@polderlabs/bizar 3.15.1 → 3.17.0

package/cli/bin.mjs

@@ -25,7 +25,6 @@ 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);
@@ -82,7 +81,6 @@ function showHelp() {
     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              Auto-update everything (opencode + bizar + dash + plugin)
     service             Manage the background service daemon
@@ -129,29 +127,10 @@ function showInitHelp() {
 
   Description:
     Detects the project stack, creates .bizar/PROJECT.md and
-    .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.
+    .bizar/AGENTS_SELF_IMPROVEMENT.md and installs relevant skills.
+    The per-project knowledge graph (in .bizar/graph/) is provided
+    by the graphify mod — install it from the mod registry for
+    that feature.
   `);
 }
 
@@ -485,9 +464,6 @@ 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'));
@@ -535,6 +511,10 @@ async function main() {
     // v3.11.1 — Background agent manager (list / view / kill / logs).
     const { runBg } = await import('./bg.mjs');
     await runBg(args[1], args.slice(2));
+  } else if (args[0] === 'providers' && args[1] === 'detect') {
+    // v3.16.0 — Auto-detect provider API keys from env + opencode.json.
+    const { runProvidersDetect } = await import('./providers-detect.mjs');
+    await runProvidersDetect(args.slice(2));
   } else if (args[0] === 'dash' || args[0] === 'dashboard') {
     // `bizar dashboard` is a deprecated alias for `bizar dash`
     if (args[0] === 'dashboard') {

package/cli/install.mjs

@@ -406,6 +406,14 @@ export async function runInstaller() {
   ));
   console.log();
 
+  // ── Provider auto-detect (v3.16.0) — best-effort, doesn't block install
+  const { runProvidersDetect } = await import('./providers-detect.mjs');
+  try {
+    await runProvidersDetect(['--no-probe']);
+  } catch {
+    // best-effort
+  }
+
   // ── Restart prompt ──
   const shouldRestart = await promptRestartOpenCode();
   if (shouldRestart) {

package/cli/providers-detect.mjs

@@ -0,0 +1,233 @@
+/**
+ * cli/providers-detect.mjs
+ *
+ * v3.16.0 — Auto-detect providers from environment variables and
+ * opencode.json. Surfaces which providers have working API keys,
+ * which have keys in unexpected formats, and which need configuration.
+ *
+ * Usage:
+ *   bizar providers detect                  — probe + print
+ *   bizar providers detect --no-probe       — skip the /models probe
+ *   bizar providers detect --json           — machine-readable
+ *   bizar providers detect --install <id>   — auto-add to opencode.json
+ *
+ * Recognised env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY,
+ * GEMINI_API_KEY, GOOGLE_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY,
+ * COHERE_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY,
+ * MINIMAX_API_KEY.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+
+const HOME = homedir();
+const OPENCODE_JSON = join(HOME, '.config', 'opencode', 'opencode.json');
+
+const KNOWN_PROVIDERS = [
+  { id: 'anthropic', name: 'Anthropic', envKeys: ['ANTHROPIC_API_KEY'], baseURL: 'https://api.anthropic.com/v1', keyPattern: /^sk-ant-[A-Za-z0-9_-]{20,}$/ },
+  { id: 'openai', name: 'OpenAI', envKeys: ['OPENAI_API_KEY'], baseURL: 'https://api.openai.com/v1', keyPattern: /^sk-[A-Za-z0-9]{20,}$/ },
+  { id: 'google', name: 'Google AI', envKeys: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'], baseURL: 'https://generativelanguage.googleapis.com/v1beta', keyPattern: /^AIza[A-Za-z0-9_-]{30,}$/ },
+  { id: 'mistral', name: 'Mistral', envKeys: ['MISTRAL_API_KEY'], baseURL: 'https://api.mistral.ai/v1', keyPattern: /^[A-Za-z0-9]{20,}$/ },
+  { id: 'groq', name: 'Groq', envKeys: ['GROQ_API_KEY'], baseURL: 'https://api.groq.com/openai/v1', keyPattern: /^gsk_[A-Za-z0-9]{20,}$/ },
+  { id: 'cohere', name: 'Cohere', envKeys: ['COHERE_API_KEY'], baseURL: 'https://api.cohere.com/v1', keyPattern: /^[A-Za-z0-9]{20,}$/ },
+  { id: 'openrouter', name: 'OpenRouter', envKeys: ['OPENROUTER_API_KEY'], baseURL: 'https://openrouter.ai/api/v1', keyPattern: /^sk-or-[A-Za-z0-9_-]{20,}$/ },
+  { id: 'deepseek', name: 'DeepSeek', envKeys: ['DEEPSEEK_API_KEY'], baseURL: 'https://api.deepseek.com/v1', keyPattern: /^sk-[A-Za-z0-9]{20,}$/ },
+  { id: 'minimax', name: 'MiniMax', envKeys: ['MINIMAX_API_KEY', 'ANTHROPIC_API_KEY'], baseURL: 'https://api.minimax.chat/v1', keyPattern: /^[A-Za-z0-9]{20,}$/ },
+];
+
+function loadOpencodeConfig() {
+  try {
+    if (!existsSync(OPENCODE_JSON)) return {};
+    return JSON.parse(readFileSync(OPENCODE_JSON, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+function saveOpencodeConfig(cfg) {
+  mkdirSync(dirname(OPENCODE_JSON), { recursive: true });
+  const tmp = `${OPENCODE_JSON}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  renameSync(tmp, OPENCODE_JSON);
+}
+
+async function probe(spec, apiKey) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 1500);
+  try {
+    const resp = await fetch(`${spec.baseURL}/models`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: ctrl.signal,
+    });
+    if (resp.ok) {
+      let modelCount = 0;
+      try {
+        const body = await resp.json();
+        if (Array.isArray(body?.data)) modelCount = body.data.length;
+        else if (Array.isArray(body)) modelCount = body.length;
+      } catch { /* ignore */ }
+      return { ok: true, status: resp.status, modelCount };
+    }
+    return { ok: false, status: resp.status, reason: `HTTP ${resp.status}` };
+  } catch (err) {
+    return { ok: false, reason: err?.name === 'AbortError' ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function detect({ probe: doProbe }) {
+  const cfg = loadOpencodeConfig();
+  const out = [];
+  for (const spec of KNOWN_PROVIDERS) {
+    let apiKey = '';
+    let keySource = '';
+    const cfgProvider = cfg.provider?.[spec.id];
+    if (cfgProvider?.apiKey) {
+      apiKey = cfgProvider.apiKey;
+      keySource = 'config';
+    } else if (cfgProvider?.options?.apiKey) {
+      apiKey = cfgProvider.options.apiKey;
+      keySource = 'config';
+    }
+    for (const k of spec.envKeys) {
+      const v = process.env[k];
+      if (typeof v === 'string' && v.length > 0) {
+        apiKey = v;
+        keySource = 'env';
+        break;
+      }
+    }
+    let status;
+    if (!apiKey) {
+      status = 'no-key';
+    } else if (spec.keyPattern && !spec.keyPattern.test(apiKey)) {
+      status = 'unknown';
+    } else {
+      status = 'configured';
+    }
+    let probed = null;
+    if (doProbe && status === 'configured') {
+      probed = await probe(spec, apiKey);
+      if (!probed.ok && probed.status) status = 'unknown';
+    }
+    out.push({
+      id: spec.id,
+      name: spec.name,
+      baseURL: spec.baseURL,
+      status,
+      keySource,
+      hasKey: !!apiKey,
+      probed,
+    });
+  }
+  return out;
+}
+
+function printTable(results) {
+  const pad = (s, n) => String(s).padEnd(n);
+  const idW = Math.max(2, ...results.map((r) => r.id.length));
+  const nameW = Math.max(4, ...results.map((r) => r.name.length));
+  const statusW = Math.max(6, ...results.map((r) => r.status.length));
+  const sourceW = Math.max(6, ...results.map((r) => r.keySource.length || 1));
+  console.log();
+  console.log(chalk.bold(`  ${pad('ID', idW)}  ${pad('NAME', nameW)}  ${pad('STATUS', statusW)}  ${pad('SOURCE', sourceW)}  PROBE`));
+  console.log(chalk.dim(`  ${'-'.repeat(idW)}  ${'-'.repeat(nameW)}  ${'-'.repeat(statusW)}  ${'-'.repeat(sourceW)}  ${'-'.repeat(20)}`));
+  for (const r of results) {
+    const id = pad(r.id, idW);
+    const name = pad(r.name, nameW);
+    const status = pad(r.status, statusW);
+    const source = pad(r.keySource || '-', sourceW);
+    const statusColored =
+      r.status === 'configured' ? chalk.green(status) :
+      r.status === 'unknown' ? chalk.yellow(status) :
+      chalk.dim(status);
+    const probeTxt = r.probed
+      ? (r.probed.modelCount != null ? chalk.green(`${r.probed.modelCount} models`) : chalk.dim(r.probed.reason || 'ok'))
+      : chalk.dim('-');
+    console.log(`  ${id}  ${name}  ${statusColored}  ${pad(source, sourceW)}  ${probeTxt}`);
+  }
+  console.log();
+  const configured = results.filter((r) => r.status === 'configured').length;
+  const unknown = results.filter((r) => r.status === 'unknown').length;
+  const noKey = results.filter((r) => r.status === 'no-key').length;
+  console.log(chalk.bold(`  ${configured} configured, ${unknown} unknown, ${noKey} no-key`));
+  console.log();
+}
+
+function installProvider(id) {
+  const spec = KNOWN_PROVIDERS.find((s) => s.id === id);
+  if (!spec) {
+    console.error(chalk.red(`  ✗ unknown provider: ${id}`));
+    console.error(chalk.dim(`    Available: ${KNOWN_PROVIDERS.map((s) => s.id).join(', ')}`));
+    process.exit(1);
+  }
+  // Get the apiKey from env or config
+  let apiKey = '';
+  for (const k of spec.envKeys) {
+    const v = process.env[k];
+    if (typeof v === 'string' && v.length > 0) {
+      apiKey = v;
+      break;
+    }
+  }
+  if (!apiKey) {
+    console.error(chalk.red(`  ✗ no API key found in env (${spec.envKeys.join(', ')})`));
+    process.exit(1);
+  }
+  const cfg = loadOpencodeConfig();
+  cfg.provider = cfg.provider || {};
+  cfg.provider[spec.id] = {
+    name: spec.name,
+    baseURL: spec.baseURL,
+    apiKey,
+    enabled: true,
+  };
+  saveOpencodeConfig(cfg);
+  console.log(chalk.green(`  ✓ ${spec.name} (${spec.id}) added to opencode.json`));
+}
+
+function showHelp() {
+  console.log(`
+  ${chalk.bold('bizar providers detect')} — auto-detect provider API keys
+
+  Usage:
+    bizar providers detect                  Probe env + opencode.json, print table
+    bizar providers detect --no-probe       Skip the /models probe
+    bizar providers detect --json           Print JSON instead of a table
+    bizar providers detect --install <id>   Add a configured provider to opencode.json
+
+  Recognised env vars:
+    ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY,
+    MISTRAL_API_KEY, GROQ_API_KEY, COHERE_API_KEY, OPENROUTER_API_KEY,
+    DEEPSEEK_API_KEY, MINIMAX_API_KEY
+`);
+}
+
+export async function runProvidersDetect(args) {
+  const doProbe = !args.includes('--no-probe');
+  const json = args.includes('--json');
+  const help = args.includes('--help') || args.includes('-h');
+
+  if (help) {
+    showHelp();
+    return;
+  }
+
+  const installIdx = args.indexOf('--install');
+  const installId = installIdx >= 0 ? args[installIdx + 1] : null;
+  if (installId) {
+    installProvider(installId);
+    return;
+  }
+
+  const results = await detect({ probe: doProbe });
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  console.log(chalk.bold.cyan('\n  Provider auto-detect\n'));
+  console.log(chalk.dim(`  Probing ${KNOWN_PROVIDERS.length} providers...`));
+  printTable(results);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness.",
   "type": "module",
   "bin": {

package/cli/graph-build-from-cache.mjs

@@ -1,124 +0,0 @@
-#!/usr/bin/env node
-/**
- * cli/graph-build-from-cache.mjs
- *
- * One-off script for environments where graphify's semantic-extraction
- * step fails (e.g. no LLM API key + remaining non-code docs that the
- * `.graphifyignore` can't filter) but the AST cache is intact.
- *
- * graphify's pipeline has two stages:
- *   1. AST extraction (local, tree-sitter) — writes per-file JSON to
- *      `.bizar/graph/cache/ast/v0.8.46/<hash>.json` regardless of LLM status.
- *   2. Semantic extraction (LLM, optional) — merges per-file nodes into a
- *      project-wide graph.
- *
- * If stage 2 aborts, `graph.json` is never written and the dashboard has
- * nothing to render. This script reconstructs `graph.json` directly from
- * the per-file AST cache, then calls `graphify cluster-only` to generate
- * `graph.html` + `GRAPH_REPORT.md`.
- *
- * Usage:
- *   node cli/graph-build-from-cache.mjs                 # use .bizar/graph/
- *   node cli/graph-build-from-cache.mjs /tmp/other/graph # custom dir
- */
-
-import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-const graphDirArg = process.argv[2] || '.bizar/graph';
-const graphDir = resolve(graphDirArg);
-
-// The cache version directory inside graphify's cache layout. Bumping the
-// graphify version moves the cache; we discover the actual subdir at
-// runtime so we don't hardcode "v0.8.46".
-const cacheAstRoot = join(graphDir, 'cache', 'ast');
-
-function findCacheDir() {
-  if (!existsSync(cacheAstRoot)) {
-    throw new Error(`No AST cache found at ${cacheAstRoot}. Run \`bizar graph build\` first to populate it.`);
-  }
-  const entries = readdirSync(cacheAstRoot);
-  if (entries.length === 0) {
-    throw new Error(`AST cache directory ${cacheAstRoot} is empty.`);
-  }
-  // graphify uses one version directory like v0.8.46. Pick the first.
-  return join(cacheAstRoot, entries[0]);
-}
-
-function buildGraphFromCache(cacheDir) {
-  const files = readdirSync(cacheDir).filter((f) => f.endsWith('.json'));
-  console.log(`  Reading ${files.length} AST cache files from ${cacheDir}...`);
-
-  const nodesById = new Map();
-  const edges = [];
-  const rawCalls = [];
-
-  let fileIdx = 0;
-  for (const f of files) {
-    fileIdx++;
-    const raw = JSON.parse(readFileSync(join(cacheDir, f), 'utf8'));
-    for (const n of raw.nodes || []) {
-      // Later files win on duplicate id (consistent with graphify's
-      // dedup behavior — first write keeps the canonical location).
-      if (!nodesById.has(n.id)) nodesById.set(n.id, n);
-    }
-    for (const e of raw.edges || []) edges.push(e);
-    for (const rc of raw.raw_calls || []) rawCalls.push(rc);
-    if (fileIdx % 50 === 0) {
-      console.log(`    merged ${fileIdx}/${files.length} files`);
-    }
-  }
-
-  // Re-key node.community so it matches the dashboard's expected schema.
-  // The AST cache uses `community` as a numeric cluster id; we keep it as-is.
-  const nodes = Array.from(nodesById.values());
-
-  const graph = {
-    directed: false,
-    multigraph: false,
-    graph: {},
-    nodes,
-    links: edges,
-  };
-
-  console.log(`  Built graph: ${nodes.length} nodes, ${edges.length} edges (raw_calls=${rawCalls.length})`);
-  return { graph, rawCalls };
-}
-
-function writeOutputs(graphDir, graph) {
-  // graph.json — NetworkX node-link format
-  const graphJsonPath = join(graphDir, 'graph.json');
-  writeFileSync(graphJsonPath, JSON.stringify(graph, null, 2), 'utf8');
-  console.log(`  ✓ Wrote ${graphJsonPath}`);
-
-  // .graphify_analysis.json — graphify's secondary output. cluster-only
-  // doesn't strictly require this, but writing it keeps the directory
-  // shape consistent with what `graphify .` would have produced.
-  const analysis = {
-    schema_version: 1,
-    generated_at: new Date().toISOString(),
-    clusters: [],
-  };
-  const analysisPath = join(graphDir, '.graphify_analysis.json');
-  writeFileSync(analysisPath, JSON.stringify(analysis, null, 2), 'utf8');
-  console.log(`  ✓ Wrote ${analysisPath}`);
-}
-
-function main() {
-  console.log(`  Graph dir: ${graphDir}`);
-  if (!existsSync(graphDir)) {
-    throw new Error(`Graph dir does not exist: ${graphDir}`);
-  }
-  const cacheDir = findCacheDir();
-  const { graph } = buildGraphFromCache(cacheDir);
-  writeOutputs(graphDir, graph);
-  console.log('');
-  console.log('  Next step: run `bizar graph cluster-only` to generate graph.html.');
-}
-
-try {
-  main();
-} catch (err) {
-  console.error(`\n  Error: ${err.message}\n`);
-  process.exit(1);
-}

package/cli/graph.mjs

@@ -1,642 +0,0 @@
-/**
- * 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, copyFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-export const GRAPH_DIR = '.bizar/graph';
-export const GRAPHIFY_OUT_ENV = 'GRAPHIFY_OUT';
-
-/**
- * Env vars graphify recognises for semantic extraction of docs/papers/images.
- * If NONE of these are set, graphify refuses to run on a corpus that contains
- * any non-code file ("A code-only corpus needs no key."). We auto-detect this
- * and write a comprehensive .graphifyignore so a fresh checkout can build
- * the graph offline with no LLM key.
- */
-const GRAPHIFY_LLM_KEY_ENVS = [
-  'GEMINI_API_KEY', 'GOOGLE_API_KEY',
-  'MOONSHOT_API_KEY',
-  'ANTHROPIC_API_KEY',
-  'OPENAI_API_KEY',
-  'DEEPSEEK_API_KEY',
-  'AZURE_OPENAI_API_KEY',
-];
-
-/**
- * Minimal .graphifyignore that restricts graphify to code-only extraction.
- * Written automatically by `bizar graph build` when no LLM key is set.
- * The user can override this file with their own .graphifyignore — we
- * never overwrite a pre-existing one.
- */
-const CODE_ONLY_GRAPHIFYIGNORE = [
-  '# Auto-generated by `bizar graph build` — code-only mode.',
-  '# Bizar detected no LLM key, so docs/papers/images cannot be semantically',
-  '# extracted. We restrict extraction to code files (processed locally via',
-  "# tree-sitter — no API key needed). Delete this file and re-run once you've",
-  '# set one of: GEMINI_API_KEY, GOOGLE_API_KEY, MOONSHOT_API_KEY,',
-  '# ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, AZURE_OPENAI_API_KEY.',
-  '',
-  '# Heavy / vendored dirs to skip entirely',
-  'node_modules/',
-  '.git/',
-  '.bizar/',
-  '.agents/',
-  'dist/',
-  'build/',
-  'coverage/',
-  '',
-  '# Agent system prompts — they\'re Markdown but contain YAML frontmatter',
-  '# + system instructions, not project documentation. They\'re noise for',
-  '# a structural graph and would balloon the doc count to ~1100.',
-  'config/agents/',
-  '',
-  '# Non-code file types — graphify would need an LLM for these',
-  '*.md',
-  '*.mdx',
-  '*.qmd',
-  '*.html',
-  '*.txt',
-  '*.rst',
-  '*.pdf',
-  '*.png',
-  '*.jpg',
-  '*.jpeg',
-  '*.webp',
-  '*.gif',
-  '*.mp4',
-  '*.mov',
-  '*.mp3',
-  '*.wav',
-  '',
-].join('\n');
-
-/**
- * Detect whether any graphify-recognised LLM API key is set in the
- * current process env. Used by `cmdBuild` to decide whether to write
- * the code-only .graphifyignore.
- */
-function hasLlmKey(env = process.env) {
-  return GRAPHIFY_LLM_KEY_ENVS.some((k) => {
-    const v = env[k];
-    return typeof v === 'string' && v.trim().length > 0;
-  });
-}
-
-// ── Python detection ───────────────────────────────────────────────────────────
-
-/**
- * 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() {
-  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')) {
-        return name;
-      }
-    } catch {
-      // try next
-    }
-  }
-  return null;
-}
-
-/**
- * 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',
-      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.
- *
- * Resolution order:
- *   1. If the `graphify` binary is on PATH (the uv-tool shim), invoke it
- *      directly. This is what `checkGraphify` already verified — we don't
- *      need to know about its venv.
- *   2. Otherwise fall back to `python -m graphify` for pip/pipx installs.
- */
-function runGraphify(python, subArgs, extraEnv = {}) {
-  const env = { ...process.env, [GRAPHIFY_OUT_ENV]: GRAPH_DIR, ...extraEnv };
-  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
-  let bin = null;
-  try {
-    const r = spawnSync(whichCmd, ['graphify'], { encoding: 'utf8', timeout: 5000 });
-    if (r.status === 0 && (r.stdout || '').trim().length > 0) {
-      bin = 'graphify';
-    }
-  } catch {
-    // ignore — fall through to python -m
-  }
-
-  if (bin) {
-    const result = spawnSync(bin, subArgs, {
-      stdio: 'inherit',
-      env,
-      timeout: 0, // no timeout — user may run long builds
-    });
-    return result.status ?? 1;
-  }
-
-  const result = spawnSync(python, ['-m', 'graphify', ...subArgs], {
-    stdio: 'inherit',
-    env,
-    timeout: 0,
-  });
-  return result.status ?? 1;
-}
-
-// ── Subcommand handlers ────────────────────────────────────────────────────────
-
-async function cmdBuild(python) {
-  // If no LLM key is set, fall back to a code-only build by writing a
-  // comprehensive .graphifyignore. We never overwrite a user-provided
-  // .graphifyignore — only create the file when it doesn't exist.
-  let llmKeyPresent = hasLlmKey();
-  if (!llmKeyPresent) {
-    const ignorePath = '.graphifyignore';
-    if (!existsSync(ignorePath)) {
-      writeFileSync(ignorePath, CODE_ONLY_GRAPHIFYIGNORE, 'utf8');
-      console.log(chalk.dim('  No LLM API key detected — switching to code-only build.'));
-      console.log(chalk.dim(`  Wrote ${ignorePath} restricting extraction to code files.`));
-      console.log(chalk.dim('  Set GEMINI_API_KEY / OPENAI_API_KEY / etc. and re-run for full docs extraction.\n'));
-    } else {
-      console.log(chalk.dim('  No LLM API key detected — using existing .graphifyignore for code-only build.\n'));
-    }
-  }
-
-  console.log(chalk.dim('  Running full graphify pipeline...'));
-  let code = runGraphify(python, ['.']);
-
-  // Offline code-only fallback — when no LLM key is set, graphify's
-  // pre-flight check rejects the build before it can write any output.
-  // Even with a dummy key set, the semantic step fails for any non-code
-  // docs that escaped the .graphifyignore filter, and graphify refuses
-  // to write graph.json. To unblock this case we:
-  //   1. Run graphify with a dummy ANTHROPIC_API_KEY so the AST cache
-  //      gets populated (semantic extraction will fail, that's fine).
-  //   2. Reconstruct graph.json from the per-file AST cache.
-  //   3. Run cluster-only to generate graph.html + GRAPH_REPORT.md.
-  if (code !== 0 && !llmKeyPresent) {
-    const cacheAstRoot = join(GRAPH_DIR, 'cache', 'ast');
-    const cacheIsPopulated = existsSync(cacheAstRoot) && (
-      // graphify creates a versioned subdir on first extract.
-      // Check if any version dir contains JSON files.
-      (await import('node:fs/promises'))
-        .readdir(cacheAstRoot, { withFileTypes: true })
-        .then((entries) =>
-          entries.some(async (e) => {
-            if (!e.isDirectory()) return false;
-            const files = await (await import('node:fs/promises')).readdir(join(cacheAstRoot, e.name));
-            return files.some((f) => f.endsWith('.json'));
-          }),
-        )
-        .catch(() => false)
-    );
-
-    if (!cacheIsPopulated) {
-      console.log(chalk.yellow('  ⚠ No AST cache yet. Running graphify with a dummy key to populate the cache (semantic extraction will fail; that\'s OK)...'));
-      // Set a dummy key so graphify gets past its pre-flight check and
-      // populates the AST cache. We invoke the graphify binary directly
-      // (the user's python3 -m graphify may not have graphify installed;
-      // uv-tool installs put a shim at ~/.local/bin/graphify).
-      const dummyRes = spawnSync('graphify', ['.'], {
-        stdio: 'inherit',
-        env: { ...process.env, ANTHROPIC_API_KEY: 'sk-bizar-graph-dummy', GRAPHIFY_OUT: GRAPH_DIR },
-        timeout: 0,
-      });
-      void dummyRes; // exit code doesn't matter — we want the cache, not the merge
-    }
-
-    const cacheStillEmpty = !(await (async () => {
-      try {
-        const e = await (await import('node:fs/promises')).readdir(cacheAstRoot, { withFileTypes: true });
-        for (const d of e) {
-          if (!d.isDirectory()) continue;
-          const f = await (await import('node:fs/promises')).readdir(join(cacheAstRoot, d.name));
-          if (f.some((x) => x.endsWith('.json'))) return true;
-        }
-        return false;
-      } catch {
-        return false;
-      }
-    })());
-
-    if (!cacheStillEmpty) {
-      console.log(chalk.yellow('  ⚠ graphify exited non-zero. Falling back to AST-cache build...'));
-      const fb = runCacheFallbackBuild();
-      if (fb === 0) code = 0;
-    }
-  }
-
-  if (code === 0) {
-    ensureGitignore(GRAPH_DIR);
-    // After extract, run cluster-only to write graph.html + GRAPH_REPORT.md
-    // (extract only writes graph.json; cluster-only adds viz + report).
-    const graphJson = join(GRAPH_DIR, 'graph.json');
-    if (existsSync(graphJson)) {
-      console.log(chalk.dim('  Generating graph.html + GRAPH_REPORT.md via cluster-only...'));
-      // Pass "." as the cluster-only path so it writes graph.html +
-      // GRAPH_REPORT.md to the current directory's graphify-out/.
-      // (Passing `.bizar/graph` directly nests the output as
-      // `.bizar/graph/.bizar/graph/...` which is wrong.) The explicit
-      // --graph overrides the auto-discovery to find graph.json.
-      const clusterArgs = ['cluster-only', '.', '--graph', graphJson];
-      const clusterCode = runGraphify(python, clusterArgs);
-      if (clusterCode !== 0) {
-        console.log(chalk.yellow(`  ⚠ cluster-only returned ${clusterCode} — graph.json was built but graph.html may be stale.`));
-      } else {
-        // cluster-only writes to ./graphify-out/ (relative to CWD).
-        // Promote the artifacts up to .bizar/graph/ paths the dashboard
-        // serves directly.
-        const out = join(GRAPH_DIR, 'graphify-out');
-        if (!existsSync(out)) {
-          // Fallback: graphify may have written to ./graphify-out/ at CWD.
-          const cwdOut = join(process.cwd(), 'graphify-out');
-          if (existsSync(cwdOut)) {
-            promoteFromDir(cwdOut, GRAPH_DIR);
-          }
-        } else {
-          promoteClusterOutputs(GRAPH_DIR);
-        }
-      }
-    }
-    console.log(chalk.green(`\n  ✓ Graph built → ${GRAPH_DIR}/\n`));
-  }
-  return code;
-}
-
-/**
- * Reconstruct graph.json from graphify's per-file AST cache and run
- * cluster-only to produce graph.html + GRAPH_REPORT.md. Used when the
- * full graphify pipeline fails because some docs need an LLM that we
- * don't have, but the AST cache for code-only files was successfully
- * extracted.
- *
- * Returns the exit code of the overall sequence (0 on success).
- */
-function runCacheFallbackBuild() {
-  // Step 1: merge the per-file AST cache into a single graph.json.
-  const scriptPath = new URL(import.meta.url).pathname;
-  // cli/graph.mjs sits next to cli/graph-build-from-cache.mjs.
-  const cacheScript = scriptPath.replace(/graph\.mjs$/, 'graph-build-from-cache.mjs');
-  if (!existsSync(cacheScript)) {
-    console.log(chalk.red(`  ✗ Cache fallback script not found at ${cacheScript}`));
-    return 1;
-  }
-  const buildRes = spawnSync(process.execPath, [cacheScript, GRAPH_DIR], {
-    stdio: 'inherit',
-  });
-  if (buildRes.status !== 0) {
-    return buildRes.status ?? 1;
-  }
-  // Step 2: cluster-only regenerates graph.html from the merged graph.json.
-  return 0;
-}
-
-/**
- * Copy the named files from `srcDir` up to `dstDir`. Used to hoist
- * cluster-only's graph.html / GRAPH_REPORT.md / graph.json up to the
- * canonical .bizar/graph/ paths the dashboard serves.
- */
-function promoteFromDir(srcDir, dstDir) {
-  for (const name of ['graph.html', 'GRAPH_REPORT.md', 'graph.json']) {
-    const src = join(srcDir, name);
-    const dst = join(dstDir, name);
-    if (existsSync(src)) {
-      copyFileSync(src, dst);
-    }
-  }
-}
-
-/**
- * cluster-only writes its outputs to a nested graphify-out/ directory
- * by default. This hoists them up to the standard paths the dashboard
- * serves (.bizar/graph/graph.html + .bizar/graph/GRAPH_REPORT.md).
- */
-function promoteClusterOutputs(graphDir) {
-  const out = join(graphDir, 'graphify-out');
-  if (existsSync(out)) promoteFromDir(out, graphDir);
-}
-
-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;
-  }
-
-  // Prefer uv (handles PEP 668 isolated installs cleanly); fall back to pip.
-  const { detectUv } = await import('./utils.mjs');
-  const hasUv = await detectUv();
-
-  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'));
-  const 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

@@ -1,218 +0,0 @@
-/**
- * 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');