prehello 0.0.0-stage → 1.0.0

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));
+}

package/dist/mcp/configs.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_MCP_SERVERS = void 0;
+exports.parseMcpMap = parseMcpMap;
+exports.parseCodexToml = parseCodexToml;
+const smol_toml_1 = require("smol-toml");
+const fmt_1 = require("../util/fmt");
+function isObj(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function guessPkg(entry) {
+    const args = Array.isArray(entry.args) ? entry.args.filter((a) => typeof a === "string") : [];
+    const cmd = typeof entry.command === "string" ? entry.command : "";
+    if (!/(^|\/)(npx|bunx|pnpx|uvx|pipx)$/.test(cmd) && !/^(npx|bunx|pnpx|uvx|pipx)$/.test(cmd))
+        return undefined;
+    const a = args.find((x) => !x.startsWith("-"));
+    return a ? a.replace(/@[\w.^~<>=*-]+$/, (m) => (a.startsWith("@") && a.indexOf("@", 1) === -1 ? m : "")) : undefined;
+}
+/** A real config has a handful of servers. A hostile one with 200,000 entries must not become a 180 MB report. */
+exports.MAX_MCP_SERVERS = 500;
+/** Extract server definitions from a `{ mcpServers: {...} }`-style map. Values (env, headers, args) are never retained. */
+function parseMcpMap(map, warn) {
+    if (!isObj(map))
+        return [];
+    const out = [];
+    const names = Object.keys(map);
+    if (names.length > exports.MAX_MCP_SERVERS)
+        warn?.(`an MCP config lists ${names.length} servers; only the first ${exports.MAX_MCP_SERVERS} were read, so MCP counts are a lower bound`);
+    for (const name of names.slice(0, exports.MAX_MCP_SERVERS)) {
+        const v = map[name];
+        if (!isObj(v))
+            continue;
+        const t = typeof v.type === "string" ? v.type : typeof v.transport === "string" ? v.transport : undefined;
+        const transport = t === "http" || t === "streamable-http" ? "http" : t === "sse" ? "sse" : t === "stdio" || t === "local" || typeof v.command === "string" ? "stdio" : typeof v.url === "string" || typeof v.httpUrl === "string" ? "http" : "unknown";
+        out.push({ name: (0, fmt_1.sanitize)(name, 60), transport, pkg: guessPkg(v), disabled: v.disabled === true || v.enabled === false });
+    }
+    return out;
+}
+function parseCodexToml(text, warn) {
+    const cfg = (0, smol_toml_1.parse)(text);
+    return { servers: parseMcpMap(cfg.mcp_servers, warn), config: cfg };
+}

package/dist/model.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOAD_MODES = exports.ALL_AGENTS = exports.AGENT_NAMES = exports.SCHEMA_VERSION = void 0;
+exports.SCHEMA_VERSION = 1;
+var agents_1 = require("./agents");
+Object.defineProperty(exports, "AGENT_NAMES", { enumerable: true, get: function () { return agents_1.AGENT_NAMES; } });
+Object.defineProperty(exports, "ALL_AGENTS", { enumerable: true, get: function () { return agents_1.ALL_AGENTS; } });
+exports.LOAD_MODES = ["always", "conditional", "deferred", "on-demand", "unknown"];

package/dist/platform.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWinAbsolute = isWinAbsolute;
+exports.resolveHomeDir = resolveHomeDir;
+exports.isWindowsReservedName = isWindowsReservedName;
+exports.hasWindowsStream = hasWindowsStream;
+exports.unicodeSupported = unicodeSupported;
+exports.toAscii = toAscii;
+exports.toPosix = toPosix;
+exports.makeGlobMatcher = makeGlobMatcher;
+exports.isInsideWith = isInsideWith;
+exports.decodeUserText = decodeUserText;
+/**
+ * Platform helpers: everything that differs between Linux, macOS and Windows lives here, as pure functions that take the
+ * platform (and a `path` implementation) as arguments, so the Windows behaviour can be unit-tested on any machine.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const picomatch_1 = __importDefault(require("picomatch"));
+/** Is `p` an absolute path in the Windows sense (C:\x, C:/x, \\server\share)? Works on any host. */
+function isWinAbsolute(p) {
+    return node_path_1.default.win32.isAbsolute(p) && /^(?:[a-zA-Z]:[\\/]|\\\\|\/\/)/.test(p);
+}
+/**
+ * The home directory the AGENTS use. Claude Code, Cursor (Electron) and Codex all take it from the OS, not from $HOME:
+ * on Windows that is %USERPROFILE%. Git Bash sets HOME to a POSIX-style "/c/Users/me" that Node cannot open, and a network HOME
+ * ("H:\") can differ from the profile folder the agents read, so on Windows HOME is only a last resort.
+ */
+function resolveHomeDir(env, platform, osHomedir) {
+    if (platform === "win32") {
+        if (env.USERPROFILE && isWinAbsolute(env.USERPROFILE))
+            return env.USERPROFILE;
+        if (env.HOMEDRIVE && env.HOMEPATH && isWinAbsolute(env.HOMEDRIVE + env.HOMEPATH))
+            return env.HOMEDRIVE + env.HOMEPATH;
+        if (env.HOME && isWinAbsolute(env.HOME))
+            return env.HOME;
+        return osHomedir();
+    }
+    if (env.HOME && node_path_1.default.posix.isAbsolute(env.HOME))
+        return env.HOME;
+    return osHomedir();
+}
+/** Windows device names: opening "nul.svg" or "COM1.md" writes to a device (silently discarding the report), whatever the extension. */
+function isWindowsReservedName(file) {
+    const base = file.split(/[\\/]/).pop() ?? "";
+    const stem = base.split(".")[0].replace(/[ .]+$/, "");
+    return /^(con|prn|aux|nul|conin\$|conout\$|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3])$/i.test(stem);
+}
+/** On Windows a ":" after the drive letter is an NTFS alternate data stream ("report.md:hidden"): never write one. */
+function hasWindowsStream(file) {
+    return file.replace(/^(?:\\\\\?\\)?[a-zA-Z]:/, "").includes(":");
+}
+/**
+ * Can this terminal draw the box/block/arrow glyphs prehello uses? Mirrors the widely used "is-unicode-supported" rule:
+ * the Linux virtual console (TERM=linux) and the legacy Windows console host (cmd.exe / classic PowerShell window) cannot,
+ * Windows Terminal, VS Code, JetBrains, ConEmu, Alacritty and modern xterm-likes can.
+ */
+function unicodeSupported(env, platform) {
+    if (env.PREHELLO_ASCII === "1")
+        return false;
+    if (platform !== "win32")
+        return env.TERM !== "linux";
+    return (!!env.WT_SESSION ||
+        !!env.TERMINUS_SUBLIME ||
+        env.ConEmuTask === "{cmd::Cmder}" ||
+        env.TERM_PROGRAM === "vscode" ||
+        env.TERM_PROGRAM === "Terminus-Sublime" ||
+        env.TERM === "xterm-256color" ||
+        env.TERM === "alacritty" ||
+        env.TERMINAL_EMULATOR === "JetBrains-JediTerm");
+}
+const ASCII_MAP = {
+    "·": "-", "–": "-", "—": "-", "−": "-", "…": "...", "≥": ">=", "≤": "<=", "→": "->", "⚠": "!", "ℹ": "i", "•": "*",
+    "█": "#", "▌": "=", "‘": "'", "’": "'", "“": '"', "”": '"', "≈": "~", "×": "x",
+};
+/** Replace every non-ASCII glyph prehello prints with an ASCII stand-in (accents and other letters become "?"). */
+function toAscii(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[^\x00-\x7f]/gu, (c) => ASCII_MAP[c] ?? "?");
+}
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+/**
+ * Glob matcher for settings such as claudeMdExcludes. Always matches forward-slash paths: a Windows path is converted first,
+ * and backslashes in a pattern are path separators there (not escapes). Windows paths are case-insensitive.
+ */
+function makeGlobMatcher(patterns, platform) {
+    const win = platform === "win32";
+    const pats = win ? patterns.map(toPosix) : patterns;
+    const m = (0, picomatch_1.default)(pats, { dot: true, windows: false, nocase: win });
+    return (file) => m(win ? toPosix(file) : file);
+}
+/** True if `child` is `parent` or inside it. A directory called "..foo" is inside; "../x" is not. */
+function isInsideWith(pm, child, parent) {
+    const rel = pm.relative(parent, child);
+    return rel === "" || (rel !== ".." && !rel.startsWith(".." + pm.sep) && !pm.isAbsolute(rel));
+}
+/**
+ * Text a USER hands to prehello (--mcp-catalog file, --paste-user-rules file or stdin). Windows editors and PowerShell 5 write
+ * a UTF-8 BOM or UTF-16: both are decoded here instead of failing as "malformed JSON" or counting a BOM as a token.
+ * CRLF is normalised to LF for pasted rules so the same text counts the same on every platform.
+ */
+function decodeUserText(buf) {
+    let s;
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe)
+        s = buf.subarray(2).toString("utf16le");
+    else if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff)
+        s = Buffer.from(buf.subarray(2)).swap16().toString("utf16le");
+    else
+        s = buf.toString("utf8");
+    return s.replace(/^\ufeff/, "");
+}

package/dist/redact.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrubSecrets = exports.findSecretLines = void 0;
+exports.displayPath = displayPath;
+const node_path_1 = __importDefault(require("node:path"));
+const fmt_1 = require("./util/fmt");
+const secrets_1 = require("./util/secrets");
+Object.defineProperty(exports, "findSecretLines", { enumerable: true, get: function () { return secrets_1.findSecretLines; } });
+Object.defineProperty(exports, "scrubSecrets", { enumerable: true, get: function () { return secrets_1.scrubSecrets; } });
+/** True when `rel` (from path.relative) leaves its base: "..", "../x", but not a child called "..foo". */
+function escapes(pm, rel) {
+    return rel === ".." || rel.startsWith(".." + pm.sep) || pm.isAbsolute(rel);
+}
+/** Display form of a path: ./relative inside the project, ~/ inside HOME, else absolute. Always forward slashes. Sanitised + scrubbed. */
+function displayPath(p, c) {
+    const pm = c.pathMod ?? node_path_1.default;
+    const slash = (x) => x.split(pm.sep).join("/");
+    let out;
+    const rel = pm.relative(c.cwd, p);
+    if (rel === "")
+        out = ".";
+    else if (!escapes(pm, rel))
+        out = "./" + slash(rel);
+    else {
+        const hr = pm.relative(c.home, p);
+        if (hr === "")
+            out = "~";
+        else if (!escapes(pm, hr))
+            out = "~/" + slash(hr);
+        else if (rel.split(pm.sep).filter((x) => x === "..").length <= 4 && !pm.isAbsolute(rel))
+            out = slash(rel); // ../../CLAUDE.md (ancestor directory)
+        else
+            out = slash(p); // absolute elsewhere; on Windows "C:/Users/..." rather than backslashes (JSON/markdown-safe)
+    }
+    return (0, secrets_1.scrubSecrets)((0, fmt_1.sanitize)(out, 200));
+}