@review-my-code/rmcode 0.1.1 → 0.1.3

package/dist/cli.js

@@ -2,17 +2,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 const readline_1 = require("readline");
 const API_URL = process.env.RMC_API_URL || "https://review-my-code.com";
 const APP_URL = process.env.RMC_APP_URL || "https://review-my-code.com";
-const VERSION = "0.1.1";
+const VERSION = "0.1.3";
 const FREE_PLAN_CREDITS_PER_MONTH = 30;
 const REQUEST_TIMEOUT_MS = 290_000;
 const POLL_TIMEOUT_MS = 10 * 60_000;
-const POLL_INTERVAL_MS = 2_000;
+// Backed-off polling keeps long reviews well under the backend's per-IP
+// rate limit (100 requests / 15 min).
+const POLL_INITIAL_INTERVAL_MS = 3_000;
+const POLL_MAX_INTERVAL_MS = 15_000;
+const POLL_BACKOFF_FACTOR = 1.5;
 const MAX_UNTRACKED_FILE_BYTES = 512 * 1024;
+const EXTRACTOR_TIMEOUT_MS = 120_000;
+const EXTRACTOR_DOWNLOAD_TIMEOUT_MS = 60_000;
+const EXTRACTOR_INFO_TIMEOUT_MS = 15_000;
+// Mirrors the GitHub App workflow template's "Install extractor runtime
+// dependencies" step and REPOMAP_MAX_CHARS env.
+const EXTRACTOR_RUNTIME_DEPS = [
+    "web-tree-sitter@0.20.8",
+    "tree-sitter-wasms@0.1.13",
+];
+const EXTRACTOR_REPOMAP_MAX_CHARS = "80000";
 // ── Colors (no dependencies) ──────────────────────────────────────────
 const c = {
     reset: "\x1b[0m",
@@ -35,6 +51,19 @@ function style(text, ...codes) {
         return text;
     return codes.join("") + text + c.reset;
 }
+// ── Owl header ────────────────────────────────────────────────────────
+//
+// Brand header shown once at the start of review runs (stderr, so piped
+// stdout stays parseable) and in --help. Hidden in --json mode, non-TTY,
+// NO_COLOR, and CI via the noColor/isCI guards.
+function owlHeader() {
+    const owl = (part) => style(part, c.dim, c.gray);
+    return [
+        `   ${owl("{o,o}")}`,
+        `   ${owl("/)__)")}   ${style("rmcode", c.bold, c.white)} ${style(`v${VERSION} — AI code review`, c.dim)}`,
+        `    ${owl('" "')}   ${style("─────────────────────────────────", c.dim)}`,
+    ].join("\n");
+}
 // ── Severity styling ──────────────────────────────────────────────────
 function severityBadge(severity) {
     const s = severity.toLowerCase();
@@ -53,6 +82,13 @@ function git(args) {
         maxBuffer: 10 * 1024 * 1024,
     }).trim();
 }
+function gitQuiet(args) {
+    return (0, child_process_1.execFileSync)("git", args, {
+        encoding: "utf-8",
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
 function isGitRepo() {
     try {
         git(["rev-parse", "--is-inside-work-tree"]);
@@ -90,25 +126,33 @@ function mergeBase() {
     }
     throw new Error("Could not determine a base branch. Set an upstream branch, or run rmcode --staged, rmcode --all, or pipe an explicit git diff.");
 }
+function headCommit() {
+    try {
+        return git(["rev-parse", "--verify", "HEAD"]);
+    }
+    catch {
+        return undefined;
+    }
+}
 function diffFromMergeBase() {
     const base = mergeBase();
     const diff = git(["diff", `${base}...HEAD`]);
     const files = git(["diff", `${base}...HEAD`, "--name-only"])
         .split("\n")
         .filter(Boolean);
-    return { diff, files };
+    return { diff, files, baseRef: base };
 }
 function diffStaged() {
     const diff = git(["diff", "--cached"]);
     const files = git(["diff", "--cached", "--name-only"])
         .split("\n")
         .filter(Boolean);
-    return { diff, files };
+    return { diff, files, baseRef: headCommit() };
 }
 function diffUnstaged() {
     const diff = git(["diff"]);
     const files = git(["diff", "--name-only"]).split("\n").filter(Boolean);
-    return { diff, files };
+    return { diff, files, baseRef: headCommit() };
 }
 function diffAll() {
     const root = gitWorktreeRoot();
@@ -124,7 +168,7 @@ function diffAll() {
         .filter(Boolean);
     const diff = [trackedDiff, ...untrackedDiffs].filter(Boolean).join("\n\n");
     const files = [...trackedFiles, ...untrackedFiles];
-    return { diff, files };
+    return { diff, files, baseRef: headCommit() };
 }
 function pseudoDiffForNewFile(file, worktreeRoot) {
     try {
@@ -236,22 +280,50 @@ async function fetchReviewJson(url, init) {
         clearTimeout(timeout);
     }
 }
-async function callAuthenticatedAPI(code, language, type, files) {
+async function callAuthenticatedAPI(code, language, type, files, bundle, progress) {
     const repo = gitRepoName();
-    const { status, body } = await fetchReviewJson(`${API_URL}/api/reviews/cli`, {
+    const payload = {
+        type,
+        value: code,
+        language,
+        files,
+        repo,
+    };
+    if (bundle)
+        payload.bundle = bundle;
+    let { status, body } = await fetchReviewJson(`${API_URL}/api/reviews/cli`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "X-API-Key": API_KEY,
         },
-        body: JSON.stringify({ type, value: code, language, files, repo }),
+        body: JSON.stringify(payload),
     });
+    // If the API rejects the attached context bundle (too large or invalid),
+    // degrade to the legacy diff-only request instead of failing the review.
+    if (bundle && (status === 413 || status === 400)) {
+        const notice = style("  Repository context was rejected by the API — reviewing without it.", c.dim);
+        if (progress)
+            progress.note(notice);
+        else
+            console.error(notice);
+        delete payload.bundle;
+        ({ status, body } = await fetchReviewJson(`${API_URL}/api/reviews/cli`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": API_KEY,
+            },
+            body: JSON.stringify(payload),
+        }));
+    }
     if (status === 202 && body.data?.accessToken) {
-        return pollForResults(`${API_URL}/api/reviews/cli/${body.data.accessToken}`, body.meta, { "X-API-Key": API_KEY });
+        progress?.update("Reviewing (queued)");
+        return pollForResults(`${API_URL}/api/reviews/cli/${body.data.accessToken}`, body.meta, { "X-API-Key": API_KEY }, progress);
     }
     return body;
 }
-async function callAnonymousAPI(code, language, type, files) {
+async function callAnonymousAPI(code, language, type, files, progress) {
     const repo = gitRepoName();
     const { status, body } = await fetchReviewJson(`${API_URL}/api/reviews/anonymous`, {
         method: "POST",
@@ -259,15 +331,23 @@ async function callAnonymousAPI(code, language, type, files) {
         body: JSON.stringify({ type, value: code, language, files, repo }),
     });
     if (status === 202 && body.data?.accessToken) {
-        return pollForResults(`${API_URL}/api/reviews/anonymous/${body.data.accessToken}`, body.meta);
+        progress?.update("Reviewing (queued)");
+        return pollForResults(`${API_URL}/api/reviews/anonymous/${body.data.accessToken}`, body.meta, undefined, progress);
     }
     return body;
 }
-async function pollForResults(url, initialMeta, headers) {
+async function pollForResults(url, initialMeta, headers, progress) {
     const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let interval = POLL_INITIAL_INTERVAL_MS;
+    let reviewing = false;
     while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        await new Promise((r) => setTimeout(r, interval));
+        interval = Math.min(interval * POLL_BACKOFF_FACTOR, POLL_MAX_INTERVAL_MS);
         const { status, body } = await fetchReviewJson(url, { headers });
+        if (status === 429 || body.error?.includes("Too many requests")) {
+            // Rate limiting is transient — retry at the backed-off interval.
+            continue;
+        }
         if (status >= 400 || body.success === false) {
             if (initialMeta && !body.meta)
                 body.meta = initialMeta;
@@ -278,12 +358,19 @@ async function pollForResults(url, initialMeta, headers) {
                 body.meta = initialMeta;
             return body;
         }
+        // The poll body carries no real queue state ("pending" covers both
+        // queued and running), so flip to the active phase once the first
+        // poll answers — unless the API explicitly reports "queued".
+        if (progress && !reviewing && body.data?.status !== "queued") {
+            reviewing = true;
+            progress.update("Reviewing");
+        }
     }
     return { success: false, error: "Review timed out after 10 minutes." };
 }
-function callAPI(code, language, type = "snippet", files = []) {
+function callAPI(code, language, type = "snippet", files = [], bundle, progress) {
     if (API_KEY)
-        return callAuthenticatedAPI(code, language, type, files);
+        return callAuthenticatedAPI(code, language, type, files, bundle, progress);
     return Promise.resolve({
         success: false,
         error: "API key required. Run `rmcode login`, then set RMC_API_KEY before sending code for review.",
@@ -295,6 +382,186 @@ function callAPI(code, language, type = "snippet", files = []) {
         },
     });
 }
+class ExtractorIntegrityError extends Error {
+}
+function sha256Hex(data) {
+    return (0, crypto_1.createHash)("sha256").update(data).digest("hex");
+}
+async function fetchExtractorInfo() {
+    try {
+        const resp = await fetch(`${API_URL}/api/reviews/cli/extractor`, {
+            headers: { "X-API-Key": API_KEY },
+            signal: AbortSignal.timeout(EXTRACTOR_INFO_TIMEOUT_MS),
+        });
+        if (!resp.ok)
+            return null;
+        const body = (await resp.json());
+        const data = body.data;
+        if (!data?.version || !data.sha256 || !data.url)
+            return null;
+        return {
+            version: data.version,
+            sha256: data.sha256.toLowerCase(),
+            url: data.url,
+            tier: data.tier,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Download (or reuse a cached copy of) the pinned extractor and install its
+ * runtime dependencies next to it, mirroring the GitHub App workflow.
+ * Throws ExtractorIntegrityError on checksum mismatch — never run an
+ * artifact that fails verification.
+ */
+async function ensureExtractor(info) {
+    const cacheDir = (0, path_1.join)((0, os_1.tmpdir)(), "rmcode-extractor", info.version);
+    (0, fs_1.mkdirSync)(cacheDir, { recursive: true });
+    const extractorPath = (0, path_1.join)(cacheDir, "extractor.mjs");
+    let verified = false;
+    if ((0, fs_1.existsSync)(extractorPath)) {
+        verified = sha256Hex((0, fs_1.readFileSync)(extractorPath)) === info.sha256;
+    }
+    if (!verified) {
+        const resp = await fetch(info.url, {
+            signal: AbortSignal.timeout(EXTRACTOR_DOWNLOAD_TIMEOUT_MS),
+        });
+        if (!resp.ok) {
+            throw new Error(`Extractor download failed (${resp.status}).`);
+        }
+        const data = Buffer.from(await resp.arrayBuffer());
+        if (sha256Hex(data) !== info.sha256) {
+            throw new ExtractorIntegrityError(`Extractor checksum mismatch for ${info.url} — refusing to run it. Expected sha256 ${info.sha256}.`);
+        }
+        (0, fs_1.writeFileSync)(extractorPath, data);
+    }
+    if (!(0, fs_1.existsSync)((0, path_1.join)(cacheDir, "node_modules", "web-tree-sitter"))) {
+        const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+        const init = (0, child_process_1.spawnSync)(npm, ["init", "-y"], {
+            cwd: cacheDir,
+            stdio: "ignore",
+            timeout: 30_000,
+        });
+        if (init.status !== 0) {
+            throw new Error("Could not initialize extractor dependency directory.");
+        }
+        const install = (0, child_process_1.spawnSync)(npm, [
+            "install",
+            "--no-save",
+            "--legacy-peer-deps",
+            "--no-audit",
+            "--no-fund",
+            ...EXTRACTOR_RUNTIME_DEPS,
+        ], { cwd: cacheDir, stdio: "ignore", timeout: EXTRACTOR_TIMEOUT_MS });
+        if (install.status !== 0) {
+            throw new Error("Could not install extractor runtime dependencies.");
+        }
+    }
+    return extractorPath;
+}
+/**
+ * Run the pinned extractor against a temporary detached worktree at the
+ * diff's base state and return the ContextBundle, or null when extraction
+ * is unavailable. Throws ExtractorIntegrityError on checksum mismatch.
+ */
+async function extractContextBundle(diff, baseRef) {
+    const info = await fetchExtractorInfo();
+    if (!info)
+        return null;
+    const extractorPath = await ensureExtractor(info);
+    const runDir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "rmcode-run-"));
+    const diffPath = (0, path_1.join)(runDir, "pr.diff");
+    const bundlePath = (0, path_1.join)(runDir, "bundle.json");
+    const baseDir = (0, path_1.join)(runDir, "base");
+    let worktreeAdded = false;
+    try {
+        try {
+            gitQuiet(["worktree", "add", "--detach", baseDir, baseRef]);
+            worktreeAdded = true;
+        }
+        catch {
+            // Without a base-state worktree the extractor would see the wrong
+            // tree (e.g. uncommitted or post-PR files), so degrade to diff-only
+            // instead of extracting from the live checkout.
+            return null;
+        }
+        (0, fs_1.writeFileSync)(diffPath, diff);
+        const result = (0, child_process_1.spawnSync)(process.execPath, [
+            extractorPath,
+            "--pr=0",
+            `--diff-file=${diffPath}`,
+            `--output-bundle=${bundlePath}`,
+            `--source-repo=${process.env.RMC_SOURCE_REPO || gitRepoName() || "local/repo"}`,
+            `--tier=${info.tier || "free"}`,
+        ], {
+            cwd: baseDir,
+            stdio: "ignore",
+            timeout: EXTRACTOR_TIMEOUT_MS,
+            env: {
+                ...process.env,
+                REPOMAP_MAX_CHARS: EXTRACTOR_REPOMAP_MAX_CHARS,
+                RMCODE_EXTRACTOR_VERSION: info.version,
+                RMCODE_EXTRACTOR_SHA256: info.sha256,
+            },
+        });
+        if (result.status !== 0 || !(0, fs_1.existsSync)(bundlePath))
+            return null;
+        const bundle = JSON.parse((0, fs_1.readFileSync)(bundlePath, "utf-8"));
+        if (typeof bundle.diff !== "string" ||
+            typeof bundle.repomapContext !== "string" ||
+            typeof bundle.enrichedContext !== "string" ||
+            !Array.isArray(bundle.changedFiles)) {
+            return null;
+        }
+        return bundle;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (worktreeAdded) {
+            try {
+                gitQuiet(["worktree", "remove", "--force", baseDir]);
+            }
+            catch {
+                (0, fs_1.rmSync)(baseDir, { recursive: true, force: true });
+                try {
+                    gitQuiet(["worktree", "prune"]);
+                }
+                catch {
+                    // Stale worktree metadata only; git prunes it on its own later.
+                }
+            }
+        }
+        (0, fs_1.rmSync)(runDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Best-effort context extraction for git-based diff reviews. Returns null
+ * (after printing a one-line notice) when the review must run diff-only.
+ * Reports progress on the shared review spinner so the run renders as one
+ * phase-aware line. Exits the process on extractor checksum mismatch.
+ */
+async function maybeExtractContext(diff, spinner, baseRef) {
+    if (!API_KEY || !baseRef || !isGitRepo())
+        return null;
+    try {
+        const bundle = await extractContextBundle(diff, baseRef);
+        if (bundle)
+            return bundle;
+    }
+    catch (err) {
+        if (err instanceof ExtractorIntegrityError) {
+            spinner.stop("Context extraction aborted");
+            console.error(style(`  ${err.message}`, c.red));
+            process.exit(1);
+        }
+    }
+    spinner.note(style("  Running review without repository context.", c.dim));
+    return null;
+}
 // ── Language detection ────────────────────────────────────────────────
 const EXT_TO_LANG = {
     ".ts": "typescript",
@@ -339,9 +606,54 @@ function detectLanguage(files) {
     return "javascript";
 }
 // ── Output formatting ─────────────────────────────────────────────────
-function printFindings(findings) {
+function severityRank(severity) {
+    const s = severity.toLowerCase();
+    if (s === "critical" || s === "security")
+        return 0;
+    if (s === "bug" || s === "high")
+        return 1;
+    if (s === "perf" || s === "medium")
+        return 2;
+    return 3;
+}
+function wrapText(text, width) {
+    const lines = [];
+    for (const paragraph of text.split("\n")) {
+        if (!paragraph.trim()) {
+            lines.push("");
+            continue;
+        }
+        let line = "";
+        for (const word of paragraph.split(/\s+/)) {
+            if (!line)
+                line = word;
+            else if (line.length + 1 + word.length <= width)
+                line += ` ${word}`;
+            else {
+                lines.push(line);
+                line = word;
+            }
+        }
+        if (line)
+            lines.push(line);
+    }
+    return lines;
+}
+function verdictFooter(findingCount, startedAt) {
+    const rule = noColor ? "--" : style("──", c.dim);
+    const mark = findingCount > 0 ? style("✗", c.red, c.bold) : style("✓", c.green, c.bold);
+    const verdict = findingCount > 0
+        ? `changes requested · ${findingCount} finding${findingCount !== 1 ? "s" : ""}`
+        : "approved · no blocking findings";
+    const elapsed = startedAt != null
+        ? ` · ${formatElapsed(Date.now() - startedAt, true)}`
+        : "";
+    return `  ${rule} ${mark} ${verdict}${elapsed} ${rule}`;
+}
+function printFindings(findings, startedAt) {
     if (findings.length === 0) {
         console.log(`\n  ${style("No issues found.", c.green, c.bold)} Your code looks good.\n`);
+        console.log(`${verdictFooter(0, startedAt)}\n`);
         return;
     }
     const counts = {};
@@ -351,20 +663,43 @@ function printFindings(findings) {
         .map(([k, v]) => `${v} ${k}`)
         .join(" · ");
     console.log(`\n  ${style(`${findings.length} finding${findings.length !== 1 ? "s" : ""}`, c.bold, c.white)} · ${summary}\n`);
-    for (const f of findings) {
+    const sorted = [...findings].sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+    const numWidth = String(sorted.length).length;
+    // Each body line is indented by "  " + number column + " " + gutter bar
+    // + " " = numWidth + 5 chars. Clamp to a sane floor so narrow terminals
+    // never produce a negative width for wrap/repeat.
+    const wrapWidth = Math.max(20, Math.min(process.stdout.columns || 80, 100) - (numWidth + 5));
+    const pad = " ".repeat(numWidth);
+    const bar = noColor ? "|" : style("▌", c.dim);
+    const fixPad = " ".repeat("fix: ".length);
+    sorted.forEach((f, idx) => {
+        const num = String(idx + 1).padStart(numWidth);
         const location = f.filePath
             ? `${style(f.filePath, c.cyan)}${f.line ? `:${f.line}` : ""}`
             : "";
-        console.log(`  ${severityBadge(f.severity)} ${style(f.title, c.bold, c.white)}`);
+        console.log(`  ${style(num, c.bold, c.white)} ${bar} ${severityBadge(f.severity)} ${style(f.title, c.bold, c.white)}`);
         if (location)
-            console.log(`  ${style("at", c.dim)} ${location}`);
-        console.log(`  ${style(f.explanation, c.gray)}`);
-        if (f.codeContext)
-            console.log(`  ${style(f.codeContext, c.dim)}`);
-        if (f.suggestedCode)
-            console.log(`  ${style("fix:", c.green)} ${style(f.suggestedCode, c.green)}`);
-        console.log();
-    }
+            console.log(`  ${pad} ${bar} ${style("at", c.dim)} ${location}`);
+        for (const line of wrapText(f.explanation, wrapWidth)) {
+            console.log(`  ${pad} ${bar} ${style(line, c.gray)}`);
+        }
+        if (f.codeContext) {
+            for (const line of f.codeContext.split("\n")) {
+                console.log(`  ${pad} ${bar} ${style(line, c.dim)}`);
+            }
+        }
+        if (f.suggestedCode) {
+            const [first, ...rest] = f.suggestedCode.split("\n");
+            console.log(`  ${pad} ${bar} ${style("fix:", c.green)} ${style(first, c.green)}`);
+            for (const line of rest) {
+                console.log(`  ${pad} ${bar} ${fixPad}${style(line, c.green)}`);
+            }
+        }
+        if (idx < sorted.length - 1) {
+            console.log(`  ${noColor ? "-".repeat(wrapWidth) : style("─".repeat(wrapWidth), c.dim)}`);
+        }
+    });
+    console.log(`\n${verdictFooter(sorted.length, startedAt)}\n`);
 }
 function printMeta(meta) {
     if (!meta)
@@ -390,35 +725,73 @@ function hasBlockingFindings(result) {
     const findings = result.data?.findings?.findings || [];
     return (findings.length > 0 || result.data?.findings?.verdict === "request_changes");
 }
-// ── Spinner ───────────────────────────────────────────────────────────
+function formatElapsed(ms, compact = false) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = String(totalSeconds % 60).padStart(2, "0");
+    if (compact)
+        return minutes > 0 ? `${minutes}m${seconds}s` : `${totalSeconds % 60}s`;
+    return `${minutes}m ${seconds}s`;
+}
 function createSpinner(msg) {
     if (noColor || isCI) {
+        // Plain fallback: print each phase transition once, no timer spam.
+        let lastMsg = msg;
         process.stderr.write(`  ${msg}...\n`);
         return {
-            stop: (final) => {
+            update(nextMsg) {
+                if (nextMsg === lastMsg)
+                    return;
+                lastMsg = nextMsg;
+                process.stderr.write(`  ${nextMsg}...\n`);
+            },
+            note(line) {
+                process.stderr.write(`${line}\n`);
+            },
+            stop(final) {
                 if (final)
                     process.stderr.write(`  ${final}\n`);
             },
         };
     }
     const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    const startedAt = Date.now();
+    let currentMsg = msg;
     let i = 0;
     const interval = setInterval(() => {
-        process.stderr.write(`\r  ${style(frames[i++ % frames.length], c.green)} ${msg}`);
+        process.stderr.write(`\r  ${style(frames[i++ % frames.length], c.green)} ${currentMsg}… ${style(formatElapsed(Date.now() - startedAt), c.dim)}\x1b[K`);
     }, 80);
     return {
+        update(nextMsg) {
+            currentMsg = nextMsg;
+        },
+        note(line) {
+            process.stderr.write(`\r\x1b[K${line}\n`);
+        },
         stop(finalMsg) {
             clearInterval(interval);
-            process.stderr.write(`\r  ${style("✓", c.green)} ${finalMsg || msg}${"".padEnd(20)}\n`);
+            process.stderr.write(`\r  ${style("✓", c.green)} ${finalMsg || currentMsg}\x1b[K\n`);
         },
     };
 }
 // ── Review runner ─────────────────────────────────────────────────────
-async function runReview(content, files, label, jsonMode, failOnFindings, type = "diff", language) {
+async function runReview(content, files, label, jsonMode, failOnFindings, type = "diff", language, baseRef) {
+    const startedAt = Date.now();
     const lang = language || detectLanguage(files);
-    const spinner = createSpinner(`Reviewing ${label} (${files.length} file${files.length !== 1 ? "s" : ""}, ${lang})`);
+    const uploadMsg = `Uploading review request (${files.length} file${files.length !== 1 ? "s" : ""}, ${lang})`;
+    // Reach parity with the GitHub App path: run the pinned extractor against
+    // the diff's base state so the review sees the same repository context.
+    // One spinner carries the whole run through its phases. The guard here
+    // mirrors maybeExtractContext's own early return.
+    const willExtract = type === "diff" && Boolean(API_KEY) && Boolean(baseRef) && isGitRepo();
+    const spinner = createSpinner(willExtract ? "Extracting repository context" : uploadMsg);
+    const bundle = willExtract
+        ? await maybeExtractContext(content, spinner, baseRef)
+        : null;
+    if (willExtract)
+        spinner.update(uploadMsg);
     try {
-        const result = await callAPI(content, lang, type, files);
+        const result = await callAPI(content, lang, type, files, bundle, spinner);
         spinner.stop(`Reviewed ${label}`);
         if (jsonMode) {
             printJsonResponse(result);
@@ -434,9 +807,9 @@ async function runReview(content, files, label, jsonMode, failOnFindings, type =
                 console.log(`  ${style(result.meta.message, c.yellow)}`);
             process.exit(1);
         }
-        printMeta(result.meta);
         if (result.data?.findings?.findings)
-            printFindings(result.data.findings.findings);
+            printFindings(result.data.findings.findings, startedAt);
+        printMeta(result.meta);
     }
     catch (err) {
         spinner.stop("Review failed");
@@ -446,8 +819,11 @@ async function runReview(content, files, label, jsonMode, failOnFindings, type =
 }
 // ── Help ──────────────────────────────────────────────────────────────
 function printHelp() {
+    const header = !noColor && !isCI
+        ? owlHeader()
+        : `  ${style("rmcode", c.bold, c.green)} ${style(`v${VERSION}`, c.dim)} — AI code review from your terminal`;
     console.log(`
-  ${style("rmcode", c.bold, c.green)} ${style(`v${VERSION}`, c.dim)} — AI code review from your terminal
+${header}
 
   ${style("COMMANDS", c.bold)}
 
@@ -458,6 +834,7 @@ function printHelp() {
     ${style("rmcode <file>", c.cyan)}             Review a single local file
     ${style("rmcode login", c.cyan)}              Set up your API key
     ${style("rmcode install", c.cyan)}            Install the GitHub App for automatic PR reviews
+    ${style("rmcode update", c.cyan)}             Update rmcode to the latest version
     ${style("rmcode help", c.cyan)}               Show this help
 
   ${style("OPTIONS", c.bold)}
@@ -513,18 +890,120 @@ function printHelp() {
   ${style("https://review-my-code.com", c.dim)}
 `);
 }
-// ── Version check ─────────────────────────────────────────────────────
-async function checkForUpdate() {
+// ── Self-update ───────────────────────────────────────────────────────
+const PACKAGE_NAME = "@review-my-code/rmcode";
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@review-my-code%2Frmcode/latest";
+/** Resolved real path of the running entry script, for install detection. */
+function entryScriptPath() {
+    const binPath = process.argv[1] || "";
     try {
-        const resp = await fetch("https://registry.npmjs.org/@review-my-code/rmcode/latest", {
-            signal: AbortSignal.timeout(3000),
-        });
-        if (!resp.ok)
-            return;
-        const data = (await resp.json());
-        if (data.version && data.version !== VERSION) {
-            console.log(style(`\n  Update available: ${VERSION} → ${data.version}`, c.yellow));
-            console.log(style(`  Run: npm install -g @review-my-code/rmcode\n`, c.dim));
+        return (0, fs_1.realpathSync)(binPath);
+    }
+    catch {
+        return binPath;
+    }
+}
+function isNpxInvocation(binPath) {
+    // npm's exec cache lives under .../_npx/<hash>/; older layouts use /npx/.
+    return /[\\/]_?npx[\\/]/.test(binPath);
+}
+function updateCommandFor(binPath) {
+    const ext = process.platform === "win32" ? ".cmd" : "";
+    if (/[\\/]pnpm[\\/]/.test(binPath))
+        return { cmd: `pnpm${ext}`, args: ["add", "-g", `${PACKAGE_NAME}@latest`] };
+    if (/[\\/]bun[\\/]/.test(binPath))
+        return { cmd: "bun", args: ["add", "-g", `${PACKAGE_NAME}@latest`] };
+    return {
+        cmd: `npm${ext}`,
+        args: ["install", "-g", `${PACKAGE_NAME}@latest`],
+    };
+}
+async function runUpdate() {
+    const binPath = entryScriptPath();
+    if (isNpxInvocation(binPath)) {
+        console.log(`\n  ${style("Running via npx — already using the latest published version each run.", c.dim)}\n`);
+        return;
+    }
+    const { cmd, args } = updateCommandFor(binPath);
+    console.log(`\n  ${style(`Updating ${PACKAGE_NAME} via ${cmd}...`, c.bold)}\n`);
+    const result = (0, child_process_1.spawnSync)(cmd, args, { stdio: "inherit" });
+    if (result.status === 0) {
+        const latest = await fetchLatestVersion().catch(() => null);
+        console.log(`\n  ${style("✓", c.green)} ${latest
+            ? `Updated to v${latest}.`
+            : "Updated. Run rmcode --version to confirm."}\n`);
+        return;
+    }
+    console.error(style(`\n  Update failed. Run it manually:`, c.red));
+    console.error(`  ${style([cmd, ...args].join(" "), c.cyan, c.bold)}\n`);
+    process.exit(1);
+}
+// ── Update nudge ──────────────────────────────────────────────────────
+//
+// After a successful human-mode review, print at most one dim line when a
+// newer version is published. The registry is queried at most once per
+// 24h (cached in ~/.config/rmcode/update-check.json) and only after the
+// review output has been printed. Any failure here is silently swallowed
+// — the nudge must never affect review output or exit codes.
+const UPDATE_CHECK_TIMEOUT_MS = 1_500;
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+function updateCachePath() {
+    return (0, path_1.join)((0, os_1.homedir)(), ".config", "rmcode", "update-check.json");
+}
+async function fetchLatestVersion() {
+    const resp = await fetch(REGISTRY_LATEST_URL, {
+        signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
+    });
+    if (!resp.ok)
+        return null;
+    const data = (await resp.json());
+    return typeof data.version === "string" ? data.version : null;
+}
+/** Latest published version, from the daily cache when fresh. */
+async function latestPublishedVersion() {
+    const cachePath = updateCachePath();
+    try {
+        const cached = JSON.parse((0, fs_1.readFileSync)(cachePath, "utf-8"));
+        if (typeof cached.latest === "string" &&
+            typeof cached.checkedAt === "number" &&
+            Date.now() - cached.checkedAt < UPDATE_CHECK_TTL_MS) {
+            return cached.latest;
+        }
+    }
+    catch {
+        // Missing or unreadable cache — fall through to a fresh fetch.
+    }
+    const latest = await fetchLatestVersion();
+    if (!latest)
+        return null;
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.join)((0, os_1.homedir)(), ".config", "rmcode"), { recursive: true });
+        (0, fs_1.writeFileSync)(cachePath, JSON.stringify({ latest, checkedAt: Date.now() }));
+    }
+    catch {
+        // Cache writes are best-effort.
+    }
+    return latest;
+}
+/** Hand-rolled x.y.z compare: 1 if a > b, -1 if a < b, 0 if equal. */
+function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10));
+    const pb = b.split(".").map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] || 0;
+        const db = pb[i] || 0;
+        if (da !== db)
+            return da > db ? 1 : -1;
+    }
+    return 0;
+}
+async function maybeShowUpdateNudge() {
+    if (noColor || isCI)
+        return;
+    try {
+        const latest = await latestPublishedVersion();
+        if (latest && compareVersions(latest, VERSION) > 0) {
+            console.log(style(`  Update available ${VERSION} → ${latest} · run rmcode update`, c.dim));
         }
     }
     catch {
@@ -582,6 +1061,10 @@ async function main() {
         console.error(style(`  Run: rmcode help\n`, c.dim));
         process.exit(1);
     }
+    if (positional[0] === "update") {
+        await runUpdate();
+        return;
+    }
     if (positional[0] === "install") {
         console.log(`\n  ${style("Install the GitHub App for automatic PR reviews:", c.bold)}\n`);
         console.log(`  ${style("https://github.com/apps/rmcode-ai", c.cyan, c.bold)}\n`);
@@ -617,8 +1100,10 @@ async function main() {
         console.error(style(`  Run: rmcode help\n`, c.dim));
         process.exit(1);
     }
-    if (!jsonMode) {
-        console.log(`\n  ${style("rmcode", c.green, c.bold)} ${style(`v${VERSION}`, c.dim)}`);
+    // Brand header for review runs — stderr so any stdout consumers stay
+    // safe; hidden in --json, non-TTY, NO_COLOR, and CI.
+    if (!jsonMode && !noColor && !isCI) {
+        process.stderr.write(`\n${owlHeader()}\n\n`);
     }
     // Piped stdin
     if (hasPipedStdin()) {
@@ -632,11 +1117,12 @@ async function main() {
             console.error(style("  No input received on stdin.", c.red));
             process.exit(1);
         }
-        const spinner = createSpinner(`Reviewing stdin (${lang})`);
+        const startedAt = Date.now();
+        const spinner = createSpinner(`Uploading review request (stdin, ${lang})`);
         try {
             const stdinType = looksLikeUnifiedDiff(code) ? "diff" : "snippet";
             const stdinFiles = stdinType === "diff" ? filesFromDiff(code) : [];
-            const result = await callAPI(code, lang, stdinType, stdinFiles);
+            const result = await callAPI(code, lang, stdinType, stdinFiles, null, spinner);
             spinner.stop("Reviewed stdin");
             if (jsonMode) {
                 printJsonResponse(result);
@@ -650,9 +1136,9 @@ async function main() {
                 console.error(style(`  ${result.error || "Review failed."}`, c.red));
                 process.exit(1);
             }
-            printMeta(result.meta);
             if (result.data?.findings?.findings)
-                printFindings(result.data.findings.findings);
+                printFindings(result.data.findings.findings, startedAt);
+            printMeta(result.meta);
         }
         catch (err) {
             spinner.stop("Review failed");
@@ -677,7 +1163,7 @@ async function main() {
         }
         await runReview(code, [file], file, jsonMode, failOnFindings, "file", detectLanguage([file]));
         if (!jsonMode)
-            await checkForUpdate();
+            await maybeShowUpdateNudge();
         return;
     }
     // Git modes
@@ -688,9 +1174,10 @@ async function main() {
     const branch = currentBranch();
     let diff;
     let files;
+    let baseRef;
     let label;
     if (flags.has("--staged")) {
-        ({ diff, files } = diffStaged());
+        ({ diff, files, baseRef } = diffStaged());
         label = "staged changes";
         if (!diff) {
             console.error(style("  No staged changes. Stage files with: git add <files>", c.yellow));
@@ -698,7 +1185,7 @@ async function main() {
         }
     }
     else if (flags.has("--unstaged")) {
-        ({ diff, files } = diffUnstaged());
+        ({ diff, files, baseRef } = diffUnstaged());
         label = "unstaged changes";
         if (!diff) {
             console.error(style("  No unstaged changes.", c.yellow));
@@ -706,7 +1193,7 @@ async function main() {
         }
     }
     else if (flags.has("--all")) {
-        ({ diff, files } = diffAll());
+        ({ diff, files, baseRef } = diffAll());
         label = "all uncommitted changes";
         if (!diff) {
             console.error(style("  No uncommitted changes.", c.yellow));
@@ -714,21 +1201,21 @@ async function main() {
         }
     }
     else {
-        ({ diff, files } = diffFromMergeBase());
+        ({ diff, files, baseRef } = diffFromMergeBase());
         label = `branch ${style(branch, c.cyan)} vs base`;
         if (!diff) {
             console.error(style("  No changes from merge base. Your branch matches main.", c.yellow));
             process.exit(0);
         }
     }
-    await runReview(diff, files, label, jsonMode, failOnFindings);
+    await runReview(diff, files, label, jsonMode, failOnFindings, "diff", undefined, baseRef);
     if (!jsonMode && !API_KEY) {
         console.log(style(`  Get ${FREE_PLAN_CREDITS_PER_MONTH} credits/month free: rmcode login`, c.dim));
         console.log(style("  Auto-review every PR: rmcode install", c.dim));
         console.log();
     }
     if (!jsonMode)
-        await checkForUpdate();
+        await maybeShowUpdateNudge();
 }
 main()
     .then(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@review-my-code/rmcode",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "AI code review from your terminal. Catches logic errors, null risks, security holes, and broken error handling.",
   "keywords": [
     "code-review",