@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/lane/lane-stop-stats.ts

@@ -0,0 +1,96 @@
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type LedgerEntry, type StopEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long a lane stood stopped: the ledger's `stop` entries of one period reduced to one row per stop
+// reason — median, maximum, how many stops were resumed and how many never were — printed by
+// `josh lane:stats` under the per-stage table, so the stop reason worth removing next is a number.
+//
+// **The wait is derived, not recorded**: from a stop to the start of the same issue's next ship stage,
+// the way `implement` is. A stop that no ship stage followed — the lane parked, or left stopped — is
+// counted under `not resumed` and kept out of the median and the maximum, whose time has no end.
+//
+// **A re-dispatch of the issue ends the search**: the new child's ship is a fresh lane's work, not the
+// resumption of a stop that may be days old.
+
+const COLUMNS = ['stop', 'median (min)', 'max (min)', 'runs', 'not resumed'] as const
+const { STAGE } = run_ship_stage
+const { is_dispatch, is_number, is_stage } = lane_stage_stats
+const REASONS = [
+	STAGE.PREFLIGHT,
+	STAGE.REVIEW,
+	STAGE.SYNC,
+	run_ship_stage.CONFLICT,
+	STAGE.GATE,
+	STAGE.COMMIT,
+	STAGE.ROUND_TWO,
+	STAGE.FOLLOWUP,
+	STAGE.REPORT,
+] as const
+
+interface StopWait {
+	reason: string
+	wait_ms: number | undefined
+}
+
+function is_stop(entry: LedgerEntry): entry is StopEntry {
+	return entry.kind === lane_ledger.KIND.STOP
+}
+
+function redispatch_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number {
+	const from_ms = Date.parse(stop.at)
+	const later = entries
+		.filter((entry) => is_dispatch(entry))
+		.filter((entry) => entry.issue === stop.issue)
+		.map((entry) => Date.parse(entry.at))
+		.filter((at) => at > from_ms)
+
+	return later.length === 0 ? Infinity : Math.min(...later)
+}
+
+function wait_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number | undefined {
+	const from_ms = Date.parse(stop.at)
+	const until_ms = redispatch_ms(stop, entries)
+	const starts = entries
+		.filter((entry) => is_stage(entry))
+		.filter((stage) => stage.issue === stop.issue)
+		.map((stage) => lane_stage_stats.started_ms(stage))
+		.filter((start) => start >= from_ms && start < until_ms)
+
+	return starts.length === 0 ? undefined : Math.min(...starts) - from_ms
+}
+
+function waits_of(entries: ReadonlyArray<LedgerEntry>): Array<StopWait> {
+	return entries
+		.filter(is_stop)
+		.map((stop) => ({ reason: stop.reason, wait_ms: wait_ms(stop, entries) }))
+}
+
+function reason_row(reason: string, waits: ReadonlyArray<StopWait>): string {
+	const of_reason = waits.filter((wait) => wait.reason === reason)
+	const resumed = of_reason.map((wait) => wait.wait_ms).filter((value) => is_number(value))
+
+	return lane_stats.to_row([
+		reason,
+		lane_stage_stats.cell(lane_stats.median(resumed)),
+		lane_stage_stats.cell(lane_stats.peak(resumed)),
+		String(resumed.length),
+		String(of_reason.length - resumed.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const waits = waits_of(lane_stats.in_window(entries, window))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...REASONS.map((reason) => reason_row(reason, waits)),
+	].join('\n')
+}
+
+const lane_stop_stats = { REASONS, table }
+
+export { lane_stop_stats }

package/scripts/lane/openai-lane-supervisor.ts

@@ -9,10 +9,10 @@ import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
+import { lane_session_broker } from './lane-session-broker'
 import { openai_lane_ship } from './openai-lane-ship'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
 import { openai_lane_supervisor_owner, type SupervisorOwner } from './openai-lane-supervisor-owner'
-import { openai_review_broker } from './openai-review-broker'
 
 const { claim, read_state, release, update } = openai_lane_supervisor_owner
 const CHILD_POLL_MS = 250
@@ -178,7 +178,7 @@ async function supervise(lane: LaneInfo, profile: AgentProfile, nonce: string):
 	try {
 		if (!(await openai_lane_supervisor_decision.is_approved(lane.directory, nonce))) return 0
 
-		return await openai_review_broker.with_server(
+		return await lane_session_broker.with_server(
 			lane,
 			async () => await run_claimed(lane, profile, owner),
 		)

package/scripts/lane/process-tools.ts

@@ -0,0 +1,31 @@
+import path from 'node:path'
+
+// One definition of "the process tools a lane reads are not installed".
+//
+// **`ps` and `pgrep` are a prerequisite, not an optional probe.** The owner check walks the caller's
+// ancestry with `ps`, and lane liveness and reaping match children with `pgrep`. A machine without
+// them (a slim Debian image ships no `procps`) used to read every probe as "nothing there": the
+// ancestry stopped at the caller, `run:step` answered `unknown`, and the parent stopped before its
+// first lane with no word of why. A missing tool is refused by name instead.
+
+// What Node reports when the executable to spawn does not exist.
+const NOT_FOUND_CODE = 'ENOENT'
+const PACKAGE_HINT =
+	'install the package that provides it (procps on Debian/Ubuntu: `apt-get install procps`)'
+
+function is_not_found(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === NOT_FOUND_CODE
+}
+
+function missing_notice(command: string): string {
+	return `\`${path.basename(command)}\` is not installed — kit's lane commands read processes with ps and pgrep; ${PACKAGE_HINT}`
+}
+
+/** Throw a named refusal when `error` says `command` could not be spawned because it does not exist. */
+function throw_if_missing(command: string, error: unknown): void {
+	if (is_not_found(error)) throw new Error(missing_notice(command), { cause: error })
+}
+
+const process_tools = { missing_notice, throw_if_missing }
+
+export { process_tools }

package/scripts/lib/buffered-process.ts

@@ -1,4 +1,6 @@
+import { existsSync } from 'node:fs'
 import { execa } from 'execa'
+import { pnpm_reach } from './pnpm-reach'
 import { SUITE_TIMEOUT_MS } from './timeouts'
 
 // One definition of "run a check, keep its output, never throw".
@@ -9,7 +11,7 @@ import { SUITE_TIMEOUT_MS } from './timeouts'
 // (so one failing check does not abort its siblings), and a bound on how long a child may hang.
 // They had the same code twice, which is how a fix to one of them missed the other.
 
-const PNPM = 'pnpm'
+const { PNPM } = pnpm_reach
 const FORCE_COLOR = '1'
 const FAIL_EXIT_CODE = 1
 
@@ -35,6 +37,38 @@ interface BufferedProcessOptions {
 	timeout_ms?: number
 }
 
+// What execa reports about a child that produced no exit code. Declared here because execa's own
+// result type does not carry `code` or `shortMessage` on the non-rejecting path, though both are
+// there at runtime whenever the child did not exit by itself.
+interface UnfinishedChild {
+	exitCode?: number | undefined
+	code?: string | undefined
+	shortMessage?: string | undefined
+}
+
+// A missing working directory is reported with the same code as a missing executable, so the code
+// alone would blame pnpm for a lane directory that was removed.
+function is_pnpm_missing(result: UnfinishedChild, cwd: string | undefined): boolean {
+	return pnpm_reach.is_not_found(result) && existsSync(cwd ?? process.cwd())
+}
+
+// Why a child has no exit code: it could not be started, it ran past its bound, or a signal ended
+// it. The child cannot say so itself — in the first case there is no child — and without this a
+// check that never ran reads as a check that failed with nothing to report.
+function unfinished_reason(result: UnfinishedChild, cwd: string | undefined): Array<string> {
+	if (result.exitCode !== undefined) return []
+	const reason = [result.shortMessage ?? '']
+	if (is_pnpm_missing(result, cwd)) reason.push(pnpm_reach.NOT_ON_PATH_NOTICE)
+
+	return reason
+}
+
+// The reason follows whatever the child wrote before it stopped: a timed-out suite's last lines
+// are the evidence, and the reason is what explains them.
+function collect_output(all: string, reason: ReadonlyArray<string>): string {
+	return [all, ...reason].filter((part) => part !== '').join('\n')
+}
+
 async function run_buffered_process(
 	command_args: ReadonlyArray<string>,
 	options: BufferedProcessOptions = {},
@@ -58,7 +92,7 @@ async function run_buffered_process(
 	})
 
 	return {
-		output: result.all,
+		output: collect_output(result.all, unfinished_reason(result, options.cwd)),
 		exit_code: result.exitCode,
 		elapsed_ms: performance.now() - started_at,
 	}

package/scripts/lib/pnpm-reach.ts

@@ -0,0 +1,27 @@
+// One definition of "pnpm is not reachable from this process", for every caller that starts pnpm.
+//
+// `josh` runs its checks as `pnpm josh <check>` children, so a `pnpm` missing from the PATH this
+// process sees fails every one of them before it starts. Nothing in the child's output can say so —
+// there is no child — and the two places that can tell the user (the spawn itself and `josh doctor`)
+// have to say the same thing.
+
+const PNPM = 'pnpm'
+// What Node reports when the executable to spawn is not on PATH.
+const NOT_FOUND_CODE = 'ENOENT'
+const PREREQUISITES_URL =
+	'https://github.com/joshuafolkken/kit/blob/main/docs/setup/prerequisites.md#2-install-pnpm-and-nodejs'
+const NOT_ON_PATH_NOTICE = [
+	'pnpm was not found on the PATH this process sees, so the command could not start.',
+	'A shell opened by an editor, an agent or a service can have a different PATH from your terminal.',
+	`Install pnpm or add its directory to that PATH: ${PREREQUISITES_URL}`,
+].join('\n')
+
+// Narrowed to the one field it reads: execa's declared result type does not carry `code` on the
+// non-rejecting path, though the value is there at runtime whenever the spawn itself failed.
+function is_not_found(result: { code?: string | undefined }): boolean {
+	return result.code === NOT_FOUND_CODE
+}
+
+const pnpm_reach = { PNPM, NOT_ON_PATH_NOTICE, is_not_found }
+
+export { pnpm_reach }

package/scripts/lib/status-icons.ts

@@ -15,10 +15,14 @@
 // `✔ verification gate passed` line to tell a green gate from the third-party warning bodies it
 // forwards, so the pass icon is under the same rule as the failure icon: declared
 // once, imported by the printer and the reader alike.
+//
+// **The warning icon is read as well.** It opens the gate's `not verified` verdict — a gate that ran no
+// check — which `josh-verdict.ts` reads back, so it is declared here for the reason the other two are.
 
 const FAIL_ICON = '✗'
 const PASS_ICON = '✔'
+const WARN_ICON = '⚠'
 
-const status_icons = { FAIL_ICON, PASS_ICON }
+const status_icons = { FAIL_ICON, PASS_ICON, WARN_ICON }
 
 export { status_icons }

package/scripts/lint/lint-parallel.ts

@@ -8,6 +8,7 @@ import {
 	FAIL_EXIT_CODE,
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
+import { SKIP_MARKER } from '#scripts/test/skip-marker'
 import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
 const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
@@ -67,6 +68,22 @@ async function run_checked_eslint(
 	return await run_eslint(eslint)
 }
 
+function is_silent_pass(result: BufferedProcessResult): boolean {
+	return result.output === '' && !buffered_process.is_process_failed(result)
+}
+
+// Only beside a skipped sibling (`project_checks.ran_notice`): a `lint` that skipped nothing keeps the
+// output it always had.
+function with_ran_notice(
+	check: string,
+	result: BufferedProcessResult,
+	sibling: BufferedProcessResult,
+): BufferedProcessResult {
+	if (!sibling.output.includes(SKIP_MARKER) || !is_silent_pass(result)) return result
+
+	return { ...result, output: `${project_checks.ran_notice(check)}\n` }
+}
+
 function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcessResult): number {
 	return buffered_process.is_process_failed(prettier) || buffered_process.is_process_failed(eslint)
 		? FAIL_EXIT_CODE
@@ -94,8 +111,8 @@ async function run_lint_checks(
 		run_checked_eslint(directory, { args: eslint_args, recheck }),
 	])
 
-	write_output(prettier)
-	write_output(eslint)
+	write_output(with_ran_notice('prettier', prettier, eslint))
+	write_output(with_ran_notice('eslint', eslint, prettier))
 
 	return lint_exit_code(prettier, eslint)
 }

package/scripts/observations/observation-ledger-home.ts

@@ -119,6 +119,7 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 
 const observation_ledger_home = {
 	append,
+	file_path,
 	issue_path,
 	ledger_date,
 	ledger_root,

package/scripts/observations/observation-ledger-migrate.ts

@@ -8,6 +8,7 @@ import {
 	rmSync,
 } from 'node:fs'
 import path from 'node:path'
+import { process_identity } from '#scripts/josh/process-identity'
 import { file_reader } from '#scripts/lib/read-file'
 import {
 	LEDGER_FILE_EXTENSION,
@@ -38,8 +39,6 @@ import { observation_ledger_line } from './observation-ledger-line'
 // migration with no await point cannot be interleaved with another write in the same process.
 
 const NEWLINE = '\n'
-const NO_SIGNAL = 0
-const NO_SUCH_PROCESS = 'ESRCH'
 
 function claim_path(legacy: string): string {
 	return `${legacy}.${String(process.pid)}${MIGRATION_CLAIM_SUFFIX}`
@@ -55,18 +54,6 @@ function claim(from: string, to: string): boolean {
 	}
 }
 
-// Only `ESRCH` means the process is gone; `EPERM` means it runs under another user, and its claim is
-// still its own.
-function is_alive(pid: number): boolean {
-	try {
-		process.kill(pid, NO_SIGNAL)
-
-		return true
-	} catch (error) {
-		return (error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS
-	}
-}
-
 // A claim is named `<old ledger>.<pid>.migrating`, so the pid is what sits between the two.
 function is_stale_claim(name: string, legacy_name: string): boolean {
 	const prefix = `${legacy_name}.`
@@ -75,7 +62,8 @@ function is_stale_claim(name: string, legacy_name: string): boolean {
 
 	const pid = Number(name.slice(prefix.length, -MIGRATION_CLAIM_SUFFIX.length))
 
-	return Number.isSafeInteger(pid) && !is_alive(pid)
+	// A process under another user still holds its claim (`process_identity.is_present_pid`).
+	return Number.isSafeInteger(pid) && !process_identity.is_present_pid(pid)
 }
 
 function stale_claims(legacy: string): ReadonlyArray<string> {

package/scripts/release/release-issue-close.ts

@@ -0,0 +1,133 @@
+import { epic_issue } from '#scripts/epic/epic-issue'
+import { epic_parse } from '#scripts/epic/epic-parse'
+import type { IssueReference } from '#scripts/epic/epic-reference'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { epic_child_schema } from '#scripts/git/git-schemas'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_release_cli } from '#scripts/issue/issue-release-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+
+// Closes the repository's open release Issue once `pnpm josh release` has published
+// (joshuafolkken/kit#3825). Its body promises that, and an Issue waiting on the release reopens only
+// once it closes; left open, it keeps naming published work as unreleased.
+//
+// **Nothing here throws or changes the release's exit code.** The version is already out by the time
+// this runs, so a close that fails is reported for a person to finish rather than read as a failed
+// release.
+
+function published_comment(version: string): string {
+	return `Published in \`v${version}\` by \`pnpm josh release\`.`
+}
+
+// Resolved through `epic_issue.blocker_references_of`, so a blocker in another repository keeps that
+// repository instead of reading as the same number here.
+function open_references_of(
+	json: string | undefined,
+	repo: string,
+): Array<IssueReference> | undefined {
+	if (json === undefined) return undefined
+	const parsed = parse_json_object_or_undefined(json, epic_child_schema)
+
+	if (parsed === undefined) return undefined
+
+	return epic_issue
+		.blocker_references_of(parsed, repo)
+		.filter((reference) => !epic_parse.is_state_closed(reference.state))
+}
+
+// The blockers still open at publish have not merged, so this release did not carry them.
+// `undefined` when the relations are unreadable: closing then could strand a blocker on a closed
+// release Issue that no open one tracks.
+async function open_blockers_of(
+	repo: string,
+	issue_number: number,
+): Promise<Array<IssueReference> | undefined> {
+	const json = await git_gh_command.issue_get_state_and_relations(String(issue_number))
+
+	try {
+		return open_references_of(json, repo)
+	} catch {
+		return undefined
+	}
+}
+
+// A release Issue tracks only its own repository's changes, so a blocker elsewhere is named for a
+// person to carry rather than linked under a number that means a different Issue here.
+function warn_foreign(repo: string, foreign: ReadonlyArray<IssueReference>): void {
+	for (const reference of foreign) {
+		const cite = session_cite.issue(reference.number, undefined, reference.repo)
+
+		console.warn(`⚠ ${cite} is not in ${repo}, so it was not carried — carry it by hand`)
+	}
+}
+
+// Each unmerged blocker joins the next release Issue — the first link files it, the rest find it
+// open — so an open release Issue still names every change no release has published.
+async function carry_forward(repo: string, blockers: ReadonlyArray<IssueReference>): Promise<void> {
+	const own = blockers.filter((blocker) => blocker.repo === repo)
+
+	warn_foreign(
+		repo,
+		blockers.filter((blocker) => blocker.repo !== repo),
+	)
+
+	for (const blocker of own) {
+		// eslint-disable-next-line no-await-in-loop -- the first link files the Issue the rest join
+		await issue_release_cli.link(blocker.number, repo)
+	}
+}
+
+async function close_and_carry(
+	repo: string,
+	issue_number: number,
+	version: string,
+	blockers: ReadonlyArray<IssueReference>,
+): Promise<void> {
+	const cite = `release Issue ${session_cite.issue(issue_number, undefined, repo)}`
+	const is_closed = await git_gh_command.issue_close(
+		String(issue_number),
+		published_comment(version),
+	)
+
+	if (!is_closed) {
+		console.warn(`⚠ ${cite} could not be closed — close it by hand`)
+
+		return
+	}
+
+	console.info(`${cite} closed (v${version})`)
+	await carry_forward(repo, blockers)
+}
+
+async function close_issue(repo: string, issue_number: number, version: string): Promise<void> {
+	const blockers = await open_blockers_of(repo, issue_number)
+
+	if (blockers === undefined) {
+		const cite = session_cite.issue(issue_number, undefined, repo)
+
+		console.warn(`⚠ the blockers of release Issue ${cite} could not be read, so it was left open`)
+
+		return
+	}
+
+	await close_and_carry(repo, issue_number, version, blockers)
+}
+
+async function close_published(version: string): Promise<void> {
+	const repo = await git_gh_command.repo_get_name_with_owner()
+
+	if (repo === undefined) {
+		console.warn('⚠ the repository is unreadable, so its release Issue was left open')
+
+		return
+	}
+
+	const open = await issue_release_cli.find_open(repo)
+
+	if (open === undefined) console.warn(`⚠ the release Issues of ${repo} could not be listed`)
+	else if (typeof open === 'number') await close_issue(repo, open, version)
+}
+
+const release_issue_close = { close_published }
+
+export { release_issue_close }

package/scripts/release/release-publish.ts

@@ -5,6 +5,7 @@ import { git_remote_branch } from '#scripts/git/git-remote-branch'
 import { repository_lock } from '#scripts/git/repository-lock'
 import { write_version } from '#scripts/version/bump-version'
 import { version_targets } from '#scripts/version/version-targets'
+import { release_issue_close } from './release-issue-close'
 import type { ReleasePlan } from './release-plan'
 import { release_progress } from './release-progress'
 import { release_tag } from './release-tag'
@@ -121,6 +122,14 @@ async function commit_release(plan: ReleasePlan): Promise<string> {
 	return pr_url
 }
 
+// The release Issue is closed only once the distribution answered success — a failed watch leaves it
+// open, still naming the work as unreleased (joshuafolkken/kit#3825).
+async function close_when_published(version: string, exit_code: number): Promise<number> {
+	if (exit_code === SUCCESS_EXIT_CODE) await release_issue_close.close_published(version)
+
+	return exit_code
+}
+
 // No tag means nothing downstream ran, so the npm and GitHub Release watches are not started.
 async function merge_and_tag(
 	plan: ReleasePlan,
@@ -136,7 +145,9 @@ async function merge_and_tag(
 	console.info(release_tag.format_result(plan.next_version, is_tagged))
 	if (!is_tagged) return FAILURE_EXIT_CODE
 
-	return await release_progress.wait_for_distribution(plan.next_version)
+	const exit_code = await release_progress.wait_for_distribution(plan.next_version)
+
+	return await close_when_published(plan.next_version, exit_code)
 }
 
 // The whole release happens inside a work tree cut for it, so the root checkout is never touched: the

package/scripts/repo/repository-labels.ts

@@ -86,6 +86,16 @@ function ensure_labels(repo: string | undefined): ReadonlyArray<string> {
 	return create_missing(missing_labels(existing), repo)
 }
 
-const repository_labels = { ensure_labels }
+// The label names `ensure_labels` would create, read without creating any — every one when the
+// repository does not exist yet (`josh start --dry-run`). Undefined when the listing cannot be read,
+// so an unread repository is not reported as one with no labels.
+function planned_labels(repo: string | undefined): ReadonlyArray<string> | undefined {
+	if (repo === undefined) return label_names(REPOSITORY_LABELS)
+	const existing = read_existing(repo)
+
+	return existing === undefined ? undefined : label_names(missing_labels(existing))
+}
+
+const repository_labels = { ensure_labels, planned_labels }
 
 export { repository_labels }