@warpgogol/werkstatt-shared 0.2.0

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

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0783: determinism + shape tests for the API Catalog linkset projection.</purpose>
+<keywords>RFC-0783, agent surface, API Catalog, linkset, test</keywords>
+</MODULE_CONTRACT>
+<MODULE_MAP>
+  <entry key="tests">empty manifest, knowledge ref projection, mcp link entries, determinism.</entry>
+</MODULE_MAP>
+<CHANGE_SUMMARY>
+  <item>RFC-0783: initial API Catalog projection tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { buildApiCatalog } from "../agent/api-catalog.ts";
+import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+
+test("buildApiCatalog: empty manifest yields service-meta + service-doc links", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const catalog = buildApiCatalog(manifest);
+  const entry = catalog.linkset[0];
+  expect(entry.anchor).toBe("https://s.example/");
+  const serviceMeta = entry["service-meta"] as { href: string }[];
+  expect(serviceMeta).toHaveLength(1);
+  expect(serviceMeta[0].href).toBe("/.well-known/agent.json");
+  const serviceDoc = entry["service-doc"] as { href: string }[];
+  expect(serviceDoc).toHaveLength(1);
+  expect(serviceDoc[0].href).toBe("/llms.txt");
+});
+
+test("buildApiCatalog: one knowledge ref → one item link", () => {
+  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" },
+    ],
+  });
+  const catalog = buildApiCatalog(manifest);
+  const itemLinks = catalog.linkset[0]["item"] as { href: string; type: string; title: string }[];
+  expect(itemLinks).toHaveLength(1);
+  expect(itemLinks[0].href).toBe("/api/agent/v1/offer.json");
+  expect(itemLinks[0].type).toBe("application/json");
+  expect(itemLinks[0].title).toBe("offer");
+});
+
+test("buildApiCatalog: mcp interface adds service-desc + service links", () => {
+  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 = buildApiCatalog(manifest);
+  const entry = catalog.linkset[0];
+  const descHrefs = (entry["service-desc"] as { href: string }[]).map((l) => l.href);
+  expect(descHrefs).toContain("/.well-known/mcp/server-card.json");
+  const service = entry["service"] as { href: string }[];
+  expect(service[0].href).toBe("/api/agent/mcp");
+});
+
+test("buildApiCatalog: 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" },
+      { domain: "team", url: "/api/agent/v1/team.json", schema: "gogol.agent.knowledge/team@1" },
+    ],
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
+  };
+  const a = buildApiCatalog(buildAgentSurfaceManifest(input));
+  const b = buildApiCatalog(buildAgentSurfaceManifest(input));
+  expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+});
+
+test("buildApiCatalog: links are sorted by href within each relation", () => {
+  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 = buildApiCatalog(manifest);
+  const itemHrefs = (catalog.linkset[0]["item"] as { href: string }[]).map((l) => l.href);
+  const sorted = [...itemHrefs].sort();
+  expect(itemHrefs).toEqual(sorted);
+});

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

@@ -0,0 +1,126 @@
+/*
+<MODULE_CONTRACT>
+<purpose>[RFC-0229] Unit tests for the canonical breadcrumb trail builder: ordering (Home → ancestors
+  → self), dedupe against Home/self, site-name stripping, empty-ancestor flat trail, and the resolver
+  seam contract.</purpose>
+<keywords>breadcrumb, trail, test, RFC-0229</keywords>
+</MODULE_CONTRACT>
+*/
+
+import { test, expect } from "vitest";
+import {
+  buildBreadcrumbTrail,
+  stripSiteNameFromTitle,
+  surfaceAncestorPageIds,
+  type BreadcrumbAncestorResolver,
+  type BreadcrumbCrumb,
+} from "../semantic/breadcrumbs.ts";
+
+const HOME = "https://example.com/";
+const SELF = "https://example.com/website/schreiner/muenchen/";
+
+function resolverWith(ancestors: BreadcrumbCrumb[]): BreadcrumbAncestorResolver {
+  return { resolveAncestors: async () => ancestors };
+}
+
+test("flat trail when there are no ancestors: Home → self", async () => {
+  const trail = await buildBreadcrumbTrail({
+    pageId: "impressum",
+    pageTitle: "Impressum | Warpgogol",
+    selfUrl: "https://example.com/impressum/",
+    homeLabel: "Startseite",
+    homeUrl: HOME,
+    lang: "de",
+    defaultLang: "de",
+    resolver: resolverWith([]),
+  });
+  expect(trail.map((c) => c.name)).toEqual(["Startseite", "Impressum"]);
+  expect(trail[1]!.url).toBe("https://example.com/impressum/");
+});
+
+test("multi-level trail: Home → ancestors (root-first) → self, site name stripped", async () => {
+  const trail = await buildBreadcrumbTrail({
+    pageId: "website-local:schreiner:muenchen",
+    pageTitle: "Schreiner-Website in München | Warpgogol",
+    selfUrl: SELF,
+    homeLabel: "Startseite",
+    homeUrl: HOME,
+    lang: "de",
+    defaultLang: "de",
+    resolver: resolverWith([
+      { name: "Website erstellen lassen", url: "https://example.com/website/" },
+      { name: "Schreiner-Websites", url: "https://example.com/website/schreiner/" },
+    ]),
+  });
+  expect(trail.map((c) => c.name)).toEqual([
+    "Startseite",
+    "Website erstellen lassen",
+    "Schreiner-Websites",
+    "Schreiner-Website in München",
+  ]);
+  expect(trail[trail.length - 1]!.url).toBe(SELF);
+});
+
+test("ancestors collapsing onto Home or self are dropped", async () => {
+  const trail = await buildBreadcrumbTrail({
+    pageId: "p",
+    pageTitle: "Self",
+    selfUrl: SELF,
+    homeLabel: "Home",
+    homeUrl: HOME,
+    lang: "de",
+    defaultLang: "de",
+    resolver: resolverWith([
+      { name: "Home dup", url: "https://example.com" }, // == Home after trailing-slash normalize
+      { name: "Mid", url: "https://example.com/website/" },
+      { name: "Self dup", url: SELF.replace(/\/$/, "") }, // == self after normalize
+    ]),
+  });
+  expect(trail.map((c) => c.name)).toEqual(["Home", "Mid", "Self"]);
+});
+
+test("repeated ancestor URLs are deduped, blank names skipped", async () => {
+  const trail = await buildBreadcrumbTrail({
+    pageId: "p",
+    pageTitle: "Self",
+    selfUrl: SELF,
+    homeLabel: "Home",
+    homeUrl: HOME,
+    lang: "de",
+    defaultLang: "de",
+    resolver: resolverWith([
+      { name: "A", url: "https://example.com/a/" },
+      { name: "A again", url: "https://example.com/a" }, // same after normalize → dropped
+      { name: "   ", url: "https://example.com/b/" }, // blank name → dropped
+    ]),
+  });
+  expect(trail.map((c) => c.name)).toEqual(["Home", "A", "Self"]);
+});
+
+test("stripSiteNameFromTitle trims a ' | Site' suffix only", () => {
+  expect(stripSiteNameFromTitle("Page | Site")).toBe("Page");
+  expect(stripSiteNameFromTitle("Just A Page")).toBe("Just A Page");
+  expect(stripSiteNameFromTitle("A | B | Site")).toBe("A | B");
+});
+
+test("surfaceAncestorPageIds derives the depth chain (root-first, excludes self)", () => {
+  // depth-2 page → [root, depth-1]
+  expect(surfaceAncestorPageIds("website-local:elektriker:heidelberg")).toEqual([
+    "website-local:_root",
+    "website-local:elektriker",
+  ]);
+  // depth-3 page → [root, depth-1, depth-2]
+  expect(surfaceAncestorPageIds("website-service:elektriker:leistung:wallbox")).toEqual([
+    "website-service:_root",
+    "website-service:elektriker",
+    "website-service:elektriker:leistung",
+  ]);
+  // depth-1 page → [root]
+  expect(surfaceAncestorPageIds("website-local:elektriker")).toEqual(["website-local:_root"]);
+});
+
+test("surfaceAncestorPageIds returns [] for the root landing and non-surface ids", () => {
+  expect(surfaceAncestorPageIds("website-local:_root")).toEqual([]);
+  expect(surfaceAncestorPageIds("impressum")).toEqual([]); // authored pageId, no colon
+  expect(surfaceAncestorPageIds("")).toEqual([]);
+});

package/src/share/tests/build-page-price-markers.test.ts

@@ -0,0 +1,160 @@
+/*
+<MODULE_CONTRACT>
+<purpose>[RFC-0767] Integration tests for price marker resolution in buildSemanticPageModelWith — verifies that markers in heading, lead, and description are resolved before entering the SemanticPageModel.</purpose>
+<keywords>price-marker, semantic, build-page, integration, test, RFC-0767</keywords>
+</MODULE_CONTRACT>
+*/
+
+import { test, expect, describe } from "vitest";
+import {
+  buildSemanticPageModelWith,
+  type SemanticContentReader,
+  type SemanticBuildProfile,
+} from "../semantic/build-page.ts";
+import { OFFERING_URI_PREFIX, type DerivedPriceEntry } from "../semantic/price-marker-resolver.ts";
+
+const fixturePrices: Record<string, DerivedPriceEntry[]> = {
+  [`${OFFERING_URI_PREFIX}referral-fee`]: [
+    {
+      chargeRef: "activation",
+      targetCurrency: "USD",
+      amount: { value: "75", currency: "USD" },
+      trace: {
+        source: { amount: "70", currency: "EUR" },
+        rate: { value: "1.07", pair: "EUR/USD" },
+      },
+    },
+  ],
+};
+
+function createMockReader(
+  frontmatter: Record<string, unknown>,
+  derivedPrices: Record<string, DerivedPriceEntry[]> | null,
+): SemanticContentReader {
+  return {
+    async getPageFrontmatter() {
+      return frontmatter;
+    },
+    async getProseBody() {
+      return "";
+    },
+    async getHomeLabel() {
+      return "Home";
+    },
+    async getFaqEntries() {
+      return [];
+    },
+    getDerivedPrices() {
+      return derivedPrices;
+    },
+  };
+}
+
+const emptyProfile: SemanticBuildProfile = {
+  organization: {
+    name: "Test Org",
+    description: "Test organization",
+    url: "https://example.com",
+    sameAs: [],
+  },
+  people: [],
+  initiatives: [],
+};
+
+describe("buildSemanticPageModelWith with price markers", () => {
+  test("13. heading with price marker resolves to EUR string", async () => {
+    const reader = createMockReader(
+      {
+        title: "Test Page",
+        description: "Test description",
+        blocks: [
+          {
+            type: "hero",
+            props: {
+              header: {
+                heading: "Отримайте {price:referral-fee:activation} за кожну підписку",
+              },
+            },
+          },
+        ],
+      },
+      fixturePrices,
+    );
+
+    const model = await buildSemanticPageModelWith(reader, {
+      pageId: "test-page",
+      semanticType: "about",
+      lang: "de",
+      url: "https://example.com/test",
+      profile: emptyProfile,
+    });
+
+    expect(model).not.toBeNull();
+    expect(model!.heading).toContain("70");
+    expect(model!.heading).toContain("€");
+    expect(model!.heading).not.toContain("{price:");
+  });
+
+  test("14. heading with price marker and null derived prices resolves to 0 € fallback", async () => {
+    const reader = createMockReader(
+      {
+        title: "Test Page",
+        description: "Test description",
+        blocks: [
+          {
+            type: "hero",
+            props: {
+              header: {
+                heading: "Отримайте {price:referral-fee:activation}",
+              },
+            },
+          },
+        ],
+      },
+      null,
+    );
+
+    const model = await buildSemanticPageModelWith(reader, {
+      pageId: "test-page",
+      semanticType: "about",
+      lang: "de",
+      url: "https://example.com/test",
+      profile: emptyProfile,
+    });
+
+    expect(model).not.toBeNull();
+    expect(model!.heading).toContain("0");
+    expect(model!.heading).toContain("€");
+    expect(model!.heading).not.toContain("{price:");
+  });
+
+  test("15. page without price markers has unchanged model", async () => {
+    const frontmatter = {
+      title: "Plain Page",
+      description: "A page without price markers",
+      blocks: [
+        {
+          type: "hero",
+          props: {
+            header: {
+              heading: "Welcome to the page",
+            },
+          },
+        },
+      ],
+    };
+    const reader = createMockReader(frontmatter, fixturePrices);
+
+    const model = await buildSemanticPageModelWith(reader, {
+      pageId: "plain-page",
+      semanticType: "about",
+      lang: "de",
+      url: "https://example.com/plain",
+      profile: emptyProfile,
+    });
+
+    expect(model).not.toBeNull();
+    expect(model!.heading).toBe("Welcome to the page");
+    expect(model!.description).toBe("A page without price markers");
+  });
+});

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

@@ -0,0 +1,107 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0288: gating-logic tests for resolveActiveCapabilities.</purpose>
+<keywords>RFC-0288, agent surface, capability, test</keywords>
+</MODULE_CONTRACT>
+<MODULE_MAP>
+  <entry key="tests">entitlement gating, section gating, disabled-list, no agent.actions.</entry>
+</MODULE_MAP>
+<CHANGE_SUMMARY>
+  <item>RFC-0288: initial capability resolution tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import {
+  resolveActiveCapabilities,
+  capabilityToActionRef,
+  type CapabilityRecord,
+} from "../agent/capability.ts";
+
+function makeCap(overrides: Partial<CapabilityRecord> = {}): CapabilityRecord {
+  return {
+    id: "lead.submit",
+    version: 1,
+    kind: "action",
+    title: { de: "x", en: "x" },
+    description: { de: "x", en: "x" },
+    input: { type: "object", additionalProperties: false, properties: {} },
+    output: { type: "object", additionalProperties: false, properties: {} },
+    integration: { eventKind: "lead", source: "agent" },
+    requires: { entitlements: [], sections: ["send-message"] },
+    humanEquivalent: { sectionType: "send-message" },
+    limits: { perMinutePerIp: 10, maxPayloadBytes: 16384 },
+    ...overrides,
+  };
+}
+
+test("resolveActiveCapabilities: empty when agent.actions is not entitled", () => {
+  const result = resolveActiveCapabilities({
+    catalog: [makeCap()],
+    entitlements: [],
+    renderedSectionTypes: ["send-message"],
+    actionsDisabled: [],
+  });
+  expect(result).toEqual([]);
+});
+
+test("resolveActiveCapabilities: active when agent.actions held + section renders", () => {
+  const result = resolveActiveCapabilities({
+    catalog: [makeCap()],
+    entitlements: ["agent.actions"],
+    renderedSectionTypes: ["send-message", "hero"],
+    actionsDisabled: [],
+  });
+  expect(result.length).toBe(1);
+  expect(result[0]!.id).toBe("lead.submit");
+});
+
+test("resolveActiveCapabilities: inactive when required section does not render", () => {
+  const result = resolveActiveCapabilities({
+    catalog: [makeCap()],
+    entitlements: ["agent.actions"],
+    renderedSectionTypes: ["hero"],
+    actionsDisabled: [],
+  });
+  expect(result).toEqual([]);
+});
+
+test("resolveActiveCapabilities: inactive when an extra required entitlement is missing", () => {
+  const cap = makeCap({
+    id: "appointment.request",
+    requires: { entitlements: ["booking"], sections: ["booking"] },
+  });
+  const withoutBooking = resolveActiveCapabilities({
+    catalog: [cap],
+    entitlements: ["agent.actions"],
+    renderedSectionTypes: ["booking"],
+    actionsDisabled: [],
+  });
+  expect(withoutBooking).toEqual([]);
+
+  const withBooking = resolveActiveCapabilities({
+    catalog: [cap],
+    entitlements: ["agent.actions", "booking"],
+    renderedSectionTypes: ["booking"],
+    actionsDisabled: [],
+  });
+  expect(withBooking.length).toBe(1);
+});
+
+test("resolveActiveCapabilities: actionsDisabled withholds an otherwise-active capability", () => {
+  const result = resolveActiveCapabilities({
+    catalog: [makeCap()],
+    entitlements: ["agent.actions"],
+    renderedSectionTypes: ["send-message"],
+    actionsDisabled: ["lead.submit"],
+  });
+  expect(result).toEqual([]);
+});
+
+test("capabilityToActionRef: projects id/url/title/entitlement", () => {
+  const ref = capabilityToActionRef(makeCap());
+  expect(ref.id).toBe("lead.submit");
+  expect(ref.url).toBe("/api/agent/actions/lead.submit");
+  expect(ref.entitlement).toBe("agent.actions");
+  expect(ref.title).toEqual({ de: "x", en: "x" });
+});

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

@@ -0,0 +1,90 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0211: round-trip + edge-case tests for the claim subject address codec.</purpose>
+<keywords>RFC-0211, CKL, claim, subject, test</keywords>
+</MODULE_CONTRACT>
+<MODULE_MAP>
+  <entry key="tests">parse/format round-trips, lang detection, malformed input.</entry>
+</MODULE_MAP>
+<CHANGE_SUMMARY>
+  <item>RFC-0211: initial codec tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import {
+  parseClaimSubject,
+  formatClaimSubject,
+  claimSubjectsEqual,
+  ClaimSubjectParseError,
+} from "../knowledge/claim.ts";
+
+test("parse: lang-scoped subject with simple field", () => {
+  const s = parseClaimSubject("business/de/location#residents");
+  expect(s.collection).toBe("business");
+  expect(s.lang).toBe("de");
+  expect(s.file).toBe("location");
+  expect(s.fieldPath).toEqual(["residents"]);
+});
+
+test("parse: lang-scoped subject with nested field path", () => {
+  const s = parseClaimSubject("business/uk/offer#price.monthly");
+  expect(s.lang).toBe("uk");
+  expect(s.file).toBe("offer");
+  expect(s.fieldPath).toEqual(["price", "monthly"]);
+});
+
+test("parse: collection without lang", () => {
+  const s = parseClaimSubject("surface/landing#headline");
+  expect(s.collection).toBe("surface");
+  expect(s.lang).toBe(undefined);
+  expect(s.file).toBe("landing");
+  expect(s.fieldPath).toEqual(["headline"]);
+});
+
+test("parse: nested file path under a lang", () => {
+  const s = parseClaimSubject("business/de/faq/df-start#answer");
+  expect(s.lang).toBe("de");
+  expect(s.file).toBe("faq/df-start");
+  expect(s.fieldPath).toEqual(["answer"]);
+});
+
+test("format is the inverse of parse", () => {
+  for (const raw of [
+    "business/de/location#residents",
+    "business/uk/offer#price.monthly",
+    "surface/landing#headline",
+    "business/de/faq/df-start#answer",
+  ]) {
+    expect(formatClaimSubject(parseClaimSubject(raw))).toBe(raw);
+  }
+});
+
+test("claimSubjectsEqual compares canonical forms", () => {
+  const a = parseClaimSubject("business/de/location#residents");
+  const b = parseClaimSubject("business/de/location#residents");
+  const c = parseClaimSubject("business/uk/location#residents");
+  expect(claimSubjectsEqual(a, b)).toBeTruthy();
+  expect(!claimSubjectsEqual(a, c)).toBeTruthy();
+});
+
+test("parse: a two-letter file stem is not mistaken for a lang when alone", () => {
+  // Only treated as lang when a file segment still remains after it.
+  const s = parseClaimSubject("glossary/de#term");
+  expect(s.collection).toBe("glossary");
+  expect(s.lang).toBe(undefined);
+  expect(s.file).toBe("de");
+  expect(s.fieldPath).toEqual(["term"]);
+});
+
+test("parse: missing # throws", () => {
+  expect(() => parseClaimSubject("business/de/location")).toThrow(ClaimSubjectParseError);
+});
+
+test("parse: empty field path throws", () => {
+  expect(() => parseClaimSubject("business/de/location#")).toThrow(ClaimSubjectParseError);
+});
+
+test("parse: too-short path throws", () => {
+  expect(() => parseClaimSubject("business#x")).toThrow(ClaimSubjectParseError);
+});