@triagepilot/provider-github 1.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Miroslav Babjak
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/dist/adapter.d.ts

@@ -0,0 +1,142 @@
+import type { ConfigurationDocument, ConfigurationSource, RepositoryRef as ContractRepositoryRef, RiskTier, WorkspaceId } from "@triagepilot/contracts";
+type Requester = {
+    request(route: string, parameters: Record<string, unknown>): Promise<{
+        data: unknown;
+    }>;
+};
+export declare class GitHubConfigurationSource implements ConfigurationSource {
+    private readonly octokit;
+    constructor(octokit: Requester);
+    loadOrganization(_workspaceId: WorkspaceId): Promise<null>;
+    loadRepository(input: {
+        workspaceId: WorkspaceId;
+        repository: ContractRepositoryRef;
+        trustedRevision: string;
+    }): Promise<ConfigurationDocument | null>;
+}
+export interface RepositoryRef {
+    owner: string;
+    repo: string;
+}
+export interface PullRequestRef extends RepositoryRef {
+    pullNumber: number;
+}
+export interface CheckRunRef extends RepositoryRef {
+    headSha: string;
+}
+export interface PullRequestReview {
+    userLogin: string;
+    userType?: string;
+    state: "APPROVED" | "CHANGES_REQUESTED" | "COMMENTED" | "PENDING" | "DISMISSED" | string;
+    commitId: string | null;
+    submittedAt: string | null;
+}
+export interface GitHubReviewerReplacementState {
+    state: string;
+    currentHeadRevision: string;
+    authorActor: string;
+    requestedActors: string[];
+    reviews: Array<{
+        actor: string;
+        actorType: "human" | "bot";
+        state: string;
+        commitId: string | null;
+        submittedAt: string | null;
+    }>;
+}
+export interface GitHubRoutingRecoveryState {
+    state: string;
+    baseRevision: string;
+    headRevision: string;
+    isDraft: boolean;
+}
+export interface ReviewerReplacementErrorClassification {
+    kind: "permanent" | "retryable";
+    message: string;
+}
+export declare function createInstallationRequester(input: {
+    appId: string;
+    privateKey: string;
+    installationId: number;
+}): Promise<Requester>;
+export declare class GitHubAdapter {
+    private readonly octokit;
+    constructor(octokit: Requester);
+    fetchDefaultBranchRevision(repository: ContractRepositoryRef): Promise<string>;
+    fetchRoutingRecoveryState(input: {
+        pullRequest: PullRequestRef;
+    }): Promise<GitHubRoutingRecoveryState | null>;
+    inspectReviewerReplacement(input: {
+        pullRequest: PullRequestRef;
+    }): Promise<GitHubReviewerReplacementState>;
+    listRequestedReviewers(input: {
+        pullRequest: PullRequestRef;
+        signal?: AbortSignal;
+        assertAuthorized?: () => Promise<void>;
+    }): Promise<string[]>;
+    reconcileReviewerReplacement(input: {
+        pullRequest: PullRequestRef;
+        unavailableActor: string;
+        replacementActor: string;
+        signal?: AbortSignal;
+        assertAuthorized?: () => Promise<void>;
+    }): Promise<{
+        changed: boolean;
+    }>;
+    classifyReviewerReplacementError(error: unknown): ReviewerReplacementErrorClassification;
+    upsertRoutingComment(input: {
+        pullRequest: PullRequestRef;
+        decisionId: string;
+        body: string;
+    }): Promise<void>;
+    requestHumanReviewers(input: {
+        pullRequest: PullRequestRef;
+        reviewers: string[];
+    }): Promise<void>;
+    syncRiskLabel(input: {
+        pullRequest: PullRequestRef;
+        tier: RiskTier;
+    }): Promise<void>;
+    submitPolicyApproval(input: {
+        pullRequest: PullRequestRef;
+        expectedHeadSha: string;
+        decisionId: string;
+        body: string;
+    }): Promise<void>;
+    listPullRequestReviews(input: {
+        pullRequest: PullRequestRef;
+    }): Promise<PullRequestReview[]>;
+    private listReviewerReplacementReviews;
+    createHumanReviewPolicyCheck(input: {
+        checkRun: CheckRunRef;
+        decisionId: string;
+        state: "in_progress" | "success" | "failure";
+        summary: string;
+    }): Promise<{
+        checkRunId: string;
+    }>;
+    findHumanReviewPolicyCheck(input: {
+        checkRun: CheckRunRef;
+        decisionId: string;
+        appId: number;
+    }): Promise<{
+        checkRunId: string;
+        state: "in_progress" | "success" | "failure";
+    } | null>;
+    updateHumanReviewPolicyCheck(input: {
+        checkRun: CheckRunRef;
+        checkRunId: string;
+        state: "success" | "failure";
+        summary: string;
+    }): Promise<void>;
+    writeRoutingCheck(input: {
+        checkRun: CheckRunRef;
+        decisionId: string;
+        conclusion: "success" | "neutral" | "failure";
+        summary: string;
+    }): Promise<void>;
+}
+export declare function githubRepositoryUrl(repository: Pick<ContractRepositoryRef, "owner" | "name">): string;
+export declare function githubChangeRequestUrl(repository: Pick<ContractRepositoryRef, "owner" | "name">, changeRequestNumber: number): string;
+export declare function parseGitHubPullRequestUrl(value: unknown): PullRequestRef | null;
+export {};

package/dist/adapter.js

@@ -0,0 +1,632 @@
+import { App } from "@octokit/app";
+const PAGE_SIZE = 100;
+const HUMAN_REVIEW_POLICY_CHECK_NAME = "triagepilot/human-review-policy";
+const RISK_LABELS = {
+    low: { name: "triagepilot:risk-low", color: "0e8a16", description: "TriagePilot risk: low" },
+    medium: { name: "triagepilot:risk-medium", color: "fbca04", description: "TriagePilot risk: medium" },
+    high: { name: "triagepilot:risk-high", color: "b60205", description: "TriagePilot risk: high" },
+};
+const CONFIGURATION_PATHS = [".triagepilot.yml", ".github/triagepilot.yml"];
+export class GitHubConfigurationSource {
+    octokit;
+    constructor(octokit) {
+        this.octokit = octokit;
+    }
+    async loadOrganization(_workspaceId) {
+        return null;
+    }
+    async loadRepository(input) {
+        for (const path of CONFIGURATION_PATHS) {
+            try {
+                const response = await this.octokit.request("GET /repos/{owner}/{repo}/contents/{path}", {
+                    owner: input.repository.owner,
+                    repo: input.repository.name,
+                    path,
+                    ref: input.trustedRevision,
+                });
+                return {
+                    content: decodeGitHubContent(response.data),
+                    revision: input.trustedRevision,
+                    path,
+                };
+            }
+            catch (error) {
+                if (!isGitHubStatus(error, 404))
+                    throw error;
+            }
+        }
+        return null;
+    }
+}
+class GitHubReviewerReplacementProtocolError extends Error {
+}
+class GitHubReviewerReplacementInputError extends Error {
+}
+export async function createInstallationRequester(input) {
+    const app = new App({ appId: input.appId, privateKey: input.privateKey });
+    return app.getInstallationOctokit(input.installationId);
+}
+export class GitHubAdapter {
+    octokit;
+    constructor(octokit) {
+        this.octokit = octokit;
+    }
+    async fetchDefaultBranchRevision(repository) {
+        const repositoryResponse = await this.octokit.request("GET /repos/{owner}/{repo}", {
+            owner: repository.owner,
+            repo: repository.name,
+        });
+        const defaultBranch = readRequiredString(repositoryResponse.data, "default_branch", "GitHub repository default branch");
+        const commitResponse = await this.octokit.request("GET /repos/{owner}/{repo}/commits/{ref}", {
+            owner: repository.owner,
+            repo: repository.name,
+            ref: defaultBranch,
+        });
+        return readRequiredString(commitResponse.data, "sha", "GitHub default branch revision");
+    }
+    async fetchRoutingRecoveryState(input) {
+        let response;
+        try {
+            response = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}", {
+                ...toPullParams(input.pullRequest),
+            });
+        }
+        catch (error) {
+            if (isGitHubStatus(error, 404))
+                return null;
+            throw error;
+        }
+        if (!isRecord(response.data)
+            || !isRecord(response.data.base)
+            || !isRecord(response.data.head)
+            || typeof response.data.draft !== "boolean") {
+            throw new GitHubReviewerReplacementProtocolError("GitHub pull request routing state is unavailable");
+        }
+        try {
+            return {
+                state: readRequiredString(response.data, "state", "GitHub pull request state").toLowerCase(),
+                baseRevision: readRequiredString(response.data.base, "sha", "GitHub pull request base revision"),
+                headRevision: readRequiredString(response.data.head, "sha", "GitHub pull request head revision"),
+                isDraft: response.data.draft,
+            };
+        }
+        catch {
+            throw new GitHubReviewerReplacementProtocolError("GitHub pull request routing state is unavailable");
+        }
+    }
+    async inspectReviewerReplacement(input) {
+        const response = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}", {
+            ...toPullParams(input.pullRequest),
+        });
+        if (!isRecord(response.data) || !isRecord(response.data.head) || !isRecord(response.data.user)) {
+            throw new GitHubReviewerReplacementProtocolError("GitHub pull request replacement state is unavailable");
+        }
+        const state = readReviewerReplacementString(response.data, "state", "GitHub pull request state");
+        const currentHeadRevision = readReviewerReplacementString(response.data.head, "sha", "GitHub pull request head revision");
+        const authorActor = normalizeGitHubActor(readReviewerReplacementString(response.data.user, "login", "GitHub pull request author"));
+        const requestedActors = await this.listRequestedReviewers(input);
+        const reviews = (await this.listReviewerReplacementReviews(input)).map((review) => ({
+            actor: normalizeGitHubActor(review.userLogin),
+            actorType: review.userType === "Bot" ? "bot" : "human",
+            state: review.state.toLowerCase(),
+            commitId: review.commitId,
+            submittedAt: review.submittedAt,
+        }));
+        return { state, currentHeadRevision, authorActor, requestedActors, reviews };
+    }
+    async listRequestedReviewers(input) {
+        await assertProviderMutationAuthorized(input);
+        const reviewers = new Set();
+        const response = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers", { ...toPullParams(input.pullRequest), ...providerRequestSignal(input.signal) });
+        const users = readRequestedReviewerUsers(response.data);
+        for (const user of users) {
+            if (!isRecord(user) || typeof user.login !== "string" || user.login.trim().length === 0) {
+                throw new GitHubReviewerReplacementProtocolError("GitHub requested reviewer user is malformed");
+            }
+            reviewers.add(normalizeGitHubActor(user.login));
+        }
+        return [...reviewers];
+    }
+    async reconcileReviewerReplacement(input) {
+        const unavailableActor = normalizeGitHubIndividualActor(input.unavailableActor);
+        const replacementActor = normalizeGitHubIndividualActor(input.replacementActor);
+        if (unavailableActor === replacementActor) {
+            throw new GitHubReviewerReplacementInputError("GitHub unavailable and replacement actors must differ");
+        }
+        const requestedBeforeRemoval = await this.listRequestedReviewers(input);
+        let changed = false;
+        if (requestedBeforeRemoval.includes(unavailableActor)) {
+            await assertProviderMutationAuthorized(input);
+            await this.octokit.request("DELETE /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers", {
+                ...toPullParams(input.pullRequest),
+                reviewers: [unavailableActor.slice(1)],
+                team_reviewers: [],
+                ...providerRequestSignal(input.signal),
+            });
+            changed = true;
+        }
+        const requestedBeforeAddition = await this.listRequestedReviewers(input);
+        if (!requestedBeforeAddition.includes(replacementActor)) {
+            await assertProviderMutationAuthorized(input);
+            await this.octokit.request("POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers", {
+                ...toPullParams(input.pullRequest),
+                reviewers: [replacementActor.slice(1)],
+                team_reviewers: [],
+                ...providerRequestSignal(input.signal),
+            });
+            changed = true;
+        }
+        return { changed };
+    }
+    classifyReviewerReplacementError(error) {
+        const message = error instanceof Error ? error.message : readOptionalString(error, "message") ?? "provider failed";
+        const status = readOptionalNumber(error, "status");
+        const retryableLimit = hasRetryableReviewerReplacementSignal(error, message);
+        return {
+            kind: error instanceof GitHubReviewerReplacementProtocolError
+                || error instanceof GitHubReviewerReplacementInputError
+                || (status !== null && [400, 401, 403, 404, 410, 422].includes(status) && !retryableLimit)
+                ? "permanent"
+                : "retryable",
+            message,
+        };
+    }
+    async upsertRoutingComment(input) {
+        const marker = decisionMarker(input.decisionId);
+        const existing = await findPaginated(async (page) => {
+            const comments = await this.octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+                ...toIssueParams(input.pullRequest),
+                page,
+                per_page: PAGE_SIZE,
+            });
+            return Array.isArray(comments.data) ? comments.data : [];
+        }, (comment) => isCommentWithMarker(comment, marker));
+        const body = `${marker}\n${input.body}`;
+        if (isCommentWithId(existing)) {
+            await this.octokit.request("PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}", {
+                ...toRepositoryParams(input.pullRequest),
+                comment_id: existing.id,
+                body,
+            });
+            return;
+        }
+        await this.octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+            ...toIssueParams(input.pullRequest),
+            body,
+        });
+    }
+    async requestHumanReviewers(input) {
+        const handles = [...new Set(input.reviewers)].slice(0, 2).map((reviewer) => reviewer.replace(/^@/, ""));
+        const reviewers = handles.filter((handle) => !handle.includes("/"));
+        const teamReviewers = handles
+            .filter((handle) => handle.includes("/"))
+            .map((handle) => handle.slice(handle.indexOf("/") + 1));
+        await this.octokit.request("POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers", {
+            ...toPullParams(input.pullRequest),
+            reviewers,
+            team_reviewers: teamReviewers,
+        });
+    }
+    async syncRiskLabel(input) {
+        const target = RISK_LABELS[input.tier];
+        try {
+            await this.octokit.request("POST /repos/{owner}/{repo}/labels", {
+                ...toRepositoryParams(input.pullRequest),
+                ...target,
+            });
+        }
+        catch (error) {
+            if (!isGitHubStatus(error, 422))
+                throw error;
+        }
+        const labels = [];
+        for (let page = 1;; page += 1) {
+            const response = await this.octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}/labels", {
+                ...toIssueParams(input.pullRequest),
+                page,
+                per_page: PAGE_SIZE,
+            });
+            const records = Array.isArray(response.data) ? response.data : [];
+            labels.push(...records);
+            if (records.length < PAGE_SIZE)
+                break;
+        }
+        const managedNames = new Set(Object.values(RISK_LABELS).map((label) => label.name));
+        for (const label of labels) {
+            const name = readLabelName(label);
+            if (name === undefined || name === target.name || !managedNames.has(name))
+                continue;
+            await this.octokit.request("DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}", {
+                ...toIssueParams(input.pullRequest),
+                name,
+            });
+        }
+        await this.octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/labels", {
+            ...toIssueParams(input.pullRequest),
+            labels: [target.name],
+        });
+    }
+    async submitPolicyApproval(input) {
+        const marker = decisionMarker(input.decisionId);
+        const existing = await findPaginated(async (page) => {
+            const reviews = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews", {
+                ...toPullParams(input.pullRequest),
+                page,
+                per_page: PAGE_SIZE,
+            });
+            return Array.isArray(reviews.data) ? reviews.data : [];
+        }, (review) => hasBodyMarker(review, marker));
+        if (existing !== undefined)
+            return;
+        await this.octokit.request("POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews", {
+            ...toPullParams(input.pullRequest),
+            commit_id: input.expectedHeadSha,
+            event: "APPROVE",
+            body: `${marker}\n${input.body}`,
+        });
+    }
+    async listPullRequestReviews(input) {
+        const reviews = [];
+        for (let page = 1;; page += 1) {
+            const response = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews", {
+                ...toPullParams(input.pullRequest),
+                page,
+                per_page: PAGE_SIZE,
+            });
+            const records = Array.isArray(response.data) ? response.data : [];
+            for (const record of records) {
+                const review = readPullRequestReview(record, false);
+                if (review !== undefined)
+                    reviews.push(review);
+            }
+            if (records.length < PAGE_SIZE)
+                return reviews;
+        }
+    }
+    async listReviewerReplacementReviews(input) {
+        const reviews = [];
+        for (let page = 1;; page += 1) {
+            const response = await this.octokit.request("GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews", {
+                ...toPullParams(input.pullRequest),
+                page,
+                per_page: PAGE_SIZE,
+            });
+            if (!Array.isArray(response.data)) {
+                throw new GitHubReviewerReplacementProtocolError("GitHub pull request reviews response is malformed");
+            }
+            for (const record of response.data)
+                reviews.push(readPullRequestReview(record, true));
+            if (response.data.length < PAGE_SIZE)
+                return reviews;
+        }
+    }
+    async createHumanReviewPolicyCheck(input) {
+        const response = await this.octokit.request("POST /repos/{owner}/{repo}/check-runs", {
+            ...toRepositoryParams(input.checkRun),
+            head_sha: input.checkRun.headSha,
+            external_id: input.decisionId,
+            ...humanReviewPolicyCheckPayload(input),
+        });
+        if (!isCheckRunWithId(response.data))
+            throw new Error("GitHub did not return a check run ID");
+        return { checkRunId: String(response.data.id) };
+    }
+    async findHumanReviewPolicyCheck(input) {
+        const matches = [];
+        for (let page = 1;; page += 1) {
+            const checks = await this.octokit.request("GET /repos/{owner}/{repo}/commits/{ref}/check-runs", {
+                ...toRepositoryParams(input.checkRun),
+                ref: input.checkRun.headSha,
+                check_name: HUMAN_REVIEW_POLICY_CHECK_NAME,
+                app_id: input.appId,
+                filter: "all",
+                page,
+                per_page: PAGE_SIZE,
+            });
+            const records = readCheckRuns(checks.data);
+            for (const check of records) {
+                if (!isCheckRunWithId(check) || !isHumanReviewPolicyCheckRun(check, input.decisionId, input.appId))
+                    continue;
+                const state = readHumanReviewPolicyCheckState(check);
+                if (state !== null)
+                    matches.push({ id: check.id, state });
+            }
+            if (records.length < PAGE_SIZE)
+                break;
+        }
+        const existing = matches.sort((left, right) => compareCheckRunIds(right.id, left.id))[0];
+        if (!isCheckRunWithId(existing))
+            return null;
+        return { checkRunId: String(existing.id), state: existing.state };
+    }
+    async updateHumanReviewPolicyCheck(input) {
+        await this.octokit.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
+            ...toRepositoryParams(input.checkRun),
+            check_run_id: input.checkRunId,
+            ...completedHumanReviewPolicyCheckPayload(input),
+        });
+    }
+    async writeRoutingCheck(input) {
+        const existing = await findPaginated(async (page) => {
+            const checks = await this.octokit.request("GET /repos/{owner}/{repo}/commits/{ref}/check-runs", {
+                ...toRepositoryParams(input.checkRun),
+                ref: input.checkRun.headSha,
+                check_name: "triagepilot/routing",
+                filter: "all",
+                page,
+                per_page: PAGE_SIZE,
+            });
+            return readCheckRuns(checks.data);
+        }, (check) => isDecisionCheckRun(check, input.decisionId));
+        const check = {
+            name: "triagepilot/routing",
+            external_id: input.decisionId,
+            status: "completed",
+            conclusion: input.conclusion,
+            output: {
+                title: "TriagePilot routing",
+                summary: input.summary,
+            },
+        };
+        if (isCheckRunWithId(existing)) {
+            await this.octokit.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
+                ...toRepositoryParams(input.checkRun),
+                check_run_id: existing.id,
+                ...check,
+            });
+            return;
+        }
+        await this.octokit.request("POST /repos/{owner}/{repo}/check-runs", {
+            ...toRepositoryParams(input.checkRun),
+            head_sha: input.checkRun.headSha,
+            ...check,
+        });
+    }
+}
+async function assertProviderMutationAuthorized(input) {
+    input.signal?.throwIfAborted();
+    await input.assertAuthorized?.();
+    input.signal?.throwIfAborted();
+}
+function providerRequestSignal(signal) {
+    return signal === undefined ? {} : { request: { signal } };
+}
+export function githubRepositoryUrl(repository) {
+    return `https://github.com/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.name)}`;
+}
+export function githubChangeRequestUrl(repository, changeRequestNumber) {
+    return `${githubRepositoryUrl(repository)}/pull/${changeRequestNumber}`;
+}
+export function parseGitHubPullRequestUrl(value) {
+    if (typeof value !== "string" || value.trim() !== value || value.length === 0)
+        return null;
+    try {
+        const url = new URL(value);
+        const match = /^\/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]+)\/pull\/([1-9][0-9]*)\/?$/.exec(url.pathname);
+        if (url.protocol !== "https:"
+            || url.hostname !== "github.com"
+            || url.port !== ""
+            || url.username !== ""
+            || url.password !== ""
+            || url.search !== ""
+            || url.hash !== ""
+            || match === null)
+            return null;
+        const pullNumber = Number(match[3]);
+        if (!Number.isSafeInteger(pullNumber) || pullNumber > 2_147_483_647)
+            return null;
+        return { owner: match[1], repo: match[2], pullNumber };
+    }
+    catch {
+        return null;
+    }
+}
+function toRepositoryParams(ref) {
+    return { owner: ref.owner, repo: ref.repo };
+}
+function toPullParams(ref) {
+    return { ...toRepositoryParams(ref), pull_number: ref.pullNumber };
+}
+function toIssueParams(ref) {
+    return { ...toRepositoryParams(ref), issue_number: ref.pullNumber };
+}
+function decisionMarker(decisionId) {
+    return `<!-- triagepilot:decision:${decisionId} -->`;
+}
+function isCommentWithMarker(comment, marker) {
+    return typeof comment === "object" && comment !== null && "body" in comment && String(comment.body).startsWith(marker);
+}
+function isCommentWithId(comment) {
+    return typeof comment === "object" && comment !== null && "id" in comment;
+}
+function readLabelName(label) {
+    if (typeof label !== "object" || label === null || !("name" in label))
+        return undefined;
+    const name = String(label.name).trim();
+    return name || undefined;
+}
+function readRequiredString(value, key, label) {
+    if (!isRecord(value) || typeof value[key] !== "string" || value[key].trim().length === 0) {
+        throw new Error(`${label} is unavailable`);
+    }
+    return value[key].trim();
+}
+function decodeGitHubContent(data) {
+    if (!isRecord(data) || typeof data.content !== "string")
+        return "";
+    return Buffer.from(data.content.replace(/\s/g, ""), "base64").toString("utf8");
+}
+function isGitHubStatus(error, status) {
+    return typeof error === "object" && error !== null && "status" in error && error.status === status;
+}
+function readCheckRuns(data) {
+    if (typeof data !== "object" || data === null || !("check_runs" in data))
+        return [];
+    return Array.isArray(data.check_runs) ? data.check_runs : [];
+}
+function isDecisionCheckRun(check, decisionId) {
+    return (typeof check === "object" &&
+        check !== null &&
+        "name" in check &&
+        check.name === "triagepilot/routing" &&
+        "external_id" in check &&
+        check.external_id === decisionId);
+}
+function isHumanReviewPolicyCheckRun(check, decisionId, appId) {
+    return (isRecord(check) &&
+        check.name === HUMAN_REVIEW_POLICY_CHECK_NAME &&
+        check.external_id === decisionId &&
+        isRecord(check.app) &&
+        check.app.id === appId);
+}
+function compareCheckRunIds(left, right) {
+    const leftId = BigInt(String(left));
+    const rightId = BigInt(String(right));
+    return leftId < rightId ? -1 : leftId > rightId ? 1 : 0;
+}
+function readHumanReviewPolicyCheckState(check) {
+    if (!isRecord(check))
+        return null;
+    if (check.status !== "completed")
+        return "in_progress";
+    return check.conclusion === "success" || check.conclusion === "failure" ? check.conclusion : null;
+}
+function isCheckRunWithId(check) {
+    return typeof check === "object" && check !== null && "id" in check;
+}
+function humanReviewPolicyCheckPayload(input) {
+    const check = {
+        name: HUMAN_REVIEW_POLICY_CHECK_NAME,
+        output: {
+            title: "TriagePilot human review policy",
+            summary: input.summary,
+        },
+    };
+    if (input.state === "in_progress")
+        return { ...check, status: "in_progress" };
+    return { ...check, status: "completed", conclusion: input.state };
+}
+function completedHumanReviewPolicyCheckPayload(input) {
+    return {
+        name: HUMAN_REVIEW_POLICY_CHECK_NAME,
+        status: "completed",
+        conclusion: input.state,
+        output: {
+            title: "TriagePilot human review policy",
+            summary: input.summary,
+        },
+    };
+}
+function readPullRequestReview(value, strict) {
+    if (!isRecord(value)
+        || !isRecord(value.user)
+        || typeof value.user.login !== "string"
+        || typeof value.state !== "string"
+        || value.user.login.trim().length === 0
+        || value.state.trim().length === 0) {
+        if (strict)
+            throw new GitHubReviewerReplacementProtocolError("GitHub pull request review is malformed");
+        return undefined;
+    }
+    if (strict
+        && (typeof value.user.type !== "string"
+            || (value.user.type !== "User" && value.user.type !== "Bot")
+            || !("commit_id" in value)
+            || !("submitted_at" in value)
+            || (typeof value.commit_id !== "string" && value.commit_id !== null)
+            || (typeof value.submitted_at !== "string" && value.submitted_at !== null)
+            || (typeof value.commit_id === "string" && value.commit_id.trim().length === 0)
+            || (typeof value.submitted_at === "string" && value.submitted_at.trim().length === 0))) {
+        throw new GitHubReviewerReplacementProtocolError("GitHub pull request review is malformed");
+    }
+    return {
+        userLogin: value.user.login,
+        ...(typeof value.user.type === "string" ? { userType: value.user.type } : {}),
+        state: value.state,
+        commitId: typeof value.commit_id === "string" ? value.commit_id : null,
+        submittedAt: typeof value.submitted_at === "string" ? value.submitted_at : null,
+    };
+}
+function readRequestedReviewerUsers(value) {
+    if (!isRecord(value) || !Array.isArray(value.users)) {
+        throw new GitHubReviewerReplacementProtocolError("GitHub requested reviewers response is malformed");
+    }
+    return value.users;
+}
+function readReviewerReplacementString(value, key, label) {
+    if (!isRecord(value) || typeof value[key] !== "string" || value[key].trim().length === 0) {
+        throw new GitHubReviewerReplacementProtocolError(`${label} is unavailable`);
+    }
+    return value[key].trim();
+}
+function normalizeGitHubActor(value) {
+    const login = value.trim().replace(/^@/, "").toLowerCase();
+    if (login.length === 0)
+        throw new Error("GitHub actor login is unavailable");
+    return `@${login}`;
+}
+function normalizeGitHubIndividualActor(value) {
+    let actor;
+    try {
+        actor = normalizeGitHubActor(value);
+    }
+    catch {
+        throw new GitHubReviewerReplacementInputError("GitHub reviewer actor login is unavailable");
+    }
+    if (actor.includes("/")) {
+        throw new GitHubReviewerReplacementInputError("GitHub reviewer actor must identify an individual user");
+    }
+    return actor;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function readOptionalString(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : null;
+}
+function readOptionalNumber(value, key) {
+    return isRecord(value) && typeof value[key] === "number" ? value[key] : null;
+}
+function hasRetryableReviewerReplacementSignal(error, message) {
+    const status = readOptionalNumber(error, "status");
+    if (status === 429)
+        return true;
+    if (status !== 403 && status !== 422)
+        return false;
+    const headers = isRecord(error) && isRecord(error.response) && isRecord(error.response.headers)
+        ? error.response.headers
+        : null;
+    const retryAfter = readHeader(headers, "retry-after");
+    const remaining = readHeader(headers, "x-ratelimit-remaining");
+    const normalizedMessage = message.toLowerCase();
+    return retryAfter !== null
+        || remaining === "0"
+        || normalizedMessage.includes("rate limit")
+        || normalizedMessage.includes("secondary limit")
+        || normalizedMessage.includes("abuse")
+        || normalizedMessage.includes("spam")
+        || normalizedMessage.includes("submitted too quickly");
+}
+function readHeader(headers, name) {
+    if (headers === null)
+        return null;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && (typeof value === "string" || typeof value === "number")) {
+            return String(value).trim();
+        }
+    }
+    return null;
+}
+function hasBodyMarker(value, marker) {
+    return typeof value === "object" && value !== null && "body" in value && String(value.body).includes(marker);
+}
+async function findPaginated(fetchPage, predicate) {
+    for (let page = 1;; page += 1) {
+        const values = await fetchPage(page);
+        const match = values.find(predicate);
+        if (match !== undefined)
+            return match;
+        if (values.length < PAGE_SIZE)
+            return undefined;
+    }
+}

package/dist/credentials.d.ts

@@ -0,0 +1,24 @@
+import type { CredentialProvider, ProviderConnectionId, WorkspaceId } from "@triagepilot/contracts";
+export interface GitHubAppCredentials {
+    appId: string;
+    privateKey: string;
+}
+export interface GitHubAppCredentialShape extends GitHubAppCredentials {
+    webhookSecret: string;
+}
+export declare class GitHubCredentialProvider implements CredentialProvider<GitHubAppCredentials> {
+    private readonly credential;
+    constructor(credential: GitHubAppCredentials);
+    getCredential(_input: {
+        workspaceId: WorkspaceId;
+        providerConnectionId: ProviderConnectionId;
+    }): Promise<GitHubAppCredentials>;
+}
+export declare function validateGitHubAppCredentials(input: GitHubAppCredentials): {
+    appId: string;
+};
+export declare function validateGitHubAppCredentialsShape(input: GitHubAppCredentialShape): {
+    appId: string;
+};
+export declare function loadGitHubAppCredentials(source: NodeJS.ProcessEnv): Promise<GitHubAppCredentials>;
+export declare function loadGitHubCredentials(source: NodeJS.ProcessEnv): Promise<GitHubAppCredentialShape>;

package/dist/credentials.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+export class GitHubCredentialProvider {
+    credential;
+    constructor(credential) {
+        this.credential = credential;
+        validateGitHubAppCredentials(credential);
+    }
+    async getCredential(_input) {
+        return { ...this.credential };
+    }
+}
+async function readSecret(source, directName, fileName) {
+    const direct = source[directName]?.trim();
+    const file = source[fileName]?.trim();
+    if (direct && file) {
+        throw new Error(`${directName} and ${fileName} cannot both be set`);
+    }
+    const value = file ? (await readFile(file, "utf8")).trim() : direct;
+    if (!value) {
+        throw new Error(`${directName} or ${fileName} is required`);
+    }
+    return value;
+}
+export function validateGitHubAppCredentials(input) {
+    if (!input.appId.trim()) {
+        throw new Error("GitHub App ID is required");
+    }
+    if (!input.privateKey.includes("-----BEGIN") || !input.privateKey.includes("PRIVATE KEY-----")) {
+        throw new Error("GitHub private key must be PEM formatted");
+    }
+    return { appId: input.appId.trim() };
+}
+export function validateGitHubAppCredentialsShape(input) {
+    const validated = validateGitHubAppCredentials(input);
+    if (!input.webhookSecret.trim()) {
+        throw new Error("GitHub webhook secret is required");
+    }
+    return validated;
+}
+export async function loadGitHubAppCredentials(source) {
+    const credentials = {
+        appId: source.GITHUB_APP_ID?.trim() ?? "",
+        privateKey: (await readSecret(source, "GITHUB_PRIVATE_KEY", "GITHUB_PRIVATE_KEY_FILE")).replace(/\\n/g, "\n"),
+    };
+    validateGitHubAppCredentials(credentials);
+    return credentials;
+}
+export async function loadGitHubCredentials(source) {
+    const credentials = {
+        ...(await loadGitHubAppCredentials(source)),
+        webhookSecret: await readSecret(source, "GITHUB_WEBHOOK_SECRET", "GITHUB_WEBHOOK_SECRET_FILE"),
+    };
+    validateGitHubAppCredentialsShape(credentials);
+    return credentials;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createInstallationRequester, GitHubAdapter, GitHubConfigurationSource, githubChangeRequestUrl, githubRepositoryUrl, parseGitHubPullRequestUrl, type CheckRunRef, type PullRequestRef, type PullRequestReview, type GitHubReviewerReplacementState, type GitHubRoutingRecoveryState, type ReviewerReplacementErrorClassification, type RepositoryRef, } from "./adapter.js";
+export { GitHubCredentialProvider, loadGitHubAppCredentials, loadGitHubCredentials, validateGitHubAppCredentials, validateGitHubAppCredentialsShape, type GitHubAppCredentials, type GitHubAppCredentialShape, } from "./credentials.js";
+export { normalizeGitHubWebhook, type GitHubWebhookInput, type NormalizedGitHubWebhookEvent, } from "./normalization.js";
+export { verifyGitHubSignature } from "./webhook.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createInstallationRequester, GitHubAdapter, GitHubConfigurationSource, githubChangeRequestUrl, githubRepositoryUrl, parseGitHubPullRequestUrl, } from "./adapter.js";
+export { GitHubCredentialProvider, loadGitHubAppCredentials, loadGitHubCredentials, validateGitHubAppCredentials, validateGitHubAppCredentialsShape, } from "./credentials.js";
+export { normalizeGitHubWebhook, } from "./normalization.js";
+export { verifyGitHubSignature } from "./webhook.js";

package/dist/normalization.d.ts

@@ -0,0 +1,14 @@
+import type { NormalizedChangeRequestEvent } from "@triagepilot/contracts";
+export interface GitHubWebhookInput {
+    deliveryId: string;
+    eventName: string;
+    payload: unknown;
+}
+export interface NormalizedGitHubWebhookEvent extends NormalizedChangeRequestEvent {
+    provider: "github";
+    providerAccount: {
+        login: string;
+        type: string;
+    };
+}
+export declare function normalizeGitHubWebhook(input: GitHubWebhookInput): NormalizedGitHubWebhookEvent | null;

package/dist/normalization.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+const ROUTING_PULL_REQUEST_ACTIONS = new Set(["opened", "reopened", "synchronize", "ready_for_review"]);
+const REVIEW_PULL_REQUEST_ACTIONS = new Set(["submitted", "edited", "dismissed"]);
+const githubIdSchema = z.union([
+    z.number().int().safe().transform(String),
+    z.string().trim().regex(/^\d+$/),
+]);
+const pullRequestWebhookSchema = z.object({
+    action: z.string(),
+    installation: z.object({ id: githubIdSchema }),
+    sender: z.object({
+        id: githubIdSchema,
+        login: z.string().trim().min(1),
+    }),
+    repository: z.object({
+        id: githubIdSchema,
+        name: z.string().trim().min(1),
+        owner: z.object({ login: z.string().trim().min(1), type: z.string().trim().min(1) }),
+    }),
+    pull_request: z.object({
+        id: githubIdSchema,
+        number: z.number().int().positive(),
+        draft: z.boolean(),
+        base: z.object({ sha: z.string().trim().min(1) }),
+        head: z.object({ sha: z.string().trim().min(1) }),
+    }),
+});
+const pullRequestReviewWebhookSchema = pullRequestWebhookSchema.extend({
+    review: z.object({ state: z.string().trim().min(1) }),
+});
+export function normalizeGitHubWebhook(input) {
+    if (input.eventName === "pull_request") {
+        const payload = pullRequestWebhookSchema.parse(input.payload);
+        if (!ROUTING_PULL_REQUEST_ACTIONS.has(payload.action))
+            return null;
+        return toNormalizedEvent(input.deliveryId, "change_request", payload);
+    }
+    if (input.eventName === "pull_request_review") {
+        const payload = pullRequestReviewWebhookSchema.parse(input.payload);
+        if (!REVIEW_PULL_REQUEST_ACTIONS.has(payload.action))
+            return null;
+        return toNormalizedEvent(input.deliveryId, "change_request_review", payload);
+    }
+    return null;
+}
+function toNormalizedEvent(deliveryId, eventName, payload) {
+    return {
+        deliveryId,
+        eventName,
+        eventAction: payload.action,
+        provider: "github",
+        externalConnectionId: payload.installation.id,
+        providerAccount: {
+            login: payload.repository.owner.login,
+            type: payload.repository.owner.type,
+        },
+        changeRequest: {
+            repository: {
+                provider: "github",
+                externalId: payload.repository.id,
+                owner: payload.repository.owner.login,
+                name: payload.repository.name,
+            },
+            externalId: String(payload.pull_request.number),
+            number: payload.pull_request.number,
+            baseRevision: payload.pull_request.base.sha,
+            headRevision: payload.pull_request.head.sha,
+        },
+        actor: {
+            externalId: payload.sender.id,
+            displayName: payload.sender.login,
+        },
+        isDraft: payload.pull_request.draft,
+    };
+}

package/dist/webhook.d.ts

@@ -0,0 +1,5 @@
+export declare function verifyGitHubSignature(input: {
+    body: string;
+    secret: string;
+    signature: string | null;
+}): Promise<void>;

package/dist/webhook.js

@@ -0,0 +1,12 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export async function verifyGitHubSignature(input) {
+    if (!input.signature?.startsWith("sha256=")) {
+        throw new Error("Invalid GitHub webhook signature");
+    }
+    const expected = `sha256=${createHmac("sha256", input.secret).update(input.body).digest("hex")}`;
+    const expectedBuffer = Buffer.from(expected);
+    const actualBuffer = Buffer.from(input.signature);
+    if (expectedBuffer.length !== actualBuffer.length || !timingSafeEqual(expectedBuffer, actualBuffer)) {
+        throw new Error("Invalid GitHub webhook signature");
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@triagepilot/provider-github",
+  "version": "1.1.0",
+  "license": "FSL-1.1-Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TriagePilot/triage-pilot.git",
+    "directory": "packages/provider-github"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@types/node": "^22.10.2",
+    "@triagepilot/contracts": "1.1.0",
+    "@octokit/app": "^15.1.2",
+    "@octokit/request": "^9.1.4",
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "publishedAt": "2026-09-22T09:41:47.000Z",
+  "futureLicenseEffectiveAt": "2028-09-22T09:41:47.000Z",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}