Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

Relationships

#4646 Lazy loading: root --help renders from route metadata instead of loading every command

Opened by zack · 11/11/2026· Shipped 11/11/2026

Part of the lazy command loading plan. It builds on the route table (#4592) and uses the benchmark and parity scripts from #4590.

Why

Root --help prints one line per top-level command: its name, aliases, argument syntax and the first line of its description. To print that, it loads the whole command tree. selectRoute finds no command word, so it returns all, and every routed group then loads all of its subcommands.

Measured on the bundled build (#4624, Linux x86_64), with paired runs that alternate the binaries run by run. Median of 21 warm runs:

binary --help version (control)
main 574 ms 153 ms
L8 routing prototype (#4647, four more groups routed) 788 ms 159 ms
prototype: root help from stub commands 158 ms 160 ms

A prototype registered stub commands built from a metadata table for a bare --help / -h, and imported no command module. Its --help and -h output was byte-identical to main's, and --help cost the same as version. Each group routed per subcommand makes full-tree help slower, so this also keeps L8 (#4647) from slowing root help down; #4647 should land after this.

Scope

  • Add the root-help metadata to each ROOT_ROUTES row: description and the argument syntax (only init [path] has one today). name, aliases and hidden are already there. One table, not a second list to keep in sync.
  • When argv asks for root help and nothing else, loadCommands in src/cli/mod.ts registers stub commands built from those rows (new Command().description(…), plus aliases, arguments and hidden()) instead of calling loadRoutes(ROOT_ROUTES). "Root help and nothing else" means --help or -h, optionally with root global options from ROOT_GLOBAL_OPTIONS, and no command word. An option the router doesn't know still loads the full tree, as today.
  • Check whether bare swamp (no arguments) renders the same help through the root action. If it does, route it the same way.
  • Add a fitness rule to the route rules test: each row's description, argument syntax, aliases and hidden equal the loaded command's. This is what stops the table drifting from the real commands.

Not in scope

  • Group help (vault --help, help vault). The same stub approach would work one level down with each group's subcommand metadata, at the cost of more metadata to keep in sync. In the L8 prototype (#4647), routing made group help slower: extension --help +45 ms, vault --help +37 ms. Decide after L8.
  • completions <shell> and bare swamp help (the JSON tree). These really do need the whole tree; they cost +195 to +243 ms in the L8 prototype. Making them fast probably means a schema snapshot generated at compile time, which is a separate design.

Findings to carry forward

  • Parallel import() is not the fix for the full-tree cost.
    • At the root, starting every route's import at once crashed every full-tree command. The behavior and model command modules form an import cycle that only resolves in table order: model method history get read its syntax constant before that module had finished evaluating. The "sequential, so command modules evaluate in table order" comment on loadRoutes is load-bearing.
    • Within a group, starting the subcommand imports together gained nothing measurable (−1 to +23 ms). So the full-tree regression from routing does not come from awaiting imports one at a time. It is more likely per-chunk overhead in the bundle, but that is not verified.
  • The prototype binary's peak RSS was about 18 MiB higher than main's on unrelated commands (version: 152 vs 134 MiB), with no change in time. It is probably a shift in the bundle's chunk layout, but nobody looked. Check it on the real change.

Acceptance

  • The parity script passes against the base binary, including --help, -h, help and help --include-hidden.
  • The benchmark shows --help within noise of version. Quote both, plus peak RSS for version, --help and one routed command, before and after, from builds taken in the same session.
  • The new fitness rule fails when a row's description or aliases differ from the command's (mutation-checked).

Risk

Low. The only new failure mode is the metadata drifting from the real commands, and the fitness rule covers that.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 6 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/11/2026, 6:22:47 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/11/2026, 5:36:23 PM

Sign in to post a ripple.