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

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 CommandRoute type with name, aliases, module (the file path), needsFullTree and load(rest);
    • commandWords(args) and selectRoute(routes, args);
    • loadRoutes, which loads sequentially in table order.
  • 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 literal import(), because deno compile embeds only literal specifiers.

  • registerCommands(cli, args?) and buildCommandTree(args?) in mod.ts become async and take argv. runInvocation passes 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 help with no path;
    • the route has needsFullTree (completions).
  • help <path> loads the route named by the first path word, passes the rest on, and registers help over that tree. commands/help.ts resolves 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.load so a failed import becomes an error that names the command and module.

  • Callers await the builders: about 22 test and script files, scripts/command_index.ts among them. The fixes are mechanical (await buildCommandTree()).

  • Rewrite scripts/command_index.ts to read name → module from 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, so build_attestation.ts, the CI display and swamp-uat are untouched. Update integration/affected_commands_rules_test.ts.

  • src/cli/import_side_effects_test.ts and integration/remote_ca_cert_rules_test.ts call await buildCommandTree(). mod.ts no 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.ts from src/cli/mod.ts to src/cli/root_routes.ts (keep mod.ts too). Make it detect import() as well as static imports.

  • Fitness rules in integration/command_routes_rules_test.ts:

    1. Each route's module matches the specifier in its load (checked by reading the table source).
    2. The loaded tree's root children equal the table (names, aliases, hidden, order).
    3. No file under src/cli/commands/ is in the static-import closure of main.ts, built with collectImportEdges. commands/help.ts is 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.
    4. 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.
    5. Schema parity: for every command path, the tree built for that path has, at that path, the same buildCliSchema output as the full tree. Snapshot the full tree's schemas first, since building a second tree re-parents the shared instances.
    6. 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.
  • Unit tests for commandWords and selectRoute:

    • globals before and after the word;
    • --log-level in both spellings;
    • aliases (behaviour, summarize);
    • unknown options;
    • --;
    • no word;
    • help with and without a path.

    Add a property test that selectRoute never names a route that Cliffy's real parse of the full tree would not reach.

  • Keep the mechanical await changes 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 version and help data get gains and no workflow run regression.
  • The full-tree paths are slower until the bundled build ships: root --help, bare help, completions and a mistyped root command (measured 391 → 472 ms for --help). The PR states the measured number.
  • affectedCommands produced by the attestation generator is unchanged on a sample of changes (compare with the base commit). deno info records dynamic imports and buildImportGraph follows every edge, so a route's literal import() still links its command.
  • A swamp-uat run 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.

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

Shipped

11/10/2026, 9:36:57 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/10/2026, 6:57:46 PM

Sign in to post a ripple.