@warpgogol/werkstatt-shared 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -1353,22 +1353,25 @@
     "ajv": "^8.20.0",
     "bs58": "^6.0.0",
     "expr-eval": "^2.0.2",
+    "gray-matter": "^4.0.3",
     "hls.js": "^1.6.16",
     "lenis": "^1.3.25",
     "plyr": "^3.8.4",
-    "gray-matter": "^4.0.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@syrokomskyi/axiom-study": "*"
+    "@syrokomskyi/axiom-study": "link:../../../pipelines/packages/axiom/axiom-study"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "^7.0.0",
     "@cloudflare/workers-types": "^5.20260801.1",
     "@types/node": "^24.0.0",
+    "@warpgogol/werkstatt": "1.4.0",
     "astro": "^7.2.0",
     "eslint": "^10.8.0",
     "fast-check": "^4.9.0",
+    "gsap": "^3.15.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "8.65.0",
     "vitest": "^4.1.10"

package/src/share/agent/ard-catalog.ts

@@ -0,0 +1,133 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+ARD (Agentic Resource Discovery) ai-catalog.json projection. Pure, dependency-free
+formatter that projects a site's Agent Surface Manifest into the ai-catalog data model
+for /.well-known/ai-catalog.json. No I/O — the kernel command loads the manifest and
+passes it here.
+</purpose>
+<non-goals>
+  <item>Do not read files — callers load and pass the manifest.</item>
+  <item>Do not duplicate logic from api-catalog or mcp-card — this is a separate spec.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial ARD ai-catalog.json projection for isitagentready.com ARD check.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { AgentSurfaceManifest } from "./manifest.ts";
+
+/** ARD ai-catalog entry — one per discoverable resource. */
+export interface ArdCatalogEntry {
+  identifier: string;
+  displayName: string;
+  type: string;
+  url: string;
+  representativeQueries: string[];
+}
+
+/** ARD ai-catalog host object. */
+export interface ArdCatalogHost {
+  displayName: string;
+  identifier: string;
+}
+
+/** ARD ai-catalog top-level document. */
+export interface ArdCatalog {
+  specVersion: string;
+  host: ArdCatalogHost;
+  entries: ArdCatalogEntry[];
+}
+
+/**
+ * Pure: project Agent Surface Manifest into ARD ai-catalog.json.
+ * Deterministic — entries are sorted by identifier for byte-identical output (DNA-58).
+ */
+export function buildArdCatalog(
+  manifest: AgentSurfaceManifest,
+  hostDisplayName?: string,
+): ArdCatalog {
+  const domain = manifest.baseUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const displayName = hostDisplayName ?? manifest.site;
+
+  const entries: ArdCatalogEntry[] = [];
+
+  // MCP server card entry
+  if (manifest.interfaces.mcp) {
+    entries.push({
+      identifier: `urn:air:${domain}:server:mcp`,
+      displayName: "MCP Server",
+      type: "application/mcp-server-card+json",
+      url: "/.well-known/mcp/server-card.json",
+      representativeQueries: [
+        "What tools are available on this MCP server",
+        "List MCP server capabilities and endpoints",
+      ],
+    });
+  }
+
+  // A2A Agent Card entry
+  entries.push({
+    identifier: `urn:air:${domain}:agent:a2a`,
+    displayName: "A2A Agent Card",
+    type: "application/a2a+json",
+    url: "/.well-known/agent-card.json",
+    representativeQueries: [
+      "What agent capabilities does this site offer",
+      "Get the A2A agent card for this service",
+    ],
+  });
+
+  // OpenAPI entry
+  if (manifest.interfaces.openapi) {
+    entries.push({
+      identifier: `urn:air:${domain}:api:openapi`,
+      displayName: "OpenAPI Specification",
+      type: "application/vnd.oai.openapi+json",
+      url: manifest.interfaces.openapi,
+      representativeQueries: [
+        "What API endpoints are available on this site",
+        "Get the OpenAPI specification for agent integration",
+      ],
+    });
+  }
+
+  // Agent Surface Manifest entry
+  entries.push({
+    identifier: `urn:air:${domain}:manifest:agent-surface`,
+    displayName: "Agent Surface Manifest",
+    type: "application/json",
+    url: "/.well-known/agent.json",
+    representativeQueries: [
+      "What agent discovery endpoints does this site provide",
+      "Get the agent surface manifest for this site",
+    ],
+  });
+
+  // Knowledge domain entries
+  for (const ref of manifest.knowledge) {
+    entries.push({
+      identifier: `urn:air:${domain}:knowledge:${ref.domain}`,
+      displayName: `${ref.domain.charAt(0).toUpperCase() + ref.domain.slice(1)} Knowledge`,
+      type: "application/json",
+      url: ref.url,
+      representativeQueries: [
+        `What ${ref.domain} information is available on this site`,
+        `Get structured ${ref.domain} data for agent consumption`,
+      ],
+    });
+  }
+
+  // Sort entries by identifier for deterministic output
+  entries.sort((a, b) => a.identifier.localeCompare(b.identifier));
+
+  return {
+    specVersion: "1.0",
+    host: {
+      displayName,
+      identifier: `did:web:${domain}`,
+    },
+    entries,
+  };
+}

package/src/share/agent/index.ts

@@ -27,3 +27,4 @@ export * from "./fleet-catalog.ts";
 export * from "./api-catalog.ts";
 export * from "./mcp-card.ts";
 export * from "./dns-aid.ts";
+export * from "./ard-catalog.ts";

package/src/share/content-reference.ts

@@ -205,6 +205,7 @@ export function resolveReferencesInString(
   lang: string,
   defaultLang: string,
   sourceRef?: SourceRef,
+  onUnresolved?: (ref: string, error: string) => void,
 ): string {
   // RFC-0731: Check for this. as a pure reference (entire text is this.field.path)
   if (
@@ -219,6 +220,7 @@ export function resolveReferencesInString(
       if (result.resolved) {
         return formatValue(result.value);
       }
+      onUnresolved?.(text.trim(), result.error ?? "unresolved this. reference");
     }
   }
   THIS_SCAN_PATTERN.lastIndex = 0;
@@ -228,6 +230,7 @@ export function resolveReferencesInString(
     if (result.resolved) {
       return formatValue(result.value);
     }
+    onUnresolved?.(text, result.error ?? "unresolved reference");
     return text;
   }
 
@@ -310,9 +313,12 @@ export async function resolveReferencesDeep(
   lang: string,
   defaultLang: string,
   sourceRef?: SourceRef,
+  onUnresolved?: (ref: string, error: string) => void,
 ): Promise<unknown> {
   return substituteRefsDeep(data, (value) =>
-    Promise.resolve(resolveReferencesInString(index, value, lang, defaultLang, sourceRef)),
+    Promise.resolve(
+      resolveReferencesInString(index, value, lang, defaultLang, sourceRef, onUnresolved),
+    ),
   );
 }
 

package/src/share/tests/ard-catalog.test.ts

@@ -0,0 +1,129 @@
+/*
+<MODULE_CONTRACT>
+<purpose>ARD ai-catalog.json projection tests: determinism, shape, entry coverage.</purpose>
+<keywords>ARD, ai-catalog, agent surface, test</keywords>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial ARD ai-catalog.json projection tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { buildArdCatalog } from "../agent/ard-catalog.ts";
+import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+
+test("buildArdCatalog: produces specVersion, host, and entries array", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const catalog = buildArdCatalog(manifest, "My Site");
+  expect(catalog.specVersion).toBe("1.0");
+  expect(catalog.host.displayName).toBe("My Site");
+  expect(catalog.host.identifier).toBe("did:web:s.example");
+  expect(catalog.entries.length).toBeGreaterThan(0);
+});
+
+test("buildArdCatalog: each entry has identifier, displayName, type, url, representativeQueries", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
+    knowledge: [
+      { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
+    ],
+  });
+  const catalog = buildArdCatalog(manifest);
+  for (const entry of catalog.entries) {
+    expect(entry.identifier).toMatch(/^urn:air:s\.example:/);
+    expect(entry.displayName).toBeTruthy();
+    expect(entry.type).toBeTruthy();
+    expect(entry.url).toBeTruthy();
+    expect(entry.representativeQueries.length).toBeGreaterThanOrEqual(2);
+    expect(entry.representativeQueries.length).toBeLessThanOrEqual(5);
+  }
+});
+
+test("buildArdCatalog: MCP interface adds MCP server entry", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
+  });
+  const catalog = buildArdCatalog(manifest);
+  const mcpEntry = catalog.entries.find((e) => e.identifier.includes(":server:mcp"));
+  expect(mcpEntry).toBeDefined();
+  expect(mcpEntry?.type).toBe("application/mcp-server-card+json");
+  expect(mcpEntry?.url).toBe("/.well-known/mcp/server-card.json");
+});
+
+test("buildArdCatalog: knowledge refs produce entries", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    knowledge: [
+      { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
+      { domain: "team", url: "/api/agent/v1/team.json", schema: "gogol.agent.knowledge/team@1" },
+    ],
+  });
+  const catalog = buildArdCatalog(manifest);
+  const knowledgeEntries = catalog.entries.filter((e) => e.identifier.includes(":knowledge:"));
+  expect(knowledgeEntries).toHaveLength(2);
+  expect(knowledgeEntries[0].url).toBe("/api/agent/v1/offer.json");
+});
+
+test("buildArdCatalog: entries are sorted by identifier", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    knowledge: [
+      { domain: "zeta", url: "/api/agent/v1/zeta.json", schema: "gogol.agent.knowledge/zeta@1" },
+      { domain: "alpha", url: "/api/agent/v1/alpha.json", schema: "gogol.agent.knowledge/alpha@1" },
+    ],
+  });
+  const catalog = buildArdCatalog(manifest);
+  const identifiers = catalog.entries.map((e) => e.identifier);
+  const sorted = [...identifiers].sort();
+  expect(identifiers).toEqual(sorted);
+});
+
+test("buildArdCatalog: determinism — same input produces identical output", () => {
+  const input = {
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    knowledge: [
+      { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
+    ],
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
+  };
+  const a = buildArdCatalog(buildAgentSurfaceManifest(input), "My Site");
+  const b = buildArdCatalog(buildAgentSurfaceManifest(input), "My Site");
+  expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+});
+
+test("buildArdCatalog: host identifier uses did:web format with domain", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "warpgogol-com",
+    baseUrl: "https://warpgogol.com",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const catalog = buildArdCatalog(manifest, "Warpgogol");
+  expect(catalog.host.identifier).toBe("did:web:warpgogol.com");
+  expect(catalog.host.displayName).toBe("Warpgogol");
+});
+
+test("buildArdCatalog: default hostDisplayName falls back to site name", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "my-site",
+    baseUrl: "https://example.com",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const catalog = buildArdCatalog(manifest);
+  expect(catalog.host.displayName).toBe("my-site");
+});

package/src/share/types/axiom-study.d.ts

@@ -0,0 +1,14 @@
+declare module "@syrokomskyi/axiom-study" {
+  export interface Finding {
+    findingId: string;
+    semanticFingerprint: string;
+    methodologyId: string;
+    ruleId: string;
+    affectedSubjectId: string;
+    title: string;
+    severity: "info" | "low" | "medium" | "high" | "critical";
+    evidence: Array<{ evidenceId: string; digest: string }>;
+    uncertainty: unknown[];
+    extension: Record<string, unknown>;
+  }
+}

package/tsconfig.json

@@ -2,19 +2,22 @@
   "compilerOptions": {
     "target": "ES2022",
     "module": "preserve",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
     "noEmit": true,
+    "allowImportingTsExtensions": true,
     "declaration": true,
     "rewriteRelativeImportExtensions": true,
-    "types": [
-      "node"
-    ],
+    "types": ["node"],
     "rootDir": ".",
-    "outDir": "dist",
-    "allowImportingTsExtensions": true
+    "outDir": "dist"
   },
-  "include": [
-    "src/**/*.ts"
-  ],
+  "include": ["src/**/*.ts"],
   "exclude": [
     "src/**/*.template.*",
     "src/**/*.test.ts",