blume 1.1.3 → 1.2.0

package/src/core/schema.ts

@@ -1,3 +1,4 @@
+import type { AstroIntegration } from "astro";
 import { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
@@ -78,6 +79,11 @@ const searchMetaSchema = z.strictObject({
   tags: z.array(z.string()).optional(),
 });
 
+const aiMetaSchema = z.strictObject({
+  /** Exclude this page from llms.txt and llms-full.txt. */
+  exclude: z.boolean().default(false),
+});
+
 const changelogMetaSchema = z.strictObject({
   category: z.string().optional(),
   date: dateSchema.optional(),
@@ -105,6 +111,7 @@ const authorSchema = z.union([
 
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z.strictObject({
+  ai: aiMetaSchema.default({}),
   /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
   authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
@@ -351,6 +358,10 @@ const contentConfigSchema = z.strictObject({
 });
 
 const navTabSchema = z.strictObject({
+  // Rejected empty rather than accepted: an empty `href` would render a link to
+  // nowhere, and it can't mean "resolve it for me" either — that's what
+  // omitting the field does.
+  href: z.string().min(1).optional(),
   icon: iconName.optional(),
   items: z
     .array(
@@ -575,18 +586,44 @@ const mcpConfigSchema = z.strictObject({
   route: z.string().default("/mcp").transform(normalizeRoute),
 });
 
+const askEndpointSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .refine(
+    (value) => {
+      if (value.startsWith("/") && !value.startsWith("//")) {
+        return true;
+      }
+      try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+      } catch {
+        return false;
+      }
+    },
+    {
+      message:
+        "ai.ask.endpoint must be an HTTP(S) URL or a root-relative path.",
+    }
+  );
+
 const aiConfigSchema = z.strictObject({
   ask: z
     .strictObject({
       // Name of the env var holding the provider's API key; each provider has
       // a sensible default, so this only needs setting to override it.
       apiKeyEnv: z.string().optional(),
-      // Base URL of the backend. Required for `openai-compatible`; for the
-      // named providers it overrides the built-in preset.
+      // Base URL of the backend. Required for `openai-compatible` only when no
+      // external endpoint is supplied; for named providers it overrides the preset.
       // blume bundles Zod 3; top-level `z.url()` is undefined at runtime.
       // oxlint-disable-next-line react-doctor/zod-v4-prefer-top-level-string-formats
       baseUrl: z.string().url().optional(),
       enabled: z.boolean().default(false),
+      // Optional external endpoint for projects that keep their docs static
+      // and host Ask AI in an existing backend. Absolute URLs and root-relative
+      // paths are both valid; the built-in request/stream contract is unchanged.
+      endpoint: askEndpointSchema.optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
       // Empty-state prompts shown before the first question. Each renders as a
@@ -603,7 +640,10 @@ const aiConfigSchema = z.strictObject({
     .superRefine((value, ctx) => {
       // A generic OpenAI-compatible backend has no preset URL, so the user
       // must supply one; the named providers fall back to their preset.
-      if (value.provider === "openai-compatible" && !value.baseUrl) {
+      if (
+        value.provider === "openai-compatible" &&
+        !(value.baseUrl || value.endpoint)
+      ) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message:
@@ -1118,15 +1158,21 @@ const reactConfigSchema = z.strictObject({
  * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 const openapiSourceSchema = z.strictObject({
+  /** Include generated pages from this spec in llms.txt/llms-full.txt. */
+  includeInLlms: z.boolean().default(true),
+  /** Include generated pages from this spec in site search. */
+  includeInSearch: z.boolean().default(true),
   /** Nav/section label for this source. */
   label: z.string().optional(),
+  /** Emit noindex metadata and omit generated pages from the sitemap. */
+  noindex: z.boolean().default(false),
   /** Per-source route; defaults to the block's `route` (or a derived path). */
   route: z.string().optional(),
   /** Local path or `http(s)` URL to the spec. */
   spec: z.string(),
 });
 
-export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
+export type OpenApiSource = z.input<typeof openapiSourceSchema>;
 
 /**
  * Arbitrary Scalar API-reference options forwarded verbatim to the generated
@@ -1283,6 +1329,7 @@ export const blumeConfigSchema = z.strictObject({
   frontmatter: frontmatterConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
+  integrations: z.array(z.custom<AstroIntegration>()).default([]),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),

package/src/core/server-features.ts

@@ -7,7 +7,7 @@ import type { ResolvedConfig } from "./schema.ts";
  */
 export const serverFeatures = (config: ResolvedConfig): string[] => {
   const features: string[] = [];
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     features.push("Ask AI");
   }
   // The hosted MCP server is a live JSON-RPC endpoint, so it needs a runtime.

package/src/core/sources/normalize.ts

@@ -38,6 +38,15 @@ export const slugify = (text: string): string =>
     .replaceAll(/-+/gu, "-")
     .replaceAll(/^-|-$/gu, "");
 
+/**
+ * {@link slugify} for a slug that may span path segments (`guides/setup`).
+ * `slugify` deletes `/` along with all other punctuation, which would mash
+ * `guides/setup` into `guidessetup` — and collide it with a genuine `guidessetup`
+ * document. Each segment is slugged on its own and the separators kept.
+ */
+export const slugifyPath = (text: string): string =>
+  text.split("/").map(slugify).filter(Boolean).join("/");
+
 /** Title-case a slug segment for display. */
 const titleCase = (value: string): string =>
   value
@@ -104,13 +113,24 @@ type FenceState = "```" | "~~~" | null;
  * the state untouched.
  */
 const nextFenceState = (line: string, fence: FenceState): FenceState => {
-  const delimiter = line.trimStart().match(CODE_FENCE)?.groups?.delimiter as
+  const trimmed = line.trimStart();
+  const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter as
     | Exclude<FenceState, null>
     | undefined;
   if (delimiter === undefined) {
     return fence;
   }
   if (fence === null) {
+    // A backtick fence's info string cannot itself contain a backtick
+    // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
+    // opening a phantom fence on it would swallow every heading and link
+    // after it. Tilde fences carry no such rule.
+    if (delimiter === "```") {
+      const run = trimmed.match(/^`+/u)?.[0].length ?? 0;
+      if (trimmed.slice(run).includes("`")) {
+        return fence;
+      }
+    }
     return delimiter;
   }
   return fence === delimiter ? null : fence;
@@ -159,6 +179,13 @@ const linesWithoutFrontMatter = (body: string): string[] => {
   if (!/^-{3}\s*$/u.test(lines[0] ?? "")) {
     return lines;
   }
+  // A blank line directly after the dashes means the body *opens* with a
+  // thematic break, not front matter — YAML metadata starts on the very next
+  // line. Treating it as an unclosed block ate everything up to the next
+  // `---`/`...` line of an already-stripped body.
+  if ((lines[1] ?? "").trim() === "") {
+    return lines;
+  }
   const close = lines.findIndex(
     (line, index) => index > 0 && FRONT_MATTER_CLOSE.test(line)
   );
@@ -304,9 +331,26 @@ export const extractHeadings = (body: string): Heading[] => {
   return headings;
 };
 
-const MD_LINK = /\[[^\]]*\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)/gu;
+// The label admits one level of nested brackets so an image-wrapped link
+// (`[![alt](/img.png)](/target)`) matches as the *outer* link — with a flat
+// `[^\]]*` label the match stopped at the image's `]` and the outer target was
+// never seen. The target admits one level of balanced parens so a Wikipedia-
+// style URL (`/wiki/Foo_(bar)`) isn't truncated at its first `)`.
+const MD_LINK =
+  /\[(?<label>(?:[^[\]]|\[[^\]]*\])*)\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
+// An image inside a link label; its target was matched (and so validated) as a
+// link of its own before labels admitted nesting, and still should be.
+const MD_IMAGE =
+  /!\[[^\]]*\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
 const INLINE_CODE = /`[^`]*`/gu;
 
+/** Column (0-based, within `matched`) where a link/image match's target starts. */
+const targetOffsetIn = (
+  matched: string,
+  target: string,
+  title: string | undefined
+): number => matched.length - 1 - (title?.length ?? 0) - target.length;
+
 /**
  * Extract link targets from a markdown body for later validation, recording the
  * 1-based line/column of each target. Skips fenced code blocks and inline code.
@@ -335,16 +379,33 @@ const scanLinkLine = (
     if (target === undefined || match.index === undefined) {
       continue;
     }
-    // Locate the target from the `](` boundary rather than searching for the
-    // target text from the match start — otherwise a label that contains the
-    // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
-    // label can't contain `]`, so `](` is unambiguous.
-    const targetOffset = match.index + match[0].indexOf("](") + "](".length;
+    // Locate the target by arithmetic from the match end rather than searching
+    // for its text — a label that contains the same text (e.g. `[/a/b](/a/b)`)
+    // would otherwise report the column inside the label.
+    const targetOffset = targetOffsetIn(match[0], target, match.groups?.title);
     links.push({
-      column: targetOffset + 1,
+      column: match.index + targetOffset + 1,
       line: lineNumber,
       target,
     });
+    // An image nested in the label (`[![alt](/img.png)](/target)`) carries its
+    // own target; surface it too so a missing image is still caught.
+    const label = match[0].slice(0, targetOffset - "](".length);
+    for (const image of label.matchAll(MD_IMAGE)) {
+      const imageTarget = image.groups?.target;
+      if (imageTarget === undefined || image.index === undefined) {
+        continue;
+      }
+      links.push({
+        column:
+          match.index +
+          image.index +
+          targetOffsetIn(image[0], imageTarget, image.groups?.title) +
+          1,
+        line: lineNumber,
+        target: imageTarget,
+      });
+    }
   }
   return next;
 };

package/src/core/sources/notion.ts

@@ -12,7 +12,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
-import { slugify } from "./normalize.ts";
+import { slugifyPath } from "./normalize.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -432,7 +432,9 @@ export const notionSource = (
     const slugProp = richToMarkdown(
       page.properties[props.slug ?? "Slug"]?.rich_text
     );
-    const slug = slugify(slugProp || title) || page.id;
+    // Path-aware: a `guides/setup` slug keeps its `/` (per-segment slugging)
+    // instead of mashing into `guidessetup`.
+    const slug = slugifyPath(slugProp || title) || page.id;
     return { data, slug };
   };
 

package/src/core/sources/sanity.ts

@@ -8,7 +8,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
-import { slugify } from "./normalize.ts";
+import { slugify, slugifyPath } from "./normalize.ts";
 import { portableTextToMarkdown } from "./portable-text.ts";
 import type { PortableTextBlock } from "./portable-text.ts";
 import type {
@@ -142,9 +142,11 @@ export const sanitySource = (
       "untitled";
     // Fall back to the unique `_id` when a slug (e.g. a non-ASCII `slug.current`)
     // slugifies to empty, so distinct documents don't all collapse to the same
-    // `untitled.md` ref and silently overwrite each other.
+    // `untitled.md` ref and silently overwrite each other. Path-aware: a
+    // `guides/setup` slug keeps its `/` (per-segment slugging) instead of
+    // mashing into `guidessetup`.
     const slug =
-      slugify(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
+      slugifyPath(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
     const data: Record<string, unknown> = {};
     const title = asString(getPath(doc, fields.title ?? "title"));

package/src/core/types.ts

@@ -201,9 +201,11 @@ export interface NavTab {
    */
   path: string;
   /**
-   * The clickable target. Equals `path` when the section has an index page;
-   * otherwise it's resolved to the section's first page so the tab never links
-   * to a 404. Absent when it matches `path`.
+   * The clickable target. Author-declared when the config sets it; otherwise
+   * equals `path` when the section has an index page, and resolves to the
+   * section's first page when it doesn't, so the tab doesn't link to a 404 as
+   * long as the section has a page to offer — a section with no linkable page at
+   * all keeps `path`. Absent when a resolved target matches `path`.
    */
   href?: string;
   icon?: string;

package/src/eval/agents.ts

@@ -0,0 +1,340 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+import { z } from "zod";
+
+import type { AgentKind } from "../audit/agent.ts";
+
+/** How long the SIGTERM on timeout gets to work before SIGKILL follows. */
+const KILL_GRACE_MS = 5000;
+
+/** The MCP tools a reader run may use — nothing else. */
+export const MCP_TOOL_NAMES = [
+  "search_docs",
+  "get_page",
+  "list_pages",
+  "get_navigation",
+] as const;
+
+/** The MCP server name in the generated config; tool ids derive from it. */
+const MCP_SERVER_NAME = "docs";
+
+/**
+ * Claude Code built-ins that would let the agent escape the docs-only
+ * sandbox: the reader must not read the repo, run commands, or search the
+ * web — it sees the documentation the way a stranger does, through MCP.
+ */
+const DISALLOWED_TOOLS = [
+  "Bash",
+  "Read",
+  "Glob",
+  "Grep",
+  "Write",
+  "Edit",
+  "NotebookEdit",
+  "WebFetch",
+  "WebSearch",
+  "Task",
+];
+
+/** The captured outcome of one headless agent invocation. */
+export interface HeadlessResult {
+  code: number;
+  stderr: string;
+  stdout: string;
+  timedOut: boolean;
+}
+
+export interface HeadlessOptions {
+  cwd: string;
+  platform?: NodeJS.Platform;
+  prompt: string;
+  timeoutMs: number;
+}
+
+/**
+ * Run an agent CLI headlessly: prompt over stdin (dodging argv limits and
+ * cmd.exe newline quoting alike), stdout and stderr captured, SIGTERM at the
+ * deadline with a SIGKILL follow-up. Resolves with the captured result;
+ * rejects only when the executable cannot be spawned at all (ENOENT).
+ */
+export const runAgentHeadless = (
+  bin: string,
+  args: string[],
+  options: HeadlessOptions
+): Promise<HeadlessResult> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
+  new Promise((resolve, reject) => {
+    const platform = options.platform ?? process.platform;
+    // npm installs agent CLIs as `.cmd` shims on Windows, which Node refuses
+    // to spawn without a shell. Arguments are plain flags and absolute paths,
+    // so shell interpolation has nothing to mangle.
+    const child = spawn(bin, args, {
+      cwd: options.cwd,
+      shell: platform === "win32",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf-8");
+    });
+
+    const deadline = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      const hardKill = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+      hardKill.unref();
+    }, options.timeoutMs);
+    deadline.unref();
+
+    child.once("error", (error) => {
+      clearTimeout(deadline);
+      reject(error);
+    });
+    child.once("close", (code) => {
+      clearTimeout(deadline);
+      resolve({ code: code ?? 1, stderr, stdout, timedOut });
+    });
+    // `close` waits for the stdio pipes, which a killed agent's own children
+    // (an MCP server, a shell) can hold open past the SIGTERM. A timed-out
+    // run's output is discarded anyway, so the process dying is enough.
+    child.once("exit", (code) => {
+      if (timedOut) {
+        clearTimeout(deadline);
+        resolve({ code: code ?? 1, stderr, stdout, timedOut });
+      }
+    });
+
+    child.stdin.end(options.prompt);
+  });
+
+/** The spawn signature `runEval` accepts, injectable for tests. */
+export type HeadlessRunner = typeof runAgentHeadless;
+
+/** How the eval reaches the MCP stdio bridge from a spawned agent. */
+export interface McpLaunch {
+  /** The generated MCP config file (claude's `--mcp-config`). */
+  configPath: string;
+  /** argv for the bridge process (codex's `-c mcp_servers` override). */
+  serverArgs: string[];
+  /** The executable launching the bridge. */
+  serverCommand: string;
+}
+
+/**
+ * Write the MCP config a reader run points its agent CLI at. The bridge is
+ * this same CLI relaunched (`blume mcp-stdio`), which resolves correctly from
+ * both a source checkout (bun + src/cli/index.ts) and an installed package
+ * (node + bin/blume.mjs).
+ */
+export const writeMcpConfig = async (
+  dir: string,
+  snapshotPath: string,
+  launcher?: { args: string[]; command: string }
+): Promise<McpLaunch> => {
+  const resolved = launcher ?? {
+    args: [process.argv[1] ?? "", "mcp-stdio", "--data", snapshotPath],
+    command: process.execPath,
+  };
+  const configPath = join(dir, "mcp-config.json");
+  const config = {
+    mcpServers: {
+      [MCP_SERVER_NAME]: { args: resolved.args, command: resolved.command },
+    },
+  };
+  await writeFile(configPath, JSON.stringify(config, null, 2));
+  return {
+    configPath,
+    serverArgs: resolved.args,
+    serverCommand: resolved.command,
+  };
+};
+
+export interface InvocationContext {
+  /** Where codex writes its final message; unused by claude. */
+  lastMessagePath: string;
+  /** The MCP bridge for reader runs; omitted for the judge. */
+  mcp?: McpLaunch;
+}
+
+const CLAUDE_READER_MAX_TURNS = "25";
+const CLAUDE_JUDGE_MAX_TURNS = "1";
+
+const claudeArgs = (context: InvocationContext): string[] => {
+  const base = ["-p", "--output-format", "json", "--strict-mcp-config"];
+  if (context.mcp) {
+    const allowed = MCP_TOOL_NAMES.map(
+      (tool) => `mcp__${MCP_SERVER_NAME}__${tool}`
+    ).join(",");
+    return [
+      ...base,
+      "--mcp-config",
+      context.mcp.configPath,
+      "--allowedTools",
+      allowed,
+      "--disallowedTools",
+      DISALLOWED_TOOLS.join(","),
+      "--max-turns",
+      CLAUDE_READER_MAX_TURNS,
+    ];
+  }
+  return [
+    ...base,
+    "--disallowedTools",
+    DISALLOWED_TOOLS.join(","),
+    "--max-turns",
+    CLAUDE_JUDGE_MAX_TURNS,
+  ];
+};
+
+const codexArgs = (context: InvocationContext): string[] => {
+  const base = [
+    "exec",
+    "--skip-git-repo-check",
+    "--ignore-user-config",
+    "--ephemeral",
+    "--sandbox",
+    "read-only",
+    "--output-last-message",
+    context.lastMessagePath,
+  ];
+  if (context.mcp) {
+    // `-c` values parse as TOML; JSON string/array literals are valid TOML
+    // values, so JSON.stringify produces exactly the quoting codex expects.
+    return [
+      ...base,
+      "-c",
+      `mcp_servers.${MCP_SERVER_NAME}.command=${JSON.stringify(
+        context.mcp.serverCommand
+      )}`,
+      "-c",
+      `mcp_servers.${MCP_SERVER_NAME}.args=${JSON.stringify(
+        context.mcp.serverArgs
+      )}`,
+      "-",
+    ];
+  }
+  return [...base, "-"];
+};
+
+/** Build the argv for one headless run; pass `mcp` for the reader role. */
+export const agentArgs = (
+  kind: AgentKind,
+  context: InvocationContext
+): string[] => (kind === "claude" ? claudeArgs(context) : codexArgs(context));
+
+/** What one headless run produced, normalized across agent CLIs. */
+export interface AgentOutput {
+  costUsd?: number;
+  detail?: string;
+  isError: boolean;
+  text: string;
+}
+
+const claudeResultSchema = z.object({
+  is_error: z.boolean().default(false),
+  result: z.string().default(""),
+  total_cost_usd: z.number().optional(),
+});
+
+const tail = (value: string, max = 300): string => {
+  const trimmed = value.trim();
+  return trimmed.length > max ? trimmed.slice(-max) : trimmed;
+};
+
+/**
+ * Normalize a finished run into the answer text. Claude prints one JSON
+ * object on stdout (`--output-format json`); codex writes the final message
+ * to `--output-last-message` because its stdout interleaves progress.
+ */
+export const readAgentOutput = async (
+  kind: AgentKind,
+  result: HeadlessResult,
+  lastMessagePath: string
+): Promise<AgentOutput> => {
+  if (result.timedOut) {
+    return { detail: "timed out", isError: true, text: "" };
+  }
+  if (result.code !== 0) {
+    return {
+      detail: tail(result.stderr) || `exited with code ${result.code}`,
+      isError: true,
+      text: "",
+    };
+  }
+
+  if (kind === "claude") {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      return {
+        detail: "unparseable --output-format json payload",
+        isError: true,
+        text: "",
+      };
+    }
+    const payload = claudeResultSchema.safeParse(parsed);
+    if (!payload.success) {
+      return {
+        detail: "unexpected --output-format json shape",
+        isError: true,
+        text: "",
+      };
+    }
+    return {
+      costUsd: payload.data.total_cost_usd,
+      isError: payload.data.is_error,
+      text: payload.data.result,
+    };
+  }
+
+  let text: string;
+  try {
+    const raw = await readFile(lastMessagePath, "utf-8");
+    text = raw.trim();
+  } catch {
+    return { detail: "no last message written", isError: true, text: "" };
+  }
+  if (text === "") {
+    return { detail: "empty last message", isError: true, text: "" };
+  }
+  return { isError: false, text };
+};
+
+const verdictSchema = z.object({
+  missing: z.array(z.string()).default([]),
+  notes: z.string().default(""),
+  pass: z.boolean(),
+  score: z.number().min(0).max(1).optional(),
+});
+
+/** The judge's grade for one answer. */
+export type Verdict = z.infer<typeof verdictSchema>;
+
+/**
+ * Extract the verdict JSON from a judge reply. Tolerates markdown fences and
+ * surrounding prose; returns undefined when no valid verdict can be found.
+ */
+export const parseVerdict = (text: string): Verdict | undefined => {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) {
+    return;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return;
+  }
+  const result = verdictSchema.safeParse(parsed);
+  return result.success ? result.data : undefined;
+};