@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

package/dist/core/file-cache.js

@@ -1,6 +1,45 @@
+/**
+ * Per-session file-read cache + stale-read gate.
+ *
+ * ( upstream `FileEditTool.ts`, gap analysis
+ * §5.1): every FileEdit must validate the operator's last-known view of
+ * the file before mutating disk. The gate compares BOTH `mtimeMs` and
+ * `sha256(content)` of the file on disk against the record captured at
+ * read time:
+ *
+ *  - mtimeMs is a cheap fast-path. If the inode mtime hasn't moved
+ *    since the read, the content hash cannot have changed (barring a
+ *    filesystem with hash-on-mtime-skew bugs) and we can short-circuit.
+ *  - sha256 is the authoritative gate. A user editor that writes back
+ *    identical content can leave mtime untouched on some filesystems
+ *    (atomic-rename with preserved metadata), and conversely `touch`
+ *    bumps mtime without changing content. Hash is the truth.
+ *
+ * Both signals must agree for the gate to PASS. Any divergence => STALE
+ * => refuse the edit, force the model to re-read.
+ *
+ * Cache lifetime: per-session. `FileReadCache.clear()` is called at
+ * session.end (see `core/session.ts`). The cache is intentionally NOT
+ * durable across sessions — a re-read after restart is cheap and stale
+ * cross-session entries would themselves be a soundness hazard.
+ *
+ * Exception: writeTool for create-new (path doesn't exist on disk) does
+ * not consult the cache. Creating a brand new file has no "last-known
+ * view" to invalidate.
+ */
 import { createHash } from 'node:crypto';
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
+export class StaleReadError extends Error {
+    reason;
+    path;
+    constructor(path, reason, detail) {
+        super(`stale_read: ${path} — ${detail}. Re-read the file before editing.`);
+        this.name = 'StaleReadError';
+        this.reason = reason;
+        this.path = path;
+    }
+}
 export class FileReadCache {
     records = new Map();
     set(record) {
@@ -9,6 +48,70 @@ export class FileReadCache {
     get(root, path) {
         return this.records.get(resolve(root, path));
     }
+    /**
+     * Validate a candidate edit against the cached read record. Returns
+     * a tagged-union: `{ stale: false }` when the edit may proceed, or
+     * `{ stale: true, reason, detail }` when the gate must refuse.
+     *
+     * Pure function over the cache + supplied `currentMtimeMs` /
+     * `currentContent` — does NOT touch disk. Callers (editTool /
+     * writeTool) do their own `statSync` + `readFileSync` because they
+     * also need the content for the diff/edit itself.
+     *
+     * @param root          workspace root (used to resolve relative path)
+     * @param path          workspace-relative file path
+     * @param currentMtimeMs `fs.statSync().mtimeMs` of the on-disk file
+     * @param currentContent UTF-8 contents of the on-disk file
+     */
+    validate(root, path, currentMtimeMs, currentContent) {
+        const record = this.get(root, path);
+        if (!record) {
+            return {
+                stale: true,
+                reason: 'no_prior_read',
+                detail: 'file must be read first',
+            };
+        }
+        // Fast-path: mtime hasn't moved. Hash check is redundant in the
+        // common case but cheap, so we still verify below. Skipping hash
+        // when mtime matches would allow a subtle bug class (in-place
+        // writers that preserve mtime) to slip through.
+        if (currentMtimeMs > record.mtimeMs) {
+            // mtime advanced — confirm with hash before flagging. A bump
+            // without a content change (e.g. `touch`) shouldn't fire stale.
+            const currentHash = hashContent(currentContent);
+            if (currentHash !== record.sha256) {
+                return {
+                    stale: true,
+                    reason: 'mtime_drift',
+                    detail: `mtime advanced (${record.mtimeMs} → ${currentMtimeMs}) and content hash diverged`,
+                };
+            }
+            // mtime bumped but content identical — treat as fresh. The cache
+            // entry's mtime is intentionally NOT refreshed here; the next
+            // edit will hit the same path and the gate will keep agreeing.
+            return { stale: false };
+        }
+        // mtime hasn't moved — hash MUST still match the record. A
+        // mismatch is a filesystem-level inconsistency or an in-place
+        // editor that preserves mtime; either way, refuse.
+        const currentHash = hashContent(currentContent);
+        if (currentHash !== record.sha256) {
+            return {
+                stale: true,
+                reason: 'hash_drift',
+                detail: 'content hash diverged from last read (mtime unchanged)',
+            };
+        }
+        return { stale: false };
+    }
+    /**
+     * Drop every cached record. Called by session.end so a fresh REPL
+     * session never inherits stale cross-session entries.
+     */
+    clear() {
+        this.records.clear();
+    }
 }
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
@@ -26,4 +129,13 @@ export function createReadRecord(root, path, content, source) {
         source,
     };
 }
+/**
+ * Convenience helper: does this absolute path exist on disk? Wraps the
+ * existsSync import so file-tools.ts can decide between create-new
+ * (skip stale gate) and update-existing (apply stale gate) without
+ * pulling in another fs import.
+ */
+export function pathExists(absolutePath) {
+    return existsSync(absolutePath);
+}
 //# sourceMappingURL=file-cache.js.map

package/dist/core/flatten/flatten-repo.js

@@ -0,0 +1,439 @@
+/**
+ * `pugi flatten` — single-page repository renderer (backlog).
+ *
+ * Ported from karpathy/rendergit (BSD-0). License is compatible with
+ * Pugi's open-source posture so the port is permitted with any degree
+ * of source copying. The TypeScript adaptation below is structural —
+ * the data model, ignore semantics, and HTML envelope mirror the
+ * upstream Python single-file tool but the implementation is written
+ * from scratch in TypeScript-strict so it composes with our existing
+ * `loadPugiIgnore` chain, the CLI writeOutput sink, and node:test.
+ *
+ * Two output modes:
+ *  - `human` — Prism.js CDN syntax highlight + nav tree + anchor
+ *    links. Ctrl+F across the whole codebase in a single browser tab.
+ *  - `llm`  — `<repo><file path="..."><content>...</content></file>
+ *    </repo>` envelope for paste into other LLMs.
+ *
+ * Privacy: output files are chmod 600. The .pugi/flat/ directory is
+ * created with chmod 700 so an operator can drop a workspace flatten
+ * without leaking it to other UNIX accounts.
+ *
+ * Self-contained: depends only on `node:fs` / `node:path` /
+ * `node:child_process` + the workspace-local `loadPugiIgnore` matcher.
+ * No new npm deps.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, chmodSync, } from 'node:fs';
+import { basename, extname, relative, resolve, sep } from 'node:path';
+import { loadPugiIgnore, } from '../context/pugiignore.js';
+/** Default per-file byte ceiling. 200 KiB matches Karpathy's tool. */
+export const DEFAULT_MAX_FILE_SIZE = 200 * 1024;
+/**
+ * Entry point. Walks the repo, filters, renders, and (unless `stdout`)
+ * writes the result to `.pugi/flat/<basename>-<sha>.html`.
+ */
+export async function flattenRepo(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const mode = options.mode ?? 'human';
+    const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const include = options.include ?? [];
+    const exclude = options.exclude ?? [];
+    const ignore = loadPugiIgnore(cwd);
+    const files = [];
+    const skipped = [];
+    for await (const entry of walkFiles(cwd, ignore, { maxFileSize, include, exclude })) {
+        if ('reason' in entry) {
+            skipped.push(entry);
+        }
+        else {
+            files.push(entry);
+        }
+    }
+    // Stable order: lexicographic by repo-relative path so the HTML nav
+    // tree and the LLM envelope reproduce 1:1 across runs.
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    skipped.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const html = mode === 'human'
+        ? renderHumanHTML(files, skipped, basename(cwd))
+        : renderLLMXML(files, skipped, basename(cwd));
+    if (options.stdout) {
+        return { html, files, skipped };
+    }
+    const outDir = options.outDir ?? resolve(cwd, '.pugi', 'flat');
+    ensureDir(outDir);
+    const sha = options.shaOverride ?? resolveShortSha(cwd);
+    const ext = mode === 'human' ? 'html' : 'xml';
+    const fileName = `${basename(cwd)}-${sha}.${ext}`;
+    const path = resolve(outDir, fileName);
+    writeFileSync(path, html, { encoding: 'utf8', mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // best-effort; some filesystems (mounted shares) reject chmod.
+    }
+    if (options.open) {
+        tryOpenBrowser(path);
+    }
+    return { html, path, files, skipped };
+}
+/**
+ * Async generator that walks the workspace, applying the pugi-ignore
+ * chain + include/exclude filters + binary/size gate. Each yielded
+ * item is either a `FlattenedFile` (kept) or a `SkippedFile` (dropped
+ * with a reason).
+ */
+export async function* walkFiles(rootDir, ignore, filters) {
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!dir)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
+        }
+        catch {
+            continue;
+        }
+        // Sort directory listing so the walk is deterministic regardless of
+        // the underlying filesystem's readdir order.
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const ent of entries) {
+            const abs = resolve(dir, ent.name);
+            if (ignore.isIgnored(abs, ent.isDirectory()))
+                continue;
+            if (ent.isDirectory()) {
+                stack.push(abs);
+                continue;
+            }
+            if (!ent.isFile())
+                continue;
+            const relPath = toPosix(relative(rootDir, abs));
+            if (!matchesFilters(relPath, filters.include, filters.exclude))
+                continue;
+            let size;
+            try {
+                size = statSync(abs).size;
+            }
+            catch {
+                yield { path: relPath, reason: 'unreadable', size: 0 };
+                continue;
+            }
+            if (size > filters.maxFileSize) {
+                yield { path: relPath, reason: 'too_large', size };
+                continue;
+            }
+            let buf;
+            try {
+                buf = readFileSync(abs);
+            }
+            catch {
+                yield { path: relPath, reason: 'unreadable', size };
+                continue;
+            }
+            if (isBinary(buf)) {
+                yield { path: relPath, reason: 'binary', size };
+                continue;
+            }
+            yield { path: relPath, content: buf.toString('utf8'), size };
+        }
+    }
+}
+/**
+ * Binary-file heuristic. Mirrors Git's "first 8000 bytes contain a
+ * NUL" detection — simple, robust, and matches what rendergit ships.
+ */
+export function isBinary(content) {
+    const len = Math.min(content.length, 8000);
+    for (let i = 0; i < len; i += 1) {
+        if (content[i] === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Parse a `.gitignore`-shaped file into a deduped pattern list. Thin
+ * wrapper around `readFileSync` + the gitignore comment / blank-line
+ * rules. Re-exports `core/context/pugiignore`'s parser when callers
+ * want a non-layered raw read (test fixtures, CI shims).
+ */
+export function parseIgnoreFile(path) {
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const out = [];
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            if (trimmed.startsWith('#'))
+                continue;
+            out.push(trimmed);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Render the human-facing HTML page. Single document, Prism.js loaded
+ * from CDN, nav tree on the left, file sections anchored on the right.
+ *
+ * Generated structure mirrors karpathy/rendergit (BSD-0):
+ *  - <head> Prism CSS + a few inline rules for the layout
+ *  - <aside> nav tree of file paths with anchor links
+ *  - <main> one <section> per file with `<pre><code class="language-X">`
+ *  - <footer> credits the upstream tool + license
+ */
+export function renderHumanHTML(files, skipped, repoName) {
+    const title = escapeHtml(`${repoName} — pugi flatten`);
+    const nav = files
+        .map((f) => {
+        const anchor = anchorFor(f.path);
+        return `     <li><a href="#${anchor}">${escapeHtml(f.path)}</a></li>`;
+    })
+        .join('\n');
+    const skippedList = skipped.length === 0
+        ? ''
+        : `
+ <section class="skipped">
+   <h2>Skipped (${skipped.length})</h2>
+   <ul>
+${skipped
+            .map((s) => `     <li><code>${escapeHtml(s.path)}</code> — ${s.reason} (${s.size}B)</li>`)
+            .join('\n')}
+   </ul>
+ </section>`;
+    const sections = files
+        .map((f) => {
+        const lang = languageFor(f.path);
+        const anchor = anchorFor(f.path);
+        return ` <section id="${anchor}" class="file">
+   <h2><a href="#${anchor}">${escapeHtml(f.path)}</a></h2>
+   <pre><code class="language-${lang}">${escapeHtml(f.content)}</code></pre>
+ </section>`;
+    })
+        .join('\n');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8" />
+ <title>${title}</title>
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css" integrity="sha512-tN7Ec6zAFaVSG3TpNAKtk4DOHNpSwKHxxrsiw4GHKESGPs5njn/0sMCUMl2svV4wo4BK/rCP7juYz+zx+l6oeQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+ <style>
+   body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+          margin: 0; display: grid; grid-template-columns: 280px 1fr; min-height: 100vh; }
+   aside { background: #f7f7f7; border-right: 1px solid #ddd; padding: 1rem;
+           position: sticky; top: 0; height: 100vh; overflow-y: auto; }
+   aside h1 { font-size: 1rem; margin: 0 0 1rem; }
+   aside ul { list-style: none; padding: 0; margin: 0; font-family: monospace; font-size: 0.85rem; }
+   aside li { margin: 0.15rem 0; word-break: break-all; }
+   aside a { color:; text-decoration: none; }
+   aside a:hover { text-decoration: underline; }
+   main { padding: 1.5rem; max-width: 100%; overflow-x: auto; }
+   section.file { margin-bottom: 2rem; border-bottom: 1px solid #eee; padding-bottom: 1rem; }
+   section.file h2 { font-family: monospace; font-size: 0.95rem; }
+   section.file h2 a { color:; text-decoration: none; }
+   pre { background: #fafafa; padding: 1rem; border: 1px solid #eee; overflow-x: auto; }
+   code { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.85rem; }
+   section.skipped { color:; font-size: 0.85rem; border-top: 2px solid #ddd; padding-top: 1rem; }
+   footer { grid-column: 1 / -1; padding: 1rem 1.5rem; color:; font-size: 0.8rem;
+            border-top: 1px solid #eee; }
+ </style>
+</head>
+<body>
+ <aside>
+   <h1>${title}</h1>
+   <ul>
+${nav}
+   </ul>
+ </aside>
+ <main>
+${sections}
+${skippedList}
+ </main>
+ <footer>
+   Generated by <code>pugi flatten</code>. Ported from
+   <a href="https://github.com/karpathy/rendergit">karpathy/rendergit</a> (BSD-0).
+ </footer>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js" integrity="sha512-7Z9J3l1+EYfeaPKcGXu3MS/7T+w19WtKQY/n+xzmw4hZhJ9tyYmcUS+4QqAlzhicE5LAfMQSF3iFTK9bQdTxXg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-typescript.min.js" integrity="sha512-uOw7XYETzS/DPmmirpP5UCMihSDNMeyTS965J0/456OSPfxn9xEtHHjj5Q/5WefVdqyMfN/afmQnNpZd/tpkcA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-tsx.min.js" integrity="sha512-xjGCJ9YxyZBfYTCHsEjkOZMoOse1W3cKMXv1szXrxs68myuXt0YTj3/xKPar6iDMlXzTUSEqwUxprWcyp+plaw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-jsx.min.js" integrity="sha512-m3JYEI6gx5fh9jF10FjGoMzVKcV2N6nchcDcqPCdI1L3R2WQV7br2XVNR8iTLb2daOMRl3zldbcfT40xU2ntVw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js" integrity="sha512-whYhDwtTmlC/NpZlCr6PSsAaLOrfjVg/iXAnC4H/dtiHawpShhT2SlIMbpIhT/IL/NrpdMm+Hq2C13+VKpHTYw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-json.min.js" integrity="sha512-QXFMVAusM85vUYDaNgcYeU3rzSlc+bTV4JvkfJhjxSHlQEo+ig53BtnGkvFTiNJh8D+wv6uWAQ2vJaVmxe8d3w==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-yaml.min.js" integrity="sha512-6O/PZimM3TD1NN3yrazePA4AbZrPcwt1QCGJrVY7WoHDJROZFc9TlBvIKMe+QfqgcslW4lQeBzNJEJvIMC8WhA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js" integrity="sha512-AKaNmg8COK0zEbjTdMHJAPJ0z6VeNqvRvH4/d5M4sHJbQQUToMBtodq4HaV4fa+WV2UTfoperElm66c9/8cKmQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-rust.min.js" integrity="sha512-R/HpMlNfZZV6DxMhNz1dYJbBaPBVSOCqX8imo3uGUurhPDHRcXrBxkEVOjawwUwTMfOqT6t1eLYYQXIjFWCX/A==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-go.min.js" integrity="sha512-w200Nz1i9KgDNi+IpPMgpZBVRIvfVK/V5vskyHjkz7XJkVnRJcb1uNmpiHhDv0/Ln+GG2VqScKKz/1izBfg64Q==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-markdown.min.js" integrity="sha512-IHQR8J+JbQpZ1tjkHkq8Ivsgo6ovfnYbQnYzmoKCjTCQG90YVs9l+2P14DRIZ94VBrB+F86Ju4wSGOMOjfVCQQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+</body>
+</html>
+`;
+}
+/**
+ * Render the LLM-CXML envelope. Each file is wrapped in a
+ * `<file path="...">` block with the content escaped for XML.
+ */
+export function renderLLMXML(files, skipped, repoName) {
+    const blocks = files
+        .map((f) => ` <file path="${escapeXmlAttr(f.path)}" size="${f.size}">
+   <content><![CDATA[${escapeCdata(f.content)}]]></content>
+ </file>`)
+        .join('\n');
+    const skippedBlocks = skipped
+        .map((s) => ` <skipped path="${escapeXmlAttr(s.path)}" reason="${s.reason}" size="${s.size}" />`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<repo name="${escapeXmlAttr(repoName)}" generator="pugi-flatten">
+${blocks}
+${skippedBlocks}
+</repo>
+`;
+}
+// --- helpers --------------------------------------------------------------
+function matchesFilters(path, include, exclude) {
+    if (include.length > 0) {
+        let any = false;
+        for (const pat of include) {
+            if (substringOrGlob(path, pat)) {
+                any = true;
+                break;
+            }
+        }
+        if (!any)
+            return false;
+    }
+    for (const pat of exclude) {
+        if (substringOrGlob(path, pat))
+            return false;
+    }
+    return true;
+}
+/**
+ * Lightweight matcher: `*` glob OR plain substring. We deliberately
+ * avoid a full glob library here — the use case is operator-driven
+ * `--include=src/` and `--exclude=test/` overrides, not arbitrary
+ * gitignore semantics (which already run upstream in `loadPugiIgnore`).
+ */
+function substringOrGlob(path, pattern) {
+    if (pattern.length === 0)
+        return false;
+    if (!pattern.includes('*'))
+        return path.includes(pattern);
+    const re = new RegExp('^' +
+        pattern
+            .split('*')
+            .map((part) => escapeRegex(part))
+            .join('.*') +
+        '$');
+    return re.test(path);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function toPosix(p) {
+    return sep === '/' ? p : p.split(sep).join('/');
+}
+function anchorFor(path) {
+    return 'f-' + path.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function escapeXmlAttr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * Escape a payload for inclusion inside a `<![CDATA[ ... ]]>` block.
+ * CDATA cannot contain the literal `]]>`; the workaround is to split
+ * the sequence across two CDATA sections.
+ */
+function escapeCdata(s) {
+    return s.replace(/]]>/g, ']]]]><![CDATA[>');
+}
+const LANG_BY_EXT = {
+    '.ts': 'typescript',
+    '.tsx': 'tsx',
+    '.js': 'javascript',
+    '.jsx': 'jsx',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.py': 'python',
+    '.rs': 'rust',
+    '.go': 'go',
+    '.json': 'json',
+    '.yml': 'yaml',
+    '.yaml': 'yaml',
+    '.md': 'markdown',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.zsh': 'bash',
+    '.html': 'markup',
+    '.css': 'css',
+    '.sql': 'sql',
+    '.toml': 'toml',
+};
+function languageFor(path) {
+    const ext = extname(path).toLowerCase();
+    return LANG_BY_EXT[ext] ?? 'plaintext';
+}
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return;
+    }
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // ignore — best-effort tightening of an existing dir.
+    }
+}
+function resolveShortSha(cwd) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+        });
+        const trimmed = out.trim();
+        if (/^[0-9a-f]{4,40}$/i.test(trimmed))
+            return trimmed;
+    }
+    catch {
+        // not a git repo, or git missing — fall through.
+    }
+    // Fall back to a sortable timestamp so the filename stays unique.
+    const now = new Date();
+    return [
+        now.getUTCFullYear().toString().slice(2),
+        String(now.getUTCMonth() + 1).padStart(2, '0'),
+        String(now.getUTCDate()).padStart(2, '0'),
+        String(now.getUTCHours()).padStart(2, '0'),
+        String(now.getUTCMinutes()).padStart(2, '0'),
+    ].join('');
+}
+function tryOpenBrowser(path) {
+    try {
+        const bin = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        execFileSync(bin, [path], { stdio: 'ignore' });
+    }
+    catch {
+        // best-effort; absence of a browser opener is non-fatal.
+    }
+}
+//# sourceMappingURL=flatten-repo.js.map

package/dist/core/format/osc8-link.js

@@ -0,0 +1,28 @@
+/**
+ * OSC 8 hyperlink helpers — turns workspace-relative file paths into
+ * clickable links in modern terminals (iTerm2, kitty, Windows Terminal,
+ * VS Code integrated terminal, Alacritty, WezTerm). Dumb terminals and
+ * pipes ignore the escape sequence and render only the visible label.
+ *
+ * CEO P2 #38 — artifact linking. Triggers ONLY when:
+ *  - stdout is a TTY
+ *  - PUGI_ARTIFACT_LINKS_DISABLE !== '1'
+ *  - NO_COLOR is not set
+ */
+import { resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const ESC = '';
+export function linkArtifact(pathRel, opts) {
+    const env = opts.env ?? process.env;
+    const tty = opts.isTty ?? process.stdout.isTTY ?? false;
+    if (!tty)
+        return pathRel;
+    if (env['PUGI_ARTIFACT_LINKS_DISABLE'] === '1')
+        return pathRel;
+    if (env['NO_COLOR'] && env['NO_COLOR'].length > 0)
+        return pathRel;
+    const abs = isAbsolute(pathRel) ? pathRel : resolve(opts.workspaceRoot, pathRel);
+    const url = pathToFileURL(abs).href;
+    return `${ESC}]8;;${url}${ESC}\\${pathRel}${ESC}]8;;${ESC}\\`;
+}
+//# sourceMappingURL=osc8-link.js.map