@selvajs/cli 4.8.0-beta.8 → 4.8.0

package/src/commands/pm2.js

@@ -1,6 +1,6 @@
-// Thin wrappers around PM2 commands: always pass --update-env (ignore edits),
-// resolve to deployment-local pm2 (avoid daemon version skew with global install),
-// and resync daemon before state changes.
+// Thin wrappers around PM2 commands: resolve to the deployment-local pm2, resync
+// the daemon before state changes, and pass --update-env on restart so edits to
+// .env actually take effect.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -9,10 +9,9 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
-const APP_NAME = 'selva-compute';
+export const APP_NAME = 'selva-compute';
 
-// Resolve to deployment-local pm2 (no global fallback; prevents version skew).
-function pm2Bin(dir) {
+export function pm2Bin(dir) {
 	const local = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'pm2.cmd' : 'pm2');
 	if (!existsSync(local)) {
 		throw new Error(
@@ -25,11 +24,10 @@ function pm2Bin(dir) {
 	return local;
 }
 
-// Parse the two versions pm2 prints alongside its out-of-date warning:
+// Parses the two versions pm2 prints alongside its out-of-date warning:
 //   In memory PM2 version: 6.0.14
 //   Local PM2 version: 5.4.3
-// Returns nulls when the shape changes — callers then fall back to resyncing,
-// which is the pre-existing behaviour.
+// Returns nulls when the shape doesn't match, so callers fall back to resyncing.
 export function parsePm2Skew(output) {
 	// eslint-disable-next-line no-control-regex -- pm2 colourises via chalk on a TTY
 	const clean = output.replace(/\[[0-9;]*m/g, '');
@@ -38,12 +36,10 @@ export function parsePm2Skew(output) {
 	return { daemon: daemon?.[1] ?? null, local: local?.[1] ?? null };
 }
 
-/**
- * True when the running daemon is newer than the deployment-local pm2 — i.e. a
- * foreign global pm2 owns it. `pm2 update` cannot fix that direction: it
- * downgrades the daemon and hands it a dump from a newer version, which drops
- * the process table so selva-compute is never re-registered (issue #118).
- */
+// True when the running daemon is newer than the deployment-local pm2 — i.e. a
+// foreign global pm2 owns it. `pm2 update` can't fix that direction: it would
+// downgrade the daemon and hand it a dump from a newer version, dropping the
+// process table so selva-compute never gets re-registered.
 export function daemonOutranksCli(daemon, local) {
 	if (!daemon || !local) return false;
 	const [a, b] = [daemon.split('.').map(Number), local.split('.').map(Number)];
@@ -54,7 +50,6 @@ export function daemonOutranksCli(daemon, local) {
 	return false;
 }
 
-// Check for daemon/CLI version mismatch; run `pm2 update` only when it can help.
 function ensurePm2InSync(dir) {
 	const bin = pm2Bin(dir);
 	const probe = spawnSync(bin, ['ping'], {
@@ -92,8 +87,10 @@ function ensurePm2InSync(dir) {
 	}
 }
 
-function runPm2(dir, args, { inherit = true } = {}) {
-	const bin = pm2Bin(dir);
+// `bin` lets a caller pass an already-resolved pm2 path instead of resolving
+// fresh from `dir` — needed when node_modules won't exist at call time (e.g.
+// `selva migrate` wipes it mid-flight and passes the binary it stashed first).
+export function runPm2(dir, args, { inherit = true, bin = pm2Bin(dir) } = {}) {
 	const result = spawnSync(bin, args, {
 		cwd: dir,
 		stdio: inherit ? 'inherit' : 'pipe',

package/src/deployment-package.js

@@ -0,0 +1,254 @@
+// The package.json a deployment directory gets. `create` writes it at scaffold
+// time and `migrate` rewrites an existing one onto it, so it lives here rather
+// than in either command — two copies drifted once already, and the pm2 pin is
+// 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';
+
+/**
+ * pm2 is pinned exactly, not caret-ranged.
+ *
+ * pm2's CLI and its long-running daemon must be the same version. A range lets
+ * two deployments installed a week apart resolve differently, and the newer one
+ * silently adopts the daemon the older one started — the skew `ensurePm2InSync`
+ * has to detect and, in the daemon-is-newer direction, cannot repair (#118).
+ *
+ * Read from this package's own devDependencies rather than written here as a
+ * literal. Dependabot scans manifests, not source, so a literal is invisible to
+ * it — this pin sat on 5.4.3 while upstream reached 7.x, which is precisely the
+ * drift operators point at when they argue for distro packages instead.
+ * `checkPinIsExact` keeps the manifest entry from being loosened to a range.
+ */
+const PM2_VERSION = readPinnedPm2Version();
+
+function readPinnedPm2Version() {
+	const manifest = JSON.parse(
+		readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+	);
+	const pinned = manifest.devDependencies?.pm2;
+	if (!pinned || !/^\d+\.\d+\.\d+$/.test(pinned)) {
+		throw new Error(
+			`@selvajs/cli devDependencies.pm2 must be an exact version, got ${JSON.stringify(pinned)}. ` +
+				`Every deployment this CLI scaffolds inherits it, and a range there lets two ` +
+				`installs resolve different pm2s that then fight over one daemon.`
+		);
+	}
+	return pinned;
+}
+
+const SCRIPTS = {
+	start: 'selva start',
+	stop: 'selva stop',
+	restart: 'selva restart',
+	logs: 'selva logs',
+	doctor: 'selva doctor',
+	update: 'selva update'
+};
+
+/**
+ * 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',
+	'@selvajs/selva': 'latest',
+	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
+ * is a temporary shim: remove it once the parent ships the fixed version on
+ * its own (the override then matches what would install anyway, so removal is
+ * cleanup, never urgent).
+ *
+ * js-yaml: pm2 <= 7.0.3 pins 4.3.0, which carries the quadratic-complexity
+ * DoS advisories (GHSA-5p4m-2wfm-xmqj and friends); the fix landed in 4.3.1.
+ * Drop when pm2's own js-yaml dependency reaches >= 4.3.1.
+ */
+export const OVERRIDES = {
+	'js-yaml': '^4.3.1'
+};
+
+/**
+ * Legacy `@selvajs/*` packages that a deployment may still list. Each was
+ * either renamed or folded into `@selvajs/selva`; `migrate` drops them and
+ * `doctor` reports them as layout drift.
+ */
+export const LEGACY_DEPENDENCIES = {
+	'@selvajs/runtime': 'the old runtime package',
+	'@selvajs/create': 'the old CLI package',
+	'@selvajs/platform': 'now bundled into @selvajs/selva',
+	'@selvajs/local-provider': 'now bundled into @selvajs/selva',
+	'@selvajs/supabase-provider': 'now bundled into @selvajs/selva',
+	'@selvajs/header-auth-provider': 'now bundled into @selvajs/selva'
+};
+
+/**
+ * Build the canonical deployment package.json.
+ *
+ * Dependencies are replaced wholesale rather than merged, so an operator's own
+ * additions are dropped. That is deliberate — a deployment directory is
+ * generated output, and anyone needing custom dependencies should depend on
+ * `@selvajs/selva` from their own project instead of editing this file.
+ *
+ * `engines` is the one exception, carried over when present: npm only enforces
+ * it under `engine-strict`, so an operator who pinned a Node floor did it
+ * 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, dependencies }) {
+	const pkg = {
+		name: sanitizePackageName(name),
+		version,
+		private: true,
+		type: 'module',
+		scripts: { ...SCRIPTS },
+		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
+ * them so the loss is declared rather than discovered later.
+ */
+export const CANONICAL_FIELDS = new Set([
+	'name',
+	'version',
+	'private',
+	'type',
+	'scripts',
+	'dependencies',
+	'overrides',
+	'engines'
+]);
+
+export function sanitizePackageName(name) {
+	return (
+		String(name ?? '')
+			.toLowerCase()
+			.replace(/[^a-z0-9._-]+/g, '-')
+			.replace(/^[-._]+|[-._]+$/g, '') || 'selva-deployment'
+	);
+}
+
+export { DEPENDENCIES, SCRIPTS, PM2_VERSION };

package/src/env.js

@@ -2,13 +2,10 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 
-/**
- * Old env name → its replacement, for keys renamed without changing meaning.
- * The server still reads each old name for one minor version and warns at boot
- * (`readRenamed` in `@selvajs/server` `resolveComputeLimits`); `selva doctor`
- * reports them and `selva migrate` rewrites them. Keep in sync with that list,
- * and drop an entry when the server stops reading it.
- */
+// Old env name → its replacement, for keys renamed without changing meaning.
+// The server still reads each old name for one minor version and warns at
+// boot; keep this in sync with the server's list and drop an entry once the
+// server stops reading it.
 export const RENAMED_ENV_VARS = {
 	COMPUTE_DEFINITION_BYTE_CACHE_MB: 'COMPUTE_DEFINITION_CACHE_MB',
 	COMPUTE_RESPONSE_CACHE_MB: 'COMPUTE_SOLVE_CACHE_MB',
@@ -16,16 +13,148 @@ export const RENAMED_ENV_VARS = {
 	MAX_SOLVE_DURATION_MS: 'COMPUTE_SOLVE_DEADLINE_MS'
 };
 
-/**
- * Deprecated vars whose replacement changes the VALUE too, so they can't be
- * rewritten by renaming a key. `selva doctor` reports these; migrate leaves
- * them alone rather than guessing.
- */
+// Deprecated vars whose replacement changes the VALUE too, so a simple key
+// rename can't migrate them — `selva migrate` leaves these alone rather than guessing.
 export const REPLACED_ENV_VARS = {
 	SELVA_FLAG_COMPUTE_DEBUG_VERBOSE: 'SELVA_FLAG_COMPUTE_DEBUG=verbose'
 };
 
-// Parse a .env file into { key: value }. Preserves nothing else.
+// 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/)) {
@@ -51,7 +180,6 @@ export function readEnvFile(path) {
 	return parseEnv(readFileSync(path, 'utf8'));
 }
 
-// Merge values into template: preserve structure, rewrite in-place, append new keys.
 export function mergeEnv(template, values) {
 	const seen = new Set();
 	const lines = template.split(/\r?\n/);
@@ -92,27 +220,71 @@ export function mergeEnv(template, values) {
 		out.push(...appended);
 	}
 
-	// Ensure single trailing newline (shell append mishap guard).
 	while (out.length > 0 && out[out.length - 1] === '') out.pop();
 	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');
 }
 
 /**
- * Rewrite deprecated keys to their current names, in place. `renames` maps old
- * name → new name. Only the key is touched — the value, comments, ordering and
- * spacing survive, so an operator's tuned file stays recognisably theirs.
+ * Rewrite deprecated keys to their current names, in place. Only the key is
+ * touched — value, comments, ordering, and spacing survive.
  *
  * A key already present under its new name is left alone and its old line is
- * dropped: the server resolves the same way (new name wins), so keeping both
- * would preserve a line that does nothing.
+ * dropped: the server resolves new-name-wins, so keeping both would preserve
+ * a line that does nothing.
  *
- * Returns `{ text, changes }` where `changes` is `[oldName, newName, 'renamed'
- * | 'dropped']` per line acted on; an empty array means the file was already
- * current and nothing should be written.
+ * Returns `{ text, changes }`, `changes` being `[oldName, newName, 'renamed'
+ * | 'dropped']` per line acted on. Empty means the file was already current.
  */
 export function renameEnvKeys(text, renames) {
 	const present = new Set(Object.keys(parseEnv(text)));

package/src/node-range.js

@@ -0,0 +1,66 @@
+// Node version-range matching, used by `selva doctor` to check an installed
+// runtime and by the scaffolder to refuse a too-old shell before writing files.
+
+/**
+ * Narrow `engines.node` range check — `>=X`, `^`, `~`, `||`, and bare/x-ranges.
+ * Returns null when unparseable so a misread never reports a false failure.
+ *
+ * Mirrors `satisfiesRange` in @selvajs/server/ops. Duplicated because the CLI is
+ * dependency-free by design (it scaffolds the deployment that installs the
+ * runtime, so it cannot import from it).
+ */
+export function satisfiesNodeRange(version, range) {
+	const core = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(version).trim());
+	if (!core) return null;
+	const v = [Number(core[1]), Number(core[2]), Number(core[3])];
+
+	let anyParsed = false;
+	for (const alt of String(range).split('||')) {
+		const clauses = alt.trim().split(/\s+/).filter(Boolean);
+		if (!clauses.length) continue;
+
+		let all = true;
+		let parsed = true;
+		for (const clause of clauses) {
+			const m = /^(>=|<=|>|<|\^|~|=)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/.exec(clause);
+			if (!m) {
+				parsed = false;
+				break;
+			}
+			const op = m[1] ?? '=';
+			const num = (s) => (s == null || s === 'x' || s === '*' ? 0 : Number(s));
+			const t = [Number(m[2]), num(m[3]), num(m[4])];
+			let cmp = 0;
+			for (let i = 0; i < 3; i++) {
+				if (v[i] > t[i]) {
+					cmp = 1;
+					break;
+				}
+				if (v[i] < t[i]) {
+					cmp = -1;
+					break;
+				}
+			}
+			let ok;
+			if (op === '>=') ok = cmp >= 0;
+			else if (op === '>') ok = cmp > 0;
+			else if (op === '<=') ok = cmp <= 0;
+			else if (op === '<') ok = cmp < 0;
+			else if (op === '^') ok = cmp >= 0 && v[0] === t[0];
+			else if (op === '~') ok = cmp >= 0 && v[0] === t[0] && v[1] === t[1];
+			else
+				ok =
+					v[0] === t[0] &&
+					(m[3] == null || m[3] === 'x' || m[3] === '*' || v[1] === t[1]) &&
+					(m[4] == null || m[4] === 'x' || m[4] === '*' || v[2] === t[2]);
+			if (!ok) {
+				all = false;
+				break;
+			}
+		}
+		if (!parsed) continue;
+		anyParsed = true;
+		if (all) return true;
+	}
+	return anyParsed ? false : null;
+}