@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/init/init.ts

@@ -23,7 +23,9 @@ import { init_file_action } from './init-file-action'
 import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
+import { kit_development_versions } from './kit-development-versions'
 import { kit_setup_state } from './kit-setup-state'
+import { package_manager_pin } from './package-manager-pin'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
 const PACKAGE_JSON = 'package.json'
@@ -51,7 +53,10 @@ function resolve_kit_package_manager(manifest: unknown): string | undefined {
 }
 
 function get_kit_package_manager(): string | undefined {
-	return resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON))
+	return package_manager_pin.choose(
+		resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON)),
+		process.env['npm_config_user_agent'],
+	)
 }
 
 function get_kit_development_engines(): Record<string, unknown> {
@@ -81,21 +86,10 @@ function tool_dependency_names(has_git: boolean): ReadonlyArray<string> {
 
 // Versions mirror kit's own devDependencies, so the consumer runs the toolchain kit is verified with.
 function get_toolchain_development_dependencies(has_git: boolean): Record<string, string> {
-	const manifest = z
-		.object({
-			peerDependencies: z.record(z.string(), z.string()),
-			devDependencies: z.record(z.string(), z.string()),
-		})
-		.parse(init_actions.read_package_json(PACKAGE_JSON))
-	const names = [...Object.keys(manifest.peerDependencies), ...tool_dependency_names(has_git)]
-	const entries = names.map((name): [string, string] => {
-		const version = manifest.devDependencies[name]
-		if (version === undefined) throw new Error(`Missing development version for ${name}`)
-
-		return [name, version]
-	})
-
-	return Object.fromEntries(entries)
+	return kit_development_versions.versions_of([
+		...kit_development_versions.peer_names(),
+		...tool_dependency_names(has_git),
+	])
 }
 
 function apply_dependency_merges(content: string, has_git = true): string {

package/scripts/init/initial-commit.ts

@@ -6,17 +6,17 @@ import { start_exec } from './start-exec'
 const DEFAULT_BRANCH = 'main'
 
 function create_repository(root: string): void {
-	start_exec.run('git', ['init', `--initial-branch=${DEFAULT_BRANCH}`], root)
+	start_exec.git_run(['init', `--initial-branch=${DEFAULT_BRANCH}`], root)
 }
 
 function commit_all(root: string): void {
-	start_exec.run('git', ['add', '--all'], root)
+	start_exec.git_run(['add', '--all'], root)
 	// The first commit of a new repository has no branch to come from, so the hook that keeps commits
 	// off main — installed by the initialize step in a full project — would refuse the only commit
 	// that has to land there.
-	start_exec.run('git', ['commit', '--no-verify', '--message', 'Initial commit'], root)
+	start_exec.git_run(['commit', '--no-verify', '--message', 'Initial commit'], root)
 	// A repository created by an older `git init` may name its unborn branch `master`.
-	start_exec.run('git', ['branch', '--move', '--force', DEFAULT_BRANCH], root)
+	start_exec.git_run(['branch', '--move', '--force', DEFAULT_BRANCH], root)
 }
 
 const initial_commit = { create_repository, commit_all }

package/scripts/init/kit-development-versions.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { z } from 'zod'
+import { package_path } from './init-paths'
+
+const PACKAGE_JSON = 'package.json'
+
+const kit_manifest_schema = z.object({
+	peerDependencies: z.record(z.string(), z.string()).default({}),
+	devDependencies: z.record(z.string(), z.string()),
+})
+
+type KitManifest = z.infer<typeof kit_manifest_schema>
+
+function read_kit_manifest(): KitManifest {
+	const content = readFileSync(package_path(PACKAGE_JSON), 'utf8')
+
+	return kit_manifest_schema.parse(JSON.parse(content))
+}
+
+// The version kit's own devDependencies carry for each name, so a consumer runs the toolchain kit
+// is verified with rather than a copy of it that drifts.
+function versions_of(names: ReadonlyArray<string>): Record<string, string> {
+	const { devDependencies: versions } = read_kit_manifest()
+	const entries = names.map((name): [string, string] => {
+		const version = versions[name]
+		if (version === undefined) throw new Error(`Missing development version for ${name}`)
+
+		return [name, version]
+	})
+
+	return Object.fromEntries(entries)
+}
+
+function peer_names(): ReadonlyArray<string> {
+	return Object.keys(read_kit_manifest().peerDependencies)
+}
+
+const kit_development_versions = { peer_names, versions_of }
+
+export { kit_development_versions }

package/scripts/init/kit-setup-state.ts

@@ -8,13 +8,13 @@ const START_HINT =
 // reached the branch, so `josh start` has no setup pull request to open (joshuafolkken/kit#2816).
 function is_kit_committed(root: string): boolean {
 	// `./` resolves the path from `root` rather than from the repository's top level.
-	const manifest = start_exec.read_output('git', ['show', 'HEAD:./package.json'], root)
+	const manifest = start_exec.git_read(['show', 'HEAD:./package.json'], root)
 
 	return manifest?.includes(`"${KIT_PACKAGE_NAME}"`) ?? false
 }
 
 function is_git_work_tree(root: string): boolean {
-	return start_exec.succeeds('git', ['rev-parse', '--is-inside-work-tree'], root)
+	return start_exec.git_succeeds(['rev-parse', '--is-inside-work-tree'], root)
 }
 
 // The line `josh init` ends with in a Git repository whose checkout does not hold kit yet: the setup is

package/scripts/init/package-manager-pin.ts

@@ -0,0 +1,35 @@
+import { package_manager_version } from '#scripts/version/package-manager-version'
+import semver from 'semver'
+
+// pnpm sets `npm_config_user_agent` to `pnpm/<version> npm/? node/<version> <platform> <arch>` for
+// every script and `pnpm exec` it runs, so the pnpm that invoked `josh init` is readable from it.
+const PNPM_USER_AGENT_REGEX = /^pnpm\/(\S+)/u
+
+function running_pnpm_version(user_agent = ''): string | undefined {
+	const version = PNPM_USER_AGENT_REGEX.exec(user_agent)?.[1]
+
+	return version === undefined ? undefined : (semver.valid(version) ?? undefined)
+}
+
+function is_older_than(kit_pin: string, version: string): boolean {
+	const kit_version = semver.valid(package_manager_version.extract_pnpm_pin(kit_pin) ?? '')
+
+	return kit_version !== null && semver.lt(kit_version, version)
+}
+
+// Never pin a project below the pnpm installing it: the lockfile that pnpm just wrote can name a
+// version an older pnpm fails to resolve, so `pnpm install` under kit's older pin breaks the
+// first `josh init` (joshuafolkken/kit#3367). The kit pin keeps its integrity suffix when it wins.
+function choose(kit_pin: string | undefined, user_agent: string | undefined): string | undefined {
+	const running = running_pnpm_version(user_agent)
+	if (kit_pin === undefined || running === undefined) return kit_pin
+
+	return is_older_than(kit_pin, running) ? `pnpm@${running}` : kit_pin
+}
+
+const package_manager_pin = {
+	running_pnpm_version,
+	choose,
+}
+
+export { package_manager_pin }

package/scripts/init/start-exec.ts

@@ -1,39 +1,80 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { COMMAND_TIMEOUT_MS, SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
+import type { Visibility } from './start-plan'
 
-// The three spawn shapes every `josh start` step uses, shared by `start-steps.ts`, the setup pull
-// request step and the `josh init` hint so none of them keeps a copy of its own.
+// The spawn shapes every `josh start` step uses, shared by `start-steps.ts`, the setup pull request
+// step and the `josh init` hint so none of them keeps a copy of its own.
 //
-// The three git-driving shapes below act on `root`, so `cwd` has to mean it: an inherited `GIT_DIR` and friends beat `cwd`
+// The git shapes below act on `root`, so `cwd` has to mean it: an inherited `GIT_DIR` and friends beat `cwd`
 // and would carry a `git init` or commit into whichever repository a calling hook was firing in
 // (joshuafolkken/kit#3151).
+//
+// **Every git and gh call here is bounded** (joshuafolkken/kit#3262). A read asks the local
+// repository and takes git's own budget. A write — and `gh repo create --push` — can fire the
+// project's own commit and push hooks, which may run its whole suite, so it takes the suite budget:
+// long enough for that, short enough that a push that never answers ends the run.
+const SUCCESS_EXIT_CODE = 0
+
 function root_environment(): Record<string, string | undefined> {
 	return git_location_environment.location_free_environment()
 }
 
-function succeeds(command: string, args: ReadonlyArray<string>, root: string): boolean {
-	return (
-		execaSync(command, args, { cwd: root, env: root_environment(), reject: false }).exitCode === 0
-	)
+function git_succeeds(args: ReadonlyArray<string>, root: string): boolean {
+	return git_spawn_sync.run(args, { cwd: root, env: root_environment() }).exit_code === 0
 }
 
-function read_output(
-	command: string,
-	args: ReadonlyArray<string>,
-	root: string,
-): string | undefined {
-	const result = execaSync(command, args, { cwd: root, env: root_environment(), reject: false })
+function git_read(args: ReadonlyArray<string>, root: string): string | undefined {
+	return git_spawn_sync.read(args, { cwd: root, env: root_environment() })
+}
+
+function git_run(args: ReadonlyArray<string>, root: string): void {
+	const options = { cwd: root, env: root_environment(), timeout: SUITE_TIMEOUT_MS }
+	const { exit_code } = git_spawn_sync.run(args, { ...options, stdio: 'inherit' })
+
+	if (exit_code === SUCCESS_EXIT_CODE) return
 
-	return result.exitCode === 0 ? result.stdout.trim() : undefined
+	const outcome = exit_code === undefined ? 'did not finish' : `exited with ${String(exit_code)}`
+
+	throw new Error(`git ${args.join(' ')} ${outcome}`)
+}
+
+// Every gh spawn here dials GitHub directly, past a scanner's loopback proxy, the same as every
+// other `gh` spawn under scripts/ (joshuafolkken/kit#2436). Each argument list is written inline so
+// `gh-subcommand-guard.ts` reads its subcommand rather than `<dynamic>`.
+interface GhProbeOptions {
+	cwd: string
+	env: Record<string, string | undefined>
+	timeout: number
+	reject: false
 }
 
-// Every step spawned here dials GitHub directly, past a scanner's loopback proxy, the same as every
-// other `gh` spawn under scripts/ (joshuafolkken/kit#2436); a local `git` step is unaffected by it.
-function run(command: string, args: ReadonlyArray<string>, root: string): void {
+function gh_probe_options(root: string): GhProbeOptions {
 	const environment = { ...root_environment(), ...git_gh_exec.direct_environment().env }
 
-	execaSync(command, args, { env: environment, cwd: root, stdio: 'inherit' })
+	return { cwd: root, env: environment, timeout: COMMAND_TIMEOUT_MS, reject: false }
+}
+
+function is_gh_installed(root: string): boolean {
+	const result = execaSync('gh', ['--version'], gh_probe_options(root)) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+	return result.exitCode === SUCCESS_EXIT_CODE
+}
+
+function is_gh_signed_in(root: string): boolean {
+	const result = execaSync('gh', ['auth', 'status'], gh_probe_options(root)) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+	return result.exitCode === SUCCESS_EXIT_CODE
+}
+
+function create_github_repository(name: string, visibility: Visibility, root: string): void {
+	const source = ['--source', '.', '--remote', 'origin', '--push']
+	const { env } = gh_probe_options(root)
+	const options = { cwd: root, env, timeout: SUITE_TIMEOUT_MS, stdio: 'inherit' } as const
+
+	execaSync('gh', ['repo', 'create', name, `--${visibility}`, ...source], options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
 }
 
 // A caller's own initialize command stands in for the in-process `josh init`, so it keeps the
@@ -42,6 +83,14 @@ function run_local(command: string, args: ReadonlyArray<string>, root: string):
 	execaSync(command, args, { cwd: root, stdio: 'inherit' })
 }
 
-const start_exec = { succeeds, read_output, run, run_local }
+const start_exec = {
+	git_succeeds,
+	git_read,
+	git_run,
+	is_gh_installed,
+	is_gh_signed_in,
+	create_github_repository,
+	run_local,
+}
 
 export { start_exec }

package/scripts/init/start-setup-pr.ts

@@ -22,12 +22,12 @@ const FIRST_SETUP_ISSUE_FILTER = `[.[] | select(.title == "${SETUP_TITLE}") | .n
 
 // Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
 // command wrote need not be ASCII the way kit's own are (#2872).
-function paths_of(output: string | undefined): Array<string> {
-	return (output ?? '').split('\0').filter((listed) => listed.length > 0)
+function paths_of(output: string | undefined = ''): Array<string> {
+	return output.split('\0').filter((listed) => listed.length > 0)
 }
 
 function listing(args: ReadonlyArray<string>, root: string): Array<string> {
-	return paths_of(start_exec.read_output('git', [...args, '-z'], root))
+	return paths_of(start_exec.git_read([...args, '-z'], root))
 }
 
 function setup_issue(issue_number: string): IssueInfo {
@@ -103,13 +103,13 @@ function switch_to(branch: string, current: string | undefined, root: string): v
 
 	const reference = `refs/heads/${branch}`
 
-	if (start_exec.succeeds('git', ['rev-parse', '--verify', '--quiet', reference], root)) {
+	if (start_exec.git_succeeds(['rev-parse', '--verify', '--quiet', reference], root)) {
 		throw new Error(
 			`The setup branch ${branch} already exists. Run git switch ${branch}, then josh start again.`,
 		)
 	}
 
-	start_exec.run('git', ['switch', '--create', branch], root)
+	start_exec.git_run(['switch', '--create', branch], root)
 }
 
 // The paths are named on the commit as well as on the add, so anything the user had staged before
@@ -117,8 +117,8 @@ function switch_to(branch: string, current: string | undefined, root: string): v
 function commit_kit_paths(paths: ReadonlyArray<string>, issue: IssueInfo, root: string): void {
 	if (paths.length === 0) return
 
-	start_exec.run('git', ['add', '--', ...paths], root)
-	start_exec.run('git', ['commit', '--message', issue.commit_message, '--', ...paths], root)
+	start_exec.git_run(['add', '--', ...paths], root)
+	start_exec.git_run(['commit', '--message', issue.commit_message, '--', ...paths], root)
 }
 
 // A caller's initialize command writes files kit cannot name, so with a `baseline` — what was already
@@ -143,7 +143,7 @@ function setup_paths(
 // Issue → branch → only the setup's files committed → push → pull request. The merge is left to a
 // person: it is the one step that changes main.
 async function open(root: string, baseline?: ReadonlyArray<string>): Promise<void> {
-	const current = start_exec.read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
+	const current = start_exec.git_read(['symbolic-ref', '--short', 'HEAD'], root)
 	const paths = setup_paths(root, baseline, current)
 
 	if (paths.length === 0) {
@@ -156,7 +156,7 @@ async function open(root: string, baseline?: ReadonlyArray<string>): Promise<voi
 
 	switch_to(issue.branch_name, current, root)
 	commit_kit_paths(paths, issue, root)
-	start_exec.run('git', ['push', '--set-upstream', 'origin', issue.branch_name], root)
+	start_exec.git_run(['push', '--set-upstream', 'origin', issue.branch_name], root)
 	await git_pr.create_with_issue_info(issue)
 }
 

package/scripts/init/start-steps.ts

@@ -29,7 +29,7 @@ const GH_INSTALL_HINT =
 const GH_AUTH_HINT =
 	'GitHub CLI is not signed in. Run gh auth login, then run josh start again. Nothing was changed.'
 
-const { succeeds, read_output, run, run_local } = start_exec
+const { git_succeeds, git_read, run_local } = start_exec
 
 function read_git_state(root: string, shape: ProjectShape): GitState {
 	const { has_git, has_github } = shape
@@ -46,8 +46,8 @@ function read_git_state(root: string, shape: ProjectShape): GitState {
 	}
 
 	const has_origin = git_spawn_sync.origin_url(root) !== undefined
-	const branch = read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
-	const has_commits = succeeds('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], root)
+	const branch = git_read(['symbolic-ref', '--short', 'HEAD'], root)
+	const has_commits = git_succeeds(['rev-parse', '--verify', '--quiet', 'HEAD'], root)
 	const has_kit_committed = kit_setup_state.is_kit_committed(root)
 
 	return { has_git, has_github, has_origin, branch, has_commits, has_kit_committed }
@@ -56,8 +56,8 @@ function read_git_state(root: string, shape: ProjectShape): GitState {
 // Every step talks to GitHub, so the CLI is checked before the first write rather than at the step
 // that needs it — a missing `gh` then leaves the directory exactly as it was.
 function github_cli_refusal(root: string): string | undefined {
-	if (!succeeds('gh', ['--version'], root)) return GH_INSTALL_HINT
-	if (!succeeds('gh', ['auth', 'status'], root)) return GH_AUTH_HINT
+	if (!start_exec.is_gh_installed(root)) return GH_INSTALL_HINT
+	if (!start_exec.is_gh_signed_in(root)) return GH_AUTH_HINT
 
 	return undefined
 }
@@ -94,11 +94,7 @@ function commit_all(context: StepContext): void {
 }
 
 function create_github_repository(context: StepContext): void {
-	const name = path.basename(context.root)
-	const visibility = `--${context.visibility}`
-	const source = ['--source', '.', '--remote', 'origin', '--push']
-
-	run('gh', ['repo', 'create', name, visibility, ...source], context.root)
+	start_exec.create_github_repository(path.basename(context.root), context.visibility, context.root)
 }
 
 // The repository was created by the step before, so `gh` resolves the placeholder from the

package/scripts/issue/defect-rate-cli.ts

@@ -2,8 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { parse_json } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { z } from 'zod'

package/scripts/issue/git-next-issues.ts

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { parse_json_array_safe } from '#scripts/git/parse-json-array'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
 import { issue_rank, type DependencyRow } from './issue-rank'
 

package/scripts/issue/issue-auto-ok.ts

@@ -1,8 +1,8 @@
 import { git_branch } from '#scripts/git/git-branch'
 import { git_command } from '#scripts/git/git-command'
-import { run_carry } from '#scripts/run/run-carry'
+import { run_carry } from '#scripts/run/carry/run-carry'
 import { issue_file } from './issue-file'
-import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+import { AUTO_OK_LABEL, has_label_name, RELEASE_LABEL } from './issue-labels'
 import { issue_state_cli } from './issue-state-cli'
 
 // Whether `josh issue:file` applies `auto-ok` to the Issue it files (joshuafolkken/kit#3213). Work
@@ -12,9 +12,13 @@ import { issue_state_cli } from './issue-state-cli'
 // default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
 // (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
 // repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
+// A `release` Issue is never opted in either (joshuafolkken/kit#3360): a release is Tier C, so only a
+// person applies `auto-ok` to it, whatever the carry record or the branch's Issue says.
 
 interface AutoOkSignals {
 	is_opted_out: boolean
+	// The filing carries the `release` label.
+	is_release: boolean
 	is_carried: boolean
 	// The labels of the Issue the current branch names; `undefined` when the branch names none or the
 	// Issue could not be read.
@@ -31,6 +35,10 @@ const CROSS_REPOSITORY: AutoOkDecision = {
 	is_applied: false,
 	reason: 'the Issue is filed to another repository',
 }
+const RELEASE: AutoOkDecision = {
+	is_applied: false,
+	reason: `a ${RELEASE_LABEL} Issue is opted in by a person only`,
+}
 const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
 const BRANCH_OPTED_IN: AutoOkDecision = {
 	is_applied: true,
@@ -41,9 +49,22 @@ const NOT_OPTED_IN: AutoOkDecision = {
 	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
 }
 
-// The opt-out wins over every signal, then the carry record, then the branch's Issue.
-function decide(signals: AutoOkSignals): AutoOkDecision {
+type Withholding = Pick<AutoOkSignals, 'is_opted_out' | 'is_release'>
+
+// The two signals that withhold `auto-ok` before any other is read, or `undefined` when neither holds.
+function withheld(signals: Withholding): AutoOkDecision | undefined {
 	if (signals.is_opted_out) return OPTED_OUT
+	if (signals.is_release) return RELEASE
+
+	return undefined
+}
+
+// The opt-out and the `release` label win over every signal, then the carry record, then the branch's
+// Issue.
+function decide(signals: AutoOkSignals): AutoOkDecision {
+	const decision = withheld(signals)
+
+	if (decision !== undefined) return decision
 	if (signals.is_carried) return CARRIED
 	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
 
@@ -76,17 +97,21 @@ async function branch_labels(current: string): Promise<ReadonlyArray<string> | u
 }
 
 // Each read is skipped once an earlier signal has already decided the answer; a cross-repository
-// filing is refused before any signal is read.
+// filing is refused before any signal is read. `labels` are the ones the filing declares.
 async function resolve(
 	is_opted_out: boolean,
 	target: string,
 	current: string,
+	labels: ReadonlyArray<string> = [],
 ): Promise<AutoOkDecision> {
-	if (is_opted_out) return OPTED_OUT
+	const withholding = { is_opted_out, is_release: has_label_name(labels, RELEASE_LABEL) }
+	const decision = withheld(withholding)
+
+	if (decision !== undefined) return decision
 	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
 	if (await is_carried()) return CARRIED
 
-	return decide({ is_opted_out, is_carried: false, branch_labels: await branch_labels(current) })
+	return decide({ ...withholding, is_carried: false, branch_labels: await branch_labels(current) })
 }
 
 const issue_auto_ok = { decide, line_of, resolve }

package/scripts/issue/issue-backlinks-cli.ts

@@ -34,8 +34,8 @@ async function read_upstream(reference: string): Promise<UpstreamEntry | undefin
 	const match = REF_PATTERN.exec(reference)
 	if (match === null) return undefined
 
-	const [, repo, number] = match
-	const body = await read_body(number ?? '', repo)
+	const [, repo, number = ''] = match
+	const body = await read_body(number, repo)
 
 	return body === undefined ? undefined : { ref: reference, body }
 }

package/scripts/issue/issue-backlinks.ts

@@ -33,11 +33,11 @@ function has_heading(body: string, heading: string): boolean {
 	return markdown_section.has_line(body, heading)
 }
 
-// The lines under `heading`, up to the next `##` heading; `undefined` when the heading is absent.
-function section_lines(body: string, heading: string): ReadonlyArray<string> | undefined {
-	if (!has_heading(body, heading)) return undefined
+// The lines under the upstream heading, up to the next `##` heading; `undefined` when it is absent.
+function upstream_section_lines(body: string): ReadonlyArray<string> | undefined {
+	if (!has_heading(body, UPSTREAM_ISSUES_HEADING)) return undefined
 
-	return markdown_section.section_lines(body, heading)
+	return markdown_section.section_lines(body, UPSTREAM_ISSUES_HEADING)
 }
 
 // A heading that looks like the upstream one but is not exactly it (`## Upstream`, `## Upstreams`,
@@ -59,8 +59,8 @@ function tokens_of(section: ReadonlyArray<string>): ReadonlyArray<string> {
 		.filter((token) => token.length > 0)
 }
 
-function has_two_segments(path: string | undefined): boolean {
-	const segments = (path ?? '').split(PATH_SEPARATOR)
+function has_two_segments(path: string | undefined = ''): boolean {
+	const segments = path.split(PATH_SEPARATOR)
 
 	return segments.length === PATH_SEGMENT_COUNT && segments.every((segment) => segment.length > 0)
 }
@@ -115,7 +115,7 @@ function classify_backlinks(
 ): BacklinkVerdict {
 	if (has_wrong_upstream_heading(origin_body)) return WRONG_HEADING
 
-	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+	const section = upstream_section_lines(origin_body)
 
 	return section === undefined
 		? verdict_without_section(origin_body)
@@ -125,7 +125,7 @@ function classify_backlinks(
 // The `owner/repo#N` references the upstream section lists, so the CLI knows which upstream bodies to
 // fetch and check for `## Origin`.
 function upstream_references(origin_body: string): ReadonlyArray<string> {
-	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+	const section = upstream_section_lines(origin_body)
 	if (section === undefined) return []
 
 	return tokens_of(section).filter((token) => is_qualified_reference(token))
@@ -138,7 +138,7 @@ function upstream_references(origin_body: string): ReadonlyArray<string> {
 function needs_upstreams(origin_body: string): boolean {
 	if (has_wrong_upstream_heading(origin_body)) return false
 
-	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+	const section = upstream_section_lines(origin_body)
 	if (section === undefined) return false
 
 	return !is_malformed_upstream_section(section)

package/scripts/issue/issue-comment-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { cli_body } from '#scripts/josh/cli-body'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 
 // `josh issue:comment <N> --body <text> | --body-file <path>` — post one comment to an issue (a PR
@@ -28,25 +29,30 @@ interface CommentRequest {
 	body: string
 }
 
-// The value after a flag word, or `undefined` when the flag is absent. `cli_body.resolve` owns the
-// both-flags-at-once refusal and the file read, so this stays the one narrow job of finding the token.
-function flag_value(argv: ReadonlyArray<string>, flag: string): string | undefined {
-	const index = argv.indexOf(flag)
+// The read is strict (joshuafolkken/kit#3261): an unknown flag refuses the call rather than being
+// ignored. `cli_body.resolve` owns the both-flags-at-once refusal and the file read.
+const OPTIONS = { body: { type: 'string' }, 'body-file': { type: 'string' } } as const
 
-	return index === -1 ? undefined : argv[index + 1]
+// The number is the one positional, and it must be a real issue number: a missing, malformed or
+// second one refuses the whole call rather than posting to some other issue.
+function single_issue_number(positionals: ReadonlyArray<string>): string | undefined {
+	const [issue_number, ...rest] = positionals
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? issue_number : undefined
 }
 
-// The number is the first argument, and it must be a real issue number: a missing or malformed one
-// refuses the whole call rather than posting to some other issue. `resolve` may throw when both body
-// flags are given, which `run` reports — the message names the two flags a caller must pick between.
+// `resolve` may throw when both body flags are given, which `run` reports — the message names the two
+// flags a caller must pick between.
 function parse_request(argv: ReadonlyArray<string>): CommentRequest | undefined {
-	const [issue_number] = argv
-
-	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) return undefined
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue_number = single_issue_number(parsed.positionals)
+	if (issue_number === undefined) return undefined
 
 	const body = cli_body.resolve({
-		inline: flag_value(argv, BODY_FLAG),
-		file_path: flag_value(argv, BODY_FILE_FLAG),
+		inline: parsed.values.body,
+		file_path: parsed.values['body-file'],
 		inline_flag: BODY_FLAG,
 		file_flag: BODY_FILE_FLAG,
 	})