@joshuafolkken/kit 1.872.0

package/scripts/version/version-commands.ts

@@ -0,0 +1,296 @@
+import { execaSync } from 'execa'
+import { release_age } from './release-age'
+import { release_hold } from './release-hold'
+import { running_binary } from './running-binary'
+import type { InstalledVersions } from './upgrade-command-guard'
+import {
+	version_check_logic,
+	type ReleaseHold,
+	type RunningBinary,
+	type UpstreamEffective,
+	type UpstreamReport,
+	type VersionOutputExtras,
+	type VersionSnapshot,
+} from './version-check-logic'
+import type {
+	UpstreamHookContext,
+	UpstreamVersionConfig,
+	VersionCommandConfig,
+} from './version-command-config'
+import { fetch_latest_version, fetch_release_times } from './version-remote'
+import { version_targets } from './version-targets'
+
+const FAILURE_EXIT_CODE = 1
+const ALREADY_UP_TO_DATE = 'Already up to date'
+const NO_QUARANTINE_MINUTES = 0
+
+// What the local minimum-release-age policy permits for one package. Resolved per package because
+// the newest installable release is a property of that package's own publish history. Returns a hold
+// whose `installable` is undefined when the timestamps cannot be read — the report then renders
+// exactly as it did before (joshuafolkken/kit#808).
+//
+// Skipped entirely unless some target is behind `latest`: the timestamps cost a second `gh api`
+// round trip per package, and a package with nothing stale has no gap for a hold to explain. On the
+// common all-current run the report costs exactly what it did before this feature.
+function read_release_hold(
+	versions_endpoint: string | undefined,
+	latest: string,
+	versions: ReadonlyArray<string | undefined>,
+): ReleaseHold | undefined {
+	if (versions.every((version) => version === undefined || version === latest)) return undefined
+	// Resolved by walking up from the working directory: `josh version` runs from subdirectories and
+	// from outside a project, where a fixed relative path would silently read "no quarantine".
+	const minimum_age_minutes = release_age.read_nearest_minimum_release_age(process.cwd())
+	// No window means nothing can be withheld, so there is no hold to explain and no reason to spend
+	// a registry round trip discovering that.
+	if (minimum_age_minutes <= NO_QUARANTINE_MINUTES) return undefined
+	const installable = release_hold.resolve_installable(
+		fetch_release_times(versions_endpoint),
+		latest,
+		minimum_age_minutes,
+		Date.now(),
+	)
+	// Absent rather than present-with-nothing: `ReleaseHold` is publicly exported, so the field's
+	// presence must mean a hold was actually resolved.
+	if (installable === undefined) return undefined
+
+	return { installable, minimum_age_minutes }
+}
+
+// Read the global, project, and latest versions for the configured package — the three values a
+// single `version` / `version:upgrade` invocation operates on.
+function read_snapshot(config: VersionCommandConfig): VersionSnapshot {
+	return {
+		global_version: version_targets.read_global_version(config.package_name),
+		project_version: version_targets.read_project_version(process.cwd(), config.package_name),
+		latest: fetch_latest_version(config.versions_endpoint, config.package_name),
+	}
+}
+
+// The running binary is the single source of truth: report the version/path of the install that
+// actually executed. Undefined when the consumer supplies no `self_dir` or the binary is unknown.
+function read_running_binary(self_directory: string | undefined): RunningBinary | undefined {
+	if (self_directory === undefined) return undefined
+	const version = running_binary.read_running_version(self_directory)
+	if (version === undefined) return undefined
+
+	return { version, path: running_binary.running_package_directory(self_directory) }
+}
+
+// Build the optional report extras (running-binary line + PATH-shadowing warning) from the
+// consumer's hooks, assigning only defined values to stay `exactOptionalPropertyTypes`-compatible.
+function build_extras(config: VersionCommandConfig): VersionOutputExtras {
+	const extras: VersionOutputExtras = {}
+	const running = read_running_binary(config.self_directory)
+	if (running !== undefined) extras.running = running
+	const warning = config.resolve_warning?.()
+	if (warning !== undefined) extras.warning = warning
+
+	return extras
+}
+
+// Resolve the upstream's effective (running-relative) install from the consumer's opt-in hooks, or
+// undefined when the consumer supplies neither (e.g. kit, which has no upstream). Both hooks are
+// required together and receive `context` (the downstream package's already-fetched latest) so the
+// global upgrade command can reuse kit's single fetch instead of resolving `latest` a second time.
+function build_upstream_effective(
+	upstream: UpstreamVersionConfig,
+	context: UpstreamHookContext,
+): UpstreamEffective | undefined {
+	const { resolve_effective_version, resolve_global_upgrade_command } = upstream
+	if (resolve_effective_version === undefined) return undefined
+	if (resolve_global_upgrade_command === undefined) return undefined
+
+	return {
+		version: resolve_effective_version(context),
+		upgrade_command: resolve_global_upgrade_command(context),
+	}
+}
+
+// The globally-resolved versions kit already knows for one upstream: the primary package's global
+// install (what a `pnpm add -g <primary>@<v>` command would target) and the upstream's own effective
+// install. Attached to the report only when the consumer declared its global upgrade command
+// pin-only, so the no-op guard can prove a command that pins these exact versions is dead (#697).
+function build_installed_versions(
+	report: UpstreamReport,
+	config: VersionCommandConfig,
+	snapshot: VersionSnapshot,
+): InstalledVersions {
+	return new Map([
+		[config.package_name, snapshot.global_version],
+		[report.config.package_name, report.effective?.version],
+	])
+}
+
+// Attach the effective install and, when the consumer declared its global command pin-only, the
+// installed versions the no-op guard needs. Mutates the report in place so the optional fields stay
+// absent for upstreams without hooks (`exactOptionalPropertyTypes`).
+function attach_upstream_effective(
+	report: UpstreamReport,
+	config: VersionCommandConfig,
+	snapshot: VersionSnapshot,
+	upstream: UpstreamVersionConfig,
+): void {
+	const context: UpstreamHookContext = { latest: snapshot.latest, upstream_latest: report.latest }
+	const effective = build_upstream_effective(upstream, context)
+	if (effective === undefined) return
+
+	report.effective = effective
+	if (upstream.is_global_upgrade_command_pinned !== true) return
+
+	report.installed_versions = build_installed_versions(report, config, snapshot)
+}
+
+// Read one upstream's project-installed and latest versions, plus the optional effective/global
+// install when the consumer opts in. Absent the hooks, the report keeps its project/latest-only shape.
+function read_upstream_report(
+	upstream: UpstreamVersionConfig,
+	config: VersionCommandConfig,
+	snapshot: VersionSnapshot,
+	is_hold_wanted: boolean,
+): UpstreamReport {
+	const latest = fetch_latest_version(upstream.versions_endpoint, upstream.package_name)
+	const project_version = version_targets.read_project_version(process.cwd(), upstream.package_name)
+	const report: UpstreamReport = { config: upstream, project_version, latest }
+
+	attach_upstream_effective(report, config, snapshot, upstream)
+	// After the effective install is attached, so its version counts toward the staleness gate.
+	// Only the effective install is peer-resolved, so it is the only target the window can hold back.
+	const hold = is_hold_wanted
+		? read_release_hold(upstream.versions_endpoint, latest, [report.effective?.version])
+		: undefined
+	if (hold !== undefined) report.hold = hold
+
+	return report
+}
+
+// Read the reports for the configured upstream chain, preserving the configured (nearest-first)
+// order. Empty when the consumer declares no upstreams (e.g. kit itself). `snapshot` is the primary
+// package's already-read state (from `read_snapshot`): its `latest` is threaded into each upstream's
+// hooks so a consumer never re-fetches it, and its `global_version` feeds the no-op guard.
+function read_upstream_reports(
+	config: VersionCommandConfig,
+	snapshot: VersionSnapshot,
+	is_hold_wanted = false,
+): Array<UpstreamReport> {
+	return config.upstreams.map((upstream) =>
+		read_upstream_report(upstream, config, snapshot, is_hold_wanted),
+	)
+}
+
+// The `version` (show) command for any configured package: print the dual/offline report with
+// staleness markers, upstream sections, upgrade hints, and the running-binary/warning extras.
+function run_check(config: VersionCommandConfig): void {
+	const snapshot = read_snapshot(config)
+	const upstream_reports = read_upstream_reports(config, snapshot, true)
+
+	console.info(
+		version_check_logic.format_dual_version_output(
+			snapshot,
+			config,
+			build_extras(config),
+			upstream_reports,
+		),
+	)
+}
+
+function run_upgrade_command(command: string): number {
+	const result = execaSync('sh', ['-c', command], { stdio: 'inherit', reject: false })
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+// Run every upgrade command in order, returning the last non-zero exit code (or 0 when all
+// succeed) so a failure on either target is surfaced without aborting the remaining upgrades.
+function run_all_upgrade_commands(commands: ReadonlyArray<string>): number {
+	let exit_code = 0
+
+	for (const command of commands) {
+		const code = run_upgrade_command(command)
+		if (code !== 0) exit_code = code
+	}
+
+	return exit_code
+}
+
+// What to print when nothing can be upgraded: either everything is current, or a stale effective
+// upstream's global command provably cannot change it and the explanation says so (#697).
+function build_idle_message(reports: ReadonlyArray<UpstreamReport>): string {
+	const notes = version_check_logic.build_upstream_upgrade_notes(reports)
+	if (notes.length === 0) return ALREADY_UP_TO_DATE
+
+	return notes.join('\n')
+}
+
+// Re-read one upstream's effective install after the upgrade ran and describe what changed, or
+// nothing when it reached the latest (success needs no explanation). Gated on the global command
+// having actually been emitted: a suppressed no-op command never ran, so reporting that it "did not
+// change" the install would blame a command the user was never offered.
+function describe_effective_outcome(
+	upstream: UpstreamVersionConfig,
+	report: UpstreamReport | undefined,
+	snapshot: VersionSnapshot,
+): Array<string> {
+	const { resolve_effective_version } = upstream
+	if (resolve_effective_version === undefined || report === undefined) return []
+	if (version_check_logic.build_effective_upgrade_commands(report).length === 0) return []
+
+	const after = resolve_effective_version({
+		latest: snapshot.latest,
+		upstream_latest: report.latest,
+	})
+	if (after === report.latest) return []
+
+	return [version_check_logic.format_effective_outcome(report, after)]
+}
+
+// After the upgrade commands ran, report every effective upstream that did not reach its latest, so
+// `version:upgrade` states the outcome itself instead of leaving the next `version` to repeat the
+// same warning. Reports and configured upstreams share an index — `read_upstream_reports` maps over
+// `config.upstreams` in order — which is how each report is paired back with its hooks.
+function report_effective_outcomes(
+	config: VersionCommandConfig,
+	snapshot: VersionSnapshot,
+	reports: ReadonlyArray<UpstreamReport>,
+): void {
+	const lines = config.upstreams.flatMap((upstream, index) =>
+		describe_effective_outcome(upstream, reports[index], snapshot),
+	)
+	if (lines.length > 0) console.info(lines.join('\n'))
+}
+
+// The `version:upgrade` command for any configured package: upgrade whichever of global/project
+// are stale, plus any stale upstream project dependencies (each respecting the fix-gh-packages
+// lockfile repair). Returns the process exit code.
+function run_upgrade(config: VersionCommandConfig): number {
+	const snapshot = read_snapshot(config)
+	const reports = read_upstream_reports(config, snapshot)
+	const commands = version_check_logic.unique_upgrade_commands([
+		...version_check_logic.build_dual_upgrade_commands(snapshot, config),
+		...version_check_logic.build_upstream_upgrade_commands(reports),
+	])
+
+	if (commands.length === 0) {
+		console.info(build_idle_message(reports))
+
+		return 0
+	}
+
+	const exit_code = run_all_upgrade_commands(commands)
+
+	report_effective_outcomes(config, snapshot, reports)
+
+	return exit_code
+}
+
+const version_commands = {
+	read_snapshot,
+	read_upstream_reports,
+	build_extras,
+	run_check,
+	run_upgrade,
+	run_upgrade_command,
+	run_all_upgrade_commands,
+}
+
+export { version_commands }

package/scripts/version/version-remote.ts

@@ -0,0 +1,86 @@
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { execaSync } from 'execa'
+import { safe_json_parse } from './parse-json'
+import { release_age } from './release-age'
+
+const GH_FAILURE_FALLBACK = 'gh api failed'
+// Enough history to reach past a quarantine window into the newest release that has aged out of it.
+// The endpoint's default page is a single entry, so it is widened to the API's maximum rather than
+// paged through: a page that cannot span the window resolves no aged release at all, which silently
+// drops the explanation and leaves the unexplained `⚠` this exists to remove. At the maximum, a
+// week-long window still needs more than 14 releases a day to overflow (joshuafolkken/kit#808).
+const TIMES_PAGE_SIZE = 100
+// Reduce the endpoint's version objects to the version → publish-date map the selector expects.
+const TIMES_JQ = '[.[] | {(.name): .created_at}] | add'
+
+// Guard an undefined/empty endpoint before it reaches `gh api` — otherwise the CLI would run
+// `gh api undefined` and surface a raw 404 ExecaSyncError. Narrows to a concrete string.
+function require_endpoint(versions_endpoint: string | undefined, package_name: string): string {
+	if (versions_endpoint !== undefined && versions_endpoint.trim() !== '') return versions_endpoint
+
+	throw new Error(
+		`Could not derive a versions endpoint for ${package_name}; check its version-command config.`,
+	)
+}
+
+// Turn a failed `gh api` result into a concise detail line: prefer gh's own stderr
+// (e.g. "gh: Not Found (HTTP 404)"), falling back to execa's short message.
+function describe_failure(result: { stderr: string; shortMessage?: string | undefined }): string {
+	const stderr = result.stderr.trim()
+
+	if (stderr !== '') return stderr
+
+	return result.shortMessage ?? GH_FAILURE_FALLBACK
+}
+
+// Fetch the latest published version from a GitHub Packages versions endpoint. The endpoint is
+// supplied per package (e.g. `/users/joshuafolkken/packages/npm/kit/versions?per_page=1`) so the
+// same fetcher serves kit, jgame, and app-kit. Guards an undefined/empty endpoint and wraps
+// `gh api` failures with an actionable message instead of a raw ExecaSyncError stack.
+function fetch_latest_version(versions_endpoint: string | undefined, package_name: string): string {
+	const endpoint = require_endpoint(versions_endpoint, package_name)
+	const result = execaSync('gh', ['api', endpoint, '--jq', '.[0].name'], {
+		...git_gh_exec.direct_environment(),
+		reject: false,
+	})
+
+	if (result.exitCode === 0) return result.stdout.trim()
+
+	throw new Error(
+		`Failed to fetch latest version for ${package_name} via ${endpoint}: ${describe_failure(result)}`,
+	)
+}
+
+// Rewrite the endpoint's page size. The endpoint is consumer-overridable, so `per_page` is set
+// through a query parser rather than by substituting the literal the default happens to carry.
+function with_page_size(endpoint: string, page_size: number): string {
+	// Cut at the first `?` rather than `split`, whose limit truncates: a query carrying a second `?`
+	// would otherwise lose everything after it.
+	const separator = endpoint.indexOf('?')
+	const path_part = separator === -1 ? endpoint : endpoint.slice(0, separator)
+	const query = new URLSearchParams(separator === -1 ? '' : endpoint.slice(separator + 1))
+
+	query.set('per_page', String(page_size))
+
+	return `${path_part}?${query.toString()}`
+}
+
+// Publish timestamps for the package's recent releases, or nothing. Unlike `fetch_latest_version`
+// this never throws: the timestamps only enrich an explanation, so a package whose history cannot be
+// read keeps the report it had before (joshuafolkken/kit#808).
+function fetch_release_times(
+	versions_endpoint: string | undefined,
+): Record<string, string> | undefined {
+	if (versions_endpoint === undefined || versions_endpoint.trim() === '') return undefined
+	const endpoint = with_page_size(versions_endpoint, TIMES_PAGE_SIZE)
+	const result = execaSync('gh', ['api', endpoint, '--jq', TIMES_JQ], {
+		...git_gh_exec.direct_environment(),
+		reject: false,
+	})
+	if (result.exitCode !== 0) return undefined
+	const parsed = release_age.release_times_schema.safeParse(safe_json_parse(result.stdout))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+export { fetch_latest_version, fetch_release_times, with_page_size }

package/scripts/version/version-targets.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { package_version_schema, pnpm_ls_global_schema } from '#scripts/lib/schemas'
+import { execaSync } from 'execa'
+import { safe_json_parse } from './parse-json'
+
+const NODE_MODULES = 'node_modules'
+const PACKAGE_JSON = 'package.json'
+
+// Build the `pnpm ls -g --json <package>` arguments for the package being checked.
+function build_pnpm_ls_arguments(package_name: string): Array<string> {
+	return ['ls', '-g', '--json', package_name]
+}
+
+// Read the globally installed version from `pnpm ls -g --json` output. Returns undefined when
+// the package is absent or the output cannot be parsed (e.g. pnpm missing, empty stdout).
+function parse_global_version(stdout: string, package_name: string): string | undefined {
+	const parsed = pnpm_ls_global_schema.safeParse(safe_json_parse(stdout))
+	if (!parsed.success) return undefined
+
+	return parsed.data[0]?.dependencies?.[package_name]?.version
+}
+
+// Read the project-local version from a node_modules package.json string. Undefined when the
+// file is missing (raw is undefined) or malformed.
+function parse_project_version(raw: string | undefined): string | undefined {
+	if (raw === undefined) return undefined
+	const parsed = package_version_schema.safeParse(safe_json_parse(raw))
+
+	return parsed.success ? parsed.data.version : undefined
+}
+
+function read_global_version(package_name: string): string | undefined {
+	const result = execaSync('pnpm', build_pnpm_ls_arguments(package_name), { reject: false })
+
+	return parse_global_version(result.stdout, package_name)
+}
+
+function project_package_path(cwd: string, package_name: string): string {
+	return path.join(cwd, NODE_MODULES, package_name, PACKAGE_JSON)
+}
+
+function read_project_version(cwd: string, package_name: string): string | undefined {
+	const package_path = project_package_path(cwd, package_name)
+	const raw = existsSync(package_path) ? readFileSync(package_path, 'utf8') : undefined
+
+	return parse_project_version(raw)
+}
+
+// Read the current project's own declared version from <cwd>/package.json. This is the version
+// that `josh bump` increments — distinct from read_project_version, which reads the installed kit
+// package version under node_modules.
+function read_workspace_version(cwd: string): string | undefined {
+	const package_path = path.join(cwd, PACKAGE_JSON)
+	const raw = existsSync(package_path) ? readFileSync(package_path, 'utf8') : undefined
+
+	return parse_project_version(raw)
+}
+
+// `format_project_version_line` / `project_version_line` lived here and formatted
+// `📦 project version: <v>` for the end of a workflow. Both are gone (joshuafolkken/kit#1486): a
+// child no longer bumps, so the local manifest names the *previous* release rather than what the run
+// ships, and every caller now prints the count of unreleased merges instead
+// (`scripts/git/git-followup-pending.ts`). Removed rather than left unused, so nothing reaches for
+// the misleading reading again.
+
+const version_targets = {
+	build_pnpm_ls_arguments,
+	parse_global_version,
+	parse_project_version,
+	read_global_version,
+	read_project_version,
+	project_package_path,
+	read_workspace_version,
+	// The manifest's filename. Exported rather than re-declared in each of `josh release`'s two
+	// halves (joshuafolkken/kit#1169): the module that already owns "where the project's manifest is"
+	// is where the name belongs.
+	PACKAGE_JSON,
+}
+
+export { version_targets }

package/scripts/yaml/yaml-document.ts

@@ -0,0 +1,46 @@
+import { json_object_schema } from '#scripts/lib/schemas'
+import { load, loadAll, YAMLException } from 'js-yaml'
+
+// js-yaml 5 throws "expected a document, but the input is empty" for input with no document node
+// (empty / whitespace / comment-only), whereas js-yaml 4 returned undefined. Restore the v4
+// semantics so reading an empty or comment-only file yields {} instead of throwing.
+const EMPTY_YAML_REASON = 'expected a document, but the input is empty'
+
+function load_yaml_or_empty(content: string): unknown {
+	try {
+		return load(content)
+	} catch (error) {
+		if (error instanceof YAMLException && error.reason === EMPTY_YAML_REASON) return {}
+		throw error
+	}
+}
+
+// Shared by every reader that needs a YAML file as a plain object: the config-merge list patcher
+// and the overrides protection check both parse `pnpm-workspace.yaml`-shaped documents, and a
+// second copy of the empty-document handling would drift the moment js-yaml changes again.
+function parse_yaml(content: string): Record<string, unknown> {
+	const raw = load_yaml_or_empty(content)
+	if (raw === null || raw === undefined) return {}
+
+	return json_object_schema.parse(raw)
+}
+
+function is_mapping_document(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+// pnpm 11 writes pnpm-lock.yaml as a multi-document stream (the package-manager document, then the
+// dependency graph), which `load` rejects outright. Non-mapping documents are dropped rather than
+// rejected: a reader only ever looks up keys, and a stream that legitimately carries a scalar
+// document should not make the whole file unreadable.
+// js-yaml 5.3 deprecated the iterator overload ("Iterator is not supported"); the plain
+// `loadAll(content)` form returns the documents as an array and is the supported replacement.
+function parse_yaml_documents(content: string): Array<Record<string, unknown>> {
+	if (content.trim().length === 0) return []
+
+	return loadAll(content).filter(is_mapping_document)
+}
+
+const yaml_document = { is_mapping_document, parse_yaml, parse_yaml_documents }
+
+export { yaml_document }

package/scripts-ai/completion-gate.ts

@@ -0,0 +1,13 @@
+const GATE_LINT = 'pnpm run lint'
+const GATE_CHECK_CI = 'pnpm josh check:svelte:ci'
+const GATE_CSPELL = 'pnpm josh cspell:dot'
+const GATE_TEST_UNIT = 'pnpm josh test:unit'
+
+const COMPLETION_GATE_STEPS: ReadonlyArray<string> = [
+	GATE_LINT,
+	GATE_CHECK_CI,
+	GATE_CSPELL,
+	GATE_TEST_UNIT,
+]
+
+export { COMPLETION_GATE_STEPS, GATE_LINT, GATE_CHECK_CI, GATE_CSPELL, GATE_TEST_UNIT }

package/scripts-ai/environment-loader.ts

@@ -0,0 +1,9 @@
+function load_optional_environment(): void {
+	try {
+		process.loadEnvFile('.env')
+	} catch {
+		// .env is optional
+	}
+}
+
+export { load_optional_environment }

package/scripts-ai/epic-check.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env tsx
+/**
+ * Check an existing epic Issue against the four requirements, reporting each as pass or fail.
+ *
+ * Usage: tsx scripts-ai/epic-check.ts <issue-number>
+ */
+import { git_epic_run } from '../scripts/git/git-epic-run'
+import { epic_cli } from './epic-cli'
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh epic:check <issue-number>'
+const FAILURE_EXIT_CODE = 1
+
+async function main(): Promise<void> {
+	const epic_number = epic_cli.parse_check_argument(process.argv.slice(ARGV_OFFSET))
+
+	if (epic_number === undefined) {
+		console.error(`✖ An epic issue number is required.\n${USAGE}`)
+		process.exit(FAILURE_EXIT_CODE)
+	}
+
+	const exit_code = await git_epic_run.check_epic(epic_number)
+
+	if (exit_code !== 0) process.exit(exit_code)
+}
+
+// A `gh` failure carries its stderr as the message, which is the useful part; printing it alone
+// keeps a routine "not authenticated" from arriving as a stack trace.
+try {
+	await main()
+} catch (error) {
+	console.error(`✖ ${error instanceof Error ? error.message : String(error)}`)
+	process.exit(FAILURE_EXIT_CODE)
+}

package/scripts-ai/epic-cli-argv.ts

@@ -0,0 +1,77 @@
+// The argument-reading primitives every `josh epic` form shares.
+//
+// They were private to `epic-cli.ts` until `--remove` needed the same four (joshuafolkken/kit#1712),
+// at which point the choice was to copy them or to name them. Copying is what `CLAUDE.md` prohibits,
+// and the failure it would produce is specific: two readers disagreeing about what counts as a flag
+// value would have one form silently take a `--decision-file` path for an issue number.
+
+const FLAG_PREFIX = '--'
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+
+function is_flag(argument: string): boolean {
+	return argument.startsWith(FLAG_PREFIX)
+}
+
+function read_flag_value(argv: ReadonlyArray<string>, flag: string): string | undefined {
+	const index = argv.indexOf(flag)
+	if (index === -1) return undefined
+
+	return argv[index + 1]
+}
+
+// A value-taking flag's argument must not be mistaken for a child issue number, so the argument
+// directly after one is dropped along with the flag itself.
+function is_flag_value(
+	argv: ReadonlyArray<string>,
+	index: number,
+	value_flags: ReadonlySet<string>,
+): boolean {
+	return value_flags.has(argv[index - 1] ?? '')
+}
+
+// **Which flags consume the argument after them is per parser, not module-wide**: `--before` takes a
+// value only under `--add`, and treating it as one everywhere had `josh epic "T" 101 102 --after 103`
+// silently drop #103 from the new epic instead of ignoring an unknown flag (joshuafolkken/kit#890).
+function to_positional_arguments(
+	argv: ReadonlyArray<string>,
+	value_flags: ReadonlySet<string>,
+): Array<string> {
+	return argv.filter(
+		(argument, index) => !is_flag(argument) && !is_flag_value(argv, index, value_flags),
+	)
+}
+
+function count_flag(argv: ReadonlyArray<string>, flag: string): number {
+	return argv.filter((argument) => argument === flag).length
+}
+
+// A value-taking flag given without a usable value: last on the line, or followed by another flag.
+// **Refused rather than read as "none was asked for"** — `--decision-file` is passed precisely because
+// the record has to exist, so a shell that ate the path would otherwise land the edit, write no
+// record, post no comment and exit 0: success reported for half the job. Repeated, it names two
+// records, which is refused for the reason two positioning flags are (joshuafolkken/kit#1350).
+function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
+	if (!argv.includes(flag)) return false
+	if (count_flag(argv, flag) > 1) return true
+	const value = read_flag_value(argv, flag)
+
+	return value === undefined || is_flag(value)
+}
+
+// `--add` and `--remove` refuse a flag they do not know, unlike creation and promotion which ignore
+// one. A typo there costs a flag; here a mistyped flag would leave its value positional, so it
+// becomes an issue number and the edit silently lands somewhere else (joshuafolkken/kit#890).
+function has_unknown_flag(argv: ReadonlyArray<string>, known: ReadonlySet<string>): boolean {
+	return argv.some((argument) => is_flag(argument) && !known.has(argument))
+}
+
+const epic_cli_argv = {
+	is_flag,
+	read_flag_value,
+	to_positional_arguments,
+	count_flag,
+	is_value_unusable,
+	has_unknown_flag,
+}
+
+export { epic_cli_argv, ISSUE_NUMBER_PATTERN }