prehello 0.0.0-stage → 1.0.0

package/dist/cli.js

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const diff_1 = require("./diff");
+const calibrate_1 = require("./calibrate");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const scan_1 = require("./scan");
+const model_1 = require("./model");
+const terminal_1 = require("./render/terminal");
+const fix_1 = require("./render/fix");
+const json_1 = require("./render/json");
+const card_1 = require("./render/card");
+const png_1 = require("./render/png");
+const markdown_1 = require("./render/markdown");
+const sarif_1 = require("./render/sarif");
+const platform_1 = require("./platform");
+const fmt_1 = require("./util/fmt");
+const fs_safe_1 = require("./fs-safe");
+const safe_write_1 = require("./safe-write");
+const spec_1 = require("./spec");
+const HELP = `prehello ${scan_1.VERSION} — what your coding agent loads before you say hello.
+Local-only, read-only scan. No network, no telemetry, no API key. Token counts are ESTIMATES.
+
+Usage:
+  prehello [path] [options]
+  prehello explain grade        print the Context Grade rubric
+  prehello calibrate [path] --file <ctx.txt|->
+                                compare prehello with Claude Code's /context output
+                                (--json for JSON, --save <file> writes a redacted record)
+  prehello diff <base.json> <head.json> [--markdown[=file]] [--json] [--fail-above <n>]
+                                token change between two snapshots (exit 2 over the limit)
+
+Options:
+  --agent <list>        comma list of agents to force "in use":
+                        ${model_1.ALL_AGENTS.join(", ")}
+  --window <n|200k|1m>  context window for percentages (default 200k)
+  --json                print the report as JSON to stdout (versioned schema)
+  --json=<file>         also write the JSON to <file>
+  --save <file>         save a snapshot (the JSON report) for prehello diff
+  --badge <file>        write a shields.io endpoint badge JSON (see docs/github-action.md)
+  --redact              strict JSON: no paths or names (share-safe)
+  --card[=<file>]       write a share card (no paths or file contents). The file extension picks the format:
+                        .svg (default name prehello-card.svg) or .png (prehello-card.png)
+                        name the file with "=" or a space: --card=card.png or --card card.png
+  --markdown[=<file>]   a shareable Markdown report (title, headline, tables, what to cut, measured vs not measured) for a
+                        GitHub issue / PR / README / Slack. Without a file it is printed to stdout INSTEAD of the terminal
+                        report (pipe it: prehello --markdown | pbcopy); with a file (.md or .markdown) it is written there
+                        and the terminal report is still printed. No paths, file contents or finding texts, ever.
+  --markdown-compact    the short version for a PR comment: headline, one line per agent, the first things to cut
+                        (implies --markdown; combine with --markdown=<file> to save it)
+  --sarif[=<file>]      SARIF 2.1.0 for GitHub code scanning / IDEs (rules PH001-PH011: large always-on files, heavy plugins and MCP servers,
+                        over --max-tokens, unmeasured items, duplicates, over-long / truncated / ignored files, possible secrets).
+                        Without a file it is printed to stdout INSTEAD of the terminal report; with a file (.sarif or .sarif.json)
+                        it is written there and the terminal report is still printed. File locations only for files inside the
+                        scanned folder (relative to %SRCROOT%: run it from the repository root); never home or user-config paths.
+  --card-anonymize      show plugin and MCP server names on the card and in the Markdown report as "plugin 1" / "MCP server 1"
+                        (implied by --redact; --anonymize is the same flag). In SARIF, --redact also drops every file location.
+  --card-format svg|png format when --card has no file name (default svg); must match the extension if both are given
+  --card-theme dark|light     --card-size og|square     --card-agent <id>
+  --card-scale 1|2      PNG only: 1 = 1200x630 (square 1080x1080), 2 = double that, sharper (default 2)
+  --card-headline cut|total   (card and Markdown report) lead with "skills/plugins cost ~X before hello; cutting the top N saves ~Y"
+                        (default; falls back to the total when there is no meaningful saving) or always with
+                        the always-on total
+  --force               let --json=<file> / --card=<file> / --markdown=<file> replace an existing file that prehello did not write.
+                        Symlinks are never written through, with or without --force.
+  --max-tokens <n|16k>  CI gate: exit 2 if the always-on token count (a lower bound when anything is
+                        unmeasured) of any agent in use is above n. Compares the central estimate.
+  --fix                 print a dry-run fix plan (changes nothing)
+  --tokenizer auto|heuristic  --claude-profile current|legacy
+  --no-bundled-catalog  ignore the measured MCP weights that ship with prehello
+  --mcp-catalog <file>  extra pre-measured MCP weights (see spec/mcp-weights.json)
+  --paste-user-rules <file|->  count text you pasted for rules that live inside an app
+                        (Cursor "User Rules"). Read-only; the text is counted, never printed.
+  --scan-budget-mb <n>  stop reading after n MiB in total (default 64); the report is then marked PARTIAL
+  --scan-budget-ms <n>  stop walking/reading after n ms (default 20000); a safety net, so it is the one
+                        limit that can vary run to run on a slow disk
+  --include-fixtures    also look inside test-fixture folders (fixtures, __fixtures__, fixture, testdata, test-data, __mocks__,
+                        __snapshots__, and snapshots/golden under test/spec/e2e folders) for nested AGENTS.md, CLAUDE.md,
+                        .cursor/rules and skills. By default they are skipped (no agent loads them) and the report says how many.
+                        Scanning a folder that is itself inside a fixtures folder never skips anything.
+  --cwd <dir>           simulate launching the agent from <dir>
+  --ascii               plain ASCII output (no block characters or arrows); automatic in terminals that cannot draw them
+                        (Linux console, classic Windows console). PREHELLO_ASCII=1 does the same.
+  --no-grade  --no-color  --quiet  --verbose  --about-specs  --version  --help
+
+Output files (--json=<file>, --card=<file>, --markdown=<file>, --sarif=<file>): a symlink is never followed; an existing file is only replaced
+if it is a previous prehello output (or with --force).
+
+Scan budget: at most ~64 MiB read and ~20 s of walking per run, then the scan stops, warns, and every total is a
+lower bound. Files over 4 MiB are skipped (Claude Code skips them at startup too).
+
+PNG cards need the optional package @resvg/resvg-wasm. If it is not installed, prehello prints how to install it, writes no card,
+exits 1, and everything else you asked for (report, --json, --markdown) is still produced. An SVG card never needs it.
+
+Windows: the home folder is %USERPROFILE%; use --markdown=<file> or --json=<file> rather than shell redirection (Windows PowerShell 5
+re-encodes redirected output as UTF-16). Works the same on Linux, macOS and Windows.
+
+Exit codes: 0 ok · 1 error (incl. PNG engine missing) · 2 --max-tokens exceeded · 3 partial (some sources unreadable/skipped/budget hit; report still printed)
+  (2 wins over 3 when both apply)
+`;
+const VALUE_FLAGS = new Set(["agent", "window", "tokenizer", "claude-profile", "card-theme", "card-size", "card-agent", "cwd", "mcp-catalog", "ceiling", "managed-dir", "system-root", "paste-user-rules", "card-headline", "card-format", "card-scale", "png-engine", "max-tokens", "scan-budget-mb", "scan-budget-ms", "file", "context-file", "save", "fail-above", "badge"]);
+const BOOL_FLAGS = new Set(["json", "card", "redact", "fix", "no-grade", "no-color", "quiet", "verbose", "about-specs", "version", "help", "no-redact", "no-bundled-catalog", "force", "card-anonymize", "anonymize", "markdown", "markdown-compact", "sarif", "ascii", "include-fixtures"]);
+function parseArgs(argv) {
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a === "-h") {
+            flags.set("help", true);
+            continue;
+        }
+        if (a === "-v" || a === "-V") {
+            flags.set("version", true);
+            continue;
+        }
+        if (a.length > 1 && a.startsWith("-") && !a.startsWith("--"))
+            return `unknown option ${a} (try --help)`;
+        if (!a.startsWith("--")) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+        const inline = eq === -1 ? undefined : a.slice(eq + 1);
+        if (VALUE_FLAGS.has(name)) {
+            const v = inline ?? argv[++i];
+            if (v === undefined || (inline === undefined && v.startsWith("--")))
+                return `option --${name} needs a value`;
+            if (v === "" && name !== "paste-user-rules")
+                return `option --${name} needs a value`;
+            flags.set(name, v);
+        }
+        else if (BOOL_FLAGS.has(name)) {
+            if (inline !== undefined && name !== "json" && name !== "card" && name !== "markdown" && name !== "sarif")
+                return `option --${name} does not take a value`;
+            if (inline === "" && name === "json")
+                return "--json= needs a file name (for stdout, write --json with no =)";
+            // --card card.png: take the next argument as the file name when it ends in .svg/.png and is not an existing directory
+            if (name === "card" && inline === undefined && i + 1 < argv.length && /\.(svg|png)$/i.test(argv[i + 1]) && !argv[i + 1].startsWith("-") && !(0, fs_safe_1.isDir)(node_path_1.default.resolve(argv[i + 1]))) {
+                flags.set(name, argv[++i]);
+                continue;
+            }
+            flags.set(name, inline ?? true);
+        }
+        else
+            return `unknown option --${name} (try --help)`;
+    }
+    return { flags, positional };
+}
+function fail(msg) {
+    process.stderr.write(`prehello: ${msg}\n`);
+    process.exit(1);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const parsed = parseArgs(argv);
+    if (typeof parsed === "string")
+        return fail(parsed);
+    const { flags, positional } = parsed;
+    if (flags.has("help"))
+        return void process.stdout.write(HELP);
+    if (flags.has("version"))
+        return void process.stdout.write(scan_1.VERSION + "\n");
+    if (flags.has("about-specs")) {
+        for (const id of model_1.ALL_AGENTS) {
+            const s = (0, spec_1.loadSpec)(id);
+            process.stdout.write(`${model_1.AGENT_NAMES[id]}: verifiedAt ${s.verifiedAt}\n  ${s.verifiedNote}\n  docs: ${Object.values(s.docs).join(" ")}\n`);
+        }
+        return;
+    }
+    if (positional[0] === "explain") {
+        if (positional[1] === "grade")
+            return void process.stdout.write((0, terminal_1.renderRubric)());
+        return fail("usage: prehello explain grade");
+    }
+    const calibrating = positional[0] === "calibrate";
+    if (calibrating)
+        positional.shift();
+    let contextText;
+    if (calibrating) {
+        const dash = positional.indexOf("-");
+        if (dash >= 0)
+            positional.splice(dash, 1);
+        const src = (flags.get("file") ?? flags.get("context-file") ?? (dash >= 0 ? "-" : undefined));
+        if (src === undefined || src === "-") {
+            if (src === undefined && process.stdin.isTTY)
+                return fail("usage: prehello calibrate --file ctx.txt (paste the output of /context from Claude Code into ctx.txt), or pipe it: pbpaste | prehello calibrate -");
+            contextText = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(0));
+        }
+        else {
+            try {
+                contextText = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(src));
+            }
+            catch {
+                return fail(`cannot read /context text from ${src}`);
+            }
+        }
+    }
+    else if (flags.has("file") || flags.has("context-file"))
+        return fail("--file and --context-file belong to 'prehello calibrate'");
+    if (positional[0] === "diff")
+        return runDiff(positional.slice(1), flags);
+    if (flags.has("fail-above"))
+        return fail("--fail-above belongs to 'prehello diff'");
+    if (positional[0] === "ci")
+        return fail("there is no 'ci' command: use the GitHub Action (docs/github-action.md), or prehello --save + prehello diff");
+    if (positional.length > 1)
+        return fail("at most one path argument is supported");
+    const env = process.env;
+    const target = flags.get("cwd") ?? positional[0] ?? process.cwd();
+    const cwdAbs = node_path_1.default.resolve(target);
+    if (!(0, fs_safe_1.isDir)(cwdAbs)) {
+        if (flags.get("card") === true && positional[0] && /\.(svg|png)$/i.test(positional[0]))
+            return fail(`not a directory: ${target}. To name the card file write --card=${positional[0]}`);
+        return fail(`not a directory: ${target}`);
+    }
+    const cwd = (0, fs_safe_1.realpathOrSelf)(cwdAbs);
+    // Windows: %USERPROFILE% (what the agents use), not HOME (Git Bash sets a POSIX-style "/c/Users/me" Node cannot open).
+    const home = (0, fs_safe_1.realpathOrSelf)((0, platform_1.resolveHomeDir)(env, process.platform, node_os_1.default.homedir));
+    let window = 200_000;
+    if (flags.has("window")) {
+        const w = (0, fmt_1.parseWindow)(String(flags.get("window")));
+        if (!w)
+            return fail("--window must look like 200k, 1m or 128000");
+        window = w;
+    }
+    const tokenizer = String(flags.get("tokenizer") ?? "auto");
+    if (tokenizer === "exact")
+        return fail("--tokenizer exact (network) is not part of 0.1; this build never makes network calls");
+    if (tokenizer !== "auto" && tokenizer !== "heuristic")
+        return fail("--tokenizer must be auto or heuristic");
+    const cp = String(flags.get("claude-profile") ?? "current");
+    if (cp !== "current" && cp !== "legacy")
+        return fail("--claude-profile must be current or legacy");
+    let agents;
+    if (flags.has("agent")) {
+        const list = String(flags.get("agent")).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+        if (!list.length)
+            return fail("--agent needs at least one of: " + model_1.ALL_AGENTS.join(", "));
+        const bad = list.filter((x) => !model_1.ALL_AGENTS.includes(x));
+        if (bad.length)
+            return fail(`unknown agent '${bad[0]}' (supported: ${model_1.ALL_AGENTS.join(", ")})`);
+        agents = list;
+    }
+    if (calibrating) {
+        if (agents && (agents.length !== 1 || agents[0] !== "claude-code"))
+            return fail("calibrate reads Claude Code's /context; Codex and Cursor have no per-category reading to compare against (yet)");
+        agents = ["claude-code"];
+    }
+    const cardTheme = String(flags.get("card-theme") ?? "dark");
+    const cardSize = String(flags.get("card-size") ?? "og");
+    if (!["dark", "light"].includes(cardTheme))
+        return fail("--card-theme must be dark or light");
+    if (!["og", "square"].includes(cardSize))
+        return fail("--card-size must be og or square");
+    const cardHeadline = String(flags.get("card-headline") ?? "cut");
+    if (!["total", "cut"].includes(cardHeadline))
+        return fail("--card-headline must be total or cut");
+    const cardScaleRaw = String(flags.get("card-scale") ?? "2");
+    if (!["1", "2"].includes(cardScaleRaw))
+        return fail("--card-scale must be 1 or 2");
+    const cardScale = Number(cardScaleRaw);
+    const fmtFlag = flags.has("card-format") ? String(flags.get("card-format")).toLowerCase() : undefined;
+    if (fmtFlag !== undefined && !["svg", "png"].includes(fmtFlag))
+        return fail("--card-format must be svg or png");
+    if (flags.has("png-engine") && flags.get("png-engine") !== "none")
+        return fail("--png-engine only accepts 'none' (test hook)");
+    let cardFile = "";
+    let cardFormat = "svg";
+    if (flags.get("card") !== undefined) {
+        const cf = flags.get("card");
+        if (typeof cf === "string") {
+            const ext = /\.(svg|png)$/i.exec(cf)?.[1].toLowerCase();
+            if (!ext)
+                return fail("--card file name must end in .svg or .png");
+            if (fmtFlag && fmtFlag !== ext)
+                return fail(`--card-format ${fmtFlag} does not match the file name ${cf}`);
+            cardFile = cf;
+            cardFormat = ext;
+        }
+        else {
+            cardFormat = fmtFlag ?? "svg";
+            cardFile = `prehello-card.${cardFormat}`;
+        }
+    }
+    else if (fmtFlag)
+        return fail("--card-format needs --card");
+    const mdFlag = flags.get("markdown");
+    const mdCompact = flags.has("markdown-compact");
+    let mdFile = "";
+    if (typeof mdFlag === "string") {
+        if (!/\.(md|markdown)$/i.test(mdFlag))
+            return fail("--markdown file name must end in .md or .markdown (for stdout, write --markdown with no file name)");
+        mdFile = mdFlag;
+    }
+    const mdStdout = mdFile === "" && (mdFlag !== undefined || mdCompact);
+    const sarifFlag = flags.get("sarif");
+    let sarifFile = "";
+    if (typeof sarifFlag === "string") {
+        if (!/\.sarif(\.json)?$/i.test(sarifFlag))
+            return fail("--sarif file name must end in .sarif or .sarif.json (for stdout, write --sarif with no file name)");
+        sarifFile = sarifFlag;
+    }
+    const sarifStdout = sarifFlag === true;
+    if (mdStdout && flags.get("json") === true)
+        return fail("--json and --markdown both want standard output; give one of them a file: --markdown=report.md or --json=report.json");
+    if (mdStdout && flags.has("fix"))
+        return fail("--fix and --markdown both want standard output; give the Markdown report a file: --markdown=report.md");
+    if (sarifStdout && flags.get("json") === true)
+        return fail("--json and --sarif both want standard output; give one of them a file: --sarif=report.sarif or --json=report.json");
+    if (sarifStdout && mdStdout)
+        return fail("--markdown and --sarif both want standard output; give one of them a file: --sarif=report.sarif or --markdown=report.md");
+    if (sarifStdout && flags.has("fix"))
+        return fail("--fix and --sarif both want standard output; give the SARIF report a file: --sarif=report.sarif");
+    let maxTokens;
+    if (flags.has("max-tokens")) {
+        const m = /^(\d+(?:\.\d+)?)\s*([km]?)$/i.exec(String(flags.get("max-tokens")).trim());
+        if (!m)
+            return fail("--max-tokens must look like 16000 or 16k");
+        maxTokens = Math.round(parseFloat(m[1]) * (m[2].toLowerCase() === "k" ? 1000 : m[2].toLowerCase() === "m" ? 1_000_000 : 1));
+    }
+    const force = flags.has("force");
+    const posNum = (name) => {
+        if (!flags.has(name))
+            return undefined;
+        const raw = String(flags.get(name));
+        const n = Number(raw);
+        return /^\d+(\.\d+)?$/.test(raw) && n > 0 ? n : `--${name} must be a positive number`;
+    };
+    const budgetMb = posNum("scan-budget-mb");
+    const budgetMs = posNum("scan-budget-ms");
+    if (typeof budgetMb === "string")
+        return fail(budgetMb);
+    if (typeof budgetMs === "string")
+        return fail(budgetMs);
+    let pastedUserRules;
+    if (flags.has("paste-user-rules")) {
+        const src = String(flags.get("paste-user-rules"));
+        try {
+            if (src === "-") {
+                if (process.stdin.isTTY)
+                    return fail("--paste-user-rules - reads standard input; pipe the text in (e.g. pbpaste | prehello --paste-user-rules -) or pass a file");
+                pastedUserRules = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(0)).replace(/\r\n/g, "\n");
+            }
+            else {
+                const st = node_fs_1.default.statSync(src);
+                if (!st.isFile())
+                    return fail(`--paste-user-rules: not a file: ${src}`);
+                if (st.size > 1024 * 1024)
+                    return fail("--paste-user-rules: file is larger than 1 MB");
+                pastedUserRules = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(src)).replace(/\r\n/g, "\n");
+            }
+        }
+        catch (e) {
+            return fail(`--paste-user-rules: could not read ${src === "-" ? "standard input" : src} (${e.code ?? "error"})`);
+        }
+        if (pastedUserRules.length > 1024 * 1024)
+            return fail("--paste-user-rules: text is larger than 1 MB");
+        if (!pastedUserRules.trim())
+            return fail("--paste-user-rules: the text is empty");
+    }
+    const report = (0, scan_1.scan)({
+        cwd,
+        home,
+        env,
+        platform: process.platform,
+        ceiling: flags.has("ceiling") ? (0, fs_safe_1.realpathOrSelf)(String(flags.get("ceiling"))) : undefined,
+        managedDir: flags.has("managed-dir") ? String(flags.get("managed-dir")) : undefined,
+        noBundledCatalog: flags.has("no-bundled-catalog"),
+        systemRoot: flags.has("system-root") ? node_path_1.default.resolve(String(flags.get("system-root"))) : undefined,
+        pastedUserRules,
+        window,
+        tokenizer,
+        claudeProfile: cp,
+        includeFixtures: flags.has("include-fixtures"),
+        agents,
+        catalogPath: flags.has("mcp-catalog") ? node_path_1.default.resolve(String(flags.get("mcp-catalog"))) : undefined,
+        now: new Date(),
+        maxScanBytes: budgetMb === undefined ? undefined : Math.round(budgetMb * 1048576),
+        maxScanMs: budgetMs,
+        noGrade: flags.has("no-grade"),
+    });
+    const protectedPaths = new Set(report.agents.flatMap((a) => a.items.map((i) => (0, fs_safe_1.realpathOrSelf)(i.path))));
+    const write = (file, content, what, kind) => {
+        const abs = node_path_1.default.resolve(file);
+        if (protectedPaths.has((0, fs_safe_1.realpathOrSelf)(abs)))
+            return fail(`refusing to overwrite a scanned context file with ${what}: ${file}`);
+        try {
+            (0, safe_write_1.safeWrite)(abs, content, { kind, force });
+        }
+        catch (e) {
+            if (e instanceof safe_write_1.SafeWriteError)
+                return fail(`${what} not written to ${file}: ${e.message}`);
+            return fail(`could not write ${what} to ${file}: ${(0, safe_write_1.describeWriteError)(e.code)}`);
+        }
+    };
+    if (calibrating) {
+        let reading;
+        try {
+            reading = (0, calibrate_1.parseContext)(contextText ?? "");
+        }
+        catch (e) {
+            if (e instanceof calibrate_1.ContextParseError)
+                return fail(e.message);
+            throw e;
+        }
+        const a = report.agents.find((x) => x.id === "claude-code");
+        if (!a)
+            return fail("no Claude Code report to compare against");
+        const cal = (0, calibrate_1.compare)(reading, a, home);
+        if (flags.has("save"))
+            write(String(flags.get("save")), JSON.stringify((0, calibrate_1.calibrationJson)(cal, report, a, true), null, 2) + "\n", "calibration", "json");
+        if (process.exitCode)
+            return;
+        if (flags.get("json") === true)
+            process.stdout.write(JSON.stringify((0, calibrate_1.calibrationJson)(cal, report, a, flags.has("redact")), null, 2) + "\n");
+        else
+            process.stdout.write((0, calibrate_1.renderCalibration)(cal, report));
+        if (flags.has("save"))
+            process.stderr.write(`Calibration written to ${flags.get("save")} (no paths or names).\n`);
+        return;
+    }
+    const strict = flags.has("redact");
+    const jsonFlag = flags.get("json");
+    const color = !flags.has("no-color") && !env.NO_COLOR && env.TERM !== "dumb" && !!process.stdout.isTTY;
+    const asciiOut = flags.has("ascii") || env.PREHELLO_ASCII === "1" || (!!process.stdout.isTTY && !(0, platform_1.unicodeSupported)(env, process.platform));
+    const term = (t) => (asciiOut ? (0, platform_1.toAscii)(t) : t);
+    const width = Math.min(process.stdout.columns || 80, 100);
+    const jsonText = jsonFlag !== undefined ? JSON.stringify((0, json_1.toJson)(report, { cwd, home }, strict), null, 2) + "\n" : "";
+    if (typeof jsonFlag === "string")
+        write(jsonFlag, jsonText, "JSON", "json");
+    if (flags.has("save"))
+        write(String(flags.get("save")), JSON.stringify((0, json_1.toJson)(report, { cwd, home }, strict), null, 2) + "\n", "snapshot", "json");
+    if (flags.has("badge")) {
+        // a CI runner has no agent installed: fall back to the agent with the most always-on context in the repository
+        const ba = (0, card_1.pickCardAgent)(report, flags.get("card-agent")) ?? [...report.agents].filter((a) => a.items.length).sort((x, y) => y.totals.always.est - x.totals.always.est)[0] ?? null;
+        write(String(flags.get("badge")), JSON.stringify(ba ? (0, diff_1.badgeJson)(ba.name, ba.totals.always.measuredItems || !ba.totals.always.unmeasuredItems ? ba.totals.always.est : null, ba.lowerBound) : (0, diff_1.badgeJson)("no agent", null, false)) + "\n", "badge", "badge");
+    }
+    let cardMsg = "";
+    let cardFailed = false;
+    const anonymizeNames = flags.has("card-anonymize") || flags.has("anonymize") || strict;
+    let mdText = "";
+    let mdMsg = "";
+    let sarifOut = "";
+    if (mdFlag !== undefined || mdCompact) {
+        mdText = (0, markdown_1.renderMarkdown)(report, { anonymize: anonymizeNames, compact: mdCompact, headline: cardHeadline });
+        if (mdFile) {
+            write(mdFile, `${safe_write_1.MD_MARKER_PREFIX}${scan_1.VERSION} -->\n${mdText}`, "Markdown report", "md");
+            mdMsg = `Markdown report written to ${mdFile} (no paths, file contents or finding texts; ${anonymizeNames ? "plugin and MCP server names anonymised" : "plugin and MCP server names are shown, add --card-anonymize to hide them"}).\n`;
+        }
+    }
+    if (cardFile) {
+        const agent = (0, card_1.pickCardAgent)(report, flags.has("card-agent") ? String(flags.get("card-agent")) : undefined);
+        if (!agent)
+            cardMsg = "No card written: nothing measurable (or unmeasured) loads before hello for the selected agent(s).\n";
+        else {
+            const base = { theme: cardTheme, size: cardSize, headline: cardHeadline, anonymize: anonymizeNames };
+            if (cardFormat === "svg")
+                write(cardFile, (0, card_1.renderCard)(report, agent, base), "card", "svg");
+            else {
+                try {
+                    const png = await (0, png_1.svgToPng)((0, card_1.renderCard)(report, agent, { ...base, fontFamily: png_1.PNG_FONT_FAMILY, charEm: png_1.PNG_CHAR_EM }), {
+                        scale: cardScale,
+                        version: scan_1.VERSION,
+                        resolver: flags.get("png-engine") === "none" ? () => { throw new Error("disabled"); } : undefined,
+                    });
+                    write(cardFile, png, "card", "png");
+                }
+                catch (e) {
+                    if (!(e instanceof png_1.PngUnavailableError))
+                        throw e;
+                    cardFailed = true;
+                    cardMsg = `prehello: ${e.message}\n`;
+                }
+            }
+            if (!cardFailed)
+                cardMsg = `Card written to ${cardFile} (${agent.name}; no paths or file contents; ${anonymizeNames ? "plugin and MCP server names anonymised" : "plugin and MCP server names are shown, add --card-anonymize to hide them"}).\n`;
+        }
+    }
+    let sarifMsg = "";
+    if (sarifFlag !== undefined) {
+        const sarifText = (0, sarif_1.renderSarif)(report, { anonymize: anonymizeNames, strict, maxTokens, cwd, home });
+        if (sarifFile) {
+            write(sarifFile, sarifText, "SARIF report", "sarif");
+            sarifMsg = `SARIF report written to ${sarifFile} (no file contents or finding texts; file locations only for files inside the scanned folder${strict ? ", none with --redact" : ""}).\n`;
+        }
+        else
+            sarifOut = sarifText;
+    }
+    const docOnStdout = jsonFlag === true || mdStdout || sarifStdout;
+    if (jsonFlag === true)
+        process.stdout.write(jsonText);
+    else if (sarifStdout)
+        process.stdout.write(sarifOut);
+    else if (mdStdout)
+        process.stdout.write(mdText);
+    else if (flags.has("fix"))
+        process.stdout.write(term((0, fix_1.renderFix)(report)));
+    else
+        process.stdout.write(term((0, terminal_1.renderTerminal)(report, { color, width, verbose: flags.has("verbose"), quiet: flags.has("quiet"), home, cwd })));
+    if (cardMsg)
+        (docOnStdout || cardFailed ? process.stderr : process.stdout).write(term(cardMsg));
+    if (mdMsg)
+        (docOnStdout ? process.stderr : process.stdout).write(term(mdMsg));
+    if (sarifMsg)
+        (docOnStdout ? process.stderr : process.stdout).write(term(sarifMsg));
+    process.exitCode = cardFailed ? 1 : report.warnings.length ? 3 : 0;
+    if (maxTokens !== undefined) {
+        const over = report.agents.filter((a) => !a.presentInRepoOnly && a.totals.always.est > maxTokens);
+        for (const a of over) {
+            const lb = a.lowerBound ? "at least " : "";
+            process.stderr.write(`prehello: ${a.name} always-on context is ${lb}~${(0, fmt_1.fmtTok)(a.totals.always.est)} tokens (estimate), above --max-tokens ${maxTokens}\n`);
+        }
+        if (over.length)
+            process.exitCode = 2;
+    }
+}
+// `prehello --markdown | head` closes the pipe early: that is not an error.
+process.stdout.on("error", (e) => {
+    if (e.code === "EPIPE")
+        process.exit(process.exitCode ?? 0);
+    throw e;
+});
+main().catch((e) => {
+    process.stderr.write(`prehello: internal error: ${e.message}\n`);
+    process.exitCode = 1;
+});
+function parseTokenCount(v) {
+    const m = /^(\d+(?:\.\d+)?)([kKmM]?)$/.exec(v.trim());
+    if (!m)
+        return undefined;
+    return Math.round(parseFloat(m[1]) * (m[2].toLowerCase() === "k" ? 1000 : m[2].toLowerCase() === "m" ? 1_000_000 : 1));
+}
+/** `prehello diff base.json head.json [--markdown[=file]] [--json] [--fail-above N]`. Reads two saved reports; no scan, no git. */
+function runDiff(files, flags) {
+    if (files.length !== 2)
+        return fail("usage: prehello diff <base.json> <head.json> [--markdown] [--json] [--fail-above <tokens>]  (make each file with: prehello --save <file>)");
+    let threshold;
+    if (flags.has("fail-above")) {
+        threshold = parseTokenCount(String(flags.get("fail-above")));
+        if (threshold === undefined)
+            return fail("--fail-above needs a token count, e.g. 2000 or 2k");
+    }
+    const snaps = [];
+    for (const f of files) {
+        let text;
+        try {
+            text = node_fs_1.default.readFileSync(f === "-" ? 0 : f, "utf8");
+        }
+        catch {
+            return fail(`cannot read ${f}`);
+        }
+        try {
+            snaps.push((0, diff_1.parseSnapshot)(text, f));
+        }
+        catch (e) {
+            if (e instanceof diff_1.DiffInputError)
+                return fail(e.message);
+            throw e;
+        }
+    }
+    const d = (0, diff_1.diffSnapshots)(snaps[0], snaps[1]);
+    const md = flags.get("markdown");
+    if (typeof md === "string") {
+        try {
+            (0, safe_write_1.safeWrite)(node_path_1.default.resolve(md), (0, diff_1.renderDiffMarkdown)(d, { threshold }), { kind: "md", force: flags.has("force") });
+        }
+        catch (e) {
+            return fail(`diff Markdown not written to ${md}: ${e.message}`);
+        }
+    }
+    if (flags.get("json") === true)
+        process.stdout.write(JSON.stringify((0, diff_1.diffJson)(d, threshold), null, 2) + "\n");
+    else if (md === true)
+        process.stdout.write((0, diff_1.renderDiffMarkdown)(d, { threshold }));
+    else
+        process.stdout.write((0, diff_1.renderDiffTerminal)(d));
+    const over = threshold !== undefined ? (0, diff_1.overThreshold)(d, threshold) : [];
+    for (const a of over)
+        process.stderr.write(`prehello: ${a.name} always-on context grew by ${(0, fmt_1.fmtTok)(a.delta)} tokens (estimate), above --fail-above ${(0, fmt_1.fmtTok)(threshold)}\n`);
+    process.exitCode = over.length ? 2 : 0;
+}