@hone-ai/cli 1.4.0

package/lib/ci-failures.js

@@ -0,0 +1,173 @@
+'use strict';
+/**
+ * ci-failures.js — H-010 CI failures feedback loop helpers.
+ *
+ * Pure helpers — no I/O. Caller (hone-cli.js) reads/writes the jsonl file.
+ *
+ * Storage shape (per issue #19): .github/learnings/ci-failures.jsonl
+ *   One JSON object per line (NDJSON).
+ *   Required fields: tool, rule, timestamp.
+ *   Optional: file, line, message, story_id, severity, category.
+ *
+ * Closes #19 parts 1+2 (record + summarize). Parts 3 (auto-derive) and
+ * 4 (server round-trip = #22 H-013) deferred.
+ *
+ * 7th instance of pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after auto-detect.js (H-018), learnings-parse.js (H-035),
+ * pipeline-status.js (H-009), metrics-collect.js (H-008),
+ * config-update.js (H-021), ci-classifier.js (H-061).
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// appendFailure — append one NDJSON entry to existing text
+// ─────────────────────────────────────────────────────────────────────
+//   Returns new text (caller writes to disk). Stamps timestamp if absent.
+function appendFailure(existingText, entry) {
+  if (typeof existingText !== 'string') existingText = '';
+  if (!entry || typeof entry !== 'object') return existingText;
+
+  const stamped = {
+    timestamp: entry.timestamp || new Date().toISOString(),
+    ...entry,
+  };
+  // Ensure timestamp is at the front for readability when grep'd
+  const ordered = { timestamp: stamped.timestamp };
+  for (const [k, v] of Object.entries(stamped)) {
+    if (k !== 'timestamp') ordered[k] = v;
+  }
+  const line = JSON.stringify(ordered);
+
+  // Ensure existing text ends with newline before appending
+  const sep = existingText.length > 0 && !existingText.endsWith('\n') ? '\n' : '';
+  return existingText + sep + line + '\n';
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// loadFailures — parse NDJSON; skip malformed lines gracefully (E2)
+// ─────────────────────────────────────────────────────────────────────
+//   Returns { failures: FailureEntry[], malformedCount: number }.
+function loadFailures(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { failures: [], malformedCount: 0 };
+  }
+  const failures = [];
+  let malformedCount = 0;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object') {
+        failures.push(parsed);
+      } else {
+        malformedCount++;
+      }
+    } catch {
+      malformedCount++;
+    }
+  }
+  return { failures, malformedCount };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// groupByToolRule — aggregate by `${tool}:${rule}` key
+// ─────────────────────────────────────────────────────────────────────
+function groupByToolRule(failures) {
+  const out = new Map();
+  for (const f of failures || []) {
+    const key = `${f.tool || 'unknown'}:${f.rule || 'unknown'}`;
+    if (!out.has(key)) out.set(key, []);
+    out.get(key).push(f);
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// findRecurring — groups with count >= threshold, optionally within sinceDays
+// ─────────────────────────────────────────────────────────────────────
+//   Returns { key, count, latestTimestamp, entries }[] sorted desc by count.
+function findRecurring(failures, opts = {}) {
+  const threshold = opts.threshold || 3;
+  const sinceDays = opts.sinceDays;
+
+  let pool = failures || [];
+  if (sinceDays != null) {
+    const cutoff = Date.now() - sinceDays * 86400000;
+    pool = pool.filter(f => {
+      if (!f.timestamp) return false;
+      const t = new Date(f.timestamp).getTime();
+      return Number.isFinite(t) && t >= cutoff;
+    });
+  }
+
+  const groups = groupByToolRule(pool);
+  const result = [];
+  for (const [key, entries] of groups.entries()) {
+    if (entries.length >= threshold) {
+      const latestTimestamp = entries
+        .map(e => e.timestamp)
+        .filter(Boolean)
+        .sort()
+        .pop() || null;
+      result.push({
+        key,
+        count: entries.length,
+        latestTimestamp,
+        entries,
+      });
+    }
+  }
+  return result.sort((a, b) => b.count - a.count);
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// summarize — human-readable summary string
+// ─────────────────────────────────────────────────────────────────────
+function summarize(failures, opts = {}) {
+  const threshold = opts.threshold || 3;
+  const sinceDays = opts.sinceDays || 30;
+
+  const lines = [];
+  lines.push(`CI failures summary`);
+  lines.push(`==================`);
+  lines.push(`Total entries: ${failures.length}`);
+
+  const groups = groupByToolRule(failures);
+  lines.push(`Distinct tool:rule pairs: ${groups.size}`);
+  lines.push('');
+
+  // All-time top groups
+  const sorted = [...groups.entries()]
+    .map(([key, entries]) => ({ key, count: entries.length }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  if (sorted.length > 0) {
+    lines.push(`Top tool:rule pairs (all-time):`);
+    for (const g of sorted) {
+      lines.push(`  ${g.count.toString().padStart(4)} × ${g.key}`);
+    }
+    lines.push('');
+  }
+
+  const recurring = findRecurring(failures, { threshold, sinceDays });
+  if (recurring.length > 0) {
+    lines.push(`Recurring patterns (≥${threshold} occurrences in last ${sinceDays} days):`);
+    for (const r of recurring) {
+      lines.push(`  ${r.count.toString().padStart(4)} × ${r.key}  (latest: ${r.latestTimestamp || 'unknown'})`);
+    }
+    lines.push('');
+    lines.push(`Consider adding patterns from the above to .github/skills/ via \`hone derive\`.`);
+  } else {
+    lines.push(`No recurring patterns (threshold ${threshold} in last ${sinceDays} days).`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  appendFailure,
+  loadFailures,
+  groupByToolRule,
+  findRecurring,
+  summarize,
+};

package/lib/claude-md-tokens.js

@@ -0,0 +1,71 @@
+'use strict';
+/**
+ * claude-md-tokens.js — H-002b CLAUDE.md template token substitution.
+ *
+ * Pure helpers — no I/O. Caller (hone-cli.js setup command) reads the
+ * template, calls substituteClaudeMdTokens, writes the result.
+ *
+ * Closes #54 deliverable 4 (CLAUDE.md `{{TEST_COMMAND}}` substitution).
+ *
+ * 13th instance of pure-helpers + thin-CLI-shell pattern.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// CLAUDE_MD_TOKENS — canonical token list (extend in v2 stories)
+// ─────────────────────────────────────────────────────────────────────
+const CLAUDE_MD_TOKENS = ['TEST_COMMAND', 'LINT_COMMAND', 'PRIMARY_STACK'];
+
+// ─────────────────────────────────────────────────────────────────────
+// STACK_VARS — per-stack defaults
+// ─────────────────────────────────────────────────────────────────────
+//   Returns the values for {{TEST_COMMAND}} / {{LINT_COMMAND}} /
+//   {{PRIMARY_STACK}} per detected primary stack. Falls back to node
+//   for unknown stacks (graceful — see E5).
+const STACK_VARS = {
+  python:     { TEST_COMMAND: 'pytest',                 LINT_COMMAND: 'ruff check',          PRIMARY_STACK: 'python' },
+  node:       { TEST_COMMAND: 'npm test',               LINT_COMMAND: 'npm run lint',        PRIMARY_STACK: 'node' },
+  'react-vite': { TEST_COMMAND: 'npm test',             LINT_COMMAND: 'npm run lint',        PRIMARY_STACK: 'react-vite' },
+  react:      { TEST_COMMAND: 'npm test',               LINT_COMMAND: 'npm run lint',        PRIMARY_STACK: 'react' },
+  nextjs:     { TEST_COMMAND: 'npm test',               LINT_COMMAND: 'npm run lint',        PRIMARY_STACK: 'nextjs' },
+  nestjs:     { TEST_COMMAND: 'npm test',               LINT_COMMAND: 'npm run lint',        PRIMARY_STACK: 'nestjs' },
+  java:       { TEST_COMMAND: 'mvn test',               LINT_COMMAND: 'mvn checkstyle:check', PRIMARY_STACK: 'java' },
+  dotnet:     { TEST_COMMAND: 'dotnet test',            LINT_COMMAND: 'dotnet format --verify-no-changes', PRIMARY_STACK: 'dotnet' },
+  salesforce: { TEST_COMMAND: 'sfdx force:lightning:lwc:test:run', LINT_COMMAND: 'eslint **/*.js', PRIMARY_STACK: 'salesforce' },
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// getClaudeMdVarsForStack — returns the {TEST,LINT,STACK} object
+// ─────────────────────────────────────────────────────────────────────
+function getClaudeMdVarsForStack(stack) {
+  if (stack && STACK_VARS[stack]) return { ...STACK_VARS[stack] };
+  // E5 graceful fallback: unknown stack → node defaults
+  return { ...STACK_VARS.node };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// substituteClaudeMdTokens — replace {{KNOWN_TOKEN}} occurrences
+// ─────────────────────────────────────────────────────────────────────
+//   Only replaces tokens that have a value in the vars object.
+//   Unknown {{TOKEN}}s are left intact (E4 — future-proof for new
+//   stories that may add tokens not yet in this list).
+function substituteClaudeMdTokens(template, vars = {}) {
+  if (typeof template !== 'string') return template;
+  let out = template;
+  for (const [key, value] of Object.entries(vars)) {
+    if (value == null) continue;
+    const re = new RegExp(`\\{\\{${escapeRegex(key)}\\}\\}`, 'g');
+    out = out.replace(re, String(value));
+  }
+  return out;
+}
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  CLAUDE_MD_TOKENS,
+  STACK_VARS,
+  getClaudeMdVarsForStack,
+  substituteClaudeMdTokens,
+};

package/lib/compliance-check.js

@@ -0,0 +1,62 @@
+'use strict';
+/**
+ * compliance-check.js — H-011 pipeline-compliance pre-commit check.
+ *
+ * Pure helper — no I/O at the helper layer. Caller (hone-cli.js) does
+ * git symbolic-ref + filesystem checks; passes results in.
+ *
+ * Closes #20 sub-tasks (a) CLI command + (b) docs example. Sub-task
+ * (c) `hone setup --pre-commit` flag deferred to a follow-up.
+ *
+ * Reuses H-009's STORY_ID_PATTERN regex for branch → STORY-ID
+ * extraction (DRY — same canonical pattern as H-005 substitutes into
+ * ai-review.yml at install time).
+ *
+ * 11th instance of pure-helpers + thin-CLI-shell pattern.
+ */
+
+const path = require('path');
+const { extractStoryIdFromBranch } = require('./pipeline-status');
+
+// ─────────────────────────────────────────────────────────────────────
+// evaluateCompliance — pure compliance evaluator
+// ─────────────────────────────────────────────────────────────────────
+//   inputs:
+//     branch: string | null    (current git branch; null/empty for detached HEAD)
+//     pipelineRoot: string     (path to .github/pipeline/, used to compute `expected`)
+//     fileExists: (path) => bool   (caller's filesystem checker — testable)
+//
+//   returns: { compliant, reason, storyId, expected? }
+//   reasons:
+//     'no-story-id'      → branch has no STORY-ID pattern (graceful pass)
+//     'no-pipeline-dir'  → .github/pipeline/ missing (graceful pass — fresh repo)
+//     'ok'               → STORY-ID present + step-0-grooming.md exists
+//     'missing-grooming' → STORY-ID present + step-0-grooming.md missing (FAIL)
+function evaluateCompliance({ branch, pipelineRoot, fileExists } = {}) {
+  // 1. Empty/null branch → detached HEAD or no git → graceful pass
+  if (!branch || typeof branch !== 'string' || branch.length === 0) {
+    return { compliant: true, reason: 'no-story-id', storyId: null };
+  }
+
+  // 2. Branch has no STORY-ID pattern → graceful pass (chore branches OK)
+  const storyId = extractStoryIdFromBranch(branch);
+  if (!storyId) {
+    return { compliant: true, reason: 'no-story-id', storyId: null };
+  }
+
+  // 3. Pipeline dir missing → fresh repo, hasn't run hone setup yet → graceful pass
+  if (typeof fileExists !== 'function' || !fileExists(pipelineRoot)) {
+    return { compliant: true, reason: 'no-pipeline-dir', storyId };
+  }
+
+  // 4. Check the canonical step-0 artifact
+  const expected = path.join(pipelineRoot, storyId, 'step-0-grooming.md');
+  if (fileExists(expected)) {
+    return { compliant: true, reason: 'ok', storyId };
+  }
+
+  // 5. STORY-ID + pipeline dir present, but no grooming → FAIL
+  return { compliant: false, reason: 'missing-grooming', storyId, expected };
+}
+
+module.exports = { evaluateCompliance };

package/lib/config-augment.js

@@ -0,0 +1,133 @@
+'use strict';
+/**
+ * config-augment.js — HC-013a surgical YAML insert/replace for platform
+ * discovery sections in .pipeline-config.yml.
+ *
+ * Pure helper — no I/O. Caller reads + writes the file.
+ *
+ * Same pattern as config-update.js (H-021): surgical regex preserves
+ * adopter comments + structure. Never uses yaml.dump round-trip.
+ *
+ * Two modes:
+ *   INSERT — config has platform.detected but no HC-013 marker → add sections
+ *   REPLACE — config has HC-013 marker → replace managed sections, preserve rest
+ *
+ * Architecture: docs/architecture/platform-auto-discovery-v1.md (HC-013)
+ */
+
+/**
+ * Format metadata_types as YAML text.
+ */
+function formatMetadataTypes(mt) {
+  if (!mt) return '    code: []\n    config: []\n    test: []';
+  const lines = [];
+  for (const cat of ['code', 'config', 'test']) {
+    const items = mt[cat] || [];
+    if (items.length === 0) {
+      lines.push(`    ${cat}: []`);
+    } else {
+      lines.push(`    ${cat}:`);
+      for (const item of items) {
+        lines.push(`      - { type: ${item.type}, path: "${item.path}", count: ${item.count} }`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format the managed platform block (everything between marker and next top-level key).
+ */
+function formatManagedBlock(data) {
+  const lines = [];
+  lines.push(`  # HC-013: Auto-discovered platform grounding`);
+  lines.push(`  discovered_at: "${data.discovered_at}"`);
+
+  // source_roots
+  if (data.source_roots && data.source_roots.length > 0) {
+    lines.push(`  source_roots:`);
+    for (const r of data.source_roots) lines.push(`    - "${r}"`);
+  } else {
+    lines.push(`  source_roots: []`);
+  }
+
+  // metadata_types
+  lines.push(`  metadata_types:`);
+  lines.push(formatMetadataTypes(data.metadata_types));
+
+  // config_paths
+  if (data.config_paths && data.config_paths.length > 0) {
+    lines.push(`  config_paths:`);
+    for (const p of data.config_paths) lines.push(`    - "${p}"`);
+  } else {
+    lines.push(`  config_paths: []`);
+  }
+
+  // doc_registry
+  if (data.doc_registry && data.doc_registry.length > 0) {
+    lines.push(`  doc_registry:`);
+    for (const d of data.doc_registry) lines.push(`    - ${d}`);
+  } else {
+    lines.push(`  doc_registry: []`);
+  }
+
+  // mcp
+  const mcp = data.mcp || {};
+  lines.push(`  mcp:`);
+  lines.push(`    enabled: ${mcp.enabled || false}`);
+  if (mcp.server) lines.push(`    server: "${mcp.server}"`);
+  if (mcp.capabilities && mcp.capabilities.length > 0) {
+    lines.push(`    capabilities: [${mcp.capabilities.join(', ')}]`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Surgically insert or replace platform discovery sections.
+ *
+ * @param {string|null} configText — raw .pipeline-config.yml content
+ * @param {object} data — platform discovery data
+ * @param {string} data.discovered_at — ISO timestamp
+ * @param {string[]} data.source_roots — from project descriptor
+ * @param {object} data.metadata_types — { code: [...], config: [...], test: [...] }
+ * @param {string[]} data.config_paths — regex patterns for classifier
+ * @param {string[]} data.doc_registry — platform keys for doc registry
+ * @param {object} data.mcp — { enabled, server, capabilities }
+ * @returns {string|null} — augmented config text, or original if no platform section
+ */
+function augmentPlatformConfig(configText, data) {
+  if (typeof configText !== 'string') return configText;
+  if (!data) return configText;
+
+  // Check if platform: section exists
+  if (!/^platform:/m.test(configText)) return configText;
+
+  const managedBlock = formatManagedBlock(data);
+
+  // REPLACE mode: HC-013 marker exists → replace from marker to next top-level key
+  if (configText.includes('# HC-013:')) {
+    // Find the marker and replace everything from it to the next top-level key
+    // (a line starting with a non-space character that isn't part of the platform block)
+    const replaced = configText.replace(
+      /  # HC-013:[^\n]*\n(?:  [^\n]*\n)*/,
+      managedBlock + '\n'
+    );
+    return replaced;
+  }
+
+  // INSERT mode: no marker → insert after platform.detected block
+  // Remove commented config_paths template if present
+  let text = configText.replace(/  # config_paths:\n(?:  #[^\n]*\n)*/g, '');
+
+  // Find the end of the detected: block (after all "    - platform" lines)
+  // Insert the managed block after it
+  const insertPoint = text.replace(
+    /(^platform:\n  detected:\n(?:    - [^\n]+\n)+)/m,
+    `$1${managedBlock}\n`
+  );
+
+  return insertPoint;
+}
+
+module.exports = { augmentPlatformConfig, formatMetadataTypes, formatManagedBlock };

package/lib/config-update.js

@@ -0,0 +1,70 @@
+'use strict';
+/**
+ * config-update.js — H-021 surgical edits to .github/.pipeline-config.yml.
+ * Pure helpers — no I/O. Caller (hone-cli.js) reads + writes the file.
+ *
+ * Why surgical regex (not yaml.dump round-trip): adopters' .pipeline-config.yml
+ * has rich comments documenting intent. js-yaml.dump strips them all.
+ * For single-field updates, regex preserves comments + structure.
+ *
+ * 5th instance of the pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after auto-detect.js (H-018), learnings-parse.js (H-035),
+ * pipeline-status.js (H-009), metrics-collect.js (H-008).
+ *
+ * Closes #31.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// stampLastDerived — replace `skill_refresh.last_derived: <old>` with new ISO.
+// ─────────────────────────────────────────────────────────────────────
+//   Returns { text, updated }:
+//     - updated=true  if the `last_derived:` line was found + replaced
+//     - updated=false if the line was absent (graceful no-op for caller)
+//
+// Preserves all comments + other fields by doing a single-line regex replace.
+function stampLastDerived(configText, isoTimestamp) {
+  if (typeof configText !== 'string' || !isoTimestamp) {
+    return { text: configText, updated: false };
+  }
+  const re = /^(\s*last_derived:\s*).*$/m;
+  if (!re.test(configText)) {
+    return { text: configText, updated: false };
+  }
+  const newText = configText.replace(re, `$1"${isoTimestamp}"`);
+  return { text: newText, updated: true };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// stampLastDerivedSrcFiles — H-015 — REPLACE existing or INSERT after `last_derived:`
+// ─────────────────────────────────────────────────────────────────────
+//   Returns { text, updated }:
+//     - updated=true if the line was replaced (existing) or inserted
+//       (forward-compat for adopters whose .pipeline-config.yml predates
+//       H-015's schema addition)
+//     - updated=false if neither `last_derived_src_files:` nor `last_derived:`
+//       are present (graceful — caller handles)
+function stampLastDerivedSrcFiles(configText, count) {
+  if (typeof configText !== 'string' || count == null) {
+    return { text: configText, updated: false };
+  }
+  // First: replace existing line in place
+  const replaceRe = /^(\s*last_derived_src_files:\s*).*$/m;
+  if (replaceRe.test(configText)) {
+    return {
+      text: configText.replace(replaceRe, `$1${count}`),
+      updated: true,
+    };
+  }
+  // Otherwise: insert immediately after `last_derived:` line, preserving
+  // its indentation (2 spaces under `skill_refresh:` per the schema docs)
+  const insertRe = /^(\s*last_derived:[^\n]*)$/m;
+  if (insertRe.test(configText)) {
+    return {
+      text: configText.replace(insertRe, `$1\n  last_derived_src_files: ${count}`),
+      updated: true,
+    };
+  }
+  return { text: configText, updated: false };
+}
+
+module.exports = { stampLastDerived, stampLastDerivedSrcFiles };

package/lib/dependency-audit.js

@@ -0,0 +1,108 @@
+'use strict';
+/**
+ * dependency-audit.js — HC-023 npm audit + pip-audit integration.
+ *
+ * Pure helper with injected I/O (exec + fileExists).
+ * Runs package manager audit commands and parses structured output.
+ * Graceful degradation: if tool is missing, returns skipped (not failed).
+ *
+ * Architecture: docs/architecture/master-roadmap.md (Epic 2, HC-023)
+ */
+
+/**
+ * Run dependency audit for the detected stack.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot
+ * @param {string} opts.stack — 'node' | 'python' | etc.
+ * @param {(cmd: string) => {stdout: string, exitCode: number}} [opts.exec]
+ * @param {(relativePath: string) => boolean} [opts.fileExists]
+ * @returns {{ passed: boolean, findings: Array, skipped?: boolean, reason?: string }}
+ */
+function runDependencyAudit(opts = {}) {
+  const { stack, exec, fileExists } = opts;
+
+  if (typeof exec !== 'function' || typeof fileExists !== 'function') {
+    return { passed: true, findings: [], skipped: true, reason: 'exec or fileExists not provided' };
+  }
+
+  switch (stack) {
+    case 'node': return auditNode(exec, fileExists);
+    case 'python': return auditPython(exec, fileExists);
+    default: return { passed: true, findings: [], skipped: true, reason: `no audit tool for stack: ${stack}` };
+  }
+}
+
+function auditNode(exec, fileExists) {
+  if (!fileExists('package-lock.json') && !fileExists('yarn.lock')) {
+    return { passed: true, findings: [], skipped: true, reason: 'no lock file found (package-lock.json or yarn.lock)' };
+  }
+
+  try {
+    const result = exec('npm audit --json 2>/dev/null');
+    const parsed = JSON.parse(result.stdout);
+    const vulns = parsed.vulnerabilities || {};
+    const findings = [];
+
+    for (const [pkg, info] of Object.entries(vulns)) {
+      findings.push({
+        package: pkg,
+        severity: info.severity || 'unknown',
+        fixAvailable: !!info.fixAvailable,
+        via: Array.isArray(info.via) ? info.via.filter(v => typeof v === 'string') : [],
+      });
+    }
+
+    const hasHighOrCritical = findings.some(f =>
+      f.severity === 'high' || f.severity === 'critical'
+    );
+
+    return {
+      passed: !hasHighOrCritical,
+      findings,
+      summary: findings.length === 0
+        ? 'No known vulnerabilities.'
+        : `${findings.length} vulnerabilities found (${findings.filter(f => f.severity === 'critical').length} critical, ${findings.filter(f => f.severity === 'high').length} high).`,
+    };
+  } catch (e) {
+    return { passed: true, findings: [], skipped: true, reason: `npm audit failed: ${e.message}` };
+  }
+}
+
+function auditPython(exec, fileExists) {
+  if (!fileExists('requirements.txt') && !fileExists('pyproject.toml')) {
+    return { passed: true, findings: [], skipped: true, reason: 'no requirements.txt or pyproject.toml found' };
+  }
+
+  try {
+    const result = exec('pip-audit --format=json 2>/dev/null');
+    const parsed = JSON.parse(result.stdout);
+    const findings = [];
+
+    if (Array.isArray(parsed)) {
+      for (const item of parsed) {
+        for (const vuln of (item.vulns || [])) {
+          findings.push({
+            package: item.name,
+            version: item.version,
+            severity: 'high', // pip-audit doesn't always provide severity
+            advisory: vuln.id,
+            fixVersions: vuln.fix_versions || [],
+          });
+        }
+      }
+    }
+
+    return {
+      passed: findings.length === 0,
+      findings,
+      summary: findings.length === 0
+        ? 'No known vulnerabilities.'
+        : `${findings.length} vulnerabilities found.`,
+    };
+  } catch (e) {
+    return { passed: true, findings: [], skipped: true, reason: `pip-audit failed: ${e.message}` };
+  }
+}
+
+module.exports = { runDependencyAudit };