penthera 1.2.0 → 1.5.0

package/docs/release-plan.md

@@ -0,0 +1,228 @@
+# Release plan: v1.2.0 → v1.4.0
+
+The engineering plan behind the [roadmap](../ROADMAP.md): what ships in each
+release, in what order, what each piece depends on, and how we know it is done.
+Dates are targets, not promises. Building is fast; review, real-world testing,
+and the 2FA release approval set the pace.
+
+Written 2026-10-19. **Status:** both milestones shipped together as 1.4.0 on 2026-10-19, a few weeks ahead of the targets below.
+
+## The bet
+
+Two releases that move Penthera from "a good scanner" to a system that competes
+with commercial supply-chain and AppSec platforms on their core value, while
+keeping what they cannot copy: local, deterministic, explainable, no telemetry.
+
+| Commercial platforms sell | Penthera answers with | Release |
+|---------------------------|-----------------------|---------|
+| Dependency capability alerts and upgrade diffs | `penthera deps` and `deps --diff` | v1.3.0 |
+| Skill, extension, and MCP scanning | `penthera agents` and `penthera.lock` | v1.3.0 |
+| PR comments on dependency changes | GitHub Action that comments the capability diff | v1.4.0 |
+| An install firewall | `penthera install`: check before install scripts run | v1.4.0 |
+| Auto-fix PRs | A local scan → fix → verify → learn loop that never pushes | v1.4.0 |
+| Proof that it works | Published methodology, verified citations, a benchmark | v1.3.0 |
+
+## Timeline at a glance
+
+| When | Milestone |
+|------|-----------|
+| Oct 19–20 | v1.2.0 live on npm (2FA approval), old npm token deleted |
+| Oct 20–22 | v1.3.0 PRs merged in order, release staged |
+| Oct 23 | v1.3.0 live, launch write-up published |
+| Oct 23–30 | v1.4.0 wave 1: HTTP client and egress guard, learning store, fix recipes, install firewall |
+| Oct 30–Nov 6 | v1.4.0 wave 2: agent loop, custom reports, PR-comment Action |
+| Nov 6–10 | Release gate: real-app test, benchmark diff, security review |
+| Nov 10 | v1.4.0 live |
+| From Nov 16 | Internal testing audit, landing page (see "Scheduled for later") |
+| December | v1.5.0 (staged on the roadmap) |
+
+---
+
+## v1.2.0: finish the release
+
+| Step | Owner | Done when |
+|------|-------|-----------|
+| Approve the staged version on npmjs.com (Staged Packages, 2FA) | Maintainer | `npm view penthera version` is 1.2.0 with provenance |
+| Delete the `NPM_TOKEN` repository secret | Maintainer | Secret gone; publishing is OIDC-only |
+| Decide Dependabot #11 (`setup-node` v6 → v7) | Maintainer + CI | v7 changes how `NODE_AUTH_TOKEN` is handled. With no token left this is likely safe, but merge it only with a dry-run of `publish.yml` (`npm stage publish --dry-run`) on a branch first |
+
+## v1.3.0 "AI toolchain": target Oct 22, live Oct 23
+
+All four pieces are already built or in progress. The work is review and merge
+order, because three of them touch `src/cli.js`, the README, and the CHANGELOG.
+
+**Merge order:**
+
+1. **#12 `penthera agents`.** Offline audit of `.mcp.json`, `~/.claude`,
+   `~/.cursor`, hooks, plugins, skills, and rule files. Includes the
+   hidden-content engine, `penthera.lock`, an A–F grade, and OWASP MCP / Agentic
+   mapping. Rebase on main, review, merge.
+2. **Research and methodology.** `docs/METHODOLOGY.md`, verified
+   `references.bib`, per-finding citations in Markdown and SARIF,
+   `CITATION.cff`, an offline benchmark with precision and recall. Rebase
+   after #12 (both touch the reporters).
+3. **`penthera deps`.** Static capability detection on `node_modules`,
+   `--diff` between lockfiles, typosquat check against a vendored list, and an
+   opt-in `--online` registry check. Rebase after the research PR.
+4. **Funding pack.** Docs only, any order.
+
+**Also in v1.3.0:**
+
+| Item | Why | Size |
+|------|-----|------|
+| Bump to 1.3.0 everywhere, CHANGELOG, tag, approve | Release | S |
+| Launch write-up: an offline audit of popular public skills and MCP servers with `penthera agents` | The post that earns attention. Read-only analysis of public repos, findings reported to authors privately first | M |
+
+**Release gate:** `npm test` green, benchmark numbers in `bench/RESULTS.md` no
+worse than v1.2.0, `penthera agents` and `penthera deps` run cleanly on this
+repo, every citation verified.
+
+## v1.4.0 "Local loop + competitive": target Nov 10
+
+### Wave 1 (parallel, Oct 23–30)
+
+Each workstream owns different files, so they can be built side by side.
+
+**W1. One HTTP client, `--offline` egress guard, User-Agent, inconclusive probes**
+- Every network call goes through `src/utils/http.js`. Today `crawler`,
+  `injections`, `fuzzer`, `templates`, `recon`, `params`, `retirejs`, and
+  `adaptive-probes` each build their own fetch wrapper.
+- `--offline`: the client refuses any host other than the scan target. Recon
+  sources (crt.sh, Wayback, OTX) become explicit opt-ins.
+- Vendor a Retire.js database snapshot, refreshed by a release script, so JS
+  CVE checks work offline.
+- Send `penthera/<version> (+repo url)` as the User-Agent (closes #7).
+- Probe errors are recorded and reported as "inconclusive" instead of passing
+  silently (closes #8).
+- While rewriting `lib/injections.js` and `lib/fuzzer.js`: an honest header,
+  and payload strings moved into a clearly named data file. Socket's AI judge
+  flagged Penthera as malware for containing test payloads; this gives any
+  reviewer the context a snippet lacks. Then ask Socket to review the alert.
+- **Done when:** a test that blocks all egress except the target passes for
+  every profile, and the vendored database matches upstream at release time.
+
+**W2. Local learning store**
+- `~/.penthera/memory/<project-hash>/events.jsonl`: append-only; each event
+  carries the hash of the previous one.
+- Events: scan summary, fix applied (recipe, diff hash), fix verified or
+  failed, false positive suppressed (fingerprint, reason), probe yield per
+  stack.
+- Derived views: recipe success rate per framework, active suppressions,
+  probe ranking. Used only to re-rank and suppress; never executes anything.
+- `penthera memory show | verify | forget`. `verify` detects any edit to the
+  chain.
+- Never read from the scanned repo. A suppression committed to a repo is shown
+  in the report as "suppressed by repo file" so a reviewer sees it.
+- **Done when:** tampering with any line fails `verify`, and suppressions and
+  re-ranking are covered by tests.
+
+**W3. Fix recipes**
+- `lib/fix/`: deterministic codemods that produce a unified diff for the most
+  common findings:
+  - security headers for Next.js, Express (helmet), Fastify, and Hono;
+  - cookie flags;
+  - a CORS allowlist;
+  - a rate-limit stub on auth routes;
+  - moving a hardcoded secret to an environment variable, with "rotate it" as
+    an owner action.
+- Framework detection reuses `lib/whitebox/frameworks.js`.
+- Optional local model adapter (Ollama on localhost, enforced by W1) for
+  findings without a recipe. Its output is labelled "model-suggested,
+  needs-human-review".
+- **Done when:** each recipe has before/after fixtures, and every produced diff
+  applies cleanly and makes its finding disappear on re-scan in the fixture app.
+
+**W4. Install firewall**
+- `penthera install [pkg...]`: resolve the dependency tree with scripts
+  disabled, run the `deps` capability diff against the current lockfile, show
+  what is new (install scripts, network, shell, env), and only then run the
+  real install, either after a prompt or under a policy file
+  (`penthera.policy.json`).
+- **Done when:** a fixture package that gains an install script is stopped
+  before its script runs.
+
+### Wave 2 (Oct 30–Nov 6)
+
+**W5. Agent loop: `penthera agent --loop`** (depends on W1, W2, W3)
+- State machine: scan → triage (ranked by memory) → plan (recipe or model
+  suggestion) → patch on a local branch `penthera/fix-<date>` → verify
+  (re-scan, plus the project's tests if present) → learn → repeat.
+- Stops when nothing fixable remains or `--max-iterations` is reached.
+- Every diff needs approval by default. `--auto low` auto-applies only
+  recipes with a verified success history in memory.
+- Hard guarantees, each with a test:
+  - never pushes, never opens pull requests, never calls a remote;
+  - egress is limited to the target;
+  - the working tree must be clean before it starts.
+- **Done when:** on the fixture app the loop takes the findings to zero in a
+  bounded number of iterations, and a second run is faster because memory
+  re-ranked the recipes.
+
+**W6. Custom reports and evidence bundle** (depends on W2)
+- Audience templates: developer, owner, auditor. User templates via
+  `--report-template file.md` with a small placeholder syntax that evaluates
+  no code.
+- Loop timeline: found → fixed → verified, with time-to-fix from memory.
+- `--evidence <dir>`: reports plus a `manifest.json` with the SHA-256 of
+  every artifact. Optional signing with a local SSH key
+  (`ssh-keygen -Y sign`), no new dependency.
+- **Done when:** an auditor can verify a bundle with one documented command.
+
+**W7. PR-comment GitHub Action** (depends on `deps` from v1.3.0)
+- A composite action published from this repo: on PRs that change a lockfile
+  it runs `penthera deps --diff` against the base branch, posts or updates a
+  single comment ("2 packages gained network access, 1 new install script"),
+  and uploads SARIF.
+- Pinned by SHA in the docs; no secrets needed beyond the default token.
+- **Done when:** it runs on a test PR in this repo and the comment updates in
+  place on a new push.
+
+**W8. Skill and docs**
+- SKILL.md workflow "scan and fix" uses `penthera agent`.
+- `docs/local-loop.md` explains the threat model: why nothing leaves the
+  machine, why the store is hash-chained, why rules never update at runtime.
+
+### Release gate (Nov 6–10)
+
+- Run the loop on one real app the maintainer owns, not only fixtures.
+- Benchmark: precision and recall no worse than v1.3.0.
+- Self-scan with `penthera --repo .`, `penthera agents`, and `penthera deps`:
+  no new high findings.
+- Security review of the diff since v1.3.0, focused on the loop and the
+  firewall (they run commands and write code).
+- Then bump to 1.4.0, tag, approve.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Three PRs conflict in `src/cli.js` | Strict merge order, rebase each after the previous one lands. Consider splitting subcommands into `src/commands/` early in v1.4.0 |
+| Fix recipes break someone's app | Diffs only, approval by default, verify by re-scan and tests, a local branch only |
+| The learning store becomes an attack surface | Home directory only, hash chain, re-rank and suppress only, nothing executable |
+| Install firewall false positives annoy users | Show the capability diff, not a verdict; a policy file to allow known packages |
+| Another AI-judge false positive on new modules | Honest headers, payloads in data files, Socket review requested |
+
+---
+
+## Scheduled for later (from Nov 16)
+
+**Internal testing audit.** A standing quality gate run before every release:
+- Penthera against itself and a fixed set of deliberately vulnerable apps
+  (mock server, OWASP Juice Shop, crAPI).
+- `agents` and `deps` against fixture configs.
+- A diff of results against the previous release, with false positives and
+  false negatives triaged into issues.
+- A scheduled weekly run, so drift shows up between releases.
+- The results feed `bench/RESULTS.md`.
+
+**Landing page.** A one-page site: what it does, the 30-second install, the
+trust story (offline, staged releases, methodology, benchmark), and links to
+the docs. Static, hosted on GitHub Pages, with no tracking scripts, in keeping
+with the no-telemetry principle.
+
+## v1.5.0 and beyond
+
+Staged on the [roadmap](../ROADMAP.md): LLM endpoint probes, OWASP LLM
+mapping, the CRA Article 14 helper, the AI-BOM, a pre-commit hook, license
+policy, and signed rule packs. After that: the local dashboard (`penthera ui`)
+and a team pack.

package/lib/adaptive-probes.js

@@ -8,15 +8,20 @@
  * Results feed into the SecurityKnowledgeGraph for chain discovery.
  */
 
+import { request } from "../src/utils/http.js";
+
 const DEFAULT_TIMEOUT = 10_000;
 
 async function probe(base, path, opts = {}) {
   const url = `${base}${path}`;
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), opts.timeout || DEFAULT_TIMEOUT);
   const start = Date.now();
   try {
-    const res = await fetch(url, { ...opts, signal: controller.signal });
+    const res = await request(url, {
+      timeout: DEFAULT_TIMEOUT,
+      probe: "adaptive",
+      redirect: "follow",
+      ...opts,
+    });
     const elapsed = Date.now() - start;
     let body = null;
     const ct = res.headers.get("content-type") || "";
@@ -36,8 +41,6 @@ async function probe(base, path, opts = {}) {
       elapsed: Date.now() - start, ok: false,
       error: err.name === "AbortError" ? "timeout" : err.message,
     };
-  } finally {
-    clearTimeout(timeout);
   }
 }
 

package/lib/agents/discover.js

@@ -0,0 +1,384 @@
+/**
+ * Discover AI developer-tooling configuration in a repo and (opt-in) in the
+ * user's home directory: MCP servers, hooks, permissions, skills, plugins,
+ * marketplaces, and instruction files (AGENTS.md, CLAUDE.md, rules).
+ *
+ * Read-only. Nothing here writes, executes, or touches the network.
+ */
+import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from "node:fs";
+import { join, relative, dirname, basename, sep, resolve } from "node:path";
+import { homedir } from "node:os";
+import YAML from "yaml";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".venv", "venv", "__pycache__", "dist", "build", ".next"]);
+export const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_WALK_FILES = 5000;
+
+// ── Small helpers ─────────────────────────────────────────────────────────
+
+/** JSON.parse that tolerates // and /* *\/ comments and trailing commas (JSONC). */
+export function parseJsonc(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    let out = "";
+    let inStr = false;
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      if (inStr) {
+        out += ch;
+        if (ch === "\\") { out += text[++i] ?? ""; continue; }
+        if (ch === '"') inStr = false;
+        continue;
+      }
+      if (ch === '"') { inStr = true; out += ch; continue; }
+      if (ch === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++; out += "\n"; continue; }
+      if (ch === "/" && text[i + 1] === "*") { i += 2; while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++; i++; continue; }
+      out += ch;
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+  }
+}
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+export function readText(p) {
+  try {
+    const st = statSync(p);
+    if (!st.isFile()) return null;
+    if (st.size > MAX_FILE_BYTES) return { tooLarge: true, size: st.size };
+    return readFileSync(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Parse YAML frontmatter from a Markdown file. Returns {} when absent or invalid. */
+export function parseFrontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---\r?(?:\n|$)/.exec(text || "");
+  if (!m) return {};
+  try {
+    const fm = YAML.parse(m[1]);
+    return fm && typeof fm === "object" ? fm : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Walk a directory without following symlinks. Returns files and symlinks
+ * (relative to `dir`), bounded so a hostile tree can't hang the scan.
+ */
+export function walk(dir, { maxDepth = 12, maxFiles = MAX_WALK_FILES } = {}) {
+  const files = [];
+  const symlinks = [];
+  let truncated = false;
+  const visit = (d, depth) => {
+    if (files.length >= maxFiles) { truncated = true; return; }
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      if (files.length >= maxFiles) { truncated = true; return; }
+      const full = join(d, e.name);
+      if (e.isSymbolicLink()) { symlinks.push(full); continue; }
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name) || depth >= maxDepth) continue;
+        visit(full, depth + 1);
+      } else if (e.isFile()) {
+        files.push(full);
+      }
+    }
+  };
+  visit(dir, 0);
+  return { files, symlinks, truncated };
+}
+
+// ── Inventory ─────────────────────────────────────────────────────────────
+
+function createInventory(root, homeDir, includeHome) {
+  const display = (p) => {
+    const abs = resolve(p);
+    if (abs === root || abs.startsWith(root + sep)) return relative(root, abs) || ".";
+    if (homeDir && (abs === homeDir || abs.startsWith(homeDir + sep))) return "~/" + relative(homeDir, abs).split(sep).join("/");
+    return abs;
+  };
+  return {
+    root,
+    homeDir: includeHome ? homeDir : null,
+    display,
+    configFiles: [],      // every config file read: { path, display }
+    instructionFiles: [], // Markdown/rule files a model reads: { path, display, scope }
+    skills: [],           // { name, dir, display, skillFile, frontmatter, scope }
+    mcpServers: [],       // { name, def, file, scope }
+    hooks: [],            // { event, matcher, hook, file, key, baseDir }
+    permissions: [],      // { rule, list, file }
+    settings: [],         // { file, defaultMode, raw }
+    marketplaces: [],     // { name, source, file }
+    plugins: [],          // { id, installPath, version, gitCommitSha, file, enabled }
+    pluginSources: [],    // plugin entries listed in a marketplace.json: { name, source, file }
+    errors: [],           // { file, message }
+  };
+}
+
+function loadJson(inv, path) {
+  const text = readText(path);
+  if (text == null) return null;
+  if (typeof text === "object") {
+    inv.errors.push({ file: inv.display(path), message: `larger than ${MAX_FILE_BYTES} bytes, not parsed` });
+    return null;
+  }
+  try {
+    const json = parseJsonc(text);
+    inv.configFiles.push({ path, display: inv.display(path) });
+    return json;
+  } catch (e) {
+    inv.errors.push({ file: inv.display(path), message: `invalid JSON: ${e.message}` });
+    return null;
+  }
+}
+
+function addMcpServers(inv, servers, file, scope) {
+  if (!servers || typeof servers !== "object") return;
+  for (const [name, def] of Object.entries(servers)) {
+    if (def && typeof def === "object") inv.mcpServers.push({ name, def, file, scope });
+  }
+}
+
+function addMcpFile(inv, path, scope) {
+  const json = loadJson(inv, path);
+  if (!json) return;
+  // Claude/Cursor/Desktop use `mcpServers`; VS Code uses `servers`.
+  addMcpServers(inv, json.mcpServers || json.servers, inv.display(path), scope);
+}
+
+function addHooks(inv, hooksObj, file, baseDir) {
+  if (!hooksObj || typeof hooksObj !== "object") return;
+  for (const [event, groups] of Object.entries(hooksObj)) {
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((group, gi) => {
+      const matcher = group?.matcher ?? "";
+      const list = Array.isArray(group?.hooks) ? group.hooks : [group];
+      list.forEach((hook, hi) => {
+        if (!hook || typeof hook !== "object") return;
+        inv.hooks.push({
+          event,
+          matcher,
+          hook,
+          file,
+          baseDir,
+          key: `hook:${file}#${event}[${matcher || "*"}]/${gi}.${hi}`,
+        });
+      });
+    });
+  }
+}
+
+function addSettingsFile(inv, path, scope) {
+  const json = loadJson(inv, path);
+  if (!json) return;
+  const file = inv.display(path);
+  const projectDir = scope === "repo" ? inv.root : dirname(dirname(path));
+  inv.settings.push({ file, defaultMode: json.permissions?.defaultMode ?? null, raw: json });
+  addHooks(inv, json.hooks, file, projectDir);
+  for (const list of ["allow", "ask", "deny"]) {
+    const rules = json.permissions?.[list];
+    if (Array.isArray(rules)) for (const rule of rules) inv.permissions.push({ rule: String(rule), list, file });
+  }
+  addMcpServers(inv, json.mcpServers, file, scope);
+  const mk = json.extraKnownMarketplaces;
+  if (mk && typeof mk === "object") {
+    for (const [name, v] of Object.entries(mk)) inv.marketplaces.push({ name, source: v?.source ?? v, file });
+  }
+}
+
+function addInstructionFile(inv, path, scope) {
+  if (!isFile(path)) return;
+  inv.instructionFiles.push({ path, display: inv.display(path), scope });
+}
+
+function addMarkdownDir(inv, dir, scope) {
+  if (!isDir(dir)) return;
+  for (const f of walk(dir, { maxDepth: 6 }).files) {
+    if (/\.(?:md|mdc|markdown|txt)$/i.test(f)) addInstructionFile(inv, f, scope);
+  }
+}
+
+function addSkillsUnder(inv, dir, scope) {
+  if (!isDir(dir)) return;
+  const seen = new Set(inv.skills.map((s) => s.dir));
+  for (const f of walk(dir, { maxDepth: 6 }).files) {
+    if (basename(f).toLowerCase() !== "skill.md") continue;
+    const skillDir = dirname(f);
+    if (seen.has(skillDir)) continue;
+    seen.add(skillDir);
+    const text = readText(f);
+    const fm = typeof text === "string" ? parseFrontmatter(text) : {};
+    inv.skills.push({
+      name: typeof fm.name === "string" ? fm.name : basename(skillDir),
+      dir: skillDir,
+      display: inv.display(skillDir),
+      skillFile: f,
+      frontmatter: fm,
+      scope,
+    });
+  }
+}
+
+function addPluginDir(inv, pluginDir, scope) {
+  addSkillsUnder(inv, join(pluginDir, "skills"), scope);
+  addMarkdownDir(inv, join(pluginDir, "commands"), scope);
+  addMarkdownDir(inv, join(pluginDir, "agents"), scope);
+  const hooksFile = join(pluginDir, "hooks", "hooks.json");
+  if (isFile(hooksFile)) {
+    const json = loadJson(inv, hooksFile);
+    if (json) addHooks(inv, json.hooks || json, inv.display(hooksFile), pluginDir);
+  }
+  const mcp = join(pluginDir, ".mcp.json");
+  if (isFile(mcp)) addMcpFile(inv, mcp, scope);
+  const manifest = join(pluginDir, ".claude-plugin", "plugin.json");
+  if (isFile(manifest)) {
+    const json = loadJson(inv, manifest);
+    if (json) {
+      if (json.mcpServers && typeof json.mcpServers === "object") addMcpServers(inv, json.mcpServers, inv.display(manifest), scope);
+      if (json.hooks && typeof json.hooks === "object") addHooks(inv, json.hooks.hooks || json.hooks, inv.display(manifest), pluginDir);
+    }
+  }
+}
+
+function addMarketplaceManifest(inv, path) {
+  const json = loadJson(inv, path);
+  if (!json || !Array.isArray(json.plugins)) return;
+  for (const p of json.plugins) {
+    if (p && typeof p === "object") inv.pluginSources.push({ name: p.name || "(unnamed)", source: p.source, file: inv.display(path) });
+  }
+}
+
+// ── Repo ──────────────────────────────────────────────────────────────────
+
+const SKILL_ROOTS = ["skills", ".claude/skills", ".cursor/skills", ".agents/skills", ".codex/skills"];
+const INSTRUCTION_FILES = [
+  "AGENTS.md", "CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md", "GEMINI.md",
+  ".cursorrules", ".windsurfrules", ".clinerules",
+  ".github/copilot-instructions.md",
+];
+
+function discoverRepo(inv) {
+  const r = inv.root;
+  for (const f of [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json"]) {
+    if (isFile(join(r, f))) addMcpFile(inv, join(r, f), "repo");
+  }
+  for (const f of [".claude/settings.json", ".claude/settings.local.json"]) {
+    if (isFile(join(r, f))) addSettingsFile(inv, join(r, f), "repo");
+  }
+  for (const f of INSTRUCTION_FILES) addInstructionFile(inv, join(r, f), "repo");
+  if (isDir(join(r, ".clinerules"))) addMarkdownDir(inv, join(r, ".clinerules"), "repo");
+  addMarkdownDir(inv, join(r, ".cursor", "rules"), "repo");
+  addMarkdownDir(inv, join(r, ".github", "instructions"), "repo");
+  addMarkdownDir(inv, join(r, ".claude", "commands"), "repo");
+  addMarkdownDir(inv, join(r, ".claude", "agents"), "repo");
+  for (const s of SKILL_ROOTS) addSkillsUnder(inv, join(r, s), "repo");
+  // Plugins developed in this repo: plugins/<name>/{skills,hooks,...}
+  if (isDir(join(r, "plugins"))) {
+    for (const e of readdirSync(join(r, "plugins"), { withFileTypes: true })) {
+      if (e.isDirectory()) addPluginDir(inv, join(r, "plugins", e.name), "repo");
+    }
+  }
+  if (isFile(join(r, ".claude-plugin", "marketplace.json"))) addMarketplaceManifest(inv, join(r, ".claude-plugin", "marketplace.json"));
+  if (isFile(join(r, ".claude-plugin", "plugin.json"))) addPluginDir(inv, r, "repo");
+}
+
+// ── Home ──────────────────────────────────────────────────────────────────
+
+export function claudeDesktopConfigPaths(homeDir, platform = process.platform) {
+  const out = [];
+  if (platform === "darwin") out.push(join(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json"));
+  if (platform === "win32" && process.env.APPDATA) out.push(join(process.env.APPDATA, "Claude", "claude_desktop_config.json"));
+  out.push(join(homeDir, ".config", "Claude", "claude_desktop_config.json"));
+  return out;
+}
+
+function discoverHome(inv, homeDir) {
+  const claude = join(homeDir, ".claude");
+  for (const f of ["settings.json", "settings.local.json"]) {
+    if (isFile(join(claude, f))) addSettingsFile(inv, join(claude, f), "home");
+  }
+  addInstructionFile(inv, join(claude, "CLAUDE.md"), "home");
+  addSkillsUnder(inv, join(claude, "skills"), "home");
+  addSkillsUnder(inv, join(homeDir, ".agents", "skills"), "home");
+  addSkillsUnder(inv, join(homeDir, ".cursor", "skills"), "home");
+  addMarkdownDir(inv, join(claude, "commands"), "home");
+  addMarkdownDir(inv, join(claude, "agents"), "home");
+
+  // User-scoped MCP servers for Claude Code live in ~/.claude.json, top level
+  // and per project. Only the scanned project's entry is read.
+  const userJsonPath = join(homeDir, ".claude.json");
+  if (isFile(userJsonPath)) {
+    const json = loadJson(inv, userJsonPath);
+    if (json) {
+      addMcpServers(inv, json.mcpServers, inv.display(userJsonPath), "home");
+      const proj = json.projects?.[inv.root];
+      if (proj?.mcpServers) addMcpServers(inv, proj.mcpServers, `${inv.display(userJsonPath)} (project ${basename(inv.root)})`, "home");
+    }
+  }
+
+  if (isFile(join(homeDir, ".cursor", "mcp.json"))) addMcpFile(inv, join(homeDir, ".cursor", "mcp.json"), "home");
+  for (const p of claudeDesktopConfigPaths(homeDir)) {
+    if (isFile(p)) addMcpFile(inv, p, "home");
+  }
+
+  // Plugins and the marketplaces they come from.
+  const pluginsDir = join(claude, "plugins");
+  const known = isFile(join(pluginsDir, "known_marketplaces.json")) ? loadJson(inv, join(pluginsDir, "known_marketplaces.json")) : null;
+  if (known && typeof known === "object") {
+    const file = inv.display(join(pluginsDir, "known_marketplaces.json"));
+    for (const [name, v] of Object.entries(known)) {
+      if (!inv.marketplaces.some((m) => m.name === name)) inv.marketplaces.push({ name, source: v?.source ?? v, file });
+    }
+  }
+  const enabled = new Set();
+  for (const s of inv.settings) {
+    const ep = s.raw?.enabledPlugins;
+    if (ep && typeof ep === "object") for (const [id, on] of Object.entries(ep)) if (on) enabled.add(id);
+  }
+  const installed = isFile(join(pluginsDir, "installed_plugins.json")) ? loadJson(inv, join(pluginsDir, "installed_plugins.json")) : null;
+  const pluginMap = installed?.plugins && typeof installed.plugins === "object" ? installed.plugins : {};
+  const file = inv.display(join(pluginsDir, "installed_plugins.json"));
+  for (const [id, entries] of Object.entries(pluginMap)) {
+    for (const e of Array.isArray(entries) ? entries : [entries]) {
+      if (!e || typeof e !== "object") continue;
+      inv.plugins.push({
+        id,
+        installPath: e.installPath || null,
+        version: e.version || null,
+        gitCommitSha: e.gitCommitSha || null,
+        file,
+        enabled: enabled.has(id),
+      });
+      if (e.installPath && isDir(e.installPath)) addPluginDir(inv, e.installPath, `plugin:${id}`);
+    }
+  }
+}
+
+/**
+ * Discover agent configuration.
+ * @param {string} root - repo root
+ * @param {object} [opts] { home: boolean, homeDir: string }
+ */
+export function discoverAgentConfig(root, opts = {}) {
+  const absRoot = resolve(root);
+  let canonical = absRoot;
+  try { canonical = realpathSync(absRoot); } catch { /* keep as given */ }
+  const homeDir = resolve(opts.homeDir || homedir());
+  const inv = createInventory(canonical, homeDir, !!opts.home);
+  if (existsSync(canonical)) discoverRepo(inv);
+  if (opts.home) discoverHome(inv, homeDir);
+  return inv;
+}
+
+export { isFile, isDir };