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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.0-beta.12",
+  "version": "4.8.0-beta.13",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",

package/src/checks/config.js

@@ -160,7 +160,7 @@ export function checkEnvDocumentation(commentLines, fix) {
 			`never updated by \`selva migrate\`, so they still describe the release this ` +
 			`deployment was installed at — including variables the code no longer reads. ` +
 			`Strip them (values and your own inline notes are kept, .env.bak written):\n     ` +
-			`selva doctor --fix`,
+			`npx selva doctor --fix`,
 		fix
 	);
 }

package/src/checks/runtime.js

@@ -15,7 +15,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { green, red, yellow } from './result.js';
+import { fixable, green, red, yellow } from './result.js';
 import { PM2_VERSION } from '../deployment-package.js';
 
 /** The real OS. Tests pass a stand-in with the same shape. */
@@ -56,7 +56,8 @@ export function checkRuntimeEnvironment(dir, env = runtimeEnv) {
 		checkNpm(env),
 		checkNodeProvenance(env),
 		...checkPm2Install(dir, env),
-		...checkPm2Daemon(dir, env)
+		...checkPm2Daemon(dir, env),
+		...checkPm2LogRotation(dir, env)
 	];
 }
 
@@ -270,6 +271,81 @@ function checkPm2Daemon(dir, env) {
 	];
 }
 
+// ── pm2 log rotation ────────────────────────────────────────────────────
+
+// pm2 appends to `$PM2_HOME/logs/*.log` forever. Nothing in a default install
+// truncates them, and the app writes a line per solve — so the only bound is
+// the disk. It fails late and all at once: the partition fills, and pm2 and the
+// app go down together on a box that looked healthy the day before.
+//
+// Detected from the filesystem, never by running `pm2 ls`: an invocation with
+// no live daemon spawns one as a side effect, which doctor must not do (see
+// checkPm2Daemon). Installed modules live in `$PM2_HOME/node_modules`.
+function checkPm2LogRotation(dir, env) {
+	const bin = join(dir, 'node_modules', '.bin', env.platform() === 'win32' ? 'pm2.cmd' : 'pm2');
+	if (!env.exists(bin)) return [];
+
+	const pm2Home = env.env().PM2_HOME ?? join(env.homedir(), '.pm2');
+	if (env.exists(join(pm2Home, 'node_modules', 'pm2-logrotate'))) {
+		return [green('pm2-logrotate installed — pm2 logs are rotated')];
+	}
+
+	return [
+		yellow(
+			'pm2-logrotate is not installed — pm2 logs grow without bound and are only\n     ' +
+				'capped by free disk. Install it (takes effect immediately, no restart):\n     ' +
+				'npx pm2 install pm2-logrotate\n     ' +
+				`npx pm2 set pm2-logrotate:rotateInterval "${LOGROTATE_SETTINGS.rotateInterval}"\n     ` +
+				`npx pm2 set pm2-logrotate:retain ${LOGROTATE_SETTINGS.retain}\n     ` +
+				`npx pm2 set pm2-logrotate:compress ${LOGROTATE_SETTINGS.compress}`,
+			fixable('install pm2-logrotate (weekly rotation, 8 kept, compressed)', () =>
+				installLogRotate(bin, dir, env)
+			)
+		)
+	];
+}
+
+/**
+ * Weekly on Sunday 00:00, keeping 8 — about two months of history, compressed.
+ *
+ * Weekly rather than pm2's daily default: a Selva deployment writes a line per
+ * solve, so daily files are mostly idle days, and two months of them is a lot
+ * of near-empty archives to page through when tracing an incident.
+ */
+const LOGROTATE_SETTINGS = {
+	rotateInterval: '0 0 * * 0',
+	retain: 8,
+	compress: true
+};
+
+// `pm2 install` needs no root and doesn't restart managed processes, which is
+// what makes it eligible as a doctor fixer at all. The settings are applied
+// after: failing to set one leaves rotation on at pm2's defaults, which still
+// beats unbounded growth, so a failed `set` is reported, not fatal.
+function installLogRotate(bin, dir, env) {
+	const install = env.run(bin, ['install', 'pm2-logrotate'], { cwd: dir });
+	if ((install.status ?? 1) !== 0) {
+		const detail = String(install.stderr ?? install.stdout ?? '')
+			.trim()
+			.split('\n')
+			.pop();
+		return red(`\`pm2 install pm2-logrotate\` failed${detail ? `: ${detail}` : ''}`);
+	}
+
+	const failed = [];
+	for (const [key, value] of Object.entries(LOGROTATE_SETTINGS)) {
+		const set = env.run(bin, ['set', `pm2-logrotate:${key}`, String(value)], { cwd: dir });
+		if ((set.status ?? 1) !== 0) failed.push(key);
+	}
+	if (failed.length > 0) {
+		return yellow(
+			`pm2-logrotate installed, but could not set: ${failed.join(', ')}. ` +
+				`Rotation is active at pm2's defaults; set them by hand with \`npx pm2 set\`.`
+		);
+	}
+	return green('pm2-logrotate installed — weekly rotation, 8 kept, compressed');
+}
+
 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, '');

package/src/cli.js

@@ -18,6 +18,59 @@ const COMMANDS = {
 	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
 };
 
+// `selva doctor --help` used to run the full doctor: commands own their argv,
+// and only `doctor` reads a flag at all, so every other command silently
+// ignored `--help` and did its work. Intercepting here keeps `--help` uniform
+// across the whole surface without each command re-implementing it.
+const USAGE = {
+	init: {
+		usage: 'selva init',
+		blurb:
+			'Reconfigure this deployment. Prompts for the same values as scaffolding\nand rewrites .env; generated secrets are left alone.'
+	},
+	doctor: {
+		usage: 'selva doctor [--fix]',
+		blurb:
+			'Validate .env, providers, Node engine, pm2 boot persistence, and package\npins. Read-only without --fix.',
+		flags: [['--fix', 'Apply the repairs doctor reports as automatic. Prompts before each.']]
+	},
+	start: { usage: 'selva start', blurb: 'pm2 start ecosystem.config.cjs' },
+	stop: { usage: 'selva stop', blurb: 'pm2 stop selva-compute' },
+	restart: {
+		usage: 'selva restart',
+		blurb:
+			'pm2 restart selva-compute --update-env. The --update-env is why this\nexists: without it a pm2 restart keeps the old .env in memory.'
+	},
+	logs: { usage: 'selva logs', blurb: 'pm2 logs selva-compute' },
+	update: {
+		usage: 'selva update',
+		blurb:
+			'npm update @selvajs/cli + @selvajs/selva, then restart. Rolls the\ndependency tree back if the install fails.'
+	},
+	migrate: {
+		usage: 'selva migrate',
+		blurb:
+			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
+	},
+	keys: {
+		usage: 'selva keys rotate <hmac|at-rest>',
+		blurb:
+			'Rotate one secret in .env. Destructive and not reversible — the command\nspells out the blast radius and asks before writing.'
+	}
+};
+
+function printCommandHelp(command) {
+	const entry = USAGE[command];
+	const lines = [pc.bold(entry.usage), '', entry.blurb];
+	if (entry.flags) {
+		lines.push('', pc.bold('Flags:'));
+		for (const [flag, description] of entry.flags) {
+			lines.push(`  ${flag.padEnd(22)}${description}`);
+		}
+	}
+	console.log(lines.join('\n'));
+}
+
 function keysDispatch(m) {
 	return async (argv) => {
 		const sub = argv[0];
@@ -51,6 +104,11 @@ export async function runSelva(argv) {
 		process.exit(1);
 	}
 
+	if (rest.includes('--help') || rest.includes('-h')) {
+		printCommandHelp(command);
+		return;
+	}
+
 	const run = await loader();
 	await run(rest);
 }
@@ -60,6 +118,8 @@ function printHelp() {
 		[
 			pc.bold('selva') + ' — operate a Selva deployment',
 			'',
+			pc.bold('Usage:') + '  npx selva <command>',
+			'',
 			pc.bold('Commands:'),
 			'  init                    Reconfigure this deployment (prompts again)',
 			'  doctor [--fix]          Validate env, providers, Node engine, and packages',
@@ -71,7 +131,15 @@ function printHelp() {
 			'  migrate                 Bring package.json onto the current layout',
 			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
 			'',
-			pc.dim('To scaffold a new deployment: ') + pc.cyan('npx @selvajs/cli <dir>')
+			pc.dim('`npx selva <command> --help` explains one command.'),
+			'',
+			pc.bold('Two commands, two jobs:'),
+			'  ' + pc.cyan('npx @selvajs/cli <dir>') + '   scaffold a NEW deployment into <dir>',
+			'  ' + pc.cyan('npx selva <command>') + '      operate the deployment you are standing in',
+			'',
+			pc.dim('`npx selva` works in a deployment directory because @selvajs/cli is one of'),
+			pc.dim('its dependencies. The package.json scripts (`npm run doctor`, `npm start`)'),
+			pc.dim('are thin aliases for the same commands.')
 		].join('\n')
 	);
 }

package/src/commands/create.js

@@ -215,11 +215,37 @@ function runNpmInstall(cwd) {
 	});
 }
 
+// `npx @selvajs/cli` resolves to the `cli` bin — the scaffolder — while every
+// operate command lives on the sibling `selva` bin. So `npx @selvajs/cli doctor
+// --fix` lands here, where "doctor" is just a directory name and `--fix` an
+// unknown flag. Name the bin split rather than letting the operator conclude
+// their CLI is too old for a flag it has shipped for releases.
+const OPERATE_COMMANDS = new Set([
+	'doctor',
+	'start',
+	'stop',
+	'restart',
+	'logs',
+	'update',
+	'migrate',
+	'keys',
+	'init'
+]);
+
 function parseArgs(argv) {
 	let dir;
 	let force = false;
 	let skipInstall = false;
 	let yes = false;
+
+	if (OPERATE_COMMANDS.has(argv[0])) {
+		throw new Error(
+			`\`${argv[0]}\` is an operate command, but \`npx @selvajs/cli\` runs the scaffolder.\n` +
+				`  Run it through the deployment's own CLI instead:\n` +
+				`    npx selva ${argv.join(' ')}`
+		);
+	}
+
 	for (const arg of argv) {
 		if (arg === '--force') force = true;
 		else if (arg === '--skip-install') skipInstall = true;

package/src/commands/doctor.js

@@ -36,7 +36,7 @@ import {
 	checkTenancy,
 	resolveProviders
 } from '../checks/config.js';
-import { detectDrift, NODE_MODULES_STASH } from './migrate.js';
+import { BACKUP_AGE_DAYS, classifyBackups, detectDrift, NODE_MODULES_STASH } from './migrate.js';
 
 export async function runDoctor(argv = []) {
 	const fix = argv.includes('--fix');
@@ -52,6 +52,7 @@ export async function runDoctor(argv = []) {
 	checks.push(checkFile(join(dir, 'ecosystem.config.cjs'), 'ecosystem.config.cjs present'));
 	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'));
 
@@ -99,7 +100,7 @@ export async function runDoctor(argv = []) {
 		if (repairable > 0) {
 			p.log.info(
 				`${repairable} issue${repairable === 1 ? '' : 's'} can be repaired automatically — ` +
-					`re-run with \`selva doctor --fix\`.`
+					`re-run with \`npx selva doctor --fix\`.`
 			);
 		}
 	}
@@ -377,6 +378,42 @@ function checkMigrationLeftovers(dir) {
 	);
 }
 
+// Migration backups are timestamped so a later migration can't overwrite an
+// earlier one's (#184), which means they accumulate. Deleting them silently
+// would throw away the operator's only copy of a pre-migration config, so this
+// reports and lets `--fix` opt in. `classifyBackups` always keeps the newest
+// run, so the escape hatch is never emptied — only superseded generations go.
+function checkAgedBackups(dir) {
+	let names;
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return green('no aged migration backups');
+	}
+
+	const { aged } = classifyBackups(names);
+	if (aged.length === 0) return green('no aged migration backups');
+
+	const shown = aged.slice(0, 3).join(', ');
+	const more = aged.length > 3 ? `, +${aged.length - 3} more` : '';
+	return yellow(
+		`${aged.length} migration backup${aged.length === 1 ? '' : 's'} older than ` +
+			`${BACKUP_AGE_DAYS} days (${shown}${more}). The newest set is kept either way.`,
+		fixable(`delete ${aged.length} aged migration backup${aged.length === 1 ? '' : 's'}`, () => {
+			const failed = [];
+			for (const name of aged) {
+				try {
+					rmSync(join(dir, name), { force: true });
+				} catch (err) {
+					failed.push(`${name} (${err instanceof Error ? err.message : err})`);
+				}
+			}
+			if (failed.length > 0) return red(`could not remove: ${failed.join(', ')}`);
+			return green(`removed ${aged.length} aged backup${aged.length === 1 ? '' : 's'}`);
+		})
+	);
+}
+
 // Reads the raw file rather than the parsed env: the finding IS the comments,
 // which parseEnv discards. The repair is attached here (not in checks/config.js)
 // to keep that module filesystem-free.

package/src/commands/migrate.js

@@ -27,6 +27,74 @@ import { APP_NAME, runPm2 } from './pm2.js';
 // 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 };
+}
+
 // `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.
@@ -135,17 +203,24 @@ export async function runMigrate(
 		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
-	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');
+		copyFileSync(ecoPath, ecoBak);
 		// Text substitution, not regeneration, so any operator customizations to the file survive.
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
@@ -155,7 +230,7 @@ export async function runMigrate(
 	}
 
 	if (envRename.changes.length > 0) {
-		copyFileSync(envPath, envPath + '.bak');
+		copyFileSync(envPath, envBak);
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
@@ -182,14 +257,14 @@ export async function runMigrate(
 	} catch (err) {
 		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);
 		}
 
 		// A half-installed node_modules from the failed attempt is worse than the old
@@ -224,10 +299,10 @@ export async function runMigrate(
 	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');
-	if (envRename.changes.length > 0) backupHints.push('.env.bak');
+	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(