blume 0.7.0 → 0.8.0

package/src/cli/commands/init.ts

@@ -1,149 +1,73 @@
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-
+import * as clack from "@clack/prompts";
 import { defineCommand } from "citty";
-import { basename, dirname, isAbsolute, join, relative } from "pathe";
+import { resolve } from "pathe";
 
 import { ensureGitignore } from "../../core/gitignore.ts";
-import { blumePackageJson, toPackageName } from "../../core/package-json.ts";
 import { eject } from "../../registry/eject.ts";
+import { updatePackageScripts } from "../eject-scripts.ts";
+import { collectAnswers } from "../init/questions.ts";
+import {
+  applyPlan,
+  buildPlan,
+  commandsFor,
+  detectPackageManager,
+  nextSteps,
+  PACKAGE_MANAGERS,
+  TEMPLATES,
+  validateContentDir,
+} from "../init/scaffold.ts";
+import type {
+  InitAnswers,
+  PackageManager,
+  Template,
+} from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
-const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
-type Template = (typeof TEMPLATES)[number];
-
-const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
-type PackageManager = (typeof PACKAGE_MANAGERS)[number];
-
-/** A starter: the config plus seed content files (path is relative to root). */
-interface Starter {
-  config: string;
-  files: (contentDir: string) => { content: string; path: string }[];
-}
-
-const configFor = (
-  extra: string
-): string => `import { defineConfig } from "blume";
-
-export default defineConfig({
-  title: "My Docs",
-  description: "Documentation powered by Blume.",${extra}
-});
-`;
-
-const page = (title: string, description: string, body: string): string =>
-  `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
-
-const STARTERS: Record<Template, Starter> = {
-  api: {
-    config: configFor(`
-  openapi: {
-    enabled: true,
-    route: "/api",
-    sources: [
-      {
-        label: "Petstore",
-        spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-      },
-    ],
-  },`),
-    files: (dir) => [
-      {
-        content: page(
-          "API Reference",
-          "Explore the API.",
-          "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."
-        ),
-        path: join(dir, "index.mdx"),
-      },
-    ],
-  },
-  changelog: {
-    config: configFor(`
-  navigation: {
-    tabs: [
-      { label: "Docs", path: "/" },
-      { label: "Changelog", path: "/changelog" },
-    ],
-  },`),
-    files: (dir) => [
-      {
-        content: page(
-          "Introduction",
-          "Welcome to your new Blume docs.",
-          "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."
-        ),
-        path: join(dir, "index.mdx"),
-      },
-      {
-        content: `---\ntitle: v1.0.0\ntype: changelog\ndate: 2026-01-01\n---\n\nThe first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.\n`,
-        path: join(dir, "changelog", "v1-0-0.mdx"),
-      },
-    ],
-  },
-  docs: {
-    config: configFor(""),
-    files: (dir) => [
-      {
-        content: page(
-          "Introduction",
-          "Welcome to your new Blume docs.",
-          `# Introduction\n\nWelcome to **Blume** — markdown-first docs powered by Astro and Vite.\n\nEdit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`
-        ),
-        path: join(dir, "index.mdx"),
-      },
-    ],
-  },
-  sdk: {
-    config: configFor(""),
-    files: (dir) => [
-      {
-        content: page(
-          "Introduction",
-          "Get started with the SDK.",
-          "# Introduction\n\nInstall the SDK and make your first call. See [Installation](/installation)."
-        ),
-        path: join(dir, "index.mdx"),
-      },
-      {
-        content: page(
-          "Installation",
-          "Install the SDK.",
-          "# Installation\n\n```package-install\nyour-sdk\n```"
-        ),
-        path: join(dir, "installation.mdx"),
-      },
-    ],
-  },
-};
-
-/** Install + dev commands to print for the chosen package manager. */
-const commandsFor = (pm: PackageManager): { dev: string; install: string } => ({
-  dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
-  install: `${pm} install`,
-});
-
-const writeFileSafe = async (
-  path: string,
-  content: string
-): Promise<boolean> => {
-  if (existsSync(path)) {
-    logger.info(`Skipped existing ${path}`);
-    return false;
+/**
+ * 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.
+ */
+const ejectScaffold = async (
+  root: string,
+  answers: InitAnswers
+): Promise<void> => {
+  const commands = commandsFor(answers.packageManager);
+  const cd = answers.directory === "." ? [] : [`cd ${answers.directory}`];
+  try {
+    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);
+    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`);
+  } catch (error) {
+    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`);
   }
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, content, "utf-8");
-  logger.success(`Created ${path}`);
-  return true;
 };
 
 export const initCommand = defineCommand({
   args: {
     "content-dir": {
-      default: "docs",
       description: "Content directory.",
       type: "string",
     },
+    dir: {
+      description: "Directory to scaffold into (default: current directory).",
+      required: false,
+      type: "positional",
+    },
     eject: {
       description: "Eject to a standalone Astro project after scaffolding.",
       type: "boolean",
@@ -157,85 +81,101 @@ export const initCommand = defineCommand({
       description: "Starter template: docs | api | sdk | changelog.",
       type: "string",
     },
-    yes: { description: "Skip prompts.", type: "boolean" },
+    yes: {
+      description: "Skip prompts and scaffold with defaults.",
+      type: "boolean",
+    },
   },
   meta: {
     description: "Scaffold a minimal Blume project.",
     name: "init",
   },
   async run({ args }) {
-    const root = process.cwd();
-    const contentDir = args["content-dir"] ?? "docs";
-    // The content dir is joined into every scaffolded file path, so an absolute
-    // or `../`-escaping value would write outside the project. Reject it.
-    if (
-      isAbsolute(contentDir) ||
-      relative(root, join(root, contentDir)).startsWith("..")
-    ) {
+    const cwd = process.cwd();
+
+    const template = args.template as Template | undefined;
+    if (template !== undefined && !TEMPLATES.includes(template)) {
       logger.error(
-        `Invalid --content-dir "${contentDir}" (must be a path inside the project).`
+        `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
       );
       process.exit(1);
     }
-
-    const template = (args.template ?? "docs") as Template;
-    if (!TEMPLATES.includes(template)) {
+    const pm = args["package-manager"] as PackageManager | undefined;
+    if (pm !== undefined && !PACKAGE_MANAGERS.includes(pm)) {
       logger.error(
-        `Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`
+        `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
       );
       process.exit(1);
     }
-    const pm = (args["package-manager"] ?? "npm") as PackageManager;
-    if (!PACKAGE_MANAGERS.includes(pm)) {
+
+    const interactive =
+      !args.yes &&
+      process.stdin.isTTY === true &&
+      clack.isTTY(process.stdout) &&
+      !clack.isCI();
+
+    let answers: InitAnswers;
+    if (interactive) {
+      clack.intro("blume init");
+      const collected = await collectAnswers(
+        clack,
+        {
+          contentDir: args["content-dir"],
+          directory: args.dir,
+          packageManager: pm,
+          template,
+        },
+        { cwd, userAgent: process.env.npm_config_user_agent }
+      );
+      if (collected === null) {
+        clack.cancel("Cancelled — nothing was written.");
+        process.exit(0);
+      }
+      answers = collected;
+    } else {
+      answers = {
+        contentDir: args["content-dir"] ?? "docs",
+        directory: args.dir ?? ".",
+        packageManager:
+          pm ?? detectPackageManager(process.env.npm_config_user_agent),
+        sources: ["filesystem"],
+        template: template ?? "docs",
+        title: "My Docs",
+      };
+    }
+
+    const root = resolve(cwd, answers.directory);
+    // Interactive runs validate this inline, but an explicit --content-dir
+    // flag skips that prompt, so guard here in both modes.
+    if (validateContentDir(root, answers.contentDir) !== undefined) {
       logger.error(
-        `Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`
+        `Invalid --content-dir "${answers.contentDir}" (must be a path inside the project).`
       );
       process.exit(1);
     }
 
-    const starter = STARTERS[template];
-    const createdPackage = await writeFileSafe(
-      join(root, "package.json"),
-      blumePackageJson(toPackageName(basename(root)))
-    );
-    await writeFileSafe(join(root, "blume.config.ts"), starter.config);
-    await Promise.all(
-      starter
-        .files(contentDir)
-        .map((file) => writeFileSafe(join(root, file.path), file.content))
-    );
+    const sink = interactive ? clack.log : logger;
+    const { createdPackage } = await applyPlan(buildPlan(root, answers), sink);
 
     // Keep Blume's generated runtime (`.blume/`) and build output (`dist/`) out
     // of version control. Idempotent: creates `.gitignore` when absent and skips
     // entries already present (trailing-slash agnostic).
     const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
     if (ignored.length > 0) {
-      logger.success(`Added ${ignored.join(", ")} to .gitignore`);
+      sink.success(`Added ${ignored.join(", ")} to .gitignore`);
     }
 
-    const commands = commandsFor(pm);
-
     if (args.eject) {
-      // Eject only generates files (no Astro runtime), so it works right after
-      // scaffolding. The standalone app then runs with Astro directly.
-      try {
-        await eject(root);
-        logger.success("Ejected to a standalone Astro project.");
-        logger.box(`Next steps:\n\n  ${commands.install}\n  npx astro dev\n`);
-      } catch (error) {
-        logger.warn(
-          `Scaffolded, but eject failed: ${(error as Error).message}`
-        );
-        logger.box(
-          `Next steps:\n\n  ${commands.install}\n  blume eject --yes\n`
-        );
-      }
+      await ejectScaffold(root, answers);
       return;
     }
 
-    const nextSteps = createdPackage
-      ? `Next steps:\n\n  ${commands.install}\n  ${commands.dev}\n`
-      : `Next steps:\n\n  ${commands.dev}\n`;
-    logger.box(nextSteps);
+    const steps = nextSteps(answers, createdPackage);
+    if (interactive) {
+      clack.note(steps.trimEnd());
+      clack.outro("You're all set.");
+    } else {
+      logger.box(steps);
+    }
   },
 });

package/src/cli/commands/preview.ts

@@ -8,6 +8,7 @@ import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
 import { logger } from "../log.ts";
+import { normalizeHost } from "./dev.ts";
 
 export const previewCommand = defineCommand({
   args: {
@@ -32,7 +33,9 @@ export const previewCommand = defineCommand({
       logLevel: "info",
       root: context.outDir,
       server: {
-        host: args.host ?? false,
+        // `normalizeHost` maps a bare `--host` (citty parses it as "") to
+        // `true` so Vite binds all interfaces instead of the hostname "".
+        host: normalizeHost(args.host),
         port: parsePort(args.port),
       },
     });

package/src/cli/commands/validate.ts

@@ -3,8 +3,14 @@ import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import {
+  customStaticRoutes,
+  discoverPages,
+  hasGeneratedChangelog,
+} from "../../astro/pages.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 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 { reportInternalError } from "../internal-error.ts";
@@ -44,11 +50,40 @@ export const validateCommand = defineCommand({
       // link-validation blind spot, so silently passing would be misleading.
       diagnostics.push(...project.diagnostics);
 
+      // Custom `.astro` pages and the generated changelog index are servable
+      // routes the content graph can't see — without them, a docs link to e.g.
+      // a custom landing page fails as BLUME_BROKEN_LINK.
+      const userPages = project.context.pagesRoot
+        ? await discoverPages(project.context.pagesRoot)
+        : [];
+      const extraRoutes = customStaticRoutes(userPages);
+      if (hasGeneratedChangelog(project, userPages)) {
+        extraRoutes.push("/changelog");
+      }
+
+      // Fallback-materialized locale routes (an untranslated page prerendered
+      // at its localized URL) are servable but absent from the content graph —
+      // without them a link to an untranslated sibling under a non-default
+      // locale fails as BLUME_BROKEN_LINK even though the built site serves it.
+      if (project.config.i18n) {
+        const manifest = buildManifest({
+          config: project.config,
+          context: project.context,
+          graph: project.graph,
+        });
+        extraRoutes.push(
+          ...manifest.routes.flatMap((route) =>
+            route.fallback ? [route.path] : []
+          )
+        );
+      }
+
       const publicDir = join(root, "public");
       diagnostics.push(
         ...(await validateLinks(project.graph, {
           basePath: project.config.basePath,
           checkExternal: Boolean(args.external),
+          extraRoutes,
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
         }))
@@ -62,12 +97,18 @@ export const validateCommand = defineCommand({
       }
     }
 
+    // `--strict` escalates warnings to failures; info-level notes (e.g.
+    // BLUME_ASSETS_UNCHECKED when there is no public/ dir) stay advisory.
+    const strictFailure =
+      Boolean(args.strict) &&
+      diagnostics.some((diagnostic) => diagnostic.severity !== "info");
+
     if (args.json) {
       // Drain stdout before exiting non-zero: `process.exit` would otherwise
       // truncate the JSON payload mid-write when stdout is a pipe — exactly how
       // `--json` is consumed in CI/editors.
       const hadErrors = reportDiagnosticsJson(diagnostics, root);
-      if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+      if (hadErrors || strictFailure) {
         await flushStdout();
         process.exit(1);
       }
@@ -78,7 +119,7 @@ export const validateCommand = defineCommand({
     if (diagnostics.length === 0) {
       logger.success("No broken links found.");
     }
-    if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+    if (hadErrors || strictFailure) {
       process.exit(1);
     }
   },

package/src/cli/dev-lock.ts

@@ -191,17 +191,21 @@ export const describeDevLock = (lock: DevLockInfo): string =>
  * `action` names the operation being refused (e.g. "building"). `runtimeDir`
  * relocates the checked dir: an isolated verify (`.blume-verify`) targets a dir
  * dev never locks, so it proceeds; a default or `--runtime-dir .blume` run still
- * refuses.
+ * refuses. Only commands that actually accept `--isolated` (build, check) should
+ * set `isolatedHint`, so the refusal never suggests a flag the command ignores.
  */
 export const refuseIfDevRunning = (
   root: string,
   action: string,
-  runtimeDir?: string
+  options: { runtimeDir?: string; isolatedHint?: boolean } = {}
 ): void => {
-  const lock = readDevLock(resolveRuntimeDir(root, runtimeDir));
+  const lock = readDevLock(resolveRuntimeDir(root, options.runtimeDir));
   if (lock) {
+    const remedies = options.isolatedHint
+      ? "Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it."
+      : "Reuse that server or stop it first.";
     logger.error(
-      `A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it.`
+      `A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. ${remedies}`
     );
     process.exit(1);
   }

package/src/cli/eject-scripts.ts

@@ -0,0 +1,72 @@
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import type { ResolvedConfig } from "../core/schema.ts";
+import { searchProviderMeta } from "../search/providers.ts";
+
+/**
+ * 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
+ * `"dev": "blume dev"` would rebuild the removed `.blume` tree instead of
+ * serving the ejected app. A missing or unreadable package.json is left alone.
+ */
+export const updatePackageScripts = async (root: string): Promise<void> => {
+  const pkgPath = join(root, "package.json");
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const scripts = (pkg.scripts ?? {}) as Record<string, string>;
+  pkg.scripts = {
+    ...scripts,
+    build: "astro build",
+    dev: "astro dev",
+    preview: "astro preview",
+  };
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+};

package/src/cli/env.ts

@@ -13,15 +13,25 @@ const ENV_LINE =
 const DOUBLE_QUOTED = /^"(?<body>[\s\S]*)"$/u;
 const SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
 
+const ESCAPE = /\\(?<char>[\\nt"])/gu;
+const UNESCAPED: Record<string, string> = {
+  '"': '"',
+  "\\": "\\",
+  n: "\n",
+  t: "\t",
+};
+
 /** Unquote a value, expanding `\n`/`\t`/escapes inside double quotes only. */
 const unquote = (raw: string): string => {
   const double = raw.match(DOUBLE_QUOTED)?.groups?.body;
   if (double !== undefined) {
-    return double
-      .replaceAll("\\n", "\n")
-      .replaceAll("\\t", "\t")
-      .replaceAll('\\"', '"')
-      .replaceAll("\\\\", "\\");
+    // A single pass so each backslash is consumed exactly once — sequential
+    // replaceAll calls would expand the `n` in `\\n` (an escaped backslash
+    // followed by a literal `n`) into a newline.
+    return double.replaceAll(
+      ESCAPE,
+      (match, char: string) => UNESCAPED[char] ?? match
+    );
   }
   const single = raw.match(SINGLE_QUOTED)?.groups?.body;
   if (single !== undefined) {