@selvajs/cli 4.8.0-beta.4 → 4.8.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.0-beta.4",
+  "version": "4.8.0-beta.6",
   "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/__tests__/doctor-node-engine.test.js

@@ -0,0 +1,97 @@
+// Node engine detection in `selva doctor` (issue #176).
+//
+// The CLI carries its own range check rather than importing @selvajs/server:
+// it scaffolds the deployment that installs the runtime, so it cannot depend on
+// it. These pin the two behaviours that matter — the incident direction is
+// caught, and an unparseable range never produces a false failure that would
+// tell an operator to upgrade a Node that is already fine.
+//
+// Run by `pnpm test` via node's built-in runner.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { satisfiesNodeRange } from '../commands/doctor.js';
+
+test('catches the reported incident — Node 20 host, runtime requiring >=22', () => {
+	assert.equal(satisfiesNodeRange('20.20.2', '>=22.0.0'), false);
+});
+
+test('accepts a host that satisfies the floor', () => {
+	assert.equal(satisfiesNodeRange('22.0.0', '>=22.0.0'), true);
+	assert.equal(satisfiesNodeRange('24.16.0', '>=22.0.0'), true);
+});
+
+test('accepts a v-prefixed version, as process.version reports it', () => {
+	assert.equal(satisfiesNodeRange('v22.4.0', '>=22.0.0'), true);
+});
+
+test('is exact at the boundary', () => {
+	assert.equal(satisfiesNodeRange('21.9.9', '>=22.0.0'), false);
+	assert.equal(satisfiesNodeRange('22.0.0', '>22.0.0'), false);
+});
+
+test('handles caret, tilde, alternatives and conjunctions', () => {
+	assert.equal(satisfiesNodeRange('22.5.0', '^22.0.0'), true);
+	assert.equal(satisfiesNodeRange('23.0.0', '^22.0.0'), false);
+	assert.equal(satisfiesNodeRange('22.1.5', '~22.1.0'), true);
+	assert.equal(satisfiesNodeRange('20.0.0', '^18.0.0 || ^20.0.0'), true);
+	assert.equal(satisfiesNodeRange('19.0.0', '^18.0.0 || ^20.0.0'), false);
+	assert.equal(satisfiesNodeRange('20.0.0', '>=18 <21'), true);
+	assert.equal(satisfiesNodeRange('21.0.0', '>=18 <21'), false);
+});
+
+test('treats a bare major or x-range as the whole line', () => {
+	assert.equal(satisfiesNodeRange('22.7.1', '22'), true);
+	assert.equal(satisfiesNodeRange('22.7.1', '22.x'), true);
+	assert.equal(satisfiesNodeRange('23.0.0', '22.x'), false);
+});
+
+test('returns null — never a false failure — when it cannot parse', () => {
+	// A wrong `false` would tell an operator to upgrade a Node that is fine.
+	assert.equal(satisfiesNodeRange('22.0.0', 'lts/*'), null);
+	assert.equal(satisfiesNodeRange('not-a-version', '>=22.0.0'), null);
+	assert.equal(satisfiesNodeRange('22.0.0', ''), null);
+});
+
+test('agrees with @selvajs/server satisfiesRange on the shared cases', () => {
+	// The two implementations are duplicated by necessity; if they diverge, the
+	// admin UI and the CLI would disagree about the same deployment.
+	const cases = [
+		['20.20.2', '>=22.0.0', false],
+		['22.0.0', '>=22.0.0', true],
+		['22.5.0', '^22.0.0', true],
+		['23.0.0', '^22.0.0', false],
+		['20.0.0', '>=18 <21', true],
+		['22.0.0', 'lts/*', null]
+	];
+	for (const [version, range, expected] of cases) {
+		assert.equal(satisfiesNodeRange(version, range), expected, `${version} vs ${range}`);
+	}
+});
+
+// ── The floor itself must not be hardcoded ──────────────────────────────
+
+test('requiredNodeRange reads the CLI package.json, not a copy in code', async () => {
+	const { requiredNodeRange } = await import('../paths.js');
+	const { readFileSync } = await import('node:fs');
+	const { join, dirname } = await import('node:path');
+	const { fileURLToPath } = await import('node:url');
+
+	const here = dirname(fileURLToPath(import.meta.url));
+	const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+
+	// If someone bumps engines.node, this follows automatically. A hardcoded
+	// literal anywhere in the scaffolder would fail here.
+	assert.equal(requiredNodeRange(), pkg.engines.node);
+});
+
+test('the create-time guard tracks a bumped floor', async () => {
+	const { requiredNodeRange } = await import('../paths.js');
+	const range = requiredNodeRange();
+	assert.ok(range, 'engines.node must be declared for the scaffolder to enforce it');
+
+	// The floor is whatever package.json says; a host below it is refused.
+	const floorMajor = Number(/(\d+)/.exec(range)[1]);
+	assert.equal(satisfiesNodeRange(`${floorMajor - 1}.0.0`, range), false);
+	assert.equal(satisfiesNodeRange(`${floorMajor}.0.0`, range), true);
+});

package/src/__tests__/pm2-skew.test.js

@@ -0,0 +1,60 @@
+// PM2 daemon/CLI skew direction (issue #118, defect 2).
+//
+// The old check treated any `out-of-date` report as "run `pm2 update`". That is
+// only correct when the daemon is OLDER than the deployment-local CLI. In the
+// reported incident a global pm2 v6 owned the daemon while the deployment pinned
+// v5.4.3 — `pm2 update` ran the v5 CLI against it, downgrading the daemon and
+// feeding it a v6 dump, so the process table came back empty and selva-compute
+// was never re-registered.
+//
+// Run by `pnpm test` via node's built-in runner.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parsePm2Skew, daemonOutranksCli } from '../commands/pm2.js';
+
+// pm2 colourises through chalk on a TTY; build the codes rather than embedding
+// raw control characters in the source.
+const ESC = String.fromCharCode(27);
+const colour = (s) => `${ESC}[34m${ESC}[1m${s}${ESC}[22m${ESC}[39m`;
+
+const REAL_OUTPUT =
+	`${ESC}[31m${ESC}[1m>>>> In-memory PM2 is out-of-date, do:\n>>>> $ pm2 update${ESC}[22m${ESC}[39m\n` +
+	`In memory PM2 version: ${colour('6.0.14')}\n` +
+	`Local PM2 version: ${colour('5.4.3')}\n`;
+
+test('parses both versions out of real colourised pm2 output', () => {
+	assert.deepEqual(parsePm2Skew(REAL_OUTPUT), { daemon: '6.0.14', local: '5.4.3' });
+});
+
+test('parses plain uncoloured output (non-TTY)', () => {
+	const plain = 'In memory PM2 version: 5.4.3\nLocal PM2 version: 5.4.3\n';
+	assert.deepEqual(parsePm2Skew(plain), { daemon: '5.4.3', local: '5.4.3' });
+});
+
+test('returns nulls when the message shape changes, so callers fall back to resync', () => {
+	assert.deepEqual(parsePm2Skew('something else entirely'), { daemon: null, local: null });
+});
+
+test('flags the incident direction — global daemon newer than the pinned CLI', () => {
+	assert.equal(daemonOutranksCli('6.0.14', '5.4.3'), true);
+});
+
+test('allows the repairable direction — daemon older than the CLI', () => {
+	assert.equal(daemonOutranksCli('5.4.3', '6.0.14'), false);
+});
+
+test('is false when the versions match', () => {
+	assert.equal(daemonOutranksCli('5.4.3', '5.4.3'), false);
+});
+
+test('compares minor and patch, not just major', () => {
+	assert.equal(daemonOutranksCli('5.5.0', '5.4.3'), true);
+	assert.equal(daemonOutranksCli('5.4.4', '5.4.3'), true);
+	assert.equal(daemonOutranksCli('5.4.3', '5.4.4'), false);
+});
+
+test('never blocks on an unparseable version — resync stays the default', () => {
+	assert.equal(daemonOutranksCli(null, '5.4.3'), false);
+	assert.equal(daemonOutranksCli('6.0.14', null), false);
+});

package/src/cli.js

@@ -62,7 +62,7 @@ function printHelp() {
 			'',
 			pc.bold('Commands:'),
 			'  init                    Reconfigure this deployment (prompts again)',
-			'  doctor                  Validate env, providers, and installed packages',
+			'  doctor [--fix]          Validate env, providers, Node engine, and packages',
 			'  start                   pm2 start ecosystem.config.cjs',
 			'  stop                    pm2 stop selva-compute',
 			'  restart                 pm2 restart selva-compute --update-env',

package/src/commands/create.js

@@ -10,13 +10,32 @@ import pc from 'picocolors';
 import { collectConfig, collectConfigFromEnv } from '../prompts.js';
 import { generateKey } from '../secrets.js';
 import { writeEnvFile } from '../env.js';
-import { isEmptyOrMissing } from '../paths.js';
+import { isEmptyOrMissing, requiredNodeRange } from '../paths.js';
+import { satisfiesNodeRange } from './doctor.js';
 
 const CLI_VERSION = '0.1.0';
 
 export async function runCreate(argv) {
 	const { dir: rawDir, force, skipInstall, yes } = parseArgs(argv);
 
+	// Scaffolding under too old a Node produces a deployment that installs
+	// cleanly and passes its health check, then fails only under real traffic —
+	// npm treats an engine mismatch as a warning unless engine-strict is set,
+	// which no deployment sets (issue #176). Refuse at the one moment the
+	// operator is still choosing their environment. The floor comes from this
+	// CLI's own engines.node, so a bump can't leave a stale copy behind.
+	const required = requiredNodeRange();
+	if (required && satisfiesNodeRange(process.versions.node, required) === false) {
+		console.error(
+			`${pc.red('✗')} Selva requires Node ${required}, but this shell runs ` +
+				`v${process.versions.node}.\n` +
+				`  A deployment scaffolded here would install and start, then fail once real\n` +
+				`  requests hit newer Node APIs. Upgrade Node first (nvm, fnm, or your package\n` +
+				`  manager), then re-run this command.`
+		);
+		process.exit(1);
+	}
+
 	const targetDir = resolve(rawDir);
 	if (!isEmptyOrMissing(targetDir) && !force) {
 		console.error(

package/src/commands/doctor.js

@@ -1,7 +1,12 @@
 // Validate deployment without starting it: files, secrets, layout, providers,
-// boot persistence. Read-only; yellow warnings don't fail, red failures exit 1.
+// Node engine, boot persistence. Yellow warnings don't fail, red failures exit 1.
+//
+// Read-only by default. `--fix` applies the repairs attached to individual
+// checks, each behind its own confirmation — and only those needing no root and
+// no runtime restart. See `applyFixes`.
 
 import { existsSync, readFileSync, readdirSync, accessSync, constants, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { join, resolve, dirname, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -14,11 +19,12 @@ import { detectDrift } from './migrate.js';
 const HEX_64 = /^[0-9a-f]{64}$/i;
 const PLACEHOLDER = 'replace-this-with-a-random-32-byte-hex-key';
 
-export async function runDoctor() {
+export async function runDoctor(argv = []) {
+	const fix = argv.includes('--fix');
 	const dir = resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
-	p.intro(pc.bgCyan(pc.black(' selva doctor ')));
+	p.intro(pc.bgCyan(pc.black(fix ? ' selva doctor --fix ' : ' selva doctor ')));
 
 	const checks = [];
 	const env = readEnvFile(join(dir, '.env'));
@@ -72,6 +78,7 @@ export async function runDoctor() {
 	}
 
 	checks.push(checkPackage(dir, '@selvajs/selva'));
+	checks.push(checkNodeEngine(dir));
 	checks.push(checkCliRuntimeAlignment(dir));
 	checks.push(...checkBootPersistence(dir));
 	if (env.ORIGIN) {
@@ -101,12 +108,25 @@ export async function runDoctor() {
 	}
 
 	// ── Render ─────────────────────────────────────────────────────────
+	const resolved = await Promise.all(checks);
 	let failures = 0;
-	for (const c of await Promise.all(checks)) {
+	for (const c of resolved) {
 		console.log('  ' + c.line);
 		if (c.severity === 'red') failures += 1;
 	}
 
+	if (fix) {
+		failures = await applyFixes(resolved, failures);
+	} else {
+		const repairable = resolved.filter((c) => c.fix).length;
+		if (repairable > 0) {
+			p.log.info(
+				`${repairable} issue${repairable === 1 ? '' : 's'} can be repaired automatically — ` +
+					`re-run with \`selva doctor --fix\`.`
+			);
+		}
+	}
+
 	if (failures === 0) {
 		p.outro(pc.green('All checks passed.'));
 	} else {
@@ -115,14 +135,66 @@ export async function runDoctor() {
 	}
 }
 
+/**
+ * Apply the repairs attached to failing checks, each behind its own
+ * confirmation. Returns the updated failure count.
+ *
+ * Nothing here needs root: anything privileged (the systemd unit) or that would
+ * restart this process (a Node upgrade) stays a printed instruction, because a
+ * fixer that dies halfway through its own runtime leaves the operator with no
+ * obvious path back.
+ */
+async function applyFixes(resolved, failures) {
+	const repairs = resolved.filter((c) => c.fix && c.severity !== 'green');
+	if (repairs.length === 0) {
+		p.log.info('Nothing to repair automatically.');
+		return failures;
+	}
+
+	console.log('');
+	p.log.step(`${repairs.length} repair${repairs.length === 1 ? '' : 's'} available`);
+
+	for (const check of repairs) {
+		const approved = await p.confirm({
+			message: check.fix.label,
+			initialValue: false
+		});
+		if (p.isCancel(approved) || !approved) {
+			p.log.info('Skipped.');
+			continue;
+		}
+		let result;
+		try {
+			result = await check.fix.run();
+		} catch (err) {
+			result = red(`repair threw: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		console.log('  ' + result.line);
+		if (result.severity === 'green' && check.severity === 'red') failures -= 1;
+	}
+	return failures;
+}
+
 function green(text) {
 	return { severity: 'green', line: `${pc.green('✓')} ${text}` };
 }
-function yellow(text) {
-	return { severity: 'yellow', line: `${pc.yellow('!')} ${text}` };
+function yellow(text, fix) {
+	return { severity: 'yellow', line: `${pc.yellow('!')} ${text}`, fix };
 }
-function red(text) {
-	return { severity: 'red', line: `${pc.red('✗')} ${text}` };
+function red(text, fix) {
+	return { severity: 'red', line: `${pc.red('✗')} ${text}`, fix };
+}
+
+/**
+ * A repair `--fix` may run. `label` is what the operator is asked to approve;
+ * `run()` performs it and returns a result line.
+ *
+ * Only attach one where the repair is unambiguous and reversible-ish. Anything
+ * needing root, or that restarts the runtime running this process, stays a
+ * printed instruction — a half-applied privileged fix is worse than none.
+ */
+function fixable(label, run) {
+	return { label, run };
 }
 
 function checkFile(path, label) {
@@ -312,6 +384,108 @@ function checkCliRuntimeAlignment(dir) {
 }
 
 // Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
+/**
+ * Does this host's Node satisfy the installed runtime's `engines.node`?
+ *
+ * npm only enforces engines under `engine-strict=true`, which no deployment
+ * sets, so a mismatched install succeeds silently and `/api/health` still
+ * returns 200 — routes using newer APIs throw only under real traffic
+ * (issue #176). Deliberately NOT auto-fixable: upgrading Node is
+ * distro-specific and would restart the process running this check.
+ */
+function checkNodeEngine(dir) {
+	let required;
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(dir, 'node_modules', '@selvajs', 'selva', 'package.json'), 'utf8')
+		);
+		required = pkg.engines?.node;
+	} catch {
+		return yellow('@selvajs/selva engines.node — package.json unreadable, skipped');
+	}
+	if (typeof required !== 'string') {
+		return yellow('@selvajs/selva declares no engines.node — cannot verify this host');
+	}
+
+	const running = process.versions.node;
+	const ok = satisfiesNodeRange(running, required);
+	if (ok === null) {
+		return yellow(`engines.node "${required}" not understood — verify Node v${running} manually`);
+	}
+	if (ok) return green(`Node v${running} satisfies engines.node ${required}`);
+
+	return red(
+		`Node v${running} does NOT satisfy @selvajs/selva's engines.node ${required}.\n     ` +
+			`npm installs it anyway and the health check still passes, so this fails only\n     ` +
+			`under real traffic. Upgrade Node on this host (nvm/fnm or your package manager),\n     ` +
+			`then: npm rebuild && npm run restart`
+	);
+}
+
+/**
+ * Narrow `engines.node` range check — `>=X`, `^`, `~`, `||`, and bare/x-ranges.
+ * Returns null when unparseable so a misread never reports a false failure.
+ *
+ * Mirrors `satisfiesRange` in @selvajs/server/ops. Duplicated because the CLI is
+ * dependency-free by design (it scaffolds the deployment that installs the
+ * runtime, so it cannot import from it).
+ */
+export function satisfiesNodeRange(version, range) {
+	const core = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(version).trim());
+	if (!core) return null;
+	const v = [Number(core[1]), Number(core[2]), Number(core[3])];
+
+	let anyParsed = false;
+	for (const alt of String(range).split('||')) {
+		const clauses = alt.trim().split(/\s+/).filter(Boolean);
+		if (!clauses.length) continue;
+
+		let all = true;
+		let parsed = true;
+		for (const clause of clauses) {
+			const m = /^(>=|<=|>|<|\^|~|=)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/.exec(clause);
+			if (!m) {
+				parsed = false;
+				break;
+			}
+			const op = m[1] ?? '=';
+			const num = (s) => (s == null || s === 'x' || s === '*' ? 0 : Number(s));
+			const t = [Number(m[2]), num(m[3]), num(m[4])];
+			let cmp = 0;
+			for (let i = 0; i < 3; i++) {
+				if (v[i] > t[i]) {
+					cmp = 1;
+					break;
+				}
+				if (v[i] < t[i]) {
+					cmp = -1;
+					break;
+				}
+			}
+			let ok;
+			if (op === '>=') ok = cmp >= 0;
+			else if (op === '>') ok = cmp > 0;
+			else if (op === '<=') ok = cmp <= 0;
+			else if (op === '<') ok = cmp < 0;
+			else if (op === '^') ok = cmp >= 0 && v[0] === t[0];
+			else if (op === '~') ok = cmp >= 0 && v[0] === t[0] && v[1] === t[1];
+			else
+				ok =
+					v[0] === t[0] &&
+					(m[3] == null || m[3] === 'x' || m[3] === '*' || v[1] === t[1]) &&
+					(m[4] == null || m[4] === 'x' || m[4] === '*' || v[2] === t[2]);
+			if (!ok) {
+				all = false;
+				break;
+			}
+		}
+		if (!parsed) continue;
+		anyParsed = true;
+		if (all) return true;
+	}
+	return anyParsed ? false : null;
+}
+
 function checkBootPersistence(dir) {
 	// pm2's boot integration is Linux/systemd-specific. On macOS it's launchd
 	// (different unit path) and on Windows pm2 boot persistence isn't a thing —
@@ -329,7 +503,15 @@ function checkBootPersistence(dir) {
 		out.push(
 			yellow(
 				'pm2 process list not saved — run `npx pm2 save` so a reboot can ' +
-					'resurrect the app (nothing to restore without it)'
+					'resurrect the app (nothing to restore without it)',
+				fixable('run `pm2 save` to persist the current process list', () => {
+					const bin = join(dir, 'node_modules', '.bin', 'pm2');
+					if (!existsSync(bin)) return red('pm2 not installed in this deployment');
+					const r = spawnSync(bin, ['save'], { cwd: dir, encoding: 'utf8' });
+					return (r.status ?? 1) === 0
+						? green('pm2 process list saved')
+						: red(`pm2 save failed: ${(r.stderr || r.stdout || '').trim()}`);
+				})
 			)
 		);
 	}
@@ -376,11 +558,31 @@ function checkBootPersistence(dir) {
 	// Warn if global pm2 is on PATH (root cause of version skew).
 	const globalPm2 = findGlobalPm2(dir);
 	if (globalPm2) {
+		// Only offer the removal when we could actually perform it. A global
+		// install under /usr is root-owned; attempting it would half-fail and
+		// leave the operator worse informed than a printed instruction.
+		let writable = false;
+		try {
+			accessSync(dirname(globalPm2), constants.W_OK);
+			writable = true;
+		} catch {
+			writable = false;
+		}
+
 		out.push(
 			yellow(
 				`a pm2 outside this deployment is on PATH (${globalPm2}) — it can fork a ` +
 					`mismatched daemon and trigger skew. Prefer \`npm run\` wrappers / \`npx pm2\` ` +
-					`from this directory; consider \`npm uninstall -g pm2\`.`
+					`from this directory; consider \`npm uninstall -g pm2\`.` +
+					(writable ? '' : `\n     (${dirname(globalPm2)} is not writable — needs sudo)`),
+				writable
+					? fixable(`uninstall the global pm2 at ${globalPm2}`, () => {
+							const r = spawnSync('npm', ['uninstall', '-g', 'pm2'], { encoding: 'utf8' });
+							return (r.status ?? 1) === 0
+								? green('global pm2 uninstalled')
+								: red(`npm uninstall -g pm2 failed: ${(r.stderr || r.stdout || '').trim()}`);
+						})
+					: undefined
 			)
 		);
 	}

package/src/commands/pm2.js

@@ -25,7 +25,36 @@ function pm2Bin(dir) {
 	return local;
 }
 
-// Check for daemon/CLI version mismatch; run `pm2 update` if stale.
+// Parse the two versions pm2 prints alongside its out-of-date warning:
+//   In memory PM2 version: 6.0.14
+//   Local PM2 version: 5.4.3
+// Returns nulls when the shape changes — callers then fall back to resyncing,
+// which is the pre-existing behaviour.
+export function parsePm2Skew(output) {
+	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
+	const clean = output.replace(/\[[0-9;]*m/g, '');
+	const daemon = /In memory PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean);
+	const local = /Local PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean);
+	return { daemon: daemon?.[1] ?? null, local: local?.[1] ?? null };
+}
+
+/**
+ * True when the running daemon is newer than the deployment-local pm2 — i.e. a
+ * foreign global pm2 owns it. `pm2 update` cannot fix that direction: it
+ * downgrades the daemon and hands it a dump from a newer version, which drops
+ * the process table so selva-compute is never re-registered (issue #118).
+ */
+export function daemonOutranksCli(daemon, local) {
+	if (!daemon || !local) return false;
+	const [a, b] = [daemon.split('.').map(Number), local.split('.').map(Number)];
+	for (let i = 0; i < 3; i++) {
+		if (a[i] > b[i]) return true;
+		if (a[i] < b[i]) return false;
+	}
+	return false;
+}
+
+// Check for daemon/CLI version mismatch; run `pm2 update` only when it can help.
 function ensurePm2InSync(dir) {
 	const bin = pm2Bin(dir);
 	const probe = spawnSync(bin, ['ping'], {
@@ -36,6 +65,16 @@ function ensurePm2InSync(dir) {
 	const output = (probe.stdout ?? '') + (probe.stderr ?? '');
 	if (!/out-of-date/i.test(output)) return;
 
+	const { daemon, local } = parsePm2Skew(output);
+	if (daemonOutranksCli(daemon, local)) {
+		throw new Error(
+			`The running PM2 daemon (v${daemon}) is NEWER than this deployment's pm2 (v${local}), ` +
+				`so a global pm2 owns it. Running \`pm2 update\` would downgrade the daemon and drop ` +
+				`its process table, leaving ${APP_NAME} unregistered. Resolve the conflict first: ` +
+				`\`which -a pm2\`, \`pm2 -v\`, \`pm2 ping\`.`
+		);
+	}
+
 	p.log.warn(
 		'PM2 in-memory daemon is a different version than the deployment-local pm2 — ' +
 			'running `pm2 update` to resync (this briefly restarts managed processes).'

package/src/paths.js

@@ -1,5 +1,25 @@
-import { existsSync, readdirSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The Node floor Selva requires, read from this CLI's own `engines.node`.
+ *
+ * Never hardcode it: the CLI, runtime, and server all declare the same range in
+ * package.json, and a copy in code silently keeps enforcing the old floor after
+ * a bump. Falls back to null (skip the check) rather than guessing a number —
+ * refusing to scaffold on a wrong guess is worse than not checking.
+ */
+export function requiredNodeRange() {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url));
+		const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+		const range = pkg.engines?.node;
+		return typeof range === 'string' ? range : null;
+	} catch {
+		return null;
+	}
+}
 
 // A deployment directory must contain an .env and an ecosystem.config.cjs.
 // Anything else (selva.config.js, node_modules) is "should be there" but the