jackherd 1.9.0 → 1.11.0

package/src/lane/close-check.ts

@@ -0,0 +1,183 @@
+/** The lane's merged pull request: the newest one on its branch, with the commit the merge left on the base. */
+export type MergedPullRequest = { number: number; headCommit: string; mergeCommit: string }
+
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { AGENT_STATUS } from '../terminal/types'
+
+/** How the board's lanes table names the lane: with open rows, only with rows marked cleaned up, or not at all. */
+export const BOARD_LANE = { open: 'open', closed: 'closed', missing: 'missing' } as const
+
+export type BoardLane = (typeof BOARD_LANE)[keyof typeof BOARD_LANE]
+
+/** The lane's branch, the head the check compared, and its merged pull request once nothing stands against closing it. */
+export type ClosableLane = { branch: string; head: string; pullRequest: MergedPullRequest }
+
+/** Every reason against closing, or the lane ready to close; the second only when the first is empty. */
+export type CloseVerdict = { kind: 'refused'; refusals: string[] } | ({ kind: 'closable' } & ClosableLane)
+
+/** One entry of `git status --porcelain`: its two status letters (`!!` ignored, `??` untracked) and its path. */
+export type StatusEntry = { code: string; path: string }
+
+/**
+ * What git, GitHub and the terminal answered about one lane, gathered before anything is removed. `treeDiff` lists the
+ * paths in which the branch head differs from the merge commit; `status` holds the worktree's status with ignored
+ * files (`statusEntriesOf`); `setupFiles` the patterns of the lane setup's copy list; `handoverEntries` every
+ * entry of the worktree's handover directory, which git shows only as the directory.
+ */
+export type CloseFacts = {
+  lane: string
+  boardLane: BoardLane
+  worktreeExists: boolean
+  branch: string | null
+  /** The commit the worktree's branch points to, as `git worktree list` reports it; null without a worktree. */
+  head: string | null
+  pullRequest: MergedPullRequest | null
+  treeDiff: readonly string[]
+  status: readonly StatusEntry[]
+  setupFiles: readonly string[]
+  handoverEntries: readonly string[]
+  /** The agent named after the lane whose directory lies in the worktree, with its pane. */
+  agent: { pane: string; status: string } | null
+  /** The panes of other agents whose directory lies in the worktree: a helper, or a session without the lane's name. */
+  otherAgents: readonly string[]
+  /** Whether the command itself runs in the worktree it would remove. */
+  runsInside: boolean
+  /** The reason `git worktree lock` recorded, empty for a lock without one; null when the worktree is not locked. */
+  locked: string | null
+}
+
+const RESTING_AGENT = new Set<string>([AGENT_STATUS.idle, AGENT_STATUS.done])
+const IGNORED_CODE = '!!'
+const RENAME_OR_COPY = new Set(['R', 'C'])
+/** A status field is two letters, a space, then the path. */
+const STATUS_PATH_START = 3
+const DEPENDENCY_DIRECTORY = 'node_modules'
+const BUILD_OUTPUT_DIRECTORIES = ['dist', '.turbo', 'test-results', '__pycache__']
+const BUILD_OUTPUT = [
+  ...BUILD_OUTPUT_DIRECTORIES.flatMap((directory) => [`**/${directory}`, `**/${directory}/**`]),
+  '**/*.tsbuildinfo',
+  'packages/*/bin/*.{js,mjs,cjs}',
+  '.husky/_',
+  '.husky/_/**',
+].map((glob) => new Bun.Glob(glob))
+/** Build output only as a directory entry: a package's `bin/` that an ignore rule hides as a whole. */
+const BUILD_OUTPUT_DIRECTORY_ENTRIES = [new Bun.Glob('packages/*/bin')]
+const HANDOVER = claudePath(HANDOVER_DIRECTORY)
+
+const withoutSlashes = (path: string): string => path.replace(/^\/+|\/+$/g, '')
+
+const isHandoverDirectory = (path: string): boolean => withoutSlashes(path) === HANDOVER
+
+/** The patterns of a `.gitignore`-style list that name files; comments, blanks and negations name none. */
+const patternsOf = (lines: readonly string[]): string[] =>
+  lines.map((line) => line.trim()).filter((line) => line !== '' && !line.startsWith('#') && !line.startsWith('!'))
+
+/**
+ * Whether `path` (relative to the worktree, a directory with its trailing slash) is one the lane setup copies in: a
+ * pattern with an inner slash is anchored at the root, one without matches the name at any depth, as in `.gitignore`.
+ */
+export const isSetupFile = (path: string, setupFiles: readonly string[]): boolean => {
+  const target = withoutSlashes(path)
+  return patternsOf(setupFiles).some((pattern) => {
+    const bare = withoutSlashes(pattern)
+    const glob = bare.includes('/') ? bare : `**/${bare}`
+    return new Bun.Glob(glob).match(target) || new Bun.Glob(bare).match(target)
+  })
+}
+
+const isDependencyPath = (path: string): boolean => withoutSlashes(path).split('/').includes(DEPENDENCY_DIRECTORY)
+
+/**
+ * The entries of `git status --porcelain=v1 -z --ignored=matching`: NUL-separated, never quoted, a rename or copy followed by
+ * its source as a field of its own, which is skipped. Names are read as git wrote them, so no file name can pose as
+ * another path.
+ */
+export const statusEntriesOf = (output: string): StatusEntry[] => {
+  const fields = output.split('\0')
+  const entries: StatusEntry[] = []
+  for (let i = 0; i < fields.length; i += 1) {
+    const field = fields[i]
+    if (field.length < STATUS_PATH_START) continue
+    const code = field.slice(0, 2)
+    entries.push({ code, path: field.slice(STATUS_PATH_START) })
+    if (RENAME_OR_COPY.has(code[0])) i += 1
+  }
+  return entries
+}
+
+/**
+ * Whether `path` (relative to the worktree, a directory with its trailing slash) is output a build makes again, from a
+ * fixed list: `dist`, `.turbo`, `test-results` and `__pycache__` at any depth, a `*.tsbuildinfo`, a
+ * `packages/*\/bin/*.{js,mjs,cjs}` or a whole `packages/*\/bin/`, and husky's helpers in `.husky/_`. Everything else an
+ * ignore rule hides may hold work and is not.
+ */
+export const isBuildOutput = (path: string): boolean => {
+  const target = withoutSlashes(path)
+  const directory = path.endsWith('/') && BUILD_OUTPUT_DIRECTORY_ENTRIES.some((glob) => glob.match(target))
+  return directory || BUILD_OUTPUT.some((glob) => glob.match(target))
+}
+
+/**
+ * The paths removing the worktree would delete for good: every tracked change and untracked file, and every ignored
+ * path except dependencies (`node_modules` at any depth), the setup files, build output and the handover directory.
+ */
+export const lostPathsOf = (status: readonly StatusEntry[], setupFiles: readonly string[]): string[] => {
+  const kept = (path: string) =>
+    isDependencyPath(path) || isSetupFile(path, setupFiles) || isBuildOutput(path) || isHandoverDirectory(path)
+  return status.filter(({ code, path }) => code !== IGNORED_CODE || !kept(path)).map(({ path }) => path)
+}
+
+/** The lost paths and the entries of the handover directory, each once: the directory stands for all of them. */
+const deletedPathsOf = ({ status, setupFiles, handoverEntries }: CloseFacts): string[] => [
+  ...new Set([...lostPathsOf(status, setupFiles), ...handoverEntries]),
+]
+
+/** A lane the board marks cleaned up already may still have its worktree left over; only a lane it never named is refused. */
+const boardRefusals = ({ lane, boardLane }: CloseFacts): string[] =>
+  boardLane === BOARD_LANE.missing ? [`the board has no row for lane ${lane}`] : []
+
+const mergeRefusals = ({ lane, branch, pullRequest, treeDiff }: CloseFacts): string[] => {
+  if (branch === null) return [`the worktree of ${lane} is on no branch`]
+  if (pullRequest === null) return [`branch ${branch} has no merged pull request`]
+  return treeDiff.map(
+    (path) => `branch ${branch} differs from the merge of #${pullRequest.number} (${pullRequest.mergeCommit}): ${path}`,
+  )
+}
+
+const agentRefusals = ({ lane, agent, otherAgents }: CloseFacts): string[] => [
+  ...(agent === null || RESTING_AGENT.has(agent.status) ? [] : [`the agent of ${lane} is ${agent.status}`]),
+  ...otherAgents.map((pane) => `pane ${pane} runs another agent in the worktree of ${lane}`),
+]
+
+const lockRefusals = ({ lane, locked }: CloseFacts): string[] =>
+  locked === null
+    ? []
+    : [`the worktree of ${lane} is locked${locked ? ` (${locked})` : ''}; unlock it once its session has ended`]
+
+/**
+ * Every reason not to close the lane, all at once; empty when nothing would be lost. Closing needs an open board row,
+ * the worktree on a branch whose newest merged pull request left the same tree on the base (a squash merge leaves the
+ * branch unmerged in git's eyes, so the trees are compared), nothing in the worktree beyond dependencies, the setup
+ * files and build output (`isBuildOutput`), an empty handover directory, an agent that is gone or rests, and no lock
+ * on the worktree (a Claude Code session may still hold it).
+ */
+export const closeRefusals = (facts: CloseFacts): string[] => {
+  if (!facts.worktreeExists) return [...boardRefusals(facts), `lane ${facts.lane} has no worktree`]
+  if (facts.runsInside) return [`run it outside the worktree of ${facts.lane}, which it would remove`]
+  return [
+    ...boardRefusals(facts),
+    ...mergeRefusals(facts),
+    ...deletedPathsOf(facts).map((path) => `removing the worktree deletes ${path}`),
+    ...agentRefusals(facts),
+    ...lockRefusals(facts),
+  ]
+}
+
+/** `closeRefusals` as a verdict that carries the branch and pull request it proved, so a caller needs no second check. */
+export const closeVerdict = (facts: CloseFacts): CloseVerdict => {
+  const refusals = closeRefusals(facts)
+  const { branch, head, pullRequest } = facts
+  if (refusals.length > 0 || branch === null || head === null || pullRequest === null)
+    return { kind: 'refused', refusals }
+  return { kind: 'closable', branch, head, pullRequest }
+}

package/src/lane/close-command-line.ts

@@ -0,0 +1,11 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+
+/** The command as the usage, the board's history and the watcher's status line name it. */
+export const LANE_CLOSE_COMMAND = `${CLI_NAME} lane close`
+
+export const DRY_RUN_OPTION = '--dry-run'
+
+/** The dry run the watcher suggests for a lane; null for a name no command line should carry. */
+export const closeDryRunOf = (lane: string): string | null =>
+  SAFE_LANE_NAME.test(lane) ? `${LANE_CLOSE_COMMAND} ${lane} ${DRY_RUN_OPTION}` : null

package/src/lane/close-command.ts

@@ -0,0 +1,217 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { TERMINAL_ADAPTER } from '../config'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor } from '../plans/board-pick'
+import { commitOf, mainCheckout, worktreeRoot } from '../plans/git'
+import { type PlansSettings, readSettings, worktreeOf } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { laneStatusSourceFor } from '../terminal'
+import { runHerdr } from '../terminal/herdr'
+import { runGh } from '../watch/gh'
+import { parseWatchedPullRequests, WATCHED_PULL_REQUEST_FIELDS } from '../watch/pull-requests'
+import { type ClosePorts, type CloseRequest, type CloseSurvey, closeLane } from './close'
+import { boardLaneOf } from './close-board'
+import { type CloseFacts, type MergedPullRequest, statusEntriesOf } from './close-check'
+import { type CloseOptions, LANE_CLOSE_USAGE, parseCloseOptions } from './close-options'
+import { agentFactsOf, mergedPullRequestOf, openWorkspaceOf, type WorktreeEntry, worktreeEntryOf } from './close-survey'
+
+/** Where the command runs and what it acts on, located once. */
+type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktree: string; boardFile: string }
+
+/** The facts that only a worktree git lists has. */
+type WorktreeFacts = Pick<
+  CloseFacts,
+  'worktreeExists' | 'branch' | 'head' | 'pullRequest' | 'treeDiff' | 'status' | 'handoverEntries' | 'locked'
+>
+
+/** The file the lane setup copies into every new worktree, in `.gitignore` syntax. */
+const SETUP_FILES = '.worktreeinclude'
+const GH_TIMEOUT_MS = 30_000
+const PULL_REQUEST_LIMIT = 20
+const EXIT_WAIT_MS = 60_000
+const EXIT_POLL_MS = 1_000
+const EXIT_COMMAND = '/exit'
+const BRANCH_REF = 'refs/heads/'
+/**
+ * Ignored paths as an ignore pattern names them: a directory whose files are all ignored by a file pattern
+ * (`packages/*\/bin/*.js`) shows as those files, not folded into a directory no pattern names, so the build output
+ * list can judge each one.
+ */
+const IGNORED_MATCHING = '--ignored=matching'
+/** Untracked files are listed whatever `status.showUntrackedFiles` says, so a project setting cannot hide one. */
+const ALL_UNTRACKED = '--untracked-files=all'
+
+const ABSENT_WORKTREE: WorktreeFacts = {
+  worktreeExists: false,
+  branch: null,
+  head: null,
+  pullRequest: null,
+  treeDiff: [],
+  status: [],
+  handoverEntries: [],
+  locked: null,
+}
+
+/** Runs git and returns its stdout; throws with git's own error text. */
+const runGit = (cwd: string, args: string[]): string => {
+  const result = Bun.spawnSync(['git', '-C', cwd, ...args], { stdout: 'pipe', stderr: 'pipe' })
+  if (result.exitCode !== 0)
+    throw new Error(`git ${args[0]}: ${result.stderr.toString().trim() || `exit ${result.exitCode}`}`)
+  return result.stdout.toString()
+}
+
+const realPath = (path: string): string => (existsSync(path) ? realpathSync(path) : path)
+
+const linesOf = (text: string): string[] => text.split('\n').filter((line) => line.trim() !== '')
+
+const setupFilesOf = (root: string): string[] => {
+  const file = join(root, SETUP_FILES)
+  return existsSync(file) ? readFileSync(file, 'utf8').split('\n') : []
+}
+
+/** The paths in which the branch head differs from the merge commit; fetches the base once when the commit is missing. */
+const treeDiffOf = (context: CloseContext, head: string, mergeCommit: string): string[] => {
+  if (commitOf(context.root, mergeCommit) === null)
+    runGit(context.root, ['fetch', '--quiet', 'origin', context.settings.baseBranch])
+  return linesOf(runGit(context.root, ['diff', '--name-only', '--end-of-options', head, mergeCommit]))
+}
+
+/** Every entry of the worktree's handover directory, a folder with its trailing slash, as git names paths. */
+const handoverEntriesOf = (worktree: string): string[] => {
+  const directory = claudePath(HANDOVER_DIRECTORY)
+  const absolute = join(worktree, directory)
+  if (!existsSync(absolute)) return []
+  return readdirSync(absolute, { withFileTypes: true })
+    .map((entry) => `${directory}/${entry.name}${entry.isDirectory() ? '/' : ''}`)
+    .sort()
+}
+
+const mergedPullRequestOn = async (context: CloseContext, branch: string): Promise<MergedPullRequest | null> => {
+  const fields = ['--json', WATCHED_PULL_REQUEST_FIELDS, '--limit', String(PULL_REQUEST_LIMIT)]
+  const answer = await runGh(['pr', 'list', '--head', branch, '--state', 'merged', ...fields], context.root, {
+    timeoutMs: GH_TIMEOUT_MS,
+  })
+  if (!answer.ok) throw new Error(answer.error)
+  return mergedPullRequestOf(parseWatchedPullRequests(answer.stdout), branch)
+}
+
+/** Branch, merged pull request, tree difference, status, handover files and lock of the worktree git lists for the lane. */
+const worktreeFactsOf = async (context: CloseContext, entry: WorktreeEntry): Promise<WorktreeFacts> => {
+  const pullRequest = entry.branch === null ? null : await mergedPullRequestOn(context, entry.branch)
+  return {
+    worktreeExists: true,
+    branch: entry.branch,
+    head: entry.head,
+    pullRequest,
+    treeDiff: pullRequest === null ? [] : treeDiffOf(context, entry.head, pullRequest.mergeCommit),
+    status: statusEntriesOf(
+      runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
+    ),
+    handoverEntries: handoverEntriesOf(context.worktree),
+    locked: entry.locked,
+  }
+}
+
+const workspaceOf = (context: CloseContext): string | null =>
+  context.settings.adapter === TERMINAL_ADAPTER.herdr
+    ? openWorkspaceOf(runHerdr(['worktree', 'list', '--cwd', context.root]), context.worktree)
+    : null
+
+/** What git, GitHub and the terminal say about the lane now; throws when one of them cannot be asked. */
+const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurvey> => {
+  const entry = worktreeEntryOf(runGit(context.root, ['worktree', 'list', '--porcelain']), context.worktree)
+  const present = entry !== null && existsSync(context.worktree)
+  const facts: CloseFacts = {
+    lane,
+    boardLane: boardLaneOf(readFileSync(context.boardFile, 'utf8'), lane, context.settings.planLanguage),
+    setupFiles: setupFilesOf(context.root),
+    ...agentFactsOf(laneStatusSourceFor(context.settings.adapter).listAgents(), lane, context.worktree),
+    runsInside: realPath(worktreeRoot(context.cwd)) === realPath(context.worktree),
+    ...(present ? await worktreeFactsOf(context, entry) : ABSENT_WORKTREE),
+  }
+  return { facts, workspace: present ? workspaceOf(context) : null }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((done) => setTimeout(done, ms))
+
+/** Sends `/exit` to the agent in `pane` and waits until the terminal lists no session in that pane. */
+const exitAgentIn =
+  (context: CloseContext) =>
+  async (pane: string): Promise<void> => {
+    if (context.settings.adapter !== TERMINAL_ADAPTER.herdr) throw new Error('only herdr can end an agent')
+    runHerdr(['agent', 'prompt', pane, EXIT_COMMAND])
+    const source = laneStatusSourceFor(context.settings.adapter)
+    for (let waited = 0; waited < EXIT_WAIT_MS; waited += EXIT_POLL_MS) {
+      await sleep(EXIT_POLL_MS)
+      const agent = source.listAgents().find((listed) => listed.pane === pane)
+      if (agent === undefined || agent.session === null) return
+    }
+    throw new Error(`the agent in pane ${pane} still runs after ${EXIT_WAIT_MS / 1000} s`)
+  }
+
+/** Git removes the worktree and refuses on any change itself; herdr then only closes the emptied workspace. */
+const removeWorktreeIn =
+  (context: CloseContext) =>
+  (worktree: string, workspace: string | null): void => {
+    runGit(context.root, ['worktree', 'remove', worktree])
+    if (workspace !== null) runHerdr(['workspace', 'close', workspace])
+  }
+
+/** Deletes the branch only while it points to `head`; git refuses when it moved since the check. */
+const deleteBranchIn =
+  (context: CloseContext) =>
+  (branch: string, head: string): void => {
+    runGit(context.root, ['update-ref', '-d', `${BRANCH_REF}${branch}`, head])
+  }
+
+const portsFor = (lane: string, context: CloseContext): ClosePorts => ({
+  survey: () => surveyOf(lane, context),
+  exitAgent: exitAgentIn(context),
+  removeWorktree: removeWorktreeIn(context),
+  deleteBranch: deleteBranchIn(context),
+  readBoard: () => readFileSync(context.boardFile, 'utf8'),
+  writeBoard: (text) => writeFileSync(context.boardFile, text),
+  print: (line) => console.log(terminalSafe(line)),
+  printError: (line) => console.error(terminalSafe(line)),
+})
+
+/** The main checkout, its settings, the lane's worktree from those settings, and the board, with the pick's notice. */
+const contextOf = (options: CloseOptions, cwd: string): { context: CloseContext; notice: string | null } => {
+  const root = mainCheckout(cwd)
+  const settings = readSettings([root, worktreeRoot(cwd)])
+  const boardPath = options.boardPath === null ? null : resolve(cwd, options.boardPath)
+  const board = boardFor(boardPath, [root], settings, () => [options.lane])
+  const worktree = worktreeOf(root, settings, options.lane)
+  return { context: { root, cwd, settings, worktree, boardFile: board.file }, notice: board.notice }
+}
+
+/**
+ * `jh lane close <lane> [--dry-run] [--board <board.md>]`: closes a lane in one run once nothing would be lost, see
+ * `closeLane`. The worktree's path comes from the settings and the lane's name, never from a reply. Exit 0 closed or
+ * dry run, 1 refused or failed.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_CLOSE_USAGE)
+    return 0
+  }
+  try {
+    const options = parseCloseOptions(args)
+    const { context, notice } = contextOf(options, cwd)
+    if (notice) console.error(terminalSafe(notice))
+    const request: CloseRequest = {
+      lane: options.lane,
+      worktree: context.worktree,
+      boardPath: relative(context.root, context.boardFile),
+      dryRun: options.dryRun,
+      now: new Date(),
+      language: context.settings.planLanguage,
+    }
+    return await closeLane(request, portsFor(options.lane, context))
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return 1
+  }
+}

package/src/lane/close-options.ts

@@ -0,0 +1,43 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import { DRY_RUN_OPTION, LANE_CLOSE_COMMAND } from './close-command-line'
+
+/** What `jh lane close` was asked for; `boardPath` is null where `--board` was left out. */
+export type CloseOptions = { lane: string; dryRun: boolean; boardPath: string | null }
+
+const BOARD = '--board'
+
+export const LANE_CLOSE_USAGE = `usage: ${LANE_CLOSE_COMMAND} <lane> [${DRY_RUN_OPTION}] [--board <board.md>]
+
+Closes a lane whose pull request is merged, once nothing in it would be lost: exits its agent, removes its workspace,
+worktree and local branch, and marks its rows in the board with a history row. Refuses with every reason otherwise.
+  --dry-run            check and print the steps, change nothing
+  --board <board.md>   the board to mark; without it the board is picked as for ${CLI_NAME} herd`
+
+const usageError = (message: string): Error => new Error(`${message}\n${LANE_CLOSE_USAGE}`)
+
+const laneOf = (words: readonly string[]): string => {
+  if (words.length === 0) throw usageError('the lane is required')
+  if (words.length > 1) throw usageError(`one lane at most, got ${words.join(' ')}`)
+  if (!SAFE_LANE_NAME.test(words[0])) throw usageError(`${words[0]} is no lane name (letters, digits, . _ -)`)
+  return words[0]
+}
+
+/** Reads `<lane> [--dry-run] [--board <file>]` in any order, the arguments after `close`; throws on a wrong line. */
+export const parseCloseOptions = (args: readonly string[]): CloseOptions => {
+  const words: string[] = []
+  let dryRun = false
+  let boardPath: string | null = null
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === DRY_RUN_OPTION) dryRun = true
+    else if (arg === BOARD) {
+      const value = args[i + 1]
+      if (value === undefined || value.startsWith('--')) throw usageError(`${BOARD} needs a value`)
+      boardPath = value
+      i += 1
+    } else if (arg.startsWith('--')) throw usageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  return { lane: laneOf(words), dryRun, boardPath }
+}

package/src/lane/close-survey.ts

@@ -0,0 +1,83 @@
+import { sep } from 'node:path'
+import { isRecord } from '../shared/is-record'
+import type { LaneAgent } from '../terminal'
+import { PULL_REQUEST_STATE, type WatchedPullRequest } from '../watch/pull-requests'
+import type { CloseFacts, MergedPullRequest } from './close-check'
+
+/** A worktree as `git worktree list --porcelain` lists it; `branch` null when detached, `locked` as in `CloseFacts`. */
+export type WorktreeEntry = { head: string; branch: string | null; locked: string | null }
+
+const BRANCH_REF = 'refs/heads/'
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+const fieldOf = (lines: readonly string[], key: string): string | null => {
+  const line = lines.find((entry) => entry === key || entry.startsWith(`${key} `))
+  return line === undefined ? null : line.slice(key.length + 1)
+}
+
+/** The entry of the worktree at `path` in `git worktree list --porcelain`; null when git lists none there. */
+export const worktreeEntryOf = (porcelain: string, path: string): WorktreeEntry | null => {
+  const entry = porcelain
+    .split('\n\n')
+    .map((block) => block.split('\n').filter(Boolean))
+    .find((lines) => fieldOf(lines, 'worktree') === path)
+  if (entry === undefined) return null
+  const branch = fieldOf(entry, 'branch')
+  return {
+    head: fieldOf(entry, 'HEAD') ?? '',
+    branch: branch?.startsWith(BRANCH_REF) ? branch.slice(BRANCH_REF.length) : null,
+    locked: fieldOf(entry, 'locked'),
+  }
+}
+
+type HerdrWorktree = { path: string; open_workspace_id?: string }
+
+const isHerdrWorktree = (value: unknown): value is HerdrWorktree =>
+  isRecord(value) &&
+  typeof value.path === 'string' &&
+  (value.open_workspace_id === undefined || typeof value.open_workspace_id === 'string')
+
+/** The herdr workspace the worktree at `path` is open in, from `herdr worktree list`; null when it is in none. */
+export const openWorkspaceOf = (json: string, path: string): string | null => {
+  const result = (JSON.parse(json) as { result?: { worktrees?: unknown } }).result
+  const worktrees = result?.worktrees
+  if (!Array.isArray(worktrees) || !worktrees.every(isHerdrWorktree))
+    throw new Error('herdr worktree list: unexpected answer')
+  return worktrees.find((worktree) => worktree.path === path)?.open_workspace_id ?? null
+}
+
+/** A full git object id, SHA-1 or SHA-256; anything else from GitHub never reaches a git command line. */
+export const isObjectId = (value: string): boolean => OBJECT_ID.test(value)
+
+/** The newest merged pull request on `branch`, by number; null when none was merged with a well-formed merge commit. */
+export const mergedPullRequestOf = (
+  pullRequests: readonly WatchedPullRequest[],
+  branch: string,
+): MergedPullRequest | null => {
+  const merged = pullRequests
+    .filter((pullRequest) => pullRequest.branch === branch && pullRequest.state === PULL_REQUEST_STATE.merged)
+    .flatMap(({ number, headCommit, mergeCommit }) =>
+      mergeCommit === null || !isObjectId(mergeCommit) ? [] : [{ number, headCommit, mergeCommit }],
+    )
+  return merged.sort((left, right) => right.number - left.number)[0] ?? null
+}
+
+const isInside = (cwd: string | null, worktree: string): boolean =>
+  cwd !== null && (cwd === worktree || cwd.startsWith(`${worktree}${sep}`))
+
+/**
+ * The lane's agent, by its name and a directory in the worktree, so an agent of that name elsewhere is never ended;
+ * and the panes of every other agent in the worktree.
+ */
+export const agentFactsOf = (
+  agents: readonly LaneAgent[],
+  lane: string,
+  worktree: string,
+): Pick<CloseFacts, 'agent' | 'otherAgents'> => {
+  const inWorktree = agents.filter(({ cwd }) => isInside(cwd, worktree))
+  const own = inWorktree.find(({ name }) => name === lane)
+  return {
+    agent: own === undefined ? null : { pane: own.pane, status: own.status },
+    otherAgents: inWorktree.filter((agent) => agent !== own).map(({ pane }) => pane),
+  }
+}