@shepai/cli 1.116.3 → 1.117.0-pr367.ca5b6ac

package/dist/packages/core/src/infrastructure/services/tunnel/cloudflare-tunnel.service.js

@@ -0,0 +1,203 @@
+/**
+ * Cloudflare Tunnel Service
+ *
+ * Manages a `cloudflared` quick-tunnel that exposes ONLY the webhook
+ * API routes to the public internet via a random *.trycloudflare.com
+ * subdomain.
+ *
+ * Uses the `cloudflared` npm package which handles binary installation
+ * and provides a typed Tunnel API — no need for the user to install
+ * cloudflared separately.
+ *
+ * Security: A lightweight proxy HTTP server is started on a random port
+ * that only forwards requests matching the allowed path prefix
+ * (/api/webhooks) to the main app. The tunnel connects to this proxy,
+ * not the main app server. All other paths return 404.
+ */
+import { createServer, request as httpRequest } from 'node:http';
+const TAG = '[CloudflareTunnel]';
+const STARTUP_TIMEOUT_MS = 30_000;
+const ALLOWED_PATH_PREFIX = '/api/webhooks';
+async function defaultCreateTunnel(origin) {
+    const { Tunnel } = await import('cloudflared');
+    return Tunnel.quick(origin);
+}
+const defaultDeps = {
+    createTunnel: defaultCreateTunnel,
+};
+export class CloudflareTunnelService {
+    tunnel = null;
+    proxyServer = null;
+    publicUrl = null;
+    urlChangeHandlers = [];
+    deps;
+    constructor(deps = {}) {
+        this.deps = { ...defaultDeps, ...deps };
+    }
+    async start(localPort) {
+        if (this.tunnel) {
+            throw new Error(`${TAG} Tunnel already running at ${this.publicUrl}`);
+        }
+        // Start a proxy server that only forwards webhook routes
+        const proxyPort = await this.startProxyServer(localPort);
+        let tunnel;
+        try {
+            tunnel = await Promise.resolve(this.deps.createTunnel(`http://localhost:${proxyPort}`));
+        }
+        catch (err) {
+            this.stopProxyServer();
+            throw new Error(`${TAG} Failed to create tunnel: ${err.message}`);
+        }
+        this.tunnel = tunnel;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.stopTunnel();
+                reject(new Error(`${TAG} Timed out waiting for tunnel URL (${STARTUP_TIMEOUT_MS}ms)`));
+            }, STARTUP_TIMEOUT_MS);
+            tunnel.on('url', (url) => {
+                if (!this.publicUrl) {
+                    // First URL — startup complete
+                    this.publicUrl = url;
+                    clearTimeout(timeout);
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Tunnel ready: ${url} (proxying ${ALLOWED_PATH_PREFIX}/* to port ${localPort})`);
+                    resolve(url);
+                }
+                else if (url !== this.publicUrl) {
+                    // URL changed — reconnection with new subdomain
+                    const oldUrl = this.publicUrl;
+                    this.publicUrl = url;
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Tunnel URL changed: ${oldUrl} -> ${url}`);
+                    this.notifyUrlChange(url);
+                }
+            });
+            tunnel.on('error', (err) => {
+                clearTimeout(timeout);
+                this.tunnel = null;
+                this.publicUrl = null;
+                this.stopProxyServer();
+                reject(new Error(`${TAG} Failed to start tunnel: ${err.message}`));
+            });
+            tunnel.on('exit', (code) => {
+                clearTimeout(timeout);
+                if (this.tunnel === tunnel) {
+                    this.tunnel = null;
+                    const wasRunning = this.publicUrl !== null;
+                    this.publicUrl = null;
+                    this.stopProxyServer();
+                    if (wasRunning) {
+                        // eslint-disable-next-line no-console
+                        console.log(`${TAG} Tunnel process exited (code ${code})`);
+                    }
+                    else {
+                        reject(new Error(`${TAG} cloudflared exited with code ${code} before producing a URL`));
+                    }
+                }
+            });
+        });
+    }
+    async stop() {
+        this.stopTunnel();
+        this.publicUrl = null;
+    }
+    getPublicUrl() {
+        return this.publicUrl;
+    }
+    onUrlChange(handler) {
+        this.urlChangeHandlers.push(handler);
+    }
+    isRunning() {
+        return this.tunnel !== null && this.publicUrl !== null;
+    }
+    /**
+     * Start a lightweight HTTP proxy on a random port that only forwards
+     * requests with paths starting with ALLOWED_PATH_PREFIX to the main app.
+     * Everything else gets a 404.
+     */
+    startProxyServer(targetPort) {
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => {
+                const url = req.url ?? '';
+                if (!url.startsWith(ALLOWED_PATH_PREFIX)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Not found' }));
+                    return;
+                }
+                // Proxy the request to the main app
+                const proxyReq = httpRequest({
+                    hostname: 'localhost',
+                    port: targetPort,
+                    path: url,
+                    method: req.method,
+                    headers: req.headers,
+                }, (proxyRes) => {
+                    res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                    proxyRes.pipe(res);
+                });
+                proxyReq.on('error', (err) => {
+                    // eslint-disable-next-line no-console
+                    console.warn(`${TAG} Proxy error: ${err.message}`);
+                    if (!res.headersSent) {
+                        res.writeHead(502, { 'Content-Type': 'application/json' });
+                    }
+                    res.end(JSON.stringify({ error: 'Bad gateway' }));
+                });
+                req.pipe(proxyReq);
+            });
+            // Listen on port 0 = OS assigns a random available port
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                if (addr && typeof addr === 'object') {
+                    this.proxyServer = server;
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Webhook proxy listening on port ${addr.port}`);
+                    resolve(addr.port);
+                }
+                else {
+                    server.close();
+                    reject(new Error(`${TAG} Failed to start proxy server`));
+                }
+            });
+            server.on('error', (err) => {
+                reject(new Error(`${TAG} Proxy server error: ${err.message}`));
+            });
+        });
+    }
+    stopProxyServer() {
+        if (this.proxyServer) {
+            this.proxyServer.close();
+            this.proxyServer = null;
+        }
+    }
+    stopTunnel() {
+        if (this.tunnel) {
+            const tunnel = this.tunnel;
+            this.tunnel = null;
+            try {
+                tunnel.stop();
+            }
+            catch {
+                // Tunnel already stopped
+            }
+        }
+        this.stopProxyServer();
+    }
+    notifyUrlChange(newUrl) {
+        for (const handler of this.urlChangeHandlers) {
+            try {
+                const result = handler(newUrl);
+                if (result instanceof Promise) {
+                    result.catch((err) => {
+                        // eslint-disable-next-line no-console
+                        console.warn(`${TAG} URL change handler failed:`, err);
+                    });
+                }
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`${TAG} URL change handler threw:`, err);
+            }
+        }
+    }
+}

package/dist/packages/core/src/infrastructure/services/webhook/github-webhook.service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * GitHub Webhook Service
+ *
+ * Manages GitHub webhook registration and incoming event processing.
+ * Uses the GitHub CLI (`gh api`) for webhook CRUD operations.
+ *
+ * Webhook events supplement the existing PR sync polling:
+ * - Webhooks provide near-instant event delivery
+ * - Polling remains as a fallback for missed events
+ *
+ * Registered events: pull_request, check_suite, check_run
+ */
+import type { IWebhookService, WebhookEvent, WebhookValidationResult } from '../../../application/ports/output/services/webhook-service.interface.js';
+import type { IFeatureRepository } from '../../../application/ports/output/repositories/feature-repository.interface.js';
+import type { IGitPrService } from '../../../application/ports/output/services/git-pr-service.interface.js';
+import type { INotificationService } from '../../../application/ports/output/services/notification-service.interface.js';
+export type ExecFunction = (file: string, args: string[], options?: object) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface RegisteredWebhook {
+    repoFullName: string;
+    webhookId: number;
+    repositoryPath: string;
+}
+export type WebhookDeliveryStatus = 'success' | 'ignored' | 'error';
+export interface WebhookDeliveryRecord {
+    deliveryId: string;
+    eventType: string;
+    source: string;
+    receivedAt: string;
+    status: WebhookDeliveryStatus;
+    statusMessage: string;
+    durationMs: number;
+    payload: Record<string, unknown>;
+}
+export declare class GitHubWebhookService implements IWebhookService {
+    private readonly featureRepo;
+    private readonly gitPrService;
+    private readonly notificationService;
+    private readonly execFn;
+    private readonly registeredWebhooks;
+    private readonly deliveryHistory;
+    private webhookSecret;
+    constructor(featureRepo: IFeatureRepository, gitPrService: IGitPrService, notificationService: INotificationService, execFn: ExecFunction);
+    /**
+     * Get the webhook secret for signature validation.
+     * Exposed so the API route can validate incoming requests.
+     */
+    getSecret(): string;
+    /**
+     * Get the list of registered webhooks (for dashboard display).
+     */
+    getRegisteredWebhooks(): readonly RegisteredWebhook[];
+    /**
+     * Get recent delivery history (newest first).
+     */
+    getDeliveryHistory(): readonly WebhookDeliveryRecord[];
+    registerWebhooks(publicUrl: string): Promise<void>;
+    updateWebhookUrl(newUrl: string): Promise<void>;
+    removeWebhooks(): Promise<void>;
+    validateSignature(payload: string, signature: string, secret: string): WebhookValidationResult;
+    handleEvent(event: WebhookEvent): Promise<void>;
+    private recordDelivery;
+    private handlePullRequestEvent;
+    private handleCheckSuiteEvent;
+    private handleCheckRunEvent;
+    private findFeatureByPrOrBranch;
+    private findFeatureByBranch;
+    private updateFeaturePrStatus;
+    private updateFeatureCiStatus;
+    private registerWebhookForRepo;
+    private getRepoFullName;
+}
+//# sourceMappingURL=github-webhook.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/webhook/github-webhook.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-webhook.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/webhook/github-webhook.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,uBAAuB,EACxB,MAAM,yEAAyE,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gFAAgF,CAAC;AACzH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wEAAwE,CAAC;AAC5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8EAA8E,CAAC;AASzH,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAuB;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2B;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+B;IAC/D,OAAO,CAAC,aAAa,CAAS;gBAG5B,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,aAAa,EAC3B,mBAAmB,EAAE,oBAAoB,EACzC,MAAM,EAAE,YAAY;IAStB;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,qBAAqB,IAAI,SAAS,iBAAiB,EAAE;IAIrD;;OAEG;IACH,kBAAkB,IAAI,SAAS,qBAAqB,EAAE;IAIhD,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlD,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkC/C,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BrC,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,uBAAuB;IAgCxF,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA4CrD,OAAO,CAAC,cAAc;YAOR,sBAAsB;YAsBtB,qBAAqB;YAiBrB,mBAAmB;YAoBnB,uBAAuB;YAWvB,mBAAmB;YAKnB,qBAAqB;YA6CrB,qBAAqB;YA4BrB,sBAAsB;YAqDtB,eAAe;CAe9B"}

package/dist/packages/core/src/infrastructure/services/webhook/github-webhook.service.js

@@ -0,0 +1,372 @@
+/**
+ * GitHub Webhook Service
+ *
+ * Manages GitHub webhook registration and incoming event processing.
+ * Uses the GitHub CLI (`gh api`) for webhook CRUD operations.
+ *
+ * Webhook events supplement the existing PR sync polling:
+ * - Webhooks provide near-instant event delivery
+ * - Polling remains as a fallback for missed events
+ *
+ * Registered events: pull_request, check_suite, check_run
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { SdlcLifecycle, PrStatus, CiStatus } from '../../../domain/generated/output.js';
+import { NotificationEventType, NotificationSeverity } from '../../../domain/generated/output.js';
+const TAG = '[GitHubWebhook]';
+const WEBHOOK_EVENTS = ['pull_request', 'check_suite', 'check_run'];
+const MAX_EVENT_HISTORY = 200;
+export class GitHubWebhookService {
+    featureRepo;
+    gitPrService;
+    notificationService;
+    execFn;
+    registeredWebhooks = [];
+    deliveryHistory = [];
+    webhookSecret;
+    constructor(featureRepo, gitPrService, notificationService, execFn) {
+        this.featureRepo = featureRepo;
+        this.gitPrService = gitPrService;
+        this.notificationService = notificationService;
+        this.execFn = execFn;
+        this.webhookSecret = randomBytes(32).toString('hex');
+    }
+    /**
+     * Get the webhook secret for signature validation.
+     * Exposed so the API route can validate incoming requests.
+     */
+    getSecret() {
+        return this.webhookSecret;
+    }
+    /**
+     * Get the list of registered webhooks (for dashboard display).
+     */
+    getRegisteredWebhooks() {
+        return this.registeredWebhooks;
+    }
+    /**
+     * Get recent delivery history (newest first).
+     */
+    getDeliveryHistory() {
+        return this.deliveryHistory;
+    }
+    async registerWebhooks(publicUrl) {
+        const webhookUrl = `${publicUrl}/api/webhooks/github`;
+        // Find all repos with features in Review lifecycle
+        const features = await this.featureRepo.list({ lifecycle: SdlcLifecycle.Review });
+        const repoPaths = new Set();
+        for (const feature of features) {
+            if (feature.repositoryPath) {
+                repoPaths.add(feature.repositoryPath);
+            }
+        }
+        for (const repoPath of repoPaths) {
+            await this.registerWebhookForRepo(repoPath, webhookUrl);
+        }
+        // eslint-disable-next-line no-console
+        console.log(`${TAG} Registered webhooks for ${this.registeredWebhooks.length} repositories`);
+    }
+    async updateWebhookUrl(newUrl) {
+        const webhookUrl = `${newUrl}/api/webhooks/github`;
+        for (const webhook of this.registeredWebhooks) {
+            try {
+                await this.execFn('gh', [
+                    'api',
+                    '--method',
+                    'PATCH',
+                    `-H`,
+                    'Accept: application/vnd.github+json',
+                    `/repos/${webhook.repoFullName}/hooks/${webhook.webhookId}`,
+                    '-f',
+                    `config[url]=${webhookUrl}`,
+                    '-f',
+                    `config[content_type]=json`,
+                    '-f',
+                    `config[secret]=${this.webhookSecret}`,
+                ], { cwd: webhook.repositoryPath });
+                // eslint-disable-next-line no-console
+                console.log(`${TAG} Updated webhook URL for ${webhook.repoFullName}`);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                // eslint-disable-next-line no-console
+                console.warn(`${TAG} Failed to update webhook for ${webhook.repoFullName}: ${msg}`);
+            }
+        }
+    }
+    async removeWebhooks() {
+        for (const webhook of this.registeredWebhooks) {
+            try {
+                await this.execFn('gh', [
+                    'api',
+                    '--method',
+                    'DELETE',
+                    `-H`,
+                    'Accept: application/vnd.github+json',
+                    `/repos/${webhook.repoFullName}/hooks/${webhook.webhookId}`,
+                ], { cwd: webhook.repositoryPath });
+                // eslint-disable-next-line no-console
+                console.log(`${TAG} Removed webhook for ${webhook.repoFullName}`);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                // eslint-disable-next-line no-console
+                console.warn(`${TAG} Failed to remove webhook for ${webhook.repoFullName}: ${msg}`);
+            }
+        }
+        this.registeredWebhooks.length = 0;
+    }
+    validateSignature(payload, signature, secret) {
+        if (!signature) {
+            return { valid: false, error: 'Missing signature header' };
+        }
+        const parts = signature.split('=');
+        if (parts.length !== 2 || parts[0] !== 'sha256') {
+            return { valid: false, error: 'Invalid signature format (expected sha256=...)' };
+        }
+        const expected = createHmac('sha256', secret).update(payload).digest('hex');
+        const actual = parts[1];
+        // Use timing-safe comparison to prevent timing attacks
+        try {
+            const expectedBuf = Buffer.from(expected, 'hex');
+            const actualBuf = Buffer.from(actual, 'hex');
+            if (expectedBuf.length !== actualBuf.length) {
+                return { valid: false, error: 'Signature length mismatch' };
+            }
+            if (!timingSafeEqual(expectedBuf, actualBuf)) {
+                return { valid: false, error: 'Signature mismatch' };
+            }
+            return { valid: true };
+        }
+        catch {
+            return { valid: false, error: 'Invalid signature encoding' };
+        }
+    }
+    async handleEvent(event) {
+        const startTime = Date.now();
+        // eslint-disable-next-line no-console
+        console.log(`${TAG} Received ${event.source}/${event.eventType} (delivery: ${event.deliveryId})`);
+        let status = 'success';
+        let statusMessage = 'Processed successfully';
+        try {
+            switch (event.eventType) {
+                case 'pull_request':
+                    await this.handlePullRequestEvent(event.payload);
+                    break;
+                case 'check_suite':
+                    await this.handleCheckSuiteEvent(event.payload);
+                    break;
+                case 'check_run':
+                    await this.handleCheckRunEvent(event.payload);
+                    break;
+                default:
+                    status = 'ignored';
+                    statusMessage = `Unhandled event type: ${event.eventType}`;
+                    // eslint-disable-next-line no-console
+                    console.log(`${TAG} Ignoring unhandled event type: ${event.eventType}`);
+            }
+        }
+        catch (error) {
+            status = 'error';
+            statusMessage = error instanceof Error ? error.message : String(error);
+        }
+        this.recordDelivery({
+            deliveryId: event.deliveryId,
+            eventType: event.eventType,
+            source: event.source,
+            receivedAt: new Date().toISOString(),
+            status,
+            statusMessage,
+            durationMs: Date.now() - startTime,
+            payload: event.payload,
+        });
+    }
+    recordDelivery(record) {
+        this.deliveryHistory.unshift(record);
+        if (this.deliveryHistory.length > MAX_EVENT_HISTORY) {
+            this.deliveryHistory.length = MAX_EVENT_HISTORY;
+        }
+    }
+    async handlePullRequestEvent(payload) {
+        const action = payload.action;
+        const pr = payload.pull_request;
+        if (!pr)
+            return;
+        const prNumber = pr.number;
+        const prUrl = pr.html_url ?? '';
+        const headBranch = pr.head?.ref;
+        // Find feature by PR number or branch
+        const feature = await this.findFeatureByPrOrBranch(prNumber, headBranch);
+        if (!feature)
+            return;
+        if (action === 'closed' && pr.merged === true) {
+            await this.updateFeaturePrStatus(feature, PrStatus.Merged, prNumber, prUrl);
+        }
+        else if (action === 'closed') {
+            await this.updateFeaturePrStatus(feature, PrStatus.Closed, prNumber, prUrl);
+        }
+        else if (action === 'reopened') {
+            await this.updateFeaturePrStatus(feature, PrStatus.Open, prNumber, prUrl);
+        }
+    }
+    async handleCheckSuiteEvent(payload) {
+        const action = payload.action;
+        if (action !== 'completed')
+            return;
+        const checkSuite = payload.check_suite;
+        if (!checkSuite)
+            return;
+        const conclusion = checkSuite.conclusion;
+        const headBranch = checkSuite.head_branch;
+        const feature = await this.findFeatureByBranch(headBranch);
+        if (!feature)
+            return;
+        const ciStatus = conclusion === 'success' ? CiStatus.Success : CiStatus.Failure;
+        await this.updateFeatureCiStatus(feature, ciStatus);
+    }
+    async handleCheckRunEvent(payload) {
+        const action = payload.action;
+        if (action !== 'completed')
+            return;
+        const checkRun = payload.check_run;
+        if (!checkRun)
+            return;
+        const conclusion = checkRun.conclusion;
+        const checkSuite = checkRun.check_suite;
+        const headBranch = checkSuite?.head_branch;
+        if (!headBranch)
+            return;
+        const feature = await this.findFeatureByBranch(headBranch);
+        if (!feature)
+            return;
+        const ciStatus = conclusion === 'success' ? CiStatus.Success : CiStatus.Failure;
+        await this.updateFeatureCiStatus(feature, ciStatus);
+    }
+    async findFeatureByPrOrBranch(prNumber, branch) {
+        const features = await this.featureRepo.list({ lifecycle: SdlcLifecycle.Review });
+        // Try matching by PR number first
+        const byPr = features.find((f) => f.pr?.number === prNumber);
+        if (byPr)
+            return byPr;
+        // Fall back to branch matching
+        return features.find((f) => f.branch === branch) ?? null;
+    }
+    async findFeatureByBranch(branch) {
+        const features = await this.featureRepo.list({ lifecycle: SdlcLifecycle.Review });
+        return features.find((f) => f.branch === branch) ?? null;
+    }
+    async updateFeaturePrStatus(feature, status, prNumber, prUrl) {
+        const oldStatus = feature.pr?.status;
+        if (oldStatus === status)
+            return;
+        feature.pr = { ...feature.pr, status, url: prUrl, number: prNumber };
+        if (status === PrStatus.Merged) {
+            feature.lifecycle = SdlcLifecycle.Maintain;
+        }
+        await this.featureRepo.update(feature);
+        // Emit notification
+        const eventType = status === PrStatus.Merged
+            ? NotificationEventType.PrMerged
+            : status === PrStatus.Closed
+                ? NotificationEventType.PrClosed
+                : NotificationEventType.PrChecksPassed; // reopened
+        const severity = status === PrStatus.Merged
+            ? NotificationSeverity.Success
+            : status === PrStatus.Closed
+                ? NotificationSeverity.Warning
+                : NotificationSeverity.Info;
+        const event = {
+            eventType,
+            featureId: feature.id,
+            agentRunId: feature.agentRunId ?? '',
+            featureName: feature.name,
+            message: `PR #${prNumber} ${status.toLowerCase()} for ${feature.name} (via webhook)`,
+            severity,
+            timestamp: new Date().toISOString(),
+        };
+        this.notificationService.notify(event);
+    }
+    async updateFeatureCiStatus(feature, ciStatus) {
+        if (!feature.pr)
+            return;
+        if (feature.pr.ciStatus === ciStatus)
+            return;
+        feature.pr = { ...feature.pr, ciStatus };
+        await this.featureRepo.update(feature);
+        const eventType = ciStatus === CiStatus.Success
+            ? NotificationEventType.PrChecksPassed
+            : NotificationEventType.PrChecksFailed;
+        const severity = ciStatus === CiStatus.Success ? NotificationSeverity.Success : NotificationSeverity.Error;
+        const event = {
+            eventType,
+            featureId: feature.id,
+            agentRunId: feature.agentRunId ?? '',
+            featureName: feature.name,
+            message: `CI ${ciStatus === CiStatus.Success ? 'passed' : 'failed'} for ${feature.name} (via webhook)`,
+            severity,
+            timestamp: new Date().toISOString(),
+        };
+        this.notificationService.notify(event);
+    }
+    async registerWebhookForRepo(repoPath, webhookUrl) {
+        try {
+            // Get the repo full name (owner/repo) from the remote URL
+            const repoFullName = await this.getRepoFullName(repoPath);
+            if (!repoFullName) {
+                // eslint-disable-next-line no-console
+                console.warn(`${TAG} Could not determine repo name for ${repoPath}`);
+                return;
+            }
+            // Create webhook via GitHub API
+            const { stdout } = await this.execFn('gh', [
+                'api',
+                '--method',
+                'POST',
+                `-H`,
+                'Accept: application/vnd.github+json',
+                `/repos/${repoFullName}/hooks`,
+                '-f',
+                'name=web',
+                '-f',
+                `config[url]=${webhookUrl}`,
+                '-f',
+                'config[content_type]=json',
+                '-f',
+                `config[secret]=${this.webhookSecret}`,
+                ...WEBHOOK_EVENTS.flatMap((e) => ['-f', `events[]=${e}`]),
+                '-F',
+                'active=true',
+            ], { cwd: repoPath });
+            const response = JSON.parse(stdout);
+            const webhookId = response.id;
+            this.registeredWebhooks.push({
+                repoFullName,
+                webhookId,
+                repositoryPath: repoPath,
+            });
+            // eslint-disable-next-line no-console
+            console.log(`${TAG} Registered webhook #${webhookId} for ${repoFullName}`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`${TAG} Failed to register webhook for ${repoPath}: ${msg}`);
+        }
+    }
+    async getRepoFullName(repoPath) {
+        try {
+            const remoteUrl = await this.gitPrService.getRemoteUrl(repoPath);
+            if (!remoteUrl)
+                return null;
+            // Parse owner/repo from URL
+            // Handles both https://github.com/owner/repo and git@github.com:owner/repo.git
+            const match = remoteUrl.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+            if (!match)
+                return null;
+            return `${match[1]}/${match[2]}`;
+        }
+        catch {
+            return null;
+        }
+    }
+}