@joshuafolkken/kit 1.1514.0 → 1.2114.0

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/poll.ts

@@ -1,4 +1,4 @@
-// One bounded polling loop and one sleep, in one place.
+// One polling loop — bounded by attempts, or ended only by its read — and one sleep, in one place.
 //
 // **Three modules had already written the same three-line `sleep`** — `gh/git-pr-checks.ts`,
 // `eval/eval-run.ts` and `propagate/propagate-publish.ts` — and the release command's tag watch
@@ -24,9 +24,6 @@ interface PollOptions {
 	sleeper?: (duration_ms: number) => Promise<void>
 }
 
-// **True as soon as `is_done` answers true, false when the attempts run out.** The first attempt runs
-// before any wait, so a condition already met costs nothing — which is the common case for a tag that
-// was created while the command was doing something else.
 // **The wait goes between attempts, never after the last one**, so the budget a caller computes from
 // `attempts × interval_ms` is the budget it actually spends. The pre-existing merge-gate loop in
 // `git-pr-checks.ts` guards its sleep the same way; extracted here so the loop keeps one branch.
@@ -39,21 +36,53 @@ async function wait_between(
 	if (attempt < attempts - 1) await wait(interval_ms)
 }
 
-async function poll_until(is_done: () => Promise<boolean>, options: PollOptions): Promise<boolean> {
+type WaitOptions = Omit<PollOptions, 'attempts'>
+
+// **The first value `read` answers, `undefined` when the attempts run out.** `undefined` is "not yet",
+// so a read that reaches a verdict — success or failure — answers it and the loop ends there.
+async function poll_for<T>(
+	read: () => Promise<T | undefined> | T | undefined,
+	options: PollOptions,
+): Promise<T | undefined> {
 	const wait = options.sleeper ?? sleep
 
 	for (let attempt = 0; attempt < options.attempts; attempt += 1) {
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		if (await is_done()) return true
+		const value = await read()
+		if (value !== undefined) return value
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await wait_between(wait, options.interval_ms, attempt, options.attempts)
 	}
 
-	return false
+	return undefined
+}
+
+// **True as soon as `is_done` answers true, false when the attempts run out.** The first attempt runs
+// before any wait, so a condition already met costs nothing — which is the common case for a tag that
+// was created while the command was doing something else.
+async function poll_until(
+	is_done: () => Promise<boolean> | boolean,
+	options: PollOptions,
+): Promise<boolean> {
+	const is_reached = await poll_for(async () => ((await is_done()) ? true : undefined), options)
+
+	return is_reached === true
+}
+
+// **A wait that ends only when `read` answers** — a child process exiting, a ship leaving `running`.
+// Its bound, if any, is the read's own: a wall-clock deadline the read answers with its failure.
+async function wait_for<T>(
+	read: () => Promise<T | undefined> | T | undefined,
+	options: WaitOptions,
+): Promise<T> {
+	const value = await poll_for(read, { ...options, attempts: Infinity })
+	if (value === undefined) throw new Error('an unbounded poll ran out of attempts')
+
+	return value
 }
 
-const poll = { poll_until, sleep }
+const poll = { poll_for, poll_until, sleep, wait_for }
 
 export { poll }
-export type { PollOptions }
+export type { PollOptions, WaitOptions }

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 }

package/scripts/lib/settled-together.ts

@@ -0,0 +1,10 @@
+// Both steps run to their end before either's failure is thrown, so neither is left half-done behind
+// the other's failure. The first step's failure is thrown when both failed.
+async function settled_together(first: Promise<void>, second: Promise<void>): Promise<void> {
+	const [result, other] = await Promise.allSettled([first, second])
+
+	if (result.status === 'rejected') throw result.reason
+	if (other.status === 'rejected') throw other.reason
+}
+
+export { settled_together }

package/scripts/lib/shell-quote.ts

@@ -0,0 +1,21 @@
+// One word for a POSIX shell, in single quotes, so a `$`, a backtick or a `"` in it is never expanded
+// or ends the word: a quote inside closes the word, adds an escaped quote and reopens it.
+
+const QUOTE = "'"
+const ESCAPED_QUOTE = String.raw`'\''`
+
+function single_quoted(text: string): string {
+	return QUOTE + text.split(QUOTE).join(ESCAPED_QUOTE) + QUOTE
+}
+
+// A token of only these characters means the same to the shell quoted or not, so it is left bare.
+const BARE_WORD = /^[\w%+,./:=@-]+$/u
+
+// `token` as one shell word: bare when quoting would change nothing, single-quoted otherwise.
+function word(token: string): string {
+	return BARE_WORD.test(token) ? token : single_quoted(token)
+}
+
+const shell_quote = { single_quoted, word }
+
+export { shell_quote }

package/scripts/lib/stamped-memo.ts

@@ -0,0 +1,63 @@
+import { lstatSync } from 'node:fs'
+
+// An answer remembered per key, recomputed only when the key's stamp changes (joshuafolkken/kit#4263).
+//
+// **`run:board` redraws every second, and most of what it reads has not changed since the last
+// redraw.** A process's app name, a ledger's parsed lines and a work tree's git config were computed
+// again on every pass, and on a saturated machine those passes stopped the spinner for 45–200ms. The
+// stamp is what says "this has changed": a file's `file_stamp`, or a constant where the key alone
+// decides the answer.
+
+const NO_STAMP = ''
+const STAMP_SEPARATOR = ':'
+
+interface Remembered<Value> {
+	stamp: string
+	value: Value
+}
+
+interface StampedMemo<Value> {
+	// `compute`'s answer for `key`, run only when `key` was never seen or its stamp moved since.
+	of: (key: string, stamp: string, compute: () => Value) => Value
+	// Forget every key outside `keys` — a process gone from the table, so the memo cannot grow unbounded.
+	keep: (keys: ReadonlySet<string>) => void
+}
+
+function create<Value>(): StampedMemo<Value> {
+	const answers = new Map<string, Remembered<Value>>()
+
+	return {
+		of(key, stamp, compute) {
+			const known = answers.get(key)
+
+			if (known?.stamp === stamp) return known.value
+
+			const value = compute()
+
+			answers.set(key, { stamp, value })
+
+			return value
+		},
+		keep(keys) {
+			for (const key of answers.keys()) if (!keys.has(key)) answers.delete(key)
+		},
+	}
+}
+
+// What changes when a file is rewritten, appended to, replaced or re-owned: its inode, its modification
+// and change times and its size. An absent or unreadable file is `NO_STAMP`, so it reads again once
+// it appears.
+function file_stamp(file: string): string {
+	try {
+		const status = lstatSync(file)
+
+		return [status.ino, status.mtimeMs, status.ctimeMs, status.size].join(STAMP_SEPARATOR)
+	} catch {
+		return NO_STAMP
+	}
+}
+
+const stamped_memo = { NO_STAMP, create, file_stamp }
+
+export { stamped_memo }
+export type { StampedMemo }

package/scripts/lib/stdout-on-stderr.ts

@@ -0,0 +1,24 @@
+// Runs work whose own reports go to stdout with stdout pointed at stderr, for a caller whose stdout is
+// a contract: the `Stop` hook's decision envelope, and `josh run:hold`'s single verdict token.
+
+type StreamWrite = typeof process.stdout.write
+
+function set_stdout_write(stream_write: StreamWrite): void {
+	process.stdout.write = stream_write
+}
+
+async function run<T>(work: () => Promise<T>): Promise<T> {
+	const saved = { write: process.stdout.write.bind(process.stdout) }
+
+	set_stdout_write(process.stderr.write.bind(process.stderr))
+
+	try {
+		return await work()
+	} finally {
+		set_stdout_write(saved.write)
+	}
+}
+
+const stdout_on_stderr = { run }
+
+export { stdout_on_stderr }

package/scripts/lib/timeouts.ts

@@ -3,6 +3,12 @@
 // limit stays stuck where it stopped and never comes back, so every such
 // call takes one of these, and a value used in more than one place is named once here.
 
+// The unit conversions every duration is read and printed through. They sit beside the limits because a
+// limit is the most common thing they convert; a second copy in a caller is a clone of these two lines.
+const MS_PER_SECOND = 1000
+const SECONDS_PER_MINUTE = 60
+const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE
+
 // A probe that only asks the local machine (`ps`, `lsof`, `git config`) on a path something else is
 // waiting on. Failing answers "cannot tell", which every caller handles, so anything slower is a fault.
 const PROBE_TIMEOUT_MS = 2000
@@ -41,6 +47,9 @@ export {
 	HOOK_PROCESS_TIMEOUT_MS,
 	INSTALL_TIMEOUT_MS,
 	LINT_TIMEOUT_MS,
+	MS_PER_MINUTE,
+	MS_PER_SECOND,
 	PROBE_TIMEOUT_MS,
+	SECONDS_PER_MINUTE,
 	SUITE_TIMEOUT_MS,
 }