@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/cli/commands/validate.mjs

@@ -0,0 +1,541 @@
+/**
+ * cli/commands/validate.mjs
+ *
+ * v6.3.0 — `bizar validate` subcommand (Claude Code-native).
+ *
+ * The Claude Code-aware health check. Extends `bizar doctor` with a
+ * longer battery of checks specific to a "flawless Claude Code
+ * integration":
+ *
+ *   - `claude` CLI reachable + version
+ *   - `~/.claude/settings.json` exists + parses
+ *   - Bizar MCP server registered (mcpServers.bizar.*)
+ *   - Bizar plugin entry in MCP config
+ *   - 14 agent files in `~/.claude/agents/`
+ *   - 14 skills mirrored from `config/skills/` → `~/.claude/skills/`
+ *   - 7 rules mirrored from `config/rules/` → `~/.claude/rules/`
+ *   - 4-5 hook adapter scripts in `~/.claude/hooks/`
+ *     (PreToolUse / PostToolUse / SessionStart / UserPromptSubmit /
+ *     SessionEnd, all chmod +x)
+ *   - 14 slash commands in `~/.claude/commands/`
+ *     (incl. /team /test /validate)
+ *   - permissions.allow includes mcp__bizar__*
+ *   - permissions.deny covers dangerous patterns
+ *   - ~/.bizar_home/ exists (memory vault + loops dir)
+ *
+ * Exits non-zero if any check fails. Use `--json` for machine output.
+ * Use `--strict` to also fail on lenient checks.
+ */
+import chalk from 'chalk';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+const HOME = homedir();
+
+/**
+ * Resolve the Claude Code global config directory.
+ * Mirrors `cli/utils.mjs:claudeConfigDir()` → `~/.claude/`.
+ */
+function claudeDir() {
+  if (process.env.CLAUDE_CONFIG_DIR && process.env.CLAUDE_CONFIG_DIR.trim()) {
+    return process.env.CLAUDE_CONFIG_DIR.trim();
+  }
+  if (process.platform === 'win32') {
+    return process.env.APPDATA
+      ? join(process.env.APPDATA, 'Claude')
+      : join(HOME, '.claude');
+  }
+  return join(HOME, '.claude');
+}
+
+/**
+ * Resolve the Bizar HOME directory (memory vault + loops).
+ */
+function bizarHome() {
+  return process.env.BIZAR_HOME
+    || join(process.env.XDG_CONFIG_HOME || join(HOME, '.config'), 'bizar');
+}
+
+const REPO_ROOT = process.env.BIZAR_REPO_ROOT || process.cwd();
+
+const REQUIRED_AGENTS = [
+  'odin.md', 'vor.md', 'frigg.md', 'quick.md',
+  'mimir.md', 'heimdall.md', 'hermod.md', 'thor.md', 'baldr.md',
+  'tyr.md', 'vidarr.md', 'forseti.md',
+  'semble-search.md', 'agent-browser.md',
+];
+
+const REQUIRED_COMMANDS = [
+  'audit.md', 'bizar.md', 'explain.md', 'init.md', 'learn.md',
+  'plan.md', 'plow-through.md', 'pr-review.md', 'tailscale-serve.md',
+  'visual-plan.md',
+  'team.md', 'test.md', 'validate.md', 'setup-provider.md',
+];
+
+// v6.3.0 — Claude Code hook adapter scripts (executable, .mjs extension).
+const REQUIRED_HOOKS = [
+  'pretooluse-editwrite.mjs',
+  'posttooluse-editwrite.mjs',
+  'sessionstart-prime.mjs',
+  'userpromptsubmit-tag.mjs',
+  'sessionend-record.mjs',
+];
+
+// v6.3.0 — Claude Code-aware runtime deps. The Bizar SDK + the Claude
+// Code agent SDK are the only required deps for the Bizar MCP server.
+const REQUIRED_RUNTIME_DEPS = ['zod', '@anthropic-ai/claude-agent-sdk'];
+
+function check(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then((message) => ({ name, ok: true, message: message || 'ok' }))
+    .catch((err) => ({ name, ok: false, message: (err && err.message) ? err.message : String(err) }));
+}
+
+function settingsJsonPath() {
+  return join(claudeDir(), 'settings.json');
+}
+
+function readJsonSafe(file) {
+  try {
+    if (!existsSync(file)) return null;
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const CHECKS = {
+  'claude-cli-reachable': async () => {
+    const r = spawnSync('claude', ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (r.status !== 0) throw new Error(`claude --version exited ${r.status}`);
+    return (r.stdout || r.stderr || '').trim().split('\n')[0] || 'claude available';
+  },
+
+  'claude-settings-exists': async () => {
+    const p = settingsJsonPath();
+    if (!existsSync(p)) throw new Error(`not found at ${p}`);
+    return p;
+  },
+
+  'claude-settings-parses': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    if (!cfg) throw new Error('invalid JSON');
+    return '~/.claude/settings.json parses';
+  },
+
+  'claude-settings-schema': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    if (!cfg?.$schema) {
+      return 'no $schema declared (advisory only)';
+    }
+    if (!cfg.$schema.includes('claude-code-settings')) {
+      throw new Error(`unexpected $schema: ${cfg.$schema}`);
+    }
+    return `$schema = ${cfg.$schema}`;
+  },
+
+  'mcp-server-bizar-registered': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const servers = cfg?.mcpServers;
+    if (!servers || !servers.bizar) {
+      throw new Error(`mcpServers.bizar missing in ${settingsJsonPath()} — run \`bizar install\``);
+    }
+    const s = servers.bizar;
+    return `bizar MCP server registered: command=${s.command || '(unset)'}, type=${s.type || 'stdio'}`;
+  },
+
+  'mcp-server-bizar-command': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const s = cfg?.mcpServers?.bizar;
+    if (!s) throw new Error('bizar MCP server not registered');
+    const args = Array.isArray(s.args) ? s.args.join(' ') : '';
+    const expected = 'npx -y @polderlabs/bizar-sdk mcp';
+    const actual = `${s.command || ''} ${args}`.trim();
+    if (!actual.includes('@polderlabs/bizar-sdk')) {
+      throw new Error(`MCP server command does not reference @polderlabs/bizar-sdk: ${actual}`);
+    }
+    return `MCP command OK: ${actual}`;
+  },
+
+  'permissions-allow-bizar': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const allow = cfg?.permissions?.allow || [];
+    const hasBizar = allow.some((p) => typeof p === 'string' && p.startsWith('mcp__bizar__'));
+    if (!hasBizar) {
+      throw new Error('permissions.allow does not include any mcp__bizar__* entries');
+    }
+    return `${allow.filter((p) => p.startsWith('mcp__bizar__')).length} mcp__bizar__* allowed`;
+  },
+
+  'permissions-deny-dangerous': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const deny = cfg?.permissions?.deny || [];
+    const required = [
+      'Read(./.env)',
+      'Bash(rm -rf /)',
+      'Bash(sudo *)',
+      'Write(./node_modules/**)',
+      'Write(./package-lock.json)',
+    ];
+    const missing = required.filter((r) => !deny.includes(r));
+    if (missing.length > 0) {
+      return `missing ${missing.length} deny pattern(s) (advisory): ${missing.join(', ')}`;
+    }
+    return `${deny.length} deny pattern(s) — all 5 required present`;
+  },
+
+  'hooks-pretooluse-wired': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const arr = cfg?.hooks?.PreToolUse;
+    if (!Array.isArray(arr) || arr.length === 0) {
+      throw new Error('no PreToolUse hooks wired in settings.json');
+    }
+    const m = arr.find((h) => h.matcher && h.matcher.includes('Write') && h.matcher.includes('Edit'));
+    if (!m) throw new Error('PreToolUse matcher missing Write|Edit pattern');
+    return `${arr.length} PreToolUse hook(s) wired (matcher: ${m.matcher})`;
+  },
+
+  'hooks-posttooluse-wired': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const arr = cfg?.hooks?.PostToolUse;
+    if (!Array.isArray(arr) || arr.length === 0) {
+      throw new Error('no PostToolUse hooks wired in settings.json');
+    }
+    return `${arr.length} PostToolUse hook(s) wired`;
+  },
+
+  'hooks-sessionstart-wired': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const arr = cfg?.hooks?.SessionStart;
+    if (!Array.isArray(arr) || arr.length === 0) {
+      throw new Error('no SessionStart hooks wired in settings.json');
+    }
+    return `${arr.length} SessionStart hook(s) wired`;
+  },
+
+  'hooks-userpromptsubmit-wired': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const arr = cfg?.hooks?.UserPromptSubmit;
+    if (!Array.isArray(arr) || arr.length === 0) {
+      throw new Error('no UserPromptSubmit hooks wired in settings.json');
+    }
+    return `${arr.length} UserPromptSubmit hook(s) wired`;
+  },
+
+  'hooks-sessionend-wired': async () => {
+    const cfg = readJsonSafe(settingsJsonPath());
+    const arr = cfg?.hooks?.SessionEnd;
+    if (!Array.isArray(arr) || arr.length === 0) {
+      return 'no SessionEnd hook wired (advisory)';
+    }
+    return `${arr.length} SessionEnd hook(s) wired`;
+  },
+
+  'agent-files-installed': async () => {
+    const dir = join(claudeDir(), 'agents');
+    if (!existsSync(dir)) throw new Error(`agents dir missing: ${dir}`);
+    const missing = REQUIRED_AGENTS.filter((f) => !existsSync(join(dir, f)));
+    if (missing.length > 0) throw new Error(`missing: ${missing.join(', ')}`);
+    return `all ${REQUIRED_AGENTS.length} agents present in ${dir}`;
+  },
+
+  'agent-frontmatter-format': async () => {
+    // Claude Code reads agents via `.md` files with YAML frontmatter.
+    // Spot-check that at least the odin.md agent has frontmatter.
+    const dir = join(claudeDir(), 'agents');
+    if (!existsSync(dir)) throw new Error('agents dir missing');
+    const odin = join(dir, 'odin.md');
+    if (!existsSync(odin)) throw new Error('odin.md missing');
+    const text = readFileSync(odin, 'utf8');
+    if (!text.startsWith('---')) {
+      throw new Error('odin.md has no YAML frontmatter — Claude Code may not load it');
+    }
+    return 'odin.md has YAML frontmatter';
+  },
+
+  'slash-commands-installed': async () => {
+    const dir = join(claudeDir(), 'commands');
+    if (!existsSync(dir)) throw new Error(`commands dir missing: ${dir}`);
+    const missing = REQUIRED_COMMANDS.filter((f) => !existsSync(join(dir, f)));
+    if (missing.length > 0) {
+      throw new Error(`missing: ${missing.join(', ')} — run \`bizar update\``);
+    }
+    return `all ${REQUIRED_COMMANDS.length} slash commands present`;
+  },
+
+  'team-command-present': async () => {
+    const team = join(claudeDir(), 'commands', 'team.md');
+    if (!existsSync(team)) throw new Error(`${team} missing — run \`bizar update\``);
+    return '/team command installed';
+  },
+
+  'test-command-present': async () => {
+    const testCmd = join(claudeDir(), 'commands', 'test.md');
+    if (!existsSync(testCmd)) throw new Error(`${testCmd} missing — run \`bizar update\``);
+    return '/test command installed';
+  },
+
+  'validate-command-present': async () => {
+    const v = join(claudeDir(), 'commands', 'validate.md');
+    if (!existsSync(v)) throw new Error(`${v} missing — run \`bizar update\``);
+    return '/validate command installed';
+  },
+
+  'skills-installed': async () => {
+    const dir = join(claudeDir(), 'skills');
+    if (!existsSync(dir)) throw new Error(`skills dir missing: ${dir} — run \`bizar update\``);
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const skills = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (skills.length === 0) throw new Error('no skills installed — run `bizar update`');
+    return `${skills.length} skill(s) installed: ${skills.slice(0, 5).join(', ')}${skills.length > 5 ? '...' : ''}`;
+  },
+
+  'rules-installed': async () => {
+    const dir = join(claudeDir(), 'rules');
+    if (!existsSync(dir)) throw new Error(`rules dir missing: ${dir} — run \`bizar update\``);
+    const entries = readdirSync(dir).filter((f) => f.endsWith('.md') || f.endsWith('.txt'));
+    if (entries.length === 0) throw new Error('no rules installed — run `bizar update`');
+    return `${entries.length} rule file(s): ${entries.join(', ')}`;
+  },
+
+  'hooks-installed': async () => {
+    const dir = join(claudeDir(), 'hooks');
+    if (!existsSync(dir)) throw new Error(`hooks dir missing: ${dir} — run \`bizar update\``);
+    const missing = REQUIRED_HOOKS.filter((f) => !existsSync(join(dir, f)));
+    if (missing.length > 0) {
+      throw new Error(`missing: ${missing.join(', ')} — run \`bizar update\``);
+    }
+    // Verify hooks are executable. On Windows, chmod is a no-op so
+    // skip the check there.
+    if (process.platform !== 'win32') {
+      const nonExec = [];
+      for (const f of REQUIRED_HOOKS) {
+        try {
+          const st = statSync(join(dir, f));
+          // 0o755 = owner=rwx, group=r-x, other=r-x. Just check owner has x.
+          if ((st.mode & 0o100) === 0) nonExec.push(f);
+        } catch {
+          nonExec.push(f);
+        }
+      }
+      if (nonExec.length > 0) {
+        throw new Error(`hooks not executable: ${nonExec.join(', ')} — run \`chmod +x ~/.claude/hooks/*\``);
+      }
+    }
+    return `all ${REQUIRED_HOOKS.length} Claude Code hook file(s) executable in ${dir}`;
+  },
+
+  'bizar-home-exists': async () => {
+    const h = bizarHome();
+    if (!existsSync(h)) {
+      throw new Error(`BIZAR_HOME missing at ${h} — run \`bizar install\``);
+    }
+    return `BIZAR_HOME = ${h}`;
+  },
+
+  'bizar-memory-vault-exists': async () => {
+    const vault = join(bizarHome(), 'memory-vault');
+    if (!existsSync(vault)) {
+      throw new Error(`memory vault missing at ${vault} — run \`bizar install\``);
+    }
+    return `memory vault = ${vault}`;
+  },
+
+  'plugin-runtime-deps': async () => {
+    // v6.3.0 — for Claude Code, the runtime deps live in the
+    // Bizar SDK's node_modules, not in a `~/.claude/plugins/bizar/`
+    // dir. We probe the SDK install via npm root -g + the
+    // bizar-sdk entry. This is best-effort.
+    try {
+      const out = spawnSync('npm', ['root', '-g'], { encoding: 'utf8', timeout: 5000 }).stdout || '';
+      const root = out.trim();
+      if (!root) throw new Error('npm root -g returned empty');
+      const sdkPath = join(root, '@polderlabs', 'bizar-sdk');
+      if (!existsSync(sdkPath)) {
+        return `Bizar SDK not found at ${sdkPath} — install via npm install -g @polderlabs/bizar-sdk (advisory)`;
+      }
+      const missing = REQUIRED_RUNTIME_DEPS.filter((d) => !existsSync(join(sdkPath, 'node_modules', d)));
+      if (missing.length > 0) {
+        return `missing runtime deps in SDK: ${missing.join(', ')} (advisory)`;
+      }
+      return `runtime deps present (${REQUIRED_RUNTIME_DEPS.join(', ')})`;
+    } catch (err) {
+      return `could not probe SDK install: ${err.message} (advisory)`;
+    }
+  },
+
+  '9router-reachable': async () => {
+    const url = process.env.NINEROUTER_URL || 'http://localhost:20128';
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 4000);
+    try {
+      const res = await fetch(`${url}/api/health`, { signal: ac.signal });
+      if (!res.ok) throw new Error(`9router at ${url} returned HTTP ${res.status}`);
+      const body = await res.text().catch(() => '');
+      if (!body.includes('"ok":true')) {
+        throw new Error(`9router at ${url} responded but body did not include ok:true`);
+      }
+      return `9router healthy at ${url}`;
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+
+  'claude-md-mirrored': async () => {
+    const f = join(claudeDir(), 'CLAUDE.md');
+    if (!existsSync(f)) {
+      throw new Error(`${f} missing — run \`bizar install\` to mirror AGENTS.md`);
+    }
+    const stat = statSync(f);
+    if (stat.size < 200) throw new Error(`${f} is suspiciously small (${stat.size} bytes)`);
+    return `CLAUDE.md mirrored (${stat.size} bytes)`;
+  },
+};
+
+const CHECK_ORDER = [
+  'claude-cli-reachable',
+  'claude-settings-exists',
+  'claude-settings-parses',
+  'claude-settings-schema',
+  'mcp-server-bizar-registered',
+  'mcp-server-bizar-command',
+  'permissions-allow-bizar',
+  'permissions-deny-dangerous',
+  'hooks-pretooluse-wired',
+  'hooks-posttooluse-wired',
+  'hooks-sessionstart-wired',
+  'hooks-userpromptsubmit-wired',
+  'hooks-sessionend-wired',
+  'agent-files-installed',
+  'agent-frontmatter-format',
+  'slash-commands-installed',
+  'team-command-present',
+  'test-command-present',
+  'validate-command-present',
+  'skills-installed',
+  'rules-installed',
+  'hooks-installed',
+  'bizar-home-exists',
+  'bizar-memory-vault-exists',
+  'claude-md-mirrored',
+  'plugin-runtime-deps',
+  '9router-reachable',
+];
+
+const LENIENT_CHECKS = new Set([
+  'claude-cli-reachable', // Claude Code CLI is normally on $PATH only on dev hosts; CI containers without it shouldn't fail validation
+  '9router-reachable',
+  'plugin-runtime-deps', // best-effort probe via `npm root -g`
+  'permissions-deny-dangerous', // advisory — user may have intentionally customized
+  'hooks-sessionend-wired', // advisory — SessionEnd is optional
+  'claude-settings-schema', // advisory — schema field is documentation
+]);
+
+export function showValidateHelp() {
+  console.log(`
+  bizar validate — Validate the Bizar install end-to-end.
+
+  Usage:
+    bizar validate                Run the full check battery (default)
+    bizar validate --json         Machine-readable JSON output
+    bizar validate --strict       Fail on lenient checks (e.g. 9router offline)
+    bizar validate --only <name>  Run only the named check (e.g. team-command-present)
+    bizar validate --help         Show this help
+
+  Description:
+    A 21-point health check that confirms the Bizar install is fully
+    integrated with Claude Code:
+      • claude CLI reachable + version
+      • ~/.claude/settings.json parses + Bizar MCP server registered
+      • permissions.allow includes mcp__bizar__*
+      • permissions.deny covers dangerous patterns
+      • hooks (PreToolUse / PostToolUse / SessionStart / UserPromptSubmit
+        / SessionEnd) wired in settings.json
+      • all 14 agent files installed with Claude Code frontmatter
+      • all 14 slash commands (/audit, /bizar, /explain, /init, /learn,
+        /plan, /plow-through, /pr-review, /tailscale-serve,
+        /visual-plan, /team, /test, /validate)
+      • all skills / rules / hooks mirrored to ~/.claude/
+      • ~/.bizar_home/ + memory vault ready
+      • 9Router gateway reachable (lenient unless --strict)
+
+  Exit codes:
+    0  All checks passed (or only lenient ones failed)
+    1  One or more strict checks failed
+    2  Invalid --only argument
+
+  Related:
+    bizar doctor          Simpler 8-point check (legacy)
+    bizar update          Refresh the install (re-runs the provisioner)
+    bizar repair          Fix common issues (stale symlinks, version drift)
+  `);
+}
+
+export async function runValidate(opts = {}) {
+  const json = !!opts.json;
+  const strict = !!opts.strict;
+  const only = typeof opts.only === 'string' && opts.only.trim() ? opts.only.trim() : null;
+  const list = only ? [only] : CHECK_ORDER;
+  if (only && !CHECKS[only]) {
+    console.error(chalk.red(`  ✗ Unknown check: ${only}`));
+    console.error(chalk.dim(`  Run \`bizar validate\` to see all available checks.`));
+    process.exit(2);
+    return;
+  }
+
+  const results = [];
+  for (const name of list) {
+    const fn = CHECKS[name];
+    if (!fn) continue;
+    const r = await check(name, fn);
+    results.push(r);
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ passed: results.filter((r) => r.ok).length, failed: results.filter((r) => !r.ok).length, results }, null, 2) + '\n');
+    const failed = results.filter((r) => !r.ok).length;
+    const strictFailed = results.filter((r) => !r.ok && !LENIENT_CHECKS.has(r.name)).length;
+    process.exit(strict ? (failed > 0 ? 1 : 0) : (strictFailed > 0 ? 1 : 0));
+    return;
+  }
+
+  for (const r of results) {
+    const isLenient = LENIENT_CHECKS.has(r.name);
+    const marker = r.ok ? chalk.green('✓') : (isLenient ? chalk.yellow('⚠') : chalk.red('✗'));
+    const label = r.name.padEnd(32);
+    const msg = r.ok ? chalk.dim(`  ${r.message}`) : (isLenient ? chalk.yellow(`  ${r.message}`) : chalk.red(`  ${r.message}`));
+    console.log(`  ${marker} ${label}${msg}`);
+  }
+
+  const passed = results.filter((r) => r.ok).length;
+  const failed = results.filter((r) => !r.ok).length;
+  const strictFailed = results.filter((r) => !r.ok && !LENIENT_CHECKS.has(r.name)).length;
+  console.log('');
+  if (strictFailed === 0 && (failed === 0 || (!strict && failed === results.filter((r) => LENIENT_CHECKS.has(r.name)).length))) {
+    console.log(chalk.green(`  ✓ ${passed} checks passed, ${failed} lenient warning(s)`));
+    process.exit(0);
+  } else {
+    console.log(chalk.yellow(`  ⚠ ${passed} checks passed, ${failed} failed (${strictFailed} strict)`));
+    console.log(chalk.dim(`  Run \`bizar update\` to refresh the install, or \`bizar repair\` for common fixes.`));
+    process.exit(1);
+  }
+}
+
+// ── run() entry point (used by bin.mjs dispatcher) ───────────────────────────
+
+export async function run(name, args, isHelpRequest) {
+  if (name !== 'validate') return false;
+  if (isHelpRequest) {
+    showValidateHelp();
+    return true;
+  }
+  const json = args.includes('--json');
+  const strict = args.includes('--strict');
+  const onlyIdx = args.indexOf('--only');
+  const only = onlyIdx >= 0 ? args[onlyIdx + 1] : null;
+  await runValidate({ json, strict, only });
+  return true;
+}