nebula-ai 0.0.16 → 0.0.17

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.16",
+  "version": "0.0.17",
   "description": "CLI/TUI for the nebula.gg AI task orchestration platform",
   "type": "module",
   "bin": {