@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/version/latest-corepack.ts

@@ -11,12 +11,12 @@
  * major equals the `packageManager` pin keeps both invariants: never below the adopted
  * major, and advancing while that major is the current one.
  *
- * The `minimum-release-age` quarantine is applied natively from `.npmrc` (kit#768).
- * safe-chain filters the registry only when the process tree was launched through one of
- * its wrapped shell commands, so `josh latest` and `pnpm josh latest` used to resolve
+ * The `minimumReleaseAge` quarantine is applied natively from `pnpm-workspace.yaml` (kit#768,
+ * #3267). safe-chain filters the registry only when the process tree was launched through one
+ * of its wrapped shell commands, so `josh latest` and `pnpm josh latest` used to resolve
  * different answers and the pin oscillated. Reading the window from the repo-managed
- * `.npmrc` and filtering by publish timestamp makes the resolution identical in every
- * invocation context; right after a pnpm release the answer is simply the previous
+ * `pnpm-workspace.yaml` and filtering by publish timestamp makes the resolution identical in
+ * every invocation context; right after a pnpm release the answer is simply the previous
  * release, exactly as the filtered view behaved.
  *
  * The resolved version is floored at the current `packageManager` pin: a filtered registry
@@ -38,6 +38,7 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { json_value } from '#scripts/lib/json-value'
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import semver from 'semver'
 import { z } from 'zod'
@@ -49,8 +50,7 @@ const PACKAGE_MANAGER_RE = /"packageManager"\s*:\s*"pnpm@(\d+)(?:[^\d]|$)/u
 const PINNED_VERSION_RE = /"packageManager"\s*:\s*"pnpm@([^"+]+)/u
 const TARGET_PREFIX = 'pnpm@'
 const FAILURE_EXIT_CODE = 1
-const NPMRC_PATH = '.npmrc'
-const VIEW_TIMEOUT_MS = 30_000
+const WORKSPACE_PATH = 'pnpm-workspace.yaml'
 const SHA512_BYTES = 64
 const INTEGRITY_RE = /^sha512-([A-Za-z0-9+/]+={0,2})$/u
 const PACKAGE_MANAGER_VALUE_RE = /("packageManager"\s*:\s*")pnpm@[^"]+(")/u
@@ -121,7 +121,7 @@ function extract_times_json(stdout: string): Record<string, string> | undefined
 function query_release_times(): Record<string, string> | undefined {
 	const result = execaSync('pnpm', ['view', 'pnpm', 'time', '--json'], {
 		reject: false,
-		timeout: VIEW_TIMEOUT_MS,
+		timeout: COMMAND_TIMEOUT_MS,
 	})
 	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
 
@@ -134,14 +134,14 @@ function query_major_latest_version(major: string): string | undefined {
 	const times = query_release_times()
 	if (times === undefined) return undefined
 
-	// The project's own `.npmrc`, deliberately not the upward walk the version check uses: `josh
-	// latest` reads `package.json` and writes the pnpm pin relative to the working directory, so it
-	// has no subdirectory case — and honouring a user-level policy here could freeze pnpm bumps in a
-	// project that declares none (joshuafolkken/kit#808).
+	// The project's own `pnpm-workspace.yaml`, deliberately not the upward walk the version check
+	// uses: `josh latest` reads `package.json` and writes the pnpm pin relative to the working
+	// directory, so it has no subdirectory case — and honouring an ancestor's policy here could freeze
+	// pnpm bumps in a project that declares none (joshuafolkken/kit#808).
 	return release_age.select_aged_version(
 		times,
 		major,
-		release_age.read_minimum_release_age(NPMRC_PATH),
+		release_age.read_minimum_release_age(WORKSPACE_PATH),
 		Date.now(),
 	)
 }
@@ -156,7 +156,7 @@ function parse_latest_version(stdout: string): string | undefined {
 function query_latest_version(): string | undefined {
 	const result = execaSync('pnpm', ['view', 'pnpm', 'version', '--json'], {
 		reject: false,
-		timeout: VIEW_TIMEOUT_MS,
+		timeout: COMMAND_TIMEOUT_MS,
 	})
 	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
 
@@ -179,8 +179,8 @@ function warn_skip(reason: string): void {
 	console.warn(`⚠ Skipped pnpm bump (${reason}); the chain continues.`)
 }
 
-function warn_unresolved(major: string | undefined): void {
-	warn_skip(`no pnpm ${major ?? ''} release resolvable from the registry`)
+function warn_unresolved(major: string | undefined = ''): void {
+	warn_skip(`no pnpm ${major} release resolvable from the registry`)
 }
 
 function run_pnpm_update(target: string): number {
@@ -247,7 +247,7 @@ function extract_encoded_integrity(stdout: string): string | undefined {
 function query_integrity(target: string): string | undefined {
 	const result = execaSync('pnpm', ['view', target, 'dist.integrity', '--json'], {
 		reject: false,
-		timeout: VIEW_TIMEOUT_MS,
+		timeout: COMMAND_TIMEOUT_MS,
 	})
 	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
 

package/scripts/version/latest-regression.ts

@@ -1,4 +1,4 @@
-import { package_with_deps_schema } from '#scripts/overrides/schemas'
+import { package_with_deps_schema } from '#scripts/overrides/overrides-schemas'
 import semver from 'semver'
 
 // `pnpm update --latest` sets each range to whatever the registry reports as newest. When a

package/scripts/version/latest-update.ts

@@ -13,7 +13,7 @@ import { overrides_check } from '#scripts/overrides/overrides-logic'
 import { execaSync } from 'execa'
 import { fresh_metadata_cache } from './fresh-metadata-cache'
 import { latest_regression, type VersionRegression } from './latest-regression'
-import { preinstall_version_update } from './preinstall-version-update'
+import { safe_chain_version_update } from './safe-chain-version-update'
 
 const PACKAGE_JSON_PATH = 'package.json'
 const LOCKFILE_PATH = 'pnpm-lock.yaml'
@@ -175,11 +175,11 @@ function main(): void {
 	report_overrides(overrides)
 	report_lockfile_overrides()
 
-	// Skipped after a rollback so the tree really is left exactly as it was found — this sync writes
-	// package.json to advance the pinned safe-chain version, which would contradict the notice that
+	// Skipped after a rollback so the tree really is left exactly as it was found — this sync rewrites
+	// the workflows' pinned safe-chain installer, which would contradict the notice that
 	// nothing changed.
 	if (outcome.status === 0 && !outcome.is_rolled_back) {
-		preinstall_version_update.sync(PACKAGE_JSON_PATH)
+		safe_chain_version_update.sync()
 	}
 }
 

package/scripts/version/npm-registry.ts

@@ -1,6 +1,8 @@
 import { json_value } from '#scripts/lib/json-value'
+import { FETCH_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { migrate_logic } from '#scripts/registry-migration/migrate-logic'
 import { execaSync } from 'execa'
+import semver from 'semver'
 import { z } from 'zod'
 import { release_age } from './release-age'
 
@@ -12,7 +14,6 @@ const PUBLIC_REGISTRY = 'https://registry.npmjs.org'
 // The abbreviated packument carries `dist-tags` without every version's full manifest.
 const ABBREVIATED_ACCEPT = 'application/vnd.npm.install-v1+json'
 const FULL_ACCEPT = 'application/json'
-const REQUEST_TIMEOUT_MS = 10_000
 const SCOPE_SEPARATOR = '/'
 const ENCODED_SCOPE_SEPARATOR = '%2f'
 const SCOPE_PATTERN = /^@[^/]+(?=\/)/u
@@ -29,7 +30,10 @@ const FETCH_SCRIPT = [
 	'process.stdout.write(await response.text())',
 ].join('\n')
 
-const latest_schema = z.looseObject({ 'dist-tags': z.looseObject({ latest: z.string() }) })
+// A registry-supplied version is used only when it is exactly a semver version — it ends up inside an
+// install command, so `1.0.0;curl…|sh` or any other text is refused at the source, not downstream.
+const version_schema = z.string().refine((value) => semver.valid(value) === value)
+const latest_schema = z.looseObject({ 'dist-tags': z.looseObject({ latest: version_schema }) })
 const times_schema = z.looseObject({ time: release_age.release_times_schema })
 
 // The packument URL for a package name; a scoped name keeps its `@` and encodes the separator, the
@@ -42,7 +46,7 @@ function read_packument(package_name: string, accept: string): unknown {
 	const result = execaSync(
 		process.execPath,
 		['--input-type=module', '-e', FETCH_SCRIPT, packument_url(package_name), accept],
-		{ reject: false, timeout: REQUEST_TIMEOUT_MS },
+		{ reject: false, timeout: FETCH_TIMEOUT_MS },
 	)
 	if (result.exitCode !== 0) return undefined
 
@@ -59,7 +63,7 @@ function is_github_scope(scope: string): boolean {
 	if (is_cached_github !== undefined) return is_cached_github
 	const result = execaSync('pnpm', ['config', 'get', `${scope}${SCOPE_REGISTRY_SUFFIX}`], {
 		reject: false,
-		timeout: REQUEST_TIMEOUT_MS,
+		timeout: FETCH_TIMEOUT_MS,
 	})
 	const is_github = result.exitCode === 0 && migrate_logic.is_github_tarball(result.stdout.trim())
 
@@ -102,6 +106,17 @@ function has_public_version(package_name: string, version: string): boolean {
 	return parsed.success && parsed.data.time[version] !== undefined
 }
 
-const npm_registry = { has_public_version, packument_url, read_latest, read_release_times }
+// The version itself, or nothing when it is not exactly a semver version.
+function valid_version(value: string): string | undefined {
+	return version_schema.safeParse(value).success ? value : undefined
+}
+
+const npm_registry = {
+	has_public_version,
+	packument_url,
+	read_latest,
+	read_release_times,
+	valid_version,
+}
 
 export { npm_registry }

package/scripts/version/publishable-range-check.ts

@@ -6,6 +6,7 @@
  */
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import {
 	publishable_range,
@@ -15,7 +16,6 @@ import {
 } from './publishable-range'
 
 const PACKAGE_JSON_PATH = 'package.json'
-const VIEW_TIMEOUT_MS = 30_000
 const FAILURE_EXIT_CODE = 1
 
 // A registry query rather than a direct fetch: safe-chain installs shims ahead of the package
@@ -29,7 +29,7 @@ const FAILURE_EXIT_CODE = 1
 function probe_range(name: string, range: string): ProbeResult {
 	const result = execaSync('pnpm', ['view', `${name}@${range}`, 'version'], {
 		reject: false,
-		timeout: VIEW_TIMEOUT_MS,
+		timeout: COMMAND_TIMEOUT_MS,
 	})
 
 	return { exit_code: result.exitCode ?? FAILURE_EXIT_CODE, stdout: result.stdout }

package/scripts/version/publishable-range.ts

@@ -1,4 +1,4 @@
-import { package_with_deps_schema } from '#scripts/overrides/schemas'
+import { package_with_deps_schema } from '#scripts/overrides/overrides-schemas'
 import semver from 'semver'
 
 // kit ships a `preinstall` hook that installs @aikidosec/safe-chain, whose minimum-age policy hides

package/scripts/version/release-age.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { yaml_document } from '#scripts/lib/yaml-document'
 import semver from 'semver'
 import { z } from 'zod'
 
@@ -7,30 +8,41 @@ import { z } from 'zod'
 // safe-chain's interception. safe-chain filters the registry only when the process tree was
 // started through one of its six wrapped shell commands, so `josh latest` and
 // `pnpm josh latest` used to resolve different "newest release" answers. These functions
-// make the resolution deterministic: the policy comes from the repo-managed `.npmrc`, the
-// publish timestamps from the registry, and the selection is a pure computation over both.
+// make the resolution deterministic: the policy comes from the repo-managed `pnpm-workspace.yaml`,
+// the publish timestamps from the registry, and the selection is a pure computation over both.
+// pnpm 12 reads its settings from `pnpm-workspace.yaml` — a `minimum-release-age` line in `.npmrc`
+// is ignored there, so reading it would report a window pnpm does not apply (kit#3267).
 
-const MINIMUM_RELEASE_AGE_RE = /^minimum-release-age\s*=\s*(\d+)\s*$/mu
 const NO_QUARANTINE_MINUTES = 0
-const NPMRC_PATH = '.npmrc'
+const WORKSPACE_PATH = 'pnpm-workspace.yaml'
+const workspace_age_schema = z.object({ minimumReleaseAge: z.number().int().nonnegative() })
 
 // A version → ISO publish date map, the shape both the registry and the GitHub Packages API are
 // reduced to before the aged-version selection runs.
 const release_times_schema = z.record(z.string(), z.string())
 const MS_PER_MINUTE = 60_000
 
-// The window `.npmrc` content declares, or nothing when it does not declare one — an explicit
-// `minimum-release-age=0` stays 0 rather than collapsing into "not declared".
-function parse_declared_minimum_release_age(npmrc_content: string): number | undefined {
-	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
+function parse_workspace(workspace_content: string): unknown {
+	try {
+		return yaml_document.parse_yaml(workspace_content)
+	} catch {
+		return undefined
+	}
+}
+
+// The window `pnpm-workspace.yaml` content declares, or nothing when it does not declare one or the
+// document is malformed — an explicit `minimumReleaseAge: 0` stays 0 rather than collapsing into
+// "not declared".
+function parse_declared_minimum_release_age(workspace_content: string): number | undefined {
+	const parsed = workspace_age_schema.safeParse(parse_workspace(workspace_content))
 
-	return raw === undefined ? undefined : Number(raw)
+	return parsed.success ? parsed.data.minimumReleaseAge : undefined
 }
 
-// The quarantine window in minutes from `.npmrc`; a missing or malformed entry means no
-// quarantine, matching pnpm's own default for the setting.
-function parse_minimum_release_age(npmrc_content: string): number {
-	return parse_declared_minimum_release_age(npmrc_content) ?? NO_QUARANTINE_MINUTES
+// The quarantine window in minutes from `pnpm-workspace.yaml`; a missing or malformed entry means
+// no quarantine, matching pnpm's own default for the setting.
+function parse_minimum_release_age(workspace_content: string): number {
+	return parse_declared_minimum_release_age(workspace_content) ?? NO_QUARANTINE_MINUTES
 }
 
 // Stable releases only, on the requested major, published at or before the cutoff. The
@@ -83,49 +95,47 @@ function select_aged_version(
 	return eligible[0]
 }
 
-// The window declared in one `.npmrc`, or nothing when the file is absent, unreadable, or does not
-// declare the setting. Distinguishing "not declared" from "declared as 0" is what lets an explicit
-// `minimum-release-age=0` opt-out stop the walk instead of falling through to an ancestor's policy.
-function read_declared_minimum_release_age(npmrc_path: string): number | undefined {
+// The window declared in one `pnpm-workspace.yaml`, or nothing when the file is absent, unreadable,
+// or does not declare the setting. Distinguishing "not declared" from "declared as 0" is what lets an
+// explicit `minimumReleaseAge: 0` opt-out stop the walk instead of falling through to an ancestor's.
+function read_declared_minimum_release_age(workspace_path: string): number | undefined {
 	try {
-		return parse_declared_minimum_release_age(readFileSync(npmrc_path, 'utf8'))
+		return parse_declared_minimum_release_age(readFileSync(workspace_path, 'utf8'))
 	} catch {
 		return undefined
 	}
 }
 
-// The quarantine window declared by one specific `.npmrc`, defaulting to the project's own. An
-// absent, unreadable, or undeclared setting means no quarantine — the policy is advisory, and a
-// project without one is not held back.
+// The quarantine window declared by one specific `pnpm-workspace.yaml`, defaulting to the project's
+// own. An absent, unreadable, or undeclared setting means no quarantine — the policy is advisory,
+// and a project without one is not held back.
 //
 // Deliberately not the upward walk below: `josh latest` resolves this against the working directory
-// it also writes `corepack use` into, and honouring a user-level policy there could freeze pnpm
+// it also writes `corepack use` into, and honouring an ancestor's policy there could freeze pnpm
 // bumps in a project that declares none (joshuafolkken/kit#808).
-function read_minimum_release_age(npmrc_path: string = NPMRC_PATH): number {
-	return read_declared_minimum_release_age(npmrc_path) ?? NO_QUARANTINE_MINUTES
+function read_minimum_release_age(workspace_path: string = WORKSPACE_PATH): number {
+	return read_declared_minimum_release_age(workspace_path) ?? NO_QUARANTINE_MINUTES
 }
 
-// The window declared by the nearest `.npmrc` at or above `start`, or nothing.
+// The window declared by the nearest `pnpm-workspace.yaml` at or above `start`, or nothing.
 //
-// Two reasons this walks rather than reading one path. `josh version` and `josh latest` both run
-// from anywhere inside a project — and from outside one — so resolving against the working directory
-// alone would silently read "no quarantine" in every subdirectory. And pnpm merges config per key
-// across project, workspace and user levels, so a project `.npmrc` that only sets a registry must
-// not mask a `~/.npmrc` carrying the policy (joshuafolkken/kit#808).
+// This walks rather than reading one path because `josh version` and `josh latest` both run from
+// anywhere inside a project — and from outside one — so resolving against the working directory
+// alone would silently read "no quarantine" in every subdirectory (joshuafolkken/kit#808). pnpm
+// finds its workspace root the same way, by walking up to the nearest `pnpm-workspace.yaml`.
 //
-// `boundary` stops the walk at a known root. Production passes none — a user-level `~/.npmrc` is a
-// legitimate source — while tests bound the search so it cannot depend on the machine's real home.
+// `boundary` stops the walk at a known root. Production passes none, while tests bound the search
+// so it cannot depend on the directories above the machine's temp root.
 //
-// Simplification: the walk visits every ancestor, whereas pnpm consults only the project, the
-// workspace root, `~/.npmrc` and its global config. A stray `.npmrc` in an intermediate directory
-// would therefore be honoured here and not by pnpm. The consequence is one informational `Held:`
-// line — the value never suppresses a command — so the faithful four-level model is not worth its
-// complexity here.
+// Simplification: a nearer workspace file that does not declare the window falls through to an
+// ancestor's, and pnpm's user-level `config.yaml` is not consulted. The consequence is one
+// informational `Held:` line — the value never suppresses a command — so modelling pnpm's exact
+// lookup is not worth its complexity here.
 function find_declared_minimum_release_age(
 	start: string,
 	boundary: string | undefined,
 ): number | undefined {
-	const declared = read_declared_minimum_release_age(path.join(start, NPMRC_PATH))
+	const declared = read_declared_minimum_release_age(path.join(start, WORKSPACE_PATH))
 	if (declared !== undefined) return declared
 	if (start === boundary) return undefined
 	const parent = path.dirname(start)

package/scripts/version/release-hold.ts

@@ -8,7 +8,7 @@ import { release_age } from './release-age'
 // is by definition the youngest (joshuafolkken/kit#808).
 //
 // **The window binds unpinned resolution only.** Measured on pnpm 11.22.0 with
-// `minimum-release-age=1440` and a release published 3.5 h earlier:
+// `minimumReleaseAge: 1440` and a release published 3.5 h earlier:
 //
 //   pnpm add pkg@1.80.0   ->  1.80.0   (pnpm records a `minimumReleaseAgeExclude` entry)
 //   pnpm add pkg          ->  1.78.0   (the newest release past the window)

package/scripts/version/safe-chain-version-update.ts

@@ -0,0 +1,40 @@
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { ci_installer_pin } from '#scripts/safe-chain/ci-installer-pin'
+import { npm_registry } from '#scripts/version/npm-registry'
+import { execaSync } from 'execa'
+
+const SAFE_CHAIN_PKG = '@aikidosec/safe-chain'
+
+// The registry's answer is trusted only as an exact semver version: it ends up in workflow files and
+// in the installer URL (joshuafolkken/kit#3266).
+function fetch_latest_version(): string | undefined {
+	const result = execaSync('npm', ['view', SAFE_CHAIN_PKG, 'version'], {
+		reject: false,
+		timeout: COMMAND_TIMEOUT_MS,
+	})
+	if (result.exitCode !== 0 || !result.stdout) return undefined
+
+	return npm_registry.valid_version(result.stdout.trim())
+}
+
+// The hash-verified installer pinned in the workflows is the one place a safe-chain release is
+// recorded; `preinstall` no longer names one (joshuafolkken/kit#3269). Every repository moves the
+// files that carry the pin — app-kit's own `dast.yml` / `load.yml` included (joshuafolkken/kit#2830).
+function sync(): void {
+	const latest = fetch_latest_version()
+
+	if (latest === undefined) {
+		console.warn(`\n⚠ Could not fetch a valid latest version of ${SAFE_CHAIN_PKG}; skipping`)
+
+		return
+	}
+
+	ci_installer_pin.sync(latest)
+}
+
+const safe_chain_version_update = {
+	sync,
+	fetch_latest_version,
+}
+
+export { safe_chain_version_update }

package/scripts/version/upgrade-shell-command.ts

@@ -1,9 +1,28 @@
 import type { PackageVersionConfig } from './version-command-config'
 
+// One upgrade the version commands offer and run: `text` is the line printed after `Run:`, and
+// `steps` are the argument vectors executed in order, each only after the one before it succeeded.
+// A command kit builds itself is spawned without a shell, so a registry-supplied version is never
+// parsed by one; only the consumer's own configured command goes through `sh -c`.
+interface UpgradeCommand {
+	text: string
+	steps: ReadonlyArray<ReadonlyArray<string>>
+}
+
+const STEP_SEPARATOR = ' && '
+
 function update_scope_flag(is_local: boolean): string {
 	return is_local ? '-D' : '-g'
 }
 
+function update_argv(
+	latest: string,
+	is_local: boolean,
+	config: PackageVersionConfig,
+): Array<string> {
+	return ['pnpm', 'add', update_scope_flag(is_local), `${config.package_name}@${latest}`]
+}
+
 // The bare `pnpm add` invocation that installs one package at an exact version, in the global or the
 // project (dev-dependency) scope.
 function format_update_command(
@@ -11,20 +30,41 @@ function format_update_command(
 	is_local: boolean,
 	config: PackageVersionConfig,
 ): string {
-	return `pnpm add ${update_scope_flag(is_local)} ${config.package_name}@${latest}`
+	return update_argv(latest, is_local, config).join(' ')
+}
+
+// The upgrade for one target. A project-scope install is followed by kit's lockfile repair
+// (`fix-gh-packages`), which a global install does not need. The printed text is derived from the
+// steps, so the hint and what actually runs cannot drift apart.
+function build_upgrade_command(
+	latest: string,
+	is_local: boolean,
+	config: PackageVersionConfig,
+): UpgradeCommand {
+	const steps = [update_argv(latest, is_local, config)]
+	if (is_local) steps.push(['node_modules/.bin/tsx', config.fix_gh_packages_path])
+
+	return { text: steps.map((step) => step.join(' ')).join(STEP_SEPARATOR), steps }
+}
+
+// The consumer's own configured command — `pnpm add -g …`, or a chain with `&&` — is inside the trust
+// boundary and needs a shell to mean what it says.
+function shell_upgrade_command(command: string): UpgradeCommand {
+	return { text: command, steps: [['sh', '-c', command]] }
 }
 
-// The full shell command for one upgrade target. A project-scope install is chained with kit's
-// lockfile repair (`fix-gh-packages`), which a global install does not need.
 function build_upgrade_shell_command(
 	latest: string,
 	is_local: boolean,
 	config: PackageVersionConfig,
 ): string {
-	const add_command = format_update_command(latest, is_local, config)
-	if (!is_local) return add_command
-
-	return `${add_command} && node_modules/.bin/tsx ${config.fix_gh_packages_path}`
+	return build_upgrade_command(latest, is_local, config).text
 }
 
-export { build_upgrade_shell_command, format_update_command }
+export type { UpgradeCommand }
+export {
+	build_upgrade_command,
+	build_upgrade_shell_command,
+	format_update_command,
+	shell_upgrade_command,
+}

package/scripts/version/version-check-logic.ts

@@ -1,6 +1,12 @@
 import { release_hold } from './release-hold'
 import { is_no_op_upgrade_command, type InstalledVersions } from './upgrade-command-guard'
-import { build_upgrade_shell_command, format_update_command } from './upgrade-shell-command'
+import {
+	build_upgrade_command,
+	build_upgrade_shell_command,
+	format_update_command,
+	shell_upgrade_command,
+	type UpgradeCommand,
+} from './upgrade-shell-command'
 import type { PackageVersionConfig } from './version-command-config'
 
 const NOT_INSTALLED = 'not installed'
@@ -161,11 +167,11 @@ function resolve_effective_upgrade_hint(report: UpstreamReport): EffectiveUpgrad
 // The consumer-supplied global upgrade command for a stale effective upstream, or nothing. Skipped
 // when the consumer did not opt in, the effective install is up to date / unresolved, or the command
 // provably cannot change the effective version it was meant to fix (see the note line instead).
-function build_effective_upgrade_commands(report: UpstreamReport): Array<string> {
+function build_effective_upgrade_commands(report: UpstreamReport): Array<UpgradeCommand> {
 	const hint = resolve_effective_upgrade_hint(report)
 	if (hint === undefined || hint.is_no_op) return []
 
-	return [hint.command]
+	return [shell_upgrade_command(hint.command)]
 }
 
 // The explanation that replaces a suppressed `Run:` hint, so a stale effective install is never left
@@ -202,8 +208,9 @@ function format_upstream_lines(report: UpstreamReport): Array<string> {
 // Drop repeated commands while preserving first-seen order. A consumer with several upstreams can
 // return the same chain-pinning global command from each of them (game-kit returns one command for
 // both app-kit and kit), which would otherwise print an identical `Run:` line once per upstream.
-function unique_upgrade_commands(commands: ReadonlyArray<string>): Array<string> {
-	return [...new Set(commands)]
+// Keyed on the printed text, which the steps are derived from or carried verbatim inside.
+function unique_upgrade_commands(commands: ReadonlyArray<UpgradeCommand>): Array<UpgradeCommand> {
+	return [...new Map(commands.map((command) => [command.text, command])).values()]
 }
 
 // The outcome line for an effective install the upgrade command left exactly where it was.
@@ -235,37 +242,39 @@ function format_effective_outcome(report: UpstreamReport, after: string | undefi
 
 // The project-scope upgrade command when the upstream's project dependency is installed and stale.
 // Always local (with lockfile repair), since the project path is the only scope kit resolves.
-function build_project_upgrade_commands(report: UpstreamReport): Array<string> {
+function build_project_upgrade_commands(report: UpstreamReport): Array<UpgradeCommand> {
 	if (!is_target_stale(report.project_version, report.latest)) return []
 
-	return [build_upgrade_shell_command(report.latest, true, report.config)]
+	return [build_upgrade_command(report.latest, true, report.config)]
 }
 
 // Build the upgrade commands for every upstream: the consumer's global command for a stale effective
 // install first, then the project-scope command, mirroring the main report's global-before-project
 // order. Upstreams without either stale target contribute nothing.
-function build_upstream_upgrade_commands(reports: ReadonlyArray<UpstreamReport>): Array<string> {
+function build_upstream_upgrade_commands(
+	reports: ReadonlyArray<UpstreamReport>,
+): Array<UpgradeCommand> {
 	return reports.flatMap((report) => [
 		...build_effective_upgrade_commands(report),
 		...build_project_upgrade_commands(report),
 	])
 }
 
-// Build the shell upgrade commands for whichever of the two targets are installed and stale.
+// Build the upgrade commands for whichever of the two targets are installed and stale.
 // Order: global first, then project (mirrors the display order).
 function build_dual_upgrade_commands(
 	snapshot: VersionSnapshot,
 	config: PackageVersionConfig,
-): Array<string> {
+): Array<UpgradeCommand> {
 	const { global_version, project_version, latest } = snapshot
-	const commands: Array<string> = []
+	const commands: Array<UpgradeCommand> = []
 
 	if (is_target_stale(global_version, latest)) {
-		commands.push(build_upgrade_shell_command(latest, false, config))
+		commands.push(build_upgrade_command(latest, false, config))
 	}
 
 	if (is_target_stale(project_version, latest)) {
-		commands.push(build_upgrade_shell_command(latest, true, config))
+		commands.push(build_upgrade_command(latest, true, config))
 	}
 
 	return commands
@@ -298,7 +307,7 @@ function format_dual_version_output(
 	const hints = unique_upgrade_commands([
 		...build_dual_upgrade_commands(snapshot, config),
 		...build_upstream_upgrade_commands(upstreams),
-	]).map((command) => `Run: ${command}`)
+	]).map((command) => `Run: ${command.text}`)
 	if (hints.length > 0) lines.push('', ...hints)
 	if (extras.warning !== undefined) lines.push('', extras.warning)