nebula-ai 0.0.7 → 0.0.8

package/bin/nebula-ai.js

@@ -39,16 +39,18 @@
 //      long enough for the dist-tag to catch up, then delete the old
 //      key material.
 
-import { spawnSync } from "node:child_process";
+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 { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -80,8 +82,75 @@ const SUPPORTED_PLATFORMS = new Set([
   "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");
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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 true when running under `npx` (which always fetches the latest
+ * wrapper, making the check redundant).
+ */
+export function isNpx() {
+  return process.env.npm_command === "exec";
+}
+
 export function sha256HexSync(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
@@ -189,7 +258,7 @@ async function downloadBinary(version, destPath) {
   const url = `${DOWNLOAD_BASE_URL}/v${version}/${platformKey}/${binName}`;
 
   process.stderr.write(
-    `nebula-ai: fetching ${platformKey} v${version} prebuilt binary…\n`,
+    `nebula-ai: downloading runtime for your platform (one-time setup)…\n`,
   );
 
   const manifest = await fetchManifest(version);
@@ -227,21 +296,105 @@ async function downloadBinary(version, destPath) {
   }
 }
 
+// ─── 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
+ * write it to the cache file. The process is unref'd so it does not keep the
+ * 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 fs = require("node:fs");
+    const path = require("node:path");
+    const cachePath = ${JSON.stringify(cachePath)};
+    fetch("https://registry.npmjs.org/nebula-ai/${distTag}", {
+      headers: { "Accept": "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(10000),
+    })
+      .then(r => { if (!r.ok) throw new Error(r.status); return r.json(); })
+      .then(data => {
+        if (typeof data.version === "string") {
+          fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+          fs.writeFileSync(cachePath, JSON.stringify({
+            latest: data.version,
+            channel: "${distTag}",
+            checkedAt: Date.now(),
+          }));
+        }
+      })
+      .catch(() => {});
+  `;
+
+  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.
+  }
+}
+
 async function main() {
   if (DOWNLOAD_BASE_URL.includes("__NEBULA_AI_DOWNLOAD_BASE__")) {
     console.error(
-      "nebula-ai: this build of the wrapper was not stamped with a download base URL.\n" +
-        "  Set NEBULA_AI_DOWNLOAD_BASE to a reachable mirror, or install\n" +
-        "  nebula-ai from a dev checkout of https://github.com/thirdweb-dev/nebula-cli.",
+      "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: no prebuilt binary for ${platformKey}.\n` +
+      `nebula-ai: your platform (${platformKey}) is not yet supported.\n` +
+        `\n` +
         `Supported platforms: ${[...SUPPORTED_PLATFORMS].join(", ")}.\n` +
-        `File an issue at https://github.com/thirdweb-dev/nebula-cli/issues`,
+        `\n` +
+        `Please open an issue to request support:\n` +
+        `  https://github.com/thirdweb-dev/nebula-cli/issues`,
     );
     process.exit(1);
   }
@@ -250,7 +403,12 @@ async function main() {
   try {
     version = await readVersion();
   } catch (err) {
-    console.error(`nebula-ai: ${err instanceof Error ? err.message : 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);
   }
 
@@ -261,21 +419,44 @@ async function main() {
     try {
       await downloadBinary(version, binaryPath);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
       console.error(
-        `nebula-ai: failed to install prebuilt binary.\n  ${msg}\n` +
-          `\nIf your environment blocks outbound HTTPS, set NEBULA_AI_DOWNLOAD_BASE\n` +
-          `to a reachable mirror, or install from source.`,
+        `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: failed to exec binary: ${result.error.message}`);
+    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);

package/package.json

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