@pugi/cli 0.1.0-beta.24 → 0.1.0-beta.25

package/dist/core/repo-map/formatter.js

@@ -0,0 +1,145 @@
+/**
+ * Default byte cap for the engine system-prompt injection. The L28
+ * spec calls for 2000 tokens; conservatively that is ~8 KB of UTF-8
+ * (rough Claude tokeniser ratio: ~4 chars per token). We cap at 8 KB
+ * so the formatted block stays under the token budget across every
+ * supported model family without per-model accounting.
+ */
+export const DEFAULT_FORMAT_BYTES_CAP = 8 * 1024;
+/**
+ * Maximum symbols per row. The engine row format is:
+ *
+ *   `- path/to/file.ts — summary line — exports: Foo(class), bar(fn)`
+ *
+ * Beyond 6 symbols the row grows past the readable column budget and
+ * the additional names rarely move the needle for the model — the
+ * exports tail is signal-bearing only for the first few entries
+ * anyway (`index.ts` re-exports tend к pile up).
+ */
+export const MAX_SYMBOLS_PER_ROW = 6;
+/**
+ * Render the repo-map text. The implementation is intentionally split
+ * into:
+ *
+ *   - `prioritise(...)` — pure sort + filter, fully testable in
+ *     isolation, no I/O of any kind.
+ *   - `renderRow(...)`  — one file's row, byte-counted.
+ *   - main loop — assembles header + rows + footer, respecting cap.
+ *
+ * The split lets the spec assert each stage in isolation (priority
+ * order, single-row shape, truncation arithmetic).
+ */
+export function formatRepoMap(extracts, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_FORMAT_BYTES_CAP;
+    const omitHeader = options.omitHeader === true;
+    const prioritised = prioritise(extracts);
+    const header = omitHeader
+        ? ''
+        : `## Repo map\n\n${prioritised.length} source files indexed.\n\n`;
+    const headerBytes = byteLength(header);
+    if (headerBytes >= maxBytes) {
+        // Cap is smaller than even the header — emit nothing rather than
+        // a truncated header that the engine cannot parse.
+        return {
+            text: '',
+            filesIncluded: 0,
+            filesTotal: extracts.length,
+            bytes: 0,
+            truncated: extracts.length > 0,
+        };
+    }
+    const rows = [];
+    let bytesUsed = headerBytes;
+    let filesIncluded = 0;
+    let truncated = false;
+    for (let i = 0; i < prioritised.length; i += 1) {
+        const row = renderRow(prioritised[i]);
+        const rowBytes = byteLength(row);
+        // Reserve space for the footer (`\n... N more files\n`). We
+        // overestimate at 64 bytes — the exact number depends on the
+        // file count digits but 64 covers any realistic case.
+        const footerReserve = i + 1 < prioritised.length ? 64 : 0;
+        if (bytesUsed + rowBytes + footerReserve > maxBytes) {
+            truncated = true;
+            break;
+        }
+        rows.push(row);
+        bytesUsed += rowBytes;
+        filesIncluded += 1;
+    }
+    let text = header + rows.join('');
+    if (truncated) {
+        const omitted = prioritised.length - filesIncluded;
+        text += `\n... ${omitted} more file${omitted === 1 ? '' : 's'}\n`;
+    }
+    return {
+        text,
+        filesIncluded,
+        filesTotal: extracts.length,
+        bytes: byteLength(text),
+        truncated,
+    };
+}
+/* ----------------------------- helpers ----------------------------- */
+/**
+ * Sort the extracts by (exported-symbol count desc, path asc). The
+ * engine cares about the public surface; a file with 12 exported
+ * symbols carries more signal than 50 private helpers.
+ */
+export function prioritise(extracts) {
+    return [...extracts].sort((a, b) => {
+        const expA = countExports(a);
+        const expB = countExports(b);
+        if (expA !== expB)
+            return expB - expA;
+        return a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0;
+    });
+}
+function countExports(extract) {
+    let n = 0;
+    for (const sym of extract.symbols)
+        if (sym.exported)
+            n += 1;
+    return n;
+}
+/**
+ * Render a single file row. Format:
+ *
+ *   `- path/to/file.ts — summary — exports: Foo(class), bar(fn), Baz(type)`
+ *
+ * When there are no exported symbols, the `exports:` tail is dropped.
+ * When there is no summary, the dash separator is dropped.
+ */
+export function renderRow(extract) {
+    const exported = extract.symbols.filter((s) => s.exported);
+    const symbolsTail = exported.length > 0
+        ? ` — exports: ${formatSymbolList(exported.slice(0, MAX_SYMBOLS_PER_ROW))}`
+        : '';
+    const summaryTail = extract.summary ? ` — ${extract.summary}` : '';
+    return `- ${extract.relPath}${summaryTail}${symbolsTail}\n`;
+}
+function formatSymbolList(symbols) {
+    return symbols.map((s) => `${s.name}(${shortKind(s.kind)})`).join(', ');
+}
+function shortKind(kind) {
+    switch (kind) {
+        case 'function':
+            return 'fn';
+        case 'class':
+            return 'class';
+        case 'interface':
+            return 'iface';
+        case 'type':
+            return 'type';
+        case 'enum':
+            return 'enum';
+        case 'const':
+            return 'const';
+        case 'heading':
+            return 'h';
+    }
+}
+function byteLength(s) {
+    return Buffer.byteLength(s, 'utf8');
+}
+//# sourceMappingURL=formatter.js.map

package/dist/core/repo-map/scanner.js

@@ -0,0 +1,211 @@
+/**
+ * Repo-map scanner — Leak L28 (2026-05-27).
+ *
+ * Walks the workspace via `fs.readdirSync` (sync, depth-first), filters
+ * to a recognised set of source-language extensions, and applies the
+ * shared `PugiIgnore` matcher so the same exclusion rules used by the
+ * three-tier context skeleton also gate the repo-map.
+ *
+ * Why a stand-alone scanner (vs. reusing the α6.5 skeleton walker):
+ *
+ *   1. The skeleton walker emits a flat `IndexArtifact[]` of every
+ *      ignore-respecting file (markdown, configs, schemas, etc.) for
+ *      the working-set heuristic. The repo-map ONLY needs source
+ *      files — markdown headings and JSON keys are not "definitions"
+ *      in the L28 sense. Filtering downstream is cheap, but the
+ *      scanner gets to short-circuit on extension before stat'ing
+ *      the file, which matters for monorepos with thousands of
+ *      non-source artefacts (lockfiles, schemas, fixtures).
+ *
+ *   2. We need mtime + size per file so `cache.ts` can invalidate
+ *      stale entries without re-parsing. The skeleton walker
+ *      surfaces only paths.
+ *
+ *   3. The L28 contract caps the walk at `MAX_SRC_FILES` (5000) and
+ *      individual files at `MAX_FILE_BYTES` (200 KiB). When the cap
+ *      trips the scanner returns a `{ skipped: 'too-large' }`
+ *      verdict rather than partial data — the consumer must decide
+ *      whether to fall back to a no-op map or surface a hint к the
+ *      operator. Surfacing partial data would silently bias the
+ *      injected summary toward whichever subtree the walker happened
+ *      to traverse first.
+ *
+ * The output is sorted (POSIX path string compare) so two runs over
+ * the same workspace produce byte-identical `repo-map.json` caches —
+ * `cache.ts` relies on stable ordering for its hash-free freshness
+ * check. POSIX-style separators are used in `relPath` regardless of
+ * platform so the cache file stays portable.
+ *
+ * Pure module surface: no logging, no network. Errors during readdir
+ * on a single subtree (permission denied, symlink loop) are swallowed
+ * and the walker continues — repo-map is a best-effort context
+ * enrichment, never a gate.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, posix, relative, resolve, sep } from 'node:path';
+/**
+ * Hard ceiling on total source files surfaced by a single scan. The
+ * engine context budget is the binding constraint — a 5K-file repo
+ * already overflows the 2K-token injection cap so going higher buys
+ * nothing but walker latency. Repos above the cap fall back к the
+ * `{ skipped: 'too-large' }` verdict.
+ */
+export const MAX_SRC_FILES = 5000;
+/**
+ * Per-file size cap. Files larger than this are skipped — they are
+ * almost always generated (compiled JS, vendored libs, encoded blobs)
+ * and add noise without signal. The 200 KiB threshold mirrors the
+ * α6.5 skeleton walker's own `MAX_FILE_BYTES` so the two scans agree
+ * on "what counts as a source file".
+ */
+export const MAX_FILE_BYTES = 200 * 1024;
+/**
+ * Source-language extensions the extractor knows how to parse. Adding
+ * a language here without a matching extractor branch is a silent
+ * no-op (the file shows up в the scan but extracts zero symbols);
+ * the spec asserts the symmetry so a future PR cannot drift the two
+ * lists out of sync.
+ */
+export const SUPPORTED_EXTENSIONS = Object.freeze([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.md',
+    '.mdx',
+]);
+const defaultReaddir = (path) => readdirSync(path, { withFileTypes: true });
+const defaultStat = (path) => {
+    const s = statSync(path);
+    return { size: s.size, mtimeMs: s.mtimeMs };
+};
+/**
+ * Walk the workspace once and return every source file the extractor
+ * is willing to parse. The function is deliberately synchronous —
+ * the underlying walks are CPU-bound, не I/O-bound, and the sync
+ * call avoids the promise overhead that dominates for thousands of
+ * small files. The L28 engine boot path runs this on a Node `setImmediate`
+ * so the main thread is not blocked.
+ */
+export function scanRepoForMap(options) {
+    const root = resolve(options.root);
+    const readdir = options.readdir ?? defaultReaddir;
+    const stat = options.stat ?? defaultStat;
+    const maxFiles = options.maxFiles ?? MAX_SRC_FILES;
+    const maxFileBytes = options.maxFileBytes ?? MAX_FILE_BYTES;
+    const ignore = options.ignore;
+    const files = [];
+    let walked = 0;
+    let skippedLarge = 0;
+    let skippedIgnored = 0;
+    let tooLarge = false;
+    /**
+     * Depth-first recursion. We push dirs into a manual stack instead of
+     * recursing in JS because deep monorepos (Nx with 100+ packages)
+     * have approached the v8 default stack limit on Windows runners
+     * before; an explicit stack is one less thing to debug.
+     */
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdir(dir);
+        }
+        catch {
+            // Permission denied / symlink loop / mid-flight delete — keep
+            // walking. Repo-map is best-effort context, never a gate.
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            const isDir = entry.isDirectory();
+            if (ignore.isIgnored(abs, isDir)) {
+                skippedIgnored += 1;
+                continue;
+            }
+            if (isDir) {
+                stack.push(abs);
+                continue;
+            }
+            if (!entry.isFile()) {
+                // Symlinks, sockets, FIFOs etc. Skip silently — they are not
+                // source code and stat'ing them can throw on broken links.
+                continue;
+            }
+            walked += 1;
+            const ext = extOf(entry.name);
+            if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+                continue;
+            }
+            let statResult;
+            try {
+                statResult = stat(abs);
+            }
+            catch {
+                // File vanished between readdir and stat — skip.
+                continue;
+            }
+            if (statResult.size > maxFileBytes) {
+                skippedLarge += 1;
+                continue;
+            }
+            // Workspace-relative POSIX path. `relative` returns the host
+            // separator on Windows; normalise to forward slashes so the
+            // cache file is portable.
+            const rel = relative(root, abs).split(sep).join(posix.sep);
+            files.push({
+                relPath: rel,
+                absPath: abs,
+                ext,
+                sizeBytes: statResult.size,
+                mtimeMs: statResult.mtimeMs,
+            });
+            if (files.length > maxFiles) {
+                tooLarge = true;
+                break;
+            }
+        }
+        if (tooLarge)
+            break;
+    }
+    if (tooLarge) {
+        return {
+            ok: false,
+            root,
+            skipped: {
+                reason: 'too-large',
+                walked,
+            },
+        };
+    }
+    // Sort by POSIX path for stable cache output. Two runs over the
+    // same workspace yield byte-identical JSON so the cache hash check
+    // is a simple `mtime + size` per entry without a content digest.
+    files.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+    return {
+        ok: true,
+        root,
+        files,
+        stats: {
+            walked,
+            kept: files.length,
+            skippedLarge,
+            skippedIgnored,
+        },
+    };
+}
+/**
+ * Lowercase extension including the leading dot, or '' when the
+ * filename has no extension. Mirrors `node:path.extname` semantics —
+ * inlined so the scanner has zero per-iteration call overhead.
+ */
+function extOf(name) {
+    const dot = name.lastIndexOf('.');
+    if (dot < 0 || dot === 0)
+        return '';
+    return name.slice(dot).toLowerCase();
+}
+//# sourceMappingURL=scanner.js.map

package/dist/core/session.js

@@ -18,6 +18,50 @@ export function openSession(root) {
         enabled,
     };
 }
+/**
+ * Leak L12 MVP — fire the `SessionStart` lifecycle event for all hooks
+ * declared in `~/.pugi/hooks-mvp.json`. Single-call surface; the REPL
+ * boot path invokes this once after `openSession`. Best-effort: any
+ * failure (missing config, hook spawn error) is swallowed so a
+ * misconfigured hook can never crash the REPL.
+ *
+ * Returns the number of hooks that fired (0 when no config / no
+ * matching hooks). Tests assert on the return value as the
+ * single-call invariant.
+ */
+export async function fireSessionStartMvp(session) {
+    try {
+        const { loadHooksConfig, fireHooks } = await import('./hooks/index.js');
+        // Defense-in-depth: `loadHooksConfig` is contractually non-null
+        // (returns `HooksConfig.empty(path)` when the file is absent), but
+        // the dynamic import boundary above can in principle return an
+        // unexpected shape if the module is mis-resolved at runtime. Guard
+        // the optional-chained `isEmpty()` call so a malformed loader can
+        // never raise `TypeError: Cannot read properties of undefined` and
+        // crash the REPL boot path. Belt-and-suspenders with the
+        // surrounding try/catch — the catch still swallows everything else.
+        const config = loadHooksConfig();
+        if (!config || config.isEmpty())
+            return 0;
+        const outcome = await fireHooks({
+            config,
+            event: 'SessionStart',
+            payload: {
+                event: 'SessionStart',
+                sessionId: session.id,
+                workspaceRoot: session.root,
+                startedAt: new Date().toISOString(),
+            },
+            workspaceRoot: session.root,
+        });
+        return outcome.results.length;
+    }
+    catch {
+        // SessionStart is never blocking — log nothing, return 0. A
+        // broken `hooks-mvp.json` is surfaced via `pugi hooks doctor`.
+        return 0;
+    }
+}
 export function recordCommandStarted(session, command) {
     if (!session.enabled)
         return;

package/dist/core/settings.js

@@ -88,6 +88,15 @@ const pugiSettingsSchema = z.object({
         python: z.boolean().optional(),
         go: z.boolean().optional(),
         rust: z.boolean().optional(),
+        // Leak L15 (2026-05-27): post-edit auto-diagnostics. When `true`,
+        // a successful `edit`/`write`/`multi_edit` triggers a diagnostic
+        // pull on the touched file(s) and the result is appended to the
+        // tool envelope so the model can self-correct in the same turn.
+        // Off by default — the cold-start of `typescript-language-server`
+        // is heavy enough that we opt in explicitly until dogfood proves
+        // the throughput trade is worth it. Also enabled via env var
+        // `PUGI_LSP_POST_EDIT=1` for CI / one-off operator probes.
+        postEditDiagnostics: z.boolean().optional(),
     })
         .optional(),
     // β1 Pl9 (#74) — per-command budget overrides. Optional. Partial

package/dist/runtime/cli.js

@@ -37,6 +37,7 @@ import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
 import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runStickersCommand } from './commands/stickers.js';
+import { runRepoMapCommand } from './commands/repo-map.js';
 import { runReleaseNotesCommand, defaultReleaseNotesHome, } from './commands/release-notes.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
@@ -45,6 +46,7 @@ import { BARE_MODE_BANNER, isBareMode, setBareMode, } from '../core/bare-mode/in
 import { runCostCommand } from './commands/cost.js';
 import { runShareCommand } from './commands/share.js';
 import { runSkillsCommand } from './commands/skills.js';
+import { runHooksCommand } from './commands/hooks.js';
 import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
 import { runLspCommand } from './commands/lsp.js';
@@ -93,6 +95,7 @@ const handlers = {
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
+    hooks: dispatchHooks,
     fix: runEngineTask('fix'),
     handoff,
     help,
@@ -127,6 +130,14 @@ const handlers = {
     skills: dispatchSkills,
     status,
     stickers,
+    // Leak L28 (2026-05-27): `pugi repo-map` walks the source tree,
+    // extracts top-level function / class / interface / type / enum
+    // declarations + JSDoc summaries, caches the result in
+    // `.pugi/repo-map.json`, and renders the compact markdown listing.
+    // Same builder powers the engine boot-time system-prompt injection
+    // — running the CLI command shows the operator EXACTLY what the
+    // engine would see.
+    'repo-map': dispatchRepoMap,
     // Leak L21 (2026-05-27): in-CLI feedback collector. Shares the
     // same handler as the in-REPL `/feedback` slash; the wrapper just
     // routes TTY vs non-TTY before mounting Ink.
@@ -370,6 +381,31 @@ async function dispatchStyle(args, flags, _session) {
  * The runner returns the code; we attach it to `process.exitCode` so
  * subsequent dispatch wrappers do not clobber it on success.
  */
+/**
+ * Leak L12 (2026-05-27) — `pugi hooks` top-level dispatcher (MVP).
+ *
+ * Two subcommands:
+ *   - `pugi hooks list`   — show configured hooks per event.
+ *   - `pugi hooks doctor` — validate `~/.pugi/hooks-mvp.json`.
+ *
+ * MVP scope: 2 events of 8 (SessionStart + PreToolUse). Remaining 6
+ * events (PostToolUse, UserPromptSubmit, Stop, SubagentStop,
+ * PreCompact, Notification) deferred to fast-follow PR. The runner
+ * pattern established here is reusable for those events without
+ * touching this dispatcher.
+ *
+ * Exit codes:
+ *   0 -> happy path.
+ *   1 -> config present but invalid (doctor only).
+ *   2 -> argument error / unknown subcommand.
+ */
+async function dispatchHooks(args, flags, _session) {
+    const rc = await runHooksCommand(args, {
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 async function dispatchTheme(args, flags, _session) {
     const rc = await runThemeCommand(args, {
         workspaceRoot: process.cwd(),
@@ -995,6 +1031,10 @@ function parseArgs(argv) {
         // bare invocation only surfaces new sections. Opt-in to force the
         // full bundled changelog к re-render (clears the on-disk marker).
         reset: false,
+        // Leak L28 — `--refresh` for `pugi repo-map`. Default off so a
+        // bare invocation hits the cache when mtime + size match; opt-in
+        // for a cold rebuild from the source tree.
+        refresh: false,
     };
     const args = [];
     // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
@@ -1089,6 +1129,22 @@ function parseArgs(argv) {
             // single consumer today.
             flags.reset = true;
         }
+        else if (arg === '--refresh') {
+            // Leak L28 — `pugi repo-map --refresh` busts the cache and
+            // rebuilds the AST-light summary from a cold scan. Parsed
+            // globally for symmetry with the rest of the flag grammar;
+            // `runRepoMapCommand` is the single consumer today.
+            flags.refresh = true;
+        }
+        else if (arg === '--format=json' || arg === '--format' && argv[index + 1] === 'json') {
+            // Leak L28 — `pugi repo-map --format=json` is a per-command
+            // synonym for the global `--json` flag. The L28 spec calls
+            // out the `--format=json` shape explicitly so we accept it
+            // verbatim and route through the existing JSON envelope.
+            flags.json = true;
+            if (arg === '--format')
+                index += 1;
+        }
         else if (arg === '--decompose') {
             // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
             // it. Parsed globally for symmetry with the rest of the flag
@@ -1796,6 +1852,27 @@ async function stickers(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi repo-map` — Leak L28 (2026-05-27). Builds + caches the AST-
+ * light symbol summary of the workspace. The handler is intentionally
+ * thin: argv tail tokens are honoured for `--refresh` symmetry (the
+ * global parser already sets `flags.refresh`, but accepting the flag
+ * positionally lets `pugi repo-map refresh` work too — both forms
+ * land в the same path). Exit code is always 0 (informational).
+ *
+ * The same builder is invoked lazily on engine boot when `--bare` is
+ * not set; running the CLI command shows the operator EXACTLY what
+ * the engine would inject into the system prompt.
+ */
+async function dispatchRepoMap(args, flags, _session) {
+    const refresh = flags.refresh || args.includes('--refresh') || args.includes('refresh');
+    await runRepoMapCommand({
+        cwd: process.cwd(),
+        refresh,
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * `pugi feedback` — Leak L21 (2026-05-27). In-CLI feedback collector.
  *
@@ -4188,6 +4265,19 @@ function runEngineTask(kind) {
                     process.stderr.write(`pugi ${label}: MCP registry shutdown reported error — ${error.message}\n`);
                 });
             }
+            // Leak L15 (2026-05-27) — tear down any LSP servers warmed up
+            // by the post-edit diagnostics cache. The cache is per-process
+            // and survives across multiple tool calls; without this hook a
+            // `pugi code ...` invocation would leak a tsserver process when
+            // the Node host exits. The dynamic import keeps the cache module
+            // out of the cold path for runs that never touch LSP.
+            try {
+                const { stopAllLspClients } = await import('../core/lsp/cache.js');
+                await stopAllLspClients();
+            }
+            catch (error) {
+                process.stderr.write(`pugi ${label}: LSP cache shutdown reported error — ${error.message}\n`);
+            }
         }
     };
 }