hello-world

Skeleton repo untuk alur vibecoding: edit lokal -> AI agent -> commit -> Forgejo Actions (CI) -> deploy.

Repo ini sengaja dibuat minimal tapi lengkap secara gate, supaya jadi tEMPLATE yang bisa Anda salin ke project berikutnya.

---

Isi repo

src/
├── config/env.ts                    # satu-satunya tempat baca process.env (zod)
├── lib/errors.ts                    # AppError: 400/404/429/500 bisa dibedakan
├── modules/health/
│   ├── health.service.ts            # business logic, tanpa import Fastify
│   └── health.test.ts               # 5 test, termasuk kasus negatif
├── routes/health.ts                 # HTTP tipis: parse -> service -> response
└── index.ts                         # entry point + wiring + graceful shutdown
.forgejo/workflows/ci.yml            # 6 gerbang + secret scan
AGENTS.md                            # kontrak untuk AI agent
AGENTS-API.md                        # peta entrypoint untuk AI agent

---

Menjalankan

npm install
cp .env.example .env
npm run dev        # http://localhost:3000/health

Contoh respons:

{
  "status": "ok",
  "uptimeSeconds": 42,
  "version": "0.1.0-test",
  "checkedAt": "2026-01-01T00:00:00.000Z"
}

---

Gerbang (jalankan lokal SEBELUM push)

npm run lint && npm run typecheck && npm test && npm run build

Script	Fungsi	Menangkap
npm run format:check	Cek format (prettier)	Gaya kode meleset
npm run lint	ESLint + typescript-eslint, max-warn 0	any, unused, unsafe
npm run typecheck	tsc --noEmit	Salah tipe, typo nama
npm test	vitest	Logika salah
npm run build	tsc ke dist/	Yang tidak bisa dibuild

Urutan ini sengaja: murah dulu, mahal belakangan. Jangan bolak-balik.

---

Loop harian (pakai AI agent)

git switch -c feat/tambah-endpoint-user

Prompt untuk AI (pola yang benar):

Baca AGENTS.md dan AGENTS-API.md dulu.
Tambah endpoint POST /api/v1/users sesuai pola modul health yang ada.
Wajib: validasi zod, rate limit, integration test.
Jalankan: npm run lint && npm run typecheck && npm test && npm run build

Lalu review sendiri hasilnya sebelum commit:

git diff
git add -A && git commit
git push -u origin feat/tambah-endpoint-user

Buka PR di Forgejo -> CI jalan -> merge.

---

Kenapa AGENTS.md dan AGENTS-API.md dua file

• AGENTS.md = aturan (gaya, batasan, urutan kerja, format laporan)
• AGENTS-API.md = peta (task apa -> file mana yang dibuka)

Peta stopping AI dari "buka 15 file lalu menebak" jadi "buka 2 file yang tepat".

---

CI

Workflow: .forgejo/workflows/ci.yml. Di instance dev.cloudbit.net.id workflow ini sudah terdeteksi (run ci.yml #1 tercatat), tapi masih menunggu karena belum ada runner terdaftar.

Aktifkan runner (sekali saja):

1. Forgejo -> Site Administration -> Actions -> Runners
2. Create new runner -> instance Global
3. Label: ubuntu-latest, docker (harus cocok dengan runs-on di workflow)
4. Selesai -> run yang tertunda akan langsung dieksekusi

Kalau instance Anda tidak punya runner bawaan, jalankan self-hosted runner (data.forgejo.org/forgejo-runner) di server. Lihat ~/vibecoding-tutorial/README.md Bagian 6.5.

Setelah runner aktif, baca badge di tab Actions:

Hasil	Arti
Semua hijau	aman untuk merge
format:check merah	npm run format lalu commit ulang
lint merah	biasanya any atau variabel unused
typecheck merah	salah tipe / nama import
test merah	logika salah — jangan commit ulang sebelum paham
secret-scan merah	batalkan tokennya, lalu pindah ke Forgejo Secrets

---

Deploy

deploy.yml sengaja tidak disertakan di skeleton ini, karena butuh DEPLOY_HOST / DEPLOY_USER / DEPLOY_KEY yang spesifik server Anda. Lihat ~/vibecoding-tutorial/README.md Bagian 7 untuk pola lengkapnya.

Prinsipnya: server hanya menarik (git pull), tidak pernah AI menyentuh server langsung. Semua perubahan harus lewat commit yang tercatat.