securevibe 0.1.7 → 0.1.10

package/README.md

@@ -27,6 +27,7 @@ midnight). The `--staged` commit guard is never limited. See [`LICENSE`](LICENSE
 | `securevibe scan [path]` | Full scan → findings + security score (default command) |
 | `securevibe init [path]` | **Wire SecureVibe in: pre-commit guard + GitHub Action + gitignore** (doc 12) |
 | `securevibe fix [path]` | **Autonomously fix findings, then re-scan to verify** (doc 05) |
+| `securevibe explain [path]` | AI-powered plain-language explanations for critical/high findings |
 | `securevibe deps [path]` | Audit dependencies for known CVEs against the local OSV database (SCA) |
 | `securevibe db <update\|status>` | Manage the local OSV database — `update` is the only networked command |
 | `securevibe ready [path]` | Launch readiness scorecard: pass/fail gates + go/no-go verdict |
@@ -34,6 +35,8 @@ midnight). The `--staged` commit guard is never limited. See [`LICENSE`](LICENSE
 | `securevibe protect [path]` | Remediation-first view: the fix for every finding (doc 05) |
 | `securevibe attack-map [path]` | Exploit paths from reachable findings + choke point (doc 06) |
 | `securevibe score [path]` | Just the score + deployment-readiness verdict (doc 08) |
+| `securevibe config <show\|set-key\|unset-key>` | Manage local Groq/Anthropic keys for the AI-powered fixer |
+| `securevibe repl [path]` | Interactive session — run `scan`/`fix`/etc without re-invoking the CLI each time |
 
 Flags: `--json`, `--sarif` (GitHub code-scanning / CI interop), `--no-color`,
 `--ci` (exit `2` on BLOCK, `1` on WARN, `0` on SHIP — for build gates),
@@ -76,11 +79,20 @@ Anything that fails the gate is rolled back and surfaced as a manual instruction
   is kept **only if it passes the verification gate**, otherwise it falls back to a precise manual
   instruction. Groq is used by default when both keys are present (lower bar to try it at all);
   set `SECUREVIBE_LLM_PROVIDER=anthropic` to force Claude instead.
-- **Setting a key:** either export it yourself (`GROQ_API_KEY=...`), or run
-  `securevibe config set-key groq` — it prompts interactively (never as a command argument, so it
-  never lands in shell history) and saves it to `~/.securevibe/config.json`, used automatically by
-  `fix` whenever the env var isn't already set. Run `fix --apply` with no key configured and it will
-  offer to set one up on the spot. `securevibe config show` lists what's stored (masked).
+- **Setting a key:** `securevibe init` is the primary path — if it detects an LLM SDK dependency
+  (openai, `@anthropic-ai/sdk`, langchain, ...) and no key is already set, it offers to set one up
+  on the spot, once per project (declining is remembered so it won't ask again). You can also
+  export a key yourself (`GROQ_API_KEY=...`), or run `securevibe config set-key groq` any time — it
+  prompts interactively (never as a command argument, so it never lands in shell history) and saves
+  it to `~/.securevibe/config.json`, used automatically whenever the env var isn't already set.
+- **A second AI feature, `securevibe explain`:** for critical/high findings, asks
+  the same configured provider for a plain-language explanation grounded in the
+  actual flagged code (not just the generic why/fix text every finding of that
+  detector shares). Capped at the top 10 qualifying findings per run. Falls back to
+  the static why/fix text with no key configured, or if a call fails — an
+  explanation is always additional context, never required to use the command.
+  `fix --apply` with no key configured still offers to set one up as a fallback.
+  `securevibe config show` lists what's stored (masked).
 
 **Honesty (read this):**
 - A "fixed" finding means *our detector no longer flags it* — not that the app is proven secure.

package/dist/engine/explain.js

@@ -0,0 +1,79 @@
+/**
+ * `securevibe explain` (AI feature #2, 2026-07-10). Turns a critical/high
+ * finding's generic why/fix text into a plain-language explanation grounded
+ * in the actual flagged code. Read-only — no files are modified, so there is
+ * no verification/rollback gate the way `fix` needs one.
+ *
+ * Capped at EXPLAIN_MAX_FINDINGS per run to bound worst-case AI cost/latency:
+ * a scan with dozens of criticals should never turn into dozens of API calls
+ * without the caller asking for it. Degrades gracefully with no provider
+ * configured (or a failed call) — every finding still gets a result, with
+ * explanation: null, so the UI layer falls back to the static why/fix text.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { SEVERITY_ORDER } from "./types.js";
+import { llmChat, llmAvailability } from "./fix/llm.js";
+export const EXPLAIN_MAX_FINDINGS = 10;
+const EXPLAIN_SEVERITIES = new Set(["critical", "high"]);
+const SNIPPET_CONTEXT_LINES = 4;
+const EXPLAIN_SYSTEM = [
+    "You are a senior application-security engineer explaining one specific vulnerability finding to the developer who wrote the code.",
+    "You will receive the finding's detector, severity, generic why/fix guidance, and a snippet of the actual flagged code (the vulnerable line is marked with >>).",
+    "Write a short plain-language explanation (3-5 sentences) of the concrete risk IN THIS CODE specifically — reference the actual variable, function, or endpoint names visible in the snippet, not generic advice.",
+    "Do not repeat the generic why/fix text verbatim. Do not add a heading, bullet list, or markdown formatting. Return prose only.",
+].join("\n");
+function explainUserPrompt(finding, snippet) {
+    return [
+        `Finding: ${finding.title}`,
+        `Detector: ${finding.detector}  Severity: ${finding.severity}${finding.cwe ? `  ${finding.cwe}` : ""}`,
+        `File: ${finding.file}:${finding.line}`,
+        "",
+        "Generic why:",
+        finding.why,
+        "",
+        "Generic fix:",
+        finding.fix,
+        "",
+        "Code snippet (flagged line marked with >>):",
+        snippet,
+    ].join("\n");
+}
+/** A fixed window of lines around `line` (1-indexed), clamped to file bounds. */
+export function extractSnippet(code, line) {
+    const lines = code.split(/\r?\n/);
+    const idx = Math.min(Math.max(line - 1, 0), lines.length - 1);
+    const start = Math.max(0, idx - SNIPPET_CONTEXT_LINES);
+    const end = Math.min(lines.length, idx + SNIPPET_CONTEXT_LINES + 1);
+    const out = [];
+    for (let i = start; i < end; i++) {
+        out.push(`${i === idx ? ">>" : "  "} ${i + 1}: ${lines[i]}`);
+    }
+    return out.join("\n");
+}
+export async function explainFindings(scanResult, opts = {}) {
+    const qualifying = scanResult.findings
+        .filter((f) => EXPLAIN_SEVERITIES.has(f.severity))
+        .sort((a, b) => SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity] || b.confidence - a.confidence);
+    const capped = qualifying.slice(0, EXPLAIN_MAX_FINDINGS);
+    const truncatedCount = qualifying.length - capped.length;
+    const avail = llmAvailability(false);
+    const results = [];
+    for (const finding of capped) {
+        opts.onProgress?.(`Explaining ${finding.file}:${finding.line}…`);
+        let explanation = null;
+        if (avail.available) {
+            let snippet;
+            try {
+                const code = await fs.readFile(path.join(scanResult.root, finding.file), "utf8");
+                snippet = extractSnippet(code, finding.line);
+            }
+            catch {
+                snippet = "(source unavailable)";
+            }
+            explanation = await llmChat(EXPLAIN_SYSTEM, explainUserPrompt(finding, snippet));
+        }
+        results.push({ finding, explanation });
+    }
+    return { root: scanResult.root, results, truncatedCount, llmAvailable: avail.available };
+}

package/dist/engine/fix/llm.js

@@ -94,18 +94,30 @@ function userPrompt(input) {
 export async function llmFix(input) {
     if (input.code.length > MAX_FILE_CHARS)
         return null;
+    const text = await llmChat(SYSTEM, userPrompt(input));
+    if (text == null)
+        return null;
+    return parseFile(text, input.code);
+}
+/**
+ * Generic single-turn chat call against whichever provider is configured.
+ * Shared by llmFix (full-file rewrites) and engine/explain.ts (plain-language
+ * finding explanations) so the Groq/Anthropic HTTP plumbing lives in one place.
+ * Returns null on no-provider / network / auth / quota failure — callers degrade
+ * gracefully and must never throw because of this.
+ */
+export async function llmChat(system, user) {
     const provider = selectProvider();
     if (!provider)
         return null;
     try {
-        const text = provider === "groq" ? await callGroq(input) : await callAnthropic(input);
-        return parseFile(text, input.code);
+        return provider === "groq" ? await callGroq(system, user) : await callAnthropic(system, user);
     }
     catch {
-        return null; // network / auth / quota failure → fall back to manual
+        return null;
     }
 }
-async function callAnthropic(input) {
+async function callAnthropic(system, user) {
     let Anthropic;
     try {
         ({ default: Anthropic } = await import("@anthropic-ai/sdk"));
@@ -117,13 +129,13 @@ async function callAnthropic(input) {
     const msg = await client.messages.create({
         model: modelFor("anthropic"),
         max_tokens: 8192,
-        system: SYSTEM,
-        messages: [{ role: "user", content: userPrompt(input) }],
+        system,
+        messages: [{ role: "user", content: user }],
     });
     return extractAnthropicText(msg);
 }
 /** Groq's chat-completions endpoint is OpenAI-compatible — plain fetch, no SDK. */
-async function callGroq(input) {
+async function callGroq(system, user) {
     const res = await fetch("https://api.groq.com/openai/v1/chat/completions", {
         method: "POST",
         headers: {
@@ -134,8 +146,8 @@ async function callGroq(input) {
             model: modelFor("groq"),
             max_tokens: 8192,
             messages: [
-                { role: "system", content: SYSTEM },
-                { role: "user", content: userPrompt(input) },
+                { role: "system", content: system },
+                { role: "user", content: user },
             ],
         }),
     });

package/dist/engine/init.js

@@ -9,6 +9,43 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { isGitRepo, gitDir } from "./git.js";
+export function projectConfigPath(root) {
+    return path.join(path.resolve(root), "securevibe.config.json");
+}
+/** Tolerant read: a missing or corrupt config is treated as empty. */
+export async function readProjectConfig(root) {
+    try {
+        const raw = await fs.readFile(projectConfigPath(root), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function patchProjectConfig(root, patch) {
+    const current = await readProjectConfig(root);
+    const next = { ...current, ...patch };
+    await fs.writeFile(projectConfigPath(root), JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+// Package names/imports that mark a repo as "uses an LLM SDK" — matched against
+// package.json (dependency keys) and requirements.txt (package names) so the
+// init-time AI-fixer offer only fires where it's actually relevant.
+const AI_PACKAGE_RE = /"(openai|@anthropic-ai\/sdk|anthropic|langchain|@langchain\/[\w.-]+|cohere-ai|@google\/generative-ai|llamaindex|@modelcontextprotocol\/sdk)"\s*:|^\s*(openai|anthropic|langchain|cohere|google-generativeai|llama-index)\b/im;
+export async function looksAiRelated(root) {
+    const absRoot = path.resolve(root);
+    for (const rel of ["package.json", "requirements.txt"]) {
+        try {
+            const content = await fs.readFile(path.join(absRoot, rel), "utf8");
+            if (AI_PACKAGE_RE.test(content))
+                return true;
+        }
+        catch {
+            /* file absent — try the next */
+        }
+    }
+    return false;
+}
 const GITIGNORE_LINES = [".env", ".env.local", ".env.*.local", ".securevibe-backup/"];
 const CONFIG = `{
   "failOn": "block",

package/dist/index-support.js

@@ -0,0 +1,61 @@
+/**
+ * Shared helpers used by both the one-shot CLI commands (index.ts) and the
+ * interactive REPL (repl.ts), so the two entry points never duplicate logic.
+ */
+/**
+ * If `fix` is about to run with no AI-fixer provider key available (and we're
+ * in an interactive terminal), offer to set one up on the spot — a free Groq
+ * key takes under a minute. Never prompts under --json/non-TTY/--no-llm, and
+ * never touches process.env if the user declines or a key is already set.
+ */
+export async function maybeOfferAiFixerSetup() {
+    if (process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)
+        return;
+    const { isInteractive, askLine } = await import("./ui/prompt.js");
+    if (!isInteractive())
+        return;
+    process.stderr.write("\n  AI auto-fix (RCE, AI tool-hijack, IDOR, complex SQLi) needs a provider key — you don't have one set.\n");
+    const ans = (await askLine("  Enable it now with a free Groq key? [y/N]: ")).trim().toLowerCase();
+    if (ans !== "y" && ans !== "yes") {
+        process.stderr.write("  Skipping — those findings will show as manual review. Run `securevibe config set-key groq` anytime.\n\n");
+        return;
+    }
+    const key = (await askLine("  Paste your Groq key (get one free at console.groq.com/keys): ")).trim();
+    if (!key) {
+        process.stderr.write("  No key entered — skipping.\n\n");
+        return;
+    }
+    const { setKey, configFilePath } = await import("./config.js");
+    await setKey("groq", key);
+    process.env.GROQ_API_KEY = key;
+    process.stderr.write(`  Saved to ${configFilePath()}. This run will use it.\n\n`);
+}
+/**
+ * Runs once at the end of `init`, interactive-only. Users were learning a
+ * provider key was needed only mid-`fix` — too late, past the point of
+ * expecting the fixer to already work. `init` already runs once per project
+ * before any `fix`, so it's the right place to surface this early — but only
+ * for repos that actually use an LLM SDK, and only once (a decline is
+ * remembered per-project so we don't nag).
+ */
+export async function maybeOfferAiFixerSetupDuringInit(root, deps) {
+    const { applyStoredKeysToEnv } = await import("./config.js");
+    await applyStoredKeysToEnv(deps?.configFile);
+    if (process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)
+        return;
+    const { readProjectConfig, patchProjectConfig, looksAiRelated } = await import("./engine/init.js");
+    const cfg = await readProjectConfig(root);
+    if (cfg.aiFixerPromptDismissed)
+        return;
+    if (!(await looksAiRelated(root)))
+        return;
+    const isInteractive = deps?.isInteractive ?? (await import("./ui/prompt.js")).isInteractive;
+    if (!isInteractive())
+        return;
+    process.stderr.write("\n  This project uses an LLM SDK — SecureVibe can auto-fix AI-specific findings\n  (tool-hijack, prompt-injection sinks) with a free key.\n");
+    const offer = deps?.offer ?? maybeOfferAiFixerSetup;
+    await offer();
+    if (!(process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+        await patchProjectConfig(root, { aiFixerPromptDismissed: true });
+    }
+}

package/dist/index.js

@@ -92,34 +92,6 @@ async function maybeNotifyUpdate(opts) {
     if (latest)
         process.stderr.write("\n" + updateNotice(VERSION, latest) + "\n");
 }
-/**
- * If `fix` is about to run with no AI-fixer provider key available (and we're
- * in an interactive terminal), offer to set one up on the spot — a free Groq
- * key takes under a minute. Never prompts under --json/non-TTY/--no-llm, and
- * never touches process.env if the user declines or a key is already set.
- */
-async function maybeOfferAiFixerSetup() {
-    if (process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)
-        return;
-    const { isInteractive, askLine } = await import("./ui/prompt.js");
-    if (!isInteractive())
-        return;
-    process.stderr.write("\n  AI auto-fix (RCE, AI tool-hijack, IDOR, complex SQLi) needs a provider key — you don't have one set.\n");
-    const ans = (await askLine("  Enable it now with a free Groq key? [y/N]: ")).trim().toLowerCase();
-    if (ans !== "y" && ans !== "yes") {
-        process.stderr.write("  Skipping — those findings will show as manual review. Run `securevibe config set-key groq` anytime.\n\n");
-        return;
-    }
-    const key = (await askLine("  Paste your Groq key (get one free at console.groq.com/keys): ")).trim();
-    if (!key) {
-        process.stderr.write("  No key entered — skipping.\n\n");
-        return;
-    }
-    const { setKey, configFilePath } = await import("./config.js");
-    await setKey("groq", key);
-    process.env.GROQ_API_KEY = key;
-    process.stderr.write(`  Saved to ${configFilePath()}. This run will use it.\n\n`);
-}
 /** Exit code policy for CI gating (doc 08/12). */
 function ciExit(result, opts) {
     if (!opts.ci)
@@ -156,6 +128,8 @@ program
     const { renderInit } = await import("./ui/init.js");
     const result = await runInit(pathArg ?? ".", { force: opts.force });
     process.stdout.write(renderInit(result) + "\n");
+    const { maybeOfferAiFixerSetupDuringInit } = await import("./index-support.js");
+    await maybeOfferAiFixerSetupDuringInit(pathArg ?? ".");
 });
 program
     .command("fix")
@@ -175,8 +149,10 @@ program
     const decision = decideApply(opts, isInteractive());
     // Only worth asking on a run that will actually write something — a dry-run
     // preview has no use for a key yet, and asking anyway reads as nagging.
-    if (opts.llm !== false && !opts.json && decision.apply)
+    if (opts.llm !== false && !opts.json && decision.apply) {
+        const { maybeOfferAiFixerSetup } = await import("./index-support.js");
         await maybeOfferAiFixerSetup();
+    }
     const usage = await meter();
     const { runFix } = await import("./engine/fix/session.js");
     const { renderFixSession, fixToJson, renderApprovalRequest } = await import("./ui/fix.js");
@@ -195,6 +171,36 @@ program
     }
     await maybeNotifyUpdate({ json: opts.json });
 });
+program
+    .command("explain")
+    .description("AI-powered plain-language explanations for critical/high findings")
+    .argument("[path]", "path to the repository", ".")
+    .option("--json", "output machine-readable JSON")
+    .option("--no-color", "disable coloured output")
+    .action(async (pathArg, opts) => {
+    if (opts.color === false)
+        process.env.NO_COLOR = "1";
+    const { applyStoredKeysToEnv } = await import("./config.js");
+    await applyStoredKeysToEnv();
+    if (!opts.json) {
+        const { maybeOfferAiFixerSetup } = await import("./index-support.js");
+        await maybeOfferAiFixerSetup();
+    }
+    const { result, usage } = await runScan(pathArg, { json: opts.json, color: opts.color });
+    const { explainFindings } = await import("./engine/explain.js");
+    const report = await explainFindings(result, {
+        onProgress: opts.json ? undefined : (m) => process.stderr.write(`  · ${m}\n`),
+    });
+    if (opts.json) {
+        const { explainToJson } = await import("./ui/explain.js");
+        process.stdout.write(explainToJson(report) + "\n");
+    }
+    else {
+        const { renderExplain } = await import("./ui/explain.js");
+        process.stdout.write(renderExplain(report, usage) + "\n");
+    }
+    await maybeNotifyUpdate({ json: opts.json });
+});
 addCommon(program
     .command("ai-audit")
     .description("Focus on the AI-application / agent attack surface (doc 04)")
@@ -352,6 +358,14 @@ program
     process.stderr.write(`  unknown config action: ${action} (use: show | set-key | unset-key)\n`);
     process.exit(64);
 });
+program
+    .command("repl")
+    .description("Interactive session: run scan/fix/etc without re-invoking the CLI each time")
+    .argument("[path]", "path to the repository", ".")
+    .action(async (pathArg) => {
+    const { runRepl } = await import("./repl.js");
+    await runRepl(pathArg ?? ".");
+});
 program.parseAsync(process.argv).catch((err) => {
     process.stderr.write(`securevibe: ${err?.message ?? err}\n`);
     process.exit(70);

package/dist/repl.js

@@ -0,0 +1,277 @@
+/**
+ * Interactive REPL (`securevibe repl`). A persistent session that holds the
+ * last scan result in memory and reuses the exact same underlying functions
+ * the one-shot commands use (scan(), runFix(), the ui/* renderers) — never
+ * the commander actions, since several of those call process.exit() on
+ * error/limit paths, which would tear down the whole session, not just the
+ * failed command.
+ *
+ * Only ever one readline interface alive at a time (via askLine, which opens
+ * and closes its own per call): the REPL's own prompt and any nested
+ * interactive flow (fix --apply confirmations, config set-key) are always
+ * sequential, never concurrent, so there's no stdin contention.
+ *
+ * Streams are injectable (runReplSession) so the whole loop — including
+ * fix --apply's confirm prompts — is unit-testable without a real TTY; the
+ * public runRepl() just wraps it with the real stdio + the TTY gate.
+ */
+import path from "node:path";
+import { askLine, isInteractive, decideApply, makeFixConfirm } from "./ui/prompt.js";
+function tokenize(line) {
+    const out = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let m;
+    while ((m = re.exec(line)))
+        out.push(m[1] ?? m[2] ?? m[3]);
+    return out;
+}
+function hasFlag(tokens, ...names) {
+    return tokens.some((t) => names.includes(t));
+}
+function write(io, text) {
+    io.output.write(text);
+}
+async function meterOrPrint(io) {
+    const { recordUse, limitMessage } = await import("./usage.js");
+    const r = await recordUse();
+    if (!r.allowed) {
+        write(io, limitMessage() + "\n");
+        return undefined;
+    }
+    return r;
+}
+const HELP = [
+    "  Commands:",
+    "    scan [--json]                 full scan",
+    "    fix [--apply] [--yes] [--no-llm] [--json]   fix findings",
+    "    explain [--json]               AI explanations for critical/high findings",
+    "    ai-audit | protect | attack-map | score | deps | ready   [--json]",
+    "    init [--force]                 wire up the pre-commit guard + CI",
+    "    config show | set-key <groq|anthropic> | unset-key <groq|anthropic>",
+    "    db update | status             manage the local OSV database",
+    "    cd <path>                      change the scan target",
+    "    pwd                            show the current scan target",
+    "    help                           this message",
+    "    exit | quit                    leave the session",
+].join("\n");
+/** Public entry point: real stdio, refuses to start without a TTY. */
+export async function runRepl(initialPath) {
+    if (!isInteractive()) {
+        process.stderr.write("  repl needs an interactive terminal.\n");
+        process.exitCode = 64;
+        return;
+    }
+    await runReplSession(initialPath, { input: process.stdin, output: process.stdout });
+}
+/** The actual session loop, over injectable streams — testable without a TTY. */
+export async function runReplSession(initialPath, io) {
+    const { applyStoredKeysToEnv } = await import("./config.js");
+    await applyStoredKeysToEnv();
+    const state = { root: path.resolve(initialPath) };
+    const { renderBanner } = await import("./ui/banner.js");
+    write(io, renderBanner({ subtitle: "interactive session — type `help`" }) + "\n\n");
+    write(io, `  target: ${state.root}\n\n`);
+    while (true) {
+        const raw = await askLine(`securevibe (${path.basename(state.root)})> `, io.input, io.output);
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const tokens = tokenize(line);
+        const cmd = tokens[0];
+        const rest = tokens.slice(1);
+        try {
+            if (cmd === "exit" || cmd === "quit" || cmd === "q")
+                break;
+            if (cmd === "help" || cmd === "?") {
+                write(io, HELP + "\n\n");
+                continue;
+            }
+            if (cmd === "pwd") {
+                write(io, `  ${state.root}\n\n`);
+                continue;
+            }
+            if (cmd === "cd") {
+                if (!rest[0]) {
+                    write(io, "  usage: cd <path>\n\n");
+                    continue;
+                }
+                state.root = path.resolve(state.root, rest[0]);
+                write(io, `  target: ${state.root}\n\n`);
+                continue;
+            }
+            await dispatch(cmd, rest, state, io);
+        }
+        catch (err) {
+            write(io, `  error: ${err?.message ?? err}\n\n`);
+        }
+    }
+}
+async function dispatch(cmd, tokens, state, io) {
+    const asJson = hasFlag(tokens, "--json");
+    if (["scan", "ai-audit", "protect", "attack-map", "score", "deps", "ready"].includes(cmd)) {
+        const { scan } = await import("./engine/scan.js");
+        const usage = await meterOrPrint(io);
+        const result = await scan(state.root, {
+            aiOnly: cmd === "ai-audit",
+            onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`),
+        });
+        state.lastResult = result;
+        if (asJson) {
+            const { toJson } = await import("./ui/emit.js");
+            write(io, toJson(result) + "\n\n");
+            return;
+        }
+        write(io, (await renderFor(cmd, result, usage)) + "\n");
+        return;
+    }
+    if (cmd === "fix") {
+        const { runFix } = await import("./engine/fix/session.js");
+        const { renderFixSession, fixToJson, renderApprovalRequest } = await import("./ui/fix.js");
+        const opts = { apply: hasFlag(tokens, "--apply"), yes: hasFlag(tokens, "--yes"), json: asJson };
+        const decision = decideApply(opts, true);
+        if (decision.apply && !hasFlag(tokens, "--no-llm")) {
+            const { maybeOfferAiFixerSetup } = await import("./index-support.js");
+            await maybeOfferAiFixerSetup();
+        }
+        const usage = await meterOrPrint(io);
+        const result = await runFix(state.root, {
+            apply: decision.apply,
+            noLlm: hasFlag(tokens, "--no-llm"),
+            confirm: decision.prompt ? makeFixConfirm(renderApprovalRequest, io.input, io.output) : undefined,
+            onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`),
+        });
+        if (asJson) {
+            write(io, fixToJson(result) + "\n\n");
+            return;
+        }
+        write(io, renderFixSession(result, usage) + "\n");
+        if (decision.notice) {
+            write(io, "  Not applied: re-run with `fix --apply --yes` to apply non-interactively.\n\n");
+        }
+        return;
+    }
+    if (cmd === "explain") {
+        if (!asJson) {
+            const { maybeOfferAiFixerSetup } = await import("./index-support.js");
+            await maybeOfferAiFixerSetup();
+        }
+        const { explainFindings } = await import("./engine/explain.js");
+        const usage = await meterOrPrint(io);
+        const { scan } = await import("./engine/scan.js");
+        const scanResult = await scan(state.root, { onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`) });
+        state.lastResult = scanResult;
+        const report = await explainFindings(scanResult, {
+            onProgress: asJson ? undefined : (m) => write(io, `  · ${m}\n`),
+        });
+        if (asJson) {
+            const { explainToJson } = await import("./ui/explain.js");
+            write(io, explainToJson(report) + "\n\n");
+            return;
+        }
+        const { renderExplain } = await import("./ui/explain.js");
+        write(io, renderExplain(report, usage) + "\n");
+        return;
+    }
+    if (cmd === "init") {
+        const { runInit } = await import("./engine/init.js");
+        const { renderInit } = await import("./ui/init.js");
+        const result = await runInit(state.root, { force: hasFlag(tokens, "--force") });
+        write(io, renderInit(result) + "\n");
+        const { maybeOfferAiFixerSetupDuringInit } = await import("./index-support.js");
+        await maybeOfferAiFixerSetupDuringInit(state.root);
+        return;
+    }
+    if (cmd === "config") {
+        await handleConfig(tokens, io);
+        return;
+    }
+    if (cmd === "db") {
+        await handleDb(tokens, io);
+        return;
+    }
+    write(io, `  unknown command: ${cmd} (type \`help\`)\n\n`);
+}
+async function renderFor(cmd, result, usage) {
+    if (cmd === "scan" || cmd === "ai-audit") {
+        const { renderReport } = await import("./ui/report.js");
+        return renderReport(result, { aiFocus: cmd === "ai-audit", usage });
+    }
+    if (cmd === "protect") {
+        const { renderRemediations } = await import("./ui/protect.js");
+        return renderRemediations(result, usage);
+    }
+    if (cmd === "attack-map") {
+        const { renderAttackMap } = await import("./ui/attackmap.js");
+        return renderAttackMap(result, usage);
+    }
+    if (cmd === "score") {
+        const { renderScoreOnly } = await import("./ui/protect.js");
+        return renderScoreOnly(result, usage);
+    }
+    if (cmd === "deps") {
+        const { renderDeps } = await import("./ui/deps.js");
+        return renderDeps(result, usage);
+    }
+    const { renderScorecard } = await import("./ui/readiness.js");
+    return renderScorecard(result, usage);
+}
+async function handleConfig(tokens, io) {
+    const [action, provider] = tokens;
+    const { readConfig, setKey, unsetKey, maskKey, configFilePath, ENV_VAR } = await import("./config.js");
+    if (action === "show" || !action) {
+        const cfg = await readConfig();
+        const line = (label, stored, envSet) => `  ${label}:`.padEnd(13) + (stored ? maskKey(stored) : "not set") + (envSet ? "  (env var active)" : "");
+        write(io, "  SecureVibe AI-fixer keys\n");
+        write(io, `  file: ${configFilePath()}\n`);
+        write(io, line("groq", cfg.groqApiKey, !!process.env.GROQ_API_KEY) + "\n");
+        write(io, line("anthropic", cfg.anthropicApiKey, !!process.env.ANTHROPIC_API_KEY) + "\n\n");
+        return;
+    }
+    if ((action === "set-key" || action === "unset-key") && provider !== "groq" && provider !== "anthropic") {
+        write(io, `  usage: config ${action} <groq|anthropic>\n\n`);
+        return;
+    }
+    if (action === "set-key") {
+        const hint = provider === "groq" ? " (free — console.groq.com/keys)" : " (console.anthropic.com)";
+        const key = (await askLine(`  Paste your ${provider} API key${hint}: `, io.input, io.output)).trim();
+        if (!key) {
+            write(io, "  No key entered — nothing saved.\n\n");
+            return;
+        }
+        await setKey(provider, key);
+        process.env[ENV_VAR[provider]] = key;
+        write(io, `  Saved to ${configFilePath()}. This session will use it.\n\n`);
+        return;
+    }
+    if (action === "unset-key") {
+        await unsetKey(provider);
+        write(io, `  Removed the stored ${provider} key.\n\n`);
+        return;
+    }
+    write(io, "  usage: config show | set-key <groq|anthropic> | unset-key <groq|anthropic>\n\n");
+}
+async function handleDb(tokens, io) {
+    const [action] = tokens;
+    if (action === "status") {
+        const { loadDepDb, userDbDir } = await import("./engine/deps/db.js");
+        const db = await loadDepDb();
+        const ecos = Object.entries(db.ecosystems)
+            .map(([e, pkgs]) => `${e}: ${Object.keys(pkgs).length} packages`)
+            .join(", ");
+        write(io, `  SecureVibe OSV database\n  date:   ${db.date ?? "(bundled seed only)"}\n  cache:  ${userDbDir()}\n  loaded: ${ecos || "(empty)"}\n\n`);
+        return;
+    }
+    if (action === "update") {
+        const { updateDb } = await import("./engine/deps/osv.js");
+        write(io, "  · fetching OSV dumps (npm, PyPI)…\n");
+        try {
+            const r = await updateDb();
+            write(io, `  Updated local OSV db (${r.date}): ${r.count} packages → ${r.destDir}\n\n`);
+        }
+        catch (err) {
+            write(io, `  db update failed: ${err?.message ?? err}\n\n`);
+        }
+        return;
+    }
+    write(io, "  usage: db update | status\n\n");
+}

package/dist/ui/explain.js

@@ -0,0 +1,72 @@
+/**
+ * `explain` view. Shows the AI-generated explanation per finding when
+ * available, falling back to the existing static why/fix text otherwise —
+ * an AI explanation is additional context, never a replacement, so the
+ * static text stays a guaranteed field in both the human and JSON output.
+ */
+import pc from "picocolors";
+import { renderBanner } from "./banner.js";
+import { renderUsageLine } from "./usage.js";
+const SEV_TAG = {
+    critical: (s) => pc.bgRed(pc.white(pc.bold(s))),
+    high: (s) => pc.red(pc.bold(s)),
+    medium: (s) => pc.yellow(s),
+    low: (s) => pc.blue(s),
+    info: (s) => pc.dim(s),
+};
+export function renderExplain(report, usage) {
+    const L = [];
+    L.push(renderBanner({ subtitle: "AI-powered finding explanations" }));
+    L.push(pc.dim(`  ${report.root}`));
+    L.push("");
+    if (usage) {
+        L.push(renderUsageLine(usage));
+        L.push("");
+    }
+    if (report.results.length === 0) {
+        L.push(pc.green("  No critical/high findings to explain."));
+        L.push("");
+        return L.join("\n");
+    }
+    for (const r of report.results) {
+        const f = r.finding;
+        const sev = SEV_TAG[f.severity](` ${f.severity.toUpperCase()} `);
+        L.push(`  ${sev} ${pc.bold(f.title)} ${pc.dim(`(${f.file}:${f.line})`)}`);
+        if (r.explanation) {
+            L.push(`    ${pc.cyan("AI:")} ${r.explanation.trim()}`);
+        }
+        else {
+            L.push(`    ${pc.dim("why:")} ${f.why}`);
+            L.push(`    ${pc.dim("fix:")} ${f.fix}`);
+        }
+        L.push("");
+    }
+    if (report.truncatedCount > 0) {
+        const total = report.results.length + report.truncatedCount;
+        L.push(pc.dim(`  Showing the top ${report.results.length} of ${total} critical/high findings — re-run \`scan\` to see the rest.`));
+        L.push("");
+    }
+    if (!report.llmAvailable) {
+        L.push(pc.dim("  Set GROQ_API_KEY (free tier) or ANTHROPIC_API_KEY for AI-generated explanations — showing static guidance above. Run `securevibe config set-key groq`."));
+        L.push("");
+    }
+    return L.join("\n");
+}
+export function explainToJson(report) {
+    return JSON.stringify({
+        root: report.root,
+        llmAvailable: report.llmAvailable,
+        truncatedCount: report.truncatedCount,
+        results: report.results.map((r) => ({
+            id: r.finding.id,
+            detector: r.finding.detector,
+            severity: r.finding.severity,
+            file: r.finding.file,
+            line: r.finding.line,
+            title: r.finding.title,
+            why: r.finding.why,
+            fix: r.finding.fix,
+            explanation: r.explanation,
+        })),
+    }, null, 2);
+}

package/dist/version.js

@@ -2,4 +2,4 @@
 // Single source of truth for the CLI's own version, so it can't drift from
 // what commander reports and what the update-check compares against.
 // Kept in sync with the "version" field in package.json by hand at release time.
-export const VERSION = "0.1.7";
+export const VERSION = "0.1.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securevibe",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Autonomous AI security engineer for AI generated apps: scan, fix, verify, and gate every commit before you launch",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",