@jsorm/cli 0.1.3 → 0.2.1

package/README.md

@@ -60,8 +60,25 @@ jsorm watch
 
 ---
 
+## jsorm update
+
+Installs the latest engine compatible with this CLI and removes older installed versions. It checks the download server now and fails, removing nothing, when the server cannot be reached or the latest engine belongs to a newer release line.
+
+```bash
+jsorm update            # install the latest compatible engine
+jsorm update --check    # report installed and latest, install nothing
+jsorm update --force    # reinstall the latest compatible engine
+```
+
+The engine lives in `~/.jsorm/engines/v<version>/` (owner-only). Before every run the CLI checks the binary against the SHA-256 signed in the release manifest; a modified engine is reinstalled, never run. Other commands check for updates at most once every 24 hours; `JSORM_NO_UPDATE_CHECK=1` skips the check while an engine is installed.
+
+---
+
 ## Requirements
 
 - Node.js 22+
+- macOS or Linux, x64 or arm64 (Windows is not supported yet)
 - `jsorm.config.ts` at project root
-- Models in configured path
+- Models in configured path
+
+Run commands through your package manager: `pnpm jsorm`, `npx jsorm`, `yarn jsorm` or `bunx jsorm`. A local install does not put `jsorm` on `PATH`.

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -43,6 +43,15 @@ function detectPackageManager() {
 	if (process.env.npm_config_user_agent?.includes("yarn")) return "yarn";
 	return "npm";
 }
+/** Command that runs a locally installed `jsorm` with this package manager. */
+function cliRunner(pm) {
+	switch (pm) {
+		case "npm": return "npx jsorm";
+		case "yarn": return "yarn jsorm";
+		case "bun": return "bunx jsorm";
+		default: return "pnpm jsorm";
+	}
+}
 function detectRuntime() {
 	if (typeof process !== "undefined" && process.versions?.bun) return "bun";
 	if (typeof process !== "undefined" && process.versions?.deno) return "deno";
@@ -85,6 +94,134 @@ function detectFramework() {
 	return "none";
 }
 //#endregion
+//#region src/version.ts
+function compareVersions(a, b) {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+		const na = pa[i] ?? 0;
+		const nb = pb[i] ?? 0;
+		if (na > nb) return 1;
+		if (na < nb) return -1;
+	}
+	return 0;
+}
+/** Release line of a version: "0.2" while the major is 0, "1" from 1.0 on. */
+function releaseLine(version) {
+	const [major = "0", minor = "0"] = version.split(".");
+	return major === "0" ? `0.${minor}` : major;
+}
+/** The CLI only runs engines of its own release line. */
+function isCompatibleEngine(cliVersion, engineVersion) {
+	return releaseLine(cliVersion) === releaseLine(engineVersion);
+}
+//#endregion
+//#region src/install.ts
+function getVersionDir(enginesDir, version) {
+	return join(enginesDir, `v${version}`);
+}
+/** Signed envelope stored next to an installed binary. */
+function getEnvelopePath(enginesDir, version, binaryName) {
+	return join(getVersionDir(enginesDir, version), `${binaryName}.envelope.json`);
+}
+/**
+* Creates `dir` (and missing parents) readable and writable by its owner
+* only, and tightens it when it already exists: nobody else may replace an
+* engine the CLI is going to run.
+*/
+function ensureOwnerOnlyDir(dir) {
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	if (process.platform !== "win32") chmodSync(dir, 448);
+}
+/** Installed versions that hold `binaryName`, newest first, e.g. ["0.2.1", "0.2.0"]. */
+function listInstalledVersions(enginesDir, binaryName) {
+	if (!existsSync(enginesDir)) return [];
+	return readdirSync(enginesDir).filter((d) => d.startsWith("v") && existsSync(join(enginesDir, d, binaryName))).map((d) => d.slice(1)).sort((a, b) => compareVersions(b, a));
+}
+/** Newest installed version accepted by `accept`, e.g. "0.2.1". */
+function detectInstalledVersion(enginesDir, binaryName, accept = () => true) {
+	return listInstalledVersions(enginesDir, binaryName).find(accept) ?? null;
+}
+/** Removes every installed version directory except `keepVersion`. Returns the removed versions. */
+function pruneInstalledVersions(enginesDir, binaryName, keepVersion) {
+	const removed = listInstalledVersions(enginesDir, binaryName).filter((v) => v !== keepVersion);
+	for (const version of removed) rmSync(getVersionDir(enginesDir, version), {
+		recursive: true,
+		force: true
+	});
+	return removed;
+}
+async function sha256File(filePath) {
+	const hash = createHash("sha256");
+	await pipeline(createReadStream(filePath), hash);
+	return hash.digest("hex");
+}
+async function downloadToFile(url, destPath) {
+	const res = await fetch(url, { signal: AbortSignal.timeout(6e4) });
+	if (!res.ok || !res.body) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+	await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}
+function extractTarGz(tarPath, destDir) {
+	try {
+		execFileSync("tar", [
+			"-xzf",
+			tarPath,
+			"-C",
+			destDir
+		], { stdio: "pipe" });
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`tar extraction failed: ${msg}`);
+	}
+}
+/**
+* Downloads, verifies and extracts the engine inside a private temp directory,
+* and only then moves the binary into `<enginesDir>/v<version>/<binaryName>`.
+* A failed or interrupted install never leaves a binary at the final path.
+* Returns the installed binary path.
+*/
+async function installEngine(options) {
+	const { url, enginesDir, version, binaryName, expectedSha256, expectedBinarySha256, envelope, log = () => {} } = options;
+	ensureOwnerOnlyDir(enginesDir);
+	const tempDir = mkdtempSync(join(enginesDir, ".tmp-"));
+	try {
+		const tarPath = join(tempDir, "engine.tar.gz");
+		log(`  Downloading from ${url}...`);
+		await downloadToFile(url, tarPath);
+		log(`  ✓ Downloaded ${(statSync(tarPath).size / 1024).toFixed(1)} KB`);
+		log(`  Verifying checksum...`);
+		const hash = await sha256File(tarPath);
+		if (hash !== expectedSha256) throw new Error(`Checksum mismatch!\n  Expected: ${expectedSha256}\n  Got:      ${hash}`);
+		log(`  ✓ Checksum verified`);
+		log(`  Extracting...`);
+		const extractDir = join(tempDir, "out");
+		mkdirSync(extractDir);
+		extractTarGz(tarPath, extractDir);
+		const extractedPath = join(extractDir, "jsorm");
+		if (!existsSync(extractedPath)) throw new Error(`Archive does not contain the "jsorm" binary`);
+		const binaryHash = await sha256File(extractedPath);
+		if (binaryHash !== expectedBinarySha256) throw new Error(`Binary checksum mismatch!\n  Expected: ${expectedBinarySha256}\n  Got:      ${binaryHash}`);
+		if (process.platform !== "win32") chmodSync(extractedPath, 448);
+		const envelopeTemp = join(tempDir, "envelope.json");
+		writeFileSync(envelopeTemp, JSON.stringify(envelope), { mode: 384 });
+		const destDir = getVersionDir(enginesDir, version);
+		const destPath = join(destDir, binaryName);
+		ensureOwnerOnlyDir(destDir);
+		renameSync(envelopeTemp, getEnvelopePath(enginesDir, version, binaryName));
+		renameSync(extractedPath, destPath);
+		log(`  ✓ Engine installed: ${destPath}`);
+		return destPath;
+	} finally {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region src/manifest.ts
 const EMBEDDED_PUBLIC_KEY_B64 = "6AUQMvF7jBV+S8yv9K8hnnoYzIznQw4nf5x5LAuEsfM=";
 function getSpkiPublicKey(rawKeyB64 = EMBEDDED_PUBLIC_KEY_B64) {
@@ -129,7 +266,12 @@ function parseSignedEnvelope(envelope, publicKey) {
 	if (typeof manifest?.version !== "string" || !manifest.targets || typeof manifest.targets !== "object") return invalid("Invalid manifest format");
 	return {
 		status: "ok",
-		manifest
+		manifest,
+		envelope: {
+			success: true,
+			signature,
+			signed_payload
+		}
 	};
 }
 async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
@@ -155,124 +297,153 @@ async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
 	return parseSignedEnvelope(envelope, publicKey);
 }
 //#endregion
-//#region src/install.ts
-function compareVersions(a, b) {
-	const pa = a.split(".").map(Number);
-	const pb = b.split(".").map(Number);
-	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-		const na = pa[i] ?? 0;
-		const nb = pb[i] ?? 0;
-		if (na > nb) return 1;
-		if (na < nb) return -1;
-	}
-	return 0;
-}
-function getVersionDir(enginesDir, version) {
-	return join(enginesDir, `v${version}`);
-}
-/** Newest installed version that holds `binaryName`, e.g. "0.1.3". */
-function detectInstalledVersion(enginesDir, binaryName) {
-	if (!existsSync(enginesDir)) return null;
-	const dirs = readdirSync(enginesDir).filter((d) => d.startsWith("v")).sort((a, b) => compareVersions(b.slice(1), a.slice(1)));
-	for (const dir of dirs) if (existsSync(join(enginesDir, dir, binaryName))) return dir.slice(1);
-	return null;
-}
-async function sha256File(filePath) {
-	const hash = createHash("sha256");
-	await pipeline(createReadStream(filePath), hash);
-	return hash.digest("hex");
-}
-async function downloadToFile(url, destPath) {
-	const res = await fetch(url, { signal: AbortSignal.timeout(6e4) });
-	if (!res.ok || !res.body) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
-	await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
-}
-function extractTarGz(tarPath, destDir) {
-	try {
-		execFileSync("tar", [
-			"-xzf",
-			tarPath,
-			"-C",
-			destDir
-		], { stdio: "pipe" });
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`tar extraction failed: ${msg}`);
-	}
-}
+//#region src/verify.ts
+const SHA256_HEX = /^[0-9a-f]{64}$/;
 /**
-* Downloads, verifies and extracts the engine inside a private temp directory,
-* and only then moves the binary into `<enginesDir>/v<version>/<binaryName>`.
-* A failed or interrupted install never leaves a binary at the final path.
-* Returns the installed binary path.
+* Checks an installed engine before it runs: its stored envelope must be
+* signed with `publicKey`, declare this version and target, and carry the
+* SHA-256 of the binary on disk.
 */
-async function installEngine(options) {
-	const { url, enginesDir, version, binaryName, expectedSha256, log = () => {} } = options;
-	mkdirSync(enginesDir, { recursive: true });
-	const tempDir = mkdtempSync(join(enginesDir, ".tmp-"));
+async function verifyInstalledEngine(enginesDir, version, binaryName, publicKey) {
+	const envelopePath = getEnvelopePath(enginesDir, version, binaryName);
+	if (!existsSync(envelopePath)) return {
+		ok: false,
+		reason: "no signed envelope next to the binary"
+	};
+	let envelope;
 	try {
-		const tarPath = join(tempDir, "engine.tar.gz");
-		log(`  Downloading from ${url}...`);
-		await downloadToFile(url, tarPath);
-		log(`  ✓ Downloaded ${(statSync(tarPath).size / 1024).toFixed(1)} KB`);
-		log(`  Verifying checksum...`);
-		const hash = await sha256File(tarPath);
-		if (hash !== expectedSha256) throw new Error(`Checksum mismatch!\n  Expected: ${expectedSha256}\n  Got:      ${hash}`);
-		log(`  ✓ Checksum verified`);
-		log(`  Extracting...`);
-		const extractDir = join(tempDir, "out");
-		mkdirSync(extractDir);
-		extractTarGz(tarPath, extractDir);
-		const extractedPath = join(extractDir, "jsorm");
-		if (!existsSync(extractedPath)) throw new Error(`Archive does not contain the "jsorm" binary`);
-		if (process.platform !== "win32") chmodSync(extractedPath, 493);
-		const destDir = getVersionDir(enginesDir, version);
-		const destPath = join(destDir, binaryName);
-		mkdirSync(destDir, { recursive: true });
-		renameSync(extractedPath, destPath);
-		log(`  ✓ Engine installed: ${destPath}`);
-		return destPath;
-	} finally {
-		rmSync(tempDir, {
-			recursive: true,
-			force: true
-		});
+		envelope = JSON.parse(readFileSync(envelopePath, "utf-8"));
+	} catch {
+		return {
+			ok: false,
+			reason: "the stored envelope is not valid JSON"
+		};
 	}
+	const result = parseSignedEnvelope(envelope, publicKey);
+	if (result.status !== "ok") return {
+		ok: false,
+		reason: result.reason
+	};
+	if (result.manifest.version !== version) return {
+		ok: false,
+		reason: `the stored envelope is for v${result.manifest.version}`
+	};
+	const expected = result.manifest.targets[binaryName]?.binary_sha256;
+	if (typeof expected !== "string" || !SHA256_HEX.test(expected)) return {
+		ok: false,
+		reason: `the stored envelope has no binary_sha256 for ${binaryName}`
+	};
+	if (await sha256File(join(getVersionDir(enginesDir, version), binaryName)) !== expected) return {
+		ok: false,
+		reason: "the binary does not match its signed SHA-256"
+	};
+	return { ok: true };
 }
 //#endregion
 //#region src/resolve.ts
+const DAY_MS = 864e5;
+const LAST_CHECK_FILE = ".last-check";
+function readLastCheck(enginesDir) {
+	try {
+		const value = Number(readFileSync(join(enginesDir, LAST_CHECK_FILE), "utf-8").trim());
+		return Number.isFinite(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+function writeLastCheck(enginesDir, time) {
+	try {
+		mkdirSync(enginesDir, { recursive: true });
+		writeFileSync(join(enginesDir, LAST_CHECK_FILE), String(time));
+	} catch {}
+}
+function incompatibleMessage(cliVersion, engineVersion) {
+	return `The latest engine v${engineVersion} needs a newer @jsorm/cli (this is v${cliVersion}, release line ${releaseLine(cliVersion)}).\n  Upgrade it: npm install -D @jsorm/cli@latest`;
+}
+async function fetchTrustedManifest(options) {
+	const { manifestUrl, publicKey = getSpkiPublicKey(), log = () => {} } = options;
+	log(`  Fetching manifest from ${manifestUrl}...`);
+	const result = await fetchManifest(manifestUrl, publicKey);
+	if (result.status === "unreachable") return { unreachable: result.reason };
+	if (result.status === "invalid") throw new Error(result.reason);
+	log(`  ✓ Manifest signature verified`);
+	log(`  ✓ Manifest v${result.manifest.version} (${Object.keys(result.manifest.targets).length} targets)`);
+	return {
+		manifest: result.manifest,
+		envelope: result.envelope
+	};
+}
 /**
 * Returns the path of an engine binary that is safe to run: the installed one
-* when it is current, or a freshly installed stable release. When the server
-* cannot be reached, an installed engine is used as is. Throws when no engine
-* can be provided or when the server's answer cannot be trusted.
+* when it is current, or a freshly installed stable release. Only engines of
+* the CLI's release line are used, and an installed engine only runs after
+* its binary matches the signed SHA-256 stored next to it. When the server
+* cannot be reached, a verified installed engine is used as is. Throws when
+* no engine can be provided or when the server's answer cannot be trusted.
 */
 async function resolveEngine(options) {
-	const { enginesDir, binaryName, manifestUrl, downloadUrl, publicKey = getSpkiPublicKey(), log = () => {} } = options;
-	const installedVer = detectInstalledVersion(enginesDir, binaryName);
+	const { enginesDir, binaryName, downloadUrl, cliVersion, publicKey = getSpkiPublicKey(), log = () => {}, updateCommand = "jsorm update", checkIntervalMs = DAY_MS, skipUpdateCheck = false, force = false, requireLiveCheck = false, now = Date.now } = options;
+	const compatible = (version) => isCompatibleEngine(cliVersion, version);
+	let installedVer = detectInstalledVersion(enginesDir, binaryName, compatible);
+	let rejectedVer = null;
+	if (installedVer) {
+		const check = await verifyInstalledEngine(enginesDir, installedVer, binaryName, publicKey);
+		if (!check.ok) {
+			log(`  ⚠ Installed engine v${installedVer} failed verification: ${check.reason}`);
+			try {
+				rmSync(getVersionDir(enginesDir, installedVer), {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				log(`  ⚠ Could not remove engine v${installedVer}: ${err instanceof Error ? err.message : err}`);
+			}
+			rejectedVer = installedVer;
+			installedVer = null;
+		}
+	}
 	const installedPath = installedVer ? join(getVersionDir(enginesDir, installedVer), binaryName) : null;
-	log(`  Fetching manifest from ${manifestUrl}...`);
-	const result = await fetchManifest(manifestUrl, publicKey);
-	if (result.status === "unreachable") {
-		if (installedPath) {
-			log(`  ⚠ ${result.reason}`);
+	if (installedPath && !force && !requireLiveCheck) {
+		if (skipUpdateCheck) return installedPath;
+		const lastCheck = readLastCheck(enginesDir);
+		const elapsed = lastCheck === null ? Infinity : now() - lastCheck;
+		if (checkIntervalMs > 0 && elapsed >= 0 && elapsed < checkIntervalMs) return installedPath;
+	}
+	const trusted = await fetchTrustedManifest({
+		...options,
+		publicKey
+	});
+	if ("unreachable" in trusted) {
+		if (installedPath && !requireLiveCheck) {
+			log(`  ⚠ ${trusted.unreachable}`);
 			log(`  ⚠ Using installed engine v${installedVer} without checking for updates`);
 			return installedPath;
 		}
-		throw new Error(`${result.reason}\n  ✖ Failed to fetch manifest.`);
+		if (rejectedVer) throw new Error(`${trusted.unreachable}\n  ✖ Installed engine v${rejectedVer} failed verification and cannot be reinstalled offline.\n  Run "${updateCommand}" once the download server is reachable.`);
+		throw new Error(`${trusted.unreachable}\n  ✖ Failed to fetch manifest.`);
 	}
-	if (result.status === "invalid") throw new Error(result.reason);
-	const { manifest } = result;
+	const { manifest, envelope } = trusted;
+	writeLastCheck(enginesDir, now());
 	const stableVersion = manifest.version;
-	log(`  ✓ Manifest signature verified`);
-	log(`  ✓ Manifest v${stableVersion} (${Object.keys(manifest.targets).length} targets)`);
+	if (!compatible(stableVersion)) {
+		if (installedPath && !requireLiveCheck) {
+			log(`  ⚠ ${incompatibleMessage(cliVersion, stableVersion)}`);
+			log(`  ⚠ Using installed engine v${installedVer}`);
+			return installedPath;
+		}
+		throw new Error(incompatibleMessage(cliVersion, stableVersion));
+	}
 	const target = manifest.targets[binaryName];
 	if (!target) throw new Error(`No binary available for ${binaryName}\n  Available: ${Object.keys(manifest.targets).join(", ")}`);
-	if (installedPath && installedVer && compareVersions(stableVersion, installedVer) <= 0) {
+	if (!/^[0-9a-f]{64}$/.test(target.binary_sha256 ?? "")) throw new Error(`Engine v${stableVersion} has no signed binary hash for ${binaryName}; it cannot be verified after install.`);
+	if (installedPath && installedVer && !force && compareVersions(stableVersion, installedVer) <= 0) {
 		log(`  ✓ Engine v${installedVer} is up to date (stable: v${stableVersion})`);
 		return installedPath;
 	}
-	log(installedVer ? `  Update available: v${installedVer} → v${stableVersion}` : `  Engine not found. Downloading v${stableVersion}...`);
+	if (rejectedVer) log(`  Reinstalling engine v${stableVersion}...`);
+	else if (!installedVer) log(`  Engine not found. Downloading v${stableVersion}...`);
+	else if (compareVersions(stableVersion, installedVer) > 0) log(`  Update available: v${installedVer} → v${stableVersion}`);
+	else log(`  Reinstalling engine v${stableVersion}...`);
 	log(`  Requesting download URL...`);
 	const dlRes = await fetch(`${downloadUrl}/${binaryName}`, { signal: AbortSignal.timeout(1e4) });
 	if (!dlRes.ok) throw new Error(`Download request failed: ${dlRes.status} ${dlRes.statusText}`);
@@ -285,9 +456,72 @@ async function resolveEngine(options) {
 		version: stableVersion,
 		binaryName,
 		expectedSha256: target.sha256,
+		expectedBinarySha256: target.binary_sha256,
+		envelope,
 		log
 	});
 }
+/** Reads the live manifest and compares it with the installed engine, without installing. */
+async function checkForUpdate(options) {
+	const { enginesDir, binaryName, cliVersion, now = Date.now } = options;
+	const compatible = (version) => isCompatibleEngine(cliVersion, version);
+	const installed = detectInstalledVersion(enginesDir, binaryName, compatible);
+	const trusted = await fetchTrustedManifest(options);
+	if ("unreachable" in trusted) throw new Error(trusted.unreachable);
+	const { manifest } = trusted;
+	writeLastCheck(enginesDir, now());
+	const latestCompatible = compatible(manifest.version);
+	return {
+		installed,
+		latest: manifest.version,
+		compatible: latestCompatible,
+		updateAvailable: latestCompatible && (installed === null || compareVersions(manifest.version, installed) > 0)
+	};
+}
+//#endregion
+//#region src/update.ts
+/**
+* `jsorm update`: checks the live manifest now, installs the newest
+* compatible engine (again when `force`), and removes every other installed
+* version. Fails, removing nothing, when the live manifest cannot be reached
+* or its engine belongs to another release line.
+*/
+async function updateEngine(options) {
+	const { enginesDir, binaryName, cliVersion, log = () => {} } = options;
+	await resolveEngine({
+		...options,
+		checkIntervalMs: 0,
+		skipUpdateCheck: false,
+		requireLiveCheck: true
+	});
+	const version = detectInstalledVersion(enginesDir, binaryName, (v) => isCompatibleEngine(cliVersion, v));
+	if (!version) throw new Error("No compatible engine is installed after the update");
+	const removed = pruneInstalledVersions(enginesDir, binaryName, version);
+	for (const old of removed) log(`  ✓ Removed engine v${old}`);
+	log(`  ✓ Engine v${version} is installed`);
+	return {
+		version,
+		removed
+	};
+}
+const UPDATE_FLAGS = ["--check", "--force"];
+/** Validates `jsorm update` flags; returns an error message, or null when valid. */
+function validateUpdateArgs(args) {
+	const unknown = args.filter((arg) => !UPDATE_FLAGS.includes(arg));
+	if (unknown.length > 0) return `Unknown option for jsorm update: ${unknown.join(" ")} (use --check or --force)`;
+	if (args.includes("--check") && args.includes("--force")) return "jsorm update: --check and --force cannot be combined";
+	return null;
+}
+/** `jsorm update --check`: reports the installed and latest engine without installing. */
+async function reportUpdate(options) {
+	const { log = () => {} } = options;
+	const status = await checkForUpdate(options);
+	log(`  Installed engine: ${status.installed ? `v${status.installed}` : "none"}`);
+	log(`  Latest engine:    v${status.latest}`);
+	if (!status.compatible) log(`  ⚠ v${status.latest} needs a newer @jsorm/cli: npm install -D @jsorm/cli@latest`);
+	else if (status.updateAvailable) log(`  Update available. Run: jsorm update`);
+	else log(`  ✓ Up to date`);
+}
 //#endregion
 //#region src/index.ts
 const __filename = fileURLToPath(import.meta.url);
@@ -351,32 +585,54 @@ async function main() {
 		console.log("  configure   Interactive project setup wizard");
 		console.log("  gen         Generate types, model types, and runtime files");
 		console.log("  watch       Watch model files and regenerate on changes");
+		console.log("  update      Install the latest compatible engine and remove old ones");
+		console.log("              (--check: only report, --force: reinstall)");
 		console.log();
 		console.log("Options:");
 		console.log("  --help, -h          Print help");
 		console.log("  --version, -v, -V   Print version");
 		console.log("  --dry-run           Show what would be generated without writing files");
+		console.log();
+		console.log("Environment:");
+		console.log("  JSORM_NO_UPDATE_CHECK=1   Skip engine update checks while an engine is installed");
 		return;
 	}
-	const localEnginePath = getLocalDevEnginePath();
-	if (localEnginePath) {
-		executeEngine(localEnginePath, args);
-		return;
+	try {
+		ensureOwnerOnlyDir(dirname(ENGINES_DIR));
+	} catch (err) {
+		console.error(`  ⚠ Could not restrict ${dirname(ENGINES_DIR)}: ${err instanceof Error ? err.message : err}`);
 	}
-	let enginePath;
+	const resolveOptions = {
+		enginesDir: ENGINES_DIR,
+		binaryName: getEngineBinaryName(),
+		manifestUrl: STABLE_MANIFEST_URL,
+		downloadUrl: STABLE_DOWNLOAD_URL,
+		cliVersion: readVersion(),
+		skipUpdateCheck: process.env.JSORM_NO_UPDATE_CHECK === "1",
+		updateCommand: `${cliRunner(detectPackageManager())} update`,
+		log: console.log
+	};
 	try {
-		enginePath = await resolveEngine({
-			enginesDir: ENGINES_DIR,
-			binaryName: getEngineBinaryName(),
-			manifestUrl: STABLE_MANIFEST_URL,
-			downloadUrl: STABLE_DOWNLOAD_URL,
-			log: console.log
-		});
+		if (args[0] === "update") {
+			const invalid = validateUpdateArgs(args.slice(1));
+			if (invalid) throw new Error(invalid);
+			if (args.includes("--check")) await reportUpdate(resolveOptions);
+			else await updateEngine({
+				...resolveOptions,
+				force: args.includes("--force")
+			});
+			return;
+		}
+		const localEnginePath = getLocalDevEnginePath();
+		if (localEnginePath) {
+			executeEngine(localEnginePath, args);
+			return;
+		}
+		executeEngine(await resolveEngine(resolveOptions), args);
 	} catch (err) {
 		console.error(`  ✖ ${err instanceof Error ? err.message : err}`);
 		process.exit(1);
 	}
-	executeEngine(enginePath, args);
 }
 main();
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jsorm/cli",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "CLI de JSORM",
   "license": "MPL-2.0",
   "repository": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@jsorm/core": "1.0.3"
+    "@jsorm/core": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",