@spinabot/brigade 0.1.0 → 0.1.2

package/dist/ui/onboarding.js

@@ -15,6 +15,7 @@
 import * as path from "node:path";
 import { getEnvApiKey, getModels } from "@mariozechner/pi-ai";
 import { CancellableLoader, Input, SelectList, Text } from "@mariozechner/pi-tui";
+import { loadBrigadeConfig, writeBrigadeConfig } from "../core/brigade-config.js";
 import { BRIGADE_DIR, saveConfig } from "../core/config.js";
 import { discoverOllamaModels, writeOllamaToModelsJson } from "../integrations/ollama.js";
 import { findProvider, PROVIDERS } from "../providers/catalog.js";
@@ -41,7 +42,7 @@ function getProviderModels(modelRegistry, providerId) {
     }
     return modelRegistry.getAll().filter((m) => m.provider === providerId);
 }
-export async function runOnboarding(tui, authStorage, modelRegistry) {
+export async function runOnboarding(tui, authStorage, modelRegistry, opts = {}) {
     // Tiny step state machine so each step can resolve to "ok" or "back".
     // Esc on provider picker exits onboarding entirely; Esc on later steps
     // just rewinds to the previous step. This is what makes invalid keys
@@ -70,7 +71,7 @@ export async function runOnboarding(tui, authStorage, modelRegistry) {
                 step = "model";
                 continue;
             }
-            const result = await ensureApiKey(tui, authStorage, provider);
+            const result = await ensureApiKey(tui, authStorage, provider, { noEnvDetect: opts.noEnvDetect });
             if (result === "back") {
                 step = "provider";
                 continue;
@@ -111,11 +112,28 @@ function renderScreen(tui, subheader) {
 }
 /* ────────────────────────────── steps ─────────────────────────────────── */
 async function pickProvider(tui) {
-    const items = PROVIDERS.map((p) => ({
-        value: p.id,
-        label: p.name,
-        description: p.description,
-    }));
+    // Re-order providers so any with a credential the user already has —
+    // either an env var Pi can read, OR a noAuth provider like Ollama —
+    // floats to the top. Without this, PROVIDERS[0] = anthropic always wins
+    // the highlight, and a user with only OPENROUTER_API_KEY exported picks
+    // anthropic by reflex (then fails when they send a message).
+    const detected = [];
+    const undetected = [];
+    for (const p of PROVIDERS) {
+        const hasEnvKey = !!getEnvApiKey(p.id);
+        const noAuth = p.noAuth === true;
+        const item = {
+            value: p.id,
+            label: p.name,
+            description: hasEnvKey
+                ? `${p.description} · detected ${p.envVar ?? "env var"}`
+                : noAuth
+                    ? `${p.description} · no auth required`
+                    : p.description,
+        };
+        (hasEnvKey || noAuth ? detected : undetected).push(item);
+    }
+    const items = [...detected, ...undetected];
     const list = new SelectList(items, Math.min(items.length, 9), selectListTheme, {
         minPrimaryColumnWidth: 18,
         maxPrimaryColumnWidth: 22,
@@ -139,24 +157,133 @@ async function pickProvider(tui) {
  * and re-enters the field with their previous attempt pre-filled. Esc on
  * the input bails out of the loop with "back" instead of throwing.
  */
-async function ensureApiKey(tui, authStorage, providerId) {
+export async function ensureApiKey(tui, authStorage, providerId, opts = {}) {
     const provider = findProvider(providerId);
     if (!provider)
         throw new Error(`Unknown provider: ${providerId}`);
     // Already configured? (env var OR previously stored)
-    const existing = await authStorage.getApiKey(providerId);
+    // CRITICAL: an env var being PRESENT doesn't mean it WORKS — stale leftover
+    // values (from old experiments, exported by .bashrc, etc.) silently auto-
+    // completed onboarding and let users reach chat with a dead key. We now
+    // always run the online validation. Stored credentials get the fast accept
+    // only if they previously passed validation when first saved (which is
+    // always — see the typed-key path below — so saved keys are trustworthy
+    // enough to skip the re-check).
+    //
+    // `noEnvDetect` short-circuits the entire env-detection path: when true we
+    // pretend no credential exists, regardless of what `authStorage` returns
+    // from a shell env fallback. The typed-key prompt fires immediately. This
+    // is the enterprise / CI escape hatch — operators who want TYPED-only auth
+    // can flip the flag and Brigade never silently consults `$env:OPENROUTER_API_KEY`
+    // or its peers.
+    const existing = opts.noEnvDetect ? "" : await authStorage.getApiKey(providerId);
     if (existing) {
-        renderScreen(tui, `Step 2 of 3 · ${provider.name}`);
         const fromEnv = !!getEnvApiKey(providerId);
-        const source = fromEnv ? "your environment" : "your saved credentials";
-        tui.addChild(new Text(`  ${brand.amber("✓")} ${provider.name} is already connected (using ${brand.white(source)}).`, 0, 0));
+        if (!fromEnv) {
+            // Saved credential — passed validation when first stored. Fast accept.
+            renderScreen(tui, `Step 2 of 3 · ${provider.name}`);
+            tui.addChild(new Text(`  ${brand.amber("✓")} ${provider.name} is already connected (using ${brand.white("your saved credentials")}).`, 0, 0));
+            tui.requestRender();
+            await delay(600);
+            return "ok";
+        }
+        // Env-supplied key: ALWAYS confirm with the user before adopting it.
+        // Just because OPENROUTER_API_KEY (etc.) is exported in the user's
+        // shell does NOT mean they want this onboarding session to consume it.
+        // Auto-accepting silently led to the "I never typed a key, why is it
+        // already connected?" footgun. Default to No (defensive opt-in) so
+        // pressing Enter falls through to the typed-key prompt.
+        //
+        // Wording rationale: "shell environment" is portable across PowerShell,
+        // bash, zsh, fish, cmd, etc. The previous "(env, sk-…)" label was too
+        // cryptic — "env" could be read as brigade.json::env OR shell env, and
+        // users who had just run `Remove-Item -Recurse ~/.brigade` (or the bash
+        // equivalent) couldn't tell where the credential was coming from. Be
+        // explicit so they immediately know the key originated from THEIR shell,
+        // not from a stale brigade.json.
+        const envVar = provider.envVar ?? "the env var";
+        renderScreen(tui, `Step 2 of 3 · ${provider.name}`);
+        tui.addChild(new Text(brand.dim(`  Brigade detected this key in your shell environment.`), 0, 0));
+        tui.addChild(new Text(brand.dim(`  Picking "Yes" persists it to ~/.brigade/brigade.json (so it survives shell restarts and machine moves).`), 0, 0));
+        tui.addChild(new Text("", 0, 0));
+        tui.addChild(new Text(`  ${brand.amber("?")} Use ${envVar} from your shell environment (${formatApiKeyPreview(existing)})?`, 0, 0));
+        tui.addChild(new Text(brand.dim(`  Pick "No" to paste a different ${provider.name} key instead.`), 0, 0));
+        tui.addChild(new Text("", 0, 0));
+        const confirmList = new SelectList([
+            { value: "no", label: "No, let me paste a different key" },
+            { value: "yes", label: "Yes, use the shell-env value" },
+        ], 2, selectListTheme, { minPrimaryColumnWidth: 36, maxPrimaryColumnWidth: 48 });
+        confirmList.setSelectedIndex(0); // defensive: default = No
+        tui.addChild(confirmList);
+        tui.setFocus(confirmList);
         tui.requestRender();
-        await delay(600);
-        return "ok";
+        let confirmChoice;
+        try {
+            const chosen = await new Promise((resolve, reject) => {
+                confirmList.onSelect = (item) => resolve(item);
+                confirmList.onCancel = () => reject(new Error("back"));
+            });
+            confirmChoice = chosen.value === "yes" ? "yes" : "no";
+        }
+        catch {
+            return "back";
+        }
+        tui.removeChild(confirmList);
+        if (confirmChoice === "no") {
+            // User declined the env key — skip the validation path entirely
+            // and let them paste their own. The typed-key loop below treats
+            // `lastError === null` as a clean first iteration, so no stale
+            // error text leaks in.
+            renderScreen(tui, `Step 2 of 3 · Connect ${provider.name}`);
+            // Fall through to typed-key loop without `lastError` set.
+            // (Variable declared just below the env block.)
+            return await promptTypedKey(tui, authStorage, provider, providerId, null);
+        }
+        // User confirmed — verify the env key actually works before accepting.
+        tui.addChild(new Text(`  ${brand.dim(`Verifying ${envVar} with ${provider.name}…`)}`, 0, 0));
+        const envLoader = new CancellableLoader(tui, (s) => brand.amber(s), (s) => brand.dim(s), `Verifying ${provider.name}…`);
+        tui.addChild(envLoader);
+        tui.requestRender();
+        const envCheck = await validateApiKeyOnline(providerId, existing);
+        tui.removeChild(envLoader);
+        if (envCheck.ok) {
+            // State-isolation contract: everything Brigade needs lives under
+            // `~/.brigade/`. The env var that fed us this key is owned by the
+            // user's shell, so without persisting it here, `rm -rf ~/.brigade`
+            // would NOT actually wipe auth — the key would sneak back in via
+            // env detection on the next boot. Mirror it into brigade.json::env
+            // so the file is the canonical home for the credential.
+            await persistEnvKeyToBrigadeConfig(provider, existing);
+            tui.addChild(new Text(`  ${brand.amber("✓")} ${provider.name} is already connected (using ${brand.white("your environment")}).`, 0, 0));
+            tui.requestRender();
+            await delay(600);
+            return "ok";
+        }
+        // Stale env var (user confirmed but it failed validation). Don't auto-
+        // skip — drop into the typed-key path with the failure seeded so the
+        // user immediately sees WHY their env key didn't work and can paste a
+        // fresh one.
+        const staleReason = `The ${provider.envVar ?? "env var"} for ${provider.name} doesn't work: ${envCheck.reason}`;
+        return await promptTypedKey(tui, authStorage, provider, providerId, staleReason);
     }
+    return await promptTypedKey(tui, authStorage, provider, providerId, null);
+}
+/**
+ * Typed-key entry loop, extracted so both the env-confirm-no path and the
+ * no-env-key path can share it without duplicating the retry/validate dance.
+ *
+ * `seedError` lets the caller pre-render an error line above the input —
+ * used when a confirmed env key fails online validation, so the user sees
+ * "the env var didn't work" reason instead of a blank "paste your key" prompt.
+ *
+ * Returns:
+ *   - "ok"   → key validated and persisted
+ *   - "back" → user pressed Esc; caller rewinds to provider picker
+ */
+async function promptTypedKey(tui, authStorage, provider, providerId, seedError) {
     // Retry loop. Each iteration re-renders the screen so old error lines and
     // stale loader frames don't pile up vertically.
-    let lastError = null;
+    let lastError = seedError;
     while (true) {
         renderScreen(tui, `Step 2 of 3 · Connect ${provider.name}`);
         if (lastError) {
@@ -203,6 +330,12 @@ async function ensureApiKey(tui, authStorage, providerId) {
         // Step 3: only persist after both checks pass.
         authStorage.set(providerId, { type: "api_key", key });
         authStorage.reload();
+        // Mirror the credential into brigade.json::env so the unified
+        // super-config remains the canonical state-isolation boundary —
+        // `rm -rf ~/.brigade` reliably wipes everything, including any env
+        // fallback Pi might pick up on a future boot. No-op for providers
+        // that don't have a documented env var (custom OpenAI-compatible).
+        await persistEnvKeyToBrigadeConfig(provider, key);
         const successLine = onlineCheck.modelCount
             ? `${provider.name} connected · ${onlineCheck.modelCount} model${onlineCheck.modelCount === 1 ? "" : "s"} available`
             : `${provider.name} connected`;
@@ -379,6 +512,76 @@ function renderDone(tui, provider, modelId) {
     tui.requestRender();
 }
 /* ────────────────────────────── helpers ───────────────────────────────── */
+/**
+ * Render an API key in a form safe to splat to the terminal/log: shows the
+ * first 4 and last 4 characters separated by an ellipsis, e.g. `sk-o…2b5x`.
+ *
+ * Anything shorter than `head + tail + 4` is rejected as `<too short>` so we
+ * never reveal a meaningful fraction of an 8-char key. Empty/whitespace-only
+ * input returns `<empty>`. The user invokes this in a confirm prompt so they
+ * can recognize *which* key is sitting in their env without us echoing the
+ * whole thing into scrollback (or worse, a bug-report copy-paste).
+ */
+export function formatApiKeyPreview(raw, opts = {}) {
+    const head = opts.head ?? 4;
+    const tail = opts.tail ?? 4;
+    const trimmed = (raw ?? "").trim();
+    if (!trimmed)
+        return "<empty>";
+    // Don't show ANY characters of a key that's too short to safely split —
+    // a 6-char key with head=4/tail=4 would otherwise leak the entire value.
+    if (trimmed.length < head + tail + 4)
+        return "<too short>";
+    return `${trimmed.slice(0, head)}…${trimmed.slice(-tail)}`;
+}
+/**
+ * Persist a validated API key into `~/.brigade/brigade.json::env.<envVar>`.
+ * Goes through `loadBrigadeConfig` + `writeBrigadeConfig` so writes are
+ * atomic + .bak-rotated; never touches the file directly.
+ *
+ * Also pokes `process.env[envVar]` so the in-process agent that's about to
+ * boot sees the credential without needing a restart. (The next boot will
+ * pick it up via `loadEnvIntoProcess` from brigade.json.)
+ *
+ * No-op when the provider has no documented env var (Ollama, custom OpenAI-
+ * compatible) — those are not credential-driven and shouldn't pollute the
+ * env block.
+ *
+ * Failure is non-fatal: a write error here would leave the user with a
+ * working chat session backed by `auth.json` (typed-key path) or the live
+ * env var (env-key path) — better to log and continue than abort the
+ * onboarding the user has already invested time in.
+ */
+async function persistEnvKeyToBrigadeConfig(provider, key) {
+    const envVar = provider.envVar;
+    if (!envVar || envVar.length === 0)
+        return;
+    if (!key || key.length === 0)
+        return;
+    try {
+        const cfg = await loadBrigadeConfig(BRIGADE_DIR);
+        const env = { ...(cfg.env ?? {}) };
+        // Skip a redundant write if the value is already pinned correctly —
+        // avoids a useless .bak rotation (and a useless fsync) when the user
+        // re-runs onboarding with an unchanged env-supplied credential.
+        if (env[envVar] === key) {
+            process.env[envVar] = key;
+            return;
+        }
+        env[envVar] = key;
+        await writeBrigadeConfig(BRIGADE_DIR, { ...cfg, env });
+        // Make the credential visible to the about-to-boot agent without a
+        // restart. brigade.json is now the canonical source; this just
+        // short-circuits "wait for the next process to load it."
+        process.env[envVar] = key;
+    }
+    catch (err) {
+        // Surface to stderr but don't crash onboarding — the credential is
+        // already valid in the running process, so the user can keep chatting.
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`brigade: warning: couldn't persist ${envVar} to brigade.json (${msg})\n`);
+    }
+}
 function clear(tui) {
     for (const child of [...tui.children])
         tui.removeChild(child);

package/dist/ui/terminal-cleanup.js

@@ -0,0 +1,132 @@
+/**
+ * Centralized terminal-state restoration on TUI exit.
+ *
+ * After a Brigade TUI session ends (clean exit, Ctrl+C, crash, signal,
+ * `process.exit`, anything), the user's shell prompt must look like Brigade
+ * was never there. The kitty keyboard protocol in particular is sticky: if
+ * the push (CSI > 1 u) isn't matched by a pop (CSI < u) on the way out,
+ * terminals that support it (Kitty, Ghostty, WezTerm, recent Windows
+ * Terminal) keep emitting key release events into the next program — which
+ * the shell then renders as visible garbage like `[57361;1:3u`.
+ *
+ * Why we don't rely solely on Pi-TUI's ProcessTerminal.stop():
+ *   1. Its kitty pop is gated on a `_kittyProtocolActive` flag that gets
+ *      set lazily after the terminal answers the capability query. If the
+ *      user exits between query-write and response-read, the push happens
+ *      anyway (or rather: kitty mode is left in whatever state the terminal
+ *      already held) and the pop is skipped.
+ *   2. It only runs on graceful `tui.stop()` paths. A crash that bypasses
+ *      `tui.stop()` leaves the terminal in raw + kitty + bracketed-paste
+ *      mode forever.
+ *   3. It never emits the broader safety net (focus reporting, mouse
+ *      tracking, synchronized output, alt-screen) which other libraries
+ *      sometimes leave on.
+ *
+ * `restoreTerminal()` is idempotent — every escape sequence here is a
+ * "disable" or "show", and terminals tolerate disable-when-disabled. Safe
+ * to wire into multiple exit paths and to call repeatedly.
+ *
+ * IMPORTANT: writes go to stderr, never stdout. stderr is the conventional
+ * channel for terminal control and is unbuffered + always-on; stdout might
+ * be redirected to a file or pipe, in which case writing escape sequences
+ * there would corrupt the captured output.
+ */
+import process from "node:process";
+/**
+ * Emit every escape sequence needed to restore the terminal to a known-good
+ * state. Called from every Brigade exit path (signal handlers, normal exit,
+ * crash, `process.on("exit")`).
+ */
+export function restoreTerminal() {
+    const out = process.stderr;
+    try {
+        out.write(
+        // 1. Pop kitty keyboard protocol stack — THE main bug fix. Without
+        //    this, key release events leak into the user's shell as visible
+        //    text like `[57361;1:3u`.
+        "\x1b[<u" +
+            // 2. Disable any pushed kitty modes (extra safety; no-op if
+            //    nothing was pushed). `>0u` clears the current flag set
+            //    explicitly in case the pop above didn't drain it.
+            "\x1b[>0u" +
+            // 3. Disable xterm modifyOtherKeys mode (used by Pi-TUI as a
+            //    tmux fallback when kitty isn't available).
+            "\x1b[>4;0m" +
+            // 4. Disable bracketed paste (Pi-TUI enables `?2004h` on entry).
+            "\x1b[?2004l" +
+            // 5. Show the cursor — Pi-TUI hides it on entry via `?25l`.
+            "\x1b[?25h" +
+            // 6. Disable synchronized output mode (some renderers leave
+            //    this on across an unclean exit).
+            "\x1b[?2026l" +
+            // 7. Disable focus reporting.
+            "\x1b[?1004l" +
+            // 8. Disable every mouse tracking flavor anyone might have on.
+            "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l" +
+            // 9. Reset cursor style to terminal default (DECSCUSR 0).
+            "\x1b[0 q" +
+            // 10. Reset color / SGR attributes so the next prompt isn't
+            //     painted in whatever color we last used.
+            "\x1b[0m" +
+            // 11. Exit alternate screen buffer LAST — biggest visual change,
+            //     and we want every other mode reset while alt screen is
+            //     still active so the cleanup looks tidy if anyone ever
+            //     enables it. Brigade itself doesn't use alt screen, but
+            //     the sequence costs nothing on terminals that aren't in it.
+            "\x1b[?1049l");
+    }
+    catch {
+        // Terminal may already be closed (EPIPE) — nothing to do.
+    }
+}
+/**
+ * Install a single `process.on("exit")` handler that runs `restoreTerminal()`.
+ * Idempotent — registers at most once per process so callers in multiple
+ * subcommand entry points don't stack listeners.
+ *
+ * `process.on("exit")` fires for ALL exit paths (normal return, throw,
+ * signal, `process.exit`, etc.) and is synchronous, which is the right shape
+ * for emitting a single string of bytes to stderr.
+ */
+let exitHandlerInstalled = false;
+export function installTerminalCleanupHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    process.on("exit", restoreTerminal);
+    // Signals that should also flush cleanup before we exit. `process.on("exit")`
+    // alone covers `process.exit()` calls but NOT signal-driven termination
+    // (Node defaults to dying without firing the exit event when an uncaught
+    // signal arrives). Wiring these explicitly guarantees cleanup before the
+    // terminal hands control back to the shell.
+    const signalHandler = (sig) => {
+        restoreTerminal();
+        // Re-raise the default behavior: exit with 128 + signal number convention.
+        // SIGINT → 130, SIGTERM → 143, SIGHUP → 129, SIGQUIT → 131.
+        const code = sig === "SIGINT"
+            ? 130
+            : sig === "SIGTERM"
+                ? 143
+                : sig === "SIGHUP"
+                    ? 129
+                    : sig === "SIGQUIT"
+                        ? 131
+                        : 1;
+        // Use `process.exit` rather than re-raising so the `exit` event fires
+        // (where restoreTerminal will run again, harmlessly, via idempotency).
+        process.exit(code);
+    };
+    // Use addListener (not once) so we don't disarm if any subcommand-specific
+    // handler also fires — but DON'T register if a listener with the same
+    // effective intent already exists (chat-cmd / connect-cmd install their own
+    // SIGINT handlers that call tui.stop() first; ours runs alongside).
+    //
+    // We only register SIGTERM and SIGHUP here. SIGINT is owned by the
+    // per-subcommand handler (which has UI state to tear down — abort an
+    // in-flight turn first, etc.); that handler calls `restoreTerminal()`
+    // directly before `process.exit`, and the `exit` event handler above is
+    // the final safety net.
+    process.on("SIGTERM", signalHandler);
+    process.on("SIGHUP", signalHandler);
+}
+//# sourceMappingURL=terminal-cleanup.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spinabot/brigade",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Brigade — your personal AI crew. Polished terminal CLI for Anthropic, OpenAI, Gemini, Groq, xAI, DeepSeek, Mistral, OpenRouter, Cerebras, Ollama and any OpenAI-compatible endpoint. Built on the Pi SDK.",
   "license": "MIT",
@@ -28,8 +28,7 @@
     "LICENSE",
     "CHANGELOG.md",
     "SECURITY.md",
-    "assets/brigade-wordmark.png",
-    "assets/brigade-wordmark-on-black.png"
+    "assets/brigade-wordmark.png"
   ],
   "keywords": [
     "ai",