@skillsmith/core 0.5.5 → 0.5.6

package/dist/webhooks/WebhookDeadLetterRepository.d.ts

@@ -0,0 +1,178 @@
+/**
+ * SMI-4291 / SMI-4308: WebhookDeadLetterRepository
+ *
+ * Thin persistence layer over the `webhook_dead_letters` table
+ * (migrations 070 + 077). Used by the WebhookQueue deadLetterSink wiring
+ * and by the `webhook-dlq` edge function.
+ *
+ * Plans:
+ *   - docs/internal/implementation/github-wave-4-webhook-dlq.md
+ *   - docs/internal/implementation/smi-4308-webhook-dlq-retry-real-enqueue.md
+ *
+ * Current operations (three terminal states: never-touched / retried / resolved):
+ *  - insertDeadLetter(item, reason, teamId)        — sink path
+ *  - listOpen(teamId)                              — edge fn GET + repo consumers
+ *  - listUnretried(teamId)                         — DEPRECATED alias for listOpen
+ *                                                    (kept for SMI-4322's delivery worker)
+ *  - markRetried(id, success)                      — reserved for SMI-4322 delivery worker
+ *  - markResolved(id, resolvedBy?)                 — operator acknowledgement (edge fn)
+ *
+ * No `audit_logs` emission is performed by this repository (plan-review finding
+ * C2: cross-tenant exposure risk on the global-read RLS of `audit_logs`). The
+ * edge function emits `webhook:dlq_resolved` for operator actions — see
+ * plan-review finding C-03 — because those writes are team-scoped.
+ */
+import type { WebhookQueueItem } from './WebhookQueue.types.js';
+/**
+ * Minimal Supabase-client shape this repository depends on. We avoid
+ * importing `@supabase/supabase-js` directly so the module stays usable
+ * from Deno edge functions, Node services, and tests with a fake client.
+ */
+export interface SupabaseLikeClient {
+    from(table: string): {
+        insert(row: Record<string, unknown>): Promise<{
+            error: {
+                message: string;
+            } | null;
+        }>;
+        select(columns: string): {
+            eq(column: string, value: string): {
+                order(column: string, opts?: {
+                    ascending?: boolean;
+                }): Promise<{
+                    data: DeadLetterRow[] | null;
+                    error: {
+                        message: string;
+                    } | null;
+                }>;
+            };
+            single?: () => Promise<{
+                data: DeadLetterRow | null;
+                error: {
+                    message: string;
+                } | null;
+            }>;
+        };
+        update(row: Record<string, unknown>): {
+            eq(column: string, value: string): Promise<{
+                data: DeadLetterRow | null;
+                error: {
+                    message: string;
+                } | null;
+            }>;
+        };
+    };
+}
+export interface DeadLetterRow {
+    id: string;
+    original_event_id: string;
+    endpoint_url: string;
+    payload: Record<string, unknown>;
+    failure_reason: string;
+    attempt_count: number;
+    first_failed_at: string;
+    last_failed_at: string;
+    retried_at: string | null;
+    retry_success: boolean | null;
+    resolved_at: string | null;
+    resolved_by: string | null;
+    team_id: string;
+    created_at: string;
+}
+export interface InsertDeadLetterInput {
+    originalEventId: string;
+    endpointUrl: string;
+    payload: Record<string, unknown>;
+    failureReason: string;
+    attemptCount: number;
+    firstFailedAt: Date | string;
+    lastFailedAt?: Date | string;
+    teamId: string;
+}
+/**
+ * WebhookDeadLetterRepository — single-table CRUD wrapper.
+ *
+ * Instances are stateless beyond the client reference; construct freely per
+ * request in edge functions and once per process in long-lived services.
+ */
+export declare class WebhookDeadLetterRepository {
+    private readonly client;
+    constructor(client: SupabaseLikeClient);
+    /**
+     * Persist a dead-letter row for an exhausted queue item.
+     *
+     * Validates `endpoint_url` length at the application layer so the DB
+     * CHECK constraint is never hit in practice; a row that would violate the
+     * check throws a sanitized error without the payload.
+     *
+     * SMI-4307 F-03/F-02: When `input.teamId` is null or empty, the caller is an
+     * Individual-tier user (or a user whose team has not been provisioned yet).
+     * `webhook_dead_letters.team_id` is NOT NULL and RLS is team-scoped, so an
+     * insert would fail the FK/CHECK or land unreachable for its owner.
+     * Short-circuit instead: emit a console warning for ops visibility and
+     * return. A follow-on issue can promote this to an `audit_logs` write if
+     * orphan-DLQ observability becomes operationally valuable.
+     *
+     * F-02 overload note: the guard uses `input.teamId` (already resolved by the
+     * caller). Do NOT call `user_team_ids()` from here — the SMI-4309 overload
+     * collision between migrations 070 and 071 makes any such call brittle.
+     */
+    insertDeadLetter(input: InsertDeadLetterInput): Promise<void>;
+    /**
+     * List open DLQ rows for a team — rows that are neither retried nor
+     * operator-resolved. Ordered by `last_failed_at` descending so fresh
+     * failures surface first.
+     *
+     * RLS guarantees cross-team isolation; the `team_id` filter below is a
+     * belt-and-braces server-side refinement for service-role callers.
+     *
+     * SMI-4308 H-03: the in-process filter now checks both terminal columns.
+     * Prior to this change the filter only checked `retried_at === null`, so
+     * resolved rows would have leaked into `listUnretried` results once the
+     * /resolve path landed.
+     */
+    listOpen(teamId: string): Promise<DeadLetterRow[]>;
+    /**
+     * @deprecated SMI-4308 — use {@link listOpen}. Retained because the
+     * dormant WebhookQueue sink wiring (SMI-4322) will call this through an
+     * older API contract. Removed once SMI-4322 lands.
+     */
+    listUnretried(teamId: string): Promise<DeadLetterRow[]>;
+    /**
+     * Mark a DLQ row as retried. Three-state `retry_success` semantics:
+     *  - true  — retry succeeded (item re-entered the queue and drained)
+     *  - false — retry failed (item re-entered the queue and was re-deadlettered)
+     *
+     * NULL is reserved for rows that have never been retried; this method
+     * never writes NULL.
+     *
+     * SMI-4308 status: dormant in production until SMI-4322 ships the
+     * outbound delivery worker. The shipped edge function uses
+     * {@link markResolved} instead.
+     */
+    markRetried(id: string, success: boolean): Promise<void>;
+    /**
+     * Mark a DLQ row as operator-resolved (SMI-4308). The row is
+     * acknowledged out-of-band; no automated re-delivery took place. `retried_at`
+     * and `retry_success` are left NULL so the three-state retry semantic stays
+     * clean for the future delivery worker (SMI-4322).
+     *
+     * `resolvedBy` is typically the auth.users.id of the operator; when the
+     * edge function cannot extract the `sub` claim from the caller JWT, it
+     * passes `undefined` and the column is set to NULL (the RLS policy has
+     * already scoped the row to the caller's team).
+     */
+    markResolved(id: string, resolvedBy?: string): Promise<void>;
+    /**
+     * Build a sink function compatible with `WebhookQueueOptions.deadLetterSink`.
+     *
+     * The sink captures `teamId` and a payload-extraction strategy so the
+     * WebhookQueue stays decoupled from Supabase.
+     */
+    makeSink(opts: {
+        teamId: string;
+        extractEndpointUrl: (item: WebhookQueueItem) => string;
+        extractPayload?: (item: WebhookQueueItem) => Record<string, unknown>;
+    }): (item: WebhookQueueItem, reason: string) => Promise<void>;
+}
+//# sourceMappingURL=WebhookDeadLetterRepository.d.ts.map

package/dist/webhooks/WebhookDeadLetterRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebhookDeadLetterRepository.d.ts","sourceRoot":"","sources":["../../src/webhooks/WebhookDeadLetterRepository.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/WebhookDeadLetterRepository.js

@@ -0,0 +1,196 @@
+/**
+ * SMI-4291 / SMI-4308: WebhookDeadLetterRepository
+ *
+ * Thin persistence layer over the `webhook_dead_letters` table
+ * (migrations 070 + 077). Used by the WebhookQueue deadLetterSink wiring
+ * and by the `webhook-dlq` edge function.
+ *
+ * Plans:
+ *   - docs/internal/implementation/github-wave-4-webhook-dlq.md
+ *   - docs/internal/implementation/smi-4308-webhook-dlq-retry-real-enqueue.md
+ *
+ * Current operations (three terminal states: never-touched / retried / resolved):
+ *  - insertDeadLetter(item, reason, teamId)        — sink path
+ *  - listOpen(teamId)                              — edge fn GET + repo consumers
+ *  - listUnretried(teamId)                         — DEPRECATED alias for listOpen
+ *                                                    (kept for SMI-4322's delivery worker)
+ *  - markRetried(id, success)                      — reserved for SMI-4322 delivery worker
+ *  - markResolved(id, resolvedBy?)                 — operator acknowledgement (edge fn)
+ *
+ * No `audit_logs` emission is performed by this repository (plan-review finding
+ * C2: cross-tenant exposure risk on the global-read RLS of `audit_logs`). The
+ * edge function emits `webhook:dlq_resolved` for operator actions — see
+ * plan-review finding C-03 — because those writes are team-scoped.
+ */
+/**
+ * Coerce a Date|string to an ISO string suitable for TIMESTAMPTZ columns.
+ */
+function toIso(value) {
+    if (!value)
+        return new Date().toISOString();
+    return value instanceof Date ? value.toISOString() : value;
+}
+/**
+ * WebhookDeadLetterRepository — single-table CRUD wrapper.
+ *
+ * Instances are stateless beyond the client reference; construct freely per
+ * request in edge functions and once per process in long-lived services.
+ */
+export class WebhookDeadLetterRepository {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Persist a dead-letter row for an exhausted queue item.
+     *
+     * Validates `endpoint_url` length at the application layer so the DB
+     * CHECK constraint is never hit in practice; a row that would violate the
+     * check throws a sanitized error without the payload.
+     *
+     * SMI-4307 F-03/F-02: When `input.teamId` is null or empty, the caller is an
+     * Individual-tier user (or a user whose team has not been provisioned yet).
+     * `webhook_dead_letters.team_id` is NOT NULL and RLS is team-scoped, so an
+     * insert would fail the FK/CHECK or land unreachable for its owner.
+     * Short-circuit instead: emit a console warning for ops visibility and
+     * return. A follow-on issue can promote this to an `audit_logs` write if
+     * orphan-DLQ observability becomes operationally valuable.
+     *
+     * F-02 overload note: the guard uses `input.teamId` (already resolved by the
+     * caller). Do NOT call `user_team_ids()` from here — the SMI-4309 overload
+     * collision between migrations 070 and 071 makes any such call brittle.
+     */
+    async insertDeadLetter(input) {
+        if (!input.teamId || input.teamId.length === 0) {
+            console.warn('webhook-dlq: skipping DLQ insert — no teamId (orphan event)', {
+                originalEventId: input.originalEventId,
+                failureReason: input.failureReason,
+                attemptCount: input.attemptCount,
+            });
+            return;
+        }
+        const endpointUrl = input.endpointUrl ?? '';
+        if (endpointUrl.length === 0 || endpointUrl.length > 2048) {
+            throw new Error(`webhook-dlq: endpoint_url length ${endpointUrl.length} outside [1, 2048]`);
+        }
+        if (input.attemptCount < 1 || !Number.isInteger(input.attemptCount)) {
+            throw new Error(`webhook-dlq: attempt_count must be a positive integer (got ${input.attemptCount})`);
+        }
+        const row = {
+            original_event_id: input.originalEventId,
+            endpoint_url: endpointUrl,
+            payload: input.payload,
+            failure_reason: input.failureReason,
+            attempt_count: input.attemptCount,
+            first_failed_at: toIso(input.firstFailedAt),
+            last_failed_at: toIso(input.lastFailedAt),
+            team_id: input.teamId,
+        };
+        const { error } = await this.client.from('webhook_dead_letters').insert(row);
+        if (error) {
+            throw new Error(`webhook-dlq: insert failed: ${error.message}`);
+        }
+    }
+    /**
+     * List open DLQ rows for a team — rows that are neither retried nor
+     * operator-resolved. Ordered by `last_failed_at` descending so fresh
+     * failures surface first.
+     *
+     * RLS guarantees cross-team isolation; the `team_id` filter below is a
+     * belt-and-braces server-side refinement for service-role callers.
+     *
+     * SMI-4308 H-03: the in-process filter now checks both terminal columns.
+     * Prior to this change the filter only checked `retried_at === null`, so
+     * resolved rows would have leaked into `listUnretried` results once the
+     * /resolve path landed.
+     */
+    async listOpen(teamId) {
+        const { data, error } = await this.client
+            .from('webhook_dead_letters')
+            .select('*')
+            .eq('team_id', teamId)
+            .order('last_failed_at', { ascending: false });
+        if (error) {
+            throw new Error(`webhook-dlq: list failed: ${error.message}`);
+        }
+        return (data ?? []).filter((row) => row.retried_at === null && row.resolved_at === null);
+    }
+    /**
+     * @deprecated SMI-4308 — use {@link listOpen}. Retained because the
+     * dormant WebhookQueue sink wiring (SMI-4322) will call this through an
+     * older API contract. Removed once SMI-4322 lands.
+     */
+    async listUnretried(teamId) {
+        return this.listOpen(teamId);
+    }
+    /**
+     * Mark a DLQ row as retried. Three-state `retry_success` semantics:
+     *  - true  — retry succeeded (item re-entered the queue and drained)
+     *  - false — retry failed (item re-entered the queue and was re-deadlettered)
+     *
+     * NULL is reserved for rows that have never been retried; this method
+     * never writes NULL.
+     *
+     * SMI-4308 status: dormant in production until SMI-4322 ships the
+     * outbound delivery worker. The shipped edge function uses
+     * {@link markResolved} instead.
+     */
+    async markRetried(id, success) {
+        const { error } = await this.client
+            .from('webhook_dead_letters')
+            .update({
+            retried_at: new Date().toISOString(),
+            retry_success: success,
+        })
+            .eq('id', id);
+        if (error) {
+            throw new Error(`webhook-dlq: markRetried failed: ${error.message}`);
+        }
+    }
+    /**
+     * Mark a DLQ row as operator-resolved (SMI-4308). The row is
+     * acknowledged out-of-band; no automated re-delivery took place. `retried_at`
+     * and `retry_success` are left NULL so the three-state retry semantic stays
+     * clean for the future delivery worker (SMI-4322).
+     *
+     * `resolvedBy` is typically the auth.users.id of the operator; when the
+     * edge function cannot extract the `sub` claim from the caller JWT, it
+     * passes `undefined` and the column is set to NULL (the RLS policy has
+     * already scoped the row to the caller's team).
+     */
+    async markResolved(id, resolvedBy) {
+        const { error } = await this.client
+            .from('webhook_dead_letters')
+            .update({
+            resolved_at: new Date().toISOString(),
+            resolved_by: resolvedBy ?? null,
+        })
+            .eq('id', id);
+        if (error) {
+            throw new Error(`webhook-dlq: markResolved failed: ${error.message}`);
+        }
+    }
+    /**
+     * Build a sink function compatible with `WebhookQueueOptions.deadLetterSink`.
+     *
+     * The sink captures `teamId` and a payload-extraction strategy so the
+     * WebhookQueue stays decoupled from Supabase.
+     */
+    makeSink(opts) {
+        return async (item, reason) => {
+            await this.insertDeadLetter({
+                originalEventId: item.id,
+                endpointUrl: opts.extractEndpointUrl(item),
+                payload: opts.extractPayload
+                    ? opts.extractPayload(item)
+                    : { repoFullName: item.repoFullName, filePath: item.filePath, commitSha: item.commitSha },
+                failureReason: reason,
+                attemptCount: Math.max(1, (item.retries ?? 0) + 1),
+                firstFailedAt: new Date(item.timestamp),
+                lastFailedAt: new Date(),
+                teamId: opts.teamId,
+            });
+        };
+    }
+}
+//# sourceMappingURL=WebhookDeadLetterRepository.js.map

package/dist/webhooks/WebhookDeadLetterRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebhookDeadLetterRepository.js","sourceRoot":"","sources":["../../src/webhooks/WebhookDeadLetterRepository.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/WebhookHandler.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SMI-645: WebhookHandler - Process incoming GitHub webhook events
+ *
+ * Provides:
+ * - Secure HMAC-SHA256 signature verification
+ * - Event type routing
+ * - SKILL.md change detection
+ * - Integration with WebhookQueue for processing
+ */
+import type { SignatureVerificationResult, SkillFileChange } from './WebhookPayload.js';
+import type { WebhookQueue } from './WebhookQueue.js';
+/**
+ * Webhook handler options
+ */
+export interface WebhookHandlerOptions {
+    /**
+     * GitHub webhook secret for signature verification
+     */
+    secret: string;
+    /**
+     * Queue for processing webhook events
+     */
+    queue: WebhookQueue;
+    /**
+     * Optional callback when a skill change is detected
+     */
+    onSkillChange?: (change: SkillFileChange) => void;
+    /**
+     * Optional callback for logging
+     */
+    onLog?: (level: 'info' | 'warn' | 'error', message: string, data?: unknown) => void;
+}
+/**
+ * Result of handling a webhook event
+ */
+export interface WebhookHandleResult {
+    /**
+     * Whether the webhook was handled successfully
+     */
+    success: boolean;
+    /**
+     * Event type that was processed
+     */
+    eventType: string;
+    /**
+     * Number of skill changes detected (for push events)
+     */
+    changesDetected: number;
+    /**
+     * Number of items queued for processing
+     */
+    itemsQueued: number;
+    /**
+     * Error message if processing failed
+     */
+    error?: string;
+    /**
+     * Message describing what happened
+     */
+    message: string;
+}
+/**
+ * Delivery statistics for monitoring
+ */
+export interface DeliveryStats {
+    trackedDeliveries: number;
+}
+/**
+ * Webhook handler for GitHub events
+ */
+export declare class WebhookHandler {
+    private secret;
+    private queue;
+    private onSkillChange?;
+    private log;
+    /**
+     * Track processed delivery IDs for idempotency
+     * Using a Set for O(1) lookups
+     */
+    private processedDeliveries;
+    constructor(options: WebhookHandlerOptions);
+    /**
+     * Get delivery tracking statistics
+     */
+    getDeliveryStats(): DeliveryStats;
+    /**
+     * Verify webhook signature using HMAC-SHA256
+     * Uses timing-safe comparison to prevent timing attacks
+     */
+    verifySignature(payload: string, signature: string): SignatureVerificationResult;
+    /**
+     * Handle an incoming webhook event
+     * @param eventType - GitHub event type (push, repository, ping, etc.)
+     * @param payload - Raw JSON payload string
+     * @param signature - X-Hub-Signature-256 header value
+     * @param deliveryId - X-GitHub-Delivery header value (optional, for idempotency)
+     */
+    handleWebhook(eventType: string, payload: string, signature: string, deliveryId?: string): Promise<WebhookHandleResult>;
+    /**
+     * Process a parsed webhook event
+     */
+    private processEvent;
+    /**
+     * Handle push events - detect SKILL.md changes
+     */
+    private handlePushEvent;
+    /**
+     * Handle repository events - handle deletion/archival
+     */
+    private handleRepositoryEvent;
+    /**
+     * Calculate priority based on repository metrics
+     */
+    private calculatePriority;
+}
+export default WebhookHandler;
+//# sourceMappingURL=WebhookHandler.d.ts.map

package/dist/webhooks/WebhookHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebhookHandler.d.ts","sourceRoot":"","sources":["../../src/webhooks/WebhookHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAIV,2BAA2B,EAC3B,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,mBAAmB,CAAA;AAEvE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,KAAK,EAAE,YAAY,CAAA;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAA;IAEjD;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACpF;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAYD;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAmC;IACzD,OAAO,CAAC,GAAG,CAA6E;IAExF;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAoB;gBAEnC,OAAO,EAAE,qBAAqB;IAO1C;;OAEG;IACH,gBAAgB,IAAI,aAAa;IAMjC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,2BAA2B;IAqChF;;;;;;OAMG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC;IAiE/B;;OAEG;YACW,YAAY;IAiC1B;;OAEG;YACW,eAAe;IAmE7B;;OAEG;YACW,qBAAqB;IAqGnC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAgB1B;AAED,eAAe,cAAc,CAAA"}