selfguard 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 selfguard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,155 @@
 # selfguard
 
-This version only reserves the package name. It contains no code.
+A local-first guard for the dependencies of **every** JavaScript repo you work on.
 
-The first real release (published from GitHub Actions with provenance) will be available soon:
-https://github.com/josseed/selfguard
+- **Hands-off**: `cd` into a project and selfguard registers it and scans it in the background.
+  Run `npm install` and it notices that the lockfile changed and re-scans.
+- **Reverse alerts**: `selfguard sync` (or the scheduled job) re-checks all your projects against
+  new advisories. You get a macOS notification when a repo you haven't opened in months becomes vulnerable.
+- **Malicious packages first**: OSV includes the OpenSSF malicious-packages feed (`MAL-*`), so
+  compromised releases (Shai-Hulud style) are flagged above any CVE.
+- **Incident response**: `selfguard where <pkg>` answers "do I use this anywhere?" in one command.
+
+## Install
+
+```sh
+npm install -g selfguard
+selfguard setup
+```
+
+`setup` is a small terminal UI: pick the folders where you keep your repos (it suggests
+`~/repository`, `~/code`, `~/dev`… and shows how many projects each has), then it scans them and
+offers to install the shell hook and the background sync.
+
+```
+Where do you keep your code?
+selfguard only looks inside the folders you pick, nothing else on your disk.
+
+  [x] ~/repository                     205 projects   depth 3
+› [x] ~/code                             12 projects   depth 2
+  + add another folder…
+
+↑/↓ move · space select · ←/→ depth · a add folder · enter continue · q quit
+```
+
+## How projects are found
+
+selfguard **never crawls your whole disk**. A project gets tracked in one of three ways:
+
+1. **Your folders** (`setup` / `roots add`): a recursive search of every subfolder (depth-limited,
+   default 5) that only skips dependency/generated folders: `node_modules`, `bower_components`,
+   `vendor`, `Pods`, `venv`, `target`, `__pycache__`, hidden folders (`.git`, `.next`, `.cache`…),
+   and symlinks. It also looks inside projects, so monorepos with several lockfiles are covered.
+   `sync` re-runs it, so a fresh `git clone` gets watched even if you never open it.
+2. **The shell hook**: `cd` anywhere and the enclosing project is registered.
+3. **By hand**: `selfguard scan <dir>`.
+
+Worktrees and separate clones of the same repo are **grouped** (by remote URL, or by the main
+repo a worktree points to), and each subfolder project of a monorepo stays its own group:
+
+```
+CRITICAL acme/datahub  31 vulnerable pkg(s) on main · 82 on feat/calculadora  3 checkouts
+   ├ main  31 vulnerable  ~/code/datahub
+   ├ fix/query-perf worktree  30 vulnerable  ~/code/datahub-query-perf
+   └ feat/calculadora worktree  82 vulnerable  ~/code/datahub-feat-calculadora
+```
+
+Notifications about the same advisory in several checkouts of one repo arrive once. `sync` stops
+tracking folders that no longer exist (e.g. removed worktrees). `status --flat` lists every checkout.
+
+Test fixtures, examples or archived repos you don't care about: `selfguard forget <dir>` stops
+tracking them and excludes them from discovery (undo with `selfguard unexclude <dir>`).
+
+## Use it with AI (MCP)
+
+selfguard ships an MCP server, so assistants like Claude Code or Cursor can triage and manage it:
+
+```sh
+claude mcp add selfguard -- selfguard mcp
+```
+
+Then ask things like *"which of my projects have critical vulnerabilities and how do I fix them?"*,
+*"is `@ctrl/tinycolor` used anywhere?"* or *"stop tracking the test fixtures in ~/code/shop"*.
+
+| Tool | Purpose |
+|---|---|
+| `selfguard_status` | All projects with risk summary |
+| `selfguard_project_report` | Vulnerable packages of a project, with `upgradeTo` |
+| `selfguard_scan` / `selfguard_sync` | Re-check one project / everything |
+| `selfguard_where` | Which projects use a package |
+| `selfguard_vulnerability` | Advisory details + which of your projects it affects |
+| `selfguard_roots_*`, `selfguard_discover` | Manage watched folders |
+| `selfguard_forget` / `selfguard_unexclude` | Stop tracking / re-include |
+
+The MCP tools never run package managers or project code. Fixes are proposed for the user to apply.
+Advisory text is marked as third-party data so the model treats it as data, not instructions.
+
+Without MCP, every command accepts `--json` (one JSON document on stdout, errors as
+`{"error":{"code","message"}}`, exit codes 0/1/2), and `selfguard guide` prints a guide written
+for agents.
+
+## Commands
+
+Run `selfguard --help` for everything. The main ones:
+
+| Command | What it does |
+|---|---|
+| `selfguard setup` | Interactive: choose your code folders, scan, install hook + sync |
+| `selfguard status [--vulnerable] [--flat]` | Tracked repos, riskiest first (worktrees/clones grouped) |
+| `selfguard scan [dir] [-v]` | Scan a project now (exit code 1 if anything is found) |
+| `selfguard report [dir] [-v]` | Last results for a project, no network |
+| `selfguard sync` | Find new repos in your folders, re-check everything, notify about news |
+| `selfguard where <pkg>` | Which projects use a package, and which versions |
+| `selfguard vuln <id>` | Advisory details and which of your projects it affects |
+| `selfguard roots [add <dir> [--depth N] \| remove <dir>]` | Manage your code folders |
+| `selfguard discover [--dry-run]` | Register new projects found in your folders |
+| `selfguard forget [dir]` / `unexclude <dir>` | Stop tracking + exclude / re-include |
+| `selfguard schedule on\|off\|status` | Periodic sync via launchd (macOS) |
+| `selfguard mcp` / `selfguard guide` | MCP server / guide for AI agents |
+
+## Security model
+
+selfguard is a security tool, so it holds itself to a stricter standard:
+
+- **Never executes anything from your projects.** Lockfiles are parsed as data. No `npm ls`, no
+  lifecycle scripts, no `.npmrc`. Entering a hostile repo is safe.
+- **Zero runtime dependencies.** Only Node built-ins. CI fails if a runtime dependency is added.
+- **Minimal data leaves your machine**: only `name` + `version` pairs go to
+  [OSV.dev](https://osv.dev). No paths, repo names, or file contents.
+- **Untrusted text is sanitized** before it reaches your terminal or a notification: no terminal
+  escape injection and no bidi spoofing. Notification text goes to AppleScript as arguments, never as code.
+- **Local state is private**: `~/.selfguard` is created `0700` and its files `0600`.
+- **Releases use npm Trusted Publishing with provenance and staged publishing**: no long-lived
+  publish token exists, CI can only stage a version, and a maintainer must approve it with 2FA
+  before anyone can install it. `npm view selfguard --json` shows the provenance attestation.
+
+## How it works
+
+```
+cd ──► zsh hook (pure shell: walk up for package.json, stat lockfile on each prompt)
+         │ only when the project or lockfile changes
+         ▼
+   selfguard hook-enter ──► cached summary on stderr
+         │ lockfile changed / never scanned / >24h
+         ▼
+   detached background scan ──► parse lockfile ──► OSV querybatch ──► ~/.selfguard
+                                                                    └─► macOS notification on new findings
+```
+
+Supported lockfiles: `package-lock.json` / `npm-shrinkwrap.json` (v1–v3), `pnpm-lock.yaml`
+(v5, v6, v9), `yarn.lock` (classic v1 and berry v2+) and `bun.lock`. The binary `bun.lockb` is
+not supported (`bun install --save-text-lockfile` converts it). All of them are parsed as data,
+with a dependency-free parser; the test suite checks that real lockfiles from every manager
+produce identical results for the same project.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm test          # node:test runs the TypeScript sources directly (Node >= 22.18)
+npm run build     # emits dist/
+```
+
+## License
+
+MIT

package/dist/alerts.js

@@ -0,0 +1,96 @@
+/** Decide what to tell the user (and how) after a scan or sync. Pure: easy to test. */
+import { basename } from "node:path";
+import { criticalDialog, notify } from "./notify.js";
+import { groupByPackage, worstSeverity } from "./report.js";
+const LABEL = {
+    malicious: "MALICIOUS",
+    critical: "CRITICAL",
+    high: "HIGH",
+    moderate: "MODERATE",
+    low: "LOW",
+    unknown: "UNKNOWN",
+};
+const name = (path) => basename(path) || path;
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function listFixes(findings, max = 3) {
+    const groups = groupByPackage(findings);
+    const parts = groups.slice(0, max).map((g) => (g.upgradeTo ? `${g.name} → ${g.upgradeTo}` : `${g.name} (no fix yet)`));
+    if (groups.length > max)
+        parts.push(`+${groups.length - max} more`);
+    return parts.join(", ");
+}
+/** Merge checkouts of the same repo into one entry, de-duplicating findings. */
+function byRepo(news) {
+    const groups = new Map();
+    for (const n of news) {
+        if (n.newFindings.length === 0)
+            continue;
+        const key = n.repo?.key ?? `path:${n.path}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = { path: n.path, newFindings: [], label: n.repo?.label ?? name(n.path), checkouts: 0, seen: new Set() };
+            groups.set(key, g);
+        }
+        g.checkouts++;
+        for (const f of n.newFindings) {
+            const k = `${f.id}|${f.name}@${f.version}`;
+            if (g.seen.has(k))
+                continue;
+            g.seen.add(k);
+            g.newFindings.push(f);
+        }
+    }
+    return [...groups.values()].map(({ seen: _s, ...g }) => g);
+}
+export function buildAlert(news) {
+    const affected = byRepo(news);
+    if (affected.length === 0)
+        return { kind: "none" };
+    const all = affected.flatMap((n) => n.newFindings);
+    const malicious = affected.flatMap((n) => n.newFindings.filter((f) => f.severity === "malicious").map((f) => ({ f, path: n.path })));
+    if (malicious.length > 0) {
+        const { f, path } = malicious[0];
+        const group = affected.find((n) => n.path === path);
+        const where = affected.length === 1 ? group.label : `${affected.length} projects`;
+        const others = malicious.length > 1 ? ` (+${malicious.length - 1} more malicious)` : "";
+        return {
+            kind: "critical",
+            title: `⛔ Malicious package in ${where}`,
+            subtitle: `${f.name}@${f.version} · ${f.id}`,
+            body: "Remove it now and rotate credentials on this machine.",
+            dialogTitle: `selfguard: malicious package in ${where}`,
+            dialogMessage: `${f.name}@${f.version} is a known malicious package${others}.\n\n` +
+                `Project: ${path}${group.checkouts > 1 ? ` (and ${group.checkouts - 1} other checkout(s) of ${group.label})` : ""}\n\n` +
+                "1. Remove it (or pin a safe version) and reinstall.\n" +
+                "2. Rotate credentials this machine or CI could reach: npm tokens, cloud keys, SSH keys, .env secrets.\n" +
+                "3. Check the advisory for what the payload does.",
+            url: `https://osv.dev/vulnerability/${encodeURIComponent(f.id)}`,
+        };
+    }
+    const worst = LABEL[worstSeverity(all) ?? "unknown"];
+    if (affected.length === 1) {
+        const n = affected[0];
+        const pkgs = groupByPackage(n.newFindings).length;
+        return {
+            kind: "banner",
+            title: `selfguard: ${n.label}${n.checkouts > 1 ? ` (${n.checkouts} checkouts)` : ""}`,
+            subtitle: `${plural(pkgs, "vulnerable package")} · worst: ${worst}`,
+            body: listFixes(n.newFindings),
+        };
+    }
+    const pkgs = affected.reduce((sum, n) => sum + groupByPackage(n.newFindings).length, 0);
+    const names = affected.map((n) => n.label);
+    return {
+        kind: "banner",
+        title: `selfguard: ${affected.length} projects affected`,
+        subtitle: `${plural(pkgs, "vulnerable package")} · worst: ${worst}`,
+        body: `${names.slice(0, 3).join(", ")}${names.length > 3 ? ` +${names.length - 3} more` : ""}. Run: selfguard status`,
+    };
+}
+export async function deliver(alert) {
+    if (alert.kind === "none")
+        return;
+    await notify(alert.title, alert.body, alert.subtitle);
+    if (alert.kind === "critical")
+        await criticalDialog(alert.dialogTitle, alert.dialogMessage, alert.url);
+}

package/dist/api.js

@@ -0,0 +1,327 @@
+/**
+ * Structured operations shared by the CLI (`--json`) and the MCP server.
+ * Every function returns plain JSON-serializable data with a stable shape
+ * (documented in src/guide.ts). Human rendering lives elsewhere.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { clampDepth, DEFAULT_DEPTH, isExcluded, loadConfig, normalizeDir, saveConfig, } from "./config.js";
+import { discoverAll } from "./discover.js";
+import { tryLock } from "./fsutil.js";
+import { findProject } from "./lockfile/detect.js";
+import { evaluate, severityOf, severityRank } from "./match.js";
+import { getVulns } from "./osv.js";
+import { countBySeverity, groupByPackage, worstSeverity } from "./report.js";
+import { repoIdentity } from "./repoid.js";
+import { clean } from "./sanitize.js";
+import { scanProjects } from "./scan.js";
+import { forgetRepo, listRepos, loadRepo, saveRepo } from "./store.js";
+export class ApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const advisoryUrl = (id) => `https://osv.dev/vulnerability/${encodeURIComponent(id)}`;
+// ---------- helpers ----------
+function summarize(rec) {
+    return {
+        path: rec.path,
+        exists: existsSync(rec.path),
+        lockfile: rec.lockfile,
+        lockType: rec.lockType,
+        packages: rec.deps.length,
+        skippedEntries: rec.skipped,
+        scannedAt: rec.scannedAt,
+        error: rec.error ?? null,
+        worstSeverity: worstSeverity(rec.findings),
+        vulnerablePackages: groupByPackage(rec.findings).length,
+        advisories: rec.findings.length,
+        bySeverity: countBySeverity(rec.findings),
+        repo: existsSync(rec.path) ? repoIdentity(rec.path) : null,
+    };
+}
+export function toReport(rec) {
+    return {
+        ...summarize(rec),
+        vulnerable: groupByPackage(rec.findings).map((g) => ({
+            name: g.name,
+            version: g.version,
+            direct: g.direct,
+            dev: g.dev,
+            worstSeverity: g.worst,
+            upgradeTo: g.worst === "malicious" ? null : (g.upgradeTo ?? null),
+            advisoriesWithoutFix: g.unfixed,
+            advisories: g.findings.map((f) => ({
+                id: f.id,
+                aliases: f.aliases,
+                severity: f.severity,
+                summary: f.summary,
+                fixedIn: f.fixedIn ?? null,
+                firstSeen: f.firstSeen,
+                url: advisoryUrl(f.id),
+            })),
+        })),
+    };
+}
+function resolveProject(path) {
+    const abs = resolve(path);
+    if (!existsSync(abs))
+        throw new ApiError("not_found", `no such directory: ${abs}`);
+    const project = findProject(abs);
+    if (!project)
+        throw new ApiError("no_project", `no package.json found in ${abs} or its parents`);
+    return project;
+}
+// ---------- operations ----------
+export function getStatus(opts = {}) {
+    const rank = (w) => (w ? severityRank(w) : 99);
+    const records = listRepos();
+    const summaries = records.map(summarize);
+    const groups = new Map();
+    summaries.forEach((p, i) => {
+        const rec = records[i];
+        const key = p.repo?.key ?? `path:${p.path}`;
+        let g = groups.get(key);
+        if (!g) {
+            const label = p.repo?.label ?? (p.path.split("/").pop() || p.path);
+            g = { group: { key, label, worstSeverity: null, vulnerablePackages: 0, checkouts: [] }, pkgs: new Set(), findings: [] };
+            groups.set(key, g);
+        }
+        g.group.checkouts.push({
+            path: p.path,
+            branch: p.repo?.branch ?? null,
+            worktree: p.repo?.worktree ?? false,
+            exists: p.exists,
+            worstSeverity: p.worstSeverity,
+            vulnerablePackages: p.vulnerablePackages,
+            advisories: p.advisories,
+            error: p.error,
+        });
+        for (const f of rec.findings)
+            g.pkgs.add(`${f.name}@${f.version}`);
+        g.findings.push(...rec.findings);
+    });
+    const repos = [...groups.values()]
+        .map(({ group, pkgs, findings }) => {
+        group.worstSeverity = worstSeverity(findings);
+        group.vulnerablePackages = pkgs.size;
+        // main checkout first, then riskiest worktrees
+        group.checkouts.sort((a, b) => Number(a.worktree) - Number(b.worktree) || rank(a.worstSeverity) - rank(b.worstSeverity) || a.path.localeCompare(b.path));
+        return group;
+    })
+        .filter((g) => !opts.onlyVulnerable || g.vulnerablePackages > 0)
+        .sort((a, b) => rank(a.worstSeverity) - rank(b.worstSeverity) || b.vulnerablePackages - a.vulnerablePackages || a.label.localeCompare(b.label));
+    const projects = summaries
+        .filter((p) => !opts.onlyVulnerable || p.advisories > 0)
+        .sort((a, b) => rank(a.worstSeverity) - rank(b.worstSeverity) || b.advisories - a.advisories || a.path.localeCompare(b.path));
+    return { repos, projects };
+}
+/** Last stored report for a project (no network). */
+export function getReport(path) {
+    const project = resolveProject(path);
+    const rec = loadRepo(project.root);
+    if (!rec)
+        throw new ApiError("not_tracked", `${project.root} is not tracked yet; scan it first`);
+    return toReport(rec);
+}
+export async function scanPath(path) {
+    const project = resolveProject(path);
+    const release = tryLock(`scan:${project.root}`);
+    if (!release)
+        throw new ApiError("busy", "another scan of this project is running, try again in a moment");
+    try {
+        const [o] = await scanProjects([project]);
+        saveRepo(o.record);
+        return { project: toReport(o.record), firstScan: o.firstScan, newAdvisories: o.newFindings.length };
+    }
+    finally {
+        release();
+    }
+}
+export async function sync() {
+    const release = tryLock("sync");
+    if (!release)
+        throw new ApiError("busy", "a sync is already running");
+    try {
+        const cfg = loadConfig();
+        const projects = [];
+        const seen = new Set();
+        const pruned = [];
+        for (const r of listRepos()) {
+            if (!existsSync(r.path)) {
+                forgetRepo(r.path); // e.g. a worktree you removed: nothing left to protect
+                pruned.push(r.path);
+                continue;
+            }
+            if (isExcluded(r.path, cfg.exclude))
+                continue;
+            const p = findProject(r.path);
+            if (p && p.root === r.path) {
+                projects.push(p);
+                seen.add(p.root);
+            }
+        }
+        // New clones inside your folders get tracked without you ever cd-ing into them.
+        const discovered = (await discoverAll(cfg.roots, { exclude: cfg.exclude })).filter((p) => !seen.has(p.root));
+        projects.push(...discovered);
+        const outcomes = await scanProjects(projects);
+        for (const o of outcomes)
+            saveRepo(o.record);
+        return {
+            projects: projects.length,
+            discovered: discovered.map((p) => p.root),
+            pruned,
+            news: outcomes
+                .filter((o) => o.newFindings.length > 0)
+                .map((o) => ({
+                path: o.record.path,
+                packages: groupByPackage(o.newFindings).map((g) => ({
+                    name: g.name,
+                    version: g.version,
+                    worstSeverity: g.worst,
+                    advisories: g.findings.map((f) => f.id),
+                })),
+            })),
+            errors: outcomes.filter((o) => o.record.error).map((o) => ({ path: o.record.path, error: o.record.error })),
+            outcomes,
+        };
+    }
+    finally {
+        release();
+    }
+}
+export async function discoverNew(opts = {}) {
+    const cfg = loadConfig();
+    if (cfg.roots.length === 0)
+        throw new ApiError("no_roots", "no folders configured; add one with roots add <dir>");
+    const known = new Set(listRepos().map((r) => r.path));
+    const fresh = (await discoverAll(cfg.roots, { exclude: cfg.exclude })).filter((p) => !known.has(p.root));
+    const found = fresh.map((p) => ({ path: p.root, lockType: p.lockType }));
+    if (opts.dryRun || fresh.length === 0)
+        return { dryRun: Boolean(opts.dryRun), found, registered: 0, withVulnerabilities: 0 };
+    const outcomes = await scanProjects(fresh);
+    for (const o of outcomes)
+        saveRepo(o.record);
+    return {
+        dryRun: false,
+        found,
+        registered: outcomes.length,
+        withVulnerabilities: outcomes.filter((o) => o.record.findings.length > 0).length,
+    };
+}
+export function whereUsed(name) {
+    const usedIn = [];
+    for (const r of listRepos()) {
+        const versions = r.deps
+            .filter((d) => d.name === name)
+            .map((d) => ({
+            version: d.version,
+            direct: d.direct,
+            dev: d.dev,
+            vulnerable: r.findings.some((f) => f.name === name && f.version === d.version),
+        }));
+        if (versions.length)
+            usedIn.push({ path: r.path, versions });
+    }
+    return { package: name, usedIn };
+}
+export function listRoots() {
+    const { roots, exclude } = loadConfig();
+    return { roots, exclude };
+}
+export function addRoot(path, depth) {
+    const dir = normalizeDir(path);
+    if (!dir)
+        throw new ApiError("not_found", `not a directory: ${path}`);
+    const cfg = loadConfig();
+    const d = depth === undefined ? DEFAULT_DEPTH : clampDepth(depth);
+    cfg.roots = [...cfg.roots.filter((r) => r.path !== dir), { path: dir, depth: d }];
+    saveConfig(cfg);
+    return { roots: cfg.roots, exclude: cfg.exclude };
+}
+export function removeRoot(path) {
+    const cfg = loadConfig();
+    const abs = normalizeDir(path) ?? resolve(path);
+    const before = cfg.roots.length;
+    cfg.roots = cfg.roots.filter((r) => r.path !== abs);
+    saveConfig(cfg);
+    return { roots: cfg.roots, exclude: cfg.exclude, removed: cfg.roots.length < before };
+}
+/**
+ * Stop tracking a path. With `exclude` (default), it's also excluded from discovery
+ * so it never comes back (use for fixtures, examples, archived repos).
+ */
+export function forget(path, opts = {}) {
+    const abs = normalizeDir(path) ?? resolve(path);
+    const root = loadRepo(abs) ? abs : (findProject(abs)?.root ?? abs);
+    const wasTracked = forgetRepo(root);
+    const alsoForgotten = [];
+    const exclude = opts.exclude ?? true;
+    if (exclude) {
+        const cfg = loadConfig();
+        if (!cfg.exclude.includes(root))
+            cfg.exclude.push(root);
+        saveConfig(cfg);
+        // Excluding a folder also drops tracked projects below it.
+        for (const r of listRepos()) {
+            if (r.path !== root && isExcluded(r.path, [root])) {
+                forgetRepo(r.path);
+                alsoForgotten.push(r.path);
+            }
+        }
+    }
+    return { path: root, wasTracked, excluded: exclude, alsoForgotten };
+}
+export function unexclude(path) {
+    const cfg = loadConfig();
+    const abs = normalizeDir(path) ?? resolve(path);
+    const before = cfg.exclude.length;
+    cfg.exclude = cfg.exclude.filter((e) => e !== abs);
+    saveConfig(cfg);
+    return { roots: cfg.roots, exclude: cfg.exclude, removed: cfg.exclude.length < before };
+}
+export async function getVulnerability(id) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id))
+        throw new ApiError("invalid", "invalid advisory id");
+    const vulns = await getVulns([{ id, modified: "" }]);
+    const v = vulns.get(id);
+    if (!v)
+        throw new ApiError("not_found", `advisory ${id} not found`);
+    const s = (x, n) => clean(x ?? "", n);
+    const affectsYourProjects = [];
+    for (const r of listRepos()) {
+        for (const d of r.deps) {
+            const ev = evaluate(v, d.name, d.version);
+            if (ev.affected)
+                affectsYourProjects.push({ path: r.path, package: d.name, version: d.version, fixedIn: ev.fixedIn ?? null });
+        }
+    }
+    const raw = v;
+    return {
+        id: v.id,
+        aliases: (v.aliases ?? []).map((a) => s(a, 64)),
+        severity: severityOf(v),
+        summary: s(v.summary, 300),
+        details: clean(v.details ?? "", 4000),
+        published: typeof raw.published === "string" ? raw.published : null,
+        modified: v.modified ?? null,
+        withdrawn: v.withdrawn ?? null,
+        affected: (v.affected ?? [])
+            .filter((a) => a.package?.ecosystem === "npm")
+            .slice(0, 20)
+            .map((a) => ({
+            package: s(a.package?.name, 214),
+            ranges: (a.ranges ?? []).flatMap((r) => (r.events ?? []).map((e) => ({ ...e }))).slice(0, 50),
+            versions: (a.versions ?? []).slice(0, 50).map((x) => s(x, 64)),
+        })),
+        references: (Array.isArray(raw.references) ? raw.references : [])
+            .map((r) => (r && typeof r === "object" ? r.url : undefined))
+            .filter((u) => typeof u === "string" && /^https:\/\//.test(u))
+            .slice(0, 15)
+            .map((u) => s(u, 300)),
+        url: advisoryUrl(v.id),
+        affectsYourProjects,
+    };
+}