@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/propagate/propagate-targets.ts

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import type { RepoMap } from '#scripts/discovery/repo-map-logic'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
 // Deciding which repositories a published release should be carried into.
 //
-// The candidate set is joshuafolkken/kit#869's discovery map, so the owner restriction is inherited
+// The candidate set is the repository discovery map, so the owner restriction is inherited
 // rather than restated: propagation writes — `josh vu`, `josh sync`, a commit, a pull request — and
 // a write aimed at somebody else's repository is worse than a read aimed at one. Nothing here
 // re-implements discovery.
@@ -13,16 +14,15 @@ import { z } from 'zod'
 // Which candidates are targets is read from the candidate itself: a repository is downstream when
 // its manifest declares a dependency on this package. That is a fact about the checkout in front of
 // us rather than a roster, so a new consumer needs no edit here — and it covers a consumer that is
-// not a published package at all, which a list of downstream package names cannot
-// (joshuafolkken/kit#863).
+// not a published package at all, which a list of downstream package names cannot.
 
 const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
 // Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
-// after classification: a candidate `--target` left out (joshuafolkken/kit#2755). `carried_above` is
+// after classification: a candidate `--target` left out. `carried_above` is
 // the other: a consumer that installs a toolkit above the supplier, which that toolkit's own
-// propagation delivers instead (joshuafolkken/kit#2879).
+// propagation delivers instead.
 type TargetState =
 	| 'ready'
 	| 'up_to_date'
@@ -68,11 +68,7 @@ function read_manifest(repository_path: string): Manifest | undefined {
 	if (!existsSync(manifest_path)) return undefined
 
 	try {
-		const parsed: unknown = JSON.parse(readFileSync(manifest_path, 'utf8'))
-
-		const result = manifest_schema.safeParse(parsed)
-
-		return result.success ? result.data : undefined
+		return json_value.parse_with(readFileSync(manifest_path, 'utf8'), manifest_schema)
 	} catch {
 		return undefined
 	}

package/scripts/propagate/propagate.ts

@@ -15,7 +15,7 @@ import { propagate_steps, type ReleasePlan } from './propagate-steps'
 import { propagate_targets, type PropagateTarget } from './propagate-targets'
 
 // `josh propagate` — carry the release this repository just published into every consumer checked
-// out next to it (joshuafolkken/kit#863).
+// out next to it.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -32,7 +32,7 @@ const UNTOUCHED_NOTE = 'No consumer was touched.'
 interface RunOptions {
 	is_dry_run: boolean
 	is_publish_wait_skipped: boolean
-	// The one consumer to propagate to, when `--target` narrowed the run (joshuafolkken/kit#2755).
+	// The one consumer to propagate to, when `--target` narrowed the run.
 	target?: string
 	// The usage message, when the arguments were not accepted. Carried alongside rather than returned
 	// instead, so the caller has one shape to branch on.
@@ -87,11 +87,11 @@ function parse_options(argv: ReadonlyArray<string>): RunOptions {
 }
 
 // Propagation runs from the supplier's own repository, and only there — kit's, or a toolkit's built
-// on it (joshuafolkken/kit#2879).
+// on it.
 //
 // This is also what decides who propagates when several sessions are running: in the
 // per-repository concurrency model there is one session per checkout, so the session standing in
-// the supplier repository is the one that can run this command (joshuafolkken/kit#861). It is a
+// the supplier repository is the one that can run this command. It is a
 // convention enforced at the boundary, not a lock — two checkouts of the supplier would both pass,
 // which is why each consumer is additionally refused unless its working tree is clean.
 function refuse_outside_source_repository(project_root: string): string | undefined {
@@ -192,7 +192,7 @@ interface RunPlan {
 
 // The consumers this run will consider, narrowed by `--target`. Resolved before the publish wait so
 // a mistyped name fails at once instead of after minutes of polling the registry. A consumer that
-// installs a toolkit above the supplier is left to that toolkit's propagation (joshuafolkken/kit#2879).
+// installs a toolkit above the supplier is left to that toolkit's propagation.
 function resolve_run_targets(
 	releases: ReleasePlan,
 	version: string,

package/scripts/refactor/import-graph.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 import { file_reader } from '#scripts/lib/read-file'
 
-// The scope expansion `prompts/refactoring.md` §4.3 used to describe in prose (joshuafolkken/kit#2180):
+// The scope expansion `prompts/refactoring.md` §4.3 used to describe in prose:
 // from the seed files, follow imports both ways — the files a seed imports and the files that import a
 // seed — for up to three stages, stopping as soon as a stage finds nothing new. Walking the import
 // graph is exactly computable, so it is computed here rather than read and traced by hand.

package/scripts/refactor/refactor-lint.ts

@@ -1,10 +1,11 @@
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { json_value } from '#scripts/lib/json-value'
 import { LINT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { z } from 'zod'
 
-// The mechanical half of `prompts/refactoring.md` (joshuafolkken/kit#2255): the refactoring
+// The mechanical half of `prompts/refactoring.md`: the refactoring
 // priorities ESLint already decides. Rather than read the checklist and grep by hand, the project's
 // own eslint is asked in JSON and its findings are bucketed into the checklist's items.
 //
@@ -186,16 +187,9 @@ function eslint_command(root: string, files: ReadonlyArray<string>): ReadonlyArr
 }
 
 // `undefined` means the run did not produce parseable eslint JSON — a failure, kept distinct from a
-// valid empty array (a clean scope), so a scan that could not run is never reported as `clear`
-// (joshuafolkken/kit#2180).
+// valid empty array (a clean scope), so a scan that could not run is never reported as `clear`.
 function parse_results(raw: string | undefined = 'null'): Array<LintResult> | undefined {
-	try {
-		const parsed = results_schema.safeParse(JSON.parse(raw))
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, results_schema)
 }
 
 // The project's own eslint over the scope, in JSON. `reject: false` because eslint exits non-zero when

package/scripts/refactor/refactor-scan-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { refactor_scan } from './refactor-scan'
 
 // The `josh refactor:scan` entry point. It takes no arguments: the scope is the changed files, or
-// `scripts/` when nothing changed, decided the same way for every run (joshuafolkken/kit#2180).
+// `scripts/` when nothing changed, decided the same way for every run.
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await refactor_scan.run_scan()

package/scripts/refactor/refactor-scan.ts

@@ -5,7 +5,7 @@ import { refactor_lint, type CategoryResult } from './refactor-lint'
 import { refactor_targets } from './refactor-targets'
 
 // `josh refactor:scan` — the command `prompts/refactoring.md` §4.1–§4.3 now point to instead of
-// describing the search by hand (joshuafolkken/kit#2180). It selects the target files, expands the
+// describing the search by hand. It selects the target files, expands the
 // scope along the import graph, asks the project's own eslint which refactoring candidates the scope
 // holds, and answers whether any high- or medium-priority candidate remains.
 //
@@ -16,7 +16,7 @@ import { refactor_targets } from './refactor-targets'
 
 // The convergence vocabulary. `clear` is what §4.3's self-reported "no high- or medium-priority
 // candidate left" loop exit becomes once a command answers it: a token a caller can read, not a claim.
-// `error` is the third answer (joshuafolkken/kit#2180): the eslint run itself did not complete, so the
+// `error` is the third answer: the eslint run itself did not complete, so the
 // scope's state is unknown — kept distinct from `clear` so a failed scan is never read as converged.
 const CLEAR = 'clear'
 const CANDIDATES = 'candidates'

package/scripts/refactor/refactor-targets.ts

@@ -4,7 +4,7 @@ import { changed_paths } from '#scripts/git/changed-paths'
 import { line_targets } from '#scripts/lines/line-targets'
 
 // The target-file selection of `josh refactor:scan` — the priority `prompts/refactoring.md` §4.1
-// used to spell out in prose (joshuafolkken/kit#2180). The scope is the same reading every scoped
+// used to spell out in prose. The scope is the same reading every scoped
 // command decides from — the branch diff plus the untracked files (`changed-paths.ts`) — and only
 // when that is empty does it fall back to `scripts/`, so a run on a clean `main` still has something
 // to scan rather than reporting nothing.

package/scripts/release/github-release-cli.ts

@@ -1,8 +1,14 @@
 import { fileURLToPath } from 'node:url'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { github_release } from './github-release'
 import { github_release_environment } from './github-release-environment'
 
+const KNOWN_FLAGS: ReadonlyArray<string> = []
+const COMMAND_NAME = 'release:github'
+const ARGUMENT_START = 2
+const SUCCESS_EXIT_CODE = 0
+
 // A release published without the tag list would pick its previous tag from nothing, so a failed
 // `git tag` stops the run rather than reading as "no tags".
 function local_tags(): Array<string> {
@@ -12,13 +18,29 @@ function local_tags(): Array<string> {
 	return output.split('\n')
 }
 
-async function main(): Promise<void> {
+// **No argument reaches the publish**. The command reads only the
+// environment, so a `--help` it ignored would create a real GitHub Release; a help request prints
+// the usage and any other argument is refused, both before the environment is read.
+async function run_argv(argv: ReadonlyArray<string>): Promise<number> {
+	const answer = cli_flags.answer_help_or_unknown(
+		argv.slice(ARGUMENT_START),
+		KNOWN_FLAGS,
+		COMMAND_NAME,
+	)
+	if (answer !== undefined) return answer
+
 	const { token, tag, settings } = github_release_environment.read_release_input(process.env)
 
 	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags: local_tags() }))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run_argv(argv)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv)
 
-const github_release_cli = { local_tags }
+const github_release_cli = { local_tags, run_argv }
 export { github_release_cli }

package/scripts/release/github-release-environment.ts

@@ -38,6 +38,7 @@ function read_release_input(environment: Environment): ReleaseInput {
 			workflow: optional(environment['RELEASE_WORKFLOW']),
 			jobs: job_names(environment['RELEASE_JOBS']),
 			await_publish: environment['RELEASE_AWAIT_PUBLISH'] === 'true',
+			release_run_workflow: optional(environment['RELEASE_RUN_WORKFLOW']),
 		},
 	}
 }

package/scripts/release/github-release-runs.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+
+// A job skipped by its `if:` (or neutral) belongs to a run that succeeded; counting it would skip a
+// lower tag whose release is still on its way.
+const FAILED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure'])
+const RELEASE_RUN_TITLE = 'GitHub Release '
+const RUN_SCHEMA = z.object({
+	id: z.number(),
+	display_title: z.string(),
+	status: z.string().optional(),
+	conclusion: z.string().nullable().optional(),
+})
+const JOB_SCHEMA = z.object({
+	name: z.string(),
+	status: z.string(),
+	conclusion: z.string().nullable(),
+})
+const RUNS_SCHEMA = z.object({ workflow_runs: z.array(RUN_SCHEMA) })
+const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
+
+type Run = z.infer<typeof RUN_SCHEMA>
+type PollState = 'ready' | 'failed' | 'pending'
+
+// `read` answers a GET on a repository API path. `workflow` is the publish workflow and `jobs` the
+// jobs in it whose failure counts (empty: every job). `release_run_workflow` is the workflow that
+// creates a tag's release — the publish workflow itself when its run creates the release.
+interface RunSource {
+	read: (path: string) => Promise<unknown>
+	workflow: string | undefined
+	jobs: ReadonlyArray<string>
+	release_run_workflow: string | undefined
+}
+
+function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<string>): boolean {
+	if (job.status !== 'completed' || !FAILED_CONCLUSIONS.has(job.conclusion ?? '')) return false
+	if (names.length === 0) return true
+
+	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
+}
+
+async function list_runs(source: RunSource, workflow_name: string): Promise<ReadonlyArray<Run>> {
+	const workflow = encodeURIComponent(workflow_name)
+
+	return RUNS_SCHEMA.parse(await source.read(`/actions/workflows/${workflow}/runs?per_page=100`))
+		.workflow_runs
+}
+
+async function find_run(
+	source: RunSource,
+	workflow_name: string,
+	title: string,
+): Promise<Run | undefined> {
+	const runs = await list_runs(source, workflow_name)
+
+	return runs.find((item) => item.display_title === title)
+}
+
+async function has_failed_job(source: RunSource, run_id: number): Promise<boolean> {
+	const { jobs } = JOBS_SCHEMA.parse(
+		await source.read(`/actions/runs/${String(run_id)}/jobs?per_page=100`),
+	)
+
+	return jobs.some((job) => is_failed_job(job, source.jobs))
+}
+
+// A run started before its title named the tag may be at work on any tag.
+function may_release(run: Run, tag: string): boolean {
+	if (run.status === 'completed') return false
+
+	return (
+		run.display_title === `${RELEASE_RUN_TITLE}${tag}` ||
+		!run.display_title.startsWith(RELEASE_RUN_TITLE)
+	)
+}
+
+// Unset, nothing tells that a release is over, so the lower tag is waited for.
+async function is_release_over(source: RunSource, tag: string): Promise<boolean> {
+	const workflow = source.release_run_workflow
+	if (workflow === undefined) return false
+	if (workflow === source.workflow) return true
+
+	const runs = await list_runs(source, workflow)
+
+	return runs.every((run) => !may_release(run, tag))
+}
+
+// A lower tag whose publication failed, or finished while no release run is left at work on it,
+// never gains a release, so waiting on it would hold every later one.
+async function is_release_lost(source: RunSource, tag: string): Promise<boolean> {
+	if (source.workflow === undefined) return false
+
+	const run = await find_run(source, source.workflow, `Publish ${tag}`)
+	if (!run) return false
+	if (await has_failed_job(source, run.id)) return true
+
+	return run.status === 'completed' && (await is_release_over(source, tag))
+}
+
+// A run not listed yet is pending too: the announcement that starts this release also starts the
+// publication, so the release can ask before GitHub has queued that run.
+async function publication_state(
+	source: RunSource,
+	workflow: string,
+	tag: string,
+): Promise<PollState> {
+	const run = await find_run(source, workflow, `Publish ${tag}`)
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
+const github_release_runs = { is_release_lost, publication_state }
+
+export type { PollState, RunSource }
+export { github_release_runs }

package/scripts/release/github-release.ts

@@ -1,6 +1,7 @@
 import { setTimeout } from 'node:timers/promises'
 import semver from 'semver'
 import { z } from 'zod'
+import { github_release_runs, type PollState, type RunSource } from './github-release-runs'
 
 const API_ROOT = 'https://api.github.com/repos'
 const LATEST_PATH = '/releases/latest'
@@ -8,42 +9,26 @@ const REPOSITORY_PATTERN = /^[\w.-]+\/[\w.-]+$/u
 const TAG_PATTERN = /^v\d+\.\d+\.\d+(?:[.-][0-9A-Za-z.-]+)?$/u
 const REQUEST_TIMEOUT_MS = 30_000
 const NOT_FOUND_STATUS = 404
-// A job skipped by its `if:` (or neutral) belongs to a run that succeeded; counting it would skip a
-// lower tag whose release is still on its way.
-const FAILED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure'])
 const POLL_INTERVAL_MS = 30_000
 const MAX_WAIT_ATTEMPTS = 120
 const RELEASE_SCHEMA = z.object({ tag_name: z.string().min(1) })
 const NOTES_SCHEMA = z.object({ name: z.string().min(1), body: z.string().min(1) })
-const RUN_SCHEMA = z.object({
-	id: z.number(),
-	display_title: z.string(),
-	status: z.string().optional(),
-	conclusion: z.string().nullable().optional(),
-})
-const JOB_SCHEMA = z.object({
-	name: z.string(),
-	status: z.string(),
-	conclusion: z.string().nullable(),
-})
-const RUNS_SCHEMA = z.object({ workflow_runs: z.array(RUN_SCHEMA) })
-const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
-
 type ReleaseRequest = (url: string, init: RequestInit) => Promise<Response>
 type Wait = () => Promise<void>
-type PollState = 'ready' | 'failed' | 'pending'
 
 // What differs between repositories. `start_tag` is the last tag that predates automatic releases;
 // without it the latest existing release is the floor. `workflow` names the publish workflow whose
 // failed run lets a lower tag be skipped, and `jobs` the jobs in it that count (empty: every job).
 // `await_publish` holds the tag's own release until its run in that workflow has succeeded, for a
-// release started beside the publication rather than from inside it.
+// release started beside the publication rather than from inside it. `release_run_workflow` names
+// the workflow whose run creates a tag's release, so a lower tag left without one can be told lost.
 interface ReleaseSettings {
 	repository: string
 	start_tag?: string | undefined
 	workflow?: string | undefined
 	jobs?: ReadonlyArray<string> | undefined
 	await_publish?: boolean | undefined
+	release_run_workflow?: string | undefined
 }
 
 interface PublishOptions extends ReleaseSettings {
@@ -51,12 +36,10 @@ interface PublishOptions extends ReleaseSettings {
 	wait?: Wait
 }
 
-interface Client {
+interface Client extends Omit<RunSource, 'read'> {
 	request: ReleaseRequest
 	token: string
 	url: string
-	workflow: string | undefined
-	jobs: ReadonlyArray<string>
 }
 
 // `fallback` answers when no tag sits between the floor and the target; without one the floor itself
@@ -139,59 +122,21 @@ function predecessor(
 		.toSorted((left, right) => semver.compare(right, left))[0]
 }
 
-function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<string>): boolean {
-	if (job.status !== 'completed' || !FAILED_CONCLUSIONS.has(job.conclusion ?? '')) return false
-	if (names.length === 0) return true
-
-	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
-}
-
-async function publish_run(
-	client: Client,
-	workflow_name: string,
-	tag: string,
-): Promise<z.infer<typeof RUN_SCHEMA> | undefined> {
-	const workflow = encodeURIComponent(workflow_name)
-	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
-	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
-
-	return runs.find((item) => item.display_title === `Publish ${tag}`)
-}
-
-async function failed_publication(client: Client, tag: string): Promise<boolean> {
-	if (client.workflow === undefined) return false
-
-	const run = await publish_run(client, client.workflow, tag)
-	if (!run) return false
-
-	const jobs_response = await api_get(client, `/actions/runs/${String(run.id)}/jobs?per_page=100`)
-	const { jobs } = JOBS_SCHEMA.parse(await read_response(jobs_response))
-
-	return jobs.some((job) => is_failed_job(job, client.jobs))
+function run_source(client: Client): RunSource {
+	return { ...client, read: async (path) => await read_response(await api_get(client, path)) }
 }
 
 async function default_wait(): Promise<void> {
 	await setTimeout(POLL_INTERVAL_MS)
 }
 
+// The lost state is read before the release: a run completes only after creating the release, so a
+// run that completes between the two reads still shows its release to the second one.
 async function release_state(client: Client, tag: string): Promise<PollState> {
+	const is_lost = await github_release_runs.is_release_lost(run_source(client), tag)
 	if (await existing_release(client, tag)) return 'ready'
-	if (await failed_publication(client, tag)) return 'failed'
-
-	return 'pending'
-}
-
-// A run not listed yet is pending too: the announcement that starts this release also starts the
-// publication, so the release can ask before GitHub has queued that run.
-async function publication_state(
-	client: Client,
-	workflow: string,
-	tag: string,
-): Promise<PollState> {
-	const run = await publish_run(client, workflow, tag)
-	if (run?.status !== 'completed') return 'pending'
 
-	return run.conclusion === 'success' ? 'ready' : 'failed'
+	return is_lost ? 'failed' : 'pending'
 }
 
 async function poll(
@@ -225,7 +170,7 @@ async function wait_for_publication(client: Client, tag: string, budget: Budget)
 	if (workflow === undefined) throw new Error('Waiting for the publication needs RELEASE_WORKFLOW')
 
 	return await poll(
-		async () => await publication_state(client, workflow, tag),
+		async () => await github_release_runs.publication_state(run_source(client), workflow, tag),
 		budget,
 		`Publish ${tag}`,
 	)
@@ -325,6 +270,7 @@ function create_client(request: ReleaseRequest, token: string, settings: Release
 		url: `${API_ROOT}/${settings.repository}`,
 		workflow: settings.workflow,
 		jobs: settings.jobs ?? [],
+		release_run_workflow: settings.release_run_workflow,
 	}
 }
 

package/scripts/release/release-cli.ts

@@ -1,23 +1,26 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 import { release_history } from './release-history'
 import { release_plan, type ReleasePlan } from './release-plan'
 import { release_publish } from './release-publish'
 
-// `pnpm josh release` — the one place that decides a version (joshuafolkken/kit#1169).
+// `pnpm josh release` — the one place that decides a version.
 //
 // It does three things and no more: count the merges main has taken since the version last changed,
 // report and stop when that count is zero, and otherwise raise the version by that many minors, open
 // a pull request, merge it and watch for the tag.
 //
-// **It never touches the root checkout** (joshuafolkken/kit#2411). The count is read from
+// **It never touches the root checkout**. The count is read from
 // `origin/<default>`, and the version bump / commit / push happen in a dedicated work tree
 // `release_publish` cuts for the release — so a release can run beside a `backlogrun` (which keeps the
 // root on the default branch) and can start even when the root is dirty or on another branch.
 
 const DRY_RUN_FLAG = '--dry-run'
+const KNOWN_FLAGS: ReadonlyArray<string> = [DRY_RUN_FLAG]
+const COMMAND_NAME = 'release'
 const ARGUMENT_START = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -73,9 +76,23 @@ function is_dry_run_requested(argv: ReadonlyArray<string>): boolean {
 	return argv.slice(ARGUMENT_START).includes(DRY_RUN_FLAG)
 }
 
+// **Only a known argument reaches the release**. The command publishes,
+// so a `--help` it did not read once started a real release; a help request now prints the usage, and
+// anything else unknown is refused, both before the first fetch.
+async function run_argv(argv: ReadonlyArray<string>): Promise<number> {
+	const answer = cli_flags.answer_help_or_unknown(
+		argv.slice(ARGUMENT_START),
+		KNOWN_FLAGS,
+		COMMAND_NAME,
+	)
+	if (answer !== undefined) return answer
+
+	return await run(is_dry_run_requested(argv))
+}
+
 async function main(): Promise<void> {
 	try {
-		process.exit(await run(is_dry_run_requested(process.argv)))
+		process.exit(await run_argv(process.argv))
 	} catch (error) {
 		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
@@ -84,6 +101,6 @@ async function main(): Promise<void> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) void main()
 
-const release_cli = { is_dry_run_requested, run, DRY_RUN_FLAG }
+const release_cli = { is_dry_run_requested, run, run_argv, DRY_RUN_FLAG }
 
 export { release_cli }

package/scripts/release/release-history.ts

@@ -1,15 +1,16 @@
 import { git_command } from '#scripts/git/git-command'
+import { json_value } from '#scripts/lib/json-value'
 import { package_with_version_schema } from '#scripts/lib/schemas'
 import { version_targets } from '#scripts/version/version-targets'
 import { release_plan, type ReleasePlan, type VersionedCommit } from './release-plan'
 
 // Reading main's history for the two numbers a release is made of: where the version last changed,
-// and how many merges have landed since (joshuafolkken/kit#1169).
+// and how many merges have landed since.
 
 const { PACKAGE_JSON } = version_targets
 
 // How far back the search for "the commit that last changed the version" goes, counted in commits
-// that touched `package.json`. Once children stop bumping (joshuafolkken/kit#1486) that file still
+// that touched `package.json`. Once children stop bumping that file still
 // changes for every dependency update, so the base can sit several entries down — but a repository
 // that has taken thirty `package.json` commits without a single release has a different problem, and
 // guessing past that point would be worse than saying so.
@@ -18,8 +19,7 @@ const BASE_SEARCH_LIMIT = 30
 // **Which ref the history is read from.** `josh release` runs on a pulled default branch, so `HEAD`
 // is main there and the default is right. A caller on a feature branch names the ref it means —
 // `origin/main` — because `--first-parent` from a branch tip walks that branch rather than main, and
-// the count would silently omit every merge main took after the branch was cut
-// (joshuafolkken/kit#1486).
+// the count would silently omit every merge main took after the branch was cut.
 const DEFAULT_TIP = 'HEAD'
 
 // The reads this module makes, named so a test can answer them without a git repository. Production
@@ -42,11 +42,7 @@ const git_reader: HistoryReader = {
 function parse_version(content: string | undefined): string | undefined {
 	if (content === undefined) return undefined
 
-	try {
-		return package_with_version_schema.parse(JSON.parse(content)).version
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(content, package_with_version_schema)?.version
 }
 
 async function read_version_at(
@@ -90,7 +86,7 @@ async function read_base(
 
 // The version `package.json` carries at a git revision. `josh release` reads it from
 // `origin/<default>` rather than from the checkout's own `package.json`, so the number it raises is
-// main's latest even when the run happens in a work tree cut for the release (joshuafolkken/kit#2411).
+// main's latest even when the run happens in a work tree cut for the release.
 async function read_current_version(
 	tip: string = DEFAULT_TIP,
 	reader: HistoryReader = git_reader,

package/scripts/release/release-plan.ts

@@ -1,6 +1,6 @@
 import semver from 'semver'
 
-// What a release is, decided from main's history alone (joshuafolkken/kit#1169).
+// What a release is, decided from main's history alone.
 //
 // **A version is a property of main's history, not of a branch.** `bump-version.ts` reads the local
 // `package.json` and increments it, so two branches cut from the same version both claim the same
@@ -51,7 +51,7 @@ function previous_version_of(
 // **The newest commit whose `package.json` version differs from the version immediately before it.**
 //
 // **A commit that touched `package.json` without moving the version is skipped**, which is what makes
-// this right once children stop bumping (joshuafolkken/kit#1486): a dependency update rewrites the
+// this right once children stop bumping: a dependency update rewrites the
 // file every time and must not be mistaken for a release.
 //
 // **Both sides have to be readable for this to be a version change.** An unreadable neighbor makes
@@ -96,7 +96,7 @@ function short_sha(sha: string): string {
 
 // **The count is the line a person reads**, which is why it is built here rather than at each caller:
 // the release command prints it, and so does anything else that wants to say how much is waiting to
-// ship (joshuafolkken/kit#1169 → "the count of unreleased merges shows somewhere visible").
+// ship.
 function format_pending_line(pending: number): string {
 	return `${PENDING_ICON} unreleased merges on main: ${String(pending)}`
 }

package/scripts/release/release-progress.ts

@@ -9,13 +9,12 @@ import { version_targets } from '#scripts/version/version-targets'
 import { z } from 'zod'
 import { release_tag } from './release-tag'
 
-// The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag
-// (joshuafolkken/kit#3193).
+// The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag.
 //
 // **The tag starts the distribution, it does not finish it.** `publish.yml` runs off the tag:
 // `publish-npm` puts the version on npm and `create-release` opens the GitHub Release once the
-// publishing jobs pass. The command used to stop at the tag and call the release published, ahead of
-// both. It now waits for each, prints one line per stage reached, and prints the completion line only
+// publishing jobs pass. Stopping at the tag would call the release published ahead of both, so the
+// command waits for each, prints one line per stage reached, and prints the completion line only
 // when every stage has — a stage that times out is named with ❌ and the run exits non-zero.
 
 const { PACKAGE_JSON } = version_targets