@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-withdraw.ts

@@ -0,0 +1,183 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_label } from '#scripts/run/run-label'
+import { lane_close, type CloseKind } from './lane-close'
+import { lane_preserve, type KeptWork } from './lane-preserve'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_residents } from './lane-residents'
+import { lane_state } from './lane-state'
+
+// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the
+// current run: the child is stopped, its work stashed and the lane closed. **The Issue stays open** —
+// a withdrawal ends this run's attempt, not the work — so a later run offers it again; this run does
+// not (`backlog-drive-restore.ts` → `offer_exclude`, and the drive's own exclusion).
+//
+// **The `withdraw` event is written first, before anything is stopped.** Killing the child alone would
+// let `lane:await` book it stopped and `run:merge` classify it from GitHub — an open issue resumed as an
+// `outage` or parked `run:stalled`. `run:merge` reads the event stream before GitHub, so a child whose
+// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads.
+//
+// A tree that could not be stashed is left in place: closing the lane would delete the work, and the
+// person decides what to keep.
+
+const WITHDRAW_OCCASION = 'lane withdraw'
+const WITHDRAW_CAUSE = 'a person withdrew it with `lane:withdraw`'
+const CLOSED_STATE = 'CLOSED'
+const CLOSED_KIND = 'closed'
+const NO_LANE_KIND = 'no-lane'
+const UNREADABLE_KIND = 'unreadable'
+
+type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
+
+interface Withdrawn {
+	kind: 'withdrawn'
+	// How many of the child's processes the withdrawal stopped — 0 for a child that had already ended.
+	reaped: number
+	stash: string | undefined
+	// Whether the comment saying the issue stays open reached it.
+	is_noted: boolean
+	lane: CloseKind
+	// What else the close ended from the checkout; `undefined` where it could not be read.
+	residents: ReadonlyArray<number> | undefined
+}
+
+type Refused =
+	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
+type WithdrawOutcome = Withdrawn | Unsaved | Refused
+
+function withdraw_comment(reason: string): string {
+	return [
+		'Withdrawn from the current run by a person with `pnpm josh lane:withdraw`.',
+		'Its lane child was stopped and the lane closed. The Issue stays open: this run does not resume it, and the next run offers it again.',
+		`- Why: ${reason}`,
+	].join('\n')
+}
+
+async function record_withdraw(issue: string, reason: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.WITHDRAW,
+		`${issue_cite.plain(issue)} withdrawn by a person: ${reason}`,
+	)
+}
+
+// A closed issue has nothing to withdraw, and an unread one might be: neither writes anything.
+async function refusal_of(issue: string): Promise<Refused | undefined> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	if (read.kind !== 'state') return { kind: UNREADABLE_KIND }
+	if (read.state.state.toUpperCase() === CLOSED_STATE) return { kind: CLOSED_KIND }
+
+	return undefined
+}
+
+async function note_issue(
+	issue: string,
+	reason: string,
+	stash: string | undefined,
+): Promise<boolean> {
+	const is_noted = await git_gh_issue_write.issue_try_comment(issue, withdraw_comment(reason))
+
+	if (stash !== undefined) await lane_preserve.announce(issue, stash, WITHDRAW_CAUSE)
+	await run_label.unmark(issue)
+
+	return is_noted
+}
+
+async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
+	await record_withdraw(lane.issue, reason)
+	const reaped = lane_reap.reap_child(lane).length
+	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, WITHDRAW_OCCASION)
+
+	if (saved.kind === 'unsaved') return saved
+	const is_noted = await note_issue(lane.issue, reason, saved.stash)
+	const closed = await lane_close.close_lane(lane.issue)
+
+	// After the close, so the record names the withdrawal rather than the close it ran. An `incomplete`
+	// close is not `ended`: the supervisor closes the lane again until its last process is gone.
+	if (closed.kind !== 'incomplete') {
+		await lane_state.record_change({ issue: lane.issue, state: 'ended', command: 'lane:withdraw' })
+	}
+
+	return {
+		kind: 'withdrawn',
+		reaped,
+		stash: saved.stash,
+		is_noted,
+		lane: closed.kind,
+		residents: closed.residents,
+	}
+}
+
+/** Stop `#<N>`'s lane child, stash its work and close the lane, leaving the Issue open. */
+async function withdraw(issue: string, reason: string): Promise<WithdrawOutcome> {
+	issue_number_shape.require_issue_number(issue)
+	const refusal = await refusal_of(issue)
+
+	if (refusal !== undefined) return refusal
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: NO_LANE_KIND }
+
+	return await stop_and_close(lane, reason)
+}
+
+function stash_sentence(stash: string | undefined): string {
+	if (stash === undefined) return 'The lane held no uncommitted work.'
+
+	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
+}
+
+// What the lane's close left or ended, as a suffix.
+function lane_suffix(outcome: Withdrawn, cited: string): string {
+	const removed = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+	const residents = lane_residents.residents_sentence(outcome.residents, cited)
+
+	return residents === undefined ? removed : `${removed} ${residents}`
+}
+
+function withdrawn_text(outcome: Withdrawn, issue: string): string {
+	const cited = session_cite.issue(issue)
+	const stopped = outcome.reaped === 0 ? 'Its child had already ended.' : 'Stopped its child.'
+	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
+	const lane = lane_suffix(outcome, cited)
+	const noted = outcome.is_noted ? '' : ' The comment saying so could not be posted.'
+
+	return `${head} The Issue stays open: this run does not offer it again, the next run does.${noted}${lane}`
+}
+
+function unsaved_text(outcome: Unsaved, issue: string): string {
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the lane is left at ${outcome.directory}; \`run:merge\` books it withdrawn.`
+}
+
+function refused_text(outcome: Refused, issue: string): string {
+	const cited = session_cite.issue(issue)
+
+	if (outcome.kind === CLOSED_KIND) {
+		return `${cited} is already closed, so there is nothing to withdraw.`
+	}
+
+	if (outcome.kind === NO_LANE_KIND) {
+		return `No lane is open for ${cited}, so there is no child to withdraw.`
+	}
+
+	return `The state of ${cited} could not be read, so nothing was stopped or closed — try again.`
+}
+
+function describe(outcome: WithdrawOutcome, issue: string): string {
+	if (outcome.kind === 'unsaved') return unsaved_text(outcome, issue)
+
+	return outcome.kind === 'withdrawn'
+		? withdrawn_text(outcome, issue)
+		: refused_text(outcome, issue)
+}
+
+const lane_withdraw = { describe, withdraw }
+
+export type { WithdrawOutcome }
+export { lane_withdraw }

package/scripts/lane/process-directories.ts

@@ -0,0 +1,70 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_paths } from './lane-paths'
+
+// Each process's working directory, read with `lsof` — the one place its output is parsed.
+//
+// **A process belongs to a lane by its working directory first, its ancestry only after.** A process
+// detached from a lane (`josh ship --detach`, a diagnostic started under `script`) is re-parented to
+// pid 1, so no parent chain reaches it, while its working directory still sits under `.kit-lanes/<N>`.
+// `run:board` draws such a process as a lane's or a leftover, and `lane:close` ends it
+// (joshuafolkken/kit#4304); the board falls back to the ancestry where the directory names no lane
+// (`run-board-usage-lanes.ts`).
+// **macOS alone**, as the board reads it: elsewhere nothing is listed.
+
+const LSOF_COMMAND = 'lsof'
+// `-a` joins the conditions: the `cwd` descriptor only, in `-F` fields. The board appends `-p <pids>`.
+const CWD_ARGUMENTS = ['-a', '-d', 'cwd', '-Fn']
+// `lsof -F`'s field lines: `p<pid>` opens a process, `n<path>` names its directory.
+const LSOF_PROCESS = /^(?=p)/mu
+const LSOF_NAME = 'n'
+const LISTING_PLATFORMS: ReadonlySet<NodeJS.Platform> = new Set(['darwin'])
+
+function lsof_block(block: string): [number, string] | undefined {
+	const [process_line = '', ...rest] = block.trim().split('\n')
+	const name = rest.find((line) => line.startsWith(LSOF_NAME))
+
+	return name === undefined ? undefined : [Number(process_line.slice(1)), name.slice(1)]
+}
+
+/** Each process's working directory from `lsof -F`'s output. */
+function parse(output: string): Map<number, string> {
+	const blocks = output.split(LSOF_PROCESS).map((block) => lsof_block(block))
+
+	return new Map(blocks.filter((block) => block !== undefined))
+}
+
+/**
+ * Every process's working directory, `undefined` where `lsof` could not be run or timed out — never
+ * read as "nothing there". `lsof` exits non-zero when one process cannot be read and still lists the
+ * rest, so its output is read whatever the exit status.
+ */
+function list_all(platform: NodeJS.Platform = process.platform): Map<number, string> | undefined {
+	if (!LISTING_PLATFORMS.has(platform)) return new Map()
+
+	const result = spawnSync(LSOF_COMMAND, CWD_ARGUMENTS, {
+		encoding: 'utf8',
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return result.error === undefined ? parse(result.stdout) : undefined
+}
+
+/**
+ * The lane of `root` a directory sits under — itself or a directory above it, the outermost first.
+ * The one lane-membership reading: the board draws a leftover by it, and the close ends by it
+ * (joshuafolkken/kit#4300).
+ */
+function lane_of(directory: string, root: string): string | undefined {
+	const parts = directory.split(path.sep)
+	const ancestors = parts.map((_, index) => parts.slice(0, index + 1).join(path.sep)).slice(1)
+	const environment = { [lane_paths.LANE_ROOT_KEY]: root }
+
+	return ancestors.map((ancestor) => lane_paths.lane_issue_of(ancestor, environment)).find(Boolean)
+}
+
+const process_directories = { CWD_ARGUMENTS, lane_of, list_all, parse }
+
+export { process_directories }

package/scripts/lane/process-lane-marks.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from 'node:child_process'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_child_marker } from './lane-child-marker'
+
+// Each process's lane mark — the `JOSH_LANE_CHILD` it inherited — read from `ps -E`
+// (joshuafolkken/kit#4315).
+//
+// **A process belongs to a lane by its mark wherever it runs.** A lane child that measures something
+// from the main checkout or `/tmp` leaves processes whose working directory is not under the lane, and
+// one started under `script` or a new session has left the child's tree and group for pid 1. The
+// environment survives all of that, and `lane:dispatch` puts the issue number in it
+// (`lane-child-marker.ts`), so the mark names the lane a process was started from.
+//
+// **The mark is read from the environment, never from the arguments.** `ps -E` appends the environment
+// to the command line, so the plain command line is read too and only what follows it is searched: a
+// `grep JOSH_LANE_CHILD=42` carries the text without the mark.
+//
+// **An application bundle is never marked.** A lane that opened Docker Desktop passed its environment
+// to an application the whole machine uses; it is a person's, not the lane's.
+//
+// **macOS alone**, as `process-directories.ts` reads it: elsewhere nothing is listed.
+
+const PS_COMMAND = '/bin/ps'
+const LISTING_ARGUMENTS = ['-A', '-ww', '-o', 'pid=,command=']
+const ENVIRONMENT_FLAG = '-E'
+// `ps -E` over every process runs to hundreds of kilobytes; the default 1 MiB would cut it short.
+const LISTING_BUFFER_BYTES = 67_108_864
+const PID_LINE = /^\s*(?<pid>\d+) (?<command>.*)$/u
+const APPLICATION_BUNDLE = '.app/Contents/'
+const LISTING_PLATFORMS: ReadonlySet<NodeJS.Platform> = new Set(['darwin'])
+const MARK = new RegExp(String.raw`(?:^|\s)${lane_child_marker.KEY}=(?<issue>\d+)(?=\s|$)`, 'u')
+
+function command_lines(printed: string): Map<number, string> {
+	const groups = printed.split('\n').map((line) => PID_LINE.exec(line)?.groups)
+
+	return new Map(
+		groups
+			.filter((group) => group !== undefined)
+			.map((group) => [Number(group['pid']), group['command'] ?? '']),
+	)
+}
+
+// What `ps -E` printed after the plain command line; `undefined` for an application bundle and for a
+// process the two listings disagree on (it ended or exec'd between them).
+function environment_of(command: string | undefined, with_environment: string): string | undefined {
+	if (command === undefined || command.includes(APPLICATION_BUNDLE)) return undefined
+
+	return with_environment.startsWith(command) ? with_environment.slice(command.length) : undefined
+}
+
+function mark_of(command: string | undefined, with_environment: string): string | undefined {
+	const environment = environment_of(command, with_environment)
+
+	return environment === undefined ? undefined : MARK.exec(environment)?.groups?.['issue']
+}
+
+/** Each marked process's issue, from `ps`'s plain and `-E` listings. */
+function parse(plain: string, with_environment: string): Map<number, string> {
+	const commands = command_lines(plain)
+	const marks = [...command_lines(with_environment)].map(
+		([pid, line]) => [pid, mark_of(commands.get(pid), line)] as const,
+	)
+
+	return new Map(marks.filter((pair): pair is [number, string] => pair[1] !== undefined))
+}
+
+function listing(arguments_: ReadonlyArray<string>): string | undefined {
+	const result = spawnSync(PS_COMMAND, arguments_, {
+		encoding: 'utf8',
+		maxBuffer: LISTING_BUFFER_BYTES,
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return result.error === undefined ? result.stdout : undefined
+}
+
+/**
+ * Every marked process's issue, `undefined` where `ps` could not be run or timed out — never read as
+ * "nothing marked".
+ */
+function list_all(platform: NodeJS.Platform = process.platform): Map<number, string> | undefined {
+	if (!LISTING_PLATFORMS.has(platform)) return new Map()
+	const plain = listing(LISTING_ARGUMENTS)
+	const with_environment = listing([ENVIRONMENT_FLAG, ...LISTING_ARGUMENTS])
+
+	if (plain === undefined || with_environment === undefined) return undefined
+
+	return parse(plain, with_environment)
+}
+
+const process_lane_marks = { list_all, parse }
+
+export { process_lane_marks }

package/scripts/lib/atomic-write.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto'
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// Replacing a file so a concurrent reader sees the old content or the new, never half of either.
+//
+// The content is written to a staging file and renamed over the target; `rename` swaps the path
+// itself, so a reader that opened the old file keeps reading it. **The staging name is unique per
+// write** — process id and a random UUID — because two writers sharing one name interleave their bytes
+// into the same staging file and both rename the mix into place. Create-exclusively refuses a name
+// someone else already holds rather than writing through it, and the `finally` removes the staging
+// file on every failing path. The `.tmp` ending keeps it out of a directory scan that matches the
+// target's own extension.
+
+const STAGING_EXTENSION = '.tmp'
+const CREATE_EXCLUSIVE_FLAG = 'wx'
+
+interface AtomicWriteOptions {
+	// Given to the create, so a private file is never readable at another mode in between, and
+	// applied again with `chmod`, so the umask cannot narrow it.
+	readonly mode?: number
+	// Where the staging file is written; the target's directory by default. It must sit on the
+	// target's filesystem for the rename to stay atomic.
+	readonly staging_directory?: string
+}
+
+function staging_path(target: string, staging_directory: string): string {
+	const name = `${path.basename(target)}.${String(process.pid)}.${randomUUID()}${STAGING_EXTENSION}`
+
+	return path.join(staging_directory, name)
+}
+
+function write_staged(staging: string, content: string | Uint8Array, mode?: number): void {
+	writeFileSync(staging, content, {
+		flag: CREATE_EXCLUSIVE_FLAG,
+		...(mode !== undefined && { mode }),
+	})
+	if (mode !== undefined) chmodSync(staging, mode)
+}
+
+function replace_file(
+	target: string,
+	content: string | Uint8Array,
+	options: AtomicWriteOptions = {},
+): void {
+	const directory = options.staging_directory ?? path.dirname(target)
+	const staging = staging_path(target, directory)
+
+	mkdirSync(directory, { recursive: true })
+
+	try {
+		write_staged(staging, content, options.mode)
+		renameSync(staging, target)
+	} finally {
+		rmSync(staging, { force: true })
+	}
+}
+
+const atomic_write = { replace_file }
+
+export { atomic_write }
+export type { AtomicWriteOptions }

package/scripts/lib/buffered-process.ts

@@ -69,6 +69,16 @@ function collect_output(all: string, reason: ReadonlyArray<string>): string {
 	return [all, ...reason].filter((part) => part !== '').join('\n')
 }
 
+// A buffered child writes to a pipe, so it is told to keep its colors unless the caller opted out.
+// Exported for the eslint daemon route (`eslint-daemon.ts`), which buffers the same way.
+function child_environment(): NodeJS.ProcessEnv {
+	const environment = { ...process.env }
+	if (environment['NO_COLOR'] === undefined) environment['FORCE_COLOR'] = FORCE_COLOR
+	else delete environment['FORCE_COLOR']
+
+	return environment
+}
+
 async function run_buffered_process(
 	command_args: ReadonlyArray<string>,
 	options: BufferedProcessOptions = {},
@@ -76,14 +86,11 @@ async function run_buffered_process(
 	// `performance.now()` rather than `Date.now()`: it is monotonic, so a system clock adjusted
 	// mid-check cannot produce a negative or wildly inflated duration.
 	const started_at = performance.now()
-	const environment = { ...process.env }
-	if (environment['NO_COLOR'] === undefined) environment['FORCE_COLOR'] = FORCE_COLOR
-	else delete environment['FORCE_COLOR']
 	// `cwd` is spread in rather than assigned: `exactOptionalPropertyTypes` refuses an explicit
 	// `undefined` for an optional `string`, and passing one anyway breaks execa's overload
 	// resolution — which silently widens `result.all` back to `string | undefined`.
 	const result = await execa(PNPM, [...command_args], {
-		env: environment,
+		env: child_environment(),
 		extendEnv: false,
 		all: true,
 		reject: false,
@@ -104,7 +111,7 @@ function is_process_failed(result: Pick<BufferedProcessResult, 'exit_code'>): bo
 	return result.exit_code !== 0
 }
 
-const buffered_process = { is_process_failed, run_buffered_process }
+const buffered_process = { child_environment, is_process_failed, run_buffered_process }
 
 export type { BufferedProcessResult }
 export { buffered_process, FAIL_EXIT_CODE }

package/scripts/lib/cli-flags.ts

@@ -152,7 +152,59 @@ function attach_values(
 	return attached
 }
 
+// Digits and nothing else. `Number('')`, `Number(' ')` and `Number('0x10')` are all safe integers, so a
+// check that only asked `Number.isSafeInteger` would read an unset shell variable — `--max
+// "$max_issues"` — as zero. The magnitude check is separate because the pattern bounds nothing: a
+// number past the safe range would be read as a different number.
+const COUNT_PATTERN = /^\d+$/u
+// Whole and positive: `0`, a sign, a decimal point and anything not a digit are refused.
+const POSITIVE_PATTERN = /^[1-9]\d*$/u
+
+// The value a positive-integer setting answers, or why it could not be read. A problem rather than a
+// throw: the caller decides whether a bad setting ends the command or is reported and worked around.
+type PositiveSetting = { kind: 'limit'; limit: number } | { kind: 'problem'; problem: string }
+
+function to_integer(raw: string | undefined, pattern: RegExp): number | undefined {
+	if (raw === undefined || !pattern.test(raw)) return undefined
+
+	const parsed = Number(raw)
+
+	return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+// A count flag's value — zero or more — or `undefined` when it is absent or not a count.
+function to_count(raw: string | undefined): number | undefined {
+	return to_integer(raw, COUNT_PATTERN)
+}
+
+// A value that must be one or more, or `undefined` when it is absent or not.
+function to_positive(raw: string | undefined): number | undefined {
+	return to_integer(raw, POSITIVE_PATTERN)
+}
+
+// A positive-integer setting read from the environment or an argument. Blank is unset, not invalid — an
+// `.env` line left as `KEY=` is a setting nobody configured — and answers `fallback`. Anything else that
+// is not a positive integer is a problem naming `name`, never a silent fall back to the default: a typo
+// that quietly became the default is a number nobody chose.
+function read_positive_setting(
+	raw: string | undefined,
+	name: string,
+	fallback: number,
+): PositiveSetting {
+	const trimmed = raw?.trim() ?? ''
+
+	if (trimmed === '') return { kind: 'limit', limit: fallback }
+
+	const limit = to_positive(trimmed)
+	if (limit !== undefined) return { kind: 'limit', limit }
+
+	return { kind: 'problem', problem: `${name} must be a positive integer, not "${trimmed}"` }
+}
+
 const cli_flags = {
+	to_count,
+	to_positive,
+	read_positive_setting,
 	attach_values,
 	usage_line,
 	refuse_unknown_flags,
@@ -167,3 +219,4 @@ const cli_flags = {
 }
 
 export { cli_flags }
+export type { PositiveSetting }

package/scripts/lib/figure-format.ts

@@ -0,0 +1,63 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+
+// The figures the reports print — a dollar amount, a token count, a percentage share, a duration in
+// minutes and a local wall clock — and the precision each uses. The cost reports, `josh time`'s
+// reports, `run:board` and the run event pane all render these, so each is written once here.
+
+const USD_DECIMALS = 4
+const PERCENT_SCALE = 100
+const PERCENT_DECIMALS = 1
+const MINUTE_DECIMALS = 1
+const CLOCK_WIDTH = 2
+const CLOCK_PAD = '0'
+
+// The caller names the decimals where its figure rounds to another place — a run total to the cent.
+function format_usd(usd: number, decimals: number = USD_DECIMALS): string {
+	return `$${usd.toFixed(decimals)}`
+}
+
+function format_tokens(count: number): string {
+	return count.toLocaleString('en-US')
+}
+
+function format_share(part: number, whole: number): string {
+	if (whole === 0) return 'n/a'
+
+	return `${((part / whole) * PERCENT_SCALE).toFixed(PERCENT_DECIMALS)}%`
+}
+
+function format_minutes(duration_ms: number): string {
+	return `${(duration_ms / MS_PER_MINUTE).toFixed(MINUTE_DECIMALS)} min`
+}
+
+function two_digits(value: number): string {
+	return String(value).padStart(CLOCK_WIDTH, CLOCK_PAD)
+}
+
+// The local wall-clock `HH:MM:SS` of a moment.
+function clock_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes(), date.getSeconds()]
+		.map((value) => two_digits(value))
+		.join(':')
+}
+
+// The local wall-clock `HH:MM` of a moment, for one a person reads to the minute.
+function minute_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes()].map((value) => two_digits(value)).join(':')
+}
+
+const figure_format = {
+	format_usd,
+	format_tokens,
+	format_share,
+	format_minutes,
+	two_digits,
+	clock_of,
+	minute_of,
+}
+
+export { figure_format }

package/scripts/lib/json-value.ts

@@ -28,12 +28,20 @@ function parse_with<T>(text: string, schema: z.ZodType<T>): T | undefined {
 	return parsed.success ? parsed.data : undefined
 }
 
+// The read a listing wants: text that is not JSON and JSON that is not an array both answer
+// `undefined`, so a caller can keep "unreadable" apart from an empty listing.
+function parse_array(text: string): Array<unknown> | undefined {
+	const value = parse_or_undefined(text)
+
+	return Array.isArray(value) ? value : undefined
+}
+
 // A plain object, as opposed to an array or a primitive. `typeof null` is `'object'`, and an array
 // answers `'object'` too, so both have to be excluded by hand before a key lookup means anything.
 function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-const json_value = { parse_or_undefined, parse_with, is_record }
+const json_value = { parse_or_undefined, parse_with, parse_array, is_record }
 
 export { json_value }

package/scripts/lib/package-manifest.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import type { z } from 'zod'
+import { json_value } from './json-value'
+import { file_reader } from './read-file'
+
+// The one place a `package.json` is named and read. Readers across `scripts/` had each spelled the
+// file name and written their own read-then-parse; they now ask here, and choose only how a manifest
+// that cannot be read answers.
+const PACKAGE_JSON = 'package.json'
+
+function manifest_path(directory: string): string {
+	return path.join(directory, PACKAGE_JSON)
+}
+
+// For a manifest that must exist: a missing file, text that is not JSON and a shape the schema
+// rejects all throw, so the defect surfaces where it was met.
+function read_manifest<T>(directory: string, schema: z.ZodType<T>): T {
+	const text = readFileSync(manifest_path(directory), 'utf8')
+
+	return schema.parse(JSON.parse(text))
+}
+
+// For a manifest that may be absent or broken without that being this reader's failure: every one of
+// those answers `undefined`.
+function read_manifest_if_valid<T>(directory: string, schema: z.ZodType<T>): T | undefined {
+	const text = file_reader.read_if_readable(manifest_path(directory))
+	if (text === undefined) return undefined
+
+	return json_value.parse_with(text, schema)
+}
+
+const package_manifest = { manifest_path, read_manifest, read_manifest_if_valid }
+
+export { PACKAGE_JSON, package_manifest }

package/scripts/lib/read-file.ts

@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs'
 
 const ABSENT_CODE = 'ENOENT'
 
+// Whether a filesystem error says "there is nothing here" — ENOENT and nothing else. A permission
+// error or ENOTDIR says something is there, so neither reads as absent.
 function is_absent(error: unknown): boolean {
 	return error instanceof Error && 'code' in error && error.code === ABSENT_CODE
 }
@@ -35,6 +37,6 @@ function read_if_readable(path: string): string | undefined {
 	}
 }
 
-const file_reader = { read_optional, read_file_or_empty, read_if_readable }
+const file_reader = { is_absent, read_optional, read_file_or_empty, read_if_readable }
 
 export { file_reader }