@warpgogol/werkstatt-shared 0.14.0 → 0.14.1

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { buildApiCatalog } from "../api-catalog.ts";
+
+describe("buildApiCatalog", () => {
+  it("is a function", () => {
+    expect(typeof buildApiCatalog).toBe("function");
+  });
+});

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { buildArdCatalog } from "../ard-catalog.ts";
+
+describe("buildArdCatalog", () => {
+  it("is a function", () => {
+    expect(typeof buildArdCatalog).toBe("function");
+  });
+});

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

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { resolveActiveCapabilities, capabilityToActionRef } from "../capability.ts";
+
+describe("resolveActiveCapabilities", () => {
+  it("is a function", () => {
+    expect(typeof resolveActiveCapabilities).toBe("function");
+  });
+});
+
+describe("capabilityToActionRef", () => {
+  it("is a function", () => {
+    expect(typeof capabilityToActionRef).toBe("function");
+  });
+});

package/src/share/agent/tests/fleet-catalog.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { FLEET_AGENT_CATALOG_SCHEMA, buildFleetAgentCatalog } from "../fleet-catalog.ts";
+
+describe("FLEET_AGENT_CATALOG_SCHEMA", () => {
+  it("is a string constant", () => {
+    expect(typeof FLEET_AGENT_CATALOG_SCHEMA).toBe("string");
+    expect(FLEET_AGENT_CATALOG_SCHEMA).toContain("fleet.agent-catalog");
+  });
+});
+
+describe("buildFleetAgentCatalog", () => {
+  it("is a function", () => {
+    expect(typeof buildFleetAgentCatalog).toBe("function");
+  });
+});

package/src/share/agent/tests/knowledge.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { AGENT_KNOWLEDGE_DOMAINS, isAgentKnowledgeDomain } from "../knowledge.ts";
+
+describe("AGENT_KNOWLEDGE_DOMAINS", () => {
+  it("is a non-empty array", () => {
+    expect(Array.isArray(AGENT_KNOWLEDGE_DOMAINS)).toBe(true);
+    expect(AGENT_KNOWLEDGE_DOMAINS.length).toBeGreaterThan(0);
+  });
+});
+
+describe("isAgentKnowledgeDomain", () => {
+  it("returns true for valid domain", () => {
+    const firstDomain = AGENT_KNOWLEDGE_DOMAINS[0];
+    expect(isAgentKnowledgeDomain(firstDomain)).toBe(true);
+  });
+
+  it("returns false for invalid domain", () => {
+    expect(isAgentKnowledgeDomain("invalid-domain")).toBe(false);
+  });
+});

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

@@ -0,0 +1,9 @@
+import { describe, it, expect } from "vitest";
+import { AGENT_SURFACE_VERSION } from "../manifest.ts";
+
+describe("AGENT_SURFACE_VERSION", () => {
+  it("is a version string", () => {
+    expect(typeof AGENT_SURFACE_VERSION).toBe("string");
+    expect(AGENT_SURFACE_VERSION).toMatch(/\d+\.\d+\.\d+/);
+  });
+});

package/src/share/agent/tests/mcp-card.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { buildMcpServerCard } from "../mcp-card.ts";
+
+describe("buildMcpServerCard", () => {
+  it("is a function", () => {
+    expect(typeof buildMcpServerCard).toBe("function");
+  });
+});

package/src/share/agent/tests/omit-empty.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { omitEmptyKnowledgeValues } from "../omit-empty.ts";
+
+describe("omitEmptyKnowledgeValues", () => {
+  it("is a function", () => {
+    expect(typeof omitEmptyKnowledgeValues).toBe("function");
+  });
+
+  it("removes empty strings, null, undefined, empty arrays, and empty objects", () => {
+    const input = { a: "value", b: "", c: null, d: undefined, e: [], f: {} };
+    const result = omitEmptyKnowledgeValues(input);
+    expect(result).not.toHaveProperty("b");
+    expect(result).not.toHaveProperty("c");
+    expect(result).not.toHaveProperty("d");
+    expect(result).not.toHaveProperty("e");
+    expect(result).not.toHaveProperty("f");
+    expect(result).toHaveProperty("a", "value");
+  });
+
+  it("preserves false and 0 (schema-allowed falsy values)", () => {
+    const input = { enabled: false, count: 0 };
+    const result = omitEmptyKnowledgeValues(input);
+    expect(result).toHaveProperty("enabled", false);
+    expect(result).toHaveProperty("count", 0);
+  });
+
+  it("preserves non-empty arrays and objects", () => {
+    const input = { items: [1, 2], nested: { x: 1 } };
+    const result = omitEmptyKnowledgeValues(input);
+    expect(result).toHaveProperty("items", [1, 2]);
+    expect(result).toHaveProperty("nested", { x: 1 });
+  });
+});

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { formatAgentOpenApi } from "../openapi.ts";
+
+describe("formatAgentOpenApi", () => {
+  it("is a function", () => {
+    expect(typeof formatAgentOpenApi).toBe("function");
+  });
+});

package/src/share/agent/tests/proof.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { AGENT_PROOF_DOMAIN, buildAgentSigningPayload } from "../proof.ts";
+
+describe("AGENT_PROOF_DOMAIN", () => {
+  it("is a string constant", () => {
+    expect(typeof AGENT_PROOF_DOMAIN).toBe("string");
+    expect(AGENT_PROOF_DOMAIN.length).toBeGreaterThan(0);
+  });
+});
+
+describe("buildAgentSigningPayload", () => {
+  it("is a function", () => {
+    expect(typeof buildAgentSigningPayload).toBe("function");
+  });
+});

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

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { CLAIM_PROVENANCE_KINDS } from "../claim.ts";
+
+describe("CLAIM_PROVENANCE_KINDS", () => {
+  it("contains expected provenance kinds", () => {
+    expect(CLAIM_PROVENANCE_KINDS).toContain("external");
+    expect(CLAIM_PROVENANCE_KINDS).toContain("derived");
+    expect(CLAIM_PROVENANCE_KINDS).toContain("asserted");
+    expect(CLAIM_PROVENANCE_KINDS).toContain("generated");
+  });
+});

package/src/share/knowledge/tests/derivation.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { normalizeForHash, hashSourceValue, derivedState } from "../derivation.ts";
+
+describe("normalizeForHash", () => {
+  it("is a function", () => {
+    expect(typeof normalizeForHash).toBe("function");
+  });
+
+  it("normalizes whitespace", () => {
+    const result = normalizeForHash("  hello  world  ");
+    expect(typeof result).toBe("string");
+  });
+});
+
+describe("hashSourceValue", () => {
+  it("is a function", () => {
+    expect(typeof hashSourceValue).toBe("function");
+  });
+
+  it("returns a string hash", () => {
+    const result = hashSourceValue("test");
+    expect(typeof result).toBe("string");
+  });
+});
+
+describe("derivedState", () => {
+  it("is a function", () => {
+    expect(typeof derivedState).toBe("function");
+  });
+});

package/src/share/knowledge/tests/freshness.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest";
+import { addDuration } from "../freshness.ts";
+
+describe("addDuration", () => {
+  it("is a function", () => {
+    expect(typeof addDuration).toBe("function");
+  });
+
+  it("adds months to a date", () => {
+    const result = addDuration("2026-01-01", "P3M");
+    expect(result).not.toBeNull();
+  });
+
+  it("returns null for invalid duration", () => {
+    const result = addDuration("2026-01-01", "invalid");
+    expect(result).toBeNull();
+  });
+});

package/src/share/knowledge/tests/ledger.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import type { ClaimEvent, ClaimLineage } from "../ledger.ts";
+
+describe("ledger types", () => {
+  it("ClaimEvent is a valid type", () => {
+    const event: ClaimEvent = {
+      id: "evt-1",
+      ts: "2026-01-01T00:00:00Z",
+      subject: "test",
+      provenance: "asserted",
+      asOf: "2026-01-01",
+      actor: "agent",
+      event: "asserted" as ClaimEvent["event"],
+    };
+    expect(event).toBeDefined();
+  });
+
+  it("ClaimLineage is a valid type", () => {
+    const event: ClaimEvent = {
+      id: "evt-1",
+      ts: "2026-01-01T00:00:00Z",
+      subject: "test",
+      provenance: "asserted",
+      asOf: "2026-01-01",
+      actor: "agent",
+      event: "asserted" as ClaimEvent["event"],
+    };
+    const lineage: ClaimLineage = {
+      subject: "test",
+      current: event,
+      history: [event],
+    };
+    expect(lineage).toBeDefined();
+  });
+});

package/src/share/knowledge/tests/plan.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { stableTaskId } from "../plan.ts";
+
+describe("stableTaskId", () => {
+  it("is a function", () => {
+    expect(typeof stableTaskId).toBe("function");
+  });
+
+  it("returns a string id", () => {
+    const result = stableTaskId("subject-1", "review-due");
+    expect(typeof result).toBe("string");
+  });
+
+  it("is deterministic for same inputs", () => {
+    const a = stableTaskId("subject-1", "review-due");
+    const b = stableTaskId("subject-1", "review-due");
+    expect(a).toBe(b);
+  });
+});

package/src/share/knowledge/tests/source.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { SOURCE_KINDS, sourceToleranceSchema } from "../source.ts";
+
+describe("SOURCE_KINDS", () => {
+  it("contains expected source kinds", () => {
+    expect(SOURCE_KINDS).toContain("http-json");
+    expect(SOURCE_KINDS).toContain("manual");
+  });
+});
+
+describe("sourceToleranceSchema", () => {
+  it("is defined", () => {
+    expect(sourceToleranceSchema).toBeDefined();
+  });
+
+  it("rejects null", () => {
+    expect(() => sourceToleranceSchema.parse(null)).toThrow();
+  });
+});

package/src/share/remediation/remediation-catalog.ts

@@ -0,0 +1,196 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Canonical remediation catalog mapping ruleId to structured remediation patterns.
+  Consumed by diagnosticsResult() for auto-population and by remediation.hint.validate
+  for coverage checking (RFC-1027).
+</purpose>
+<non-goals>
+  <item>Does not own the Diagnostic schema — that lives in werkstatt-engine schemas.</item>
+  <item>Does not aggregate remediation hints into KernelExecutionReport — that is the engine's job.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1027: Create REMEDIATION_CATALOG with 30+ patterns for the most common ruleIds.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface RemediationPattern {
+  ruleId: string;
+  action: string;
+  template?: string;
+  docRef?: string;
+  targetFiles?: string[];
+}
+
+const REMEDIATION_ENTRIES: RemediationPattern[] = [
+  {
+    ruleId: "SEO-RUNTIME.CANONICAL-MISMATCH",
+    action: "Ensure the canonical URL in the rendered HTML matches the production domain without language prefix for the default locale.",
+    docRef: "docs/authoring/site-composition.md",
+    targetFiles: ["src/layouts/**/*.astro"],
+  },
+  {
+    ruleId: "WORKSPACE.SURFACE.VALIDATE",
+    action: "Fix surface validation errors by checking the surface block declarations against the schema.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "TEST.SIGNAL.POLICY.VALIDATE",
+    action: "Align test signal declarations with the policy schema — check signal name, severity, and evidence path.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "PUBLIC.ICONS.VALIDATE",
+    action: "Replace invalid icon references with valid SurfaceLabels entries or remove the icon field.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "PARITY-SECTION-COUNT",
+    action: "Add or remove sections so the locale overlay matches the base locale section count.",
+    docRef: "docs/authoring/preventive-measures-parity-and-templates.md",
+  },
+  {
+    ruleId: "GEN-FILES-01",
+    action: "Regenerate generated files by running the owning kernel command, then commit the updated output.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "DEPS-GEN-01",
+    action: "Run pnpm exec werkstatt run deps.peer.check to regenerate the peer dependency manifest.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "AGC-01",
+    action: "Fix the agent gate configuration — ensure the gate metadata matches the declared gate catalog.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "WORKPIECE-IMPORTS-01",
+    action: "Resolve the broken import in the workpiece — check the module path and ensure the package is installed.",
+  },
+  {
+    ruleId: "SNAP-01",
+    action: "Regenerate the behavior snapshot by running pnpm exec werkstatt run behavior.snapshot.generate.",
+  },
+  {
+    ruleId: "CREG-04",
+    action: "Fix the content regression — review the content diff and update the review.yaml before closing the mission.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "CREG-03",
+    action: "Fix the content regression — ensure all locale overlays are consistent with the base content.",
+    docRef: "docs/authoring/preventive-measures-parity-and-templates.md",
+  },
+  {
+    ruleId: "CREG-01",
+    action: "Fix the content regression — the base content was changed without a review.yaml. Run content.regression.review.generate.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "BRK-04",
+    action: "Fix the bordbuch entry — ensure the hash chain is intact and the entry is properly signed.",
+  },
+  {
+    ruleId: "PROPS-01",
+    action: "Fix the content props schema violation — check the frontmatter against the schema declaration.",
+  },
+  {
+    ruleId: "MAINTENANCE.DEBT.BASELINE.VALIDATE",
+    action: "Regenerate the maintenance debt baseline by running pnpm exec werkstatt run maintenance.debt.baseline.generate.",
+  },
+  {
+    ruleId: "HDR-04",
+    action: "Fix the header configuration — ensure the header block matches the surface schema.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "HDR-02",
+    action: "Fix the header navigation — ensure all nav items have valid href and label.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "HDR-01",
+    action: "Fix the header structure — ensure the header block is declared in the surface composition.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "GEN-EDIT-01",
+    action: "Do not hand-edit generated files. Modify the source template and regenerate.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "DEPS-PEER-01",
+    action: "Add the missing peer dependency to the package.json or remove the import that requires it.",
+  },
+  {
+    ruleId: "CW-EVID-01",
+    action: "Fix the changelog evidence — ensure the evidence file exists and is referenced correctly.",
+  },
+  {
+    ruleId: "CMD-MAN-03",
+    action: "Regenerate the command manifest by running pnpm exec werkstatt run command.manifest.generate.",
+  },
+  {
+    ruleId: "CI-LOCAL-05",
+    action: "Fix the CI configuration — ensure the local CI workflow matches the pipeline definitions.",
+  },
+  {
+    ruleId: "AGS-05",
+    action: "Fix the agent gate search configuration — ensure the search manifest is generated and accessible.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGS-02",
+    action: "Fix the agent gate search schema — ensure the search chunk text is within the max length.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGO-01",
+    action: "Fix the agent gate output — ensure the gate output matches the declared schema.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGK-03",
+    action: "Fix the agent gate key — ensure the gate key is unique and matches the declared catalog.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "WS-WRITE-02",
+    action: "Fix the workspace write — ensure the write intent is declared and the path is within the workspace root.",
+  },
+  {
+    ruleId: "SUPPRESS-VAL-04",
+    action: "Fix the suppression validation — ensure the suppression rule matches the declared schema.",
+    docRef: "docs/authoring/guide-suppression-matching.md",
+  },
+  {
+    ruleId: "ENV-CONTRACT-02",
+    action: "Fix the environment contract — ensure the env variable is declared in .env.example and matches the contract.",
+  },
+  {
+    ruleId: "ENV-CONTRACT-04",
+    action: "Fix the environment contract — ensure the env variable type matches the declared schema.",
+  },
+  {
+    ruleId: "ENV-CONTRACT-05",
+    action: "Fix the environment contract — ensure the env variable is documented in the .env.example file.",
+  },
+  {
+    ruleId: "DEPLOY-SCRIPTS-03",
+    action: "Fix the deploy script — ensure the script is executable and matches the deployment pipeline.",
+  },
+  {
+    ruleId: "FLEET-05",
+    action: "Fix the fleet configuration — ensure the fleet entry matches the declared schema.",
+  },
+];
+
+export const REMEDIATION_CATALOG: ReadonlyMap<string, RemediationPattern> = new Map(
+  REMEDIATION_ENTRIES.map((entry) => [entry.ruleId, entry]),
+);
+
+export function lookupRemediation(ruleId: string): RemediationPattern | undefined {
+  return REMEDIATION_CATALOG.get(ruleId);
+}

package/src/share/schemas/tests/claim-records.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { claimSourceRefSchema } from "../claim-records.ts";
+
+describe("claimSourceRefSchema", () => {
+  it("accepts a valid source ref", () => {
+    const ref = {
+      sourceId: "src-1",
+      url: "https://example.com",
+      title: "Example",
+      retrievedAt: "2026-01-01",
+    };
+    expect(claimSourceRefSchema.parse(ref)).toEqual(ref);
+  });
+
+  it("rejects missing required fields", () => {
+    expect(() => claimSourceRefSchema.parse({ sourceId: "src-1" })).toThrow();
+  });
+
+  it("rejects invalid URL", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "not-a-url",
+        title: "Example",
+        retrievedAt: "2026-01-01",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects invalid date format", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "https://example.com",
+        title: "Example",
+        retrievedAt: "01/01/2026",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects extra keys (strict)", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "https://example.com",
+        title: "Example",
+        retrievedAt: "2026-01-01",
+        extra: true,
+      }),
+    ).toThrow();
+  });
+});

package/src/share/schemas/tests/claims.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { recordClaimsSchema } from "../claims.ts";
+
+describe("recordClaimsSchema", () => {
+  it("accepts empty record", () => {
+    expect(recordClaimsSchema.parse({})).toEqual({});
+  });
+
+  it("accepts a valid claims record", () => {
+    const claims = {
+      field1: {
+        provenance: "external",
+        asOf: "2026-01-01",
+      },
+    };
+    const result = recordClaimsSchema.safeParse(claims);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects non-object", () => {
+    expect(() => recordClaimsSchema.parse("not an object")).toThrow();
+  });
+});