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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.0-beta.11",
+  "version": "4.8.0-beta.12",
   "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/checks/config.js

@@ -65,6 +65,106 @@ export function checkOrigin(env) {
 	return green(`ORIGIN=${env.ORIGIN}`);
 }
 
+// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
+// A test in providers/header-auth pins both sides, so drift surfaces in CI.
+export const DEFAULT_HEADER_NAMES = {
+	upn: 'SELVA-UserPrincipalName',
+	email: 'SELVA-Email',
+	displayName: 'SELVA-DisplayName'
+};
+
+// oauth2-proxy's `set_xauthrequest` names. Two proxy styles are documented and
+// both are correct, but they need opposite env config:
+//
+//   rewrite      — Caddy maps X-Auth-Request-* onto SELVA-* before proxying.
+//                  Selva sees SELVA-*, so the overrides must be UNSET.
+//   copy-through — Caddy forwards X-Auth-Request-* unchanged.
+//                  Selva sees those names, so all three must be overridden.
+//
+// Mixing them is the failure this check exists to catch: a name Selva reads but
+// the proxy never sends yields `null` from identifyFromHeaders (for the UPN, a
+// total login failure) with nothing in the logs pointing at the env var.
+const OAUTH2_PROXY_HEADERS = new Set([
+	'x-auth-request-user',
+	'x-auth-request-email',
+	'x-auth-request-preferred-username'
+]);
+
+/**
+ * Reports the header names the provider will actually read, and flags the
+ * combinations that can't match any documented proxy config.
+ *
+ * Deliberately not a "did you override all three" count: with the rewrite
+ * style, zero overrides is the correct answer, so counting alone would push
+ * operators toward breaking a working deployment.
+ */
+export function checkHeaderNames(env) {
+	const resolved = {
+		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
+		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,
+		displayName: env.HEADER_AUTH_DISPLAY_NAME_HEADER || DEFAULT_HEADER_NAMES.displayName
+	};
+	const list = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
+
+	const oauth2 = Object.values(resolved).filter((h) =>
+		OAUTH2_PROXY_HEADERS.has(h.toLowerCase())
+	).length;
+	const defaults = Object.entries(resolved).filter(
+		([slot, name]) => name === DEFAULT_HEADER_NAMES[slot]
+	).length;
+
+	if (oauth2 === 0) {
+		return defaults === 3
+			? green(`header names (bundled defaults): ${list}`)
+			: green(`header names (custom): ${list}`);
+	}
+
+	// Some X-Auth-Request-*, some SELVA-* defaults — neither proxy style emits
+	// that mix, so whichever slots are still on a default are being read from a
+	// header nothing sets.
+	if (defaults > 0) {
+		const stale = Object.entries(resolved)
+			.filter(([slot, name]) => name === DEFAULT_HEADER_NAMES[slot])
+			.map(([slot, name]) => `${slot}=${name}`)
+			.join(', ');
+		return yellow(
+			`header names mix oauth2-proxy and bundled-default names: ${list} — ` +
+				`${stale} will never arrive if your proxy forwards X-Auth-Request-* unchanged. ` +
+				`Either override all three with the X-Auth-Request-* names, or map them to SELVA-* ` +
+				`in the proxy and unset all three overrides.`
+		);
+	}
+
+	return green(`header names (oauth2-proxy pass-through): ${list}`);
+}
+
+// Below this, an annotated .env is just a slightly chatty config file; above it
+// the operator is scrolling past screens of prose that no command can correct.
+const COMMENT_LINE_BUDGET = 40;
+
+/**
+ * Flags a `.env` still carrying the shipped documentation block.
+ *
+ * The block is a snapshot of the release the deployment was installed at.
+ * `migrate` rewrites keys but never prose, so those comments keep describing
+ * vars the code has since renamed or retired — confidently wrong instructions
+ * sitting in the file an operator reaches for first. Nothing breaks, which is
+ * why this is yellow, and why it needs saying at all.
+ */
+export function checkEnvDocumentation(commentLines, fix) {
+	if (commentLines <= COMMENT_LINE_BUDGET) {
+		return green('.env is values-only');
+	}
+	return yellow(
+		`.env carries ~${commentLines} lines of shipped documentation. Comments are ` +
+			`never updated by \`selva migrate\`, so they still describe the release this ` +
+			`deployment was installed at — including variables the code no longer reads. ` +
+			`Strip them (values and your own inline notes are kept, .env.bak written):\n     ` +
+			`selva doctor --fix`,
+		fix
+	);
+}
+
 // A rename is auto-fixable (`selva migrate` rewrites the key). A replacement
 // encodes a value in the new name, so migrate leaves it alone rather than
 // guessing — it's reported here and nowhere else.

package/src/checks/runtime.js

@@ -112,7 +112,9 @@ function checkNodeProvenance(env) {
 		?.trim();
 
 	if (!onPath) {
-		return yellow(`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`);
+		return yellow(
+			`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`
+		);
 	}
 
 	if (env.realpath(onPath) === running) {

package/src/commands/create.js

@@ -15,7 +15,11 @@ import {
 	runtimeTemplatePath,
 	scaffoldVersion
 } from '../paths.js';
-import { buildDeploymentPackageJson } from '../deployment-package.js';
+import {
+	buildDeploymentPackageJson,
+	npmDistTagVersion,
+	resolveSelvaPins
+} from '../deployment-package.js';
 import { satisfiesNodeRange } from '../node-range.js';
 
 export async function runCreate(argv) {
@@ -57,9 +61,19 @@ export async function runCreate(argv) {
 
 	const deployName = basename(targetDir);
 
+	// Resolve the dist-tags to concrete versions before writing. A stored
+	// `"latest"` re-resolves on every later `npm install`, so the deployment
+	// would follow the tag instead of the version it was scaffolded against —
+	// and `selva doctor` reports a floating pin as drift.
+	const { pins } = resolveSelvaPins({}, npmDistTagVersion);
+
 	// package.json first: npm install needs it, and the runtime templates below
 	// only exist once @selvajs/selva is installed into node_modules.
-	const pkgJson = JSON.stringify(buildDeploymentPackageJson({ name: deployName }), null, 2);
+	const pkgJson = JSON.stringify(
+		buildDeploymentPackageJson({ name: deployName, dependencies: pins }),
+		null,
+		2
+	);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
 	if (!skipInstall) {

package/src/commands/doctor.js

@@ -8,6 +8,8 @@
 import {
 	existsSync,
 	readFileSync,
+	writeFileSync,
+	copyFileSync,
 	readdirSync,
 	accessSync,
 	constants,
@@ -18,7 +20,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile } from '../env.js';
+import { readEnvFile, parseEnv, countEnvCommentLines, stripEnvComments } from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
@@ -26,6 +28,8 @@ import { checkBootPersistence } from '../checks/boot.js';
 import { checkRuntimeEnvironment } from '../checks/runtime.js';
 import {
 	checkDeprecatedEnv,
+	checkEnvDocumentation,
+	checkHeaderNames,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
@@ -78,6 +82,7 @@ export async function runDoctor(argv = []) {
 	checks.push(...checkBootPersistence(dir));
 	checks.push(checkOrigin(env));
 	checks.push(...checkDeprecatedEnv(env));
+	checks.push(checkEnvDocs(dir));
 
 	// ── Render ─────────────────────────────────────────────────────────
 	const resolved = await Promise.all(checks);
@@ -372,6 +377,58 @@ function checkMigrationLeftovers(dir) {
 	);
 }
 
+// Reads the raw file rather than the parsed env: the finding IS the comments,
+// which parseEnv discards. The repair is attached here (not in checks/config.js)
+// to keep that module filesystem-free.
+function checkEnvDocs(dir) {
+	const envPath = join(dir, '.env');
+	if (!existsSync(envPath)) return green('.env documentation check skipped (no .env)');
+
+	let text;
+	try {
+		text = readFileSync(envPath, 'utf8');
+	} catch (err) {
+		return yellow(`.env unreadable (${err instanceof Error ? err.message : err})`);
+	}
+
+	return checkEnvDocumentation(
+		countEnvCommentLines(text),
+		fixable('strip the shipped documentation from .env (backup: .env.bak)', () => {
+			try {
+				// Re-read at repair time: doctor may have run minutes ago in --fix's
+				// confirmation loop, and rewriting from a stale snapshot would silently
+				// revert an edit made in between.
+				const current = readFileSync(envPath, 'utf8');
+				const { text: strippedText, removed } = stripEnvComments(current);
+				// A rewrite that changes which settings are live is a bug, not a
+				// cleanup — refuse rather than hand back a subtly different deployment.
+				const before = parseEnv(current);
+				const after = parseEnv(strippedText);
+				const drift = diffEnvKeys(before, after);
+				if (drift) return red(`refused to strip .env — ${drift}`);
+
+				copyFileSync(envPath, envPath + '.bak');
+				writeFileSync(envPath, strippedText, 'utf8');
+				return green(`stripped ${removed} comment lines from .env (backup: .env.bak)`);
+			} catch (err) {
+				return red(`could not rewrite .env: ${err instanceof Error ? err.message : err}`);
+			}
+		})
+	);
+}
+
+// Names the first discrepancy between two parsed envs, or null when identical.
+function diffEnvKeys(before, after) {
+	for (const key of Object.keys(before)) {
+		if (!(key in after)) return `${key} would be lost`;
+		if (before[key] !== after[key]) return `${key} would change value`;
+	}
+	for (const key of Object.keys(after)) {
+		if (!(key in before)) return `${key} would be added`;
+	}
+	return null;
+}
+
 function checkLayoutDrift(dir) {
 	const pkgPath = join(dir, 'package.json');
 	if (!existsSync(pkgPath)) return yellow('package.json missing — cannot check layout');
@@ -389,14 +446,6 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// Duplicated from HeaderAuthProvider.DEFAULT_HEADERS to avoid loading the runtime here.
-// A test in providers/header-auth pins both sides, so drift surfaces in CI.
-const DEFAULT_HEADER_NAMES = {
-	upn: 'SELVA-UserPrincipalName',
-	email: 'SELVA-Email',
-	displayName: 'SELVA-DisplayName'
-};
-
 // Static config only — runtime invariants like spoofing protection can't be checked from here.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
@@ -466,29 +515,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	const resolved = {
-		upn: env.HEADER_AUTH_UPN_HEADER || DEFAULT_HEADER_NAMES.upn,
-		email: env.HEADER_AUTH_EMAIL_HEADER || DEFAULT_HEADER_NAMES.email,
-		displayName: env.HEADER_AUTH_DISPLAY_NAME_HEADER || DEFAULT_HEADER_NAMES.displayName
-	};
-	const overrides = [
-		Boolean(env.HEADER_AUTH_UPN_HEADER),
-		Boolean(env.HEADER_AUTH_EMAIL_HEADER),
-		Boolean(env.HEADER_AUTH_DISPLAY_NAME_HEADER)
-	].filter(Boolean).length;
-	const headerList = `UPN=${resolved.upn}, Email=${resolved.email}, DisplayName=${resolved.displayName}`;
-	if (overrides === 0) {
-		out.push(green(`header names (bundled defaults): ${headerList}`));
-	} else if (overrides === 3) {
-		out.push(green(`header names (all overridden): ${headerList}`));
-	} else {
-		out.push(
-			yellow(
-				`header names partially overridden (${overrides}/3 set): ${headerList} — ` +
-					`a partial override is usually a typo. Set all three or none.`
-			)
-		);
-	}
+	out.push(checkHeaderNames(env));
 
 	return out;
 }

package/src/commands/init.js

@@ -42,7 +42,11 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	writeEnvFile(envPath, readEnvTemplate(dir), values);
+	// A values-only rewrite drops anything it isn't handed, and the prompts cover
+	// only the vars they ask about — every tuned knob the operator set by hand
+	// (BODY_SIZE_LIMIT, COMPUTE_*, LOG_LEVEL, …) lives outside that set. Carry
+	// the existing file forward and let the prompt answers win on top.
+	writeEnvFile(envPath, readEnvTemplate(dir), { ...current, ...values });
 
 	p.outro(
 		[

package/src/commands/migrate.js

@@ -13,8 +13,12 @@ import {
 	buildDeploymentPackageJson,
 	CANONICAL_FIELDS,
 	DEPENDENCIES,
+	isFloatingPin,
 	LEGACY_DEPENDENCIES,
-	OVERRIDES
+	npmDistTagVersion,
+	OVERRIDES,
+	resolveSelvaPins,
+	SELVA_PACKAGES
 } from '../deployment-package.js';
 import { APP_NAME, runPm2 } from './pm2.js';
 
@@ -34,7 +38,8 @@ export async function runMigrate(
 		// predates the release being migrated to.
 		install = (cwd) => execSync('npm install --prefer-online', { cwd, stdio: 'pipe' }),
 		confirm = (message) => p.confirm({ message, initialValue: true }),
-		pm2 = runPm2
+		pm2 = runPm2,
+		resolveVersion = npmDistTagVersion
 	} = {}
 ) {
 	const dir = injectedDir ?? resolveDeploymentDir();
@@ -49,7 +54,7 @@ export async function runMigrate(
 	}
 
 	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
-	const target = buildTargetPackageJson(before);
+	const { pkg: target, notes: pinNotes } = buildTargetPackageJson(before, resolveVersion);
 	const pkgDiff = diffPackageJson(before, target);
 
 	const configPath = join(dir, 'selva.config.js');
@@ -94,6 +99,23 @@ export async function runMigrate(
 	for (const line of pkgDiff) console.log('  ' + line);
 	for (const line of sideFileChanges) console.log('  ' + line);
 
+	// 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
+	// "no change" in the diff, and the second one is a stale pin, not a stable one.
+	for (const note of pinNotes) {
+		if (note.kind === 'prerelease') {
+			p.log.info(
+				`${note.name} stays on ${note.pin} — a prerelease pin is kept, since \`latest\` ` +
+					`means newest stable and would move this deployment backwards.`
+			);
+		} else {
+			p.log.warn(
+				`Could not resolve the current version of ${note.name} (${note.reason}). ` +
+					`Keeping ${JSON.stringify(note.pin ?? null)}; re-run migrate when the registry is reachable.`
+			);
+		}
+	}
+
 	const confirmed = await confirm('Apply these changes, reinstall, and restart?');
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
@@ -242,12 +264,15 @@ function restartAfterRollback(dir, pm2 = runPm2) {
 	}
 }
 
-function buildTargetPackageJson(current) {
-	return buildDeploymentPackageJson({
+function buildTargetPackageJson(current, resolveVersion = npmDistTagVersion) {
+	const { pins, notes } = resolveSelvaPins(current.dependencies, resolveVersion);
+	const pkg = buildDeploymentPackageJson({
 		name: current.name ?? 'selva-deployment',
 		version: current.version ?? '0.1.0',
-		engines: current.engines
+		engines: current.engines,
+		dependencies: pins
 	});
+	return { pkg, notes };
 }
 
 // Format package.json diff for confirmation prompt (concise, not full diff).
@@ -331,6 +356,20 @@ export function detectDrift(pkgJson, dir) {
 		reasons.push(`pm2 is pinned to ${deps.pm2} (current scaffold pins ${DEPENDENCIES.pm2})`);
 	}
 
+	// A stored dist-tag re-resolves on every `npm install`, so the deployment
+	// follows the tag instead of a version an operator chose. Worse on a
+	// prerelease line, where `latest` points at the older stable release and the
+	// "upgrade" is a downgrade. Migrate wrote these before it learned to resolve
+	// tags, so existing deployments carry one and nothing else reports it.
+	for (const name of SELVA_PACKAGES) {
+		if (deps[name] && isFloatingPin(deps[name])) {
+			reasons.push(
+				`${name} is pinned to the floating tag ${JSON.stringify(deps[name])} ` +
+					`(re-resolves on every install; migrate writes a concrete version)`
+			);
+		}
+	}
+
 	// Overrides are security shims for vulnerable transitive deps — a
 	// deployment without them installs the vulnerable version on its next
 	// `npm install`, silently.
@@ -370,8 +409,14 @@ export function buildPm2UpgradeNotice(beforeVersion, afterVersion) {
 		`still the old version. Finish the upgrade (brief restart of managed processes):`,
 		``,
 		`  npx pm2 update`,
+		`  npx pm2 list          # ${APP_NAME} must be listed and 'online' before the next step`,
 		`  npx pm2 save`,
 		``,
+		`Do not run \`pm2 save\` until the list looks right. \`pm2 update\` empties the`,
+		`process table before restoring it, so saving a failed restore overwrites`,
+		`~/.pm2/dump.pm2 — the only record of what to bring back. If the list is empty,`,
+		`recover with \`npx pm2 resurrect\`, or \`npx pm2 start ecosystem.config.cjs\`.`,
+		``,
 		`If doctor reports a pm2 outside this deployment (global or apt install), follow`,
 		`the full procedure in the docs instead: self-hosting → deployment → prerequisites.`
 	].join('\n');

package/src/deployment-package.js

@@ -4,6 +4,7 @@
 // exactly the field where a silent difference costs the most.
 
 import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -51,6 +52,11 @@ const SCRIPTS = {
  * Packages a deployment carries. Providers are bundled into `@selvajs/selva`;
  * the CLI is a dependency so `npm run start` resolves the `selva` bin locally
  * instead of relying on a global install.
+ *
+ * The `latest` entries are what `create` resolves at scaffold time, never what
+ * gets written: `resolveSelvaPins` turns them into concrete versions. A stored
+ * `"latest"` re-resolves on every `npm install`, so the deployment follows the
+ * dist-tag forever and can change under the operator with no migrate at all.
  */
 const DEPENDENCIES = {
 	'@selvajs/cli': 'latest',
@@ -58,6 +64,34 @@ const DEPENDENCIES = {
 	pm2: PM2_VERSION
 };
 
+/** The `@selvajs/*` packages whose pin belongs to the operator, not the scaffold. */
+export const SELVA_PACKAGES = ['@selvajs/cli', '@selvajs/selva'];
+
+/**
+ * True for a pin that names no version — a dist-tag (`latest`, `beta`) or the
+ * empty-ish values npm also accepts (`*`, `""`). These are the pins that move
+ * on their own, which is what makes them unfit to store.
+ */
+export function isFloatingPin(pin) {
+	if (typeof pin !== 'string') return true;
+	const trimmed = pin.trim();
+	if (trimmed === '' || trimmed === '*' || trimmed === 'x') return true;
+	// A range still names versions; only a bare tag has no digits at all.
+	return !/\d/.test(trimmed);
+}
+
+/**
+ * True for a pin on a prerelease line (`^4.8.0-beta.11`).
+ *
+ * These are preserved across a migration. An operator on a beta channel chose
+ * it, and npm's `latest` tag points at the newest *stable* release — so
+ * resolving their pin through `latest` is a downgrade that reads as an upgrade
+ * in the confirmation diff.
+ */
+export function isPrereleasePin(pin) {
+	return typeof pin === 'string' && /\d+\.\d+\.\d+-/.test(pin);
+}
+
 /**
  * npm `overrides` forced onto every deployment — security patches for
  * transitive deps whose direct parent hasn't picked up the fix yet. Each entry
@@ -100,21 +134,98 @@ export const LEGACY_DEPENDENCIES = {
  * deliberately, and dropping it removes a guard whose absence shows up only
  * under real traffic (issue #176). Everything else a migration discards is
  * listed by `diffPackageJson` before the operator confirms.
+ *
+ * `dependencies` is the second exception, for the same reason: a version pin is
+ * an operator choice too. `migrate` passes the resolved `@selvajs/*` pins in
+ * here; a fresh scaffold passes none and inherits the defaults.
  */
-export function buildDeploymentPackageJson({ name, version = '0.1.0', engines }) {
+export function buildDeploymentPackageJson({ name, version = '0.1.0', engines, dependencies }) {
 	const pkg = {
 		name: sanitizePackageName(name),
 		version,
 		private: true,
 		type: 'module',
 		scripts: { ...SCRIPTS },
-		dependencies: { ...DEPENDENCIES },
+		dependencies: { ...DEPENDENCIES, ...dependencies },
 		overrides: { ...OVERRIDES }
 	};
 	if (engines && typeof engines === 'object') pkg.engines = { ...engines };
 	return pkg;
 }
 
+/**
+ * Ask npm what a dist-tag currently points at. Kept beside the pin logic it
+ * serves, and injected rather than called directly so tests never hit the
+ * network.
+ */
+export function npmDistTagVersion(name, tag) {
+	const out = execSync(`npm view ${name}@${tag} version`, {
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe']
+	});
+	const version = String(out).trim().split('\n').pop()?.trim();
+	if (!version || !/^\d+\.\d+\.\d+/.test(version)) {
+		throw new Error(`npm view returned no usable version for ${name}@${tag}`);
+	}
+	return version;
+}
+
+/**
+ * Decide the `@selvajs/*` pins a migration should write.
+ *
+ * Two rules, both aimed at the same failure: a migration silently moving a
+ * deployment to a version the operator didn't ask for.
+ *
+ *   - A prerelease pin is kept as-is. `latest` means newest stable, so
+ *     resolving a beta pin through it walks the deployment backwards.
+ *   - Anything else resolves to a concrete version via `resolveVersion`, so
+ *     `"latest"` never reaches disk and the diff can show what it resolved to.
+ *
+ * `resolveVersion` hits the network. When it fails — offline, registry down, a
+ * package with no such tag — the existing pin is kept and the reason returned,
+ * so migrate can report it rather than inventing a version or aborting a
+ * migration whose other half (layout, overrides, env renames) is still valid.
+ */
+export function resolveSelvaPins(currentDeps, resolveVersion) {
+	const pins = {};
+	const notes = [];
+
+	for (const name of SELVA_PACKAGES) {
+		const current = currentDeps?.[name];
+
+		if (isPrereleasePin(current)) {
+			pins[name] = current;
+			notes.push({ name, kind: 'prerelease', pin: current });
+			continue;
+		}
+
+		let resolved = null;
+		try {
+			resolved = resolveVersion(name, 'latest');
+		} catch (err) {
+			notes.push({ name, kind: 'unresolved', pin: current, reason: err?.message ?? String(err) });
+		}
+
+		if (resolved) {
+			pins[name] = `^${resolved}`;
+			continue;
+		}
+
+		// Nothing resolvable and nothing worth keeping — fall back to the tag so
+		// the install still succeeds. Rare: offline *and* a floating pin.
+		if (isFloatingPin(current)) {
+			pins[name] = DEPENDENCIES[name];
+			if (!notes.some((n) => n.name === name)) {
+				notes.push({ name, kind: 'unresolved', pin: current, reason: 'no version returned' });
+			}
+		} else {
+			pins[name] = current;
+		}
+	}
+
+	return { pins, notes };
+}
+
 /**
  * Top-level keys the canonical package.json defines. Anything outside this set
  * that an operator added is dropped by `migrate` — `diffPackageJson` reports

package/src/env.js

@@ -19,6 +19,142 @@ export const REPLACED_ENV_VARS = {
 	SELVA_FLAG_COMPUTE_DEBUG_VERBOSE: 'SELVA_FLAG_COMPUTE_DEBUG=verbose'
 };
 
+// Header written above the settings in a stripped .env. The pointer matters:
+// without it the operator has no way back to what a var means, and the reflex
+// is to paste the old annotated template back in.
+export const ENV_HEADER = [
+	'# Selva deployment configuration.',
+	'#',
+	'# Values only — every variable is documented in the runtime template at',
+	'# node_modules/@selvajs/selva/templates/.env.example, which is refreshed on',
+	'# every update. Do not paste that template in here: a copy stops tracking',
+	'# the release and starts describing variables the code no longer reads.'
+].join('\n');
+
+/**
+ * Strip a deployment `.env` down to its live settings, dropping the shipped
+ * documentation block.
+ *
+ * A comment block copied onto a server is a snapshot with no update path —
+ * `migrate` rewrites keys but never prose, so a deployment keeps documenting
+ * the release it was installed at, describing vars the code has since renamed
+ * or retired. Deleting it is what makes the file navigable AND unable to lie.
+ *
+ * Operator comments are NOT prose to be discarded: a short `#` run directly
+ * above a setting (no blank line between) is that setting's note and rides
+ * along with it. Everything else goes.
+ *
+ * "Short" is doing real work here. The shipped template also writes prose
+ * immediately above a setting — its banner blocks run 40+ lines and end with a
+ * bare `#` — so proximity alone would keep the very documentation this exists
+ * to remove. A hand-written note is a line or two; a block longer than
+ * ATTACHED_NOTE_MAX_LINES, or one containing a `# ====` banner rule, is the
+ * template's and is dropped.
+ *
+ * Returns `{ text, removed }`, `removed` being the count of dropped comment
+ * lines. `removed === 0` means the file was already values-only.
+ */
+export function stripEnvComments(text, { header = ENV_HEADER } = {}) {
+	// Our own header is re-emitted below, so counting it as prose we removed
+	// would make every run report work it didn't do — and break idempotency,
+	// which is what lets doctor call a stripped file clean. Matched as a whole
+	// leading block, not line-by-line: the header contains a bare `#`, and
+	// excluding that by value would silently stop counting an operator's own
+	// `#` separators anywhere in the file.
+	let lines = text.split(/\r?\n/);
+	if (header) {
+		const headerLines = header.split('\n');
+		const leads = headerLines.every((h, i) => lines[i]?.trim() === h.trim());
+		if (leads) lines = lines.slice(headerLines.length);
+	}
+	const out = [];
+	let pending = [];
+	let removed = 0;
+	let sawSetting = false;
+	// Whether a blank line or dropped prose separated the last setting from the
+	// next one — the original file's own grouping, worth carrying over.
+	let groupBreak = false;
+
+	const flushDropped = () => {
+		const dropped = pending.filter((l) => l.trim().startsWith('#'));
+		removed += dropped.length;
+		// A discarded banner marked a section boundary in the original; keep that
+		// boundary as a blank line so the result still reads as grouped settings.
+		if (dropped.length > 0 && sawSetting) groupBreak = true;
+		pending = [];
+	};
+
+	for (const line of lines) {
+		const stripped = line.trim();
+
+		if (stripped.startsWith('#')) {
+			pending.push(line);
+			continue;
+		}
+
+		// A blank line ends whatever comment block was accumulating: those
+		// comments float free rather than annotating the next setting.
+		if (!stripped) {
+			if (sawSetting) groupBreak = true;
+			flushDropped();
+			continue;
+		}
+
+		if (stripped.indexOf('=') === -1) {
+			flushDropped();
+			continue;
+		}
+
+		// Comments still pending sit directly above this setting. Keep them only
+		// if they read as a hand-written note rather than a template banner.
+		const note = isAttachedNote(pending);
+		// Blank line only where it earns one: before a kept note, or where the
+		// original had a break. Separating every key would just trade a wall of
+		// prose for a file twice as long as it needs to be.
+		if (sawSetting && (note || groupBreak)) out.push('');
+		if (note) {
+			out.push(...pending);
+		} else {
+			flushDropped();
+		}
+		pending = [];
+		groupBreak = false;
+		out.push(line);
+		sawSetting = true;
+	}
+
+	// Trailing comments annotate nothing.
+	flushDropped();
+
+	const body = out.join('\n');
+	return {
+		text: header ? `${header}\n\n${body}\n` : `${body}\n`,
+		removed
+	};
+}
+
+// A hand-written note is a line or two. Longer than this and it is the shipped
+// template's prose, which is what stripping exists to remove.
+const ATTACHED_NOTE_MAX_LINES = 3;
+
+// A `# ====` rule is the template's section-banner style; nothing hand-written
+// above a single setting uses it.
+const BANNER_RULE = /^#\s*[=-]{4,}/;
+
+function isAttachedNote(pending) {
+	if (pending.length === 0 || pending.length > ATTACHED_NOTE_MAX_LINES) return false;
+	return !pending.some((l) => BANNER_RULE.test(l.trim()));
+}
+
+/**
+ * How many lines of the file are shipped documentation rather than config.
+ * Used by `selva doctor` to flag an annotated `.env` without rewriting it.
+ */
+export function countEnvCommentLines(text) {
+	const { removed } = stripEnvComments(text);
+	return removed;
+}
+
 export function parseEnv(text) {
 	const out = {};
 	for (const rawLine of text.split(/\r?\n/)) {
@@ -88,8 +224,55 @@ export function mergeEnv(template, values) {
 	return out.join('\n') + '\n';
 }
 
-export function writeEnvFile(path, template, values) {
-	writeFileSync(path, mergeEnv(template, values), 'utf8');
+/**
+ * Render a values-only `.env` — the scaffold's default shape.
+ *
+ * The annotated template is genuinely useful while you are deciding what to
+ * set, which is why the runtime still ships it; it stops being useful the
+ * moment it is written to a server and cannot be corrected there. So the
+ * template stays a reference and the deployment gets values, in the template's
+ * own key order (it groups related settings) with anything unknown appended.
+ */
+export function renderEnvValues(template, values, { header = ENV_HEADER } = {}) {
+	const ordered = [];
+	const seen = new Set();
+
+	// The template names a var three ways — live (`KEY=v`), commented-out
+	// (`# KEY=v`), and as a bare mention in prose (`# KEY   single | multi`).
+	// All three signal where the var belongs, so the first token of any line is
+	// enough; anything that isn't a known key is filtered out below.
+	for (const rawLine of template.split(/\r?\n/)) {
+		const stripped = rawLine.trim().replace(/^#\s*/, '');
+		const key = stripped.split(/[\s=]/)[0]?.trim();
+		if (!key || !/^[A-Z][A-Z0-9_]{2,}$/.test(key)) continue;
+		if (seen.has(key)) continue;
+		if (!Object.prototype.hasOwnProperty.call(values, key)) continue;
+		seen.add(key);
+		ordered.push(key);
+	}
+
+	for (const key of Object.keys(values)) {
+		if (!seen.has(key)) ordered.push(key);
+	}
+
+	const lines = [];
+	for (const key of ordered) {
+		const value = values[key];
+		if (value === undefined || value === null || value === '') continue;
+		lines.push(`${key}=${quoteIfNeeded(value)}`);
+	}
+
+	return header ? `${header}\n\n${lines.join('\n')}\n` : `${lines.join('\n')}\n`;
+}
+
+/**
+ * Writes the deployment `.env`. Values-only by default — pass
+ * `{ annotated: true }` to merge into the template's comments instead, which
+ * only an operator who explicitly wants the old shape should do.
+ */
+export function writeEnvFile(path, template, values, { annotated = false } = {}) {
+	const text = annotated ? mergeEnv(template, values) : renderEnvValues(template, values);
+	writeFileSync(path, text, 'utf8');
 }
 
 /**