Relationships
#4592 Lazy loading L2: route table, load only the invoked top-level command
Opened by zack · 11/10/2026· Shipped 11/10/2026
Third step of the lazy command loading plan, and the first user-visible gain. Depends on the startup benchmark and parity scripts (#4590) and on moving VERSION/GIT_SHA out of the version command (#4591).
Why
Every invocation builds the whole Cliffy command tree today. Measured on a prototype (compiled, warm), loading only the invoked top-level command takes swamp version from 384 to about 165 ms and from 219 to 131 MB. Every light command (auth, config, update, issue, quest, …) gains about the same. swamp help <command>, which the swamp skill tells agents to run before every command, stops loading the whole tree.
The table and the argv selection land together. A module loaded through import() costs more than the same module loaded statically, because Deno's code cache covers only modules loaded at startup. A table whose routes all load on every invocation would be slower than today for every command.
Scope
src/cli/command_routes.ts:- a
CommandRoutetype withname,aliases,module(the file path),needsFullTreeandload(rest); commandWords(args)andselectRoute(routes, args);loadRoutes, which loads sequentially in table order.
- a
src/cli/root_routes.ts: one row per top-level command in today's registration order (that order is root help's listing order). Each row has a literalimport(), becausedeno compileembeds only literal specifiers.registerCommands(cli, args?)andbuildCommandTree(args?)inmod.tsbecome async and take argv.runInvocationpasses it to both the auth-gate tree and the real tree, and still builds the gate tree first: top-level commands are shared instances that Cliffy re-parents to the last tree.Only the root's own global options may appear before the first word:
--json,--log,--log-level <v>/--log-level=v,-q/--quiet,-v/--verbose,--no-telemetry,--show-properties,--no-color.The full tree loads when:
- there is no command word;
- the word is unknown;
- any other option comes before the first word;
- the command is
helpwith no path; - the route has
needsFullTree(completions).
help <path>loads the route named by the first path word, passes the rest on, and registershelpover that tree.commands/help.tsresolves the path from the root and builds the schema of that node alone, so the output does not change. An unknown first path word loads the full tree, so the "Unknown command" error and telemetry's command-word check see what they see today.Wrap each
route.loadso a failed import becomes an error that names the command and module.Callers
awaitthe builders: about 22 test and script files,scripts/command_index.tsamong them. The fixes are mechanical (await buildCommandTree()).Rewrite
scripts/command_index.tsto readname → modulefrom the route table, and drop the object-identity matching (it breaks once the builder is async:tree.getCommands is not a function). Keep its output format, sobuild_attestation.ts, the CI display andswamp-uatare untouched. Updateintegration/affected_commands_rules_test.ts.src/cli/import_side_effects_test.tsandintegration/remote_ca_cert_rules_test.tscallawait buildCommandTree().mod.tsno longer evaluates command modules on import, so without this change they would pass without testing anything.Move the "nothing imports the CLI composition root" guard in
integration/ddd_layer_rules_test.tsfromsrc/cli/mod.tstosrc/cli/root_routes.ts(keepmod.tstoo). Make it detectimport()as well as static imports.Fitness rules in
integration/command_routes_rules_test.ts:- Each route's
modulematches the specifier in itsload(checked by reading the table source). - The loaded tree's root children equal the table (names, aliases, hidden, order).
- No file under
src/cli/commands/is in the static-import closure ofmain.ts, built withcollectImportEdges.commands/help.tsis the one pinned exception. This is the rule that keeps the gain: one static import of a command from startup code brings its whole graph back for every invocation. - The router's global-option list equals the options declared on the root command, including which of them take a value. A new root option that the router does not know sends every use of it to the full tree; one whose arity it gets wrong picks the wrong word.
- Schema parity: for every command path, the tree built for that path has, at that path, the same
buildCliSchemaoutput as the full tree. Snapshot the full tree's schemas first, since building a second tree re-parents the shared instances. - Each route loads and resolves its path in a fresh
Worker. Each Worker has its own module graph, so a module-cycle TDZ error or a missing side effect shows up per command. Run them with bounded parallelism.
- Each route's
Unit tests for
commandWordsandselectRoute:- globals before and after the word;
--log-levelin both spellings;- aliases (
behaviour,summarize); - unknown options;
--;- no word;
helpwith and without a path.
Add a property test that
selectRoutenever names a route that Cliffy's real parse of the full tree would not reach.Keep the mechanical
awaitchanges in their own commit.
Not in scope
Group routing (loading one subcommand inside data, workflow, behavior/model); that is the next step.
Acceptance
- The parity script passes against the base binary.
- The benchmark shows the
versionandhelp data getgains and noworkflow runregression. - The full-tree paths are slower until the bundled build ships: root
--help, barehelp,completionsand a mistyped root command (measured 391 → 472 ms for--help). The PR states the measured number. affectedCommandsproduced by the attestation generator is unchanged on a sample of changes (compare with the base commit).deno inforecords dynamic imports andbuildImportGraphfollows every edge, so a route's literalimport()still links its command.- A
swamp-uatrun against the PR's compiled binary (SWAMP_BINARY_PATH) passes before merge. The release UAT runs everything for this PR anyway (startup-only change), but a failure there blocks every other release until the revert.
Review gate
scripts/command_index.ts is on the trust-root list in .github/workflows/ci.yml, so this PR triggers claude-review-integrity. scripts/affected_commands.ts needs no change.
Risk
Medium:
- side-effect order (command modules now evaluate after startup code, in table order rather than import order);
- a command module that reads a registry before startup populates it;
- a command that relied on a sibling command's module having been evaluated.
The Worker test catches the first two at import; the UAT run is the guard for the third. Rolling back is one revert.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.