jackherd 1.16.0 → 1.18.0

package/kit/hooks/hooks/approval-gate/standing-history.ts

@@ -0,0 +1,90 @@
+/**
+ * The board's history row a call under a standing approval leaves before it passes: its id, lane, the start of its
+ * hash, the kind of statement and its first table, and the end of the approval. The board is committed and SQL may
+ * carry customer data in its values, so the row names no value; the whole call stays in the request file.
+ */
+import { type BoardLanguage, openLaneNamesOf } from '../shared/board-lanes'
+import type { Board } from '../shared/boards'
+import { isRecord } from '../shared/json'
+import { STAGE } from './settings'
+
+export type StandingHistoryEntry = { id: string; lane: string; hash: string; query: string; until: number; at: number }
+
+/** The history section and its table head per plan language, as `PLAN_VOCABULARY` and `withHistoryRow` in the package. */
+const HISTORY_HEADING: Record<BoardLanguage, string> = { de: 'Verlauf', en: 'History' }
+
+/** Statement words a history row may name; anything else reads as `sql`, so a first word is never a value. */
+const STATEMENTS = new Set(['select', 'insert', 'update', 'delete', 'merge', 'with', 'truncate', 'alter', 'create', 'drop', 'grant', 'revoke', 'copy', 'call', 'do', 'set', 'begin', 'commit'])
+
+/** The word before the table each statement writes to. */
+const TABLE_AFTER: Record<string, RegExp> = {
+  update: /^update\s+(?:only\s+)?/i,
+  insert: /^insert\s+into\s+/i,
+  delete: /^delete\s+from\s+(?:only\s+)?/i,
+}
+
+const IDENTIFIER = /^"?([A-Za-z_][A-Za-z0-9_$]*)"?(?:\."?([A-Za-z_][A-Za-z0-9_$]*)"?)?/
+const LEADING_NOISE = /^(?:\s+|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/
+const HASH_START = 8
+/** The header row and the separator row of a table. */
+const TABLE_HEAD_LINES = 2
+
+const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+const timeOfDay = (at: number): string => {
+  const date = new Date(at)
+  return `${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+}
+
+/** The date cell of a history row, `YYYY-MM-DD` in local time. */
+export const historyDate = (at: number): string => {
+  const date = new Date(at)
+  return `${date.getFullYear()}-${twoDigits(date.getMonth() + 1)}-${twoDigits(date.getDate())}`
+}
+
+const tableOf = (statement: string, sql: string): string | undefined => {
+  const after = TABLE_AFTER[statement]
+  const match = after?.exec(sql)
+  const identifier = match ? IDENTIFIER.exec(sql.slice(match[0].length)) : null
+  return identifier ? [identifier[1], identifier[2]].filter(Boolean).join('.') : undefined
+}
+
+/** The SQL of a call's input (`{ query }`, as an SQL tool takes it); empty for any other input. */
+export const queryOf = (input: unknown): string =>
+  isRecord(input) && typeof input.query === 'string' ? input.query : ''
+
+/** The kind of statement and the table it writes to, from the start of the SQL: `update orders`, `select`, `sql`. */
+export const sqlHeadOf = (query: string): string => {
+  const sql = query.replace(LEADING_NOISE, '')
+  const statement = /^[A-Za-z]+/.exec(sql)?.[0].toLowerCase() ?? ''
+  if (!STATEMENTS.has(statement)) return 'sql'
+  const table = tableOf(statement, sql)
+  return table === undefined ? statement : `${statement} ${table}`
+}
+
+/** The row's text: the time, then what passed without asking and under which approval. */
+export const standingHistoryLine = ({ id, lane, hash, query, until, at }: StandingHistoryEntry): string =>
+  `${timeOfDay(at)}: ${STAGE} sql without asking ${id} ${lane} ${hash.slice(0, HASH_START)} (${sqlHeadOf(query)}, standing approval ${STAGE} until ${timeOfDay(until)})`
+
+const cell = (text: string): string => text.replace(/\s+/g, ' ').trim().replaceAll('|', '\\|')
+
+/** The board with a row on top of its history table; null for a board without that table, so nothing passes. */
+export const withHistoryRow = (board: string, language: BoardLanguage, date: string, text: string): string | null => {
+  const lines = board.split('\n')
+  const heading = new RegExp(`^##\\s+${HISTORY_HEADING[language]}\\s*$`)
+  const start = lines.findIndex((line) => heading.test(line))
+  if (start === -1) return null
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s/.test(line))
+  const tableAt = (end === -1 ? rest : rest.slice(0, end)).findIndex((line) => line.startsWith('|'))
+  if (tableAt === -1) return null
+  const firstRow = start + 1 + tableAt + TABLE_HEAD_LINES
+  return [...lines.slice(0, firstRow), `| ${date} | ${cell(text)} |`, ...lines.slice(firstRow)].join('\n')
+}
+
+/** The board whose lanes table names the lane as open; the only board when none does; else none. */
+export const boardForLane = (boards: readonly Board[], lane: string, language: BoardLanguage): Board | null => {
+  const naming = boards.filter(({ text }) => openLaneNamesOf(text, language).includes(lane))
+  if (naming.length === 1) return naming[0]
+  return naming.length === 0 && boards.length === 1 ? boards[0] : null
+}

package/kit/hooks/hooks/approval-gate/standing-sql.ts

@@ -0,0 +1,58 @@
+/**
+ * The standing approval for calls against stage: the user approved the environment for a while in the coordinator's
+ * dialog, and the coordinator marked this very call checked (`jh approval checked <id> <hash>`). Both are read from
+ * the coordinator's transcript; together they replace the dialog for one call. Only an `execute_sql` tool the config
+ * names as stage, whose name does not say `prod`, and only one insert, update or delete pass; every doubt asks as before.
+ * The SQL check guards against a mistake (a migration, a schema change, a statement appended), not against SQL written
+ * to get around it: the coordinator's reading before the mark is the control.
+ */
+import type { StandingKind, StandingMark } from '../shared/standing-mark'
+import type { CheckedMark } from './checked-marks'
+import type { ApprovalRequest } from './request'
+import { type GateSettings, isStandingTool, STAGE } from './settings'
+import { queryOf } from './standing-history'
+
+export type StandingSqlQuery = {
+  request: ApprovalRequest
+  /** The environments the user approved standing, as they hold now. */
+  grants: readonly StandingMark[]
+  checks: readonly CheckedMark[]
+  standingTools: GateSettings['standingTools']
+  now: number
+}
+
+/** The call passes, and the approval it passes under ends at `until`. */
+export type StandingSqlPass = { until: number }
+
+/** How a standing approval of an environment reads in the question: ``Environment `stage` <until> <YYYY-MM-DD HH:MM>``. */
+export const ENVIRONMENT_KIND: StandingKind = { key: 'Environment', isSubject: (subject) => subject === STAGE }
+
+/** The statements a standing approval covers, at the very start; a schema change or anything else goes to the user's dialog. */
+const STANDING_HEAD = /^[ \t\n]*(?:insert|update|delete)\b/i
+const TRAILING_TERMINATORS = new Set([' ', '\t', '\n', ';'])
+
+const isStageTool = (tool: string, standingTools: GateSettings['standingTools']): boolean =>
+  isStandingTool(tool) && standingTools[tool] === STAGE
+
+/** The SQL without the whitespace and semicolons it ends with; a scan from the end, linear in the length. */
+const withoutTrailingTerminators = (query: string): string => {
+  let end = query.length
+  while (end > 0 && TRAILING_TERMINATORS.has(query[end - 1])) end--
+  return query.slice(0, end)
+}
+
+/** One insert, update or delete: no semicolon before the end, so no second statement rides along (one in a value asks too). */
+const isStandingStatement = (query: string): boolean =>
+  STANDING_HEAD.test(query) && !withoutTrailingTerminators(query).includes(';')
+
+const isCheckedNow = ({ id, hash, createdAt }: ApprovalRequest, checks: readonly CheckedMark[], now: number): boolean =>
+  checks.some((check) => check.id === id && check.hash === hash && check.checkedAt >= createdAt && check.checkedAt <= now)
+
+/** Whether the call passes without a dialog, and until when the approval holds; null asks as before. */
+export const standingSqlDecision = ({ request, grants, checks, standingTools, now }: StandingSqlQuery): StandingSqlPass | null => {
+  if (request.usedAt !== null || !isStageTool(request.tool, standingTools)) return null
+  if (!isStandingStatement(queryOf(request.input))) return null
+  const grant = grants.find(({ subject, until }) => subject === STAGE && until > now)
+  if (grant === undefined || !isCheckedNow(request, checks, now)) return null
+  return { until: grant.until }
+}

package/kit/hooks/hooks/approval-gate/transcripts.ts

@@ -2,6 +2,10 @@ import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync } fro
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { type DialogAnswer, dialogAnswers, parseTranscript } from '../shared/dialog-answers'
+import { type CheckedMark, checkedMarks } from './checked-marks'
+
+/** What the coordinator's transcripts say about held calls: the user's dialog answers and the coordinator's marks. */
+export type CoordinatorLog = { answers: DialogAnswer[]; checks: CheckedMark[] }
 
 /** Claude Code's transcripts: `~/.claude/projects/<project>/<session>.jsonl`; this file is the client adapter. */
 const PROJECTS_DIRECTORY = join(homedir(), '.claude', 'projects')
@@ -29,12 +33,14 @@ const readTail = (path: string): string => {
   }
 }
 
-/** The dialog answers in the transcripts of these sessions; a session without a transcript gives none. */
-export const coordinatorAnswers = (
+/** The dialog answers and checked marks in the transcripts of these sessions, each read once; a session without a transcript gives none. */
+export const coordinatorLog = (
   sessions: readonly string[],
   projectsDirectory: string = PROJECTS_DIRECTORY,
-): DialogAnswer[] =>
-  sessions.flatMap((session) => {
+): CoordinatorLog => {
+  const entries = sessions.map((session) => {
     const path = transcriptPath(session, projectsDirectory)
-    return path ? dialogAnswers(parseTranscript(readTail(path))) : []
+    return path ? parseTranscript(readTail(path)) : []
   })
+  return { answers: entries.flatMap(dialogAnswers), checks: entries.flatMap(checkedMarks) }
+}

package/kit/hooks/hooks/lane-start-guard/decision.ts

@@ -0,0 +1,74 @@
+import { basename } from 'node:path'
+import { parseShell } from '../shared/shell'
+
+const MAX_DEPTH = 4
+const LANE_NAME = /^[a-z][a-z0-9_-]{0,31}$/
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash'])
+const WRAPPERS = new Set(['exec', 'nohup', 'env', 'time', 'setsid', 'command', 'nice', 'stdbuf', 'sudo', 'timeout'])
+const KEYWORDS = new Set(['!', '{', 'if', 'then', 'elif', 'else', 'while', 'until', 'do'])
+const ASSIGNMENT = /^\w+=/
+const DURATION = /^\d+(?:\.\d+)?[smhd]?$/
+const COMMAND_FLAG = /^-[a-zA-Z]*c[a-zA-Z]*$/
+/** What an unreadable call is searched for: the text that spells the start. */
+const START_TEXT = /\bherdr\s+agent\s+start\s+([a-z][a-z0-9_-]{0,31})\b/g
+
+const isPrefixWord = (word: string): boolean =>
+  KEYWORDS.has(word) ||
+  WRAPPERS.has(basename(word)) ||
+  ASSIGNMENT.test(word) ||
+  DURATION.test(word) ||
+  word.startsWith('-')
+
+/** The lane of a `herdr agent start <lane>` that is the command itself, behind wrappers; null for any other command. */
+const startOfCommand = (words: readonly string[]): string | null => {
+  const program = words.findIndex((word) => !isPrefixWord(word))
+  if (program === -1 || basename(words[program] ?? '') !== 'herdr') return null
+  if (words[program + 1] !== 'agent' || words[program + 2] !== 'start') return null
+  const lane = words[program + 3] ?? ''
+  return LANE_NAME.test(lane) ? lane : null
+}
+
+/** The script a `bash -c '<script>'` or `eval <words>` runs; null for any other command. */
+const nestedScriptOf = (words: readonly string[]): string | null => {
+  const program = words.findIndex((word) => !isPrefixWord(word))
+  const name = basename(words[program] ?? '')
+  if (name === 'eval') return words.slice(program + 1).join(' ')
+  if (!SHELLS.has(name)) return null
+  const flag = words.findIndex((word, index) => index > program && COMMAND_FLAG.test(word))
+  return flag === -1 ? null : (words[flag + 1] ?? null)
+}
+
+const startsIn = (script: string, depth: number): string[] =>
+  depth > MAX_DEPTH
+    ? []
+    : parseShell(script).flatMap((command) => {
+        const words = command.map((word) => word.value)
+        const lane = startOfCommand(words)
+        const nested = nestedScriptOf(words)
+        return [...(lane === null ? [] : [lane]), ...(nested === null ? [] : startsIn(nested, depth + 1))]
+      })
+
+/**
+ * The lanes a Bash call starts with `herdr agent start <lane>`, also behind wrappers, in `bash -c` and `eval`. Text
+ * that only names the command is no start. A call the parser cannot read falls back to the text match: a doubtful call
+ * is checked against the board, which a start with a row passes anyway.
+ */
+export const laneStartsOf = (command: string): string[] => {
+  try {
+    return startsIn(command, 0)
+  } catch {
+    return [...command.matchAll(START_TEXT)].map((match) => match[1] ?? '')
+  }
+}
+
+/**
+ * The reason to refuse the start of a lane that has no row in any board; null when a board has it or there is no
+ * board to check. A row is a table line that opens with the lane in backticks.
+ */
+export const missingRowReason = (lane: string, boards: readonly string[]): string | null => {
+  if (boards.length === 0) return null
+  const row = new RegExp(`^\\|\\s*\`${lane}\``, 'm')
+  return boards.some((board) => row.test(board))
+    ? null
+    : `Lane ${lane} has no row: write a table row that opens with \`| \\\`${lane}\\\`\` in the board before \`herdr agent start\` (orchestrate § 2 step 5), then start it.`
+}

package/kit/hooks/hooks/lane-start-guard/index.ts

@@ -0,0 +1,36 @@
+// PreToolUse hook for Bash, shipped by jackherd: refuses `herdr agent start <lane>` from the main checkout while no
+// board holds a row for the lane (orchestrate § 2 step 5). Reads the hook input on stdin; exit 2 blocks the call and
+// hands the reason on stderr back to the model, exit 0 leaves it to the permission rules. Any failure lets the call
+// through: the guard repeats a rule of the skill and must not stop a start it cannot judge.
+import { resolve } from 'node:path'
+import { boardLocationOf, boardsIn } from '../shared/boards'
+import { mainCheckoutOf, repositoryRootOf } from '../shared/checkout'
+import { readConfig } from '../shared/config'
+import { isRecord } from '../shared/json'
+import { laneStartsOf, missingRowReason } from './decision'
+
+/** The reasons to refuse the call; none outside the main checkout, without a board location or on any failure. */
+const reasonsOf = (command: string, cwd: string): string[] => {
+  try {
+    const lanes = laneStartsOf(command)
+    if (lanes.length === 0) return []
+    const main = mainCheckoutOf(cwd)
+    if (resolve(repositoryRootOf(cwd)) !== resolve(main)) return []
+    const location = boardLocationOf(readConfig([main]))
+    if (location === null) return []
+    const boards = boardsIn(main, location).map(({ text }) => text)
+    return lanes.flatMap((lane) => missingRowReason(lane, boards) ?? [])
+  } catch {
+    return []
+  }
+}
+
+const input: unknown = await Bun.stdin.json().catch(() => null)
+const toolInput = isRecord(input) ? input.tool_input : undefined
+const command = isRecord(toolInput) && typeof toolInput.command === 'string' ? toolInput.command : ''
+const cwd = isRecord(input) && typeof input.cwd === 'string' ? input.cwd : process.cwd()
+const [reason] = command === '' ? [] : reasonsOf(command, cwd)
+if (reason !== undefined) {
+  console.error(reason)
+  process.exit(2)
+}

package/kit/hooks/hooks/merge-guard/always-ask.ts

@@ -1,5 +1,5 @@
 /** Workflows and the actions they run. */
-const WORKFLOW_PATHS: readonly string[] = ['.github/**']
+export const WORKFLOW_PATHS: readonly string[] = ['.github/**']
 
 /** Migrations, in a `migrations` folder or as SQL in a `drizzle` folder. */
 export const MIGRATION_PATHS: readonly string[] = ['**/migrations/**', '**/drizzle/*.sql']
@@ -11,7 +11,7 @@ export const ENV_PATHS: readonly string[] = ['**/.env*', '**/*.env', '**/.dev.va
  * The guards and what runs before them: the project's hooks and settings, the jackherd config, git hooks and
  * `bunfig.toml`, whose `preload` runs before every hook (they start in the project root, so only the root one).
  */
-const GUARD_PATHS: readonly string[] = [
+export const GUARD_PATHS: readonly string[] = [
   '.claude/hooks/**',
   '.claude/settings*.json',
   '.jackherd/**',

package/kit/hooks/hooks/merge-guard/approval.ts

@@ -9,16 +9,30 @@
 import { type DialogAnswer, dialogAnswers } from '../shared/dialog-answers'
 import { isFresh } from '../shared/fresh'
 
+/** A branch the user approved, with the change they saw: the first characters of its `git patch-id --verbatim`. */
+export type ApprovedChange = { branch: string; change: string }
+
 const BRANCH_MENTION = /\bBranch `([^`]*)`/g
+/** The change right after the branch, as ``Branch `name` @<patch id>``. */
+const CHANGE_MENTION = /\bBranch `[^`]*` @([0-9a-f]{7,40})\b/g
 
 /** A branch name as git takes it from a shell word: no leading dash, no space, no `..`, no shell character. */
 const BRANCH_NAME = /^(?![-/.])(?!.*(?:\.\.|\/\/|@\{))[A-Za-z0-9._/-]+$/
 
-/** The one branch a question names as ``Branch `name` ``; a question that names none or several approves none. */
-const namedBranch = (question: string): string | undefined => {
-  const names = new Set([...question.matchAll(BRANCH_MENTION)].map(([, name]) => name))
-  const [only] = names
-  return names.size === 1 && BRANCH_NAME.test(only) ? only : undefined
+const onlyOf = (values: string[]): string | undefined => {
+  const distinct = new Set(values)
+  const [only] = distinct
+  return distinct.size === 1 ? only : undefined
+}
+
+/**
+ * The one branch a question names as ``Branch `name` ``, with the one change it names after it; a question that names
+ * none or several of either approves none.
+ */
+const namedChange = (question: string): ApprovedChange | undefined => {
+  const branch = onlyOf([...question.matchAll(BRANCH_MENTION)].map(([, name]) => name))
+  const change = onlyOf([...question.matchAll(CHANGE_MENTION)].map(([, id]) => id))
+  return branch !== undefined && change !== undefined && BRANCH_NAME.test(branch) ? { branch, change } : undefined
 }
 
 const approves = (answer: DialogAnswer, label: string): boolean => answer.answer === label && answer.offered.includes(label)
@@ -33,12 +47,10 @@ export type ApprovalQuery = {
   windowMinutes: number
 }
 
-/** The branches whose question the user answered with `label` within the window. */
-export const approvedBranches = ({ entries, label, now, windowMinutes }: ApprovalQuery): Set<string> => {
-  if (label === '') return new Set()
-  return new Set(
-    dialogAnswers(entries)
-      .filter((answer) => approves(answer, label) && isFresh(answer.answeredAt, now, windowMinutes))
-      .flatMap((answer) => namedBranch(answer.question) ?? []),
-  )
+/** The branches and changes whose question the user answered with `label` within the window. */
+export const approvedChanges = ({ entries, label, now, windowMinutes }: ApprovalQuery): ApprovedChange[] => {
+  if (label === '') return []
+  return dialogAnswers(entries)
+    .filter((answer) => approves(answer, label) && isFresh(answer.answeredAt, now, windowMinutes))
+    .flatMap((answer) => namedChange(answer.question) ?? [])
 }

package/kit/hooks/hooks/merge-guard/change-id.ts

@@ -0,0 +1,34 @@
+/**
+ * The change a pull request carries, as one id: the `git patch-id --verbatim` of its diff, as GitHub serves it. The
+ * coordinator writes the same id of the staged change into the self-merge question, so the approval holds for the
+ * change the user saw: a push that alters the diff alters the id, a rebase without a conflict keeps it.
+ */
+import { runGh } from './gh'
+
+const PATCH_ID_TIMEOUT_MS = 4000
+const PATCH_ID = /^([0-9a-f]{40}) /
+
+/** The patch id from the first line `git patch-id` prints, `<patch id> <commit>`; nothing for an empty diff. */
+export const parsePatchId = (stdout: string): string | undefined => stdout.match(PATCH_ID)?.[1]
+
+/** Whether the change the question named is this one: the question names the first characters. */
+export const isSameChange = (named: string, patchId: string | undefined): boolean =>
+  patchId !== undefined && patchId.startsWith(named)
+
+const patchIdOf = (diff: string, directory: string): string | undefined => {
+  // --verbatim keeps whitespace: an indentation pushed after the approval changes a workflow, so it changes the id
+  const result = Bun.spawnSync(['git', 'patch-id', '--verbatim'], {
+    cwd: directory,
+    stdin: new TextEncoder().encode(diff),
+    timeout: PATCH_ID_TIMEOUT_MS,
+    stdout: 'pipe',
+    stderr: 'ignore',
+  })
+  return result.exitCode === 0 ? parsePatchId(result.stdout.toString()) : undefined
+}
+
+/** The patch id of pull request <number>'s diff (`gh pr diff`); any failure, a diff too large for GitHub too, answers nothing. */
+export const changeIdOf = (pullRequest: number, directory: string): string | undefined => {
+  const diff = runGh(['pr', 'diff', String(pullRequest)], directory)
+  return diff === undefined ? undefined : patchIdOf(diff, directory)
+}