blume 1.6.4 → 1.6.6

package/src/cli/commands/build.ts

@@ -1,19 +1,17 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 
 import { build } from "astro";
 import { defineCommand } from "citty";
-import { dirname, join, resolve } from "pathe";
+import { join } from "pathe";
 
-import { buildAgentReadability } from "../../ai/agent-readability.ts";
 import {
   API_CATALOG_PATH,
   API_CATALOG_TYPE,
-  buildApiCatalog,
   hasApiCatalog,
 } from "../../ai/api-catalog.ts";
+import { pageJsonPath } from "../../ai/api/paths.ts";
 import { buildHomeLinkHeader } from "../../ai/link-headers.ts";
-import { buildLlmsFiles } from "../../ai/llms.ts";
 import {
   agentMarkdown,
   buildRawMarkdown,
@@ -21,16 +19,10 @@ import {
   markdownTokenCount,
 } from "../../ai/markdown.ts";
 import {
-  AGENT_SKILLS_DIR,
-  buildSkillsIndex,
-  collectSkills,
-} from "../../ai/skills.ts";
-import type { SkillArtifact } from "../../ai/skills.ts";
-import {
-  buildSignaturesDirectory,
   SIGNATURES_DIRECTORY_PATH,
   SIGNATURES_DIRECTORY_TYPE,
 } from "../../ai/web-bot-auth.ts";
+import { publishBuildProject } from "../../astro/integration.ts";
 import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
@@ -39,7 +31,6 @@ import type { ProjectContext } from "../../core/types.ts";
 import {
   ADAPTER_IGNORE_DIRS,
   deployStaticDir,
-  readsHeaderFiles,
   servesClientSubdir,
   surfaceAdapterOutput,
 } from "../../deploy/adapter-output.ts";
@@ -52,18 +43,9 @@ import {
   blumeDependencyNames,
   functionBundleVerdict,
 } from "../../deploy/function-bundle.ts";
-import { buildNetlifyHeaders } from "../../deploy/headers.ts";
-import {
-  buildNetlifyRedirects,
-  buildRedirectManifest,
-  buildVercelConfig,
-  platformRedirects,
-} from "../../deploy/redirects.ts";
-import { buildRobots } from "../../deploy/robots.ts";
-import { buildSitemapFiles } from "../../deploy/sitemap.ts";
+import { platformRedirects } from "../../deploy/redirects.ts";
 import { injectNegotiationRoutes } from "../../deploy/vercel-negotiation.ts";
-import { buildSearchIndex } from "../../search/build.ts";
-import { syncSearchProvider } from "../../search/sync/index.ts";
+import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
@@ -102,208 +84,6 @@ 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/. 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,
-  distDir: string
-): Promise<void> => {
-  const redirects = platformRedirects(config);
-  if (redirects.length === 0 || config.deployment.output !== "static") {
-    return;
-  }
-  await writeFile(
-    join(distDir, "blume-redirects.json"),
-    buildRedirectManifest(redirects),
-    "utf-8"
-  );
-  const platformFiles = [
-    { content: buildNetlifyRedirects(redirects), name: "_redirects" },
-    { content: buildVercelConfig(redirects), name: "vercel.json" },
-  ];
-  await Promise.all(
-    platformFiles.map((file) =>
-      existsSync(join(distDir, file.name))
-        ? Promise.resolve()
-        : writeFile(join(distDir, file.name), file.content, "utf-8")
-    )
-  );
-  logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
-};
-
-/**
- * Emit a `_headers` file so Netlify / Cloudflare serve the raw AI-ready
- * endpoints (`*.md`, `*.mdx`, `*.txt`) with an explicit `charset=utf-8`. Without
- * it those hosts send `text/markdown` / `text/plain` with no charset and
- * browsers fall back to Windows-1252, garbling any non-ASCII docs (#82).
- *
- * The same file carries the rest of the agent-discovery surface that only a
- * response header can express: the homepage `Link` header (RFC 8288, see
- * `ai/link-headers.ts`), and the registered media types for the extensionless
- * well-known files — `application/linkset+json` for the API catalog, the
- * signatures directory, and the Agent Skills archives. A static host serves
- * those as `octet-stream` or nothing at all without a rule.
- *
- * A `_headers` shipped in `public/` wins, exactly like `_redirects` — the opt-out
- * is checked at its source rather than in `dist`, because on Cloudflare the file
- * in `dist` is not necessarily the user's: `@astrojs/cloudflare` writes its own
- * `_headers` (an immutable `Cache-Control` rule for `/_astro/*`) during the
- * build, before this runs. Testing `dist` therefore read an adapter-generated
- * file as a user opt-out and skipped silently. When both exist, the adapter's
- * rules are preserved and ours are appended.
- *
- * Gated on {@link readsHeaderFiles}, not on `output === "static"`. A **Cloudflare
- * server** build serves `dist/client` through the Worker's ASSETS binding, and
- * Workers static assets honor `_headers` from that directory — so the file
- * applies there too, and skipping it left every Cloudflare server build with no
- * `Link` header and no media type on its own discovery files. The charset half
- * of this file *is* redundant on a server build, because the runtime endpoint
- * sets Content-Type on the Response itself; the `Link` and well-known halves are
- * not, and one conclusion about the first was applied to all three.
- *
- * Exported for the test suite, which exercises it in a subprocess like the
- * other command helpers.
- */
-export const emitHeaderFiles = async (
-  project: BlumeProject,
-  distDir: string
-): Promise<void> => {
-  const { config } = project;
-  if (
-    !readsHeaderFiles(config.deployment) ||
-    existsSync(join(project.context.root, "public", "_headers"))
-  ) {
-    return;
-  }
-  const ours = buildNetlifyHeaders(
-    config,
-    buildHomeLinkHeader(config, markdownRoutePaths(project))
-  );
-  // An adapter may have written its own rules here already (Cloudflare adds an
-  // immutable Cache-Control for /_astro/*). Keep them and append ours: both
-  // sets are wanted, and `_headers` has no merge semantics beyond order.
-  const target = join(distDir, "_headers");
-  const existing = existsSync(target) ? await readFile(target, "utf-8") : "";
-  await writeFile(
-    target,
-    existing ? `${existing.trimEnd()}\n${ours}` : ours,
-    "utf-8"
-  );
-  logger.success(
-    "Emitted _headers (UTF-8 Content-Type + homepage Link header)"
-  );
-};
-
-/**
- * Collect the Agent Skills `ai.skills` publishes, once per build, so both the
- * skills surface and llms.txt (which lists them) read the same set. Empty
- * when the feature is off, the directory is missing, nothing in it is
- * publishable (each with a warning), or a user-shipped
- * `public/.well-known/agent-skills/index.json` already owns the surface.
- */
-const collectConfiguredSkills = async (
-  project: BlumeProject,
-  distDir: string
-): Promise<SkillArtifact[]> => {
-  const configured = project.config.ai.skills;
-  if (!configured) {
-    return [];
-  }
-  const dir = resolve(project.context.root, configured);
-  if (!existsSync(dir)) {
-    logger.warn(
-      `ai.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
-    );
-    return [];
-  }
-  if (existsSync(join(distDir, AGENT_SKILLS_DIR.slice(1), "index.json"))) {
-    return [];
-  }
-  const { skills, warnings } = await collectSkills(dir);
-  for (const warning of warnings) {
-    logger.warn(warning);
-  }
-  if (skills.length === 0) {
-    logger.warn(`ai.skills: no publishable skills found in "${configured}".`);
-  }
-  return skills;
-};
-
-/**
- * Publish the collected Agent Skills: copy each skill artifact under
- * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
- * `public/.well-known/agent-skills/index.json` takes over the whole surface
- * (the collector returns nothing then), matching every other generated
- * artifact.
- */
-const emitAgentSkills = async (
-  project: BlumeProject,
-  distDir: string,
-  skills: readonly SkillArtifact[]
-): Promise<void> => {
-  if (skills.length === 0) {
-    return;
-  }
-  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
-  await Promise.all(
-    skills.map(async (skill) => {
-      const target = join(outDir, skill.path);
-      await mkdir(dirname(target), { recursive: true });
-      await writeFile(target, skill.content);
-    })
-  );
-  await writeFile(
-    join(outDir, "index.json"),
-    buildSkillsIndex(skills, project.config),
-    "utf-8"
-  );
-  logger.success(
-    `Published ${skills.length} agent skill(s) (.well-known/agent-skills/index.json)`
-  );
-};
-
-/**
- * Emit the generated `.well-known` discovery files — the RFC 9727 API catalog
- * and the Web Bot Auth signature directory — each skipped when the feature is
- * off or when the user ships their own copy via public/ (already in dist by
- * the time this runs).
- */
-const emitWellKnownFiles = async (
-  config: ResolvedConfig,
-  distDir: string
-): Promise<void> => {
-  const files = [
-    {
-      content: buildSignaturesDirectory(config),
-      label: "Web Bot Auth",
-      path: SIGNATURES_DIRECTORY_PATH,
-    },
-    {
-      content: buildApiCatalog(config),
-      label: "RFC 9727",
-      path: API_CATALOG_PATH,
-    },
-  ];
-  for (const file of files) {
-    const target = join(distDir, file.path.slice(1));
-    if (!file.content || existsSync(target)) {
-      continue;
-    }
-    // Sequential by nature: both files share the .well-known dir creation.
-    // oxlint-disable-next-line no-await-in-loop
-    await mkdir(join(distDir, ".well-known"), { recursive: true });
-    // oxlint-disable-next-line no-await-in-loop
-    await writeFile(target, file.content, "utf-8");
-    logger.success(`Generated ${file.path.slice(1)} (${file.label})`);
-  }
-};
-
 /**
  * Splice `Accept: text/markdown` negotiation routes into the Vercel adapter's
  * Build Output config, so a content-page request that prefers Markdown gets the
@@ -436,6 +216,15 @@ const emitCloudflareNegotiation = async (
       contentRoutePaths: project.manifest.routes.map((route) => route.path),
       homeLinkHeader: buildHomeLinkHeader(config, routePaths),
       homeTokens: home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+      // Exactly the per-page JSON documents the API emits (see `pageParams`):
+      // the non-hidden routes with agent Markdown, when the API is on.
+      pageJsonPaths: config.ai.api
+        ? project.manifest.routes
+            .filter(
+              (route) => !route.hidden && rawMarkdown[route.path] !== undefined
+            )
+            .map((route) => pageJsonPath(route.path))
+        : [],
       // The wrapper Worker matches full served URLs, so the redirects are
       // based the same way the platform files are — it answers any the
       // worker-first rules claim, where `_redirects` is never consulted and
@@ -616,118 +405,22 @@ export const isolatedStaticDir = (
 };
 
 /**
- * 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`.
+ * Print the build summary box and run the optional bundle report / budget
+ * gate against the served static dir. The deploy artifacts themselves
+ * (search index, llms.txt, sitemap, robots, redirect and header files, …)
+ * were written by the integration's `astro:build:done` hook during
+ * `build()` — see `deploy/artifacts.ts`. Exits non-zero if a budget is
+ * exceeded.
  */
-const publishLlmsFiles = async (
-  project: BlumeProject,
-  distDir: string,
-  skills: readonly SkillArtifact[]
-): 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, { skills });
-  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 except the bundle
- * report / budget gate, which they run against their own output.
- */
-const publishBuildArtifacts = async (
+const reportBuild = async (
   project: BlumeProject,
   distDir: string,
   args: { analyze?: boolean } & BudgetArgs
 ): Promise<void> => {
-  if (project.config.search.provider === "pagefind") {
-    logger.start("Building search index");
-    const indexed = await buildSearchIndex(distDir);
-    logger.success(`Indexed ${indexed} page(s) for search`);
-  }
-
-  // Upload the index to a hosted provider (Algolia, Orama Cloud, Typesense).
-  // Skipped with a warning when its admin key isn't configured.
-  await syncSearchProvider(project, {
-    start: (message) => logger.start(message),
-    success: (message) => logger.success(message),
-    warn: (message) => logger.warn(message),
-  });
-
-  // Collected once: llms.txt lists the skills the build publishes below.
-  const skills = await collectConfiguredSkills(project, distDir);
-  if (project.config.ai.llmsTxt.enabled) {
-    await publishLlmsFiles(project, distDir, skills);
-  }
-
-  // A user's own public/ file (copied into dist by Astro) always wins.
-  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);
-  if (robots && !existsSync(join(distDir, "robots.txt"))) {
-    await writeFile(join(distDir, "robots.txt"), robots, "utf-8");
-    logger.success("Generated robots.txt");
-  }
-
-  const agentReadability = buildAgentReadability(project);
-  if (
-    agentReadability &&
-    !existsSync(join(distDir, "agent-readability.json"))
-  ) {
-    await writeFile(
-      join(distDir, "agent-readability.json"),
-      `${JSON.stringify(agentReadability, null, 2)}\n`,
-      "utf-8"
-    );
-    logger.success("Generated agent-readability.json");
-  }
-
-  await emitWellKnownFiles(project.config, distDir);
-  await emitAgentSkills(project, distDir, skills);
-
-  await emitRedirectFiles(project.config, distDir);
-  await emitHeaderFiles(project, distDir);
-
   const { config } = project;
   const features = serverFeatures(config);
-  // `buildSitemapFiles` returns null both when the sitemap is disabled and when no
-  // `site` is configured — only the latter deserves the remediation hint.
+  // The sitemap needs both the flag and a `site` (absolute URLs) — only the
+  // latter deserves the remediation hint.
   const sitemapNote = config.seo.sitemap
     ? "no (set deployment.site)"
     : "no (seo.sitemap is false)";
@@ -738,9 +431,9 @@ const publishBuildArtifacts = async (
       `Site       ${config.deployment.site ?? "not set"}`,
       `Search     ${config.search.provider}`,
       `Redirects  ${config.redirects.length}`,
-      `Sitemap    ${sitemapFiles ? "yes" : sitemapNote}`,
-      `Robots     ${robots ? "yes" : "no"}`,
-      `Agent JSON ${agentReadability ? "yes" : "no"}`,
+      `Sitemap    ${config.deployment.site && config.seo.sitemap ? "yes" : sitemapNote}`,
+      `Robots     ${config.seo.robots ? "yes" : "no"}`,
+      `Agent JSON ${config.seo.agentReadability ? "yes" : "no"}`,
       `LLM files  ${config.ai.llmsTxt.enabled ? "yes" : "no"}`,
       `Server features  ${features.length > 0 ? features.join(", ") : "none"}`,
     ].join("\n")
@@ -800,10 +493,7 @@ export const buildCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Build the docs site for production.",
-    name: "build",
-  },
+  meta: commandMeta.build,
   async run({ args }) {
     const root = process.cwd();
 
@@ -852,18 +542,24 @@ export const buildCommand = defineCommand({
       `Building ${project.graph.pages.length} page(s) (${project.config.deployment.output} output)`
     );
 
+    // Hand the scanned project to the integration: its `astro:build:done`
+    // hook writes the deploy artifacts (search index, llms.txt, sitemap, …)
+    // into Astro's client output during the build. An isolated build is a
+    // throwaway verify that only needs to confirm the site compiles and
+    // renders, so it publishes nothing — no network post-steps (a hosted
+    // search sync would push), no deploy artifacts.
+    if (!runtimeDir) {
+      publishBuildProject(project);
+    }
+
     await build({
       logLevel: "info",
       root: project.context.outDir,
     });
 
-    // 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. 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.
+    // The bundle report and budget gate still run for an isolated build —
+    // `blume build --isolated --budget-js 100` exiting 0 without measuring
+    // anything would be a silent false pass in CI.
     if (runtimeDir) {
       if (
         project.config.deployment.output === "server" &&
@@ -918,7 +614,7 @@ export const buildCommand = defineCommand({
       await emitCloudflareNegotiation(project, markdownRoutePaths(project));
     }
 
-    await publishBuildArtifacts(
+    await reportBuild(
       project,
       deployStaticDir(project.config, project.context),
       args

package/src/cli/commands/check.ts

@@ -6,6 +6,7 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { ensureGitignore } from "../../core/gitignore.ts";
+import { commandMeta } from "../command-meta.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
@@ -26,10 +27,7 @@ export const checkCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Type-check the docs site with astro check.",
-    name: "check",
-  },
+  meta: commandMeta.check,
   async run({ args }) {
     const root = process.cwd();
 

package/src/cli/commands/dev.ts

@@ -4,37 +4,29 @@ import { defineCommand } from "citty";
 import { debounce } from "perfect-debounce";
 
 import { generateRuntime } from "../../astro/generate.ts";
-import { showBlumeErrorOverlay } from "../../astro/integration.ts";
+import {
+  refreshBlumeContent,
+  showBlumeErrorOverlay,
+} from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
+import { commandMeta } from "../command-meta.ts";
 import {
   acquireDevLock,
   describeDevLock,
   DevLockHeldError,
   updateDevLockPort,
 } from "../dev-lock.ts";
+import { normalizeHost } from "../host-args.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 has no mixed string/boolean arg type, so `host` is declared as a
- * string and a bare `--host` parses as `""` (the CLI entry rewrites it to
- * `--host=` first; see `host-args.ts`) — 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.
+ * "structural" change (needs a content re-sync) from a hot-reloadable one.
  */
 const routeSignature = (
   routes: readonly { entryId: string; path: string }[]
@@ -63,10 +55,7 @@ export const devCommand = defineCommand({
     },
     strict: { description: "Fail on diagnostics.", type: "boolean" },
   },
-  meta: {
-    description: "Start the Blume development server.",
-    name: "dev",
-  },
+  meta: commandMeta.dev,
   async run({ args }) {
     const root = process.cwd();
     const preview = args.preview ?? false;
@@ -110,10 +99,10 @@ export const devCommand = defineCommand({
       strict: args.strict,
     });
 
-    // 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.
+    // A factory so the regenerate loop can recreate the server when a
+    // structural (route-set) change can't be re-synced in place (see below).
+    // `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",
@@ -141,14 +130,16 @@ export const devCommand = defineCommand({
     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. perfect-debounce
-    // both debounces the watch burst (80ms) and single-flights the scan: a
+    // hot-reloads via Vite (fast path). A route-set change also needs Astro's
+    // content store re-synced: its glob watcher misses directory renames, so a
+    // renamed page would 404 (`getEntry` reads a stale store). Astro hands the
+    // integration `refreshContent` for exactly that — a full loader run
+    // against the live server, after which Astro's own store watcher clears
+    // the route cache and reloads the browser. Only a server that registered
+    // no refresh (none since Astro 5) falls back to a cold restart: stop,
+    // then bring up 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
@@ -166,23 +157,21 @@ export const devCommand = defineCommand({
         });
         const nextSignature = routeSignature(next.manifest.routes);
         const structural = nextSignature !== lastSignature;
-        if (structural) {
+        // Generate first: the new runtime data (and any staged remote content)
+        // is on disk and published before the store re-syncs against it.
+        await generateRuntime(next);
+        if (structural && !(await refreshBlumeContent())) {
           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.
+        // re-sync or restart above throws mid-sequence, the signature stays
+        // stale so the next watch event retries the structural path.
         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.
+        // overlay. The terminal report is not redundant: the overlay only
+        // shows once the browser has connected, and it clears on the next HMR
+        // update.
         reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {

package/src/cli/commands/doctor.ts

@@ -9,6 +9,7 @@ import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
   flushStdout,
@@ -41,10 +42,7 @@ export const doctorCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Diagnose common configuration and content problems.",
-    name: "doctor",
-  },
+  meta: commandMeta.doctor,
   async run({ args }) {
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];