@wardby/cli 0.1.0

package/dist/providers/vcs/github.d.ts

@@ -0,0 +1,105 @@
+export interface GitHubAppConfig {
+    appId: string;
+    privateKey: string;
+    apiBaseUrl?: string;
+    apiVersion?: string;
+}
+export interface PullRequestTestResult {
+    command: string;
+    outcome: "passed" | "failed" | "skipped";
+}
+export interface PullRequestInput {
+    runId: string;
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    /** Already-validated/redacted agent-authored fields (coding/protocol.ts); optional for callers with none. */
+    summary?: string;
+    tests?: readonly PullRequestTestResult[];
+    tag?: string;
+}
+export interface PullRequestResult {
+    number: number;
+    url: string;
+}
+/** See VcsProvider.notifyContinuationStarted/Finished (types.ts) — these back that GitHub-specific mechanism. */
+export interface ContinuationStatusCommentInput {
+    /** This continuation round's own run id — the comment's identity/marker key. */
+    runId: string;
+    /** The run whose PR this belongs to (used only to re-find the PR via the existing marker lookup). */
+    rootRunId: string;
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    body: string;
+}
+export interface ContinuationCheckRunInput {
+    repository: string;
+    headSha: string;
+    /** Stored as the check run's external_id — the re-lookup key, so no numeric id needs to be cached anywhere. */
+    runId: string;
+}
+export interface ContinuationCheckRunCompleteInput extends ContinuationCheckRunInput {
+    outcome: "succeeded" | "failed";
+}
+export interface GitHubRepositoryAccess {
+    withRepositoryToken<T>(repository: string, action: (token: string) => Promise<T>): Promise<T>;
+    createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
+    /** Creates the status comment if none exists yet for this run, else updates it. */
+    upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
+    /** Updates the status comment if one already exists for this run; a no-op otherwise (never creates). */
+    updateContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
+    /** Creates an in-progress check run if none exists yet for this run+commit; a no-op if one already does. */
+    createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;
+    /** Completes the check run if one exists for this run+commit; a no-op otherwise (never creates). */
+    completeContinuationCheckRun(input: ContinuationCheckRunCompleteInput): Promise<void>;
+}
+type Fetch = typeof globalThis.fetch;
+/** Accepts bounded opaque installation tokens without allowing control characters. */
+export declare function isSafeGitHubInstallationToken(value: unknown): value is string;
+export declare class GitHubAppClient implements GitHubRepositoryAccess {
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly apiBaseUrl;
+    private readonly apiVersion;
+    constructor(config: GitHubAppConfig, fetchImpl?: Fetch, now?: () => Date);
+    withRepositoryToken<T>(repository: string, action: (token: string) => Promise<T>): Promise<T>;
+    /**
+     * Isolated from withRepositoryToken on purpose: "Checks: write" is a
+     * genuinely distinct GitHub App permission from contents/pull_requests
+     * (confirmed empirically). Minting it separately means an ungranted-permission
+     * failure here can only ever disable the check-run mechanism, never the
+     * real git push, PR, or status comment. (Status comments, below, do NOT
+     * need this treatment: PR-comment writes work fine on the existing
+     * contents/pull_requests token -- confirmed empirically after "Issues:
+     * write" alone, on its own isolated token, kept returning 403 "Resource
+     * not accessible by integration" even once granted; commenting on a PR
+     * apparently isn't gated the same way a genuine issue comment might be.)
+     */
+    private withChecksToken;
+    upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
+    updateContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
+    createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;
+    completeContinuationCheckRun(input: ContinuationCheckRunCompleteInput): Promise<void>;
+    createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
+    private appJwt;
+    private mintRepositoryToken;
+    private mintChecksToken;
+    /**
+     * Shared installation-token mint: requests exactly `permissions`, then
+     * verifies the response granted exactly that (no more, no less, modulo
+     * the always-implicit `metadata: read`) before trusting the token. Each
+     * caller requests the narrowest permission set it needs — see
+     * withIssuesToken/withChecksToken for why these are minted separately
+     * from withRepositoryToken rather than requesting a union of everything.
+     */
+    private mintScopedToken;
+    private revokeToken;
+    private findPullRequest;
+    private parsePullRequest;
+    private findStatusComment;
+    private findCheckRun;
+    private requestJson;
+}
+export {};

package/dist/providers/vcs/github.js

@@ -0,0 +1,394 @@
+import { createPrivateKey } from "node:crypto";
+import { importPKCS8, SignJWT } from "jose";
+import { normalizeGitHubRepository, normalizeGitRef } from "../../coding/protocol.js";
+const DEFAULT_API_BASE_URL = "https://api.github.com";
+const DEFAULT_API_VERSION = "2026-03-10";
+const RUN_MARKER_PREFIX = "<!-- wardby:";
+const STATUS_COMMENT_MARKER_PREFIX = "<!-- wardby-status:";
+const CONTINUATION_CHECK_RUN_NAME = "wardby/continuation";
+/** Mirrors coding/protocol.ts's tagSchema — validated independently here since this is where it reaches GitHub. */
+const SAFE_PULL_REQUEST_TAG = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,31}$/;
+/** Mirrors the runId shape validated elsewhere (coding/protocol.ts, git.ts) — validated independently here too. */
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const SAFE_COMMIT_SHA = /^[0-9a-f]{40}$/;
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("github_api_invalid_response");
+    return value;
+}
+function positiveInteger(value) {
+    if (!Number.isSafeInteger(value) || Number(value) <= 0)
+        throw new Error("github_api_invalid_response");
+    return Number(value);
+}
+function safeApiError(response) {
+    const requestId = response.headers.get("x-github-request-id");
+    return new Error(`github_api_error:${response.status}${requestId ? `:${requestId}` : ""}`);
+}
+/** Accepts bounded opaque installation tokens without allowing control characters. */
+export function isSafeGitHubInstallationToken(value) {
+    return (typeof value === "string" &&
+        value.length >= 20 &&
+        Buffer.byteLength(value, "utf8") <= 512 &&
+        /^[A-Za-z0-9._-]+$/.test(value));
+}
+function pullRequestTitle(input) {
+    return input.tag ? `[${input.tag}] Wardby run ${input.runId}` : `Wardby run ${input.runId}`;
+}
+/** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
+function pullRequestBody(input) {
+    const sections = [`${RUN_MARKER_PREFIX}${input.runId} -->`];
+    if (input.summary)
+        sections.push(input.summary);
+    if (input.tests?.length) {
+        sections.push(["**Tests:**", ...input.tests.map((test) => `- \`${test.command}\`: ${test.outcome}`)].join("\n"));
+    }
+    return sections.join("\n\n");
+}
+/** The hidden marker stays first and unconditional: findStatusComment's lookup depends on it. */
+function statusCommentBody(runId, body) {
+    return `${STATUS_COMMENT_MARKER_PREFIX}${runId} -->\n\n${body}`;
+}
+function normalizeApiBaseUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" ||
+        url.hostname.toLowerCase() !== "api.github.com" ||
+        url.port ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/") {
+        throw new Error("github_api_base_url_invalid");
+    }
+    return url.toString().replace(/\/$/, "");
+}
+function normalizePrivateKey(value) {
+    return value.includes("\\n") && !value.includes("\n") ? value.replaceAll("\\n", "\n") : value;
+}
+export class GitHubAppClient {
+    config;
+    fetchImpl;
+    now;
+    apiBaseUrl;
+    apiVersion;
+    constructor(config, fetchImpl = globalThis.fetch, now = () => new Date()) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+        if (!/^[1-9]\d*$/.test(config.appId))
+            throw new Error("github_app_id_invalid");
+        if (!config.privateKey.trim())
+            throw new Error("github_app_private_key_invalid");
+        this.apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
+        this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(this.apiVersion))
+            throw new Error("github_api_version_invalid");
+    }
+    async withRepositoryToken(repository, action) {
+        const normalized = normalizeGitHubRepository(repository);
+        const token = await this.mintRepositoryToken(normalized);
+        try {
+            return await action(token);
+        }
+        finally {
+            await this.revokeToken(token).catch(() => undefined);
+        }
+    }
+    /**
+     * Isolated from withRepositoryToken on purpose: "Checks: write" is a
+     * genuinely distinct GitHub App permission from contents/pull_requests
+     * (confirmed empirically). Minting it separately means an ungranted-permission
+     * failure here can only ever disable the check-run mechanism, never the
+     * real git push, PR, or status comment. (Status comments, below, do NOT
+     * need this treatment: PR-comment writes work fine on the existing
+     * contents/pull_requests token -- confirmed empirically after "Issues:
+     * write" alone, on its own isolated token, kept returning 403 "Resource
+     * not accessible by integration" even once granted; commenting on a PR
+     * apparently isn't gated the same way a genuine issue comment might be.)
+     */
+    async withChecksToken(repository, action) {
+        const normalized = normalizeGitHubRepository(repository);
+        const token = await this.mintChecksToken(normalized);
+        try {
+            return await action(token);
+        }
+        finally {
+            await this.revokeToken(token).catch(() => undefined);
+        }
+    }
+    async upsertContinuationStatusComment(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId) || !SAFE_RUN_ID.test(input.rootRunId)) {
+            throw new Error("github_status_comment_input_invalid");
+        }
+        await this.withRepositoryToken(repository, async (token) => {
+            const pr = await this.findPullRequest(token, { runId: input.rootRunId, repository, baseRef, headRef });
+            if (!pr)
+                return;
+            const existing = await this.findStatusComment(token, repository, pr.number, input.runId);
+            const [owner, name] = repository.split("/");
+            const body = statusCommentBody(input.runId, input.body);
+            if (existing) {
+                await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/comments/${existing.id}`, token, { method: "PATCH", body: JSON.stringify({ body }) }, [200]);
+            }
+            else {
+                await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/${pr.number}/comments`, token, { method: "POST", body: JSON.stringify({ body }) }, [201]);
+            }
+        });
+    }
+    async updateContinuationStatusComment(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId) || !SAFE_RUN_ID.test(input.rootRunId)) {
+            throw new Error("github_status_comment_input_invalid");
+        }
+        await this.withRepositoryToken(repository, async (token) => {
+            const pr = await this.findPullRequest(token, { runId: input.rootRunId, repository, baseRef, headRef });
+            if (!pr)
+                return;
+            const existing = await this.findStatusComment(token, repository, pr.number, input.runId);
+            if (!existing)
+                return;
+            const [owner, name] = repository.split("/");
+            await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/comments/${existing.id}`, token, { method: "PATCH", body: JSON.stringify({ body: statusCommentBody(input.runId, input.body) }) }, [200]);
+        });
+    }
+    async createContinuationCheckRun(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        if (!SAFE_RUN_ID.test(input.runId) || !SAFE_COMMIT_SHA.test(input.headSha)) {
+            throw new Error("github_check_run_input_invalid");
+        }
+        await this.withChecksToken(repository, async (token) => {
+            const existing = await this.findCheckRun(token, repository, input.headSha, input.runId);
+            if (existing)
+                return;
+            const [owner, name] = repository.split("/");
+            await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/check-runs`, token, {
+                method: "POST",
+                body: JSON.stringify({
+                    name: CONTINUATION_CHECK_RUN_NAME,
+                    head_sha: input.headSha,
+                    status: "in_progress",
+                    external_id: input.runId,
+                }),
+            }, [201]);
+        });
+    }
+    async completeContinuationCheckRun(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        if (!SAFE_RUN_ID.test(input.runId) || !SAFE_COMMIT_SHA.test(input.headSha)) {
+            throw new Error("github_check_run_input_invalid");
+        }
+        await this.withChecksToken(repository, async (token) => {
+            const existing = await this.findCheckRun(token, repository, input.headSha, input.runId);
+            if (!existing)
+                return;
+            const [owner, name] = repository.split("/");
+            await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/check-runs/${existing.id}`, token, {
+                method: "PATCH",
+                body: JSON.stringify({
+                    status: "completed",
+                    conclusion: input.outcome === "succeeded" ? "success" : "failure",
+                }),
+            }, [200]);
+        });
+    }
+    async createOrFindDraftPullRequest(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(input.runId) || headRef !== `wardby/run-${input.runId}`) {
+            throw new Error("github_pull_request_input_invalid");
+        }
+        if (input.tag !== undefined && !SAFE_PULL_REQUEST_TAG.test(input.tag)) {
+            throw new Error("github_pull_request_tag_invalid");
+        }
+        return this.withRepositoryToken(repository, async (token) => {
+            const existing = await this.findPullRequest(token, { ...input, repository, baseRef, headRef });
+            if (existing)
+                return existing;
+            const [owner, name] = repository.split("/");
+            const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`, token, {
+                method: "POST",
+                body: JSON.stringify({
+                    title: pullRequestTitle(input),
+                    head: headRef,
+                    base: baseRef,
+                    body: pullRequestBody(input),
+                    draft: true,
+                }),
+            }, [201, 422]);
+            if (response.status === 201)
+                return this.parsePullRequest(await response.json(), repository);
+            const raced = await this.findPullRequest(token, { ...input, repository, baseRef, headRef });
+            if (raced)
+                return raced;
+            throw safeApiError(response);
+        });
+    }
+    async appJwt() {
+        let keyObject;
+        try {
+            keyObject = createPrivateKey(normalizePrivateKey(this.config.privateKey));
+        }
+        catch {
+            throw new Error("github_app_private_key_invalid");
+        }
+        const pkcs8 = keyObject.export({ type: "pkcs8", format: "pem" }).toString();
+        const key = await importPKCS8(pkcs8, "RS256");
+        const now = Math.floor(this.now().getTime() / 1000);
+        return new SignJWT({})
+            .setProtectedHeader({ alg: "RS256", typ: "JWT" })
+            .setIssuedAt(now - 60)
+            .setExpirationTime(now + 9 * 60)
+            .setIssuer(this.config.appId)
+            .sign(key);
+    }
+    async mintRepositoryToken(repository) {
+        return this.mintScopedToken(repository, { contents: "write", pull_requests: "write" }, (name, level) => (name === "contents" && level === "write") ||
+            (name === "pull_requests" && level === "write") ||
+            (name === "metadata" && level === "read"));
+    }
+    async mintChecksToken(repository) {
+        return this.mintScopedToken(repository, { checks: "write" }, (name, level) => (name === "checks" && level === "write") || (name === "metadata" && level === "read"));
+    }
+    /**
+     * Shared installation-token mint: requests exactly `permissions`, then
+     * verifies the response granted exactly that (no more, no less, modulo
+     * the always-implicit `metadata: read`) before trusting the token. Each
+     * caller requests the narrowest permission set it needs — see
+     * withIssuesToken/withChecksToken for why these are minted separately
+     * from withRepositoryToken rather than requesting a union of everything.
+     */
+    async mintScopedToken(repository, permissions, isAllowedPermission) {
+        const [owner, name] = repository.split("/");
+        const appJwt = await this.appJwt();
+        const installationResponse = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/installation`, appJwt);
+        const installation = record(await installationResponse.json());
+        const installationId = positiveInteger(installation.id);
+        const tokenResponse = await this.requestJson(`/app/installations/${installationId}/access_tokens`, appJwt, { method: "POST", body: JSON.stringify({ repositories: [name], permissions }) }, [201]);
+        const payload = record(await tokenResponse.json());
+        const grantedPermissions = record(payload.permissions);
+        const repositories = Array.isArray(payload.repositories) ? payload.repositories.map(record) : [];
+        const scopedRepository = repositories.some((candidate) => typeof candidate.full_name === "string" && candidate.full_name.toLowerCase() === repository);
+        const expiresAt = typeof payload.expires_at === "string" ? Date.parse(payload.expires_at) : Number.NaN;
+        const unexpectedPermission = Object.entries(grantedPermissions).some(([permissionName, level]) => !isAllowedPermission(permissionName, level));
+        const requestedGranted = Object.entries(permissions).every(([permissionName, level]) => grantedPermissions[permissionName] === level);
+        if (!isSafeGitHubInstallationToken(payload.token) ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= this.now().getTime() + 60_000 ||
+            !requestedGranted ||
+            unexpectedPermission ||
+            !scopedRepository) {
+            throw new Error("github_installation_token_scope_invalid");
+        }
+        return payload.token;
+    }
+    async revokeToken(token) {
+        await this.requestJson("/installation/token", token, { method: "DELETE" }, [204]);
+    }
+    async findPullRequest(token, input) {
+        const [owner, name] = input.repository.split("/");
+        const query = new URLSearchParams({
+            state: "open",
+            head: `${owner}:${input.headRef}`,
+            base: input.baseRef,
+            per_page: "100",
+        });
+        const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls?${query.toString()}`, token);
+        const payload = await response.json();
+        if (!Array.isArray(payload))
+            throw new Error("github_api_invalid_response");
+        const marker = `${RUN_MARKER_PREFIX}${input.runId} -->`;
+        for (const item of payload) {
+            const candidate = record(item);
+            if (typeof candidate.body === "string" && candidate.body.includes(marker)) {
+                if (candidate.draft !== true)
+                    throw new Error("github_pull_request_not_draft");
+                return this.parsePullRequest(candidate, input.repository);
+            }
+        }
+        return null;
+    }
+    parsePullRequest(value, repository) {
+        const payload = record(value);
+        const number = positiveInteger(payload.number);
+        if (payload.draft !== true)
+            throw new Error("github_pull_request_not_draft");
+        const expectedUrl = `https://github.com/${repository}/pull/${number}`;
+        if (typeof payload.html_url !== "string")
+            throw new Error("github_pull_request_response_invalid");
+        let receivedUrl;
+        try {
+            receivedUrl = new URL(payload.html_url);
+        }
+        catch {
+            throw new Error("github_pull_request_response_invalid");
+        }
+        if (receivedUrl.protocol !== "https:" ||
+            receivedUrl.hostname.toLowerCase() !== "github.com" ||
+            receivedUrl.port ||
+            receivedUrl.username ||
+            receivedUrl.password ||
+            receivedUrl.search ||
+            receivedUrl.hash ||
+            receivedUrl.pathname.toLowerCase() !== new URL(expectedUrl).pathname.toLowerCase()) {
+            throw new Error("github_pull_request_response_invalid");
+        }
+        return { number, url: expectedUrl };
+    }
+    async findStatusComment(token, repository, pullRequestNumber, runId) {
+        const [owner, name] = repository.split("/");
+        const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/issues/${pullRequestNumber}/comments?per_page=100`, token);
+        const payload = await response.json();
+        if (!Array.isArray(payload))
+            throw new Error("github_api_invalid_response");
+        const marker = `${STATUS_COMMENT_MARKER_PREFIX}${runId} -->`;
+        for (const item of payload) {
+            const candidate = record(item);
+            if (typeof candidate.body === "string" && candidate.body.includes(marker)) {
+                return { id: positiveInteger(candidate.id) };
+            }
+        }
+        return null;
+    }
+    async findCheckRun(token, repository, headSha, runId) {
+        const [owner, name] = repository.split("/");
+        const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${headSha}/check-runs?per_page=100`, token);
+        const payload = record(await response.json());
+        const checkRuns = Array.isArray(payload.check_runs) ? payload.check_runs.map(record) : [];
+        for (const candidate of checkRuns) {
+            if (candidate.external_id === runId)
+                return { id: positiveInteger(candidate.id) };
+        }
+        return null;
+    }
+    async requestJson(path, bearer, init = {}, expectedStatuses = [200]) {
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+                ...init,
+                headers: {
+                    accept: "application/vnd.github+json",
+                    authorization: `Bearer ${bearer}`,
+                    "content-type": "application/json",
+                    "user-agent": "wardby",
+                    "x-github-api-version": this.apiVersion,
+                    ...init.headers,
+                },
+            });
+        }
+        catch (error) {
+            // Keep the cause: the operator log needs the transport reason (DNS,
+            // TLS, connect timeout); the message itself stays fixed and safe.
+            throw new Error("github_api_unavailable", { cause: error });
+        }
+        if (!expectedStatuses.includes(response.status))
+            throw safeApiError(response);
+        return response;
+    }
+}

package/dist/providers/vcs/index.d.ts

@@ -0,0 +1,6 @@
+import type { GitHubVcsConfig, ProviderConfig } from "../../config/providers.js";
+import type { VcsProvider } from "./types.js";
+export * from "./types.js";
+export { GitHubAppClient } from "./github.js";
+export { GitVcsProvider, NodeGitCommandRunner } from "./git.js";
+export declare function buildVcsProvider(providerConfig: Pick<ProviderConfig, "vcs">, config: GitHubVcsConfig): VcsProvider;

package/dist/providers/vcs/index.js

@@ -0,0 +1,26 @@
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { GitHubAppClient } from "./github.js";
+import { GitVcsProvider } from "./git.js";
+export * from "./types.js";
+export { GitHubAppClient } from "./github.js";
+export { GitVcsProvider, NodeGitCommandRunner } from "./git.js";
+export function buildVcsProvider(providerConfig, config) {
+    if (providerConfig.vcs !== "github")
+        throw new Error(`VCS_PROVIDER=${String(providerConfig.vcs)} is not supported.`);
+    if (!config.appId || !config.privateKey) {
+        throw new Error("GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are required by the GitHub VCS adapter.");
+    }
+    const rootDir = resolve(config.workRoot ?? resolve(tmpdir(), "wardby-vcs"));
+    const github = new GitHubAppClient({
+        appId: config.appId,
+        privateKey: config.privateKey,
+        apiVersion: config.apiVersion,
+    });
+    return new GitVcsProvider({
+        rootDir,
+        github,
+        maxChangedFiles: config.maxChangedFiles,
+        maxDiffBytes: config.maxDiffBytes,
+    });
+}

package/dist/providers/vcs/types.d.ts

@@ -0,0 +1,118 @@
+export interface VcsPrepareInput {
+    runId: string;
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    protectedPaths: string[];
+    /**
+     * Revision-in-place: set when headRef is an EXISTING branch to continue
+     * rather than a fresh one
+     * to create off baseRef. `rootRunId` is the id of the run that originally
+     * opened the PR headRef belongs to (used for PR lookup identity, since
+     * GitHub's find-by-marker keys on that run's id, not this one's) -- the
+     * caller (dispatch.ts) must already have verified, against the database,
+     * that this run is legitimately allowed to continue that branch before
+     * ever setting this; this layer trusts it exactly as much as it already
+     * trusts baseRef, no more, and cannot independently re-verify a database
+     * fact.
+     */
+    continuation?: {
+        rootRunId: string;
+    };
+}
+/** Trusted paths are returned by the provider, never accepted from worker output. */
+export interface PreparedWorkspace {
+    id: string;
+    runId: string;
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    /** For a fresh workspace, the commit baseRef pointed at when cloned. For
+     * a continuation, the tip of the branch being continued at clone time --
+     * each round is independently validated against its own agent's rules at
+     * commit time (see design doc §8.3), so there's no need to re-derive or
+     * re-validate the PR's true original root here; "where this round
+     * started" is the only anchor the single-new-commit and protected-path
+     * checks need. */
+    baseCommit: string;
+    workspacePath: string;
+    gitMetadataPath: string;
+    protectedPaths: string[];
+    continuation?: {
+        rootRunId: string;
+    };
+}
+/** Already-validated/redacted agent-authored fields (coding/protocol.ts) surfaced in the opened PR, if any. */
+export interface FinalizeChangesDetails {
+    summary?: string;
+    tests?: readonly {
+        command: string;
+        outcome: "passed" | "failed" | "skipped";
+    }[];
+    tag?: string;
+}
+export type FinalizeChangesResult = {
+    outcome: "no_changes";
+    repository: string;
+    baseRef: string;
+    baseCommit: string;
+} | {
+    outcome: "pull_request_opened";
+    repository: string;
+    baseRef: string;
+    baseCommit: string;
+    headRef: string;
+    commitSha: string;
+    pullRequestNumber: number;
+    pullRequestUrl: string;
+} | {
+    /** Revision-in-place: pushed a new commit onto an existing open PR's
+     * branch instead of opening a new one. */
+    outcome: "pull_request_updated";
+    repository: string;
+    baseRef: string;
+    baseCommit: string;
+    headRef: string;
+    commitSha: string;
+    pullRequestNumber: number;
+    pullRequestUrl: string;
+};
+export interface VcsProvider {
+    prepareWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace>;
+    recoverWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace | null>;
+    finalizeChanges(workspace: PreparedWorkspace, details?: FinalizeChangesDetails): Promise<FinalizeChangesResult>;
+    cleanup(workspace: PreparedWorkspace): Promise<void>;
+    /**
+     * Best-effort "wardby is working on this" signal for a continuation
+     * a no-op when `workspace.continuation` is unset, since a fresh run has
+     * no PR to attach anything to until its one commit lands. Optional
+     * because this is a GitHub-specific concept, not a universal VCS one --
+     * a future non-GitHub provider (or a test double) can simply omit it,
+     * mirroring `Executor.resolveCodingWorkerImage?` (dispatch.ts calls it
+     * with `?.()`). Implementations MUST NOT throw: this is strictly
+     * observability, never allowed to affect the real coding run.
+     * `details.agentName`, when present, is the human-readable agent name
+     * (e.g. "knock-knock-implement") surfaced alongside the opaque run id --
+     * particularly useful for the cross-agent case, where the agent
+     * continuing the PR isn't the one that originally opened it.
+     */
+    notifyContinuationStarted?(workspace: PreparedWorkspace, details?: {
+        agentName?: string;
+    }): Promise<void>;
+    /**
+     * Companion to `notifyContinuationStarted` -- must find and update
+     * whatever that call created, never create fresh state itself (a
+     * "finished" status with no preceding "in progress" one would be
+     * confusing, and could happen if the process crashed between the two
+     * calls). Safe to call more than once for the same run. Same
+     * never-throw contract as `notifyContinuationStarted`. `details.summary`,
+     * when present, is the agent's own already-validated/redacted summary
+     * (the same text that goes in the PR body -- see
+     * `FinalizeChangesDetails.summary`) so the "done" status reflects what
+     * actually happened instead of a caller having to go find out.
+     */
+    notifyContinuationFinished?(workspace: PreparedWorkspace, outcome: "succeeded" | "failed", details?: {
+        summary?: string;
+        agentName?: string;
+    }): Promise<void>;
+}

package/dist/providers/vcs/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/bounded-json.d.ts

@@ -0,0 +1,2 @@
+export declare function boundedJson(value: unknown, maxBytes: number): string;
+export declare function boundedString(value: unknown, maxBytes: number): asserts value is string;