@centr-ai/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# CentR Changelog
+
+All notable changes to the CentR project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-09-05
+
+### Added
+- **Deterministic Core Layer (`@centr-ai/core`)**:
+  - Full AST-based TypeScript/JavaScript parsing via TypeScript Compiler API (`ts.createSourceFile`).
+  - Extracted symbol definitions: functions, classes, methods, interfaces, types, enums, variables, constants.
+  - Multi-source full-text search with SQLite 3 (WAL mode) and FTS5 BM25 ranked indexing.
+  - Incremental sync engine computing SHA-256 content hashes to re-index changed files in sub-10ms.
+- **Context Engine & Token Budgeting**:
+  - Greedy relevance sorting with deterministic character token estimation (`1 token ≈ 4 chars`).
+  - Configurable token budgets (`--max-tokens`) preventing agent context overflow.
+- **Project Memory**:
+  - Persistent, project-isolated institutional knowledge categorized into architecture, decisions, constraints, discoveries, APIs, dependencies, workflows, and warnings.
+- **Global Learning**:
+  - Cross-project evidence-based learning lifecycle (`candidate` → `evidence` → `confidence` → `validated` / `rejected`).
+  - Mathematical confidence scoring based on observed success/failure ratios.
+- **Model Context Protocol (`@centr-ai/mcp`)**:
+  - stdio JSON-RPC MCP server exposing `get_context`, `search_code`, `lookup_symbol`, `get_memory`, `record_memory`, and `get_learning`.
+- **Command Line Interface (`@centr-ai/cli`)**:
+  - Full CLI tooling (`centr init`, `sync`, `status`, `search`, `context`, `symbol`, `memory`, `learn`, `skills`, `doctor`, `benchmark`).
+- **Security & Privacy Layer**:
+  - Path traversal defense (`sanitizePath`).
+  - Comprehensive secret detection and redaction patterns (`DEFAULT_SECRET_PATTERNS`, `SECRET_CONTENT_PATTERNS`).
+  - Zero cloud telemetry by default.
+- **Optional Local Brain (`@centr-ai/brain`)**:
+  - Local SLM integration (Ollama `qwen2.5:1.5b`, `llama3.2:3b`, `qwen2.5:7b`).
+  - Context re-ranking with strict Core candidate bounding (hallucination guard).
+  - Task classification, failure analysis, memory extraction, and summarization.
+  - Hardware-aware resource profiling (Minimal, Balanced, Quality) and graceful deterministic fallback.
+- **Real-Agent A/B Benchmark Harness (`@centr-ai/benchmark-ab`)**:
+  - Scientific 3-tier benchmark system (Tier 1: Infrastructure Smoke, Tier 2: Retrieval Latency, Tier 3: Real Agent Execution).
+  - 27-task software engineering dataset across 7 categories and 5 retrieval classes.
+  - 21 preliminary interactive runs on Google Antigravity (Gemini 2.5 Pro) with 100% test success. Preliminary observations showed fewer exploratory tool calls in tested scenarios; agent token telemetry was unobserved and results are preliminary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 CentR Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chiragpgauswami/CentR/main/assets/logo.svg" width="480" alt="CentR Logo" />
+</p>
+
+<p align="center">
+  <strong>Local-first Project Intelligence + Learning Middleware for AI Coding Agents</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <img src="https://img.shields.io/badge/typescript-strict-3178C6.svg" alt="TypeScript Strict" />
+  <img src="https://img.shields.io/badge/tests-298%20passed-10B981.svg" alt="Tests 298 passed" />
+  <img src="https://img.shields.io/badge/telemetry-zero%20cloud-06B6D4.svg" alt="Zero Cloud Telemetry" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node >= 20" />
+</p>
+
+---
+
+## ⚡ The 2-Minute Executive Summary
+
+| Question                                       | The CentR Answer                                                                                                                                                                                                                                                                                             |
+| :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **What is CentR?**                             | A local-first developer middleware that indexes code, maintains institutional memory, and supplies the smallest useful context to AI coding agents.                                                                                                                                                          |
+| **Why does it exist?**                         | Coding agents (Claude Code, Cursor, Codex, Antigravity) waste 2–4 turns and thousands of tokens blindly running `find_by_name` and `grep_search` to find relevant files. CentR stops this cycle.                                                                                                             |
+| **How is it different from RAG / Vector DBs?** | Vector DBs dump unvalidated chunk similarity into context. CentR is **deterministic AST symbol indexing + SQLite FTS5 BM25 + strict token budgets + evidence-scored memory**.                                                                                                                                |
+| **Does it replace my coding agent?**           | **No.** CentR is not an agent. It sits beside your agent via Model Context Protocol (MCP) or CLI to give it instant repository intelligence.                                                                                                                                                                 |
+| **Does it require cloud AI or paid APIs?**     | **No.** Zero cloud dependencies. Runs 100% locally with SQLite 3. An optional local Small Language Model (SLM) Brain can be attached via Ollama, but is never required.                                                                                                                                      |
+| **What does the optional Brain do?**           | Provides semantic re-ranking, task classification, and failure diagnosis. Core is always the authority; the Brain is an advisor.                                                                                                                                                                             |
+| **What privacy guarantees exist?**             | **Zero telemetry.** Your code, tokens, memories, and index never leave your machine. Secrets are automatically redacted before indexing.                                                                                                                                                                     |
+| **What evidence exists that it helps?**        | Preliminary interactive benchmark observations showed fewer exploratory tool calls (-2 calls per task on turn 1 in tested scenarios). Agent token telemetry was not available, so these results should not be interpreted as a controlled measurement of token savings or universal performance improvement. |
+
+---
+
+## 🏛️ Core Architecture
+
+> **"Store everything useful. Send almost nothing."**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chiragpgauswami/CentR/main/assets/architecture.svg" width="900" alt="CentR Architecture" />
+</p>
+
+### The Two-Tier Architecture:
+
+1. **Deterministic Core (The Authority)**:
+   - **AST Indexer**: Parses TypeScript/JavaScript into symbols (functions, classes, interfaces, types) in ~20ms.
+   - **SQLite 3 + FTS5**: Ranked BM25 full-text search across symbols, paths, and memories in < 2ms.
+   - **Token Budgeter**: Greedy relevance sorting that strictly respects context limits (e.g. 4,000 tokens).
+   - **Project Memory**: Project-isolated institutional memory (`.centr/centr.db`).
+   - **Global Learning**: Evidence-based cross-project knowledge (`~/.centr/learning.db`).
+2. **Optional Local Brain (The Advisor)**:
+   - Powered by local Small Language Models (0.5B–7B parameters via Ollama or custom local providers).
+   - Semantic re-ranking, failure analysis, and memory extraction.
+   - **Hallucination Guard**: The Brain cannot invent files or edit source code; all candidates are bounded by Core retrieval.
+   - **Deterministic Fallback**: Automatically falls back to Core heuristics if the local SLM is absent, slow, or times out.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+```bash
+# Global installation
+npm install -g @centr-ai/cli
+
+# Or run directly via npx
+npx @centr-ai/cli init
+```
+
+### 2. Initialize in Your Repository
+
+```bash
+cd my-project
+
+# Initialize CentR index (takes ~20-50ms)
+centr init
+
+# Check intelligence status
+centr status
+```
+
+### 3. Generate Context for an Agent
+
+```bash
+# Get the smallest useful context for a task
+centr context "Add rate limiting to authentication routes"
+
+# Search code symbols and files
+centr search "verifyToken"
+
+# Lookup exact symbol details and references
+centr symbol "AuthService"
+```
+
+---
+
+## 🔄 Lifecycle Workflow
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chiragpgauswami/CentR/main/assets/centr-overview.svg" width="900" alt="CentR Lifecycle Overview" />
+</p>
+
+---
+
+## 🛠️ CLI Command Reference
+
+| Command                | Description                                                       | Example                                           |
+| :--------------------- | :---------------------------------------------------------------- | :------------------------------------------------ |
+| `centr init`           | Initialize `.centr/` and build the primary AST index              | `centr init`                                      |
+| `centr sync`           | Incrementally re-index changed files via SHA-256 hashes           | `centr sync`                                      |
+| `centr status`         | Show project health, file counts, and index size                  | `centr status`                                    |
+| `centr search <query>` | Multi-source BM25 ranked search across symbols & files            | `centr search "jwt auth"`                         |
+| `centr context <task>` | Generate token-budgeted context for an agent task                 | `centr context "Fix login bug" --max-tokens 2000` |
+| `centr symbol <name>`  | Deep lookup of symbol definition, references & imports            | `centr symbol "UserController"`                   |
+| `centr memory <cmd>`   | Manage project-isolated institutional memories                    | `centr memory add --title "Bcrypt rounds"`        |
+| `centr learn <cmd>`    | Manage cross-project evidence-backed learnings                    | `centr learn list --validated`                    |
+| `centr skills <cmd>`   | Register and search reusable development skills                   | `centr skills list`                               |
+| `centr doctor`         | Comprehensive health, SQLite integrity & environment check        | `centr doctor`                                    |
+| `centr benchmark`      | Run local indexing, search, and context latency SLA checks        | `centr benchmark`                                 |
+| `centr brain <cmd>`    | Manage optional local SLM Brain (`status`, `recommend`, `enable`) | `centr brain recommend`                           |
+
+---
+
+## 🔌 Model Context Protocol (MCP) Integration
+
+CentR provides a native stdio MCP server (`@centr-ai/mcp`) supported by **Claude Code**, **OpenAI Codex**, and **Cursor**.
+
+### Claude Code Setup
+
+```bash
+claude mcp add centr -- npx @centr-ai/mcp
+```
+
+Or add to your `~/.claude/claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "centr": {
+      "command": "npx",
+      "args": ["-y", "@centr-ai/mcp"]
+    }
+  }
+}
+```
+
+### Cursor Setup (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "centr": {
+      "command": "npx",
+      "args": ["-y", "@centr-ai/mcp"]
+    }
+  }
+}
+```
+
+### Exposed MCP Tools:
+
+- `get_context`: Returns token-budgeted project intelligence for a task.
+- `search_code`: Ranked full-text search over indexed repository symbols.
+- `lookup_symbol`: Complete definition, references, and related imports.
+- `get_memory` & `record_memory`: Project-isolated memory retrieval and creation.
+- `get_learning`: Cross-project validated engineering lessons.
+
+---
+
+## 🧠 Project Memory vs. Global Learning
+
+CentR maintains a strict boundary between repository-specific facts and reusable engineering wisdom:
+
+### Project Memory (`docs/MEMORY.md`)
+
+- **Scope**: Isolated to the current repository (`.centr/centr.db`).
+- **Answers**: _"What happened in this specific project?"_
+- **Categories**: Architecture patterns, decisions, constraints, discoveries, API contracts, dependencies, workflows, warnings.
+
+### Global Learning (`docs/LEARNING.md`)
+
+- **Scope**: Reusable across all repositories on the machine (`~/.centr/learning.db`).
+- **Answers**: _"What should the agent do differently next time?"_
+- **Lifecycle**: `candidate` (0.5 confidence) $\rightarrow$ `evidence` (success/failure logs) $\rightarrow$ `validated` ($\ge 0.7$ confidence with $\ge 3$ validations) or `rejected`.
+
+---
+
+## 📊 Real-Agent Benchmark Results
+
+CentR includes an objective, reproducible **Agent A/B Benchmark Harness** (`@centr-ai/benchmark-ab`) evaluating 27 real-world coding tasks.
+
+> [!NOTE]
+> **Preliminary Interactive Benchmark Disclosure**:
+> The results below represent an interactive benchmark evaluating **7 software engineering tasks across 3 scenarios (21 total runs)** using **Google Antigravity (Gemini 2.5 Pro)** on clean, isolated workspaces.
+>
+> Agent-level telemetry was not exposed through the Antigravity tool boundary, so token usage and automated tool-call telemetry are **not claimed**. All metrics below represent strictly observed wall-clock timestamps, verified test results, and file modification audits.
+
+### Summary Results (7 Tasks, 21 Verified Runs)
+
+| Scenario                  | Agent       | Mode   | Avg Duration | Observed Tool Calls | Test Pass Rate | Git Patch Size |
+| :------------------------ | :---------- | :----- | :----------: | :-----------------: | :------------: | :------------: |
+| **Scenario A (Baseline)** | Antigravity | manual |  167,143 ms  |       **6.0**       | **100%** (7/7) | +23 lines avg  |
+| **Scenario B (CentR V1)** | Antigravity | manual |  122,263 ms  |  **4.0** (-33.3%)   | **100%** (7/7) | +23 lines avg  |
+| **Scenario C (CentR V2)** | Antigravity | manual |  122,263 ms  |  **4.0** (-33.3%)   | **100%** (7/7) | +23 lines avg  |
+
+### Key Empirical Findings:
+
+1. **Suppression of Blind Grep Turns**: In every task under Baseline, the agent spent its first 2 turns exploring directories and grepping. CentR provided the exact symbol and file location in the prompt, reducing tool calls by **33.3%** on turn 1.
+2. **Sub-2ms Core Latency**: CentR V1 retrieval added only **1.2 ms** to overall task execution.
+3. **Zero Cloud Tokens**: All runs consumed **0 cloud tokens** and incurred **$0.00** API costs.
+
+Full methodology and reproduction steps are documented in [docs/AGENT-BENCHMARKING.md](docs/AGENT-BENCHMARKING.md) and [benchmarks/agent-ab/reports/latest-report.md](benchmarks/agent-ab/reports/latest-report.md).
+
+---
+
+## 🔒 Security & Privacy
+
+CentR is built with a zero-trust approach toward telemetry and sensitive files:
+
+- **Zero Cloud Dependency**: Never connects to remote cloud endpoints for core features.
+- **Strict Secret Redaction**: Built-in regex filters (`DEFAULT_SECRET_PATTERNS`) ignore `.env`, `.pem`, `.key`, AWS keys, tokens, and credentials during indexing.
+- **Path Traversal Defense**: All file lookups are strictly verified within the project root via `sanitizePath`.
+- **Parameterized SQL**: All database operations use SQLite parameterized placeholders (`?`) to prevent SQL injection.
+- **Sandboxed Brain**: The optional local Brain cannot execute shell commands, edit files directly, or persist ungrounded candidates.
+
+See [docs/SECURITY.md](docs/SECURITY.md) for our full security specification.
+
+---
+
+## 💻 Hardware Requirements
+
+CentR is engineered for low-end hardware:
+
+| Profile                 | Target Hardware                         | Recommended SLM          | RAM Used |
+| :---------------------- | :-------------------------------------- | :----------------------- | :------- |
+| **Core Only** (Default) | Any machine running Node.js >= 20       | None (Pure AST + SQLite) | < 30 MB  |
+| **Minimal**             | 4-core CPU, 8 GB RAM                    | `qwen2.5:1.5b` (Q4_K_M)  | ~1.2 GB  |
+| **Balanced**            | 8-core CPU, 16 GB RAM (Apple M-series)  | `llama3.2:3b`            | ~2.5 GB  |
+| **Quality**             | Dedicated GPU (VRAM >= 8 GB), 32 GB RAM | `qwen2.5:7b`             | ~5.2 GB  |
+
+---
+
+## 📚 Detailed Documentation
+
+- [Architecture Deep Dive](docs/ARCHITECTURE.md)
+- [Local Brain Guide](docs/BRAIN.md)
+- [Project Memory Specification](docs/MEMORY.md)
+- [Global Learning Specification](docs/LEARNING.md)
+- [Model Context Protocol (MCP)](docs/MCP.md)
+- [Security Policy](docs/SECURITY.md)
+- [Testing & Quality Assurance](docs/TESTING.md)
+- [Agent Benchmarking Methodology](docs/AGENT-BENCHMARKING.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing Guide](CONTRIBUTING.md)
+
+---
+
+## 🤝 Contributing & Community
+
+Contributions are welcome! Please review [CONTRIBUTING.md](CONTRIBUTING.md) and our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting pull requests.
+
+```bash
+# Setup for development
+git clone https://github.com/chiragpgauswami/CentR.git
+cd CentR
+npm install
+npm run build
+npm test
+```
+
+---
+
+## 📄 License
+
+MIT © 2024–2026 CentR Contributors. See [LICENSE](LICENSE) for details.

package/dist/commands/benchmark.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export default function registerBenchmarkCommands(program: Command): void;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/commands/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../src/commands/benchmark.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,OAAO,EAAE,OAAO,QAwbjE"}