@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

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

@@ -0,0 +1,533 @@
+/**
+ * Tier 0 repo skeleton builder - α6.5 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 #380).
+    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 #380). 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 #380).
+        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
+ * Claude Code 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