@selvajs/cli 2.0.0 → 2.0.2

package/README.md

@@ -8,7 +8,7 @@ CLI for white-label Selva deployments.
 npx @selvajs/cli my-deployment
 ```
 
-Interactive scaffolder. Prompts for provider, tenancy, flags, brand name, admin email. Generates `SELVA_HMAC_KEY` + `SELVA_AT_REST_KEY`. Writes `.env`, `selva.config.js`, `ecosystem.config.cjs`, `package.json`. Runs `npm install`.
+Interactive scaffolder. Prompts for provider, tenancy, flags, brand name, admin email. Generates `SELVA_HMAC_KEY` + `SELVA_AT_REST_KEY`. Writes `.env`, `ecosystem.config.cjs`, `package.json`. Runs `npm install`.
 
 ## Operate an existing deployment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "publishConfig": {
@@ -8,7 +8,7 @@
   },
   "type": "module",
   "bin": {
-    "create": "./bin/create.js",
+    "cli": "./bin/cli.js",
     "selva": "./bin/selva.js"
   },
   "files": [
@@ -23,8 +23,8 @@
     "picocolors": "^1.1.1"
   },
   "scripts": {
-    "start": "node ./bin/create.js",
+    "start": "node ./bin/cli.js",
     "selva": "node ./bin/selva.js",
-    "test": "node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/keys.js']) { await import(m); }\""
+    "test": "node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js']) { await import(m); }\""
   }
 }

package/src/cli.js

@@ -14,6 +14,7 @@ const COMMANDS = {
 	restart: () => import('./commands/pm2.js').then((m) => m.runRestart),
 	logs: () => import('./commands/pm2.js').then((m) => m.runLogs),
 	update: () => import('./commands/pm2.js').then((m) => m.runUpdate),
+	migrate: () => import('./commands/migrate.js').then((m) => m.runMigrate),
 	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
 };
 
@@ -70,6 +71,7 @@ function printHelp() {
 			'  restart                 pm2 restart selva-compute --update-env',
 			'  logs                    pm2 logs selva-compute',
 			'  update                  npm update @selvajs/selva + 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>')

package/src/commands/create.js

@@ -2,15 +2,15 @@
 //
 // What this writes into <dir>:
 //   .env                    merged from runtime's .env.example + prompt values
-//   selva.config.js         copied from runtime's templates (operator can edit)
-//   ecosystem.config.cjs    copied verbatim
-//   package.json            depends on @selvajs/selva + providers
+//   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/.
+// from node_modules/@selvajs/selva/templates/. Provider selection is
+// env-driven (SELVA_AUTH_PROVIDER etc.) — no selva.config.js is generated.
 
 import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
 import { resolve, join, basename } from 'node:path';
@@ -81,7 +81,6 @@ export async function runCreate(argv) {
 	const envTemplate = readFileSync(join(runtimeTemplates, '.env.example'), 'utf8');
 	writeEnvFile(join(targetDir, '.env'), envTemplate, values);
 
-	cpSync(join(runtimeTemplates, 'selva.config.example.js'), join(targetDir, 'selva.config.js'));
 	cpSync(join(runtimeTemplates, 'ecosystem.config.cjs'), join(targetDir, 'ecosystem.config.cjs'));
 
 	writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
@@ -257,16 +256,16 @@ function envBool(v) {
 }
 
 // The deployment's package.json depends on @selvajs/selva (prebuilt
-// SvelteKit app) plus whichever providers the operator picked. Providers are
-// imported by selva.config.js — npm needs them resolvable from node_modules.
+// 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 also list @selvajs/cli itself as a dep so the `selva` bin gets linked
+// 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.
-function buildPackageJson(name, values) {
+function buildPackageJson(name /*, values */) {
 	const deps = {
 		'@selvajs/cli': 'latest',
-		'@selvajs/platform': '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
@@ -274,16 +273,6 @@ function buildPackageJson(name, values) {
 		pm2: '^5.4.0'
 	};
 
-	const providers = new Set([
-		values.SELVA_AUTH_PROVIDER,
-		values.SELVA_DATA_PROVIDER,
-		values.SELVA_STORAGE_PROVIDER
-	]);
-
-	if (providers.has('local')) deps['@selvajs/local-provider'] = 'latest';
-	if (providers.has('supabase')) deps['@selvajs/supabase-provider'] = 'latest';
-	if (providers.has('header')) deps['@selvajs/header-auth-provider'] = 'latest';
-
 	// 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.

package/src/commands/doctor.js

@@ -1,21 +1,23 @@
 // `selva doctor` — validate a deployment without starting it.
 //
 // Checks:
-//   • .env exists and has the required keys for the chosen providers
+//   • .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 + chosen provider packages installed
+//   • @selvajs/selva installed
 //   • Origin set when behind a reverse proxy looks set
 //
 // Exits 0 (green) or 1 (any red); yellow checks don't fail the run.
 
-import { existsSync, accessSync, constants, statSync } from 'node:fs';
+import { existsSync, readFileSync, accessSync, constants, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readEnvFile } from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { detectDrift } from './migrate.js';
 
 const HEX_64 = /^[0-9a-f]{64}$/i;
 const PLACEHOLDER = 'replace-this-with-a-random-32-byte-hex-key';
@@ -31,16 +33,21 @@ export async function runDoctor() {
 
 	// ── Files ──────────────────────────────────────────────────────────
 	checks.push(checkFile(join(dir, '.env'), '.env present'));
-	checks.push(checkFile(join(dir, 'selva.config.js'), 'selva.config.js 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 selva.config.ts enforces.
+	// local|supabase. Mirror what providers.server.ts enforces.
 	const providers = {
 		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
 		data: (env.SELVA_DATA_PROVIDER ?? 'local').toLowerCase(),
@@ -83,10 +90,9 @@ export async function runDoctor() {
 	}
 
 	// ── Installed packages ─────────────────────────────────────────────
+	// Provider implementations are bundled into @selvajs/selva — only the
+	// runtime package needs to be on disk.
 	checks.push(checkPackage(dir, '@selvajs/selva'));
-	if (used.has('local')) checks.push(checkPackage(dir, '@selvajs/local-provider'));
-	if (used.has('supabase')) checks.push(checkPackage(dir, '@selvajs/supabase-provider'));
-	if (used.has('header')) checks.push(checkPackage(dir, '@selvajs/header-auth-provider'));
 
 	// ── Origin (best-effort) ───────────────────────────────────────────
 	if (env.ORIGIN) {
@@ -192,10 +198,38 @@ function checkPackage(dir, name) {
 	return green(`${name} installed`);
 }
 
+function checkLayoutDrift(dir) {
+	const pkgPath = join(dir, 'package.json');
+	if (!existsSync(pkgPath)) return yellow('package.json missing — cannot check layout');
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+	} catch {
+		return red('package.json is not valid JSON');
+	}
+	const reasons = detectDrift(pkg, dir);
+	if (reasons.length === 0) return green('deployment layout is current');
+	return red(
+		`deployment layout is outdated — run \`selva migrate\`:\n     ` +
+			reasons.map((r) => '· ' + r).join('\n     ')
+	);
+}
+
+// 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.
+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, and logout URL.
+// allowlist file presence, HOST binding, ORIGIN, bootstrap admin, and the
+// resolved header names so they can be diffed against the proxy config.
 function checkHeaderAuth(dir, env, dataProvider) {
 	const out = [];
 
@@ -204,7 +238,8 @@ function checkHeaderAuth(dir, env, dataProvider) {
 	if (!allowlistDir) {
 		out.push(red('HEADER_AUTH_DATA_DIR (or DATA_PATH) unset — provider will fail to start'));
 	} else {
-		const allowlistPath = resolve(dir, allowlistDir, 'header-allowlist.json');
+		const allowlistAbsDir = resolve(dir, allowlistDir);
+		const allowlistPath = join(allowlistAbsDir, 'header-allowlist.json');
 		if (existsSync(allowlistPath)) {
 			out.push(green(`header-allowlist.json present (${allowlistDir}/header-allowlist.json)`));
 		} else {
@@ -216,6 +251,14 @@ function checkHeaderAuth(dir, env, dataProvider) {
 					`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.
+			if (env.HEADER_AUTH_DATA_DIR) {
+				out.push(checkDirWritable(allowlistAbsDir, `HEADER_AUTH_DATA_DIR=${allowlistDir}`));
+			}
 		}
 	}
 
@@ -264,5 +307,56 @@ 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.
+	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.`
+			)
+		);
+	}
+
 	return out;
 }
+
+function checkDirWritable(absDir, label) {
+	try {
+		if (existsSync(absDir)) {
+			const stat = statSync(absDir);
+			if (!stat.isDirectory()) return red(`${label} exists but isn't a directory`);
+			accessSync(absDir, constants.W_OK);
+			return green(`${label} writable`);
+		}
+		const parent = resolve(absDir, '..');
+		if (!existsSync(parent)) {
+			return yellow(`${label} doesn't exist yet (parent missing: ${parent})`);
+		}
+		accessSync(parent, constants.W_OK);
+		return yellow(`${label} doesn't exist yet — will be created on first run`);
+	} catch {
+		return red(`${label} not writable`);
+	}
+}

package/src/commands/migrate.js

@@ -0,0 +1,304 @@
+// `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.
+
+import {
+	existsSync,
+	readFileSync,
+	writeFileSync,
+	copyFileSync,
+	rmSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync, execSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+
+const APP_NAME = 'selva-compute';
+
+// Packages we own. Everything in this set is rewritten wholesale by migrate;
+// anything outside it (operator's own deps) gets dropped, which is the
+// explicit design choice — operators with custom deps should fork the
+// template rather than hand-patch the deployment package.json.
+const SELVA_DEPS = new Set([
+	'@selvajs/cli',
+	'@selvajs/selva',
+	'@selvajs/runtime', // legacy — removed during migrate
+	'@selvajs/platform', // legacy — bundled into @selvajs/selva
+	'@selvajs/local-provider', // legacy — bundled into @selvajs/selva
+	'@selvajs/supabase-provider', // legacy — bundled into @selvajs/selva
+	'@selvajs/header-auth-provider', // legacy — bundled into @selvajs/selva
+	'@selvajs/create' // legacy CLI — removed during migrate
+]);
+
+const CANONICAL_SCRIPTS = {
+	start: 'selva start',
+	stop: 'selva stop',
+	restart: 'selva restart',
+	logs: 'selva logs',
+	doctor: 'selva doctor',
+	update: 'selva update'
+};
+
+export async function runMigrate() {
+	const dir = resolveDeploymentDir();
+	requireDeploymentDir(dir);
+
+	p.intro(pc.bgCyan(pc.black(' selva migrate ')));
+
+	const pkgPath = join(dir, 'package.json');
+	if (!existsSync(pkgPath)) {
+		p.outro(pc.red('No package.json in this directory — nothing to migrate.'));
+		process.exit(1);
+	}
+
+	const before = JSON.parse(readFileSync(pkgPath, 'utf8'));
+	const target = buildTargetPackageJson(before);
+	const pkgDiff = diffPackageJson(before, target);
+
+	// Side-files: selva.config.js (now unused) and ecosystem.config.cjs
+	// (must point at @selvajs/selva, not @selvajs/runtime).
+	const configPath = join(dir, 'selva.config.js');
+	const hasStaleConfig = existsSync(configPath);
+
+	const ecoPath = join(dir, 'ecosystem.config.cjs');
+	const ecoHasStaleRuntime =
+		existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime');
+
+	const sideFileChanges = [];
+	if (hasStaleConfig) sideFileChanges.push(`${pc.red('-')} selva.config.js ${pc.dim('(no longer needed; providers are env-driven)')}`);
+	if (ecoHasStaleRuntime) sideFileChanges.push(`${pc.yellow('~')} ecosystem.config.cjs ${pc.dim('(rewrite: @selvajs/runtime → @selvajs/selva)')}`);
+
+	if (pkgDiff.length === 0 && sideFileChanges.length === 0) {
+		p.outro(pc.green('Already on the current layout — nothing to migrate.'));
+		return;
+	}
+
+	p.log.info('Changes to apply:');
+	for (const line of pkgDiff) console.log('  ' + line);
+	for (const line of sideFileChanges) console.log('  ' + line);
+
+	const confirmed = await p.confirm({
+		message: 'Apply these changes, reinstall, and restart?',
+		initialValue: true
+	});
+	if (p.isCancel(confirmed) || !confirmed) {
+		p.cancel('Cancelled.');
+		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.
+	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.
+	const bakPath = pkgPath + '.bak';
+	copyFileSync(pkgPath, bakPath);
+	writeFileSync(pkgPath, JSON.stringify(target, null, 2) + '\n', 'utf8');
+
+	if (hasStaleConfig) {
+		copyFileSync(configPath, configPath + '.bak');
+		rmSync(configPath, { force: true });
+	}
+
+	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.
+		const ecoContent = readFileSync(ecoPath, 'utf8').replace(
+			/@selvajs\/runtime/g,
+			'@selvajs/selva'
+		);
+		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.
+	rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
+	rmSync(join(dir, 'package-lock.json'), { force: true });
+
+	const s = p.spinner();
+	s.start('Installing new dependencies (this can take a minute)');
+	try {
+		// --prefer-online to bypass the stale-packument trap documented in
+		// docs/Hotfix-CLI-Runtime.md.
+		execSync('npm install --prefer-online', {
+			cwd: dir,
+			stdio: 'pipe'
+		});
+		s.stop('Dependencies installed');
+	} catch (err) {
+		s.stop(pc.red('npm install failed — rolling back package.json'));
+		copyFileSync(bakPath, pkgPath);
+		if (hasStaleConfig && existsSync(configPath + '.bak')) {
+			copyFileSync(configPath + '.bak', configPath);
+		}
+		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.
+		runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+		p.outro(pc.red(`Migration aborted: ${err.message ?? err}`));
+		process.exit(1);
+	}
+
+	const status = runPm2(dir, ['start', APP_NAME, '--update-env'], { inherit: false });
+	const backupHints = ['package.json.bak'];
+	if (hasStaleConfig) backupHints.push('selva.config.js.bak');
+	if (ecoHasStaleRuntime) backupHints.push('ecosystem.config.cjs.bak');
+
+	if (status === 0) {
+		p.outro(
+			[
+				pc.green('Migration complete.'),
+				pc.dim('Backups saved as ') + pc.cyan(backupHints.join(', ')),
+				pc.dim('Run ') + pc.cyan('selva doctor') + pc.dim(' to verify.')
+			].join('\n')
+		);
+	} else {
+		p.outro(pc.yellow(`Migration applied but pm2 start failed — check \`pm2 logs ${APP_NAME}\`.`));
+	}
+}
+
+// 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.
+function buildTargetPackageJson(current) {
+	const deps = {
+		'@selvajs/cli': 'latest',
+		'@selvajs/selva': 'latest',
+		pm2: '^5.4.0'
+	};
+
+	return {
+		name: current.name ?? 'selva-deployment',
+		version: current.version ?? '0.1.0',
+		private: true,
+		type: 'module',
+		scripts: { ...CANONICAL_SCRIPTS },
+		dependencies: deps
+	};
+}
+
+// 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.
+function diffPackageJson(before, after) {
+	const lines = [];
+
+	const beforeDeps = before.dependencies ?? {};
+	const afterDeps = after.dependencies ?? {};
+
+	const allNames = new Set([...Object.keys(beforeDeps), ...Object.keys(afterDeps)]);
+	for (const name of [...allNames].sort()) {
+		const a = beforeDeps[name];
+		const b = afterDeps[name];
+		if (a && !b) lines.push(`${pc.red('-')} ${name} ${pc.dim(a)}`);
+		else if (!a && b) lines.push(`${pc.green('+')} ${name} ${pc.dim(b)}`);
+		else if (a !== b) lines.push(`${pc.yellow('~')} ${name} ${pc.dim(a + ' → ' + b)}`);
+	}
+
+	const beforeScripts = before.scripts ?? {};
+	const afterScripts = after.scripts ?? {};
+	const allScripts = new Set([...Object.keys(beforeScripts), ...Object.keys(afterScripts)]);
+	for (const name of [...allScripts].sort()) {
+		const a = beforeScripts[name];
+		const b = afterScripts[name];
+		if (a !== b) {
+			if (a && !b) lines.push(`${pc.red('-')} script.${name} ${pc.dim(a)}`);
+			else if (!a && b) lines.push(`${pc.green('+')} script.${name} ${pc.dim(b)}`);
+			else lines.push(`${pc.yellow('~')} script.${name} ${pc.dim(a + ' → ' + b)}`);
+		}
+	}
+
+	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.
+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';
+	const result = spawnSync(bin, args, {
+		cwd: dir,
+		stdio: inherit ? 'inherit' : 'pipe',
+		shell: process.platform === 'win32'
+	});
+	if (result.error) return 1;
+	return result.status ?? 0;
+}
+
+// Exported for use by `selva doctor` so it can warn about layout drift
+// without duplicating the detection logic.
+export function detectDrift(pkgJson, dir) {
+	const deps = pkgJson?.dependencies ?? {};
+	const reasons = [];
+	if (deps['@selvajs/runtime']) reasons.push('@selvajs/runtime is the old runtime package');
+	if (deps['@selvajs/create']) reasons.push('@selvajs/create is the old CLI package');
+	if (deps['@selvajs/platform']) reasons.push('@selvajs/platform is now bundled into @selvajs/selva');
+	if (deps['@selvajs/local-provider'])
+		reasons.push('@selvajs/local-provider is now bundled into @selvajs/selva');
+	if (deps['@selvajs/supabase-provider'])
+		reasons.push('@selvajs/supabase-provider is now bundled into @selvajs/selva');
+	if (deps['@selvajs/header-auth-provider'])
+		reasons.push('@selvajs/header-auth-provider is now bundled into @selvajs/selva');
+	if (!deps['@selvajs/selva']) reasons.push('@selvajs/selva is missing');
+	if (!deps['@selvajs/cli']) reasons.push('@selvajs/cli is missing');
+	if (!deps['pm2']) reasons.push('pm2 is not in dependencies');
+
+	if (dir) {
+		const configPath = join(dir, 'selva.config.js');
+		if (existsSync(configPath)) {
+			reasons.push('selva.config.js is no longer needed (providers are env-driven)');
+		}
+		const ecoPath = join(dir, 'ecosystem.config.cjs');
+		if (existsSync(ecoPath) && readFileSync(ecoPath, 'utf8').includes('@selvajs/runtime')) {
+			reasons.push('ecosystem.config.cjs still references @selvajs/runtime');
+		}
+	}
+
+	return reasons;
+}
+
+// Re-exported so tests/imports can verify what migrate would write without
+// actually running it.
+export { buildTargetPackageJson, SELVA_DEPS };

package/src/commands/pm2.js

@@ -78,17 +78,10 @@ export async function runUpdate() {
 	const before = readRuntimeVersion(dir);
 	p.log.info(`Current @selvajs/selva: ${before ?? 'unknown'}`);
 
-	// All @selvajs/* packages move in lockstep so provider-only fixes and CLI
-	// fixes get picked up even when the runtime version hasn't moved. The
-	// admin-center button runs the same list — keep them in sync if you edit.
-	const packages = [
-		'@selvajs/cli',
-		'@selvajs/selva',
-		'@selvajs/platform',
-		'@selvajs/local-provider',
-		'@selvajs/supabase-provider',
-		'@selvajs/header-auth-provider'
-	];
+	// Providers are bundled into @selvajs/selva — the only @selvajs/* packages
+	// an operator install carries are the runtime and the CLI. The admin-center
+	// "Run update" button runs the same list — keep them in sync if you edit.
+	const packages = ['@selvajs/cli', '@selvajs/selva'];
 
 	const confirmed = await p.confirm({
 		message: 'Refresh all @selvajs/* packages and restart the app?',

package/src/env.js

@@ -78,7 +78,13 @@ export function mergeEnv(template, values) {
 		out.push(...appended);
 	}
 
-	return out.join('\n');
+	// 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.
+	while (out.length > 0 && out[out.length - 1] === '') out.pop();
+	return out.join('\n') + '\n';
 }
 
 export function writeEnvFile(path, template, values) {

package/bin/create.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { runCreate } from '../src/commands/create.js';
-
-runCreate(process.argv.slice(2)).catch((err) => {
-	console.error(err instanceof Error ? err.message : err);
-	process.exit(1);
-});

package/bin/selva.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { runSelva } from '../src/cli.js';
-
-runSelva(process.argv.slice(2)).catch((err) => {
-	console.error(err instanceof Error ? err.message : err);
-	process.exit(1);
-});