codehere 0.3.0 → 0.5.0-alpha

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024
+Copyright (c) 2025
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,14 @@
 # codehere
 
-> Enterprise-grade AI coding assistant with local embeddings and semantic search
+> **Status:** v0.5 Solo Dev Alpha – CLI agent focused on solo developer workflows and safe editing with review gates.
+
+> A governed, measurable AI coding OS that plans, edits, validates, and measures its own reliability. Every change is traceable, reviewable, and scored – so you can trust it on real code.
+
+Codehere is a multi-agent coding system designed for **solo developers working on their own repositories**. Unlike simple AI assistants, Codehere orchestrates specialized agents (Planning, Execution, Validation) to handle complex tasks while maintaining full transparency and control through review gates and trust metrics.
+
+**v0.5 Scope**: Single developer, single repository, local workflows. Not yet validated for team/enterprise use.
+
+**📖 [Documentation →](docs/GETTING_STARTED.md)**
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)
@@ -22,9 +30,13 @@ npm install -g .
 codehere --version
 ```
 
-**Option 2: Install from npm (after publishing)**
+**Option 2: Install from npm**
 ```bash
+# Stable version
 npm install -g codehere
+
+# Latest alpha (includes OpenRouter & enhanced local LLM)
+npm install -g codehere@alpha
 ```
 
 Once installed globally, you can use `codehere` from any directory in your terminal.
@@ -50,19 +62,69 @@ codehere index
 codehere "How does authentication work?"
 ```
 
+### Switching Providers
+
+Codehere supports multiple AI providers. By default, it uses **Cohere** (no configuration needed).
+
+**Quick Options:**
+
+**Default (Cohere):**
+```bash
+export COHERE_API_KEY=your-key
+codehere status
+```
+
+**OpenAI:**
+```bash
+export CODEHERE_AI_PROVIDER=openai
+export CODEHERE_OPENAI_API_KEY=sk-...
+codehere status
+```
+
+**OpenRouter (400+ Models):**
+```bash
+export CODEHERE_AI_PROVIDER=openrouter
+export OPENROUTER_API_KEY=sk-or-v1-...
+codehere status
+```
+
+**Local LLM (Ollama, LM Studio):**
+```bash
+export CODEHERE_AI_PROVIDER=local
+export CODEHERE_LOCAL_BASE_URL=http://localhost:11434
+codehere status
+```
+
+**Fake Mode (Testing/Demo):**
+```bash
+export CODEHERE_FAKE_AI=1
+codehere status  # No API calls, deterministic outputs
+```
+
+**Per-Operation Routing:**
+
+Create `.codehere/providers.json` to route different operations to different providers. See [docs/PROVIDERS_QUICKSTART.md](docs/PROVIDERS_QUICKSTART.md) for complete setup guide.
+
+**📖 [Complete Provider Guide →](docs/PROVIDERS_QUICKSTART.md)**
+
 **Using Codehere:**
 
 ```bash
 # Natural language queries (unified command)
 codehere "explain this function"
-codehere "add error handling to src/utils.ts"
-codehere "refactor user service to use dependency injection"
+codehere "add error handling to src/utils.ts" --review
+codehere "refactor user service to use dependency injection" --review
 
 # Or use explicit commands
 codehere ask "How does authentication work?"
 codehere explain src/utils.ts
 codehere plan "implement user authentication system"
-codehere orchestrate "add comprehensive logging"
+codehere orchestrate "add comprehensive logging" --review
+
+# Validation Mode: Review before applying changes
+codehere fix src/utils.ts "Add error handling" --review
+codehere orchestrate "Add authentication" --review
+codehere plan "Refactor to DI" --execute --review
 
 # Manage configuration
 codehere config                    # Show current configuration
@@ -74,57 +136,229 @@ codehere --help
 codehere help <command>
 ```
 
+> **💡 Tip**: Use `--review` on destructive operations (edit, orchestrate, plan --execute) to see summaries and approve changes before they're applied. This builds trust and prevents mistakes.
+
+### 🔍 Validation Mode & Trust Scores
+
+Validation Mode makes every agent operation traceable, reviewable, and measurable. Use `--review` to pause before applying changes, review structured summaries, and approve or reject. Every operation generates feedback that feeds into trust scores.
+
+**How it works:**
+- Run commands with `--review` to enable feedback capture
+- Review summaries show files changed, validation checks, and risk assessment
+- Feedback is stored locally in `data/feedback/agent-feedback.jsonl`
+- Trust scores are computed per agent: `(approved_success_runs / total_runs) × 100`
+
+**Example:**
+```bash
+# Enable review & feedback capture
+CODEHERE_AUTO_APPROVE=true codehere fix src/file.ts "add input validation" --review
+
+# View trust scores
+npm run analyze:feedback
+codehere status
+```
+
+**Optional:** Configure minimum trust thresholds via `config/trust-config.json` to highlight agents that need more validation (warnings only, non-blocking).
+
+**For CI/dashboards:** Export trust and feedback stats as JSON:
+- `npm run analyze:feedback -- --json`
+- `codehere status --json`
+
+**For CI gates:** Enforce minimum trust scores:
+- `npm run check:trust` - Fails if any agent is below its configured threshold
+
+**📖 [Complete Guide →](docs/VALIDATION_MODE.md)**
+
+### 💬 Feedback Collection
+
+Codehere collects feedback after operations to improve responses. In interactive mode, you'll see a prompt asking for feedback. In non-interactive mode (scripts, CI), you can provide feedback via environment variables:
+
+```bash
+# Positive feedback (thumbs up)
+CODEHERE_FEEDBACK=y codehere ask "What is main?"
+
+# Negative feedback (thumbs down)
+CODEHERE_FEEDBACK=n codehere ask "What is main?"
+
+# Request refinement with message
+CODEHERE_FEEDBACK=r CODEHERE_FEEDBACK_MESSAGE="Add more examples" codehere ask "What is main?"
+
+# Alternative values
+CODEHERE_FEEDBACK=positive codehere ask "What is main?"
+CODEHERE_FEEDBACK=negative codehere ask "What is main?"
+CODEHERE_FEEDBACK=yes codehere ask "What is main?"
+CODEHERE_FEEDBACK=no codehere ask "What is main?"
+```
+
+**Environment Variables:**
+- `CODEHERE_FEEDBACK`: `y`/`yes`/`positive` (thumbs up), `n`/`no`/`negative` (thumbs down), `r`/`refine`/`refinement` (request refinement)
+- `CODEHERE_FEEDBACK_MESSAGE`: Optional message for refinement requests
+
 ## ✨ Features
 
-### 🧠 Semantic Code Search
-- Builds local embedding index using Cohere's embedding API
-- Uses cosine similarity to find relevant code chunks
-- Enhanced context with file relationships and dependencies
+### 🎯 Why Codehere vs Other Coding Agents?
+
+- **Safe Editing with Review Gates**: Unlike agents that apply changes immediately, Codehere uses `--review` to pause, show summaries, and request approval before modifying files. **This is the strongest differentiator in v0.5.**
+- **Automatic Backup & Rollback**: Every edit creates a backup. On failure, automatic rollback ensures your repo stays consistent.
+- **Trust Scores & Analytics**: Every agent run is scored. Run `npm run analyze:feedback` to see which agents are most reliable in your workflow
+- **Full Traceability**: Every operation generates a structured TraceSummary showing files changed, reasoning steps, validation checks, and risk assessment
+- **Privacy-First Feedback**: All feedback stored locally in JSONL. No telemetry. Opt-out available. Your data stays yours
+
+## What's Stable (Ready to Use)
+
+These capabilities have been validated through comprehensive testing (Pack A, Real Repo, Pack B):
+
+### 🧠 Autonomous Planning
+- **Command**: `codehere plan "Implement X" --json`
+- **Status**: ✅ Stable
+- **What it does**: Generates structured task plans with hierarchical sub-plans, complexity assessment, and JSON export
+
+### 🔍 Semantic Code Search & Understanding
+- **Commands**: 
+  - `codehere index` (may fail on 30K+ file repos - see limitations)
+  - `codehere ask "How does X work?" --json`
+  - `codehere explain path/to/file.ts`
+- **Status**: ✅ Stable
+- **What it does**: Uses semantic search + AST-aware explanations to answer questions about your codebase
+
+### ✏️ Safe Code Editing with Review Gates
+- **Command**: `codehere fix path/to/file.ts "Change spec" --review`
+- **Status**: ✅ Stable (Key Differentiator)
+- **What it does**: 
+  - Shows review summary before applying changes
+  - Creates automatic backup
+  - Runs verification checks
+  - Automatic rollback on failure
+
+### 💬 Natural Language Interface
+- **Command**: `codehere "What files handle user authentication?"`
+- **Status**: ✅ Stable
+- **What it does**: Intelligently routes queries to planning, search, or editing workflows
+
+### 📦 JSON-First Automation
+- **Commands**: All main commands support `--json` flag
+- **Status**: ✅ Stable
+- **What it does**: Returns stable, machine-readable JSON schemas for scripts and tooling
+
+### 📊 Operation History
+- **Command**: `codehere memory --list --json`
+- **Status**: ✅ Stable (for operation history)
+- **What it does**: Provides structured operation history with JSON export
+- **Note**: This is **operation history**, not full long-term conversational memory
+
+## Beta / Experimental Features
+
+These features exist and work, but behavior quality is not guaranteed:
+
+### 🤖 Multi-Agent Orchestration
+- **Command**: `codehere orchestrate "Add feature X" --json`
+- **Status**: 🟡 Beta
+- **What works**: JSON schema is stable (`plan`, `execution`, `validation`, `provider` always present)
+- **Limitation**: Content quality depends on provider and is experimental. Fields may be `null` for some providers.
+
+### 🔁 ReAct-Style Reasoning
+- **Command**: `codehere react "Solve problem X"`
+- **Status**: 🟡 Experimental
+- **What works**: Executes Thought/Action/Observation loops
+- **Limitation**: Not hardened for all repo sizes. Use with caution on large/complex codebases.
+
+### 🛡️ Validation Mode & Review Gates
+
+- **`--review` Flag**: Pause before applying changes, review structured summaries, approve or reject
+- **TraceSummary Generation**: Every agent run produces a detailed summary (files, steps, checks, metrics, risk)
+- **Composite Summaries**: Multi-agent operations merge all agent summaries into one reviewable report
+- **Risk Assessment**: Automatic risk level calculation (low/medium/high/critical) with clear reasons
+- **Environment Controls**: `CODEHERE_AUTO_APPROVE=true` for CI/CD, `CODEHERE_FEEDBACK_OPT_OUT=true` for privacy
+
+### 📊 Trust & Reliability Metrics
+
+- **Agent Feedback Analytics**: Run `npm run analyze:feedback` to see trust scores, success rates, and operation breakdowns
+- **Trust Score Calculation**: `(approved_success_runs / total_runs) × 100` – measurable agent reliability
+- **Outcome Tracking**: Success, failure, partial_success, cancelled, error – complete visibility
+- **User Action Tracking**: Approved, rejected, modified – understand how users interact with agents
+
+### 🧠 Semantic Code Search & Context
 
-### 🤖 AI-Powered Assistance
+- Builds local embedding index using Cohere's embedding API
+- Enhanced context with file relationships and dependencies (15+ chunks)
 - Context-aware responses using retrieved code
-- Natural language code explanations
-- Intelligent code editing with unified diff generation
-- Enhanced context understanding (15+ chunks)
-
-### 🛡️ Enterprise Safety
-- **Line limit enforcement** - Maximum 50 lines changed per edit
-- **Restricted folders** - Protect critical directories (infra/, billing/)
-- **Single-file edits** - Prevent accidental multi-file changes
-- **Audit logging** - Every operation logged to JSONL
-
-### 🔧 Enterprise Reliability
-- **Automatic error recovery** - Retry with exponential backoff
-- **Circuit breaker** - Protects against API failures
-- **Health monitoring** - System health checks and metrics
-- **24/7 operation ready** - Robust error handling
-
-### 📦 Production Ready
-- Fully tested end-to-end
-- TypeScript for type safety
-- SQLite for local vector storage
-- Comprehensive error handling
+- Natural language code explanations and intelligent editing
+
+### 🔒 Security & Privacy
+
+- **Local-first**: All embeddings and feedback stored locally in SQLite
+- **No code transmission**: Only chunks sent to API for embedding, never full files
+- **Audit trail**: Complete JSONL logging of all operations
+- **Policy enforcement**: Line limits, restricted folders, single-file safety checks
+- **Privacy controls**: Opt-out available, anonymization by default
+
+### 🔧 Reliability Features
+
+- **Automatic error recovery**: Retry with exponential backoff
+- **Circuit breaker**: Protects against API failures
+- **Health monitoring**: System health checks and metrics
+- **Robust error handling**: Graceful degradation and recovery
+
+**Note**: v0.5 targets solo dev workflows. Enterprise-grade reliability guarantees are not yet validated. See limitations section below.
 
 ## 🏗️ Architecture
 
+### Multi-Agent System
+
 ```
-┌─────────────┐
-│   CLI Tool  │
-└──────┬──────┘
-       │
-       ├─→ Index: Scan → Chunk → Embed → Store (SQLite)
-       ├─→ Ask: Query → Embed → Search (15 chunks) → Chat
-       ├─→ Explain: Read → Chat
-       ├─→ Fix: Read → Generate Diff → Policy Check → Apply
-       └─→ Health: System Status → Metrics
+┌─────────────────────────────────────────────────┐
+│              Intelligent Router                  │
+│  (Routes queries to appropriate workflow)        │
+└───────────────┬─────────────────────────────────┘
+                │
+    ┌───────────┼───────────┐
+    │           │           │
+┌───▼───┐  ┌───▼────┐  ┌───▼──────────────┐
+│ Simple│  │ ReAct  │  │ Multi-Agent      │
+│ Work  │  │ Agent  │  │ Orchestrator     │
+└───────┘  └────────┘  └──────┬───────────┘
+                               │
+                    ┌──────────┼──────────┐
+                    │          │          │
+            ┌───────▼──┐  ┌───▼──────┐  ┌▼────────────┐
+            │ Planning │  │Execution │  │ Validation  │
+            │  Agent   │→ │  Agent   │→ │   Agent     │
+            └──────────┘  └──────────┘  └─────────────┘
+                    │          │          │
+                    └──────────┼──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │ Composite Summary   │
+                    │ + Review Gate       │
+                    │ + AgentFeedback     │
+                    └─────────────────────┘
 ```
 
+### Core Components
+
+- **Intelligent Router**: Analyzes query intent, selects optimal workflow
+- **Planning Agent**: Creates hierarchical plans with risk assessment
+- **Execution Agent**: Executes plans, tracks changes, handles rollbacks
+- **Validation Agent**: Compiles, tests, analyzes quality
+- **Multi-Agent Orchestrator**: Coordinates all agents, creates unified run context
+- **Validation Layer**: TraceSummary generation, AgentFeedback recording, review handler
+
+### Data Flow
+
+1. **Query** → Router determines intent
+2. **Planning** → Agent creates plan with complexity tracking
+3. **Execution** → Agent executes with file change tracking
+4. **Validation** → Agent runs checks with pass/fail tracking
+5. **Summary** → Composite summary aggregated from all agents
+6. **Review** → User reviews summary, approves/rejects
+7. **Feedback** → Outcome recorded to local JSONL, trust scores updated
+
 **Tech Stack:**
 - **TypeScript** - Type-safe development
-- **Cohere AI** - Embeddings and chat completion
-- **SQL.js** - In-memory SQLite for vector storage
+- **Cohere AI** - Embeddings, chat completion, reranking
+- **SQLite** - Local vector storage and feedback persistence
 - **Commander.js** - CLI interface
-- **Tiktoken** - Token counting and chunking
+- **Clean Architecture** - Domain, application, infrastructure layers
 
 ## 📊 Performance
 
@@ -133,36 +367,40 @@ codehere help <command>
 - **Chat:** ~2-5 seconds per query
 - **Storage:** ~13KB per chunk (1024-dim embeddings)
 
+## 🎯 Trust & Reliability Dashboard
+
+Codehere measures and reports its own reliability. Every operation with `--review` generates feedback that feeds into trust scores.
+
+### Run Analytics
+
+```bash
+npm run analyze:feedback
+```
+
+Shows trust scores per agent, success rates, and operation breakdowns. See `docs/VALIDATION_MODE_USAGE_GUIDE.md` for details.
+
 ## 🔒 Security & Privacy
 
-- **Local-first:** All embeddings stored locally in SQLite
-- **No code transmission:** Only chunks sent to API for embedding
-- **Audit trail:** Complete JSONL logging of all operations
-- **Policy enforcement:** Multiple safety checks before applying changes
+- **Local-first storage:** All embeddings and feedback stored locally in SQLite – nothing leaves your machine
+- **No code transmission:** Only chunks sent to API for embedding, never full files
+- **Privacy-first feedback:** All AgentFeedback stored locally in `data/feedback/agent-feedback.jsonl`. No telemetry. Opt out with `CODEHERE_FEEDBACK_OPT_OUT=true`
+- **Audit trail:** Complete JSONL logging of all operations with full traceability
+- **Policy enforcement:** Line limits, restricted folders, single-file safety checks
+- **Review gates:** Explicit approval required before applying destructive changes
 
-## 📈 Use Cases
+## 📈 Use Cases (v0.5 Solo Dev Alpha)
 
-Codehere helps developers, teams, and enterprises in many ways:
+Codehere helps **solo developers** working on their own repositories:
 
-### For Developers
+### For Solo Developers
 - **Onboard faster**: Understand new codebases in hours, not days
 - **Debug smarter**: AI-powered reasoning to find root causes
-- **Refactor safely**: Automatic verification and rollback
+- **Refactor safely**: Automatic verification and rollback with review gates
 - **Learn continuously**: Get explanations of any code
+- **Plan work**: Generate structured task plans with JSON export
+- **Safe editing**: Review gates, backup, and automatic rollback on failure
 
-### For Teams
-- **Better documentation**: Auto-generate accurate, up-to-date docs
-- **Faster code reviews**: AI-assisted review catches issues early
-- **Consistent patterns**: Learn and apply team conventions automatically
-- **Knowledge sharing**: Preserve and share patterns across projects
-
-### For Enterprises
-- **Secure by default**: Built-in security scanning and audit trails
-- **Privacy-first**: Local processing, code never leaves your machine
-- **Productivity metrics**: Track ROI and developer productivity
-- **Organizational memory**: Build knowledge that survives team changes
-
-**See [docs/USE_CASES.md](../docs/USE_CASES.md) for detailed scenarios and examples.**
+**Note**: v0.5 is not yet validated for team workflows, enterprise use, or multi-repo orchestration.
 
 ## 🧪 Testing
 
@@ -224,6 +462,32 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
+## Known Limitations (v0.5 Solo Dev Alpha)
+
+### 🧱 Large Repos Indexing
+- **Issue**: Full `codehere index` can hit heap/memory limits on very large codebases (~30–40k+ files)
+- **Impact**: You may not be able to fully index very large repositories
+- **Workaround**: Semantic search still works with partial/cached results. You don't need full indexing for most operations.
+
+### 🧠 Memory Scope
+- **Issue**: `codehere memory --list --json` provides **operation history**, not full long-term conversational memory
+- **Impact**: No strong guarantees around cross-session, long-horizon memory semantics
+- **What you get**: Structured operation history with JSON export for tooling
+- **What you don't get**: "Remembers everything you say forever" - that's not v0.5
+
+### 👥 Not Enterprise-Ready
+- **Issue**: v0.5 targets **solo devs on single repos**
+- **Impact**: No guarantees (yet) for:
+  - Team workflows
+  - Multi-repo orchestration
+  - Governance/audit requirements
+  - Production CI/CD reliability guarantees
+
+### 🤖 Orchestration Behavior
+- **Issue**: Multi-agent orchestration JSON schema is stable, but content quality depends on provider
+- **Impact**: `plan`, `execution`, `validation` fields may be `null` for some providers
+- **Workaround**: Check JSON structure - if fields are `null`, orchestration didn't produce rich content (expected for fake provider, may vary for real providers)
+
 ---
 
-**Built with ❤️ for developers who want AI assistance without sacrificing control.**
+**Built with ❤️ for solo developers who want AI assistance without sacrificing control.**

package/dist/application/agents/documentation-agent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Application Agent: Documentation Agent
+ * Generates and maintains documentation (README, API docs)
+ */
+import type { IAIService } from '../../domain/interfaces/ai-service.interface.js';
+import type { MemoryStreamService } from '../../infrastructure/storage/memory-stream-service.js';
+import type { IAgent } from '../../domain/interfaces/agent.interface.js';
+import type { DocumentationRequest, DocumentationResponse } from '../../domain/entities/documentation.js';
+export declare class DocumentationAgent implements IAgent<DocumentationRequest, DocumentationResponse> {
+    private aiService;
+    private memoryStream?;
+    private cwd;
+    name: string;
+    type: "non-engineering";
+    constructor(aiService: IAIService, memoryStream?: MemoryStreamService | undefined, cwd?: string);
+    execute(request: DocumentationRequest): Promise<DocumentationResponse>;
+    private generateREADME;
+    private generateAPIDocs;
+    private analyzeFolderStructure;
+    private findSourceFiles;
+    private buildReadmePrompt;
+    private buildAPIDocsContent;
+}
+//# sourceMappingURL=documentation-agent.d.ts.map

package/dist/application/agents/documentation-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation-agent.d.ts","sourceRoot":"","sources":["../../../src/application/agents/documentation-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iDAAiD,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAC;AACjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAC;AACzE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,wCAAwC,CAAC;AAOhD,qBAAa,kBAAmB,YAAW,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;IAK1F,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,YAAY,CAAC;IACrB,OAAO,CAAC,GAAG;IANb,IAAI,SAAyB;IAC7B,IAAI,EAAG,iBAAiB,CAAU;gBAGxB,SAAS,EAAE,UAAU,EACrB,YAAY,CAAC,EAAE,mBAAmB,YAAA,EAClC,GAAG,GAAE,MAAsB;IAG/B,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;YAuD9D,cAAc;YA2Gd,eAAe;IAgG7B,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,eAAe;IA8BvB,OAAO,CAAC,iBAAiB;YA2BX,mBAAmB;CA6DlC"}