securevibe 0.1.10 → 0.1.13

package/README.md

@@ -28,8 +28,9 @@ midnight). The `--staged` commit guard is never limited. See [`LICENSE`](LICENSE
 | `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) |
@@ -40,11 +41,26 @@ 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.
+
+Inside the REPL, anything you type that is not a command is a question for the AI about
+your last scan: "why is finding 3 critical?", "which of these should I fix first?".
+Answers are grounded in the scan results only; the assistant never sees your files and
+never claims your code is secure. The first question each session asks before anything
+is sent to your provider. Needs the same key as `fix` and `explain`
+(`securevibe config set-key groq`).
+
 ## Always-on (doc 12)
 
 `securevibe init` makes the tool continuous so insecure code can't slip through:
@@ -53,11 +69,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)
 
@@ -121,8 +142,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/chat.js

@@ -0,0 +1,76 @@
+import { SEVERITY_ORDER } from "./types.js";
+import { llmChatMessages } from "./fix/llm.js";
+/** Findings included in the grounding table, top N by severity then confidence. */
+export const CHAT_MAX_FINDINGS = 30;
+/** Prior exchanges (user + assistant pairs) kept and re-sent per question. */
+export const CHAT_MAX_EXCHANGES = 10;
+const CHAT_SYSTEM = [
+    "You are the assistant inside SecureVibe, a security scanner CLI. The user just scanned their repository; the scan results are below. Answer their questions about those results.",
+    "Rules you must never break:",
+    "- Answer ONLY from the scan results provided. You cannot see the repository's files, only the findings listed. If asked about anything not in them, say you can only see the scan results.",
+    "- Never call the code \"secure\", \"safe\", or \"unhackable\". A clean scan means our detectors found nothing, not that the code is secure.",
+    "- When you give remediation advice, end with: review the diff and run your tests.",
+    "- The user can run these commands: scan, fix (--apply), explain, ai-audit, protect, attack-map, score, deps, ready. Recommend those when relevant. You cannot fix, read files, or run anything yourself; never claim otherwise.",
+    "- Findings are numbered; \"finding 3\" means number 3 in the list below.",
+    "- Keep answers short and concrete: plain prose, no markdown headings, no bullet spam.",
+].join("\n");
+/** The compact, numbered findings table the assistant is grounded in. */
+export function buildGrounding(result) {
+    const sorted = [...result.findings].sort((a, b) => SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity] || b.confidence - a.confidence);
+    const shown = sorted.slice(0, CHAT_MAX_FINDINGS);
+    const lines = [
+        `Target: ${result.root}`,
+        `Score: grade ${result.score.grade} (composite ${result.score.composite}), readiness: ${result.score.readiness}`,
+    ];
+    if (result.launchReadiness) {
+        lines.push(`Launch verdict: ${result.launchReadiness.verdict} (${result.launchReadiness.blockers} blockers, ${result.launchReadiness.warnings} warnings)`);
+    }
+    if (shown.length === 0) {
+        lines.push("Findings: none (no findings — our detectors found nothing; that does not prove the code is secure).");
+        return lines.join("\n");
+    }
+    lines.push(shown.length < sorted.length
+        ? `Findings (top ${shown.length} of ${sorted.length}, by severity):`
+        : `Findings (${shown.length}):`);
+    shown.forEach((f, i) => {
+        lines.push(`${i + 1}. [${f.severity}] ${f.detector} ${f.file}:${f.line} - ${f.title}`);
+        if (f.evidence)
+            lines.push(`   evidence: ${f.evidence.trim()}`);
+    });
+    return lines.join("\n");
+}
+export class ChatSession {
+    callLlm;
+    history = [];
+    grounding = null;
+    constructor(callLlm = llmChatMessages) {
+        this.callLlm = callLlm;
+    }
+    /** New grounding means a fresh conversation: the old answers described old results. */
+    setScanResult(result) {
+        this.grounding = buildGrounding(result);
+        this.history = [];
+    }
+    reset() {
+        this.grounding = null;
+        this.history = [];
+    }
+    /**
+     * Ask one question. Returns null (and leaves history untouched) when there
+     * is no grounding or the call fails — the caller owns the user-facing
+     * degradation message, same contract as llmChat.
+     */
+    async ask(question) {
+        if (this.grounding === null)
+            return null;
+        const messages = [...this.history, { role: "user", content: question }];
+        const answer = await this.callLlm(`${CHAT_SYSTEM}\n\nScan results:\n${this.grounding}`, messages);
+        if (answer == null)
+            return null;
+        this.history.push({ role: "user", content: question }, { role: "assistant", content: answer });
+        const max = CHAT_MAX_EXCHANGES * 2;
+        if (this.history.length > max)
+            this.history = this.history.slice(-max);
+        return answer;
+    }
+}

package/dist/engine/fix/llm.js

@@ -102,22 +102,29 @@ export async function llmFix(input) {
 /**
  * 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.
+ * finding explanations). 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) {
+    return llmChatMessages(system, [{ role: "user", content: user }]);
+}
+/**
+ * Multi turn variant: same provider selection and same null-on-failure
+ * contract as llmChat, but takes the full message history. Used by
+ * engine/chat.ts (the REPL's free text chat).
+ */
+export async function llmChatMessages(system, messages) {
     const provider = selectProvider();
     if (!provider)
         return null;
     try {
-        return provider === "groq" ? await callGroq(system, user) : await callAnthropic(system, user);
+        return provider === "groq" ? await callGroq(system, messages) : await callAnthropic(system, messages);
     }
     catch {
         return null;
     }
 }
-async function callAnthropic(system, user) {
+async function callAnthropic(system, messages) {
     let Anthropic;
     try {
         ({ default: Anthropic } = await import("@anthropic-ai/sdk"));
@@ -130,12 +137,12 @@ async function callAnthropic(system, user) {
         model: modelFor("anthropic"),
         max_tokens: 8192,
         system,
-        messages: [{ role: "user", content: user }],
+        messages,
     });
     return extractAnthropicText(msg);
 }
 /** Groq's chat-completions endpoint is OpenAI-compatible — plain fetch, no SDK. */
-async function callGroq(system, user) {
+async function callGroq(system, messages) {
     const res = await fetch("https://api.groq.com/openai/v1/chat/completions", {
         method: "POST",
         headers: {
@@ -145,10 +152,7 @@ async function callGroq(system, user) {
         body: JSON.stringify({
             model: modelFor("groq"),
             max_tokens: 8192,
-            messages: [
-                { role: "system", content: system },
-                { role: "user", content: user },
-            ],
+            messages: [{ role: "system", content: system }, ...messages],
         }),
     });
     if (!res.ok)

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,7 +2,7 @@
  * `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.
  */
@@ -72,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:
@@ -82,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
@@ -101,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);
@@ -122,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())
@@ -52,7 +65,8 @@ export async function maybeOfferAiFixerSetupDuringInit(root, deps) {
     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 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)) {

package/dist/index.js

@@ -22,16 +22,18 @@ function addCommon(cmd) {
         .option("--sarif", "output SARIF 2.1.0 (for CI / GitHub code scanning)")
         .option("--no-color", "disable coloured output")
         .option("--staged", "scan only git-staged files (for pre-commit guards)")
+        .option("--diff <base>", "scan only files changed since <base> (for PR checks)")
         .option("--ci", "CI mode: exit non-zero based on deployment readiness");
 }
 /**
  * Free beta metering: one use per analysis command against the daily quota.
- * The --staged commit guard is exempt — a quota must never block a commit.
- * Returns the usage state so callers can show it, or undefined when this run
- * wasn't metered (--staged).
+ * The --staged commit guard and --diff (PR-scoped CI scans) are both exempt —
+ * an always-on automated guard must never be the thing that breaks. Returns
+ * the usage state so callers can show it, or undefined when this run wasn't
+ * metered.
  */
 async function meter(opts = {}) {
-    if (opts.staged)
+    if (opts.staged || opts.diff)
         return undefined;
     const { recordUse, limitMessage } = await import("./usage.js");
     const r = await recordUse();
@@ -62,6 +64,20 @@ async function runScan(pathArg, opts, scanOpts = {}) {
             scanOpts = { ...scanOpts, files: staged };
         }
     }
+    // --diff <base>: analyze only files changed since <base> (PR-scoped CI checks).
+    if (opts.diff) {
+        const path = await import("node:path");
+        const { listChangedFiles } = await import("./engine/git.js");
+        const absRoot = path.resolve(target);
+        const changed = await listChangedFiles(absRoot, opts.diff);
+        if (changed === null) {
+            if (!quiet)
+                process.stderr.write(`  · could not diff against ${opts.diff} — scanning the whole tree\n`);
+        }
+        else {
+            scanOpts = { ...scanOpts, files: changed };
+        }
+    }
     const result = await scan(target, {
         ...scanOpts,
         onProgress: quiet ? undefined : (m) => process.stderr.write(`  · ${m}\n`),
@@ -201,6 +217,36 @@ program
     }
     await maybeNotifyUpdate({ json: opts.json });
 });
+program
+    .command("pr-comment")
+    .description("Post/update a PR summary of changed-file findings (used by the GitHub Actions workflow)")
+    .argument("[path]", "path to the repository", ".")
+    .option("--diff <base>", "base ref to diff against (the workflow passes the PR's base SHA)")
+    .action(async (pathArg, opts) => {
+    if (!opts.diff) {
+        process.stderr.write("  pr-comment: --diff <base> is required (the workflow passes the PR's base SHA).\n");
+        process.exit(64);
+    }
+    const { result } = await runScan(pathArg, { diff: opts.diff });
+    const { renderPrComment } = await import("./ui/prComment.js");
+    const body = renderPrComment(result);
+    const token = process.env.GITHUB_TOKEN;
+    const repoSlug = process.env.GITHUB_REPOSITORY;
+    const prNumber = process.env.PR_NUMBER ? Number(process.env.PR_NUMBER) : undefined;
+    if (!token || !repoSlug || !prNumber) {
+        process.stdout.write(body + "\n");
+        return;
+    }
+    const [owner, repo] = repoSlug.split("/");
+    const { postOrUpdateComment } = await import("./engine/github.js");
+    const posted = await postOrUpdateComment({ owner, repo, prNumber, token }, body);
+    if (!posted.posted) {
+        process.stderr.write(`  pr-comment: could not post to GitHub (${posted.error ?? "unknown error"}) — printing instead.\n`);
+        process.stdout.write(body + "\n");
+        return;
+    }
+    process.stderr.write(`  pr-comment: ${posted.updated ? "updated" : "posted"} the summary on PR #${prNumber}.\n`);
+});
 addCommon(program
     .command("ai-audit")
     .description("Focus on the AI-application / agent attack surface (doc 04)")
@@ -275,7 +321,7 @@ addCommon(program
 });
 program
     .command("db")
-    .description("Manage the local OSV vulnerability database (the only networked command)")
+    .description("Manage the local OSV vulnerability database (update is networked)")
     .argument("<action>", "update | status")
     .option("--no-color", "disable coloured output")
     .action(async (action, opts) => {