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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.20.0-beta.3",
+  "version": "4.20.0-beta.30",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -41,11 +41,11 @@
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "pm2": "7.0.3"
+    "pm2": "7.1.2"
   },
   "scripts": {
     "start": "node ./bin/cli.js",
     "selva": "node ./bin/selva.js",
-    "test": "node --check ./bin/cli.js && node --check ./bin/selva.js && node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/node-range.js','./src/deployment-package.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js']) { await import(m); }\" && node --test \"./src/__tests__/*.test.js\""
+    "test": "node --check ./bin/cli.js && node --check ./bin/selva.js && node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/node-range.js','./src/deployment-package.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js','./src/commands/config.js','./src/env-migration.js']) { await import(m); }\" && node --test \"./src/__tests__/*.test.js\""
   }
 }

package/src/caddyfile.js

@@ -45,11 +45,11 @@ export function renderCaddyfile({ domain, acmeEmail, port = 3000 }) {
 	@api path /api/*
 	header @api Cache-Control "no-cache, no-store, must-revalidate"
 
-	# Must clear the app's own caps (COMPUTE_REQUEST_MAX_BYTES / BODY_SIZE_LIMIT,
-	# both 256 MB) — Caddy rejects first, so a lower value here silently caps
-	# every upload no matter what .env says.
+	# Must clear the app's own caps (the solve request cap and BODY_SIZE_LIMIT,
+	# both 256 MiB) — Caddy rejects first, so a lower value here silently caps
+	# every upload no matter what .env says. Write MiB: Caddy's "mb" is 10^6 bytes.
 	request_body {
-		max_size 256mb
+		max_size 256MiB
 	}
 
 	log {

package/src/checks/config.js

@@ -10,7 +10,8 @@
 // it. `__tests__/doctor-config-parity.test.js` asserts both against one fixture
 // table, so a rule changed here and not there fails CI.
 
-import { RENAMED_ENV_VARS, REPLACED_ENV_VARS } from '../env.js';
+import { RENAMED_ENV_VARS, RETIRED_ENV_VARS } from '../env.js';
+import { keyRotationStatus } from '../generated/config.js';
 import { green, red, yellow } from './result.js';
 
 const HEX_64 = /^[0-9a-f]{64}$/i;
@@ -28,10 +29,33 @@ const VALID_DATA = ['local', 'supabase'];
 export function checkSecret(value, label) {
 	if (!value) return red(`${label} — unset`);
 	if (value === PLACEHOLDER) return red(`${label} — still the placeholder`);
-	if (!HEX_64.test(value)) return red(`${label} — not 64 hex chars`);
+	if (!HEX_64.test(value) && !isBase64Of32Bytes(value)) {
+		return red(`${label} — not 32 bytes as 64 hex chars or base64`);
+	}
 	return green(label);
 }
 
+/**
+ * SELVA_HMAC_KEY takes any string of 32+ characters (the token codec's rule),
+ * not only hex: reding a valid key would send an operator rotating it.
+ */
+export function checkHmacKey(value) {
+	const label = 'SELVA_HMAC_KEY is at least 32 characters';
+	if (!value) return red(`${label} — unset`);
+	if (value === PLACEHOLDER) return red(`${label} — still the placeholder`);
+	if (value.length < 32) return red(`${label} — only ${value.length}`);
+	return green(label);
+}
+
+// Mirrors decodeSecretKey in @selvajs/platform: only a round trip proves the
+// whole string was base64, since Buffer.from skips what it can't decode.
+function isBase64Of32Bytes(value) {
+	const buf = Buffer.from(value, 'base64');
+	return (
+		buf.length === 32 && buf.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
+	);
+}
+
 // Lowercased and defaulted the same way create-selva-providers.ts defaults them.
 export function resolveProviders(env) {
 	return {
@@ -197,10 +221,10 @@ export function parseBodySizeLimit(raw) {
 	return bytes;
 }
 
-// The app's own default for COMPUTE_REQUEST_MAX_BYTES (packages/server
+// The app's solve request cap (COMPUTE_REQUEST_MAX_BYTES in packages/server
 // compute/limits.ts). Duplicated rather than imported: the CLI installs the
 // runtime and cannot import from it.
-const COMPUTE_REQUEST_DEFAULT_BYTES = 256 * 1024 * 1024;
+const COMPUTE_REQUEST_MAX_BYTES = 256 * 1024 * 1024;
 
 /**
  * BODY_SIZE_LIMIT has to clear the compute request cap, or adapter-node's global
@@ -210,7 +234,7 @@ const COMPUTE_REQUEST_DEFAULT_BYTES = 256 * 1024 * 1024;
  */
 export function checkBodySizeLimit(env) {
 	const raw = env.BODY_SIZE_LIMIT;
-	const requestCap = Number(env.COMPUTE_REQUEST_MAX_BYTES) || COMPUTE_REQUEST_DEFAULT_BYTES;
+	const requestCap = COMPUTE_REQUEST_MAX_BYTES;
 	const asMb = (bytes) => `${Math.round(bytes / (1024 * 1024))} MB`;
 
 	if (raw == null || raw === '') {
@@ -231,9 +255,9 @@ export function checkBodySizeLimit(env) {
 
 	if (bytes < requestCap) {
 		return yellow(
-			`BODY_SIZE_LIMIT=${raw} (${asMb(bytes)}) is below COMPUTE_REQUEST_MAX_BYTES ` +
-				`(${asMb(requestCap)}) — the global cap rejects first, making the compute cap ` +
-				`dead config. Raise it to at least ${asMb(requestCap)}.`
+			`BODY_SIZE_LIMIT=${raw} (${asMb(bytes)}) is below the ` +
+				`${asMb(requestCap)} a solve may send — larger solves fail with 413 before Selva ` +
+				`sees them. Raise it to at least ${asMb(requestCap)}.`
 		);
 	}
 
@@ -291,12 +315,23 @@ export function checkClientAddress(env) {
 		);
 	}
 
+	// A trusted address header is only safe if every request passes through the
+	// proxy: on a public bind a direct caller sets the header itself and picks
+	// its own rate-limit bucket.
+	const host = env.HOST ?? '0.0.0.0';
+	if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
+		return yellow(
+			`ADDRESS_HEADER=${header} is trusted but HOST=${host} leaves the app reachable ` +
+				`without the proxy, so a direct caller can set the header and pick its own ` +
+				`rate-limit bucket. Set HOST=127.0.0.1 and keep port 3000 closed in the ` +
+				`firewall (ignore this only if the proxy runs on another host behind network isolation).`
+		);
+	}
+
 	return green(`ADDRESS_HEADER=${header}${depth ? ` (XFF_DEPTH=${depth})` : ''}`);
 }
 
-// A rename is auto-fixable (`selva migrate` rewrites the key). A replacement
-// encodes a value in the new name, so migrate leaves it alone rather than
-// guessing — it's reported here and nowhere else.
+// Both are auto-fixable: `selva migrate` renames old names and removes retired keys.
 export function checkDeprecatedEnv(env) {
 	const checks = [];
 
@@ -309,10 +344,40 @@ export function checkDeprecatedEnv(env) {
 		);
 	}
 
-	for (const [oldName, replacement] of Object.entries(REPLACED_ENV_VARS)) {
-		if (env[oldName] === undefined) continue;
-		checks.push(yellow(`${oldName} is deprecated — replace it with ${replacement}`));
+	for (const [key, now] of Object.entries(RETIRED_ENV_VARS)) {
+		if (env[key] === undefined) continue;
+		checks.push(yellow(`${key} is no longer read (${now}) — \`selva migrate\` removes it`));
 	}
 
 	return checks;
 }
+
+/** Where each root key's rotation overlap stands. Nothing while no rotation is in progress. */
+export function checkKeyRotation(env, now = Date.now()) {
+	return keyRotationStatus(env, now).flatMap(({ key, state, expires, daysLeft }) => {
+		const previous = `${key}_PREVIOUS`;
+		const target = key === 'SELVA_HMAC_KEY' ? 'hmac' : 'at-rest';
+		if (state === 'active') {
+			return [
+				green(`${previous} accepted for ${daysLeft} more days (until ${expires.slice(0, 10)})`)
+			];
+		}
+		if (state === 'expired') {
+			return [
+				yellow(
+					`${previous} passed its deadline (${expires}) and is no longer accepted. ` +
+						`Remove it: npx selva keys rotate ${target} --finish`
+				)
+			];
+		}
+		if (state === 'no-deadline') {
+			return [
+				yellow(
+					`${previous} has no deadline, so the old key is accepted for good. Set ` +
+						`${previous}_EXPIRES, or remove it: npx selva keys rotate ${target} --finish`
+				)
+			];
+		}
+		return [];
+	});
+}

package/src/checks/migrations.js

@@ -0,0 +1,156 @@
+// Supabase schema head: what the installed runtime expects, what the installed
+// provider can migrate to, and what the database is at. These are three
+// separate numbers. The runtime bundles the provider's code but not its SQL,
+// so `selva update` can move the runtime past a provider install that stays
+// pinned. Comparing the database against the provider then reports a match
+// while the app degrades /api/health to 503.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { green, yellow, red } from './result.js';
+
+const HEAD_RE = /^\d{14}$/;
+
+/** Head the installed @selvajs/selva was built against, or null for a runtime that predates runtime-meta.json. */
+export function readRuntimeMigrationHead(dir) {
+	try {
+		const meta = JSON.parse(
+			readFileSync(
+				join(dir, 'node_modules', '@selvajs', 'selva', 'build', 'runtime-meta.json'),
+				'utf8'
+			)
+		);
+		return HEAD_RE.test(meta?.supabaseMigrationHead) ? meta.supabaseMigrationHead : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Newest migration the installed @selvajs/supabase-provider ships, or null when it isn't installed. */
+export function readProviderMigrationHead(dir) {
+	const migrationsDir = join(
+		dir,
+		'node_modules',
+		'@selvajs',
+		'supabase-provider',
+		'supabase',
+		'migrations'
+	);
+	if (!existsSync(migrationsDir)) return null;
+	return (
+		readdirSync(migrationsDir)
+			.filter((f) => /^\d{14}_.+\.sql$/.test(f))
+			.map((f) => f.slice(0, 14))
+			.sort()
+			.pop() ?? null
+	);
+}
+
+/** The npm dist-tag matching the installed runtime: a pre-release runtime needs the provider's beta migrations. */
+export function providerTagFor(runtimeVersion) {
+	return runtimeVersion?.includes('-') ? 'beta' : 'latest';
+}
+
+/**
+ * `{ head }` on success, `{ missing: true }` when selva.migration_head() doesn't
+ * exist yet, `{ error }` when the database couldn't be asked.
+ */
+export async function fetchDatabaseMigrationHead(env) {
+	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 { missing: true };
+		if (!res.ok) return { error: `migration_head RPC responded ${res.status}` };
+		return { head: String((await res.json()) ?? '') };
+	} catch (err) {
+		return { error: err.message ?? String(err) };
+	}
+}
+
+function migrateSteps(tag, providerBehind) {
+	return [
+		...(providerBehind ? [`npm install --prefer-online @selvajs/supabase-provider@${tag}`] : []),
+		'npx selva-supabase',
+		'npx supabase db push'
+	].join(' && ');
+}
+
+/**
+ * Pure verdict, so the three-way comparison is testable without disk or network.
+ * `runtime` is null for an old runtime; the provider head is then the best guess.
+ * String comparison is safe: every head is a fixed-width timestamp.
+ */
+export function judgeMigrationHeads({ runtime, provider, database, tag }) {
+	const expected = runtime ?? provider;
+	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`.'
+		);
+	}
+	const providerBehind = !provider || provider < expected;
+	const steps = migrateSteps(tag, providerBehind);
+	const providerNote =
+		runtime && providerBehind
+			? ` The installed @selvajs/supabase-provider only reaches ${provider ?? '(none)'}, so syncing it copies nothing new.`
+			: '';
+
+	if (database.error) return yellow(`Migration-head check skipped (${database.error})`);
+	if (database.missing) {
+		return red(
+			`Database is missing selva.migration_head(): migrations are pending (expected head ${expected}).${providerNote} Run: ${steps}`
+		);
+	}
+	if (!database.head) {
+		return red(
+			`Database reports no applied migrations (expected head ${expected}).${providerNote} Run: ${steps}`
+		);
+	}
+	if (database.head < expected) {
+		const against = runtime ? "the app's expected" : 'the installed provider';
+		return red(
+			`Database migration head ${database.head} is behind ${against} ${expected}. ` +
+				`/api/health returns 503 and writes that need the newer schema fail.${providerNote} Run: ${steps}`
+		);
+	}
+	if (runtime && providerBehind) {
+		// The database is fine today; the next upgrade's sync would silently copy nothing.
+		return yellow(
+			`Database migration head ${database.head} matches the app, but @selvajs/supabase-provider ` +
+				`is at ${provider ?? '(none)'}. Run: npm install --prefer-online @selvajs/supabase-provider@${tag}`
+		);
+	}
+	return green(
+		`Database migration head ${database.head} matches the ${runtime ? 'app' : 'installed provider'}`
+	);
+}
+
+export async function checkSupabaseMigrations(dir, env, runtimeVersion) {
+	if (!env.SUPABASE_URL || !env.SUPABASE_SERVICE_ROLE_KEY) {
+		return yellow('Migration-head check skipped: Supabase env incomplete');
+	}
+	const runtime = readRuntimeMigrationHead(dir);
+	const provider = readProviderMigrationHead(dir);
+	if (!runtime && !provider) {
+		return judgeMigrationHeads({ runtime, provider, database: {}, tag: 'latest' });
+	}
+	return judgeMigrationHeads({
+		runtime,
+		provider,
+		database: await fetchDatabaseMigrationHead(env),
+		tag: providerTagFor(runtimeVersion)
+	});
+}

package/src/checks/runtime.js

@@ -17,6 +17,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { fixable, green, red, yellow } from './result.js';
 import { PM2_VERSION } from '../deployment-package.js';
+import { APP_NAME } from '../commands/pm2.js';
 
 /** The real OS. Tests pass a stand-in with the same shape. */
 export const runtimeEnv = {
@@ -245,7 +246,12 @@ function checkPm2Daemon(dir, env) {
 	const output = String(probe.stdout ?? '') + String(probe.stderr ?? '');
 
 	if (!/out-of-date/i.test(output)) {
-		if (/pong/i.test(output)) return [green('pm2 daemon responds and matches the local pm2')];
+		if (/pong/i.test(output)) {
+			return [
+				green('pm2 daemon responds and matches the local pm2'),
+				checkAppProcess(bin, dir, env)
+			];
+		}
 		return [yellow('pm2 daemon did not answer `pm2 ping` — check `npx pm2 ping` by hand')];
 	}
 
@@ -267,10 +273,37 @@ function checkPm2Daemon(dir, env) {
 		yellow(
 			`pm2 daemon (v${daemon ?? 'unknown'}) differs from the local pm2 (v${local ?? PM2_VERSION}).\n     ` +
 				'Resync it — this briefly restarts managed processes: npx pm2 update'
-		)
+		),
+		checkAppProcess(bin, dir, env)
 	];
 }
 
+// A live daemon says nothing about the app: an interrupted `pm2 update` leaves
+// the daemon up with an empty process table, and every other check still
+// passes. Only called once the daemon is confirmed alive, so `jlist` can't
+// spawn one.
+function checkAppProcess(bin, dir, env) {
+	const r = env.run(bin, ['jlist'], { cwd: dir });
+	// A skewed daemon prints its out-of-date banner ahead of the JSON.
+	const json = String(r.stdout ?? '')
+		.split('\n')
+		.find((line) => line.trimStart().startsWith('['));
+	let list;
+	try {
+		list = JSON.parse(json ?? '');
+	} catch {
+		return yellow(`could not read the pm2 process list — check \`npx pm2 list\` by hand`);
+	}
+	const app = list.find((proc) => proc.name === APP_NAME);
+	const status = app?.pm2_env?.status;
+	if (status === 'online') return green(`${APP_NAME} is online`);
+	return red(
+		`${APP_NAME} is ${app ? `'${status}'` : 'not registered with pm2'} — the app is down.\n     ` +
+			'Start it, then save the list so a reboot brings it back:\n     ' +
+			'npx selva start && npx pm2 save'
+	);
+}
+
 // ── pm2 log rotation ────────────────────────────────────────────────────
 
 // pm2 appends to `$PM2_HOME/logs/*.log` forever. Nothing in a default install
@@ -352,7 +385,6 @@ function installLogRotate(bin, dir, env) {
 }
 
 function parseSkew(output) {
-	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
 	const clean = output.replace(/\[[0-9;]*m/g, '');
 	return {
 		daemon: /In memory PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean)?.[1] ?? null,

package/src/cli.js

@@ -16,7 +16,8 @@ const COMMANDS = {
 	update: () => import('./commands/pm2.js').then((m) => m.runUpdate),
 	migrate: () => import('./commands/migrate.js').then((m) => m.runMigrate),
 	'setup-proxy': () => import('./commands/proxy.js').then((m) => m.runSetupProxy),
-	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
+	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m)),
+	config: () => import('./commands/config.js').then((m) => m.runConfig)
 };
 
 // `selva doctor --help` used to run the full doctor: commands own their argv,
@@ -49,9 +50,13 @@ const USAGE = {
 			'npm update @selvajs/cli + @selvajs/selva, then restart. Rolls the\ndependency tree back if the install fails.'
 	},
 	migrate: {
-		usage: 'selva migrate',
+		usage: 'selva migrate [--dry-run | --undo]',
 		blurb:
-			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
+			'Bring package.json, the deployment layout and .env onto the current release.\nRenames old keys and proves every setting keeps its meaning before writing.',
+		flags: [
+			['--dry-run', 'Show what would change. Writes nothing.'],
+			['--undo', 'Restore the newest .env backup.']
+		]
 	},
 	'setup-proxy': {
 		usage: 'selva setup-proxy [--domain <fqdn>] [--acme-email <addr>]',
@@ -62,10 +67,20 @@ const USAGE = {
 			['--acme-email', "Address Let's Encrypt sends expiry notices to."]
 		]
 	},
+	config: {
+		usage: 'selva config <show [--all] | set KEY=VALUE | unset KEY>',
+		blurb:
+			'Show what .env sets, what is default and what is wrong; set or unset one\nkey after checking it. Edits only that line and keeps a backup.',
+		flags: [['--all', 'show: list every setting, defaults included.']]
+	},
 	keys: {
-		usage: 'selva keys rotate <hmac|at-rest>',
+		usage: 'selva keys rotate <hmac|at-rest> [--finish | --leaked]',
 		blurb:
-			'Rotate one secret in .env. Destructive and not reversible — the command\nspells out the blast radius and asks before writing.'
+			'Rotate one secret in .env. The old key stays accepted as <KEY>_PREVIOUS, so\nnothing breaks; --finish drops it later. --leaked drops it at once.',
+		flags: [
+			['--finish', 'Remove <KEY>_PREVIOUS once the overlap has passed.'],
+			['--leaked', 'Replace the key and drop the old one now. Breaks what it signed.']
+		]
 	}
 };
 
@@ -85,7 +100,7 @@ function keysDispatch(m) {
 	return async (argv) => {
 		const sub = argv[0];
 		if (sub === 'rotate') return m.runKeysRotate(argv.slice(1));
-		console.error(`Usage: selva keys rotate <hmac|at-rest>`);
+		console.error(`Usage: selva keys rotate <hmac|at-rest> [--finish | --leaked]`);
 		process.exit(1);
 	};
 }
@@ -140,7 +155,8 @@ function printHelp() {
 			'  update                  npm update @selvajs/cli + @selvajs/selva, then restart',
 			'  migrate                 Bring package.json onto the current layout',
 			'  setup-proxy             Install + configure Caddy with TLS for this deployment',
-			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
+			'  config show|set|unset   What .env sets; change one key safely',
+			'  keys rotate <hmac|at-rest>   Rotate a secret; the old one keeps working',
 			'',
 			pc.dim('`npx selva <command> --help` explains one command.'),
 			'',

package/src/commands/config.js

@@ -0,0 +1,196 @@
+// `selva config show|set|unset`: what this deployment's .env sets, checked
+// against the manifest the runtime declares.
+
+import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { parseEnv, setEnvValues, writeEnvText } from '../env.js';
+import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import {
+	ALL_SETTINGS,
+	deploymentReport,
+	deploymentSnapshot,
+	diffSnapshots,
+	resolveConfig
+} from '../generated/config.js';
+import { backupPathFor, backupStamp } from './migrate.js';
+
+export const SNAPSHOT_FILE = '.selva-config-snapshot.json';
+
+/** The same report the app builds for /admin/system. */
+export const reportFor = deploymentReport;
+
+/**
+ * How `.env` differs from what the app last booted with. Non-empty means it
+ * was edited without a restart, or something (pm2's saved env, compose)
+ * overrides it.
+ */
+export function driftFromLastBoot(dir, env) {
+	const path = join(dir, SNAPSHOT_FILE);
+	if (!existsSync(path)) return null;
+	let snapshot;
+	try {
+		snapshot = JSON.parse(readFileSync(path, 'utf8'));
+	} catch {
+		return null;
+	}
+	return diffSnapshots(snapshot, deploymentSnapshot(env, snapshot.salt));
+}
+
+/** Validate one KEY=VALUE against the manifest. Returns the spec, or an error message. */
+export function checkSetting(key, value) {
+	const spec = ALL_SETTINGS.find((s) => s.key === key);
+	if (!spec) {
+		const alias = ALL_SETTINGS.find((s) => s.aliases?.includes(key));
+		return {
+			error: alias
+				? `${key} was renamed to ${alias.key}.`
+				: `${key} is not a setting Selva reads. \`selva config show --all\` lists them.`
+		};
+	}
+	// Setting a key by hand skips _PREVIOUS and breaks what it protected.
+	if (spec.class === 'secret' && spec.generated) {
+		const target = key.startsWith('SELVA_HMAC_KEY') ? 'hmac' : 'at-rest';
+		return {
+			error: `${key} is replaced with \`selva keys rotate ${target}\`, which keeps the old key working.`
+		};
+	}
+	const report = resolveConfig([spec], { [key]: value }).keys[key];
+	if (report.status !== 'ok') return { error: `${key} ${report.problem}.` };
+	return { spec };
+}
+
+function printRow(row) {
+	const value = row.display === '' ? pc.dim('—') : row.display;
+	const source =
+		row.source === 'default'
+			? pc.dim('default')
+			: row.source === 'unset'
+				? pc.dim('not set')
+				: row.source === 'alias'
+					? pc.yellow(`from ${row.alias}`)
+					: '.env';
+	const mark =
+		row.status === 'error' ? pc.red('✗') : row.status === 'invalid' ? pc.yellow('!') : ' ';
+	console.log(`${mark} ${row.key.padEnd(36)} ${String(value).padEnd(30)} ${source}`);
+	if (row.problem) console.log(`    ${pc.red(`value ${row.problem}`)}`);
+}
+
+export async function runConfig(argv) {
+	const [sub, ...rest] = argv;
+	if (sub === 'show' || sub === undefined) return runShow(rest);
+	if (sub === 'set') return runSet(rest);
+	if (sub === 'unset') return runUnset(rest);
+	console.error('Usage: selva config <show [--all] | set KEY=VALUE | unset KEY>');
+	process.exit(1);
+}
+
+function readDeploymentEnv() {
+	const dir = resolveDeploymentDir();
+	requireDeploymentDir(dir);
+	const envPath = join(dir, '.env');
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	return { dir, envPath, text, env: parseEnv(text) };
+}
+
+function runShow(argv) {
+	const all = argv.includes('--all');
+	const { dir, env } = readDeploymentEnv();
+	const report = reportFor(env);
+
+	console.log(pc.bold('\nThe important ones'));
+	for (const row of report.rows.filter((r) => r.summary)) printRow(row);
+
+	const rest = report.rows.filter(
+		(r) => !r.summary && (all || r.source !== 'default') && r.source !== 'unset'
+	);
+	if (rest.length > 0) {
+		console.log(pc.bold(all ? '\nEverything else' : '\nAlso set in .env'));
+		for (const row of rest) printRow(row);
+	}
+
+	if (report.unknown.length > 0) {
+		console.log(pc.bold('\nNot settings Selva reads'));
+		for (const u of report.unknown) {
+			console.log(
+				`${pc.yellow('!')} ${u.key}${u.suggestion ? pc.dim(`  did you mean ${u.suggestion}?`) : ''}`
+			);
+		}
+	}
+
+	const drift = driftFromLastBoot(dir, env);
+	if (drift && drift.length > 0) {
+		console.log(pc.bold('\nDiffers from what the app last started with'));
+		console.log(
+			pc.dim('  Restart to apply, or check whether pm2 or the environment overrides .env.')
+		);
+		for (const c of drift) {
+			const detail =
+				c.from !== undefined || c.to !== undefined ? `  ${c.from ?? '—'} → ${c.to ?? '—'}` : '';
+			console.log(`  ${c.key} ${pc.dim(c.change)}${detail}`);
+		}
+	}
+
+	const errors = report.problems.filter((p) => p.status === 'error').length;
+	console.log(
+		'\n' +
+			(errors > 0
+				? pc.red(`${errors} setting${errors === 1 ? '' : 's'} would stop the app from starting.`)
+				: pc.green('Nothing stops the app from starting.')) +
+			(all ? '' : pc.dim('  `selva config show --all` lists every setting.'))
+	);
+	if (errors > 0) process.exit(1);
+}
+
+function backUp(envPath) {
+	if (!existsSync(envPath)) return null;
+	const bak = backupPathFor(envPath, backupStamp());
+	copyFileSync(envPath, bak);
+	writeEnvText(bak, readFileSync(bak, 'utf8'));
+	return bak;
+}
+
+function runSet(argv) {
+	const arg = argv[0] ?? '';
+	const eq = arg.indexOf('=');
+	if (eq <= 0) {
+		console.error('Usage: selva config set KEY=VALUE');
+		process.exit(1);
+	}
+	const key = arg.slice(0, eq);
+	const value = arg.slice(eq + 1);
+	const { spec, error } = checkSetting(key, value);
+	if (error) {
+		console.error(pc.red(`✗ ${error}`));
+		process.exit(1);
+	}
+	const { envPath, text } = readDeploymentEnv();
+	if (spec.impact) console.log(pc.yellow(`! ${spec.impact}`));
+	const bak = backUp(envPath);
+	writeEnvText(envPath, setEnvValues(text, { [key]: value }));
+	console.log(pc.green(`✓ ${key} set.`) + (bak ? pc.dim(` Backup: ${bak}`) : ''));
+	console.log(pc.dim('Restart to apply: ') + pc.cyan('selva restart'));
+}
+
+function runUnset(argv) {
+	const key = argv[0];
+	if (!key) {
+		console.error('Usage: selva config unset KEY');
+		process.exit(1);
+	}
+	const { envPath, text, env } = readDeploymentEnv();
+	if (!(key in env)) {
+		console.log(pc.dim(`${key} is not set in .env.`));
+		return;
+	}
+	const spec = ALL_SETTINGS.find((s) => s.key === key);
+	if (spec?.required) {
+		console.error(pc.red(`✗ ${key} is required; the app would not start without it.`));
+		process.exit(1);
+	}
+	if (spec?.impact) console.log(pc.yellow(`! ${spec.impact}`));
+	const bak = backUp(envPath);
+	writeEnvText(envPath, setEnvValues(text, { [key]: undefined }));
+	console.log(pc.green(`✓ ${key} removed.`) + (bak ? pc.dim(` Backup: ${bak}`) : ''));
+	console.log(pc.dim('Restart to apply: ') + pc.cyan('selva restart'));
+}