@kinqs/brainrouter-mcp-server 0.3.6 → 0.3.8

package/README.md

@@ -34,7 +34,7 @@ Verify:
 
 ```bash
 which brainrouter-mcp
-brainrouter-mcp --version    # prints 0.3.5
+brainrouter-mcp --version    # prints 0.3.7
 ```
 
 ---

package/dist/api/auth/crypto.js

@@ -37,9 +37,14 @@ export function verifyJwt(token, secret) {
     if (parts.length !== 3)
         return null;
     const [header, claims, signature] = parts;
-    const expected = createHmac("sha256", secret).update(`${header}.${claims}`).digest();
-    const actual = Buffer.from(signature, "base64url");
-    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+    // Compare in base64url string space so single-character changes to padding
+    // bits (e.g. "A" → "B" at the last position of a 32-byte HMAC) are caught.
+    // Raw-byte comparison misses these because base64url decoding ignores the
+    // bottom 2 bits of the final character.
+    const expected = createHmac("sha256", secret).update(`${header}.${claims}`).digest("base64url");
+    const expBuf = Buffer.from(expected);
+    const actBuf = Buffer.from(signature);
+    if (expBuf.length !== actBuf.length || !timingSafeEqual(expBuf, actBuf))
         return null;
     try {
         const payload = JSON.parse(base64UrlDecode(claims).toString("utf8"));

package/dist/index.js

@@ -102,7 +102,7 @@ const PORT = parseInt(parseFlag('--port') ?? '3747', 10);
 function buildMcpServer(registry, options) {
     const defaultUserId = options?.defaultUserId ?? STDIO_DEFAULT_USER_ID;
     const isAdmin = options?.isAdmin ?? false;
-    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.5' }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.7' }, { capabilities: { tools: {} } });
     // ── Tool list ──────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [

package/docs/specs/0.3.7-terminal-ui-redesign.md

@@ -0,0 +1,259 @@
+# Spec: 0.3.7 Item 6 — Terminal UI redesign + in-terminal config wizard
+
+> Status: drafted, awaiting implementation. See [Tasks.md](../../Tasks.md)
+> for live progress. Pairs with [`brainrouter-roadmap/0.3.7.md`](../../brainrouter-roadmap/0.3.7.md)
+> as the headline feature of the 0.3.7 cycle.
+
+## Objective
+
+Make BrainRouter's CLI feel like Claude Code / OpenCode / Codex / Grok-CLI
+/ DeepSeek-TUI — **especially around in-terminal, picker-driven
+configuration**. Today a first-run user has to:
+
+1. Run `brainrouter login` outside the REPL → answers a sequence of
+   `inquirer` text prompts → exits.
+2. Run `brainrouter config` outside the REPL → answers another sequence
+   of text prompts → exits.
+3. Then start `brainrouter` (the chat REPL) and discover everything else
+   (`/theme`, `/personality`, `/effort`, `/mode`, statusline) via
+   `/help` or by hand-editing JSON.
+
+Peer CLIs do this differently:
+
+- **Claude Code** — `/config` opens a tabbed settings panel; `/theme`,
+  `/model`, `/login` are arrow-key pickers; first-run shows a welcome
+  card → onboarding wizard with a step counter.
+- **Codex** — `Step::{Welcome, Auth, TrustDirectory}` state machine
+  drives the onboarding; one modal owns multiple sub-states (`PickMode`
+  → `ApiKeyEntry`) via an enum.
+- **DeepSeek-TUI** — `/config` is verb-overloaded: bare opens a picker,
+  `<key>` shows, `<key> <val>` sets session, `<key> <val> --save`
+  persists. Provider picker uses a single modal with `Stage::{List,
+  KeyEntry}`; selecting an un-configured provider transitions the same
+  modal into key entry.
+- **Grok-CLI** — first-run is a render-time `ApiKeyModal` overlay
+  inside the REPL, not a separate `login` subcommand. Each settings
+  surface (`/models`, `/mcp`, `/sandbox`, `/wallet`) is its own modal
+  that merges through a single `saveUserSettings(partial)`.
+
+We adopt the **render-time modal** + **state-enum** + **verb-overloaded
+slash command** patterns, on top of our existing
+`brainrouter-cli/src/cli/cliPrompt.ts` picker primitive.
+
+## Non-goals
+
+- A full Ratatui/Ink-style fullscreen renderer. That's the 0.5.0 cycle.
+- Replacing `readline` as the REPL composer. We extend the existing
+  raw-mode picker; we do not rewrite the input loop.
+- Multi-provider OAuth flows. v0.3.7 keeps API-key auth; OAuth /
+  device-code can be a follow-up once the wizard skeleton lands.
+- Touching the MCP server's config (`~/.config/brainrouter/server.env`).
+  The wizard reads/writes only the CLI-owned files:
+  `~/.config/brainrouter/config.json` and
+  `<workspace>/.brainrouter/cli/preferences.json`.
+
+## Tech stack
+
+- Same as the rest of `brainrouter-cli/`: TypeScript on Node 22+, ESM,
+  Vitest, `chalk` for color, our own `cliPrompt.askChoice` for the
+  arrow-key picker.
+- `inquirer` is deliberately **removed from the new flows** — its
+  competing readline interface is the bug that motivated `cliPrompt.ts`
+  in the first place. Legacy `brainrouter login` / `brainrouter config`
+  subcommands stay (for back-compat) but the docs steer users at the
+  new in-REPL flows.
+
+## Slash command surface
+
+Following the verb-overload pattern from DeepSeek-TUI:
+
+| Command | Behaviour |
+| --- | --- |
+| `/init` | Re-runs the first-run onboarding wizard (theme → provider → model → MCP → done). Idempotent; safe to re-run. **Aliased from the old `/init` which only wrote `AGENT.md`** — that one-shot is folded into the wizard's final step as an opt-in toggle so we don't regress for users who relied on it. |
+| `/config` | Bare — opens the **settings home panel** (picker over: LLM, MCP, Theme, Statusline, Effort, Mode, Quiet, Personality, Editor mode, View raw config). |
+| `/config <key>` | Show current value for `<key>` (e.g. `/config theme` → `theme: dark (preference)`). |
+| `/config <key> <value>` | Set `<key>` to `<value>` and persist (writes to `~/.config/brainrouter/config.json` for LLM/MCP knobs, `<workspace>/.brainrouter/cli/preferences.json` for prefs). |
+| `/login` | NEW slash alias for the old `brainrouter login` flow — opens the **MCP profile editor** in-REPL (transport picker → fields → reachability test → save). The standalone `brainrouter login` CLI subcommand stays for first-run-before-REPL use. |
+| `/logout` | Already exists; unchanged. Clears API keys from the active profile. |
+| `/theme` | Already exists. Extended with `/theme` (bare) opening the picker (live-preview the banner + prompt accent on cursor-change), confirming via ENTER, restoring on Esc. |
+| `/model` | Already exists. Extended with bare-`/model` opening a picker over a curated short-list (gpt-4o-mini, gpt-4o, gpt-5, claude-sonnet-4, deepseek-v4, qwen3-coder, …) + "Other" for free-text. |
+
+The bare `/config` panel is the **settings home** — it's the screen
+that lets users discover every knob without needing to memorise the
+slash vocabulary.
+
+## Onboarding wizard (`/init`)
+
+State machine — same shape as Codex `Step` and DeepSeek
+`OnboardingState`:
+
+```
+Welcome → Theme → Provider → ApiKey → Model → MCP → AgentMd → Done
+```
+
+- **Welcome** — a single boxed card (~5 lines) introducing
+  BrainRouter, what gets configured, and where (path of
+  `~/.config/brainrouter/config.json`). ENTER continues, q quits
+  without writing.
+- **Theme** — arrow-key picker over `dark / light / mono / auto`,
+  with **live preview**: on cursor-change, redraw the banner accent so
+  the user sees the change before confirming. Persists to
+  `preferences.theme` on confirm.
+- **Provider** — picker over a curated provider list:
+  `OpenAI · DeepSeek · OpenRouter · Anthropic (via gateway) · Gemini
+  (OpenAI-compat) · LM Studio (local) · Ollama (local) · Custom…`.
+  Each row shows a one-line hint (endpoint, "(local)" / "(cloud)",
+  needs-key indicator). Pre-detects from env vars
+  (`OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, etc.)
+  — pre-selects the row whose key is already present in the shell.
+- **ApiKey** — free-text entry (re-uses the picker's `awaitingOther`
+  free-text mode). Pre-filled from env when available. Validation
+  tier `Accept{warning?}` / `Reject(reason)`: empty for local
+  endpoints is OK; non-empty with `sk-`-shape prefix or vendor-known
+  shape is OK; everything else is **accepted with a warning** (not
+  rejected — vendors invent new prefixes all the time). Mask to last
+  4 chars after entry.
+- **Model** — picker over the provider's curated short-list +
+  "Other" for free-text. Defaults: OpenAI → `gpt-4o-mini`, DeepSeek
+  → `deepseek-chat`, OpenRouter → `anthropic/claude-sonnet-4`,
+  LM Studio → blank (user picks from loaded models), etc.
+- **MCP** — picker over `Local stdio (brainrouter-mcp on PATH) ·
+  Local HTTP (http://localhost:3747/mcp) · Remote HTTP… (free-text
+  URL) · Skip (offline-only)`. On confirm, run a single
+  `mcpClient.listTools()` reachability test (5s timeout); on success
+  save the profile and mark it active; on failure offer "save
+  anyway" / "try a different transport" / "skip".
+- **AgentMd** — yes/no: "Write AGENT.md to this workspace? (helps
+  agents understand your repo conventions)". Defaults to **yes** if
+  no `AGENT.md` / `CLAUDE.md` exists yet, **no** otherwise. This is
+  the toggle that absorbs the old `/init` behaviour.
+- **Done** — summary card showing the saved config (with API keys
+  masked) + next steps (`/help`, `/config`, `/where`). Marker file
+  written to `~/.config/brainrouter/.onboarded` so subsequent CLI
+  starts skip the wizard. Re-running `/init` is always allowed.
+
+**Skip semantics.** At any step `Esc` backs out one state; `q`
+aborts the whole wizard with **no changes saved** (everything is
+journalled in-memory until the Done step commits the write).
+
+**Auto-trigger.** When the user runs `brainrouter` (the chat command)
+and no `~/.config/brainrouter/config.json` exists, instead of the
+current "Run \`brainrouter login\` …" error-and-exit, we drop them
+**straight into the wizard inside the REPL** (no separate subcommand).
+This is the grok-cli `ApiKeyModal` pattern — the modal IS the
+onboarding.
+
+## Settings home panel (`/config`)
+
+Picker over the settings categories. Each row shows the current value
+on the right so the user can scan the state at a glance:
+
+```
+┌─ ⚙️  BrainRouter Config ────────────────────────────────────────┐
+│                                                                 │
+│  ▶ LLM provider       openai · gpt-4o-mini                      │
+│    MCP profile        default · http · 🟢 online                │
+│    Theme              dark                                      │
+│    Statusline         mode,branch,workflow,goal                 │
+│    Reasoning effort   medium                                    │
+│    Execution mode     planning                                  │
+│    Review policy      request                                   │
+│    Quiet mode         off                                       │
+│    Personality        standard                                  │
+│    Editor mode        emacs                                     │
+│                                                                 │
+│    View raw config                                              │
+│    Quit (Esc)                                                   │
+│                                                                 │
+│  ↑/↓ navigate  ·  ENTER edit  ·  Esc to quit                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Selecting a row opens the appropriate sub-picker (provider picker,
+theme picker, etc.). On confirm, returns to the home panel with the
+new value visible. Esc backs out one level (sub-picker → home → exit).
+
+The "View raw config" row prints the scrubbed JSON (today's bare
+`/config` behaviour) so users who prefer the JSON view can still get
+it without leaving the panel.
+
+## Persistence contract
+
+One central writer per file. No scattered `fs.writeFileSync` calls.
+
+| File | Wrapper | Owns |
+| --- | --- | --- |
+| `~/.config/brainrouter/config.json` | `saveConfig(partial)` in [`config/config.ts`](../../brainrouter-cli/src/config/config.ts) — existing function, called with the merged result. | LLM provider, MCP profiles, active profile. |
+| `<workspace>/.brainrouter/cli/preferences.json` | `writePreferences(workspaceRoot, partial)` in [`state/preferencesStore.ts`](../../brainrouter-cli/src/state/preferencesStore.ts) — existing function; already merges. | Theme, statusline, effort, exec mode, review policy, quiet, personality, editor, sandbox grants. |
+| `~/.config/brainrouter/.onboarded` | New `markOnboarded()` helper alongside `config/config.ts`. | Empty file; presence = wizard has run at least once. |
+
+The wizard accumulates intent in an in-memory `Draft` object across
+all steps; the commit happens **once** at the Done step. Aborting via
+`q` discards the draft.
+
+## Picker primitive — additions to `cliPrompt.ts`
+
+Today's `askChoice` is sufficient for confirm-only pickers; the
+redesign needs two new behaviours we can fold in as optional fields:
+
+1. **`onCursorChange(index)` callback** — fired by `reducePicker` after
+   an `up`/`down` keystroke if the option list moved. Theme picker
+   uses it to repaint the banner accent live.
+2. **`prefilledOther?: string`** — when the wizard wants to drop the
+   user straight into the `awaitingOther` free-text input pre-filled
+   with the env-var value (so ENTER accepts the env-derived default,
+   editing overrides it).
+
+Both are additive; existing callers keep working with `undefined`.
+
+## Boundary rules (per `spec-driven-skill`)
+
+- **Always:** route all settings persistence through
+  `saveConfig` / `writePreferences`; mask API keys to last 4 chars on
+  every render; pause the parent `rl` while a picker is active; close
+  with the cursor visible.
+- **Ask first:** changing `~/.config/brainrouter/config.json` shape
+  (any new top-level key) — needs explicit user sign-off because it
+  surfaces in `/debug-config`.
+- **Never:** write API keys to disk in plain text under the workspace
+  (only under `~/.config/brainrouter/`); silently overwrite an
+  existing config without confirmation; default to option 1 in
+  non-TTY mode (mirrors the existing `NoTTYError` contract).
+
+## Definition of Done
+
+1. `brainrouter` started against a clean `$HOME` (no `~/.config/brainrouter/`)
+   drops into the wizard automatically — no `brainrouter login`
+   needed.
+2. `/init` re-runs the wizard at any time inside the REPL.
+3. `/config` (bare) opens the settings home panel; arrow-keys
+   navigate; ENTER opens a sub-picker; Esc backs out.
+4. `/config theme dark` sets theme to dark and prints the new value
+   without opening any picker.
+5. Theme picker live-previews on cursor-change and restores the
+   original theme if the user presses Esc.
+6. Tests: pure-function tests for the wizard reducer (`stepReducer`,
+   `Draft` shape, validation tier), `Vitest` tests for the
+   `/config` argument parser (bare / get / set), and one
+   `cliPrompt.ts` test for the new `onCursorChange` callback.
+7. Docs: `brainrouter-docs/cli.md` and `brainrouter-docs/configuration.md`
+   are updated end-to-end. README's "First-time setup" section
+   collapses to "run `brainrouter`; the wizard takes over."
+8. No regressions: `npm run test --workspace brainrouter-cli` stays
+   green; the legacy `brainrouter login` / `brainrouter config`
+   subcommands still work for users who scripted around them.
+
+## Open questions
+
+- **Should `/init` skip the wizard if the marker file exists**, or
+  always re-run? Current answer: always re-run when invoked
+  explicitly; only **auto-trigger on REPL start** when the marker is
+  missing. This matches Codex's "explicit `--login` always honoured"
+  contract.
+- **Should the MCP step probe both stdio and HTTP**, or just the
+  user's pick? Current answer: just the pick. Probing both adds 5s
+  to the wizard for unclear payoff. Users can re-run `/init` if they
+  want to try the other transport.
+- **Should the wizard offer to install missing system deps** (gh,
+  jq, ripgrep)? Current answer: no. Out of scope for v0.3.7. A
+  future `/doctor --fix` could handle it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-mcp-server",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "BrainRouter MCP server — the cognitive memory engine. Exposes recall, capture, focus scenes, persona, contradictions, skills, and graph queries as MCP tools for any MCP-speaking agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,14 +38,14 @@
     "setup:admin": "node scripts/setup-admin.js"
   },
   "dependencies": {
+    "@kinqs/brainrouter-types": "^0.3.8",
     "@modelcontextprotocol/sdk": "^1.11.0",
     "dotenv": "^16.4.5",
     "express": "^5.2.1",
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "sqlite-vec": "^0.1.9",
-    "zod": "^3.22.4",
-    "@kinqs/brainrouter-types": "^0.3.6"
+    "zod": "^3.22.4"
   },
   "engines": {
     "node": ">=22.0.0"