echoproof

# Echoproof

[![CI](https://github.com/est57/echoproof/actions/workflows/ci.yml/badge.svg)](https://github.com/est57/echoproof/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/echoproof.svg)](https://crates.io/crates/echoproof)
[![Release](https://img.shields.io/github/v/release/est57/echoproof?sort=semver)](https://github.com/est57/echoproof/releases)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#lisensi)

**Bahasa Indonesia** | [English](README.en.md)

**Verifikasi perilaku API untuk setiap perubahan kode, berdasarkan traffic nyata.**

Echoproof merekam request dan response asli dari service Anda, memutarnya ulang ke build hasil perubahan kode, lalu melaporkan **apa yang berubah, di endpoint dan field mana, pada berapa persen request, dan apakah perubahan itu memang diniatkan**. Hasilnya bisa dipakai sebagai gate di CI atau langsung oleh coding agent (Claude Code, Cursor, dan sejenisnya) untuk memeriksa pekerjaannya sendiri.

<p align="center"><img src="https://raw.githubusercontent.com/est57/echoproof/main/docs/demo.svg" alt="Echoproof menangkap regresi harga yang tidak dijelaskan oleh niat perubahan" width="900"></p>

```
record  ->  replay ke build lama dan baru  ->  diff semantik  ->  nilai terhadap niat  ->  gate
```

## Daftar isi

- [Mengapa Echoproof](#mengapa-echoproof)
- [Fitur utama](#fitur-utama)
- [Instalasi](#instalasi)
- [Mulai cepat](#mulai-cepat)
- [Demo](#demo)
- [Konsep](#konsep)
- [Referensi perintah](#referensi-perintah)
- [Konfigurasi](#konfigurasi)
- [Membaca laporan](#membaca-laporan)
- [Integrasi CI](#integrasi-ci)
- [Integrasi coding agent (MCP)](#integrasi-coding-agent-mcp)
- [Keamanan dan privasi](#keamanan-dan-privasi)
- [Batasan](#batasan)
- [Pengembangan](#pengembangan)
- [Lisensi](#lisensi)

## Mengapa Echoproof

Saat sebagian besar kode ditulis oleh AI agent, jumlah perubahan naik jauh lebih cepat daripada kemampuan manusia untuk meninjaunya. Tes yang lulus dan diff yang tampak rapi belum menjamin perilaku sistem tetap benar, karena tes ditulis dari asumsi, sedangkan bug sering muncul dari kombinasi data nyata yang tidak terpikirkan.

Echoproof menjawab satu pertanyaan yang tidak dijawab oleh tes unit maupun code review:

> Apakah perubahan ini mengubah perilaku sistem terhadap traffic nyata, dan apakah perubahan itu memang yang dimaksud?

Contoh yang ditangkap Echoproof: sebuah PR berniat "menambah field `currency` di katalog", tetapi tanpa sengaja salah menempatkan satu argumen. Akibatnya harga 3 dari 8 menu berubah, sementara 5 menu lainnya tetap benar. Tes unit lulus dan diff kode terlihat wajar. Echoproof melaporkan `products[*].price: 18000 -> 22000` pada setiap request katalog dan menandainya sebagai regresi.

## Fitur utama

- **Rekam dari traffic nyata.** Reverse proxy yang merekam setiap request dan response, dengan data sensitif disamarkan sebelum ditulis ke disk.
- **Diff semantik.** JSON dibandingkan per field, bukan per baris teks. Perubahan dikelompokkan per endpoint dan field, lalu diklasifikasikan sebagai `breaking`, `behavior`, atau `additive`.
- **Tahan noise.** UUID, timestamp, dan nilai acak dikenali otomatis. Field yang berubah sendiri antar-run dipelajari dengan me-replay build lama dua kali.
- **Aman terhadap state.** Request tulis tidak di-replay kecuali diizinkan per endpoint. Build lama dan baru dibandingkan di atas data yang sama, dengan perintah reset di antara setiap putaran.
- **Sadar niat perubahan.** Setiap kelompok perubahan bisa dinilai oleh Claude terhadap deskripsi PR atau tugas agent. Perubahan yang tidak dijelaskan oleh niat ditandai sebagai regresi.
- **Siap untuk CI dan agent.** Exit code untuk gate merge, laporan Markdown untuk komentar PR, JSON untuk otomasi, dan server MCP untuk coding agent.

## Instalasi

### Homebrew (macOS dan Linux)

```bash
brew install est57/tap/echoproof
```

### Binary siap pakai (disarankan)

Unduh arsip untuk platform Anda dari [halaman rilis](https://github.com/est57/echoproof/releases), atau lewat terminal:

```bash
VERSION=v0.1.0
TARGET=aarch64-apple-darwin   # atau x86_64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz
curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz.sha256
shasum -a 256 -c echoproof-$VERSION-$TARGET.tar.gz.sha256
tar -xzf echoproof-$VERSION-$TARGET.tar.gz
sudo mv echoproof-$VERSION-$TARGET/echoproof /usr/local/bin/
```

```bash
echoproof --version
```

### Dengan Cargo

Jika Rust 1.85 atau lebih baru sudah terpasang:

```bash
cargo install echoproof
```

### Dari source code

**Kebutuhan:** Rust 1.85 atau lebih baru. `curl` diperlukan untuk menjalankan demo.

```bash
git clone https://github.com/est57/echoproof.git
cd echoproof
cargo install --path crates/echoproof-cli
```

Binary `echoproof` dipasang di `~/.cargo/bin`. Pastikan folder itu ada di `PATH`:

```bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```

```bash
echoproof --version
```

## Mulai cepat

Langkah berikut memeriksa sebuah perubahan kode pada service yang berjalan di lingkungan uji Anda.

**1. Buat file konfigurasi** (opsional, semua pengaturan punya nilai default):

```bash
echoproof init
```

**2. Rekam traffic.** Jalankan proxy di depan service, lalu arahkan aplikasi, Postman, atau tes otomatis ke alamat proxy:

```bash
echoproof record --upstream http://127.0.0.1:8000 --listen 127.0.0.1:8080 --out traffic.jsonl
```

Hentikan dengan `Ctrl-C` setelah traffic yang representatif terkumpul.

**Aplikasi Laravel bisa merekam tanpa proxy** dengan [echoproof/laravel](https://github.com/est57/echoproof-laravel): jalankan `composer require echoproof/laravel`, isi `ECHOPROOF_RECORD=true` di `.env`, dan traffic ditulis ke `storage/echoproof/traffic.jsonl` dengan aturan sensor yang sama.

**3. Jalankan dua build**, versi sebelum perubahan (base) dan sesudahnya (PR), memakai database yang sama.

**4. Bandingkan:**

```bash
echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002
```

**5. Baca hasilnya.** Exit code `0` berarti tidak ada perubahan yang tidak diharapkan, `1` berarti ada regresi, `2` berarti terjadi error. Lihat [Membaca laporan](#membaca-laporan).

Untuk menilai perubahan terhadap niatnya, tambahkan deskripsi PR dan diff kodenya:

```bash
git diff main...HEAD > change.diff
echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002 \
  --intent-file pr-description.md --code-diff change.diff --output echoproof-report.md
```

## Demo

Demo lengkap berjalan sekitar 10 detik dan tidak membutuhkan service Anda sendiri:

```bash
./scripts/demo.sh
```

Demo memakai backend POS kecil (`examples/demo-shop`) yang memiliki state, yaitu stok produk yang berkurang setiap ada order. Sebuah "PR dari agent" berniat menambah field `currency` pada produk, tetapi juga mengubah cara diskon promo dan voucher digabungkan.

| Langkah | Yang ditunjukkan |
|---|---|
| 1. Rekam 2.000 request dari versi production | Proses perekaman |
| 2. Replay ke versi yang sama, dibandingkan dengan rekaman | Alarm palsu akibat state: stok sudah berkurang selama perekaman |
| 3. Bandingkan build base dan PR dengan `--base` dan `--reset`, mode aman | Alarm palsu hilang. `currency` terdeteksi. Request tulis dilaporkan belum terverifikasi |
| 4. Sama seperti langkah 3, dengan `--allow-writes "POST /orders"` | Bug diskon tertangkap, hanya pada order yang memakai promo dan voucher bersamaan |
| 5. Penilaian niat oleh Claude (jika `ANTHROPIC_API_KEY` tersedia) | `currency` dinilai intended, perubahan diskon dinilai regression |

## Konsep

### Snapshot

Snapshot adalah file JSONL berisi satu pasangan request dan response per baris. Header dan field sensitif sudah disamarkan sebelum ditulis. Snapshot yang sama dapat dipakai berulang kali untuk memeriksa banyak PR.

### Dua mode perbandingan

| Mode | Perintah | Cocok untuk |
|---|---|---|
| Terhadap rekaman | `echoproof check -s traffic.jsonl -t URL_PR` | Service tanpa state, atau lingkungan yang datanya identik dengan saat perekaman |
| Base vs PR | `echoproof check -s traffic.jsonl --base URL_BASE -t URL_PR` | Service dengan database (disarankan) |

Pada mode **base vs PR**, response hasil rekaman tidak dipakai sebagai acuan. Echoproof memutar traffic yang sama ke kedua build di atas data yang sama:

```
reset  ->  replay ke base         ->  acuan
reset  ->  replay ke base lagi    ->  field yang berbeda dicatat sebagai noise
reset  ->  replay ke PR           ->  kandidat
diff acuan dan kandidat, abaikan noise
```

Alamat server masing-masing build (misalnya `http://127.0.0.1:8001` di URL gambar atau link pagination) dinormalkan otomatis, sehingga dua build yang berjalan di port berbeda tetap sebanding.

### Mode aman

Secara default, hanya method `GET`, `HEAD`, dan `OPTIONS` yang di-replay. Request tulis dilewati dan **tidak dihitung lulus**: laporan menyebut jumlahnya dan memperingatkan bahwa perilakunya belum terverifikasi.

Izinkan request tulis per endpoint, hanya terhadap lingkungan yang boleh diubah atau dapat di-reset:

```bash
echoproof check ... --allow-writes "POST /orders" --allow-writes "PUT /cart/*"
```

Gunakan `--reset` (atau `replay.reset`) untuk mengembalikan state sebelum setiap putaran, misalnya dengan me-restore dump database atau memanggil endpoint reset di lingkungan uji. Echoproof menolak me-replay request tulis tanpa reset bila noise sedang dipelajari, karena perubahan state di antara run akan ikut dianggap noise dan menyembunyikan regresi.

### Diff semantik

- JSON dibandingkan per field. `5` dan `5.0` dianggap sama, dan urutan key diabaikan.
- Setiap perubahan diklasifikasikan:

  | Klasifikasi | Contoh |
  |---|---|
  | `breaking` | Field hilang, tipe berubah (termasuk menjadi `null`), status 2xx menjadi error |
  | `behavior` | Nilai