blume 1.4.2 → 1.5.0

package/src/cli/commands/build.ts

@@ -54,7 +54,7 @@ import {
   platformRedirects,
 } from "../../deploy/redirects.ts";
 import { buildRobots } from "../../deploy/robots.ts";
-import { buildSitemap } from "../../deploy/sitemap.ts";
+import { buildSitemapFiles } from "../../deploy/sitemap.ts";
 import { injectNegotiationRoutes } from "../../deploy/vercel-negotiation.ts";
 import { buildSearchIndex } from "../../search/build.ts";
 import { syncSearchProvider } from "../../search/sync/index.ts";
@@ -64,6 +64,9 @@ import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+const isAdapter = (value: string): value is (typeof ADAPTERS)[number] =>
+  ADAPTERS.some((adapter) => adapter === value);
+
 const BUDGET_JS = "budget-js";
 const BUDGET_CSS = "budget-css";
 
@@ -295,14 +298,13 @@ const emitVercelNegotiation = async (
   if (!existsSync(configPath)) {
     return;
   }
-  const overrides: Record<string, string> = {
-    ...(hasApiCatalog(config)
-      ? { [API_CATALOG_PATH.slice(1)]: API_CATALOG_TYPE }
-      : {}),
-    ...(config.ai.webBotAuth.keys.length > 0
-      ? { [SIGNATURES_DIRECTORY_PATH.slice(1)]: SIGNATURES_DIRECTORY_TYPE }
-      : {}),
-  };
+  const overrides: Record<string, string> = {};
+  if (hasApiCatalog(config)) {
+    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+  }
+  if (config.ai.webBotAuth.keys.length > 0) {
+    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+  }
   // The homepage rewrite serves `/index.md` from the static layer, so its
   // `x-markdown-tokens` estimate has to ride the routing config; the runtime
   // endpoint stamps it on dev/server-rendered responses itself.
@@ -616,10 +618,18 @@ const publishBuildArtifacts = async (
   }
 
   // A user's own public/ file (copied into dist by Astro) always wins.
-  const sitemap = buildSitemap(project);
-  if (sitemap && !existsSync(join(distDir, "sitemap.xml"))) {
-    await writeFile(join(distDir, "sitemap.xml"), sitemap, "utf-8");
-    logger.success("Generated sitemap.xml");
+  const sitemapFiles = buildSitemapFiles(project);
+  if (sitemapFiles && !existsSync(join(distDir, "sitemap.xml"))) {
+    await Promise.all(
+      sitemapFiles.map((file) =>
+        writeFile(join(distDir, file.name), file.xml, "utf-8")
+      )
+    );
+    logger.success(
+      sitemapFiles.length === 1
+        ? "Generated sitemap.xml"
+        : `Generated sitemap.xml (index of ${sitemapFiles.length - 1} sitemap files)`
+    );
   }
 
   const robots = buildRobots(project);
@@ -649,7 +659,7 @@ const publishBuildArtifacts = async (
 
   const { config } = project;
   const features = serverFeatures(config);
-  // `buildSitemap` returns null both when the sitemap is disabled and when no
+  // `buildSitemapFiles` returns null both when the sitemap is disabled and when no
   // `site` is configured — only the latter deserves the remediation hint.
   const sitemapNote = config.seo.sitemap
     ? "no (set deployment.site)"
@@ -661,7 +671,7 @@ const publishBuildArtifacts = async (
       `Site       ${config.deployment.site ?? "not set"}`,
       `Search     ${config.search.provider}`,
       `Redirects  ${config.redirects.length}`,
-      `Sitemap    ${sitemap ? "yes" : sitemapNote}`,
+      `Sitemap    ${sitemapFiles ? "yes" : sitemapNote}`,
       `Robots     ${robots ? "yes" : "no"}`,
       `Agent JSON ${agentReadability ? "yes" : "no"}`,
       `LLM files  ${config.ai.llmsTxt.enabled ? "yes" : "no"}`,
@@ -746,7 +756,7 @@ export const buildCommand = defineCommand({
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
     }
-    if (args.adapter && !ADAPTERS.includes(args.adapter as never)) {
+    if (args.adapter && !isAdapter(args.adapter)) {
       logger.error(
         `Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`
       );
@@ -757,8 +767,12 @@ export const buildCommand = defineCommand({
     const project = await prepareProject({
       mode: "build",
       overrides: {
+        // SAFETY: an invalid --adapter exited above; a set flag is an ADAPTERS
+        // member.
         adapter: args.adapter as (typeof ADAPTERS)[number] | undefined,
         base: args.base,
+        // SAFETY: an invalid --output exited above; a set flag is static or
+        // server.
         output: args.output as "server" | "static" | undefined,
       },
       preview: args.preview,

package/src/cli/commands/dev.ts

@@ -1,13 +1,13 @@
 import { dev } from "astro";
 import { watch } from "chokidar";
 import { defineCommand } from "citty";
+import { debounce } from "perfect-debounce";
 
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
-import { coalescedRunner } from "../coalesce.ts";
 import {
   acquireDevLock,
   describeDevLock,
@@ -146,10 +146,16 @@ export const devCommand = defineCommand({
     // watcher misses directory renames, so a renamed page 404s (`getEntry` reads
     // a stale in-memory store) until the server is restarted. We restart it
     // ourselves — stop, regenerate while down (no watcher races), then bring up
-    // a fresh container whose cold sync re-globs everything. `coalescedRunner`
-    // single-flights the scan so a burst of watch events can never stack
-    // overlapping regenerations (piled-up scans exhaust the heap).
-    const runRegenerate = coalescedRunner(async () => {
+    // a fresh container whose cold sync re-globs everything. perfect-debounce
+    // both debounces the watch burst (80ms) and single-flights the scan: a
+    // trigger during a run never starts a second run, only marks one trailing
+    // rerun after the current settles. Both halves are load-bearing — a plain
+    // debounce once let bursts stack overlapping scans until the heap was
+    // exhausted (observed as an OOM after minutes of looping). The contract is
+    // pinned by test/dev-debounce.test.ts. The task must not reject (the
+    // library re-invokes it from an unhandled .finally), so the body catches
+    // its own errors and always resolves.
+    const regenerate = debounce(async () => {
       try {
         const next = await scanProject(root, {
           devServerUrl,
@@ -179,23 +185,17 @@ export const devCommand = defineCommand({
         reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {
+        // SAFETY: regeneration failures come from the generator and Astro's
+        // server API, which raise Error instances; only the message is shown.
         logger.error(`Regeneration failed: ${(error as Error).message}`);
       }
-    });
-
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    const regenerate = () => {
-      if (timer) {
-        clearTimeout(timer);
-      }
-      timer = setTimeout(runRegenerate, 80);
-    };
+    }, 80);
 
     // The runtime prepared above baked the *requested* port into the site
     // fallback; if Vite bumped it, regenerate so OG images, canonicals, and
     // other site-gated URLs point at the port actually serving.
     if (boundPort !== port) {
-      void runRegenerate();
+      void regenerate();
     }
 
     // Content is watched per source (filesystem uses fs.watch; remote sources

package/src/cli/commands/doctor.ts

@@ -23,6 +23,8 @@ const FALLBACK_NODE_RANGE = ">=22.12.0";
  * doctor can never drift from what the package actually declares. */
 const supportedNodeRange = (): string => {
   try {
+    // SAFETY: this parses blume's own package.json; the optional fields cover
+    // an `engines` block going missing, and a bad read falls to the catch.
     const pkg = JSON.parse(
       readFileSync(join(packageRoot(), "package.json"), "utf-8")
     ) as { engines?: { node?: string } };

package/src/cli/commands/eject.ts

@@ -8,7 +8,7 @@ import {
   droppedArtifactNotices,
   updatePackageScripts,
 } from "../eject-scripts.ts";
-import { commandsFor, detectPackageManager } from "../init/scaffold.ts";
+import { commandsFor, detectProjectPackageManager } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
 /**
@@ -76,9 +76,9 @@ export const ejectCommand = defineCommand({
       process.stdout.write(`  ${relative(root, file)}\n`);
     }
     reportDroppedArtifacts(notices);
-    // Print run commands matching the user's package manager, detected the
-    // same way as `blume init`'s next-steps hint.
-    const pm = detectPackageManager(process.env.npm_config_user_agent);
+    // 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);
     logger.box(
       `Your project is now a standalone Astro app.\n\n  ${dev}\n  ${build}\n\nThe blume package remains importable.`

package/src/cli/commands/eval.ts

@@ -3,11 +3,7 @@ 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 { AGENTS, launchAgent } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
@@ -37,32 +33,35 @@ 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.
+ * Launch the interactive agent CLI, turning a missing executable into the
+ * install hint. Only `ENOENT` means "not installed" — any other spawn failure
+ * (`EACCES`, `EMFILE`, …) must surface as itself.
  */
+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);
+};
+
 const launchAgentCode = async (
-  bin: string,
+  agent: AgentKind,
   prompt: string
 ): Promise<number> => {
   try {
-    return await launchAgent(bin, prompt);
+    return await launchAgent(AGENTS[agent].bin, prompt);
   } catch (error) {
+    // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+    // ErrnoException, and any other thrown value fails the comparison and
+    // rethrows unchanged.
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
-    return WINDOWS_COMMAND_NOT_FOUND;
+    return notInstalled(agent);
   }
 };
 
-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;
@@ -80,9 +79,7 @@ interface EvalFlags {
 }
 
 /** Validate the flag surface, exiting with a message on the first offense. */
-const parseFlags = (
-  args: EvalFlags
-): { agent: AgentKind; threshold: number; timeoutS: number } => {
+const parseFlags = (args: EvalFlags) => {
   if (!isAgentKind(args.agent)) {
     logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
     process.exit(1);
@@ -125,10 +122,7 @@ const runFixHandoff = async (
   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);
-  }
+  const code = await launchAgentCode(agent, evalFixPrompt(report));
   if (code !== 0) {
     process.exit(code);
   }
@@ -143,10 +137,7 @@ const runInit = async (agent: AgentKind, file: string): Promise<void> => {
     );
     process.exit(1);
   }
-  const code = await launchAgentCode(AGENTS[agent].bin, initPrompt(file));
-  if (code === WINDOWS_COMMAND_NOT_FOUND) {
-    notInstalled(agent);
-  }
+  const code = await launchAgentCode(agent, initPrompt(file));
   if (code !== 0) {
     process.exit(code);
   }
@@ -247,6 +238,9 @@ export const evalCommand = defineCommand({
         logger.error(error.diagnostic.message);
         process.exit(1);
       }
+      // SAFETY: only the `code` tag is inspected; a spawn failure throws an
+      // ErrnoException, and any other thrown value fails the comparison and
+      // falls through to the internal-error report.
       if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
         notInstalled(agent);
       }

package/src/cli/commands/init.ts

@@ -16,11 +16,7 @@ import {
   TEMPLATES,
   validateContentDir,
 } from "../init/scaffold.ts";
-import type {
-  InitAnswers,
-  PackageManager,
-  Template,
-} from "../init/scaffold.ts";
+import type { InitAnswers } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
 /**
@@ -45,6 +41,8 @@ const ejectScaffold = async (
     const steps = [...cd, commands.install, commands.dev];
     logger.box(`Next steps:\n\n  ${steps.join("\n  ")}\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}`
     );
@@ -93,15 +91,17 @@ export const initCommand = defineCommand({
   async run({ args }) {
     const cwd = process.cwd();
 
-    const template = args.template as Template | undefined;
-    if (template !== undefined && !TEMPLATES.includes(template)) {
+    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 = args["package-manager"] as PackageManager | undefined;
-    if (pm !== undefined && !PACKAGE_MANAGERS.includes(pm)) {
+    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(" | ")}).`
       );

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

@@ -23,6 +23,9 @@ export const mcpStdioCommand = defineCommand({
     // must go to stderr or the MCP client chokes on the stray line.
     let data: McpData;
     try {
+      // SAFETY: the snapshot is written by `blume eval` itself as
+      // JSON.stringify of an McpData; a hand-mangled file fails the parse and
+      // lands in the catch below.
       data = JSON.parse(await readFile(args.data, "utf-8")) as McpData;
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);

package/src/cli/commands/translate.ts

@@ -47,10 +47,17 @@ interface TranslateFlags {
   timeout?: string;
 }
 
+/** The validated flag surface `parseFlags` hands the command body. */
+interface ParsedTranslateFlags {
+  agent: AgentKind | undefined;
+  concurrency: number;
+  timeoutS: number;
+}
+
 /** Validate the flag surface, exiting with a message on the first offense. */
-const parseFlags = (
-  args: TranslateFlags
-): { agent: AgentKind | undefined; concurrency: number; timeoutS: number } => {
+const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
+  // SAFETY: Object.keys of the AGENTS table returns exactly its declared
+  // AgentKind keys.
   const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
     (kind) => args[kind]
   );
@@ -227,6 +234,8 @@ export const translateCommand = defineCommand({
         return;
       }
 
+      // SAFETY: parseFlags exits unless --check was passed or exactly one
+      // agent flag was; on this non-check path the agent is therefore set.
       const kind = agent as AgentKind;
       process.stderr.write(
         `${translateHeaderLine(workList.items.length, workList.targetLocales.length, kind)}\n\n`
@@ -290,6 +299,8 @@ export const translateCommand = defineCommand({
         logger.error(error.diagnostic.message);
         process.exit(1);
       }
+      // SAFETY: an ENOENT from spawning the agent CLI is an ErrnoException;
+      // any other thrown shape reads `code` as undefined and falls through.
       if ((error as NodeJS.ErrnoException)?.code === "ENOENT" && agent) {
         notInstalled(agent);
       }

package/src/cli/commands/version.ts

@@ -0,0 +1,85 @@
+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 { reportInternalError } from "../internal-error.ts";
+import { logger } from "../log.ts";
+
+export const versionCommand = defineCommand({
+  args: {
+    force: {
+      description: "Overwrite an existing snapshot directory.",
+      type: "boolean",
+    },
+    id: {
+      description: 'Version id to cut (e.g. "v1.0").',
+      required: false,
+      type: "positional",
+    },
+  },
+  meta: {
+    description: "Freeze the current docs as an archived version.",
+    name: "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`
+        );
+      } else if (result.configSnippet) {
+        logger.info(result.configSnippet);
+      }
+      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);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});

package/src/cli/dev-lock.ts

@@ -29,15 +29,32 @@ export interface DevLockInfo {
 
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
-const isValidPid = (pid: unknown): pid is number =>
+/** What `JSON.parse` can yield for a lock file body. */
+type LockFileValue =
+  | string
+  | number
+  | boolean
+  | null
+  | LockFileValue[]
+  | { [key: string]: LockFileValue };
+
+const isValidPid = (pid: LockFileValue | undefined): pid is number =>
   typeof pid === "number" && Number.isInteger(pid) && pid > 0;
 
+const isPortNumber = (port: LockFileValue | undefined): port is number =>
+  typeof port === "number";
+
+const isLockRecord = (
+  data: LockFileValue
+): data is { pid?: LockFileValue; port?: LockFileValue } =>
+  typeof data === "object" && data !== null;
+
 /**
  * Parse a lock file body. Current locks are JSON (`{"pid":123,"port":3001}`);
  * a bare integer (the pre-port format) still parses as a pid-only lock.
  */
 const parseLock = (raw: string): DevLockInfo | null => {
-  let data: unknown;
+  let data: LockFileValue;
   try {
     data = JSON.parse(raw.trim());
   } catch {
@@ -46,10 +63,10 @@ const parseLock = (raw: string): DevLockInfo | null => {
   if (isValidPid(data)) {
     return { pid: data };
   }
-  if (typeof data === "object" && data !== null) {
-    const { pid, port } = data as { pid?: unknown; port?: unknown };
+  if (isLockRecord(data)) {
+    const { pid, port } = data;
     if (isValidPid(pid)) {
-      return typeof port === "number" ? { pid, port } : { pid };
+      return isPortNumber(port) ? { pid, port } : { pid };
     }
   }
   return null;
@@ -63,6 +80,7 @@ const isProcessAlive = (pid: number): boolean => {
   } catch (error) {
     // EPERM means the process exists but belongs to another user — still
     // live, so the lock must hold (only ESRCH proves it's gone).
+    // SAFETY: `process.kill` failures are errno exceptions.
     return (error as NodeJS.ErrnoException).code === "EPERM";
   }
 };
@@ -84,11 +102,13 @@ export const readDevLock = (outDir: string): DevLockInfo | null => {
 export const isDevLocked = (outDir: string): boolean =>
   readDevLock(outDir) !== null;
 
-const lockPayload = (port?: number): string =>
-  JSON.stringify({
-    pid: process.pid,
-    ...(port === undefined ? {} : { port }),
-  });
+const lockPayload = (port?: number): string => {
+  const info: DevLockInfo = { pid: process.pid };
+  if (port !== undefined) {
+    info.port = port;
+  }
+  return JSON.stringify(info);
+};
 
 const writeLock = (outDir: string, port?: number): void => {
   writeFileSync(lockPath(outDir), lockPayload(port));
@@ -128,6 +148,7 @@ const tryClaimLock = (outDir: string, port?: number): boolean => {
     writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
     return true;
   } catch (error) {
+    // SAFETY: `writeFileSync` failures are errno exceptions.
     if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
       throw error;
     }

package/src/cli/eject-scripts.ts

@@ -5,6 +5,21 @@ import { join } from "pathe";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 
+/** A JSON value, as `JSON.parse` of a manifest can return. */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** The slice of package.json the rewrite touches; the rest rides along. */
+interface PackageManifest {
+  [key: string]: JsonValue | undefined;
+  scripts?: Record<string, string>;
+}
+
 /**
  * The `blume build`-only artifacts this project's config actually produces, as
  * notice lines for the eject command. After an eject the build script runs
@@ -55,13 +70,13 @@ export const droppedArtifactNotices = (config: ResolvedConfig): string[] => {
  */
 export const updatePackageScripts = async (root: string): Promise<void> => {
   const pkgPath = join(root, "package.json");
-  let pkg: Record<string, unknown>;
+  let pkg: PackageManifest;
   try {
     pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
   } catch {
     return;
   }
-  const scripts = (pkg.scripts ?? {}) as Record<string, string>;
+  const scripts = pkg.scripts ?? {};
   pkg.scripts = {
     ...scripts,
     build: "astro build",

package/src/cli/env.ts

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 
-import { parse } from "dotenv";
+import { config } from "dotenv";
 import { dirname, join, resolve } from "pathe";
 
 // Blume's remote sources (GitHub Releases, mdx-remote, Sanity, Notion…) read
@@ -9,44 +9,27 @@ import { dirname, join, resolve } from "pathe";
 // that gap: it cascades `.env`/`.env.local` from the working dir up to the repo
 // root, so a monorepo can keep one `.env` at the root and every app picks it up.
 
-/** Apply parsed vars without clobbering anything already in `process.env`. */
-const applyEnv = (parsed: Record<string, string>): void => {
-  for (const [key, value] of Object.entries(parsed)) {
-    if (!(key in process.env)) {
-      process.env[key] = value;
-    }
-  }
-};
-
-const loadFile = (path: string): void => {
-  try {
-    if (existsSync(path)) {
-      // dotenv is the same parser Vite runs over these files at build time,
-      // so a value means the same thing to the pre-boot content scan and the
-      // built site — including multi-line double-quoted values (PEM keys),
-      // which a line-based parser silently truncates.
-      applyEnv(parse(readFileSync(path, "utf-8")));
-    }
-  } catch {
-    // Env files are best-effort; a read/parse failure must not abort a build.
-  }
-};
-
 /**
  * Load `.env`/`.env.local`, cascading from `startDir` up to the repository root
- * (the first ancestor containing a `.git`) or the filesystem root. Nearer files
- * and existing `process.env` values win, so shell/CI overrides are never lost
- * and `.env.local` layers over `.env`.
+ * (the first ancestor containing a `.git`) or the filesystem root. The ordered
+ * path list is handed to dotenv, whose `config` is first-wins, never clobbers
+ * existing `process.env` values, and treats unreadable files as best-effort —
+ * so shell/CI overrides are never lost, `.env.local` layers over `.env`, and a
+ * bad file never aborts a build. dotenv is also the parser Vite runs over
+ * these files at build time, so a value means the same thing to the pre-boot
+ * content scan and the built site — including multi-line double-quoted values
+ * (PEM keys), which a line-based parser silently truncates.
  */
 export const loadEnvFiles = (startDir: string): void => {
+  const paths: string[] = [];
   let dir = resolve(startDir);
   let done = false;
   while (!done) {
-    loadFile(join(dir, ".env.local"));
-    loadFile(join(dir, ".env"));
+    paths.push(join(dir, ".env.local"), join(dir, ".env"));
     const parent = dirname(dir);
     // Stop at the repo root (nearest `.git`) or the filesystem root.
     done = existsSync(join(dir, ".git")) || parent === dir;
     dir = parent;
   }
+  config({ path: paths, quiet: true });
 };