blume 0.7.0 → 1.0.0

package/src/cli/commands/build.ts

@@ -11,6 +11,7 @@ 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,
@@ -63,7 +64,10 @@ const validateBudgetFlags = (args: BudgetArgs): void => {
 /**
  * Emit platform redirect files for a static build (adapters wire redirects
  * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
- * when the user hasn't shipped one via public/.
+ * when the user hasn't shipped one via public/. Note that Vercel's
+ * git-integration builds read `vercel.json` from the repository root only —
+ * the copy emitted here takes effect when the dist folder itself is deployed
+ * directly via the Vercel CLI.
  */
 const emitRedirectFiles = async (
   config: ResolvedConfig,
@@ -189,11 +193,105 @@ 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);
+  }
+};
+
+/**
+ * Root of an isolated build's output. The runtime-local `dist/`, except for a
+ * Vercel server build, whose deploy bundle lands at `<runtime>/.vercel/output`
+ * and is never surfaced to the project root.
+ */
+export const isolatedOutputDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.outDir, ".vercel", "output");
+  }
+  return context.distDir ?? join(context.outDir, "dist");
+};
+
+/**
+ * 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;
+  const outputDir = isolatedOutputDir(config, context);
+  if (output === "server" && adapter === "vercel") {
+    return join(outputDir, "static");
+  }
+  if (output === "server" && adapter === "node") {
+    return join(outputDir, "client");
+  }
+  return outputDir;
+};
+
+/**
+ * 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,
@@ -214,13 +312,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.
@@ -253,6 +346,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}`,
@@ -260,21 +358,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}`);
 };
@@ -330,7 +422,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/"]);
     }
@@ -369,15 +461,20 @@ export const buildCommand = defineCommand({
       root: project.context.outDir,
     });
 
-    const distDir = project.context.distDir ?? join(root, "dist");
-
     // 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).`
+        `Isolated build OK — output at ${isolatedOutputDir(project.config, project.context)} (not published).`
       );
       return;
     }

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,21 @@ 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
@@ -100,13 +112,13 @@ export const devCommand = defineCommand({
 
     // 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 honoured on first
+    // 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: args.host ?? false, open, port: listenPort },
+        server: { host: normalizeHost(args.host), open, port: listenPort },
       });
 
     let server = await createServer(explicitPort, args.open ?? false);
@@ -148,7 +160,6 @@ export const devCommand = defineCommand({
         });
         const nextSignature = routeSignature(next.manifest.routes);
         const structural = nextSignature !== lastSignature;
-        lastSignature = nextSignature;
         if (structural) {
           await server.stop();
           await generateRuntime(next);
@@ -156,7 +167,17 @@ export const devCommand = defineCommand({
         } else {
           await generateRuntime(next);
         }
-        // Surface any content/config errors in the browser overlay too.
+        // 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/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.`
     );
   },
 });