Metadata-Version: 2.4
Name: codereaper
Version: 0.1.0
Summary: AI-driven JavaScript dead code elimination via browser agent + V8 coverage
Project-URL: Homepage, https://github.com/kaldonia/codereaper
Project-URL: Repository, https://github.com/kaldonia/codereaper
License-Expression: MIT
Keywords: browser-agent,coverage,cursor,dead-code,javascript,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: lmnr-index>=0.1.0
Requires-Dist: playwright>=1.49.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.10.0
Provides-Extra: all
Requires-Dist: fastapi>=0.115.0; extra == 'all'
Requires-Dist: lmnr[all]>=0.5.0; extra == 'all'
Requires-Dist: rich>=13.9.0; extra == 'all'
Requires-Dist: sse-starlette>=2.2.0; extra == 'all'
Requires-Dist: typer>=0.15.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == 'api'
Requires-Dist: sse-starlette>=2.2.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'api'
Description-Content-Type: text/markdown

# CodeReaper

AI-driven JavaScript dead code elimination for websites and Chrome extensions.

CodeReaper scans a target URL or unpacked Chrome extension, autonomously explores the UI via the [Index](https://github.com/lmnr-ai/index) browser agent, collects V8 precise coverage data, and produces verified unified diffs that safely remove dead code.

## Install

### pip / pipx (recommended)

```bash
pip install codereaper
playwright install chromium
```

Or with zero-install via pipx:

```bash
pipx run codereaper          # starts MCP server directly
```

### npm / npx

```bash
npx codereaper               # auto-detects uvx/pipx/python
```

### From source

```bash
git clone https://github.com/your-org/codereaper.git
cd codereaper
pip install -e ".[all]"
playwright install chromium
```

## Configure

Create a `.env` file in the project root (or set environment variables):

```env
# LLM for Index browser agent
CODEREAPER_INDEX_LLM_PROVIDER=gemini
CODEREAPER_INDEX_LLM_MODEL=gemini-2.5-pro-preview-05-06
GOOGLE_API_KEY=your-key-here

# Or use OpenAI / Anthropic
# CODEREAPER_INDEX_LLM_PROVIDER=openai
# CODEREAPER_INDEX_LLM_MODEL=gpt-4o
# OPENAI_API_KEY=your-key-here

# Storage (optional, defaults shown)
CODEREAPER_DATA_DIR=./data
CODEREAPER_DB_PATH=./data/codereaper.db
```

## Cursor MCP Integration

CodeReaper runs as an MCP (Model Context Protocol) server that Cursor invokes to scan websites, find dead code, and suggest what to delete.

### Add to Cursor

Add one of these to your `.cursor/mcp.json`:

**If installed via pip:**

```json
{
  "mcpServers": {
    "codereaper": {
      "command": "codereaper"
    }
  }
}
```

**If using pipx (zero-install):**

```json
{
  "mcpServers": {
    "codereaper": {
      "command": "pipx",
      "args": ["run", "codereaper"]
    }
  }
}
```

**If using npx (zero-install):**

```json
{
  "mcpServers": {
    "codereaper": {
      "command": "npx",
      "args": ["-y", "codereaper"]
    }
  }
}
```

**From source (development):**

```json
{
  "mcpServers": {
    "codereaper": {
      "command": "python3",
      "args": ["-m", "codereaper.mcp"],
      "cwd": "/absolute/path/to/codereaper"
    }
  }
}
```

Restart Cursor after editing `mcp.json`.

### Usage in Cursor

Ask the assistant to find dead code:

> "Find dead JavaScript code on http://localhost:3000"

The assistant calls `find_dead_code` which:
1. Launches a browser with an AI agent that explores the site
2. Collects V8 code coverage showing which functions executed
3. Returns a report of every function with zero executions

Provide a local source directory so the report maps URLs to local files:

> "Find dead code on http://localhost:3000, source is in ./test_site"

### MCP Tools

| Tool | Description |
|------|-------------|
| `find_dead_code` | Full pipeline: scan + analyze. Returns dead-code report with file paths, line numbers, risk scores, and removal recommendations. |
| `scan_website` | Scan only (no analysis). Returns scan_id for later use. |
| `analyze_dead_code` | Analyze a completed scan. Takes scan_id. |
| `generate_patches` | Generate unified diffs to remove dead code (conservative / balanced / aggressive). |
| `get_patch_diff` | Retrieve the combined diff for a patch. |
| `apply_patch` | Apply a patch to source files (stores snapshots for rollback). |
| `verify_patch` | Re-run the browser agent to check for regressions after patching. |
| `rollback_patch` | Restore original files from pre-patch snapshots. |
| `list_scans` | List recent scans. |
| `get_scan_status` | Get detailed status of a scan. |

## REST API

CodeReaper also exposes a REST API via FastAPI for programmatic access.

### Start the API server

```bash
codereaper-api                                          # console script
python -m codereaper.api                                # module
uvicorn codereaper.api.app:app --reload --port 8000     # uvicorn directly
```

API docs at [http://localhost:8000/docs](http://localhost:8000/docs).

### Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| `POST` | `/api/v1/scans` | Start scan + exploration |
| `GET` | `/api/v1/scans/{scanId}` | Scan status & results |
| `GET` | `/api/v1/scans/{scanId}/stream` | SSE progress stream |
| `POST` | `/api/v1/scans/{scanId}/analyze` | Analyze dead code candidates |
| `POST` | `/api/v1/scans/{scanId}/patches` | Generate patch proposals |
| `GET` | `/api/v1/patches/{patchId}` | Retrieve patch details / diffs |
| `POST` | `/api/v1/patches/{patchId}/apply` | Apply patch (requires confirm) |
| `POST` | `/api/v1/patches/{patchId}/verify` | Verify patch via replay |
| `GET` | `/api/v1/patches/{patchId}/verify/stream` | SSE verification progress |
| `POST` | `/api/v1/patches/{patchId}/rollback` | Rollback to pre-patch state |
| `GET` | `/api/v1/health` | Health check |

## Architecture

```
Cursor (MCP)  /  CLI  /  REST client
        |                    |
   MCP Server           FastAPI Server
   (codereaper.mcp)     (codereaper.api)
        \                  /
         \                /
      Shared Services Layer
      (scanner, analyzer, patcher, verifier)
              |                |
    Index Browser Agent    V8 CDP Coverage
    (autonomous UI         (precise per-function
     exploration)           execution counts)
```

## Pipeline

| Phase | Description |
|-------|-------------|
| 1. Scan & Explore | Launch Index agent to autonomously interact with all UI surfaces while collecting V8 coverage |
| 2. Analyze | Map coverage ranges to functions, classify executed vs. unexecuted, detect dynamic references |
| 3. Patch | Generate unified diffs with rationale and risk scores |
| 4. Verify | Replay the original interaction plan against patched code, detect regressions |
| 5. Rollback | Restore original files from pre-patch snapshots |

## Project Structure

```
codereaper/
├── __main__.py              # python -m codereaper -> MCP server
├── mcp/                     # MCP server for Cursor
│   ├── __init__.py          # main() entry point
│   ├── __main__.py          # python -m codereaper.mcp
│   └── server.py            # FastMCP tools
├── api/                     # REST API (FastAPI)
│   ├── __init__.py          # main() entry point
│   ├── __main__.py          # python -m codereaper.api
│   ├── app.py               # FastAPI app, lifespan, CORS
│   └── routers/
│       ├── scans.py         # Scan + analyze endpoints
│       └── patches.py       # Patch + verify + rollback endpoints
├── services/                # Shared business logic
│   ├── scanner.py           # Index agent orchestration + CDP coverage
│   ├── analyzer.py          # Coverage mapping + dead code detection
│   ├── patcher.py           # Diff generation + application + rollback
│   └── verifier.py          # Replay + regression detection
├── models/
│   ├── schemas.py           # Pydantic request/response models
│   └── enums.py             # Status, risk, safety enums
├── core/
│   ├── config.py            # Settings via pydantic-settings
│   ├── storage.py           # SQLite + filesystem artifact storage
│   └── sse.py               # SSE event helpers + channel
└── tests/

bin/cli.mjs                  # npx wrapper (spawns uvx/pipx/python)
pyproject.toml               # Python packaging (pip install codereaper)
package.json                 # npm packaging (npx codereaper)
```

## Tech Stack

- **MCP Server**: FastMCP
- **REST Server**: FastAPI + Uvicorn
- **Validation**: Pydantic v2
- **Storage**: aiosqlite + filesystem
- **Browser**: Playwright (via Index agent)
- **Coverage**: V8 CDP Profiler domain
- **Diff**: Python `difflib`
- **SSE**: `StreamingResponse` with `text/event-stream`
