@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/init/init-logic-workspace.ts

@@ -2,7 +2,7 @@ function extract_yaml_top_level_keys(content: string): Array<string> {
 	return content.split('\n').flatMap((line) => {
 		const key = /^([a-zA-Z][a-zA-Z0-9_-]*):/u.exec(line)?.[1]
 
-		return key ? [key] : []
+		return key ?? []
 	})
 }
 
@@ -125,6 +125,45 @@ function add_missing_build_entries(existing: string, template: string): string {
 	return existing.replace(block, () => [block, ...missing].join('\n'))
 }
 
+interface MovedNpmrcSetting {
+	npmrc_key: string
+	workspace_key: string
+	value_pattern: RegExp
+}
+
+// `.npmrc` settings pnpm 12 reads only from `pnpm-workspace.yaml`, with the value shape each takes.
+// A project's own value (a longer age window, `engine-strict=false`) replaces the template's, so the
+// move neither loosens nor tightens what the project chose (joshuafolkken/kit#3267).
+const MOVED_NPMRC_SETTINGS: ReadonlyArray<MovedNpmrcSetting> = [
+	{ npmrc_key: 'minimum-release-age', workspace_key: 'minimumReleaseAge', value_pattern: /^\d+$/u },
+	{ npmrc_key: 'engine-strict', workspace_key: 'engineStrict', value_pattern: /^(?:true|false)$/u },
+]
+
+// The last assignment wins, as it does when npm reads the file.
+function npmrc_value(npmrc: string, key: string): string | undefined {
+	const pattern = new RegExp(String.raw`^[ \t]*${key}[ \t]*=[ \t]*(\S+)[ \t]*$`, 'gmu')
+
+	return [...npmrc.matchAll(pattern)].at(-1)?.[1]
+}
+
+function carry_npmrc_setting(template: string, npmrc: string, setting: MovedNpmrcSetting): string {
+	const value = npmrc_value(npmrc, setting.npmrc_key)
+	if (value === undefined || !setting.value_pattern.test(value)) return template
+	const line_pattern = new RegExp(`^${setting.workspace_key}:.*$`, 'mu')
+
+	return template.replace(line_pattern, () => `${setting.workspace_key}: ${value}`)
+}
+
+function carry_npmrc_settings(template: string, npmrc: string): string {
+	let result = template
+
+	for (const setting of MOVED_NPMRC_SETTINGS) {
+		result = carry_npmrc_setting(result, npmrc, setting)
+	}
+
+	return result
+}
+
 function merge_workspace_yaml(existing: string, template: string): string {
 	if (!existing.trim()) return template
 	const normalized = existing.endsWith('\n') ? existing : `${existing}\n`
@@ -138,6 +177,6 @@ function merge_workspace_yaml(existing: string, template: string): string {
 	return append_user_blocks(cleaned, new_keys, template)
 }
 
-const init_logic_workspace = { merge_workspace_yaml, template_build_values }
+const init_logic_workspace = { carry_npmrc_settings, merge_workspace_yaml, template_build_values }
 
 export { init_logic_workspace }

package/scripts/init/init-logic.ts

@@ -14,16 +14,15 @@ const DEV_ENGINES_VALUE = {
 	packageManager: { name: 'pnpm', version: '>=12.1.0', onFail: 'error' },
 }
 
-// New projects resolve kit from public npm. Existing registry and auth lines remain untouched
-// by merge_npmrc so consumers of other GitHub Packages can migrate separately.
-const NPMRC_LINES: ReadonlyArray<string> = [
+// The settings lines earlier kit releases wrote into a project `.npmrc`. pnpm 12 reads only registry
+// and auth settings from `.npmrc`, so all four are inert there: the age window and engine check now
+// live in `pnpm-workspace.yaml`, and `confirmModulesPurge` no longer exists (joshuafolkken/kit#3267).
+const LEGACY_NPMRC_LINES: ReadonlySet<string> = new Set([
 	'engine-strict=true',
 	'minimum-release-age=1440',
 	'confirmModulesPurge=false',
-	// Pin full GitHub Packages tarball URLs in the lockfile so pnpm >=11.5 frozen-lockfile
-	// installs hit the correct authenticated download path (avoids ERR_PNPM_FETCH_401 on CI).
 	'lockfile-include-tarball-url=true',
-]
+])
 
 const CSPELL_IMPORT = '@joshuafolkken/kit/cspell'
 
@@ -254,10 +253,6 @@ function generate_cspell_config(): string {
 	return `version: "0.2"\nimport:\n  - "${CSPELL_IMPORT}"\nwords: []\nignorePaths: []\n`
 }
 
-function generate_npmrc(): string {
-	return `${NPMRC_LINES.join('\n')}\n`
-}
-
 // Append `missing` lines to `existing`, inserting a separating newline when the base is
 // non-empty and lacks a trailing one. Returns `existing` untouched when nothing is missing.
 function append_missing_lines(existing: string, missing: ReadonlyArray<string>): string {
@@ -267,18 +262,19 @@ function append_missing_lines(existing: string, missing: ReadonlyArray<string>):
 	return `${prefix}${missing.join('\n')}\n`
 }
 
-// Insert-only: every existing line survives verbatim, including a `_authToken` line the consumer
-// added themselves. Kit removed the env-var form until #759, on the premise that pnpm always
-// ignores it in a project .npmrc — true only while `npmrcAuthFile` is unset. A consumer that
-// declares the project file its trusted auth file (Cloudflare Workers Builds via
-// `PNPM_CONFIG_NPMRC_AUTH_FILE`, for instance) gets the credential expanded, and that setting can
-// live in a deploy platform's dashboard — so no reading of the repository tells an inert line
-// apart from a live one. Deleting it took down a working production deploy; leaving it costs at
-// most the warning pnpm already prints. See docs/authentication.md §4(d).
+// Removes only an exact kit-written legacy line; every other line survives verbatim, including a
+// `_authToken` line the consumer added themselves and a setting carrying a value of their own. Kit
+// removed the env-var auth form until #759, on the premise that pnpm always ignores it in a project
+// .npmrc — true only while `npmrcAuthFile` is unset. A consumer that declares the project file its
+// trusted auth file (Cloudflare Workers Builds via `PNPM_CONFIG_NPMRC_AUTH_FILE`, for instance) gets
+// the credential expanded, and that setting can live in a deploy platform's dashboard — so no
+// reading of the repository tells an inert auth line apart from a live one. Deleting it took down a
+// working production deploy. See docs/authentication.md §4(d).
 function merge_npmrc(content: string): string {
-	const missing = NPMRC_LINES.filter((line) => !content.includes(line))
+	const lines = content.split('\n')
+	const kept = lines.filter((line) => !LEGACY_NPMRC_LINES.has(line.trim()))
 
-	return append_missing_lines(content, missing)
+	return kept.length === lines.length ? content : kept.join('\n')
 }
 
 // A gitignore line worth appending during a union merge: real ignore patterns only.
@@ -349,10 +345,6 @@ function strip_kit_only_vscode_settings_content(raw: string): string {
 	return json_format.format_json(stripped)
 }
 
-function get_npmrc_lines(): ReadonlyArray<string> {
-	return NPMRC_LINES
-}
-
 function get_development_engines_value(): typeof DEV_ENGINES_VALUE {
 	return DEV_ENGINES_VALUE
 }
@@ -436,7 +428,6 @@ const init_logic = {
 	get_tsconfig_exclude_entries,
 	generate_lefthook_config,
 	generate_cspell_config,
-	generate_npmrc,
 	merge_npmrc,
 	merge_gitignore,
 	get_tsconfig_extends_entry,
@@ -450,7 +441,6 @@ const init_logic = {
 	SAFE_CHAIN_CMD,
 	GUARDED_LEFTHOOK_CMD,
 	upgrade_prepare_lefthook_warning,
-	get_npmrc_lines,
 	get_development_engines_value,
 	get_ai_copy_files,
 	get_ai_copy_file_mappings,

package/scripts/init/init.ts

@@ -23,6 +23,7 @@ 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 { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
@@ -81,21 +82,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/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,6 +1,6 @@
 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 { issue_state_cli } from './issue-state-cli'

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,
 	})