@selvajs/cli 4.20.0-beta.8 → 4.20.0

package/src/commands/pm2.js

@@ -8,6 +8,9 @@ import { spawnSync, execSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { readEnvFile } from '../env.js';
+import { needsSupabaseProvider } from '../deployment-package.js';
+import { checkSupabaseMigrations, providerTagFor } from '../checks/migrations.js';
 
 export const APP_NAME = 'selva-compute';
 
@@ -147,10 +150,10 @@ export async function runUpdate() {
 	const before = readRuntimeVersion(dir);
 	p.log.info(`Current @selvajs/selva: ${before ?? 'unknown'}`);
 
-	// Providers are bundled into @selvajs/selva — the only @selvajs/* packages
-	// an operator install carries are the runtime and the CLI. The admin-center
-	// "Run update" button runs the same list — keep them in sync if you edit.
+	// The admin-center "Run update" button runs the same list: keep them in sync.
 	const packages = ['@selvajs/cli', '@selvajs/selva'];
+	const env = readEnvFile(join(dir, '.env'));
+	const supabase = needsSupabaseProvider(env);
 
 	const confirmed = await p.confirm({
 		message: 'Refresh all @selvajs/* packages and restart the app?',
@@ -185,6 +188,23 @@ export async function runUpdate() {
 	const after = readRuntimeVersion(dir);
 	p.log.info(`New @selvajs/selva:     ${after ?? 'unknown'}`);
 
+	realignPm2Pin(dir, s);
+
+	if (supabase) {
+		// Provider code is bundled into @selvajs/selva, but the migration SQL ships
+		// here. Left behind, `selva-supabase` copies nothing new. Installed by tag,
+		// not `npm update`d: its pin can sit on another channel than the runtime's.
+		const spec = `@selvajs/supabase-provider@${providerTagFor(after)}`;
+		s.start(`npm install ${spec}`);
+		try {
+			execSync(`npm install --save --prefer-online ${spec}`, { cwd: dir, stdio: 'pipe' });
+			s.stop(`${spec} installed`);
+		} catch (err) {
+			s.stop(`npm install ${spec} failed`);
+			p.log.warn(String(err.stderr ?? err.message ?? err).trim());
+		}
+	}
+
 	if (before && after && before === after) {
 		p.log.warn(
 			[
@@ -199,12 +219,115 @@ export async function runUpdate() {
 		);
 	}
 
+	// Migrations are not applied here: they aren't reversible, and the old build
+	// is already gone. The app serves on an old schema (degraded), so start it and
+	// say what is left to do.
+	const schema = supabase ? await checkSupabaseMigrations(dir, env, after) : null;
+
 	const status = runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
-	if (status === 0) {
-		p.outro(pc.green('Started ' + APP_NAME));
-	} else {
+	if (status !== 0) {
 		p.outro(pc.yellow(`Start failed — investigate with \`pm2 logs ${APP_NAME}\`.`));
+		process.exitCode = 1;
+		return;
+	}
+
+	const health = await waitForHealth(env);
+	if (schema && schema.severity !== 'green') p.log.message(schema.line);
+	if (health.ok) {
+		p.outro(pc.green(`Started ${APP_NAME}`));
+		return;
+	}
+	p.outro(
+		pc.red(
+			health.status
+				? `Started ${APP_NAME}, but /api/health returned ${health.status}: ${health.reason}`
+				: `Started ${APP_NAME}, but /api/health did not answer within 30s. Check \`pm2 logs ${APP_NAME}\`.`
+		)
+	);
+	process.exitCode = 1;
+}
+
+// Moves the deployment onto the pm2 the just-installed CLI pins, then swaps the
+// daemon. Without it a release that bumps pm2 needs `selva migrate` and
+// `pm2 update` by hand on every host. Runs from the OLD CLI, so the pin is read
+// from the new one on disk. The app is stopped here, so the swap costs no
+// extra downtime. A failure leaves the old pm2 working: warn, don't abort.
+function readPm2Pins(dir) {
+	const read = (path) => {
+		try {
+			return JSON.parse(readFileSync(path, 'utf8'));
+		} catch {
+			return null;
+		}
+	};
+	return {
+		declared: read(join(dir, 'package.json'))?.dependencies?.pm2 ?? null,
+		pinned:
+			read(join(dir, 'node_modules', '@selvajs', 'cli', 'package.json'))?.devDependencies?.pm2 ??
+			null
+	};
+}
+
+function realignPm2Pin(dir, s) {
+	const { declared, pinned } = readPm2Pins(dir);
+	if (!pinned || pinned === declared) return;
+
+	s.start(`npm install pm2@${pinned}`);
+	try {
+		execSync(`npm install --save --save-exact --prefer-online pm2@${pinned}`, {
+			cwd: dir,
+			stdio: 'pipe'
+		});
+		s.stop(`pm2 ${declared ?? '(none)'} → ${pinned}`);
+	} catch (err) {
+		s.stop(`npm install pm2@${pinned} failed`);
+		p.log.warn(
+			`${String(err.stderr ?? err.message ?? err).trim()}\n` +
+				'The previous pm2 still runs the app. Retry with `npx selva migrate`.'
+		);
+		return;
+	}
+	try {
+		ensurePm2InSync(dir);
+	} catch (err) {
+		p.log.warn(`${err instanceof Error ? err.message : err}`);
+	}
+}
+
+// The app was stopped before the update, so the first answer is the new process.
+async function waitForHealth(env, timeoutMs = 30_000) {
+	const host = !env.HOST || env.HOST === '0.0.0.0' || env.HOST === '::' ? '127.0.0.1' : env.HOST;
+	const url = `http://${host.includes(':') ? `[${host}]` : host}:${env.PORT || 3000}/api/health`;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+			if (res.ok) return { ok: true };
+			return {
+				ok: false,
+				status: res.status,
+				reason: degradedReason(await res.json().catch(() => null))
+			};
+		} catch {
+			await new Promise((r) => setTimeout(r, 1000));
+		}
+	}
+	return { ok: false };
+}
+
+/** Names the cause a 503 from /api/health reports in `boot`. */
+export function degradedReason(body) {
+	const boot = body?.boot;
+	if (boot?.schemaVersion?.ok === false) {
+		return (
+			boot.schemaVersion.message ??
+			`database migration head ${boot.schemaVersion.actual} is behind ${boot.schemaVersion.expected}`
+		);
+	}
+	if (boot?.atRestSecrets?.ok === false) {
+		return 'stored compute API keys cannot be decrypted under the current SELVA_AT_REST_KEY';
 	}
+	return 'see `pm2 logs selva-compute`';
 }
 
 function readRuntimeVersion(dir) {

package/src/commands/proxy.js

@@ -144,6 +144,18 @@ export async function runSetupProxy(argv = []) {
 		);
 	}
 
+	const host = env.HOST ?? '0.0.0.0';
+	if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+		p.log.warn(
+			`Add this to .env, then \`selva restart\`:\n` +
+				pc.cyan('  HOST=127.0.0.1\n') +
+				pc.dim(
+					'Without it the app listens on every interface, so port 3000 is reachable\n' +
+						'without Caddy and a direct caller can set its own X-Forwarded-For.'
+				)
+		);
+	}
+
 	p.outro(
 		[
 			pc.green(`Caddy is serving ${domain}.`),

package/src/deployment-package.js

@@ -129,7 +129,9 @@ export function isPrereleasePin(pin) {
  *
  * js-yaml: pm2 <= 7.0.3 pins 4.3.0, which carries the quadratic-complexity
  * DoS advisories (GHSA-5p4m-2wfm-xmqj and friends); the fix landed in 4.3.1.
- * Drop when pm2's own js-yaml dependency reaches >= 4.3.1.
+ * pm2 7.1.2 pins 4.3.2, so this is now redundant. Dropping it rewrites every
+ * deployment's package.json and `doctor` reports the change as drift, so it
+ * goes with the next release that migrates the layout anyway.
  */
 export const OVERRIDES = {
 	'js-yaml': '^4.3.1'

package/src/env-migration.js

@@ -0,0 +1,155 @@
+// Plan the .env rewrite `selva migrate` applies: old names renamed, values a
+// looser reader used to accept rewritten to what they meant, no-op and retired
+// lines removed, shipped template prose stripped. Unknown keys are kept.
+//
+// `mismatches` is the proof: every declared key resolved from the old file
+// (with the old readers' semantics) and from the new one. Anything but empty
+// means the rewrite would change behaviour, and migrate refuses to write it.
+
+import {
+	countEnvCommentLines,
+	parseEnv,
+	RENAMED_ENV_VARS as RENAMES,
+	RETIRED_ENV_VARS as RETIRED,
+	renameEnvKeys,
+	setEnvValues,
+	stripEnvComments
+} from './env.js';
+import { ALL_SETTINGS, legacyValue, resolveConfig } from './generated/config.js';
+import { reportFor } from './commands/config.js';
+
+const SPECS = new Map(ALL_SETTINGS.map((s) => [s.key, s]));
+
+// How the old reader took SELVA_FLAG_COMPUTE_DEBUG_VERBOSE (engine.server.ts).
+const OLD_VERBOSE_TRUE = new Set(['true', '1', 'yes']);
+
+/** The debug mode the app runs in, from either generation of the keys. */
+function computeDebugMode(env) {
+	const raw = (env.SELVA_FLAG_COMPUTE_DEBUG ?? '').toLowerCase();
+	if (raw === 'verbose') return 'verbose';
+	if (OLD_VERBOSE_TRUE.has((env.SELVA_FLAG_COMPUTE_DEBUG_VERBOSE ?? '').toLowerCase()))
+		return 'verbose';
+	return ['true', '1', 'yes', 'on'].includes(raw) ? 'on' : 'off';
+}
+
+/** Keys whose effective value depends on another key. */
+const EFFECTIVE = {
+	HEADER_AUTH_DATA_DIR: (env) => env.HEADER_AUTH_DATA_DIR || env.DATA_PATH,
+	SELVA_FLAG_COMPUTE_DEBUG: computeDebugMode
+};
+
+function canonical(value) {
+	if (typeof value === 'boolean') return value ? 'true' : 'false';
+	if (Array.isArray(value)) return value.join(',');
+	return String(value);
+}
+
+/** What `env[key]` means to the reader of that generation. */
+function meaning(spec, env, { legacy }) {
+	if (EFFECTIVE[spec.key]) return EFFECTIVE[spec.key](env);
+	const name = [spec.key, ...(spec.aliases ?? [])].find(
+		(k) => env[k] !== undefined && env[k] !== ''
+	);
+	if (name === undefined) return spec.default;
+	const raw = env[name];
+	if (legacy && spec.legacy) return legacyValue(spec, raw);
+	return resolveConfig([spec], { [spec.key]: raw }).values[spec.key];
+}
+
+export function planEnvMigration(input) {
+	const changes = [];
+	let text = input;
+
+	if (countEnvCommentLines(text) > 0) {
+		text = stripEnvComments(text).text;
+		changes.push({ key: '(comments)', action: 'stripped' });
+	}
+
+	const renamed = renameEnvKeys(text, RENAMES);
+	text = renamed.text;
+	for (const [from, to, how] of renamed.changes) {
+		changes.push(
+			how === 'renamed'
+				? { key: from, action: 'renamed', to }
+				: { key: from, action: 'dropped', reason: `${to} is set` }
+		);
+	}
+
+	const env = parseEnv(text);
+	const updates = {};
+
+	if (env.SELVA_FLAG_COMPUTE_DEBUG_VERBOSE !== undefined) {
+		updates.SELVA_FLAG_COMPUTE_DEBUG_VERBOSE = undefined;
+		if (computeDebugMode(env) === 'verbose') updates.SELVA_FLAG_COMPUTE_DEBUG = 'verbose';
+		changes.push({
+			key: 'SELVA_FLAG_COMPUTE_DEBUG_VERBOSE',
+			action: 'replaced',
+			to: 'SELVA_FLAG_COMPUTE_DEBUG'
+		});
+	}
+
+	for (const [key, raw] of Object.entries(env)) {
+		const spec = SPECS.get(key);
+		if (!spec?.legacy) continue;
+		const old = legacyValue(spec, raw);
+		const now = resolveConfig([spec], { [key]: raw }).keys[key];
+		if (now.status !== 'ok' || now.value !== old) {
+			updates[key] = canonical(old);
+			changes.push({ key, action: 'rewritten', to: canonical(old) });
+		}
+	}
+
+	for (const key of [
+		'HEADER_AUTH_UPN_HEADER',
+		'HEADER_AUTH_EMAIL_HEADER',
+		'HEADER_AUTH_DISPLAY_NAME_HEADER'
+	]) {
+		if (env[key] !== undefined && env[key] === SPECS.get(key)?.default) {
+			updates[key] = undefined;
+			changes.push({ key, action: 'removed', reason: 'same as the default' });
+		}
+	}
+	if (env.HEADER_AUTH_DATA_DIR !== undefined && env.HEADER_AUTH_DATA_DIR === env.DATA_PATH) {
+		updates.HEADER_AUTH_DATA_DIR = undefined;
+		changes.push({ key: 'HEADER_AUTH_DATA_DIR', action: 'removed', reason: 'same as DATA_PATH' });
+	}
+
+	// The app ignores these whatever their value, so removing the line changes nothing it does.
+	for (const [key, now] of Object.entries(RETIRED)) {
+		if (env[key] === undefined || key in updates) continue;
+		updates[key] = undefined;
+		changes.push({ key, action: 'removed', reason: `no longer read: ${now}` });
+	}
+
+	if (Object.keys(updates).length > 0) text = setEnvValues(text, updates);
+
+	// Read back with Node's parser, the one the app boots with, so a writer bug
+	// shows up here as a mismatch instead of on the server.
+	const before = parseEnv(input);
+	const after = parseEnv(text);
+	const mismatches = [];
+	for (const spec of ALL_SETTINGS) {
+		const was = meaning(spec, before, { legacy: true });
+		const is = meaning(spec, after, { legacy: false });
+		if (JSON.stringify(was) !== JSON.stringify(is)) mismatches.push({ key: spec.key, was, is });
+	}
+	for (const key of Object.keys(before)) {
+		if (!SPECS.has(key) && !(key in RENAMES) && !(key in RETIRED) && after[key] !== before[key]) {
+			mismatches.push({ key, was: before[key], is: after[key] });
+		}
+	}
+
+	// A value both generations reject compares equal above, yet the old reader
+	// shrugged it off while the new one may stop boot on it. Name those apart:
+	// `blockers` stop the app, `fallbacks` run on the default.
+	const report = reportFor(after);
+	return {
+		text,
+		changes,
+		mismatches,
+		// A missing required key is a broken .env either way: doctor's job, not a migration's.
+		blockers: report.problems.filter((p) => p.status === 'error' && p.source !== 'unset'),
+		fallbacks: report.problems.filter((p) => p.status === 'invalid'),
+		unknown: report.unknown
+	};
+}

package/src/env.js

@@ -1,23 +1,19 @@
-// Minimal .env parser/serializer (no dotenv; runtime uses node --env-file).
+// .env reading and writing. Reads go through Node's own parser, the one
+// `node --env-file` boots the app with, so the CLI never sees a value the app
+// doesn't.
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
+import { parseEnv as nodeParseEnv } from 'node:util';
+import { ALL_SETTINGS, RETIRED_KEYS } from './generated/config.js';
 
 // Old env name → its replacement, for keys renamed without changing meaning.
-// The server still reads each old name for one minor version and warns at
-// boot; keep this in sync with the server's list and drop an entry once the
-// server stops reading it.
-export const RENAMED_ENV_VARS = {
-	COMPUTE_DEFINITION_BYTE_CACHE_MB: 'COMPUTE_DEFINITION_CACHE_MB',
-	COMPUTE_RESPONSE_CACHE_MB: 'COMPUTE_SOLVE_CACHE_MB',
-	DEFINITION_CACHE_TTL_MS: 'REMOTE_DEFINITION_CACHE_TTL_MS',
-	MAX_SOLVE_DURATION_MS: 'COMPUTE_SOLVE_DEADLINE_MS'
-};
-
-// Deprecated vars whose replacement changes the VALUE too, so a simple key
-// rename can't migrate them — `selva migrate` leaves these alone rather than guessing.
-export const REPLACED_ENV_VARS = {
-	SELVA_FLAG_COMPUTE_DEBUG_VERBOSE: 'SELVA_FLAG_COMPUTE_DEBUG=verbose'
-};
+// From the manifest's `aliases`, the same list the server reads old names by.
+export const RENAMED_ENV_VARS = Object.fromEntries(
+	ALL_SETTINGS.flatMap((s) => (s.aliases ?? []).map((alias) => [alias, s.key]))
+);
+
+// Keys the app no longer reads → what took their place. `selva migrate` removes them.
+export const RETIRED_ENV_VARS = RETIRED_KEYS;
 
 // Header written above the settings in a stripped .env. The pointer matters:
 // without it the operator has no way back to what a var means, and the reflex
@@ -156,23 +152,7 @@ export function countEnvCommentLines(text) {
 }
 
 export function parseEnv(text) {
-	const out = {};
-	for (const rawLine of text.split(/\r?\n/)) {
-		const line = rawLine.trim();
-		if (!line || line.startsWith('#')) continue;
-		const eq = line.indexOf('=');
-		if (eq === -1) continue;
-		const key = line.slice(0, eq).trim();
-		let value = line.slice(eq + 1).trim();
-		if (
-			(value.startsWith('"') && value.endsWith('"')) ||
-			(value.startsWith("'") && value.endsWith("'"))
-		) {
-			value = value.slice(1, -1);
-		}
-		out[key] = value;
-	}
-	return out;
+	return nodeParseEnv(text);
 }
 
 export function readEnvFile(path) {
@@ -196,7 +176,7 @@ export function readEnvFile(path) {
 const SEEDED_TEMPLATE_DEFAULTS = ['BODY_SIZE_LIMIT'];
 
 /** The subset of the template's live `KEY=value` lines that are safe to seed. */
-function seededTemplateDefaults(template) {
+export function seededTemplateDefaults(template) {
 	const parsed = parseEnv(template);
 	const out = {};
 	for (const key of SEEDED_TEMPLATE_DEFAULTS) {
@@ -253,15 +233,65 @@ export function renderEnvValues(template, values, { header = ENV_HEADER } = {})
 		// operator has deliberately blanked one out.
 		const value = Object.prototype.hasOwnProperty.call(values, key) ? values[key] : defaults[key];
 		if (value === undefined || value === null || value === '') continue;
-		lines.push(`${key}=${quoteIfNeeded(value)}`);
+		lines.push(`${key}=${encodeEnvValue(value)}`);
 	}
 
 	return header ? `${header}\n\n${lines.join('\n')}\n` : `${lines.join('\n')}\n`;
 }
 
-/** Writes the deployment `.env` — values only, in the template's key order. */
+/** Writes a fresh deployment `.env`, values only, in the template's key order. */
 export function writeEnvFile(path, template, values) {
-	writeFileSync(path, renderEnvValues(template, values), 'utf8');
+	writeEnvText(path, renderEnvValues(template, values));
+}
+
+/** `.env` holds both root keys, so it is the owner's alone. */
+export function writeEnvText(path, text) {
+	writeFileSync(path, text, { encoding: 'utf8', mode: 0o600 });
+	// `mode` applies only when the file is created; an existing file keeps its own.
+	if (process.platform !== 'win32') chmodSync(path, 0o600);
+}
+
+/**
+ * Set or remove keys in an existing `.env`, touching only their lines.
+ *
+ * Re-rendering the whole file drops the operator's comments and re-encodes
+ * every value. `undefined` or `null` removes the key; a key not yet present is
+ * appended.
+ */
+export function setEnvValues(text, updates) {
+	const pending = new Map(Object.entries(updates));
+	const lines = text.split(/\r?\n/);
+	// Node reads the last line for a key that appears twice, so that is the one
+	// to edit; earlier duplicates would only mislead the next reader of the file.
+	const last = new Map();
+	lines.forEach((line, i) => {
+		const key = keyOfLine(line);
+		if (key !== null && pending.has(key)) last.set(key, i);
+	});
+	const out = [];
+	lines.forEach((line, i) => {
+		const key = keyOfLine(line);
+		if (key === null || !pending.has(key)) {
+			out.push(line);
+			return;
+		}
+		if (last.get(key) !== i) return;
+		const value = pending.get(key);
+		if (value !== undefined && value !== null) out.push(`${key}=${encodeEnvValue(value)}`);
+	});
+	for (const key of last.keys()) pending.delete(key);
+	// The split leaves '' for the final newline; appended keys go above it.
+	while (out.length > 0 && out[out.length - 1] === '') out.pop();
+	for (const [key, value] of pending) {
+		if (value === undefined || value === null) continue;
+		out.push(`${key}=${encodeEnvValue(value)}`);
+	}
+	return out.length === 0 ? '' : `${out.join('\n')}\n`;
+}
+
+function keyOfLine(line) {
+	const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+	return match ? match[1] : null;
 }
 
 /**
@@ -304,9 +334,17 @@ export function renameEnvKeys(text, renames) {
 	return { text: out.join('\n'), changes };
 }
 
-function quoteIfNeeded(value) {
+/**
+ * Quote a value so Node's parser reads it back unchanged. Node does not
+ * unescape `\"` inside double quotes, so `JSON.stringify` corrupts JSON values,
+ * and an unquoted `#` starts a comment. Single quotes are literal, so they come
+ * first; the other two quote kinds cover values that contain them.
+ */
+export function encodeEnvValue(value) {
 	const s = String(value);
-	if (s === '') return '""';
-	if (/[\s"'#=]/.test(s)) return JSON.stringify(s);
-	return s;
+	if (s === '') return "''";
+	if (!/[\s"'`#\\]/.test(s)) return s;
+	if (s.includes('\n')) throw new Error('Multi-line .env values are not supported');
+	for (const q of ["'", '"', '`']) if (!s.includes(q)) return `${q}${s}${q}`;
+	throw new Error('Value contains every quote character and cannot be written to .env');
 }