prehello 0.0.0-stage → 0.1.0

package/dist/render/terminal.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kinds = kinds;
+exports.headlineAgents = headlineAgents;
+exports.renderTerminal = renderTerminal;
+exports.renderRubric = renderRubric;
+const fmt_1 = require("../util/fmt");
+const redact_1 = require("../redact");
+const grade_1 = require("../analyze/grade");
+const MODE_TITLES = {
+    always: "ALWAYS ON before hello",
+    conditional: "CONDITIONAL (path/dir triggers)",
+    deferred: "DEFERRED (stub now, body on demand)",
+    "on-demand": "ON-DEMAND (only if invoked)",
+    unknown: "UNKNOWN LOAD BEHAVIOUR",
+};
+const LOOKED_FOR = [
+    ["Claude Code", "~/.claude, ~/.claude.json, `claude` on PATH; CLAUDE.md, .claude/, .mcp.json in the project"],
+    ["Cursor", "~/.cursor, Cursor.app, `cursor` on PATH; .cursor/, .cursorrules, AGENTS.md in the project"],
+    ["Codex", "~/.codex, `codex` on PATH; AGENTS.md, .codex/, .agents/skills in the project"],
+];
+const WHERE_LOOKED = {
+    "claude-code": "CLAUDE.md (project, parent folders, ~/.claude), .claude/{rules,skills,commands}, plugins, .mcp.json, ~/.claude.json",
+    cursor: ".cursor/rules (incl. nested), AGENTS.md, .cursorrules, skills folders, ~/.cursor/{skills,plugins,mcp.json}, .cursor/mcp.json",
+    codex: "AGENTS.md chain, ~/.codex/{AGENTS.md,config.toml}, .agents/skills, ~/.agents/skills, .codex/config.toml",
+};
+const AGENT_HINT = {
+    cursor: "Cursor's User Rules live inside the app, not on disk. Paste them into a file and run with --paste-user-rules <file> to count them.",
+};
+const KIND_NOUN = {
+    instructions: ["instruction file", "instruction files"],
+    rule: ["rule", "rules"],
+    memory: ["memory file", "memory files"],
+    "skills-listing": ["skills listing", "skills listings"],
+    "skill-body": ["skill body", "skill bodies"],
+    subagents: ["subagents listing", "subagents listings"],
+    "rule-description": ["rule description", "rule descriptions"],
+    "rule-body": ["rule body", "rule bodies"],
+    "mcp-server": ["MCP server entry", "MCP server entries"],
+    "user-rules": ["pasted user rules", "pasted user rules"],
+};
+function kinds(m) {
+    return Object.entries(m)
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+        .map(([k, n]) => `${n} ${(KIND_NOUN[k] ?? [k, k])[n === 1 ? 0 : 1]}`)
+        .join(", ");
+}
+function painter(on) {
+    const w = (open, close) => (s) => (on ? `\u001b[${open}m${s}\u001b[${close}m` : s);
+    return { bold: w(1, 22), dim: w(2, 22), red: w(31, 39), yellow: w(33, 39), green: w(32, 39), cyan: w(36, 39) };
+}
+function bar(frac, width) {
+    const full = Math.max(0, Math.min(width, frac * width));
+    const whole = Math.floor(full);
+    const half = full - whole >= 0.5 ? "▌" : "";
+    return "█".repeat(whole) + half;
+}
+function range(t) {
+    return `${(0, fmt_1.fmtTok)(t.low)}–${(0, fmt_1.fmtTok)(t.high)}`;
+}
+/** Summaries by agent for the one-line headline and the card agent choice. */
+function headlineAgents(r) {
+    return r.agents.filter((a) => !a.presentInRepoOnly);
+}
+function aggregate(items) {
+    const rows = new Map();
+    for (const it of items) {
+        const key = it.group && it.tokens ? `g:${it.group}` : `i:${it.id}`;
+        const cur = rows.get(key);
+        const t = it.tokens;
+        if (!cur) {
+            rows.set(key, { label: it.group && it.tokens ? it.groupLabel ?? it.group : it.label, detail: it.detail, tokens: t ? t.est : null, low: t?.low ?? 0, high: t?.high ?? 0, n: 1, notes: [...it.notes], unit: it.kind === "mcp-server" ? "servers" : "files" });
+        }
+        else {
+            cur.n++;
+            if (t) {
+                cur.tokens = (cur.tokens ?? 0) + t.est;
+                cur.low += t.low;
+                cur.high += t.high;
+            }
+        }
+    }
+    return [...rows.values()].sort((a, b) => (b.tokens ?? -1) - (a.tokens ?? -1));
+}
+function summaryBlock(r, shown, W, p, verbose) {
+    const out = [];
+    if (!shown.length)
+        return out;
+    out.push(p.bold("Measured vs. not measured (always-on items)"));
+    const nameW = Math.max(...shown.map((a) => a.name.length));
+    for (const a of shown) {
+        const c = a.coverage;
+        const total = c.alwaysMeasuredItems + c.alwaysUnmeasuredItems;
+        let line;
+        if (!total) {
+            const by = a.detectedBy.length ? ` (found via ${a.detectedBy.join(", ")})` : "";
+            line = `nothing that loads up front was found${by}`;
+        }
+        else {
+            line = `measured ${c.alwaysMeasuredItems} of ${total}${c.alwaysFraction !== null ? ` (${Math.round(c.alwaysFraction * 100)}%)` : ""}`;
+            if (c.alwaysMeasuredItems)
+                line += `: ${kinds(c.measuredKinds)}`;
+        }
+        out.push(...(0, fmt_1.wrap)(line, W, "  " + a.name.padEnd(nameW) + "  ", " ".repeat(nameW + 6)));
+        if (c.alwaysUnmeasuredItems) {
+            const names = a.mcpServers.filter((m) => !m.measured).map((m) => m.name);
+            const parts = [kinds(c.unmeasuredKinds)];
+            const nm = names.length ? ` (${names.slice(0, 4).join(", ")}${names.length > 4 ? `, +${names.length - 4} more` : ""})` : "";
+            out.push(...(0, fmt_1.wrap)(`NOT measured: ${parts.join("")}${c.unmeasuredKinds["mcp-server"] ? nm : ""}; no token count, never shown as 0`, W, " ".repeat(nameW + 4), " ".repeat(nameW + 6)).map((l) => p.yellow(l)));
+        }
+    }
+    const all = shown.flatMap((a) => a.offenders.map((x) => ({ ...x, name: a.name, always: a.totals.always.est })));
+    all.sort((a, b) => b.tokens - a.tokens);
+    const top = all.slice(0, verbose ? 10 : 5);
+    if (top.length >= 3) {
+        out.push("");
+        out.push(p.bold("Top offenders (always on, estimates)"));
+        const multi = shown.length > 1;
+        const maxTok = Math.max(1, top[0].tokens);
+        top.forEach((x, i) => {
+            const lbl = (0, fmt_1.sanitize)(x.label, 200) + (multi ? `  [${x.name}]` : "");
+            const share = x.always ? (x.tokens / x.always) * 100 : 0;
+            out.push(`  ${String(i + 1).padStart(2)}. ${(0, fmt_1.shortenLabel)(lbl, 46).padEnd(46)} ${(0, fmt_1.fmtInt)(x.tokens).padStart(7)} ${(0, fmt_1.fmtPct)(share).padStart(6)}  ${p.cyan(bar(x.tokens / maxTok, 12))}`);
+        });
+    }
+    out.push("");
+    return out;
+}
+/**
+ * "What to cut": the actionable version of the headline. Skills, plugins and MCP servers are the part of the always-on cost
+ * you can remove with one click, so say how big that part is and what removing the top few would save. All estimates.
+ */
+function cutBlock(shown, window, W, p) {
+    const rows = shown.filter((a) => a.savings);
+    if (!rows.length)
+        return [];
+    const out = [p.bold("What to cut (estimates)")];
+    const nameW = Math.max(...rows.map((a) => a.name.length));
+    for (const a of rows) {
+        const sv = a.savings;
+        const always = a.totals.always.est;
+        const lead = `  ${a.name.padEnd(nameW)}  `;
+        const pad = " ".repeat(nameW + 4);
+        out.push(...(0, fmt_1.wrap)(`skills, plugins and MCP servers add ~${(0, fmt_1.fmtTok)(sv.groupsTokens)} tokens before hello: ${(0, fmt_1.fmtPct)((sv.groupsTokens / always) * 100)} of the measured always-on total, in ${sv.groupsCount} group${sv.groupsCount > 1 ? "s" : ""}.`, W, lead, pad));
+        out.push(...(0, fmt_1.wrap)(`Top ${sv.n} group${sv.n > 1 ? "s" : ""} = ${(0, fmt_1.fmtPct)(sv.pctOfGroups)} of that. Removing ${sv.n > 1 ? "them" : "it"} would save about ${(0, fmt_1.fmtTok)(sv.topTokens)} tokens (${(0, fmt_1.fmtPct)(sv.pctOfWindow)} of a ${(0, fmt_1.fmtWindow)(window)} window); estimate, not a promise.`, W, pad, pad));
+        sv.top.forEach((c, i) => {
+            const cnt = c.kind === "skills" && c.count > 1 && c.label.startsWith("plugin ") ? ` (${c.count} skills)` : "";
+            const lbl = (0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(c.label + cnt, 200), Math.max(20, W - nameW - 30)).padEnd(Math.max(20, W - nameW - 30));
+            out.push(`${pad}${String(i + 1).padStart(2)}. ${lbl} ${("~" + (0, fmt_1.fmtTok)(c.tokens)).padStart(7)}  ${(0, fmt_1.fmtPct)((c.tokens / always) * 100).padStart(5)}`);
+        });
+        if (a.lowerBound)
+            out.push(p.dim(`${pad}(always-on is a lower bound: unmeasured items are not counted here)`));
+    }
+    out.push("");
+    return out;
+}
+function mcpTail(servers) {
+    const un = servers.filter((m) => !m.measured).length;
+    if (!un)
+        return "; sizes come from prehello's measured catalog (version-specific, ballpark)";
+    if (un === servers.length)
+        return "; tool-schema size unknown (not in the catalog, no server is started)";
+    return `; ${servers.length - un} sized from the measured catalog, ${un} unknown (never shown as 0)`;
+}
+function renderTerminal(r, o) {
+    const p = painter(o.color);
+    const W = Math.max(64, Math.min(o.width, 100));
+    const out = [];
+    const dp = (x) => (0, redact_1.displayPath)(x, { cwd: o.cwd, home: o.home });
+    const win = (0, fmt_1.fmtWindow)(r.scan.window);
+    const shown = headlineAgents(r);
+    out.push(`${p.bold("prehello " + r.tool.version)} · ${dp(r.scan.cwd) === "." ? "this folder" : (0, fmt_1.shortenLeft)((0, fmt_1.sanitize)(dp(r.scan.cwd), 400), 60)} + user config · window ${win}`);
+    out.push(...(0, fmt_1.wrap)(`Token counts are ESTIMATES (${r.scan.tokenizer.method === "bpe-o200k" ? "o200k BPE with per-agent scaling priors" : "chars/3.5 heuristic"}), shown with ~. Not exact for any model.`, W).map((l) => p.dim(l)));
+    out.push("");
+    if (r.agents.length === 0) {
+        out.push(`No coding agents detected on this machine, and no agent files found in ${dp(r.scan.cwd) === "." ? "this folder" : dp(r.scan.cwd)}.`);
+        out.push("");
+        out.push(p.bold("prehello looked for"));
+        for (const [n, t] of LOOKED_FOR)
+            out.push(...(0, fmt_1.wrap)(t, W, `  ${n.padEnd(12)} `, " ".repeat(15)));
+        out.push("");
+        out.push(p.bold("Try"));
+        out.push("  prehello ~/code/my-project       scan a project folder (default: the current directory)");
+        out.push("  prehello --agent claude-code     treat an agent as in use, to see what it WOULD load");
+        out.push("  prehello --help                  all options");
+        out.push("");
+        out.push(p.dim("Nothing was measured. This is not a score of 0: absence of data is never shown as 0."));
+        out.push(...tail(r, o, p, W, false, true));
+        return out.join("\n") + "\n";
+    }
+    // one-line summary
+    const sum = shown
+        .map((a) => {
+        const t = a.totals.always;
+        if (!t.measuredItems)
+            return t.unmeasuredItems ? `${a.name} tokens unmeasured` : `${a.name} nothing found`;
+        return `${a.name} ${a.lowerBound ? "≥ " : ""}~${(0, fmt_1.fmtTok)(t.est)} tokens`;
+    })
+        .join(" · ");
+    if (sum)
+        out.push(...(0, fmt_1.wrap)("Before your first message: " + sum, W, "", "  ").map((l, i) => (i === 0 ? p.bold(l.slice(0, 27)) + l.slice(27) : l)));
+    out.push("");
+    out.push(...cutBlock(shown, r.scan.window, W, p));
+    out.push(...summaryBlock(r, shown, W, p, o.verbose));
+    if (o.quiet) {
+        out.push(...tail(r, { ...o, verbose: false }, p, W, true));
+        return out.join("\n") + "\n";
+    }
+    for (const a of r.agents) {
+        if (a.presentInRepoOnly) {
+            out.push(...(0, fmt_1.wrap)(`── ${a.name}: agent files exist in this repo but ${a.name} was not found on this machine; excluded from headline and card (use --agent ${a.id} to include).`, W, "", "   ").map((l) => p.dim(l)));
+            out.push("");
+            continue;
+        }
+        const grade = a.grade ? `  Grade ${a.grade.letter}${a.grade.provisional ? (a.grade.cappedAt ? " (provisional, capped)" : " (provisional)") : ""}` : "";
+        const head = `── ${a.name} `;
+        out.push(p.bold(head + "─".repeat(Math.max(2, W - head.length - grade.length))) + (a.grade ? p.bold(grade) : ""));
+        out.push(...(0, fmt_1.wrap)(`estimate model: ${a.profile.label}; band ${a.profile.band}`, W, "   ", "      ").map((l) => p.dim(l)));
+        for (const mode of ["always", "conditional", "deferred", "on-demand", "unknown"]) {
+            const items = a.items.filter((i) => i.loadMode === mode);
+            if (!items.length)
+                continue;
+            const t = a.totals[mode];
+            const lower = mode === "always" ? (a.lowerBound ? "≥ " : "") : t.unmeasuredItems > 0 ? "≥ " : "";
+            let line;
+            if (!t.measuredItems)
+                line = `${p.bold(MODE_TITLES[mode])}   unmeasured only (${t.unmeasuredItems} item${t.unmeasuredItems > 1 ? "s" : ""}) — NOT zero`;
+            else {
+                line = `${p.bold(MODE_TITLES[mode])}   ${lower}~${(0, fmt_1.fmtTok)(t.est)} tokens (${range(t)})`;
+                if (mode === "always" && a.percentOfWindowAlways !== null)
+                    line += `  ≈ ${(0, fmt_1.fmtPct)(a.percentOfWindowAlways)} of ${win}`;
+                if (t.unmeasuredItems)
+                    line += p.yellow(`  + ${t.unmeasuredItems} unmeasured`);
+            }
+            out.push(line);
+            const rows = aggregate(items);
+            const limit = o.verbose || mode !== "always" ? (mode === "always" ? 50 : 6) : 8;
+            const maxTok = Math.max(1, ...rows.map((x) => x.tokens ?? 0));
+            const barW = W >= 96 ? 20 : 12;
+            const labelW = Math.min(Math.max(30, W - 24 - barW), Math.max(...rows.map((x) => (x.label + (x.detail ? " " + x.detail : "") + (x.n > 1 ? ` (${x.n} ${x.unit})` : "")).length), 10));
+            const measuredRows = rows.filter((x) => x.tokens !== null);
+            const unmeasuredRows = rows.filter((x) => x.tokens === null).slice(0, o.verbose ? 40 : 5);
+            for (const row of [...measuredRows.slice(0, limit), ...unmeasuredRows]) {
+                let lbl = row.label + (row.detail ? " " + row.detail : "") + (row.n > 1 ? ` (${row.n} ${row.unit})` : "");
+                lbl = (0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(lbl, 300), labelW).padEnd(labelW);
+                if (row.tokens === null)
+                    out.push(`   ${lbl}  ${p.yellow("unmeasured".padStart(9))}`);
+                else {
+                    const share = t.est ? (row.tokens / t.est) * 100 : 0;
+                    out.push(`   ${lbl}  ${(0, fmt_1.fmtInt)(row.tokens).padStart(9)}  ${(0, fmt_1.fmtPct)(share).padStart(6)}  ${p.cyan(bar(row.tokens / maxTok, barW))}`);
+                }
+            }
+            if (measuredRows.length > limit)
+                out.push(p.dim(`   … ${measuredRows.length - limit} more (use --verbose)`));
+            const unmTotal = rows.filter((x) => x.tokens === null).length;
+            if (unmTotal > unmeasuredRows.length)
+                out.push(p.dim(`   … ${unmTotal - unmeasuredRows.length} more unmeasured (use --verbose)`));
+            if (o.verbose) {
+                for (const it of items)
+                    for (const n of it.notes)
+                        out.push(...(0, fmt_1.wrap)(`· ${(0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(it.label, 300), 50)}: ${(0, fmt_1.sanitize)(n, 300)}`, W, "     ", "       ").map((l) => p.dim(l)));
+                const unm = items.filter((i) => i.tokens === null);
+                for (const it of unm)
+                    out.push(...(0, fmt_1.wrap)(`· ${(0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(it.label, 300), 50)} unmeasured: ${it.unmeasuredReason}`, W, "     ", "       ").map((l) => p.dim(l)));
+            }
+        }
+        if (a.gradeNote)
+            out.push(p.dim(`   ${a.gradeNote}`));
+        if (!a.items.length) {
+            const by = a.detectedBy.length ? ` (via ${a.detectedBy.join(", ")})` : "";
+            out.push(p.bold(`   ${a.name} is installed${by}, but nothing that loads before hello was found.`));
+            out.push(...(0, fmt_1.wrap)(`This is NOT a score of 0 and NOT proof the agent loads nothing: it still loads its own system prompt and tools. Looked in: ${WHERE_LOOKED[a.id]}.`, W, "   ", "   ").map((l) => p.dim(l)));
+            if (AGENT_HINT[a.id])
+                out.push(...(0, fmt_1.wrap)(AGENT_HINT[a.id], W, "   ", "   ").map((l) => p.dim(l)));
+        }
+        if (a.mcpServers.length) {
+            const names = a.mcpServers.map((m) => m.name);
+            const shownN = names.slice(0, o.verbose ? 40 : 8).join(", ");
+            out.push(...(0, fmt_1.wrap)(`MCP servers configured (${a.mcpServers.length}): ${shownN}${names.length > (o.verbose ? 40 : 8) ? `, +${names.length - (o.verbose ? 40 : 8)} more` : ""}${mcpTail(a.mcpServers)}`, W, "   ", "      ").map((l) => p.dim(l)));
+        }
+        out.push(...(0, fmt_1.wrap)("not measurable from disk: " + a.unmeasuredBanner.join(" · "), W, "   ", "      ").map((l) => p.dim(l)));
+        out.push("");
+    }
+    out.push(...tail(r, o, p, W));
+    return out.join("\n") + "\n";
+}
+function tail(r, o, p, W, compact = false, firstRun = false) {
+    const out = [];
+    if (!compact && r.findings.length) {
+        out.push(p.bold(`Findings (${r.findings.length})`));
+        for (const f of r.findings.slice(0, o.verbose ? 100 : 10)) {
+            const sav = f.savingsTokens ? `  −~${(0, fmt_1.fmtInt)(f.savingsTokens)} tokens` : "";
+            out.push(...(0, fmt_1.wrap)((0, fmt_1.sanitize)(f.message, 400) + sav, W - 3, ` ${f.severity === "warn" ? p.yellow("⚠") : "ℹ"} `, "   "));
+        }
+        if (r.findings.length > 10 && !o.verbose)
+            out.push(p.dim(`   … ${r.findings.length - 10} more (use --verbose)`));
+        const total = r.findings.reduce((s, f) => s + (f.savingsTokens ?? 0), 0);
+        if (total)
+            out.push(p.dim(` Potential always-on savings (estimate): ~${(0, fmt_1.fmtInt)(total)} tokens. Run --fix for the plan; nothing is changed automatically.`));
+        out.push("");
+    }
+    if (r.scan.fixturesSkipped) {
+        const n = r.scan.fixturesSkipped;
+        out.push(...(0, fmt_1.wrap)(`ℹ Skipped ${n} fixture folder${n > 1 ? "s" : ""} with agent files (use --include-fixtures).`, W, " ", "   ").map((l) => p.dim(l)));
+        out.push("");
+    }
+    if (!compact && o.verbose && r.excluded.length) {
+        out.push(p.bold(`Not loaded / ignored (${r.excluded.length})`));
+        for (const e of r.excluded)
+            out.push(...(0, fmt_1.wrap)(`${e.agent}: ${(0, redact_1.displayPath)(e.path, { cwd: o.cwd, home: o.home })} — ${(0, fmt_1.sanitize)(e.reason, 200)}`, W, "   ", "      "));
+        out.push("");
+    }
+    if (r.warnings.length) {
+        out.push(p.yellow(`Partial results (${r.warnings.length} source${r.warnings.length > 1 ? "s" : ""} skipped):`));
+        for (const w of r.warnings)
+            out.push(...(0, fmt_1.wrap)((0, fmt_1.sanitize)(w, 300), W, "   ", "      "));
+        out.push("");
+    }
+    if (!compact && !firstRun) {
+        out.push(...(0, fmt_1.wrap)("Never measured: " + r.notMeasurable.join("; ") + ".", W).map((l) => p.dim(l)));
+        const g = r.agents.filter((a) => a.grade).sort((a, b) => (b.totals.always.est - a.totals.always.est))[0];
+        if (g?.grade)
+            out.push(...(0, fmt_1.wrap)(`Context Grade (${g.name}): ${g.grade.letter}${g.grade.provisional ? (g.grade.cappedAt ? ` (provisional, capped at ${g.grade.cappedAt}: some always-loaded items are unmeasured)` : " (provisional: some always-loaded items are unmeasured)") : ""} — heuristic, not a standard. See: prehello explain grade`, W).map((l) => p.dim(l)));
+    }
+    return out;
+}
+function renderRubric() {
+    return ["Context Grade rubric", "", ...grade_1.RUBRIC.map((l) => "• " + l)].join("\n") + "\n";
+}

package/dist/render/treemap.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.squarify = squarify;
+/** Squarified treemap (Bruls et al.). Input values must be > 0; output order follows descending value. */
+function squarify(values, x, y, w, h) {
+    const total = values.reduce((a, b) => a + b, 0);
+    const out = [];
+    if (total <= 0 || w <= 0 || h <= 0)
+        return out;
+    const scale = (w * h) / total;
+    let rem = values.map((v, i) => ({ a: v * scale, i })).sort((p, q) => q.a - p.a);
+    let cx = x, cy = y, cw = w, ch = h;
+    const worst = (row, side) => {
+        const s = row.reduce((t, r) => t + r.a, 0);
+        const mx = Math.max(...row.map((r) => r.a));
+        const mn = Math.min(...row.map((r) => r.a));
+        return Math.max((side * side * mx) / (s * s), (s * s) / (side * side * mn));
+    };
+    while (rem.length) {
+        const side = Math.min(cw, ch);
+        let row = [rem[0]];
+        let k = 1;
+        while (k < rem.length) {
+            const cand = [...row, rem[k]];
+            if (worst(cand, side) <= worst(row, side)) {
+                row = cand;
+                k++;
+            }
+            else
+                break;
+        }
+        const s = row.reduce((t, r) => t + r.a, 0);
+        if (cw >= ch) {
+            const colW = s / ch;
+            let yy = cy;
+            for (const r of row) {
+                const hh = r.a / colW;
+                out.push({ x: cx, y: yy, w: colW, h: hh, i: r.i });
+                yy += hh;
+            }
+            cx += colW;
+            cw -= colW;
+        }
+        else {
+            const rowH = s / cw;
+            let xx = cx;
+            for (const r of row) {
+                const ww = r.a / rowH;
+                out.push({ x: xx, y: cy, w: ww, h: rowH, i: r.i });
+                xx += ww;
+            }
+            cy += rowH;
+            ch -= rowH;
+        }
+        rem = rem.slice(row.length);
+    }
+    return out;
+}

package/dist/safe-write.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MD_MARKER_PREFIX = exports.SafeWriteError = void 0;
+exports.looksLikePrehelloOutput = looksLikePrehelloOutput;
+exports.describeWriteError = describeWriteError;
+exports.safeWrite = safeWrite;
+/**
+ * Safe output files for --json=<file>, --card=<file>, --markdown=<file> and --sarif=<file>.
+ * Rules: never write through a symlink; only replace a regular file that is a previous prehello output
+ * (or anything, with --force); never follow a link swapped in between the check and the open (O_NOFOLLOW + fstat identity check).
+ * Together with src/cli.ts, this is the only place that writes to disk, and the static test allowlists exactly these two files.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const platform_1 = require("./platform");
+class SafeWriteError extends Error {
+}
+exports.SafeWriteError = SafeWriteError;
+/** First line of a markdown report written to a file. An HTML comment: invisible when the file is rendered or pasted into GitHub. */
+exports.MD_MARKER_PREFIX = "<!-- generated by prehello ";
+/** True when the first bytes look like something prehello itself wrote. */
+function looksLikePrehelloOutput(headRaw, kind) {
+    // a Windows editor may have re-saved our file with a UTF-8 BOM (as "\ufeff", or as its three latin1 bytes): still ours
+    const head = kind === "png" ? headRaw : headRaw.replace(/^(?:\ufeff|\u00ef\u00bb\u00bf)/, "");
+    if (kind === "md")
+        return head.startsWith(exports.MD_MARKER_PREFIX);
+    // `head` is decoded as latin1, so a PNG's bytes survive: signature, then the tEXt "Software: prehello" chunk tagPng() adds right after IHDR.
+    if (kind === "png")
+        return head.startsWith("\u0089PNG\r\n\u001a\n") && /tEXtSoftware\u0000prehello /.test(head);
+    if (kind === "svg")
+        return /^\s*(<\?xml[^>]*>\s*)?<svg[\s>]/.test(head) && /Generated by prehello /.test(head);
+    if (kind === "sarif")
+        return /^\s*\{/.test(head) && /"version":\s*"2\.1\.0"/.test(head) && /"driver":\s*\{\s*"name":\s*"prehello"/.test(head);
+    return /^\s*\{/.test(head) && /"tool":\s*\{\s*"name":\s*"prehello"/.test(head);
+}
+/** Friendly text for the errors a Windows (or any) user actually hits when the target is busy, read-only or in a missing folder. */
+function describeWriteError(code) {
+    switch (code) {
+        case "ENOENT": return "the folder does not exist (create it first)";
+        case "EACCES":
+        case "EPERM": return "permission denied (read-only file or folder, or another program such as an editor, sync client or antivirus holds it)";
+        case "EBUSY": return "the file is in use by another program; close it and try again";
+        case "EISDIR": return "that name is a folder";
+        case "ENOSPC": return "the disk is full";
+        case "ENAMETOOLONG": return "the path is too long";
+        default: return code ?? "error";
+    }
+}
+function safeWrite(abs, content, opts) {
+    if ((opts.platform ?? process.platform) === "win32") {
+        if ((0, platform_1.isWindowsReservedName)(abs))
+            throw new SafeWriteError("that is a reserved Windows device name (CON, NUL, COM1, ...); pick another file name");
+        if ((0, platform_1.hasWindowsStream)(abs))
+            throw new SafeWriteError("a ':' in the file name would create a hidden NTFS data stream; pick another file name");
+    }
+    let st = null;
+    let identity = null;
+    try {
+        st = node_fs_1.default.lstatSync(abs);
+        identity = node_fs_1.default.lstatSync(abs, { bigint: true });
+    }
+    catch (e) {
+        const code = e.code;
+        if (code !== "ENOENT")
+            throw new SafeWriteError(describeWriteError(code));
+    }
+    if (st) {
+        if (st.isSymbolicLink())
+            throw new SafeWriteError("it is a symlink; prehello never writes through symlinks (remove the link or pick another name)");
+        if (!st.isFile())
+            throw new SafeWriteError("it exists and is not a regular file");
+        if (!opts.force) {
+            if (st.nlink > 1)
+                throw new SafeWriteError("it has other hard links; use --force to write anyway");
+            let head = "";
+            try {
+                const fd = node_fs_1.default.openSync(abs, node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NOFOLLOW ?? 0));
+                try {
+                    const buf = Buffer.alloc(4096);
+                    head = buf.toString("latin1", 0, node_fs_1.default.readSync(fd, buf, 0, buf.length, 0));
+                }
+                finally {
+                    node_fs_1.default.closeSync(fd);
+                }
+            }
+            catch {
+                throw new SafeWriteError("it exists and could not be checked; use --force to replace it");
+            }
+            if (!looksLikePrehelloOutput(head, opts.kind))
+                throw new SafeWriteError("it exists and was not written by prehello; use --force to replace it");
+        }
+    }
+    const C = node_fs_1.default.constants;
+    const flags = C.O_WRONLY | C.O_CREAT | (C.O_NOFOLLOW ?? 0) | (st ? 0 : C.O_EXCL);
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(abs, flags, 0o644);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ELOOP" || code === "EEXIST")
+            throw new SafeWriteError("the path changed while writing (symlink or new file); nothing was written");
+        throw new SafeWriteError(describeWriteError(code));
+    }
+    try {
+        // bigint: NTFS file ids do not fit in a double, two different files could otherwise compare equal
+        const now = node_fs_1.default.fstatSync(fd, { bigint: true });
+        if (!now.isFile() || (st && (now.ino !== (identity?.ino ?? 0n) || now.dev !== (identity?.dev ?? 0n))))
+            throw new SafeWriteError("the file changed while writing; nothing was written");
+        node_fs_1.default.ftruncateSync(fd, 0);
+        const buf = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+        for (let off = 0; off < buf.length;)
+            off += node_fs_1.default.writeSync(fd, buf, off, buf.length - off);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}

package/dist/scan.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_MEASURABLE = exports.VERSION = void 0;
+exports.scan = scan;
+const fs_safe_1 = require("./fs-safe");
+const context_1 = require("./context");
+const fmt_1 = require("./util/fmt");
+const counter_1 = require("./tokens/counter");
+const model_1 = require("./model");
+const claude_code_1 = require("./adapters/claude-code");
+const cursor_1 = require("./adapters/cursor");
+const codex_1 = require("./adapters/codex");
+const totals_1 = require("./analyze/totals");
+const findings_1 = require("./analyze/findings");
+const grade_1 = require("./analyze/grade");
+const savings_1 = require("./analyze/savings");
+const summary_1 = require("./analyze/summary");
+exports.VERSION = "0.1.0";
+const ADAPTERS = {
+    "claude-code": { detect: claude_code_1.detectClaude, discover: claude_code_1.discoverClaude },
+    cursor: { detect: cursor_1.detectCursor, discover: cursor_1.discoverCursor },
+    codex: { detect: codex_1.detectCodex, discover: codex_1.discoverCodex },
+};
+exports.NOT_MEASURABLE = [
+    "the agent's built-in system prompt and built-in tool definitions",
+    "server-side / org rules, Cursor User & Team Rules, claude.ai connectors",
+    "MCP servers whose tools are only known at runtime (no server is started by default)",
+    "files outside the scanned locations; anything the agent injects dynamically (hooks, memory/RAG plugins)",
+];
+function scan(input) {
+    // Canonicalise once: on case-insensitive filesystems (macOS APFS default, Windows) `~/Projects/Foo` and
+    // `~/projects/foo` are the same directory, and every containment / ceiling / duplicate check below compares strings.
+    const opts = { ...input, cwd: (0, fs_safe_1.realpathOrSelf)(input.cwd), home: (0, fs_safe_1.realpathOrSelf)(input.home), ceiling: input.ceiling ? (0, fs_safe_1.realpathOrSelf)(input.ceiling) : undefined };
+    const counter = (0, counter_1.makeCounter)(opts.tokenizer);
+    const ctx = new context_1.Ctx(opts, counter);
+    const forced = opts.agents && opts.agents.length ? opts.agents : undefined;
+    const agents = [];
+    for (const id of model_1.ALL_AGENTS) {
+        if (forced && !forced.includes(id))
+            continue;
+        const ad = ADAPTERS[id];
+        const det = ad.detect(ctx);
+        const inUse = !!forced || det.detectedBy.length > 0;
+        const repoOnly = !inUse && det.repoFiles.length > 0;
+        if (!inUse && !repoOnly)
+            continue;
+        const res = ad.discover(ctx);
+        const rank = { always: 0, conditional: 1, deferred: 2, "on-demand": 3, unknown: 4 };
+        const items = [...res.items].sort((a, b) => rank[a.loadMode] - rank[b.loadMode] || (b.tokens?.est ?? -1) - (a.tokens?.est ?? -1) || (0, fmt_1.cmp)(a.label, b.label));
+        const totals = (0, totals_1.sumTotals)(items);
+        const prof = ctx.profile(id);
+        agents.push({
+            id,
+            name: model_1.AGENT_NAMES[id],
+            detected: inUse,
+            detectedBy: forced ? ["--agent"] : det.detectedBy,
+            presentInRepoOnly: repoOnly,
+            profile: { id: prof.id, label: prof.label, band: prof.band },
+            items,
+            totals,
+            percentOfWindowAlways: totals.always.measuredItems ? (totals.always.est / opts.window) * 100 : null,
+            unmeasuredBanner: res.unmeasuredBanner,
+            grade: null,
+            lowerBound: totals.always.unmeasuredItems > 0 || !!ctx.budgetHit,
+            savings: totals.always.measuredItems ? (0, savings_1.savingsOf)(items, totals.always.est, opts.window) : null,
+            coverage: (0, summary_1.coverageOf)(id, items),
+            offenders: (0, summary_1.offendersOf)(id, items),
+            mcpServers: (0, summary_1.mcpServersOf)(items),
+        });
+    }
+    const budgetNote = ctx.budgetSummary();
+    if (budgetNote) {
+        ctx.warn(budgetNote);
+        for (const a of agents)
+            a.lowerBound = true;
+    }
+    (0, findings_1.crossFindings)(ctx, agents);
+    const visible = new Set(agents.filter((a) => !a.presentInRepoOnly).map((a) => a.id));
+    const findings = (0, findings_1.rankFindings)(ctx.findings.filter((f) => f.agent === "all" || visible.has(f.agent)));
+    if (!opts.noGrade) {
+        for (const a of agents) {
+            if (a.presentInRepoOnly)
+                continue;
+            if (a.totals.always.measuredItems > 0)
+                a.grade = (0, grade_1.gradeAgent)(a, findings, opts.window);
+            else
+                a.gradeNote = a.totals.always.unmeasuredItems > 0 ? "no grade: everything that loads up front is unmeasured" : "no grade: nothing that loads up front was found";
+        }
+    }
+    const epoch = opts.env.SOURCE_DATE_EPOCH;
+    const when = epoch && /^\d+$/.test(epoch) ? new Date(parseInt(epoch, 10) * 1000) : opts.now;
+    return {
+        schemaVersion: model_1.SCHEMA_VERSION,
+        tool: { name: "prehello", version: exports.VERSION },
+        generatedAt: when.toISOString(),
+        scan: { cwd: opts.cwd, window: opts.window, tokenizer: { method: counter.method, note: counter.note }, claudeProfile: opts.claudeProfile, ...(ctx.fixturesSkipped > 0 ? { fixturesSkipped: ctx.fixturesSkipped } : {}) },
+        agents,
+        excluded: ctx.excluded.filter((e) => e.agent === "all" || visible.has(e.agent)),
+        findings,
+        warnings: [...ctx.warnings],
+        notMeasurable: exports.NOT_MEASURABLE,
+        ...(ctx.budgetHit ? { partial: { reason: ctx.budgetHit, filesNotRead: ctx.budgetSkipped } } : {}),
+    };
+}

package/dist/spec.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSpec = loadSpec;
+exports.loadBundledCatalogPath = loadBundledCatalogPath;
+exports.evidenceFor = evidenceFor;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SPEC_DIR = node_path_1.default.join(__dirname, "..", "spec");
+const cache = new Map();
+function loadSpec(agent) {
+    let s = cache.get(agent);
+    if (!s) {
+        s = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(SPEC_DIR, `${agent}.json`), "utf8"));
+        cache.set(agent, s);
+    }
+    return s;
+}
+function loadBundledCatalogPath() {
+    return node_path_1.default.join(SPEC_DIR, "mcp-weights.json");
+}
+function evidenceFor(agent, doc) {
+    const s = loadSpec(agent);
+    return { docUrl: s.docs[doc] ?? Object.values(s.docs)[0], verifiedAt: s.verifiedAt };
+}