wiki-formant 0.2.1 → 0.4.0

package/dist/well-known.d.ts

@@ -0,0 +1,83 @@
+export interface RegistryAuthRecord {
+    body: string;
+    contentType: string;
+    cacheControl: string;
+}
+/**
+ * The `v=MCPv1` record the official MCP registry fetches from
+ * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
+ * login http --domain=<host>` checks the key here against the private key
+ * signing the login, which is what grants publish rights over the reversed-
+ * domain namespace the server's name sits in.
+ *
+ * Returns null when no key is configured, so the caller can 404 rather than
+ * serve a malformed record — a missing key should read as "not configured",
+ * not as a verification failure nobody can explain.
+ *
+ * The key material belongs in an env var rather than the repo: the public half
+ * is harmless to serve but pointless to commit, and keeping it out gives the
+ * private half an obvious home too (a keychain, never git).
+ *
+ *   openssl genpkey -algorithm Ed25519 -out key.pem
+ *   openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
+ */
+export declare function registryAuthRecord(publicKey?: string, keyType?: string): RegistryAuthRecord | null;
+/** A day at the edge, a week stale-while-revalidate. A card changes rarely. */
+export declare const AGENT_CARD_CACHE_CONTROL = "public, s-maxage=86400, stale-while-revalidate=604800";
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    authentication?: unknown;
+}
+/** The shape a tool needs to carry to become a skill. */
+export interface SkillSource {
+    name: string;
+    description: string;
+    skill?: {
+        id: string;
+        tags: string[];
+        examples?: string[];
+    } | undefined;
+    auth?: unknown;
+}
+/**
+ * Skills derived from the MCP tool manifest, so a card can never advertise a
+ * capability the server does not have. `search_pages` becomes "Search Pages".
+ */
+export declare function skillsFromTools(tools: readonly SkillSource[]): AgentSkill[];
+export interface AgentCardLicense {
+    name: string;
+    url: string;
+    spdx?: string;
+    /** What the licence covers, e.g. `'content'`. */
+    scope?: string;
+}
+export interface AgentCardConfig {
+    name: string;
+    description: string;
+    /** Origin, no trailing slash. Every derived URL below hangs off it. */
+    url: string;
+    version: string;
+    skills: AgentSkill[];
+    license?: AgentCardLicense;
+    /** Defaults to `name`. */
+    organization?: string;
+    /** Defaults to `${url}/llms.txt`. */
+    documentationUrl?: string;
+    /** Defaults to `${url}/api/mcp`. Pass null for an origin with no MCP server. */
+    mcpEndpoint?: string | null;
+    /** Anything this origin advertises that the others do not. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
+ * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
+ * fallback in either direction, so a spec-current client probes only the new
+ * one and a client on an older SDK probes only the old one. Serving one path
+ * means half the callers conclude the origin has no agent at all.
+ */
+export declare function agentCard(config: AgentCardConfig): Record<string, unknown>;
+//# sourceMappingURL=well-known.d.ts.map

package/dist/well-known.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.d.ts","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAQlG;AAID,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,0DAA0D,CAAC;AAEhG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAW3E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB1E"}

package/dist/well-known.js

@@ -0,0 +1,84 @@
+// well-known.ts — the descriptors an agent finds before it knows anything else
+// about an origin: the A2A Agent Card and the MCP registry's domain proof.
+//
+// All three apps here serve both, and all three had written them out. The
+// registry-auth handler was identical bar a domain named in a comment; the
+// agent cards shared an envelope, a skills mapping and a cache header, and
+// differed only in the fields a card is *supposed* to differ in.
+//
+// Nothing here touches a framework: these return plain values, and the caller
+// wraps them in whatever its router wants. That keeps this package free of a
+// Next dependency and keeps each app's route a two-liner.
+/**
+ * The `v=MCPv1` record the official MCP registry fetches from
+ * `/.well-known/mcp-registry-auth` to prove domain ownership. `mcp-publisher
+ * login http --domain=<host>` checks the key here against the private key
+ * signing the login, which is what grants publish rights over the reversed-
+ * domain namespace the server's name sits in.
+ *
+ * Returns null when no key is configured, so the caller can 404 rather than
+ * serve a malformed record — a missing key should read as "not configured",
+ * not as a verification failure nobody can explain.
+ *
+ * The key material belongs in an env var rather than the repo: the public half
+ * is harmless to serve but pointless to commit, and keeping it out gives the
+ * private half an obvious home too (a keychain, never git).
+ *
+ *   openssl genpkey -algorithm Ed25519 -out key.pem
+ *   openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
+ */
+export function registryAuthRecord(publicKey, keyType) {
+    if (!publicKey)
+        return null;
+    return {
+        // ed25519 unless a P-384 key was used instead (the LibreSSL-friendly path).
+        body: `v=MCPv1; k=${keyType || 'ed25519'}; p=${publicKey}\n`,
+        contentType: 'text/plain; charset=utf-8',
+        cacheControl: 'no-store',
+    };
+}
+// ---- A2A Agent Card ---------------------------------------------------------
+/** A day at the edge, a week stale-while-revalidate. A card changes rarely. */
+export const AGENT_CARD_CACHE_CONTROL = 'public, s-maxage=86400, stale-while-revalidate=604800';
+/**
+ * Skills derived from the MCP tool manifest, so a card can never advertise a
+ * capability the server does not have. `search_pages` becomes "Search Pages".
+ */
+export function skillsFromTools(tools) {
+    return tools
+        .filter(t => t.skill)
+        .map(t => ({
+        id: t.skill.id,
+        name: t.name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+        description: t.description,
+        tags: t.skill.tags,
+        ...(t.skill.examples ? { examples: t.skill.examples } : {}),
+        ...(t.auth ? { authentication: t.auth } : {}),
+    }));
+}
+/**
+ * An A2A Agent Card. Serve the same object at both `/.well-known/agent.json`
+ * and `/.well-known/agent-card.json`: v0.3 renamed the path and defined no
+ * fallback in either direction, so a spec-current client probes only the new
+ * one and a client on an older SDK probes only the old one. Serving one path
+ * means half the callers conclude the origin has no agent at all.
+ */
+export function agentCard(config) {
+    const { name, description, url, version, skills, license, organization, documentationUrl, mcpEndpoint, extra } = config;
+    return {
+        name,
+        description,
+        url,
+        version,
+        capabilities: { streaming: false, pushNotifications: false },
+        skills,
+        provider: { organization: organization ?? name, url },
+        documentationUrl: documentationUrl ?? `${url}/llms.txt`,
+        ...(mcpEndpoint === null ? {} : { mcpEndpoint: mcpEndpoint ?? `${url}/api/mcp` }),
+        ...(license ? { license } : {}),
+        ...extra,
+        defaultInputModes: ['text/plain', 'application/json'],
+        defaultOutputModes: ['text/plain', 'application/json', 'text/markdown'],
+    };
+}
+//# sourceMappingURL=well-known.js.map

package/dist/well-known.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"well-known.js","sourceRoot":"","sources":["../src/well-known.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,0DAA0D;AAU1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAkB,EAAE,OAAgB;IACrE,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO;QACL,4EAA4E;QAC5E,IAAI,EAAE,cAAc,OAAO,IAAI,SAAS,OAAO,SAAS,IAAI;QAC5D,WAAW,EAAE,2BAA2B;QACxC,YAAY,EAAE,UAAU;KACzB,CAAC;AACJ,CAAC;AAED,gFAAgF;AAEhF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,uDAAuD,CAAC;AAmBhG;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAA6B;IAC3D,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACT,EAAE,EAAE,CAAC,CAAC,KAAM,CAAC,EAAE;QACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACtE,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,IAAI,EAAE,CAAC,CAAC,KAAM,CAAC,IAAI;QACnB,GAAG,CAAC,CAAC,CAAC,KAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC,CAAC;AACR,CAAC;AA4BD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAC/C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACxH,OAAO;QACL,IAAI;QACJ,WAAW;QACX,GAAG;QACH,OAAO;QACP,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE;QAC5D,MAAM;QACN,QAAQ,EAAE,EAAE,YAAY,EAAE,YAAY,IAAI,IAAI,EAAE,GAAG,EAAE;QACrD,gBAAgB,EAAE,gBAAgB,IAAI,GAAG,GAAG,WAAW;QACvD,GAAG,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,IAAI,GAAG,GAAG,UAAU,EAAE,CAAC;QACjF,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,KAAK;QACR,iBAAiB,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC;QACrD,kBAAkB,EAAE,CAAC,YAAY,EAAE,kBAAkB,EAAE,eAAe,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wiki-formant",
-  "version": "0.2.1",
-  "description": "The portable half of a wiki: derived taxonomy, a spec-correct MCP transport, markdown twins, block rendering, rate limiting, and the conditional-GET plumbing agent surfaces need. Zero runtime dependencies.",
+  "version": "0.4.0",
+  "description": "The portable half of a wiki: derived taxonomy, a spec-correct MCP transport, markdown twins, block rendering, link normalisation, freshness, rate limiting, and the conditional-GET plumbing agent surfaces need. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,9 @@
     "markdown",
     "agent",
     "rate-limit",
-    "plausible"
+    "plausible",
+    "links",
+    "freshness"
   ],
   "sideEffects": false,
   "exports": {
@@ -34,6 +36,10 @@
       "types": "./dist/mcp.d.ts",
       "import": "./dist/mcp.js"
     },
+    "./headings": {
+      "types": "./dist/headings.d.ts",
+      "import": "./dist/headings.js"
+    },
     "./markdown": {
       "types": "./dist/markdown.d.ts",
       "import": "./dist/markdown.js"
@@ -61,6 +67,34 @@
     "./blocks": {
       "types": "./dist/blocks.d.ts",
       "import": "./dist/blocks.js"
+    },
+    "./links": {
+      "types": "./dist/links.d.ts",
+      "import": "./dist/links.js"
+    },
+    "./maps": {
+      "types": "./dist/maps.d.ts",
+      "import": "./dist/maps.js"
+    },
+    "./freshness": {
+      "types": "./dist/freshness.d.ts",
+      "import": "./dist/freshness.js"
+    },
+    "./text": {
+      "types": "./dist/text.d.ts",
+      "import": "./dist/text.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "import": "./dist/validation.js"
+    },
+    "./well-known": {
+      "types": "./dist/well-known.d.ts",
+      "import": "./dist/well-known.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "import": "./dist/conformance.js"
     }
   },
   "files": [