jackherd 0.0.1 → 1.0.1

package/kit/hooks/hooks/git-guard/decision.ts

@@ -0,0 +1,438 @@
+import { posix } from 'node:path'
+import { parseShell, ShellParseError, type SimpleCommand, type Word } from './shell'
+
+export type GitGuardDecision = { kind: 'pass' } | { kind: 'deny'; reason: string }
+
+/** The git verbs a project guards with permission rules: each one changes a ref or the working tree. */
+const PROTECTED_VERB = {
+  push: 'push',
+  commit: 'commit',
+  rebase: 'rebase',
+  reset: 'reset',
+  checkout: 'checkout',
+  merge: 'merge',
+} as const
+
+type ProtectedVerb = (typeof PROTECTED_VERB)[keyof typeof PROTECTED_VERB]
+
+/** Where a script runs: at the top, where permission rules look, or inside `sh -c`/`eval`, where none does. */
+const SCRIPT_CONTEXT = { top: 'top', nested: 'nested' } as const
+
+type ScriptContext = (typeof SCRIPT_CONTEXT)[keyof typeof SCRIPT_CONTEXT]
+
+/**
+ * Where a `git` word stands: written plainly where a permission rule compares (`ruleMatched`), run
+ * as the program in a form no rule matches (`program`), or a mere argument (`grep git file`).
+ */
+const GIT_POSITION = { ruleMatched: 'ruleMatched', program: 'program', argument: 'argument' } as const
+
+type GitPosition = (typeof GIT_POSITION)[keyof typeof GIT_POSITION]
+
+type GitInvocation = {
+  assignments: string[]
+  options: Word[]
+  directories: string[]
+  verb: Word
+  verbArguments: Word[]
+}
+
+/** A dangerous use of a verb: a long option (or a git-accepted prefix of it), a short letter, an operand. */
+type DangerRule = {
+  long: string[]
+  short?: string
+  operand?: (operand: string) => boolean
+  message: string
+}
+
+/**
+ * How a verb's options take values: a letter in `shortWithValue` takes the rest of its cluster, or
+ * the next word when it ends the cluster and is also in `shortSeparate`; a long option in
+ * `longWithValue` takes the next word unless it carries `=`.
+ */
+type VerbSyntax = { shortWithValue: string; shortSeparate: string; longWithValue: string[] }
+
+type SplitArguments = { options: string[]; operands: string[] }
+
+const PASS: GitGuardDecision = { kind: 'pass' }
+
+const FORCE_PUSH =
+  'A force push is refused. Use `--force-with-lease` instead, and only after the user agreed to rewrite the remote branch.'
+const SKIP_HOOKS =
+  'Skipping the git hooks (`--no-verify`, `HUSKY=0` and the like) is refused. Fix what the hook reports instead.'
+const HARD_RESET = '`git reset --hard` is refused: it discards uncommitted work. Ask the user how to proceed.'
+const VERB_HINT =
+  'Refused: the git verb is quoted, escaped or expanded, so neither the permission rules nor this hook can tell what it is. Write the verb plainly.'
+const PROGRAM_HINT =
+  'Refused: the program is expanded from a variable or a substitution and is followed by a protected git verb, so the permission rules cannot see it. Write `git` plainly.'
+const BRACE_HINT =
+  'Refused: an option of this git call is written as a brace expansion, so neither the permission rules nor this hook can tell what git receives. Write the option plainly.'
+const ALIAS_HINT =
+  'Refused: `-c alias.…` defines a git alias inline, which hides the verb from the permission rules. Run the git command it stands for directly.'
+
+const DANGER_RULES: Record<ProtectedVerb, DangerRule[]> = {
+  push: [
+    { long: ['--force', '--mirror'], short: 'f', operand: (operand) => operand.startsWith('+'), message: FORCE_PUSH },
+    { long: ['--no-verify'], message: SKIP_HOOKS },
+  ],
+  commit: [{ long: ['--no-verify'], short: 'n', message: SKIP_HOOKS }],
+  rebase: [{ long: ['--no-verify'], message: SKIP_HOOKS }],
+  merge: [{ long: ['--no-verify'], message: SKIP_HOOKS }],
+  reset: [{ long: ['--hard'], message: HARD_RESET }],
+  checkout: [],
+}
+
+const VERB_SYNTAX: Record<ProtectedVerb, VerbSyntax> = {
+  push: {
+    shortWithValue: 'o',
+    shortSeparate: 'o',
+    longWithValue: ['--push-option', '--repo', '--receive-pack', '--exec'],
+  },
+  commit: {
+    shortWithValue: 'mFCctuS',
+    shortSeparate: 'mFCct',
+    longWithValue: [
+      '--message',
+      '--file',
+      '--author',
+      '--date',
+      '--template',
+      '--reuse-message',
+      '--reedit-message',
+      '--fixup',
+      '--squash',
+      '--trailer',
+      '--cleanup',
+      '--pathspec-from-file',
+    ],
+  },
+  rebase: {
+    shortWithValue: 'sxX',
+    shortSeparate: 'sxX',
+    longWithValue: ['--onto', '--strategy', '--strategy-option', '--exec'],
+  },
+  merge: {
+    shortWithValue: 'mFsX',
+    shortSeparate: 'mFsX',
+    longWithValue: ['--message', '--file', '--strategy', '--strategy-option'],
+  },
+  reset: { shortWithValue: '', shortSeparate: '', longWithValue: ['--pathspec-from-file'] },
+  checkout: { shortWithValue: 'bB', shortSeparate: 'bB', longWithValue: ['--orphan', '--pathspec-from-file'] },
+}
+
+/** Global git options that take the next word as their value. */
+const OPTIONS_WITH_VALUE = new Set([
+  '-C',
+  '-c',
+  '--git-dir',
+  '--work-tree',
+  '--namespace',
+  '--super-prefix',
+  '--config-env',
+  '--attr-source',
+])
+const CONFIG_OPTIONS = new Set(['-c', '--config-env'])
+const CONFIG_ENV_ATTACHED = '--config-env='
+
+/**
+ * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
+ * permission matching also reaches into control-flow bodies, which the reserved words open.
+ */
+const RULE_TRANSPARENT_WRAPPERS = new Set(['time', 'nohup', 'nice', 'command', 'builtin', 'noglob'])
+const RESERVED_WORDS = new Set(['!', '{', '}', 'if', 'then', 'elif', 'else', 'fi', 'do', 'done', 'while', 'until'])
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/
+const DURATION = /^\d+(\.\d+)?[smhd]?$/
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish'])
+const SHELL_COMMAND_FLAG = /^-[a-z]*c[a-z]*$/
+const INLINE_ALIAS = /^alias\./i
+/** Variables that make git or its hook manager skip the hooks. */
+const HOOK_SKIPPING_VARIABLE = /^(HUSKY|LEFTHOOK|SKIP)\+?=/
+/** Variables that point git at other config, another repository or another work tree, like options do. */
+const REDIRECTING_VARIABLE = /^(GIT_CONFIG\w*|GIT_DIR|GIT_WORK_TREE|GIT_INDEX_FILE)\+?=/
+/** An option the shell rewrites before git sees it: `--forc{e,}` reaches git as `--force`. */
+const BRACE_IN_OPTION = /^-.*\{.*(,|\.\.).*\}/
+/** Programs that run their arguments as a command, so a `git` right after them is the program. */
+const COMMAND_RUNNERS = new Set([
+  ...RULE_TRANSPARENT_WRAPPERS,
+  'env',
+  'sudo',
+  'doas',
+  'exec',
+  'xargs',
+  'timeout',
+  'stdbuf',
+  'setsid',
+  'watch',
+])
+const PROTECTED_MENTION = new RegExp(`\\bgit\\b[\\s\\S]*\\b(${Object.values(PROTECTED_VERB).join('|')})\\b`)
+
+const isProtectedVerb = (value: string): value is ProtectedVerb =>
+  (Object.values(PROTECTED_VERB) as string[]).includes(value)
+
+const deny = (reason: string): GitGuardDecision => ({ kind: 'deny', reason })
+
+const transparentWidth = (words: SimpleCommand, index: number): number => {
+  const { value, literal } = words[index]
+  if (ASSIGNMENT.test(value)) return 1
+  if (!literal) return 0
+  if (RESERVED_WORDS.has(value) || RULE_TRANSPARENT_WRAPPERS.has(value)) return 1
+  return value === 'timeout' && DURATION.test(words[index + 1]?.value ?? '') ? 2 : 0
+}
+
+/** The index of the word a permission rule compares against: past assignments and stripped wrappers. */
+const ruleStart = (words: SimpleCommand): number => {
+  let index = 0
+  while (index < words.length) {
+    const width = transparentWidth(words, index)
+    if (width === 0) break
+    index += width
+  }
+  return index
+}
+
+/** The program a word names, as a case-insensitive file system would find it. */
+const programName = (word: Word): string =>
+  posix
+    .basename(word.value.replace(/^=/, ''))
+    .toLowerCase()
+    .replace(/\.exe$/, '')
+
+const isGit = (word: Word): boolean => programName(word) === 'git'
+
+/** At the rule start, or anywhere after a runner such as `sudo -u me` or `env FOO=1`: git runs as the program. */
+const isProgramPosition = (words: SimpleCommand, index: number): boolean =>
+  index === ruleStart(words) || words.slice(0, index).some((word) => COMMAND_RUNNERS.has(programName(word)))
+
+const gitPosition = (words: SimpleCommand, index: number, context: ScriptContext): GitPosition => {
+  const word = words[index]
+  const plain = context === SCRIPT_CONTEXT.top && index === ruleStart(words) && word.literal && word.value === 'git'
+  if (plain) return GIT_POSITION.ruleMatched
+  return isProgramPosition(words, index) ? GIT_POSITION.program : GIT_POSITION.argument
+}
+
+const isOption = (word: Word | undefined): boolean => word?.value.startsWith('-') ?? false
+
+const readInvocation = (words: SimpleCommand, gitIndex: number): GitInvocation | undefined => {
+  const options: Word[] = []
+  const directories: string[] = []
+  let index = gitIndex + 1
+  while (isOption(words[index])) {
+    const option = words[index]
+    const value = OPTIONS_WITH_VALUE.has(option.value) ? words[index + 1] : undefined
+    options.push(option, ...(value ? [value] : []))
+    if (option.value === '-C' && value) directories.push(value.value)
+    index += value ? 2 : 1
+  }
+  const verb = words[index]
+  if (!verb) return undefined
+  const assignments = words
+    .slice(0, gitIndex)
+    .map(({ value }) => value)
+    .filter((value) => ASSIGNMENT.test(value))
+  return { assignments, options, directories, verb, verbArguments: words.slice(index + 1) }
+}
+
+/** `--for` counts as `--force`: git accepts any unambiguous prefix of a long option. */
+const matchesLong = (word: string, name: string): boolean => {
+  const flag = word.split('=')[0]
+  return flag.startsWith('--') && flag.length >= 3 && name.startsWith(flag)
+}
+
+/** The cluster's letters up to and including the first one that takes a value. */
+const clusterLetters = (word: string, { shortWithValue }: VerbSyntax): string => {
+  const letters = word.slice(1)
+  const valueAt = [...letters].findIndex((letter) => shortWithValue.includes(letter))
+  return valueAt === -1 ? letters : letters.slice(0, valueAt + 1)
+}
+
+const isShortCluster = (word: string): boolean => /^-[^-]/.test(word)
+
+const takesNextWord = (word: string, syntax: VerbSyntax): boolean => {
+  if (isShortCluster(word)) {
+    const letters = clusterLetters(word, syntax)
+    return letters === word.slice(1) && syntax.shortSeparate.includes(letters.at(-1) ?? '')
+  }
+  return syntax.longWithValue.includes(word)
+}
+
+/** Options and operands after the verb; option values are neither, and `--` ends the options. */
+const splitArguments = (words: Word[], syntax: VerbSyntax): SplitArguments => {
+  const split: SplitArguments = { options: [], operands: [] }
+  let optionsEnded = false
+  for (let index = 0; index < words.length; index++) {
+    const { value } = words[index]
+    if (optionsEnded || !value.startsWith('-')) split.operands.push(value)
+    else if (value === '--') optionsEnded = true
+    else {
+      split.options.push(value)
+      if (takesNextWord(value, syntax)) index++
+    }
+  }
+  return split
+}
+
+const holdsShortFlag = (option: string, short: string | undefined, syntax: VerbSyntax): boolean =>
+  short !== undefined &&
+  isShortCluster(option) &&
+  [...clusterLetters(option, syntax)].some((letter) => short.includes(letter))
+
+const breaksRule = (rule: DangerRule, { options, operands }: SplitArguments, syntax: VerbSyntax): boolean =>
+  options.some((option) => rule.long.some((name) => matchesLong(option, name))) ||
+  options.some((option) => holdsShortFlag(option, rule.short, syntax)) ||
+  (rule.operand !== undefined && operands.some(rule.operand))
+
+const dangerOf = (verb: ProtectedVerb, { assignments, verbArguments }: GitInvocation): string | undefined => {
+  if (assignments.some((assignment) => HOOK_SKIPPING_VARIABLE.test(assignment))) return SKIP_HOOKS
+  const syntax = VERB_SYNTAX[verb]
+  const split = splitArguments(verbArguments, syntax)
+  return DANGER_RULES[verb].find((rule) => breaksRule(rule, split, syntax))?.message
+}
+
+/** The `key=value` entries the global options set, from `-c k=v`, `--config-env k=V` and `--config-env=k=V`. */
+const configEntries = ({ options }: GitInvocation): string[] =>
+  options.flatMap(({ value }, index) => {
+    if (value.startsWith(CONFIG_ENV_ATTACHED)) return [value.slice(CONFIG_ENV_ATTACHED.length)]
+    const previous = options[index - 1]?.value
+    return previous !== undefined && CONFIG_OPTIONS.has(previous) ? [value] : []
+  })
+
+const definesAlias = (invocation: GitInvocation): boolean =>
+  configEntries(invocation).some((entry) => INLINE_ALIAS.test(entry))
+
+const targetDirectory = (directories: string[]): string =>
+  directories.reduce((joined, directory) => (directory.startsWith('/') ? directory : posix.join(joined, directory)), '')
+
+const plainInstead = (verb: string): string => `Run \`git ${verb} …\` as a plain command of its own.`
+
+const optionsHint = (verb: string, { options, directories }: GitInvocation): string => {
+  const written = `\`git ${options.map(({ value }) => value).join(' ')} ${verb}\``
+  const instead =
+    directories.length > 0
+      ? `Run \`cd ${targetDirectory(directories)}\` as a command of its own, then \`git ${verb} …\` with the same arguments.`
+      : `Run \`git ${verb} …\` without them; if one is really needed, ask the user first.`
+  return `Refused: ${written} puts options between git and ${verb}, so the permission rules for \`git ${verb}\` never see it. ${instead}`
+}
+
+const variablesHint = (verb: string): string =>
+  `Refused: a \`GIT_CONFIG…\`, \`GIT_DIR\`, \`GIT_WORK_TREE\` or \`GIT_INDEX_FILE\` assignment changes what \`git ${verb}\` acts on, like an option before the verb. ${plainInstead(verb)}`
+
+const formHint = (verb: string): string =>
+  `Refused: this \`git ${verb}\` is written in a form the permission rules do not match (behind a wrapper, through a path, quoted, split across lines or inside \`sh -c\`). ${plainInstead(verb)}`
+
+const judgeProtectedVerb = (verb: ProtectedVerb, invocation: GitInvocation, ruleMatched: boolean): GitGuardDecision => {
+  if (invocation.verbArguments.some(({ value }) => BRACE_IN_OPTION.test(value))) return deny(BRACE_HINT)
+  const danger = dangerOf(verb, invocation)
+  if (danger) return deny(`Refused: ${danger}`)
+  if (invocation.options.length > 0) return deny(optionsHint(verb, invocation))
+  if (invocation.assignments.some((assignment) => REDIRECTING_VARIABLE.test(assignment))) {
+    return deny(variablesHint(verb))
+  }
+  return ruleMatched ? PASS : deny(formHint(verb))
+}
+
+/**
+ * A quoted, escaped or expanded verb could be a protected one. Where git runs as the program it is
+ * refused; as a mere argument, as in `grep git "$file"`, it is no git call at all.
+ */
+const judgeInvocation = (invocation: GitInvocation, position: GitPosition): GitGuardDecision => {
+  if (definesAlias(invocation)) return deny(ALIAS_HINT)
+  const { value, literal } = invocation.verb
+  if (isProtectedVerb(value)) {
+    return judgeProtectedVerb(value, invocation, position === GIT_POSITION.ruleMatched && literal)
+  }
+  return literal || position === GIT_POSITION.argument ? PASS : deny(VERB_HINT)
+}
+
+const isShell = (word: Word): boolean => SHELLS.has(programName(word))
+
+/** The script word after `-c`: the first one that is neither an option nor `--`. */
+const shellCommandScript = (words: SimpleCommand, shellIndex: number): string | undefined => {
+  const flag = words.findIndex((word, position) => position > shellIndex && SHELL_COMMAND_FLAG.test(word.value))
+  if (flag === -1) return undefined
+  return words.slice(flag + 1).find((word) => !isOption(word))?.value
+}
+
+const inlineScript = (words: SimpleCommand, index: number): string | undefined => {
+  const word = words[index]
+  if (word.literal && word.value === 'eval') return words.slice(index + 1).map(({ value }) => value).join(' ')
+  return isShell(word) ? shellCommandScript(words, index) : undefined
+}
+
+/** A shell at the rule start with no script argument reads its script from stdin: a pipe, a here-document. */
+const readsScriptFromInput = (words: SimpleCommand): boolean => {
+  const start = ruleStart(words)
+  const shell = words[start]
+  return shell !== undefined && isShell(shell) && words.slice(start + 1).every(isOption)
+}
+
+/**
+ * `HUSKY=0`, `export HUSKY=0`, `local -x HUSKY=0`, `set -a; HUSKY=0`: wherever such an assignment
+ * stands, it may reach a later git call of the script, not only the one it precedes.
+ */
+const setsGitVariable = (words: SimpleCommand): boolean =>
+  words.some(({ value }) => HOOK_SKIPPING_VARIABLE.test(value) || REDIRECTING_VARIABLE.test(value))
+
+/** A program expanded from a variable or a substitution could be git. */
+const runsExpandedProgram = (words: SimpleCommand): boolean => words[ruleStart(words)]?.literal === false
+
+/** An expanded program (`"$tool" push`, `sudo "$tool" push`) followed by a protected verb could be git. */
+const judgeExpandedProgram = (words: SimpleCommand): GitGuardDecision => {
+  const program = words.findIndex((word, index) => !word.literal && isProgramPosition(words, index))
+  if (program === -1) return PASS
+  return words.slice(program + 1).some(({ value }) => isProtectedVerb(value)) ? deny(PROGRAM_HINT) : PASS
+}
+
+const firstDenial = (decisions: GitGuardDecision[]): GitGuardDecision =>
+  decisions.find((decision) => decision.kind === 'deny') ?? PASS
+
+const denyIfMentionsProtectedVerb = (script: string, reason: string): GitGuardDecision => {
+  const verb = script.match(PROTECTED_MENTION)?.[1]
+  return verb ? deny(`Refused: ${reason}, and it mentions \`git ${verb}\`. ${plainInstead(verb)}`) : PASS
+}
+
+const judgeWord = (words: SimpleCommand, index: number, context: ScriptContext): GitGuardDecision => {
+  const script = inlineScript(words, index)
+  if (script !== undefined) return judgeScript(script, SCRIPT_CONTEXT.nested)
+  if (!isGit(words[index])) return PASS
+  const invocation = readInvocation(words, index)
+  return invocation ? judgeInvocation(invocation, gitPosition(words, index, context)) : PASS
+}
+
+const judgeCommand = (words: SimpleCommand, context: ScriptContext): GitGuardDecision =>
+  firstDenial([...words.map((_word, index) => judgeWord(words, index, context)), judgeExpandedProgram(words)])
+
+/**
+ * What no single command shows. Each check reads the whole script, so a harmless git call beside
+ * a shell that reads stdin, a set git variable or an expanded program is refused too: an accepted
+ * over-refusal for rare shapes.
+ */
+const judgeScriptWide = (script: string, commands: SimpleCommand[]): GitGuardDecision => {
+  if (commands.some(readsScriptFromInput)) {
+    return denyIfMentionsProtectedVerb(script, 'a shell reads its script from input here, which no rule inspects')
+  }
+  if (commands.some(setsGitVariable)) {
+    return denyIfMentionsProtectedVerb(script, 'a `HUSKY`, `LEFTHOOK`, `SKIP` or `GIT_*` variable is set, which changes the git calls')
+  }
+  if (commands.some(runsExpandedProgram)) {
+    return denyIfMentionsProtectedVerb(script, 'a program is expanded from a variable or a substitution and could be git')
+  }
+  return PASS
+}
+
+const judgeScript = (script: string, context: ScriptContext): GitGuardDecision => {
+  try {
+    const commands = parseShell(script)
+    return firstDenial([...commands.map((words) => judgeCommand(words, context)), judgeScriptWide(script, commands)])
+  } catch (error) {
+    if (error instanceof ShellParseError) return denyIfMentionsProtectedVerb(script, 'the command could not be parsed')
+    throw error
+  }
+}
+
+/**
+ * Decides on a Bash command before it runs. Denies a protected git verb that a permission rule
+ * written as `git <verb> …` would not match (options or `GIT_*` variables before the verb, a
+ * wrapper, a path to git, a quoted verb, a line continuation, `sh -c`, `eval`, a script piped into
+ * a shell), and denies a force push, a skipped hook and a hard reset in any form. Everything else
+ * passes on to the project's own permission rules.
+ */
+export const decideBashCommand = (command: string): GitGuardDecision => judgeScript(command, SCRIPT_CONTEXT.top)

package/kit/hooks/hooks/git-guard/index.ts

@@ -0,0 +1,38 @@
+// PreToolUse hook for Bash, shipped by jackherd. Reads the hook input on stdin and
+// answers with a deny decision on stdout, or with nothing to leave the call to the permission rules.
+// Any failure denies: a guard that crashes must not wave the command through.
+import { decideBashCommand, type GitGuardDecision } from './decision'
+
+type HookInput = { tool_input?: { command?: unknown } }
+
+const decideInput = (text: string): GitGuardDecision | undefined => {
+  const command = (JSON.parse(text) as HookInput).tool_input?.command
+  return typeof command === 'string' ? decideBashCommand(command) : undefined
+}
+
+const failureDecision = (error: unknown): GitGuardDecision => ({
+  kind: 'deny',
+  reason: `Refused: the git guard hook failed (${error instanceof Error ? error.message : String(error)}), so the command is blocked. Tell the user.`,
+})
+
+const decide = async (): Promise<GitGuardDecision | undefined> => {
+  try {
+    return decideInput(await Bun.stdin.text())
+  } catch (error) {
+    return failureDecision(error)
+  }
+}
+
+const decision = await decide()
+
+if (decision?.kind === 'deny') {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: decision.reason,
+      },
+    }),
+  )
+}