securevibe 0.1.8 → 0.1.12

package/README.md

@@ -27,8 +27,10 @@ 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 pr-comment [path]` | Post/update a PR findings summary (used by the GitHub Actions workflow) |
 | `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 db <update\|status>` | Manage the local OSV database — `update` is networked |
 | `securevibe ready [path]` | Launch readiness scorecard: pass/fail gates + go/no-go verdict |
 | `securevibe ai-audit [path]` | Focus on the AI-agent attack surface (doc 04) |
 | `securevibe protect [path]` | Remediation-first view: the fix for every finding (doc 05) |
@@ -39,11 +41,19 @@ midnight). The `--staged` commit guard is never limited. See [`LICENSE`](LICENSE
 
 Flags: `--json`, `--sarif` (GitHub code-scanning / CI interop), `--no-color`,
 `--ci` (exit `2` on BLOCK, `1` on WARN, `0` on SHIP — for build gates),
-`--staged` (scan only git-staged files — what the pre-commit guard uses).
+`--staged` (scan only git-staged files — what the pre-commit guard uses),
+`--diff <base>` (scan only files changed since `<base>` — what the PR-comment step
+uses; also exempt from the daily usage limit, same as `--staged`).
 `fix` flags: `--apply` (write to disk; asks before each change), `--yes` (apply every
 verified fix without prompting — for CI/scripts), `--no-llm` (deterministic-only), `--json`.
 `init` flags: `--force` (replace an existing hook/workflow/config).
 
+The REPL renders a bordered input box with a live status line (target + active AI-fixer
+provider). Type `/` to open a command-discovery menu, or type commands directly as
+before (`scan`, `fix --apply`, `help`, etc. — the `/` prefix is optional, not required).
+Up/down arrow cycles through your command history. `scan`/`fix`/`explain` show a single
+live progress spinner instead of scrolling status lines.
+
 ## Always-on (doc 12)
 
 `securevibe init` makes the tool continuous so insecure code can't slip through:
@@ -52,11 +62,16 @@ verified fix without prompting — for CI/scripts), `--no-llm` (deterministic-on
   a blocking issue** — including a committed secret (verified: it aborts the commit, then lets the
   clean version through);
 - a **GitHub Actions workflow** (`.github/workflows/securevibe.yml`) that scans every PR and uploads
-  SARIF to GitHub code scanning, gating the build on deployment-readiness;
+  SARIF to GitHub code scanning, gates the build on deployment-readiness, and posts a PR comment
+  summarizing findings in the *changed* files only (updated in place on new commits, not reposted —
+  and the only other command besides `db update` that talks to the network, and only to post a
+  findings summary already computed locally, never your source code);
 - gitignores `.env` / backups and drops a minimal `securevibe.config.json`.
 
-It is idempotent (existing files are left alone unless `--force`) and runs entirely locally —
-**no account, no upload, and your secrets / API keys are never stored or transmitted.**
+It is idempotent (existing files are left alone unless `--force`). Everything it installs runs
+locally — **no account, and your secrets / API keys are never stored or transmitted.** The one
+exception is the PR-comment step above, which uploads a findings summary (never your source code)
+already computed by the local scan.
 
 ## The fix loop (doc 05)
 
@@ -78,11 +93,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.
@@ -111,8 +135,9 @@ against a local copy of the [OSV](https://osv.dev) advisory database, and report
   CVE still blocks deployment, and `securevibe fix` bumps the package to the lowest non vulnerable
   version while preserving your range prefix (`^`, `~`, `==`, ...).
 - **Offline first.** A bundled seed (`data/osv-seed.json`) ships with the CLI, so `deps` works with
-  no network. `db update` is the **only networked command**: it streams the public OSV npm and PyPI
-  dumps into `~/.securevibe/db`. Nothing about your code or package list leaves the machine.
+  no network. `db update` is the only command that **downloads** anything (the public OSV npm and
+  PyPI dumps, into `~/.securevibe/db`). `pr-comment` is the only command that **uploads** anything,
+  and only a findings summary already computed locally — never your code or package list.
 - **Honest framing.** A clean result reads "no known advisories as of `<db date>`", not "secure" —
   it means nothing matched the local database on that date, which is not a proof of safety.
 

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/git.js

@@ -34,11 +34,15 @@ export function gitDir(root) {
 /**
  * Staged files (added/copied/modified) as absolute paths, filtered to those
  * that exist on disk. Returns null if not a git repo / git unavailable.
+ * `--relative` matters when `root` is a subdirectory of the repo: git diff
+ * paths are toplevel-relative by default, which would silently mis-resolve
+ * against `root` otherwise (and --relative also scopes the diff to `root`,
+ * matching "scan this path" semantics for a subdirectory target).
  */
 export async function listStagedFiles(root) {
     if (!isGitRepo(root))
         return null;
-    const out = git(root, ["diff", "--cached", "--name-only", "--diff-filter=ACM", "-z"]);
+    const out = git(root, ["diff", "--cached", "--relative", "--name-only", "--diff-filter=ACM", "-z"]);
     if (out == null)
         return null;
     const rels = out.split("\0").filter((s) => s.length > 0);
@@ -56,3 +60,32 @@ export async function listStagedFiles(root) {
     }
     return abs;
 }
+/**
+ * Files changed (added/copied/modified) between `baseRef` and the working
+ * tree, as absolute paths, filtered to those that still exist on disk. Used
+ * by `--diff` (PR-scoped scans) — same shape as listStagedFiles, but diffing
+ * against an arbitrary ref instead of the index. Returns null if not a git
+ * repo / git unavailable, or if the diff itself fails (e.g. `baseRef` doesn't
+ * exist in this checkout).
+ */
+export async function listChangedFiles(root, baseRef) {
+    if (!isGitRepo(root))
+        return null;
+    const out = git(root, ["diff", "--relative", "--name-only", "--diff-filter=ACM", "-z", baseRef]);
+    if (out == null)
+        return null;
+    const rels = out.split("\0").filter((s) => s.length > 0);
+    const abs = [];
+    for (const rel of rels) {
+        const p = path.join(root, rel);
+        try {
+            const st = await fs.stat(p);
+            if (st.isFile())
+                abs.push(p);
+        }
+        catch {
+            /* changed-but-removed or unreadable — skip */
+        }
+    }
+    return abs;
+}

package/dist/engine/github.js

@@ -0,0 +1,59 @@
+/**
+ * Minimal GitHub REST client for the pr-comment command (doc 12). Posts or
+ * updates a single PR comment, found via a hidden marker so re-runs replace
+ * it in place instead of piling up new comments. Every failure (auth,
+ * network, rate limit) is caught and returned as a result — this must never
+ * throw, since posting the comment is best-effort visibility, not a gate
+ * (the existing `scan --ci` step is what's allowed to fail the build).
+ */
+export const PR_COMMENT_MARKER = "<!-- securevibe-pr-comment -->";
+const API_BASE = "https://api.github.com";
+function authHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+}
+/** Finds an existing SecureVibe comment on the PR by its hidden marker, or null if none/on any failure. */
+async function findExistingComment(target) {
+    try {
+        const res = await fetch(`${API_BASE}/repos/${target.owner}/${target.repo}/issues/${target.prNumber}/comments?per_page=100`, { headers: authHeaders(target.token) });
+        if (!res.ok)
+            return null;
+        const comments = await res.json();
+        if (!Array.isArray(comments))
+            return null;
+        const existing = comments.find((c) => typeof c?.body === "string" && c.body.includes(PR_COMMENT_MARKER));
+        return existing?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Posts a new PR comment, or updates the existing SecureVibe comment (found
+ * via the marker) in place. Never throws — any failure comes back as
+ * `{ posted: false, error }` so the caller can warn and continue.
+ */
+export async function postOrUpdateComment(target, body) {
+    try {
+        const existingId = await findExistingComment(target);
+        const url = existingId
+            ? `${API_BASE}/repos/${target.owner}/${target.repo}/issues/comments/${existingId}`
+            : `${API_BASE}/repos/${target.owner}/${target.repo}/issues/${target.prNumber}/comments`;
+        const res = await fetch(url, {
+            method: existingId ? "PATCH" : "POST",
+            headers: authHeaders(target.token),
+            body: JSON.stringify({ body }),
+        });
+        if (!res.ok) {
+            return { posted: false, updated: false, error: `GitHub API error: ${res.status}` };
+        }
+        return { posted: true, updated: existingId !== null };
+    }
+    catch (err) {
+        return { posted: false, updated: false, error: err?.message ?? String(err) };
+    }
+}

package/dist/engine/init.js

@@ -2,13 +2,50 @@
  * `securevibe init` (doc 12) — make SecureVibe always-on in a project with one
  * command. Installs a git pre-commit guard (blocks commits that introduce a
  * BLOCK-level issue, including committed secrets), a GitHub Actions workflow
- * (PR scan + SARIF upload to code scanning), gitignores `.env` and backups, and
+ * (PR scan + SARIF upload + PR summary comment), gitignores `.env` and backups, and
  * drops a minimal config. Idempotent: existing files are left alone unless
  * `--force`. Everything runs locally — no account, no upload, no API key.
  */
 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",
@@ -35,8 +72,8 @@ if [ "$?" -eq 2 ]; then
 fi
 exit 0
 `;
-const WORKFLOW = `# SecureVibe — scan every PR and upload findings to GitHub code scanning.
-# Managed by \`securevibe init\`.
+const WORKFLOW = `# SecureVibe — scan every PR, upload findings to GitHub code scanning, and
+# post a PR summary comment. Managed by \`securevibe init\`.
 name: SecureVibe
 on:
   pull_request:
@@ -45,11 +82,14 @@ on:
 permissions:
   contents: read
   security-events: write
+  issues: write
 jobs:
   securevibe:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -64,6 +104,12 @@ jobs:
           sarif_file: securevibe.sarif
       - name: Gate the build on deployment readiness
         run: securevibe scan . --ci
+      - name: PR comment
+        if: always() && github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: \${{ github.event.pull_request.number }}
+        run: securevibe pr-comment . --diff \${{ github.event.pull_request.base.sha }}
 `;
 export async function runInit(root, opts = {}) {
     const absRoot = path.resolve(root);
@@ -85,7 +131,7 @@ export async function runInit(root, opts = {}) {
         });
     }
     // 4) GitHub Actions workflow.
-    actions.push(await writeIfAbsent(absRoot, ".github/workflows/securevibe.yml", WORKFLOW, opts.force, "PR scan + SARIF upload"));
+    actions.push(await writeIfAbsent(absRoot, ".github/workflows/securevibe.yml", WORKFLOW, opts.force, "PR scan + SARIF upload + PR summary comment"));
     return { root: absRoot, isGitRepo: repo, actions };
 }
 async function ensureGitignore(root) {

package/dist/engine/taint.js

@@ -1,6 +1,13 @@
 import { walk } from "./ast.js";
-/** Untrusted-input sources. Matching text is considered tainted at its origin. */
-const SOURCE_RE = /\b(req|request)\.(query|body|params|headers|cookies)\b|\bsearchParams\.get\b|\bnextUrl\.searchParams\b|\bparams\.[a-zA-Z_$]|\breq(uest)?\.json\(\)|\bawait\s+\w+\.json\(\)|\bprocess\.argv\b|\bflask\.request\.|\brequest\.args\b|\brequest\.form\b|\brequest\.json\b/;
+/**
+ * Untrusted-input sources. Matching text is considered tainted at its origin.
+ * `req(uest)?.json()` (with or without a preceding `await`) is intentionally
+ * scoped to those two names, not `\w+.json()` generically -- an unrestricted
+ * `\w+` also matched `await res.json()` on a response *we* fetched (e.g. an
+ * outbound GitHub API call), wrongly treating our own already-fetched data
+ * as untrusted input.
+ */
+const SOURCE_RE = /\b(req|request)\.(query|body|params|headers|cookies)\b|\bsearchParams\.get\b|\bnextUrl\.searchParams\b|\bparams\.[a-zA-Z_$]|\breq(uest)?\.json\(\)|\bprocess\.argv\b|\bflask\.request\.|\brequest\.args\b|\brequest\.form\b|\brequest\.json\b/;
 function collectAssignments(root) {
     const out = [];
     walk(root, (n) => {
@@ -32,7 +39,12 @@ function referencesTainted(text, tainted) {
     if (SOURCE_RE.test(text))
         return true;
     for (const v of tainted) {
-        // word-boundary match so `id` doesn't match `idx`
+        // word-boundary match so `id` doesn't match `idx` -- but this also can't
+        // tell a real reference to `v` from `v`'s name coincidentally appearing
+        // inside a string/template literal (e.g. a URL path segment: a tainted
+        // var named `comments` false-matched a fetch URL literally containing
+        // "/comments"). Known false-positive class, not fixed here -- narrowing
+        // SOURCE_RE only closes the one source that produced this instance.
         const re = new RegExp(`\\b${escapeRe(v)}\\b`);
         if (re.test(text))
             return true;

package/dist/index-support.js

@@ -2,6 +2,19 @@
  * 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.
  */
+/**
+ * Pure (no I/O) check: is there no AI-fixer provider key configured right
+ * now? Returns the static nudge text to print when true, undefined when a
+ * key is already set. Shared by the interactive `askLine`-based offer below
+ * and by the Ink REPL path (ui/repl-tui/App.ts), which can't safely open a
+ * second readline on process.stdin while Ink holds it in raw mode — so it
+ * prints this instead of calling maybeOfferAiFixerSetup().
+ */
+export function noKeyNudgeMessage() {
+    if (process.env.GROQ_API_KEY || process.env.ANTHROPIC_API_KEY)
+        return undefined;
+    return "  no AI-fixer key set — those findings show as manual review. Run `securevibe config set-key groq` (outside the REPL) to enable AI-powered fixes.\n\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
@@ -9,7 +22,7 @@
  * 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)
+    if (!noKeyNudgeMessage())
         return;
     const { isInteractive, askLine } = await import("./ui/prompt.js");
     if (!isInteractive())
@@ -30,3 +43,33 @@ export async function maybeOfferAiFixerSetup() {
     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;
+    const writePreamble = deps?.writePreamble ?? ((text) => process.stderr.write(text));
+    writePreamble("\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 });
+    }
+}