blume 1.5.2 → 1.6.0

package/src/astro/generate.ts

@@ -14,7 +14,15 @@ import { pathToFileURL } from "node:url";
 
 import { imageSize } from "image-size";
 import pMap from "p-map";
-import { basename, dirname, join, normalize, relative, resolve } from "pathe";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+} from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
@@ -25,7 +33,10 @@ import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import { analyzeComponentOverrides } from "../core/component-overrides.ts";
-import { collectContentAssets } from "../core/content-assets.ts";
+import {
+  collectContentAssets,
+  rewriteRelativeImages,
+} from "../core/content-assets.ts";
 import type {
   BlumeBanner,
   BlumeData,
@@ -34,8 +45,14 @@ import type {
 } from "../core/data.ts";
 import { BlumeError } from "../core/diagnostics.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
+import {
+  apiUrl as githubApiUrl,
+  editBaseUrl as githubEditBaseUrl,
+  repoUrl as githubRepoUrl,
+} from "../core/github.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
+import { buildIncludeGraph } from "../core/includes.ts";
 import {
   validateNavTargets,
   validateSearchPopularIcons,
@@ -44,14 +61,20 @@ import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/resolve.ts";
+import { trimChar } from "../core/trim.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
-import type { Diagnostic, Navigation, ProjectContext } from "../core/types.ts";
+import type { Diagnostic, Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
-import type { OpenApiData } from "../openapi/model.ts";
-import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
+import type { ApiSpecData, OpenApiData } from "../openapi/model.ts";
+import {
+  builtinProxyKinds,
+  hasScalarReferences,
+  needsPlaygroundProxy,
+  referenceRoutes,
+} from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
@@ -62,7 +85,11 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
-import { buildFontsCss, configuredFonts } from "../theme/fonts.ts";
+import {
+  buildFontsCss,
+  configuredFonts,
+  fontLocaleCodes,
+} from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
@@ -98,7 +125,6 @@ import {
   playgroundProxyTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
-  runtimeDirWithin,
   staticJsonEndpointTemplate,
   runtimeDependencies,
   runtimePackageTemplate,
@@ -512,47 +538,6 @@ export const prerenderDepsPlugin = (
   },
 });
 
-/** The subset of Rollup's plugin context `blume:server-app-resolve` needs. */
-interface ServerAppResolveContext {
-  resolve: (source: string) => Promise<{ id: string } | null>;
-}
-
-/**
- * Work around an Astro + Vite dev bug that breaks content renames.
- *
- * Astro's dev SSR entry is the virtual module `astro:server-app`, but its
- * resolver only matches the exact id (`/^astro:server-app$/`). Whenever the
- * route set changes — a content add, remove, or rename — Astro triggers a full
- * page reload, during which Vite re-requests the entry as `astro:server-app.js`.
- * The trailing `.js` misses Astro's filter, so the load fails ("Failed to load
- * url astro:server-app.js") and Vite's SSR module runner is left corrupted: the
- * in-memory content store never reconnects, so `getEntry` returns undefined and
- * the renamed page 404s until the dev server is manually restarted.
- *
- * Stripping the spurious `.js` and delegating back to Astro's resolver lets the
- * reload complete cleanly, so the renamed route resolves without a restart.
- */
-export interface ServerAppResolvePlugin {
-  enforce: "pre";
-  name: string;
-  resolveId: (
-    this: ServerAppResolveContext,
-    id: string
-  ) => Promise<string | null>;
-}
-
-export const serverAppResolvePlugin = (): ServerAppResolvePlugin => ({
-  enforce: "pre",
-  name: "blume:server-app-resolve",
-  async resolveId(id) {
-    if (id === "astro:server-app.js") {
-      const resolved = await this.resolve("astro:server-app");
-      return resolved?.id ?? null;
-    }
-    return null;
-  },
-});
-
 /** Astro integration package each non-React island framework needs installed. */
 const ISLAND_FRAMEWORK_DEPS = new Map([
   ["svelte", "@astrojs/svelte"],
@@ -843,7 +828,19 @@ export const collectStaged = (project: BlumeProject): Map<string, string> => {
   const staged = new Map<string, string>();
   for (const page of project.graph.pages) {
     if (page.collection === "staged" && page.entryId && page.body) {
-      staged.set(page.entryId, page.body.text);
+      // A colocated `./image.png` reference resolves against `.blume/content`
+      // once the body is materialized there, where the file does not exist.
+      // Point it at the served original instead — the same rewrite the
+      // agent-facing Markdown gets.
+      const text = page.sourcePath
+        ? rewriteRelativeImages({
+            deployBase: project.config.deployment.base,
+            projectRoot: project.context.root,
+            source: page.body.text,
+            sourcePath: page.sourcePath,
+          })
+        : page.body.text;
+      staged.set(page.entryId, text);
     }
   }
   return staged;
@@ -916,6 +913,22 @@ const readLogoSvg = (
 const isStringShorthand = <T>(value: T | string): value is string =>
   typeof value === "string";
 
+/**
+ * The URL behind the header's repo mark. A string is used as-is: `github`
+ * drives the per-page edit link, the header mark and the manifest's
+ * `repository` together, so a project whose docs repo is private has to unset
+ * all three, and would otherwise have no way to point the mark at anything.
+ */
+const headerRepoUrl = (
+  repo: boolean | string,
+  derived: string | null
+): string | null => {
+  if (isStringShorthand(repo)) {
+    return repo;
+  }
+  return repo ? derived : null;
+};
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -1165,14 +1178,29 @@ const resolveOgDescription = (config: ResolvedConfig): string | undefined => {
   return configured ?? config.description;
 };
 
+/**
+ * Repo coordinates for content components. `host` and the derived `api` ride
+ * along so a card on an Enterprise site links and queries that instance rather
+ * than the public one.
+ */
+const resolveGithubData = (
+  github: ResolvedConfig["github"]
+): BlumeData["config"]["github"] =>
+  github
+    ? {
+        api: githubApiUrl(github),
+        host: github.host,
+        owner: github.owner,
+        repo: github.repo,
+      }
+    : null;
+
 /** Serialize the content graph into the data module the runtime consumes. */
 export const buildRuntimeData = (project: BlumeProject): string => {
   const { config, context, graph, manifest } = project;
   const { github } = config;
-  const repoUrl = github
-    ? `https://github.com/${github.owner}/${github.repo}`
-    : null;
-  const editBase = github ? `${repoUrl}/edit/${github.branch}` : null;
+  const repoUrl = github ? githubRepoUrl(github) : null;
+  const editBase = github ? githubEditBaseUrl(github) : null;
   const logo = resolveLogo(project);
   const ogLogo = resolveOgMark(project, logo?.svg);
 
@@ -1181,7 +1209,18 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       return null;
     }
     const rel = relative(context.root, sourcePath).split("\\").join("/");
-    const editPath = github?.dir ? `${github.dir}/${rel}` : rel;
+    // The edit path is repo-relative: `github.dir` places the project inside
+    // the repo, so a source above the project dir (a monorepo vault beside the
+    // docs app) still resolves to an in-repo file. A path that escapes the
+    // repo itself has nothing to edit — fabricating one yields a 404 link.
+    // `dir` is a bare string in the schema, so a leading slash (`/apps/docs`)
+    // is trimmed rather than read as an absolute path — which would drop the
+    // link from every page of a site that has always written it that way.
+    const editDir = trimChar(github?.dir ?? "", "/");
+    const editPath = normalize(editDir ? join(editDir, rel) : rel);
+    if (editPath.startsWith("..") || isAbsolute(editPath)) {
+      return null;
+    }
     return `${editBase}/${editPath}`;
   };
 
@@ -1190,9 +1229,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
   // Resolve the header repo link per locale. API references no longer add a tab
   // automatically — authors point a `navigation.tabs` entry at the reference
   // route to surface it (see `referenceRoutes`).
+  const markUrl = headerRepoUrl(config.navigation.repo, repoUrl);
   const withRepoUrl = (nav: Navigation): Navigation => ({
     ...nav,
-    repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
+    repoUrl: markUrl,
   });
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
@@ -1221,6 +1261,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           code,
           withRepoUrl(
             graph.navigationByLocale[code] ?? {
+              actions: [],
+              cta: null,
               featured: [],
               selectors: [],
               sidebar: [],
@@ -1250,9 +1292,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       discovery: {
         agentReadability: config.seo.agentReadability,
         llmsTxt: config.ai.llmsTxt.enabled,
+        // Mirrors `buildSitemapFiles`: no site, no sitemap.
+        sitemap: config.seo.sitemap && Boolean(config.deployment.site),
       },
       favicon: resolveFavicon(project),
       feedback: config.feedback,
+      github: resolveGithubData(github),
       i18n: i18n
         ? {
             defaultLocale: i18n.defaultLocale,
@@ -1267,6 +1312,15 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
+      // `undefined` members drop out of the JSON snapshot; the null keeps the
+      // "nothing configured" case explicit for the layouts.
+      identity:
+        config.seo.organization || config.seo.software
+          ? {
+              organization: config.seo.organization,
+              software: config.seo.software,
+            }
+          : null,
       imageZoom: config.markdown.imageZoom,
       logo,
       mcp: config.ai.mcp.enabled
@@ -1311,8 +1365,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       title: feed.title,
     })),
     // CSS variables for Astro's <Font> component; matches the astro.config
-    // `fonts:` entries derived from the same theme.fonts config.
-    fontCssVars: configuredFonts(config.theme.fonts),
+    // `fonts:` entries derived from the same theme.fonts config (and the
+    // same locale-derived subsets, so preloads cover the scripts pages use).
+    fontCssVars: configuredFonts(
+      config.theme.fonts,
+      fontLocaleCodes(config.i18n)
+    ),
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
@@ -1460,11 +1518,7 @@ const writeMcpFiles = async (
  * `prerender = false` export wins over the injection default.
  */
 const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
-  enabled:
-    config.openapi.enabled &&
-    config.openapi.renderer === "blume" &&
-    config.openapi.playground.enabled &&
-    config.openapi.playground.proxy === true,
+  enabled: needsPlaygroundProxy(config),
   entrypoint: join(srcDir, "blume-openapi", "api-proxy.ts"),
   pattern: "/_api-proxy",
 });
@@ -1480,46 +1534,68 @@ const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
  * origin to allow and are skipped; AsyncAPI documents declare `servers` as a
  * map and contribute nothing (the proxy is OpenAPI-only).
  */
-const specOrigins = (data: OpenApiData): string[] => {
+const specOriginsOf = (spec: ApiSpecData): string[] => {
   const origins = new Set<string>();
-  for (const spec of Object.values(data)) {
-    // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
-    // the optional `servers` shape, and every access below re-checks it —
-    // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
-    const { servers } = spec.document as { servers?: { url?: string }[] };
-    for (const server of Array.isArray(servers) ? servers : []) {
-      const url = server.url ?? "";
-      // `new URL("https://{region}.api.example.com")` parses — the braces land
-      // in the hostname — so templated URLs need an explicit check or their
-      // junk literal becomes an allowlist entry no real request can match.
-      if (url.includes("{")) {
-        continue;
-      }
-      try {
-        origins.add(new URL(url).origin);
-      } catch {
-        // Not an absolute URL: nothing to allow.
-      }
+  // A GraphQL schema names no servers; its configured live endpoint is the
+  // one origin the playground targets.
+  if (spec.endpoint !== undefined) {
+    try {
+      origins.add(new URL(spec.endpoint).origin);
+    } catch {
+      // Not an absolute URL: nothing to allow.
     }
   }
-  return [...origins].toSorted();
+  // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
+  // the optional `servers` shape, and every access below re-checks it —
+  // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
+  const { servers } = spec.document as { servers?: { url?: string }[] };
+  for (const server of Array.isArray(servers) ? servers : []) {
+    const url = server.url ?? "";
+    // `new URL("https://{region}.api.example.com")` parses — the braces land
+    // in the hostname — so templated URLs need an explicit check or their
+    // junk literal becomes an allowlist entry no real request can match.
+    if (url.includes("{")) {
+      continue;
+    }
+    try {
+      origins.add(new URL(url).origin);
+    } catch {
+      // Not an absolute URL: nothing to allow.
+    }
+  }
+  return [...origins];
 };
 
+const specOrigins = (data: OpenApiData): string[] =>
+  [...new Set(Object.values(data).flatMap(specOriginsOf))].toSorted();
+
 /**
- * The build-time diagnostic for a proxy whose allowlist came out empty. The
- * allowlist comes solely from absolute `servers[].url` entries — relative and
- * templated ones carry no origin — and with none at all the endpoint would
- * 403 every playground send with nothing pointing the author at the spec.
+ * Build-time diagnostics for playground sends the built-in proxy would refuse.
+ * The baked-in allowlist pools every documented origin, but each spec's
+ * playground only ever targets that spec's own servers/endpoint — so a
+ * non-empty pool can still leave one spec's Send 403ing on every request.
+ * Hence the check is per spec: any spec routed through the built-in proxy
+ * whose own origins came out empty (no absolute `servers[].url`, no absolute
+ * GraphQL `endpoint`) gets a warning naming it.
  */
 const proxyAllowlistWarnings = (
-  enabled: boolean,
-  origins: string[]
-): string[] =>
-  enabled && origins.length === 0
-    ? [
-        "openapi.playground.proxy is enabled, but no spec declares an absolute servers[].url (relative and templated URLs carry no origin), so the proxy's allowlist is empty and it will refuse every request. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.",
-      ]
-    : [];
+  config: ResolvedConfig,
+  data: OpenApiData
+): string[] => {
+  const kinds = builtinProxyKinds(config);
+  const warnings: string[] = [];
+  for (const spec of Object.values(data)) {
+    if (!kinds.includes(spec.kind) || specOriginsOf(spec).length > 0) {
+      continue;
+    }
+    warnings.push(
+      spec.kind === "graphql"
+        ? `The "${spec.label}" GraphQL reference (${spec.route}) has playground.proxy: true, but no absolute endpoint is configured for it, so the built-in proxy has no origin to allow and will refuse every request its playground sends. Set the graphql block's (or the source's) \`endpoint\` to the live GraphQL URL, or point playground.proxy at an external proxy URL.`
+        : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative and templated URLs carry no origin), so the built-in proxy has no origin to allow and will refuse every request its playground sends. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.`
+    );
+  }
+  return warnings;
+};
 
 /**
  * Write the Ask AI endpoint and, unless the backend runs its own retrieval
@@ -1615,20 +1691,6 @@ const buildComponentSlots = async (
   };
 };
 
-/**
- * Whether the docs glob-loader's watcher observes the runtime dir: a
- * filesystem collection whose base contains it (a migrated, `content.root:
- * "."` project) — the one layout where the dev watcher must be kept out of
- * Astro's cache dir. See `devWatchOption` in templates.ts.
- */
-const contentWatchesRuntimeDir = (
-  hasFilesystemSource: boolean,
-  collectionBase: string,
-  context: ProjectContext
-): boolean =>
-  hasFilesystemSource &&
-  runtimeDirWithin(collectionBase, context.outDir) !== null;
-
 /** The OG endpoint fonts for a scanned project (see {@link resolveOgFonts}). */
 const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
   resolveOgFonts(
@@ -1780,8 +1842,9 @@ export const generateRuntime = async (
       pattern: playgroundProxy.pattern,
     });
   }
-  // Computed once: the endpoint template bakes it in below, and an empty list
-  // is worth a diagnostic — the proxy would refuse every request it gets.
+  // Computed once: the endpoint template bakes it in below. A spec that
+  // contributes no origin of its own gets a per-spec diagnostic
+  // (`proxyAllowlistWarnings`) — the proxy would refuse its every send.
   const proxyOrigins = specOrigins(openApiData);
 
   const hasStaged = staged.size > 0;
@@ -1804,12 +1867,8 @@ export const generateRuntime = async (
           aliases: resolveTsconfigAliases(context.root),
           askPath,
           config,
+          contentRoot: docsCollection.base,
           contentRoutes: markdownRoutePaths(project),
-          contentWatchesRuntimeDir: contentWatchesRuntimeDir(
-            hasFilesystemSource,
-            docsCollection.base,
-            context
-          ),
           context,
           dataPath,
           examplesPath,
@@ -1993,6 +2052,14 @@ export const generateRuntime = async (
     );
   }
 
+  // The include graph (partial → including pages) behind `includeHmrPlugin`:
+  // editing a partial invalidates every page that splices it. Written even
+  // when empty so the plugin's configured path always resolves.
+  await write(
+    join(srcDir, "generated", "includes.json"),
+    `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`
+  );
+
   const rawMarkdown = await buildRawMarkdown(project);
   // The originals behind the rewritten `/blume-assets/content/…` references in
   // the agent-facing Markdown, plus the endpoint that serves them (and the
@@ -2047,7 +2114,7 @@ export const generateRuntime = async (
   // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
-    ...proxyAllowlistWarnings(playgroundProxy.enabled, proxyOrigins),
+    ...proxyAllowlistWarnings(config, openApiData),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
     ...mcp.warnings,
     ...islandDiscovery.warnings,

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,7 @@
 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";