Skip to content

ref(cli): Load top-level routes from a checked-in command manifest - #1918

Merged
BYK merged 3 commits into
mainfrom
byk/cli-command-manifest
Nov 3, 2026
Merged

BYK merged 3 commits into
mainfrom
byk/cli-command-manifest

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Part of #1914 (part 1: the manifest).

src/command-manifest.ts lists every top-level route of the CLI, in help order. Each entry has an import() loader for the module that implements it, whether help hides it, and what the top-level help shows for it: the brief, a group's visible subcommands, or a top-level command's usage line and placeholder. Loading the manifest loads no command.

  • app-for-args.ts and sdk-app.ts load single routes through the manifest. generate:routes, script/generate-route-loaders.ts and the generated route-loaders.ts are gone, and app-root.ts reads hidden routes from the manifest instead of its own HIDDEN_ROUTES list.
  • sentry, sentry help and sentry --help now load only the help command. Every other visible route becomes a help-only stand-in built from the manifest (root-help-routes.ts), so Stricli renders --help itself and the branded help reads the same tree. No root-help.json and no Stricli patch change. JSON help, help <command>, and --help before a route name still load the full application.
  • test/lib/command-manifest.test.ts fails when the manifest and app.ts disagree (names, order, loaders, hidden flags, briefs, subcommands, usage lines), and its diff shows the entry to copy. It also checks that the stand-in tree prints the same --help (plain and colored) and branded help as the full tree.

app.ts still imports every command statically, because tests and the build generators import app/routes synchronously and the npm bundle is CJS (no top-level await). Adding a top-level route means adding it to both files; the test catches mismatches.

Builds on #1826 (--version and leading global flags), whose token scanner root-help detection reuses.

Startup with the npm bundle (median of 15 runs, noisy sandbox):

command main this PR
sentry 389 ms 323 ms
sentry help 393 ms 329 ms
sentry --help 384 ms 336 ms
sentry issue list --help 340 ms 342 ms (unchanged, as expected)

I compared the npm bundle's output and exit codes against main for 21 argument cases × piped/TTY × 5 environments (agent mode on/off, NO_COLOR, SENTRY_OUTPUT_FORMAT=json, with an auth token): all 210 matched.

Open question: the manifest repeats each top-level brief and the usage lines of the 8 visible top-level commands (help, explore, mcp, init, info, api, schema, wasm-split). The test keeps them in sync, but adding a flag to one of those commands now means updating the manifest too. The alternative is for commands to read their brief from the manifest. That's a wider change, so I left it out.

--

View Session in Sentry

sentry-junior Bot and others added 2 commits November 3, 2026 21:41
routesForArgs fell back to the full application whenever the first token
was a flag, so `sentry --version` and `sentry --verbose issue list`
loaded every command. Read the leading tokens like the route scanner
does: skip global flags (and their values), and for a bare `--version`
load only the help route, since Stricli prints the version before it
runs any command. Other leading flags, like `--help`, still get the
full application.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
`src/command-manifest.ts` lists every top-level route of the CLI with an
`import()` loader for the module that implements it, whether help hides
it, and what the top-level help shows for it: the brief, a group's
visible subcommands, or a command's usage line and placeholder.

`app-for-args.ts` and `sdk-app.ts` load single routes through it, so
`generate:routes` and the generated `route-loaders.ts` go away, and
`app-root.ts` reads hidden routes from it instead of its own list.

`sentry`, `sentry help`, and `sentry --help` now load only the `help`
command. The other visible routes become help-only stand-ins built from
the manifest (`root-help-routes.ts`), so Stricli renders `--help` itself
and the branded help reads the same tree. JSON help, `help <command>`,
and `--help` before a route name still load the full application.

`test/lib/command-manifest.test.ts` fails when the manifest and the
routes in `app.ts` disagree (names, order, loaders, hidden flags,
briefs, subcommands, usage lines), and checks that both trees print the
same top-level help.

Part of #1914.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sentry-local Ready Ready Preview Nov 3, 2026 10:30pm UTC

Request Review

# Conflicts:
#	packages/cli/AGENTS.md
#	packages/cli/src/app-for-args.ts
#	packages/cli/test/lib/app-for-args.test.ts
@BYK
BYK marked this pull request as ready for review November 3, 2026 22:39
@BYK
BYK enabled auto-merge (squash) November 3, 2026 22:39
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 3, 2026
@BYK
BYK merged commit 77edf6b into main Nov 3, 2026
38 checks passed
@BYK
BYK deleted the byk/cli-command-manifest branch November 3, 2026 22:42
BYK added a commit that referenced this pull request Nov 3, 2026
)

Part of #1914. Follow-up to #1918, whose open question was that the
command manifest repeated each top-level brief, the subcommand lists,
and the usage lines of the 8 visible top-level commands.

- **Briefs:** the manifest is now the only copy. Top-level route maps
and commands set `brief: topLevelBrief("<name>")`, which throws for an
unknown or hidden name, so a typo fails every run and test that loads
the route.
- **Subcommands, usage lines, placeholders:** these come from flags,
positionals and route maps, so nobody writes them down anymore.
`generate:top-level-routes` (part of `generate:docs`, listed in
`ensure-generated.mjs`) loads the route tree and writes them to the
gitignored `src/generated/top-level-routes.json`, and
`root-help-routes.ts` builds its stand-ins from that file plus the
manifest. Root help still loads only `help`, with no precomputed help
text and no Stricli patch change.
- **Manifest boilerplate:** entries use `route(brief, () => import(...),
"export")` and `hidden(() => import(...), "export")`. The export name is
type-checked against the module. `import()` specifiers stay literal, so
the split bundle still gets one chunk per command.
- **Test:** `command-manifest.test.ts` keeps the order and loader
checks, checks that every visible route's brief comes from the manifest,
and checks that `top-level-routes.json` matches the route tree. The old
field-by-field comparison would now be checking the manifest against
itself, so it's gone. The plain and colored root `--help` and
branded-help equality tests stay.

Output of `sentry`, `help`, `--help`, `-h`, `--helpAll`, `help <cmd>`,
`<cmd> --help`, `help --json` and `--version` matches `main`, both from
source (agent, piped and TTY modes) and from the npm bundle (piped and
TTY). Generated docs, the skill and the other generated JSON files are
byte-identical. Startup with the npm bundle is within noise of `main`
(`sentry` ~321–340 ms vs ~321–326 ms, `--help` ~325 ms vs ~318–329 ms).

The new generator overlaps a little with the #1914 parts 2–3 work, which
also generates per-command data from the loaded tree. If that lands a
shared tree-loading generator, this one can fold into it.

<!-- junior-request-attribution:start -->
via @BYK.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3Afe7bc68084c13561534d518256e879c0 -->

--

[View Session in
Sentry](https://sentry.sentry.io/explore/conversations/agent%3Afe7bc68084c13561534d518256e879c0/?project=4510944073809921)

<!-- junior-session-footer:end -->

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
BYK added a commit that referenced this pull request Nov 4, 2026
Closes #1914. This does parts 2 and 3; part 1, the manifest, landed in
#1918.

Command output schemas now live in build-only modules. At runtime the
CLI reads precomputed field data and never builds or walks a valibot
output schema.

**Part 3: generated field data**
- New `script/generate-output-schemas.ts`, which runs in `generate:docs`
and is listed in `ensure-generated.mjs`.
  - It imports each `src/output-schemas/<area>.ts` through tsx.
- It reads every exported `…Schema` with the extraction that used to run
at startup, now in `script/lib/output-schema-fields.ts`.
- It writes `{ fields, paths }` to the gitignored
`src/generated/output-schemas/<area>.ts`, keeping the same export name.
- **Lookup key:** there is none. A command imports its own entry by
name, for example `import { IssueViewOutputSchema } from
"../../generated/output-schemas/issue.js"`.
- The route module, which the manifest already loads lazily, pulls in
only its own area's data.
- There are no path keys and no bootstrap ordering, and esbuild drops
unused exports.
- The data is typed `OutputSchemaFields<typeof Schema>`, with the schema
kept as a phantom type. `SchemaMatches` still fails the build when a
command's data doesn't match its schema; a deliberately mismatched probe
confirmed this.
- `buildFieldsFlag` (`--fields` parsing and completion),
`enrichDocsWithSchema` (`--help`) and `buildCommand` read
`schema.fields` / `schema.paths`.
- Commands carry `__jsonFields` instead of `__jsonSchema`;
`introspect.ts` and `generate-sdk.ts` read it.

**Part 2: build-only schemas**
- The CLI-only output schemas move into `src/output-schemas/`: one
module per area, plus the `output.ts` and `org-list.ts` building blocks.
They come from `types/*.ts`, `commands/alert/output-schemas.ts` and
inline command definitions.
  - Commands and formatters import only types from there.
- Four schemas also validate API responses at runtime, so they stay put
and their area module re-exports them:
  - `SentryLogSchema`, part of `LogsResponseSchema`
  - `TransactionListItemSchema`, part of `TransactionsResponseSchema`
  - `ConversationListItemSchema`
  - `DashboardRevisionSchema`
- `span list` documents `FlatSpanSchema`, which is CLI-only;
`SpanListItemSchema` remains the runtime schema.
- Org-scoped lists pass the item schema, `orgListItemSchema(Entity)`,
built in `src/output-schemas/`.
- New oxlint rule `sentry-cli/no-runtime-output-schema-imports`. It
rejects value imports, re-exports and `import()` of
`src/output-schemas/` from `src/`.
- It also rejects `import { type X }`, because `verbatimModuleSyntax`
keeps that as a runtime import.
- `packages/cli/AGENTS.md` "Declaring Command Output" is updated.

**Verification against main**
- A metadata dump of all 141 commands is identical: help text with field
tables, `jsonFields`, the `--fields` brief, and the parser choices.
- `help --json`, `help issue view --json`, the sampled `--help` output
and `__complete --fields` are byte-identical.
- These are unchanged: the generated `src/generated/*`, the docs pages,
`.well-known/skills/index.json` and the tracked SKILL.md files.
- `sdk.generated.{ts,d.cts}` differ only in one comment, which now says
`__jsonFields` instead of `__jsonSchema`.
- tsc, oxlint, oxfmt, ast-grep and the deps check pass.
- Unit tests: 11 failures in 8 files. The same tests fail on main in the
agent sandbox (root-permission EACCES/EPERM, disk I/O, and the `npx`
login hint).
- Startup, median of 41 interleaved runs:
  - `sentry issue list --help`: 328 → 322 ms
  - `sentry issue view ABC-1 --json --fields id`: 334 → 322 ms
- The npm bundle's `.cjs` grew from 8,128,006 to 8,159,198 bytes (+31
KB, +0.4%), because the expanded field and path lists are bigger than
the compact schema code they replace.

**Verification after merging `main` (38dd63c)**
- `generate:output-schemas` runs before `generate:command-api` and
`generate:top-level-routes`, since both load the command tree.
- With the untracked files in `src/generated/` removed, `generate:docs`
succeeds: 19 area modules, 60 exports, and a populated
`top-level-routes.json`. Tracked generated files are unchanged.
- tsc, oxlint and oxfmt pass. 40 related test files run: 39 pass, and
the only failures are the two root-permission cases in
`completions.test.ts`, which also fail on main in the agent sandbox.
- `@sentry/mcp-server`: `bundle` passes the CLI-only module guard
(3,445.7 KB, under the 3.75 MB cap), and `test:bundle` passes 15/15.

**Decision:** keep emitting every `…Schema`. Emitting only the imported
ones would save about 0.5 ms of build time and about 19 KB of gitignored
source, but it would need an import scanner and add a new way for the
data to go stale.

<!-- junior-request-attribution:start -->
via @BYK.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3Aa6317603e9bd96f1e8e67236e16ff7a7 -->

--

[View Session in
Sentry](https://sentry.sentry.io/explore/conversations/agent%3Aa6317603e9bd96f1e8e67236e16ff7a7/?project=4510944073809921)

<!-- junior-session-footer:end -->

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
sentry-junior Bot added a commit that referenced this pull request Nov 4, 2026
Resolve conflicts with main's command manifest (#1918), build-only output
schemas (#1923) and toolkit-core Markdown builders (#1805):

- Register token/tokens in app.ts, command-manifest.ts, app-root.ts
  plurals and top-level-briefs.ts
- Re-export OrgAuthTokenSchema from output-schemas/token.ts (it also
  validates API responses) and read token list's fields from generated data
- Use text/inlineCode/tableCell from @sentry/toolkit-core/markdown
- Move the argument-error credential redaction to lib/application.ts

This branch was successfully deployed

1 active deployment
Preview — d2ecf6cc Deployed Nov 3, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant