@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/tracking/working-snapshots.js

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

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

@@ -0,0 +1,102 @@
+/**
+ * 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 };
+}