@joshuafolkken/kit 1.872.0

package/scripts/version/preinstall-version-update.ts

@@ -0,0 +1,84 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { execaSync } from 'execa'
+
+const SAFE_CHAIN_PKG = '@aikidosec/safe-chain'
+const VERSION_RE = /@aikidosec\/safe-chain@([^\s"']+)/u
+const NPM_TIMEOUT_MS = 30_000
+
+interface PreinstallInfo {
+	content: string
+	current_version: string
+}
+
+function extract_pinned_version(preinstall: string): string | undefined {
+	return VERSION_RE.exec(preinstall)?.[1]
+}
+
+function fetch_latest_version(): string | undefined {
+	const result = execaSync('npm', ['view', SAFE_CHAIN_PKG, 'version'], {
+		reject: false,
+		timeout: NPM_TIMEOUT_MS,
+	})
+	if (result.exitCode !== 0 || !result.stdout) return undefined
+
+	return result.stdout.trim()
+}
+
+function rewrite_version(content: string, current_version: string, next_version: string): string {
+	return content.replace(
+		`${SAFE_CHAIN_PKG}@${current_version}`,
+		() => `${SAFE_CHAIN_PKG}@${next_version}`,
+	)
+}
+
+function read_preinstall_info(package_json_path: string): PreinstallInfo | undefined {
+	const content = readFileSync(package_json_path, 'utf8')
+	const package_json = JSON.parse(content) as { scripts?: { preinstall?: string } }
+	const preinstall = package_json.scripts?.preinstall
+	if (!preinstall) return undefined
+
+	const current_version = extract_pinned_version(preinstall)
+	if (!current_version) return undefined
+
+	return { content, current_version }
+}
+
+function write_if_updated(
+	package_json_path: string,
+	content: string,
+	current: string,
+	latest: string,
+): void {
+	if (current === latest) {
+		console.info(`\n✔ ${SAFE_CHAIN_PKG} preinstall already at ${latest}`)
+
+		return
+	}
+
+	console.info(`\n↑ Updating ${SAFE_CHAIN_PKG} preinstall: ${current} → ${latest}`)
+	writeFileSync(package_json_path, rewrite_version(content, current, latest), 'utf8')
+}
+
+function sync(package_json_path: string): void {
+	const info = read_preinstall_info(package_json_path)
+	if (!info) return
+
+	const latest = fetch_latest_version()
+
+	if (!latest) {
+		console.warn(`\n⚠ Could not fetch latest version of ${SAFE_CHAIN_PKG}; skipping`)
+
+		return
+	}
+
+	write_if_updated(package_json_path, info.content, info.current_version, latest)
+}
+
+const preinstall_version_update = {
+	sync,
+	extract_pinned_version,
+	fetch_latest_version,
+	rewrite_version,
+}
+
+export { preinstall_version_update }

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env tsx
+/**
+ * Release gate: every dependency range this package publishes must resolve for a consumer.
+ *
+ * Usage: tsx scripts/version/publishable-range-check.ts
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { execaSync } from 'execa'
+import {
+	publishable_range,
+	type ProbeResult,
+	type PublishedRange,
+	type RangeProbe,
+} 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
+// managers on PATH, so the answer comes back already filtered by the same minimum-age policy a
+// consumer installs under. A plain fetch would read the unfiltered registry and pass a range no
+// consumer can resolve — the exact blind spot this guard exists to close.
+//
+// `pnpm view` rather than `npm view` because npm refuses to run at all inside a project whose
+// `devEngines.packageManager` names pnpm with `onFail: "error"`, failing every probe with
+// EBADDEVENGINES instead of answering. Both are shimmed, so the filtered view is preserved.
+function probe_range(name: string, range: string): ProbeResult {
+	const result = execaSync('pnpm', ['view', `${name}@${range}`, 'version'], {
+		reject: false,
+		timeout: VIEW_TIMEOUT_MS,
+	})
+
+	return { exit_code: result.exitCode ?? FAILURE_EXIT_CODE, stdout: result.stdout }
+}
+
+function report(violations: ReadonlyArray<PublishedRange>, total: number): number {
+	if (violations.length === 0) {
+		console.info(publishable_range.format_success(total))
+
+		return 0
+	}
+
+	console.error(publishable_range.format_failure(violations))
+
+	return FAILURE_EXIT_CODE
+}
+
+function report_skipped(skipped: ReadonlyArray<PublishedRange>): void {
+	if (skipped.length === 0) return
+
+	console.info(publishable_range.format_skipped(skipped))
+}
+
+/** Returns the process exit code so the decision can be asserted without spawning a process. */
+function check(package_json_content: string, probe: RangeProbe): number {
+	const ranges = publishable_range.read_published_ranges(package_json_content)
+	const { checked, skipped } = publishable_range.partition_registry_ranges(ranges)
+
+	report_skipped(skipped)
+
+	return report(publishable_range.find_unsatisfiable(checked, probe), checked.length)
+}
+
+function main(): void {
+	process.exit(check(readFileSync(PACKAGE_JSON_PATH, 'utf8'), probe_range))
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+const publishable_range_check = { check, probe_range }
+
+export { publishable_range_check }

package/scripts/version/publishable-range.ts

@@ -0,0 +1,123 @@
+import { package_with_deps_schema } from '#scripts/overrides/schemas'
+import semver from 'semver'
+
+// kit ships a `preinstall` hook that installs @aikidosec/safe-chain, whose minimum-age policy hides
+// releases younger than its window from every install running behind it. A range whose floor sits
+// inside that window has no satisfying version for a consumer, so `pnpm install` fails with
+// ERR_PNPM_NO_MATCHING_VERSION naming a version that demonstrably exists and is tagged latest (#742).
+//
+// The check asks the registry through that same filtered view instead of modelling the policy:
+// `pnpm view <name>@<range> version` prints no version and exits non-zero
+// (ERR_PNPM_PACKAGE_NOT_FOUND) exactly when nothing visible satisfies the range. Modelling would
+// mean guessing safe-chain's threshold, and `minimumReleaseAgeExclude` cannot stand in for it —
+// that list governs pnpm's own `minimum-release-age`, and safe-chain has no knowledge of it, which
+// is precisely what made the original failure surprising.
+
+interface PublishedRange {
+	name: string
+	range: string
+}
+
+interface ProbeResult {
+	exit_code: number
+	stdout: string
+}
+
+type RangeProbe = (name: string, range: string) => ProbeResult
+
+interface RangePartition {
+	checked: Array<PublishedRange>
+	skipped: Array<PublishedRange>
+}
+
+// A registry range is the only kind this guard can ask about. `workspace:*`, `catalog:`, `file:`,
+// `link:` and git URLs resolve outside the registry entirely, so probing them would report a
+// violation for a dependency that installs fine — and this runs in consumer repos too, where those
+// protocols are ordinary. semver decides: anything it cannot read as a range is not a registry range.
+function is_registry_range(range: string): boolean {
+	return semver.validRange(range) !== null
+}
+
+// Only `dependencies` are installed by a consumer, so only they can break a consumer's install.
+// devDependencies never reach one, and peer ranges are satisfied from the consumer's own tree.
+function read_published_ranges(package_json_content: string): Array<PublishedRange> {
+	const parsed = package_with_deps_schema.parse(JSON.parse(package_json_content))
+
+	return Object.entries(parsed.dependencies ?? {}).map(([name, range]) => ({ name, range }))
+}
+
+function partition_registry_ranges(ranges: ReadonlyArray<PublishedRange>): RangePartition {
+	const partition: RangePartition = { checked: [], skipped: [] }
+
+	for (const entry of ranges) {
+		if (is_registry_range(entry.range)) partition.checked.push(entry)
+		else partition.skipped.push(entry)
+	}
+
+	return partition
+}
+
+// A satisfied range is proven by an actual version on stdout, not merely by output existing:
+// safe-chain appends its own "some package versions were suppressed" notice to stdout, so a query
+// that answered nothing still comes back non-empty. Requiring a token semver can parse ignores that
+// banner without having to match its text, which would rot the moment its wording changes.
+//
+// Fails closed otherwise: a probe that could not answer (network error, auth failure) counts as
+// unsatisfiable rather than being waved through. This runs as a release gate, where a false stop
+// costs one re-run and a false pass publishes a package nobody can install.
+function is_satisfiable(result: ProbeResult): boolean {
+	if (result.exit_code !== 0) return false
+
+	return result.stdout.split(/\s+/u).some((token) => semver.valid(token) !== null)
+}
+
+function find_unsatisfiable(
+	ranges: ReadonlyArray<PublishedRange>,
+	probe: RangeProbe,
+): Array<PublishedRange> {
+	return ranges.filter((entry) => !is_satisfiable(probe(entry.name, entry.range)))
+}
+
+function format_violation(violation: PublishedRange): string {
+	return `   ${violation.name}@${violation.range} — no visible version satisfies this range`
+}
+
+// The remedy is spelled out because the failure reads as "this version does not exist" while the
+// version does exist: without the explanation the obvious next step is to raise the floor further.
+function format_failure(violations: ReadonlyArray<PublishedRange>): string {
+	return [
+		`\n✖ ${String(violations.length)} published dependency range(s) cannot be resolved:`,
+		...violations.map((violation) => format_violation(violation)),
+		'',
+		'   A consumer re-resolving its lockfile installs these ranges and hits',
+		'   ERR_PNPM_NO_MATCHING_VERSION. Lower each floor to a release that is already outside',
+		'   the supply-chain minimum-age window — the caret still admits the newer version once',
+		'   it ages in, so nothing is given up.',
+	].join('\n')
+}
+
+function format_success(count: number): string {
+	return `\n✔ ${String(count)} published dependency range(s) resolve against the registry.`
+}
+
+// Printed rather than dropped in silence: a guard that quietly narrows its own coverage reports
+// success for exactly the dependencies it never looked at.
+function format_skipped(skipped: ReadonlyArray<PublishedRange>): string {
+	const list = skipped.map((entry) => `${entry.name}@${entry.range}`).join(', ')
+
+	return `\n⏭ Not checked — resolved outside the registry: ${list}`
+}
+
+const publishable_range = {
+	read_published_ranges,
+	partition_registry_ranges,
+	is_registry_range,
+	is_satisfiable,
+	find_unsatisfiable,
+	format_failure,
+	format_skipped,
+	format_success,
+}
+
+export { publishable_range }
+export type { ProbeResult, PublishedRange, RangeProbe }

package/scripts/version/release-age.ts

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import semver from 'semver'
+import { z } from 'zod'
+
+// The minimum-release-age quarantine (kit#768), applied natively instead of inherited from
+// 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.
+
+const MINIMUM_RELEASE_AGE_RE = /^minimum-release-age\s*=\s*(\d+)\s*$/mu
+const NO_QUARANTINE_MINUTES = 0
+const NPMRC_PATH = '.npmrc'
+
+// 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 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 {
+	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
+
+	return raw === undefined ? NO_QUARANTINE_MINUTES : Number(raw)
+}
+
+// Stable releases only, on the requested major, published at or before the cutoff. The
+// registry's `time` object also carries `created` / `modified` keys and prereleases; both
+// fall out via the semver checks.
+// An undefined major matches every line; a defined one pins the search to that major.
+function is_on_major(version: string, major: string | undefined): boolean {
+	return major === undefined || String(semver.major(version)) === major
+}
+
+function is_eligible(
+	version: string,
+	published_at: string,
+	major: string | undefined,
+	cutoff_ms: number,
+): boolean {
+	if (
+		semver.valid(version) === null ||
+		semver.prerelease(version) !== null ||
+		!is_on_major(version, major)
+	) {
+		return false
+	}
+
+	const published_ms = Date.parse(published_at)
+
+	return Number.isFinite(published_ms) && published_ms <= cutoff_ms
+}
+
+// The newest release on the major that has aged past the quarantine window, or undefined
+// when none qualifies. Pure: identical inputs give the identical answer regardless of how
+// the surrounding process was launched.
+// `major` pins the search to one major line — what `josh latest` needs, since corepack validates the
+// resolved pnpm version against `devEngines`. Pass `undefined` to search every major, which is what
+// an "is this installable at all" question wants: `pnpm add pkg@latest` resolves to the newest
+// permitted release regardless of major (joshuafolkken/kit#808).
+function select_aged_version(
+	times: Record<string, string>,
+	major: string | undefined,
+	minimum_age_minutes: number,
+	now_ms: number,
+): string | undefined {
+	const cutoff_ms = now_ms - minimum_age_minutes * MS_PER_MINUTE
+	// cspell:ignore rcompare -- semver's reverse-compare API, newest first
+	const eligible = Object.entries(times)
+		.filter(([version, published_at]) => is_eligible(version, published_at, major, cutoff_ms))
+		.map(([version]) => version)
+		.toSorted(semver.rcompare)
+
+	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 {
+	try {
+		const raw = MINIMUM_RELEASE_AGE_RE.exec(readFileSync(npmrc_path, 'utf8'))?.[1]
+
+		return raw === undefined ? undefined : Number(raw)
+	} 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.
+//
+// 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
+// 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
+}
+
+// The window declared by the nearest `.npmrc` 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).
+//
+// `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.
+//
+// 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.
+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))
+	if (declared !== undefined) return declared
+	if (start === boundary) return undefined
+	const parent = path.dirname(start)
+
+	return parent === start ? undefined : find_declared_minimum_release_age(parent, boundary)
+}
+
+// The quarantine window resolved by walking up from a starting directory. An absent or undeclared
+// policy means no quarantine — it is advisory, and a project without one is not held back.
+function read_nearest_minimum_release_age(start: string, boundary?: string): number {
+	return find_declared_minimum_release_age(path.resolve(start), boundary) ?? NO_QUARANTINE_MINUTES
+}
+
+const release_age = {
+	release_times_schema,
+	parse_minimum_release_age,
+	read_minimum_release_age,
+	read_nearest_minimum_release_age,
+	select_aged_version,
+}
+
+export { release_age }

package/scripts/version/release-hold.ts

@@ -0,0 +1,142 @@
+import semver from 'semver'
+import { release_age } from './release-age'
+
+// A release-age hold: the local minimum-release-age policy withholds the newest release from
+// *unpinned* resolution, so anything resolved without an explicit version stops one or more releases
+// short of `latest`. Reporting that as a bare `⚠ → <latest>` is indistinguishable from an install the
+// user forgot to upgrade — and it recurs after every successful upgrade, because the newest release
+// 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:
+//
+//   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)
+//
+// So a pinned `Run:` hint always works and is never suppressed. What the window actually holds back
+// is peer resolution — the mechanism behind an upstream's effective install (joshuafolkken/kit#698),
+// which is why this explanation is attached there and nowhere else.
+
+const MINUTES_PER_HOUR = 60
+const MS_PER_MINUTE = 60_000
+const HOLD_LABEL = 'Held:'
+
+// Whether `latest` is itself inside the window — the precondition for a hold existing at all. Without
+// this check the note fires whenever `select_aged_version` returns something other than `latest` for
+// *any* reason: a prerelease `latest` (filtered as ineligible though published weeks ago) would be
+// declared "inside the 24 h window" forever, and a `latest` that has aged out would produce the
+// degenerate "an unpinned resolve lands on <latest>".
+function is_latest_withheld(
+	times: Record<string, string>,
+	latest: string,
+	minimum_age_minutes: number,
+	now_ms: number,
+): boolean {
+	const published_at = times[latest]
+	if (published_at === undefined) return false
+	const published_ms = Date.parse(published_at)
+	if (!Number.isFinite(published_ms)) return false
+
+	return published_ms > now_ms - minimum_age_minutes * MS_PER_MINUTE
+}
+
+// The newest release the quarantine window permits, or nothing when there is no hold to explain:
+// unavailable timestamps, a `latest` that has already aged out, or nothing aged out yet.
+//
+// Not scoped to `latest`'s major: a freshly published major is exactly when the previous line is the
+// only thing an unpinned resolve can reach.
+function resolve_installable(
+	times: Record<string, string> | undefined,
+	latest: string,
+	minimum_age_minutes: number,
+	now_ms: number,
+): string | undefined {
+	if (times === undefined) return undefined
+	if (!is_latest_withheld(times, latest, minimum_age_minutes, now_ms)) return undefined
+	const installable = release_age.select_aged_version(times, undefined, minimum_age_minutes, now_ms)
+
+	return installable === latest ? undefined : installable
+}
+
+// Whether a target is behind `latest` only because the quarantine withheld it. The install must be
+// behind `latest` (otherwise there is nothing to explain) and at least at the newest installable
+// release (otherwise it is genuinely stale and the existing upgrade hint is the right answer).
+//
+// `gte`, not equality: an install can sit *ahead* of the newest installable release and still be
+// behind `latest` — a version installed before the policy tightened, or one published between the
+// page kit reads and `latest`. Treating those as stale would print a command the same policy
+// refuses.
+function is_at_or_above(version: string, installable: string): boolean {
+	// Unparseable versions cannot be ordered, so the comparison falls back to equality rather than
+	// guessing at a prerelease or a non-semver tag.
+	if (semver.valid(version) === null || semver.valid(installable) === null) {
+		return version === installable
+	}
+
+	return semver.gte(version, installable)
+}
+
+function is_release_age_hold(
+	version: string | undefined,
+	latest: string,
+	installable: string | undefined,
+): boolean {
+	if (version === undefined || installable === undefined || version === latest) return false
+
+	return is_at_or_above(version, installable)
+}
+
+// Render the window in whole hours when it divides evenly, otherwise in minutes. The policy is
+// written in minutes but read by humans in hours (1440 → 24 h), and printing "1440 minutes" buries
+// the one number the reader needs to judge how long the hold lasts.
+function format_window(minimum_age_minutes: number): string {
+	if (minimum_age_minutes % MINUTES_PER_HOUR !== 0) return `${String(minimum_age_minutes)} min`
+
+	return `${String(minimum_age_minutes / MINUTES_PER_HOUR)} h`
+}
+
+// The explanation that accompanies a staleness marker no unpinned resolve can clear. Names the
+// window so the reader can see the gap is a policy delay rather than a failed upgrade.
+//
+// The "lands on" clause is dropped when the install is already ahead of `installable`: naming a
+// lower version beside a `⚠ → <latest>` marker reads as a downgrade instruction, when the point is
+// simply that `latest` is not yet reachable.
+function format_release_hold_note(
+	version: string,
+	latest: string,
+	installable: string,
+	minimum_age_minutes: number,
+): string {
+	const window = format_window(minimum_age_minutes)
+	const head = `${HOLD_LABEL} ${latest} is inside the ${window} minimum-release-age window`
+	if (version !== installable) return `${head}; an unpinned resolve cannot reach it yet`
+
+	return `${head}; an unpinned resolve lands on ${installable}`
+}
+
+// The note lines for one target, or nothing when the target is not on hold. Returned as an array so
+// callers can splice it into a line list without a conditional at every call site.
+function build_release_hold_notes(
+	version: string | undefined,
+	latest: string,
+	installable: string | undefined,
+	minimum_age_minutes: number,
+): Array<string> {
+	if (version === undefined || installable === undefined) return []
+	if (!is_release_age_hold(version, latest, installable)) return []
+
+	return [format_release_hold_note(version, latest, installable, minimum_age_minutes)]
+}
+
+const release_hold = {
+	HOLD_LABEL,
+	is_at_or_above,
+	is_latest_withheld,
+	resolve_installable,
+	is_release_age_hold,
+	format_window,
+	format_release_hold_note,
+	build_release_hold_notes,
+}
+
+export { release_hold }

package/scripts/version/running-binary.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { package_version_schema } from '#scripts/lib/schemas'
+import { safe_json_parse } from './parse-json'
+
+const PACKAGE_JSON = 'package.json'
+// Scripts live two levels under the package root (scripts/<group>/<file>.ts), so the running
+// binary's own package.json is reached by walking up twice from the script directory.
+const SCRIPT_DEPTH_FROM_ROOT = ['..', '..'] as const
+
+// The running binary is the single source of truth: resolve the package.json of the install that
+// is actually executing (via import.meta.url's directory), mirroring how `init`/`sync` key off the
+// package directory rather than `pnpm ls -g` or `<cwd>/node_modules`.
+function resolve_self_package_path(self_directory: string): string {
+	return path.join(self_directory, ...SCRIPT_DEPTH_FROM_ROOT, PACKAGE_JSON)
+}
+
+// Absolute directory of the running binary's package root — the path reported as the source of the
+// version that actually ran.
+function running_package_directory(self_directory: string): string {
+	return path.resolve(self_directory, ...SCRIPT_DEPTH_FROM_ROOT)
+}
+
+// Read the version declared in the running binary's own package.json. Undefined only when the file
+// is missing or malformed (should not happen for a real install, but kept total for safety).
+function read_running_version(self_directory: string): string | undefined {
+	const package_path = resolve_self_package_path(self_directory)
+	if (!existsSync(package_path)) return undefined
+	const parsed = package_version_schema.safeParse(
+		safe_json_parse(readFileSync(package_path, 'utf8')),
+	)
+
+	return parsed.success ? parsed.data.version : undefined
+}
+
+const running_binary = {
+	resolve_self_package_path,
+	running_package_directory,
+	read_running_version,
+}
+
+export { running_binary }

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

@@ -0,0 +1,49 @@
+// A package-name → currently-installed-version lookup, used to decide whether an upgrade command can
+// still change anything. `undefined` means the package is not installed at the scope being checked.
+type InstalledVersions = ReadonlyMap<string, string | undefined>
+
+// One `<package>@<version>` specifier found inside a shell command.
+interface VersionPin {
+	name: string
+	version: string
+}
+
+// One whole `<package>@<version>` shell token, e.g. `@joshuafolkken/app-kit@2.0.0` (scoped) or
+// `tsx@4.20.0` (unscoped). Applied to one token at a time and anchored at both ends, so the match is
+// linear — scanning the full command string would instead re-backtrack from every start position.
+// The version must begin with a digit so a dist-tag (`pkg@latest`) never matches: a dist-tag can
+// always resolve to something newer, so a command carrying one is never provably a no-op.
+const VERSION_PIN_PATTERN = /^(?<name>@[\w.-]+\/[\w.-]+|[\w.-]+)@(?<version>\d[\w.+-]*)$/u
+const WHITESPACE_PATTERN = /\s+/u
+
+// One shell token read as a version pin, or undefined when it is not one (a flag, a sub-command, a
+// path, or a dist-tag specifier).
+function parse_version_pin(token: string): VersionPin | undefined {
+	const { name, version } = VERSION_PIN_PATTERN.exec(token)?.groups ?? {}
+	if (name === undefined || version === undefined) return undefined
+
+	return { name, version }
+}
+
+// Every exact version pin the command carries, in the order they appear.
+function extract_version_pins(command: string): Array<VersionPin> {
+	return command.split(WHITESPACE_PATTERN).flatMap((token) => parse_version_pin(token) ?? [])
+}
+
+// An upgrade command provably cannot change anything when it pins at least one exact version and
+// every version it pins is already installed — running it would leave the staleness it was meant to
+// fix untouched (see #697, where `vu` → `v` looped forever on such a command).
+//
+// Only commands the consumer declared as pin-only reach this check. A command that forces a fresh
+// resolve (e.g. `pnpm remove -g <pkg> && pnpm add -g <pkg>@<latest>`) genuinely changes the resolved
+// dependency graph even though its pin is already installed, so consumers leave
+// `is_global_upgrade_command_pinned` unset for those and the hint is never suppressed.
+function is_no_op_upgrade_command(command: string, installed: InstalledVersions): boolean {
+	const pins = extract_version_pins(command)
+	if (pins.length === 0) return false
+
+	return pins.every((pin) => installed.get(pin.name) === pin.version)
+}
+
+export type { InstalledVersions }
+export { is_no_op_upgrade_command }