wolverine-ai 1.7.1 → 1.8.0

package/README.md

@@ -204,7 +204,7 @@ The error hook auto-patches Fastify and Express via `--require` preload. No midd
 
 ## Agent Tool Harness
 
-The AI agent has 16 built-in tools (inspired by [claw-code](https://github.com/ultraworkers/claw-code)):
+The AI agent has 18 built-in tools (inspired by [claw-code](https://github.com/ultraworkers/claw-code)):
 
 | Tool | Category | Description |
 |------|----------|-------------|
@@ -222,6 +222,8 @@ The AI agent has 16 built-in tools (inspired by [claw-code](https://github.com/u
 | `run_db_fix` | Database | UPDATE/DELETE/INSERT/ALTER on SQLite (auto-backup before write) |
 | `check_port` | Diagnostic | Check if a port is in use and by what process |
 | `check_env` | Diagnostic | Check environment variables (values auto-redacted) |
+| `audit_deps` | Deps | Full health check: vulnerabilities, outdated, peer conflicts, unused |
+| `check_migration` | Deps | Known upgrade paths (express→fastify, moment→dayjs, etc.) |
 | `web_fetch` | Research | Fetch URL content for documentation/research |
 | `done` | Control | Signal task completion with summary |
 
@@ -492,6 +494,19 @@ Auto-discovered from `src/skills/`. Each skill exports metadata for the registry
 - **db.idempotent(key, fn)** — Database-level dedup for critical writes (payments, orders)
 - Auto-injected into agent prompts when building database features
 
+### Dependency Manager (`src/skills/deps.js`)
+- **diagnose()** — structured diagnosis of dependency errors before AI runs (zero tokens)
+- **healthReport()** — full audit: vulnerabilities, outdated, peer conflicts, unused packages, lock file, health score
+- **getMigration()** — known upgrade paths with code transformation patterns:
+
+| From | To | Why |
+|------|----|-----|
+| `express` | `fastify` | 5.6x faster, async-first, built-in validation |
+| `moment` | `dayjs` | Maintenance mode, 70KB → 2KB |
+| `request` | `node-fetch` | Deprecated since 2020 |
+| `body-parser` | built-in | Included in Express 4.16+ / Fastify |
+| callbacks | `async/await` | Cleaner error handling, no callback hell |
+
 Add new skills by creating a file in `src/skills/` with `SKILL_NAME`, `SKILL_DESCRIPTION`, `SKILL_KEYWORDS`, `SKILL_USAGE` exports.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {

package/src/agent/agent-engine.js

@@ -261,6 +261,33 @@ const TOOL_DEFINITIONS = [
       },
     },
   },
+  // ── DEPENDENCY MANAGEMENT ──
+  {
+    type: "function",
+    function: {
+      name: "audit_deps",
+      description: "Run a full dependency health check: npm audit (vulnerabilities), outdated packages, peer dep conflicts, unused packages, lock file status. Returns a health score and actionable fixes. Use BEFORE editing code when the error might be a dependency issue.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "check_migration",
+      description: "Check if a package has a known migration/upgrade path. Use when a deprecated API or old package is causing errors. Returns the recommended replacement and code transformation patterns.",
+      parameters: {
+        type: "object",
+        properties: {
+          package: { type: "string", description: "Package name to check (e.g. 'express', 'moment', 'request')" },
+        },
+        required: ["package"],
+      },
+    },
+  },
   // ── COMPLETION ──
   {
     type: "function",
@@ -352,6 +379,10 @@ DIAGNOSTICS:
 - check_port: Check if a port is in use and by what process
 - check_env: Check environment variables (values auto-redacted for security)
 
+DEPENDENCY MANAGEMENT:
+- audit_deps: Full health check (vulnerabilities, outdated, peer conflicts, unused). Use FIRST for dependency errors.
+- check_migration: Check if a package has a known upgrade path (express→fastify, moment→dayjs, etc.)
+
 RESEARCH:
 - web_fetch: Fetch a URL (docs, npm packages, error solutions)
 
@@ -365,7 +396,7 @@ RESEARCH:
 
 | Error Pattern | Category | Diagnostic Steps | Fix |
 |---|---|---|---|
-| Cannot find module 'X' | DEPENDENCY | check package.json | bash_exec: npm install X |
+| Cannot find module 'X' | DEPENDENCY | audit_deps first, check package.json | bash_exec: npm install X |
 | Cannot find module './X' | IMPORT | glob_files to find real path | edit_file: fix require path |
 | ENOENT: no such file | FILE MISSING | list_dir to check structure | write_file or move_file |
 | EACCES/EPERM | PERMISSION | bash_exec: ls -la | bash_exec: chmod 755 |
@@ -530,6 +561,8 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
       case "check_env":     return this._checkEnv(args);
       case "inspect_db":    return this._inspectDb(args);
       case "run_db_fix":    return this._runDbFix(args);
+      case "audit_deps":    return this._auditDeps(args);
+      case "check_migration": return this._checkMigration(args);
       case "done":          return this._done(args);
       // Legacy aliases
       case "list_files":    return this._globFiles({ pattern: (args.dir || ".") + "/*" + (args.pattern || "") });
@@ -932,6 +965,52 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
     } catch (e) { return { content: `DB error: ${e.message}` }; }
   }
 
+  _auditDeps() {
+    try {
+      const { healthReport } = require("../skills/deps");
+      const report = healthReport(this.cwd);
+      const { redact } = require("../security/secret-redactor");
+      const lines = [
+        `Dependency Health Score: ${report.score}/100 (${report.summary})`,
+        "",
+        `Vulnerabilities: ${report.audit.vulnerabilities} (${report.audit.critical} critical, ${report.audit.high} high, ${report.audit.moderate} moderate)`,
+        report.audit.fixes.length > 0 ? `Fix: ${report.audit.fixes.join(", ")}` : "",
+        "",
+        `Outdated: ${report.outdated.length} packages`,
+        ...report.outdated.slice(0, 10).map(p => `  ${p.name}: ${p.current} → ${p.latest}`),
+        report.outdated.length > 10 ? `  ... and ${report.outdated.length - 10} more` : "",
+        "",
+        `Peer Dependency Issues: ${report.peerDeps.length}`,
+        ...report.peerDeps.slice(0, 5).map(p => `  ${p.package}: ${p.requires}`),
+        "",
+        `Unused Packages: ${report.unused.length}`,
+        report.unused.length > 0 ? `  ${report.unused.join(", ")}` : "",
+        "",
+        `Lock File: ${report.lockFile.healthy ? "OK" : report.lockFile.issue}`,
+        report.lockFile.fix ? `  Fix: ${report.lockFile.fix}` : "",
+      ].filter(l => l !== undefined);
+      console.log(chalk.gray(`    📦 Deps audit: score ${report.score}/100, ${report.audit.vulnerabilities} vulns, ${report.outdated.length} outdated`));
+      return { content: redact(lines.join("\n")) };
+    } catch (e) { return { content: `Deps audit error: ${e.message}` }; }
+  }
+
+  _checkMigration(args) {
+    try {
+      const { getMigration } = require("../skills/deps");
+      const migration = getMigration(args.package);
+      if (!migration) return { content: `No known migration path for '${args.package}'.` };
+      const lines = [
+        `Migration: ${args.package} → ${migration.to}`,
+        `Reason: ${migration.reason}`,
+        "",
+        "Code patterns:",
+        ...migration.patterns.map(p => `  ${p.from}\n  → ${p.to}`),
+      ];
+      console.log(chalk.gray(`    📦 Migration: ${args.package} → ${migration.to}`));
+      return { content: lines.join("\n") };
+    } catch (e) { return { content: `Migration check error: ${e.message}` }; }
+  }
+
   _done(args) {
     console.log(chalk.green(`    ✅ Agent done: ${args.summary}`));
     if (this.logger) {

package/src/agent/sub-agents.js

@@ -23,9 +23,9 @@ const { getModel } = require("../core/models");
 
 // Tool restrictions per agent type (claw-code: allowed_tools_for_subagent)
 const AGENT_TOOL_SETS = {
-  explore: ["read_file", "glob_files", "grep_code", "git_log", "git_diff", "list_dir", "check_env", "check_port", "inspect_db", "done"],
-  plan: ["read_file", "glob_files", "grep_code", "list_dir", "inspect_db", "check_env", "search_brain", "done"],
-  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "bash_exec", "move_file", "run_db_fix", "done"],
+  explore: ["read_file", "glob_files", "grep_code", "git_log", "git_diff", "list_dir", "check_env", "check_port", "inspect_db", "audit_deps", "done"],
+  plan: ["read_file", "glob_files", "grep_code", "list_dir", "inspect_db", "check_env", "audit_deps", "check_migration", "search_brain", "done"],
+  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "bash_exec", "move_file", "run_db_fix", "audit_deps", "done"],
   verify: ["read_file", "glob_files", "grep_code", "bash_exec", "inspect_db", "check_port", "done"],
   research: ["read_file", "grep_code", "web_fetch", "search_brain", "done"],
   security: ["read_file", "glob_files", "grep_code", "inspect_db", "done"],

package/src/brain/brain.js

@@ -228,9 +228,13 @@ const SEED_DOCS = [
     metadata: { topic: "idempotency" },
   },
   {
-    text: "Heal pipeline no longer requires a file path. When no file is identified from the error (database errors, config problems, port conflicts), the pipeline skips fast path and goes straight to the agent, which uses investigation tools (glob_files, grep_code, list_dir, inspect_db, check_env, check_port) to find the root cause. Agent verification for no-file errors: if agent made changes or ran commands, trust the agent's assessment. For file-based errors, verification uses syntax check + boot probe as before.",
+    text: "Heal pipeline no longer requires a file path. When no file is identified from the error (database errors, config problems, port conflicts), the pipeline skips fast path and goes straight to the agent, which uses investigation tools (glob_files, grep_code, list_dir, inspect_db, check_env, check_port, audit_deps) to find the root cause. Agent verification for no-file errors: if agent made changes or ran commands, trust the agent's assessment. For file-based errors, verification uses syntax check + boot probe + route probe as before.",
     metadata: { topic: "fileless-heal" },
   },
+  {
+    text: "Dependency manager skill (src/skills/deps.js): structured npm dependency analysis + repair. diagnose(errorMessage, cwd) returns {diagnosed, category, summary, fixes} — categories: missing_install, missing_package, version_conflict, outdated_api, corrupted_modules. healthReport(cwd) returns full health check: npm audit (vulnerabilities), outdated packages, peer dep conflicts, unused packages, lock file status, health score 0-100. getMigration(packageName) returns known upgrade paths: express→fastify (5.6x faster), moment→dayjs (2KB vs 70KB), request→node-fetch (deprecated), body-parser→built-in, callbacks→async/await. Agent tools: audit_deps (full health check), check_migration (upgrade paths). Heal pipeline uses diagnose() in tryOperationalFix before AI — zero tokens for dependency issues.",
+    metadata: { topic: "skill-deps" },
+  },
 ];
 
 class Brain {

package/src/core/wolverine.js

@@ -13,6 +13,7 @@ const { ResearchAgent } = require("../agent/research-agent");
 const { GoalLoop } = require("../agent/goal-loop");
 const { exploreAndFix, spawnParallel } = require("../agent/sub-agents");
 const { EVENT_TYPES } = require("../logger/event-logger");
+const { diagnose: diagnoseDeps } = require("../skills/deps");
 
 /**
  * The Wolverine healing engine — v3.
@@ -400,33 +401,19 @@ async function tryOperationalFix(parsed, cwd, logger) {
   const { execSync } = require("child_process");
   const msg = parsed.errorMessage || "";
 
-  // Pattern 1: Cannot find module 'X' — missing npm package
-  const missingModule = msg.match(/Cannot find module '([^']+)'/);
-  if (missingModule) {
-    const moduleName = missingModule[1];
-
-    // Only npm install if it's a package name (not a relative/absolute path)
-    if (!moduleName.startsWith(".") && !moduleName.startsWith("/") && !moduleName.startsWith("\\")) {
-      // Check if it's already in package.json but not installed
-      const fs = require("fs");
-      const path = require("path");
-      const pkgPath = path.join(cwd, "package.json");
-      let isInPkg = false;
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-        isInPkg = !!allDeps[moduleName];
-      } catch {}
+  // Pattern 1: Dependency issues — use deps skill for structured diagnosis
+  const depsDiag = diagnoseDeps(msg, cwd);
+  if (depsDiag.diagnosed) {
+    console.log(chalk.blue(`  📦 Deps diagnosis: ${depsDiag.category} — ${depsDiag.summary}`));
+    if (logger) logger.info("heal.ops.deps", depsDiag.summary, { category: depsDiag.category });
 
+    for (const fix of (depsDiag.fixes || [])) {
       try {
-        const cmd = isInPkg ? "npm install" : `npm install ${moduleName}`;
-        console.log(chalk.blue(`  📦 Missing module '${moduleName}' — running: ${cmd}`));
-        if (logger) logger.info("heal.ops", `Running: ${cmd}`, { module: moduleName });
-        execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
-        return { fixed: true, action: `Installed missing module '${moduleName}' via: ${cmd}` };
+        console.log(chalk.blue(`  📦 Running: ${fix}`));
+        execSync(fix, { cwd, stdio: "pipe", timeout: 60000 });
+        return { fixed: true, action: `${depsDiag.summary}. Fixed via: ${fix}` };
       } catch (e) {
-        console.log(chalk.yellow(`  ⚠️ npm install failed: ${e.message?.slice(0, 100)}`));
-        // Fall through to AI repair
+        console.log(chalk.yellow(`  ⚠️ ${fix} failed: ${e.message?.slice(0, 80)}`));
       }
     }
   }

package/src/index.js

@@ -34,6 +34,7 @@ const { detect: detectSystem } = require("./core/system-info");
 const { ClusterManager } = require("./core/cluster-manager");
 const { loadConfig, getConfig } = require("./core/config");
 const { sqlGuard, SafeDB, scanForInjection, idempotencyGuard, idempotencyAfterHook } = require("./skills/sql");
+const { diagnose: diagnoseDeps, healthReport: depsHealthReport, getMigration } = require("./skills/deps");
 
 module.exports = {
   // Core
@@ -95,4 +96,7 @@ module.exports = {
   scanForInjection,
   idempotencyGuard,
   idempotencyAfterHook,
+  diagnoseDeps,
+  depsHealthReport,
+  getMigration,
 };

package/src/skills/deps.js

@@ -0,0 +1,449 @@
+/**
+ * Dependency Manager Skill — structured npm dependency analysis + repair.
+ *
+ * The agent often sees errors caused by dependency issues (version conflicts,
+ * missing peer deps, deprecated APIs, vulnerabilities) and wastes tokens trying
+ * to "fix" code when the real problem is in package.json or node_modules.
+ *
+ * This skill provides structured analysis BEFORE the AI runs, so the agent
+ * gets actionable context like "express@4.21 has a known vulnerability,
+ * upgrade to 4.22" instead of guessing from a stack trace.
+ *
+ * Capabilities:
+ * 1. Audit: npm audit wrapper — finds vulnerabilities with fix commands
+ * 2. Outdated: detects packages with available updates
+ * 3. Peer deps: finds missing/conflicting peer dependencies
+ * 4. Unused: detects packages in package.json not imported anywhere
+ * 5. Lock repair: detects and fixes corrupted package-lock.json
+ * 6. Version conflicts: finds packages requiring incompatible versions
+ * 7. Migration knowledge: knows common upgrade paths (express→fastify, etc.)
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const chalk = require("chalk");
+
+/**
+ * Run npm audit and return structured vulnerability data.
+ * @param {string} cwd — project root
+ * @returns {{ vulnerabilities: number, critical: number, high: number, fixes: string[] }}
+ */
+function audit(cwd) {
+  try {
+    const raw = execSync("npm audit --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw);
+    const meta = data.metadata || {};
+    const vulns = meta.vulnerabilities || {};
+    const total = (vulns.critical || 0) + (vulns.high || 0) + (vulns.moderate || 0) + (vulns.low || 0);
+
+    const fixes = [];
+    if (total > 0) {
+      try {
+        const fixOutput = execSync("npm audit fix --dry-run --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+        const fixData = JSON.parse(fixOutput);
+        if (fixData.added || fixData.updated || fixData.removed) {
+          fixes.push("npm audit fix");
+        }
+      } catch { fixes.push("npm audit fix (may require --force for breaking changes)"); }
+    }
+
+    return {
+      vulnerabilities: total,
+      critical: vulns.critical || 0,
+      high: vulns.high || 0,
+      moderate: vulns.moderate || 0,
+      low: vulns.low || 0,
+      fixes,
+    };
+  } catch (e) {
+    // npm audit exits non-zero when vulnerabilities exist
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      const vulns = (data.metadata || {}).vulnerabilities || {};
+      return {
+        vulnerabilities: (vulns.critical || 0) + (vulns.high || 0) + (vulns.moderate || 0) + (vulns.low || 0),
+        critical: vulns.critical || 0,
+        high: vulns.high || 0,
+        moderate: vulns.moderate || 0,
+        low: vulns.low || 0,
+        fixes: ["npm audit fix"],
+      };
+    } catch { return { vulnerabilities: 0, critical: 0, high: 0, moderate: 0, low: 0, fixes: [], error: e.message?.slice(0, 100) }; }
+  }
+}
+
+/**
+ * Find outdated packages.
+ * @param {string} cwd
+ * @returns {Array<{ name, current, wanted, latest, type }>}
+ */
+function outdated(cwd) {
+  try {
+    const raw = execSync("npm outdated --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw || "{}");
+    return Object.entries(data).map(([name, info]) => ({
+      name,
+      current: info.current,
+      wanted: info.wanted,
+      latest: info.latest,
+      type: info.type || "dependencies",
+    }));
+  } catch (e) {
+    // npm outdated exits non-zero when outdated packages exist
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      return Object.entries(data).map(([name, info]) => ({
+        name,
+        current: info.current,
+        wanted: info.wanted,
+        latest: info.latest,
+        type: info.type || "dependencies",
+      }));
+    } catch { return []; }
+  }
+}
+
+/**
+ * Find missing or conflicting peer dependencies.
+ * @param {string} cwd
+ * @returns {Array<{ package, requires, missing }>}
+ */
+function checkPeerDeps(cwd) {
+  const issues = [];
+  try {
+    const raw = execSync("npm ls --json --depth=1 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw || "{}");
+
+    const walk = (deps, parentName = "root") => {
+      if (!deps) return;
+      for (const [name, info] of Object.entries(deps)) {
+        if (info.peerMissing) {
+          for (const peer of info.peerMissing) {
+            issues.push({ package: name, requires: peer.requires, missing: peer.requiredBy || name });
+          }
+        }
+        if (info.problems) {
+          for (const problem of info.problems) {
+            if (problem.includes("peer dep")) {
+              issues.push({ package: name, requires: problem, missing: parentName });
+            }
+          }
+        }
+        if (info.dependencies) walk(info.dependencies, name);
+      }
+    };
+    walk(data.dependencies);
+  } catch (e) {
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      if (data.problems) {
+        for (const p of data.problems) {
+          issues.push({ package: "root", requires: p, missing: "project" });
+        }
+      }
+    } catch {}
+  }
+  return issues;
+}
+
+/**
+ * Find packages in package.json that aren't imported anywhere in the project.
+ * @param {string} cwd
+ * @returns {string[]} — unused package names
+ */
+function findUnused(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) return [];
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  const allDeps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+
+  // Scan all .js/.ts/.mjs/.cjs files for require/import statements
+  const usedPackages = new Set();
+  const scanDir = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".wolverine") continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) { scanDir(fullPath); continue; }
+      if (!/\.(js|ts|mjs|cjs|jsx|tsx)$/.test(entry.name)) continue;
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        // Match require("X") and import ... from "X"
+        const requires = content.match(/require\s*\(\s*["']([^"'./][^"']*)["']\s*\)/g) || [];
+        const imports = content.match(/from\s+["']([^"'./][^"']*)["']/g) || [];
+        for (const r of requires) {
+          const m = r.match(/["']([^"']+)["']/);
+          if (m) usedPackages.add(m[1].split("/")[0]);
+        }
+        for (const i of imports) {
+          const m = i.match(/["']([^"']+)["']/);
+          if (m) usedPackages.add(m[1].split("/")[0]);
+        }
+      } catch {}
+    }
+  };
+  scanDir(cwd);
+
+  // Filter: only report deps that are truly unused
+  // Exclude common false positives (types, plugins, bin-only packages)
+  const falsePositives = new Set(["typescript", "@types", "eslint", "prettier", "nodemon", "ts-node"]);
+  return allDeps.filter(dep => {
+    const baseName = dep.startsWith("@") ? dep : dep.split("/")[0];
+    return !usedPackages.has(baseName) && !falsePositives.has(baseName) && !baseName.startsWith("@types/");
+  });
+}
+
+/**
+ * Check if package-lock.json is healthy.
+ * @param {string} cwd
+ * @returns {{ healthy: boolean, issue?: string, fix?: string }}
+ */
+function checkLockFile(cwd) {
+  const lockPath = path.join(cwd, "package-lock.json");
+  const pkgPath = path.join(cwd, "package.json");
+
+  if (!fs.existsSync(lockPath)) {
+    return { healthy: false, issue: "No package-lock.json found", fix: "npm install" };
+  }
+
+  try {
+    const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+
+    // Check lock version
+    if (!lock.lockfileVersion || lock.lockfileVersion < 2) {
+      return { healthy: false, issue: `Outdated lockfile version ${lock.lockfileVersion || 1}`, fix: "rm package-lock.json && npm install" };
+    }
+
+    // Check if lock matches package.json
+    const pkgDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const lockDeps = lock.packages?.[""]?.dependencies || {};
+    const lockDevDeps = lock.packages?.[""]?.devDependencies || {};
+    const allLockDeps = { ...lockDeps, ...lockDevDeps };
+
+    for (const [name] of Object.entries(pkgDeps)) {
+      if (!allLockDeps[name] && !lock.dependencies?.[name]) {
+        return { healthy: false, issue: `${name} in package.json but missing from lock`, fix: "npm install" };
+      }
+    }
+
+    return { healthy: true };
+  } catch (e) {
+    return { healthy: false, issue: `Corrupted lock file: ${e.message?.slice(0, 60)}`, fix: "rm package-lock.json && npm install" };
+  }
+}
+
+/**
+ * Diagnose a dependency-related error and return structured fix recommendations.
+ * This is the main entry point — call it from the heal pipeline.
+ *
+ * @param {string} errorMessage
+ * @param {string} cwd
+ * @returns {{ diagnosed: boolean, category: string, summary: string, fixes: string[] }}
+ */
+function diagnose(errorMessage, cwd) {
+  const msg = (errorMessage || "").toLowerCase();
+
+  // Pattern: Cannot find module 'X'
+  const missingMatch = errorMessage.match(/Cannot find module '([^']+)'/);
+  if (missingMatch) {
+    const mod = missingMatch[1];
+    if (!mod.startsWith(".") && !mod.startsWith("/")) {
+      // Check if it's in package.json
+      const pkgPath = path.join(cwd, "package.json");
+      let inPkg = false;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        inPkg = !!(pkg.dependencies?.[mod] || pkg.devDependencies?.[mod]);
+      } catch {}
+
+      if (inPkg) {
+        return {
+          diagnosed: true,
+          category: "missing_install",
+          summary: `${mod} is in package.json but not installed`,
+          fixes: ["npm install"],
+        };
+      }
+      return {
+        diagnosed: true,
+        category: "missing_package",
+        summary: `${mod} is not in package.json and not installed`,
+        fixes: [`npm install ${mod}`],
+      };
+    }
+  }
+
+  // Pattern: version/compatibility errors
+  if (/version mismatch|incompatible|peer dep|ERESOLVE/i.test(msg)) {
+    const peerIssues = checkPeerDeps(cwd);
+    return {
+      diagnosed: true,
+      category: "version_conflict",
+      summary: `Dependency version conflict (${peerIssues.length} peer dep issues)`,
+      fixes: peerIssues.length > 0
+        ? peerIssues.map(p => `npm install ${p.package}@latest`).concat(["npm install --legacy-peer-deps"])
+        : ["npm install --legacy-peer-deps", "rm -rf node_modules && npm install"],
+      details: peerIssues,
+    };
+  }
+
+  // Pattern: deprecated/removed API
+  if (/is not a function|is not a constructor|has no method|deprecated/i.test(msg)) {
+    const outdatedPkgs = outdated(cwd);
+    if (outdatedPkgs.length > 0) {
+      // Find the package mentioned in the error
+      const relevantPkgs = outdatedPkgs.filter(p =>
+        msg.includes(p.name.toLowerCase()) || errorMessage.includes(p.name)
+      );
+      if (relevantPkgs.length > 0) {
+        return {
+          diagnosed: true,
+          category: "outdated_api",
+          summary: `API may have changed in newer version of ${relevantPkgs.map(p => p.name).join(", ")}`,
+          fixes: relevantPkgs.map(p => `npm install ${p.name}@${p.latest}`),
+          details: relevantPkgs,
+        };
+      }
+    }
+  }
+
+  // Pattern: corrupted node_modules
+  if (/unexpected token|cannot find module.*node_modules|EISDIR|ENOTDIR/i.test(msg) && msg.includes("node_modules")) {
+    return {
+      diagnosed: true,
+      category: "corrupted_modules",
+      summary: "node_modules appears corrupted",
+      fixes: ["rm -rf node_modules package-lock.json && npm install"],
+    };
+  }
+
+  return { diagnosed: false };
+}
+
+/**
+ * Full dependency health report — used by dashboard and agent context.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function healthReport(cwd) {
+  const auditResult = audit(cwd);
+  const outdatedPkgs = outdated(cwd);
+  const peerIssues = checkPeerDeps(cwd);
+  const unused = findUnused(cwd);
+  const lockStatus = checkLockFile(cwd);
+
+  const score = Math.max(0, 100
+    - (auditResult.critical * 20)
+    - (auditResult.high * 10)
+    - (auditResult.moderate * 3)
+    - (peerIssues.length * 5)
+    - (lockStatus.healthy ? 0 : 15)
+    - Math.min(outdatedPkgs.length * 2, 20)
+  );
+
+  return {
+    score,
+    audit: auditResult,
+    outdated: outdatedPkgs,
+    peerDeps: peerIssues,
+    unused,
+    lockFile: lockStatus,
+    summary: score >= 80 ? "Healthy" : score >= 50 ? "Needs attention" : "Critical issues",
+  };
+}
+
+// ── Migration Knowledge ──
+
+const MIGRATION_PATTERNS = {
+  "express": {
+    to: "fastify",
+    reason: "5.6x faster routing, built-in validation, async-first",
+    patterns: [
+      { from: "app.get(path, handler)", to: "fastify.get(path, handler)" },
+      { from: "app.use(middleware)", to: "fastify.addHook('preHandler', middleware)" },
+      { from: "res.json(data)", to: "reply.send(data)" },
+      { from: "res.status(code)", to: "reply.code(code)" },
+      { from: "app.listen(port)", to: "fastify.listen({ port, host: '0.0.0.0' })" },
+    ],
+  },
+  "request": {
+    to: "node-fetch or undici",
+    reason: "request is deprecated since 2020",
+    patterns: [
+      { from: "request(url, callback)", to: "const res = await fetch(url)" },
+      { from: "request.post(url, { body })", to: "await fetch(url, { method: 'POST', body })" },
+    ],
+  },
+  "moment": {
+    to: "dayjs or date-fns",
+    reason: "moment is in maintenance mode, 70KB vs 2KB",
+    patterns: [
+      { from: "moment().format('YYYY-MM-DD')", to: "dayjs().format('YYYY-MM-DD')" },
+      { from: "moment(date).diff(other)", to: "dayjs(date).diff(other)" },
+    ],
+  },
+  "body-parser": {
+    to: "built-in (Express 4.16+ / Fastify)",
+    reason: "Included by default in modern frameworks",
+    patterns: [
+      { from: "app.use(bodyParser.json())", to: "app.use(express.json())" },
+    ],
+  },
+  "callback-style": {
+    to: "async/await with util.promisify",
+    reason: "Cleaner error handling, no callback hell",
+    patterns: [
+      { from: "fs.readFile(path, (err, data) => {})", to: "const data = await fs.promises.readFile(path)" },
+      { from: "db.query(sql, (err, rows) => {})", to: "const rows = await db.query(sql)" },
+    ],
+  },
+};
+
+/**
+ * Check if a package has a known migration path.
+ * @param {string} packageName
+ * @returns {object|null}
+ */
+function getMigration(packageName) {
+  return MIGRATION_PATTERNS[packageName] || null;
+}
+
+// ── Skill Metadata ──
+
+const SKILL_NAME = "deps";
+const SKILL_DESCRIPTION = "Dependency manager: npm audit, version conflicts, peer deps, unused packages, lock file repair, migration knowledge. Diagnoses dependency-related errors before AI runs, providing actionable fix commands instead of code edits.";
+const SKILL_KEYWORDS = ["dependency", "dependencies", "npm", "package", "install", "audit", "vulnerability", "outdated", "peer", "version", "conflict", "lock", "node_modules", "upgrade", "migrate", "deprecated"];
+const SKILL_USAGE = `// Diagnose a dependency error (returns structured fix)
+const { diagnose } = require("../src/skills/deps");
+const result = diagnose("Cannot find module 'cors'", process.cwd());
+// { diagnosed: true, category: "missing_package", fixes: ["npm install cors"] }
+
+// Full health report
+const { healthReport } = require("../src/skills/deps");
+const report = healthReport(process.cwd());
+// { score: 85, audit: {...}, outdated: [...], peerDeps: [...], unused: [...] }
+
+// Check migration paths
+const { getMigration } = require("../src/skills/deps");
+const migration = getMigration("moment");
+// { to: "dayjs", reason: "maintenance mode, 70KB vs 2KB", patterns: [...] }`;
+
+module.exports = {
+  SKILL_NAME,
+  SKILL_DESCRIPTION,
+  SKILL_KEYWORDS,
+  SKILL_USAGE,
+  audit,
+  outdated,
+  checkPeerDeps,
+  findUnused,
+  checkLockFile,
+  diagnose,
+  healthReport,
+  getMigration,
+  MIGRATION_PATTERNS,
+};