tinybeeai 0.0.0-stage → 0.16.1

package/dist/integrations/github.js

@@ -0,0 +1,1284 @@
+import { runTracked } from '../proc.js';
+import { httpError } from '../http-error.js';
+import { targetUrlOf } from '../target-url.js';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { cp, mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { config, liveEnv, onSettingsChange } from '../config.js';
+import { githubArtifactSource } from '../review/coverage.js';
+import { carryTicks } from '../review/render.js';
+import { withBotMarker } from './bot-marker.js';
+import { forgetOwnId, rememberOwnId } from './own-identity.js';
+import { isFullSha, isSafeRef } from '../runner/verify.js';
+import { getWorkspaceRepo, parseRepoId, primaryRepo, repoId, targetRepo } from '../repos.js';
+export const STICKY_MARKER = '<!-- localdost:pr-summary -->';
+/** Matches the marker as written now and as QA Dots wrote it, so old sticky comments are still found and updated. */
+export const STICKY_MARKER_RE = /<!-- (?:localdost|qadots):pr-summary -->/;
+export function hasStickyMarker(body) {
+    return typeof body === 'string' && STICKY_MARKER_RE.test(body);
+}
+/** The label every defect the dot files carries. */
+export const DEFECT_LABEL = 'localdost';
+/** The label QA Dots put on defects. Still recognised, never applied. */
+export const LEGACY_DEFECT_LABEL = 'qa-dots';
+export const DEFECT_LABELS = [DEFECT_LABEL, LEGACY_DEFECT_LABEL];
+export function isDefectLabel(name) {
+    return typeof name === 'string' && DEFECT_LABELS.includes(name.toLowerCase());
+}
+/** Largest job log jobLog returns, in bytes. A longer log is cut to this size. */
+export const JOB_LOG_CAP = 5 * 1024 * 1024;
+/** What the statuses of a deployment said at the look where it first succeeded, by repository and deployment id; later statuses are not read. Bounded: the oldest entry goes first. */
+const succeededDeployments = new Map();
+const SUCCEEDED_DEPLOYMENTS_MAX = 2000;
+/** Forgets the deployments that were read as succeeded. Tests call it between cases. */
+export function forgetSucceededDeployments() {
+    succeededDeployments.clear();
+}
+/**
+ * The service a deployment is for, as its own fields say: `payload.service` (or name, app, component, project), else a `task` other
+ * than GitHub's default "deploy", else the description. Lower case; undefined when none of them says. Two deployments of one commit
+ * with the same service are two attempts at one deployment, and with different services they are two deployments.
+ */
+export function deploymentService(d) {
+    return serviceInfo(d)?.name;
+}
+/** True when the service of the deployment comes from its description only, which is a guess (see DeploymentInfo.serviceGuessed). */
+export function deploymentServiceGuessed(d) {
+    return !!serviceInfo(d)?.guessed;
+}
+function serviceInfo(d) {
+    if (!d)
+        return undefined;
+    let payload = d.payload;
+    if (typeof payload === 'string') {
+        try {
+            payload = JSON.parse(payload);
+        }
+        catch {
+            payload = undefined;
+        }
+    }
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        for (const key of ['service', 'name', 'app', 'component', 'project']) {
+            const v = payload[key];
+            if (typeof v === 'string' && v.trim())
+                return { name: v.trim().toLowerCase().slice(0, 100), guessed: false };
+        }
+    }
+    if (typeof d.task === 'string' && d.task.trim() && d.task.trim().toLowerCase() !== 'deploy')
+        return { name: d.task.trim().toLowerCase().slice(0, 100), guessed: false };
+    if (typeof d.description === 'string') {
+        const name = serviceOfDescription(d.description);
+        return name ? { name, guessed: true } : undefined;
+    }
+    return undefined;
+}
+/**
+ * The service a description names (KAT-403). A pipeline often writes its run into the description ("Deploy web (run 8841)", "web, attempt 2"),
+ * and a retry then has another description, so each retry would look like a new service. What names a try and not a service is cut:
+ * run, attempt, build and job numbers, #numbers, long numbers, commit shas, uuids, and timestamps. A description with nothing else left names none.
+ */
+export function serviceOfDescription(text) {
+    const t = text
+        .toLowerCase()
+        .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/g, ' ')
+        .replace(/\b\d{4}-\d{2}-\d{2}[t ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?z?\b/g, ' ')
+        .replace(/\b(?:run|attempt|try|retry|build|job|workflow|pipeline|deployment|deploy|release|execution|id)[\s_-]*(?:id|number|no|#)?[\s#:=_-]*\d+\b/g, ' ')
+        .replace(/#\d+\b/g, ' ')
+        .replace(/\b[0-9a-f]{7,40}\b/g, (m) => (/\d/.test(m) && /[a-f]/.test(m) ? ' ' : m))
+        .replace(/\b\d{5,}\b/g, ' ')
+        .replace(/\(\s*\)|\[\s*\]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .replace(/^[\s,;:|/-]+|[\s,;:|/-]+$/g, '')
+        .trim();
+    return t ? t.slice(0, 100) : undefined;
+}
+export function pullSummary(p) {
+    const merged = Boolean(p.merged || p.merged_at);
+    return {
+        number: Number(p.number),
+        title: String(p.title ?? ''),
+        state: merged ? 'merged' : p.state === 'open' ? 'open' : 'closed',
+        headSha: String(p.head?.sha ?? ''),
+        ...(merged && p.merge_commit_sha ? { mergeSha: String(p.merge_commit_sha) } : {}),
+        ...(p.user?.login ? { author: String(p.user.login) } : {}),
+        ...(p.html_url ? { url: String(p.html_url) } : {}),
+        ...(p.updated_at ? { updatedAt: String(p.updated_at) } : {}),
+    };
+}
+// deployment_status previews, keyed by repo and sha
+const previews = new Map();
+const PREVIEW_CAP = 500;
+/** Closed-PR pages (100 each) the review picker reads at most while it looks for merged PRs. */
+const CLOSED_PULL_PAGES = 3;
+function repoKey(repo) {
+    return (typeof repo === 'string' ? repo : `${repo.owner}/${repo.name}`).toLowerCase();
+}
+/**
+ * Keeps the preview address of a commit. The address comes from a deployment_status, which anyone who can write one chooses, so it is
+ * cleaned like the address of a deploy (targetUrlOf): https, or http on this machine, no sign-in, query or fragment, at most 300
+ * characters. Any other address is not kept.
+ */
+export function rememberPreview(repo, sha, rawUrl) {
+    const url = targetUrlOf(rawUrl);
+    if (!url)
+        return;
+    const key = `${repoKey(repo)}@${sha}`;
+    previews.delete(key);
+    previews.set(key, url);
+    if (previews.size > PREVIEW_CAP) {
+        const oldest = previews.keys().next().value;
+        if (oldest !== undefined)
+            previews.delete(oldest);
+    }
+}
+export function previewFor(repo, sha) {
+    return previews.get(`${repoKey(repo)}@${sha}`);
+}
+const deploymentListeners = new Set();
+/**
+ * Calls `fn` for every deployment_status the server reads that ends a deployment (a webhook delivery, or a simulated one): success,
+ * failure or error. A listener that throws is logged and never stops the delivery. Returns a function that removes the listener.
+ */
+export function onDeploymentEnd(fn) {
+    deploymentListeners.add(fn);
+    return () => {
+        deploymentListeners.delete(fn);
+    };
+}
+export function normalizeGithub(eventName, payload, deliveryId, opts = {}) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const r = payload.repository;
+    const repo = r ? { owner: String(r.owner?.login ?? r.owner?.name ?? ''), name: String(r.name ?? '') } : undefined;
+    const full = r?.full_name ?? (repo ? `${repo.owner}/${repo.name}` : 'unknown');
+    const key = (semantic) => (deliveryId ? `github:${deliveryId}` : `github:${semantic}`);
+    const extra = {};
+    if (Array.isArray(payload.inlineDiff))
+        extra.inlineDiff = payload.inlineDiff;
+    if (payload.inlineTicket)
+        extra.inlineTicket = payload.inlineTicket;
+    switch (eventName) {
+        case 'pull_request': {
+            const pr = payload.pull_request;
+            if (!pr)
+                return null;
+            const action = String(payload.action ?? '');
+            const base = {
+                number: Number(pr.number ?? payload.number),
+                headSha: String(pr.head?.sha ?? ''),
+                baseRef: String(pr.base?.ref ?? ''),
+                headRef: String(pr.head?.ref ?? ''),
+                author: pr.user?.login,
+                // A head repository that is gone (null: a deleted fork) is a fork too. The same-repo path runs code on this machine.
+                fork: Boolean(pr.head?.repo === null || (pr.head?.repo && r?.full_name && String(pr.head.repo.full_name).toLowerCase() !== String(r.full_name).toLowerCase())),
+                ...(pr.base?.sha ? { baseSha: String(pr.base.sha) } : {}),
+                ...(typeof pr.body === 'string' && pr.body ? { body: pr.body.slice(0, 20000) } : {}),
+                // What a dot's PR scope reads (KAT-354). Set only when true, so other events keep their shape.
+                ...(pr.draft === true ? { draft: true } : {}),
+                ...(pr.user?.type === 'Bot' || /\[bot\]$/.test(String(pr.user?.login ?? '')) ? { authorIsBot: true } : {}),
+            };
+            // ready_for_review: a draft left draft state, so the PR is now one to review (KAT-354). Its head did not change,
+            // so the dedupe key names the action, and a dot that already reviewed this head skips it (src/webhooks.ts).
+            if (action === 'opened' || action === 'synchronize' || action === 'reopened' || action === 'ready_for_review') {
+                return {
+                    source: 'github',
+                    kind: 'pr_opened',
+                    dedupeKey: key(`${full}#${base.number}:${action}:${base.headSha}`),
+                    title: `PR #${base.number}: ${pr.title ?? ''}`.trim(),
+                    url: pr.html_url,
+                    repo,
+                    pr: action === 'ready_for_review' ? { ...base, readyForReview: true } : base,
+                    ...extra,
+                };
+            }
+            if (action === 'closed' && pr.merged) {
+                const mergeSha = String(pr.merge_commit_sha ?? '');
+                return {
+                    source: 'github',
+                    kind: 'pr_merged',
+                    dedupeKey: key(`${full}#${base.number}:merged:${mergeSha}`),
+                    title: `Merged PR #${base.number}: ${pr.title ?? ''}`.trim(),
+                    url: pr.html_url,
+                    repo,
+                    pr: { ...base, mergeSha },
+                    ...extra,
+                };
+            }
+            return null;
+        }
+        case 'push': {
+            const defaultBranch = r?.default_branch ?? r?.master_branch;
+            const pushed = String(payload.ref ?? '').replace(/^refs\/heads\//, '');
+            if (!defaultBranch || !String(payload.ref ?? '').startsWith('refs/heads/'))
+                return null;
+            if (payload.ref !== `refs/heads/${defaultBranch}` && !(repo && opts.isTestBranch?.(repo, pushed)))
+                return null;
+            if (payload.deleted || /^0+$/.test(String(payload.after ?? '')))
+                return null;
+            const msg = String(payload.head_commit?.message ?? '').split('\n')[0] ?? '';
+            // GitHub lists added, modified and removed paths per commit, and only the first 20 commits.
+            const commits = Array.isArray(payload.commits) ? payload.commits : [];
+            const pushedFiles = new Set();
+            for (const c of commits)
+                for (const k of ['added', 'modified', 'removed'])
+                    for (const f of Array.isArray(c?.[k]) ? c[k] : [])
+                        pushedFiles.add(String(f));
+            const filesKnown = pushedFiles.size > 0 && commits.length < 20;
+            return {
+                source: 'github',
+                kind: 'push',
+                dedupeKey: key(`${full}:push:${payload.after}`),
+                title: `Push to ${pushed}${msg ? `: ${msg}` : ''}`,
+                url: payload.compare,
+                repo,
+                push: { before: String(payload.before ?? ''), after: String(payload.after ?? ''), ref: String(payload.ref) },
+                ...(filesKnown
+                    ? { changedFiles: [...pushedFiles] }
+                    : { pathFilterNote: commits.length >= 20 ? 'The push payload lists only the first 20 commits.' : 'The push payload lists no changed files.' }),
+                ...extra,
+            };
+        }
+        case 'workflow_run': {
+            const wr = payload.workflow_run;
+            if (!wr || payload.action !== 'completed')
+                return null;
+            if (wr.conclusion !== 'failure' && wr.conclusion !== 'timed_out')
+                return null;
+            return {
+                source: 'github',
+                kind: 'ci_failure',
+                dedupeKey: key(`${full}:ci:${wr.id}:${wr.run_attempt ?? 1}`),
+                title: `CI ${wr.conclusion === 'timed_out' ? 'timed out' : 'failed'}: ${wr.name ?? 'workflow'} on ${wr.head_branch ?? wr.head_sha}`,
+                url: wr.html_url,
+                repo,
+                ci: { runId: Number(wr.id), workflow: String(wr.name ?? ''), conclusion: String(wr.conclusion), headSha: String(wr.head_sha ?? '') },
+                ...extra,
+            };
+        }
+        case 'deployment_status': {
+            const ds = payload.deployment_status;
+            const sha = payload.deployment?.sha;
+            const url = ds?.environment_url || ds?.target_url;
+            if (ds?.state === 'success' && sha && url && repo)
+                rememberPreview(repo, sha, String(url));
+            // A merge run that waits for the deploy of its commit looks again when this arrives (src/deploy-wait.ts): a success may end the
+            // wait, and a failure or error ends it too.
+            if ((ds?.state === 'success' || ds?.state === 'failure' || ds?.state === 'error') && sha && repo) {
+                const environment = String(ds.environment ?? payload.deployment?.environment ?? '');
+                for (const fn of [...deploymentListeners]) {
+                    try {
+                        const dep = payload.deployment ?? {};
+                        fn({
+                            repo,
+                            environment,
+                            sha: String(sha),
+                            state: ds.state,
+                            ...(Number.isFinite(Number(dep.id)) && dep.id !== undefined && dep.id !== null ? { id: Number(dep.id) } : {}),
+                            ...(dep.created_at ? { createdAt: String(dep.created_at) } : {}),
+                            ...(ds.created_at ? { at: String(ds.created_at) } : {}),
+                            ...(deploymentService(dep) ? { service: deploymentService(dep) } : {}),
+                            ...(deploymentService(dep) && deploymentServiceGuessed(dep) ? { serviceGuessed: true } : {}),
+                        });
+                    }
+                    catch (err) {
+                        console.warn(`[github] a deployment listener failed: ${String(err)}`);
+                    }
+                }
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+/** Edits of the localdost sticky comment on a pull request; null for anything else. */
+export function normalizeCommentEdit(eventName, payload) {
+    if (eventName !== 'issue_comment' || !payload || typeof payload !== 'object')
+        return null;
+    if (payload.action !== 'edited')
+        return null;
+    const issue = payload.issue;
+    const comment = payload.comment;
+    const r = payload.repository;
+    if (!issue?.pull_request || !comment || !r)
+        return null;
+    const body = typeof comment.body === 'string' ? comment.body : '';
+    if (!hasStickyMarker(body))
+        return null;
+    const sender = payload.sender ?? {};
+    const login = String(sender.login ?? '');
+    return {
+        repo: { owner: String(r.owner?.login ?? r.owner?.name ?? ''), name: String(r.name ?? '') },
+        pr: Number(issue.number),
+        commentId: Number(comment.id ?? 0),
+        body,
+        sender: login,
+        senderIsBot: sender.type === 'Bot' || /\[bot\]$/.test(login),
+        association: String(comment.author_association ?? 'NONE').toUpperCase(),
+    };
+}
+// Client
+export function githubMode() {
+    if (liveEnv.GITHUB_APP_ID && liveEnv.GITHUB_PRIVATE_KEY)
+        return 'app';
+    if (liveEnv.GITHUB_TOKEN)
+        return 'pat';
+    return 'demo';
+}
+let clientOverride;
+/** Test seam: githubFor returns what `fn` returns, or its normal client when `fn` returns undefined. Pass undefined to reset. */
+export function overrideGithubClient(fn) {
+    clientOverride = fn;
+}
+/**
+ * Client for the repo an event belongs to (docs/MULTI-REPO.md section 1.2): the event's repo when
+ * the dot holds it, else the dot's first app repo. `event` is optional; with none the client is for
+ * the first app repo. In demo mode the event's inlineDiff is what prFiles and compare return.
+ */
+export function githubFor(watch, event) {
+    const fake = clientOverride?.(watch, event);
+    if (fake)
+        return fake;
+    const target = targetRepo(watch, event);
+    const mode = target ? githubMode() : 'demo';
+    if (mode === 'demo' || !target)
+        return demoClient(watch, event);
+    return liveClient(target, mode);
+}
+/**
+ * Client for the repo a defect is filed in. That is the tracker repo of a team dot, which can be none of the dot's own
+ * repos (`katalon-studio/product` holds no app code), so githubFor would answer with the first app repo instead (KAT-355).
+ * The test seam decides first; with no connection it answers like githubFor does, as the demo client.
+ */
+export function githubForIssues(watch, project) {
+    const ref = parseRepoId(project);
+    const fake = clientOverride?.(watch, ref ? { repo: ref } : undefined);
+    if (fake)
+        return fake;
+    const mode = githubMode();
+    if (!ref || mode === 'demo')
+        return demoClient(watch, undefined);
+    const ws = getWorkspaceRepo(repoId(ref.owner, ref.name));
+    return liveClient({ owner: ws?.owner ?? ref.owner, name: ws?.name ?? ref.name, defaultBranch: ws?.defaultBranch ?? 'main' }, mode);
+}
+/** Client for a workspace repo with no dot (scans, profile reads, repo info). null when GitHub is not connected. */
+export function githubForRepo(id, defaultBranch) {
+    const ref = parseRepoId(id);
+    const mode = githubMode();
+    if (!ref || mode === 'demo')
+        return null;
+    const ws = getWorkspaceRepo(repoId(ref.owner, ref.name));
+    return liveClient({ owner: ws?.owner ?? ref.owner, name: ws?.name ?? ref.name, defaultBranch: defaultBranch ?? ws?.defaultBranch ?? 'main' }, mode);
+}
+/** A git command ran past its time limit and was stopped. */
+export class GitTimeoutError extends Error {
+}
+/** The connection cannot read the repo: it does not exist, the token has no access, or the App is not installed on it. */
+export class RepoAccessError extends Error {
+}
+/**
+ * GET /repos/{owner}/{name} with the live credentials: GitHub's casing, default branch, and private flag.
+ * Throws RepoAccessError when the connection cannot read the repo, and a plain Error for anything
+ * else (not connected, network, rate limit).
+ */
+export async function fetchRepoInfo(ref) {
+    const mode = githubMode();
+    if (mode === 'demo')
+        throw new Error('GitHub is not connected. Connect it on the Setup page first.');
+    const full = `${ref.owner}/${ref.name}`;
+    let tok;
+    try {
+        tok = mode === 'app' ? await installationToken(full) : liveEnv.GITHUB_TOKEN;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw /not installed/.test(msg) ? new RepoAccessError(`The GitHub App is not installed on ${full}.`) : err;
+    }
+    const res = await fetch(`${apiBase()}/repos/${full}`, { headers: headers(tok) });
+    if (res.status === 404 || res.status === 403)
+        throw new RepoAccessError(`${full} was not found, or the GitHub connection cannot read it.`);
+    if (!res.ok)
+        throw new Error(`GitHub GET /repos/${full} failed: HTTP ${res.status}`);
+    const r = (await res.json());
+    return { owner: r.owner?.login || ref.owner, name: r.name || ref.name, defaultBranch: r.default_branch || 'main', private: !!r.private };
+}
+export const apiBase = () => (liveEnv.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/$/, '');
+/** Token for git over HTTPS and API reads on one repo: the App installation token, or the PAT. Null without GitHub credentials. */
+export async function repoGitToken(repo) {
+    const mode = githubMode();
+    if (mode === 'app')
+        return installationToken(`${repo.owner}/${repo.name}`);
+    if (mode === 'pat')
+        return liveEnv.GITHUB_TOKEN ?? null;
+    return null;
+}
+/** Bytes per language from GET /repos/{owner}/{repo}/languages, or null when unavailable. */
+export async function repoLanguages(repo) {
+    try {
+        const tok = await repoGitToken(repo);
+        if (!tok)
+            return null;
+        const res = await fetch(`${apiBase()}/repos/${repo.owner}/${repo.name}/languages`, { headers: headers(tok) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+const serverBase = () => (liveEnv.GITHUB_SERVER_URL ?? 'https://github.com').replace(/\/$/, '');
+/** GitHub web base for file and commit links in comments (GitHub Enterprise sets GITHUB_SERVER_URL). */
+export const githubWebUrl = serverBase;
+function loadPrivateKey() {
+    const raw = liveEnv.GITHUB_PRIVATE_KEY ?? '';
+    if (!raw.includes('-----BEGIN') && existsSync(raw))
+        return readFileSync(raw, 'utf8');
+    return raw.replace(/\\n/g, '\n');
+}
+let appAuth = null;
+const installationIds = new Map();
+// Credentials saved in the app take effect without a restart: drop cached App auth and lookups.
+onSettingsChange((keys) => {
+    if (!keys.some((k) => k.startsWith('GITHUB_')))
+        return;
+    appAuth = null;
+    installationIds.clear();
+    selfLogins.clear();
+    forgetOwnId('github');
+});
+async function getAppAuth() {
+    appAuth ??= (async () => {
+        const { createAppAuth } = await import('@octokit/auth-app');
+        return createAppAuth({ appId: liveEnv.GITHUB_APP_ID, privateKey: loadPrivateKey() });
+    })();
+    return appAuth;
+}
+/** Boot: loads the GitHub App auth module and checks the private key, so the first job does not pay for it. Returns the mode. */
+export async function warmGithub() {
+    const mode = githubMode();
+    if (mode === 'app')
+        await getAppAuth();
+    return mode;
+}
+/** Installation token for the repo. @octokit/auth-app caches it until shortly before expiry. */
+async function installationToken(full) {
+    const auth = await getAppAuth();
+    let id = installationIds.get(full);
+    if (!id) {
+        const { token: jwt } = await auth({ type: 'app' });
+        const res = await ghFetch(`${apiBase()}/repos/${full}/installation`, { headers: headers(jwt) });
+        if (!res.ok)
+            throw new Error(`GitHub App is not installed on ${full} (HTTP ${res.status})`);
+        id = (await res.json()).id;
+        installationIds.set(full, id);
+    }
+    return (await auth({ type: 'installation', installationId: id })).token;
+}
+/**
+ * GitHub could not be reached or answered with an outage-class status (5xx, 429, rate limit), so
+ * nothing is known about the thing being read. It is never an empty result: the flows stop the run
+ * as an environment failure and the job retries with its backoff.
+ */
+export class GithubUnreachableError extends Error {
+    what;
+    constructor(message, what = 'api', options) {
+        super(message, options);
+        this.what = what;
+        this.name = 'GithubUnreachableError';
+    }
+}
+/**
+ * The real reason behind a failed fetch. Node's fetch throws `TypeError: fetch failed` and keeps the
+ * reason in `cause`: a system error with a code (ENOTFOUND, ETIMEDOUT, ECONNRESET), a TLS error, or an
+ * AggregateError of several addresses. Returns e.g. `fetch failed (ECONNRESET: read ECONNRESET)`.
+ */
+export function describeFetchError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const parts = [];
+    const seen = new Set();
+    const walk = (e, depth) => {
+        if (!(e instanceof Error) || seen.has(e) || depth > 4)
+            return;
+        seen.add(e);
+        const x = e;
+        const code = typeof x.code === 'string' ? x.code : '';
+        const msg = x.message && x.message !== err.message ? x.message : '';
+        if (depth > 0 || code)
+            parts.push(code && msg && !msg.includes(code) ? `${code}: ${msg}` : code || msg);
+        if (x.cause)
+            walk(x.cause, depth + 1);
+        for (const inner of x.errors ?? [])
+            walk(inner, depth + 1);
+    };
+    walk(err, 0);
+    const why = [...new Set(parts.filter(Boolean))].join('; ');
+    return why ? `${err.message} (${why})` : err.message;
+}
+/** fetch for GitHub calls: a network failure becomes a GithubUnreachableError that carries the real cause and is logged with it. */
+async function ghFetch(url, init) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (err) {
+        if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+            throw err;
+        throw unreachable(`${init?.method ?? 'GET'} ${url.replace(apiBase(), '').split('?')[0]}`, err);
+    }
+}
+function unreachable(what, err, kind = 'api') {
+    const why = describeFetchError(err);
+    console.warn(`[github] could not reach GitHub for ${what}: ${why}`);
+    return new GithubUnreachableError(`Could not reach GitHub (${what}): ${why}`, kind, { cause: err });
+}
+/** A status that says GitHub could not serve the read right now: server errors, 429, and a spent rate limit. */
+function isOutageStatus(res) {
+    if (res.status >= 500 || res.status === 429)
+        return true;
+    return res.status === 403 && (res.headers.get('x-ratelimit-remaining') === '0' || res.headers.has('retry-after'));
+}
+export function headers(token, accept = 'application/vnd.github+json') {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: accept,
+        'X-GitHub-Api-Version': '2022-11-28',
+        'User-Agent': 'localdost',
+    };
+}
+const truncate = (s, n) => (s.length > n ? s.slice(0, n - 20) + '\n\n(truncated)' : s);
+function mapFile(f) {
+    const status = f.status === 'added' || f.status === 'removed' || f.status === 'renamed' ? f.status : 'modified';
+    const out = { path: String(f.filename), status, additions: Number(f.additions ?? 0), deletions: Number(f.deletions ?? 0) };
+    if (typeof f.patch === 'string')
+        out.patch = f.patch;
+    return out;
+}
+const selfLogins = new Map();
+/** A token for `owner/name`: the PAT, or an App installation token. Throws when GitHub is not connected. */
+export async function githubTokenFor(full) {
+    const mode = githubMode();
+    if (mode === 'app')
+        return installationToken(full);
+    if (mode === 'pat')
+        return liveEnv.GITHUB_TOKEN;
+    throw new Error('GitHub is not connected: set GITHUB_TOKEN or a GitHub App in Setup');
+}
+/** Login of the user a PAT belongs to, read once per token. Lowercase; null when GET /user fails. */
+export async function selfLogin(tok) {
+    if (selfLogins.has(tok))
+        return selfLogins.get(tok) ?? null;
+    let login = null;
+    try {
+        const res = await fetch(`${apiBase()}/user`, { headers: headers(tok) });
+        if (res.ok)
+            login = String((await res.json()).login ?? '').toLowerCase() || null;
+    }
+    catch {
+        /* unknown: the caller falls back to the first marked comment */
+    }
+    if (login) {
+        selfLogins.set(tok, login);
+        // The PAT of the dot is the dot's own identity; other tokens passed in are not.
+        if (tok === liveEnv.GITHUB_TOKEN)
+            rememberOwnId('github', login);
+    }
+    return login;
+}
+function liveClient(repo, mode) {
+    const full = `${repo.owner}/${repo.name}`;
+    const token = async () => {
+        if (mode !== 'app')
+            return liveEnv.GITHUB_TOKEN;
+        try {
+            return await installationToken(full);
+        }
+        catch (err) {
+            // The App auth library calls fetch itself: its network failure surfaces as a bare "fetch failed".
+            throw err instanceof TypeError ? unreachable('installation token', err) : err;
+        }
+    };
+    /** Runs a read whose failure to reach GitHub must stop the run, and tags the error with what was being read. */
+    async function reading(kind, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (err instanceof GithubUnreachableError)
+                err.what = kind;
+            throw err;
+        }
+    }
+    async function call(method, p, body, accept) {
+        const res = await ghFetch(`${apiBase()}${p}`, {
+            method,
+            headers: { ...headers(await token(), accept), ...(body ? { 'Content-Type': 'application/json' } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (isOutageStatus(res))
+                throw new GithubUnreachableError(`Could not reach GitHub (${method} ${p.split('?')[0]}): HTTP ${res.status} ${text.slice(0, 200)}`.trim());
+            throw httpError(`GitHub ${method} ${p.split('?')[0]} failed: HTTP ${res.status} ${text.slice(0, 300)}`, res);
+        }
+        if (res.status === 204)
+            return undefined;
+        const type = res.headers.get('content-type') ?? '';
+        return (type.includes('json') ? await res.json() : await res.text());
+    }
+    async function paginate(p, maxPages) {
+        const out = [];
+        const sep = p.includes('?') ? '&' : '?';
+        for (let page = 1; page <= maxPages; page++) {
+            const batch = await call('GET', `${p}${sep}per_page=100&page=${page}`);
+            out.push(...batch);
+            if (batch.length < 100)
+                break;
+        }
+        return out;
+    }
+    /** Creates a check run (no id) or patches one (id). Returns the check run id in App mode. */
+    async function writeCheck(id, sha, r) {
+        const name = r.name ?? 'localdost';
+        if (mode === 'pat') {
+            // Check runs are App-only; a PAT gets a commit status instead. A later status with the same context replaces the earlier one.
+            // Pending: still running, a report that waits for a person, or a commit nobody reviewed. Failure: only a real failure.
+            // A check closed without a verdict (cancelled, neutral, skipped) is a success style status, so it never blocks a merge rule.
+            // A run that ended without a result is an error: a commit status has no neutral, and green would hide it (KAT-290).
+            const state = r.runFailed
+                ? 'error'
+                : !r.conclusion || r.superseded || r.conclusion === 'action_required'
+                    ? 'pending'
+                    : r.conclusion === 'failure' || r.conclusion === 'timed_out'
+                        ? 'failure'
+                        : 'success';
+            await call('POST', `/repos/${full}/statuses/${sha}`, {
+                state,
+                context: name,
+                description: (r.statusDescription ?? r.title).slice(0, 140),
+                ...(r.detailsUrl ? { target_url: r.detailsUrl } : {}),
+            });
+            return undefined;
+        }
+        const annotations = (r.annotations ?? []).map((a) => ({
+            path: a.path,
+            start_line: a.startLine,
+            end_line: a.endLine ?? a.startLine,
+            annotation_level: a.level,
+            message: a.message.slice(0, 64000),
+            ...(a.title ? { title: a.title.slice(0, 255) } : {}),
+        }));
+        const output = (batch) => ({
+            title: r.title.slice(0, 255),
+            summary: truncate(r.summary, 65000),
+            ...(r.text ? { text: truncate(r.text, 65000) } : {}),
+            annotations: batch,
+        });
+        const completed = Boolean(r.conclusion);
+        const fields = {
+            status: completed ? 'completed' : (r.status ?? 'in_progress'),
+            ...(completed ? { conclusion: r.conclusion, completed_at: new Date().toISOString() } : {}),
+            ...(r.detailsUrl ? { details_url: r.detailsUrl } : {}),
+            output: output(annotations.slice(0, 50)),
+        };
+        let checkId = id;
+        if (checkId === undefined)
+            checkId = (await call('POST', `/repos/${full}/check-runs`, { name, head_sha: sha, ...fields })).id;
+        else
+            await call('PATCH', `/repos/${full}/check-runs/${checkId}`, { name, ...fields });
+        // GitHub takes at most 50 annotations per request; the rest go in follow-up PATCHes.
+        for (let i = 50; i < annotations.length; i += 50) {
+            await call('PATCH', `/repos/${full}/check-runs/${checkId}`, { output: output(annotations.slice(i, i + 50)) });
+        }
+        return checkId;
+    }
+    /**
+     * Our sticky comment: it carries the marker and localdost wrote it. Anyone who can comment can paste
+     * the marker. Without the author check that comment would be read for ticks and patched, and the
+     * PATCH of someone else's comment fails, so the real comment would never be posted.
+     */
+    async function findSticky(pr) {
+        const comments = await paginate(`/repos/${full}/issues/${pr}/comments`, 10);
+        const marked = comments.filter((c) => hasStickyMarker(c.body));
+        if (!marked.length)
+            return undefined;
+        const mine = await ownCommentTest();
+        return mine ? marked.find(mine) : marked[0];
+    }
+    /** A test for comments this client wrote; null when the identity cannot be read (then the first marked comment counts). */
+    async function ownCommentTest() {
+        if (mode === 'app') {
+            const appId = Number(liveEnv.GITHUB_APP_ID);
+            return (c) => c.user?.type === 'Bot' && (!appId || Number(c.performed_via_github_app?.id ?? appId) === appId);
+        }
+        const login = await selfLogin(await token());
+        return login ? (c) => String(c.user?.login ?? '').toLowerCase() === login : null;
+    }
+    return {
+        mode,
+        // A failed page is an error, never a short list: the file list is whole or the read throws.
+        async prFiles(pr) {
+            return reading('diff', async () => (await paginate(`/repos/${full}/pulls/${pr}/files`, 30)).map(mapFile));
+        },
+        async compare(base, head) {
+            return reading('diff', async () => {
+                const data = await call('GET', `/repos/${full}/compare/${base}...${head}`);
+                return (data.files ?? []).map(mapFile);
+            });
+        },
+        async upsertStickyComment(pr, body) {
+            const existing = await findSticky(pr);
+            // Ticks a tester made since the flow read the comment are carried into the new body.
+            const merged = existing ? carryTicks(body, String(existing.body)) : body;
+            const text = truncate(hasStickyMarker(merged) ? merged.replace(STICKY_MARKER_RE, STICKY_MARKER) : `${STICKY_MARKER}\n${merged}`, 65000);
+            if (existing)
+                await call('PATCH', `/repos/${full}/issues/comments/${existing.id}`, { body: text });
+            else
+                await call('POST', `/repos/${full}/issues/${pr}/comments`, { body: text });
+        },
+        async getStickyComment(pr) {
+            const existing = await findSticky(pr);
+            return existing ? String(existing.body) : null;
+        },
+        async readFile(p, ref) {
+            const res = await ghFetch(`${apiBase()}/repos/${full}/contents/${p.split('/').map(encodeURIComponent).join('/')}?ref=${encodeURIComponent(ref)}`, {
+                headers: headers(await token(), 'application/vnd.github.raw+json'),
+            });
+            if (res.status === 404)
+                return null;
+            if (isOutageStatus(res))
+                throw new GithubUnreachableError(`Could not reach GitHub (contents ${p}): HTTP ${res.status}`);
+            if (!res.ok)
+                throw new Error(`GitHub contents ${p} failed: HTTP ${res.status}`);
+            return res.text();
+        },
+        async addComment(issue, body) {
+            await call('POST', `/repos/${full}/issues/${issue}/comments`, { body: withBotMarker(truncate(body, 64000)) });
+        },
+        async listOpenDefects() {
+            // GitHub ANDs a comma list of labels, so the current and the legacy label are two reads.
+            const pages = await Promise.all(DEFECT_LABELS.map((label) => call('GET', `/repos/${full}/issues?state=open&labels=${label}&sort=updated&direction=desc&per_page=100`)));
+            const seen = new Set();
+            const rows = pages.flat().filter((i) => (seen.has(Number(i.number)) ? false : (seen.add(Number(i.number)), true)));
+            return rows
+                .filter((i) => !i.pull_request)
+                .map((i) => ({
+                key: `${full}#${i.number}`,
+                title: String(i.title ?? ''),
+                body: String(i.body ?? ''),
+                ...(i.html_url ? { url: String(i.html_url) } : {}),
+                labels: (i.labels ?? []).map((l) => String(typeof l === 'string' ? l : l.name)),
+            }));
+        },
+        async checkRunsFor(sha) {
+            const out = [];
+            for (let page = 1; page <= 3; page++) {
+                const data = await call('GET', `/repos/${full}/commits/${encodeURIComponent(sha)}/check-runs?per_page=100&page=${page}`);
+                const runs = (data.check_runs ?? []);
+                for (const r of runs)
+                    out.push({
+                        id: Number(r.id),
+                        name: String(r.name ?? ''),
+                        status: String(r.status ?? ''),
+                        conclusion: r.conclusion ? String(r.conclusion) : null,
+                        ...(r.html_url ? { htmlUrl: String(r.html_url) } : {}),
+                        headSha: String(r.head_sha ?? ''),
+                        ...(r.app?.slug ? { app: String(r.app.slug) } : {}),
+                    });
+                if (runs.length < 100)
+                    break;
+            }
+            return out;
+        },
+        async deployments({ environment, sha, limit = 5 }) {
+            const q = new URLSearchParams({ environment, per_page: String(Math.min(Math.max(1, limit), 30)) });
+            if (sha)
+                q.set('sha', sha);
+            const rows = await call('GET', `/repos/${full}/deployments?${q}`);
+            const out = [];
+            for (const d of rows.slice(0, limit)) {
+                const id = Number(d.id);
+                // A deployment that succeeded keeps its success for good, so a later look reads it from memory (KAT-395): a push that deploys
+                // many services would otherwise cost one statuses call for each of them on every look of every waiting merge.
+                const key = `${full.toLowerCase()}#${id}`;
+                let seen = succeededDeployments.get(key);
+                if (!seen) {
+                    const statuses = await call('GET', `/repos/${full}/deployments/${id}/statuses?per_page=30`);
+                    const newest = statuses[0];
+                    seen = {
+                        state: String(newest?.state ?? 'pending'),
+                        succeeded: statuses.some((st) => st.state === 'success'),
+                        ...(newest?.created_at ? { at: String(newest.created_at) } : {}),
+                        ...(newest?.environment_url ? { url: String(newest.environment_url) } : {}),
+                    };
+                    if (seen.succeeded) {
+                        succeededDeployments.set(key, seen);
+                        if (succeededDeployments.size > SUCCEEDED_DEPLOYMENTS_MAX)
+                            succeededDeployments.delete(succeededDeployments.keys().next().value);
+                    }
+                }
+                const service = deploymentService(d);
+                out.push({
+                    id,
+                    sha: String(d.sha ?? ''),
+                    environment: String(d.environment ?? environment),
+                    ...seen,
+                    ...(d.created_at ? { createdAt: String(d.created_at) } : {}),
+                    ...(service ? { service } : {}),
+                    ...(service && deploymentServiceGuessed(d) ? { serviceGuessed: true } : {}),
+                });
+            }
+            return out;
+        },
+        async pullReviews(pr) {
+            const rows = await paginate(`/repos/${full}/pulls/${pr}/reviews`, 3);
+            const states = ['APPROVED', 'CHANGES_REQUESTED', 'COMMENTED', 'DISMISSED', 'PENDING'];
+            return rows.map((r) => ({
+                user: String(r.user?.login ?? ''),
+                state: (states.includes(String(r.state).toUpperCase()) ? String(r.state).toUpperCase() : 'COMMENTED'),
+                ...(r.submitted_at ? { submittedAt: String(r.submitted_at) } : {}),
+            }));
+        },
+        async commitStatuses(sha) {
+            const data = await call('GET', `/repos/${full}/commits/${encodeURIComponent(sha)}/status?per_page=100`);
+            return (data.statuses ?? []).map((st) => ({
+                context: String(st.context ?? ''),
+                state: (['success', 'failure', 'error', 'pending'].includes(String(st.state)) ? String(st.state) : 'pending'),
+                ...(st.target_url ? { url: String(st.target_url) } : {}),
+            }));
+        },
+        async jobLog(jobId) {
+            // Redirects to a signed URL; fetch drops the Authorization header on the cross-origin hop.
+            const res = await ghFetch(`${apiBase()}/repos/${full}/actions/jobs/${jobId}/logs`, { headers: headers(await token()) });
+            if (!res.ok)
+                throw new Error(`GitHub GET /repos/${full}/actions/jobs/${jobId}/logs failed: HTTP ${res.status}`);
+            return readCapped(res, JOB_LOG_CAP);
+        },
+        async renderMarkdown(text) {
+            const res = await ghFetch(`${apiBase()}/markdown`, {
+                method: 'POST',
+                headers: { ...headers(await token()), 'Content-Type': 'application/json' },
+                body: JSON.stringify({ text, mode: 'gfm', context: full }),
+            });
+            if (!res.ok)
+                throw new Error(`GitHub POST /markdown failed: HTTP ${res.status}`);
+            return res.text();
+        },
+        async rawDiff(target) {
+            const p = 'pr' in target ? `/repos/${full}/pulls/${target.pr}` : `/repos/${full}/compare/${target.base}...${target.head}`;
+            const res = await ghFetch(`${apiBase()}${p}`, { headers: headers(await token(), 'application/vnd.github.diff') });
+            if (!res.ok)
+                return null;
+            return res.text();
+        },
+        artifactSource() {
+            return {
+                async coverageArtifacts(sha) {
+                    return githubArtifactSource({ owner: repo.owner, repo: repo.name, token: await token(), apiBase: apiBase() }).coverageArtifacts(sha);
+                },
+            };
+        },
+        async teamMembers(slug) {
+            const [org, team] = slug.split('/');
+            if (!org || !team)
+                throw new Error(`"${slug}" is not a team slug like org/team`);
+            const rows = await paginate(`/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(team)}/members`, 10);
+            return rows.map((m) => String(m.login ?? '').toLowerCase()).filter(Boolean);
+        },
+        async pullsOfCommit(sha) {
+            if (!/^[0-9a-f]{7,64}$/i.test(sha))
+                return [];
+            return call('GET', `/repos/${full}/commits/${sha}/pulls?per_page=10`);
+        },
+        async writePermission(login) {
+            if (!login)
+                return false;
+            const res = await ghFetch(`${apiBase()}/repos/${full}/collaborators/${encodeURIComponent(login)}/permission`, { headers: headers(await token()) });
+            if (res.status === 404)
+                return false;
+            if (!res.ok)
+                return null;
+            const perm = String((await res.json()).permission ?? '');
+            return perm === 'admin' || perm === 'maintain' || perm === 'write';
+        },
+        async getPull(pr) {
+            const res = await ghFetch(`${apiBase()}/repos/${full}/pulls/${pr}`, { headers: headers(await token()) });
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`GitHub GET /repos/${full}/pulls/${pr} failed: HTTP ${res.status}`);
+            const payload = (await res.json());
+            return { summary: pullSummary(payload), payload };
+        },
+        async listPulls(limit = 20) {
+            const n = Math.max(1, Math.min(50, limit));
+            // Open PRs, then recently closed ones of which only the merged count. Closed PRs come a full
+            // page at a time, and the next page is read while the merged ones are short of the limit, so a
+            // run of PRs closed without a merge does not push the merged ones out. Pages stop at
+            // CLOSED_PULL_PAGES to bound GitHub calls per dialog open; an older PR is reviewed by number.
+            const closedPage = (page) => call('GET', `/repos/${full}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`);
+            const [open, firstClosed] = await Promise.all([
+                call('GET', `/repos/${full}/pulls?state=open&sort=updated&direction=desc&per_page=${n}`),
+                closedPage(1),
+            ]);
+            const merged = firstClosed.filter((p) => p.merged_at);
+            let last = firstClosed;
+            for (let page = 2; merged.length < n && last.length === 100 && page <= CLOSED_PULL_PAGES; page++) {
+                last = await closedPage(page);
+                merged.push(...last.filter((p) => p.merged_at));
+            }
+            merged.splice(n);
+            return [...open, ...merged]
+                .map(pullSummary)
+                .sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))
+                .slice(0, n);
+        },
+        async getCommit(ref) {
+            const res = await ghFetch(`${apiBase()}/repos/${full}/commits/${encodeURIComponent(ref)}`, { headers: headers(await token()) });
+            if (res.status === 404 || res.status === 422)
+                return null;
+            if (!res.ok)
+                throw new Error(`GitHub GET /repos/${full}/commits failed: HTTP ${res.status}`);
+            const c = (await res.json());
+            return {
+                sha: String(c.sha),
+                parents: (c.parents ?? []).map((p) => String(p.sha)),
+                message: String(c.commit?.message ?? ''),
+                ...(c.commit?.tree?.sha ? { treeSha: String(c.commit.tree.sha) } : {}),
+                ...(c.html_url ? { url: String(c.html_url) } : {}),
+            };
+        },
+        async defaultBranchName() {
+            const data = await call('GET', `/repos/${full}`);
+            const name = String(data.default_branch ?? '');
+            if (!name)
+                throw new Error(`GitHub did not report a default branch for ${full}`);
+            return name;
+        },
+        async refSha(kind, name) {
+            if (!isSafeRef(name))
+                return null;
+            const enc = (x) => x.split('/').map(encodeURIComponent).join('/');
+            const res = await ghFetch(`${apiBase()}/repos/${full}/git/ref/${kind === 'branch' ? 'heads' : 'tags'}/${enc(name)}`, { headers: headers(await token()) });
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                if (isOutageStatus(res))
+                    throw new GithubUnreachableError(`Could not reach GitHub (GET /repos/${full}/git/ref): HTTP ${res.status}`);
+                throw httpError(`GitHub GET /repos/${full}/git/ref failed: HTTP ${res.status}`, res);
+            }
+            const ref = (await res.json());
+            let sha = String(ref.object?.sha ?? '');
+            // An annotated tag points at a tag object, which points at the commit.
+            if (ref.object?.type === 'tag')
+                sha = String((await call('GET', `/repos/${full}/git/tags/${sha}`)).object?.sha ?? '');
+            return isFullSha(sha) ? sha.toLowerCase() : null;
+        },
+        async fetchCommit(dir, sha, ref, timeoutMs) {
+            if (!isFullSha(sha))
+                throw new Error(`Refusing to fetch "${sha.slice(0, 60)}": a commit must be 40 hex characters.`);
+            if (!/^refs\/localdost\/[A-Za-z0-9._/-]+$/.test(ref) || ref.includes('..'))
+                throw new Error('Refusing to fetch into a ref outside refs/localdost/.');
+            await reading('checkout', async () => {
+                const tok = await token();
+                const authed = `${serverBase().replace(/^https:\/\//, `https://x-access-token:${encodeURIComponent(tok)}@`)}/${full}.git`;
+                // By URL, so the token never lands in the config of the folder the worktrees are made from.
+                await git(['fetch', '-q', '--depth', '1', '--no-tags', authed, `+${sha}:${ref}`], dir, tok, timeoutMs);
+            });
+        },
+        async compareStatus(base, head) {
+            const enc = (x) => x.split('/').map(encodeURIComponent).join('/');
+            const data = await call('GET', `/repos/${full}/compare/${enc(base)}...${encodeURIComponent(head)}?per_page=1`);
+            const status = String(data.status ?? '');
+            if (status !== 'ahead' && status !== 'behind' && status !== 'identical' && status !== 'diverged')
+                throw new Error(`GitHub compare of ${base}...${head} returned status "${status}"`);
+            return status;
+        },
+        async openPullWithFiles({ base, branch, title, body, files }) {
+            const enc = (x) => x.split('/').map(encodeURIComponent).join('/');
+            const ref = await call('GET', `/repos/${full}/git/ref/heads/${enc(base)}`);
+            const parent = String(ref.object?.sha ?? '');
+            const commit = await call('GET', `/repos/${full}/git/commits/${parent}`);
+            const tree = await call('POST', `/repos/${full}/git/trees`, {
+                base_tree: String(commit.tree?.sha ?? ''),
+                tree: files.map((f) => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })),
+            });
+            const created = await call('POST', `/repos/${full}/git/commits`, { message: title, tree: String(tree.sha), parents: [parent] });
+            // A retry after a failed send finds the branch, and maybe the PR, from the first attempt: the
+            // branch moves to the new commit and an open PR for it is reused.
+            const existing = await ghFetch(`${apiBase()}/repos/${full}/git/ref/heads/${enc(branch)}`, { headers: headers(await token()) });
+            if (existing.ok)
+                await call('PATCH', `/repos/${full}/git/refs/heads/${enc(branch)}`, { sha: String(created.sha), force: true });
+            else
+                await call('POST', `/repos/${full}/git/refs`, { ref: `refs/heads/${branch}`, sha: String(created.sha) });
+            const open = await call('GET', `/repos/${full}/pulls?state=open&head=${encodeURIComponent(`${repo.owner}:${branch}`)}`);
+            if (open.length)
+                return String(open[0].html_url ?? '');
+            const pull = await call('POST', `/repos/${full}/pulls`, { title, head: branch, base, body: truncate(body, 65000), draft: true });
+            return String(pull.html_url ?? '');
+        },
+        async createCheckRun(sha, r) {
+            return writeCheck(undefined, sha, r);
+        },
+        async updateCheckRun(id, sha, r) {
+            await writeCheck(id, sha, r);
+        },
+        async searchCode(q) {
+            try {
+                const data = await call('GET', `/search/code?q=${encodeURIComponent(`${q} repo:${full}`)}&per_page=10`, undefined, 'application/vnd.github.text-match+json');
+                return (data.items ?? []).map((it) => ({
+                    path: String(it.path),
+                    snippet: String(it.text_matches?.[0]?.fragment ?? ''),
+                }));
+            }
+            catch (err) {
+                console.warn(`[github] code search failed for ${full}: ${err.message}`);
+                return [];
+            }
+        },
+        async jobLogTail(runId) {
+            const data = await call('GET', `/repos/${full}/actions/runs/${runId}/jobs?filter=latest&per_page=100`);
+            const jobs = (data.jobs ?? []);
+            const job = jobs.find((j) => j.conclusion === 'failure' || j.conclusion === 'timed_out') ?? jobs[0];
+            if (!job)
+                return '';
+            const step = (job.steps ?? []).find((s) => s.conclusion === 'failure');
+            // Redirects to a signed URL; fetch drops the Authorization header on the cross-origin hop.
+            const res = await ghFetch(`${apiBase()}/repos/${full}/actions/jobs/${job.id}/logs`, { headers: headers(await token()) });
+            const raw = res.ok ? await res.text() : '';
+            const lines = raw
+                .replace(/\u001b\[[0-9;]*m/g, '')
+                .replace(/^\d{4}-\d\d-\d\dT[\d:.]+Z /gm, '')
+                .split('\n');
+            const tail = lines.slice(-200).join('\n').slice(-15000);
+            return [`Job: ${job.name}`, step ? `Failed step: ${step.name}` : '', tail].filter(Boolean).join('\n');
+        },
+        async cloneTo(dir, sha) {
+            // Both go to git as arguments: a full hex sha, or a ref that starts with a letter or digit (never an option).
+            if (sha && !isFullSha(sha))
+                throw new Error(`Refusing to fetch "${sha.slice(0, 60)}": a commit must be 40 hex characters.`);
+            if (!sha && !isSafeRef(repo.defaultBranch))
+                throw new Error(`Refusing to fetch the branch "${repo.defaultBranch.slice(0, 60)}": not a safe branch name.`);
+            await reading('checkout', async () => {
+                const tok = await token();
+                const authed = `${serverBase().replace(/^https:\/\//, `https://x-access-token:${encodeURIComponent(tok)}@`)}/${full}.git`;
+                await mkdir(dir, { recursive: true });
+                // Fetch by URL so the token never lands in .git/config of the checkout we later mount.
+                await git(['init', '-q'], dir, tok);
+                await git(['fetch', '-q', '--depth', '1', '--no-tags', authed, sha || repo.defaultBranch], dir, tok);
+                await git(['checkout', '-q', '--detach', 'FETCH_HEAD'], dir, tok);
+                // A checkout with no files must not reach the setup step: it would run in a folder with no package.json or lockfile.
+                if (!(await readdir(dir)).some((name) => name !== '.git'))
+                    throw new GithubUnreachableError(`The checkout of ${full} at ${sha || repo.defaultBranch} has no files.`, 'checkout');
+            });
+        },
+    };
+}
+/** The body of a response as UTF-8 text, cut at `cap` bytes; the rest of the stream is not read. */
+async function readCapped(res, cap) {
+    if (!res.body)
+        return (await res.text()).slice(0, cap);
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    while (size < cap) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(Buffer.from(value));
+        size += value.byteLength;
+    }
+    await reader.cancel().catch(() => { });
+    return Buffer.concat(chunks).subarray(0, cap).toString('utf8');
+}
+/** One git command in a tracked process group, so shutdown and cancel can stop a clone mid-flight. */
+async function git(args, cwd, secret, timeoutMs) {
+    const r = await runTracked('git', args, { cwd, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, maxBuffer: 4000, ...(timeoutMs ? { timeoutMs } : {}) });
+    if (r.error)
+        throw new Error(`git ${args[0]} could not start: ${scrub(r.error, secret)}`);
+    if (r.timedOut)
+        throw new GitTimeoutError(`git ${args[0]} was stopped after ${Math.round((timeoutMs ?? 0) / 1000)} s`);
+    if (r.code === 0)
+        return;
+    const how = r.signal ? `stopped by ${r.signal}` : `failed (exit ${r.code})`;
+    const stderr = scrub(r.stderr, secret).trim();
+    const message = `git ${args[0]} ${how}: ${stderr}`.replace(/: $/, '');
+    // The network, not the repo: GitHub could not be reached, so the checkout is unknown rather than wrong.
+    if (GIT_NETWORK_FAILURE.test(stderr)) {
+        console.warn(`[github] could not reach GitHub for ${message}`);
+        throw new GithubUnreachableError(`Could not reach GitHub (${message})`, 'checkout');
+    }
+    throw new Error(message);
+}
+const GIT_NETWORK_FAILURE = /Could not resolve host|Failed to connect|Connection (?:timed out|reset|refused)|Operation timed out|Network is unreachable|early EOF|RPC failed|remote end hung up|TLS|SSL|gnutls|returned error: (?:429|5\d\d)/i;
+function scrub(text, secret) {
+    return secret ? text.split(secret).join('***').split(encodeURIComponent(secret)).join('***') : text;
+}
+/**
+ * PRs from demo/payloads for the demo repo, one per number (the file read last wins), so the
+ * PR picker and review on demand work with no GitHub. A watch on any other repo gets none.
+ */
+function demoPulls(watch) {
+    const dir = path.join(config.demoDir, 'payloads');
+    const primary = primaryRepo(watch);
+    if (!primary || !existsSync(dir))
+        return [];
+    const want = primary.id;
+    const byNumber = new Map();
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((f) => f.startsWith('pr_') && f.endsWith('.json'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    for (const f of files) {
+        try {
+            const body = JSON.parse(readFileSync(path.join(dir, f), 'utf8')).body;
+            const pull = body?.pull_request;
+            if (!pull?.number || String(body?.repository?.full_name ?? '').toLowerCase() !== want)
+                continue;
+            byNumber.set(Number(pull.number), { pull, ...(Array.isArray(body?.inlineDiff) ? { diff: body.inlineDiff } : {}) });
+        }
+        catch {
+            /* a broken demo payload is skipped */
+        }
+    }
+    return [...byNumber.values()].sort((a, b) => Number(b.pull.number) - Number(a.pull.number));
+}
+// Demo client: reads only local data and writes nothing. The rules gate records outward actions in the outbox.
+function demoClient(watch, event) {
+    const root = watch.runner?.workdir ?? path.join(config.demoDir, 'sample-app');
+    return {
+        mode: 'demo',
+        prFiles: async () => event?.inlineDiff ?? [],
+        compare: async () => event?.inlineDiff ?? [],
+        upsertStickyComment: async () => { },
+        createCheckRun: async () => undefined,
+        updateCheckRun: async () => { },
+        renderMarkdown: async () => null,
+        addComment: async () => { },
+        listOpenDefects: async () => [],
+        checkRunsFor: async () => [],
+        pullReviews: async () => [],
+        commitStatuses: async () => [],
+        teamMembers: async () => null,
+        pullsOfCommit: async () => null,
+        jobLog: async () => '',
+        searchCode: (q) => localSearch(root, q),
+        jobLogTail: async () => '',
+        async getStickyComment(pr) {
+            // The rules gate sends demo comments to the outbox; the newest one for this PR is the sticky.
+            const { list } = await import('../db.js');
+            const rows = list('outbox', { watchId: watch.id }, { orderBy: 'id DESC', limit: 200 });
+            const hit = rows.find((o) => o.action.kind === 'pr_comment' && Number(o.action.meta?.pr) === pr && hasStickyMarker(o.action.body));
+            return hit ? hit.action.body : null;
+        },
+        async readFile(p) {
+            const full = path.resolve(root, p);
+            if (!full.startsWith(path.resolve(root) + path.sep) || !existsSync(full))
+                return null;
+            return readFile(full, 'utf8');
+        },
+        rawDiff: async () => null,
+        artifactSource: () => undefined,
+        writePermission: async () => null,
+        async getPull(pr) {
+            const hit = demoPulls(watch).find((d) => Number(d.pull.number) === pr);
+            return hit ? { summary: pullSummary(hit.pull), payload: hit.pull, ...(hit.diff ? { inlineDiff: hit.diff } : {}) } : null;
+        },
+        async defaultBranchName() {
+            throw new Error('GitHub is not connected, so the default branch is unknown.');
+        },
+        async compareStatus() {
+            throw new Error('GitHub is not connected, so commits cannot be compared.');
+        },
+        async listPulls(limit = 20) {
+            return demoPulls(watch)
+                .map((d) => pullSummary(d.pull))
+                .filter((p) => p.state !== 'closed')
+                .slice(0, limit);
+        },
+        async getCommit(ref) {
+            const r = ref.toLowerCase();
+            if (!/^[0-9a-f]{7,40}$/.test(r))
+                return null;
+            for (const d of demoPulls(watch)) {
+                const p = d.pull;
+                const merge = String(p.merge_commit_sha ?? '');
+                const head = String(p.head?.sha ?? '');
+                const parent = String(p.base?.sha ?? '');
+                const sha = merge.startsWith(r) ? merge : head.startsWith(r) ? head : '';
+                if (sha)
+                    return { sha, parents: parent ? [parent] : [], message: String(p.title ?? ''), ...(d.diff ? { inlineDiff: d.diff } : {}) };
+            }
+            return null;
+        },
+        async cloneTo(dir) {
+            if (!existsSync(root))
+                return;
+            await cp(root, dir, {
+                recursive: true,
+                filter: (src) => !/[\\/](node_modules|\.git|test-results|playwright-report)([\\/]|$)/.test(src),
+            });
+        },
+    };
+}
+const SEARCH_SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'test-results', 'playwright-report', 'coverage']);
+const SEARCH_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|html|css|md|json|py|go|rb|java|kt|vue|svelte)$/i;
+/** Keyword search over a local checkout, one best hit per file. */
+export async function localSearch(root, q, limit = 10) {
+    const terms = q
+        .toLowerCase()
+        .split(/[^a-z0-9_-]+/)
+        .filter((t) => t.length > 2);
+    if (!terms.length || !existsSync(root))
+        return [];
+    const hits = [];
+    let seen = 0;
+    async function walk(dir) {
+        if (seen > 2000)
+            return;
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (SEARCH_SKIP.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (!SEARCH_EXT.test(entry.name) || ++seen > 2000)
+                continue;
+            if ((await stat(full)).size > 200_000)
+                continue;
+            const lines = (await readFile(full, 'utf8')).split('\n');
+            let best = -1;
+            let bestScore = 0;
+            lines.forEach((line, i) => {
+                const lower = line.toLowerCase();
+                const score = terms.filter((t) => lower.includes(t)).length;
+                if (score > bestScore) {
+                    bestScore = score;
+                    best = i;
+                }
+            });
+            if (best >= 0) {
+                const snippet = lines
+                    .slice(Math.max(0, best - 1), best + 2)
+                    .join('\n')
+                    .trim()
+                    .slice(0, 400);
+                hits.push({ path: path.relative(root, full), snippet, score: bestScore });
+            }
+        }
+    }
+    await walk(root);
+    return hits
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(({ path: p, snippet }) => ({ path: p, snippet }));
+}
+//# sourceMappingURL=github.js.map