blume 1.5.3 → 1.6.1

package/src/astro/include-hmr.ts

@@ -0,0 +1,81 @@
+import { readFile, utimes } from "node:fs/promises";
+
+/**
+ * Dev-server invalidation for `<include>` partials. A partial is not an Astro
+ * content-collection entry (the default underscore-prefix exclude keeps it
+ * out of the `docs` glob), so Vite has no edge from an including page to it —
+ * editing the partial would keep serving the page's stale compiled module.
+ * The scan records each page's transitive includes; `generateRuntime` writes
+ * them to `generated/includes.json` as partial → including pages, and this
+ * plugin turns a partial edit into an invalidation of those page modules plus
+ * a full reload.
+ *
+ * The graph file is re-read on every hot update: `blume dev`'s regenerate
+ * loop rewrites it after each content change, so the mapping tracks include
+ * edits without restarting the server.
+ */
+
+/** The Vite module-graph slice the plugin touches (structurally typed, like
+ * every Blume-authored Vite plugin — see `serverAppResolvePlugin`). */
+interface IncludeHmrServer {
+  moduleGraph: {
+    getModulesByFile: (file: string) => Set<unknown> | undefined;
+    invalidateModule: (mod: never) => void;
+  };
+  ws: { send: (payload: { type: "full-reload" }) => void };
+}
+
+export interface IncludeHmrContext {
+  file: string;
+  server: IncludeHmrServer;
+}
+
+export interface IncludeHmrPlugin {
+  name: string;
+  handleHotUpdate: (ctx: IncludeHmrContext) => Promise<never[] | undefined>;
+}
+
+export const includeHmrPlugin = (graphPath: string): IncludeHmrPlugin => ({
+  async handleHotUpdate(ctx) {
+    let graph: Record<string, string[]>;
+    try {
+      // SAFETY: `generateRuntime` is the file's only writer and serializes
+      // exactly this shape; a malformed hand-edit throws into the catch below.
+      graph = JSON.parse(await readFile(graphPath, "utf-8")) as Record<
+        string,
+        string[]
+      >;
+    } catch {
+      // No graph yet (first run) — nothing to invalidate.
+      return;
+    }
+    const includers = graph[ctx.file];
+    if (!includers || includers.length === 0) {
+      return;
+    }
+    const { moduleGraph, ws } = ctx.server;
+    const now = new Date();
+    for (const includer of includers) {
+      for (const mod of moduleGraph.getModulesByFile(includer) ?? []) {
+        // SAFETY: the module came out of this module graph; `never` only
+        // reflects that the structural slice doesn't model the node type.
+        moduleGraph.invalidateModule(mod as never);
+      }
+      // Plain `.md` pages have no Vite module: their HTML lives in the
+      // content-layer store, rendered at sync time. Bump the page's mtime so
+      // Astro's content watcher re-syncs it — the include-aware digest
+      // (`withIncludeRefresh`) then forces a fresh render that re-reads the
+      // edited partial.
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- ordered per-page touch
+        await utimes(includer, now, now);
+      } catch {
+        // The page may have been deleted since the graph was written.
+      }
+    }
+    ws.send({ type: "full-reload" });
+    // The partial itself is not a module; suppress Vite's default handling.
+    return [];
+  },
+  name: "blume:include-hmr",
+});

package/src/astro/index.ts

@@ -1,9 +1,14 @@
 export { withAdapterRoot } from "./adapter-root.ts";
-export {
-  generateRuntime,
-  prerenderDepsPlugin,
-  serverAppResolvePlugin,
-} from "./generate.ts";
+export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
+export { includeHmrPlugin } from "./include-hmr.ts";
+export { withIncludeRefresh } from "./include-refresh.ts";
 export type { GenerateResult } from "./generate.ts";
 export { blumeIntegration } from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
+export {
+  publishRuntimeModules,
+  readRuntimeModule,
+  RUNTIME_MODULE_FILES,
+  runtimeModulesPlugin,
+} from "./runtime-modules.ts";
+export type { RuntimeModuleId } from "./runtime-modules.ts";

package/src/astro/markdown-negotiation.ts

@@ -29,7 +29,7 @@ const parseAccept = (accept: string): AcceptEntry[] =>
 
 /**
  * Whether the client explicitly prefers Markdown over HTML. Browsers never send
- * `text/markdown`, so an ordinary page request (`text/html`, `*​/*`) is false.
+ * `text/markdown`, so an ordinary page request (`text/html` or the catch-all wildcard) is false.
  */
 export const prefersMarkdown = (accept: string | null | undefined): boolean => {
   if (!accept) {

package/src/astro/runtime-modules.ts

@@ -0,0 +1,196 @@
+/**
+ * In-memory runtime data modules.
+ *
+ * The generated runtime's data snapshots — the page data behind `blume:data`,
+ * the parsed API specs, the static search index, the raw-Markdown and
+ * content-asset maps, the MCP and Ask corpora, and the rendered RSS feeds —
+ * used to be written under `.blume/src/generated/*.json` and imported by the
+ * generated pages through aliases or relative paths. `generateRuntime` now
+ * publishes them here and `runtimeModulesPlugin` serves them to Vite as
+ * virtual modules, so a regeneration never round-trips the disk or waits on a
+ * file watcher: publishing invalidates the changed modules in every live dev
+ * server (Vite walks the importers, so the pages that render them re-evaluate
+ * on the next request) and asks the browser to reload — the same effect a JSON
+ * file change used to reach through the watcher, minus the write and the
+ * watch debounce.
+ *
+ * The registry hangs off `globalThis`, not module state. On a published
+ * install the CLI bundle (`dist/cli`) carries its own copy of this module,
+ * separate from the one Vite loads from `blume/astro` for the generated
+ * config, and both must see the same map. `blume dev`, `blume build`, and
+ * `blume check` all run Astro in-process, so the map the CLI fills is the map
+ * the plugin reads.
+ *
+ * `blume eject` keeps the file form: the ejected project has no CLI to
+ * publish, so its `astro.config.mjs` aliases each id to the JSON file eject
+ * writes under `src/generated/` — the names in {@link RUNTIME_MODULE_FILES}.
+ */
+
+export type RuntimeModuleId =
+  | "blume:ask-data"
+  | "blume:content-assets"
+  | "blume:data"
+  | "blume:mcp-data"
+  | "blume:openapi"
+  | "blume:raw-markdown"
+  | "blume:rss"
+  | "blume:search-index";
+
+/** Virtual module id → the `src/generated` JSON file eject writes for it. */
+export const RUNTIME_MODULE_FILES: ReadonlyMap<RuntimeModuleId, string> =
+  new Map([
+    ["blume:ask-data", "ask-data.json"],
+    ["blume:content-assets", "content-assets.json"],
+    ["blume:data", "data.json"],
+    ["blume:mcp-data", "mcp-data.json"],
+    ["blume:openapi", "openapi.json"],
+    ["blume:raw-markdown", "raw-markdown.json"],
+    ["blume:rss", "rss.json"],
+    ["blume:search-index", "search.json"],
+  ]);
+
+const RUNTIME_MODULE_IDS: ReadonlySet<string> = new Set(
+  RUNTIME_MODULE_FILES.keys()
+);
+
+/** Rollup's virtual-module convention: `\0` keeps other plugins off the id. */
+const RESOLVED_PREFIX = "\0";
+
+/** A node in Vite's module graph; only its identity matters here. */
+interface RuntimeModuleNode {
+  id: string | null;
+}
+
+/**
+ * The Vite dev-server slice the registry touches (structurally typed, like
+ * every Blume-authored Vite plugin — see `includeHmrPlugin`).
+ */
+export interface RuntimeModuleServer {
+  httpServer?: {
+    once: (event: "close", listener: () => void) => void;
+  } | null;
+  moduleGraph: {
+    getModuleById: (id: string) => RuntimeModuleNode | undefined;
+    invalidateModule: (mod: RuntimeModuleNode) => void;
+  };
+  ws: { send: (payload: { type: "full-reload" }) => void };
+}
+
+interface RuntimeModuleRegistry {
+  /** Published JSON text by module id. */
+  modules: Map<string, string>;
+  /** Live dev servers to invalidate on publish. */
+  servers: Set<RuntimeModuleServer>;
+}
+
+const REGISTRY_KEY = Symbol.for("blume.runtime-modules");
+
+type RegistryHost = typeof globalThis & {
+  [REGISTRY_KEY]?: RuntimeModuleRegistry;
+};
+
+const registry = (): RuntimeModuleRegistry => {
+  // SAFETY: the registry is stashed on globalThis under a well-known symbol so
+  // every copy of this module in the process shares it; the intersection only
+  // names that slot.
+  const host = globalThis as RegistryHost;
+  host[REGISTRY_KEY] ??= { modules: new Map(), servers: new Set() };
+  return host[REGISTRY_KEY];
+};
+
+/** The published JSON text for a module, if any (tests and diagnostics). */
+export const readRuntimeModule = (id: RuntimeModuleId): string | undefined =>
+  registry().modules.get(id);
+
+/**
+ * Replace the published snapshot set with `modules` (an id absent from the map
+ * is unpublished — its feature was switched off). Returns the ids whose text
+ * changed; each is invalidated in every live dev server, followed by one
+ * full-reload per server. Nothing is sent when nothing changed, so a
+ * regeneration triggered by an unrelated edit stays quiet — the same contract
+ * `writeIfChanged` gave the file form.
+ */
+export const publishRuntimeModules = (
+  modules: ReadonlyMap<RuntimeModuleId, string>
+): RuntimeModuleId[] => {
+  const { modules: current, servers } = registry();
+  const changed: RuntimeModuleId[] = [];
+  for (const id of RUNTIME_MODULE_FILES.keys()) {
+    const next = modules.get(id);
+    if (current.get(id) === next) {
+      continue;
+    }
+    if (next === undefined) {
+      current.delete(id);
+    } else {
+      current.set(id, next);
+    }
+    changed.push(id);
+  }
+  if (changed.length === 0) {
+    return changed;
+  }
+  for (const server of servers) {
+    for (const id of changed) {
+      const mod = server.moduleGraph.getModuleById(`${RESOLVED_PREFIX}${id}`);
+      if (mod) {
+        server.moduleGraph.invalidateModule(mod);
+      }
+    }
+    server.ws.send({ type: "full-reload" });
+  }
+  return changed;
+};
+
+export interface RuntimeModulesPlugin {
+  configureServer: (server: RuntimeModuleServer) => void;
+  enforce: "pre";
+  load: (id: string) => string | undefined;
+  name: string;
+  resolveId: (id: string) => string | undefined;
+}
+
+/**
+ * Serve the published runtime modules to Vite. `enforce: "pre"` claims the
+ * `blume:*` ids before Vite's resolver would try (and fail) to find them as
+ * packages. Loading an unpublished id is a hard error rather than an empty
+ * module: the generated pages only import a module when its data exists, so a
+ * miss means the config was run outside the CLI that publishes.
+ */
+export const runtimeModulesPlugin = (): RuntimeModulesPlugin => ({
+  configureServer(server) {
+    const { servers } = registry();
+    servers.add(server);
+    // Astro restarts the dev container in place on a config change (and the
+    // CLI restarts it on a route-set change): the old Vite server closes and
+    // a new one registers, so drop the stale handle rather than invalidating
+    // into a dead graph.
+    server.httpServer?.once("close", () => {
+      servers.delete(server);
+    });
+  },
+  enforce: "pre",
+  load(id) {
+    if (!id.startsWith(RESOLVED_PREFIX)) {
+      return;
+    }
+    const moduleId = id.slice(RESOLVED_PREFIX.length);
+    if (!RUNTIME_MODULE_IDS.has(moduleId)) {
+      return;
+    }
+    const text = registry().modules.get(moduleId);
+    if (text === undefined) {
+      throw new Error(
+        `Blume runtime module "${moduleId}" was requested before it was published. Run the generated project through the Blume CLI (blume dev / blume build), which publishes the runtime data before starting Astro.`
+      );
+    }
+    // A JSON.parse over a string literal evaluates faster than an equivalent
+    // object literal for large snapshots (V8's guidance; Vite's own JSON
+    // plugin does the same past a size threshold).
+    return `export default JSON.parse(${JSON.stringify(text)});\n`;
+  },
+  name: "blume:runtime-modules",
+  resolveId(id) {
+    return RUNTIME_MODULE_IDS.has(id) ? `${RESOLVED_PREFIX}${id}` : undefined;
+  },
+});