@polderlabs/bizar 3.9.0 → 3.10.0

package/README.md

@@ -143,7 +143,9 @@ npx bizar
 
 The interactive installer walks you through component selection, agent choice, install mode, API key setup, and auto-restarts opencode.
 
-### Source — git clone (contributors)
+> **Windows users:** the `npm install -g @polderlabs/bizar` command above is the recommended path on Windows. The installer uses `irm | iex` for uv, `py -m pip` for the pip fallback, `taskkill` for forced kills, and JS `setTimeout` instead of `sleep` — so it works on both Windows PowerShell and POSIX shells. See the [Windows](#-windows) section below for prerequisites, known limitations, and the optional graph feature install.
+
+### Source — git clone (Linux/macOS contributors)
 
 ```bash
 git clone git@github.com:DrB0rk/BizarHarness.git
@@ -154,6 +156,50 @@ chmod +x install.sh
 
 Copies agent definitions and config to `~/.config/opencode/`, merges `opencode.json`, and prints next steps. Use this if you want to hack on BizarHarness itself.
 
+> This `install.sh` script is bash-only and does **not** run on Windows natively. Windows contributors should use the npm path above instead.
+
+### Windows
+
+The `bizar` CLI is cross-platform — the npm install runs a Node.js installer that handles `curl | sh` redirects, signal handling, and temp paths on Windows PowerShell automatically.
+
+**Prerequisites**
+
+- [Node.js 18+](https://nodejs.org/) on `PATH`
+- [Python 3.10+](https://www.python.org/downloads/windows/) (only required for the optional `bizar graph` knowledge-graph feature)
+- [Git for Windows](https://git-scm.com/download/win) — only needed if you want to run the bash `install.sh` from a Git Bash shell
+
+**Install**
+
+```powershell
+npm install -g @polderlabs/bizar
+bizar
+```
+
+**Optional: graph feature (knowledge graph + per-project .bizar/)**
+
+The `bizar graph build` subcommand uses [graphify](https://github.com/bretbhomas/graphify). Install uv and graphify from PowerShell:
+
+```powershell
+# Install uv (Python package manager) — Windows-native PowerShell installer
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Install graphify
+uv tool install graphifyy
+```
+
+Then build the project graph from any repo:
+
+```powershell
+bizar graph build
+```
+
+**Known Windows limitations**
+
+- The `blessed` TUI library may render with quirks inside Windows Terminal; if you see garbled output in the TUI, use the browser UI via `bizar dash start --bg` and open http://localhost:4321 instead.
+- Some shell scripts under `config/skills/embedded-esp-idf/` are bash-only and require Git Bash (or WSL).
+- The bash `install.sh` does not run on Windows cmd/PowerShell; use the `npm install -g` path above.
+- RTK (Rust Token Killer) ships a bash-only installer. On Windows, install it manually via [Cargo](https://github.com/rtk-ai/rtk#installation) or a [prebuilt binary](https://github.com/rtk-ai/rtk/releases), then run `rtk init -g --opencode`.
+
 ### Prerequisites
 
 - [opencode CLI](https://opencode.ai) installed and on `$PATH`

package/cli/bin.mjs

@@ -2,20 +2,17 @@
 /**
  * cli/bin.mjs
  *
- * v3.0.0 — `bizar` runtime CLI.
+ * v3.10.0 — `bizar` runtime CLI.
  *
  * Architecture:
  *   - `bizar` is the core runtime + installer + audit/init/export/update/plan
- *     + service commands.
- *   - The dashboard lives in a separate package, `@polderlabs/bizar-dash`.
- *     If it's installed, `bizar dashboard` / `bizar --web*` will defer to it.
- *     If not, the user is told to install it.
+ *     + service + dash commands.
+ *   - The dashboard lives in `@polderlabs/bizar-dash` as a library.
+ *     Commands live under `bizar dash <subcommand>` (new canonical form).
+ *     `bizar dashboard` is a deprecated alias (still works, prints warning).
  *
- * Subcommands (unchanged from v2.7.0):
- *   install, audit, init, export, plan, update, test-gate, service
- *
- * Flags (unchanged):
- *   --web / --no-web / --web-only / --bg / --detach
+ * Subcommands:
+ *   install, audit, init, export, plan, update, test-gate, service, dash
  */
 import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
@@ -77,36 +74,34 @@ function showHelp() {
   Bizar — Norse Pantheon Agent System for opencode
 
   Usage:
-    bizar                       Launch the TUI dashboard (auto-runs first-time setup if needed)
-    bizar --web                 Launch TUI + auto-open web dashboard
-    bizar --no-web              Launch TUI only (no browser)
-    bizar --web-only            Web dashboard only (no TUI, in browser)
-    bizar --bg, --detach        Launch web dashboard in background, return to shell
-    bizar install               Run the interactive installer
-    bizar audit                 Run security audit on agent configuration
-    bizar init                  Initialize .bizar/ in current project
-    bizar export [target]       Export agents/rules to another harness
-    bizar plan <subcommand>     Manage visual plans
-    bizar graph                 Per-project knowledge graph (powered by graphify)
-    bizar test-gate             Detect & run the project's test suite
-    bizar update                Update opencode, bizar, and/or bizar-plugin
-    bizar service               Manage the background service daemon
-    bizar dashboard             Launch the web dashboard (uses bizar)
-    bizar --setup               Re-run setup manually (agents, plugin, RTK, Semble, Skills CLI)
-    bizar --check               Print setup status as JSON, exit 1 if setup needed
-    bizar --version             Show package version
-    bizar --help                Show this help
+    bizar <command> [options]
+
+  Commands:
+    install             Run the interactive installer
+    audit               Run security audit on agent configuration
+    init                Initialize .bizar/ in current project
+    export [target]     Export agents/rules to another harness
+    plan <subcommand>  Manage visual plans
+    graph               Per-project knowledge graph (powered by graphify)
+    test-gate           Detect & run the project's test suite
+    update              Update opencode, bizar, and/or bizar-plugin
+    service             Manage the background service daemon
+    dash <subcommand>   Manage the dashboard (start/stop/status/tui)
+
+  Examples:
+    bizar install
+    bizar audit
+    bizar dash start
+    bizar dash start --bg
+    bizar dash stop
+    bizar dash status
+
+  Run \`bizar <command> --help\` for per-command help.
 
   Install:
     npm install -g @polderlabs/bizar          Install globally
-    npm install -g @polderlabs/bizar-dash     Optional companion dashboard
+    npm install -g @polderlabs/bizar-dash     Optional dashboard package
     npm install -g @polderlabs/bizar-plugin   Bizar opencode plugin
-
-  Notes:
-    The TUI is the default command — press 1-8 for tabs, q to quit.
-    \`bizar --bg\` launches the dashboard detached; \`bizar dashboard stop\`
-    terminates it. The web dashboard lives in the \`@polderlabs/bizar-dash\`
-    package — if it's not installed, you'll be prompted to install it.
   `);
 }
 
@@ -181,7 +176,7 @@ function showInstallHelp() {
 
 function showUpdateHelp() {
   console.log(`
-  bizar update — Update opencode, bizar, bizar-dash, and/or bizar-plugin
+  bizar update — Update opencode, bizar, and/or bizar-plugin
 
   Usage:
     bizar update                       Interactive prompt for components
@@ -207,7 +202,7 @@ function showUpdateHelp() {
     • Sends SIGTERM, waits up to 5s, escalates to SIGKILL if needed.
     • Re-runs the install script so the deployed plugin source matches
       the just-upgraded npm version (avoids the version-skew trap).
-    • If the dashboard was running and bizar / bizar-dash were updated,
+    • 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).
 
@@ -244,19 +239,35 @@ function showServiceHelp() {
   `);
 }
 
-function showDashboardHelp() {
+function showDashHelp() {
   console.log(`
-  bizar dashboard — Launch the web dashboard (uses @polderlabs/bizar-dash)
+  bizar dash — Manage the Bizar dashboard
 
   Usage:
-    bizar dashboard             Start the dashboard
-    bizar dashboard start       Same
-    bizar dashboard stop        Kill the running dashboard
-    bizar dashboard status      Show port + URL
+    bizar dash <subcommand> [options]
 
-  Description:
-    The dashboard lives in a separate package. If it's not installed,
-    you'll see an install hint pointing at @polderlabs/bizar-dash.
+  Subcommands:
+    start [--bg] [--port N]   Start the dashboard (default port 4321)
+    stop                       Stop the running dashboard
+    status                     Show dashboard port and URL
+    tui [--no-web]             Launch the TUI
+
+  Options:
+    --bg                       Detach and run in background (for start)
+    --port N                   Override the default port
+    --no-web                   Skip launching the web UI (for tui)
+
+  Examples:
+    bizar dash start
+    bizar dash start --bg
+    bizar dash stop
+    bizar dash status
+    bizar dash tui
+    bizar dash tui --no-web
+
+  Note:
+    \`bizar dashboard\` is a deprecated alias for \`bizar dash\` and still
+    works, but new code should use \`bizar dash\`.
   `);
 }
 
@@ -420,35 +431,131 @@ async function main() {
   } else if (args[0] === 'service') {
     if (isHelpRequest) showServiceHelp();
     else await runServiceCommand(args[1]);
-  } else if (args[0] === 'dashboard' || args[0] === 'start' || args[0] === 'stop' || args[0] === 'status' || args[0] === 'tui') {
-    if (isHelpRequest) showDashboardHelp();
-    else await delegateToDash(args.slice(1));
-  } else if (args.includes('--bg') || args.includes('--detach')) {
-    // Delegate to bizar-dash
-    await delegateToDash(['--bg']);
-  } else if (args.includes('--web-only')) {
-    await delegateToDash(['--web-only']);
+  } else if (args[0] === 'dash' || args[0] === 'dashboard') {
+    // `bizar dashboard` is a deprecated alias for `bizar dash`
+    if (args[0] === 'dashboard') {
+      console.warn(chalk.yellow('  ⚠ `bizar dashboard` is deprecated, use `bizar dash` instead.'));
+    }
+    const dashArgs = args.slice(1); // everything after 'dash' or 'dashboard'
+    if (dashArgs.length === 0 || isHelpRequest) {
+      showDashHelp();
+    } else {
+      await runDash(dashArgs);
+    }
   } else if (isHelpRequest) {
     showHelp();
   } else {
-    // Default: launch the TUI dashboard. The TUI lives in bizar-dash.
-    const dashPath = await findBizarDash();
-    if (dashPath) {
-      const skipWeb = args.includes('--no-web');
-      const forceWeb = args.includes('--web');
-      const settingAuto = await readAutoLaunchWeb();
-      const launchWeb = !skipWeb && (forceWeb || settingAuto);
-      await delegateToDash(['tui', ...(launchWeb ? [] : ['--no-web'])]);
+    // No args — show help (breaking: previously launched TUI)
+    showHelp();
+    process.exit(1);
+  }
+}
+
+// ── Dashboard subcommand ───────────────────────────────────────────────────────
+
+/**
+ * Parse dash-specific options from an array of args.
+ * Returns { opts, remaining } where opts have --bg / --port stripped.
+ */
+function parseDashOpts(dashArgs) {
+  const opts = { bg: false, port: null, noWeb: false };
+  const remaining = [];
+  for (let i = 0; i < dashArgs.length; i++) {
+    const a = dashArgs[i];
+    if (a === '--bg') {
+      opts.bg = true;
+    } else if (a === '--no-web') {
+      opts.noWeb = true;
+    } else if (a === '--port' && i + 1 < dashArgs.length) {
+      opts.port = Number(dashArgs[i + 1]);
+      i++;
     } else {
-      console.log('The Bizar dashboard is in a separate package:');
-      console.log(chalk.cyan('  npm install -g @polderlabs/bizar-dash'));
-      console.log('');
-      console.log('Or run the installer to set up everything:');
-      console.log(chalk.cyan('  npx -y @polderlabs/bizar install'));
+      remaining.push(a);
     }
   }
+  return { opts, remaining };
 }
 
+/**
+ * Try to load the dashboard CLI module.
+ * Try 1: import via the package exports map (@polderlabs/bizar-dash/dash-cli)
+ * Try 2: file path probing for older installs or dev trees
+ */
+async function loadDashCli() {
+  // Try 1: import via exports map (requires Tyr's package.json changes)
+  try {
+    const mod = await import('@polderlabs/bizar-dash/dash-cli');
+    return mod;
+  } catch (_e) {
+    // fall through to file probing
+  }
+
+  // Try 2: file path probing
+  const { join } = await import('node:path');
+  const { homedir } = await import('node:os');
+  const candidates = [
+    // npm global install
+    join(homedir(), '.npm-global', 'lib', 'node_modules', '@polderlabs', 'bizar-dash', 'src', 'cli.mjs'),
+    // nvm
+    join(homedir(), '.nvm', 'versions', 'node'),
+    // relative to current process
+    join(process.execPath, '..', '..', 'lib', 'node_modules', '@polderlabs', 'bizar-dash', 'src', 'cli.mjs'),
+    // local node_modules
+    join(process.cwd(), 'node_modules', '@polderlabs', 'bizar-dash', 'src', 'cli.mjs'),
+  ];
+
+  const { pathToFileURL } = await import('node:url');
+  for (const p of candidates) {
+    try {
+      const url = pathToFileURL(p).href;
+      const mod = await import(url);
+      return mod;
+    } catch (_e) {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Dispatch a dashboard subcommand by loading the dashboard module and
+ * calling the appropriate exported function.
+ */
+async function runDash(dashArgs) {
+  const { opts, remaining } = parseDashOpts(dashArgs);
+  const sub = remaining[0];
+  const subOpts = { ...opts, subArgs: remaining.slice(1) };
+
+  const dashModule = await loadDashCli();
+  if (!dashModule) {
+    console.error(chalk.red('  ✗ Dashboard not installed.'));
+    console.error(chalk.dim('  Run: npm install -g @polderlabs/bizar-dash'));
+    console.error(chalk.dim('  Or: npx -y @polderlabs/bizar install'));
+    process.exit(1);
+  }
+
+  switch (sub) {
+    case 'start':
+      await dashModule.start(subOpts);
+      break;
+    case 'stop':
+      await dashModule.stop(subOpts);
+      break;
+    case 'status':
+      await dashModule.status(subOpts);
+      break;
+    case 'tui':
+      await dashModule.tui(subOpts);
+      break;
+    default:
+      console.error(chalk.red(`  ✗ Unknown subcommand: ${sub}`));
+      showDashHelp();
+      process.exit(1);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
 await main().catch((err) => {
   console.error(chalk.red(`bizar: ${err && err.message ? err.message : String(err)}`));
   process.exit(1);

package/cli/copy.mjs

@@ -356,6 +356,9 @@ export async function installRtk() {
   const spinner = ora({ text: 'Installing RTK (Rust Token Killer)...', color: 'magenta' }).start();
 
   if (process.platform === 'win32') {
+    // RTK ships a bash-only installer; no PowerShell equivalent. On
+    // Windows the user must install RTK manually (e.g. via Cargo or
+    // prebuilt binary) and re-run `rtk init -g --opencode`.
     spinner.fail(chalk.red('Automatic RTK install not supported on Windows. Install manually from https://github.com/rtk-ai/rtk'));
     return false;
   }
@@ -392,13 +395,17 @@ export async function installSemble() {
     spinner.text = 'Installing uv (Python package manager)...';
     try {
       if (process.platform === 'win32') {
-        spinner.fail(chalk.red('Automatic uv install not supported on Windows. Install from https://docs.astral.sh/uv'));
-        return false;
+        // Windows: use the official PowerShell installer
+        execSync(
+          'powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"',
+          { stdio: 'pipe', timeout: 60000 },
+        );
+      } else {
+        execSync(
+          'curl -LsSf https://astral.sh/uv/install.sh | sh',
+          { stdio: 'pipe', timeout: 60000 },
+        );
       }
-      execSync(
-        'curl -LsSf https://astral.sh/uv/install.sh | sh',
-        { stdio: 'pipe', timeout: 60000 },
-      );
       spinner.text = 'Setting up Semble...';
     } catch {
       spinner.fail(chalk.red('uv install failed. Install manually from https://docs.astral.sh/uv'));

package/cli/graph.mjs

@@ -20,13 +20,18 @@ export const GRAPHIFY_OUT_ENV = 'GRAPHIFY_OUT';
 /**
  * Find a Python 3 interpreter on PATH.
  * Returns the absolute path string, or null if none found.
+ *
+ * On Windows the `py` launcher is the most reliable option; on Unix
+ * we prefer python3 then python.
  */
 export function findPython() {
-  // Prefer python3, fall back to python
-  for (const name of ['python3', 'python']) {
+  const candidates = process.platform === 'win32'
+    ? ['py', 'python', 'python3']
+    : ['python3', 'python'];
+  for (const name of candidates) {
     try {
       const result = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
-      if (result.status === 0 && result.stdout.includes('Python 3')) {
+      if (result.status === 0 && result.stdout.includes('Python')) {
         return name;
       }
     } catch {
@@ -37,10 +42,33 @@ export function findPython() {
 }
 
 /**
- * Check whether graphify is available via `python3 -m graphify --version`.
+ * Check whether graphify is available.
+ *
+ * Strategy:
+ *  1. Probe PATH for the `graphify` binary (uv tool install puts a shim at
+ *     ~/.local/bin/graphify — invisible to the isolated python -m lookup).
+ *  2. Fall back to `python -m graphify --version` for pip/pipx installs.
+ *
  * Returns true if available, false otherwise.
  */
 function checkGraphify(python) {
+  // Try 1: check for the graphify binary on PATH (uv tool install shim).
+  // On Windows the Python launcher `py` is not on PATH by default, but the
+  // graphify shim is placed next to pip/pipx so a plain `where` works.
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const whichResult = spawnSync(whichCmd, ['graphify'], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    if (whichResult.status === 0 && (whichResult.stdout || '').trim().length > 0) {
+      return true;
+    }
+  } catch {
+    // fall through to python -m check
+  }
+
+  // Try 2: check via python -m (catches pip/pipx installs into system python)
   try {
     const result = spawnSync(python, ['-m', 'graphify', '--version'], {
       encoding: 'utf8',
@@ -219,19 +247,33 @@ async function cmdInstall() {
     return 1;
   }
 
-  console.log(chalk.dim('  Installing graphify via pip...\n'));
+  // Prefer uv (handles PEP 668 isolated installs cleanly); fall back to pip.
+  const { detectUv } = await import('./utils.mjs');
+  const hasUv = await detectUv();
 
-  // pip install graphifyy
-  console.log(chalk.dim('  $ pip install graphifyy'));
-  let result = spawnSync('pip', ['install', 'graphifyy'], { stdio: 'inherit' });
-  if (result.status !== 0) {
-    console.log(chalk.red('  ✗ pip install graphifyy failed.\n'));
-    return 1;
+  if (hasUv) {
+    console.log(chalk.dim('  Installing graphify via uv...\n'));
+    const result = spawnSync('uv', ['tool', 'install', 'graphifyy'], { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.log(chalk.red('  ✗ uv tool install graphifyy failed.\n'));
+      return 1;
+    }
+  } else {
+    console.log(chalk.dim('  Installing graphify via pip...\n'));
+    // On Windows `pip` may not be on PATH; use `py -m pip` as the fallback.
+    const pipCmd = process.platform === 'win32'
+      ? [python, '-m', 'pip']
+      : ['pip'];
+    const result = spawnSync(pipCmd[0], pipCmd.slice(1).concat(['install', 'graphifyy']), { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.log(chalk.red('  ✗ pip install graphifyy failed.\n'));
+      return 1;
+    }
   }
 
   // graphify install --platform opencode --project
   console.log(chalk.dim('\n  $ graphify install --platform opencode --project'));
-  result = spawnSync('graphify', ['install', '--platform', 'opencode', '--project'], {
+  const result = spawnSync('graphify', ['install', '--platform', 'opencode', '--project'], {
     stdio: 'inherit',
   });
   if (result.status !== 0) {

package/cli/init.mjs

@@ -154,12 +154,22 @@ ${stack.runner ? `- Dev: \`${stack.runner}\`` : ''}
   // Soft step: never fails init. If graphify is missing or build errors,
   // the user can retry manually with `bizar graph build`.
   console.log(chalk.bold('\n--- Graph ---\n'));
-  const detectGraphify = spawnSync('python3', ['-c', 'import graphify; print(graphify.__version__)'], {
-    cwd,
-    encoding: 'utf8',
-    timeout: 5000,
-  });
-  const graphifyAvailable = detectGraphify.status === 0 && (detectGraphify.stdout || '').trim().length > 0;
+
+  // Check for the graphify binary on PATH first (uv tool install shim).
+  // Falls back to python -m for pip/pipx installs.
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  const whichCheck = spawnSync(whichCmd, ['graphify'], { encoding: 'utf8', timeout: 5000 });
+  let graphifyAvailable = whichCheck.status === 0 && (whichCheck.stdout || '').trim().length > 0;
+
+  if (!graphifyAvailable) {
+    const python = process.platform === 'win32' ? 'py' : 'python3';
+    const detectGraphify = spawnSync(python, ['-c', 'import graphify; print(graphify.__version__)'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    graphifyAvailable = detectGraphify.status === 0 && (detectGraphify.stdout || '').trim().length > 0;
+  }
 
   if (!graphifyAvailable) {
     console.log(chalk.yellow('  graphify not detected — skipping project graph build.'));