jackherd 0.0.0-stage → 1.0.0

package/src/plans/supervisor.ts

@@ -0,0 +1,124 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import { watch } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { pendingKitUpdate, VERSION_POLL_MS } from '../version/installed-version'
+import type { StartedKit } from '../version/started-kit'
+import { CHILD_MARKER, exitCodeOf, isRestartTrigger, nextStep, RESTART_DEBOUNCE_MS } from './restart-decision'
+import { TERMINAL_OFF } from './view'
+
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+const packageSourceDirectory = (): string => dirname(dirname(fileURLToPath(import.meta.url)))
+
+const entryScript = (): string => {
+  const script = process.argv[1]
+  if (!script) throw new Error('Cannot supervise the plans view: process.argv[1] is missing')
+  return script
+}
+
+const describeEnd = (code: number | null, signal: NodeJS.Signals | null): string =>
+  signal ? `signal ${signal}` : `exit ${code}`
+
+const spawnView = (scriptPath: string, args: string[]): ChildProcess =>
+  spawn(process.execPath, [scriptPath, 'plans', ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, [CHILD_MARKER]: '1' },
+  })
+
+/**
+ * Runs the live view as a child process and restarts it when the package's own source changes,
+ * so a long-lived `plans` never shows the behaviour of code that has since been edited. The child
+ * stops on SIGTERM through the handler that restores the terminal. Resolves with the exit code
+ * of a wanted end only: the child's clean exit (`q`) or a signal forwarded to it. A child that
+ * dies otherwise leaves the supervisor waiting, with the terminal restored, for the next change
+ * to `src/`, which spawns a fresh child. `kit` is the package this process loaded (null when it cannot be
+ * located, which turns the version check off). A failure to spawn the very first child resolves with 1.
+ *
+ * Meant to run once per process: the signal listeners it registers stay registered.
+ */
+export const superviseView = (
+  args: string[],
+  kit: StartedKit | null,
+  scriptPath: string = entryScript(),
+): Promise<number> =>
+  new Promise((resolveExit) => {
+    let child: ChildProcess | undefined
+    let restarting = false
+    let stopping = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let runningKit = kit
+
+    const finish = (code: number): void => {
+      clearTimeout(timer)
+      clearInterval(versionTimer)
+      watcher.close()
+      resolveExit(code)
+    }
+
+    const waitForChange = (reason: string): void => {
+      child = undefined
+      process.stdout.write(TERMINAL_OFF)
+      console.log(`plans view stopped (${reason}); waiting for the next change to src/`)
+    }
+
+    const start = (isFirst: boolean): void => {
+      const current = spawnView(scriptPath, args)
+      child = current
+
+      current.on('error', (error) => {
+        if (child !== current) return
+        if (isFirst) {
+          console.error(`plans view could not start: ${error.message}`)
+          finish(1)
+          return
+        }
+        console.error(error.message)
+        waitForChange('error')
+      })
+
+      current.on('exit', (code, signal) => {
+        if (child !== current) return
+        const context = { restarting, stopping, code, signal }
+        restarting = false
+        const actions = {
+          respawn: () => start(false),
+          exit: () => finish(exitCodeOf(code, signal)),
+          wait: () => waitForChange(describeEnd(code, signal)),
+        }
+        actions[nextStep(context)]()
+      })
+    }
+
+    const restartView = (): void => {
+      if (child) {
+        restarting = true
+        child.kill('SIGTERM')
+      } else start(false)
+    }
+
+    const watcher = watch(packageSourceDirectory(), { recursive: true }, (_event, name) => {
+      if (stopping || !name || !isRestartTrigger(name.toString())) return
+      clearTimeout(timer)
+      timer = setTimeout(restartView, RESTART_DEBOUNCE_MS)
+    })
+
+    const versionTimer = setInterval(() => {
+      const update = pendingKitUpdate(runningKit)
+      if (stopping || !update || !runningKit) return
+      runningKit = { ...runningKit, version: update.to }
+      restartView()
+    }, VERSION_POLL_MS)
+
+    start(true)
+
+    for (const signal of FORWARDED_SIGNALS) {
+      process.on(signal, () => {
+        stopping = true
+        clearTimeout(timer)
+        clearInterval(versionTimer)
+        if (child) child.kill(signal)
+        else finish(exitCodeOf(null, signal))
+      })
+    }
+  })

package/src/plans/symbols.ts

@@ -0,0 +1,54 @@
+import { AGENT_STATUS, type AgentStatus, isAgentStatus } from '../terminal/types'
+
+/** The symbols and words the plans views share: herdr's own status words, and the state of a phase. */
+export const STATUS_SYMBOL: Record<AgentStatus, string> = {
+  [AGENT_STATUS.working]: '⚡',
+  [AGENT_STATUS.blocked]: '❓',
+  [AGENT_STATUS.idle]: '⏸',
+  [AGENT_STATUS.done]: '📨',
+}
+export const NO_AGENT_SYMBOL = '·'
+export const NO_AGENT_WORD = 'no agent'
+export const UNKNOWN_SYMBOL = '•'
+
+export const statusSymbol = (agent: string | null): string => {
+  if (agent === null) return NO_AGENT_SYMBOL
+  return isAgentStatus(agent) ? STATUS_SYMBOL[agent] : UNKNOWN_SYMBOL
+}
+
+export const statusWord = (agent: string | null): string => agent ?? NO_AGENT_WORD
+
+/** Before a row that opens and closes: lanes, the notes of a lane, the planned phases, the ticked items of a phase. */
+export const CHEVRON = { closed: '▸', open: '▾' } as const
+
+export const chevronOf = (open: boolean): string => (open ? CHEVRON.open : CHEVRON.closed)
+
+export const PHASE_STATE = { missing: 'missing', empty: 'empty', all: 'all', open: 'open' } as const
+
+export type PhaseState = (typeof PHASE_STATE)[keyof typeof PHASE_STATE]
+
+/** A phase the plan lacks, one without checkboxes, one fully ticked, or one with ticks still to do. */
+export const phaseStateOf = ({
+  title,
+  done,
+  total,
+}: {
+  title: string | null
+  done: number
+  total: number
+}): PhaseState => {
+  if (title === null) return PHASE_STATE.missing
+  if (total === 0) return PHASE_STATE.empty
+  return done === total ? PHASE_STATE.all : PHASE_STATE.open
+}
+
+/** What a phase shows in place of a symbol: `0/5`, `✓ 15/15`, `–` without checkboxes, `?` when the plan lacks it. */
+export const PHASE_COUNT = { missing: '?', empty: '–', allTicked: '✓' } as const
+
+export const phaseCountOf = (phase: { title: string | null; done: number; total: number }): string => {
+  const state = phaseStateOf(phase)
+  if (state === PHASE_STATE.missing) return PHASE_COUNT.missing
+  if (state === PHASE_STATE.empty) return PHASE_COUNT.empty
+  const count = `${phase.done}/${phase.total}`
+  return state === PHASE_STATE.all ? `${PHASE_COUNT.allTicked} ${count}` : count
+}

package/src/plans/texts.ts

@@ -0,0 +1,103 @@
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { CHECKS, type ChecksState } from './pull-requests'
+import { NO_AGENT_WORD, PHASE_COUNT } from './symbols'
+
+/**
+ * Everything the plans view says in words but the watcher's badges. The view is English whatever language the
+ * project answers in; plan and phase titles come from the plans as written, and the status words are herdr's own terms.
+ */
+export type PlanTexts = {
+  noAgent: string
+  noPlan: string
+  noWorktree: string
+  noRow: string
+  notInPlan: string
+  noCheckboxes: string
+  ticked: string
+  tickedUnmerged: string
+  tickedSummary: (count: number) => string
+  notesHidden: (count: number) => string
+  notesShown: (count: number) => string
+  draft: string
+  privateLink: string
+  planned: (phases: number, plans: number) => string
+  following: (groups: string) => string
+  checks: Record<ChecksState, string>
+  hint: string
+  legend: string[]
+}
+
+/**
+ * The words of the watcher's badges and of the header notice when they are missing, in the project's response
+ * language (D96): they report on the lane's pull request as the watcher's own messages do.
+ */
+export type BadgeTexts = {
+  preview: string
+  /** The feedback since the last push, without ignored authors. */
+  feedback: (count: number) => string
+  changesRequested: string
+  watcherOff: string
+  stale: (minutes: number) => string
+}
+
+export const BADGE_TEXTS: Record<PlanLanguage, BadgeTexts> = {
+  [PLAN_LANGUAGE.de]: {
+    preview: '🌐 preview',
+    feedback: (count) => `💬 ${count} neu`,
+    changesRequested: '✋ Änderungen verlangt',
+    watcherOff: 'Watcher aus',
+    stale: (minutes) => `Stand ${minutes} min alt`,
+  },
+  [PLAN_LANGUAGE.en]: {
+    preview: '🌐 preview',
+    feedback: (count) => `💬 ${count} new`,
+    changesRequested: '✋ changes requested',
+    watcherOff: 'watcher off',
+    stale: (minutes) => `state ${minutes} min old`,
+  },
+}
+
+/** What the view says about a board, in the word the project calls it (`board.term`). */
+export const boardTexts = (term: string) => ({
+  missing: (glob: string) => `no ${term} under ${glob}`,
+  laneNotListed: (lane: string) => `lane "${lane}" is not in the ${term}`,
+  pageOpened: (path: string) => `${term} page opened: ${path}`,
+  pageNotOpened: (path: string, reason: string) => `${term} page written to ${path} (not opened: ${reason})`,
+  pageNotWritten: (reason: string) => `${term} page not written: ${reason}`,
+  pageNotOpenedReason: (reason: string) => `${term} page: ${reason}`,
+  notReadable: (reason: string) => `${term} not readable: ${reason}`,
+})
+
+export const TEXTS: PlanTexts = {
+  noAgent: NO_AGENT_WORD,
+  noPlan: 'no plan',
+  noWorktree: 'no worktree',
+  noRow: 'no row in lanes',
+  notInPlan: 'not in the plan',
+  noCheckboxes: 'no checkboxes',
+  ticked: 'ticked',
+  tickedUnmerged: 'ticked, not merged',
+  tickedSummary: (count) => `${count} ticked · click or a lists them`,
+  notesHidden: (count) => `${count} ${count === 1 ? 'note' : 'notes'} hidden · click or n shows them`,
+  notesShown: (count) => `${count} ${count === 1 ? 'note' : 'notes'} shown · click or n hides them`,
+  draft: 'draft · ',
+  privateLink: 'private',
+  following: (groups) => `also open · ${groups}`,
+  planned: (phases, plans) =>
+    `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
+  checks: {
+    [CHECKS.passed]: '✓ checks',
+    [CHECKS.failed]: '✗ checks',
+    [CHECKS.pending]: '… checks',
+    [CHECKS.none]: 'no checks',
+  },
+  hint: '↑↓ select  →← open  a all  n notes  s html  q quit  ? help',
+  legend: [
+    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
+    '⚡ working · ❓ blocked, waits for you · 📨 done = the agent finished its answer, not the lane · ⏸ idle · · no agent · working and blocked lanes open by themselves, → ← overrule until the status changes',
+    `n/m = m checkboxes of the phase, n ticked (the phase being worked on is yellow; ticked, not merged = all ticked in the worktree, not on the base branch yet) · ${PHASE_COUNT.allTicked} n/n all ticked · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · n shows or hides the notes of a lane · s opens every lane and plan as one HTML page · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main`,
+  ],
+}
+
+/** The mark of a running lane the board has no row for; null for a lane it lists. */
+export const laneMarkText = (lane: { unlisted?: boolean }): string | null => (lane.unlisted ? TEXTS.noRow : null)

package/src/plans/unlisted-lanes.ts

@@ -0,0 +1,45 @@
+import { isAbsolute, relative, sep } from 'node:path'
+import type { SprintLane } from '../plan-format'
+import type { LaneAgent } from '../terminal'
+
+/** A worktree with an agent that has no row in the sprint table; `name` is its directory below the worktree directory. */
+export type UnlistedLane = { name: string; agent: LaneAgent }
+
+type PlacedAgent = { lane: string; agent: LaneAgent }
+
+/** The worktree an agent runs in: the first directory below `worktreeDirectory`, null for anything outside it. */
+export const laneDirectoryOf = (cwd: string, worktreeDirectory: string): string | null => {
+  const below = relative(worktreeDirectory, cwd)
+  if (below === '' || below === '..' || below.startsWith(`..${sep}`) || isAbsolute(below)) return null
+  return below.split(sep)[0]
+}
+
+/** An unlisted lane as a sprint lane: its name and nothing else, no port, no steps. */
+export const unlistedSprintLane = (name: string): SprintLane => ({ name, port: null, steps: [], closed: false })
+
+const placed = (agents: readonly LaneAgent[], worktreeDirectory: string): PlacedAgent[] =>
+  agents.flatMap((agent) => {
+    const lane = agent.cwd ? laneDirectoryOf(agent.cwd, worktreeDirectory) : null
+    return lane === null ? [] : [{ lane, agent }]
+  })
+
+/**
+ * The lanes that run but are missing from the sprint table: one per worktree below `worktreeDirectory` with an
+ * agent in it. A worktree counts as listed when the table names it, or names any agent running in it. The first
+ * agent of a worktree stands for it; the lanes come in name order.
+ */
+export const unlistedLanes = (
+  agents: readonly LaneAgent[],
+  listed: ReadonlySet<string>,
+  worktreeDirectory: string,
+): UnlistedLane[] => {
+  const inWorktrees = placed(agents, worktreeDirectory)
+  const listedWorktrees = new Set(
+    inWorktrees.filter(({ lane, agent }) => listed.has(lane) || listed.has(agent.name)).map(({ lane }) => lane),
+  )
+  const byLane = new Map<string, LaneAgent>()
+  for (const { lane, agent } of inWorktrees) {
+    if (!listedWorktrees.has(lane) && !byLane.has(lane)) byLane.set(lane, agent)
+  }
+  return [...byLane].sort(([left], [right]) => left.localeCompare(right)).map(([name, agent]) => ({ name, agent }))
+}

package/src/plans/view.ts

@@ -0,0 +1,68 @@
+import { fit, plainText } from '../terminal/text'
+import { renderSelected, type Screen } from './layout'
+import type { Options } from './options'
+import { laneSelection, overviewSelection, type Selection } from './selection'
+import type { Snapshot } from './snapshot'
+
+const DEFAULT_WIDTH = 100
+const CURSOR_HOME = '\x1b[H'
+const CLEAR_LINE_END = '\x1b[K'
+const CLEAR_BELOW = '\x1b[J'
+
+export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h'
+export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l'
+
+/** One column short of the pane: a line filling the last column makes some terminals wrap it. */
+export const paneWidth = (): number => (process.stdout.columns ?? (Number(process.env.COLUMNS) || DEFAULT_WIDTH)) - 1
+
+const paneRows = (): number => process.stdout.rows ?? Number.MAX_SAFE_INTEGER
+
+export const bodyRows = (screen: Screen): number =>
+  Math.max(paneRows() - screen.header.length - screen.footer.length, 1)
+
+export const clockOf = (locale: string): string => new Date().toLocaleTimeString(locale)
+
+export const renderSnapshot = (
+  snapshot: Snapshot,
+  selection: Selection,
+  errors: string[],
+  width: number,
+  locale: string,
+): Screen => {
+  const screen = renderSelected(
+    {
+      title: snapshot.title,
+      time: clockOf(locale),
+      lanes: snapshot.views,
+      planned: snapshot.planned,
+      watch: snapshot.watch,
+      language: snapshot.language,
+    },
+    selection,
+    width,
+  )
+  return { ...screen, footer: [...errors.map((error) => fit(error, width)), ...screen.footer] }
+}
+
+export const startSelection = (snapshot: Snapshot, options: Options): Selection =>
+  options.lane
+    ? laneSelection(snapshot.views[0]?.progress, snapshot.views[0]?.status.agent ?? null)
+    : overviewSelection()
+
+/** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
+export const draw = (screen: Screen, top: number): void => {
+  const width = paneWidth()
+  const rows = bodyRows(screen)
+  const body = screen.body.lines.slice(top, top + rows)
+  const padding = Array.from({ length: Math.max(rows - body.length, 0) }, () => '')
+  const lines = [...screen.header, ...body, ...padding, ...screen.footer]
+  process.stdout.write(
+    `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`,
+  )
+}
+
+/** One frame as text; ANSI styling is dropped when stdout is not a terminal. */
+export const frameText = (screen: Screen, isTerminal: boolean): string => {
+  const lines = [...screen.header, ...screen.body.lines, ...screen.footer]
+  return (isTerminal ? lines : lines.map(plainText)).join('\n')
+}

package/src/plans/worked-phases.ts

@@ -0,0 +1,53 @@
+import {
+  type LaneProgress,
+  laneProgress,
+  PHASE_ID_PREFIX,
+  type PlanStep,
+  type PlansByHref,
+  type SprintLane,
+} from '../plan-format'
+import { belongsToLane } from './phase-source'
+
+/**
+ * The phases of a plan the lane worked on in its worktree although none of its rows names them, in plan order: touched
+ * by `mergePlanPhases` and with at least one tick, so a draft the lane only wrote down does not become its current phase.
+ */
+const workedIds = (lane: SprintLane, plans: PlansByHref, href: string): string[] => {
+  const named = lane.steps.filter((step) => step.planHref === href).flatMap((step) => step.phaseIds)
+  return (plans[href] ?? [])
+    .filter((phase) => phase.touched && phase.items.some((item) => item.done) && !belongsToLane(phase.id, named))
+    .map((phase) => phase.id)
+}
+
+/** A step no board row wrote: the plan of `last`, the worked phases, no model and no start condition. */
+const workedStep = (last: PlanStep, ids: string[]): PlanStep => ({
+  planTitle: last.planTitle,
+  planHref: last.planHref,
+  phaseIds: ids,
+  label: ids.map((id) => `${PHASE_ID_PREFIX}${id}`).join(' '),
+  startsAfter: '',
+  model: '',
+  withoutRow: true,
+})
+
+/**
+ * The lane with one more step per plan for the phases it worked on without a board row: `mergePlanPhases` marks
+ * them touched (new in the worktree, or ticked further than the base). Marked `withoutRow`, they count as older phases
+ * when `currentPhaseOf` looks for the lane's newest board row, and they leave the list of phases still open in the plan.
+ */
+export const withWorkedPhases = (lane: SprintLane, plans: PlansByHref): SprintLane => {
+  const hrefs = [...new Set(lane.steps.flatMap((step) => (step.planHref ? [step.planHref] : [])))]
+  const added = hrefs.flatMap((href) => {
+    const ids = workedIds(lane, plans, href)
+    const last = lane.steps.filter((step) => step.planHref === href).at(-1)
+    return last && ids.length > 0 ? [workedStep(last, ids)] : []
+  })
+  return added.length > 0 ? { ...lane, steps: [...lane.steps, ...added] } : lane
+}
+
+/**
+ * The progress of a lane over its rows and the phases it worked on without one, as the watcher reports it. The view
+ * builds the same from `withWorkedPhases` itself, since it also needs that lane for the phases still open.
+ */
+export const workedLaneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress =>
+  laneProgress(withWorkedPhases(lane, plans), plans)

package/src/sync/checksum.ts

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto'
+
+export const checksum = (content: string): string => createHash('sha256').update(content, 'utf8').digest('hex')
+
+const sortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value === null || typeof value !== 'object') return value
+  const entries = Object.entries(value).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+  return Object.fromEntries(entries.map(([key, inner]) => [key, sortKeys(inner)]))
+}
+
+/** JSON with sorted keys, so two semantically equal objects serialise to the same string. */
+export const canonicalJson = (value: unknown): string => JSON.stringify(sortKeys(value))

package/src/sync/choice.ts

@@ -0,0 +1,14 @@
+/** One answer of a `choose` question: the value the code gets and the words the user reads. */
+export type Choice<T extends string> = { value: T; label: string }
+
+/** The text of a `choose` question: the question, then one numbered line per answer, the fallback marked. */
+export const choiceText = <T extends string>(question: string, options: readonly Choice<T>[], fallback: T): string =>
+  [
+    question,
+    ...options.map(({ value, label }, index) => `  ${index + 1}) ${label}${value === fallback ? ' (default)' : ''}`),
+    `Choose 1-${options.length}, Enter for the default: `,
+  ].join('\n')
+
+/** The chosen value: a valid number picks its answer, anything else (Enter included) the fallback. */
+export const chosenValue = <T extends string>(answer: string, options: readonly Choice<T>[], fallback: T): T =>
+  options[Number.parseInt(answer, 10) - 1]?.value ?? fallback

package/src/sync/command-context.ts

@@ -0,0 +1,113 @@
+import { spawnSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { createInterface } from 'node:readline/promises'
+import { CLI_NAME } from '../version/release'
+import { type Choice, choiceText, chosenValue } from './choice'
+import { errorMessage } from './error-message'
+import { linkHerdrPluginFrom } from './herdr-plugin'
+import type { KitSource } from './kit'
+import { type KitLocation, locateKit, readKitSource } from './kit-source'
+import { exitCodeOf, formatReport, SYNC_EXIT } from './report'
+import type { SyncResult } from './sync-result'
+import { detectTools, INSTALLERS, type InstallerName, spawnTool, type ToolPresence } from './tools'
+
+export type CommandContext = {
+  projectRoot: string
+  /** `XDG_CONFIG_HOME` from the environment; a test context leaves it out, so its home stays its own. */
+  configHome?: string
+  /** Where `--global` installs: the directory holding the user's `.claude/`. */
+  home: string
+  locate: () => Promise<KitLocation>
+  log: (line: string) => void
+  /** Hooks the herdr plugin in and returns the line to print, if any. Must not throw: a failure is a line, not an error. */
+  linkHerdrPlugin: (packageRoot: string) => string | null
+  /** A yes/no question to the user; null when there is no terminal to ask in. */
+  ask: (question: string) => Promise<boolean | null>
+  /** A choice among fixed answers; Enter takes `fallback`; null when there is no terminal to ask in. */
+  choose: <T extends string>(question: string, options: readonly Choice<T>[], fallback: T) => Promise<T | null>
+  /** Which external tools are installed; the test context answers a fixed value, so no test depends on the machine. */
+  detectTools: () => ToolPresence
+  /** True when `jh` runs from the PATH, so a hook may name it; the test context answers a fixed value. */
+  cliOnPath: () => boolean
+  /** Runs one of the kit's fixed installers with the terminal attached; the exit code. */
+  runInstaller: (name: InstallerName) => number
+}
+
+/** What a command did: lines to print before the report, and the sync result. */
+export type CommandOutcome = { notes: string[]; result: SyncResult }
+
+const YES = /^y(es)?$/i
+
+const hasTerminal = (): boolean => Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+/** One question on the terminal, the trimmed answer. */
+const questionOnTerminal = async (text: string): Promise<string> => {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await terminal.question(text)).trim()
+  } finally {
+    terminal.close()
+  }
+}
+
+/** Asks on the terminal; without one on both stdin and stdout nobody would see or answer the question. */
+const askOnTerminal = async (question: string): Promise<boolean | null> =>
+  hasTerminal() ? YES.test(await questionOnTerminal(`${question} [y/N] `)) : null
+
+const chooseOnTerminal = async <T extends string>(
+  question: string,
+  options: readonly Choice<T>[],
+  fallback: T,
+): Promise<T | null> =>
+  hasTerminal()
+    ? chosenValue(await questionOnTerminal(choiceText(question, options, fallback)), options, fallback)
+    : null
+
+/** One of `INSTALLERS`, run by `sh` from the home directory with the terminal attached; the name type admits no other command. */
+const runInstallerOnTerminal = (name: InstallerName): number =>
+  spawnSync('sh', ['-c', INSTALLERS[name]], { stdio: 'inherit', cwd: homedir() }).status ?? 1
+
+export const defaultContext = (): CommandContext => ({
+  projectRoot: process.cwd(),
+  home: homedir(),
+  configHome: process.env.XDG_CONFIG_HOME,
+  locate: () => locateKit(),
+  log: (line) => console.log(line),
+  linkHerdrPlugin: linkHerdrPluginFrom,
+  ask: askOnTerminal,
+  choose: chooseOnTerminal,
+  detectTools: () => detectTools(process.env, process.platform, spawnTool(process.env)),
+  cliOnPath: () => !spawnTool(process.env)(CLI_NAME, ['--version']).missing,
+  runInstaller: runInstallerOnTerminal,
+})
+
+export const usageError = (context: CommandContext, message: string): number => {
+  context.log(message)
+  return SYNC_EXIT.error
+}
+
+/** Reads the kit, runs the command, prints the report; any thrown error becomes exit code 2. */
+export const runWithKit = async (
+  context: CommandContext,
+  commandName: string,
+  action: (kit: KitSource) => Promise<CommandOutcome>,
+): Promise<number> => {
+  try {
+    const location = await context.locate()
+    const { notes, result } = await action(await readKitSource(location))
+    const herdrNote = context.linkHerdrPlugin(location.packageRoot)
+    for (const note of herdrNote ? [...notes, herdrNote] : notes) context.log(note)
+    context.log(formatReport(result))
+    return exitCodeOf(result)
+  } catch (err) {
+    context.log(`${CLI_NAME} ${commandName} failed: ${errorMessage(err)}`)
+    return SYNC_EXIT.error
+  }
+}
+
+/** Installs into `~/.claude/` instead of the project's `.claude/`. */
+export const GLOBAL_FLAG = '--global'
+
+/** Printed before a global report: its paths are relative to the home directory, not to the project. */
+export const globalTargetNote = (home: string): string =>
+  `Installed into ~/.claude; the paths below are relative to ${home}.`