blume 1.7.3 → 2.0.0

package/src/cli/commands/translate.ts

@@ -28,7 +28,7 @@ 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";
+import { flushStdout, logger, reportDiagnostics } from "../log.ts";
 
 /** Wall-clock ceiling per file, in seconds. */
 const DEFAULT_TIMEOUT_S = DEFAULT_TRANSLATE_TIMEOUT_MS / 1000;
@@ -293,7 +293,7 @@ export const translateCommand = defineCommand({
       }
     } catch (error) {
       if (error instanceof BlumeError) {
-        logger.error(error.diagnostic.message);
+        reportDiagnostics([error.diagnostic], root);
         process.exit(1);
       }
       // SAFETY: an ENOENT from spawning the agent CLI is an ErrnoException;

package/src/cli/commands/upgrade.ts

@@ -0,0 +1,141 @@
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { AGENTS, launchInstalledAgent } from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { formatDiagnostic } from "../../core/diagnostics.ts";
+import { packageRoot } from "../../core/package-root.ts";
+import { getBlumeVersion } from "../../core/version.ts";
+import {
+  UPGRADE_GUIDE_FILE,
+  UPGRADE_GUIDE_URL,
+  bumpBlumeDependency,
+  collectUpgradeFindings,
+  isOutsideBlumeProject,
+  upgradePrompt,
+} from "../../upgrade/upgrade.ts";
+import { commandMeta } from "../command-meta.ts";
+import { installDependencies } from "../init/install.ts";
+import { commandsFor, detectProjectPackageManager } from "../init/scaffold.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger } from "../log.ts";
+
+/**
+ * `blume upgrade` — move a project to this version of Blume. Run it through the
+ * package runner (`npx blume@latest upgrade`), since a project on the previous
+ * major doesn't have the command yet: it bumps `blume` in `package.json`,
+ * installs, then checks the config, `components.ts`, and each page's front
+ * matter against this version and lists what's left, or hands the list to
+ * Claude Code or Codex the way
+ * `blume audit --claude` does. Status lines go straight to stderr, like the
+ * audit's: consola drops info-level lines in test and CI environments.
+ */
+export const upgradeCommand = defineCommand({
+  args: {
+    claude: {
+      description: "Hand the remaining changes to Claude Code.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Hand the remaining changes to Codex.",
+      type: "boolean",
+    },
+    install: {
+      default: true,
+      description: "Install dependencies after bumping blume.",
+      negativeDescription: "Bump package.json without installing.",
+      type: "boolean",
+    },
+  },
+  meta: commandMeta.upgrade,
+  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 --claude or --codex.");
+      process.exit(1);
+    }
+    const [agent] = agents;
+    const version = getBlumeVersion();
+
+    try {
+      const bump = await bumpBlumeDependency(root, version);
+      // With neither a config nor a `blume` dependency there is nothing to
+      // check: the defaults would always pass and report the folder ready.
+      if (isOutsideBlumeProject(root, bump)) {
+        logger.error(
+          "No blume.config.ts or `blume` dependency here. Run `blume upgrade` from the folder with blume.config.ts — in a monorepo, the package that depends on blume."
+        );
+        process.exit(1);
+      }
+      const pm = await detectProjectPackageManager(root);
+      // A local install puts no `blume` on PATH, so every command this
+      // prints (or hands the agent) runs through the project's runner.
+      const runner = commandsFor(pm).exec;
+      if (bump.status === "bumped") {
+        process.stderr.write(
+          `  Bumped blume ${bump.from} → ${bump.to} in package.json.\n`
+        );
+        if (args.install) {
+          const outcome = await installDependencies(root, pm, {
+            quiet: false,
+          });
+          if (outcome.failure) {
+            logger.warn(
+              `Installing failed; run \`${outcome.command}\` yourself.\n${outcome.failure}`
+            );
+          }
+        }
+      } else if (bump.status === "missing") {
+        logger.warn(
+          `No \`blume\` dependency in ./package.json; add blume@^${version} to the package that uses it.`
+        );
+      }
+
+      const findings = await collectUpgradeFindings(root);
+      if (findings.length === 0) {
+        process.stderr.write(
+          `  Ready for Blume ${version}: the config, components.ts, and pages check out. Run \`${runner} blume build\` to confirm.\n`
+        );
+        return;
+      }
+      process.stderr.write(
+        `\n${findings.map((finding) => formatDiagnostic(finding, root)).join("\n\n")}\n\n`
+      );
+
+      if (!agent) {
+        process.stderr.write(
+          `  Each change is covered in the upgrade guide: ${UPGRADE_GUIDE_URL}\n  Rerun with --claude or --codex to hand them to a coding agent.\n`
+        );
+        process.exit(1);
+      }
+
+      const cli = AGENTS[agent];
+      process.stderr.write(`  Handing the upgrade to ${cli.name}…\n\n`);
+      const prompt = upgradePrompt({
+        findings,
+        guidePath: join(packageRoot(), UPGRADE_GUIDE_FILE),
+        root,
+        runner,
+        version,
+      });
+      const code = await launchInstalledAgent(cli.bin, prompt);
+      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);
+    }
+  },
+});

package/src/cli/commands/version.ts

@@ -3,9 +3,58 @@ 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 type { CutResult } from "../../core/version-cut.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { logger } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
+
+/** `blume version` with no id: list the configured versions. */
+const listVersions = async (root: string): Promise<void> => {
+  const { config } = await loadConfig(root);
+  if (!config.versions) {
+    logger.info(
+      "Versioning is not configured. Cut the first version with `blume version <id>` (e.g. `blume version v1.0`)."
+    );
+    return;
+  }
+  const { current, archived } = config.versions;
+  process.stdout.write(
+    `  ${current.label} (current)${current.badge ? ` — ${current.badge}` : ""}\n`
+  );
+  for (const version of archived) {
+    process.stdout.write(`  ${version.label ?? version.id} — ${version.id}/\n`);
+  }
+};
+
+/** Report what a cut did, including how its id reached the config (or didn't). */
+const reportCut = (id: string, result: CutResult): void => {
+  logger.success(`Snapshot ${result.dir} (${result.copied} file(s) copied)`);
+  const totalRewrites = result.rewritten.reduce(
+    (sum, entry) => sum + entry.count,
+    0
+  );
+  if (totalRewrites > 0) {
+    logger.info(
+      `Rewrote root-absolute links in ${result.rewritten.length} page(s) (${totalRewrites} line(s)).`
+    );
+  }
+  if (result.versionsAdded) {
+    logger.success(
+      `Turned on versioning in blume.config.ts with "${id}" archived; the live docs are labeled "Latest" in the switcher until you rename versions.current.label.`
+    );
+  } else if (result.configUpdated) {
+    logger.success(`Added "${id}" to versions.archived in blume.config.ts`);
+  } else if (result.configSnippet) {
+    // A warning, not info: until it's pasted, the snapshot builds as ordinary
+    // content — every page twice — and consola drops info lines under CI.
+    logger.warn(
+      `blume.config.ts couldn't be updated automatically, so "${id}" isn't registered yet and its pages build as ordinary content until it is. ${result.configSnippet}`
+    );
+  }
+  logger.info(
+    "Archived versions are frozen — future edits belong in the live tree. Restart `blume dev` to pick up the snapshot."
+  );
+};
 
 export const versionCommand = defineCommand({
   args: {
@@ -22,58 +71,22 @@ export const versionCommand = defineCommand({
   meta: commandMeta.version,
   async run({ args }) {
     const root = process.cwd();
-
-    if (!args.id) {
-      const { config } = await loadConfig(root);
-      if (!config.versions) {
-        logger.info(
-          "Versioning is not configured. Cut the first version with `blume version <id>` (e.g. `blume version v1.0`)."
-        );
-        return;
-      }
-      const { current, archived } = config.versions;
-      process.stdout.write(
-        `  ${current.label} (current)${current.badge ? ` — ${current.badge}` : ""}\n`
-      );
-      for (const version of archived) {
-        process.stdout.write(
-          `  ${version.label ?? version.id} — ${version.id}/\n`
-        );
-      }
-      return;
-    }
-
     try {
-      const result = await cutVersion(root, args.id, { force: args.force });
-      logger.success(
-        `Snapshot ${result.dir} (${result.copied} file(s) copied)`
-      );
-      const totalRewrites = result.rewritten.reduce(
-        (sum, entry) => sum + entry.count,
-        0
-      );
-      if (totalRewrites > 0) {
-        logger.info(
-          `Rewrote root-absolute links in ${result.rewritten.length} page(s) (${totalRewrites} line(s)).`
-        );
-      }
-      if (result.configUpdated) {
-        logger.success(
-          `Added "${args.id}" to versions.archived in blume.config.ts`
+      if (args.id) {
+        reportCut(
+          args.id,
+          await cutVersion(root, args.id, { force: args.force })
         );
-      } else if (result.configSnippet) {
-        logger.info(result.configSnippet);
+      } else {
+        await listVersions(root);
       }
-      logger.info(
-        "Archived versions are frozen — future edits belong in the live tree. Restart `blume dev` to pick up the snapshot."
-      );
     } catch (error) {
       if (error instanceof CutError) {
         logger.error(error.message);
         process.exit(1);
       }
       if (error instanceof BlumeError) {
-        logger.error(error.diagnostic.message);
+        reportDiagnostics([error.diagnostic], root);
         process.exit(1);
       }
       reportInternalError(error);

package/src/cli/eject-scripts.ts

@@ -1,7 +1,13 @@
+import { existsSync, readFileSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
 import { join } from "pathe";
 
+import { EJECTED_CONFIG_HEADER } from "../astro/templates.ts";
+import { packageRoot } from "../core/package-root.ts";
+import { commandsFor, detectProjectPackageManager } from "./init/scaffold.ts";
+import { logger } from "./log.ts";
+
 /** A JSON value, as `JSON.parse` of a manifest can return. */
 type JsonValue =
   | string
@@ -14,22 +20,72 @@ type JsonValue =
 /** The slice of package.json the rewrite touches; the rest rides along. */
 interface PackageManifest {
   [key: string]: JsonValue | undefined;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
   scripts?: Record<string, string>;
 }
 
+/** Package name → the semver range to depend on it at. */
+export interface DependencyRanges {
+  [name: string]: string;
+}
+
 /**
- * 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
- * `"dev": "blume dev"` would rebuild the removed `.blume` tree instead of
- * serving the ejected app. A missing or unreadable package.json is left alone.
+ * The version range Blume itself uses for each package it depends on or
+ * accepts as a peer, plus `blume` at the installed version — what an ejected
+ * app should pin so it keeps building against the same majors.
  */
-export const updatePackageScripts = async (root: string): Promise<void> => {
+export const blumeDependencyRanges = (): DependencyRanges => {
+  // SAFETY: blume's own package.json, which declares its version and both
+  // dependency maps; nothing else is read.
+  const manifest = JSON.parse(
+    readFileSync(join(packageRoot(), "package.json"), "utf-8")
+  ) as {
+    dependencies: Record<string, string>;
+    peerDependencies: Record<string, string>;
+    version: string;
+  };
+  return {
+    ...manifest.peerDependencies,
+    ...manifest.dependencies,
+    blume: `^${manifest.version}`,
+  };
+};
+
+/** Whether the manifest already lists `name` in any dependency field. */
+const declares = (pkg: PackageManifest, name: string): boolean =>
+  [
+    pkg.dependencies,
+    pkg.devDependencies,
+    pkg.optionalDependencies,
+    pkg.peerDependencies,
+  ].some((field) => field !== undefined && Object.hasOwn(field, name));
+
+/**
+ * Point the project's package.json at the ejected app. Its scripts run Astro
+ * directly: after an eject the Blume CLI no longer manages the runtime, so
+ * scaffolded scripts like `"dev": "blume dev"` would rebuild the removed
+ * `.blume` tree instead of serving the ejected app. And every package the
+ * ejected app imports by bare name (`dependencies`, from `eject()`) that the
+ * project doesn't list yet becomes a dependency at the range Blume itself
+ * uses (`ranges`).
+ *
+ * Returns the names it added, so the caller can ask for an install. A missing
+ * or unreadable package.json is left alone.
+ */
+export const updatePackageScripts = async (
+  root: string,
+  dependencies: string[] = [],
+  ranges: DependencyRanges = blumeDependencyRanges()
+): Promise<string[]> => {
   const pkgPath = join(root, "package.json");
   let pkg: PackageManifest;
   try {
     pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
   } catch {
-    return;
+    return [];
   }
   const scripts = pkg.scripts ?? {};
   pkg.scripts = {
@@ -38,5 +94,64 @@ export const updatePackageScripts = async (root: string): Promise<void> => {
     dev: "astro dev",
     preview: "astro preview",
   };
+  const added = dependencies.filter((name) => !declares(pkg, name));
+  if (added.length > 0) {
+    // Sorted, the way package managers write the field.
+    pkg.dependencies = Object.fromEntries(
+      Object.entries({
+        ...pkg.dependencies,
+        ...Object.fromEntries(added.map((name) => [name, ranges[name] ?? "*"])),
+      }).toSorted(([a], [b]) => (a < b ? -1 : 1))
+    );
+  }
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+  return added;
+};
+
+/**
+ * The first line Blume 1's `blume eject` wrote into the ejected
+ * `astro.config.mjs` — the hidden runtime's own header, carried over. Blume 2's
+ * hidden runtime keeps it under `.blume/`, never at the project root, so a root
+ * config that opens with it is an app Blume 1 ejected.
+ */
+const BLUME_1_EJECTED_CONFIG_HEADER =
+  "// Generated by Blume. Do not edit; this file is recreated on each run.";
+
+/**
+ * Whether `root` holds an app `blume eject` already wrote: a root
+ * `astro.config.mjs` whose first line is eject's header, or the header Blume 1
+ * ejected with. The header is the only signal: a Blume project may keep its own
+ * `astro.config.mjs` and a codegen `src/generated/` folder beside its content,
+ * and neither makes it an ejected app.
+ */
+export const isEjectedProject = (root: string): boolean => {
+  const config = join(root, "astro.config.mjs");
+  if (!existsSync(config)) {
+    return false;
+  }
+  const source = readFileSync(config, "utf-8");
+  return (
+    source.startsWith(EJECTED_CONFIG_HEADER) ||
+    source.startsWith(BLUME_1_EJECTED_CONFIG_HEADER)
+  );
+};
+
+/**
+ * Stop `blume dev`/`blume build` in an ejected app. Either would regenerate
+ * `.blume/` from `blume.config.ts` and run that hidden copy, ignoring every
+ * edit made to the app since eject, so point at the app's own script under
+ * the project's package manager instead.
+ */
+export const refuseIfEjected = async (
+  root: string,
+  script: "build" | "dev"
+): Promise<void> => {
+  if (!isEjectedProject(root)) {
+    return;
+  }
+  const commands = commandsFor(await detectProjectPackageManager(root));
+  logger.error(
+    `This project was ejected to a standalone Astro app, so \`blume ${script}\` would run a regenerated copy of the site instead of it. Run \`${commands[script]}\` instead.`
+  );
+  process.exit(1);
 };

package/src/cli/index.ts

@@ -16,7 +16,7 @@ import "./log.ts";
 
 const main = defineCommand({
   meta: {
-    description: "Markdown-first documentation powered by Astro and Vite.",
+    description: "The open-source docs framework for humans and agents.",
     name: "blume",
     version: getBlumeVersion(),
   },
@@ -71,6 +71,11 @@ const main = defineCommand({
       () => import("./commands/mcp-stdio.ts"),
       "mcpStdioCommand"
     ),
+    migrate: lazyCommand(
+      commandMeta.migrate,
+      () => import("./commands/migrate.ts"),
+      "migrateCommand"
+    ),
     preview: lazyCommand(
       commandMeta.preview,
       () => import("./commands/preview.ts"),
@@ -86,6 +91,11 @@ const main = defineCommand({
       () => import("./commands/translate.ts"),
       "translateCommand"
     ),
+    upgrade: lazyCommand(
+      commandMeta.upgrade,
+      () => import("./commands/upgrade.ts"),
+      "upgradeCommand"
+    ),
     validate: lazyCommand(
       commandMeta.validate,
       () => import("./commands/validate.ts"),

package/src/cli/init/install.ts

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+
+import { commandsFor } from "./scaffold.ts";
+import type { PackageManager } from "./scaffold.ts";
+
+/** How `installDependencies` ended, plus the command to print on failure. */
+export interface InstallOutcome {
+  /** The install command that ran (`bun install`, `npm install`, …). */
+  command: string;
+  /**
+   * Why the install failed: the package manager's exit code with whatever it
+   * printed, or the spawn error when the binary isn't on PATH. Absent on
+   * success.
+   */
+  failure?: string;
+}
+
+export interface InstallOptions {
+  /**
+   * Capture the package manager's output instead of streaming it to the
+   * terminal. Interactive runs capture it behind a spinner and show it only
+   * on failure; non-interactive runs stream it as-is.
+   */
+  quiet: boolean;
+}
+
+/**
+ * Run the package manager's install in a freshly scaffolded project so
+ * `blume dev` works as soon as `init` returns. Never throws: a missing binary
+ * or a non-zero exit resolves with a `failure`, so the caller can keep the
+ * scaffolded files and print the exact command to retry by hand.
+ */
+export const installDependencies = async (
+  root: string,
+  pm: PackageManager,
+  { quiet }: InstallOptions
+): Promise<InstallOutcome> => {
+  const command = commandsFor(pm).install;
+  const child = spawn(pm, ["install"], {
+    cwd: root,
+    env: process.env,
+    // npm, pnpm and yarn are `.cmd` shims on Windows, which Node only runs
+    // through a shell; bun is a real executable everywhere.
+    shell: process.platform === "win32",
+    stdio: quiet ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  const chunks: Buffer[] = [];
+  child.stdout?.on("data", (chunk: Buffer) => chunks.push(chunk));
+  child.stderr?.on("data", (chunk: Buffer) => chunks.push(chunk));
+  try {
+    // `once` rejects when the child emits `error` (e.g. ENOENT) before `close`.
+    // SAFETY: `close` is emitted with `(code, signal)`, so the first element
+    // is the exit code, or null when a signal ended the process.
+    const [code] = (await once(child, "close")) as [number | null];
+    if (code === 0) {
+      return { command };
+    }
+    const output = Buffer.concat(chunks).toString("utf-8").trim();
+    return {
+      command,
+      failure: [`${command} exited with code ${code}`, output]
+        .filter(Boolean)
+        .join("\n"),
+    };
+  } catch (error) {
+    // SAFETY: a spawn failure is an ErrnoException; only its message is shown.
+    return { command, failure: (error as Error).message };
+  }
+};

package/src/cli/init/questions.ts

@@ -119,6 +119,13 @@ export const collectAnswers = async (
       },
       { hint: "A Notion database", label: "notion", value: "notion" },
       { hint: "A Sanity dataset", label: "sanity", value: "sanity" },
+      {
+        hint: "A Contentful content type",
+        label: "contentful",
+        value: "contentful",
+      },
+      { hint: "A Payload collection", label: "payload", value: "payload" },
+      { hint: "A Strapi content type", label: "strapi", value: "strapi" },
       {
         hint: "MDX fetched from a GitHub repo",
         label: "mdx-remote",