@warpgogol/werkstatt-shared 0.7.0 → 0.8.1

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/tests/build-page-price-markers.test.ts

@@ -69,6 +69,7 @@ describe("buildSemanticPageModelWith with price markers", () => {
         description: "Test description",
         blocks: [
           {
+            id: "hero",
             type: "hero",
             props: {
               header: {
@@ -102,6 +103,7 @@ describe("buildSemanticPageModelWith with price markers", () => {
         description: "Test description",
         blocks: [
           {
+            id: "hero",
             type: "hero",
             props: {
               header: {
@@ -134,6 +136,7 @@ describe("buildSemanticPageModelWith with price markers", () => {
       description: "A page without price markers",
       blocks: [
         {
+          id: "hero",
           type: "hero",
           props: {
             header: {

package/src/share/tests/jsonld-video.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from "vitest";
+import { buildVideoObjectNodes } from "../semantic/jsonld/video.ts";
+import { createJsonLdContext } from "../semantic/jsonld/context.ts";
+import type { SemanticPageModel, VideoSeoData } from "../semantic/models.ts";
+
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-0912: Tests for buildVideoObjectNodes — the JSON-LD builder that emits
+    VideoObject nodes from SemanticBlock.video data on opted-in content video blocks.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+function makeMinimalPage(overrides: Partial<SemanticPageModel> = {}): SemanticPageModel {
+  return {
+    url: "https://example.com/uk/demo",
+    type: "article",
+    lang: "uk",
+    title: "Demo Page",
+    description: "A demo page",
+    blocks: [],
+    organization: { name: "Test Org", description: "Test", url: "https://example.com" },
+    ...overrides,
+  } as unknown as SemanticPageModel;
+}
+
+const sampleVideoSeo: VideoSeoData = {
+  seo: {
+    name: "Demo Video",
+    description: "A demonstration of the platform",
+    uploadDate: "2026-01-15T00:00:00Z",
+  },
+  manifest: {
+    posterUrl: "https://example.com/_video/uk/demo/poster.webp",
+    contentUrl: "https://example.com/_video/uk/demo/progressive.h264.mp4",
+    durationSec: 120,
+  },
+};
+
+describe("buildVideoObjectNodes", () => {
+  it("returns empty array when no blocks have video data", () => {
+    const page = makeMinimalPage({
+      blocks: [{ id: "block-1", heading: "Intro" }],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+    expect(nodes).toHaveLength(0);
+  });
+
+  it("emits a VideoObject node for a block with video data", () => {
+    const page = makeMinimalPage({
+      blocks: [{ id: "video-section", heading: "Demo", video: sampleVideoSeo }],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+
+    expect(nodes).toHaveLength(1);
+    const node = nodes[0]!;
+    expect(node["@type"]).toBe("VideoObject");
+    expect(node.name).toBe("Demo Video");
+    expect(node.description).toBe("A demonstration of the platform");
+    expect(node.uploadDate).toBe("2026-01-15T00:00:00Z");
+    expect(node.thumbnailUrl).toBe("https://example.com/_video/uk/demo/poster.webp");
+    expect(node.contentUrl).toBe("https://example.com/_video/uk/demo/progressive.h264.mp4");
+  });
+
+  it("includes ISO 8601 duration when durationSec is present", () => {
+    const page = makeMinimalPage({
+      blocks: [{ id: "v1", heading: "Demo", video: sampleVideoSeo }],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+
+    expect(nodes[0]!.duration).toBe("PT2M0S");
+  });
+
+  it("omits duration when durationSec is absent", () => {
+    const videoWithoutDuration: VideoSeoData = {
+      seo: sampleVideoSeo.seo,
+      manifest: {
+        posterUrl: sampleVideoSeo.manifest.posterUrl,
+        contentUrl: sampleVideoSeo.manifest.contentUrl,
+      },
+    };
+    const page = makeMinimalPage({
+      blocks: [{ id: "v1", heading: "Demo", video: videoWithoutDuration }],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+
+    expect(nodes[0]!.duration).toBeUndefined();
+  });
+
+  it("emits multiple nodes for multiple video blocks", () => {
+    const page = makeMinimalPage({
+      blocks: [
+        { id: "v1", heading: "Demo 1", video: sampleVideoSeo },
+        {
+          id: "v2",
+          heading: "Demo 2",
+          video: {
+            seo: { name: "Second", description: "Second video", uploadDate: "2026-02-01" },
+            manifest: {
+              posterUrl: "https://example.com/_video/uk/demo2/poster.webp",
+              contentUrl: "https://example.com/_video/uk/demo2/progressive.h264.mp4",
+              durationSec: 3661,
+            },
+          },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+
+    expect(nodes).toHaveLength(2);
+    expect(nodes[0]!.name).toBe("Demo Video");
+    expect(nodes[1]!.name).toBe("Second");
+    expect(nodes[1]!.duration).toBe("PT1H1M1S");
+  });
+
+  it("generates unique @id per video block", () => {
+    const page = makeMinimalPage({
+      blocks: [
+        { id: "v1", heading: "Demo 1", video: sampleVideoSeo },
+        {
+          id: "v2",
+          heading: "Demo 2",
+          video: {
+            ...sampleVideoSeo,
+            seo: { name: "Second", description: "d", uploadDate: "2026-02-01" },
+          },
+        },
+      ],
+    });
+    const ctx = createJsonLdContext(page);
+    const nodes = buildVideoObjectNodes(ctx);
+
+    expect(nodes[0]!["@id"]).not.toBe(nodes[1]!["@id"]);
+    expect(nodes[0]!["@id"]).toContain("v1");
+    expect(nodes[1]!["@id"]).toContain("v2");
+  });
+});

package/src/share/tests/jsonld-webpage.test.ts

@@ -0,0 +1,69 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>Test that buildWebPageNode emits correct speakable cssSelector matching the rendered section-header__subheading class.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial test for speakable cssSelector referencing section-header__subheading (not section-header__lead).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, expect, it } from "vitest";
+import { buildWebPageNode } from "../semantic/jsonld/webpage.ts";
+import { createJsonLdContext } from "../semantic/jsonld/context.ts";
+import type { SemanticPageModel, SemanticOrganization } from "../semantic/models.ts";
+
+function makeModel(overrides: Partial<SemanticPageModel> = {}): SemanticPageModel {
+  const org: SemanticOrganization = {
+    name: "Test Org",
+    description: "Test organization",
+    url: "https://example.com",
+  };
+  return {
+    type: "home",
+    lang: "de",
+    url: "https://example.com/de",
+    title: "Test Page",
+    description: "Test description",
+    breadcrumbs: [],
+    blocks: [],
+    organization: org,
+    ...overrides,
+  };
+}
+
+describe("buildWebPageNode speakable cssSelector", () => {
+  it("references section-header__subheading (not section-header__lead) when page has lead", () => {
+    const model = makeModel({
+      lead: "Test lead text",
+      blocks: [{ id: "block-1", heading: "Section heading" }],
+    });
+    const context = createJsonLdContext(model);
+    const node = buildWebPageNode(context);
+    const speakable = node.speakable as { cssSelector: string[] };
+    expect(speakable).toBeDefined();
+    expect(speakable.cssSelector).toContain("h1");
+    expect(speakable.cssSelector).toContain(".section-header__subheading");
+    expect(speakable.cssSelector).not.toContain(".section-header__lead");
+  });
+
+  it("emits only h1 selector when page has no lead", () => {
+    const model = makeModel({
+      blocks: [{ id: "block-1", heading: "Section heading" }],
+    });
+    const context = createJsonLdContext(model);
+    const node = buildWebPageNode(context);
+    const speakable = node.speakable as { cssSelector: string[] };
+    expect(speakable).toBeDefined();
+    expect(speakable.cssSelector).toEqual(["h1"]);
+  });
+
+  it("omits speakable when no blocks have headings", () => {
+    const model = makeModel({
+      lead: "Test lead text",
+      blocks: [{ id: "block-1", heading: "" }],
+    });
+    const context = createJsonLdContext(model);
+    const node = buildWebPageNode(context);
+    expect(node.speakable).toBeUndefined();
+  });
+});

package/src/share/tests/organization-jsonld.test.ts

@@ -72,3 +72,55 @@ describe("RFC-0745: buildOrganizationNode makesOffer priceCurrency", () => {
     expect(makesOffer[1].priceCurrency).toBe("EUR");
   });
 });
+
+describe("buildOrganizationNode priceRange", () => {
+  it("emits priceRange as min–max with currency when multiple prices exist", () => {
+    const org = makeOrgWithPrices([
+      { id: "monthly", label: "Monthly", amount: "70.00", currency: "EUR" },
+      { id: "yearly", label: "Yearly", amount: "700.00", currency: "EUR" },
+      { id: "setup", label: "Setup", amount: "200.00", currency: "EUR" },
+    ]);
+    const context = createJsonLdContext(makeModel(org));
+    const node = buildOrganizationNode(context);
+    expect(node.priceRange).toBe("70–700 EUR");
+  });
+
+  it("emits single-amount priceRange when all prices are equal", () => {
+    const org = makeOrgWithPrices([
+      { id: "monthly", label: "Monthly", amount: "70.00", currency: "EUR" },
+    ]);
+    const context = createJsonLdContext(makeModel(org));
+    const node = buildOrganizationNode(context);
+    expect(node.priceRange).toBe("70 EUR");
+  });
+
+  it("omits priceRange when no prices exist", () => {
+    const org: SemanticOrganization = {
+      name: "Test Org",
+      description: "Test organization",
+      url: "https://example.com",
+    };
+    const context = createJsonLdContext(makeModel(org));
+    const node = buildOrganizationNode(context);
+    expect(node.priceRange).toBeUndefined();
+  });
+
+  it("omits priceRange when price amounts are non-numeric", () => {
+    const org = makeOrgWithPrices([
+      { id: "custom", label: "Custom", amount: "auf Anfrage", currency: "EUR" },
+    ]);
+    const context = createJsonLdContext(makeModel(org));
+    const node = buildOrganizationNode(context);
+    expect(node.priceRange).toBe("");
+  });
+
+  it("emits priceRange without currency when prices lack currency", () => {
+    const org = makeOrgWithPrices([
+      { id: "monthly", label: "Monthly", amount: "70.00" },
+      { id: "setup", label: "Setup", amount: "200.00" },
+    ]);
+    const context = createJsonLdContext(makeModel(org));
+    const node = buildOrganizationNode(context);
+    expect(node.priceRange).toBe("70–200");
+  });
+});

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

@@ -0,0 +1,22 @@
+declare module "@syrokomskyi/axiom-study" {
+  export interface Finding {
+    findingId: string;
+    semanticFingerprint: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+    methodologyId: string;
+    ruleId: string;
+    affectedSubjectId: string;
+    title: string;
+    severity: "info" | "low" | "medium" | "high" | "critical";
+    evidence: Array<{
+      evidenceRef: {
+        artifactId: string;
+        rootDigest: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+        schema: string;
+      };
+      selector: string;
+      evidenceClass: string;
+    }>;
+    uncertainty: unknown[];
+    extension: Record<string, unknown>;
+  }
+}

package/src/share/utility-registry.yaml

@@ -0,0 +1,36 @@
+utilities:
+  - id: slug
+    canonicalPath: packages/werkstatt-shared/src/share/slug/
+    forbiddenImports:
+      - "@sindresorhus/slugify"
+      - "cyrillic-to-translit-js"
+      - "github-slugger"
+    functionNames:
+      - slugify
+      - toSlug
+      - makeSlug
+      - createSlug
+      - slugUrl
+      - slugId
+    patterns:
+      - id: nkfd-diacritic-strip
+        regex: "\\.normalize\\(.{0,5}NFKD.{0,5}\\)\\.replace"
+        description: NFKD normalize + diacritic strip + non-alphanumeric replace (legacy custom slugify pattern)
+    allowlist:
+      - path: packages/werkstatt-shared/src/share/slug/
+        reason: Canonical slug module — owns all slug generation logic (RFC-0915, DNA-88)
+      - path: packages/werkstatt-shared/src/share/semantic/extract.ts
+        reason: CHANGE_SUMMARY comment references slugify removal — no function definition remains
+      - path: packages/werkstatt-site/src/checks/tests/utility-provenance.test.ts
+        reason: Test file intentionally contains forbidden patterns to validate the provenance validator (RFC-0916)
+      - path: packages/werkstatt-site/src/checks/utility-provenance.ts
+        reason: Validator implementation references forbidden imports/function names in string literals for detection logic (RFC-0916)
+  - id: template-filter
+    canonicalPath: packages/werkstatt-shared/src/share/routes/
+    forbiddenImports: []
+    functionNames:
+      - hasPlaceholderRoutes
+    patterns: []
+    allowlist:
+      - path: packages/werkstatt-shared/src/share/routes/
+        reason: Canonical placeholder route filter — owns all template detection logic (RFC-0917)

package/src/surface/blueprint-schema.ts

@@ -53,7 +53,7 @@ const pillarAdaptationSchema = z.object({
 const pillarProductPriceSchema = z.object({
   heading: localizedString,
   body: localizedString,
-  priceRef: z.string().min(1),
+  priceRef: z.string().min(1).optional(),
 });
 
 const pillarFinalCtaSchema = z.object({

package/src/surface/blueprint-types.ts

@@ -52,7 +52,7 @@ export interface BlueprintPillarAdaptation {
 export interface BlueprintPillarProductPrice {
   heading: LocalizedString;
   body: LocalizedString;
-  priceRef: string;
+  priceRef?: string;
 }
 
 export interface BlueprintPillarFinalCta {

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",