@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/pause/run-pause.ts

@@ -0,0 +1,251 @@
+import { epic_add } from '#scripts/epic/epic-add'
+import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
+import { epic_index } from '#scripts/epic/epic-index'
+import { epic_reconcile } from '#scripts/epic/epic-reconcile'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { stash_push_cli } from '#scripts/git/stash/stash-push-cli'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { z } from 'zod'
+
+// `josh run:pause <M> --for <N>` — set a run aside while its prerequisite `#N` lands first
+// (`prerequisite.md`): the work in progress stashed under a fixed name, a comment on `#M` naming the
+// pop, `#M` blocked by `#N` and the hold released, in that order.
+//
+// **Every step asks whether it is already done before it acts**, so a rerun after a failure carries on
+// from the step that failed rather than stashing, commenting or recording twice. The state lives where
+// each write lands — the stash stack, the Issue's comments and its `blocked_by` relations — so no
+// record of its own is kept. Each write is the existing command's implementation, not a copy of it.
+
+// `epic:bundle`'s own listing limit, so both commands see the same epics.
+const EPIC_LIMIT = 200
+const SUCCESS_EXIT_CODE = 0
+const ALREADY = 'already'
+const comment_schema = z.object({ body: z.string().nullish() })
+
+interface PauseRequest {
+	issue: string
+	prerequisite: string
+}
+
+type StepName = 'stash' | 'comment' | 'blocked-by' | 'release'
+
+interface StepReport {
+	step: StepName
+	detail: string
+}
+
+type PauseResult =
+	| { kind: 'paused'; done: ReadonlyArray<StepReport> }
+	| { kind: 'failed'; step: StepName; reason: string; done: ReadonlyArray<StepReport> }
+
+function stash_message(request: PauseRequest): string {
+	return `run:pause: ${issue_cite.plain(request.issue)} waits on ${issue_cite.plain(request.prerequisite)}`
+}
+
+function comment_marker(request: PauseRequest): string {
+	return `<!-- josh:run-pause ${issue_cite.plain(request.issue)} for ${issue_cite.plain(request.prerequisite)} -->`
+}
+
+async function is_stashed(request: PauseRequest): Promise<boolean> {
+	return git_stash.select(await git_stash.list(), stash_message(request)).kind !== 'none'
+}
+
+async function stash_step(request: PauseRequest): Promise<string> {
+	if (await is_stashed(request)) return ALREADY
+
+	return await stash_push_cli.set_aside({ message: stash_message(request), dir: undefined })
+}
+
+function pause_comment(request: PauseRequest, is_work_stashed: boolean): string {
+	const work = is_work_stashed
+		? `- The work in progress was stashed. After \`pnpm josh ms\`, recover it with \`pnpm josh stash:pop "${stash_message(request)}"\` (expect conflicts).`
+		: '- The tree held no uncommitted work, so nothing was stashed.'
+
+	return [
+		`Paused: ${issue_cite.plain(request.prerequisite)} has to land first.`,
+		work,
+		comment_marker(request),
+	].join('\n')
+}
+
+async function has_pause_comment(request: PauseRequest): Promise<boolean> {
+	const json = await git_gh_issue_read.issue_list_comments(request.issue)
+	const rows = json === undefined ? undefined : parse_json_array_or_undefined(json, comment_schema)
+
+	if (rows === undefined) {
+		throw new Error(`the comments on ${session_cite.issue(request.issue)} could not be read`)
+	}
+
+	return rows.some((row) => row.body?.includes(comment_marker(request)) === true)
+}
+
+async function comment_step(request: PauseRequest): Promise<string> {
+	if (await has_pause_comment(request)) return ALREADY
+
+	const body = pause_comment(request, await is_stashed(request))
+
+	return await git_gh_issue_write.issue_comment(request.issue, body)
+}
+
+async function is_blocked(request: PauseRequest): Promise<boolean> {
+	const blockers = await git_gh_issue_read.issue_blocked_by_numbers(request.issue)
+
+	return blockers.includes(Number(request.prerequisite))
+}
+
+interface Tracking {
+	epic: number
+	// Whether the same epic already tracks the prerequisite as a row of its own.
+	is_prerequisite_child: boolean
+}
+
+// Every epic listing the child, not the one `build_epic_index` keeps: a child a second epic also
+// lists is still a row of this one.
+function is_listed_by(
+	epics: ReadonlyArray<{ number: number; body: string }>,
+	child: string,
+	epic: number,
+): boolean {
+	return epic_index.build_tracking_index(epics).get(Number(child))?.includes(epic) === true
+}
+
+// A listing cut short is no answer about absence: an epic past the cut tracks `#M` invisibly, and a
+// direct relation written then leaves that epic recording an order its body never declares.
+async function tracking_epic(request: PauseRequest): Promise<Tracking | undefined> {
+	const fetched = await epic_index.fetch_epics(EPIC_LIMIT)
+	if (fetched === undefined) throw new Error('the open epics could not be read')
+	const index = epic_index.build_epic_index(fetched.epics)
+	const epic = index.get(Number(request.issue))
+
+	if (epic === undefined && !epic_bundle_gaps.is_membership_established(fetched.cutoff)) {
+		throw new Error('the open epics were not read in full, so an epic tracking it may be unseen')
+	}
+
+	if (epic === undefined) return undefined
+
+	return { epic, is_prerequisite_child: is_listed_by(fetched.epics, request.prerequisite, epic) }
+}
+
+async function add_to_epic(epic: number, request: PauseRequest): Promise<void> {
+	const code = await epic_add.add_children({
+		epic_number: epic,
+		children: [Number(request.prerequisite)],
+		position: { kind: 'before', target: Number(request.issue) },
+	})
+
+	if (code !== SUCCESS_EXIT_CODE) {
+		throw new Error(`\`epic --add\` into ${session_cite.issue(epic)} failed`)
+	}
+}
+
+async function record_relation(request: PauseRequest): Promise<void> {
+	if (await git_gh_issue_write.issue_add_blocked_by(request.issue, request.prerequisite)) return
+
+	throw new Error('the blocked-by relation was not recorded')
+}
+
+async function refuse_unreconcilable(epic: number, request: PauseRequest): Promise<void> {
+	const link = { blocker: Number(request.prerequisite), blocked: Number(request.issue) }
+	const refusal = await epic_reconcile.refusal_after(epic, link)
+	if (refusal === undefined) return
+
+	throw new Error(
+		`\`pnpm josh epic --reconcile ${String(epic)}\` would refuse the relation, so none was recorded: ${refusal}`,
+	)
+}
+
+async function reconcile_epic(epic: number): Promise<void> {
+	if ((await epic_reconcile.reconcile_epic(epic)) === SUCCESS_EXIT_CODE) return
+
+	throw new Error(
+		`the relation was recorded, but \`pnpm josh epic --reconcile ${String(epic)}\` failed to declare it`,
+	)
+}
+
+// A prerequisite outside the epic gains its row, declaration and relation from `epic --add --before`.
+// One the epic already tracks does not: `epic --add` reads it as a move and drops every order it
+// already had, where a pause only adds one — so the relation is recorded directly and
+// `epic --reconcile` copies it into the declaration beside the others, once a dry plan shows the
+// reconcile accepts it: a refusal after the write would leave the relation undeclared. `epic --add`
+// exits 0 on a relation it failed to post, so the relation is read back after the insertion.
+async function record_in_epic(tracking: Tracking, request: PauseRequest): Promise<string> {
+	if (tracking.is_prerequisite_child) {
+		await refuse_unreconcilable(tracking.epic, request)
+		await record_relation(request)
+		await reconcile_epic(tracking.epic)
+	} else {
+		await add_to_epic(tracking.epic, request)
+		if (!(await is_blocked(request))) await record_relation(request)
+	}
+
+	return `recorded in epic ${session_cite.issue(tracking.epic)}`
+}
+
+// A relation recorded inside an epic tracking both issues is only done once it is declared, so a
+// rerun past a failed reconcile reconciles again — a no-op on an epic that already declares it.
+async function settle_recorded(request: PauseRequest): Promise<string> {
+	const tracking = await tracking_epic(request)
+	if (tracking?.is_prerequisite_child === true) await reconcile_epic(tracking.epic)
+
+	return ALREADY
+}
+
+async function blocked_by_step(request: PauseRequest): Promise<string> {
+	if (await is_blocked(request)) return await settle_recorded(request)
+
+	const tracking = await tracking_epic(request)
+	if (tracking !== undefined) return await record_in_epic(tracking, request)
+	await record_relation(request)
+
+	return 'recorded'
+}
+
+// Releasing a free record is a success, so a rerun past this step answers `released` again.
+async function release_step(request: PauseRequest): Promise<string> {
+	const code = await run_hold_cli.run(['--release', request.issue])
+	if (code !== SUCCESS_EXIT_CODE) throw new Error('`run:release` refused')
+
+	return 'released'
+}
+
+const STEPS: ReadonlyArray<[StepName, (request: PauseRequest) => Promise<string>]> = [
+	['stash', stash_step],
+	['comment', comment_step],
+	['blocked-by', blocked_by_step],
+	['release', release_step],
+]
+
+async function attempt(
+	act: (request: PauseRequest) => Promise<string>,
+	request: PauseRequest,
+): Promise<{ detail: string } | { reason: string }> {
+	try {
+		return { detail: await act(request) }
+	} catch (error) {
+		return { reason: error_text.message_of(error) }
+	}
+}
+
+async function pause(request: PauseRequest): Promise<PauseResult> {
+	const done: Array<StepReport> = []
+
+	for (const [step, act] of STEPS) {
+		// eslint-disable-next-line no-await-in-loop -- each step runs only once the one before it landed
+		const outcome = await attempt(act, request)
+		if ('reason' in outcome) return { kind: 'failed', step, reason: outcome.reason, done }
+		done.push({ step, detail: outcome.detail })
+	}
+
+	return { kind: 'paused', done }
+}
+
+const run_pause = { pause }
+
+export type { PauseRequest, PauseResult, StepReport }
+export { run_pause }

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

@@ -1,11 +1,10 @@
-#!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
-import { fileURLToPath } from 'node:url'
 import { backlog_arrival, type ArrivalProbe } from '#scripts/backlog/backlog-arrival'
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_progress, type ProgressState } from './run-progress'
 import { run_progress_args, type ParsedValues } from './run-progress-args'
@@ -34,7 +33,6 @@ import { run_progress_read, type ObservationRead } from './run-progress-read'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // How often the loop wakes to look at the clock — not how often it reports. It is short relative to
 // the interval so that a `--mark` written by the run is noticed promptly, and long enough that a
 // watcher left running overnight costs nothing measurable.
@@ -78,7 +76,7 @@ const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
 const REPO_LOOKUP_TIMEOUT_SECONDS = 10
-const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * run_progress.MS_PER_SECOND
+const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * MS_PER_SECOND
 // A lookup that timed out or failed is not an argument the caller got wrong, so it is told apart from
 // the usage error — read as one, it would send a person to fix arguments that were correct.
 const REPO_UNRESOLVED_NOTICE = `The repository could not be resolved (\`gh\` did not answer within ${String(REPO_LOOKUP_TIMEOUT_SECONDS)}s or failed), so the progress watcher did not start. Pass \`--repo <owner/repo>\` and start it again.`
@@ -215,7 +213,7 @@ async function emit(options: WatchOptions, context: EmitContext): Promise<EmitRe
 function decline(loop: WatchLoop, now_ms: number, notice: string): WatchLoop {
 	if (loop.said !== notice) console.error(notice)
 
-	const cooldown_ms = DECLINE_RETRY_SECONDS * run_progress.MS_PER_SECOND
+	const cooldown_ms = DECLINE_RETRY_SECONDS * MS_PER_SECOND
 
 	return { ...loop, retry_at_ms: now_ms + cooldown_ms, said: notice }
 }
@@ -442,7 +440,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 		max_ms: run_progress_args.to_max_ms(values.hours, values.wait === true),
 		output_paths: values.output ?? [],
 		repo,
-		tick_ms: TICK_SECONDS * run_progress.MS_PER_SECOND,
+		tick_ms: TICK_SECONDS * MS_PER_SECOND,
 	}
 }
 
@@ -480,10 +478,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await run_watch(values)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_progress_cli = {
 	DECLINE_RETRY_SECONDS,
 	DEFAULT_WAIT_MAX_HOURS,
@@ -503,7 +497,5 @@ const run_progress_cli = {
 	wait_once,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { WatchLoop, WatchOptions }
 export { run_progress_cli }

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

@@ -2,6 +2,7 @@ import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { z } from 'zod'
 
 // The report clock `josh run:progress` keeps, in the one form both of its readers can use.
@@ -48,7 +49,6 @@ const LOG_SUFFIX = '.log'
 // A few hours of heartbeats at the twenty-minute interval — enough to read the run's recent shape, and
 // bounded so an unattended run cannot grow the file without limit.
 const LOG_KEEP = 12
-const MS_PER_MINUTE = 60_000
 // Longer than any heartbeat interval and shorter than any gap between two runs. Heartbeats land at most
 // one interval apart while a run is live (twenty minutes by default, well under this), so a newest block
 // older than this belongs to a previous run: past it the log is reset rather than extended, and a fresh

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

@@ -1,7 +1,6 @@
-import { readFileSync } from 'node:fs'
-import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
-import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { z } from 'zod'
 import { run_progress } from './run-progress'
 
@@ -25,8 +24,6 @@ import { run_progress } from './run-progress'
 // Reading the working directory alone would let the guard enforce the repository's interval while the
 // watcher it guards kept the default, which is the one state this module exists to prevent.
 
-const PACKAGE_FILE = 'package.json'
-
 // Unknown keys are stripped rather than rejected: this reads a whole `package.json`, and every other
 // field in it is none of this module's business. A present-but-unusable interval fails the parse and
 // falls through, which is the same answer an unusable environment variable already gets.
@@ -35,13 +32,8 @@ const package_schema = z.object({
 })
 
 function read_declared_minutes(directory: string): number | undefined {
-	try {
-		const raw = readFileSync(path.join(directory, PACKAGE_FILE), 'utf8')
-
-		return json_value.parse_with(raw, package_schema)?.josh?.progress_interval_minutes
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(directory, package_schema)?.josh
+		?.progress_interval_minutes
 }
 
 function read_package_minutes(start: string): number | undefined {
@@ -55,7 +47,7 @@ function read_package_minutes(start: string): number | undefined {
 }
 
 function to_ms(minutes: number | undefined): number | undefined {
-	return minutes === undefined ? undefined : minutes * run_progress.MS_PER_MINUTE
+	return minutes === undefined ? undefined : minutes * MS_PER_MINUTE
 }
 
 /**
@@ -88,7 +80,7 @@ function configured_interval_ms(directory: string = process.cwd()): number {
 }
 
 const run_progress_config = {
-	PACKAGE_FILE,
+	PACKAGE_FILE: PACKAGE_JSON,
 	configured_interval_ms,
 	read_package_minutes,
 	resolve_interval_ms,

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_progress_cli } from './run-progress-cli'
+
+// The `josh run:progress` entry, kept apart from `run-progress-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_progress_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -1,4 +1,5 @@
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
 // that decides when that is.
@@ -45,8 +46,6 @@ const DEFAULT_INTERVAL_MINUTES = 20
 // The one name for the setting, so the watcher and the guard read the same variable rather than two
 // spellings of it.
 const INTERVAL_KEY = 'JOSH_PROGRESS_INTERVAL_MINUTES'
-const MS_PER_MINUTE = 60_000
-const MS_PER_SECOND = 1000
 const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
 // The switch that silences every progress report — the watcher's and `run:board --every`'s alike.
 const DISABLED_KEY = 'JOSH_PROGRESS'
@@ -351,8 +350,6 @@ const run_progress = {
 	DISABLED_KEY,
 	DISABLED_VALUE,
 	INTERVAL_KEY,
-	MS_PER_MINUTE,
-	MS_PER_SECOND,
 	NO_CHILD_YET,
 	NO_NEXT,
 	format_child,