@selvajs/cli 4.8.0-beta.10 → 4.8.0-beta.12

package/src/commands/create.js

@@ -1,6 +1,5 @@
-// Scaffold a fresh deployment: write .env (merged from template + prompts),
-// ecosystem.config.cjs, package.json, and bootstrap node_modules. Runtime
-// templates are the source of truth; providers are env-driven.
+// Scaffolds a fresh deployment: package.json, node_modules, .env (merged from
+// template + prompts), and ecosystem.config.cjs.
 
 import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
 import { resolve, join, basename, dirname } from 'node:path';
@@ -16,18 +15,20 @@ import {
 	runtimeTemplatePath,
 	scaffoldVersion
 } from '../paths.js';
-import { buildDeploymentPackageJson } from '../deployment-package.js';
+import {
+	buildDeploymentPackageJson,
+	npmDistTagVersion,
+	resolveSelvaPins
+} 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.
+	// Scaffolding under too old a Node installs and passes the health check,
+	// then fails only under real traffic — npm treats an engine mismatch as a
+	// warning, not an error, unless engine-strict is set, which no deployment
+	// sets. Refuse now, while the operator is still choosing their environment.
 	const required = requiredNodeRange();
 	if (required && satisfiesNodeRange(process.versions.node, required) === false) {
 		console.error(
@@ -50,20 +51,29 @@ export async function runCreate(argv) {
 	}
 	mkdirSync(targetDir, { recursive: true });
 
-	// --yes or CI=1 skips prompts (unattended bootstrap).
 	const nonInteractive = yes || envBool(process.env.CI);
 	const values = nonInteractive
 		? collectConfigFromEnv(process.env)
 		: await collectConfig({ defaults: {}, mode: 'create' });
 
-	// Generate fresh secrets (stable across restarts; init refuses to regen).
 	values.SELVA_HMAC_KEY = generateKey();
 	values.SELVA_AT_REST_KEY = generateKey();
 
 	const deployName = basename(targetDir);
 
-	// Write package.json, then install (need templates from @selvajs/selva).
-	const pkgJson = JSON.stringify(buildDeploymentPackageJson({ name: deployName }), null, 2);
+	// Resolve the dist-tags to concrete versions before writing. A stored
+	// `"latest"` re-resolves on every later `npm install`, so the deployment
+	// would follow the tag instead of the version it was scaffolded against —
+	// and `selva doctor` reports a floating pin as drift.
+	const { pins } = resolveSelvaPins({}, npmDistTagVersion);
+
+	// package.json first: npm install needs it, and the runtime templates below
+	// only exist once @selvajs/selva is installed into node_modules.
+	const pkgJson = JSON.stringify(
+		buildDeploymentPackageJson({ name: deployName, dependencies: pins }),
+		null,
+		2
+	);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
 	if (!skipInstall) {
@@ -74,7 +84,6 @@ export async function runCreate(argv) {
 		);
 	}
 
-	// Copy templates from installed runtime.
 	const envTemplatePath = runtimeTemplatePath(targetDir, '.env.example');
 	const ecosystemTemplatePath = runtimeTemplatePath(targetDir, 'ecosystem.config.cjs');
 	if (skipInstall || !existsSync(envTemplatePath)) {
@@ -110,21 +119,17 @@ export async function runCreate(argv) {
 	);
 }
 
-// Stream npm output with live progress; on failure, show tail for debugging.
-// Cache-bust hint: surface broken versions like @selvajs/selva@0.10.2.
 function runNpmInstall(cwd) {
 	return new Promise((resolveP, rejectP) => {
 		const s = p.spinner();
 		s.start('Installing dependencies (this can take a minute)');
 
-		// Keep last 80 lines for failure output.
 		const tail = [];
 		const remember = (line) => {
 			tail.push(line);
 			if (tail.length > 80) tail.shift();
 		};
 
-		// Extract progress milestones (reify: lines, package count).
 		const updateProgress = (line) => {
 			const trimmed = line.trim();
 			if (!trimmed) return;
@@ -140,7 +145,7 @@ function runNpmInstall(cwd) {
 			if (/^npm (WARN|error|notice)/.test(trimmed)) return;
 		};
 
-		// Spawn with --loglevel=info for reify: progress; pipe stdout/stderr for live updates.
+		// --loglevel=info is what makes npm print the reify: lines updateProgress matches on.
 		const child = spawn('npm', ['install', '--loglevel=info'], {
 			cwd,
 			stdio: ['ignore', 'pipe', 'pipe'],
@@ -184,8 +189,8 @@ function runNpmInstall(cwd) {
 			}
 			s.stop(pc.red(`npm install failed (exit ${code})`));
 
-			// Show what npm actually said. Without this the operator has to
-			// dig through ~/.npm/_logs/*-debug-0.log to find a single line.
+			// Without this the operator has to dig through ~/.npm/_logs/*-debug-0.log
+			// to find out what actually went wrong.
 			console.error('');
 			console.error(pc.dim('── last lines of npm output ──'));
 			for (const line of tail) console.error(line);

package/src/commands/doctor.js

@@ -2,12 +2,14 @@
 // 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`.
+// checks, each behind its own confirmation — only fixes needing no root and
+// no runtime restart exist. See applyFixes.
 
 import {
 	existsSync,
 	readFileSync,
+	writeFileSync,
+	copyFileSync,
 	readdirSync,
 	accessSync,
 	constants,
@@ -18,13 +20,16 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile } from '../env.js';
+import { readEnvFile, parseEnv, countEnvCommentLines, stripEnvComments } from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
 import { checkBootPersistence } from '../checks/boot.js';
+import { checkRuntimeEnvironment } from '../checks/runtime.js';
 import {
 	checkDeprecatedEnv,
+	checkEnvDocumentation,
+	checkHeaderNames,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
@@ -73,9 +78,11 @@ export async function runDoctor(argv = []) {
 	checks.push(checkPackage(dir, '@selvajs/selva'));
 	checks.push(checkNodeEngine(dir));
 	checks.push(checkCliRuntimeAlignment(dir));
+	checks.push(...checkRuntimeEnvironment(dir));
 	checks.push(...checkBootPersistence(dir));
 	checks.push(checkOrigin(env));
 	checks.push(...checkDeprecatedEnv(env));
+	checks.push(checkEnvDocs(dir));
 
 	// ── Render ─────────────────────────────────────────────────────────
 	const resolved = await Promise.all(checks);
@@ -105,15 +112,9 @@ export async function runDoctor(argv = []) {
 	}
 }
 
-/**
- * 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.
- */
+// Anything privileged (the systemd unit) or that would restart this process
+// (a Node upgrade) stays a printed instruction instead of a fixer — one that
+// dies halfway through its own runtime leaves the operator with no way back.
 async function applyFixes(resolved, failures) {
 	const repairs = resolved.filter((c) => c.fix && c.severity !== 'green');
 	if (repairs.length === 0) {
@@ -183,8 +184,7 @@ async function checkSupabase(env) {
 		return red(`SUPABASE_URL="${env.SUPABASE_URL}" is not a valid URL`);
 	}
 
-	// Ping the Supabase health endpoint. Soft-fail to yellow on network
-	// errors — operators may be offline at install time.
+	// Network errors go yellow, not red — operators may be offline at install time.
 	try {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), 4000);
@@ -199,11 +199,10 @@ async function checkSupabase(env) {
 	}
 }
 
-// App↔DB schema handshake (audit O3). Expected head = newest migration shipped
-// by the installed @selvajs/supabase-provider; actual = what the database
-// reports via the selva.migration_head() RPC. Red on skew — the app degrades
-// /api/health to 503 at boot in the same state, so catching it here saves a
-// confusing deploy.
+// Compares the newest migration shipped by @selvajs/supabase-provider against
+// what the database reports via selva.migration_head(). Red on skew — the app
+// degrades /api/health to 503 at boot in the same state, so catching it here
+// saves a confusing deploy.
 async function checkSupabaseMigrations(dir, env) {
 	if (!env.SUPABASE_URL || !env.SUPABASE_SERVICE_ROLE_KEY) {
 		return yellow('Migration-head check skipped — Supabase env incomplete');
@@ -264,6 +263,7 @@ async function checkSupabaseMigrations(dir, env) {
 				`Database reports no applied migrations (expected head ${expected}). Sync + run: npx supabase db push`
 			);
 		}
+		// String comparison — relies on both heads being fixed-width, zero-padded timestamps.
 		if (actual < expected) {
 			return red(
 				`Database migration head ${actual} is behind the installed provider (${expected}). Sync + run: npx supabase db push`
@@ -271,7 +271,6 @@ async function checkSupabaseMigrations(dir, env) {
 		}
 		return green(`Database migration head ${actual} matches the installed provider`);
 	} catch (err) {
-		// Soft-fail on network errors, same as checkSupabase.
 		return yellow(`Migration-head check skipped (${err.message ?? err})`);
 	}
 }
@@ -295,7 +294,7 @@ function majorOf(version) {
 	return m ? Number(m[1]) : null;
 }
 
-// CLI and runtime release together (fixed group); major skew = stale CLI pin.
+// CLI and runtime release as a fixed group; major-version skew means a stale CLI pin.
 function checkCliRuntimeAlignment(dir) {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const cliVersion = readPackageVersion(join(here, '..', '..', 'package.json'));
@@ -303,7 +302,7 @@ function checkCliRuntimeAlignment(dir) {
 		join(dir, 'node_modules', '@selvajs', 'selva', 'package.json')
 	);
 
-	// Runtime missing is already reported red by checkPackage; stay quiet here.
+	// checkPackage already reports missing runtime as red; stay quiet here.
 	if (!runtimeVersion) return yellow('CLI/runtime version check skipped (runtime not installed)');
 	if (!cliVersion) return yellow('CLI/runtime version check skipped (could not read CLI version)');
 
@@ -324,16 +323,10 @@ function checkCliRuntimeAlignment(dir) {
 	);
 }
 
-// Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
-/**
- * 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.
- */
+// npm only enforces engines.node 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. Not auto-fixable:
+// upgrading Node is distro-specific and would restart the process running this check.
 function checkNodeEngine(dir) {
 	let required;
 	try {
@@ -363,12 +356,10 @@ function checkNodeEngine(dir) {
 	);
 }
 
-/**
- * `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.
- */
+// `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 flagging since it's 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');
@@ -386,6 +377,58 @@ function checkMigrationLeftovers(dir) {
 	);
 }
 
+// Reads the raw file rather than the parsed env: the finding IS the comments,
+// which parseEnv discards. The repair is attached here (not in checks/config.js)
+// to keep that module filesystem-free.
+function checkEnvDocs(dir) {
+	const envPath = join(dir, '.env');
+	if (!existsSync(envPath)) return green('.env documentation check skipped (no .env)');
+
+	let text;
+	try {
+		text = readFileSync(envPath, 'utf8');
+	} catch (err) {
+		return yellow(`.env unreadable (${err instanceof Error ? err.message : err})`);
+	}
+
+	return checkEnvDocumentation(
+		countEnvCommentLines(text),
+		fixable('strip the shipped documentation from .env (backup: .env.bak)', () => {
+			try {
+				// Re-read at repair time: doctor may have run minutes ago in --fix's
+				// confirmation loop, and rewriting from a stale snapshot would silently
+				// revert an edit made in between.
+				const current = readFileSync(envPath, 'utf8');
+				const { text: strippedText, removed } = stripEnvComments(current);
+				// A rewrite that changes which settings are live is a bug, not a
+				// cleanup — refuse rather than hand back a subtly different deployment.
+				const before = parseEnv(current);
+				const after = parseEnv(strippedText);
+				const drift = diffEnvKeys(before, after);
+				if (drift) return red(`refused to strip .env — ${drift}`);
+
+				copyFileSync(envPath, envPath + '.bak');
+				writeFileSync(envPath, strippedText, 'utf8');
+				return green(`stripped ${removed} comment lines from .env (backup: .env.bak)`);
+			} catch (err) {
+				return red(`could not rewrite .env: ${err instanceof Error ? err.message : err}`);
+			}
+		})
+	);
+}
+
+// Names the first discrepancy between two parsed envs, or null when identical.
+function diffEnvKeys(before, after) {
+	for (const key of Object.keys(before)) {
+		if (!(key in after)) return `${key} would be lost`;
+		if (before[key] !== after[key]) return `${key} would change value`;
+	}
+	for (const key of Object.keys(after)) {
+		if (!(key in before)) return `${key} would be added`;
+	}
+	return null;
+}
+
 function checkLayoutDrift(dir) {
 	const pkgPath = join(dir, 'package.json');
 	if (!existsSync(pkgPath)) return yellow('package.json missing — cannot check layout');
@@ -403,19 +446,10 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// Must match HeaderAuthProvider.DEFAULT_HEADERS (duplicated to avoid loading runtime).
-// Smoke test in providers/header-auth pins them; divergence surfaces in CI.
-const DEFAULT_HEADER_NAMES = {
-	upn: 'SELVA-UserPrincipalName',
-	email: 'SELVA-Email',
-	displayName: 'SELVA-DisplayName'
-};
-
-// Header-auth checks (read-only; runtime invariants like spoofing can't be verified).
+// Static config only — runtime invariants like spoofing protection can't be checked from here.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
 
-	// Allowlist file location.
 	const allowlistDir = env.HEADER_AUTH_DATA_DIR ?? env.DATA_PATH;
 	if (!allowlistDir) {
 		out.push(red('HEADER_AUTH_DATA_DIR (or DATA_PATH) unset — provider will fail to start'));
@@ -425,21 +459,21 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		if (existsSync(allowlistPath)) {
 			out.push(green(`header-allowlist.json present (${allowlistDir}/header-allowlist.json)`));
 		} else {
-			// Provider creates lazily, but missing file locks everyone out.
+			// The provider creates this file lazily, but a missing file locks everyone out
+			// until one exists — worth a warning even though nothing is technically broken.
 			out.push(
 				yellow(
 					`header-allowlist.json not found at ${allowlistDir}/ — no users will be allowed in until one is added`
 				)
 			);
 
-			// Check writability only if explicitly set (DATA_PATH checked separately).
+			// DATA_PATH's own writability is checked separately (checkDataPath).
 			if (env.HEADER_AUTH_DATA_DIR) {
 				out.push(checkDirWritable(allowlistAbsDir, `HEADER_AUTH_DATA_DIR=${allowlistDir}`));
 			}
 		}
 	}
 
-	// HOST binding (loopback recommended for header-auth).
 	const host = env.HOST ?? '0.0.0.0';
 	if (host === '127.0.0.1' || host === 'localhost') {
 		out.push(green(`HOST=${host} (loopback-only)`));
@@ -452,12 +486,11 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 3. ORIGIN — header-auth implies a reverse proxy, so ORIGIN is required.
+	// header-auth always sits behind a reverse proxy, so ORIGIN is required.
 	if (!env.ORIGIN) {
 		out.push(red('ORIGIN unset — required for header-auth (always behind a proxy)'));
 	}
 
-	// Non-local data provider: HEADER_AUTH_DATA_DIR must be explicit (no DATA_PATH fallback).
 	if (dataProvider !== 'local' && !env.HEADER_AUTH_DATA_DIR) {
 		out.push(
 			red(
@@ -467,10 +500,10 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 5. Bootstrap admin email. Without it, the first proxy-authenticated
-	// visitor's UPN is rejected (not in allowlist) and the operator has to
-	// hand-write JSON to claim admin. With it, the first matching visit is
-	// auto-allowlisted and granted instance_admin in one step.
+	// Without this, the first proxy-authenticated visitor's UPN is rejected
+	// (not in the allowlist) and the operator has to hand-write JSON to claim
+	// admin. With it, the first matching visit auto-allowlists and grants
+	// instance_admin in one step.
 	if (!env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL) {
 		out.push(
 			red(
@@ -482,30 +515,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	// Resolved header names (print for diffing against proxy config; partial override = typo risk).
-	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 overrides = [
-		Boolean(env.HEADER_AUTH_UPN_HEADER),
-		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}`;
-	if (overrides === 0) {
-		out.push(green(`header names (bundled defaults): ${headerList}`));
-	} else if (overrides === 3) {
-		out.push(green(`header names (all overridden): ${headerList}`));
-	} else {
-		out.push(
-			yellow(
-				`header names partially overridden (${overrides}/3 set): ${headerList} — ` +
-					`a partial override is usually a typo. Set all three or none.`
-			)
-		);
-	}
+	out.push(checkHeaderNames(env));
 
 	return out;
 }

package/src/commands/init.js

@@ -1,11 +1,6 @@
-// `selva init` — reconfigure an existing deployment.
-//
-// Differences from `create`:
-//   • Reads current .env values; uses them as prompt defaults.
-//   • Never regenerates SELVA_HMAC_KEY / SELVA_AT_REST_KEY if they're set.
-//     Rotating those invalidates sessions and at-rest encryption — that's
-//     `selva keys rotate`'s job, not init's.
-//   • Doesn't touch package.json or run npm install.
+// `selva init` — reconfigures an existing deployment. Unlike `create`, it reads
+// the current .env as prompt defaults and never touches package.json or runs
+// npm install.
 
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
@@ -23,10 +18,10 @@ export async function runInit() {
 	const current = readEnvFile(envPath);
 	const values = await collectConfig({ defaults: current, mode: 'init' });
 
-	// Preserve secrets. The only safe time to generate them is at install
-	// time (no sessions to invalidate, no encrypted data to lose). If the
-	// existing .env doesn't have them — which can happen if a previous
-	// scaffold bailed mid-flight — generate now and warn.
+	// Never regenerate an existing key: rotating SELVA_HMAC_KEY or
+	// SELVA_AT_REST_KEY invalidates sessions and at-rest encryption — that's
+	// `selva keys rotate`'s job, not init's. Missing keys (a scaffold that
+	// bailed mid-flight) are the one case it's safe to generate here.
 	if (
 		current.SELVA_HMAC_KEY &&
 		current.SELVA_HMAC_KEY !== 'replace-this-with-a-random-32-byte-hex-key'
@@ -47,7 +42,11 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	writeEnvFile(envPath, readEnvTemplate(dir), values);
+	// A values-only rewrite drops anything it isn't handed, and the prompts cover
+	// only the vars they ask about — every tuned knob the operator set by hand
+	// (BODY_SIZE_LIMIT, COMPUTE_*, LOG_LEVEL, …) lives outside that set. Carry
+	// the existing file forward and let the prompt answers win on top.
+	writeEnvFile(envPath, readEnvTemplate(dir), { ...current, ...values });
 
 	p.outro(
 		[