@polderlabs/bizar 2.3.0 → 2.6.0

package/cli/bin.mjs

@@ -24,6 +24,7 @@ function showHelp() {
     bizar plan <subcommand>     Manage visual plans (new, open, list, delete, export, templates)
     bizar test-gate             Detect & run the project's test suite
     bizar update                Update opencode, bizar, and/or bizar-plugin
+    bizar dashboard [start|stop|status]  Launch or control the web dashboard (v2.5.0+)
     bizar --help                Show this help
 
   Install:
@@ -93,6 +94,75 @@ function showTestGateHelp() {
   `);
 }
 
+function showDashboardHelp() {
+  console.log(`
+  bizar dashboard — Launch or control the Bizar web dashboard
+
+  Usage:
+    bizar dashboard             Start the dashboard (default action = start)
+    bizar dashboard start       Start the dashboard in the current process
+    bizar dashboard stop        Kill the running dashboard (reads PID file)
+    bizar dashboard status      Print port + URL of any running dashboard
+
+  Description:
+    Starts a local Express + WebSocket server on 127.0.0.1, opens the
+    user's default browser to the dashboard URL, and broadcasts live
+    file-change events from config/, agents/, commands-bizar/, .bizar/,
+    and plans/. The server binds loopback only — never expose it.
+  `);
+}
+
+async function runDashboard(action) {
+  const sub = action || 'start';
+  const { launchDashboard, PORT_FILE, PID_FILE } = await import('./dashboard.mjs');
+  const { existsSync, readFileSync, unlinkSync } = await import('node:fs');
+
+  if (sub === 'status') {
+    if (existsSync(PORT_FILE)) {
+      const port = readFileSync(PORT_FILE, 'utf8').trim();
+      console.log(`Bizar dashboard is running at http://localhost:${port}/`);
+      if (existsSync(PID_FILE)) {
+        console.log(`PID: ${readFileSync(PID_FILE, 'utf8').trim()}`);
+      }
+    } else {
+      console.log('No Bizar dashboard is running. Use: bizar dashboard start');
+    }
+    return;
+  }
+
+  if (sub === 'stop') {
+    if (!existsSync(PID_FILE)) {
+      console.log('No Bizar dashboard is running.');
+      return;
+    }
+    const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid)) {
+      console.log(`Bad PID file: ${PID_FILE}`);
+      return;
+    }
+    try {
+      process.kill(pid, 'SIGTERM');
+      console.log(`Stopped Bizar dashboard (pid ${pid}).`);
+    } catch (err) {
+      console.log(`Could not stop dashboard (pid ${pid}): ${err.message}`);
+    }
+    try { unlinkSync(PORT_FILE); } catch { /* ignore */ }
+    try { unlinkSync(PID_FILE); } catch { /* ignore */ }
+    return;
+  }
+
+  if (sub !== 'start') {
+    showDashboardHelp();
+    return;
+  }
+
+  // Start — keep the process alive so the server stays up
+  await launchDashboard();
+  console.log(chalk.dim('  Press Ctrl-C to stop the dashboard.'));
+  // Wait forever; SIGINT will exit the process.
+  await new Promise(() => {});
+}
+
 function showUpdateHelp() {
   console.log(`
   bizar update — Update opencode, bizar, and/or bizar-plugin
@@ -179,6 +249,9 @@ if (args.includes('--postinstall')) {
 } else if (args[0] === 'plan') {
   const planArgs = args.slice(1);
   await runPlan(planArgs, {});
+} else if (args[0] === 'dashboard') {
+  if (args.includes('--help') || args.includes('-h')) showDashboardHelp();
+  else await runDashboard(args[1]);
 } else if (args.includes('--help') || args.includes('-h')) {
   showHelp();
 } else {

package/cli/copy.mjs

@@ -269,8 +269,11 @@ export async function installPluginBizar(projectRoot) {
   try {
     await access(srcDir, constants.F_OK);
   } catch {
-    spinner.warn(chalk.yellow('Bizar plugin source not found — skipping'));
-    return { copied: 0, errors: ['Source not found: ' + srcDir] };
+    // The Bizar plugin now lives in a separate npm package
+    // (@polderlabs/bizar-plugin). The interactive installer copies it from
+    // there; the source tree no longer carries plugins/bizar/.
+    // Silent return — no warning needed.
+    return { copied: 0, errors: [] };
   }
 
   const destDir = join(projectRoot, '.opencode', 'plugins', 'bizar');
@@ -506,3 +509,40 @@ export async function installCommands() {
   }
   return count;
 }
+
+/**
+ * Install Bizar-specific commands to commands-bizar/ (separate from ECC's
+ * commands/ symlink). This directory holds the Bizar plugin's own command
+ * templates: audit, explain, init, learn, plan, pr-review, tailscale-serve,
+ * visual-plan, and bizar.
+ *
+ * If dest is a symlink (e.g. the ECC installer symlinked it), skip with a
+ * friendly message — we don't want to follow a symlink and write into someone
+ * else's directory.
+ *
+ * @returns {Promise<number>} count of .md files copied
+ */
+export async function installCommandsBizar() {
+  const src = repoPath('config', 'commands');
+  const dest = join(opencodeConfigDir(), 'commands-bizar');
+  const { mkdirSync, readdirSync, copyFileSync, lstatSync } = await import('node:fs');
+
+  // Guard: skip if dest is a symlink (don't follow other packages' symlinks)
+  try {
+    const stat = lstatSync(dest);
+    if (stat.isSymbolicLink()) {
+      console.log('BizarHarness: commands-bizar/ is a symlink — skipping install.');
+      return 0;
+    }
+  } catch {
+    // dest does not exist — that's fine, we'll create it
+  }
+
+  mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const file of readdirSync(src).filter(f => f.endsWith('.md'))) {
+    copyFileSync(join(src, file), join(dest, file));
+    count++;
+  }
+  return count;
+}

package/cli/dashboard/api.mjs

@@ -0,0 +1,473 @@
+/**
+ * cli/dashboard/api.mjs
+ *
+ * REST surface for the dashboard. Every route:
+ *   - Returns JSON
+ *   - Returns { error, message } with appropriate status on failure
+ *   - Never throws to Express — every handler is wrapped in try/catch
+ *
+ * The router is mounted at /api/* by cli/dashboard/server.mjs.
+ */
+import express from 'express';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { createTask, updateTask, deleteTask, moveTask } from './tasks-store.mjs';
+
+/**
+ * @param {object} deps
+ * @param {ReturnType<import('./state.mjs').createState>} deps.state
+ * @param {ReturnType<import('./watcher.mjs').createWatcher>} deps.watcher
+ * @param {string} deps.projectRoot
+ * @param {string} deps.opencodeConfigDir
+ * @param {string} deps.bizarRoot
+ * @param {function} deps.broadcast - WS broadcast function ({ type, ... }) => void
+ */
+export function createApiRouter({
+  state,
+  watcher,
+  projectRoot,
+  opencodeConfigDir,
+  bizarRoot,
+  broadcast = () => {},
+}) {
+  const router = express.Router();
+
+  /** Safe async handler — never throws past Express. */
+  const wrap =
+    (fn) =>
+    async (req, res, ...rest) => {
+      try {
+        await fn(req, res, ...rest);
+      } catch (err) {
+        const status = err?.status || 500;
+        res.status(status).json({
+          error: err?.code || 'internal_error',
+          message: err?.message || String(err),
+        });
+      }
+    };
+
+  // ── /api/overview ──────────────────────────────────────────────────────────
+  router.get('/overview', wrap(async (_req, res) => {
+    res.json(state.getOverview());
+  }));
+
+  // ── /api/snapshot ──────────────────────────────────────────────────────────
+  // Returns every dashboard panel in one round-trip — used by the React SPA
+  // for its initial load. Mirrors the WS snapshot payload shape.
+  router.get('/snapshot', wrap(async (_req, res) => {
+    res.json({
+      overview: state.getOverview(),
+      agents: state.getAgents(),
+      plans: state.getPlans(),
+      projects: state.getProjects(),
+      config: state.getConfig(),
+      settings: state.getSettings(),
+      tasks: state.getTasks(),
+    });
+  }));
+
+  // ── /api/chat ──────────────────────────────────────────────────────────────
+  router.get('/chat', wrap(async (req, res) => {
+    const sessionId = req.query.session
+      ? String(req.query.session)
+      : null;
+    const limit = req.query.limit ? Number(req.query.limit) : 200;
+    res.json(state.getChat({ sessionId, limit }));
+  }));
+
+  router.post('/chat', wrap(async (req, res) => {
+    const body = req.body || {};
+    const message = typeof body.message === 'string' ? body.message.trim() : '';
+    const agent = typeof body.agent === 'string' ? body.agent : null;
+    if (!message) {
+      res.status(400).json({
+        error: 'bad_request',
+        message: 'message is required',
+      });
+      return;
+    }
+    state.appendActivity({
+      kind: 'chat.message',
+      agent,
+      message: message.slice(0, 500),
+    });
+    res.status(202).json({
+      accepted: true,
+      agent,
+      queued: true,
+      note:
+        'Live agent dispatch runs in the opencode TUI; the dashboard ' +
+        'records and broadcasts the message. Open the TUI to dispatch it.',
+    });
+  }));
+
+  // ── /api/agents ────────────────────────────────────────────────────────────
+  router.get('/agents', wrap(async (_req, res) => {
+    const agents = state.getAgents();
+    res.json({ agents });
+  }));
+
+  router.post(
+    '/agents/:name/invoke',
+    wrap(async (req, res) => {
+      const name = req.params.name;
+      const prompt = (req.body && req.body.prompt) || '';
+      if (!prompt.trim()) {
+        res.status(400).json({
+          error: 'bad_request',
+          message: 'prompt is required',
+        });
+        return;
+      }
+      state.appendActivity({
+        kind: 'agent.invoke',
+        agent: name,
+        prompt: String(prompt).slice(0, 500),
+      });
+      res.status(202).json({
+        accepted: true,
+        agent: name,
+        note:
+          'Agent dispatch is forwarded to the opencode TUI. The dashboard ' +
+          'records the invocation for the activity feed.',
+      });
+    }),
+  );
+
+  // ── /api/plans ─────────────────────────────────────────────────────────────
+  router.get('/plans', wrap(async (_req, res) => {
+    res.json({ plans: state.getPlans() });
+  }));
+
+  router.post('/plans', wrap(async (req, res) => {
+    const slug = req.body?.slug;
+    const title = req.body?.title || slug;
+    if (
+      typeof slug !== 'string' ||
+      !/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)
+    ) {
+      res.status(400).json({
+        error: 'bad_request',
+        message:
+          'slug must match ^[a-z0-9][a-z0-9-]{0,63}$',
+      });
+      return;
+    }
+    const plansDir = state.paths.plansDir;
+    const target = join(plansDir, slug);
+    if (existsSync(target)) {
+      res.status(409).json({
+        error: 'exists',
+        message: `plan "${slug}" already exists`,
+      });
+      return;
+    }
+    mkdirSync(target, { recursive: true });
+    writeFileSync(
+      join(target, 'meta.json'),
+      JSON.stringify(
+        {
+          slug,
+          title,
+          status: 'draft',
+          createdAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    );
+    state.appendActivity({ kind: 'plan.create', slug, title });
+    watcher.poke('change', target);
+    res.status(201).json({ slug, title, path: target });
+  }));
+
+  router.get('/plans/:slug', wrap(async (req, res) => {
+    const slug = req.params.slug;
+    const local = join(state.paths.plansDir, slug);
+    const global = join(state.paths.globalPlansDir, slug);
+    const dir = existsSync(local) ? local : existsSync(global) ? global : null;
+    if (!dir) {
+      res.status(404).json({
+        error: 'not_found',
+        message: `plan "${slug}" not found`,
+      });
+      return;
+    }
+    const meta = readMeta(join(dir, 'meta.json'));
+    const planMdx = readMaybe(join(dir, 'plan.mdx'));
+    res.json({
+      slug,
+      dir,
+      meta,
+      planMdx,
+    });
+  }));
+
+  router.get('/plans/:slug/canvas', wrap(async (req, res) => {
+    const slug = req.params.slug;
+    const local = join(state.paths.plansDir, slug);
+    const global = join(state.paths.globalPlansDir, slug);
+    const dir = existsSync(local) ? local : existsSync(global) ? global : null;
+    if (!dir) {
+      res.status(404).json({
+        error: 'not_found',
+        message: `plan "${slug}" not found`,
+      });
+      return;
+    }
+    const planJson = join(dir, 'plan.json');
+    const canvas = readMaybe(planJson);
+    if (canvas === null) {
+      res.json({
+        slug,
+        dir,
+        canvas: {
+          schemaVersion: 2,
+          title: slug,
+          elements: [],
+          connections: [],
+          comments: [],
+          viewport: { x: 0, y: 0, zoom: 1 },
+        },
+      });
+      return;
+    }
+    try {
+      res.json({
+        slug,
+        dir,
+        canvas: JSON.parse(canvas),
+      });
+    } catch {
+      res.json({
+        slug,
+        dir,
+        canvas: {
+          schemaVersion: 2,
+          title: slug,
+          elements: [],
+          connections: [],
+          comments: [],
+          viewport: { x: 0, y: 0, zoom: 1 },
+        },
+      });
+    }
+  }));
+
+  router.put('/plans/:slug', wrap(async (req, res) => {
+    const slug = req.params.slug;
+    const local = join(state.paths.plansDir, slug);
+    const global = join(state.paths.globalPlansDir, slug);
+    const dir = existsSync(local) ? local : existsSync(global) ? local : null;
+    if (!dir) {
+      res.status(404).json({
+        error: 'not_found',
+        message: `plan "${slug}" not found`,
+      });
+      return;
+    }
+    const body = req.body || {};
+    if (!body || typeof body !== 'object') {
+      res.status(400).json({
+        error: 'bad_request',
+        message: 'body must be an object',
+      });
+      return;
+    }
+    if (body.meta && typeof body.meta === 'object') {
+      const existing = readMeta(join(dir, 'meta.json')) || {};
+      const merged = { ...existing, ...body.meta, updatedAt: new Date().toISOString() };
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(
+        join(dir, 'meta.json'),
+        JSON.stringify(merged, null, 2) + '\n',
+        'utf8',
+      );
+    }
+    if (typeof body.planMdx === 'string') {
+      writeFileSync(join(dir, 'plan.mdx'), body.planMdx, 'utf8');
+    }
+    state.appendActivity({ kind: 'plan.update', slug });
+    watcher.poke('change', dir);
+    res.json({ ok: true, slug });
+  }));
+
+  // ── /api/projects ──────────────────────────────────────────────────────────
+  router.get('/projects', wrap(async (_req, res) => {
+    res.json({ projects: state.getProjects() });
+  }));
+
+  router.post(
+    '/projects/:name/activate',
+    wrap(async (req, res) => {
+      const name = req.params.name;
+      const projects = state.getProjects();
+      const target = projects.find((p) => p.name === name);
+      if (!target) {
+        res.status(404).json({
+          error: 'not_found',
+          message: `project "${name}" not found`,
+        });
+        return;
+      }
+      state.appendActivity({
+        kind: 'project.activate',
+        name,
+        path: target.path,
+      });
+      res.json({
+        activated: name,
+        path: target.path,
+        note:
+          'The dashboard exposes the project; the opencode TUI must be ' +
+          'restarted in the new directory to fully activate.',
+      });
+    }),
+  );
+
+  // ── /api/config ────────────────────────────────────────────────────────────
+  router.get('/config', wrap(async (_req, res) => {
+    res.json(state.getConfig());
+  }));
+
+  router.put('/config', wrap(async (req, res) => {
+    const body = req.body;
+    let parsed;
+    if (typeof body === 'string') {
+      try {
+        parsed = JSON.parse(body);
+      } catch (err) {
+        res.status(400).json({
+          error: 'invalid_json',
+          message: err.message,
+        });
+        return;
+      }
+    } else if (body && typeof body === 'object') {
+      parsed = body;
+    } else {
+      res.status(400).json({
+        error: 'bad_request',
+        message: 'body must be a JSON object or string',
+      });
+      return;
+    }
+    const updated = state.setConfig(parsed);
+    state.appendActivity({ kind: 'config.update' });
+    watcher.poke('change', state.paths.opencodeJson);
+    res.json(updated);
+  }));
+
+  router.post('/config/reload', wrap(async (_req, res) => {
+    const snapshot = state.getConfig();
+    state.appendActivity({ kind: 'config.reload' });
+    res.json(snapshot);
+  }));
+
+  // ── /api/settings ──────────────────────────────────────────────────────────
+  router.get('/settings', wrap(async (_req, res) => {
+    res.json(state.getSettings());
+  }));
+
+  router.put('/settings', wrap(async (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object') {
+      res.status(400).json({
+        error: 'bad_request',
+        message: 'body must be an object',
+      });
+      return;
+    }
+    const updated = state.setSettings(body);
+    state.appendActivity({ kind: 'settings.update' });
+    res.json(updated);
+  }));
+
+  // ── /api/tasks ────────────────────────────────────────────────────────────
+  router.get('/tasks', wrap(async (_req, res) => {
+    res.json(state.getTasks());
+  }));
+
+  router.post('/tasks', wrap(async (req, res) => {
+    const { title, description, status, tags, priority } = req.body || {};
+    if (!title || typeof title !== 'string' || title.length > 200) {
+      res.status(400).json({ error: 'bad_request', message: 'title required (1-200 chars)' });
+      return;
+    }
+    const task = await createTask({ title, description, status, tags, priority });
+    broadcast({ type: 'tasks:change', task });
+    res.status(201).json(task);
+  }));
+
+  router.put('/tasks/:id', wrap(async (req, res) => {
+    const task = await updateTask(req.params.id, req.body || {});
+    if (!task) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'tasks:change', task });
+    res.json(task);
+  }));
+
+  router.patch('/tasks/:id/status', wrap(async (req, res) => {
+    const { status } = req.body || {};
+    if (!['queued', 'doing', 'done'].includes(status)) {
+      res.status(400).json({ error: 'bad_request', message: 'invalid status' });
+      return;
+    }
+    const task = await moveTask(req.params.id, status);
+    if (!task) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'tasks:change', task });
+    res.json(task);
+  }));
+
+  router.delete('/tasks/:id', wrap(async (req, res) => {
+    const ok = await deleteTask(req.params.id);
+    if (!ok) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'tasks:delete', id: req.params.id });
+    res.status(204).end();
+  }));
+
+  // ── health ────────────────────────────────────────────────────────────────
+  router.get('/health', (_req, res) => {
+    res.json({ ok: true, ts: Date.now() });
+  });
+
+  // ── fallback ──────────────────────────────────────────────────────────────
+  router.use((req, res) => {
+    res.status(404).json({
+      error: 'not_found',
+      message: `no route for ${req.method} ${req.originalUrl}`,
+    });
+  });
+
+  return router;
+}
+
+function readMeta(file) {
+  try {
+    if (!existsSync(file)) return null;
+    const txt = readFileSync(file, 'utf8');
+    if (!txt.trim()) return null;
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+function readMaybe(file) {
+  try {
+    if (!existsSync(file)) return null;
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/cli/dashboard/browser.mjs

@@ -0,0 +1,40 @@
+/**
+ * cli/dashboard/browser.mjs
+ *
+ * Cross-platform best-effort browser launcher. On failure (no graphical
+ * session, headless server), we just log the URL so the user can open it
+ * manually.
+ */
+import { spawn } from 'node:child_process';
+
+export async function launchBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  let args;
+
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    // Windows `start` is a shell builtin; spawn it via cmd.exe.
+    cmd = 'cmd';
+    args = ['/c', 'start', '""', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+
+  try {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', () => {
+      /* swallowed — best effort */
+    });
+    child.unref();
+  } catch (_err) {
+    // Browser launch failed — print URL for manual opening
+    console.log(`Open ${url} in your browser`);
+  }
+}