@selvajs/cli 4.8.2 → 4.9.0

package/README.md

@@ -24,7 +24,7 @@ selva keys rotate hmac      # rotate SELVA_HMAC_KEY (logs everyone out)
 selva keys rotate at-rest   # rotate SELVA_AT_REST_KEY (compute API key needs re-entry)
 ```
 
-`selva init` never regenerates `SELVA_HMAC_KEY` or `SELVA_AT_REST_KEY` once they're set — rotating those is `keys rotate`'s job, since it invalidates sessions or encrypted data. A `.selva-version` marker records which CLI version scaffolded the directory, so a later `selva migrate` knows what layout it's upgrading from.
+`selva init` never regenerates `SELVA_HMAC_KEY` or `SELVA_AT_REST_KEY` once they're set — rotating those is `keys rotate`'s job, since it invalidates sessions or encrypted data.
 
 ## Relationship to `@selvajs/selva`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.2",
+  "version": "4.9.0",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",

package/src/caddyfile.js

@@ -0,0 +1,89 @@
+// The Caddyfile a Selva deployment sits behind.
+//
+// This is the same config `infra/startup.sh.tpl` writes on the Terraform path —
+// kept here as the single source so the two deployment routes can't drift.
+// Anything changed in one has to be changed in the other, and a diff between
+// them is a bug.
+//
+// Only the production (HTTPS + ACME) shape is emitted. The dev/plain-HTTP
+// variant is deliberately absent: it exists in
+// docs/self-hosting/deployment/Caddyfile.example for hand-editing, and a
+// generator that can silently produce a no-TLS config is a footgun — Secure
+// cookies are dropped over http://, so login appears to work and every
+// subsequent request is anonymous.
+
+/**
+ * Render a Caddyfile for `domain`, reverse-proxying to the local app port.
+ *
+ * `www.<domain>` gets a permanent redirect to the apex. Skipped when the domain
+ * is already a subdomain — `www.app.example.dev` is not a name anyone points at,
+ * and Caddy would try to provision a certificate for it on first boot and log a
+ * failure every retry.
+ */
+export function renderCaddyfile({ domain, acmeEmail, port = 3000 }) {
+	const labels = domain.split('.').length;
+	const wantsWww = labels === 2;
+
+	const site = `${domain} {
+	encode gzip
+
+	# === HEADER AUTH SLOT ===
+	# Forward-auth providers go here. See packages/providers/header-auth/README.md.
+
+	reverse_proxy 127.0.0.1:${port}
+
+	header {
+		Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+		X-Content-Type-Options    "nosniff"
+		Referrer-Policy           "strict-origin-when-cross-origin"
+		Permissions-Policy        "geolocation=(), microphone=(), camera=()"
+		-Server
+	}
+
+	@static path /assets/*
+	header @static Cache-Control "public, max-age=31536000, immutable"
+	@api path /api/*
+	header @api Cache-Control "no-cache, no-store, must-revalidate"
+
+	request_body {
+		max_size 100mb
+	}
+
+	log {
+		output file /var/log/caddy/access.log
+		format json
+	}
+}`;
+
+	const www = wantsWww
+		? `
+
+www.${domain} {
+	redir https://${domain}{uri} permanent
+}`
+		: '';
+
+	return `{
+	email ${acmeEmail}
+}
+
+${site}${www}
+`;
+}
+
+/** A hostname Caddy can request a certificate for. */
+export function isServableDomain(value) {
+	if (typeof value !== 'string') return false;
+	const domain = value.trim();
+	if (domain === '' || domain.length > 253) return false;
+	// Rejects bare hostnames, IPs, and anything with a scheme, port, or path —
+	// ACME issues against a resolvable FQDN and nothing else.
+	return /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i.test(
+		domain
+	);
+}
+
+/** The origin a given domain implies, for cross-checking `.env`. */
+export function originFor(domain) {
+	return `https://${domain}`;
+}

package/src/checks/boot.js

@@ -18,6 +18,7 @@ import { spawnSync } from 'node:child_process';
 import { posix as path } from 'node:path';
 import { homedir } from 'node:os';
 import { green, red, yellow, fixable } from './result.js';
+import { escalationHint, runPrivileged } from './privileged.js';
 
 /** The real OS. Tests pass a stand-in with the same shape. */
 export const systemEnv = {
@@ -34,7 +35,8 @@ export const systemEnv = {
 			return false;
 		}
 	},
-	run: (cmd, args, opts) => spawnSync(cmd, args, { ...opts, encoding: 'utf8' })
+	run: (cmd, args, opts) => spawnSync(cmd, args, { ...opts, encoding: 'utf8' }),
+	runPrivileged: (cmd, args, opts) => runPrivileged(cmd, args, opts)
 };
 
 export function checkBootPersistence(dir, env = systemEnv) {
@@ -80,7 +82,12 @@ function checkSystemdUnit(dir, env) {
 			yellow(
 				'pm2 systemd boot unit not installed — the app will NOT restart after a ' +
 					'reboot. Run `npx pm2 startup systemd -u $USER --hp $HOME` and paste the ' +
-					'printed command (point it at this deployment’s pm2).'
+					'printed command (point it at this deployment’s pm2).',
+				user
+					? fixable('install the pm2 systemd boot unit (needs sudo)', () =>
+							installBootUnit(dir, user, env)
+						)
+					: undefined
 			)
 		];
 	}
@@ -106,11 +113,74 @@ function checkSystemdUnit(dir, env) {
 				`Reboots will resurrect via the wrong pm2 (version skew). Re-run startup ` +
 				`with the local binary:\n     ` +
 				`sudo env PATH=$PATH:${path.join(dir, 'node_modules', '.bin')} ${localPm2} ` +
-				`startup systemd -u $USER --hp $HOME`
+				`startup systemd -u $USER --hp $HOME`,
+			fixable('repoint the boot unit at this deployment’s pm2 (needs sudo)', () =>
+				installBootUnit(dir, user, env)
+			)
 		)
 	];
 }
 
+/**
+ * Install (or overwrite) the pm2 systemd unit so it resurrects via this
+ * deployment's pm2.
+ *
+ * pm2's own `startup` subcommand doesn't write the unit when run unprivileged —
+ * it prints a `sudo env PATH=… pm2 startup …` line for the operator to paste.
+ * Rather than parse that line, this runs the same command through `sudo`
+ * directly: PATH carries the deployment's `.bin` so systemd's generated
+ * ExecStart resolves to the local pm2 rather than whichever one is on root's
+ * PATH — the exact skew the wrong-unit branch above exists to catch.
+ *
+ * A unit without a saved process list resurrects nothing, so `pm2 save` runs
+ * after. Reporting it separately keeps a save failure from reading as a failed
+ * unit install.
+ */
+function installBootUnit(dir, user, env) {
+	const localPm2 = path.join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
+	if (!env.exists(localPm2)) {
+		return red('pm2 not installed in this deployment — run `npm install` first');
+	}
+
+	const home = env.env().HOME ?? env.homedir();
+	const binDir = path.join(dir, 'node_modules', '.bin');
+	const result = env.runPrivileged(
+		'env',
+		[
+			`PATH=${env.env().PATH ?? ''}:${binDir}`,
+			localPm2,
+			'startup',
+			'systemd',
+			'-u',
+			user,
+			'--hp',
+			home
+		],
+		{ cwd: dir }
+	);
+
+	if (result.blocked) {
+		return yellow(
+			`could not escalate — ${escalationHint(result.reason)}. Run this yourself:\n     ` +
+				result.command
+		);
+	}
+	if (!result.ok) {
+		return red(
+			`pm2 startup failed (exit ${result.status}). Run it manually:\n     ` + result.command
+		);
+	}
+
+	const saved = env.run(path.join(binDir, 'pm2'), ['save'], { cwd: dir });
+	if ((saved.status ?? 1) !== 0) {
+		return yellow(
+			'boot unit installed, but `pm2 save` failed — a reboot would resurrect an ' +
+				'empty process list. Run `npx pm2 save` once the app is started.'
+		);
+	}
+	return green('pm2 systemd boot unit installed and process list saved');
+}
+
 // A pm2 outside the deployment is the root cause of daemon version skew.
 function checkStrayGlobalPm2(dir, env) {
 	const globalPm2 = findGlobalPm2(dir, env);

package/src/checks/privileged.js

@@ -0,0 +1,92 @@
+// Running a command as root from a tool the operator invoked as themselves.
+//
+// Every privileged repair in the CLI funnels through here so there is exactly
+// one place that decides whether escalation is possible, and exactly one shape
+// for "we could not, here is the line to run yourself". A fixer that shells out
+// to sudo on its own would each need to re-derive that fallback, and the ones
+// that got it wrong would strand an operator mid-repair with no printed command.
+//
+// The contract: never escalate without the caller having already confirmed, and
+// never escalate when nobody is at the terminal to answer a password prompt.
+// `sudo -n` (non-interactive) is the probe for the second — it exits non-zero
+// rather than blocking when a password would be needed.
+
+import { spawnSync } from 'node:child_process';
+
+/** The real OS. Tests pass a stand-in with the same shape. */
+export const systemPrivileged = {
+	platform: () => process.platform,
+	isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+	geteuid: () => (typeof process.geteuid === 'function' ? process.geteuid() : null),
+	run: (cmd, args, opts) => spawnSync(cmd, args, { ...opts, encoding: 'utf8' })
+};
+
+/**
+ * How a privileged command can be run here, if at all.
+ *
+ * - `root`    — already uid 0; run it directly, no sudo needed.
+ * - `sudo`    — sudo exists and a TTY is attached to answer for it.
+ * - `blocked` — no way to escalate. `reason` says which, for the printed hint.
+ */
+export function escalationMode(env = systemPrivileged) {
+	if (env.platform() !== 'linux') return { mode: 'blocked', reason: 'not-linux' };
+	if (env.geteuid() === 0) return { mode: 'root' };
+
+	const probe = env.run('sudo', ['-n', 'true'], {});
+	// ENOENT surfaces as a null status with an error — sudo isn't installed.
+	if (probe.error) return { mode: 'blocked', reason: 'no-sudo' };
+
+	// A passwordless sudo (NOPASSWD, or a live credential cache) works even with
+	// no TTY, so it's checked before the TTY requirement rather than after.
+	if ((probe.status ?? 1) === 0) return { mode: 'sudo' };
+
+	if (!env.isTTY()) return { mode: 'blocked', reason: 'no-tty' };
+	return { mode: 'sudo' };
+}
+
+/** The reason text a blocked escalation reports, for a printed fallback. */
+export function escalationHint(reason) {
+	switch (reason) {
+		case 'not-linux':
+			return 'this step is Linux-only';
+		case 'no-sudo':
+			return 'sudo is not available on this host';
+		case 'no-tty':
+			return 'sudo needs a password and nothing is attached to answer it';
+		default:
+			return 'privileged commands cannot be run from here';
+	}
+}
+
+/**
+ * Run `cmd args` with root privileges.
+ *
+ * Returns `{ ok, status, stdout, stderr, command }` — `command` is the exact
+ * line that was run (or would have been), so a caller can print it verbatim
+ * when escalation is blocked rather than reconstructing it.
+ *
+ * Callers MUST have confirmed with the operator first. This does not prompt.
+ */
+export function runPrivileged(cmd, args, { env = systemPrivileged, cwd } = {}) {
+	const { mode, reason } = escalationMode(env);
+	const command = mode === 'root' ? [cmd, ...args].join(' ') : ['sudo', cmd, ...args].join(' ');
+
+	if (mode === 'blocked') {
+		return { ok: false, blocked: true, reason, command, stdout: '', stderr: '' };
+	}
+
+	const r =
+		mode === 'root'
+			? env.run(cmd, args, { cwd, stdio: 'inherit' })
+			: // stdio inherit so sudo's own password prompt reaches the terminal.
+				env.run('sudo', [cmd, ...args], { cwd, stdio: 'inherit' });
+
+	return {
+		ok: (r.status ?? 1) === 0,
+		blocked: false,
+		status: r.status ?? 1,
+		stdout: r.stdout ?? '',
+		stderr: r.stderr ?? '',
+		command
+	};
+}

package/src/cli.js

@@ -15,6 +15,7 @@ const COMMANDS = {
 	logs: () => import('./commands/pm2.js').then((m) => m.runLogs),
 	update: () => import('./commands/pm2.js').then((m) => m.runUpdate),
 	migrate: () => import('./commands/migrate.js').then((m) => m.runMigrate),
+	'setup-proxy': () => import('./commands/proxy.js').then((m) => m.runSetupProxy),
 	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
 };
 
@@ -52,6 +53,15 @@ const USAGE = {
 		blurb:
 			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
 	},
+	'setup-proxy': {
+		usage: 'selva setup-proxy [--domain <fqdn>] [--acme-email <addr>]',
+		blurb:
+			"Put Caddy in front of the app with a Let's Encrypt certificate. Installs\nCaddy if missing, writes /etc/caddy/Caddyfile, validates, and reloads.\nNeeds sudo; prints the config to apply by hand when it can't escalate.",
+		flags: [
+			['--domain', 'Domain to serve. Prompts (defaulting to ORIGIN) when omitted.'],
+			['--acme-email', "Address Let's Encrypt sends expiry notices to."]
+		]
+	},
 	keys: {
 		usage: 'selva keys rotate <hmac|at-rest>',
 		blurb:
@@ -129,6 +139,7 @@ function printHelp() {
 			'  logs                    pm2 logs selva-compute',
 			'  update                  npm update @selvajs/cli + @selvajs/selva, then restart',
 			'  migrate                 Bring package.json onto the current layout',
+			'  setup-proxy             Install + configure Caddy with TLS for this deployment',
 			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
 			'',
 			pc.dim('`npx selva <command> --help` explains one command.'),

package/src/commands/create.js

@@ -9,12 +9,7 @@ import pc from 'picocolors';
 import { collectConfig, collectConfigFromEnv } from '../prompts.js';
 import { generateKey } from '../secrets.js';
 import { writeEnvFile } from '../env.js';
-import {
-	isEmptyOrMissing,
-	requiredNodeRange,
-	runtimeTemplatePath,
-	scaffoldVersion
-} from '../paths.js';
+import { isEmptyOrMissing, requiredNodeRange, runtimeTemplatePath } from '../paths.js';
 import {
 	buildDeploymentPackageJson,
 	needsSupabaseProvider,
@@ -97,7 +92,6 @@ export async function runCreate(argv) {
 			`Couldn't read runtime templates from ${dirname(envTemplatePath)}. ` +
 				`Run \`npm install\`, then \`selva init\` to finish setup.`
 		);
-		writeFileSync(join(targetDir, '.selva-version'), scaffoldVersion() + '\n', 'utf8');
 		p.outro(`Partial scaffold at ${pc.cyan(targetDir)}.`);
 		return;
 	}
@@ -106,23 +100,71 @@ export async function runCreate(argv) {
 
 	cpSync(ecosystemTemplatePath, join(targetDir, 'ecosystem.config.cjs'));
 
-	writeFileSync(join(targetDir, '.selva-version'), scaffoldVersion() + '\n', 'utf8');
 	writeGitignore(targetDir);
 
-	p.outro(
-		[
-			pc.green('Scaffolded ' + pc.cyan(targetDir)),
-			'',
-			pc.bold('Next steps:'),
-			`  cd ${rawDir}`,
-			`  npm run doctor         # sanity-check the install`,
-			`  npm start              # pm2 start ecosystem.config.cjs`,
-			'',
-			values.ORIGIN
-				? `Then visit ${pc.cyan(values.ORIGIN)} (set up your reverse proxy first).`
-				: `Then visit ${pc.cyan('http://localhost:3000')}.`
-		].join('\n')
+	p.outro(nextSteps({ rawDir, values, supabase }).join('\n'));
+}
+
+/**
+ * The remaining work, in the order it has to happen.
+ *
+ * Ordered by dependency, not by importance: the schema has to exist before the
+ * app can serve a request, and the proxy has to terminate TLS before a browser
+ * will keep the session cookie. A list that mentioned them in any other order
+ * would have the operator debugging a 503 or a login loop that the next step
+ * was about to fix.
+ */
+function nextSteps({ rawDir, values, supabase }) {
+	const lines = [
+		pc.green('Scaffolded ' + pc.cyan(targetDirLabel(rawDir))),
+		'',
+		pc.bold('Next steps:')
+	];
+	let n = 1;
+
+	lines.push(`  ${n++}. cd ${rawDir}`);
+
+	if (supabase) {
+		lines.push(
+			`  ${n++}. Apply the database schema (once per Supabase project):`,
+			pc.dim('       npx selva-supabase          # copy migrations into ./supabase'),
+			pc.dim('       npx supabase link --project-ref <ref>'),
+			pc.dim('       npx supabase db push')
+		);
+	}
+
+	lines.push(
+		`  ${n++}. npm run doctor${pc.dim('       # verify config, schema, and boot persistence')}`
+	);
+	lines.push(`  ${n++}. npm start${pc.dim('            # start under pm2')}`);
+
+	if (values.ORIGIN?.startsWith('https://')) {
+		lines.push(
+			`  ${n++}. npx selva setup-proxy${pc.dim(' # Caddy + TLS for ' + hostOf(values.ORIGIN))}`
+		);
+	}
+
+	lines.push(
+		'',
+		values.ORIGIN
+			? `Then visit ${pc.cyan(values.ORIGIN)} and open ${pc.cyan('/setup')} to claim admin.`
+			: `Then visit ${pc.cyan('http://localhost:3000')} and open ${pc.cyan('/setup')} to claim admin.`,
+		'',
+		pc.dim('`npm run doctor --fix` repairs what it can, including pm2 boot persistence.')
 	);
+	return lines;
+}
+
+function targetDirLabel(rawDir) {
+	return resolve(rawDir);
+}
+
+function hostOf(origin) {
+	try {
+		return new URL(origin).host;
+	} catch {
+		return origin;
+	}
 }
 
 function runNpmInstall(cwd) {
@@ -158,7 +200,6 @@ function runNpmInstall(cwd) {
 			shell: process.platform === 'win32'
 		});
 
-		let sawBrokenVersion = false;
 		const handleStream = (stream) => {
 			let buf = '';
 			stream.setEncoding('utf8');
@@ -169,7 +210,6 @@ function runNpmInstall(cwd) {
 				for (const line of lines) {
 					remember(line);
 					updateProgress(line);
-					if (line.includes('@selvajs/selva@0.10.2')) sawBrokenVersion = true;
 				}
 			});
 			stream.on('end', () => {
@@ -202,19 +242,19 @@ function runNpmInstall(cwd) {
 			for (const line of tail) console.error(line);
 			console.error(pc.dim('──────────────────────────────'));
 
-			if (sawBrokenVersion) {
-				console.error('');
-				console.error(
-					pc.yellow(
-						'npm resolved @selvajs/selva@0.10.2 — that version is broken (unresolved\n' +
-							'workspace:* / catalog: specs) and has been unpublished. Your local npm\n' +
-							'cache is stale. Clear it and retry:\n\n' +
-							'  npm cache clean --force\n' +
-							'  rm -rf node_modules package-lock.json\n' +
-							'  npm install --prefer-online'
-					)
-				);
-			}
+			// A stale npm cache resolves versions that no longer exist on the
+			// registry, and the error it produces names the package rather than the
+			// cache — so this is worth suggesting on any install failure.
+			console.error('');
+			console.error(
+				pc.yellow(
+					'If the output above names a version that cannot be resolved, the local\n' +
+						'npm cache is stale. Clear it and retry:\n\n' +
+						'  npm cache clean --force\n' +
+						'  rm -rf node_modules package-lock.json\n' +
+						'  npm install --prefer-online'
+				)
+			);
 
 			rejectP(new Error(`npm install exited with code ${code}`));
 		});

package/src/commands/migrate.js

@@ -131,13 +131,6 @@ export async function runMigrate(
 	);
 	const pkgDiff = diffPackageJson(before, target);
 
-	const configPath = join(dir, 'selva.config.js');
-	const hasStaleConfig = existsSync(configPath);
-
-	const ecoPath = join(dir, 'ecosystem.config.cjs');
-	const ecoHasStaleRuntime =
-		existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime');
-
 	// 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.
@@ -148,14 +141,6 @@ export async function runMigrate(
 		: { text: '', changes: [] };
 
 	const sideFileChanges = [];
-	if (hasStaleConfig)
-		sideFileChanges.push(
-			`${pc.red('-')} selva.config.js ${pc.dim('(no longer needed; providers are env-driven)')}`
-		);
-	if (ecoHasStaleRuntime)
-		sideFileChanges.push(
-			`${pc.yellow('~')} ecosystem.config.cjs ${pc.dim('(rewrite: @selvajs/runtime → @selvajs/selva)')}`
-		);
 	for (const [oldName, newName, action] of envRename.changes) {
 		sideFileChanges.push(
 			action === 'dropped'
@@ -213,28 +198,11 @@ export async function runMigrate(
 	// later migration cannot overwrite this one's (#184).
 	const stamp = backupStamp();
 	const bakPath = backupPathFor(pkgPath, stamp);
-	const configBak = backupPathFor(configPath, stamp);
-	const ecoBak = backupPathFor(ecoPath, stamp);
 	const envBak = backupPathFor(envPath, stamp);
 
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
 
-	if (hasStaleConfig) {
-		copyFileSync(configPath, configBak);
-		rmSync(configPath, { force: true });
-	}
-
-	if (ecoHasStaleRuntime) {
-		copyFileSync(ecoPath, ecoBak);
-		// Text substitution, not regeneration, so any operator customizations to the file survive.
-		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
-			/@selvajs\/runtime/g,
-			'@selvajs/selva'
-		);
-		writeFileSync(ecoPath, ecoContent, 'utf8');
-	}
-
 	if (envRename.changes.length > 0) {
 		copyFileSync(envPath, envBak);
 		writeFileSync(envPath, envRename.text, 'utf8');
@@ -263,12 +231,6 @@ export async function runMigrate(
 	} catch (err) {
 		s.stop(pc.red('npm install failed — rolling back'));
 		copyFileSync(bakPath, pkgPath);
-		if (hasStaleConfig && existsSync(configBak)) {
-			copyFileSync(configBak, configPath);
-		}
-		if (ecoHasStaleRuntime && existsSync(ecoBak)) {
-			copyFileSync(ecoBak, ecoPath);
-		}
 		if (envRename.changes.length > 0 && existsSync(envBak)) {
 			copyFileSync(envBak, envPath);
 		}
@@ -306,8 +268,6 @@ export async function runMigrate(
 	if (pm2Notice) p.log.warn(pm2Notice);
 
 	const backupHints = [`package.json.${stamp}.bak`];
-	if (hasStaleConfig) backupHints.push(`selva.config.js.${stamp}.bak`);
-	if (ecoHasStaleRuntime) backupHints.push(`ecosystem.config.cjs.${stamp}.bak`);
 	if (envRename.changes.length > 0) backupHints.push(`.env.${stamp}.bak`);
 
 	if (status === 0) {
@@ -480,14 +440,6 @@ export function detectDrift(pkgJson, dir) {
 	}
 
 	if (dir) {
-		const configPath = join(dir, 'selva.config.js');
-		if (existsSync(configPath)) {
-			reasons.push('selva.config.js is no longer needed (providers are env-driven)');
-		}
-		const ecoPath = join(dir, 'ecosystem.config.cjs');
-		if (existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime')) {
-			reasons.push('ecosystem.config.cjs still references @selvajs/runtime');
-		}
 		const envPath = join(dir, '.env');
 		if (existsSync(envPath)) {
 			const { changes } = renameEnvKeys(readFileSync(envPath, 'utf8'), RENAMED_ENV_VARS);

package/src/commands/proxy.js

@@ -0,0 +1,254 @@
+// `selva setup-proxy` — put Caddy in front of the app with a real certificate.
+//
+// This is the step that separates "pm2 says the app is up" from "someone can
+// log in". The app binds 127.0.0.1 only, so without a proxy nothing reaches it;
+// and without TLS the session cookie is dropped by the browser, which looks
+// exactly like a login that silently fails.
+//
+// Every privileged action is confirmed once, up front, and routed through
+// runPrivileged so a host without sudo gets the exact commands printed instead
+// of a half-applied config.
+
+import { existsSync, readFileSync, writeFileSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+
+import { renderCaddyfile, isServableDomain, originFor } from '../caddyfile.js';
+import { escalationHint, escalationMode, runPrivileged } from '../checks/privileged.js';
+import { readEnvFile } from '../env.js';
+
+const CADDYFILE_PATH = '/etc/caddy/Caddyfile';
+
+export async function runSetupProxy(argv = []) {
+	const dir = process.cwd();
+	p.intro(pc.bgCyan(pc.black(' selva setup-proxy ')));
+
+	if (process.platform !== 'linux') {
+		p.outro(
+			pc.yellow(
+				`Caddy setup is automated for Linux/systemd only. On ${process.platform}, ` +
+					`copy docs/self-hosting/deployment/Caddyfile.example by hand.`
+			)
+		);
+		return;
+	}
+
+	const env = existsSync(join(dir, '.env')) ? readEnvFile(join(dir, '.env')) : {};
+	const domain = await resolveDomain(argv, env);
+	if (domain === null) return;
+
+	const acmeEmail = await resolveAcmeEmail(argv, env, domain);
+	if (acmeEmail === null) return;
+
+	// ORIGIN drives cookie and redirect behaviour. A proxy serving a domain the
+	// app doesn't know about produces logins that succeed then bounce, so this
+	// is worth stopping for rather than warning about after the fact.
+	const expectedOrigin = originFor(domain);
+	if (env.ORIGIN && env.ORIGIN !== expectedOrigin) {
+		p.log.warn(
+			`.env has ORIGIN=${env.ORIGIN}, but this proxy will serve ${expectedOrigin}.\n` +
+				`Sessions break when they disagree — update ORIGIN with \`selva init\` ` +
+				`(then \`selva restart\`) if the proxy domain is the right one.`
+		);
+	}
+
+	const caddyfile = renderCaddyfile({ domain, acmeEmail });
+	const { mode, reason } = escalationMode();
+	if (mode === 'blocked') {
+		printManualPath(caddyfile, reason);
+		p.outro(pc.yellow('Nothing was changed.'));
+		return;
+	}
+
+	const existing = readExistingCaddyfile();
+	if (existing && existing.trim() !== '' && !existing.includes('reverse_proxy 127.0.0.1')) {
+		// Someone else's config. Overwriting it could take an unrelated site
+		// offline, and this command has no way to merge two Caddyfiles.
+		p.log.warn(`${CADDYFILE_PATH} already exists and doesn't look like a Selva config.`);
+		const overwrite = await p.confirm({
+			message: `Overwrite ${CADDYFILE_PATH}? The current file is backed up first.`,
+			initialValue: false
+		});
+		if (p.isCancel(overwrite) || !overwrite) {
+			printManualPath(caddyfile, null);
+			p.outro(pc.yellow('Nothing was changed.'));
+			return;
+		}
+	}
+
+	const proceed = await p.confirm({
+		message: `Write ${CADDYFILE_PATH} for ${domain} and reload Caddy? (needs sudo)`,
+		initialValue: true
+	});
+	if (p.isCancel(proceed) || !proceed) {
+		p.outro(pc.yellow('Nothing was changed.'));
+		return;
+	}
+
+	if (!ensureCaddyInstalled()) {
+		p.outro(pc.red('Caddy is not installed and could not be installed automatically.'));
+		return;
+	}
+
+	const s = p.spinner();
+	s.start('Writing Caddyfile');
+	const staged = stageCaddyfile(caddyfile);
+	if (existing) runPrivileged('cp', [CADDYFILE_PATH, `${CADDYFILE_PATH}.bak`]);
+	const installed = runPrivileged('cp', [staged, CADDYFILE_PATH]);
+	if (!installed.ok) {
+		s.stop('Could not write the Caddyfile');
+		p.log.error(installed.blocked ? escalationHint(installed.reason) : installed.stderr);
+		return;
+	}
+	s.stop('Caddyfile written');
+
+	// Validate before reload: a bad config leaves the running Caddy untouched,
+	// so catching it here means the site never goes down.
+	const valid = runPrivileged('caddy', ['validate', '--config', CADDYFILE_PATH]);
+	if (!valid.ok) {
+		p.log.error('caddy validate rejected the generated config — reverting.');
+		if (existing) runPrivileged('cp', [`${CADDYFILE_PATH}.bak`, CADDYFILE_PATH]);
+		p.outro(pc.red('Proxy not configured.'));
+		return;
+	}
+
+	// The Debian package leaves /var/log/caddy root-owned while the service runs
+	// as `caddy`; without this the service fails to start on the log directive.
+	runPrivileged('mkdir', ['-p', '/var/log/caddy']);
+	runPrivileged('chown', ['-R', 'caddy:caddy', '/var/log/caddy']);
+
+	runPrivileged('systemctl', ['enable', 'caddy']);
+	const restarted = runPrivileged('systemctl', ['restart', 'caddy']);
+	if (!restarted.ok) {
+		p.log.error('caddy failed to restart — check `sudo journalctl -u caddy -n 50`.');
+		p.outro(pc.red('Proxy configured but not running.'));
+		return;
+	}
+
+	p.outro(
+		[
+			pc.green(`Caddy is serving ${domain}.`),
+			pc.dim('A certificate is requested on first request; it needs ') +
+				pc.cyan(`${domain} → this host`) +
+				pc.dim(' in DNS, and ports 80 + 443 open.'),
+			pc.dim('Check it with:  ') + pc.cyan(`curl -sI ${expectedOrigin}/api/health`)
+		].join('\n')
+	);
+}
+
+async function resolveDomain(argv, env) {
+	const flag = readFlag(argv, '--domain');
+	if (flag) {
+		if (isServableDomain(flag)) return flag;
+		p.log.error(`--domain ${flag} is not a valid domain name.`);
+		return null;
+	}
+
+	// ORIGIN is the domain the operator already committed to at scaffold time.
+	const fromOrigin = env.ORIGIN?.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+	const answer = await p.text({
+		message: 'Domain to serve (must already point at this host)',
+		placeholder: 'app.example.dev',
+		initialValue: fromOrigin && isServableDomain(fromOrigin) ? fromOrigin : '',
+		validate: (v) =>
+			isServableDomain(v) ? undefined : 'Enter a domain like app.example.dev (no scheme, no port).'
+	});
+	if (p.isCancel(answer)) {
+		p.outro(pc.yellow('Cancelled.'));
+		return null;
+	}
+	return answer.trim();
+}
+
+async function resolveAcmeEmail(argv, env, domain) {
+	const flag = readFlag(argv, '--acme-email');
+	if (flag) return flag;
+
+	const answer = await p.text({
+		message: "Email for Let's Encrypt (expiry notices)",
+		placeholder: `admin@${domain}`,
+		initialValue: env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL ?? '',
+		validate: (v) => (v.includes('@') ? undefined : 'Enter an email address.')
+	});
+	if (p.isCancel(answer)) {
+		p.outro(pc.yellow('Cancelled.'));
+		return null;
+	}
+	return answer.trim() || `admin@${domain}`;
+}
+
+function readFlag(argv, name) {
+	const i = argv.indexOf(name);
+	if (i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--')) return argv[i + 1].trim();
+	const inline = argv.find((a) => a.startsWith(`${name}=`));
+	return inline ? inline.slice(name.length + 1).trim() : null;
+}
+
+function readExistingCaddyfile() {
+	try {
+		return readFileSync(CADDYFILE_PATH, 'utf8');
+	} catch {
+		// Unreadable is the same as absent here: either way there's nothing to
+		// preserve, and the write is privileged regardless.
+		return null;
+	}
+}
+
+// Written to a temp file first because the shell redirect that would otherwise
+// place it (`echo … | sudo tee`) needs a shell, and passing config text through
+// one is how quoting bugs corrupt a file that then fails to validate.
+function stageCaddyfile(text) {
+	const staged = join(mkdtempSync(join(tmpdir(), 'selva-caddy-')), 'Caddyfile');
+	writeFileSync(staged, text, 'utf8');
+	return staged;
+}
+
+function ensureCaddyInstalled() {
+	if (spawnSync('caddy', ['version'], { encoding: 'utf8' }).status === 0) return true;
+
+	p.log.info('Caddy is not installed. Installing from the official apt repository.');
+	const steps = [
+		[
+			'apt-get',
+			['install', '-y', 'debian-keyring', 'debian-archive-keyring', 'apt-transport-https', 'curl']
+		],
+		['apt-get', ['update']],
+		['apt-get', ['install', '-y', 'caddy']]
+	];
+	// The keyring + source-list dance needs a shell pipeline, so it runs as one
+	// privileged `sh -c` rather than as spawn args.
+	const repo =
+		"curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg && " +
+		"curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' > /etc/apt/sources.list.d/caddy-stable.list";
+
+	const s = p.spinner();
+	s.start('Installing Caddy');
+	if (!runPrivileged(steps[0][0], steps[0][1]).ok) {
+		s.stop('Could not install Caddy prerequisites');
+		return false;
+	}
+	if (!runPrivileged('sh', ['-c', repo]).ok) {
+		s.stop('Could not add the Caddy apt repository');
+		return false;
+	}
+	for (const [cmd, args] of steps.slice(1)) {
+		if (!runPrivileged(cmd, args).ok) {
+			s.stop(`\`${cmd} ${args.join(' ')}\` failed`);
+			return false;
+		}
+	}
+	s.stop('Caddy installed');
+	return true;
+}
+
+function printManualPath(caddyfile, reason) {
+	if (reason) p.log.warn(`Cannot escalate — ${escalationHint(reason)}.`);
+	p.log.info(
+		`Write this to ${CADDYFILE_PATH} yourself, then ` +
+			`\`sudo caddy validate --config ${CADDYFILE_PATH} && sudo systemctl restart caddy\`:`
+	);
+	console.log('\n' + caddyfile);
+}

package/src/deployment-package.js

@@ -136,16 +136,16 @@ export const OVERRIDES = {
 };
 
 /**
- * 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.
+ * Packages folded into `@selvajs/selva` that a deployment may still list.
+ * `migrate` drops them and `doctor` reports them as layout drift.
+ *
+ * Only ones still on the registry are listed: an unpublished package fails
+ * `npm install` outright, so a deployment carrying one never reaches a state
+ * where this could report it — npm's own error is the diagnosis there.
  */
 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/header-auth-provider': 'now bundled into @selvajs/selva'
+	'@selvajs/local-provider': 'now bundled into @selvajs/selva'
 };
 
 /**

package/src/env.js

@@ -180,50 +180,6 @@ export function readEnvFile(path) {
 	return parseEnv(readFileSync(path, 'utf8'));
 }
 
-export function mergeEnv(template, values) {
-	const seen = new Set();
-	const lines = template.split(/\r?\n/);
-	const out = [];
-
-	for (const line of lines) {
-		const stripped = line.trim();
-		if (!stripped || stripped.startsWith('#')) {
-			out.push(line);
-			continue;
-		}
-		const eq = stripped.indexOf('=');
-		if (eq === -1) {
-			out.push(line);
-			continue;
-		}
-		const key = stripped.slice(0, eq).trim();
-		if (Object.prototype.hasOwnProperty.call(values, key)) {
-			out.push(`${key}=${quoteIfNeeded(values[key])}`);
-			seen.add(key);
-		} else {
-			out.push(line);
-		}
-	}
-
-	const appended = [];
-	for (const [key, value] of Object.entries(values)) {
-		if (seen.has(key)) continue;
-		if (value === undefined || value === null || value === '') continue;
-		appended.push(`${key}=${quoteIfNeeded(value)}`);
-	}
-
-	if (appended.length > 0) {
-		if (out.length > 0 && out[out.length - 1].trim() !== '') out.push('');
-		out.push('# ============================================================================');
-		out.push('# Additional values written by the Selva CLI');
-		out.push('# ============================================================================');
-		out.push(...appended);
-	}
-
-	while (out.length > 0 && out[out.length - 1] === '') out.pop();
-	return out.join('\n') + '\n';
-}
-
 /**
  * Render a values-only `.env` — the scaffold's default shape.
  *
@@ -265,14 +221,9 @@ export function renderEnvValues(template, values, { header = ENV_HEADER } = {})
 	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');
+/** Writes the deployment `.env` — values only, in the template's key order. */
+export function writeEnvFile(path, template, values) {
+	writeFileSync(path, renderEnvValues(template, values), 'utf8');
 }
 
 /**

package/src/paths.js

@@ -21,24 +21,6 @@ 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
@@ -53,9 +35,10 @@ export function runtimeTemplatePath(dir, name) {
  * 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.
+ * Returns `''` when neither exists rather than throwing — `renderEnvValues`
+ * writes every value it was given even with no template to order them by, 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');

package/src/prompts.js

@@ -48,7 +48,9 @@ const FLAG_NAMES = FLAG_OPTIONS.map((o) => o.value);
  * `single`, where one org makes both settings describe the same set.
  */
 export function promptableFlags(tenancy) {
-	return FLAG_OPTIONS.filter((o) => o.promptable !== false && (tenancy === 'multi' || !o.multiOnly));
+	return FLAG_OPTIONS.filter(
+		(o) => o.promptable !== false && (tenancy === 'multi' || !o.multiOnly)
+	);
 }
 
 function envBool(v) {