prehello 0.0.0-stage → 1.0.0

package/dist/render/card.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CARD_FONT = exports.THEMES = exports.AT_LEAST = exports.MIN_CUT_HEADLINE_TOKENS = exports.REPO_URL = void 0;
+exports.buildHeadline = buildHeadline;
+exports.assertHeadline = assertHeadline;
+exports.pickCardAgent = pickCardAgent;
+exports.wrapLabel = wrapLabel;
+exports.renderCard = renderCard;
+const fmt_1 = require("../util/fmt");
+const treemap_1 = require("./treemap");
+const savings_1 = require("../analyze/savings");
+const secrets_1 = require("../util/secrets");
+const agents_1 = require("../agents");
+exports.REPO_URL = "github.com/PIYUSH-KUMAR1809/prehello";
+/** A saving smaller than this (estimated tokens) is noise, not a headline. Same threshold as the cut list itself. */
+exports.MIN_CUT_HEADLINE_TOKENS = 500;
+/** Wording of the lower-bound marker. Words, not a glyph: "≥" is missing from several fallback fonts used by SVG renderers. */
+exports.AT_LEAST = "at least";
+/**
+ * Headline templates. Each one is selected by data and re-validated by assertHeadline():
+ * no claim is rendered unless it is true for the scanned data (plan §10.1 guard).
+ */
+function buildHeadline(a, window, variant = "cut") {
+    const t = a.totals.always;
+    const lower = a.lowerBound ? `${exports.AT_LEAST} ` : "";
+    // The cut headline needs measured always-on data AND a saving that is worth saying out loud; otherwise the total headline is used.
+    if (variant === "cut" && a.savings && t.measuredItems > 0 && a.savings.topTokens >= exports.MIN_CUT_HEADLINE_TOKENS) {
+        const sv = a.savings;
+        const what = sv.top.some((c) => c.kind === "mcp") ? "Skills, plugins & MCP" : "Skills & plugins";
+        return {
+            id: "cut-list",
+            hero: `${what} cost ${lower}~${(0, fmt_1.fmtTok)(sv.groupsTokens)} tokens before hello`,
+            sub: `${sv.n === sv.groupsCount ? `all ${sv.n} group${sv.n > 1 ? "s" : ""}` : `top ${sv.n} of ${sv.groupsCount} groups`}: cut ${sv.n > 1 ? "them" : "it"}, save ~${(0, fmt_1.fmtTok)(sv.topTokens)} (estimate)`,
+        };
+    }
+    if (t.measuredItems > 0 && t.est > 0) {
+        const pct = (t.est / window) * 100;
+        return {
+            id: "tokens-before-hello",
+            hero: `${lower}~${(0, fmt_1.fmtTok)(t.est)} tokens load before hello`,
+            sub: `${pct < 0.1 ? (a.lowerBound ? "under 0.1% so far" : "under 0.1%") : (a.lowerBound ? exports.AT_LEAST + " " : "about ") + (0, fmt_1.fmtPct)(pct)} of a ${(0, fmt_1.fmtWindow)(window)} window · ${a.name} · estimate`,
+        };
+    }
+    if (t.unmeasuredItems > 0) {
+        const n = t.unmeasuredItems;
+        // only claim "MCP servers" when every unmeasured always-on item really is one (an unreadable CLAUDE.md is not a server)
+        const un = a.items.filter((i) => i.loadMode === "always" && i.tokens === null);
+        const mcpOnly = un.length > 0 && un.every((i) => i.kind === "mcp-server");
+        return { id: "mcp-unmeasured", hero: mcpOnly ? `${n} MCP server${n > 1 ? "s" : ""} load before hello` : `${n} always-loaded item${n > 1 ? "s" : ""} could not be measured`, sub: `${a.name} · token cost unmeasured (not zero)` };
+    }
+    return null;
+}
+function assertHeadline(h, a, window) {
+    const t = a.totals.always;
+    if (h.id === "tokens-before-hello") {
+        if (!(t.measuredItems > 0 && t.est > 0))
+            throw new Error("headline guard: tokens claim without measured always-on data");
+        if (a.lowerBound && !h.hero.startsWith(exports.AT_LEAST))
+            throw new Error("headline guard: lower-bound marker missing");
+        if (!h.hero.includes("~"))
+            throw new Error("headline guard: estimate marker missing");
+        if (/%/.test(h.hero))
+            throw new Error("headline guard: unexpected percentage in hero");
+    }
+    else if (h.id === "cut-list") {
+        if (!a.savings || !(t.measuredItems > 0))
+            throw new Error("headline guard: cut-list claim without savings data");
+        if (a.savings.topTokens < exports.MIN_CUT_HEADLINE_TOKENS)
+            throw new Error("headline guard: cut-list claim below the minimum saving");
+        if (!h.hero.includes("~") || !/estimate/.test(h.sub))
+            throw new Error("headline guard: estimate marker missing");
+        if (a.lowerBound && !/ cost at least /.test(h.hero))
+            throw new Error("headline guard: lower-bound marker missing");
+    }
+    else if (h.id === "mcp-unmeasured") {
+        if (t.measuredItems > 0 || t.unmeasuredItems === 0)
+            throw new Error("headline guard: mcp claim without unmeasured-only data");
+        if (/\d+(\.\d+)?k? tokens/.test(h.hero + h.sub))
+            throw new Error("headline guard: token number for unmeasured data");
+    }
+    void window;
+}
+function pickCardAgent(r, want) {
+    const shown = r.agents.filter((a) => !a.presentInRepoOnly);
+    if (want)
+        return shown.find((a) => a.id === want) ?? null;
+    const withData = shown.filter((a) => buildHeadline(a, r.scan.window));
+    withData.sort((a, b) => b.totals.always.est - a.totals.always.est || b.totals.always.unmeasuredItems - a.totals.always.unmeasuredItems);
+    return withData[0] ?? null;
+}
+const FILLS = ["#1f6feb", "#8250df", "#1a7f37", "#9a6700", "#bf3989", "#0a7a8a", "#bc4c00"];
+const OTHER_FILL = "#57606a";
+exports.THEMES = {
+    dark: { bg: "#0d1117", text: "#e6edf3", muted: "#9da7b3", chip: "#21262d", border: "#30363d" },
+    light: { bg: "#ffffff", text: "#1f2328", muted: "#4b5563", chip: "#eef1f4", border: "#d0d7de" },
+};
+function fit(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return maxChars <= 3 ? text.slice(0, Math.max(0, maxChars)) : text.slice(0, maxChars - 3) + "...";
+}
+/**
+ * Font stack with sane fallbacks: SVG renderers (browsers, rsvg, Inkscape, link-preview bots) differ in which of these exist,
+ * and `system-ui` is unknown to some of them. It always ends in the generic `sans-serif`, and every width estimate below assumes
+ * a wide face (DejaVu Sans is ~0.62 em per character) so text still fits when the fallback is the widest one.
+ */
+exports.CARD_FONT = "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Liberation Sans', 'DejaVu Sans', sans-serif";
+const DEFAULT_CHAR_EM = 0.62;
+/** Greedy wrap of a tile label at spaces and after hyphens; the last allowed line ends in "..." when text is left over. Never returns an empty list. */
+function wrapLabel(label, maxChars, maxLines) {
+    const toks = label.split(/(?<=-)|\s+/).filter(Boolean);
+    const lines = [];
+    let cur = "";
+    const rest = [];
+    for (let i = 0; i < toks.length; i++) {
+        const t = toks[i];
+        const joined = cur ? (cur.endsWith("-") ? cur + t : `${cur} ${t}`) : t;
+        if (!cur || joined.length <= maxChars)
+            cur = joined;
+        else {
+            lines.push(cur);
+            cur = t;
+        }
+        if (lines.length === maxLines) {
+            rest.push(...toks.slice(i));
+            cur = "";
+            break;
+        }
+    }
+    if (cur)
+        lines.push(cur);
+    if (lines.length > maxLines)
+        lines.length = maxLines;
+    const out = lines.map((l) => (l.length > maxChars ? fit(l, maxChars) : l));
+    if (rest.length > 0)
+        out[out.length - 1] = fit(out[out.length - 1] + "...", maxChars);
+    return out.length ? out : [fit(label, maxChars)];
+}
+/** Greedy wrap on " · " boundaries so a footer never runs off the card. */
+function wrapSegments(segments, maxChars) {
+    const lines = [];
+    let cur = "";
+    for (const seg of segments) {
+        const next = cur ? `${cur} · ${seg}` : seg;
+        if (cur && next.length > maxChars) {
+            lines.push(cur);
+            cur = seg;
+        }
+        else
+            cur = next;
+    }
+    if (cur)
+        lines.push(cur);
+    return lines.map((l) => fit(l, maxChars));
+}
+/** No paths or file contents by construction: only cut-list group names (plugin / MCP server names; anonymisable), generic labels (cardLabel), counts, the version and a date reach the SVG. */
+function renderCard(r, a, o) {
+    const CHAR_EM = o.charEm ?? DEFAULT_CHAR_EM;
+    const maxCharsFor = (px, fontSize) => Math.max(1, Math.floor(px / (fontSize * CHAR_EM)));
+    const head = buildHeadline(a, r.scan.window, o.headline ?? "cut") ?? buildHeadline(a, r.scan.window, "total");
+    if (!head)
+        throw new Error("nothing measurable to put on a card");
+    assertHeadline(head, a, r.scan.window);
+    const th = exports.THEMES[o.theme];
+    const og = o.size === "og";
+    const W = og ? 1200 : 1080;
+    const H = og ? 630 : 1080;
+    const pad = og ? 48 : 56;
+    const innerW = W - pad * 2;
+    const font = o.fontFamily ?? exports.CARD_FONT;
+    const heroMax = og ? 64 : 72;
+    let heroLines = [head.hero];
+    let heroSize = Math.min(heroMax, Math.floor(innerW / (head.hero.length * CHAR_EM)));
+    // Square cards have the room for a two-line hero: split it at the space nearest the middle when one line would be small.
+    if (!og && heroSize < 52 && head.hero.includes(" ")) {
+        const mid = head.hero.length / 2;
+        const cut = [...head.hero.matchAll(/ /g)].map((m) => m.index).sort((x, y) => Math.abs(x - mid) - Math.abs(y - mid))[0];
+        heroLines = [head.hero.slice(0, cut), head.hero.slice(cut + 1)];
+        heroSize = Math.min(heroMax, Math.floor(innerW / (Math.max(...heroLines.map((l) => l.length)) * CHAR_EM)));
+    }
+    const heroLineH = Math.round(heroSize * 1.12);
+    const heroY = og ? 168 : heroLines.length > 1 ? 196 : 214;
+    const subSize = og ? 26 : 30;
+    const subY = heroY + (heroLines.length - 1) * heroLineH + (og ? 46 : 52);
+    const showStrip = !!a.savings && head.id !== "cut-list";
+    const tmY = subY + (og ? 36 : 56);
+    // footer: wrap on segment boundaries, anchored to the bottom edge
+    const unvalidated = a.profile.id.startsWith("claude") || a.profile.id === "cursor-mixed" || a.profile.id === "heuristic";
+    const footSize = og ? 17 : 20;
+    const footLines = wrapSegments(["npx prehello", exports.REPO_URL, "local-only scan", `estimate band: ${a.profile.band}${unvalidated ? " (unvalidated)" : ""}`, `window ${(0, fmt_1.fmtWindow)(r.scan.window)}`, ...(r.partial ? ["PARTIAL scan"] : [])], maxCharsFor(innerW, footSize));
+    const footLineH = footSize + 6;
+    const footTop = H - (og ? 30 : 44) - (footLines.length - 1) * footLineH;
+    // Layout flows upward from the footer so a wrapped (2-3 line) footer can never collide with the chips or the treemap.
+    const chipH = 38;
+    const limit = footTop - footSize - (og ? 14 : 24);
+    const stripBlock = showStrip ? (og ? 40 : 52) : 0;
+    const tmH = Math.max(og ? 120 : 200, Math.min(og ? 400 : 640, limit - chipH - (og ? 22 : 30) - stripBlock - tmY));
+    const stripY = tmY + tmH + (og ? 30 : 42);
+    const chipsY = tmY + tmH + (og ? 22 : 30) + stripBlock;
+    // Treemap: the same groups as "what to cut" (plugin posthog, 18 Cursor-managed skills, ...) plus the always-on items that are not removable
+    // (rules, instruction files). Small tiles are merged into "other" so every visible tile is big enough to read.
+    const tiles = (0, savings_1.cardTiles)(a.items, !!o.anonymize);
+    const tilesTotal = tiles.reduce((s, t) => s + t.tokens, 0);
+    const MAX_TILES = og ? 7 : 8;
+    const MIN_SHARE = 0.04;
+    const shown = tiles.filter((t, k) => k < MAX_TILES && t.tokens / tilesTotal >= MIN_SHARE);
+    const restTiles = tiles.filter((t) => !shown.includes(t));
+    if (restTiles.length === 1 && restTiles[0].tokens / tilesTotal >= MIN_SHARE)
+        shown.push(restTiles.pop());
+    const rest = restTiles.reduce((s, t) => s + t.tokens, 0);
+    const cells = shown.map((t, k) => ({ label: t.named ? (0, secrets_1.scrubSecrets)(t.label) : t.label, v: t.tokens, fill: FILLS[k % FILLS.length] }));
+    if (rest > 0)
+        cells.push({ label: restTiles.length > 1 ? `other (${restTiles.length} smaller)` : "other", v: rest, fill: OTHER_FILL });
+    const rects = (0, treemap_1.squarify)(cells.map((c) => c.v), pad, tmY, innerW, tmH);
+    const totalCells = cells.reduce((s, c) => s + c.v, 0);
+    const parts = [];
+    parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" role="img" aria-labelledby="t d">`);
+    parts.push(`<title id="t">${(0, fmt_1.xmlEscape)(head.hero)}</title><desc id="d">${(0, fmt_1.xmlEscape)(head.sub)}. Generated by prehello ${(0, fmt_1.xmlEscape)(r.tool.version)}. Token counts are estimates.</desc>`);
+    parts.push(`<rect width="${W}" height="${H}" fill="${th.bg}"/>`);
+    parts.push(`<text x="${pad}" y="${pad + 20}" font-family="${font}" font-size="28" font-weight="700" fill="${th.text}">prehello <tspan font-weight="400" fill="${th.muted}" font-size="20">v${(0, fmt_1.xmlEscape)(r.tool.version)} · ${(0, fmt_1.xmlEscape)(r.generatedAt.slice(0, 10))}</tspan></text>`);
+    if (a.grade) {
+        const gx = W - pad - 36;
+        const gy = pad + 14;
+        parts.push(`<circle cx="${gx}" cy="${gy}" r="34" fill="none" stroke="${th.muted}" stroke-width="3"/>`);
+        parts.push(`<text x="${gx}" y="${gy + 16}" text-anchor="middle" font-family="${font}" font-size="46" font-weight="800" fill="${th.text}">${(0, fmt_1.xmlEscape)(a.grade.letter)}</text>`);
+        parts.push(`<text x="${W - pad}" y="${gy + 54}" text-anchor="end" font-family="${font}" font-size="14" fill="${th.muted}">Context Grade${a.grade.provisional ? " (provisional)" : ""}</text>`);
+    }
+    heroLines.forEach((line, k) => parts.push(`<text x="${pad}" y="${heroY + k * heroLineH}" font-family="${font}" font-size="${heroSize}" font-weight="800" fill="${th.text}">${(0, fmt_1.xmlEscape)(line)}</text>`));
+    parts.push(`<text x="${pad}" y="${subY}" font-family="${font}" font-size="${subSize}" fill="${th.muted}">${(0, fmt_1.xmlEscape)(fit(head.sub, maxCharsFor(innerW, subSize)))}</text>`);
+    rects.forEach((rc) => {
+        const c = cells[rc.i];
+        const g = 3;
+        const rx = rc.x + g / 2, ry = rc.y + g / 2, rw = Math.max(0, rc.w - g), rh = Math.max(0, rc.h - g);
+        parts.push(`<rect x="${rx.toFixed(1)}" y="${ry.toFixed(1)}" width="${rw.toFixed(1)}" height="${rh.toFixed(1)}" rx="6" fill="${c.fill}"/>`);
+        // label size follows cell size: big cells get a big label, token count and share; small cells get the number only
+        const big = rw >= 240 && rh >= 110;
+        const mid = rw >= 120 && rh >= 64;
+        const lf0 = big ? 26 : mid ? 20 : 15;
+        if (rw >= 64 && rh >= 34) {
+            const avail = rw - 18;
+            // shrink the label to fit before wrapping or truncating it (never below 11 px)
+            let lf = Math.max(11, Math.min(lf0, Math.floor(avail / (Math.max(1, c.label.length) * CHAR_EM))));
+            let lines = [c.label];
+            if (c.label.length * lf * CHAR_EM > avail) {
+                // still too wide at the smallest size: wrap onto up to 3 lines at spaces and hyphens, ellipsis only if it still does not fit
+                lf = Math.min(lf0, 14);
+                const withSub = Math.floor((rh - 14 - (13 + 8)) / (lf + 3));
+                const maxLines = Math.min(3, withSub >= 1 ? withSub : Math.max(1, Math.floor((rh - 8) / (lf + 3))));
+                lines = wrapLabel(c.label, maxCharsFor(avail, lf), maxLines);
+            }
+            const lineH = lf + 3;
+            const tf = Math.max(13, lf - 4);
+            lines.forEach((ln, k) => parts.push(`<text x="${(rx + 10).toFixed(1)}" y="${(ry + lf + 6 + k * lineH).toFixed(1)}" font-family="${font}" font-size="${lf}" font-weight="600" fill="#ffffff">${(0, fmt_1.xmlEscape)(ln)}</text>`));
+            const subY = ry + lf + 6 + (lines.length - 1) * lineH + tf + 6;
+            if (lines.length === 1 ? rh >= lf + tf + 22 : subY <= ry + rh - 6) {
+                const pct = totalCells ? ` · ${(0, fmt_1.fmtPct)((c.v / totalCells) * 100)}` : "";
+                const ty = lines.length === 1 ? ry + lf + tf + 12 : subY;
+                parts.push(`<text x="${(rx + 10).toFixed(1)}" y="${ty.toFixed(1)}" font-family="${font}" font-size="${tf}" fill="#ffffff">${(0, fmt_1.xmlEscape)(fit(`~${(0, fmt_1.fmtTok)(c.v)}${big ? pct : ""}`, maxCharsFor(avail, tf)))}</text>`);
+            }
+        }
+        else if (rw >= 24 && rh >= 90) {
+            // a tall, narrow tile: the name and size read bottom-to-top instead of being dropped
+            const tx = rx + rw / 2 + 4.5;
+            const ty = ry + rh - 10;
+            parts.push(`<text transform="rotate(-90 ${tx.toFixed(1)} ${ty.toFixed(1)})" x="${tx.toFixed(1)}" y="${ty.toFixed(1)}" font-family="${font}" font-size="13" font-weight="600" fill="#ffffff">${(0, fmt_1.xmlEscape)(fit(`${c.label} · ~${(0, fmt_1.fmtTok)(c.v)}`, maxCharsFor(rh - 20, 13)))}</text>`);
+        }
+        else if (rw >= 40 && rh >= 22) {
+            parts.push(`<text x="${(rx + 6).toFixed(1)}" y="${(ry + rh / 2 + 5).toFixed(1)}" font-family="${font}" font-size="13" fill="#ffffff">${(0, fmt_1.xmlEscape)(fit(`~${(0, fmt_1.fmtTok)(c.v)}`, maxCharsFor(rw - 8, 13)))}</text>`);
+        }
+    });
+    if (showStrip && a.savings) {
+        const sv = a.savings;
+        const kindWord = sv.top.every((c) => c.kind === "mcp") ? "MCP server" : sv.top.some((c) => c.kind === "mcp") ? "skill/plugin/MCP group" : "skill/plugin group";
+        const line = `Cut the top ${sv.n} ${kindWord}${sv.n > 1 ? "s" : ""}: save ~${(0, fmt_1.fmtTok)(sv.topTokens)} tokens (estimate)`;
+        const ss = og ? 22 : 24;
+        parts.push(`<text x="${pad}" y="${stripY}" font-family="${font}" font-size="${ss}" font-weight="700" fill="${th.text}">${(0, fmt_1.xmlEscape)(fit(line, maxCharsFor(innerW, ss)))}</text>`);
+    }
+    // chips (only for data that exists)
+    const chips = [];
+    // the cut headline does not show the total itself, so the total always appears as the first chip
+    if (head.id === "cut-list")
+        chips.push(`always-on ${a.lowerBound ? exports.AT_LEAST + " " : ""}~${(0, fmt_1.fmtTok)(a.totals.always.est)} · ${(0, fmt_1.fmtPct)((a.totals.always.est / r.scan.window) * 100)} of ${(0, fmt_1.fmtWindow)(r.scan.window)}`);
+    const mode = (m) => a.totals[m];
+    for (const m of ["deferred", "conditional", "on-demand"])
+        if (mode(m).measuredItems)
+            chips.push(`${m} ~${(0, fmt_1.fmtTok)(mode(m).est)}`);
+    const unm = a.totals.always.unmeasuredItems + a.totals.deferred.unmeasuredItems;
+    if (unm)
+        chips.push(`unmeasured: ${unm} item${unm > 1 ? "s" : ""}`);
+    chips.push(...((0, agents_1.agentMeta)(a.id).cardChips ?? []));
+    if (r.partial)
+        chips.unshift("partial scan");
+    let cx = pad;
+    const chipSize = 18;
+    for (const chip of chips) {
+        const cw = chip.length * chipSize * CHAR_EM + 28;
+        if (cx + cw > W - pad)
+            break;
+        parts.push(`<rect x="${cx}" y="${chipsY}" width="${cw.toFixed(0)}" height="${chipH}" rx="19" fill="${th.chip}" stroke="${th.border}"/>`);
+        parts.push(`<text x="${(cx + 14).toFixed(0)}" y="${chipsY + 25}" font-family="${font}" font-size="${chipSize}" fill="${th.text}">${(0, fmt_1.xmlEscape)(chip)}</text>`);
+        cx += cw + 12;
+    }
+    footLines.forEach((l, k) => parts.push(`<text x="${pad}" y="${footTop + k * footLineH}" font-family="${font}" font-size="${footSize}" fill="${th.muted}">${(0, fmt_1.xmlEscape)(l)}</text>`));
+    parts.push(`</svg>`);
+    return parts.join("\n") + "\n";
+}

package/dist/render/fix.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFix = renderFix;
+const fmt_1 = require("../util/fmt");
+/** Dry-run plan. This function only formats text; there is no code path in 0.1 that modifies user files. */
+function renderFix(r) {
+    const lines = [];
+    const items = r.findings.filter((f) => f.fix);
+    const total = items.reduce((s, f) => s + (f.savingsTokens ?? 0), 0);
+    lines.push(`Fix plan (dry run): ${items.length} suggestion${items.length === 1 ? "" : "s"}${total ? `, ~${(0, fmt_1.fmtInt)(total)} always-on tokens could be saved (estimate)` : ""} · 0 files changed`);
+    lines.push("");
+    items.forEach((f, i) => {
+        lines.push(` ${i + 1}. [${f.id}] ${(0, fmt_1.sanitize)(f.message, 200)}`);
+        lines.push(`    suggestion: ${(0, fmt_1.sanitize)(f.fix ?? "", 240)}`);
+        lines.push(`    savings: ${f.savingsTokens ? "~" + (0, fmt_1.fmtInt)(f.savingsTokens) + " tokens (estimate)" : "none measurable (clarity/correctness)"} · confidence: ${f.confidence}`);
+    });
+    if (!items.length)
+        lines.push(" Nothing to suggest from the rules implemented in 0.1 (F1, F2, F4, F5, F7, F8, F9).");
+    lines.push("");
+    lines.push("Nothing was modified. prehello 0.1 has no --apply or --patch: changes are yours to make. Content-level rewrites are never auto-applied.");
+    return lines.join("\n") + "\n";
+}

package/dist/render/json.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJson = toJson;
+exports.numberedLabels = numberedLabels;
+const redact_1 = require("../redact");
+function numberedLabels(agent, only) {
+    const list = only ?? agent.items;
+    // privacy-safe labels: cardLabel, numbered when repeated ("MCP server 2")
+    const totals = new Map();
+    for (const it of list)
+        totals.set(it.cardLabel, (totals.get(it.cardLabel) ?? 0) + 1);
+    const seen = new Map();
+    const out = new Map();
+    for (const it of list) {
+        const n = (seen.get(it.cardLabel) ?? 0) + 1;
+        seen.set(it.cardLabel, n);
+        out.set(it.id, (totals.get(it.cardLabel) ?? 1) > 1 ? `${it.cardLabel} ${n}` : it.cardLabel);
+    }
+    return out;
+}
+/** Serialise the Report. NEVER includes file contents. `strict` drops paths/names entirely (use before sharing). */
+/** Defence in depth: user-controlled names (skill `name:`, MCP server keys, …) must never carry a secret-shaped string into JSON. */
+function scrubDeep(v) {
+    if (typeof v === "string")
+        return (0, redact_1.scrubSecrets)(v);
+    if (Array.isArray(v))
+        return v.map(scrubDeep);
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [(0, redact_1.scrubSecrets)(k), scrubDeep(x)]));
+    return v;
+}
+function toJson(r, c, strict) {
+    return scrubDeep(toJsonRaw(r, c, strict));
+}
+function toJsonRaw(r, c, strict) {
+    const dp = (p) => (0, redact_1.displayPath)(p, c);
+    return {
+        schemaVersion: r.schemaVersion,
+        tool: r.tool,
+        generatedAt: r.generatedAt,
+        redacted: strict ? "strict" : "paths-shortened (~ and ./ prefixes); server and file names kept",
+        scan: { ...r.scan, cwd: strict ? "project" : dp(r.scan.cwd) },
+        agents: r.agents.map((a) => {
+            const labels = numberedLabels(a);
+            return {
+                id: a.id,
+                name: a.name,
+                detected: a.detected,
+                detectedBy: a.detectedBy,
+                presentInRepoOnly: a.presentInRepoOnly,
+                profile: a.profile,
+                totals: a.totals,
+                percentOfWindowAlways: a.percentOfWindowAlways,
+                alwaysIsLowerBound: a.lowerBound,
+                savings: a.savings
+                    ? {
+                        ...a.savings,
+                        top: a.savings.top.map((c, i) => (strict ? { label: `group ${i + 1}`, kind: c.kind, tokens: c.tokens, count: c.count } : c)),
+                        note: "estimate: what removing these groups would save; not a promise",
+                    }
+                    : null,
+                grade: a.grade,
+                ...(a.gradeNote ? { gradeNote: a.gradeNote } : {}),
+                coverage: a.coverage,
+                installedButNothingFound: a.items.length === 0 && !a.presentInRepoOnly,
+                offenders: a.offenders.map((x) => (strict ? { kind: x.kind, loadMode: x.loadMode, tokens: x.tokens } : { label: x.label, path: dp(x.path), kind: x.kind, loadMode: x.loadMode, tokens: x.tokens, ...(x.note ? { note: x.note } : {}) })),
+                mcpServers: a.mcpServers.map((m, i) => (strict ? { n: i + 1, transport: m.transport, scope: m.scope, measured: m.measured } : { name: m.name, source: dp(m.source), scope: m.scope, transport: m.transport, measured: m.measured })),
+                unmeasuredBanner: a.unmeasuredBanner,
+                items: a.items.map((it) => ({
+                    id: it.id,
+                    kind: it.kind,
+                    scope: it.scope,
+                    loadMode: it.loadMode,
+                    label: strict ? labels.get(it.id) : it.label,
+                    ...(strict ? {} : { path: dp(it.path) }),
+                    tokens: it.tokens,
+                    unmeasured: it.tokens === null,
+                    ...(it.unmeasuredReason ? { unmeasuredReason: it.unmeasuredReason } : {}),
+                    chars: it.chars,
+                    lines: it.lines,
+                    ...(it.breakdown && !strict ? { breakdown: it.breakdown } : {}),
+                    ...(it.parts && !strict ? { parts: it.parts } : {}),
+                    confidence: it.confidence,
+                    evidence: it.evidence,
+                    notes: strict ? it.notes.filter((n) => !/["'`\/\\@]/.test(n) && !/\bplugin\b/i.test(n)) : it.notes,
+                })),
+            };
+        }),
+        excluded: strict ? r.excluded.map((e) => ({ agent: e.agent, reason: e.reason.replace(/"[^"]*"/g, '"…"') })) : r.excluded.map((e) => ({ agent: e.agent, path: dp(e.path), reason: e.reason })),
+        findings: r.findings.map((f) => strict
+            ? { id: f.id, severity: f.severity, agent: f.agent, savingsTokens: f.savingsTokens, confidence: f.confidence, fileCount: f.paths.length }
+            : { id: f.id, severity: f.severity, agent: f.agent, message: f.message, paths: f.paths.map(dp), savingsTokens: f.savingsTokens, confidence: f.confidence, fix: f.fix }),
+        warnings: strict ? r.warnings.length : r.warnings,
+        notMeasurable: r.notMeasurable,
+        partial: r.partial ?? null,
+    };
+}

package/dist/render/markdown.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mdCode = mdCode;
+exports.fixtureNote = fixtureNote;
+exports.renderMarkdown = renderMarkdown;
+const card_1 = require("./card");
+const savings_1 = require("../analyze/savings");
+const terminal_1 = require("./terminal");
+const fmt_1 = require("../util/fmt");
+const MAX_NAME = 60;
+const ZERO_WIDTH = /[\u200b-\u200f\u2028\u2029\u2060\ufeff]/g;
+/** A user-controlled name as an inline code span. Never throws, never returns an empty span, safe inside a table cell when `table`. */
+function mdCode(name, table = false) {
+    let t = (0, fmt_1.sanitize)(name.replace(/[\r\n\t\v\f]+/g, " "), 400).replace(ZERO_WIDTH, "").replace(/\s+/g, " ").trim();
+    if (t.length > MAX_NAME)
+        t = t.slice(0, MAX_NAME - 3) + "...";
+    if (!t)
+        t = "(unnamed)";
+    if (table)
+        t = t.replace(/\|/g, "\\|");
+    const longest = Math.max(0, ...(t.match(/`+/g) ?? []).map((r) => r.length));
+    const fence = "`".repeat(longest + 1);
+    const pad = /^`|`$/.test(t) ? " " : "";
+    return `${fence}${pad}${t}${pad}${fence}`;
+}
+/** One-line note (a count, no paths) when fixture folders holding agent files were skipped; null otherwise. */
+function fixtureNote(r) {
+    const n = r.scan.fixturesSkipped;
+    return n ? `Skipped ${n} fixture folder${n > 1 ? "s" : ""} with agent files (use --include-fixtures to count them).` : null;
+}
+const ascii = (s) => s.replace(/±/g, "+/-").replace(/−/g, "-");
+const plural = (n, one, many = one + "s") => `${n} ${n === 1 ? one : many}`;
+function alwaysSentence(a, window) {
+    const t = a.totals.always;
+    if (!t.measuredItems)
+        return t.unmeasuredItems ? `${plural(t.unmeasuredItems, "always-loaded item")} could not be measured: token cost unknown (not zero).` : "nothing that loads up front was found (this is not a score of 0; the agent still has its own system prompt and tools).";
+    const lb = a.lowerBound ? `${card_1.AT_LEAST} ` : "";
+    const pct = (t.est / window) * 100;
+    const share = pct < 0.1 ? (a.lowerBound ? "under 0.1% so far" : "under 0.1%") : `${a.lowerBound ? card_1.AT_LEAST + " " : "about "}${(0, fmt_1.fmtPct)(pct)}`;
+    return `${lb}~${(0, fmt_1.fmtTok)(t.est)} tokens always on, ${share} of a ${(0, fmt_1.fmtWindow)(window)} window (range ~${(0, fmt_1.fmtTok)(t.low)}-${(0, fmt_1.fmtTok)(t.high)}).`;
+}
+function gradeLine(a) {
+    const g = a.grade;
+    if (!g)
+        return a.gradeNote ? `Context Grade: none (${ascii((0, fmt_1.sanitize)(a.gradeNote, 200)).replace(/^no grade: /, "")}).` : undefined;
+    const why = g.provisional ? ` (provisional${g.cappedAt ? `, capped at ${g.cappedAt}` : ""}: some always-loaded items are unmeasured${a.totals.always.unmeasuredItems ? "" : " or the scan hit its budget"})` : "";
+    return `Context Grade: **${g.letter}**${why}. A heuristic, not a standard.`;
+}
+function unmeasuredList(a, o) {
+    const names = a.mcpServers.filter((m) => !m.measured).map((m) => m.name);
+    if (!names.length)
+        return "";
+    if (o.anonymize)
+        return ` (${plural(names.length, "MCP server")}, names hidden)`;
+    return ` (${names.slice(0, 6).map((n) => mdCode(n)).join(", ")}${names.length > 6 ? `, +${names.length - 6} more` : ""})`;
+}
+function agentSection(r, a, o) {
+    const out = [`### ${a.name}`, ""];
+    const lead = alwaysSentence(a, r.scan.window);
+    out.push(lead.charAt(0).toUpperCase() + lead.slice(1));
+    const gl = gradeLine(a);
+    if (gl)
+        out.push("", gl);
+    const t = a.totals.always;
+    const tiles = (0, savings_1.cardTiles)(a.items, o.anonymize);
+    const unmeasuredServers = a.mcpServers.filter((m) => !m.measured);
+    if (tiles.length || unmeasuredServers.length) {
+        out.push("", "| What loads before hello | ~Tokens | Share of measured |", "|---|--:|--:|");
+        const total = tiles.reduce((s, x) => s + x.tokens, 0) || 1;
+        const MAX = 10;
+        for (const x of tiles.slice(0, MAX))
+            out.push(`| ${x.named ? mdCode(x.label, true) : x.label} | ~${(0, fmt_1.fmtTok)(x.tokens)} | ${(0, fmt_1.fmtPct)((x.tokens / total) * 100)} |`);
+        if (tiles.length > MAX) {
+            const rest = tiles.slice(MAX).reduce((s, x) => s + x.tokens, 0);
+            out.push(`| ${tiles.length - MAX} smaller groups | ~${(0, fmt_1.fmtTok)(rest)} | ${(0, fmt_1.fmtPct)((rest / total) * 100)} |`);
+        }
+        unmeasuredServers.slice(0, 8).forEach((m, i) => out.push(`| ${o.anonymize ? `unmeasured MCP server ${i + 1}` : `MCP server ${mdCode(m.name, true)}`} | not measured | - |`));
+        if (unmeasuredServers.length > 8)
+            out.push(`| ${unmeasuredServers.length - 8} more unmeasured MCP servers | not measured | - |`);
+        if (a.lowerBound)
+            out.push("", `The total is a lower bound: items marked "not measured" are not counted, and are never shown as 0.`);
+    }
+    if (a.savings) {
+        const sv = a.savings;
+        out.push("", `**What to cut** (estimates, not a promise): removing the top ${sv.n === 1 ? "group" : sv.n + " groups"} would save ~${(0, fmt_1.fmtTok)(sv.topTokens)} tokens (${(0, fmt_1.fmtPct)(sv.pctOfWindow)} of a ${(0, fmt_1.fmtWindow)(r.scan.window)} window).`, "");
+        const byCut = new Map(tiles.filter((x) => x.cut !== undefined).map((x) => [x.cut, x]));
+        sv.top.forEach((c, i) => {
+            const x = byCut.get(i);
+            const label = x ? (x.named ? mdCode(x.label) : x.label) : "group";
+            const cnt = c.kind === "skills" && c.count > 1 && c.label.startsWith("plugin ") ? `, ${c.count} skills` : "";
+            out.push(`${i + 1}. ${label}: ~${(0, fmt_1.fmtTok)(c.tokens)} (${(0, fmt_1.fmtPct)((c.tokens / (t.est || 1)) * 100)} of always-on${cnt})`);
+        });
+    }
+    const c = a.coverage;
+    const totalAlways = c.alwaysMeasuredItems + c.alwaysUnmeasuredItems;
+    if (!totalAlways)
+        return [...out, ""];
+    out.push("", "**Measured vs not measured** (always-on items)", "");
+    {
+        out.push(`- Measured ${c.alwaysMeasuredItems} of ${totalAlways}${c.alwaysFraction !== null ? ` (${Math.round(c.alwaysFraction * 100)}%)` : ""}${c.alwaysMeasuredItems ? `: ${(0, terminal_1.kinds)(c.measuredKinds)}` : ""}`);
+        if (c.alwaysUnmeasuredItems)
+            out.push(`- NOT measured: ${(0, terminal_1.kinds)(c.unmeasuredKinds)}${c.unmeasuredKinds["mcp-server"] ? unmeasuredList(a, o) : ""}. No token count; never shown as 0.`);
+    }
+    const other = ["deferred", "conditional", "on-demand"].filter((m) => a.totals[m].measuredItems);
+    if (other.length)
+        out.push(`- Not always on: ${other.map((m) => `${m} ~${(0, fmt_1.fmtTok)(a.totals[m].est)}`).join(", ")} (loaded only when triggered or invoked)`);
+    const nf = r.findings.filter((f) => f.agent === a.id).length;
+    if (nf)
+        out.push(`- ${plural(nf, "finding")} (duplicates, over-long or ignored files): details name files, so they are left out of this report. Run prehello locally to see them.`);
+    out.push("");
+    return out;
+}
+/** The headline sentence of the report (top agent), with the same guards as the card. */
+function headlineOf(r, o) {
+    const agent = (0, card_1.pickCardAgent)(r);
+    if (!agent)
+        return null;
+    const h = (0, card_1.buildHeadline)(agent, r.scan.window, o.headline) ?? (0, card_1.buildHeadline)(agent, r.scan.window, "total");
+    if (!h)
+        return null;
+    (0, card_1.assertHeadline)(h, agent, r.scan.window);
+    return { agent, hero: h.hero, sub: h.sub, id: h.id };
+}
+function footer(r, shown) {
+    const unvalidated = shown.some((a) => a.profile.id.startsWith("claude") || a.profile.id === "cursor-mixed" || a.profile.id === "heuristic");
+    const bands = [...new Set(shown.filter((a) => a.totals.always.measuredItems).map((a) => `${a.name} ${ascii(a.profile.band)}`))];
+    return `_Generated by prehello ${r.tool.version} on ${r.generatedAt.slice(0, 10)}. Local-only scan: no paths or file contents are included. All token counts are estimates (${r.scan.tokenizer.method === "bpe-o200k" ? "o200k BPE with per-agent scaling factors" : "chars/3.5 heuristic"}${bands.length ? "; band " + bands.join(", ") : ""}${unvalidated ? ", unvalidated" : ""}), not exact for any model. Window ${(0, fmt_1.fmtWindow)(r.scan.window)}.${r.partial ? " PARTIAL scan: every total is a lower bound." : ""} Try it: \`npx prehello\` (https://${card_1.REPO_URL})._`;
+}
+function renderMarkdown(r, o) {
+    const shown = r.agents.filter((a) => !a.presentInRepoOnly);
+    const out = ["## prehello report: what your coding agent loads before you say hello", ""];
+    const repoOnly = r.agents.filter((a) => a.presentInRepoOnly).map((a) => a.name);
+    if (!shown.length) {
+        out.push("No coding agent was detected on this machine, so nothing was measured. This is not a score of 0.", "");
+        if (repoOnly.length)
+            out.push(`Agent files for ${repoOnly.join(" and ")} exist in the repo, but the agent is not installed here, so they are not counted.`, "");
+        out.push(footer(r, shown));
+        return out.join("\n") + "\n";
+    }
+    const head = headlineOf(r, o);
+    if (head) {
+        // cut headline: "top 3 of 6 groups: cut them, save ~13.2k (estimate)" -> "Claude Code: top 3 of 6 groups - cut them, save ~13.2k (estimate)."
+        const sub = head.sub.replace(/ · /g, ", ");
+        const parts = sub.split(", ");
+        const line = head.id === "cut-list" ? `${head.agent.name}: ${sub.replace(": ", " - ")}` : (sub.includes(" window") ? `${sub.charAt(0).toUpperCase()}${sub.slice(1, sub.indexOf(" window") + 7)} (${parts.slice(-2).join(", ")})` : `${sub.charAt(0).toUpperCase()}${sub.slice(1)}`);
+        out.push(`**${head.hero.charAt(0).toUpperCase()}${head.hero.slice(1)}**`, "", `${line}.`, "");
+    }
+    else
+        out.push("Nothing measurable loads before hello for the detected agents. This is not a score of 0: absence of data is never shown as 0.", "");
+    if (o.compact) {
+        for (const a of shown) {
+            const t = a.totals.always;
+            const g = a.grade ? `, grade ${a.grade.letter}${a.grade.provisional ? " (provisional)" : ""}` : "";
+            out.push(`- **${a.name}**: ${t.measuredItems ? `${a.lowerBound ? card_1.AT_LEAST + " " : ""}~${(0, fmt_1.fmtTok)(t.est)} tokens always on (${a.lowerBound ? card_1.AT_LEAST + " " : ""}${(0, fmt_1.fmtPct)((t.est / r.scan.window) * 100)} of ${(0, fmt_1.fmtWindow)(r.scan.window)})` : t.unmeasuredItems ? "tokens unmeasured (not zero)" : "nothing found up front"}${g}`);
+        }
+        const cut = (0, card_1.pickCardAgent)(r)?.savings;
+        const top = (0, card_1.pickCardAgent)(r);
+        if (cut && top) {
+            const tiles = (0, savings_1.cardTiles)(top.items, o.anonymize).filter((x) => x.cut !== undefined && x.cut < cut.n);
+            out.push("", `Cut first (${top.name}, estimates): ${tiles.map((x) => `${x.named ? mdCode(x.label) : x.label} ~${(0, fmt_1.fmtTok)(x.tokens)}`).join(", ")}`);
+        }
+        const fxc = fixtureNote(r);
+        if (fxc)
+            out.push("", fxc);
+        out.push("", footer(r, shown));
+        return out.join("\n") + "\n";
+    }
+    for (const a of shown)
+        out.push(...agentSection(r, a, o));
+    if (repoOnly.length)
+        out.push(`Agent files for ${repoOnly.join(" and ")} exist in the repo, but the agent is not installed here, so they are not counted.`, "");
+    const shared = r.findings.filter((f) => f.agent === "all").length;
+    if (shared)
+        out.push(`${plural(shared, "finding")} apply to more than one agent (duplicate or conflicting files); details name files, so they are left out of this report.`, "");
+    if (r.warnings.length || r.partial)
+        out.push(`**Partial results:** some sources could not be read or were skipped (or the scan hit its budget), so every total is a lower bound. Run prehello locally for details.`, "");
+    const fx = fixtureNote(r);
+    if (fx)
+        out.push(fx, "");
+    out.push(footer(r, shown));
+    return out.join("\n") + "\n";
+}