@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-cli.ts

@@ -0,0 +1,410 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { epic_busy } from '#scripts/epic/epic-busy'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { run_carry } from '#scripts/run/run-carry'
+import { lane_await } from './lane-await'
+import { lane_close, type CloseOutcome, type SweepOutcome } from './lane-close'
+import { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
+import { lane_occupancy } from './lane-occupancy'
+import { lane_open, type OpenOutcome } from './lane-open'
+import { lane_output, type ReadOutcome, type RecordOutcome } from './lane-output'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_report } from './lane-report'
+import { lane_seed_policy } from './lane-seed'
+
+// `josh lane:open` / `lane:close` / `lane:list` / `lane:prune` — the lane's whole lifecycle
+// (joshuafolkken/kit#1490).
+//
+// **`lane:open` prints the lane's directory on standard output and nothing else**, so
+// `dir=$(pnpm josh lane:open 1490)` is what a caller needs and a refusal is an empty capture beside
+// a non-zero exit. The other three follow the contract `run:hold` and `epic:next` set: a token per
+// line on standard output, every explanation on standard error.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const SINGLE_ARGUMENT = 1
+const ISSUE_AND_PATH_ARGUMENTS = 2
+const ALL_FLAG = '--all'
+const NONE_TOKEN = 'none'
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+
+const USAGE = [
+	'Usage: josh lane:open <issue-number>',
+	'       josh lane:close <issue-number> | josh lane:close --all',
+	'       josh lane:list',
+	'       josh lane:prune',
+	'       josh lane:output <issue-number> [<path>]',
+	'       josh lane:dispatch <issue-number>',
+	'       josh lane:await <issue-number> ...',
+].join('\n')
+
+type Handler = (rest: ReadonlyArray<string>) => Promise<number>
+
+function report_usage(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Read the carry record and refuse if this session has already handed off its budget via `--cut`.
+// A cut session must not open new lanes or dispatch new children — the successor owns the budget
+// (joshuafolkken/kit#2114).
+async function guard_cut_session(): Promise<string | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	const read = run_carry.read_carry(run_carry.carry_path(directory))
+
+	if ((read.kind !== 'carried' && read.kind !== 'expired') || read.carry.is_handed_off !== true) {
+		return undefined
+	}
+
+	return run_carry.count_refused_message(read.carry)
+}
+
+function parse_lane_issue(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined
+
+	return ISSUE_NUMBER_PATTERN.test(value) ? value : undefined
+}
+
+function parse_issue(rest: ReadonlyArray<string>): string | undefined {
+	if (rest.length > SINGLE_ARGUMENT) return undefined
+
+	return parse_lane_issue(rest[0])
+}
+
+// The two refusals name what to type next, because both are states a person recovers from rather
+// than reports: one lane is already there, or every index is spoken for.
+function refusal_message(outcome: Exclude<OpenOutcome, { kind: 'opened' }>): string {
+	if (outcome.kind === 'full') {
+		return `All ${String(lane_seed_policy.LAST_LANE_SEAT)} lane seats are taken. Run \`pnpm josh lane:list\` to see them and \`pnpm josh lane:close <issue-number>\` to free one.`
+	}
+
+	return `A lane for #${outcome.lane.issue} is already open at ${outcome.lane.directory}. Run \`pnpm josh lane:close ${outcome.lane.issue}\` before opening it again.`
+}
+
+function report_open(outcome: OpenOutcome): number {
+	if (outcome.kind !== 'opened') {
+		console.error(refusal_message(outcome))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.error(lane_report.describe_opened(outcome.lane))
+	console.info(outcome.lane.directory)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// One token per closed lane, `none` when there was nothing to close — so a caller sweeping up after
+// an interruption can branch on the output without reading the prose.
+function report_issues(issues: ReadonlyArray<string>): number {
+	console.info(issues.length === 0 ? NONE_TOKEN : issues.join('\n'))
+
+	return SUCCESS_EXIT_CODE
+}
+
+// A close that left something behind exits non-zero and names it. Reported as a success, it would
+// send the caller to the next `lane:open`, which then fails on git's own message about a branch that
+// still exists.
+function report_close(outcome: CloseOutcome): number {
+	if (outcome.reaped.length > 0) {
+		console.error(
+			`Terminated the lane child for #${outcome.issue} that had not ended by itself: process ${outcome.reaped.join(', ')}.`,
+		)
+	}
+
+	if (outcome.kind !== 'incomplete') {
+		return report_issues(outcome.kind === 'closed' ? [outcome.issue] : [])
+	}
+
+	console.error(
+		`Closing the lane for #${outcome.issue} left this behind: ${outcome.left_behind.join(', ')}. Remove it and run \`pnpm josh lane:close ${outcome.issue}\` again.`,
+	)
+
+	return FAILURE_EXIT_CODE
+}
+
+// The closed lanes still go to standard output, because a sweep that failed on one of them has
+// closed the rest and the caller has to know which.
+function report_sweep(outcome: SweepOutcome): number {
+	const code = report_issues(outcome.closed)
+
+	if (outcome.failed.length === 0) return code
+
+	const named = outcome.failed.map((issue) => `#${issue}`).join(', ')
+
+	// `lane:list` reads git's work trees, and the usual survivor is a branch whose work tree is
+	// already gone — which that listing cannot show. Closing each one again is what names it.
+	console.error(
+		`These lanes could not be closed: ${named}. Run \`pnpm josh lane:close <issue-number>\` on each to see what is left of it.`,
+	)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `none` on standard output for the empty case as well, so `lane:list` keeps the contract the rest
+// of the commands follow — the prose belongs on standard error with every other explanation.
+function report_lanes(lanes: ReadonlyArray<LaneInfo>): number {
+	if (lanes.length === 0) console.error(lane_report.NO_LANES)
+
+	console.info(lanes.length === 0 ? NONE_TOKEN : lane_report.describe_lanes(lanes))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function open_command(rest: ReadonlyArray<string>): Promise<number> {
+	const issue = parse_issue(rest)
+
+	if (issue === undefined) return report_usage()
+
+	const refused = await guard_cut_session()
+
+	if (refused !== undefined) {
+		console.error(refused)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return report_open(await lane_open.open_lane(issue))
+}
+
+async function close_command(rest: ReadonlyArray<string>): Promise<number> {
+	if (rest[0] === ALL_FLAG && rest.length === SINGLE_ARGUMENT) {
+		return report_sweep(await lane_close.close_all_lanes())
+	}
+
+	const issue = parse_issue(rest)
+
+	if (issue === undefined) return report_usage()
+
+	return report_close(await lane_close.close_lane(issue))
+}
+
+const OCCUPANCY_UNREADABLE =
+	'Could not read the `in-progress` listing, so the lane/label difference was not checked — that is not "everything agrees"; check `gh auth status`.'
+
+// The `in-progress` issues this repository shows running, read the way `epic:next` reads lane
+// occupancy — never rebuilt (joshuafolkken/kit#2235). A read that could not see the whole listing is
+// `undefined`, so the difference is skipped rather than computed against a set known to be partial.
+async function to_holder_numbers(repo: string): Promise<ReadonlyArray<number> | undefined> {
+	const read = await epic_busy.read_repository(repo)
+	if (read.kind === 'idle') return []
+
+	return read.kind === 'busy' ? read.issues.map((issue) => issue.number) : undefined
+}
+
+async function read_in_progress(): Promise<ReadonlyArray<number> | undefined> {
+	try {
+		const repo = await git_gh_command.repo_get_name_with_owner()
+
+		return repo === undefined ? undefined : await to_holder_numbers(repo)
+	} catch {
+		return undefined
+	}
+}
+
+// A stranded lane's work tree is gone, so it holds no issue: it counts as no lane rather than a live
+// one, which is what turns its surviving `in-progress` label into a `stopped` anomaly.
+function live_lane_issues(lanes: ReadonlyArray<LaneInfo>): Array<number> {
+	return lanes.filter((lane) => !lane.is_stranded).map((lane) => Number(lane.issue))
+}
+
+// The lane/label difference, printed to standard error beside the listing. Wrapped so a GitHub read
+// that fails skips only this section — `lane:list`'s job is to list the lanes it already read.
+async function report_occupancy(lanes: ReadonlyArray<LaneInfo>): Promise<void> {
+	const in_progress = await read_in_progress()
+
+	if (in_progress === undefined) {
+		console.error(OCCUPANCY_UNREADABLE)
+
+		return
+	}
+
+	const report = lane_occupancy.classify(in_progress, {
+		kind: 'lanes',
+		issues: live_lane_issues(lanes),
+	})
+	const described = lane_occupancy.describe(report)
+
+	if (described !== undefined) console.error(described)
+}
+
+async function list_command(rest: ReadonlyArray<string>): Promise<number> {
+	if (rest.length > 0) return report_usage()
+
+	const lanes = await lane_registry.list_lanes()
+	const code = report_lanes(lanes)
+
+	await report_occupancy(lanes)
+
+	return code
+}
+
+async function prune_command(rest: ReadonlyArray<string>): Promise<number> {
+	if (rest.length > 0) return report_usage()
+
+	return report_sweep(await lane_close.prune_lanes())
+}
+
+// The recorded path goes to standard output on both arms, so
+// `unit_output=$(pnpm josh lane:output <N>) && pnpm josh run:liveness <N> --output "$unit_output"`
+// works in a session that opened the lane and in one that never saw it alike. **The `&&` rather than
+// a substitution inside the argument**: a substitution discards the exit status, so the `none` below
+// would reach `--output` as a relative path and poll `undetermined` for ever.
+function report_record(outcome: RecordOutcome, issue: string): number {
+	if (outcome.kind !== 'recorded') {
+		console.error(lane_output.describe_refusal(outcome, issue))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(outcome.output)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// `none` for a lane that records nothing yet — the same token `lane:list` and `lane:close` print for
+// an empty answer — but with a **non-zero** exit, unlike either of those. The reader here is a
+// command substitution, and `--output none` is a relative path `run:liveness` answers `undetermined`
+// for: polled that way a lane says "could not read" for ever rather than "the record is missing". A
+// non-zero exit is what stops the `&&` in the documented one-liner before it gets there.
+function report_output(outcome: ReadOutcome, issue: string): number {
+	if (outcome.kind === 'no-lane') {
+		console.error(lane_output.describe_refusal(outcome, issue))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (outcome.kind === 'none') {
+		console.error(lane_output.NO_OUTPUT)
+		console.info(NONE_TOKEN)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(outcome.output)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function output_command(rest: ReadonlyArray<string>): Promise<number> {
+	const [first, second] = rest
+	const issue = parse_lane_issue(first)
+
+	if (issue === undefined || rest.length > ISSUE_AND_PATH_ARGUMENTS) return report_usage()
+
+	if (second === undefined) return report_output(await lane_output.read_output(issue), issue)
+
+	return report_record(await lane_output.record_output(issue, second), issue)
+}
+
+// The child's pid goes to standard output alone, so `pid=$(pnpm josh lane:dispatch <N>)` is what a
+// caller needs — and a refusal is an empty capture beside a non-zero exit, exactly as `lane:open`'s is.
+// **Every refusal also warns**, because the session that issued the dispatch may be the one about to be
+// cut: a lane that never started its child is indistinguishable from one whose child is still thinking,
+// and nothing else would ever say which it was. **So does a launch that started a child with nowhere to
+// write** — `is_worth_warning` is what decides, rather than this function reading the outcome's shape.
+async function report_dispatch(outcome: DispatchOutcome, issue: string): Promise<number> {
+	console.error(lane_dispatch.describe(outcome, issue))
+
+	if (lane_dispatch.is_worth_warning(outcome)) await lane_dispatch.warn_of_problem(outcome, issue)
+
+	if (outcome.kind !== 'dispatched') return FAILURE_EXIT_CODE
+
+	console.info(String(outcome.pid))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function dispatch_command(rest: ReadonlyArray<string>): Promise<number> {
+	const issue = parse_issue(rest)
+
+	if (issue === undefined) return report_usage()
+
+	const refused = await guard_cut_session()
+
+	if (refused !== undefined) {
+		console.error(refused)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report_dispatch(await lane_dispatch.dispatch_child(issue), issue)
+}
+
+// Each valid argument is an issue number; any non-number stops parsing and triggers usage.
+function parse_issues(rest: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
+	if (rest.length === 0) return undefined
+	const issues = rest.filter((value) => lane_await.ISSUE_PATTERN.test(value))
+
+	return issues.length === rest.length ? issues : undefined
+}
+
+// The completed issue number goes to standard output so `N=$(pnpm josh lane:await ...)` captures
+// which child finished without parsing stderr.
+async function await_command(rest: ReadonlyArray<string>): Promise<number> {
+	const issues = parse_issues(rest)
+
+	if (issues === undefined) return report_usage()
+
+	const completed = await lane_await.wait_for_any(issues)
+
+	console.info(completed)
+
+	return SUCCESS_EXIT_CODE
+}
+
+const HANDLERS: Record<string, Handler> = {
+	open: open_command,
+	close: close_command,
+	list: list_command,
+	prune: prune_command,
+	output: output_command,
+	dispatch: dispatch_command,
+	await: await_command,
+}
+
+async function dispatch(argv: ReadonlyArray<string>): Promise<number> {
+	const [verb, ...rest] = argv
+	const handler = verb === undefined ? undefined : HANDLERS[verb]
+
+	if (handler === undefined) return report_usage()
+
+	return await handler(rest)
+}
+
+// A git failure — no repository, a path a work tree cannot be created at — is reported and exits
+// non-zero rather than throwing a stack trace at a caller that is capturing standard output.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	try {
+		return await dispatch(argv)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_cli = {
+	ALL_FLAG,
+	NONE_TOKEN,
+	USAGE,
+	main,
+	parse_issue,
+	parse_lane_issue,
+	refusal_message,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_cli }

package/scripts/lane/lane-close.ts

@@ -0,0 +1,197 @@
+import { existsSync, rmSync } from 'node:fs'
+import { git_command } from '#scripts/git/git-command'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { lane_paths } from './lane-paths'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// Closing a lane: no work tree, no branch, no directory (joshuafolkken/kit#1490).
+//
+// **A lane is closed after a park, a failure or an interruption as readily as after a success**, so
+// every step here is written to run over a subject that is already gone or that still holds
+// uncommitted work. A close that refused either would leave exactly the debris it exists to remove,
+// and the next lane for that issue would then fail on a directory nobody could account for. There
+// is no ledger entry to remove: the lane's seat lived in the `.env` that goes with the work tree.
+
+interface LaneTargets {
+	directory: string
+	branch: string
+}
+
+// The lane an issue number names: its registration, when there is one, and the paths a close acts on.
+// Resolved once here so a caller that has to look inside the tree before closing it reads the same
+// directory the close removes (joshuafolkken/kit#2476).
+interface ResolvedLane {
+	existing: LaneInfo | undefined
+	targets: LaneTargets
+}
+
+type CloseKind = 'closed' | 'incomplete' | 'none'
+
+interface CloseOutcome {
+	issue: string
+	kind: CloseKind
+	left_behind: Array<string>
+	// The lane child's processes this close terminated — empty for a child that ended by itself.
+	reaped: Array<number>
+}
+
+interface SweepOutcome {
+	closed: Array<string>
+	failed: Array<string>
+}
+
+async function ignore_failure(action: () => Promise<string>): Promise<void> {
+	try {
+		await action()
+	} catch {
+		// Expected on every path this command was written for: a work tree git no longer registers, a
+		// branch already deleted, a prune with nothing to prune. What matters is that the next step
+		// still runs — the outcome is judged by what is left on disk, not by these exit codes.
+	}
+}
+
+// Without a registration — the state a crash between `worktree add` and the `.env` write leaves —
+// the issue number still implies both paths, which is what makes such a lane closable at all.
+function lane_targets(root: string, issue: string, lane: LaneInfo | undefined): LaneTargets {
+	return {
+		directory: lane?.directory ?? lane_paths.lane_directory(root, issue),
+		branch: lane?.branch ?? lane_paths.lane_branch(issue),
+	}
+}
+
+// A directory that will not go — a permission, a busy mount — is left for the check below to report
+// rather than thrown out of the middle of the removal, where it would abandon the steps after it
+// and, inside a sweep, every lane after this one.
+function remove_directory(directory: string): void {
+	try {
+		rmSync(directory, { force: true, recursive: true })
+	} catch {
+		// Reported by `residue`, which is what judges the close.
+	}
+}
+
+// **The order is load bearing.** `worktree remove` unregisters and deletes in one step; the explicit
+// removal after it covers a tree git had already forgotten; `prune` covers the opposite case, a
+// registration whose directory someone deleted by hand; and the branch goes last, because git
+// refuses to delete one that is still checked out in a registered work tree.
+async function remove_lane(targets: LaneTargets): Promise<void> {
+	await ignore_failure(async () => await git_worktree.worktree_remove(targets.directory))
+	remove_directory(targets.directory)
+	await ignore_failure(async () => await git_worktree.worktree_prune())
+	await ignore_failure(async () => await git_worktree.branch_delete(targets.branch))
+}
+
+/**
+ * What the removal left behind — the empty list is what "closed" means.
+ *
+ * **The verdict comes from the end state, not from the exit codes above**, every one of which is
+ * expected to fail on some legitimate path. The branch is the case that matters: one git refused to
+ * delete survives, the next `lane:open` for that issue dies on `worktree add` with git's own message
+ * instead of this command's, and a close that had reported success said nothing about it.
+ */
+async function residue(targets: LaneTargets): Promise<Array<string>> {
+	const left: Array<string> = []
+
+	if (existsSync(targets.directory)) left.push(targets.directory)
+	if (await git_command.branch_exists(targets.branch)) left.push(targets.branch)
+
+	return left
+}
+
+function close_kind(did_exist: boolean, left_behind: ReadonlyArray<string>): CloseKind {
+	if (left_behind.length > 0) return 'incomplete'
+
+	return did_exist ? 'closed' : 'none'
+}
+
+// The main work tree's root, not this one's — the same reading `list_lanes` uses, so the fallback
+// directory an unregistered lane is closed by is the one `lane:open` would have created
+// (joshuafolkken/kit#1497). Derived here from the current work tree, a close run inside a lane
+// reports `none` over a directory that is still on disk.
+async function lane_root_directory(): Promise<string> {
+	return lane_paths.lane_root(await lane_registry.main_repository_root())
+}
+
+/**
+ * Close the lane for `issue`. `none` means there was nothing there, which is not a failure: a caller
+ * cleaning up after an interruption cannot know whether the lane was ever opened. `incomplete` means
+ * something survived the removal, and `left_behind` names it.
+ */
+async function resolve_lane(issue: string): Promise<ResolvedLane> {
+	const root = await lane_root_directory()
+	const existing = lane_registry.find_lane(await lane_registry.list_lanes(), issue)
+
+	return { existing, targets: lane_targets(root, issue, existing) }
+}
+
+async function close_lane(issue: string): Promise<CloseOutcome> {
+	const { existing, targets } = await resolve_lane(issue)
+	const did_exist = existing !== undefined || existsSync(targets.directory)
+	// Before the removal, not after: a child still running in the tree would keep writing into a
+	// directory being deleted, and a process outliving its lane is the half-discarded state
+	// joshuafolkken/kit#2421 found — the work tree gone, the child still answering `alive`.
+	const reaped = lane_reap.reap_child(issue)
+
+	await remove_lane(targets)
+
+	const left_behind = await residue(targets)
+
+	return { issue, kind: close_kind(did_exist, left_behind), left_behind, reaped }
+}
+
+// A lane that could not be closed is recorded rather than thrown: a sweep has to attempt every lane,
+// and the caller has to be told which ones are still there.
+async function try_close(issue: string): Promise<boolean> {
+	try {
+		const outcome = await close_lane(issue)
+
+		return outcome.kind !== 'incomplete'
+	} catch {
+		return false
+	}
+}
+
+// Sequential on purpose: two `git worktree` writes at once contend for the same registration
+// directory, and the whole point of the command is that nothing is left half-removed.
+async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome> {
+	const sweep: SweepOutcome = { closed: [], failed: [] }
+
+	for (const issue of issues) {
+		const bucket = (await try_close(issue)) ? sweep.closed : sweep.failed
+
+		bucket.push(issue)
+	}
+
+	return sweep
+}
+
+/**
+ * Close every lane whose work tree is no longer on disk — the route out of an interruption that took
+ * the directory with it and left git's registration behind.
+ */
+async function prune_lanes(): Promise<SweepOutcome> {
+	const lanes = await lane_registry.list_lanes()
+	const stranded = lanes.filter((lane) => lane.is_stranded)
+
+	return await close_each(stranded.map((lane) => lane.issue))
+}
+
+async function close_all_lanes(): Promise<SweepOutcome> {
+	const lanes = await lane_registry.list_lanes()
+
+	return await close_each(lanes.map((lane) => lane.issue))
+}
+
+const lane_close = {
+	close_all_lanes,
+	close_lane,
+	lane_root_directory,
+	lane_targets,
+	prune_lanes,
+	remove_lane,
+	resolve_lane,
+}
+
+export type { CloseKind, CloseOutcome, ResolvedLane, SweepOutcome }
+export { lane_close }

package/scripts/lane/lane-dispatch-log.ts

@@ -0,0 +1,13 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import type { LaneInfo } from './lane-registry'
+
+const LOG_PREFIX = 'josh-lane-dispatch-'
+const LOG_SUFFIX = '.log'
+
+function default_log_path(lane: LaneInfo): string {
+	return stamp_file.stamp_path(`${LOG_PREFIX}${lane.issue}-`, lane.directory, LOG_SUFFIX)
+}
+
+const lane_dispatch_log = { default_log_path }
+
+export { lane_dispatch_log }