blume 1.7.2 → 1.7.3

package/src/core/schema.ts

@@ -869,6 +869,23 @@ const llmsTxtObjectSchema = z.strictObject({
 
 type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
 
+/** The object form of `ai.catalog`; a bare boolean normalizes onto it. */
+const aiCatalogObjectSchema = z.strictObject({
+  enabled: z.boolean().default(true),
+  /**
+   * Representative queries per catalog entry, keyed by the entry's
+   * `<namespace>:<name>` (the identifier minus its `urn:air:<host>:` prefix,
+   * e.g. `mcp:docs`, `skill:blume`, `api:docs`). Replaces the generated
+   * defaults for that entry; 2–5 short natural-language questions the
+   * resource can answer, which registries embed for semantic search.
+   */
+  queries: z
+    .record(z.string().min(1), z.array(z.string().trim().min(1)).min(1))
+    .default({}),
+});
+
+type AiCatalogResolved = z.output<typeof aiCatalogObjectSchema>;
+
 const aiConfigSchema = z.strictObject({
   /**
    * The JSON docs API: the page index, per-page JSON, and navigation under
@@ -983,6 +1000,21 @@ const aiConfigSchema = z.strictObject({
       }
     })
     .optional(),
+  /**
+   * The AI Catalog / ARD manifest at `/.well-known/ai-catalog.json` (mirrored
+   * at `/.well-known/ard.json`): one entry per agent-facing resource the site
+   * publishes — the MCP server card, each agent skill, the JSON docs API's
+   * OpenAPI document, each rendered API reference, and llms.txt — so agent
+   * registries can index the site from its domain alone. Needs a
+   * `deployment.site` (identifiers are domain-anchored URNs). On by default;
+   * the object form overrides the generated representative queries.
+   */
+  catalog: z
+    .union([z.boolean(), aiCatalogObjectSchema])
+    .default(true)
+    .transform((value): AiCatalogResolved =>
+      isBoolean(value) ? { enabled: value, queries: {} } : value
+    ),
   /**
    * `llms.txt`/`llms-full.txt` emission. A bare boolean toggles it; the object
    * form adds `openapi: false` to keep generated API reference pages out of

package/src/core/types.ts

@@ -220,6 +220,11 @@ export type NavNode =
        */
       display: SidebarDisplay;
       icon?: string;
+      /**
+       * The group row's link: an explicit-config group's `root`, or the
+       * generated folder's index page route. Absent when there is no page at
+       * the group's own path, so the row never links to a 404.
+       */
       route?: string;
       /**
        * The group's URL path (its folder route prefix), even when the folder

package/src/deploy/artifacts.ts

@@ -4,6 +4,11 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "pathe";
 
 import { buildAgentReadability } from "../ai/agent-readability.ts";
+import {
+  AI_CATALOG_PATH,
+  ARD_MANIFEST_PATH,
+  buildAiCatalog,
+} from "../ai/ai-catalog.ts";
 import { API_CATALOG_PATH, buildApiCatalog } from "../ai/api-catalog.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildLlmsFiles } from "../ai/llms.ts";
@@ -234,8 +239,12 @@ const emitAgentSkills = async (
 const emitWellKnownFiles = async (
   config: ResolvedConfig,
   distDir: string,
+  skills: readonly SkillArtifact[],
   logger: ArtifactLogger
 ): Promise<void> => {
+  // One document, two paths: the ai-catalog spec's well-known URI and the
+  // ARD v0.91 one (see `ai/ai-catalog.ts`).
+  const aiCatalog = buildAiCatalog(config, skills);
   const files = [
     {
       content: buildSignaturesDirectory(config),
@@ -247,6 +256,8 @@ const emitWellKnownFiles = async (
       label: "RFC 9727",
       path: API_CATALOG_PATH,
     },
+    { content: aiCatalog, label: "AI Catalog", path: AI_CATALOG_PATH },
+    { content: aiCatalog, label: "ARD manifest", path: ARD_MANIFEST_PATH },
   ];
   for (const file of files) {
     const target = join(distDir, file.path.slice(1));
@@ -362,7 +373,7 @@ export const publishBuildArtifacts = async (
     logger.info("Generated agent-readability.json");
   }
 
-  await emitWellKnownFiles(project.config, distDir, logger);
+  await emitWellKnownFiles(project.config, distDir, skills, logger);
   await emitAgentSkills(project, distDir, skills, logger);
 
   await emitRedirectFiles(project.config, distDir, logger);

package/src/deploy/headers.ts

@@ -1,3 +1,4 @@
+import { crossOriginDiscoveryPaths } from "../ai/ai-catalog.ts";
 import {
   API_CATALOG_PATH,
   API_CATALOG_TYPE,
@@ -95,6 +96,11 @@ export const buildNetlifyHeaders = (
       `${deployBase}${SIGNATURES_DIRECTORY_PATH}\n  Content-Type: ${SIGNATURES_DIRECTORY_TYPE}`
     );
   }
+  // Agent registries fetch the discovery documents cross-origin; a static
+  // host sends no CORS header unless told to.
+  for (const path of crossOriginDiscoveryPaths(config)) {
+    rules.push(`${deployBase}${path}\n  Access-Control-Allow-Origin: *`);
+  }
   // Published skills live at the deployment base, outside `basePath` — the
   // `.md` charset rule above misses them whenever a basePath is set, and the
   // RFC wants archives served as application/gzip explicitly.

package/src/deploy/vercel-negotiation.ts

@@ -235,6 +235,26 @@ export const buildNegotiationRoutes = (
 /** The `src` of the injected homepage `Link` header route. */
 const HOME_SRC = "^/$";
 
+const ALLOW_ANY_ORIGIN = "*";
+
+/**
+ * A main-phase `continue` route stamping `Access-Control-Allow-Origin: *` on
+ * one static discovery document (see `crossOriginDiscoveryPaths`), so a
+ * registry reading it from another origin isn't refused by the browser.
+ */
+const corsRoute = (path: string): VercelRoute => ({
+  continue: true,
+  headers: { "access-control-allow-origin": ALLOW_ANY_ORIGIN },
+  src: `^${routePattern(path)}$`,
+});
+
+/** Whether a route is a `corsRoute` — the same three-field shape test as the others. */
+const isCorsRoute = (route: VercelRoute): boolean =>
+  route.continue === true &&
+  route.headers?.["access-control-allow-origin"] === ALLOW_ANY_ORIGIN &&
+  isString(route.src) &&
+  Object.keys(route).length === 3;
+
 /**
  * Whether a route is one this module previously injected, so re-injection
  * replaces rather than duplicates. Rewrites are identified by their `accept`
@@ -258,7 +278,8 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
   (route.continue === true &&
     isString(route.headers?.link) &&
     route.src === HOME_SRC &&
-    Object.keys(route).length === 3);
+    Object.keys(route).length === 3) ||
+  isCorsRoute(route);
 
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
@@ -287,7 +308,8 @@ export const injectNegotiationRoutes = (
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
   homeTokens?: number,
-  notFound: NotFoundVariants = {}
+  notFound: NotFoundVariants = {},
+  corsPaths: readonly string[] = []
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -325,6 +347,7 @@ export const injectNegotiationRoutes = (
       src: HOME_SRC,
     });
   }
+  headerRoutes.push(...corsPaths.map(corsRoute));
   // Headers first: `continue` routes accumulate, so a request the rewrite
   // route then terminates (Markdown negotiation on the homepage) still carries
   // the Link header.

package/src/search/build.ts

@@ -1,4 +1,6 @@
-import { join } from "pathe";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
 
 /**
  * Build a local Pagefind search index over the built site. Pagefind indexes
@@ -6,6 +8,15 @@ import { join } from "pathe";
  * `data-pagefind-ignore`, which Blume stamps on non-indexable pages
  * (search-excluded, or hidden without the opt-in), so those stay out.
  *
+ * The index files are fetched with `getFiles()` and written here rather than
+ * with Pagefind's `writeFiles()`: in service mode Pagefind acknowledges
+ * `writeFiles()` once tokio has buffered the writes, not once they are on
+ * disk, and `close()` kills the backend, so a loaded CI host can ship a
+ * truncated `pagefind-entry.json` (Pagefind/pagefind#1271). Writing the bytes
+ * ourselves puts them on disk before the backend goes away. Fixed upstream in
+ * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
+ * that fix.
+ *
  * Returns the number of pages indexed.
  */
 export const buildSearchIndex = async (outDir: string): Promise<number> => {
@@ -17,11 +28,22 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
   }
 
   // These awaits are strictly ordered, not independent: the directory must be
-  // indexed before its files are written, and the index closed only after.
+  // indexed before its files are read, and the index closed only after.
   // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
-  await index.writeFiles({ outputPath: join(outDir, "pagefind") });
+  const { files } = await index.getFiles();
   await pagefind.close();
 
+  const searchDir = join(outDir, "pagefind");
+  const directories = new Set(
+    files.map((file) => dirname(join(searchDir, file.path)))
+  );
+  await Promise.all(
+    [...directories].map((directory) => mkdir(directory, { recursive: true }))
+  );
+  await Promise.all(
+    files.map((file) => writeFile(join(searchDir, file.path), file.content))
+  );
+
   return result.page_count;
 };

package/src/theme/entry.ts

@@ -298,6 +298,11 @@ ${THEME_MAPPING}
   --tw-prose-pre-bg: var(--blume-code-background);
   --tw-prose-th-borders: var(--blume-border);
   --tw-prose-td-borders: var(--blume-border);
+  /* Neutralized: the plugin defaults are near-black text and shadow with no
+     dark counterpart (Blume never applies prose-invert), and the kbd rule
+     below draws the badge with Blume tokens instead. */
+  --tw-prose-kbd: inherit;
+  --tw-prose-kbd-shadows: transparent;
   color: var(--blume-muted-foreground);
   font-size: 0.875rem;
   line-height: 1.7;
@@ -827,6 +832,24 @@ pre:has(.line.focused):hover .line:not(.focused) {
   content: none;
 }
 
+/* Keyboard keys (<kbd>) render as the same bordered badge the search dialog
+   uses for its shortcut hints. Typography's own kbd rule is scoped with
+   :not(.not-prose *), so it never reaches a key inside <Steps>, <Callout>,
+   <Card>, or any other not-prose component; this rule is deliberately
+   unscoped from that exclusion so a key looks the same everywhere in the
+   content column. Unlayered, so it outranks the plugin's layered rule. */
+.prose kbd {
+  background: var(--blume-muted);
+  border: 1px solid var(--blume-border);
+  border-radius: 0.25rem;
+  box-shadow: none;
+  color: inherit;
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+  font-weight: 500;
+  padding: 0.125rem 0.25rem;
+}
+
 /* Inline code highlighting: Shiki colors the tokens of a \`code\`{:lang} snippet
    via the same dual-theme CSS variables as fenced blocks, keeping the inline
    pill background. Always on — it only fires on the trailing {:lang} marker. */