@ouija-dev/plugin-github 0.1.0

package/dist/api-client.d.ts

@@ -0,0 +1,75 @@
+import type { OpenPRParams, StandardPR } from '@ouija-dev/types';
+/**
+ * Encode a GitHub PR as a branded PrId.
+ * Format: "owner/repo#number"
+ * This is the canonical parse boundary — all external callers use this format.
+ */
+export declare function encodePrId(owner: string, repo: string, prNumber: number): import("@ouija-dev/types").PrId;
+/**
+ * Decode a PrId back to its GitHub coordinates.
+ * Throws if the format is unexpected — a broken PrId means something upstream
+ * gave us bad data.
+ */
+export declare function decodePrId(id: string): {
+    owner: string;
+    repo: string;
+    prNumber: number;
+};
+/**
+ * Parse a GitHub repo URL into owner/repo components.
+ * Accepts:
+ *   https://github.com/owner/repo
+ *   https://github.com/owner/repo.git
+ *   git@github.com:owner/repo.git
+ */
+export declare function parseRepoUrl(repoUrl: string): {
+    owner: string;
+    repo: string;
+};
+export declare class GitHubApiClient {
+    private readonly octokit;
+    constructor(token: string);
+    /**
+     * Create a new branch from an existing ref.
+     * `fromRef` may be a branch name, tag, or full SHA.
+     */
+    createBranch(owner: string, repo: string, branch: string, fromRef: string): Promise<void>;
+    /**
+     * Open a pull request and return its standard representation.
+     * `repoUrl` is parsed to extract owner/repo.
+     */
+    openPR(repoUrl: string, params: OpenPRParams): Promise<StandardPR>;
+    /**
+     * Merge a pull request by its PrId.
+     * Uses the squash merge strategy by default.
+     */
+    mergePR(prIdValue: string): Promise<void>;
+    /**
+     * Add a comment to a pull request (as an issue comment — visible on the PR timeline).
+     */
+    addPRComment(prIdValue: string, body: string): Promise<void>;
+    /**
+     * Get a pull request by its PrId.
+     */
+    getPR(prIdValue: string): Promise<StandardPR>;
+    /**
+     * Check whether a branch exists on the repo.
+     * Returns null if not found, the branch ref object if found.
+     */
+    getBranch(owner: string, repo: string, branch: string): Promise<{
+        sha: string;
+        name: string;
+    } | null>;
+    /**
+     * Verify that the token has sufficient access by listing repos.
+     * Throws if the request fails (bad token, revoked, etc.).
+     */
+    verifyToken(): Promise<void>;
+    /**
+     * Lightweight health check — call GET /user and return whether it succeeds.
+     */
+    getAuthenticatedUser(): Promise<{
+        login: string;
+    }>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKjE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mCAEvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAUxF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAc7E;AAID,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,KAAK,EAAE,MAAM;IAIzB;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB/F;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IA2BxE;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiCnD;;;OAGG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAiBhD;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAIzD"}

package/dist/api-client.js

@@ -0,0 +1,209 @@
+import { Octokit } from '@octokit/rest';
+import { prId } from '@ouija-dev/types';
+// ---- Helpers ----
+/**
+ * Encode a GitHub PR as a branded PrId.
+ * Format: "owner/repo#number"
+ * This is the canonical parse boundary — all external callers use this format.
+ */
+export function encodePrId(owner, repo, prNumber) {
+    return prId(`${owner}/${repo}#${prNumber}`);
+}
+/**
+ * Decode a PrId back to its GitHub coordinates.
+ * Throws if the format is unexpected — a broken PrId means something upstream
+ * gave us bad data.
+ */
+export function decodePrId(id) {
+    const match = /^([^/]+)\/([^#]+)#(\d+)$/.exec(id);
+    if (!match) {
+        throw new Error(`GitHubApiClient: cannot decode PrId "${id}" — expected "owner/repo#number"`);
+    }
+    return {
+        owner: match[1],
+        repo: match[2],
+        prNumber: parseInt(match[3], 10),
+    };
+}
+/**
+ * Parse a GitHub repo URL into owner/repo components.
+ * Accepts:
+ *   https://github.com/owner/repo
+ *   https://github.com/owner/repo.git
+ *   git@github.com:owner/repo.git
+ */
+export function parseRepoUrl(repoUrl) {
+    // SSH format: git@github.com:owner/repo.git
+    const sshMatch = /git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/.exec(repoUrl);
+    if (sshMatch) {
+        return { owner: sshMatch[1], repo: sshMatch[2] };
+    }
+    // HTTPS format: https://github.com/owner/repo[.git]
+    const httpsMatch = /github\.com\/([^/]+)\/(.+?)(?:\.git)?$/.exec(repoUrl);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    }
+    throw new Error(`GitHubApiClient: cannot parse repo URL "${repoUrl}"`);
+}
+// ---- GitHub API client ----
+export class GitHubApiClient {
+    octokit;
+    constructor(token) {
+        this.octokit = new Octokit({ auth: token });
+    }
+    /**
+     * Create a new branch from an existing ref.
+     * `fromRef` may be a branch name, tag, or full SHA.
+     */
+    async createBranch(owner, repo, branch, fromRef) {
+        // Resolve fromRef to a SHA. If it's already a SHA (40 hex chars) we skip this.
+        let sha;
+        if (/^[0-9a-f]{40}$/i.test(fromRef)) {
+            sha = fromRef;
+        }
+        else {
+            const { data: refData } = await this.octokit.git.getRef({
+                owner,
+                repo,
+                ref: `heads/${fromRef}`,
+            });
+            sha = refData.object.sha;
+        }
+        await this.octokit.git.createRef({
+            owner,
+            repo,
+            ref: `refs/heads/${branch}`,
+            sha,
+        });
+    }
+    /**
+     * Open a pull request and return its standard representation.
+     * `repoUrl` is parsed to extract owner/repo.
+     */
+    async openPR(repoUrl, params) {
+        const { owner, repo } = parseRepoUrl(repoUrl);
+        const { data } = await this.octokit.pulls.create({
+            owner,
+            repo,
+            title: params.title,
+            body: params.body,
+            head: params.branch,
+            base: params.baseBranch,
+            draft: params.draft ?? false,
+        });
+        return {
+            id: encodePrId(owner, repo, data.number),
+            url: data.html_url,
+            title: data.title,
+            body: data.body ?? '',
+            branch: data.head.ref,
+            baseBranch: data.base.ref,
+            state: 'open',
+            draft: data.draft ?? false,
+            createdAt: data.created_at,
+            updatedAt: data.updated_at,
+        };
+    }
+    /**
+     * Merge a pull request by its PrId.
+     * Uses the squash merge strategy by default.
+     */
+    async mergePR(prIdValue) {
+        const { owner, repo, prNumber } = decodePrId(prIdValue);
+        await this.octokit.pulls.merge({
+            owner,
+            repo,
+            pull_number: prNumber,
+            merge_method: 'squash',
+        });
+    }
+    /**
+     * Add a comment to a pull request (as an issue comment — visible on the PR timeline).
+     */
+    async addPRComment(prIdValue, body) {
+        const { owner, repo, prNumber } = decodePrId(prIdValue);
+        await this.octokit.issues.createComment({
+            owner,
+            repo,
+            issue_number: prNumber,
+            body,
+        });
+    }
+    /**
+     * Get a pull request by its PrId.
+     */
+    async getPR(prIdValue) {
+        const { owner, repo, prNumber } = decodePrId(prIdValue);
+        const { data } = await this.octokit.pulls.get({
+            owner,
+            repo,
+            pull_number: prNumber,
+        });
+        let state;
+        if (data.merged) {
+            state = 'merged';
+        }
+        else if (data.state === 'closed') {
+            state = 'closed';
+        }
+        else {
+            state = 'open';
+        }
+        return {
+            id: encodePrId(owner, repo, data.number),
+            url: data.html_url,
+            title: data.title,
+            body: data.body ?? '',
+            branch: data.head.ref,
+            baseBranch: data.base.ref,
+            state,
+            draft: data.draft ?? false,
+            createdAt: data.created_at,
+            updatedAt: data.updated_at,
+            ...(data.merged_at ? { mergedAt: data.merged_at } : {}),
+        };
+    }
+    /**
+     * Check whether a branch exists on the repo.
+     * Returns null if not found, the branch ref object if found.
+     */
+    async getBranch(owner, repo, branch) {
+        try {
+            const { data } = await this.octokit.git.getRef({
+                owner,
+                repo,
+                ref: `heads/${branch}`,
+            });
+            return { sha: data.object.sha, name: branch };
+        }
+        catch (err) {
+            // Octokit throws a RequestError with status 404 when the ref doesn't exist.
+            if (isOctokitNotFound(err)) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Verify that the token has sufficient access by listing repos.
+     * Throws if the request fails (bad token, revoked, etc.).
+     */
+    async verifyToken() {
+        await this.octokit.repos.listForAuthenticatedUser({ per_page: 1 });
+    }
+    /**
+     * Lightweight health check — call GET /user and return whether it succeeds.
+     */
+    async getAuthenticatedUser() {
+        const { data } = await this.octokit.users.getAuthenticated();
+        return { login: data.login };
+    }
+}
+// ---- Error helpers ----
+function isOctokitNotFound(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        err.status === 404);
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export declare const githubConfigSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly personalAccessToken: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly defaultOrg: {
+            readonly type: "string";
+        };
+        readonly webhookSecret: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly required: readonly ["personalAccessToken", "webhookSecret"];
+    readonly additionalProperties: false;
+};
+export interface GitHubConfig {
+    personalAccessToken: string;
+    defaultOrg?: string;
+    webhookSecret: string;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;CASrB,CAAC;AAIX,MAAM,WAAW,YAAY;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/config.js

@@ -0,0 +1,12 @@
+// ---- GitHub plugin config schema ----
+export const githubConfigSchema = {
+    type: 'object',
+    properties: {
+        personalAccessToken: { type: 'string', minLength: 1 },
+        defaultOrg: { type: 'string' },
+        webhookSecret: { type: 'string', minLength: 1 },
+    },
+    required: ['personalAccessToken', 'webhookSecret'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;QACrD,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC9B,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;KAChD;IACD,QAAQ,EAAE,CAAC,qBAAqB,EAAE,eAAe,CAAC;IAClD,oBAAoB,EAAE,KAAK;CACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import type { FastifyInstance } from 'fastify';
+import type { GitPlugin, PluginManifest, PluginContext, PluginHealth, StandardPR, OpenPRParams } from '@ouija-dev/types';
+import type { PrId } from '@ouija-dev/types';
+import type { PluginFactory } from '@ouija-dev/plugin-sdk';
+import { type GitHubConfig } from './config.js';
+export declare class GitHubPlugin implements GitPlugin<GitHubConfig> {
+    readonly manifest: PluginManifest;
+    private client;
+    private context;
+    init(context: PluginContext<GitHubConfig>): Promise<void>;
+    /**
+     * Verify that the personal access token has list-repos scope.
+     * A 401/403 at this point surfaces immediately rather than silently at PR time.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    healthCheck(): Promise<PluginHealth>;
+    /**
+     * Register the GitHub webhook ingress route.
+     *
+     * Route: POST /hooks/github/:secret
+     *
+     * The :secret path segment is compared against `config.webhookSecret` to
+     * allow routing multiple GitHub app installations to different endpoints
+     * without embedding secrets in GitHub's per-repo webhook URL. The
+     * X-Hub-Signature-256 header is additionally verified with HMAC-SHA256
+     * so that even a leaked URL cannot be abused.
+     */
+    registerRoutes(fastify: FastifyInstance): Promise<void>;
+    /**
+     * Create a branch from `fromBranch` on the repo identified by `repoUrl`.
+     */
+    createBranch(repoUrl: string, branchName: string, fromBranch: string): Promise<void>;
+    /**
+     * Open a pull request on the repo identified by `repoUrl`.
+     */
+    openPR(repoUrl: string, params: OpenPRParams): Promise<StandardPR>;
+    /**
+     * Merge the pull request identified by `prId`.
+     */
+    mergePR(id: PrId): Promise<void>;
+    /**
+     * Add a comment to the pull request identified by `prId`.
+     */
+    addPRComment(id: PrId, body: string): Promise<void>;
+    /**
+     * Get the current state of a pull request by its `prId`.
+     */
+    getPR(id: PrId): Promise<StandardPR>;
+}
+declare const PluginFactoryExport: PluginFactory<GitHubConfig>;
+export { PluginFactoryExport as PluginFactory };
+export default PluginFactoryExport;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAqBpE,qBAAa,YAAa,YAAW,SAAS,CAAC,YAAY,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAY;IAE7C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,OAAO,CAA+B;IAIxC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAYtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAkB1C;;;;;;;;;;OAUG;IACG,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmE7D;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1F;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAIxE;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;OAEG;IACG,KAAK,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;CAG3C;AAID,QAAA,MAAM,mBAAmB,EAAE,aAAa,CAAC,YAAY,CAKpD,CAAC;AAEF,OAAO,EAAE,mBAAmB,IAAI,aAAa,EAAE,CAAC;AAChD,eAAe,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,161 @@
+import { githubConfigSchema } from './config.js';
+import { GitHubApiClient, parseRepoUrl } from './api-client.js';
+import { normalizeWebhook, verifySignature } from './webhook-handler.js';
+// ---- Plugin manifest ----
+const manifest = {
+    name: '@ouija-dev/plugin-github',
+    version: '0.1.0',
+    type: 'git',
+    coreApiVersion: '>=1.0.0 <2.0.0',
+    configSchema: githubConfigSchema,
+    dependencies: [],
+    events: {
+        produces: ['git.pr.opened', 'git.pr.merged'],
+        consumes: [],
+    },
+};
+// ---- Plugin implementation ----
+export class GitHubPlugin {
+    manifest = manifest;
+    client;
+    context;
+    // ---- Lifecycle ----
+    async init(context) {
+        this.context = context;
+        this.client = new GitHubApiClient(context.config.personalAccessToken);
+        context.logger.info('GitHubPlugin initialised');
+    }
+    /**
+     * Verify that the personal access token has list-repos scope.
+     * A 401/403 at this point surfaces immediately rather than silently at PR time.
+     */
+    async start() {
+        try {
+            await this.client.verifyToken();
+            this.context.logger.info('GitHubPlugin started — token verified');
+        }
+        catch (err) {
+            this.context.logger.error('GitHubPlugin start failed — token verification error', {
+                error: String(err),
+            });
+            throw err;
+        }
+    }
+    async stop() {
+        this.context.logger.info('GitHubPlugin stopped');
+    }
+    async healthCheck() {
+        try {
+            const user = await this.client.getAuthenticatedUser();
+            return {
+                healthy: true,
+                message: `Authenticated as ${user.login}`,
+                details: { login: user.login },
+            };
+        }
+        catch (err) {
+            return {
+                healthy: false,
+                message: `GitHub API unreachable: ${String(err)}`,
+            };
+        }
+    }
+    // ---- Route registration ----
+    /**
+     * Register the GitHub webhook ingress route.
+     *
+     * Route: POST /hooks/github/:secret
+     *
+     * The :secret path segment is compared against `config.webhookSecret` to
+     * allow routing multiple GitHub app installations to different endpoints
+     * without embedding secrets in GitHub's per-repo webhook URL. The
+     * X-Hub-Signature-256 header is additionally verified with HMAC-SHA256
+     * so that even a leaked URL cannot be abused.
+     */
+    async registerRoutes(fastify) {
+        const webhookSecret = this.context.config.webhookSecret;
+        fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (_req, body, done) => {
+            done(null, body);
+        });
+        fastify.post('/hooks/github/:secret', async (request, reply) => {
+            const params = request.params;
+            const headers = request.headers;
+            // 1. Constant-time secret comparison is handled inside verifySignature.
+            //    We additionally check the path secret matches to ensure correct routing.
+            if (params.secret !== webhookSecret) {
+                return reply.status(403).send({ error: 'Forbidden' });
+            }
+            const signatureHeader = headers['x-hub-signature-256'] ?? '';
+            const rawBody = request.body;
+            if (!verifySignature(webhookSecret, rawBody, signatureHeader)) {
+                return reply.status(403).send({ error: 'Invalid signature' });
+            }
+            // 2. Parse and normalize the webhook.
+            let parsed;
+            try {
+                parsed = JSON.parse(rawBody.toString('utf8'));
+            }
+            catch {
+                return reply.status(400).send({ error: 'Invalid JSON body' });
+            }
+            const githubEvent = headers['x-github-event'] ?? '';
+            const event = normalizeWebhook(githubEvent, parsed);
+            if (event !== null) {
+                try {
+                    await this.context.publishEvent(event.topic, event.payload);
+                }
+                catch (err) {
+                    this.context.logger.error('Failed to publish webhook event', {
+                        topic: event.topic,
+                        error: String(err),
+                    });
+                    // Still return 200 — GitHub will retry on non-2xx responses, which
+                    // would cause duplicate events. We log and move on.
+                }
+            }
+            return reply.status(200).send({ ok: true });
+        });
+    }
+    // ---- GitPlugin interface ----
+    /**
+     * Create a branch from `fromBranch` on the repo identified by `repoUrl`.
+     */
+    async createBranch(repoUrl, branchName, fromBranch) {
+        const { owner, repo } = parseRepoUrl(repoUrl);
+        await this.client.createBranch(owner, repo, branchName, fromBranch);
+    }
+    /**
+     * Open a pull request on the repo identified by `repoUrl`.
+     */
+    async openPR(repoUrl, params) {
+        return this.client.openPR(repoUrl, params);
+    }
+    /**
+     * Merge the pull request identified by `prId`.
+     */
+    async mergePR(id) {
+        await this.client.mergePR(id);
+    }
+    /**
+     * Add a comment to the pull request identified by `prId`.
+     */
+    async addPRComment(id, body) {
+        await this.client.addPRComment(id, body);
+    }
+    /**
+     * Get the current state of a pull request by its `prId`.
+     */
+    async getPR(id) {
+        return this.client.getPR(id);
+    }
+}
+// ---- PluginFactory (required by PluginLoader) ----
+const PluginFactoryExport = {
+    manifest,
+    create() {
+        return new GitHubPlugin();
+    },
+};
+export { PluginFactoryExport as PluginFactory };
+export default PluginFactoryExport;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/webhook-handler.d.ts

@@ -0,0 +1,48 @@
+import type { OuijaEvent, StandardPR } from '@ouija-dev/types';
+interface GitHubPR {
+    number: number;
+    html_url: string;
+    title: string;
+    body: string | null;
+    state: string;
+    draft: boolean;
+    merged: boolean;
+    merged_at: string | null;
+    created_at: string;
+    updated_at: string;
+    head: {
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+/**
+ * Compute the expected HMAC-SHA256 signature for a raw webhook body.
+ * Returns the value in the format GitHub sends: "sha256=<hex>".
+ */
+export declare function computeSignature(secret: string, rawBody: string | Buffer): string;
+/**
+ * Verify the X-Hub-Signature-256 header against the raw request body.
+ * Uses timingSafeEqual to prevent timing attacks.
+ *
+ * Returns true if the signature matches, false otherwise.
+ */
+export declare function verifySignature(secret: string, rawBody: string | Buffer, signatureHeader: string): boolean;
+/**
+ * Normalize a raw GitHub webhook into an OuijaEvent.
+ *
+ * Supported mappings:
+ *   pull_request / opened   → git.pr.opened
+ *   pull_request / closed (merged: true) → git.pr.merged
+ *
+ * All other events/actions return null (caller should 200 OK and discard).
+ */
+export declare function normalizeWebhook(githubEvent: string, payload: unknown): OuijaEvent<'git.pr.opened'> | OuijaEvent<'git.pr.merged'> | null;
+/**
+ * Build a StandardPR from a GitHub pull_request payload object.
+ * Exported so the main plugin can use it when returning from openPR.
+ */
+export declare function normalizePR(pr: GitHubPR, owner: string, repoName: string): StandardPR;
+export {};
+//# sourceMappingURL=webhook-handler.d.ts.map

package/dist/webhook-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handler.d.ts","sourceRoot":"","sources":["../src/webhook-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAA0C,MAAM,kBAAkB,CAAC;AAavG,UAAU,QAAQ;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACvB;AAWD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAIjF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,eAAe,EAAE,MAAM,GACtB,OAAO,CAeT;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,GACf,UAAU,CAAC,eAAe,CAAC,GAAG,UAAU,CAAC,eAAe,CAAC,GAAG,IAAI,CAwClE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAuBrF"}

package/dist/webhook-handler.js

@@ -0,0 +1,117 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { prId, instanceId } from '@ouija-dev/types';
+import { encodePrId } from './api-client.js';
+// ---- Signature verification ----
+/**
+ * Compute the expected HMAC-SHA256 signature for a raw webhook body.
+ * Returns the value in the format GitHub sends: "sha256=<hex>".
+ */
+export function computeSignature(secret, rawBody) {
+    const hmac = createHmac('sha256', secret);
+    hmac.update(typeof rawBody === 'string' ? rawBody : rawBody);
+    return `sha256=${hmac.digest('hex')}`;
+}
+/**
+ * Verify the X-Hub-Signature-256 header against the raw request body.
+ * Uses timingSafeEqual to prevent timing attacks.
+ *
+ * Returns true if the signature matches, false otherwise.
+ */
+export function verifySignature(secret, rawBody, signatureHeader) {
+    const expected = computeSignature(secret, rawBody);
+    try {
+        const expectedBuf = Buffer.from(expected, 'utf8');
+        const actualBuf = Buffer.from(signatureHeader, 'utf8');
+        if (expectedBuf.length !== actualBuf.length) {
+            return false;
+        }
+        return timingSafeEqual(expectedBuf, actualBuf);
+    }
+    catch {
+        return false;
+    }
+}
+// ---- Payload normalizer ----
+/**
+ * Normalize a raw GitHub webhook into an OuijaEvent.
+ *
+ * Supported mappings:
+ *   pull_request / opened   → git.pr.opened
+ *   pull_request / closed (merged: true) → git.pr.merged
+ *
+ * All other events/actions return null (caller should 200 OK and discard).
+ */
+export function normalizeWebhook(githubEvent, payload) {
+    if (githubEvent !== 'pull_request') {
+        return null;
+    }
+    const typed = payload;
+    const { action, pull_request: pr, repository: repo } = typed;
+    const owner = repo.owner.login;
+    const repoName = repo.name;
+    const encodedPrId = encodePrId(owner, repoName, pr.number);
+    if (action === 'opened') {
+        const eventPayload = {
+            prId: encodedPrId,
+            url: pr.html_url,
+            // instanceId is not available from a bare webhook — callers that
+            // need it will correlate by prId. We generate a placeholder here.
+            instanceId: instanceId(`github-pr-${String(pr.number)}`),
+            branch: pr.head.ref,
+            targetBranch: pr.base.ref,
+        };
+        return buildEvent('git.pr.opened', eventPayload);
+    }
+    if (action === 'closed' && pr.merged === true) {
+        const mergedAt = pr.merged_at ?? new Date().toISOString();
+        const eventPayload = {
+            prId: encodedPrId,
+            instanceId: instanceId(`github-pr-${String(pr.number)}`),
+            mergedAt,
+        };
+        return buildEvent('git.pr.merged', eventPayload);
+    }
+    // PR closed without merge, or any other action (synchronize, review_requested, etc.)
+    return null;
+}
+/**
+ * Build a StandardPR from a GitHub pull_request payload object.
+ * Exported so the main plugin can use it when returning from openPR.
+ */
+export function normalizePR(pr, owner, repoName) {
+    let state;
+    if (pr.merged) {
+        state = 'merged';
+    }
+    else if (pr.state === 'closed') {
+        state = 'closed';
+    }
+    else {
+        state = 'open';
+    }
+    return {
+        id: prId(encodePrId(owner, repoName, pr.number)),
+        url: pr.html_url,
+        title: pr.title,
+        body: pr.body ?? '',
+        branch: pr.head.ref,
+        baseBranch: pr.base.ref,
+        state,
+        draft: pr.draft,
+        createdAt: pr.created_at,
+        updatedAt: pr.updated_at,
+        ...(pr.merged_at ? { mergedAt: pr.merged_at } : {}),
+    };
+}
+// ---- Internal helpers ----
+function buildEvent(topic, payload) {
+    return {
+        id: crypto.randomUUID(),
+        topic,
+        payload,
+        timestamp: new Date().toISOString(),
+        sourcePlugin: '@ouija-dev/plugin-github',
+        correlationId: crypto.randomUUID(),
+    };
+}
+//# sourceMappingURL=webhook-handler.js.map

package/dist/webhook-handler.js.map

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

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ouija-dev/plugin-github",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/", "README.md"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/muhammadkh4n/ouija.git" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ouija-dev/types": "*",
+    "@ouija-dev/plugin-sdk": "*",
+    "@octokit/rest": "^21.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "fastify": "^5.8.4",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}