claude-bulkhead 0.2.2 → 0.3.0

package/src/allow-once.js

@@ -0,0 +1,152 @@
+'use strict'
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const { stateDir } = require('./hook')
+
+// Allow once: a block gets a short code; the user runs `bulkhead allow <code>` in their own
+// terminal, and the next identical tool call (same command text, same folder) passes the guard
+// that blocked it. One JSON file per (code, guard, rule) in <state dir>/allow, so two guards
+// blocking the same command in parallel never overwrite each other's write.
+
+const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789' // base32 without I, O, 0, 1
+const CODE_LENGTH = 5
+const DEFAULT_TTL_MINUTES = 10
+
+const dirOf = (base = stateDir()) => path.join(base, 'allow')
+
+function ttlMs(minutes) {
+  let m = minutes
+  if (m === undefined) {
+    try { m = require('./config').get('allowOnce.ttlMinutes') } catch {}
+  }
+  return (Number.isFinite(m) && m > 0 ? m : DEFAULT_TTL_MINUTES) * 60000
+}
+
+const normalizeCommand = command => String(command || '').replace(/\r\n/g, '\n').trim()
+const normalizeCwd = cwd => {
+  const s = String(cwd || '').replace(/\\/g, '/').replace(/\/+$/, '')
+  return process.platform === 'win32' ? s.toLowerCase() : s
+}
+
+// The identity of a tool call as far as allowing it goes: the command text and the folder.
+function commandKey(command, cwd) {
+  return crypto.createHash('sha256').update(`${normalizeCommand(command)}\0${normalizeCwd(cwd)}`).digest('hex')
+}
+
+function newCode(taken = new Set()) {
+  for (;;) {
+    const bytes = crypto.randomBytes(CODE_LENGTH)
+    let code = ''
+    for (const b of bytes) code += ALPHABET[b % 32]
+    if (!taken.has(code)) return code
+  }
+}
+
+const cleanCode = s => String(s || '').toUpperCase().replace(/[^A-Z0-9]/g, '')
+
+function writeAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(3).toString('hex')}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(data))
+  try {
+    fs.renameSync(tmp, file)
+  } catch (e) {
+    try { fs.unlinkSync(tmp) } catch {}
+    throw e
+  }
+}
+
+const valid = e => e && typeof e === 'object' && typeof e.code === 'string' && typeof e.guard === 'string' &&
+  typeof e.rule === 'string' && typeof e.key === 'string' && Number.isFinite(e.expires) && Number.isFinite(e.created)
+
+// Every readable entry as { file, entry }. Expired and unreadable files are deleted on the way.
+function readAll(base, now) {
+  const dir = dirOf(base)
+  let names
+  try { names = fs.readdirSync(dir) } catch { return [] }
+  const out = []
+  for (const name of names) {
+    const file = path.join(dir, name)
+    if (!name.endsWith('.json')) {
+      // a temp file left by a crash
+      try { if (now - fs.statSync(file).mtimeMs > 60000) fs.unlinkSync(file) } catch {}
+      continue
+    }
+    let entry = null
+    try { entry = JSON.parse(fs.readFileSync(file, 'utf8')) } catch {}
+    if (!valid(entry) || entry.expires <= now) {
+      try { fs.unlinkSync(file) } catch {}
+      continue
+    }
+    out.push({ file, entry })
+  }
+  return out
+}
+
+const safe = s => String(s).replace(/[^\w.-]/g, '_')
+
+// The code a block shows. A second guard blocking the same command in the same minute reuses
+// the code of the first, so the person types one code. Returns null when nothing can be stored.
+function issue({ guard, rule, command, cwd, session }, { base, now = Date.now(), ttl } = {}) {
+  try {
+    const key = commandKey(command, cwd)
+    const all = readAll(base, now)
+    const same = all.find(x => x.entry.key === key && !x.entry.approved)
+    const code = same ? same.entry.code : newCode(new Set(all.map(x => x.entry.code)))
+    const dir = dirOf(base)
+    fs.mkdirSync(dir, { recursive: true })
+    const entry = {
+      code, guard, rule, key, cmd: normalizeCommand(command).replace(/\s+/g, ' ').slice(0, 160),
+      cwd: cwd || '', session: session || null, created: now, expires: now + ttlMs(ttl), approved: null,
+    }
+    writeAtomic(path.join(dir, `${code}-${safe(guard)}-${safe(rule)}.json`), entry)
+    return code
+  } catch {
+    return null
+  }
+}
+
+// Marks every pending entry of that command as allowed once. { ok, entries } or { ok: false, reason }.
+function approve(input, { base, now = Date.now(), ttl } = {}) {
+  const code = cleanCode(input)
+  if (!code) return { ok: false, reason: 'no-code' }
+  let all
+  try { all = readAll(base, now) } catch { return { ok: false, reason: 'unreadable' } }
+  const hit = all.find(x => x.entry.code === code)
+  if (!hit) return { ok: false, reason: 'unknown' }
+  if (hit.entry.approved) return { ok: false, reason: 'used', entries: [hit.entry] }
+  const approved = []
+  for (const x of all) {
+    if (x.entry.key !== hit.entry.key || x.entry.approved) continue
+    const e = { ...x.entry, approved: now, expires: now + ttlMs(ttl) }
+    try { writeAtomic(x.file, e) } catch { return { ok: false, reason: 'unwritable' } }
+    approved.push(e)
+  }
+  return { ok: true, entries: approved }
+}
+
+// Called by a guard that is about to block. True when the user approved this exact command for
+// this guard and rule; the approval is deleted, so it works once. Any trouble means false.
+function consume(guard, rule, command, cwd, { base, now = Date.now() } = {}) {
+  try {
+    const key = commandKey(command, cwd)
+    for (const x of readAll(base, now)) {
+      const e = x.entry
+      if (!e.approved || e.key !== key || e.guard !== guard || e.rule !== rule) continue
+      try { fs.unlinkSync(x.file) } catch { continue } // somebody else used it first
+      return true
+    }
+  } catch {}
+  return false
+}
+
+// Pending and approved entries, newest first, for `bulkhead allow --list`.
+function list({ base, now = Date.now() } = {}) {
+  try {
+    return readAll(base, now).map(x => x.entry).sort((a, b) => b.created - a.created)
+  } catch {
+    return []
+  }
+}
+
+module.exports = { issue, approve, consume, list, commandKey, normalizeCommand, newCode, dirOf, ttlMs, ALPHABET, DEFAULT_TTL_MINUTES }

package/src/auto-queue.js

@@ -0,0 +1,93 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const shell = require('./shell')
+
+// Rewrites a heavy command so it runs through bulkhead-slot, which queues it against the
+// machine-wide RAM budget. Pure functions: the hook (memory-guard.js) supplies the settings.
+
+// Typical peak RAM per tool, in GB. memoryGuard.estimatesGb overrides single entries.
+const ESTIMATES_GB = {
+  vitest: 3, jest: 3, karma: 2, playwright: 4, cypress: 4, gradle: 4, gradlew: 4, mvn: 3, mvnw: 3,
+  dotnet: 2, next: 3, vite: 2, tsc: 2, webpack: 3, ffmpeg: 2, cargo: 4, go: 3, pytest: 3,
+  docker: 3, 'docker-compose': 3, bazel: 6, turbo: 4, nx: 4, xcodebuild: 6, swift: 4, fastlane: 4,
+  npm: 3, pnpm: 3, yarn: 3, bun: 3, browser: 3,
+}
+const DEFAULT_GB = 3
+
+function estimateGb(name, overrides) {
+  const n = overrides && overrides[name]
+  if (typeof n === 'number' && n > 0 && n <= 256) return n
+  return ESTIMATES_GB[name] || DEFAULT_GB
+}
+
+// A short name for bulkhead status: "npm test", "cargo build". Only characters that need no
+// quoting inside the label, so a command's own quotes never reach the wrapper.
+function labelFor(argv) {
+  const sub = argv.slice(1).find(a => !a.startsWith('-')) || ''
+  const raw = `${shell.bin(argv[0])} ${sub}`.trim().slice(0, 40)
+  return raw.replace(/[^\w .:/@=+-]/g, '_')
+}
+
+// One word for each shell. bash: single quotes, a quote inside becomes '\''. PowerShell: single
+// quotes, a quote inside is doubled. cmd: double quotes, a quote inside is doubled.
+const SAFE = /^[\w@%+=:,./-]+$/
+const SAFE_WIN = /^[\w@%+=:,./\\-]+$/
+const quoters = {
+  sh: a => (SAFE.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`),
+  ps: a => (SAFE_WIN.test(a) ? a : `'${a.replace(/'/g, "''")}'`),
+  cmd: a => (SAFE_WIN.test(a) ? a : `"${a.replace(/"/g, '""')}"`),
+}
+
+function which(name, env = process.env, exists = fs.existsSync, platform = process.platform) {
+  const dirs = String(env.PATH || env.Path || '').split(platform === 'win32' ? ';' : ':').filter(Boolean)
+  const file = platform === 'win32' ? `${name}.exe` : name
+  return dirs.some(d => exists(path.join(d, file))) ? name : null
+}
+
+// The slot script of this package, from the plugin root when Claude Code sets it. null when the
+// file is missing: the caller then leaves the command alone.
+function slotScript({ env = process.env, exists = fs.existsSync, dir = __dirname } = {}) {
+  const roots = [env.CLAUDE_PLUGIN_ROOT, path.join(dir, '..')].filter(Boolean)
+  for (const r of roots) {
+    const f = path.join(r, 'bin', 'bulkhead-slot')
+    if (exists(f)) return f
+  }
+  return null
+}
+
+// The command text with `-- <command>` handed to bulkhead-slot, or null when this shell cannot
+// carry it (a newline in a cmd line is a second command). The original runs in the same kind
+// of shell as before: bash -c for the Bash tool, an encoded script for PowerShell.
+function wrap(command, { shell: sh = 'sh', node = process.execPath, script, gb, label, wait, env = process.env, exists, platform } = {}) {
+  const q = quoters[sh]
+  if (!q || !script) return null
+  const head = [node, script].map(q)
+  const opts = ['run', `--gb=${gb}`, q(`--label=${label}`)]
+  if (wait) opts.push(`--wait=${wait}`)
+  let tail
+  if (sh === 'sh') tail = `bash -c ${q(command)}`
+  else if (sh === 'ps') {
+    const exe = which('pwsh', env, exists, platform) || 'powershell'
+    tail = `${exe} -NoProfile -EncodedCommand ${Buffer.from(command, 'utf16le').toString('base64')}`
+  } else {
+    if (/[\r\n]/.test(command)) return null
+    tail = q(command)
+  }
+  return `${sh === 'ps' ? '& ' : ''}${head.join(' ')} ${opts.join(' ')} -- ${tail}`
+}
+
+// A single & backgrounds a command, so the slot would be released at once and hold nothing.
+function backgrounded(command, mode = 'sh') {
+  const text = String(command)
+  if (mode === 'ps') return /\bStart-(?:Job|Process)\b|\bsaps\b/i.test(text)
+  const bare = text.replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, ' ').replace(/&&|\d?>&\d?|&>>?|\|&/g, ' ')
+  return bare.includes('&') || /\b(?:nohup|setsid|disown)\b/.test(bare)
+}
+
+// Already queued, or this is the wrapper we wrote.
+function wrapped(command) {
+  return /bulkhead(?:-|\s+)slot/.test(String(command))
+}
+
+module.exports = { ESTIMATES_GB, estimateGb, labelFor, wrap, slotScript, backgrounded, wrapped, quoters, which }

package/src/bash-guards.js

@@ -0,0 +1,36 @@
+'use strict'
+const { runHook, enabled } = require('./hook')
+
+// Every Bash and PowerShell guard in one process. Seven separate hooks meant seven Node starts
+// per tool call, which adds up when ten sessions share a machine. The guards run in order of
+// cost, text-only checks first and the ones that read git, memory, processes or ports last, and
+// the first block stops the rest. A guard that throws is skipped, so one bug never silences the
+// others; the whole hook still fails open on anything unexpected.
+const ORDER = [
+  ['secrets-guard', './secrets-guard'],
+  ['wait-guard', './wait-guard'],
+  ['disk-guard', './disk-guard'],
+  ['kill-guard', './kill-guard'],
+  ['basics', './basics'],
+  ['checkout-guard', './checkout-guard'],
+  ['memory-guard', './memory-guard'],
+  ['port-guard', './port-guard'],
+]
+
+// { block } from the first guard that blocks, else the first non-blocking output (memory-guard's
+// queued rewrite), else nothing. `rewrite: false` drops rewrites for callers that cannot use them.
+async function judge(input, { rewrite = true, order = ORDER } = {}) {
+  let output = null
+  for (const [name, file] of order) {
+    if (!enabled(name)) continue
+    let result = null
+    try { result = await (typeof file === 'string' ? require(file) : file).handle(input) } catch {}
+    if (result && result.block) return { block: result.block }
+    if (rewrite && result && result.output && !output) output = result.output
+  }
+  return output ? { output } : null
+}
+
+if (require.main === module) runHook('bash-guards', input => judge(input))
+
+module.exports = { judge, ORDER }

package/src/basics.js

@@ -5,9 +5,10 @@ const { execFileSync } = require('child_process')
 const { runHook, enabled, setting, blocked, oneLine, ASK_USER } = require('./hook')
 const shell = require('./shell')
 const { realPath } = require('./paths')
+const { gitCall, gitEnv, parseArgs } = require('./gitargs')
 
 // Narrow rules for mistakes that cannot be undone. Each can be turned off on its own:
-// rm-root, force-push-main, discard-changes, agent-author.
+// rm-root, force-push-main, discard-changes, agent-author, self-allow.
 
 // ~, $HOME and %USERPROFILE% become the home directory; /c/... becomes C:/... on Windows.
 // Returns null for anything with a variable we cannot expand.
@@ -94,20 +95,6 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
 }
 
-function gitCwd(t, cwd) {
-  const i = t.indexOf('-C')
-  return i > 0 && t[i + 1] ? path.resolve(cwd, t[i + 1]) : cwd
-}
-
-function gitSub(t) {
-  const rest = []
-  for (let i = 1; i < t.length; i++) {
-    if (t[i] === '-C' || t[i] === '-c') i++
-    else rest.push(t[i])
-  }
-  return rest
-}
-
 function forcePushToMain(rest, branch, protectedBranches = ['main', 'master']) {
   if (rest[0] !== 'push') return false
   const args = rest.slice(1)
@@ -119,6 +106,26 @@ function forcePushToMain(rest, branch, protectedBranches = ['main', 'master']) {
   return targets.some(r => protectedBranches.includes(String(r || '').replace(/^refs\/heads\//, '')))
 }
 
+// git push origin :main, git push --delete origin main, git push -d origin main, and
+// git branch -D main (or -d -f, --delete --force): removing a protected branch. A plain
+// git branch -d refuses unmerged work and is left alone.
+function deletesProtected(rest, protectedBranches = ['main', 'master']) {
+  const name = r => String(r || '').replace(/^\+/, '').replace(/^refs\/heads\//, '')
+  const isProtected = r => protectedBranches.includes(name(r))
+  if (rest[0] === 'push') {
+    const o = parseArgs(rest.slice(1), { valuedShort: 'o', valuedLong: ['repo', 'push-option', 'receive-pack', 'exec'] })
+    const del = o.short.has('d') || [...o.long].some(n => n.length >= 3 && 'delete'.startsWith(n))
+    return o.pos.slice(1).map(r => r.replace(/^\+/, '')).some(r => (r.startsWith(':') ? isProtected(r.slice(1)) : del && isProtected(r)))
+  }
+  if (rest[0] === 'branch') {
+    const o = parseArgs(rest.slice(1), { valuedShort: 'uts', valuedLong: ['set-upstream-to', 'track', 'sort', 'format', 'contains', 'merged', 'no-merged', 'points-at'] })
+    const del = o.short.has('D') || o.short.has('d') || o.long.has('delete')
+    const force = o.short.has('D') || o.short.has('f') || o.long.has('force')
+    return del && force && o.pos.some(isProtected)
+  }
+  return false
+}
+
 // An identity that is the agent, not the person: Claude <noreply@anthropic.com> and the like.
 const AGENT_ID = /\bclaude\b|anthropic/i
 
@@ -164,7 +171,12 @@ function check(cmd, {
   const rmRoot = once(() => enabled('rm-root'))
   const forcePush = once(() => enabled('force-push-main'))
   const discard = once(() => enabled('discard-changes'))
+  const protectedDelete = once(() => enabled('protected-delete'))
   const author = once(() => enabled('agent-author'))
+  if (/allow/i.test(String(cmd || '')) && enabled('self-allow')) {
+    const self = require('./self-allow').check(cmd, { mode })
+    if (self) return self
+  }
   const prepared = shell.prepare(String(cmd || ''), mode)
   const cmds = shell.commands(prepared, mode).filter(x => !x.remote)
   if (author() && /GIT_(?:AUTHOR|COMMITTER)_/i.test(prepared)) {
@@ -192,45 +204,52 @@ function check(cmd, {
       }
     }
     if (path.basename(t[0]).replace(/\.exe$/i, '') !== 'git') continue
-    const dir = gitCwd(t, cwd)
-    const rest = gitSub(t)
+    const call = gitCall(t, cwd, c.depth === 0 ? gitEnv(prepared.slice(c.s, c.e)) : {})
+    const dir = call.dir
+    const rest = call.sub ? [call.sub, ...call.args] : []
     const who = author() && agentAuthor(t, rest)
     if (who) return agentMessage(who)
     if (rest[0] === 'push' && forcePush() && forcePushToMain(rest, () => { try { return run(['rev-parse', '--abbrev-ref', 'HEAD'], dir) } catch { return '' } }, protectedBranches)) {
       return `[bulkhead] basics: force-pushing to ${protectedBranches.join(' or ')} rewrites history other people and sessions have pulled.\n` +
         'Push to a branch, or use --force-with-lease if you are sure.'
     }
+    if (rest[0] && protectedDelete() && deletesProtected(rest, protectedBranches)) {
+      return `[bulkhead] basics: \`${oneLine(seg, 120)}\` deletes the protected branch (${protectedBranches.join(', ')}), and the work on it goes with it.\n` +
+        'Delete a feature branch instead, or turn the rule off for this project if you really mean it.'
+    }
     const reset = rest[0] === 'reset' && rest.includes('--hard')
     const clean = rest[0] === 'clean' && rest.some(a => /^-[a-z]*f/.test(a) || a === '--force') && rest.some(a => /^-[a-z]*[dx]/.test(a))
     if ((reset || clean) && discard()) {
       let status
-      try { status = run(['status', '--porcelain'], dir) } catch { continue }
+      try { status = run([...call.opts, 'status', '--porcelain'], dir) } catch { continue }
       const lines = status.split('\n').filter(Boolean)
       const lost = reset ? lines.filter(l => !l.startsWith('??')) : lines.filter(l => l.startsWith('??'))
       if (lost.length) {
         return `[bulkhead] basics: \`${oneLine(seg, 120)}\` would throw away ${lost.length} ${reset ? 'uncommitted change' : 'untracked file'}${lost.length === 1 ? '' : 's'}` +
           ` (${lost.slice(0, 3).map(l => l.slice(3)).join(', ')}${lost.length > 3 ? ', ...' : ''}).\n` +
-          'Commit them or run `git stash push -u` first, so they can be brought back.'
+          'Commit them, or move the files somewhere else, first. `git clean -n` and `git status` show what would go.'
       }
     }
   }
   return null
 }
 
-if (require.main === module) {
-  runHook('basics', input => {
-    const cmd = input.tool_input && input.tool_input.command
-    const why = typeof cmd === 'string' && cmd && check(cmd, { cwd: input.cwd || process.cwd(), mode: shell.modeFor(input) })
-    if (!why) return
-    return blocked('basics', ruleOf(why), input, `${why}\n${ASK_USER}`)
-  })
+function handle(input) {
+  const cmd = input.tool_input && input.tool_input.command
+  const why = typeof cmd === 'string' && cmd && check(cmd, { cwd: input.cwd || process.cwd(), mode: shell.modeFor(input) })
+  if (!why) return
+  return blocked('basics', ruleOf(why), input, ruleOf(why) === 'self-allow' ? why : `${why}\n${ASK_USER}`)
 }
 
+if (require.main === module) runHook('basics', handle)
+
 function ruleOf(message) {
+  if (/cannot approve its own blocks/.test(message)) return 'self-allow'
   if (/makes the agent the author/.test(message)) return 'agent-author'
   if (/force-pushing/.test(message)) return 'force-push-main'
+  if (/deletes the protected branch/.test(message)) return 'protected-delete'
   if (/would throw away/.test(message)) return 'discard-changes'
   return 'rm-root'
 }
 
-module.exports = { check, rmTargets, dangerousTarget, forcePushToMain, ruleOf, agentAuthor }
+module.exports = { handle, check, rmTargets, dangerousTarget, forcePushToMain, deletesProtected, ruleOf, agentAuthor }