nebula-ai 0.0.15 → 0.0.17

package/bin/nebula-ai.js

@@ -46,6 +46,10 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
+import { detectInstallMethod, getChannel, getUpdateCheckCachePath, getUpgradeCommand, isNewerVersion, isNpx, isUpdateCheckDisabled, UPDATE_CHECK_TTL_MS, } from "./update-check-lib.js";
+// Re-export the pure update-check helpers so older tests / downstream
+// importers that still reach for `./launcher.js` keep working.
+export { detectInstallMethod, getChannel, getUpdateCheckCachePath, getUpgradeCommand, isNewerVersion, isNpx, isUpdateCheckDisabled, } from "./update-check-lib.js";
 // 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.
@@ -66,68 +70,11 @@ const SUPPORTED_PLATFORMS = new Set([
     "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");
-}
-/**
- * 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";
-}
+//
+// Version/update-check helpers live in ./update-check-lib.ts and are
+// re-exported above. Supply-chain helpers remain here because they import
+// node:crypto and aren't used outside the launcher.
 export function sha256HexSync(buffer) {
     return createHash("sha256").update(buffer).digest("hex");
 }
@@ -288,7 +235,7 @@ 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)
+        if (Date.now() - statSync(cachePath).mtimeMs < UPDATE_CHECK_TTL_MS)
             return;
     }
     catch {
@@ -331,16 +278,22 @@ function maybeSpawnUpdateCheck(currentVersion) {
 /**
  * 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.
+ * if a newer version is available. The suggested upgrade command is
+ * chosen based on the detected install method so pnpm/yarn/bun/brew users
+ * see an actually-applicable command.
  */
-function maybeShowUpdateNotification(currentVersion) {
+function maybeShowUpdateNotification(currentVersion, installMethod) {
     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";
+            const channel = getChannel(currentVersion);
+            // Fall back to the canonical npm command when the install method
+            // is unknown — matches the wrapper's install-time docs.
+            const cmd = getUpgradeCommand(installMethod, channel) ||
+                (channel === "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`);
         }
@@ -404,12 +357,23 @@ async function main() {
     if (!isUpdateCheckDisabled() && !isNpx()) {
         maybeSpawnUpdateCheck(version);
     }
+    // Figure out how the user installed us (npm/pnpm/yarn/bun/npx/...) from
+    // the wrapper's own launch path + env. We forward the result to the Bun
+    // binary via NEBULA_AI_INSTALL_METHOD so the in-TUI "What's new" banner
+    // can surface the right upgrade command without redoing the detection.
+    const installMethod = detectInstallMethod({
+        execPath: fileURLToPath(import.meta.url),
+        argv0: process.argv[0],
+        npmCommand: process.env.npm_command,
+        npmUserAgent: process.env.npm_config_user_agent,
+    });
     const result = spawnSync(binaryPath, process.argv.slice(2), {
         stdio: "inherit",
+        env: { ...process.env, NEBULA_AI_INSTALL_METHOD: installMethod },
     });
     // Show update notification (reads PREVIOUS check's cached result).
     if (!isUpdateCheckDisabled() && !isNpx()) {
-        maybeShowUpdateNotification(version);
+        maybeShowUpdateNotification(version, installMethod);
     }
     if (result.error) {
         console.error(`nebula-ai: unable to start the application.\n` +

package/bin/update-check-lib.js

@@ -0,0 +1,223 @@
+// Shared, pure helpers for the nebula-ai update-check flow.
+//
+// This module is imported by two very different consumers:
+//
+//   1. `scripts/publish/launcher.ts` — the Node launcher shipped as the
+//      npm wrapper. Uses these helpers to decide whether to fire the
+//      background check and to print the post-exit stderr notification.
+//
+//   2. `src/update-check/lib.ts` — a byte-for-byte mirror living inside
+//      the Bun SEA binary. Kept in sync via a parity test rather than a
+//      cross-tree import because the main tsconfig's `rootDir: src`
+//      forbids reaching outside `src/`. If you edit this file, edit the
+//      mirror as well (see the parity test in
+//      `src/update-check/lib.test.ts`).
+//
+// Everything exported here MUST be pure (no fs, no network, no process
+// exits). Side-effecting code belongs in the callers.
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ─── update-check constants ────────────────────────────────────────────────
+/** How long a cache entry counts as fresh (4 hours). */
+export const UPDATE_CHECK_TTL_MS = 4 * 60 * 60 * 1000;
+// ─── cache-path resolution ─────────────────────────────────────────────────
+/**
+ * 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");
+}
+// ─── version helpers ───────────────────────────────────────────────────────
+/**
+ * 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 a
+ * strictly newer build timestamp (dev).
+ *
+ * Dev versions look like `x.y.z-dev.YYYYMMDDHHMMSS.sha`, produced by CI on
+ * every merge. Comparing with `!==` would falsely flag any mismatch as an
+ * "update available" — including the common case where a contributor runs a
+ * locally-built dev binary that's ahead of the registry's `dev` dist-tag
+ * (e.g. a PR branch that's ahead of main). Parse the 14-digit stamp out of
+ * both sides and compare those instead; fall back to `!==` only if either
+ * string doesn't match the expected shape.
+ */
+export function isNewerVersion(latest, current) {
+    if (current.includes("-dev.")) {
+        const devStamp = /-dev\.(\d{14})\./;
+        const latestStamp = latest.match(devStamp)?.[1];
+        const currentStamp = current.match(devStamp)?.[1];
+        if (latestStamp && currentStamp)
+            return latestStamp > currentStamp;
+        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;
+}
+// ─── environment gates ─────────────────────────────────────────────────────
+/**
+ * Return true when the update check should be suppressed entirely.
+ *
+ * The TTY check targets the stream the caller is about to write to — callers
+ * pass the stream they'd render on:
+ *
+ *   - Launcher context → `process.stderr` (the stderr one-liner).
+ *   - Binary / TUI context → `process.stdout` (the in-TUI banner).
+ *
+ * Without this distinction, a user running `nebula-ai 2>/dev/null` would
+ * silence the in-TUI banner even though the TUI itself is still rendering
+ * on stdout. Defaults to `process.stderr` to preserve the launcher's
+ * historical behaviour for any caller that doesn't pass one.
+ */
+export function isUpdateCheckDisabled(stream = process.stderr) {
+    // Canonical `CI=true` is what GitHub Actions / CircleCI / GitLab CI set,
+    // but the long tail of CI runners uses `CI=1`, `CI=yes`, etc. Treat any
+    // non-empty value as "in CI" unless it's explicitly opted out
+    // (`CI=false` / `CI=0`), matching npm's is-ci heuristic.
+    const ci = process.env.CI?.toLowerCase();
+    const inCI = !!ci && ci !== "false" && ci !== "0";
+    return (process.env.NEBULA_AI_NO_UPDATE_CHECK === "1" ||
+        process.env.NEBULA_AI_NO_UPDATE_CHECK === "true" ||
+        inCI ||
+        !stream.isTTY);
+}
+/**
+ * Return true when running under a transient package runner (npx, pnpm dlx,
+ * yarn dlx, bunx). Those flows fetch a fresh copy of the wrapper every
+ * invocation, so an "update available" notice would be misleading — there's
+ * nothing persistent to upgrade.
+ *
+ * Detection is a two-step heuristic because no single signal catches every
+ * runner:
+ *
+ *   - `npm_command` is set to `"exec"` by npm and `"dlx"` by pnpm/yarn.
+ *   - bunx doesn't set `npm_command` at all, but bun-originated invocations
+ *     set `npm_config_user_agent` to `bun/...`. If we see that UA *and* the
+ *     binary isn't living under a persistent bun globals path (that check
+ *     belongs in `detectInstallMethod`), we treat it as transient.
+ *
+ * `isNpx()` deliberately stays conservative — callers that also have a
+ * path-based signal (like `detectInstallMethod`) layer that check on top.
+ */
+export function isNpx() {
+    const cmd = process.env.npm_command;
+    return cmd === "exec" || cmd === "dlx";
+}
+/**
+ * Pure detection: given a resolved launch path + a few env vars, return
+ * the best-guess install method. No fs / no process inspection — all
+ * inputs are passed in by the caller so this function stays trivial to
+ * test.
+ */
+export function detectInstallMethod(input) {
+    // 1. Transient-runner env vars win unconditionally. `exec` is set by npx;
+    //    `dlx` by pnpm/yarn's dlx commands. Each invocation re-fetches the
+    //    wrapper, so there's nothing persistent to upgrade and the banner
+    //    should be suppressed.
+    if (input.npmCommand === "exec" || input.npmCommand === "dlx")
+        return "npx";
+    // 2. Path fingerprinting precedes user-agent matching because the path
+    //    tells us WHERE the binary lives (persistent vs. transient cache),
+    //    whereas the UA only tells us WHO invoked it. A `bunx nebula-ai`
+    //    invocation sets the UA to `bun/...` but the binary lives in bun's
+    //    run-cache, not its globals dir — trusting UA there would flash an
+    //    `bun add -g` banner even though bunx already fetches fresh. Check
+    //    both execPath and argv0 because on some shims they diverge.
+    const paths = [input.execPath, input.argv0 ?? ""].map((p) => 
+    // Normalize Windows separators so our substring checks work uniformly.
+    p.replace(/\\/g, "/"));
+    const anyMatch = (...needles) => paths.some((p) => needles.some((n) => p.includes(n)));
+    // Homebrew formula name is `nebula-ai`, so a brew-installed binary lives
+    // under `.../Cellar/nebula-ai/<version>/bin/nebula-ai`. Matching the
+    // formula segment specifically avoids misdetecting an npm global under a
+    // Homebrew-installed Node (which lives at
+    // `/opt/homebrew/lib/node_modules/...`, no `/Cellar/nebula-ai/`).
+    if (anyMatch("/Cellar/nebula-ai/", "/linuxbrew/Cellar/nebula-ai/")) {
+        return "brew";
+    }
+    if (anyMatch("/.bun/install/global/", "/bun/install/global/")) {
+        return "bun";
+    }
+    if (anyMatch("/pnpm/global/", "/.pnpm/global/", "/Library/pnpm/", "/.local/share/pnpm/", "/pnpm-global/")) {
+        return "pnpm";
+    }
+    if (anyMatch("/.yarn/global/", "/yarn/global/")) {
+        return "yarn";
+    }
+    // Any `/node_modules/` fingerprint that fell through is most likely an
+    // npm global (npm installs the wrapper as a symlink inside
+    // `<prefix>/lib/node_modules/nebula-ai/`).
+    if (anyMatch("/node_modules/")) {
+        return "npm";
+    }
+    // 3. User-agent fallthrough. If we get here, none of the persistent
+    //    install paths matched, which means a UA match most likely indicates
+    //    a transient runner (e.g. `bunx nebula-ai`, or a project-local
+    //    `pnpm exec` that didn't set `npm_command=exec`). Treat these as npx
+    //    — no persistent install to upgrade.
+    const ua = (input.npmUserAgent ?? "").toLowerCase();
+    if (ua.startsWith("pnpm") ||
+        ua.startsWith("yarn") ||
+        ua.startsWith("bun") ||
+        ua.startsWith("npm")) {
+        return "npx";
+    }
+    return "unknown";
+}
+// ─── upgrade-command mapping ───────────────────────────────────────────────
+/**
+ * Map an install method + release channel to the shell command a user
+ * would run to upgrade. Returns an empty string for cases where no
+ * single-shot upgrade makes sense (npx / unknown).
+ */
+export function getUpgradeCommand(method, channel) {
+    const pkg = channel === "dev" ? "nebula-ai@dev" : "nebula-ai";
+    switch (method) {
+        case "npm":
+            return `npm install -g ${pkg}`;
+        case "pnpm":
+            return `pnpm add -g ${pkg}`;
+        case "yarn":
+            // `yarn global add` only exists on classic yarn; modern yarn (berry)
+            // drops the global registry in favour of dlx, but there's no better
+            // single-command upgrade for a classic-yarn user — this mirrors what
+            // their install command would have been.
+            return `yarn global add ${pkg}`;
+        case "bun":
+            return `bun add -g ${pkg}`;
+        case "brew":
+            // The brew tap is prod-only (dev versions use `-dev.<stamp>.<sha>`
+            // suffixes Homebrew mishandles). If someone somehow ended up on dev
+            // via brew, redirect them to npm for the dev channel.
+            return channel === "dev"
+                ? `npm install -g nebula-ai@dev`
+                : `brew upgrade nebula-ai`;
+        case "npx":
+        case "unknown":
+            return "";
+    }
+}

package/package.json

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