codehere 0.1.1 → 0.2.1

package/README.md

@@ -1,378 +1,117 @@
-# Codehere
+# codehere
 
-> **AI coding assistant that helps you learn and understand your codebase**
+> Know what your AI agent actually did — before your tech lead asks.
 
-**🎓 Learning-First • 🔒 Privacy-Focused • 🔌 Multi-Provider**
+[![npm](https://img.shields.io/npm/v/codehere)](https://www.npmjs.com/package/codehere)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 
-**v0.1.0** - Early release with core features. Built for developers who want to understand their code, not just generate it.
+codehere scans every AI write before it touches your codebase. Works with Claude Code, Cursor, Codex — any AI coding agent.
 
----
+**Safety features need no API key. AI features work with Anthropic or OpenAI.**
 
-## What It Does (v0.1.0)
-
-✅ **Index** - Build semantic search index of your codebase
-✅ **Ask** - Natural language queries about your code with context
-✅ **Plan** - Break down complex development tasks into steps
-✅ **Edit** - **Enterprise-grade code editing with security, verification, and governance** ⭐ NEW
-✅ **Multi-Provider** - Works with OpenAI, Cohere, Ollama, OpenRouter, local models
-✅ **Local-First** - SQLite storage, per-repository isolation, privacy-focused
-
-## What's Coming
-
-⏳ **Multi-file Edit** - Edit across multiple files simultaneously (v0.2.0)
-⏳ **Fix** - Automated bug fixing with context (v0.2.0)
-⏳ **Refactor** - Intelligent multi-file refactoring (v0.2.0)
-
----
-
-## Philosophy
-
-**We believe:**
-- Learning > Dependency
-- Explanations > Solutions
-- Augmentation > Replacement
-
-Codehere explains the "why", not just the "what". It teaches patterns, not just code.
-
----
-
-## Quick Start
-
-### 1. Install
+## Install
 
 ```bash
 npm install -g codehere
 ```
 
-### 2. Setup
-
-```bash
-# OpenAI (recommended for v0.1.0)
-export CODEHERE_AI_PROVIDER=openai
-export CODEHERE_OPENAI_API_KEY=sk-...
-
-# Or Cohere
-export CODEHERE_AI_PROVIDER=cohere
-export COHERE_API_KEY=your-key
-
-# Or Ollama (local, private)
-export CODEHERE_AI_PROVIDER=local
-export CODEHERE_LOCAL_BASE_URL=http://localhost:11434
-```
-
-### 3. Index Your Project
-
-```bash
-cd your-project
-codehere index
-```
-
-### 4. Ask Questions
+## 30 seconds to safer AI coding
 
 ```bash
-codehere ask "how does authentication work?"
-codehere ask "where is error handling done?"
-codehere ask "explain the database schema"
-```
+# Activate the safety hook — every AI write gets scanned
+codehere hook install
 
-### 5. Plan Tasks
+# See what the scanner finds
+codehere trust .
 
-```bash
-codehere plan "add rate limiting to the API"
-codehere plan "refactor user service for better testability"
+# Get a shareable audit report
+codehere report
 ```
 
----
-
-## Core Features
-
-### 📚 Semantic Search
+That's it. Every `Bash`, `Edit`, `Write`, and `MultiEdit` call from your AI assistant now goes through a 60+ pattern security scan in under 5ms. Dangerous calls get blocked with a reason. Clean calls execute normally.
 
-Index your codebase once, query it naturally:
+## What it catches
 
-```bash
-codehere index                    # Build embeddings
-codehere ask "how do we handle payments?"  # Query with AI
-```
-
-**What it does:**
-- Chunks your code intelligently
-- Creates embeddings (vector representations)
-- Stores in local SQLite (`.codehere-cache/`)
-- Retrieves relevant context for queries
-- Never sends your code externally (with local models)
+SQL injection, XSS, command injection, hardcoded secrets, path traversal, SSRF, weak crypto, JWT bypass, eval injection, open redirects, prompt injection, credential theft, destructive operations, supply chain patterns.
 
-### 🤖 Multi-Provider Support
-
-Switch between providers seamlessly:
+## AI-powered commands
 
 ```bash
-# OpenAI (GPT-4, GPT-4o, o1, o3)
-export CODEHERE_AI_PROVIDER=openai
-
-# Cohere (Command-R, Command-R+)
-export CODEHERE_AI_PROVIDER=cohere
+export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
 
-# OpenRouter (400+ models)
-export CODEHERE_AI_PROVIDER=openrouter
-
-# Ollama (local)
-export CODEHERE_AI_PROVIDER=local
-
-# Custom endpoint
-export CODEHERE_AI_PROVIDER=local
-export CODEHERE_LOCAL_BASE_URL=http://your-endpoint
+codehere index                          # build codebase index (once)
+codehere ask "how does auth work?"      # ask about your code
+codehere explain src/api.ts             # explain a file
+codehere fix src/api.ts "add validation"  # AI fix with safety check
+codehere plan "refactor auth to JWT"    # plan complex tasks
 ```
 
-No vendor lock-in. Your embeddings and configuration work with any provider.
-
-### 🎯 Task Planning
-
-Break down complex tasks:
+Or just type what you want:
 
 ```bash
-codehere plan "migrate from REST to GraphQL"
+codehere "what vulnerabilities does server.js have"
+codehere "explain the auth flow"
 ```
 
-Returns:
-- Step-by-step breakdown
-- Files that need changes
-- Potential risks
-- Testing strategy
-
-### ✏️ Enterprise-Grade Code Editing ⭐ NEW
+codehere routes your query to the right tool automatically.
 
-Edit code with enterprise security and governance:
+## Interactive REPL
 
 ```bash
-codehere edit src/auth.ts "add rate limiting"
-codehere edit src/api.ts "optimize performance" --explain
-codehere edit src/config.ts "add feature" --show-cost
+codehere    # launches the REPL
 ```
 
-**What makes our edit command superior:**
-
-| Feature | Codehere | Claude Code | Aider | Cursor | GitHub Copilot |
-|---------|----------|-------------|-------|--------|----------------|
-| Multi-provider support | ✅ Any LLM | ❌ Claude only | ✅ Any | ❌ Proprietary | ⚠️ Limited |
-| Cost transparency | ✅ Per-op costs | ❌ Hidden | ❌ No | ❌ Hidden | ❌ Hidden |
-| Learning mode (explains changes) | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Security scanning (SAST+License+Bias) | ✅ Full suite | ⚠️ Basic | ❌ No | ⚠️ Basic | ⚠️ Basic |
-| Automatic verification + rollback | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Team standards validation | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Enterprise governance (NIST AI RMF) | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Policy-as-Code compliance | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Bi-directional learning | ✅ Learns from you | ❌ No | ❌ No | ❌ No | ❌ No |
-| Prompt-to-code lineage tracking | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| HITL validation | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
-| Privacy (local-first) | ✅ Complete | ❌ Cloud | ⚠️ Optional | ❌ Cloud | ❌ Cloud |
-
-**Why this matters:**
-- **Multi-provider**: Never locked into one vendor. Compare GPT-4 vs Claude vs local models.
-- **Cost transparency**: Know exactly what each edit costs before you commit.
-- **Learning mode**: Understand WHY changes are made, become a better developer.
-- **Enterprise security**: Built-in SAST, license checks, bias detection, uncertainty quantification.
-- **Governance**: NIST AI RMF compliance, policy-as-code, audit trails for regulated industries.
-- **Privacy**: Your code never leaves your machine with local models.
-
-### 🔒 Privacy-Focused
-
-**Local-first architecture:**
-- SQLite storage (not cloud databases)
-- Per-repository isolation
-- No telemetry
-- No analytics
-- Your code = your data
-
-**Works completely offline** with Ollama or local models.
-
----
-
-## Configuration
+- Type anything — plain language routes to the right command
+- Type `/` to see all 27 commands with descriptions
+- Arrow keys navigate the palette, Tab completes
+- `trust .`, `status`, `explain src/auth.ts` work with or without `/`
 
-```bash
-# Show current config
-codehere config
+## Safety commands (no API key)
 
-# Interactive setup wizard
-codehere setup
+| Command | What it does |
+|---|---|
+| `codehere hook install` | Activate pre-execution safety hook |
+| `codehere trust [path]` | Security scan — score 0-100, grade A-F |
+| `codehere trust --ci` | Exit 1 on critical findings (for CI pipelines) |
+| `codehere report` | Markdown audit report (shareable) |
+| `codehere report --simple` | Plain English for non-technical readers |
+| `codehere status` | Dashboard: scans, blocks, recent activity |
+| `codehere health` | System health check |
+| `codehere serve` | Start as MCP server for Claude Desktop / Cursor |
 
-# Check system health
-codehere health
+## How the hook works
 
-# List available models
-codehere models
 ```
-
----
-
-## Commands
-
-| Command | Status | Description |
-|---------|--------|-------------|
-| `index` | ✅ Stable | Build embeddings index |
-| `ask` | ✅ Stable | Query your codebase |
-| `plan` | ✅ Stable | Break down tasks |
-| `edit` | ✅ **Stable** ⭐ | **Enterprise-grade code editing** |
-| `config` | ✅ Stable | Manage settings |
-| `models` | ✅ Stable | List providers/models |
-| `setup` | ✅ Stable | Interactive wizard |
-| `health` | ✅ Stable | System diagnostics |
-| `suggest` | ⚠️ Beta | Read-only queries |
-| `fix` | ⚠️ Beta | Automated bug fixing (uses edit) |
-| `refactor` | ⏳ v0.2.0 | Multi-file refactoring |
-
----
-
-## Requirements
-
-- **Node.js** 20+ (22+ recommended)
-- **TypeScript/JavaScript** codebase (other languages partially supported)
-- **API Key** for your chosen provider (or Ollama for local)
-
----
-
-## Examples
-
-### Understanding Authentication
-
-```bash
-$ codehere ask "explain the authentication flow"
-
-Answer:
-The authentication uses JWT tokens with a two-step process:
-
-1. Login (POST /api/auth/login):
-   - Validates credentials in auth-service.ts:45
-   - Generates JWT with 24h expiry in token-manager.ts:89
-   - Returns token + refresh token
-
-2. Protected Routes:
-   - Middleware in auth-middleware.ts:23 verifies JWT
-   - Extracts user from token payload
-   - Attaches to req.user for downstream handlers
-
-Key files:
-  - src/services/auth-service.ts
-  - src/middleware/auth-middleware.ts
-  - src/utils/token-manager.ts
-
-Potential improvements:
-  - Add rate limiting on login endpoint
-  - Consider refresh token rotation
-  - Add session invalidation on logout
+Your AI assistant → runs a command
+         ↓
+codehere intercepts (PreToolUse hook)
+         ↓
+60+ pattern scan in < 5ms
+         ↓
+Clean? → executes normally
+Dangerous? → blocked with reason
+         ↓
+Everything logged to ~/.codehere/audit/
 ```
 
-### Planning a Feature
+## MCP server
 
 ```bash
-$ codehere plan "add rate limiting to API endpoints"
-
-Plan:
-1. Install rate-limiting library (express-rate-limit)
-   Risk: Medium - Choose library carefully
-   Files: package.json
-
-2. Create rate-limit middleware
-   Risk: Low - Standard pattern
-   Files: src/middleware/rate-limit.ts
-
-3. Apply to routes
-   Risk: Medium - Don't rate-limit health checks
-   Files: src/routes/*.ts
-
-4. Add configuration
-   Risk: Low
-   Files: src/config/rate-limits.ts
-
-5. Add tests
-   Risk: Low
-   Files: test/middleware/rate-limit.test.ts
-
-Testing approach:
-- Unit tests for middleware
-- Integration tests for actual rate limiting
-- Load testing to verify limits work under pressure
+codehere serve
 ```
 
----
-
-## Roadmap
-
-### v0.1.0 (Current) ✅
-- Index, Ask, Plan commands
-- Multi-provider support
-- Local-first storage
-
-### v0.2.0 (Next)
-- Multi-file editing
-- Git integration (auto-commits)
-- IDE extension (VS Code)
-
-### v0.3.0
-- Refactor command (multi-file changes)
-- Better TypeScript support
-- Performance optimizations
+Exposes 4 tools to any MCP client (Claude Desktop, Cursor, etc.):
+- `codehere_trust` — score a file or snippet
+- `codehere_scan` — scan text for threats
+- `codehere_review` — find riskiest files
+- `codehere_audit` — read the audit log
 
-### v1.0.0
-- All core features stable
-- Production-ready
-- Comprehensive documentation
-
----
-
-## Status & Limitations
-
-**v0.1.0 is an early release.**
-
-**What works well:**
-- ✅ Indexing TypeScript/JavaScript projects
-- ✅ Semantic search and context retrieval
-- ✅ Task planning and breakdown
-- ✅ Multi-provider abstraction
-- ✅ Code editing with security validation
-- ✅ Automatic backup and rollback
-
-**Known limitations:**
-- ⚠️ Large repos (>100K lines) may be slow to index
-- ⚠️ Multi-file editing not yet implemented
-- ⚠️ Non-TS/JS files have limited support
-- ⚠️ Embeddings need refresh after major code changes
-- ⚠️ IDE integration coming in v0.2.0
-
-**We're being honest about capabilities.** If something doesn't work, we want to know: [GitHub Issues](https://github.com/muhammadegaa/codehere/issues)
-
----
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
-
-**Priority areas for v0.2.0:**
-- Multi-file editing
-- Git integration
-- VS Code extension
+## Requirements
 
----
+- Node.js 18+
+- For AI commands: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+- For safety features: nothing — works out of the box
 
 ## License
 
-MIT License - see [LICENSE](../LICENSE) for details
-
----
-
-## Philosophy
-
-Codehere is built on the belief that **developers should understand their code, not just generate it.**
-
-We focus on:
-- **Learning** - Explaining patterns and decisions
-- **Transparency** - Showing how conclusions are reached
-- **Augmentation** - Making developers better, not replacing them
-
-This is v0.1.0. We're learning too. Help us build something better.
-
----
-
-**Questions?** Open an issue or discussion on GitHub.
-**Security concerns?** See [SECURITY.md](../.internal/docs/SECURITY.md)
+MIT

package/dist/application/agents/execution-agent.js

@@ -224,8 +224,7 @@ export class ExecutionAgent {
         const failed = new Set(subPlans.filter(sp => sp.status === 'failed').map(sp => sp.id));
         subPlans.forEach((sp, index) => {
             if (sp.status === 'pending') {
-                const deps = Array.isArray(sp.dependencies) ? sp.dependencies : [];
-                const failedDependencies = deps.filter(depId => failed.has(depId));
+                const failedDependencies = sp.dependencies.filter(depId => failed.has(depId));
                 if (failedDependencies.length > 0) {
                     // Mark as failed due to dependency failure
                     subPlans[index] = {
@@ -242,11 +241,8 @@ export class ExecutionAgent {
      */
     getExecutableSubPlans(plan) {
         const completed = new Set(plan.subPlans.filter(sp => sp.status === 'completed').map(sp => sp.id));
-        return plan.subPlans.filter(sp => {
-            const deps = Array.isArray(sp.dependencies) ? sp.dependencies : [];
-            return sp.status === 'pending' &&
-                deps.every(depId => completed.has(depId));
-        });
+        return plan.subPlans.filter(sp => sp.status === 'pending' &&
+            sp.dependencies.every(depId => completed.has(depId)));
     }
     /**
      * Execute a single sub-plan
@@ -406,7 +402,7 @@ export class ExecutionAgent {
         if (filepathMatch) {
             params.filepath = filepathMatch[1];
         }
-        // For search actions, use description as query
+        // For search/review/analyze actions, use description as query
         if (subPlan.type === 'search' || subPlan.type === 'analyze' || subPlan.type === 'review') {
             params.query = subPlan.description;
         }
@@ -438,28 +434,6 @@ export class ExecutionAgent {
                 }
             }
         }
-        // For test actions, extract command for bash tool
-        if (subPlan.type === 'test') {
-            // Use description as command, or construct a reasonable test command
-            // Pattern: "Write unit tests for X" -> "npm test" or "test X"
-            if (subPlan.description.toLowerCase().includes('unit test')) {
-                params.command = 'npm test';
-            }
-            else if (subPlan.description.toLowerCase().includes('test')) {
-                // Extract what to test from description
-                const testMatch = subPlan.description.match(/test(?:s?)\s+(?:for|in|on)?\s*(.+?)(?:\s|$)/i);
-                if (testMatch) {
-                    params.command = `npm test -- ${testMatch[1].trim()}`;
-                }
-                else {
-                    params.command = 'npm test';
-                }
-            }
-            else {
-                // Default: use description as command
-                params.command = subPlan.description;
-            }
-        }
         // Merge with context
         return { ...context, ...params };
     }

package/dist/application/agents/multi-agent-orchestrator.js

@@ -71,7 +71,6 @@ export class MultiAgentOrchestrator {
                     planningResponse = await this.planningAgent.createPlan({
                         goal: request.goal,
                         context: request.context,
-                        feedback: request.feedback, // Pass feedback from previous attempt for reflexion
                     });
                     plan = planningResponse.plan;
                     // Capture planning summary