@selvajs/cli 4.8.0-beta.8 → 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.8",
+  "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,15 +34,18 @@
     "!**/*.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); }\" && node --test \"./src/__tests__/*.test.js\""
+    "test": "node --check ./bin/cli.js && node --check ./bin/selva.js && node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/node-range.js','./src/deployment-package.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js']) { 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,189 @@
+// 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}`);
+}
+
+// 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'
+]);
+
+/**
+ * Reports the header names the provider will actually read, and flags the
+ * combinations that can't match any documented proxy config.
+ *
+ * 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 = [];
+
+	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 };
+}