blume 1.6.5 → 1.7.0

package/src/astro/integration.ts

@@ -1,10 +1,18 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
+import { join, relative, resolve } from "pathe";
 
+import { loadEnvFiles } from "../cli/env.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
+import { scanProject } from "../core/project-graph.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
+import { publishBuildArtifacts } from "../deploy/artifacts.ts";
+import type { ArtifactLogger } from "../deploy/artifacts.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
+import { runtimeModuleDeclarations } from "./module-types.ts";
 
 /** The `{ type: "error" }` payload Vite's browser overlay renders. */
 interface OverlayErrorPayload {
@@ -26,13 +34,150 @@ interface OverlayServer {
   ws?: OverlayChannel;
 }
 
-// Set on `astro:server:setup`; read by `showBlumeErrorOverlay` so the CLI's
-// regeneration can push Blume diagnostics into Vite's browser error overlay.
-// Same-process module singleton (dev and the integration share the instance).
-let overlayServer: OverlayServer | null = null;
+/** The parameters Astro hands `astro:server:setup`. */
+type ServerSetupParams = Parameters<
+  NonNullable<AstroIntegration["hooks"]["astro:server:setup"]>
+>[0];
 
-const overlayChannel = (): OverlayChannel | undefined =>
-  overlayServer?.ws ?? overlayServer?.hot;
+/**
+ * Astro's `refreshContent`: re-runs every content-layer loader against the
+ * live store, the sanctioned way to re-sync content that changed outside
+ * Astro's own file watcher.
+ */
+type RefreshContent = NonNullable<ServerSetupParams["refreshContent"]>;
+
+/** What the dev negotiation middleware needs per request. */
+interface DevNegotiation {
+  /** Page routes that have a raw-Markdown variant (the content manifest). */
+  contentRoutes: ReadonlySet<string>;
+  /** Homepage agent-discovery `Link` header, when the site has one. */
+  homeLinkHeader?: string;
+}
+
+/**
+ * The state shared between the CLI and the integration: the live dev server
+ * (for the browser error overlay), Astro's `refreshContent` (so the CLI's
+ * regeneration can re-sync the content store instead of restarting the
+ * server), the negotiation inputs the CLI publishes on every regeneration (so
+ * a content-route change never rewrites the generated config, which would
+ * restart the server in place), and the scanned project a `blume build`
+ * hands over so `astro:build:done` can write the deploy artifacts.
+ *
+ * Kept on `globalThis` rather than in module state, for the same reason as
+ * the runtime-module registry (see `runtime-modules.ts`): on a published
+ * install the CLI bundle (`dist/cli`) carries its own copy of this module,
+ * while the hooks run in the copy Vite loads from `blume/astro` for the
+ * generated config. A module-level variable is set in one copy and read in
+ * the other, so the overlay never showed anything outside this repository.
+ */
+interface DevServerRegistry {
+  buildProject: BlumeProject | null;
+  negotiation: DevNegotiation | null;
+  overlay: OverlayServer | null;
+  refreshContent: RefreshContent | null;
+}
+
+const REGISTRY_KEY = Symbol.for("blume.integration");
+
+type RegistryHost = typeof globalThis & {
+  [REGISTRY_KEY]?: DevServerRegistry;
+};
+
+const registry = (): DevServerRegistry => {
+  // 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] ??= {
+    buildProject: null,
+    negotiation: null,
+    overlay: null,
+    refreshContent: null,
+  };
+  return host[REGISTRY_KEY];
+};
+
+/**
+ * Hand the scanned project to the integration ahead of `build()`, so its
+ * `astro:build:done` hook can write the deploy artifacts without scanning
+ * again. `blume build` publishes it for a real build and nothing for an
+ * isolated verify build, which produces no artifacts. `null` withdraws it.
+ */
+export const publishBuildProject = (project: BlumeProject | null): void => {
+  registry().buildProject = project;
+};
+
+/**
+ * The project an `astro build` with no CLI in front of it (an ejected app)
+ * writes artifacts for: scanned from `buildArtifactsRoot`, resolved against
+ * the Astro root recorded on `astro:config:done`. Scan diagnostics surface as
+ * warnings — there is no `--strict` to honor here, and the build itself has
+ * already succeeded. `null` when nothing asked for a scan.
+ */
+const scanForArtifacts = async (
+  astroRoot: URL | null,
+  artifactsRoot: string | undefined,
+  logger: ArtifactLogger
+): Promise<BlumeProject | null> => {
+  if (!(astroRoot && artifactsRoot)) {
+    return null;
+  }
+  const root = resolve(fileURLToPath(astroRoot), artifactsRoot);
+  // Remote sources read their tokens from the environment during the scan.
+  loadEnvFiles(root);
+  const project = await scanProject(root, { mode: "build" });
+  for (const diagnostic of project.diagnostics) {
+    logger.warn(`[${diagnostic.code}] ${diagnostic.message}`);
+  }
+  return project;
+};
+
+/**
+ * Publish the dev negotiation inputs for the running server: the content
+ * routes with a Markdown variant and the homepage `Link` header. Called by
+ * `generateRuntime` on every pass, so the middleware follows a route rename
+ * without the generated config changing. `null` withdraws a publication, so
+ * the middleware falls back to the options baked into the integration call
+ * (an ejected project has no CLI to publish).
+ */
+export const publishDevNegotiation = (
+  negotiation: {
+    contentRoutes: readonly string[];
+    homeLinkHeader?: string;
+  } | null
+): void => {
+  registry().negotiation = negotiation
+    ? {
+        contentRoutes: new Set(negotiation.contentRoutes),
+        homeLinkHeader: negotiation.homeLinkHeader,
+      }
+    : null;
+};
+
+/**
+ * Re-run Astro's content-layer loaders against the live dev server. Returns
+ * `false` when no server has registered one — before the first
+ * `astro:server:setup`, or outside `blume dev` — so the caller can fall back.
+ * A route-set change (a page added, removed, or a folder renamed) is what
+ * needs this: Astro's glob watcher misses directory renames, and its in-place
+ * config restart never re-globs, so without a re-sync `getEntry` reads a
+ * stale store and the moved page 404s.
+ */
+export const refreshBlumeContent = async (): Promise<boolean> => {
+  const { refreshContent } = registry();
+  if (!refreshContent) {
+    return false;
+  }
+  // No loader filter: every collection re-syncs (the docs glob and any
+  // staged collection alike).
+  await refreshContent({});
+  return true;
+};
+
+const overlayChannel = (): OverlayChannel | undefined => {
+  const { overlay } = registry();
+  return overlay?.ws ?? overlay?.hot;
+};
 
 /**
  * Surface Blume's own diagnostics (config/frontmatter/content errors) in the
@@ -85,36 +230,41 @@ export interface BlumePageRoute {
 
 export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
-  /** Page routes that have a raw-Markdown variant (the content manifest). */
-  contentRoutes: string[];
-  /** Configured `deployment.base`, stripped from dev URLs before matching. */
-  base?: string;
+  /**
+   * Page routes that have a raw-Markdown variant (the content manifest). The
+   * hidden runtime leaves this out: the CLI publishes the live set through
+   * `publishDevNegotiation` on every regeneration, so a route change never
+   * rewrites the generated config. An ejected project, which has no CLI,
+   * bakes it in here.
+   */
+  contentRoutes?: string[];
   /**
    * Homepage `Link` header value for agent discovery (see
    * `ai/link-headers.ts`); the dev-server counterpart of the `_headers` /
    * Vercel-config emission, so `curl -I` against `blume dev` shows what the
-   * deployed site will send.
+   * deployed site will send. Published the same way as `contentRoutes`.
    */
   homeLinkHeader?: string;
+  /**
+   * Blume project root to scan on `astro:build:done` for the deploy artifacts
+   * (search index, llms.txt, sitemap, …) when no CLI has published the
+   * project — an ejected app running plain `astro build`. Relative to the
+   * Astro root. The hidden runtime leaves it unset: `blume build` publishes
+   * its already-scanned project instead.
+   */
+  buildArtifactsRoot?: string;
 }
 
 /**
  * Whether a dev-server request URL is the homepage: the path (query dropped,
- * `deployment.base` stripped, trailing slash tolerated) is the root.
+ * trailing slash tolerated) is the root.
  */
-const isHomeUrl = (rawUrl: string | undefined, base?: string): boolean => {
+const isHomeUrl = (rawUrl: string | undefined): boolean => {
   if (!rawUrl) {
     return false;
   }
   const queryIndex = rawUrl.indexOf("?");
-  let path = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
-  const prefix = base && base !== "/" ? base.replace(/\/$/u, "") : "";
-  if (prefix) {
-    if (path !== prefix && !path.startsWith(`${prefix}/`)) {
-      return false;
-    }
-    path = path.slice(prefix.length);
-  }
+  const path = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
   return path === "" || path === "/";
 };
 
@@ -134,16 +284,26 @@ const isHomeUrl = (rawUrl: string | undefined, base?: string): boolean => {
  * page (see `markdownRoutePaths`). The same
  * middleware also stamps the homepage agent-discovery `Link` header, mirroring
  * what the deployed site sends via `_headers` / the Vercel routing config.
+ *
+ * Request URLs arrive base-less: Astro unshifts its own dev middlewares (base,
+ * trailing slash, route guard) ahead of this one from its post-`configureServer`
+ * hook, and its base middleware has already rewritten `/<base>/guide` to
+ * `/guide`. Stripping `deployment.base` here a second time would leave no
+ * request matching a content route.
  */
 const negotiateMarkdown =
-  (routes: ReadonlySet<string>, base?: string, homeLinkHeader?: string) =>
+  (fallback: DevNegotiation) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    // Read per request: the CLI republishes on every regeneration, so a page
+    // renamed while the server runs negotiates under its new route.
+    const { contentRoutes, homeLinkHeader } =
+      registry().negotiation ?? fallback;
     if (req.method === "GET" || req.method === "HEAD") {
-      if (homeLinkHeader && isHomeUrl(req.url, base)) {
+      if (homeLinkHeader && isHomeUrl(req.url)) {
         res.setHeader("Link", homeLinkHeader);
       }
       if (prefersMarkdown(req.headers.accept)) {
-        const variant = markdownVariantUrl(req.url, routes, base);
+        const variant = markdownVariantUrl(req.url, contentRoutes);
         if (variant) {
           res.setHeader("Vary", "Accept");
           req.url = variant;
@@ -153,40 +313,107 @@ const negotiateMarkdown =
     next();
   };
 
+/** The `.d.ts` the integration injects for the `blume:*` virtual modules. */
+const MODULE_TYPES_FILE = "modules.d.ts";
+
+/**
+ * Where Astro writes an integration's injected types when the integration
+ * never asked for its codegen dir (a config run whose `astro:config:setup`
+ * was skipped — the test fixtures). Mirrors Astro's own convention.
+ */
+const defaultCodegenDir = (root: URL): URL =>
+  new URL(".astro/integrations/blume/", root);
+
 /**
  * Blume's Astro integration. Mounts user-authored pages from `pages/` into the
  * generated runtime via `injectRoute`, keeping each file in its original
- * location so relative imports and `getStaticPaths` keep working, and teaches
- * the dev server to honor `Accept: text/markdown`.
+ * location so relative imports and `getStaticPaths` keep working; declares
+ * the `blume:*` virtual modules' types through `injectTypes`; and teaches the
+ * dev server to honor `Accept: text/markdown`.
  */
 export const blumeIntegration = (
   options: BlumeIntegrationOptions
-): AstroIntegration => ({
-  hooks: {
-    "astro:config:setup": ({ injectRoute }) => {
-      for (const page of options.pages) {
-        injectRoute({
-          entrypoint: page.entrypoint,
-          pattern: page.pattern,
-          prerender: true,
+): AstroIntegration => {
+  // Astro hands out the codegen dir on `astro:config:setup`; the types are
+  // injected on `astro:config:done`, once `srcDir` is final, and the
+  // `blume:examples` declaration needs the path between the two.
+  let codegenDir: URL | null = null;
+  // The Astro root, kept for the build-artifacts scan: `astro:build:done`
+  // receives no config.
+  let astroRoot: URL | null = null;
+  return {
+    hooks: {
+      "astro:build:done": async ({ dir, logger }) => {
+        const project =
+          registry().buildProject ??
+          (await scanForArtifacts(
+            astroRoot,
+            options.buildArtifactsRoot,
+            logger
+          ));
+        if (!project) {
+          return;
+        }
+        // `dir` is what Astro reports as the client output — `dist/`, or
+        // `dist/client` for a server build — which is what the platform
+        // serves (the Vercel adapter copies it into its Build Output static
+        // tree in a later hook).
+        await publishBuildArtifacts(project, fileURLToPath(dir), logger);
+      },
+      "astro:config:done": ({ config, injectTypes }) => {
+        astroRoot = config.root;
+        const from = fileURLToPath(
+          codegenDir ?? defaultCodegenDir(config.root)
+        );
+        const examplesModule = relative(
+          from,
+          join(fileURLToPath(config.srcDir), "generated", "examples.ts")
+        );
+        injectTypes({
+          content: runtimeModuleDeclarations(examplesModule),
+          filename: MODULE_TYPES_FILE,
         });
-      }
-    },
-    "astro:server:setup": ({ server }) => {
-      // Keep a handle on the dev server so Blume diagnostics can be pushed to
-      // its browser error overlay (see `showBlumeErrorOverlay`).
-      overlayServer = server;
-      // Prepend so the rewrite happens before Astro's own request handler,
-      // letting the rewritten URL resolve to the `.md` endpoint.
-      server.middlewares.stack.unshift({
-        handle: negotiateMarkdown(
-          new Set(options.contentRoutes),
-          options.base,
-          options.homeLinkHeader
-        ),
-        route: "",
-      });
+      },
+      "astro:config:setup": ({
+        addMiddleware,
+        createCodegenDir,
+        injectRoute,
+      }) => {
+        codegenDir = createCodegenDir();
+        // Splices each page's icon sprite in once the page has rendered (see
+        // components/icon-sprite-middleware.ts). Innermost, so a project's
+        // own middleware sees the finished HTML.
+        addMiddleware({
+          entrypoint: "blume/components/icon-sprite-middleware.ts",
+          order: "post",
+        });
+        for (const page of options.pages) {
+          injectRoute({
+            entrypoint: page.entrypoint,
+            pattern: page.pattern,
+            prerender: true,
+          });
+        }
+      },
+      "astro:server:setup": ({ refreshContent, server }) => {
+        // Keep a handle on the dev server so Blume diagnostics can be pushed
+        // to its browser error overlay (see `showBlumeErrorOverlay`), and on
+        // Astro's content re-sync so a route-set change needs no restart
+        // (see `refreshBlumeContent`).
+        const shared = registry();
+        shared.overlay = server;
+        shared.refreshContent = refreshContent ?? null;
+        // Prepend so the rewrite happens before Astro's own request handler,
+        // letting the rewritten URL resolve to the `.md` endpoint.
+        server.middlewares.stack.unshift({
+          handle: negotiateMarkdown({
+            contentRoutes: new Set(options.contentRoutes),
+            homeLinkHeader: options.homeLinkHeader,
+          }),
+          route: "",
+        });
+      },
     },
-  },
-  name: "blume",
-});
+    name: "blume",
+  };
+};

package/src/astro/module-types.ts

@@ -0,0 +1,83 @@
+/**
+ * Ambient declarations for the `blume:*` virtual modules the generated pages
+ * and Blume's own layouts import. The integration hands them to Astro through
+ * `injectTypes` on `astro:config:done`, so they land under
+ * `.astro/integrations/blume/` and are referenced from Astro's generated
+ * `types.d.ts` — the same channel `astro:content` and `astro:env` use — rather
+ * than a hand-written `src/env.d.ts` the generator and eject each had to
+ * write. Every project that mounts the integration gets the types with it.
+ *
+ * `examplesModule` is the path of the generated `examples.ts` relative to the
+ * declaration file: the `blume:examples` map is typed from that module's
+ * literal export so `<Component path>` lookups stay typed per project.
+ */
+export const runtimeModuleDeclarations = (
+  examplesModule: string
+): string => `declare module "blume:ask" {
+  const Ask: typeof import("blume/components/islands/AskAI.astro").default;
+  export default Ask;
+}
+
+declare module "blume:data" {
+  const data: import("blume").BlumeData;
+  export default data;
+}
+
+declare module "blume:ask-data" {
+  const askData: import("blume/ai/ask-context.ts").AskData;
+  export default askData;
+}
+
+declare module "blume:content-assets" {
+  const assets: Record<string, string>;
+  export default assets;
+}
+
+declare module "blume:mcp-data" {
+  const data: import("blume/ai/mcp/data.ts").McpData;
+  export default data;
+}
+
+declare module "blume:raw-markdown" {
+  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
+  export default raw;
+}
+
+declare module "blume:rss" {
+  const feeds: Record<string, string>;
+  export default feeds;
+}
+
+declare module "blume:search-index" {
+  const documents: import("blume/search/documents.ts").SearchDocument[];
+  export default documents;
+}
+
+declare module "blume:examples" {
+  type Examples = typeof import(${JSON.stringify(examplesModule)}).examples;
+  export const examples: Record<string, Examples[keyof Examples]>;
+  export const examplesBase: string;
+}
+
+declare module "blume:examples-theme";
+
+declare module "blume:openapi" {
+  const specs: import("blume/openapi/model.ts").OpenApiData;
+  export default specs;
+}
+
+declare module "blume:features" {
+  /** Registers the <blume-mermaid> element; null when no page has a mermaid fence. */
+  export const loadMermaid: (() => Promise<unknown>) | null;
+  /** The EPUB generator's browser bundle; null when export.epub is off. */
+  export const loadEpub:
+    | (() => Promise<typeof import("epub-gen-memory/bundle")>)
+    | null;
+}
+
+declare module "blume:search-client" {
+  export const createSearch: () =>
+    | import("blume/components/layout/search/types.ts").SearchFn
+    | Promise<import("blume/components/layout/search/types.ts").SearchFn>;
+}
+`;