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

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

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
@@ -36,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';
@@ -44,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';
@@ -92,6 +95,7 @@ const handlers = {
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
+    hooks: dispatchHooks,
     fix: runEngineTask('fix'),
     handoff,
     help,
@@ -126,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.
@@ -151,6 +163,12 @@ const handlers = {
     // handler, same flags. Operators trained on Claude Code expect either
     // verb to surface the per-model token + USD table.
     usage: dispatchCost,
+    // Leak L27 (2026-05-27): `pugi update` — channel-aware npm registry
+    // probe + optional npm install shell-out. Same handler powers the
+    // in-REPL `/update` slash via the session module. R2 atomic swap
+    // deferred to Phase 2 per the sprint plan; npm is the single
+    // distribution channel today.
+    update: dispatchUpdate,
     version,
     web: dispatchWeb,
     whoami,
@@ -363,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(),
@@ -988,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
@@ -1082,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
@@ -1503,6 +1566,32 @@ const COMMAND_HELP_BODIES = {
         'Useful in shell scripts that need a human-confirm before a destructive',
         'step. Exits 0 on yes, 1 on no, 2 on cancel.',
     ],
+    update: [
+        'pugi update — channel-aware @pugi/cli update check + install.',
+        '',
+        'Polls npm registry dist-tags for a newer @pugi/cli on the configured',
+        'channel (stable / beta / canary). Without flags, prints the install',
+        'command and exits. With --apply, shells out to `npm install -g …`.',
+        '',
+        '  --check                 Non-interactive probe + JSON envelope.',
+        '  --channel <name>        Switch channel (stable | beta | canary) and probe.',
+        '                          Persisted to ~/.pugi/config.json::updateChannel.',
+        '  --apply                 Shell out to `npm install -g @pugi/cli@<tag>`',
+        '                          after a y/n confirmation.',
+        '  --yes, -y               Skip the confirmation prompt on --apply.',
+        '  --json                  Force JSON envelope (auto-on with --check).',
+        '',
+        'Channel mapping: stable -> npm `latest`, beta -> npm `beta`,',
+        'canary -> npm `next`. Default channel is `beta` (Pugi currently',
+        'ships beta releases only).',
+        '',
+        'Also available as /update from inside the REPL — slash form NEVER',
+        'spawns npm (would corrupt the running binary); it only prints the',
+        'install command for the operator к run after exit.',
+        '',
+        'R2 atomic swap (sprint plan L27) deferred к Phase 2 — npm is the',
+        'only distribution channel today.',
+    ],
     stickers: [
         'pugi stickers — show a Pugi brand sticker (gimmick).',
         '',
@@ -1668,6 +1757,53 @@ async function doctor(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi update` — Leak L27 (2026-05-27). Channel-aware npm registry
+ * probe + optional shell-out to `npm install -g @pugi/cli@<tag>`.
+ *
+ * Argument grammar:
+ *   pugi update                       -> probe + offer install command
+ *   pugi update --check               -> probe + JSON envelope (scripted)
+ *   pugi update --channel <name>      -> persist channel + probe
+ *   pugi update --apply [--yes]       -> probe + shell out to npm
+ *   pugi update --json                -> JSON envelope (any subcommand)
+ *
+ * The handler delegates to `runUpdateCommand` in
+ * `runtime/commands/update.ts` so the in-REPL `/update` slash + the
+ * top-level shell command share one channel-resolution + persistence
+ * + probe surface. Exit codes:
+ *
+ *   0 — happy path (no update OR update completed OR probe-only)
+ *   1 — install / probe failure with structured error
+ *   2 — argument error (unknown flag, unknown channel)
+ */
+async function dispatchUpdate(args, flags, _session) {
+    const { parseUpdateArgs, runUpdateCommand, defaultSpawnInstaller } = await import('./commands/update.js');
+    const parsed = parseUpdateArgs(args, { jsonDefault: flags.json });
+    if ('error' in parsed) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    const envelope = await runUpdateCommand({
+        cwd: process.cwd(),
+        home: homedir(),
+        env: process.env,
+        flags: parsed,
+        promptConfirm: async (question) => {
+            const answer = await readSingleChoice(`${question} `);
+            return /^y(es)?$/i.test(answer.trim());
+        },
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        spawnInstaller: defaultSpawnInstaller,
+    });
+    if (!envelope.ok) {
+        // `apply_cancelled_by_operator` is a benign decline; we still
+        // surface a non-zero exit so scripted callers can detect that the
+        // operator did not green-light the install.
+        process.exitCode = 1;
+    }
+}
 /**
  * `pugi status` — Leak L34 (2026-05-27). Concise session-state probe
  * mirroring Claude Code's `/status`. Distinct from `pugi doctor`
@@ -1716,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.
  *
@@ -4108,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`);
+            }
         }
     };
 }