@selvajs/cli 4.8.0-beta.10 → 4.8.0-beta.12

package/src/commands/migrate.js

@@ -1,5 +1,5 @@
-// Migrate deployment to current layout: rewrite package.json (drop legacy
-// provider packages), remove stale selva.config.js, update ecosystem.config.cjs.
+// Migrates a deployment to the current layout: rewrites package.json (drops legacy
+// provider packages), removes stale selva.config.js, updates ecosystem.config.cjs.
 // Idempotent; mirrors update's lifecycle (stop/mutate/start with rollback on failure).
 
 import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from 'node:fs';
@@ -13,32 +13,33 @@ import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
 	DEPENDENCIES,
-	LEGACY_DEPENDENCIES
+	isFloatingPin,
+	LEGACY_DEPENDENCIES,
+	npmDistTagVersion,
+	OVERRIDES,
+	resolveSelvaPins,
+	SELVA_PACKAGES
 } from '../deployment-package.js';
 import { APP_NAME, runPm2 } from './pm2.js';
 
-/**
- * Where `migrate` parks the old node_modules while npm installs the new one.
- * Left behind only if the process is killed mid-migration — `detectDrift`
- * reports it, because a stray copy of the dependency tree is both confusing and
- * large enough to matter on a small VM.
- */
+// Where migrate parks the old node_modules while npm installs the new one.
+// Left behind only if the process is killed mid-migration; `selva doctor`
+// flags a surviving stash as an interrupted migration.
 export const NODE_MODULES_STASH = 'node_modules.selva-migrate-bak';
 
-/**
- * @param {object} [deps] Seams for tests. The rollback path destroys and
- *   restores a real dependency tree, so it has to be exercised against a real
- *   directory — but not against a real npm or a real pm2 daemon.
- */
+// `deps` are seams for tests: the rollback path destroys and restores a real
+// dependency tree, so it has to run against a real directory — but not against
+// a real npm or pm2 daemon.
 export async function runMigrate(
 	_argv,
 	{
 		dir: injectedDir,
-		// --prefer-online bypasses the stale-packument trap: npm can otherwise
-		// resolve a cached packument that predates the release being migrated to.
+		// --prefer-online: npm can otherwise resolve a cached packument that
+		// predates the release being migrated to.
 		install = (cwd) => execSync('npm install --prefer-online', { cwd, stdio: 'pipe' }),
 		confirm = (message) => p.confirm({ message, initialValue: true }),
-		pm2 = runPm2
+		pm2 = runPm2,
+		resolveVersion = npmDistTagVersion
 	} = {}
 ) {
 	const dir = injectedDir ?? resolveDeploymentDir();
@@ -53,11 +54,9 @@ export async function runMigrate(
 	}
 
 	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
-	const target = buildTargetPackageJson(before);
+	const { pkg: target, notes: pinNotes } = buildTargetPackageJson(before, resolveVersion);
 	const pkgDiff = diffPackageJson(before, target);
 
-	// Side-files: selva.config.js (now unused) and ecosystem.config.cjs
-	// (must point at @selvajs/selva, not @selvajs/runtime).
 	const configPath = join(dir, 'selva.config.js');
 	const hasStaleConfig = existsSync(configPath);
 
@@ -65,9 +64,9 @@ export async function runMigrate(
 	const ecoHasStaleRuntime =
 		existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime');
 
-	// Deprecated env keys. The server reads the old names for one more minor
-	// version, so this is a warning today and a silent fallback to defaults once
-	// that shim goes — rewriting now is what keeps a tuned value tuned.
+	// The server drops its read-old-name shim after one minor version, so
+	// rewriting now is what keeps a tuned value tuned instead of silently
+	// reverting to defaults later.
 	const envPath = join(dir, '.env');
 	const envBefore = existsSync(envPath) ? readFileSync(envPath, 'utf8') : null;
 	const envRename = envBefore
@@ -100,15 +99,33 @@ export async function runMigrate(
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
 
+	// The diff shows the pin that will be written; these explain why it is that
+	// pin. A preserved beta and a pin that couldn't be resolved both look like
+	// "no change" in the diff, and the second one is a stale pin, not a stable one.
+	for (const note of pinNotes) {
+		if (note.kind === 'prerelease') {
+			p.log.info(
+				`${note.name} stays on ${note.pin} — a prerelease pin is kept, since \`latest\` ` +
+					`means newest stable and would move this deployment backwards.`
+			);
+		} else {
+			p.log.warn(
+				`Could not resolve the current version of ${note.name} (${note.reason}). ` +
+					`Keeping ${JSON.stringify(note.pin ?? null)}; re-run migrate when the registry is reachable.`
+			);
+		}
+	}
+
 	const confirmed = await confirm('Apply these changes, reinstall, and restart?');
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
 		return;
 	}
 
-	// Stop pm2 before npm rewrites (SvelteKit lazy-loads chunks; see update command).
+	// Stop pm2 before npm rewrites — SvelteKit lazy-loads chunks, so a rewrite
+	// under a running server serves a broken page (same reason `update` stops first).
 	// A legacy deployment may predate the local-pm2 layout, so a missing binary
-	// is not fatal here — there is nothing running for us to stop.
+	// isn't fatal here: there's nothing running for us to stop.
 	try {
 		const stopStatus = pm2(dir, ['stop', APP_NAME], { inherit: false });
 		if (stopStatus !== 0) {
@@ -118,7 +135,6 @@ export async function runMigrate(
 		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
-	// Back up for rollback on npm-install failure.
 	const bakPath = pkgPath + '.bak';
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
@@ -130,7 +146,7 @@ export async function runMigrate(
 
 	if (ecoHasStaleRuntime) {
 		copyFileSync(ecoPath, ecoPath + '.bak');
-		// Rewrite @selvajs/runtime → @selvajs/selva only (preserve customizations).
+		// Text substitution, not regeneration, so any operator customizations to the file survive.
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
 			'@selvajs/selva'
@@ -143,11 +159,11 @@ export async function runMigrate(
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
-	// A clean install is required — a legacy lockfile pins the old package set
-	// across a major bump. But node_modules is also where pm2 lives, and the
-	// rollback below has to restart the app, so deleting it outright leaves a
-	// failed migration with no way back up. Rename instead: atomic, keeps the
-	// .bin symlinks intact, and restorable until the install succeeds.
+	// A legacy lockfile pins the old package set across a major bump, so this needs
+	// a clean install. But node_modules is also where pm2 lives, and rollback has to
+	// restart the app — deleting it outright would leave a failed migration with no
+	// way back up. Rename instead: atomic, keeps .bin symlinks intact, restorable
+	// until the install succeeds.
 	const nodeModules = join(dir, 'node_modules');
 	const nodeModulesBak = join(dir, NODE_MODULES_STASH);
 	const lockPath = join(dir, 'package-lock.json');
@@ -176,8 +192,8 @@ export async function runMigrate(
 			copyFileSync(envPath + '.bak', envPath);
 		}
 
-		// Restore the dependency tree the app was running on. A half-installed
-		// node_modules from the failed attempt is worse than the old one.
+		// A half-installed node_modules from the failed attempt is worse than the old
+		// one, so clear it before restoring the stash.
 		rmSync(nodeModules, { recursive: true, force: true });
 		if (existsSync(nodeModulesBak)) renameSync(nodeModulesBak, nodeModules);
 		if (lockBak !== null) writeFileSync(lockPath, lockBak, 'utf8');
@@ -187,6 +203,10 @@ export async function runMigrate(
 		process.exit(1);
 	}
 
+	// Migration itself already succeeded at this point, so a failed pm2 start is reported
+	// but doesn't exit non-zero or trigger rollback — the on-disk state is fine, only the
+	// running process isn't. Contrast restartAfterRollback, which does exit 1: that path
+	// runs after a rollback, where a failed restart leaves nothing serving traffic at all.
 	let status;
 	try {
 		status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
@@ -194,6 +214,16 @@ export async function runMigrate(
 		status = 1;
 		p.log.error(`Could not invoke pm2: ${err instanceof Error ? err.message : err}`);
 	}
+	// A pin change means the just-installed pm2 CLI and the still-running
+	// daemon are now different versions. That's the repairable skew direction
+	// (daemon older), but it stays skewed until the operator acts — say so
+	// here, once, instead of letting doctor nag forever. Deliberately NOT
+	// automated: `pm2 update` recycles the daemon, and doing that unattended
+	// inside a migration converts a mid-flight failure into an outage (see
+	// plans/fixes/host-prerequisites-and-pm2-audit.md).
+	const pm2Notice = buildPm2UpgradeNotice(before.dependencies?.pm2, target.dependencies.pm2);
+	if (pm2Notice) p.log.warn(pm2Notice);
+
 	const backupHints = ['package.json.bak'];
 	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
 	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
@@ -212,14 +242,9 @@ export async function runMigrate(
 	}
 }
 
-/**
- * Bring the app back up after a failed migration.
- *
- * Never throws: the migration is already aborting, and an exception here would
- * replace the rollback's diagnosis with a stack trace. A failure to restart is
- * the operator's problem to act on, so it must be stated, not swallowed — the
- * old code returned a bare 1 and printed nothing.
- */
+// Never throws: the migration is already aborting, and an exception here would
+// replace the rollback's diagnosis with a stack trace. A failure to restart is
+// the operator's problem to act on, so it gets logged, not swallowed.
 function restartAfterRollback(dir, pm2 = runPm2) {
 	try {
 		const status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
@@ -239,12 +264,15 @@ function restartAfterRollback(dir, pm2 = runPm2) {
 	}
 }
 
-function buildTargetPackageJson(current) {
-	return buildDeploymentPackageJson({
+function buildTargetPackageJson(current, resolveVersion = npmDistTagVersion) {
+	const { pins, notes } = resolveSelvaPins(current.dependencies, resolveVersion);
+	const pkg = buildDeploymentPackageJson({
 		name: current.name ?? 'selva-deployment',
 		version: current.version ?? '0.1.0',
-		engines: current.engines
+		engines: current.engines,
+		dependencies: pins
 	});
+	return { pkg, notes };
 }
 
 // Format package.json diff for confirmation prompt (concise, not full diff).
@@ -263,6 +291,19 @@ function diffPackageJson(before, after) {
 		else if (a !== b) lines.push(`${pc.yellow('~')} ${name} ${pc.dim(a + ' → ' + b)}`);
 	}
 
+	// Without this section, an overrides-only change reads as "already on the
+	// current layout" and the security shim never reaches existing deployments.
+	const beforeOverrides = before.overrides ?? {};
+	const afterOverrides = after.overrides ?? {};
+	const allOverrides = new Set([...Object.keys(beforeOverrides), ...Object.keys(afterOverrides)]);
+	for (const name of [...allOverrides].sort()) {
+		const a = beforeOverrides[name];
+		const b = afterOverrides[name];
+		if (a && !b) lines.push(`${pc.red('-')} overrides.${name} ${pc.dim(a)}`);
+		else if (!a && b) lines.push(`${pc.green('+')} overrides.${name} ${pc.dim(b)}`);
+		else if (a !== b) lines.push(`${pc.yellow('~')} overrides.${name} ${pc.dim(a + ' → ' + b)}`);
+	}
+
 	const beforeScripts = before.scripts ?? {};
 	const afterScripts = after.scripts ?? {};
 	const allScripts = new Set([...Object.keys(beforeScripts), ...Object.keys(afterScripts)]);
@@ -276,9 +317,9 @@ function diffPackageJson(before, after) {
 		}
 	}
 
-	// Anything outside the canonical set is discarded by the rewrite.
-	// devDependencies and description used to vanish without appearing here, so
-	// the operator confirmed a change they were never shown.
+	// Anything outside the canonical set is discarded by the rewrite — show it here
+	// too, or the operator confirms a change (e.g. losing devDependencies) they
+	// never saw.
 	for (const key of Object.keys(before).sort()) {
 		if (CANONICAL_FIELDS.has(key)) continue;
 		lines.push(`${pc.red('-')} ${key} ${pc.dim(summarize(before[key]))}`);
@@ -307,6 +348,37 @@ export function detectDrift(pkgJson, dir) {
 		if (!deps[name]) reasons.push(`${name} is missing`);
 	}
 
+	// pm2 is the one dependency pinned exactly, so a version difference is drift
+	// rather than an operator preference. Presence alone was checked above and
+	// isn't enough: a deployment scaffolded against an older CLI keeps its old
+	// pm2 forever, which is how the pin reached a two-major gap unnoticed.
+	if (deps.pm2 && deps.pm2 !== DEPENDENCIES.pm2) {
+		reasons.push(`pm2 is pinned to ${deps.pm2} (current scaffold pins ${DEPENDENCIES.pm2})`);
+	}
+
+	// A stored dist-tag re-resolves on every `npm install`, so the deployment
+	// follows the tag instead of a version an operator chose. Worse on a
+	// prerelease line, where `latest` points at the older stable release and the
+	// "upgrade" is a downgrade. Migrate wrote these before it learned to resolve
+	// tags, so existing deployments carry one and nothing else reports it.
+	for (const name of SELVA_PACKAGES) {
+		if (deps[name] && isFloatingPin(deps[name])) {
+			reasons.push(
+				`${name} is pinned to the floating tag ${JSON.stringify(deps[name])} ` +
+					`(re-resolves on every install; migrate writes a concrete version)`
+			);
+		}
+	}
+
+	// Overrides are security shims for vulnerable transitive deps — a
+	// deployment without them installs the vulnerable version on its next
+	// `npm install`, silently.
+	for (const [name, version] of Object.entries(OVERRIDES)) {
+		if (pkgJson?.overrides?.[name] !== version) {
+			reasons.push(`overrides.${name} is missing or outdated (security shim, expects ${version})`);
+		}
+	}
+
 	if (dir) {
 		const configPath = join(dir, 'selva.config.js');
 		if (existsSync(configPath)) {
@@ -328,4 +400,26 @@ export function detectDrift(pkgJson, dir) {
 	return reasons;
 }
 
+// Null when the pin didn't change. Exported for its test — the wording is the
+// operator's only pointer to finish the upgrade.
+export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
+	if (!beforeVersion || beforeVersion === afterVersion) return null;
+	return [
+		`pm2 was upgraded ${beforeVersion} → ${afterVersion}, but the running pm2 daemon is`,
+		`still the old version. Finish the upgrade (brief restart of managed processes):`,
+		``,
+		`  npx pm2 update`,
+		`  npx pm2 list          # ${APP_NAME} must be listed and 'online' before the next step`,
+		`  npx pm2 save`,
+		``,
+		`Do not run \`pm2 save\` until the list looks right. \`pm2 update\` empties the`,
+		`process table before restoring it, so saving a failed restore overwrites`,
+		`~/.pm2/dump.pm2 — the only record of what to bring back. If the list is empty,`,
+		`recover with \`npx pm2 resurrect\`, or \`npx pm2 start ecosystem.config.cjs\`.`,
+		``,
+		`If doctor reports a pm2 outside this deployment (global or apt install), follow`,
+		`the full procedure in the docs instead: self-hosting → deployment → prerequisites.`
+	].join('\n');
+}
+
 export { buildTargetPackageJson, diffPackageJson };

package/src/commands/pm2.js

@@ -1,6 +1,6 @@
-// Thin wrappers around PM2 commands: always pass --update-env (ignore edits),
-// resolve to deployment-local pm2 (avoid daemon version skew with global install),
-// and resync daemon before state changes.
+// Thin wrappers around PM2 commands: resolve to the deployment-local pm2, resync
+// the daemon before state changes, and pass --update-env on restart so edits to
+// .env actually take effect.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -11,7 +11,6 @@ import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 export const APP_NAME = 'selva-compute';
 
-// Resolve to deployment-local pm2 (no global fallback; prevents version skew).
 export function pm2Bin(dir) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	if (!existsSync(local)) {
@@ -25,11 +24,10 @@ export function pm2Bin(dir) {
 	return local;
 }
 
-// Parse the two versions pm2 prints alongside its out-of-date warning:
+// Parses the two versions pm2 prints alongside its out-of-date warning:
 //   In memory PM2 version: 6.0.14
 //   Local PM2 version: 5.4.3
-// Returns nulls when the shape changes — callers then fall back to resyncing,
-// which is the pre-existing behaviour.
+// Returns nulls when the shape doesn't match, so callers fall back to resyncing.
 export function parsePm2Skew(output) {
 	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
 	const clean = output.replace(/\[[0-9;]*m/g, '');
@@ -38,12 +36,10 @@ export function parsePm2Skew(output) {
 	return { daemon: daemon?.[1] ?? null, local: local?.[1] ?? null };
 }
 
-/**
- * True when the running daemon is newer than the deployment-local pm2 — i.e. a
- * foreign global pm2 owns it. `pm2 update` cannot fix that direction: it
- * downgrades the daemon and hands it a dump from a newer version, which drops
- * the process table so selva-compute is never re-registered (issue #118).
- */
+// True when the running daemon is newer than the deployment-local pm2 — i.e. a
+// foreign global pm2 owns it. `pm2 update` can't fix that direction: it would
+// downgrade the daemon and hand it a dump from a newer version, dropping the
+// process table so selva-compute never gets re-registered.
 export function daemonOutranksCli(daemon, local) {
 	if (!daemon || !local) return false;
 	const [a, b] = [daemon.split('.').map(Number), local.split('.').map(Number)];
@@ -54,7 +50,6 @@ export function daemonOutranksCli(daemon, local) {
 	return false;
 }
 
-// Check for daemon/CLI version mismatch; run `pm2 update` only when it can help.
 function ensurePm2InSync(dir) {
 	const bin = pm2Bin(dir);
 	const probe = spawnSync(bin, ['ping'], {
@@ -92,13 +87,9 @@ function ensurePm2InSync(dir) {
 	}
 }
 
-/**
- * Run the deployment-local pm2.
- *
- * `bin` overrides where pm2 is resolved from — `selva migrate` wipes
- * node_modules mid-flight and passes the binary it stashed beforehand, because
- * resolving from the deployment at that moment would find nothing.
- */
+// `bin` lets a caller pass an already-resolved pm2 path instead of resolving
+// fresh from `dir` — needed when node_modules won't exist at call time (e.g.
+// `selva migrate` wipes it mid-flight and passes the binary it stashed first).
 export function runPm2(dir, args, { inherit = true, bin = pm2Bin(dir) } = {}) {
 	const result = spawnSync(bin, args, {
 		cwd: dir,

package/src/deployment-package.js

@@ -3,6 +3,11 @@
 // than in either command — two copies drifted once already, and the pm2 pin is
 // exactly the field where a silent difference costs the most.
 
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 /**
  * pm2 is pinned exactly, not caret-ranged.
  *
@@ -10,8 +15,29 @@
  * two deployments installed a week apart resolve differently, and the newer one
  * silently adopts the daemon the older one started — the skew `ensurePm2InSync`
  * has to detect and, in the daemon-is-newer direction, cannot repair (#118).
+ *
+ * Read from this package's own devDependencies rather than written here as a
+ * literal. Dependabot scans manifests, not source, so a literal is invisible to
+ * it — this pin sat on 5.4.3 while upstream reached 7.x, which is precisely the
+ * drift operators point at when they argue for distro packages instead.
+ * `checkPinIsExact` keeps the manifest entry from being loosened to a range.
  */
-const PM2_VERSION = '5.4.3';
+const PM2_VERSION = readPinnedPm2Version();
+
+function readPinnedPm2Version() {
+	const manifest = JSON.parse(
+		readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+	);
+	const pinned = manifest.devDependencies?.pm2;
+	if (!pinned || !/^\d+\.\d+\.\d+$/.test(pinned)) {
+		throw new Error(
+			`@selvajs/cli devDependencies.pm2 must be an exact version, got ${JSON.stringify(pinned)}. ` +
+				`Every deployment this CLI scaffolds inherits it, and a range there lets two ` +
+				`installs resolve different pm2s that then fight over one daemon.`
+		);
+	}
+	return pinned;
+}
 
 const SCRIPTS = {
 	start: 'selva start',
@@ -26,6 +52,11 @@ const SCRIPTS = {
  * Packages a deployment carries. Providers are bundled into `@selvajs/selva`;
  * the CLI is a dependency so `npm run start` resolves the `selva` bin locally
  * instead of relying on a global install.
+ *
+ * The `latest` entries are what `create` resolves at scaffold time, never what
+ * gets written: `resolveSelvaPins` turns them into concrete versions. A stored
+ * `"latest"` re-resolves on every `npm install`, so the deployment follows the
+ * dist-tag forever and can change under the operator with no migrate at all.
  */
 const DEPENDENCIES = {
 	'@selvajs/cli': 'latest',
@@ -33,6 +64,49 @@ const DEPENDENCIES = {
 	pm2: PM2_VERSION
 };
 
+/** The `@selvajs/*` packages whose pin belongs to the operator, not the scaffold. */
+export const SELVA_PACKAGES = ['@selvajs/cli', '@selvajs/selva'];
+
+/**
+ * True for a pin that names no version — a dist-tag (`latest`, `beta`) or the
+ * empty-ish values npm also accepts (`*`, `""`). These are the pins that move
+ * on their own, which is what makes them unfit to store.
+ */
+export function isFloatingPin(pin) {
+	if (typeof pin !== 'string') return true;
+	const trimmed = pin.trim();
+	if (trimmed === '' || trimmed === '*' || trimmed === 'x') return true;
+	// A range still names versions; only a bare tag has no digits at all.
+	return !/\d/.test(trimmed);
+}
+
+/**
+ * True for a pin on a prerelease line (`^4.8.0-beta.11`).
+ *
+ * These are preserved across a migration. An operator on a beta channel chose
+ * it, and npm's `latest` tag points at the newest *stable* release — so
+ * resolving their pin through `latest` is a downgrade that reads as an upgrade
+ * in the confirmation diff.
+ */
+export function isPrereleasePin(pin) {
+	return typeof pin === 'string' && /\d+\.\d+\.\d+-/.test(pin);
+}
+
+/**
+ * npm `overrides` forced onto every deployment — security patches for
+ * transitive deps whose direct parent hasn't picked up the fix yet. Each entry
+ * is a temporary shim: remove it once the parent ships the fixed version on
+ * its own (the override then matches what would install anyway, so removal is
+ * cleanup, never urgent).
+ *
+ * js-yaml: pm2 <= 7.0.3 pins 4.3.0, which carries the quadratic-complexity
+ * DoS advisories (GHSA-5p4m-2wfm-xmqj and friends); the fix landed in 4.3.1.
+ * Drop when pm2's own js-yaml dependency reaches >= 4.3.1.
+ */
+export const OVERRIDES = {
+	'js-yaml': '^4.3.1'
+};
+
 /**
  * Legacy `@selvajs/*` packages that a deployment may still list. Each was
  * either renamed or folded into `@selvajs/selva`; `migrate` drops them and
@@ -60,20 +134,98 @@ export const LEGACY_DEPENDENCIES = {
  * deliberately, and dropping it removes a guard whose absence shows up only
  * under real traffic (issue #176). Everything else a migration discards is
  * listed by `diffPackageJson` before the operator confirms.
+ *
+ * `dependencies` is the second exception, for the same reason: a version pin is
+ * an operator choice too. `migrate` passes the resolved `@selvajs/*` pins in
+ * here; a fresh scaffold passes none and inherits the defaults.
  */
-export function buildDeploymentPackageJson({ name, version = '0.1.0', engines }) {
+export function buildDeploymentPackageJson({ name, version = '0.1.0', engines, dependencies }) {
 	const pkg = {
 		name: sanitizePackageName(name),
 		version,
 		private: true,
 		type: 'module',
 		scripts: { ...SCRIPTS },
-		dependencies: { ...DEPENDENCIES }
+		dependencies: { ...DEPENDENCIES, ...dependencies },
+		overrides: { ...OVERRIDES }
 	};
 	if (engines && typeof engines === 'object') pkg.engines = { ...engines };
 	return pkg;
 }
 
+/**
+ * Ask npm what a dist-tag currently points at. Kept beside the pin logic it
+ * serves, and injected rather than called directly so tests never hit the
+ * network.
+ */
+export function npmDistTagVersion(name, tag) {
+	const out = execSync(`npm view ${name}@${tag} version`, {
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe']
+	});
+	const version = String(out).trim().split('\n').pop()?.trim();
+	if (!version || !/^\d+\.\d+\.\d+/.test(version)) {
+		throw new Error(`npm view returned no usable version for ${name}@${tag}`);
+	}
+	return version;
+}
+
+/**
+ * Decide the `@selvajs/*` pins a migration should write.
+ *
+ * Two rules, both aimed at the same failure: a migration silently moving a
+ * deployment to a version the operator didn't ask for.
+ *
+ *   - A prerelease pin is kept as-is. `latest` means newest stable, so
+ *     resolving a beta pin through it walks the deployment backwards.
+ *   - Anything else resolves to a concrete version via `resolveVersion`, so
+ *     `"latest"` never reaches disk and the diff can show what it resolved to.
+ *
+ * `resolveVersion` hits the network. When it fails — offline, registry down, a
+ * package with no such tag — the existing pin is kept and the reason returned,
+ * so migrate can report it rather than inventing a version or aborting a
+ * migration whose other half (layout, overrides, env renames) is still valid.
+ */
+export function resolveSelvaPins(currentDeps, resolveVersion) {
+	const pins = {};
+	const notes = [];
+
+	for (const name of SELVA_PACKAGES) {
+		const current = currentDeps?.[name];
+
+		if (isPrereleasePin(current)) {
+			pins[name] = current;
+			notes.push({ name, kind: 'prerelease', pin: current });
+			continue;
+		}
+
+		let resolved = null;
+		try {
+			resolved = resolveVersion(name, 'latest');
+		} catch (err) {
+			notes.push({ name, kind: 'unresolved', pin: current, reason: err?.message ?? String(err) });
+		}
+
+		if (resolved) {
+			pins[name] = `^${resolved}`;
+			continue;
+		}
+
+		// Nothing resolvable and nothing worth keeping — fall back to the tag so
+		// the install still succeeds. Rare: offline *and* a floating pin.
+		if (isFloatingPin(current)) {
+			pins[name] = DEPENDENCIES[name];
+			if (!notes.some((n) => n.name === name)) {
+				notes.push({ name, kind: 'unresolved', pin: current, reason: 'no version returned' });
+			}
+		} else {
+			pins[name] = current;
+		}
+	}
+
+	return { pins, notes };
+}
+
 /**
  * Top-level keys the canonical package.json defines. Anything outside this set
  * that an operator added is dropped by `migrate` — `diffPackageJson` reports
@@ -86,11 +238,11 @@ export const CANONICAL_FIELDS = new Set([
 	'type',
 	'scripts',
 	'dependencies',
+	'overrides',
 	'engines'
 ]);
 
 export function sanitizePackageName(name) {
-	// npm package names: lowercase, no spaces, limited punctuation.
 	return (
 		String(name ?? '')
 			.toLowerCase()