jackherd 0.0.1 → 1.0.0

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

@@ -0,0 +1,407 @@
+/**
+ * One word of a simple command, with quotes and escapes removed. `literal` is false when quoting,
+ * an escape, an expansion or a line continuation shaped the word, because then the text a
+ * permission rule matches is not `value`.
+ */
+export type Word = { value: string; literal: boolean }
+
+export type SimpleCommand = Word[]
+
+type Cursor = { source: string; index: number }
+
+/** `expands` when the delimiter is unquoted: the shell then runs `$(…)` and backticks in the body. */
+type Heredoc = { delimiter: string; stripTabs: boolean; expands: boolean }
+
+type ListState = {
+  commands: SimpleCommand[]
+  words: Word[]
+  word: Word | undefined
+  nextWordContinued: boolean
+  dropNextWord: boolean
+  heredocs: Heredoc[]
+}
+
+type Terminator = ')' | '`' | undefined
+
+type Handler = (cursor: Cursor, state: ListState) => boolean
+
+export class ShellParseError extends Error {}
+
+const BLANKS = ' \t'
+const OPERATORS = '&;|'
+const REDIRECTION_CHARS = '<>&|'
+const DELIMITER_END = ' \t\n;&|<>()'
+
+/** Marks where an expansion stood in a word (`$z` keeps its name after it): the value is unknown before the shell runs. */
+const EXPANSION = '$'
+
+const peek = (cursor: Cursor, offset = 0): string => cursor.source[cursor.index + offset] ?? ''
+
+/** Whether the character is one of `chars`; the empty string past the end of input never is. */
+const isOneOf = (chars: string, char: string): boolean => char !== '' && chars.includes(char)
+
+const atEnd = (cursor: Cursor): boolean => cursor.index >= cursor.source.length
+
+const newListState = (): ListState => ({
+  commands: [],
+  words: [],
+  word: undefined,
+  nextWordContinued: false,
+  dropNextWord: false,
+  heredocs: [],
+})
+
+const currentWord = (state: ListState): Word => {
+  if (!state.word) {
+    state.word = { value: '', literal: !state.nextWordContinued }
+    state.nextWordContinued = false
+  }
+  return state.word
+}
+
+const appendShaped = (state: ListState, text: string): void => {
+  const word = currentWord(state)
+  word.value += text
+  word.literal = false
+}
+
+/** `{a,b}` and `{a..b}` expand into other words before the program sees them. */
+const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/
+
+const endWord = (state: ListState): void => {
+  const { word } = state
+  if (!word) return
+  if (BRACE_EXPANSION.test(word.value)) word.literal = false
+  state.word = undefined
+  if (state.dropNextWord) state.dropNextWord = false
+  else state.words.push(word)
+}
+
+const endCommand = (state: ListState): void => {
+  endWord(state)
+  state.dropNextWord = false
+  if (state.words.length > 0) state.commands.push(state.words)
+  state.words = []
+}
+
+/**
+ * Text in `${…}` or `$((…))` that could hold or end a command: a substitution, a quote or an
+ * escape (which the plain bracket count below cannot follow), an operator or a newline.
+ */
+const MAYBE_COMMAND = /\$\(|[<>]\(|[`'";&|\n\\]/
+
+/** Rather than parse a command inside an expansion, the whole text is refused as unparsable. */
+const assertNoHiddenCommand = (text: string): void => {
+  if (MAYBE_COMMAND.test(text)) throw new ShellParseError('a command or quote inside an expansion')
+}
+
+const skipBalanced = (cursor: Cursor, open: string, close: string): void => {
+  const start = cursor.index
+  let depth = 0
+  while (!atEnd(cursor)) {
+    const char = peek(cursor)
+    cursor.index++
+    if (char === open) depth++
+    if (char === close && --depth === 0) return assertNoHiddenCommand(cursor.source.slice(start, cursor.index))
+  }
+  throw new ShellParseError(`missing ${close}`)
+}
+
+const SUBSTITUTION = /\$\(|`/
+
+/** Skips the body. A substitution in an expanding body runs, so it is refused as unparsable. */
+const readHeredocBody = (cursor: Cursor, { delimiter, stripTabs, expands }: Heredoc): void => {
+  while (!atEnd(cursor)) {
+    const newline = cursor.source.indexOf('\n', cursor.index)
+    const lineEnd = newline === -1 ? cursor.source.length : newline
+    const line = cursor.source.slice(cursor.index, lineEnd)
+    cursor.index = lineEnd + 1
+    if ((stripTabs ? line.replace(/^\t+/, '') : line) === delimiter) return
+    if (expands && SUBSTITUTION.test(line)) throw new ShellParseError('a command inside a here-document')
+  }
+  throw new ShellParseError(`here-document without its ${delimiter} line`)
+}
+
+const readHeredocHeader = (cursor: Cursor, stripTabs: boolean): Heredoc => {
+  let delimiter = ''
+  let quoted = false
+  while (!atEnd(cursor) && !isOneOf(DELIMITER_END, peek(cursor))) {
+    const char = peek(cursor)
+    if (isOneOf('\'"\\', char)) quoted = true
+    else delimiter += char
+    cursor.index++
+  }
+  if (delimiter === '') throw new ShellParseError('here-document without a delimiter')
+  return { delimiter, stripTabs, expands: !quoted }
+}
+
+const lineContinuation: Handler = (cursor, state) => {
+  if (peek(cursor) !== '\\' || peek(cursor, 1) !== '\n') return false
+  cursor.index += 2
+  if (state.word) state.word.literal = false
+  else state.nextWordContinued = true
+  return true
+}
+
+const escapedChar: Handler = (cursor, state) => {
+  if (peek(cursor) !== '\\') return false
+  appendShaped(state, peek(cursor, 1))
+  cursor.index += 2
+  return true
+}
+
+const blank: Handler = (cursor, state) => {
+  if (!isOneOf(BLANKS, peek(cursor))) return false
+  endWord(state)
+  cursor.index++
+  return true
+}
+
+const newline: Handler = (cursor, state) => {
+  if (peek(cursor) !== '\n') return false
+  endCommand(state)
+  cursor.index++
+  for (const heredoc of state.heredocs) readHeredocBody(cursor, heredoc)
+  state.heredocs = []
+  return true
+}
+
+const comment: Handler = (cursor, state) => {
+  if (peek(cursor) !== '#' || state.word) return false
+  while (!atEnd(cursor) && peek(cursor) !== '\n') cursor.index++
+  return true
+}
+
+const singleQuoted: Handler = (cursor, state) => {
+  if (peek(cursor) !== "'") return false
+  const close = cursor.source.indexOf("'", cursor.index + 1)
+  if (close === -1) throw new ShellParseError('unterminated single quote')
+  appendShaped(state, cursor.source.slice(cursor.index + 1, close))
+  cursor.index = close + 1
+  return true
+}
+
+const ANSI_C_ESCAPES: Record<string, string> = { n: '\n', t: '\t', r: '\r', e: '\u001b', a: '\u0007', b: '\b', f: '\f', v: '\v' }
+const MAX_CODE_POINT = 0x10ffff
+const ANSI_C_NUMERIC = /^(x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|[0-7]{1,3})/
+
+/** Decodes one escape of a `$'…'` string at the cursor, which stands on the backslash. */
+const readAnsiCEscape = (cursor: Cursor): string => {
+  const numeric = cursor.source.slice(cursor.index + 1).match(ANSI_C_NUMERIC)?.[0]
+  if (numeric) {
+    cursor.index += 1 + numeric.length
+    const radix = /^[0-7]/.test(numeric) ? 8 : 16
+    const codePoint = Number.parseInt(radix === 8 ? numeric : numeric.slice(1), radix)
+    if (codePoint > MAX_CODE_POINT) throw new ShellParseError('an escape beyond Unicode')
+    return String.fromCodePoint(codePoint)
+  }
+  const letter = peek(cursor, 1)
+  cursor.index += 2
+  return ANSI_C_ESCAPES[letter] ?? letter
+}
+
+const ansiCQuoted: Handler = (cursor, state) => {
+  if (peek(cursor) !== '$' || peek(cursor, 1) !== "'") return false
+  cursor.index += 2
+  let text = ''
+  while (!atEnd(cursor) && peek(cursor) !== "'") {
+    if (peek(cursor) === '\\') text += readAnsiCEscape(cursor)
+    else {
+      text += peek(cursor)
+      cursor.index++
+    }
+  }
+  if (atEnd(cursor)) throw new ShellParseError('unterminated $-quote')
+  cursor.index++
+  appendShaped(state, text)
+  return true
+}
+
+const substitute = (cursor: Cursor, state: ListState, skip: number, terminator: Terminator): void => {
+  cursor.index += skip
+  state.commands.push(...parseList(cursor, terminator))
+  appendShaped(state, EXPANSION)
+}
+
+const startsCommandSubstitution = (cursor: Cursor): boolean =>
+  peek(cursor) === '$' && peek(cursor, 1) === '(' && peek(cursor, 2) !== '('
+
+const readDoubleQuotedEscape = (cursor: Cursor, state: ListState): void => {
+  const next = peek(cursor, 1)
+  if (next !== '\n') appendShaped(state, isOneOf('$`"\\', next) ? next : `\\${next}`)
+  cursor.index += 2
+}
+
+const backtick: Handler = (cursor, state) => {
+  if (peek(cursor) !== '`') return false
+  substitute(cursor, state, 1, '`')
+  return true
+}
+
+const arithmetic: Handler = (cursor, state) => {
+  if (peek(cursor) !== '$' || peek(cursor, 1) !== '(' || peek(cursor, 2) !== '(') return false
+  cursor.index++
+  skipBalanced(cursor, '(', ')')
+  appendShaped(state, EXPANSION)
+  return true
+}
+
+const commandSubstitution: Handler = (cursor, state) => {
+  if (!startsCommandSubstitution(cursor)) return false
+  substitute(cursor, state, 2, ')')
+  return true
+}
+
+/** Inside double quotes only these two still open a command. */
+const QUOTED_HANDLERS: Handler[] = [backtick, commandSubstitution]
+
+const doubleQuoted: Handler = (cursor, state) => {
+  if (peek(cursor) !== '"') return false
+  appendShaped(state, '')
+  cursor.index++
+  while (!atEnd(cursor)) {
+    const char = peek(cursor)
+    if (char === '"') {
+      cursor.index++
+      return true
+    }
+    if (char === '\\') readDoubleQuotedEscape(cursor, state)
+    else if (!QUOTED_HANDLERS.some((handle) => handle(cursor, state))) {
+      appendShaped(state, char)
+      cursor.index++
+    }
+  }
+  throw new ShellParseError('unterminated double quote')
+}
+
+/** `$"…"` is a double-quoted string translated by the locale; the text is the same. */
+const localeQuoted: Handler = (cursor, state) => {
+  if (peek(cursor) !== '$' || peek(cursor, 1) !== '"') return false
+  cursor.index++
+  return doubleQuoted(cursor, state)
+}
+
+const parameterExpansion: Handler = (cursor, state) => {
+  if (peek(cursor) !== '$') return false
+  if (peek(cursor, 1) === '{') {
+    cursor.index++
+    skipBalanced(cursor, '{', '}')
+  } else cursor.index++
+  appendShaped(state, EXPANSION)
+  return true
+}
+
+const processSubstitution: Handler = (cursor, state) => {
+  if (!isOneOf('<>', peek(cursor)) || peek(cursor, 1) !== '(') return false
+  endWord(state)
+  substitute(cursor, state, 2, ')')
+  return true
+}
+
+const hereString: Handler = (cursor, state) => {
+  if (peek(cursor) !== '<' || peek(cursor, 1) !== '<' || peek(cursor, 2) !== '<') return false
+  endWord(state)
+  cursor.index += 3
+  state.dropNextWord = true
+  return true
+}
+
+const hereDocument: Handler = (cursor, state) => {
+  if (peek(cursor) !== '<' || peek(cursor, 1) !== '<') return false
+  endWord(state)
+  cursor.index += 2
+  const stripTabs = peek(cursor) === '-'
+  if (stripTabs) cursor.index++
+  while (isOneOf(BLANKS, peek(cursor))) cursor.index++
+  state.heredocs.push(readHeredocHeader(cursor, stripTabs))
+  return true
+}
+
+const isFileDescriptor = (word: Word | undefined): boolean => word !== undefined && word.literal && /^\d+$/.test(word.value)
+
+const redirection: Handler = (cursor, state) => {
+  const char = peek(cursor)
+  if (char !== '<' && char !== '>' && !(char === '&' && peek(cursor, 1) === '>')) return false
+  if (isFileDescriptor(state.word)) state.word = undefined
+  else endWord(state)
+  while (isOneOf(REDIRECTION_CHARS, peek(cursor))) cursor.index++
+  state.dropNextWord = true
+  return true
+}
+
+const operator: Handler = (cursor, state) => {
+  if (!isOneOf(OPERATORS, peek(cursor))) return false
+  endCommand(state)
+  while (isOneOf(OPERATORS, peek(cursor))) cursor.index++
+  return true
+}
+
+const subshell: Handler = (cursor, state) => {
+  if (peek(cursor) !== '(') return false
+  endCommand(state)
+  cursor.index++
+  state.commands.push(...parseList(cursor, ')'))
+  return true
+}
+
+const strayCloseParen: Handler = (cursor, state) => {
+  if (peek(cursor) !== ')') return false
+  endCommand(state)
+  cursor.index++
+  return true
+}
+
+const plainChar = (cursor: Cursor, state: ListState): void => {
+  currentWord(state).value += peek(cursor)
+  cursor.index++
+}
+
+/**
+ * First match wins, so a handler for a longer prefix precedes the one for its own prefix:
+ * `\\⏎` before `\\`, `$'`, `$"`, `$((` and `$(` before `$`, `<(`, `<<<` and `<<` before `<`.
+ */
+const HANDLERS: Handler[] = [
+  lineContinuation,
+  escapedChar,
+  blank,
+  newline,
+  comment,
+  ansiCQuoted,
+  localeQuoted,
+  singleQuoted,
+  doubleQuoted,
+  backtick,
+  arithmetic,
+  commandSubstitution,
+  parameterExpansion,
+  processSubstitution,
+  hereString,
+  hereDocument,
+  redirection,
+  operator,
+  subshell,
+  strayCloseParen,
+]
+
+const parseList = (cursor: Cursor, terminator: Terminator): SimpleCommand[] => {
+  const state = newListState()
+  while (!atEnd(cursor)) {
+    if (terminator !== undefined && peek(cursor) === terminator) {
+      cursor.index++
+      endCommand(state)
+      return state.commands
+    }
+    if (!HANDLERS.some((handle) => handle(cursor, state))) plainChar(cursor, state)
+  }
+  if (terminator !== undefined) throw new ShellParseError(`missing ${terminator}`)
+  endCommand(state)
+  return state.commands
+}
+
+/**
+ * Splits a shell script into its simple commands, the way a permission rule sees them: at `&&`,
+ * `||`, `;`, `|`, `&` and newlines, and into subshells, command substitutions and process
+ * substitutions. Here-document bodies, comments and redirection targets are not commands and are
+ * dropped. Throws `ShellParseError` on an unterminated quote or substitution.
+ */
+export const parseShell = (script: string): SimpleCommand[] => parseList({ source: script, index: 0 }, undefined)

package/kit/hooks/hooks/watch-guard/background.ts

@@ -0,0 +1,36 @@
+const lineEnd = (script: string, from: number): number => {
+  const end = script.indexOf('\n', from)
+  return end === -1 ? script.length : end
+}
+
+/** The index after the quote that closes the one at `from`; a backslash escapes inside double quotes. */
+const afterQuoted = (script: string, from: number): number => {
+  const quote = script[from]
+  let index = from + 1
+  while (index < script.length && script[index] !== quote) index += quote === '"' && script[index] === '\\' ? 2 : 1
+  return index + 1
+}
+
+/** A lone `&`, not `&&`, `&>`, `>&`, `<&` or `|&`. */
+const isLoneAmpersand = (script: string, index: number): boolean =>
+  script[index + 1] !== '&' && script[index + 1] !== '>' && !'&<>|'.includes(script[index - 1] ?? ' ')
+
+/**
+ * Whether an unquoted `&` outside a comment sends some command of the script into the background. It
+ * answers for the whole script, not for one command: `sleep 1 & jh watch` counts as well.
+ * Here-document bodies are input and belong out of `script` before it is asked.
+ */
+export const hasBackgroundJob = (script: string): boolean => {
+  let index = 0
+  let wordStart = true
+  while (index < script.length) {
+    const char = script[index] ?? ''
+    if (char === '&' && isLoneAmpersand(script, index)) return true
+    if (char === '\\') index += 2
+    else if (char === "'" || char === '"') index = afterQuoted(script, index)
+    else if (char === '#' && wordStart) index = lineEnd(script, index)
+    else index += char === '&' && script[index + 1] === '&' ? 2 : 1
+    wordStart = /[\s;|&()]/.test(char)
+  }
+  return false
+}

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

@@ -0,0 +1,53 @@
+import { startsIn, type WatcherStart } from './starts'
+import { startsInText } from './text-fallback'
+
+export type BashToolInput = { command?: string; run_in_background?: boolean }
+
+const LINE_CONTINUATION = /\\\n\s*/g
+
+const STREAM_REFUSAL = [
+  'jh watch --stream never ends, so a Bash call never reports it, not even in the background.',
+  'Start the same command with the Monitor tool (timeout_ms 1800000), where every line it prints reaches you.',
+].join('\n')
+
+const BACKGROUND_REFUSAL = [
+  'jh watch only reports back as a background task or under the Monitor tool.',
+  'Start it with the Monitor tool and --stream, or as its own Bash call with run_in_background: true.',
+].join('\n')
+
+const BACKGROUND_JOB_REFUSAL = [
+  'jh watch in a call that sends a command off with & : a trailing & ends the call before the watcher reports.',
+  'Start it with the Monitor tool and --stream, or as its own Bash call with run_in_background: true and no &.',
+].join('\n')
+
+/**
+ * The starts in a call. Any failure of the parse (an unreadable call, nesting past the limit, or an error
+ * nobody foresaw such as a stack overflow) falls back to the text match: a hook that throws lets the call
+ * through, so a doubtful call is refused instead.
+ */
+export const startsOf = (command: string, parse: typeof startsIn = startsIn): WatcherStart[] => {
+  const script = command.replace(LINE_CONTINUATION, ' ')
+  try {
+    return parse(script, false)
+  } catch {
+    return startsInText(script)
+  }
+}
+
+/**
+ * The reason to refuse a Bash call that starts `jh watch` where its report goes unseen, or null.
+ * A start is a simple command whose program runs the watcher (the `jh` bin or the older `agent-kit` one, a package runner with
+ * the package, or `bun` with the CLI's script) with the subcommand `watch`, also behind wrappers, inside
+ * `bash -c`, `eval`, a substitution, or a here-document or here-string fed to a shell. Text that only
+ * names the command (an argument, a quoted string, a data here-document) is no start. A `--stream` start
+ * never finishes, so no Bash call reports it; a single run reports only as its own background task, in a
+ * call that sends nothing off with `&`.
+ */
+export const watcherStartViolation = (input: BashToolInput): string | null => {
+  if (!input.command) return null
+  const starts = startsOf(input.command)
+  if (starts.length === 0) return null
+  if (starts.some((start) => start.stream)) return STREAM_REFUSAL
+  if (input.run_in_background !== true) return BACKGROUND_REFUSAL
+  return starts.some((start) => start.callHasBackgroundJob) ? BACKGROUND_JOB_REFUSAL : null
+}

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

@@ -0,0 +1,11 @@
+// PreToolUse hook for Bash, shipped by jackherd: refuses a `jh watch` start whose
+// reports would go unseen. Reads the hook input on stdin; exit 2 blocks the call and hands the reason on
+// stderr back to the model, exit 0 leaves the call to the permission rules.
+import { watcherStartViolation } from './decision'
+
+const payload = await Bun.stdin.json()
+const violation = watcherStartViolation(payload.tool_input ?? {})
+if (violation) {
+  console.error(violation)
+  process.exit(2)
+}

package/kit/hooks/hooks/watch-guard/shell-input.ts

@@ -0,0 +1,32 @@
+import { parseShell } from '../git-guard/shell'
+
+/** Programs that run their `-c` argument as a command line; the names of shells among them also read stdin as a script. */
+export const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'])
+
+const SHELL_NAME = `(?:${[...SHELLS].join('|')})`
+
+const HEREDOC = /(<<-?\s*\\?(['"]?)([^\s;&|<>()'"]+)\2)([^\n]*)\n([\s\S]*?)\n\t*\3(?=\n|$)/g
+const SHELL_INPUT = new RegExp(`(?:^|[\\s;&|(/])${SHELL_NAME}\\b`)
+const PIPED_TO_SHELL = new RegExp(`\\|\\s*(?:\\S*/)?${SHELL_NAME}\\b`)
+const SHELL_HERESTRING = new RegExp(`(?:^|[\\s;&|(/])${SHELL_NAME}\\b[^\\n<]*<<<\\s*([^\\n]*)`, 'g')
+
+/**
+ * The text of the line in front of a here-document operator. Found by looking back from a match instead of by
+ * a leading `[^\n]*` in the pattern, which would rescan the rest of the line from every position (quadratic).
+ */
+const lineBefore = (script: string, index: number): string => script.slice(script.lastIndexOf('\n', index - 1) + 1, index)
+
+/** The script without here-document bodies, which are input, not commands of this script. */
+export const withoutHeredocBodies = (script: string): string =>
+  script.replace(HEREDOC, (_whole, operator: string, _quote, _tag, rest: string) => `${operator}${rest}`)
+
+/** The bodies of here-documents a shell reads as its script: `bash <<EOF`, `sh -s <<EOF`, `cat <<EOF | sh`. */
+export const shellHeredocBodies = (script: string): string[] =>
+  [...script.matchAll(HEREDOC)].flatMap((match) => {
+    const [, , , , rest = '', body = ''] = match
+    return SHELL_INPUT.test(lineBefore(script, match.index)) || PIPED_TO_SHELL.test(rest) ? [body] : []
+  })
+
+/** The strings a shell reads as its script from a here-string: `bash <<< "<script>"`. */
+export const shellHereStrings = (script: string): string[] =>
+  [...script.matchAll(SHELL_HERESTRING)].flatMap(([, rest = '']) => parseShell(rest)[0]?.[0]?.value ?? [])