@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

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

package/dist/core/codegraph/decision-store.js

@@ -0,0 +1,248 @@
+/**
+ * Codegraph install-decision store — Wave 6 BIG TRACK 9 Phase 2.
+ *
+ * Persists the operator's verdict on the codegraph install prompt so we
+ * never spam them after a single decline. The 30-day reminder cadence
+ * lets us re-surface the offer on big-enough repos in case the operator
+ * said "not now" the first time and then forgot codegraph exists.
+ *
+ * Schema (workspace-scoped at `.pugi/codegraph-decision.json`):
+ *
+ *   {
+ *     "schema": 1,
+ *     "offeredAt": "2026-05-27T00:00:00.000Z",
+ *     "accepted": false,
+ *     "decliningCount": 1,
+ *     "remindAfter": "2026-06-26T00:00:00.000Z",  // 30 days from offeredAt
+ *     "lastIndexedAt": null,                        // ISO date string OR null
+ *     "lastReindexCheckAt": null
+ *   }
+ *
+ * The store is workspace-local (each repo gets its own decision) so
+ * declining codegraph in repo A does not suppress the prompt in repo B.
+ * `.pugi/` already exists by the time we land here (pugi init scaffolds
+ * it), so the directory creation is best-effort defence-in-depth.
+ *
+ * Concurrency: every write is `tmp + rename` so a partial write cannot
+ * surface a corrupt JSON. Reads tolerate missing files + corrupt JSON
+ * by returning `null` — the caller decides whether to fall back to
+ * "offer again" (safe default) or "do nothing" (cold-start path).
+ *
+ * Pure persistence. No telemetry, no logging. The emitter lives in the
+ * call sites so the decision store stays unit-testable in isolation.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Reminder cadence — 30 days from the last decline. Operators who said
+ * no in a small repo that grew к medium during a sprint deserve a
+ * follow-up; operators who said no last week do not. The window is
+ * exposed as a const so the spec can pin it.
+ */
+export const REMIND_AFTER_DAYS = 30;
+/**
+ * Stale-index threshold for the cold-start "refresh me" reminder.
+ * Seven days is the cadence the upstream codegraph docs recommend for
+ * monorepos that ship multiple times a day; lower repos can wait
+ * longer. The spec pins it.
+ */
+export const STALE_INDEX_DAYS = 7;
+/**
+ * Resolve the decision file path for a workspace root. Pure — exposed
+ * для spec parity.
+ */
+export function decisionPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi/codegraph-decision.json');
+}
+/**
+ * Read the persisted decision. Returns null on missing file, malformed
+ * JSON, or wrong schema version. The caller MUST treat null as "no
+ * decision yet" — not "operator declined".
+ */
+export function readDecision(workspaceRoot) {
+    const path = decisionPath(workspaceRoot);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isDecisionShape(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Type guard. Defensive — a future schema bump should land a migration
+ * here. For now: schema MUST be 1; required string fields MUST be
+ * strings; optional fields may be null OR string.
+ */
+function isDecisionShape(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (v.schema !== 1)
+        return false;
+    if (typeof v.offeredAt !== 'string')
+        return false;
+    if (typeof v.accepted !== 'boolean')
+        return false;
+    if (typeof v.decliningCount !== 'number' || !Number.isFinite(v.decliningCount))
+        return false;
+    if (typeof v.remindAfter !== 'string')
+        return false;
+    if (v.lastIndexedAt !== null && typeof v.lastIndexedAt !== 'string')
+        return false;
+    if (v.lastReindexCheckAt !== null && typeof v.lastReindexCheckAt !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Atomic write. Creates `.pugi/` if it does not exist (pugi init owns
+ * that surface ordinarily; we defend the rare cold-start path).
+ */
+export function writeDecision(workspaceRoot, decision) {
+    const path = decisionPath(workspaceRoot);
+    const dir = resolve(workspaceRoot, '.pugi');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(decision, null, 2)}\n`, { mode: 0o600 });
+    try {
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        // Rename can fail if the destination was concurrently swapped on
+        // some platforms (Windows). Fall back to unlink + rename so the
+        // best-effort write does not throw to the caller.
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // ignore
+        }
+        renameSync(tmp, path);
+        void error;
+    }
+}
+/**
+ * Decide whether to surface the install prompt on init. Returns the
+ * full decision shape for callers that want to inspect the cadence;
+ * a `true` verdict means "yes, ask the operator now".
+ */
+export function shouldOfferOnInit(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior) {
+        return { shouldOffer: true, reason: 'first-run' };
+    }
+    if (prior.accepted) {
+        return { shouldOffer: false, reason: 'accepted-already' };
+    }
+    if (Date.parse(nowIso) >= Date.parse(prior.remindAfter)) {
+        return { shouldOffer: true, reason: 'reminder-due' };
+    }
+    return { shouldOffer: false, reason: 'recent-decline' };
+}
+/**
+ * Record the operator's decision atomically. Mirrors the structure on
+ * disk — callers do NOT hand-craft the schema.
+ */
+export function recordDecision(workspaceRoot, input) {
+    const nowIso = input.nowIso ?? new Date().toISOString();
+    const prior = readDecision(workspaceRoot);
+    const decliningCount = input.accepted ? 0 : (prior?.decliningCount ?? 0) + 1;
+    const remindAfter = new Date(Date.parse(nowIso) + REMIND_AFTER_DAYS * 24 * 60 * 60 * 1000).toISOString();
+    const decision = {
+        schema: 1,
+        offeredAt: nowIso,
+        accepted: input.accepted,
+        decliningCount,
+        remindAfter,
+        lastIndexedAt: prior?.lastIndexedAt ?? null,
+        lastReindexCheckAt: prior?.lastReindexCheckAt ?? null,
+    };
+    writeDecision(workspaceRoot, decision);
+    return decision;
+}
+/**
+ * Stamp the last-indexed timestamp. Called by /codegraph-status when
+ * the operator triggers a reindex from inside Pugi. Updates the
+ * `accepted` decision in place — never flips the install state.
+ */
+export function markIndexed(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior)
+        return null;
+    const next = {
+        ...prior,
+        lastIndexedAt: nowIso,
+        lastReindexCheckAt: nowIso,
+    };
+    writeDecision(workspaceRoot, next);
+    return next;
+}
+/**
+ * Stamp the last reindex-check timestamp without changing the index
+ * itself. Used by the cold-start hook so we do not show the "index is
+ * stale" hint on every keystroke once the operator has acknowledged
+ * it.
+ */
+export function markReindexChecked(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior)
+        return null;
+    const next = {
+        ...prior,
+        lastReindexCheckAt: nowIso,
+    };
+    writeDecision(workspaceRoot, next);
+    return next;
+}
+/**
+ * Compute the staleness of the codegraph index. Pure — no IO.
+ *
+ *   - returns null when `lastIndexedAt` is null (never indexed)
+ *   - returns the day-delta (rounded down) otherwise
+ */
+export function indexAgeDays(decision, nowIso = new Date().toISOString()) {
+    if (!decision.lastIndexedAt)
+        return null;
+    const deltaMs = Date.parse(nowIso) - Date.parse(decision.lastIndexedAt);
+    if (!Number.isFinite(deltaMs) || deltaMs < 0)
+        return 0;
+    return Math.floor(deltaMs / (24 * 60 * 60 * 1000));
+}
+/**
+ * Convenience predicate — should the cold-start hook show the stale-
+ * index reminder? `true` when the index is older than STALE_INDEX_DAYS
+ * AND we did NOT already remind the operator today.
+ */
+export function shouldNudgeStaleIndex(decision, nowIso = new Date().toISOString()) {
+    if (!decision.accepted)
+        return false;
+    const age = indexAgeDays(decision, nowIso);
+    if (age === null)
+        return false;
+    if (age < STALE_INDEX_DAYS)
+        return false;
+    // Throttle the nudge to once per day so the operator does not see it
+    // on every REPL keystroke.
+    if (decision.lastReindexCheckAt) {
+        const lastCheckDelta = Date.parse(nowIso) - Date.parse(decision.lastReindexCheckAt);
+        if (Number.isFinite(lastCheckDelta) && lastCheckDelta < 24 * 60 * 60 * 1000) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=decision-store.js.map