src/maintenance-branches.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/github/prune.ts, src/maintenance.ts, src/store-guards.ts, src/time.ts. Imported by src/maintenance.ts.

Source

1import type { Env } from "./env";
2import { ghFetch } from "./github/client";
3import { deletePruneCandidates, readPrunePlan, type PruneCandidate, type PruneKept, type PrunePlan } from "./github/prune";
4import type { MaintenanceItem } from "./maintenance";
5import { auditStatement } from "./store-guards";
6import { DAY_MS } from "./time";
7
8// The daily maintenance pass's branch rules (job_549550d73d4e, piece 3). A merged branch is
9// one capsid_close_pr action delete_branch with merged:true would prune (job_8779278b8e91, src/github/prune.ts): its
10// latest pull request merged and its tip is the commit that pull request merged from. The
11// same plan is read here, so the default branch, a branch with an open pull request and a
12// branch with commits after its merge are refused exactly as the tool refuses them.
13//
14// Deleting is destructive, so the auto-prune ships off (conventions 2.3). Off, the merged
15// branches are listed with a count and nothing is deleted. On, at most PRUNE_CAP per repo
16// per run are deleted, each one re-read just before its delete and audit-logged with the
17// sha it pointed at, so it can be put back. Every other branch with no open pull request
18// whose last commit is older than STALE_DAYS is listed with its age. A keep list, kept in
19// APP_KV with an empty default, names branches that are never pruned and never listed.
20//
21// With the switch on, a branch with no open pull request and no commit for ORPHAN_DAYS is
22// deleted too, in the same cap and with the same audit row (job_9dbaf2ecfd2c; Dustin,
23// 2026-10-14: every repo's branches down to the default and those with an open pull request
24// or active work). Only when every list was read in full, and never the default, a
25// protected or keep-listed branch, or a screenshot branch an open pull request
26// still shows (src/github/prune.ts, shotsInUse).
27
28/** The switch the seat sets to "on" to let the pass delete merged branches. Anything else,
29 *  or no key, is off. A KV key rather than a control: a control would add to a served
30 *  tool's surface (CLAUDE.md, tool surface rule). */
31export const PRUNE_SWITCH_KEY = "maintenance:prune-merged";
32/** The keep list: a JSON object of namespace to branch names, e.g.
33 *  {"sample": ["review/one"]}. No key is an empty list. */
34export const BRANCH_KEEP_KEY = "maintenance:branch-keep";
35
36export const PRUNE_CAP = 25;
37const STALE_DAYS = 30;
38const ORPHAN_DAYS = 2;
39// Commit dates read per repo per run; more stale candidates are listed as not checked.
40const AGE_READS_PER_REPO = 30;
41const MAX_ITEMS_PER_RULE = 50;
42const SYSTEM_ACTOR = "system:maintenance";
43export const PRUNE_AUDIT_ACTION = "maintenance-prune-branch";
44
45interface BranchSettings {
46  prune: boolean;
47  keep: Record<string, string[]>;
48}
49
50export interface BranchReaders {
51  /** The prune rule's plan for the namespace's repo, with the keep list applied. Throws
52   *  when a list could not be read. */
53  plan(namespace: string, keep: string[]): Promise<PrunePlan>;
54  /** When the commit was made. Throws when it could not be read. */
55  committedAt(plan: PrunePlan, sha: string): Promise<string>;
56  /** Delete up to `cap` of the plan's candidates, each tip re-read first, calling
57   *  `onDeleted` after each delete and before the next. */
58  prune(plan: PrunePlan, cap: number, onDeleted: (c: PruneCandidate) => Promise<void>): Promise<{ deleted: PruneCandidate[]; skipped: PruneKept[]; remaining: number }>;
59}
60
61/** The switch and the keep list. A keep list that is not a JSON object of string arrays
62 *  throws, so the pass says the branches were not checked rather than prune without it. */
63async function readBranchSettings(kv: KVNamespace): Promise<BranchSettings> {
64  const [switchRaw, keepRaw] = await Promise.all([kv.get(PRUNE_SWITCH_KEY), kv.get(BRANCH_KEEP_KEY)]);
65  const keep: Record<string, string[]> = {};
66  if (keepRaw) {
67    const parsed: unknown = JSON.parse(keepRaw);
68    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`${BRANCH_KEEP_KEY} is not a JSON object`);
69    for (const [ns, names] of Object.entries(parsed)) {
70      if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) throw new Error(`${BRANCH_KEEP_KEY}.${ns} is not a list of branch names`);
71      keep[ns] = names as string[];
72    }
73  }
74  return { prune: switchRaw === "on", keep };
75}
76
77const days = (ms: number): number => Math.floor(ms / DAY_MS);
78
79/** The branch rules over every namespace in `namespaces`, and how many branches each read,
80 *  so "nothing listed" can be told from "nothing read". */
81export async function gatherBranchItems(
82  env: Env,
83  namespaces: readonly string[],
84  readers: BranchReaders,
85  now: Date
86): Promise<{ items: MaintenanceItem[]; read: Record<string, number>; pruned: number }> {
87  const items: MaintenanceItem[] = [];
88  const read: Record<string, number> = {};
89  let pruned = 0;
90
91  let settings: BranchSettings;
92  try {
93    settings = await readBranchSettings(env.APP_KV);
94  } catch (err) {
95    const why = `the prune switch or keep list could not be read: ${err instanceof Error ? err.message : String(err)}`;
96    return { items: namespaces.map((ns) => notChecked(ns, why)), read, pruned };
97  }
98
99  for (const namespace of namespaces) {
100    let plan: PrunePlan;
101    try {
102      plan = await readers.plan(namespace, settings.keep[namespace] ?? []);
103    } catch (err) {
104      items.push(notChecked(namespace, err instanceof Error ? err.message : String(err)));
105      continue;
106    }
107    read[namespace] = plan.branchesRead;
108    let prunedHere = 0;
109
110    if (settings.prune) {
111      // One audit row per deleted branch, written before the next delete, with the sha it
112      // pointed at: the deletion is put back by pushing that sha to the branch name
113      // (snapshot invariant, test/write-invariants.test.ts). A failed audit write stops the deletes and the pass.
114      const done = await readers.prune(plan, PRUNE_CAP, async (c) => {
115        await auditStatement(env.DB, SYSTEM_ACTOR, PRUNE_AUDIT_ACTION, namespace, null, { repo: plan.repo, branch: c.branch, sha: c.sha, pr: c.pr }).run();
116      });
117      pruned += done.deleted.length;
118      prunedHere = done.deleted.length;
119      for (const c of done.deleted.slice(0, MAX_ITEMS_PER_RULE)) {
120        items.push({
121          rule: "branch-pruned",
122          namespace,
123          job: null,
124          line: `${plan.repo} branch ${c.branch} was deleted: pull request #${c.pr} merged from its tip ${c.sha}. Put it back with git push origin ${c.sha}:refs/heads/${c.branch} if it was wanted.`,
125        });
126      }
127      for (const s of done.skipped) {
128        items.push({ rule: "branch-merged", namespace, job: null, line: `${plan.repo} branch ${s.branch} is merged and was not pruned: ${s.reason}.` });
129      }
130      if (done.remaining > 0) {
131        items.push({ rule: "branch-merged", namespace, job: null, line: `${done.remaining} more merged branch(es) in ${plan.repo} wait for the next run (${PRUNE_CAP} are deleted per repo per run).` });
132      }
133    } else if (plan.prune.length > 0) {
134      for (const c of plan.prune.slice(0, MAX_ITEMS_PER_RULE)) {
135        items.push({ rule: "branch-merged", namespace, job: null, line: `${plan.repo} branch ${c.branch} is merged (pull request #${c.pr}, tip ${c.sha}): delete it, or keep-list it.` });
136      }
137      items.push({
138        rule: "branch-merged",
139        namespace,
140        job: null,
141        line: `${plan.prune.length} merged branch(es) in ${plan.repo} would be pruned; the auto-prune is off, so none was deleted.`,
142      });
143    }
144
145    // Anything else old. A branch with an open pull request is not an orphan, and that is
146    // known only when the open list was read in full.
147    if (!plan.openComplete) {
148      items.push(notChecked(namespace, `the open pull request list of ${plan.repo} was not read in full, so no branch is listed as stale`));
149      continue;
150    }
151    const orphans = plan.kept.filter((k) => k.orphan);
152    const reading = orphans.slice(0, AGE_READS_PER_REPO);
153    if (orphans.length > reading.length) {
154      items.push(notChecked(namespace, `${orphans.length - reading.length} branch(es) in ${plan.repo} with no open pull request had their age not read`));
155    }
156    const stale: Array<{ branch: string; reason: string; age: number; sha: string; ms: number }> = [];
157    for (const k of reading) {
158      let at: string;
159      try {
160        at = await readers.committedAt(plan, k.sha);
161      } catch (err) {
162        items.push(notChecked(namespace, `the last commit of ${plan.repo} branch ${k.branch}: ${err instanceof Error ? err.message : String(err)}`));
163        continue;
164      }
165      const ms = now.getTime() - Date.parse(at);
166      stale.push({ branch: k.branch, reason: k.reason, age: days(ms), sha: k.sha, ms });
167    }
168    stale.sort((a, b) => b.ms - a.ms);
169
170    if (settings.prune && plan.listsComplete) {
171      const old = stale.filter((s) => s.ms >= ORPHAN_DAYS * DAY_MS);
172      const budget = Math.max(0, PRUNE_CAP - prunedHere);
173      const done = old.length === 0 ? { deleted: [], skipped: [], remaining: 0 } : await readers.prune({ ...plan, prune: old.map((s) => ({ branch: s.branch, sha: s.sha, pr: null })) }, budget, async (c) => {
174        await auditStatement(env.DB, SYSTEM_ACTOR, PRUNE_AUDIT_ACTION, namespace, null, { repo: plan.repo, branch: c.branch, sha: c.sha, pr: null }).run();
175      });
176      pruned += done.deleted.length;
177      const why = new Map(old.map((s) => [s.branch, s]));
178      for (const c of done.deleted.slice(0, MAX_ITEMS_PER_RULE)) {
179        const s = why.get(c.branch)!;
180        items.push({
181          rule: "branch-pruned",
182          namespace,
183          job: null,
184          line: `${plan.repo} branch ${c.branch} was deleted: no open pull request and no commit for ${s.age} days (${s.reason}). Put it back with git push origin ${c.sha}:refs/heads/${c.branch} if it was wanted.`,
185        });
186      }
187      for (const k of done.skipped) items.push({ rule: "branch-stale", namespace, job: null, line: `${plan.repo} branch ${k.branch} is old and was not pruned: ${k.reason}.` });
188      if (done.remaining > 0) {
189        items.push({ rule: "branch-stale", namespace, job: null, line: `${done.remaining} more old branch(es) in ${plan.repo} wait for the next run (${PRUNE_CAP} are deleted per repo per run).` });
190      }
191      continue;
192    }
193    for (const s of stale.filter((x) => x.age > STALE_DAYS).slice(0, MAX_ITEMS_PER_RULE)) {
194      items.push({ rule: "branch-stale", namespace, job: null, line: `${plan.repo} branch ${s.branch} has had no commit for ${s.age} days (${s.reason}): delete it, open its pull request, or keep-list it.` });
195    }
196  }
197  return { items, read, pruned };
198}
199
200function notChecked(namespace: string, problem: string): MaintenanceItem {
201  return {
202    rule: "branches-not-checked",
203    namespace,
204    job: null,
205    line: `Branches in ${namespace} were not fully checked (${problem}): what is missing is not a clean result.`,
206  };
207}
208
209/** The readers on GitHub, through the App: delete_branch merged's own plan and delete step
210 *  (src/github/prune.ts), and one commit read per orphan branch for its date. */
211export function githubBranchReaders(env: Env): BranchReaders {
212  return {
213    plan: (namespace, keep) => readPrunePlan(env, namespace, keep),
214    async committedAt(plan, sha) {
215      const resp = await ghFetch(env, plan.owner, plan.name, `/repos/${plan.owner}/${plan.name}/commits/${sha}`);
216      if (!resp.ok) {
217        await resp.body?.cancel();
218        throw new Error(`the commit read returned ${resp.status}`);
219      }
220      const commit = (await resp.json()) as { commit?: { committer?: { date?: string } } };
221      const date = commit.commit?.committer?.date;
222      if (!date) throw new Error("the commit carries no committer date");
223      return date;
224    },
225    prune: (plan, cap, onDeleted) => deletePruneCandidates(env, plan, cap, onDeleted),
226  };
227}