blume 0.6.7 → 0.8.0

package/src/cli/commands/build.ts

@@ -11,11 +11,13 @@ import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
+import type { ProjectContext } from "../../core/types.ts";
 import {
   deployStaticDir,
   surfaceAdapterOutput,
 } from "../../deploy/adapter-output.ts";
 import {
+  applyBaseToRedirects,
   buildNetlifyRedirects,
   buildRedirectManifest,
   buildVercelConfig,
@@ -30,18 +32,27 @@ import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+const BUDGET_JS = "budget-js";
+const BUDGET_CSS = "budget-css";
+
+interface BudgetArgs {
+  "budget-css"?: string;
+  "budget-js"?: string;
+}
+
 /**
  * Reject a non-numeric performance budget. `Number("250kb")` is `NaN` and
  * `total > NaN` is always false, so a typo'd flag would silently pass the gate;
  * fail up front instead.
  */
-const validateBudgetFlags = (args: {
-  "budget-css"?: string;
-  "budget-js"?: string;
-}): void => {
-  for (const flag of ["budget-js", "budget-css"] as const) {
+const validateBudgetFlags = (args: BudgetArgs): void => {
+  for (const flag of [BUDGET_JS, BUDGET_CSS] as const) {
     const value = args[flag];
-    if (value !== undefined && !(Number(value) > 0)) {
+    const parsed = Number(value);
+    // Equivalent to `!(parsed > 0)` but without the inverted check: this must
+    // also reject `NaN` (a typo'd flag like "250kb"), which `parsed <= 0` alone
+    // would let through since `NaN <= 0` is false.
+    if (value !== undefined && (Number.isNaN(parsed) || parsed <= 0)) {
       logger.error(
         `Invalid --${flag} "${value}" (expected a positive number of kB).`
       );
@@ -59,7 +70,7 @@ const emitRedirectFiles = async (
   config: ResolvedConfig,
   distDir: string
 ): Promise<void> => {
-  const { redirects } = config;
+  const redirects = applyBaseToRedirects(config.redirects, config.basePath);
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
@@ -82,10 +93,13 @@ const emitRedirectFiles = async (
   logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 
-const formatBytes = (bytes: number): string =>
-  bytes < 1024
-    ? `${bytes} B`
-    : `${(bytes / 1024).toFixed(bytes < 1024 * 100 ? 1 : 0)} kB`;
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const digits = bytes < 1024 * 100 ? 1 : 0;
+  return `${(bytes / 1024).toFixed(digits)} kB`;
+};
 
 /** Sizes of `dist/_astro/*.<ext>`, largest first (empty when none exist). */
 const astroAssets = async (
@@ -144,14 +158,14 @@ const reportBundleSizes = async (distDir: string): Promise<void> => {
  */
 const enforceBudget = async (
   distDir: string,
-  args: { "budget-css"?: string; "budget-js"?: string }
+  args: BudgetArgs
 ): Promise<"fail" | "pass" | "skip"> => {
   const checks: { ext: string; limitKb: number; name: string }[] = [
-    ...(args["budget-js"]
-      ? [{ ext: "js", limitKb: Number(args["budget-js"]), name: "JavaScript" }]
+    ...(args[BUDGET_JS]
+      ? [{ ext: "js", limitKb: Number(args[BUDGET_JS]), name: "JavaScript" }]
       : []),
-    ...(args["budget-css"]
-      ? [{ ext: "css", limitKb: Number(args["budget-css"]), name: "CSS" }]
+    ...(args[BUDGET_CSS]
+      ? [{ ext: "css", limitKb: Number(args[BUDGET_CSS]), name: "CSS" }]
       : []),
   ];
   if (checks.length === 0) {
@@ -176,16 +190,94 @@ const enforceBudget = async (
   return passed ? "pass" : "fail";
 };
 
+/**
+ * Run the optional bundle report (`--analyze`) and performance-budget gate
+ * against the directory whose `_astro/` client assets the deploy serves.
+ * Shared by real and isolated builds — an isolated CI run passing
+ * `--budget-js` must still fail on an exceeded budget rather than silently
+ * skipping the check. Exits non-zero when a budget is exceeded.
+ */
+export const runClientAssetChecks = async (
+  staticDir: string,
+  args: { analyze?: boolean } & BudgetArgs
+): Promise<void> => {
+  if (args.analyze) {
+    await reportBundleSizes(staticDir);
+  }
+  if ((await enforceBudget(staticDir, args)) === "fail") {
+    process.exit(1);
+  }
+};
+
+/**
+ * Directory holding an isolated build's client `_astro/` assets. Mirrors
+ * `deployStaticDir`, except that an isolated build never surfaces the adapter
+ * bundle to the project root — a Vercel server build's static output stays at
+ * `<runtime>/.vercel/output/static`, where `deployStaticDir` would instead
+ * point at the project-root copy (a previous real build's assets, or nothing).
+ */
+export const isolatedStaticDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.outDir, ".vercel", "output", "static");
+  }
+  const dist = context.distDir ?? join(context.outDir, "dist");
+  if (output === "server" && adapter === "node") {
+    return join(dist, "client");
+  }
+  return dist;
+};
+
+/**
+ * Generate `llms.txt`/`llms-full.txt` into the dist dir. A user's own file in
+ * `public/` (copied into dist by Astro before this runs, like the sitemap and
+ * robots.txt) wins over the generated one — each file is checked and replaced
+ * independently, so a custom `llms.txt` still gets a generated `llms-full.txt`.
+ */
+const publishLlmsFiles = async (
+  project: BlumeProject,
+  distDir: string
+): Promise<void> => {
+  const indexPath = join(distDir, "llms.txt");
+  const fullPath = join(distDir, "llms-full.txt");
+  const writeIndex = !existsSync(indexPath);
+  const writeFull = !existsSync(fullPath);
+  if (!(writeIndex || writeFull)) {
+    return;
+  }
+  const { index, full } = await buildLlmsFiles(project);
+  const writes: Promise<void>[] = [];
+  if (writeIndex) {
+    writes.push(writeFile(indexPath, index, "utf-8"));
+  }
+  if (writeFull) {
+    writes.push(writeFile(fullPath, full, "utf-8"));
+  }
+  await Promise.all(writes);
+  logger.success(
+    `Generated ${[
+      writeIndex ? "llms.txt" : null,
+      writeFull ? "llms-full.txt" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ")}`
+  );
+};
+
 /**
  * Run every deploy post-step of a real (non-isolated) build: the search index +
  * hosted-provider sync, llms.txt, sitemap/robots, redirect files, the summary
  * box, and the optional bundle report / budget gate. Exits non-zero if a budget
- * is exceeded. Isolated verify builds skip all of this.
+ * is exceeded. Isolated verify builds skip all of this except the bundle
+ * report / budget gate, which they run against their own output.
  */
 const publishBuildArtifacts = async (
   project: BlumeProject,
   distDir: string,
-  args: { analyze?: boolean; "budget-css"?: string; "budget-js"?: string }
+  args: { analyze?: boolean } & BudgetArgs
 ): Promise<void> => {
   if (project.config.search.provider === "pagefind") {
     logger.start("Building search index");
@@ -201,13 +293,8 @@ const publishBuildArtifacts = async (
     warn: (message) => logger.warn(message),
   });
 
-  if (project.config.ai.llmsTxt) {
-    const { index, full } = await buildLlmsFiles(project);
-    await Promise.all([
-      writeFile(join(distDir, "llms.txt"), index, "utf-8"),
-      writeFile(join(distDir, "llms-full.txt"), full, "utf-8"),
-    ]);
-    logger.success("Generated llms.txt and llms-full.txt");
+  if (project.config.ai.llmsTxt.enabled) {
+    await publishLlmsFiles(project, distDir);
   }
 
   // A user's own public/ file (copied into dist by Astro) always wins.
@@ -240,6 +327,11 @@ const publishBuildArtifacts = async (
 
   const { config } = project;
   const features = serverFeatures(config);
+  // `buildSitemap` 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)"
+    : "no (seo.sitemap is false)";
   logger.box(
     [
       `Output     ${config.deployment.output}`,
@@ -247,21 +339,15 @@ const publishBuildArtifacts = async (
       `Site       ${config.deployment.site ?? "not set"}`,
       `Search     ${config.search.provider}`,
       `Redirects  ${config.redirects.length}`,
-      `Sitemap    ${sitemap ? "yes" : "no (set deployment.site)"}`,
+      `Sitemap    ${sitemap ? "yes" : sitemapNote}`,
       `Robots     ${robots ? "yes" : "no"}`,
       `Agent JSON ${agentReadability ? "yes" : "no"}`,
-      `LLM files  ${config.ai.llmsTxt ? "yes" : "no"}`,
+      `LLM files  ${config.ai.llmsTxt.enabled ? "yes" : "no"}`,
       `Server features  ${features.length > 0 ? features.join(", ") : "none"}`,
     ].join("\n")
   );
 
-  if (args.analyze) {
-    await reportBundleSizes(distDir);
-  }
-
-  if ((await enforceBudget(distDir, args)) === "fail") {
-    process.exit(1);
-  }
+  await runClientAssetChecks(distDir, args);
 
   logger.success(`Built to ${distDir}`);
 };
@@ -280,11 +366,11 @@ export const buildCommand = defineCommand({
       description: "Base path the site is served under (e.g. /docs).",
       type: "string",
     },
-    "budget-css": {
+    [BUDGET_CSS]: {
       description: "Fail if total client CSS exceeds this many kB.",
       type: "string",
     },
-    "budget-js": {
+    [BUDGET_JS]: {
       description: "Fail if total client JavaScript exceeds this many kB.",
       type: "string",
     },
@@ -317,7 +403,7 @@ export const buildCommand = defineCommand({
     const runtimeDir = args.isolated
       ? ".blume-verify"
       : process.env.BLUME_RUNTIME_DIR;
-    refuseIfDevRunning(root, "building", runtimeDir);
+    refuseIfDevRunning(root, "building", { isolatedHint: true, runtimeDir });
     if (args.isolated) {
       await ensureGitignore(root, [".blume-verify/"]);
     }
@@ -361,8 +447,15 @@ export const buildCommand = defineCommand({
     // An isolated build is a throwaway verify: it only needs to confirm the site
     // compiles and renders. Skip the network post-steps (search sync) and
     // deploy artifacts (index/llms/sitemap/robots/redirects) that only matter
-    // for a real publish and would push to hosted providers.
+    // for a real publish and would push to hosted providers. The bundle report
+    // and budget gate still run, though — `blume build --isolated --budget-js
+    // 100` exiting 0 without measuring anything would be a silent false pass
+    // in CI.
     if (runtimeDir) {
+      await runClientAssetChecks(
+        isolatedStaticDir(project.config, project.context),
+        args
+      );
       logger.success(
         `Isolated build OK — output at ${distDir} (not published).`
       );

package/src/cli/commands/check.ts

@@ -39,7 +39,7 @@ export const checkCommand = defineCommand({
     const runtimeDir = args.isolated
       ? ".blume-verify"
       : process.env.BLUME_RUNTIME_DIR;
-    refuseIfDevRunning(root, "checking", runtimeDir);
+    refuseIfDevRunning(root, "checking", { isolatedHint: true, runtimeDir });
     if (args.isolated) {
       await ensureGitignore(root, [".blume-verify/"]);
     }

package/src/cli/commands/dev.ts

@@ -15,9 +15,35 @@ import {
   DevLockHeldError,
   updateDevLockPort,
 } from "../dev-lock.ts";
-import { logger } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
+/**
+ * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
+ * citty (0.1) has no mixed string/boolean arg type, so `host` is declared as a
+ * string and a bare `--host` parses as `""` — Node would bind all interfaces
+ * for `""`, but Vite's `resolveHostname` treats it as a literal hostname and
+ * prints malformed URLs like `http://:4321/`. Match Astro's own `--host`
+ * semantics instead: bare flag → `true` (bind all interfaces), `--host
+ * 10.0.0.1` → that address, absent → `false` (localhost only).
+ */
+export const normalizeHost = (host: string | undefined): boolean | string =>
+  host === "" ? true : (host ?? false);
+
+/**
+ * A fingerprint of the route set: the sorted `path entryId` pairs. It changes
+ * when a page is added, removed, or renamed (a folder rename shifts many at
+ * once) but stays equal across pure body edits — so the dev loop can tell a
+ * "structural" change (needs a cold restart) from a hot-reloadable one.
+ */
+const routeSignature = (
+  routes: readonly { entryId: string; path: string }[]
+): string =>
+  routes
+    .map((route) => `${route.path} ${route.entryId}`)
+    .toSorted()
+    .join("\n");
+
 export const devCommand = defineCommand({
   args: {
     "content-dir": {
@@ -84,15 +110,18 @@ export const devCommand = defineCommand({
       strict: args.strict,
     });
 
-    const server = await dev({
-      logLevel: args.debug ? "debug" : "info",
-      root: project.context.outDir,
-      server: {
-        host: args.host ?? false,
-        open: args.open ?? false,
-        port: explicitPort,
-      },
-    });
+    // A factory so `runRegenerate` can recreate the server on a structural
+    // (route-set) change: only a cold container re-globs Astro's content store,
+    // which its in-place config restart doesn't. `open` is honored on first
+    // boot only — a restart must not reopen the browser.
+    const createServer = (listenPort: number | undefined, open: boolean) =>
+      dev({
+        logLevel: args.debug ? "debug" : "info",
+        root: project.context.outDir,
+        server: { host: normalizeHost(args.host), open, port: listenPort },
+      });
+
+    let server = await createServer(explicitPort, args.open ?? false);
 
     // Vite bumps to the next free port when the default is taken, so record
     // the port the server actually bound — the lock's URL is what a refused
@@ -109,11 +138,18 @@ export const devCommand = defineCommand({
     // (and its HMR channel) is up.
     showBlumeErrorOverlay(project.diagnostics);
 
-    // Watch user inputs and regenerate the runtime data on change. Astro/Vite
-    // hot-reloads the generated data module so nav and routes stay in sync.
-    // `coalescedRunner` single-flights the scan so a burst of watch events can
-    // never stack overlapping regenerations (a large project's scan can outlast
-    // the debounce; piled-up scans exhaust the heap).
+    let lastSignature = routeSignature(project.manifest.routes);
+
+    // Watch user inputs and regenerate the runtime data on change. A body edit
+    // hot-reloads via Vite (fast path). A route-set change instead forces a cold
+    // server restart: Astro's in-place content sync never re-globs on a Blume
+    // route change (it strips `integrations` from its cache digest) and its glob
+    // 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 () => {
       try {
         const next = await scanProject(root, {
@@ -122,8 +158,26 @@ export const devCommand = defineCommand({
           overrides,
           preview,
         });
-        await generateRuntime(next);
-        // Surface any content/config errors in the browser overlay too.
+        const nextSignature = routeSignature(next.manifest.routes);
+        const structural = nextSignature !== lastSignature;
+        if (structural) {
+          await server.stop();
+          await generateRuntime(next);
+          server = await createServer(boundPort, false);
+        } else {
+          await generateRuntime(next);
+        }
+        // Commit the signature only after the (re)generation succeeded. If the
+        // restart above throws mid-sequence, the signature stays stale so the
+        // next watch event retries the structural path — committing early would
+        // route it to the non-structural branch with the server still down.
+        lastSignature = nextSignature;
+        // Surface any content/config errors in the terminal AND the browser
+        // overlay. The terminal report must not be skipped: on a published
+        // install the CLI bundle holds its own copy of the integration module,
+        // separate from the Vite module graph that registers the overlay, so
+        // the overlay call below can be a no-op there.
+        reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {
         logger.error(`Regeneration failed: ${(error as Error).message}`);

package/src/cli/commands/doctor.ts

@@ -34,8 +34,8 @@ const minSupportedNode = (): string => {
 };
 
 const versionBelow = (current: string, minimum: string): boolean => {
-  const a = current.split(".").map((part) => Number.parseInt(part, 10));
-  const b = minimum.split(".").map((part) => Number.parseInt(part, 10));
+  const a = current.split(".").map((part) => Math.trunc(Number(part)));
+  const b = minimum.split(".").map((part) => Math.trunc(Number(part)));
   for (let i = 0; i < 3; i += 1) {
     const delta = (a[i] ?? 0) - (b[i] ?? 0);
     if (delta !== 0) {

package/src/cli/commands/eject.ts

@@ -1,28 +1,32 @@
-import { readFile, writeFile } from "node:fs/promises";
-
 import { defineCommand } from "citty";
-import { join, relative } from "pathe";
+import { relative } from "pathe";
 
+import { loadConfig } from "../../core/config.ts";
 import { eject } from "../../registry/eject.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
+import {
+  droppedArtifactNotices,
+  updatePackageScripts,
+} from "../eject-scripts.ts";
+import { commandsFor, detectPackageManager } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
-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 {
+/**
+ * Warn which `blume build` post-build artifacts the ejected app stops
+ * producing. Printed both at the confirmation (so the decision is informed)
+ * and after `--yes` (so a direct eject still sees it). No-op when the config
+ * activates none of them.
+ */
+const reportDroppedArtifacts = (notices: string[]): void => {
+  if (notices.length === 0) {
     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");
+  logger.warn(
+    [
+      "The ejected build script runs plain `astro build`, which stops producing these `blume build` artifacts:",
+      ...notices.map((notice) => `  - ${notice}`),
+    ].join("\n")
+  );
 };
 
 export const ejectCommand = defineCommand({
@@ -37,23 +41,47 @@ export const ejectCommand = defineCommand({
     const root = process.cwd();
     refuseIfDevRunning(root, "ejecting");
 
+    // Config-aware drop list: only the artifacts this project actually
+    // produces are mentioned (e.g. the Pagefind index only for
+    // `search.provider: "pagefind"`).
+    let notices: string[] = [];
+    try {
+      const { config } = await loadConfig(root);
+      notices = droppedArtifactNotices(config);
+    } catch {
+      // A config that fails to load can't gate the notice; the eject itself
+      // surfaces the load error.
+    }
+
     if (!args.yes) {
       logger.warn(
         "Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched."
       );
+      reportDroppedArtifacts(notices);
       logger.info("Re-run with --yes to proceed.");
       return;
     }
 
-    const files = await eject(root);
+    const { files, warnings } = await eject(root);
     await updatePackageScripts(root);
 
+    // The same surface as the generated-runtime path (prepare.ts): one warn
+    // per generation warning, e.g. a Scalar reference spec that wasn't found.
+    for (const warning of warnings) {
+      logger.warn(warning);
+    }
+
     logger.success(`Ejected ${files.length} file(s):`);
     for (const file of files) {
       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);
+    const { build, dev } = commandsFor(pm);
     logger.box(
-      "Your project is now a standalone Astro app.\n\n  bun run dev\n  bun run build\n\nThe blume package remains importable."
+      `Your project is now a standalone Astro app.\n\n  ${dev}\n  ${build}\n\nThe blume package remains importable.`
     );
   },
 });