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

package/README.md

@@ -8,28 +8,23 @@ 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`, `ecosystem.config.cjs`, `package.json`. Runs `npm install`.
+Prompts for provider, tenancy, flags, brand name, admin email; generates `SELVA_HMAC_KEY` and `SELVA_AT_REST_KEY`; writes `.env`, `ecosystem.config.cjs`, `package.json`; runs `npm install`. Refuses to overwrite a non-empty directory unless you pass `--force`.
 
 ## Operate an existing deployment
 
-After install, the package exposes a `selva` bin:
+Installing adds a `selva` bin, scoped to the deployment directory (needs `.env` or `ecosystem.config.cjs` in the cwd):
 
 ```bash
-selva init                  # reconfigure prompts; preserves existing secrets
-selva doctor                # validate env + providers + paths
+selva init                 # reconfigure prompts; keeps existing secrets
+selva doctor [--fix]       # validate env, providers, Node engine, boot persistence
+selva migrate              # bring package.json onto the current layout
 selva start | stop | restart | logs
-selva update                # npm update @selvajs/selva + pm2 restart
+selva update                 # update @selvajs/cli + @selvajs/selva, then restart
 selva keys rotate hmac      # rotate SELVA_HMAC_KEY (logs everyone out)
 selva keys rotate at-rest   # rotate SELVA_AT_REST_KEY (compute API key needs re-entry)
 ```
 
-All operator commands run inside the deployment directory (the one that contains `.env` and `ecosystem.config.cjs`).
-
-## Re-running a command is safe
-
-- `npx @selvajs/cli` refuses to overwrite a non-empty directory without `--force`.
-- `selva init` reads the current `.env`, lets the user edit, and **never** regenerates `SELVA_HMAC_KEY` / `SELVA_AT_REST_KEY` if they're already set.
-- A `.selva-version` marker is written so a future CLI version knows which config layout it is looking at and can upgrade it cleanly.
+`selva init` never regenerates `SELVA_HMAC_KEY` or `SELVA_AT_REST_KEY` once they're set — rotating those is `keys rotate`'s job, since it invalidates sessions or encrypted data. A `.selva-version` marker records which CLI version scaffolded the directory, so a later `selva migrate` knows what layout it's upgrading from.
 
 ## Relationship to `@selvajs/selva`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.8.0-beta.10",
+  "version": "4.8.0-beta.11",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -40,6 +40,9 @@
     "@clack/prompts": "^1.7.0",
     "picocolors": "^1.1.1"
   },
+  "devDependencies": {
+    "pm2": "7.0.3"
+  },
   "scripts": {
     "start": "node ./bin/cli.js",
     "selva": "node ./bin/selva.js",

package/src/checks/boot.js

@@ -12,7 +12,10 @@
 
 import { existsSync, readFileSync, accessSync, constants } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { join, resolve, dirname, delimiter } from 'node:path';
+// These checks only ever run on a Linux host (see the platform gate below), so
+// every path here is POSIX. Using the platform-default `node:path` would build
+// backslash paths and split PATH on `;` when the tests run on Windows.
+import { posix as path } from 'node:path';
 import { homedir } from 'node:os';
 import { green, red, yellow, fixable } from './result.js';
 
@@ -22,10 +25,10 @@ export const systemEnv = {
 	env: () => process.env,
 	homedir,
 	exists: existsSync,
-	readFile: (path) => readFileSync(path, 'utf8'),
-	isWritable: (path) => {
+	readFile: (target) => readFileSync(target, 'utf8'),
+	isWritable: (target) => {
 		try {
-			accessSync(path, constants.W_OK);
+			accessSync(target, constants.W_OK);
 			return true;
 		} catch {
 			return false;
@@ -50,15 +53,15 @@ export function checkBootPersistence(dir, env = systemEnv) {
 // dump.pm2 is what `pm2 resurrect` replays. Without it the unit starts pm2 and
 // pm2 starts nothing.
 function checkSavedProcessList(dir, env) {
-	const pm2Home = env.env().PM2_HOME ?? join(env.homedir(), '.pm2');
-	if (env.exists(join(pm2Home, 'dump.pm2'))) {
+	const pm2Home = env.env().PM2_HOME ?? path.join(env.homedir(), '.pm2');
+	if (env.exists(path.join(pm2Home, 'dump.pm2'))) {
 		return green('pm2 process list saved (dump.pm2 present)');
 	}
 	return yellow(
 		'pm2 process list not saved — run `npx pm2 save` so a reboot can ' +
 			'resurrect the app (nothing to restore without it)',
 		fixable('run `pm2 save` to persist the current process list', () => {
-			const bin = join(dir, 'node_modules', '.bin', 'pm2');
+			const bin = path.join(dir, 'node_modules', '.bin', 'pm2');
 			if (!env.exists(bin)) return red('pm2 not installed in this deployment');
 			const r = env.run(bin, ['save'], { cwd: dir });
 			return (r.status ?? 1) === 0
@@ -89,7 +92,7 @@ function checkSystemdUnit(dir, env) {
 		return [yellow(`pm2 systemd unit present but unreadable (${unitPath})`)];
 	}
 
-	const localPm2 = join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
+	const localPm2 = path.join(dir, 'node_modules', 'pm2', 'bin', 'pm2');
 	const execStart = /^ExecStart=(.+)$/m.exec(unit)?.[1] ?? '';
 	if (execStart.includes(localPm2)) {
 		return [green('pm2 systemd boot unit installed (uses deployment-local pm2)')];
@@ -102,7 +105,7 @@ function checkSystemdUnit(dir, env) {
 				`expected:  ${localPm2} resurrect\n     ` +
 				`Reboots will resurrect via the wrong pm2 (version skew). Re-run startup ` +
 				`with the local binary:\n     ` +
-				`sudo env PATH=$PATH:${join(dir, 'node_modules', '.bin')} ${localPm2} ` +
+				`sudo env PATH=$PATH:${path.join(dir, 'node_modules', '.bin')} ${localPm2} ` +
 				`startup systemd -u $USER --hp $HOME`
 		)
 	];
@@ -116,14 +119,14 @@ function checkStrayGlobalPm2(dir, env) {
 	// Only offer the removal when we could actually perform it. A global
 	// install under /usr is root-owned; attempting it would half-fail and
 	// leave the operator worse informed than a printed instruction.
-	const writable = env.isWritable(dirname(globalPm2));
+	const writable = env.isWritable(path.dirname(globalPm2));
 
 	return [
 		yellow(
 			`a pm2 outside this deployment is on PATH (${globalPm2}) — it can fork a ` +
 				`mismatched daemon and trigger skew. Prefer \`npm run\` wrappers / \`npx pm2\` ` +
 				`from this directory; consider \`npm uninstall -g pm2\`.` +
-				(writable ? '' : `\n     (${dirname(globalPm2)} is not writable — needs sudo)`),
+				(writable ? '' : `\n     (${path.dirname(globalPm2)} is not writable — needs sudo)`),
 			writable
 				? fixable(`uninstall the global pm2 at ${globalPm2}`, () => {
 						const r = env.run('npm', ['uninstall', '-g', 'pm2'], {});
@@ -136,13 +139,12 @@ function checkStrayGlobalPm2(dir, env) {
 	];
 }
 
-// Scan PATH for a stray pm2 binary (read-only).
 export function findGlobalPm2(dir, env = systemEnv) {
-	const localBin = resolve(dir, 'node_modules', '.bin');
-	const dirs = (env.env().PATH ?? '').split(delimiter).filter(Boolean);
+	const localBin = path.resolve(dir, 'node_modules', '.bin');
+	const dirs = (env.env().PATH ?? '').split(path.delimiter).filter(Boolean);
 	for (const d of dirs) {
-		if (resolve(d) === localBin) continue;
-		const candidate = join(d, 'pm2');
+		if (path.resolve(d) === localBin) continue;
+		const candidate = path.join(d, 'pm2');
 		if (env.exists(candidate)) return candidate;
 	}
 	return null;

package/src/checks/config.js

@@ -24,11 +24,7 @@ export function checkSecret(value, label) {
 	return green(label);
 }
 
-/**
- * The three provider slots, lowercased and defaulted the same way the runtime
- * defaults them. Returned alongside the checks because the caller decides which
- * provider-specific checks to run from it.
- */
+// Lowercased and defaulted the same way create-selva-providers.ts defaults them.
 export function resolveProviders(env) {
 	return {
 		auth: (env.SELVA_AUTH_PROVIDER ?? 'local').toLowerCase(),
@@ -69,13 +65,9 @@ export function checkOrigin(env) {
 	return green(`ORIGIN=${env.ORIGIN}`);
 }
 
-/**
- * Report env vars that were renamed or replaced.
- *
- * 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 is reported here and nowhere else.
- */
+// 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.
 export function checkDeprecatedEnv(env) {
 	const checks = [];
 

package/src/checks/runtime.js

@@ -0,0 +1,289 @@
+// What the host provides versus what the deployment brings itself.
+//
+// The split trips operators up: Node and npm come from the host (distro
+// packages, nvm, whatever), pm2 comes from the deployment. Installing pm2 from
+// apt or `npm i -g` looks like the tidy thing to do and produces a daemon that
+// silently fights the local one. These checks name which side of the line each
+// tool is on, so the answer is on screen instead of in a support thread.
+//
+// checkNodeEngine (doctor.js) already validates the running Node against
+// engines.node. Nothing here repeats that — this covers what it can't see: npm,
+// the pm2 install itself, and whether the Node running doctor is the same one
+// pm2 launched the app under.
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { green, red, yellow } from './result.js';
+import { PM2_VERSION } from '../deployment-package.js';
+
+/** The real OS. Tests pass a stand-in with the same shape. */
+export const runtimeEnv = {
+	platform: () => process.platform,
+	env: () => process.env,
+	homedir,
+	exists: existsSync,
+	readFile: (path) => readFileSync(path, 'utf8'),
+	realpath: (path) => {
+		try {
+			return realpathSync(path);
+		} catch {
+			return path;
+		}
+	},
+	execPath: () => process.execPath,
+	// Signal 0 probes liveness without touching the process. EPERM means it
+	// exists but belongs to another user — alive for our purposes.
+	processAlive: (pid) => {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (err) {
+			return err?.code === 'EPERM';
+		}
+	},
+	run: (cmd, args, opts) =>
+		spawnSync(cmd, args, {
+			...opts,
+			encoding: 'utf8',
+			shell: process.platform === 'win32'
+		})
+};
+
+export function checkRuntimeEnvironment(dir, env = runtimeEnv) {
+	return [
+		checkNpm(env),
+		checkNodeProvenance(env),
+		...checkPm2Install(dir, env),
+		...checkPm2Daemon(dir, env)
+	];
+}
+
+// ── npm ─────────────────────────────────────────────────────────────────
+
+// Debian's `nodejs` package doesn't always pull in `npm`, and some distro
+// splits ship an npm several majors behind the Node beside it. Both only
+// surface at `selva update`, which is the worst moment to discover it.
+const MIN_NPM_MAJOR = 10;
+
+function checkNpm(env) {
+	const probe = env.run('npm', ['--version'], {});
+	const version = String(probe.stdout ?? '')
+		.trim()
+		.split('\n')
+		.pop();
+
+	if ((probe.status ?? 1) !== 0 || !/^\d+\.\d+\.\d+/.test(version ?? '')) {
+		return red(
+			'npm not found on PATH — `selva update` and `npm install` cannot run.\n     ' +
+				'On Debian/Ubuntu the `nodejs` package does not always include it. Install\n     ' +
+				'Node 24 from NodeSource, which bundles a matching npm:\n     ' +
+				'curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs'
+		);
+	}
+
+	const major = Number(/^(\d+)\./.exec(version)[1]);
+	if (major < MIN_NPM_MAJOR) {
+		return yellow(
+			`npm ${version} is older than the Node beside it usually ships (expected >= ${MIN_NPM_MAJOR}).\n     ` +
+				'A distro-split npm can resolve dependencies the runtime does not expect.\n     ' +
+				'Install Node from NodeSource so npm and Node come from one source.'
+		);
+	}
+	return green(`npm ${version} on PATH`);
+}
+
+// ── Node provenance ─────────────────────────────────────────────────────
+
+// Which Node runs the app is decided by pm2's environment, not by the shell
+// running doctor. When those differ — a distro Node on PATH for the login
+// shell, an nvm Node for the daemon, or the reverse — doctor validates a
+// version the app never uses, and engines.node passes while production runs
+// something else entirely.
+function checkNodeProvenance(env) {
+	const running = env.realpath(env.execPath());
+	const source = describeNodeSource(running);
+
+	const which = env.run(env.platform() === 'win32' ? 'where' : 'which', ['node'], {});
+	const onPath = String(which.stdout ?? '')
+		.trim()
+		.split('\n')[0]
+		?.trim();
+
+	if (!onPath) {
+		return yellow(`Node v${process.versions.node} at ${running} (${source}) — not resolvable on PATH`);
+	}
+
+	if (env.realpath(onPath) === running) {
+		return green(`Node v${process.versions.node} — ${source} (${running})`);
+	}
+
+	return yellow(
+		`Two Node installations are in play: this shell resolves \`node\` to ${env.realpath(onPath)},\n     ` +
+			`but doctor is running under ${running} (${source}). pm2 launches the app with the\n     ` +
+			`Node it inherited when the daemon started, which may be neither. Confirm with:\n     ` +
+			`npx pm2 describe selva-compute | grep -i "node.js version"`
+	);
+}
+
+// nvm/fnm-managed Nodes disappear for a systemd unit that starts before the
+// user's shell profile runs — worth naming the manager rather than the path.
+function describeNodeSource(path) {
+	const p = path.replace(/\\/g, '/');
+	if (/\/\.nvm\//.test(p)) return 'nvm-managed';
+	if (/\/\.fnm\/|\/fnm_multishells\//.test(p)) return 'fnm-managed';
+	if (/\/\.volta\//.test(p)) return 'volta-managed';
+	if (/^\/usr\/bin\/|^\/bin\//.test(p)) return 'distro package';
+	if (/^\/usr\/local\//.test(p)) return 'manual /usr/local install';
+	if (/\/snap\//.test(p)) return 'snap package';
+	return 'unknown source';
+}
+
+// ── pm2 install ─────────────────────────────────────────────────────────
+
+// The deployment pins pm2 exactly (see deployment-package.js). This verifies
+// the pin actually landed — a hand-edited package.json, a partial install, or
+// an operator who ran `npm i -g pm2` and deleted the local one all end here.
+function checkPm2Install(dir, env) {
+	const out = [];
+	const pkgPath = join(dir, 'node_modules', 'pm2', 'package.json');
+
+	if (!env.exists(pkgPath)) {
+		out.push(
+			red(
+				`pm2 is not installed in this deployment (expected ${join(dir, 'node_modules', 'pm2')}).\n     ` +
+					'Selva ships its own pinned pm2 on purpose — the `selva` commands refuse to fall\n     ' +
+					'back to a global one, because two pm2 versions sharing a daemon hang restarts.\n     ' +
+					'Fix: npm install'
+			)
+		);
+		return out;
+	}
+
+	let installed = null;
+	try {
+		installed = JSON.parse(env.readFile(pkgPath)).version ?? null;
+	} catch {
+		// Unreadable package.json — reported below as an unverifiable version.
+	}
+
+	if (!installed) {
+		out.push(yellow('pm2 installed but its version is unreadable — cannot verify the pin'));
+	} else if (installed === PM2_VERSION) {
+		out.push(green(`pm2 ${installed} installed locally (matches the pinned version)`));
+	} else {
+		out.push(
+			yellow(
+				`pm2 ${installed} is installed but this scaffold pins ${PM2_VERSION}.\n     ` +
+					'The pin is exact because pm2 CLI and daemon must match. Realign it:\n     ' +
+					`npm install pm2@${PM2_VERSION} && npx pm2 update`
+			)
+		);
+	}
+
+	// A pm2 listed in dependencies with a range instead of the exact pin means
+	// package.json was hand-edited; the next `npm install` silently drifts again.
+	const declared = readDeclaredPm2(dir, env);
+	if (declared && declared !== PM2_VERSION) {
+		out.push(
+			yellow(
+				`package.json declares pm2 "${declared}" rather than the exact pin ${PM2_VERSION}.\n     ` +
+					'A range lets a later `npm install` adopt a version the running daemon is not.\n     ' +
+					'Run `selva migrate` to restore the canonical package.json.'
+			)
+		);
+	}
+
+	return out;
+}
+
+function readDeclaredPm2(dir, env) {
+	try {
+		const pkg = JSON.parse(env.readFile(join(dir, 'package.json')));
+		return pkg.dependencies?.pm2 ?? null;
+	} catch {
+		return null;
+	}
+}
+
+// ── pm2 daemon ──────────────────────────────────────────────────────────
+
+// Reports three distinct states rather than pass/fail: no daemon (fine,
+// nothing started yet), a matching daemon, or a daemon a foreign pm2 owns.
+//
+// `pm2 ping` SPAWNS a daemon when none is running, and doctor must stay
+// read-only — so liveness is checked via pm2.pid + signal 0 first, and pm2
+// itself is only invoked once a live daemon is confirmed.
+//
+// The daemon-is-newer direction is red and deliberately offers no fix: `pm2
+// update` would downgrade the daemon and drop its process table, leaving
+// selva-compute unregistered. Same reasoning as ensurePm2InSync in commands/pm2.js.
+function checkPm2Daemon(dir, env) {
+	const bin = join(dir, 'node_modules', '.bin', env.platform() === 'win32' ? 'pm2.cmd' : 'pm2');
+	if (!env.exists(bin)) return [];
+
+	const pm2Home = env.env().PM2_HOME ?? join(env.homedir(), '.pm2');
+	const pidPath = join(pm2Home, 'pm2.pid');
+	if (!env.exists(pidPath)) {
+		return [yellow('pm2 daemon is not running — it starts on `selva start`')];
+	}
+	let pid = NaN;
+	try {
+		pid = Number(String(env.readFile(pidPath)).trim());
+	} catch {
+		// Unreadable pid file — fall through to the stale case.
+	}
+	if (!Number.isInteger(pid) || pid <= 0 || !env.processAlive(pid)) {
+		return [yellow('pm2 daemon is not running (stale pm2.pid) — it starts on `selva start`')];
+	}
+
+	const probe = env.run(bin, ['ping'], { cwd: dir });
+	const output = String(probe.stdout ?? '') + String(probe.stderr ?? '');
+
+	if (!/out-of-date/i.test(output)) {
+		if (/pong/i.test(output)) return [green('pm2 daemon responds and matches the local pm2')];
+		return [yellow('pm2 daemon did not answer `pm2 ping` — check `npx pm2 ping` by hand')];
+	}
+
+	const { daemon, local } = parseSkew(output);
+	if (daemon && local && compareVersions(daemon, local) > 0) {
+		return [
+			red(
+				`The running pm2 daemon (v${daemon}) is NEWER than this deployment's pm2 (v${local}),\n     ` +
+					'so a pm2 from outside the deployment owns it. `pm2 update` would downgrade the\n     ' +
+					'daemon and drop its process table, so `selva start` refuses outright.\n     ' +
+					'Resolve it (the app goes down briefly):\n     ' +
+					`npx pm2 kill && sudo npm uninstall -g pm2 && npm install && npm start\n     ` +
+					'Then re-run: npx pm2 save && npx pm2 startup systemd -u $USER --hp $HOME'
+			)
+		];
+	}
+
+	return [
+		yellow(
+			`pm2 daemon (v${daemon ?? 'unknown'}) differs from the local pm2 (v${local ?? PM2_VERSION}).\n     ` +
+				'Resync it — this briefly restarts managed processes: npx pm2 update'
+		)
+	];
+}
+
+function parseSkew(output) {
+	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
+	const clean = output.replace(/\[[0-9;]*m/g, '');
+	return {
+		daemon: /In memory PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean)?.[1] ?? null,
+		local: /Local PM2 version:\s*v?(\d+\.\d+\.\d+)/i.exec(clean)?.[1] ?? null
+	};
+}
+
+function compareVersions(a, b) {
+	const [x, y] = [a.split('.').map(Number), b.split('.').map(Number)];
+	for (let i = 0; i < 3; i++) {
+		if (x[i] > y[i]) return 1;
+		if (x[i] < y[i]) return -1;
+	}
+	return 0;
+}
+
+export { describeNodeSource, compareVersions, MIN_NPM_MAJOR };

package/src/cli.js

@@ -67,7 +67,7 @@ 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)',
 			'',

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';
@@ -22,12 +21,10 @@ 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,19 +47,18 @@ 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).
+	// 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);
 	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
 
@@ -74,7 +70,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 +105,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 +131,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 +175,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);