@selvajs/cli 4.20.0-beta.2 → 4.20.0-beta.21

package/src/commands/migrate.js

@@ -2,13 +2,22 @@
 // provider packages), removes stale selva.config.js, updates ecosystem.config.cjs.
 // Idempotent; mirrors update's lifecycle (stop/mutate/start with rollback on failure).
 
-import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from 'node:fs';
+import {
+	existsSync,
+	readFileSync,
+	readdirSync,
+	writeFileSync,
+	copyFileSync,
+	rmSync,
+	renameSync
+} from 'node:fs';
 import { join } from 'node:path';
 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';
+import { readEnvFile, renameEnvKeys, RENAMED_ENV_VARS, writeEnvText } from '../env.js';
+import { planEnvMigration } from '../env-migration.js';
 import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
@@ -100,7 +109,7 @@ export function classifyBackups(names, now = new Date(), maxAgeDays = BACKUP_AGE
 // dependency tree, so it has to run against a real directory — but not against
 // a real npm or pm2 daemon.
 export async function runMigrate(
-	_argv,
+	argv = [],
 	{
 		dir: injectedDir,
 		// --prefer-online: npm can otherwise resolve a cached packument that
@@ -114,7 +123,13 @@ export async function runMigrate(
 	const dir = injectedDir ?? resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
-	p.intro(pc.bgCyan(pc.black(' selva migrate ')));
+	const dryRun = argv.includes('--dry-run');
+	p.intro(pc.bgCyan(pc.black(dryRun ? ' selva migrate --dry-run ' : ' selva migrate ')));
+
+	if (argv.includes('--undo')) {
+		undoEnvMigration(dir);
+		return;
+	}
 
 	const pkgPath = join(dir, 'package.json');
 	if (!existsSync(pkgPath)) {
@@ -123,7 +138,7 @@ export async function runMigrate(
 	}
 
 	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
-	const deploymentEnv = readDeploymentEnv(join(dir, '.env'));
+	const deploymentEnv = readEnvFile(join(dir, '.env'));
 	const { pkg: target, notes: pinNotes } = buildTargetPackageJson(
 		before,
 		resolveVersion,
@@ -131,32 +146,76 @@ export async function runMigrate(
 	);
 	const pkgDiff = diffPackageJson(before, target);
 
-	// The server drops its read-old-name shim after one minor version, so
-	// rewriting now is what keeps a tuned value tuned instead of silently
-	// reverting to defaults later.
+	// The server stops reading old names in a later release, so rewriting now is
+	// what keeps a tuned value tuned instead of silently reverting to a default.
 	const envPath = join(dir, '.env');
 	const envBefore = existsSync(envPath) ? readFileSync(envPath, 'utf8') : null;
-	const envRename = envBefore
-		? renameEnvKeys(envBefore, RENAMED_ENV_VARS)
-		: { text: '', changes: [] };
-
-	const sideFileChanges = [];
-	for (const [oldName, newName, action] of envRename.changes) {
-		sideFileChanges.push(
-			action === 'dropped'
-				? `${pc.red('-')} .env ${pc.dim(`${oldName} (deprecated; ${newName} is already set)`)}`
-				: `${pc.yellow('~')} .env ${pc.dim(`${oldName} → ${newName}`)}`
+	const envPlan = envBefore
+		? planEnvMigration(envBefore)
+		: { text: '', changes: [], mismatches: [], blockers: [], fallbacks: [], unknown: [] };
+	const envChanged = envPlan.changes.length > 0;
+
+	// The rewrite would change what a setting means. Never write that.
+	if (envPlan.mismatches.length > 0) {
+		p.log.error('The .env rewrite would change these settings, so nothing was written:');
+		for (const m of envPlan.mismatches) {
+			console.log(`  ${m.key}: ${JSON.stringify(m.was)} → ${JSON.stringify(m.is)}`);
+		}
+		p.outro(pc.red('Migration refused. Please report this: it is a bug in the migration.'));
+		process.exit(1);
+	}
+
+	// Values the old readers ignored that this release refuses to boot on.
+	if (envPlan.blockers.length > 0) {
+		p.log.error('This release would not start with these .env values:');
+		for (const b of envPlan.blockers) console.log(`  ${b.key} ${b.problem}`);
+		p.outro(
+			pc.red(
+				'Fix them first (`selva config set KEY=VALUE`), then run migrate again. Nothing was written.'
+			)
 		);
+		process.exit(1);
 	}
+	for (const f of envPlan.fallbacks) {
+		p.log.warn(`${f.key} ${f.problem}: the app runs on its default instead.`);
+	}
+
+	const sideFileChanges = envPlan.changes.map(describeEnvChange);
 
 	if (pkgDiff.length === 0 && sideFileChanges.length === 0) {
+		reportUnknown(envPlan.unknown);
 		p.outro(pc.green('Already on the current layout — nothing to migrate.'));
 		return;
 	}
 
-	p.log.info('Changes to apply:');
+	p.log.info(dryRun ? 'Would apply (nothing is written in a dry run):' : 'Changes to apply:');
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
+	reportUnknown(envPlan.unknown);
+
+	if (dryRun) {
+		p.outro(pc.green('Every setting keeps its meaning. Run without --dry-run to apply.'));
+		return;
+	}
+
+	// Only .env changes: no reinstall, no restart of anyone's running app.
+	if (pkgDiff.length === 0) {
+		const go = await confirm('Rewrite .env (a backup is kept)?');
+		if (p.isCancel(go) || !go) {
+			p.cancel('Cancelled.');
+			return;
+		}
+		const bak = backupPathFor(envPath, backupStamp());
+		copyFileSync(envPath, bak);
+		writeEnvText(bak, readFileSync(bak, 'utf8'));
+		writeEnvText(envPath, envPlan.text);
+		p.outro(
+			pc.green('.env migrated. ') +
+				pc.dim(`Backup: ${bak}. Undo: selva migrate --undo. Apply: `) +
+				pc.cyan('selva restart')
+		);
+		return;
+	}
 
 	// The diff shows the pin that will be written; these explain why it is that
 	// pin. A preserved beta and a pin that couldn't be resolved both look like
@@ -203,9 +262,10 @@ export async function runMigrate(
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
 
-	if (envRename.changes.length > 0) {
+	if (envChanged) {
 		copyFileSync(envPath, envBak);
-		writeFileSync(envPath, envRename.text, 'utf8');
+		writeEnvText(envBak, readFileSync(envBak, 'utf8'));
+		writeEnvText(envPath, envPlan.text);
 	}
 
 	// A legacy lockfile pins the old package set across a major bump, so this needs
@@ -231,7 +291,7 @@ export async function runMigrate(
 	} catch (err) {
 		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
-		if (envRename.changes.length > 0 && existsSync(envBak)) {
+		if (envChanged && existsSync(envBak)) {
 			copyFileSync(envBak, envPath);
 		}
 
@@ -263,12 +323,12 @@ export async function runMigrate(
 	// here, once, instead of letting doctor nag forever. Deliberately NOT
 	// automated: `pm2 update` recycles the daemon, and doing that unattended
 	// inside a migration converts a mid-flight failure into an outage (see
-	// plans/fixes/host-prerequisites-and-pm2-audit.md).
+	// plans/archive/host-prerequisites-and-pm2-audit.md).
 	const pm2Notice = buildPm2UpgradeNotice(before.dependencies?.pm2, target.dependencies.pm2);
 	if (pm2Notice) p.log.warn(pm2Notice);
 
 	const backupHints = [`package.json.${stamp}.bak`];
-	if (envRename.changes.length > 0) backupHints.push(`.env.${stamp}.bak`);
+	if (envChanged) backupHints.push(`.env.${stamp}.bak`);
 
 	if (status === 0) {
 		p.outro(
@@ -305,19 +365,6 @@ function restartAfterRollback(dir, pm2 = runPm2) {
 	}
 }
 
-// Only the provider keys matter here, so this reads `KEY=value` lines rather
-// than pulling in a dotenv parser: no quoting, expansion, or multi-line values
-// to honour.
-function readDeploymentEnv(envPath) {
-	if (!existsSync(envPath)) return {};
-	const env = {};
-	for (const line of readFileSync(envPath, 'utf8').split(/\r?\n/)) {
-		const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
-		if (match) env[match[1]] = match[2].trim().replace(/^["']|["']$/g, '');
-	}
-	return env;
-}
-
 function buildTargetPackageJson(current, resolveVersion = npmDistTagVersion, env = {}) {
 	const supabase = needsSupabaseProvider(env);
 	const { pins, notes } = resolveSelvaPins(
@@ -475,3 +522,51 @@ export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
 }
 
 export { buildTargetPackageJson, diffPackageJson };
+
+function describeEnvChange(c) {
+	const env = (text) => `${pc.yellow('~')} .env ${pc.dim(text)}`;
+	switch (c.action) {
+		case 'stripped':
+			return env('shipped template comments removed (your own notes above a setting are kept)');
+		case 'renamed':
+			return env(`${c.key} → ${c.to}`);
+		case 'dropped':
+			return `${pc.red('-')} .env ${pc.dim(`${c.key} (${c.reason})`)}`;
+		case 'replaced':
+			return env(`${c.key} → ${c.to}`);
+		case 'rewritten':
+			return env(`${c.key} written as ${c.to}, what it already meant`);
+		case 'removed':
+			return `${pc.red('-')} .env ${pc.dim(`${c.key} (${c.reason})`)}`;
+		default:
+			return env(c.key);
+	}
+}
+
+function reportUnknown(unknown) {
+	for (const u of unknown) {
+		p.log.warn(
+			`.env sets ${u.key}, which Selva does not read${u.suggestion ? ` (did you mean ${u.suggestion}?)` : ''}. Left as is.`
+		);
+	}
+}
+
+/** Restore the newest .env backup migrate (or config set) wrote. */
+function undoEnvMigration(dir) {
+	const backups = readdirSync(dir)
+		.filter((f) => f.startsWith('.env.') && BACKUP_PATTERN.test(f))
+		.sort()
+		.reverse();
+	if (backups.length === 0) {
+		p.outro(pc.yellow('No .env backup to restore.'));
+		return;
+	}
+	const envPath = join(dir, '.env');
+	const current = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	// Keep what is being replaced, so an undo can itself be undone.
+	if (current) writeEnvText(backupPathFor(envPath, backupStamp()), current);
+	writeEnvText(envPath, readFileSync(join(dir, backups[0]), 'utf8'));
+	p.outro(
+		pc.green(`Restored .env from ${backups[0]}. `) + pc.dim('Apply: ') + pc.cyan('selva restart')
+	);
+}

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/env-migration.js

@@ -0,0 +1,148 @@
+// Plan the .env rewrite `selva migrate` applies: old names renamed, values a
+// looser reader used to accept rewritten to what they meant, no-op 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,
+	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,
+	SELVA_FLAG_COMPUTE_DEBUG_VERBOSE: () => undefined
+};
+
+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' });
+	}
+
+	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) && 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,17 +1,16 @@
-// 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 } 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'
-};
+// 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]))
+);
 
 // 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.
@@ -156,23 +155,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 +179,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 +236,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 +337,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');
 }