@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/core/context/repo-skeleton.js

@@ -1,533 +0,0 @@
-/**
- * Tier 0 repo skeleton builder - Phase 1 (three-tier context).
- *
- * The skeleton is the ~5KB "always loaded" tier in the three-tier
- * model. Goal: give the agent enough structural awareness to navigate
- * an unfamiliar repo on the first turn without uploading the whole
- * tree. We capture:
- *
- *  - cwd + current branch (best-effort, no exec)
- *  - detected package manager (lockfile heuristic)
- *  - primary languages (file-extension histogram, top 5)
- *  - ASCII directory tree (depth <= MAX_TREE_DEPTH, collapses busy
- *    dirs to a "(N dirs, M files)" line)
- *  - package.json projection (name/version/scripts/deps)
- *  - first MAX_README_LINES of README.md
- *
- * Hard constraints:
- *
- *  1. **5KB cap on the rendered string**. We render in priority
- *     order (headers + meta first, then tree, then package.json, then
- *     README) and truncate the tail with a "..." marker rather than
- *     omitting fields. The walker's bound is independent: it stops
- *     visiting dirs after a hard `MAX_WALK_NODES` even when the
- *     skeleton would still fit.
- *
- *  2. **Ignore-aware**: every fs read is filtered through `PugiIgnore`
- *     so `.env`, `*.pem`, `node_modules/`, etc. stay out. The walker
- *     uses the same matcher so `node_modules/` is never expanded.
- *
- *  3. **No exec**: we read `.git/HEAD` for the branch, never spawn
- *     `git`. The skeleton is built on session bootstrap; spawning
- *     git on every launch is slow + makes the CLI flaky on hosts
- *     without git installed.
- *
- *  4. **Best-effort**: every FS read is wrapped in try/catch.
- *     Missing README / missing package.json / unreadable file -> the
- *     field is omitted but the skeleton still builds.
- */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
-/** Hard cap on the rendered skeleton string. Spec: ~5KB. */
-export const MAX_SKELETON_BYTES = 5_000;
-/** Maximum depth the ASCII tree descends. */
-export const MAX_TREE_DEPTH = 3;
-/** Maximum nodes the walker visits before giving up. Guards giant repos. */
-export const MAX_WALK_NODES = 5_000;
-/** Maximum README lines copied into the skeleton. Spec: ~200. */
-export const MAX_README_LINES = 200;
-/** When a single dir holds more than this many entries we collapse to a count. */
-export const COLLAPSE_DIR_ENTRIES = 20;
-/** Top-N languages reported. */
-export const TOP_LANGUAGES = 5;
-/**
- * Walk the workspace, collect signals, render the skeleton. Returns a
- * structured `RepoSkeleton` whose `dirTree` is already trimmed to fit
- * `MAX_SKELETON_BYTES` once rendered.
- */
-export function buildRepoSkeleton(cwd, options) {
-    const normalised = resolve(cwd);
-    const ignore = options.ignore;
-    const branch = readGitBranch(normalised);
-    // Pass the ignore matcher through to both readers so an operator who
-    // explicitly added README.md or package.json to .pugiignore (private
-    // contracts, customer-specific data, NDA'd boilerplate) keeps those
-    // files out of the agent context. Without this gate, the direct
-    // skeleton reads would BYPASS the matcher even though the walker
-    // honours it. triple-review P1 (PR).
-    const pkg = readPackageJson(normalised, ignore);
-    const packageManager = detectPackageManager(normalised, ignore);
-    const walk = walkTree(normalised, ignore);
-    const primaryLanguages = topLanguages(walk.extensionHistogram, TOP_LANGUAGES);
-    const dirTree = renderTree(walk.root);
-    const readmeExcerpt = readReadme(normalised, options.readmePath, ignore);
-    const skeleton = {
-        cwd: normalised,
-        branch,
-        packageManager,
-        primaryLanguages,
-        dirTree,
-        packageJson: pkg,
-        readmeExcerpt,
-        totalSize: 0,
-    };
-    const rendered = renderSkeleton(skeleton);
-    return Object.freeze({ ...skeleton, totalSize: Buffer.byteLength(rendered, 'utf8') });
-}
-/**
- * Render the skeleton as a single string for injection into the agent
- * system prompt. Sections are emitted in priority order; once the
- * cumulative byte count would exceed `MAX_SKELETON_BYTES` we drop the
- * remaining sections in reverse priority and emit a `...truncated...`
- * marker so the model knows the skeleton was clipped.
- *
- * Section order (highest priority first):
- *
- *  1. Meta header (cwd / branch / package manager / languages)
- *  2. Directory tree
- *  3. package.json projection (name / version / scripts / deps count)
- *  4. README excerpt
- *
- * Each lower-priority section is appended only when there is room for
- * its FULL body. Partial sections would mislead the model (e.g. a
- * half-README scriptkiddies a wrong project description).
- */
-export function renderSkeleton(skeleton) {
-    const header = renderHeader(skeleton);
-    const tree = renderTreeSection(skeleton);
-    const pkg = renderPackageJsonSection(skeleton);
-    const readme = renderReadmeSection(skeleton);
-    // Always include the header + tree even when they push past cap;
-    // those are the load-bearing signals. The package.json + readme are
-    // dropped from the tail if there is no room.
-    const required = [header, tree].join('\n');
-    const optional = [pkg, readme].filter((s) => s.length > 0);
-    let out = required;
-    for (const section of optional) {
-        const candidate = `${out}\n${section}`;
-        if (Buffer.byteLength(candidate, 'utf8') > MAX_SKELETON_BYTES) {
-            out = `${out}\n...truncated to fit ${MAX_SKELETON_BYTES} byte cap...`;
-            return out;
-        }
-        out = candidate;
-    }
-    // Final tail-trim: if even the required sections breached the cap
-    // (huge repo with a wide top-level tree), clip the rendered string
-    // and stamp a truncation marker.
-    if (Buffer.byteLength(out, 'utf8') > MAX_SKELETON_BYTES) {
-        const buf = Buffer.from(out, 'utf8');
-        const slice = buf.subarray(0, MAX_SKELETON_BYTES - 64).toString('utf8');
-        out = `${slice}\n...truncated to fit ${MAX_SKELETON_BYTES} byte cap...`;
-    }
-    return out;
-}
-/* ------------------------------------------------------------------ */
-/* Section renderers                                                 */
-/* ------------------------------------------------------------------ */
-function renderHeader(skeleton) {
-    const lines = [];
-    lines.push('# Repo skeleton (Tier 0)');
-    lines.push(`cwd: ${skeleton.cwd}`);
-    if (skeleton.branch)
-        lines.push(`branch: ${skeleton.branch}`);
-    if (skeleton.packageManager)
-        lines.push(`packageManager: ${skeleton.packageManager}`);
-    if (skeleton.primaryLanguages.length > 0) {
-        lines.push(`languages: ${skeleton.primaryLanguages.join(', ')}`);
-    }
-    return lines.join('\n');
-}
-function renderTreeSection(skeleton) {
-    if (!skeleton.dirTree || skeleton.dirTree.length === 0)
-        return '';
-    return `\n## tree\n${skeleton.dirTree}`;
-}
-function renderPackageJsonSection(skeleton) {
-    const pkg = skeleton.packageJson;
-    if (!pkg)
-        return '';
-    const lines = ['\n## package.json'];
-    if (pkg.name)
-        lines.push(`name: ${pkg.name}`);
-    if (pkg.version)
-        lines.push(`version: ${pkg.version}`);
-    if (pkg.scripts) {
-        const names = Object.keys(pkg.scripts).slice(0, 12);
-        if (names.length > 0)
-            lines.push(`scripts: ${names.join(', ')}`);
-    }
-    if (pkg.dependencies) {
-        const depCount = Object.keys(pkg.dependencies).length;
-        if (depCount > 0)
-            lines.push(`dependencies: ${depCount}`);
-    }
-    if (pkg.devDependencies) {
-        const depCount = Object.keys(pkg.devDependencies).length;
-        if (depCount > 0)
-            lines.push(`devDependencies: ${depCount}`);
-    }
-    return lines.join('\n');
-}
-function renderReadmeSection(skeleton) {
-    if (!skeleton.readmeExcerpt)
-        return '';
-    return `\n## README (first ${MAX_README_LINES} lines)\n${skeleton.readmeExcerpt}`;
-}
-/* ------------------------------------------------------------------ */
-/* Signal readers                                                    */
-/* ------------------------------------------------------------------ */
-/**
- * Read the current branch from `.git/HEAD` WITHOUT spawning git. The
- * file is either a ref pointer (`ref: refs/heads/main`) or a detached
- * SHA. We surface the branch name when the pointer parses, otherwise
- * the 8-char SHA prefix. Returns undefined on any error (not a git
- * repo, permissions issue, malformed HEAD).
- */
-export function readGitBranch(cwd) {
-    try {
-        const headPath = join(cwd, '.git', 'HEAD');
-        if (!existsSync(headPath))
-            return undefined;
-        const raw = readFileSync(headPath, 'utf8').trim();
-        const refMatch = /^ref:\s+refs\/heads\/(.+)$/.exec(raw);
-        if (refMatch)
-            return refMatch[1];
-        // Detached HEAD - raw is a 40-char SHA.
-        if (/^[0-9a-f]{7,40}$/i.test(raw))
-            return raw.slice(0, 8);
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Detect the package manager by looking for canonical lockfiles.
- * Preference order matches the npm ecosystem convention (pnpm > yarn
- * > bun > npm when multiple lockfiles co-exist, which is itself a
- * smell but we pick the most-likely-correct one).
- */
-export function detectPackageManager(cwd, ignore) {
-    try {
-        if (existsSync(join(cwd, 'pnpm-lock.yaml')))
-            return 'pnpm';
-        if (existsSync(join(cwd, 'yarn.lock')))
-            return 'yarn';
-        if (existsSync(join(cwd, 'bun.lockb')))
-            return 'bun';
-        if (existsSync(join(cwd, 'package-lock.json')))
-            return 'npm';
-        // Fall back to packageManager field in package.json when no
-        // lockfile is committed (e.g. a fresh monorepo skeleton).
-        // Codex R2 P2: honour .pugiignore here too — without this, an
-        // ignored package.json still leaks its packageManager value into
-        // the skeleton via this fallback path.
-        const pkgPath = join(cwd, 'package.json');
-        if (ignore?.isIgnored(pkgPath))
-            return undefined;
-        const pkgRaw = safeRead(pkgPath);
-        if (!pkgRaw)
-            return undefined;
-        const parsed = JSON.parse(pkgRaw);
-        if (typeof parsed.packageManager === 'string') {
-            const head = parsed.packageManager.split('@')[0];
-            if (head === 'npm' || head === 'yarn' || head === 'pnpm' || head === 'bun') {
-                return head;
-            }
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Read + project the `package.json`. We strip everything except the
- * fields the agent benefits from: name / version / scripts /
- * dependencies / devDependencies. The full file may be megabytes (deep
- * dependency trees, embedded changelogs); the projection caps the
- * payload at a few hundred bytes.
- */
-export function readPackageJson(cwd, ignore) {
-    const pkgPath = join(cwd, 'package.json');
-    // Honour the ignore matcher when supplied. Operators who add
-    // package.json to .pugiignore (private template projects, customer
-    // boilerplate under NDA) must not have it read into the agent
-    // context even though the walker would have skipped it.
-    // triple-review P1 (PR). The matcher is optional so direct callers
-    // (e.g. unit tests of readPackageJson in isolation) keep working.
-    if (ignore?.isIgnored(pkgPath))
-        return undefined;
-    const raw = safeRead(pkgPath);
-    if (!raw)
-        return undefined;
-    try {
-        const parsed = JSON.parse(raw);
-        const projection = {
-            name: typeof parsed.name === 'string' ? parsed.name : undefined,
-            version: typeof parsed.version === 'string' ? parsed.version : undefined,
-            scripts: pickStringMap(parsed.scripts),
-            dependencies: pickStringMap(parsed.dependencies),
-            devDependencies: pickStringMap(parsed.devDependencies),
-        };
-        return projection;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Read the first `MAX_README_LINES` of README.md (case-insensitive
- * match, since macOS / Windows are case-insensitive but POSIX is
- * case-sensitive). Returns undefined when no README is present.
- */
-export function readReadme(cwd, overridePath, ignore) {
-    const candidates = overridePath
-        ? [overridePath]
-        : ['README.md', 'readme.md', 'README', 'README.markdown'].map((n) => join(cwd, n));
-    for (const candidate of candidates) {
-        // Skip candidates the operator has explicitly ignored. A workspace
-        // README that documents private contracts / customer data must
-        // never land in the rendered skeleton. triple-review P1 (PR).
-        if (ignore?.isIgnored(candidate))
-            continue;
-        const raw = safeRead(candidate);
-        if (!raw)
-            continue;
-        const lines = raw.split(/\r?\n/).slice(0, MAX_README_LINES);
-        return lines.join('\n').trim();
-    }
-    return undefined;
-}
-/**
- * Walk the workspace once. Returns a depth-bounded tree, a histogram
- * of file extensions (drives `primaryLanguages`), and the total
- * number of nodes visited (used to short-circuit on huge repos).
- *
- * The walker honours `ignore.isIgnored` at EVERY entry so even
- * non-default ignores from `.gitignore` / `.pugiignore` stay out of
- * the tree AND out of the extension histogram. This matters because
- * a huge `node_modules/` would otherwise dominate the language signal
- * with `.json` / `.md` / `.d.ts`.
- */
-function walkTree(cwd, ignore) {
-    const extensionHistogram = new Map();
-    let visited = 0;
-    function walk(absPath, depth, name) {
-        visited += 1;
-        if (visited > MAX_WALK_NODES) {
-            return Object.freeze({
-                name,
-                children: [],
-                fileCount: 0,
-                dirCount: 0,
-                collapsed: true,
-            });
-        }
-        let entries;
-        try {
-            entries = readdirSync(absPath, { withFileTypes: true });
-        }
-        catch {
-            return Object.freeze({ name, children: [], fileCount: 0, dirCount: 0, collapsed: false });
-        }
-        // Sort alphabetically so the rendered tree is stable.
-        entries.sort((a, b) => a.name.localeCompare(b.name));
-        let fileCount = 0;
-        let dirCount = 0;
-        const dirs = [];
-        for (const entry of entries) {
-            const childAbs = join(absPath, entry.name);
-            // Pass the isDir hint so gitignore-style dir patterns
-            // (`node_modules/`, `dist/`) drop the dir itself, not just its
-            // children. Without this, the walker descends into node_modules
-            // and the tree leaks paths the agent should never see.
-            if (ignore.isIgnored(childAbs, entry.isDirectory()))
-                continue;
-            if (entry.isFile()) {
-                fileCount += 1;
-                const ext = languageForExtension(entry.name);
-                if (ext)
-                    extensionHistogram.set(ext, (extensionHistogram.get(ext) ?? 0) + 1);
-            }
-            else if (entry.isDirectory()) {
-                dirCount += 1;
-                dirs.push(entry);
-            }
-        }
-        if (depth >= MAX_TREE_DEPTH) {
-            return Object.freeze({ name, children: [], fileCount, dirCount, collapsed: dirCount > 0 });
-        }
-        // Collapse very busy dirs to keep the rendered tree under cap.
-        if (dirs.length > COLLAPSE_DIR_ENTRIES) {
-            return Object.freeze({ name, children: [], fileCount, dirCount, collapsed: true });
-        }
-        const children = [];
-        for (const dir of dirs) {
-            children.push(walk(join(absPath, dir.name), depth + 1, dir.name));
-        }
-        return Object.freeze({ name, children, fileCount, dirCount, collapsed: false });
-    }
-    const root = walk(cwd, 0, basename(cwd) || cwd);
-    return { root, extensionHistogram, visitedCount: visited };
-}
-/**
- * Render a `DirNode` as a UTF-8 ASCII-tree string. Lines use the
- * the upstream tool convention: `├──` / `└──` glyphs, two-space indents per
- * level. Collapsed dirs land as `name/ (N dirs, M files)`.
- */
-function renderTree(root) {
-    const lines = [];
-    lines.push(`${root.name}/${counts(root)}`);
-    appendChildren(root, '', lines);
-    return lines.join('\n');
-}
-function counts(node) {
-    if (!node.collapsed && node.children.length > 0)
-        return '';
-    // Surface counts on either a collapsed dir or a leaf-depth dir with
-    // nested content we did not descend into.
-    if (node.dirCount === 0 && node.fileCount === 0)
-        return '';
-    return ` (${node.dirCount} dirs, ${node.fileCount} files)`;
-}
-function appendChildren(node, prefix, lines) {
-    const children = node.children;
-    for (let i = 0; i < children.length; i += 1) {
-        const child = children[i];
-        const isLast = i === children.length - 1;
-        const glyph = isLast ? '└── ' : '├── ';
-        lines.push(`${prefix}${glyph}${child.name}/${counts(child)}`);
-        const nextPrefix = `${prefix}${isLast ? '   ' : '│  '}`;
-        appendChildren(child, nextPrefix, lines);
-    }
-}
-/* ------------------------------------------------------------------ */
-/* Language histogram                                                */
-/* ------------------------------------------------------------------ */
-/**
- * Map a filename to a human-readable language label. Returns null for
- * extensions we do not care to surface (e.g. `.json` is interesting
- * but contributes to the histogram as `json`; `.txt` is dropped).
- *
- * The mapping is conservative; we only label extensions the agent's
- * top-of-stack persona is likely to act on. Unknown extensions return
- * null so the histogram is dominated by signal rather than noise.
- */
-export function languageForExtension(filename) {
-    const dotIndex = filename.lastIndexOf('.');
-    if (dotIndex <= 0)
-        return null;
-    const ext = filename.slice(dotIndex + 1).toLowerCase();
-    const known = {
-        ts: 'TypeScript',
-        tsx: 'TypeScript',
-        mts: 'TypeScript',
-        cts: 'TypeScript',
-        js: 'JavaScript',
-        jsx: 'JavaScript',
-        mjs: 'JavaScript',
-        cjs: 'JavaScript',
-        py: 'Python',
-        rb: 'Ruby',
-        go: 'Go',
-        rs: 'Rust',
-        java: 'Java',
-        kt: 'Kotlin',
-        swift: 'Swift',
-        c: 'C',
-        h: 'C',
-        cpp: 'C++',
-        hpp: 'C++',
-        cc: 'C++',
-        cs: 'C#',
-        php: 'PHP',
-        scala: 'Scala',
-        ex: 'Elixir',
-        exs: 'Elixir',
-        erl: 'Erlang',
-        clj: 'Clojure',
-        sh: 'Shell',
-        bash: 'Shell',
-        zsh: 'Shell',
-        html: 'HTML',
-        css: 'CSS',
-        scss: 'CSS',
-        sass: 'CSS',
-        less: 'CSS',
-        vue: 'Vue',
-        svelte: 'Svelte',
-        md: 'Markdown',
-        mdx: 'Markdown',
-        json: 'JSON',
-        yaml: 'YAML',
-        yml: 'YAML',
-        toml: 'TOML',
-        sql: 'SQL',
-        graphql: 'GraphQL',
-        gql: 'GraphQL',
-        proto: 'Protobuf',
-        dockerfile: 'Dockerfile',
-    };
-    return known[ext] ?? null;
-}
-/**
- * Return the top-N languages by file count. Ties are broken
- * alphabetically so the output is stable across runs.
- */
-export function topLanguages(histogram, topN) {
-    const entries = Array.from(histogram.entries());
-    entries.sort((a, b) => {
-        if (b[1] !== a[1])
-            return b[1] - a[1];
-        return a[0].localeCompare(b[0]);
-    });
-    return entries.slice(0, topN).map(([lang]) => lang);
-}
-/* ------------------------------------------------------------------ */
-/* Small helpers                                                     */
-/* ------------------------------------------------------------------ */
-function safeRead(path) {
-    // Stat first to keep the regular-file guard (Codex R2 P2): a FIFO or
-    // socket named like README.md would otherwise block readFileSync()
-    // indefinitely and hang the REPL bootstrap. The stat itself is in a
-    // try/catch so missing-file / EACCES still fail soft. The catch on
-    // readFileSync still handles the race-deleted-between-syscalls case
-    // (TOCTOU is acceptable here - worst case we return null instead of
-    // partial bytes, never partial bytes themselves).
-    try {
-        const st = statSync(path);
-        if (!st.isFile())
-            return null;
-    }
-    catch {
-        return null;
-    }
-    try {
-        return readFileSync(path, 'utf8');
-    }
-    catch {
-        return null;
-    }
-}
-function pickStringMap(value) {
-    if (!value || typeof value !== 'object')
-        return undefined;
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-        if (typeof v === 'string')
-            out[k] = v;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-//# sourceMappingURL=repo-skeleton.js.map

package/dist/core/context/tool-eviction.js

@@ -1,55 +0,0 @@
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-export function evictByLRU(entries, targetTokens) {
-    const sorted = [...entries].sort((a, b) => a.usedAt.localeCompare(b.usedAt));
-    const total = sorted.reduce((sum, e) => sum + e.tokensEst, 0);
-    if (total <= targetTokens) {
-        return {
-            evicted: [],
-            kept: sorted.map((e) => e.id),
-            freedTokens: 0,
-        };
-    }
-    const evicted = [];
-    const kept = [];
-    let freedTokens = 0;
-    let remaining = total;
-    for (const entry of sorted) {
-        if (remaining > targetTokens) {
-            evicted.push(entry.id);
-            freedTokens += entry.tokensEst;
-            remaining -= entry.tokensEst;
-        }
-        else {
-            kept.push(entry.id);
-        }
-    }
-    return { evicted, kept, freedTokens };
-}
-export function evictByContentClass(entries, rules, now = new Date()) {
-    const ruleByTool = new Map(rules.map((r) => [r.tool, r]));
-    const nowMs = now.getTime();
-    const evicted = [];
-    const kept = [];
-    let freedTokens = 0;
-    for (const entry of entries) {
-        const rule = ruleByTool.get(entry.tool);
-        if (!rule) {
-            kept.push(entry.id);
-            continue;
-        }
-        const ageMs = nowMs - new Date(entry.ts).getTime();
-        const tooOld = ageMs > rule.maxAgeMs;
-        const tooBig = entry.tokensEst > rule.maxTokens;
-        if (tooOld || tooBig) {
-            evicted.push(entry.id);
-            freedTokens += entry.tokensEst;
-        }
-        else {
-            kept.push(entry.id);
-        }
-    }
-    return { evicted, kept, freedTokens };
-}
-//# sourceMappingURL=tool-eviction.js.map