@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/checkpoint/resumer.js

@@ -1,149 +0,0 @@
-/**
- * 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

@@ -1,291 +0,0 @@
-/**
- * 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