@selvajs/cli 4.8.0-beta.8 → 4.8.0-beta.9

package/src/commands/migrate.js

@@ -2,42 +2,46 @@
 // provider packages), remove stale selva.config.js, update ecosystem.config.cjs.
 // Idempotent; mirrors update's lifecycle (stop/mutate/start with rollback on failure).
 
-import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
-import { spawnSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { renameEnvKeys, RENAMED_ENV_VARS } from '../env.js';
-
-const APP_NAME = 'selva-compute';
-
-// Packages we own. Everything in this set is rewritten wholesale by migrate;
-// anything outside it (operator's own deps) gets dropped, which is the
-// explicit design choice — operators with custom deps should fork the
-// template rather than hand-patch the deployment package.json.
-const SELVA_DEPS = new Set([
-	'@selvajs/cli',
-	'@selvajs/selva',
-	'@selvajs/runtime', // legacy — removed during migrate
-	'@selvajs/platform', // legacy — bundled into @selvajs/selva
-	'@selvajs/local-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/supabase-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/header-auth-provider', // legacy — bundled into @selvajs/selva
-	'@selvajs/create' // legacy CLI — removed during migrate
-]);
-
-const CANONICAL_SCRIPTS = {
-	start: 'selva start',
-	stop: 'selva stop',
-	restart: 'selva restart',
-	logs: 'selva logs',
-	doctor: 'selva doctor',
-	update: 'selva update'
-};
-
-export async function runMigrate() {
-	const dir = resolveDeploymentDir();
+import {
+	buildDeploymentPackageJson,
+	CANONICAL_FIELDS,
+	DEPENDENCIES,
+	LEGACY_DEPENDENCIES
+} from '../deployment-package.js';
+import { APP_NAME, runPm2 } from './pm2.js';
+
+/**
+ * Where `migrate` parks the old node_modules while npm installs the new one.
+ * Left behind only if the process is killed mid-migration — `detectDrift`
+ * reports it, because a stray copy of the dependency tree is both confusing and
+ * large enough to matter on a small VM.
+ */
+export const NODE_MODULES_STASH = 'node_modules.selva-migrate-bak';
+
+/**
+ * @param {object} [deps] Seams for tests. The rollback path destroys and
+ *   restores a real dependency tree, so it has to be exercised against a real
+ *   directory — but not against a real npm or a real pm2 daemon.
+ */
+export async function runMigrate(
+	_argv,
+	{
+		dir: injectedDir,
+		// --prefer-online bypasses the stale-packument trap: npm can otherwise
+		// resolve a cached packument that predates the release being migrated to.
+		install = (cwd) => execSync('npm install --prefer-online', { cwd, stdio: 'pipe' }),
+		confirm = (message) => p.confirm({ message, initialValue: true }),
+		pm2 = runPm2
+	} = {}
+) {
+	const dir = injectedDir ?? resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
 	p.intro(pc.bgCyan(pc.black(' selva migrate ')));
@@ -96,19 +100,22 @@ export async function runMigrate() {
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
 
-	const confirmed = await p.confirm({
-		message: 'Apply these changes, reinstall, and restart?',
-		initialValue: true
-	});
+	const confirmed = await confirm('Apply these changes, reinstall, and restart?');
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
 		return;
 	}
 
 	// Stop pm2 before npm rewrites (SvelteKit lazy-loads chunks; see update command).
-	const stopStatus = runPm2(dir, ['stop', APP_NAME], { inherit: false });
-	if (stopStatus !== 0) {
-		p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
+	// A legacy deployment may predate the local-pm2 layout, so a missing binary
+	// is not fatal here — there is nothing running for us to stop.
+	try {
+		const stopStatus = pm2(dir, ['stop', APP_NAME], { inherit: false });
+		if (stopStatus !== 0) {
+			p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
+		}
+	} catch {
+		p.log.warn('No deployment-local pm2 to stop — continuing.');
 	}
 
 	// Back up for rollback on npm-install failure.
@@ -136,22 +143,28 @@ export async function runMigrate() {
 		writeFileSync(envPath, envRename.text, 'utf8');
 	}
 
-	// Clean install required (major version changes break legacy lockfile).
-	rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
-	rmSync(join(dir, 'package-lock.json'), { force: true });
+	// A clean install is required — a legacy lockfile pins the old package set
+	// across a major bump. But node_modules is also where pm2 lives, and the
+	// rollback below has to restart the app, so deleting it outright leaves a
+	// failed migration with no way back up. Rename instead: atomic, keeps the
+	// .bin symlinks intact, and restorable until the install succeeds.
+	const nodeModules = join(dir, 'node_modules');
+	const nodeModulesBak = join(dir, NODE_MODULES_STASH);
+	const lockPath = join(dir, 'package-lock.json');
+
+	rmSync(nodeModulesBak, { recursive: true, force: true });
+	if (existsSync(nodeModules)) renameSync(nodeModules, nodeModulesBak);
+	const lockBak = existsSync(lockPath) ? readFileSync(lockPath, 'utf8') : null;
+	rmSync(lockPath, { force: true });
 
 	const s = p.spinner();
 	s.start('Installing new dependencies (this can take a minute)');
 	try {
-		// --prefer-online to bypass the stale-packument trap documented in
-		// docs/Hotfix-CLI-Runtime.md.
-		execSync('npm install --prefer-online', {
-			cwd: dir,
-			stdio: 'pipe'
-		});
+		install(dir);
 		s.stop('Dependencies installed');
+		rmSync(nodeModulesBak, { recursive: true, force: true });
 	} catch (err) {
-		s.stop(pc.red('npm install failed — rolling back package.json'));
+		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
 		if (hasStaleConfig && existsSync(configPath + '.bak')) {
 			copyFileSync(configPath + '.bak', configPath);
@@ -162,13 +175,25 @@ export async function runMigrate() {
 		if (envRename.changes.length > 0 && existsSync(envPath + '.bak')) {
 			copyFileSync(envPath + '.bak', envPath);
 		}
-		// Try to bring the process back up (best-effort; at least package.json is consistent).
-		runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+
+		// Restore the dependency tree the app was running on. A half-installed
+		// node_modules from the failed attempt is worse than the old one.
+		rmSync(nodeModules, { recursive: true, force: true });
+		if (existsSync(nodeModulesBak)) renameSync(nodeModulesBak, nodeModules);
+		if (lockBak !== null) writeFileSync(lockPath, lockBak, 'utf8');
+
+		restartAfterRollback(dir, pm2);
 		p.outro(pc.red(`Migration aborted: ${err.message ?? err}`));
 		process.exit(1);
 	}
 
-	const status = runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+	let status;
+	try {
+		status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+	} catch (err) {
+		status = 1;
+		p.log.error(`Could not invoke pm2: ${err instanceof Error ? err.message : err}`);
+	}
 	const backupHints = ['package.json.bak'];
 	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
 	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
@@ -187,23 +212,39 @@ export async function runMigrate() {
 	}
 }
 
-// Build target package.json with canonical dependencies (wholesale replace).
-// Drops non-canonical @selvajs/* and operator's own deps (by design).
-function buildTargetPackageJson(current) {
-	const deps = {
-		'@selvajs/cli': 'latest',
-		'@selvajs/selva': 'latest',
-		pm2: '^5.4.0'
-	};
+/**
+ * Bring the app back up after a failed migration.
+ *
+ * Never throws: the migration is already aborting, and an exception here would
+ * replace the rollback's diagnosis with a stack trace. A failure to restart is
+ * the operator's problem to act on, so it must be stated, not swallowed — the
+ * old code returned a bare 1 and printed nothing.
+ */
+function restartAfterRollback(dir, pm2 = runPm2) {
+	try {
+		const status = pm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+		if (status === 0) {
+			p.log.success(`Rolled back and restarted ${APP_NAME}.`);
+			return;
+		}
+		p.log.error(
+			`Rolled back, but \`pm2 start\` exited ${status}. The app may be down — ` +
+				`check \`pm2 logs ${APP_NAME}\` and start it with \`selva start\`.`
+		);
+	} catch (err) {
+		p.log.error(
+			`Rolled back, but pm2 could not be invoked (${err instanceof Error ? err.message : err}). ` +
+				`The app is likely down — run \`npm install\` then \`selva start\`.`
+		);
+	}
+}
 
-	return {
+function buildTargetPackageJson(current) {
+	return buildDeploymentPackageJson({
 		name: current.name ?? 'selva-deployment',
 		version: current.version ?? '0.1.0',
-		private: true,
-		type: 'module',
-		scripts: { ...CANONICAL_SCRIPTS },
-		dependencies: deps
-	};
+		engines: current.engines
+	});
 }
 
 // Format package.json diff for confirmation prompt (concise, not full diff).
@@ -235,39 +276,36 @@ function diffPackageJson(before, after) {
 		}
 	}
 
+	// Anything outside the canonical set is discarded by the rewrite.
+	// devDependencies and description used to vanish without appearing here, so
+	// the operator confirmed a change they were never shown.
+	for (const key of Object.keys(before).sort()) {
+		if (CANONICAL_FIELDS.has(key)) continue;
+		lines.push(`${pc.red('-')} ${key} ${pc.dim(summarize(before[key]))}`);
+	}
+
 	return lines;
 }
 
-// Local pm2 runner (avoid circular dep; duplication is small).
-function runPm2(dir, args, { inherit = true } = {}) {
-	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
-	const bin = existsSync(local) ? local : 'pm2';
-	const result = spawnSync(bin, args, {
-		cwd: dir,
-		stdio: inherit ? 'inherit' : 'pipe',
-		shell: process.platform === 'win32'
-	});
-	if (result.error) return 1;
-	return result.status ?? 0;
+// One-line preview of a dropped field, enough to recognise what is being lost.
+function summarize(value) {
+	if (value === null || typeof value !== 'object') return String(value);
+	const keys = Object.keys(value);
+	if (Array.isArray(value)) return `[${keys.length} item${keys.length === 1 ? '' : 's'}]`;
+	return keys.length ? `{${keys.join(', ')}}` : '{}';
 }
 
 // Exported for `selva doctor` to check layout drift without duplication.
 export function detectDrift(pkgJson, dir) {
 	const deps = pkgJson?.dependencies ?? {};
 	const reasons = [];
-	if (deps['@selvajs/runtime']) reasons.push('@selvajs/runtime is the old runtime package');
-	if (deps['@selvajs/create']) reasons.push('@selvajs/create is the old CLI package');
-	if (deps['@selvajs/platform'])
-		reasons.push('@selvajs/platform is now bundled into @selvajs/selva');
-	if (deps['@selvajs/local-provider'])
-		reasons.push('@selvajs/local-provider is now bundled into @selvajs/selva');
-	if (deps['@selvajs/supabase-provider'])
-		reasons.push('@selvajs/supabase-provider is now bundled into @selvajs/selva');
-	if (deps['@selvajs/header-auth-provider'])
-		reasons.push('@selvajs/header-auth-provider is now bundled into @selvajs/selva');
-	if (!deps['@selvajs/selva']) reasons.push('@selvajs/selva is missing');
-	if (!deps['@selvajs/cli']) reasons.push('@selvajs/cli is missing');
-	if (!deps['pm2']) reasons.push('pm2 is not in dependencies');
+
+	for (const [name, why] of Object.entries(LEGACY_DEPENDENCIES)) {
+		if (deps[name]) reasons.push(`${name} is ${why}`);
+	}
+	for (const name of Object.keys(DEPENDENCIES)) {
+		if (!deps[name]) reasons.push(`${name} is missing`);
+	}
 
 	if (dir) {
 		const configPath = join(dir, 'selva.config.js');
@@ -290,5 +328,4 @@ export function detectDrift(pkgJson, dir) {
 	return reasons;
 }
 
-// Re-exported for tests to verify without running migrate.
-export { buildTargetPackageJson, SELVA_DEPS };
+export { buildTargetPackageJson, diffPackageJson };

package/src/commands/pm2.js

@@ -9,10 +9,10 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
-const APP_NAME = 'selva-compute';
+export const APP_NAME = 'selva-compute';
 
 // Resolve to deployment-local pm2 (no global fallback; prevents version skew).
-function pm2Bin(dir) {
+export function pm2Bin(dir) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	if (!existsSync(local)) {
 		throw new Error(
@@ -92,8 +92,14 @@ function ensurePm2InSync(dir) {
 	}
 }
 
-function runPm2(dir, args, { inherit = true } = {}) {
-	const bin = pm2Bin(dir);
+/**
+ * Run the deployment-local pm2.
+ *
+ * `bin` overrides where pm2 is resolved from — `selva migrate` wipes
+ * node_modules mid-flight and passes the binary it stashed beforehand, because
+ * resolving from the deployment at that moment would find nothing.
+ */
+export function runPm2(dir, args, { inherit = true, bin = pm2Bin(dir) } = {}) {
 	const result = spawnSync(bin, args, {
 		cwd: dir,
 		stdio: inherit ? 'inherit' : 'pipe',

package/src/deployment-package.js

@@ -0,0 +1,102 @@
+// The package.json a deployment directory gets. `create` writes it at scaffold
+// time and `migrate` rewrites an existing one onto it, so it lives here rather
+// than in either command — two copies drifted once already, and the pm2 pin is
+// exactly the field where a silent difference costs the most.
+
+/**
+ * pm2 is pinned exactly, not caret-ranged.
+ *
+ * pm2's CLI and its long-running daemon must be the same version. A range lets
+ * two deployments installed a week apart resolve differently, and the newer one
+ * silently adopts the daemon the older one started — the skew `ensurePm2InSync`
+ * has to detect and, in the daemon-is-newer direction, cannot repair (#118).
+ */
+const PM2_VERSION = '5.4.3';
+
+const SCRIPTS = {
+	start: 'selva start',
+	stop: 'selva stop',
+	restart: 'selva restart',
+	logs: 'selva logs',
+	doctor: 'selva doctor',
+	update: 'selva update'
+};
+
+/**
+ * Packages a deployment carries. Providers are bundled into `@selvajs/selva`;
+ * the CLI is a dependency so `npm run start` resolves the `selva` bin locally
+ * instead of relying on a global install.
+ */
+const DEPENDENCIES = {
+	'@selvajs/cli': 'latest',
+	'@selvajs/selva': 'latest',
+	pm2: PM2_VERSION
+};
+
+/**
+ * Legacy `@selvajs/*` packages that a deployment may still list. Each was
+ * either renamed or folded into `@selvajs/selva`; `migrate` drops them and
+ * `doctor` reports them as layout drift.
+ */
+export const LEGACY_DEPENDENCIES = {
+	'@selvajs/runtime': 'the old runtime package',
+	'@selvajs/create': 'the old CLI package',
+	'@selvajs/platform': 'now bundled into @selvajs/selva',
+	'@selvajs/local-provider': 'now bundled into @selvajs/selva',
+	'@selvajs/supabase-provider': 'now bundled into @selvajs/selva',
+	'@selvajs/header-auth-provider': 'now bundled into @selvajs/selva'
+};
+
+/**
+ * Build the canonical deployment package.json.
+ *
+ * Dependencies are replaced wholesale rather than merged, so an operator's own
+ * additions are dropped. That is deliberate — a deployment directory is
+ * generated output, and anyone needing custom dependencies should depend on
+ * `@selvajs/selva` from their own project instead of editing this file.
+ *
+ * `engines` is the one exception, carried over when present: npm only enforces
+ * it under `engine-strict`, so an operator who pinned a Node floor did it
+ * deliberately, and dropping it removes a guard whose absence shows up only
+ * under real traffic (issue #176). Everything else a migration discards is
+ * listed by `diffPackageJson` before the operator confirms.
+ */
+export function buildDeploymentPackageJson({ name, version = '0.1.0', engines }) {
+	const pkg = {
+		name: sanitizePackageName(name),
+		version,
+		private: true,
+		type: 'module',
+		scripts: { ...SCRIPTS },
+		dependencies: { ...DEPENDENCIES }
+	};
+	if (engines && typeof engines === 'object') pkg.engines = { ...engines };
+	return pkg;
+}
+
+/**
+ * Top-level keys the canonical package.json defines. Anything outside this set
+ * that an operator added is dropped by `migrate` — `diffPackageJson` reports
+ * them so the loss is declared rather than discovered later.
+ */
+export const CANONICAL_FIELDS = new Set([
+	'name',
+	'version',
+	'private',
+	'type',
+	'scripts',
+	'dependencies',
+	'engines'
+]);
+
+export function sanitizePackageName(name) {
+	// npm package names: lowercase, no spaces, limited punctuation.
+	return (
+		String(name ?? '')
+			.toLowerCase()
+			.replace(/[^a-z0-9._-]+/g, '-')
+			.replace(/^[-._]+|[-._]+$/g, '') || 'selva-deployment'
+	);
+}
+
+export { DEPENDENCIES, SCRIPTS, PM2_VERSION };

package/src/node-range.js

@@ -0,0 +1,66 @@
+// Node version-range matching, used by `selva doctor` to check an installed
+// runtime and by the scaffolder to refuse a too-old shell before writing files.
+
+/**
+ * Narrow `engines.node` range check — `>=X`, `^`, `~`, `||`, and bare/x-ranges.
+ * Returns null when unparseable so a misread never reports a false failure.
+ *
+ * Mirrors `satisfiesRange` in @selvajs/server/ops. Duplicated because the CLI is
+ * dependency-free by design (it scaffolds the deployment that installs the
+ * runtime, so it cannot import from it).
+ */
+export function satisfiesNodeRange(version, range) {
+	const core = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(version).trim());
+	if (!core) return null;
+	const v = [Number(core[1]), Number(core[2]), Number(core[3])];
+
+	let anyParsed = false;
+	for (const alt of String(range).split('||')) {
+		const clauses = alt.trim().split(/\s+/).filter(Boolean);
+		if (!clauses.length) continue;
+
+		let all = true;
+		let parsed = true;
+		for (const clause of clauses) {
+			const m = /^(>=|<=|>|<|\^|~|=)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/.exec(clause);
+			if (!m) {
+				parsed = false;
+				break;
+			}
+			const op = m[1] ?? '=';
+			const num = (s) => (s == null || s === 'x' || s === '*' ? 0 : Number(s));
+			const t = [Number(m[2]), num(m[3]), num(m[4])];
+			let cmp = 0;
+			for (let i = 0; i < 3; i++) {
+				if (v[i] > t[i]) {
+					cmp = 1;
+					break;
+				}
+				if (v[i] < t[i]) {
+					cmp = -1;
+					break;
+				}
+			}
+			let ok;
+			if (op === '>=') ok = cmp >= 0;
+			else if (op === '>') ok = cmp > 0;
+			else if (op === '<=') ok = cmp <= 0;
+			else if (op === '<') ok = cmp < 0;
+			else if (op === '^') ok = cmp >= 0 && v[0] === t[0];
+			else if (op === '~') ok = cmp >= 0 && v[0] === t[0] && v[1] === t[1];
+			else
+				ok =
+					v[0] === t[0] &&
+					(m[3] == null || m[3] === 'x' || m[3] === '*' || v[1] === t[1]) &&
+					(m[4] == null || m[4] === 'x' || m[4] === '*' || v[2] === t[2]);
+			if (!ok) {
+				all = false;
+				break;
+			}
+		}
+		if (!parsed) continue;
+		anyParsed = true;
+		if (all) return true;
+	}
+	return anyParsed ? false : null;
+}

package/src/paths.js

@@ -21,6 +21,50 @@ export function requiredNodeRange() {
 	}
 }
 
+/**
+ * This CLI's own version, written into `.selva-version` so a later `selva
+ * migrate` can tell which scaffold layout it is looking at.
+ *
+ * Read from package.json for the same reason as `requiredNodeRange`: a literal
+ * in code stops tracking the release the moment someone forgets to bump it, and
+ * the marker's whole job is to be accurate about which CLI wrote the directory.
+ */
+export function scaffoldVersion() {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url));
+		const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+		return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+	} catch {
+		return '0.0.0';
+	}
+}
+
+/**
+ * A scaffolding template shipped inside the installed runtime. The CLI cannot
+ * import from `@selvajs/selva` — it is what installs it — so it reads the files
+ * out of node_modules after install.
+ */
+export function runtimeTemplatePath(dir, name) {
+	return join(dir, 'node_modules', '@selvajs', 'selva', 'templates', name);
+}
+
+/**
+ * The `.env` template to merge operator values into: the runtime's `.env.example`
+ * when installed, otherwise the deployment's own `.env` so its comments and
+ * ordering survive a rewrite.
+ *
+ * Returns `''` when neither exists rather than throwing — `mergeEnv` appends
+ * every value to an empty template, so the operator gets a usable file instead
+ * of an ENOENT from a command that was only asked to change one key.
+ */
+export function readEnvTemplate(dir) {
+	const template = runtimeTemplatePath(dir, '.env.example');
+	if (existsSync(template)) return readFileSync(template, 'utf8');
+	const env = join(dir, '.env');
+	if (existsSync(env)) return readFileSync(env, 'utf8');
+	return '';
+}
+
 // A deployment directory must contain an .env and an ecosystem.config.cjs.
 // Anything else (selva.config.js, node_modules) is "should be there" but the
 // CLI doesn't require it — `selva init` is allowed to fix a partial install.

package/src/prompts.js

@@ -527,5 +527,3 @@ function headerAuthSecurityWarning() {
 		pc.dim('See packages/providers/header-auth/README.md for the full deployment checklist.')
 	].join('\n');
 }
-
-export { p as prompts, pc as colors };

package/bin/create.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { runCreate } from '../src/commands/create.js';
-
-runCreate(process.argv.slice(2)).catch((err) => {
-	console.error(err instanceof Error ? err.message : err);
-	process.exit(1);
-});