jackherd 0.0.1 → 1.0.1

package/src/plans/plan-chips.ts

@@ -0,0 +1,75 @@
+import { pathToFileURL } from 'node:url'
+import { resolvePlanPath } from '../plan-format'
+import type { LinkChip } from './link-chips'
+import type { Snapshot } from './snapshot'
+import type { WrittenPage } from './sprint-export'
+
+const PLAN_CHIP = { label: 'Plan', icon: '📄' } as const
+
+/** The chip that opens a plan's section in the sprint page. */
+export const planChip = (pagePath: string, anchor: string): LinkChip => ({
+  url: `${pathToFileURL(pagePath).href}#${anchor}`,
+  label: PLAN_CHIP.label,
+  icon: PLAN_CHIP.icon,
+  private: false,
+})
+
+/**
+ * The snapshot with a plan chip in front of the links of every plan the page carries. A plan the page does not
+ * carry gets none.
+ */
+export const withPlanChips = (snapshot: Snapshot, page: WrittenPage, sprintDirectory: string): Snapshot => ({
+  ...snapshot,
+  views: snapshot.views.map((view) => ({
+    ...view,
+    chips: Object.fromEntries(
+      Object.entries(view.chips).map(([href, chips]) => {
+        const anchor = page.anchors.get(resolvePlanPath(sprintDirectory, href))
+        return [href, anchor ? [planChip(page.path, anchor), ...chips] : chips]
+      }),
+    ),
+  })),
+})
+
+/**
+ * The anchor of a plan chip's address when it points into the page at `pagePath`; null for any other address,
+ * so a `file:` address that is not the page is never opened.
+ */
+export const planAnchorOn = (pagePath: string | null, address: string): string | null => {
+  if (!pagePath) return null
+  try {
+    const requested = new URL(address)
+    const page = pathToFileURL(pagePath)
+    return requested.protocol === page.protocol && requested.pathname === page.pathname
+      ? requested.hash.slice(1) || null
+      : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What decides whether the written page is out of date: the sprint text, the plan texts and the planned phases.
+ * The status of the lanes is left out on purpose, it changes every few seconds and building the page costs
+ * seconds; a page older than that says so in its header, and the key `s` writes a fresh one.
+ */
+export const pageKey = ({ documents, planned }: Snapshot): string =>
+  Bun.hash(JSON.stringify([documents, planned])).toString(36)
+
+/** The sprint page last written, with the key of the plans it was built from. */
+export type KnownPage = WrittenPage & { key: string }
+
+/**
+ * Whether the page has to be written: none yet, built from other plans, or the file is gone. In the view of one
+ * lane the key comes from the plans that view reads, so a plan only another lane names is not noticed there;
+ * the key `s` writes the whole sprint.
+ */
+export const pageNeedsWriting = (page: KnownPage | null, key: string, fileExists: boolean): boolean =>
+  page === null || page.key !== key || !fileExists
+
+/** The page to remember after a write: the new one, else the last good one, whose chips stay. */
+export const pageAfterWrite = (
+  previous: KnownPage | null,
+  written: WrittenPage | { error: string },
+  key: string,
+): KnownPage | null => ('error' in written ? previous : { ...written, key })

package/src/plans/plan-panes.ts

@@ -0,0 +1,206 @@
+import { basename } from 'node:path'
+
+/** One herdr pane as `plans --ensure` sees it: where it is, whether an agent runs in it, its foreground commands. */
+export type PaneState = { pane: string; tab: string; cwd: string; agent: boolean; foreground: string[][] }
+
+/** Runs a command in a free shell pane, or splits a pane to the right and runs it in the new one. */
+export type PaneAction = { kind: 'run' | 'split'; pane: string; command: string }
+
+export type PlanPaneInput = {
+  panes: readonly PaneState[]
+  /** The coordinator's pane, null when none was found. */
+  coordinator: string | null
+  lanes: readonly { name: string; cwd: string }[]
+  root: string
+  /** The worktree directory under `root`: a shell there belongs to a lane, not to the coordinator. */
+  worktrees: string
+  /** The line that says why there is no coordinator pane. */
+  missingCoordinator: string
+  /** The command that starts the view: of the lane, or of every lane for null. */
+  command: (lane: string | null) => string
+}
+
+export type PlanPaneResult = { actions: PaneAction[]; notes: string[] }
+
+type ListedPane = { pane_id: string; tab_id: string; cwd: string; agent?: unknown }
+
+const isListedPane = (value: unknown): value is ListedPane => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    typeof candidate.pane_id === 'string' && typeof candidate.tab_id === 'string' && typeof candidate.cwd === 'string'
+  )
+}
+
+/** The panes of a `herdr pane list` answer, without their foreground; throws on a changed answer. */
+export const paneListOf = (json: string): Omit<PaneState, 'foreground'>[] => {
+  const panes = (JSON.parse(json) as { result?: { panes?: unknown } }).result?.panes
+  if (!Array.isArray(panes) || !panes.every(isListedPane)) throw new Error('herdr pane list: unexpected answer')
+  return panes.map((each) => ({
+    pane: each.pane_id,
+    tab: each.tab_id,
+    cwd: each.cwd,
+    agent: typeof each.agent === 'string',
+  }))
+}
+
+/** The pane of every agent in a `herdr agent list` answer, named or not; throws on a changed answer. */
+export const agentPanesOf = (json: string): string[] => {
+  const agents = (JSON.parse(json) as { result?: { agents?: unknown } }).result?.agents
+  if (!Array.isArray(agents)) throw new Error('herdr agent list: unexpected answer')
+  return agents.flatMap((agent) => {
+    const pane = (agent as { pane_id?: unknown } | null)?.pane_id
+    return typeof pane === 'string' ? [pane] : []
+  })
+}
+
+/**
+ * Marks the panes herdr lists an agent for. After a restart `herdr pane list` names no agent in a pane for a few
+ * seconds, until the agent's process is back, while `herdr agent list` keeps it: such a pane is never a free shell.
+ */
+export const withAgentPanes = <Pane extends { pane: string; agent: boolean }>(
+  panes: readonly Pane[],
+  agentPanes: readonly string[],
+): Pane[] => panes.map((each) => (agentPanes.includes(each.pane) ? { ...each, agent: true } : each))
+
+const isArgv = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((arg) => typeof arg === 'string')
+
+/** The argv of each foreground process in a `herdr pane process-info` answer; none when it names none. */
+export const foregroundOf = (json: string): string[][] => {
+  const processes = (JSON.parse(json) as { result?: { process_info?: { foreground_processes?: unknown } } }).result
+    ?.process_info?.foreground_processes
+  if (!Array.isArray(processes)) return []
+  return processes.flatMap((each) => {
+    const argv = (each as { argv?: unknown } | null)?.argv
+    return isArgv(argv) ? [argv] : []
+  })
+}
+
+const SHELLS = new Set(['bash', 'zsh', 'sh', 'fish', 'dash', 'ksh'])
+
+/** Arguments that make a `plans` call something other than the live view. */
+const NOT_A_VIEW = ['--once', '--ensure']
+
+const programOf = (argv: readonly string[]): string => basename(argv[0] ?? '').replace(/^-/, '')
+
+const isKitEntry = (arg: string): boolean => /(jh|jackherd)(@[^/]+)?$/.test(arg) || arg.endsWith('cli.ts')
+
+const laneOf = (argv: readonly string[]): string | null => {
+  const index = argv.indexOf('--lane')
+  return index === -1 ? null : (argv[index + 1] ?? null)
+}
+
+const isViewCall = (argv: readonly string[], lane: string | null): boolean =>
+  argv.includes('plans') &&
+  argv.some(isKitEntry) &&
+  !argv.some((arg) => NOT_A_VIEW.includes(arg)) &&
+  laneOf(argv) === lane
+
+/** Whether a foreground command is the live plans view: of `lane`, or of every lane for null. */
+export const isPlanView = (foreground: readonly (readonly string[])[], lane: string | null): boolean =>
+  foreground.some((argv) => isViewCall(argv, lane))
+
+/** A pane with nothing but a shell in the foreground: what a restored pane whose command is gone looks like. */
+export const isIdleShell = ({ agent, foreground }: PaneState): boolean =>
+  !agent && foreground.length > 0 && foreground.every((argv) => SHELLS.has(programOf(argv)))
+
+/**
+ * The coordinator's pane: the agent herdr lists under the coordinator's name, else the calling pane when an agent
+ * in the main checkout runs there, else the only agent in the main checkout. Two agents there and no name: none.
+ */
+export const coordinatorPaneOf = (
+  panes: readonly PaneState[],
+  root: string,
+  hints: { named: string | null; caller: string | null },
+): string | null => {
+  if (hints.named) return hints.named
+  const inRoot = panes.filter((each) => each.agent && each.cwd === root)
+  if (hints.caller && inRoot.some((each) => each.pane === hints.caller)) return hints.caller
+  return inRoot.length === 1 ? (inRoot[0]?.pane ?? null) : null
+}
+
+/** Why no coordinator pane was found: no agent in the main checkout, or several and none of them named. */
+export const missingCoordinatorNote = (panes: readonly PaneState[], root: string, name: string): string => {
+  const inRoot = panes.filter((each) => each.agent && each.cwd === root).length
+  return inRoot === 0
+    ? 'coordinator: no agent in the main checkout'
+    : `coordinator: ${inRoot} agents in the main checkout and none named ${name}; run plans --ensure in its pane, or herdr agent rename <pane> ${name}`
+}
+
+const quoted = (arg: string): string => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`)
+
+/** The shell command that starts the view with the CLI `argv` names (runtime and entry), for `lane` or every lane. */
+export const viewCommandOf = (argv: readonly string[], lane: string | null): string =>
+  [...argv.slice(0, 2), 'plans', ...(lane ? ['--lane', lane] : [])].map(quoted).join(' ')
+
+/** The new pane of a `herdr pane split` answer; throws on a changed answer. */
+export const splitPaneOf = (json: string): string => {
+  const pane = (JSON.parse(json) as { result?: { pane?: { pane_id?: unknown } } }).result?.pane?.pane_id
+  if (typeof pane !== 'string') throw new Error('herdr pane split: unexpected answer')
+  return pane
+}
+
+/**
+ * What one view needs in the tab of `anchor`: nothing when a pane there shows it, a run in a free shell whose
+ * directory `isHome` accepts (the pane the view ran in before a restart), else a split of the anchor pane.
+ */
+const actionFor = (
+  panes: readonly PaneState[],
+  anchor: PaneState,
+  isHome: (cwd: string) => boolean,
+  lane: string | null,
+  command: string,
+): PaneAction | null => {
+  const tab = panes.filter((each) => each.tab === anchor.tab)
+  if (tab.some((each) => isPlanView(each.foreground, lane))) return null
+  const free = tab.find((each) => isHome(each.cwd) && isIdleShell(each))
+  return free ? { kind: 'run', pane: free.pane, command } : { kind: 'split', pane: anchor.pane, command }
+}
+
+/** A directory at or below the worktree: a shell there may have changed into a subdirectory. */
+const insideOf =
+  (directory: string) =>
+  (cwd: string): boolean =>
+    cwd === directory || cwd.startsWith(`${directory}/`)
+
+/** A directory of the main checkout outside the lanes' worktrees. */
+const inMainCheckout = (root: string, worktrees: string) => {
+  const inRoot = insideOf(root)
+  const inWorktrees = insideOf(worktrees)
+  return (cwd: string): boolean => inRoot(cwd) && !inWorktrees(cwd)
+}
+
+/**
+ * The pane a lane's view belongs beside: its agent in the worktree. Without one there is none yet: a shell there is
+ * the pane the agent is about to be started in.
+ */
+const laneAnchor = (panes: readonly PaneState[], inside: (cwd: string) => boolean): PaneState | undefined =>
+  panes.find((each) => inside(each.cwd) && each.agent)
+
+/** The plans views that are missing beside the coordinator and each lane, and how to bring each back. */
+export const planPaneActions = ({
+  panes,
+  coordinator,
+  lanes,
+  root,
+  worktrees,
+  command,
+  missingCoordinator,
+}: PlanPaneInput): PlanPaneResult => {
+  const actions: PaneAction[] = []
+  const notes: string[] = []
+  const coordinatorPane = panes.find((each) => each.pane === coordinator)
+  const coordinatorAction =
+    coordinatorPane && actionFor(panes, coordinatorPane, inMainCheckout(root, worktrees), null, command(null))
+  if (!coordinatorPane) notes.push(missingCoordinator)
+  if (coordinatorAction) actions.push(coordinatorAction)
+  for (const lane of lanes) {
+    const inside = insideOf(lane.cwd)
+    const anchor = laneAnchor(panes, inside)
+    const action = anchor && actionFor(panes, anchor, inside, lane.name, command(lane.name))
+    if (!anchor) notes.push(`${lane.name}: waiting for its agent`)
+    if (action) actions.push(action)
+  }
+  return { actions, notes }
+}

package/src/plans/planned.ts

@@ -0,0 +1,117 @@
+import { posix } from 'node:path'
+import {
+  PHASE_ID_PREFIX,
+  type PlanPhase,
+  parsePlanPhases,
+  readPlanHeader,
+  resolvePlanPath,
+  type SprintLane,
+} from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+
+/** The open phases of one plan that no lane names: the plan's section, its phases, their checkboxes. */
+export type PlannedPlan = {
+  /** The plan's file in the repository, which is what tells two spellings of one link apart. */
+  path: string
+  title: string
+  /** Ids without the `P`, in the order of the plan. */
+  phaseIds: string[]
+  done: number
+  total: number
+}
+
+/** A lane of the sprint and what its agent reports, null when it has none. */
+export type PlannedLane = { lane: SprintLane; agent: string | null }
+
+export type PlannedInput = {
+  /** Plan texts by the link as the sprint writes it, in the order the sprint names them. */
+  plans: Readonly<Record<string, string>>
+  lanes: readonly PlannedLane[]
+  sprintDirectory: string
+  language: PlanLanguage
+}
+
+/**
+ * A phase is open while a task before its review gate is unticked; an open documentation or roadmap box in
+ * the gate does not reopen a phase that is built and merged. A phase that has only gate boxes counts by them.
+ */
+const isOpen = ({ items }: PlanPhase): boolean => {
+  const tasks = items.filter(({ gate }) => !gate)
+  return (tasks.length > 0 ? tasks : items).some(({ done }) => !done)
+}
+
+const openPhases = (phases: PlanPhase[]): PlanPhase[] => phases.filter(isOpen)
+
+const isRunning = ({ lane, agent }: PlannedLane): boolean => agent !== null && !lane.closed
+
+const planPaths = ({ lane }: PlannedLane, sprintDirectory: string): string[] =>
+  lane.steps.flatMap(({ planHref }) => (planHref ? [resolvePlanPath(sprintDirectory, planHref)] : []))
+
+/** The plans a running lane works on: their open phases show under that lane, so the planned row leaves them out. */
+const followedPaths = ({ lanes, sprintDirectory }: PlannedInput): Set<string> =>
+  new Set(lanes.filter(isRunning).flatMap((lane) => planPaths(lane, sprintDirectory)))
+
+const plannedPlanOf = (path: string, markdown: string, language: PlanLanguage, excluded: ReadonlySet<string>) => {
+  const phases = openPhases(parsePlanPhases(markdown, language)).filter(({ id }) => !excluded.has(id))
+  if (phases.length === 0) return []
+  const items = phases.flatMap((phase) => phase.items)
+  const plan: PlannedPlan = {
+    path,
+    title: readPlanHeader(markdown, language, posix.basename(path, '.md')).title,
+    phaseIds: phases.map(({ id }) => id),
+    done: items.filter(({ done }) => done).length,
+    total: items.length,
+  }
+  return [plan]
+}
+
+/**
+ * The phases that are planned and open: each plan of the sprint (its plans tables and its lanes) with the phases
+ * that still have an unticked checkbox, less the plans a lane with an agent works on (those show under the lane).
+ * A plan appears once however the sprint spells its link, and not at all when nothing in it is open.
+ */
+export const plannedPlans = (input: PlannedInput): PlannedPlan[] => {
+  const followed = followedPaths(input)
+  const seen = new Set<string>()
+  return Object.entries(input.plans).flatMap(([href, markdown]) => {
+    const path = resolvePlanPath(input.sprintDirectory, href)
+    if (seen.has(path) || followed.has(path)) return []
+    seen.add(path)
+    return plannedPlanOf(path, markdown, input.language, new Set())
+  })
+}
+
+/**
+ * The open phases of the plans a lane works on that its own steps do not name, which is what comes after the
+ * phase the lane is on. Empty for a lane without an agent or a closed one: it is listed in the closing block.
+ */
+export const followingPlans = (planned: PlannedLane, input: Omit<PlannedInput, 'lanes'>): PlannedPlan[] => {
+  if (!isRunning(planned)) return []
+  const seen = new Set<string>()
+  return planned.lane.steps.flatMap(({ planHref }) => {
+    const markdown = planHref ? input.plans[planHref] : undefined
+    const path = planHref ? resolvePlanPath(input.sprintDirectory, planHref) : null
+    if (path === null || markdown === undefined || seen.has(path)) return []
+    seen.add(path)
+    const named = new Set(
+      planned.lane.steps
+        .filter((step) => step.planHref !== null && resolvePlanPath(input.sprintDirectory, step.planHref) === path)
+        .flatMap((step) => step.phaseIds),
+    )
+    return plannedPlanOf(path, markdown, input.language, named)
+  })
+}
+
+/** The plan the lane's current phase belongs to goes first; the others keep their order. */
+export const currentPlanFirst = (plans: readonly PlannedPlan[], currentPath: string | null): PlannedPlan[] => [
+  ...plans.filter(({ path }) => path === currentPath),
+  ...plans.filter(({ path }) => path !== currentPath),
+]
+
+/** `P3 P4 P5` */
+export const phaseList = (plan: Pick<PlannedPlan, 'phaseIds'>): string =>
+  plan.phaseIds.map((id) => `${PHASE_ID_PREFIX}${id}`).join(' ')
+
+/** How many phases the plans list together. */
+export const plannedPhaseCount = (planned: readonly Pick<PlannedPlan, 'phaseIds'>[]): number =>
+  planned.reduce((count, plan) => count + plan.phaseIds.length, 0)

package/src/plans/pull-requests.ts

@@ -0,0 +1,107 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+
+/** The check state of a pull request, folded from all its check runs and commit statuses. */
+export const CHECKS = { passed: 'passed', failed: 'failed', pending: 'pending', none: 'none' } as const
+
+export type ChecksState = (typeof CHECKS)[keyof typeof CHECKS]
+
+export type PullRequest = {
+  number: number
+  title: string
+  url: string
+  branch: string
+  draft: boolean
+  checks: ChecksState
+}
+
+/** One entry of `statusCheckRollup`: a check run carries status and conclusion, a commit status a state. */
+export type RollupEntry = { __typename?: string; status?: string; conclusion?: string | null; state?: string }
+
+export type GhPullRequest = {
+  number: number
+  title: string
+  url: string
+  headRefName: string
+  isDraft: boolean
+  statusCheckRollup: RollupEntry[] | null
+}
+
+/** The fields `parsePullRequests` reads; pass them to `gh pr list --json`. */
+export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup'
+
+const FAILED = new Set(['FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'ERROR'])
+const PENDING_STATES = new Set(['PENDING', 'EXPECTED'])
+
+const isFailed = ({ conclusion, state }: RollupEntry): boolean =>
+  FAILED.has(conclusion ?? '') || FAILED.has(state ?? '')
+
+const isPending = ({ status, state }: RollupEntry): boolean =>
+  state === undefined ? status !== 'COMPLETED' : PENDING_STATES.has(state)
+
+export const checksOf = (rollup: readonly RollupEntry[]): ChecksState => {
+  if (rollup.length === 0) return CHECKS.none
+  if (rollup.some(isFailed)) return CHECKS.failed
+  return rollup.some(isPending) ? CHECKS.pending : CHECKS.passed
+}
+
+const PULL_REQUEST_PATH = /^\/[\w.-]+\/[\w.-]+\/pull\/(\d+)$/
+
+/** True only for `https://<host>/<owner>/<repo>/pull/<number>` of this very pull request: the view opens it on a click. */
+const isPullRequestPage = (url: string, number: number, host: string): boolean => {
+  try {
+    const parsed = new URL(url)
+    const path = parsed.pathname.match(PULL_REQUEST_PATH)
+    const exact = parsed.href === url && parsed.search === '' && parsed.hash === ''
+    return exact && parsed.protocol === 'https:' && parsed.hostname === host && Number(path?.[1]) === number
+  } catch {
+    return false
+  }
+}
+
+/** One entry of `gh pr list --json <PULL_REQUEST_FIELDS>` whose link is the pull request's own page on `host`. */
+export const isGhPullRequest = (value: unknown, host: string): value is GhPullRequest => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    typeof candidate.number === 'number' &&
+    typeof candidate.title === 'string' &&
+    typeof candidate.url === 'string' &&
+    isPullRequestPage(candidate.url, candidate.number, host) &&
+    typeof candidate.headRefName === 'string' &&
+    typeof candidate.isDraft === 'boolean' &&
+    (candidate.statusCheckRollup === null || Array.isArray(candidate.statusCheckRollup))
+  )
+}
+
+/**
+ * Reads the JSON of `gh pr list --json <PULL_REQUEST_FIELDS>`. Throws on anything else, including a
+ * link that is not the pull request's own page on `host`: the view opens these links on a click.
+ * Titles and branch names come from whoever opened the pull request and are made terminal-safe here.
+ */
+export const parsePullRequests = (json: string, host = 'github.com'): PullRequest[] => {
+  const answer: unknown = JSON.parse(json)
+  const valid = Array.isArray(answer) && answer.every((entry) => isGhPullRequest(entry, host))
+  if (!valid) throw new Error('gh pr list: unexpected answer')
+  return (answer as GhPullRequest[]).map((pullRequest) => ({
+    number: pullRequest.number,
+    title: terminalSafe(pullRequest.title),
+    url: pullRequest.url,
+    branch: terminalSafe(pullRequest.headRefName),
+    draft: pullRequest.isDraft,
+    checks: checksOf(pullRequest.statusCheckRollup ?? []),
+  }))
+}
+
+export const pullRequestsByBranch = (pullRequests: readonly PullRequest[]): Map<string, PullRequest[]> =>
+  pullRequests.reduce(
+    (byBranch, pullRequest) =>
+      byBranch.set(pullRequest.branch, [...(byBranch.get(pullRequest.branch) ?? []), pullRequest]),
+    new Map<string, PullRequest[]>(),
+  )
+
+/** The selection key of a pull request row; two parts, so it never equals a three-part phase key. */
+export const pullRequestKey = (number: number): string => `pr:${number}`
+
+/** The link behind a row key, or null when the key is a phase or a pull request no longer open. */
+export const pullRequestUrl = (pullRequests: readonly PullRequest[], key: string): string | null =>
+  pullRequests.find((pullRequest) => pullRequestKey(pullRequest.number) === key)?.url ?? null

package/src/plans/restart-decision.ts

@@ -0,0 +1,42 @@
+import { constants } from 'node:os'
+
+export const CHILD_MARKER = 'JACKHERD_PLANS_CHILD'
+
+/** Milliseconds a burst of file changes is collapsed into one restart. */
+export const RESTART_DEBOUNCE_MS = 300
+
+/** Whether a change to `path` (relative to the package's `src/`) makes the running view stale. */
+export const isRestartTrigger = (path: string): boolean => {
+  const segments = path.split(/[\\/]/)
+  if (segments.includes('node_modules')) return false
+  return path.endsWith('.ts') && !path.endsWith('.test.ts') && !path.endsWith('.d.ts')
+}
+
+/** Whether this process is the supervised view rather than the supervisor. */
+export const isSupervisedChild = (env: Record<string, string | undefined>): boolean => env[CHILD_MARKER] === '1'
+
+export type ChildExit = {
+  restarting: boolean
+  stopping: boolean
+  code: number | null
+  signal: NodeJS.Signals | null
+}
+
+export type NextStep = 'respawn' | 'wait' | 'exit'
+
+/**
+ * What the supervisor does once the child has ended. Only a wanted end stops it: a forwarded
+ * signal (`stopping`) or a clean exit code 0 (`q`, Ctrl-C in raw mode). A restart we asked for
+ * respawns; any other end is a crash, and the supervisor waits for the next change to the source.
+ */
+export const nextStep = ({ restarting, stopping, code }: ChildExit): NextStep => {
+  if (stopping) return 'exit'
+  if (restarting) return 'respawn'
+  return code === 0 ? 'exit' : 'wait'
+}
+
+/** The process exit code for a child that ended with `code` or `signal` (shell convention: 128 + signal number). */
+export const exitCodeOf = (code: number | null, signal: NodeJS.Signals | null): number => {
+  if (code !== null) return code
+  return signal ? 128 + (constants.signals[signal] ?? 0) : 0
+}