# BRIEFING: Setup Talbiya dev environment + bridge ke Jarvis (Hermes)

> **Untuk: OpenCode (agent di laptop Dezz)**
> Baca seluruh dokumen ini sebelum menjalankan perintah apa pun.
> Tujuan akhir: Dezz bisa `flutter run` di HP-nya, dan **Jarvis** (Hermes di
> server terpisah) bisa menerima laporan/log dari laptop ini tanpa Dezz harus
> copy-paste manual.

---

## 0. Konteks — baca dulu, jangan skip

Ada **dua mesin** yang terlibat. Ini sumber kebingungan kalau tidak dipahami:

| | Laptop Dezz | Server Jarvis |
|---|---|---|
| OS | Windows/macOS/Linux (tanya Dezz) | Debian 13 (headless) |
| Isi | Android Studio, HP via USB, OpenCode | Flutter 3.47.7, JDK 21, SDK 36, kode master |
| Bisa lihat layar? | ya | **tidak** |
| Punya emulator? | ya (kalau ada) | **tidak** — tidak ada `/dev/kvm` |

**Kode master ada di server Jarvis**, di `/opt/data/projects/talbiya`.
Arsip sumber: `https://dl.talbiya.id/talbiya-src.zip`

Jarvis **bukan** AI di dalam Android Studio. Dia proses terpisah yang bisa:
menulis kode, menjalankan `flutter analyze` / `flutter test` / `flutter build`,
dan mengunggah hasil ke `https://dl.talbiya.id/`.
Dia **tidak bisa** melihat layar laptop atau mengendalikan IDE.

---

## 1. Tugas OpenCode — urutan kerja

Kerjakan berurutan. **Berhenti dan tanya Dezz** kalau ada yang tidak jelas
atau kalau sebuah langkah gagal dua kali.

### Langkah 1 — Verifikasi toolchain

```bash
flutter --version     # HARUS 3.47.7
java -version         # HARUS 21
flutter doctor        # "Android toolchain" harus centang hijau
```

| Tool | Versi wajib | Alasan |
|---|---|---|
| Flutter | **3.47.7** | `pubspec.lock` mengunci resolusi paket. Versi lain = error yang tidak ada di server |
| JDK | **21** | AGP 9.1.0 menolak JDK 17 ke bawah |
| Android SDK Platform | **36** | `compileSdk = 36` |
| Build-Tools | **36.0.0** | dipakai `aapt2` & `apksigner` |

Kalau Flutter belum ada / versi salah: **jangan** upgrade global. Pakai FVM atau
install 3.47.7 berdampingan, lalu set project ini memakai versi itu.
Kalau JDK salah: set `JAVA_HOME` ke JDK 21 saja, jangan ubah sistem.

### Langkah 2 — Ambil source

```bash
# dari URL (paling gampang)
curl -L -o talbiya-src.zip https://dl.talbiya.id/talbiya-src.zip
unzip talbiya-src.zip          # menghasilkan folder talbiya/
cd talbiya
flutter pub get
```

Arsip sudah bersih: tanpa `build/`, `.dart_tool/`, `dist/`, tanpa `key.properties`,
tanpa file `.jks`.

### Langkah 3 — Konfigurasi (WAJIB, kalau dilewat login tidak jalan)

```bash
cp dart_defines.example.json dart_defines.json
```

Isi `SUPABASE_ANON_KEY`. **Jangan** minta Dezz paste key di chat publik.
Ambil langsung dari server:

```bash
ssh root@187.77.127.46 \
  'cd /data/coolify/services/puuyq3hxkdqracjubshw5u56 && \
   grep ^SERVICE_SUPABASEANON_KEY= .env | cut -d= -f2-'
```

Kalau Dezz belum punya akses SSH, **tanya dia** — jangan mengarang nilai.

`GOOGLE_WEB_CLIENT_ID` sudah terisi di template, biarkan.

> `dart_defines.json` sudah masuk `.gitignore`. **Jangan pernah commit.**

### Langkah 4 — Jalankan di HP

```bash
adb devices                                  # pastikan HP terdeteksi
flutter run --release --dart-define-from-file=dart_defines.json
```

Pakai `--release`. Beberapa plugin (`geolocator`, `google_sign_in`,
`flutter_local_notifications`) berperilaku beda di debug build.

**Jangan** jalankan `flutter build apk` untuk sekarang — akan gagal karena
`android/key.properties` tidak ada (lihat Langkah 7).

### Langkah 5 — Verifikasi hasil

Yang harus terjadi saat app dibuka:

1. Icon hijau bergambar kubah + bulan sabit (**bukan** logo Flutter biru)
2. Splash hijau dengan logo + tulisan `talbiya` dan tagline
3. Splash **maksimal 3 detik**, lalu masuk welcome screen
4. Kalau gagal, muncul layar **"Gagal menyiapkan aplikasi"** + tombol "Coba lagi"
   — **bukan** diam di logo

Kalau nyangkut >5 detik di splash: itu **bug**, laporkan ke Jarvis dengan logcat.

### Langkah 6 — Pasang bridge ke Jarvis

Ini inti permintaan Dezz: supaya Jarvis bisa menerima konteks dari laptop tanpa
copy-paste. Ada **dua** bagian, keduanya butuh tindakan Dezz (karena menyangkut
kredensial). Jangan kerjakan sendiri tanpa izin dia.

#### 6a. OpenCode membaca MCP server Hermes

Hermes bisa diekspos sebagai ACP custom agent:

```bash
hermes acp --help      # cek apakah subcommand tersedia di versi ini
```

Daftarkan sebagai custom agent MCP di config OpenCode
(`~/.config/opencode/config.json` atau `opencode.json` di root project —
sesuaikan dengan versi OpenCode yang terpasang):

```json
{
  "mcp": {
    "hermes": {
      "type": "local",
      "command": ["hermes", "acp"],
      "enabled": true
    }
  }
}
```

Kalau `hermes` tidak terpasang di laptop, opsi ini batal — lanjut ke 6b.

#### 6b. Jalur yang selalu bekerja: laporan lewat file + HTTP

Karena Jarvis tidak bisa melihat layar, cara paling andal adalah **menulis
laporan ke file** lalu Dezz mengirimkannya, atau OpenCode mengunggahnya.

Buat script `tools/report.sh` di project:

```bash
#!/usr/bin/env bash
# Kumpulkan konteks debug dari laptop untuk dikirim ke Jarvis.
# Tidak mengirim otomatis — hanya membuat satu file ringkas.
set -euo pipefail
OUT="reports/$(date +%Y%m%d-%H%M%S).txt"
mkdir -p reports
{
  echo "=== flutter --version ==="; flutter --version 2>&1
  echo; echo "=== java -version ==="; java -version 2>&1
  echo; echo "=== flutter doctor ==="; flutter doctor 2>&1
  echo; echo "=== flutter analyze ==="; flutter analyze 2>&1 | tail -40
  echo; echo "=== adb devices ==="; adb devices -l 2>&1
  echo; echo "=== last crash (logcat) ==="
  adb logcat -d -v brief 2>/dev/null | grep -iE 'talbiya|flutter|AndroidRuntime' | tail -60 || echo "(no adb)"
} > "$OUT" 2>&1
echo "Wrote $OUT"
```

**Jangan** sertakan isi `dart_defines.json` atau `key.properties` di laporan.
Script di atas sudah aman.

### Langkah 7 — (Opsional) signing untuk build APK rilis

Hanya kalau Dezz minta. Butuh `android/key.properties` + `android/app/talbiya-release.jks`.
Minta lewat channel privat, **bukan** chat. Jangan buat keystore baru — APK
dengan signature berbeda tidak bisa meng-update instalasi yang sudah ada.

---

## 2. Aturan keras — jangan dilanggar

1. **Jangan pernah** commit atau menampilkan `key.properties`, `*.jks`,
   `*.keystore`, atau `dart_defines.json`.
2. **Jangan pernah** membuat keystore baru. Itu memutus rantai update Play Store.
3. **Jangan** upgrade Flutter/JDK/AGP secara global. Project ini terkunci di
   Flutter 3.47.7 / JDK 21 / AGP 9.1.0 / Gradle 9.3.1 / Kotlin 2.4.0.
4. **Jangan** mengubah `applicationId` atau `namespace`. Sudah final: `id.talbiya.id`.
5. **Jangan** menambah dependency tanpa bertanya. Setiap paket baru = risiko
   resolusi versi.
6. **Satu repo, satu agent.** Jangan buka working tree yang sama di dua editor.
7. Kalau ragu: **berhenti dan tanya Dezz.** Lebih baik lambat daripada merusak.

---

## 3. Hal teknis yang sering bikin salah

| Gejala | Penyebab nyata |
|---|---|
| `Unable to load asset` saat app jalan | asset belum terdaftar di `pubspec.yaml` |
| Splash nyangkut lama | `Supabase.initialize()` lambat / jaringan; timeout sudah 3s |
| Build gagal: `keystore not found` | `android/key.properties` tidak ada — normal di mesin baru |
| Login Google `DEVELOPER_ERROR` | SHA-1 belum terdaftar di Google Console |
| `redirect_uri_mismatch` | URI harus persis `https://api.talbiya.id/auth/v1/callback` |
| `Access blocked / app not verified` | app masih status *Testing* di Google Console; tambahkan email sebagai test user |
| APK tidak bisa update APK lama | beda signature (debug vs release) |

---

## 4. Ringkasan URL

| Item | URL |
|---|---|
| Source code (~1.3 MB) | `https://dl.talbiya.id/talbiya-src.zip` |
| APK terbaru | `https://dl.talbiya.id/Talbiya-v1.9.1.apk` |
| Backend | `https://api.talbiya.id` |
| Panduan Studio (lebih detail) | `docs/setup-android-studio.md` di dalam arsip |

---

## 5. Definisi selesai

Kerjaan OpenCode dianggap selesai kalau **semua** ini benar:

- [ ] `flutter --version` = 3.47.7
- [ ] `java -version` = 21
- [ ] `flutter pub get` sukses
- [ ] `dart_defines.json` terisi, **tidak** ter-commit
- [ ] `flutter analyze` → *No issues found*
- [ ] App terpasang di HP Dezz, splash < 3 detik
- [ ] `tools/report.sh` ada dan menghasilkan file di `reports/`

Setelah itu, **berhenti**. Jangan lanjut mengerjakan fitur baru — Jarvis yang
memegang pekerjaan fitur (web version, adhan MP3, konten doa).