blume 2.0.0 → 2.0.2

package/src/astro/generate.ts

@@ -31,7 +31,7 @@ import {
   hasDeferrableGroups,
   navVariants,
 } from "../components/layout/nav-utils.ts";
-import { normalizeBasePath } from "../core/base-path.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
@@ -81,7 +81,9 @@ import { ogCacheDir } from "../og/cache.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
-import type { ApiSpecData, OpenApiData } from "../openapi/model.ts";
+import type { AsyncApiSpecValue } from "../openapi/asyncapi.ts";
+import type { ApiSpecData, HttpMethod, OpenApiData } from "../openapi/model.ts";
+import { HTTP_METHODS, withServerDefaults } from "../openapi/model.ts";
 import {
   builtinProxyReferences,
   hasScalarReferences,
@@ -636,7 +638,7 @@ const writeIfChanged = async (
 
 /**
  * Delete generated files under `srcDir` that this pass didn't (re)write. The
- * generator emits many files conditionally — an Ask AI endpoint, OG images, a
+ * generator emits many files conditionally — an assistant endpoint, OG images, a
  * search index, RSS feeds, reference pages, the MCP server — so toggling a
  * feature off would otherwise leave a stale file behind, and a leftover
  * server-rendered endpoint breaks the static build. `writeIfChanged` only ever
@@ -954,6 +956,8 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
+  // `link.href` stays as authored; the link the banner renders is the
+  // navigation's `bannerHref`, localized and mounted under `basePath`.
   return {
     content: banner.content,
     dismissible: banner.dismissible,
@@ -1114,10 +1118,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     config: {
       analytics: config.analytics,
       appleIcon: resolveAppleIcon(project),
-      ask: config.ai.ask?.enabled
+      assistant: config.ai.assistant?.enabled
         ? {
-            endpoint: config.ai.ask.endpoint ?? null,
-            suggestions: config.ai.ask.suggestions,
+            endpoint: config.ai.assistant.endpoint ?? null,
+            suggestions: config.ai.assistant.suggestions,
           }
         : null,
       banner: resolveBanner(config),
@@ -1489,28 +1493,41 @@ const writeApiFiles = async (
   await Promise.all(writes);
 };
 
+/** The proxy endpoint's file under the Astro `src/` dir (eject writes it too). */
+export const PLAYGROUND_PROXY_ENTRY = join("blume-openapi", "api-proxy.ts");
+
+/** The URL the built-in proxy is injected at (see {@link planPlaygroundProxy}). */
+export const playgroundProxyPattern = (config: ResolvedConfig): string =>
+  withBasePath(config.basePath, "/_api-proxy");
+
 /**
  * Decide whether to generate the playground's built-in CORS proxy endpoint.
  * Only the Blume renderer's playground with `proxy: true` needs it — a proxy
  * URL string points at an external service, and `false` sends requests
  * directly. Injected at `/_api-proxy` (rather than written under `pages/`)
  * because Astro treats `_`-prefixed page files as private; the endpoint's own
- * `prerender = false` export wins over the injection default.
+ * `prerender = false` export wins over the injection default. Mounted under
+ * the site `basePath`, at the URL the playground sends to (see
+ * openapi/source.ts); Astro layers `deployment.base` onto both.
  */
 const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
   enabled: needsPlaygroundProxy(config),
-  entrypoint: join(srcDir, "blume-openapi", "api-proxy.ts"),
-  pattern: "/_api-proxy",
+  entrypoint: join(srcDir, PLAYGROUND_PROXY_ENTRY),
+  pattern: playgroundProxyPattern(config),
 });
 
 /**
  * The origins the built-in proxy is allowed to reach: one per absolute
- * `servers[].url` across the parsed specs. This is the endpoint's whole trust
- * boundary — the client sends the target as a query parameter, and a reader's
- * custom base URL is not a documented server — so it is derived here, at build
- * time, from the same documents the operation pages render.
+ * `servers[].url` across the parsed specs — the document's, each path item's,
+ * and each operation's, since an operation's playground sends to the most
+ * specific of those. This is the endpoint's whole trust boundary — the client
+ * sends the target as a query parameter, and a reader's custom base URL is not
+ * a documented server — so it is derived here, at build time, from the same
+ * documents the operation pages render.
  *
- * Relative (`/v1`) and templated (`{env}.api.example.com`) server URLs carry no
+ * A templated URL (`https://{env}.api.example.com`) is allowed as the
+ * playground sends it, with each variable at its declared default. Relative
+ * (`/v1`) URLs, and templates with a variable left undefaulted, carry no
  * origin to allow and are skipped; AsyncAPI documents declare `servers` as a
  * map and contribute nothing (the proxy is OpenAPI-only).
  */
@@ -1526,27 +1543,53 @@ const specOriginsOf = (spec: ApiSpecData): string[] => {
     }
   }
   // 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;
+  // the optional `servers` and `paths` shapes, and every access below
+  // re-checks them — `Array.isArray` guards each list, optional chaining each
+  // path item and operation, and `server.url ?? ""` the url.
+  const document = spec.document as {
+    paths?: Record<string, DocumentPathItem | null | undefined>;
+    servers?: DocumentServer[];
+  };
+  const lists = [document.servers];
+  for (const item of Object.values(document.paths ?? {})) {
+    lists.push(item?.servers);
+    for (const method of HTTP_METHODS) {
+      lists.push(item?.[method]?.servers);
     }
-    try {
-      origins.add(new URL(url).origin);
-    } catch {
-      // Not an absolute URL: nothing to allow.
+  }
+  for (const servers of lists) {
+    for (const server of Array.isArray(servers) ? servers : []) {
+      const url = withServerDefaults(server.url ?? "", server.variables);
+      // `new URL("https://{region}.api.example.com")` parses — the braces land
+      // in the hostname — so a variable with no default needs an explicit
+      // check or its 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[] =>
+/** A `servers[]` entry as a parsed spec document declares it. */
+interface DocumentServer {
+  url?: string;
+  variables?: AsyncApiSpecValue;
+}
+
+/** An OpenAPI path item: its own `servers` plus one per operation. */
+type DocumentPathItem = { servers?: DocumentServer[] } & Partial<
+  Record<HttpMethod, { servers?: DocumentServer[] } | null>
+>;
+
+/** The built-in proxy's allowlist: every spec's origins, deduped and sorted. */
+export const specOrigins = (data: OpenApiData): string[] =>
   [...new Set(Object.values(data).flatMap(specOriginsOf))].toSorted();
 
 /**
@@ -1558,7 +1601,7 @@ const specOrigins = (data: OpenApiData): string[] =>
  * whose own origins came out empty (no absolute `servers[].url`, no absolute
  * GraphQL `endpoint`) gets a warning naming it.
  */
-const proxyAllowlistWarnings = (
+export const proxyAllowlistWarnings = (
   config: ResolvedConfig,
   data: OpenApiData
 ): string[] => {
@@ -1573,16 +1616,16 @@ const proxyAllowlistWarnings = (
     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 \`endpoint\` on the graphql() adapter (or the source) 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.`
+        : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative URLs, and templated ones with a variable missing its default, 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
+ * Write the assistant endpoint and, unless the backend runs its own retrieval
  * (Inkeep), the grounding snapshot the endpoint queries at request time. A no-op
- * when Ask AI is disabled.
+ * when the assistant is disabled.
  */
 const writeAskFiles = async (
   project: BlumeProject,
@@ -1590,20 +1633,20 @@ const writeAskFiles = async (
   write: (path: string, content: string) => Promise<boolean>,
   modules: RuntimeModules
 ): Promise<void> => {
-  const { ask } = project.config.ai;
-  if (!(ask?.enabled && !ask.endpoint)) {
+  const { assistant } = project.config.ai;
+  if (!(assistant?.enabled && !assistant.endpoint)) {
     return;
   }
-  const backend = resolveAskBackend(ask.provider);
+  const backend = resolveAskBackend(assistant.provider);
   if (backend.grounded) {
     modules.set("blume:ask-data", JSON.stringify(await buildAskData(project)));
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
     askEndpointTemplate(backend, {
-      cors: ask.cors,
-      instructions: ask.instructions,
-      retrieval: ask.retrieval,
+      cors: assistant.cors,
+      instructions: assistant.instructions,
+      retrieval: assistant.retrieval,
     })
   );
 };
@@ -1645,7 +1688,7 @@ export const diagnosticWarning = (diagnostic: Diagnostic): string =>
 
 /**
  * Missing-dependency preflight: the search provider's SDK, content source
- * SDKs, the Ask AI backend's provider SDK, the deployment adapter's package,
+ * SDKs, the assistant backend's provider SDK, the deployment adapter's package,
  * and — since React ships with Blume while Vue/Svelte don't — any island
  * framework's Astro integration. A build fails here, before anything is
  * written, with the install command for the project's package manager —
@@ -1699,6 +1742,7 @@ export const analyzeComponentsFile = async (
 const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
   resolveOgFonts(
     {
+      locales: fontLocaleCodes(project.config.i18n),
       ogFonts: project.config.seo.og.fonts,
       themeFonts: project.config.theme.fonts,
       themeFontsConfigured: project.themeFontsConfigured,
@@ -1845,7 +1889,7 @@ export const generateRuntime = async (
   const homeLinkHeader =
     buildHomeLinkHeader(config, contentRoutes) ?? undefined;
 
-  const askEnabled = config.ai.ask?.enabled ?? false;
+  const assistantEnabled = config.ai.assistant?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
   // Every route's source Markdown: published as `blume:raw-markdown` below,
@@ -1897,7 +1941,7 @@ export const generateRuntime = async (
   project.examples = exampleMarkdownLookup(exampleDiscovery.examples);
 
   // Each island/example framework enables its Astro renderer. React also
-  // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
+  // switches on for any project `.tsx`/`.jsx` and for the assistant; Vue/Svelte are
   // island/example-driven. `.astro` examples need no renderer. Component
   // overrides referencing a framework component enable its renderer too.
   const frameworks = new Set<string>([
@@ -1906,7 +1950,8 @@ export const generateRuntime = async (
     ...slotPlan.frameworks,
   ]);
   const dependencyWarnings = await dependencyPreflight(project, frameworks);
-  const needsReact = detectedReact || askEnabled || frameworks.has("react");
+  const needsReact =
+    detectedReact || assistantEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
 
@@ -2025,7 +2070,7 @@ export const generateRuntime = async (
       // The header's Ask trigger, behind the `blume:ask` alias. Always written
       // (even when Ask is off, as a component that renders nothing) so the alias
       // resolves — the same contract as `blume:search-client`.
-      write(askPath, askComponentTemplate(askEnabled)),
+      write(askPath, askComponentTemplate(assistantEnabled)),
       write(join(srcDir, "generated", "components.ts"), slotPlan.module),
       write(
         join(srcDir, "generated", "examples.ts"),
@@ -2288,7 +2333,7 @@ export const generateRuntime = async (
     writeStagedContent(out, staged),
   ]);
 
-  // Remove anything under `.blume/src` this pass didn't write — e.g. an Ask AI
+  // Remove anything under `.blume/src` this pass didn't write — e.g. an assistant
   // endpoint left behind after the feature was switched off.
   await pruneOrphans(srcDir, written);
 

package/src/astro/module-types.ts

@@ -14,7 +14,7 @@
 export const runtimeModuleDeclarations = (
   examplesModule: string
 ): string => `declare module "blume:ask" {
-  const Ask: typeof import("blume/components/islands/AskAI.astro").default;
+  const Ask: typeof import("blume/components/islands/Assistant.astro").default;
   export default Ask;
 }
 

package/src/astro/runtime-deps.ts

@@ -85,18 +85,18 @@ export const sourceAdapterDependencies = (
   );
 
 /**
- * The Ask AI adapter's provider SDK, when missing — only `gateway` needs
+ * The assistant adapter's provider SDK, when missing — only `gateway` needs
  * nothing beyond the core `ai` package Blume ships. An external `endpoint`
  * means no generated route, so no SDK is imported.
  */
-export const askProviderDependencies = (
-  ask: ResolvedConfig["ai"]["ask"],
+export const assistantProviderDependencies = (
+  ask: ResolvedConfig["ai"]["assistant"],
   root: string,
   pkgDir: string = packageRoot()
 ): MissingDependency[] =>
   ask?.enabled && !ask.endpoint
     ? unresolved(
-        `Ask AI provider "${ask.provider.kind}"`,
+        `Assistant provider "${ask.provider.kind}"`,
         ask.provider.runtimeDeps,
         root,
         pkgDir
@@ -152,7 +152,7 @@ export const islandFrameworkDependencies = (
 /**
  * Every package the resolved config's adapters (and the given island
  * frameworks) import that isn't installed: the search SDK, content source
- * SDKs, the Ask AI provider SDK, the deployment adapter, and island
+ * SDKs, the assistant provider SDK, the deployment adapter, and island
  * integrations. The adapters' `runtimeDeps` are the one place that knows.
  */
 export const missingRuntimeDependencies = (
@@ -163,7 +163,7 @@ export const missingRuntimeDependencies = (
 ): MissingDependency[] => [
   ...searchProviderDependencies(config.search.provider, root, pkgDir),
   ...sourceAdapterDependencies(config.content.sources, root, pkgDir),
-  ...askProviderDependencies(config.ai.ask, root, pkgDir),
+  ...assistantProviderDependencies(config.ai.assistant, root, pkgDir),
   ...deploymentAdapterDependencies(config.deployment, root, pkgDir),
   ...islandFrameworkDependencies(frameworks, root),
 ];