blume 2.0.0 → 2.0.2

package/src/ai/index.ts

@@ -1,5 +1,5 @@
 /**
- * Ask AI provider adapters for `blume.config.ts`:
+ * Assistant provider adapters for `blume.config.ts`:
  *
  * ```ts
  * import { defineConfig } from "blume";
@@ -7,7 +7,7 @@
  *
  * export default defineConfig({
  *   ai: {
- *     ask: {
+ *     assistant: {
  *       enabled: true,
  *       provider: openrouter({ model: "anthropic/claude-sonnet-4-5" }),
  *     },
@@ -27,19 +27,19 @@ export {
   openrouter,
 } from "./ask.ts";
 export type {
-  AskAdapter,
-  AskAdapterOptions,
-  AskGatewayAdapter,
-  AskGatewayOptions,
-  AskInkeepAdapter,
-  AskInkeepOptions,
-  AskLlmGatewayAdapter,
-  AskLlmGatewayOptions,
-  AskOpenAICompatibleAdapter,
-  AskOpenAICompatibleOptions,
-  AskOpenRouterAdapter,
-  AskOpenRouterOptions,
-  AskProviderOptions,
-  AskReasoning,
+  AssistantAdapter,
+  AssistantAdapterOptions,
+  AssistantGatewayAdapter,
+  AssistantGatewayOptions,
+  AssistantInkeepAdapter,
+  AssistantInkeepOptions,
+  AssistantLlmGatewayAdapter,
+  AssistantLlmGatewayOptions,
+  AssistantOpenAICompatibleAdapter,
+  AssistantOpenAICompatibleOptions,
+  AssistantOpenRouterAdapter,
+  AssistantOpenRouterOptions,
+  AssistantProviderOptions,
+  AssistantReasoning,
 } from "./ask.ts";
 export type { AdapterDescriptor } from "../core/adapter.ts";

package/src/ai/link-headers.ts

@@ -5,7 +5,11 @@ import {
   AI_CATALOG_TYPE,
   hasAiCatalog,
 } from "./ai-catalog.ts";
-import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  hasApiCatalog,
+} from "./api-catalog.ts";
 import { OPENAPI_PATH } from "./api/paths.ts";
 
 /**
@@ -37,10 +41,11 @@ export const buildHomeLinkHeader = (
   const deployBase = normalizeBasePath(config.deployment.options.base);
   const links: string[] = [];
   // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
-  // well-known catalog.
+  // well-known catalog. Its type carries the RFC 9727 profile, whose quotes
+  // are escaped inside the quoted `type` value (RFC 8288 quoted-string).
   if (hasApiCatalog(config)) {
     links.push(
-      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="application/linkset+json"`
+      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="${API_CATALOG_TYPE.replaceAll('"', String.raw`\"`)}"`
     );
   }
   // The ai-catalog spec's own relation for its well-known document, the

package/src/ai/llms.ts

@@ -312,10 +312,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
           source: raw,
           sourcePath: page.sourcePath,
         });
-        // Relative page links too: a reader of one flat file has no page URL
-        // to resolve `./install` against.
-        raw = rewriteLinks(raw, page);
       }
+      // Page links too: a reader of one flat file has no page URL to resolve
+      // `./install` against, and `/install` needs the base the site is
+      // served under.
+      raw = rewriteLinks(raw, page);
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.

package/src/ai/markdown.ts

@@ -8,6 +8,7 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
+import { advertisedConfig, servesMcp } from "./agent-surface.ts";
 import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
@@ -80,13 +81,14 @@ export const buildRawMarkdown = async (
           source: text,
           sourcePath: route.sourcePath,
         });
-        // `./install` means the page's sibling, not whatever the `.md` URL
-        // an agent fetched resolves it to.
-        text = rewriteLinks(text, {
-          route: route.path,
-          sourcePath: route.sourcePath,
-        });
       }
+      // `./install` means the page's sibling, not whatever the `.md` URL an
+      // agent fetched resolves it to, and `/install` gains the base and the
+      // page's locale the rendered link has — remote content included.
+      text = rewriteLinks(text, {
+        route: route.path,
+        sourcePath: route.sourcePath,
+      });
       const source = applyAgentVisibility(text);
       // The `.md` variant keeps the front-matter block in the output, but its
       // data must also be in scope for `prop={frontmatter.*}` expressions.
@@ -97,19 +99,29 @@ export const buildRawMarkdown = async (
     })
   );
   const map = Object.fromEntries(entries);
+  const userPages = project.context.pagesRoot
+    ? await discoverPages(project.context.pagesRoot)
+    : [];
   // A landing-page homepage (user `.astro` page, or no home route at all) has
   // no Markdown source, but agents negotiating `Accept: text/markdown` on `/`
   // still expect a Markdown answer. The llms.txt index — the machine-readable
   // representation of the site a landing page fronts — becomes its mirror, so
-  // `/index.md` always exists (see `markdownRoutePaths`).
+  // `/index.md` always exists (see `markdownRoutePaths`). Like llms.txt, it
+  // leaves out an MCP server a page's route kept from being generated.
   if (!map["/"]) {
-    map["/"] = { mdx: buildLlmsIndex(project) };
+    map["/"] = {
+      mdx: buildLlmsIndex({
+        ...project,
+        config: advertisedConfig(project.config, {
+          mcp: servesMcp(project, userPages),
+          // Skills are collected at the end of the build, after this runs.
+          skills: Boolean(project.config.agents.skills),
+        }),
+      }),
+    };
   }
   // The generated changelog index has no source either; its release list is
   // its mirror, so `/changelog.md` and `get_page` answer as the page does.
-  const userPages = project.context.pagesRoot
-    ? await discoverPages(project.context.pagesRoot)
-    : [];
   if (hasGeneratedChangelog(project, userPages)) {
     map[CHANGELOG_INDEX_ROUTE] = { mdx: buildChangelogIndexMarkdown(project) };
   }

package/src/ai/mcp/server.ts

@@ -2,7 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
-  CallToolRequestSchema,
+  ErrorCode,
   ListResourcesRequestSchema,
   ListToolsRequestSchema,
   McpError,
@@ -11,6 +11,7 @@ import {
 import { z } from "zod";
 
 import { withBasePath } from "../../core/base-path.ts";
+import { readCappedText } from "../../core/request-body.ts";
 import type { McpData } from "./data.ts";
 import {
   createIndexProvider,
@@ -42,6 +43,12 @@ const RESOURCE_MIME_TYPE = "text/markdown";
 const RESOURCE_NOT_FOUND = -32_002;
 /** URI scheme for page resources when no `deployment.site` is configured. */
 const LOCAL_RESOURCE_SCHEME = "blume:";
+/**
+ * The largest request body the HTTP endpoint reads. A JSON-RPC call to these
+ * tools is a few hundred bytes; the cap keeps one oversized POST from being
+ * buffered whole, as the assistant route's does.
+ */
+const MCP_BODY_LIMIT_BYTES = 65_536;
 
 const CORS_HEADERS = {
   "Access-Control-Allow-Headers":
@@ -108,6 +115,20 @@ const resourceRoute = (uri: string, data: McpData): string =>
     data
   );
 
+/**
+ * The `tools/call` params, as far as the server reads them before dispatch:
+ * each tool validates its own `arguments` against `TOOL_INPUTS`.
+ */
+const TOOL_CALL_PARAMS = z.object({
+  arguments: z.record(z.string(), z.unknown()).optional(),
+  name: z.string(),
+});
+
+/** A tool call's `arguments` object, before the tool's own validation. */
+type ToolArguments = NonNullable<
+  z.output<typeof TOOL_CALL_PARAMS>["arguments"]
+>;
+
 /** A tool call's text result, marked as an error when `isError` is set. */
 const text = (value: string, isError = false) => {
   const content = [{ text: value, type: "text" as const }];
@@ -165,9 +186,7 @@ export const buildServer = (
     };
   });
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { arguments: args = {}, name } = request.params;
-
+  const callTool = async (name: string, args: ToolArguments) => {
     if (name === "search_docs") {
       const results = await searchDocs(
         data,
@@ -206,12 +225,44 @@ export const buildServer = (
       return text(JSON.stringify(result.navigation, null, 2));
     }
 
-    return text(`Unknown tool: ${name}`, true);
-  });
+    // The MCP spec answers an unknown tool with a protocol error, not a
+    // failed tool result.
+    throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+  };
+
+  // `tools/call` goes through the fallback handler rather than a registered
+  // one: the SDK parses a registered handler's request against its own
+  // schema first and reports a malformed call (`arguments` that aren't an
+  // object) as -32603 Internal error carrying a raw Zod dump. Reading the
+  // params here answers it as -32602 Invalid params with a short message.
+  server.fallbackRequestHandler = async (request) => {
+    if (request.method !== "tools/call") {
+      throw new McpError(ErrorCode.MethodNotFound, "Method not found");
+    }
+    const params = TOOL_CALL_PARAMS.safeParse(request.params);
+    if (!params.success) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "Invalid tools/call params: `name` must be a string and `arguments`, when given, an object."
+      );
+    }
+    return await callTool(params.data.name, params.data.arguments ?? {});
+  };
 
   return server;
 };
 
+/** A JSON-RPC error response the transport would send, for errors raised before it runs. */
+const jsonRpcError = (
+  status: number,
+  code: number,
+  message: string
+): Response =>
+  Response.json(
+    { error: { code, message }, id: null, jsonrpc: "2.0" },
+    { headers: CORS_HEADERS, status }
+  );
+
 /**
  * Build a stateless Streamable-HTTP MCP request handler from a data snapshot.
  *
@@ -239,6 +290,26 @@ export const createMcpFetchHandler = (
       });
     }
 
+    // The transport would read the body with `request.json()`, buffering
+    // whatever a client sends; read it under the cap first and hand the
+    // transport a copy.
+    let forwarded = request;
+    if (request.method === "POST") {
+      const body = await readCappedText(request, MCP_BODY_LIMIT_BYTES);
+      if (body === undefined) {
+        return jsonRpcError(
+          413,
+          ErrorCode.InvalidRequest,
+          "Request too large: the body must be at most 64 KB."
+        );
+      }
+      forwarded = new Request(request.url, {
+        body,
+        headers: request.headers,
+        method: "POST",
+      });
+    }
+
     const server = buildServer(data, index);
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
@@ -248,7 +319,7 @@ export const createMcpFetchHandler = (
       sessionIdGenerator: undefined,
     });
     await server.connect(transport);
-    const response = await transport.handleRequest(request);
+    const response = await transport.handleRequest(forwarded);
 
     const headers = new Headers(response.headers);
     for (const [key, value] of Object.entries(CORS_HEADERS)) {

package/src/ai/openapi-components.ts

@@ -44,7 +44,7 @@ const listItem = (
  * the body plus one of these components, deliberately: the structured UI is the
  * component's job, and the prose stays Markdown so it indexes. That split is
  * right for the rendered page and lossy everywhere else — `<route>.md`,
- * llms-full.txt, MCP `get_page` and the Ask AI corpus all downlevel components
+ * llms-full.txt, MCP `get_page` and the assistant corpus all downlevel components
  * to Markdown, and these three had no serializer, so an operation page reached
  * an agent as its description followed by a bare tag. On a site whose reference
  * is most of the corpus, that is most of the corpus: measured on one 449-page

package/src/ai/relative-links.ts

@@ -1,8 +1,14 @@
 import { basename } from "pathe";
 
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  isInternalPath,
+  normalizeBasePath,
+  withBasePath,
+  withComposedBasePath,
+} from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
+import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
   isIndexFileName,
@@ -10,19 +16,25 @@ import {
   routeOfLinkedFile,
 } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
+import { localizeHref } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
 
 /**
- * Relative page links on the agent surfaces — the `.md`/`.mdx` mirrors,
+ * Page links on the agent surfaces — the `.md`/`.mdx` mirrors,
  * llms-full.txt, MCP `get_page` and `resources/read`. An agent resolves
  * `[Install](./install)` against the URL it fetched (`/guides.md`), so the
  * link lands on `/install`; the rendered page rewrites it to the route it
  * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
  * the same rewrite from the same resolver (`resolveRelativeHref`), so both
- * point at one page. Inline links and reference definitions are rewritten;
- * fenced and inline code, images, and anything not a relative page link are
- * left as written.
+ * point at one page. Root-relative page links (`[x](/guide)`,
+ * `<Card href="/guide">`) get what the rendered page gives them too: the
+ * `deployment.base` + `basePath` prefix (`markdown/base-links.ts`,
+ * `components/content/base-href.ts`) and, on a page in a prefixed locale,
+ * that locale's copy of the route when it is served
+ * (`components/layout/LocaleLinks.astro`). Inline links, component `href`s,
+ * and reference definitions are rewritten; fenced and inline code, images,
+ * asset links, and external URLs are left as written.
  */
 
 /** The page a Markdown text was written for. */
@@ -47,6 +59,21 @@ const DEFINITION =
 const MAYBE_RELATIVE =
   /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/|#)/imu;
 
+/**
+ * {@link MAYBE_RELATIVE}, or a root-relative target (`/x`, never `//host`):
+ * the gate when root-relative links are rewritten too — a base or basePath is
+ * set, or the page sits under a locale prefix.
+ */
+const MAYBE_PAGE_LINK =
+  /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/\/|#)/imu;
+
+/**
+ * A path whose final segment carries a file extension — a `public/` asset or
+ * a raw `.md` twin, which the rendered page neither bases nor localizes (see
+ * `markdown/base-links.ts`).
+ */
+const ASSET_PATH = /\.[\da-z]+$/iu;
+
 interface Splice {
   column: number;
   length: number;
@@ -124,7 +151,7 @@ const collectSplices = (
 export const relativeLinkRewriter = (
   project: BlumeProject
 ): RelativeLinkRewriter => {
-  const { deployment, i18n } = project.config;
+  const { basePath, deployment, i18n } = project.config;
   const deployBase = normalizeBasePath(deployment.options.base);
   const localeTokens = i18n
     ? ["$", ...i18n.locales.map((locale) => locale.code)]
@@ -137,11 +164,20 @@ export const relativeLinkRewriter = (
     ])
   );
   const routes = new Set(project.manifest.routes.map((route) => route.path));
+  const localeByRoute = new Map(
+    project.manifest.routes.map((route) => [route.path, route.locale])
+  );
 
-  return (text, page) => {
+  /**
+   * A page's relative-link resolver; `undefined` when the page has no file
+   * to resolve its links from.
+   */
+  const relativeRoute = (
+    page: LinkedPage
+  ): ((target: string) => string | undefined) | undefined => {
     const { sourcePath } = page;
-    if (!sourcePath || !MAYBE_RELATIVE.test(text)) {
-      return text;
+    if (!sourcePath) {
+      return;
     }
     const from: RelativeLinkBase = {
       isIndex: isIndexFileName(basename(sourcePath), localeTokens),
@@ -150,12 +186,44 @@ export const relativeLinkRewriter = (
     const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
     const resolveFile = (path: string): string | undefined =>
       routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
-    const routed = (target: string): string | undefined => {
+    return (target) => {
       const route = resolveRelativeHref(target, from, resolveFile, (path) =>
         routes.has(path)
       );
       return route === undefined ? undefined : withBasePath(deployBase, route);
     };
+  };
+
+  return (text, page) => {
+    const locale = localeByRoute.get(page.route);
+    // The page's locale moves root links only when it has a URL prefix.
+    const localize =
+      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
+        ? { basePath, deployBase, i18n, locale, routes }
+        : undefined;
+    // A root-relative link only changes when the site is mounted under a
+    // prefix or the page reads in a prefixed locale.
+    const rootLinks =
+      deployBase !== "" || basePath !== "" || localize !== undefined;
+    if (
+      !(page.sourcePath || rootLinks) ||
+      !(rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text)
+    ) {
+      return text;
+    }
+    const relative = relativeRoute(page);
+    // What the rendered page makes of `/guide`: based, then moved into the
+    // page's locale when that route is served.
+    const rooted = (target: string): string | undefined => {
+      if (ASSET_PATH.test(target.replace(/[#?].*$/u, ""))) {
+        return undefined;
+      }
+      const based = withComposedBasePath(deployBase, basePath, target);
+      const href = localize ? localizeHref(based, localize) : based;
+      return href === target ? undefined : href;
+    };
+    const routed = (target: string): string | undefined =>
+      isInternalPath(target) ? rooted(target) : relative?.(target);
 
     const lines = text.split("\n");
     const splices = collectSplices(text, lines, routed);

package/src/ai/serializers.ts

@@ -6,7 +6,7 @@ import { openapiComponentSerializers } from "./openapi-components.ts";
 
 /**
  * Every serializer a project brings to a downlevel pass, layered once for all
- * the agent surfaces (`<route>.md`, llms-full.txt, the search and Ask AI
+ * the agent surfaces (`<route>.md`, llms-full.txt, the search and assistant
  * corpora): the built-in families that read project data — examples, then the
  * API reference — under the user's `agents.markdownComponents`, which is spread
  * last so an entry of the same name still wins. One layering, so a new family