jackherd 1.9.0 → 1.10.0

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

@@ -1,168 +0,0 @@
-/**
- * Whether the user's approval of a plan lifts the question for the merge of a pull request: it merges into the base
- * branch, its checks passed, its head contains the base, the pull request comes from a lane whose rows link exactly
- * that plan, the plan still has an open phase, no file matches a path that always asks, none is a package.json and
- * none the CHANGELOG.md of a published package, the newest answer to a plan question naming it approved it, and the
- * plan gained no phase and no undecided task since that answer. Everything is read from the base branch and from
- * GitHub, never from the pull request's own files, and every doubt answers "no", so the guard asks as before. Only a
- * plain `gh pr merge <number>` gets this far.
- */
-import type { LanePlans } from '../shared/board-lanes'
-import { hasOpenPhase } from '../shared/plan-open-phases'
-import { isRecord } from '../shared/json'
-import type { MergeNote } from './decision'
-import { isPlainPath } from './plain-path'
-import { type NewTask, newPhasesSince, newTasksSince } from './plan-growth'
-
-/** The label the user picked in a plan question and when; read from the transcript, not from the pointer. */
-export type PlanAnswer = { answer: string; answeredAt: number }
-
-/** Where the facts come from; each is asked only once the steps before it said yes. */
-export type PlanApprovalSources = {
-  /** Whether GitHub can merge the head commit and its checks passed, the required ones among them. */
-  checksPassed: (requiredChecks: readonly string[] | undefined) => boolean
-  /** Whether the head commit contains the base commit plan approval reads. */
-  containsBase: (headCommit: string) => boolean
-  /** The files of the pull request as GitHub lists them, renames with their old name; undefined when not complete. */
-  files: () => readonly string[] | undefined
-  /** The texts of these paths at the base branch; null for a path it does not have. */
-  readAtBase: (paths: readonly string[]) => ReadonlyMap<string, string | null>
-  /** The lane whose worktree has the branch checked out. */
-  laneOfBranch: (branch: string) => string | undefined
-  /** The lane's rows in each board at the base branch that has any. */
-  lanePlans: (lane: string) => LanePlans[]
-  /** The answers to the plan questions naming this plan, each backed by its dialog in a transcript. */
-  answers: (plan: string) => PlanAnswer[]
-  /** The plan as the base held it at the time of the answer; undefined when it held none then or it is unreadable. */
-  readAtCommitBefore: (plan: string, answeredAt: number) => string | undefined
-}
-
-export type PlanApprovalQuery = {
-  /** The pull request as GitHub names it: its head branch and commit, and the branch it merges into. */
-  pullRequest: { branch: string; headCommit: string; baseBranch: string }
-  /** The exact option label that approves a plan. */
-  label: string
-  /** The time of the check, in milliseconds. */
-  now: number
-  /** The paths that always ask, the base branch, and the checks that must have passed (undefined: every one listed). */
-  settings: { exceptPaths: readonly string[]; baseBranch: string; requiredChecks: readonly string[] | undefined }
-}
-
-/** `true` lifts the question; `false` asks as before; a note asks and says why, for a plan that grew since its approval. */
-export type PlanVerdict = boolean | MergeNote
-
-const MANIFEST = 'package.json'
-/** How many new tasks a note names before it only counts the rest. */
-const NAMED_TASKS = 5
-const TASK_LENGTH = 80
-const CHANGELOG = 'changelog.md'
-
-const directoryOf = (file: string): string => file.slice(0, Math.max(file.lastIndexOf('/'), 0))
-
-/** In lower case, as a case-insensitive file system would write it. */
-const fileName = (file: string): string => file.slice(file.lastIndexOf('/') + 1).toLowerCase()
-
-const manifestOf = (directory: string): string => (directory === '' ? MANIFEST : `${directory}/${MANIFEST}`)
-
-/**
- * Compared in lower case: on a case-insensitive file system git writes `.Claude/x` into the existing `.claude/`, so a
- * pattern must not miss it. Folding only ever adds a question.
- */
-const matchesAny = (files: readonly string[], patterns: readonly string[]): boolean => {
-  const globs = patterns.map((pattern) => new Bun.Glob(pattern.toLowerCase()))
-  return files.some((file) => globs.some((glob) => glob.match(file.toLowerCase())))
-}
-
-/** The manifests of the packages whose CHANGELOG.md the pull request changes. */
-const changelogManifests = (files: readonly string[]): string[] => [
-  ...new Set(files.filter((file) => fileName(file) === CHANGELOG).map((file) => manifestOf(directoryOf(file)))),
-]
-
-/** A package is private only when its manifest at the base says `"private": true`; a missing or broken one is published. */
-const isPrivate = (manifest: string | null | undefined): boolean => {
-  try {
-    const parsed: unknown = JSON.parse(manifest ?? '')
-    return isRecord(parsed) && parsed.private === true
-  } catch {
-    return false
-  }
-}
-
-/** The one plan the lane's open rows link across the boards; none or several gives none. */
-const onlyPlanOf = (rows: readonly LanePlans[]): string | undefined => {
-  const plans = new Set(rows.filter(({ closed }) => !closed).flatMap(({ plans }) => plans))
-  const [only] = plans
-  return plans.size === 1 ? only : undefined
-}
-
-/**
- * When the user approved the plan: the time of the newest answers not from the future, when every one of them is the
- * label. Two answers at the same time (two questions in one dialog) approve only together.
- */
-const approvedAt = (answers: readonly PlanAnswer[], label: string, now: number): number | undefined => {
-  const past = answers.filter(({ answeredAt }) => answeredAt <= now)
-  if (past.length === 0) return undefined
-  const newest = Math.max(...past.map(({ answeredAt }) => answeredAt))
-  const atNewest = past.filter(({ answeredAt }) => answeredAt === newest)
-  return atNewest.every(({ answer }) => answer === label) ? newest : undefined
-}
-
-const shortened = (task: string): string => (task.length > TASK_LENGTH ? `${task.slice(0, TASK_LENGTH - 1)}…` : task)
-
-const tasksNote = (tasks: readonly NewTask[]): string => {
-  const named = tasks.slice(0, NAMED_TASKS).map(({ phase, task }) => `P${phase} "${shortened(task)}"`)
-  const rest = tasks.length > NAMED_TASKS ? ` and ${tasks.length - NAMED_TASKS} more` : ''
-  return `${tasks.length} new tasks: ${named.join(', ')}${rest}`
-}
-
-/** Why the approval no longer covers the plan: the phases and the undecided tasks it gained; undefined when none. */
-const growthNote = (plan: string, approvedText: string, currentText: string): string | undefined => {
-  const phases = newPhasesSince(approvedText, currentText)
-  const tasks = newTasksSince(approvedText, currentText)
-  const parts = [
-    ...(phases.length > 0 ? [`new phases: ${phases.map((phase) => `"${phase}"`).join(', ')}`] : []),
-    ...(tasks.length > 0 ? [tasksNote(tasks)] : []),
-  ]
-  return parts.length === 0 ? undefined : `Plan \`${plan}\` gained since the user's approval ${parts.join('; ')}.`
-}
-
-/**
- * No file of the pull request matches a path that always asks or is a package.json (private or not: it can drop
- * `"private"` or add a dependency), and none is the changelog of a package the base does not call private.
- */
-const changesOnlyOrdinaryFiles = (files: readonly string[], exceptPaths: readonly string[], sources: PlanApprovalSources) => {
-  if (files.length === 0 || !files.every(isPlainPath) || matchesAny(files, exceptPaths)) return false
-  if (files.some((file) => fileName(file) === MANIFEST)) return false
-  const manifests = changelogManifests(files)
-  if (manifests.length === 0) return true
-  const texts = sources.readAtBase(manifests)
-  return manifests.every((manifest) => isPrivate(texts.get(manifest)))
-}
-
-/** The plan of the branch's lane and its text at the base, while that plan has an open phase there. */
-const openPlanOf = (branch: string, sources: PlanApprovalSources): { plan: string; text: string } | undefined => {
-  const lane = sources.laneOfBranch(branch)
-  const plan = lane === undefined ? undefined : onlyPlanOf(sources.lanePlans(lane))
-  if (plan === undefined) return undefined
-  const text = sources.readAtBase([plan]).get(plan)
-  return typeof text === 'string' && hasOpenPhase(text) ? { plan, text } : undefined
-}
-
-/** The pull request merges into the base, the head contains it, and its checks passed. */
-const isTestedAgainstBase = ({ pullRequest, settings }: PlanApprovalQuery, sources: PlanApprovalSources): boolean =>
-  pullRequest.baseBranch === settings.baseBranch &&
-  sources.checksPassed(settings.requiredChecks) &&
-  sources.containsBase(pullRequest.headCommit)
-
-export const isPlanApproved = (query: PlanApprovalQuery, sources: PlanApprovalSources): PlanVerdict => {
-  if (!isTestedAgainstBase(query, sources)) return false
-  const files = sources.files()
-  if (files === undefined || !changesOnlyOrdinaryFiles(files, query.settings.exceptPaths, sources)) return false
-  const open = openPlanOf(query.pullRequest.branch, sources)
-  const answeredAt = open === undefined ? undefined : approvedAt(sources.answers(open.plan), query.label, query.now)
-  if (open === undefined || answeredAt === undefined) return false
-  const approvedText = sources.readAtCommitBefore(open.plan, answeredAt)
-  if (approvedText === undefined) return false
-  const note = growthNote(open.plan, approvedText, open.text)
-  return note === undefined ? true : { note }
-}

package/kit/hooks/hooks/merge-guard/plan-growth.ts

@@ -1,40 +0,0 @@
-/**
- * What a plan gained since the user approved it: phases, and tasks in the phases they already saw. Both compare the
- * text of the approved plan with the plan at the base, whatever the boxes say, so ticking a task is no growth.
- */
-import { phaseBlocksOf, taskOf } from '../shared/plan-open-phases'
-
-/** A task of a phase that was there at the approval, which the approved plan did not hold. */
-export type NewTask = { phase: string; task: string }
-
-/** A task the user decided, marked `(User <date> …)` with `DD.MM.` or `YYYY-MM-DD`; the user already saw it. */
-const USER_DECIDED = /\(User (?:\d{1,2}\.\d{1,2}\.|\d{4}-\d{2}-\d{2})/
-
-const tasksOf = (lines: readonly string[]): string[] =>
-  lines.flatMap((line) => {
-    const task = taskOf(line)
-    return task === null ? [] : [task.text]
-  })
-
-/** The headings of the current plan's phases the approved plan does not have, by their text: a rename is new. */
-export const newPhasesSince = (approvedText: string, currentText: string): string[] => {
-  const approved = new Set(phaseBlocksOf(approvedText).map(({ heading }) => heading))
-  return phaseBlocksOf(currentText)
-    .map(({ heading }) => heading)
-    .filter((heading) => !approved.has(heading))
-}
-
-/**
- * The tasks of the current plan that the same phase of the approved plan did not hold, by their text (a rewording is
- * new), leaving out tasks the user decided and every task of a phase that is new itself.
- */
-export const newTasksSince = (approvedText: string, currentText: string): NewTask[] => {
-  const approved = new Map(phaseBlocksOf(approvedText).map(({ id, lines }) => [id, new Set(tasksOf(lines))]))
-  return phaseBlocksOf(currentText).flatMap(({ id, lines }) => {
-    const known = approved.get(id)
-    if (known === undefined) return []
-    return tasksOf(lines)
-      .filter((task) => !known.has(task) && !USER_DECIDED.test(task))
-      .map((task) => ({ phase: id, task }))
-  })
-}

package/kit/hooks/hooks/merge-guard/plan-pointers.ts

@@ -1,194 +0,0 @@
-/**
- * A plan approval outlives the session it was given in: the `PostToolUse` hook on `AskUserQuestion` leaves a pointer
- * (plan, transcript file, `tool_use_id`) under `.jackherd/approvals/plans/`, and the merge guard follows it back into
- * that transcript at every merge. The pointer only says where to look; what counts is the dialog it finds there, the
- * question naming the plan and the label the user picked, so a pointer an agent writes itself gains nothing.
- *
- * The limit, as for the branch approval: an agent that runs as the user could still write a transcript file. This
- * guards against a mistake, not against an agent that sets out to get around it.
- */
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, isAbsolute, join } from 'node:path'
-import { ASK_USER_QUESTION_TOOL, dialogAnswers } from '../shared/dialog-answers'
-import { realPathOrNull } from '../shared/files'
-import { isRecord } from '../shared/json'
-import { ensurePrivateDirectory, PRIVATE_FILE } from '../shared/private-directory'
-import type { PlanAnswer } from './plan-approval'
-
-/**
- * `answers`: per plan, the answer the hook input reported, null where it reported none. An approval still needs its
- * dialog in the transcript; any other answer ends the approval at `recordedAt` without one, since it only adds a question.
- */
-export type PlanPointer = {
-  toolUseId: string
-  transcript: string
-  plans: string[]
-  answers: Record<string, string | null>
-  recordedAt: number
-}
-
-export type PlanAnswerQuery = {
-  /** The pointer directory, `.jackherd/approvals/plans` of the main checkout. */
-  directory: string
-  /** The transcript of the session that merges: only transcripts beside it, of the same project, are read. */
-  currentTranscript: string | undefined
-  plan: string
-  /** The label that approves a plan; a pointer with any other answer is a revocation. */
-  label: string
-}
-
-const PLAN_MENTION = /\bPlan `([^`]*)`/g
-const PLAN_PATH = /^[A-Za-z0-9_./-]+\.md$/
-const TOOL_USE_ID = /^[A-Za-z0-9_-]{1,128}$/
-const POINTER_FILE = /^([A-Za-z0-9_-]{1,128})\.json$/
-const TRANSCRIPT_FILE = /\.jsonl$/
-
-/** A plan path as a board links it: a relative markdown file, no empty, `.` or `..` segment. */
-const isPlanPath = (path: string): boolean =>
-  PLAN_PATH.test(path) && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
-
-const isTranscriptPath = (value: unknown): value is string =>
-  typeof value === 'string' && isAbsolute(value) && TRANSCRIPT_FILE.test(value)
-
-const isToolUseId = (value: unknown): value is string => typeof value === 'string' && TOOL_USE_ID.test(value)
-
-/** The one plan a question names as ``Plan `path` ``; a question that names none or several names none. */
-export const namedPlan = (question: string): string | undefined => {
-  const plans = new Set([...question.matchAll(PLAN_MENTION)].map(([, path]) => path))
-  const [only] = plans
-  return plans.size === 1 && isPlanPath(only) ? only : undefined
-}
-
-type PlanAsked = { plan: string; question: string }
-
-/** The plans of the single-choice questions that name one and offer one of the plan labels, with the question text. */
-const plansAsked = (input: unknown, labels: readonly string[]): PlanAsked[] => {
-  const questions = isRecord(input) && Array.isArray(input.questions) ? input.questions.filter(isRecord) : []
-  return questions.flatMap((question) => {
-    const options = question.multiSelect !== true && Array.isArray(question.options) ? question.options : []
-    const offersLabel = options.some((option) => isRecord(option) && labels.includes(String(option.label)))
-    const text = typeof question.question === 'string' ? question.question : ''
-    const plan = namedPlan(text)
-    return offersLabel && plan !== undefined ? [{ plan, question: text }] : []
-  })
-}
-
-/** The answer the hook input reports for a question, keyed by its text; null when it reports none. */
-const reportedAnswer = (response: unknown, question: string): string | null => {
-  const answers = isRecord(response) && isRecord(response.answers) ? response.answers : {}
-  const answer = answers[question]
-  return typeof answer === 'string' ? answer : null
-}
-
-/** The pointer for a `PostToolUse` input of an `AskUserQuestion` call that asked about a plan; undefined for any other. */
-export const pointerOf = (input: unknown, labels: readonly string[], now: number): PlanPointer | undefined => {
-  if (!isRecord(input) || input.tool_name !== ASK_USER_QUESTION_TOOL) return undefined
-  const { tool_use_id: toolUseId, transcript_path: transcript } = input
-  if (!isToolUseId(toolUseId) || !isTranscriptPath(transcript)) return undefined
-  const asked = plansAsked(input.tool_input, labels.filter(Boolean))
-  if (asked.length === 0) return undefined
-  const answers = Object.fromEntries(asked.map(({ plan, question }) => [plan, reportedAnswer(input.tool_response, question)]))
-  return { toolUseId, transcript, plans: [...new Set(asked.map(({ plan }) => plan))], answers, recordedAt: now }
-}
-
-/** The lines of the file that contain `needle`: a transcript runs to hundreds of megabytes, and only these get parsed. */
-const linesContaining = (text: Buffer, needle: string): string[] => {
-  const lines: string[] = []
-  for (let at = text.indexOf(needle); at !== -1; ) {
-    const start = text.lastIndexOf('\n', at) + 1
-    const newline = text.indexOf('\n', at)
-    const end = newline === -1 ? text.length : newline
-    lines.push(text.subarray(start, end).toString('utf8'))
-    at = newline === -1 ? -1 : text.indexOf(needle, end)
-  }
-  return lines
-}
-
-const parsedLines = (lines: string[]): unknown[] =>
-  lines.flatMap((line) => {
-    try {
-      return [JSON.parse(line)]
-    } catch {
-      return []
-    }
-  })
-
-/** The answers of the dialog `toolUseId` in the transcript to questions naming `plan`, free text included. */
-const answersInTranscript = (text: Buffer, toolUseId: string, plan: string): PlanAnswer[] =>
-  dialogAnswers(parsedLines(linesContaining(text, JSON.stringify(toolUseId))))
-    .filter(({ question }) => namedPlan(question) === plan)
-    .map(({ answer, answeredAt }) => ({ answer, answeredAt }))
-
-/** A pointer whose reported answer is not the label ends the approval when it was recorded; no transcript needed. */
-const revocationOf = (pointer: PlanPointer, plan: string): PlanAnswer => ({
-  answer: pointer.answers[plan] ?? '',
-  answeredAt: pointer.recordedAt,
-})
-
-/** The pointer directory of a main checkout, beside the approval gate's requests. */
-export const planPointersDirectory = (main: string): string => join(main, '.jackherd', 'approvals', 'plans')
-
-export const writePointer = (directory: string, pointer: PlanPointer): void => {
-  ensurePrivateDirectory(directory)
-  writeFileSync(join(directory, `${pointer.toolUseId}.json`), `${JSON.stringify(pointer)}\n`, { mode: PRIVATE_FILE })
-}
-
-const pointerIn = (directory: string, name: string): PlanPointer[] => {
-  const id = POINTER_FILE.exec(name)?.[1]
-  if (id === undefined) return []
-  try {
-    const value: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
-    if (!isRecord(value) || value.toolUseId !== id || !isTranscriptPath(value.transcript)) return []
-    const plans = Array.isArray(value.plans) ? value.plans : []
-    const valid = plans.length > 0 && plans.every((plan) => typeof plan === 'string' && isPlanPath(plan))
-    if (!valid || typeof value.recordedAt !== 'number') return []
-    const answers = isRecord(value.answers) ? value.answers : {}
-    const reported = (plan: string) => (typeof answers[plan] === 'string' ? answers[plan] : null)
-    return [{ ...(value as PlanPointer), answers: Object.fromEntries(plans.map((plan) => [plan, reported(plan)])) }]
-  } catch {
-    return []
-  }
-}
-
-/** Every file of the directory that parses as a pointer named after its own id; none for a missing directory. */
-export const readPointers = (directory: string): PlanPointer[] => {
-  try {
-    return readdirSync(directory).flatMap((name) => pointerIn(directory, name))
-  } catch {
-    return []
-  }
-}
-
-const readOrNull = (path: string): Buffer | null => {
-  try {
-    return readFileSync(path)
-  } catch {
-    return null
-  }
-}
-
-/** The answers a pointer's transcript holds for `plan`, when that transcript lies beside the current one. */
-const backedAnswers = (pointer: PlanPointer, plan: string, project: string, texts: Map<string, Buffer | null>) => {
-  const path = realPathOrNull(pointer.transcript)
-  if (path === null || dirname(path) !== project) return []
-  if (!texts.has(path)) texts.set(path, readOrNull(path))
-  const text = texts.get(path)
-  return text ? answersInTranscript(text, pointer.toolUseId, plan) : []
-}
-
-/**
- * The answers to the plan questions naming `plan`. A pointer that reported the approval label counts only with its
- * dialog in a transcript beside the current one (Claude Code keeps a project's sessions side by side); a pointer that
- * reported anything else, free text or nothing included, is a revocation and counts as it stands.
- */
-export const planAnswers = ({ directory, currentTranscript, plan, label }: PlanAnswerQuery): PlanAnswer[] => {
-  const pointers = readPointers(directory).filter((pointer) => pointer.plans.includes(plan))
-  const revocations = pointers.filter((pointer) => pointer.answers[plan] !== label).map((pointer) => revocationOf(pointer, plan))
-  const project = currentTranscript === undefined ? null : realPathOrNull(dirname(currentTranscript))
-  if (project === null) return revocations
-  const texts = new Map<string, Buffer | null>()
-  const approvals = pointers
-    .filter((pointer) => pointer.answers[plan] === label)
-    .flatMap((pointer) => backedAnswers(pointer, plan, project, texts))
-  return [...approvals, ...revocations]
-}

package/kit/hooks/hooks/shared/command-text-runners.ts

@@ -1,71 +0,0 @@
-import { isProgramPosition, programName } from './program-position'
-import type { SimpleCommand, Word } from './shell'
-
-/** Programs that run text they are given or read from elsewhere, so no parse of the shell sees what runs. */
-const OPAQUE_RUNNERS = new Set([
-  'xargs',
-  'find',
-  'trap',
-  'coproc',
-  'repeat',
-  'script',
-  'su',
-  'flock',
-  'ssh',
-  'parallel',
-  'ionice',
-  'chrt',
-  'taskset',
-  'strace',
-  'unbuffer',
-  'chroot',
-  'runuser',
-  'systemd-run',
-  'nsenter',
-  'unshare',
-  'firejail',
-  'pkexec',
-  'entr',
-  'watchexec',
-  'busybox',
-  'watch',
-  'osascript',
-])
-
-/** Package runners whose `-c`/`--call` hands a command string to a shell: `npx -c`, `npm exec -c`, `pnpm dlx -c`. */
-const PACKAGE_RUNNERS = new Set(['npx', 'npm', 'pnpm', 'yarn'])
-const CALL_OPTION = /^(-c|--call)(=|$)/
-const AWK_PROGRAMS = new Set(['awk', 'gawk', 'mawk', 'nawk'])
-/** An awk program that starts a command: `system(…)`, a pipe into or out of `getline`, `print … | "cmd"`. */
-const AWK_RUNS_COMMAND = /\bsystem\s*\(|\|\s*getline|\|&|print[^;}]*\|/
-/** sed's `e` command, alone or after an address: `1e cmd`, `/x/e cmd`, `;e`. */
-const SED_EXECUTE_COMMAND = /(^|[\s;{}!=\d$/])e(\s|;|$)/
-/** sed's `s///e` flag, which runs the pattern space as a command. */
-const SED_EXECUTE_FLAG = /^\s*s(.)(?:\\.|(?!\1).)*\1(?:\\.|(?!\1).)*\1[^;\s}]*e/
-
-const sedRunsCommand = (rest: Word[]): boolean =>
-  rest.some(
-    ({ value }) => SED_EXECUTE_COMMAND.test(value) || value.split(/[;\n]/).some((piece) => SED_EXECUTE_FLAG.test(piece)),
-  )
-
-const runsCommandText = (name: string, rest: Word[]): boolean =>
-  OPAQUE_RUNNERS.has(name) ||
-  (PACKAGE_RUNNERS.has(name) && rest.some(({ value }) => CALL_OPTION.test(value))) ||
-  (name === 'sed' && sedRunsCommand(rest)) ||
-  (AWK_PROGRAMS.has(name) && rest.some(({ value }) => AWK_RUNS_COMMAND.test(value)))
-
-/**
- * The index of a program that runs command text it is given (`watch '…'`, `script -qc '…'`, `npx -c '…'`, sed's `e`,
- * awk's `system()`), anywhere a program can stand; -1 when there is none.
- */
-export const commandTextRunnerIndex = (words: SimpleCommand): number =>
-  words.findIndex(
-    (word, index) => isProgramPosition(words, index) && runsCommandText(programName(word), words.slice(index + 1)),
-  )
-
-/**
- * The text a mention search reads: the script as written and, beside it, every word as the shell decodes it, so a word
- * split by quotes (`pu""sh`) or written in `$'…'` escapes (`pu\x73h`) is found too.
- */
-export const searchableText = (script: string, commands: SimpleCommand[]): string =>
-  [script, ...commands.map((words) => words.map(({ value }) => value).join(' '))].join('\n')

package/kit/hooks/hooks/shared/plan-open-phases.ts

@@ -1,114 +0,0 @@
-/**
- * Whether a plan still has an open phase, read the way the herd reads phases (`parsePlanPhases` in the package),
- * which a hook cannot import. A test compares both on the repository's real plans.
- */
-
-/** A task of a phase, a checkbox or a row with a ⬜/✅ cell: whether it is open, and its text without the state. */
-export type PlanTask = { open: boolean; text: string }
-
-type Phase = { id: string; items: boolean[]; deferredOpen: boolean; pointer?: string }
-
-/** A phase's id, its heading without the leading hashes, and its lines up to the next heading that ends it. */
-export type PhaseBlock = { id: string; heading: string; lines: string[] }
-
-const PHASE_HEADING = /^###\s+Phase\s+(\d+[a-z]?)\b/i
-/** `## 10 — title`, and `## P15 — title` as a board names the phase. */
-const NUMBERED_SECTION = /^##\s+P?(\d+[a-z]?)\s*[—–:-]\s*(.*)$/
-const PHASE_END = /^#{1,3}\s/
-const SECTION_HEADING = /^##\s+(.+?)\s*$/
-const TOP_HEADING = /^#\s/
-const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/
-const DEFERRED_TO = /\s→\s*P(\d+[a-z]?)\s*$/i
-const SECTION_POINTER = /`##\s+([^`]+?)\s*`/
-const STATUS = { done: '✅', open: '⬜' } as const
-
-const collapsed = (text: string): string => text.trim().replace(/\s+/g, ' ')
-
-/** The task a line holds, null for a line that is none. */
-export const taskOf = (line: string): PlanTask | null => {
-  const checkbox = line.match(CHECKBOX)
-  if (checkbox) return { open: checkbox[1] === ' ', text: collapsed(checkbox[2]) }
-  const trimmed = line.trim()
-  if (!trimmed.startsWith('|')) return null
-  const cells = trimmed.replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim())
-  const status = cells.find((cell) => cell === STATUS.done || cell === STATUS.open)
-  if (status === undefined) return null
-  const text = cells.filter((cell) => cell !== STATUS.done && cell !== STATUS.open).join(' | ')
-  return { open: status === STATUS.open, text: collapsed(text) }
-}
-
-/** An item of a phase: `true` while open, `false` when done, null for a line that is none. */
-const itemOf = (line: string): boolean | null => taskOf(line)?.open ?? null
-
-/** An open checkbox moved on to another phase with `→ P<n>` at its end; it stays open, in that phase. */
-const isDeferred = (line: string, phaseId: string): boolean => {
-  const checkbox = line.match(CHECKBOX)
-  const target = checkbox?.[1] === ' ' ? checkbox[2].match(DEFERRED_TO)?.[1]?.toLowerCase() : undefined
-  return target !== undefined && target !== phaseId
-}
-
-const phaseIdOf = (line: string): string | undefined =>
-  (line.match(PHASE_HEADING) ?? line.match(NUMBERED_SECTION))?.[1]?.toLowerCase()
-
-const fileLine = (phase: Phase, line: string): void => {
-  phase.pointer ??= line.match(SECTION_POINTER)?.[1]
-  if (isDeferred(line, phase.id)) {
-    phase.deferredOpen = true
-    return
-  }
-  const item = itemOf(line)
-  if (item !== null) phase.items.push(item)
-}
-
-/** The phases of a plan as they stand, `### Phase <id>` and `## <id> — title` alike. */
-export const phaseBlocksOf = (markdown: string): PhaseBlock[] => {
-  const blocks: PhaseBlock[] = []
-  let open: PhaseBlock | null = null
-  for (const line of markdown.split('\n')) {
-    const id = phaseIdOf(line)
-    if (id !== undefined) {
-      open = { id, heading: collapsed(line.replace(/^#+/, '')), lines: [] }
-      blocks.push(open)
-    } else if (PHASE_END.test(line)) open = null
-    else open?.lines.push(line)
-  }
-  return blocks
-}
-
-const phasesOf = (markdown: string): Phase[] =>
-  phaseBlocksOf(markdown).map(({ id, lines }) => {
-    const phase: Phase = { id, items: [], deferredOpen: false }
-    for (const line of lines) fileLine(phase, line)
-    return phase
-  })
-
-/** The items of every `## ` section by heading, sub-headings included; the last of equal headings wins. */
-const sectionItems = (markdown: string): Map<string, boolean[]> => {
-  const sections = new Map<string, boolean[]>()
-  let open: boolean[] | null = null
-  for (const line of markdown.split('\n')) {
-    const heading = line.match(SECTION_HEADING)
-    if (heading) {
-      open = []
-      sections.set(heading[1], open)
-    } else if (TOP_HEADING.test(line)) open = null
-    else {
-      const item = itemOf(line)
-      if (item !== null) open?.push(item)
-    }
-  }
-  return sections
-}
-
-/**
- * True when a phase (`### Phase <id>` or `## <id> — title`) holds an open checkbox or ⬜ row, a deferred one included;
- * a phase without items of its own counts the section it points at (``Siehe `## Dokumentation` ``).
- */
-export const hasOpenPhase = (markdown: string): boolean => {
-  const phases = phasesOf(markdown)
-  if (phases.some((phase) => phase.deferredOpen || phase.items.includes(true))) return true
-  const pointed = phases.filter((phase) => phase.items.length === 0 && phase.pointer !== undefined)
-  if (pointed.length === 0) return false
-  const sections = sectionItems(markdown)
-  return pointed.some((phase) => (sections.get(phase.pointer ?? '') ?? []).includes(true))
-}