ref(cli): replace argv-hoist preprocessor with a Stricli top-level-flags patch

[jared-outpost]

Global flags before the subcommand (sentry --verbose issue list) used to be relocated to the tail of argv by argv-hoist.ts, because Stricli only parses flags at the leaf command and treats a global flag in a route position as an unknown subcommand.

This teaches Stricli's route scanner about a fixed allow-list of Sentry global flags via the existing @stricli/core patch (same mechanism as the -H removal), so buildRouteScanner recognizes --verbose, --json, --org, --project, --log-level, --fields (and the -v alias, plus =-inline/value forms) at any route depth and forwards them to the leaf command instead of failing route resolution. The patch also drops Stricli's built-in -v=version alias so -v stays the CLI's --verbose alias at every position; --version remains the version flag.

argv-hoist.ts is deleted. The two transforms Stricli can't do at arbitrary route depth stay as thin app-boundary glue in argv-glue.ts: --version normalization (Stricli only prints it at argv[0]) and the --help --json rewrite to the help command (Stricli intercepts --help and ignores --json).

Scope note: the last checklist item from the issue — upstreaming the top-level-flags behavior to Stricli — is intentionally left out of this PR; the local patch stays until/unless accepted.

Testing

• pnpm exec vitest run test/lib/argv-glue.test.ts test/lib/argv-glue.integration.test.ts test/commands/help.test.ts test/commands/bash-hook.test.ts (77 passed)
• pnpm run check:patches, tsc --noEmit, biome check on changed files — all clean
• Manual smoke via run(app, preprocessArgv(argv)): issue list --help --json and --help --json emit structured JSON; cli --version and --version print the version; --verbose/--org/-v before or between route segments reach the leaf; -- passthru is not consumed as a global flag

Closes #1339

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-03 11:32 UTC

[jared-outpost]

marked ready — full CI is green (Build: lint/typecheck, unit + e2e tests, binary + npm smoke builds; plus Warden, Semgrep, CodeQL, Socket, dependency review). check:patches passes with the new required-marker guards for the scanner allow-list and the dropped -v=version alias. self-review turned up nothing outstanding.

@BYK — flagging the two deliberate calls for your read: the top-level-flag token set is hardcoded in the @stricli/core patch (minified dist can't import GLOBAL_FLAGS, so global-flags.ts documents the coupling), and the app-boundary glue in argv-glue.ts is intentionally kept for --version-at-depth and --help --json since Stricli only handles those at fixed positions. upstreaming to Stricli is left as follow-up per the issue's last checklist item.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 388f884. Configure here.}

[BYK]

Jared, you need to make this a generic patch: something we can send as a PR upstream. I see SENTRY_TOP_LEVEL_VALUE_FLAGS etc hard-coded in the patch. They should be pluggable, maybe passed in during init or config or something. Rework your patch to make it a generic patch.

[jared-outpost]

reworked the patch to be generic/upstreamable in 3b43098. the scanner no longer hardcodes SENTRY_TOP_LEVEL_*_FLAGS — it reads a scanner.topLevelFlags allow-list (booleanFlags/valueFlags sets) from config, and is inert when unset so stock Stricli behavior is unchanged. matchTopLevelFlag(input, config.topLevelFlags) replaces the hardcoded matcher, withDefaults carries the option through, and the option is documented on ScannerConfiguration in the patched .d.ts.

the Sentry-specific allow-list is now supplied at init: app.ts passes topLevelFlags: buildTopLevelFlags(), derived from GLOBAL_FLAGS, so adding a global flag stays a one-line change with no patch edits. added a test pinning the derivation contract; check:patches, tsc, biome, and the argv-glue integration suite are green.

the -v/-H alias edits in the patch are separate pre-existing Sentry concerns and were left as-is.

[BYK]

Good job Jared. What would it take for us to get rid of packages/cli/src/lib/argv-glue.ts too? You can either merge this as it is and do a follow up or try to address it in the same PR if you think it makes sense.

Btw you gotta fix that CI

[jared-outpost]

thanks!

CI: the E2E failure was infra flake, not code — library.test.ts failed with "Bundle not built" because the pnpm run bundle step errored in the runner (the job also logged a digest-mismatch on the Linux binary download, and the two warden failures are "skill execution failed", not findings). The bundle builds clean locally with the patched @stricli/core and all 16 library-mode tests pass. I re-ran the failed jobs.

dropping argv-glue.ts: I'd keep it and not fold it into this PR/patch. It's down to two transforms that are genuinely outside Stricli's model, and both are the opposite of upstreamable:

• isVersionRequest — Stricli only prints --version when it's argv[0] (handled in runApplication before the scanner runs). sentry cli --version needs --version normalized to the front. Making the scanner signal a version request back to runApplication at any depth is a much more invasive core change than the topLevelFlags option.
• rewriteHelpJsonRequest — Stricli intercepts --help and renders text usage; it has no JSON help renderer. Our --help --json reroutes to the dedicated help command that already emits structured JSON via introspection. Teaching Stricli to emit JSON help is a whole feature, and it's Sentry-specific UX.

Adding either to the patch would make it less upstreamable, which cuts against the goal of the rework. argv-glue.ts is already thin app-boundary glue and reads that way. My vote: merge as-is, leave it. If you want, I can open a follow-up issue to track upstreaming a versionRequestAtAnyDepth scanner hook + a pluggable help renderer, but those are real Stricli feature proposals rather than patch tweaks.

[BYK]

ewriteHelpJsonRequest — Stricli intercepts --help and renders text usage; it has no JSON help renderer. Our --help --json reroutes to the dedicated help command that already emits structured JSON via introspection. Teaching Stricli to emit JSON help is a whole feature, and it's Sentry-specific UX.

My request here is not to teach Stricli about --json but --help can be combined with other top-level flags (the concept you just introduced) and it should allow us to modify/intercept the help rendering. Can be done here or in a follow up but I think it is important.

--version is similar: it's a top-level flag that we define so when that happens, Stricli should treat it as such?

[jared-outpost]

got it — you're right, both of these are top-level flags in the new model, and the clean version is a scanner intercept hook, not argv string-scanning. concrete design:

--version at any depth — cheap. Stricli already tracks helpRequested in the scanner while walking the route tree; add a parallel versionRequested that trips when it sees --version (guarded by config.versionInfo) at any depth, and have runApplication print the version from scanner.finish() instead of only checking inputs[0]. That deletes isVersionRequest outright — no app-side glue.

--help + other top-level flags — the interesting one. The scanner already sets helpRequested at any depth, and with this PR --json/--fields are already recognized as top-level flags and land in unprocessedInputs. What's missing is a render hook: add config.documentation.renderHelp?(ctx) where ctx carries the resolved target path + the unprocessed top-level flags (so --json/--fields are visible). When the app returns output, Stricli uses it; otherwise it falls back to the built-in text formatHelp. Sentry's hook detects --json and renders via the existing introspectAllCommands/introspectCommand path. That deletes rewriteHelpJsonRequest and the help-command reroute, and it's genuinely upstreamable — Stricli gains a pluggable help renderer, we don't teach it about --json specifically.

Net result: argv-glue.ts and preprocessArgv go away; cli.ts calls run(app, cliArgs, …) directly. One wrinkle to handle carefully: the post-run sentry <group> help → help <group> recovery in cli.ts currently keys off the original argv; without the rewrite that logic simplifies but I need to preserve the No command registered for help fallback.

I'd land this PR as-is and do the intercept-hook as a focused follow-up rather than fold a core-dispatch redesign into an already high-risk PR — it touches the scanner + runApplication + config types + deletes a module + rewrites the argv-glue tests, so it deserves its own review surface. I'll open the follow-up issue with this design and take it. If you'd rather I do it here, say the word and I'll push it onto this branch. CI's green now (the E2E flake cleared on re-run).