@polderlabs/bizar 3.12.1 → 3.12.3

package/cli/bin.mjs

@@ -88,6 +88,9 @@ function showHelp() {
     service             Manage the background service daemon
     bg <subcommand>     Manage background agents (list/view/kill/logs)
     dash <subcommand>   Manage the dashboard (start/stop/status/tui)
+    dev-link [src]      Symlink the local plugin source into opencode's plugin dir
+    dev-unlink          Remove the dev symlink and restore the deployed copy
+    doctor              Check the BizarHarness install for health issues
 
   Examples:
     bizar install
@@ -96,6 +99,8 @@ function showHelp() {
     bizar dash start --bg
     bizar dash stop
     bizar dash status
+    bizar doctor
+    bizar update --all --dry-run
 
   Run \`bizar <command> --help\` for per-command help.
 
@@ -185,6 +190,7 @@ function showUpdateHelp() {
     bizar update opencode bizar dash    Update specific components
     bizar update --all --yes           Update everything + auto-kill running instances
     bizar update --no-restart          Don't auto-restart the dashboard after update
+    bizar update --dry-run             Print what would happen, change nothing
     bizar update --help                Show this help
 
   Components:
@@ -206,11 +212,17 @@ function showUpdateHelp() {
     • If the dashboard was running and bizar or dash was updated,
       spawns a fresh detached dashboard process with the new code
       (skipped with --no-restart).
+    • Runs \`bizar doctor\` after a successful update to catch config
+      regressions before opencode tries to start.
+    • If ~/.config/opencode/plugins/bizar is a dev symlink (created
+      by \`bizar dev-link\`), the copy step is skipped to preserve the
+      link. Use \`bizar dev-unlink\` first, or pass --force.
 
   Examples:
     bizar update --all --yes           Headless full update + restart
     bizar update dash                  Update only the dashboard
     bizar update plugin --no-restart   Plugin-only, leave dashboard alone
+    bizar update --all --dry-run       See what would change without doing it
   `);
 }
 
@@ -220,6 +232,69 @@ function showTestGateHelp() {
   `);
 }
 
+function showDevLinkHelp() {
+  console.log(`
+  bizar dev-link / dev-unlink — Manage a symlink from the opencode plugin dir
+  to a local source checkout, so edits propagate to opencode on next session.
+
+  Usage:
+    bizar dev-link [source-dir]    Symlink source-dir (default: ./plugins/bizar)
+                                   to ~/.config/opencode/plugins/bizar
+    bizar dev-link --force         Replace an existing deployed copy
+    bizar dev-unlink               Remove the dev symlink + restore from npm
+    bizar dev-unlink --force       Remove even if not a symlink (destructive)
+
+  Description:
+    By default, opencode loads the Bizar plugin from
+    ~/.config/opencode/plugins/bizar, which is a real directory copied
+    from the npm package. Edits to plugins/bizar/ in the BizarHarness
+    repo don't propagate until you re-run the installer.
+
+    \`bizar dev-link\` replaces that directory with a symlink pointing
+    at your local checkout, so source edits are picked up immediately.
+    \`bizar dev-unlink\` reverses the change by removing the symlink
+    and re-installing the deployed copy from the npm package.
+
+    While the dev link is in place, \`bizar update\` will skip the
+    plugin-copy step (and print a warning) so it doesn't clobber the
+    link. Run \`bizar dev-unlink\` first, or pass --force to overwrite.
+
+  Examples:
+    bizar dev-link
+    bizar dev-link /home/me/projects/bizar/plugins/bizar
+    bizar dev-link --force
+    bizar dev-unlink
+  `);
+}
+
+function showDoctorHelp() {
+  console.log(`
+  bizar doctor — Check the BizarHarness install for health issues
+
+  Usage:
+    bizar doctor
+
+  Description:
+    Runs a battery of health checks against the local install:
+      • opencode CLI reachable
+      • ~/.config/opencode/opencode.json parses as JSON
+      • the Bizar plugin is registered
+      • plugin path resolves
+      • @polderlabs/bizar-plugin is installed globally
+      • core agent files are installed (odin, quick, thor, tyr)
+      • rtk / semble / skills on PATH (lenient — at least one)
+      • dashboard reachable (skipped if no port file)
+      • provider.openrouter block + MiniMax model flags are sane
+
+    Prints ✓/✗ for each check and a final summary. Exits non-zero
+    if any check fails. Use \`bizar doctor\` after a manual config
+    edit or to diagnose "why is opencode misbehaving?" questions.
+
+  Related:
+    bizar update              Update + auto-run doctor on success
+  `);
+}
+
 function showServiceHelp() {
   const bizarConfigDir = getBizarConfigDir();
   console.log(`
@@ -424,6 +499,32 @@ async function main() {
   } else if (args[0] === 'update') {
     if (isHelpRequest) showUpdateHelp();
     else await runUpdate(args.slice(1));
+  } else if (args[0] === 'dev-link') {
+    if (isHelpRequest) showDevLinkHelp();
+    else {
+      const { createDevLink } = await import('./dev-link.mjs');
+      const positional = args.slice(1).filter((a) => !a.startsWith('-'));
+      const flags = args.slice(1).filter((a) => a.startsWith('-'));
+      const sourceDir = positional[0] ?? null;
+      const force = flags.includes('--force') || flags.includes('-f');
+      const ok = createDevLink(sourceDir, { force });
+      if (!ok) process.exit(1);
+    }
+  } else if (args[0] === 'dev-unlink') {
+    if (isHelpRequest) showDevLinkHelp();
+    else {
+      const { removeDevLink } = await import('./dev-link.mjs');
+      const force = args.includes('--force') || args.includes('-f');
+      const ok = await removeDevLink({ force });
+      if (!ok) process.exit(1);
+    }
+  } else if (args[0] === 'doctor') {
+    if (isHelpRequest) showDoctorHelp();
+    else {
+      const { runDoctor } = await import('./doctor.mjs');
+      const result = await runDoctor();
+      if (result.failed > 0) process.exit(1);
+    }
   } else if (args[0] === 'plan') {
     await runPlan(args.slice(1), {});
   } else if (args[0] === 'install') {

package/cli/dev-link.mjs

@@ -0,0 +1,175 @@
+/**
+ * cli/dev-link.mjs
+ *
+ * v3.12.2 — `bizar dev-link` / `bizar dev-unlink` subcommands.
+ *
+ * The Bizar opencode plugin lives at:
+ *   ~/.config/opencode/plugins/bizar   (the deployed copy, written by installPluginFromGlobal)
+ *
+ * When developing the plugin source under <repo>/plugins/bizar/, edits
+ * don't auto-propagate to opencode because the deployed copy is a real
+ * directory. `bizar dev-link` creates a symlink so that source edits
+ * are picked up on the next opencode session. `bizar dev-unlink`
+ * restores the deployed copy from the npm package.
+ *
+ * Symlink guard: installPluginFromGlobal refuses to overwrite a
+ * symlink (the underlying `cp -r` would dereference it and silently
+ * break the dev workflow). Combined with that guard, `bizar update` is
+ * safe to run while a dev link is in place — it prints a warning and
+ * leaves the link alone (use `--force` or `bizar dev-unlink` first).
+ */
+import chalk from 'chalk';
+import {
+  lstatSync,
+  rmSync,
+  symlinkSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { opencodeConfigDir } from './utils.mjs';
+
+/**
+ * Path of the deployed plugin. Reads XDG_CONFIG_HOME / HOME at call
+ * time so tests can mock HOME.
+ */
+function pluginDest() {
+  return join(opencodeConfigDir(), 'plugins', 'bizar');
+}
+
+/**
+ * Create a symlink from ~/.config/opencode/plugins/bizar to the
+ * local source dir (default: <cwd>/plugins/bizar).
+ *
+ * Behavior:
+ *   - dest does not exist         → create symlink
+ *   - dest is a symlink           → replace it
+ *   - dest is a real directory    → refuse unless opts.force
+ *
+ * Returns true on success, false on refusal.
+ */
+export function createDevLink(sourceDir = null, opts = {}) {
+  const resolvedSource = resolve(process.cwd(), sourceDir ?? 'plugins/bizar');
+  const dest = pluginDest();
+  const parentDir = join(dest, '..');
+
+  // Make sure ~/.config/opencode/plugins/ exists.
+  if (!existsSync(parentDir)) {
+    mkdirSync(parentDir, { recursive: true });
+  }
+
+  // Probe existing dest state. Use lstat so we see the symlink itself,
+  // not its target.
+  let existing = null;
+  let isSymlink = false;
+  try {
+    existing = lstatSync(dest);
+    isSymlink = existing.isSymbolicLink();
+  } catch {
+    // doesn't exist — we will create.
+  }
+
+  if (existing && !isSymlink) {
+    if (!opts.force) {
+      console.log(chalk.yellow(`  ⚠ ${dest} exists and is not a symlink.`));
+      console.log(chalk.yellow(`    Refusing to overwrite the deployed copy.`));
+      console.log(
+        chalk.dim(
+          `    Use --force to replace it, or remove it manually before running \`bizar dev-link\`.`,
+        ),
+      );
+      return false;
+    }
+    console.log(chalk.yellow(`  ⚠ Replacing existing deployed copy at ${dest}`));
+    rmSync(dest, { recursive: true, force: true });
+  }
+
+  if (isSymlink) {
+    // Existing symlink (possibly stale) — remove before re-creating.
+    rmSync(dest, { force: true });
+  }
+
+  symlinkSync(resolvedSource, dest);
+  console.log(
+    chalk.green(`  ✓ dev link created: ${dest} → ${resolvedSource}`),
+  );
+  console.log(
+    chalk.dim(
+      `    Edits to the source dir will now propagate to opencode on next session.`,
+    ),
+  );
+  return true;
+}
+
+/**
+ * Remove the dev symlink and restore the deployed plugin from npm.
+ * Refuses to remove a real directory (would destroy the deployed copy)
+ * unless opts.force is set.
+ *
+ * Returns true on success, false on refusal or error.
+ */
+export async function removeDevLink(opts = {}) {
+  const dest = pluginDest();
+  let isSymlink = false;
+  let exists = false;
+  try {
+    const st = lstatSync(dest);
+    exists = true;
+    isSymlink = st.isSymbolicLink();
+  } catch {
+    // doesn't exist
+  }
+
+  if (!exists) {
+    console.log(chalk.red(`  ✗ ${dest} does not exist — nothing to unlink.`));
+    return false;
+  }
+
+  if (!isSymlink) {
+    if (!opts.force) {
+      console.log(
+        chalk.red(
+          `  ✗ ${dest} is not a symlink. Refusing to remove a real directory.`,
+        ),
+      );
+      console.log(chalk.dim(`    Use --force if you really mean it.`));
+      return false;
+    }
+    console.log(chalk.yellow(`  ⚠ Force-removing real directory at ${dest}`));
+    rmSync(dest, { recursive: true, force: true });
+  } else {
+    rmSync(dest, { force: true });
+  }
+
+  // Restore from npm. installPluginFromGlobal is silent because we
+  // already announced the unlink above; it will print its own brief
+  // success message on the next line if a real copy was installed.
+  try {
+    const { installPluginFromGlobal } = await import('./install.mjs');
+    await installPluginFromGlobal({ silent: true });
+  } catch (err) {
+    console.log(chalk.yellow(`  ⚠ restore from npm failed: ${err.message}`));
+  }
+
+  // Read the installed version for the success message.
+  let version = 'unknown';
+  try {
+    const root = execSync('npm root -g', { encoding: 'utf8', timeout: 5000 }).trim();
+    const pkgPath = join(root, '@polderlabs', 'bizar-plugin', 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      version = pkg.version ?? 'unknown';
+    }
+  } catch {
+    // informational only
+  }
+
+  console.log(
+    chalk.green(
+      `  ✓ dev link removed; deployed plugin restored from @polderlabs/bizar-plugin@${version}`,
+    ),
+  );
+  return true;
+}

package/cli/dev-link.test.mjs

@@ -0,0 +1,297 @@
+/**
+ * cli/dev-link.test.mjs
+ *
+ * Tests for the `bizar dev-link` / `bizar dev-unlink` subcommands.
+ * Uses Node's built-in node:test (no external test framework).
+ *
+ * Strategy: mock HOME (and XDG_CONFIG_HOME) so opencodeConfigDir() in
+ * cli/utils.mjs returns a path inside a tmpdir, and exercise the
+ * create/remove symlink behavior against a controlled filesystem.
+ *
+ * Note: We mock HOME *before* importing dev-link.mjs because the module
+ * imports opencodeConfigDir transitively from utils.mjs. The path is
+ * resolved at call time, though, so the mock just needs to be in place
+ * when the functions run.
+ */
+import { test, describe, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  symlinkSync,
+  lstatSync,
+  existsSync,
+  readlinkSync,
+} 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 { createDevLink, removeDevLink } = await import('./dev-link.mjs');
+
+// ── HOME mocking ────────────────────────────────────────────────────────────
+
+const ORIG_HOME = process.env.HOME;
+const ORIG_XDG = process.env.XDG_CONFIG_HOME;
+
+/**
+ * Point HOME at a fresh tmpdir so the module's opencodeConfigDir()
+ * resolves inside it (via the fallback `<HOME>/.config/opencode`).
+ * Returns the tmpdir path.
+ *
+ * Note: we deliberately do NOT set XDG_CONFIG_HOME here. The
+ * opencodeConfigDir() helper treats a set XDG_CONFIG_HOME as the
+ * direct parent (so `XDG_CONFIG_HOME=~/.config` → `~/.config/opencode`,
+ * matching the standard layout). Setting it to a raw tmpdir would
+ * produce `<tmpdir>/opencode` instead of the expected
+ * `<tmpdir>/.config/opencode` and break path alignment with the test.
+ */
+function freshHome() {
+  const home = mkdtempSync(join(tmpdir(), 'bizar-devlink-'));
+  process.env.HOME = home;
+  delete process.env.XDG_CONFIG_HOME;
+  return home;
+}
+
+/** Path to the deployed plugin dir under the mocked HOME. */
+function pluginDest(home) {
+  return join(home, '.config', 'opencode', 'plugins', 'bizar');
+}
+
+after(() => {
+  // Restore env at the very end (individual tests have already done this).
+  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;
+});
+
+// ── createDevLink ───────────────────────────────────────────────────────────
+
+describe('createDevLink()', () => {
+  let home;
+  let sourceDir;
+
+  beforeEach(() => {
+    home = freshHome();
+    // The "source" can be any directory — it doesn't need real plugin
+    // contents for the symlink test. Use the actual repo plugins/bizar
+    // so the test doubles as a smoke test of the real path.
+    sourceDir = join(PROJECT_ROOT, 'plugins', 'bizar');
+  });
+
+  afterEach(() => {
+    if (home && existsSync(home)) rmSync(home, { recursive: true, force: true });
+    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;
+  });
+
+  test('creates a symlink when dest does not exist', () => {
+    const dest = pluginDest(home);
+    assert.equal(existsSync(dest), false, 'precondition: dest should not exist');
+
+    const ok = createDevLink(sourceDir);
+    assert.equal(ok, true);
+    assert.equal(existsSync(dest), true);
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), true, 'dest should be a symlink');
+  });
+
+  test('refuses to overwrite a real directory without --force', () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+    writeFileSync(join(dest, 'index.ts'), 'not a symlink');
+
+    const ok = createDevLink(sourceDir);
+    assert.equal(ok, false, 'should refuse without force');
+    assert.equal(existsSync(dest), true);
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), false, 'dest should still be a real dir');
+    assert.equal(existsSync(join(dest, 'index.ts')), true, 'contents preserved');
+  });
+
+  test('overwrites a real directory with opts.force=true', () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+    writeFileSync(join(dest, 'index.ts'), 'not a symlink');
+
+    const ok = createDevLink(sourceDir, { force: true });
+    assert.equal(ok, true);
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), true, 'dest should now be a symlink');
+    // Confirm the symlink points at the requested source. We can't
+    // look up `dest/index.ts` to verify the old contents are gone —
+    // that path now resolves through the symlink to the source's own
+    // index.ts, which may exist. Instead, verify the link target.
+    const linkTarget = readlinkSync(dest);
+    assert.equal(linkTarget, sourceDir);
+    // And confirm the previously-existing real directory is no longer
+    // present as a real directory at `dest`.
+    assert.equal(st.isDirectory(), false, 'dest should no longer be a directory');
+  });
+
+  test('replaces an existing symlink', () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+
+    const otherTarget = join(home, 'other-source');
+    mkdirSync(otherTarget, { recursive: true });
+    symlinkSync(otherTarget, dest);
+
+    const ok = createDevLink(sourceDir);
+    assert.equal(ok, true);
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), true);
+    // Confirm the symlink now points at the requested source.
+    const linkTarget = readlinkSync(dest);
+    assert.equal(linkTarget, sourceDir);
+  });
+
+  test('resolves a relative source dir against cwd', () => {
+    const dest = pluginDest(home);
+    const ok = createDevLink('plugins/bizar');
+    assert.equal(ok, true);
+    const linkTarget = readlinkSync(dest);
+    // The resolved path should be an absolute path under PROJECT_ROOT.
+    assert.ok(linkTarget.startsWith('/'), `expected absolute path, got: ${linkTarget}`);
+    assert.ok(linkTarget.endsWith('/plugins/bizar'));
+  });
+
+  test('creates the opencode config parent if missing', () => {
+    const dest = pluginDest(home);
+    assert.equal(existsSync(dirname(dest)), false, 'precondition');
+    const ok = createDevLink(sourceDir);
+    assert.equal(ok, true);
+    assert.equal(existsSync(dirname(dest)), true);
+  });
+});
+
+// ── removeDevLink ───────────────────────────────────────────────────────────
+
+describe('removeDevLink()', () => {
+  let home;
+
+  beforeEach(() => {
+    home = freshHome();
+  });
+
+  afterEach(() => {
+    if (home && existsSync(home)) rmSync(home, { recursive: true, force: true });
+    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;
+  });
+
+  test('errors when dest does not exist', async () => {
+    const dest = pluginDest(home);
+    assert.equal(existsSync(dest), false);
+
+    const ok = await removeDevLink();
+    assert.equal(ok, false);
+  });
+
+  test('errors when dest is a real directory and no --force', async () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+    writeFileSync(join(dest, 'index.ts'), 'precious data');
+
+    const ok = await removeDevLink();
+    assert.equal(ok, false);
+    assert.equal(existsSync(join(dest, 'index.ts')), true, 'data preserved');
+  });
+
+  test('removes a symlink and restores from npm', async () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+
+    const sourceDir = join(PROJECT_ROOT, 'plugins', 'bizar');
+    symlinkSync(sourceDir, dest);
+    assert.equal(lstatSync(dest).isSymbolicLink(), true);
+
+    const ok = await removeDevLink();
+    assert.equal(ok, true);
+    // The symlink should be gone. Whether the npm-restore step
+    // recreated a real directory depends on whether @polderlabs/bizar-plugin
+    // is installed globally in the test environment. Both outcomes are
+    // acceptable — what matters is that the symlink was removed.
+    if (existsSync(dest)) {
+      const st = lstatSync(dest);
+      assert.equal(
+        st.isSymbolicLink(),
+        false,
+        'symlink should have been replaced with a real directory (npm restore)',
+      );
+    }
+  });
+
+  test('refuses to unlink a real dir without --force', async () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+
+    const ok = await removeDevLink();
+    assert.equal(ok, false);
+    assert.equal(existsSync(dest), true);
+  });
+
+  test('force-removes a real dir with opts.force=true', async () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+    writeFileSync(join(dest, 'marker'), 'x');
+
+    const ok = await removeDevLink({ force: true });
+    assert.equal(ok, true);
+    // The npm-restore may or may not recreate the directory. If it
+    // does, the marker should be gone.
+    if (existsSync(dest)) {
+      assert.equal(existsSync(join(dest, 'marker')), false);
+    }
+  });
+});
+
+// ── Symlink detection ───────────────────────────────────────────────────────
+
+describe('symlink detection', () => {
+  let home;
+
+  beforeEach(() => {
+    home = freshHome();
+  });
+
+  afterEach(() => {
+    if (home && existsSync(home)) rmSync(home, { recursive: true, force: true });
+    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;
+  });
+
+  test('lstatSync reports isSymbolicLink()=true after createDevLink', () => {
+    const dest = pluginDest(home);
+    createDevLink(join(PROJECT_ROOT, 'plugins', 'bizar'));
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), true);
+  });
+
+  test('lstatSync reports isSymbolicLink()=false for a real dir', () => {
+    const dest = pluginDest(home);
+    mkdirSync(dirname(dest), { recursive: true });
+    mkdirSync(dest, { recursive: true });
+    const st = lstatSync(dest);
+    assert.equal(st.isSymbolicLink(), false);
+  });
+});
+
+console.log('  dev-link.mjs tests loaded — run with: node --test cli/dev-link.test.mjs');