docs(cli): add a CLI docs section generated from the command tree - #6762
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR SummaryLow Risk Overview Navigation and layout: CLI pages keep prev/next links inside Content: A full CLI tree under CLI behavior (outside the MDX-only hunks): Bulk knowledge document updates are exposed as Reviewed by Cursor Bugbot for commit a5ac9e9. Configure here. |
Greptile SummaryThe PR adds generated CLI documentation, surfaces route-contract descriptions in CLI help, and resolves a duplicate command path.
Confidence Score: 5/5The PR appears safe to merge because the previously reported navigation failure is fixed and no blocking failure remains. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| apps/docs/components/navbar/navbar.tsx | Uses whole path-segment matching for navigation sections, resolving the previously reported false CLI match on ClickUp and ClickHouse integration routes. |
| scripts/generate-cli-docs.ts | Generates CLI reference pages and validates command-path uniqueness, documentation coverage, and generated-page freshness. |
| packages/sim-cli/src/runtime/options.ts | Propagates contract descriptions into Commander option help while preserving generated flag behavior. |
| packages/sim-cli/src/contract/commands.ts | Adjusts CLI command metadata, including the non-colliding batch-update path for bulk knowledge-document updates. |
| apps/docs/app/[lang]/[[...slug]]/page.tsx | Treats CLI pages as a self-contained section when calculating previous and next navigation links. |
Reviews (2): Last reviewed commit: "fix(docs): match the CLI tab by path seg..." | Re-trigger Greptile
The `sim` CLI shipped with no coverage in the docs site. Adds a fourth top-level tab for it, and moves Academy last. The command reference is generated. `sim` exposes 147 leaf commands across 33 groups, most of them derived at runtime from the v2 route contracts, so a hand-written reference would be wrong the week after it was written. The generator walks the command tree `buildProgram()` hands to commander — the same tree the terminal parses — rather than re-deriving it from the contract, which would be a second implementation free to describe commands nobody can invoke. `check:cli-docs` is a zero-arg `check:*` script, so the existing audit runner picks it up and stale pages fail CI. Generating against the real tree surfaced a collision it had been hiding: `bulkUpdateKnowledgeDocuments` and `updateKnowledgeDocument` both derived to `sim knowledge documents update`. Commander resolves a duplicate to the first match, so the bulk form shadowed the single-document one and its flags were unreachable while still appearing in `--help`. The bulk form is now `batch-update`, matching how `tables rows batch-delete`/`batch-update` already handle the same REST overload, and the generator fails on any duplicate path so the next one cannot land silently. Five hand-written guides cover install, auth, configuration, output formats, and scripting. Also corrects two commands in the package README that do not exist as documented (`tables columns <tableId>`, and `--sort score:desc`, which is JSON).
…g and a single-page reference The command reference was structurally complete but said almost nothing: 223 of 377 flags rendered as "Set sort by" because the CLI only ever read flag help from its own contract overrides, and fell back to restating the flag name. The prose already existed. The v2 route contracts carry 931 `.describe()` calls and the OpenAPI specs publish all of them — 327 parameters and 282 body properties, 100% coverage — but the generated operation table dropped every one, carrying only a per-operation summary. It now carries the field descriptions, the path-parameter descriptions, and positional help, so `--help` and the docs explain a flag the same way the API reference does. Placeholder descriptions are now zero, and 147/147 commands, 377/377 flags and 130/130 arguments are documented. `check:cli-docs` fails on a request field with no `.describe()` rather than letting it render as documentation that says nothing. Also in this pass: - Commands are root-level sidebar entries under a Commands heading rather than a folder, and headings are the command's description, so the table of contents distinguishes entries at the first word instead of repeating "sim knowledge documents …" fourteen times. A guard fails the build if two descriptions on a page collide, since they would share an anchor. - A single-page `Complete reference` carrying all 147 commands, for in-page search and for agents fetching `/cli/reference.mdx`. It keys on exact command paths because descriptions are only unique within a group. - A troubleshooting page, with every message copied from the source. - Table columns are sized by a local component; the flag column was starved while descriptions kept most of the row empty. - The prerelease install channels are dropped from the docs and the package README, which is what npm renders.
…before pipes
`pathname.includes('/cli')` also matches `/integrations/clickup` and
`/integrations/clickhouse`, so both existing integration pages lit the CLI tab
and unlit Documentation. Matching is now per path segment. Anchoring to the
start would not work either — a non-default locale prefixes the path, as in
`/ja/cli` — so the segment is matched wherever it sits.
Table cells now double a backslash before escaping pipes. A value ending in one
turned `a\` + `|` into `a\\|`, which the table parser reads as an escaped
backslash followed by an unescaped pipe, splitting the cell early. Nothing in
the command surface contains a backslash today, so this was latent rather than
visible.
The reference page's global options table is two-column and was being wrapped in
`CommandTable`, which sizes the second column for the `Required` cell of the
three-column tables and crushed the description into 5.5rem. It now matches the
overview page, which leaves that table unsized.
12e44cb to
a5ac9e9
Compare
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a5ac9e9. Configure here.
Summary
simCLI shipped with no coverage in the docs site.check:cli-docsis a zero-argcheck:*script, so the existing audit runner picks it up and stale pages fail CI..describe()prose into the CLI. 223 of 377 flags previously rendered asSet sort by: the contracts carry 931.describe()calls and the OpenAPI specs publish all of them, but the generated operation table dropped every one. Now--helpand the docs explain a flag the same way the API reference does. Placeholder descriptions are zero; 147/147 commands, 377/377 flags and 130/130 arguments are documented.bulkUpdateKnowledgeDocumentsandupdateKnowledgeDocumentboth derived tosim knowledge documents update. Commander resolves duplicates to the first match, so the bulk form shadowed the single-document one and its flags were unreachable while still appearing in--help. The bulk form is nowbatch-update, matching howtables rows batch-delete/batch-updatealready handle the same REST overload.Complete referencecarrying every command, for in-page search and for agents fetching/cli/reference.mdx.tables columns <tableId>, and--sort score:desc, which is JSON), and drops the prerelease install channels from the docs and README.Three guards keep this honest in CI: stale pages fail, duplicate command paths fail, and a request field with no
.describe()fails rather than rendering as documentation that says nothing. Each was verified to actually fail.Important
npm's
latestforsimstill points at the previous owner's unrelated1.0.18package. The publish workflow only moveslateston a push tomain, sonpm install --global sim— the first command on the landing page — installs the wrong package until the CLI lands there. Worth sequencing the merges.Type of Change
knowledge documents update)Testing
bun run check:audits(28/28), 242 CLI tests, type-checks clean onpackages/sim-cliandapps/docs, full docs site builds and all CLI routes renderNot verified against a live API: response shapes come from the route contracts, and no command was run against a real deployment.
Checklist