limbo-ai 1.21.0 → 1.22.1

package/README.md

@@ -52,20 +52,49 @@ Headless mode skips Telegram setup. To add Telegram later, run `npx limbo-ai sta
 ### Available commands
 
 ```sh
-npx limbo-ai start        # Install and start (default if no command given)
-npx limbo-ai stop         # Stop the container
-npx limbo-ai update       # Pull latest image and restart
-npx limbo-ai status       # Show container status
-npx limbo-ai logs         # Tail container logs
-npx limbo-ai start --reconfigure   # Change API keys or settings
+npx limbo-ai@latest start        # Install and start (default if no command given)
+npx limbo-ai@latest stop         # Stop the container
+npx limbo-ai@latest update       # Pull latest image and restart
+npx limbo-ai@latest status       # Show container status
+npx limbo-ai@latest logs         # Tail container logs
+npx limbo-ai@latest start --reconfigure   # Change API keys or settings
+npx limbo-ai@latest config               # Configure optional features (voice, web-search)
 ```
 
 ---
 
+## Optional Features
+
+Limbo supports optional features that can be enabled during the setup wizard (step 7) or anytime via the CLI.
+
+### Voice Messages
+
+Transcribe Telegram voice notes using [Groq](https://groq.com) Whisper. Requires a Groq API key (`gsk_...`).
+
+```sh
+npx limbo-ai@latest config voice --enable --api-key gsk_xxx
+npx limbo-ai@latest config voice --status
+npx limbo-ai@latest config voice --disable
+```
+
+### Web Search
+
+Give Limbo real-time web search via the [Brave Search API](https://brave.com/search/api/). Requires a Brave API key (`BSA...`).
+
+```sh
+npx limbo-ai@latest config web-search --enable --api-key BSAxxx
+npx limbo-ai@latest config web-search --status
+npx limbo-ai@latest config web-search --disable
+```
+
+Both features store API keys as Docker secrets and toggle config sections in the container on restart.
+
+---
+
 ## Updating
 
 ```sh
-npx limbo-ai update
+npx limbo-ai@latest update
 ```
 
 Pulls the latest Limbo image and restarts the container. Your vault data is persisted in the `limbo-data` Docker volume and is not affected.
@@ -124,6 +153,8 @@ Managed automatically by `npx limbo-ai start`, stored in `~/.limbo/.env`.
 | `MODEL_NAME` | no | `claude-opus-4-6` | Model name (e.g. `claude-opus-4-6`, `claude-sonnet-4-6`, `gpt-5.4`) |
 | `TELEGRAM_ENABLED` | no | `false` | Enable Telegram bot integration |
 | `TELEGRAM_BOT_TOKEN` | no | — | Telegram bot token (required if `TELEGRAM_ENABLED=true`) |
+| `VOICE_ENABLED` | no | `false` | Enable voice transcription (requires Groq API key as Docker secret) |
+| `WEB_SEARCH_ENABLED` | no | `false` | Enable web search (requires Brave API key as Docker secret) |
 
 > \* API keys are required only for `AUTH_MODE=api-key`. Subscription auth uses ZeroClaw auth profiles instead.
 

package/cli.js

@@ -6,6 +6,7 @@
 const { execSync, spawn, spawnSync } = require('child_process');
 const crypto = require('crypto');
 const fs = require('fs');
+const https = require('https');
 const os = require('os');
 const path = require('path');
 const readline = require('readline');
@@ -1066,7 +1067,7 @@ function teardownSetupTunnel(tunnel) {
 function installGlobalAlias() {
   // Create a `limbo` shell wrapper so users don't have to type `npx limbo-ai` every time.
   // Tries /usr/local/bin first (macOS, Linux with sudo), falls back to ~/.local/bin (no sudo).
-  const wrapper = '#!/bin/sh\nexec npx limbo-ai "$@"\n';
+  const wrapper = '#!/bin/sh\nexec npx limbo-ai@latest "$@"\n';
   const candidates = [
     path.join(os.homedir(), '.local', 'bin', 'limbo'),
     '/usr/local/bin/limbo',
@@ -1074,10 +1075,10 @@ function installGlobalAlias() {
 
   for (const target of candidates) {
     try {
-      // Skip if already installed and current
+      // Skip if already installed and current (must include @latest)
       if (fs.existsSync(target)) {
         const existing = fs.readFileSync(target, 'utf8');
-        if (existing.includes('limbo-ai')) return;
+        if (existing.includes('limbo-ai@latest')) return;
       }
       const dir = path.dirname(target);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -1669,9 +1670,32 @@ function cmdLogs() {
   run('docker compose logs -f');
 }
 
+function selfUpdateCli() {
+  const pkg = require('./package.json');
+  try {
+    const latest = execSync('npm view limbo-ai version', { encoding: 'utf8', timeout: 10000 }).trim();
+    if (!latest || latest === pkg.version) return;
+    const cur = pkg.version.split('.').map(Number);
+    const lat = latest.split('.').map(Number);
+    const isNewer = lat[0] > cur[0] || (lat[0] === cur[0] && lat[1] > cur[1]) ||
+      (lat[0] === cur[0] && lat[1] === cur[1] && lat[2] > cur[2]);
+    if (!isNewer) return;
+
+    log(`Updating CLI: ${pkg.version} → ${latest}...`);
+    execSync('npm install -g limbo-ai@latest', { stdio: 'inherit', timeout: 60000 });
+    ok(`CLI updated to ${latest}.`);
+  } catch {
+    warn('Could not self-update CLI. Run: npm install -g limbo-ai@latest');
+  }
+}
+
 function cmdUpdate() {
   if (!fs.existsSync(COMPOSE_FILE)) die(t('en', 'installMissing'));
 
+  // Self-update the CLI if installed globally
+  const isGlobal = !process.argv[1].includes('npx') && !process.argv[1].includes('node_modules/.cache');
+  if (isGlobal) selfUpdateCli();
+
   // Patch image tag to :latest in existing compose files (handles upgrades from pinned tags)
   let compose = fs.readFileSync(COMPOSE_FILE, 'utf8');
   const patched = compose.replace(
@@ -1828,27 +1852,118 @@ ${c.bold}Data directory:${c.reset} ${LIMBO_DIR}
 `);
 }
 
+// ─── Update Notifier ─────────────────────────────────────────────────────────
+
+const UPDATE_CHECK_FILE = path.join(LIMBO_DIR, '.update-check');
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+
+// Spawn a detached background process to check the npm registry.
+// Writes {latest, checkedAt} to UPDATE_CHECK_FILE and exits.
+function checkForUpdateInBackground() {
+  try {
+    let shouldCheck = true;
+    if (fs.existsSync(UPDATE_CHECK_FILE)) {
+      const cached = JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf8'));
+      if (Date.now() - cached.checkedAt < UPDATE_CHECK_INTERVAL) shouldCheck = false;
+    }
+    if (!shouldCheck) return;
+
+    // Spawn detached child that hits the registry and writes cache
+    const child = spawn(process.execPath, ['-e', `
+      const https = require('https');
+      const fs = require('fs');
+      const req = https.get('https://registry.npmjs.org/limbo-ai/latest', { timeout: 5000 }, (res) => {
+        let data = '';
+        res.on('data', (chunk) => data += chunk);
+        res.on('end', () => {
+          try {
+            const { version } = JSON.parse(data);
+            fs.mkdirSync('${LIMBO_DIR.replace(/\\/g, '\\\\')}', { recursive: true });
+            fs.writeFileSync('${UPDATE_CHECK_FILE.replace(/\\/g, '\\\\')}', JSON.stringify({ latest: version, checkedAt: Date.now() }));
+          } catch {}
+        });
+      });
+      req.on('error', () => {});
+      req.end();
+    `], { detached: true, stdio: 'ignore' });
+    child.unref();
+  } catch {}
+}
+
+// Read cache and print banner if a newer version is available.
+function notifyUpdate() {
+  try {
+    if (!fs.existsSync(UPDATE_CHECK_FILE)) return;
+    const { latest } = JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf8'));
+    const pkg = require('./package.json');
+    if (!latest || latest === pkg.version) return;
+
+    // Simple semver compare: split on dots, compare numerically
+    const cur = pkg.version.split('.').map(Number);
+    const lat = latest.split('.').map(Number);
+    const isNewer = lat[0] > cur[0] || (lat[0] === cur[0] && lat[1] > cur[1]) ||
+      (lat[0] === cur[0] && lat[1] === cur[1] && lat[2] > cur[2]);
+    if (!isNewer) return;
+
+    // Strip ANSI escapes for visible-length padding
+    const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - strip(s).length));
+
+    const line = `  Update available: ${c.dim}${pkg.version}${c.reset} → ${c.green}${latest}${c.reset}  `;
+    const instruction = `  Run ${c.cyan}npx limbo-ai@latest update${c.reset} to update  `;
+    const inner = Math.max(strip(line).length, strip(instruction).length);
+    const border = '─'.repeat(inner);
+    console.error(`\n  ${c.dim}╭${border}╮${c.reset}`);
+    console.error(`  ${c.dim}│${c.reset}${pad(line, inner)}${c.dim}│${c.reset}`);
+    console.error(`  ${c.dim}│${c.reset}${pad(instruction, inner)}${c.dim}│${c.reset}`);
+    console.error(`  ${c.dim}╰${border}╯${c.reset}\n`);
+  } catch {}
+}
+
+// ─── Exports (for testing) ────────────────────────────────────────────────────
+
+module.exports = {
+  MODEL_CATALOG,
+  normalizeConfig,
+  parseEnvFile,
+  deriveProviderFamily,
+  getModelCatalog,
+  parseCallbackInput,
+  decodeJwtPayload,
+  parseClaudeSetupToken,
+  buildCodexAuthProfile,
+  buildAnthropicAuthProfile,
+  generatePKCE,
+  buildOAuthUrl,
+};
+
 // ─── Main ────────────────────────────────────────────────────────────────────
 
-const [,, cmd = 'start'] = process.argv;
-
-(async () => {
-  switch (cmd) {
-    case 'start':
-    case 'install': await cmdStart(); break;
-    case 'stop':    cmdStop(); break;
-    case 'logs':    cmdLogs(); break;
-    case 'update':  cmdUpdate(); break;
-    case 'status':  cmdStatus(); break;
-    case 'config':  cmdConfig(); break;
-    case 'help':
-    case '--help':
-    case '-h':      cmdHelp(); break;
-    default:
-      warn(t('en', 'unknownCommand', cmd));
-      cmdHelp();
-      process.exit(1);
-  }
-})().catch((err) => {
-  die(err.message || String(err));
-});
+if (require.main === module) {
+  const [,, cmd = 'start'] = process.argv;
+
+  (async () => {
+    checkForUpdateInBackground();
+
+    switch (cmd) {
+      case 'start':
+      case 'install': await cmdStart(); break;
+      case 'stop':    cmdStop(); break;
+      case 'logs':    cmdLogs(); break;
+      case 'update':  cmdUpdate(); break;
+      case 'status':  cmdStatus(); break;
+      case 'config':  cmdConfig(); break;
+      case 'help':
+      case '--help':
+      case '-h':      cmdHelp(); break;
+      default:
+        warn(t('en', 'unknownCommand', cmd));
+        cmdHelp();
+        process.exit(1);
+    }
+
+    notifyUpdate();
+  })().catch((err) => {
+    die(err.message || String(err));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "limbo-ai",
-  "version": "1.21.0",
+  "version": "1.22.1",
   "description": "Your personal AI memory agent — install and manage Limbo via npx",
   "type": "commonjs",
   "bin": {
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "start": "node cli.js start",
-    "test": "node --test test/cli-filter.test.js test/zeroclaw-migration.test.js"
+    "test": "node --test test/cli-filter.test.js test/cli-auth.test.js test/zeroclaw-migration.test.js test/setup-server.test.js"
   },
   "keywords": [
     "limbo",

package/setup-server/server.js

@@ -154,7 +154,10 @@ function ensureSetupToken() {
   return token;
 }
 
-const SETUP_TOKEN = ensureSetupToken();
+let SETUP_TOKEN = null;
+if (require.main === module) {
+  SETUP_TOKEN = ensureSetupToken();
+}
 
 function checkToken(req) {
   const parsed = new URL(req.url, `http://${req.headers.host}`);
@@ -851,17 +854,46 @@ async function handleRequest(req, res) {
   }
 }
 
+// ─── Exports (for testing) ────────────────────────────────────────────────────
+
+module.exports = {
+  MODEL_CATALOG,
+  KEY_PREFIXES,
+  MIME_TYPES,
+  parseJSON,
+  generatePKCE,
+  buildOAuthUrl,
+  decodeJwtPayload,
+  buildCodexAuthProfile,
+  buildAnthropicAuthProfile,
+  handleRequest,
+  _internals: {
+    OPENAI_OAUTH,
+    readBody,
+    sendJSON,
+    sendError,
+    checkToken,
+    writeSecretFile,
+    readSecretFile,
+    ensureGatewayToken,
+    ensureSetupToken,
+    writeAuthProfiles,
+  },
+};
+
 // ─── Server ──────────────────────────────────────────────────────────────────
 
-const server = http.createServer(handleRequest);
+if (require.main === module) {
+  const server = http.createServer(handleRequest);
 
-server.listen(PORT, '0.0.0.0', () => {
-  log(`Limbo Setup Wizard listening on port ${PORT}`);
-  log(`SETUP_URL=http://0.0.0.0:${PORT}/?token=${SETUP_TOKEN}`);
-  log('Share the URL above with the user to complete setup.');
-});
+  server.listen(PORT, '0.0.0.0', () => {
+    log(`Limbo Setup Wizard listening on port ${PORT}`);
+    log(`SETUP_URL=http://0.0.0.0:${PORT}/?token=${SETUP_TOKEN}`);
+    log('Share the URL above with the user to complete setup.');
+  });
 
-server.on('error', (err) => {
-  log(`Server error: ${err.message}`);
-  process.exit(1);
-});
+  server.on('error', (err) => {
+    log(`Server error: ${err.message}`);
+    process.exit(1);
+  });
+}

package/test/cli-auth.test.js

@@ -1,250 +1,356 @@
 // test/cli-auth.test.js
-// Unit tests for the streamFilteredAuth pure-logic functions exported from cli.js.
+// Unit tests for CLI install-phase pure functions exported from cli.js.
 // Run with: node --test test/cli-auth.test.js
 'use strict';
 
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+
+const {
+  MODEL_CATALOG,
+  normalizeConfig,
+  deriveProviderFamily,
+  getModelCatalog,
+  parseCallbackInput,
+  decodeJwtPayload,
+  parseClaudeSetupToken,
+  buildCodexAuthProfile,
+  buildAnthropicAuthProfile,
+  generatePKCE,
+  buildOAuthUrl,
+} = require('../cli.js');
+
+// ─── deriveProviderFamily ─────────────────────────────────────────────────────
+
+test('deriveProviderFamily: null/undefined returns anthropic', () => {
+  assert.equal(deriveProviderFamily(null), 'anthropic');
+  assert.equal(deriveProviderFamily(undefined), 'anthropic');
+});
 
-const { stripAnsi, AUTH_URL_RE, TUI_CHROME_RE, flushStreamLines } = require('../cli.js');
-
-// ─── stripAnsi ────────────────────────────────────────────────────────────────
+test('deriveProviderFamily: openai-codex returns openai', () => {
+  assert.equal(deriveProviderFamily('openai-codex'), 'openai');
+});
 
-test('stripAnsi: strips standard CSI sequences', () => {
-  assert.equal(stripAnsi('\x1b[32mgreen\x1b[0m'), 'green');
-  assert.equal(stripAnsi('\x1b[1;31mbold red\x1b[0m'), 'bold red');
-  assert.equal(stripAnsi('\x1b[2Kclear line'), 'clear line');
+test('deriveProviderFamily: openai returns openai', () => {
+  assert.equal(deriveProviderFamily('openai'), 'openai');
 });
 
-test('stripAnsi: strips ?-prefixed private-mode CSI sequences', () => {
-  // \x1b[?25l hide cursor, \x1b[?25h show cursor
-  assert.equal(stripAnsi('\x1b[?25lhello\x1b[?25h'), 'hello');
-  // \x1b[?2004h / \x1b[?2004l bracketed paste mode
-  assert.equal(stripAnsi('\x1b[?2004htext\x1b[?2004l'), 'text');
+test('deriveProviderFamily: openrouter returns openrouter', () => {
+  assert.equal(deriveProviderFamily('openrouter'), 'openrouter');
 });
 
-test('stripAnsi: strips two-char ESC sequences (0x40-0x5F range)', () => {
-  // ESC M (0x4D) — reverse index (cursor up with scroll)
-  assert.equal(stripAnsi('\x1bMline'), 'line');
-  // ESC E (0x45) — next line
-  assert.equal(stripAnsi('text\x1bEafter'), 'textafter');
-  // ESC ^ (0x5E) — privacy message (PM)
-  assert.equal(stripAnsi('before\x1b^after'), 'beforeafter');
+test('deriveProviderFamily: unknown provider returns anthropic', () => {
+  assert.equal(deriveProviderFamily('mistral'), 'anthropic');
+  assert.equal(deriveProviderFamily('google'), 'anthropic');
 });
 
-test('stripAnsi: strips OSC sequences (BEL-terminated)', () => {
-  // OSC 0 ; title BEL — window title sequence
-  assert.equal(stripAnsi('\x1b]0;My Terminal Title\x07visible'), 'visible');
+// ─── getModelCatalog ──────────────────────────────────────────────────────────
+
+test('getModelCatalog: returns correct catalog for openai:subscription', () => {
+  const catalog = getModelCatalog('openai', 'subscription');
+  assert.ok(catalog);
+  assert.equal(catalog.provider, 'openai-codex');
 });
 
-test('stripAnsi: strips OSC sequences (ST-terminated)', () => {
-  assert.equal(stripAnsi('\x1b]0;title\x1b\\visible'), 'visible');
+test('getModelCatalog: returns correct catalog for openai:api-key', () => {
+  const catalog = getModelCatalog('openai', 'api-key');
+  assert.ok(catalog);
+  assert.equal(catalog.provider, 'openai');
 });
 
-test('stripAnsi: strips bare carriage returns', () => {
-  assert.equal(stripAnsi('line1\rline2'), 'line1line2');
-  assert.equal(stripAnsi('\r'), '');
+test('getModelCatalog: returns correct catalog for anthropic:subscription', () => {
+  const catalog = getModelCatalog('anthropic', 'subscription');
+  assert.ok(catalog);
+  assert.equal(catalog.provider, 'anthropic');
 });
 
-test('stripAnsi: leaves plain text untouched', () => {
-  const plain = 'Hello, world! 123 !@#';
-  assert.equal(stripAnsi(plain), plain);
+test('getModelCatalog: returns correct catalog for anthropic:api-key', () => {
+  const catalog = getModelCatalog('anthropic', 'api-key');
+  assert.ok(catalog);
+  assert.equal(catalog.provider, 'anthropic');
 });
 
-test('stripAnsi: handles empty string', () => {
-  assert.equal(stripAnsi(''), '');
+test('getModelCatalog: returns correct catalog for openrouter:api-key', () => {
+  const catalog = getModelCatalog('openrouter', 'api-key');
+  assert.ok(catalog);
+  assert.equal(catalog.provider, 'openrouter');
 });
 
-test('stripAnsi: strips mixed sequences in one pass', () => {
-  // CSI (?25l hide cursor) + CSI (32m color) + OSC (window title) + bare CR
-  const input = '\x1b[?25l\x1b[32mProcessing\x1b[0m...\x1b]0;term\x07done\r';
-  assert.equal(stripAnsi(input), 'Processing...done');
-  // CSI + two-char ESC (M) mixed with real text
-  const input2 = '\x1b[1mbold\x1b[0m\x1bMnext';
-  assert.equal(stripAnsi(input2), 'boldnext');
+test('getModelCatalog: returns undefined for invalid combo', () => {
+  assert.equal(getModelCatalog('openrouter', 'subscription'), undefined);
+  assert.equal(getModelCatalog('invalid', 'api-key'), undefined);
 });
 
-// ─── TUI_CHROME_RE ────────────────────────────────────────────────────────────
+// ─── MODEL_CATALOG ────────────────────────────────────────────────────────────
 
-test('TUI_CHROME_RE: suppresses Braille spinner chars', () => {
-  // Common clack/openclaw spinner frames
-  for (const ch of ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']) {
-    assert.equal(TUI_CHROME_RE.test(ch), true, `expected ${ch} to match TUI_CHROME_RE`);
+test('MODEL_CATALOG: all entries have required fields', () => {
+  for (const [key, entry] of Object.entries(MODEL_CATALOG)) {
+    assert.ok(entry.provider, `${key} missing provider`);
+    assert.ok(entry.defaultModel, `${key} missing defaultModel`);
+    assert.ok(Array.isArray(entry.menuModels), `${key} menuModels not array`);
+    assert.ok(Array.isArray(entry.supportedModels), `${key} supportedModels not array`);
   }
 });
 
-test('TUI_CHROME_RE: suppresses box-drawing chars', () => {
-  assert.equal(TUI_CHROME_RE.test('─'), true);
-  assert.equal(TUI_CHROME_RE.test('│'), true);
-  assert.equal(TUI_CHROME_RE.test('┌┐└┘'), true);
-  assert.equal(TUI_CHROME_RE.test('═══'), true);
+// ─── normalizeConfig ──────────────────────────────────────────────────────────
+
+test('normalizeConfig: defaults for empty config', () => {
+  const result = normalizeConfig({});
+  assert.equal(result.CLI_LANGUAGE, 'en');
+  assert.equal(result.AUTH_MODE, 'api-key');
+  assert.equal(result.MODEL_PROVIDER, 'anthropic');
+  assert.equal(result.MODEL_NAME, 'claude-opus-4-6');
+  assert.equal(result.TELEGRAM_ENABLED, 'false');
+  assert.ok(result.GATEWAY_TOKEN, 'should generate a gateway token');
+});
+
+test('normalizeConfig: cfg values override defaults', () => {
+  const result = normalizeConfig({
+    language: 'es',
+    authMode: 'subscription',
+    provider: 'openai',
+    modelName: 'gpt-5.4',
+  });
+  assert.equal(result.CLI_LANGUAGE, 'es');
+  assert.equal(result.AUTH_MODE, 'subscription');
+  assert.equal(result.MODEL_PROVIDER, 'openai');
+  assert.equal(result.MODEL_NAME, 'gpt-5.4');
 });
 
-test('TUI_CHROME_RE: suppresses clack decoration chars', () => {
-  assert.equal(TUI_CHROME_RE.test('◇'), true);
-  assert.equal(TUI_CHROME_RE.test('●'), true);
-  assert.equal(TUI_CHROME_RE.test('◆'), true);
-  assert.equal(TUI_CHROME_RE.test('○'), true);
+test('normalizeConfig: provider-specific key routing for openai', () => {
+  const result = normalizeConfig({ provider: 'openai', apiKey: 'sk-test-key' });
+  assert.equal(result.OPENAI_API_KEY, 'sk-test-key');
+  assert.equal(result.ANTHROPIC_API_KEY, '');
+  assert.equal(result.LLM_API_KEY, 'sk-test-key');
 });
 
-test('TUI_CHROME_RE: suppresses whitespace-only lines', () => {
-  assert.equal(TUI_CHROME_RE.test('   '), true);
-  assert.equal(TUI_CHROME_RE.test(''), true);
-  assert.equal(TUI_CHROME_RE.test('\t'), true);
+test('normalizeConfig: provider-specific key routing for anthropic', () => {
+  const result = normalizeConfig({ provider: 'anthropic', apiKey: 'sk-ant-test' });
+  assert.equal(result.ANTHROPIC_API_KEY, 'sk-ant-test');
+  assert.equal(result.OPENAI_API_KEY, '');
+  assert.equal(result.LLM_API_KEY, 'sk-ant-test');
 });
 
-test('TUI_CHROME_RE: suppresses mixed chrome lines (spinner + whitespace)', () => {
-  assert.equal(TUI_CHROME_RE.test('  ⠋  '), true);
-  assert.equal(TUI_CHROME_RE.test('◇  ─  ◇'), true);
+test('normalizeConfig: existingEnv used as fallback', () => {
+  const existing = {
+    CLI_LANGUAGE: 'es',
+    MODEL_PROVIDER: 'openai',
+    GATEWAY_TOKEN: 'existing-token',
+  };
+  const result = normalizeConfig({}, existing);
+  assert.equal(result.CLI_LANGUAGE, 'es');
+  assert.equal(result.MODEL_PROVIDER, 'openai');
+  assert.equal(result.GATEWAY_TOKEN, 'existing-token');
 });
 
-test('TUI_CHROME_RE: passes lines with real text content', () => {
-  assert.equal(TUI_CHROME_RE.test('Please open this URL'), false);
-  assert.equal(TUI_CHROME_RE.test('Authenticating...'), false);
-  assert.equal(TUI_CHROME_RE.test('Press Enter to continue'), false);
-  assert.equal(TUI_CHROME_RE.test('Error: invalid token'), false);
+test('normalizeConfig: keepExisting preserves old keys', () => {
+  const existing = {
+    OPENAI_API_KEY: 'old-openai-key',
+    ANTHROPIC_API_KEY: 'old-anthropic-key',
+    LLM_API_KEY: 'old-llm-key',
+    TELEGRAM_BOT_TOKEN: 'old-telegram',
+  };
+  const result = normalizeConfig({ keepExisting: true }, existing);
+  assert.equal(result.OPENAI_API_KEY, 'old-openai-key');
+  assert.equal(result.ANTHROPIC_API_KEY, 'old-anthropic-key');
+  assert.equal(result.LLM_API_KEY, 'old-llm-key');
+  assert.equal(result.TELEGRAM_BOT_TOKEN, 'old-telegram');
 });
 
-test('TUI_CHROME_RE: passes lines starting with decoration but containing text', () => {
-  // clack prompts often have a leading decoration glyph followed by text
-  assert.equal(TUI_CHROME_RE.test('◇ Enter your API key'), false);
-  assert.equal(TUI_CHROME_RE.test('● Model selected: claude-opus-4-6'), false);
+test('normalizeConfig: without keepExisting clears unrelated keys', () => {
+  const existing = {
+    OPENAI_API_KEY: 'old-openai-key',
+    ANTHROPIC_API_KEY: 'old-anthropic-key',
+    LLM_API_KEY: 'old-llm-key',
+    TELEGRAM_BOT_TOKEN: 'old-telegram',
+  };
+  const result = normalizeConfig({}, existing);
+  assert.equal(result.OPENAI_API_KEY, '');
+  assert.equal(result.ANTHROPIC_API_KEY, '');
+  assert.equal(result.LLM_API_KEY, '');
+  assert.equal(result.TELEGRAM_BOT_TOKEN, '');
 });
 
-// ─── AUTH_URL_RE (URL extraction) ─────────────────────────────────────────────
+// ─── parseCallbackInput ──────────────────────────────────────────────────────
 
-test('AUTH_URL_RE: detects http OAuth URLs', () => {
-  const line = 'Open this URL to authenticate: http://localhost:3000/oauth/callback?code=abc123';
-  const matches = line.match(AUTH_URL_RE);
-  assert.ok(matches, 'expected URL match');
-  assert.equal(matches[0], 'http://localhost:3000/oauth/callback?code=abc123');
+test('parseCallbackInput: full URL with code and state', () => {
+  const result = parseCallbackInput('http://localhost:1455/auth/callback?code=abc123&state=xyz');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, 'xyz');
 });
 
-test('AUTH_URL_RE: detects https OAuth URLs', () => {
-  const line = 'Visit https://auth.anthropic.com/oauth2/authorize?client_id=limbo&state=xyz to login';
-  const matches = line.match(AUTH_URL_RE);
-  assert.ok(matches, 'expected URL match');
-  assert.equal(matches[0], 'https://auth.anthropic.com/oauth2/authorize?client_id=limbo&state=xyz');
+test('parseCallbackInput: URL without state', () => {
+  const result = parseCallbackInput('http://localhost:1455/auth/callback?code=abc123');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, null);
 });
 
-test('AUTH_URL_RE: does not match plain text without URL', () => {
-  const line = 'Waiting for authentication...';
-  const matches = line.match(AUTH_URL_RE);
-  assert.equal(matches, null);
+test('parseCallbackInput: query string format', () => {
+  const result = parseCallbackInput('code=abc123&state=xyz');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, 'xyz');
 });
 
-test('AUTH_URL_RE: stops URL at whitespace', () => {
-  const line = 'URL: https://example.com/auth and then some text';
-  const matches = line.match(AUTH_URL_RE);
-  assert.ok(matches);
-  assert.equal(matches[0], 'https://example.com/auth');
+test('parseCallbackInput: query string with leading ?', () => {
+  const result = parseCallbackInput('?code=abc123&state=xyz');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, 'xyz');
 });
 
-test('AUTH_URL_RE: stops URL at angle bracket', () => {
-  const line = 'Go to <https://example.com/auth>';
-  const matches = line.match(AUTH_URL_RE);
-  assert.ok(matches);
-  assert.equal(matches[0], 'https://example.com/auth');
+test('parseCallbackInput: bare code string', () => {
+  const result = parseCallbackInput('abc123');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, null);
 });
 
-test('AUTH_URL_RE: extracts multiple URLs from a single line', () => {
-  const line = 'Primary: https://example.com/a Fallback: https://example.com/b';
-  const matches = line.match(AUTH_URL_RE);
-  assert.ok(matches);
-  assert.equal(matches.length, 2);
-  assert.equal(matches[0], 'https://example.com/a');
-  assert.equal(matches[1], 'https://example.com/b');
+test('parseCallbackInput: whitespace trimming', () => {
+  const result = parseCallbackInput('  abc123  ');
+  assert.equal(result.code, 'abc123');
+  assert.equal(result.state, null);
 });
 
-test('AUTH_URL_RE: URL deduplication — same URL seen twice is emitted once', () => {
-  // This tests the seenUrls Set logic conceptually — we verify that running AUTH_URL_RE
-  // against the same URL twice and filtering via a Set yields a single emission.
-  const url = 'https://auth.openai.com/oauth/callback?code=abc';
-  const lines = [
-    `Open: ${url}`,
-    `Retry: ${url}`,
-    'Different: https://example.com/other',
-  ];
+// ─── decodeJwtPayload ─────────────────────────────────────────────────────────
 
-  const emitted = [];
-  const seenUrls = new Set();
+test('decodeJwtPayload: valid 3-part JWT decodes payload', () => {
+  const payload = { sub: 'user123', email: 'test@example.com' };
+  const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const token = `header.${encoded}.signature`;
+  const result = decodeJwtPayload(token);
+  assert.deepEqual(result, payload);
+});
 
-  for (const line of lines) {
-    const urls = line.match(AUTH_URL_RE) || [];
-    for (const u of urls) {
-      if (!seenUrls.has(u)) {
-        seenUrls.add(u);
-        emitted.push(u);
-      }
-    }
-  }
+test('decodeJwtPayload: 1-part token returns empty object', () => {
+  const result = decodeJwtPayload('single-part-token');
+  assert.deepEqual(result, {});
+});
 
-  assert.equal(emitted.length, 2, 'duplicate URL should only be emitted once');
-  assert.equal(emitted[0], url);
-  assert.equal(emitted[1], 'https://example.com/other');
+test('decodeJwtPayload: JWT with nested OpenAI auth claim', () => {
+  const payload = {
+    sub: 'user123',
+    'https://api.openai.com/auth': {
+      user_id: 'user-abc',
+    },
+  };
+  const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const token = `header.${encoded}.signature`;
+  const result = decodeJwtPayload(token);
+  assert.deepEqual(result['https://api.openai.com/auth'], { user_id: 'user-abc' });
 });
 
-// ─── flushStreamLines (animation scatter regression) ──────────────────────────
+// ─── parseClaudeSetupToken ────────────────────────────────────────────────────
+
+test('parseClaudeSetupToken: valid sk-ant-xxx accepted', () => {
+  const token = 'sk-ant-abc123_DEF-456';
+  assert.equal(parseClaudeSetupToken(token), token);
+});
 
-test('flushStreamLines: emits only final \\r frame — suppresses scatter', () => {
-  // This is the exact pattern that caused the diagonal scatter seen in the screenshot:
-  // clack's character-by-character reveal writes each progressive state separated by \r.
-  // Before the fix, every frame was emitted as a separate line causing staircase output.
-  const buf = '│ Y\r│ Yo\r│ You\r│ Your URL: https://auth.example.com\n';
-  const { lines, remaining } = flushStreamLines(buf);
-  assert.equal(remaining, '');
-  assert.equal(lines.length, 1, 'only the final frame should be emitted');
-  assert.equal(lines[0], '│ Your URL: https://auth.example.com');
+test('parseClaudeSetupToken: whitespace trimmed', () => {
+  const token = '  sk-ant-abc123  ';
+  assert.equal(parseClaudeSetupToken(token), 'sk-ant-abc123');
 });
 
-test('flushStreamLines: handles spinner animation (pure chrome final frame)', () => {
-  // Spinner that completes and clears the line — final state is empty/chrome
-  const buf = '⠋\r⠙\r⠹\r⠸\r \n';
-  const { lines } = flushStreamLines(buf);
-  assert.equal(lines.length, 1);
-  assert.equal(lines[0], ' '); // final frame (space = cleared); TUI_CHROME_RE will suppress it
+test('parseClaudeSetupToken: invalid format sk-abc returns null', () => {
+  assert.equal(parseClaudeSetupToken('sk-abc'), null);
 });
 
-test('flushStreamLines: normalises \\r\\n to single newline', () => {
-  const buf = 'line one\r\nline two\r\n';
-  const { lines, remaining } = flushStreamLines(buf);
-  assert.equal(remaining, '');
-  assert.deepEqual(lines, ['line one', 'line two']);
+test('parseClaudeSetupToken: empty string returns null', () => {
+  assert.equal(parseClaudeSetupToken(''), null);
 });
 
-test('flushStreamLines: holds incomplete segment in remaining', () => {
-  const buf = 'complete line\nstill coming';
-  const { lines, remaining } = flushStreamLines(buf);
-  assert.deepEqual(lines, ['complete line']);
-  assert.equal(remaining, 'still coming');
+test('parseClaudeSetupToken: special chars return null', () => {
+  assert.equal(parseClaudeSetupToken('sk-ant-abc!@#'), null);
 });
 
-test('flushStreamLines: accumulating chunks yields same result as one chunk', () => {
-  // Simulate data arriving in two chunks mid-animation-frame
-  const chunk1 = '│ Y\r│ Yo\r';
-  const chunk2 = '│ You\r│ Your URL: https://auth.example.com\n';
+// ─── buildCodexAuthProfile ────────────────────────────────────────────────────
+
+test('buildCodexAuthProfile: correct structure with email', () => {
+  const profile = {
+    email: 'user@example.com',
+    access: 'access-token',
+    refresh: 'refresh-token',
+    expires: 1234567890,
+    accountId: 'acct-123',
+  };
+  const result = buildCodexAuthProfile(profile);
+  assert.equal(result.version, 1);
+  const profileId = 'openai-codex:user@example.com';
+  assert.ok(result.profiles[profileId]);
+  assert.equal(result.profiles[profileId].type, 'oauth');
+  assert.equal(result.profiles[profileId].provider, 'openai-codex');
+  assert.equal(result.profiles[profileId].access, 'access-token');
+  assert.equal(result.profiles[profileId].refresh, 'refresh-token');
+  assert.equal(result.profiles[profileId].expires, 1234567890);
+  assert.equal(result.profiles[profileId].accountId, 'acct-123');
+});
+
+test('buildCodexAuthProfile: default profileId without email', () => {
+  const profile = { access: 'tok', refresh: 'ref', expires: 0 };
+  const result = buildCodexAuthProfile(profile);
+  assert.ok(result.profiles['openai-codex:default']);
+});
 
-  // Chunk 1 alone: no complete \n-terminated line yet
-  const r1 = flushStreamLines(chunk1);
-  assert.deepEqual(r1.lines, []);
-  assert.equal(r1.remaining, '│ Y\r│ Yo\r');
+// ─── buildAnthropicAuthProfile ────────────────────────────────────────────────
+
+test('buildAnthropicAuthProfile: correct structure', () => {
+  const result = buildAnthropicAuthProfile('sk-ant-test-token');
+  assert.equal(result.version, 1);
+  assert.ok(result.profiles['anthropic:token']);
+  assert.equal(result.profiles['anthropic:token'].type, 'token');
+  assert.equal(result.profiles['anthropic:token'].provider, 'anthropic');
+  assert.equal(result.profiles['anthropic:token'].token, 'sk-ant-test-token');
+});
+
+test('buildAnthropicAuthProfile: order has anthropic key', () => {
+  const result = buildAnthropicAuthProfile('sk-ant-test');
+  assert.deepEqual(result.order, { anthropic: ['anthropic:token'] });
+});
+
+// ─── generatePKCE ─────────────────────────────────────────────────────────────
+
+test('generatePKCE: returns verifier and challenge strings', () => {
+  const pkce = generatePKCE();
+  assert.equal(typeof pkce.verifier, 'string');
+  assert.equal(typeof pkce.challenge, 'string');
+  assert.ok(pkce.verifier.length > 0);
+  assert.ok(pkce.challenge.length > 0);
+});
+
+test('generatePKCE: challenge is sha256 of verifier', () => {
+  const pkce = generatePKCE();
+  const expected = crypto.createHash('sha256').update(pkce.verifier).digest('base64url');
+  assert.equal(pkce.challenge, expected);
+});
+
+test('generatePKCE: unique each call', () => {
+  const a = generatePKCE();
+  const b = generatePKCE();
+  assert.notEqual(a.verifier, b.verifier);
+  assert.notEqual(a.challenge, b.challenge);
+});
+
+// ─── buildOAuthUrl ────────────────────────────────────────────────────────────
+
+test('buildOAuthUrl: URL includes response_type=code', () => {
+  const pkce = generatePKCE();
+  const url = buildOAuthUrl(pkce, 'test-state');
+  assert.ok(url.includes('response_type=code'));
+});
 
-  // Chunk 2 appended to remaining: yields only the final frame
-  const r2 = flushStreamLines(r1.remaining + chunk2);
-  assert.equal(r2.lines.length, 1);
-  assert.equal(r2.lines[0], '│ Your URL: https://auth.example.com');
-  assert.equal(r2.remaining, '');
+test('buildOAuthUrl: URL includes code_challenge', () => {
+  const pkce = generatePKCE();
+  const url = buildOAuthUrl(pkce, 'test-state');
+  assert.ok(url.includes(`code_challenge=${encodeURIComponent(pkce.challenge)}`));
 });
 
-test('flushStreamLines: multiple \\n-terminated lines processed independently', () => {
-  // Two different lines, each with animation frames
-  const buf = '⠋ Loading...\r⠙ Loading...\r Done!\nEnter code: \r\n';
-  const { lines } = flushStreamLines(buf);
-  assert.deepEqual(lines, [' Done!', 'Enter code: ']);
+test('buildOAuthUrl: URL includes state', () => {
+  const pkce = generatePKCE();
+  const url = buildOAuthUrl(pkce, 'my-state-value');
+  assert.ok(url.includes('state=my-state-value'));
 });
 
-test('flushStreamLines: empty buffer returns no lines', () => {
-  const { lines, remaining } = flushStreamLines('');
-  assert.deepEqual(lines, []);
-  assert.equal(remaining, '');
+test('buildOAuthUrl: URL includes client_id', () => {
+  const pkce = generatePKCE();
+  const url = buildOAuthUrl(pkce, 'state');
+  assert.ok(url.includes('client_id='));
 });

package/test/setup-server.test.js

@@ -0,0 +1,287 @@
+// test/setup-server.test.js — Unit tests for setup-server/server.js
+'use strict';
+
+const { describe, it, after, before } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const crypto = require('crypto');
+
+const {
+  MODEL_CATALOG,
+  KEY_PREFIXES,
+  MIME_TYPES,
+  parseJSON,
+  generatePKCE,
+  buildOAuthUrl,
+  decodeJwtPayload,
+  buildCodexAuthProfile,
+  buildAnthropicAuthProfile,
+  handleRequest,
+  _internals: { OPENAI_OAUTH },
+} = require('../setup-server/server.js');
+
+// ─── Helper: make HTTP request against test server ──────────────────────────
+
+function request(server, method, path, body) {
+  return new Promise((resolve, reject) => {
+    const addr = server.address();
+    const opts = {
+      hostname: '127.0.0.1',
+      port: addr.port,
+      path,
+      method,
+      headers: {},
+    };
+
+    if (body !== undefined) {
+      const payload = typeof body === 'string' ? body : JSON.stringify(body);
+      opts.headers['Content-Type'] = 'application/json';
+      opts.headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+
+    const req = http.request(opts, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let json = null;
+        try { json = JSON.parse(raw); } catch {}
+        resolve({ statusCode: res.statusCode, headers: res.headers, raw, json });
+      });
+    });
+
+    req.on('error', reject);
+
+    if (body !== undefined) {
+      const payload = typeof body === 'string' ? body : JSON.stringify(body);
+      req.write(payload);
+    }
+    req.end();
+  });
+}
+
+// ─── A. Pure function tests ─────────────────────────────────────────────────
+
+describe('parseJSON', () => {
+  it('parses valid JSON', () => {
+    assert.deepStrictEqual(parseJSON('{"a":1}'), { a: 1 });
+  });
+
+  it('returns null for invalid JSON', () => {
+    assert.strictEqual(parseJSON('not json'), null);
+  });
+
+  it('returns null for empty string', () => {
+    assert.strictEqual(parseJSON(''), null);
+  });
+});
+
+describe('KEY_PREFIXES', () => {
+  it('has correct prefix for openai', () => {
+    assert.strictEqual(KEY_PREFIXES.openai, 'sk-');
+  });
+
+  it('has correct prefix for anthropic', () => {
+    assert.strictEqual(KEY_PREFIXES.anthropic, 'sk-ant-');
+  });
+
+  it('has correct prefix for openrouter', () => {
+    assert.strictEqual(KEY_PREFIXES.openrouter, 'sk-or-');
+  });
+});
+
+describe('MODEL_CATALOG', () => {
+  for (const provider of ['anthropic', 'openai', 'openrouter']) {
+    it(`${provider} has defaultModel and models array`, () => {
+      const entry = MODEL_CATALOG[provider];
+      assert.ok(entry, `missing provider ${provider}`);
+      assert.ok(typeof entry.defaultModel === 'string', 'defaultModel is string');
+      assert.ok(Array.isArray(entry.models), 'models is array');
+      assert.ok(entry.models.length > 0, 'models is non-empty');
+    });
+
+    it(`${provider} models have id and name`, () => {
+      for (const m of MODEL_CATALOG[provider].models) {
+        assert.ok(typeof m.id === 'string' && m.id.length > 0, `model missing id`);
+        assert.ok(typeof m.name === 'string' && m.name.length > 0, `model missing name`);
+      }
+    });
+  }
+});
+
+describe('generatePKCE', () => {
+  it('returns verifier and challenge strings', () => {
+    const pkce = generatePKCE();
+    assert.ok(typeof pkce.verifier === 'string' && pkce.verifier.length > 0);
+    assert.ok(typeof pkce.challenge === 'string' && pkce.challenge.length > 0);
+  });
+
+  it('challenge is sha256 of verifier (base64url)', () => {
+    const pkce = generatePKCE();
+    const expected = crypto.createHash('sha256').update(pkce.verifier).digest('base64url');
+    assert.strictEqual(pkce.challenge, expected);
+  });
+});
+
+describe('buildOAuthUrl', () => {
+  it('includes required OAuth params', () => {
+    const pkce = generatePKCE();
+    const state = 'test-state-123';
+    const redirectUri = 'http://localhost:1455/auth/callback';
+    const url = buildOAuthUrl(pkce, state, redirectUri);
+
+    assert.ok(url.includes('response_type=code'), 'missing response_type');
+    assert.ok(url.includes(`client_id=${OPENAI_OAUTH.clientId}`), 'missing client_id');
+    assert.ok(url.includes(`code_challenge=${pkce.challenge}`), 'missing code_challenge');
+    assert.ok(url.includes(`state=${state}`), 'missing state');
+    assert.ok(url.includes('code_challenge_method=S256'), 'missing code_challenge_method');
+    assert.ok(url.startsWith(OPENAI_OAUTH.authorizeUrl), 'wrong base URL');
+  });
+});
+
+describe('decodeJwtPayload', () => {
+  it('decodes a valid 3-part JWT', () => {
+    const payload = { sub: 'user-123', email: 'test@example.com' };
+    const b64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const token = `header.${b64}.signature`;
+    const decoded = decodeJwtPayload(token);
+    assert.deepStrictEqual(decoded, payload);
+  });
+
+  it('returns empty object for 1-part token', () => {
+    assert.deepStrictEqual(decodeJwtPayload('single-part'), {});
+  });
+
+  it('extracts nested claims', () => {
+    const payload = {
+      sub: 'user-1',
+      'https://api.openai.com/auth': {
+        chatgpt_account_id: 'acct-abc',
+      },
+    };
+    const b64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const token = `h.${b64}.s`;
+    const decoded = decodeJwtPayload(token);
+    assert.strictEqual(decoded['https://api.openai.com/auth'].chatgpt_account_id, 'acct-abc');
+  });
+});
+
+describe('buildCodexAuthProfile', () => {
+  it('builds correct structure with email', () => {
+    const profile = {
+      access: 'access-tok',
+      refresh: 'refresh-tok',
+      expires: Date.now() + 3600000,
+      accountId: 'acct-1',
+      email: 'test@example.com',
+    };
+    const result = buildCodexAuthProfile(profile);
+    assert.strictEqual(result.version, 1);
+    const pid = 'openai-codex:default';
+    assert.ok(result.profiles[pid], 'profile entry exists');
+    assert.strictEqual(result.profiles[pid].provider, 'openai-codex');
+    assert.strictEqual(result.profiles[pid].kind, 'oauth');
+    assert.strictEqual(result.profiles[pid].access_token, 'access-tok');
+    assert.strictEqual(result.profiles[pid].refresh_token, 'refresh-tok');
+    assert.deepStrictEqual(result.order, { 'openai-codex': [pid] });
+  });
+
+  it('builds correct structure without email (accountId empty)', () => {
+    const profile = {
+      access: 'a',
+      refresh: 'r',
+      expires: Date.now() + 1000,
+    };
+    const result = buildCodexAuthProfile(profile);
+    const pid = 'openai-codex:default';
+    assert.strictEqual(result.profiles[pid].account_id, '');
+  });
+});
+
+describe('buildAnthropicAuthProfile', () => {
+  it('builds correct structure', () => {
+    const result = buildAnthropicAuthProfile('sk-ant-test123');
+    assert.strictEqual(result.version, 1);
+    const pid = 'anthropic:default';
+    assert.ok(result.profiles[pid], 'profile entry exists');
+    assert.strictEqual(result.profiles[pid].provider, 'anthropic');
+    assert.strictEqual(result.profiles[pid].kind, 'token');
+    assert.strictEqual(result.profiles[pid].access_token, 'sk-ant-test123');
+  });
+
+  it('order includes anthropic key', () => {
+    const result = buildAnthropicAuthProfile('sk-ant-xyz');
+    assert.ok(result.order.anthropic, 'order has anthropic key');
+    assert.deepStrictEqual(result.order.anthropic, ['anthropic:default']);
+  });
+});
+
+// ─── B. HTTP handler tests ──────────────────────────────────────────────────
+
+describe('HTTP handler', () => {
+  let server;
+
+  before(() => {
+    return new Promise((resolve) => {
+      server = http.createServer(handleRequest);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+  });
+
+  after(() => {
+    return new Promise((resolve) => {
+      server.close(resolve);
+    });
+  });
+
+  // Note: SETUP_TOKEN is null when imported (not running as main module).
+  // checkToken compares searchParams.get('token') === null, so requests
+  // WITHOUT a token param pass auth (null === null). Requests with a WRONG
+  // token correctly fail (e.g. 'wrong' !== null).
+
+  it('GET /api/models without token passes (SETUP_TOKEN is null)', async () => {
+    // null === null → auth passes, returns the catalog
+    const res = await request(server, 'GET', '/api/models');
+    assert.strictEqual(res.statusCode, 200);
+    assert.ok(res.json && res.json.anthropic, 'should return model catalog');
+  });
+
+  it('GET /api/models with wrong token returns 403', async () => {
+    const res = await request(server, 'GET', '/api/models?token=wrong');
+    assert.strictEqual(res.statusCode, 403);
+  });
+
+  it('GET /api/models with provider filter returns single provider', async () => {
+    const res = await request(server, 'GET', '/api/models?provider=openai');
+    assert.strictEqual(res.statusCode, 200);
+    assert.ok(res.json && res.json.defaultModel, 'should return provider entry');
+    assert.ok(Array.isArray(res.json.models), 'should have models array');
+  });
+
+  it('path traversal is neutralised by Node URL parsing', async () => {
+    // Node's HTTP parser normalises /../../../etc/passwd → /etc/passwd
+    // serveStatic resolves it inside PUBLIC_DIR and returns 404 (not found)
+    const res = await request(server, 'GET', '/../../../etc/passwd');
+    assert.ok([403, 404].includes(res.statusCode), `expected 403 or 404, got ${res.statusCode}`);
+  });
+
+  it('GET /auth/callback without code handles missing PKCE session', async () => {
+    const res = await request(server, 'GET', '/auth/callback?code=test&state=none');
+    // Should return 400 with error page (invalid session) — not crash
+    assert.ok(res.statusCode === 400, `expected 400, got ${res.statusCode}`);
+    assert.ok(res.raw.includes('Invalid or expired session'), 'should mention invalid session');
+  });
+
+  it('POST /api/validate-key without body returns 400', async () => {
+    // Auth passes (null token), but missing body fields → 400
+    const res = await request(server, 'POST', '/api/validate-key', {});
+    assert.strictEqual(res.statusCode, 400);
+  });
+
+  it('unsupported method returns 405', async () => {
+    // Auth passes (null token), but DELETE is not handled → 405
+    const res = await request(server, 'DELETE', '/api/models');
+    assert.strictEqual(res.statusCode, 405);
+    assert.ok(res.json && res.json.error.includes('Method not allowed'));
+  });
+});