blume 1.7.3 → 2.0.1

package/src/cli/commands/doctor.ts

@@ -1,15 +1,24 @@
 import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 
 import { defineCommand } from "citty";
 import { join } from "pathe";
 import { satisfies } from "semver";
 
+import { discoverIslands } from "../../astro/islands.ts";
+import { missingDependencyDiagnostic } from "../../astro/runtime-deps.ts";
+import {
+  analyzeComponentOverrides,
+  ComponentOverridesError,
+} from "../../core/component-overrides.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 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 { unregisteredSnapshotDiagnostics } from "../../core/version-cut.ts";
 import { commandMeta } from "../command-meta.ts";
+import { loadEnvFiles } from "../env.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
   flushStdout,
@@ -17,9 +26,36 @@ import {
   reportDiagnostics,
   reportDiagnosticsJson,
 } from "../log.ts";
+import { checkRequiredSecrets } from "../required-secrets.ts";
 
 const FALLBACK_NODE_RANGE = ">=22.12.0";
 
+/**
+ * Plan `components.ts` the way `blume dev`/`build` do, reporting each override
+ * that can't be planned — a non-static form, or an import of a file that
+ * doesn't exist — with its own line. The scan alone never reads the file, so
+ * without this doctor would pass a project whose build fails.
+ */
+const componentsDiagnostics = async (
+  componentsFile: string | null
+): Promise<Diagnostic[]> => {
+  if (!componentsFile) {
+    return [];
+  }
+  try {
+    analyzeComponentOverrides(
+      await readFile(componentsFile, "utf-8"),
+      componentsFile
+    );
+    return [];
+  } catch (error) {
+    if (error instanceof ComponentOverridesError) {
+      return error.issues;
+    }
+    throw error;
+  }
+};
+
 /** The supported Node range, read from the package's own `engines` field so
  * doctor can never drift from what the package actually declares. */
 const supportedNodeRange = (): string => {
@@ -56,33 +92,75 @@ export const doctorCommand = defineCommand({
       });
     }
 
+    // Read `.env` files first, as `blume dev`/`build` do: remote sources read
+    // their tokens during the scan, and the secrets check below reads them too.
+    loadEnvFiles(root);
+
     try {
       const project = await scanProject(root, { mode: "build" });
-      diagnostics.push(...project.diagnostics);
+      diagnostics.push(
+        ...project.diagnostics,
+        ...unregisteredSnapshotDiagnostics(project)
+      );
 
       const { config } = project;
+      // The packages and secrets a build would need: an adapter's missing SDK
+      // fails the build, and a missing secret fails at the first request.
+      const { islands } = await discoverIslands(root);
+      const dependencies = await missingDependencyDiagnostic(
+        config,
+        root,
+        "error",
+        islands.map((island) => island.framework)
+      );
+      if (dependencies) {
+        diagnostics.push(dependencies);
+      }
+      diagnostics.push(
+        ...(await componentsDiagnostics(project.context.componentsFile)),
+        ...checkRequiredSecrets(config)
+      );
       const features = serverFeatures(config);
-      if (features.length > 0 && config.deployment.output === "static") {
+      if (
+        features.length > 0 &&
+        config.deployment.options.output === "static"
+      ) {
+        // A host adapter already names the target, so only its
+        // `output: "static"` stands in the way; otherwise name one.
+        const { kind } = config.deployment;
         diagnostics.push({
           code: "BLUME_SERVER_FEATURE_REQUIRED",
-          message: `${features.join(", ")} require server output.`,
-          severity: "error",
-          suggestion: 'Set deployment.output to "server".',
-        });
-      }
-      if (config.deployment.output === "server" && !config.deployment.adapter) {
-        diagnostics.push({
-          code: "BLUME_ADAPTER_REQUIRED",
-          message: "Server output requires an adapter.",
+          message: `${features.join(", ")} ${features.length === 1 ? "requires" : "require"} server output.`,
           severity: "error",
-          suggestion: 'Set deployment.adapter (e.g. "vercel").',
+          suggestion:
+            kind === "static"
+              ? 'Set deployment to a host adapter from "blume/deploy" (e.g. `deployment: vercel()`).'
+              : `Drop \`output: "static"\` from \`deployment: ${kind}()\` to build for the server.`,
         });
       }
 
       if (!args.json) {
         logger.info(`Pages: ${project.graph.pages.length}`);
-        logger.info(`Output: ${config.deployment.output}`);
-        logger.info(`Search: ${config.search.provider}`);
+        logger.info(`Output: ${config.deployment.options.output}`);
+        logger.info(`Adapter: ${config.deployment.kind}`);
+        logger.info(`Search: ${config.search.provider.kind}`);
+        logger.info(
+          `References: ${config.reference.map((adapter) => adapter.kind).join(", ") || "none"}`
+        );
+        logger.info(
+          `Analytics: ${config.analytics.map((adapter) => adapter.kind).join(", ") || "none"}`
+        );
+        logger.info(
+          `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`
+        );
+        const { assistant } = config.ai;
+        let assistantSummary = "off";
+        if (assistant?.enabled) {
+          assistantSummary = assistant.endpoint
+            ? "external endpoint"
+            : assistant.provider.kind;
+        }
+        logger.info(`Assistant: ${assistantSummary}`);
       }
     } catch (error) {
       if (error instanceof BlumeError) {

package/src/cli/commands/eject.ts

@@ -1,15 +1,39 @@
 import { defineCommand } from "citty";
 import { relative } from "pathe";
 
+import { BlumeError } from "../../core/diagnostics.ts";
 import { eject } from "../../registry/eject.ts";
 import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
-import { updatePackageScripts } from "../eject-scripts.ts";
+import { isEjectedProject, updatePackageScripts } from "../eject-scripts.ts";
 import { commandsFor, detectProjectPackageManager } from "../init/scaffold.ts";
-import { logger } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
+
+/**
+ * Eject the project, reporting a config or `components.ts` error as the same
+ * diagnostic other commands print (a Blume 1 config, say) instead of a stack.
+ */
+const ejectOrExit = async (
+  root: string
+): Promise<Awaited<ReturnType<typeof eject>>> => {
+  try {
+    return await eject(root);
+  } catch (error) {
+    if (error instanceof BlumeError) {
+      reportDiagnostics([error.diagnostic], root);
+      process.exit(1);
+    }
+    throw error;
+  }
+};
 
 export const ejectCommand = defineCommand({
   args: {
+    force: {
+      description:
+        "Eject again over an already-ejected app, overwriting astro.config.mjs and src/.",
+      type: "boolean",
+    },
     yes: { description: "Skip the confirmation prompt.", type: "boolean" },
   },
   meta: commandMeta.eject,
@@ -17,16 +41,25 @@ export const ejectCommand = defineCommand({
     const root = process.cwd();
     refuseIfDevRunning(root, "ejecting");
 
+    // A second eject rewrites the app from blume.config.ts, discarding every
+    // edit made to it since the first, so it takes an explicit --force.
+    if (isEjectedProject(root) && !args.force) {
+      logger.error(
+        "This project is already ejected: ejecting again would overwrite astro.config.mjs and src/ with a fresh copy, discarding your edits to them. Pass --force to overwrite them anyway."
+      );
+      process.exit(1);
+    }
+
     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."
+        "Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, adds the packages the Astro app imports to its dependencies, and removes .blume. An existing tsconfig.json is left untouched."
       );
       logger.info("Re-run with --yes to proceed.");
       return;
     }
 
-    const { files, warnings } = await eject(root);
-    await updatePackageScripts(root);
+    const { dependencies, files, warnings } = await ejectOrExit(root);
+    const added = await updatePackageScripts(root, dependencies);
 
     // The same surface as the generated-runtime path (prepare.ts): one warn
     // per generation warning, e.g. a Scalar reference spec that wasn't found.
@@ -41,9 +74,13 @@ export const ejectCommand = defineCommand({
     // Print run commands matching the project's package manager (lockfile
     // detection, since eject runs inside an existing project).
     const pm = await detectProjectPackageManager(root);
-    const { build, dev } = commandsFor(pm);
+    const { build, dev, install } = commandsFor(pm);
+    // Newly added dependencies aren't installed yet, so install comes first.
+    const run = added.length > 0 ? [install, dev, build] : [dev, build];
+    const addedNote =
+      added.length > 0 ? `Added to package.json: ${added.join(", ")}.\n\n` : "";
     logger.box(
-      `Your project is now a standalone Astro app.\n\n  ${dev}\n  ${build}\n\nThe blume package remains importable.`
+      `Your project is now a standalone Astro app.\n\n${addedNote}${run.map((command) => `  ${command}`).join("\n")}\n\nThe blume package remains importable.`
     );
   },
 });

package/src/cli/commands/eval.ts

@@ -24,7 +24,7 @@ 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";
+import { flushStdout, logger, reportDiagnostics } from "../log.ts";
 
 const DEFAULT_FILE = "evals.yaml";
 
@@ -82,7 +82,7 @@ interface EvalFlags {
 /** Validate the flag surface, exiting with a message on the first offense. */
 const parseFlags = (args: EvalFlags) => {
   if (!isAgentKind(args.agent)) {
-    logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
+    logger.error(`Invalid --agent "${args.agent}" (use codex | claude).`);
     process.exit(1);
   }
   if (args.action !== undefined && args.action !== "init") {
@@ -152,8 +152,8 @@ export const evalCommand = defineCommand({
       type: "positional",
     },
     agent: {
-      default: "claude",
-      description: "Agent CLI that reads and grades the docs: claude | codex.",
+      default: "codex",
+      description: "Agent CLI that reads and grades the docs: codex | claude.",
       type: "string",
     },
     file: {
@@ -232,7 +232,7 @@ export const evalCommand = defineCommand({
         process.exit(1);
       }
       if (error instanceof BlumeError) {
-        logger.error(error.diagnostic.message);
+        reportDiagnostics([error.diagnostic], root);
         process.exit(1);
       }
       // SAFETY: only the `code` tag is inspected; a spawn failure throws an

package/src/cli/commands/init.ts

@@ -6,6 +6,7 @@ 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 { installDependencies } from "../init/install.ts";
 import { collectAnswers } from "../init/questions.ts";
 import {
   applyPlan,
@@ -14,48 +15,160 @@ import {
   detectPackageManager,
   nextSteps,
   PACKAGE_MANAGERS,
+  readExistingPackage,
   TEMPLATES,
   validateContentDir,
+  workspaceNote,
 } from "../init/scaffold.ts";
 import type { InitAnswers } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
+/** The `cd` line that opens every next-steps hint, when one is needed. */
+const cdStep = (answers: InitAnswers): string[] =>
+  answers.directory === "." ? [] : [`cd ${answers.directory}`];
+
+/**
+ * Install the scaffolded project's dependencies. Interactive runs hide the
+ * package manager's output behind a spinner; `--yes`/CI runs stream it. On
+ * failure the scaffold is left intact and the exact retry command is printed
+ * before exiting non-zero, so a CI wrapper can tell the two outcomes apart.
+ */
+const installScaffold = async (
+  root: string,
+  answers: InitAnswers,
+  interactive: boolean
+): Promise<void> => {
+  const command = commandsFor(answers.packageManager).install;
+  const spinner = interactive ? clack.spinner() : undefined;
+  if (spinner) {
+    spinner.start(`Installing dependencies (${command})`);
+  } else {
+    logger.info(`Installing dependencies (${command})…`);
+  }
+  const outcome = await installDependencies(root, answers.packageManager, {
+    quiet: interactive,
+  });
+  if (outcome.failure === undefined) {
+    if (spinner) {
+      spinner.stop("Installed dependencies");
+    } else {
+      logger.success("Installed dependencies");
+    }
+    return;
+  }
+  const retry = [...cdStep(answers), command];
+  const hint = `Project created successfully, but dependency installation failed.\n\nRetry with:\n\n  ${retry.join("\n  ")}\n`;
+  if (spinner) {
+    spinner.stop("Dependency installation failed");
+    clack.log.error(outcome.failure);
+    clack.note(hint.trimEnd());
+    clack.outro("Scaffolded without dependencies.");
+  } else {
+    logger.error(outcome.failure);
+    logger.box(hint.trimEnd());
+  }
+  process.exit(1);
+};
+
 /**
  * Eject the freshly scaffolded project, or print the install-then-eject path.
  * Eject jiti-loads the scaffolded blume.config.ts, whose `import { defineConfig }
  * from "blume"` only resolves once dependencies are installed (or blume is
- * hoisted from an ancestor node_modules, as in a monorepo) — so on a fresh
- * scaffold the fallback below is the common path.
+ * hoisted from an ancestor node_modules, as in a monorepo) — so the fallback
+ * below is the common path when the install step was skipped.
  */
 const ejectScaffold = async (
   root: string,
-  answers: InitAnswers
+  answers: InitAnswers,
+  needsInstall: boolean
 ): Promise<void> => {
   const commands = commandsFor(answers.packageManager);
-  const cd = answers.directory === "." ? [] : [`cd ${answers.directory}`];
+  const cd = cdStep(answers);
+  const install = needsInstall ? [commands.install] : [];
   try {
-    await eject(root);
+    const { dependencies } = await eject(root);
     // The scaffolded scripts point at the Blume CLI; the ejected app runs
     // Astro directly (mirroring the standalone `blume eject` command).
-    await updatePackageScripts(root);
+    const added = await updatePackageScripts(root, dependencies);
     logger.success("Ejected to a standalone Astro project.");
-    const steps = [...cd, commands.install, commands.dev];
-    logger.box(`Next steps:\n\n  ${steps.join("\n  ")}\n`);
+    // The packages eject added aren't installed yet, even when the scaffold's
+    // own install already ran, so install comes first either way.
+    const ejectInstall = added.length > 0 ? [commands.install] : install;
+    const steps = [...cd, ...ejectInstall, commands.dev];
+    logger.box(`Next steps:\n\n  ${steps.join("\n  ")}`);
   } catch (error) {
     // SAFETY: eject and the script rewrite throw Error instances; only the
     // message is surfaced in the fallback hint.
     logger.warn(
       `Scaffolded, but eject needs the project's dependencies installed to load blume.config.ts: ${(error as Error).message}`
     );
-    const steps = [
-      ...cd,
-      commands.install,
-      `${commands.exec} blume eject --yes`,
-    ];
-    logger.box(`Next steps:\n\n  ${steps.join("\n  ")}\n`);
+    const steps = [...cd, ...install, `${commands.exec} blume eject --yes`];
+    logger.box(`Next steps:\n\n  ${steps.join("\n  ")}`);
   }
 };
 
+/**
+ * Print the closing next steps. An existing package.json was left alone, so
+ * the steps add what it lacks; a workspace `note` already printed ahead of an
+ * install that ran, so it closes the steps only when the install is still the
+ * user's to run.
+ */
+const printNextSteps = async (
+  root: string,
+  answers: InitAnswers,
+  outcome: {
+    createdPackage: boolean;
+    interactive: boolean;
+    needsInstall: boolean;
+    note: string | undefined;
+  }
+): Promise<void> => {
+  const existing = outcome.createdPackage
+    ? undefined
+    : await readExistingPackage(root);
+  const steps = nextSteps(
+    answers,
+    outcome.needsInstall,
+    existing,
+    outcome.needsInstall ? outcome.note : undefined
+  );
+  if (outcome.interactive) {
+    clack.note(steps.trimEnd());
+    clack.outro("You're all set.");
+  } else {
+    // consola's box pads its content itself; a trailing newline would add
+    // blank rows at the bottom.
+    logger.box(steps.trimEnd());
+  }
+};
+
+/**
+ * Validate the enum-valued flags up front, exiting with the accepted values
+ * on a typo so a bad flag never reaches the prompts.
+ */
+const resolveFlags = (args: {
+  "package-manager"?: string;
+  template?: string;
+}) => {
+  const template = TEMPLATES.find((candidate) => candidate === args.template);
+  if (args.template !== undefined && template === undefined) {
+    logger.error(
+      `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
+    );
+    process.exit(1);
+  }
+  const pm = PACKAGE_MANAGERS.find(
+    (candidate) => candidate === args["package-manager"]
+  );
+  if (args["package-manager"] !== undefined && pm === undefined) {
+    logger.error(
+      `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
+    );
+    process.exit(1);
+  }
+  return { pm, template };
+};
+
 export const initCommand = defineCommand({
   args: {
     "content-dir": {
@@ -71,9 +184,15 @@ export const initCommand = defineCommand({
       description: "Eject to a standalone Astro project after scaffolding.",
       type: "boolean",
     },
+    install: {
+      default: true,
+      description: "Install dependencies after scaffolding.",
+      negativeDescription: "Skip installing dependencies after scaffolding.",
+      type: "boolean",
+    },
     "package-manager": {
       description:
-        "Package manager for the next-steps hint (npm|pnpm|yarn|bun).",
+        "Package manager to install with and print in the next steps (npm|pnpm|yarn|bun).",
       type: "string",
     },
     template: {
@@ -88,23 +207,7 @@ export const initCommand = defineCommand({
   meta: commandMeta.init,
   async run({ args }) {
     const cwd = process.cwd();
-
-    const template = TEMPLATES.find((candidate) => candidate === args.template);
-    if (args.template !== undefined && template === undefined) {
-      logger.error(
-        `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
-      );
-      process.exit(1);
-    }
-    const pm = PACKAGE_MANAGERS.find(
-      (candidate) => candidate === args["package-manager"]
-    );
-    if (args["package-manager"] !== undefined && pm === undefined) {
-      logger.error(
-        `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
-      );
-      process.exit(1);
-    }
+    const { pm, template } = resolveFlags(args);
 
     const interactive =
       !args.yes &&
@@ -153,7 +256,14 @@ export const initCommand = defineCommand({
     }
 
     const sink = interactive ? clack.log : logger;
-    const { createdPackage } = await applyPlan(buildPlan(root, answers), sink);
+    const env = { userAgent: process.env.npm_config_user_agent };
+    const { createdPackage } = await applyPlan(
+      buildPlan(root, answers, env),
+      sink
+    );
+    // A workspace the project joins keeps its own package-manager config,
+    // which `init` leaves alone; say what it still needs before installing.
+    const note = workspaceNote(root, answers, env);
 
     // Keep installed dependencies, Blume's generated runtime (`.blume/`), and
     // build output (`dist/`) out of version control. Idempotent: creates
@@ -168,17 +278,27 @@ export const initCommand = defineCommand({
       sink.success(`Added ${ignored.join(", ")} to .gitignore`);
     }
 
+    // A newly written package.json is the only one `init` knows lists blume;
+    // an existing one is left alone, and so are its dependencies.
+    const shouldInstall = createdPackage && args.install;
+    if (note) {
+      (interactive ? clack.log : logger).warn(note);
+    }
+    if (shouldInstall) {
+      await installScaffold(root, answers, interactive);
+    }
+    const needsInstall = createdPackage && !shouldInstall;
+
     if (args.eject) {
-      await ejectScaffold(root, answers);
+      await ejectScaffold(root, answers, needsInstall);
       return;
     }
 
-    const steps = nextSteps(answers, createdPackage);
-    if (interactive) {
-      clack.note(steps.trimEnd());
-      clack.outro("You're all set.");
-    } else {
-      logger.box(steps);
-    }
+    await printNextSteps(root, answers, {
+      createdPackage,
+      interactive,
+      needsInstall,
+      note,
+    });
   },
 });

package/src/cli/commands/migrate.ts

@@ -0,0 +1,121 @@
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { AGENTS, launchInstalledAgent } from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { packageRoot } from "../../core/package-root.ts";
+import { getBlumeVersion } from "../../core/version.ts";
+import {
+  MIGRATE_SKILL_DIR,
+  MIGRATE_SOURCES,
+  MIGRATE_SOURCE_NAMES,
+  detectMigrateSource,
+  isMigrateSource,
+  migratePrompt,
+} from "../../migrate/migrate.ts";
+import type { MigrateSourceId } from "../../migrate/migrate.ts";
+import { commandMeta } from "../command-meta.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger } from "../log.ts";
+
+/**
+ * `blume migrate [source]` — move a docs site from another framework to Blume
+ * with a coding agent. Run it through the package runner (`npx blume migrate
+ * fumadocs --claude`) in the site being migrated: it names the source (or
+ * detects it), then opens Claude Code or Codex on the `blume-migrate` skill
+ * bundled in this package, the way `blume audit --claude` hands off its
+ * findings. The judgment stays in the skill; the command is the front door.
+ * Status lines go straight to stderr: consola drops info-level lines in test
+ * and CI environments.
+ */
+export const migrateCommand = defineCommand({
+  args: {
+    claude: {
+      description: "Run the migration with Claude Code.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Run the migration with Codex.",
+      type: "boolean",
+    },
+    source: {
+      description: `The framework to migrate from: ${MIGRATE_SOURCES.join(" | ")}. Detected when omitted.`,
+      required: false,
+      type: "positional",
+    },
+  },
+  meta: commandMeta.migrate,
+  async run({ args }) {
+    const root = process.cwd();
+    // SAFETY: AGENTS is a closed record keyed by AgentKind, so its keys are
+    // exactly the agent kinds.
+    const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
+      (kind) => args[kind]
+    );
+    if (agents.length > 1) {
+      logger.error("Pass at most one of --codex or --claude.");
+      process.exit(1);
+    }
+    const [agent] = agents;
+    if (args.source && !isMigrateSource(args.source)) {
+      logger.error(
+        `Unknown source "${args.source}" (use ${MIGRATE_SOURCES.join(" | ")}). Leave it out to detect the framework, or to migrate from one not listed.`
+      );
+      process.exit(1);
+    }
+
+    try {
+      const detected = await detectMigrateSource(root);
+      const named: MigrateSourceId | null =
+        args.source && isMigrateSource(args.source) ? args.source : null;
+      const source = named ?? detected?.source ?? null;
+      process.stderr.write(
+        source
+          ? `  Migrating from ${MIGRATE_SOURCE_NAMES[source]}${named ? "" : ` (detected from ${detected?.evidence})`}.\n`
+          : "  Couldn't detect the docs framework; the agent will inventory the repo first.\n"
+      );
+      // A named source wins, but a repo that looks like another framework is
+      // worth a second look before an agent rewrites it on the wrong mappings.
+      if (named && detected && detected.source !== named) {
+        process.stderr.write(
+          `  Warning: this looks like a ${MIGRATE_SOURCE_NAMES[detected.source]} project (${detected.evidence}); migrating from ${MIGRATE_SOURCE_NAMES[named]} as named.\n`
+        );
+      }
+      const skillDir = join(packageRoot(), MIGRATE_SKILL_DIR);
+
+      // Without an agent flag the command is the pointer for any other agent:
+      // the bundled skill's path (which lives in a throwaway cache under npx),
+      // plus the install line that puts the skill where agents look for it.
+      if (!agent) {
+        process.stderr.write(
+          `  blume migrate runs the migration with a coding agent: rerun with --codex or --claude.\n  Using another agent? Point it at ${join(skillDir, "SKILL.md")},\n  or install the skill where your agent looks for skills: npx skills add haydenbleasel/blume --skill blume-migrate\n`
+        );
+        return;
+      }
+
+      const cli = AGENTS[agent];
+      process.stderr.write(`  Handing the migration to ${cli.name}…\n\n`);
+      const code = await launchInstalledAgent(
+        cli.bin,
+        migratePrompt({
+          detected,
+          skillDir,
+          source,
+          version: getBlumeVersion(),
+        })
+      );
+      if (code === null) {
+        logger.error(
+          `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+        );
+        process.exit(1);
+      }
+      if (code !== 0) {
+        process.exit(code);
+      }
+    } catch (error) {
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});