prehello 0.0.0-stage → 0.1.0

package/dist/context.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ctx = exports.WALK_CANDIDATES = void 0;
+exports.readFailWhy = readFailWhy;
+exports.lineCount = lineCount;
+exports.shingles = shingles;
+exports.jaccard = jaccard;
+const node_path_1 = __importDefault(require("node:path"));
+const families_1 = require("./tokens/families");
+const fs_safe_1 = require("./fs-safe");
+const redact_1 = require("./redact");
+const fmt_1 = require("./util/fmt");
+const fixtures_1 = require("./fixtures");
+/** Entry budget for looking inside skipped fixture folders (only to count how many held agent files; nothing from them is reported). */
+const FIXTURE_PROBE_ENTRIES = 20_000;
+const FIXTURE_PROBE_TOTAL = 50_000;
+/** Human wording for a failed read; `verb` is "skipped" (rules, skills) or "not read" (instruction files). */
+function readFailWhy(reason, verb) {
+    switch (reason) {
+        case "too-large": return `larger than 4 MiB (Claude Code's own limit for startup files), ${verb}`;
+        case "binary": return `binary content, ${verb}`;
+        case "utf16": return `saved as UTF-16 (Windows PowerShell "> file" does this); coding agents read UTF-8, so it is ${verb}. Re-save it as UTF-8`;
+        case "symlink-escape": return `symlink points outside the project, ${verb === "skipped" ? "skipped" : "not followed"}`;
+        case "not-file": return `not a regular file, ${verb}`;
+        case "budget": return `${verb}: scan budget reached`;
+        default: return reason === "unreadable" ? `unreadable, ${verb}` : `${reason}, ${verb}`;
+    }
+}
+/** Names (files) and "dir/" entries looked for in every directory of the bounded project walk. */
+exports.WALK_CANDIDATES = [
+    "CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md", "AGENTS.md", "AGENTS.override.md",
+    ".cursor/rules/", ".cursor/skills/", ".agents/skills/", ".claude/skills/",
+];
+class Ctx {
+    opts;
+    counter;
+    warnings = [];
+    excluded = [];
+    findings = [];
+    docs = new Map(); // realpath -> info (for F2)
+    gitRoot;
+    seq = 0;
+    readCache = new Map();
+    findingKeys = new Set();
+    countCache = new Map();
+    walkCache;
+    /** Fixture folders skipped by the project walk that held agent files (counted, never read). */
+    fixturesSkipped = 0;
+    t0;
+    bytesRead = 0;
+    /** Set when a whole-scan budget (bytes or time) stopped reading; totals are then lower bounds. */
+    budgetHit;
+    budgetSkipped = 0;
+    constructor(opts, counter) {
+        this.opts = opts;
+        this.counter = counter;
+        this.gitRoot = (0, fs_safe_1.findGitRoot)(opts.cwd, opts.ceiling);
+        this.t0 = (opts.clock ?? Date.now)();
+    }
+    get maxScanBytes() {
+        return this.opts.maxScanBytes ?? fs_safe_1.DEFAULT_MAX_SCAN_BYTES;
+    }
+    get maxScanMs() {
+        return this.opts.maxScanMs ?? fs_safe_1.DEFAULT_MAX_SCAN_MS;
+    }
+    timeUp() {
+        if (this.budgetHit === "time")
+            return true;
+        if ((this.opts.clock ?? Date.now)() - this.t0 > this.maxScanMs) {
+            this.budgetHit = this.budgetHit ?? "time";
+            return true;
+        }
+        return false;
+    }
+    /** Is cwd a project folder (as opposed to a home directory, a drive root or a downloads folder)? .git, or an agent file at its top level. Never true for the home folder. */
+    isProjectDir() {
+        if (this.cwd === this.home)
+            return false;
+        if (this.gitRoot && this.gitRoot !== this.home)
+            return true;
+        const top = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", ".cursorrules", ".mcp.json"];
+        if (top.some((f) => (0, fs_safe_1.isFile)(node_path_1.default.join(this.cwd, f))))
+            return true;
+        return [".claude", ".cursor", ".codex", ".agents"].some((d) => (0, fs_safe_1.isDir)(node_path_1.default.join(this.cwd, d)));
+    }
+    get cwd() {
+        return this.opts.cwd;
+    }
+    get home() {
+        return this.opts.home;
+    }
+    profile(agent) {
+        return (0, families_1.profileFor)(agent, this.counter.method, this.opts.claudeProfile);
+    }
+    display(p) {
+        return (0, redact_1.displayPath)(p, { cwd: this.cwd, home: this.home });
+    }
+    warn(msg) {
+        if (!this.warnings.includes(msg))
+            this.warnings.push(msg);
+    }
+    exclude(agent, p, reason) {
+        this.excluded.push({ agent, path: p, reason });
+    }
+    /** A machine-wide absolute location, re-rooted under --system-root when given. */
+    sys(abs) {
+        const root = this.opts.systemRoot;
+        if (!root)
+            return abs;
+        const rel = abs.replace(/^[A-Za-z]:/, "").replace(/\\/g, "/").replace(/^\/+/, "");
+        return node_path_1.default.join(root, ...rel.split("/"));
+    }
+    /** Directories from filesystem root (or ceiling) down to cwd, root-first. */
+    ancestorDirs() {
+        const dirs = [];
+        let dir = this.cwd;
+        for (;;) {
+            dirs.unshift(dir);
+            if (this.opts.ceiling && dir === this.opts.ceiling)
+                break;
+            const parent = node_path_1.default.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return dirs;
+    }
+    /** jail for project-tree files: the git root if the file is inside it, else its own directory. */
+    jailFor(dir) {
+        return this.gitRoot && (0, fs_safe_1.isInside)(dir, this.gitRoot) ? this.gitRoot : dir;
+    }
+    /** Skip fixture folders? Not when asked not to, and not when the scan root is itself inside one (scanning a fixture on purpose). */
+    skipFixtures() {
+        return !this.opts.includeFixtures && !(0, fixtures_1.rootIsInsideFixtures)(this.cwd);
+    }
+    walk() {
+        if (!this.walkCache) {
+            const skip = this.skipFixtures();
+            const w = (0, fs_safe_1.walkForFiles)(this.cwd, exports.WALK_CANDIDATES, { timeUp: () => this.timeUp(), skipDir: skip ? (0, fixtures_1.makeFixtureSkipper)(this.cwd) : undefined });
+            const notAProject = !this.isProjectDir();
+            if ((w.truncated || w.timedOut) && notAProject) {
+                // Walking a home folder, a drive root or ~/Downloads: whatever CLAUDE.md/AGENTS.md files happen to sit in the first
+                // 5,000 entries are random, not "your project". Reporting them would print junk token totals, so drop them.
+                this.walkCache = { ...w, hits: [], notAProject, skipped: [] };
+                this.warn(`${this.display(this.cwd) === "." ? "this folder" : this.display(this.cwd)} does not look like a project (no .git, no agent files at its top level) and holds more than ${fs_safe_1.MAX_WALK_ENTRIES} entries, so nested agent files were NOT scanned (they would be arbitrary). Run prehello on a project folder: prehello ~/code/my-project`);
+            }
+            else {
+                this.walkCache = { ...w, notAProject };
+                if (w.truncated)
+                    this.warn(`project walk stopped at ${fs_safe_1.MAX_WALK_ENTRIES} entries; nested files deeper in the tree may be missed`);
+                if (w.timedOut)
+                    this.warn("project walk stopped at the time budget; nested files may be missed");
+                this.fixturesSkipped = this.probeFixtures(w.skipped);
+            }
+        }
+        return this.walkCache;
+    }
+    /** How many skipped fixture folders hold agent files? A bounded, read-only look (names only); folders it cannot settle are not counted. */
+    probeFixtures(dirs) {
+        let left = FIXTURE_PROBE_TOTAL;
+        let n = 0;
+        for (const d of dirs) {
+            if (left <= 0 || this.timeUp())
+                break;
+            const p = (0, fs_safe_1.walkForFiles)(d, exports.WALK_CANDIDATES, { timeUp: () => this.timeUp(), includeRoot: true, stopAtFirstHit: true, maxEntries: Math.min(left, FIXTURE_PROBE_ENTRIES) });
+            left -= p.entries;
+            if (p.hits.length)
+                n++;
+        }
+        return n;
+    }
+    /** Cached, defensive read. Missing = silent; other failures become warnings (-> exit code 3). */
+    read(p, opts = {}) {
+        const key = `${p}|${opts.jail ?? ""}|${opts.maxBytes ?? ""}`;
+        let r = this.readCache.get(key);
+        if (!r) {
+            if (this.timeUp() || this.bytesRead >= this.maxScanBytes) {
+                // Budget spent: stop touching the disk. Missing files stay silent, everything else counts as skipped.
+                if (this.bytesRead >= this.maxScanBytes)
+                    this.budgetHit = this.budgetHit ?? "bytes";
+                r = (0, fs_safe_1.readTextSafe)(p, { ...opts, budgetBytes: 0 });
+                if (!r.ok && r.reason === "budget")
+                    this.budgetSkipped++;
+            }
+            else {
+                r = (0, fs_safe_1.readTextSafe)(p, { ...opts, budgetBytes: this.maxScanBytes - this.bytesRead });
+                if (r.ok)
+                    this.bytesRead += r.bytes;
+                else if (r.reason === "budget") {
+                    this.budgetHit = this.budgetHit ?? "bytes";
+                    this.budgetSkipped++;
+                }
+            }
+            this.readCache.set(key, r);
+            if (!r.ok && !opts.quiet && r.reason !== "missing" && r.reason !== "budget")
+                this.warn(`${this.display(p)}: ${readFailWhy(r.reason, "skipped")}`);
+        }
+        return r;
+    }
+    /** Called once at the end of a scan: one summary warning when a whole-scan budget cut the scan short. */
+    budgetSummary() {
+        if (!this.budgetHit)
+            return undefined;
+        const what = this.budgetHit === "time" ? `${Math.round(this.maxScanMs / 1000)} s time budget` : `${Math.round(this.maxScanBytes / 1048576)} MiB read budget`;
+        return `scan stopped at its ${what}${this.budgetSkipped ? `; ${this.budgetSkipped} file${this.budgetSkipped > 1 ? "s were" : " was"} not read` : ""}. Results are PARTIAL: totals are lower bounds. Scan a smaller folder, or raise the budget with --scan-budget-mb / --scan-budget-ms.`;
+    }
+    readJson(p) {
+        const r = this.read(p, { maxBytes: 64 * 1024 * 1024 });
+        if (!r.ok)
+            return undefined;
+        try {
+            return JSON.parse(r.text);
+        }
+        catch {
+            this.warn(`${this.display(p)}: could not parse as JSON, skipped`);
+            return undefined;
+        }
+    }
+    count(key, text) {
+        let n = this.countCache.get(key);
+        if (n === undefined) {
+            n = this.counter.count(text);
+            this.countCache.set(key, n);
+        }
+        return n;
+    }
+    addFinding(f, dedupeKey) {
+        const k = dedupeKey ?? `${f.id}|${f.agent}|${f.paths.join(",")}|${f.message}`;
+        if (this.findingKeys.has(k))
+            return;
+        this.findingKeys.add(k);
+        this.findings.push(f);
+    }
+    makeItem(a) {
+        const prof = this.profile(a.agent);
+        return {
+            id: `${a.agent}:${++this.seq}`,
+            agent: a.agent,
+            path: a.path,
+            kind: a.kind,
+            scope: a.scope,
+            loadMode: a.loadMode,
+            tokens: a.raw === null ? null : prof.apply(a.raw),
+            ...(a.raw === null ? { unmeasuredReason: a.unmeasuredReason ?? "not measurable" } : {}),
+            chars: a.chars ?? 0,
+            lines: a.lines ?? 0,
+            confidence: a.confidence,
+            evidence: a.evidence,
+            notes: a.notes ?? [],
+            cardLabel: a.cardLabel,
+            label: (0, fmt_1.sanitize)(a.label, 100),
+            ...(a.detail ? { detail: a.detail } : {}),
+            ...(a.group ? { group: a.group, groupLabel: a.groupLabel ?? a.group } : {}),
+        };
+    }
+    /** Per-document analysis shared by all agents: secrets (F9), guideline length (F1), shingles for duplicates (F2). */
+    analyzeDoc(agent, filePath, rawText, processed, rawTokens, guidelineLines) {
+        const real = (0, fs_safe_1.realpathOrSelf)(filePath);
+        const lines = lineCount(rawText);
+        const secretLines = (0, redact_1.findSecretLines)(rawText);
+        if (secretLines.length) {
+            this.addFinding({
+                id: "F9",
+                severity: "warn",
+                agent: "all",
+                message: `Possible secret on line${secretLines.length > 1 ? "s" : ""} ${secretLines.slice(0, 5).join(", ")}${secretLines.length > 5 ? ", …" : ""} of ${this.display(filePath)} (value not shown)`,
+                paths: [filePath],
+                confidence: "medium",
+                data: { lines: secretLines.slice(0, 50) },
+                fix: "Remove the secret from the instruction file and rotate it; agents send this file to a model provider.",
+            }, `F9|${real}`);
+        }
+        if (guidelineLines && lines > guidelineLines) {
+            this.addFinding({
+                id: "F1",
+                severity: "info",
+                agent,
+                message: `${this.display(filePath)} is ${lines} lines (documented guideline: under ${guidelineLines}); longer files can reduce adherence`,
+                paths: [filePath],
+                confidence: "medium",
+                data: { fileLines: lines, guidelineLines },
+                fix: "Split into scoped rules or move reference material out of the always-loaded file.",
+            });
+        }
+        let info = this.docs.get(real);
+        if (!info) {
+            info = { path: filePath, tokens: rawTokens, shingles: shingles(processed), agents: new Set() };
+            this.docs.set(real, info);
+        }
+        info.agents.add(agent);
+    }
+}
+exports.Ctx = Ctx;
+function lineCount(text) {
+    if (!text)
+        return 0;
+    return text.replace(/\n$/, "").split("\n").length;
+}
+function fnv(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+function shingles(text, k = 5) {
+    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+    const out = new Set();
+    if (words.length < k) {
+        if (words.length)
+            out.add(fnv(words.join(" ")));
+        return out;
+    }
+    for (let i = 0; i + k <= words.length; i++)
+        out.add(fnv(words.slice(i, i + k).join(" ")));
+    return out;
+}
+function jaccard(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let inter = 0;
+    const [s, l] = a.size < b.size ? [a, b] : [b, a];
+    for (const x of s)
+        if (l.has(x))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}

package/dist/fixtures.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Test-fixture folders. A repository that tests an agent tool (prehello itself, linters for AGENTS.md, skill validators, ...) keeps
+ * sample AGENTS.md / CLAUDE.md / .cursor/rules / skills under test/fixtures/**. Those files are not loaded by any agent, so the
+ * project walk skips such folders by default (`--include-fixtures` brings them back).
+ *
+ * Pure functions over path segments; callers split paths on BOTH separators so Windows paths work.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitSegments = splitSegments;
+exports.isFixtureSegment = isFixtureSegment;
+exports.rootIsInsideFixtures = rootIsInsideFixtures;
+exports.makeFixtureSkipper = makeFixtureSkipper;
+/** Names that mean "test data" wherever they appear below the scan root. */
+const FIXTURE_NAMES = new Set(["fixtures", "__fixtures__", "fixture", "testdata", "test-data", "__mocks__", "__snapshots__"]);
+/** Names that are too generic on their own: only fixtures when they sit under one of TEST_PARENTS. */
+const GENERIC_NAMES = new Set(["snapshots", "golden", "goldens"]);
+const TEST_PARENTS = new Set(["test", "tests", "__tests__", "spec", "specs", "e2e", "cypress", "testdata", "test-data"]);
+function splitSegments(p) {
+    return p.split(/[\\/]+/).filter(Boolean);
+}
+/**
+ * Is segment `i` of `segs` a fixture folder? `segs` = the segments from some root down to the folder, folder last at `i`.
+ * Comparison is case-insensitive (macOS and Windows filesystems are).
+ */
+function isFixtureSegment(segs, i) {
+    const name = segs[i].toLowerCase();
+    if (FIXTURE_NAMES.has(name))
+        return true;
+    if (!GENERIC_NAMES.has(name))
+        return false;
+    for (let j = 0; j < i; j++)
+        if (TEST_PARENTS.has(segs[j].toLowerCase()))
+            return true;
+    return false;
+}
+/** Is the scan root itself inside a fixture folder (so the user is deliberately scanning a fixture)? Then nothing is skipped. */
+function rootIsInsideFixtures(cwd) {
+    const segs = splitSegments(cwd);
+    for (let i = 0; i < segs.length; i++)
+        if (isFixtureSegment(segs, i))
+            return true;
+    return false;
+}
+/**
+ * Directory filter for the walk below `cwd`. `rel` = segments below the root (folder last). The root's own last segment counts as a
+ * possible test parent for generic names (scanning `repo/test` should still skip `test/golden`).
+ */
+function makeFixtureSkipper(cwd) {
+    const base = splitSegments(cwd).slice(-1);
+    return (_name, rel) => isFixtureSegment([...base, ...rel], base.length + rel.length - 1);
+}

package/dist/fs-safe.js

@@ -0,0 +1,222 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WALK_DEPTH = exports.MAX_WALK_ENTRIES = exports.DEFAULT_MAX_SCAN_MS = exports.DEFAULT_MAX_SCAN_BYTES = exports.MAX_FILE_BYTES = void 0;
+exports.realpathOrSelf = realpathOrSelf;
+exports.isInside = isInside;
+exports.exists = exists;
+exports.isDir = isDir;
+exports.isFile = isFile;
+exports.listDir = listDir;
+exports.readTextSafe = readTextSafe;
+exports.walkForFiles = walkForFiles;
+exports.findGitRoot = findGitRoot;
+exports.onPath = onPath;
+/**
+ * The ONLY module that touches the filesystem for scanning. It exposes read-only operations;
+ * nothing in the scan path may call a write API (enforced by test/safety.test.ts).
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const platform_1 = require("./platform");
+/**
+ * Per-file read cap. 4 MiB is Claude Code's documented limit for startup CLAUDE.md files ("Claude Code skips a file over
+ * 4 MiB and loads none of it"), so for Claude Code a skipped file here is a file the agent skips too. For other agents it is
+ * a generic safety cap (Codex has its own, much smaller, project_doc_max_bytes that the Codex adapter models separately).
+ */
+exports.MAX_FILE_BYTES = 4 * 1024 * 1024;
+/** Whole-scan budgets (a safety net against pathological trees, not a feature knob). Bytes are deterministic; the clock is not. */
+exports.DEFAULT_MAX_SCAN_BYTES = 64 * 1024 * 1024;
+exports.DEFAULT_MAX_SCAN_MS = 20_000;
+exports.MAX_WALK_ENTRIES = 5000;
+exports.MAX_WALK_DEPTH = 8;
+const IGNORE_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", "target", ".next", ".nuxt", ".venv", "venv", "__pycache__",
+    "vendor", ".cache", "coverage", ".gradle", ".idea", ".tox", ".turbo",
+]);
+/**
+ * Canonical path. Uses the OS-native realpath where available so that on case-insensitive filesystems
+ * (macOS APFS default, Windows NTFS) `claude.md` and `CLAUDE.md`, or a `/var` -> `/private/var` alias,
+ * resolve to ONE path and are never counted twice.
+ */
+function realpathOrSelf(p) {
+    try {
+        return (node_fs_1.default.realpathSync.native ?? node_fs_1.default.realpathSync)(p);
+    }
+    catch {
+        try {
+            return node_fs_1.default.realpathSync(p);
+        }
+        catch {
+            return node_path_1.default.resolve(p);
+        }
+    }
+}
+function isInside(child, parent) {
+    return (0, platform_1.isInsideWith)(node_path_1.default, child, parent);
+}
+function exists(p) {
+    try {
+        node_fs_1.default.statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return node_fs_1.default.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(p) {
+    try {
+        return node_fs_1.default.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Sorted directory entries, or [] if unreadable. */
+function listDir(p) {
+    try {
+        return node_fs_1.default.readdirSync(p, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read a text file defensively. `jail`: if given, the file's real path must be inside it
+ * (blocks symlinks in untrusted project trees that point at e.g. ~/.ssh).
+ */
+function readTextSafe(p, opts = {}) {
+    let st;
+    try {
+        st = node_fs_1.default.statSync(p);
+    }
+    catch (e) {
+        const code = e.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? { ok: false, reason: "missing" } : { ok: false, reason: "unreadable", detail: String(code) };
+    }
+    if (!st.isFile())
+        return { ok: false, reason: "not-file" };
+    const real = realpathOrSelf(p);
+    if (opts.jail && !isInside(real, realpathOrSelf(opts.jail)))
+        return { ok: false, reason: "symlink-escape" };
+    if (st.size > (opts.maxBytes ?? exports.MAX_FILE_BYTES))
+        return { ok: false, reason: "too-large", detail: `${st.size} bytes` };
+    if (opts.budgetBytes !== undefined && st.size > opts.budgetBytes)
+        return { ok: false, reason: "budget", detail: `${st.size} bytes` };
+    let buf;
+    try {
+        buf = node_fs_1.default.readFileSync(p);
+    }
+    catch (e) {
+        return { ok: false, reason: "unreadable", detail: String(e.code) };
+    }
+    // Windows PowerShell 5 writes UTF-16 with a BOM for `echo x > AGENTS.md`; agents read these files as UTF-8, so say so instead of "binary".
+    if (buf.length >= 2 && ((buf[0] === 0xff && buf[1] === 0xfe) || (buf[0] === 0xfe && buf[1] === 0xff)))
+        return { ok: false, reason: "utf16" };
+    if (buf.subarray(0, 8000).includes(0))
+        return { ok: false, reason: "binary" };
+    let text = buf.toString("utf8");
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    text = text.replace(/\r\n?/g, "\n");
+    return { ok: true, text, bytes: buf.length, realPath: real };
+}
+/**
+ * Bounded project walk (no symlink following, ignores build dirs, dot-dirs, ≤5k entries, depth ≤ 8).
+ * Returns directories (other than root) that contain any of the candidate relative paths.
+ */
+function walkForFiles(root, candidates, opts = {}) {
+    const hits = [];
+    const skipped = [];
+    const maxEntries = opts.maxEntries ?? exports.MAX_WALK_ENTRIES;
+    let seen = 0;
+    let truncated = false;
+    let timedOut = false;
+    const visit = (dir, depth, rel) => {
+        if (truncated || timedOut || (opts.stopAtFirstHit && hits.length))
+            return;
+        if (opts.timeUp?.()) {
+            timedOut = true;
+            return;
+        }
+        const entries = listDir(dir);
+        seen += entries.length;
+        if (seen > maxEntries) {
+            truncated = true;
+            return;
+        }
+        if (dir !== root || opts.includeRoot) {
+            // a trailing "/" in a candidate means "a directory with this relative path"
+            const present = candidates.filter((c) => (c.endsWith("/") ? isDir(node_path_1.default.join(dir, c)) : isFile(node_path_1.default.join(dir, c))) && !isSymlink(node_path_1.default.join(dir, c)));
+            if (present.length)
+                hits.push({ dir, names: present });
+        }
+        if (depth >= exports.MAX_WALK_DEPTH)
+            return;
+        for (const e of entries) {
+            if (!e.isDirectory() || e.isSymbolicLink())
+                continue;
+            if (IGNORE_DIRS.has(e.name) || e.name.startsWith("."))
+                continue;
+            const childRel = [...rel, e.name];
+            if (opts.skipDir?.(e.name, childRel)) {
+                skipped.push(node_path_1.default.join(dir, e.name));
+                continue;
+            }
+            visit(node_path_1.default.join(dir, e.name), depth + 1, childRel);
+        }
+    };
+    visit(root, 0, []);
+    return { hits, truncated, timedOut, entries: Math.min(seen, maxEntries), skipped };
+}
+function isSymlink(p) {
+    try {
+        return node_fs_1.default.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Find the nearest ancestor (inclusive) containing `.git`. */
+function findGitRoot(start, ceiling) {
+    let dir = start;
+    for (;;) {
+        if (exists(node_path_1.default.join(dir, ".git")))
+            return dir;
+        if (ceiling && dir === ceiling)
+            return undefined;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Is an executable named `name` on the given PATH string? (read-only stat calls)
+ * On Windows the binary is `claude.exe` / `claude.cmd` (npm shims), never bare `claude`, so PATHEXT is honoured.
+ */
+function onPath(name, pathVar, opts = {}) {
+    if (!pathVar)
+        return false;
+    const win = opts.platform === "win32";
+    const delim = opts.platform ? (win ? ";" : ":") : node_path_1.default.delimiter;
+    const exts = win ? ["", ...(opts.pathExt || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((e) => e.toLowerCase()), ".ps1"] : [""];
+    for (const d of pathVar.split(delim)) {
+        if (!d)
+            continue;
+        for (const e of exts)
+            if (isFile(node_path_1.default.join(d, name + e)))
+                return true;
+    }
+    return false;
+}

package/dist/mcp/catalog.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCatalog = loadCatalog;
+exports.lookup = lookup;
+const node_fs_1 = __importDefault(require("node:fs"));
+const platform_1 = require("../platform");
+const spec_1 = require("../spec");
+function valid(e) {
+    if (typeof e !== "object" || e === null)
+        return false;
+    const x = e;
+    return ((typeof x.name === "string" || typeof x.package === "string") &&
+        Number.isFinite(x.nameTokens) && x.nameTokens >= 0 &&
+        Number.isFinite(x.schemaTokens) && x.schemaTokens >= 0 &&
+        Number.isFinite(x.tools) &&
+        typeof x.measuredAt === "string");
+}
+function loadCatalog(extraPath, noBundled = false) {
+    const entries = [];
+    const warnings = [];
+    // user-supplied file first: lookup() returns the first match, so a user's own measurement beats the bundled one
+    for (const p of [extraPath, noBundled ? undefined : (0, spec_1.loadBundledCatalogPath)()].filter((x) => !!x)) {
+        try {
+            const j = JSON.parse((0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(p)));
+            for (const e of j.servers ?? []) {
+                if (valid(e))
+                    entries.push(e);
+                else
+                    warnings.push("an MCP catalog entry was malformed and ignored");
+            }
+        }
+        catch {
+            if (p === extraPath)
+                warnings.push("MCP catalog file could not be read or parsed; ignored");
+        }
+    }
+    return { entries, warnings };
+}
+function lookup(entries, def) {
+    return entries.find((e) => (e.name && e.name === def.name) || (e.package && def.pkg && e.package === def.pkg));
+}