blume 2.1.3 → 2.2.1

package/src/core/schema.ts

@@ -43,6 +43,7 @@ import { isExternalUrl, normalizeBasePath } from "./base-path.ts";
 import { FOOTER_SOCIALS } from "./footer.ts";
 import { PUBLIC_HOST_URL } from "./github.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
+import { isBuiltInMcpClient, mcpClients } from "./mcp-clients.ts";
 import { openInChatProviders } from "./open-in-chat.ts";
 import { PAGE_MODES } from "./page-modes.ts";
 import { redirectPatternError } from "./redirect-patterns.ts";
@@ -305,11 +306,24 @@ const pageMetaBaseSchema = z.strictObject({
   type: z.string().optional(),
 });
 
-export const pageMetaSchema = pageMetaBaseSchema;
-
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
 
+/**
+ * Fold the top-level `hidden`/`noindex` shorthands into the nested fields
+ * every consumer reads (`sidebar.hidden`, `seo.noindex`). It runs inside both
+ * page schemas, so the scan's `PageMeta` (the sitemap, llms.txt, search) and
+ * the content collections' `entry.data` (the page's robots tag) can't
+ * disagree about a page that uses the shorthand.
+ */
+const foldShorthands = <Meta extends PageMeta>(meta: Meta): Meta => ({
+  ...meta,
+  seo: { ...meta.seo, noindex: meta.seo.noindex || meta.noindex },
+  sidebar: { ...meta.sidebar, hidden: meta.sidebar.hidden || meta.hidden },
+});
+
+export const pageMetaSchema = pageMetaBaseSchema.transform(foldShorthands);
+
 /** The fully-defaulted front matter of a page that declares nothing. */
 const EMPTY_PAGE_META: PageMeta = pageMetaBaseSchema.parse({});
 
@@ -326,11 +340,12 @@ const EMPTY_PAGE_META: PageMeta = pageMetaBaseSchema.parse({});
  */
 export const pageCollectionSchema = pageMetaBaseSchema
   .loose()
+  .transform(foldShorthands)
   // oxlint-disable-next-line promise/prefer-await-to-then -- zod's catch, not a promise
   .catch(() => EMPTY_PAGE_META);
 
 /** Built-in page frontmatter keys; custom keys must never redeclare one. */
-const BUILT_IN_PAGE_META_KEYS = new Set<string>(
+export const BUILT_IN_PAGE_META_KEYS: ReadonlySet<string> = new Set<string>(
   pageMetaBaseSchema.keyof().options
 );
 
@@ -473,10 +488,13 @@ const apiConfigSchema = z.strictObject({
 });
 
 /**
- * The site footer: a row of links, and social profile icons. Unset, the site
- * has no footer (a `components.ts` `Footer` still renders).
+ * The site footer: a copyright line, a row of links, and social profile
+ * icons. Unset, the site has no footer (a `components.ts` `Footer` still
+ * renders).
  */
 const footerConfigSchema = z.strictObject({
+  /** A line of plain text between the links and the icons (`© 2026 Acme, Inc.`). */
+  copyright: localizableLabelSchema.optional(),
   /** Links in one row, in the order written. */
   links: z
     .array(z.strictObject({ href: z.string(), label: localizableLabelSchema }))
@@ -877,7 +895,91 @@ const publicJwkSchema = z
     }
   });
 
+// The label is the row button's only accessible name (its icon is
+// decorative), so unlike a header link's it can't be blank in any locale.
+const mcpClientLabelSchema = z.union(
+  [
+    z.string().trim().min(1),
+    z
+      .record(z.string(), z.string().trim().min(1))
+      .refine((value) => Object.keys(value).length > 0, {
+        message: "Provide at least one locale's label.",
+      }),
+  ],
+  { error: "Expected a label, or a map of locale code to label" }
+);
+
+// A "Connect to MCP" row for a client Blume doesn't ship: its `command` is
+// copied with `{name}` and `{url}` filled in.
+const mcpCustomClientSchema = z.strictObject({
+  command: z.string().trim().min(1),
+  icon: iconName.optional(),
+  label: mcpClientLabelSchema,
+});
+
+const ACCEPTED_MCP_CLIENTS = `${mcpClients.map((key) => `"${key}"`).join(", ")}, or a custom client { label, command, icon? }`;
+
+/** A union's issue: every member failed, each with issues of its own. */
+const isUnionIssue = (
+  issue: z.core.$ZodIssue
+): issue is z.core.$ZodIssueInvalidUnion => issue.code === "invalid_union";
+
+// A bad entry fails the list member of `clients`, which zod reports as a bare
+// "Invalid input" on the whole list; that union issue is all this map sees.
+// The entries' issues ride along in `errors`. The culprit is an entry that
+// matches neither a built-in key nor a custom client, which fails as a union
+// at its index (a blank field or an unknown key elsewhere doesn't fail the
+// list on its own). Name that entry, and for a custom client its bad field.
+const mcpClientsError = (issue: z.core.$ZodRawIssue): string => {
+  const entryIssue = (issue.code === "invalid_union" ? issue.errors : [])
+    .flat()
+    .filter(isUnionIssue)
+    .find((nested) => Number.isInteger(nested.path[0]));
+  if (!entryIssue) {
+    return `agents.mcp.clients takes true, false, or a list whose entries are each ${ACCEPTED_MCP_CLIENTS}.`;
+  }
+  const index = Number(entryIssue.path[0]);
+  const at = `agents.mcp.clients.${String(index)}`;
+  const entry = Array.isArray(issue.input) ? issue.input[index] : null;
+  if (isString(entry)) {
+    return `${at} is "${entry}", which isn't a built-in client. Use ${ACCEPTED_MCP_CLIENTS}.`;
+  }
+  const fieldIssue = entryIssue.errors
+    .flat()
+    .find((nested) => nested.path.length > 0);
+  return fieldIssue
+    ? `${at}.${fieldIssue.path.map(String).join(".")}: ${fieldIssue.message}. A custom client is { label, command, icon? }.`
+    : `${at} isn't ${ACCEPTED_MCP_CLIENTS}.`;
+};
+
 const mcpConfigSchema = z.strictObject({
+  /**
+   * The "Connect to MCP" page action's clients. `true` (the default) lists
+   * every built-in client, `false` none (the menu keeps "Copy server URL"),
+   * and an array picks built-in clients by key and adds custom ones, in the
+   * given order. Normalized to the list so consumers read a plain array.
+   */
+  clients: z
+    .union(
+      [
+        z.boolean(),
+        z.array(z.union([z.enum(mcpClients), mcpCustomClientSchema])).refine(
+          (value) => {
+            const keys = value.filter(isBuiltInMcpClient);
+            return new Set(keys).size === keys.length;
+          },
+          { message: "agents.mcp.clients must not repeat a built-in client." }
+        ),
+      ],
+      { error: mcpClientsError }
+    )
+    .default(true)
+    .transform((value) => {
+      if (isBoolean(value)) {
+        return value ? [...mcpClients] : [];
+      }
+      return value;
+    }),
   enabled: z.boolean().default(false),
   /** Optional system hint passed to connecting agents. */
   instructions: z.string().optional(),
@@ -1168,6 +1270,8 @@ export type AssistantConfig = NonNullable<
 >;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";
+export { mcpClients } from "./mcp-clients.ts";
+export type { McpClient, McpCustomClient } from "./mcp-clients.ts";
 
 // Reader-facing "Export" page action (PDF via print, EPUB via client-side
 // generation). Off by default. Accepts a shorthand boolean to toggle both
@@ -2257,7 +2361,7 @@ export const blumeConfigSchema = z
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message:
-          'rateLimit: cloudflare() counts with a Workers binding, so it needs `deployment: cloudflare()` from "blume/deploy". On another host, use upstash() or memory() from "blume/ratelimit".',
+          'rateLimit: cloudflare() counts with a Workers binding, so it needs `deployment: cloudflare()` from "blume/deploy". On another host, use upstash(), unkey(), or memory() from "blume/ratelimit".',
         path: ["rateLimit"],
       });
     }

package/src/core/sources/mdx-remote.ts

@@ -9,6 +9,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
+import { extractHeadings } from "./normalize.ts";
 import { REMOTE_TIMEOUT_MS } from "./remote.ts";
 import type {
   ContentSource,
@@ -71,20 +72,29 @@ interface RemoteRef {
 // arbitrary third party.
 const GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
 
+const isGithubUrl = (url: string): boolean =>
+  URL.canParse(url) && GITHUB_HOSTS.has(new URL(url).hostname);
+
 const githubHeaders = (url: string): Record<string, string> => {
   const token = process.env.GITHUB_TOKEN;
-  if (!token) {
-    return {};
-  }
-  let host = "";
-  try {
-    host = new URL(url).hostname;
-  } catch {
-    return {};
-  }
-  return GITHUB_HOSTS.has(host) ? { authorization: `Bearer ${token}` } : {};
+  return token && isGithubUrl(url) ? { authorization: `Bearer ${token}` } : {};
 };
 
+// What GitHub answers a request for a private repository's file without a
+// token (404, so it never confirms the repository exists), a token it rejects
+// (401), and a client past the unauthenticated rate limit (403).
+const TOKEN_STATUSES = new Set([401, 403, 404]);
+
+/**
+ * Why a request failed, naming GITHUB_TOKEN when it's unset and a token could
+ * fix the status. A public repository needs no token, so a raw `url` source
+ * declares none up front and only says so here, once a request fails.
+ */
+const statusReason = (url: string, status: number): string =>
+  TOKEN_STATUSES.has(status) && !process.env.GITHUB_TOKEN && isGithubUrl(url)
+    ? `${url} -> ${status}; GITHUB_TOKEN is not set, which a private repository needs`
+    : `${url} -> ${status}`;
+
 /**
  * GET `url`'s body, giving up after {@link REMOTE_TIMEOUT_MS}: a server that
  * accepts the connection and never finishes answering would otherwise hold the
@@ -103,7 +113,7 @@ const fetchText = async (
       signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS),
     });
     if (!res.ok) {
-      throw new Error(`${url} -> ${res.status}`);
+      throw new Error(statusReason(url, res.status));
     }
     return await res.text();
   } catch (error) {
@@ -183,6 +193,50 @@ const enumerateGithub = async (
   };
 };
 
+// A line an ATX heading opens (`# Title`); any other first line can only open
+// a setext heading, underlined on the line after it.
+const ATX_HEADING = /^ {0,3}#/u;
+
+/** A remote page's body and front matter, as the source hands them on. */
+interface RemotePage {
+  body: string;
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- pre-validation front matter, as `SourceEntry.data` holds it
+  data: Record<string, unknown>;
+}
+
+/**
+ * Drop a remote page's leading h1 when it is the page's title. A file written
+ * to read on GitHub opens with `# Title`, and Blume renders the page's title
+ * as its h1, so the heading would show twice. A local page loses the
+ * duplicate when its author deletes the heading (the fix the multiple-h1
+ * audit names); a remote file can't be edited from the site that reads it.
+ * The heading's text becomes `title` when the front matter sets none, the
+ * title Blume derives from it anyway, and an h1 that differs from a front
+ * matter title stays. The heading's lines are blanked rather than removed, so
+ * every other line keeps the number it has in the remote file.
+ */
+const withoutTitleHeading = (page: RemotePage): RemotePage => {
+  const lines = page.body.split("\n");
+  const start = lines.findIndex((line) => line.trim() !== "");
+  const span = ATX_HEADING.test(lines[start] ?? "") ? 1 : 2;
+  const [heading] =
+    start === -1
+      ? []
+      : extractHeadings(lines.slice(start, start + span).join("\n"));
+  if (
+    heading?.depth !== 1 ||
+    heading.text === "" ||
+    (page.data.title !== undefined && page.data.title !== heading.text)
+  ) {
+    return page;
+  }
+  lines.fill("", start, start + span);
+  return {
+    body: lines.join("\n"),
+    data: { ...page.data, title: heading.text },
+  };
+};
+
 /**
  * Remote Markdown/MDX content source. Fetches raw `.md`/`.mdx` over HTTP and
  * passes the text straight through `normalizeEntry`. A snapshot under
@@ -229,12 +283,19 @@ export const mdxRemoteSource = (
     const text = await fetchText(item.fetchUrl, doFetch);
     const parsed = matter(text);
     const format = item.ref.toLowerCase().endsWith(".mdx") ? "mdx" : "md";
-    return {
-      body: { format, text: parsed.content },
+    const page = withoutTitleHeading({
+      body: parsed.content,
       data: parsed.data,
+    });
+    return {
+      body: { format, text: page.body },
+      data: page.data,
       editUrl: item.editUrl,
       hash: hashText(text),
-      raw: text,
+      // The body is the text's tail, after the front matter, which stays as
+      // written: a title taken from the dropped heading lives in `data`, as a
+      // title derived from a local page's heading does.
+      raw: text.slice(0, text.length - parsed.content.length) + page.body,
       ref: item.ref,
     };
   };