blume 2.0.1 → 2.0.3

package/src/registry/eject.ts

@@ -3,10 +3,13 @@ import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 
 import { join, relative } from "pathe";
 
+import { OPENAPI_PATH } from "../ai/api/paths.ts";
+import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
+import type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
 import {
@@ -23,15 +26,25 @@ import {
   detectNeedsReact,
   detectUsesMath,
   languageIconCssFor,
+  PLAYGROUND_PROXY_ENTRY,
+  playgroundProxyPattern,
+  proxyAllowlistWarnings,
+  specOrigins,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPagesIndexTemplate,
+  apiPageTemplate,
+  apiSearchTemplate,
   askComponentTemplate,
   askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
+  contentAssetsEndpointTemplate,
   contentConfigTemplate,
   exampleMapTemplate,
   exampleSlug,
@@ -41,8 +54,11 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
+  playgroundProxyTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
   runtimeDependencies,
@@ -51,6 +67,7 @@ import {
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { collectContentAssets } from "../core/content-assets.ts";
 import { buildIncludeGraph } from "../core/includes.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
@@ -61,8 +78,12 @@ import {
 } from "../core/sources/collection.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { resolveOgFonts } from "../og/derive.ts";
 import type { OpenApiData } from "../openapi/model.ts";
-import { hasScalarReferences } from "../openapi/references.ts";
+import {
+  hasScalarReferences,
+  needsPlaygroundProxy,
+} from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
@@ -70,6 +91,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
+import { fontLocaleCodes } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
@@ -191,21 +213,70 @@ const mcpDiscoveryPages = (
     : [];
 
 /**
- * The MCP data snapshot, server endpoint, and `.well-known` discovery
- * documents, mirroring `writeMcpFiles` in generate.ts. Empty when the server
- * is disabled or its route is already owned by a page.
+ * The playground's built-in CORS proxy route (`playground: { proxy: true }`),
+ * mirroring `planPlaygroundProxy` in generate.ts: injected like the MCP
+ * discovery routes, because Astro treats a `_`-prefixed page file as private,
+ * and mounted under `basePath` at the URL the playground sends to. Empty when
+ * no reference routes its playground through it.
  */
-const mcpFiles = async (
+const playgroundProxyPages = (
+  config: BlumeProject["config"]
+): { entrypoint: string; pattern: string }[] =>
+  needsPlaygroundProxy(config)
+    ? [
+        {
+          entrypoint: toPosix(join("src", PLAYGROUND_PROXY_ENTRY)),
+          pattern: playgroundProxyPattern(config),
+        },
+      ]
+    : [];
+
+/**
+ * The proxy endpoint behind {@link playgroundProxyPages}, with the origin
+ * allowlist baked in from the same parsed specs the reference pages render.
+ */
+const playgroundProxyFiles = (
+  config: BlumeProject["config"],
+  openApiData: OpenApiData,
+  srcDir: string
+): { content: string; path: string }[] =>
+  needsPlaygroundProxy(config)
+    ? [
+        {
+          content: playgroundProxyTemplate(specOrigins(openApiData)),
+          path: join(srcDir, PLAYGROUND_PROXY_ENTRY),
+        },
+      ]
+    : [];
+
+/**
+ * The agent data snapshot (`blume:mcp-data`) behind the MCP server and the
+ * JSON docs API, mirroring `publishAgentData` in generate.ts: built when
+ * either is on, null when neither needs it.
+ */
+const ejectAgentData = async (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): Promise<McpData | null> =>
+  hostsMcp(project, userPages) || project.config.agents.api
+    ? await buildMcpData(project)
+    : null;
+
+/**
+ * The MCP server endpoint and `.well-known` discovery documents, mirroring
+ * `writeMcpFiles` in generate.ts. Empty when the server is disabled or its
+ * route is already owned by a page.
+ */
+const mcpFiles = (
   project: BlumeProject,
   userPages: { pattern: string }[],
   srcDir: string,
-  genDir: string
-): Promise<{ content: string; path: string }[]> => {
-  if (!hostsMcp(project, userPages)) {
+  data: McpData | null
+): { content: string; path: string }[] => {
+  if (!(data && hostsMcp(project, userPages))) {
     return [];
   }
   const { route } = project.config.agents.mcp;
-  const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -214,10 +285,6 @@ const mcpFiles = async (
     version: data.version,
   };
   return [
-    {
-      content: `${JSON.stringify(data)}\n`,
-      path: join(genDir, "mcp-data.json"),
-    },
     {
       content: mcpEndpointTemplate(),
       path: join(srcDir, "pages", mcpPageFile(route)),
@@ -233,6 +300,87 @@ const mcpFiles = async (
   ];
 };
 
+/**
+ * The JSON docs API, mirroring `planApi` and `writeApiFiles` in generate.ts:
+ * the prerendered page index, per-page documents, and navigation; on server
+ * output the search endpoint and, unless a user page or a content page already
+ * lives under `/api/`, the JSON 404 catch-all; and `/openapi.json`, unless a
+ * `public/openapi.json` or a page owns that route. The ejected `llms.txt`,
+ * homepage `Link` header, and 404 page advertise these routes, so the ejected
+ * app serves them. Empty when `agents.api` is off.
+ */
+const apiFiles = (
+  project: BlumeProject,
+  userPages: { pattern: string }[],
+  root: string,
+  srcDir: string,
+  data: McpData | null
+): { content: string; path: string }[] => {
+  const { config } = project;
+  if (!(data && config.agents.api)) {
+    return [];
+  }
+  const server = config.deployment.options.output === "server";
+  const apiDir = join(srcDir, "pages", "api");
+  const files = [
+    {
+      content: apiPagesIndexTemplate(),
+      path: join(apiDir, "docs", "pages.json.ts"),
+    },
+    {
+      content: apiPageTemplate(),
+      path: join(apiDir, "docs", "pages", "[...route].json.ts"),
+    },
+    {
+      content: apiNavigationTemplate(),
+      path: join(apiDir, "docs", "navigation.json.ts"),
+    },
+  ];
+  if (server) {
+    files.push({
+      content: apiSearchTemplate(),
+      path: join(apiDir, "docs", "search.ts"),
+    });
+  }
+  const apiOwned =
+    userPages.some((page) => page.pattern.startsWith("/api/[")) ||
+    project.graph.pages.some(
+      (page) => page.route === "/api" || page.route.startsWith("/api/")
+    );
+  if (server && !apiOwned) {
+    files.push({
+      content: apiNotFoundTemplate({ base: data.base, site: data.site }),
+      path: join(apiDir, "[...path].ts"),
+    });
+  }
+  if (
+    !(
+      routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) ||
+      existsSync(join(root, "public", "openapi.json"))
+    )
+  ) {
+    files.push({
+      content: staticJsonEndpointTemplate(
+        buildApiSpec({
+          agentReadability: config.agents.agentReadability,
+          base: data.base,
+          description: config.description,
+          llmsTxt: config.agents.llmsTxt.enabled,
+          mcpRoute: hostsMcp(project, userPages)
+            ? config.agents.mcp.route
+            : null,
+          name: config.title,
+          search: server,
+          site: data.site,
+          version: data.version,
+        })
+      ),
+      path: join(srcDir, "pages", "openapi.json.ts"),
+    });
+  }
+  return files;
+};
+
 /**
  * The `/changelog` index page, mirroring `shouldGenerateChangelog` in
  * generate.ts: emitted when `type: changelog` entries or a release-backed
@@ -265,6 +413,59 @@ const changelogFiles = (
   ];
 };
 
+/**
+ * The colocated-image map and the `/blume-assets/[...asset]` endpoint that
+ * serves it, mirroring generate.ts: the ejected raw Markdown points
+ * `![x](./diagram.png)` at `/blume-assets/content/…`, and the config aliases
+ * `blume:content-assets` to the map. Each original's path is written relative
+ * to the project root (the directory `astro dev`/`astro build` run from), so
+ * the ejected app builds from any checkout. Remote-source images need no
+ * endpoint: eject copies them into the project's own `public/blume-assets`.
+ */
+const contentAssetFiles = async (
+  project: BlumeProject,
+  root: string,
+  srcDir: string,
+  genDir: string
+): Promise<{ content: string; path: string }[]> => {
+  const assets = await collectContentAssets(project);
+  const portable = Object.fromEntries(
+    Object.entries(assets).map(([param, abs]) => [
+      param,
+      toPosix(relative(root, abs)),
+    ])
+  );
+  return [
+    {
+      content: `${JSON.stringify(portable)}\n`,
+      path: join(genDir, "content-assets.json"),
+    },
+    {
+      content: contentAssetsEndpointTemplate(null),
+      path: join(srcDir, "pages", "blume-assets", "[...asset].ts"),
+    },
+  ];
+};
+
+/**
+ * The partial → including-pages map with every path relative to the project
+ * root, like every other path in the ejected app, so it holds in any checkout.
+ * Its readers (`includeHmrPlugin`, `withIncludeRefresh`) resolve each path
+ * against the app's root, which after eject is the project itself.
+ */
+const portableIncludeGraph = (
+  project: BlumeProject,
+  root: string
+): Record<string, string[]> =>
+  Object.fromEntries(
+    Object.entries(buildIncludeGraph(project.graph.pages)).map(
+      ([partial, includers]) => [
+        toPosix(relative(root, partial)),
+        includers.map((page) => toPosix(relative(root, page))),
+      ]
+    )
+  );
+
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
 /**
  * Read a user stylesheet that eject inlines into a generated entry under
@@ -309,16 +510,18 @@ const examplesPreviewFiles = (
 
 /**
  * The packages the ejected app imports by bare name: Astro, Tailwind's Vite
- * plugin, `blume` itself, the integrations the config wires in, whatever the
- * configured adapters declare, and React when islands, examples, or the assistant
- * render with it (Blume ships React, so projects rarely list it). They have
- * to be the project's own dependencies after eject — under a strict linker
- * such as pnpm nothing else makes them resolvable, and `astro build` fails.
- * The hidden runtime reaches the same packages through its `node_modules`
- * junction into Blume's own, so only eject declares the ones its generated
- * files import directly: the AI SDK the assistant route streams through (unless
- * `ai.assistant.endpoint` points elsewhere, when no route is written) and the EPUB
- * generator's browser bundle `features.ts` loads.
+ * plugin, Tailwind and its typography plugin (which the generated `app.css`
+ * and `examples.css` import by name), `blume` itself, the integrations the
+ * config wires in, whatever the configured adapters declare, and React when
+ * islands, examples, or the assistant render with it (Blume ships React, so
+ * projects rarely list it). They have to be the project's own dependencies
+ * after eject — under a strict linker such as pnpm nothing else makes them
+ * resolvable, and `astro build` fails. The hidden runtime reaches the same
+ * packages through its `node_modules` junction into Blume's own, so only
+ * eject declares the ones its generated files import directly: the AI SDK the
+ * assistant route streams through (unless `ai.assistant.endpoint` points
+ * elsewhere, when no route is written) and the EPUB generator's browser bundle
+ * `features.ts` loads (only named there when `export.epub` is on).
  */
 const ejectDependencies = (
   options: Parameters<typeof runtimeDependencies>[0]
@@ -328,6 +531,8 @@ const ejectDependencies = (
     ...new Set([
       "astro",
       "@tailwindcss/vite",
+      "tailwindcss",
+      "@tailwindcss/typography",
       "blume",
       ...runtimeDependencies(options),
       ...(options.needsReact ? ["react", "react-dom"] : []),
@@ -439,7 +644,9 @@ export const eject = async (
       pattern: page.pattern,
     })),
     ...mcpDiscoveryPages(project, pages),
+    ...playgroundProxyPages(config),
   ];
+  const openApiData = ejectOpenApiData(project);
 
   // Non-filesystem sources eject their materialized MDX into `<root>/blume-staged`
   // (a dedicated dir so it never clashes with a content root literally named
@@ -555,7 +762,7 @@ export const eject = async (
       path: join(genDir, "Ask.astro"),
     },
     {
-      content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
+      content: `${JSON.stringify(openApiData)}\n`,
       path: join(genDir, "openapi.json"),
     },
     {
@@ -568,7 +775,7 @@ export const eject = async (
       // hot update's read would silently no-op and partial edits would serve
       // stale pages. A snapshot like the rest of `src/generated`: the ejected
       // app owns (and may regenerate or prune) it.
-      content: `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`,
+      content: `${JSON.stringify(portableIncludeGraph(project, root))}\n`,
       path: join(genDir, "includes.json"),
     },
     {
@@ -581,40 +788,85 @@ export const eject = async (
     },
   ];
 
+  files.push(...(await contentAssetFiles(project, root, srcDir, genDir)));
+
   if (assistantEnabled) {
     files.push(...(await askFiles(project, srcDir, genDir)));
   }
 
+  // The `/changelog` index, mirrored from the generated runtime (`[]` when
+  // the project has no changelog). The OG endpoint below adds its card.
+  const changelog = changelogFiles(project, pages, srcDir, {
+    exportEpub,
+    exportPdf,
+    needsReact,
+    staged: hasStaged,
+  });
+
   if (config.seo.og.enabled) {
+    // The default script fallbacks ride along (Google family names, nothing
+    // machine-specific), so a non-Latin card still renders after eject. An
+    // explicit seo.og.fonts replaces them, and isn't carried over.
+    const { fallbacks, families } = resolveOgFonts(
+      {
+        locales: fontLocaleCodes(config.i18n),
+        ogFonts: config.seo.og.fonts,
+        themeFonts: config.theme.fonts,
+        themeFontsConfigured: false,
+      },
+      root
+    );
     files.push({
       content: ogEndpointTemplate(
         customOgRoutes(pages, config.title, config.seo.og.titles),
-        { pageDescriptions: config.seo.og.description !== false }
+        {
+          fallbacks,
+          families,
+          pageDescriptions: config.seo.og.description !== false,
+        },
+        changelog.length > 0
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }
 
-  // The hosted MCP server and the `/changelog` index, mirrored from the
-  // generated runtime (each helper returns `[]` when its feature is off).
+  // The hosted MCP server, the JSON docs API, and the playground's built-in
+  // proxy, mirrored from the generated runtime (`[]` when each is off). The
+  // server and the API share one agent data snapshot.
+  const agentData = await ejectAgentData(project, pages);
+  if (agentData) {
+    files.push({
+      content: `${JSON.stringify(agentData)}\n`,
+      path: join(genDir, "mcp-data.json"),
+    });
+  }
   files.push(
-    ...(await mcpFiles(project, pages, srcDir, genDir)),
-    ...changelogFiles(project, pages, srcDir, {
-      exportEpub,
-      exportPdf,
-      needsReact,
-      staged: hasStaged,
-    })
+    ...mcpFiles(project, pages, srcDir, agentData),
+    ...apiFiles(project, pages, root, srcDir, agentData),
+    ...changelog,
+    ...playgroundProxyFiles(config, openApiData, srcDir)
   );
 
-  // Default 404 page, unless the project already owns `/404` (a custom
-  // `pages/404.astro` or a `404.md` content page). The ejected project owns the
-  // file afterwards and can edit or remove it.
+  // Default 404 page and its Markdown (`/404.md`) and JSON (`/404.json`)
+  // twins, mirroring `writeNotFoundPage` in generate.ts: all three are skipped
+  // when the project already owns `/404` (a custom `pages/404.astro` or a
+  // `404.md` content page). The ejected project owns the files afterwards and
+  // can edit or remove them.
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
-    files.push({
-      content: notFoundPageTemplate(),
-      path: join(srcDir, "pages", "404.astro"),
-    });
+    files.push(
+      {
+        content: notFoundPageTemplate(),
+        path: join(srcDir, "pages", "404.astro"),
+      },
+      {
+        content: notFoundMarkdownTemplate(),
+        path: join(srcDir, "pages", "404.md.ts"),
+      },
+      {
+        content: notFoundJsonTemplate(),
+        path: join(srcDir, "pages", "404.json.ts"),
+      }
+    );
   }
 
   // The client-feature loaders behind the `blume:features` alias, and the
@@ -673,7 +925,9 @@ export const eject = async (
   // the ejected app keeps its reference routes — including the warnings (a
   // missing spec file, a route collision), which the caller surfaces exactly
   // like the generated-runtime path does.
-  const warnings: string[] = [];
+  // A proxied spec with no origin to allow gets the generated runtime's
+  // diagnostic too.
+  const warnings: string[] = proxyAllowlistWarnings(config, openApiData);
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/search/adapters/version-scope.ts

@@ -0,0 +1,30 @@
+import type { SearchAdapterKind } from "./registry.ts";
+
+/**
+ * Whether each adapter's client can filter results to one docs version. The
+ * source-built indexes (Orama, FlexSearch) store every document's `version`,
+ * and the Algolia and Typesense syncs upload it as a facet their clients
+ * filter on. Pagefind indexes the built HTML with no version metadata, the
+ * Orama Cloud sync uploads no `version`, and the Mixedbread endpoint takes no
+ * filter, so those always search every version. Keyed by every kind so a new
+ * adapter has to decide.
+ */
+const SCOPES_VERSIONS = {
+  algolia: true,
+  flexsearch: true,
+  mixedbread: false,
+  none: false,
+  orama: true,
+  "orama-cloud": false,
+  pagefind: false,
+  typesense: true,
+} satisfies Record<SearchAdapterKind, boolean>;
+
+/**
+ * Whether the configured search adapter scopes results to the viewed docs
+ * version. The search dialog offers its "All versions" toggle only when it
+ * does: on the others the toggle would change nothing, and every query
+ * already spans all versions.
+ */
+export const scopesVersions = (kind: SearchAdapterKind): boolean =>
+  SCOPES_VERSIONS[kind];