@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/tracking/working-snapshots.js

@@ -1,188 +0,0 @@
-/**
- * Sprint 10.1: Working Snapshot Management.
- *
- * Manages "known-good" state snapshots. The developer (or agent) marks
- * "this works" after tests pass, before risky changes, or at session start.
- * These snapshots become rewind targets for deterministic rewind (Task 10.2).
- *
- * Storage: `.unerr/snapshots/{id}.json`
- * Processing: deferred to ledger flush.
- *
- * Design authority: Phase 5.5 Flow 2 (State Validated → Working Snapshot Created)
- */
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
-import { join } from "node:path";
-/** stderr logger */
-const _log = {
-    info: (msg) => process.stderr.write(`[unerr:snapshot] ${msg}\n`),
-    warn: (msg) => process.stderr.write(`[unerr:snapshot] WARN: ${msg}\n`),
-};
-/** Maximum snapshots retained locally (oldest evicted). */
-const MAX_SNAPSHOTS = 50;
-/** Auto-snapshot cooldown: don't auto-snapshot within 1 hour of last. */
-const AUTO_SNAPSHOT_COOLDOWN_MS = 60 * 60 * 1000;
-export class WorkingSnapshotStore {
-    snapshotDir;
-    unerrDir;
-    constructor(unerrDir) {
-        this.unerrDir = unerrDir;
-        this.snapshotDir = join(unerrDir, "snapshots");
-        if (!existsSync(this.snapshotDir)) {
-            mkdirSync(this.snapshotDir, { recursive: true });
-        }
-    }
-    /**
-     * Create a new working snapshot.
-     */
-    create(opts) {
-        const id = `snap_${randomBytes(6).toString("hex")}`;
-        const snapshot = {
-            id,
-            commitSha: opts.commitSha,
-            reason: opts.reason,
-            timestamp: new Date().toISOString(),
-            branch: opts.branch,
-            timelineBranch: opts.timelineBranch,
-            sessionId: opts.sessionId,
-            processed: false,
-        };
-        writeFileSync(join(this.snapshotDir, `${id}.json`), JSON.stringify(snapshot, null, 2), "utf-8");
-        _log.info(`Created snapshot ${id} at ${opts.commitSha.slice(0, 8)} (${opts.reason})`);
-        // Enforce cap
-        this.enforceCap();
-        return snapshot;
-    }
-    /**
-     * Get a snapshot by ID.
-     */
-    get(snapshotId) {
-        const filePath = join(this.snapshotDir, `${snapshotId}.json`);
-        if (!existsSync(filePath))
-            return null;
-        try {
-            return JSON.parse(readFileSync(filePath, "utf-8"));
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * List all snapshots, most recent first.
-     */
-    list() {
-        if (!existsSync(this.snapshotDir))
-            return [];
-        const files = readdirSync(this.snapshotDir).filter((f) => f.endsWith(".json"));
-        const snapshots = [];
-        for (const file of files) {
-            try {
-                const raw = readFileSync(join(this.snapshotDir, file), "utf-8");
-                snapshots.push(JSON.parse(raw));
-            }
-            catch {
-                // Skip corrupted files
-            }
-        }
-        // Sort by timestamp descending
-        snapshots.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-        return snapshots;
-    }
-    /**
-     * Get the most recent snapshot (rewind target).
-     */
-    getLatest() {
-        const snapshots = this.list();
-        return snapshots[0] ?? null;
-    }
-    /**
-     * Get the most recent snapshot for a specific branch.
-     */
-    getLatestForBranch(branch) {
-        const snapshots = this.list();
-        return snapshots.find((s) => s.branch === branch) ?? null;
-    }
-    /**
-     * Check if auto-snapshot should be created (no recent snapshot within cooldown).
-     */
-    shouldAutoSnapshot() {
-        const latest = this.getLatest();
-        if (!latest)
-            return true;
-        const age = Date.now() - new Date(latest.timestamp).getTime();
-        return age > AUTO_SNAPSHOT_COOLDOWN_MS;
-    }
-    /**
-     * Mark a snapshot as processed.
-     */
-    markProcessed(snapshotId) {
-        const snapshot = this.get(snapshotId);
-        if (!snapshot)
-            return;
-        snapshot.processed = true;
-        writeFileSync(join(this.snapshotDir, `${snapshotId}.json`), JSON.stringify(snapshot, null, 2), "utf-8");
-    }
-    /**
-     * Get all unprocessed snapshots (for ledger flush).
-     */
-    getUnprocessed() {
-        return this.list().filter((s) => !s.processed);
-    }
-    /**
-     * Delete a snapshot.
-     */
-    delete(snapshotId) {
-        const filePath = join(this.snapshotDir, `${snapshotId}.json`);
-        if (!existsSync(filePath))
-            return false;
-        rmSync(filePath);
-        return true;
-    }
-    /**
-     * Get the timeline branch counter from branch_context.json.
-     */
-    getTimelineBranch() {
-        const contextPath = join(this.unerrDir, "branch_context.json");
-        if (!existsSync(contextPath))
-            return 0;
-        try {
-            const ctx = JSON.parse(readFileSync(contextPath, "utf-8"));
-            return ctx.timelineBranch ?? 0;
-        }
-        catch {
-            return 0;
-        }
-    }
-    /**
-     * Increment the timeline branch counter. Returns the new value.
-     */
-    incrementTimelineBranch() {
-        const contextPath = join(this.unerrDir, "branch_context.json");
-        let ctx = {};
-        if (existsSync(contextPath)) {
-            try {
-                ctx = JSON.parse(readFileSync(contextPath, "utf-8"));
-            }
-            catch {
-                ctx = {};
-            }
-        }
-        const current = ctx.timelineBranch ?? 0;
-        ctx.timelineBranch = current + 1;
-        writeFileSync(contextPath, JSON.stringify(ctx, null, 2), "utf-8");
-        return current + 1;
-    }
-    /**
-     * Enforce max snapshot cap — evict oldest beyond limit.
-     */
-    enforceCap() {
-        const snapshots = this.list();
-        if (snapshots.length <= MAX_SNAPSHOTS)
-            return;
-        const toRemove = snapshots.slice(MAX_SNAPSHOTS);
-        for (const snapshot of toRemove) {
-            this.delete(snapshot.id);
-            _log.info(`Evicted old snapshot: ${snapshot.id}`);
-        }
-    }
-}

package/dist/tracking/workspace-manifest.js

@@ -1,176 +0,0 @@
-/**
- * Workspace Manifest — Causal Bridge between intents and commits.
- *
- * Maintains `.unerr/manifest.json` — a structured record linking AI intent
- * chains to git commits. This file is the single source of truth for
- * attributing "why" a change was made (AI-assisted or human-only).
- *
- * Flow:
- *   1. Shadow Ledger records every tool call with correlation IDs
- *   2. Intent Correlator groups related calls into pending correlations
- *   3. Commit Watcher associates pending correlations with commit SHAs
- *   4. Workspace Manifest snapshots committed correlations into attribution records
- *   5. On push/PR → manifest is persisted locally for PR badges + attribution
- *
- * File: .unerr/manifest.json
- *
- * All logging to stderr (stdout reserved for MCP).
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-// ── Manifest Manager ────────────────────────────────────────────────
-export class WorkspaceManifest {
-    unerrDir;
-    repoId;
-    sessionId;
-    manifestPath;
-    data;
-    constructor(unerrDir, repoId, sessionId) {
-        this.unerrDir = unerrDir;
-        this.repoId = repoId;
-        this.sessionId = sessionId;
-        this.manifestPath = join(unerrDir, "manifest.json");
-        this.data = this.load();
-    }
-    /**
-     * Record a committed correlation as an attribution.
-     * Called by CommitWatcher when it associates a pending correlation with a commit.
-     */
-    recordAttribution(correlation, branch) {
-        if (!correlation.commitSha)
-            return; // Only committed correlations
-        const record = {
-            intentId: correlation.rootIntentId,
-            commitSha: correlation.commitSha,
-            branch,
-            sessionId: this.sessionId,
-            prompt: correlation.prompt,
-            toolChain: correlation.toolChain,
-            entitiesAffected: correlation.entities,
-            filesChanged: correlation.files,
-            correlatedAt: correlation.createdAt,
-            committedAt: new Date().toISOString(),
-            flushed: false,
-        };
-        this.data.records.push(record);
-        this.save();
-    }
-    /**
-     * Get unflushed attribution records.
-     */
-    getUnflushedRecords() {
-        return this.data.records.filter((r) => !r.flushed);
-    }
-    /**
-     * Mark records as flushed after successful processing.
-     */
-    markFlushed(intentIds) {
-        const idSet = new Set(intentIds);
-        for (const record of this.data.records) {
-            if (idSet.has(record.intentId)) {
-                record.flushed = true;
-            }
-        }
-        this.data.lastFlushedAt = new Date().toISOString();
-        this.data.totalFlushed += intentIds.length;
-        this.save();
-        // Prune old flushed records (keep last 50)
-        this.pruneOldRecords();
-    }
-    /**
-     * Get manifest stats for display.
-     */
-    getStats() {
-        return {
-            total: this.data.records.length,
-            unflushed: this.data.records.filter((r) => !r.flushed).length,
-            orphanedIntents: this.data.orphanedIntents?.length ?? 0,
-            lastFlushedAt: this.data.lastFlushedAt,
-        };
-    }
-    /**
-     * Record an orphaned intent — a pending correlation that was never committed.
-     * Called when the proxy detects stale correlations (e.g., session shutdown
-     * with pending correlations older than the correlation window).
-     */
-    recordOrphanedIntents(intents) {
-        if (intents.length === 0)
-            return;
-        if (!this.data.orphanedIntents) {
-            this.data.orphanedIntents = [];
-        }
-        for (const intent of intents) {
-            this.data.orphanedIntents.push({
-                intentId: intent.rootIntentId,
-                prompt: intent.prompt,
-                toolChain: intent.toolChain,
-                filesAffected: intent.files,
-                detectedAt: new Date().toISOString(),
-                originalAt: intent.createdAt,
-            });
-        }
-        // Keep only the last 100 orphaned intents
-        if (this.data.orphanedIntents.length > 100) {
-            this.data.orphanedIntents = this.data.orphanedIntents.slice(-100);
-        }
-        this.save();
-    }
-    /**
-     * Get orphaned intents for display in workspace views.
-     */
-    getOrphanedIntents() {
-        return this.data.orphanedIntents ?? [];
-    }
-    // ── Internal ─────────────────────────────────────────────────────
-    load() {
-        if (!existsSync(this.manifestPath)) {
-            return {
-                version: 1,
-                repoId: this.repoId,
-                records: [],
-                lastFlushedAt: null,
-                totalFlushed: 0,
-            };
-        }
-        try {
-            const raw = readFileSync(this.manifestPath, "utf-8");
-            const parsed = JSON.parse(raw);
-            // Validate it's for this repo
-            if (parsed.repoId !== this.repoId) {
-                return {
-                    version: 1,
-                    repoId: this.repoId,
-                    records: [],
-                    lastFlushedAt: null,
-                    totalFlushed: 0,
-                };
-            }
-            return parsed;
-        }
-        catch {
-            return {
-                version: 1,
-                repoId: this.repoId,
-                records: [],
-                lastFlushedAt: null,
-                totalFlushed: 0,
-            };
-        }
-    }
-    save() {
-        if (!existsSync(this.unerrDir)) {
-            mkdirSync(this.unerrDir, { recursive: true });
-        }
-        writeFileSync(this.manifestPath, JSON.stringify(this.data, null, 2), "utf-8");
-    }
-    pruneOldRecords() {
-        const flushed = this.data.records.filter((r) => r.flushed);
-        if (flushed.length <= 50)
-            return;
-        // Keep only unflushed + last 50 flushed
-        const unflushed = this.data.records.filter((r) => !r.flushed);
-        const recentFlushed = flushed.slice(-50);
-        this.data.records = [...recentFlushed, ...unflushed];
-        this.save();
-    }
-}

package/dist/transport/http.js

@@ -1,102 +0,0 @@
-/**
- * HTTP Transport — Hono-based HTTP server for the intelligence proxy.
- *
- * Provides an alternative transport to stdio MCP. Disabled by default,
- * enabled via `unerr --http` or `unerr serve --http-port 3141`.
- *
- * Endpoints:
- *   GET  /health   → { status, version, uptime_ms }
- *   GET  /ui/*     → Static files from packages/ui/dist/ (dashboard)
- *   GET  /ui       → Redirect to /ui/
- *
- * Invariant: The HTTP server never interferes with MCP stdio transport.
- * Both can run simultaneously — HTTP on a port, MCP on stdin/stdout.
- */
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { extname, join } from "node:path";
-import { serve } from "@hono/node-server";
-import { Hono } from "hono";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("http");
-const startedAt = Date.now();
-const MIME_TYPES = {
-    ".html": "text/html",
-    ".js": "application/javascript",
-    ".css": "text/css",
-    ".json": "application/json",
-    ".svg": "image/svg+xml",
-    ".png": "image/png",
-    ".ico": "image/x-icon",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-};
-function resolveUiDistDir() {
-    const candidates = [
-        join(process.cwd(), "packages", "ui", "dist"),
-        join(process.cwd(), "..", "packages", "ui", "dist"),
-    ];
-    for (const dir of candidates) {
-        if (existsSync(join(dir, "index.html")))
-            return dir;
-    }
-    return null;
-}
-export function createHttpTransport(options = {}) {
-    const port = options.port ?? 3141;
-    const hostname = options.hostname ?? "127.0.0.1";
-    const app = new Hono();
-    app.get("/health", (c) => c.json({
-        status: "ok",
-        version: "0.1.0",
-        uptime_ms: Date.now() - startedAt,
-    }));
-    app.get("/ui", (c) => c.redirect("/ui/"));
-    app.get("/ui/*", async (c) => {
-        const uiDir = resolveUiDistDir();
-        if (!uiDir) {
-            return c.json({ error: "UI not built. Run: pnpm --filter @unerr/ui build" }, 404);
-        }
-        let filePath = c.req.path.replace(/^\/ui\/?/, "");
-        if (!filePath || filePath === "/")
-            filePath = "index.html";
-        const fullPath = join(uiDir, filePath);
-        if (!fullPath.startsWith(uiDir)) {
-            return c.json({ error: "forbidden" }, 403);
-        }
-        try {
-            const content = await readFile(fullPath);
-            const ext = extname(filePath);
-            const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-            return new Response(content, {
-                headers: { "Content-Type": contentType },
-            });
-        }
-        catch {
-            const indexPath = join(uiDir, "index.html");
-            try {
-                const indexContent = await readFile(indexPath);
-                return new Response(indexContent, {
-                    headers: { "Content-Type": "text/html" },
-                });
-            }
-            catch {
-                return c.json({ error: "not_found" }, 404);
-            }
-        }
-    });
-    app.onError((err, c) => {
-        log.error("Unhandled HTTP error:", err.message);
-        return c.json({ error: "internal_error", message: err.message }, 500);
-    });
-    app.notFound((c) => c.json({
-        error: "not_found",
-        message: `${c.req.method} ${c.req.path} not found`,
-    }, 404));
-    const start = () => {
-        const server = serve({ fetch: app.fetch, port, hostname });
-        log.info(`HTTP transport listening on http://${hostname}:${port}`);
-        return server;
-    };
-    return { app, start, port };
-}

package/dist/utils/counterfactual.js

@@ -1,65 +0,0 @@
-/**
- * Counterfactual Framing Utility — wraps all savings displays in
- * "without unerr" framing for value perception.
- *
- * VS.8: Every savings display must use counterfactual language:
- *   "Without unerr, this session would have cost $X.XX more"
- *   "Without unerr, the agent would have explored 15 files to find this"
- */
-import { formatDollars } from "../proxy/model-pricing.js";
-/**
- * Frame a token savings as a counterfactual statement.
- */
-export function frameTokenSavings(tokensSaved, dollarsSaved) {
-    if (tokensSaved <= 0)
-        return "";
-    const tokensStr = tokensSaved >= 1000
-        ? `${(tokensSaved / 1000).toFixed(1)}K`
-        : String(tokensSaved);
-    return `Without unerr, ${tokensStr} additional tokens (${formatDollars(dollarsSaved)}) would have been consumed.`;
-}
-/**
- * Frame a guard moment (prevented cost).
- */
-export function frameGuardMoment(description, dollarsPrevented) {
-    return `[unerr] ⚠ Prevented: ${description}. Without unerr, est. cost: ${formatDollars(dollarsPrevented)}`;
-}
-/**
- * Frame exploration savings.
- */
-export function frameExplorationSaving(queryType, filesAvoided) {
-    return `Without unerr, the agent would have read ~${filesAvoided} files to get this information.`;
-}
-/**
- * Frame session summary with counterfactual.
- */
-export function frameSessionSummary(tokensSaved, dollarsSaved, guardsFirered) {
-    const parts = [];
-    if (tokensSaved > 0) {
-        const tokensStr = tokensSaved >= 1000
-            ? `${(tokensSaved / 1000).toFixed(1)}K`
-            : String(tokensSaved);
-        parts.push(`${tokensStr} tokens saved (${formatDollars(dollarsSaved)})`);
-    }
-    if (guardsFirered > 0) {
-        parts.push(`${guardsFirered} issue(s) prevented`);
-    }
-    if (parts.length === 0) {
-        return "Graph intelligence active — monitoring for savings opportunities.";
-    }
-    return `Without unerr: ${parts.join(", ")} would have been wasted.`;
-}
-/**
- * Frame a weekly trend delta.
- */
-export function frameWeeklyTrend(thisWeekSaved, lastWeekSaved, dollarsSaved) {
-    const trend = thisWeekSaved > lastWeekSaved
-        ? "↑"
-        : thisWeekSaved < lastWeekSaved
-            ? "↓"
-            : "→";
-    const tokensStr = thisWeekSaved >= 1000
-        ? `${(thisWeekSaved / 1000).toFixed(1)}K`
-        : String(thisWeekSaved);
-    return `This week: ${tokensStr} tokens saved (${formatDollars(dollarsSaved)}) ${trend}`;
-}

package/dist/utils/deep-link.js

@@ -1,34 +0,0 @@
-/**
- * Deep-link URL generation for bridging CLI → web dashboard.
- *
- * §0.7 Constraint #8: "Every terminal display must include a deep link."
- * Used by: startup display, status command, health check, session summary.
- */
-const BASE_URL = "https://app.unerr.dev";
-/**
- * Generate a context-aware deep link to the unerr web dashboard.
- *
- * @param repoId - Repository identifier (e.g. "repo_abc123"). If empty/undefined, returns generic landing.
- * @param options - Query parameters for view targeting and analytics.
- * @returns Full URL string with query parameters.
- */
-export function buildDeepLink(repoId, options) {
-    if (!repoId) {
-        // Fallback: generic landing when repo context unavailable
-        const params = new URLSearchParams();
-        params.set("utm_source", options?.utm_source ?? "cli");
-        return `${BASE_URL}?${params.toString()}`;
-    }
-    const base = `${BASE_URL}/r/${repoId}`;
-    const params = new URLSearchParams();
-    if (options?.view)
-        params.set("view", options.view);
-    if (options?.branch)
-        params.set("branch", options.branch);
-    if (options?.entities?.length)
-        params.set("entities", options.entities.join(","));
-    if (options?.intents?.length)
-        params.set("intents", options.intents.join(","));
-    params.set("utm_source", options?.utm_source ?? "cli");
-    return `${base}?${params.toString()}`;
-}