@selvajs/cli 4.8.0-beta.8 → 4.8.0

package/src/commands/init.js

@@ -1,20 +1,14 @@
-// `selva init` — reconfigure an existing deployment.
-//
-// Differences from `create`:
-//   • Reads current .env values; uses them as prompt defaults.
-//   • Never regenerates SELVA_HMAC_KEY / SELVA_AT_REST_KEY if they're set.
-//     Rotating those invalidates sessions and at-rest encryption — that's
-//     `selva keys rotate`'s job, not init's.
-//   • Doesn't touch package.json or run npm install.
+// `selva init` — reconfigures an existing deployment. Unlike `create`, it reads
+// the current .env as prompt defaults and never touches package.json or runs
+// npm install.
 
-import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { collectConfig } from '../prompts.js';
 import { readEnvFile, writeEnvFile } from '../env.js';
 import { generateKey } from '../secrets.js';
-import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 export async function runInit() {
 	const dir = resolveDeploymentDir();
@@ -24,10 +18,10 @@ export async function runInit() {
 	const current = readEnvFile(envPath);
 	const values = await collectConfig({ defaults: current, mode: 'init' });
 
-	// Preserve secrets. The only safe time to generate them is at install
-	// time (no sessions to invalidate, no encrypted data to lose). If the
-	// existing .env doesn't have them — which can happen if a previous
-	// scaffold bailed mid-flight — generate now and warn.
+	// Never regenerate an existing key: rotating SELVA_HMAC_KEY or
+	// SELVA_AT_REST_KEY invalidates sessions and at-rest encryption — that's
+	// `selva keys rotate`'s job, not init's. Missing keys (a scaffold that
+	// bailed mid-flight) are the one case it's safe to generate here.
 	if (
 		current.SELVA_HMAC_KEY &&
 		current.SELVA_HMAC_KEY !== 'replace-this-with-a-random-32-byte-hex-key'
@@ -48,24 +42,11 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	// Use whatever .env.example shipped with the installed runtime as the
-	// canonical template. Falls back to the current .env if the runtime
-	// templates aren't present (shouldn't happen post-install).
-	const templatePath = join(
-		dir,
-		'node_modules',
-		'@selvajs',
-		'selva',
-		'templates',
-		'.env.example'
-	);
-	const template = existsSync(templatePath)
-		? readFileSync(templatePath, 'utf8')
-		: existsSync(envPath)
-			? readFileSync(envPath, 'utf8')
-			: '';
-
-	writeEnvFile(envPath, template, values);
+	// A values-only rewrite drops anything it isn't handed, and the prompts cover
+	// only the vars they ask about — every tuned knob the operator set by hand
+	// (BODY_SIZE_LIMIT, COMPUTE_*, LOG_LEVEL, …) lives outside that set. Carry
+	// the existing file forward and let the prompt answers win on top.
+	writeEnvFile(envPath, readEnvTemplate(dir), { ...current, ...values });
 
 	p.outro(
 		[

package/src/commands/keys.js

@@ -1,12 +1,11 @@
 // Rotate SELVA_HMAC_KEY or SELVA_AT_REST_KEY; requires explicit confirm (blast radius in TARGETS).
 
-import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readEnvFile, writeEnvFile } from '../env.js';
 import { generateKey } from '../secrets.js';
-import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 const TARGETS = {
 	hmac: {
@@ -57,19 +56,7 @@ export async function runKeysRotate(argv) {
 	const fresh = generateKey();
 	current[envVar] = fresh;
 
-	const templatePath = join(
-		dir,
-		'node_modules',
-		'@selvajs',
-		'selva',
-		'templates',
-		'.env.example'
-	);
-	const template = existsSync(templatePath)
-		? readFileSync(templatePath, 'utf8')
-		: readFileSync(envPath, 'utf8');
-
-	writeEnvFile(envPath, template, current);
+	writeEnvFile(envPath, readEnvTemplate(dir), current);
 
 	p.outro(
 		[

package/src/commands/migrate.js

@@ -1,43 +1,116 @@
-// 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 } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
-import { spawnSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { renameEnvKeys, RENAMED_ENV_VARS } from '../env.js';
+import {
+	buildDeploymentPackageJson,
+	CANONICAL_FIELDS,
+	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; `selva doctor`
+// flags a surviving stash as an interrupted migration.
+export const NODE_MODULES_STASH = 'node_modules.selva-migrate-bak';
+
+// Matches the backups migrate writes: `.env.2026-08-10T05-43-12.bak`. Anchored
+// at both ends so an operator's own `notes.bak` is never picked up as ours.
+export const BACKUP_PATTERN = /\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2})\.bak$/;
+
+/**
+ * Colons are illegal in Windows filenames, so this is ISO with `:` swapped for
+ * `-` and the fractional seconds dropped: 2026-08-10T05-43-12.
+ */
+export function backupStamp(now = new Date()) {
+	return now
+		.toISOString()
+		.replace(/\.\d+Z$/, '')
+		.replace(/:/g, '-');
+}
+
+/**
+ * A migration used to write `package.json.bak` at a fixed path, so the second
+ * substantive migration overwrote the first's copy — and since each run backs
+ * up the *current* file, that left the operator's original config recoverable
+ * from nowhere (#184). One stamp per run keeps a whole migration's backups
+ * together and makes them sortable.
+ *
+ * Not auto-pruned here: deleting an operator's only copy of their old config is
+ * worse than a few small files accumulating. `selva doctor` reports aged ones
+ * with a `--fix`, which keeps the decision theirs.
+ */
+export function backupPathFor(filePath, stamp) {
+	return `${filePath}.${stamp}.bak`;
+}
+
+// Old enough that the migration which wrote it is long settled.
+export const BACKUP_AGE_DAYS = 30;
+
+/**
+ * Split migration backups into what to keep and what `doctor --fix` may delete.
+ *
+ * The newest run's backups are always kept, however old they are — on a
+ * deployment that migrates once a year, age alone would delete the only copy of
+ * the pre-migration config, which is the whole point of keeping them. So the
+ * rule is: keep the newest stamp, offer to delete stamps older than
+ * `BACKUP_AGE_DAYS`.
+ *
+ * `names` are basenames; the stamp is read from the filename rather than mtime,
+ * which a copy or restore would reset.
+ */
+export function classifyBackups(names, now = new Date(), maxAgeDays = BACKUP_AGE_DAYS) {
+	const found = [];
+	for (const name of names) {
+		const m = BACKUP_PATTERN.exec(name);
+		if (m) found.push({ name, stamp: m[1] });
+	}
+	if (found.length === 0) return { keep: [], aged: [], newest: null };
+
+	// Stamps are fixed-width and zero-padded, so lexical order is chronological.
+	const newest = found.reduce((a, b) => (b.stamp > a.stamp ? b : a)).stamp;
+	const cutoff = now.getTime() - maxAgeDays * 24 * 60 * 60 * 1000;
+
+	const keep = [];
+	const aged = [];
+	for (const entry of found) {
+		// `2026-08-10T05-43-12` → parseable by restoring the colons.
+		const at = Date.parse(entry.stamp.replace(/T(\d{2})-(\d{2})-(\d{2})$/, 'T$1:$2:$3') + 'Z');
+		if (entry.stamp === newest || !Number.isFinite(at) || at >= cutoff) keep.push(entry.name);
+		else aged.push(entry.name);
+	}
+	return { keep, aged, newest };
+}
 
-const APP_NAME = 'selva-compute';
-
-// Packages we own. Everything in this set is rewritten wholesale by migrate;
-// anything outside it (operator's own deps) gets dropped, which is the
-// explicit design choice — operators with custom deps should fork the
-// template rather than hand-patch the deployment package.json.
-const SELVA_DEPS = new Set([
-	'@selvajs/cli',
-	'@selvajs/selva',
-	'@selvajs/runtime', // legacy — removed during migrate
-	'@selvajs/platform', // legacy — bundled into @selvajs/selva
-	'@selvajs/local-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/supabase-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/header-auth-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/create' // legacy CLI — removed during migrate
-]);
-
-const CANONICAL_SCRIPTS = {
-	start: 'selva start',
-	stop: 'selva stop',
-	restart: 'selva restart',
-	logs: 'selva logs',
-	doctor: 'selva doctor',
-	update: 'selva update'
-};
-
-export async function runMigrate() {
-	const dir = resolveDeploymentDir();
+// `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: 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,
+		resolveVersion = npmDistTagVersion
+	} = {}
+) {
+	const dir = injectedDir ?? resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
 	p.intro(pc.bgCyan(pc.black(' selva migrate ')));
@@ -49,11 +122,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);
 
@@ -61,9 +132,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
@@ -96,34 +167,61 @@ export async function runMigrate() {
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
 
-	const confirmed = await p.confirm({
-		message: 'Apply these changes, reinstall, and restart?',
-		initialValue: true
-	});
+	// 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).
-	const stopStatus = runPm2(dir, ['stop', APP_NAME], { inherit: false });
-	if (stopStatus !== 0) {
-		p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
+	// 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
+	// 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) {
+			p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
+		}
+	} catch {
+		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
-	// Back up for rollback on npm-install failure.
-	const bakPath = pkgPath + '.bak';
+	// One stamp for the whole run, so a migration's backups sort together and a
+	// later migration cannot overwrite this one's (#184).
+	const stamp = backupStamp();
+	const bakPath = backupPathFor(pkgPath, stamp);
+	const configBak = backupPathFor(configPath, stamp);
+	const ecoBak = backupPathFor(ecoPath, stamp);
+	const envBak = backupPathFor(envPath, stamp);
+
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
 
 	if (hasStaleConfig) {
-		copyFileSync(configPath, configPath + '.bak');
+		copyFileSync(configPath, configBak);
 		rmSync(configPath, { force: true });
 	}
 
 	if (ecoHasStaleRuntime) {
-		copyFileSync(ecoPath, ecoPath + '.bak');
-		// Rewrite @selvajs/runtime → @selvajs/selva only (preserve customizations).
+		copyFileSync(ecoPath, ecoBak);
+		// Text substitution, not regeneration, so any operator customizations to the file survive.
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
 			'@selvajs/selva'
@@ -132,47 +230,79 @@ export async function runMigrate() {
 	}
 
 	if (envRename.changes.length > 0) {
-		copyFileSync(envPath, envPath + '.bak');
+		copyFileSync(envPath, envBak);
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
-	// Clean install required (major version changes break legacy lockfile).
-	rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
-	rmSync(join(dir, 'package-lock.json'), { force: true });
+	// 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');
+
+	rmSync(nodeModulesBak, { recursive: true, force: true });
+	if (existsSync(nodeModules)) renameSync(nodeModules, nodeModulesBak);
+	const lockBak = existsSync(lockPath) ? readFileSync(lockPath, 'utf8') : null;
+	rmSync(lockPath, { force: true });
 
 	const s = p.spinner();
 	s.start('Installing new dependencies (this can take a minute)');
 	try {
-		// --prefer-online to bypass the stale-packument trap documented in
-		// docs/Hotfix-CLI-Runtime.md.
-		execSync('npm install --prefer-online', {
-			cwd: dir,
-			stdio: 'pipe'
-		});
+		install(dir);
 		s.stop('Dependencies installed');
+		rmSync(nodeModulesBak, { recursive: true, force: true });
 	} catch (err) {
-		s.stop(pc.red('npm install failed — rolling back package.json'));
+		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
-		if (hasStaleConfig && existsSync(configPath + '.bak')) {
-			copyFileSync(configPath + '.bak', configPath);
+		if (hasStaleConfig && existsSync(configBak)) {
+			copyFileSync(configBak, configPath);
 		}
-		if (ecoHasStaleRuntime && existsSync(ecoPath + '.bak')) {
-			copyFileSync(ecoPath + '.bak', ecoPath);
+		if (ecoHasStaleRuntime && existsSync(ecoBak)) {
+			copyFileSync(ecoBak, ecoPath);
 		}
-		if (envRename.changes.length > 0 && existsSync(envPath + '.bak')) {
-			copyFileSync(envPath + '.bak', envPath);
+		if (envRename.changes.length > 0 && existsSync(envBak)) {
+			copyFileSync(envBak, envPath);
 		}
-		// Try to bring the process back up (best-effort; at least package.json is consistent).
-		runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+
+		// 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');
+
+		restartAfterRollback(dir, pm2);
 		p.outro(pc.red(`Migration aborted: ${err.message ?? err}`));
 		process.exit(1);
 	}
 
-	const status = runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
-	const backupHints = ['package.json.bak'];
-	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
-	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
-	if (envRename.changes.length > 0) backupHints.push('.env.bak');
+	// 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 });
+	} catch (err) {
+		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.${stamp}.bak`];
+	if (hasStaleConfig) backupHints.push(`selva.config.js.${stamp}.bak`);
+	if (ecoHasStaleRuntime) backupHints.push(`ecosystem.config.cjs.${stamp}.bak`);
+	if (envRename.changes.length > 0) backupHints.push(`.env.${stamp}.bak`);
 
 	if (status === 0) {
 		p.outro(
@@ -187,23 +317,37 @@ export async function runMigrate() {
 	}
 }
 
-// Build target package.json with canonical dependencies (wholesale replace).
-// Drops non-canonical @selvajs/* and operator's own deps (by design).
-function buildTargetPackageJson(current) {
-	const deps = {
-		'@selvajs/cli': 'latest',
-		'@selvajs/selva': 'latest',
-		pm2: '^5.4.0'
-	};
+// 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 });
+		if (status === 0) {
+			p.log.success(`Rolled back and restarted ${APP_NAME}.`);
+			return;
+		}
+		p.log.error(
+			`Rolled back, but \`pm2 start\` exited ${status}. The app may be down — ` +
+				`check \`pm2 logs ${APP_NAME}\` and start it with \`selva start\`.`
+		);
+	} catch (err) {
+		p.log.error(
+			`Rolled back, but pm2 could not be invoked (${err instanceof Error ? err.message : err}). ` +
+				`The app is likely down — run \`npm install\` then \`selva start\`.`
+		);
+	}
+}
 
-	return {
+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',
-		private: true,
-		type: 'module',
-		scripts: { ...CANONICAL_SCRIPTS },
-		dependencies: deps
-	};
+		engines: current.engines,
+		dependencies: pins
+	});
+	return { pkg, notes };
 }
 
 // Format package.json diff for confirmation prompt (concise, not full diff).
@@ -222,6 +366,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)]);
@@ -235,39 +392,67 @@ function diffPackageJson(before, after) {
 		}
 	}
 
+	// 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]))}`);
+	}
+
 	return lines;
 }
 
-// Local pm2 runner (avoid circular dep; duplication is small).
-function runPm2(dir, args, { inherit = true } = {}) {
-	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
-	const bin = existsSync(local) ? local : 'pm2';
-	const result = spawnSync(bin, args, {
-		cwd: dir,
-		stdio: inherit ? 'inherit' : 'pipe',
-		shell: process.platform === 'win32'
-	});
-	if (result.error) return 1;
-	return result.status ?? 0;
+// One-line preview of a dropped field, enough to recognise what is being lost.
+function summarize(value) {
+	if (value === null || typeof value !== 'object') return String(value);
+	const keys = Object.keys(value);
+	if (Array.isArray(value)) return `[${keys.length} item${keys.length === 1 ? '' : 's'}]`;
+	return keys.length ? `{${keys.join(', ')}}` : '{}';
 }
 
 // Exported for `selva doctor` to check layout drift without duplication.
 export function detectDrift(pkgJson, dir) {
 	const deps = pkgJson?.dependencies ?? {};
 	const reasons = [];
-	if (deps['@selvajs/runtime']) reasons.push('@selvajs/runtime is the old runtime package');
-	if (deps['@selvajs/create']) reasons.push('@selvajs/create is the old CLI package');
-	if (deps['@selvajs/platform'])
-		reasons.push('@selvajs/platform is now bundled into @selvajs/selva');
-	if (deps['@selvajs/local-provider'])
-		reasons.push('@selvajs/local-provider is now bundled into @selvajs/selva');
-	if (deps['@selvajs/supabase-provider'])
-		reasons.push('@selvajs/supabase-provider is now bundled into @selvajs/selva');
-	if (deps['@selvajs/header-auth-provider'])
-		reasons.push('@selvajs/header-auth-provider is now bundled into @selvajs/selva');
-	if (!deps['@selvajs/selva']) reasons.push('@selvajs/selva is missing');
-	if (!deps['@selvajs/cli']) reasons.push('@selvajs/cli is missing');
-	if (!deps['pm2']) reasons.push('pm2 is not in dependencies');
+
+	for (const [name, why] of Object.entries(LEGACY_DEPENDENCIES)) {
+		if (deps[name]) reasons.push(`${name} is ${why}`);
+	}
+	for (const name of Object.keys(DEPENDENCIES)) {
+		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');
@@ -290,5 +475,26 @@ export function detectDrift(pkgJson, dir) {
 	return reasons;
 }
 
-// Re-exported for tests to verify without running migrate.
-export { buildTargetPackageJson, SELVA_DEPS };
+// 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 };