Echoproof

Bahasa Indonesia | English

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.

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

Daftar isi

• Mengapa Echoproof
• Fitur utama
• Instalasi
• Mulai cepat
• Demo
• Konsep
• Referensi perintah
• Konfigurasi
• Membaca laporan
• Integrasi CI
• Integrasi coding agent (MCP)
• Keamanan dan privasi
• Batasan
• Pengembangan
• 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)

brew install est57/tap/echoproof

Binary siap pakai (disarankan)

Unduh arsip untuk platform Anda dari halaman rilis, atau lewat terminal:

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/

echoproof --version

Dengan Cargo

Jika Rust 1.85 atau lebih baru sudah terpasang:

cargo install echoproof

Dari source code

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

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:

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

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):

echoproof init

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

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: 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:

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.

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

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:

./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.

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

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:

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 berubah, panjang array berubah, status berubah
  additive	Field baru

• Path dinormalkan: /products/42 menjadi GET /products/{id}, dan items[3].price menjadi $.items[*].price. Setiap perubahan dihitung sekali per request.

• UUID, ULID, dan date-time dengan bentuk yang sama dianggap noise. Tanggal saja (misalnya 2026-10-14) tetap dibandingkan.

Niat perubahan

Ada dua cara memberi tahu Echoproof perubahan apa yang diharapkan.

--expect meloloskan semua perubahan di endpoint yang disebut. Jika sebuah PR memang mengubah katalog tetapi tanpa sengaja juga merusak harga di katalog, --expect "GET /catalog" tidak akan menangkapnya.

Dengan --intent, setiap kelompok perubahan dinilai oleh Claude dan diberi verdict intended, regression, atau unclear, beserta alasan yang mengutip nilai contoh. Bahan penilaiannya meliputi niat perubahan, diff kode (opsional), persentase request yang terdampak, contoh request yang berubah beserta nilai sebelum dan sesudah, serta contoh request di endpoint yang sama yang tidak berubah sebagai pembanding. Verdict unclear dan kelompok yang tidak dinilai diperlakukan sebagai regresi (fail closed).

Penilaian niat membutuhkan API key Anthropic. Satu run melakukan satu panggilan API, dan hanya jika ada perubahan. Biaya tipikal sekitar USD 0,01 sampai 0,02 per run dengan model default.

Panggilan ke pihak ketiga

Service yang memanggil payment gateway, layanan pesan, atau API lain tidak boleh benar-benar menghubunginya saat replay. Dengan echoproof/laravel, panggilan itu direkam bersama setiap request, dan build yang dijalankan dengan ECHOPROOF_REPLAY=true menjawabnya dari rekaman serta memblokir semua panggilan lain. Kedua build menerima jawaban pihak ketiga yang identik, lalu Echoproof membandingkan apa yang dikirim setiap build:

  x POST /checkout  3/3 changed (100.0%)  unexpected
      behavior  value changed   outbound[POST pay.example.com/v2/charges] $.amount  (3 requests)
            outbound[POST pay.example.com/v2/charges] $.amount: 18000 -> 1800000

Pada contoh ini response checkout identik; hanya nominal yang dikirim ke gateway yang berubah. Panggilan yang tidak pernah terekam dilaporkan sebagai call added dengan tingkat breaking. Kalau sebuah build melaporkan panggilan yang tidak bisa dibaca Echoproof, request itu gagal dalam check, bukan lolos tanpa verifikasi.

Referensi perintah

Opsi umum:

Pola endpoint: POST /orders, GET /products/* (* cocok dengan satu segmen), /admin/** (** cocok dengan banyak segmen), atau * untuk semua.

Exit code: 0 lulus atau hanya perubahan yang diharapkan, 1 ada regresi, 2 error (konfigurasi, jaringan, reset gagal, atau penilaian niat gagal).

Konfigurasi

Semua pengaturan bersifat opsional. Jalankan echoproof init untuk membuat file berisi seluruh pengaturan beserta penjelasannya.

[record]
upstream = "http://127.0.0.1:8000"
listen = "127.0.0.1:8080"

[sanitize]
# Diterapkan saat merekam dan saat replay, sehingga nilai yang disamarkan tetap sebanding.
redact_headers = ["authorization", "cookie", "set-cookie", "x-api-key"]
redact_fields = ["password", "token", "pin", "card_number", "phone", "email"]

[replay]
concurrency = 1                                          # naikkan hanya untuk endpoint tanpa state
timeout_ms = 10000
headers = { authorization = "Bearer ${STAGING_TOKEN}" }  # menggantikan header yang disamarkan
safe_methods = ["GET", "HEAD", "OPTIONS"]
allow_writes = ["POST /orders"]                          # default kosong (mode aman)
reset = "./scripts/restore-test-db.sh"
noise_runs = 1

[diff]
ignore = ["updated_at", "$.meta.trace_id", "items[*].etag"]
expect = ["GET /products/*"]
auto_noise = true
compare_headers = ["content-type"]

[judge]
model = "claude-opus-5-5"
effort = "high"                                          # low, medium, high, xhigh, max
fallbacks = true

[mcp]
allowed_hosts = []                                       # host selain localhost yang boleh dipakai agent

Pola ignore: nama saja (updated_at) cocok di kedalaman mana pun. Pola yang diawali $ atau mengandung titik ($.meta.trace_id, items[*].etag) dihitung dari akar body.

Variabel lingkungan:

Membaca laporan

Contoh laporan di terminal:

echoproof: REGRESSION - 83 exchanges, 5 changed, 78 unchanged
  ignored 1 noisy fields that differ between runs of the base build: GET /up body
  intent judged by claude-opus-5-5: The currency field is added as intended. ...

  x GET /catalog                5/5 changed (100.0%)  unexpected
      behavior  value changed   $.result.products[*].price  (5 requests)
          [regression] The diff swaps the third argument of products() ...
          GET /catalog  [00e36fd43ade]
            $.result.products[1].price: 18000 -> 22000
      additive  added           $.result.currency  (5 requests)
          [intended] Adding 'currency' => 'IDR' matches the intent.

  - GET /branches               0/5 changed (0.0%)  unchanged

result: FAIL

Format lain:

• --format markdown menghasilkan laporan yang siap dipakai sebagai komentar PR.
• --format json menghasilkan data terstruktur, termasuk findings: satu kalimat per masalah yang siap dikembalikan ke coding agent.

Setelah perubahan ditinjau dan disetujui, jadikan hasilnya baseline baru:

echoproof replay -s traffic.jsonl -t URL_PR -o candidate.jsonl
echoproof accept candidate.jsonl --baseline traffic.jsonl

Integrasi CI

Gunakan GitHub Action Echoproof. Action ini memasang binary rilis, menjalankan echoproof check, menulis laporan ke ringkasan job, dan menyediakan verdict sebagai output:

- name: Start base and PR builds
  run: ./scripts/start-builds.sh   # base on :8001, PR on :8002, same test database

- run: git diff origin/${{ github.base_ref }}...HEAD > change.diff

- name: Behavior check
  id: echoproof
  uses: est57/echoproof-action@v1
  with:
    snapshot: traffic/baseline.jsonl
    base: http://127.0.0.1:8001
    target: http://127.0.0.1:8002
    reset: ./scripts/reset-db.sh
    intent: ${{ github.event.pull_request.title }}
    code-diff: change.diff
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Comment on PR
  if: always()
  run: gh pr comment ${{ github.event.number }} --body-file "${{ steps.echoproof.outputs.report }}"
  env:
    GH_TOKEN: ${{ github.token }}

Regresi menggagalkan step dan memblokir merge. Pakai fail-on-regression: false bila hanya ingin melapor. Di sistem CI lain, pasang binary-nya dan jalankan echoproof check langsung; exit code 1 berarti regresi.

Integrasi coding agent (MCP)

Dalam rekaman ini, Claude Code (Sonnet) diminta merapikan nama kasir di service order. Sebelumnya, bug diskon sudah ditanam di file yang sama. Pemeriksaan gagal, agent menelusuri regresi itu sampai ke bug yang bukan buatannya, memperbaikinya, dan baru menyatakan tugas selesai setelah pemeriksaan lulus.

echoproof mcp menjalankan server Model Context Protocol melalui stdio, sehingga coding agent dapat memeriksa perubahan yang dibuatnya sendiri sebelum menyatakan pekerjaan selesai.

Pasang di coding agent Anda

Pasang binary echoproof lebih dulu (brew install est57/tap/echoproof atau cargo install echoproof). Setiap agent di bawah menjalankan echoproof mcp di folder proyek Anda, sehingga dapat menjangkau build lokal dan file snapshot.

Claude Code, sebagai plugin (disarankan). Plugin ini memasang server MCP dan skill verify-behavior yang memberi tahu Claude kapan dan bagaimana memeriksa perubahannya, sehingga tidak perlu instruksi tambahan di CLAUDE.md:

/plugin marketplace add est57/echoproof
/plugin install echoproof@echoproof

Dari shell: claude plugin marketplace add est57/echoproof dan claude plugin install echoproof@echoproof.

Claude Code, hanya server MCP:

claude mcp add echoproof -- echoproof mcp

Cursor (.cursor/mcp.json di proyek, atau ~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), dan klien lain yang membaca peta mcpServers:

{ "mcpServers": { "echoproof": { "command": "echoproof", "args": ["mcp"] } } }

VS Code dengan Copilot agent mode (.vscode/mcp.json):

{ "servers": { "echoproof": { "type": "stdio", "command": "echoproof", "args": ["mcp"] } } }

Codex CLI: codex mcp add echoproof -- echoproof mcp, atau di ~/.codex/config.toml:

[mcp_servers.echoproof]
command = "echoproof"
args = ["mcp"]

Gemini CLI: gemini mcp add echoproof echoproof mcp, yang menulis .gemini/settings.json di proyek.

Integrasi Claude Code sudah diuji dari ujung ke ujung. Klien lain memakai MCP stdio standar yang sama tetapi belum diuji; laporan pemakaian sangat diterima. Asisten berbasis web seperti ChatGPT dan Claude.ai tidak dapat memakai Echoproof, karena berjalan di server penyedianya dan tidak dapat menjangkau build di komputer Anda.

Echoproof terdaftar di MCP Registry resmi dengan nama:

mcp-name: io.github.est57/echoproof

Tool

Alur kerja agent: mengubah kode, menjalankan build, memanggil echoproof_check dengan tugasnya sebagai intent, lalu jika hasilnya regresi, membuka contoh dengan echoproof_exchange, memperbaiki kode, dan memeriksa ulang. Server sengaja tidak menyediakan accept, karena menyetujui baseline baru tetap keputusan manusia.

Keamanan dan privasi

Data yang direkam

• Header dan field yang terdaftar di [sanitize] disamarkan menjadi [REDACTED] sebelum ditulis ke disk. Tambahkan field yang memuat data pribadi di domain Anda, misalnya nomor telepon, email, atau nomor identitas.
• Snapshot berisi data bisnis. Simpan di luar repository publik atau pastikan masuk .gitignore.

Data yang dikirim ke Anthropic saat memakai --intent

Teks niat, diff kode (jika diberikan), nama endpoint dan field, jumlah request yang terdampak, serta contoh body request dan nilai sebelum dan sesudah, setelah disamarkan. Body contoh di atas 4.000 karakter dipotong. Tidak ada data yang dikirim jika --intent tidak dipakai.

Pengaman bawaan

• Request tulis tidak di-replay tanpa izin eksplisit per endpoint.
• Path dari snapshot divalidasi agar request dan kredensial yang disisipkan tidak dapat diarahkan ke host lain.
• Response dibatasi 32 MB.
• API key hanya dikirim melalui https, kecuali ke localhost.
• Teks dari luar (niat, diff, traffic) tidak dapat mengubah struktur prompt penilai, dan tidak dapat merusak tabel di laporan Markdown.

Pengaman untuk coding agent (MCP)

• target dan base hanya boleh localhost, kecuali host didaftarkan di [mcp] allowed_hosts. Replay membawa header dari replay.headers, sehingga agent tidak boleh dapat mengirimnya ke host lain.
• Path file (snapshot, save, code_diff_file) harus berada di dalam folder proyek. Symlink ke luar folder ditolak.
• Perintah reset hanya dibaca dari echoproof.toml, tidak pernah dari agent.

Batasan

• Request tulis membutuhkan lingkungan uji yang dapat di-reset. Tanpa itu, gunakan mode aman, yang hanya memverifikasi request baca.
• Panggilan ke pihak ketiga baru di-mock untuk aplikasi Laravel yang memakai klien Http, lewat echoproof/laravel. SDK dengan klien HTTP sendiri, bahasa lain, dan dependency non-HTTP (SMTP, antrean) masih dipanggil sungguhan saat replay.
• ID antar-request belum dipetakan. Request rekaman seperti GET /orders/123 mungkin merujuk data yang tidak ada di lingkungan uji.
• Urutan request dijaga dengan replay berurutan (concurrency = 1). Traffic besar bisa lambat, dan replay paralel hanya aman untuk endpoint tanpa state.
• Perubahan yang seharusnya terjadi tetapi tidak terjadi sulit dideteksi, karena Echoproof melaporkan request yang berubah.
• Noise yang jarang muncul dapat lolos dari satu run pembelajaran. Naikkan --noise-runs atau tambahkan pola ignore bila perlu.

Pengembangan

Struktur repository

crates/echoproof-core     format snapshot, sanitasi, diff, laporan, penilaian niat
crates/echoproof-cli      binary `echoproof`: perekam, replay, CLI, server MCP
examples/demo-shop     backend POS untuk demo dan eval
eval/judge             eval penilai niat: kasus uji, runner, dan grader
scripts/demo.sh        demo end-to-end

Menjalankan tes

cargo test
cargo clippy --all-targets -- -D warnings

Eval penilai niat

eval/judge berisi 26 skenario PR berlabel (54 kelompok perubahan) yang mengukur seberapa akurat penilai membedakan perubahan yang diniatkan dari regresi. Pada konfigurasi default, penilai mencatat 100% gate benar pada 78 run, tanpa false alarm. Skenario saat ini sudah tidak cukup sulit untuk membedakan konfigurasi yang lebih baik, sehingga kasus dari sistem nyata sedang ditambahkan. Daftar kasus ada di eval/judge/CASES.md.

eval/judge/prepare.sh                                                         # buat fixture, tanpa biaya API
node eval/judge/run-eval.mjs --flow eval/judge/runs/intent-judge --variant baseline --reps 3
node eval/judge/summarize.mjs eval/judge/runs/intent-judge/baseline

Runner menolak berjalan sampai harness disetujui sekali dengan --approve-harness, dan meminta persetujuan ulang setiap kali kode runner, kasus, atau penilai berubah.

Lisensi

Echoproof dilisensikan di bawah salah satu dari dua lisensi berikut, sesuai pilihan Anda:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

Kecuali dinyatakan lain, setiap kontribusi yang Anda kirimkan untuk disertakan dalam proyek ini dilisensikan ganda dengan cara yang sama, tanpa syarat tambahan.