@selvajs/cli 4.5.0 → 4.6.0-beta.0

package/package.json

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

package/src/commands/create.js

@@ -1,16 +1,6 @@
-// `npx @selvajs/cli <dir>` — scaffold a fresh deployment.
-//
-// What this writes into <dir>:
-//   .env                    merged from runtime's .env.example + prompt values
-//   ecosystem.config.cjs    copied verbatim from runtime templates
-//   package.json            depends on @selvajs/selva + @selvajs/cli + pm2
-//   .selva-version          marker for future CLI migrations
-//   node_modules/           after `npm install`
-//
-// The runtime templates are the source of truth — we don't carry our own
-// copies in @selvajs/cli. We install @selvajs/selva first, then copy
-// from node_modules/@selvajs/selva/templates/. Provider selection is
-// env-driven (SELVA_AUTH_PROVIDER etc.) — no selva.config.js is generated.
+// 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.
 
 import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
 import { resolve, join, basename } from 'node:path';
@@ -37,27 +27,22 @@ export async function runCreate(argv) {
 	}
 	mkdirSync(targetDir, { recursive: true });
 
-	// 1. Collect config. --yes (or CI=1) takes everything from the
-	//    environment instead of prompting — for Terraform startup scripts,
-	//    Dockerfiles, and any other unattended bootstrap.
+	// --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' });
 
-	// 2. Always generate fresh secrets for a new install. They MUST be stable
-	//    across restarts; the env-merge logic below writes them once and
-	//    `selva init` later refuses to regenerate them.
+	// 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);
 
-	// 3. Write package.json before installing so npm has something to read.
+	// Write package.json, then install (need templates from @selvajs/selva).
 	const pkgJson = buildPackageJson(deployName, values);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
-	// 4. Install. We need @selvajs/selva on disk to copy templates from it.
 	if (!skipInstall) {
 		await runNpmInstall(targetDir);
 	} else {
@@ -66,7 +51,7 @@ export async function runCreate(argv) {
 		);
 	}
 
-	// 5. Now copy templates from the installed runtime and fill them in.
+	// Copy templates from installed runtime.
 	const runtimeTemplates = join(targetDir, 'node_modules', '@selvajs', 'selva', 'templates');
 	if (skipInstall || !existsSync(runtimeTemplates)) {
 		p.log.warn(
@@ -86,7 +71,6 @@ export async function runCreate(argv) {
 	writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
 	writeGitignore(targetDir);
 
-	// 6. Outro with next steps.
 	p.outro(
 		[
 			pc.green('Scaffolded ' + pc.cyan(targetDir)),
@@ -103,59 +87,37 @@ export async function runCreate(argv) {
 	);
 }
 
-// Run `npm install` with live progress and a real error report.
-//
-// The previous implementation used execSync + stdio:'pipe' which buffered
-// everything in memory and discarded it on failure — operators saw "Command
-// failed: npm install" with no clue what went wrong. We stream stdout/stderr
-// into a ring buffer instead, and on failure dump the last lines so they can
-// act on the actual error (sharp's libvips missing, registry timeout, etc.)
-// without fishing through /home/user/.npm/_logs/.
-//
-// Cache-bust hint: if npm prints a placeDep for @selvajs/selva@0.10.2
-// (which was published broken and unpublished), surface that so the operator
-// knows to `npm cache clean --force`.
+// 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)');
 
-		// Ring buffer — keep the last 80 lines so we can show them on failure.
+		// Keep last 80 lines for failure output.
 		const tail = [];
-		const maxTail = 80;
 		const remember = (line) => {
 			tail.push(line);
-			if (tail.length > maxTail) tail.shift();
+			if (tail.length > 80) tail.shift();
 		};
 
-		// Visible progress milestones. npm doesn't emit a clean progress
-		// stream; we cherry-pick recognizable transitions and pass them to
-		// the spinner so the operator sees movement.
+		// Extract progress milestones (reify: lines, package count).
 		const updateProgress = (line) => {
 			const trimmed = line.trim();
 			if (!trimmed) return;
-			// "added 412 packages" — final summary
 			if (/^added \d+ packages/.test(trimmed)) {
 				s.message('Finalizing installation');
 				return;
 			}
-			// "reify:foo: timing reifyNode..." — npm 8/9/10 progress lines.
-			// Pull the package name out and show it.
 			const reify = trimmed.match(/^reify:([^:]+):/);
 			if (reify) {
 				s.message(`Installing ${pc.cyan(reify[1])}`);
 				return;
 			}
-			// "npm WARN ..." / "npm error ..." — pass through prefixed.
-			if (/^npm (WARN|error|notice)/.test(trimmed)) {
-				// Don't change the spinner message for these — they're noisy.
-				return;
-			}
+			if (/^npm (WARN|error|notice)/.test(trimmed)) return;
 		};
 
-		// Spawn npm with --loglevel=info so we get reify: progress lines.
-		// We DO NOT use stdio: 'inherit' because that would interleave with
-		// the spinner; we DO want a live read so we can update the message.
+		// Spawn with --loglevel=info for reify: progress; pipe stdout/stderr for live updates.
 		const child = spawn('npm', ['install', '--loglevel=info'], {
 			cwd,
 			stdio: ['ignore', 'pipe', 'pipe'],
@@ -255,38 +217,16 @@ function envBool(v) {
 	return ['1', 'true', 'yes'].includes(String(v).toLowerCase());
 }
 
-// The deployment's package.json depends on @selvajs/selva (prebuilt
-// SvelteKit app with all providers bundled in) plus @selvajs/cli (the
-// operator-side tool). Provider selection is env-driven — no provider
-// packages need to be listed here.
-//
-// We list @selvajs/cli itself as a dep so the `selva` bin gets linked
-// into node_modules/.bin/. Without this the operator's only way to run
-// `selva doctor` / `selva start` is a global install of the CLI.
+// Depends on @selvajs/selva (prebuilt) + @selvajs/cli (operator tool).
+// @selvajs/cli links the `selva` bin; without it, only global CLI works.
 function buildPackageJson(name /*, values */) {
 	const deps = {
 		'@selvajs/cli': 'latest',
 		'@selvajs/selva': 'latest',
-		// pm2 lives in the deployment's own node_modules so `selva start` can
-		// resolve it via node_modules/.bin/pm2 without a global install. The
-		// pm2.js wrapper requires this local binary (see pm2Bin()) — we never
-		// fall back to a global pm2 because two pm2 binaries managing the
-		// same daemon produces persistent CLI-vs-daemon version-skew
-		// warnings and stops/restarts that mysteriously hang.
-		//
-		// PINNED EXACT (no caret) on purpose. PM2's daemon and CLI must be
-		// the same version, and the daemon is sticky — once a daemon is
-		// running, only `pm2 update` swaps it. A caret range means two
-		// deployments scaffolded weeks apart can install different 5.x
-		// versions, and any host that briefly ran a different pm2 (e.g. a
-		// stray `npm i -g pm2`) is left with a daemon that won't match
-		// either. Bump this deliberately, in lockstep with documentation.
+		// Deployment-local pm2 (pinned exact to prevent daemon version skew).
 		pm2: '5.4.3'
 	};
 
-	// Use `selva` (resolved via node_modules/.bin) in the npm scripts. Running
-	// them as `npm run start` / `npm run doctor` works without remembering the
-	// ./node_modules/.bin/ prefix.
 	const pkg = {
 		name: sanitizePackageName(name),
 		version: '0.1.0',

package/src/commands/doctor.js

@@ -1,18 +1,5 @@
-// `selva doctor` — validate a deployment without starting it.
-//
-// Checks:
-//   • .env and ecosystem.config.cjs exist
-//   • Layout drift (legacy provider packages, stale selva.config.js, etc.)
-//   • Secrets are present and look like 32-byte hex
-//   • DATA_PATH writable (when local provider is in use)
-//   • Supabase URL reachable (when supabase provider is in use)
-//   • @selvajs/selva installed
-//   • Boot persistence (Linux): dump.pm2 saved, systemd unit installed and
-//     pointing at the deployment-local pm2, no stray global pm2 on PATH
-//   • Origin set when behind a reverse proxy looks set
-//
-// Exits 0 (green) or 1 (any red); yellow checks don't fail the run.
-// All checks are read-only — doctor never starts or pings the pm2 daemon.
+// Validate deployment without starting it: files, secrets, layout, providers,
+// boot persistence. Read-only; yellow warnings don't fail, red failures exit 1.
 
 import { existsSync, readFileSync, accessSync, constants, statSync } from 'node:fs';
 import { join, resolve, dirname, delimiter } from 'node:path';
@@ -36,23 +23,13 @@ export async function runDoctor() {
 	const checks = [];
 	const env = readEnvFile(join(dir, '.env'));
 
-	// ── Files ──────────────────────────────────────────────────────────
 	checks.push(checkFile(join(dir, '.env'), '.env present'));
 	checks.push(checkFile(join(dir, 'ecosystem.config.cjs'), 'ecosystem.config.cjs present'));
-
-	// ── Layout drift ───────────────────────────────────────────────────
-	// Catches deployments still on the @selvajs/runtime layout (or other
-	// historical states) and points the operator at `selva migrate` instead
-	// of just letting the missing-package checks below scream.
 	checks.push(checkLayoutDrift(dir));
-
-	// ── Secrets ────────────────────────────────────────────────────────
 	checks.push(checkSecret(env.SELVA_HMAC_KEY, 'SELVA_HMAC_KEY is a 32-byte hex string'));
 	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte hex string'));
 
-	// ── Provider wiring ────────────────────────────────────────────────
-	// `header` is only valid for the auth slot — data/storage stay
-	// local|supabase. Mirror what providers.server.ts enforces.
+	// Header-auth: auth only; data/storage must be local or supabase.
 	const providers = {
 		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
 		data: (env.SELVA_DATA_PROVIDER ?? 'local').toLowerCase(),
@@ -86,7 +63,6 @@ export async function runDoctor() {
 		checks.push(...checkHeaderAuth(dir, env, providers.data));
 	}
 
-	// ── Tenancy ────────────────────────────────────────────────────────
 	const tenancy = (env.SELVA_TENANCY ?? 'single').toLowerCase();
 	if (tenancy !== 'single' && tenancy !== 'multi') {
 		checks.push(red(`SELVA_TENANCY="${tenancy}" — expected single|multi`));
@@ -94,27 +70,9 @@ export async function runDoctor() {
 		checks.push(green(`SELVA_TENANCY=${tenancy}`));
 	}
 
-	// ── Installed packages ─────────────────────────────────────────────
-	// Provider implementations are bundled into @selvajs/selva — only the
-	// runtime package needs to be on disk.
 	checks.push(checkPackage(dir, '@selvajs/selva'));
-
-	// ── CLI / runtime version alignment ────────────────────────────────
-	// The CLI and runtime ship as a `fixed` changeset group, so they SHOULD
-	// always share a version. They can still drift on disk: a caret pin
-	// (`^4`) won't cross a major, so after the group jumps to 5.x a stale
-	// `^4` pin silently keeps the CLI on 4.x. That's the exact failure that
-	// makes `selva update` look like a no-op for the CLI. Surface it.
 	checks.push(checkCliRuntimeAlignment(dir));
-
-	// ── Boot persistence (read-only) ───────────────────────────────────
-	// Validates that a reboot will actually bring the app back. All checks
-	// here are pure reads — no `pm2 ping`/daemon interaction — so doctor keeps
-	// its "never starts anything" contract. Linux/systemd only; skipped
-	// elsewhere because pm2's boot integration is platform-specific.
 	checks.push(...checkBootPersistence(dir));
-
-	// ── Origin (best-effort) ───────────────────────────────────────────
 	if (env.ORIGIN) {
 		try {
 			new URL(env.ORIGIN);
@@ -231,9 +189,7 @@ function majorOf(version) {
 	return m ? Number(m[1]) : null;
 }
 
-// Compare the running CLI's major against the installed @selvajs/selva
-// runtime's major. They release together (`fixed` group), so a major skew
-// means the deployment's `@selvajs/cli` pin is stale — bump it and reinstall.
+// CLI and runtime release together (fixed group); major skew = stale CLI pin.
 function checkCliRuntimeAlignment(dir) {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const cliVersion = readPackageVersion(join(here, '..', '..', 'package.json'));
@@ -262,17 +218,7 @@ function checkCliRuntimeAlignment(dir) {
 	);
 }
 
-// Validate that a VM reboot will resurrect the app. Three failure modes,
-// all of which we hit in the field:
-//   1. `pm2 save` never run → no dump.pm2 → resurrect restores nothing.
-//   2. `pm2 startup` never run → no systemd unit → pm2 never launches at boot.
-//   3. The systemd unit was generated from a *global* pm2 (the operator
-//      pasted pm2's auto-printed `sudo env ... pm2 startup` line verbatim
-//      while a global pm2 was on PATH). The unit then resurrects via a
-//      different pm2 than the deployment-local one the CLI manages with —
-//      silent version skew on every boot. This is the only RED here.
-// All checks are read-only (existsSync + reading the unit file + scanning
-// PATH); none touch the pm2 daemon, so doctor stays side-effect-free.
+// Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
 function checkBootPersistence(dir) {
 	// pm2's boot integration is Linux/systemd-specific. On macOS it's launchd
 	// (different unit path) and on Windows pm2 boot persistence isn't a thing —
@@ -281,7 +227,7 @@ function checkBootPersistence(dir) {
 
 	const out = [];
 
-	// 1. dump.pm2 — what `pm2 startup` resurrects. PM2_HOME overrides location.
+	// dump.pm2 (what pm2 startup resurrects).
 	const pm2Home = process.env.PM2_HOME ?? join(homedir(), '.pm2');
 	const dumpPath = join(pm2Home, 'dump.pm2');
 	if (existsSync(dumpPath)) {
@@ -295,7 +241,7 @@ function checkBootPersistence(dir) {
 		);
 	}
 
-	// 2 + 3. systemd unit: present, and pointing at the deployment-local pm2.
+	// systemd unit: present and pointing at deployment-local pm2.
 	const user = process.env.USER ?? process.env.LOGNAME;
 	const unitPath = user
 		? `/etc/systemd/system/pm2-${user}.service`
@@ -336,8 +282,7 @@ function checkBootPersistence(dir) {
 		);
 	}
 
-	// Global pm2 on PATH — the root cause of mode 3 and of day-to-day skew
-	// warnings. Advisory only.
+	// Warn if global pm2 is on PATH (root cause of version skew).
 	const globalPm2 = findGlobalPm2(dir);
 	if (globalPm2) {
 		out.push(
@@ -352,8 +297,7 @@ function checkBootPersistence(dir) {
 	return out;
 }
 
-// Scan PATH for a `pm2` binary that isn't this deployment's. Returns the first
-// such path, or null. Pure filesystem reads — no execution.
+// Scan PATH for stray pm2 binary (read-only).
 function findGlobalPm2(dir) {
 	const localBin = resolve(dir, 'node_modules', '.bin');
 	const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
@@ -382,25 +326,19 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// Defaults must match HeaderAuthProvider.DEFAULT_HEADERS. Duplicated here so
-// doctor doesn't have to load the runtime. If the provider's defaults ever
-// change, update both places — there's a smoke test in providers/header-auth
-// that pins them, so a divergence would surface in CI.
+// 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-specific sanity checks. None of these catch the truly dangerous
-// misconfigurations (header spoofing, missing proxy auth) — those are
-// runtime invariants we can't verify from here. We DO check the things we can:
-// allowlist file presence, HOST binding, ORIGIN, bootstrap admin, and the
-// resolved header names so they can be diffed against the proxy config.
+// Header-auth checks (read-only; runtime invariants like spoofing can't be verified).
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
 
-	// 1. Where does header-allowlist.json live?
+	// 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'));
@@ -410,26 +348,21 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		if (existsSync(allowlistPath)) {
 			out.push(green(`header-allowlist.json present (${allowlistDir}/header-allowlist.json)`));
 		} else {
-			// The provider creates it lazily, but a fresh deployment with no
-			// allowlisted UPNs locks everyone out — surface this so the
-			// operator knows to bootstrap.
+			// Provider creates lazily, but missing file locks everyone out.
 			out.push(
 				yellow(
 					`header-allowlist.json not found at ${allowlistDir}/ — no users will be allowed in until one is added`
 				)
 			);
 
-			// If we expect lazy creation, the dir (or its parent) needs to be
-			// writable. Only check when HEADER_AUTH_DATA_DIR is set explicitly
-			// — when falling back to DATA_PATH the `local` provider's own
-			// checkDataPath has already covered the same ground.
+			// Check writability only if explicitly set (DATA_PATH checked separately).
 			if (env.HEADER_AUTH_DATA_DIR) {
 				out.push(checkDirWritable(allowlistAbsDir, `HEADER_AUTH_DATA_DIR=${allowlistDir}`));
 			}
 		}
 	}
 
-	// 2. HOST binding. Loopback is strongly recommended for header-auth.
+	// 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)`));
@@ -447,9 +380,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(red('ORIGIN unset — required for header-auth (always behind a proxy)'));
 	}
 
-	// 4. If data provider isn't local, the allowlist file is the ONLY local
-	// state — make sure the operator picked an explicit dir, not the
-	// fall-through DATA_PATH which may not be set.
+	// 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(
@@ -474,13 +405,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	// 6. Resolved header names. The most common header-auth boot symptom is
-	// `user:null` because the proxy sets one set of names and the provider
-	// reads another. Print what the provider WILL read so the operator can
-	// diff it against the Caddyfile / oauth2-proxy config. We don't fail on
-	// custom names — operators legitimately override these for non-Caddy
-	// proxies — but yellow-flag the case where one is overridden and the
-	// others aren't, since a partial override is almost always a typo.
+	// 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,

package/src/commands/keys.js

@@ -1,16 +1,4 @@
-// `selva keys rotate <hmac|at-rest>` — generate a fresh secret and write it
-// back to .env. Refuses without an explicit confirm; what gets invalidated is
-// not subtle.
-//
-//   hmac     — SELVA_HMAC_KEY (HMAC-SHA256). Rotating logs every user out
-//              (cookie sessions stop verifying) and breaks any share-link /
-//              invite tokens that fell back to it (only relevant when
-//              SHARE_LINK_SECRET / INVITE_TOKEN_SECRET are unset — those have
-//              their own rotation cycle).
-//
-//   at-rest  — SELVA_AT_REST_KEY (AES-256-GCM). The encrypted Rhino.Compute
-//              API key in compute.config.json becomes undecryptable. The
-//              operator has to re-enter the key at /admin/compute.
+// Rotate SELVA_HMAC_KEY or SELVA_AT_REST_KEY; requires explicit confirm (blast radius in TARGETS).
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';

package/src/commands/migrate.js

@@ -1,27 +1,6 @@
-// `selva migrate` — bring an existing deployment onto the current layout.
-//
-// Three historical migrations exist for Selva deployments:
-//   1. `@selvajs/create` → `@selvajs/cli`  (CLI bootstrap; can't be automated
-//      since the operator has no `selva` binary yet — they run two npm
-//      commands by hand from the Hotfix doc).
-//   2. `@selvajs/runtime` → `@selvajs/selva`  (runtime bundling: UI, schemas,
-//      ui-kit and the providers' workspace deps are now built into
-//      @selvajs/selva).
-//   3. selva.config.js → env-driven providers  (the picker logic moved into
-//      the runtime; deployments no longer need a config file. Provider
-//      packages are bundled into @selvajs/selva.)
-//
-// Migrate automates 2 and 3 together: it rewrites package.json, drops the
-// now-bundled provider packages, removes any stale selva.config.js, and
-// rewrites ecosystem.config.cjs if it still points at @selvajs/runtime.
-//
-// Future package-layout shifts go here too — the command should remain
-// idempotent. On an already-current deployment it prints "nothing to
-// migrate" and exits 0.
-//
-// Mirrors `selva update`'s lifecycle: stop pm2, mutate node_modules, start
-// pm2 again with --update-env. Rollback restores package.json.bak on
-// npm-install failure so the operator isn't left with a broken deployment.
+// Migrate deployment to current layout: rewrite package.json (drop legacy
+// provider packages), remove stale selva.config.js, update ecosystem.config.cjs.
+// Idempotent; mirrors update's lifecycle (stop/mutate/start with rollback on failure).
 
 import {
 	existsSync,
@@ -109,16 +88,13 @@ export async function runMigrate() {
 		return;
 	}
 
-	// Stop pm2 before mutating node_modules. Same reasoning as `selva update`:
-	// SvelteKit's node adapter lazy-imports chunks, so swapping the build dir
-	// under a live process causes ERR_MODULE_NOT_FOUND on in-flight requests.
+	// Stop pm2 before npm rewrites (SvelteKit lazy-loads chunks; see update command).
 	const stopStatus = runPm2(dir, ['stop', APP_NAME], { inherit: false });
 	if (stopStatus !== 0) {
 		p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
 	}
 
-	// Back up everything we're about to mutate. Restored on npm-install failure
-	// so the operator isn't left with a half-migrated deployment.
+	// Back up for rollback on npm-install failure.
 	const bakPath = pkgPath + '.bak';
 	copyFileSync(pkgPath, bakPath);
 	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
@@ -130,9 +106,7 @@ export async function runMigrate() {
 
 	if (ecoHasStaleRuntime) {
 		copyFileSync(ecoPath, ecoPath + '.bak');
-		// Single-line rewrite: only @selvajs/runtime → @selvajs/selva. We don't
-		// regenerate from the canonical template here because the operator may
-		// have customized port/memory/cluster settings; preserve their edits.
+		// Rewrite @selvajs/runtime → @selvajs/selva only (preserve customizations).
 		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
 			/@selvajs\/runtime/g,
 			'@selvajs/selva'
@@ -140,10 +114,7 @@ export async function runMigrate() {
 		writeFileSync(ecoPath, ecoContent, 'utf8');
 	}
 
-	// Nuke node_modules + lockfile. A simple `npm install` won't always
-	// resolve correctly when major version ranges change (e.g. runtime 0.10
-	// → selva 2.0) — the lockfile pins old transitive deps that no longer
-	// belong. Clean install is the only reliable path.
+	// Clean install required (major version changes break legacy lockfile).
 	rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
 	rmSync(join(dir, 'package-lock.json'), { force: true });
 
@@ -166,9 +137,7 @@ export async function runMigrate() {
 		if (ecoHasStaleRuntime && existsSync(ecoPath + '.bak')) {
 			copyFileSync(ecoPath + '.bak', ecoPath);
 		}
-		// Try to bring the old process back up so we don't leave the operator
-		// with downtime. If node_modules was wiped this won't help, but at
-		// least package.json matches what's on disk.
+		// Try to bring the process back up (best-effort; at least package.json is consistent).
 		runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
 		p.outro(pc.red(`Migration aborted: ${err.message ?? err}`));
 		process.exit(1);
@@ -192,16 +161,8 @@ export async function runMigrate() {
 	}
 }
 
-// Compute what package.json should look like given the current contents.
-//
-// Wholesale-replace semantics: any @selvajs/* or pm2 entry not in our
-// canonical set is dropped. Non-selva deps the operator added are also
-// dropped — that's the design choice we made up-front.
-//
-// Provider packages (@selvajs/local-provider etc.) are NOT preserved even
-// when the operator's .env selects them: they're bundled into @selvajs/selva
-// in v2.1+ and the standalone packages are legacy. Providers are picked at
-// runtime from SELVA_*_PROVIDER env vars.
+// Build target package.json with canonical dependencies (wholesale replace).
+// Drops non-canonical @selvajs/* and operator's own deps (by design).
 function buildTargetPackageJson(current) {
 	const deps = {
 		'@selvajs/cli': 'latest',
@@ -219,8 +180,7 @@ function buildTargetPackageJson(current) {
 	};
 }
 
-// Produce human-readable diff lines for the confirmation prompt. Keep it
-// short — the operator just needs to see what's moving, not a unified diff.
+// Format package.json diff for confirmation prompt (concise, not full diff).
 function diffPackageJson(before, after) {
 	const lines = [];
 
@@ -252,9 +212,7 @@ function diffPackageJson(before, after) {
 	return lines;
 }
 
-// Local copy of pm2.js's runner. Importing it would create a circular
-// dependency via the `pm2.js` exports; pm2 invocation is small enough to
-// duplicate.
+// Local pm2 runner (avoid circular dep; duplication is small).
 function runPm2(dir, args, { inherit = true } = {}) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	const bin = existsSync(local) ? local : 'pm2';
@@ -267,8 +225,7 @@ function runPm2(dir, args, { inherit = true } = {}) {
 	return result.status ?? 0;
 }
 
-// Exported for use by `selva doctor` so it can warn about layout drift
-// without duplicating the detection logic.
+// Exported for `selva doctor` to check layout drift without duplication.
 export function detectDrift(pkgJson, dir) {
 	const deps = pkgJson?.dependencies ?? {};
 	const reasons = [];
@@ -299,6 +256,5 @@ export function detectDrift(pkgJson, dir) {
 	return reasons;
 }
 
-// Re-exported so tests/imports can verify what migrate would write without
-// actually running it.
+// Re-exported for tests to verify without running migrate.
 export { buildTargetPackageJson, SELVA_DEPS };

package/src/commands/pm2.js

@@ -1,16 +1,6 @@
-// Thin wrappers around PM2 commands. The point isn't to abstract pm2 —
-// it's to hide footguns the docs already warn about:
-//
-//   • `pm2 restart` without --update-env silently keeps the old env, even
-//     after the operator edited .env. We always pass --update-env.
-//
-//   • PM2's daemon and CLI must be the same version. The daemon is sticky:
-//     once forked it runs that version forever, regardless of what the on-
-//     disk binary later becomes. We resolve pm2 to ONE binary (the project-
-//     local one) so every command — interactive, scripted, admin endpoint —
-//     hits the same code path. If a different pm2 ever started the daemon
-//     (e.g. a stray `npm i -g pm2`), `ensurePm2InSync` detects the skew
-//     and runs `pm2 update` to respawn the daemon under our binary.
+// Thin wrappers around PM2 commands: always pass --update-env (ignore edits),
+// resolve to deployment-local pm2 (avoid daemon version skew with global install),
+// and resync daemon before state changes.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -21,9 +11,7 @@ import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 const APP_NAME = 'selva-compute';
 
-// Resolve pm2 to the deployment's own copy. NO global fallback — having two
-// pm2 binaries on the same host and letting them both manage the daemon
-// produces the exact version-skew bug this wrapper exists to prevent.
+// Resolve to deployment-local pm2 (no global fallback; prevents version skew).
 function pm2Bin(dir) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	if (!existsSync(local)) {
@@ -37,12 +25,7 @@ function pm2Bin(dir) {
 	return local;
 }
 
-// Check whether the in-memory PM2 daemon was forked by a different pm2 than
-// the one we're about to invoke. PM2 prints "In-memory PM2 is out-of-date" on
-// every command in that state and process operations may stall. `pm2 update`
-// is the only fix: dump → kill daemon → respawn under the current binary →
-// resurrect dump. We run it here before any state-changing command so the
-// caller never gets a half-applied stop/restart against a stale daemon.
+// Check for daemon/CLI version mismatch; run `pm2 update` if stale.
 function ensurePm2InSync(dir) {
 	const bin = pm2Bin(dir);
 	const probe = spawnSync(bin, ['ping'], {
@@ -142,19 +125,10 @@ export async function runUpdate() {
 		return;
 	}
 
-	// Resync the daemon BEFORE we touch the running app — if the daemon is a
-	// different version than the local CLI, `pm2 stop` may report success
-	// while leaving the process group in a half-state, and the subsequent
-	// `pm2 start` then hangs. Running `pm2 update` here puts everything on
-	// the same version (and survives the dump+resurrect cycle).
+	// Resync daemon before state changes (avoid half-state stop/start).
 	ensurePm2InSync(dir);
 
-	// Stop the running process BEFORE npm rewrites node_modules/@selvajs/selva/build/.
-	// SvelteKit's node adapter lazy-imports chunks from build/server/chunks/ on every
-	// request; if we let npm replace them while the old process is still serving
-	// traffic, in-flight requests hit ERR_MODULE_NOT_FOUND for chunks whose hash
-	// just changed. Brief downtime (~1-2s longer than restart-in-place) but no
-	// chunk-mismatch errors.
+	// Stop before npm rewrites (SvelteKit lazy-loads chunks; see migrate command).
 	const stopStatus = runPm2(dir, ['stop', APP_NAME], { inherit: false });
 	if (stopStatus !== 0) {
 		p.log.warn('pm2 stop did not succeed — selva-compute may not be running. Continuing.');
@@ -163,11 +137,7 @@ export async function runUpdate() {
 	const s = p.spinner();
 	s.start(`npm update ${packages.join(' ')}`);
 	try {
-		// --prefer-online forces npm to revalidate cached packuments against
-		// the registry before using them. Without this, npm's 5+ minute
-		// packument cache silently re-installs the same version even when a
-		// newer one was published in the meantime. See docs/Hotfix-CLI-Runtime.md
-		// "The stale-packument-cache trap".
+		// --prefer-online bypasses npm's packument cache (see docs/Hotfix-CLI-Runtime.md).
 		execSync(`npm update --save --prefer-online ${packages.join(' ')}`, {
 			cwd: dir,
 			stdio: 'pipe'
@@ -175,7 +145,7 @@ export async function runUpdate() {
 		s.stop('npm update finished');
 	} catch (err) {
 		s.stop('npm update failed');
-		// Bring the old process back up so the operator isn't left with downtime.
+		// Best-effort: bring old process back up.
 		runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
 		throw err;
 	}
@@ -183,10 +153,7 @@ export async function runUpdate() {
 	const after = readRuntimeVersion(dir);
 	p.log.info(`New @selvajs/selva:     ${after ?? 'unknown'}`);
 
-	// Surface no-op updates explicitly. --prefer-online closes most cache
-	// holes, but a freshly-published version can take a minute or two to
-	// propagate through npm's CDN — operators who run update too quickly
-	// after publish still see "Current = New". Tell them how to retry.
+	// Surface no-op updates (cache may be stale; propagation delay is real).
 	if (before && after && before === after) {
 		p.log.warn(
 			[

package/src/env.js

@@ -1,8 +1,4 @@
-// Minimal .env parser / serializer.
-//
-// We don't pull in dotenv: the runtime already loads .env via node --env-file,
-// and the CLI's needs are simpler than dotenv supports (no shell expansion, no
-// multiline values). Keeping it in-tree means one less dep to vet.
+// Minimal .env parser/serializer (no dotenv; runtime uses node --env-file).
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 
@@ -32,12 +28,7 @@ export function readEnvFile(path) {
 	return parseEnv(readFileSync(path, 'utf8'));
 }
 
-// Re-serialize a .env file. Comments + section structure from `template` are
-// preserved; lines whose key appears in `values` get rewritten in-place. Keys
-// in `values` but absent from the template are appended at the end.
-//
-// Lines beginning with `# KEY=...` (commented examples) are treated as
-// suggestions and left alone; the actual value (if any) goes uncommented.
+// 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/);
@@ -78,11 +69,7 @@ export function mergeEnv(template, values) {
 		out.push(...appended);
 	}
 
-	// Always end with a single trailing newline. Without it, a later
-	// `echo VAR=value >> .env` concatenates onto the last line, producing
-	// `HOST=127.0.0.1HEADER_AUTH_DATA_DIR=...` and a `getaddrinfo ENOTFOUND`
-	// boot crash. Strip any existing trailing blanks first so we don't grow
-	// the file by a line on each rewrite.
+	// Ensure single trailing newline (shell append mishap guard).
 	while (out.length > 0 && out[out.length - 1] === '') out.pop();
 	return out.join('\n') + '\n';
 }

package/src/prompts.js

@@ -1,6 +1,4 @@
-// Shared prompt flow used by both `create` (fresh scaffold) and
-// `selva init` (reconfigure existing install). The two callers differ only in
-// what defaults are passed in and what gets written afterwards.
+// Shared prompt flow for create and init; differs only in defaults and output.
 
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
@@ -12,17 +10,8 @@ function envBool(v) {
 	return TRUTHY.has(String(v).toLowerCase());
 }
 
-// Non-interactive sibling of `collectConfig`. Reads everything from `env`
-// (defaults to process.env) so unattended bootstraps — Terraform startup
-// scripts, CI, Docker entrypoints — never touch a prompt. Same output shape
-// as `collectConfig` so the caller code in create.js doesn't branch further.
-//
-// Validation mirrors collectConfig's prompt-time checks. Anything missing or
-// malformed throws with the offending var name so the boot log makes the
-// fix obvious. We deliberately do NOT fall back to a "safe default" for
-// security-relevant fields (BOOTSTRAP_INSTANCE_ADMIN_EMAIL for header-auth /
-// multi-tenant, SUPABASE_SERVICE_ROLE_KEY when supabase is selected) — a
-// silently-misconfigured deploy is worse than a loud failure.
+// Non-interactive sibling of collectConfig: read from env, validate strictly,
+// fail loud for security-relevant fields (no safe defaults).
 export function collectConfigFromEnv(env = process.env) {
 	const tenancy = pick(env.SELVA_TENANCY, ['single', 'multi'], 'single', 'SELVA_TENANCY');
 	const auth = pick(
@@ -55,7 +44,6 @@ export function collectConfigFromEnv(env = process.env) {
 		SELVA_STORAGE_PROVIDER: storage
 	};
 
-	// ── Provider-specific config ──────────────────────────────────────────
 	if (auth === 'local' || data === 'local' || storage === 'local') {
 		values.DATA_PATH = env.DATA_PATH || './.selva-data';
 	}
@@ -101,7 +89,6 @@ export function collectConfigFromEnv(env = process.env) {
 	}
 	values.BOOTSTRAP_INSTANCE_ADMIN_EMAIL = adminEmail;
 
-	// ── Reverse proxy ────────────────────────────────────────────────────
 	const origin = env.ORIGIN || '';
 	if (origin) {
 		try {
@@ -115,10 +102,7 @@ export function collectConfigFromEnv(env = process.env) {
 	}
 	values.ORIGIN = origin;
 
-	// ── Feature flags ────────────────────────────────────────────────────
-	// Pass-through: any SELVA_FLAG_* var set on the environment is written
-	// verbatim. Unset flags get an empty string so the .env file still has
-	// a row for them (operator can flip later without editing structure).
+	// Pass-through: SELVA_FLAG_* vars written verbatim; unset = empty string.
 	const flagNames = [
 		'ALLOW_ORG_CREATION',
 		'ALLOW_CROSS_ORG_PUBLIC',
@@ -148,12 +132,8 @@ function requireEnv(env, name) {
 	return v;
 }
 
-// Runs the full interactive prompt sequence and returns a flat object of
-// env-var-name → value (string). The caller decides whether to merge with an
-// existing .env or write fresh.
-//
-// `defaults` is an existing env map (from .env, or {}). Anything present there
-// pre-populates the prompt so re-running is cheap.
+// 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';
 
@@ -164,7 +144,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	// these env vars are absent. To re-enable, add a brand prompt block here
 	// and write the values into `values` below.
 
-	// ── Tenancy ─────────────────────────────────────────────────────────
 	const tenancy = await p.select({
 		message: 'Tenancy mode',
 		initialValue: defaults.SELVA_TENANCY ?? 'single',
@@ -183,7 +162,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	});
 	cancelOn(tenancy);
 
-	// ── Auth provider ───────────────────────────────────────────────────
 	const auth = await p.select({
 		message: 'Auth backend',
 		initialValue: defaults.SELVA_AUTH_PROVIDER ?? 'local',
@@ -199,9 +177,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	});
 	cancelOn(auth);
 
-	// Header-auth is auth-only — it has no data/storage to share. The user
-	// MUST pick a separate backend for those. Local is the sensible default
-	// pairing (same filesystem as the allowlist).
+	// Header-auth: auth-only; user must pick separate data/storage backend.
 	let data;
 	let storage;
 	if (auth === 'header') {
@@ -229,9 +205,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		cancelOn(storageChoice);
 		storage = storageChoice;
 	} else {
-		// In practice operators almost always want data + storage on the same
-		// backend as auth. Ask once, default the others; let advanced users
-		// override.
+		// 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)
@@ -265,7 +239,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		}
 	}
 
-	// ── Provider-specific config ───────────────────────────────────────
 	const providerValues = {};
 	if (auth === 'local' || data === 'local' || storage === 'local') {
 		const dataPath = await p.text({
@@ -316,10 +289,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	}
 
 	if (auth === 'header') {
-		// HEADER_AUTH_DATA_DIR is where header-allowlist.json lives. When the
-		// data provider is local, DATA_PATH is the natural home and we let
-		// the provider fall back to it. Only ask explicitly if data isn't
-		// local — otherwise there's no obvious default.
+		// 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',
@@ -369,10 +339,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 			providerValues.HEADER_AUTH_DISPLAY_NAME_HEADER = stringValue(display);
 		}
 
-		// Header-auth deployments MUST bind to loopback. We don't force it
-		// (the operator might run inside a Docker network where the proxy
-		// reaches the container by service name), but we set HOST=127.0.0.1
-		// as the default and let them override.
+		// Header-auth: default to loopback (not enforced; Docker networks may override).
 		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'
@@ -381,14 +348,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		providerValues.HOST = bindLoopback ? '127.0.0.1' : stringValue(defaults.HOST);
 	}
 
-	// ── Bootstrap admin ────────────────────────────────────────────────
-	// Two roles in one env var: (1) gate the "first-signup-becomes-admin"
-	// path to a specific email — required for multi-tenant so a random
-	// signup doesn't get Selva staff perms; (2) break-glass recovery if
-	// admin is lost to a backup restore / manual DB edit. The check ONLY
-	// runs while no admin exists yet, so leaving it set permanently is
-	// safe. Phrase the prompt differently per tenancy/auth-provider because
-	// the security implications differ.
+	// Bootstrap admin (checked only while no admin exists; safe to leave set).
 	if (auth === 'header') {
 		p.note(
 			[
@@ -449,7 +409,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	});
 	cancelOn(adminEmail);
 
-	// ── Reverse proxy ──────────────────────────────────────────────────
 	const behindProxy = await p.confirm({
 		message: 'Behind a reverse proxy (Caddy, nginx, etc.)?',
 		initialValue: Boolean(defaults.ORIGIN)
@@ -476,10 +435,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		cancelOn(value);
 		origin = String(value);
 
-		// Plain HTTP + NODE_ENV=production drops the session cookie (Secure
-		// flag on, browser refuses to send over http://). Login appears to
-		// succeed but the next request is anonymous. Warn loudly here — the
-		// fix is either TLS or ALLOW_INSECURE_COOKIES=true in .env.
+		// Plain HTTP kills Secure cookies in production (login appears to succeed, then anon).
 		if (origin.startsWith('http://')) {
 			p.note(
 				'Sessions use Secure cookies in production; browsers will silently\n' +
@@ -494,7 +450,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 		}
 	}
 
-	// ── Platform flags ─────────────────────────────────────────────────
 	const flagOptions = [
 		{
 			value: 'ALLOW_ORG_CREATION',
@@ -535,7 +490,6 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	});
 	cancelOn(flags);
 
-	// ── Done ───────────────────────────────────────────────────────────
 	const values = {
 		SELVA_TENANCY: tenancy,
 		SELVA_AUTH_PROVIDER: auth,
@@ -554,9 +508,7 @@ export async function collectConfig({ defaults = {}, mode = 'create' } = {}) {
 	return values;
 }
 
-// `selva init` should default to "yes, same provider for all three" only when
-// the current .env already reflects that. If the operator deliberately split
-// auth and data, don't re-merge them on reconfigure.
+// 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;
@@ -565,8 +517,6 @@ function pickSameProviderDefault(defaults, auth) {
 }
 
 function cancelOn(v) {
-	// @clack/prompts returns Symbol(clack:cancel) when the user hits Ctrl+C.
-	// p.isCancel() is the official API for detecting it.
 	if (p.isCancel(v)) {
 		p.cancel('Cancelled.');
 		process.exit(0);
@@ -578,9 +528,7 @@ function stringValue(v) {
 	return String(v);
 }
 
-// Shown once when the operator picks header-auth. The provider's README is
-// emphatic that the deployment IS the security boundary — none of these
-// invariants can be enforced at runtime, so we surface them up front.
+// Header-auth security: deployment IS the boundary (runtime enforcement impossible).
 function headerAuthSecurityWarning() {
 	return [
 		'Header-auth trusts identity headers from the upstream proxy. Anyone who',