@polderlabs/bizar 3.12.1 → 3.12.2

package/cli/doctor.mjs

@@ -0,0 +1,275 @@
+/**
+ * cli/doctor.mjs
+ *
+ * v3.12.2 — `bizar doctor` subcommand.
+ *
+ * Runs a battery of health checks against the local Bizar / opencode
+ * install and reports pass/fail for each. Returns a structured summary
+ * suitable for callers (e.g. `bizar update`) that want to act on the
+ * result without re-printing the per-check output.
+ *
+ * The checks are intentionally tolerant: missing optional tools
+ * (rtk/semble/skills) don't fail the run, and the dashboard check is
+ * skipped silently if no port file exists. The goal is "is your
+ * install healthy?" not "is every conceivable thing present?".
+ *
+ * Usage:
+ *   import { runDoctor } from './doctor.mjs';
+ *   const r = await runDoctor();                    // prints everything
+ *   const r = await runDoctor({ silent: true });    // returns summary only
+ */
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { opencodeConfigDir, opencodeAgentsDir } from './utils.mjs';
+
+const REQUIRED_AGENTS = ['odin.md', 'quick.md', 'thor.md', 'tyr.md'];
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function bizarConfigDir() {
+  return process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : join(homedir(), '.config', 'bizar');
+}
+
+/**
+ * Run a check function and capture its result. The check either
+ * returns a string message (pass) or throws an Error (fail).
+ */
+async function runCheck(name, fn) {
+  try {
+    const message = await fn();
+    return { name, ok: true, message: message || 'ok' };
+  } catch (err) {
+    return {
+      name,
+      ok: false,
+      message: err && err.message ? err.message : String(err),
+    };
+  }
+}
+
+function which(cmd) {
+  const probe = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+// ── individual checks ───────────────────────────────────────────────────────
+
+async function checkOpencodeReachable() {
+  const r = spawnSync('opencode', ['--version'], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  if (r.status !== 0) {
+    throw new Error(`opencode --version exited ${r.status}`);
+  }
+  return (r.stdout || r.stderr || '').trim().split('\n')[0] || 'opencode available';
+}
+
+async function checkConfigValid() {
+  const cfgPath = join(opencodeConfigDir(), 'opencode.json');
+  if (!existsSync(cfgPath)) {
+    throw new Error(`not found at ${cfgPath}`);
+  }
+  try {
+    JSON.parse(readFileSync(cfgPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`invalid JSON: ${err.message}`);
+  }
+  return 'opencode.json parses';
+}
+
+async function checkPluginEntryPresent() {
+  const cfgPath = join(opencodeConfigDir(), 'opencode.json');
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+  const plugins = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+  if (plugins.length === 0) {
+    throw new Error('no plugin entries in opencode.json');
+  }
+  const hasBizar = plugins.some((p) => {
+    if (typeof p === 'string') return p.includes('bizar');
+    if (p && typeof p === 'object') {
+      return (
+        (p.name || '').includes('bizar') ||
+        (p.path || '').includes('bizar')
+      );
+    }
+    return false;
+  });
+  if (!hasBizar) {
+    throw new Error('bizar not found in plugin[]');
+  }
+  return 'bizar present in plugin[]';
+}
+
+async function checkPluginPathResolves() {
+  const cfgPath = join(opencodeConfigDir(), 'opencode.json');
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+  const plugins = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+  let lastChecked = null;
+  for (const p of plugins) {
+    if (!p || typeof p !== 'object' || !p.path) continue;
+    const entryPath = p.path;
+    const isAbs = entryPath.startsWith('/') || /^[a-z]:[\\/]/i.test(entryPath);
+    const resolved = isAbs ? entryPath : join(opencodeConfigDir(), entryPath);
+    lastChecked = resolved;
+    if (!existsSync(resolved)) {
+      throw new Error(`plugin path does not exist: ${resolved}`);
+    }
+  }
+  if (lastChecked === null) {
+    return 'no plugin path to check';
+  }
+  return `plugin path resolves: ${lastChecked}`;
+}
+
+async function checkDeployedPluginPresent() {
+  const r = spawnSync('npm', ['root', '-g'], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  if (r.status !== 0) {
+    throw new Error('npm root -g failed');
+  }
+  const root = (r.stdout || '').trim();
+  const pkgPath = join(root, '@polderlabs', 'bizar-plugin', 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error('@polderlabs/bizar-plugin not installed globally');
+  }
+  return '@polderlabs/bizar-plugin present';
+}
+
+async function checkAgentFilesInstalled() {
+  const dir = opencodeAgentsDir();
+  if (!existsSync(dir)) {
+    throw new Error(`agents dir missing: ${dir}`);
+  }
+  const missing = REQUIRED_AGENTS.filter((f) => !existsSync(join(dir, f)));
+  if (missing.length > 0) {
+    throw new Error(`missing: ${missing.join(', ')}`);
+  }
+  return `all ${REQUIRED_AGENTS.length} core agents present`;
+}
+
+/**
+ * Lenient: passes if at least one of rtk/semble/skills is on PATH.
+ * These are informational — none of them are strictly required for
+ * `bizar doctor` to do its job, and missing them shouldn't fail the
+ * overall health report.
+ */
+async function checkToolsAvailable() {
+  const tools = ['rtk', 'semble', 'skills'];
+  const found = tools.filter(which);
+  if (found.length === 0) {
+    throw new Error(`none of ${tools.join('/')} on PATH`);
+  }
+  return `available: ${found.join(', ')}`;
+}
+
+async function checkDashboardReachable() {
+  const portFile = join(bizarConfigDir(), 'dashboard.port');
+  if (!existsSync(portFile)) {
+    return 'no dashboard port file (skipped)';
+  }
+  let port;
+  try {
+    port = parseInt(readFileSync(portFile, 'utf8').trim(), 10);
+  } catch {
+    throw new Error(`could not read port from ${portFile}`);
+  }
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error(`invalid port in ${portFile}: ${port}`);
+  }
+  const r = spawnSync(
+    'curl',
+    ['-fsS', '-m', '2', `http://127.0.0.1:${port}/api/health`],
+    { encoding: 'utf8', timeout: 5000 },
+  );
+  if (r.status !== 0) {
+    throw new Error(`dashboard on port ${port} not reachable`);
+  }
+  return `dashboard reachable on port ${port}`;
+}
+
+async function checkProviderConfigSanity() {
+  const cfgPath = join(opencodeConfigDir(), 'opencode.json');
+  if (!existsSync(cfgPath)) {
+    throw new Error('opencode.json missing');
+  }
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+  const openrouter = cfg.provider && cfg.provider.openrouter;
+  if (!openrouter) {
+    throw new Error('provider.openrouter block missing');
+  }
+  const models = openrouter.models || {};
+  const saneNames = Object.entries(models).filter(([, m]) => {
+    return (
+      m &&
+      typeof m === 'object' &&
+      'interleaved' in m &&
+      'reasoning' in m
+    );
+  });
+  if (saneNames.length === 0) {
+    throw new Error(
+      'no MiniMax-style model with interleaved + reasoning flags',
+    );
+  }
+  return `provider.openrouter + ${saneNames.length} model(s) sane`;
+}
+
+const CHECKS = [
+  ['opencode-reachable', checkOpencodeReachable],
+  ['opencode-config-valid', checkConfigValid],
+  ['plugin-entry-present', checkPluginEntryPresent],
+  ['plugin-path-resolves', checkPluginPathResolves],
+  ['deployed-plugin-present', checkDeployedPluginPresent],
+  ['agent-files-installed', checkAgentFilesInstalled],
+  ['tools-available', checkToolsAvailable],
+  ['dashboard-reachable', checkDashboardReachable],
+  ['provider-config-sanity', checkProviderConfigSanity],
+];
+
+// ── public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Run all health checks. Prints per-check output unless `opts.silent`.
+ * Always prints a final summary line. Returns `{ passed, failed, results }`.
+ */
+export async function runDoctor(opts = {}) {
+  const silent = !!opts.silent;
+  const results = [];
+  for (const [name, fn] of CHECKS) {
+    const r = await runCheck(name, fn);
+    results.push(r);
+    if (!silent) {
+      const marker = r.ok ? chalk.green('✓') : chalk.red('✗');
+      const label = name.padEnd(28);
+      const msg = r.ok ? chalk.dim(`  ${r.message}`) : chalk.red(`  ${r.message}`);
+      console.log(`  ${marker} ${label}${msg}`);
+    }
+  }
+
+  const passed = results.filter((r) => r.ok).length;
+  const failed = results.length - passed;
+
+  // Always print a summary line if there were failures, or if not silent.
+  if (failed > 0 || !silent) {
+    console.log('');
+    if (failed === 0) {
+      console.log(
+        chalk.green(`  ✓ ${passed} checks passed, ${failed} failed`),
+      );
+    } else {
+      console.log(
+        chalk.yellow(`  ⚠ ${passed} checks passed, ${failed} failed`),
+      );
+    }
+  }
+
+  return { passed, failed, results };
+}

package/cli/doctor.test.mjs

@@ -0,0 +1,312 @@
+/**
+ * cli/doctor.test.mjs
+ *
+ * Tests for the `bizar doctor` subcommand. Uses Node's built-in
+ * node:test (no external test framework).
+ *
+ * Strategy: mock HOME so opencodeConfigDir() resolves inside a
+ * tmpdir, and craft the opencode.json + agents/ directory to drive
+ * specific pass/fail outcomes. For checks that depend on global
+ * npm-installed packages or external CLIs (e.g. opencode --version,
+ * npm root -g, which rtk), we accept that they may pass or fail
+ * depending on the test environment and just verify the framework
+ * returns the right shape.
+ */
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  existsSync,
+  utimesSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
+
+const { runDoctor } = await import('./doctor.mjs');
+
+// ── HOME mocking ────────────────────────────────────────────────────────────
+
+const ORIG_HOME = process.env.HOME;
+const ORIG_XDG = process.env.XDG_CONFIG_HOME;
+
+/**
+ * Mock HOME so opencodeConfigDir() resolves to `<tmpdir>/.config/opencode`.
+ * Returns the tmpdir path.
+ *
+ * We don't set XDG_CONFIG_HOME here for the same reason as dev-link.test.mjs:
+ * the helper treats a set XDG_CONFIG_HOME as the direct parent (so
+ * `XDG_CONFIG_HOME=~/.config` → `~/.config/opencode`).
+ */
+function freshHome() {
+  const home = mkdtempSync(join(tmpdir(), 'bizar-doctor-'));
+  process.env.HOME = home;
+  delete process.env.XDG_CONFIG_HOME;
+  return home;
+}
+
+afterEach(() => {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+  if (ORIG_XDG === undefined) delete process.env.XDG_CONFIG_HOME;
+  else process.env.XDG_CONFIG_HOME = ORIG_XDG;
+});
+
+// ── Shape & silent-mode tests ───────────────────────────────────────────────
+
+describe('runDoctor() shape', () => {
+  let home;
+
+  beforeEach(() => {
+    home = freshHome();
+  });
+
+  afterEach(() => {
+    if (home && existsSync(home)) rmSync(home, { recursive: true, force: true });
+  });
+
+  test('returns { passed, failed, results }', async () => {
+    const result = await runDoctor({ silent: true });
+    assert.equal(typeof result.passed, 'number');
+    assert.equal(typeof result.failed, 'number');
+    assert.ok(Array.isArray(result.results));
+    // results should have one entry per check
+    assert.equal(result.results.length, 9);
+    assert.equal(result.passed + result.failed, 9);
+    // Each result has the expected fields
+    for (const r of result.results) {
+      assert.equal(typeof r.name, 'string');
+      assert.equal(typeof r.ok, 'boolean');
+      assert.equal(typeof r.message, 'string');
+    }
+  });
+
+  test('silent mode suppresses per-check output but still prints summary on failure', async () => {
+    // Capture stdout by overriding console.log.
+    const lines = [];
+    const origLog = console.log;
+    console.log = (...args) => {
+      lines.push(args.join(' '));
+    };
+
+    try {
+      // Empty home → many checks will fail → summary should print.
+      const result = await runDoctor({ silent: true });
+      assert.ok(result.failed > 0, 'precondition: some checks should fail');
+    } finally {
+      console.log = origLog;
+    }
+
+    // In silent mode with failures, only the summary line should print
+    // (an empty leading line is also fine — it's a visual separator).
+    const summaryLines = lines.filter((l) => /checks passed.*failed/.test(l));
+    assert.equal(
+      summaryLines.length,
+      1,
+      `expected exactly 1 summary line in silent+failed mode, got ${summaryLines.length}:\n${lines.join('\n')}`,
+    );
+    assert.match(summaryLines[0], /checks passed.*failed/);
+  });
+
+  test('silent mode suppresses ALL output when nothing fails', async () => {
+    // Build a fully healthy environment. We can't make opencode reachable
+    // or rtk installed without modifying PATH, so we settle for: no failures
+    // means no output at all. Since we know some checks will fail in a
+    // bare tmpdir, this test is structured to assert the negative case
+    // differently: we verify silent+no-fail produces 0 lines.
+    //
+    // For this we mock nothing — the test just confirms the framework
+    // doesn't print per-check lines when silent is true.
+    const lines = [];
+    const origLog = console.log;
+    console.log = (...args) => {
+      lines.push(args.join(' '));
+    };
+
+    try {
+      await runDoctor({ silent: true });
+      // Some checks failed (because the env isn't fully healthy).
+      // What we want to verify is that per-check lines did NOT print.
+      const perCheckLines = lines.filter((l) =>
+        /^\s+[✓✗]\s/.test(l) // chalk check markers
+      );
+      assert.equal(
+        perCheckLines.length,
+        0,
+        `silent mode should suppress per-check output, got:\n${perCheckLines.join('\n')}`,
+      );
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  test('non-silent mode prints per-check output', async () => {
+    const lines = [];
+    const origLog = console.log;
+    console.log = (...args) => {
+      lines.push(args.join(' '));
+    };
+
+    try {
+      await runDoctor();
+    } finally {
+      console.log = origLog;
+    }
+
+    // Should have at least 9 per-check lines plus the summary.
+    const perCheckLines = lines.filter((l) => /^\s+[✓✗]\s/.test(l));
+    assert.ok(
+      perCheckLines.length >= 9,
+      `expected ≥9 per-check lines, got ${perCheckLines.length}`,
+    );
+  });
+});
+
+// ── Fixture-driven pass/fail tests ──────────────────────────────────────────
+
+describe('runDoctor() with fixture HOME', () => {
+  let home;
+
+  beforeEach(() => {
+    home = freshHome();
+  });
+
+  afterEach(() => {
+    if (home && existsSync(home)) rmSync(home, { recursive: true, force: true });
+  });
+
+  function writeOpencodeConfig(json) {
+    const cfgDir = join(home, '.config', 'opencode');
+    mkdirSync(cfgDir, { recursive: true });
+    writeFileSync(join(cfgDir, 'opencode.json'), JSON.stringify(json), 'utf8');
+    return cfgDir;
+  }
+
+  function writeAgents(...files) {
+    const agentsDir = join(home, '.config', 'opencode', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+    for (const f of files) {
+      writeFileSync(join(agentsDir, f), `# ${f}`, 'utf8');
+    }
+    return agentsDir;
+  }
+
+  function findCheck(result, name) {
+    return result.results.find((r) => r.name === name);
+  }
+
+  test('config-valid passes for parseable JSON', async () => {
+    writeOpencodeConfig({ provider: {} });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'opencode-config-valid');
+    assert.equal(r.ok, true, `expected config-valid to pass: ${r.message}`);
+  });
+
+  test('config-valid fails for missing opencode.json', async () => {
+    // No opencode.json written.
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'opencode-config-valid');
+    assert.equal(r.ok, false);
+    assert.match(r.message, /not found/);
+  });
+
+  test('config-valid fails for invalid JSON', async () => {
+    const cfgDir = writeOpencodeConfig({});
+    // Overwrite with garbage
+    writeFileSync(join(cfgDir, 'opencode.json'), '{ this is not json', 'utf8');
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'opencode-config-valid');
+    assert.equal(r.ok, false);
+    assert.match(r.message, /invalid JSON/);
+  });
+
+  test('plugin-entry-present fails when plugin[] is empty', async () => {
+    writeOpencodeConfig({ plugin: [] });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'plugin-entry-present');
+    assert.equal(r.ok, false);
+  });
+
+  test('plugin-entry-present fails when plugin[] has no bizar', async () => {
+    writeOpencodeConfig({ plugin: ['something-else'] });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'plugin-entry-present');
+    assert.equal(r.ok, false);
+  });
+
+  test('plugin-entry-present passes when plugin[] has bizar string', async () => {
+    writeOpencodeConfig({ plugin: ['bizar'] });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'plugin-entry-present');
+    assert.equal(r.ok, true, r.message);
+  });
+
+  test('plugin-entry-present passes when plugin[] has bizar object', async () => {
+    writeOpencodeConfig({ plugin: [{ name: 'bizar', path: './plugins/bizar' }] });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'plugin-entry-present');
+    assert.equal(r.ok, true, r.message);
+  });
+
+  test('agent-files-installed fails when core agents missing', async () => {
+    writeOpencodeConfig({});
+    writeAgents('odin.md'); // missing quick, thor, tyr
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'agent-files-installed');
+    assert.equal(r.ok, false);
+    assert.match(r.message, /missing/);
+  });
+
+  test('agent-files-installed passes when all core agents present', async () => {
+    writeOpencodeConfig({});
+    writeAgents('odin.md', 'quick.md', 'thor.md', 'tyr.md');
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'agent-files-installed');
+    assert.equal(r.ok, true, r.message);
+  });
+
+  test('provider-config-sanity fails without openrouter block', async () => {
+    writeOpencodeConfig({ provider: {} });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'provider-config-sanity');
+    assert.equal(r.ok, false);
+    assert.match(r.message, /openrouter/);
+  });
+
+  test('provider-config-sanity fails when models lack interleaved+reasoning', async () => {
+    writeOpencodeConfig({
+      provider: {
+        openrouter: {
+          models: { 'some-model': { id: 'foo' } },
+        },
+      },
+    });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'provider-config-sanity');
+    assert.equal(r.ok, false);
+    assert.match(r.message, /interleaved.*reasoning/);
+  });
+
+  test('provider-config-sanity passes with interleaved+reasoning', async () => {
+    writeOpencodeConfig({
+      provider: {
+        openrouter: {
+          models: {
+            'MiniMax/MiniMax-M3': { interleaved: true, reasoning: true },
+          },
+        },
+      },
+    });
+    const result = await runDoctor({ silent: true });
+    const r = findCheck(result, 'provider-config-sanity');
+    assert.equal(r.ok, true, r.message);
+  });
+});
+
+console.log('  doctor.mjs tests loaded — run with: node --test cli/doctor.test.mjs');

package/cli/install.mjs

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import boxen from 'boxen';
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { showBanner, showPantheon, sectionHeading } from './banner.mjs';
@@ -26,13 +26,56 @@ const AGENT_FILES = [
  * `opencodeConfigDir()`). Otherwise, prints a hint directing the user to run
  * `npm install -g @polderlabs/bizar-plugin`.
  *
- * Returns `true` if the plugin was installed, `false` otherwise. Never throws.
+ * Symlink guard (v3.12.2): if the dest is a symlink (e.g. created by
+ * `bizar dev-link`), do NOT overwrite it. The copy below would otherwise
+ * dereference the symlink and silently turn it back into a real directory,
+ * breaking the dev workflow. Pass `{ force: true }` to override (after
+ * confirming the user really wants the deployed copy back).
+ *
+ * Pass `{ silent: true }` to suppress the warning prints; the function
+ * still returns `true` if the dest is already in the desired state.
+ *
+ * Returns `true` if the plugin was installed (or already in place),
+ * `false` otherwise. Never throws.
  */
-export async function installPluginFromGlobal() {
+export async function installPluginFromGlobal(opts = {}) {
   const { execSync } = await import('node:child_process');
   const { mkdir, readdir, copyFile } = await import('node:fs/promises');
   const { join } = await import('node:path');
 
+  // ── Symlink guard ───────────────────────────────────────────────────────────
+  // If dest is a symlink (created by `bizar dev-link`), don't overwrite it.
+  // A plain copy would dereference the symlink and silently break the
+  // dev workflow. Print a hint unless silent, or honour an explicit
+  // --force from the caller.
+  const destDir = join(opencodeConfigDir(), 'plugins', 'bizar');
+  let destIsSymlink = false;
+  try {
+    destIsSymlink = lstatSync(destDir).isSymbolicLink();
+  } catch {
+    // doesn't exist yet — fine
+  }
+
+  if (destIsSymlink) {
+    if (opts.silent) {
+      // Called from dev-unlink, which has already removed the symlink.
+      // If we somehow still see one here, treat as "already restored".
+      return true;
+    }
+    console.log(
+      chalk.yellow(
+        '  ⚠ ~/.config/opencode/plugins/bizar is a dev symlink — skipping npm copy.',
+      ),
+    );
+    console.log(
+      chalk.dim(
+        '    Run `bizar dev-unlink` to restore the deployed copy, or pass --force to overwrite.',
+      ),
+    );
+    if (!opts.force) return false;
+    rmSync(destDir, { force: true });
+  }
+
   let globalRoot;
   try {
     globalRoot = execSync('npm root -g', { stdio: ['ignore', 'pipe', 'ignore'] })
@@ -50,7 +93,6 @@ export async function installPluginFromGlobal() {
     return false;
   }
 
-  const destDir = join(opencodeConfigDir(), 'plugins', 'bizar');
   await mkdir(destDir, { recursive: true });
 
   async function copyRecursive(srcDir, dstDir) {