Follow-up from #1337 (discussion with @BYK).
Background
#1337 makes --help --json emit structured output by rewriting the argv into a help command invocation inside preprocessArgv (src/lib/argv-hoist.ts). That landed as the interim fix, but the whole argv-hoist.ts preprocessor exists only because Stricli parses flags at the leaf level and treats global flags placed before the subcommand as unknown route segments. We work around that today by hoisting --verbose, --log-level, --json, --fields, --org, --project to the tail, normalizing --version, and rewriting --help --json.
Proposal
Teach Stricli about a configurable set of top-level flags (via our @stricli/core patch, same mechanism as the existing -H removal) so those flags are recognized at any route depth and handed to the leaf command. This removes the need for argv-hoist.ts entirely — no hoisting, no --version normalization, no --help --json rewrite.
buildRouteScanner is the natural hook: it already special-cases --help/--helpAll/--version while walking the route tree, so it can collect an allow-list of global flags instead of failing route resolution on them.
Design note (from @BYK)
"Terminal" flags like --help should not short-circuit. They should still parse the other flags on the line and pass them to their handler, which may ignore them or act on them. That is what lets --help --json produce JSON: --help stays terminal for routing, but --json reaches the handler and switches output to our introspectCommand/introspectAllCommands structured form. So the scanner change needs a small amount of app-level glue to route "help + json" to structured output rather than text usage.
Tasks
Notes
- The patch targets minified
dist/index.{cjs,js}; check-patches.ts already flags that every Stricli bump requires re-deriving it, so keep the edit minimal.
- Closing criterion:
argv-hoist.ts is gone and all existing argv-hoist / help-json / version behaviors are covered by the patched scanner plus app glue, with equivalent test coverage.
Follow-up from #1337 (discussion with @BYK).
Background
#1337 makes
--help --jsonemit structured output by rewriting the argv into ahelpcommand invocation insidepreprocessArgv(src/lib/argv-hoist.ts). That landed as the interim fix, but the wholeargv-hoist.tspreprocessor exists only because Stricli parses flags at the leaf level and treats global flags placed before the subcommand as unknown route segments. We work around that today by hoisting--verbose,--log-level,--json,--fields,--org,--projectto the tail, normalizing--version, and rewriting--help --json.Proposal
Teach Stricli about a configurable set of top-level flags (via our
@stricli/corepatch, same mechanism as the existing-Hremoval) so those flags are recognized at any route depth and handed to the leaf command. This removes the need forargv-hoist.tsentirely — no hoisting, no--versionnormalization, no--help --jsonrewrite.buildRouteScanneris the natural hook: it already special-cases--help/--helpAll/--versionwhile walking the route tree, so it can collect an allow-list of global flags instead of failing route resolution on them.Design note (from @BYK)
"Terminal" flags like
--helpshould not short-circuit. They should still parse the other flags on the line and pass them to their handler, which may ignore them or act on them. That is what lets--help --jsonproduce JSON:--helpstays terminal for routing, but--jsonreaches the handler and switches output to ourintrospectCommand/introspectAllCommandsstructured form. So the scanner change needs a small amount of app-level glue to route "help + json" to structured output rather than text usage.Tasks
@stricli/corepatch with a top-level-flags allow-list inbuildRouteScanner.--help) still parse sibling flags and forward them to the handler.--help --jsonrenders structured help via existing introspection.src/lib/argv-hoist.tsand itspreprocessArgvusage once the patch covers all cases; migrate/prune the associated tests.-Hchange) as PRs upstream to Stricli; keep the local patch until/unless accepted.Notes
dist/index.{cjs,js};check-patches.tsalready flags that every Stricli bump requires re-deriving it, so keep the edit minimal.argv-hoist.tsis gone and all existing argv-hoist / help-json / version behaviors are covered by the patched scanner plus app glue, with equivalent test coverage.