ai-catalog 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,605 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname } from "path";
+
+// src/types.ts
+var SPEC_VERSION = "1.0";
+var WELL_KNOWN_PATH = "/.well-known/ai-catalog.json";
+var CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+var LINK_REL = "ai-catalog";
+var DEFAULT_MAX_DEPTH = 4;
+var KnownType = {
+  /** A nested AI Catalog. */
+  AiCatalog: "application/ai-catalog+json",
+  /** Reserved generic Agent Card format. */
+  AgentCard: "application/agent-card+json",
+  /** An A2A Agent Card. */
+  A2aAgentCard: "application/a2a-agent-card+json",
+  /** An MCP Server Card. */
+  McpServerCard: "application/mcp-server-card+json",
+  /** Agent Skill metadata JSON. */
+  AgentSkillsJson: "application/agent-skills+json",
+  /** Agent Skill in Markdown. */
+  AgentSkillsMd: "application/agent-skills+md",
+  /** Agent Skill bundle (ZIP). */
+  AgentSkillsZip: "application/agent-skills+zip",
+  /** Agent Skill bundle (gzipped tarball). */
+  AgentSkillsGzip: "application/agent-skills+gzip"
+};
+
+// src/urn.ts
+function parseAirUrn(identifier) {
+  if (typeof identifier !== "string") return null;
+  const parts = identifier.split(":");
+  if (parts.length < 5) return null;
+  if (parts[0].toLowerCase() !== "urn" || parts[1].toLowerCase() !== "air") {
+    return null;
+  }
+  const publisher = parts[2];
+  const name = parts[parts.length - 1];
+  const namespace = parts.slice(3, parts.length - 1).join(":");
+  if (!publisher || !namespace || !name) return null;
+  return { publisher, namespace, name };
+}
+function isAirUrn(identifier) {
+  return parseAirUrn(identifier) !== null;
+}
+function identifierTail(identifier) {
+  const m = identifier.match(/[^:/]+$/);
+  return m ? m[0] : identifier;
+}
+
+// src/validate.ts
+var KNOWN_TYPES = new Set(Object.values(KnownType));
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isRfc3339(s) {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(s)) {
+    return false;
+  }
+  return !Number.isNaN(Date.parse(s));
+}
+function validateCatalog(doc, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const err = (path, message) => errors.push({ path, message, severity: "error" });
+  const warn = (path, message) => warnings.push({ path, message, severity: "warning" });
+  if (!isPlainObject(doc)) {
+    err("", "catalog must be a JSON object");
+    return { valid: false, errors, warnings };
+  }
+  if (typeof doc.specVersion !== "string") {
+    err("/specVersion", "required string member is missing");
+  } else if (!/^\d+\.\d+$/.test(doc.specVersion)) {
+    warn("/specVersion", `should be "Major.Minor" (got "${doc.specVersion}")`);
+  }
+  if (doc.host !== void 0) validateHost(doc.host, "/host", err, warn);
+  if (doc.metadata !== void 0 && !isPlainObject(doc.metadata)) {
+    err("/metadata", "metadata must be an object");
+  }
+  if (!Array.isArray(doc.entries)) {
+    err("/entries", "required array member is missing");
+  } else {
+    const seen = /* @__PURE__ */ new Map();
+    doc.entries.forEach((entry, i) => {
+      validateEntry(entry, `/entries/${i}`, err, warn);
+      if (isPlainObject(entry) && typeof entry.identifier === "string") {
+        const versions = seen.get(entry.identifier) ?? /* @__PURE__ */ new Set();
+        const v = typeof entry.version === "string" ? entry.version : void 0;
+        if (versions.has(v)) {
+          err(
+            `/entries/${i}/identifier`,
+            v === void 0 ? `duplicate identifier "${entry.identifier}" (identifier alone must be unique when no version is set)` : `duplicate identifier+version "${entry.identifier}"@"${v}"`
+          );
+        }
+        versions.add(v);
+        seen.set(entry.identifier, versions);
+      }
+    });
+  }
+  const allErrors = opts.strict ? [...errors, ...warnings] : errors;
+  return { valid: allErrors.length === 0, errors, warnings };
+}
+function validateHost(host, path, err, warn) {
+  if (!isPlainObject(host)) {
+    err(path, "host must be an object");
+    return;
+  }
+  if (typeof host.displayName !== "string" || host.displayName.length === 0) {
+    err(`${path}/displayName`, "host.displayName is required and must be a non-empty string");
+  }
+  for (const k of ["identifier", "documentationUrl", "logoUrl"]) {
+    if (host[k] !== void 0 && typeof host[k] !== "string") {
+      err(`${path}/${k}`, `${k} must be a string`);
+    }
+  }
+}
+function validateEntry(entry, path, err, warn) {
+  if (!isPlainObject(entry)) {
+    err(path, "entry must be an object");
+    return;
+  }
+  if (typeof entry.identifier !== "string" || entry.identifier.length === 0) {
+    err(`${path}/identifier`, "required string member is missing");
+  } else if (!isAirUrn(entry.identifier)) {
+    warn(
+      `${path}/identifier`,
+      `should use urn:air:{publisher}:{namespace}:{name} for open/federated use (got "${entry.identifier}")`
+    );
+  }
+  if (typeof entry.type !== "string" || entry.type.length === 0) {
+    if (typeof entry.mediaType === "string") {
+      err(`${path}/type`, "required `type` is missing \u2014 `mediaType` was renamed to `type` (ADR-0014)");
+    } else {
+      err(`${path}/type`, "required string member is missing");
+    }
+  } else if (!KNOWN_TYPES.has(entry.type)) {
+    warn(`${path}/type`, `"${entry.type}" is not a recognized known type`);
+  }
+  const hasUrl = entry.url !== void 0;
+  const hasData = entry.data !== void 0;
+  if (hasUrl && hasData) {
+    err(path, "entry must contain exactly one of `url` or `data`, not both");
+  } else if (!hasUrl && !hasData) {
+    err(path, "entry must contain exactly one of `url` or `data`");
+  }
+  if (hasUrl && typeof entry.url !== "string") {
+    err(`${path}/url`, "url must be a string");
+  }
+  if (entry.displayName !== void 0 && typeof entry.displayName !== "string") {
+    err(`${path}/displayName`, "displayName must be a string");
+  }
+  if (entry.description !== void 0 && typeof entry.description !== "string") {
+    err(`${path}/description`, "description must be a string");
+  }
+  if (entry.version !== void 0 && typeof entry.version !== "string") {
+    err(`${path}/version`, "version must be a string");
+  }
+  if (entry.tags !== void 0) {
+    if (!Array.isArray(entry.tags) || entry.tags.some((t) => typeof t !== "string")) {
+      err(`${path}/tags`, "tags must be an array of strings");
+    }
+  }
+  if (entry.updatedAt !== void 0) {
+    if (typeof entry.updatedAt !== "string") {
+      err(`${path}/updatedAt`, "updatedAt must be a string");
+    } else if (!isRfc3339(entry.updatedAt)) {
+      warn(`${path}/updatedAt`, "updatedAt should be an RFC 3339 timestamp");
+    }
+  }
+  if (entry.publisher !== void 0) {
+    const p = entry.publisher;
+    if (!isPlainObject(p)) {
+      err(`${path}/publisher`, "publisher must be an object");
+    } else {
+      if (typeof p.identifier !== "string" || p.identifier.length === 0) {
+        err(`${path}/publisher/identifier`, "publisher.identifier is required");
+      }
+      if (typeof p.displayName !== "string" || p.displayName.length === 0) {
+        err(`${path}/publisher/displayName`, "publisher.displayName is required");
+      }
+    }
+  }
+  if (entry.trustManifest !== void 0 && typeof entry.identifier === "string") {
+    const tm = entry.trustManifest;
+    const air = parseAirUrn(entry.identifier);
+    const idDomain = isPlainObject(tm) && isPlainObject(tm.identity) && typeof tm.identity.identifier === "string" ? tm.identity.identifier : void 0;
+    if (air && idDomain) {
+      const domainSegment = stripIdentityScheme(idDomain);
+      if (domainSegment && !domainMatches(air.publisher, domainSegment)) {
+        err(
+          `${path}/trustManifest/identity/identifier`,
+          `trust identity domain "${domainSegment}" must align with the entry publisher "${air.publisher}"`
+        );
+      }
+    }
+  }
+}
+function stripIdentityScheme(id) {
+  if (id.startsWith("did:web:")) return id.slice("did:web:".length).split(":")[0];
+  if (id.startsWith("dns:")) return id.slice("dns:".length);
+  if (id.startsWith("https://")) {
+    try {
+      return new URL(id).hostname;
+    } catch {
+      return void 0;
+    }
+  }
+  if (/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(id)) return id;
+  return void 0;
+}
+function domainMatches(publisher, domain) {
+  const p = publisher.toLowerCase().replace(/\.$/, "");
+  const d = domain.toLowerCase().replace(/\.$/, "");
+  return p === d || d.endsWith(`.${p}`) || p.endsWith(`.${d}`);
+}
+function assertValidCatalog(doc, opts) {
+  const r = validateCatalog(doc, opts);
+  const fatal = opts?.strict ? [...r.errors, ...r.warnings] : r.errors;
+  if (fatal.length > 0) {
+    const lines = fatal.map((i) => `  ${i.path || "/"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid ai-catalog.json:
+${lines}`);
+  }
+}
+
+// src/builder.ts
+var CatalogBuilder = class {
+  catalog;
+  constructor(host, specVersion = SPEC_VERSION) {
+    this.catalog = { specVersion, entries: [] };
+    if (host) this.catalog.host = host;
+  }
+  /** Set or replace the Host Info object. */
+  setHost(host) {
+    this.catalog.host = host;
+    return this;
+  }
+  /** Set a catalog-level metadata key. */
+  setMetadata(key, value) {
+    this.catalog.metadata ??= {};
+    this.catalog.metadata[key] = value;
+    return this;
+  }
+  /** Append a catalog entry. */
+  addEntry(entry) {
+    this.catalog.entries.push(entry);
+    return this;
+  }
+  /** Append several catalog entries. */
+  addEntries(entries) {
+    this.catalog.entries.push(...entries);
+    return this;
+  }
+  /**
+   * Add a nested-catalog entry (`type: application/ai-catalog+json`) that points
+   * at another catalog by URL.
+   */
+  addNestedCatalog(identifier, url, extra) {
+    return this.addEntry({
+      identifier,
+      type: "application/ai-catalog+json",
+      url,
+      ...extra
+    });
+  }
+  /** The built catalog object (a fresh shallow copy each call). */
+  build() {
+    return { ...this.catalog, entries: [...this.catalog.entries] };
+  }
+  /** Validate the built catalog, throwing on any error. Returns the catalog. */
+  validateOrThrow(opts) {
+    const built = this.build();
+    assertValidCatalog(built, opts);
+    return built;
+  }
+  /** Serialize to a JSON string. */
+  toJSON(indent = 2) {
+    return JSON.stringify(this.build(), null, indent);
+  }
+};
+
+// src/resolve.ts
+function getFetch(opts) {
+  const f = opts?.fetch ?? globalThis.fetch;
+  if (!f) {
+    throw new Error("No fetch available. Pass options.fetch or run on Node 18+.");
+  }
+  return f;
+}
+async function withTimeout(fetchFn, url, init, timeoutMs) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fetchFn(url, { ...init, signal: ctrl.signal });
+  } finally {
+    clearTimeout(t);
+  }
+}
+function parseLinkHeader(header) {
+  if (!header) return null;
+  for (const part of header.split(",")) {
+    const m = part.match(/<([^>]+)>\s*;\s*(.+)/);
+    if (!m) continue;
+    const target = m[1].trim();
+    const params = m[2];
+    const rel = params.match(/rel\s*=\s*"?([^";]+)"?/i)?.[1]?.trim();
+    if (rel && rel.split(/\s+/).includes(LINK_REL)) return target;
+  }
+  return null;
+}
+function parseHtmlLink(html) {
+  const linkTags = html.match(/<link\b[^>]*>/gi) ?? [];
+  for (const tag of linkTags) {
+    const rel = tag.match(/\brel\s*=\s*["']?([^"'>]+)["']?/i)?.[1];
+    if (!rel || !rel.split(/\s+/).includes(LINK_REL)) continue;
+    const href = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1];
+    if (href) return href;
+  }
+  return null;
+}
+async function discover(siteUrl, opts = {}) {
+  const fetchFn = getFetch(opts);
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const base = new URL(siteUrl);
+  const resp = await withTimeout(fetchFn, base.toString(), { redirect: "follow" }, timeoutMs);
+  const headerTarget = parseLinkHeader(resp.headers.get("link"));
+  if (headerTarget) {
+    const url = new URL(headerTarget, resp.url || base).toString();
+    return { url, via: "link-header", catalog: await fetchCatalog(url, fetchFn, timeoutMs) };
+  }
+  const contentType = resp.headers.get("content-type") ?? "";
+  if (contentType.includes("html")) {
+    const html = await resp.text();
+    const htmlTarget = parseHtmlLink(html);
+    if (htmlTarget) {
+      const url = new URL(htmlTarget, resp.url || base).toString();
+      return { url, via: "html-link", catalog: await fetchCatalog(url, fetchFn, timeoutMs) };
+    }
+  }
+  if (!opts.noWellKnownFallback) {
+    const url = new URL(WELL_KNOWN_PATH, base.origin).toString();
+    return { url, via: "well-known", catalog: await fetchCatalog(url, fetchFn, timeoutMs) };
+  }
+  throw new Error(`No ai-catalog discovered at ${siteUrl} (no Link header, no HTML <link>).`);
+}
+async function fetchCatalog(url, fetchFn = getFetch(), timeoutMs = 1e4) {
+  const resp = await withTimeout(
+    fetchFn,
+    url,
+    { redirect: "follow", headers: { accept: `${CATALOG_MEDIA_TYPE}, application/json` } },
+    timeoutMs
+  );
+  if (!resp.ok) {
+    throw new Error(`Failed to fetch catalog ${url}: HTTP ${resp.status}`);
+  }
+  let doc;
+  try {
+    doc = await resp.json();
+  } catch {
+    throw new Error(`Catalog at ${url} is not valid JSON`);
+  }
+  const result = validateCatalog(doc);
+  if (!result.valid) {
+    const first = result.errors[0];
+    throw new Error(
+      `Catalog at ${url} is not a valid ai-catalog.json: ${first.path || "/"} ${first.message}`
+    );
+  }
+  return doc;
+}
+async function resolveCatalog(root, opts = {}) {
+  const fetchFn = getFetch(opts);
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+  let rootCatalog;
+  let rootUrl;
+  if (typeof root === "string") {
+    rootUrl = root;
+    rootCatalog = await fetchCatalog(root, fetchFn, timeoutMs);
+  } else {
+    rootCatalog = root;
+    rootUrl = opts.rootUrl ?? "(in-memory)";
+  }
+  const out = [];
+  const visited = /* @__PURE__ */ new Set([rootUrl]);
+  const walk = async (catalog, sourceUrl, depth) => {
+    for (const entry of catalog.entries) {
+      const isNested = entry.type === CATALOG_MEDIA_TYPE && typeof entry.url === "string";
+      if (isNested && depth < maxDepth) {
+        const childUrl = new URL(entry.url, sourceUrl === "(in-memory)" ? void 0 : sourceUrl).toString();
+        if (visited.has(childUrl)) continue;
+        visited.add(childUrl);
+        try {
+          const child = await fetchCatalog(childUrl, fetchFn, timeoutMs);
+          await walk(child, childUrl, depth + 1);
+        } catch {
+          out.push({ ...entry, sourceCatalogUrl: sourceUrl, depth });
+        }
+      } else {
+        out.push({ ...entry, sourceCatalogUrl: sourceUrl, depth });
+      }
+    }
+  };
+  await walk(rootCatalog, rootUrl, 0);
+  return out;
+}
+function resolveDisplayName(entry, referencedName) {
+  if (entry.displayName) return entry.displayName;
+  if (referencedName) return referencedName;
+  return identifierTail(entry.identifier);
+}
+
+// src/cli/index.ts
+var VERSION = "0.1.0";
+var c = {
+  red: (s) => `\x1B[31m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  bold: (s) => `\x1B[1m${s}\x1B[0m`
+};
+var USAGE = `ai-catalog ${VERSION} \u2014 tooling for the Agentic Resource Discovery (ARD) spec
+
+Usage:
+  ai-catalog init [path]            Scaffold a .well-known/ai-catalog.json
+  ai-catalog validate <file>        Validate a catalog file against the spec
+  ai-catalog discover <site-url>    Discover the catalog a website advertises
+  ai-catalog resolve <url|site>     Fetch a catalog and flatten nested catalogs
+  ai-catalog --help                 Show this help
+
+Flags:
+  --strict        (validate) treat RECOMMENDED warnings as errors
+  --json          machine-readable JSON output
+  --names         (resolve) print resolved display names
+`;
+function arg(argv, flag) {
+  return argv.includes(flag);
+}
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (cmd === "--version" || cmd === "-v") {
+    process.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  switch (cmd) {
+    case "init":
+      return cmdInit(rest);
+    case "validate":
+      return cmdValidate(rest);
+    case "discover":
+      return cmdDiscover(rest);
+    case "resolve":
+      return cmdResolve(rest);
+    default:
+      process.stderr.write(c.red(`Unknown command: ${cmd}
+
+`));
+      process.stdout.write(USAGE);
+      return 2;
+  }
+}
+async function cmdInit(rest) {
+  const path = rest.find((a) => !a.startsWith("-")) ?? `.${WELL_KNOWN_PATH}`;
+  if (existsSync(path)) {
+    process.stderr.write(c.red(`Refusing to overwrite existing file: ${path}
+`));
+    return 1;
+  }
+  const sample = new CatalogBuilder({
+    displayName: "Your Organization",
+    identifier: "did:web:example.com",
+    documentationUrl: "https://example.com/docs"
+  }).addEntry({
+    identifier: "urn:air:example.com:mcp:weather",
+    type: "application/mcp-server-card+json",
+    description: "Weather lookup MCP server.",
+    tags: ["weather", "mcp"],
+    url: "https://example.com/.well-known/mcp/weather.json"
+  }).toJSON();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, sample + "\n");
+  process.stdout.write(
+    `${c.green("created")} ${path}
+` + c.dim(`Serve it at ${WELL_KNOWN_PATH} with content-type application/ai-catalog+json.
+`)
+  );
+  return 0;
+}
+async function cmdValidate(rest) {
+  const file = rest.find((a) => !a.startsWith("-"));
+  if (!file) {
+    process.stderr.write(c.red("validate: missing <file>\n"));
+    return 2;
+  }
+  const strict = arg(rest, "--strict");
+  const json = arg(rest, "--json");
+  let doc;
+  try {
+    doc = JSON.parse(await readFile(file, "utf8"));
+  } catch (e) {
+    process.stderr.write(c.red(`Cannot read/parse ${file}: ${e.message}
+`));
+    return 1;
+  }
+  const result = validateCatalog(doc, { strict });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return result.valid ? 0 : 1;
+  }
+  for (const e of result.errors) {
+    process.stdout.write(`${c.red("error")} ${c.bold(e.path || "/")} ${e.message}
+`);
+  }
+  for (const w of result.warnings) {
+    process.stdout.write(`${c.yellow("warn")}  ${c.bold(w.path || "/")} ${w.message}
+`);
+  }
+  if (result.valid && result.warnings.length === 0) {
+    process.stdout.write(`${c.green("valid")} ${file} conforms to ARD spec v${SPEC_VERSION}
+`);
+  } else if (result.valid) {
+    process.stdout.write(`${c.green("valid")} ${file} (${result.warnings.length} warning(s))
+`);
+  } else {
+    process.stdout.write(
+      `${c.red("invalid")} ${result.errors.length} error(s), ${result.warnings.length} warning(s)
+`
+    );
+  }
+  return result.valid ? 0 : 1;
+}
+async function cmdDiscover(rest) {
+  const site = rest.find((a) => !a.startsWith("-"));
+  if (!site) {
+    process.stderr.write(c.red("discover: missing <site-url>\n"));
+    return 2;
+  }
+  const json = arg(rest, "--json");
+  try {
+    const r = await discover(site);
+    if (json) {
+      process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+      return 0;
+    }
+    process.stdout.write(
+      `${c.green("found")} ${r.url}
+${c.dim(`via ${r.via}, ${r.catalog.entries.length} entr(ies)`)}
+`
+    );
+    for (const e of r.catalog.entries) {
+      process.stdout.write(`  ${c.bold(resolveDisplayName(e))} ${c.dim(e.type)}
+`);
+    }
+    return 0;
+  } catch (e) {
+    process.stderr.write(c.red(`discover failed: ${e.message}
+`));
+    return 1;
+  }
+}
+async function cmdResolve(rest) {
+  const target = rest.find((a) => !a.startsWith("-"));
+  if (!target) {
+    process.stderr.write(c.red("resolve: missing <url|site>\n"));
+    return 2;
+  }
+  const json = arg(rest, "--json");
+  const names = arg(rest, "--names");
+  try {
+    const u = new URL(target);
+    const isBareSite = u.pathname === "/" || u.pathname === "";
+    const rootUrl = isBareSite ? (await discover(target)).url : target;
+    const entries = await resolveCatalog(rootUrl);
+    if (json) {
+      process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
+      return 0;
+    }
+    process.stdout.write(`${c.green("resolved")} ${entries.length} entr(ies) from ${rootUrl}
+`);
+    for (const e of entries) {
+      const label = names ? resolveDisplayName(e) : e.identifier;
+      process.stdout.write(`  ${c.dim(`d${e.depth}`)} ${c.bold(label)} ${c.dim(e.type)}
+`);
+    }
+    return 0;
+  } catch (e) {
+    process.stderr.write(c.red(`resolve failed: ${e.message}
+`));
+    return 1;
+  }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code)).catch((e) => {
+  process.stderr.write(c.red(`fatal: ${e?.message ?? e}
+`));
+  process.exit(1);
+});