@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/commands/gain.js

@@ -0,0 +1,156 @@
+/**
+ * R5 — `unerr gain` / `unerr discover`
+ *
+ * Two analytics CLI commands that read the token-flow ledger and surface:
+ * - `gain`:     where compression IS working — top commands by tokens_saved
+ * - `discover`: where compression IS NOT working — commands with high raw
+ *               bytes but <30% reduction. These are untapped opportunities.
+ *
+ * Both read `.unerr/token-flow.jsonl` for the current repo only; no network,
+ * no aggregation across repos.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const PALETTE = {
+    reset: "\x1b[0m",
+    violet: "\x1b[38;2;139;92;246m",
+    cyan: "\x1b[38;2;34;211;238m",
+    success: "\x1b[38;2;52;211;153m",
+    warn: "\x1b[38;2;251;191;36m",
+    red: "\x1b[38;2;248;113;113m",
+    dim: "\x1b[38;2;161;161;170m",
+    bold: "\x1b[1m",
+};
+function loadFlow(cwd) {
+    const path = join(cwd, ".unerr", "token-flow.jsonl");
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, "utf8");
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return events;
+}
+/** Normalize a command to its leading-token fingerprint ("git diff" → "git diff"). */
+function commandKey(detail) {
+    const cmd = (detail?.command ?? detail?.cmd);
+    if (!cmd)
+        return null;
+    const tokens = cmd.trim().split(/\s+/).slice(0, 2).join(" ");
+    return tokens || null;
+}
+function aggregateByCommand(events) {
+    const map = new Map();
+    for (const e of events) {
+        if (e.mechanism !== "shell_compression")
+            continue;
+        const key = commandKey(e.detail);
+        if (!key)
+            continue;
+        let row = map.get(key);
+        if (!row) {
+            row = {
+                command: key,
+                invocations: 0,
+                rawTokens: 0,
+                outTokens: 0,
+                savedTokens: 0,
+                ratio: 0,
+            };
+            map.set(key, row);
+        }
+        row.invocations++;
+        row.rawTokens += e.tokens_without;
+        row.outTokens += e.tokens_with;
+        row.savedTokens += e.tokens_saved;
+    }
+    for (const row of map.values()) {
+        row.ratio = row.rawTokens > 0 ? row.savedTokens / row.rawTokens : 0;
+    }
+    return [...map.values()];
+}
+function fmtNum(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return `${n}`;
+}
+function table(rows, title, kind) {
+    const c = PALETTE;
+    const out = [];
+    out.push("");
+    out.push(`  ${c.violet}◆${c.reset} ${c.bold}${title}${c.reset}`);
+    out.push("");
+    if (rows.length === 0) {
+        out.push(`  ${c.dim}No matching shell compression events yet.${c.reset}`);
+        out.push("");
+        return out.join("\n");
+    }
+    out.push(`  ${c.dim}${"command".padEnd(28)} ${"invs".padStart(5)}  ${"raw".padStart(7)}  ${"saved".padStart(7)}  ${"ratio".padStart(6)}${c.reset}`);
+    out.push(`  ${c.dim}${"".padEnd(28, "─")} ${"────".padStart(5)}  ${"───".padStart(7)}  ${"─────".padStart(7)}  ${"─────".padStart(6)}${c.reset}`);
+    for (const r of rows) {
+        const ratioColor = kind === "discover"
+            ? r.ratio < 0.3
+                ? c.red
+                : r.ratio < 0.5
+                    ? c.warn
+                    : c.dim
+            : r.ratio >= 0.8
+                ? c.success
+                : r.ratio >= 0.5
+                    ? c.cyan
+                    : c.warn;
+        const cmd = r.command.slice(0, 28).padEnd(28);
+        const ratioStr = `${(r.ratio * 100).toFixed(0)}%`.padStart(6);
+        out.push(`  ${cmd} ${String(r.invocations).padStart(5)}  ${fmtNum(r.rawTokens).padStart(7)}  ${fmtNum(r.savedTokens).padStart(7)}  ${ratioColor}${ratioStr}${c.reset}`);
+    }
+    out.push("");
+    return out.join("\n");
+}
+export function registerGainCommand(program) {
+    program
+        .command("gain")
+        .description("Show top commands by tokens saved through shell compression (this repo)")
+        .option("-n, --limit <n>", "Number of rows to show", "20")
+        .action((opts) => {
+        const limit = Number.parseInt(opts.limit, 10) || 20;
+        const cwd = process.cwd();
+        const events = loadFlow(cwd);
+        const rows = aggregateByCommand(events);
+        const top = rows
+            .sort((a, b) => b.savedTokens - a.savedTokens)
+            .slice(0, limit);
+        process.stderr.write(table(top, `unerr gain — top ${limit} by tokens saved`, "gain"));
+    });
+}
+export function registerDiscoverCommand(program) {
+    program
+        .command("discover")
+        .description("Surface commands that bypass effective compression — untapped savings")
+        .option("-n, --limit <n>", "Number of rows to show", "20")
+        .option("-t, --threshold <pct>", "Ratio floor (0..100) below which a command is flagged", "30")
+        .option("-m, --min-raw <bytes>", "Ignore commands with raw output below this", "2000")
+        .action((opts) => {
+        const limit = Number.parseInt(opts.limit, 10) || 20;
+        const threshold = (Number.parseFloat(opts.threshold) || 30) / 100;
+        const minRaw = Number.parseInt(opts.minRaw, 10) || 2000;
+        const cwd = process.cwd();
+        const events = loadFlow(cwd);
+        const rows = aggregateByCommand(events);
+        const leaking = rows
+            .filter((r) => r.ratio < threshold &&
+            r.rawTokens / Math.max(1, r.invocations) >= minRaw)
+            .sort((a, b) => b.rawTokens - a.rawTokens)
+            .slice(0, limit);
+        process.stderr.write(table(leaking, `unerr discover — ${leaking.length} commands below ${Math.round(threshold * 100)}% compression`, "discover"));
+    });
+}

package/dist/commands/hook.js

@@ -0,0 +1,88 @@
+/**
+ * `unerr hook <pre-*|post-*|prompt-submit>` — Hook handlers for all event types.
+ *
+ * Each subcommand reads stdin JSON and writes stdout JSON.
+ * - pre-bash: rewrites Bash commands to route through `unerr exec` (transparent)
+ * - pre-read/pre-grep/pre-glob: inject systemMessage nudges suggesting unerr tools
+ * - pre-write/pre-edit: blast radius + convention validation before code modifications
+ * - post-read/post-grep/post-glob: enrich tool output with graph navigation suggestions
+ * - post-write/post-edit: convention check + caller verification after modifications
+ * - prompt-submit: inject unerr tool reminder on each user prompt (UserPromptSubmit)
+ */
+import { readFileSync } from "node:fs";
+import { runPostEditHook, runPostGlobHook, runPostGrepHook, runPostReadHook, runPostWriteHook, runPreEditHook, runPreGlobHook, runPreGrepHook, runPreReadHook, runPreWriteHook, } from "../hooks/navigation-hooks.js";
+import { runUserPromptSubmitHook } from "../hooks/prompt-hooks.js";
+import { runPreBashHook } from "../hooks/shell-hooks.js";
+/**
+ * Safe hook action wrapper. Reads stdin, runs the handler, writes stdout.
+ * On ANY failure (EAGAIN on stdin, handler throw, etc.) outputs valid JSON "{}"
+ * so Claude Code never sees a crash/invalid output and reports "hook error".
+ */
+function safeHookAction(handler) {
+    return () => {
+        try {
+            const stdin = readFileSync(0, "utf-8");
+            process.stdout.write(handler(stdin));
+        }
+        catch (e) {
+            process.stderr.write(`[unerr] hook error: ${e}\n`);
+            process.stdout.write("{}");
+        }
+    };
+}
+export function registerHookCommand(program) {
+    const hook = program
+        .command("hook")
+        .description("IDE hook handlers (stdin/stdout JSON)");
+    // ── PreToolUse hooks ──────────────────────────────────────────
+    hook
+        .command("pre-bash")
+        .description("Rewrite Bash tool input to pipe through unerr exec")
+        .action(safeHookAction(runPreBashHook));
+    hook
+        .command("pre-read")
+        .description("Nudge agent to use file_outline/file_read instead of Read")
+        .action(safeHookAction(runPreReadHook));
+    hook
+        .command("pre-grep")
+        .description("Nudge agent to use search_code/get_callers instead of Grep")
+        .action(safeHookAction(runPreGrepHook));
+    hook
+        .command("pre-glob")
+        .description("Nudge agent to use search_code instead of Glob")
+        .action(safeHookAction(runPreGlobHook));
+    hook
+        .command("pre-write")
+        .description("Blast radius + convention check before Write")
+        .action(safeHookAction(runPreWriteHook));
+    hook
+        .command("pre-edit")
+        .description("Blast radius + convention check before Edit")
+        .action(safeHookAction(runPreEditHook));
+    // ── PostToolUse hooks ─────────────────────────────────────────
+    hook
+        .command("post-read")
+        .description("Enrich Read output with graph navigation suggestions")
+        .action(safeHookAction(runPostReadHook));
+    hook
+        .command("post-grep")
+        .description("Enrich Grep output with graph navigation suggestions")
+        .action(safeHookAction(runPostGrepHook));
+    hook
+        .command("post-glob")
+        .description("Enrich Glob output with graph navigation suggestions")
+        .action(safeHookAction(runPostGlobHook));
+    hook
+        .command("post-write")
+        .description("Post-write convention check + caller verification reminder")
+        .action(safeHookAction(runPostWriteHook));
+    hook
+        .command("post-edit")
+        .description("Post-edit convention check + caller verification reminder")
+        .action(safeHookAction(runPostEditHook));
+    // ── UserPromptSubmit hook ───────────────────────────────────────
+    hook
+        .command("prompt-submit")
+        .description("Inject unerr tool reminder on each user prompt")
+        .action(safeHookAction(runUserPromptSubmitHook));
+}

package/dist/commands/index.js

@@ -0,0 +1,88 @@
+/**
+ * unerr index — Trigger local graph indexing.
+ *
+ * Scans the current project with tree-sitter AST analysis, extracts
+ * entities + edges, populates the persistent CozoDB at .unerr/graph.db,
+ * and runs community detection. Data persists across restarts.
+ */
+import { createHash } from "node:crypto";
+import { getRemoteUrl, isGitRepo } from "../utils/git.js";
+// ── Helpers ─────────────────────────────────────────────────
+async function isInsideGitRepo() {
+    return isGitRepo(process.cwd());
+}
+async function deriveLocalRepoId(projectRoot) {
+    let repoIdentifier = projectRoot;
+    const remoteUrl = await getRemoteUrl(projectRoot);
+    if (remoteUrl)
+        repoIdentifier = remoteUrl;
+    return `local-${createHash("sha256").update(repoIdentifier).digest("hex").slice(0, 12)}`;
+}
+// ── Command ─────────────────────────────────────────────────
+export function registerIndexCommand(program) {
+    program
+        .command("index")
+        .description("Build local code intelligence graph (replaces 'pull' in Local Mode)")
+        .option("--force", "Re-index even if local snapshot is fresh")
+        .option("--verbose", "Show per-file indexing progress")
+        .option("--json", "Output results as JSON (to stdout)")
+        .action(async (opts) => {
+        if (!(await isInsideGitRepo())) {
+            process.stderr.write("[unerr] Error: not inside a git repository.\n");
+            process.exit(1);
+        }
+        const projectRoot = process.cwd();
+        // Check freshness unless --force
+        if (!opts.force) {
+            const { shouldReindex } = await import("../intelligence/local-snapshot.js");
+            if (!shouldReindex(projectRoot)) {
+                if (opts.json) {
+                    process.stdout.write(JSON.stringify({ status: "fresh", reindexed: false }));
+                    process.stdout.write("\n");
+                }
+                else {
+                    process.stderr.write("[unerr] Local snapshot is fresh. Use --force to re-index.\n");
+                }
+                process.exit(0);
+            }
+        }
+        // Open persistent CozoDB (SQLite-backed at .unerr/graph.db)
+        const { openPersistentDb } = await import("../intelligence/persistent-db.js");
+        const { CozoGraphStore } = await import("../intelligence/local-graph.js");
+        const { db } = await openPersistentDb(projectRoot);
+        const graphStore = await CozoGraphStore.create(db);
+        const repoId = await deriveLocalRepoId(projectRoot);
+        // Run indexing
+        if (!opts.json) {
+            process.stderr.write("[unerr] Indexing local project...\n");
+        }
+        const { indexLocalProject } = await import("../intelligence/local-indexer.js");
+        const result = await indexLocalProject(projectRoot, graphStore, repoId, {
+            verbose: opts.verbose,
+        });
+        // Output results
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                status: "indexed",
+                reindexed: true,
+                fileCount: result.fileCount,
+                entityCount: result.entityCount,
+                edgeCount: result.edgeCount,
+                communityCount: result.communityCount,
+                patternCount: result.patternCount,
+                ruleCount: result.ruleCount,
+                elapsedMs: result.elapsedMs,
+            }));
+            process.stdout.write("\n");
+        }
+        else {
+            process.stderr.write(`\n[unerr] Indexed ${result.fileCount} files\n`);
+            process.stderr.write(`  Entities:    ${result.entityCount}\n`);
+            process.stderr.write(`  Edges:       ${result.edgeCount}\n`);
+            process.stderr.write(`  Communities: ${result.communityCount}\n`);
+            process.stderr.write(`  Conventions: ${result.patternCount} patterns, ${result.ruleCount} rules\n`);
+            process.stderr.write(`  Time:        ${result.elapsedMs}ms\n`);
+            process.stderr.write("\n[unerr] Graph persisted to .unerr/graph.db — available instantly on next boot.\n");
+        }
+    });
+}

package/dist/commands/init.js

@@ -0,0 +1,74 @@
+/**
+ * `unerr init` — auto-detect AI tools, install hooks, write MCP config.
+ *
+ * S6.2+S6.3: Combines tool detection, hook installation, and MCP config
+ * writing into a single command. Idempotent — safe to run multiple times.
+ *
+ * All output to stderr (stdout is MCP-sacred).
+ */
+import { installClaudeHook } from "../config/hook-installer.js";
+import { writeMcpConfig } from "../config/mcp-config-writer.js";
+import { detectTools, formatDetectedTools } from "../config/tool-detector.js";
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Auto-detect AI tools and configure unerr integration")
+        .action(async () => {
+        const cwd = process.cwd();
+        const result = runInit(cwd);
+        if (result.detectedTools.length === 0) {
+            process.stderr.write("[unerr] No AI tools detected. Create a .cursor/, .claude/, or .vscode/ directory first.\n");
+            process.stderr.write("[unerr] Or run 'unerr' directly — it will start the MCP proxy on stdio.\n");
+            return;
+        }
+        process.stderr.write(`[unerr] Detected: ${result.detectedTools.join(", ")}\n`);
+        for (const h of result.hooksInstalled) {
+            process.stderr.write(`[unerr] ✓ ${h}\n`);
+        }
+        for (const c of result.configsWritten) {
+            process.stderr.write(`[unerr] ✓ ${c}\n`);
+        }
+        for (const s of result.skipped) {
+            process.stderr.write(`[unerr] · ${s}\n`);
+        }
+        process.stderr.write("[unerr] Init complete. Run 'unerr' to start.\n");
+    });
+}
+/**
+ * Core init logic — testable without Commander.
+ */
+export function runInit(cwd) {
+    const tools = detectTools(cwd);
+    const result = {
+        detectedTools: [],
+        hooksInstalled: [],
+        configsWritten: [],
+        skipped: [],
+    };
+    for (const tool of tools) {
+        const name = formatDetectedTools([tool]);
+        result.detectedTools.push(name);
+        // Install hook for Claude Code
+        if (tool.ide === "claude-code") {
+            const hookResult = installClaudeHook(cwd);
+            if (hookResult.action === "installed") {
+                result.hooksInstalled.push(`Installed Claude Code hook at ${hookResult.path}`);
+            }
+            else if (hookResult.action === "already_exists") {
+                result.skipped.push("Claude Code hook already installed");
+            }
+        }
+        // Write MCP config for all detected tools
+        const configResult = writeMcpConfig(cwd, tool.ide);
+        if (configResult.action === "created") {
+            result.configsWritten.push(`Created MCP config at ${configResult.path}`);
+        }
+        else if (configResult.action === "updated") {
+            result.configsWritten.push(`Added unerr to existing config at ${configResult.path}`);
+        }
+        else {
+            result.skipped.push(`MCP config for ${name} already configured`);
+        }
+    }
+    return result;
+}