@selvajs/cli 4.7.4-beta.0 → 4.8.0-beta.10

package/README.md

@@ -25,11 +25,11 @@ selva keys rotate at-rest   # rotate SELVA_AT_REST_KEY (compute API key needs re
 
 All operator commands run inside the deployment directory (the one that contains `.env` and `ecosystem.config.cjs`).
 
-## Idempotency rules
+## 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 future CLI versions can migrate config schema cleanly.
+- A `.selva-version` marker is written so a future CLI version knows which config layout it is looking at and can upgrade it cleanly.
 
 ## Relationship to `@selvajs/selva`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.7.4-beta.0",
+  "version": "4.8.0-beta.10",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -28,10 +28,13 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
@@ -40,6 +43,6 @@
   "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,149 @@
+// 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';
+import { join, resolve, dirname, delimiter } 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: (path) => readFileSync(path, 'utf8'),
+	isWritable: (path) => {
+		try {
+			accessSync(path, 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 ?? join(env.homedir(), '.pm2');
+	if (env.exists(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');
+			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 = 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:${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(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
+				? 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
+		)
+	];
+}
+
+// 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);
+	for (const d of dirs) {
+		if (resolve(d) === localBin) continue;
+		const candidate = join(d, 'pm2');
+		if (env.exists(candidate)) return candidate;
+	}
+	return null;
+}

package/src/checks/config.js

@@ -0,0 +1,97 @@
+// 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);
+}
+
+/**
+ * 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.
+ */
+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}`);
+}
+
+/**
+ * Report env vars that were renamed or replaced.
+ *
+ * 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.
+ */
+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/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

@@ -3,20 +3,43 @@
 // templates are the source of truth; providers are env-driven.
 
 import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
-import { resolve, join, basename } from 'node:path';
+import { resolve, join, basename, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import * as p from '@clack/prompts';
 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';
-
-const CLI_VERSION = '0.1.0';
+import {
+	isEmptyOrMissing,
+	requiredNodeRange,
+	runtimeTemplatePath,
+	scaffoldVersion
+} from '../paths.js';
+import { buildDeploymentPackageJson } from '../deployment-package.js';
+import { satisfiesNodeRange } from '../node-range.js';
 
 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(
@@ -40,7 +63,7 @@ export async function runCreate(argv) {
 	const deployName = basename(targetDir);
 
 	// Write package.json, then install (need templates from @selvajs/selva).
-	const pkgJson = buildPackageJson(deployName, values);
+	const pkgJson = JSON.stringify(buildDeploymentPackageJson({ name: deployName }), null, 2);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
 	if (!skipInstall) {
@@ -52,23 +75,23 @@ export async function runCreate(argv) {
 	}
 
 	// Copy templates from installed runtime.
-	const runtimeTemplates = join(targetDir, 'node_modules', '@selvajs', 'selva', 'templates');
-	if (skipInstall || !existsSync(runtimeTemplates)) {
+	const envTemplatePath = runtimeTemplatePath(targetDir, '.env.example');
+	const ecosystemTemplatePath = runtimeTemplatePath(targetDir, 'ecosystem.config.cjs');
+	if (skipInstall || !existsSync(envTemplatePath)) {
 		p.log.warn(
-			`Couldn't read runtime templates from ${runtimeTemplates}. ` +
+			`Couldn't read runtime templates from ${dirname(envTemplatePath)}. ` +
 				`Run \`npm install\`, then \`selva init\` to finish setup.`
 		);
-		writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
+		writeFileSync(join(targetDir, '.selva-version'), scaffoldVersion() + '\n', 'utf8');
 		p.outro(`Partial scaffold at ${pc.cyan(targetDir)}.`);
 		return;
 	}
 
-	const envTemplate = readFileSync(join(runtimeTemplates, '.env.example'), 'utf8');
-	writeEnvFile(join(targetDir, '.env'), envTemplate, values);
+	writeEnvFile(join(targetDir, '.env'), readFileSync(envTemplatePath, 'utf8'), values);
 
-	cpSync(join(runtimeTemplates, 'ecosystem.config.cjs'), join(targetDir, 'ecosystem.config.cjs'));
+	cpSync(ecosystemTemplatePath, join(targetDir, 'ecosystem.config.cjs'));
 
-	writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
+	writeFileSync(join(targetDir, '.selva-version'), scaffoldVersion() + '\n', 'utf8');
 	writeGitignore(targetDir);
 
 	p.outro(
@@ -173,7 +196,7 @@ function runNpmInstall(cwd) {
 				console.error(
 					pc.yellow(
 						'npm resolved @selvajs/selva@0.10.2 — that version is broken (unresolved\n' +
-							"workspace:* / catalog: specs) and has been unpublished. Your local npm\n" +
+							'workspace:* / catalog: specs) and has been unpublished. Your local npm\n' +
 							'cache is stale. Clear it and retry:\n\n' +
 							'  npm cache clean --force\n' +
 							'  rm -rf node_modules package-lock.json\n' +
@@ -205,9 +228,7 @@ function parseArgs(argv) {
 		}
 	}
 	if (!dir) {
-		throw new Error(
-			'Usage: npx @selvajs/cli <directory> [--force] [--skip-install] [--yes]'
-		);
+		throw new Error('Usage: npx @selvajs/cli <directory> [--force] [--skip-install] [--yes]');
 	}
 	return { dir, force, skipInstall, yes };
 }
@@ -217,44 +238,6 @@ function envBool(v) {
 	return ['1', 'true', 'yes'].includes(String(v).toLowerCase());
 }
 
-// Depends on @selvajs/selva (prebuilt) + @selvajs/cli (operator tool).
-// @selvajs/cli links the `selva` bin; without it, only global CLI works.
-function buildPackageJson(name /*, values */) {
-	const deps = {
-		'@selvajs/cli': 'latest',
-		'@selvajs/selva': 'latest',
-		// Deployment-local pm2 (pinned exact to prevent daemon version skew).
-		pm2: '5.4.3'
-	};
-
-	const pkg = {
-		name: sanitizePackageName(name),
-		version: '0.1.0',
-		private: true,
-		type: 'module',
-		scripts: {
-			start: 'selva start',
-			stop: 'selva stop',
-			restart: 'selva restart',
-			logs: 'selva logs',
-			doctor: 'selva doctor',
-			update: 'selva update'
-		},
-		dependencies: deps
-	};
-	return JSON.stringify(pkg, null, 2);
-}
-
-function sanitizePackageName(name) {
-	// npm package names: lowercase, no spaces, limited punctuation.
-	return (
-		name
-			.toLowerCase()
-			.replace(/[^a-z0-9._-]+/g, '-')
-			.replace(/^[-._]+|[-._]+$/g, '') || 'selva-deployment'
-	);
-}
-
 function writeGitignore(dir) {
 	const path = join(dir, '.gitignore');
 	if (existsSync(path)) return;