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

package/dist/runtime/commands/repo-map.js

@@ -0,0 +1,95 @@
+/**
+ * `pugi repo-map` — Leak L28 (2026-05-27).
+ *
+ * Builds a compact AST-light summary of the workspace's source surface
+ * (top-level function / class / interface / type / enum declarations
+ * plus the leading JSDoc / markdown summary line) and renders it as
+ * a markdown listing. The same builder backs the engine boot-time
+ * system-prompt injection — running `pugi repo-map` shows the operator
+ * EXACTLY what the engine would inject.
+ *
+ * The command surface mirrors the L28 spec:
+ *
+ *   `pugi repo-map`             build + show (cache hit when fresh)
+ *   `pugi repo-map --refresh`   bust cache + rebuild from scratch
+ *   `pugi repo-map --format=json` machine-readable envelope
+ *
+ * Exit code is always 0 — the command is informational, not a gate.
+ * The `--json` envelope carries an `ok: false` branch when the repo is
+ * too large to map (the L28 5000-file ceiling), so scripted callers
+ * can detect the skip without parsing prose.
+ *
+ * The handler is awaited even though the underlying pipeline is sync,
+ * matching the pattern of every other `run*Command` (stickers, status,
+ * doctor) so future async paths (remote cache pull) drop в without
+ * changing the call sites.
+ */
+import { buildAndFormatRepoMap } from '../../core/repo-map/build.js';
+/**
+ * Run the command. Always resolves к the structured envelope so the
+ * caller can chain into a status table. Exit code is set к 0 in every
+ * branch — the command is informational.
+ */
+export async function runRepoMapCommand(ctx) {
+    const result = buildAndFormatRepoMap({
+        root: ctx.cwd,
+        refresh: ctx.refresh === true,
+        writeCache: ctx.writeCache !== false,
+        formatBytesCap: ctx.formatBytesCap,
+        omitHeader: false,
+    });
+    if (!result.build.ok) {
+        const payload = {
+            ok: false,
+            command: 'repo-map',
+            root: result.build.root,
+            reason: result.build.reason,
+            walked: result.build.walked,
+        };
+        const text = result.build.reason === 'too-large'
+            ? `repo-map skipped: workspace exceeds the ${result.build.walked}-file ceiling. Tighten .pugiignore and re-run.`
+            : `repo-map skipped: no workspace at ${result.build.root}.`;
+        ctx.writeOutput(payload, text);
+        // Informational — never a gate.
+        process.exitCode = 0;
+        return payload;
+    }
+    const build = result.build;
+    if (!build.ok) {
+        // TS narrowing — handled above.
+        throw new Error('unreachable');
+    }
+    const format = result.format;
+    const payload = {
+        ok: true,
+        command: 'repo-map',
+        root: build.root,
+        stats: {
+            filesScanned: build.scanStats.walked,
+            filesIncluded: format.filesIncluded,
+            filesRebuilt: build.diffStats.rebuilt,
+            filesReused: build.diffStats.reused,
+            filesDropped: build.diffStats.dropped,
+            skippedLarge: build.scanStats.skippedLarge,
+            skippedIgnored: build.scanStats.skippedIgnored,
+            bytes: format.bytes,
+            truncated: format.truncated,
+        },
+        cachePath: build.cachePath,
+        cacheWritten: build.cacheWritten,
+        text: format.text,
+    };
+    // The text surface IS the formatted markdown. We append a one-line
+    // stats footer so the operator sees the cache-hit ratio at a glance
+    // (engine context cache is opaque otherwise) — kept off the JSON
+    // payload so machine consumers do not have to skip a trailer.
+    const footer = formatFooter(payload.stats);
+    ctx.writeOutput(payload, `${format.text}\n${footer}`);
+    process.exitCode = 0;
+    return payload;
+}
+function formatFooter(stats) {
+    const truncatedHint = stats.truncated ? ' (truncated к budget)' : '';
+    return `${stats.filesIncluded} files · ${stats.filesRebuilt} rebuilt · ${stats.filesReused} cache hit · ${stats.bytes} bytes${truncatedHint}`;
+}
+//# sourceMappingURL=repo-map.js.map

package/dist/runtime/commands/resume.js

@@ -0,0 +1,118 @@
+/**
+ * `/resume` runtime — leak L9 (2026-05-27).
+ *
+ * Light runner that augments the existing `pugi resume` surface in
+ * `runtime/cli.ts` with rewind-aware session listings. The full
+ * REPL-mount path stays in cli.ts (it owns the credential resolver +
+ * Ink renderer); this module exposes the data-access helpers the slash
+ * dispatcher + the cli.ts handler share.
+ *
+ * Why a separate runner rather than inlining inside cli.ts: the in-REPL
+ * `/resume` slash already holds the writer lock, so it cannot use the
+ * read-only view path the top-level command relies on. The split lets
+ * the slash code call `listResumableSessionsForRepl` (which routes
+ * through the live store) while the shell code calls
+ * `listResumableSessionsReadOnly` (which uses the no-lock view).
+ */
+import { homedir } from 'node:os';
+import { slugForCwd } from '../../core/repl/history.js';
+import { applyAllMasks, listResumableSessions, } from '../../core/checkpoint/resumer.js';
+import { findLatestActiveRewind } from '../../core/checkpoint/rewinder.js';
+/**
+ * Read-only `pugi resume --list` path. Uses the no-lock view so a live
+ * REPL writing in the same project does not block the listing.
+ */
+export async function runResumeList(ctx) {
+    const slug = slugForCwd(ctx.workspaceRoot);
+    const baseInput = {
+        projectSlug: slug,
+        limit: ctx.limit ?? 10,
+        home: ctx.home ?? homedir(),
+    };
+    const sessions = await listResumableSessions(baseInput);
+    const rows = sessions.map(toResumeListRow);
+    const text = renderResumeList(rows, slug);
+    ctx.writeOutput({
+        command: 'resume',
+        status: rows.length === 0 ? 'empty' : 'listed',
+        projectSlug: slug,
+        sessions: rows,
+    }, text);
+    return {
+        command: 'resume',
+        status: rows.length === 0 ? 'empty' : 'listed',
+        projectSlug: slug,
+        sessions: rows,
+    };
+}
+/**
+ * In-REPL `/resume` slash variant. The live REPL holds the writer
+ * lockfile so we cannot reuse the read-only view path; this routes
+ * through the store the session module already opened. Returns the
+ * sessions list directly so the slash handler can render system lines.
+ */
+export async function runResumeListForRepl(input) {
+    const slug = slugForCwd(input.workspaceRoot);
+    const limit = input.limit ?? 10;
+    const sessionRows = await input.store.listSessions({
+        project: slug,
+        limit,
+        status: 'active+archived',
+    });
+    const out = [];
+    for (const row of sessionRows) {
+        const events = await input.store.loadEvents(row.id);
+        const visible = applyAllMasks(events);
+        const latest = findLatestActiveRewind(events);
+        out.push({
+            id: row.id,
+            title: row.title,
+            branch: row.branch,
+            turnCount: row.turnCount,
+            eventCount: row.eventCount,
+            visibleEventCount: visible.length,
+            hasActiveRewind: latest !== null,
+            updatedAt: row.updatedAt,
+        });
+    }
+    return out;
+}
+function toResumeListRow(input) {
+    return {
+        id: input.row.id,
+        title: input.row.title,
+        branch: input.row.branch,
+        turnCount: input.row.turnCount,
+        eventCount: input.row.eventCount,
+        visibleEventCount: input.visibleEventCount,
+        hasActiveRewind: input.hasActiveRewind,
+        updatedAt: input.row.updatedAt,
+    };
+}
+/**
+ * Pretty-print a resume list. Adds a small "rewound" tag when the
+ * session carries an unfinished rewind so the operator knows the
+ * transcript will load with a masked range.
+ */
+export function renderResumeList(rows, projectSlug) {
+    if (rows.length === 0) {
+        return `No stored sessions for project '${projectSlug}' yet.`;
+    }
+    const lines = [
+        `Recent local sessions for '${projectSlug}' (${rows.length}):`,
+        '',
+    ];
+    for (let i = 0; i < rows.length; i += 1) {
+        const row = rows[i];
+        const title = (row.title ?? '(untitled)').slice(0, 64);
+        const idShort = row.id.slice(0, 13);
+        const branch = (row.branch ?? 'no-branch').padEnd(16);
+        const turns = `${row.turnCount}t`.padStart(4);
+        const events = `${row.visibleEventCount}e`.padStart(5);
+        const tag = row.hasActiveRewind ? ' [rewound]' : '';
+        lines.push(`  ${idShort}  ${branch}  ${turns} ${events}${tag}  ${title}`);
+    }
+    lines.push('', 'Resume with: pugi resume <id>');
+    return lines.join('\n');
+}
+//# sourceMappingURL=resume.js.map

package/dist/runtime/commands/rewind.js

@@ -0,0 +1,333 @@
+/**
+ * `/rewind` runtime — leak L9 (2026-05-27).
+ *
+ * Three invocation modes, sharing one runner:
+ *
+ *   - `/rewind N`              drop the last N operator turns + every
+ *                              tool call that landed between.
+ *   - `/rewind --to <id>`      rewind to a specific event index from the
+ *                              visible (post-mask) transcript.
+ *   - `/rewind`                interactive picker — surfaces the last 10
+ *                              user-turn boundaries (newest-first) and
+ *                              returns a payload the caller can use to
+ *                              mount a select prompt.
+ *
+ * The rewind is APPEND-ONLY: we never delete events. `applyRewindMask`
+ * elides the masked range on read; `pugi sessions undo-rewind` appends
+ * an inverse marker that nullifies the latest rewind so operators have
+ * a reliable escape hatch.
+ *
+ * Surface contract (same shape as `runCompactCommand`):
+ *
+ *   - Returns a structured result for the JSON path.
+ *   - Calls `ctx.writeOutput(payload, text)` once per invocation.
+ *   - Throws ONLY on programmer-error. Store failures, missing
+ *     sessions, etc. are surfaced as `failed_*` statuses.
+ *
+ * Exit codes (mapped by the dispatcher in cli.ts):
+ *
+ *   0  — marker appended OR picker surfaced
+ *   1  — store unavailable / session not found
+ *   2  — noop (asked to drop 0 turns, nothing to rewind, etc.)
+ */
+import { homedir } from 'node:os';
+import { slugForCwd } from '../../core/repl/history.js';
+import { appendRewindMarker, buildRewindPickerRows, pickRewindTargetForTurns, resolveEventIdToIndex, } from '../../core/checkpoint/rewinder.js';
+import { loadFromStore } from '../../core/checkpoint/resumer.js';
+import { SqliteSessionStore, resolveProjectStoreDir, } from '../../core/repl/store/session-store.js';
+/**
+ * Entry point reused by the slash command + the top-level dispatcher.
+ *
+ * `args` accepts:
+ *   - `[]`              picker mode
+ *   - `["N"]`           drop last N turns
+ *   - `["--to", "<id>"]`  rewind to event id
+ *
+ * Both `-N` and `--turns N` are accepted for parity with Claude Code's
+ * `--turns` flag.
+ */
+export async function runRewindCommand(args, ctx) {
+    const parsed = parseRewindArgs(args);
+    if (parsed.kind === 'error') {
+        return emit(ctx, {
+            command: 'rewind',
+            status: 'failed_parse',
+            reason: parsed.message,
+        }, parsed.message);
+    }
+    // Resolve session + store.
+    const slug = slugForCwd(ctx.workspaceRoot);
+    let store = ctx.store ?? null;
+    let sessionId = ctx.sessionId ?? null;
+    let storeOpenedHere = false;
+    if (store === null) {
+        sessionId = sessionId ?? (await pickMostRecentSessionIdReadOnly(slug));
+        if (!sessionId) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_no_session',
+                reason: 'No active session to rewind. Start a REPL with `pugi`.',
+            });
+        }
+        const opened = await openLiveStore(slug, sessionId);
+        if (!opened) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_store',
+                sessionId,
+                reason: 'Could not open local session store (lock held by another REPL?).',
+            });
+        }
+        store = opened;
+        storeOpenedHere = true;
+    }
+    else if (sessionId === null) {
+        const rows = await store.listSessions({ project: slug, limit: 1, status: 'active' });
+        if (rows.length === 0) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_no_session',
+                reason: 'No active session to rewind.',
+            });
+        }
+        sessionId = rows[0].id;
+    }
+    try {
+        const loaded = await loadFromStore(store, sessionId);
+        if (!loaded) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_no_session',
+                sessionId,
+                reason: `Session '${sessionId}' not found.`,
+            });
+        }
+        // Picker mode: surface the last 10 user-turn boundaries.
+        if (parsed.kind === 'picker') {
+            const rows = buildRewindPickerRows(loaded.rawEvents, 10);
+            if (rows.length === 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_empty',
+                    sessionId,
+                    reason: 'No operator turns to rewind to.',
+                }, 'Nothing to rewind — no operator turns yet.');
+            }
+            const pickerRows = rows.map((r) => ({
+                visibleIndex: r.visibleIndex,
+                turnsAgo: r.turnsAgo,
+                preview: r.preview,
+                timestampEpochMs: r.timestampEpochMs,
+            }));
+            const text = renderPicker(pickerRows);
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'picker',
+                sessionId,
+                pickerRows,
+            }, text);
+        }
+        // Resolve target index.
+        let toEventIndex;
+        let turnsRewound;
+        if (parsed.kind === 'turns') {
+            if (parsed.n <= 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_zero',
+                    sessionId,
+                    reason: 'Asked to drop 0 turns — nothing to do.',
+                }, 'Asked to drop 0 turns — nothing to do.');
+            }
+            const target = pickRewindTargetForTurns(loaded.rawEvents, parsed.n);
+            if (target.turnsRewound === 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_empty',
+                    sessionId,
+                    reason: 'No operator turns to rewind.',
+                }, 'No operator turns to rewind.');
+            }
+            toEventIndex = target.toEventIndex;
+            turnsRewound = target.turnsRewound;
+        }
+        else {
+            // mode === 'to-event'
+            const resolvedIdx = resolveEventIdToIndex(loaded.rawEvents, parsed.eventId);
+            if (resolvedIdx === null) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'failed_parse',
+                    sessionId,
+                    reason: `Could not resolve event id '${parsed.eventId}'. Try \`/rewind\` for the picker.`,
+                });
+            }
+            toEventIndex = resolvedIdx;
+            // Count user turns in the masked range to report turnsRewound.
+            turnsRewound = countUserTurnsAfter(loaded.rawEvents, toEventIndex);
+        }
+        const fromEventIndex = loaded.rawEvents.length;
+        await appendRewindMarker({
+            store,
+            toEventIndex,
+            fromEventIndex,
+            turnsRewound,
+            reason: parsed.kind === 'turns' ? 'manual' : 'to-event',
+            ...(ctx.now !== undefined ? { now: ctx.now } : {}),
+        });
+        // Reload + recompute visible count for the operator banner.
+        const after = await loadFromStore(store, sessionId);
+        const visibleAfter = after?.visibleEvents.length ?? 0;
+        const banner = `Rewound ${turnsRewound} turn${turnsRewound === 1 ? '' : 's'} ` +
+            `(to event ${toEventIndex < 0 ? 'start' : `#${toEventIndex + 1}`}). ` +
+            `${visibleAfter} event${visibleAfter === 1 ? '' : 's'} now visible. ` +
+            `Undo with \`pugi sessions undo-rewind\`.`;
+        return emit(ctx, {
+            command: 'rewind',
+            status: 'rewound',
+            sessionId,
+            turnsRewound,
+            toEventIndex,
+            fromEventIndex,
+            visibleAfter,
+        }, banner);
+    }
+    finally {
+        if (storeOpenedHere && store) {
+            try {
+                await store.close();
+            }
+            catch {
+                /* idempotent */
+            }
+        }
+    }
+}
+/**
+ * Accepts:
+ *   pugi rewind            -> picker
+ *   pugi rewind 3          -> drop 3 turns
+ *   pugi rewind --turns 3  -> same
+ *   pugi rewind --to 12    -> rewind to event index 12 (1-based visible)
+ *   pugi rewind --to #12   -> rewind to event index 12 (0-based hidden)
+ */
+function parseRewindArgs(args) {
+    if (args.length === 0)
+        return { kind: 'picker' };
+    const head = args[0];
+    // --to <id>
+    if (head === '--to' || head === '-t') {
+        const eventId = args[1];
+        if (!eventId) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --to <event-id>',
+            };
+        }
+        return { kind: 'to-event', eventId };
+    }
+    if (head.startsWith('--to=')) {
+        const eventId = head.slice('--to='.length);
+        if (eventId.length === 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --to <event-id>',
+            };
+        }
+        return { kind: 'to-event', eventId };
+    }
+    // --turns N OR -N OR positional N
+    if (head === '--turns' || head === '-n') {
+        const n = Number.parseInt(args[1] ?? '', 10);
+        if (!Number.isFinite(n) || n < 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --turns <N>',
+            };
+        }
+        return { kind: 'turns', n };
+    }
+    if (head.startsWith('--turns=')) {
+        const n = Number.parseInt(head.slice('--turns='.length), 10);
+        if (!Number.isFinite(n) || n < 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --turns <N>',
+            };
+        }
+        return { kind: 'turns', n };
+    }
+    // Bare integer: positional turns count.
+    const positional = Number.parseInt(head, 10);
+    if (Number.isFinite(positional) && positional >= 0) {
+        return { kind: 'turns', n: positional };
+    }
+    return {
+        kind: 'error',
+        message: `Unknown argument '${head}'. Try \`pugi rewind\`, \`pugi rewind <N>\`, or \`pugi rewind --to <id>\`.`,
+    };
+}
+function emit(ctx, payload, text) {
+    const human = text ?? payload.reason ?? `rewind: ${payload.status}`;
+    ctx.writeOutput(payload, human);
+    return payload;
+}
+function renderPicker(rows) {
+    const lines = ['Rewind picker — pick a turn boundary:', ''];
+    for (const r of rows) {
+        const tag = `[#${r.visibleIndex.toString().padStart(3)}]`;
+        const ago = `${r.turnsAgo}t ago`.padStart(8);
+        lines.push(`  ${tag}  ${ago}  ${r.preview}`);
+    }
+    lines.push('', 'Rewind with: pugi rewind --to <#N>  (or `pugi rewind <turnsToDrop>`).');
+    return lines.join('\n');
+}
+function countUserTurnsAfter(events, toEventIndex) {
+    let count = 0;
+    for (let i = toEventIndex + 1; i < events.length; i += 1) {
+        if (events[i].kind === 'user')
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Open the SqliteSessionStore for the workspace's project slug, bound
+ * to `sessionId`. Returns null when the lock is held by another REPL.
+ */
+async function openLiveStore(projectSlug, sessionId) {
+    try {
+        const store = new SqliteSessionStore({ projectSlug, home: homedir() });
+        await store.open({
+            id: sessionId,
+            workspaceRoot: process.cwd(),
+            projectSlug,
+        });
+        return store;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover the most recent active session id for a project slug,
+ * without taking the writer lockfile. Used by the standalone CLI path
+ * (no `--session` flag) so a live REPL holding the lock does not block
+ * the lookup.
+ */
+async function pickMostRecentSessionIdReadOnly(projectSlug) {
+    try {
+        const dir = resolveProjectStoreDir(projectSlug, homedir());
+        const view = await SqliteSessionStore.openReadOnly(dir);
+        try {
+            const rows = await view.list({ project: projectSlug, limit: 1, status: 'active' });
+            return rows.length > 0 ? rows[0].id : null;
+        }
+        finally {
+            await view.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=rewind.js.map