@polderlabs/bizar 4.5.1 → 4.7.0

package/cli/commands/util.mjs

@@ -0,0 +1,306 @@
+/**
+ * cli/commands/util.mjs
+ *
+ * Miscellaneous utility commands:
+ *   audit, init, export, test-gate, dev-link, dev-unlink,
+ *   doctor, repair, heads-up, bg, browser-harness-up, providers detect
+ */
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// ── Help texts ──────────────────────────────────────────────────────────────────
+
+export function showAuditHelp() {
+  console.log(`
+  bizar audit — Run security audit on agent configuration
+
+  Usage:
+    bizar audit
+  `);
+}
+
+export function showInitHelp() {
+  console.log(`
+  bizar init — Initialize .bizar/ in current project
+
+  Usage:
+    bizar init
+
+  Description:
+    Detects the project stack, creates .bizar/PROJECT.md and
+    .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.
+  `);
+}
+
+export function showExportHelp() {
+  console.log(`
+  bizar export — Export agents/rules to another harness
+
+  Usage:
+    bizar export [claude|cursor|opencode]
+
+  Description:
+    Copies installed Bizar agents and rules into another harness format.
+  `);
+}
+
+export function showTestGateHelp() {
+  console.log(`
+  bizar test-gate — Detect & run the project's test suite
+  `);
+}
+
+export function showDevLinkHelp() {
+  console.log(`
+  bizar dev-link / dev-unlink — Manage a symlink from the opencode plugin dir
+  to a local source checkout, so edits propagate to opencode on next session.
+
+  Usage:
+    bizar dev-link [source-dir]    Symlink source-dir (default: ./plugins/bizar)
+                                   to ~/.config/opencode/plugins/bizar
+    bizar dev-link --force         Replace an existing deployed copy
+    bizar dev-unlink               Remove the dev symlink + restore from npm
+    bizar dev-unlink --force       Remove even if not a symlink (destructive)
+
+  Description:
+    By default, opencode loads the Bizar plugin from
+    ~/.config/opencode/plugins/bizar, which is a real directory copied
+    from the npm package. Edits to plugins/bizar/ in the BizarHarness
+    repo don't propagate until you re-run the installer.
+
+    \`bizar dev-link\` replaces that directory with a symlink pointing
+    at your local checkout, so source edits are picked up immediately.
+    \`bizar dev-unlink\` reverses the change by removing the symlink
+    and re-installing the deployed copy from the npm package.
+
+    While the dev link is in place, \`bizar update\` will skip the
+    plugin-copy step (and print a warning) so it doesn't clobber the
+    link. Run \`bizar dev-unlink\` first, or pass --force to overwrite.
+
+  Examples:
+    bizar dev-link
+    bizar dev-link /home/me/projects/bizar/plugins/bizar
+    bizar dev-link --force
+    bizar dev-unlink
+  `);
+}
+
+export function showDoctorHelp() {
+  console.log(`
+  bizar doctor — Check the BizarHarness install for health issues
+
+  Usage:
+    bizar doctor
+
+  Description:
+    Runs a battery of health checks against the local install:
+      • opencode CLI reachable
+      • ~/.config/opencode/opencode.json parses as JSON
+      • the Bizar plugin is registered
+      • plugin path resolves
+      • @polderlabs/bizar-plugin is installed globally
+      • core agent files are installed (odin, quick, thor, tyr)
+      • headroom / semble / skills on PATH (lenient — at least one)
+      • dashboard reachable (skipped if no port file)
+      • provider.minimax block + MiniMax model flags are sane
+
+    Prints ✓/✗ for each check and a final summary. Exits non-zero
+    if any check fails. Use \`bizar doctor\` after a manual config
+    edit or to diagnose "why is opencode misbehaving?" questions.
+
+  Related:
+    bizar update              Update + auto-run doctor on success
+  `);
+}
+
+export function showRepairHelp() {
+  console.log(`
+  bizar repair — Fix common install issues
+
+  Usage:
+    bizar repair                Diagnose + fix stale bin symlinks and mismatched versions
+    bizar repair --dry-run      Show what would change without modifying anything
+    bizar repair --bin-only     Only fix the bin symlink; skip version checks
+  `);
+}
+
+// ── Test gate ──────────────────────────────────────────────────────────────────
+
+export async function runTestGate() {
+  console.log(chalk.bold.hex('#a855f7')('\n  ᚦ TEST GATE ᚦ\n'));
+  const { execSync } = await import('node:child_process');
+  const cwd = process.cwd();
+  const possible = [
+    { cmd: 'npm test', check: 'package.json' },
+    { cmd: 'pytest', check: 'pyproject.toml' },
+    { cmd: 'cargo test', check: 'Cargo.toml' },
+    { cmd: 'go test ./...', check: 'go.mod' },
+  ];
+  for (const suite of possible) {
+    try {
+      if (existsSync(join(cwd, suite.check))) {
+        console.log(`  Running: ${suite.cmd}`);
+        execSync(suite.cmd, { stdio: 'inherit', timeout: 120000, cwd });
+        console.log('\n  ✓ Test gate passed\n');
+        return true;
+      }
+    } catch {
+      console.log(`\n  ✗ Test gate failed: ${suite.cmd}\n`);
+      process.exit(1);
+    }
+  }
+  console.log('  No test suite detected. Install one to use the test gate.\n');
+  return false;
+}
+
+// ── Main dispatcher ────────────────────────────────────────────────────────────
+
+export async function run(name, args, isHelpRequest) {
+  switch (name) {
+    case 'audit':
+      if (isHelpRequest) showAuditHelp();
+      else {
+        const { runAudit } = await import('../audit.mjs');
+        await runAudit();
+      }
+      break;
+
+    case 'init':
+      if (isHelpRequest) showInitHelp();
+      else {
+        const { runInit } = await import('../init.mjs');
+        await runInit(process.cwd());
+      }
+      break;
+
+    case 'export':
+      if (isHelpRequest) showExportHelp();
+      else {
+        const { runExport } = await import('../export.mjs');
+        const targetFlag = args.includes('--target') ? args[args.indexOf('--target') + 1] : null;
+        await runExport(targetFlag);
+      }
+      break;
+
+    case 'test-gate':
+      if (isHelpRequest) showTestGateHelp();
+      else await runTestGate();
+      break;
+
+    case 'dev-link':
+      if (isHelpRequest) showDevLinkHelp();
+      else {
+        const { createDevLink } = await import('../dev-link.mjs');
+        const positional = args.filter((a) => !a.startsWith('-'));
+        const flags = args.filter((a) => a.startsWith('-'));
+        const sourceDir = positional[0] ?? null;
+        const force = flags.includes('--force') || flags.includes('-f');
+        const ok = createDevLink(sourceDir, { force });
+        if (!ok) process.exit(1);
+      }
+      break;
+
+    case 'dev-unlink':
+      if (isHelpRequest) showDevLinkHelp();
+      else {
+        const { removeDevLink } = await import('../dev-link.mjs');
+        const force = args.includes('--force') || args.includes('-f');
+        const ok = await removeDevLink({ force });
+        if (!ok) process.exit(1);
+      }
+      break;
+
+    case 'doctor':
+      if (isHelpRequest) showDoctorHelp();
+      else {
+        const { runDoctor } = await import('../doctor.mjs');
+        const wantJson = args.includes('--json');
+        const result = await runDoctor({ silent: wantJson, json: wantJson });
+        if (wantJson) process.stdout.write(JSON.stringify(result) + '\n');
+        if (result.failed > 0) process.exit(1);
+      }
+      break;
+
+    case 'repair':
+      if (isHelpRequest) showRepairHelp();
+      else {
+        const { runRepair } = await import('../repair.mjs');
+        const dryRun = args.includes('--dry-run');
+        const binOnly = args.includes('--bin-only');
+        const result = await runRepair({ dryRun, binOnly });
+        if (!result.ok) {
+          for (const n of result.notes) console.log(`  ${n}`);
+          process.exit(1);
+        }
+        for (const n of result.notes) console.log(`  ${n}`);
+        if (result.fixed.length > 0) {
+          console.log(chalk.green('\n  Repair complete. Re-run your shell or `hash -r` to pick up the new path.'));
+        }
+      }
+      break;
+
+    case 'heads-up':
+      if (isHelpRequest) {
+        console.log('  heads-up <subcommand>   Manage pre-push / pre-release heads-ups (list/check/archive)');
+      } else {
+        const { runHeadsUp } = await import('../heads-up.mjs');
+        await runHeadsUp(args[0], args.slice(1));
+      }
+      break;
+
+    case 'bg':
+      if (isHelpRequest) {
+        console.log('  bg <subcommand>   Manage background agents (list/view/kill/logs)');
+      } else {
+        const { runBg } = await import('../bg.mjs');
+        await runBg(args[0], args.slice(1));
+      }
+      break;
+
+    case 'browser-harness-up': {
+      const { execFileSync } = await import('node:child_process');
+      const sub = args[0] || 'start';
+      const __dirname = fileURLToPath(new URL('.', import.meta.url));
+      const scriptPath = join(__dirname, '..', 'browser-harness-up.sh');
+      try {
+        const out = execFileSync('bash', [scriptPath, sub], {
+          encoding: 'utf8',
+          stdio: 'inherit',
+        });
+        if (out) process.stdout.write(out);
+      } catch (err) {
+        console.error(chalk.red(`  ✗ browser-harness-up ${sub} failed (exit ${err.status ?? 1})`));
+        process.exit(err.status || 1);
+      }
+      break;
+    }
+
+    case 'providers':
+      if (args[0] === 'detect') {
+        const { runProvidersDetect } = await import('../providers-detect.mjs');
+        await runProvidersDetect(args.slice(1));
+      }
+      break;
+
+    case 'plan':
+      // Alias for artifact
+      if (isHelpRequest) {
+        const { showHelp } = await import('../artifact-cli.mjs');
+        showHelp();
+      } else {
+        const { runArtifact } = await import('../artifact-cli.mjs');
+        await runArtifact(args, {});
+      }
+      break;
+
+    default:
+      return false;
+  }
+  return true;
+}

package/cli/doctor.mjs

@@ -21,9 +21,8 @@
 import chalk from 'chalk';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { opencodeConfigDir, opencodeAgentsDir } from './utils.mjs';
+import { opencodeConfigDir, opencodeAgentsDir, which, bizarConfigDir } from './utils.mjs';
 
 // v3.20.11: list every agent the install script is expected to deploy.
 // Adding a new agent to `config/agents/` without adding it here causes
@@ -50,12 +49,6 @@ const REQUIRED_AGENTS = [
 
 // ── helpers ─────────────────────────────────────────────────────────────────
 
-function bizarConfigDir() {
-  return process.env.XDG_CONFIG_HOME
-    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
-    : join(homedir(), '.config', 'bizar');
-}
-
 /**
  * Run a check function and capture its result. The check either
  * returns a string message (pass) or throws an Error (fail).
@@ -73,11 +66,6 @@ async function runCheck(name, fn) {
   }
 }
 
-function which(cmd) {
-  const probe = spawnSync('which', [cmd], { stdio: 'ignore' });
-  return probe.status === 0;
-}
-
 // ── individual checks ───────────────────────────────────────────────────────
 
 async function checkOpencodeReachable() {
@@ -269,10 +257,12 @@ const CHECKS = [
 
 /**
  * Run all health checks. Prints per-check output unless `opts.silent`.
- * Always prints a final summary line. Returns `{ passed, failed, results }`.
+ * Prints a final summary line unless `opts.json` is true.
+ * Returns `{ passed, failed, results }`.
  */
 export async function runDoctor(opts = {}) {
   const silent = !!opts.silent;
+  const jsonMode = !!opts.json;
   const results = [];
   for (const [name, fn] of CHECKS) {
     const r = await runCheck(name, fn);
@@ -288,8 +278,8 @@ export async function runDoctor(opts = {}) {
   const passed = results.filter((r) => r.ok).length;
   const failed = results.length - passed;
 
-  // Always print a summary line if there were failures, or if not silent.
-  if (failed > 0 || !silent) {
+  // Print summary line only when not in JSON mode
+  if (!jsonMode && (failed > 0 || !silent)) {
     console.log('');
     if (failed === 0) {
       console.log(

package/cli/memory.mjs

@@ -755,7 +755,8 @@ function printSetupResult({ mode, remote, vaultPath }) {
 /**
  * `bizar memory status`
  */
-async function cmdStatus(_args) {
+async function cmdStatus(_args, opts = {}) {
+  const { wantJson = false } = opts;
   const projectRoot = getProjectRoot();
   const { loadConfig, resolveVault, initVault, listNotes } = memoryStore;
   const { isGitInstalled, status: gitStatus } = memoryGit;
@@ -768,19 +769,15 @@ async function cmdStatus(_args) {
 
   const { vaultRoot, mode, projectId, branch } = resolveVault(projectRoot);
 
-  console.log(chalk.bold('\n  Bizar Memory Status'));
-  console.log('  ─────────────────────────────');
-  kv('mode', mode);
-  kv('projectId', projectId);
-  kv('vault', vaultRoot);
-  kv('branch', branch);
+  const out = { mode, projectId, vault: vaultRoot, branch };
 
   // Ensure vault exists
   if (!existsSync(vaultRoot)) {
-    warn(`vault directory does not exist — run \`bizar memory init\` or \`bizar memory sync\``);
+    out.vaultExists = false;
   } else {
+    out.vaultExists = true;
     const notes = listNotes(projectRoot);
-    kv('noteCount', String(notes.length));
+    out.noteCount = notes.length;
   }
 
   // Git status if managed
@@ -788,14 +785,14 @@ async function cmdStatus(_args) {
     if (isGitInstalled()) {
       const gs = gitStatus(vaultRoot);
       if (gs.ok) {
-        kv('git', `${gs.branch} (${gs.clean ? chalk.green('clean') : chalk.red('dirty')})`);
-        if (gs.ahead > 0) kv('ahead', String(gs.ahead));
-        if (gs.behind > 0) kv('behind', String(gs.behind));
+        out.git = { branch: gs.branch, clean: gs.clean };
+        if (gs.ahead > 0) out.git.ahead = gs.ahead;
+        if (gs.behind > 0) out.git.behind = gs.behind;
       } else {
-        kv('git', chalk.yellow(`not a git repo`));
+        out.git = { error: 'not a git repo' };
       }
     } else {
-      kv('git', chalk.yellow(`git not installed`));
+      out.git = { error: 'git not installed' };
     }
   }
 
@@ -804,15 +801,15 @@ async function cmdStatus(_args) {
     const { isLightRAGRunning, isLightRAGInstalled, resolveLightRAGConfig } = memoryStore;
     const cfg = resolveLightRAGConfig(projectRoot);
     if (!cfg.enabled) {
-      kv('lightrag', chalk.gray('disabled'));
+      out.lightrag = { enabled: false };
     } else if (!(await isLightRAGInstalled())) {
-      kv('lightrag', chalk.yellow('not installed — `uv tool install "lightrag-hku[api]"`'));
+      out.lightrag = { enabled: true, installed: false };
     } else {
       const running = await isLightRAGRunning(cfg);
-      kv('lightrag', running ? chalk.green(`${cfg.host}:${cfg.port} (running)`) : chalk.yellow(`${cfg.host}:${cfg.port} (not running — run \`bizar memory reindex\`)`));
+      out.lightrag = { enabled: true, installed: true, running, host: cfg.host, port: cfg.port };
     }
   } catch (err) {
-    kv('lightrag', chalk.gray(`status unavailable (${err.message})`));
+    out.lightrag = { error: err.message };
   }
 
   // Last reindex attempt
@@ -820,10 +817,55 @@ async function cmdStatus(_args) {
   if (existsSync(reindexMarker)) {
     try {
       const { finishedAt, ok, inserted, failed, noteCount } = JSON.parse(readFileSync(reindexMarker, 'utf8'));
-      kv('lastReindex', `${new Date(finishedAt).toLocaleString()} — ${ok ? chalk.green(`${inserted}/${noteCount} ok`) : chalk.red(`${failed} failed`)}`);
+      out.lastReindex = { finishedAt, ok, inserted, failed, noteCount };
     } catch { /* ignore */ }
   }
 
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(out) + '\n');
+    return;
+  }
+
+  console.log(chalk.bold('\n  Bizar Memory Status'));
+  console.log('  ─────────────────────────────');
+  kv('mode', mode);
+  kv('projectId', projectId);
+  kv('vault', vaultRoot);
+  kv('branch', branch);
+  if (!out.vaultExists) {
+    warn(`vault directory does not exist — run \`bizar memory init\` or \`bizar memory sync\``);
+  } else {
+    kv('noteCount', String(out.noteCount));
+  }
+  if (out.git) {
+    if (out.git.error) {
+      kv('git', chalk.yellow(out.git.error));
+    } else {
+      const cleanStr = out.git.clean ? chalk.green('clean') : chalk.red('dirty');
+      kv('git', `${out.git.branch} (${cleanStr})`);
+      if (out.git.ahead) kv('ahead', String(out.git.ahead));
+      if (out.git.behind) kv('behind', String(out.git.behind));
+    }
+  }
+  if (out.lightrag) {
+    if (out.lightrag.error) {
+      kv('lightrag', chalk.gray(`status unavailable (${out.lightrag.error})`));
+    } else if (!out.lightrag.enabled) {
+      kv('lightrag', chalk.gray('disabled'));
+    } else if (!out.lightrag.installed) {
+      kv('lightrag', chalk.yellow('not installed — `uv tool install "lightrag-hku[api]"`'));
+    } else {
+      const runningStr = out.lightrag.running
+        ? chalk.green(`${out.lightrag.host}:${out.lightrag.port} (running)`)
+        : chalk.yellow(`${out.lightrag.host}:${out.lightrag.port} (not running)`);
+      kv('lightrag', runningStr);
+    }
+  }
+  if (out.lastReindex) {
+    const lr = out.lastReindex;
+    const lrStr = `${new Date(lr.finishedAt).toLocaleString()} — ${lr.ok ? chalk.green(`${lr.inserted}/${lr.noteCount} ok`) : chalk.red(`${lr.failed} failed`)}`;
+    kv('lastReindex', lrStr);
+  }
   console.log();
 }
 
@@ -1606,8 +1648,10 @@ async function cmdDelete(args) {
 /**
  * @param {string} subcommand
  * @param {string[]} args
+ * @param {{ wantJson?: boolean }} opts
  */
-export async function runMemory(subcommand, args) {
+export async function runMemory(subcommand, args, opts = {}) {
+  const { wantJson = false } = opts;
   switch (subcommand) {
     case 'init':
       await cmdInit(args);
@@ -1616,7 +1660,7 @@ export async function runMemory(subcommand, args) {
       await cmdSetup(args);
       break;
     case 'status':
-      await cmdStatus(args);
+      await cmdStatus(args, { wantJson });
       break;
     case 'link':
       await cmdLink(args);

package/cli/provision.mjs

@@ -42,9 +42,11 @@ import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync, mkdirSync
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { bizarConfigDir } from './utils.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const HOME = homedir();
 
 // `cli/provision.mjs` lives at `<pkg>/cli/provision.mjs`. The repo root
 // (where `plugins/bizar/`, `bizar-dash/`, `package.json` etc. live) is
@@ -53,19 +55,6 @@ const __dirname = dirname(__filename);
 export const REPO_ROOT = join(__dirname, '..');
 export const PKG_MAIN = '@polderlabs/bizar';
 
-const HOME = homedir();
-
-function bizarConfigDir() {
-  if (process.platform === 'win32') {
-    return process.env.APPDATA
-      ? join(process.env.APPDATA, 'bizar')
-      : join(HOME, '.config', 'bizar');
-  }
-  return process.env.XDG_CONFIG_HOME
-    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
-    : join(HOME, '.config', 'bizar');
-}
-
 export const BIZAR_HOME = bizarConfigDir();
 export const OPENCODE_DIR =
   process.platform === 'win32'
@@ -446,7 +435,10 @@ export async function ensureNpmPackage(pkg, { mode, dryRun, force }) {
   // processes are reading files inside the npm-global install dir. We
   // can't replace those files atomically while they're open. The caller
   // is expected to have already killed them via ensureInstancesKilled().
-  const r = spawnSync('npm', ['install', '-g', `${pkg}@latest`], { stdio: 'inherit' });
+  const r = spawnSync('npm', ['install', '-g', `${pkg}@latest`], { stdio: 'inherit', timeout: 600000 });
+  if (r.status === null && r.error?.code === 'ETIMEDOUT') {
+    return { ok: false, message: `${pkg} install timed out after 10 minutes`, installed: current };
+  }
   if (r.status !== 0) {
     return { ok: false, message: `${pkg} install failed`, installed: current };
   }
@@ -471,7 +463,10 @@ export async function updateOpencodeCli({ dryRun, force }) {
     return { ok: true, message: 'opencode updated via `opencode upgrade`' };
   }
   console.log(chalk.dim('  opencode upgrade not available; falling back to npm'));
-  const r2 = spawnSync('npm', ['install', '-g', 'opencode-ai@latest'], { stdio: 'inherit' });
+  const r2 = spawnSync('npm', ['install', '-g', 'opencode-ai@latest'], { stdio: 'inherit', timeout: 600000 });
+  if (r2.status === null && r2.error?.code === 'ETIMEDOUT') {
+    return { ok: false, message: 'opencode install timed out after 10 minutes' };
+  }
   if (r2.status === 0) {
     return { ok: true, message: 'opencode updated via npm' };
   }

package/cli/service-controller.mjs

@@ -39,6 +39,7 @@ import {
 import { homedir, platform } from 'node:os';
 import { join, dirname, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { bizarConfigDir } from './utils.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -47,17 +48,6 @@ const PLATFORM = platform();
 
 // ── Path helpers ──────────────────────────────────────────────────────────────
 
-function bizarConfigDir() {
-  if (PLATFORM === 'win32') {
-    return process.env.APPDATA
-      ? join(process.env.APPDATA, 'bizar')
-      : join(HOME, '.config', 'bizar');
-  }
-  return process.env.XDG_CONFIG_HOME
-    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
-    : join(HOME, '.config', 'bizar');
-}
-
 function userUnitDir() {
   if (PLATFORM === 'win32') return null;
   return process.env.XDG_CONFIG_HOME

package/cli/service.mjs

@@ -35,22 +35,12 @@ import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import { bizarConfigDir } from './utils.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const HOME = homedir();
 
-function bizarConfigDir() {
-  if (process.platform === 'win32') {
-    return process.env.APPDATA
-      ? join(process.env.APPDATA, 'bizar')
-      : join(HOME, '.config', 'bizar');
-  }
-  return process.env.XDG_CONFIG_HOME
-    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
-    : join(HOME, '.config', 'bizar');
-}
-
 const BIZAR_HOME = bizarConfigDir();
 const LOG_FILE = join(BIZAR_HOME, 'service.log');
 const PID_FILE = join(BIZAR_HOME, 'service.pid');

package/cli/utils.mjs

@@ -1,8 +1,9 @@
 import { access, constants, readFile } from 'node:fs/promises';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync } from 'node:fs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const REPO_ROOT = join(__dirname, '..');
@@ -153,3 +154,42 @@ export function buildSummary(components, agents, target, skillPacks = []) {
     parts,
   };
 }
+
+// ── Path helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Return the platform-specific Bizar config directory.
+ * Windows: %APPDATA%\bizar
+ * Unix: $XDG_CONFIG_HOME/bizar (default: ~/.config/bizar)
+ */
+export function bizarConfigDir() {
+  if (process.platform === 'win32') {
+    return process.env.APPDATA
+      ? join(process.env.APPDATA, 'bizar')
+      : join(homedir(), '.config', 'bizar');
+  }
+  return process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : join(homedir(), '.config', 'bizar');
+}
+
+/**
+ * Check if a command exists on PATH.
+ * Returns true if found, false otherwise.
+ */
+export function which(cmd) {
+  const probe = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+/**
+ * Check if a command exists on PATH (bg.mjs variant that returns the path or null).
+ */
+export function whichPath(cmd) {
+  try {
+    const out = execFileSync('which', [cmd], { encoding: 'utf8' });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}