blume 1.7.3 → 2.0.1

package/src/ai/api/handlers.ts

@@ -154,19 +154,43 @@ export const buildPage = (data: McpData, route: string): ApiPage | null => {
   return { ...summarize(entry, data), markdown };
 };
 
+/** The 404 for a route no page has, at its per-page JSON path. */
+const pageNotFoundResponse = (
+  route: string,
+  context: ApiSiteContext
+): Response =>
+  problemResponse({
+    code: "PAGE_NOT_FOUND",
+    detail: `No documentation page has the route "${route}".`,
+    instance: siteUrl(pageJsonPath(route), context),
+    resolution: `List every page at ${siteUrl(API_PAGES_PATH, context)}, or discover the API through ${siteUrl(OPENAPI_PATH, context)}.`,
+    status: 404,
+    title: "Page not found",
+  });
+
 export const pageResponse = (data: McpData, route: string): Response => {
   const page = buildPage(data, route);
-  if (!page) {
-    return problemResponse({
-      code: "PAGE_NOT_FOUND",
-      detail: `No documentation page has the route "${route}".`,
-      instance: siteUrl(pageJsonPath(route), data),
-      resolution: `List every page at ${siteUrl(API_PAGES_PATH, data)}, or discover the API through ${siteUrl(OPENAPI_PATH, data)}.`,
-      status: 404,
-      title: "Page not found",
-    });
+  return page ? jsonResponse(page) : pageNotFoundResponse(route, data);
+};
+
+const PAGE_JSON_PATH = /^\/api\/docs\/pages\/(?<param>.+)\.json$/u;
+
+/**
+ * The route a base-less `pages/{route}.json` path asks for (`index` is the
+ * home page), or `undefined` for any other path.
+ */
+const requestedPageRoute = (path: string): string | undefined => {
+  const param = PAGE_JSON_PATH.exec(path)?.groups?.param;
+  if (param === undefined) {
+    return undefined;
+  }
+  let decoded = param;
+  try {
+    decoded = decodeURIComponent(param);
+  } catch {
+    // A malformed escape names no page either; report it as written.
   }
-  return jsonResponse(page);
+  return decoded === "index" ? "/" : `/${decoded}`;
 };
 
 /** The default navigation tree (default locale, current docs). */
@@ -248,13 +272,24 @@ export const createSearchHandler = (
 /**
  * The 404 for anything under `/api/` that no endpoint answers — the catch-all
  * behind every live route on server output, so an agent probing the API
- * namespace gets a problem document instead of the HTML not-found page.
+ * namespace gets a problem document instead of the HTML not-found page. A
+ * `pages/{route}.json` miss gets the per-page `PAGE_NOT_FOUND` problem.
  */
 export const apiNotFoundResponse = (
   request: Request,
   context: ApiSiteContext
 ): Response => {
   const { pathname } = new URL(request.url);
+  // Per-page JSON is prerendered, so a route no page has falls through to
+  // this catch-all on server output; answer it as the page miss it is.
+  const baseless =
+    context.base && pathname.startsWith(`${context.base}/`)
+      ? pathname.slice(context.base.length)
+      : pathname;
+  const route = requestedPageRoute(baseless);
+  if (route !== undefined) {
+    return pageNotFoundResponse(route, context);
+  }
   return problemResponse({
     code: "API_ROUTE_NOT_FOUND",
     detail: `No API route exists at ${pathname}.`,

package/src/ai/api/paths.ts

@@ -1,7 +1,7 @@
 /**
  * Where the JSON docs API and its OpenAPI description are served. Base-less
  * (like every route Blume emits); callers layer `deployment.base` on top.
- * Under `/api/` alongside the Ask AI endpoint (`/api/ask`) so the namespace a
+ * Under `/api/` alongside the assistant endpoint (`/api/ask`) so the namespace a
  * Blume site reserves for live endpoints stays one prefix, and under its own
  * `docs` segment so a search provider's proxy at `/api/search` never collides.
  */

package/src/ai/api-catalog.ts

@@ -30,8 +30,8 @@ const HTTP_URL = /^https?:\/\//u;
 
 /** The catalog's linkset entries; empty when the site publishes no APIs. */
 const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
-  const site = config.deployment.site ?? null;
-  const deployBase = normalizeBasePath(config.deployment.base);
+  const site = config.deployment.options.site ?? null;
+  const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
     return site ? absoluteUrl(site, based) : based;
@@ -42,9 +42,9 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
     // Blume-rendered pages mount under `basePath`; Scalar pages stay at the
     // raw route (see `referenceRoutes`).
     const docRoute =
-      reference.renderer === "blume"
-        ? withBasePath(reference.basePath, reference.route)
-        : reference.route;
+      reference.kind === "scalar"
+        ? reference.route
+        : withBasePath(reference.basePath, reference.route);
     const entry: LinksetEntry = {
       anchor: abs(docRoute),
       "service-doc": [{ href: abs(docRoute), type: "text/html" }],
@@ -57,7 +57,7 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
     entries.push(entry);
   }
 
-  if (config.ai.api) {
+  if (config.agents.api) {
     entries.push({
       anchor: abs(API_BASE),
       "service-desc": [{ href: abs(OPENAPI_PATH), type: "application/json" }],
@@ -65,9 +65,9 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
     });
   }
 
-  if (config.ai.mcp.enabled) {
+  if (config.agents.mcp.enabled) {
     entries.push({
-      anchor: abs(config.ai.mcp.route),
+      anchor: abs(config.agents.mcp.route),
       "service-desc": [
         { href: abs("/.well-known/mcp.json"), type: "application/json" },
       ],

package/src/ai/ask-context.ts

@@ -4,7 +4,7 @@ import type { FenceState } from "../core/code-fences.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
 
-/** A chat message as posted by the Ask AI island (`{ role, content }`). */
+/** A chat message as posted by the assistant island (`{ role, content }`). */
 export interface AskMessage {
   content: string;
   role: string;
@@ -16,7 +16,7 @@ export interface AskPage {
 }
 
 /**
- * The self-contained snapshot the grounded Ask AI endpoint imports. Bundles the
+ * The self-contained snapshot the assistant's grounded endpoint imports. Bundles the
  * search documents so retrieval works regardless of the configured search
  * provider and needs no filesystem access at request time. Serialized to
  * `generated/ask-data.json` and built by {@link buildAskData}.
@@ -47,7 +47,7 @@ const CONTEXT_BUDGET = 10_000;
 const MIN_EXCERPT_CHARS = 200;
 
 /**
- * How much retrieved documentation a question carries (the `ai.ask.retrieval`
+ * How much retrieved documentation a question carries (the `ai.assistant.retrieval`
  * config). Every field falls back to the built-in default, so a partial object
  * only changes what it names. Injected characters dominate time-to-first-token
  * on a self-hosted backend, and the three knobs aren't interchangeable: the
@@ -309,7 +309,7 @@ const interleave = (lists: OramaDoc[][], limit: number): OramaDoc[] => {
  *
  * Pages are indexed whole (one document each), so a naive head slice of a long
  * page returns its intro and misses sections below the fold — the exact failure
- * where "How does Ask AI work?" retrieves the right page but only sees its
+ * where "How does the assistant work?" retrieves the right page but only sees its
  * opening paragraph. This centers the window on the densest cluster of query
  * terms so the injected text is the part that actually answers the question.
  * Exported for testing; {@link createAskContext} is the runtime entry point.
@@ -585,7 +585,7 @@ export const sectionExcerpt = (
 ): string => excerptPage(parsePage(content), query, max);
 
 /**
- * Build the request-time grounding function for the Ask AI endpoint.
+ * Build the request-time grounding function for the assistant endpoint.
  *
  * Lexical retrieval over Orama (the same index/ranking the search dialog and MCP
  * server use). The index is built once and memoized across requests. Returns a
@@ -593,12 +593,12 @@ export const sectionExcerpt = (
  * viewing — or `undefined` when there is nothing to ground on, so the endpoint
  * can fall back to its plain prompt.
  *
- * `options.instructions` (the `ai.ask.instructions` config) is appended after
+ * `options.instructions` (the `ai.assistant.instructions` config) is appended after
  * the base instruction rather than replacing it: the base carries the
  * functional contract (answer only from the excerpts, cite pages as Markdown
  * links) that the panel's citation rendering depends on.
  *
- * `options.retrieval` (the `ai.ask.retrieval` config) sizes how much
+ * `options.retrieval` (the `ai.assistant.retrieval` config) sizes how much
  * documentation each question carries; omitted fields keep today's defaults.
  */
 export const createAskContext = (

package/src/ai/ask-data.ts

@@ -3,8 +3,8 @@ import { buildSearchDocuments } from "../search/documents.ts";
 import type { AskData } from "./ask-context.ts";
 
 /**
- * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
- * Ask AI is independent of on-page search, so documents are indexed even when the
+ * Build the grounding snapshot the assistant endpoint serves. Like the MCP server,
+ * the assistant is independent of on-page search, so documents are indexed even when the
  * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
  * MCP snapshot) so retrieval can be filtered to the current page's language, and
  * content is kept as Markdown so grounding sees fenced code examples — the model
@@ -28,6 +28,6 @@ export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
       route: doc.route,
       title: doc.title,
     })),
-    site: project.config.deployment.site ?? null,
+    site: project.config.deployment.options.site ?? null,
   };
 };