@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/tracking/stash-manager.js

@@ -1,258 +0,0 @@
-/**
- * Sprint 7.1: Git Stash Awareness — save/restore drift overlay on stash/pop.
- *
- * Detects `git stash` and `git stash pop` by watching `.git/refs/stash`.
- * On stash push: serializes drift_overlay + file hashes to `.unerr/drift/stash/{ref}/`.
- * On stash pop: restores overlay from snapshot.
- * Max 10 stash snapshots (LRU eviction).
- */
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { join } from "node:path";
-/** Maximum number of stash snapshots to retain (LRU). */
-const MAX_STASH_SNAPSHOTS = 10;
-/** Files written per stash snapshot. */
-const OVERLAY_FILE = "overlay_snapshot.json";
-const HASHES_FILE = "file_hashes.json";
-/** stderr logger */
-const _log = {
-    info: (msg) => process.stderr.write(`[unerr:stash] ${msg}\n`),
-    warn: (msg) => process.stderr.write(`[unerr:stash] WARN: ${msg}\n`),
-};
-export class StashManager {
-    unerrDir;
-    projectRoot;
-    stashDir;
-    gitDir;
-    previousStashRef = null;
-    previousStashCount = 0;
-    constructor(unerrDir, projectRoot) {
-        this.unerrDir = unerrDir;
-        this.projectRoot = projectRoot;
-        this.stashDir = join(unerrDir, "drift", "stash");
-        this.gitDir = join(projectRoot, ".git");
-        // Initialize stash state
-        this.previousStashRef = this.readStashRef();
-        this.previousStashCount = this.getStashCount();
-    }
-    /**
-     * Check for stash changes. Call this periodically or on file-watcher trigger.
-     * Returns "push" if a stash was pushed, "pop" if popped/dropped, null if unchanged.
-     */
-    detectStashChange() {
-        const currentRef = this.readStashRef();
-        const currentCount = this.getStashCount();
-        if (currentRef === this.previousStashRef &&
-            currentCount === this.previousStashCount) {
-            return null;
-        }
-        let action = null;
-        if (currentCount > this.previousStashCount) {
-            action = "push";
-        }
-        else if (currentCount < this.previousStashCount) {
-            action = "pop";
-        }
-        else if (currentRef !== this.previousStashRef) {
-            // Same count but different ref — stash apply or complex operation
-            action = null;
-        }
-        this.previousStashRef = currentRef;
-        this.previousStashCount = currentCount;
-        return action;
-    }
-    /**
-     * Save the current drift overlay + file hashes as a stash snapshot.
-     */
-    async saveSnapshot(localGraph, fileHashState) {
-        const stashRef = this.readStashRef();
-        if (!stashRef)
-            return null;
-        const entities = await localGraph.getAllDriftEntities();
-        const edges = await localGraph.getAllDriftEdges();
-        if (entities.length === 0 && edges.length === 0) {
-            _log.info("No drift entities/edges to snapshot on stash push");
-            return null;
-        }
-        // Use stash ref SHA (truncated) as directory name
-        const snapshotId = stashRef.slice(0, 12);
-        const snapshotDir = join(this.stashDir, snapshotId);
-        if (!existsSync(snapshotDir)) {
-            mkdirSync(snapshotDir, { recursive: true });
-        }
-        const snapshot = {
-            stashRef,
-            entities,
-            edges,
-            fileHashes: fileHashState,
-            savedAt: new Date().toISOString(),
-        };
-        writeFileSync(join(snapshotDir, OVERLAY_FILE), JSON.stringify(snapshot, null, 2), "utf-8");
-        writeFileSync(join(snapshotDir, HASHES_FILE), JSON.stringify(fileHashState, null, 2), "utf-8");
-        // Enforce LRU cap
-        this.enforceLruCap();
-        _log.info(`Saved stash snapshot: ${snapshotId} (${entities.length} entities)`);
-        return snapshotId;
-    }
-    /**
-     * Restore drift overlay from the most recent stash snapshot.
-     * Called on stash pop. Returns the number of entities restored.
-     */
-    async restoreSnapshot(localGraph) {
-        const snapshots = this.listSnapshots();
-        if (snapshots.length === 0) {
-            _log.info("No stash snapshots to restore");
-            return 0;
-        }
-        // Restore the most recently saved snapshot
-        const latest = snapshots[0];
-        const snapshotDir = join(this.stashDir, latest.id);
-        const overlayPath = join(snapshotDir, OVERLAY_FILE);
-        if (!existsSync(overlayPath)) {
-            _log.warn(`Snapshot ${latest.id} missing overlay file`);
-            return 0;
-        }
-        try {
-            const raw = readFileSync(overlayPath, "utf-8");
-            const snapshot = JSON.parse(raw);
-            // Restore entities into drift overlay
-            for (const entity of snapshot.entities) {
-                await localGraph.upsertDriftEntity(entity);
-            }
-            // Restore drift edges (Task 6.4)
-            if (snapshot.edges) {
-                for (const edge of snapshot.edges) {
-                    await localGraph.upsertDriftEdge(edge);
-                }
-            }
-            // Clean up the snapshot after restore
-            rmSync(snapshotDir, { recursive: true, force: true });
-            _log.info(`Restored stash snapshot: ${latest.id} (${snapshot.entities.length} entities, ${snapshot.edges?.length ?? 0} edges)`);
-            return snapshot.entities.length;
-        }
-        catch (err) {
-            _log.warn(`Failed to restore snapshot ${latest.id}: ${err instanceof Error ? err.message : String(err)}`);
-            return 0;
-        }
-    }
-    /**
-     * Get the file hash state from the most recent stash snapshot.
-     * Returns null if no snapshot exists.
-     */
-    getSnapshotFileHashes() {
-        const snapshots = this.listSnapshots();
-        if (snapshots.length === 0)
-            return null;
-        const latest = snapshots[0];
-        const hashesPath = join(this.stashDir, latest.id, HASHES_FILE);
-        if (!existsSync(hashesPath))
-            return null;
-        try {
-            const raw = readFileSync(hashesPath, "utf-8");
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Remove snapshot for a specific stash ref (on stash drop).
-     */
-    dropSnapshot(stashRef) {
-        const snapshotId = stashRef.slice(0, 12);
-        const snapshotDir = join(this.stashDir, snapshotId);
-        if (!existsSync(snapshotDir))
-            return false;
-        rmSync(snapshotDir, { recursive: true, force: true });
-        _log.info(`Dropped stash snapshot: ${snapshotId}`);
-        return true;
-    }
-    /**
-     * List all stash snapshots, sorted by most recent first.
-     */
-    listSnapshots() {
-        if (!existsSync(this.stashDir))
-            return [];
-        try {
-            const entries = readdirSync(this.stashDir, { withFileTypes: true });
-            const snapshots = [];
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                const overlayPath = join(this.stashDir, entry.name, OVERLAY_FILE);
-                if (!existsSync(overlayPath))
-                    continue;
-                try {
-                    const stat = statSync(overlayPath);
-                    snapshots.push({ id: entry.name, savedAt: stat.mtime });
-                }
-                catch { }
-            }
-            // Sort by most recent first
-            snapshots.sort((a, b) => b.savedAt.getTime() - a.savedAt.getTime());
-            return snapshots;
-        }
-        catch {
-            return [];
-        }
-    }
-    /**
-     * Read the current stash ref SHA from `.git/refs/stash`.
-     */
-    readStashRef() {
-        const stashPath = join(this.gitDir, "refs", "stash");
-        if (!existsSync(stashPath))
-            return null;
-        try {
-            return readFileSync(stashPath, "utf-8").trim() || null;
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Count current stash entries via `.git/logs/refs/stash`.
-     */
-    getStashCount() {
-        const logPath = join(this.gitDir, "logs", "refs", "stash");
-        if (!existsSync(logPath))
-            return 0;
-        try {
-            const content = readFileSync(logPath, "utf-8");
-            return content.split("\n").filter((line) => line.trim().length > 0)
-                .length;
-        }
-        catch {
-            return 0;
-        }
-    }
-    /**
-     * Enforce LRU cap — remove oldest snapshots beyond MAX_STASH_SNAPSHOTS.
-     */
-    enforceLruCap() {
-        const snapshots = this.listSnapshots();
-        if (snapshots.length <= MAX_STASH_SNAPSHOTS)
-            return;
-        const toRemove = snapshots.slice(MAX_STASH_SNAPSHOTS);
-        for (const snapshot of toRemove) {
-            const dir = join(this.stashDir, snapshot.id);
-            rmSync(dir, { recursive: true, force: true });
-            _log.info(`LRU evicted stash snapshot: ${snapshot.id}`);
-        }
-    }
-}
-/**
- * Start a stash change poller. Calls onPush/onPop when stash state changes.
- * Returns a dispose function to stop polling.
- */
-export function startStashPoller(stashManager, onPush, onPop, intervalMs = 3000) {
-    const timer = setInterval(() => {
-        const action = stashManager.detectStashChange();
-        if (action === "push")
-            onPush();
-        else if (action === "pop")
-            onPop();
-    }, intervalMs);
-    // Don't prevent process exit
-    timer.unref();
-    return () => clearInterval(timer);
-}

package/dist/tracking/timeline-fork.js

@@ -1,213 +0,0 @@
-/**
- * Timeline Fork — tracks divergence points when rewinds create alternate timelines.
- *
- * When a rewind occurs, the current timeline is "abandoned" and a new one begins.
- * This module persists fork metadata to `.unerr/state/timeline-forks.json`,
- * enabling the system to trace what was tried, why it failed, and what replaced it.
- *
- * Storage format: JSON array of TimelineFork objects, newest first.
- * Active timeline ID: persisted alongside forks, monotonically increasing.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("timeline-fork");
-const MAX_FORK_HISTORY = 100;
-let inMemoryTimeline = 0;
-/**
- * Creates a new timeline fork when a rewind occurs.
- *
- * When called with unerrDir, reads/writes persistent state.
- * When called without unerrDir, uses in-memory counter (for lightweight use).
- */
-export function createTimelineFork(snapshotId, abandonedEntities, prompts, reason, unerrDir) {
-    const state = unerrDir
-        ? loadState(unerrDir)
-        : { activeTimeline: inMemoryTimeline, forks: [] };
-    const now = new Date().toISOString();
-    const currentTimeline = state.activeTimeline;
-    const nextTimeline = currentTimeline + 1;
-    const fork = {
-        forkPoint: snapshotId,
-        abandonedBranch: {
-            timelineId: currentTimeline,
-            entityChanges: deduplicateStrings(abandonedEntities),
-            promptsTried: deduplicateStrings(prompts),
-            ...(reason ? { failureReason: reason } : {}),
-        },
-        newBranch: {
-            timelineId: nextTimeline,
-            startedAt: now,
-        },
-    };
-    state.forks.unshift(fork);
-    if (state.forks.length > MAX_FORK_HISTORY) {
-        state.forks = state.forks.slice(0, MAX_FORK_HISTORY);
-    }
-    state.activeTimeline = nextTimeline;
-    if (unerrDir) {
-        saveState(unerrDir, state);
-    }
-    else {
-        inMemoryTimeline = nextTimeline;
-    }
-    log.info(`Fork created: timeline ${currentTimeline} → ${nextTimeline} at snapshot ${snapshotId}`);
-    return fork;
-}
-/**
- * Returns the active timeline ID for the repository.
- */
-export function getActiveTimeline(unerrDir) {
-    const state = loadState(unerrDir);
-    return state.activeTimeline;
-}
-/**
- * Returns the full fork history, newest first.
- */
-export function getForkHistory(unerrDir) {
-    const state = loadState(unerrDir);
-    return state.forks;
-}
-/**
- * Returns forks where a specific entity was abandoned.
- */
-export function getEntityForkHistory(unerrDir, entityKey) {
-    const state = loadState(unerrDir);
-    return state.forks.filter((f) => f.abandonedBranch.entityChanges.includes(entityKey));
-}
-/**
- * Returns the most recent fork, or null if no forks have occurred.
- */
-export function getLatestFork(unerrDir) {
-    const state = loadState(unerrDir);
-    return state.forks[0] ?? null;
-}
-/**
- * Returns aggregate statistics about the fork history.
- */
-export function getForkStats(unerrDir) {
-    const state = loadState(unerrDir);
-    const entitySet = new Set();
-    const promptSet = new Set();
-    const reasons = {};
-    for (const fork of state.forks) {
-        for (const entity of fork.abandonedBranch.entityChanges) {
-            entitySet.add(entity);
-        }
-        for (const prompt of fork.abandonedBranch.promptsTried) {
-            promptSet.add(prompt);
-        }
-        if (fork.abandonedBranch.failureReason) {
-            const reason = fork.abandonedBranch.failureReason;
-            reasons[reason] = (reasons[reason] ?? 0) + 1;
-        }
-    }
-    return {
-        totalForks: state.forks.length,
-        activeTimeline: state.activeTimeline,
-        uniqueEntitiesAbandoned: entitySet.size,
-        uniquePromptsAbandoned: promptSet.size,
-        failureReasons: reasons,
-    };
-}
-/**
- * Checks if a fork involved a specific snapshot as its fork point.
- */
-export function wasForkPoint(unerrDir, snapshotId) {
-    const state = loadState(unerrDir);
-    return state.forks.some((f) => f.forkPoint === snapshotId);
-}
-/**
- * Returns all prompts tried across abandoned timelines for a given entity.
- * Useful for avoiding repeated failed approaches.
- */
-export function getAbandonedPrompts(unerrDir, entityKey) {
-    const state = loadState(unerrDir);
-    const prompts = new Set();
-    for (const fork of state.forks) {
-        if (fork.abandonedBranch.entityChanges.includes(entityKey)) {
-            for (const p of fork.abandonedBranch.promptsTried) {
-                prompts.add(p);
-            }
-        }
-    }
-    return Array.from(prompts);
-}
-/**
- * Returns the timeline ID at a given fork point, or null if not a fork point.
- */
-export function getTimelineAtFork(unerrDir, snapshotId) {
-    const state = loadState(unerrDir);
-    const fork = state.forks.find((f) => f.forkPoint === snapshotId);
-    if (!fork)
-        return null;
-    return {
-        abandoned: fork.abandonedBranch.timelineId,
-        created: fork.newBranch.timelineId,
-    };
-}
-/**
- * Resets the timeline state. Primarily for testing.
- */
-export function resetTimelineForks(unerrDir) {
-    const defaultState = {
-        activeTimeline: 0,
-        forks: [],
-    };
-    saveState(unerrDir, defaultState);
-    log.info("Timeline fork state reset");
-}
-/**
- * Compacts the fork history by removing forks older than the given cutoff.
- */
-export function compactForkHistory(unerrDir, maxAge) {
-    const state = loadState(unerrDir);
-    const cutoff = Date.now() - maxAge;
-    const originalCount = state.forks.length;
-    state.forks = state.forks.filter((f) => {
-        const forkTs = new Date(f.newBranch.startedAt).getTime();
-        return forkTs >= cutoff;
-    });
-    const removed = originalCount - state.forks.length;
-    if (removed > 0) {
-        saveState(unerrDir, state);
-        log.info(`Compacted ${removed} old forks`);
-    }
-    return removed;
-}
-// ── Persistence ─────────────────────────────────────────────────────
-function getStatePath(unerrDir) {
-    return join(unerrDir, "state", "timeline-forks.json");
-}
-function ensureStateDir(unerrDir) {
-    const stateDir = join(unerrDir, "state");
-    if (!existsSync(stateDir)) {
-        mkdirSync(stateDir, { recursive: true });
-    }
-}
-function loadState(unerrDir) {
-    const path = getStatePath(unerrDir);
-    if (!existsSync(path)) {
-        return { activeTimeline: 0, forks: [] };
-    }
-    try {
-        const raw = readFileSync(path, "utf-8");
-        const parsed = JSON.parse(raw);
-        return {
-            activeTimeline: typeof parsed.activeTimeline === "number" ? parsed.activeTimeline : 0,
-            forks: Array.isArray(parsed.forks) ? parsed.forks : [],
-        };
-    }
-    catch {
-        log.warn("Failed to parse timeline-forks.json, starting fresh");
-        return { activeTimeline: 0, forks: [] };
-    }
-}
-function saveState(unerrDir, state) {
-    ensureStateDir(unerrDir);
-    const path = getStatePath(unerrDir);
-    writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
-}
-function deduplicateStrings(arr) {
-    return Array.from(new Set(arr));
-}

package/dist/tracking/timeline.js

@@ -1,69 +0,0 @@
-/**
- * Sprint 10.3: Timeline View — chronological ledger entries per branch.
- *
- * Provides `unerr_get_timeline` MCP tool: returns ledger entries
- * grouped by branch with timeline branch counter for rewind context.
- *
- * Design authority: Phase 5.5 §1.5 (Timeline View)
- */
-/** stderr logger */
-const _log = {
-    info: (msg) => process.stderr.write(`[unerr:timeline] ${msg}\n`),
-};
-/**
- * Build a timeline view from the shadow ledger.
- */
-export function getTimeline(ledger, currentBranch, timelineBranch, opts = {}) {
-    const limit = opts.limit ?? 50;
-    const branch = opts.branch ?? currentBranch;
-    // Read all entries from buffer (fast path) or file (full history)
-    let entries;
-    if (limit <= 100) {
-        entries = ledger.getRecentEntries(100);
-    }
-    else {
-        entries = ledger.readAllEntries();
-    }
-    // Apply filters
-    let filtered = entries.filter((e) => e.branch === branch);
-    if (opts.tool) {
-        filtered = filtered.filter((e) => e.tool === opts.tool);
-    }
-    if (opts.rootsOnly) {
-        filtered = filtered.filter((e) => e.correlation_id === null);
-    }
-    if (opts.after) {
-        const afterMs = new Date(opts.after).getTime();
-        filtered = filtered.filter((e) => new Date(e.ts).getTime() > afterMs);
-    }
-    if (opts.before) {
-        const beforeMs = new Date(opts.before).getTime();
-        filtered = filtered.filter((e) => new Date(e.ts).getTime() < beforeMs);
-    }
-    const totalCount = filtered.length;
-    // Most recent first, then apply limit
-    filtered.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
-    const limited = filtered.slice(0, limit);
-    // Map to timeline entries
-    const timelineEntries = limited.map((e) => ({
-        id: e.id,
-        timestamp: e.ts,
-        tool: e.tool,
-        argsSummary: e.args_summary,
-        resultSummary: e.result_summary,
-        branch: e.branch,
-        headSha: e.head_sha,
-        correlationId: e.correlation_id,
-        commitSha: e.commit_sha,
-        planSummary: e.plan_summary,
-        changeType: e.change_type,
-        featureArea: e.feature_area,
-    }));
-    return {
-        entries: timelineEntries,
-        branch,
-        timelineBranch,
-        totalCount,
-        sessionId: ledger.getSessionId(),
-    };
-}