nebula-ai 0.0.17 → 0.0.19

package/README.md

@@ -18,7 +18,7 @@ npx nebula-ai                                  # interactive TUI
 npx nebula-ai chat "summarize the open issues in repo X"
 ```
 
-At login you pick where the auth token lives — your **system keychain** (recommended; uses `Bun.secrets` → macOS Keychain / Windows Credential Manager / libsecret) or a **local file** at `~/.nebula/.auth-token` (0600). Keychain failures fall back transparently to the file store so you never lose a session you just authenticated.
+The auth token is persisted as an encrypted file at `~/.nebula/auth-token` (mode `0600`). The encryption key is derived from your hostname and OS user via HKDF-SHA256, so backups/syncs of `~/.nebula/` to a different machine yield ciphertext that won't decrypt on the target — the binding is intentional, not a bug. See [ADR-0054](../../docs/adr/0054-encrypted-file-token-store-no-keychain.md) for the threat-model details.
 
 **Supported platforms:** macOS (arm64, x64), Linux (x64, arm64), Windows (x64).
 
@@ -40,6 +40,10 @@ The Homebrew channel ships prod releases only. Dev builds remain on npm — inst
 
 If you've installed via both `brew` and `npm i -g`, whichever prefix appears first on your `PATH` wins — this is normal for multi-source CLIs.
 
+### Bundled with Nebula Desktop
+
+The [Nebula Desktop app](https://github.com/agent-labs-dev/nebula-desktop/releases) bundles this same CLI binary inside its `.app`. From **Settings → Install Shell Command** in the desktop app, you can expose `nebula-ai` on your `$PATH` without a separate npm/brew install — the shim re-execs the bundled binary, so desktop updates automatically refresh the CLI version. Both surfaces share `~/.nebula/auth-token`: a session you sign into in one is immediately usable from the other.
+
 ## Interactive TUI
 
 The TUI gives you a full dashboard with agents, channels, and settings — all navigable from the keyboard.
@@ -149,6 +153,14 @@ No events are sent when telemetry is disabled.
 | `NEBULA_AI_DOWNLOAD_BASE` | Use an alternate mirror for the prebuilt binary download (useful behind restrictive firewalls). |
 | `NEBULA_AI_NO_UPDATE_CHECK` | Set to `1` to suppress the daily update check. Already suppressed under `npx`, CI, or a non-TTY stderr. |
 | `API_URL` | Override the Nebula API base URL (alternative to the `--api-url` flag). |
-| `NEBULA_AUTH_TOKEN` | Use a pre-minted auth token instead of the stored credential. Scripting / CI escape hatch — takes precedence over both keychain and file stores. |
+| `NEBULA_AUTH_TOKEN` | Use a pre-minted auth token instead of the stored credential. Scripting / CI escape hatch — takes precedence over the encrypted on-disk store. |
 | `NEBULA_DEBUG` / `DEBUG=nebula-cli` | Enable verbose logging (same effect as `-v/--verbose`). |
 | `DO_NOT_TRACK` / `NEBULA_DO_NOT_TRACK` | Set to `1` to disable product telemetry. |
+
+## Development
+
+This CLI is developed in the [`nebula-desktop`](https://github.com/agent-labs-dev/nebula-desktop) Bun-workspaces umbrella alongside the desktop app and shared packages. Contributor docs:
+
+- [`AGENTS.md`](./AGENTS.md) — CLI-specific build, dev, and architecture conventions.
+- [`docs/`](./docs/) — working notes (local-device backend contracts, RPC port mappings, sandbox image directives).
+- The [workspace README](../../README.md) and [root `AGENTS.md`](../../AGENTS.md) cover umbrella-level conventions (gates, releases, packages).

package/bin/nebula-ai.js

@@ -46,23 +46,23 @@ 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";
+import { detectInstallMethod, distTagForChannel, 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";
+export { detectInstallMethod, distTagForChannel, 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.
 const EMBEDDED_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAd8QFvCTSMY0HmSsJgL6jtFQas00WedvSZhkc9bxdAl0=
+MCowBQYDK2VwAyEAyAvta5v665Vd82jfFmuCEw3WpneUQboj936gYHQE4/0=
 -----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 STAMPED_DOWNLOAD_BASE_URL = "https://app-assets.nebula.gg/cli/stable";
+const DOWNLOAD_BASE_URL = process.env["NEBULA_AI_DOWNLOAD_BASE"] ?? STAMPED_DOWNLOAD_BASE_URL;
 const SUPPORTED_PLATFORMS = new Set([
     "darwin-arm64",
     "darwin-x64",
@@ -97,10 +97,10 @@ export function verifyManifest(manifestBytes, signatureBase64, publicKeyPem) {
         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["algorithm"] !== "sha256") {
+        throw new Error(`unsupported manifest algorithm: ${m["algorithm"] ?? "(missing)"}`);
     }
-    if (!m.binaries || typeof m.binaries !== "object") {
+    if (!m["binaries"] || typeof m["binaries"] !== "object") {
         throw new Error("manifest is missing the `binaries` map");
     }
     return manifest;
@@ -129,18 +129,18 @@ async function readVersion() {
     const pkgPath = join(here, "..", "package.json");
     const raw = await readFile(pkgPath, "utf8");
     const pkg = JSON.parse(raw);
-    if (typeof pkg.version !== "string") {
+    if (typeof pkg["version"] !== "string") {
         throw new Error("nebula-ai: package.json is missing a version field");
     }
-    return pkg.version;
+    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 ||
+    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"));
+            ? process.env["LOCALAPPDATA"] || join(homedir(), "AppData", "Local")
+            : process.env["XDG_CACHE_HOME"] || join(homedir(), ".cache"));
     return join(base, "nebula-ai");
 }
 function getCacheDir(version) {
@@ -242,7 +242,7 @@ function maybeSpawnUpdateCheck(currentVersion) {
         // File missing — fall through to spawn.
     }
     const channel = getChannel(currentVersion);
-    const distTag = channel === "dev" ? "dev" : "latest";
+    const distTag = distTagForChannel(channel);
     const script = `
     const fs = require("node:fs");
     const path = require("node:path");
@@ -293,7 +293,9 @@ function maybeShowUpdateNotification(currentVersion, installMethod) {
             const cmd = getUpgradeCommand(installMethod, channel) ||
                 (channel === "dev"
                     ? "npm install -g nebula-ai@dev"
-                    : "npm install -g nebula-ai");
+                    : channel === "nightly"
+                        ? "npm install -g nebula-ai@nightly"
+                        : "npm install -g nebula-ai");
             process.stderr.write(`\nnebula-ai: update available ${currentVersion} \u2192 ${cached.latest}\n` +
                 `  Run: ${cmd}\n`);
         }
@@ -310,7 +312,7 @@ async function main() {
             "  npm install -g nebula-ai\n" +
             "\n" +
             "If the problem persists, please open an issue:\n" +
-            "  https://github.com/agent-labs-dev/nebula-cli/issues");
+            "  https://github.com/agent-labs-dev/nebula-desktop/issues");
         process.exit(1);
     }
     if (!SUPPORTED_PLATFORMS.has(platformKey)) {
@@ -319,7 +321,7 @@ async function main() {
             `Supported platforms: ${[...SUPPORTED_PLATFORMS].join(", ")}.\n` +
             `\n` +
             `Please open an issue to request support:\n` +
-            `  https://github.com/agent-labs-dev/nebula-cli/issues`);
+            `  https://github.com/agent-labs-dev/nebula-desktop/issues`);
         process.exit(1);
     }
     let version;
@@ -347,7 +349,7 @@ async function main() {
                 `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/agent-labs-dev/nebula-cli/issues`);
+                `  • Open an issue: https://github.com/agent-labs-dev/nebula-desktop/issues`);
             process.exit(1);
         }
         // New version downloaded — purge stale version directories.
@@ -364,8 +366,8 @@ async function main() {
     const installMethod = detectInstallMethod({
         execPath: fileURLToPath(import.meta.url),
         argv0: process.argv[0],
-        npmCommand: process.env.npm_command,
-        npmUserAgent: process.env.npm_config_user_agent,
+        npmCommand: process.env["npm_command"],
+        npmUserAgent: process.env["npm_config_user_agent"],
     });
     const result = spawnSync(binaryPath, process.argv.slice(2), {
         stdio: "inherit",

package/bin/update-check-lib.js

@@ -27,37 +27,50 @@ export const UPDATE_CHECK_TTL_MS = 4 * 60 * 60 * 1000;
  * across version upgrades.
  */
 export function getUpdateCheckCachePath() {
-    const base = process.env.NEBULA_AI_CACHE_DIR ||
+    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"));
+            ? 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`.
+ * Pre-stable versions look like `x.y.z-<channel>.YYYYMMDDHHMMSS.sha`.
  */
 export function getChannel(version) {
-    return version.includes("-dev.") ? "dev" : "prod";
+    if (version.includes("-dev."))
+        return "dev";
+    if (version.includes("-nightly."))
+        return "nightly";
+    return "prod";
+}
+/** Map a channel back to the npm dist-tag we publish under. */
+export function distTagForChannel(channel) {
+    if (channel === "dev")
+        return "dev";
+    if (channel === "nightly")
+        return "nightly";
+    return "latest";
 }
 /**
  * Return true if `latest` is a newer semver than `current` (prod), or a
- * strictly newer build timestamp (dev).
+ * strictly newer build timestamp (dev/nightly).
  *
- * 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.
+ * Pre-stable versions look like `x.y.z-<channel>.YYYYMMDDHHMMSS.sha`,
+ * produced by CI on every release run. Comparing with `!==` would falsely
+ * flag any mismatch as an "update available" — including the common case
+ * where a contributor runs a locally-built pre-stable binary that's ahead
+ * of the registry's 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];
+    const currentChannel = getChannel(current);
+    if (currentChannel === "dev" || currentChannel === "nightly") {
+        const stamp = new RegExp(`-${currentChannel}\\.(\\d{14})\\.`);
+        const latestStamp = latest.match(stamp)?.[1];
+        const currentStamp = current.match(stamp)?.[1];
         if (latestStamp && currentStamp)
             return latestStamp > currentStamp;
         return latest !== current;
@@ -98,10 +111,10 @@ export function isUpdateCheckDisabled(stream = process.stderr) {
     // 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 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" ||
+    return (process.env["NEBULA_AI_NO_UPDATE_CHECK"] === "1" ||
+        process.env["NEBULA_AI_NO_UPDATE_CHECK"] === "true" ||
         inCI ||
         !stream.isTTY);
 }
@@ -124,7 +137,7 @@ export function isUpdateCheckDisabled(stream = process.stderr) {
  * path-based signal (like `detectInstallMethod`) layer that check on top.
  */
 export function isNpx() {
-    const cmd = process.env.npm_command;
+    const cmd = process.env["npm_command"];
     return cmd === "exec" || cmd === "dlx";
 }
 /**
@@ -151,6 +164,9 @@ export function detectInstallMethod(input) {
     // Normalize Windows separators so our substring checks work uniformly.
     p.replace(/\\/g, "/"));
     const anyMatch = (...needles) => paths.some((p) => needles.some((n) => p.includes(n)));
+    if (anyMatch(".app/Contents/Resources/")) {
+        return "desktop-bundle";
+    }
     // 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
@@ -195,7 +211,11 @@ export function detectInstallMethod(input) {
  * single-shot upgrade makes sense (npx / unknown).
  */
 export function getUpgradeCommand(method, channel) {
-    const pkg = channel === "dev" ? "nebula-ai@dev" : "nebula-ai";
+    const pkg = channel === "dev"
+        ? "nebula-ai@dev"
+        : channel === "nightly"
+            ? "nebula-ai@nightly"
+            : "nebula-ai";
     switch (method) {
         case "npm":
             return `npm install -g ${pkg}`;
@@ -210,12 +230,17 @@ export function getUpgradeCommand(method, channel) {
         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`;
+            // The brew tap is stable-only (pre-stable versions use
+            // `-<channel>.<stamp>.<sha>` suffixes Homebrew mishandles). If
+            // someone somehow ended up on a pre-stable build via brew,
+            // redirect them to npm for the matching channel.
+            if (channel === "dev")
+                return "npm install -g nebula-ai@dev";
+            if (channel === "nightly")
+                return "npm install -g nebula-ai@nightly";
+            return "brew upgrade nebula-ai";
+        case "desktop-bundle":
+            return "Update via Nebula.app -> Settings";
         case "npx":
         case "unknown":
             return "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nebula-ai",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "CLI/TUI for the nebula.gg AI task orchestration platform",
   "type": "module",
   "bin": {
@@ -21,13 +21,14 @@
     "tasks"
   ],
   "license": "MIT",
-  "homepage": "https://github.com/agent-labs-dev/nebula-cli#readme",
+  "homepage": "https://github.com/agent-labs-dev/nebula-desktop/tree/main/apps/cli#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/agent-labs-dev/nebula-cli.git"
+    "url": "git+https://github.com/agent-labs-dev/nebula-desktop.git",
+    "directory": "apps/cli"
   },
   "bugs": {
-    "url": "https://github.com/agent-labs-dev/nebula-cli/issues"
+    "url": "https://github.com/agent-labs-dev/nebula-desktop/issues"
   },
   "publishConfig": {
     "access": "public"