blume 2.0.2 → 2.1.0

package/src/ai/cors.ts

@@ -61,6 +61,8 @@ export const preflightResponse = (
 
 /** The slice of Astro's `APIContext` the wrapped handler reads. */
 interface RequestContext {
+  /** The reader's address, which the route's rate limit keys on. */
+  readonly clientAddress?: string;
   request: Request;
 }
 

package/src/ai/index.ts

@@ -20,23 +20,35 @@
  * nothing here runs at request time.
  */
 export {
+  anthropic,
   gateway,
+  gemini,
+  grok,
   inkeep,
   llmgateway,
+  openai,
   openaiCompatible,
   openrouter,
 } from "./ask.ts";
 export type {
   AssistantAdapter,
   AssistantAdapterOptions,
+  AssistantAnthropicAdapter,
+  AssistantAnthropicOptions,
   AssistantGatewayAdapter,
   AssistantGatewayOptions,
+  AssistantGeminiAdapter,
+  AssistantGeminiOptions,
+  AssistantGrokAdapter,
+  AssistantGrokOptions,
   AssistantInkeepAdapter,
   AssistantInkeepOptions,
   AssistantLlmGatewayAdapter,
   AssistantLlmGatewayOptions,
+  AssistantOpenAIAdapter,
   AssistantOpenAICompatibleAdapter,
   AssistantOpenAICompatibleOptions,
+  AssistantOpenAIOptions,
   AssistantOpenRouterAdapter,
   AssistantOpenRouterOptions,
   AssistantProviderOptions,

package/src/ai/link-headers.ts

@@ -33,24 +33,33 @@ import { OPENAPI_PATH } from "./api/paths.ts";
  * headers. Targets are
  * root-relative under `deployment.base` — RFC 8288 resolves them against the
  * request URL. Returns null when nothing is advertisable.
+ *
+ * `surface` is where the header is sent. A deployed site (`"build"`) serves
+ * every target. The dev server (`"dev"`) serves the routes — the JSON API's
+ * OpenAPI document and the Markdown mirror — but not the files `blume build`
+ * writes after the build (the API and AI catalogs, `agent-readability.json`,
+ * `llms.txt`), so its header leaves those out rather than point agents at
+ * 404s.
  */
 export const buildHomeLinkHeader = (
   config: ResolvedConfig,
-  routePaths: readonly string[]
+  routePaths: readonly string[],
+  surface: "build" | "dev" = "build"
 ): string | null => {
   const deployBase = normalizeBasePath(config.deployment.options.base);
+  const artifacts = surface === "build";
   const links: string[] = [];
   // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
   // 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)) {
+  if (artifacts && hasApiCatalog(config)) {
     links.push(
       `<${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
   // header form of the `<link rel="ai-catalog">` every page carries.
-  if (hasAiCatalog(config)) {
+  if (artifacts && hasAiCatalog(config)) {
     links.push(
       `<${deployBase}${AI_CATALOG_PATH}>; rel="ai-catalog"; type="${AI_CATALOG_TYPE}"`
     );
@@ -62,12 +71,12 @@ export const buildHomeLinkHeader = (
       `<${deployBase}${OPENAPI_PATH}>; rel="service-desc"; type="application/json"`
     );
   }
-  if (config.agents.agentReadability) {
+  if (artifacts && config.agents.agentReadability) {
     links.push(
       `<${deployBase}/agent-readability.json>; rel="describedby"; type="application/json"`
     );
   }
-  if (config.agents.llmsTxt.enabled) {
+  if (artifacts && config.agents.llmsTxt.enabled) {
     links.push(
       `<${deployBase}/llms.txt>; rel="describedby"; type="text/plain"`
     );

package/src/ai/llms.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -12,19 +12,31 @@ import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
-import { AGENT_SKILLS_DIR, AGENT_SKILLS_INDEX_PATH } from "./skills.ts";
+import {
+  AGENT_SKILLS_DIR,
+  AGENT_SKILLS_INDEX_PATH,
+  servesSkillsIndex,
+} from "./skills.ts";
 import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
-// with or without a `site` (the mcp.json convention) — so the emitted URL
-// matches where the page is served. Encoded like the sitemap: a route with
-// spaces or non-ASCII must still yield a valid Markdown link.
+// with or without a `site` (the mcp.json convention), and even over a route
+// that starts with the base's own name — so the emitted URL matches where the
+// page is served. Encoded like the sitemap: a route with spaces or non-ASCII
+// must still yield a valid Markdown link.
 const pageUrl = (route: string, site?: string, base = ""): string => {
-  const path = withBasePath(base, route);
+  const path = mountBasePath(base, route);
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
+/**
+ * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
+ * — closes or nests the text early, and the line stops being a link.
+ */
+const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
+
 /** Inputs only the build has: the published skills, collected once per build. */
 export interface LlmsIndexOptions {
   /**
@@ -67,7 +79,7 @@ const agentResourceLines = (project: BlumeProject): string[] => {
       `- [MCP server](${url(config.agents.mcp.route)}): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: ${url("/.well-known/mcp.json")}`
     );
   }
-  if (config.agents.skills) {
+  if (servesSkillsIndex(config)) {
     lines.push(
       `- [Agent skills](${url(AGENT_SKILLS_INDEX_PATH)}): Agent Skills discovery index of the skills this site publishes.`
     );
@@ -176,7 +188,7 @@ export const buildLlmsIndex = (
   const line = (page: PageRecord): string => {
     seen.add(page.route);
     const summary = page.description ? `: ${page.description}` : "";
-    return `- [${page.title}](${pageUrl(page.route, site, base)})${summary}`;
+    return `- [${linkText(page.title)}](${pageUrl(page.route, site, base)})${summary}`;
   };
 
   // One nav level -> Markdown blocks: the level's loose pages as a link list,
@@ -259,7 +271,10 @@ export const buildLlmsIndex = (
     blocks.push(
       "## RSS Feeds",
       feeds
-        .map((feed) => `- [${feed.title}](${pageUrl(feed.path, site, base)})`)
+        .map(
+          (feed) =>
+            `- [${linkText(feed.title)}](${pageUrl(feed.path, site, base)})`
+        )
         .join("\n")
     );
   }

package/src/ai/markdown.ts

@@ -14,6 +14,7 @@ import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
 import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
+import { servesSkillsIndex } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -115,7 +116,7 @@ export const buildRawMarkdown = async (
         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),
+          skills: servesSkillsIndex(project.config),
         }),
       }),
     };

package/src/ai/mcp/data.ts

@@ -130,6 +130,12 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
       if (doc.facets) {
         document.facets = doc.facets;
       }
+      if (doc.boost !== undefined) {
+        document.boost = doc.boost;
+      }
+      if (doc.keywords) {
+        document.keywords = doc.keywords;
+      }
       return document;
     }),
     instructions: config.agents.mcp.instructions,

package/src/ai/mcp/discovery.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import { trimChar } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
@@ -18,7 +18,7 @@ export interface McpDiscoveryInput {
 const serverUrl = (input: McpDiscoveryInput): string => {
   // The endpoint is a generated Astro page, so it's served under
   // `deployment.base` like every other route (the sitemap/llms.txt convention).
-  const path = withBasePath(input.base, input.route);
+  const path = mountBasePath(input.base, input.route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
   return input.site ? absoluteUrl(input.site, path) : path;

package/src/ai/mcp/query.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
 
 import {
+  mountBasePath,
   normalizeRoute as normalizePageRoute,
   stripBasePath,
-  withBasePath,
 } from "../../core/base-path.ts";
 import { absoluteUrl } from "../../core/site-url.ts";
 import { trimEnd } from "../../core/trim.ts";
@@ -244,7 +244,7 @@ export const normalizeRoute = (input: string, data: McpData): string => {
 export const urlFor = (route: string, data: McpData): string => {
   // Routes are base-less manifest paths; layer `deployment.base` on top so the
   // URL matches where the page is served (the sitemap/llms.txt convention).
-  const path = withBasePath(data.base, route);
+  const path = mountBasePath(data.base, route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
   return data.site ? absoluteUrl(data.site, path) : path;

package/src/ai/mcp/server.ts

@@ -10,7 +10,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { readCappedText } from "../../core/request-body.ts";
 import type { McpData } from "./data.ts";
 import {
@@ -104,7 +104,7 @@ interface PageResource {
 const resourceUri = (route: string, data: McpData): string =>
   data.site
     ? urlFor(route, data)
-    : `${LOCAL_RESOURCE_SCHEME}${withBasePath(data.base, route)}`;
+    : `${LOCAL_RESOURCE_SCHEME}${mountBasePath(data.base, route)}`;
 
 /** The `pages` key a resource URI (either form, or a bare route) names. */
 const resourceRoute = (uri: string, data: McpData): string =>

package/src/ai/openapi-components.ts

@@ -1,3 +1,4 @@
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
 import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
@@ -20,10 +21,14 @@ const inlineText = (text: string): string =>
     .replaceAll(/\s+/gu, " ")
     .replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
 
-/** One operation as a link, for the tag listings. */
+/**
+ * One operation as a link, for the tag listings. `href` is the operation's
+ * served URL: its route under the deployment base.
+ */
 const listItem = (
   signature: string,
-  operation: Pick<ApiOperationRef, "deprecated" | "route" | "summary">
+  href: string,
+  operation: Pick<ApiOperationRef, "deprecated" | "summary">
 ): string => {
   const tail = [
     // Title-like summaries ("Get a flag") need their own period before the
@@ -33,7 +38,7 @@ const listItem = (
   ]
     .filter(Boolean)
     .join(" ");
-  return `- [${inlineCode(signature)}](${linkDestination(operation.route)})${tail ? ` — ${tail}` : ""}`;
+  return `- [${inlineCode(signature)}](${linkDestination(href)})${tail ? ` — ${tail}` : ""}`;
 };
 
 /**
@@ -60,9 +65,16 @@ const listItem = (
  * endpoint and what it does is the part that was missing altogether.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
- * API reference, in which case every serializer declines.
+ * API reference, in which case every serializer declines. `deployBase` is the
+ * configured `deployment.base`: operation routes carry `basePath` but not it,
+ * and the links written here are made after the agent surfaces rebase the
+ * page's own links, so they take it here, as the rendered page's do.
  */
-export const openapiComponentSerializers = (specs: OpenApiData) => {
+export const openapiComponentSerializers = (
+  specs: OpenApiData,
+  deployBase?: string
+) => {
+  const base = normalizeBasePath(deployBase);
   const spec = (source: EvaluatedValue) =>
     isString(source) ? specOf(specs, source) : undefined;
 
@@ -97,7 +109,11 @@ export const openapiComponentSerializers = (specs: OpenApiData) => {
       const items = Object.values(data.operations)
         .filter((operation) => operation.tagSlug === tag)
         .map((operation) =>
-          listItem(operationSignature(data, operation), operation)
+          listItem(
+            operationSignature(data, operation),
+            mountBasePath(base, operation.route),
+            operation
+          )
         );
       return items.length > 0 ? items.join("\n") : null;
     },
@@ -118,9 +134,15 @@ export const openapiComponentSerializers = (specs: OpenApiData) => {
         return null;
       }
       const signature = inlineCode(operationSignature(data, operation));
-      return operation.deprecated
-        ? `${signature}\n\n**Deprecated.**`
-        : signature;
+      const notes = [
+        // An agent reading the page must not take a webhook for an endpoint
+        // it can call.
+        operation.webhook
+          ? "**Webhook.** The API sends this request to your endpoint."
+          : "",
+        operation.deprecated ? "**Deprecated.**" : "",
+      ].filter(Boolean);
+      return [signature, ...notes].join("\n\n");
     },
   } satisfies Record<string, ComponentMarkdown>;
 };

package/src/ai/relative-links.ts

@@ -2,9 +2,10 @@ import { basename } from "pathe";
 
 import {
   isInternalPath,
+  mountBasePath,
   normalizeBasePath,
+  withAuthoredBasePath,
   withBasePath,
-  withComposedBasePath,
 } from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
@@ -16,7 +17,7 @@ import {
   routeOfLinkedFile,
 } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
-import { localizeHref } from "../core/locale-links.ts";
+import { localizeHref, servesRoute } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
 
@@ -27,14 +28,16 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * 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. 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,
+ * point at one page. Root-relative links (`[x](/guide)`,
+ * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
+ * gives them too (`markdown/base-links.ts`,
+ * `components/content/base-href.ts`): a page link the `deployment.base` +
+ * `basePath` prefix, a public file (`/spec.pdf`) or image the
+ * `deployment.base` alone, and, on a page in a prefixed locale, a page link
  * 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.
+ * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * `href`s, and reference definitions are rewritten; fenced and inline code,
+ * relative images and asset links, and external URLs are left as written.
  */
 
 /** The page a Markdown text was written for. */
@@ -67,13 +70,6 @@ const MAYBE_RELATIVE =
 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;
@@ -109,18 +105,23 @@ const definitionSplice = (
   return { column: lead.length + angled, length: target.length, text: route };
 };
 
-/** Every routed splice in `text`, by 0-based line: links, then definitions. */
+/**
+ * Every routed splice in `text`, by 0-based line: links and images, then
+ * definitions. An image target goes through `imaged`, everything else through
+ * `routed`.
+ */
 const collectSplices = (
   text: string,
   lines: readonly string[],
-  routed: (target: string) => string | undefined
+  routed: (target: string) => string | undefined,
+  imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
   const splices = new Map<number, Splice[]>();
   const add = (index: number, splice: Splice): void => {
     splices.set(index, [...(splices.get(index) ?? []), splice]);
   };
   for (const link of extractLinks(text)) {
-    const route = link.image ? undefined : routed(link.target);
+    const route = (link.image ? imaged : routed)(link.target);
     if (route !== undefined) {
       add(link.line - 1, {
         column: link.column - 1,
@@ -186,14 +187,19 @@ export const relativeLinkRewriter = (
     const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
     const resolveFile = (path: string): string | undefined =>
       routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
+    // A resolved route is one Blume serves, so the deployment base goes on
+    // unconditionally — even over a route that starts with the base's name.
     return (target) => {
       const route = resolveRelativeHref(target, from, resolveFile, (path) =>
         routes.has(path)
       );
-      return route === undefined ? undefined : withBasePath(deployBase, route);
+      return route === undefined ? undefined : mountBasePath(deployBase, route);
     };
   };
 
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean => servesRoute(routes, route);
+
   return (text, page) => {
     const locale = localeByRoute.get(page.route);
     // The page's locale moves root links only when it has a URL prefix.
@@ -212,21 +218,31 @@ export const relativeLinkRewriter = (
       return text;
     }
     const relative = relativeRoute(page);
-    // What the rendered page makes of `/guide`: based, then moved into the
+    // What the rendered page makes of `/guide`: based (a public file like
+    // `/spec.pdf` under the deployment base alone), 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 based = withAuthoredBasePath(
+        deployBase,
+        basePath,
+        target,
+        servesPage
+      );
       const href = localize ? localizeHref(based, localize) : based;
       return href === target ? undefined : href;
     };
     const routed = (target: string): string | undefined =>
       isInternalPath(target) ? rooted(target) : relative?.(target);
+    // An image is always a file: `public/` (or a generated asset endpoint),
+    // served under the deployment base but never `basePath`. A relative one
+    // is left to `core/content-assets.ts`.
+    const imaged = (target: string): string | undefined => {
+      const based = withBasePath(deployBase, target);
+      return based === target ? undefined : based;
+    };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed);
+    const splices = collectSplices(text, lines, routed, imaged);
 
     return lines
       .map((line, index) => {

package/src/ai/serializers.ts

@@ -18,7 +18,8 @@ export const projectComponentSerializers = (
   ({
     ...exampleComponentSerializers(project.examples ?? {}),
     ...openapiComponentSerializers(
-      project.sources.find(isOpenApiSource)?.openApiData() ?? {}
+      project.sources.find(isOpenApiSource)?.openApiData() ?? {},
+      project.config.deployment.options.base
     ),
     ...project.config.agents.markdownComponents,
   }) satisfies Record<string, ComponentMarkdown>;