@selvajs/cli 4.20.0-beta.3 → 4.20.0-beta.30

package/src/commands/doctor.js

@@ -8,7 +8,6 @@
 import {
 	existsSync,
 	readFileSync,
-	writeFileSync,
 	copyFileSync,
 	readdirSync,
 	accessSync,
@@ -20,18 +19,27 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile, parseEnv, countEnvCommentLines, stripEnvComments } from '../env.js';
+import {
+	readEnvFile,
+	parseEnv,
+	countEnvCommentLines,
+	stripEnvComments,
+	writeEnvText
+} from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
 import { checkBootPersistence } from '../checks/boot.js';
 import { checkRuntimeEnvironment } from '../checks/runtime.js';
+import { checkSupabaseMigrations } from '../checks/migrations.js';
 import {
 	checkBodySizeLimit,
 	checkClientAddress,
 	checkDeprecatedEnv,
 	checkEnvDocumentation,
 	checkHeaderNames,
+	checkHmacKey,
+	checkKeyRotation,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
@@ -55,8 +63,9 @@ export async function runDoctor(argv = []) {
 	checks.push(checkLayoutDrift(dir));
 	checks.push(checkMigrationLeftovers(dir));
 	checks.push(checkAgedBackups(dir));
-	checks.push(checkSecret(env.SELVA_HMAC_KEY, 'SELVA_HMAC_KEY is a 32-byte hex string'));
-	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte hex string'));
+	checks.push(checkHmacKey(env.SELVA_HMAC_KEY));
+	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte key'));
+	checks.push(...checkKeyRotation(env));
 
 	const providers = resolveProviders(env);
 	checks.push(...checkProviders(providers));
@@ -69,7 +78,13 @@ export async function runDoctor(argv = []) {
 
 	if (used.has('supabase')) {
 		checks.push(checkSupabase(env));
-		checks.push(checkSupabaseMigrations(dir, env));
+		checks.push(
+			checkSupabaseMigrations(
+				dir,
+				env,
+				readPackageVersion(join(dir, 'node_modules', '@selvajs', 'selva', 'package.json'))
+			)
+		);
 	}
 
 	if (providers.auth === 'header') {
@@ -214,83 +229,6 @@ export async function checkSupabase(env) {
 	}
 }
 
-// Compares the newest migration shipped by @selvajs/supabase-provider against
-// what the database reports via selva.migration_head(). Red on skew — the app
-// degrades /api/health to 503 at boot in the same state, so catching it here
-// saves a confusing deploy.
-async function checkSupabaseMigrations(dir, env) {
-	if (!env.SUPABASE_URL || !env.SUPABASE_SERVICE_ROLE_KEY) {
-		return yellow('Migration-head check skipped — Supabase env incomplete');
-	}
-
-	const migrationsDir = join(
-		dir,
-		'node_modules',
-		'@selvajs',
-		'supabase-provider',
-		'supabase',
-		'migrations'
-	);
-	let expected = null;
-	try {
-		expected =
-			readdirSync(migrationsDir)
-				.filter((f) => /^\d{14}_.+\.sql$/.test(f))
-				.map((f) => f.slice(0, 14))
-				.sort()
-				.pop() ?? null;
-	} catch {
-		// Provider package not installed in this deployment.
-	}
-	if (!expected) {
-		return red(
-			'@selvajs/supabase-provider is not installed, so the migration SQL is missing. ' +
-				'Run `selva migrate` to add it, then `npm install`.'
-		);
-	}
-
-	try {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), 4000);
-		const res = await fetch(env.SUPABASE_URL + '/rest/v1/rpc/migration_head', {
-			method: 'POST',
-			headers: {
-				apikey: env.SUPABASE_SERVICE_ROLE_KEY,
-				Authorization: `Bearer ${env.SUPABASE_SERVICE_ROLE_KEY}`,
-				'Content-Type': 'application/json',
-				// The function lives in the selva schema the app is pinned to.
-				'Content-Profile': 'selva'
-			},
-			body: '{}',
-			signal: controller.signal
-		});
-		clearTimeout(timer);
-		if (res.status === 404) {
-			return red(
-				`Database is missing selva.migration_head() — migrations are pending (expected head ${expected}). Run: npx selva-supabase && npx supabase db push`
-			);
-		}
-		if (!res.ok) {
-			return yellow(`migration_head RPC responded ${res.status} — cannot verify schema head`);
-		}
-		const actual = String((await res.json()) ?? '');
-		if (!actual) {
-			return red(
-				`Database reports no applied migrations (expected head ${expected}). Run: npx selva-supabase && npx supabase db push`
-			);
-		}
-		// String comparison — relies on both heads being fixed-width, zero-padded timestamps.
-		if (actual < expected) {
-			return red(
-				`Database migration head ${actual} is behind the installed provider (${expected}). Run: npx selva-supabase && npx supabase db push`
-			);
-		}
-		return green(`Database migration head ${actual} matches the installed provider`);
-	} catch (err) {
-		return yellow(`Migration-head check skipped (${err.message ?? err})`);
-	}
-}
-
 function checkPackage(dir, name) {
 	const path = join(dir, 'node_modules', ...name.split('/'), 'package.json');
 	if (!existsSync(path)) return red(`${name} not installed (run npm install)`);
@@ -460,7 +398,7 @@ function checkEnvDocs(dir) {
 				if (drift) return red(`refused to strip .env — ${drift}`);
 
 				copyFileSync(envPath, envPath + '.bak');
-				writeFileSync(envPath, strippedText, 'utf8');
+				writeEnvText(envPath, strippedText);
 				return green(`stripped ${removed} comment lines from .env (backup: .env.bak)`);
 			} catch (err) {
 				return red(`could not rewrite .env: ${err instanceof Error ? err.message : err}`);

package/src/commands/init.js

@@ -2,11 +2,12 @@
 // 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 { parseEnv, seededTemplateDefaults, setEnvValues, writeEnvText } from '../env.js';
 import { generateKey } from '../secrets.js';
 import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
@@ -15,7 +16,8 @@ export async function runInit() {
 	requireDeploymentDir(dir);
 
 	const envPath = join(dir, '.env');
-	const current = readEnvFile(envPath);
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	const current = parseEnv(text);
 	const values = await collectConfig({ defaults: current, mode: 'init' });
 
 	// Never regenerate an existing key: rotating SELVA_HMAC_KEY or
@@ -42,11 +44,17 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	// 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 });
+	// Line-level: keys the prompts don't cover, and the operator's comments, stay as they are.
+	// A prompt answered blank means unset, as it did when the file was re-rendered.
+	const updates = Object.fromEntries(
+		Object.entries(values).map(([k, v]) => [k, v === '' ? undefined : v])
+	);
+	// A template default missing from .env (BODY_SIZE_LIMIT: unset, every upload
+	// 413s at adapter-node's 512 KB) is filled in; one the operator set is kept.
+	for (const [k, v] of Object.entries(seededTemplateDefaults(readEnvTemplate(dir)))) {
+		if (current[k] === undefined && !(k in updates)) updates[k] = v;
+	}
+	writeEnvText(envPath, setEnvValues(text, updates));
 
 	p.outro(
 		[

package/src/commands/keys.js

@@ -1,67 +1,146 @@
-// Rotate SELVA_HMAC_KEY or SELVA_AT_REST_KEY; requires explicit confirm (blast radius in TARGETS).
+// `selva keys rotate <hmac|at-rest> [--finish | --leaked]`.
+//
+// A routine rotation keeps the old key as <KEY>_PREVIOUS, which the app still
+// accepts, so nothing breaks. `--finish` drops the previous key once its
+// overlap has passed. `--leaked` replaces the key and drops the old one at
+// once: that is the destructive path, for a key that must stop working now.
 
+import { existsSync, readFileSync, readdirSync } 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 { parseEnv, setEnvValues, writeEnvText } from '../env.js';
+import { resolveProviders } from '../checks/config.js';
 import { generateKey } from '../secrets.js';
-import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { PREVIOUS_KEY_DAYS } from '../generated/config.js';
+import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 const TARGETS = {
 	hmac: {
 		envVar: 'SELVA_HMAC_KEY',
-		warning: [
-			'This will:',
-			pc.red('  • log every signed-in user out (existing session cookies stop verifying)'),
-			pc.red('  • invalidate every share link and pending invite')
-		].join('\n')
+		leakedBlastRadius: hmacBlastRadius,
+		finishNote:
+			'The app stops accepting the previous key on its own at SELVA_HMAC_KEY_PREVIOUS_EXPIRES; ' +
+			'finishing ends it now. Either way this stops working: MCP clients registered before the ' +
+			'rotation (they register again), and share links, invites and API tokens stored under the ' +
+			'previous key before tokens were hashed without one. Sessions it signed last 8 hours at most.'
 	},
 	'at-rest': {
 		envVar: 'SELVA_AT_REST_KEY',
-		warning: [
-			'This will:',
-			pc.red('  • make the encrypted Rhino.Compute API key undecryptable'),
-			pc.red('  • require re-entering the API key at /admin/compute'),
-			pc.dim('    (other data is plaintext on disk — only the compute API key is encrypted)')
-		].join('\n')
+		leakedBlastRadius: atRestBlastRadius,
+		finishNote:
+			'The app re-seals stored API keys under the new key at boot, and stops accepting the previous ' +
+			'key at SELVA_AT_REST_KEY_PREVIOUS_EXPIRES. Check that /admin/system shows none left on the ' +
+			'previous key before finishing, or they become unreadable.'
 	}
 };
 
+/** What dropping the old SELVA_HMAC_KEY at once invalidates on this deployment's providers. */
+export function hmacBlastRadius(env) {
+	const { auth } = resolveProviders(env);
+	const lines = [];
+	// Only the local provider signs sessions with it: Supabase sessions are
+	// Supabase JWTs, and under header auth the proxy owns the session.
+	if (auth === 'local') lines.push('log every signed-in user out');
+	lines.push(
+		'invalidate share links, invites and API tokens created before stored tokens were hashed without a key',
+		'disconnect every MCP client (each has to register and sign in again)',
+		'fail live solve-event streams of solves already running'
+	);
+	return lines;
+}
+
+export function atRestBlastRadius() {
+	return [
+		'make the stored Rhino.Compute API keys unreadable',
+		'require re-entering each API key at /admin/compute'
+	];
+}
+
+/** The .env change for each mode, as `setEnvValues` updates. */
+export function rotationUpdates(env, envVar, mode, fresh = generateKey(), now = Date.now()) {
+	const previousVar = `${envVar}_PREVIOUS`;
+	const expiresVar = `${previousVar}_EXPIRES`;
+	if (mode === 'finish') return { [previousVar]: undefined, [expiresVar]: undefined };
+	if (mode === 'leaked')
+		return { [envVar]: fresh, [previousVar]: undefined, [expiresVar]: undefined };
+	const expires = new Date(now + PREVIOUS_KEY_DAYS * 86_400_000).toISOString();
+	return { [envVar]: fresh, [previousVar]: env[envVar], [expiresVar]: expires };
+}
+
+function backupsHolding(dir, value) {
+	if (!value) return [];
+	return readdirSync(dir)
+		.filter((f) => f.startsWith('.env.') && f.endsWith('.bak'))
+		.filter((f) => readFileSync(join(dir, f), 'utf8').includes(value));
+}
+
 export async function runKeysRotate(argv) {
 	const target = argv[0];
+	const mode = argv.includes('--finish')
+		? 'finish'
+		: argv.includes('--leaked')
+			? 'leaked'
+			: 'rotate';
 	if (!target || !(target in TARGETS)) {
-		console.error(`Usage: selva keys rotate <hmac|at-rest>`);
+		console.error('Usage: selva keys rotate <hmac|at-rest> [--finish | --leaked]');
 		process.exit(1);
 	}
 
 	const dir = resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
-	const { envVar, warning } = TARGETS[target];
+	const { envVar, leakedBlastRadius, finishNote } = TARGETS[target];
+	const previousVar = `${envVar}_PREVIOUS`;
 	const envPath = join(dir, '.env');
-	const current = readEnvFile(envPath);
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	const env = parseEnv(text);
 
-	p.intro(pc.bgYellow(pc.black(` rotate ${envVar} `)));
-	p.note(warning, 'Blast radius');
+	p.intro(pc.bgYellow(pc.black(` ${mode === 'rotate' ? 'rotate' : mode} ${envVar} `)));
+
+	if (mode === 'rotate') {
+		if (env[previousVar]) {
+			p.cancel(
+				`${previousVar} is still set from the last rotation. Run \`selva keys rotate ${target} --finish\` first.`
+			);
+			process.exit(1);
+		}
+		p.note(
+			`The current key moves to ${previousVar}, which the app keeps accepting for ${PREVIOUS_KEY_DAYS} days.\nNothing stops working now. After that it is refused on its own; \`selva keys rotate ${target} --finish\`\nremoves it from .env.`,
+			'Safe rotation'
+		);
+	} else if (mode === 'finish') {
+		if (!env[previousVar]) {
+			p.outro(pc.dim(`${previousVar} is not set: nothing to finish.`));
+			return;
+		}
+		p.note(finishNote, 'Before you finish');
+	} else {
+		p.note(
+			['This will:', ...leakedBlastRadius(env).map((l) => pc.red(`  • ${l}`))].join('\n'),
+			'Blast radius'
+		);
+	}
 
-	const confirmed = await p.confirm({
-		message: `Rotate ${envVar}?`,
-		initialValue: false
-	});
+	const confirmed = await p.confirm({ message: 'Continue?', initialValue: mode === 'rotate' });
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
 		return;
 	}
 
-	const fresh = generateKey();
-	current[envVar] = fresh;
+	writeEnvText(envPath, setEnvValues(text, rotationUpdates(env, envVar, mode)));
 
-	writeEnvFile(envPath, readEnvTemplate(dir), current);
-
-	p.outro(
-		[
-			pc.green(`${envVar} rotated.`),
-			pc.dim('Restart the app to apply: ') + pc.cyan('selva restart')
-		].join('\n')
-	);
+	const lines = [pc.green(mode === 'finish' ? `${previousVar} removed.` : `${envVar} rotated.`)];
+	if (mode !== 'rotate') {
+		const stale = backupsHolding(dir, mode === 'finish' ? env[previousVar] : env[envVar]);
+		if (stale.length > 0) {
+			lines.push(
+				pc.yellow(
+					`These backups still hold the old key: ${stale.join(', ')}. Delete them if it leaked.`
+				)
+			);
+		}
+	}
+	lines.push(pc.dim('Restart the app to apply: ') + pc.cyan('selva restart'));
+	p.outro(lines.join('\n'));
 }

package/src/commands/migrate.js

@@ -2,13 +2,22 @@
 // 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';
+import {
+	existsSync,
+	readFileSync,
+	readdirSync,
+	writeFileSync,
+	copyFileSync,
+	rmSync,
+	renameSync
+} from 'node:fs';
 import { join } from 'node:path';
 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 { readEnvFile, renameEnvKeys, RENAMED_ENV_VARS, writeEnvText } from '../env.js';
+import { planEnvMigration } from '../env-migration.js';
 import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
@@ -100,7 +109,7 @@ export function classifyBackups(names, now = new Date(), maxAgeDays = BACKUP_AGE
 // 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,
+	argv = [],
 	{
 		dir: injectedDir,
 		// --prefer-online: npm can otherwise resolve a cached packument that
@@ -114,7 +123,13 @@ export async function runMigrate(
 	const dir = injectedDir ?? resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
-	p.intro(pc.bgCyan(pc.black(' selva migrate ')));
+	const dryRun = argv.includes('--dry-run');
+	p.intro(pc.bgCyan(pc.black(dryRun ? ' selva migrate --dry-run ' : ' selva migrate ')));
+
+	if (argv.includes('--undo')) {
+		undoEnvMigration(dir);
+		return;
+	}
 
 	const pkgPath = join(dir, 'package.json');
 	if (!existsSync(pkgPath)) {
@@ -123,7 +138,7 @@ export async function runMigrate(
 	}
 
 	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
-	const deploymentEnv = readDeploymentEnv(join(dir, '.env'));
+	const deploymentEnv = readEnvFile(join(dir, '.env'));
 	const { pkg: target, notes: pinNotes } = buildTargetPackageJson(
 		before,
 		resolveVersion,
@@ -131,32 +146,76 @@ export async function runMigrate(
 	);
 	const pkgDiff = diffPackageJson(before, target);
 
-	// 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.
+	// The server stops reading old names in a later release, so rewriting now is
+	// what keeps a tuned value tuned instead of silently reverting to a default.
 	const envPath = join(dir, '.env');
 	const envBefore = existsSync(envPath) ? readFileSync(envPath, 'utf8') : null;
-	const envRename = envBefore
-		? renameEnvKeys(envBefore, RENAMED_ENV_VARS)
-		: { text: '', changes: [] };
-
-	const sideFileChanges = [];
-	for (const [oldName, newName, action] of envRename.changes) {
-		sideFileChanges.push(
-			action === 'dropped'
-				? `${pc.red('-')} .env ${pc.dim(`${oldName} (deprecated; ${newName} is already set)`)}`
-				: `${pc.yellow('~')} .env ${pc.dim(`${oldName} → ${newName}`)}`
+	const envPlan = envBefore
+		? planEnvMigration(envBefore)
+		: { text: '', changes: [], mismatches: [], blockers: [], fallbacks: [], unknown: [] };
+	const envChanged = envPlan.changes.length > 0;
+
+	// The rewrite would change what a setting means. Never write that.
+	if (envPlan.mismatches.length > 0) {
+		p.log.error('The .env rewrite would change these settings, so nothing was written:');
+		for (const m of envPlan.mismatches) {
+			console.log(`  ${m.key}: ${JSON.stringify(m.was)} → ${JSON.stringify(m.is)}`);
+		}
+		p.outro(pc.red('Migration refused. Please report this: it is a bug in the migration.'));
+		process.exit(1);
+	}
+
+	// Values the old readers ignored that this release refuses to boot on.
+	if (envPlan.blockers.length > 0) {
+		p.log.error('This release would not start with these .env values:');
+		for (const b of envPlan.blockers) console.log(`  ${b.key} ${b.problem}`);
+		p.outro(
+			pc.red(
+				'Fix them first (`selva config set KEY=VALUE`), then run migrate again. Nothing was written.'
+			)
 		);
+		process.exit(1);
 	}
+	for (const f of envPlan.fallbacks) {
+		p.log.warn(`${f.key} ${f.problem}: the app runs on its default instead.`);
+	}
+
+	const sideFileChanges = envPlan.changes.map(describeEnvChange);
 
 	if (pkgDiff.length === 0 && sideFileChanges.length === 0) {
+		reportUnknown(envPlan.unknown);
 		p.outro(pc.green('Already on the current layout — nothing to migrate.'));
 		return;
 	}
 
-	p.log.info('Changes to apply:');
+	p.log.info(dryRun ? 'Would apply (nothing is written in a dry run):' : 'Changes to apply:');
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
+	reportUnknown(envPlan.unknown);
+
+	if (dryRun) {
+		p.outro(pc.green('Every setting keeps its meaning. Run without --dry-run to apply.'));
+		return;
+	}
+
+	// Only .env changes: no reinstall, no restart of anyone's running app.
+	if (pkgDiff.length === 0) {
+		const go = await confirm('Rewrite .env (a backup is kept)?');
+		if (p.isCancel(go) || !go) {
+			p.cancel('Cancelled.');
+			return;
+		}
+		const bak = backupPathFor(envPath, backupStamp());
+		copyFileSync(envPath, bak);
+		writeEnvText(bak, readFileSync(bak, 'utf8'));
+		writeEnvText(envPath, envPlan.text);
+		p.outro(
+			pc.green('.env migrated. ') +
+				pc.dim(`Backup: ${bak}. Undo: selva migrate --undo. Apply: `) +
+				pc.cyan('selva restart')
+		);
+		return;
+	}
 
 	// 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
@@ -203,9 +262,10 @@ export async function runMigrate(
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
 
-	if (envRename.changes.length > 0) {
+	if (envChanged) {
 		copyFileSync(envPath, envBak);
-		writeFileSync(envPath, envRename.text, 'utf8');
+		writeEnvText(envBak, readFileSync(envBak, 'utf8'));
+		writeEnvText(envPath, envPlan.text);
 	}
 
 	// A legacy lockfile pins the old package set across a major bump, so this needs
@@ -231,7 +291,7 @@ export async function runMigrate(
 	} catch (err) {
 		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
-		if (envRename.changes.length > 0 && existsSync(envBak)) {
+		if (envChanged && existsSync(envBak)) {
 			copyFileSync(envBak, envPath);
 		}
 
@@ -263,12 +323,12 @@ export async function runMigrate(
 	// 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).
+	// plans/archive/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 (envRename.changes.length > 0) backupHints.push(`.env.${stamp}.bak`);
+	if (envChanged) backupHints.push(`.env.${stamp}.bak`);
 
 	if (status === 0) {
 		p.outro(
@@ -305,19 +365,6 @@ function restartAfterRollback(dir, pm2 = runPm2) {
 	}
 }
 
-// Only the provider keys matter here, so this reads `KEY=value` lines rather
-// than pulling in a dotenv parser: no quoting, expansion, or multi-line values
-// to honour.
-function readDeploymentEnv(envPath) {
-	if (!existsSync(envPath)) return {};
-	const env = {};
-	for (const line of readFileSync(envPath, 'utf8').split(/\r?\n/)) {
-		const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
-		if (match) env[match[1]] = match[2].trim().replace(/^["']|["']$/g, '');
-	}
-	return env;
-}
-
 function buildTargetPackageJson(current, resolveVersion = npmDistTagVersion, env = {}) {
 	const supabase = needsSupabaseProvider(env);
 	const { pins, notes } = resolveSelvaPins(
@@ -475,3 +522,51 @@ export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
 }
 
 export { buildTargetPackageJson, diffPackageJson };
+
+function describeEnvChange(c) {
+	const env = (text) => `${pc.yellow('~')} .env ${pc.dim(text)}`;
+	switch (c.action) {
+		case 'stripped':
+			return env('shipped template comments removed (your own notes above a setting are kept)');
+		case 'renamed':
+			return env(`${c.key} → ${c.to}`);
+		case 'dropped':
+			return `${pc.red('-')} .env ${pc.dim(`${c.key} (${c.reason})`)}`;
+		case 'replaced':
+			return env(`${c.key} → ${c.to}`);
+		case 'rewritten':
+			return env(`${c.key} written as ${c.to}, what it already meant`);
+		case 'removed':
+			return `${pc.red('-')} .env ${pc.dim(`${c.key} (${c.reason})`)}`;
+		default:
+			return env(c.key);
+	}
+}
+
+function reportUnknown(unknown) {
+	for (const u of unknown) {
+		p.log.warn(
+			`.env sets ${u.key}, which Selva does not read${u.suggestion ? ` (did you mean ${u.suggestion}?)` : ''}. Left as is.`
+		);
+	}
+}
+
+/** Restore the newest .env backup migrate (or config set) wrote. */
+function undoEnvMigration(dir) {
+	const backups = readdirSync(dir)
+		.filter((f) => f.startsWith('.env.') && BACKUP_PATTERN.test(f))
+		.sort()
+		.reverse();
+	if (backups.length === 0) {
+		p.outro(pc.yellow('No .env backup to restore.'));
+		return;
+	}
+	const envPath = join(dir, '.env');
+	const current = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	// Keep what is being replaced, so an undo can itself be undone.
+	if (current) writeEnvText(backupPathFor(envPath, backupStamp()), current);
+	writeEnvText(envPath, readFileSync(join(dir, backups[0]), 'utf8'));
+	p.outro(
+		pc.green(`Restored .env from ${backups[0]}. `) + pc.dim('Apply: ') + pc.cyan('selva restart')
+	);
+}