@unerr-ai/unerr 0.0.0-beta.0

package/LICENSE

@@ -0,0 +1,47 @@
+Elastic License 2.0 (ELv2)
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the software the licensor makes available under these terms, including any portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,301 @@
+<p align="center">
+  <img src="public/icon-wordmark.svg" alt="unerr" width="320" />
+</p>
+
+<p align="center">
+  <strong>Lands your AI agent at the right code in fewer turns, tokens, & breakages.</strong>
+</p>
+
+<p align="center">
+  Local code intelligence that gives your AI agent a graph of your entire codebase.<br/>
+  It stops looping, stops re-reading, stops breaking things it can't see.
+</p>
+
+<p align="center">
+  <a href="#get-started"><img src="https://img.shields.io/badge/install-npx_@unerr/unerr-8B5CF6?style=flat-square&logo=npm" alt="Install" /></a>
+  <img src="https://img.shields.io/badge/runtime-Node.js_≥20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/protocol-MCP-7C3AED?style=flat-square" alt="MCP" />
+  <img src="https://img.shields.io/badge/tests-1455_passing-34D399?style=flat-square" alt="Tests" />
+  <img src="https://img.shields.io/badge/license-ELv2-A1A1AA?style=flat-square" alt="License" />
+</p>
+
+<p align="center">
+  <code>npx @unerr/unerr</code>
+</p>
+
+---
+
+## Your agent loops because it's blind
+
+You've seen it. You ask Claude or Cursor to refactor a function. It reads 30 files to find the call graph. It misses 14 downstream callers. It re-discovers conventions you told it yesterday. It tries a broken approach, fails, tries again — burning tokens while you watch.
+
+**The agent isn't stupid. It's blind.**
+
+- It can't see that `processPayment()` has 40 callers across 3 services
+- It doesn't know your team uses `fetch` prefixes, not `get`
+- It forgot everything from yesterday's session
+
+unerr gives it a graph. Every caller, every dependency, every convention. The agent lands at the right code instead of searching for it.
+
+---
+
+## What happens when you run it
+
+```bash
+npx @unerr/unerr
+```
+
+**5 seconds later**, your agent has:
+
+| Before unerr | After unerr |
+|:---|:---|
+| Reads 30 files to understand a call graph | Queries the graph in 5ms |
+| Misses downstream callers, breaks things | Sees full blast radius before editing |
+| Re-derives conventions every session | Knows your patterns, enforces them |
+| Session degrades at 70% context fill | Stays sharp — 93% shell compression, context lasts 3-5x longer |
+| Starts from zero tomorrow | Resumes where it left off |
+
+```
+unerr session (12 min)
+  Tool calls    47 (all local, <5ms each)
+  Tokens saved  ~120K (93% shell compression + graph-targeted reads)
+  Turns saved   ~8 (approaches that would have failed, prevented)
+```
+
+---
+
+## Get Started
+
+```bash
+npx @unerr/unerr
+```
+
+That's it. Auto-detects your IDE, indexes your codebase (~30s), starts serving intelligence via MCP.
+
+### Add to more agents
+
+```bash
+unerr install claude-code   # .mcp.json + .claude/skills/ + PreToolUse hook
+unerr install cursor        # .cursor/mcp.json + .cursor/rules/
+unerr install vscode        # .vscode/mcp.json + .github/copilot/
+unerr install windsurf      # .windsurf/mcp.json + .windsurf/rules/
+unerr install zed           # .zed/mcp.json
+unerr install codex         # .codex/mcp.json
+unerr install gemini-cli    # .gemini/settings.json
+unerr install kiro          # .kiro/mcp.json
+unerr install aider         # .aider/mcp.json
+unerr install continue      # .continue/config.json
+```
+
+Works with any MCP-compatible agent. 15 supported out of the box.
+
+<details>
+<summary>Manual MCP config (any agent)</summary>
+
+```json
+{
+  "mcpServers": {
+    "unerr": {
+      "command": "npx",
+      "args": ["@unerr/unerr", "--mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+## What you get
+
+### Instant (first session)
+
+- **Graph navigation** — `get_callers` · `get_callees` · `get_imports` · `search_code` in <5ms. The agent stops reading 30 files to find one function.
+- **Blast radius** — before editing, the agent sees every downstream dependency. No more confident wrong changes.
+- **Smart file reads** — `file_read({entity: "functionName"})` returns just that function + context. Not 2000 lines.
+- **Shell compression** — 10 strategies, 645 command classifiers. Diffs, errors, logs, test results, key-value, tabular — each compressed differently. **93% average compression** across real-world benchmarks (2MB → 138KB).
+- **Full output recovery** — when compression is significant, raw output is saved to disk with a recovery path. The agent can always access the original.
+- **Convention awareness** — auto-detected naming, structure, and import patterns injected into agent context.
+
+### Compounding (session 2+)
+
+- **Session persistence** — the agent tomorrow knows what the agent learned today. No more starting from zero.
+- **Convention enforcement** — patterns detected in session 1 are enforced in session 5. No manual `.cursorrules` maintenance.
+- **Anti-pattern rules** — when you revert bad code, unerr learns. That mistake never happens again.
+- **Durability scoring** — code that keeps getting rewritten gets flagged before the agent touches it.
+- **Loop prevention** — circuit breaker fires after repeated failed attempts.
+
+### Shell compression benchmarks
+
+Every shell command the agent runs is classified (645 command patterns + content heuristics) and compressed with the best-fit strategy:
+
+| Strategy | What it compresses | Avg compression |
+|----------|-------------------|:-:|
+| **diff** | `git diff`, patch output | **99%** |
+| **structured** | JSON APIs, `docker inspect` | **97%** |
+| **progress** | `npm install`, `pip install` | **95%** |
+| **log_text** | Build logs, server logs, `make`, `cargo build` | **89%** |
+| **test_results** | `vitest`, `pytest`, `cargo test`, `playwright` | **80%** |
+| **tabular** | `ps aux`, `docker ps`, `kubectl get` | **77%** |
+| **error_diagnostic** | `tsc`, `eslint`, `rustc`, `shellcheck` | **72%** |
+| **key_value** | `env`, `kubectl describe`, `systemctl status` | **48%** |
+| **tree_paths** | `find`, `tree`, `ls -R` | **42%** |
+| **omni** | Fallback for unrecognized output | adaptive |
+
+**Overall: 93% compression** (2MB → 138KB across 40 real-world test cases). Low-confidence classifications use smart fallback — tries both the best-guess strategy and generic compression, picks whichever saves more tokens.
+
+### Language support
+
+| Language | Entity Extraction | Edge Extraction | Tree-sitter AST | SCIP |
+|----------|:-:|:-:|:-:|:-:|
+| TypeScript | ✓ | ✓ | ✓ | ✓ |
+| JavaScript | ✓ | ✓ | ✓ | ✓ |
+| Python | ✓ | ✓ | ✓ | ✓ |
+| Go | ✓ | ✓ | ✓ | ✓ |
+| Java | ✓ | ✓ | ✓ | ✓ |
+| Rust | ✓ | ✓ | ✓ | ✓ |
+| C# | ✓ | ✓ | ✓ | — |
+| C / C++ | ✓ | ✓ | ✓ | — |
+| Ruby | ✓ | ✓ | ✓ | — |
+| PHP | ✓ | ✓ | ✓ | — |
+| Kotlin | ✓ | ✓ | ✓ | — |
+| Swift | ✓ | ✓ | ✓ | — |
+
+All 13 languages get full regex-based entity extraction (functions, classes, interfaces, methods with `parent_class` detection) and tree-sitter AST extraction when WASM grammars are available. SCIP integration provides compiler-verified call graphs for TypeScript, Python, Go, Java, and Rust.
+
+---
+
+## How it works
+
+```
+AI Agent (Claude Code / Cursor / VS Code / Windsurf / any MCP client)
+    │
+    ├── MCP tools ──→ unerr ──→ CozoDB graph (in-process, <5ms)
+    │                   │
+    │                   ├── Convention engine (auto-detects patterns)
+    │                   ├── Session ledger (cross-session memory)
+    │                   ├── Token budgeter (prevents context rot)
+    │                   └── Compression engine (10 strategies, 645 classifiers)
+    │
+    └── CLI hooks ──→ Output compression ──→ Graph-aware prioritization
+```
+
+One process. Fully local. No API keys. No network calls. No cloud.
+
+---
+
+## MCP Tools (17)
+
+| Tool | What the agent gets |
+|------|-----|
+| `get_function` | Function body + callers + blast radius + applicable conventions |
+| `get_class` | Class with inheritance, methods, and dependents |
+| `get_file` | All entities, imports, exports, risk summary |
+| `get_callers` | Every caller with file location and risk level |
+| `get_callees` | All downstream dependencies |
+| `get_imports` | Import/dependency graph |
+| `search_code` | Graph-ranked full-text search |
+| `get_rules` | Active rules for a path |
+| `check_rules` | Evaluate rules — returns violations |
+| `get_conventions` | Naming, structure, import conventions |
+| `get_god_nodes` | High fan-in chokepoints |
+| `get_surprising_connections` | Unexpected cross-module dependencies |
+| `file_read` | Entity-targeted reads (not full file dumps) |
+| `file_outline` | File structure without content |
+
+Every response includes `_meta` (latency, risk level, drift status) and contextual warnings.
+
+---
+
+<details>
+<summary><strong>Commands</strong></summary>
+
+```bash
+unerr                 # Start MCP proxy (auto-started by IDE via MCP config)
+unerr status          # Graph stats, health grade, active rules
+unerr stats           # Session and weekly efficiency metrics
+unerr install <agent> # Add unerr to a specific AI coding agent
+unerr init            # Initialize unerr in a new project
+unerr timeline        # What happened across sessions
+unerr rewind          # Restore to a previous working state
+unerr learn           # Teach unerr a convention or correction
+unerr debug           # Diagnostic dump
+```
+
+</details>
+
+<details>
+<summary><strong>Architecture</strong></summary>
+
+```
+src/
+  entrypoints/        CLI entry + state machine
+  intelligence/       CozoDB graph, AST, conventions, rules, search
+  proxy/              MCP server, compression, session stats, token tracking
+  tracking/           Prompt ledger, drift detection, git attribution
+  commands/           CLI commands
+  tools/              MCP tool implementations
+  behaviors/          Agent behavior modules (cascade guard, loop breaker)
+  config/             Agent registry, MCP config writer
+  schemas/            Zod schemas
+  utils/              Logging, detection, git helpers
+```
+
+**Design principles:**
+- Zero network calls — fully local, no API keys
+- stdout is sacred — MCP JSON-RPC only, everything else to stderr
+- <5ms query responses — CozoDB runs in-process (Rust via NAPI)
+- 30s time-to-value — shallow index first, deep enrichment in background
+- Enhancement, not dependency — agent falls back gracefully if unerr is unavailable
+
+**Tech stack:** TypeScript (ESM) · CozoDB (Rust/NAPI) · web-tree-sitter (WASM) · MCP SDK · Ink (React CLI) · tsup · Vitest
+
+</details>
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```bash
+pnpm install
+pnpm run build          # tsup → dist/ (ESM, node20)
+pnpm run dev            # tsx watch
+pnpm run test:run       # full suite (1455 tests)
+pnpm run lint           # biome check
+pnpm run typecheck      # tsc --noEmit
+```
+
+```bash
+pnpm link --global      # make `unerr` available globally
+```
+
+</details>
+
+<details>
+<summary><strong>Contributing</strong></summary>
+
+Contributions welcome. Please open an issue first.
+
+**Before submitting a PR:**
+- Run `pnpm run typecheck && pnpm run lint && pnpm run test:run`
+- All output goes to stderr — never stdout (MCP JSON-RPC channel)
+- All CozoDB interactions are async — always `await`
+- Use `.js` extensions in imports (NodeNext resolution)
+
+See [CLAUDE.md](./CLAUDE.md) for detailed conventions.
+
+</details>
+
+---
+
+## License
+
+[Elastic License 2.0 (ELv2)](./LICENSE) — free to use, modify, and distribute. Cannot be offered as a hosted service.
+
+---
+
+<p align="center">
+  <code>npx @unerr/unerr</code>
+  <br /><br />
+  <sub>One command. No cloud. No account. Free.</sub>
+</p>

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node