Panduan Rilis Mandiri & Publikasi Cloudflare R2 Dojo

Dokumen ini adalah panduan resmi bagi maintainer proyek Dracin untuk membangun, memverifikasi, dan memublikasikan rilis produk resmi ke infrastruktur penyimpanan publik Cloudflare R2 ekosistem Dojo (dojo.cc).

---

1. Filosofi & Arsitektur Rilis Mandiri (Zero-CI)

Dalam ekosistem Dojo, pipeline rilis dirancang mandiri (self-contained), deterministik, dan dapat dieksekusi secara lokal atau dari server staging terotorisasi tanpa ketergantungan pada runner CI/CD pihak ketiga (Zero-CI).

Diagram Alur Rilis Mandiri ke Cloudflare R2:

---

2. Struktur Artefak & Kunci Kanonik R2

Artefak yang diunggah ke Cloudflare R2 mengikuti konvensi penamaan standar yang langsung kompatibel dengan pemindai membership Dojo (ScanR2Files.php):

Berkas Lokal	Kunci Kanonik Cloudflare R2	Tipe Konten	Tujuan
products/agc-dracin-{version}.zip	products/agc-dracin-{version}.zip	application/zip	Paket instalasi lengkap yang diunduh pembeli di portal member Dojo (slug: agc-dracin)
products/agc-dracin-{version}.zip.sha256	products/agc-dracin-{version}.zip.sha256	text/plain	Checksum SHA-256 untuk verifikasi integritas paket rilis

Catatan: Pipeline rilis juga mempertahankan backward-compatibility untuk format lama products/dracin-v{version}.zip.

Isi Paket Berkas ZIP Pembeli (agc-dracin-3.0.0.zip):

1. dracin-launcher-windows-amd64.exe (Launcher Windows x64)
2. dracin-launcher-darwin-amd64 (Launcher macOS Intel, izin 0755)
3. dracin-launcher-darwin-arm64 (Launcher macOS Apple Silicon M1–M4, izin 0755)
4. dracin-launcher-linux-amd64 (Launcher Linux x64, izin 0755)
5. dracin-v3.0.0.tar.gz (Arsip produksi aplikasi Laravel mandiri)
6. dracin-v3.0.0.tar.gz.sha256 (Hash verifikasi arsip aplikasi)
7. releases/dracin-v3.0.0.tar.gz (Salinan kompatibilitas ganda launcher)
8. releases/dracin-v3.0.0.tar.gz.sha256
9. SHA256SUMS (Daftar hash SHA-256 seluruh komponen)
10. PANDUAN-RINGKAS.txt (Instruksi visual membuka launcher dan mengatasi smartscreen/gatekeeper)
11. README.md & docs/guide.md (Dokumentasi lengkap)

---

3. Variabel Lingkungan & Kredensial Cloudflare R2

Modul uploader scripts/upload_r2.cjs membaca kredensial secara aman dari environment pengembang atau server rilis:

Nama Variabel Lingkungan	Nilai Fallback	Keterangan
DOJO_CF_ACCESS_KEY_ID	AWS_ACCESS_KEY_ID	Access Key ID API S3 Cloudflare R2
DOJO_CF_SECRET_ACCESS_KEY	AWS_SECRET_ACCESS_KEY	Secret Access Key API S3 Cloudflare R2
DOJO_CF_S3_API_ENDPOINT	AWS_ENDPOINT_URL / DOJO_CF_ACCOUNT_ID	S3 API endpoint URL (format: https://<account_id>.r2.cloudflarestorage.com)
DOJO_R2_BUCKET	AWS_BUCKET	Nama bucket target (standar: dojo)
AWS_DEFAULT_REGION	-	Region S3 SigV4 (standar: auto)

IMPORTANT

Jangan pernah menuliskan atau melakukan hardcode kredensial R2 di dalam skrip repositori publik maupun paket ZIP yang didistribusikan ke pembeli.

---

4. Prosedur Eksekusi Rilis Langkah demi Langkah

Langkah 1: Pengecekan Prasyarat & Pengujian Terarah

Sebelum menjalankan rilis produksi, jalankan pengujian terarah untuk memastikan seluruh komponen lulus validasi:

# Jalankan test suite terarah rilis (< 5 detik)
bash scripts/test-release.sh

Langkah 2: Simulasi Rilis (Dry-Run)

Jalankan rilis dalam mode simulasi --dry-run untuk memverifikasi kalkulasi hash, struktur ZIP, dan otentikasi AWS SigV4 tanpa mutasi disk atau storage:

bash scripts/release.sh 3.0.0 --slug agc-dracin --dry-run

Langkah 3: Eksekusi Publikasi Rilis Resmi (Live)

Setelah mode simulasi berhasil tanpa catatan error:

# Rilis versi resmi v3.0.0 dengan slug kanonik agc-dracin
bash scripts/release.sh 3.0.0 --slug agc-dracin

Skrip ini akan secara otomatis:

1. Memeriksa status git working tree bersih (100% committed).
2. Mengompilasi 4 target launcher biner (windows-amd64.exe, darwin-amd64, darwin-arm64, linux-amd64) dan tarball aplikasi Laravel siap pakai.
3. Memvalidasi tanda tangan header biner (file PE32+, Mach-O, ELF) dan memverifikasi SHA256SUMS.
4. Mengemas produk akhir products/agc-dracin-3.0.0.zip serta mengaudit nol kebocoran berkas pengembang (.git, .env, node_modules, tests).
5. Mengunggah berkas ZIP dan SHA256 ke Cloudflare R2 bucket dojo.

---

5. Penggunaan Mandiri Uploader R2 (scripts/upload_r2.cjs)

Modul scripts/upload_r2.cjs adalah skrip native Node.js tanpa dependensi eksternal (zero-dependency) yang mengimplementasikan protokol AWS Signature Version 4 (SigV4).

Sintaks Pemanggilan:

node scripts/upload_r2.cjs <berkas-lokal> [kunci-r2] [--dry-run]

Contoh Penggunaan:

# Upload berkas rilis dengan kunci eksplisit
node scripts/upload_r2.cjs products/agc-dracin-3.0.0.zip products/agc-dracin-3.0.0.zip

# Upload dengan kunci otomatis (default: products/<nama-file>)
node scripts/upload_r2.cjs products/agc-dracin-3.0.0.zip

# Pengujian dry-run (validasi autentikasi & kalkulasi SHA256 tanpa upload)
node scripts/upload_r2.cjs products/agc-dracin-3.0.0.zip --dry-run

---

6. Sinkronisasi Katalog Membership Dojo (ScanR2Files.php)

Setelah artefak rilis terunggah ke Cloudflare R2, backend Dojo akan secara otomatis mengenali dan menautkannya ke produk pembeli melalui perintah Artisan scanner:

# Jalankan scanner di server Dojo
php artisan memberships:scan-r2 --directory=products

Aturan Pencocokan Parser Dojo:

1. Pola Nama Berkas: agc-dracin-3.0.0.zip cocok dengan regex [-_]v?(\d+[\d\.]*.*)\.([a-z0-9]+)$.
2. Ekstraksi Versi: 3.0.0.
3. Ekstraksi Slug: agc-dracin (secara otomatis dicocokkan dengan model Product Dojo yang memiliki slug agc-dracin).
4. Pengambilan Catatan Rilis (Release Notes): Scanner Dojo akan otomatis mengambil catatan rilis markdown dari URL https://dracin.dojo.cc/release-notes/v3.0.0.md dan menyimpannya ke kolom notes pada database membership.

---

7. Prosedur Rollback & Pembatalan Rilis

Jika ditemukan kendala kritis pada versi rilis yang baru dipublikasikan:

1. Jalankan scripts/release.sh untuk versi patch perbaikan (misal 3.0.1).
2. Di backend Dojo, nonaktifkan rilis bermasalah melalui dashboard admin atau tinker:

   \App\Models\ProductFile::where('filename', 'agc-dracin-3.0.0.zip')->update(['is_active' => false]);

3. Pembeli akan secara otomatis mendapatkan versi patch terbaru saat mengunduh dari portal membership Dojo.