jackherd 0.0.1 → 1.0.1

package/src/watch/watch-events.ts

@@ -0,0 +1,399 @@
+import { CHECKS, type ChecksState } from '../plans/pull-requests'
+import { type CoordinatorLevel, type CoordinatorReading, isContextLevel, levelStep } from './coordinator-fill'
+import { emptyFeedbackState, FEEDBACK_EVENT, type FeedbackEvent, type FeedbackState, isFeedbackState } from './feedback'
+import { isRecord } from './json-guards'
+import { isLaneLevels, LANE_FILL_EVENT, type LaneFillEvent, type LaneLevels } from './lane-fill'
+import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
+import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
+import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
+import { emptySourceState, isSourceState, SOURCE_EVENT, type SourceEvent, type SourceState } from './sources'
+import { RUN_EVENT, RUN_STATUS, type WorkflowRun } from './workflow-runs'
+
+/** What the coordinator is told besides a lane that stopped. The values are the words of the report. */
+export const WATCH_EVENT = {
+  merged: 'merged',
+  checksFailed: 'checks failed',
+  checksPassed: 'checks passed',
+  deploy: 'deploy',
+  heartbeat: 'heartbeat',
+  ghUnavailable: 'gh unavailable',
+  coordinator: 'coordinator',
+  feedback: FEEDBACK_EVENT,
+  preview: PREVIEW_EVENT,
+  laneFill: LANE_FILL_EVENT,
+  source: SOURCE_EVENT,
+} as const
+
+export type PullRequestObservation = Omit<WatchedPullRequest, 'number' | 'branch'>
+
+/** The settled verdict of a pull request's checks on one head commit, the unit that fires once. */
+export type CheckVerdict = { headCommit: string; checks: ChecksState }
+
+export type PullRequestRecord = PullRequestObservation & {
+  /** The last failed or passed verdict reported; pending and none never replace it. */
+  reportedChecks: CheckVerdict | null
+  /** Seen by the search for the user's own pull requests on a branch without a lane; kept until the record drops out. */
+  own?: true
+}
+
+export type PullRequestSnapshot = WatchedPullRequest
+
+/**
+ * Everything the watcher remembers between returns. A lane, pull request number or run ID without an
+ * entry has never been seen, and its first sighting is a baseline, not an event.
+ */
+export type WatchState = {
+  seenSeqs: SeenSeqs
+  pullRequests: Record<string, PullRequestRecord>
+  /** Per run ID: whether the run had completed when it was last seen. */
+  runs: Record<string, boolean>
+  /** Epoch milliseconds of the first failed `gh` call of the current streak; null while `gh` answers. */
+  ghDownSince: number | null
+  /** Epoch milliseconds of the last state recorded from an answering `gh`; null before the first one. */
+  savedAt: number | null
+  /**
+   * Lane → branch, kept while the lane is watched or a pull request of the branch is still listed:
+   * a deploy run that ends after its lane was closed still finds the lane's merge commit.
+   */
+  laneBranches: Record<string, string>
+  /** The coordinator's level when it was last read with a value; null before the first one (counts as `ok`). */
+  coordinatorLevel: CoordinatorLevel | null
+  /** The feedback seen on the lanes' open pull requests; kept apart from `pullRequests`, it is read over REST. */
+  feedback: FeedbackState
+  /** The previews seen on the lanes' open pull requests: per pull request the head last reported and the source versions. */
+  previews: PreviewState
+  /** The context level last read for each watched lane's agent; a rise above it fires `lane <name> <level>`. */
+  laneLevels: LaneLevels
+  /** Per configured source of `watch.sources`: the entries seen (`[id, fingerprint]`) and the start of a failure streak. */
+  sources: SourceState
+  /** Lane → change time of the report file last shown for it, null when it had none; a lane without an entry is unseen. */
+  reportMtimes: Record<string, number | null>
+  /** The lane lines of the status block last printed; null before the first report. */
+  statusLines: string[] | null
+}
+
+/** The kinds of the events a pull request fires. */
+export const PULL_REQUEST_KINDS = [WATCH_EVENT.merged, WATCH_EVENT.checksFailed, WATCH_EVENT.checksPassed] as const
+
+/** A lane's pull request, or an own one without a lane, which names its branch instead. */
+export type PullRequestEvent = {
+  kind: (typeof PULL_REQUEST_KINDS)[number]
+  number: number
+  headCommit: string
+  mergeCommit: string | null
+} & ({ lane: string } | { lane: null; branch: string })
+
+/** A run of a lane's merge, or without a lane: of an own pull request's merge (`pullRequest`), else started by hand. */
+export type DeployEvent = {
+  kind: typeof WATCH_EVENT.deploy
+  runId: number
+  trigger: string
+  conclusion: string | null
+} & ({ lane: string } | { lane: null; pullRequest?: number })
+
+export type SignalEvent =
+  | { kind: typeof WATCH_EVENT.heartbeat }
+  | { kind: typeof WATCH_EVENT.ghUnavailable; reason: string }
+
+export type CoordinatorEvent = { kind: typeof WATCH_EVENT.coordinator } & CoordinatorReading
+
+export type WatchEvent =
+  | PullRequestEvent
+  | DeployEvent
+  | SignalEvent
+  | CoordinatorEvent
+  | FeedbackEvent
+  | PreviewEvent
+  | LaneFillEvent
+  | SourceEvent
+
+export const isPullRequestEvent = (event: WatchEvent): event is PullRequestEvent =>
+  (PULL_REQUEST_KINDS as readonly string[]).includes(event.kind)
+
+/** `github` is null when `gh` failed; the pull requests and runs of the last good answer then stay as they were. */
+export type Observation = {
+  lanes: LaneSnapshot
+  /** The branch checked out in each watched lane's worktree. */
+  laneBranches: Record<string, string>
+  github: {
+    pullRequests: readonly PullRequestSnapshot[]
+    runs: readonly WorkflowRun[]
+    /** The numbers of the user's own open pull requests without a lane; none when left out. */
+    own?: readonly number[]
+  } | null
+}
+
+export const emptyWatchState = (): WatchState => ({
+  seenSeqs: {},
+  pullRequests: {},
+  runs: {},
+  ghDownSince: null,
+  savedAt: null,
+  laneBranches: {},
+  coordinatorLevel: null,
+  feedback: emptyFeedbackState(),
+  previews: emptyPreviewState(),
+  laneLevels: {},
+  sources: emptySourceState(),
+  reportMtimes: {},
+  statusLines: null,
+})
+
+const isOneOf = (values: Record<string, string>, value: unknown): boolean =>
+  typeof value === 'string' && Object.values(values).includes(value)
+
+/** A sequence or an epoch time: a number, or null when there is none yet. */
+const isSeq = (value: unknown): value is number | null => value === null || typeof value === 'number'
+
+const everyValue = (value: unknown, check: (entry: unknown) => boolean): boolean =>
+  isRecord(value) && Object.values(value).every(check)
+
+const isCheckVerdict = (value: unknown): boolean =>
+  isRecord(value) && typeof value.headCommit === 'string' && isOneOf(CHECKS, value.checks)
+
+const isPullRequestRecord = (value: unknown): boolean =>
+  isRecord(value) &&
+  isOneOf(PULL_REQUEST_STATE, value.state) &&
+  isOneOf(CHECKS, value.checks) &&
+  typeof value.headCommit === 'string' &&
+  (value.mergeCommit === null || typeof value.mergeCommit === 'string') &&
+  (value.reportedChecks === null || isCheckVerdict(value.reportedChecks)) &&
+  (value.own === undefined || value.own === true)
+
+const isWatchState = (value: Record<string, unknown>): value is WatchState =>
+  everyValue(value.seenSeqs, isSeq) &&
+  everyValue(value.pullRequests, isPullRequestRecord) &&
+  everyValue(value.runs, (entry) => typeof entry === 'boolean') &&
+  isSeq(value.ghDownSince) &&
+  isSeq(value.savedAt) &&
+  everyValue(value.laneBranches, (entry) => typeof entry === 'string') &&
+  (value.coordinatorLevel === null || isContextLevel(value.coordinatorLevel)) &&
+  isFeedbackState(value.feedback) &&
+  isPreviewState(value.previews) &&
+  isLaneLevels(value.laneLevels) &&
+  isSourceState(value.sources) &&
+  everyValue(value.reportMtimes, isSeq) &&
+  (value.statusLines === null ||
+    (Array.isArray(value.statusLines) && value.statusLines.every((line) => typeof line === 'string')))
+
+/**
+ * Reads the state file; throws on any other shape, so a damaged file is seen, not read as empty. The
+ * flat `Record<lane, seq>` of the earlier watcher is taken over as the seen sequences.
+ */
+export const parseWatchState = (json: string): WatchState => {
+  const value: unknown = JSON.parse(json)
+  if (!isRecord(value)) throw new Error('watch state: unexpected shape')
+  if (isRecord(value.seenSeqs)) {
+    const complete = {
+      savedAt: null,
+      laneBranches: {},
+      coordinatorLevel: null,
+      feedback: emptyFeedbackState(),
+      previews: emptyPreviewState(),
+      laneLevels: {},
+      sources: emptySourceState(),
+      reportMtimes: {},
+      statusLines: null,
+      ...value,
+    }
+    if (!isWatchState(complete)) throw new Error('watch state: unexpected shape')
+    return complete
+  }
+  if (!Object.values(value).every(isSeq)) throw new Error('watch state: unexpected shape')
+  return { ...emptyWatchState(), seenSeqs: value as SeenSeqs }
+}
+
+const isSettled = (checks: ChecksState): boolean => checks === CHECKS.failed || checks === CHECKS.passed
+
+const reportedChecksOf = (known: PullRequestRecord | undefined, observed: PullRequestSnapshot): CheckVerdict | null =>
+  isSettled(observed.checks)
+    ? { headCommit: observed.headCommit, checks: observed.checks }
+    : (known?.reportedChecks ?? null)
+
+const recordsOf = (
+  previous: WatchState,
+  pullRequests: readonly PullRequestSnapshot[],
+  own: readonly number[],
+): Record<string, PullRequestRecord> =>
+  Object.fromEntries(
+    pullRequests.map((observed) => {
+      const { number, state, checks, headCommit, mergeCommit } = observed
+      const known = previous.pullRequests[String(number)]
+      const reportedChecks = reportedChecksOf(known, observed)
+      const isOwn = known?.own === true || own.includes(number)
+      return [String(number), { state, checks, headCommit, mergeCommit, reportedChecks, ...(isOwn && { own: true }) }]
+    }),
+  )
+
+/** The remembered lane branches plus the observed ones, minus those of lanes no longer watched whose branch has no listed pull request. */
+const keptLaneBranches = (
+  previous: WatchState,
+  observation: Observation,
+  pullRequests: readonly PullRequestSnapshot[],
+): Record<string, string> => {
+  const listed = new Set(pullRequests.map((pullRequest) => pullRequest.branch))
+  const all = { ...previous.laneBranches, ...observation.laneBranches }
+  return Object.fromEntries(
+    Object.entries(all).filter(([lane, branch]) => lane in observation.laneBranches || listed.has(branch)),
+  )
+}
+
+const runsOf = (runs: readonly WorkflowRun[]): Record<string, boolean> =>
+  Object.fromEntries(runs.map((run) => [String(run.id), run.status === RUN_STATUS.completed]))
+
+/**
+ * The state to save after an observation: every observed lane, pull request and run, whether or not
+ * it fired. Entries that dropped out of the listings are forgotten.
+ */
+export const recordWatchState = (previous: WatchState, observation: Observation, now: number): WatchState => {
+  const { lanes, github } = observation
+  if (!github) {
+    const laneBranches = { ...previous.laneBranches, ...observation.laneBranches }
+    return { ...previous, seenSeqs: seenSeqsOf(lanes), ghDownSince: previous.ghDownSince ?? now, laneBranches }
+  }
+  return {
+    seenSeqs: seenSeqsOf(lanes),
+    pullRequests: recordsOf(previous, github.pullRequests, github.own ?? []),
+    runs: runsOf(github.runs),
+    ghDownSince: null,
+    savedAt: now,
+    laneBranches: keptLaneBranches(previous, observation, github.pullRequests),
+    coordinatorLevel: previous.coordinatorLevel,
+    feedback: previous.feedback,
+    previews: previous.previews,
+    laneLevels: previous.laneLevels,
+    sources: previous.sources,
+    reportMtimes: previous.reportMtimes,
+    statusLines: previous.statusLines,
+  }
+}
+
+/**
+ * The report times of the watched lanes only: a known lane keeps its time, a lane seen for the first time takes the
+ * report already there as its baseline (`mtimeOf`), so an old file never reads as new; a lane no longer watched is
+ * forgotten and starts afresh when it comes back.
+ */
+export const withReportBaselines = (
+  state: WatchState,
+  lanes: readonly string[],
+  mtimeOf: (lane: string) => number | null,
+): WatchState => ({
+  ...state,
+  reportMtimes: Object.fromEntries(
+    lanes.map((lane) => [lane, lane in state.reportMtimes ? (state.reportMtimes[lane] ?? null) : mtimeOf(lane)]),
+  ),
+})
+
+/** The state with the coordinator's level of `reading` stored; no reading keeps the stored level. */
+export const recordCoordinatorLevel = (state: WatchState, reading: CoordinatorReading | null): WatchState => ({
+  ...state,
+  coordinatorLevel: levelStep(state.coordinatorLevel, reading?.level ?? null).level,
+})
+
+/** Fires when the coordinator's level rose to `warn` or `alert` since `previous` (see `levelStep`). */
+export const coordinatorWatchEvent = (
+  previous: WatchState,
+  reading: CoordinatorReading | null,
+): CoordinatorEvent | null =>
+  reading && levelStep(previous.coordinatorLevel, reading.level).fire
+    ? { kind: WATCH_EVENT.coordinator, ...reading }
+    : null
+
+const settledChecksKind = (checks: ChecksState): PullRequestEvent['kind'] | null => {
+  if (checks === CHECKS.failed) return WATCH_EVENT.checksFailed
+  return checks === CHECKS.passed ? WATCH_EVENT.checksPassed : null
+}
+
+const isReported = (known: PullRequestRecord, observed: PullRequestSnapshot): boolean =>
+  known.reportedChecks?.headCommit === observed.headCommit && known.reportedChecks.checks === observed.checks
+
+const eventKindOf = (known: PullRequestRecord, observed: PullRequestSnapshot): PullRequestEvent['kind'] | null => {
+  if (observed.state === PULL_REQUEST_STATE.merged)
+    return known.state === PULL_REQUEST_STATE.merged ? null : WATCH_EVENT.merged
+  if (observed.state !== PULL_REQUEST_STATE.open || isReported(known, observed)) return null
+  return settledChecksKind(observed.checks)
+}
+
+const laneOfBranch = (laneBranches: Readonly<Record<string, string>>, branch: string): string | undefined =>
+  Object.keys(laneBranches).find((lane) => laneBranches[lane] === branch)
+
+/**
+ * The merges and settled checks of the lanes' pull requests since `previous`, and of the user's own pull requests on
+ * a branch without a lane, which name their branch. A pull request number never seen is a baseline, and so is an own
+ * one the state does not mark as own yet. Checks fire once per head commit and settled verdict: a new head commit
+ * fires when its checks settle, not while they are pending, and pending never clears what was reported.
+ */
+export const pullRequestEvents = (
+  previous: WatchState,
+  current: readonly PullRequestSnapshot[],
+  laneBranches: Readonly<Record<string, string>>,
+): PullRequestEvent[] =>
+  current.flatMap((pullRequest) => {
+    const lane = laneOfBranch(laneBranches, pullRequest.branch)
+    const known = previous.pullRequests[String(pullRequest.number)]
+    const followed = lane !== undefined || known?.own === true
+    const kind = followed && known ? eventKindOf(known, pullRequest) : null
+    if (!kind) return []
+    const { number, headCommit, mergeCommit, branch } = pullRequest
+    const owner = lane === undefined ? { lane: null, branch } : { lane }
+    return [{ kind, ...owner, number, headCommit, mergeCommit }]
+  })
+
+/** The lane each merge commit belongs to, for matching deploy runs to a lane's merge. */
+export const mergeCommitsOf = (
+  pullRequests: readonly PullRequestSnapshot[],
+  laneBranches: Readonly<Record<string, string>>,
+): Record<string, string> =>
+  Object.fromEntries(
+    pullRequests.flatMap(({ branch, mergeCommit }) => {
+      const lane = laneOfBranch(laneBranches, branch)
+      return lane && mergeCommit ? [[mergeCommit, lane]] : []
+    }),
+  )
+
+/** The number of the own pull request without a lane each merge commit belongs to, for matching deploy runs. */
+export const ownMergeCommitsOf = (
+  previous: WatchState,
+  pullRequests: readonly PullRequestSnapshot[],
+  laneBranches: Readonly<Record<string, string>>,
+): Record<string, number> =>
+  Object.fromEntries(
+    pullRequests.flatMap(({ number, branch, mergeCommit }) => {
+      const own = previous.pullRequests[String(number)]?.own === true
+      return own && mergeCommit && !laneOfBranch(laneBranches, branch) ? [[mergeCommit, number]] : []
+    }),
+  )
+
+const wasOpen = (previous: WatchState, run: WorkflowRun): boolean => {
+  const completedBefore = previous.runs[String(run.id)]
+  if (completedBefore !== undefined) return !completedBefore
+  return previous.savedAt !== null && Date.parse(run.createdAt) >= previous.savedAt
+}
+
+/**
+ * The deploy runs that completed since `previous`, any conclusion included (a cancelled run is news).
+ * A run counts when its head commit is the merge commit of a lane or of an own pull request without a lane
+ * (`ownMergeCommits`, merge commit → number), or when someone started it by hand.
+ * A run that had already completed does not fire again. A run ID never seen is a baseline,
+ * unless it was created after the last saved state: it started and ended between two returns and counts as open.
+ */
+export const deployEvents = (
+  previous: WatchState,
+  runs: readonly WorkflowRun[],
+  mergeCommits: Readonly<Record<string, string>>,
+  ownMergeCommits: Readonly<Record<string, number>>,
+): DeployEvent[] =>
+  runs.flatMap((run) => {
+    const lane = mergeCommits[run.headSha] ?? null
+    const pullRequest = lane === null ? ownMergeCommits[run.headSha] : undefined
+    const relevant = lane !== null || pullRequest !== undefined || run.event === RUN_EVENT.workflowDispatch
+    if (!wasOpen(previous, run) || run.status !== RUN_STATUS.completed || !relevant) return []
+    const deploy = { kind: WATCH_EVENT.deploy, runId: run.id, trigger: run.event, conclusion: run.conclusion, lane }
+    return [pullRequest === undefined ? deploy : { ...deploy, pullRequest }]
+  })
+
+/** Fires once, at the first failed `gh` read of a streak (`error` is its reason); a streak that has begun is already known. */
+export const ghOutageEvent = (previous: WatchState, error: string | null): SignalEvent | null =>
+  error !== null && previous.ghDownSince === null ? { kind: WATCH_EVENT.ghUnavailable, reason: error } : null
+
+export const isHeartbeatDue = (armedAt: number, now: number, intervalMs: number): boolean => now - armedAt >= intervalMs

package/src/watch/watcher-lock.ts

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { CLI_NAME, PACKAGE_NAME } from '../version/release'
+
+/** Looks up the command line of a process; null when there is no such process. */
+export type CommandLineOf = (pid: number) => string | null
+
+/** What taking the lock did to a watcher that held it: stopped it, or found it still running after the wait. */
+export type TakeOver = { replaced: number | null; stillRunning: number | null }
+
+/** The CLI's entry by source path or bin link (`jh`, and `jackherd` for `bunx jackherd`); `agent-kit` until 2.0.0, so a watcher of the old CLI is replaced. */
+const CLI_ENTRIES = ['cli.ts', CLI_NAME, PACKAGE_NAME, 'agent-kit']
+const WATCH_COMMAND = 'watch'
+const RUNTIME = 'bun'
+const DIRECTORY_PREFIX = 'jackherd-watch'
+const KEY_HASH_LENGTH = 12
+const NOT_A_SEGMENT = /[^A-Za-z0-9._-]+/g
+const PRIVATE_DIRECTORY = 0o700
+const PRIVATE_FILE = 0o600
+const STOP_WAIT_MS = 5_000
+const STOP_POLL_MS = 50
+
+export const WATCHER_FILES = { state: 'watch-state.json', lock: 'watch.lock' } as const
+
+/** The process ID a lock file holds, or null for a missing, empty or damaged file. */
+export const lockedPid = (content: string | null): number | null => {
+  const pid = Number.parseInt(content?.trim() ?? '', 10)
+  return Number.isInteger(pid) && pid > 0 ? pid : null
+}
+
+/**
+ * True for `bun <…/cli.ts|…/jh> watch …`: the runtime first, the kit's CLI as an argument of its own and
+ * `watch` right after it; not an editor, a pager or another command of the CLI.
+ */
+export const isWatcherCommand = (commandLine: string): boolean => {
+  const [program, ...args] = commandLine.trim().split(/\s+/)
+  if (basename(program ?? '') !== RUNTIME) return false
+  const entry = args.findIndex((arg) => CLI_ENTRIES.includes(basename(arg)))
+  return entry !== -1 && args[entry + 1] === WATCH_COMMAND
+}
+
+/**
+ * The watcher to stop before this one takes the lock, or null. Only a process whose command line
+ * runs `jh watch` is ever named: a process ID is reused after its process ends, and a signal
+ * must never reach whatever holds the number now.
+ */
+export const supersedeTarget = (
+  content: string | null,
+  ownPid: number,
+  commandLineOf: CommandLineOf,
+): number | null => {
+  const pid = lockedPid(content)
+  if (pid === null || pid === ownPid) return null
+  const commandLine = commandLineOf(pid)
+  return commandLine !== null && isWatcherCommand(commandLine) ? pid : null
+}
+
+/** What a watcher that received SIGTERM prints: who replaced it, or that it was stopped from outside. */
+export const stopNotice = (content: string | null, ownPid: number): string => {
+  const pid = lockedPid(content)
+  return pid !== null && pid !== ownPid ? `superseded by ${pid}` : 'stopped by SIGTERM'
+}
+
+/**
+ * The name of a repository's watcher directory: the checkout's directory name, reduced to a plain path segment,
+ * and the first hex digits of a SHA-256 of its path, so two checkouts of the same name stay apart.
+ */
+export const repositoryKey = (root: string): string => {
+  const name = basename(root).replace(NOT_A_SEGMENT, '-')
+  const hash = createHash('sha256').update(root).digest('hex').slice(0, KEY_HASH_LENGTH)
+  return `${name}-${hash}`
+}
+
+const readText = (file: string): string | null => {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const commandLineOf: CommandLineOf = (pid) => {
+  const result = Bun.spawnSync(['ps', '-o', 'command=', '-p', String(pid)], { stdout: 'pipe', stderr: 'ignore' })
+  return result.exitCode === 0 ? result.stdout.toString().trim() || null : null
+}
+
+const isAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Where `ensureWatcherDirectory` puts the watcher's files, without creating anything: for readers such as the plans view. */
+export const watcherDirectoryOf = (root: string): string =>
+  join(tmpdir(), `${DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`, repositoryKey(root))
+
+/**
+ * The directory for the lock and state of the watcher of the repository at `root`, one per user and repository,
+ * readable by that user only: with `TMPDIR` unset, `tmpdir()` is the shared `/tmp`, where another account could
+ * plant the files. A watcher in another repository has its own lock and does not supersede this one.
+ */
+export const ensureWatcherDirectory = (root: string): string => {
+  const directory = watcherDirectoryOf(root)
+  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  return directory
+}
+
+/** Whether the lock names a live process that is a watcher, so its saved state is being kept up to date. */
+export const isWatcherRunning = (lockFile: string, lookUp: CommandLineOf = commandLineOf): boolean => {
+  const pid = lockedPid(readText(lockFile))
+  return pid !== null && isAlive(pid) && isWatcherCommand(lookUp(pid) ?? '')
+}
+
+/** Writes a file only the user can read. */
+export const writePrivate = (file: string, content: string) => writeFileSync(file, content, { mode: PRIVATE_FILE })
+
+/**
+ * Takes the lock for this process. A watcher that held it gets SIGTERM and is waited for, so the state
+ * file it writes on the way out is complete before this one reads it.
+ */
+export const takeOverLock = async (lockFile: string): Promise<TakeOver> => {
+  const previous = supersedeTarget(readText(lockFile), process.pid, commandLineOf)
+  writePrivate(lockFile, String(process.pid))
+  if (previous === null || !isAlive(previous)) return { replaced: null, stillRunning: null }
+  try {
+    process.kill(previous, 'SIGTERM')
+  } catch {
+    return { replaced: null, stillRunning: null }
+  }
+  const deadline = Date.now() + STOP_WAIT_MS
+  while (isAlive(previous) && Date.now() < deadline) await Bun.sleep(STOP_POLL_MS)
+  return isAlive(previous) ? { replaced: null, stillRunning: previous } : { replaced: previous, stillRunning: null }
+}
+
+export const stopNoticeOf = (lockFile: string): string => stopNotice(readText(lockFile), process.pid)
+
+/** Removes the lock only while it still names this process; a successor's lock stays. */
+export const releaseLock = (lockFile: string) => {
+  if (lockedPid(readText(lockFile)) === process.pid) rmSync(lockFile, { force: true })
+}

package/src/watch/workflow-runs.ts

@@ -0,0 +1,96 @@
+import type { JackherdConfig } from '../config'
+import { isRecord, parseArray } from './json-guards'
+
+/** Which workflow's runs are deploys, and which environments count as their target (`watch.deploy`). */
+export type DeployConfig = NonNullable<JackherdConfig['watch']['deploy']>
+
+/** The statuses of a run in `gh run list --json status`. */
+export const RUN_STATUS = { queued: 'queued', inProgress: 'in_progress', completed: 'completed' } as const
+
+/** The triggers of a run in `gh run list --json event` a deploy workflow answers to. */
+export const RUN_EVENT = { push: 'push', workflowRun: 'workflow_run', workflowDispatch: 'workflow_dispatch' } as const
+
+/** `conclusion` is null while a run is open; `createdAt` is ISO 8601. */
+export type WorkflowRun = {
+  id: number
+  event: string
+  headSha: string
+  status: string
+  conclusion: string | null
+  createdAt: string
+}
+
+/** A GitHub deployment of a commit; its statuses point at the run that made it. */
+type Deployment = { id: number; environment: string }
+
+type GhWorkflowRun = {
+  databaseId: number
+  event: string
+  headSha: string
+  status: string
+  conclusion: string
+  createdAt: string
+}
+
+/** The fields `parseWorkflowRuns` reads; pass them to `gh run list --json`. */
+export const WORKFLOW_RUN_FIELDS = 'databaseId,event,headSha,status,conclusion,createdAt'
+
+const RUN_LIMIT = '20'
+
+const RUN_LOG_PATH = /\/actions\/runs\/(\d+)\//
+
+const isGhWorkflowRun = (value: unknown): value is GhWorkflowRun =>
+  isRecord(value) &&
+  typeof value.databaseId === 'number' &&
+  typeof value.event === 'string' &&
+  typeof value.headSha === 'string' &&
+  typeof value.status === 'string' &&
+  typeof value.conclusion === 'string' &&
+  typeof value.createdAt === 'string'
+
+const isDeployment = (value: unknown): value is Deployment =>
+  isRecord(value) && typeof value.id === 'number' && typeof value.environment === 'string'
+
+/**
+ * Reads the JSON of `gh run list --json <WORKFLOW_RUN_FIELDS>`; throws on anything else. `gh` sends an
+ * open run's conclusion as an empty string, which becomes null here.
+ */
+export const parseWorkflowRuns = (json: string): WorkflowRun[] =>
+  parseArray(json, isGhWorkflowRun, 'gh run list').map((run) => ({
+    id: run.databaseId,
+    event: run.event,
+    headSha: run.headSha,
+    status: run.status,
+    conclusion: run.conclusion || null,
+    createdAt: run.createdAt,
+  }))
+
+/** Reads `[{id, environment}]` as `gh api …/deployments --jq '[.[] | {id, environment}]'` prints it. */
+export const parseDeployments = (json: string): Deployment[] => parseArray(json, isDeployment, 'gh api deployments')
+
+/** True for an environment the config names as a target; any other name in a deployment is not taken as one. */
+export const isDeployTarget = (environment: string, environments: readonly string[]): boolean =>
+  environments.includes(environment)
+
+/** The `gh` arguments that list the deploy workflow's runs on the base branch; null when the project reports no deploys. */
+export const runListArgs = (deploy: DeployConfig | undefined, baseBranch: string): string[] | null =>
+  deploy
+    ? [
+        'run',
+        'list',
+        '--workflow',
+        deploy.workflow,
+        '--branch',
+        baseBranch,
+        '--limit',
+        RUN_LIMIT,
+        '--json',
+        WORKFLOW_RUN_FIELDS,
+      ]
+    : null
+
+/** The run ID a deployment status's `log_url` (`…/actions/runs/<id>/job/<job>`) points at, or null. */
+export const runIdOfLogUrl = (logUrl: string): number | null => {
+  const match = logUrl.match(RUN_LOG_PATH)
+  return match ? Number(match[1]) : null
+}