@jsorm/cli 0.1.3 → 0.2.0

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";
@@ -155,7 +155,7 @@ async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
 	return parseSignedEnvelope(envelope, publicKey);
 }
 //#endregion
-//#region src/install.ts
+//#region src/version.ts
 function compareVersions(a, b) {
 	const pa = a.split(".").map(Number);
 	const pb = b.split(".").map(Number);
@@ -167,15 +167,37 @@ function compareVersions(a, b) {
 	}
 	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}`);
 }
-/** 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;
+/** 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");
@@ -241,38 +263,81 @@ async function installEngine(options) {
 }
 //#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 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. 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. 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, manifestUrl, downloadUrl, publicKey = getSpkiPublicKey(), log = () => {} } = options;
-	const installedVer = detectInstalledVersion(enginesDir, binaryName);
+	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;
-	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 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(`${result.reason}\n  ✖ Failed to fetch manifest.`);
+		throw new Error(`${manifest.unreachable}\n  ✖ Failed to fetch manifest.`);
 	}
-	if (result.status === "invalid") throw new Error(result.reason);
-	const { manifest } = result;
+	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 (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 (!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}`);
@@ -288,6 +353,66 @@ async function resolveEngine(options) {
 		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);
@@ -351,32 +476,48 @@ 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;
-	}
-	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",
+		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.0",
   "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.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",