blume 1.7.2 → 2.0.0

package/src/upgrade/upgrade.ts

@@ -0,0 +1,499 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join, relative, resolve } from "pathe";
+import { glob } from "tinyglobby";
+import { z } from "zod";
+
+import {
+  analyzeComponentOverrides,
+  ComponentOverridesError,
+} from "../core/component-overrides.ts";
+import { ConfigValidationError, loadConfig } from "../core/config.ts";
+import { BlumeError, locateFrontmatterKey } from "../core/diagnostics.ts";
+import matter from "../core/frontmatter.ts";
+import { createModuleLoader } from "../core/load-module.ts";
+import { findComponentsFile, findConfigFile } from "../core/project.ts";
+import { pageMetaSchema } from "../core/schema.ts";
+import { baselineScanIgnore } from "../core/sources/watch.ts";
+import type { Diagnostic } from "../core/types.ts";
+import {
+  DEFAULT_CONTENT_EXCLUDE,
+  DEFAULT_CONTENT_INCLUDE,
+} from "../sources/filesystem.ts";
+
+/**
+ * `blume upgrade`'s logic, kept out of the command module so it runs (and is
+ * covered) in-process: bump the `blume` dependency to the running CLI's major,
+ * then check the project against it — the config through the same loader
+ * every command uses, which names each removed or renamed field and its
+ * replacement, `components.ts` through the same static planner the build
+ * runs, and each page's front matter for fields the schema removed. The
+ * command prints the findings or hands them to a coding agent.
+ */
+
+/** The upgrade guide's route on the Blume docs site. */
+export const UPGRADE_GUIDE_URL = "https://useblume.dev/docs/upgrading";
+
+/** The upgrade guide's file inside the published package's bundled docs. */
+export const UPGRADE_GUIDE_FILE = join("docs", "03-upgrading.mdx");
+
+/** What `bumpBlumeDependency` did to `package.json`. */
+export type DependencyBump =
+  | {
+      field: DependencyField;
+      from: string;
+      status: "bumped";
+      to: string;
+    }
+  | { range: string; status: "current" }
+  | { status: "missing" };
+
+type DependencyField = "dependencies" | "devDependencies";
+
+const DEPENDENCY_FIELDS: DependencyField[] = [
+  "dependencies",
+  "devDependencies",
+];
+
+/** The slice of `package.json` the bump reads and rewrites. */
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+// Leading comparators and a `v` may precede the major (`^1.7.3`, `>=1 <2`,
+// `v1`); a protocol (`workspace:`, `file:`, `npm:`) or a tag (`latest`) names
+// no major at all, and those ranges are left to the user.
+const RANGE_MAJOR = /^[\s<=>^~v]*(?<major>\d+)/u;
+
+/** The major version a dependency range pins, or null when it names none. */
+export const rangeMajor = (range: string): number | null => {
+  const major = RANGE_MAJOR.exec(range)?.groups?.major;
+  return major === undefined ? null : Number(major);
+};
+
+// The file's own indentation (two spaces, four, or a tab), so a fallback
+// rewrite doesn't reformat a package.json the user keeps differently.
+const INDENT = /^(?<indent>[ \t]+)"/mu;
+
+const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
+const escapeRegExp = (value: string): string =>
+  value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
+
+/**
+ * `text` with the `blume` range under `field` replaced in place, so the file
+ * keeps its own formatting, key order, and inline objects; null when the entry
+ * isn't written the plain way (an escaped key or value).
+ */
+const replaceRange = (
+  text: string,
+  field: DependencyField,
+  from: string,
+  to: string
+): string | null => {
+  const value = JSON.stringify(from);
+  const entry = new RegExp(`"blume"\\s*:\\s*${escapeRegExp(value)}`, "gu");
+  entry.lastIndex = Math.max(text.indexOf(JSON.stringify(field)), 0);
+  const match = entry.exec(text);
+  if (!match) {
+    return null;
+  }
+  const end = match.index + match[0].length;
+  return `${text.slice(0, end - value.length)}${JSON.stringify(to)}${text.slice(end)}`;
+};
+
+/**
+ * Point `package.json`'s `blume` dependency at `^version` when it pins an
+ * older major. A range already on this major, or one that names no version
+ * (`workspace:*`, `latest`), is reported as current and left alone; a
+ * project with no `package.json`, or none that lists `blume`, is `missing`.
+ * Only the range changes: the rest of the file is kept byte for byte.
+ */
+export const bumpBlumeDependency = async (
+  root: string,
+  version: string
+): Promise<DependencyBump> => {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return { status: "missing" };
+  }
+  const text = await readFile(path, "utf-8");
+  // SAFETY: package.json is a JSON object; only its dependency maps, which
+  // map package names to range strings, are read.
+  const pkg = JSON.parse(text) as PackageJson;
+  const field = DEPENDENCY_FIELDS.find(
+    (name) => pkg[name]?.blume !== undefined
+  );
+  const from = field ? pkg[field]?.blume : undefined;
+  if (!(field && from)) {
+    return { status: "missing" };
+  }
+  const current = rangeMajor(from);
+  const target = rangeMajor(version);
+  if (current === null || target === null || current >= target) {
+    return { range: from, status: "current" };
+  }
+  const to = `^${version}`;
+  const indent = INDENT.exec(text)?.groups?.indent ?? "  ";
+  const updated = { ...pkg, [field]: { ...pkg[field], blume: to } };
+  await writeFile(
+    path,
+    replaceRange(text, field, from, to) ??
+      `${JSON.stringify(updated, null, indent)}\n`
+  );
+  return { field, from, status: "bumped", to };
+};
+
+/**
+ * Whether `root` is no Blume project at all: no config file and no `blume`
+ * dependency, so the upgrade would only check the defaults and report the
+ * folder ready. A zero-config project still lists `blume`.
+ */
+export const isOutsideBlumeProject = (
+  root: string,
+  bump: DependencyBump
+): boolean => bump.status === "missing" && findConfigFile(root) === null;
+
+// ---------------------------------------------------------------------------
+// Removed `blume build` flags
+// ---------------------------------------------------------------------------
+
+/** A `blume build` flag Blume 2 removed, bare or with an `=value`. */
+const REMOVED_BUILD_FLAG = /^--(?<flag>adapter|base|output)(?:=|$)/u;
+
+/** The removed `blume build` flags among `args`, in order, each once. */
+export const removedBuildFlags = (args: readonly string[]): string[] => [
+  ...new Set(
+    args.flatMap((arg) => {
+      const flag = REMOVED_BUILD_FLAG.exec(arg)?.groups?.flag;
+      return flag ? [flag] : [];
+    })
+  ),
+];
+
+/** The flags as the reader typed them: `--adapter, --output`. */
+export const flagList = (flags: string[]): string =>
+  flags.map((flag) => `--${flag}`).join(", ");
+
+/** What replaces each removed flag: the `deployment` config. */
+export const removedBuildFlagsAdvice = (flags: string[]): string => {
+  const advice: string[] = [];
+  if (flags.includes("adapter") || flags.includes("output")) {
+    advice.push(
+      'name the host in blume.config.ts with `deployment: vercel()` (or `netlify()`, `cloudflare()`, `node()`) from "blume/deploy" — a host adapter builds for the server, and `output: "static"` keeps it static'
+    );
+  }
+  if (flags.includes("base")) {
+    advice.push(
+      'set the subpath with `deployment: { base: "/docs" }`, or the host adapter\'s `base` option'
+    );
+  }
+  return `Drop ${flagList(flags)} and ${advice.join("; ")}.`;
+};
+
+// A command that runs the Blume CLI: the bare bin, a versioned package
+// (`blume@2`), or a path to it (`./node_modules/.bin/blume`).
+const BLUME_BIN = /(?:^|[/\\])blume(?:@\S+)?$/u;
+const COMMAND_SEPARATOR = /&&|\|\||[;|]/u;
+const WHITESPACE = /\s+/u;
+
+/** The arguments each `blume build` in a script passes, flattened. */
+const buildArgs = (script: string): string[] =>
+  script.split(COMMAND_SEPARATOR).flatMap((command) => {
+    const words = command.trim().split(WHITESPACE);
+    const at = words.findIndex(
+      (word, index) => BLUME_BIN.test(word) && words[index + 1] === "build"
+    );
+    return at === -1 ? [] : words.slice(at + 2);
+  });
+
+/** The slice of package.json the script check reads. */
+const scriptsSchema = z.looseObject({
+  scripts: z.record(z.string(), z.string()).default({}),
+});
+
+const lineOf = (text: string, index: number): number =>
+  text.slice(0, index).split("\n").length;
+
+/**
+ * A finding for each package.json script that still passes a removed flag to
+ * `blume build` — it would otherwise build a static site without a word.
+ */
+const scriptFindings = async (root: string): Promise<Diagnostic[]> => {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return [];
+  }
+  const text = await readFile(path, "utf-8");
+  const pkg = scriptsSchema.safeParse(JSON.parse(text));
+  const scripts = pkg.success ? pkg.data.scripts : {};
+  const scriptsAt = text.indexOf('"scripts"');
+  return Object.entries(scripts).flatMap(([name, script]) => {
+    const flags = removedBuildFlags(buildArgs(script));
+    if (flags.length === 0) {
+      return [];
+    }
+    const at = text.indexOf(JSON.stringify(name), scriptsAt);
+    return [
+      {
+        code: "BLUME_BUILD_FLAG_REMOVED",
+        file: path,
+        line: at === -1 ? undefined : lineOf(text, at),
+        message: `The "${name}" script passes ${flagList(flags)} to \`blume build\`, which Blume 2 removed.`,
+        severity: "error",
+        suggestion: removedBuildFlagsAdvice(flags),
+      } satisfies Diagnostic,
+    ];
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Removed front matter fields
+// ---------------------------------------------------------------------------
+
+/** Where a project's local content lives, as its config names it. */
+interface ContentGlobs {
+  exclude: string[];
+  include: string[];
+  root: string;
+}
+
+const globFields = {
+  exclude: z.array(z.string()).optional(),
+  include: z.array(z.string()).optional(),
+  root: z.string().optional(),
+};
+
+/**
+ * A filesystem source in either form a config being upgraded may hold: the
+ * `filesystem()` descriptor, or Blume 1's `{ type: "filesystem" }` object.
+ */
+const rawFilesystemSourceSchema = z.union([
+  z
+    .looseObject({
+      kind: z.literal("filesystem"),
+      options: z.looseObject(globFields).default({}),
+    })
+    .transform((source) => source.options),
+  z.looseObject({ type: z.literal("filesystem"), ...globFields }),
+]);
+
+/** The `content` slice of a config as written, before validation. */
+const rawContentSchema = z.looseObject({
+  content: z
+    .looseObject({ ...globFields, sources: z.array(z.unknown()).optional() })
+    .optional(),
+});
+
+/**
+ * The content roots to scan, read from the config as written rather than the
+ * validated config: the upgrade runs on configs that don't validate yet. Its
+ * filesystem sources when it lists any, else the `content.root` shorthand,
+ * else the zero-config `docs` folder.
+ */
+export const contentGlobs = ({
+  content,
+}: z.infer<typeof rawContentSchema>): ContentGlobs[] => {
+  const sources = (content?.sources ?? []).flatMap((source) => {
+    const filesystem = rawFilesystemSourceSchema.safeParse(source);
+    return filesystem.success ? [filesystem.data] : [];
+  });
+  return (sources.length > 0 ? sources : [content ?? {}]).map((globs) => ({
+    exclude: globs.exclude ?? DEFAULT_CONTENT_EXCLUDE,
+    include: globs.include ?? DEFAULT_CONTENT_INCLUDE,
+    root: globs.root ?? "docs",
+  }));
+};
+
+/** The content roots the project's config names, loaded as written. */
+const configContentGlobs = async (root: string): Promise<ContentGlobs[]> => {
+  const file = findConfigFile(root);
+  let raw: z.infer<typeof rawContentSchema> = {};
+  if (file) {
+    try {
+      const parsed = rawContentSchema.safeParse(
+        await createModuleLoader()(file)
+      );
+      raw = parsed.success ? parsed.data : {};
+    } catch {
+      // A config that won't load is already reported by the config check;
+      // its content still gets the zero-config scan.
+    }
+  }
+  return contentGlobs(raw);
+};
+
+const isPathKey = (segment: PropertyKey): segment is number | string =>
+  typeof segment !== "symbol";
+
+// Zod's own wording for an unknown key; a removed field's hint replaces it.
+const PLAIN_UNKNOWN_KEY = "Unrecognized key";
+
+/**
+ * The removed fields among one page's front matter issues, each at its own
+ * line. Only issues the page schema words as a removed-field hint count: a
+ * key a project declares through `frontmatter.extend` is unknown to the bare
+ * schema, and any other invalid value was already an error on Blume 1.
+ */
+const removedFieldFindings = (
+  file: string,
+  text: string,
+  issues: readonly z.core.$ZodIssue[]
+): Diagnostic[] =>
+  issues.flatMap((issue) => {
+    if (
+      issue.code !== "unrecognized_keys" ||
+      issue.message.startsWith(PLAIN_UNKNOWN_KEY)
+    ) {
+      return [];
+    }
+    const path = issue.path.filter(isPathKey);
+    const position =
+      locateFrontmatterKey(text, [...path, ...issue.keys.slice(0, 1)]) ??
+      locateFrontmatterKey(text, path);
+    return [
+      {
+        code: "BLUME_FRONTMATTER_INVALID",
+        column: position?.column,
+        file,
+        line: position?.line,
+        message: issue.message,
+        severity: "error",
+      } satisfies Diagnostic,
+    ];
+  });
+
+/** The removed front matter fields in one page, or none it can't parse. */
+const pageFindings = async (file: string): Promise<Diagnostic[]> => {
+  const text = await readFile(file, "utf-8");
+  let parsed: ReturnType<typeof pageMetaSchema.safeParse>;
+  try {
+    parsed = pageMetaSchema.safeParse(matter(text).data);
+  } catch {
+    // Unparseable front matter fails the build with its own diagnostic.
+    return [];
+  }
+  return parsed.success
+    ? []
+    : removedFieldFindings(file, text, parsed.error.issues);
+};
+
+/**
+ * A finding for each front matter field Blume 2 removed, across the project's
+ * local content. A page with one fails validation and drops out of the build,
+ * which the config and components checks alone would report as ready.
+ */
+const frontmatterFindings = async (root: string): Promise<Diagnostic[]> => {
+  const roots = await configContentGlobs(root);
+  const matches = await Promise.all(
+    roots.map((globs) => {
+      const cwd = resolve(root, globs.root);
+      return existsSync(cwd)
+        ? glob(globs.include, {
+            absolute: true,
+            cwd,
+            ignore: [...globs.exclude, ...baselineScanIgnore()],
+            onlyFiles: true,
+          })
+        : [];
+    })
+  );
+  // Two sources can share a folder; each page is checked once.
+  const files = [...new Set(matches.flat())].toSorted();
+  const findings = await Promise.all(files.map(pageFindings));
+  return findings.flat();
+};
+
+/**
+ * Run one check, turning the {@link BlumeError} it throws into its findings:
+ * each config issue or `components.ts` entry on its own, or the one diagnostic
+ * any other check has.
+ */
+const findingsOf = async (
+  check: () => Promise<void>
+): Promise<Diagnostic[]> => {
+  try {
+    await check();
+    return [];
+  } catch (error) {
+    if (
+      error instanceof ConfigValidationError ||
+      error instanceof ComponentOverridesError
+    ) {
+      return error.issues;
+    }
+    if (error instanceof BlumeError) {
+      return [error.diagnostic];
+    }
+    throw error;
+  }
+};
+
+/**
+ * Check a project against this version of Blume: its config through the
+ * loader (every invalid field, each with its line and replacement), its
+ * `components.ts` through the static override planner (each entry at its
+ * line), its pages' front matter for removed fields, and its package.json
+ * scripts for `blume build` flags that no longer exist. Returns the failures;
+ * an empty list means the project is ready.
+ */
+export const collectUpgradeFindings = async (
+  root: string
+): Promise<Diagnostic[]> => {
+  const componentsFile = findComponentsFile(root);
+  return [
+    ...(await findingsOf(async () => {
+      await loadConfig(root);
+    })),
+    ...(componentsFile
+      ? await findingsOf(async () => {
+          analyzeComponentOverrides(
+            await readFile(componentsFile, "utf-8"),
+            componentsFile
+          );
+        })
+      : []),
+    ...(await frontmatterFindings(root)),
+    ...(await scriptFindings(root)),
+  ];
+};
+
+/** A finding as plain text for the agent: where, what, and the fix. */
+const plainFinding = (finding: Diagnostic, root: string): string => {
+  const where = finding.file
+    ? `${relative(root, finding.file)}${finding.line === undefined ? "" : `:${finding.line}`}`
+    : "blume.config.ts";
+  const fix = finding.suggestion ? `\n  Fix: ${finding.suggestion}` : "";
+  return `- ${where} (${finding.code})\n  ${finding.message.replaceAll("\n", "\n  ")}${fix}`;
+};
+
+/**
+ * The handoff prompt: the findings inline (they're few, and each already
+ * names its replacement), where the guide is, and the ground rules — change
+ * the config's shape, never the site's behavior, and verify with the site's
+ * own checks, run through the project's package runner (`npx`, `pnpm exec`),
+ * since a local install puts no `blume` on PATH.
+ */
+export const upgradePrompt = (options: {
+  findings: Diagnostic[];
+  guidePath: string;
+  root: string;
+  runner: string;
+  version: string;
+}): string =>
+  `Upgrade this Blume project to Blume ${options.version}. \`blume upgrade\` has bumped the \`blume\` dependency in package.json where it could; what's left is the config.
+
+The upgrade guide is at ${options.guidePath} (online at ${UPGRADE_GUIDE_URL}). It covers every change between Blume 1 and 2 with before-and-after examples: search, deployment, content sources, API references, analytics, and Ask AI become adapters imported from \`blume/*\` subpaths; the machine-readable settings move from \`ai\` to \`agents\`; and \`components.ts\` entries must be one of the static forms.
+
+\`blume upgrade\` found:
+
+${options.findings.map((finding) => plainFinding(finding, options.root)).join("\n\n")}
+
+Work through every finding:
+1. Read the guide section for each change before editing.
+2. Rewrite the config to the Blume 2 form, adding the adapter imports it needs. Keep the site's behavior the same: the same content, routes, search backend, deployment target, analytics, and credentials (keep reading secrets from the same environment variables).
+3. The config loader reports every invalid field at once, but some changes only surface once earlier ones are fixed, so rerun \`${options.runner} blume doctor\` after each round of edits.
+4. Never delete content, or remove a setting only to silence an error; if something needs a human decision, leave it and say so in your summary.
+
+When \`${options.runner} blume doctor\` reports no errors, run \`${options.runner} blume build\` and fix anything it reports until it succeeds.`;

package/dist/cli/chunk-12dxjqk7.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/cli/commands/dev.ts"],
-  "sourcesContent": [
-    "import { dev } from \"astro\";\nimport { watch } from \"chokidar\";\nimport { defineCommand } from \"citty\";\nimport { debounce } from \"perfect-debounce\";\n\nimport { generateRuntime } from \"../../astro/generate.ts\";\nimport {\n  refreshBlumeContent,\n  showBlumeErrorOverlay,\n} from \"../../astro/integration.ts\";\nimport { scanProject } from \"../../core/project-graph.ts\";\nimport { resolveRuntimeDir } from \"../../core/project.ts\";\nimport { parsePort } from \"../args.ts\";\nimport { commandMeta } from \"../command-meta.ts\";\nimport {\n  acquireDevLock,\n  describeDevLock,\n  DevLockHeldError,\n  updateDevLockPort,\n} from \"../dev-lock.ts\";\nimport { normalizeHost } from \"../host-args.ts\";\nimport { logger, reportDiagnostics } from \"../log.ts\";\nimport { prepareProject } from \"../prepare.ts\";\n\n/**\n * A fingerprint of the route set: the sorted `path entryId` pairs. It changes\n * when a page is added, removed, or renamed (a folder rename shifts many at\n * once) but stays equal across pure body edits — so the dev loop can tell a\n * \"structural\" change (needs a content re-sync) from a hot-reloadable one.\n */\nconst routeSignature = (\n  routes: readonly { entryId: string; path: string }[]\n): string =>\n  routes\n    .map((route) => `${route.path} ${route.entryId}`)\n    .toSorted()\n    .join(\"\\n\");\n\nexport const devCommand = defineCommand({\n  args: {\n    \"content-dir\": {\n      description: \"Content folder to scan, overriding config (content.root).\",\n      type: \"string\",\n    },\n    debug: {\n      description: \"Verbose Astro/Vite logging for troubleshooting.\",\n      type: \"boolean\",\n    },\n    host: { description: \"Network host to bind.\", type: \"string\" },\n    open: { description: \"Open the browser on start.\", type: \"boolean\" },\n    port: { description: \"Port to listen on.\", type: \"string\" },\n    preview: {\n      description: \"Include drafts and unpublished CMS content.\",\n      type: \"boolean\",\n    },\n    strict: { description: \"Fail on diagnostics.\", type: \"boolean\" },\n  },\n  meta: commandMeta.dev,\n  async run({ args }) {\n    const root = process.cwd();\n    const preview = args.preview ?? false;\n    const overrides = args[\"content-dir\"]\n      ? { contentRoot: args[\"content-dir\"] }\n      : undefined;\n    // Astro's dev server defaults to 4321 when no port is passed. Feeding the\n    // resolved URL in as the `deployment.site` fallback lets site-gated features\n    // (OG images, canonicals, sitemap) work locally without configuring a site.\n    const explicitPort = parsePort(args.port);\n    const port = explicitPort ?? 4321;\n    let devServerUrl = `http://localhost:${port}`;\n\n    // Claim the shared `.blume` dir BEFORE preparing: `prepareProject`\n    // regenerates the runtime, so even a refused second dev server would\n    // otherwise clobber the running one's generated tree (with this\n    // invocation's port baked in) on its way out. The claim is atomic, so two\n    // simultaneous starts can't both win. Dev never relocates the runtime dir,\n    // so the lock always lives at `<root>/.blume`.\n    const outDir = resolveRuntimeDir(root);\n    let releaseLock: () => void;\n    try {\n      releaseLock = acquireDevLock(outDir, port);\n    } catch (error) {\n      if (error instanceof DevLockHeldError) {\n        logger.error(\n          `A \\`blume dev\\` server is already running${describeDevLock(error.lock)} in this project. Reuse that server instead of starting a second one — two dev servers would corrupt the shared .blume dir. If it crashed, delete .blume/dev.lock.`\n        );\n        process.exit(1);\n      }\n      throw error;\n    }\n    process.on(\"exit\", releaseLock);\n\n    const project = await prepareProject({\n      devServerUrl,\n      mode: \"dev\",\n      overrides,\n      preview,\n      root,\n      strict: args.strict,\n    });\n\n    // A factory so the regenerate loop can recreate the server when a\n    // structural (route-set) change can't be re-synced in place (see below).\n    // `open` is honored on first boot only — a restart must not reopen the\n    // browser.\n    const createServer = (listenPort: number | undefined, open: boolean) =>\n      dev({\n        logLevel: args.debug ? \"debug\" : \"info\",\n        root: project.context.outDir,\n        server: { host: normalizeHost(args.host), open, port: listenPort },\n      });\n\n    let server = await createServer(explicitPort, args.open ?? false);\n\n    // Vite bumps to the next free port when the default is taken, so record\n    // the port the server actually bound — the lock's URL is what a refused\n    // second invocation tells its caller to reuse. The site fallback baked\n    // into the runtime also carries the port, so it must follow suit (below,\n    // once the regeneration closure exists).\n    const boundPort = server.address.port;\n    if (boundPort !== port) {\n      updateDevLockPort(outDir, boundPort);\n      devServerUrl = `http://localhost:${boundPort}`;\n    }\n\n    // Mirror any initial diagnostics into the browser overlay now the server\n    // (and its HMR channel) is up.\n    showBlumeErrorOverlay(project.diagnostics);\n\n    let lastSignature = routeSignature(project.manifest.routes);\n\n    // Watch user inputs and regenerate the runtime data on change. A body edit\n    // hot-reloads via Vite (fast path). A route-set change also needs Astro's\n    // content store re-synced: its glob watcher misses directory renames, so a\n    // renamed page would 404 (`getEntry` reads a stale store). Astro hands the\n    // integration `refreshContent` for exactly that — a full loader run\n    // against the live server, after which Astro's own store watcher clears\n    // the route cache and reloads the browser. Only a server that registered\n    // no refresh (none since Astro 5) falls back to a cold restart: stop,\n    // then bring up a fresh container whose cold sync re-globs everything.\n    // perfect-debounce both debounces the watch burst (80ms) and\n    // single-flights the scan: a\n    // trigger during a run never starts a second run, only marks one trailing\n    // rerun after the current settles. Both halves are load-bearing — a plain\n    // debounce once let bursts stack overlapping scans until the heap was\n    // exhausted (observed as an OOM after minutes of looping). The contract is\n    // pinned by test/dev-debounce.test.ts. The task must not reject (the\n    // library re-invokes it from an unhandled .finally), so the body catches\n    // its own errors and always resolves.\n    const regenerate = debounce(async () => {\n      try {\n        const next = await scanProject(root, {\n          devServerUrl,\n          mode: \"dev\",\n          overrides,\n          preview,\n        });\n        const nextSignature = routeSignature(next.manifest.routes);\n        const structural = nextSignature !== lastSignature;\n        // Generate first: the new runtime data (and any staged remote content)\n        // is on disk and published before the store re-syncs against it.\n        await generateRuntime(next);\n        if (structural && !(await refreshBlumeContent())) {\n          await server.stop();\n          server = await createServer(boundPort, false);\n        }\n        // Commit the signature only after the (re)generation succeeded. If the\n        // re-sync or restart above throws mid-sequence, the signature stays\n        // stale so the next watch event retries the structural path.\n        lastSignature = nextSignature;\n        // Surface any content/config errors in the terminal AND the browser\n        // overlay. The terminal report is not redundant: the overlay only\n        // shows once the browser has connected, and it clears on the next HMR\n        // update.\n        reportDiagnostics(next.diagnostics, root);\n        showBlumeErrorOverlay(next.diagnostics);\n      } catch (error) {\n        // SAFETY: regeneration failures come from the generator and Astro's\n        // server API, which raise Error instances; only the message is shown.\n        logger.error(`Regeneration failed: ${(error as Error).message}`);\n      }\n    }, 80);\n\n    // The runtime prepared above baked the *requested* port into the site\n    // fallback; if Vite bumped it, regenerate so OG images, canonicals, and\n    // other site-gated URLs point at the port actually serving.\n    if (boundPort !== port) {\n      void regenerate();\n    }\n\n    // Content is watched per source (filesystem uses fs.watch; remote sources\n    // are frozen for the session). The remaining project inputs — user pages,\n    // config, theme, and component overrides — are watched directly.\n    const dirTargets = [project.context.pagesRoot].filter(\n      (target) => target !== null\n    );\n    const fileTargets = [\n      project.context.configFile,\n      project.context.themeFile,\n      project.context.componentsFile,\n    ].filter((target) => target !== null);\n\n    // chokidar handles what raw fs.watch made us hand-roll: recursive\n    // directory watching on every platform, and single files surviving a\n    // rename-replace save (vim and most \"atomic save\" editors), which orphans\n    // an inode-tracking fs.watch watcher after the first write.\n    const projectWatcher = watch([...dirTargets, ...fileTargets], {\n      ignoreInitial: true,\n    }).on(\"all\", regenerate);\n    const disposers = [\n      ...project.sources.map((source) => source.watch?.(regenerate)),\n      () => {\n        void projectWatcher.close();\n      },\n    ].filter((dispose) => dispose !== undefined);\n\n    const shutdown = async () => {\n      for (const dispose of disposers) {\n        dispose();\n      }\n      releaseLock();\n      await server.stop();\n      process.exit(0);\n    };\n\n    process.on(\"SIGINT\", shutdown);\n    process.on(\"SIGTERM\", shutdown);\n  },\n});\n"
-  ],
-  "mappings": "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",
-  "debugId": "350EDAE5A410927464756E2164756E21",
-  "names": []
-}