nebula-ai 0.0.14 → 0.0.16

package/README.md

@@ -18,6 +18,8 @@ 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.
+
 **Supported platforms:** macOS (arm64, x64), Linux (x64, arm64), Windows (x64).
 
 ## Install via Homebrew
@@ -47,21 +49,62 @@ The TUI gives you a full dashboard with agents, channels, and settings — all n
 - **Ctrl+K command palette** — jump to any agent, channel, or settings page instantly. Start typing to filter, or create channels and send messages directly from the palette.
 - **Tab / Shift+Tab** — cycle between Agents, Channels, and Settings sections on the home screen.
 - **@ / #** — jump directly to the Agents or Channels section.
+- **Vim-style motion** — `j`/`k` up/down, `h`/`Esc` back, `l`/`Enter` open. Works everywhere lists are rendered.
+- **Tab bar** — `h`/`l` switch between open tabs, `x` closes the current tab.
+- **Status bar** — always-on mode badge (`NAV` / `INSERT` / `HITL` / `FIND`), breadcrumb, contextual key hints, and a live connection indicator.
+- **q** from any navigation-mode screen exits cleanly.
 
 ### Chat
 
 - **Markdown rendering** — agent responses display bold, italic, inline code, headings, and clickable links.
-- **Per-channel model selection** — press `m` in any DM or channel to switch the AI model for that conversation. A global default model can be set in Settings.
-- **File attachments** — drag and drop files from your file manager into the chat input. Files appear as chips above the message area and are sent with your next message.
-- **Activity log** — tool calls and execution details are surfaced inline in chat, with a keystroke to open the full activity log for a completed turn.
-- **Interactive prompts** — when an agent asks a multi-choice question, it renders as a widget with option descriptions, number-key shortcuts (1–9), and an "Other" free-text fallback.
+- **Per-channel model selection** — press `m` in any DM or channel to open the model picker. Verified and experimental model lists are surfaced separately; a global default model can be set in Settings.
+- **File attachments** — drag and drop files from your file manager into the chat input. Files appear as chips above the message area and are sent with your next message. When the local device daemon is running, files are delivered through the sandbox instead of being uploaded to the cloud.
+- **Activity log** — tool calls and execution details are surfaced inline in chat, with `Enter` on a completed turn opening the full activity log.
+- **Entity navigation** — press `Tab` on a selected message to cycle through referenced agents, triggers, files, and skills; `Enter` opens the detail view.
+- **Message history** — press `↑` from an empty input (or `k` in navigation mode) to scroll back through previous turns.
+- **Interactive prompts (HITL)** — when an agent asks a multi-choice question or requests plan approval, it renders as a widget with option descriptions, number-key shortcuts (1–9), and an "Other" free-text fallback.
+- **Archive** — press `Shift+A` in any channel to archive it with a confirm prompt.
+- **Refresh** — press `Shift+R` to pull the latest state for the current view.
 - **Auto-focus input** — configurable in Settings. When disabled, chats open in navigation mode; press `i` to start typing.
 
 ### Workspace & session
 
 - **Multi-tab workspace** — tabs dynamically resize to your terminal width and scroll horizontally when they overflow.
 - **Instant tab switching** — previously visited screens load from cache while fresh data is fetched in the background (stale-while-revalidate).
-- **Session restore** — enable in Settings to automatically reopen your tabs and navigation state when you restart the CLI.
+- **Session restore** — enable in Settings to automatically reopen your tabs and navigation state when you restart the CLI. Session state is also flushed on clean Ctrl+C / SIGTERM.
+
+### Theming
+
+Sixteen base16 color themes ship in the box: `default-dark`, `monokai`, `ocean`, `eighties`, `gruvbox`, `solarized`, `tokyo-night`, `dracula`, `nord`, `onedark`, `catppuccin`, `rose-pine`, `kanagawa`, `everforest`, `night-owl`, `material`. Cycle through them from **Settings → Configuration** (press `Enter` on the Theme row), or set a fixed value from the CLI:
+
+```sh
+npx nebula-ai user config set theme tokyo-night
+```
+
+### Settings
+
+Reachable from the home screen (`Settings` row) or the command palette:
+
+- **Profile & Account** — username, email, display name.
+- **Default Model** — global LLM fallback for new chats.
+- **Local Device** — daemon status, start/stop/restart controls, device ID.
+- **Mounted Folders** — add/remove host folders that are mounted into the sandbox.
+- **Files** — browse and manage files stored on the platform.
+- **Configuration** — theme, color, verbose, auto-focus, session restore, telemetry.
+
+## Local device & sandbox
+
+For long-running tasks, agents can execute code on your own machine inside a managed microVM sandbox (powered by [Boxlite](https://boxlite.ai)). The sandbox is isolated from your host but can optionally mount folders you choose as read-write or read-only.
+
+```sh
+npx nebula-ai install              # install and start the background daemon
+npx nebula-ai local-device status  # check daemon state
+npx nebula-ai local-device folders add ~/code/my-project
+npx nebula-ai shell                # open an interactive shell inside the sandbox
+npx nebula-ai uninstall            # remove the daemon (use --keep-data to keep config/logs)
+```
+
+The daemon is installed as a native OS service — **launchd** on macOS, **systemd --user** on Linux, **Task Scheduler** on Windows — and runs under your user account so there's no root prompt. The sandbox image is pre-pulled during install so the first real RPC doesn't block on a download.
 
 ## CLI commands
 
@@ -70,21 +113,26 @@ The same surface is available from the command line:
 - `chat` — send a message to an agent (`-a/--agent`, `-c/--channel`, `--no-stream`).
 - `channels` — list, create, get, delete, archive, unarchive, share, update, and view messages in conversation threads.
 - `agents` — list, create, update, delete, enable/disable, view logs/errors, manage triggers, and attach/detach skills.
-- `user` — profile, billing, files, variables (including secrets), and local config.
-  - `user config` — list, get, set, and reset configuration values; list available AI models.
+- `user` — profile, account, and platform-side resources.
+  - `user update` — change username or display name.
+  - `user config` — list, get, set, and reset CLI configuration values; list available AI models.
   - `user variables` — manage global or agent-scoped variables and secrets.
   - `user billing` — check balance, view transaction history, and configure auto top-up.
   - `user files` — upload, download, list, share, and manage files and folders.
-- `status` — current CLI and device state.
+  - `user devices` — manage your cloud sandbox device (info, start, stop, rename, visibility, file browse/search, and long-running services: create, start, stop, logs).
+- `local-device` — manage the on-host daemon (status, logs, start, stop, restart, folders add/remove).
+- `install` / `uninstall` — set up or tear down the on-host daemon as a background service.
+- `shell` — open an interactive shell inside the local sandbox VM (`--shell <path>` to pick a different binary).
+- `status` — current CLI, auth, daemon, device, and folder state.
 - `login` / `logout` — authenticate or clear stored credentials.
 
-Every command supports `--json` for machine-readable output, `-v/--verbose` for extra detail, and `--no-color` to disable ANSI styling.
+Every command supports `--json` for machine-readable output, `-v/--verbose` for extra detail, `--no-color` to disable ANSI styling, and `--api-url <url>` to point at a non-default backend.
 
 ## Privacy and telemetry
 
 The CLI collects anonymized usage analytics (via PostHog) to help improve the product. You can opt out at any time:
 
-- Toggle telemetry off in the TUI under **Settings > Configuration**
+- Toggle telemetry off in the TUI under **Settings → Configuration**
 - From the CLI: `npx nebula-ai user config set telemetry false`
 - Or set `DO_NOT_TRACK=1` (or `NEBULA_DO_NOT_TRACK=1`) in your environment
 
@@ -94,8 +142,13 @@ No events are sent when telemetry is disabled.
 
 | Path / variable | Purpose |
 |---|---|
-| `~/.config/nebula-cli/` | Stored auth session and CLI settings. |
-| `~/.cache/nebula-ai/` | Cached prebuilt binary. |
+| `~/.nebula/` | Stored auth session, CLI settings, sandbox data, daemon logs. |
+| `~/.cache/nebula-ai/` | Cached prebuilt binary (per-version, per-platform). |
+| `NEBULA_HOME` | Override the `~/.nebula` home directory. |
 | `NEBULA_AI_CACHE_DIR` | Override the binary cache location. |
 | `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_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. |

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/package.json

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