@codexstar/bug-hunter 3.0.0

package/bin/bug-hunter

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+/**
+ * bug-hunter CLI — installs the bug-hunter skill into your agent's skill directory.
+ *
+ * Usage:
+ *   bug-hunter install            # Auto-detect agent and install skill
+ *   bug-hunter install --agent claude-code
+ *   bug-hunter install --path ~/.custom/skills
+ *   bug-hunter doctor             # Check environment (node, chub, context7)
+ *   bug-hunter info               # Show skill metadata
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SKILL_SRC = path.resolve(__dirname, '..');
+const SKILL_NAME = 'bug-hunter';
+
+// Agent skill directories in priority order
+const AGENT_DIRS = [
+  { agent: 'claude-code', dir: path.join(require('os').homedir(), '.claude', 'skills', SKILL_NAME) },
+  { agent: 'codex', dir: path.join(require('os').homedir(), '.codex', 'skills', SKILL_NAME) },
+  { agent: 'agents', dir: path.join(require('os').homedir(), '.agents', 'skills', SKILL_NAME) },
+  { agent: 'cursor', dir: path.join(require('os').homedir(), '.cursor', 'skills', SKILL_NAME) },
+  { agent: 'kiro', dir: path.join(require('os').homedir(), '.kiro', 'skills', SKILL_NAME) },
+];
+
+function usage() {
+  console.log(`
+  bug-hunter - Adversarial AI bug hunting skill
+
+  Commands:
+    install [--agent <name>] [--path <dir>]   Install skill into agent directory
+    doctor                                     Check environment readiness
+    info                                       Show skill metadata
+
+  Options:
+    --agent <name>    Target agent: claude-code, codex, cursor, kiro, agents
+    --path <dir>      Custom install directory (overrides --agent)
+
+  Examples:
+    bug-hunter install                         # Auto-detect agent
+    bug-hunter install --agent claude-code     # Specific agent
+    bug-hunter install --path ~/my-skills/bug-hunter
+    bug-hunter doctor                          # Check node, chub, context7
+  `.trim());
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      // Skip git, node_modules, tmp, .bug-hunter output
+      if (['.git', 'node_modules', 'tmp', '.bug-hunter'].includes(entry)) continue;
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function install(args) {
+  let targetDir = null;
+  let agentName = null;
+
+  // Parse args
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--path' && args[i + 1]) {
+      targetDir = path.resolve(args[++i]);
+    } else if (args[i] === '--agent' && args[i + 1]) {
+      agentName = args[++i];
+    }
+  }
+
+  // Resolve target directory
+  if (!targetDir) {
+    if (agentName) {
+      const match = AGENT_DIRS.find(a => a.agent === agentName);
+      if (!match) {
+        console.error(`Unknown agent: ${agentName}`);
+        console.error(`Available: ${AGENT_DIRS.map(a => a.agent).join(', ')}`);
+        process.exit(1);
+      }
+      targetDir = match.dir;
+    } else {
+      // Auto-detect: use first agent whose parent dir exists
+      for (const { agent, dir } of AGENT_DIRS) {
+        const parent = path.dirname(path.dirname(dir)); // e.g. ~/.claude
+        if (fs.existsSync(parent)) {
+          targetDir = dir;
+          agentName = agent;
+          break;
+        }
+      }
+      if (!targetDir) {
+        // Default to ~/.agents/skills/bug-hunter
+        targetDir = AGENT_DIRS.find(a => a.agent === 'agents').dir;
+        agentName = 'agents';
+      }
+    }
+  }
+
+  console.log(`Installing bug-hunter skill...`);
+  console.log(`  Source:  ${SKILL_SRC}`);
+  console.log(`  Target:  ${targetDir}`);
+  if (agentName) console.log(`  Agent:   ${agentName}`);
+
+  // Copy skill files
+  copyRecursive(SKILL_SRC, targetDir);
+
+  console.log(`\n  Installed successfully.\n`);
+  console.log(`  Usage: /bug-hunter src/`);
+  console.log(`  Docs:  https://github.com/codexstar69/bug-hunter`);
+
+  // Run doctor automatically after install
+  console.log('');
+  doctor();
+}
+
+function doctor() {
+  console.log('Environment check:\n');
+  let issues = 0;
+
+  // Node.js
+  try {
+    const nodeVersion = execFileSync('node', ['--version'], { encoding: 'utf8' }).trim();
+    console.log(`  [ok] Node.js ${nodeVersion}`);
+  } catch {
+    console.log('  [!!] Node.js not found — required for doc verification');
+    issues++;
+  }
+
+  // Context Hub (chub)
+  try {
+    execFileSync('chub', ['--help'], { stdio: 'ignore', timeout: 3000 });
+    console.log('  [ok] Context Hub (chub) installed — curated docs available');
+  } catch {
+    console.log('  [--] Context Hub (chub) not installed — will fall back to Context7');
+    console.log('       Install for better doc verification: npm install -g @aisuite/chub');
+    console.log('       More info: https://github.com/andrewyng/context-hub');
+  }
+
+  // Context7 API
+  try {
+    const c7Script = path.join(SKILL_SRC, 'scripts', 'context7-api.cjs');
+    if (fs.existsSync(c7Script)) {
+      console.log('  [ok] Context7 fallback available');
+    } else {
+      console.log('  [--] Context7 script not found (non-critical)');
+    }
+  } catch {
+    console.log('  [--] Context7 check skipped');
+  }
+
+  // Git
+  try {
+    const gitVersion = execFileSync('git', ['--version'], { encoding: 'utf8' }).trim();
+    console.log(`  [ok] ${gitVersion}`);
+  } catch {
+    console.log('  [!!] Git not found — required for fix pipeline');
+    issues++;
+  }
+
+  console.log('');
+  if (issues === 0) {
+    console.log('  Ready to hunt bugs.\n');
+  } else {
+    console.log(`  ${issues} issue(s) found. Fix them for full functionality.\n`);
+  }
+}
+
+function info() {
+  const skillMd = path.join(SKILL_SRC, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) {
+    console.error('SKILL.md not found');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillMd, 'utf8');
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (frontmatterMatch) {
+    const lines = frontmatterMatch[1].split('\n');
+    console.log('\nbug-hunter skill metadata:\n');
+    for (const line of lines) {
+      console.log(`  ${line}`);
+    }
+    console.log('');
+  }
+
+  console.log(`  Install:  npx skills add codexstar69/bug-hunter`);
+  console.log(`  Or:       npm install -g @codexstar/bug-hunter && bug-hunter install`);
+  console.log(`  Repo:     https://github.com/codexstar69/bug-hunter`);
+  console.log('');
+}
+
+// Main
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'install':
+    install(args.slice(1));
+    break;
+  case 'doctor':
+    doctor();
+    break;
+  case 'info':
+    info();
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    usage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    usage();
+    process.exit(1);
+}

package/evals/evals.json

@@ -0,0 +1,362 @@
+{
+  "skill_name": "bug-hunter",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "/bug-hunter test-fixture/",
+      "expected_output": "Full pipeline execution on the included test fixture (Express app with 6 planted bugs). Should run Recon -> Hunter -> Skeptic -> Referee and produce a final report confirming at least 5 of 6 planted bugs with severity ratings, file paths, and suggested fixes.",
+      "files": [
+        "test-fixture/server.js",
+        "test-fixture/auth.js",
+        "test-fixture/users.js",
+        "test-fixture/db.js"
+      ],
+      "assertions": [
+        {
+          "text": "Pipeline runs all phases: Recon, Hunter, Skeptic, Referee",
+          "type": "content_check"
+        },
+        {
+          "text": "At least 5 of 6 planted bugs are confirmed in the final report",
+          "type": "content_check"
+        },
+        {
+          "text": "Each confirmed bug includes file path, line numbers, severity, and suggested fix",
+          "type": "content_check"
+        },
+        {
+          "text": "False positives are challenged and filtered by the Skeptic/Referee pipeline",
+          "type": "content_check"
+        },
+        {
+          "text": "Final report includes scan metadata (mode, files scanned, coverage)",
+          "type": "content_check"
+        },
+        {
+          "text": "Fix pipeline is triggered by default when confirmed bugs exist; only --scan-only disables fixes",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "/bug-hunter src/api/auth.ts",
+      "expected_output": "Single-file mode scan of an auth file. Should skip Recon (not needed for single file), run one Hunter, one Skeptic, and one Referee. Output should focus on security and logic bugs in the auth file specifically.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Selects single-file mode (1 file detected)",
+          "type": "content_check"
+        },
+        {
+          "text": "Skips Recon agent (not needed for single-file mode)",
+          "type": "content_check"
+        },
+        {
+          "text": "Hunter scans the target file and reports findings with BUG-ID format",
+          "type": "content_check"
+        },
+        {
+          "text": "Skeptic challenges the findings with code-based counter-arguments",
+          "type": "content_check"
+        },
+        {
+          "text": "Referee produces a final verdict (REAL BUG or NOT A BUG) for each finding",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "/bug-hunter -b feature-auth --base develop",
+      "expected_output": "Branch diff mode. Should run git diff to find changed files between feature-auth and develop branches, filter out non-source files, then run the full pipeline on the changed source files.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Runs git diff --name-only to extract changed files between branches",
+          "type": "content_check"
+        },
+        {
+          "text": "Filters out non-source files (configs, docs, assets, lockfiles)",
+          "type": "content_check"
+        },
+        {
+          "text": "Reports the number of source files to scan after filtering",
+          "type": "content_check"
+        },
+        {
+          "text": "Selects appropriate mode based on file count (small, parallel, extended, etc.)",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "/bug-hunter --staged",
+      "expected_output": "Staged file mode for pre-commit checking. Should run git diff --cached --name-only to get staged files, filter non-source files, then scan the staged source files.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Runs git diff --cached --name-only to get staged files",
+          "type": "content_check"
+        },
+        {
+          "text": "Filters out non-source files from the staged list",
+          "type": "content_check"
+        },
+        {
+          "text": "Scans full file contents of staged files (not just diffs)",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "/bug-hunter --fix src/",
+      "expected_output": "Full pipeline with auto-fix. After Phase 1 (find & verify), should proceed to Phase 2: create a git branch, acquire single-writer lock, detect test infrastructure, capture test baseline, run Fixer clusters sequentially with checkpoint commits, run post-fix tests, auto-revert regressions, and release lock.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Creates a git safety branch (bug-hunter-fix-*) before applying fixes",
+          "type": "content_check"
+        },
+        {
+          "text": "Detects test command from package.json or project config",
+          "type": "content_check"
+        },
+        {
+          "text": "Captures test baseline before applying fixes",
+          "type": "content_check"
+        },
+        {
+          "text": "Fixer agents implement minimal, surgical code changes",
+          "type": "content_check"
+        },
+        {
+          "text": "Each fix is a separate checkpoint commit with descriptive message",
+          "type": "content_check"
+        },
+        {
+          "text": "Post-fix test run compares against baseline (new failures vs pre-existing)",
+          "type": "content_check"
+        },
+        {
+          "text": "Fixes that cause new test failures are auto-reverted",
+          "type": "content_check"
+        },
+        {
+          "text": "Acquires and releases .claude/bug-hunter-fix.lock around fix phase",
+          "type": "content_check"
+        },
+        {
+          "text": "Auto-fixes only bugs that pass confidence eligibility threshold",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "/bug-hunter --loop src/",
+      "expected_output": "Loop mode for thorough coverage. Should create ralph-loop state files, iterate the pipeline until all CRITICAL and HIGH files are scanned, track coverage in .claude/bug-hunter-coverage.md, and mark ALL_TASKS_COMPLETE when done.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Creates .claude/ralph-loop.local.md state file for loop mode",
+          "type": "content_check"
+        },
+        {
+          "text": "Creates or updates .claude/bug-hunter-coverage.md with machine-parseable format",
+          "type": "content_check"
+        },
+        {
+          "text": "Tracks file coverage status (DONE, PARTIAL, SKIPPED) per iteration",
+          "type": "content_check"
+        },
+        {
+          "text": "Subsequent iterations only scan uncovered files (no re-scanning DONE files)",
+          "type": "content_check"
+        },
+        {
+          "text": "Marks ALL_TASKS_COMPLETE when all CRITICAL and HIGH files show DONE",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Can you check my Express API for security vulnerabilities? The code is in src/",
+      "expected_output": "Should trigger the bug-hunter skill (even though the user didn't say /bug-hunter) and run a security-focused scan on the src/ directory. The deep Hunter should prioritize security findings, with optional triage hints when enabled.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Triggers bug-hunter skill from natural language (security audit request)",
+          "type": "content_check"
+        },
+        {
+          "text": "Runs Recon to map architecture and identify trust boundaries",
+          "type": "content_check"
+        },
+        {
+          "text": "Deep Hunter focuses on injection, auth bypass, input validation, and secrets exposure in security audit requests",
+          "type": "content_check"
+        },
+        {
+          "text": "Output includes severity ratings (Critical, Medium, Low) for each finding",
+          "type": "content_check"
+        },
+        {
+          "text": "Framework-specific protections are checked (Express middleware, helmet, etc.)",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "/bug-hunter --fix --approve src/auth/",
+      "expected_output": "Fix mode with approval. Should find bugs in auth directory, then fix them but prompt the user before each edit (approval mode). Fixer agents run in default mode rather than auto mode.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "APPROVE_MODE is set to true from --approve flag",
+          "type": "content_check"
+        },
+        {
+          "text": "Fixer agents run in mode: default (user reviews each edit)",
+          "type": "content_check"
+        },
+        {
+          "text": "Reports 'Running in approval mode' to the user",
+          "type": "content_check"
+        },
+        {
+          "text": "Fixes are still committed as individual checkpoint commits",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "/bug-hunter huge-repo/",
+      "expected_output": "Large-repo run should initialize .claude/bug-hunter-state.json, split files into sequential chunks, and resume from state if interrupted.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Initializes bug-hunter-state.json with chunk metadata",
+          "type": "content_check"
+        },
+        {
+          "text": "Processes chunks sequentially and marks each chunk state",
+          "type": "content_check"
+        },
+        {
+          "text": "Can resume from existing state file without rescanning completed chunks",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "/bug-hunter src/ (second run with unchanged files)",
+      "expected_output": "Hash cache should skip unchanged files and focus scan effort on changed files only.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Runs hash-filter against bug-hunter-state.json before deep scan",
+          "type": "content_check"
+        },
+        {
+          "text": "Reports skipped unchanged files from cache",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 11,
+      "prompt": "/bug-hunter src/ with malformed subagent payload",
+      "expected_output": "Pipeline should fail fast before spawning subagents when payload validation fails.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Validates payload via payload-guard.cjs before each subagent launch",
+          "type": "content_check"
+        },
+        {
+          "text": "Does not launch subagent when payload validation fails",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 12,
+      "prompt": "/bug-hunter --fix src/ while another fix run is active",
+      "expected_output": "Fix phase should stop when single-writer lock cannot be acquired.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Attempts to acquire .claude/bug-hunter-fix.lock before any edits",
+          "type": "content_check"
+        },
+        {
+          "text": "Stops Phase 2 with clear lock-held message when lock is already held",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "prompt": "/bug-hunter --fix src/ with mixed-confidence bugs",
+      "expected_output": "Auto-fix should run only on high-confidence bugs and leave low-confidence bugs as manual review.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Applies confidence threshold gating (>=75%) for auto-fix eligibility",
+          "type": "content_check"
+        },
+        {
+          "text": "Reports low-confidence bugs as manual-review and does not auto-edit them",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "prompt": "/bug-hunter src/ on a CLI without spawn_agent",
+      "expected_output": "Pipeline should auto-select the available orchestration backend and continue. If remote orchestration is unavailable, it should fall back to local sequential execution.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Selects AGENT_BACKEND in preflight based on available runtime tools",
+          "type": "content_check"
+        },
+        {
+          "text": "Falls back to next backend when launch fails",
+          "type": "content_check"
+        },
+        {
+          "text": "Completes run with local-sequential fallback when no delegation backend is available",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 15,
+      "prompt": "/bug-hunter huge-repo/ with flaky chunk worker",
+      "expected_output": "Orchestrator should enforce per-chunk timeout, retry failed chunk once with backoff, and persist attempt details in run journal.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Uses run-bug-hunter.cjs for autonomous chunk orchestration",
+          "type": "content_check"
+        },
+        {
+          "text": "Retries timed out/failed chunk according to max-retries and backoff policy",
+          "type": "content_check"
+        },
+        {
+          "text": "Writes attempt events to .claude/bug-hunter-run.log",
+          "type": "content_check"
+        }
+      ]
+    }
+  ]
+}