@selvajs/cli 4.7.4-beta.1 → 4.8.0-beta.11

package/README.md

@@ -8,28 +8,23 @@ CLI for white-label Selva deployments.
 npx @selvajs/cli my-deployment
 ```
 
-Interactive scaffolder. Prompts for provider, tenancy, flags, brand name, admin email. Generates `SELVA_HMAC_KEY` + `SELVA_AT_REST_KEY`. Writes `.env`, `ecosystem.config.cjs`, `package.json`. Runs `npm install`.
+Prompts for provider, tenancy, flags, brand name, admin email; generates `SELVA_HMAC_KEY` and `SELVA_AT_REST_KEY`; writes `.env`, `ecosystem.config.cjs`, `package.json`; runs `npm install`. Refuses to overwrite a non-empty directory unless you pass `--force`.
 
 ## Operate an existing deployment
 
-After install, the package exposes a `selva` bin:
+Installing adds a `selva` bin, scoped to the deployment directory (needs `.env` or `ecosystem.config.cjs` in the cwd):
 
 ```bash
-selva init                  # reconfigure prompts; preserves existing secrets
-selva doctor                # validate env + providers + paths
+selva init                 # reconfigure prompts; keeps existing secrets
+selva doctor [--fix]       # validate env, providers, Node engine, boot persistence
+selva migrate              # bring package.json onto the current layout
 selva start | stop | restart | logs
-selva update                # npm update @selvajs/selva + pm2 restart
+selva update                 # update @selvajs/cli + @selvajs/selva, then restart
 selva keys rotate hmac      # rotate SELVA_HMAC_KEY (logs everyone out)
 selva keys rotate at-rest   # rotate SELVA_AT_REST_KEY (compute API key needs re-entry)
 ```
 
-All operator commands run inside the deployment directory (the one that contains `.env` and `ecosystem.config.cjs`).
-
-## Idempotency rules
-
-- `npx @selvajs/cli` refuses to overwrite a non-empty directory without `--force`.
-- `selva init` reads the current `.env`, lets the user edit, and **never** regenerates `SELVA_HMAC_KEY` / `SELVA_AT_REST_KEY` if they're already set.
-- A `.selva-version` marker is written so future CLI versions can migrate config schema cleanly.
+`selva init` never regenerates `SELVA_HMAC_KEY` or `SELVA_AT_REST_KEY` once they're set — rotating those is `keys rotate`'s job, since it invalidates sessions or encrypted data. A `.selva-version` marker records which CLI version scaffolded the directory, so a later `selva migrate` knows what layout it's upgrading from.
 
 ## Relationship to `@selvajs/selva`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.7.4-beta.1",
+  "version": "4.8.0-beta.11",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -28,18 +28,24 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "picocolors": "^1.1.1"
   },
+  "devDependencies": {
+    "pm2": "7.0.3"
+  },
   "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/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); }\""
+    "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\""
   }
 }

package/src/checks/boot.js

@@ -0,0 +1,151 @@
+// Will a reboot bring the app back?
+//
+// Three things have to line up: pm2 has a saved process list to resurrect, a
+// systemd unit exists to do the resurrecting, and that unit points at THIS
+// deployment's pm2 rather than a global one. Each fails silently — the
+// deployment runs fine until the VM restarts, which is exactly when nobody is
+// watching.
+//
+// Every OS interaction arrives through `env` so the whole matrix (unit missing,
+// unit pointing elsewhere, unit unreadable, stray global pm2) is reachable in a
+// test without a Linux box, a systemd unit, or root.
+
+import { existsSync, readFileSync, accessSync, constants } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+// These checks only ever run on a Linux host (see the platform gate below), so
+// every path here is POSIX. Using the platform-default `node:path` would build
+// backslash paths and split PATH on `;` when the tests run on Windows.
+import { posix as path } from 'node:path';
+import { homedir } from 'node:os';
+import { green, red, yellow, fixable } from './result.js';
+
+/** The real OS. Tests pass a stand-in with the same shape. */
+export const systemEnv = {
+	platform: () => process.platform,
+	env: () => process.env,
+	homedir,
+	exists: existsSync,
+	readFile: (target) => readFileSync(target, 'utf8'),
+	isWritable: (target) => {
+		try {
+			accessSync(target, constants.W_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+	run: (cmd, args, opts) => spawnSync(cmd, args, { ...opts, encoding: 'utf8' })
+};
+
+export function checkBootPersistence(dir, env = systemEnv) {
+	// 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 —
+	// stay silent rather than emit misleading checks.
+	if (env.platform() !== 'linux') return [];
+
+	return [
+		checkSavedProcessList(dir, env),
+		...checkSystemdUnit(dir, env),
+		...checkStrayGlobalPm2(dir, env)
+	];
+}
+
+// dump.pm2 is what `pm2 resurrect` replays. Without it the unit starts pm2 and
+// pm2 starts nothing.
+function checkSavedProcessList(dir, env) {
+	const pm2Home = env.env().PM2_HOME ?? path.join(env.homedir(), '.pm2');
+	if (env.exists(path.join(pm2Home, 'dump.pm2'))) {
+		return green('pm2 process list saved (dump.pm2 present)');
+	}
+	return yellow(
+		'pm2 process list not saved — run `npx pm2 save` so a reboot can ' +
+			'resurrect the app (nothing to restore without it)',
+		fixable('run `pm2 save` to persist the current process list', () => {
+			const bin = path.join(dir, 'node_modules', '.bin', 'pm2');
+			if (!env.exists(bin)) return red('pm2 not installed in this deployment');
+			const r = env.run(bin, ['save'], { cwd: dir });
+			return (r.status ?? 1) === 0
+				? green('pm2 process list saved')
+				: red(`pm2 save failed: ${(r.stderr || r.stdout || '').trim()}`);
+		})
+	);
+}
+
+function checkSystemdUnit(dir, env) {
+	const user = env.env().USER ?? env.env().LOGNAME;
+	const unitPath = user ? `/etc/systemd/system/pm2-${user}.service` : null;
+
+	if (!unitPath || !env.exists(unitPath)) {
+		return [
+			yellow(
+				'pm2 systemd boot unit not installed — the app will NOT restart after a ' +
+					'reboot. Run `npx pm2 startup systemd -u $USER --hp $HOME` and paste the ' +
+					'printed command (point it at this deployment’s pm2).'
+			)
+		];
+	}
+
+	let unit;
+	try {
+		unit = env.readFile(unitPath);
+	} catch {
+		return [yellow(`pm2 systemd unit present but unreadable (${unitPath})`)];
+	}
+
+	const localPm2 = path.join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
+	const execStart = /^ExecStart=(.+)$/m.exec(unit)?.[1] ?? '';
+	if (execStart.includes(localPm2)) {
+		return [green('pm2 systemd boot unit installed (uses deployment-local pm2)')];
+	}
+
+	return [
+		red(
+			`pm2 systemd boot unit points at a different pm2 than this deployment's.\n     ` +
+				`ExecStart: ${execStart || '(not found)'}\n     ` +
+				`expected:  ${localPm2} resurrect\n     ` +
+				`Reboots will resurrect via the wrong pm2 (version skew). Re-run startup ` +
+				`with the local binary:\n     ` +
+				`sudo env PATH=$PATH:${path.join(dir, 'node_modules', '.bin')} ${localPm2} ` +
+				`startup systemd -u $USER --hp $HOME`
+		)
+	];
+}
+
+// A pm2 outside the deployment is the root cause of daemon version skew.
+function checkStrayGlobalPm2(dir, env) {
+	const globalPm2 = findGlobalPm2(dir, env);
+	if (!globalPm2) return [];
+
+	// 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.
+	const writable = env.isWritable(path.dirname(globalPm2));
+
+	return [
+		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\`.` +
+				(writable ? '' : `\n     (${path.dirname(globalPm2)} is not writable — needs sudo)`),
+			writable
+				? fixable(`uninstall the global pm2 at ${globalPm2}`, () => {
+						const r = env.run('npm', ['uninstall', '-g', 'pm2'], {});
+						return (r.status ?? 1) === 0
+							? green('global pm2 uninstalled')
+							: red(`npm uninstall -g pm2 failed: ${(r.stderr || r.stdout || '').trim()}`);
+					})
+				: undefined
+		)
+	];
+}
+
+export function findGlobalPm2(dir, env = systemEnv) {
+	const localBin = path.resolve(dir, 'node_modules', '.bin');
+	const dirs = (env.env().PATH ?? '').split(path.delimiter).filter(Boolean);
+	for (const d of dirs) {
+		if (path.resolve(d) === localBin) continue;
+		const candidate = path.join(d, 'pm2');
+		if (env.exists(candidate)) return candidate;
+	}
+	return null;
+}

package/src/checks/config.js

@@ -0,0 +1,89 @@
+// Checks that read only `.env` values — no filesystem, no network, no
+// subprocesses. These decide whether a deployment is validly configured, so
+// they run on every `selva doctor` regardless of which providers are in play.
+
+import { RENAMED_ENV_VARS, REPLACED_ENV_VARS } from '../env.js';
+import { green, red, yellow } from './result.js';
+
+const HEX_64 = /^[0-9a-f]{64}$/i;
+const PLACEHOLDER = 'replace-this-with-a-random-32-byte-hex-key';
+
+const VALID_AUTH = ['local', 'supabase', 'header'];
+// Header-auth is an auth provider only — it has no data or storage layer.
+const VALID_DATA = ['local', 'supabase'];
+
+/**
+ * Guards SELVA_HMAC_KEY and SELVA_AT_REST_KEY. A placeholder or short key
+ * starts and serves traffic — the damage (forgeable sessions, weak at-rest
+ * encryption) is invisible until someone looks for it.
+ */
+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`);
+	return green(label);
+}
+
+// Lowercased and defaulted the same way create-selva-providers.ts defaults them.
+export function resolveProviders(env) {
+	return {
+		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
+		data: (env.SELVA_DATA_PROVIDER ?? 'local').toLowerCase(),
+		storage: (env.SELVA_STORAGE_PROVIDER ?? 'local').toLowerCase()
+	};
+}
+
+export function checkProviders(providers) {
+	const checks = [];
+	if (!VALID_AUTH.includes(providers.auth)) {
+		checks.push(red(`SELVA_AUTH_PROVIDER="${providers.auth}" — expected local|supabase|header`));
+	}
+	if (!VALID_DATA.includes(providers.data)) {
+		checks.push(red(`SELVA_DATA_PROVIDER="${providers.data}" — expected local|supabase`));
+	}
+	if (!VALID_DATA.includes(providers.storage)) {
+		checks.push(red(`SELVA_STORAGE_PROVIDER="${providers.storage}" — expected local|supabase`));
+	}
+	return checks;
+}
+
+export function checkTenancy(env) {
+	const tenancy = (env.SELVA_TENANCY ?? 'single').toLowerCase();
+	if (tenancy !== 'single' && tenancy !== 'multi') {
+		return red(`SELVA_TENANCY="${tenancy}" — expected single|multi`);
+	}
+	return green(`SELVA_TENANCY=${tenancy}`);
+}
+
+export function checkOrigin(env) {
+	if (!env.ORIGIN) return yellow('ORIGIN unset — required behind a reverse proxy');
+	try {
+		new URL(env.ORIGIN);
+	} catch {
+		return red(`ORIGIN="${env.ORIGIN}" is not a valid URL`);
+	}
+	return green(`ORIGIN=${env.ORIGIN}`);
+}
+
+// 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.
+export function checkDeprecatedEnv(env) {
+	const checks = [];
+
+	for (const [oldName, newName] of Object.entries(RENAMED_ENV_VARS)) {
+		if (env[oldName] === undefined) continue;
+		checks.push(
+			env[newName] === undefined
+				? yellow(`${oldName} is deprecated — \`selva migrate\` renames it to ${newName}`)
+				: yellow(`${oldName} is deprecated and ignored — ${newName} is set and wins`)
+		);
+	}
+
+	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}`));
+	}
+
+	return checks;
+}

package/src/checks/result.js

@@ -0,0 +1,27 @@
+// The shape every `selva doctor` check returns, and the repair a check may
+// carry. Kept apart from the checks themselves so a pure predicate can be
+// tested without pulling in the filesystem and network ones.
+
+import pc from 'picocolors';
+
+export function green(text) {
+	return { severity: 'green', line: `${pc.green('✓')} ${text}` };
+}
+export function yellow(text, fix) {
+	return { severity: 'yellow', line: `${pc.yellow('!')} ${text}`, fix };
+}
+export 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.
+ */
+export function fixable(label, run) {
+	return { label, run };
+}

package/src/checks/runtime.js

@@ -0,0 +1,289 @@
+// What the host provides versus what the deployment brings itself.
+//
+// The split trips operators up: Node and npm come from the host (distro
+// packages, nvm, whatever), pm2 comes from the deployment. Installing pm2 from
+// apt or `npm i -g` looks like the tidy thing to do and produces a daemon that
+// silently fights the local one. These checks name which side of the line each
+// tool is on, so the answer is on screen instead of in a support thread.
+//
+// checkNodeEngine (doctor.js) already validates the running Node against
+// engines.node. Nothing here repeats that — this covers what it can't see: npm,
+// the pm2 install itself, and whether the Node running doctor is the same one
+// pm2 launched the app under.
+
+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 { PM2_VERSION } from '../deployment-package.js';
+
+/** The real OS. Tests pass a stand-in with the same shape. */
+export const runtimeEnv = {
+	platform: () => process.platform,
+	env: () => process.env,
+	homedir,
+	exists: existsSync,
+	readFile: (path) => readFileSync(path, 'utf8'),
+	realpath: (path) => {
+		try {
+			return realpathSync(path);
+		} catch {
+			return path;
+		}
+	},
+	execPath: () => process.execPath,
+	// Signal 0 probes liveness without touching the process. EPERM means it
+	// exists but belongs to another user — alive for our purposes.
+	processAlive: (pid) => {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (err) {
+			return err?.code === 'EPERM';
+		}
+	},
+	run: (cmd, args, opts) =>
+		spawnSync(cmd, args, {
+			...opts,
+			encoding: 'utf8',
+			shell: process.platform === 'win32'
+		})
+};
+
+export function checkRuntimeEnvironment(dir, env = runtimeEnv) {
+	return [
+		checkNpm(env),
+		checkNodeProvenance(env),
+		...checkPm2Install(dir, env),
+		...checkPm2Daemon(dir, env)
+	];
+}
+
+// ── npm ─────────────────────────────────────────────────────────────────
+
+// Debian's `nodejs` package doesn't always pull in `npm`, and some distro
+// splits ship an npm several majors behind the Node beside it. Both only
+// surface at `selva update`, which is the worst moment to discover it.
+const MIN_NPM_MAJOR = 10;
+
+function checkNpm(env) {
+	const probe = env.run('npm', ['--version'], {});
+	const version = String(probe.stdout ?? '')
+		.trim()
+		.split('\n')
+		.pop();
+
+	if ((probe.status ?? 1) !== 0 || !/^\d+\.\d+\.\d+/.test(version ?? '')) {
+		return red(
+			'npm not found on PATH — `selva update` and `npm install` cannot run.\n     ' +
+				'On Debian/Ubuntu the `nodejs` package does not always include it. Install\n     ' +
+				'Node 24 from NodeSource, which bundles a matching npm:\n     ' +
+				'curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs'
+		);
+	}
+
+	const major = Number(/^(\d+)\./.exec(version)[1]);
+	if (major < MIN_NPM_MAJOR) {
+		return yellow(
+			`npm ${version} is older than the Node beside it usually ships (expected >= ${MIN_NPM_MAJOR}).\n     ` +
+				'A distro-split npm can resolve dependencies the runtime does not expect.\n     ' +
+				'Install Node from NodeSource so npm and Node come from one source.'
+		);
+	}
+	return green(`npm ${version} on PATH`);
+}
+
+// ── Node provenance ─────────────────────────────────────────────────────
+
+// Which Node runs the app is decided by pm2's environment, not by the shell
+// running doctor. When those differ — a distro Node on PATH for the login
+// shell, an nvm Node for the daemon, or the reverse — doctor validates a
+// version the app never uses, and engines.node passes while production runs
+// something else entirely.
+function checkNodeProvenance(env) {
+	const running = env.realpath(env.execPath());
+	const source = describeNodeSource(running);
+
+	const which = env.run(env.platform() === 'win32' ? 'where' : 'which', ['node'], {});
+	const onPath = String(which.stdout ?? '')
+		.trim()
+		.split('\n')[0]
+		?.trim();
+
+	if (!onPath) {
+		return yellow(`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`);
+	}
+
+	if (env.realpath(onPath) === running) {
+		return green(`Node v${process.versions.node} — ${source} (${running})`);
+	}
+
+	return yellow(
+		`Two Node installations are in play: this shell resolves \`node\` to ${env.realpath(onPath)},\n     ` +
+			`but doctor is running under ${running} (${source}). pm2 launches the app with the\n     ` +
+			`Node it inherited when the daemon started, which may be neither. Confirm with:\n     ` +
+			`npx pm2 describe selva-compute | grep -i "node.js version"`
+	);
+}
+
+// nvm/fnm-managed Nodes disappear for a systemd unit that starts before the
+// user's shell profile runs — worth naming the manager rather than the path.
+function describeNodeSource(path) {
+	const p = path.replace(/\\/g, '/');
+	if (/\/\.nvm\//.test(p)) return 'nvm-managed';
+	if (/\/\.fnm\/|\/fnm_multishells\//.test(p)) return 'fnm-managed';
+	if (/\/\.volta\//.test(p)) return 'volta-managed';
+	if (/^\/usr\/bin\/|^\/bin\//.test(p)) return 'distro package';
+	if (/^\/usr\/local\//.test(p)) return 'manual /usr/local install';
+	if (/\/snap\//.test(p)) return 'snap package';
+	return 'unknown source';
+}
+
+// ── pm2 install ─────────────────────────────────────────────────────────
+
+// The deployment pins pm2 exactly (see deployment-package.js). This verifies
+// the pin actually landed — a hand-edited package.json, a partial install, or
+// an operator who ran `npm i -g pm2` and deleted the local one all end here.
+function checkPm2Install(dir, env) {
+	const out = [];
+	const pkgPath = join(dir, 'node_modules', 'pm2', 'package.json');
+
+	if (!env.exists(pkgPath)) {
+		out.push(
+			red(
+				`pm2 is not installed in this deployment (expected ${join(dir, 'node_modules', 'pm2')}).\n     ` +
+					'Selva ships its own pinned pm2 on purpose — the `selva` commands refuse to fall\n     ' +
+					'back to a global one, because two pm2 versions sharing a daemon hang restarts.\n     ' +
+					'Fix: npm install'
+			)
+		);
+		return out;
+	}
+
+	let installed = null;
+	try {
+		installed = JSON.parse(env.readFile(pkgPath)).version ?? null;
+	} catch {
+		// Unreadable package.json — reported below as an unverifiable version.
+	}
+
+	if (!installed) {
+		out.push(yellow('pm2 installed but its version is unreadable — cannot verify the pin'));
+	} else if (installed === PM2_VERSION) {
+		out.push(green(`pm2 ${installed} installed locally (matches the pinned version)`));
+	} else {
+		out.push(
+			yellow(
+				`pm2 ${installed} is installed but this scaffold pins ${PM2_VERSION}.\n     ` +
+					'The pin is exact because pm2 CLI and daemon must match. Realign it:\n     ' +
+					`npm install pm2@${PM2_VERSION} && npx pm2 update`
+			)
+		);
+	}
+
+	// A pm2 listed in dependencies with a range instead of the exact pin means
+	// package.json was hand-edited; the next `npm install` silently drifts again.
+	const declared = readDeclaredPm2(dir, env);
+	if (declared && declared !== PM2_VERSION) {
+		out.push(
+			yellow(
+				`package.json declares pm2 "${declared}" rather than the exact pin ${PM2_VERSION}.\n     ` +
+					'A range lets a later `npm install` adopt a version the running daemon is not.\n     ' +
+					'Run `selva migrate` to restore the canonical package.json.'
+			)
+		);
+	}
+
+	return out;
+}
+
+function readDeclaredPm2(dir, env) {
+	try {
+		const pkg = JSON.parse(env.readFile(join(dir, 'package.json')));
+		return pkg.dependencies?.pm2 ?? null;
+	} catch {
+		return null;
+	}
+}
+
+// ── pm2 daemon ──────────────────────────────────────────────────────────
+
+// Reports three distinct states rather than pass/fail: no daemon (fine,
+// nothing started yet), a matching daemon, or a daemon a foreign pm2 owns.
+//
+// `pm2 ping` SPAWNS a daemon when none is running, and doctor must stay
+// read-only — so liveness is checked via pm2.pid + signal 0 first, and pm2
+// itself is only invoked once a live daemon is confirmed.
+//
+// The daemon-is-newer direction is red and deliberately offers no fix: `pm2
+// update` would downgrade the daemon and drop its process table, leaving
+// selva-compute unregistered. Same reasoning as ensurePm2InSync in commands/pm2.js.
+function checkPm2Daemon(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');
+	const pidPath = join(pm2Home, 'pm2.pid');
+	if (!env.exists(pidPath)) {
+		return [yellow('pm2 daemon is not running — it starts on `selva start`')];
+	}
+	let pid = NaN;
+	try {
+		pid = Number(String(env.readFile(pidPath)).trim());
+	} catch {
+		// Unreadable pid file — fall through to the stale case.
+	}
+	if (!Number.isInteger(pid) || pid <= 0 || !env.processAlive(pid)) {
+		return [yellow('pm2 daemon is not running (stale pm2.pid) — it starts on `selva start`')];
+	}
+
+	const probe = env.run(bin, ['ping'], { cwd: dir });
+	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')];
+		return [yellow('pm2 daemon did not answer `pm2 ping` — check `npx pm2 ping` by hand')];
+	}
+
+	const { daemon, local } = parseSkew(output);
+	if (daemon && local && compareVersions(daemon, local) > 0) {
+		return [
+			red(
+				`The running pm2 daemon (v${daemon}) is NEWER than this deployment's pm2 (v${local}),\n     ` +
+					'so a pm2 from outside the deployment owns it. `pm2 update` would downgrade the\n     ' +
+					'daemon and drop its process table, so `selva start` refuses outright.\n     ' +
+					'Resolve it (the app goes down briefly):\n     ' +
+					`npx pm2 kill && sudo npm uninstall -g pm2 && npm install && npm start\n     ` +
+					'Then re-run: npx pm2 save && npx pm2 startup systemd -u $USER --hp $HOME'
+			)
+		];
+	}
+
+	return [
+		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'
+		)
+	];
+}
+
+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,
+		local: /Local PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean)?.[1] ?? null
+	};
+}
+
+function compareVersions(a, b) {
+	const [x, y] = [a.split('.').map(Number), b.split('.').map(Number)];
+	for (let i = 0; i < 3; i++) {
+		if (x[i] > y[i]) return 1;
+		if (x[i] < y[i]) return -1;
+	}
+	return 0;
+}
+
+export { describeNodeSource, compareVersions, MIN_NPM_MAJOR };

package/src/cli.js

@@ -62,12 +62,12 @@ 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',
 			'  logs                    pm2 logs selva-compute',
-			'  update                  npm update @selvajs/selva + restart',
+			'  update                  npm update @selvajs/cli + @selvajs/selva, then restart',
 			'  migrate                 Bring package.json onto the current layout',
 			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
 			'',