@joshuafolkken/kit 1.872.0

package/scripts/run/run-preflight.ts

@@ -0,0 +1,337 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_gh_pr_read } from '#scripts/git/git-gh-pr-read'
+import { z } from 'zod'
+import { run_hold } from './run-hold'
+import { run_issue_number } from './run-issue-number'
+
+// The preflight check — what an interrupted run left in this working tree, and what the rule says to
+// do about it before the next child starts (joshuafolkken/kit#926). It once had its own
+// `josh run:preflight` CLI; joshuafolkken/kit#1965 folded the check into `run:hold`, which now runs it
+// before it claims the tree, so this module is the shared logic behind that claim and behind
+// `run:progress`, and no longer a command of its own.
+//
+// joshuafolkken/kit#1091 gave a run a way to say "this tree is mine". This is the sibling question,
+// and it is about the run that never said anything again: an unattended run ends abnormally — a
+// crash, a Ctrl-C, a laptop asleep, an expired token — and leaves its feature branch, its open pull
+// request and its uncommitted changes behind. Every child of an `epicrun` starts with
+// `git switch main && git pull`, which refuses over a dirty tree, and an agent may not reach for
+// `git stash` on its own judgement, so the batch could not recover without a person.
+//
+// **The rule answers, so the run does not judge.** "There is a branch already, I will carry on from
+// it" and "there is a branch already, I had better stop" are both defensible in the moment, which is
+// exactly why the choice is not left to the moment — the same reason `josh delegate` and
+// `josh review:level` refuse to leave their answers to an agent.
+//
+// **The check is re-askable, which the claim it now gates deliberately is not.** A claim asked twice
+// answers `busy`, because the second ask is a second run. This check reads state and writes nothing,
+// so the reclaim recovery ends by asking `run:hold` again on the tree it just cleaned.
+
+const CLEAN_VERDICT = 'clean'
+const RECLAIM_VERDICT = 'reclaim'
+const RESUME_VERDICT = 'resume'
+const PARK_VERDICT = 'park'
+
+type PreflightVerdict =
+	typeof CLEAN_VERDICT | typeof PARK_VERDICT | typeof RECLAIM_VERDICT | typeof RESUME_VERDICT
+
+const NO_PR = 'none'
+const OPEN_PR = 'open'
+const MERGED_PR = 'merged'
+const CLOSED_PR = 'closed'
+
+type PrState = typeof CLOSED_PR | typeof MERGED_PR | typeof NO_PR | typeof OPEN_PR
+
+interface TreeState {
+	branch: string
+	default_branch: string
+	is_dirty: boolean
+}
+
+interface ChildState {
+	branch_name: string | undefined
+	pr_state: PrState
+}
+
+interface PreflightDecision {
+	advice: string
+	reason: string
+	verdict: PreflightVerdict
+}
+
+const NO_CHILD_WORK: ChildState = { branch_name: undefined, pr_state: NO_PR }
+
+// `pr_view` answers with the three fields `to_pr_info` selects; only the state matters here, and it
+// is already normalized to upper case by `git-gh-rest-state.ts`, so a lower-case REST spelling never
+// reaches this map.
+const pr_info_schema = z.object({ state: z.string().optional() })
+
+const GH_PR_STATES: ReadonlyMap<string, PrState> = new Map([
+	['CLOSED', CLOSED_PR],
+	['MERGED', MERGED_PR],
+	['OPEN', OPEN_PR],
+])
+
+const CLEAN_REASON =
+	'Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no branch or pull request.'
+
+const CLEAN_ADVICE = 'Start the child.'
+
+const RESUME_ADVICE =
+	'Reuse the branch and run the whole verification gate from the start — refactor, `pnpm josh gate`, `/code-review` — never only the part the interrupted run had not reached. Nobody verified what it already committed.'
+
+const PARK_ADVICE =
+	'Park the child: add `needs-decision` and comment what was found. Do not delete the branch, do not reopen the pull request, and do not commit on top of it.'
+
+const STASH_LABEL_PREFIX = 'run:hold reclaimed before #'
+
+// The issue number reaches the advice inside a double-quoted shell command a caller is told to paste,
+// so the shape it may take is pinned beside the interpolation rather than only in the CLI that
+// happens to be today's single caller. `run:liveness` interpolates it the same way, so the pattern
+// and the refusal live in one module both read (joshuafolkken/kit#1485).
+const { ISSUE_NUMBER_PATTERN, require_issue_number } = run_issue_number
+const UNREADABLE_PR_MESSAGE = 'The pull request could not be read for branch '
+
+function needs_reclaim(tree: TreeState): boolean {
+	return tree.is_dirty || tree.branch !== tree.default_branch
+}
+
+// A pull request that was merged or closed is a decision somebody already made. Carrying on over a
+// merged one duplicates work that landed; carrying on over a closed one revives work that was
+// rejected. Which of those is happening is a person's read, so this is the one verdict that parks.
+function is_pr_decided(state: PrState): boolean {
+	return state === MERGED_PR || state === CLOSED_PR
+}
+
+// **The second clause is `decide`'s contract, not a case `check` produces.** A pull request is only
+// ever reached through one of the candidate branches, so a state read from `check` never carries an
+// open pull request without the branch it belongs to — and a pull request whose head branch is gone
+// from the checkout *and* the remote is outside what this command can see at all, which is what
+// `docs/josh-commands.md` says rather than implying coverage the read does not have.
+function has_leftover_work(child: ChildState): boolean {
+	return child.branch_name !== undefined || child.pr_state === OPEN_PR
+}
+
+// The precedence is fixed, and the first row is why it has to be. A `resume` or a `park` decided over
+// a dirty tree hands the next child a checkout it cannot switch — so the tree is reclaimed first and
+// the question asked again on the clean tree, rather than two answers being merged into one.
+function to_verdict(tree: TreeState, child: ChildState): PreflightVerdict {
+	if (needs_reclaim(tree)) return RECLAIM_VERDICT
+
+	if (is_pr_decided(child.pr_state)) return PARK_VERDICT
+
+	if (has_leftover_work(child)) return RESUME_VERDICT
+
+	return CLEAN_VERDICT
+}
+
+function reclaim_reason(tree: TreeState): string {
+	const findings = [
+		tree.is_dirty ? 'uncommitted changes' : undefined,
+		tree.branch === tree.default_branch ? undefined : `HEAD on ${tree.branch}`,
+	].filter((entry): entry is string => entry !== undefined)
+
+	return `An earlier run left ${findings.join(' and ')} in this working tree.`
+}
+
+function park_reason(state: PrState): string {
+	return `The pull request for this issue is ${state}, so whether any work is still owed is a person's call.`
+}
+
+function resume_reason(child: ChildState): string {
+	const branch_part = child.branch_name === undefined ? '' : ` on branch ${child.branch_name}`
+	const pr_part = child.pr_state === OPEN_PR ? ', and its pull request is still open' : ''
+
+	return `An earlier run left a partial implementation${branch_part}${pr_part}.`
+}
+
+function to_reason(verdict: PreflightVerdict, tree: TreeState, child: ChildState): string {
+	if (verdict === RECLAIM_VERDICT) return reclaim_reason(tree)
+
+	if (verdict === PARK_VERDICT) return park_reason(child.pr_state)
+
+	if (verdict === RESUME_VERDICT) return resume_reason(child)
+
+	return CLEAN_REASON
+}
+
+// **`-u` is not optional.** What an interrupted run leaves almost always includes a new `*.test.ts`,
+// which is untracked, and a stash without it leaves exactly those files for the `git switch` that
+// follows to refuse over. **And the stash is recorded rather than popped**, which is what sets this
+// stash apart from every other sanctioned one: the work belongs to a run that is gone, so the Issue
+// comment is the only thing that can ever bring it back.
+//
+// **The stash lines appear only over a dirty tree.** `reclaim` also answers a clean checkout parked on
+// a feature branch, and printing them there tells the caller to record a stash `git stash push` never
+// created — an Issue comment naming nothing, under a rule that says the comment is what restores it.
+function reclaim_steps(tree: TreeState, issue: string): Array<string> {
+	if (!tree.is_dirty) return []
+
+	return [
+		`git stash push -u -m "${STASH_LABEL_PREFIX}${issue}"`,
+		`Record the stash on #${issue} — the comment is what gets it popped; nothing pops it for you.`,
+	]
+}
+
+function reclaim_advice(tree: TreeState, issue: string): string {
+	return [
+		...reclaim_steps(tree, issue),
+		`git switch ${tree.default_branch} && git pull`,
+		'Then ask this command again: it is re-askable, and the clean tree gets its own answer.',
+	].join('\n')
+}
+
+function to_advice(verdict: PreflightVerdict, issue: string, tree: TreeState): string {
+	if (verdict === RECLAIM_VERDICT) return reclaim_advice(tree, issue)
+
+	if (verdict === RESUME_VERDICT) return RESUME_ADVICE
+
+	if (verdict === PARK_VERDICT) return PARK_ADVICE
+
+	return CLEAN_ADVICE
+}
+
+function decide(tree: TreeState, child: ChildState, issue: string): PreflightDecision {
+	const verdict = to_verdict(tree, child)
+
+	return {
+		advice: to_advice(verdict, issue, tree),
+		reason: to_reason(verdict, tree, child),
+		verdict,
+	}
+}
+
+function read_pr_field(raw: string): string | undefined {
+	try {
+		return pr_info_schema.parse(JSON.parse(raw)).state
+	} catch {
+		return undefined
+	}
+}
+
+function to_pr_state(raw: string): PrState {
+	const state = read_pr_field(raw)
+
+	return (state === undefined ? undefined : GH_PR_STATES.get(state)) ?? NO_PR
+}
+
+async function read_tree_state(): Promise<TreeState> {
+	const [is_dirty, current, default_branch] = await Promise.all([
+		run_hold.is_tree_dirty(),
+		git_command.branch(),
+		git_command.get_default_branch(),
+	])
+
+	return { branch: current, default_branch, is_dirty }
+}
+
+// **An unreadable `gh` is not an absent pull request.** `pr_view` folds both into `''` and cannot tell
+// them apart, so the existence question is asked through `pr_exists`, which throws on a lookup it
+// could not complete (joshuafolkken/kit#1048). That throw reaches the CLI as `unknown`; without it a
+// rate-limited or logged-out `gh` turns a **merged** pull request into `resume`, and the run commits
+// on top of work somebody already landed — the exact hazard `park` exists for.
+// **The second half of the same guard.** `pr_exists` refuses to read an unreadable lookup as an
+// absence, but `pr_view` still folds any failure of its own into `''` — and the two are separate
+// round trips, so a rate limit or a 5xx arriving between them would put a **merged** pull request
+// back through `NO_PR` and out as `resume`. An empty answer for a branch `pr_exists` has just
+// confirmed is therefore a failed read by construction, and it throws rather than answering.
+async function read_pr_state(branch_name: string): Promise<PrState> {
+	if (!(await git_gh_pr_read.pr_exists(branch_name))) return NO_PR
+
+	const raw = await git_gh_pr_read.pr_view(branch_name)
+
+	if (raw === '') throw new Error(`${UNREADABLE_PR_MESSAGE}${branch_name}`)
+
+	return to_pr_state(raw)
+}
+
+function is_pr_open(state: PrState): boolean {
+	return state === OPEN_PR
+}
+
+async function read_pr_of_branch(branch_name: string): Promise<ChildState> {
+	return { branch_name, pr_state: await read_pr_state(branch_name) }
+}
+
+// **A decided pull request on any candidate branch outranks an open one on another.** An interrupted
+// run can leave more than one branch for an issue — a retry beside the original — and reading only
+// whichever git lists first hides a merged pull request behind a branch that has none. **The branch
+// reported is the one that produced the winning state**, so the reason never names branch A while the
+// verdict came from branch B's pull request.
+function pick_child_state(reads: ReadonlyArray<ChildState>): ChildState {
+	const decided = reads.find((read) => is_pr_decided(read.pr_state))
+	const open = reads.find((read) => is_pr_open(read.pr_state))
+
+	return decided ?? open ?? { branch_name: reads[0]?.branch_name, pr_state: NO_PR }
+}
+
+// `git branch --list` takes a glob, so the branch is found without knowing its slug: `pnpm josh git`
+// builds `<N>-<slug>` (`scripts/git/git-issue.ts` → `create_branch_name`), and `<N>-*` matches it
+// whatever the title was, while never matching `<N><digit>-…`.
+//
+// **Remote-tracking branches are searched too**, and the remote name is stripped back off, because the
+// pull request is keyed by its head branch: a run interrupted on another machine — or in a checkout
+// since re-cloned — leaves the branch on the remote with no local counterpart, and searching locally
+// alone would answer `clean` over an open pull request.
+const ISSUE_BRANCH_SUFFIX = '-*'
+const ANY_REMOTE_PREFIX = '*/'
+const REMOTE_SEPARATOR = '/'
+const NOT_FOUND_INDEX = -1
+
+function to_head_branch(name: string): string {
+	const separator_index = name.indexOf(REMOTE_SEPARATOR)
+
+	return separator_index === NOT_FOUND_INDEX ? name : name.slice(separator_index + 1)
+}
+
+async function read_branch_candidates(issue: string): Promise<Array<string>> {
+	const pattern = `${issue}${ISSUE_BRANCH_SUFFIX}`
+	const [local, remote] = await Promise.all([
+		git_command.branch_names(pattern),
+		git_command.branch_names_remote(`${ANY_REMOTE_PREFIX}${pattern}`),
+	])
+
+	return [...new Set([...local, ...remote.map((name) => to_head_branch(name))])]
+}
+
+async function read_child_state(issue: string): Promise<ChildState> {
+	const candidates = await read_branch_candidates(issue)
+
+	return pick_child_state(
+		await Promise.all(candidates.map(async (name) => await read_pr_of_branch(name))),
+	)
+}
+
+// The child read is skipped where the tree already answers `reclaim`: a `gh` round trip buys nothing
+// there, because the verdict would be `reclaim` whatever it said, and the recovery ends by asking
+// this command again on the clean tree.
+async function check(issue: string): Promise<PreflightDecision> {
+	require_issue_number(issue)
+
+	const tree = await read_tree_state()
+
+	if (needs_reclaim(tree)) return decide(tree, NO_CHILD_WORK, issue)
+
+	return decide(tree, await read_child_state(issue), issue)
+}
+
+const run_preflight = {
+	CLEAN_ADVICE,
+	CLEAN_REASON,
+	CLEAN_VERDICT,
+	ISSUE_NUMBER_PATTERN,
+	PARK_ADVICE,
+	PARK_VERDICT,
+	RECLAIM_VERDICT,
+	RESUME_ADVICE,
+	RESUME_VERDICT,
+	MERGED_PR,
+	STASH_LABEL_PREFIX,
+	check,
+	decide,
+	read_child_state,
+	read_pr_state,
+	to_pr_state,
+}
+
+export type { ChildState, PreflightDecision, PreflightVerdict, PrState, TreeState }
+export { run_preflight }

package/scripts/run/run-prep-cli.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_stash } from '#scripts/git/git-stash'
+import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
+import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
+import { run_prep, type PrepParts } from './run-prep'
+
+// `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
+// (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and
+// `human_review` line (`issue:state`), and the dependency-update scope (`latest:scope`). Each is
+// reused rather than reproduced, and the two body reads run concurrently, so three round trips become
+// one.
+//
+// **The hold and the cost check stay their own calls.** `run:hold` writes the working-tree record and
+// `cost --over` reads the session, not the issue; folding a side effect and a session read into a
+// bundle of issue reads would make one command answer three unrelated questions. They are batched in
+// the same turn as this one instead.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh run:prep <issue-number>'
+const LANE_SKIP_SCOPE = 'not asked'
+const LANE_SKIP_REASON =
+	'a dispatched lane child does not run josh latest — the parent does, once per session'
+
+interface LatestDecision {
+	scope: string
+	reason: string
+}
+
+interface PrepReads {
+	content: BlockRead
+	state: StateRead
+	latest: LatestDecision
+	has_changes: boolean
+}
+
+// Exactly one issue number, or the call is refused: `run:prep` prepares one run, and a second number
+// would print a second issue's body a caller reads as this run's own.
+function parse_number(argv: ReadonlyArray<string>): string | undefined {
+	const [first] = argv
+
+	if (first === undefined || argv.length !== 1 || !ISSUE_NUMBER_PATTERN.test(first)) {
+		return undefined
+	}
+
+	return first
+}
+
+// One note for a read that produced nothing, naming which of the two it was — the same distinction
+// `issue:read` and `issue:state` keep, so a bundled failure still tells a retry from an answer.
+function failure_note(issue_number: string, kind: string): string {
+	return `(issue #${issue_number} not bundled: ${kind})`
+}
+
+// A dispatched lane child never runs `josh latest` — the parent does it once per session
+// (`backlogrun.md` → "`josh latest` runs once per session, not once per child"), so computing the
+// dependency scope inside a lane would report a decision nothing there acts on. Skip the read and say
+// so, rather than printing a `required` a lane never honors.
+function latest_decision(): LatestDecision {
+	if (lane_child_marker.is_child_of(process.cwd())) {
+		return { scope: LANE_SKIP_SCOPE, reason: LANE_SKIP_REASON }
+	}
+
+	return latest_scope_cli.decide()
+}
+
+// Whether a dispatched lane child's tree holds uncommitted work (joshuafolkken/kit#2476). A lane child
+// that popped its parked work back and then found its issue closed is the one position that work is
+// lost from — the lane is removed by force — so only a lane is asked; a person's own checkout keeps its
+// unrelated edits out of the verdict. A status that cannot be read reports none, leaving the verdict
+// printed before this read existed.
+async function lane_has_changes(): Promise<boolean> {
+	if (!lane_child_marker.is_child_of(process.cwd())) return false
+
+	try {
+		return await git_stash.has_changes(process.cwd())
+	} catch {
+		return false
+	}
+}
+
+async function gather(issue_number: string): Promise<PrepReads> {
+	const [content, state, has_changes] = await Promise.all([
+		issue_read_cli.read_block(issue_number),
+		issue_state_cli.read_issue(issue_number),
+		lane_has_changes(),
+	])
+
+	return { content, state, latest: latest_decision(), has_changes }
+}
+
+function content_body(issue_number: string, content: BlockRead): string {
+	return content.kind === 'ok' ? content.block : failure_note(issue_number, content.kind)
+}
+
+function to_parts(issue_number: string, reads: PrepReads): PrepParts {
+	const state = reads.state.kind === 'state' ? reads.state.state : undefined
+	const state_failure = state === undefined ? failure_note(issue_number, reads.state.kind) : ''
+
+	return {
+		issue_number,
+		content_body: content_body(issue_number, reads.content),
+		state,
+		state_failure,
+		latest_scope: reads.latest.scope,
+		latest_reason: reads.latest.reason,
+		has_changes: reads.has_changes,
+	}
+}
+
+// Non-zero when either issue read failed, exactly as `issue:read` and `issue:state` each exit, so a
+// bundle missing a part is never read as a complete one.
+function exit_code(reads: PrepReads): number {
+	const is_complete = reads.content.kind === 'ok' && reads.state.kind === 'state'
+
+	return is_complete ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reads = await gather(issue_number)
+
+	console.info(run_prep.format_report(to_parts(issue_number, reads)))
+
+	return exit_code(reads)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+// `gather` and `to_parts` are exported so `run:next` reads the same state from the same three reads
+// rather than growing a second copy of the gather (joshuafolkken/kit#2188) — `run:next` is the
+// consumer of `run:prep` the epic #2166 wanted.
+const run_prep_cli = { USAGE, gather, main, parse_number, run, to_parts }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_prep_cli }

package/scripts/run/run-prep.ts

@@ -0,0 +1,84 @@
+import { issue_state, type IssueState } from '#scripts/issue/issue-state'
+
+// `josh run:prep <N>` — the reads a `fullrun` makes before its first edit, assembled into one report
+// (joshuafolkken/kit#1978). Two earlier passes at the setup phase were a documentation rule
+// (joshuafolkken/kit#1847) and a measurement (joshuafolkken/kit#1868); neither was an execution-side
+// change, and the `setup` median did not move. This joins the issue body and comments, the state and
+// `human_review` line, and the dependency-update scope that `issue:read`, `issue:state` and
+// `latest:scope` answered in three separate calls — reusing each rather than reproducing it.
+//
+// The leading summary line carries the three facts a run branches on — the state, whether the issue
+// stops before its commit, and whether a dependency update is owed — so the decision is read off the
+// first line without parsing the sections below it.
+
+const SUMMARY_PREFIX = 'prep #'
+const STATE_LABEL = 'state: '
+const HUMAN_REVIEW_LABEL = 'human_review: '
+const LATEST_LABEL = 'latest: '
+const FIELD_SEPARATOR = ' · '
+const SUMMARY_DASH = ' — '
+const UNKNOWN = '?'
+const YES = 'yes'
+const NO = 'no'
+const CONTENT_HEADER = '=== issue ==='
+const STATE_HEADER = '=== state ==='
+const LATEST_HEADER = '=== dependency update ==='
+const SECTION_SEPARATOR = '\n\n'
+const LATEST_JOINER = ' — '
+
+interface PrepParts {
+	issue_number: string
+	content_body: string
+	// `undefined` when the state read failed; `state_failure` then carries the note that stands in for
+	// the three-line block, so a bundled failure never prints as an empty state.
+	state: IssueState | undefined
+	state_failure: string
+	latest_scope: string
+	latest_reason: string
+	// Whether a lane child's tree holds uncommitted work — read for the verdict, not printed in the
+	// report (joshuafolkken/kit#2476).
+	has_changes: boolean
+}
+
+function human_review_value(state: IssueState | undefined): string {
+	if (state === undefined) return UNKNOWN
+
+	return state.is_human_review ? YES : NO
+}
+
+function summary(parts: PrepParts): string {
+	const state_value = parts.state === undefined ? UNKNOWN : parts.state.state
+	const fields = [
+		`${STATE_LABEL}${state_value}`,
+		`${HUMAN_REVIEW_LABEL}${human_review_value(parts.state)}`,
+		`${LATEST_LABEL}${parts.latest_scope}`,
+	]
+
+	return `${SUMMARY_PREFIX}${parts.issue_number}${SUMMARY_DASH}${fields.join(FIELD_SEPARATOR)}`
+}
+
+// The state's three lines come from `issue:state`'s own formatter, so the spelling a document compares
+// against — `human_review: yes` included — is the one this bundle prints.
+function state_body(parts: PrepParts): string {
+	return parts.state === undefined
+		? parts.state_failure
+		: issue_state.format_issue_state(parts.state)
+}
+
+function section(header: string, body: string): string {
+	return `${header}\n${body}`
+}
+
+function format_report(parts: PrepParts): string {
+	return [
+		summary(parts),
+		section(CONTENT_HEADER, parts.content_body),
+		section(STATE_HEADER, state_body(parts)),
+		section(LATEST_HEADER, `${parts.latest_scope}${LATEST_JOINER}${parts.latest_reason}`),
+	].join(SECTION_SEPARATOR)
+}
+
+const run_prep = { CONTENT_HEADER, LATEST_HEADER, STATE_HEADER, SUMMARY_PREFIX, format_report }
+
+export type { PrepParts }
+export { run_prep }

package/scripts/run/run-progress-args.ts

@@ -0,0 +1,65 @@
+import { parseArgs } from 'node:util'
+import { run_progress_config } from './run-progress-config'
+
+// The argument half of `josh run:progress`, kept apart from the watcher so the CLI stays inside the file
+// limit (joshuafolkken/kit#2503). Everything here is pure: argv in, values out.
+
+// A watcher outlives the turn that started it, so something has to end it. One hour is three of the
+// default twenty-minute intervals: long enough that the bound never truncates a report, short enough
+// that a watcher left waiting on a run that has already merged is gone within the hour. It is
+// deliberately **not** `run:hold`'s eight-hour expiry — that holds an uncommitted working tree across
+// a person's latency and is trampled by being short (joshuafolkken/kit#1091), while a watcher holds
+// only a heartbeat the caller restarts on the next interval, so the two guard different things and
+// only one has anything to lose by being short.
+const DEFAULT_MAX_HOURS = 1
+const MS_PER_HOUR = 3_600_000
+
+const OPTIONS = {
+	hours: { type: 'string' },
+	interval: { type: 'string' },
+	mark: { type: 'boolean' },
+	once: { type: 'boolean' },
+	output: { type: 'string', multiple: true },
+	path: { type: 'boolean' },
+	repo: { type: 'string' },
+	wait: { type: 'boolean' },
+} as const
+
+interface ParsedValues {
+	hours?: string
+	interval?: string
+	mark?: boolean
+	once?: boolean
+	output?: Array<string>
+	path?: boolean
+	repo?: string
+	wait?: boolean
+}
+
+function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
+	try {
+		return parseArgs({ args: [...argv], options: OPTIONS }).values
+	} catch {
+		return undefined
+	}
+}
+
+// A hand-typed `--interval` outranks the environment, the environment outranks the interval the
+// repository commits, and that outranks the twenty-minute default. Every step goes through the same
+// reader, so an unusable value falls back rather than ending an unattended run over an optional
+// setting — `run-progress-config.ts` → `resolve_interval_ms` is where that order is written down.
+function to_interval_ms(raw: string | undefined): number {
+	return run_progress_config.resolve_interval_ms(raw)
+}
+
+function to_max_ms(raw: string | undefined): number {
+	const hours = Number(raw)
+	const is_usable = raw !== undefined && Number.isFinite(hours) && hours > 0
+
+	return (is_usable ? hours : DEFAULT_MAX_HOURS) * MS_PER_HOUR
+}
+
+const run_progress_args = { DEFAULT_MAX_HOURS, read_arguments, to_interval_ms, to_max_ms }
+
+export type { ParsedValues }
+export { run_progress_args }