blume 1.6.5 → 1.7.0

package/src/cli/commands/dev.ts

@@ -4,37 +4,29 @@ import { defineCommand } from "citty";
 import { debounce } from "perfect-debounce";
 
 import { generateRuntime } from "../../astro/generate.ts";
-import { showBlumeErrorOverlay } from "../../astro/integration.ts";
+import {
+  refreshBlumeContent,
+  showBlumeErrorOverlay,
+} from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
+import { commandMeta } from "../command-meta.ts";
 import {
   acquireDevLock,
   describeDevLock,
   DevLockHeldError,
   updateDevLockPort,
 } from "../dev-lock.ts";
+import { normalizeHost } from "../host-args.ts";
 import { logger, reportDiagnostics } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
-/**
- * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
- * citty has no mixed string/boolean arg type, so `host` is declared as a
- * string and a bare `--host` parses as `""` (the CLI entry rewrites it to
- * `--host=` first; see `host-args.ts`) — Node would bind all interfaces
- * for `""`, but Vite's `resolveHostname` treats it as a literal hostname and
- * prints malformed URLs like `http://:4321/`. Match Astro's own `--host`
- * semantics instead: bare flag → `true` (bind all interfaces), `--host
- * 10.0.0.1` → that address, absent → `false` (localhost only).
- */
-export const normalizeHost = (host: string | undefined): boolean | string =>
-  host === "" ? true : (host ?? false);
-
 /**
  * A fingerprint of the route set: the sorted `path entryId` pairs. It changes
  * when a page is added, removed, or renamed (a folder rename shifts many at
  * once) but stays equal across pure body edits — so the dev loop can tell a
- * "structural" change (needs a cold restart) from a hot-reloadable one.
+ * "structural" change (needs a content re-sync) from a hot-reloadable one.
  */
 const routeSignature = (
   routes: readonly { entryId: string; path: string }[]
@@ -63,10 +55,7 @@ export const devCommand = defineCommand({
     },
     strict: { description: "Fail on diagnostics.", type: "boolean" },
   },
-  meta: {
-    description: "Start the Blume development server.",
-    name: "dev",
-  },
+  meta: commandMeta.dev,
   async run({ args }) {
     const root = process.cwd();
     const preview = args.preview ?? false;
@@ -110,10 +99,10 @@ export const devCommand = defineCommand({
       strict: args.strict,
     });
 
-    // A factory so `runRegenerate` can recreate the server on a structural
-    // (route-set) change: only a cold container re-globs Astro's content store,
-    // which its in-place config restart doesn't. `open` is honored on first
-    // boot only — a restart must not reopen the browser.
+    // A factory so the regenerate loop can recreate the server when a
+    // structural (route-set) change can't be re-synced in place (see below).
+    // `open` is honored on first boot only — a restart must not reopen the
+    // browser.
     const createServer = (listenPort: number | undefined, open: boolean) =>
       dev({
         logLevel: args.debug ? "debug" : "info",
@@ -141,14 +130,16 @@ export const devCommand = defineCommand({
     let lastSignature = routeSignature(project.manifest.routes);
 
     // Watch user inputs and regenerate the runtime data on change. A body edit
-    // hot-reloads via Vite (fast path). A route-set change instead forces a cold
-    // server restart: Astro's in-place content sync never re-globs on a Blume
-    // route change (it strips `integrations` from its cache digest) and its glob
-    // watcher misses directory renames, so a renamed page 404s (`getEntry` reads
-    // a stale in-memory store) until the server is restarted. We restart it
-    // ourselves — stop, regenerate while down (no watcher races), then bring up
-    // a fresh container whose cold sync re-globs everything. perfect-debounce
-    // both debounces the watch burst (80ms) and single-flights the scan: a
+    // hot-reloads via Vite (fast path). A route-set change also needs Astro's
+    // content store re-synced: its glob watcher misses directory renames, so a
+    // renamed page would 404 (`getEntry` reads a stale store). Astro hands the
+    // integration `refreshContent` for exactly that — a full loader run
+    // against the live server, after which Astro's own store watcher clears
+    // the route cache and reloads the browser. Only a server that registered
+    // no refresh (none since Astro 5) falls back to a cold restart: stop,
+    // then bring up a fresh container whose cold sync re-globs everything.
+    // perfect-debounce both debounces the watch burst (80ms) and
+    // single-flights the scan: a
     // trigger during a run never starts a second run, only marks one trailing
     // rerun after the current settles. Both halves are load-bearing — a plain
     // debounce once let bursts stack overlapping scans until the heap was
@@ -166,23 +157,21 @@ export const devCommand = defineCommand({
         });
         const nextSignature = routeSignature(next.manifest.routes);
         const structural = nextSignature !== lastSignature;
-        if (structural) {
+        // Generate first: the new runtime data (and any staged remote content)
+        // is on disk and published before the store re-syncs against it.
+        await generateRuntime(next);
+        if (structural && !(await refreshBlumeContent())) {
           await server.stop();
-          await generateRuntime(next);
           server = await createServer(boundPort, false);
-        } else {
-          await generateRuntime(next);
         }
         // Commit the signature only after the (re)generation succeeded. If the
-        // restart above throws mid-sequence, the signature stays stale so the
-        // next watch event retries the structural path — committing early would
-        // route it to the non-structural branch with the server still down.
+        // re-sync or restart above throws mid-sequence, the signature stays
+        // stale so the next watch event retries the structural path.
         lastSignature = nextSignature;
         // Surface any content/config errors in the terminal AND the browser
-        // overlay. The terminal report must not be skipped: on a published
-        // install the CLI bundle holds its own copy of the integration module,
-        // separate from the Vite module graph that registers the overlay, so
-        // the overlay call below can be a no-op there.
+        // overlay. The terminal report is not redundant: the overlay only
+        // shows once the browser has connected, and it clears on the next HMR
+        // update.
         reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {

package/src/cli/commands/doctor.ts

@@ -9,6 +9,7 @@ import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
   flushStdout,
@@ -41,10 +42,7 @@ export const doctorCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Diagnose common configuration and content problems.",
-    name: "doctor",
-  },
+  meta: commandMeta.doctor,
   async run({ args }) {
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];

package/src/cli/commands/eject.ts

@@ -1,63 +1,26 @@
 import { defineCommand } from "citty";
 import { relative } from "pathe";
 
-import { loadConfig } from "../../core/config.ts";
 import { eject } from "../../registry/eject.ts";
+import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
-import {
-  droppedArtifactNotices,
-  updatePackageScripts,
-} from "../eject-scripts.ts";
+import { updatePackageScripts } from "../eject-scripts.ts";
 import { commandsFor, detectProjectPackageManager } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
-/**
- * Warn which `blume build` post-build artifacts the ejected app stops
- * producing. Printed both at the confirmation (so the decision is informed)
- * and after `--yes` (so a direct eject still sees it). No-op when the config
- * activates none of them.
- */
-const reportDroppedArtifacts = (notices: string[]): void => {
-  if (notices.length === 0) {
-    return;
-  }
-  logger.warn(
-    [
-      "The ejected build script runs plain `astro build`, which stops producing these `blume build` artifacts:",
-      ...notices.map((notice) => `  - ${notice}`),
-    ].join("\n")
-  );
-};
-
 export const ejectCommand = defineCommand({
   args: {
     yes: { description: "Skip the confirmation prompt.", type: "boolean" },
   },
-  meta: {
-    description: "Promote the generated runtime into an owned Astro project.",
-    name: "eject",
-  },
+  meta: commandMeta.eject,
   async run({ args }) {
     const root = process.cwd();
     refuseIfDevRunning(root, "ejecting");
 
-    // Config-aware drop list: only the artifacts this project actually
-    // produces are mentioned (e.g. the Pagefind index only for
-    // `search.provider: "pagefind"`).
-    let notices: string[] = [];
-    try {
-      const { config } = await loadConfig(root);
-      notices = droppedArtifactNotices(config);
-    } catch {
-      // A config that fails to load can't gate the notice; the eject itself
-      // surfaces the load error.
-    }
-
     if (!args.yes) {
       logger.warn(
         "Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched."
       );
-      reportDroppedArtifacts(notices);
       logger.info("Re-run with --yes to proceed.");
       return;
     }
@@ -75,7 +38,6 @@ export const ejectCommand = defineCommand({
     for (const file of files) {
       process.stdout.write(`  ${relative(root, file)}\n`);
     }
-    reportDroppedArtifacts(notices);
     // Print run commands matching the project's package manager (lockfile
     // detection, since eject runs inside an existing project).
     const pm = await detectProjectPackageManager(root);

package/src/cli/commands/eval.ts

@@ -22,6 +22,7 @@ import {
 import { runEval } from "../../eval/run.ts";
 import type { EvalResult } from "../../eval/run.ts";
 import { EvalsFileError, loadEvalsFile } from "../../eval/schema.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger } from "../log.ts";
 
@@ -183,11 +184,7 @@ export const evalCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description:
-      "Test the docs: an agent answers your questions using only the documentation.",
-    name: "eval",
-  },
+  meta: commandMeta.eval,
   async run({ args }) {
     const root = process.cwd();
     const { agent, threshold, timeoutS } = parseFlags(args);

package/src/cli/commands/init.ts

@@ -4,6 +4,7 @@ import { resolve } from "pathe";
 
 import { ensureGitignore } from "../../core/gitignore.ts";
 import { eject } from "../../registry/eject.ts";
+import { commandMeta } from "../command-meta.ts";
 import { updatePackageScripts } from "../eject-scripts.ts";
 import { collectAnswers } from "../init/questions.ts";
 import {
@@ -84,10 +85,7 @@ export const initCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Scaffold a minimal Blume project.",
-    name: "init",
-  },
+  meta: commandMeta.init,
   async run({ args }) {
     const cwd = process.cwd();
 

package/src/cli/commands/mcp-stdio.ts

@@ -4,6 +4,7 @@ import { defineCommand } from "citty";
 
 import type { McpData } from "../../ai/mcp/data.ts";
 import { serveMcpStdio } from "../../ai/mcp/stdio.ts";
+import { commandMeta } from "../command-meta.ts";
 
 export const mcpStdioCommand = defineCommand({
   args: {
@@ -13,11 +14,7 @@ export const mcpStdioCommand = defineCommand({
       type: "string",
     },
   },
-  meta: {
-    description:
-      "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
-    name: "mcp-stdio",
-  },
+  meta: commandMeta["mcp-stdio"],
   async run({ args }) {
     // stdout belongs to the JSON-RPC transport from here on; every diagnostic
     // must go to stderr or the MCP client chokes on the stray line.

package/src/cli/commands/preview.ts

@@ -7,18 +7,16 @@ import { join } from "pathe";
 import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
+import { commandMeta } from "../command-meta.ts";
+import { normalizeHost } from "../host-args.ts";
 import { logger } from "../log.ts";
-import { normalizeHost } from "./dev.ts";
 
 export const previewCommand = defineCommand({
   args: {
     host: { description: "Network host to bind.", type: "string" },
     port: { description: "Port to listen on.", type: "string" },
   },
-  meta: {
-    description: "Preview the last production build.",
-    name: "preview",
-  },
+  meta: commandMeta.preview,
   async run({ args }) {
     const root = process.cwd();
     const { config } = await loadConfig(root);

package/src/cli/commands/sync.ts

@@ -8,6 +8,7 @@ import {
   resolveProjectContext,
   resolveRuntimeDir,
 } from "../../core/project.ts";
+import { commandMeta } from "../command-meta.ts";
 import { readDevLock } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
@@ -24,10 +25,7 @@ export const syncCommand = defineCommand({
     },
     strict: { description: "Fail on diagnostics.", type: "boolean" },
   },
-  meta: {
-    description: "Re-fetch remote content sources and regenerate the runtime.",
-    name: "sync",
-  },
+  meta: commandMeta.sync,
   async run({ args }) {
     const root = process.cwd();
 

package/src/cli/commands/translate.ts

@@ -26,6 +26,7 @@ import {
 } from "../../translate/report.ts";
 import { runTranslate } from "../../translate/run.ts";
 import { computeWorkList } from "../../translate/work-list.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger } from "../log.ts";
 
@@ -181,11 +182,7 @@ export const translateCommand = defineCommand({
       type: "string",
     },
   },
-  meta: {
-    description:
-      "Translate docs into the configured locales with a local agent CLI.",
-    name: "translate",
-  },
+  meta: commandMeta.translate,
   async run({ args }) {
     const root = process.cwd();
     const { agent, concurrency, timeoutS } = parseFlags(args);

package/src/cli/commands/validate.ts

@@ -13,6 +13,7 @@ import { validateLinks } from "../../core/links.ts";
 import { buildManifest } from "../../core/manifest.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
   flushStdout,
@@ -36,10 +37,7 @@ export const validateCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Validate internal, anchor, asset, and external links.",
-    name: "validate",
-  },
+  meta: commandMeta.validate,
   async run({ args }) {
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];

package/src/cli/commands/version.ts

@@ -3,6 +3,7 @@ import { defineCommand } from "citty";
 import { loadConfig } from "../../core/config.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { CutError, cutVersion } from "../../core/version-cut.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { logger } from "../log.ts";
 
@@ -18,10 +19,7 @@ export const versionCommand = defineCommand({
       type: "positional",
     },
   },
-  meta: {
-    description: "Freeze the current docs as an archived version.",
-    name: "version",
-  },
+  meta: commandMeta.version,
   async run({ args }) {
     const root = process.cwd();
 

package/src/cli/eject-scripts.ts

@@ -2,9 +2,6 @@ import { readFile, writeFile } from "node:fs/promises";
 
 import { join } from "pathe";
 
-import type { ResolvedConfig } from "../core/schema.ts";
-import { searchProviderMeta } from "../search/providers.ts";
-
 /** A JSON value, as `JSON.parse` of a manifest can return. */
 type JsonValue =
   | string
@@ -20,48 +17,6 @@ interface PackageManifest {
   scripts?: Record<string, string>;
 }
 
-/**
- * The `blume build`-only artifacts this project's config actually produces, as
- * notice lines for the eject command. After an eject the build script runs
- * plain `astro build`, which emits none of them — printing the config-aware
- * list makes the loss explicit instead of silent (a Pagefind site would
- * otherwise eject into a build whose search fails at runtime). Each gate
- * mirrors the artifact's producer in `blume build` (cli/commands/build.ts).
- */
-export const droppedArtifactNotices = (config: ResolvedConfig): string[] => {
-  const notices: string[] = [];
-  if (config.search.provider === "pagefind") {
-    notices.push(
-      'the Pagefind search index — the search UI loads it from the built site, so search will break in production. Add a post-build step: `"build": "astro build && pagefind --site dist"` (with `pagefind` installed as a devDependency).'
-    );
-  }
-  if (searchProviderMeta(config.search.provider).syncs) {
-    notices.push(
-      `the hosted ${config.search.provider} index sync — new and updated pages stop being pushed; re-upload your search records after each build with the provider's API or CLI.`
-    );
-  }
-  if (config.ai.llmsTxt.enabled) {
-    notices.push("llms.txt and llms-full.txt");
-  }
-  if (config.deployment.site && config.seo.sitemap) {
-    notices.push(
-      "sitemap.xml — recreate it with the @astrojs/sitemap integration."
-    );
-  }
-  if (config.seo.robots) {
-    notices.push("robots.txt — recreate it as a public/robots.txt file.");
-  }
-  if (config.seo.agentReadability) {
-    notices.push("agent-readability.json");
-  }
-  if (config.redirects.length > 0 && config.deployment.output === "static") {
-    notices.push(
-      "the platform redirect files (_redirects, vercel.json) — your redirects still work as Astro-generated meta-refresh pages."
-    );
-  }
-  return notices;
-};
-
 /**
  * Rewrite the project's package.json scripts to run Astro directly. After an
  * eject the Blume CLI no longer manages the runtime, so scaffolded scripts like

package/src/cli/host-args.ts

@@ -16,3 +16,19 @@ export const normalizeHostArgs = (rawArgs: readonly string[]): string[] =>
     const next = rawArgs[index + 1];
     return next === undefined || next.startsWith("-") ? "--host=" : arg;
   });
+
+/**
+ * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
+ * citty has no mixed string/boolean arg type, so `host` is declared as a
+ * string and a bare `--host` parses as `""` (`normalizeHostArgs` rewrites it
+ * to `--host=` first) — Node would bind all interfaces for `""`, but Vite's
+ * `resolveHostname` treats it as a literal hostname and prints malformed URLs
+ * like `http://:4321/`. Match Astro's own `--host` semantics instead: bare
+ * flag → `true` (bind all interfaces), `--host 10.0.0.1` → that address,
+ * absent → `false` (localhost only).
+ *
+ * Lives beside `normalizeHostArgs` rather than in `commands/dev.ts` so
+ * `preview` can share it without importing the whole dev command graph.
+ */
+export const normalizeHost = (host?: string): boolean | string =>
+  host === "" ? true : (host ?? false);

package/src/cli/index.ts

@@ -1,24 +1,18 @@
 import { defineCommand, runMain } from "citty";
 
 import { getBlumeVersion } from "../core/version.ts";
-import { addCommand } from "./commands/add.ts";
-import { auditCommand } from "./commands/audit.ts";
-import { buildCommand } from "./commands/build.ts";
-import { checkCommand } from "./commands/check.ts";
-import { devCommand } from "./commands/dev.ts";
-import { doctorCommand } from "./commands/doctor.ts";
-import { ejectCommand } from "./commands/eject.ts";
-import { evalCommand } from "./commands/eval.ts";
-import { initCommand } from "./commands/init.ts";
-import { mcpStdioCommand } from "./commands/mcp-stdio.ts";
-import { previewCommand } from "./commands/preview.ts";
-import { syncCommand } from "./commands/sync.ts";
-import { translateCommand } from "./commands/translate.ts";
-import { validateCommand } from "./commands/validate.ts";
-import { versionCommand } from "./commands/version.ts";
+import { commandMeta } from "./command-meta.ts";
 import { loadEnvFiles } from "./env.ts";
 import { normalizeHostArgs } from "./host-args.ts";
 import { reportInternalError } from "./internal-error.ts";
+import { lazyCommand } from "./lazy-command.ts";
+// consola reads CONSOLA_LEVEL / NODE_ENV / TEST / CI / DEBUG when its module
+// evaluates. Import the logger here, ahead of `loadEnvFiles`, so those values
+// come from the real environment — never from a project `.env`, which would
+// otherwise silence or restyle every command's output. The commands are loaded
+// lazily below, so without this line consola would first evaluate after `.env`
+// had been applied.
+import "./log.ts";
 
 const main = defineCommand({
   meta: {
@@ -27,31 +21,86 @@ const main = defineCommand({
     version: getBlumeVersion(),
   },
   subCommands: {
-    add: addCommand,
-    audit: auditCommand,
-    build: buildCommand,
-    check: checkCommand,
-    dev: devCommand,
-    doctor: doctorCommand,
-    eject: ejectCommand,
-    eval: evalCommand,
-    init: initCommand,
-    "mcp-stdio": mcpStdioCommand,
-    preview: previewCommand,
-    sync: syncCommand,
-    translate: translateCommand,
-    validate: validateCommand,
-    version: versionCommand,
+    add: lazyCommand(
+      commandMeta.add,
+      () => import("./commands/add.ts"),
+      "addCommand"
+    ),
+    audit: lazyCommand(
+      commandMeta.audit,
+      () => import("./commands/audit.ts"),
+      "auditCommand"
+    ),
+    build: lazyCommand(
+      commandMeta.build,
+      () => import("./commands/build.ts"),
+      "buildCommand"
+    ),
+    check: lazyCommand(
+      commandMeta.check,
+      () => import("./commands/check.ts"),
+      "checkCommand"
+    ),
+    dev: lazyCommand(
+      commandMeta.dev,
+      () => import("./commands/dev.ts"),
+      "devCommand"
+    ),
+    doctor: lazyCommand(
+      commandMeta.doctor,
+      () => import("./commands/doctor.ts"),
+      "doctorCommand"
+    ),
+    eject: lazyCommand(
+      commandMeta.eject,
+      () => import("./commands/eject.ts"),
+      "ejectCommand"
+    ),
+    eval: lazyCommand(
+      commandMeta.eval,
+      () => import("./commands/eval.ts"),
+      "evalCommand"
+    ),
+    init: lazyCommand(
+      commandMeta.init,
+      () => import("./commands/init.ts"),
+      "initCommand"
+    ),
+    "mcp-stdio": lazyCommand(
+      commandMeta["mcp-stdio"],
+      () => import("./commands/mcp-stdio.ts"),
+      "mcpStdioCommand"
+    ),
+    preview: lazyCommand(
+      commandMeta.preview,
+      () => import("./commands/preview.ts"),
+      "previewCommand"
+    ),
+    sync: lazyCommand(
+      commandMeta.sync,
+      () => import("./commands/sync.ts"),
+      "syncCommand"
+    ),
+    translate: lazyCommand(
+      commandMeta.translate,
+      () => import("./commands/translate.ts"),
+      "translateCommand"
+    ),
+    validate: lazyCommand(
+      commandMeta.validate,
+      () => import("./commands/validate.ts"),
+      "validateCommand"
+    ),
+    version: lazyCommand(
+      commandMeta.version,
+      () => import("./commands/version.ts"),
+      "versionCommand"
+    ),
   },
 });
 
-// Load `.env`/`.env.local` before any command runs so remote content sources
-// can read their tokens (e.g. `GITHUB_TOKEN`) during the content scan.
 loadEnvFiles(process.cwd());
 
-// Backstop for unexpected async failures that escape a command's own handling
-// (e.g. a rejected timer/watcher in `blume dev`), so even those report through
-// the stable internal-error contract rather than a bare stack trace.
 process.on("uncaughtException", (error) => {
   reportInternalError(error);
   process.exit(1);

package/src/cli/lazy-command.ts

@@ -0,0 +1,47 @@
+import type { ArgsDef, CommandDef, CommandMeta } from "citty";
+
+/**
+ * Wrap a command so its module is imported only when citty needs its `args`
+ * or runs it. `meta` stays static (from `command-meta.ts`), so rendering root
+ * usage, matching an unknown name, and `blume <cmd> --help` for *another*
+ * command never touch this one's dependency graph.
+ *
+ * `load` imports the command's module and `key` names its export, so the call
+ * site stays a plain `() => import("./commands/x.ts")`.
+ *
+ * Only `args`, `setup`, `run`, and `cleanup` are forwarded: no Blume command
+ * declares `default`, `plugins`, or nested `subCommands`.
+ */
+export const lazyCommand = <Args extends ArgsDef, Key extends string>(
+  meta: CommandMeta,
+  load: () => Promise<Record<Key, CommandDef<Args>>>,
+  key: Key
+): CommandDef<Args> => {
+  const command = async () => {
+    const module = await load();
+    return module[key];
+  };
+  return {
+    args: async () => {
+      const { args } = await command();
+      // SAFETY: every Blume command passes `args` to `defineCommand` as a plain
+      // object literal (the "command registry" test checks it); citty's
+      // `Resolvable` widening is the only reason the type also admits a thunk
+      // or a promise here.
+      return args as Args;
+    },
+    cleanup: async (context) => {
+      const loaded = await command();
+      await loaded.cleanup?.(context);
+    },
+    meta,
+    run: async (context) => {
+      const loaded = await command();
+      await loaded.run?.(context);
+    },
+    setup: async (context) => {
+      const loaded = await command();
+      await loaded.setup?.(context);
+    },
+  };
+};