blume 2.0.3 → 2.1.1

package/src/ai/component-markdown.ts

@@ -1,6 +1,7 @@
 import { markdownTable } from "markdown-table";
 import { mdxToMdast } from "satteri";
 
+import { PARAM_LOCATIONS } from "../components/content/api-field.ts";
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
 import { MDX_FEATURES } from "../markdown/features.ts";
@@ -398,6 +399,18 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
     .join("\n\n");
 };
 
+/**
+ * A `<View>` block: its content under its view's name, so an agent reading
+ * the Markdown sees every view and which one each part belongs to.
+ */
+const view: ComponentMarkdown = ({ children, props }) => {
+  const title = isString(props.title) && props.title !== "" ? props.title : "";
+  if (!title) {
+    return children;
+  }
+  return children ? `**${title}**\n\n${children}` : `**${title}**`;
+};
+
 /** Escape the brackets that would end a link's text early. */
 const linkText = (value: string): string =>
   value.replaceAll(/[[\]]/gu, String.raw`\$&`);
@@ -420,6 +433,63 @@ const textProp = (value: EvaluatedValue): string => {
   return isNumber(value) ? String(value) : "";
 };
 
+/** Whether a flag prop is on: shorthand `true`, or the string `"true"`. */
+const flagOn = (value: EvaluatedValue): boolean =>
+  value === true || value === "true";
+
+/** A prop that holds one label or several. */
+const labelList = (value: EvaluatedValue): string[] =>
+  (Array.isArray(value) ? value : [value]).map(textProp).filter(Boolean);
+
+/**
+ * One `<ParamField>` or `<ResponseField>` as a list item: its labels, name,
+ * location, type, flags, and default on the first line, joined with middle
+ * dots, and its description indented under it, nested fields included. A
+ * field with no name, or a prop that wouldn't evaluate, declines.
+ */
+const apiField = (
+  { children, lossy, props }: ComponentMarkdownContext,
+  name: string,
+  location?: string
+): string | null => {
+  if (lossy || name === "") {
+    return null;
+  }
+  const value = props.default;
+  const head = [
+    ...labelList(props.pre),
+    `**${cellCode(name)}**`,
+    ...labelList(props.post),
+    location,
+    textProp(props.type) && cellCode(props.type),
+    flagOn(props.required) ? "required" : "",
+    flagOn(props.deprecated) ? "deprecated" : "",
+    value === undefined || value === null || value === ""
+      ? ""
+      : `default ${cellCode(isString(value) ? value : JSON.stringify(value))}`,
+  ].filter(Boolean);
+  const item = `- ${head.join(" · ")}`;
+  if (!children) {
+    return item;
+  }
+  const body = children
+    .split("\n")
+    .map((line) => (line === "" ? "" : `  ${line}`))
+    .join("\n");
+  return `${item}\n\n${body}`;
+};
+
+/** `<ParamField query="limit">`: named by its location attribute, else `name`. */
+const paramFieldMarkdown: ComponentMarkdown = (context) => {
+  const location = PARAM_LOCATIONS.find((key) => isString(context.props[key]));
+  return location
+    ? apiField(context, textProp(context.props[location]), location)
+    : apiField(context, textProp(context.props.name));
+};
+
+const responseFieldMarkdown: ComponentMarkdown = (context) =>
+  apiField(context, textProp(context.props.name));
+
 /**
  * A card is a link with a blurb, so that is what it becomes: the title as the
  * link text, the body under it, and the call to action last — the order the
@@ -514,7 +584,7 @@ export const inlineCode = (text: string): string => {
 };
 
 /** Fence `code` so its opening/closing run outlengths any backticks inside. */
-const fencedBlock = (lang: string, code: string): string => {
+export const fencedBlock = (lang: string, code: string): string => {
   const trimmed = code.replace(/(?<!\n)\n+$/u, "");
   const runs = trimmed.match(/`+/gu);
   const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
@@ -822,7 +892,11 @@ const SERIALIZERS = {
   Icon: icon,
   Math: math,
   Panel: panel,
+  ParamField: paramFieldMarkdown,
   Prompt: prompt,
+  RequestExample: cardGroup,
+  ResponseExample: cardGroup,
+  ResponseField: responseFieldMarkdown,
   Steps: steps,
   Tabs: tabs,
   Tile: tile,
@@ -832,6 +906,7 @@ const SERIALIZERS = {
   "Tree.Folder": treeFolder,
   TypeTable: typeTable,
   Update: update,
+  View: view,
   YouTube: youtube,
 } satisfies Record<string, ComponentMarkdown>;
 

package/src/ai/cors.ts

@@ -61,9 +61,18 @@ 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;
 }
 
+/**
+ * The response headers a cross-origin caller may read beyond the safelisted
+ * ones: the rate limit's `Retry-After`, so a caller can tell a reader how
+ * long to wait after a `429`.
+ */
+const EXPOSED_HEADERS = "retry-after";
+
 /** Stamp the CORS headers on every response `handler` returns. */
 export const withCors =
   (
@@ -72,9 +81,8 @@ export const withCors =
   ): ((context: RequestContext) => Promise<Response>) =>
   async (context) => {
     const response = await handler(context);
-    for (const [key, value] of Object.entries(
-      corsHeaders(context.request, allowed)
-    )) {
+    const headers = corsHeaders(context.request, allowed);
+    for (const [key, value] of Object.entries(headers)) {
       // `Vary` accumulates (the handler may already vary on something), the
       // rest replace.
       if (key === "vary") {
@@ -83,5 +91,8 @@ export const withCors =
         response.headers.set(key, value);
       }
     }
+    if (headers["access-control-allow-origin"]) {
+      response.headers.set("access-control-expose-headers", EXPOSED_HEADERS);
+    }
     return response;
   };

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/llms.ts

@@ -12,7 +12,11 @@ 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";
 
@@ -75,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.`
     );

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/query.ts

@@ -53,20 +53,28 @@ const contentTypesField = z.preprocess((value) => {
 }, z.array(z.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
 
 /**
- * The optional facet filter `search_docs` and `list_pages` share. Only
- * string-valued entries survive; an empty `{}` means "no filter".
+ * The optional facet filter `search_docs` and `list_pages` share. A value
+ * is read the way `pageFacets` stores one: a string as-is, a number or
+ * boolean stringified (`{"priority": 1}` matches the facet `"1"`). Entries of
+ * any other shape are dropped; an empty `{}` means "no filter".
  */
-/** Accepts any plain object, so the string-valued entries can be sifted out. */
+/** Accepts any plain object, so the usable entries can be sifted out. */
 const looseFacetObject = z.record(z.string(), z.unknown());
 
+/** A filter value a facet can hold, stringified like `pageFacets` does. */
+const facetFilterValue = z
+  .union([z.string(), z.number(), z.boolean()])
+  .transform(String);
+
 const filtersField = z.preprocess((value) => {
   const candidate = looseFacetObject.safeParse(value);
   if (!candidate.success) {
     return;
   }
-  const entries = Object.entries(candidate.data).filter(
-    (entry): entry is [string, string] => typeof entry[1] === "string"
-  );
+  const entries = Object.entries(candidate.data).flatMap(([key, entry]) => {
+    const parsed = facetFilterValue.safeParse(entry);
+    return parsed.success ? [[key, parsed.data] as const] : [];
+  });
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }, z.record(z.string(), z.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
 

package/src/ai/openapi-components.ts

@@ -1,13 +1,24 @@
+import { customCodeSamples } from "../components/openapi/code-samples.ts";
 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 {
+  operationObject,
+  operationOf,
+  specAddresses,
+  specOf,
+} from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
 import { operationSignature } from "../openapi/signature.ts";
 import type {
   ComponentMarkdown,
   EvaluatedValue,
 } from "./component-markdown.ts";
-import { inlineCode, isString, linkDestination } from "./component-markdown.ts";
+import {
+  fencedBlock,
+  inlineCode,
+  isString,
+  linkDestination,
+} from "./component-markdown.ts";
 
 /**
  * Spec-authored prose as one line of inline Markdown. Unlike the props the
@@ -62,7 +73,10 @@ const listItem = (
  * section shows. Parameters, schemas and responses are deliberately left out:
  * those are `operation-model.ts` plus each component's own preparation, and a
  * second implementation here would be free to disagree with the page. The
- * endpoint and what it does is the part that was missing altogether.
+ * endpoint and what it does is the part that was missing altogether. The
+ * spec's own `x-codeSamples` do come along, as fenced code: they're text the
+ * spec wrote out (often an SDK call no agent could derive from the
+ * endpoint), read through the same `customCodeSamples` the page renders.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
  * API reference, in which case every serializer declines. `deployBase` is the
@@ -134,9 +148,25 @@ export const openapiComponentSerializers = (
         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);
+      // The spec's own `x-codeSamples`, labeled as their tabs are.
+      const object =
+        data.kind === "openapi" ? operationObject(data, operation) : undefined;
+      const samples = customCodeSamples({
+        "x-code-samples": object?.["x-code-samples"],
+        "x-codeSamples": object?.["x-codeSamples"],
+      }).map(
+        (sample) =>
+          `**${inlineText(sample.label)}**\n\n${fencedBlock(sample.lang, sample.source)}`
+      );
+      return [signature, ...notes, ...samples].join("\n\n");
     },
   } satisfies Record<string, ComponentMarkdown>;
 };

package/src/ai/relative-links.ts

@@ -7,8 +7,6 @@ import {
   withAuthoredBasePath,
   withBasePath,
 } 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,
@@ -49,10 +47,6 @@ export interface LinkedPage {
 /** Rewrite a page's relative page links to the routes they mean. */
 export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
 
-/** A reference definition's target: `[label]: ./install` or `<./install>`. */
-const DEFINITION =
-  /^(?<lead> {0,3}\[(?:[^\]\\]|\\.)+\]:[\t ]*)(?:<(?<angled>[^>]*)>|(?<bare>\S+))/u;
-
 /**
  * Whether a text could hold a relative page link at all: an inline link, a
  * reference definition, or a component `href` whose target isn't a URL with
@@ -88,31 +82,13 @@ const spliceLine = (line: string, splices: readonly Splice[]): string => {
   return out;
 };
 
-/** One line's reference-definition splice, when it defines a routed target. */
-const definitionSplice = (
-  line: string,
-  routed: (target: string) => string | undefined
-): Splice | undefined => {
-  const groups = DEFINITION.exec(line)?.groups;
-  const lead = groups?.lead;
-  const target = groups?.angled ?? groups?.bare;
-  const route = target === undefined ? undefined : routed(target);
-  if (lead === undefined || target === undefined || route === undefined) {
-    return undefined;
-  }
-  // An angle-bracketed target starts one past its `<`.
-  const angled = groups?.angled === undefined ? 0 : 1;
-  return { column: lead.length + angled, length: target.length, text: route };
-};
-
 /**
- * Every routed splice in `text`, by 0-based line: links and images, then
- * definitions. An image target goes through `imaged`, everything else through
- * `routed`.
+ * Every routed splice in `text`, by 0-based line: links, images, and
+ * reference definitions, as `extractLinks` finds them. An image target goes
+ * through `imaged`, everything else through `routed`.
  */
 const collectSplices = (
   text: string,
-  lines: readonly string[],
   routed: (target: string) => string | undefined,
   imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
@@ -130,16 +106,6 @@ const collectSplices = (
       });
     }
   }
-  let fence: FenceState = null;
-  for (const [index, line] of lines.entries()) {
-    const next = nextFenceState(line, fence);
-    const inFence = fence !== null || next !== null;
-    fence = next;
-    const splice = inFence ? undefined : definitionSplice(line, routed);
-    if (splice !== undefined) {
-      add(index, splice);
-    }
-  }
   return splices;
 };
 
@@ -242,7 +208,7 @@ export const relativeLinkRewriter = (
     };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed, imaged);
+    const splices = collectSplices(text, routed, imaged);
 
     return lines
       .map((line, index) => {