@polderlabs/bizar 6.2.1 → 6.2.3

package/cli/commands/setup-provider.test.mjs

@@ -0,0 +1,311 @@
+/**
+ * cli/commands/setup-provider.test.mjs
+ *
+ * v6.2.3 — Unit tests for the setup-provider subcommand.
+ *
+ * v6.2.3 changed the storage backend from `~/.cline/cline.json` to
+ * `~/.cline/data/settings/providers.json` (the file the Cline CLI
+ * and kanban mode actually read). The default providerId changed
+ * from `9router` to `litellm` (a real entry in Cline's catalog).
+ *
+ * Exercises the pure helpers (`buildProviderBlock`, `parseFlags`,
+ * `OPENAI_COMPATIBLE_PROVIDERS`) and the filesystem mutations
+ * (`applyProviderBlock`, `removeProvider`) with a mocked CLINE_DIR.
+ */
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const {
+  buildProviderBlock,
+  applyProviderBlock,
+  removeProvider,
+  listGatewayModels,
+  parseFlags,
+  OPENAI_COMPATIBLE_PROVIDERS,
+} = await import('./setup-provider.mjs');
+
+const ORIG_CLINE_DIR = process.env.CLINE_DIR;
+const ORIG_DATA_DIR = process.env.CLINE_DATA_DIR;
+const ORIG_PROVIDER_PATH = process.env.CLINE_PROVIDER_SETTINGS_PATH;
+let workDir;
+
+function freshWorkDir() {
+  workDir = mkdtempSync(join(tmpdir(), 'bizar-setup-provider-'));
+  // CLINE_DIR is the *base* dir (e.g. ~/.cline). The settings file
+  // lives at `${CLINE_DIR}/data/settings/providers.json`. Mocking
+  // CLINE_DIR is the easiest way to redirect the whole tree.
+  process.env.CLINE_DIR = workDir;
+  // Clear overrides that could change the resolution path.
+  delete process.env.CLINE_DATA_DIR;
+  delete process.env.CLINE_PROVIDER_SETTINGS_PATH;
+  return workDir;
+}
+
+function settingsFile() {
+  return join(workDir, 'data', 'settings', 'providers.json');
+}
+
+function makeFakeSettings(root, body = {}) {
+  const cfg = {
+    version: 1,
+    providers: {},
+    lastUsedProvider: 'litellm',
+    ...body,
+  };
+  const file = join(root, 'data', 'settings', 'providers.json');
+  mkdirSync(join(root, 'data', 'settings'), { recursive: true });
+  writeFileSync(file, JSON.stringify(cfg, null, 2));
+  return file;
+}
+
+beforeEach(() => {
+  workDir = freshWorkDir();
+});
+
+afterEach(() => {
+  if (workDir && existsSync(workDir)) rmSync(workDir, { recursive: true, force: true });
+  if (ORIG_CLINE_DIR === undefined) delete process.env.CLINE_DIR;
+  else process.env.CLINE_DIR = ORIG_CLINE_DIR;
+  if (ORIG_DATA_DIR === undefined) delete process.env.CLINE_DATA_DIR;
+  else process.env.CLINE_DATA_DIR = ORIG_DATA_DIR;
+  if (ORIG_PROVIDER_PATH === undefined) delete process.env.CLINE_PROVIDER_SETTINGS_PATH;
+  else process.env.CLINE_PROVIDER_SETTINGS_PATH = ORIG_PROVIDER_PATH;
+});
+
+describe('OPENAI_COMPATIBLE_PROVIDERS', () => {
+  test('includes litellm (the new v6.2.3 default)', () => {
+    assert.ok(OPENAI_COMPATIBLE_PROVIDERS.includes('litellm'),
+      'litellm must be the canonical openai-compatible providerId');
+  });
+  test('does NOT include the fake "openai-compatible" or "9router" IDs', () => {
+    assert.equal(OPENAI_COMPATIBLE_PROVIDERS.includes('openai-compatible'), false,
+      'openai-compatible is a family, not a valid providerId');
+    assert.equal(OPENAI_COMPATIBLE_PROVIDERS.includes('9router'), false,
+      '9router is not a built-in Cline providerId (would fail in kanban)');
+  });
+});
+
+describe('buildProviderBlock()', () => {
+  test('emits a Cline-settings-shaped block (version 1 + settings + updatedAt)', () => {
+    const block = buildProviderBlock({
+      name: 'litellm',
+      gateway: 'http://localhost:20128/v1',
+      apiKey: 'sk-test',
+      model: 'minimaxcustom/MiniMax-M3',
+    });
+    assert.ok(block.settings);
+    assert.equal(block.settings.provider, 'litellm');
+    assert.equal(block.settings.model, 'minimaxcustom/MiniMax-M3');
+    assert.equal(block.settings.apiKey, 'sk-test');
+    assert.equal(block.settings.baseUrl, 'http://localhost:20128/v1');
+    assert.ok(block.settings.reasoning);
+    assert.equal(block.settings.reasoning.enabled, false);
+    assert.ok(block.updatedAt);
+    assert.match(block.updatedAt, /^\d{4}-\d{2}-\d{2}T/);
+    assert.equal(block.tokenSource, 'manual');
+  });
+
+  test('wraps env-var-style keys in ${env:...}', () => {
+    const block = buildProviderBlock({
+      name: 'litellm',
+      gateway: 'http://localhost:20128/v1',
+      apiKey: 'NINEROUTER_KEY',
+      model: 'm1',
+    });
+    assert.equal(block.settings.apiKey, '${env:NINEROUTER_KEY}');
+  });
+
+  test('sets reasoning.enabled=true when reason=true', () => {
+    const block = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm', reason: true,
+    });
+    assert.equal(block.settings.reasoning.enabled, true);
+  });
+});
+
+describe('applyProviderBlock()', () => {
+  test('writes to ${CLINE_DIR}/data/settings/providers.json (NOT ~/.cline/cline.json)', () => {
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://localhost:20128/v1',
+      apiKey: 'sk-test', model: 'minimaxcustom/MiniMax-M3',
+    });
+    const r = applyProviderBlock('litellm', body);
+    const expected = settingsFile();
+    assert.equal(r.path, expected, 'must write to the Cline settings file');
+    assert.ok(existsSync(expected));
+  });
+
+  test('bootstraps the settings file when it does not exist', () => {
+    // No makeFakeSettings call.
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
+    });
+    const r = applyProviderBlock('litellm', body);
+    assert.ok(existsSync(r.path));
+    const cfg = JSON.parse(readFileSync(r.path, 'utf8'));
+    assert.equal(cfg.version, 1);
+    assert.equal(cfg.lastUsedProvider, 'litellm');
+    assert.ok(cfg.providers.litellm);
+  });
+
+  test('preserves other provider entries when adding a new one', () => {
+    makeFakeSettings(workDir, {
+      providers: { ollama: { settings: { provider: 'ollama', model: 'llama3' } } },
+    });
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
+    });
+    applyProviderBlock('litellm', body);
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.ok(cfg.providers.ollama, 'existing provider preserved');
+    assert.ok(cfg.providers.litellm, 'new provider added');
+  });
+
+  test('overwrites an existing provider with the same name', () => {
+    makeFakeSettings(workDir, {
+      providers: { litellm: { settings: { provider: 'litellm', baseUrl: 'https://old', model: 'old' } } },
+    });
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://new', apiKey: 'new', model: 'new',
+    });
+    applyProviderBlock('litellm', body);
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers.litellm.settings.baseUrl, 'http://new');
+    assert.equal(cfg.providers.litellm.settings.model, 'new');
+  });
+
+  test('creates a backup file', () => {
+    makeFakeSettings(workDir, {
+      providers: { x: { settings: { provider: 'x' } } },
+    });
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
+    });
+    const r = applyProviderBlock('litellm', body);
+    assert.ok(existsSync(r.backup), 'backup file created');
+    const backup = JSON.parse(readFileSync(r.backup, 'utf8'));
+    assert.ok(backup.providers.x, 'backup contains original entry');
+  });
+});
+
+describe('migrateLegacyOpenaiCompatible()', async () => {
+  const { migrateLegacyOpenaiCompatible } = await import('./setup-provider.mjs');
+
+  test('renames an openai-compatible entry to litellm (preserving baseUrl/apiKey/model)', () => {
+    makeFakeSettings(workDir, {
+      providers: {
+        'openai-compatible': {
+          settings: {
+            provider: 'openai-compatible',
+            baseUrl: 'http://localhost:20128/v1',
+            apiKey: 'sk-test',
+            model: 'minimaxcustom/MiniMax-M3',
+            reasoning: { enabled: false, effort: 'medium' },
+          },
+          updatedAt: '2026-07-09T21:20:00.000Z',
+          tokenSource: 'manual',
+        },
+      },
+      lastUsedProvider: 'openai-compatible',
+    });
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, true);
+    assert.equal(r.from, 'openai-compatible');
+    assert.equal(r.to, 'litellm');
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers['openai-compatible'], undefined, 'old key removed');
+    assert.ok(cfg.providers.litellm, 'new key added');
+    assert.equal(cfg.providers.litellm.settings.baseUrl, 'http://localhost:20128/v1', 'baseUrl preserved');
+    assert.equal(cfg.providers.litellm.settings.apiKey, 'sk-test', 'apiKey preserved');
+    assert.equal(cfg.providers.litellm.settings.model, 'minimaxcustom/MiniMax-M3', 'model preserved');
+    assert.equal(cfg.lastUsedProvider, 'litellm', 'active provider switched');
+  });
+
+  test('no-op when no legacy entry exists', () => {
+    makeFakeSettings(workDir, {
+      providers: { litellm: { settings: { provider: 'litellm' } } },
+    });
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, false);
+    assert.equal(r.reason, 'no legacy entry');
+  });
+
+  test('no-op when settings file missing', () => {
+    // No makeFakeSettings call
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, false);
+    assert.equal(r.reason, 'no settings file');
+  });
+
+  test('preserves lastUsedProvider when it pointed at a different entry', () => {
+    makeFakeSettings(workDir, {
+      providers: {
+        'openai-compatible': { settings: { provider: 'openai-compatible', baseUrl: 'http://a' } },
+        ollama: { settings: { provider: 'ollama' } },
+      },
+      lastUsedProvider: 'ollama',
+    });
+    migrateLegacyOpenaiCompatible('litellm');
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    // Should NOT clobber the active provider if it wasn't the broken one
+    assert.equal(cfg.lastUsedProvider, 'ollama', 'active ollama preserved');
+  });
+});
+
+describe('removeProvider()', () => {
+  test('removes a named provider', () => {
+    makeFakeSettings(workDir, {
+      providers: {
+        a: { settings: { provider: 'a' } },
+        b: { settings: { provider: 'b' } },
+      },
+    });
+    const r = removeProvider('a');
+    assert.equal(r.removed, true);
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers.a, undefined);
+    assert.ok(cfg.providers.b, 'untouched provider preserved');
+  });
+
+  test('returns removed=false when settings file is missing', () => {
+    const r = removeProvider('nope');
+    assert.equal(r.removed, false);
+    assert.equal(r.reason, 'no settings file');
+  });
+
+  test('returns removed=false for a missing provider', () => {
+    makeFakeSettings(workDir);
+    const r = removeProvider('nonexistent');
+    assert.equal(r.removed, false);
+    assert.equal(r.reason, 'not present');
+  });
+});
+
+describe('parseFlags()', () => {
+  test('parses --gateway, --key, --provider, --model with space separator', () => {
+    const f = parseFlags(['--gateway', 'http://x', '--key', 'sk-x', '--provider', 'litellm', '--model', 'm1']);
+    assert.equal(f.gateway, 'http://x');
+    assert.equal(f.key, 'sk-x');
+    assert.equal(f.provider, 'litellm');
+    assert.equal(f.model, 'm1');
+  });
+
+  test('parses equals form', () => {
+    const f = parseFlags(['--gateway=http://x', '--key=sk-x', '--provider=litellm', '--model=m1']);
+    assert.equal(f.gateway, 'http://x');
+    assert.equal(f.key, 'sk-x');
+    assert.equal(f.provider, 'litellm');
+    assert.equal(f.model, 'm1');
+  });
+
+  test('parses --list, --discover, --remove', () => {
+    const f = parseFlags(['--list', '--discover']);
+    assert.equal(f.list, true);
+    assert.equal(f.discover, true);
+    const g = parseFlags(['--remove', 'myprov']);
+    assert.equal(g.remove, 'myprov');
+  });
+});

package/cli/commands/validate.mjs

@@ -51,7 +51,7 @@ const REQUIRED_COMMANDS = [
   'audit.md', 'bizar.md', 'explain.md', 'init.md', 'learn.md',
   'plan.md', 'plow-through.md', 'pr-review.md', 'tailscale-serve.md',
   'visual-plan.md',
-  'team.md', 'test.md', 'validate.md',
+  'team.md', 'test.md', 'validate.md', 'setup-provider.md',
 ];
 
 // v6.2.1 — Cline-native hook scripts (executable, shebang, no extension).
@@ -65,6 +65,23 @@ const REQUIRED_HOOKS = [
 
 const REQUIRED_RUNTIME_DEPS = ['zod', '@cline/sdk', '@cline/core', '@cline/shared'];
 
+// v6.2.3 — Built-in Cline providerIds that are safe for any
+// "OpenAI-compatible endpoint" use case. The harness warns about
+// any providerId NOT in this set (since they fail in kanban mode).
+const OPENAI_COMPATIBLE_BUILTIN_IDS = new Set([
+  'litellm', 'cline', 'ollama', 'lmstudio', 'huggingface',
+  // Plus the first-class providers (also OpenAI-compatible):
+  'openrouter', 'deepseek', 'xai', 'together', 'fireworks',
+  'groq', 'cerebras', 'sambanova', 'nebius', 'baseten',
+  'requesty', 'vercel-ai-gateway', 'v0', 'aihubmix', 'hicap',
+  'nousResearch', 'huawei-cloud-maas', 'qwen', 'qwen-code',
+  'doubao', 'zai', 'zai-coding-plan', 'moonshot', 'wandb',
+  'xiaomi', 'kilo', 'oca', 'asksage', 'sapaicore',
+  // Non-OpenAI-compatible (kept so we don't false-positive):
+  'anthropic', 'google', 'bedrock', 'vertex', 'gemini',
+  'openai', 'openai-native', 'openai-codex',
+]);
+
 function check(name, fn) {
   return Promise.resolve()
     .then(fn)
@@ -266,20 +283,66 @@ const CHECKS = {
   },
 
   'provider-config': async () => {
+    // v6.2.2 — The installer no longer adds a provider block. The user
+    // must configure their own provider. This check is therefore
+    // ALWAYS lenient (returns a hint, never fails). It just reports
+    // what's in cline.json so the user can see the current state.
     const cfg = readJsonSafe(clineJsonPath());
-    if (!cfg?.provider) throw new Error('no provider block in cline.json');
-    const nine = cfg.provider['9router'];
-    if (nine && nine.baseUrl) {
-      const models = nine.models || {};
-      const count = Object.keys(models).length;
-      if (count === 0) throw new Error('provider.9router has no models');
-      return `provider.9router (${count} models, baseUrl=${nine.baseUrl})`;
+    if (!cfg?.provider || Object.keys(cfg.provider).length === 0) {
+      return 'no provider configured — user must add one. `bizar install` no longer touches provider config (v6.2.2+).';
+    }
+    const names = Object.keys(cfg.provider);
+    const summary = names.map((n) => {
+      const p = cfg.provider[n];
+      const url = p?.baseUrl || p?.options?.baseURL || '(no baseUrl)';
+      const modelCount = Object.keys(p?.models || {}).length;
+      return `${n} (${modelCount} models, baseUrl=${url})`;
+    });
+    return `user-configured providers: ${summary.join('; ')}`;
+  },
+
+  'cline-settings-provider': async () => {
+    // v6.2.3 — The Cline CLI and kanban mode read from
+    // `~/.cline/data/settings/providers.json`. The harness config
+    // (`cline.json`) is a separate thing. This check inspects the
+    // actual settings file and:
+    //   1. Warns if the user has a legacy `openai-compatible` providerId
+    //      (from the v6.0.1 Cline auto-migration shim). Kanban mode
+    //      fails on this with "Unknown or disabled provider". Run
+    //      `bizar setup-provider` to auto-migrate.
+    //   2. Reports the active `lastUsedProvider` so the user can
+    //      see which provider Cline will actually use on the next
+    //      session.
+    const file = join(homedir(), '.cline', 'data', 'settings', 'providers.json');
+    if (!existsSync(file)) {
+      return 'no settings file at ~/.cline/data/settings/providers.json — run `bizar setup-provider` to add one';
+    }
+    const settings = readJsonSafe(file);
+    if (!settings || !settings.providers) {
+      return 'settings file is empty or invalid — run `bizar setup-provider`';
     }
-    const minimax = cfg.provider.minimax;
-    if (!minimax) {
-      throw new Error('no provider.9router AND no provider.minimax');
+    const names = Object.keys(settings.providers);
+    if (names.length === 0) {
+      throw new Error('no providers configured in Cline settings — run `bizar setup-provider`');
     }
-    return 'provider.minimax (legacy fallback)';
+    const issues = [];
+    if (names.includes('openai-compatible')) {
+      issues.push(`legacy 'openai-compatible' providerId present (broken in kanban mode) — run \`bizar setup-provider\` to auto-migrate to 'litellm'`);
+    }
+    // Check for any providerId that's not in Cline's built-in catalog.
+    for (const n of names) {
+      if (n === 'openai-compatible') continue; // handled above
+      if (!OPENAI_COMPATIBLE_BUILTIN_IDS.has(n)) {
+        issues.push(`'${n}' providerId is NOT in Cline's built-in catalog (likely broken in kanban mode)`);
+      }
+    }
+    const lastUsed = settings.lastUsedProvider || '(none)';
+    if (issues.length > 0) {
+      // Throw so the ⚠ marker shows up; the check is in LENIENT_CHECKS
+      // so this won't cause `bizar validate` to exit non-zero.
+      throw new Error(`WARN: ${issues.join('; ')}. lastUsedProvider=${lastUsed} (${names.join(', ')})`);
+    }
+    return `lastUsedProvider=${lastUsed}; providers: ${names.join(', ')}`;
   },
 
   '9router-reachable': async () => {
@@ -369,10 +432,15 @@ const CHECK_ORDER = [
   'default-agent-set',
   'instructions-loaded',
   'provider-config',
+  'cline-settings-provider',
   '9router-reachable',
 ];
 
-const LENIENT_CHECKS = new Set(['9router-reachable']);
+const LENIENT_CHECKS = new Set([
+  '9router-reachable',
+  'provider-config', // v6.2.2+ — installer no longer touches provider config; user must configure
+  'cline-settings-provider', // v6.2.3 — warns about legacy/fake providerIds; non-blocking
+]);
 
 export function showValidateHelp() {
   console.log(`

package/cli/commands/validate.test.mjs

@@ -68,7 +68,7 @@ function makeFakeClineInstall(root) {
     'audit.md', 'bizar.md', 'explain.md', 'init.md', 'learn.md',
     'plan.md', 'plow-through.md', 'pr-review.md', 'tailscale-serve.md',
     'visual-plan.md',
-    'team.md', 'test.md', 'validate.md',
+    'team.md', 'test.md', 'validate.md', 'setup-provider.md',
   ]) {
     writeFileSync(join(cmdsDir, f), '# fake command');
   }
@@ -205,28 +205,54 @@ describe('runValidate() — JSON output', () => {
     assert.equal(exitCode, 1, 'should fail when enableAgentTeams is false');
   });
 
-  test('fails when provider config is missing', async () => {
+  test('passes when no provider is configured (v6.2.2+ — user must configure)', async () => {
+    // v6.2.2: the installer no longer touches provider config. The
+    // user must add their own provider. The provider-config check
+    // is therefore ALWAYS lenient — it just reports state.
     const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
     delete cfg.provider;
     writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
-    const { exitCode } = await captureRun({ json: true });
-    assert.equal(exitCode, 1);
+    const { exitCode, stdout } = await captureRun({ json: true });
+    assert.equal(exitCode, 0, 'no-provider must not fail validation (v6.2.2+ contract)');
+    const parsed = JSON.parse(stdout);
+    const p = parsed.results.find((r) => r.name === 'provider-config');
+    assert.ok(p, 'provider-config check should be present');
+    assert.equal(p.ok, true, 'provider-config always returns ok (lenient)');
+    assert.match(p.message, /no provider configured/);
   });
 
-  test('passes when only 9router is configured (no minimax)', async () => {
+  test('reports user-configured providers when present', async () => {
+    // User has set up their own provider (anything goes).
     const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    delete cfg.provider.minimax;
+    cfg.provider = {
+      'my-custom-provider': {
+        baseUrl: 'https://my-llm.example/v1',
+        apiKey: 'sk-test',
+        models: { 'my-model-1': {}, 'my-model-2': {} },
+      },
+    };
     writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
-    const { exitCode } = await captureRun({ json: true });
+    const { exitCode, stdout } = await captureRun({ json: true });
     assert.equal(exitCode, 0);
+    const parsed = JSON.parse(stdout);
+    const p = parsed.results.find((r) => r.name === 'provider-config');
+    assert.match(p.message, /my-custom-provider/);
+    assert.match(p.message, /2 models/);
   });
 
-  test('passes when only minimax is configured (no 9router)', async () => {
+  test('reports both providers if user has multiple', async () => {
     const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    delete cfg.provider['9router'];
+    cfg.provider = {
+      'a': { baseUrl: 'https://a.example/v1', models: { 'm1': {} } },
+      'b': { baseUrl: 'https://b.example/v1', models: { 'm2': {}, 'm3': {} } },
+    };
     writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
-    const { exitCode } = await captureRun({ json: true });
+    const { exitCode, stdout } = await captureRun({ json: true });
     assert.equal(exitCode, 0);
+    const parsed = JSON.parse(stdout);
+    const p = parsed.results.find((r) => r.name === 'provider-config');
+    assert.match(p.message, /\ba\b/);
+    assert.match(p.message, /\bb\b/);
   });
 
   test('default mode is lenient on 9router-unreachable', async () => {