@warpgogol/werkstatt-shared 0.2.0

package/src/checks/suppressions-config.ts

@@ -0,0 +1,195 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0684: Zod schemas, loaders, merger, and post-filter for the Axiom finding suppression layer. Defines the shape for suppression rules, loads workshop-level and per-site configs, merges them, and applies suppressions to findings.</purpose>
+<non-goals>
+  <item>Does not execute Axiom checks — that belongs in mission.check and the external Axiom package.</item>
+  <item>Does not validate suppression config — that belongs in suppressions-validate.ts.</item>
+  <item>Does not modify evidence files — applySuppressions returns a new array; the caller decides whether to write it back.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0684: initial implementation of suppression config schema, loaders, merger, and applySuppressions post-filter.</item>
+  <item>RFC-0688: add titlePattern field to match against finding.title (always populated). messagePattern/descriptionPattern kept for forward compatibility but match against non-existent Finding fields.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { parse as parseYaml } from "yaml";
+import type { Finding } from "@syrokomskyi/axiom-study";
+
+export const suppressionRuleSchema = z.object({
+  ruleId: z.string().min(1),
+  category: z.string().min(1),
+  channel: z.enum(["dev", "alt", "main"]).optional(),
+  channelNot: z.enum(["dev", "alt", "main"]).optional(),
+  contentType: z.array(z.string()).optional(),
+  urlPattern: z.string().optional(),
+  titlePattern: z.string().optional(),
+  messagePattern: z.string().optional(),
+  descriptionPattern: z.string().optional(),
+  reason: z.string().min(1),
+});
+
+export const suppressionsConfigSchema = z.object({
+  suppressions: z.array(suppressionRuleSchema),
+});
+
+export type SuppressionRule = z.infer<typeof suppressionRuleSchema>;
+export type SuppressionsConfig = z.infer<typeof suppressionsConfigSchema>;
+
+export interface SuppressedBy {
+  ruleIndex: number;
+  ruleId: string;
+  category: string;
+  reason: string;
+}
+
+export type SuppressedFinding = Finding & {
+  suppressed?: boolean;
+  suppressedBy?: SuppressedBy;
+};
+
+export const WORKSHOP_SUPPRESSIONS_PATH = "systems/axiom-suppressions.yaml";
+export const WORKPIECE_SUPPRESSIONS_PATH = "axiom-suppressions.yaml";
+
+export function parseSuppressionsConfig(content: string): SuppressionsConfig {
+  const raw = parseYaml(content) as unknown;
+  return suppressionsConfigSchema.parse(raw);
+}
+
+export function loadWorkshopSuppressions(workspaceRoot: string): SuppressionsConfig | undefined {
+  const absPath = join(workspaceRoot, WORKSHOP_SUPPRESSIONS_PATH);
+  if (!existsSync(absPath)) return undefined;
+  const content = readFileSync(absPath, "utf-8");
+  return parseSuppressionsConfig(content);
+}
+
+export function loadWorkpieceSuppressions(missionDir: string): SuppressionsConfig | undefined {
+  const absPath = join(missionDir, "workpiece", WORKPIECE_SUPPRESSIONS_PATH);
+  if (!existsSync(absPath)) return undefined;
+  const content = readFileSync(absPath, "utf-8");
+  return parseSuppressionsConfig(content);
+}
+
+export function mergeSuppressions(
+  workshop: SuppressionsConfig | undefined,
+  workpiece: SuppressionsConfig | undefined,
+): SuppressionRule[] {
+  const workshopRules = workshop?.suppressions ?? [];
+  const workpieceRules = workpiece?.suppressions ?? [];
+  // Per-site rules can only ADD new suppressions — they cannot remove workshop-level rules.
+  // Concatenation is sufficient: workshop rules fire first, workpiece rules fire for
+  // findings not already suppressed by workshop rules (first-match-wins in applySuppressions).
+  return [...workshopRules, ...workpieceRules];
+}
+
+function matchesCondition(
+  finding: Finding,
+  rule: SuppressionRule,
+  context: { channel: string },
+): boolean {
+  // ruleId must match
+  if (finding.ruleId !== rule.ruleId) return false;
+
+  // channel: suppress if context.channel === channel
+  if (rule.channel !== undefined && context.channel !== rule.channel) return false;
+
+  // channelNot: suppress if context.channel !== channelNot
+  if (rule.channelNot !== undefined && context.channel === rule.channelNot) return false;
+
+  // contentType: suppress if the finding's URL ends with one of the listed extensions
+  if (rule.contentType !== undefined && rule.contentType.length > 0) {
+    const url = finding.affectedSubjectId;
+    const matched = rule.contentType.some((ext) => url.endsWith(ext));
+    if (!matched) return false;
+  }
+
+  // urlPattern: suppress if the finding's URL matches the regex
+  if (rule.urlPattern !== undefined) {
+    try {
+      const regex = new RegExp(rule.urlPattern);
+      if (!regex.test(finding.affectedSubjectId)) return false;
+    } catch {
+      return false;
+    }
+  }
+
+  // titlePattern: suppress if the finding's title contains the pattern (substring match)
+  if (rule.titlePattern !== undefined) {
+    if (!finding.title.includes(rule.titlePattern)) return false;
+  }
+
+  // messagePattern: suppress if the finding's message contains the pattern (substring match)
+  if (rule.messagePattern !== undefined) {
+    const message = extractMessage(finding);
+    if (message === undefined || !message.includes(rule.messagePattern)) return false;
+  }
+
+  // descriptionPattern: suppress if the finding's description contains the pattern (substring match)
+  if (rule.descriptionPattern !== undefined) {
+    const description = extractDescription(finding);
+    if (description === undefined || !description.includes(rule.descriptionPattern)) return false;
+  }
+
+  return true;
+}
+
+function extractMessage(finding: Finding): string | undefined {
+  const ext = finding.extension as Record<string, unknown> | undefined;
+  if (ext && typeof ext.message === "string") return ext.message;
+  return undefined;
+}
+
+function extractDescription(finding: Finding): string | undefined {
+  const ext = finding.extension as Record<string, unknown> | undefined;
+  if (ext && typeof ext.description === "string") return ext.description;
+  return undefined;
+}
+
+export function applySuppressions(
+  findings: Finding[],
+  rules: SuppressionRule[],
+  context: { channel: string },
+): SuppressedFinding[] {
+  return findings.map((finding) => {
+    // If already suppressed, keep as-is
+    if ((finding as SuppressedFinding).suppressed) return finding;
+
+    for (let i = 0; i < rules.length; i++) {
+      const rule = rules[i];
+      if (matchesCondition(finding, rule, context)) {
+        return {
+          ...finding,
+          suppressed: true,
+          suppressedBy: {
+            ruleIndex: i,
+            ruleId: rule.ruleId,
+            category: rule.category,
+            reason: rule.reason,
+          },
+        } as SuppressedFinding;
+      }
+    }
+
+    return finding;
+  });
+}
+
+export function countSuppressedByCategory(findings: SuppressedFinding[]): {
+  totalSuppressed: number;
+  byCategory: Record<string, number>;
+} {
+  let totalSuppressed = 0;
+  const byCategory: Record<string, number> = {};
+
+  for (const f of findings) {
+    if (f.suppressed && f.suppressedBy) {
+      totalSuppressed++;
+      byCategory[f.suppressedBy.category] = (byCategory[f.suppressedBy.category] ?? 0) + 1;
+    }
+  }
+
+  return { totalSuppressed, byCategory };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Package barrel for @warpgogol/werkstatt-shared — stack-agnostic shared infrastructure extracted from werkstatt-site (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not export site-specific validators, Astro components, or stack plugin logic.</item>
+  <item>Do not import from @warpgogol/werkstatt-site or any stack plugin.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: initial extraction from werkstatt-site.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./checks/index.ts";

package/src/integration/README.md

@@ -0,0 +1,38 @@
+# `@warpgogol/share/integration`
+
+Vendor-agnostic lead/event delivery: normalize a captured lead into an `IntegrationEvent`, deliver it reliably, and route it to the client's own destinations (CRM/channels) **executing inside the client's site with the client's tokens**. The studio never becomes a CRM and never holds a destination token.
+
+Full architecture + the EU-residency argument: **[`docs/specs/integration-delivery.md`](../../../../docs/specs/integration-delivery.md)**. Governing RFCs: 0168, 0176, 0177, 0179, 0180, **0181**.
+
+## Modules
+
+| File | Role |
+| --- | --- |
+| `port.ts` | `IntegrationEvent`, `Lead`, `DestinationAdapter`, secrets bag. The contracts. |
+| `port-barrel.ts` | Types-only barrel (`@warpgogol/share/integration/port`) — re-exports port + sibling type modules without pulling in adapter implementations. Type-only consumers (agent-gate, supabase-crm tests) import from here. |
+| `index.ts` | Full barrel (`@warpgogol/share/integration`) — types + runtime (registries, fan-out, delivery handler). |
+| `orchestration.ts` | Registries + `routeEventToReady`, `authenticateInbound`. |
+| `delivery-handler.ts` | `createDeliveryHandler` — QStash delivery callback factory. |
+| `qstash.ts` | **EU delivery substrate (RFC-0181):** `buildQstashPublish` (→ Upstash QStash EU), `IdempotencyLedger` / `restRedisLedger` (→ Upstash Redis EU). |
+| `dispatch.ts` | `executeDispatch` — the site-side route body that runs destinations with the client's tokens. |
+| `sharding.ts` | RFC-0179 CF-queue placement — **superseded for the EU path by RFC-0181** (retained, not used for EU delivery). |
+| `adapters.ts` | Channel + Pipedrive destination adapters. |
+
+## Delivery flow (EU)
+
+1. A source publishes an `IntegrationEvent` to **Upstash QStash (EU)** via `buildQstashPublish` (dedup on `eventId`, N retries).
+2. QStash delivers a **signed webhook** to the site's `POST /internal/integration-route`.
+3. The route verifies the QStash signature, checks `restRedisLedger.firstSeen(eventId)` (Upstash Redis EU), then `executeDispatch` routes to the client's destinations.
+4. `200` acks; a non-2xx triggers QStash retry → DLQ.
+
+## EU residency — say it accurately
+
+Physical EU residency (Frankfurt, eu-central-1) + DPA/SCC/EU-U.S. DPF: **yes**. Structural sovereignty: **no** — Upstash is US-incorporated (CLOUD Act exposure closed contractually, not structurally). Never claim "no US access". See the spec for the exact wording and the tier-2 (EU-incorporated/self-hosted) path.
+
+## Secrets (server-only, never committed)
+
+`UPSTASH_QSTASH_URL`, `UPSTASH_QSTASH_TOKEN`, `UPSTASH_QSTASH_CURRENT_SIGNING_KEY`, `UPSTASH_QSTASH_NEXT_SIGNING_KEY`, `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN`, plus each destination's tokens (e.g. `INTEGRATION_PIPEDRIVE_API_TOKEN`) and `INTEGRATION_INBOUND_SECRET`. Read via `astro:env/server`; provide through untracked `.env` / deploy secrets only.
+
+## Tests
+
+`node --import tsx --test src/integration/tests/*.test.ts` (run via `pnpm --filter @warpgogol/share test`). Covers QStash publish + Redis ledger, the dispatch seam, sharding, and the inbound/route runtime.

package/src/integration/adapters.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0168/0181: reference Integration Port adapters. Channel adapters (Telegram, WhatsApp
+Cloud API) and a CRM adapter (Pipedrive). Each is fetch-based, secret-driven, and self-disables when
+its required secrets are absent. Email is NOT a fetch adapter — it is sent via Cloudflare Email
+Routing (send_email binding) in the delivery callback (RFC-0181).</purpose>
+<non-goals>
+  <item>Do not import vendor SDKs or astro:env — fetch + injected secrets only.</item>
+  <item>Do not log or echo secrets.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0168: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  CrmAdapter,
+  DestinationAdapter,
+  IntegrationChannelAdapter,
+  IntegrationEvent,
+  IntegrationSecrets,
+  Lead,
+  LeadMessage,
+} from "./port.ts";
+import { eventToLead } from "./port.ts";
+
+function formatMessageText(message: LeadMessage): string {
+  return [
+    "Neue Kontaktanfrage (send-message)",
+    `Formular: ${message.formId}`,
+    `Sprache: ${message.locale}`,
+    `Zeit: ${message.submittedAt}`,
+    "",
+    message.message,
+  ].join("\n");
+}
+
+export const telegramChannelAdapter: IntegrationChannelAdapter = {
+  id: "telegram",
+  requiredSecrets: ["INTEGRATION_TELEGRAM_BOT_TOKEN", "INTEGRATION_TELEGRAM_CHAT_ID"],
+  async deliver(message: LeadMessage, secrets: IntegrationSecrets): Promise<void> {
+    const token = secrets.INTEGRATION_TELEGRAM_BOT_TOKEN;
+    const chatId = secrets.INTEGRATION_TELEGRAM_CHAT_ID;
+    if (!token || !chatId) throw new Error("telegram: missing credentials");
+    const res = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ chat_id: chatId, text: formatMessageText(message) }),
+    });
+    if (!res.ok) throw new Error(`telegram: API ${res.status}`);
+  },
+};
+
+// RFC-0181: the Resend email channel adapter was removed. Email notifications are
+// sent via Cloudflare Email Routing (the `send_email` Worker binding), handled in the
+// delivery callback route — not as a fetch+secret channel adapter. See the email
+// notification step in chat-widget-section.delivery.api.ts and docs/specs/integration-delivery.md.
+
+export const whatsappChannelAdapter: IntegrationChannelAdapter = {
+  id: "whatsapp",
+  requiredSecrets: [
+    "INTEGRATION_WHATSAPP_TOKEN",
+    "INTEGRATION_WHATSAPP_PHONE_ID",
+    "INTEGRATION_WHATSAPP_TO",
+  ],
+  async deliver(message: LeadMessage, secrets: IntegrationSecrets): Promise<void> {
+    const token = secrets.INTEGRATION_WHATSAPP_TOKEN;
+    const phoneId = secrets.INTEGRATION_WHATSAPP_PHONE_ID;
+    const to = secrets.INTEGRATION_WHATSAPP_TO;
+    if (!token || !phoneId || !to) throw new Error("whatsapp: missing credentials");
+    const res = await fetch(`https://graph.facebook.com/v21.0/${phoneId}/messages`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        messaging_product: "whatsapp",
+        to,
+        type: "text",
+        text: { body: formatMessageText(message) },
+      }),
+    });
+    if (!res.ok) throw new Error(`whatsapp: Cloud API ${res.status}`);
+  },
+};
+
+export const pipedriveCrmAdapter: CrmAdapter = {
+  id: "pipedrive",
+  requiredSecrets: ["INTEGRATION_PIPEDRIVE_API_TOKEN", "INTEGRATION_PIPEDRIVE_DOMAIN"],
+  async upsertLead(lead: Lead, secrets: IntegrationSecrets): Promise<{ id: string } | null> {
+    const token = secrets.INTEGRATION_PIPEDRIVE_API_TOKEN;
+    const domain = secrets.INTEGRATION_PIPEDRIVE_DOMAIN;
+    if (!token || !domain) throw new Error("pipedrive: missing credentials");
+    // Create a person first (leads require a linked person/organization in Pipedrive).
+    const personRes = await fetch(
+      `https://${domain}.pipedrive.com/api/v1/persons?api_token=${encodeURIComponent(token)}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          name: lead.name ?? lead.email ?? lead.phone ?? "Website lead",
+          ...(lead.email ? { email: [lead.email] } : {}),
+          ...(lead.phone ? { phone: [lead.phone] } : {}),
+        }),
+      },
+    );
+    if (!personRes.ok) throw new Error(`pipedrive: persons API ${personRes.status}`);
+    const personJson = (await personRes.json()) as { data?: { id?: number } };
+    const personId = personJson.data?.id;
+    if (!personId) return null;
+
+    const leadRes = await fetch(
+      `https://${domain}.pipedrive.com/api/v1/leads?api_token=${encodeURIComponent(token)}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          title: `${lead.source}: ${lead.name ?? "lead"}`,
+          person_id: personId,
+        }),
+      },
+    );
+    if (!leadRes.ok) throw new Error(`pipedrive: leads API ${leadRes.status}`);
+    const leadJson = (await leadRes.json()) as { data?: { id?: string } };
+    return leadJson.data?.id ? { id: String(leadJson.data.id) } : null;
+  },
+};
+
+/**
+ * RFC-0176: Pipedrive as a destination-hub adapter (kind `crm`, mode `gogol-adapter`).
+ * Runs on the client's site with the client's token. Reuses the RFC-0168
+ * pipedriveCrmAdapter by mapping the normalized IntegrationEvent → Lead.
+ */
+export const pipedriveDestinationAdapter: DestinationAdapter = {
+  kind: "crm",
+  vendor: "pipedrive",
+  requiredSecrets: pipedriveCrmAdapter.requiredSecrets,
+  async route(
+    event: IntegrationEvent,
+    secrets: IntegrationSecrets,
+  ): Promise<{ id: string } | null> {
+    return pipedriveCrmAdapter.upsertLead(eventToLead(event), secrets);
+  },
+};