prehello 0.0.0-stage → 0.1.0

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 priors" : "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." : ""}_`;
+}
+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";
+}

package/dist/render/png.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PNG_MAGIC = exports.PNG_UNAVAILABLE_MESSAGE = exports.FONT_DIR = exports.PNG_CHAR_EM = exports.PNG_FONT_FAMILY = exports.PngUnavailableError = void 0;
+exports.detectInstallKind = detectInstallKind;
+exports.pngUnavailableMessage = pngUnavailableMessage;
+exports.loadEngine = loadEngine;
+exports.toFontSafeText = toFontSafeText;
+exports.tagPng = tagPng;
+exports.svgToPng = svgToPng;
+/**
+ * PNG export of the share card. Pure JS + WebAssembly: no native binaries, no network, no child processes.
+ *
+ * Engine: `@resvg/resvg-wasm` (MPL-2.0), an OPTIONAL dependency. If it is not installed, prehello says so and SVG keeps working.
+ * Fonts: three subsetted static weights of Inter (SIL OFL 1.1, see assets/fonts/OFL.txt) are shipped in the package and handed to the
+ * renderer as buffers. System fonts are never used, so the PNG looks the same on every machine and can never show "tofu" boxes
+ * for the glyphs a card uses (ASCII, Latin-1, and a handful of punctuation marks).
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+class PngUnavailableError extends Error {
+}
+exports.PngUnavailableError = PngUnavailableError;
+/** Family name the PNG variant of the SVG asks for; it matches the name inside the shipped font files. */
+exports.PNG_FONT_FAMILY = "Inter";
+const FONT_FILES = ["Inter-Regular.subset.ttf", "Inter-SemiBold.subset.ttf", "Inter-ExtraBold.subset.ttf"];
+/** Average advance of the shipped Inter weights is 0.46-0.50 em on card text and 0.58-0.61 on caps and digits; layout uses this (the system-font stack uses a wider 0.62). */
+exports.PNG_CHAR_EM = 0.58;
+exports.FONT_DIR = node_path_1.default.join(__dirname, "..", "..", "assets", "fonts");
+function detectInstallKind(dir = __dirname, hasPackageJson = (d) => node_fs_1.default.existsSync(node_path_1.default.join(d, "package.json"))) {
+    const hits = [...dir.matchAll(/[\\/]node_modules(?=[\\/]|$)/g)];
+    if (!hits.length)
+        return "source";
+    if (dir.split(/[\\/]+/).includes("_npx"))
+        return "npx";
+    // <something>/node_modules/prehello/dist/render -> <something> is a project (has package.json) for a local install,
+    // and a global prefix (<prefix>/lib or %APPDATA%\npm, no package.json) for `npm install -g`.
+    const holder = dir.slice(0, hits[hits.length - 1].index) || "/";
+    return hasPackageJson(holder) ? "local" : "global";
+}
+/**
+ * Printed (stderr) when PNG is asked for and the optional engine is missing. Same wording on Linux, macOS and Windows: npm commands
+ * are identical there. The detected install kind is marked, the other ways follow, and SVG is always offered.
+ */
+function pngUnavailableMessage(kind = "unknown") {
+    const here = (k) => (kind === k ? "   <- how this prehello was installed" : "");
+    return [
+        "PNG cards need the optional package @resvg/resvg-wasm, which is not installed here, so no card was written (everything else in this run completed normally).",
+        "Install it, then run the same command again:",
+        `  global install of prehello:  npm install -g @resvg/resvg-wasm${here("global")}`,
+        `  project install:             npm install @resvg/resvg-wasm   (run it in the project that has prehello in node_modules)${here("local")}`,
+        `  one-off with npx:            npx --package prehello --package @resvg/resvg-wasm -- prehello --card=card.png${here("npx")}`,
+        ...(kind === "source" ? ["  from a source checkout:      npm install   (in the prehello folder)   <- how this prehello is running"] : []),
+        "  if you installed with --omit=optional (or npm config optional=false), reinstall without it.",
+        "Or skip PNG: an SVG card needs no extra install, e.g. --card=card.svg (browsers and most image tools open it).",
+    ].join("\n");
+}
+/** Generic form of the message (install kind unknown). */
+exports.PNG_UNAVAILABLE_MESSAGE = pngUnavailableMessage();
+let engine;
+/** Loads the optional engine once. `resolver` exists so tests can simulate a missing dependency. */
+function loadEngine(resolver = require.resolve) {
+    if (engine)
+        return engine;
+    const p = (async () => {
+        let mod;
+        let wasmPath;
+        try {
+            wasmPath = resolver("@resvg/resvg-wasm/index_bg.wasm");
+            mod = require(resolver("@resvg/resvg-wasm"));
+        }
+        catch {
+            throw new PngUnavailableError(pngUnavailableMessage(detectInstallKind()));
+        }
+        try {
+            await mod.initWasm(node_fs_1.default.readFileSync(wasmPath));
+        }
+        catch (e) {
+            const msg = e.message;
+            // initWasm throws "Already initialized" when something else in the process initialised it: harmless.
+            if (!/already initialized/i.test(msg))
+                throw new PngUnavailableError(`PNG export could not start its WebAssembly renderer (${msg}). Reinstalling it may help: npm install @resvg/resvg-wasm. Or write an SVG instead: --card=card.svg`);
+        }
+        return mod;
+    })();
+    // a failed load is not cached when the caller injected a resolver (tests); the real one is cached either way
+    if (resolver === require.resolve)
+        engine = p;
+    return p;
+}
+/** Every glyph the card can print is in the font subset; anything else (never expected) becomes "?" rather than a tofu box. */
+function toFontSafeText(svg) {
+    return svg.replace(/[^\x09\x0a\x0d\x20-\x7e\u00a0-\u00ff\u2013\u2014\u2018\u2019\u201c\u201d\u2022\u2026\u2192\u2212\u2248\u2264\u2265]/gu, "?");
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function textChunk(keyword, text) {
+    const data = Buffer.concat([Buffer.from(keyword, "latin1"), Buffer.from([0]), Buffer.from(text, "latin1")]);
+    const body = Buffer.concat([Buffer.from("tEXt", "latin1"), data]);
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body));
+    return Buffer.concat([len, body, crc]);
+}
+/** Adds `Software` and `Description` tEXt chunks right after IHDR. This is how prehello recognises its own PNG before replacing it. */
+function tagPng(png, version) {
+    const ihdrEnd = 8 + 4 + 4 + 13 + 4; // signature + length + type + data + crc
+    return Buffer.concat([
+        png.subarray(0, ihdrEnd),
+        textChunk("Software", `prehello ${version}`),
+        textChunk("Description", "Share card generated locally by prehello. Token counts are estimates."),
+        png.subarray(ihdrEnd),
+    ]);
+}
+exports.PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Rasterises a card SVG (made with `fontFamily: PNG_FONT_FAMILY`) to a PNG buffer. Throws PngUnavailableError when the engine is missing. */
+async function svgToPng(svg, o) {
+    const { Resvg } = await loadEngine(o.resolver);
+    let fontBuffers;
+    try {
+        fontBuffers = FONT_FILES.map((f) => new Uint8Array(node_fs_1.default.readFileSync(node_path_1.default.join(exports.FONT_DIR, f))));
+    }
+    catch {
+        throw new PngUnavailableError("PNG export could not read prehello's bundled fonts (assets/fonts is missing from this install). Reinstall prehello, or write an SVG instead: --card=card.svg");
+    }
+    const width = Number(/<svg[^>]*\swidth="(\d+)"/.exec(svg)?.[1] ?? 1200);
+    try {
+        const r = new Resvg(toFontSafeText(svg), {
+            font: { fontBuffers, defaultFontFamily: exports.PNG_FONT_FAMILY, sansSerifFamily: exports.PNG_FONT_FAMILY },
+            fitTo: { mode: "width", value: width * o.scale },
+            textRendering: 1,
+            shapeRendering: 2,
+        });
+        try {
+            return tagPng(Buffer.from(r.render().asPng()), o.version);
+        }
+        finally {
+            r.free();
+        }
+    }
+    catch (e) {
+        // never a stack trace: a renderer failure is reported like a missing engine, and SVG keeps working
+        throw new PngUnavailableError(`PNG rendering failed (${String(e?.message ?? e).slice(0, 200)}). Write an SVG instead: --card=card.svg`);
+    }
+}