# RepoPilot

**One repo in. A launch-ready plan out.**

RepoPilot is the quality layer for agents that ship code. Point it at a
public GitHub repository and get a structured launch-readiness report —
evidence-backed findings, explainable scoring, and ready-to-paste launch
copy — plus a **fix plan per finding** that an agent can act on directly.

It closes the loop: audit → fix plan → fix → re-audit → compare. The
comparison attributes score movement rule by rule and splits findings
into resolved, new and still-open. Built for Web3 developers, hackathon
contestants, and other AI agents.

📚 **Looking for a specific doc?** Start at
[docs/INDEX.md](docs/INDEX.md) — it lists every document with one-line
descriptions and points you at the right one.

RepoPilot runs **static analysis only**. It does not execute the
audited repository's code. It does not perform a formal security
audit. It does not custody funds or read private keys.

## Why RepoPilot

- **Evidence first.** Every finding has at least one `path:line:reason`
  pointer, and so does every fix step. The score is rule-based and
  reproducible.
- **A plan, not just a report.** Each finding gets a fix plan with
  ordered steps, tests to add, acceptance criteria, estimated effort and
  risks — plus an `agentInstructions` block you can hand straight to
  Codex, Claude Code or OpenCode.
- **Before/after, attributed.** Re-audit after fixing and RepoPilot says
  what moved: the score delta per dimension, the exact scoring rules
  that changed, and which findings were resolved, appeared or persist.
- **Built for AI agents.** The report is a single JSON document with a
  stable schema (`reportVersion: "1.1"`; `"1.0"` still parses). The MCP
  server exposes seven
  tools and marks which of them are free, so any MCP-compatible client
  can drive the whole loop.
- **No surprise charges.** Reading a fix plan or a comparison is free;
  only running an audit costs anything. A `MockPaymentAdapter` is the
  default, the real `OkxPaymentAdapter` is opt-in. See
  [`docs/EXTERNAL_ACTIONS.md`](docs/EXTERNAL_ACTIONS.md) for the
  Beta gate.
- **No execution, and no LLM in the scoring.** The pipeline reads text
  only. Binary files are skipped, prompt-injection patterns are reported
  as findings, and the LLM (when enabled) may only rewrite natural
  language — never a score, a priority or a piece of evidence.

## Quick start

```bash
git clone <repo>
cd repopilot
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm build
pnpm --filter @repopilot/api start
# API on http://localhost:4000
# Web on http://localhost:5173 (run pnpm --filter @repopilot/web dev in another shell)
```

Or with Docker:

```bash
docker build -t repopilot:0.1.0-rc.2 .
docker run --rm -p 4000:4000 \
  -e NODE_ENV=production -e PAYMENT_MODE=mock \
  -e DATABASE_URL=file:/data/repopilot.db \
  -e ALLOWED_REPO_HOSTS=github.com,raw.githubusercontent.com \
  -v $(pwd)/data:/data \
  repopilot:0.1.0-rc.2
```

A first audit takes 5–15 seconds for a typical `mode: 'quick'`:

```bash
# 1. Submit a repo for audit (returns 402 with a payment challenge)
curl -X POST http://localhost:4000/api/v1/audits \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/octocat/Hello-World",
       "mode":"quick","target":"open_source","outputLanguage":"en"}'

# 2. Replay with the mock X-PAYMENT header (use the paymentId from step 1)
curl -X POST http://localhost:4000/api/v1/audits \
  -H 'content-type: application/json' \
  -H "x-payment: mock:mock_xxx" \
  -d '{"repoUrl":"https://github.com/octocat/Hello-World",
       "mode":"quick","target":"open_source","outputLanguage":"en"}'
```

Then close the loop. These three are free and never re-scan the repo:

```bash
# 3. Get an actionable plan for every finding
curl http://localhost:4000/api/v1/audits/<jobId>/fix-plan

# 4. Fix something, then audit the same repository again
curl -X POST http://localhost:4000/api/v1/repositories/octocat/Hello-World/reaudit

# 5. See what actually changed, attributed rule by rule
curl "http://localhost:4000/api/v1/audits/<newJobId>/diff?base=<jobId>"
```

## Documentation

| Doc                                                  | What's in it                                          |
|------------------------------------------------------|-------------------------------------------------------|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)         | Layering, data flow, evidence rules                   |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)             | Docker, nginx, Caddy, Railway, Render, VPS            |
| [docs/SECURITY.md](docs/SECURITY.md)                 | Threat model, mitigations, redaction                  |
| [docs/API.md](docs/API.md)                           | Full HTTP API reference                               |
| [docs/MCP_CLIENT_SETUP.md](docs/MCP_CLIENT_SETUP.md) | Claude Code / Codex / OpenClaw / generic              |
| [docs/REPOSITORY_INTELLIGENCE_PLAN.md](docs/REPOSITORY_INTELLIGENCE_PLAN.md) | Repository intelligence roadmap |
| [docs/EXTERNAL_ACTIONS.md](docs/EXTERNAL_ACTIONS.md) | The only place that lists what a human must do        |
| [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) | Pre-tag checklist                                    |
| [docs/HERO_IMAGE_BRIEF.md](docs/HERO_IMAGE_BRIEF.md) | Marketplace hero spec                                 |
| [README_OKX.md](README_OKX.md)                       | OKX.AI / Agent Payments Protocol integration          |
| [MARKETPLACE_LISTING.md](MARKETPLACE_LISTING.md)     | EN + CN marketplace copy                              |

Project meta:

| File                                       | Purpose                                          |
|--------------------------------------------|--------------------------------------------------|
| [PROJECT_STATE.md](PROJECT_STATE.md)       | What the project is, right now                   |
| [ROADMAP.md](ROADMAP.md)                   | What's next                                      |
| [BACKLOG.md](BACKLOG.md)                   | Prioritised TODO list                            |
| [DECISIONS.md](DECISIONS.md)               | Architecture Decision Records                    |
| [RISKS.md](RISKS.md)                       | Active risks + mitigations                       |
| [CHANGELOG.md](CHANGELOG.md)               | Per-release notes                                |

## Project layout

```
repopilot/
  apps/
    api/      Fastify HTTP API
    web/      React + Vite admin UI
  packages/
    core/        analyzers + scoring + report + security + schemas + llm
                 + fixplan (report -> fix plan) + diff (report -> diff)
    mcp-server/  MCP server (stdio), seven tools
    okx-adapter/ PaymentAdapter interface, mock + OKX implementations
  fixtures/      6 sample repos for tests
  docs/          ARCHITECTURE / DEPLOYMENT / SECURITY / API / MCP / EXTERNAL
  scripts/       env-check, verify-release, docker-check, lint
  .github/workflows/  ci.yml + docker.yml
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the layering
diagram.

## Scripts

| Command                     | What it does                                              |
|-----------------------------|-----------------------------------------------------------|
| `pnpm install`              | Install all workspace deps                                |
| `pnpm -r typecheck`         | `tsc --noEmit` in every package                           |
| `pnpm -r test`              | All unit + integration tests                              |
| `pnpm lint`                 | tsc + custom static rules                                 |
| `pnpm build`                | All packages and apps                                     |
| `pnpm env:check`            | Validate env (no secret values printed)                   |
| `pnpm docker:check`         | Static Docker check (or full build if Docker is present)  |
| `pnpm compose:check`        | Static docker-compose review                              |
| `pnpm verify:release`       | End-to-end smoke (env → lint → test → build → API → MCP)  |
| `pnpm db:migrate`           | Apply DB migrations (SQLite + Postgres)                   |
| `pnpm mcp`                  | Start the MCP server over stdio                           |
| `pnpm start`                | Start the API server                                      |
| `make help`                 | See all targets (Makefile mirrors the above)              |

## Tech stack

- Node.js 22 LTS, TypeScript 5.7 strict + NodeNext ESM
- pnpm 11.x workspaces
- Fastify 5, Zod 3.24, Octokit, Drizzle (SQLite + Postgres)
- Vitest, Pino 10, React 18 + Vite 6
- `@modelcontextprotocol/sdk@1.22` (official MCP TS SDK, stdio)
- viem 2.x for EIP-3009 / EIP-712 in the OKX adapter

## Known limitations

- OKX.AI Marketplace went GA on 2026-06-30. The `OkxPaymentAdapter` is
  fully wired (x402 v2 + EIP-3009 + EIP-712) and accepts `PAYMENT_MODE=okx`
  with a valid `OKX_PAYMENT_ADDRESS`. To publish the marketplace listing,
  run `onchainos agent register --role asp` (see
  [docs/EXTERNAL_ACTIONS.md](docs/EXTERNAL_ACTIONS.md) item 2). The product
  still ships with `PAYMENT_MODE=mock` as the default so the full audit
  flow works without external services.
- `mode: 'full'` runs synchronously inside the HTTP request. Very
  large repos (> 50 MiB / 2000 files) may time out. A background
  worker is on the P1 backlog.
- The LLM is optional. With `LLM_PROVIDER=noop` the `summary` and
  `launchCopy` are template-generated; scores are always
  rule-based.

## License

MIT — see [LICENSE](LICENSE).