feat(cli): generate command reference from Clap - #712
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2898b9e8a4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| .map(ToString::to_string) | ||
| .map(|value| normalized(&value)) | ||
| .unwrap_or_default(), | ||
| required: argument.is_required_set(), |
There was a problem hiding this comment.
Deriving required only from Arg::is_required_set() discards requirements imposed by groups and relationships. For example, evidencectl audit show requires the singleton view group, so bare show is rejected, while its generated table labels --last-operation as not required; similarly, the requires relationships among relayctl inspect options are absent. This makes the published Required column inaccurate for valid command scenarios, so the catalog should represent effective group and conditional constraints rather than only the per-argument flag.
Useful? React with 👍 / 👎.
2898b9e to
6a4ad08
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6a4ad0810a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| | Option | Always required | Default | Values | Environment | Description | | ||
| | --- | --- | --- | --- | --- | --- | | ||
| | `--config <CONFIG>` | Yes | n/a | n/a | `MINT_CONFIG` | n/a | |
There was a problem hiding this comment.
When MINT_CONFIG is set, Clap accepts mint check without --config—an invocation with the variable set reaches configuration loading rather than producing a missing-argument error—yet this row says the option is always required. The same incorrect classification is generated for EVIDENCE_OID4VCI_CONFIG and RELAY_RUNTIME; derive requiredness from the effective CLI/environment alternatives rather than only Arg::is_required_set().
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| | `--openapi <OPENAPI>` | No | n/a | n/a | n/a | OpenAPI 3.0 or 3.1 document: a local path or an HTTPS URL | | ||
| | `--transport <TRANSPORT>` | No | n/a | `sqlite-extract` | n/a | Source transport to author without an API description | | ||
| | `--profile <PROFILE>` | No | n/a | `local` | n/a | Explicit development profile for local authoring | |
There was a problem hiding this comment.
Every evidencectl new invocation is rejected by scaffold::run unless --profile local is present and exactly one of --openapi or --transport is supplied, but this new reference marks all three options as optional and emits no Constraints section. These checks remain outside the Clap metadata even after the new group/relationship extraction, so encode them in the command tree or otherwise include the runtime validation in the generated catalog.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| "check:tutorial:evidence:dry-run": "bash scripts/check-evidence-tutorials.sh --dry-run", | ||
| "check:links": "npm run build && npm run check:links:built", | ||
| "check": "npm run generate && npm run check:evidence-links && npm run check:research-banners && npm run check:docset && npm run check:release-manifests && npm run check:archive-lock && npm run check:content && npm run check:cutover && npm run check:notary-surface && npm run check:markdown && npm run check:style && npm run check:style:fixtures && npm run check:openapi && npm run check:config-vocabulary && npm run check:tutorial:dry-run && npm run check:tutorial:evidence:dry-run && npm run check:svg && npm run build && npm run check:accessibility:built && npm run check:llms:built && npm run check:seo:current && npm run check:links:current", | ||
| "check": "npm run generate && npm run check:cli-reference && npm run check:evidence-links && npm run check:research-banners && npm run check:docset && npm run check:release-manifests && npm run check:archive-lock && npm run check:content && npm run check:cutover && npm run check:notary-surface && npm run check:markdown && npm run check:style && npm run check:style:fixtures && npm run check:openapi && npm run check:config-vocabulary && npm run check:tutorial:dry-run && npm run check:tutorial:evidence:dry-run && npm run check:svg && npm run build && npm run check:accessibility:built && npm run check:llms:built && npm run check:seo:current && npm run check:links:current", |
There was a problem hiding this comment.
In the inspected .github/workflows/ci.yml docs job, the only build check is npm run check, but this script runs npm run generate before check:cli-reference; generation overwrites the committed CLI pages and JSON, so the later comparison always sees freshly generated files. A PR containing stale or hand-edited CLI output can therefore pass the docs job; run the drift check before generation or assert that generation leaves the checkout clean.
AGENTS.md reference: AGENTS.md:L289-L291
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fb31796b95
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Usage | ||
|
|
||
| ```text | ||
| evidencectl source suggest [OPTIONS] |
There was a problem hiding this comment.
For evidencectl source suggest, this usage implies that a bare invocation is valid and the page emits no Constraints section, but suggest::load_spec rejects both the no-source case and the case where --openapi and --project are supplied together (suggest/mod.rs:288-292). Encode this required mutually exclusive choice in the Clap tree or otherwise include the runtime condition, so adopters following the generated syntax do not receive an immediate error.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f8d3fa1888
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7d6015be35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| label: 'Command-line interfaces', | ||
| collapsed: true, | ||
| items: [ | ||
| { label: 'Overview', slug: 'reference/cli' }, |
There was a problem hiding this comment.
When check:archives --bootstrap rebuilds v0.18.0 or another tag predating this generator, stagePinnedGeneratedArtifacts removes reference/cli/** because the pinned tree has no such files, but buildDocsetArchive still evaluates this current, unconditional sidebar. Archived pages therefore gain links to absent routes, changing the locked archive bytes and causing link or digest verification to fail; make this sidebar docset-aware or stage its definition from the same source ref.
AGENTS.md reference: AGENTS.md:L289-L291
Useful? React with 👍 / 👎.
| ## Usage | ||
|
|
||
| ```text | ||
| evidencectl dev [OPTIONS] [COMMAND] |
There was a problem hiding this comment.
When starting the local pair without a subcommand, crates/registry-evidencectl/src/dev.rs:310-312 rejects the bare form unless --detach is present, while lines 298-306 reject --detach with stop or clean. This usage and its options table advertise [COMMAND] and --detach as independently optional, so users following the generated syntax can hit an immediate runtime error; represent this conditional requirement and conflict in Clap or another catalog constraint.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| | `--client-id <CLIENT_ID>` | Yes | n/a | n/a | n/a | The `clientId` this caller is registered under | | ||
| | `--key <KEY>` | Yes | n/a | n/a | n/a | The caller's private JWK. Must be owner-only and not a symlink | | ||
| | `--audience <AUDIENCE>` | No | n/a | n/a | n/a | The endpoint's configured `clientAssertion.audience`. Defaults to `--url`, which is the usual configuration | | ||
| | `--actor <ACTOR>` | No | n/a | n/a | n/a | Request a delegated token for this actor. Requires `--subject-file` | |
There was a problem hiding this comment.
When either delegation option is supplied alone, sign_client_assertion rejects it in crates/registry-mint/src/caller.rs:105-125, but this page has no Constraints section and only the --actor prose mentions one direction, leaving --subject-file alone advertised as valid syntax. Both options use plain #[arg(long)] definitions, so encode their mutual requirement in Clap or another catalog constraint.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
7d6015b to
71f531f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 71f531feec
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Usage | ||
|
|
||
| ```text | ||
| evidencectl request prepare [OPTIONS] --purpose <PURPOSE> --subject <SUBJECT> --name <NAME> <QUESTION> |
There was a problem hiding this comment.
For requests whose subject selectors are supplied in an owner-only file, this syntax is inaccurate: load_subject_inputs requires exactly one of --subject or --subjects-file (request.rs:368-375), while this page requires --subject and omits --subjects-file from the options table entirely. Readers therefore cannot discover the supported path that keeps identifying selector values out of process arguments; encode the pair as a required exclusive Clap group so regeneration publishes both forms.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
1 participant
Pull Request
Summary
Add reusable Clap command-tree introspection for every released Evidence and Relay CLI:
relay,relayctl,evidence,evidencectl,mint, andevidence-oid4vci.A new docs-only
registry-cli-docscollector serializes those command trees to a deterministic, validated JSON contract. The docs generator uses that contract to produce the command-line reference overview and 66 command pages, with exact usage, arguments, options, defaults, values, environment variables, and nested-command links.The docs drift gate and CI change routing now keep the generated reference aligned with CLI changes. Hidden implementation seams and Clap's built-in help subcommands are excluded.
Checks
cargo fmt --all -- --checkcargo check --locked --workspace --all-targets-D warningsregistry-cli-docs, Relay V2, Relayctl, Evidence, Evidencectl, Mint, and Evidence OID4VCIcargo deny checkpython3 .github/scripts/test_ci_changes.pyproducts/identifiers/scripts/check.shproducts/relay-v2/scripts/check-contracts.shproducts/evidence/scripts/check-contracts.shproducts/evidence/scripts/check-source-neutrality.shnpm testandnpm run checkindocs/sitenode docs/site/scripts/generate-cli-reference.mjs --checkgit diff --checkFocused coverage verifies the exact released-binary set, complete usage/about metadata, hidden-command exclusion, deterministic regeneration, generated-file drift, MDX-safe provenance, and CLI/CI routing contracts.
Notes
This changes adopter tooling and generated documentation only. It does not change Relay or Evidence HTTP contracts, authorization, evaluation, signing, or release artifacts.
Existing non-blocking warnings remain in Redocly, Astro, Rhai syntax highlighting, Vale, and cargo-deny. No new warning or functional risk was found.
DCO
Signed-off-bytrailer.