nebula-ai 0.0.8 → 0.0.9

package/bin/nebula-ai.js

@@ -38,26 +38,14 @@
 //      so keep the old key valid (publish one more release with it)
 //      long enough for the dist-tag to catch up, then delete the old
 //      key material.
-
 import { spawn, spawnSync } from "node:child_process";
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
-import {
-  chmodSync,
-  createWriteStream,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  realpathSync,
-  renameSync,
-  rmSync,
-  statSync,
-} from "node:fs";
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
-
 // The public half of the ed25519 key that signs `checksums.json`. The
 // private half lives only in the `NEBULA_AI_SIGNING_PRIVATE_KEY` GitHub
 // Actions secret.
@@ -65,239 +53,231 @@ const EMBEDDED_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MCowBQYDK2VwAyEAd8QFvCTSMY0HmSsJgL6jtFQas00WedvSZhkc9bxdAl0=
 -----END PUBLIC KEY-----
 `;
-
 // Stamped by `scripts/publish/prepare.mjs` at wrapper staging time with
 // the channel-appropriate base URL (dev vs prod). The `__NEBULA_AI_…__`
 // sentinel lets us keep the checked-in source runnable for local tests
 // without pointing at any real host.
 const STAMPED_DOWNLOAD_BASE_URL = "https://cli-assets.nebula-dev.ai/production";
-const DOWNLOAD_BASE_URL =
-  process.env.NEBULA_AI_DOWNLOAD_BASE ?? STAMPED_DOWNLOAD_BASE_URL;
-
+const DOWNLOAD_BASE_URL = process.env.NEBULA_AI_DOWNLOAD_BASE ?? STAMPED_DOWNLOAD_BASE_URL;
 const SUPPORTED_PLATFORMS = new Set([
-  "darwin-arm64",
-  "darwin-x64",
-  "linux-x64",
-  "linux-arm64",
-  "win32-x64",
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-x64",
+    "linux-arm64",
+    "win32-x64",
 ]);
-
 // ─── update-check constants ────────────────────────────────────────────────
-
 const UPDATE_CHECK_TTL = 4 * 60 * 60 * 1000; // 4 hours
-
 // ─── pure helpers (exported for tests) ─────────────────────────────────────
-
 /**
  * Return the path to the update-check cache file. Lives at the top of the
  * cache directory (NOT under a version-specific subdirectory) so it persists
  * across version upgrades.
  */
 export function getUpdateCheckCachePath() {
-  const base =
-    process.env.NEBULA_AI_CACHE_DIR ||
-    (process.platform === "win32"
-      ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
-      : process.env.XDG_CACHE_HOME || join(homedir(), ".cache"));
-  return join(base, "nebula-ai", "update-check.json");
+    const base = process.env.NEBULA_AI_CACHE_DIR ||
+        (process.platform === "win32"
+            ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
+            : process.env.XDG_CACHE_HOME || join(homedir(), ".cache"));
+    return join(base, "nebula-ai", "update-check.json");
 }
-
 /**
  * Determine the release channel from a version string.
  * Dev versions look like `x.y.z-dev.YYYYMMDDHHMMSS.sha`.
  */
 export function getChannel(version) {
-  return version.includes("-dev.") ? "dev" : "prod";
+    return version.includes("-dev.") ? "dev" : "prod";
 }
-
 /**
  * Return true if `latest` is a newer semver than `current` (prod), or simply
  * different (dev — timestamps are monotonically increasing).
  */
 export function isNewerVersion(latest, current) {
-  if (current.includes("-dev.")) {
-    return latest !== current;
-  }
-  // Strip any prerelease suffix (e.g., "-beta.1") before parsing.
-  const clean = (v) => v.replace(/-.*$/, "");
-  const [a1, a2, a3] = clean(latest).split(".").map(Number);
-  const [b1, b2, b3] = clean(current).split(".").map(Number);
-  if (a1 !== b1) return a1 > b1;
-  if (a2 !== b2) return a2 > b2;
-  if (a3 !== b3) return a3 > b3;
-  // Same numeric version: a stable release is newer than a prerelease
-  // (e.g. 1.0.0 is newer than 1.0.0-beta.1).
-  if (current.includes("-") && !latest.includes("-")) return true;
-  return false;
+    if (current.includes("-dev.")) {
+        return latest !== current;
+    }
+    // Strip any prerelease suffix (e.g., "-beta.1") before parsing.
+    const clean = (v) => v.replace(/-.*$/, "");
+    const [a1, a2, a3] = clean(latest).split(".").map(Number);
+    const [b1, b2, b3] = clean(current).split(".").map(Number);
+    if (a1 !== b1)
+        return a1 > b1;
+    if (a2 !== b2)
+        return a2 > b2;
+    if (a3 !== b3)
+        return a3 > b3;
+    // Same numeric version: a stable release is newer than a prerelease
+    // (e.g. 1.0.0 is newer than 1.0.0-beta.1).
+    if (current.includes("-") && !latest.includes("-"))
+        return true;
+    return false;
 }
-
 /**
  * Return true when the update check should be suppressed entirely.
  */
 export function isUpdateCheckDisabled() {
-  return (
-    process.env.NEBULA_AI_NO_UPDATE_CHECK === "1" ||
-    process.env.NEBULA_AI_NO_UPDATE_CHECK === "true" ||
-    process.env.CI === "true" ||
-    !process.stderr.isTTY
-  );
+    return (process.env.NEBULA_AI_NO_UPDATE_CHECK === "1" ||
+        process.env.NEBULA_AI_NO_UPDATE_CHECK === "true" ||
+        process.env.CI === "true" ||
+        !process.stderr.isTTY);
 }
-
 /**
  * Return true when running under `npx` (which always fetches the latest
  * wrapper, making the check redundant).
  */
 export function isNpx() {
-  return process.env.npm_command === "exec";
+    return process.env.npm_command === "exec";
 }
-
 export function sha256HexSync(buffer) {
-  return createHash("sha256").update(buffer).digest("hex");
+    return createHash("sha256").update(buffer).digest("hex");
 }
-
 /**
  * Verify a signed checksums.json blob and return the parsed manifest.
  * Throws if the signature is invalid or the manifest is malformed.
  */
 export function verifyManifest(manifestBytes, signatureBase64, publicKeyPem) {
-  const pubKey = createPublicKey(publicKeyPem);
-  if (pubKey.asymmetricKeyType !== "ed25519") {
-    throw new Error(
-      `embedded public key is not ed25519 (got ${pubKey.asymmetricKeyType})`,
-    );
-  }
-  const sig = Buffer.from(signatureBase64.trim(), "base64");
-  const ok = cryptoVerify(null, manifestBytes, pubKey, sig);
-  if (!ok) {
-    throw new Error("manifest signature verification failed");
-  }
-  const manifest = JSON.parse(manifestBytes.toString("utf8"));
-  if (!manifest || typeof manifest !== "object") {
-    throw new Error("manifest is not a JSON object");
-  }
-  if (manifest.algorithm !== "sha256") {
-    throw new Error(
-      `unsupported manifest algorithm: ${manifest.algorithm ?? "(missing)"}`,
-    );
-  }
-  if (!manifest.binaries || typeof manifest.binaries !== "object") {
-    throw new Error("manifest is missing the `binaries` map");
-  }
-  return manifest;
+    const pubKey = createPublicKey(publicKeyPem);
+    if (pubKey.asymmetricKeyType !== "ed25519") {
+        throw new Error(`embedded public key is not ed25519 (got ${pubKey.asymmetricKeyType})`);
+    }
+    const sig = Buffer.from(signatureBase64.trim(), "base64");
+    const ok = cryptoVerify(null, manifestBytes, pubKey, sig);
+    if (!ok) {
+        throw new Error("manifest signature verification failed");
+    }
+    const manifest = JSON.parse(manifestBytes.toString("utf8"));
+    if (!manifest || typeof manifest !== "object") {
+        throw new Error("manifest is not a JSON object");
+    }
+    const m = manifest;
+    if (m.algorithm !== "sha256") {
+        throw new Error(`unsupported manifest algorithm: ${m.algorithm ?? "(missing)"}`);
+    }
+    if (!m.binaries || typeof m.binaries !== "object") {
+        throw new Error("manifest is missing the `binaries` map");
+    }
+    return manifest;
 }
-
 /**
  * Given a verified manifest + a platform key + the bytes of a downloaded
  * binary, confirm the binary's SHA-256 matches the manifest entry. Throws
  * on mismatch.
  */
 export function assertBinaryMatchesManifest(manifest, platformKey, binName, binaryBuffer) {
-  const entryKey = `${platformKey}/${binName}`;
-  const expected = manifest.binaries[entryKey];
-  if (typeof expected !== "string") {
-    throw new Error(`manifest has no entry for ${entryKey}`);
-  }
-  const actual = sha256HexSync(binaryBuffer);
-  if (actual !== expected) {
-    throw new Error(
-      `binary digest mismatch for ${entryKey}\n  expected: ${expected}\n  actual:   ${actual}`,
-    );
-  }
+    const entryKey = `${platformKey}/${binName}`;
+    const expected = manifest.binaries[entryKey];
+    if (typeof expected !== "string") {
+        throw new Error(`manifest has no entry for ${entryKey}`);
+    }
+    const actual = sha256HexSync(binaryBuffer);
+    if (actual !== expected) {
+        throw new Error(`binary digest mismatch for ${entryKey}\n  expected: ${expected}\n  actual:   ${actual}`);
+    }
 }
-
 // ─── runtime (only runs when this file is the entrypoint) ─────────────────
-
 const platformKey = `${process.platform}-${process.arch}`;
 const binName = process.platform === "win32" ? "nebula-ai.exe" : "nebula-ai";
-
 async function readVersion() {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const pkgPath = join(here, "..", "package.json");
-  const raw = await readFile(pkgPath, "utf8");
-  const pkg = JSON.parse(raw);
-  if (typeof pkg.version !== "string") {
-    throw new Error("nebula-ai: package.json is missing a version field");
-  }
-  return pkg.version;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(here, "..", "package.json");
+    const raw = await readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.version !== "string") {
+        throw new Error("nebula-ai: package.json is missing a version field");
+    }
+    return pkg.version;
+}
+function getCacheBaseDir() {
+    // Respect XDG_CACHE_HOME on linux, honor LOCALAPPDATA on windows, default
+    // to ~/.cache elsewhere. Keeps behavior predictable across platforms.
+    const base = process.env.NEBULA_AI_CACHE_DIR ||
+        (process.platform === "win32"
+            ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
+            : process.env.XDG_CACHE_HOME || join(homedir(), ".cache"));
+    return join(base, "nebula-ai");
 }
-
 function getCacheDir(version) {
-  // Respect XDG_CACHE_HOME on linux, honor LOCALAPPDATA on windows, default
-  // to ~/.cache elsewhere. Keeps behavior predictable across platforms.
-  const base =
-    process.env.NEBULA_AI_CACHE_DIR ||
-    (process.platform === "win32"
-      ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
-      : process.env.XDG_CACHE_HOME || join(homedir(), ".cache"));
-  return join(base, "nebula-ai", `v${version}`, platformKey);
+    return join(getCacheBaseDir(), `v${version}`, platformKey);
+}
+/**
+ * Remove cached binaries for versions other than the current one.
+ * Only touches directories whose names are `v<semver>` — leaves
+ * non-version entries (e.g. `boxlite/`, `update-check.json`) untouched.
+ * Best-effort: individual removal failures are silently ignored so one
+ * stuck directory doesn't prevent the rest from being cleaned up.
+ */
+const VERSION_CACHE_DIR_RE = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function cleanupOldVersions(currentVersion) {
+    try {
+        const base = getCacheBaseDir();
+        const currentDir = `v${currentVersion}`;
+        for (const entry of readdirSync(base, { withFileTypes: true })) {
+            if (entry.isDirectory() &&
+                VERSION_CACHE_DIR_RE.test(entry.name) &&
+                entry.name !== currentDir) {
+                try {
+                    rmSync(join(base, entry.name), { recursive: true, force: true });
+                }
+                catch {
+                    // best-effort — skip this entry and continue
+                }
+            }
+        }
+    }
+    catch {
+        // Parent directory may not exist yet, or permissions issue — ignore.
+    }
 }
-
 async function fetchManifest(version) {
-  const manifestUrl = `${DOWNLOAD_BASE_URL}/v${version}/checksums.json`;
-  const sigUrl = `${DOWNLOAD_BASE_URL}/v${version}/checksums.json.sig`;
-  const [manifestRes, sigRes] = await Promise.all([
-    fetch(manifestUrl, { redirect: "follow" }),
-    fetch(sigUrl, { redirect: "follow" }),
-  ]);
-  if (!manifestRes.ok) {
-    throw new Error(
-      `manifest download failed: ${manifestRes.status} ${manifestRes.statusText}\n  url: ${manifestUrl}`,
-    );
-  }
-  if (!sigRes.ok) {
-    throw new Error(
-      `signature download failed: ${sigRes.status} ${sigRes.statusText}\n  url: ${sigUrl}`,
-    );
-  }
-  const manifestBytes = Buffer.from(await manifestRes.arrayBuffer());
-  const signatureBase64 = await sigRes.text();
-  return verifyManifest(manifestBytes, signatureBase64, EMBEDDED_PUBLIC_KEY_PEM);
+    const manifestUrl = `${DOWNLOAD_BASE_URL}/v${version}/checksums.json`;
+    const sigUrl = `${DOWNLOAD_BASE_URL}/v${version}/checksums.json.sig`;
+    const [manifestRes, sigRes] = await Promise.all([
+        fetch(manifestUrl, { redirect: "follow" }),
+        fetch(sigUrl, { redirect: "follow" }),
+    ]);
+    if (!manifestRes.ok) {
+        throw new Error(`manifest download failed: ${manifestRes.status} ${manifestRes.statusText}\n  url: ${manifestUrl}`);
+    }
+    if (!sigRes.ok) {
+        throw new Error(`signature download failed: ${sigRes.status} ${sigRes.statusText}\n  url: ${sigUrl}`);
+    }
+    const manifestBytes = Buffer.from(await manifestRes.arrayBuffer());
+    const signatureBase64 = await sigRes.text();
+    return verifyManifest(manifestBytes, signatureBase64, EMBEDDED_PUBLIC_KEY_PEM);
 }
-
 async function downloadBinary(version, destPath) {
-  const url = `${DOWNLOAD_BASE_URL}/v${version}/${platformKey}/${binName}`;
-
-  process.stderr.write(
-    `nebula-ai: downloading runtime for your platform (one-time setup)…\n`,
-  );
-
-  const manifest = await fetchManifest(version);
-
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok || !res.body) {
-    throw new Error(
-      `download failed: ${res.status} ${res.statusText}\n  url: ${url}`,
-    );
-  }
-
-  mkdirSync(dirname(destPath), { recursive: true });
-
-  // Stage under a unique temp name in the SAME directory as destPath so the
-  // final renameSync is always an intra-filesystem move. tmpdir() can live on
-  // a different mount (tmpfs on linux, user-local tmp on some sandboxes) and
-  // rename across mounts fails with EXDEV.
-  const tmpPath = join(
-    dirname(destPath),
-    `.nebula-ai-${version}-${process.pid}-${Date.now()}.partial`,
-  );
-  try {
-    await pipeline(res.body, createWriteStream(tmpPath));
-    const tmpBytes = await readFile(tmpPath);
-    assertBinaryMatchesManifest(manifest, platformKey, binName, tmpBytes);
-    if (process.platform !== "win32") chmodSync(tmpPath, 0o755);
-    renameSync(tmpPath, destPath);
-  } catch (err) {
+    const url = `${DOWNLOAD_BASE_URL}/v${version}/${platformKey}/${binName}`;
+    process.stderr.write(`nebula-ai: downloading runtime for your platform (one-time setup)…\n`);
+    const manifest = await fetchManifest(version);
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok || !res.body) {
+        throw new Error(`download failed: ${res.status} ${res.statusText}\n  url: ${url}`);
+    }
+    mkdirSync(dirname(destPath), { recursive: true });
+    // Stage under a unique temp name in the SAME directory as destPath so the
+    // final renameSync is always an intra-filesystem move. tmpdir() can live on
+    // a different mount (tmpfs on linux, user-local tmp on some sandboxes) and
+    // rename across mounts fails with EXDEV.
+    const tmpPath = join(dirname(destPath), `.nebula-ai-${version}-${process.pid}-${Date.now()}.partial`);
     try {
-      rmSync(tmpPath, { force: true });
-    } catch {
-      // best-effort cleanup
+        await pipeline(res.body, createWriteStream(tmpPath));
+        const tmpBytes = await readFile(tmpPath);
+        assertBinaryMatchesManifest(manifest, platformKey, binName, tmpBytes);
+        if (process.platform !== "win32")
+            chmodSync(tmpPath, 0o755);
+        renameSync(tmpPath, destPath);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+        throw err;
     }
-    throw err;
-  }
 }
-
 // ─── update-check runtime ───────────────────────────────────────────────────
-
 /**
  * If the cached check result is stale (or missing), spawn a detached
  * background process to fetch the latest version from the npm registry and
@@ -305,19 +285,18 @@ async function downloadBinary(version, destPath) {
  * launcher alive.
  */
 function maybeSpawnUpdateCheck(currentVersion) {
-  const cachePath = getUpdateCheckCachePath();
-
-  // Skip if the cache is still fresh (stat is cheaper than read + parse).
-  try {
-    if (Date.now() - statSync(cachePath).mtimeMs < UPDATE_CHECK_TTL) return;
-  } catch {
-    // File missing — fall through to spawn.
-  }
-
-  const channel = getChannel(currentVersion);
-  const distTag = channel === "dev" ? "dev" : "latest";
-
-  const script = `
+    const cachePath = getUpdateCheckCachePath();
+    // Skip if the cache is still fresh (stat is cheaper than read + parse).
+    try {
+        if (Date.now() - statSync(cachePath).mtimeMs < UPDATE_CHECK_TTL)
+            return;
+    }
+    catch {
+        // File missing — fall through to spawn.
+    }
+    const channel = getChannel(currentVersion);
+    const distTag = channel === "dev" ? "dev" : "latest";
+    const script = `
     const fs = require("node:fs");
     const path = require("node:path");
     const cachePath = ${JSON.stringify(cachePath)};
@@ -338,130 +317,112 @@ function maybeSpawnUpdateCheck(currentVersion) {
       })
       .catch(() => {});
   `;
-
-  try {
-    const child = spawn(process.execPath, ["-e", script], {
-      detached: true,
-      stdio: "ignore",
-    });
-    child.unref();
-  } catch {
-    // If we cannot spawn, silently skip.
-  }
+    try {
+        const child = spawn(process.execPath, ["-e", script], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        // If we cannot spawn, silently skip.
+    }
 }
-
 /**
  * Read the cached check result (written by a *previous* invocation's
  * background process) and print a one-line update notification to stderr
  * if a newer version is available.
  */
 function maybeShowUpdateNotification(currentVersion) {
-  try {
-    const raw = readFileSync(getUpdateCheckCachePath(), "utf8");
-    const cached = JSON.parse(raw);
-    if (cached.latest && isNewerVersion(cached.latest, currentVersion)) {
-      const cmd = currentVersion.includes("-dev.")
-        ? "npm install -g nebula-ai@dev"
-        : "npm install -g nebula-ai";
-      process.stderr.write(
-        `\nnebula-ai: update available ${currentVersion} \u2192 ${cached.latest}\n` +
-          `  Run: ${cmd}\n`,
-      );
-    }
-  } catch {
-    // Cache missing or corrupt — do nothing.
-  }
+    try {
+        const raw = readFileSync(getUpdateCheckCachePath(), "utf8");
+        const cached = JSON.parse(raw);
+        if (cached.latest && isNewerVersion(cached.latest, currentVersion)) {
+            const cmd = currentVersion.includes("-dev.")
+                ? "npm install -g nebula-ai@dev"
+                : "npm install -g nebula-ai";
+            process.stderr.write(`\nnebula-ai: update available ${currentVersion} \u2192 ${cached.latest}\n` +
+                `  Run: ${cmd}\n`);
+        }
+    }
+    catch {
+        // Cache missing or corrupt — do nothing.
+    }
 }
-
 async function main() {
-  if (DOWNLOAD_BASE_URL.includes("__NEBULA_AI_DOWNLOAD_BASE__")) {
-    console.error(
-      "nebula-ai: unable to download — this installation appears to be incomplete.\n" +
-        "\n" +
-        "To fix this, reinstall nebula-ai:\n" +
-        "  npm install -g nebula-ai\n" +
-        "\n" +
-        "If the problem persists, please open an issue:\n" +
-        "  https://github.com/thirdweb-dev/nebula-cli/issues",
-    );
-    process.exit(1);
-  }
-
-  if (!SUPPORTED_PLATFORMS.has(platformKey)) {
-    console.error(
-      `nebula-ai: your platform (${platformKey}) is not yet supported.\n` +
-        `\n` +
-        `Supported platforms: ${[...SUPPORTED_PLATFORMS].join(", ")}.\n` +
-        `\n` +
-        `Please open an issue to request support:\n` +
-        `  https://github.com/thirdweb-dev/nebula-cli/issues`,
-    );
-    process.exit(1);
-  }
-
-  let version;
-  try {
-    version = await readVersion();
-  } catch (err) {
-    console.error(
-      `nebula-ai: unable to determine the installed version.\n` +
-        `\n` +
-        `This usually means the installation is corrupted. To fix this, reinstall:\n` +
-        `  npm install -g nebula-ai`,
-    );
-    process.exit(1);
-  }
-
-  const cacheDir = getCacheDir(version);
-  const binaryPath = join(cacheDir, binName);
-
-  if (!existsSync(binaryPath)) {
+    if (DOWNLOAD_BASE_URL.includes("__NEBULA_AI_DOWNLOAD_BASE__")) {
+        console.error("nebula-ai: unable to download — this installation appears to be incomplete.\n" +
+            "\n" +
+            "To fix this, reinstall nebula-ai:\n" +
+            "  npm install -g nebula-ai\n" +
+            "\n" +
+            "If the problem persists, please open an issue:\n" +
+            "  https://github.com/thirdweb-dev/nebula-cli/issues");
+        process.exit(1);
+    }
+    if (!SUPPORTED_PLATFORMS.has(platformKey)) {
+        console.error(`nebula-ai: your platform (${platformKey}) is not yet supported.\n` +
+            `\n` +
+            `Supported platforms: ${[...SUPPORTED_PLATFORMS].join(", ")}.\n` +
+            `\n` +
+            `Please open an issue to request support:\n` +
+            `  https://github.com/thirdweb-dev/nebula-cli/issues`);
+        process.exit(1);
+    }
+    let version;
     try {
-      await downloadBinary(version, binaryPath);
-    } catch (err) {
-      console.error(
-        `nebula-ai: could not download the runtime.\n` +
-          `\n` +
-          `This is usually a network issue. Please check your internet connection and try again.\n` +
-          `\n` +
-          `If the problem persists:\n` +
-          `  • Clear the download cache: rm -rf ${getCacheDir(version)}\n` +
-          `  • Reinstall: npm install -g nebula-ai\n` +
-          `  • Open an issue: https://github.com/thirdweb-dev/nebula-cli/issues`,
-      );
-      process.exit(1);
-    }
-  }
-
-  // Fire-and-forget background version check (writes cache for next run).
-  if (!isUpdateCheckDisabled() && !isNpx()) {
-    maybeSpawnUpdateCheck(version);
-  }
-
-  const result = spawnSync(binaryPath, process.argv.slice(2), {
-    stdio: "inherit",
-  });
-
-  // Show update notification (reads PREVIOUS check's cached result).
-  if (!isUpdateCheckDisabled() && !isNpx()) {
-    maybeShowUpdateNotification(version);
-  }
-
-  if (result.error) {
-    console.error(
-      `nebula-ai: unable to start the application.\n` +
-        `\n` +
-        `This can happen if the downloaded runtime was corrupted.\n` +
-        `\n` +
-        `To fix this:\n` +
-        `  1. Clear the cache: rm -rf ${getCacheDir(version)}\n` +
-        `  2. Run nebula-ai again to re-download`,
-    );
-    process.exit(1);
-  }
-  process.exit(result.status ?? 0);
+        version = await readVersion();
+    }
+    catch (err) {
+        console.error(`nebula-ai: unable to determine the installed version.\n` +
+            `\n` +
+            `This usually means the installation is corrupted. To fix this, reinstall:\n` +
+            `  npm install -g nebula-ai`);
+        process.exit(1);
+    }
+    const cacheDir = getCacheDir(version);
+    const binaryPath = join(cacheDir, binName);
+    if (!existsSync(binaryPath)) {
+        try {
+            await downloadBinary(version, binaryPath);
+        }
+        catch (err) {
+            console.error(`nebula-ai: could not download the runtime.\n` +
+                `\n` +
+                `This is usually a network issue. Please check your internet connection and try again.\n` +
+                `\n` +
+                `If the problem persists:\n` +
+                `  • Clear the download cache: rm -rf ${getCacheDir(version)}\n` +
+                `  • Reinstall: npm install -g nebula-ai\n` +
+                `  • Open an issue: https://github.com/thirdweb-dev/nebula-cli/issues`);
+            process.exit(1);
+        }
+        // New version downloaded — purge stale version directories.
+        cleanupOldVersions(version);
+    }
+    // Fire-and-forget background version check (writes cache for next run).
+    if (!isUpdateCheckDisabled() && !isNpx()) {
+        maybeSpawnUpdateCheck(version);
+    }
+    const result = spawnSync(binaryPath, process.argv.slice(2), {
+        stdio: "inherit",
+    });
+    // Show update notification (reads PREVIOUS check's cached result).
+    if (!isUpdateCheckDisabled() && !isNpx()) {
+        maybeShowUpdateNotification(version);
+    }
+    if (result.error) {
+        console.error(`nebula-ai: unable to start the application.\n` +
+            `\n` +
+            `This can happen if the downloaded runtime was corrupted.\n` +
+            `\n` +
+            `To fix this:\n` +
+            `  1. Clear the cache: rm -rf ${getCacheDir(version)}\n` +
+            `  2. Run nebula-ai again to re-download`);
+        process.exit(1);
+    }
+    process.exit(result.status ?? 0);
 }
-
 // Only run main() when this file is the CLI entrypoint, so tests can
 // import the pure helpers above without triggering a download.
 //
@@ -471,16 +432,16 @@ async function main() {
 // a naive string compare would always fail and main() would silently never
 // run. realpathSync both sides so the comparison survives the bin shim.
 function isCliEntrypoint() {
-  if (!process.argv[1]) return false;
-  try {
-    return (
-      realpathSync(fileURLToPath(import.meta.url)) ===
-      realpathSync(process.argv[1])
-    );
-  } catch {
-    return false;
-  }
+    if (!process.argv[1])
+        return false;
+    try {
+        return (realpathSync(fileURLToPath(import.meta.url)) ===
+            realpathSync(process.argv[1]));
+    }
+    catch {
+        return false;
+    }
 }
 if (isCliEntrypoint()) {
-  main();
+    main();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nebula-ai",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "CLI/TUI for the nebula.gg AI task orchestration platform",
   "type": "module",
   "bin": {