@selvajs/cli 4.8.0-beta.9 → 4.8.0

package/src/cli.js

@@ -18,6 +18,59 @@ const COMMANDS = {
 	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
 };
 
+// `selva doctor --help` used to run the full doctor: commands own their argv,
+// and only `doctor` reads a flag at all, so every other command silently
+// ignored `--help` and did its work. Intercepting here keeps `--help` uniform
+// across the whole surface without each command re-implementing it.
+const USAGE = {
+	init: {
+		usage: 'selva init',
+		blurb:
+			'Reconfigure this deployment. Prompts for the same values as scaffolding\nand rewrites .env; generated secrets are left alone.'
+	},
+	doctor: {
+		usage: 'selva doctor [--fix]',
+		blurb:
+			'Validate .env, providers, Node engine, pm2 boot persistence, and package\npins. Read-only without --fix.',
+		flags: [['--fix', 'Apply the repairs doctor reports as automatic. Prompts before each.']]
+	},
+	start: { usage: 'selva start', blurb: 'pm2 start ecosystem.config.cjs' },
+	stop: { usage: 'selva stop', blurb: 'pm2 stop selva-compute' },
+	restart: {
+		usage: 'selva restart',
+		blurb:
+			'pm2 restart selva-compute --update-env. The --update-env is why this\nexists: without it a pm2 restart keeps the old .env in memory.'
+	},
+	logs: { usage: 'selva logs', blurb: 'pm2 logs selva-compute' },
+	update: {
+		usage: 'selva update',
+		blurb:
+			'npm update @selvajs/cli + @selvajs/selva, then restart. Rolls the\ndependency tree back if the install fails.'
+	},
+	migrate: {
+		usage: 'selva migrate',
+		blurb:
+			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
+	},
+	keys: {
+		usage: 'selva keys rotate <hmac|at-rest>',
+		blurb:
+			'Rotate one secret in .env. Destructive and not reversible — the command\nspells out the blast radius and asks before writing.'
+	}
+};
+
+function printCommandHelp(command) {
+	const entry = USAGE[command];
+	const lines = [pc.bold(entry.usage), '', entry.blurb];
+	if (entry.flags) {
+		lines.push('', pc.bold('Flags:'));
+		for (const [flag, description] of entry.flags) {
+			lines.push(`  ${flag.padEnd(22)}${description}`);
+		}
+	}
+	console.log(lines.join('\n'));
+}
+
 function keysDispatch(m) {
 	return async (argv) => {
 		const sub = argv[0];
@@ -51,6 +104,11 @@ export async function runSelva(argv) {
 		process.exit(1);
 	}
 
+	if (rest.includes('--help') || rest.includes('-h')) {
+		printCommandHelp(command);
+		return;
+	}
+
 	const run = await loader();
 	await run(rest);
 }
@@ -60,6 +118,8 @@ function printHelp() {
 		[
 			pc.bold('selva') + ' — operate a Selva deployment',
 			'',
+			pc.bold('Usage:') + '  npx selva <command>',
+			'',
 			pc.bold('Commands:'),
 			'  init                    Reconfigure this deployment (prompts again)',
 			'  doctor [--fix]          Validate env, providers, Node engine, and packages',
@@ -67,11 +127,19 @@ function printHelp() {
 			'  stop                    pm2 stop selva-compute',
 			'  restart                 pm2 restart selva-compute --update-env',
 			'  logs                    pm2 logs selva-compute',
-			'  update                  npm update @selvajs/selva + restart',
+			'  update                  npm update @selvajs/cli + @selvajs/selva, then restart',
 			'  migrate                 Bring package.json onto the current layout',
 			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
 			'',
-			pc.dim('To scaffold a new deployment: ') + pc.cyan('npx @selvajs/cli <dir>')
+			pc.dim('`npx selva <command> --help` explains one command.'),
+			'',
+			pc.bold('Two commands, two jobs:'),
+			'  ' + pc.cyan('npx @selvajs/cli <dir>') + '   scaffold a NEW deployment into <dir>',
+			'  ' + pc.cyan('npx selva <command>') + '      operate the deployment you are standing in',
+			'',
+			pc.dim('`npx selva` works in a deployment directory because @selvajs/cli is one of'),
+			pc.dim('its dependencies. The package.json scripts (`npm run doctor`, `npm start`)'),
+			pc.dim('are thin aliases for the same commands.')
 		].join('\n')
 	);
 }

package/src/commands/create.js

@@ -1,6 +1,5 @@
-// 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.
+// Scaffolds a fresh deployment: package.json, node_modules, .env (merged from
+// template + prompts), and ecosystem.config.cjs.
 
 import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
 import { resolve, join, basename, dirname } from 'node:path';
@@ -16,18 +15,20 @@ 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) {
 	const { dir: rawDir, force, skipInstall, yes } = parseArgs(argv);
 
-	// Scaffolding under too old a Node produces a deployment that installs
-	// cleanly and passes its health check, then fails only under real traffic —
-	// npm treats an engine mismatch as a warning unless engine-strict is set,
-	// which no deployment sets (issue #176). Refuse at the one moment the
-	// operator is still choosing their environment. The floor comes from this
-	// CLI's own engines.node, so a bump can't leave a stale copy behind.
+	// Scaffolding under too old a Node installs and passes the health check,
+	// then fails only under real traffic — npm treats an engine mismatch as a
+	// warning, not an error, unless engine-strict is set, which no deployment
+	// sets. Refuse now, while the operator is still choosing their environment.
 	const required = requiredNodeRange();
 	if (required && satisfiesNodeRange(process.versions.node, required) === false) {
 		console.error(
@@ -50,20 +51,29 @@ export async function runCreate(argv) {
 	}
 	mkdirSync(targetDir, { recursive: true });
 
-	// --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' });
 
-	// 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);
 
-	// Write package.json, then install (need templates from @selvajs/selva).
-	const pkgJson = JSON.stringify(buildDeploymentPackageJson({ name: deployName }), null, 2);
+	// 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, dependencies: pins }),
+		null,
+		2
+	);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
 	if (!skipInstall) {
@@ -74,7 +84,6 @@ export async function runCreate(argv) {
 		);
 	}
 
-	// Copy templates from installed runtime.
 	const envTemplatePath = runtimeTemplatePath(targetDir, '.env.example');
 	const ecosystemTemplatePath = runtimeTemplatePath(targetDir, 'ecosystem.config.cjs');
 	if (skipInstall || !existsSync(envTemplatePath)) {
@@ -110,21 +119,17 @@ export async function runCreate(argv) {
 	);
 }
 
-// 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)');
 
-		// Keep last 80 lines for failure output.
 		const tail = [];
 		const remember = (line) => {
 			tail.push(line);
 			if (tail.length > 80) tail.shift();
 		};
 
-		// Extract progress milestones (reify: lines, package count).
 		const updateProgress = (line) => {
 			const trimmed = line.trim();
 			if (!trimmed) return;
@@ -140,7 +145,7 @@ function runNpmInstall(cwd) {
 			if (/^npm (WARN|error|notice)/.test(trimmed)) return;
 		};
 
-		// Spawn with --loglevel=info for reify: progress; pipe stdout/stderr for live updates.
+		// --loglevel=info is what makes npm print the reify: lines updateProgress matches on.
 		const child = spawn('npm', ['install', '--loglevel=info'], {
 			cwd,
 			stdio: ['ignore', 'pipe', 'pipe'],
@@ -184,8 +189,8 @@ function runNpmInstall(cwd) {
 			}
 			s.stop(pc.red(`npm install failed (exit ${code})`));
 
-			// Show what npm actually said. Without this the operator has to
-			// dig through ~/.npm/_logs/*-debug-0.log to find a single line.
+			// Without this the operator has to dig through ~/.npm/_logs/*-debug-0.log
+			// to find out what actually went wrong.
 			console.error('');
 			console.error(pc.dim('── last lines of npm output ──'));
 			for (const line of tail) console.error(line);
@@ -210,11 +215,37 @@ function runNpmInstall(cwd) {
 	});
 }
 
+// `npx @selvajs/cli` resolves to the `cli` bin — the scaffolder — while every
+// operate command lives on the sibling `selva` bin. So `npx @selvajs/cli doctor
+// --fix` lands here, where "doctor" is just a directory name and `--fix` an
+// unknown flag. Name the bin split rather than letting the operator conclude
+// their CLI is too old for a flag it has shipped for releases.
+const OPERATE_COMMANDS = new Set([
+	'doctor',
+	'start',
+	'stop',
+	'restart',
+	'logs',
+	'update',
+	'migrate',
+	'keys',
+	'init'
+]);
+
 function parseArgs(argv) {
 	let dir;
 	let force = false;
 	let skipInstall = false;
 	let yes = false;
+
+	if (OPERATE_COMMANDS.has(argv[0])) {
+		throw new Error(
+			`\`${argv[0]}\` is an operate command, but \`npx @selvajs/cli\` runs the scaffolder.\n` +
+				`  Run it through the deployment's own CLI instead:\n` +
+				`    npx selva ${argv.join(' ')}`
+		);
+	}
+
 	for (const arg of argv) {
 		if (arg === '--force') force = true;
 		else if (arg === '--skip-install') skipInstall = true;

package/src/commands/doctor.js

@@ -2,12 +2,14 @@
 // Node engine, boot persistence. Yellow warnings don't fail, red failures exit 1.
 //
 // Read-only by default. `--fix` applies the repairs attached to individual
-// checks, each behind its own confirmation — and only those needing no root and
-// no runtime restart. See `applyFixes`.
+// checks, each behind its own confirmation — only fixes needing no root and
+// no runtime restart exist. See applyFixes.
 
 import {
 	existsSync,
 	readFileSync,
+	writeFileSync,
+	copyFileSync,
 	readdirSync,
 	accessSync,
 	constants,
@@ -18,20 +20,23 @@ 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';
 import { checkBootPersistence } from '../checks/boot.js';
+import { checkRuntimeEnvironment } from '../checks/runtime.js';
 import {
 	checkDeprecatedEnv,
+	checkEnvDocumentation,
+	checkHeaderNames,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
 	checkTenancy,
 	resolveProviders
 } from '../checks/config.js';
-import { detectDrift, NODE_MODULES_STASH } from './migrate.js';
+import { BACKUP_AGE_DAYS, classifyBackups, detectDrift, NODE_MODULES_STASH } from './migrate.js';
 
 export async function runDoctor(argv = []) {
 	const fix = argv.includes('--fix');
@@ -47,6 +52,7 @@ export async function runDoctor(argv = []) {
 	checks.push(checkFile(join(dir, 'ecosystem.config.cjs'), 'ecosystem.config.cjs present'));
 	checks.push(checkLayoutDrift(dir));
 	checks.push(checkMigrationLeftovers(dir));
+	checks.push(checkAgedBackups(dir));
 	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'));
 
@@ -73,9 +79,11 @@ export async function runDoctor(argv = []) {
 	checks.push(checkPackage(dir, '@selvajs/selva'));
 	checks.push(checkNodeEngine(dir));
 	checks.push(checkCliRuntimeAlignment(dir));
+	checks.push(...checkRuntimeEnvironment(dir));
 	checks.push(...checkBootPersistence(dir));
 	checks.push(checkOrigin(env));
 	checks.push(...checkDeprecatedEnv(env));
+	checks.push(checkEnvDocs(dir));
 
 	// ── Render ─────────────────────────────────────────────────────────
 	const resolved = await Promise.all(checks);
@@ -92,7 +100,7 @@ export async function runDoctor(argv = []) {
 		if (repairable > 0) {
 			p.log.info(
 				`${repairable} issue${repairable === 1 ? '' : 's'} can be repaired automatically — ` +
-					`re-run with \`selva doctor --fix\`.`
+					`re-run with \`npx selva doctor --fix\`.`
 			);
 		}
 	}
@@ -105,15 +113,9 @@ export async function runDoctor(argv = []) {
 	}
 }
 
-/**
- * Apply the repairs attached to failing checks, each behind its own
- * confirmation. Returns the updated failure count.
- *
- * Nothing here needs root: anything privileged (the systemd unit) or that would
- * restart this process (a Node upgrade) stays a printed instruction, because a
- * fixer that dies halfway through its own runtime leaves the operator with no
- * obvious path back.
- */
+// Anything privileged (the systemd unit) or that would restart this process
+// (a Node upgrade) stays a printed instruction instead of a fixer — one that
+// dies halfway through its own runtime leaves the operator with no way back.
 async function applyFixes(resolved, failures) {
 	const repairs = resolved.filter((c) => c.fix && c.severity !== 'green');
 	if (repairs.length === 0) {
@@ -183,8 +185,7 @@ async function checkSupabase(env) {
 		return red(`SUPABASE_URL="${env.SUPABASE_URL}" is not a valid URL`);
 	}
 
-	// Ping the Supabase health endpoint. Soft-fail to yellow on network
-	// errors — operators may be offline at install time.
+	// Network errors go yellow, not red — operators may be offline at install time.
 	try {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), 4000);
@@ -199,11 +200,10 @@ async function checkSupabase(env) {
 	}
 }
 
-// App↔DB schema handshake (audit O3). Expected head = newest migration shipped
-// by the installed @selvajs/supabase-provider; actual = what the database
-// reports via the selva.migration_head() RPC. Red on skew — the app degrades
-// /api/health to 503 at boot in the same state, so catching it here saves a
-// confusing deploy.
+// Compares the newest migration shipped by @selvajs/supabase-provider against
+// what the database reports via selva.migration_head(). Red on skew — the app
+// degrades /api/health to 503 at boot in the same state, so catching it here
+// saves a confusing deploy.
 async function checkSupabaseMigrations(dir, env) {
 	if (!env.SUPABASE_URL || !env.SUPABASE_SERVICE_ROLE_KEY) {
 		return yellow('Migration-head check skipped — Supabase env incomplete');
@@ -264,6 +264,7 @@ async function checkSupabaseMigrations(dir, env) {
 				`Database reports no applied migrations (expected head ${expected}). Sync + run: npx supabase db push`
 			);
 		}
+		// String comparison — relies on both heads being fixed-width, zero-padded timestamps.
 		if (actual < expected) {
 			return red(
 				`Database migration head ${actual} is behind the installed provider (${expected}). Sync + run: npx supabase db push`
@@ -271,7 +272,6 @@ async function checkSupabaseMigrations(dir, env) {
 		}
 		return green(`Database migration head ${actual} matches the installed provider`);
 	} catch (err) {
-		// Soft-fail on network errors, same as checkSupabase.
 		return yellow(`Migration-head check skipped (${err.message ?? err})`);
 	}
 }
@@ -295,7 +295,7 @@ function majorOf(version) {
 	return m ? Number(m[1]) : null;
 }
 
-// CLI and runtime release together (fixed group); major skew = stale CLI pin.
+// CLI and runtime release as a fixed group; major-version skew means a stale CLI pin.
 function checkCliRuntimeAlignment(dir) {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const cliVersion = readPackageVersion(join(here, '..', '..', 'package.json'));
@@ -303,7 +303,7 @@ function checkCliRuntimeAlignment(dir) {
 		join(dir, 'node_modules', '@selvajs', 'selva', 'package.json')
 	);
 
-	// Runtime missing is already reported red by checkPackage; stay quiet here.
+	// checkPackage already reports missing runtime as red; stay quiet here.
 	if (!runtimeVersion) return yellow('CLI/runtime version check skipped (runtime not installed)');
 	if (!cliVersion) return yellow('CLI/runtime version check skipped (could not read CLI version)');
 
@@ -324,16 +324,10 @@ function checkCliRuntimeAlignment(dir) {
 	);
 }
 
-// Verify VM reboot will resurrect app: dump.pm2 saved, systemd unit installed, no stray global pm2.
-/**
- * Does this host's Node satisfy the installed runtime's `engines.node`?
- *
- * npm only enforces engines under `engine-strict=true`, which no deployment
- * sets, so a mismatched install succeeds silently and `/api/health` still
- * returns 200 — routes using newer APIs throw only under real traffic
- * (issue #176). Deliberately NOT auto-fixable: upgrading Node is
- * distro-specific and would restart the process running this check.
- */
+// npm only enforces engines.node under engine-strict=true, which no deployment
+// sets, so a mismatched install succeeds silently and /api/health still returns
+// 200 — routes using newer APIs throw only under real traffic. Not auto-fixable:
+// upgrading Node is distro-specific and would restart the process running this check.
 function checkNodeEngine(dir) {
 	let required;
 	try {
@@ -363,12 +357,10 @@ function checkNodeEngine(dir) {
 	);
 }
 
-/**
- * `selva migrate` parks the old node_modules aside so a failed install can be
- * rolled back, and removes it on either outcome. One surviving here means the
- * migration was killed mid-flight — worth saying, because it is a full copy of
- * the dependency tree and the deployment may be running on the wrong one.
- */
+// `selva migrate` parks the old node_modules aside so a failed install can be
+// rolled back, and removes it on either outcome. One surviving here means the
+// migration was killed mid-flight — worth flagging since it's a full copy of
+// the dependency tree and the deployment may be running on the wrong one.
 function checkMigrationLeftovers(dir) {
 	const stash = join(dir, NODE_MODULES_STASH);
 	if (!existsSync(stash)) return green('no interrupted migration left behind');
@@ -386,6 +378,94 @@ function checkMigrationLeftovers(dir) {
 	);
 }
 
+// Migration backups are timestamped so a later migration can't overwrite an
+// earlier one's (#184), which means they accumulate. Deleting them silently
+// would throw away the operator's only copy of a pre-migration config, so this
+// reports and lets `--fix` opt in. `classifyBackups` always keeps the newest
+// run, so the escape hatch is never emptied — only superseded generations go.
+function checkAgedBackups(dir) {
+	let names;
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return green('no aged migration backups');
+	}
+
+	const { aged } = classifyBackups(names);
+	if (aged.length === 0) return green('no aged migration backups');
+
+	const shown = aged.slice(0, 3).join(', ');
+	const more = aged.length > 3 ? `, +${aged.length - 3} more` : '';
+	return yellow(
+		`${aged.length} migration backup${aged.length === 1 ? '' : 's'} older than ` +
+			`${BACKUP_AGE_DAYS} days (${shown}${more}). The newest set is kept either way.`,
+		fixable(`delete ${aged.length} aged migration backup${aged.length === 1 ? '' : 's'}`, () => {
+			const failed = [];
+			for (const name of aged) {
+				try {
+					rmSync(join(dir, name), { force: true });
+				} catch (err) {
+					failed.push(`${name} (${err instanceof Error ? err.message : err})`);
+				}
+			}
+			if (failed.length > 0) return red(`could not remove: ${failed.join(', ')}`);
+			return green(`removed ${aged.length} aged backup${aged.length === 1 ? '' : 's'}`);
+		})
+	);
+}
+
+// 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');
@@ -403,19 +483,10 @@ function checkLayoutDrift(dir) {
 	);
 }
 
-// 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 checks (read-only; runtime invariants like spoofing can't be verified).
+// Static config only — runtime invariants like spoofing protection can't be checked from here.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
 
-	// 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'));
@@ -425,21 +496,21 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		if (existsSync(allowlistPath)) {
 			out.push(green(`header-allowlist.json present (${allowlistDir}/header-allowlist.json)`));
 		} else {
-			// Provider creates lazily, but missing file locks everyone out.
+			// The provider creates this file lazily, but a missing file locks everyone out
+			// until one exists — worth a warning even though nothing is technically broken.
 			out.push(
 				yellow(
 					`header-allowlist.json not found at ${allowlistDir}/ — no users will be allowed in until one is added`
 				)
 			);
 
-			// Check writability only if explicitly set (DATA_PATH checked separately).
+			// DATA_PATH's own writability is checked separately (checkDataPath).
 			if (env.HEADER_AUTH_DATA_DIR) {
 				out.push(checkDirWritable(allowlistAbsDir, `HEADER_AUTH_DATA_DIR=${allowlistDir}`));
 			}
 		}
 	}
 
-	// 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)`));
@@ -452,12 +523,11 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 3. ORIGIN — header-auth implies a reverse proxy, so ORIGIN is required.
+	// header-auth always sits behind a reverse proxy, so ORIGIN is required.
 	if (!env.ORIGIN) {
 		out.push(red('ORIGIN unset — required for header-auth (always behind a proxy)'));
 	}
 
-	// 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(
@@ -467,10 +537,10 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		);
 	}
 
-	// 5. Bootstrap admin email. Without it, the first proxy-authenticated
-	// visitor's UPN is rejected (not in allowlist) and the operator has to
-	// hand-write JSON to claim admin. With it, the first matching visit is
-	// auto-allowlisted and granted instance_admin in one step.
+	// Without this, the first proxy-authenticated visitor's UPN is rejected
+	// (not in the allowlist) and the operator has to hand-write JSON to claim
+	// admin. With it, the first matching visit auto-allowlists and grants
+	// instance_admin in one step.
 	if (!env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL) {
 		out.push(
 			red(
@@ -482,30 +552,7 @@ function checkHeaderAuth(dir, env, dataProvider) {
 		out.push(green(`BOOTSTRAP_INSTANCE_ADMIN_EMAIL=${env.BOOTSTRAP_INSTANCE_ADMIN_EMAIL}`));
 	}
 
-	// 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,
-		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;
 }