codevet-cli 1.1.0

package/dist/scanners/bearerScanner.js

@@ -0,0 +1,108 @@
+import { execa } from "execa";
+import { readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ensureBinary } from "./ensureBinary.js";
+export class BearerBinaryMissingError extends Error {
+    constructor() {
+        const isWindows = process.platform === "win32";
+        super(isWindows
+            ? "bearer has no native Windows build, so the personal-data-flow check isn't available on this machine — secrets, dependencies, and hygiene checks are unaffected. WSL is a workaround if you need this specific check."
+            : "bearer binary not found and could not be downloaded automatically. Check your network connection and try again.");
+        this.name = "BearerBinaryMissingError";
+    }
+}
+export class BearerScanFailedError extends Error {
+    constructor(reason) {
+        super(`bearer's data-flow scan did not actually run: ${reason}. This is being reported as a failure rather than "no findings" — a scan that never ran is not the same as a clean result.`);
+        this.name = "BearerScanFailedError";
+    }
+}
+// Bearer's default security-report ruleset includes general Express
+// hygiene rules that CodeVet's own hygiene scanner already covers
+// (helmet, server fingerprinting) — excluded here to avoid showing the
+// same finding twice from two different scanners. Everything else stays,
+// since Bearer's actual differentiator is data-flow rules like
+// "javascript_lang_logger" (PII logged) that no pattern-based scanner
+// (including CodeVet's own hygiene checks) can detect — those require
+// understanding where a value came from and where it goes, not just
+// whether a line matches a regex.
+const OVERLAPS_WITH_HYGIENE_SCANNER = new Set([
+    "javascript_express_helmet_missing",
+    "javascript_express_reduce_fingerprint",
+]);
+export async function runBearerScan(projectRoot) {
+    // ensureBinary returns null on Windows (no native build exists) or if
+    // the download genuinely fails — both correctly surface as
+    // BearerBinaryMissingError below, same as before.
+    const binaryPath = await ensureBinary("bearer");
+    if (!binaryPath) {
+        throw new BearerBinaryMissingError();
+    }
+    const reportPath = join(projectRoot, ".codevet-bearer-report.json");
+    try {
+        // IMPORTANT: do NOT pass --exit-code 0 here. That flag forces bearer
+        // to always report success, which was confirmed in testing to mask a
+        // genuine internal failure (rule definitions failing to download,
+        // producing "0 rules found") as a silent, false "no findings" result
+        // — exactly the kind of fake-clean result this project exists to
+        // prevent. We handle bearer's real non-zero exit code ourselves below
+        // instead of suppressing it.
+        const result = await execa(binaryPath, [
+            "scan",
+            projectRoot,
+            "--format",
+            "json",
+            "--output",
+            reportPath,
+            "--quiet",
+            "--hide-progress-bar",
+            "--no-rule-meta",
+            // Directories holding example/template code (e.g. CodeVet's own
+            // fix-library, or any project keeping similar reference snippets)
+            // are structurally full of intentional secret-handling examples —
+            // Bearer's static analysis can't distinguish a variable named
+            // `SECRET` read correctly from process.env inside a documentation
+            // string from a real hardcoded secret in executable code.
+            // Confirmed as a real false-positive source by testing against
+            // CodeVet's own repo before shipping this default.
+            "--skip-path",
+            "**/fix-library/**,**/fixLibrary/**,**/security-templates/**",
+        ], { reject: false });
+        // Bearer's own internal errors (e.g. rule definitions failing to
+        // download) print "Error: ..." to stderr and produce an empty/invalid
+        // report, distinct from its normal "exit non-zero because findings
+        // exist" behavior. Confirmed this distinction by directly reproducing
+        // a rule-download failure (GitHub API rate limit) in testing.
+        const stderrText = result.stderr ?? "";
+        const errorLine = stderrText.split("\n").find((line) => line.includes("Error:"));
+        if (errorLine) {
+            throw new BearerScanFailedError(errorLine.trim());
+        }
+        const raw = await readFile(reportPath, "utf-8").catch(() => null);
+        if (raw === null) {
+            throw new BearerScanFailedError("no report file was produced");
+        }
+        const parsed = JSON.parse(raw);
+        const findings = [];
+        for (const [severity, entries] of Object.entries(parsed)) {
+            if (!["critical", "high", "medium", "low"].includes(severity))
+                continue;
+            for (const entry of entries) {
+                if (OVERLAPS_WITH_HYGIENE_SCANNER.has(entry.id))
+                    continue;
+                findings.push({
+                    ruleId: entry.id,
+                    title: entry.title,
+                    description: entry.description.split("\n")[0].replace(/^##\s*Description\s*/, "").trim() || entry.title,
+                    file: entry.filename,
+                    line: entry.line_number,
+                    severity: severity,
+                });
+            }
+        }
+        return findings;
+    }
+    finally {
+        await unlink(reportPath).catch(() => { });
+    }
+}

package/dist/scanners/ensureBinary.js

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import { mkdir, chmod, rm, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// This file lives at dist/scanners/ensureBinary.js at runtime — two levels
+// up is the package root, matching every other scanner's path resolution.
+const PACKAGE_ROOT = join(__dirname, "..", "..");
+const VENDOR_DIR = join(PACKAGE_ROOT, "bin", "vendor");
+const GITLEAKS_VERSION = "8.30.1";
+const BEARER_VERSION = "2.1.0";
+function resolveGitleaksSpec() {
+    const platformMap = { linux: "linux", darwin: "darwin", win32: "windows" };
+    const archMap = { x64: "x64", arm64: "arm64" };
+    const mappedPlatform = platformMap[process.platform];
+    const mappedArch = archMap[process.arch];
+    if (!mappedPlatform || !mappedArch)
+        return null;
+    const ext = mappedPlatform === "windows" ? "zip" : "tar.gz";
+    const binName = mappedPlatform === "windows" ? "gitleaks.exe" : "gitleaks";
+    const assetName = `gitleaks_${GITLEAKS_VERSION}_${mappedPlatform}_${mappedArch}.${ext}`;
+    return {
+        toolName: "gitleaks",
+        targetBin: join(VENDOR_DIR, binName),
+        url: `https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${assetName}`,
+        ext,
+        binName,
+    };
+}
+function resolveBearerSpec() {
+    if (process.platform === "win32")
+        return null; // confirmed: no native Windows build exists
+    const platformMap = { linux: "linux", darwin: "darwin" };
+    const archMap = { x64: "amd64", arm64: "arm64" };
+    const mappedPlatform = platformMap[process.platform];
+    const mappedArch = archMap[process.arch];
+    if (!mappedPlatform || !mappedArch)
+        return null;
+    const assetName = `bearer_${BEARER_VERSION}_${mappedPlatform}_${mappedArch}.tar.gz`;
+    return {
+        toolName: "bearer",
+        targetBin: join(VENDOR_DIR, "bearer"),
+        url: `https://github.com/Bearer/bearer/releases/download/v${BEARER_VERSION}/${assetName}`,
+        ext: "tar.gz",
+        binName: "bearer",
+    };
+}
+async function downloadAndExtract(spec) {
+    await mkdir(VENDOR_DIR, { recursive: true });
+    const archivePath = join(VENDOR_DIR, `${spec.toolName}-download.${spec.ext}`);
+    const res = await fetch(spec.url);
+    if (!res.ok) {
+        throw new Error(`Failed to download ${spec.toolName} from ${spec.url} (status ${res.status})`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    await writeFile(archivePath, buf);
+    if (spec.ext === "tar.gz") {
+        await execFileAsync("tar", ["-xzf", archivePath, "-C", VENDOR_DIR, spec.binName]);
+    }
+    else {
+        // Windows has no default 'unzip' — PowerShell's Expand-Archive ships
+        // with every Windows 10+ machine, same fix as the original postinstall bug.
+        await execFileAsync("powershell", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${VENDOR_DIR}' -Force`,
+        ]);
+    }
+    await rm(archivePath);
+    await chmod(spec.targetBin, 0o755);
+}
+/**
+ * Ensures a scanner binary is present, downloading it if missing. This is
+ * the RUNTIME fallback that makes CodeVet resilient to a real, confirmed
+ * issue: npm now blocks postinstall scripts by default (its own
+ * "allowScripts" feature) unless a package is explicitly approved.
+ * postinstall.mjs's download logic was completely correct — it just
+ * never got permission to run on a real user's machine, silently leaving
+ * gitleaks missing with no indication why.
+ *
+ * Rather than depending only on install-time postinstall (a single point
+ * of failure), every scanner now self-heals: if its binary isn't there
+ * when actually needed, it downloads right then — the user sees exactly
+ * what's happening (one-time message) instead of a permanent, confusing
+ * failure that "try npm install again" can never actually fix.
+ */
+export async function ensureBinary(tool) {
+    const spec = tool === "gitleaks" ? resolveGitleaksSpec() : resolveBearerSpec();
+    if (!spec)
+        return null; // unsupported platform (e.g. bearer on Windows) — not an error
+    if (existsSync(spec.targetBin)) {
+        return spec.targetBin;
+    }
+    console.error(`[codevet] ${spec.toolName} binary not found — this usually means npm blocked the install script (npm's "allowScripts" security feature). Downloading it directly now instead — this only happens once.`);
+    await downloadAndExtract(spec);
+    return spec.targetBin;
+}

package/dist/scanners/gitleaksScanner.js

@@ -0,0 +1,109 @@
+import { execa } from "execa";
+import { readFile, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureBinary } from "./ensureBinary.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// This file lives at dist/scanners/gitleaksScanner.js at runtime, whether
+// CodeVet is run standalone (cloned repo) or installed as a dependency
+// inside another project's node_modules/codevet/ — the relative path up
+// to the package root is identical either way, so this resolves correctly
+// in both installation modes.
+const PACKAGE_ROOT = join(__dirname, "..", "..");
+const RULES_CONFIG = join(PACKAGE_ROOT, ".gitleaks.toml");
+export class GitleaksBinaryMissingError extends Error {
+    constructor() {
+        super("gitleaks binary not found and could not be downloaded automatically. Check your network connection and try again, or install gitleaks manually and place it at bin/vendor/gitleaks.");
+        this.name = "GitleaksBinaryMissingError";
+    }
+}
+export async function runGitleaksScan(projectRoot) {
+    // ensureBinary self-heals: downloads the binary right now if it's
+    // missing (e.g. npm blocked postinstall from ever running it), instead
+    // of just failing with a message that "try npm install again" can
+    // never actually fix. Confirmed as a real, live issue via a bug report.
+    const binaryPath = await ensureBinary("gitleaks");
+    if (!binaryPath) {
+        throw new GitleaksBinaryMissingError();
+    }
+    const reportPath = join(projectRoot, ".codevet-gitleaks-report.json");
+    try {
+        await execa(binaryPath, [
+            "detect",
+            "--source",
+            projectRoot,
+            "--config",
+            RULES_CONFIG,
+            "--report-format",
+            "json",
+            "--report-path",
+            reportPath,
+            "--no-banner",
+            "--no-git",
+        ], { reject: false });
+        const raw = await readFile(reportPath, "utf-8").catch(() => "[]");
+        const parsed = JSON.parse(raw);
+        const findings = parsed.map((entry) => ({
+            ruleId: entry.RuleID,
+            description: entry.Description,
+            file: entry.File,
+            line: entry.StartLine,
+        }));
+        return await postProcess(findings, projectRoot);
+    }
+    finally {
+        await unlink(reportPath).catch(() => { });
+    }
+}
+/**
+ * Two real issues found in live Windows testing, fixed here rather than in
+ * the raw gitleaks output:
+ *
+ * 1. Duplicate findings — the same (file, line, rule) can be reported more
+ *    than once by gitleaks when overlapping rules both match; we only want
+ *    to show it once.
+ *
+ * 2. .env files legitimately contain real secret values locally — that's
+ *    the whole point of .env. The actual risk isn't the values, it's
+ *    whether the file is protected by .gitignore. If it IS gitignored, its
+ *    contents can never reach a commit, so flagging them as "leaked" is a
+ *    false positive. If it's NOT gitignored, that's a real and more
+ *    important problem worth its own clear finding.
+ */
+async function postProcess(findings, projectRoot) {
+    const seen = new Set();
+    const deduped = findings.filter((f) => {
+        const key = `${f.file}:${f.line}:${f.ruleId}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const isGitRepo = existsSync(join(projectRoot, ".git"));
+    if (!isGitRepo)
+        return deduped;
+    const envIsIgnored = await execa("git", ["check-ignore", ".env"], {
+        cwd: projectRoot,
+        reject: false,
+    }).then((r) => r.exitCode === 0);
+    if (envIsIgnored) {
+        // .env is protected — drop findings whose file is exactly .env, since
+        // its contents can't leak through git.
+        return deduped.filter((f) => !/(^|[/\\])\.env$/.test(f.file));
+    }
+    // .env exists and is NOT gitignored — replace any per-line findings
+    // inside it with one clear, higher-signal warning instead of dumping
+    // every value found inside it.
+    const hasEnvFindings = deduped.some((f) => /(^|[/\\])\.env$/.test(f.file));
+    const withoutEnvDetails = deduped.filter((f) => !/(^|[/\\])\.env$/.test(f.file));
+    if (hasEnvFindings) {
+        withoutEnvDetails.push({
+            ruleId: "env-file-not-gitignored",
+            description: ".env exists and contains real values, but is NOT excluded by .gitignore — every credential in it can end up committed to git history.",
+            file: ".env",
+            line: 1,
+        });
+    }
+    return withoutEnvDetails;
+}

package/dist/scanners/hygieneScanner.js

@@ -0,0 +1,156 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+import { FIX_TEMPLATES } from "../fixLibrary/templates.js";
+/**
+ * These are heuristic checks — package.json presence and regex scans, not
+ * a real AST parse. That means false negatives are possible (a helmet-like
+ * setup written by hand instead of the package would be missed) and
+ * "advisory" findings can be wrong for unusual architectures. Marked
+ * explicitly per-finding rather than presented with false confidence.
+ */
+export async function runHygieneScan(projectRoot) {
+    const packageJsonPath = join(projectRoot, "package.json");
+    if (!existsSync(packageJsonPath))
+        return [];
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf-8"));
+    const allDeps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    const hasDep = (name) => Boolean(allDeps[name]);
+    const findings = [];
+    // RLS check is independent of Express — Supabase is at least as common
+    // with Next.js/other frontends as with an Express backend, and skipping
+    // it here would silently miss exactly the audience most likely to use
+    // Supabase directly from the client.
+    findings.push(...(await runSupabaseRlsScan(projectRoot)));
+    // Only run Express-specific checks on projects that actually use Express
+    // — otherwise every finding below would be a guaranteed false positive
+    // on a non-Express project.
+    if (!hasDep("express"))
+        return findings;
+    if (!hasDep("helmet")) {
+        findings.push({
+            id: "missing-helmet",
+            title: "No security headers configured",
+            description: "helmet isn't installed — your responses have no protection against clickjacking, MIME-sniffing, or several XSS vectors.",
+            severity: "moderate",
+            verifyNote: "Defense-in-depth, not usually directly exploitable on its own — real risk, but rarely the single point of failure in an incident.",
+            fix: FIX_TEMPLATES.helmet,
+        });
+    }
+    if (!hasDep("express-rate-limit")) {
+        findings.push({
+            id: "missing-rate-limit",
+            title: "No rate limiting found",
+            description: "express-rate-limit isn't installed — login and other sensitive endpoints have no protection against brute-force or spam.",
+            severity: "high",
+            verifyNote: "Directly exploitable if auth routes exist with no other rate-limiting layer (e.g. a reverse proxy).",
+            fix: FIX_TEMPLATES.rateLimit,
+        });
+    }
+    const hasValidationLib = hasDep("zod") || hasDep("joi") || hasDep("yup");
+    if (!hasValidationLib) {
+        findings.push({
+            id: "missing-validation",
+            title: "No schema validation library found",
+            description: "Neither zod, joi, nor yup is installed. If requests are validated by hand, this is likely a false positive — worth a manual check either way.",
+            severity: "moderate",
+            verifyNote: "This check only looks for known validation libraries — hand-written validation is common and invisible to it. Confirm manually before treating this as real.",
+            fix: FIX_TEMPLATES.validation,
+        });
+    }
+    const sourceFindings = await scanSourceForPatterns(projectRoot);
+    findings.push(...sourceFindings);
+    return findings;
+}
+/**
+ * Supabase-specific check: scans .sql migration files for CREATE TABLE
+ * statements with no matching ENABLE ROW LEVEL SECURITY in the same file.
+ * This is a best-effort STATIC check only — it cannot see tables created
+ * via the Supabase dashboard UI or RLS enabled outside migration files.
+ * Rated CRITICAL severity (a real missing-RLS table is the single most
+ * common cause of a drained/defaced Supabase app), with verifyNote always
+ * set to keep that static-check limitation visible alongside the severity.
+ */
+export async function runSupabaseRlsScan(projectRoot) {
+    const sqlFiles = await fg(["**/*.sql"], {
+        cwd: projectRoot,
+        absolute: true,
+        ignore: ["**/node_modules/**"],
+    });
+    if (sqlFiles.length === 0)
+        return [];
+    const findings = [];
+    for (const sqlFile of sqlFiles) {
+        const content = await readFile(sqlFile, "utf-8").catch(() => "");
+        const tableMatches = [...content.matchAll(/CREATE TABLE\s+(?:IF NOT EXISTS\s+)?["`]?(\w+)["`]?/gi)];
+        for (const match of tableMatches) {
+            const tableName = match[1];
+            const rlsPattern = new RegExp(`ALTER TABLE\\s+["\`]?${tableName}["\`]?\\s+ENABLE ROW LEVEL SECURITY`, "i");
+            if (!rlsPattern.test(content)) {
+                findings.push({
+                    id: `supabase-rls-missing-${tableName}`,
+                    title: `Table '${tableName}' may be missing Row Level Security`,
+                    description: `Found in ${sqlFile.replace(projectRoot, "").replace(/^[/\\]/, "")} — no matching 'ENABLE ROW LEVEL SECURITY' for this table in the same file. Without RLS, the public anon key can read and write this table directly — this is the single most common cause of drained or defaced Supabase-backed apps.`,
+                    severity: "critical",
+                    verifyNote: "Static check only — it cannot see RLS enabled via the Supabase dashboard UI or outside migration files. Verify directly in the dashboard before treating a clean result as certain.",
+                    fix: FIX_TEMPLATES.rlsEnable,
+                });
+            }
+        }
+    }
+    return findings;
+}
+async function scanSourceForPatterns(projectRoot) {
+    const findings = [];
+    const files = await fg(["**/*.js", "**/*.ts"], {
+        cwd: projectRoot,
+        absolute: true,
+        ignore: [
+            "**/node_modules/**",
+            "**/.next/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/*.test.*",
+            "**/*.spec.*",
+        ],
+    });
+    let corsWildcardFound = false;
+    let errorLeakFound = false;
+    for (const file of files) {
+        const content = await readFile(file, "utf-8").catch(() => "");
+        if (!corsWildcardFound && /cors\s*\(\s*\)|origin\s*:\s*['"]\*['"]/.test(content)) {
+            corsWildcardFound = true;
+        }
+        // Heuristic: sending err.stack or err.message directly in a response
+        // body is a real, specific leak pattern — not "any error handling."
+        // Matches res.json(...) and the more common res.status(500).json(...).
+        if (!errorLeakFound &&
+            /res(\.status\([^)]*\))?\.(json|send)\([^)]*(err(or)?\.(stack|message))/.test(content)) {
+            errorLeakFound = true;
+        }
+        if (corsWildcardFound && errorLeakFound)
+            break;
+    }
+    if (corsWildcardFound) {
+        findings.push({
+            id: "cors-wildcard",
+            title: "CORS may be wide open",
+            description: "Found cors() with no origin restriction, or an explicit '*' origin — any website can currently read responses from this API.",
+            severity: "high",
+            verifyNote: "Pattern-based match — confirm the actual runtime config, since environment-specific overrides won't show here.",
+            fix: FIX_TEMPLATES.cors,
+        });
+    }
+    if (errorLeakFound) {
+        findings.push({
+            id: "error-leak",
+            title: "Error response may leak internals",
+            description: "Found a response that sends err.stack or err.message directly to the client — this can expose file paths, internal logic, or raw database errors.",
+            severity: "high",
+            verifyNote: "Confirmed by matching an actual response-sending pattern, not just the presence/absence of a library — lower false-positive risk than the other checks here.",
+            fix: FIX_TEMPLATES.errorHandler,
+        });
+    }
+    return findings;
+}

package/dist/scanners/npmAuditScanner.js

@@ -0,0 +1,118 @@
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export class NpmAuditScanFailedError extends Error {
+    constructor(reason) {
+        super(`npm audit did not actually run: ${reason}. This is being reported as a failure rather than "no vulnerabilities" — a scan that never ran is not the same as a clean result.`);
+        this.name = "NpmAuditScanFailedError";
+    }
+}
+export class WrongPackageManagerError extends Error {
+    constructor(manager) {
+        super(`this project uses ${manager}, not npm — npm audit cannot reliably scan a ${manager}-managed dependency tree. Confirmed in testing: npm's own dependency resolver (arborist) crashes with an internal error ("Cannot read properties of null") when node_modules contains ${manager}'s symlink structure, which is a real bug in npm itself, not something CodeVet can work around. Run '${manager} audit' directly for this project.`);
+        this.name = "WrongPackageManagerError";
+    }
+}
+/**
+ * Detects a package manager npm's own dependency resolver cannot reliably
+ * handle. Confirmed by directly reproducing the failure: a pnpm-managed
+ * node_modules/.pnpm virtual store crashes npm's arborist mid-resolution
+ * with an unhandled internal TypeError, not a normal, catchable npm error.
+ * Rather than let that crash surface as a scary internal stack trace, we
+ * detect the situation up front and skip cleanly with a clear reason.
+ */
+function detectIncompatiblePackageManager(projectRoot) {
+    if (existsSync(join(projectRoot, "pnpm-lock.yaml")) || existsSync(join(projectRoot, "node_modules", ".pnpm"))) {
+        return "pnpm";
+    }
+    // Same underlying npm/arborist bug class (npm/cli#9459 — Arborist
+    // crashes with "Cannot read properties of null (reading 'matches')" on
+    // a Link with a null target), triggered by Yarn's node_modules
+    // structure (classic Yarn's flat symlink layout, or Yarn Berry/PnP's
+    // .pnp.cjs) instead of pnpm's virtual store. Detected via yarn.lock or
+    // the .yarnrc.yml Yarn Berry uses, rather than trying to reproduce the
+    // crash signature itself.
+    if (existsSync(join(projectRoot, "yarn.lock")) ||
+        existsSync(join(projectRoot, ".yarnrc.yml")) ||
+        existsSync(join(projectRoot, ".pnp.cjs"))) {
+        return "yarn";
+    }
+    return null;
+}
+/**
+ * Runs a real npm audit against package.json/package-lock.json. This checks
+ * against npm's published advisory database (known, disclosed CVEs) — it
+ * does NOT detect novel malware or unpublished zero-days. That distinction
+ * matters and should stay visible in the report, not be implied away.
+ *
+ * If no lockfile exists, we generate one with `--package-lock-only
+ * --ignore-scripts` — this resolves the dependency tree WITHOUT installing
+ * any package or running any install/postinstall script. That matters for
+ * scanning an untrusted repo (e.g. before a URL-clone confirmation): a
+ * normal `npm install` would execute arbitrary scripts from every
+ * dependency before we ever get to look at the results.
+ */
+export async function runNpmAuditScan(projectRoot) {
+    const packageJsonPath = join(projectRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return [];
+    }
+    const incompatibleManager = detectIncompatiblePackageManager(projectRoot);
+    if (incompatibleManager) {
+        throw new WrongPackageManagerError(incompatibleManager);
+    }
+    const lockfilePath = join(projectRoot, "package-lock.json");
+    if (!existsSync(lockfilePath)) {
+        const lockResult = await execa("npm", ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: projectRoot, reject: false });
+        // If lockfile generation itself failed, npm audit below will fail too
+        // (ENOLOCK) — no point running it, and the error is clearer here.
+        // Show the FULL stderr, not just the first line — a truncated error
+        // message made a real failure (a Turborepo monorepo project) much
+        // harder to diagnose than necessary, since npm's actual diagnostic
+        // detail (often including a debug-log path) was being cut off.
+        if (lockResult.exitCode !== 0 && !existsSync(lockfilePath)) {
+            const fullError = lockResult.stderr.trim() || lockResult.stdout.trim() || "unknown error";
+            throw new NpmAuditScanFailedError(`could not generate a package-lock.json.\n${fullError}`);
+        }
+    }
+    const result = await execa("npm", ["audit", "--json"], {
+        cwd: projectRoot,
+        reject: false, // npm audit exits non-zero when it finds vulnerabilities — expected
+    });
+    let report;
+    try {
+        report = JSON.parse(result.stdout);
+    }
+    catch {
+        // Genuinely unparseable output (not even npm's own error JSON shape)
+        // — a real failure, not a clean result.
+        throw new NpmAuditScanFailedError(result.stderr.split("\n")[0] || "npm audit produced no readable output");
+    }
+    if (report.error) {
+        throw new NpmAuditScanFailedError(`${report.error.code}: ${report.error.summary}`);
+    }
+    if (!report.vulnerabilities)
+        return [];
+    return Object.values(report.vulnerabilities).map((v) => {
+        const advisories = v.via
+            .filter((entry) => typeof entry !== "string")
+            .map((entry) => ({
+            title: entry.title,
+            url: entry.url,
+            severity: entry.severity ?? v.severity,
+        }));
+        return {
+            packageName: v.name,
+            severity: v.severity,
+            advisories: advisories.length > 0
+                ? advisories
+                : [{ title: `Known vulnerability in ${v.name}`, severity: v.severity }],
+            fixAvailable: typeof v.fixAvailable === "object"
+                ? `${v.fixAvailable.name}@${v.fixAvailable.version}`
+                : v.fixAvailable
+                    ? "Run `npm audit fix`"
+                    : false,
+            isDirect: v.isDirect,
+        };
+    });
+}

package/dist/scanners/npmFixActions.js

@@ -0,0 +1,50 @@
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runNpmAuditScan } from "./npmAuditScanner.js";
+/**
+ * Runs `npm audit fix` — upgrades packages to the newest version that
+ * satisfies the existing semver range in package.json. This is the "safe"
+ * remediation: it does not change your major version constraints unless
+ * `force` is explicitly requested, matching npm's own safety model rather
+ * than inventing our own.
+ */
+export async function runFix(projectRoot, force) {
+    const before = await runNpmAuditScan(projectRoot);
+    const args = ["audit", "fix"];
+    if (force)
+        args.push("--force");
+    await execa("npm", args, { cwd: projectRoot, reject: false });
+    const after = await runNpmAuditScan(projectRoot);
+    return { before, after, ranForceFix: force };
+}
+/**
+ * Explicitly uninstalls a single flagged package. This is NOT the same as
+ * `fix` — removing a dependency the application actually imports and uses
+ * will break the app. This exists for the case where a flagged package is
+ * unused/leftover and the right move is deleting it outright, not
+ * upgrading it. The CLI layer is responsible for warning the user before
+ * calling this.
+ */
+export async function removeDependency(projectRoot, packageName) {
+    const packageJsonPath = join(projectRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return { packageName, wasPresent: false, removed: false, error: "No package.json found" };
+    }
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf-8"));
+    const wasPresent = Boolean(packageJson.dependencies?.[packageName] || packageJson.devDependencies?.[packageName]);
+    if (!wasPresent) {
+        return { packageName, wasPresent: false, removed: false };
+    }
+    const result = await execa("npm", ["uninstall", packageName], {
+        cwd: projectRoot,
+        reject: false,
+    });
+    return {
+        packageName,
+        wasPresent: true,
+        removed: result.exitCode === 0,
+        error: result.exitCode !== 0 ? result.stderr : undefined,
+    };
+}