blume 0.6.7 → 0.8.0

package/src/ai/markdown.ts

@@ -3,15 +3,37 @@ import { readFile } from "node:fs/promises";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
+import { downlevelComponents } from "./component-markdown.ts";
+import { applyAgentVisibility } from "./visibility.ts";
+
+/** One route's raw-Markdown variants. */
+export interface RawMarkdownEntry {
+  /**
+   * The agent-facing Markdown served at `/<route>.md`: supported components
+   * downleveled to plain Markdown (`<TypeTable>` → table, `<Callout>` →
+   * blockquote, …). Present only when downleveling changed something, so
+   * component-free pages aren't stored twice.
+   */
+  md?: string;
+  /** The original source, served verbatim at `/<route>.mdx`. */
+  mdx: string;
+}
+
+/** The Markdown an agent should read for a route. */
+export const agentMarkdown = (entry: RawMarkdownEntry): string =>
+  entry.md ?? entry.mdx;
 
 /**
  * Map every route to its raw source Markdown. Powers the `<route>.md` and
- * `<route>.mdx` endpoints, which serve the original source so AI tools — and
- * readers — can fetch any page as plain Markdown.
+ * `<route>.mdx` endpoints: `.mdx` serves the original source so tools can see
+ * exactly what the author wrote, while `.md` downlevels supported components
+ * to plain Markdown for consumers that can't interpret JSX. `<Visibility>`
+ * audiences are resolved for agents in both variants: web-only content is
+ * removed, agents-only unwrapped.
  */
 export const buildRawMarkdown = async (
   project: BlumeProject
-): Promise<Record<string, string>> => {
+): Promise<Record<string, RawMarkdownEntry>> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
@@ -23,9 +45,16 @@ export const buildRawMarkdown = async (
   };
 
   const entries = await Promise.all(
-    project.manifest.routes.map(
-      async (route) => [route.path, await readRoute(route)] as const
-    )
+    project.manifest.routes.map(async (route) => {
+      const source = applyAgentVisibility(await readRoute(route));
+      const md = downlevelComponents(
+        source,
+        project.config.ai.markdownComponents
+      );
+      const entry: RawMarkdownEntry =
+        md === source ? { mdx: source } : { md, mdx: source };
+      return [route.path, entry] as const;
+    })
   );
   return Object.fromEntries(entries);
 };

package/src/ai/mcp/data.ts

@@ -1,8 +1,9 @@
+import { normalizeBasePath } from "../../core/base-path.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { Navigation } from "../../core/types.ts";
 import { buildSearchDocuments } from "../../search/documents.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
-import { buildRawMarkdown } from "../markdown.ts";
+import { agentMarkdown, buildRawMarkdown } from "../markdown.ts";
 
 /** A page entry surfaced by the `list_pages` MCP tool. */
 export interface McpRoute {
@@ -21,6 +22,12 @@ export interface McpRoute {
  * access at request time. Serialized to `generated/mcp-data.json`.
  */
 export interface McpData {
+  /**
+   * Normalized `deployment.base` (`""` or `/seg`), layered onto routes when
+   * emitting URLs — the site is base-less and routes are base-less manifest
+   * paths, matching the sitemap/llms.txt convention.
+   */
+  base: string;
   documents: OramaDoc[];
   instructions?: string;
   name: string;
@@ -34,29 +41,47 @@ export interface McpData {
 /** Build the MCP data snapshot from a resolved project. */
 export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
   const { config, graph, manifest } = project;
-  const [documents, pages] = await Promise.all([
+  const [documents, rawMarkdown] = await Promise.all([
     // The MCP server is independent of on-page search, so index docs even when
-    // the search provider is `none`.
-    buildSearchDocuments(project, { includeWhenDisabled: true }),
+    // the search provider is `none`. Documents are agent-facing, so
+    // `<Visibility>` resolves like `get_page`/llms-full.txt (web-only content
+    // removed, agents-only kept).
+    buildSearchDocuments(project, {
+      audience: "agents",
+      includeWhenDisabled: true,
+    }),
     buildRawMarkdown(project),
   ]);
 
+  // `get_page` serves the agent variant: components downleveled to Markdown.
+  const pages = Object.fromEntries(
+    Object.entries(rawMarkdown).map(([route, entry]) => [
+      route,
+      agentMarkdown(entry),
+    ])
+  );
+
   const descriptionById = new Map(
     graph.pages.map((page) => [page.id, page.description])
   );
 
-  const routes: McpRoute[] = manifest.routes
-    .filter((route) => !route.hidden)
-    .map((route) => ({
+  const routes: McpRoute[] = [];
+  for (const route of manifest.routes) {
+    if (route.hidden) {
+      continue;
+    }
+    routes.push({
       contentType: route.contentType,
       description: descriptionById.get(route.id),
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
       route: route.path,
       title: route.title,
-    }));
+    });
+  }
 
   return {
+    base: normalizeBasePath(config.deployment.base),
     documents: documents.map((doc) => ({
       content: doc.content,
       description: doc.description,

package/src/ai/mcp/discovery.ts

@@ -1,7 +1,10 @@
+import { withBasePath } from "../../core/base-path.ts";
 import { MCP_TOOLS } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
 export interface McpDiscoveryInput {
+  /** Normalized `deployment.base` (`""` or `/seg`); the route is base-less. */
+  base: string;
   name: string;
   route: string;
   site: string | null;
@@ -9,10 +12,14 @@ export interface McpDiscoveryInput {
 }
 
 /** The MCP server's address — absolute when a site is configured. */
-const serverUrl = (input: McpDiscoveryInput): string =>
-  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+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);
+  // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  input.site ? `${input.site.replace(/\/+$/u, "")}${input.route}` : input.route;
+  return input.site ? `${input.site.replace(/\/+$/u, "")}${path}` : path;
+};
 
 /**
  * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use

package/src/ai/mcp/server.ts

@@ -5,6 +5,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
+import { withBasePath } from "../../core/base-path.ts";
 import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
 import type { McpData } from "./data.ts";
@@ -89,10 +90,24 @@ const normalizeRoute = (input: string): string => {
 };
 
 /** Build the absolute (or root-relative) URL for a route. */
-const urlFor = (route: string, site: string | null): string =>
-  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+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);
+  // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  site ? `${site.replace(/\/+$/u, "")}${route}` : route;
+  return data.site ? `${data.site.replace(/\/+$/u, "")}${path}` : path;
+};
+
+/** A hit's excerpt: its description, else the head of its content with an
+ * ellipsis only when something was actually cut off. */
+const excerptFor = (doc: OramaDoc): string => {
+  if (doc.description) {
+    return doc.description;
+  }
+  const head = doc.content.slice(0, EXCERPT_LENGTH).trim();
+  return doc.content.length > EXCERPT_LENGTH ? `${head}…` : head;
+};
 
 const text = (value: string, isError = false) => ({
   content: [{ text: value, type: "text" as const }],
@@ -127,10 +142,9 @@ const buildServer = (
         asLimit(args.limit)
       );
       const results = hits.map((doc: OramaDoc) => ({
-        excerpt:
-          doc.description || `${doc.content.slice(0, EXCERPT_LENGTH)}…`.trim(),
+        excerpt: excerptFor(doc),
         title: doc.title,
-        url: urlFor(doc.route, data.site),
+        url: urlFor(doc.route, data),
       }));
       return text(JSON.stringify(results, null, 2));
     }
@@ -156,7 +170,7 @@ const buildServer = (
             lastModified: route.lastModified,
             route: route.route,
             title: route.title,
-            url: urlFor(route.route, data.site),
+            url: urlFor(route.route, data),
           })),
           null,
           2
@@ -209,6 +223,9 @@ export const createMcpFetchHandler = (
     const server = buildServer(data, index);
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
+      // The SDK enables stateless mode only when this is `undefined`; `null` is
+      // not an accepted value for the `(() => string) | undefined` option.
+      // oxlint-disable-next-line sonarjs/no-undefined-assignment
       sessionIdGenerator: undefined,
     });
     await server.connect(transport);

package/src/ai/visibility.ts

@@ -0,0 +1,74 @@
+// Mirrors the fence masking in `core/sources/assets.ts`: a fenced code sample
+// that *shows* `<Visibility>` markup must keep showing what the author wrote.
+const CODE_FENCE_BLOCK =
+  /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
+// NUL delimiters cannot appear in authored markdown, so tokens never collide.
+// oxlint-disable-next-line no-control-regex -- the NUL is the collision guard.
+const FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
+
+/** The audience an output surface serves — the component's two `for` values. */
+export type VisibilityAudience = "agents" | "web";
+
+// `<Visibility for="…">…</Visibility>` in either quote style, tolerant of
+// whitespace around the attribute and inside the tags. Non-greedy bodies stop
+// at the first close tag, so nesting is not supported: a nested block closes
+// the outer match early and any remainder passes through verbatim.
+const visibilityBlock = (audience: VisibilityAudience): RegExp =>
+  new RegExp(
+    `<Visibility\\s+for\\s*=\\s*(?:"${audience}"|'${audience}')\\s*>(?<inner>[\\s\\S]*?)</Visibility\\s*>`,
+    "gu"
+  );
+
+const BLOCKS: Record<VisibilityAudience, RegExp> = {
+  agents: visibilityBlock("agents"),
+  web: visibilityBlock("web"),
+};
+
+/**
+ * Resolve `<Visibility>` blocks for one audience: blocks addressed to the
+ * other audience are removed entirely and blocks addressed to `audience` are
+ * unwrapped (tags dropped, body kept), matching what the Astro component
+ * renders on the web. Other `for` values (the component's default) are left
+ * untouched, and markdown with no matching blocks is returned byte-identical,
+ * so raw sources stay raw.
+ */
+export const applyAudienceVisibility = (
+  markdown: string,
+  audience: VisibilityAudience
+): string => {
+  // Mask fenced code blocks so documentation *about* Visibility survives.
+  const fences: string[] = [];
+  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
+    fences.push(block);
+    return `\u0000blume-fence-${fences.length - 1}\u0000`;
+  });
+
+  let touched = false;
+  const filtered = masked
+    .replaceAll(BLOCKS[audience === "agents" ? "web" : "agents"], () => {
+      touched = true;
+      return "";
+    })
+    .replaceAll(BLOCKS[audience], (_match, inner: string) => {
+      touched = true;
+      return inner;
+    });
+
+  // Removing/unwrapping block-level tags leaves runs of blank lines behind;
+  // collapse them only when something matched so untouched files round-trip
+  // exactly. Fences are masked as single-line tokens, so they are unaffected.
+  const tidied = touched ? filtered.replaceAll(/\n{3,}/gu, "\n\n") : filtered;
+
+  return tidied.replaceAll(
+    FENCE_TOKEN,
+    (token, index) => fences[Number(index)] ?? token
+  );
+};
+
+/**
+ * Resolve `<Visibility>` blocks for agent-facing Markdown (llms-full.txt, the
+ * `.md`/`.mdx` mirrors, MCP tools, Ask AI grounding): `for="web"` content is
+ * removed and `for="agents"` content is unwrapped.
+ */
+export const applyAgentVisibility = (markdown: string): string =>
+  applyAudienceVisibility(markdown, "agents");

package/src/astro/component-slots.ts

@@ -41,6 +41,8 @@ export const layoutOverrides = {};
 const attributeValue = (value: string): string =>
   value.replaceAll(/["\n\r]/gu, " ").trim();
 
+const CLIENT_LOAD = "client:load";
+
 /** Astro client directive for a hydrated override. */
 const directiveFor = (override: NormalizedOverride): string => {
   const framework = override.source?.framework;
@@ -54,15 +56,15 @@ const directiveFor = (override: NormalizedOverride): string => {
     case "media": {
       return override.media
         ? `client:media="${attributeValue(override.media)}"`
-        : "client:load";
+        : CLIENT_LOAD;
     }
     case "only": {
       return framework
         ? `client:only="${attributeValue(framework)}"`
-        : "client:load";
+        : CLIENT_LOAD;
     }
     default: {
-      return "client:load";
+      return CLIENT_LOAD;
     }
   }
 };
@@ -89,8 +91,18 @@ ${clause}
 `;
 };
 
+/**
+ * A filesystem-safe, injective token for an override key. Distinct keys must
+ * never share a wrapper file ("Foo.Bar" vs "Foo_Bar" used to collide, racing
+ * the same temp file and silently rendering the wrong component), so every
+ * non-alphanumeric character is hex-escaped rather than collapsed — the same
+ * hardening as `exampleSlug` in templates.ts.
+ */
 const sanitize = (value: string): string =>
-  value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+  value.replaceAll(
+    /[^A-Za-z0-9]/gu,
+    (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`
+  );
 
 export const planComponentSlots = (
   componentsFile: string | null,

package/src/astro/examples.ts

@@ -59,10 +59,10 @@ const GLOB_MAGIC = /[!*?[\]{}]/u;
  */
 const splitGlobBase = (pattern: string): { base: string; rest: string } => {
   const segments = pattern.split("/");
+  // Only called when the pattern contains glob magic (see the caller), and `/`
+  // is never magic, so the magic char always lands in a segment — `findIndex`
+  // is never -1 here.
   const firstMagic = segments.findIndex((segment) => GLOB_MAGIC.test(segment));
-  if (firstMagic === -1) {
-    return { base: pattern, rest: "" };
-  }
   return {
     base: segments.slice(0, firstMagic).join("/"),
     rest: segments.slice(firstMagic).join("/"),
@@ -109,11 +109,13 @@ export const discoverExamples = async (
   const warnings: string[] = [];
   const seen = new Map<string, string>();
 
-  for (const [index, file] of files.entries()) {
+  // Extracted so the two skip paths become early `return`s (one `continue`
+  // budget per loop under the lint rule) instead of `continue` statements.
+  const collectExample = (file: string, source: string): void => {
     const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
     const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
     if (!(ext && framework)) {
-      continue;
+      return;
     }
     // Strip the trailing `.<ext>` to form the `<Component path>` key.
     const path = relative(dir, file).slice(0, -(ext.length + 1));
@@ -122,10 +124,9 @@ export const discoverExamples = async (
       warnings.push(
         `Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`
       );
-      continue;
+      return;
     }
     seen.set(path, file);
-    const source = sources[index] ?? "";
     examples.push({
       client:
         framework === "astro"
@@ -137,6 +138,10 @@ export const discoverExamples = async (
       path,
       source,
     });
+  };
+
+  for (const [index, file] of files.entries()) {
+    collectExample(file, sources[index] ?? "");
   }
 
   return { examples, warnings };