bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/dist/src/review/contract.js

@@ -0,0 +1,189 @@
+// The events review hooks and step scripts post to the review server, validated so the agent gets errors it can act on.
+// The review app has its own copy of this type in review-app/src/kit/live.ts.
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const KINDS = ["request", "hook", "ok", "fail"];
+const STATUSES = ["ok", "fail", "neutral"];
+function str(e, v, path, optional = false) {
+    if (v === undefined && optional)
+        return;
+    if (typeof v !== "string" || !v.trim())
+        e.push(`${path}: expected a non-empty string`);
+}
+const status = (e, v, path) => STATUSES.includes(v) || void e.push(`${path}: expected one of ${STATUSES.join(", ")}`);
+export function validateEvent(v) {
+    const e = [];
+    if (!isObj(v))
+        return ["event: expected an object"];
+    str(e, v.instance, "instance");
+    if (!KINDS.includes(v.kind))
+        e.push(`kind: expected one of ${KINDS.join(", ")}`);
+    str(e, v.text, "text");
+    str(e, v.at, "at", true);
+    if (v.step !== undefined)
+        e.push("step: set by the server, leave it out");
+    if (v.flow !== undefined) {
+        if (!isObj(v.flow))
+            e.push("flow: expected an object");
+        else {
+            const f = v.flow;
+            str(e, f.id, "flow.id");
+            if (f.edge !== undefined && !(Array.isArray(f.edge) && f.edge.length === 2 && f.edge.every((n) => typeof n === "string")))
+                e.push("flow.edge: expected [from, to]");
+            str(e, f.node, "flow.node", true);
+            if (f.status !== undefined)
+                status(e, f.status, "flow.status");
+            str(e, f.label, "flow.label", true);
+        }
+    }
+    if (v.overlay !== undefined) {
+        if (!isObj(v.overlay))
+            e.push("overlay: expected an object");
+        else {
+            str(e, v.overlay.title, "overlay.title");
+            str(e, v.overlay.body, "overlay.body", true);
+            status(e, v.overlay.status, "overlay.status");
+        }
+    }
+    return e;
+}
+const SIDES = ["LEFT", "RIGHT"];
+// GitHub's limit on a comment
+export const MAX_COMMENT = 65_536;
+const FIELDS = ["to", "mode", "body", "path", "side", "line", "startSide", "startLine", "topic", "quotes", "inReplyTo", "replyTo"];
+// what a message quotes: a few things, each up to a few screens of code
+const MAX_QUOTES = 8;
+const MAX_QUOTE = 8000;
+const line = (e, v, path) => (Number.isInteger(v) && v > 0) || void e.push(`${path}: expected a line number from 1`);
+const body = (e, v) => {
+    str(e, v, "body");
+    if (typeof v === "string" && v.length > MAX_COMMENT)
+        e.push(`body: at most ${MAX_COMMENT} characters`);
+};
+export function validateComment(v) {
+    const e = [];
+    if (!isObj(v))
+        return ["comment: expected an object"];
+    for (const k of Object.keys(v))
+        if (!FIELDS.includes(k))
+            e.push(`${k}: not a comment field`);
+    if (v.to !== "github" && v.to !== "agent")
+        e.push("to: expected github or agent");
+    body(e, v.body);
+    const onLine = v.path !== undefined || v.side !== undefined || v.line !== undefined;
+    if (onLine) {
+        str(e, v.path, "path");
+        if (typeof v.path === "string" && (v.path.length > 1000 || v.path.startsWith("/") || v.path.split("/").includes("..")))
+            e.push("path: expected a file path in the repo");
+        if (!SIDES.includes(v.side))
+            e.push("side: expected LEFT or RIGHT");
+        line(e, v.line, "line");
+        if ((v.startLine === undefined) !== (v.startSide === undefined))
+            e.push("startLine, startSide: give both or neither");
+        if (v.startLine !== undefined) {
+            line(e, v.startLine, "startLine");
+            if (!SIDES.includes(v.startSide))
+                e.push("startSide: expected LEFT or RIGHT");
+        }
+    }
+    if (v.topic !== undefined) {
+        if (!isObj(v.topic))
+            e.push("topic: expected an object");
+        else {
+            str(e, v.topic.label, "topic.label");
+            str(e, v.topic.chapter, "topic.chapter", true);
+            if (v.topic.chat !== undefined && v.topic.chat !== true)
+                e.push("topic.chat: expected true");
+            for (const k of Object.keys(v.topic))
+                if (!["label", "chapter", "chat"].includes(k))
+                    e.push(`topic.${k}: not a topic field`);
+        }
+    }
+    if (v.quotes !== undefined) {
+        if (!Array.isArray(v.quotes) || v.quotes.length > MAX_QUOTES)
+            e.push(`quotes: expected a list of at most ${MAX_QUOTES}`);
+        else
+            v.quotes.forEach((q, i) => {
+                const at = `quotes[${i}]`;
+                if (!isObj(q))
+                    return void e.push(`${at}: expected an object`);
+                str(e, q.text, `${at}.text`);
+                if (typeof q.text === "string" && q.text.length > MAX_QUOTE)
+                    e.push(`${at}.text: at most ${MAX_QUOTE} characters`);
+                str(e, q.where, `${at}.where`, true);
+                if (q.kind !== undefined && q.kind !== "selection" && q.kind !== "comment")
+                    e.push(`${at}.kind: expected selection or comment`);
+                for (const k of Object.keys(q))
+                    if (!["text", "where", "kind"].includes(k))
+                        e.push(`${at}.${k}: not a quote field`);
+            });
+    }
+    if (v.inReplyTo !== undefined && !(Number.isInteger(v.inReplyTo) && v.inReplyTo > 0))
+        e.push("inReplyTo: expected the id of a GitHub comment");
+    if (v.replyTo !== undefined && !(typeof v.replyTo === "string" && /^c\d+$/.test(v.replyTo)))
+        e.push("replyTo: expected the id of a comment here");
+    if (v.inReplyTo !== undefined && !onLine)
+        e.push("inReplyTo: give the thread's path, side and line too");
+    if (v.to === "github") {
+        if (!onLine)
+            e.push("where: give a line (path, side, line)");
+        if (v.mode !== "single" && v.mode !== "review")
+            e.push("mode: expected single or review");
+        if (v.topic !== undefined || v.replyTo !== undefined || v.quotes !== undefined)
+            e.push("to: GitHub takes comments on lines and replies in its own threads only");
+    }
+    else {
+        // the agent is reached through the chat only
+        if (!(isObj(v.topic) && v.topic.chat === true))
+            e.push("topic: a message to the agent is a chat message, with topic.chat");
+        if (onLine || v.inReplyTo !== undefined)
+            e.push("to: the agent takes chat messages, not comments on lines");
+        if (v.mode !== undefined)
+            e.push("mode: only for comments to GitHub");
+    }
+    return e;
+}
+// an agent's answer to a comment sent to it
+export function validateAnswer(v) {
+    const e = [];
+    if (!isObj(v))
+        return ["answer: expected an object"];
+    for (const k of Object.keys(v))
+        if (k !== "body" && k !== "commit")
+            e.push(`${k}: not an answer field`);
+    body(e, v.body);
+    if (v.commit !== undefined && !(typeof v.commit === "string" && /^[0-9a-f]{7,40}$/.test(v.commit)))
+        e.push("commit: expected a commit sha");
+    return e;
+}
+// how the reviewer means to finish: the verdict and a summary for the top of the review
+export const EVENTS = ["COMMENT", "APPROVE", "REQUEST_CHANGES"];
+export function validateVerdict(v) {
+    const e = [];
+    if (!isObj(v))
+        return ["verdict: expected an object"];
+    for (const k of Object.keys(v))
+        if (k !== "event" && k !== "body")
+            e.push(`${k}: not a verdict field`);
+    if (v.event !== undefined && !EVENTS.includes(v.event))
+        e.push(`event: expected one of ${EVENTS.join(", ")}`);
+    if (v.body !== undefined && typeof v.body !== "string")
+        e.push("body: expected a string");
+    if (typeof v.body === "string" && v.body.length > MAX_COMMENT)
+        e.push(`body: at most ${MAX_COMMENT} characters`);
+    return e;
+}
+// where the agent is in setting up the review, in the order the prompt walks it through; the loading page shows them
+export const STAGES = {
+    read: "Reading the change",
+    instances: "Starting base and head",
+    hooks: "Adding review hooks",
+    steps: "Writing the steps",
+    shots: "Taking screenshots",
+    tour: "Writing the tour",
+    check: "Checking every page",
+};
+export function validateProgress(v) {
+    if (!isObj(v))
+        return ["progress: expected an object"];
+    return Object.hasOwn(STAGES, v.stage) ? [] : [`stage: expected one of ${Object.keys(STAGES).join(", ")}`];
+}

package/dist/src/review/github.d.ts

@@ -0,0 +1,120 @@
+import type { EVENTS, Side } from "./contract.ts";
+export interface GhRepo {
+    owner: string;
+    name: string;
+    hostname?: string;
+}
+export declare function parsePrUrl(url: string): {
+    repo: GhRepo;
+    number: number;
+} | undefined;
+export declare function graphql<T>(repo: GhRepo, query: string, variables: Record<string, unknown>, o?: {
+    missing?: boolean;
+}): Promise<T>;
+export interface ReviewThread {
+    id: string;
+    root: number;
+    resolved: boolean;
+}
+export declare function reviewThreads(repo: GhRepo, number: number): Promise<ReviewThread[]>;
+export interface GhRef {
+    node: string;
+    id: number;
+    url?: string;
+}
+export interface PendingComment extends GhRef {
+    body: string;
+    path: string;
+    line: number | null;
+    startLine: number | null;
+    side: Side;
+    startSide: Side | null;
+    replyTo?: number;
+    at: string;
+}
+export interface Pending {
+    pr: string;
+    review?: {
+        id: string;
+        url: string;
+        comments: PendingComment[];
+    };
+}
+export declare function pendingReview(repo: GhRepo, number: number): Promise<Pending>;
+export declare function startPendingReview(repo: GhRepo, pr: string, head?: string): Promise<{
+    id: string;
+    url: string;
+}>;
+export interface LineAt {
+    path: string;
+    side: Side;
+    line: number;
+    startSide?: Side;
+    startLine?: number;
+}
+export declare function addReviewThread(repo: GhRepo, review: string, at: LineAt, body: string): Promise<GhRef & {
+    thread: string;
+}>;
+export declare function addReviewReply(repo: GhRepo, review: string, thread: string, body: string): Promise<GhRef>;
+export declare function postSingle(repo: GhRepo, number: number, head: string, at: LineAt, body: string): Promise<GhRef>;
+export declare function postSingleReply(repo: GhRepo, number: number, root: number, body: string): Promise<GhRef>;
+export declare function editGhComment(repo: GhRepo, node: string, body: string): Promise<void>;
+export declare function deleteGhComment(repo: GhRepo, node: string): Promise<void>;
+export declare function commentStates(repo: GhRepo, nodes: string[]): Promise<Record<string, "PENDING" | "SUBMITTED" | null>>;
+export declare function submitReview(repo: GhRepo, o: {
+    pr: string;
+    review?: string;
+    head?: string;
+    event: (typeof EVENTS)[number];
+    body?: string;
+}): Promise<string>;
+export type MergeMethod = "MERGE" | "SQUASH" | "REBASE";
+export interface Check {
+    name: string;
+    workflow?: string;
+    status: "pass" | "fail" | "pending" | "skipped" | "neutral";
+    url?: string;
+    started?: string;
+    finished?: string;
+}
+export interface PrStatus {
+    id: string;
+    number: number;
+    title: string;
+    url: string;
+    body: string;
+    state: "OPEN" | "CLOSED" | "MERGED";
+    draft: boolean;
+    author?: string;
+    head: {
+        ref: string;
+        oid: string;
+    };
+    base: string;
+    additions: number;
+    deletions: number;
+    files: number;
+    merged?: {
+        at?: string;
+        by?: string;
+    };
+    mergeable: string;
+    mergeState: string;
+    reviewDecision?: string;
+    reviews: {
+        by: string;
+        state: string;
+        at?: string;
+    }[];
+    requested: string[];
+    checks: Check[];
+    canMerge: boolean;
+    methods: MergeMethod[];
+    defaultMethod?: MergeMethod;
+}
+export declare function prStatus(repo: GhRepo, number: number): Promise<PrStatus>;
+export declare function mergePr(repo: GhRepo, o: {
+    id: string;
+    method: MergeMethod;
+    head: string;
+}): Promise<void>;

package/dist/src/review/github.js

@@ -0,0 +1,160 @@
+// GitHub through the gh CLI and whatever login it has: review threads when a review starts (on this machine), and the
+// reviewer's comments and review as they write them (in the review box, with its GH_TOKEN).
+import { run } from "../util.js";
+// a PR's link, e.g. https://github.com/acme/rply/pull/18, as the repo and number gh needs
+export function parsePrUrl(url) {
+    const m = url.match(/^https:\/\/([^/]+)\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    if (!m)
+        return undefined;
+    const host = m[1].toLowerCase();
+    return { repo: { owner: m[2], name: m[3], ...(host !== "github.com" && { hostname: host }) }, number: Number(m[4]) };
+}
+const host = (repo) => (repo.hostname ? ["--hostname", repo.hostname] : []);
+async function gh(args, stdin) {
+    try {
+        return await run("gh", args, { check: false, stdin });
+    }
+    catch {
+        throw new Error("the gh CLI is not installed");
+    }
+}
+// variables go as JSON so nothing is coerced; throws with GitHub's own message.
+// missing: ids that resolve to nothing come back as null instead of failing the query
+export async function graphql(repo, query, variables, o = {}) {
+    const r = await gh(["api", "graphql", ...host(repo), "--input", "-"], JSON.stringify({ query, variables }));
+    let res = {};
+    try {
+        res = JSON.parse(r.stdout);
+    }
+    catch { }
+    if (o.missing && res.data && res.errors?.every((e) => e.type === "NOT_FOUND"))
+        return res.data;
+    if (r.code !== 0 || res.errors?.length || !res.data)
+        throw new Error(`GitHub said: ${res.errors?.map((e) => e.message).join("; ") || r.stderr.trim().slice(0, 300) || "nothing"}`);
+    return res.data;
+}
+const at = (repo, number) => ({ owner: repo.owner, name: repo.name, number });
+// every review thread on the PR, keyed by its first comment's REST id
+export async function reviewThreads(repo, number) {
+    const query = "query($owner: String!, $name: String!, $number: Int!, $after: String) { repository(owner: $owner, name: $name) { pullRequest(number: $number) { reviewThreads(first: 100, after: $after) { pageInfo { hasNextPage endCursor } nodes { id isResolved comments(first: 1) { nodes { databaseId } } } } } } }";
+    const out = [];
+    let after;
+    // ponytail: stops at 1000 threads; no PR reviewed in a tour has that many
+    for (let page = 0; page < 10; page++) {
+        const t = (await graphql(repo, query, { ...at(repo, number), ...(after && { after }) })).repository.pullRequest.reviewThreads;
+        for (const n of t.nodes)
+            if (n.comments.nodes[0])
+                out.push({ id: n.id, root: n.comments.nodes[0].databaseId, resolved: n.isResolved });
+        if (!t.pageInfo.hasNextPage)
+            break;
+        after = t.pageInfo.endCursor;
+    }
+    return out;
+}
+const COMMENT = "id databaseId url";
+const ref = (c) => ({ node: c.id, id: c.databaseId, ...(c.url && { url: c.url }) });
+// the PR's node id and the reviewer's pending review on it, with its comments; GitHub shows each reviewer only their own
+export async function pendingReview(repo, number) {
+    // ponytail: the first 100 pending comments; a review with more shows only those
+    const q = `query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { pullRequest(number: $number) { id reviews(states: PENDING, first: 1) { nodes { id url comments(first: 100) { nodes { ${COMMENT} body path line startLine replyTo { databaseId } createdAt } } } } } } }`;
+    const p = (await graphql(repo, q, at(repo, number))).repository.pullRequest;
+    const r = p.reviews.nodes[0];
+    return {
+        pr: p.id,
+        ...(r && {
+            review: {
+                id: r.id,
+                url: r.url,
+                // ponytail: a comment has no side, its thread does; one added on github.com is taken to be on the new file
+                comments: r.comments.nodes.map((c) => ({ ...ref(c), body: c.body, path: c.path, line: c.line, startLine: c.startLine, side: "RIGHT", startSide: c.startLine ? "RIGHT" : null, ...(c.replyTo && { replyTo: c.replyTo.databaseId }), at: c.createdAt })),
+            },
+        }),
+    };
+}
+export async function startPendingReview(repo, pr, head) {
+    return (await graphql(repo, "mutation($pullRequestId: ID!, $commitOID: GitObjectID) { addPullRequestReview(input: { pullRequestId: $pullRequestId, commitOID: $commitOID }) { pullRequestReview { id url } } }", { pullRequestId: pr, commitOID: head })).addPullRequestReview.pullRequestReview;
+}
+// a new thread in the pending review
+export async function addReviewThread(repo, review, at, body) {
+    const t = (await graphql(repo, `mutation($reviewId: ID!, $path: String!, $body: String!, $line: Int!, $side: DiffSide, $startLine: Int, $startSide: DiffSide) { addPullRequestReviewThread(input: { pullRequestReviewId: $reviewId, path: $path, body: $body, line: $line, side: $side, startLine: $startLine, startSide: $startSide }) { thread { id comments(first: 1) { nodes { ${COMMENT} } } } } }`, { reviewId: review, body, ...at })).addPullRequestReviewThread.thread;
+    return { ...ref(t.comments.nodes[0]), thread: t.id };
+}
+// a reply in a thread, in the pending review
+export async function addReviewReply(repo, review, thread, body) {
+    return ref((await graphql(repo, `mutation($reviewId: ID!, $threadId: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewId: $reviewId, pullRequestReviewThreadId: $threadId, body: $body }) { comment { ${COMMENT} } } }`, { reviewId: review, threadId: thread, body })).addPullRequestReviewThreadReply.comment);
+}
+// GitHub's "Add single comment": posted at once, outside any review (REST, which GraphQL has no mutation for)
+export async function postSingle(repo, number, head, at, body) {
+    return rest(repo, `pulls/${number}/comments`, { body, commit_id: head, path: at.path, line: at.line, side: at.side, ...(at.startLine && { start_line: at.startLine, start_side: at.startSide }) });
+}
+export async function postSingleReply(repo, number, root, body) {
+    return rest(repo, `pulls/${number}/comments/${root}/replies`, { body });
+}
+async function rest(repo, path, input) {
+    const r = await gh(["api", ...host(repo), "-X", "POST", `repos/${repo.owner}/${repo.name}/${path}`, "--input", "-"], JSON.stringify(input));
+    let c = {};
+    try {
+        c = JSON.parse(r.stdout);
+    }
+    catch { }
+    if (r.code !== 0 || !c.id || !c.node_id)
+        throw new Error(`GitHub said: ${c.message ?? (r.stderr.trim().slice(0, 300) || "nothing")}`);
+    return { node: c.node_id, id: c.id, ...(c.html_url && { url: c.html_url }) };
+}
+export async function editGhComment(repo, node, body) {
+    await graphql(repo, "mutation($id: ID!, $body: String!) { updatePullRequestReviewComment(input: { pullRequestReviewCommentId: $id, body: $body }) { pullRequestReviewComment { id } } }", { id: node, body });
+}
+export async function deleteGhComment(repo, node) {
+    await graphql(repo, "mutation($id: ID!) { deletePullRequestReviewComment(input: { id: $id }) { pullRequestReview { id } } }", { id: node });
+}
+// which of these comments GitHub still has, and whether they were submitted (null when deleted)
+export async function commentStates(repo, nodes) {
+    if (!nodes.length)
+        return {};
+    const r = await graphql(repo, "query($ids: [ID!]!) { nodes(ids: $ids) { ... on PullRequestReviewComment { id state } } }", { ids: nodes }, { missing: true });
+    return Object.fromEntries(nodes.map((n, i) => [n, r.nodes[i]?.state ?? null]));
+}
+// submits the pending review with the verdict and summary, or posts a review of just those when there is none
+export async function submitReview(repo, o) {
+    if (o.review) {
+        return (await graphql(repo, "mutation($reviewId: ID!, $event: PullRequestReviewEvent!, $body: String) { submitPullRequestReview(input: { pullRequestReviewId: $reviewId, event: $event, body: $body }) { pullRequestReview { url } } }", { reviewId: o.review, event: o.event, body: o.body })).submitPullRequestReview.pullRequestReview.url;
+    }
+    return (await graphql(repo, "mutation($pullRequestId: ID!, $commitOID: GitObjectID, $event: PullRequestReviewEvent, $body: String) { addPullRequestReview(input: { pullRequestId: $pullRequestId, commitOID: $commitOID, event: $event, body: $body }) { pullRequestReview { url } } }", { pullRequestId: o.pr, commitOID: o.head, event: o.event, body: o.body })).addPullRequestReview.pullRequestReview.url;
+}
+const CHECKS = "statusCheckRollup { contexts(first: 100) { nodes { __typename ... on CheckRun { name status conclusion detailsUrl startedAt completedAt checkSuite { workflowRun { workflow { name } } } } ... on StatusContext { context state targetUrl createdAt } } } }";
+export async function prStatus(repo, number) {
+    const q = `query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { viewerPermission mergeCommitAllowed squashMergeAllowed rebaseMergeAllowed viewerDefaultMergeMethod pullRequest(number: $number) { id number title url body state isDraft author { login } headRefName headRefOid baseRefName additions deletions changedFiles mergedAt mergedBy { login } mergeable mergeStateStatus reviewDecision reviews(last: 50) { nodes { author { login } state submittedAt } } reviewRequests(first: 20) { nodes { requestedReviewer { ... on User { login } ... on Team { name } } } } commits(last: 1) { nodes { commit { ${CHECKS} } } } } } }`;
+    const r = (await graphql(repo, q, at(repo, number))).repository;
+    const p = r.pullRequest;
+    const run = (c) => {
+        if (c.__typename === "StatusContext") {
+            const s = c.state === "SUCCESS" ? "pass" : c.state === "PENDING" || c.state === "EXPECTED" ? "pending" : "fail";
+            return { name: c.context ?? "status", status: s, ...(c.targetUrl && { url: c.targetUrl }), ...(c.createdAt && { started: c.createdAt }) };
+        }
+        const s = c.status !== "COMPLETED" ? "pending" : c.conclusion === "SUCCESS" ? "pass" : c.conclusion === "SKIPPED" ? "skipped" : c.conclusion === "NEUTRAL" ? "neutral" : "fail";
+        const workflow = c.checkSuite?.workflowRun?.workflow?.name;
+        return { name: c.name ?? "check", status: s, ...(workflow && { workflow }), ...(c.detailsUrl && { url: c.detailsUrl }), ...(c.startedAt && { started: c.startedAt }), ...(c.completedAt && { finished: c.completedAt }) };
+    };
+    // the latest review of each reviewer counts, as on GitHub; comments alone do not change it
+    const latest = new Map();
+    for (const v of p.reviews.nodes)
+        if (v.author && v.state !== "PENDING" && (v.state !== "COMMENTED" || !latest.has(v.author.login)))
+            latest.set(v.author.login, { by: v.author.login, state: v.state, ...(v.submittedAt && { at: v.submittedAt }) });
+    const methods = [["SQUASH", r.squashMergeAllowed], ["MERGE", r.mergeCommitAllowed], ["REBASE", r.rebaseMergeAllowed]].filter(([, ok]) => ok).map(([m]) => m);
+    return {
+        id: p.id, number: p.number, title: p.title, url: p.url, body: p.body ?? "", state: p.state, draft: p.isDraft, ...(p.author && { author: p.author.login }),
+        head: { ref: p.headRefName, oid: p.headRefOid }, base: p.baseRefName, additions: p.additions, deletions: p.deletions, files: p.changedFiles,
+        ...(p.state === "MERGED" && { merged: { ...(p.mergedAt && { at: p.mergedAt }), ...(p.mergedBy && { by: p.mergedBy.login }) } }),
+        mergeable: p.mergeable, mergeState: p.mergeStateStatus, ...(p.reviewDecision && { reviewDecision: p.reviewDecision }),
+        reviews: [...latest.values()],
+        requested: p.reviewRequests.nodes.map((n) => n.requestedReviewer?.login ?? n.requestedReviewer?.name).filter((x) => !!x),
+        checks: (p.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? []).map(run),
+        canMerge: ["ADMIN", "MAINTAIN", "WRITE"].includes(r.viewerPermission ?? ""),
+        methods,
+        ...(r.viewerDefaultMergeMethod && methods.includes(r.viewerDefaultMergeMethod) && { defaultMethod: r.viewerDefaultMergeMethod }),
+    };
+}
+// merges the PR, only if its head is still the commit the reviewer saw
+export async function mergePr(repo, o) {
+    await graphql(repo, "mutation($id: ID!, $method: PullRequestMergeMethod!, $head: GitObjectID!) { mergePullRequest(input: { pullRequestId: $id, mergeMethod: $method, expectedHeadOid: $head }) { pullRequest { merged } } }", { id: o.id, method: o.method, head: o.head });
+}

package/dist/src/review/local.d.ts

@@ -0,0 +1,14 @@
+export interface LocalChanges {
+    raw: Record<string, unknown>;
+    diff: string;
+    base: string;
+    branch: string;
+    head: Buffer;
+    baseTree: Buffer;
+}
+export declare function localChanges(root: string, opts?: {
+    base?: string;
+    note?: string;
+    repo?: string;
+    exclude?: string[];
+}): Promise<LocalChanges>;

package/dist/src/review/local.js

@@ -0,0 +1,70 @@
+// The local changes of a checkout, as a review sees them: head is the working tree (commits, uncommitted and untracked
+// files), base is where the branch left the default branch. Read without touching the checkout or its index.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { BsError } from "../config.js";
+import { run } from "../util.js";
+import { workingTree } from "../repo.js";
+async function git(root, args, env = {}) {
+    const r = await run("git", args, { cwd: root, check: false, env });
+    if (r.code !== 0)
+        throw new BsError("git_failed", `git ${args.join(" ")} failed: ${r.stderr.trim().slice(0, 300)}`, "run it in the repo yourself to see why");
+    return r.stdout;
+}
+// the default branch: origin's HEAD, else main or master
+async function defaultBranch(root) {
+    const head = await run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: root, check: false });
+    if (head.code === 0 && head.stdout.trim())
+        return head.stdout.trim();
+    for (const b of ["origin/main", "origin/master", "main", "master"])
+        if ((await run("git", ["rev-parse", "--verify", "--quiet", b], { cwd: root, check: false })).code === 0)
+            return b;
+    throw new BsError("no_base", "could not tell which branch these changes are based on", "pass --base <branch or commit>");
+}
+const tarOf = (root, ref) => new Promise((resolve, reject) => {
+    const p = spawn("git", ["archive", "--format=tar", ref], { cwd: root });
+    const chunks = [];
+    let err = "";
+    p.stdout.on("data", (d) => chunks.push(d));
+    p.stderr.on("data", (d) => (err += d));
+    p.on("error", reject);
+    p.on("close", (code) => (code === 0 ? resolve(Buffer.concat(chunks)) : reject(new BsError("git_failed", `git archive ${ref} failed: ${err.trim()}`, "check that the base exists"))));
+});
+// exclude: files that never belong in the diff, e.g. the .env files, which hold secrets and reach the box on their own
+export async function localChanges(root, opts = {}) {
+    const against = opts.base ?? (await defaultBranch(root));
+    const base = (await git(root, ["merge-base", "HEAD", against])).trim();
+    const branch = (await run("git", ["symbolic-ref", "--short", "HEAD"], { cwd: root, check: false })).stdout.trim() || "local changes";
+    // the working tree as one snapshot, staged in a throwaway index so the user's stays as it is
+    const tmp = mkdtempSync(join(tmpdir(), "bs-index-"));
+    const env = { GIT_INDEX_FILE: join(tmp, "index") };
+    let diff, numstat;
+    try {
+        await git(root, ["read-tree", "HEAD"], env);
+        await git(root, ["add", "-A"], env);
+        if (opts.exclude?.length)
+            await git(root, ["rm", "--cached", "-q", "--ignore-unmatch", "--", ...opts.exclude], env);
+        diff = await git(root, ["diff", "--cached", "--no-color", base], env);
+        numstat = await git(root, ["diff", "--cached", "--numstat", base], env);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    if (!diff.trim())
+        throw new BsError("no_changes", `nothing changed since ${against} (${base.slice(0, 7)})`, "make changes first, or pass --base <ref> to compare with something else");
+    const files = numstat.trim().split("\n").map((l) => {
+        const [a, d, path] = l.split("\t");
+        return { path, additions: Number(a) || 0, deletions: Number(d) || 0 };
+    });
+    const author = (await run("git", ["config", "user.name"], { cwd: root, check: false })).stdout.trim() || "you";
+    return {
+        raw: { number: 0, title: branch, url: "", repo: opts.repo ?? root.split("/").pop(), body: opts.note ?? "", author: { login: author }, baseRefName: against.replace(/^origin\//, ""), headRefName: branch, files, comments: [], reviews: [] },
+        diff,
+        base,
+        branch,
+        head: await workingTree(root),
+        baseTree: await tarOf(root, base),
+    };
+}

package/dist/src/review/loop.d.ts

@@ -0,0 +1,12 @@
+import { type Box } from "../boxes.ts";
+import type { Waited } from "./comments.ts";
+export declare function waitForComments(b: Box, seconds?: number, retry?: number): Promise<Waited>;
+export type Hooks = "kept" | "conflict" | "none";
+export declare function updateReview(b: Box, root: string, o: {
+    note: string;
+    answers: Record<string, string>;
+}): Promise<{
+    update: number;
+    hooks: Hooks;
+}>;
+export declare function refreshPrompt(n: number, note: string, hooks: Hooks): string;