merge-gate

1import type { Register, EngineInterface } from 'claude-code'
2
3// "Do NOT merge PRs unless I explicitly say merge." A merge is a deploy with no approval gate
4// behind it, so this mod denies the Bash merge verbs unless the latest human message contains
5// the word merge. "ship", "push", "deploy" and "land" authorise landing work on the branch, not
6// merging it; the user expects to press merge themselves.
7
8const MOD = 'merge-gate'
9const ENABLED_KEY = 'merge-gate:enabled'
10const HUMAN_ORIGINS: readonly string[] = ['composer', 'bridge', 'sdk']
11const TRUNK = ['main', 'master']
12
13const GIT = String.raw`(^|[\s&;|('"])git(\s+-\S+(\s+\S+)?)*\s+`
14const PR_MERGE = new RegExp(String.raw`(pulls/[0-9]+/merge|merge_requests/[0-9]+/merge|(^|[\s&;|('"])["']?gh["']?\s+pr\s+merge(\s|$|["'])|(^|[\s&;|('"])gh\s+api\s[^|;&]*/merge(\s|$|["']))`, 'm')
15const GIT_MERGE = new RegExp(GIT + String.raw`merge(\s|$|["'])`, 'm')
16const GIT_MERGE_LOCAL = new RegExp(GIT + String.raw`merge\s+--(abort|continue|quit)(\s|$)`, 'm')
17const GIT_PUSH = new RegExp(GIT + String.raw`push(\s|$|["'])`, 'm')
18const INERT = /^(echo|printf|grep|rg|ag|cat|less|head|tail)\b|^git(\s+-\S+(\s+\S+)?)*\s+(commit|log|show|grep)\b/
19const GIT_VALUED = ['-C', '-c', '--git-dir', '--work-tree', '--namespace']
20const SAYS_MERGE = /\bmerge\b/i
21const NEGATED = /\b(don'?t|do not|never|no|not)\s+(\w+\s+)?merge\b/i
22const GRANT_COUNT = /\bmerge\s*[x*]\s*([0-9]+)\b|\b([0-9]+)\s+merges\b/i
23const GRANT_EACH = /\bmerge\s+(after|between|per|each|every)\b|\b(after|between)\s+each\b[^.]{0,40}\bmerge\b/i
24const GRANT_EACH_USES = 5
25
26let latest: string | undefined
27let grantUses = 0
28let enabled = true
29
30// Only a segment that prints or records text is dropped; a quoted merge anywhere else (bash -c, eval) runs.
31const executable = (command: string) =>
32  command
33    .split(/&&|\|\||;|\||\n/)
34    .filter(seg => !INERT.test(seg.replace(/^[\s(]*(\w+=\S*\s+)*/, '')))
35    .join(' ; ')
36
37const saysMerge = (text: string) => {
38  const t = text.replace(/\bmerge-gate\b/gi, '')
39  return SAYS_MERGE.test(t) && !NEGATED.test(t)
40}
41
42const grantOf = (text: string): number => {
43  const m = text.replace(/\n/g, ' ').match(GRANT_COUNT)
44  const n = Number(m?.[1] ?? m?.[2])
45  if (n > 0) return n
46  return GRANT_EACH.test(text) ? GRANT_EACH_USES : 0
47}
48
49// Every branch a `git push` in the command writes to; undefined when one is left to git's default.
50const pushTargets = (command: string): string[] | undefined => {
51  const tokens = command.replace(/\n/g, ' ; ').split(/\s+/).filter(Boolean)
52  const targets: string[] = []
53  for (let i = 0; i < tokens.length; i++) {
54    if (tokens[i] !== 'git') continue
55    i++
56    while (tokens[i]?.startsWith('-')) i += GIT_VALUED.includes(tokens[i] ?? '') ? 2 : 1
57    if (tokens[i] !== 'push') continue
58    i++
59    let remote = false
60    let named = false
61    for (; i < tokens.length && !['&&', '||', ';', '|'].includes(tokens[i] ?? ''); i++) {
62      const token = tokens[i] ?? ''
63      if (['--repo', '--push-option', '--receive-pack', '--exec', '-o'].includes(token)) i++
64      else if (token.startsWith('-')) continue
65      else if (!remote) remote = true
66      else {
67        named = true
68        targets.push(token.replace(/^\+/, '').split(':').pop()?.replace(/^refs\/heads\//, '') ?? '')
69      }
70    }
71    if (!named) return undefined
72  }
73  return targets
74}
75
76const git = async ($: EngineInterface, args: string[]) => {
77  const run = await $.process.run(['git', ...args])
78  return run.exitCode === 0 ? run.stdout.trim() : undefined
79}
80
81const hasPrFlow = async ($: EngineInterface) => /github|gitlab|bitbucket/i.test((await git($, ['remote', 'get-url', 'origin'])) ?? '')
82
83const isMerge = async ($: EngineInterface, command: string): Promise<boolean> => {
84  const bare = executable(command)
85  if (PR_MERGE.test(bare)) return true
86  if (GIT_MERGE.test(bare) && !GIT_MERGE_LOCAL.test(bare)) return TRUNK.includes((await git($, ['rev-parse', '--abbrev-ref', 'HEAD'])) ?? '')
87  if (!GIT_PUSH.test(bare)) return false
88  const targets = pushTargets(bare)
89  if (!targets?.some(t => TRUNK.includes(t))) return false
90  const branch = await git($, ['rev-parse', '--abbrev-ref', 'HEAD'])
91  return branch !== undefined && !TRUNK.includes(branch) && (await hasPrFlow($))
92}
93
94// Tracked prompts are exact; after a resume the transcript stands in, every user message counted as human.
95const latestHuman = async ($: EngineInterface): Promise<string | undefined> => {
96  if (latest !== undefined) return latest
97  const messages = await $.session.messages()
98  return messages.filter(m => m.role === 'user' && !m.toolResults?.length && m.text.trim() !== '').at(-1)?.text
99}
100
101const DENIED = [
102  'merge-gate: Yash has not said merge in his latest message. Ask him, or he says \'merge\' and this passes.',
103  '"ship", "push", "deploy" and "land" do not count: stop at the push, report the PR state, and let him merge.',
104].join('\n')
105
106// The first thing anyone does when a mod misbehaves is try to turn it off. `CLAUDE_MODS_DISABLE=all`,
107// or a comma list naming this mod, makes every hook here a pass-through and registers no command.
108let disabled = false
109const readDisabled = async ($: EngineInterface): Promise<boolean> => {
110  const raw = (await $.env.get('CLAUDE_MODS_DISABLE').catch(() => undefined)) ?? ''
111  disabled = raw
112    .split(',')
113    .map(v => v.trim())
114    .some(v => v === 'all' || v === MOD)
115  return disabled
116}
117
118export const register: Register = on => {
119  on('session.start', async ($, e, next) => {
120    const r = await next(e)
121    if (await readDisabled($)) return r
122    enabled = (await $.store.get(ENABLED_KEY).catch(() => undefined)) !== false
123    await $.command
124      .register({
125        name: 'merge-gate',
126        description: 'Deny Bash merges unless the latest message says merge (merge-gate)',
127        argumentHint: '[on | off | status]',
128        immediate: true,
129      })
130      .catch(err => $.ui.log(`merge-gate: /merge-gate not registered: ${err}`))
131    return r
132  })
133
134  on('command.run', { command: 'merge-gate' }, async ($, e) => {
135    const arg = e.args.trim().toLowerCase()
136    if (arg === 'on' || arg === 'off') {
137      enabled = arg === 'on'
138      await $.store.set(ENABLED_KEY, enabled).catch(err => $.ui.log(`merge-gate: store write failed: ${err}`))
139      return { text: `merge-gate ${arg}` }
140    }
141    if (arg === '' || arg === 'status') {
142      return { text: `merge-gate is ${enabled ? 'on' : 'off'}; latest message ${latest === undefined ? 'unknown' : saysMerge(latest) ? 'says merge' : 'does not say merge'}${grantUses ? `; ${grantUses} granted merge(s) left` : ''}` }
143    }
144    return { text: `merge-gate: "${arg}" is not on, off, or status` }
145  })
146
147  on('prompt.submit', ($, e, next) => {
148    if (disabled || !HUMAN_ORIGINS.includes(e.origin.kind)) return next(e)
149    latest = e.text
150    grantUses = grantOf(e.text) || grantUses
151    return next(e)
152  })
153
154  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
155    if (disabled || !enabled || !(await isMerge($, e.command))) return next(e)
156    const text = await latestHuman($)
157    const said = text !== undefined && saysMerge(text)
158    if (!said && grantUses === 0) return { deny: DENIED }
159    if (grantUses > 0) grantUses--
160    if (!said) $.ui.log(`merge-gate: allowed by a standing grant, ${grantUses} left`)
161    return next(e)
162  }).catch(($, e, next) => (next.called ? undefined : { deny: 'merge-gate check failed; blocking until it works. To get past it: /merge-gate off, or CLAUDE_MODS_DISABLE=merge-gate.' }))
163}
164