@polderlabs/bizar 3.23.1 → 4.2.0

package/bizar-dash/templates/mod/FORMAT.md

@@ -0,0 +1,76 @@
+# Bizar Mods — Format Reference (v3.0.0)
+
+A mod is a folder with a `mod.json` manifest that extends the Bizar
+platform. Mods live at `~/.config/bizar/mods/<mod-id>/`.
+
+## Folder layout
+
+```
+<mod-id>/
+├── mod.json           # manifest (required)
+├── README.md          # description (optional)
+├── agents/            # custom agents (optional)
+│   └── <agent>.md
+├── commands/          # custom commands (optional)
+│   └── <command>.md
+├── routes/            # custom API routes (optional)
+│   └── <route>.mjs
+├── views/             # custom React views (optional)
+│   └── <view>.tsx
+├── web/               # custom web assets (optional)
+│   └── index.html
+├── tui/               # custom TUI components (optional)
+│   └── <comp>.mjs
+└── hooks/             # custom event hooks (optional)
+    └── <hook>.mjs
+```
+
+## mod.json schema
+
+```json
+{
+  "id": "my-mod",
+  "name": "My Mod",
+  "version": "1.0.0",
+  "author": "name",
+  "description": "...",
+  "bizar": ">=3.0.0",
+  "type": "agent" | "command" | "view" | "route" | "tui" | "full",
+  "enabled": true,
+  "permissions": ["read:agents", "write:tasks"],
+  "entry": {
+    "agent": "agents/my-agent.md",
+    "command": "commands/my-command.md",
+    "route": "routes/my-route.mjs",
+    "view": "views/my-view.tsx",
+    "tui": "tui/my-comp.mjs"
+  }
+}
+```
+
+## Permissions (v3.0.0)
+
+`permissions` is a hint to the user. v3 doesn't enforce it yet — the
+runtime is permissive. Future versions will gate operations by
+permission.
+
+Common permission strings:
+- `read:agents`
+- `write:agents`
+- `read:tasks`
+- `write:tasks`
+- `read:projects`
+- `write:projects`
+- `read:schedules`
+- `write:schedules`
+- `read:config`
+- `write:config`
+
+## Lifecycle
+
+- The dashboard scans `~/.config/bizar/mods/` on startup.
+- For each mod with `enabled: true`, the loader exposes its agents,
+  commands, and views in the dashboard.
+- v3 doesn't dynamically mount mod routes or render mod views — those
+  are planned for v3.1+. Mods that ship today can still install custom
+  agents and commands.

package/bizar-dash/templates/mod/hello-mod/README.md

@@ -0,0 +1,19 @@
+# Hello Mod
+
+A sample mod that ships with the Bizar platform. It demonstrates:
+
+- A `mod.json` manifest with permissions and an `entry` block
+- A sample agent (`agents/greeter.md`)
+- A slash command (`commands/hello.md`)
+- A route module (`routes/ping.mjs`) — the v3.1+ runtime will mount it
+- A view metadata file (`views/HelloView.tsx`) — the v3.1+ dashboard
+  will render it as a tab
+
+## Install
+
+```bash
+# from the bizarre-dash package root
+bizar mod install ./templates/mod/hello-mod
+```
+
+Or copy the folder into `~/.config/bizar/mods/hello-mod/` by hand.

package/bizar-dash/templates/mod/hello-mod/agents/greeter.md

@@ -0,0 +1,8 @@
+---
+description: Greets the user with a friendly hello.
+mode: subagent
+model: anthropic/claude-3-5-sonnet
+---
+
+You are a friendly greeter. When invoked, respond with a warm hello and
+ask the user how you can help. Keep it short and friendly.

package/bizar-dash/templates/mod/hello-mod/commands/hello.md

@@ -0,0 +1,6 @@
+---
+description: Say hello from the Hello Mod
+---
+
+Greet the user. Print a friendly hello and remind them that the
+Hello Mod is loaded.

package/bizar-dash/templates/mod/hello-mod/mod.json

@@ -0,0 +1,20 @@
+{
+  "id": "hello-mod",
+  "name": "Hello Mod",
+  "version": "1.0.0",
+  "author": "Bizar",
+  "description": "A sample mod that adds a /hello slash command, a Hello view tab, and a sample agent.",
+  "bizar": ">=3.0.0",
+  "type": "full",
+  "enabled": true,
+  "permissions": [
+    "read:agents",
+    "read:commands"
+  ],
+  "entry": {
+    "agent": "agents/greeter.md",
+    "command": "commands/hello.md",
+    "view": "views/HelloView.tsx"
+  },
+  "installedAt": null
+}

package/bizar-dash/templates/mod/hello-mod/routes/ping.mjs

@@ -0,0 +1,9 @@
+// Sample route registration for the Hello Mod.
+// v3 doesn't dynamically mount mod routes yet, but this file documents
+// the intended shape for v3.1+.
+
+export default function register({ app, state }) {
+  app.get('/api/mods/hello-mod/ping', (req, res) => {
+    res.json({ ok: true, from: 'hello-mod', ts: Date.now() });
+  });
+}

package/bizar-dash/templates/mod/hello-mod/views/HelloView.tsx

@@ -0,0 +1,10 @@
+// Sample view metadata for the Hello Mod.
+// v3 doesn't dynamically mount mod views yet, but this file documents
+// the intended shape for v3.1+.
+
+export default {
+  id: 'hello',
+  label: 'Hello',
+  icon: 'Sparkles',
+  component: 'HelloView',
+};

package/bizar-dash/tests/dashboard-ports.test.mjs

@@ -0,0 +1,138 @@
+/**
+ * bizar-dash/tests/dashboard-ports.test.mjs
+ *
+ * Regression tests for the "stale PID file → false positive
+ * `Another Bizar dashboard is already running`" trap.
+ *
+ * History (v3.20.14):
+ *   - The dashboard lifecycle used to:
+ *     1. Scan `ps` for any process whose argv contained "bizar dash"
+ *        or "@polderlabs/bizar-dash/src/cli.mjs".
+ *     2. Trust that ps-scan result + `process.kill(pid, 0)` returned
+ *        true to mean "this is a dashboard".
+ *     3. Refuse to start, refuse to cleanup, refuse to stop.
+ *   - On a busy machine, Linux recycles PIDs in milliseconds. A
+ *     chrome-headless-shell renderer that happened to land on the
+ *     recycled PID number would match the regex AND pass kill(0),
+ *     and the dashboard would refuse to start forever.
+ *   - The cmdline was stale, but `ps` re-reads /proc each call so
+ *     we never noticed.
+ *
+ * Fix: `cmdlineLooksLikeDashboard(cmdline)` rejects anything that
+ * doesn't structurally look like a Bizar dashboard launch. Re-applied
+ * at probe time via `verifyCmdlineAtProbeTime(pid)` to catch the
+ * recycled-PID race.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  cmdlineLooksLikeDashboard,
+  verifyCmdlineAtProbeTime,
+} from '../src/cli/dashboard-ports.mjs';
+
+// ── cmdlineLooksLikeDashboard ─────────────────────────────────────────
+
+test('cmdlineLooksLikeDashboard: accepts node + cli.mjs direct invocation', () => {
+  assert.equal(
+    cmdlineLooksLikeDashboard('node /usr/local/lib/node_modules/@polderlabs/bizar-dash/src/cli.mjs start'),
+    true,
+  );
+  assert.equal(
+    cmdlineLooksLikeDashboard('node /home/me/.local/share/npm/_npx/hash/node_modules/@polderlabs/bizar-dash/src/cli.mjs start --bg --port=4321'),
+    true,
+  );
+});
+
+test('cmdlineLooksLikeDashboard: accepts bizar-bin invocation', () => {
+  assert.equal(
+    cmdlineLooksLikeDashboard('/usr/local/bin/bizar dash start'),
+    true,
+  );
+  assert.equal(
+    cmdlineLooksLikeDashboard('/home/me/.local/npm/bin/bizar dash start --bg --port=4322'),
+    true,
+  );
+  assert.equal(
+    cmdlineLooksLikeDashboard('node /usr/local/bin/bizar dash tui'),
+    true,
+  );
+});
+
+test('cmdlineLooksLikeDashboard: rejects chrome-headless-shell renderer (recycled PID)', () => {
+  // This is what a recycled PID looks like: chrome-headless-shell
+  // happened to land on PID 938619, and its cmdline contains the
+  // substring "bizar" nowhere — so it should NOT be flagged as a
+  // dashboard.
+  assert.equal(
+    cmdlineLooksLikeDashboard('/home/me/.cache/puppeteer/chrome-headless-shell-linux64/chrome-headless-shell --type=renderer --headless=old --no-sandbox'),
+    false,
+  );
+});
+
+test('cmdlineLooksLikeDashboard: rejects stale shell command containing the words "bizar dash"', () => {
+  // A bash command whose body mentions `bizar dash` in a comment
+  // would match the old loose regex. The structural check rejects it
+  // because there's no `bizar` bin followed by `dash <subcommand>`.
+  assert.equal(
+    cmdlineLooksLikeDashboard('bash -c "echo I want to run bizar dash start"'),
+    false,
+  );
+  assert.equal(
+    cmdlineLooksLikeDashboard('man bizar-dash-config'),
+    false,
+  );
+});
+
+test('cmdlineLooksLikeDashboard: rejects ssh / tailscale sessions with "bizar" in env', () => {
+  // An ssh session whose env has "bizar" in some variable but whose
+  // argv doesn't actually invoke the dashboard CLI.
+  assert.equal(
+    cmdlineLooksLikeDashboard('/usr/sbin/tailscaled be-child ssh --login-shell=/usr/bin/fish'),
+    false,
+  );
+});
+
+test('cmdlineLooksLikeDashboard: rejects empty / null input', () => {
+  assert.equal(cmdlineLooksLikeDashboard(''), false);
+  assert.equal(cmdlineLooksLikeDashboard(null), false);
+  assert.equal(cmdlineLooksLikeDashboard(undefined), false);
+  assert.equal(cmdlineLooksLikeDashboard(42), false);
+});
+
+// ── verifyCmdlineAtProbeTime ───────────────────────────────────────────
+
+test('verifyCmdlineAtProbeTime: dead PID returns null', () => {
+  // Use a PID that's almost certainly dead.
+  const result = verifyCmdlineAtProbeTime(999999999);
+  assert.equal(result, null);
+});
+
+test('verifyCmdlineAtProbeTime: current PID with non-dashboard cmdline returns null', () => {
+  // The test runner itself is a node process but its cmdline won't
+  // look like a Bizar dashboard launch.
+  const result = verifyCmdlineAtProbeTime(process.pid);
+  assert.equal(result, null);
+});
+
+test('verifyCmdlineAtProbeTime: missing PID returns null', () => {
+  assert.equal(verifyCmdlineAtProbeTime(null), null);
+  assert.equal(verifyCmdlineAtProbeTime(0), null);
+  assert.equal(verifyCmdlineAtProbeTime(undefined), null);
+});
+
+// ── Real-world cmdline strings that have caused false positives ───────
+
+test('cmdlineLooksLikeDashboard: rejects the v3.20.13 false-positive case', () => {
+  // The exact scenario from the v3.20.13 bug report: ps-scan found
+  // PID 938619 with cmdline "node /home/drb0rk/.local/npm/bin/bizar
+  // dash start --bg --port=4322" — except PID 938619 was recycled
+  // to a chrome renderer between ps-scan and pidAlive. The structural
+  // check on the current /proc/<pid>/cmdline returns null, so the
+  // dashboard is correctly classified as dead.
+  //
+  // We simulate this by checking that chrome's cmdline (what the
+  // recycled PID actually contains now) doesn't match.
+  const chromeCmdline = '/home/drb0rk/.cache/puppeteer/chrome-headless-shell-linux64/chrome-headless-shell --type=renderer --headless=old --no-sandbox --remote-debugging-port=9222';
+  assert.equal(cmdlineLooksLikeDashboard(chromeCmdline), false);
+});

package/bizar-dash/tests/graphify-mod-spawn.node.test.mjs

@@ -0,0 +1,90 @@
+/**
+ * graphify-mod-spawn.node.test.mjs — regression test for the SIGPIPE crash.
+ *
+ * The graphify mod's route.mjs used to spawn the `graphify` CLI with
+ * `spawnSync` + `stdio: 'inherit'`. That worked in a terminal, but the
+ * dashboard is a background daemon with stdin=/dev/null and
+ * stdout/stderr redirected to a log file. With `stdio: 'inherit'`, the
+ * child inherits those descriptors; if anything closes or rotates them
+ * mid-build, the kernel delivers SIGPIPE to the dashboard — silently
+ * killing it. The user reported "building the graph crashed the dash".
+ *
+ * This test verifies the source file no longer contains the dangerous
+ * pattern. We parse the file as text (the route.mjs is loaded by the
+ * dashboard's vm sandbox, not directly importable here).
+ *
+ * Run with: node --test tests/graphify-mod-spawn.node.test.mjs
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+// Test lives at bizar-dash/tests/, source is at the repo root.
+const REPO = resolve(import.meta.dirname, '..', '..');
+const SOURCE = join(REPO, 'mods-examples/graphify/route.mjs');
+
+describe('graphify mod — SIGPIPE-safe spawn', () => {
+  it('source file exists at the expected path', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    assert.ok(text.length > 100, 'source file should be substantial');
+  });
+
+  it('does NOT import spawnSync (causes blocking + stdio inheritance)', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    assert.ok(
+      !/\bspawnSync\b/.test(text),
+      'route.mjs must not import or call spawnSync — use async spawn instead',
+    );
+  });
+
+  it('does NOT use stdio: \'inherit\' (the SIGPIPE crash vector)', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    // Strip block comments and line comments before checking — we don't
+    // want the bug description itself to trip the test.
+    const stripped = text
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/^\s*\/\/.*$/gm, '')
+      .replace(/`stdio:\s*'inherit'`/g, '');
+    // Look for the literal string in any quoting style.
+    const patterns = [
+      /stdio:\s*['"]inherit['"]/,
+      /stdio:\s*\[\s*['"]inherit['"]/,
+    ];
+    for (const pat of patterns) {
+      assert.ok(
+        !pat.test(stripped),
+        `route.mjs must not use stdio: 'inherit' — it propagates SIGPIPE to the dashboard`,
+      );
+    }
+  });
+
+  it('isolates the spawned child stdio with [\'ignore\', \'pipe\', \'pipe\']', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    assert.ok(
+      /stdio:\s*\[\s*['"]ignore['"]\s*,\s*['"]pipe['"]\s*,\s*['"]pipe['"]\s*\]/.test(text),
+      'spawn options should set stdio to [ignore, pipe, pipe] for SIGPIPE isolation',
+    );
+  });
+
+  it('runs graphify as an async spawn (not blocking)', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    // runGraphify should be declared `async function` and return a Promise.
+    assert.ok(
+      /async\s+function\s+runGraphify\s*\(/.test(text),
+      'runGraphify should be declared async so the dashboard event loop is not blocked',
+    );
+    assert.ok(
+      /return\s+new\s+Promise\s*\(/.test(text),
+      'runGraphify should return a Promise (async spawn lifecycle)',
+    );
+  });
+
+  it('forwards child stdout/stderr to the broadcast callback (no streaming lost)', () => {
+    const text = readFileSync(SOURCE, 'utf8');
+    assert.ok(
+      /broadcast\(\s*\{\s*type:\s*['"]graphify:build:log['"]/.test(text),
+      'runGraphify should call broadcast with graphify:build:log events so the dashboard UI keeps streaming',
+    );
+  });
+});