post-merge-cleanup

1import { atom, update } from 'claude-code'
2import type { EngineInterface, ProcessRunResult, Register } from 'claude-code'
3
4import {
5  decide,
6  isSamePath,
7  lastLine,
8  missingRequirement,
9  NEEDS_GH,
10  NEEDS_GIT,
11  NOT_A_REPO,
12  parsePrs,
13  parseWorktrees,
14  pickPr,
15  PR_FIELDS,
16  question,
17  summary,
18} from './plan'
19import type { Checkout, Facts, PullRequest, Step } from './plan'
20
21const COMMAND = 'cleanup'
22const GO = 'Go'
23const CANCEL = 'Cancel'
24/** A pull or a prune talks to the remote; give it longer than the 30 s default. */
25const STEP_TIMEOUT_MS = 120_000
26/** The start-up suggestion stays long enough to read the command in it. */
27const SUGGEST_MS = 8_000
28
29const hasChecked = atom({ plugin: 'post-merge-cleanup', key: 'hasChecked' } as const, false)
30
31/** A requirement the mod lacks, carrying the sentence that names it. */
32class Missing extends Error {}
33
34/**
35 * Whether any surface shows the session right now. Asked before the start-up
36 * check, never kept. Each mod carries its own copy (ADR-0001).
37 */
38async function isShown($: EngineInterface): Promise<boolean> {
39  return (await $.session.surfaces()).length > 0
40}
41
42/** Runs git or gh by bare name; one that cannot start is a missing requirement. */
43async function run($: EngineInterface, argv: readonly string[], cwd?: string): Promise<ProcessRunResult> {
44  try {
45    return await $.process.run(argv, cwd === undefined ? {} : { cwd })
46  } catch (error) {
47    // A timeout rejects too; tell it from a missing tool by whether the tool starts at all.
48    const tool = argv[0] ?? ''
49    if (!(await canStart($, tool))) throw new Missing(tool === 'gh' ? NEEDS_GH : NEEDS_GIT)
50    throw error
51  }
52}
53
54async function canStart($: EngineInterface, tool: string): Promise<boolean> {
55  try {
56    await $.process.run([tool, '--version'])
57    return true
58  } catch {
59    return false
60  }
61}
62
63/** Runs a command that must succeed and answers its trimmed output. */
64async function ask($: EngineInterface, argv: readonly string[], cwd?: string): Promise<string> {
65  const result = await run($, argv, cwd)
66  if (result.exitCode !== 0) {
67    if (argv[0] === 'gh') {
68      const missing = missingRequirement(result.exitCode, result.stderr)
69      if (missing !== undefined) throw new Missing(missing)
70    }
71    throw new Error(`${argv.slice(0, 3).join(' ')} failed: ${lastLine(result.stderr) || `exit ${result.exitCode}`}`)
72  }
73  return result.stdout.trim()
74}
75
76async function defaultBranch($: EngineInterface): Promise<string> {
77  return ask($, ['gh', 'repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name'])
78}
79
80async function findPr($: EngineInterface, branch: string): Promise<PullRequest | undefined> {
81  const json = await ask($, ['gh', 'pr', 'list', '--head', branch, '--state', 'all', '--limit', '10', '--json', PR_FIELDS])
82  return pickPr(parsePrs(json))
83}
84
85/** The local branch's tip, or '' when there is no such branch. */
86async function tipOf($: EngineInterface, branch: string): Promise<string> {
87  const result = await run($, ['git', 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
88  return result.exitCode === 0 ? result.stdout.trim() : ''
89}
90
91async function isClean($: EngineInterface, cwd?: string): Promise<boolean> {
92  return (await ask($, ['git', 'status', '--porcelain'], cwd)) === ''
93}
94
95/** Everything decide() needs, read from git and gh; nothing here changes the checkout. */
96async function gather($: EngineInterface, args: string): Promise<Facts> {
97  const top = await run($, ['git', 'rev-parse', '--show-toplevel'])
98  if (top.exitCode !== 0) throw new Missing(NOT_A_REPO)
99  const sessionPath = top.stdout.trim()
100  const currentBranch = await ask($, ['git', 'branch', '--show-current'])
101  const branch = args.trim() === '' ? currentBranch : args.trim()
102  const base = await defaultBranch($)
103  if (branch === '' || branch === base) {
104    return { branch, currentBranch, defaultBranch: base, pr: undefined, tip: '', isTreeClean: true, checkout: undefined }
105  }
106
107  const [pr, tip, isTreeClean, worktrees] = await Promise.all([
108    findPr($, branch),
109    tipOf($, branch),
110    isClean($),
111    ask($, ['git', 'worktree', 'list', '--porcelain']).then(parseWorktrees),
112  ])
113  const index = worktrees.findIndex(worktree => worktree.branch === branch)
114  let checkout: Checkout | undefined
115  if (index >= 0) {
116    const path = worktrees[index]!.path
117    const isSession = isSamePath(path, sessionPath)
118    const isMain = index === 0
119    // Only a worktree that would be removed needs its own check.
120    checkout = { path, isMain, isSession, isClean: isSession || isMain ? true : await isClean($, path) }
121  }
122  return { branch, currentBranch, defaultBranch: base, pr, tip, isTreeClean, checkout }
123}
124
125/** Runs the steps in order, stopping at the first failure; answers what to tell the person. */
126async function carryOut($: EngineInterface, branch: string, steps: readonly Step[]): Promise<string> {
127  for (const step of steps) {
128    let result: ProcessRunResult
129    try {
130      result = await $.process.run(step.argv, { timeoutMs: STEP_TIMEOUT_MS })
131    } catch (error) {
132      return `Cleanup stopped at "${step.todo}": ${error instanceof Error ? error.message : String(error)}`
133    }
134    if (result.exitCode !== 0) {
135      return `Cleanup stopped at "${step.todo}": ${lastLine(result.stderr) || lastLine(result.stdout) || `exit ${result.exitCode}`}`
136    }
137  }
138  return summary(branch, steps)
139}
140
141async function cleanup($: EngineInterface, args: string): Promise<string> {
142  const facts = await gather($, args)
143  const decision = decide(facts)
144  if ('refuse' in decision) return decision.refuse
145
146  let answer: string
147  try {
148    answer = await $.ui.ask(question(decision.pr, decision.steps), { options: [GO, CANCEL], header: 'Cleanup' })
149  } catch {
150    // Dismissed, or nobody to ask (a -p run).
151    return 'Cleanup cancelled; nothing was changed.'
152  }
153  if (answer !== GO) return 'Cleanup cancelled; nothing was changed.'
154
155  const said = await carryOut($, facts.branch, decision.steps)
156  $.ui.toast(said)
157  return said
158}
159
160/** The start-up check: one look at the session's branch, and a toast when its PR has merged. */
161async function suggest($: EngineInterface): Promise<void> {
162  const branch = await ask($, ['git', 'branch', '--show-current'])
163  if (branch === '') return
164  const [base, pr] = await Promise.all([defaultBranch($), findPr($, branch)])
165  if (branch === base || pr?.state !== 'MERGED') return
166  $.ui.toast(`PR #${pr.number} for ${branch} merged. Run /${COMMAND} to switch to ${base}, pull and delete the branch.`, {
167    timeoutMs: SUGGEST_MS,
168  })
169}
170
171/** Runs the start-up check once per session, and only while a surface shows it. */
172async function checkOnce($: EngineInterface): Promise<void> {
173  if (!(await isShown($))) return
174  let isFirst = false
175  await update($, hasChecked, was => {
176    isFirst = !was
177    return true
178  })
179  if (isFirst) await suggest($)
180}
181
182/** Quiet on failure: a missing gh is named when the person runs /cleanup, not at start. */
183function logQuietly($: EngineInterface): (error: unknown) => void {
184  return error => $.ui.log(`post-merge-cleanup: start-up check: ${error instanceof Error ? error.message : String(error)}`, { to: 'debug' })
185}
186
187export const register: Register = on => {
188  on('session.start', async ($, e, next) => {
189    await $.command.register({
190      name: COMMAND,
191      description: 'After a PR merges: switch to the default branch, pull, and delete the branch and its worktree',
192      argumentHint: '[branch]',
193    })
194    const done = await next(e)
195    void checkOnce($).catch(logQuietly($))
196    return done
197  })
198
199  // A session that started headless checks once when a surface first shows it.
200  on('session.attach', async ($, e, next) => {
201    const done = await next(e)
202    void checkOnce($).catch(logQuietly($))
203    return done
204  })
205
206  on('command.run', { command: COMMAND }, async ($, e) => {
207    try {
208      return { text: await cleanup($, e.args) }
209    } catch (error) {
210      return { text: error instanceof Missing ? error.message : `Cleanup failed: ${error instanceof Error ? error.message : String(error)}` }
211    }
212  })
213}
214

1/** The fields asked of `gh pr list`; parsePrs reads these. */
2export const PR_FIELDS = 'number,state,headRefOid'
3
4export type PullRequest = {
5  number: number
6  state: 'OPEN' | 'CLOSED' | 'MERGED'
7  /** The commit the PR's head pointed at: for a merged PR, the commit it merged. */
8  headRefOid: string
9}
10
11/** One entry of `git worktree list --porcelain`; `branch` is '' for a detached head. */
12export type Worktree = { path: string; branch: string }
13
14/** Where the branch to clean up is checked out, if anywhere. */
15export type Checkout = {
16  path: string
17  /** The main checkout: the first worktree git lists. It is never removed. */
18  isMain: boolean
19  /** The checkout this session runs in. */
20  isSession: boolean
21  /** Nothing staged, unstaged or untracked; only asked of a worktree that would be removed. */
22  isClean: boolean
23}
24
25/** What the mod found before deciding: every answer is git's or gh's. */
26export type Facts = {
27  /** The branch to clean up: the argument, or the session's branch. */
28  branch: string
29  /** The session's branch; '' for a detached head. */
30  currentBranch: string
31  defaultBranch: string
32  pr: PullRequest | undefined
33  /** The local branch's tip; '' when there is no such local branch. */
34  tip: string
35  /** The session's tree has nothing staged, unstaged or untracked. */
36  isTreeClean: boolean
37  checkout: Checkout | undefined
38}
39
40/** One git command of the cleanup, run in the session's folder. */
41export type Step = {
42  /** What it will do, for the question. */
43  todo: string
44  /** What it did, for the closing toast. */
45  done: string
46  argv: string[]
47}
48
49export type Decision = { refuse: string } | { pr: number; steps: Step[] }
50
51function isRecord(value: unknown): value is Record<string, unknown> {
52  return typeof value === 'object' && value !== null && !Array.isArray(value)
53}
54
55/** Parses `gh pr list --json PR_FIELDS`, dropping malformed rows; throws on output that is not a list. */
56export function parsePrs(json: string): PullRequest[] {
57  const rows: unknown = JSON.parse(json)
58  if (!Array.isArray(rows)) throw new Error('gh pr list did not answer a list')
59  return rows.flatMap((row): PullRequest[] => {
60    if (!isRecord(row)) return []
61    const { number, state, headRefOid } = row
62    if (typeof number !== 'number' || typeof headRefOid !== 'string') return []
63    if (state !== 'OPEN' && state !== 'CLOSED' && state !== 'MERGED') return []
64    return [{ number, state, headRefOid }]
65  })
66}
67
68/** The PR that speaks for a branch: a merged one first, then an open one, then any. gh lists the newest first. */
69export function pickPr(prs: readonly PullRequest[]): PullRequest | undefined {
70  return prs.find(pr => pr.state === 'MERGED') ?? prs.find(pr => pr.state === 'OPEN') ?? prs[0]
71}
72
73/** Parses `git worktree list --porcelain`: blocks of `worktree <path>`, then `branch refs/heads/<name>` or `detached`. */
74export function parseWorktrees(porcelain: string): Worktree[] {
75  const worktrees: Worktree[] = []
76  for (const line of porcelain.split(/\r?\n/)) {
77    if (line.startsWith('worktree ')) worktrees.push({ path: line.slice('worktree '.length), branch: '' })
78    const last = worktrees[worktrees.length - 1]
79    if (line.startsWith('branch refs/heads/') && last !== undefined) last.branch = line.slice('branch refs/heads/'.length)
80  }
81  return worktrees
82}
83
84/** Whether two paths git printed name the same folder: slashes folded, and case too for a Windows drive path. */
85export function isSamePath(a: string, b: string): boolean {
86  const fold = (path: string) => {
87    const slashed = path.replace(/\\/g, '/').replace(/\/+$/, '')
88    return /^[a-z]:\//i.test(slashed) ? slashed.toLowerCase() : slashed
89  }
90  return fold(a) === fold(b)
91}
92
93/**
94 * Decides from the facts: a refusal naming the first check that failed, or the
95 * steps to run. Nothing here changes the checkout; the steps run only after the
96 * person says Go.
97 */
98export function decide(facts: Facts): Decision {
99  const { branch, currentBranch, defaultBranch, pr, tip, checkout } = facts
100  if (branch === '') return { refuse: 'Not on a branch. Run /cleanup <branch> to name the branch to clean up.' }
101  if (branch === defaultBranch) return { refuse: `${branch} is the default branch; there is nothing to clean up.` }
102  if (pr === undefined) return { refuse: `${branch} has no pull request, so nothing was changed.` }
103  if (pr.state === 'OPEN') return { refuse: `PR #${pr.number} for ${branch} is still open, so nothing was changed.` }
104  if (pr.state === 'CLOSED') {
105    return { refuse: `PR #${pr.number} for ${branch} was closed without merging, so nothing was changed.` }
106  }
107  if (tip === '') return { refuse: `There is no local branch ${branch}, so there is nothing to delete.` }
108  if (tip !== pr.headRefOid) {
109    return {
110      refuse: `${branch} has commits that are not in PR #${pr.number}: its tip is not the commit the PR merged. Push or drop them first.`,
111    }
112  }
113  if (checkout?.isSession === true && !checkout.isMain) {
114    return {
115      refuse: `This session runs inside ${branch}'s own worktree. Run /cleanup ${branch} from the main checkout.`,
116    }
117  }
118  if (checkout?.isMain === true && !checkout.isSession) {
119    return { refuse: `${branch} is checked out in the main checkout at ${checkout.path}. Run /cleanup there.` }
120  }
121  if (!facts.isTreeClean) {
122    return { refuse: 'The working tree has uncommitted or untracked changes. Commit, stash or remove them first.' }
123  }
124  if (checkout !== undefined && !checkout.isSession && !checkout.isClean) {
125    return {
126      refuse: `The worktree at ${checkout.path} has uncommitted or untracked changes. Commit, stash or remove them first.`,
127    }
128  }
129
130  const steps: Step[] = []
131  if (currentBranch !== defaultBranch) {
132    steps.push({ todo: `switch to ${defaultBranch}`, done: `switched to ${defaultBranch}`, argv: ['git', 'switch', defaultBranch] })
133  }
134  steps.push({ todo: `pull ${defaultBranch}`, done: `pulled ${defaultBranch}`, argv: ['git', 'pull', '--ff-only'] })
135  if (checkout !== undefined && !checkout.isSession) {
136    steps.push({
137      todo: `remove the worktree at ${checkout.path}`,
138      done: `removed the worktree at ${checkout.path}`,
139      argv: ['git', 'worktree', 'remove', checkout.path],
140    })
141  }
142  // -D, not -d: a squash merge leaves the branch unmerged in git's eyes. The tip check above is what makes it safe.
143  steps.push({
144    todo: `delete ${branch} (PR #${pr.number} merged)`,
145    done: `deleted ${branch}`,
146    argv: ['git', 'branch', '-D', branch],
147  })
148  steps.push({ todo: 'prune remote-tracking branches', done: 'pruned', argv: ['git', 'fetch', '--prune'] })
149  return { pr: pr.number, steps }
150}
151
152/** The one question asked before anything changes. */
153export function question(pr: number, steps: readonly Step[]): string {
154  return `PR #${pr} merged. Clean up: ${steps.map(step => step.todo).join(', ')}?`
155}
156
157/** What the closing toast says. */
158export function summary(branch: string, steps: readonly Step[]): string {
159  return `Cleaned up ${branch}: ${steps.map(step => step.done).join(', ')}.`
160}
161
162/** What the person sees when gh cannot start. */
163export const NEEDS_GH = 'post-merge-cleanup needs the GitHub CLI (gh). Install it from cli.github.com, then run /cleanup again.'
164/** What the person sees when git cannot start. */
165export const NEEDS_GIT = 'post-merge-cleanup needs git. Install it from git-scm.com, then run /cleanup again.'
166/** What the person sees when gh is not logged in. */
167export const NOT_LOGGED_IN = 'gh is not logged in. Run gh auth login in a terminal, then run /cleanup again.'
168/** What the person sees outside a git repository. */
169export const NOT_A_REPO = 'This folder is not a git repository, so there is nothing to clean up.'
170/** What the person sees when the repository has no GitHub remote. */
171export const NOT_A_GITHUB_REPO = 'This repository has no GitHub remote, so gh cannot tell whether a PR merged.'
172
173/** gh's exit code for a command that needs authentication (`gh help exit-codes`). */
174const GH_AUTH_EXIT = 4
175
176/** The requirement a failed gh call names, or undefined when the failure is something else. */
177export function missingRequirement(exitCode: number, stderr: string): string | undefined {
178  if (exitCode === GH_AUTH_EXIT || /gh auth login|not logged in/i.test(stderr)) return NOT_LOGGED_IN
179  if (/no git remotes|none of the git remotes|not a git repository/i.test(stderr)) return NOT_A_GITHUB_REPO
180  return undefined
181}
182
183/** The last non-empty line of a command's output, cut short, for a toast. */
184export function lastLine(output: string): string {
185  const lines = output.trim().split(/\r?\n/)
186  return lines[lines.length - 1]?.slice(0, 200) ?? ''
187}
188

1/** Whether this session's start-up check for a merged PR has run: at start, or at the first attach. */
2export type HasChecked = boolean
3
4declare module 'claude-code' {
5  interface PluginState {
6    'post-merge-cleanup': {
7      hasChecked: HasChecked
8    }
9  }
10}
11