@jsorm/cli 0.1.1 → 0.2.0

package/dist/index.mjs

@@ -1,28 +1,13 @@
 #!/usr/bin/env node
-import { execSync, spawn } from "node:child_process";
-import { createHash, createPublicKey, verify } from "node:crypto";
-import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { execFileSync, spawn } from "node:child_process";
+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";
-//#region src/index.ts
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const VERSION = "0.1.1";
-const ENGINES_DIR = join(homedir(), ".jsorm", "engines");
-const DOWNLOAD_BASE = "https://download.jsorm.dev";
-const STABLE_MANIFEST_URL = `${DOWNLOAD_BASE}/engine/stable/manifest`;
-const STABLE_DOWNLOAD_URL = `${DOWNLOAD_BASE}/engine/download`;
-const EMBEDDED_PUBLIC_KEY_B64 = "pFJ+WOzwsMPbZyvF/bMPB0UNCvuosqFN7Hvjd/qmP78=";
-function getSpkiPublicKey() {
-	const rawKey = Buffer.from(EMBEDDED_PUBLIC_KEY_B64, "base64");
-	const spkiDer = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), rawKey]);
-	return createPublicKey({
-		key: spkiDer,
-		format: "der",
-		type: "spki"
-	});
-}
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+//#region src/platform.ts
 function detectPlatform() {
 	switch (process.platform) {
 		case "linux": return "linux";
@@ -38,6 +23,10 @@ function detectArch() {
 		default: throw new Error(`Unsupported architecture: ${process.arch}`);
 	}
 }
+function getEngineBinaryName() {
+	const platform = detectPlatform();
+	return `jsorm-${platform}-${detectArch()}${platform === "windows" ? ".exe" : ""}`;
+}
 function detectPackageManager() {
 	let dir = process.cwd();
 	for (let i = 0; i < 10; i++) {
@@ -95,37 +84,78 @@ function detectFramework() {
 	}
 	return "none";
 }
-function getEngineBinaryName() {
-	const platform = detectPlatform();
-	return `jsorm-${platform}-${detectArch()}${platform === "windows" ? ".exe" : ""}`;
-}
-function getLocalDevEnginePath() {
-	const debug = join(__dirname, "..", "..", "..", "engine", "target", "debug", "jsorm");
-	if (existsSync(debug)) return debug;
-	const release = join(__dirname, "..", "..", "..", "engine", "target", "release", "jsorm");
-	if (existsSync(release)) return release;
-	return null;
+//#endregion
+//#region src/manifest.ts
+const EMBEDDED_PUBLIC_KEY_B64 = "6AUQMvF7jBV+S8yv9K8hnnoYzIznQw4nf5x5LAuEsfM=";
+function getSpkiPublicKey(rawKeyB64 = EMBEDDED_PUBLIC_KEY_B64) {
+	const rawKey = Buffer.from(rawKeyB64, "base64");
+	const spkiDer = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), rawKey]);
+	return createPublicKey({
+		key: spkiDer,
+		format: "der",
+		type: "spki"
+	});
 }
-function getInstalledEnginePath(binaryName) {
-	const version = detectInstalledVersion(binaryName);
-	if (!version) return null;
-	return join(getVersionDir(version), binaryName);
+function invalid(reason) {
+	return {
+		status: "invalid",
+		reason
+	};
 }
-function verifySignature(data, signature) {
+/**
+* Verifies the envelope `{ success, signature, signed_payload }` and returns
+* the manifest decoded from `signed_payload`, the exact bytes that were signed.
+* The unsigned `envelope.manifest` copy is never trusted.
+*/
+function parseSignedEnvelope(envelope, publicKey) {
+	if (!envelope || typeof envelope !== "object") return invalid("Invalid manifest response");
+	const { success, signature, signed_payload } = envelope;
+	if (success !== true) return invalid("Invalid manifest response");
+	if (typeof signature !== "string" || typeof signed_payload !== "string") return invalid("Manifest signature or signed payload missing. Refusing to continue without signature verification.");
+	const sigBytes = Buffer.from(signature, "base64");
+	if (sigBytes.length !== 64) return invalid(`Invalid signature length: ${sigBytes.length} (expected 64)`);
+	const signedBytes = Buffer.from(signed_payload, "base64");
+	let valid = false;
 	try {
-		const publicKey = getSpkiPublicKey();
-		return verify(null, data, publicKey, signature);
+		valid = verify(null, signedBytes, publicKey, sigBytes);
+	} catch {}
+	if (!valid) return invalid("Manifest signature verification failed. The manifest may have been tampered with.");
+	let manifest;
+	try {
+		manifest = JSON.parse(signedBytes.toString("utf-8"));
 	} catch {
-		return false;
+		return invalid("Signed manifest is not valid JSON");
 	}
+	if (typeof manifest?.version !== "string" || !manifest.targets || typeof manifest.targets !== "object") return invalid("Invalid manifest format");
+	return {
+		status: "ok",
+		manifest
+	};
 }
-function verifyManifest(signedPayload, signature) {
-	if (signature.length !== 64) {
-		console.log(`  ✖ Invalid signature length: ${signature.length} (expected 64)`);
-		return false;
+async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
+	let res;
+	try {
+		res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+	} catch (err) {
+		return {
+			status: "unreachable",
+			reason: `Manifest fetch error: ${err instanceof Error ? err.message : err}`
+		};
 	}
-	return verifySignature(signedPayload, signature);
+	if (!res.ok) return {
+		status: "unreachable",
+		reason: `Manifest fetch failed: ${res.status} ${res.statusText}`
+	};
+	let envelope;
+	try {
+		envelope = await res.json();
+	} catch {
+		return invalid("Invalid manifest response");
+	}
+	return parseSignedEnvelope(envelope, publicKey);
 }
+//#endregion
+//#region src/version.ts
 function compareVersions(a, b) {
 	const pa = a.split(".").map(Number);
 	const pb = b.split(".").map(Number);
@@ -137,153 +167,287 @@ function compareVersions(a, b) {
 	}
 	return 0;
 }
-function detectInstalledVersion(target) {
-	if (!existsSync(ENGINES_DIR)) return null;
-	const dirs = readdirSync(ENGINES_DIR).filter((d) => d.startsWith("v")).sort((a, b) => {
-		const va = a.slice(1);
-		return compareVersions(b.slice(1), va);
+/** 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}`);
+}
+/** 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
 	});
-	for (const dir of dirs) {
-		const binPath = join(ENGINES_DIR, dir, target);
-		if (existsSync(binPath)) return dir.slice(1);
-	}
-	return null;
+	return removed;
 }
-function getVersionDir(version) {
-	return join(ENGINES_DIR, `v${version}`);
+async function sha256File(filePath) {
+	const hash = createHash("sha256");
+	await pipeline(createReadStream(filePath), hash);
+	return hash.digest("hex");
 }
-async function downloadManifest() {
+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 {
-		console.log(`  Fetching manifest from ${STABLE_MANIFEST_URL}...`);
-		const manifestRes = await fetch(STABLE_MANIFEST_URL, { signal: AbortSignal.timeout(1e4) });
-		if (!manifestRes.ok) {
-			console.log(`  ✖ Manifest fetch failed: ${manifestRes.status} ${manifestRes.statusText}`);
-			return null;
-		}
-		const envelope = await manifestRes.json();
-		if (!envelope.success || !envelope.manifest) {
-			console.log(`  ✖ Invalid manifest response`);
-			return null;
-		}
-		const manifest = envelope.manifest;
-		if (!manifest.targets || typeof manifest.targets !== "object") {
-			console.log(`  ✖ Invalid manifest format`);
-			return null;
-		}
-		if (envelope.signature && envelope.signed_payload) {
-			const signedBytes = Buffer.from(envelope.signed_payload, "base64");
-			const sigBytes = Buffer.from(envelope.signature, "base64");
-			console.log(`  Verifying manifest signature...`);
-			if (!verifyManifest(signedBytes, sigBytes)) {
-				console.error(`  ✖ Manifest signature verification failed.`);
-				console.error(`  The manifest may have been tampered with.`);
-				process.exit(1);
-			}
-			console.log(`  ✓ Manifest signature verified`);
-		} else {
-			console.error(`  ✖ Manifest signature or signed payload missing.`);
-			console.error(`  Refusing to continue without signature verification.`);
-			return null;
-		}
-		console.log(`  ✓ Manifest v${manifest.version} (${Object.keys(manifest.targets).length} targets)`);
-		return {
-			manifest,
-			stableVersion: manifest.version
-		};
+		execFileSync("tar", [
+			"-xzf",
+			tarPath,
+			"-C",
+			destDir
+		], { stdio: "pipe" });
 	} catch (err) {
-		console.log(`  ✖ Manifest fetch error: ${err instanceof Error ? err.message : err}`);
-		return null;
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`tar extraction failed: ${msg}`);
 	}
 }
-async function sha256File(filePath) {
-	return new Promise((resolve, reject) => {
-		const hash = createHash("sha256");
-		const stream = createReadStream(filePath);
-		stream.on("data", (data) => hash.update(data));
-		stream.on("end", () => resolve(hash.digest("hex")));
-		stream.on("error", reject);
-	});
-}
-async function downloadAndExtractEngine(url, destDir, binaryName, expectedSha256) {
-	const tempDir = join(ENGINES_DIR, ".tmp");
-	mkdirSync(tempDir, { recursive: true });
-	const tarPath = join(tempDir, `${binaryName}.tar.gz`);
+/**
+* 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, log = () => {} } = options;
+	mkdirSync(enginesDir, { recursive: true });
+	const tempDir = mkdtempSync(join(enginesDir, ".tmp-"));
 	try {
-		console.log(`  Downloading from ${url}...`);
-		const res = await fetch(url, { signal: AbortSignal.timeout(6e4) });
-		if (!res.ok) {
-			console.log(`  ✖ Download failed: ${res.status} ${res.statusText}`);
-			return false;
-		}
-		const fileStream = createWriteStream(tarPath);
-		if (res.body) {
-			const reader = res.body.getReader();
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				fileStream.write(value);
-			}
-		}
-		fileStream.end();
-		await new Promise((resolve, reject) => {
-			fileStream.on("finish", resolve);
-			fileStream.on("error", reject);
-		});
-		const tarSize = statSync(tarPath).size;
-		console.log(`  ✓ Downloaded ${(tarSize / 1024).toFixed(1)} KB`);
-		console.log(`  Verifying checksum...`);
+		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) {
-			console.error(`  ✖ Checksum mismatch!`);
-			console.error(`  Expected: ${expectedSha256}`);
-			console.error(`  Got:      ${hash}`);
-			unlinkSync(tarPath);
-			return false;
-		}
-		console.log(`  ✓ Checksum verified`);
-		console.log(`  Extracting...`);
-		mkdirSync(destDir, { recursive: true });
-		await extractTarGz(tarPath, destDir);
-		const extractedPath = join(destDir, "jsorm");
+		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);
-		if (existsSync(extractedPath) && extractedPath !== destPath) renameSync(extractedPath, destPath);
-		if (process.platform !== "win32") chmodSync(destPath, 493);
-		console.log(`  ✓ Engine installed: ${destPath}`);
-		return true;
-	} catch (err) {
-		console.log(`  ✖ Extract error: ${err instanceof Error ? err.message : err}`);
-		return false;
+		mkdirSync(destDir, { recursive: true });
+		renameSync(extractedPath, destPath);
+		log(`  ✓ Engine installed: ${destPath}`);
+		return destPath;
 	} finally {
-		try {
-			unlinkSync(tarPath);
-		} catch {}
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
 	}
 }
-async function extractTarGz(tarPath, destDir) {
+//#endregion
+//#region src/resolve.ts
+const DAY_MS = 864e5;
+const LAST_CHECK_FILE = ".last-check";
+function readLastCheck(enginesDir) {
 	try {
-		execSync(`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}`);
+		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 result.manifest;
+}
+/**
+* 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. Only engines of
+* the CLI's release line are used. 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.
+*/
+async function resolveEngine(options) {
+	const { enginesDir, binaryName, downloadUrl, cliVersion, log = () => {}, checkIntervalMs = DAY_MS, skipUpdateCheck = false, force = false, requireLiveCheck = false, now = Date.now } = options;
+	const compatible = (version) => isCompatibleEngine(cliVersion, version);
+	const installedVer = detectInstalledVersion(enginesDir, binaryName, compatible);
+	const installedPath = installedVer ? join(getVersionDir(enginesDir, installedVer), binaryName) : null;
+	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 manifest = await fetchTrustedManifest(options);
+	if ("unreachable" in manifest) {
+		if (installedPath && !requireLiveCheck) {
+			log(`  ⚠ ${manifest.unreachable}`);
+			log(`  ⚠ Using installed engine v${installedVer} without checking for updates`);
+			return installedPath;
+		}
+		throw new Error(`${manifest.unreachable}\n  ✖ Failed to fetch manifest.`);
+	}
+	writeLastCheck(enginesDir, now());
+	const stableVersion = manifest.version;
+	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 && !force && compareVersions(stableVersion, installedVer) <= 0) {
+		log(`  ✓ Engine v${installedVer} is up to date (stable: v${stableVersion})`);
+		return installedPath;
+	}
+	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}`);
+	const dl = await dlRes.json();
+	if (dl.version !== stableVersion) throw new Error(`Version mismatch: server returned v${dl.version}, manifest says v${stableVersion}`);
+	if (dl.sha256 !== target.sha256) throw new Error(`SHA-256 mismatch: server returned ${String(dl.sha256).slice(0, 16)}, manifest says ${target.sha256.slice(0, 16)}`);
+	return installEngine({
+		url: dl.url,
+		enginesDir,
+		version: stableVersion,
+		binaryName,
+		expectedSha256: target.sha256,
+		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 manifest = await fetchTrustedManifest(options);
+	if ("unreachable" in manifest) throw new Error(manifest.unreachable);
+	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);
+const __dirname = dirname(__filename);
+const ENGINES_DIR = join(homedir(), ".jsorm", "engines");
+const DOWNLOAD_BASE = "https://download.jsorm.dev";
+const STABLE_MANIFEST_URL = `${DOWNLOAD_BASE}/engine/stable/manifest`;
+const STABLE_DOWNLOAD_URL = `${DOWNLOAD_BASE}/engine/download`;
+function readVersion() {
+	try {
+		return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+	} catch {
+		return "unknown";
 	}
 }
+function getLocalDevEnginePath() {
+	const debug = join(__dirname, "..", "..", "..", "engine", "target", "debug", "jsorm");
+	if (existsSync(debug)) return debug;
+	const release = join(__dirname, "..", "..", "..", "engine", "target", "release", "jsorm");
+	if (existsSync(release)) return release;
+	return null;
+}
 function executeEngine(enginePath, args) {
-	const projectDir = process.cwd();
-	const framework = detectFramework();
-	const pm = detectPackageManager();
-	const runtime = detectRuntime();
 	const engineArgs = [
 		...args,
 		"--framework",
-		framework,
+		detectFramework(),
 		"--pm",
-		pm,
+		detectPackageManager(),
 		"--runtime",
-		runtime
+		detectRuntime()
 	];
 	const child = spawn(enginePath, engineArgs, {
 		stdio: "inherit",
-		cwd: projectDir
+		cwd: process.cwd()
 	});
 	child.on("error", (err) => {
 		console.error(`  ✖ Failed to start engine: ${err.message}`);
@@ -295,8 +459,8 @@ function executeEngine(enginePath, args) {
 }
 async function main() {
 	const args = process.argv.slice(2);
-	if (args.includes("--version") || args.includes("-v")) {
-		console.log(VERSION);
+	if (args.includes("--version") || args.includes("-v") || args.includes("-V")) {
+		console.log(readVersion());
 		return;
 	}
 	if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -305,64 +469,55 @@ async function main() {
 			executeEngine(localEnginePath, args);
 			return;
 		}
-		console.log(`jsorm ${VERSION}`);
+		console.log(`jsorm ${readVersion()}`);
 		console.log("JSORM CLI — TypeScript ORM code generation");
 		console.log();
 		console.log("Commands:");
 		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    Print version");
-		console.log("  --dry-run        Show what would be generated without writing files");
-		return;
-	}
-	const localEnginePath = getLocalDevEnginePath();
-	if (localEnginePath) {
-		executeEngine(localEnginePath, args);
-		return;
-	}
-	const binaryName = getEngineBinaryName();
-	const result = await downloadManifest();
-	if (!result) {
-		console.error(`  ✖ Failed to fetch manifest.`);
-		process.exit(1);
-	}
-	const { manifest, stableVersion } = result;
-	const target = manifest.targets[binaryName];
-	if (!target) {
-		console.error(`  ✖ No binary available for ${binaryName}`);
-		console.error(`  Available: ${Object.keys(manifest.targets).join(", ")}`);
-		process.exit(1);
-	}
-	const installedPath = getInstalledEnginePath(binaryName);
-	const installedVer = installedPath ? detectInstalledVersion(binaryName) : null;
-	if (installedVer && compareVersions(stableVersion, installedVer) <= 0) {
-		console.log(`  ✓ Engine v${installedVer} is up to date (stable: v${stableVersion})`);
-		executeEngine(installedPath, args);
+		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;
 	}
-	if (installedVer) console.log(`  Update available: v${installedVer} → v${stableVersion}`);
-	else console.log(`  Engine not found. Downloading v${stableVersion}...`);
-	console.log(`  Requesting download URL...`);
-	const dlRes = await fetch(`${STABLE_DOWNLOAD_URL}/${binaryName}`, { signal: AbortSignal.timeout(1e4) });
-	if (!dlRes.ok) {
-		console.error(`  ✖ Download request failed: ${dlRes.status} ${dlRes.statusText}`);
-		process.exit(1);
-	}
-	const dl = await dlRes.json();
-	if (dl.version !== stableVersion) {
-		console.error(`  ✖ Version mismatch: server returned v${dl.version}, manifest says v${stableVersion}`);
-		process.exit(1);
-	}
-	if (dl.sha256 !== target.sha256) {
-		console.error(`  ✖ SHA-256 mismatch: server returned ${dl.sha256.slice(0, 16)}, manifest says ${target.sha256.slice(0, 16)}`);
+	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",
+		log: console.log
+	};
+	try {
+		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);
 	}
-	const destDir = getVersionDir(stableVersion);
-	if (await downloadAndExtractEngine(dl.url, destDir, binaryName, target.sha256)) executeEngine(join(destDir, binaryName), args);
 }
 main();
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jsorm/cli",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI de JSORM",
   "license": "MPL-2.0",
   "repository": {
@@ -20,7 +20,7 @@
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "bin": {
-    "@jsorm/cli": "./dist/index.mjs"
+    "jsorm": "./dist/index.mjs"
   },
   "exports": {
     ".": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@jsorm/core": "1.0.2"
+    "@jsorm/core": "1.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",