jackherd 0.0.1 → 1.0.0

package/src/watch/pull-requests.ts

@@ -0,0 +1,117 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { type ChecksState, checksOf, type GhPullRequest, isGhPullRequest } from '../plans/pull-requests'
+import { isRecord, parseArray } from './json-guards'
+
+/** The states of a pull request in `gh pr list --json state`. */
+export const PULL_REQUEST_STATE = { open: 'OPEN', merged: 'MERGED', closed: 'CLOSED' } as const
+
+export type PullRequestLifecycle = (typeof PULL_REQUEST_STATE)[keyof typeof PULL_REQUEST_STATE]
+
+/** A pull request as the lane watcher follows it, across open, merged and closed. */
+export type WatchedPullRequest = {
+  number: number
+  branch: string
+  state: PullRequestLifecycle
+  checks: ChecksState
+  headCommit: string
+  mergeCommit: string | null
+}
+
+/** The rollup is optional: the light list has none. */
+type GhWatchedPullRequest = Omit<GhPullRequest, 'statusCheckRollup'> & {
+  statusCheckRollup?: GhPullRequest['statusCheckRollup']
+  state: PullRequestLifecycle
+  headRefOid: string
+  mergeCommit: { oid: string } | null
+}
+
+/**
+ * The fields of the light list, `gh pr list --state all --json`: everything the watcher follows except the checks.
+ * `statusCheckRollup` is what made the old single call too heavy for GitHub's GraphQL (a 504 after ~10 s).
+ */
+export const WATCHED_PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,state,headRefOid,mergeCommit'
+
+/** The fields of the list of open pull requests, which is the only one that asks for their checks. */
+export const OPEN_PULL_REQUEST_FIELDS = `${WATCHED_PULL_REQUEST_FIELDS},statusCheckRollup`
+
+const GH_PR_LIST = 'gh pr list'
+
+const isMergeCommit = (value: unknown): boolean => value === null || (isRecord(value) && typeof value.oid === 'string')
+
+/** An entry of the light list has no `statusCheckRollup` at all; it reads as one with a null rollup. */
+const withNullRollup = (value: unknown): unknown =>
+  isRecord(value) && !('statusCheckRollup' in value) ? { ...value, statusCheckRollup: null } : value
+
+const isGhWatchedPullRequest = (value: unknown, host: string): value is GhWatchedPullRequest => {
+  if (!isGhPullRequest(value, host)) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    (Object.values(PULL_REQUEST_STATE) as unknown[]).includes(candidate.state) &&
+    typeof candidate.headRefOid === 'string' &&
+    isMergeCommit(candidate.mergeCommit)
+  )
+}
+
+const watchedPullRequestsOf = (
+  json: string,
+  host: string,
+  prepare: (entry: unknown) => unknown,
+): WatchedPullRequest[] =>
+  parseArray(
+    json,
+    (entry): entry is GhWatchedPullRequest => isGhWatchedPullRequest(prepare(entry), host),
+    GH_PR_LIST,
+  ).map((pullRequest) => ({
+    number: pullRequest.number,
+    branch: terminalSafe(pullRequest.headRefName),
+    state: pullRequest.state,
+    checks: checksOf(pullRequest.statusCheckRollup ?? []),
+    headCommit: pullRequest.headRefOid,
+    mergeCommit: pullRequest.mergeCommit?.oid ?? null,
+  }))
+
+const asIs = (entry: unknown): unknown => entry
+
+/**
+ * Reads the JSON of `gh pr list --json <WATCHED_PULL_REQUEST_FIELDS>`, checked like the plans view's
+ * `parsePullRequests`; throws on anything else. The list carries no rollup, so its checks are `none`.
+ */
+export const parseWatchedPullRequests = (json: string, host = 'github.com'): WatchedPullRequest[] =>
+  watchedPullRequestsOf(json, host, withNullRollup)
+
+/**
+ * Reads the JSON of `gh pr list --state open --json <OPEN_PULL_REQUEST_FIELDS>`. The rollup must be there, null or a
+ * list: a field that went missing must not turn every check into `none` and silence the watcher; throws instead.
+ */
+export const parseOpenPullRequests = (json: string, host = 'github.com'): WatchedPullRequest[] =>
+  watchedPullRequestsOf(json, host, asIs)
+
+/** The pull request a lane's status line names: the open one on the branch, else the newest. */
+export const latestPullRequestOf = (
+  pullRequests: readonly WatchedPullRequest[],
+  branch: string,
+): WatchedPullRequest | null => {
+  const onBranch = pullRequests.filter((pullRequest) => pullRequest.branch === branch)
+  const newestFirst = [...onBranch].sort((left, right) => right.number - left.number)
+  return newestFirst.find((pullRequest) => pullRequest.state === PULL_REQUEST_STATE.open) ?? newestFirst[0] ?? null
+}
+
+/**
+ * The light list and the list of open pull requests as one. An open pull request takes its head commit and checks
+ * from the open list, which read them together, so a verdict never belongs to another commit. One the light list
+ * already shows merged or closed keeps the light entry with no checks (the two lists are read concurrently, so the open list may still hold a pull request that has ended);
+ * one the open list lacks stays as listed (it ended in between and the next read shows it). An open pull request
+ * older than the light list's limit is added at the end.
+ */
+export const mergeCheckedPullRequests = (
+  listed: readonly WatchedPullRequest[],
+  open: readonly WatchedPullRequest[],
+): WatchedPullRequest[] => {
+  const openByNumber = new Map(open.map((pullRequest) => [pullRequest.number, pullRequest]))
+  const known = new Set(listed.map(({ number }) => number))
+  const checked = listed.map((pullRequest) => {
+    const withChecks = openByNumber.get(pullRequest.number)
+    return pullRequest.state === PULL_REQUEST_STATE.open && withChecks ? withChecks : pullRequest
+  })
+  return [...checked, ...open.filter(({ number }) => !known.has(number))]
+}

package/src/watch/single-report.ts

@@ -0,0 +1,15 @@
+/**
+ * The last line of a report without `--stream`, written for the model that started the call: the
+ * watcher is gone after it. With a Monitor tool a stream keeps reporting without a restart; without one
+ * (Bedrock, Vertex, Foundry, telemetry off) the restart after every report is the way it works.
+ */
+export const SINGLE_REPORT_NOTICE =
+  'watch ended after this report. Start it once with --stream under the Monitor tool: the stream stays armed and reports every change without a restart.'
+
+export const NO_MONITOR_NOTICE =
+  'watch ended after this report. This session has no Monitor tool, so a single call is the way it works here: start it again as a background Bash call (run_in_background) after you acted on this report.'
+
+export const withSingleReportNotice = (lines: readonly string[], monitorAvailable: boolean): string[] => [
+  ...lines,
+  monitorAvailable ? SINGLE_REPORT_NOTICE : NO_MONITOR_NOTICE,
+]

package/src/watch/skill-change.ts

@@ -0,0 +1,61 @@
+import { mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { errorText } from '../plans/error-text'
+import { changedSections, SKILL_CHANGE, type SkillChange, skillChangeLine } from '../version/skill-diff'
+import type { StartedKit } from '../version/started-kit'
+import { writePrivate } from './watcher-lock'
+
+/** The kit's own text of the orchestrate skill, with its placeholders, inside the package. */
+export const orchestrateSkillPath = (packageRoot: string): string =>
+  join(packageRoot, 'kit', 'workflow', 'skills', 'orchestrate', 'SKILL.md')
+
+/** The orchestrate skill's text in the kit at `packageRoot`; null when it cannot be read. */
+export const readOrchestrateSkill = (packageRoot: string): string | null => {
+  try {
+    return readFileSync(orchestrateSkillPath(packageRoot), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The change of the orchestrate skill between `snapshot` and the kit at `packageRoot` now: the unified diff
+ * (`git diff --no-index`) written to `directory` and the sections it touches, so the coordinator reads the change
+ * instead of the whole skill. Unavailable without a snapshot, a readable skill or a diff.
+ */
+export const skillChangeSince = (snapshot: string | null, packageRoot: string, directory: string): SkillChange => {
+  if (snapshot === null) return { kind: SKILL_CHANGE.unavailable, reason: 'no snapshot at start' }
+  const current = readOrchestrateSkill(packageRoot)
+  if (current === null) return { kind: SKILL_CHANGE.unavailable, reason: 'skill not readable' }
+  if (current === snapshot) return { kind: SKILL_CHANGE.unchanged }
+  try {
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    const before = join(directory, 'orchestrate-skill.before.md')
+    writePrivate(before, snapshot)
+    const diff = Bun.spawnSync([
+      'git',
+      'diff',
+      '--no-index',
+      '--unified=3',
+      '--',
+      before,
+      orchestrateSkillPath(packageRoot),
+    ])
+    const text = diff.stdout.toString()
+    if (diff.exitCode !== 1 || text === '')
+      return { kind: SKILL_CHANGE.unavailable, reason: `git diff exit ${diff.exitCode}` }
+    const diffPath = join(directory, 'orchestrate-skill.diff')
+    writePrivate(diffPath, text)
+    return { kind: SKILL_CHANGE.changed, sections: changedSections(current, text), diffPath }
+  } catch (error) {
+    return { kind: SKILL_CHANGE.unavailable, reason: errorText(error) }
+  }
+}
+
+/** The line about the orchestrate skill after a kit update, for the kit the watcher started with. */
+export const skillLineFor = (kit: StartedKit | null, snapshot: string | null, directory: string): string =>
+  skillChangeLine(
+    kit
+      ? skillChangeSince(snapshot, kit.packageRoot, directory)
+      : { kind: SKILL_CHANGE.unavailable, reason: 'kit not located' },
+  )

package/src/watch/source-dry-run-command.ts

@@ -0,0 +1,35 @@
+import { readResolvedConfig } from '../config/read-config'
+import { type JackherdConfig, parseSourceDraft } from '../config/schema'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import type { SourceDryRun } from './options'
+import { type DryRunTarget, dryRunExitCode, dryRunLines, dryRunTarget, emptyMapFields } from './source-dry-run'
+import { runSourceCommand, SOURCE_LIMITS, sourceRunOf } from './source-run'
+import type { SourceSettings } from './sources'
+
+const settingsOf = async (target: DryRunTarget, config: JackherdConfig): Promise<SourceSettings> => {
+  if (target.kind === 'name') {
+    const found = config.watch.sources.find(({ name }) => name === target.name)
+    if (!found) throw new Error(`no source ${target.name} in watch.sources`)
+    return found
+  }
+  const text = target.kind === 'stdin' ? await Bun.stdin.text() : await Bun.file(target.path).text()
+  return parseSourceDraft(JSON.parse(text), target.kind === 'stdin' ? 'stdin' : target.path)
+}
+
+/**
+ * `jh watch source <name|draft.json|-> --dry-run [--raw]`: runs one source once in the main checkout, as the
+ * watcher would, and prints what it found and would report; `--raw` adds the command's output. Takes no lock and
+ * neither reads nor writes the watcher's state, so a running watcher is not disturbed. Exits 1 when the run failed or a
+ * `map` field is empty in every entry.
+ */
+export const sourceDryRun = async ({ target, raw }: SourceDryRun): Promise<number> => {
+  const root = mainCheckout(process.cwd())
+  const { config } = readResolvedConfig([worktreeRoot(process.cwd()), root])
+  const settings = await settingsOf(dryRunTarget(target), config)
+  const answer = await runSourceCommand(settings.command, root, SOURCE_LIMITS)
+  const run = sourceRunOf(settings, answer)
+  const mapCheck = answer.ok ? emptyMapFields(answer.stdout, settings) : null
+  const stdout = raw && answer.ok ? answer.stdout : undefined
+  console.log(dryRunLines(settings, run, { mapCheck, stdout }).join('\n'))
+  return dryRunExitCode(run, mapCheck)
+}

package/src/watch/source-dry-run.ts

@@ -0,0 +1,124 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { sourceEventLines } from './lane-report'
+import {
+  isIgnoredAuthor,
+  listAt,
+  type SourceItem,
+  type SourceRun,
+  type SourceSettings,
+  sourceEvents,
+  textAt,
+} from './sources'
+
+/** What `watch source <target> --dry-run` names: a source of the config, a draft file holding one source, or a draft on stdin. */
+export type DryRunTarget = { kind: 'name'; name: string } | { kind: 'file'; path: string } | { kind: 'stdin' }
+
+/** The map fields empty in every one of `total` raw entries, each with its path. */
+export type MapCheck = { total: number; empty: { field: string; path: string }[] }
+
+/** What one dry run shows besides the run: the map check (null when the output has no list) and the raw output. */
+export type DryRunExtras = { mapCheck: MapCheck | null; stdout?: string }
+
+const STDIN = '-'
+const LISTED_ENTRIES = 10
+const ENTRY_LENGTH = 120
+const RAW_LINES = 40
+const RAW_LINE_LENGTH = 200
+const INDENT = '  '
+const BASELINE = 'first run of this source: baseline, nothing reported'
+const NOT_CHECKED = '0 entries: map not checked'
+const FOOTER = 'watcher state not read or changed; the watcher takes a new source over at its next start'
+
+export const dryRunTarget = (value: string): DryRunTarget => {
+  if (value === STDIN) return { kind: 'stdin' }
+  return value.includes('/') || value.endsWith('.json') ? { kind: 'file', path: value } : { kind: 'name', name: value }
+}
+
+const isEmptyAt = (entry: unknown, path: string): boolean => {
+  const text = textAt(entry, path)
+  return text === null || text === ''
+}
+
+/**
+ * Each `map` field that is empty (missing, null, no text or number, or `''`) in every entry of the list at `items`,
+ * read from the raw output, so a run that failed on a missing `id` or `updatedAt` still names it; null when the
+ * output has no list there.
+ */
+export const emptyMapFields = (stdout: string, settings: Pick<SourceSettings, 'items' | 'map'>): MapCheck | null => {
+  const raw = listAt(stdout, settings.items)
+  if (!raw.ok) return null
+  const { list } = raw
+  const fields = Object.entries(settings.map).flatMap(([field, path]) => (path === undefined ? [] : [{ field, path }]))
+  const empty = list.length === 0 ? [] : fields.filter(({ path }) => list.every((entry) => isEmptyAt(entry, path)))
+  return { total: list.length, empty }
+}
+
+/** 1 when the run failed or a map field is empty in every entry, so `/follow` does not write the source; else 0. */
+export const dryRunExitCode = (run: SourceRun, mapCheck: MapCheck | null): number =>
+  run.result.ok && (mapCheck?.empty.length ?? 0) === 0 ? 0 : 1
+
+/** `map.<field>: in <n> of <n> entries empty (<path>)` per empty field; for no entries, that nothing was checked. */
+const mapCheckLines = (mapCheck: MapCheck | null): string[] => {
+  if (!mapCheck) return []
+  if (mapCheck.total === 0) return [NOT_CHECKED]
+  const { total } = mapCheck
+  return mapCheck.empty.map(
+    ({ field, path }) => `map.${terminalSafe(field)}: in ${total} of ${total} entries empty (${terminalSafe(path)})`,
+  )
+}
+
+/** `<id> · <author> · <title>`, marked when `ignoreAuthors` holds it back. */
+const entryLine = (item: SourceItem, settings: SourceSettings): string => {
+  const parts = [item.id, item.author ?? '', item.title].filter((part) => part !== '')
+  const ignored = isIgnoredAuthor(item, settings.ignoreAuthors) ? ' (ignoreAuthors)' : ''
+  return `${INDENT}${terminalSafe(parts.join(' · ')).slice(0, ENTRY_LENGTH)}${ignored}`
+}
+
+const entryLines = (items: readonly SourceItem[], settings: SourceSettings): string[] => {
+  const more = items.length - LISTED_ENTRIES
+  return [
+    `${items.length} entries`,
+    ...items.slice(0, LISTED_ENTRIES).map((item) => entryLine(item, settings)),
+    ...(more > 0 ? [`${INDENT}… ${more} more`] : []),
+  ]
+}
+
+const cutLine = (line: string): string =>
+  line.length > RAW_LINE_LENGTH
+    ? `${line.slice(0, RAW_LINE_LENGTH)} … +${line.length - RAW_LINE_LENGTH} characters`
+    : line
+
+/** The command's output line by line, cut to `RAW_LINES` of `RAW_LINE_LENGTH` characters, for finding the paths of `items` and `map`. */
+const rawLines = (stdout: string): string[] => {
+  const lines = stdout.replace(/\n$/, '').split('\n')
+  const more = lines.length - RAW_LINES
+  return [
+    'output:',
+    ...lines.slice(0, RAW_LINES).map((line) => `${INDENT}${cutLine(terminalSafe(line))}`),
+    ...(more > 0 ? [`${INDENT}… ${more} more lines`] : []),
+  ]
+}
+
+/** The events of the run against a source whose baseline holds nothing: every entry not held back as `new`. */
+const eventsOf = (settings: SourceSettings, run: SourceRun) =>
+  sourceEvents({ [settings.name]: { seen: [], failingSince: null } }, [run], [settings])
+
+/** The watcher's first run of a source reports nothing; one entry shows how a later new or changed one would read. */
+const exampleLines = (settings: SourceSettings, run: SourceRun): string[] => {
+  const example = eventsOf(settings, run).find((event) => 'id' in event)
+  if (!example) return [`${BASELINE}; no entry here would report`]
+  return [`${BASELINE}; later a new or changed entry reports like this:`, ...sourceEventLines(example)]
+}
+
+/**
+ * What one dry run of a source shows: its command, `stdout` when asked for (`--raw`), the entries after `map` as a short
+ * list (`<id> · <author> · <title>`), that the watcher's first run of the source is a baseline and reports nothing, and
+ * one entry as a later report would show it; a failure as the watcher would report it. The `map` fields empty in every
+ * entry come after the raw output. Nothing of the watcher's state is read or written.
+ */
+export const dryRunLines = (settings: SourceSettings, run: SourceRun, extras: DryRunExtras): string[] => {
+  const head = `dry run source ${terminalSafe(settings.name)}: ${terminalSafe(JSON.stringify(settings.command))}`
+  const top = [head, ...(extras.stdout === undefined ? [] : rawLines(extras.stdout)), ...mapCheckLines(extras.mapCheck)]
+  if (!run.result.ok) return [...top, ...eventsOf(settings, run).flatMap(sourceEventLines), FOOTER]
+  return [...top, ...entryLines(run.result.items, settings), ...exampleLines(settings, run), FOOTER]
+}

package/src/watch/source-fields.ts

@@ -0,0 +1,9 @@
+/** The fields of `map` the watcher knows by name; any further field is only read for `reportOn`. */
+export const SOURCE_FIELD = {
+  id: 'id',
+  updatedAt: 'updatedAt',
+  title: 'title',
+  url: 'url',
+  body: 'body',
+  author: 'author',
+} as const

package/src/watch/source-path.ts

@@ -0,0 +1,40 @@
+import { isRecord } from './json-guards'
+
+/**
+ * Where a field sits in a source's JSON output: `.` is the whole output, else a chain of `.key`, `[n]` and `[-n]`
+ * (counted from the end), such as `.fields.comment.comments[-1].body`. No jq: nothing else is understood.
+ */
+export type SourcePath = string
+
+export const ROOT_PATH = '.'
+
+const PATH_STEP = /\.([^\s.[\]|]+)|\[(-?\d+)\]/y
+
+type PathStep = { key: string } | { index: number }
+
+/** The steps of `path`, or null when it is no source path. */
+const pathSteps = (path: string): PathStep[] | null => {
+  if (path === ROOT_PATH) return []
+  const steps: PathStep[] = []
+  PATH_STEP.lastIndex = 0
+  while (PATH_STEP.lastIndex < path.length) {
+    const match = PATH_STEP.exec(path)
+    if (!match) return null
+    steps.push(match[1] === undefined ? { index: Number(match[2]) } : { key: match[1] })
+  }
+  return steps.length > 0 ? steps : null
+}
+
+export const isSourcePath = (path: string): boolean => pathSteps(path) !== null
+
+const stepInto = (value: unknown, step: PathStep): unknown => {
+  if ('key' in step) return isRecord(value) && Object.hasOwn(value, step.key) ? value[step.key] : undefined
+  return Array.isArray(value) ? value.at(step.index) : undefined
+}
+
+/** The value at `path` in `value`; undefined when a step does not fit or the path is invalid. */
+export const selectPath = (value: unknown, path: SourcePath): unknown =>
+  (pathSteps(path) ?? [undefined]).reduce<unknown>(
+    (current, step) => (step === undefined ? undefined : stepInto(current, step)),
+    value,
+  )

package/src/watch/source-run.ts

@@ -0,0 +1,90 @@
+import { exitFailure, parseSourceOutput, SOURCE_FAILURE, type SourceRun, type SourceSettings } from './sources'
+
+/** How long a source's command may run and how much it may print before it is stopped. */
+export type SourceLimits = { timeoutMs: number; maxBytes: number }
+
+export type SourceAnswer = { ok: true; stdout: string } | { ok: false; reason: string }
+
+export const SOURCE_LIMITS: SourceLimits = { timeoutMs: 30_000, maxBytes: 1_000_000 }
+
+type Child = ReturnType<typeof Bun.spawn<'ignore', 'pipe', 'ignore'>>
+
+const TIMED_OUT = Symbol('timed out')
+const TIMED_OUT_ANSWER: SourceAnswer = { ok: false, reason: SOURCE_FAILURE.timeout }
+const TOO_LARGE_ANSWER: SourceAnswer = { ok: false, reason: SOURCE_FAILURE.tooLarge }
+const UNREADABLE_ANSWER: SourceAnswer = { ok: false, reason: SOURCE_FAILURE.unreadable }
+const READ_FAILED = Symbol('read failed')
+
+const answerOf = (stdout: string, exitCode: number): SourceAnswer =>
+  exitCode === 0 ? { ok: true, stdout } : { ok: false, reason: exitFailure(exitCode) }
+
+/** The run a command's answer makes: its output over `items` and `map`, or the reason it failed. */
+export const sourceRunOf = (settings: SourceSettings, answer: SourceAnswer): SourceRun => ({
+  name: settings.name,
+  result: answer.ok ? parseSourceOutput(answer.stdout, settings) : answer,
+})
+
+/** Reads stdout up to `maxBytes`; null once it went past them. */
+const readCapped = async (child: Child, maxBytes: number): Promise<string | null> => {
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of child.stdout) {
+    size += chunk.byteLength
+    if (size > maxBytes) return null
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/** Started in a process group of its own, so a timeout reaches what the command started too (`curl` behind `sh`). */
+const spawned = (command: readonly string[], cwd: string): Child | null => {
+  try {
+    return Bun.spawn([...command], { cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'ignore', detached: true })
+  } catch {
+    return null
+  }
+}
+
+/** Kills the command's whole process group, best effort: a group that ended (ESRCH) or cannot be signalled is left alone. */
+const killGroup = (child: Child) => {
+  try {
+    process.kill(-child.pid, 'SIGKILL')
+  } catch {
+    // Nothing left to kill, or nothing this process may kill; the run's answer stands either way.
+  }
+}
+
+/**
+ * Runs `command` as given, without a shell, in `cwd` with the user's environment; never rejects. stderr is not read,
+ * so nothing a failing tool prints there (a token, a URL with credentials) reaches the report. Past `timeoutMs` or
+ * `maxBytes` the command's process group is killed, and the answer never waits past `timeoutMs` for a pipe a leftover
+ * process keeps open; the group is also killed after a normal end, so a source leaves no process behind that stays in its group.
+ */
+export const runSourceCommand = async (
+  command: readonly string[],
+  cwd: string,
+  limits: SourceLimits,
+): Promise<SourceAnswer> => {
+  const child = spawned(command, cwd)
+  if (!child) return { ok: false, reason: SOURCE_FAILURE.notStarted }
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<typeof TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), limits.timeoutMs)
+  })
+  try {
+    const reading = readCapped(child, limits.maxBytes).catch((): typeof READ_FAILED => READ_FAILED)
+    const stdout = await Promise.race([reading, deadline])
+    if (stdout === TIMED_OUT) return TIMED_OUT_ANSWER
+    if (stdout === null) return TOO_LARGE_ANSWER
+    if (stdout === READ_FAILED) return UNREADABLE_ANSWER
+    const exitCode = await Promise.race([child.exited, deadline])
+    return exitCode === TIMED_OUT ? TIMED_OUT_ANSWER : answerOf(stdout, exitCode)
+  } finally {
+    clearTimeout(timer)
+    killGroup(child)
+  }
+}
+
+/** One run of a source: its command, then its output over `items` and `map`. */
+export const runSource = async (settings: SourceSettings, cwd: string, limits: SourceLimits): Promise<SourceRun> =>
+  sourceRunOf(settings, await runSourceCommand(settings.command, cwd, limits))