@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/checkpoint/resumer.js

@@ -0,0 +1,149 @@
+/**
+ * Resumer — read SessionStore events for a session, apply the L8
+ * compact mask + the L9 rewind mask, and return the visible transcript
+ * the REPL bootstrap (or a programmatic consumer) should render.
+ *
+ * Separation of concerns:
+ *
+ *  - This module owns the READ path: list sessions, load events,
+ *    reconstruct a clean transcript stream. No writes.
+ *  - The WRITE path (append a rewind-marker, undo-rewind) lives in
+ *    `./rewinder.ts`.
+ *  - The REPL session lifecycle (lockfile, Ink mount, dispatch FSM)
+ *    stays in `core/repl/session.ts`. We do NOT spin up the REPL here.
+ *
+ * Why route resume through this module at all (vs. operators using
+ * `core/repl/store/*` directly):
+ *
+ *  The store returns RAW events. Most consumers want masked events —
+ *  i.e. the chronological list after compact-boundary masking AND
+ *  rewind-marker masking. Doing both passes inline at every call site
+ *  would scatter the mask logic; centralising it here means a future
+ *  third mask (named checkpoints? selective edit?) lands in one place.
+ */
+import { homedir } from 'node:os';
+import { applyCompactMask } from '../compact/buffer-rewriter.js';
+import { SqliteSessionStore, resolveProjectStoreDir, } from '../repl/store/index.js';
+import { applyRewindMask, findLatestActiveRewind } from './rewinder.js';
+/**
+ * Composed mask: compact-mask first (collapses summarised slices into
+ * boundary markers + kept tail), then rewind-mask (drops everything
+ * inside an active rewind range, including any compaction markers that
+ * fell inside it).
+ *
+ * Order matters: compact-mask reads `coversUntilOffset` against the
+ * RAW event indices. Running rewind-mask first would shift indices and
+ * break the compact replay anchor. The result is the chronological
+ * stream the operator should SEE, with infra rows (rewind markers)
+ * stripped.
+ */
+export function applyAllMasks(events) {
+    return applyRewindMask(applyCompactMask(events));
+}
+/**
+ * List sessions a `pugi resume` invocation could open. Uses the
+ * READ-ONLY store view so the call never takes the lockfile — safe to
+ * run alongside a live REPL. Each row carries derived metadata
+ * (`visibleEventCount`, `hasActiveRewind`) so the renderer does not
+ * need to re-walk events.
+ *
+ * Returns an empty array when the project store does not exist (no
+ * sessions ever started for this project slug). Callers surface a
+ * "nothing to resume" message in that branch.
+ */
+export async function listResumableSessions(input) {
+    const dir = input.storeDir ?? resolveProjectStoreDir(input.projectSlug, input.home ?? homedir());
+    const limit = clampLimit(input.limit ?? 10, 1, 50);
+    let view;
+    try {
+        view = await SqliteSessionStore.openReadOnly(dir);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const rows = await view.list({ project: input.projectSlug, limit });
+        const out = [];
+        for (const row of rows) {
+            const events = await view.events(row.id);
+            const visible = applyAllMasks(events);
+            const latest = findLatestActiveRewind(events);
+            out.push({
+                row,
+                visibleEventCount: visible.length,
+                hasActiveRewind: latest !== null,
+                updatedAt: row.updatedAt,
+            });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await view.close();
+    }
+}
+/**
+ * Load one session for replay. The caller (REPL bootstrap, tests,
+ * future programmatic exporters) gets BOTH the raw event stream and
+ * the masked view so it can choose its rendering strategy. Returns
+ * null when the session does not exist; throws when the store cannot
+ * be opened (the caller surfaces a one-line error).
+ *
+ * The PID lockfile contention is NOT relevant here — we use the
+ * read-only view. Concurrent writers from a live REPL are safe.
+ */
+export async function loadSessionForReplay(input) {
+    const dir = input.storeDir ?? resolveProjectStoreDir(input.projectSlug, input.home ?? homedir());
+    const view = await SqliteSessionStore.openReadOnly(dir);
+    try {
+        const row = await view.get(input.sessionId);
+        if (!row)
+            return null;
+        const rawEvents = await view.events(row.id);
+        const visibleEvents = applyAllMasks(rawEvents);
+        const latest = findLatestActiveRewind(rawEvents);
+        return {
+            row,
+            rawEvents,
+            visibleEvents,
+            hasActiveRewind: latest !== null,
+        };
+    }
+    finally {
+        await view.close();
+    }
+}
+/**
+ * Load raw + masked events through an already-open SessionStore.
+ *
+ * Used by the in-REPL `/rewind` slash handler — the live REPL already
+ * holds the writer lock, so we cannot open the read-only view in the
+ * same process. The store reference IS the active write handle; we
+ * just call `loadEvents` and run the masks.
+ *
+ * Same shape as `loadSessionForReplay` minus the read-only-view setup.
+ */
+export async function loadFromStore(store, sessionId) {
+    const row = await store.getSession(sessionId);
+    if (!row)
+        return null;
+    const rawEvents = await store.loadEvents(sessionId);
+    const visibleEvents = applyAllMasks(rawEvents);
+    const latest = findLatestActiveRewind(rawEvents);
+    return {
+        row,
+        rawEvents,
+        visibleEvents,
+        hasActiveRewind: latest !== null,
+    };
+}
+function clampLimit(raw, min, max) {
+    if (!Number.isFinite(raw) || raw < min)
+        return min;
+    if (raw > max)
+        return max;
+    return Math.floor(raw);
+}
+//# sourceMappingURL=resumer.js.map

package/dist/core/checkpoint/rewinder.js

@@ -0,0 +1,291 @@
+/**
+ * Type guard: discriminate a SessionEvent against the `rewind-marker`
+ * kind. The boundary check is strict — a malformed payload returns
+ * `false` so the replay layer can treat it as a regular (visible) event
+ * instead of trusting partial data.
+ */
+export function isRewindMarker(event) {
+    if (event.kind !== 'rewind-marker')
+        return false;
+    const p = event.payload;
+    if (p === null || typeof p !== 'object')
+        return false;
+    if (p.version !== 1)
+        return false;
+    if (p.mode !== 'rewind' && p.mode !== 'undo-rewind')
+        return false;
+    if (typeof p.toEventIndex !== 'number')
+        return false;
+    if (typeof p.fromEventIndex !== 'number')
+        return false;
+    if (typeof p.turnsRewound !== 'number')
+        return false;
+    if (p.reason !== 'manual'
+        && p.reason !== 'to-event'
+        && p.reason !== 'interactive'
+        && p.reason !== 'undo') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Append one `rewind-marker` event to the SessionStore. Returns the
+ * SessionEvent we wrote so the caller can echo it into the in-memory
+ * transcript without a re-read. Throws on store error so the caller
+ * surfaces the failure inline.
+ */
+export async function appendRewindMarker(input) {
+    const ts = (input.now ?? (() => Date.now()))();
+    const payload = {
+        version: 1,
+        mode: input.mode ?? 'rewind',
+        toEventIndex: input.toEventIndex,
+        fromEventIndex: input.fromEventIndex,
+        turnsRewound: input.turnsRewound,
+        reason: input.reason,
+    };
+    const event = {
+        t: ts,
+        kind: 'rewind-marker',
+        payload,
+    };
+    await input.store.appendEvent(event);
+    return event;
+}
+/**
+ * Apply rewind masking to a chronological event list. Pure function —
+ * returns a new array with the masked events stripped. The marker
+ * events themselves are stripped too (they are infrastructure, not
+ * conversation rows); the renderer surfaces the rewind banner via a
+ * separate informational payload, NOT by leaving the marker in the
+ * transcript.
+ *
+ * Algorithm (matched-pair cancellation):
+ *
+ *  1. Walk events newest-to-oldest. Maintain an integer `undoBalance`
+ *     that counts the unmatched 'undo-rewind' markers we have seen.
+ *  2. When we hit an 'undo-rewind' marker, increment `undoBalance` —
+ *     it will cancel the next older 'rewind' marker.
+ *  3. When we hit a 'rewind' marker:
+ *     - If `undoBalance > 0`: decrement (the undo cancels this
+ *       rewind). The marker AND the events in its masked range stay
+ *       visible — the undo restored them.
+ *     - Otherwise: record the marker's `[toEventIndex+1 ..
+ *       fromEventIndex]` range as masked.
+ *  4. After the walk, return every event whose index is NOT inside an
+ *     active masked range AND that is not itself a rewind-marker.
+ *
+ * Why not just look at the latest marker:
+ *  The operator can rewind, then rewind again, then undo-rewind once.
+ *  The newest rewind should still apply; only the innermost rewind is
+ *  cancelled by the undo. Matched-pair walking handles every
+ *  stack-depth without special-casing.
+ */
+export function applyRewindMask(events) {
+    // Pass 1: walk newest-to-oldest, collect active masked ranges.
+    let undoBalance = 0;
+    // Each range is half-open [start, end] inclusive on both ends so the
+    // membership check below stays a simple two-integer comparison.
+    const maskedRanges = [];
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const ev = events[i];
+        if (!isRewindMarker(ev))
+            continue;
+        if (ev.payload.mode === 'undo-rewind') {
+            undoBalance += 1;
+            continue;
+        }
+        // mode === 'rewind'
+        if (undoBalance > 0) {
+            undoBalance -= 1;
+            continue;
+        }
+        // Active rewind — mask everything strictly AFTER toEventIndex and
+        // strictly BEFORE the marker itself. The marker (index === i) is
+        // dropped via the rewind-marker kind filter below.
+        const start = ev.payload.toEventIndex + 1;
+        const end = i - 1;
+        if (end >= start) {
+            maskedRanges.push({ start, end });
+        }
+    }
+    // Pass 2: emit only events that are NOT inside any masked range and
+    // are NOT themselves rewind-markers. Linear scan with a sorted-ranges
+    // membership check would be faster for very large logs, but the
+    // typical transcript is in the hundreds of events — O(N*M) here with
+    // M = number of rewinds ever appended stays well under a millisecond.
+    const out = [];
+    for (let i = 0; i < events.length; i += 1) {
+        const ev = events[i];
+        if (isRewindMarker(ev))
+            continue;
+        let masked = false;
+        for (const range of maskedRanges) {
+            if (i >= range.start && i <= range.end) {
+                masked = true;
+                break;
+            }
+        }
+        if (!masked)
+            out.push(ev);
+    }
+    return out;
+}
+/**
+ * Walk events oldest-to-newest and return the indices of the last `n`
+ * operator turns (`kind === 'user'`) — used by `/rewind N` to translate
+ * "drop the last 3 turns" into a concrete `toEventIndex`.
+ *
+ * Visibility is computed via `applyRewindMask`-aware indexing: the
+ * caller supplies the FULL event list (incl. existing markers) and we
+ * walk only the visible subset so a follow-up rewind on top of an
+ * existing rewind operates on what the operator currently SEES, not the
+ * full on-disk history.
+ *
+ * Returns the index of the event that should become the new
+ * `toEventIndex` — i.e. the event *immediately before* the Nth turn
+ * boundary, counting from the end. When `n` exceeds the visible turn
+ * count, returns `-1` (rewind everything).
+ */
+export function pickRewindTargetForTurns(events, turnsToDrop) {
+    if (turnsToDrop <= 0) {
+        // No-op — return the last index unchanged so the caller can detect
+        // the noop and emit a sensible message.
+        return { toEventIndex: events.length - 1, turnsRewound: 0 };
+    }
+    const visible = applyRewindMask(events);
+    // Walk visible newest-to-oldest, count user turns.
+    const userTurnVisibleIndices = [];
+    for (let i = visible.length - 1; i >= 0; i -= 1) {
+        if (visible[i].kind === 'user')
+            userTurnVisibleIndices.push(i);
+        if (userTurnVisibleIndices.length >= turnsToDrop + 1)
+            break;
+    }
+    const turnsAvailable = userTurnVisibleIndices.length;
+    if (turnsAvailable < turnsToDrop) {
+        // Fewer turns than asked — rewind everything visible.
+        return { toEventIndex: -1, turnsRewound: turnsAvailable };
+    }
+    if (turnsAvailable === turnsToDrop) {
+        // Drop ALL visible turns — anchor at -1 inside the visible list
+        // (i.e. before the first visible event). Translate back to an
+        // index in the full event list by picking the position right
+        // before the oldest visible event.
+        const oldestVisibleIdx = visible.length > 0 ? indexInFull(events, visible[0]) : -1;
+        return { toEventIndex: oldestVisibleIdx - 1, turnsRewound: turnsToDrop };
+    }
+    // `userTurnVisibleIndices` collected user turns newest-first. The
+    // OLDEST turn the operator wants to drop sits at index
+    // `turnsToDrop - 1` of that array (the Nth most recent). The new
+    // `toEventIndex` is the visible event RIGHT BEFORE that turn — that
+    // becomes the last visible row after the rewind. The N most-recent
+    // turns + everything between them get masked.
+    const cutVisibleIdx = userTurnVisibleIndices[turnsToDrop - 1];
+    // Pick the event one slot before the cut as the new toEventIndex.
+    const anchorVisibleIdx = cutVisibleIdx - 1;
+    if (anchorVisibleIdx < 0) {
+        return { toEventIndex: -1, turnsRewound: turnsToDrop };
+    }
+    const anchorEvent = visible[anchorVisibleIdx];
+    const toEventIndex = indexInFull(events, anchorEvent);
+    return { toEventIndex, turnsRewound: turnsToDrop };
+}
+/**
+ * Resolve a `--to <event-id>` argument into a concrete event index in
+ * the on-disk log. The L8 / L9 wire format does NOT mint an `id` field
+ * on individual events; the operator picks by the (1-based) line number
+ * we surface in `applyRewindMask`-aware listings. So `<event-id>` here
+ * is `"<n>"` where n is the 1-based visible index. We accept both
+ * 1-based (UI-facing) and 0-based (programmatic / tests) by checking
+ * for a leading `#`.
+ *
+ * Returns the matching index in the full event list, or null when the
+ * input is unparseable / out of range.
+ */
+export function resolveEventIdToIndex(events, eventId) {
+    const trimmed = eventId.trim();
+    if (trimmed.length === 0)
+        return null;
+    const zeroBased = trimmed.startsWith('#');
+    const raw = zeroBased ? trimmed.slice(1) : trimmed;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return null;
+    const visible = applyRewindMask(events);
+    const visibleIdx = zeroBased ? parsed : parsed - 1;
+    if (visibleIdx < 0 || visibleIdx >= visible.length)
+        return null;
+    return indexInFull(events, visible[visibleIdx]);
+}
+/**
+ * Locate the index of `target` inside `events` by identity-then-equality.
+ * Identity hits in O(1); the equality fallback walks the array and
+ * compares the (t, kind) discriminator, which is unique-enough for the
+ * append-only log where two events at the same millisecond with the
+ * same kind would also have identical payloads.
+ */
+function indexInFull(events, target) {
+    // Identity check first — `applyRewindMask` returns elements from the
+    // input array directly, so `===` succeeds in the common path.
+    for (let i = 0; i < events.length; i += 1) {
+        if (events[i] === target)
+            return i;
+    }
+    // Fallback: compare by t + kind + payload reference. Unlikely path.
+    for (let i = 0; i < events.length; i += 1) {
+        const ev = events[i];
+        if (ev.t === target.t && ev.kind === target.kind && ev.payload === target.payload) {
+            return i;
+        }
+    }
+    return -1;
+}
+export function buildRewindPickerRows(events, limit = 10) {
+    const visible = applyRewindMask(events);
+    const rows = [];
+    let turnsAgo = 0;
+    for (let i = visible.length - 1; i >= 0 && rows.length < limit; i -= 1) {
+        const ev = visible[i];
+        if (ev.kind !== 'user')
+            continue;
+        turnsAgo += 1;
+        const payload = ev.payload;
+        const preview = typeof payload?.brief === 'string'
+            ? payload.brief.slice(0, 64)
+            : '(empty turn)';
+        rows.push({
+            eventIndex: indexInFull(events, ev),
+            visibleIndex: i + 1,
+            preview,
+            turnsAgo,
+            timestampEpochMs: ev.t,
+        });
+    }
+    return rows;
+}
+/**
+ * Find the latest active 'rewind' marker — i.e. the one that an
+ * `undo-rewind` would cancel. Walks newest-to-oldest, balancing
+ * 'undo-rewind' markers against 'rewind' markers; returns the first
+ * unmatched 'rewind' or null when every rewind has already been undone.
+ */
+export function findLatestActiveRewind(events) {
+    let undoBalance = 0;
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const ev = events[i];
+        if (!isRewindMarker(ev))
+            continue;
+        if (ev.payload.mode === 'undo-rewind') {
+            undoBalance += 1;
+            continue;
+        }
+        if (undoBalance > 0) {
+            undoBalance -= 1;
+            continue;
+        }
+        return { event: ev, payload: ev.payload, index: i };
+    }
+    return null;
+}
+//# sourceMappingURL=rewinder.js.map