@selvajs/cli 4.8.0-beta.9 → 4.8.0

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`).
-
-## Re-running a command is safe
-
-- `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 a future CLI version knows which config layout it is looking at and can upgrade it 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.8.0-beta.9",
+  "version": "4.8.0",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -34,12 +34,15 @@
     "!**/*.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",

package/src/checks/boot.js

@@ -12,7 +12,10 @@
 
 import { existsSync, readFileSync, accessSync, constants } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { join, resolve, dirname, delimiter } from 'node:path';
+// 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';
 
@@ -22,10 +25,10 @@ export const systemEnv = {
 	env: () => process.env,
 	homedir,
 	exists: existsSync,
-	readFile: (path) => readFileSync(path, 'utf8'),
-	isWritable: (path) => {
+	readFile: (target) => readFileSync(target, 'utf8'),
+	isWritable: (target) => {
 		try {
-			accessSync(path, constants.W_OK);
+			accessSync(target, constants.W_OK);
 			return true;
 		} catch {
 			return false;
@@ -50,15 +53,15 @@ export function checkBootPersistence(dir, env = systemEnv) {
 // 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 ?? join(env.homedir(), '.pm2');
-	if (env.exists(join(pm2Home, 'dump.pm2'))) {
+	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 = join(dir, 'node_modules', '.bin', 'pm2');
+			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
@@ -89,7 +92,7 @@ function checkSystemdUnit(dir, env) {
 		return [yellow(`pm2 systemd unit present but unreadable (${unitPath})`)];
 	}
 
-	const localPm2 = join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
+	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)')];
@@ -102,7 +105,7 @@ function checkSystemdUnit(dir, env) {
 				`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:${join(dir, 'node_modules', '.bin')} ${localPm2} ` +
+				`sudo env PATH=$PATH:${path.join(dir, 'node_modules', '.bin')} ${localPm2} ` +
 				`startup systemd -u $USER --hp $HOME`
 		)
 	];
@@ -116,14 +119,14 @@ function checkStrayGlobalPm2(dir, env) {
 	// 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(dirname(globalPm2));
+	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     (${dirname(globalPm2)} is not writable — needs sudo)`),
+				(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'], {});
@@ -136,13 +139,12 @@ function checkStrayGlobalPm2(dir, env) {
 	];
 }
 
-// Scan PATH for a stray pm2 binary (read-only).
 export function findGlobalPm2(dir, env = systemEnv) {
-	const localBin = resolve(dir, 'node_modules', '.bin');
-	const dirs = (env.env().PATH ?? '').split(delimiter).filter(Boolean);
+	const localBin = path.resolve(dir, 'node_modules', '.bin');
+	const dirs = (env.env().PATH ?? '').split(path.delimiter).filter(Boolean);
 	for (const d of dirs) {
-		if (resolve(d) === localBin) continue;
-		const candidate = join(d, 'pm2');
+		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

@@ -24,11 +24,7 @@ export function checkSecret(value, label) {
 	return green(label);
 }
 
-/**
- * The three provider slots, lowercased and defaulted the same way the runtime
- * defaults them. Returned alongside the checks because the caller decides which
- * provider-specific checks to run from it.
- */
+// Lowercased and defaulted the same way create-selva-providers.ts defaults them.
 export function resolveProviders(env) {
 	return {
 		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
@@ -69,13 +65,109 @@ export function checkOrigin(env) {
 	return green(`ORIGIN=${env.ORIGIN}`);
 }
 
+// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
+// A test in providers/header-auth pins both sides, so drift surfaces in CI.
+export const DEFAULT_HEADER_NAMES = {
+	upn: 'SELVA-UserPrincipalName',
+	email: 'SELVA-Email',
+	displayName: 'SELVA-DisplayName'
+};
+
+// oauth2-proxy's `set_xauthrequest` names. Two proxy styles are documented and
+// both are correct, but they need opposite env config:
+//
+//   rewrite      — Caddy maps X-Auth-Request-* onto SELVA-* before proxying.
+//                  Selva sees SELVA-*, so the overrides must be UNSET.
+//   copy-through — Caddy forwards X-Auth-Request-* unchanged.
+//                  Selva sees those names, so all three must be overridden.
+//
+// Mixing them is the failure this check exists to catch: a name Selva reads but
+// the proxy never sends yields `null` from identifyFromHeaders (for the UPN, a
+// total login failure) with nothing in the logs pointing at the env var.
+const OAUTH2_PROXY_HEADERS = new Set([
+	'x-auth-request-user',
+	'x-auth-request-email',
+	'x-auth-request-preferred-username'
+]);
+
 /**
- * Report env vars that were renamed or replaced.
+ * Reports the header names the provider will actually read, and flags the
+ * combinations that can't match any documented proxy config.
  *
- * 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 is reported here and nowhere else.
+ * Deliberately not a "did you override all three" count: with the rewrite
+ * style, zero overrides is the correct answer, so counting alone would push
+ * operators toward breaking a working deployment.
  */
+export function checkHeaderNames(env) {
+	const resolved = {
+		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
+		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,
+		displayName: env.HEADER_AUTH_DISPLAY_NAME_HEADER || DEFAULT_HEADER_NAMES.displayName
+	};
+	const list = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
+
+	const oauth2 = Object.values(resolved).filter((h) =>
+		OAUTH2_PROXY_HEADERS.has(h.toLowerCase())
+	).length;
+	const defaults = Object.entries(resolved).filter(
+		([slot, name]) => name === DEFAULT_HEADER_NAMES[slot]
+	).length;
+
+	if (oauth2 === 0) {
+		return defaults === 3
+			? green(`header names (bundled defaults): ${list}`)
+			: green(`header names (custom): ${list}`);
+	}
+
+	// Some X-Auth-Request-*, some SELVA-* defaults — neither proxy style emits
+	// that mix, so whichever slots are still on a default are being read from a
+	// header nothing sets.
+	if (defaults > 0) {
+		const stale = Object.entries(resolved)
+			.filter(([slot, name]) => name === DEFAULT_HEADER_NAMES[slot])
+			.map(([slot, name]) => `${slot}=${name}`)
+			.join(', ');
+		return yellow(
+			`header names mix oauth2-proxy and bundled-default names: ${list} — ` +
+				`${stale} will never arrive if your proxy forwards X-Auth-Request-* unchanged. ` +
+				`Either override all three with the X-Auth-Request-* names, or map them to SELVA-* ` +
+				`in the proxy and unset all three overrides.`
+		);
+	}
+
+	return green(`header names (oauth2-proxy pass-through): ${list}`);
+}
+
+// Below this, an annotated .env is just a slightly chatty config file; above it
+// the operator is scrolling past screens of prose that no command can correct.
+const COMMENT_LINE_BUDGET = 40;
+
+/**
+ * Flags a `.env` still carrying the shipped documentation block.
+ *
+ * The block is a snapshot of the release the deployment was installed at.
+ * `migrate` rewrites keys but never prose, so those comments keep describing
+ * vars the code has since renamed or retired — confidently wrong instructions
+ * sitting in the file an operator reaches for first. Nothing breaks, which is
+ * why this is yellow, and why it needs saying at all.
+ */
+export function checkEnvDocumentation(commentLines, fix) {
+	if (commentLines <= COMMENT_LINE_BUDGET) {
+		return green('.env is values-only');
+	}
+	return yellow(
+		`.env carries ~${commentLines} lines of shipped documentation. Comments are ` +
+			`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     ` +
+			`npx selva doctor --fix`,
+		fix
+	);
+}
+
+// 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 = [];
 

package/src/checks/runtime.js

@@ -0,0 +1,372 @@
+// 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 { 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. */
+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),
+		...checkPm2LogRotation(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'
+		)
+	];
+}
+
+// ── 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).
+//
+// `$PM2_HOME/modules/<name>`, NOT `node_modules/` — pm2 keeps installed modules
+// in their own tree. Checking the wrong path made this report "not installed"
+// straight after a successful install, so `--fix` offered the same repair every
+// run.
+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, '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, '');
+	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 };