blume 1.1.4 → 1.2.1

package/src/astro/generate.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import {
   lstat,
@@ -723,6 +724,22 @@ export const detectUsesMath = async (
   return [...contents, ...staged].some(containsMath);
 };
 
+const hashConfigSource = (source: string): string =>
+  createHash("sha256").update(source).digest("hex");
+
+const loadIntegrationBridge = async (
+  config: ResolvedConfig,
+  context: BlumeProject["context"]
+): Promise<Parameters<typeof astroConfigTemplate>[0]["integrationBridge"]> => {
+  if (config.integrations.length === 0 || !context.configFile) {
+    return;
+  }
+  return {
+    configFile: relative(context.outDir, context.configFile),
+    sourceHash: hashConfigSource(await readOptional(context.configFile)),
+  };
+};
+
 const writeIfChanged = async (
   path: string,
   content: string
@@ -1085,7 +1102,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       analytics: config.analytics ?? null,
       appleIcon: resolveAppleIcon(project),
       ask: config.ai.ask?.enabled
-        ? { suggestions: config.ai.ask.suggestions }
+        ? {
+            endpoint: config.ai.ask.endpoint ?? null,
+            suggestions: config.ai.ask.suggestions,
+          }
         : null,
       banner: resolveBanner(config),
       basePath: config.basePath,
@@ -1279,7 +1299,7 @@ const writeAskFiles = async (
   write: (path: string, content: string) => Promise<boolean>
 ): Promise<void> => {
   const { ask } = project.config.ai;
-  if (!ask?.enabled) {
+  if (!(ask?.enabled && !ask.endpoint)) {
     return;
   }
   const grounded = ask.provider !== "inkeep";
@@ -1418,6 +1438,7 @@ export const generateRuntime = async (
     usesMath,
     userTheme,
     userExamplesCss,
+    integrationBridge,
     islandDiscovery,
     exampleDiscovery,
     componentSlots,
@@ -1427,6 +1448,7 @@ export const generateRuntime = async (
     detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
+    loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
     buildComponentSlots(context.componentsFile),
@@ -1500,6 +1522,7 @@ export const generateRuntime = async (
           dataPath,
           examplesPath,
           examplesThemePath,
+          integrationBridge,
           needsReact,
           needsSvelte,
           needsVue,

package/src/astro/templates.ts

@@ -87,7 +87,14 @@ const WRANGLER_CONFIG_FILES = [
 ];
 
 const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
-  const args: string[] = ['prerenderEnvironment: "node"'];
+  // Every Blume HTML route prerenders (the only server routes are API
+  // endpoints), so images are optimized at build time with sharp. The
+  // adapter's default (`cloudflare-binding`) would instead declare a runtime
+  // `IMAGES` binding in the generated wrangler config that nothing uses.
+  const args: string[] = [
+    'prerenderEnvironment: "node"',
+    'imageService: "compile"',
+  ];
   const wranglerPath = WRANGLER_CONFIG_FILES.map((file) =>
     join(context.root, file)
   ).find((file) => existsSync(file));
@@ -104,6 +111,37 @@ const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
   return `{ ${args.join(", ")} }`;
 };
 
+/**
+ * Without a configured driver, `@astrojs/cloudflare` force-enables KV-backed
+ * sessions and declares a `SESSION` kv_namespaces entry in the generated
+ * wrangler config — which `wrangler deploy` then requires a real KV namespace
+ * for, even though Blume never reads `Astro.session`. An explicit in-memory
+ * driver keeps the binding out. Swap for Astro's session opt-out once
+ * withastro/astro#16871 ships in the supported range.
+ */
+const resolveSessionOption = (deployment: {
+  adapter: string | null;
+  output: string;
+}): string =>
+  deployment.output === "server" && deployment.adapter === "cloudflare"
+    ? "\n  session: { driver: sessionDrivers.memory() },"
+    : "";
+
+/** The named imports the generated config pulls from `astro/config`. */
+const astroConfigImportLine = (options: {
+  hasFonts: boolean;
+  hasSession: boolean;
+}): string => {
+  const names = ["defineConfig"];
+  if (options.hasFonts) {
+    names.push("fontProviders");
+  }
+  if (options.hasSession) {
+    names.push("sessionDrivers");
+  }
+  return `import { ${names.join(", ")} } from "astro/config";`;
+};
+
 /**
  * Integration packages the generated runtime imports. Declaring them in
  * `.blume/package.json` lets Astro's framework-package crawl discover and bundle
@@ -138,7 +176,7 @@ export const runtimeDependencies = (options: {
   // (and the user installs) exactly the backend it uses — nothing more.
   deps.push(...searchProviderMeta(config.search.provider).runtimeDeps);
   // Ask AI's provider SDK, when its backend needs one (gateway uses core `ai`).
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     const askDep = askBackendRuntimeDep(config.ai.ask);
     if (askDep) {
       deps.push(askDep);
@@ -290,6 +328,36 @@ const devWatchOption = (
       },`
     : "";
 
+interface IntegrationBridgeOptions {
+  /** Config path relative to the generated Astro config. */
+  configFile: string;
+  /** SHA-256 used to invalidate Astro's generated config. */
+  sourceHash?: string;
+}
+
+const renderIntegrationBridge = (
+  bridge: IntegrationBridgeOptions | undefined
+) => {
+  if (!bridge) {
+    return {
+      configSourceMarker: "",
+      userConfigImports: "",
+      userConfigSetup: "",
+      userIntegrationSpread: "",
+    };
+  }
+  return {
+    configSourceMarker: bridge.sourceHash
+      ? `// Blume config source SHA-256: ${bridge.sourceHash}\n`
+      : "",
+    userConfigImports: `import { dirname, resolve } from "node:path";\nimport { fileURLToPath } from "node:url";\nimport { createModuleLoader } from "blume/core/load-module.ts";\n`,
+    userConfigSetup: `const loadBlumeConfig = createModuleLoader();\nconst blumeConfig = await loadBlumeConfig(resolve(dirname(fileURLToPath(import.meta.url)), ${JSON.stringify(
+      bridge.configFile
+    )}));\n\n`,
+    userIntegrationSpread: ", ...(blumeConfig?.integrations ?? [])",
+  };
+};
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -322,6 +390,8 @@ export const astroConfigTemplate = (options: {
    * See {@link devWatchOption} for why this must stay scoped.
    */
   contentWatchesRuntimeDir?: boolean;
+  /** Bridge used to load configured integrations without serializing them. */
+  integrationBridge?: IntegrationBridgeOptions;
 }): string => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
@@ -367,6 +437,8 @@ export const astroConfigTemplate = (options: {
   const adapterOption =
     server && deployment.adapter ? `\n  adapter: ${adapterExpr},` : "";
 
+  const sessionOption = resolveSessionOption(deployment);
+
   const siteOption = deployment.site
     ? `\n  site: ${JSON.stringify(deployment.site)},`
     : "";
@@ -424,9 +496,10 @@ export const astroConfigTemplate = (options: {
         )
         .join(", ")}],`
     : "";
-  const defineConfigImport = fontEntries.length
-    ? `import { defineConfig, fontProviders } from "astro/config";`
-    : `import { defineConfig } from "astro/config";`;
+  const defineConfigImport = astroConfigImportLine({
+    hasFonts: fontEntries.length > 0,
+    hasSession: sessionOption.length > 0,
+  });
 
   // Framework renderers are only wired in when an island (or Ask AI, for React)
   // needs them. The core theme is Astro-first and ships no client JS.
@@ -486,20 +559,26 @@ export const astroConfigTemplate = (options: {
     context.outDir,
     options.contentWatchesRuntimeDir
   );
+  const {
+    configSourceMarker,
+    userConfigImports,
+    userConfigSetup,
+    userIntegrationSpread,
+  } = renderIntegrationBridge(options.integrationBridge);
 
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
-${defineConfigImport}
+${configSourceMarker}${userConfigImports}${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
 ${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
-export default defineConfig({
+${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
   outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
-  output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
-  integrations: [${integrations.join(", ")}],
+  output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
+  integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
       basePath: config.basePath,
@@ -521,18 +600,25 @@ export default defineConfig({
   devToolbar: { enabled: false },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
-    // Mermaid (lazy-loaded client-side for diagrams) statically imports dayjs as
-    // CJS (\`dayjs/dayjs.min.js\`). In dev, an un-pre-bundled dependency is served
-    // as raw ESM, and that UMD file exposes no \`default\` export, so mermaid
-    // throws on load and diagrams render blank. Forcing mermaid through the dep
-    // optimizer bundles dayjs with correct CJS interop. In a standalone install
-    // Blume's dynamic \`import("mermaid")\` lives inside \`node_modules/blume\`,
-    // which Vite's optimizer scan doesn't crawl, so mermaid is never discovered
-    // on its own — hence the explicit include. mermaid resolves through the
-    // \`blume\` package (it isn't a direct dep of the generated project), so the
-    // nested \`blume > mermaid\` form is required. Production (Rollup) already
-    // handles the interop, so this only affects dev.
-    optimizeDeps: { include: ["blume > mermaid"] },
+    // The lazy client-side imports both land on CJS/UMD files: mermaid (for
+    // diagrams) statically imports dayjs as CJS (\`dayjs/dayjs.min.js\`), and
+    // epub-gen-memory's browser bundle is a browserified UMD. In dev, an
+    // un-pre-bundled dependency is served as raw ESM, where such a file
+    // exposes no \`default\` export — mermaid throws on load and diagrams
+    // render blank, and the EPUB export throws \`epub is not a function\`
+    // (the UMD finds no \`exports\`/\`define\` and strands its callable on
+    // \`window.epubGen\` instead). Forcing them through the dep optimizer
+    // restores the CJS interop. In a standalone install these dynamic imports
+    // live inside \`node_modules/blume\`, which Vite's optimizer scan doesn't
+    // crawl, so neither is discovered on its own — hence the explicit
+    // includes. They resolve through the \`blume\` package (they aren't direct
+    // deps of the generated project), so the nested \`blume > x\` form is
+    // required, and epub-gen-memory must name the \`/bundle\` subpath that is
+    // actually imported: optimizing the package root leaves that entry out.
+    // Production (Rollup) already handles the interop, so this only affects dev.
+    optimizeDeps: {
+      include: ["blume > mermaid", "blume > epub-gen-memory/bundle"],
+    },
     // Blume's render-time deps are forced external on both build environments so
     // native bindings resolve at runtime and isolated linkers don't bundle
     // symlinked store copies (which would surface their children as unresolvable
@@ -850,7 +936,11 @@ import data from "blume:data";
 const { strings } = Astro.props;
 ---
 
-<AskAI strings={strings ?? data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />
+<AskAI
+  endpoint={data.config.ask?.endpoint ?? undefined}
+  strings={strings ?? data.ui.ask}
+  suggestions={data.config.ask?.suggestions ?? []}
+/>
 `
     : `---
 // Generated by Blume. Do not edit.
@@ -886,12 +976,18 @@ const searchClientImport = (module: string): string =>
 const SEARCH_BASE_IMPORT =
   'import { joinBase } from "blume/components/islands/base-path.ts";\n';
 
-/** A client that loads a static `blume-search.json` index (Orama, FlexSearch). */
-const staticSearchClient = (module: string): string =>
+/**
+ * A client that loads a static `blume-search.json` index (Orama, FlexSearch).
+ * `locale` (Orama only) is the site's `i18n.defaultLocale`, which selects a
+ * word-segmenting tokenizer for languages written without spaces.
+ */
+const staticSearchClient = (module: string, locale?: string): string =>
   `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}${SEARCH_BASE_IMPORT}
 const indexUrl = joinBase(import.meta.env.BASE_URL, "blume-search.json");
 
-export const createSearch = () => create({ indexUrl });
+export const createSearch = () => create({ indexUrl${
+    locale ? `, locale: ${JSON.stringify(locale)}` : ""
+  } });
 `;
 
 /** A client that passes public credentials straight to the provider SDK. */
@@ -940,7 +1036,12 @@ export const searchClientTemplate = (config: ResolvedConfig): string => {
   const { search } = config;
 
   if (search.provider === "orama" || search.provider === "flexsearch") {
-    return staticSearchClient(search.provider);
+    // Only Orama derives a tokenizer from the locale; FlexSearch has no
+    // equivalent hook, so its client keeps the bare index URL.
+    return staticSearchClient(
+      search.provider,
+      search.provider === "orama" ? config.i18n?.defaultLocale : undefined
+    );
   }
 
   const hosted = hostedSearchOptions(search);
@@ -1195,6 +1296,7 @@ export async function GET({ props }: { props: { title: string } }) {
 export const scalarReferenceTemplate = (options: {
   configuration: Record<string, unknown>;
   dataImport: string;
+  noindex?: boolean;
   route: string;
   title: string;
 }): string =>
@@ -1229,6 +1331,7 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
   favicon={data.config.favicon}
   appleIcon={data.config.appleIcon}
   navigation={data.navigation}
+  noindex={${options.noindex === true}}
   pageTitle={${JSON.stringify(options.title)}}
   route={${JSON.stringify(options.route)}}
   searchEnabled={data.config.search.enabled}

package/src/cli/commands/eval.ts

@@ -0,0 +1,291 @@
+import { existsSync } from "node:fs";
+
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import {
+  AGENTS,
+  launchAgent,
+  WINDOWS_COMMAND_NOT_FOUND,
+} from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import { evalFixPrompt, initPrompt } from "../../eval/prompts.ts";
+import {
+  evalReportJson,
+  fixLines,
+  headerLine,
+  questionDetails,
+  questionLine,
+  startLine,
+  summaryLine,
+  warningLines,
+  writeEvalReport,
+} from "../../eval/report.ts";
+import { runEval } from "../../eval/run.ts";
+import type { EvalResult } from "../../eval/run.ts";
+import { EvalsFileError, loadEvalsFile } from "../../eval/schema.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { flushStdout, logger } from "../log.ts";
+
+const DEFAULT_FILE = "evals.yaml";
+
+/** Reader wall-clock ceiling per question, in seconds. */
+const DEFAULT_TIMEOUT_S = 180;
+
+const isAgentKind = (value: string): value is AgentKind => value in AGENTS;
+
+/**
+ * Launch the interactive agent CLI, translating a missing executable into the
+ * Windows not-found sentinel. Only `ENOENT` means "not installed" — any other
+ * spawn failure (`EACCES`, `EMFILE`, …) must surface as itself.
+ */
+const launchAgentCode = async (
+  bin: string,
+  prompt: string
+): Promise<number> => {
+  try {
+    return await launchAgent(bin, prompt);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      throw error;
+    }
+    return WINDOWS_COMMAND_NOT_FOUND;
+  }
+};
+
+const notInstalled = (agent: AgentKind): never => {
+  const cli = AGENTS[agent];
+  logger.error(
+    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+  );
+  return process.exit(1);
+};
+
+/** The fraction of run (non-skipped) questions that passed. */
+export const passFraction = (result: EvalResult): number => {
+  const ran = result.results.length - result.counts.skip;
+  return ran === 0 ? 1 : result.counts.pass / ran;
+};
+
+interface EvalFlags {
+  action?: string;
+  agent: string;
+  file: string;
+  fix?: boolean;
+  json?: boolean;
+  threshold?: string;
+  timeout?: string;
+}
+
+/** Validate the flag surface, exiting with a message on the first offense. */
+const parseFlags = (
+  args: EvalFlags
+): { agent: AgentKind; threshold: number; timeoutS: number } => {
+  if (!isAgentKind(args.agent)) {
+    logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
+    process.exit(1);
+  }
+  if (args.action !== undefined && args.action !== "init") {
+    logger.error(`Unknown action "${args.action}" (did you mean "init"?).`);
+    process.exit(1);
+  }
+  if (args.json && args.fix) {
+    logger.error("--json and --fix are mutually exclusive.");
+    process.exit(1);
+  }
+  const threshold = args.threshold === undefined ? 1 : Number(args.threshold);
+  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    logger.error(`Invalid --threshold "${args.threshold}" (use 0..1).`);
+    process.exit(1);
+  }
+  const timeoutS =
+    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
+  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
+    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
+    process.exit(1);
+  }
+  return { agent: args.agent, threshold, timeoutS };
+};
+
+/** `blume eval --fix`: hand the failing report to the interactive agent. */
+const runFixHandoff = async (
+  agent: AgentKind,
+  result: EvalResult,
+  root: string,
+  threshold: number
+): Promise<void> => {
+  const count = result.counts.fail + result.counts.error;
+  if (count === 0) {
+    return;
+  }
+  const cli = AGENTS[agent];
+  const report = await writeEvalReport(result, root, threshold);
+  process.stderr.write(
+    `  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
+  );
+  const code = await launchAgentCode(cli.bin, evalFixPrompt(report));
+  if (code === WINDOWS_COMMAND_NOT_FOUND) {
+    notInstalled(agent);
+  }
+  if (code !== 0) {
+    process.exit(code);
+  }
+};
+
+/** `blume eval init`: draft a starter evals file via the interactive agent. */
+const runInit = async (agent: AgentKind, file: string): Promise<void> => {
+  const path = join(process.cwd(), file);
+  if (existsSync(path)) {
+    logger.error(
+      `${file} already exists — edit it directly, or pass --file to draft elsewhere.`
+    );
+    process.exit(1);
+  }
+  const code = await launchAgentCode(AGENTS[agent].bin, initPrompt(file));
+  if (code === WINDOWS_COMMAND_NOT_FOUND) {
+    notInstalled(agent);
+  }
+  if (code !== 0) {
+    process.exit(code);
+  }
+};
+
+export const evalCommand = defineCommand({
+  args: {
+    action: {
+      description: 'Optional action: "init" drafts a starter evals file.',
+      required: false,
+      type: "positional",
+    },
+    agent: {
+      default: "claude",
+      description: "Agent CLI that reads and grades the docs: claude | codex.",
+      type: "string",
+    },
+    file: {
+      default: DEFAULT_FILE,
+      description: "The evals file to run.",
+      type: "string",
+    },
+    fix: {
+      description:
+        "After a failing run, hand the report to the agent to fix the docs interactively.",
+      type: "boolean",
+    },
+    json: {
+      description: "Emit the report as JSON on stdout (for CI/editors).",
+      type: "boolean",
+    },
+    threshold: {
+      description:
+        "Minimum passing fraction (0..1) before the run exits non-zero. Defaults to 1.",
+      type: "string",
+    },
+    timeout: {
+      description: `Reader time limit per question, in seconds. Defaults to ${DEFAULT_TIMEOUT_S}.`,
+      type: "string",
+    },
+    verbose: {
+      description: "Include the reader's full answer under each failure.",
+      type: "boolean",
+    },
+  },
+  meta: {
+    description:
+      "Test the docs: an agent answers your questions using only the documentation.",
+    name: "eval",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const { agent, threshold, timeoutS } = parseFlags(args);
+    if (args.action === "init") {
+      await runInit(agent, args.file);
+      return;
+    }
+
+    let result: EvalResult;
+    try {
+      // `scanProject`, not `prepareProject`: the eval reads the content tree
+      // and never regenerates the runtime, so it doesn't contend with a
+      // running dev server. Same reasoning as `blume audit`.
+      const project = await scanProject(root, { mode: "build" });
+      const evalsPath = join(root, args.file);
+      const { evals, raw } = await loadEvalsFile(evalsPath);
+
+      process.stderr.write(`${headerLine(evals.questions.length, agent)}\n\n`);
+      result = await runEval({
+        agent,
+        evals,
+        evalsPath,
+        onProgress: (event) => {
+          // Straight to stderr, not `logger.info` — consola drops info-level
+          // lines in test and CI environments.
+          if (event.kind === "question-start") {
+            process.stderr.write(
+              `${startLine(event.id, event.index, event.total)}\n`
+            );
+            return;
+          }
+          const lines = [
+            questionLine(event.result),
+            ...questionDetails(event.result, Boolean(args.verbose)),
+          ];
+          process.stderr.write(`${lines.join("\n")}\n`);
+        },
+        project,
+        rawEvals: raw,
+        readerTimeoutMs: timeoutS * 1000,
+      });
+    } catch (error) {
+      if (error instanceof EvalsFileError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+        notInstalled(agent);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+
+    const tail = [
+      "",
+      ...warningLines(result, root),
+      ...fixLines(result, root),
+      "",
+      `  ${summaryLine(result)}`,
+      "",
+    ];
+    process.stderr.write(tail.join("\n"));
+
+    const failed = passFraction(result) < threshold;
+
+    if (args.fix) {
+      // The gate is a CI concern; a handoff run succeeds when the agent
+      // session does, not when the docs already passed.
+      await runFixHandoff(agent, result, root, threshold);
+      return;
+    }
+
+    if (args.json) {
+      process.stdout.write(evalReportJson(result, root, threshold));
+      if (failed) {
+        // `process.exit` doesn't flush a piped stdout — without this the JSON
+        // is truncated mid-write in exactly the CI setups that consume it.
+        await flushStdout();
+        process.exit(1);
+      }
+      return;
+    }
+
+    if (failed) {
+      process.exit(1);
+    }
+  },
+});

package/src/cli/commands/init.ts

@@ -157,10 +157,15 @@ export const initCommand = defineCommand({
     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/"]);
+    // Keep installed dependencies, 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, [
+      "node_modules/",
+      ".blume/",
+      "dist/",
+    ]);
     if (ignored.length > 0) {
       sink.success(`Added ${ignored.join(", ")} to .gitignore`);
     }

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

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+
+import { defineCommand } from "citty";
+
+import type { McpData } from "../../ai/mcp/data.ts";
+import { serveMcpStdio } from "../../ai/mcp/stdio.ts";
+
+export const mcpStdioCommand = defineCommand({
+  args: {
+    data: {
+      description: "Path to a serialized MCP data snapshot (JSON).",
+      required: true,
+      type: "string",
+    },
+  },
+  meta: {
+    description:
+      "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
+    name: "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.
+    let data: McpData;
+    try {
+      data = JSON.parse(await readFile(args.data, "utf-8")) as McpData;
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      process.stderr.write(
+        `blume mcp-stdio: cannot load the snapshot at ${args.data}: ${detail}\n`
+      );
+      process.exit(1);
+    }
+    await serveMcpStdio(data);
+  },
+});