jackherd 1.9.0 → 1.10.0

package/src/plans/closable-records.ts

@@ -0,0 +1,34 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+
+/** A record that waits on the user until something sets `closedAt`. */
+export type ClosableRecord = { id: string; closedAt: number | null }
+
+export type ClosableRecordLog<T extends ClosableRecord> = {
+  /** Every record of the log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
+  read: (root: string) => T[]
+  /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+  close: (root: string, ids: readonly string[], now: number) => number
+  /** Marks every open record `closedAt` and returns how many it closed. */
+  closeAll: (root: string, now: number) => number
+}
+
+/** The log of `.jackherd/<directoryName>/`: records the `guard` accepts, ordered by `timeOf`. */
+export const closableRecordLog = <T extends ClosableRecord>(
+  directoryName: string,
+  guard: (value: unknown) => value is T,
+  timeOf: (record: T) => number,
+): ClosableRecordLog<T> => {
+  const directoryOf = (root: string): string => join(root, '.jackherd', directoryName)
+  const read = (root: string): T[] => readRecords(directoryOf(root), guard, timeOf)
+  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number): number => {
+    const open = read(root).filter((record) => record.closedAt === null && isChosen(record))
+    for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+    return open.length
+  }
+  return {
+    read,
+    close: (root, ids, now) => closeWhere(root, (record) => ids.includes(record.id), now),
+    closeAll: (root, now) => closeWhere(root, () => true, now),
+  }
+}

package/src/plans/command.ts

@@ -6,6 +6,7 @@ import { boardFor, foundLanesOf } from './board-pick'
 import { ensurePlanPanes } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
+import { claimOwnTerminal, startExclusive } from './herd-claim'
 import { recallLanes, rememberLanes } from './herd-memory'
 import { runLive } from './live'
 import { parseOptions } from './options'
@@ -59,8 +60,8 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     }
     const source = { root, sprintFile: picked.file, options, settings, terminal }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)
-    else if (isSupervisedChild(process.env)) runLive(source)
-    else return await superviseView(args, await startedKit())
+    else if (isSupervisedChild(process.env)) await startExclusive(claimOwnTerminal, () => runLive(source))
+    else process.exit(await superviseView(args, await startedKit()))
     return 0
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/src/plans/fetch.ts

@@ -1,5 +1,7 @@
 import { errorText } from './error-text'
 import type { PullRequestState } from './github'
+import { pullHeadRefspec } from './plan-heads'
+import type { PullRequest } from './pull-requests'
 
 /** The background fetch of the base branch: when it last ran, when it last worked and why it failed. */
 export type FetchState = {
@@ -70,12 +72,13 @@ export const fetchNotice = (state: FetchState, baseRef: string, locale: string):
   return `fetch failed (${state.failure}), reading ${baseRef} as it is: ${known}`
 }
 
-/** Fetches the base branch; returns the reason when it did not work, null when it did. Never rejects. */
-export const fetchBase = async (root: string, remote: string, branch: string): Promise<string | null> => {
+/** Fetches `refspecs` from `remote` in one call; returns the reason when it did not work, null when it did or there was nothing to fetch. Never rejects. */
+export const fetchRefs = async (root: string, remote: string, refspecs: readonly string[]): Promise<string | null> => {
+  if (refspecs.length === 0) return null
   let timedOut = false
   let timer: Timer | undefined
   try {
-    const child = Bun.spawn(['git', '-C', root, 'fetch', '--quiet', remote, branch], {
+    const child = Bun.spawn(['git', '-C', root, 'fetch', '--quiet', remote, ...refspecs], {
       stdout: 'ignore',
       stderr: 'pipe',
       env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
@@ -94,3 +97,23 @@ export const fetchBase = async (root: string, remote: string, branch: string): P
     clearTimeout(timer)
   }
 }
+
+/** Fetches the base branch; returns the reason when it did not work, null when it did. Never rejects. */
+export const fetchBase = (root: string, remote: string, branch: string): Promise<string | null> =>
+  fetchRefs(root, remote, [branch])
+
+/**
+ * Fetches the heads of the given pull requests into the herd's own refs (`pullHeadRef`), in one call after the base.
+ * A failure is not reported: a head that was not fetched reads nothing, and the plan stays as the base has it.
+ */
+export const fetchPlanHeads = async (
+  root: string,
+  remote: string,
+  pullRequests: readonly Pick<PullRequest, 'number'>[],
+): Promise<void> => {
+  await fetchRefs(
+    root,
+    remote,
+    pullRequests.map(({ number }) => pullHeadRefspec(number)),
+  )
+}

package/src/plans/git.ts

@@ -35,18 +35,32 @@ export const commitOf = (root: string, ref: string): string | null =>
 /** Reads files as they are at the base ref. */
 export type BaseReader = (path: string) => string | null
 
-let cached: { root: string; commit: string; texts: Map<string, string> } | null = null
+/** How many commits keep their texts: the base ref and the heads of the open pull requests that change a plan. */
+const CACHED_COMMITS = 16
+
+/** The texts read per `root\0commit`, the one asked last at the end. */
+const cachedTexts = new Map<string, Map<string, string>>()
+
+const textsOf = (root: string, commit: string): Map<string, string> => {
+  const key = `${root}\0${commit}`
+  const texts = cachedTexts.get(key) ?? new Map<string, string>()
+  cachedTexts.delete(key)
+  cachedTexts.set(key, texts)
+  const oldest = cachedTexts.keys().next().value
+  if (cachedTexts.size > CACHED_COMMITS && oldest !== undefined) cachedTexts.delete(oldest)
+  return texts
+}
 
 /**
  * A reader for the files at `ref`, with the commit resolved once. A file at a commit never changes, so what was
- * read is kept for as long as the ref points at the same commit: a re-read of the sprint costs one `git
- * rev-parse` instead of one `git show` per plan.
+ * read is kept for as long as the commit is among the last `CACHED_COMMITS` asked: a re-read of the sprint costs
+ * one `git rev-parse` per ref instead of one `git show` per plan, and the base and the pull request heads read in
+ * the same round do not evict each other.
  */
 export const baseReaderOf = (root: string, ref: string): BaseReader => {
   const commit = commitOf(root, ref)
   if (commit === null) return () => null
-  if (cached?.root !== root || cached.commit !== commit) cached = { root, commit, texts: new Map() }
-  const { texts } = cached
+  const texts = textsOf(root, commit)
   return (path) => {
     const kept = texts.get(path)
     if (kept !== undefined) return kept

package/src/plans/herd-claim.ts

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, readlinkSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import {
+  type LocationSystem,
+  readPrivateText,
+  runtimeBaseOf,
+  systemLocation,
+  userDirectoryOf,
+} from '../shared/private-location'
+import { HERD_COMMAND } from './herd-command'
+import { CHILD_MARKER, TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
+
+const DIRECTORY_PREFIX = 'jackherd-herd'
+const POLL_MS = 50
+const POLLS_BEFORE_KILL = 20
+
+export type ClaimDeps = {
+  selfPid: number
+  prepare: () => void
+  readRecord: () => string | null
+  writeRecord: (pid: number) => void
+  removeRecordIf: (pid: number) => void
+  isHerdView: (pid: number) => boolean
+  isGone: (pid: number) => boolean
+  signal: (pid: number, signal: NodeJS.Signals) => void
+  sleep: (ms: number) => Promise<void>
+  onExit: (run: () => void) => void
+}
+
+/** A process id as the record file holds it; nothing for anything but a positive integer. */
+export const parsePid = (text: string | null): number | null => {
+  if (text === null || !/^\d+\s*$/.test(text)) return null
+  const pid = Number(text)
+  return pid > 0 ? pid : null
+}
+
+/**
+ * The older herd view of this terminal that has to end before `selfPid` draws: the recorded pid when it is not
+ * this process and still is a herd view (a number the system has reused for something else is not).
+ */
+export const olderHerdToStop = (
+  recorded: number | null,
+  selfPid: number,
+  isHerdView: (pid: number) => boolean,
+): number | null => (recorded === null || recorded === selfPid || !isHerdView(recorded) ? null : recorded)
+
+const endOlderHerd = async (pid: number, deps: ClaimDeps): Promise<void> => {
+  deps.signal(pid, TAKEOVER_SIGNAL)
+  for (let poll = 0; poll < POLLS_BEFORE_KILL; poll++) {
+    if (deps.isGone(pid)) return
+    await deps.sleep(POLL_MS)
+  }
+  if (!deps.isGone(pid) && deps.isHerdView(pid)) deps.signal(pid, 'SIGKILL')
+}
+
+/**
+ * Makes this process the one herd view of its terminal: an older one is sent `TAKEOVER_SIGNAL` and, when it has not ended
+ * after about a second and its pid still is a herd view, SIGKILL; then the own pid is recorded and removed again when the process ends. The claim
+ * directory is verified first: a record in a directory of someone else is never read, and a directory that cannot be
+ * verified throws before anything is read, signalled or written.
+ */
+export const claimTerminal = async (deps: ClaimDeps): Promise<void> => {
+  deps.prepare()
+  const older = olderHerdToStop(parsePid(deps.readRecord()), deps.selfPid, deps.isHerdView)
+  if (older !== null) await endOlderHerd(older, deps)
+  deps.writeRecord(deps.selfPid)
+  deps.onExit(() => deps.removeRecordIf(deps.selfPid))
+}
+
+/** The directory holding the claim records: one private level `jackherd-herd-<uid>` below `runtimeBaseOf`. */
+export const claimDirectoryOf = (system: LocationSystem): string =>
+  userDirectoryOf(runtimeBaseOf(system), DIRECTORY_PREFIX, system.uid)
+
+const exitWhenTakenOver = (): void => {
+  process.on(TAKEOVER_SIGNAL, () => process.exit(TAKEN_OVER_CODE))
+}
+
+/**
+ * Runs `start` once the takeover is done; a takeover that cannot be made (no terminal, no `/proc`) does not stop the
+ * view. `listen` runs first, so a newer herd's takeover signal that arrives while the claim is made ends this process
+ * as a wanted end instead of by the signal's default action; the view replaces that handler with its own.
+ */
+export const startExclusive = async (
+  claim: () => Promise<void>,
+  start: () => void,
+  listen: () => void = exitWhenTakenOver,
+): Promise<void> => {
+  listen()
+  try {
+    await claim()
+  } catch {
+    // the view still starts: one stale herd is better than none
+  }
+  start()
+}
+
+const terminalOfStdin = (): string | null => {
+  try {
+    const target = readlinkSync('/proc/self/fd/0')
+    return target.startsWith('/dev/') ? target : null
+  } catch {
+    return null
+  }
+}
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const isHerdViewProcess = (pid: number): boolean => {
+  const environment = readText(`/proc/${pid}/environ`)
+  const command = readText(`/proc/${pid}/cmdline`)
+  if (environment === null || command === null) return false
+  return environment.split('\0').includes(`${CHILD_MARKER}=1`) && command.split('\0').includes(HERD_COMMAND.name)
+}
+
+const isGoneProcess = (pid: number): boolean => {
+  const stat = readText(`/proc/${pid}/stat`)
+  if (stat === null) return true
+  const stateIndex = stat.lastIndexOf(')') + 2
+  return stat.charAt(stateIndex) === 'Z'
+}
+
+const signalProcess = (pid: number, signal: NodeJS.Signals): void => {
+  try {
+    process.kill(pid, signal)
+  } catch {
+    // already gone
+  }
+}
+
+const recordFileOf = (terminal: string): string =>
+  join(claimDirectoryOf(systemLocation()), `${createHash('sha256').update(terminal).digest('hex').slice(0, 16)}.pid`)
+
+/**
+ * The claim operations for one record file; the claim directory is verified before the record is read or written, and
+ * a record that is a link or a FIFO is not read.
+ */
+export const herdClaimDeps = (file: string): ClaimDeps => ({
+  selfPid: process.pid,
+  prepare: () => ensurePrivateDirectory(join(file, '..')),
+  readRecord: () => readPrivateText(file),
+  writeRecord: (pid) => {
+    ensurePrivateDirectory(join(file, '..'))
+    writePrivateFile(file, `${pid}\n`)
+  },
+  removeRecordIf: (pid) => {
+    try {
+      if (parsePid(readPrivateText(file)) === pid) unlinkSync(file)
+    } catch {
+      // the next herd of this terminal overwrites it
+    }
+  },
+  isHerdView: isHerdViewProcess,
+  isGone: isGoneProcess,
+  signal: signalProcess,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  onExit: (run) => {
+    process.on('exit', run)
+  },
+})
+
+/** Takes the terminal of stdin over from an older herd view; without a terminal (or `/proc`) it does nothing. */
+export const claimOwnTerminal = async (): Promise<void> => {
+  const terminal = terminalOfStdin()
+  if (terminal !== null) await claimTerminal(herdClaimDeps(recordFileOf(terminal)))
+}

package/src/plans/herd-memory.ts

@@ -1,14 +1,19 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { z } from 'zod'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import {
+  ensurePrivateLevels,
+  type LocationSystem,
+  readPrivateText,
+  runtimeBaseOf,
+  systemLocation,
+  userDirectoryOf,
+} from '../shared/private-location'
 import { repositoryKey } from '../watch/watcher-lock'
 import type { LaneMemory } from './current-phase'
 
 const DIRECTORY_PREFIX = 'jackherd-herd'
 const MEMORY_FILE = 'herd-memory.json'
-const PRIVATE_DIRECTORY = 0o700
-const PRIVATE_FILE = 0o600
 
 const phaseRef = z.object({ planHref: z.string(), phaseId: z.string() })
 
@@ -54,41 +59,46 @@ export const mergedMemories = (
  * Where the herds of the repository at `root` keep what they saw of each lane, one directory per user and
  * repository like the watcher's, so a `--once` run and a restarted herd know when a phase last moved.
  */
-const herdMemoryDirectory = (root: string): string =>
-  join(tmpdir(), `${DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`, repositoryKey(root))
+export const herdMemoryDirectoryOf = (root: string, system: LocationSystem): string =>
+  join(userDirectoryOf(runtimeBaseOf(system), DIRECTORY_PREFIX, system.uid), repositoryKey(root))
 
-export const memoryFileOf = (directory: string): string => join(directory, MEMORY_FILE)
-
-const readText = (file: string): string | null => {
-  try {
-    return readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
+/** The memory directory of `root` with both levels verified private (`ensurePrivateLevels`); throws when one is not. */
+const ensureHerdMemoryDirectory = (root: string, system: LocationSystem): string => {
+  const directory = herdMemoryDirectoryOf(root, system)
+  return ensurePrivateLevels(dirname(directory), directory)
 }
 
+export const memoryFileOf = (directory: string): string => join(directory, MEMORY_FILE)
+
 export const readLaneMemories = (directory: string): Map<string, LaneMemory> =>
-  parseLaneMemories(readText(memoryFileOf(directory)))
+  parseLaneMemories(readPrivateText(memoryFileOf(directory)))
 
 /**
  * Writes the memories of `lanes` into the file of `directory`, beside what other herds keep there; readable by the
- * user only, and replaced in one step so a herd reading at the same time never sees half a file.
+ * user only (the directory is verified with `ensurePrivateDirectory`), and replaced in one step through
+ * `writePrivateFile`, so a herd reading at the same time never sees half a file and a planted link is never followed.
  */
 export const writeLaneMemories = (
   directory: string,
   memories: ReadonlyMap<string, LaneMemory>,
   lanes: readonly string[],
 ): void => {
-  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
-  const file = memoryFileOf(directory)
+  ensurePrivateDirectory(directory)
   const merged = mergedMemories(readLaneMemories(directory), memories, lanes)
-  const partial = `${file}.${process.pid}`
-  writeFileSync(partial, JSON.stringify(merged), { mode: PRIVATE_FILE })
-  renameSync(partial, file)
+  writePrivateFile(memoryFileOf(directory), JSON.stringify(merged))
 }
 
-/** The memories the herds of the repository at `root` kept. */
-export const recallLanes = (root: string): Map<string, LaneMemory> => readLaneMemories(herdMemoryDirectory(root))
+/**
+ * The memories the herds of the repository at `root` kept; none when the directory cannot be verified private, so a
+ * file planted in a directory of someone else is never read.
+ */
+export const recallLanes = (root: string, system: LocationSystem = systemLocation()): Map<string, LaneMemory> => {
+  try {
+    return readLaneMemories(ensureHerdMemoryDirectory(root, system))
+  } catch {
+    return new Map()
+  }
+}
 
 /**
  * Keeps the memories of `lanes` for the next herd. A memory that cannot be written costs only the times of the next
@@ -98,9 +108,10 @@ export const rememberLanes = (
   root: string,
   memories: ReadonlyMap<string, LaneMemory>,
   lanes: readonly string[],
+  system: LocationSystem = systemLocation(),
 ): void => {
   try {
-    writeLaneMemories(herdMemoryDirectory(root), memories, lanes)
+    writeLaneMemories(ensureHerdMemoryDirectory(root, system), memories, lanes)
   } catch {
     return
   }

package/src/plans/lane-plans.ts

@@ -1,8 +1,10 @@
 import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { type PlansByHref, parsePlanPhases, resolvePlanPath, type SprintLane } from '../plan-format'
+import { type PlanPhase, type PlansByHref, resolvePlanPath, type SprintLane } from '../plan-format'
 import type { BaseReader } from './git'
-import { hasOwnWork, mergePlanPhases } from './phase-source'
+import { hasOwnWork, mergePlanPhases, newerPhases } from './phase-source'
+import { type PlanRound, parsedPlanPhases } from './plan-cache'
+import type { PlanHead } from './plan-heads'
 import type { PlansSettings } from './settings'
 
 /** Paths that could not be read at the base ref and were read from a checkout instead. */
@@ -10,8 +12,20 @@ export type Fallbacks = string[]
 
 export type LaneWork = { worktree: string | null; ahead: number | null; dirty: number }
 
+/** Parses a plan's text, kept under `key` in the round's cache. */
+type ParsePlan = (markdown: string, key: string) => PlanPhase[]
+
 /** What reading a lane's plans needs: the main checkout, the settings, the base ref's reader, the board's directory. */
-export type PlanSources = { root: string; settings: PlansSettings; base: BaseReader; sprintDirectory: string }
+export type PlanSources = {
+  root: string
+  settings: PlansSettings
+  base: BaseReader
+  sprintDirectory: string
+  /** The heads of the open pull requests that change a plan, besides the lane's own; a phase they ticked further counts. */
+  heads: readonly PlanHead[]
+  /** Kept between reads, so a plan whose text did not change is not parsed again; `used` collects the keys of one round. */
+  parsed?: PlanRound
+}
 
 const isOutsideRepository = (path: string): boolean => path.startsWith('..')
 
@@ -49,10 +63,30 @@ export const laneWorkOf = (worktree: string, status: { ahead: number | null; dir
 })
 
 /**
- * The plans of a lane. The base ref is the truth; while the lane has work of its own in its worktree, the phases
- * its rows name, and those new there or ticked further, come from the worktree (`mergePlanPhases`). A plan the base ref lacks is read from the lane's worktree, else from the main
- * checkout (a repository that ignores `docs/` keeps plan and board only there). `files` are the plan files to
- * watch for changes, `modified` when each was last written, by plan link (`nextActivity` bounds a movement by it).
+ * The base's phases with each phase an open pull request ticked further taken from that pull request's head, in
+ * the heads' order. A head whose ref was not fetched reads nothing and changes nothing; its phases are never the
+ * lane's work, so none is marked `touched`.
+ */
+const withPullRequestHeads = (
+  base: PlanPhase[],
+  heads: readonly PlanHead[],
+  path: string,
+  parse: ParsePlan,
+): PlanPhase[] =>
+  heads
+    .filter((head) => head.files.includes(path))
+    .reduce((phases, head) => {
+      const headText = head.read(path)
+      return headText === null ? phases : newerPhases(phases, parse(headText, `${path}\0pr${head.number}`))
+    }, base)
+
+/**
+ * The plans of a lane. The base ref is the truth, raised by the heads of open pull requests that ticked a phase
+ * further (`withPullRequestHeads`); while the lane has work of its own in its worktree, the phases its rows name,
+ * and those new there or ticked further, come from the worktree (`mergePlanPhases`). A plan the base ref lacks is
+ * read from the lane's worktree, else from the main checkout (a repository that ignores `docs/` keeps plan and
+ * board only there). `files` are the plan files to watch for changes, `modified` when each was last written, by
+ * plan link (`nextActivity` bounds a movement by it).
  */
 export const readPlans = async (lane: SprintLane, sources: PlanSources, work: LaneWork, fallbacks: Fallbacks) => {
   const { root, settings, sprintDirectory } = sources
@@ -68,12 +102,9 @@ export const readPlans = async (lane: SprintLane, sources: PlanSources, work: La
     if (text === null) continue
     const own = worktreeFile === file && hasOwnWork(work) ? await Bun.file(file).text() : null
     const laneIds = lane.steps.filter((step) => step.planHref === href).flatMap((step) => step.phaseIds)
-    plans[href] = mergePlanPhases(
-      parsePlanPhases(text, settings.planLanguage),
-      own === null ? null : parsePlanPhases(own, settings.planLanguage),
-      laneIds,
-      work,
-    )
+    const parse: ParsePlan = (markdown, key) => parsedPlanPhases(sources.parsed, key, markdown, settings.planLanguage)
+    const base = withPullRequestHeads(parse(text, path), sources.heads, path, parse)
+    plans[href] = mergePlanPhases(base, own === null ? null : parse(own, `${file}\0own`), laneIds, work)
     files.push(file)
     texts[href] = text
     if (existsSync(file)) modified[href] = statSync(file).mtimeMs