@generacy-ai/orchestrator 0.0.0-preview-20260304013206

package/dist/services/smee-receiver.js

@@ -0,0 +1,225 @@
+/**
+ * Receives GitHub webhook events from a smee.io channel via SSE.
+ * Feeds label events directly into the LabelMonitorService.
+ */
+export class SmeeWebhookReceiver {
+    logger;
+    monitorService;
+    static BASE_RECONNECT_DELAY_MS = 5000;
+    static MAX_BACKOFF_MS = 300000; // 5 minutes
+    channelUrl;
+    watchedRepos;
+    baseReconnectDelayMs;
+    abortController = null;
+    running = false;
+    reconnectAttempt = 0;
+    constructor(logger, monitorService, options) {
+        this.logger = logger;
+        this.monitorService = monitorService;
+        this.channelUrl = options.channelUrl;
+        this.watchedRepos = options.watchedRepos;
+        this.baseReconnectDelayMs = options.baseReconnectDelayMs ?? SmeeWebhookReceiver.BASE_RECONNECT_DELAY_MS;
+    }
+    /**
+     * Start listening to the smee.io channel.
+     * Automatically reconnects on disconnect.
+     */
+    async start() {
+        if (this.running) {
+            this.logger.warn('Smee receiver already running');
+            return;
+        }
+        this.running = true;
+        this.abortController = new AbortController();
+        const { signal } = this.abortController;
+        this.logger.info({ channelUrl: this.channelUrl, watchedRepos: [...this.watchedRepos] }, 'Starting smee.io webhook receiver');
+        while (this.running && !signal.aborted) {
+            try {
+                await this.connect(signal);
+                // Reset backoff counter on successful connection
+                this.reconnectAttempt = 0;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                const reconnectMs = this.reconnectDelayMs;
+                this.logger.warn({ err: String(error), reconnectMs, attempt: this.reconnectAttempt }, 'Smee connection lost, reconnecting...');
+                // Increment attempt counter for exponential backoff
+                this.reconnectAttempt++;
+            }
+            // Wait before reconnecting
+            if (this.running && !signal.aborted) {
+                await this.sleep(this.reconnectDelayMs, signal);
+            }
+        }
+        this.running = false;
+        this.logger.info('Smee receiver stopped');
+    }
+    /**
+     * Stop the receiver.
+     */
+    stop() {
+        this.running = false;
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        this.logger.info('Smee receiver stop requested');
+    }
+    /**
+     * Connect to the smee.io channel and process events.
+     */
+    async connect(signal) {
+        const response = await fetch(this.channelUrl, {
+            headers: { Accept: 'text/event-stream' },
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Smee connection failed: ${response.status} ${response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error('Smee response has no body');
+        }
+        this.logger.info('Connected to smee.io channel');
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (!signal.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete SSE events (separated by double newline)
+                const events = buffer.split('\n\n');
+                // Keep the last incomplete chunk in the buffer
+                buffer = events.pop() ?? '';
+                for (const eventBlock of events) {
+                    if (!eventBlock.trim())
+                        continue;
+                    await this.processSSEEvent(eventBlock);
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Parse and process a single SSE event block from smee.io.
+     *
+     * Smee.io SSE events have the format:
+     *   event: message
+     *   data: {"body": <webhook-payload>, "x-github-event": "issues", ...}
+     */
+    async processSSEEvent(eventBlock) {
+        let eventType = '';
+        const dataLines = [];
+        for (const line of eventBlock.split('\n')) {
+            if (line.startsWith('event:')) {
+                eventType = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                dataLines.push(line.slice(5).trim());
+            }
+        }
+        // Only process message events
+        if (eventType !== 'message' && eventType !== '') {
+            // Smee sends 'ready' and 'ping' events — ignore them
+            return;
+        }
+        const dataStr = dataLines.join('\n');
+        if (!dataStr)
+            return;
+        let data;
+        try {
+            data = JSON.parse(dataStr);
+        }
+        catch {
+            return; // Skip malformed events
+        }
+        // Smee wraps the webhook payload in a 'body' field
+        const githubEvent = data['x-github-event'];
+        const body = data['body'];
+        if (!body || githubEvent !== 'issues') {
+            return; // Only interested in issue events
+        }
+        const payload = body;
+        // Only handle "labeled" action
+        if (payload.action !== 'labeled')
+            return;
+        // Check if this is a watched repository
+        if (!payload.repository?.owner?.login || !payload.repository?.name)
+            return;
+        const repoKey = `${payload.repository.owner.login}/${payload.repository.name}`;
+        if (!this.watchedRepos.has(repoKey))
+            return;
+        // Parse and process the label event
+        const issueLabels = payload.issue?.labels?.map(l => l.name) ?? [];
+        const event = this.monitorService.parseLabelEvent(payload.label.name, payload.repository.owner.login, payload.repository.name, payload.issue.number, issueLabels, 'webhook');
+        if (!event) {
+            // If this was a completed:* label that didn't match a waiting-for:*
+            // in the webhook payload, re-fetch from GitHub to handle stale payloads.
+            if (payload.label.name.startsWith('completed:')) {
+                this.logger.info({ label: payload.label.name, repo: repoKey, issue: payload.issue.number }, 'Webhook completed:* label has no matching waiting-for:* in payload, attempting re-fetch');
+                this.monitorService.recordWebhookEvent();
+                try {
+                    await this.monitorService.verifyAndProcessCompletedLabel(payload.repository.owner.login, payload.repository.name, payload.issue.number, payload.label.name);
+                }
+                catch (error) {
+                    this.logger.error({ err: String(error), repo: repoKey, issue: payload.issue.number }, 'Error during completed:* label re-fetch verification');
+                }
+            }
+            return;
+        }
+        this.logger.info({
+            type: event.type,
+            repo: repoKey,
+            issue: event.issueNumber,
+            label: event.labelName,
+        }, 'Smee webhook received label event');
+        // Record webhook event for adaptive polling health tracking
+        this.monitorService.recordWebhookEvent();
+        // Process the event
+        try {
+            await this.monitorService.processLabelEvent(event);
+        }
+        catch (error) {
+            this.logger.error({ err: String(error), repo: repoKey, issue: event.issueNumber }, 'Error processing smee webhook event');
+        }
+    }
+    /**
+     * Get the current reconnect delay based on the number of attempts.
+     * Uses exponential backoff with the current attempt count.
+     */
+    get reconnectDelayMs() {
+        return this.calculateBackoffDelay(this.reconnectAttempt);
+    }
+    /**
+     * Calculate exponential backoff delay for reconnection attempts.
+     * Formula: BASE_RECONNECT_DELAY_MS * 2^attempt, capped at MAX_BACKOFF_MS.
+     * Progression: 5s → 10s → 20s → 40s → 80s → 160s → 300s (capped).
+     *
+     * @param attempt - The current reconnection attempt number (0-indexed)
+     * @returns Delay in milliseconds before next reconnection attempt
+     */
+    calculateBackoffDelay(attempt) {
+        const delay = this.baseReconnectDelayMs * Math.pow(2, attempt);
+        return Math.min(delay, SmeeWebhookReceiver.MAX_BACKOFF_MS);
+    }
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(resolve, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+}
+//# sourceMappingURL=smee-receiver.js.map

package/dist/services/smee-receiver.js.map

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

package/dist/services/webhook-setup-service.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Logger interface matching Pino/Fastify logger shape.
+ *
+ * Supports both simple string messages and structured logging with context objects.
+ */
+interface Logger {
+    /** Log informational message */
+    info(msg: string): void;
+    /** Log informational message with structured context */
+    info(obj: Record<string, unknown>, msg: string): void;
+    /** Log warning message */
+    warn(msg: string): void;
+    /** Log warning message with structured context */
+    warn(obj: Record<string, unknown>, msg: string): void;
+    /** Log error message */
+    error(msg: string): void;
+    /** Log error message with structured context */
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Repository configuration for webhook setup.
+ *
+ * Identifies a GitHub repository by owner and name for webhook management.
+ */
+export interface RepositoryConfig {
+    /** Repository owner (organization or user) */
+    owner: string;
+    /** Repository name */
+    repo: string;
+}
+/**
+ * Minimal GitHub webhook response type.
+ *
+ * Only includes fields needed for matching and reactivation.
+ * See: https://docs.github.com/en/rest/webhooks/repos#list-repository-webhooks
+ */
+export interface GitHubWebhook {
+    /** Webhook ID (unique identifier) */
+    id: number;
+    /** Whether webhook is active (receiving events) */
+    active: boolean;
+    /** Webhook configuration */
+    config: {
+        /** Target URL where webhook events are sent */
+        url: string;
+    };
+    /** Event types webhook subscribes to (e.g., ["issues", "pull_request"]) */
+    events: string[];
+}
+/**
+ * Result of webhook setup for a single repository.
+ *
+ * Captures the action taken and any relevant details or errors.
+ */
+export interface WebhookSetupResult {
+    /** Repository owner (organization or user) */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /**
+     * Action taken during webhook setup
+     * - `created`: New webhook was created
+     * - `skipped`: Active webhook already exists
+     * - `reactivated`: Inactive webhook was reactivated
+     * - `failed`: Setup failed (see `error` field)
+     */
+    action: 'created' | 'skipped' | 'reactivated' | 'failed';
+    /** Webhook ID (present for created/skipped/reactivated, absent for failed) */
+    webhookId?: number;
+    /** Error message (only present when action === 'failed') */
+    error?: string;
+}
+/**
+ * Summary of webhook setup across all repositories.
+ *
+ * Provides aggregate counts and detailed per-repository results.
+ */
+export interface WebhookSetupSummary {
+    /** Total number of repositories checked */
+    total: number;
+    /** Number of webhooks created (new) */
+    created: number;
+    /** Number of webhooks skipped (already active) */
+    skipped: number;
+    /** Number of webhooks reactivated (was inactive) */
+    reactivated: number;
+    /** Number of repositories that failed webhook setup */
+    failed: number;
+    /** Detailed results for each repository */
+    results: WebhookSetupResult[];
+}
+/**
+ * Service for auto-configuring GitHub webhooks for monitored repositories.
+ *
+ * When SMEE_CHANNEL_URL is configured, this service verifies and creates
+ * GitHub webhooks for all monitored repositories on orchestrator startup,
+ * ensuring near-instant label detection via Smee instead of 15-minute polling.
+ *
+ * Features:
+ * - Creates missing webhooks pointing to Smee channel URL
+ * - Skips existing active webhooks (idempotent)
+ * - Reactivates inactive webhooks and merges events
+ * - Graceful error handling (per-repo failures don't block startup)
+ * - Warns on event mismatches without modifying
+ * - Validates Smee URL format (warns on non-smee.io URLs)
+ *
+ * Error Handling:
+ * - 403/404 errors: Logged as warnings, system falls back to polling
+ * - Network/API errors: Logged and continue with next repo
+ * - All errors are non-fatal and don't block orchestrator startup
+ */
+export declare class WebhookSetupService {
+    private readonly _logger;
+    /**
+     * Creates a new WebhookSetupService instance.
+     *
+     * @param logger - Logger instance for structured logging (Pino/Fastify compatible)
+     */
+    constructor(logger: Logger);
+    /**
+     * Ensure webhooks exist for all repositories.
+     *
+     * This is the main entry point for webhook setup. For each repository:
+     * 1. Lists existing webhooks via GitHub API
+     * 2. Checks if a webhook already exists for the Smee channel URL
+     * 3. Creates missing webhooks, reactivates inactive ones, or skips active ones
+     * 4. Logs results and continues on errors (graceful degradation)
+     *
+     * Per-repository errors are logged but don't block the overall process,
+     * allowing partial success when some repositories fail (e.g., due to
+     * insufficient permissions).
+     *
+     * @param smeeChannelUrl - The Smee channel URL to configure webhooks for
+     *                         (e.g., 'https://smee.io/abc123'). URL is validated
+     *                         and a warning is logged if it doesn't point to smee.io.
+     * @param repositories - List of repositories to ensure webhooks for. Each
+     *                       repository is processed sequentially to avoid rate limits.
+     * @returns Promise resolving to a summary of webhook setup results, including
+     *          aggregate counts and detailed per-repository results.
+     *
+     * @example
+     * ```typescript
+     * const service = new WebhookSetupService(logger);
+     * const summary = await service.ensureWebhooks(
+     *   'https://smee.io/abc123',
+     *   [
+     *     { owner: 'myorg', repo: 'myrepo' },
+     *     { owner: 'myorg', repo: 'another-repo' }
+     *   ]
+     * );
+     * console.log(`Created: ${summary.created}, Skipped: ${summary.skipped}, Failed: ${summary.failed}`);
+     * ```
+     *
+     * @see {@link WebhookSetupSummary} for the structure of the returned summary
+     */
+    ensureWebhooks(smeeChannelUrl: string, repositories: RepositoryConfig[]): Promise<WebhookSetupSummary>;
+    /**
+     * Ensure webhook exists for a single repository.
+     *
+     * Internal method that handles webhook verification and setup for one repository.
+     * All errors are caught and converted to a 'failed' result to allow graceful
+     * degradation.
+     *
+     * Logic flow:
+     * 1. List existing webhooks
+     * 2. Find webhook matching the Smee URL (case-insensitive)
+     * 3. If not found: Create new webhook → 'created'
+     * 4. If found and active: Skip → 'skipped' (warn on event mismatch)
+     * 5. If found but inactive: Reactivate and merge events → 'reactivated'
+     *
+     * @param owner - Repository owner (organization or user)
+     * @param repo - Repository name
+     * @param smeeChannelUrl - The Smee channel URL to configure
+     * @returns Promise resolving to the result of webhook setup for this repository
+     *
+     * @throws Never throws - all errors are caught and returned as 'failed' results
+     */
+    private _ensureWebhookForRepo;
+    /**
+     * Find a webhook matching the given URL.
+     *
+     * Uses case-insensitive URL comparison. No URL normalization is performed -
+     * simple string matching after lowercasing both URLs. This means that
+     * 'https://smee.io/ABC' and 'https://smee.io/abc' are considered equal,
+     * but trailing slashes or different protocols would not match.
+     *
+     * @param webhooks - Array of webhooks to search through
+     * @param targetUrl - The URL to match (typically the Smee channel URL)
+     * @returns The first matching webhook, or undefined if none found
+     *
+     * @example
+     * ```typescript
+     * const webhooks = [
+     *   { id: 1, active: true, config: { url: 'https://smee.io/ABC' }, events: ['issues'] }
+     * ];
+     * const match = this._findMatchingWebhook(webhooks, 'https://smee.io/abc');
+     * // Returns the webhook with id: 1
+     * ```
+     */
+    private _findMatchingWebhook;
+    /**
+     * List webhooks for a repository via GitHub API.
+     *
+     * Uses the `gh` CLI to call `GET /repos/{owner}/{repo}/hooks`.
+     * Errors are logged and an empty array is returned for graceful degradation.
+     *
+     * @param owner - Repository owner (organization or user)
+     * @param repo - Repository name
+     * @returns Promise resolving to an array of webhooks (empty array on error)
+     *
+     * @see {@link https://docs.github.com/en/rest/webhooks/repos#list-repository-webhooks}
+     */
+    private _listRepoWebhooks;
+    /**
+     * Create a new webhook for a repository via GitHub API.
+     *
+     * Uses the `gh` CLI to call `POST /repos/{owner}/{repo}/hooks` with:
+     * - `config.url`: The Smee channel URL
+     * - `config.content_type`: 'json'
+     * - `events`: ['issues']
+     * - `active`: true
+     *
+     * @param owner - Repository owner (organization or user)
+     * @param repo - Repository name
+     * @param smeeChannelUrl - The Smee channel URL to configure
+     * @returns Promise resolving to the webhook ID on success
+     * @throws Error if webhook creation fails (caught and logged by caller)
+     *
+     * @see {@link https://docs.github.com/en/rest/webhooks/repos#create-a-repository-webhook}
+     */
+    private _createRepoWebhook;
+    /**
+     * Update an existing webhook (reactivate and/or merge events) via GitHub API.
+     *
+     * Uses the `gh` CLI to call `PATCH /repos/{owner}/{repo}/hooks/{webhookId}`.
+     * When reactivating an inactive webhook, this method also merges the 'issues'
+     * event with any existing events to preserve the webhook's original configuration.
+     *
+     * @param owner - Repository owner (organization or user)
+     * @param repo - Repository name
+     * @param webhookId - Webhook ID to update
+     * @param updates - Updates to apply
+     * @param updates.active - Set webhook active status (true to reactivate)
+     * @param updates.events - Event types to subscribe to (merged with existing)
+     * @returns Promise resolving to true on success
+     * @throws Error if webhook update fails (caught and logged by caller)
+     *
+     * @see {@link https://docs.github.com/en/rest/webhooks/repos#update-a-repository-webhook}
+     */
+    private _updateRepoWebhook;
+}
+export {};
+//# sourceMappingURL=webhook-setup-service.d.ts.map

package/dist/services/webhook-setup-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-setup-service.d.ts","sourceRoot":"","sources":["../../src/services/webhook-setup-service.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,UAAU,MAAM;IACd,gCAAgC;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,0BAA0B;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kDAAkD;IAClD,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,wBAAwB;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE;QACN,+CAA+C;QAC/C,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,2EAA2E;IAC3E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IACzD,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,MAAM,EAAE,MAAM;IAI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,gBAAgB,EAAE,GAC/B,OAAO,CAAC,mBAAmB,CAAC;IAuD/B;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,qBAAqB;IA6HnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;;;;;;;;;OAWG;YACW,iBAAiB;IA0C/B;;;;;;;;;;;;;;;;OAgBG;YACW,kBAAkB;IA0BhC;;;;;;;;;;;;;;;;;OAiBG;YACW,kBAAkB;CAoCjC"}