@codexstar/bug-hunter 3.0.0 → 3.0.6

package/scripts/tests/security-skills-integration.test.cjs

@@ -0,0 +1,29 @@
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const test = require('node:test');
+
+const { resolveSkillScript } = require('./test-utils.cjs');
+
+test('main SKILL routes into bundled local security skills', () => {
+  const skillDoc = fs.readFileSync(resolveSkillScript('..', 'SKILL.md'), 'utf8');
+
+  assert.match(skillDoc, /skills\/commit-security-scan\/SKILL\.md/);
+  assert.match(skillDoc, /skills\/security-review\/SKILL\.md/);
+  assert.match(skillDoc, /skills\/threat-model-generation\/SKILL\.md/);
+  assert.match(skillDoc, /skills\/vulnerability-validation\/SKILL\.md/);
+
+  assert.match(skillDoc, /--pr-security/);
+  assert.match(skillDoc, /--security-review/);
+  assert.match(skillDoc, /--validate-security/);
+});
+
+test('README documents the integrated enterprise security pack flows', () => {
+  const readme = fs.readFileSync(resolveSkillScript('..', 'README.md'), 'utf8');
+
+  assert.match(readme, /PR-focused security review routes into `commit-security-scan`/);
+  assert.match(readme, /`--threat-model` routes into `threat-model-generation`/);
+  assert.match(readme, /enterprise\/full security review routes into `security-review`/);
+  assert.match(readme, /`--pr-security`/);
+  assert.match(readme, /`--security-review`/);
+  assert.match(readme, /`--validate-security`/);
+});

package/scripts/tests/skills-packaging.test.cjs

@@ -0,0 +1,30 @@
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const test = require('node:test');
+
+const { resolveSkillScript } = require('./test-utils.cjs');
+
+test('package.json ships the bundled local security skills', () => {
+  const packageJson = require(resolveSkillScript('..', 'package.json'));
+  assert.equal(Array.isArray(packageJson.files), true);
+  assert.equal(packageJson.files.includes('skills/'), true);
+});
+
+test('bundled local security skills exist with SKILL.md entrypoints', () => {
+  const skillNames = [
+    'commit-security-scan',
+    'security-review',
+    'threat-model-generation',
+    'vulnerability-validation'
+  ];
+
+  for (const skillName of skillNames) {
+    const skillPath = resolveSkillScript('..', 'skills', skillName, 'SKILL.md');
+    assert.equal(fs.existsSync(skillPath), true, `${skillName} should exist`);
+    const contents = fs.readFileSync(skillPath, 'utf8');
+    assert.match(contents, /^---/);
+    assert.match(contents, /name:/);
+    assert.match(contents, /description:/);
+  }
+});

package/scripts/tests/worktree-harvest.test.cjs

@@ -20,7 +20,7 @@ function makeGitFixture() {
   // Bare origin
   const origin = path.join(sandbox, 'origin.git');
   fs.mkdirSync(origin, { recursive: true });
-  execFileSync('git', ['init', '--bare'], { cwd: origin, stdio: 'ignore' });
+  execFileSync('git', ['init', '--bare', '-b', 'main'], { cwd: origin, stdio: 'ignore' });
 
   // Working clone
   const repo = path.join(sandbox, 'repo');
@@ -106,6 +106,17 @@ test('prepare cleans up stale worktree', () => {
   assert.equal(result.ok, true);
 });
 
+test('prepare refuses to delete an unrelated pre-existing directory', () => {
+  const { repo, fixBranch } = makeGitFixture();
+  const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'notes');
+  fs.mkdirSync(wtDir, { recursive: true });
+  fs.writeFileSync(path.join(wtDir, 'keep.txt'), 'keep\n');
+
+  const result = runRaw('node', [SCRIPT, 'prepare', fixBranch, wtDir], { cwd: repo });
+  assert.notEqual(result.status, 0);
+  assert.equal(fs.existsSync(path.join(wtDir, 'keep.txt')), true);
+});
+
 test('harvest finds new commits', () => {
   const { repo, fixBranch } = makeGitFixture();
   const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'batch-1');
@@ -180,6 +191,45 @@ test('cleanup handles missing worktree gracefully', () => {
   assert.equal(result.reason, 'not-found');
 });
 
+test('cleanup does not report success for unmanaged directories', () => {
+  const { repo } = makeGitFixture();
+  const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'notes');
+  fs.mkdirSync(wtDir, { recursive: true });
+  fs.writeFileSync(path.join(wtDir, 'keep.txt'), 'keep\n');
+
+  const result = runJson('node', [SCRIPT, 'cleanup', wtDir], { cwd: repo });
+  assert.equal(result.ok, true);
+  assert.equal(result.removed, false);
+  assert.equal(fs.existsSync(path.join(wtDir, 'keep.txt')), true);
+});
+
+test('cleanup preserves worktree contents when harvest fails', () => {
+  const { repo, fixBranch } = makeGitFixture();
+  const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'batch-1');
+
+  runJson('node', [SCRIPT, 'prepare', fixBranch, wtDir], { cwd: repo });
+  fs.rmSync(path.join(wtDir, '.worktree-manifest.json'));
+
+  const result = runJson('node', [SCRIPT, 'cleanup', wtDir], { cwd: repo });
+  assert.equal(result.ok, true);
+  assert.equal(result.removed, false);
+  assert.equal(fs.existsSync(wtDir), true);
+});
+
+test('cleanup returns stash metadata when defensive harvest stashes uncommitted work', () => {
+  const { repo, fixBranch } = makeGitFixture();
+  const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'batch-1');
+
+  runJson('node', [SCRIPT, 'prepare', fixBranch, wtDir], { cwd: repo });
+  fs.writeFileSync(path.join(wtDir, 'dirty.txt'), 'uncommitted\n');
+
+  const result = runJson('node', [SCRIPT, 'cleanup', wtDir], { cwd: repo });
+  assert.equal(result.ok, true);
+  assert.equal(result.removed, true);
+  assert.equal(typeof result.stashRef, 'string');
+  assert.equal(result.stashRef.length > 0, true);
+});
+
 test('cleanup-all removes multiple worktrees', () => {
   const { repo, fixBranch } = makeGitFixture();
   const parentDir = path.join(repo, '.bug-hunter', 'worktrees');
@@ -202,6 +252,21 @@ test('cleanup-all removes multiple worktrees', () => {
   assert.ok(result.cleaned >= 1);
 });
 
+test('cleanup-all preserves unrelated directories under the parent', () => {
+  const { repo, fixBranch } = makeGitFixture();
+  const parentDir = path.join(repo, '.bug-hunter', 'worktrees');
+  const wt1 = path.join(parentDir, 'batch-1');
+  const unrelated = path.join(parentDir, 'notes');
+
+  runJson('node', [SCRIPT, 'prepare', fixBranch, wt1], { cwd: repo });
+  fs.mkdirSync(unrelated, { recursive: true });
+  fs.writeFileSync(path.join(unrelated, 'readme.txt'), 'keep me\n', 'utf8');
+
+  runJson('node', [SCRIPT, 'cleanup-all', parentDir], { cwd: repo });
+  assert.equal(fs.existsSync(unrelated), true);
+  assert.equal(fs.existsSync(path.join(unrelated, 'readme.txt')), true);
+});
+
 test('checkout-fix returns main tree to fix branch', () => {
   const { repo, fixBranch } = makeGitFixture();
   const wtDir = path.join(repo, '.bug-hunter', 'worktrees', 'batch-1');
@@ -290,6 +355,7 @@ test('status reports worktree health', () => {
   assert.equal(s2.isStale, false);
   assert.equal(s2.commitCount, 0);
   assert.equal(s2.harvested, false);
+  assert.equal(s2.hasUncommitted, false);
 
   // Clean up
   runJson('node', [SCRIPT, 'harvest', wtDir], { cwd: repo });

package/scripts/worktree-harvest.cjs

@@ -82,6 +82,21 @@ function writeJsonFile(filePath, data) {
   fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
 }
 
+function isManagedWorktreeDir(worktreeDir) {
+  const absDir = path.resolve(worktreeDir);
+  if (readJsonFile(manifestPath(absDir))) {
+    return true;
+  }
+  const listed = gitSafe(['worktree', 'list', '--porcelain']);
+  if (!listed.ok || !listed.output) {
+    return false;
+  }
+  return listed.output
+    .split('\n')
+    .filter((line) => line.startsWith('worktree '))
+    .some((line) => path.resolve(line.slice('worktree '.length).trim()) === absDir);
+}
+
 // ---------------------------------------------------------------------------
 // prepare — create worktree on the fix branch
 // ---------------------------------------------------------------------------
@@ -96,8 +111,13 @@ function prepare(fixBranch, worktreeDir) {
     process.exit(1);
   }
 
-  // 2. If worktreeDir already exists, clean up stale worktree
+  // 2. If worktreeDir already exists, clean up stale managed worktree only
   if (fs.existsSync(absDir)) {
+    const managed = isManagedWorktreeDir(absDir);
+    if (!managed) {
+      out({ ok: false, error: 'path-not-managed-worktree', detail: `${absDir} already exists and is not a managed worktree` });
+      process.exit(1);
+    }
     gitSafe(['worktree', 'remove', absDir, '--force']);
     if (fs.existsSync(absDir)) {
       fs.rmSync(absDir, { recursive: true, force: true });
@@ -319,9 +339,21 @@ function cleanup(worktreeDir) {
     return;
   }
 
+  const managed = isManagedWorktreeDir(absDir);
+  if (!managed) {
+    out({ ok: true, removed: false, reason: 'not-managed-worktree' });
+    return;
+  }
+
+  let defensiveHarvest = readJsonFile(harvestPath(absDir));
   // If harvest hasn't run yet, run it defensively
-  if (!readJsonFile(harvestPath(absDir))) {
-    try { harvestCore(absDir); } catch (_) { /* best-effort */ }
+  if (!defensiveHarvest) {
+    try {
+      defensiveHarvest = harvestCore(absDir);
+    } catch (_) {
+      out({ ok: true, removed: false, reason: 'harvest-failed' });
+      return;
+    }
   }
 
   const manifest = readJsonFile(manifestPath(absDir));
@@ -333,11 +365,14 @@ function cleanup(worktreeDir) {
   }
 
   gitSafe(['worktree', 'prune']);
+  const removed = !fs.existsSync(absDir);
 
   out({
     ok: true,
-    removed: true,
-    detachedMainTree: manifest ? manifest.detachedMainTree : false
+    removed,
+    detachedMainTree: manifest ? manifest.detachedMainTree : false,
+    reason: removed ? undefined : 'remove-failed',
+    stashRef: defensiveHarvest && defensiveHarvest.stashRef ? defensiveHarvest.stashRef : null
   });
 }
 
@@ -367,15 +402,26 @@ function cleanupAll(parentDir) {
   for (const name of entries) {
     const wtDir = path.join(absParent, name);
     try {
+      const managed = isManagedWorktreeDir(wtDir);
+      if (!managed) {
+        results.push({ name, removed: false, reason: 'not-managed-worktree' });
+        continue;
+      }
+      let defensiveHarvest = readJsonFile(harvestPath(wtDir));
       // Defensive harvest before cleanup
-      if (!readJsonFile(harvestPath(wtDir))) {
-        try { harvestCore(wtDir); } catch (_) { /* best-effort */ }
+      if (!defensiveHarvest) {
+        try {
+          defensiveHarvest = harvestCore(wtDir);
+        } catch (_) {
+          results.push({ name, removed: false, reason: 'harvest-failed' });
+          continue;
+        }
       }
       gitSafe(['worktree', 'remove', wtDir, '--force']);
       if (fs.existsSync(wtDir)) {
         fs.rmSync(wtDir, { recursive: true, force: true });
       }
-      results.push({ name, removed: true });
+      results.push({ name, removed: true, stashRef: defensiveHarvest && defensiveHarvest.stashRef ? defensiveHarvest.stashRef : null });
     } catch (err) {
       results.push({ name, removed: false, error: err.message });
     }
@@ -410,7 +456,14 @@ function statusCmd(worktreeDir) {
   const isStale = age !== null && age > STALE_AGE_MS;
 
   const statusOutput = gitSafe(['status', '--porcelain'], absDir);
-  const hasUncommitted = statusOutput.ok && statusOutput.output.length > 0;
+  const statusLines = statusOutput.ok
+    ? statusOutput.output.split('\n').filter(Boolean)
+    : [];
+  const relevantLines = statusLines.filter(line => {
+    const fileName = line.slice(3);
+    return !META_FILES.some(mf => fileName === mf || fileName.endsWith(`/${mf}`));
+  });
+  const hasUncommitted = relevantLines.length > 0;
 
   let commitCount = 0;
   if (manifest) {

package/skills/README.md

@@ -0,0 +1,19 @@
+# Bundled Local Security Skills
+
+Bug Hunter ships with a local security pack under `skills/` so the repository stays portable and self-contained.
+
+Included skills:
+- `commit-security-scan`
+- `security-review`
+- `threat-model-generation`
+- `vulnerability-validation`
+
+## How They Connect to Bug Hunter
+
+These skills are part of the main Bug Hunter orchestration flow:
+- PR-focused security review routes into `commit-security-scan`
+- `--threat-model` routes into `threat-model-generation`
+- `--security-review` routes into `security-review`
+- `--validate-security` routes into `vulnerability-validation`
+
+Bug Hunter remains the top-level orchestrator. These bundled skills provide focused security workflows and operate on Bug Hunter-native artifacts under `.bug-hunter/`.

package/skills/commit-security-scan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: commit-security-scan
+description: Scan code changes for security vulnerabilities using Bug Hunter-native artifacts and STRIDE context. Use whenever the user asks for PR security review, commit-diff scanning, staged-change security checks, branch-comparison security review, or pre-merge security analysis of changed code.
+---
+
+# Commit Security Scan
+
+This is a bundled local Bug Hunter companion skill. It is portable and self-contained: use `.bug-hunter/*` artifacts, never `.factory/*` paths.
+
+## Purpose
+
+Review *changed code* for security issues only. This skill is optimized for:
+- PR review
+- staged diff review
+- branch diff review
+- commit / commit-range security scanning
+
+## Inputs
+
+Resolve the scan scope from the user request:
+- PR review → use `scripts/pr-scope.cjs`
+- staged review → use `git diff --cached --name-only`
+- branch diff → use `git diff --name-only <base>...<head>`
+- commit range → use `git diff --name-only <base>..<head>`
+
+## Workflow
+
+1. Ensure threat-model context exists.
+   - Preferred artifacts:
+     - `.bug-hunter/threat-model.md`
+     - `.bug-hunter/security-config.json`
+   - If missing, run the bundled `threat-model-generation` skill first.
+
+2. Resolve the changed-file scope.
+
+3. Read the full contents of the changed source files, not just the patch.
+
+4. Focus on STRIDE-oriented issues in changed code:
+   - Spoofing: auth/session/token mistakes
+   - Tampering: SQLi, XSS, path traversal, command injection, mass assignment
+   - Repudiation: security-sensitive actions with no auditability
+   - Information Disclosure: IDOR, secret exposure, verbose errors
+   - DoS: unbounded input, missing limits, expensive regex/queries
+   - Elevation of Privilege: missing authorization, role bypass, privilege escalation
+
+5. Reuse Bug Hunter-native security conventions:
+   - findings should be compatible with `.bug-hunter/findings.json`
+   - use STRIDE + CWE labels
+   - include confidence scores
+
+6. If the user wants only a focused security diff review, stop after the findings report.
+   If the user wants deeper validation, hand off to the bundled `vulnerability-validation` skill.
+
+## Output
+
+Preferred outputs:
+- `.bug-hunter/findings.json` when integrating with the main Bug Hunter pipeline
+- `.bug-hunter/report.md` as a rendered companion if needed
+
+## Notes
+
+- This skill is intentionally diff-scoped; it does not replace full-repository audits.
+- Use it as the lightweight security fast-path before invoking the broader `security-review` flow.

package/skills/security-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: security-review
+description: Run a focused STRIDE-based security review using Bug Hunter-native artifacts. Use whenever the user asks for a full security audit, repository security review, weekly security scan, PR security review with deeper validation, or wants dependency CVEs and threat-model context combined into one workflow.
+---
+
+# Security Review
+
+This is a bundled local Bug Hunter companion skill. It packages a security-focused review workflow without introducing any external marketplace dependency.
+
+## Purpose
+
+Use this skill for deeper security audits than a simple bug hunt, especially when the user wants:
+- a full security review
+- PR security validation
+- weekly security scanning
+- dependency reachability + code review together
+- threat-model-driven analysis
+
+## Workflow
+
+1. Ensure `.bug-hunter/threat-model.md` exists.
+   - If missing, invoke the bundled `threat-model-generation` skill.
+
+2. Determine the scan mode from the request:
+   - PR → diff-scoped review via `commit-security-scan`
+   - staged → staged-only security review
+   - weekly → recent commit range on the default branch
+   - full → full repository security audit
+
+3. If dependency scanning is relevant, run:
+   - `node scripts/dep-scan.cjs --target <path> --output .bug-hunter/dep-findings.json`
+
+4. Scan code for STRIDE threats using Bug Hunter-native conventions.
+   Reuse:
+   - `.bug-hunter/triage.json`
+   - `.bug-hunter/threat-model.md`
+   - `.bug-hunter/security-config.json`
+   - `.bug-hunter/dep-findings.json`
+
+5. Validate severe findings using the bundled `vulnerability-validation` skill.
+
+6. Produce structured outputs compatible with the Bug Hunter pipeline.
+
+## Outputs
+
+Primary artifacts should stay inside `.bug-hunter/`:
+- `.bug-hunter/findings.json`
+- `.bug-hunter/referee.json`
+- `.bug-hunter/report.md`
+- `.bug-hunter/dep-findings.json` when dependency review is enabled
+- `.bug-hunter/fix-strategy.json` if the user wants remediation planning
+
+## Important constraints
+
+- Keep all paths Bug Hunter-native; do not emit `.factory/*` artifacts.
+- Prefer validated, exploitability-aware findings over raw volume.
+- For patching requests, hand findings back to the normal Bug Hunter fix pipeline rather than inventing a second patch system.

package/skills/threat-model-generation/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: threat-model-generation
+description: Generate or refresh a STRIDE-based threat model for the current repository using Bug Hunter-native artifacts. Use whenever the repository has no threat model yet, the architecture changed materially, a security review needs fresh trust-boundary context, or the user explicitly asks for a threat model.
+---
+
+# Threat Model Generation
+
+This is a bundled local Bug Hunter companion skill. It generates portable threat-model artifacts under `.bug-hunter/`.
+
+## Purpose
+
+Create the security context that the other security skills depend on:
+- trust boundaries
+- major components
+- STRIDE threats
+- vulnerability pattern library
+- severity/config defaults
+
+## Required outputs
+
+Write:
+- `.bug-hunter/threat-model.md`
+- `.bug-hunter/security-config.json`
+
+## Workflow
+
+1. Read `.bug-hunter/triage.json` if available for file structure and domain hints.
+2. Inspect the repository to identify:
+   - languages and frameworks
+   - public/authenticated/internal entry points
+   - data stores and external integrations
+   - sensitive assets and trust boundaries
+3. Generate a concise STRIDE threat model.
+4. Generate a matching security config with thresholds and tech-stack metadata.
+
+## Existing implementation hooks
+
+Bug Hunter already has a native prompt for this capability:
+- `prompts/threat-model.md`
+
+Prefer reusing that prompt structure and artifact conventions rather than inventing a second format.
+
+## Output rules
+
+- Keep the threat model short enough for downstream agents to consume.
+- Be specific about trust boundaries and vulnerable code patterns.
+- Keep all artifacts under `.bug-hunter/`, never `.factory/`.

package/skills/vulnerability-validation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: vulnerability-validation
+description: Validate security findings for exploitability, reachability, and real-world impact using Bug Hunter-native findings artifacts. Use after security scans, before patch generation, or whenever the user wants confirmation that a suspected vulnerability is actually exploitable.
+---
+
+# Vulnerability Validation
+
+This is a bundled local Bug Hunter companion skill. It strengthens the security-specific parts of the Skeptic/Referee process.
+
+## Purpose
+
+Take suspected or confirmed security findings and answer:
+- Is the vulnerable path reachable?
+- Can an attacker control the input?
+- Are there existing mitigations?
+- How exploitable is it really?
+- What is the CVSS / PoC / impact level?
+
+## Inputs
+
+Prefer Bug Hunter-native artifacts:
+- `.bug-hunter/findings.json`
+- `.bug-hunter/threat-model.md`
+- `.bug-hunter/security-config.json`
+- `.bug-hunter/dep-findings.json` when dependency issues are involved
+
+## Workflow
+
+1. Read the findings and isolate the security ones.
+2. Trace reachability:
+   - EXTERNAL
+   - AUTHENTICATED
+   - INTERNAL
+   - UNREACHABLE
+3. Trace exploitability:
+   - EASY
+   - MEDIUM
+   - HARD
+   - NOT_EXPLOITABLE
+4. Check for mitigations already present in code, framework behavior, or deployment assumptions.
+5. For confirmed HIGH/CRITICAL security bugs, generate:
+   - exploitation path
+   - benign proof of concept
+   - CVSS vector + score
+6. Feed the result back into Bug Hunter-native verdicting.
+
+## Outputs
+
+When used as a companion to the main pipeline, keep outputs compatible with:
+- `.bug-hunter/referee.json`
+- `.bug-hunter/report.md`
+
+If a separate validation artifact is helpful for the run, place it under `.bug-hunter/validated-findings.json`.
+
+## Important constraints
+
+- This skill validates findings; it does not replace the normal fix pipeline.
+- Keep outputs portable and self-contained under `.bug-hunter/`.
+- Prefer explicit reasoning for false positives so the user can trust dismissals.

package/templates/subagent-wrapper.md

@@ -76,6 +76,8 @@ If worktree rules are provided above (non-empty), these apply:
 
 **Write your complete output to:** `{OUTPUT_FILE_PATH}`
 
+**Artifact name for validation:** `{OUTPUT_ARTIFACT}`
+
 Follow the output format specified in your system prompt EXACTLY.
 The orchestrator will read this file to pass your results to the next pipeline phase.
 
@@ -84,12 +86,18 @@ If the file path directory does not exist, create it first:
 mkdir -p "$(dirname '{OUTPUT_FILE_PATH}')"
 ```
 
+After writing the canonical artifact, validate it before you stop:
+```bash
+node "{SKILL_DIR}/scripts/schema-validate.cjs" "{OUTPUT_ARTIFACT}" "{OUTPUT_FILE_PATH}"
+```
+
 ## Completion
 
 When you have finished your analysis:
 1. Write your report to `{OUTPUT_FILE_PATH}`
-2. Output a brief summary to stdout (one paragraph)
-3. Stop. Do not continue to other phases.
+2. Validate the artifact with `schema-validate.cjs`
+3. Output a brief summary to stdout (one paragraph)
+4. Stop. Do not continue to other phases.
 
 ---
 
@@ -106,4 +114,5 @@ When you have finished your analysis:
 | `{RISK_MAP}` | Recon output risk classification | From `.bug-hunter/recon.md` |
 | `{TECH_STACK}` | Framework, auth, DB, key dependencies | "Express + JWT + Prisma + Redis" |
 | `{PHASE_SPECIFIC_CONTEXT}` | Extra context for this phase | For Skeptic: the Hunter findings. For Referee: findings + Skeptic challenges. |
-| `{OUTPUT_FILE_PATH}` | Where to write the output | `.bug-hunter/findings.md` |
+| `{OUTPUT_FILE_PATH}` | Where to write the canonical artifact | `.bug-hunter/findings.json` |
+| `{OUTPUT_ARTIFACT}` | Artifact name passed to `schema-validate.cjs` | `findings`, `skeptic`, `referee`, `fix-report` |