@polderlabs/bizar 3.7.2 → 3.8.0

package/cli/bin.mjs

@@ -28,6 +28,7 @@ import { runInit } from './init.mjs';
 import { runExport } from './export.mjs';
 import runPlan from './plan.mjs';
 import { runUpdate } from './update.mjs';
+import { runGraph } from './graph.mjs';
 import { ensureSetup, checkSetupStatus } from './bootstrap.mjs';
 
 const args = process.argv.slice(2);
@@ -86,6 +87,7 @@ function showHelp() {
     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
@@ -126,7 +128,29 @@ function showInitHelp() {
 
   Description:
     Detects the project stack, creates .bizar/PROJECT.md and
-    .bizar/AGENTS_SELF_IMPROVEMENT.md, and installs relevant skills.
+    .bizar/AGENTS_SELF_IMPROVEMENT.md, installs relevant skills,
+    and builds the per-project knowledge graph in .bizar/graph/
+    (requires graphify — pip install graphifyy — otherwise the
+    graph step is skipped gracefully).
+  `);
+}
+
+function showGraphHelp() {
+  console.log(`
+  bizar graph — Per-project knowledge graph (powered by graphify)
+
+  Usage:
+    bizar graph build              # full build of the project graph
+    bizar graph update             # incremental rebuild
+    bizar graph query "<text>"     # query the graph
+    bizar graph path "<A>" "<B>"   # shortest path between concepts
+    bizar graph explain "<X>"      # all nodes related to a concept
+    bizar graph watch              # watch for changes and rebuild
+    bizar graph status             # show graph path, size, node/edge/community counts
+    bizar graph install            # install graphify + drop OpenCode skill/plugin
+
+  Requires Python 3.10+ and \`graphify\` (pip install graphifyy).
+  Graph data lives in .bizar/graph/ inside this project.
   `);
 }
 
@@ -157,18 +181,40 @@ function showInstallHelp() {
 
 function showUpdateHelp() {
   console.log(`
-  bizar update — Update opencode, bizar, and/or bizar-plugin
+  bizar update — Update opencode, bizar, bizar-dash, and/or bizar-plugin
 
   Usage:
-    bizar update
-    bizar update --all
-    bizar update opencode
-    bizar update bizar
-    bizar update plugin
-
-  Description:
-    Prompts interactively by default. Use --all for non-interactive
-    updates, or pass explicit component names.
+    bizar update                       Interactive prompt for components
+    bizar update --all                 Update every component
+    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 --help                Show this help
+
+  Components:
+    opencode   the opencode CLI itself
+    bizar      @polderlabs/bizar (this CLI + installer + agents + rules)
+    dash       @polderlabs/bizar-dash (web dashboard + TUI)
+    plugin     @polderlabs/bizar-plugin (opencode plugin)
+
+  Behavior:
+    • Detects running Bizar instances (background service daemon, web
+      dashboard) by reading ~/.config/bizar/{service,dashboard}.pid and
+      cleaning up any stale or empty PID files.
+    • Warns the user explicitly before killing each instance. Pass
+      --yes / -y / --force to skip the confirmation (required for
+      non-interactive shells).
+    • 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,
+      spawns a fresh detached dashboard process with the new code
+      (skipped with --no-restart).
+
+  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
   `);
 }
 
@@ -354,6 +400,9 @@ async function main() {
   } else if (args[0] === 'init') {
     if (isHelpRequest) showInitHelp();
     else await runInit(process.cwd());
+  } else if (args[0] === 'graph') {
+    if (isHelpRequest) showGraphHelp();
+    else await runGraph(args.slice(1));
   } else if (args[0] === 'export') {
     if (isHelpRequest) showExportHelp();
     else await runExport(parseFlag('--target'));

package/cli/graph.mjs

@@ -0,0 +1,337 @@
+/**
+ * cli/graph.mjs
+ *
+ * `bizar graph` — Per-project knowledge graph powered by graphify.
+ * Graph data lives in .bizar/graph/ inside the project.
+ */
+
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+export const GRAPH_DIR = '.bizar/graph';
+export const GRAPHIFY_OUT_ENV = 'GRAPHIFY_OUT';
+
+// ── Python detection ───────────────────────────────────────────────────────────
+
+/**
+ * Find a Python 3 interpreter on PATH.
+ * Returns the absolute path string, or null if none found.
+ */
+export function findPython() {
+  // Prefer python3, fall back to python
+  for (const name of ['python3', 'python']) {
+    try {
+      const result = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0 && result.stdout.includes('Python 3')) {
+        return name;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Check whether graphify is available via `python3 -m graphify --version`.
+ * Returns true if available, false otherwise.
+ */
+function checkGraphify(python) {
+  try {
+    const result = spawnSync(python, ['-m', 'graphify', '--version'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      env: { ...process.env },
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ── Graph stats parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse .bizar/graph/graph.json and return stats.
+ * Returns null if the file does not exist or cannot be parsed.
+ *
+ * Expected NetworkX node-link JSON shape:
+ * {
+ *   "directed": false,
+ *   "multigraph": false,
+ *   "graph": {},
+ *   "nodes": [{ "id": "...", "community": 0, ... }],
+ *   "links": [{ "source": "...", "target": "...", ... }]
+ * }
+ */
+export function parseGraphStats(jsonPath) {
+  if (!existsSync(jsonPath)) return null;
+  try {
+    const content = readFileSync(jsonPath, 'utf8');
+    const graph = JSON.parse(content);
+
+    const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+    const links = Array.isArray(graph.links) ? graph.links : [];
+
+    // Count unique community values among nodes
+    const communitySet = new Set();
+    for (const node of nodes) {
+      if (node.community !== undefined && node.community !== null) {
+        communitySet.add(node.community);
+      }
+    }
+
+    const stats = statSync(jsonPath);
+
+    return {
+      nodes: nodes.length,
+      edges: links.length,
+      communities: communitySet.size,
+      lastModified: stats.mtime.toISOString(),
+      sizeBytes: stats.size,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Gitignore guard ────────────────────────────────────────────────────────────
+
+const GRAPH_GITIGNORE = `cache/
+.graphify_python
+cost.json
+`;
+
+/**
+ * Ensure .bizar/graph/.gitignore exists so heavy cache artefacts are not committed.
+ * Called after a successful first build.
+ */
+function ensureGitignore(graphDir) {
+  const gitignorePath = join(graphDir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, GRAPH_GITIGNORE, 'utf8');
+  }
+}
+
+// ── Run helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Spawn a graphify command with GRAPHIFY_OUT set to GRAPH_DIR.
+ * Streams stdout/stderr to the terminal. Returns the exit code.
+ */
+function runGraphify(python, subArgs, extraEnv = {}) {
+  const env = { ...process.env, [GRAPHIFY_OUT_ENV]: GRAPH_DIR };
+  const result = spawnSync(python, ['-m', 'graphify', ...subArgs], {
+    stdio: 'inherit',
+    env,
+    timeout: 0, // no timeout — user may run long builds
+  });
+  return result.status ?? 1;
+}
+
+// ── Subcommand handlers ────────────────────────────────────────────────────────
+
+async function cmdBuild(python) {
+  console.log(chalk.dim('  Running full graphify pipeline...'));
+  const code = runGraphify(python, ['.']);
+  if (code === 0) {
+    ensureGitignore(GRAPH_DIR);
+    console.log(chalk.green(`\n  ✓ Graph built → ${GRAPH_DIR}/\n`));
+  }
+  return code;
+}
+
+async function cmdUpdate(python) {
+  console.log(chalk.dim('  Running incremental graph update...'));
+  return runGraphify(python, ['.', '--update']);
+}
+
+async function cmdQuery(python, query) {
+  if (!query) {
+    console.log(chalk.red('  Error: query text required.'));
+    console.log(chalk.dim('  Usage: bizar graph query "<search term>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['query', query]);
+}
+
+async function cmdPath(python, a, b) {
+  if (!a || !b) {
+    console.log(chalk.red('  Error: two concept names required.'));
+    console.log(chalk.dim('  Usage: bizar graph path "<A>" "<B>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['path', a, b]);
+}
+
+async function cmdExplain(python, concept) {
+  if (!concept) {
+    console.log(chalk.red('  Error: concept name required.'));
+    console.log(chalk.dim('  Usage: bizar graph explain "<X>"\n'));
+    return 1;
+  }
+  return runGraphify(python, ['explain', concept]);
+}
+
+async function cmdWatch(python) {
+  console.log(chalk.dim('  Starting graphify watch mode (Ctrl-C to stop)...'));
+  return runGraphify(python, ['.', '--watch']);
+}
+
+async function cmdStatus() {
+  const graphJsonPath = join(GRAPH_DIR, 'graph.json');
+  const stats = parseGraphStats(graphJsonPath);
+
+  console.log(chalk.bold.hex('#10b981')('\n  ᛗ BIZAR GRAPH STATUS ᛗ\n'));
+  console.log(`  Path:       ${GRAPH_DIR}/`);
+
+  if (!existsSync(GRAPH_DIR)) {
+    console.log(`  Exists:     ${chalk.yellow('no')}  (run \`bizar graph build\` first)`);
+    console.log();
+    return 0;
+  }
+
+  if (!stats) {
+    console.log(`  Exists:     ${chalk.yellow('no graph.json found')}`);
+    console.log();
+    return 0;
+  }
+
+  console.log(`  Exists:     ${chalk.green('yes')}`);
+  console.log(`  Size:       ${(stats.sizeBytes / 1024).toFixed(1)} KB`);
+  console.log(`  Last built: ${stats.lastModified}`);
+  console.log(`  Nodes:      ${stats.nodes}`);
+  console.log(`  Edges:      ${stats.edges}`);
+  console.log(`  Communities:${stats.communities}`);
+  console.log();
+  return 0;
+}
+
+async function cmdInstall() {
+  const python = findPython();
+  if (!python) {
+    console.error(chalk.red('  Error: graphify requires Python 3.10+.'));
+    console.error(chalk.dim('  Install Python from https://python.org or via your package manager, then re-run.\n'));
+    return 1;
+  }
+
+  console.log(chalk.dim('  Installing graphify via pip...\n'));
+
+  // 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;
+  }
+
+  // graphify install --platform opencode --project
+  console.log(chalk.dim('\n  $ graphify install --platform opencode --project'));
+  result = spawnSync('graphify', ['install', '--platform', 'opencode', '--project'], {
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    console.log(chalk.red('  ✗ graphify install failed.\n'));
+    return 1;
+  }
+
+  console.log(chalk.green('\n  ✓ graphify installed and OpenCode plugin configured.\n'));
+  return 0;
+}
+
+// ── Help ──────────────────────────────────────────────────────────────────────
+
+export function showGraphHelp() {
+  console.log(`
+  ${chalk.bold.hex('#10b981')('bizar graph')} — Per-project knowledge graph (powered by graphify)
+
+  ${chalk.dim('Usage:')}
+    ${chalk.cyan('bizar graph build')}              # full build of the project graph
+    ${chalk.cyan('bizar graph update')}              # incremental rebuild
+    ${chalk.cyan('bizar graph query "<text>"')}    # query the graph
+    ${chalk.cyan('bizar graph path "<A>" "<B>"')}  # shortest path between concepts
+    ${chalk.cyan('bizar graph explain "<X>"')}     # all nodes related to a concept
+    ${chalk.cyan('bizar graph watch')}              # watch for changes and rebuild
+    ${chalk.cyan('bizar graph status')}             # show graph path, size, node/edge/community counts
+    ${chalk.cyan('bizar graph install')}            # install graphify + drop OpenCode skill/plugin
+
+  ${chalk.dim('Requires:')} Python 3.10+ and \`graphify\` (${chalk.cyan('pip install graphifyy')})
+
+  ${chalk.dim('Graph data lives in')} ${chalk.cyan('.bizar/graph/')} ${chalk.dim('inside this project.')}
+  `);
+}
+
+// ── Main entry point ───────────────────────────────────────────────────────────
+
+/**
+ * `bizar graph` entry point.
+ *
+ * @param {string[]} args — subcommand + args after 'graph'
+ */
+export async function runGraph(args) {
+  // Show help when called with no args or --help / -h
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    showGraphHelp();
+    return 0;
+  }
+
+  const sub = args[0];
+
+  // status and install are the only subcommands that don't need graphify
+  if (sub !== 'status' && sub !== 'install') {
+    // Detect Python
+    const python = findPython();
+    if (!python) {
+      console.error(chalk.red('  Error: graphify requires Python 3.10+.'));
+      console.error(chalk.dim('  Install Python from https://python.org or via your package manager, then re-run.\n'));
+      return 1;
+    }
+
+    // Detect graphify
+    if (!checkGraphify(python)) {
+      console.error(chalk.red('  Error: graphify is not installed.'));
+      console.error(chalk.dim('  Install it with:'));
+      console.error(chalk.cyan('    pip install graphifyy\n'));
+      console.error(chalk.dim('  Or run:'));
+      console.error(chalk.cyan('    bizar graph install\n'));
+      return 1;
+    }
+
+    // Ensure .bizar/ directory exists (graphify will create graph/ inside it)
+    mkdirSync(GRAPH_DIR, { recursive: true });
+
+    switch (sub) {
+      case 'build':
+        return await cmdBuild(python);
+      case 'update':
+        return await cmdUpdate(python);
+      case 'query':
+        return await cmdQuery(python, args.slice(1).join(' '));
+      case 'path':
+        return await cmdPath(python, args[1], args[2]);
+      case 'explain':
+        return await cmdExplain(python, args[1]);
+      case 'watch':
+        return await cmdWatch(python);
+      default:
+        console.error(chalk.red(`  Error: unknown subcommand '${sub}'.\n`));
+        showGraphHelp();
+        return 1;
+    }
+  }
+
+  // subcommands that don't need graphify
+  switch (sub) {
+    case 'status':
+      return await cmdStatus();
+    case 'install':
+      return await cmdInstall();
+    default:
+      // unreachable — already caught unknown subcommands above
+      return 1;
+  }
+}

package/cli/graph.test.mjs

@@ -0,0 +1,218 @@
+/**
+ * cli/graph.test.mjs
+ *
+ * Tests for the `bizar graph` subcommand.
+ * Uses Node's built-in node:test (no external test framework).
+ *
+ * Covered:
+ *   - findPython() returns a string when Python is on PATH (or null)
+ *   - parseGraphStats() returns null for nonexistent files
+ *   - parseGraphStats() returns correct {nodes, edges, communities} from a fixture
+ *   - GRAPH_DIR constant is '.bizar/graph'
+ *   - help output contains all subcommand names
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Resolve graph.mjs from this test file's location
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
+
+const {
+  findPython,
+  parseGraphStats,
+  showGraphHelp,
+  GRAPH_DIR,
+} = await import('./graph.mjs');
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+test('GRAPH_DIR equals ".bizar/graph"', () => {
+  assert.equal(GRAPH_DIR, '.bizar/graph');
+});
+
+// ── findPython ────────────────────────────────────────────────────────────────
+
+describe('findPython()', () => {
+  test('returns a string when python3 or python is on PATH', () => {
+    const result = findPython();
+    // On most dev machines Python is installed; the test documents the expected shape
+    if (result !== null) {
+      assert.equal(typeof result, 'string');
+      assert.ok(result.length > 0);
+    }
+  });
+
+  test('returns null when neither python3 nor python is found', () => {
+    // We can't easily stub PATH in this test runner without副作用,
+    // so we verify the function is deterministic and returns the same value
+    // across two calls (proving it doesn't throw or return garbage).
+    const first = findPython();
+    const second = findPython();
+    assert.equal(first, second, 'findPython should be deterministic');
+  });
+});
+
+// ── parseGraphStats ────────────────────────────────────────────────────────────
+
+describe('parseGraphStats()', () => {
+  test('returns null for a nonexistent path', () => {
+    const result = parseGraphStats('/nonexistent/path/graph.json');
+    assert.equal(result, null);
+  });
+
+  test('returns null for a file that is not valid JSON', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const badPath = join(tmpDir, 'graph.json');
+      writeFileSync(badPath, '{ not json', 'utf8');
+      const result = parseGraphStats(badPath);
+      assert.equal(result, null);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('returns zeroed stats when graph.json has null nodes/links arrays', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test2');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+      writeFileSync(graphPath, JSON.stringify({ graph: {}, nodes: null, links: null }), 'utf8');
+      const result = parseGraphStats(graphPath);
+      // null arrays are treated as 0-length — parseGraphStats guards with Array.isArray
+      assert.notEqual(result, null);
+      assert.equal(result.nodes, 0);
+      assert.equal(result.edges, 0);
+      assert.equal(result.communities, 0);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('returns correct stats from a minimal NetworkX node-link fixture', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test3');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+
+      // NetworkX node-link JSON with 4 nodes, 3 links, 2 communities
+      const fixture = {
+        directed: false,
+        multigraph: false,
+        graph: {},
+        nodes: [
+          { id: 'alpha', community: 0 },
+          { id: 'beta', community: 0 },
+          { id: 'gamma', community: 1 },
+          { id: 'delta', community: 1 },
+        ],
+        links: [
+          { source: 'alpha', target: 'beta' },
+          { source: 'beta', target: 'gamma' },
+          { source: 'gamma', target: 'delta' },
+        ],
+      };
+
+      writeFileSync(graphPath, JSON.stringify(fixture), 'utf8');
+
+      const stats = parseGraphStats(graphPath);
+
+      assert.notEqual(stats, null);
+      assert.equal(stats.nodes, 4, 'should count 4 nodes');
+      assert.equal(stats.edges, 3, 'should count 3 links');
+      assert.equal(stats.communities, 2, 'should detect 2 unique communities (0 and 1)');
+      assert.ok(typeof stats.lastModified === 'string', 'lastModified should be ISO string');
+      assert.ok(typeof stats.sizeBytes === 'number', 'sizeBytes should be a number');
+      assert.ok(stats.sizeBytes > 0, 'sizeBytes should be > 0 for a real file');
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test('handles nodes without a community field gracefully', () => {
+    const tmpDir = join(PROJECT_ROOT, '.tmp_graph_test4');
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      const graphPath = join(tmpDir, 'graph.json');
+      const fixture = {
+        nodes: [
+          { id: 'orphan' },   // no community field
+          { id: 'solo', community: 0 },
+          { id: 'alone', community: 1 },
+        ],
+        links: [],
+      };
+      writeFileSync(graphPath, JSON.stringify(fixture), 'utf8');
+      const stats = parseGraphStats(graphPath);
+      assert.notEqual(stats, null);
+      assert.equal(stats.communities, 2, 'should count communities 0 and 1 only');
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+});
+
+// ── Help output ───────────────────────────────────────────────────────────────
+
+describe('showGraphHelp()', () => {
+  test('outputs all subcommand names', () => {
+    // Capture stdout
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Assert each expected subcommand keyword appears in the help text
+    const subcommands = ['build', 'update', 'query', 'path', 'explain', 'watch', 'status', 'install'];
+    for (const cmd of subcommands) {
+      assert.ok(
+        output.includes(cmd),
+        `help output should contain subcommand "${cmd}"`
+      );
+    }
+  });
+
+  test('mentions the GRAPH_DIR path', () => {
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    assert.ok(output.includes('.bizar/graph'), 'help should mention the graph directory');
+  });
+
+  test('mentions graphify pip install command', () => {
+    let output = '';
+    const originalLog = console.log;
+    console.log = (msg) => { output += msg + '\n'; };
+
+    try {
+      showGraphHelp();
+    } finally {
+      console.log = originalLog;
+    }
+
+    assert.ok(
+      output.includes('pip install graphifyy'),
+      'help should mention pip install graphifyy'
+    );
+  });
+});
+
+console.log('  graph.mjs tests loaded — run with: node --test cli/graph.test.mjs');