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

package/src/commands/doctor.js

@@ -1,24 +1,44 @@
 // Validate deployment without starting it: files, secrets, layout, providers,
-// boot persistence. Read-only; yellow warnings don't fail, red failures exit 1.
-
-import { existsSync, readFileSync, readdirSync, accessSync, constants, statSync } from 'node:fs';
-import { join, resolve, dirname, delimiter } from 'node:path';
+// 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,
+	rmSync
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readEnvFile } from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
-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() {
+import { satisfiesNodeRange } from '../node-range.js';
+import { green, yellow, red, fixable } from '../checks/result.js';
+import { checkBootPersistence } from '../checks/boot.js';
+import {
+	checkDeprecatedEnv,
+	checkOrigin,
+	checkProviders,
+	checkSecret,
+	checkTenancy,
+	resolveProviders
+} from '../checks/config.js';
+import { detectDrift, NODE_MODULES_STASH } from './migrate.js';
+
+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'));
@@ -26,28 +46,12 @@ export async function runDoctor() {
 	checks.push(checkFile(join(dir, '.env'), '.env present'));
 	checks.push(checkFile(join(dir, 'ecosystem.config.cjs'), 'ecosystem.config.cjs present'));
 	checks.push(checkLayoutDrift(dir));
+	checks.push(checkMigrationLeftovers(dir));
 	checks.push(checkSecret(env.SELVA_HMAC_KEY, 'SELVA_HMAC_KEY is a 32-byte hex string'));
 	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte hex string'));
 
-	// Header-auth: auth only; data/storage must be local or supabase.
-	const providers = {
-		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
-		data: (env.SELVA_DATA_PROVIDER ?? 'local').toLowerCase(),
-		storage: (env.SELVA_STORAGE_PROVIDER ?? 'local').toLowerCase()
-	};
-
-	const validForAuth = new Set(['local', 'supabase', 'header']);
-	const validForData = new Set(['local', 'supabase']);
-
-	if (!validForAuth.has(providers.auth)) {
-		checks.push(red(`SELVA_AUTH_PROVIDER="${providers.auth}" — expected local|supabase|header`));
-	}
-	if (!validForData.has(providers.data)) {
-		checks.push(red(`SELVA_DATA_PROVIDER="${providers.data}" — expected local|supabase`));
-	}
-	if (!validForData.has(providers.storage)) {
-		checks.push(red(`SELVA_STORAGE_PROVIDER="${providers.storage}" — expected local|supabase`));
-	}
+	const providers = resolveProviders(env);
+	checks.push(...checkProviders(providers));
 
 	const used = new Set(Object.values(providers));
 
@@ -64,34 +68,35 @@ export async function runDoctor() {
 		checks.push(...checkHeaderAuth(dir, env, providers.data));
 	}
 
-	const tenancy = (env.SELVA_TENANCY ?? 'single').toLowerCase();
-	if (tenancy !== 'single' && tenancy !== 'multi') {
-		checks.push(red(`SELVA_TENANCY="${tenancy}" — expected single|multi`));
-	} else {
-		checks.push(green(`SELVA_TENANCY=${tenancy}`));
-	}
+	checks.push(checkTenancy(env));
 
 	checks.push(checkPackage(dir, '@selvajs/selva'));
+	checks.push(checkNodeEngine(dir));
 	checks.push(checkCliRuntimeAlignment(dir));
 	checks.push(...checkBootPersistence(dir));
-	if (env.ORIGIN) {
-		try {
-			new URL(env.ORIGIN);
-			checks.push(green(`ORIGIN=${env.ORIGIN}`));
-		} catch {
-			checks.push(red(`ORIGIN="${env.ORIGIN}" is not a valid URL`));
-		}
-	} else {
-		checks.push(yellow('ORIGIN unset — required behind a reverse proxy'));
-	}
+	checks.push(checkOrigin(env));
+	checks.push(...checkDeprecatedEnv(env));
 
 	// ── 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 {
@@ -100,27 +105,50 @@ export async function runDoctor() {
 	}
 }
 
-function green(text) {
-	return { severity: 'green', line: `${pc.green('✓')} ${text}` };
-}
-function yellow(text) {
-	return { severity: 'yellow', line: `${pc.yellow('!')} ${text}` };
-}
-function red(text) {
-	return { severity: 'red', line: `${pc.red('✗')} ${text}` };
+/**
+ * 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 checkFile(path, label) {
 	return existsSync(path) ? green(label) : red(`${label} (missing: ${path})`);
 }
 
-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);
-}
-
 function checkDataPath(dir, dataPath) {
 	const absolute = resolve(dir, dataPath);
 	try {
@@ -297,94 +325,65 @@ function checkCliRuntimeAlignment(dir) {
 }
 
 // Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
-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 —
-	// stay silent rather than emit misleading checks.
-	if (process.platform !== 'linux') return [];
-
-	const out = [];
-
-	// dump.pm2 (what pm2 startup resurrects).
-	const pm2Home = process.env.PM2_HOME ?? join(homedir(), '.pm2');
-	const dumpPath = join(pm2Home, 'dump.pm2');
-	if (existsSync(dumpPath)) {
-		out.push(green('pm2 process list saved (dump.pm2 present)'));
-	} else {
-		out.push(
-			yellow(
-				'pm2 process list not saved — run `npx pm2 save` so a reboot can ' +
-					'resurrect the app (nothing to restore without it)'
-			)
+/**
+ * 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');
 	}
-
-	// systemd unit: present and pointing at deployment-local pm2.
-	const user = process.env.USER ?? process.env.LOGNAME;
-	const unitPath = user
-		? `/etc/systemd/system/pm2-${user}.service`
-		: null;
-
-	if (unitPath && existsSync(unitPath)) {
-		const localPm2 = join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
-		let unit = '';
-		try {
-			unit = readFileSync(unitPath, 'utf8');
-		} catch {
-			out.push(yellow(`pm2 systemd unit present but unreadable (${unitPath})`));
-			return out;
-		}
-		const execStart = /^ExecStart=(.+)$/m.exec(unit)?.[1] ?? '';
-		if (execStart.includes(localPm2)) {
-			out.push(green('pm2 systemd boot unit installed (uses deployment-local pm2)'));
-		} else {
-			out.push(
-				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`
-				)
-			);
-		}
-	} else {
-		out.push(
-			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).'
-			)
-		);
+	if (typeof required !== 'string') {
+		return yellow('@selvajs/selva declares no engines.node — cannot verify this host');
 	}
 
-	// Warn if global pm2 is on PATH (root cause of version skew).
-	const globalPm2 = findGlobalPm2(dir);
-	if (globalPm2) {
-		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\`.`
-			)
-		);
+	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 out;
+	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`
+	);
 }
 
-// Scan PATH for stray pm2 binary (read-only).
-function findGlobalPm2(dir) {
-	const localBin = resolve(dir, 'node_modules', '.bin');
-	const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
-	for (const d of dirs) {
-		if (resolve(d) === localBin) continue;
-		const candidate = join(d, 'pm2');
-		if (existsSync(candidate)) return candidate;
-	}
-	return null;
+/**
+ * `selva migrate` parks the old node_modules aside so a failed install can be
+ * rolled back, and removes it on either outcome. One surviving here means the
+ * migration was killed mid-flight — worth saying, because it is a full copy of
+ * the dependency tree and the deployment may be running on the wrong one.
+ */
+function checkMigrationLeftovers(dir) {
+	const stash = join(dir, NODE_MODULES_STASH);
+	if (!existsSync(stash)) return green('no interrupted migration left behind');
+	return yellow(
+		`${NODE_MODULES_STASH} exists — a \`selva migrate\` was interrupted. If the app ` +
+			`is healthy, delete it: rm -rf ${stash}`,
+		fixable(`delete the leftover ${NODE_MODULES_STASH}`, () => {
+			try {
+				rmSync(stash, { recursive: true, force: true });
+				return green(`removed ${NODE_MODULES_STASH}`);
+			} catch (err) {
+				return red(`could not remove ${stash}: ${err instanceof Error ? err.message : err}`);
+			}
+		})
+	);
 }
 
 function checkLayoutDrift(dir) {
@@ -494,8 +493,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		Boolean(env.HEADER_AUTH_EMAIL_HEADER),
 		Boolean(env.HEADER_AUTH_DISPLAY_NAME_HEADER)
 	].filter(Boolean).length;
-	const headerList =
-		`UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
+	const headerList = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
 	if (overrides === 0) {
 		out.push(green(`header names (bundled defaults): ${headerList}`));
 	} else if (overrides === 3) {

package/src/commands/init.js

@@ -7,14 +7,13 @@
 //     `selva keys rotate`'s job, not init's.
 //   • Doesn't touch package.json or run npm install.
 
-import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { collectConfig } from '../prompts.js';
 import { readEnvFile, writeEnvFile } from '../env.js';
 import { generateKey } from '../secrets.js';
-import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 export async function runInit() {
 	const dir = resolveDeploymentDir();
@@ -48,24 +47,7 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	// Use whatever .env.example shipped with the installed runtime as the
-	// canonical template. Falls back to the current .env if the runtime
-	// templates aren't present (shouldn't happen post-install).
-	const templatePath = join(
-		dir,
-		'node_modules',
-		'@selvajs',
-		'selva',
-		'templates',
-		'.env.example'
-	);
-	const template = existsSync(templatePath)
-		? readFileSync(templatePath, 'utf8')
-		: existsSync(envPath)
-			? readFileSync(envPath, 'utf8')
-			: '';
-
-	writeEnvFile(envPath, template, values);
+	writeEnvFile(envPath, readEnvTemplate(dir), values);
 
 	p.outro(
 		[

package/src/commands/keys.js

@@ -1,12 +1,11 @@
 // Rotate SELVA_HMAC_KEY or SELVA_AT_REST_KEY; requires explicit confirm (blast radius in TARGETS).
 
-import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readEnvFile, writeEnvFile } from '../env.js';
 import { generateKey } from '../secrets.js';
-import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 const TARGETS = {
 	hmac: {
@@ -14,8 +13,7 @@ const TARGETS = {
 		warning: [
 			'This will:',
 			pc.red('  • log every signed-in user out (existing session cookies stop verifying)'),
-			pc.red('  • invalidate share-link and invite tokens that fell back to this key'),
-			pc.dim('    (only relevant when SHARE_LINK_SECRET / INVITE_TOKEN_SECRET are unset)')
+			pc.red('  • invalidate every share link and pending invite')
 		].join('\n')
 	},
 	'at-rest': {
@@ -58,19 +56,7 @@ export async function runKeysRotate(argv) {
 	const fresh = generateKey();
 	current[envVar] = fresh;
 
-	const templatePath = join(
-		dir,
-		'node_modules',
-		'@selvajs',
-		'selva',
-		'templates',
-		'.env.example'
-	);
-	const template = existsSync(templatePath)
-		? readFileSync(templatePath, 'utf8')
-		: readFileSync(envPath, 'utf8');
-
-	writeEnvFile(envPath, template, current);
+	writeEnvFile(envPath, readEnvTemplate(dir), current);
 
 	p.outro(
 		[