blume 1.7.3 → 2.0.1

package/dist/cli/chunk-0qymqwzz.js.map

@@ -1,15 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/ai/api/paths.ts", "../src/ai/api-catalog.ts", "../src/ai/mcp/discovery.ts", "../src/ai/skills.ts", "../src/ai/tar.ts", "../src/ai/ai-catalog.ts"],
-  "sourcesContent": [
-    "/**\n * Where the JSON docs API and its OpenAPI description are served. Base-less\n * (like every route Blume emits); callers layer `deployment.base` on top.\n * Under `/api/` alongside the Ask AI endpoint (`/api/ask`) so the namespace a\n * Blume site reserves for live endpoints stays one prefix, and under its own\n * `docs` segment so a search provider's proxy at `/api/search` never collides.\n */\n\nexport const OPENAPI_PATH = \"/openapi.json\";\nexport const API_BASE = \"/api/docs\";\nexport const API_PAGES_PATH = `${API_BASE}/pages.json`;\nexport const API_PAGE_PATH = `${API_BASE}/pages/{route}.json`;\nexport const API_NAVIGATION_PATH = `${API_BASE}/navigation.json`;\nexport const API_SEARCH_PATH = `${API_BASE}/search`;\n\n/** The `pages/{route}.json` path segment for a route (`index` for home). */\nexport const pageParam = (route: string): string =>\n  route === \"/\" ? \"index\" : route.slice(1);\n\n/** The base-less served path of a route's per-page JSON document. */\nexport const pageJsonPath = (route: string): string =>\n  `${API_BASE}/pages/${pageParam(route)}.json`;\n",
-    "import { normalizeBasePath, withBasePath } from \"../core/base-path.ts\";\nimport type { ResolvedConfig } from \"../core/schema.ts\";\nimport { absoluteUrl } from \"../core/site-url.ts\";\nimport { resolveReferences } from \"../openapi/references.ts\";\nimport { API_BASE, OPENAPI_PATH } from \"./api/paths.ts\";\n\n/**\n * RFC 9727 API catalog: a linkset (RFC 9264) at `/.well-known/api-catalog`\n * enumerating the APIs a publisher offers, so agents can discover them from\n * the domain alone. Blume already knows the site's APIs — the configured\n * OpenAPI/AsyncAPI references and the hosted MCP server — so the catalog is\n * generated, never hand-written: one entry per API, anchored at its docs\n * route (the RFC's own examples anchor on developer-portal pages), with\n * `service-doc` pointing at the rendered reference and `service-desc` at the\n * spec when it lives at a fetchable URL. The site's own JSON docs API is an\n * entry too, described by its generated `/openapi.json`.\n */\n\nexport const API_CATALOG_PATH = \"/.well-known/api-catalog\";\nexport const API_CATALOG_TYPE = \"application/linkset+json\";\n\n/** An RFC 9264 linkset entry, restricted to the relations Blume emits. */\ninterface LinksetEntry {\n  anchor: string;\n  \"service-desc\"?: { href: string; type?: string }[];\n  \"service-doc\"?: { href: string; type: string }[];\n}\n\nconst HTTP_URL = /^https?:\\/\\//u;\n\n/** The catalog's linkset entries; empty when the site publishes no APIs. */\nconst linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {\n  const site = config.deployment.site ?? null;\n  const deployBase = normalizeBasePath(config.deployment.base);\n  const abs = (path: string): string => {\n    const based = withBasePath(deployBase, path);\n    return site ? absoluteUrl(site, based) : based;\n  };\n\n  const entries: LinksetEntry[] = [];\n  for (const reference of resolveReferences(config)) {\n    // Blume-rendered pages mount under `basePath`; Scalar pages stay at the\n    // raw route (see `referenceRoutes`).\n    const docRoute =\n      reference.renderer === \"blume\"\n        ? withBasePath(reference.basePath, reference.route)\n        : reference.route;\n    const entry: LinksetEntry = {\n      anchor: abs(docRoute),\n      \"service-doc\": [{ href: abs(docRoute), type: \"text/html\" }],\n    };\n    // A local spec file is parsed into pages, not served, so only a remote\n    // spec has a fetchable `service-desc` URL.\n    if (HTTP_URL.test(reference.spec)) {\n      entry[\"service-desc\"] = [{ href: reference.spec }];\n    }\n    entries.push(entry);\n  }\n\n  if (config.ai.api) {\n    entries.push({\n      anchor: abs(API_BASE),\n      \"service-desc\": [{ href: abs(OPENAPI_PATH), type: \"application/json\" }],\n      \"service-doc\": [{ href: abs(\"/\"), type: \"text/html\" }],\n    });\n  }\n\n  if (config.ai.mcp.enabled) {\n    entries.push({\n      anchor: abs(config.ai.mcp.route),\n      \"service-desc\": [\n        { href: abs(\"/.well-known/mcp.json\"), type: \"application/json\" },\n      ],\n      \"service-doc\": [{ href: abs(\"/\"), type: \"text/html\" }],\n    });\n  }\n  return entries;\n};\n\n/** Whether the site has anything to catalog — gates every emission surface. */\nexport const hasApiCatalog = (config: ResolvedConfig): boolean =>\n  linksetEntries(config).length > 0;\n\n/** The `application/linkset+json` document, or null when there are no APIs. */\nexport const buildApiCatalog = (config: ResolvedConfig): string | null => {\n  const linkset = linksetEntries(config);\n  if (linkset.length === 0) {\n    return null;\n  }\n  return `${JSON.stringify({ linkset }, null, 2)}\\n`;\n};\n",
-    "import { withBasePath } from \"../../core/base-path.ts\";\nimport { absoluteUrl, siteRoot } from \"../../core/site-url.ts\";\nimport { trimChar } from \"../../core/trim.ts\";\nimport { MCP_TOOLS } from \"./tools.ts\";\nimport type { McpToolMeta } from \"./tools.ts\";\n\n/** Inputs needed to describe the MCP server in discovery documents. */\nexport interface McpDiscoveryInput {\n  /** Normalized `deployment.base` (`\"\"` or `/seg`); the route is base-less. */\n  base: string;\n  name: string;\n  route: string;\n  site: string | null;\n  version: string;\n}\n\n/** The MCP server's address — absolute when a site is configured. */\nconst serverUrl = (input: McpDiscoveryInput): string => {\n  // The endpoint is a generated Astro page, so it's served under\n  // `deployment.base` like every other route (the sitemap/llms.txt convention).\n  const path = withBasePath(input.base, input.route);\n  // Concatenate rather than `new URL(path, site)` — a root-absolute path\n  // would drop the base path of a subpath deployment (`acme.com/docs`).\n  return input.site ? absoluteUrl(input.site, path) : path;\n};\n\n/**\n * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use\n * to find the server and its transport.\n */\nexport const buildMcpDiscovery = (input: McpDiscoveryInput) => ({\n  servers: [\n    {\n      name: input.name,\n      transport: \"streamable-http\",\n      url: serverUrl(input),\n    },\n  ],\n});\n\n/** The published `/v1/` Server Card schema (SEP-2127 extension). */\nconst SERVER_CARD_SCHEMA =\n  \"https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json\";\n\n/** The schema caps `description` (and `title`) at 100 characters. */\nconst CARD_TEXT_MAX = 100;\n\nconst truncate = (text: string): string =>\n  text.length > CARD_TEXT_MAX ? `${text.slice(0, CARD_TEXT_MAX - 1)}…` : text;\n\n// The server-card schema constrains `name` to `namespace/server` in ASCII\n// (`^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$`), so the display name cannot reuse the\n// route slugifier, which keeps Unicode letters. Decompose (NFKD) and drop\n// combining marks first so an accented name transliterates (`Café` → `cafe`)\n// instead of losing the letter.\nconst NON_ASCII_SLUG = /[^a-z0-9]+/gu;\nconst COMBINING_MARKS = /\\p{M}+/gu;\n\nexport const asciiSlugify = (text: string): string =>\n  trimChar(\n    text\n      .normalize(\"NFKD\")\n      .replace(COMBINING_MARKS, \"\")\n      .toLowerCase()\n      .replace(NON_ASCII_SLUG, \"-\"),\n    \"-\"\n  );\n\n/**\n * The card's identity in the schema's reverse-DNS `namespace/server` form:\n * the site hostname reversed (`useblume.dev` → `dev.useblume`), or\n * `localhost` when no site is configured, plus the slugged display name (an\n * entirely non-ASCII name falls back to `docs`).\n */\nconst reverseDnsName = (input: McpDiscoveryInput): string => {\n  let namespace = \"localhost\";\n  if (input.site) {\n    try {\n      namespace = new URL(input.site).hostname\n        .split(\".\")\n        .toReversed()\n        .join(\".\");\n    } catch {\n      // Not a parsable URL; the local namespace is honest enough.\n    }\n  }\n  return `${namespace}/${asciiSlugify(input.name) || \"docs\"}`;\n};\n\nconst HTTP_URL = /^https?:\\/\\//u;\n\n/**\n * The `/.well-known/mcp/server-card.json` document. The core follows the\n * SEP-2127 Server Card extension schema (`$schema`, reverse-DNS `name`,\n * `remotes` — which the schema requires to be absolute, so it appears only\n * when a `site` is configured). Alongside it ride initialize-shaped compat\n * fields (`serverInfo`, `capabilities`, `transports`) for scanners built\n * against the SEP's earlier revision, plus Blume's advertised tool set —\n * schema-legal extras (`additionalProperties` is open), and the tool list is\n * genuinely static for a docs server, unlike the dynamic servers the spec\n * excludes primitives for. Full input schemas are served live via\n * `tools/list`.\n */\nexport interface McpServerCard {\n  $schema: string;\n  capabilities: {\n    resources: { listChanged: boolean; subscribe: boolean };\n    tools: { listChanged: boolean };\n  };\n  description: string;\n  name: string;\n  /** Absolute endpoints only — present when a `site` is configured. */\n  remotes?: { type: string; url: string }[];\n  serverInfo: { name: string; version: string };\n  title: string;\n  tools: McpToolMeta[];\n  transport: string;\n  transports: { endpoint: string; type: string }[];\n  url: string;\n  version: string;\n  websiteUrl?: string;\n}\n\nexport const buildMcpServerCard = (input: McpDiscoveryInput): McpServerCard => {\n  const url = serverUrl(input);\n  const card: McpServerCard = {\n    $schema: SERVER_CARD_SCHEMA,\n    // Resources mirror the page list (one `text/markdown` resource per page);\n    // a rebuilt site replaces the server wholesale, so nothing changes live.\n    capabilities: {\n      resources: { listChanged: false, subscribe: false },\n      tools: { listChanged: false },\n    },\n    description: truncate(\n      `Model Context Protocol server for the ${input.name} documentation.`\n    ),\n    name: reverseDnsName(input),\n    serverInfo: { name: input.name, version: input.version },\n    title: truncate(input.name),\n    tools: MCP_TOOLS.map((tool) => ({\n      annotations: tool.annotations,\n      description: tool.description,\n      name: tool.name,\n      title: tool.title,\n    })),\n    transport: \"streamable-http\",\n    transports: [{ endpoint: url, type: \"streamable-http\" }],\n    url,\n    version: input.version,\n  };\n  if (HTTP_URL.test(url)) {\n    card.remotes = [{ type: \"streamable-http\", url }];\n  }\n  if (input.site) {\n    card.websiteUrl = siteRoot(input.site);\n  }\n  return card;\n};\n",
-    "import { createHash } from \"node:crypto\";\nimport { readdir, readFile, stat } from \"node:fs/promises\";\n\nimport { join } from \"pathe\";\n\nimport { normalizeBasePath } from \"../core/base-path.ts\";\nimport matter from \"../core/frontmatter.ts\";\nimport type { ResolvedConfig } from \"../core/schema.ts\";\nimport { buildTarGz } from \"./tar.ts\";\nimport type { TarEntry } from \"./tar.ts\";\n\n/**\n * Agent Skills discovery (Cloudflare's Agent Skills Discovery RFC v0.2.0):\n * the skills a site publishes are enumerated in an index at\n * `/.well-known/agent-skills/index.json`, each entry pointing at its artifact\n * with a SHA-256 digest. A skill that is only a `SKILL.md` publishes the file\n * verbatim (`type: \"skill-md\"`); a skill with supporting resources (scripts,\n * references, assets) is bundled into a deterministic `.tar.gz`\n * (`type: \"archive\"`) so its relative references resolve after unpacking.\n */\n\nexport const AGENT_SKILLS_DIR = \"/.well-known/agent-skills\";\nexport const AGENT_SKILLS_INDEX_PATH = \"/.well-known/agent-skills/index.json\";\n\nconst AGENT_SKILLS_SCHEMA =\n  \"https://schemas.agentskills.io/discovery/0.2.0/schema.json\";\n\n/** Skill naming rule from the Agent Skills spec (1-64 chars enforced apart). */\nconst SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;\nconst SKILL_NAME_MAX = 64;\n/** The Agent Skills spec caps `description` at 1024 characters. */\nconst DESCRIPTION_MAX = 1024;\n\n/** One publishable skill artifact plus its index entry. */\nexport interface SkillArtifact {\n  /** Raw bytes to publish (the digest is computed over exactly these). */\n  content: Uint8Array;\n  description: string;\n  /** `sha256:{hex}` digest of `content`. */\n  digest: string;\n  name: string;\n  /** Path under the agent-skills dir: `{name}/SKILL.md` or `{name}.tar.gz`. */\n  path: string;\n  type: \"archive\" | \"skill-md\";\n}\n\nexport interface CollectedSkills {\n  skills: SkillArtifact[];\n  /** Human-readable reasons for anything skipped. */\n  warnings: string[];\n}\n\nconst sha256 = (content: Uint8Array): string =>\n  `sha256:${createHash(\"sha256\").update(content).digest(\"hex\")}`;\n\n/**\n * Every regular file under a skill directory, as archive entries with\n * `/`-separated relative paths, dotfiles (`.DS_Store`, `.git`) excluded,\n * sorted for deterministic archives. The owner-execute bit is preserved so a\n * skill's scripts stay runnable after unpacking.\n */\nconst collectEntries = async (\n  dir: string,\n  prefix = \"\"\n): Promise<TarEntry[]> => {\n  const entries: TarEntry[] = [];\n  const items = await readdir(dir, { withFileTypes: true });\n  for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {\n    if (item.name.startsWith(\".\")) {\n      continue;\n    }\n    const path = join(dir, item.name);\n    const relative = prefix ? `${prefix}/${item.name}` : item.name;\n    if (item.isDirectory()) {\n      // Sequential recursion keeps ordering deterministic.\n      // oxlint-disable-next-line no-await-in-loop\n      entries.push(...(await collectEntries(path, relative)));\n    } else if (item.isFile()) {\n      // oxlint-disable-next-line no-await-in-loop\n      const [content, info] = await Promise.all([readFile(path), stat(path)]);\n      entries.push({\n        content: new Uint8Array(content),\n        // oxlint-disable-next-line no-bitwise -- testing the owner-execute mode bit\n        executable: (info.mode & 0o100) !== 0,\n        path: relative,\n      });\n    }\n  }\n  return entries;\n};\n\n/** The two SKILL.md frontmatter fields the discovery index publishes. */\ninterface SkillMeta {\n  description: string;\n  name: string;\n}\n\ninterface SkillMetaResult {\n  meta: SkillMeta | null;\n  warning?: string;\n}\n\n/**\n * What js-yaml can put in a SKILL.md frontmatter field. Rich scalars (Dates)\n * ride along as the object arm; only strings are accepted below anyway.\n */\ntype FrontmatterField =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | FrontmatterField[]\n  | { [key: string]: FrontmatterField };\n\nconst isString = (value: FrontmatterField): value is string =>\n  typeof value === \"string\";\n\n/** Frontmatter of a SKILL.md, or null with a warning when unusable. */\nconst skillMeta = (raw: string, dirName: string): SkillMetaResult => {\n  let data: { description?: FrontmatterField; name?: FrontmatterField };\n  try {\n    ({ data } = matter(raw));\n  } catch {\n    return {\n      meta: null,\n      warning: `Skill \"${dirName}\" has unparsable SKILL.md frontmatter; skipped.`,\n    };\n  }\n  const name = isString(data.name) ? data.name : \"\";\n  const description = isString(data.description) ? data.description : \"\";\n  if (!(name && description)) {\n    return {\n      meta: null,\n      warning: `Skill \"${dirName}\" is missing the required \"name\"/\"description\" frontmatter; skipped.`,\n    };\n  }\n  if (!SKILL_NAME.test(name) || name.length > SKILL_NAME_MAX) {\n    return {\n      meta: null,\n      warning: `Skill \"${dirName}\" has an invalid name \"${name}\" (lowercase alphanumerics and single hyphens, max 64 chars); skipped.`,\n    };\n  }\n  return {\n    meta: { description: description.slice(0, DESCRIPTION_MAX), name },\n  };\n};\n\n/**\n * Collect the publishable skills from a directory whose subdirectories each\n * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories\n * without one are ignored silently — the directory may hold other assets —\n * while a present-but-invalid skill earns a warning so it isn't dropped\n * behind the publisher's back.\n */\nexport const collectSkills = async (dir: string): Promise<CollectedSkills> => {\n  const skills: SkillArtifact[] = [];\n  const warnings: string[] = [];\n  const items = await readdir(dir, { withFileTypes: true });\n  for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {\n    if (!item.isDirectory() || item.name.startsWith(\".\")) {\n      continue;\n    }\n    // oxlint-disable-next-line no-await-in-loop\n    const entries = await collectEntries(join(dir, item.name));\n    const skillMd = entries.find((entry) => entry.path === \"SKILL.md\");\n    if (!skillMd) {\n      continue;\n    }\n    const { meta, warning } = skillMeta(\n      new TextDecoder().decode(skillMd.content),\n      item.name\n    );\n    if (!meta) {\n      if (warning) {\n        warnings.push(warning);\n      }\n      continue;\n    }\n    // A lone SKILL.md ships verbatim; supporting resources ship as an\n    // archive so the skill's relative references resolve after unpacking.\n    const single = entries.length === 1;\n    const content = single ? skillMd.content : buildTarGz(entries);\n    skills.push({\n      content,\n      description: meta.description,\n      digest: sha256(content),\n      name: meta.name,\n      path: single ? `${meta.name}/SKILL.md` : `${meta.name}.tar.gz`,\n      type: single ? \"skill-md\" : \"archive\",\n    });\n  }\n  return { skills, warnings };\n};\n\n/**\n * The discovery index (v0.2.0 schema). Artifact URLs are path-absolute under\n * `deployment.base` — the RFC resolves them against the index origin.\n */\nexport const buildSkillsIndex = (\n  skills: readonly SkillArtifact[],\n  config: ResolvedConfig\n): string => {\n  const deployBase = normalizeBasePath(config.deployment.base);\n  const index = {\n    $schema: AGENT_SKILLS_SCHEMA,\n    skills: skills.map((skill) => ({\n      description: skill.description,\n      digest: skill.digest,\n      name: skill.name,\n      type: skill.type,\n      url: `${deployBase}${AGENT_SKILLS_DIR}/${skill.path}`,\n    })),\n  };\n  return `${JSON.stringify(index, null, 2)}\\n`;\n};\n",
-    "import { gzipSync } from \"node:zlib\";\n\nimport { createTar } from \"nanotar\";\n\n/**\n * `.tar.gz` writer for agent-skill archives, on nanotar's ustar writer.\n * Deterministic by construction — fixed mtime/uid/gid/owner attrs,\n * caller-ordered entries, and Node's gzip header carries no timestamp — so a\n * skill's archive digest only changes when its content does. That holds per\n * machine: the tar bytes are portable, but zlib's compressed stream differs\n * across architectures, so gzip-layer digests are not comparable across\n * platforms.\n */\n\n/** One regular file to archive. Paths are `/`-separated, relative, no `..`. */\nexport interface TarEntry {\n  /** Raw file bytes. */\n  content: Uint8Array;\n  /** Preserve the owner-execute bit (e.g. a skill's scripts). */\n  executable?: boolean;\n  /** Archive-relative path, e.g. `SKILL.md` or `references/FORMS.md`. */\n  path: string;\n}\n\n/** ustar `name` field capacity; skill layouts are shallow, so no `prefix`. */\nconst NAME_MAX = 100;\n\nconst encoder = new TextEncoder();\n\n/**\n * Build a gzipped ustar archive of the given files, in the given order. Paths\n * longer than the ustar `name` field or escaping the archive root throw to\n * surface a programming error — nanotar would silently truncate an oversized\n * name into a corrupt archive, so the validation stays here.\n */\nexport const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {\n  for (const entry of entries) {\n    if (encoder.encode(entry.path).byteLength > NAME_MAX) {\n      throw new Error(`tar path exceeds ${NAME_MAX} bytes: ${entry.path}`);\n    }\n    if (entry.path.startsWith(\"/\") || entry.path.split(\"/\").includes(\"..\")) {\n      throw new Error(`tar path must be archive-relative: ${entry.path}`);\n    }\n  }\n  const tar = createTar(\n    entries.map((entry) => ({\n      // Root-owned, epoch-mtime, empty owner names: every field a rebuild\n      // could vary is pinned so the archive bytes are a function of content.\n      attrs: {\n        gid: 0,\n        group: \"\",\n        mode: entry.executable ? \"755\" : \"644\",\n        mtime: 0,\n        uid: 0,\n        user: \"\",\n      },\n      data: entry.content,\n      name: entry.path,\n    }))\n  );\n  // Sync gzip with a pinned level; Node writes no timestamp into the header.\n  return new Uint8Array(gzipSync(tar, { level: 9 }));\n};\n",
-    "import { normalizeBasePath, withBasePath } from \"../core/base-path.ts\";\nimport type { ResolvedConfig } from \"../core/schema.ts\";\nimport { absoluteUrl } from \"../core/site-url.ts\";\nimport { resolveReferences } from \"../openapi/references.ts\";\nimport { API_CATALOG_PATH, hasApiCatalog } from \"./api-catalog.ts\";\nimport { OPENAPI_PATH } from \"./api/paths.ts\";\nimport { asciiSlugify } from \"./mcp/discovery.ts\";\nimport { AGENT_SKILLS_DIR } from \"./skills.ts\";\nimport type { SkillArtifact } from \"./skills.ts\";\n\n/**\n * The AI Catalog (Agent-Card/ai-catalog data model, `specVersion` 1.0) at\n * `/.well-known/ai-catalog.json`, which is also the Agentic Resource\n * Discovery (ARD) manifest: one entry per agent-facing resource the site\n * publishes, each an `urn:air:<host>:<namespace>:<name>` identifier, a\n * display name, the artifact's media type, a URL, and the\n * `representativeQueries` registries embed for semantic search. Like the\n * RFC 9727 catalog next to it, everything is derived from `blume.config.ts`\n * and the build's published skills — nothing is hand-written.\n *\n * ARD v0.91 moved its manifest to `/.well-known/ard.json` and calls\n * `ai-catalog.json` the predecessor path that consumers only *may* consult,\n * while the ai-catalog spec and today's agent-readiness scanners key on\n * `ai-catalog.json`. The ARD manifest is just an `entries` array (other\n * members are ignored), so the one document is written to both paths.\n *\n * Served as plain `application/json`: the `.json` extension gets it from\n * every static host with no header rule, and the scanners that gate on the\n * file ask for exactly that type. The registered `application/ai-catalog+json`\n * is what the `Link`/`<link>` advertisements declare the document to be.\n */\n\nexport const AI_CATALOG_PATH = \"/.well-known/ai-catalog.json\";\nexport const ARD_MANIFEST_PATH = \"/.well-known/ard.json\";\nexport const AI_CATALOG_TYPE = \"application/ai-catalog+json\";\nconst SPEC_VERSION = \"1.0\";\n\n/** One catalog entry, restricted to the terms Blume emits. */\ninterface CatalogEntry {\n  identifier: string;\n  displayName: string;\n  type: string;\n  url: string;\n  description?: string;\n  capabilities?: string[];\n  representativeQueries: string[];\n}\n\n/** An entry before its identifier and queries are resolved against the host. */\ninterface EntrySeed {\n  /** `<namespace>:<name>` — the identifier's tail and the `queries` key. */\n  key: string;\n  displayName: string;\n  type: string;\n  url: string;\n  description?: string;\n  capabilities?: string[];\n  /** Generated queries, replaced wholesale by a configured `queries[key]`. */\n  queries: string[];\n}\n\nconst REFERENCE_KIND_LABEL = {\n  asyncapi: \"AsyncAPI\",\n  graphql: \"GraphQL\",\n  openapi: \"OpenAPI\",\n} as const;\n\n/** The `urn:air` publisher: the configured site's hostname. */\nconst publisherHost = (site: string): string => new URL(site).hostname;\n\n/**\n * Whether the site publishes a catalog: the feature is on, a `deployment.site`\n * anchors the identifiers, and at least one entry exists. Every entry source\n * is a config flag, so the answer needs no build output — the same gate the\n * header rules, the `Link` header, and the head links read.\n */\nexport const hasAiCatalog = (config: ResolvedConfig): boolean =>\n  config.ai.catalog.enabled &&\n  Boolean(config.deployment.site) &&\n  (config.ai.mcp.enabled ||\n    config.ai.api ||\n    config.ai.llmsTxt.enabled ||\n    Boolean(config.ai.skills) ||\n    resolveReferences(config).length > 0);\n\n/**\n * The `.well-known` documents agent registries fetch cross-origin (browser\n * agents, hosted registries reading through a page). Each needs\n * `Access-Control-Allow-Origin: *` on the static surface; the MCP endpoint\n * itself already sets it at runtime.\n */\nexport const crossOriginDiscoveryPaths = (config: ResolvedConfig): string[] => {\n  const paths: string[] = [];\n  if (hasAiCatalog(config)) {\n    paths.push(AI_CATALOG_PATH, ARD_MANIFEST_PATH);\n  }\n  if (hasApiCatalog(config)) {\n    paths.push(API_CATALOG_PATH);\n  }\n  if (config.ai.mcp.enabled) {\n    paths.push(\"/.well-known/mcp.json\", \"/.well-known/mcp/server-card.json\");\n  }\n  return paths;\n};\n\nconst entrySeeds = (\n  config: ResolvedConfig,\n  skills: readonly SkillArtifact[],\n  abs: (path: string) => string\n): EntrySeed[] => {\n  const { title } = config;\n  const seeds: EntrySeed[] = [];\n\n  if (config.ai.mcp.enabled) {\n    const name = config.ai.mcp.name ?? title;\n    seeds.push({\n      capabilities: [\"search_docs\", \"get_page\", \"list_pages\", \"get_navigation\"],\n      description:\n        config.ai.mcp.instructions ??\n        `Model Context Protocol server over the ${title} documentation: full-text search, page Markdown, the page index, and the navigation tree.`,\n      displayName: name,\n      key: `mcp:${asciiSlugify(name) || \"docs\"}`,\n      queries: [\n        `search the ${title} documentation`,\n        `get a ${title} docs page as Markdown`,\n        `list every page in the ${title} docs`,\n      ],\n      type: \"application/mcp-server-card+json\",\n      url: abs(\"/.well-known/mcp/server-card.json\"),\n    });\n  }\n\n  for (const skill of skills) {\n    seeds.push({\n      description: skill.description,\n      displayName: skill.name,\n      key: `skill:${skill.name}`,\n      queries: [\n        `load the ${skill.name} agent skill`,\n        `how do I use ${skill.name}`,\n      ],\n      type:\n        skill.type === \"archive\"\n          ? \"application/agent-skills+gzip\"\n          : \"application/agent-skills+md\",\n      url: abs(`${AGENT_SKILLS_DIR}/${skill.path}`),\n    });\n  }\n\n  if (config.ai.api) {\n    seeds.push({\n      description: `REST API over the ${title} documentation: the page index, each page as JSON or Markdown, and the navigation tree, described by this OpenAPI document.`,\n      displayName: `${title} docs API`,\n      key: \"api:docs\",\n      queries: [\n        `fetch a ${title} docs page as JSON`,\n        `list the pages in the ${title} docs`,\n        `get the ${title} docs navigation tree`,\n      ],\n      type: \"application/vnd.oai.openapi+json\",\n      url: abs(OPENAPI_PATH),\n    });\n  }\n\n  for (const reference of resolveReferences(config)) {\n    // Blume-rendered pages mount under `basePath`; Scalar pages stay at the\n    // raw route (see `referenceRoutes`). The rendered reference is the\n    // resource this publisher owns — the spec itself is catalogued by URL in\n    // the RFC 9727 linkset.\n    const docRoute =\n      reference.renderer === \"blume\"\n        ? withBasePath(reference.basePath, reference.route)\n        : reference.route;\n    seeds.push({\n      description: `${reference.label}: rendered ${REFERENCE_KIND_LABEL[reference.kind]} reference in the ${title} documentation.`,\n      displayName: reference.label,\n      key: `reference:${reference.slug}`,\n      queries: [\n        `what operations does the ${reference.label} API expose`,\n        `how do I call the ${reference.label} API`,\n      ],\n      type: \"text/html\",\n      url: abs(docRoute),\n    });\n  }\n\n  if (config.ai.llmsTxt.enabled) {\n    seeds.push({\n      description: `llms.txt index of the ${title} documentation: every page with a one-line summary, plus the agent-facing resources on this site.`,\n      displayName: `${title} llms.txt`,\n      key: \"docs:llms-txt\",\n      queries: [`what is ${title}`, `overview of the ${title} documentation`],\n      type: \"text/plain\",\n      url: abs(\"/llms.txt\"),\n    });\n  }\n\n  return seeds;\n};\n\n/** The catalog document, or null when the site publishes none. */\nexport const buildAiCatalog = (\n  config: ResolvedConfig,\n  skills: readonly SkillArtifact[]\n): string | null => {\n  const site = config.deployment.site ?? null;\n  if (!(site && hasAiCatalog(config))) {\n    return null;\n  }\n  const deployBase = normalizeBasePath(config.deployment.base);\n  const abs = (path: string): string =>\n    absoluteUrl(site, withBasePath(deployBase, path));\n  const host = publisherHost(site);\n  const entries = entrySeeds(config, skills, abs).map((seed): CatalogEntry => {\n    const entry: CatalogEntry = {\n      displayName: seed.displayName,\n      identifier: `urn:air:${host}:${seed.key}`,\n      representativeQueries:\n        config.ai.catalog.queries[seed.key] ?? seed.queries,\n      type: seed.type,\n      url: seed.url,\n    };\n    if (seed.description) {\n      entry.description = seed.description;\n    }\n    if (seed.capabilities) {\n      entry.capabilities = seed.capabilities;\n    }\n    return entry;\n  });\n  const catalog = {\n    entries,\n    host: {\n      displayName: config.title,\n      documentationUrl: abs(\"/\"),\n      identifier: `did:web:${host}`,\n    },\n    specVersion: SPEC_VERSION,\n  };\n  return `${JSON.stringify(catalog, null, 2)}\\n`;\n};\n"
-  ],
-  "mappings": "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",
-  "debugId": "26AE621DEDAFCC8A64756E2164756E21",
-  "names": []
-}