src/github/refs.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts. Imported by src/approval-executor.ts, src/auto-merge-tick.ts, src/github.ts, src/github/contents.ts, src/tools/repo.ts.

Source

1import type { RepoEnv as Env } from "../env";
2import {
3  assertRepoArg,
4  cachedGet,
5  encodePath,
6  getDefaultBranch,
7  getRefSha,
8  ghFetch,
9  invalidateRepoReads,
10  resolveRepo,
11} from "./client";
12
13// The create-a-work-branch step, shared by write_repo_file and delete_repo_file in
14// pr mode. create_branch does not use it: as an explicit tool it must fail when the
15// branch already exists, and this tolerates that case.
16export async function ensureBranch(env: Env, owner: string, repo: string, branch: string, fromSha: string): Promise<void> {
17  const created = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/git/refs`, {
18    method: "POST",
19    headers: { "Content-Type": "application/json" },
20    body: JSON.stringify({ ref: `refs/heads/${branch}`, sha: fromSha }),
21  });
22  // 422 means the branch already exists, which is fine when a caller passed one.
23  if (!created.ok && created.status !== 422) {
24    throw new Error(`branch create failed (${created.status}): ${await created.text()}`);
25  }
26}
27
28export async function createBranch(env: Env, namespace: string, branch: string, from?: string, repoSelector?: string) {
29  assertRepoArg("branch", branch);
30  if (from) assertRepoArg("from", from);
31  const { owner, repo } = await resolveRepo(env, namespace, repoSelector);
32  const base = from || (await getDefaultBranch(env, owner, repo));
33  const sha = await getRefSha(env, owner, repo, base);
34  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/git/refs`, {
35    method: "POST",
36    headers: { "Content-Type": "application/json" },
37    body: JSON.stringify({ ref: `refs/heads/${branch}`, sha }),
38  });
39  if (!resp.ok) throw new Error(`create_branch failed (${resp.status}): ${await resp.text()}`);
40  return { repo: `${owner}/${repo}`, branch, from: base, sha };
41}
42
43export async function openPr(
44  env: Env,
45  namespace: string,
46  title: string,
47  head: string,
48  base?: string,
49  body?: string,
50  repoSelector?: string
51) {
52  const { owner, repo } = await resolveRepo(env, namespace, repoSelector);
53  const baseBranch = base || (await getDefaultBranch(env, owner, repo));
54  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls`, {
55    method: "POST",
56    headers: { "Content-Type": "application/json" },
57    body: JSON.stringify({ title, head, base: baseBranch, body: body ?? "" }),
58  });
59  if (!resp.ok) throw new Error(`open_pr failed (${resp.status}): ${await resp.text()}`);
60  const data = (await resp.json()) as { number: number; html_url: string };
61  return { repo: `${owner}/${repo}`, number: data.number, url: data.html_url, head, base: baseBranch };
62}
63
64// Merge or close an open pull request. Merging can trigger CI deploys in repos with
65// deploy workflows, so callers gate by blast radius.
66//
67// The head branch is deleted when a PR closes or merges, because write_repo_file's
68// default PR mode creates a branch per write and nothing else cleans them up. Two
69// refusals:
70//   1. Never the default branch. A PR whose head is the default branch is a
71//      cross-fork PR or a misconfiguration.
72//   2. Never fails the PR action. The merge or close already succeeded, and failing
73//      the call because a branch delete failed would misreport it. Same rule as
74//      invalidateRepoReads. The outcome is reported in head_branch_deleted.
75async function deleteHeadBranchAfterPr(
76  env: Env,
77  owner: string,
78  repo: string,
79  number: number
80): Promise<{ head_branch: string | null; head_branch_deleted: boolean; head_branch_note?: string }> {
81  try {
82    const prResp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls/${number}`);
83    if (!prResp.ok) {
84      return { head_branch: null, head_branch_deleted: false, head_branch_note: `could not read the PR to find its head branch (${prResp.status})` };
85    }
86    const pr = (await prResp.json()) as {
87      head: { ref: string; repo?: { full_name?: string } | null };
88      base: { ref: string };
89    };
90    const branch = pr.head.ref;
91
92    // A head branch on a FORK is not this App's to delete, and the token could not
93    // anyway. Compared by full_name rather than inferred from the ref.
94    const headRepo = pr.head.repo?.full_name;
95    if (headRepo && headRepo !== `${owner}/${repo}`) {
96      return { head_branch: branch, head_branch_deleted: false, head_branch_note: `head is on ${headRepo}, not this repo, so it was left alone` };
97    }
98    if (branch === pr.base.ref) {
99      return { head_branch: branch, head_branch_deleted: false, head_branch_note: "head and base are the same branch, so nothing was deleted" };
100    }
101    const defaultBranch = await getDefaultBranch(env, owner, repo);
102    if (branch === defaultBranch) {
103      return { head_branch: branch, head_branch_deleted: false, head_branch_note: "head is the default branch, which is never deleted" };
104    }
105    const del = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/git/refs/heads/${encodePath(branch)}`, { method: "DELETE" });
106    if (!del.ok) {
107      return { head_branch: branch, head_branch_deleted: false, head_branch_note: `delete failed (${del.status}); the PR action itself succeeded` };
108    }
109    return { head_branch: branch, head_branch_deleted: true };
110  } catch (err) {
111    return {
112      head_branch: null,
113      head_branch_deleted: false,
114      head_branch_note: `branch cleanup errored: ${err instanceof Error ? err.message : String(err)}; the PR action itself succeeded`,
115    };
116  }
117}
118
119// A merge refused because the PR head is no longer the sha the caller named. GitHub
120// answers 409 for that case. Thrown only when an expected sha was passed, so a caller
121// that pinned the head can tell this refusal from any other merge failure.
122export class HeadMovedError extends Error {
123  readonly expectedSha: string;
124  constructor(expectedSha: string, detail: string) {
125    super(`merge refused: the PR head is no longer ${expectedSha} (409): ${detail}`);
126    this.name = "HeadMovedError";
127    this.expectedSha = expectedSha;
128  }
129}
130
131export async function managePr(
132  env: Env,
133  namespace: string,
134  number: number,
135  action: "merge" | "close" | "comment",
136  mergeMethod: "merge" | "squash" | "rebase" = "squash",
137  repoSelector?: string,
138  comment?: string,
139  // For a merge: the head sha the caller judged. Sent as `sha`, so GitHub merges only
140  // that commit and refuses with 409 if the head moved.
141  expectedSha?: string
142) {
143  const { owner, repo } = await resolveRepo(env, namespace, repoSelector);
144  // A comment leaves the pull request open and changes no branch, so it is handled
145  // first: it must never reach the head-branch cleanup below, which exists because
146  // merge and close end a pull request.
147  if (action === "comment") {
148    if (!comment) throw new Error("comment needs a body; a comment action with nothing to say is a call that did nothing.");
149    const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/issues/${number}/comments`, {
150      method: "POST",
151      headers: { "Content-Type": "application/json" },
152      body: JSON.stringify({ body: comment }),
153    });
154    if (!resp.ok) throw new Error(`comment failed (${resp.status}): ${await resp.text()}`);
155    const data = (await resp.json()) as { id: number; html_url: string };
156    return { repo: `${owner}/${repo}`, number, action: "comment", comment_id: data.id, url: data.html_url };
157  }
158  if (action === "merge") {
159    const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls/${number}/merge`, {
160      method: "PUT",
161      headers: { "Content-Type": "application/json" },
162      body: JSON.stringify(expectedSha ? { merge_method: mergeMethod, sha: expectedSha } : { merge_method: mergeMethod }),
163    });
164    if (resp.status === 409 && expectedSha) throw new HeadMovedError(expectedSha, await resp.text());
165    if (!resp.ok) throw new Error(`merge failed (${resp.status}): ${await resp.text()}`);
166    const data = (await resp.json()) as { sha: string; merged: boolean; message: string };
167    // A merge changes the base branch's contents, so it is a write to every path the
168    // PR touched. Those paths are not known here, which is why invalidation sweeps
169    // the repo prefix.
170    await invalidateRepoReads(env, owner, repo);
171    const cleanup = await deleteHeadBranchAfterPr(env, owner, repo, number);
172    return {
173      repo: `${owner}/${repo}`,
174      number,
175      action: "merge",
176      merged: data.merged,
177      sha: data.sha,
178      message: data.message,
179      ...cleanup,
180    };
181  }
182  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls/${number}`, {
183    method: "PATCH",
184    headers: { "Content-Type": "application/json" },
185    body: JSON.stringify({ state: "closed" }),
186  });
187  if (!resp.ok) throw new Error(`close failed (${resp.status}): ${await resp.text()}`);
188  const data = (await resp.json()) as { number: number; state: string; html_url: string };
189  const cleanup = await deleteHeadBranchAfterPr(env, owner, repo, number);
190  return { repo: `${owner}/${repo}`, number: data.number, action: "close", state: data.state, url: data.html_url, ...cleanup };
191}
192
193// The read tools below expose what the App installation token already reaches. Each
194// goes through resolveRepo, ghFetch and cachedGet; nothing opens its own path to
195// api.github.com.
196
197/** Branches, tags and open PRs in one call. The triage question is "what is in flight
198 *  here", which is three GETs the caller would otherwise make separately.
199 *  Ahead/behind is per branch against the default branch. */
200export async function repoRefs(env: Env, namespace: string, repoSelector?: string) {
201  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
202  const base = `/repos/${owner}/${repo}`;
203  const defaultBranch = await getDefaultBranch(env, owner, repo);
204
205  const [branchResp, tagResp, prResp] = await Promise.all([
206    cachedGet(env, owner, repo, `${base}/branches?per_page=100`),
207    cachedGet(env, owner, repo, `${base}/tags?per_page=100`),
208    cachedGet(env, owner, repo, `${base}/pulls?state=open&per_page=100`),
209  ]);
210  if (!branchResp.ok) throw new Error(`repo_refs branches failed (${branchResp.status}): ${(await branchResp.text()).slice(0, 200)}`);
211  if (!tagResp.ok) throw new Error(`repo_refs tags failed (${tagResp.status}): ${(await tagResp.text()).slice(0, 200)}`);
212  if (!prResp.ok) throw new Error(`repo_refs pulls failed (${prResp.status}): ${(await prResp.text()).slice(0, 200)}`);
213
214  const branchRows = (await branchResp.json()) as Array<{ name: string; commit: { sha: string } }>;
215  const tagRows = (await tagResp.json()) as Array<{ name: string; commit: { sha: string } }>;
216  const prRows = (await prResp.json()) as Array<{
217    number: number;
218    title: string;
219    head: { ref: string };
220    base: { ref: string };
221    updated_at: string;
222    html_url: string;
223  }>;
224
225  const prByHead = new Map(prRows.map((p) => [p.head.ref, p.number]));
226
227  // Ahead/behind comes from the compare endpoint, one call per branch. The default
228  // branch is skipped: compared with itself it is always 0/0. The fan-out is bounded
229  // by the 100-branch page above; a repo with more branches reports its first hundred
230  // and sets truncated.
231  const branches = await Promise.all(
232    branchRows.map(async (b) => {
233      const row: {
234        name: string;
235        sha: string;
236        committed_date: string | null;
237        ahead_by: number | null;
238        behind_by: number | null;
239        open_pr: number | null;
240        is_default: boolean;
241      } = {
242        name: b.name,
243        sha: b.commit.sha,
244        committed_date: null,
245        ahead_by: null,
246        behind_by: null,
247        open_pr: prByHead.get(b.name) ?? null,
248        is_default: b.name === defaultBranch,
249      };
250      if (b.name === defaultBranch) {
251        row.ahead_by = 0;
252        row.behind_by = 0;
253        return row;
254      }
255      const cmp = await cachedGet(
256        env,
257        owner,
258        repo,
259        `${base}/compare/${encodeURIComponent(defaultBranch)}...${encodeURIComponent(b.name)}`
260      );
261      if (cmp.ok) {
262        const c = (await cmp.json()) as {
263          ahead_by: number;
264          behind_by: number;
265          commits?: Array<{ commit: { committer: { date: string } } }>;
266        };
267        row.ahead_by = c.ahead_by;
268        row.behind_by = c.behind_by;
269        const last = c.commits?.[c.commits.length - 1];
270        if (last) row.committed_date = last.commit.committer.date;
271      }
272      return row;
273    })
274  );
275
276  return {
277    repo: full,
278    default_branch: defaultBranch,
279    truncated: branchRows.length === 100 || tagRows.length === 100 || prRows.length === 100,
280    branches,
281    tags: tagRows.map((t) => ({ name: t.name, sha: t.commit.sha })),
282    pull_requests: prRows.map((p) => ({
283      number: p.number,
284      title: p.title,
285      head: p.head.ref,
286      base: p.base.ref,
287      updated_at: p.updated_at,
288      url: p.html_url,
289    })),
290  };
291}
292
293export const REPO_HISTORY_DEFAULT_LIMIT = 20;
294export const REPO_HISTORY_MAX_LIMIT = 100;
295export const REPO_PATCH_BUDGET = 200 * 1024;
296
297function summariseCommit(c: { sha: string; commit: { message: string; author: { name: string; date: string } } }) {
298  return {
299    sha: c.sha,
300    date: c.commit.author.date,
301    author: c.commit.author.name,
302    // First line only. Commit bodies here run to paragraphs, and inlining them buries
303    // the shape of the history. Read one commit by sha for the full message.
304    subject: c.commit.message.split("\n")[0],
305  };
306}
307
308// Patch bodies are OFF by default and budgeted when on. The file list is always
309// returned: names, status and line counts answer most questions and cost nothing.
310function filesWithBudget(
311  files: Array<{ filename: string; status: string; additions: number; deletions: number; patch?: string }>,
312  wantPatch: boolean
313) {
314  let spent = 0;
315  let truncated = false;
316  const out = files.map((f) => {
317    const row: { path: string; status: string; additions: number; deletions: number; patch?: string } = {
318      path: f.filename,
319      status: f.status,
320      additions: f.additions,
321      deletions: f.deletions,
322    };
323    if (wantPatch && f.patch) {
324      if (spent + f.patch.length <= REPO_PATCH_BUDGET) {
325        row.patch = f.patch;
326        spent += f.patch.length;
327      } else {
328        truncated = true;
329      }
330    }
331    return row;
332  });
333  return { count: out.length, patch_truncated: truncated, patch_bytes: spent, entries: out };
334}
335
336/** Commits, a comparison, or one commit, chosen by which args are present. An
337 *  ambiguous combination is refused rather than resolved by precedence: a caller
338 *  passing both sha and base has two questions, and neither is answered silently. */
339export async function repoHistory(
340  env: Env,
341  namespace: string,
342  args: { ref?: string; base?: string; head?: string; sha?: string; limit?: number; patch?: boolean },
343  repoSelector?: string
344) {
345  for (const [kind, value] of [["ref", args.ref], ["base", args.base], ["head", args.head], ["sha", args.sha]] as const) {
346    if (value) assertRepoArg(kind, value);
347  }
348  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
349  const apiBase = `/repos/${owner}/${repo}`;
350
351  if (args.base && !args.head) throw new Error("repo_history: base was given without head; a comparison needs both");
352  if (args.head && !args.base) throw new Error("repo_history: head was given without base; a comparison needs both");
353  const hasCompare = Boolean(args.base && args.head);
354  const asked = [args.sha ? "sha" : null, hasCompare ? "base+head" : null, args.ref ? "ref" : null].filter(Boolean);
355  if (asked.length > 1) {
356    throw new Error(`repo_history: ${asked.join(" and ")} are different questions; pass exactly one of sha, base+head, or ref`);
357  }
358  if (asked.length === 0) {
359    throw new Error("repo_history: pass ref for commits on a ref, base and head to compare, or sha for one commit");
360  }
361
362  const limit = Math.min(Math.max(args.limit ?? REPO_HISTORY_DEFAULT_LIMIT, 1), REPO_HISTORY_MAX_LIMIT);
363
364  if (args.sha) {
365    const resp = await cachedGet(env, owner, repo, `${apiBase}/commits/${encodeURIComponent(args.sha)}`);
366    if (!resp.ok) throw new Error(`repo_history commit failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
367    const c = (await resp.json()) as {
368      sha: string;
369      commit: { message: string; author: { name: string; date: string } };
370      parents: Array<{ sha: string }>;
371      files?: Array<{ filename: string; status: string; additions: number; deletions: number; patch?: string }>;
372    };
373    return {
374      repo: full,
375      mode: "commit" as const,
376      commit: {
377        sha: c.sha,
378        date: c.commit.author.date,
379        author: c.commit.author.name,
380        message: c.commit.message,
381        parents: c.parents.map((p) => p.sha),
382      },
383      files: filesWithBudget(c.files ?? [], args.patch === true),
384    };
385  }
386
387  if (hasCompare) {
388    const resp = await cachedGet(
389      env,
390      owner,
391      repo,
392      `${apiBase}/compare/${encodeURIComponent(args.base as string)}...${encodeURIComponent(args.head as string)}`
393    );
394    if (!resp.ok) throw new Error(`repo_history compare failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
395    const c = (await resp.json()) as {
396      status: string;
397      ahead_by: number;
398      behind_by: number;
399      total_commits: number;
400      commits: Array<{ sha: string; commit: { message: string; author: { name: string; date: string } } }>;
401      files?: Array<{ filename: string; status: string; additions: number; deletions: number; patch?: string }>;
402    };
403    return {
404      repo: full,
405      mode: "compare" as const,
406      base: args.base,
407      head: args.head,
408      status: c.status,
409      ahead_by: c.ahead_by,
410      behind_by: c.behind_by,
411      total_commits: c.total_commits,
412      commits: c.commits.slice(0, limit).map(summariseCommit),
413      files: filesWithBudget(c.files ?? [], args.patch === true),
414    };
415  }
416
417  const resp = await cachedGet(env, owner, repo, `${apiBase}/commits?sha=${encodeURIComponent(args.ref as string)}&per_page=${limit}`);
418  if (!resp.ok) throw new Error(`repo_history commits failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
419  const rows = (await resp.json()) as Array<{ sha: string; commit: { message: string; author: { name: string; date: string } } }>;
420  return { repo: full, mode: "commits" as const, ref: args.ref, limit, commits: rows.map(summariseCommit) };
421}
422
423/** Delete a branch. Three refusals; force lifts only two, never the default branch. */
424export async function deleteBranch(
425  env: Env,
426  namespace: string,
427  branch: string,
428  opts: { force?: boolean } = {},
429  repoSelector?: string
430) {
431  assertRepoArg("branch", branch);
432  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
433  const base = `/repos/${owner}/${repo}`;
434  const defaultBranch = await getDefaultBranch(env, owner, repo);
435
436  // Not liftable by force: a flag that could delete a repo's default branch
437  // eventually will, so this is checked before force is read.
438  if (branch === defaultBranch) {
439    throw new Error(`delete_branch refuses: ${branch} is the default branch of ${full}. force does not lift this refusal.`);
440  }
441
442  if (!opts.force) {
443    const prResp = await cachedGet(env, owner, repo, `${base}/pulls?state=open&head=${encodeURIComponent(`${owner}:${branch}`)}`);
444    // Fail closed: a lookup that errors is not "no open PRs". Skipping the refusal on
445    // a 5xx would delete the branches this check protects whenever GitHub is flaky.
446    if (!prResp.ok) {
447      throw new Error(
448        `delete_branch refuses: could not verify open pull requests for ${branch} on ${full} (${prResp.status}), so the open-PR refusal cannot run. Retry, or pass force: true to delete without the check.`
449      );
450    }
451    const prs = (await prResp.json()) as Array<{ number: number; html_url: string }>;
452    if (prs.length > 0) {
453      throw new Error(
454        `delete_branch refuses: ${branch} has open pull request #${prs[0].number} (${prs[0].html_url}). Pass force: true to delete it anyway.`
455      );
456    }
457  }
458
459  const resp = await ghFetch(env, owner, repo, `${base}/git/refs/heads/${encodePath(branch)}`, { method: "DELETE" });
460  if (resp.status === 422 || resp.status === 404) {
461    throw new Error(`delete_branch failed: ${branch} does not exist on ${full} (${resp.status})`);
462  }
463  if (!resp.ok) throw new Error(`delete_branch failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
464  await invalidateRepoReads(env, owner, repo);
465  return { repo: full, branch, deleted: true, forced: opts.force === true };
466}