Skip to content

chore(cli): carry sidebar category and title as a command annotation (CLI-2686) - #7723

Open
mdonnalley wants to merge 5 commits into
developfrom
mdonnalley/2686
Open

mdonnalley wants to merge 5 commits into
developfrom
mdonnalley/2686

Conversation

@mdonnalley

Copy link
Copy Markdown
Contributor

Generate the docs-site CLI sidebar from command annotations. A top-level command declares its sidebar category with withSidebar({ category }), and its subcommands inherit that category. A sidebar title defaults to the command's short description, and withSidebar({ title }) overrides it. Overrides are added only where the current sidebar already uses a different title or where the short description is longer than 50 characters, so no short descriptions change.

pnpm docs:sidebar (from apps/cli) writes the content for common-cli-sections.json. Categories are a compile-time union of DOCS_SIDEBAR_CATEGORIES, which also sets their order. The build fails when a top-level command has no category, a subcommand declares one, a title is longer than 50 characters, or a category has no commands.

The spec no longer carries section tags: DOCS_TAGS is removed and every tags array is empty.

Differences from the current sidebar:

  • Seven commands are added: inspect db collation-drift, inspect db toast-sizes, inspect db xid-age, logs, logs sources, config convert and config validate.
  • Every command is listed flat under its category, including inspect db.
  • The inspect db role-stats slug becomes supabase-inspect-db-role-stats.
  • The ssl-enforcement get title drops a trailing "s" to fit the 50-character limit.

Linear: CLI-2686

@mdonnalley
mdonnalley requested review from a team and supabase-oss as code owners November 19, 2026 18:24
@mdonnalley
mdonnalley requested a review from Coly010 November 19, 2026 18:24
@github-actions

Copy link
Copy Markdown
Contributor

CLI benchmark (Lightweight Commands): no changes found

Commit 817a8f2 against develop at 5de7bf1 · 10 runs each · report only, never blocks merging

Command Workload Before After Change
supabase --version version 253 ms 270 ms no real change (+7%, within normal variation)
supabase --help help 278 ms 280 ms no real change
supabase init init 267 ms 268 ms no real change
supabase migration new bench migration-new 274 ms 256 ms no real change (-7%, within normal variation)
supabase config convert config-convert 207 ms 212 ms no real change
supabase config validate config-validate 234 ms 224 ms no real change
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 266 ms 251 ms no real change (-6%, within normal variation)
supabase projects list projects-list 197 ms 219 ms no real change (+11%, within normal variation)
supabase functions list --project-ref replayfixtureprojref functions-list 182 ms 186 ms no real change

API calls: unchanged for all 9 commands.

Binary size: 135.3 MB, up 24.0 KB from 135.3 MB.

Details: timing ranges, API calls per command, slowest phases

Timing ranges

Command Workload Before range After range Change Verdict
supabase --version version 225-341 ms 207-364 ms +17 ms (+7%) within noise
supabase --help help 230-325 ms 250-351 ms +1 ms (+0%) within noise
supabase init init 247-330 ms 236-300 ms +2 ms (+1%) within noise
supabase migration new bench migration-new 186-316 ms 204-317 ms -19 ms (-7%) within noise
supabase config convert config-convert 177-312 ms 177-316 ms +6 ms (+3%) within noise
supabase config validate config-validate 188-315 ms 180-336 ms -10 ms (-4%) within noise
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 221-339 ms 216-322 ms -15 ms (-6%) within noise
supabase projects list projects-list 176-274 ms 176-239 ms +22 ms (+11%) within noise
supabase functions list --project-ref replayfixtureprojref functions-list 177-259 ms 175-202 ms +4 ms (+2%) within noise

API calls per command

Command Workload Before After Endpoint changes
supabase --version version 0 0
supabase --help help 0 0
supabase init init 0 0
supabase migration new bench migration-new 0 0
supabase config convert config-convert 0 0
supabase config validate config-validate 0 0
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 2 2
supabase projects list projects-list 1 1
supabase functions list --project-ref replayfixtureprojref functions-list 2 2

Slowest phases

No command moved beyond noise, so there are no phase deltas.

Workflow run

Comment /bench to run the lightweight benchmark (this comment) again on the latest commit, or /bench full to also run the integration-heavy benchmark, which posts in its own comment.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI Review

CLI reference prose guidance: snapshot supabase/supabase@10488ed supplied to reviewers (advisory, not a style pass).

The release still publishes only the YAML spec, which now has empty section tags. The sidebar generator can silently omit commands assigned to an unknown category or emit links with blank labels. Several new labels misstate command behavior. The two terminology findings concern sidebar titles, which fall outside the trusted CLI reference prose procedure. The review was static. The website consumer and the pinned pnpm version were unavailable for verification.

Findings

Severity Location Category Sources Claim
🟡 MINOR apps/cli/src/docs/docs-spec.ts:435 compatibility codex The published clispec 001 loses the section definitions and per-command section memberships that it previously supplied.
🟡 MINOR apps/cli/src/docs/docs-spec.ts:416 build-validation codex The spec generator and publisher can accept a new top-level command with no sidebar category.
🟡 MINOR apps/cli/src/command-internal/command-sidebar.ts:43 input-validation codex An invalid category can pass type checking and silently omit a top-level command and its descendants from the generated sidebar.
🟡 MINOR apps/cli/src/docs/docs-sidebar.ts:66 accessibility codex The generator can emit a command link with an empty or whitespace-only label.
🟡 MINOR apps/cli/docs/README.md:67 developer-workflow codex Copying or redirecting the complete output of the documented pnpm docs:sidebar invocation may produce invalid sidebar JSON if pnpm includes a lifecycle banner on stdout.
🟡 MINOR apps/cli/src/commands/db/db.command.ts:18 docs-accuracy codex The sidebar labels for db, db diff, and db pull imply target restrictions absent from the commands.
🟡 MINOR apps/cli/src/commands/db/dump/dump.command.ts:101 docs-accuracy codex The new db dump sidebar label describes only a remote schema dump even though the command also supports local targets, data dumps, and role dumps.
🟡 MINOR apps/cli/src/commands/start/start.command.ts:94 docs-accuracy codex The start sidebar label suggests a single container, and the stop label suggests all containers on the machine.
🟡 MINOR apps/cli/src/commands/storage/ls/ls.command.ts:33 docs-accuracy codex The storage ls sidebar label promises a complete listing, but the command can scope the results by path and recurses only when requested.
🟡 MINOR apps/cli/src/commands/postgres-config/delete/delete.command.ts:46 docs-accuracy codex The postgres-config delete sidebar label can be read as deleting entire Postgres configurations.
⚪ NIT apps/cli/scripts/publish-docs-spec.ts:134 docs-tooling claude The release still depends on a manual sidebar update. Commands such as logs or config validate can remain missing from the website reference if their IDs are absent from the website sidebar and nobody copies the generated file.
⚪ NIT apps/cli/src/docs/docs-spec.unit.test.ts:273 test-clarity codex The whoami test still names the Management API reference after losing its section placement assertion.
⚪ NIT apps/cli/scripts/generate-docs-sidebar.ts:9 repo-conventions codex The new script writes to stdout outside Effect.
Refuted findings (kept for transparency, not posted as review comments)
  • apps/cli/src/commands/login/login.command.ts:37 (docs-style): The new login sidebar title uses “Log in” where the upstream word list prescribes “Sign in” for prose.
    Refuted: The quotation and upstream rule match. The trusted procedure limits this style check to overlays and command, flag, and example descriptions. The changed string is consumed as a navigation title at apps/cli/src/docs/docs-sidebar.ts:66–77. The command descriptions at apps/cli/src/commands/login/login.command.ts:38–39 are unchanged.
  • apps/cli/src/commands/domains/delete/delete.command.ts:36 (docs-style): The new custom hostname sidebar titles use “config” where the upstream word list prefers “configuration” in general prose.
    Refuted: The pinned heading and all three quotations match. Each change is a withSidebar title consumed by the sidebar generator. The neighboring command descriptions and examples are unchanged, so the changed strings fall outside the trusted prose procedure.

Stats

Claude findings: 1 · Codex findings: 14 · Confirmed: 12 · Refuted: 2 · Uncertain: 1


Models: claude-opus-5-5 + gpt-6.2-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

Comment thread apps/cli/scripts/publish-docs-spec.ts Resolved
Comment thread apps/cli/src/docs/docs-spec.ts Resolved
Comment thread apps/cli/src/docs/docs-spec.ts Resolved
Comment thread apps/cli/src/docs/docs-sidebar.ts Resolved

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant