@unerr-ai/unerr 0.2.0 → 0.2.2

package/dist/tracking/git-trailers.js

@@ -1,171 +0,0 @@
-/**
- * Sprint 10.5: Git Trailer Injection — prepare-commit-msg hook + UDS endpoint.
- *
- * Injects `Unerr-Ledger-Id`, `Unerr-Session`, `Unerr-Timeline-Branch` trailers
- * into commit messages via prepare-commit-msg hook.
- *
- * Two integration modes:
- *   1. Hook mode: Shell script calls UDS `/commit-context` endpoint
- *   2. Direct mode: CommitWatcher calls `getTrailers()` after commit detection
- *
- * Design authority: Phase 5.5 §1.4.1 (Git Trailer Injection)
- */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-/** stderr logger */
-const _log = {
-    info: (msg) => process.stderr.write(`[unerr:trailers] ${msg}\n`),
-};
-/**
- * Get trailers for the current commit context.
- * Called by the UDS `/commit-context` endpoint or directly by CommitWatcher.
- */
-export function getCommitTrailers(ledger, timelineBranch, branch) {
-    const recent = ledger.getRecentEntries(1);
-    if (recent.length === 0)
-        return null;
-    const latest = recent[0];
-    return {
-        ledgerId: latest.id,
-        sessionId: ledger.getSessionId(),
-        timelineBranch,
-        branch,
-    };
-}
-/**
- * Format trailers for git commit message injection.
- */
-export function formatTrailers(trailers) {
-    return [
-        `Unerr-Ledger-Id: ${trailers.ledgerId}`,
-        `Unerr-Session: ${trailers.sessionId}`,
-        `Unerr-Timeline-Branch: ${trailers.timelineBranch}`,
-    ].join("\n");
-}
-/**
- * Install the prepare-commit-msg hook that calls the UDS endpoint.
- * Only installs if:
- *   1. The hook doesn't already exist or doesn't contain our marker
- *   2. The .git/hooks directory exists
- */
-export function installPrepareCommitMsgHook(projectRoot) {
-    const hooksDir = join(projectRoot, ".git", "hooks");
-    if (!existsSync(hooksDir)) {
-        // Not a git repo or hooks dir missing
-        return false;
-    }
-    const hookPath = join(hooksDir, "prepare-commit-msg");
-    const marker = "# unerr-trailer-injection";
-    // Check if hook already exists with our marker
-    if (existsSync(hookPath)) {
-        try {
-            const existing = readFileSync(hookPath, "utf-8");
-            if (existing.includes(marker)) {
-                return true; // Already installed
-            }
-            // Hook exists but isn't ours — append our section
-            const appendSection = `\n\n${marker}\n${generateHookScript()}`;
-            writeFileSync(hookPath, existing + appendSection, { mode: 0o755 });
-            _log.info("Appended trailer injection to existing prepare-commit-msg hook");
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    // Create new hook
-    const hookContent = `#!/bin/sh\n${marker}\n${generateHookScript()}`;
-    try {
-        writeFileSync(hookPath, hookContent, { mode: 0o755 });
-        _log.info("Installed prepare-commit-msg hook for trailer injection");
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Remove the prepare-commit-msg hook (or our section from it).
- */
-export function uninstallPrepareCommitMsgHook(projectRoot) {
-    const hookPath = join(projectRoot, ".git", "hooks", "prepare-commit-msg");
-    if (!existsSync(hookPath))
-        return true;
-    try {
-        const content = readFileSync(hookPath, "utf-8");
-        const marker = "# unerr-trailer-injection";
-        if (!content.includes(marker))
-            return true; // Not our hook
-        // If the entire hook is ours, remove the file
-        const lines = content.split("\n");
-        const nonUnerrLines = lines.filter((line) => !line.includes(marker) &&
-            !line.includes("unerr") &&
-            !line.includes("Unerr-"));
-        // If only shebang remains, remove the file
-        if (nonUnerrLines.length <= 1 && nonUnerrLines[0]?.startsWith("#!/")) {
-            const { unlinkSync } = require("node:fs");
-            unlinkSync(hookPath);
-        }
-        else {
-            // Remove our section
-            const markerIdx = content.indexOf(marker);
-            if (markerIdx > 0) {
-                writeFileSync(hookPath, `${content.slice(0, markerIdx).trimEnd()}\n`, {
-                    mode: 0o755,
-                });
-            }
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Generate the hook script body that queries the UDS endpoint.
- */
-function generateHookScript() {
-    return `# Inject unerr ledger trailers into commit message
-COMMIT_MSG_FILE="$1"
-SOCK=".unerr/state/proxy.sock"
-
-if [ -S "$SOCK" ]; then
-  TRAILERS=$(curl -s --unix-socket "$SOCK" http://localhost/commit-context 2>/dev/null)
-  if [ -n "$TRAILERS" ] && [ "$TRAILERS" != "null" ]; then
-    LEDGER_ID=$(echo "$TRAILERS" | grep -o '"ledgerId":"[^"]*"' | cut -d'"' -f4)
-    SESSION_ID=$(echo "$TRAILERS" | grep -o '"sessionId":"[^"]*"' | cut -d'"' -f4)
-    TIMELINE=$(echo "$TRAILERS" | grep -o '"timelineBranch":[0-9]*' | cut -d: -f2)
-    if [ -n "$LEDGER_ID" ]; then
-      echo "" >> "$COMMIT_MSG_FILE"
-      echo "Unerr-Ledger-Id: $LEDGER_ID" >> "$COMMIT_MSG_FILE"
-      echo "Unerr-Session: $SESSION_ID" >> "$COMMIT_MSG_FILE"
-      echo "Unerr-Timeline-Branch: $TIMELINE" >> "$COMMIT_MSG_FILE"
-    fi
-  fi
-fi`;
-}
-/**
- * Parse trailers from a commit message. Returns null if no unerr trailers found.
- */
-export function parseTrailersFromMessage(commitMessage) {
-    const lines = commitMessage.split("\n");
-    let ledgerId = null;
-    let sessionId = null;
-    let timelineBranch = 0;
-    const branch = "unknown";
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed.startsWith("Unerr-Ledger-Id:")) {
-            ledgerId = trimmed.slice("Unerr-Ledger-Id:".length).trim();
-        }
-        else if (trimmed.startsWith("Unerr-Session:")) {
-            sessionId = trimmed.slice("Unerr-Session:".length).trim();
-        }
-        else if (trimmed.startsWith("Unerr-Timeline-Branch:")) {
-            timelineBranch = Number.parseInt(trimmed.slice("Unerr-Timeline-Branch:".length).trim(), 10);
-        }
-    }
-    if (!ledgerId || !sessionId)
-        return null;
-    return { ledgerId, sessionId, timelineBranch, branch };
-}

package/dist/tracking/intelligence-counter.js

@@ -1,46 +0,0 @@
-/**
- * Compound Intelligence Counter — tracks accumulated knowledge.
- *
- * VS.7: Displays in status + weekly: entity count, edge count,
- * conventions learned, rules generated, corrections applied.
- */
-export function createIntelligenceCounter() {
-    const metrics = {
-        entityCount: 0,
-        edgeCount: 0,
-        conventionsLearned: 0,
-        rulesGenerated: 0,
-        correctionsApplied: 0,
-        communitiesDetected: 0,
-        sessionsIndexed: 0,
-    };
-    function record(field, value) {
-        metrics[field] = value;
-    }
-    function increment(field) {
-        metrics[field]++;
-    }
-    function getMetrics() {
-        return { ...metrics };
-    }
-    function formatSummary() {
-        const parts = [
-            `${metrics.entityCount.toLocaleString()} entities`,
-            `${metrics.edgeCount.toLocaleString()} edges`,
-            `${metrics.communitiesDetected} communities`,
-        ];
-        if (metrics.conventionsLearned > 0)
-            parts.push(`${metrics.conventionsLearned} conventions`);
-        if (metrics.rulesGenerated > 0)
-            parts.push(`${metrics.rulesGenerated} rules`);
-        if (metrics.correctionsApplied > 0)
-            parts.push(`${metrics.correctionsApplied} corrections`);
-        return `Intelligence: ${parts.join(", ")}`;
-    }
-    function reset() {
-        for (const k of Object.keys(metrics)) {
-            metrics[k] = 0;
-        }
-    }
-    return { record, increment, getMetrics, formatSummary, reset };
-}

package/dist/tracking/intent-correlator.js

@@ -1,202 +0,0 @@
-/**
- * Intent Correlator — builds intent chains linking related tool calls.
- *
- * Maintains `pending_correlations.json` — intents that produced file changes
- * (via `sync_local_diff`) but haven't been committed yet. Each pending
- * correlation records the prompt, changed files, affected entities, and the
- * full tool chain that led to the change.
- *
- * Lifecycle:
- *   1. Tool calls flow through ShadowLedger → each gets an entry with correlation_id
- *   2. When sync_local_diff is called → IntentCorrelator creates a pending correlation
- *   3. On git commit (Sprint 5) → pending correlations are associated with commit SHA
- *   4. On push (Sprint 5) → committed entries flushed to local ledger
- *
- * All logging to stderr.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { join } from "node:path";
-export class IntentCorrelator {
-    ledgerDir;
-    pendingPath;
-    pending = [];
-    constructor(unerrDir) {
-        this.ledgerDir = join(unerrDir, "ledger");
-        this.pendingPath = join(this.ledgerDir, "pending_correlations.json");
-        if (!existsSync(this.ledgerDir)) {
-            mkdirSync(this.ledgerDir, { recursive: true });
-        }
-        this.load();
-    }
-    /**
-     * Called when sync_local_diff is invoked. Creates a pending correlation
-     * from the active tool chain in the ledger.
-     */
-    onSyncLocalDiff(ledger, args) {
-        const rootId = ledger.getCurrentRootId();
-        if (!rootId)
-            return null;
-        // Extract data from sync_local_diff args
-        const prompt = args.prompt ?? args.message ?? "";
-        const filesChanged = extractFiles(args);
-        const entitiesAffected = extractEntities(args);
-        // Build the tool chain from ledger buffer
-        const recentEntries = ledger.getRecentEntries(50);
-        const toolChain = buildToolChain(recentEntries, rootId);
-        const correlation = {
-            rootIntentId: rootId,
-            prompt,
-            files: filesChanged,
-            entities: entitiesAffected,
-            toolChain,
-            createdAt: new Date().toISOString(),
-        };
-        this.pending.push(correlation);
-        this.save();
-        return correlation;
-    }
-    /**
-     * Get all pending correlations (not yet committed).
-     */
-    getPending() {
-        return this.pending.filter((c) => !c.commitSha);
-    }
-    /**
-     * Get all pending correlations (including committed but not flushed).
-     */
-    getAll() {
-        return [...this.pending];
-    }
-    /**
-     * Get the count of pending correlations.
-     */
-    getPendingCount() {
-        return this.pending.filter((c) => !c.commitSha).length;
-    }
-    /**
-     * Associate pending correlations with a commit SHA.
-     * Called by the commit watcher when HEAD changes.
-     * Only associates correlations whose files appear in the commit diff.
-     */
-    associateCommit(commitSha, committedFiles) {
-        let associated = 0;
-        const committedSet = new Set(committedFiles);
-        for (const correlation of this.pending) {
-            if (correlation.commitSha)
-                continue; // Already committed
-            // Check if any of the correlation's files are in the commit
-            const hasOverlap = correlation.files.some((f) => committedSet.has(f));
-            if (hasOverlap) {
-                correlation.commitSha = commitSha;
-                associated++;
-            }
-        }
-        if (associated > 0) {
-            this.save();
-        }
-        return associated;
-    }
-    /**
-     * Get committed but not-yet-flushed correlations (for Sprint 5 push).
-     */
-    getCommittedUnflushed() {
-        return this.pending.filter((c) => c.commitSha != null);
-    }
-    /**
-     * Remove correlations that have been flushed.
-     * Called after successful flush in Sprint 5.
-     */
-    removeFlushed(rootIntentIds) {
-        const flushedSet = new Set(rootIntentIds);
-        this.pending = this.pending.filter((c) => !flushedSet.has(c.rootIntentId));
-        this.save();
-    }
-    /**
-     * Clear all pending correlations (e.g., on branch switch).
-     */
-    clear() {
-        this.pending = [];
-        this.save();
-    }
-    // ── Persistence ─────────────────────────────────────────────────
-    load() {
-        if (!existsSync(this.pendingPath))
-            return;
-        try {
-            const raw = readFileSync(this.pendingPath, "utf-8");
-            const parsed = JSON.parse(raw);
-            if (Array.isArray(parsed)) {
-                this.pending = parsed;
-            }
-        }
-        catch {
-            // Corrupted file — start fresh
-            this.pending = [];
-        }
-    }
-    save() {
-        try {
-            const tmpPath = `${this.pendingPath}.tmp`;
-            writeFileSync(tmpPath, JSON.stringify(this.pending, null, 2), "utf-8");
-            renameSync(tmpPath, this.pendingPath);
-        }
-        catch (err) {
-            process.stderr.write(`[unerr:correlator] WARN: Failed to save pending correlations: ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-    }
-}
-/**
- * Extract changed file paths from sync_local_diff args.
- */
-function extractFiles(args) {
-    // Structured format: { files: [{ path, content }] }
-    const files = args.files;
-    if (files && Array.isArray(files)) {
-        return files.map((f) => f.path).filter(Boolean);
-    }
-    // Diff format: parse git diff for file paths
-    const diff = args.diff;
-    if (diff) {
-        const paths = new Set();
-        const matches = diff.matchAll(/^(?:---|\+\+\+)\s+[ab]\/(.+)$/gm);
-        for (const m of matches) {
-            if (m[1])
-                paths.add(m[1]);
-        }
-        return Array.from(paths);
-    }
-    // filesChanged from args directly
-    const filesChanged = args.filesChanged;
-    if (filesChanged && Array.isArray(filesChanged)) {
-        return filesChanged;
-    }
-    return [];
-}
-/**
- * Extract affected entity keys from sync_local_diff args.
- */
-function extractEntities(args) {
-    const entities = args.entitiesAffected;
-    if (entities && Array.isArray(entities)) {
-        return entities;
-    }
-    return [];
-}
-/**
- * Build the tool chain for a correlation by following the intent chain
- * from root to the current sync_local_diff call.
- */
-function buildToolChain(entries, rootId) {
-    const chain = [];
-    for (const entry of entries) {
-        // Include the root entry itself
-        if (entry.id === rootId) {
-            chain.push(entry.tool);
-        }
-        // Include correlated entries
-        else if (entry.correlation_id === rootId) {
-            chain.push(entry.tool);
-        }
-    }
-    return chain;
-}

package/dist/tracking/intent-encoder.js

@@ -1,52 +0,0 @@
-/**
- * Intent Encoder — writes correlated intents as git notes (Layer 2 telemetry).
- *
- * When CommitWatcher detects a commit with associated intents, this encoder
- * writes a compact JSON note to `refs/notes/unerr`. Notes travel with commits
- * and are invisible in `git log` (only visible with `--notes=unerr`).
- *
- * This is insurance — as backup, notes carry intent data with pushes.
- * Fire-and-forget: failures are logged as warnings, never block the proxy.
- */
-import { writeNote } from "../utils/git.js";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("notes");
-/**
- * Encode correlated intents as a git note on the given commit.
- * Fire-and-forget — logs warning on failure, never throws.
- */
-export async function encodeIntentAsNote(commitSha, correlations, sessionId, branchContext, driftSummary, cwd) {
-    if (correlations.length === 0)
-        return false;
-    const note = {
-        v: 1,
-        intents: correlations.map((c) => ({
-            id: c.rootIntentId,
-            prompt: (c.prompt ?? "").slice(0, 200),
-            tools: c.toolChain,
-            entities: c.entities,
-            files: c.files,
-            risk: "l",
-        })),
-        drift: {
-            a: driftSummary.added,
-            m: driftSummary.modified,
-            d: driftSummary.deleted,
-        },
-        sid: sessionId.slice(0, 12),
-        br: branchContext?.currentBranch ?? "unknown",
-    };
-    const noteJson = JSON.stringify(note);
-    if (noteJson.length > 2048) {
-        log.warn(`Note payload exceeds 2KB budget (${noteJson.length} bytes) — writing anyway`);
-    }
-    try {
-        await writeNote(cwd ?? process.cwd(), "unerr", commitSha, noteJson);
-        log.info(`Note written for ${commitSha.slice(0, 8)} (${correlations.length} intent(s), ${noteJson.length}B)`);
-        return true;
-    }
-    catch (err) {
-        log.warn(`Failed to write git note for ${commitSha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`);
-        return false;
-    }
-}

package/dist/tracking/intent-token-tracker.js

@@ -1,159 +0,0 @@
-/**
- * Intent Token Tracker — groups tool calls by intent and tracks tokens per task.
- *
- * Each "intent" represents a coherent unit of work (e.g., "add error handling
- * to auth module"). Tool calls within an intent are aggregated for token
- * consumption, token savings, entity modifications, and duration tracking.
- *
- * Intent groups start when a new intentId is first seen and end when
- * explicitly marked with an outcome. Abandoned intents are detected via
- * inactivity timeout (30 minutes).
- */
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("intent-tokens");
-const ABANDON_TIMEOUT_MS = 30 * 60 * 1000;
-/**
- * Creates an intent-scoped token tracker. Each intent groups related tool calls
- * and accumulates token consumption/savings metrics.
- */
-export function createIntentTokenTracker(options) {
-    const dashboardSink = options?.dashboardSink;
-    const intents = new Map();
-    let activeIntentId = null;
-    function startIntent(intentId, prompt) {
-        if (intents.has(intentId))
-            return;
-        const now = Date.now();
-        intents.set(intentId, {
-            intentId,
-            prompt,
-            toolCalls: 0,
-            tokensConsumed: 0,
-            tokensSaved: 0,
-            entities: new Set(),
-            startedAt: now,
-            lastActivity: now,
-            outcome: "in_progress",
-        });
-        activeIntentId = intentId;
-        dashboardSink?.({
-            phase: "started",
-            intent_id: intentId,
-            prompt,
-        });
-    }
-    function recordToolCall(intentId, tokens, saved, entity) {
-        let state = intents.get(intentId);
-        if (!state) {
-            startIntent(intentId);
-            state = intents.get(intentId);
-        }
-        state.toolCalls += 1;
-        state.tokensConsumed += tokens;
-        state.tokensSaved += saved;
-        state.lastActivity = Date.now();
-        if (entity) {
-            state.entities.add(entity);
-        }
-        activeIntentId = intentId;
-    }
-    function getGroup(intentId) {
-        const state = intents.get(intentId);
-        if (!state)
-            return null;
-        return stateToGroup(state);
-    }
-    function getAllGroups() {
-        checkAbandoned();
-        const groups = [];
-        for (const state of intents.values()) {
-            groups.push(stateToGroup(state));
-        }
-        return groups.sort((a, b) => b.durationMs - a.durationMs);
-    }
-    function markOutcome(intentId, outcome) {
-        const state = intents.get(intentId);
-        if (!state)
-            return;
-        state.outcome = outcome;
-        state.lastActivity = Date.now();
-        dashboardSink?.({
-            phase: "outcome",
-            intent_id: intentId,
-            outcome,
-        });
-        if (outcome !== "in_progress" && activeIntentId === intentId) {
-            activeIntentId = null;
-        }
-    }
-    function getActiveIntentId() {
-        if (!activeIntentId)
-            return null;
-        const state = intents.get(activeIntentId);
-        if (!state || state.outcome !== "in_progress") {
-            activeIntentId = null;
-            return null;
-        }
-        return activeIntentId;
-    }
-    function getTotalTokens() {
-        let consumed = 0;
-        let saved = 0;
-        for (const state of intents.values()) {
-            consumed += state.tokensConsumed;
-            saved += state.tokensSaved;
-        }
-        const total = consumed + saved;
-        const ratio = total > 0 ? saved / total : 0;
-        return {
-            consumed,
-            saved,
-            ratio: Math.round(ratio * 1000) / 1000,
-        };
-    }
-    function pruneAbandoned() {
-        return checkAbandoned();
-    }
-    function checkAbandoned() {
-        const now = Date.now();
-        let count = 0;
-        for (const state of intents.values()) {
-            if (state.outcome !== "in_progress")
-                continue;
-            if (now - state.lastActivity > ABANDON_TIMEOUT_MS) {
-                state.outcome = "abandoned";
-                count += 1;
-                dashboardSink?.({
-                    phase: "abandoned",
-                    intent_id: state.intentId,
-                });
-                log.info(`Intent ${state.intentId} marked abandoned (inactive ${Math.round((now - state.lastActivity) / 60_000)}min)`);
-            }
-        }
-        return count;
-    }
-    function stateToGroup(state) {
-        const now = Date.now();
-        const endTime = state.outcome === "in_progress" ? now : state.lastActivity;
-        return {
-            intentId: state.intentId,
-            prompt: state.prompt,
-            toolCalls: state.toolCalls,
-            tokensConsumed: state.tokensConsumed,
-            tokensSaved: state.tokensSaved,
-            entitiesModified: Array.from(state.entities),
-            durationMs: endTime - state.startedAt,
-            outcome: state.outcome,
-        };
-    }
-    return {
-        startIntent,
-        recordToolCall,
-        getGroup,
-        getAllGroups,
-        markOutcome,
-        getActiveIntentId,
-        getTotalTokens,
-        pruneAbandoned,
-    };
-}