@warpgogol/werkstatt-shared 0.13.0 → 0.14.1

package/src/share/semantic/tests/update-stamp.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import {
+  isValidStampDate,
+  resolveAuthoredStamp,
+  resolveCklStamp,
+  resolvePageUpdateStamp,
+} from "../update-stamp.ts";
+
+describe("isValidStampDate", () => {
+  it("accepts YYYY-MM-DD", () => {
+    expect(isValidStampDate("2024-01-15")).toBe(true);
+  });
+
+  it("rejects non-string", () => {
+    expect(isValidStampDate(20240115)).toBe(false);
+  });
+
+  it("rejects wrong format", () => {
+    expect(isValidStampDate("2024/01/15")).toBe(false);
+    expect(isValidStampDate("January 15, 2024")).toBe(false);
+  });
+});
+
+describe("resolveAuthoredStamp", () => {
+  it("uses output.sitemap.lastmod first", () => {
+    const result = resolveAuthoredStamp({
+      output: { sitemap: { lastmod: "2024-06-01" } },
+    });
+    expect(result?.date).toBe("2024-06-01");
+    expect(result?.source).toBe("authored-system-output");
+  });
+
+  it("uses article.updatedAt when no sitemap lastmod", () => {
+    const result = resolveAuthoredStamp({
+      article: { updatedAt: "2024-05-01" },
+    });
+    expect(result?.date).toBe("2024-05-01");
+    expect(result?.source).toBe("authored-page-frontmatter");
+  });
+
+  it("uses article.publishedAt when no updatedAt", () => {
+    const result = resolveAuthoredStamp({
+      article: { publishedAt: "2024-01-01" },
+    });
+    expect(result?.date).toBe("2024-01-01");
+  });
+
+  it("returns undefined when no valid dates", () => {
+    expect(resolveAuthoredStamp({})).toBeUndefined();
+  });
+
+  it("ignores invalid date formats", () => {
+    expect(resolveAuthoredStamp({ article: { updatedAt: "not-a-date" } })).toBeUndefined();
+  });
+});
+
+describe("resolveCklStamp", () => {
+  it("returns latest valid date", () => {
+    const result = resolveCklStamp(["2024-01-01", "2024-06-15", "2024-03-01"], ["ledger"]);
+    expect(result?.date).toBe("2024-06-15");
+    expect(result?.source).toBe("ckl-claim-ledger");
+  });
+
+  it("returns undefined when no valid dates", () => {
+    expect(resolveCklStamp(["invalid"], ["ledger"])).toBeUndefined();
+  });
+});
+
+describe("resolvePageUpdateStamp", () => {
+  it("prefers authored stamp over CKL", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: { output: { sitemap: { lastmod: "2024-06-01" } } },
+      cklLedgerDates: ["2024-01-01"],
+    });
+    expect(result.stamp?.date).toBe("2024-06-01");
+    expect(result.stamp?.source).toBe("authored-system-output");
+  });
+
+  it("falls back to CKL when no authored stamp", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: {},
+      cklLedgerDates: ["2024-03-01"],
+      cklInputs: ["ledger"],
+    });
+    expect(result.stamp?.date).toBe("2024-03-01");
+    expect(result.stamp?.source).toBe("ckl-claim-ledger");
+  });
+
+  it("returns missingReason when no sources available", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: {},
+    });
+    expect(result.stamp).toBeUndefined();
+    expect(result.missingReason).toBe("no-content-source");
+  });
+});

package/src/share/tests/manifest.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0286: initial builder tests.</item>
+  <item>RFC-0954: add search interface tests.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -16,6 +17,7 @@ import {
   AGENT_SURFACE_VERSION,
   buildAgentSurfaceManifest,
   computeAgentManifestContentHash,
+  computeSignedContentHash,
   canonicalJson,
 } from "../agent/manifest.ts";
 
@@ -38,6 +40,7 @@ test("buildAgentSurfaceManifest: safe default — empty knowledge/actions, null
   expect(m.interfaces.openapi).toBe(null);
   expect(m.interfaces.mcp).toBe(null);
   expect(m.interfaces.twins).toBe(null);
+  expect(m.interfaces.search).toBe(null);
   expect(m.proof).toBe(null);
   expect(m.surfaceVersion).toBe(AGENT_SURFACE_VERSION);
 });
@@ -81,6 +84,32 @@ test("buildAgentSurfaceManifest: sorts knowledge refs by domain and actions by i
   expect(m.actions.map((a) => a.id)).toEqual(["appointment.request", "lead.submit"]);
 });
 
+test("buildAgentSurfaceManifest: populates search interface when search input is provided", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(m.interfaces.search).toEqual({
+    url: "/api/agent/search",
+    model: "@cf/baai/bge-m3",
+    dimensions: 1024,
+  });
+});
+
+test("buildAgentSurfaceManifest: search interface is null by default", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.interfaces.search).toBe(null);
+});
+
+test("buildAgentSurfaceManifest: search interface presence changes contentHash", () => {
+  const without = buildAgentSurfaceManifest(baseInput);
+  const withSearch = buildAgentSurfaceManifest({
+    ...baseInput,
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(without.contentHash).not.toBe(withSearch.contentHash);
+});
+
 test("computeAgentManifestContentHash: excludes contentHash and proof fields from the hash input", () => {
   const doc: Record<string, unknown> = { a: 1, b: 2, contentHash: "whatever", proof: { x: 1 } };
   const withoutHashFields = { a: 1, b: 2 };
@@ -98,3 +127,25 @@ test("canonicalJson: sorts object keys deeply, preserves array order", () => {
   expect(canonicalJson({ b: 1, a: { d: 2, c: 3 } })).toBe('{"a":{"c":3,"d":2},"b":1}');
   expect(canonicalJson([3, 1, 2])).toBe("[3,1,2]");
 });
+
+test("computeSignedContentHash: always excludes contentHash and proof", () => {
+  const base = { a: 1, b: 2 };
+  const withHash = { ...base, contentHash: "abc", proof: { type: "test" } };
+  const withDifferentHash = { ...base, contentHash: "xyz", proof: { type: "other" } };
+  expect(computeSignedContentHash(withHash)).toBe(computeSignedContentHash(base));
+  expect(computeSignedContentHash(withDifferentHash)).toBe(computeSignedContentHash(base));
+});
+
+test("computeSignedContentHash: supports additional excludeFields", () => {
+  const base = { a: 1, b: 2 };
+  const withTimestamp = { ...base, generatedAt: "2026-01-01T00:00:00Z" };
+  const withDifferentTimestamp = { ...base, generatedAt: "2026-12-31T23:59:59Z" };
+  expect(computeSignedContentHash(withTimestamp, ["generatedAt"])).toBe(
+    computeSignedContentHash(withDifferentTimestamp, ["generatedAt"]),
+  );
+});
+
+test("computeSignedContentHash: matches computeAgentManifestContentHash for same inputs", () => {
+  const doc = { a: 1, b: 2, contentHash: "x", proof: null };
+  expect(computeSignedContentHash(doc)).toBe(computeAgentManifestContentHash(doc));
+});

package/src/share/tests/openapi.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI formatter tests.</item>
+  <item>RFC-0954: add search path projection tests.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -114,3 +115,32 @@ test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
   const doc = formatAgentOpenApi(manifest, []);
   expect(doc["x-gogol-mcp"]).toEqual({ url: "/api/agent/mcp", protocolVersion: "2025-06-18" });
 });
+
+test("formatAgentOpenApi: search interface present → /api/agent/search GET path with dynamic lang enum", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de", "uk"] },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  const op = doc.paths["/api/agent/search"]?.get;
+  expect(op).toBeTruthy();
+  expect(op!.operationId).toBe("search.query");
+  expect(op!.tags).toEqual(["search"]);
+  expect(doc.components.schemas["search-response"]).toBeTruthy();
+  const langParam = op!.parameters!.find((p: { name: string }) => p.name === "lang");
+  expect(langParam).toBeTruthy();
+  expect(langParam!.schema.enum).toEqual(["de", "uk"]);
+});
+
+test("formatAgentOpenApi: search interface absent → no search path", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  expect(doc.paths["/api/agent/search"]).toBe(undefined);
+  expect(doc.components.schemas["search-response"]).toBe(undefined);
+});

package/src/share/types/qrcode-browser.d.ts

@@ -0,0 +1,18 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Type shim for the qrcode browser entry point (qrcode/lib/browser.js).
+The qrcode package only ships types for its main entry, but the browser entry
+exports the same toCanvas function. This shim re-exports all types from qrcode
+so the client-side QR code script gets full type safety.</purpose>
+<non-goals>
+  <item>Do not change runtime resolution; this file only fills the missing package declaration.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Add type declaration for qrcode/lib/browser.js deep import used by external-link-qr.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+declare module "qrcode/lib/browser.js" {
+  export * from "qrcode";
+}

package/src/share/utility-registry.yaml

@@ -3,8 +3,8 @@ utilities:
     canonicalPath: packages/werkstatt-shared/src/share/slug/
     forbiddenImports:
       - "@sindresorhus/slugify"
-      - "cyrillic-to-translit-js"
-      - "github-slugger"
+      - cyrillic-to-translit-js
+      - github-slugger
     functionNames:
       - slugify
       - toSlug
@@ -34,3 +34,17 @@ utilities:
     allowlist:
       - path: packages/werkstatt-shared/src/share/routes/
         reason: Canonical placeholder route filter — owns all template detection logic (RFC-0917)
+  - id: remediation-catalog
+    canonicalPath: packages/werkstatt-shared/src/share/remediation/
+    forbiddenImports: []
+    functionNames:
+      - lookupRemediation
+      - REMEDIATION_CATALOG
+    patterns: []
+    allowlist:
+      - path: packages/werkstatt-shared/src/share/remediation/
+        reason: Canonical remediation catalog — owns all ruleId-to-remediation-pattern mappings (RFC-1027)
+      - path: packages/werkstatt-shared/src/checks/result-helpers.ts
+        reason: Consumes lookupRemediation to auto-populate Diagnostic.remediation (RFC-1027)
+      - path: packages/werkstatt-engine/src/remediation/
+        reason: Engine remediation module reads REMEDIATION_CATALOG for catalog.generate and hint.validate (RFC-1027)