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

package/src/env.js

@@ -2,13 +2,10 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 
-/**
- * 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
- * (`readRenamed` in `@selvajs/server` `resolveComputeLimits`); `selva doctor`
- * reports them and `selva migrate` rewrites them. Keep in sync with that list,
- * and drop an entry when the server stops reading it.
- */
+// 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',
@@ -16,16 +13,148 @@ export const RENAMED_ENV_VARS = {
 	MAX_SOLVE_DURATION_MS: 'COMPUTE_SOLVE_DEADLINE_MS'
 };
 
-/**
- * Deprecated vars whose replacement changes the VALUE too, so they can't be
- * rewritten by renaming a key. `selva doctor` reports these; migrate leaves
- * them alone rather than guessing.
- */
+// 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'
 };
 
-// Parse a .env file into { key: value }. Preserves nothing else.
+// 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
+// is to paste the old annotated template back in.
+export const ENV_HEADER = [
+	'# Selva deployment configuration.',
+	'#',
+	'# Values only — every variable is documented in the runtime template at',
+	'# node_modules/@selvajs/selva/templates/.env.example, which is refreshed on',
+	'# every update. Do not paste that template in here: a copy stops tracking',
+	'# the release and starts describing variables the code no longer reads.'
+].join('\n');
+
+/**
+ * Strip a deployment `.env` down to its live settings, dropping the shipped
+ * documentation block.
+ *
+ * A comment block copied onto a server is a snapshot with no update path —
+ * `migrate` rewrites keys but never prose, so a deployment keeps documenting
+ * the release it was installed at, describing vars the code has since renamed
+ * or retired. Deleting it is what makes the file navigable AND unable to lie.
+ *
+ * Operator comments are NOT prose to be discarded: a short `#` run directly
+ * above a setting (no blank line between) is that setting's note and rides
+ * along with it. Everything else goes.
+ *
+ * "Short" is doing real work here. The shipped template also writes prose
+ * immediately above a setting — its banner blocks run 40+ lines and end with a
+ * bare `#` — so proximity alone would keep the very documentation this exists
+ * to remove. A hand-written note is a line or two; a block longer than
+ * ATTACHED_NOTE_MAX_LINES, or one containing a `# ====` banner rule, is the
+ * template's and is dropped.
+ *
+ * Returns `{ text, removed }`, `removed` being the count of dropped comment
+ * lines. `removed === 0` means the file was already values-only.
+ */
+export function stripEnvComments(text, { header = ENV_HEADER } = {}) {
+	// Our own header is re-emitted below, so counting it as prose we removed
+	// would make every run report work it didn't do — and break idempotency,
+	// which is what lets doctor call a stripped file clean. Matched as a whole
+	// leading block, not line-by-line: the header contains a bare `#`, and
+	// excluding that by value would silently stop counting an operator's own
+	// `#` separators anywhere in the file.
+	let lines = text.split(/\r?\n/);
+	if (header) {
+		const headerLines = header.split('\n');
+		const leads = headerLines.every((h, i) => lines[i]?.trim() === h.trim());
+		if (leads) lines = lines.slice(headerLines.length);
+	}
+	const out = [];
+	let pending = [];
+	let removed = 0;
+	let sawSetting = false;
+	// Whether a blank line or dropped prose separated the last setting from the
+	// next one — the original file's own grouping, worth carrying over.
+	let groupBreak = false;
+
+	const flushDropped = () => {
+		const dropped = pending.filter((l) => l.trim().startsWith('#'));
+		removed += dropped.length;
+		// A discarded banner marked a section boundary in the original; keep that
+		// boundary as a blank line so the result still reads as grouped settings.
+		if (dropped.length > 0 && sawSetting) groupBreak = true;
+		pending = [];
+	};
+
+	for (const line of lines) {
+		const stripped = line.trim();
+
+		if (stripped.startsWith('#')) {
+			pending.push(line);
+			continue;
+		}
+
+		// A blank line ends whatever comment block was accumulating: those
+		// comments float free rather than annotating the next setting.
+		if (!stripped) {
+			if (sawSetting) groupBreak = true;
+			flushDropped();
+			continue;
+		}
+
+		if (stripped.indexOf('=') === -1) {
+			flushDropped();
+			continue;
+		}
+
+		// Comments still pending sit directly above this setting. Keep them only
+		// if they read as a hand-written note rather than a template banner.
+		const note = isAttachedNote(pending);
+		// Blank line only where it earns one: before a kept note, or where the
+		// original had a break. Separating every key would just trade a wall of
+		// prose for a file twice as long as it needs to be.
+		if (sawSetting && (note || groupBreak)) out.push('');
+		if (note) {
+			out.push(...pending);
+		} else {
+			flushDropped();
+		}
+		pending = [];
+		groupBreak = false;
+		out.push(line);
+		sawSetting = true;
+	}
+
+	// Trailing comments annotate nothing.
+	flushDropped();
+
+	const body = out.join('\n');
+	return {
+		text: header ? `${header}\n\n${body}\n` : `${body}\n`,
+		removed
+	};
+}
+
+// A hand-written note is a line or two. Longer than this and it is the shipped
+// template's prose, which is what stripping exists to remove.
+const ATTACHED_NOTE_MAX_LINES = 3;
+
+// A `# ====` rule is the template's section-banner style; nothing hand-written
+// above a single setting uses it.
+const BANNER_RULE = /^#\s*[=-]{4,}/;
+
+function isAttachedNote(pending) {
+	if (pending.length === 0 || pending.length > ATTACHED_NOTE_MAX_LINES) return false;
+	return !pending.some((l) => BANNER_RULE.test(l.trim()));
+}
+
+/**
+ * How many lines of the file are shipped documentation rather than config.
+ * Used by `selva doctor` to flag an annotated `.env` without rewriting it.
+ */
+export function countEnvCommentLines(text) {
+	const { removed } = stripEnvComments(text);
+	return removed;
+}
+
 export function parseEnv(text) {
 	const out = {};
 	for (const rawLine of text.split(/\r?\n/)) {
@@ -51,7 +180,6 @@ export function readEnvFile(path) {
 	return parseEnv(readFileSync(path, 'utf8'));
 }
 
-// Merge values into template: preserve structure, rewrite in-place, append new keys.
 export function mergeEnv(template, values) {
 	const seen = new Set();
 	const lines = template.split(/\r?\n/);
@@ -92,27 +220,71 @@ export function mergeEnv(template, values) {
 		out.push(...appended);
 	}
 
-	// Ensure single trailing newline (shell append mishap guard).
 	while (out.length > 0 && out[out.length - 1] === '') out.pop();
 	return out.join('\n') + '\n';
 }
 
-export function writeEnvFile(path, template, values) {
-	writeFileSync(path, mergeEnv(template, values), 'utf8');
+/**
+ * Render a values-only `.env` — the scaffold's default shape.
+ *
+ * The annotated template is genuinely useful while you are deciding what to
+ * set, which is why the runtime still ships it; it stops being useful the
+ * moment it is written to a server and cannot be corrected there. So the
+ * template stays a reference and the deployment gets values, in the template's
+ * own key order (it groups related settings) with anything unknown appended.
+ */
+export function renderEnvValues(template, values, { header = ENV_HEADER } = {}) {
+	const ordered = [];
+	const seen = new Set();
+
+	// The template names a var three ways — live (`KEY=v`), commented-out
+	// (`# KEY=v`), and as a bare mention in prose (`# KEY   single | multi`).
+	// All three signal where the var belongs, so the first token of any line is
+	// enough; anything that isn't a known key is filtered out below.
+	for (const rawLine of template.split(/\r?\n/)) {
+		const stripped = rawLine.trim().replace(/^#\s*/, '');
+		const key = stripped.split(/[\s=]/)[0]?.trim();
+		if (!key || !/^[A-Z][A-Z0-9_]{2,}$/.test(key)) continue;
+		if (seen.has(key)) continue;
+		if (!Object.prototype.hasOwnProperty.call(values, key)) continue;
+		seen.add(key);
+		ordered.push(key);
+	}
+
+	for (const key of Object.keys(values)) {
+		if (!seen.has(key)) ordered.push(key);
+	}
+
+	const lines = [];
+	for (const key of ordered) {
+		const value = values[key];
+		if (value === undefined || value === null || value === '') continue;
+		lines.push(`${key}=${quoteIfNeeded(value)}`);
+	}
+
+	return header ? `${header}\n\n${lines.join('\n')}\n` : `${lines.join('\n')}\n`;
+}
+
+/**
+ * Writes the deployment `.env`. Values-only by default — pass
+ * `{ annotated: true }` to merge into the template's comments instead, which
+ * only an operator who explicitly wants the old shape should do.
+ */
+export function writeEnvFile(path, template, values, { annotated = false } = {}) {
+	const text = annotated ? mergeEnv(template, values) : renderEnvValues(template, values);
+	writeFileSync(path, text, 'utf8');
 }
 
 /**
- * Rewrite deprecated keys to their current names, in place. `renames` maps old
- * name → new name. Only the key is touched — the value, comments, ordering and
- * spacing survive, so an operator's tuned file stays recognisably theirs.
+ * Rewrite deprecated keys to their current names, in place. Only the key is
+ * touched — value, comments, ordering, and spacing survive.
  *
  * A key already present under its new name is left alone and its old line is
- * dropped: the server resolves the same way (new name wins), so keeping both
- * would preserve a line that does nothing.
+ * dropped: the server resolves new-name-wins, so keeping both would preserve
+ * a line that does nothing.
  *
- * Returns `{ text, changes }` where `changes` is `[oldName, newName, 'renamed'
- * | 'dropped']` per line acted on; an empty array means the file was already
- * current and nothing should be written.
+ * Returns `{ text, changes }`, `changes` being `[oldName, newName, 'renamed'
+ * | 'dropped']` per line acted on. Empty means the file was already current.
  */
 export function renameEnvKeys(text, renames) {
 	const present = new Set(Object.keys(parseEnv(text)));

package/src/paths.js

@@ -65,9 +65,8 @@ export function readEnvTemplate(dir) {
 	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.
+// Either .env or ecosystem.config.cjs is enough — selva.config.js and
+// node_modules are expected too, but init should still fix a partial install.
 export function isDeploymentDir(dir) {
 	return existsSync(join(dir, '.env')) || existsSync(join(dir, 'ecosystem.config.cjs'));
 }

package/src/prompts.js

@@ -18,9 +18,7 @@ export function collectConfigFromEnv(env = process.env) {
 		'local',
 		'SELVA_AUTH_PROVIDER'
 	);
-	// Default data/storage to auth — matches the prompt's "use same provider
-	// for all three" default. Header-auth has no data layer, so it falls
-	// through to local unless explicitly overridden.
+	// Header-auth has no data layer, so it falls through to local unless overridden.
 	const dataDefault = auth === 'header' ? 'local' : auth;
 	const data = pick(
 		env.SELVA_DATA_PROVIDER,
@@ -72,7 +70,6 @@ export function collectConfigFromEnv(env = process.env) {
 			values.HEADER_AUTH_DISPLAY_NAME_HEADER = env.HEADER_AUTH_DISPLAY_NAME_HEADER;
 	}
 
-	// ── Bootstrap admin ──────────────────────────────────────────────────
 	const adminRequired = auth === 'header' || tenancy === 'multi';
 	const adminEmail = env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL || '';
 	if (adminRequired && !adminEmail) {
@@ -127,15 +124,11 @@ function requireEnv(env, name) {
 	return v;
 }
 
-// Run full interactive prompt sequence; return env vars. Caller decides merge vs fresh.
-// `defaults` pre-populates prompts (cheap re-run).
 export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	const isInit = mode === 'init';
 
 	p.intro(pc.bgCyan(pc.black(isInit ? ' selva init ' : ' Selva — new deployment ')));
 
-	// Brand prompts (SELVA_BRAND_NAME / COPYRIGHT_NAME / TAGLINE / DESCRIPTION)
-
 	const tenancy = await p.select({
 		message: 'Tenancy mode',
 		initialValue: defaults.SELVA_TENANCY ?? 'single',
@@ -169,7 +162,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	});
 	cancelOn(auth);
 
-	// Header-auth: auth-only; user must pick separate data/storage backend.
 	let data;
 	let storage;
 	if (auth === 'header') {
@@ -197,7 +189,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		cancelOn(storageChoice);
 		storage = storageChoice;
 	} else {
-		// Operators usually want same backend for all three; ask once, default the others.
 		const mixProviders = await p.confirm({
 			message: `Use ${pc.cyan(auth)} for data and storage too?`,
 			initialValue: pickSameProviderDefault(defaults, auth)
@@ -281,7 +272,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	}
 
 	if (auth === 'header') {
-		// HEADER_AUTH_DATA_DIR: ask only if data provider isn't local (fallback available).
 		if (data !== 'local') {
 			const dataDir = await p.text({
 				message: 'HEADER_AUTH_DATA_DIR — directory for header-allowlist.json',
@@ -330,7 +320,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 			providerValues.HEADER_AUTH_DISPLAY_NAME_HEADER = stringValue(display);
 		}
 
-		// Header-auth: default to loopback (not enforced; Docker networks may override).
+		// Not enforced — a Docker network can still route to the container on another host.
 		const bindLoopback = await p.confirm({
 			message: 'Bind the app to 127.0.0.1 only? (recommended for header-auth)',
 			initialValue: !defaults.HOST || defaults.HOST === '127.0.0.1' || defaults.HOST === 'localhost'
@@ -339,7 +329,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		providerValues.HOST = bindLoopback ? '127.0.0.1' : stringValue(defaults.HOST);
 	}
 
-	// Bootstrap admin (checked only while no admin exists; safe to leave set).
 	if (auth === 'header') {
 		p.note(
 			[
@@ -494,10 +483,11 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	return values;
 }
 
-// Init: default to "same provider" only if current .env already shows that.
 function pickSameProviderDefault(defaults, auth) {
 	const data = defaults.SELVA_DATA_PROVIDER ?? auth;
 	const storage = defaults.SELVA_STORAGE_PROVIDER ?? auth;
+	// No existing defaults means a fresh `create`, not a re-prompted `init` — default to
+	// "same provider for all three" since there's nothing yet to disagree with auth.
 	if (!defaults.SELVA_DATA_PROVIDER && !defaults.SELVA_STORAGE_PROVIDER) return true;
 	return data === auth && storage === auth;
 }