@joshuafolkken/kit 1.872.0

package/scripts/version/latest-regression.ts

@@ -0,0 +1,93 @@
+import { package_with_deps_schema } from '#scripts/overrides/schemas'
+import semver from 'semver'
+
+// `pnpm update --latest` sets each range to whatever the registry reports as newest. When a
+// supply-chain guard suppresses versions younger than a minimum age, the newest *allowed* version
+// can be older than the one already installed, and the update writes that regression into
+// package.json and the lockfile without a word. Detecting it means comparing the ranges the update
+// rewrote against the ones it replaced — the registry is not consulted again, so this stays a pure
+// comparison of two manifests.
+
+interface VersionRegression {
+	name: string
+	kept: string
+	offered: string
+}
+
+function read_direct_dependencies(package_json_content: string): Record<string, string> {
+	const parsed = package_with_deps_schema.parse(JSON.parse(package_json_content))
+
+	return { ...parsed.dependencies, ...parsed.devDependencies }
+}
+
+// Ranges are compared by their lowest satisfying version: `^4.23.5` guarantees at least 4.23.5, so
+// a rewrite to `^4.23.1` lowers the floor even though both ranges could resolve to the same build.
+// A range semver cannot read (a git URL, `workspace:*`, a tag) yields undefined and is skipped —
+// there is no ordering to assert, and guessing one would revert updates that were never regressions.
+function to_floor(range: string | undefined): semver.SemVer | undefined {
+	if (range === undefined) return undefined
+
+	try {
+		return semver.minVersion(range) ?? undefined
+	} catch {
+		return undefined
+	}
+}
+
+function is_regression(before_range: string | undefined, after_range: string | undefined): boolean {
+	const before = to_floor(before_range)
+	const after = to_floor(after_range)
+
+	if (before === undefined || after === undefined) return false
+
+	return semver.lt(after, before)
+}
+
+/**
+ * Compare the direct dependencies of two package.json revisions and report every entry whose
+ * version floor moved down. Packages added or removed between the two are not regressions.
+ */
+function find_regressions(before_content: string, after_content: string): Array<VersionRegression> {
+	const before = read_direct_dependencies(before_content)
+	const after = read_direct_dependencies(after_content)
+
+	return Object.entries(before)
+		.filter(([name, range]) => is_regression(range, after[name]))
+		.map(([name, range]) => ({ name, kept: range, offered: after[name] ?? '' }))
+}
+
+function format_regression(regression: VersionRegression): string {
+	return `${regression.name}@${regression.kept} (newest allowed is ${regression.offered})`
+}
+
+// Named "keeping" rather than "skipping" so it does not read as the held-back list printed above it:
+// those are packages deliberately pinned, these are ones the update would have moved backwards.
+//
+// The wording blames the *allowed* set rather than the registry: the newer version is normally still
+// published and still tagged latest — a minimum-age gate is simply hiding it for now — so the state
+// is transient and a later run moves forward on its own.
+//
+// It also has to say the whole update was rolled back. Excluding the offender from the update
+// targets does not exclude it from resolution: pnpm resolves the entire graph either way, and while
+// a pin sits above the newest allowed version that pin is unresolvable
+// (`ERR_PNPM_NO_MATCHING_VERSION`). So the choice is between a downgrade and no update at all, and
+// a reader who is told only "kept tsx" would wrongly assume the rest of the run went through.
+function format_kept_back_notice(regressions: ReadonlyArray<VersionRegression>): string {
+	const list = regressions.map((regression) => format_regression(regression)).join(', ')
+
+	return [
+		`\n⏮ Keeping ${list} — the newest allowed version is older than the installed one.`,
+		'   The update was rolled back and no dependency changed: while a pin sits above the newest',
+		'   allowed version, the whole tree cannot be resolved. Re-run once the newer release is',
+		'   no longer withheld.',
+	].join('\n')
+}
+
+const latest_regression = {
+	read_direct_dependencies,
+	find_regressions,
+	format_kept_back_notice,
+}
+
+export { latest_regression }
+export type { VersionRegression }

package/scripts/version/latest-scope-cli.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { latest_lane_guard } from './latest-lane-guard'
+import { latest_stamp, type LatestStamp } from './latest-stamp'
+
+// `josh latest:scope` — say whether this run has to update dependencies (joshuafolkken/kit#1215).
+//
+// A command rather than a paragraph in a procedure, for the reason `josh review:level` is a command:
+// a rule an agent applies from memory is a rule an agent can talk itself out of, and this one is
+// argued against every time it is reached — once because the update costs a minute or two, and once
+// because skipping it is invisible until something ships against a stale dependency.
+//
+// It does not share `path_decision` with that command: `josh review:level` decides from the *changed
+// paths*, and this decides from *when the last run happened*. The flag parsing and the printing are the small half;
+// the read of the diff is what that module exists for, and this command never makes one.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh latest:scope [--record] [--json]'
+const JSON_KEY = 'scope'
+const JSON_FLAG = '--json'
+// Written by the `josh latest` chain itself once every step of it has succeeded, so a run that fell
+// over halfway leaves no record and the next one updates again.
+const RECORD_FLAG = '--record'
+const KNOWN_FLAGS: ReadonlySet<string> = new Set([JSON_FLAG, RECORD_FLAG])
+const REQUIRED_SCOPE = 'required'
+const SKIPPED_SCOPE = 'skip'
+const FAILURE_EXIT_CODE = 1
+const NO_STAMP_REASON =
+	'no record of a `josh latest` run in this checkout — update rather than assume the dependencies are current'
+const HOURS_PRECISION = 1
+
+type LatestScope = typeof REQUIRED_SCOPE | typeof SKIPPED_SCOPE
+
+interface Decision {
+	scope: LatestScope
+	reason: string
+}
+
+function format_hours(hours: number): string {
+	return hours.toFixed(HOURS_PRECISION)
+}
+
+// The age and the window both, because the answer is only readable beside the threshold that
+// produced it — a bare "3.2 hours ago" says nothing about why that was enough.
+function describe_stamp(stamp: LatestStamp, max_age_hours: number, is_fresh: boolean): string {
+	const age = format_hours(latest_stamp.hours_since(stamp))
+	const window = format_hours(max_age_hours)
+
+	if (is_fresh) return `last run ${age}h ago, inside the ${window}h window — nothing to update`
+
+	return `last run ${age}h ago, past the ${window}h window — update before implementing`
+}
+
+function decide(): Decision {
+	const stamp = latest_stamp.read_stamp()
+
+	if (stamp === undefined) return { scope: REQUIRED_SCOPE, reason: NO_STAMP_REASON }
+
+	const max_age_hours = latest_stamp.read_max_age_hours()
+	const is_fresh = latest_stamp.is_fresh(stamp, new Date(), max_age_hours)
+
+	return {
+		scope: is_fresh ? SKIPPED_SCOPE : REQUIRED_SCOPE,
+		reason: describe_stamp(stamp, max_age_hours, is_fresh),
+	}
+}
+
+// A lane is answered `skip` before the stamp is even read (joshuafolkken/kit#2135): the stamp is
+// keyed to the project root, so a lane always reads as stale, and every lane would otherwise run its
+// own dependency update. `latest_lane_guard` is the single source of the reason and of the refusal
+// `josh latest` prints.
+function scope_decision(): Decision {
+	if (latest_lane_guard.is_lane()) {
+		return { scope: SKIPPED_SCOPE, reason: latest_lane_guard.LANE_SCOPE_REASON }
+	}
+
+	return decide()
+}
+
+// The answer alone on stdout so `$(pnpm josh latest:scope)` reads it, and the reason on stderr so a
+// person sees why without a shell having to parse around it — the same split `josh review:level`
+// prints in.
+function print_decision(decision: Decision, is_json: boolean): void {
+	if (is_json) {
+		console.info(JSON.stringify({ [JSON_KEY]: decision.scope, reason: decision.reason }))
+
+		return
+	}
+
+	console.info(decision.scope)
+	console.error(decision.reason)
+}
+
+// Nothing on stdout: `--record` is the write half, and a caller capturing `$(pnpm josh
+// latest:scope)` must never be handed a scope by the invocation that was only meant to note a run
+// down. The confirmation goes where the reasons go.
+//
+// **A write that failed is reported and exits zero.** This is the last link of the `josh latest`
+// chain, so throwing here would turn a dependency update that fully succeeded into a red command
+// with a stack trace — over a note nobody reads directly. A failed write leaves no record, and no
+// record answers `required`, so the only consequence is that the next run updates again: the safe
+// direction, and the one the write's own guards were built to fall in.
+function record(): number {
+	try {
+		console.error(`recorded this josh latest run at ${latest_stamp.write_stamp()}`)
+	} catch (error) {
+		console.error(`could not record this josh latest run: ${String(error)}`)
+	}
+
+	return 0
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	if (argv.some((argument) => !KNOWN_FLAGS.has(argument))) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (argv.includes(RECORD_FLAG)) return record()
+
+	print_decision(scope_decision(), argv.includes(JSON_FLAG))
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const latest_scope_cli = {
+	decide,
+	describe_stamp,
+	JSON_KEY,
+	main,
+	NO_STAMP_REASON,
+	RECORD_FLAG,
+	REQUIRED_SCOPE,
+	run,
+	scope_decision,
+	SKIPPED_SCOPE,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { latest_scope_cli }

package/scripts/version/latest-stamp.ts

@@ -0,0 +1,107 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// When `josh latest` last finished in this checkout, and whether that is recent enough to skip
+// (joshuafolkken/kit#1215).
+//
+// `josh latest` is a network-bound chain — pnpm update, every dependency, `ranges`, `pnpm audit` — that
+// took 60–120 seconds at the head of every `fullrun` / `halfrun` and of every child a batch ran, and
+// running it several times in one day barely changes its answer. `queue` and `epicrun` had already
+// hoisted it to the head of a batch by hand; what had no rule at all was a standalone run, which is
+// its own batch head and therefore updated dependencies every single time.
+//
+// **The condition is elapsed time, not judgement.** "The deps are probably still fresh" is a call
+// made under time pressure, and time pressure resolves it toward `skip` exactly when a stale
+// dependency is most likely to matter — the same reason `pnpm josh review:level` takes its answer
+// off a mechanical input rather than out of an agent's head. The record here is that input.
+
+const STAMP_PREFIX = 'josh-latest-stamp-'
+// Twelve hours rather than a day. The issue's own measurement is that a day's worth of runs get
+// nearly the same answer, so the saving between the two settings is marginal, while the exposure is
+// not: a repository that publishes several times a day would spend a whole day on dependencies
+// nobody had re-read. Two windows a day keeps the update at a frequency a person would recognize and
+// still takes it off all but the first run of a working session. `JOSH_LATEST_MAX_AGE_HOURS` moves
+// it in either direction.
+const DEFAULT_MAX_AGE_HOURS = 12
+const MAX_AGE_ENV_VAR = 'JOSH_LATEST_MAX_AGE_HOURS'
+const MS_PER_HOUR = 3_600_000
+
+interface LatestStamp {
+	ran_at: string
+}
+
+// Keyed to the **project**, not to the kit package. A globally installed `josh` has one package
+// directory for every project on the machine, so keying on that would let `josh latest` in one
+// project answer `skip` in another for the rest of the window — skipping its `pnpm audit` too. This
+// is where the record differs from `josh eval`'s, which is genuinely about the package's own files.
+function stamp_path(): string {
+	return stamp_file.stamp_path(STAMP_PREFIX, PROJECT_ROOT)
+}
+
+// Anything that is not a positive finite number falls back to the default, the same reading
+// `JOSH_CI_TIMEOUT_SECONDS` gets: a misspelled value must not silently disable the update, and a
+// zero or negative window would ask for it on every run while looking like a configured choice.
+function read_max_age_hours(environment: NodeJS.ProcessEnv = process.env): number {
+	const raw = Number(environment[MAX_AGE_ENV_VAR])
+
+	return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MAX_AGE_HOURS
+}
+
+// Takes `unknown` rather than the declared field type: the file is written by one command and read
+// by another, so a truncated or hand-edited one has to answer "no record" rather than reach the
+// comparison as a lie.
+function parse_stamp(raw: string): LatestStamp | undefined {
+	const { ran_at } = JSON.parse(raw) as Partial<LatestStamp>
+
+	if (typeof ran_at !== 'string' || Number.isNaN(Date.parse(ran_at))) return undefined
+
+	return { ran_at }
+}
+
+function read_stamp(source: string = stamp_path()): LatestStamp | undefined {
+	const raw = stamp_file.read_stamp_text(source)
+
+	if (raw === undefined) return undefined
+
+	try {
+		return parse_stamp(raw)
+	} catch {
+		return undefined
+	}
+}
+
+function write_stamp(target: string = stamp_path()): string {
+	const stamp: LatestStamp = { ran_at: new Date().toISOString() }
+
+	return stamp_file.write_stamp(target, stamp)
+}
+
+// Negative where the record is in the future — a clock that moved backwards, or a record copied from
+// another machine.
+function hours_since(stamp: LatestStamp, now: Date = new Date()): number {
+	return (now.getTime() - Date.parse(stamp.ran_at)) / MS_PER_HOUR
+}
+
+// **The window is measured in both directions.** A record a little ahead of now is the ordinary
+// small clock skew, and reading it as stale would update on every invocation until the clock caught
+// up — the failure this command exists to remove. A record *far* ahead is a different thing: a stamp
+// written under a badly skewed clock, or copied from another machine, would otherwise answer `skip`
+// for as long as that checkout exists and silently switch dependency updates off. Distance from now
+// is what separates them, so the reading is the absolute one.
+function is_fresh(stamp: LatestStamp, now: Date = new Date(), max_age_hours?: number): boolean {
+	return Math.abs(hours_since(stamp, now)) < (max_age_hours ?? read_max_age_hours())
+}
+
+const latest_stamp = {
+	DEFAULT_MAX_AGE_HOURS,
+	hours_since,
+	is_fresh,
+	MAX_AGE_ENV_VAR,
+	read_max_age_hours,
+	read_stamp,
+	stamp_path,
+	write_stamp,
+}
+
+export type { LatestStamp }
+export { latest_stamp }

package/scripts/version/latest-update.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env tsx
+/**
+ * Filtered `pnpm update --latest` that skips overridden packages and never downgrades.
+ *
+ * Usage: tsx scripts/version/latest-update.ts
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
+import { lockfile_overrides } from '#scripts/overrides/lockfile-overrides'
+import { overrides_files } from '#scripts/overrides/overrides-files'
+import { overrides_check } from '#scripts/overrides/overrides-logic'
+import { execaSync } from 'execa'
+import { latest_regression, type VersionRegression } from './latest-regression'
+import { preinstall_version_update } from './preinstall-version-update'
+
+const PACKAGE_JSON_PATH = 'package.json'
+const LOCKFILE_PATH = 'pnpm-lock.yaml'
+
+interface TreeSnapshot {
+	package_json: string
+	lockfile: string
+}
+
+function run(arguments_: Array<string>): number {
+	const [cmd, ...rest] = arguments_
+	if (cmd === undefined) return 0
+	console.info(`\n▶ ${arguments_.join(' ')}`)
+	const result = execaSync(cmd, rest, { stdio: 'inherit', reject: false })
+
+	return result.exitCode ?? 1
+}
+
+function run_update_stages(stages: Array<Array<string>>): number {
+	for (const stage of stages) {
+		const status = run(stage)
+		if (status !== 0) return status
+	}
+
+	return 0
+}
+
+function take_snapshot(): TreeSnapshot {
+	return {
+		package_json: readFileSync(PACKAGE_JSON_PATH, 'utf8'),
+		lockfile: file_reader.read_file_or_empty(LOCKFILE_PATH),
+	}
+}
+
+// Restoring the files verbatim is the only recovery available: while the newer version is
+// suppressed it is also unresolvable, so putting the old range back and re-installing fails with
+// "the latest release is <older>". The captured lockfile still carries the resolved URL and
+// integrity, which installs fine.
+function restore_snapshot(snapshot: TreeSnapshot): void {
+	writeFileSync(PACKAGE_JSON_PATH, snapshot.package_json)
+	if (snapshot.lockfile.length > 0) writeFileSync(LOCKFILE_PATH, snapshot.lockfile)
+}
+
+function report_kept_back(regressions: ReadonlyArray<VersionRegression>): void {
+	console.info(latest_regression.format_kept_back_notice(regressions))
+}
+
+// The direct-dependency `--latest` bump lifts the package.json ranges; this second, argument-less
+// pass then re-resolves every tier the lockfile carries within those ranges, which is the only stage
+// that reaches the indirect packages a direct-only update leaves pinned at a stale resolution
+// (joshuafolkken/kit#2200). `pnpm update` defaults to depth Infinity, so no flag is needed to reach
+// the whole tree. The re-resolution stage always runs — even when every direct dependency is
+// overridden and the `--latest` stage is absent, the indirect tiers still need re-resolving.
+const PNPM_UPDATE_ALL_TIERS = ['pnpm', 'update']
+
+function build_update_commands(): Array<Array<string>> {
+	const content = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const latest = overrides_check.build_update_command(
+		overrides_files.read_current_overrides(),
+		content,
+	)
+	const stages: Array<Array<string>> = latest === undefined ? [] : [latest]
+
+	return [...stages, [...PNPM_UPDATE_ALL_TIERS]]
+}
+
+interface UpdateOutcome {
+	status: number
+	is_rolled_back: boolean
+}
+
+function find_regressions_after_update(snapshot: TreeSnapshot): Array<VersionRegression> {
+	const after = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+
+	return latest_regression.find_regressions(snapshot.package_json, after)
+}
+
+// Rolling the whole update back rather than retrying without the offender: excluding a package from
+// the update targets does not exclude it from resolution, and while its installed version sits above
+// the newest allowed one that version is unresolvable, so a retry can only fail with
+// ERR_PNPM_NO_MATCHING_VERSION. The choice is genuinely between a downgrade and no update, and this
+// takes no update — the condition is transient, so a later run picks the upgrades up.
+//
+// Exits zero: the tree is left exactly as it was found, nothing is broken, and every workflow that
+// runs `josh latest` in its preamble would otherwise stop for a situation that resolves itself.
+function update_without_downgrading(snapshot: TreeSnapshot): UpdateOutcome {
+	const status = run_update_stages(build_update_commands())
+	if (status !== 0) return { status, is_rolled_back: false }
+
+	const regressions = find_regressions_after_update(snapshot)
+	if (regressions.length === 0) return { status, is_rolled_back: false }
+
+	restore_snapshot(snapshot)
+	report_kept_back(regressions)
+
+	return { status: 0, is_rolled_back: true }
+}
+
+function report_excluded(excluded: ReadonlyArray<string>): void {
+	if (excluded.length === 0) return
+
+	console.info(`\n⏭ Skipping held-back / overridden packages: ${excluded.join(', ')}`)
+}
+
+// Printed unconditionally so the overrides verdict does not depend on an agent remembering which
+// file to open afterwards (kit #740). The summary names the files that were read, so a run with no
+// overrides anywhere is distinguishable from a run that looked in the wrong place.
+function report_overrides(before: Record<string, string>): void {
+	const summary = overrides_check.describe_sources(overrides_files.read_current_sources())
+	const diff = overrides_check.compare(before, overrides_files.read_current_overrides())
+
+	if (!diff.is_changed) {
+		console.info(`\n✔ overrides unchanged (${summary}).`)
+
+		return
+	}
+
+	console.warn(`\n⚠ overrides changed (${summary}) — restore them unless the change was intended:`)
+
+	for (const line of overrides_check.format_diff_lines(diff)) {
+		console.warn(line)
+	}
+}
+
+// The overrides verdict above only says the overrides file is intact; it says nothing about whether
+// the lockfile still honours it. Verifying that here is what turns a push-time CI failure into a
+// local one: `trustLockfile: true` (distributed in pnpm-workspace.yaml) makes
+// `pnpm install --frozen-lockfile` pass locally on the very lockfile CI refuses to install, so no
+// existing local gate covers the case (kit #744). Exits non-zero — the tree as it stands cannot be
+// installed by CI, so continuing the chain would only build on a broken lockfile.
+//
+// Reads the overrides back off disk rather than reusing the pre-update snapshot: CI resolves against
+// the files as committed, so a run that also moved an override must be judged against the new value.
+function report_lockfile_overrides(): void {
+	const lockfile = file_reader.read_file_or_empty(LOCKFILE_PATH)
+	const overrides = overrides_files.read_current_overrides()
+	const mismatches = lockfile_overrides.find_specifier_mismatches(lockfile, overrides)
+
+	if (mismatches.length === 0) return
+
+	console.error(`\n✖ ${LOCKFILE_PATH} no longer honours the overrides — CI cannot install it:`)
+
+	for (const line of lockfile_overrides.format_mismatch_lines(mismatches)) {
+		console.error(line)
+	}
+
+	console.error(`\n  Restore it with: git checkout HEAD -- ${LOCKFILE_PATH} && pnpm install`)
+	process.exitCode = 1
+}
+
+function main(): void {
+	const snapshot = take_snapshot()
+	const overrides = overrides_files.read_current_overrides()
+
+	report_excluded(overrides_check.list_excluded_package_names(overrides))
+
+	const outcome = update_without_downgrading(snapshot)
+
+	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
+	// nothing changed.
+	if (outcome.status === 0 && !outcome.is_rolled_back) {
+		preinstall_version_update.sync(PACKAGE_JSON_PATH)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+const latest_update = {
+	run,
+	main,
+	build_update_commands,
+	run_update_stages,
+	update_without_downgrading,
+	take_snapshot,
+	restore_snapshot,
+	report_lockfile_overrides,
+}
+
+export { latest_update }

package/scripts/version/package-manager-version.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod'
+
+// Capture everything after `pnpm@` verbatim — prerelease identifier AND the
+// `+<hash>` integrity suffix that `corepack use` always writes. pnpm compares
+// `packageManager` and `devEngines.packageManager.version` as raw strings, so
+// dropping the suffix here would make an exact match impossible and the
+// dual-declaration warning permanent (see the alignment comment below).
+const PNPM_PIN_REGEX = /^pnpm@(.+)$/u
+
+// Surgical replacements that touch only the `devEngines.packageManager.version`
+// value, preserving the rest of the file's formatting byte-for-byte. Two key
+// orders are supported because a hand-edited consumer manifest may list either
+// `name` or `version` first.
+const DEV_ENGINES_NAME_FIRST_REGEX = /("name":\s*"pnpm"\s*,\s*"version":\s*")[^"]+(")/u
+const DEV_ENGINES_VERSION_FIRST_REGEX = /("version":\s*")[^"]+("\s*,\s*"name":\s*"pnpm")/u
+
+const optional_version_schema = z.object({ version: z.string().optional() }).optional()
+
+const alignment_read_schema = z.object({
+	packageManager: z.string().optional(),
+	devEngines: z
+		.object({
+			packageManager: optional_version_schema,
+		})
+		.optional(),
+})
+
+type AlignmentManifest = z.infer<typeof alignment_read_schema>
+
+function extract_pnpm_pin(package_manager: string): string | undefined {
+	return PNPM_PIN_REGEX.exec(package_manager)?.[1]
+}
+
+function read_current_version(parsed: AlignmentManifest): string | undefined {
+	return parsed.devEngines?.packageManager?.version
+}
+
+// Return the value that `devEngines.packageManager.version` should adopt, or
+// undefined when there is nothing to align: no `packageManager`, no existing
+// `devEngines.packageManager`, or the two already match.
+function resolve_alignment_target(parsed: AlignmentManifest): string | undefined {
+	if (parsed.packageManager === undefined) return undefined
+	const target = extract_pnpm_pin(parsed.packageManager)
+	const current = read_current_version(parsed)
+	if (current === undefined || current === target) return undefined
+
+	return target
+}
+
+// Surgically set `devEngines.packageManager.version` to `target`, preserving the
+// rest of the file byte-for-byte. Returns the content unchanged when there is no
+// `devEngines.packageManager` block to update.
+// Replacer used with `String#replace` so the captured prefix/suffix are re-emitted
+// around `target` literally — a `$` inside `target` is never read as a replacement
+// pattern.
+function set_development_engines_version(content: string, target: string): string {
+	if (DEV_ENGINES_NAME_FIRST_REGEX.test(content)) {
+		return content.replace(
+			DEV_ENGINES_NAME_FIRST_REGEX,
+			(_match: string, prefix: string, suffix: string) => `${prefix}${target}${suffix}`,
+		)
+	}
+
+	if (DEV_ENGINES_VERSION_FIRST_REGEX.test(content)) {
+		return content.replace(
+			DEV_ENGINES_VERSION_FIRST_REGEX,
+			(_match: string, prefix: string, suffix: string) => `${prefix}${target}${suffix}`,
+		)
+	}
+
+	return content
+}
+
+// Align `devEngines.packageManager.version` with the whole pin carried by the
+// `packageManager` field — integrity suffix included — so pnpm 11.5.0+
+// (pnpm/pnpm#11307) suppresses the "Cannot use both ..." warning. Only a
+// byte-identical value silences it: pnpm 11.18.0 still warns for
+// `pnpm@11.18.0+sha512...` paired with a bare `11.18.0`. The suffix is semver
+// build metadata, which range checks ignore, so corepack and pnpm both still
+// resolve the pin as `11.18.0`.
+function align_development_engines_version(content: string): string {
+	const parsed = alignment_read_schema.parse(JSON.parse(content))
+	const target = resolve_alignment_target(parsed)
+	if (target === undefined) return content
+
+	return set_development_engines_version(content, target)
+}
+
+const package_manager_version = {
+	extract_pnpm_pin,
+	align_development_engines_version,
+	set_development_engines_version,
+}
+
+export { package_manager_version }

package/scripts/version/parse-json.ts

@@ -0,0 +1,13 @@
+// Parse JSON without throwing: returns the parsed value, or undefined when the input is not valid
+// JSON. Single source for the version commands that read package.json / CLI output and hand the
+// result to a schema's `safeParse` (running-binary, version-targets, effective-upstream), so the
+// permissive-parse behavior is defined once rather than re-cloned per reader.
+function safe_json_parse(raw: string): unknown {
+	try {
+		return JSON.parse(raw)
+	} catch {
+		return undefined
+	}
+}
+
+export { safe_json_parse }