@spinabot/brigade 0.1.0

package/dist/ui/onboarding.js

@@ -0,0 +1,400 @@
+/**
+ * First-run onboarding wizard.
+ *
+ * Flow:
+ *   1. Welcome screen
+ *   2. Provider picker (SelectList of curated providers)
+ *   3. API key entry (or detect existing env var)
+ *   4. Model picker (SelectList of models for that provider)
+ *   5. Persist to AuthStorage + Brigade config
+ *   6. Return chosen { provider, modelId }
+ *
+ * Uses Pi-TUI components — same components the chat UI uses, so the visual
+ * language is consistent across the app.
+ */
+import * as path from "node:path";
+import { getEnvApiKey, getModels } from "@mariozechner/pi-ai";
+import { CancellableLoader, Input, SelectList, Text } from "@mariozechner/pi-tui";
+import { BRIGADE_DIR, saveConfig } from "../core/config.js";
+import { discoverOllamaModels, writeOllamaToModelsJson } from "../integrations/ollama.js";
+import { findProvider, PROVIDERS } from "../providers/catalog.js";
+import { validateApiKeyOnline } from "../providers/validate-key.js";
+import { renderBrandHeader } from "./brand.js";
+import { brand, selectListTheme } from "./theme.js";
+/* ────────────────────────────── public API ────────────────────────────── */
+/**
+ * Resolve the model list for a provider. Pi's static `getModels()` only knows
+ * built-in catalogs (Anthropic, OpenAI, Google, etc.); custom providers we
+ * register at runtime via models.json (Ollama) are exposed through
+ * `modelRegistry.getAll()`. Try the static catalog first, then fall back to
+ * the dynamic registry — that way both code paths produce the same `Model<any>[]`
+ * shape that the picker expects.
+ */
+function getProviderModels(modelRegistry, providerId) {
+    try {
+        const fromCatalog = getModels(providerId);
+        if (fromCatalog && fromCatalog.length > 0)
+            return fromCatalog;
+    }
+    catch {
+        /* unknown provider — fall through */
+    }
+    return modelRegistry.getAll().filter((m) => m.provider === providerId);
+}
+export async function runOnboarding(tui, authStorage, modelRegistry) {
+    // 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
+    // recoverable instead of a one-shot abort.
+    let step = "provider";
+    let provider = "";
+    let modelId = "";
+    while (true) {
+        if (step === "provider") {
+            renderScreen(tui, "Step 1 of 3 · Pick a provider");
+            provider = await pickProvider(tui); // throws "onboarding-cancelled" on Esc
+            step = "key";
+            continue;
+        }
+        if (step === "key") {
+            // Local providers (Ollama) skip API-key entry entirely. Instead we
+            // validate the local server is up, discover its model list, and
+            // register the provider in Pi's models.json so step 3 picks it up.
+            const providerInfo = findProvider(provider);
+            if (providerInfo?.local && providerInfo.id === "ollama") {
+                const result = await ensureLocalOllama(tui, modelRegistry, providerInfo.baseUrl ?? "http://localhost:11434");
+                if (result === "back") {
+                    step = "provider";
+                    continue;
+                }
+                step = "model";
+                continue;
+            }
+            const result = await ensureApiKey(tui, authStorage, provider);
+            if (result === "back") {
+                step = "provider";
+                continue;
+            }
+            modelRegistry.refresh(); // re-evaluate available models with the new key
+            step = "model";
+            continue;
+        }
+        // step === "model"
+        renderScreen(tui, "Step 3 of 3 · Default model");
+        const result = await pickModel(tui, modelRegistry, provider);
+        if (result === "back") {
+            step = "provider"; // go all the way back so they can change provider too
+            continue;
+        }
+        modelId = result.modelId;
+        break;
+    }
+    await saveConfig({ defaultProvider: provider, defaultModelId: modelId });
+    renderScreen(tui, ""); // brand-only frame for the "Ready." moment
+    renderDone(tui, provider, modelId);
+    await delay(900);
+    clear(tui);
+    return { provider, modelId };
+}
+/* ────────────────────────── screen scaffolding ────────────────────────── */
+/** Wipe everything, render the chunky brand header, then a sub-header line. */
+function renderScreen(tui, subheader) {
+    clear(tui);
+    renderBrandHeader(tui);
+    if (subheader) {
+        tui.addChild(new Text(brand.dim("  " + "─".repeat(54)), 0, 0));
+        tui.addChild(new Text("", 0, 0));
+        tui.addChild(new Text(`  ${brand.amber(subheader)}`, 0, 0));
+        tui.addChild(new Text("", 0, 0));
+        tui.requestRender();
+    }
+}
+/* ────────────────────────────── steps ─────────────────────────────────── */
+async function pickProvider(tui) {
+    const items = PROVIDERS.map((p) => ({
+        value: p.id,
+        label: p.name,
+        description: p.description,
+    }));
+    const list = new SelectList(items, Math.min(items.length, 9), selectListTheme, {
+        minPrimaryColumnWidth: 18,
+        maxPrimaryColumnWidth: 22,
+    });
+    tui.addChild(list);
+    tui.setFocus(list);
+    tui.requestRender();
+    const chosen = await new Promise((resolve, reject) => {
+        list.onSelect = (item) => resolve(item);
+        list.onCancel = () => reject(new Error("onboarding-cancelled"));
+    });
+    return chosen.value;
+}
+/**
+ * Prompt for the API key, validate it (locally + online), persist on success.
+ * Returns:
+ *   - "ok"   → key is valid and saved (or already existed)
+ *   - "back" → user pressed Esc; caller should rewind to the previous step
+ *
+ * Loops on validation failure: the user sees "Wrong key — <reason>" inline
+ * 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) {
+    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);
+    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));
+        tui.requestRender();
+        await delay(600);
+        return "ok";
+    }
+    // Retry loop. Each iteration re-renders the screen so old error lines and
+    // stale loader frames don't pile up vertically.
+    let lastError = null;
+    while (true) {
+        renderScreen(tui, `Step 2 of 3 · Connect ${provider.name}`);
+        if (lastError) {
+            tui.addChild(new Text(`  ${brand.error("✗")} ${brand.error(lastError)}`, 0, 0));
+            tui.addChild(new Text(brand.dim("  Press Enter to try again, or Esc to choose a different provider."), 0, 0));
+            tui.addChild(new Text("", 0, 0));
+        }
+        tui.addChild(new Text(`  Paste your ${provider.name} API key.`, 0, 0));
+        tui.addChild(new Text(brand.dim(`  We'll keep it private to this device.  Need a key? ${provider.keyUrl}`), 0, 0));
+        tui.addChild(new Text(brand.dim("  Enter to continue  ·  Esc to go back"), 0, 0));
+        tui.addChild(new Text("", 0, 0));
+        const input = new Input();
+        tui.addChild(input);
+        tui.setFocus(input);
+        tui.requestRender();
+        let key;
+        try {
+            key = await new Promise((resolve, reject) => {
+                input.onSubmit = (value) => resolve(value.trim());
+                input.onEscape = () => reject(new Error("back"));
+            });
+        }
+        catch {
+            return "back"; // user pressed Esc — caller rewinds to provider picker
+        }
+        // Step 1: cheap local format check (length, whitespace, prefix).
+        const localCheck = validateApiKey(providerId, key);
+        if (!localCheck.ok) {
+            lastError = localCheck.reason;
+            continue;
+        }
+        // Step 2: live online validation against the provider's /v1/models endpoint.
+        // This catches revoked / wrong-provider / typo'd keys BEFORE we persist.
+        tui.addChild(new Text("", 0, 0));
+        const loader = new CancellableLoader(tui, (s) => brand.amber(s), (s) => brand.dim(s), `Verifying with ${provider.name}…`);
+        tui.addChild(loader);
+        tui.requestRender();
+        const onlineCheck = await validateApiKeyOnline(providerId, key);
+        tui.removeChild(loader);
+        if (!onlineCheck.ok) {
+            lastError = onlineCheck.reason;
+            continue;
+        }
+        // Step 3: only persist after both checks pass.
+        authStorage.set(providerId, { type: "api_key", key });
+        authStorage.reload();
+        const successLine = onlineCheck.modelCount
+            ? `${provider.name} connected · ${onlineCheck.modelCount} model${onlineCheck.modelCount === 1 ? "" : "s"} available`
+            : `${provider.name} connected`;
+        tui.addChild(new Text(`  ${brand.amber("✓")} ${successLine}.`, 0, 0));
+        if (onlineCheck.warning) {
+            tui.addChild(new Text(`  ${brand.dim("Note: " + onlineCheck.warning)}`, 0, 0));
+        }
+        tui.requestRender();
+        await delay(500);
+        return "ok";
+    }
+}
+/**
+ * Cheap, provider-aware sanity check on the pasted key.
+ * Catches obvious mistakes (empty, accidental newline, wrong provider's key)
+ * BEFORE we persist garbage to disk. Doesn't validate against the real API —
+ * that happens implicitly on the first model call.
+ */
+function validateApiKey(providerId, key) {
+    if (!key)
+        return { ok: false, reason: "Please enter an API key." };
+    if (key.length < 16)
+        return { ok: false, reason: `That looks incomplete (only ${key.length} characters). Try copying the key again.` };
+    if (/\s/.test(key))
+        return { ok: false, reason: "The key has extra spaces or line breaks. Copy just the key value." };
+    // Provider-specific prefix hints. Hard reject only when we have a stable, well-known prefix
+    // for that provider — we never want to block someone with a freshly-rotated format.
+    // For providers without a stable prefix (cerebras, mistral) we fall through to length+whitespace
+    // only, which is intentional.
+    const prefixHints = {
+        anthropic: "sk-ant-",
+        openai: "sk-",
+        google: "AIza", // Google API keys (Gemini Studio) all start with AIza
+        groq: "gsk_",
+        openrouter: "sk-or-",
+        xai: "xai-",
+        deepseek: "sk-", // DeepSeek mirrors OpenAI's prefix convention
+    };
+    const expected = prefixHints[providerId];
+    const providerName = findProvider(providerId)?.name ?? providerId;
+    if (expected && !key.startsWith(expected)) {
+        return {
+            ok: false,
+            reason: `That doesn't look like a ${providerName} key (${providerName} keys start with "${expected}"). Make sure you picked the right provider.`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Local-provider variant of `ensureApiKey`. For Ollama:
+ *   1. Ping `/api/tags` to confirm the daemon is running.
+ *   2. List the user's locally-pulled models.
+ *   3. Write the provider config (and inferred model definitions) into
+ *      `~/.brigade/models.json` so Pi's `ModelRegistry` exposes them.
+ *   4. Refresh the registry so the next step's model picker can see them.
+ *
+ * If discovery fails, show a friendly error with the next step the user
+ * needs to take (start the daemon, pull a model). Esc returns "back".
+ */
+async function ensureLocalOllama(tui, modelRegistry, baseUrl) {
+    let lastError = null;
+    while (true) {
+        renderScreen(tui, "Step 2 of 3 · Connect Ollama");
+        if (lastError) {
+            tui.addChild(new Text(`  ${brand.error("✗")} ${brand.error(lastError)}`, 0, 0));
+            tui.addChild(new Text(brand.dim("  Press Enter to try again, or Esc to choose a different provider."), 0, 0));
+            tui.addChild(new Text("", 0, 0));
+        }
+        tui.addChild(new Text(`  Brigade will scan your local Ollama for available models.`, 0, 0));
+        tui.addChild(new Text(brand.dim(`  Don't have Ollama yet? Get it at https://ollama.com/download`), 0, 0));
+        tui.addChild(new Text(brand.dim("  Enter to scan  ·  Esc to go back"), 0, 0));
+        // Use an Input as a confirm-prompt — user just hits Enter (or Esc).
+        const confirm = new Input();
+        tui.addChild(confirm);
+        tui.setFocus(confirm);
+        tui.requestRender();
+        try {
+            await new Promise((resolve, reject) => {
+                confirm.onSubmit = () => resolve();
+                confirm.onEscape = () => reject(new Error("back"));
+            });
+        }
+        catch {
+            return "back";
+        }
+        // Discover models with a loader spinner.
+        const loader = new CancellableLoader(tui, (s) => brand.amber(s), (s) => brand.dim(s), "Scanning Ollama…");
+        tui.addChild(loader);
+        tui.requestRender();
+        let discovered;
+        try {
+            discovered = await discoverOllamaModels(baseUrl);
+        }
+        catch (err) {
+            tui.removeChild(loader);
+            lastError = err instanceof Error ? err.message : String(err);
+            continue;
+        }
+        // Persist the provider entry so Pi sees the models from now on.
+        const modelsJsonPath = path.join(BRIGADE_DIR, "models.json");
+        try {
+            await writeOllamaToModelsJson(modelsJsonPath, baseUrl, discovered);
+            modelRegistry.refresh();
+        }
+        catch (err) {
+            tui.removeChild(loader);
+            lastError = `Couldn't save the connection: ${err instanceof Error ? err.message : String(err)}`;
+            continue;
+        }
+        tui.removeChild(loader);
+        tui.addChild(new Text(`  ${brand.amber("✓")} Ollama connected · ${brand.white(String(discovered.length))} model${discovered.length === 1 ? "" : "s"} available.`, 0, 0));
+        tui.requestRender();
+        await delay(500);
+        return "ok";
+    }
+}
+async function pickModel(tui, modelRegistry, providerId) {
+    const models = getProviderModels(modelRegistry, providerId);
+    if (models.length === 0) {
+        tui.addChild(new Text(brand.dim("  Type the model name you'd like to use, then press Enter. Esc to go back."), 0, 0));
+        const input = new Input();
+        tui.addChild(input);
+        tui.setFocus(input);
+        tui.requestRender();
+        try {
+            const id = await new Promise((resolve, reject) => {
+                input.onSubmit = (value) => resolve(value.trim());
+                input.onEscape = () => reject(new Error("back"));
+            });
+            return { modelId: id };
+        }
+        catch {
+            return "back";
+        }
+    }
+    const items = models.map((m) => ({
+        value: m.id,
+        label: m.id,
+        description: describeModel(m),
+    }));
+    // Default-first ordering: reasoning > non-reasoning, then larger context first.
+    items.sort((a, b) => {
+        const ma = models.find((m) => m.id === a.value);
+        const mb = models.find((m) => m.id === b.value);
+        if (!ma || !mb)
+            return 0;
+        if (!!ma.reasoning !== !!mb.reasoning)
+            return ma.reasoning ? -1 : 1;
+        return (mb.contextWindow ?? 0) - (ma.contextWindow ?? 0);
+    });
+    const list = new SelectList(items, Math.min(items.length, 12), selectListTheme, {
+        minPrimaryColumnWidth: 26,
+        maxPrimaryColumnWidth: 38,
+    });
+    tui.addChild(list);
+    tui.setFocus(list);
+    tui.requestRender();
+    try {
+        const chosen = await new Promise((resolve, reject) => {
+            list.onSelect = (item) => resolve(item);
+            list.onCancel = () => reject(new Error("back"));
+        });
+        return { modelId: chosen.value };
+    }
+    catch {
+        return "back";
+    }
+}
+function renderDone(tui, provider, modelId) {
+    const p = findProvider(provider)?.name ?? provider;
+    tui.addChild(new Text("", 0, 0));
+    tui.addChild(new Text(`  ${brand.amber("●")} ${brand.white("Ready.")}  ${brand.dim(`${p} · ${modelId}`)}`, 0, 0));
+    tui.addChild(new Text("", 0, 0));
+    tui.requestRender();
+}
+/* ────────────────────────────── helpers ───────────────────────────────── */
+function clear(tui) {
+    for (const child of [...tui.children])
+        tui.removeChild(child);
+    tui.requestRender();
+}
+function describeModel(m) {
+    const parts = [];
+    if (m.reasoning)
+        parts.push("reasoning");
+    if (m.contextWindow)
+        parts.push(`${Math.round(m.contextWindow / 1000)}k ctx`);
+    if (m.cost?.input)
+        parts.push(`$${m.cost.input.toFixed(2)}/Mtok in`);
+    return parts.join(" · ");
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/ui/theme.js

@@ -0,0 +1,51 @@
+/**
+ * Shared Pi-TUI themes for Brigade.
+ *
+ * One canonical place so onboarding + chat feel like the same app.
+ */
+import chalk from "chalk";
+export const markdownTheme = {
+    heading: (s) => chalk.bold.hex("#fbbf24")(s), // amber
+    link: (s) => chalk.hex("#60a5fa")(s),
+    linkUrl: (s) => chalk.dim(s),
+    code: (s) => chalk.hex("#fde7c4")(s),
+    codeBlock: (s) => chalk.hex("#a7f3d0")(s),
+    codeBlockBorder: (s) => chalk.dim.hex("#92400e")(s),
+    quote: (s) => chalk.italic.hex("#fde7c4")(s),
+    quoteBorder: (s) => chalk.dim.hex("#92400e")(s),
+    hr: (s) => chalk.dim(s),
+    listBullet: (s) => chalk.hex("#fbbf24")(s),
+    bold: (s) => chalk.bold(s),
+    italic: (s) => chalk.italic(s),
+    strikethrough: (s) => chalk.strikethrough(s),
+    underline: (s) => chalk.underline(s),
+};
+export const editorTheme = {
+    borderColor: (s) => chalk.dim(s),
+    selectList: {
+        selectedPrefix: (s) => chalk.hex("#fbbf24")(s),
+        selectedText: (s) => chalk.bold(s),
+        description: (s) => chalk.dim(s),
+        scrollInfo: (s) => chalk.dim(s),
+        noMatch: (s) => chalk.dim(s),
+    },
+};
+export const selectListTheme = {
+    selectedPrefix: (s) => chalk.hex("#fbbf24")(s),
+    selectedText: (s) => chalk.bold(s),
+    description: (s) => chalk.dim(s),
+    scrollInfo: (s) => chalk.dim(s),
+    noMatch: (s) => chalk.dim("  No matching option"),
+};
+/** Brand color helpers (used for status bars, dividers, accents). */
+export const brand = {
+    amber: (s) => chalk.hex("#fbbf24")(s),
+    amberDeep: (s) => chalk.hex("#92400e")(s),
+    dim: (s) => chalk.dim(s),
+    white: (s) => chalk.white(s),
+    user: (s) => chalk.bold.hex("#60a5fa")(s),
+    agent: (s) => chalk.bold.hex("#fbbf24")(s),
+    tool: (s) => chalk.hex("#a7f3d0")(s),
+    error: (s) => chalk.bold.hex("#fca5a5")(s),
+};
+//# sourceMappingURL=theme.js.map

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@spinabot/brigade",
+  "version": "0.1.0",
+  "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",
+  "author": "Bhasvanth Dev",
+  "homepage": "https://github.com/Bhasvanth-Dev9380/brigade#readme",
+  "bugs": {
+    "url": "https://github.com/Bhasvanth-Dev9380/brigade/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bhasvanth-Dev9380/brigade.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "brigade": "brigade.mjs"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "brigade.mjs",
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "assets/brigade-wordmark.png",
+    "assets/brigade-wordmark-on-black.png"
+  ],
+  "keywords": [
+    "ai",
+    "cli",
+    "tui",
+    "llm",
+    "chat",
+    "agent",
+    "anthropic",
+    "claude",
+    "openai",
+    "gpt",
+    "gemini",
+    "ollama",
+    "openrouter",
+    "groq",
+    "xai",
+    "deepseek",
+    "mistral",
+    "cerebras",
+    "pi-sdk"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "chat": "tsx src/cli.ts chat",
+    "gateway": "tsx src/cli.ts gateway",
+    "connect": "tsx src/cli.ts connect",
+    "doctor": "tsx src/cli.ts doctor",
+    "onboard": "tsx src/cli.ts onboard",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "biome format --write .",
+    "gen:wordmark": "node scripts/gen-wordmark-svg.mjs",
+    "prepublishOnly": "npm run build",
+    "prepack": "node scripts/prepack.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "0.70.6",
+    "@mariozechner/pi-ai": "0.70.6",
+    "@mariozechner/pi-coding-agent": "0.70.6",
+    "@mariozechner/pi-tui": "0.70.6",
+    "@types/ws": "^8.18.1",
+    "cfonts": "^3.3.1",
+    "chalk": "^5.3.0",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.7.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}