feb-guard

1import type { EngineInterface, Register } from 'claude-code'
2
3import { checkBash, checkVersionEdit, isHostingDeploy, versionFile, wantsNonHosting } from './rules'
4
5// Only this project's sessions are guarded.
6const SCOPE = '/composites_programs/'
7const APP_DIR = '06 Composites App'
8
9export const register: Register = on => {
10  // Set per prompt: Simon typing "allow rules deploy" lifts the hosting-only
11  // rule for the rest of that turn and no longer.
12  let nonHostingDeploy = false
13
14  on('prompt.submit', ($, e, next) => {
15    nonHostingDeploy = wantsNonHosting(e.text)
16    return next(e)
17  })
18
19  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
20    const cwd = await $.session.cwd()
21    if (!cwd.includes(SCOPE)) return next(e)
22
23    const reason = checkBash(e.command, { nonHostingDeploy })
24    if (reason) return refuse($, reason)
25
26    if (isHostingDeploy(e.command)) {
27      const unpushed = await unpushedState($, cwd)
28      if (unpushed) return refuse($, unpushed)
29    }
30
31    return next(e)
32  })
33
34  on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
35    if (!e.file_path.includes(SCOPE) || !versionFile(e.file_path)) return next(e)
36    const reason = checkVersionEdit(e.file_path, e.old_string, e.new_string)
37    return reason ? refuse($, reason) : next(e)
38  })
39
40  on('tool.call', { tool: 'Write' }, async ($, e, next) => {
41    if (!e.file_path.includes(SCOPE) || !versionFile(e.file_path)) return next(e)
42    const before = (await $.fs.exists(e.file_path)) ? await $.fs.read(e.file_path) : ''
43    const reason = checkVersionEdit(e.file_path, before, e.content)
44    return reason ? refuse($, reason) : next(e)
45  })
46}
47
48function refuse($: EngineInterface, reason: string) {
49  $.ui.toast('feb-guard blocked a command')
50  return { deny: `feb-guard: ${reason}` }
51}
52
53// "Deploy from a state that is pushed, so live always matches a commit."
54async function unpushedState($: EngineInterface, cwd: string): Promise<string | undefined> {
55  const top = await $.process.run(['git', 'rev-parse', '--show-toplevel'], { cwd })
56  if (top.exitCode !== 0) return undefined
57  const root = top.stdout.trim()
58
59  const dirty = await $.process.run(['git', 'status', '--porcelain', '--', APP_DIR], { cwd: root })
60  if (dirty.exitCode === 0 && dirty.stdout.trim()) {
61    return `${APP_DIR} has uncommitted changes, so what goes live would match no commit. Commit and push first, then deploy.\n${dirty.stdout.trim()}`
62  }
63
64  const ahead = await $.process.run(['git', 'rev-list', '--count', '@{u}..HEAD'], { cwd: root })
65  if (ahead.exitCode === 0 && Number(ahead.stdout.trim()) > 0) {
66    return `${ahead.stdout.trim()} commit(s) are not pushed yet. Push first, deploy second, so live always matches a commit on GitHub.`
67  }
68  return undefined
69}
70

1// Pure checks, no `$`, so the tests can drive them directly.
2// Each returns the reason to refuse, or undefined to let the command through.
3
4export type Overrides = { nonHostingDeploy: boolean }
5
6// Split a shell command into simple commands and those into words. Rough on
7// purpose: it handles quotes and the usual separators, not every corner of sh.
8export function segments(command: string): string[][] {
9  const out: string[][] = []
10  let words: string[] = []
11  let word = ''
12  let hasWord = false
13  let quote: '"' | "'" | null = null
14
15  const endWord = () => {
16    if (hasWord) words.push(word)
17    word = ''
18    hasWord = false
19  }
20  const endSegment = () => {
21    endWord()
22    if (words.length) out.push(words)
23    words = []
24  }
25
26  for (let i = 0; i < command.length; i++) {
27    const c = command[i]!
28    if (quote) {
29      if (c === quote) quote = null
30      else if (c === '\\' && quote === '"' && i + 1 < command.length) word += command[++i]!
31      else word += c
32      continue
33    }
34    if (c === '"' || c === "'") { quote = c; hasWord = true; continue }
35    if (c === '\\' && i + 1 < command.length) { word += command[++i]!; hasWord = true; continue }
36    if (c === ';' || c === '\n' || c === '|' || c === '&' || c === '(' || c === ')') { endSegment(); continue }
37    if (c === ' ' || c === '\t') { endWord(); continue }
38    word += c
39    hasWord = true
40  }
41  endSegment()
42  return out
43}
44
45// Drop leading env assignments and wrappers so `FOO=1 npx firebase deploy`
46// reads as `firebase deploy`.
47function strip(words: string[]): string[] {
48  let i = 0
49  while (i < words.length && (/^\w+=/.test(words[i]!) || ['npx', 'command', 'exec', 'time', 'sudo', 'env'].includes(words[i]!))) i++
50  return words.slice(i)
51}
52
53// `git -C dir push` and `git --no-pager tag` still count as push and tag.
54function gitSub(words: string[]): { sub: string; args: string[] } | undefined {
55  if (words[0] !== 'git') return undefined
56  let i = 1
57  while (i < words.length && words[i]!.startsWith('-')) {
58    if (words[i] === '-C' || words[i] === '-c') i++
59    i++
60  }
61  return i < words.length ? { sub: words[i]!, args: words.slice(i + 1) } : undefined
62}
63
64const HOW_RELEASE = 'Releases go through `node tools/release.mjs <version>` from the repo root (CLAUDE.md, "One version, one release").'
65
66export function checkFirebase(args: string[], o: Overrides): string | undefined {
67  if (args[0] !== 'deploy') return undefined
68  let only: string | undefined
69  for (let i = 1; i < args.length; i++) {
70    const a = args[i]!
71    if (a === '--only') only = args[i + 1]
72    else if (a.startsWith('--only=')) only = a.slice(7)
73  }
74  if (only === undefined) {
75    return 'A bare `firebase deploy` also ships firestore.rules, storage.rules and functions. The standing authorization covers `firebase deploy --only hosting` and nothing else.'
76  }
77  const targets = only.split(',').map(t => t.trim()).filter(Boolean)
78  const others = targets.filter(t => t !== 'hosting' && !t.startsWith('hosting:'))
79  if (others.length && !o.nonHostingDeploy) {
80    return `\`--only ${only}\` deploys ${others.join(', ')}. Rules can lock the team out of their own data and functions are deployed separately on purpose, so this needs Simon: ask him, and if he agrees he types "allow rules deploy" (or "allow functions deploy") in his next message.`
81  }
82  return undefined
83}
84
85export function checkGit(sub: string, args: string[]): string | undefined {
86  if (sub === 'tag' && args.some(a => a.startsWith('addin-v'))) {
87    return `There is no separate add-in version and no \`addin-v*\` tag. ${HOW_RELEASE}`
88  }
89
90  if (sub === 'remote' && (args[0] === 'add' || args[0] === 'set-url') && args.some(isSsh)) {
91    return 'Keep the remote on HTTPS. The SSH key on this machine authenticates as `starbuckgold`, but the repo belongs to `Jinxiewinx` (the gh account).'
92  }
93
94  if (sub !== 'push') return undefined
95  if (args.some(isSsh)) {
96    return 'Push over HTTPS. The SSH key on this machine authenticates as `starbuckgold`, not `Jinxiewinx`.'
97  }
98  if (args.some(a => a.includes('addin-v'))) {
99    return `There is no separate add-in version and no \`addin-v*\` tag. ${HOW_RELEASE}`
100  }
101
102  const flagForce = args.some(a => a === '-f' || a === '--force' || a.startsWith('--force-with-lease') || a.startsWith('--force-if-includes') || (/^-[a-zA-Z]+$/.test(a) && a.includes('f')))
103  const positional = args.filter(a => !a.startsWith('-'))
104  const refspecs = positional.slice(1)
105  const plusForce = refspecs.some(r => r.startsWith('+'))
106  if (!flagForce && !plusForce) return undefined
107
108  const dst = (r: string) => {
109    const s = r.replace(/^\+/, '')
110    const d = s.includes(':') ? s.split(':')[1] : s
111    return (d ?? '').replace(/^refs\/heads\//, '')
112  }
113  const hitsMain = refspecs.length === 0 || refspecs.some(r => ['main', 'master', 'HEAD'].includes(dst(r)))
114  if (hitsMain || args.includes('--all') || args.includes('--mirror')) {
115    return 'No force-push over real history on main (SN6 Resources/CLAUDE.md). If history really needs rewriting, that is a call for Simon to make and run himself.'
116  }
117  return undefined
118}
119
120function isSsh(a: string): boolean {
121  return /^git@github\.com:/.test(a) || /^ssh:\/\//.test(a)
122}
123
124const VERSION_TOKENS = /ADDIN_VERSION|APP_VERSION|FEBPlanStock\.manifest/
125
126function checkInPlaceEdit(words: string[]): string | undefined {
127  const tool = words[0]
128  const inPlace = (tool === 'sed' && words.some(w => /^-[a-zA-Z]*i/.test(w) || w === '--in-place' || w.startsWith('--in-place=')))
129    || (tool === 'perl' && words.some(w => /^-[a-zA-Z]*i/.test(w)))
130  if (inPlace && words.some(w => VERSION_TOKENS.test(w))) {
131    return `Version strings are written only by the release script, which keeps APP_VERSION, the add-in manifest and ADDIN_VERSION in step. ${HOW_RELEASE}`
132  }
133  return undefined
134}
135
136export function checkBash(command: string, o: Overrides): string | undefined {
137  for (const raw of segments(command)) {
138    const words = strip(raw)
139    if (!words.length) continue
140    let reason: string | undefined
141    if (words[0] === 'firebase') reason = checkFirebase(words.slice(1), o)
142    else if (words[0] === 'gh' && words[1] === 'release' && ['create', 'upload', 'delete', 'edit'].includes(words[2] ?? '')) {
143      reason = `\`gh release ${words[2]}\` by hand is off: the release script publishes the Release with the add-in zip attached. ${HOW_RELEASE}`
144    } else {
145      const git = gitSub(words)
146      if (git) reason = checkGit(git.sub, git.args)
147      else reason = checkInPlaceEdit(words)
148    }
149    if (reason) return reason
150  }
151  return undefined
152}
153
154// True when the command is a hosting deploy that should then be checked for a
155// pushed tree. Separate from checkBash because that check needs git.
156export function isHostingDeploy(command: string): boolean {
157  return segments(command).some(raw => {
158    const w = strip(raw)
159    if (w[0] !== 'firebase' || w[1] !== 'deploy') return false
160    const i = w.findIndex(a => a === '--only' || a.startsWith('--only='))
161    if (i < 0) return false
162    const flag = w[i]!
163    const only = flag.startsWith('--only=') ? flag.slice(7) : w[i + 1] ?? ''
164    return only.split(',').some(t => t === 'hosting' || t.startsWith('hosting:'))
165  })
166}
167
168// Edit/Write on the three files that carry the version. Returns the reason
169// when the change touches a version line.
170export const VERSION_FILES: { suffix: string; line: RegExp }[] = [
171  { suffix: '06 Composites App/app/core.js', line: /\bAPP_VERSION\s*=\s*["'][^"']*["']/ },
172  { suffix: 'FEBPlanStock/FEBPlanStock.manifest', line: /"version"\s*:\s*"[^"]*"/ },
173  { suffix: 'FEBPlanStock/FEBPlanStock.py', line: /\bADDIN_VERSION\s*=\s*["'][^"']*["']/ },
174]
175
176export function versionFile(path: string) {
177  return VERSION_FILES.find(f => path.endsWith(f.suffix))
178}
179
180export function versionOf(text: string, line: RegExp): string | undefined {
181  return text.match(line)?.[0]
182}
183
184export function checkVersionEdit(path: string, before: string, after: string): string | undefined {
185  const f = versionFile(path)
186  if (!f) return undefined
187  if (versionOf(before, f.line) !== versionOf(after, f.line)) {
188    return `This changes the version line in ${f.suffix}. ${HOW_RELEASE} tools/test_addin_package.mjs fails when the three version strings drift.`
189  }
190  return undefined
191}
192
193export function wantsNonHosting(prompt: string): boolean {
194  return /\ballow (rules|firestore|storage|functions) deploy\b/i.test(prompt)
195}
196