lapeh 2.2.2 → 2.2.3

package/doc/GETTING_STARTED.md

@@ -0,0 +1,108 @@
+# Getting Started with Lapeh Framework
+
+Selamat datang di dokumentasi resmi **Lapeh Framework**. Panduan ini akan membantu Anda memulai instalasi, konfigurasi, dan pemahaman dasar tentang struktur proyek.
+
+## Persyaratan Sistem
+
+Sebelum memulai, pastikan sistem Anda memenuhi persyaratan berikut:
+
+- **Node.js**: Versi 18.x atau lebih baru.
+- **Database**: PostgreSQL (Recommended) atau MySQL/MariaDB.
+- **Package Manager**: NPM (bawaan Node.js).
+
+## Instalasi
+
+Cara termudah untuk memulai adalah menggunakan CLI generator `npx`.
+
+### 1. Buat Project Baru
+
+Jalankan perintah berikut di terminal Anda:
+
+```bash
+npx lapeh@latest nama-project-anda
+```
+
+Atau untuk setup lengkap (dengan data dummy user & role):
+
+```bash
+npx lapeh@latest nama-project-anda --full
+```
+
+### 2. Setup Awal
+
+Setelah project dibuat, masuk ke direktori project dan jalankan setup wizard:
+
+```bash
+cd nama-project-anda
+npm run first
+```
+
+Script ini akan melakukan hal-hal berikut secara otomatis:
+
+1.  Menyalin `.env.example` ke `.env`.
+2.  Menginstall semua dependency (`npm install`).
+3.  Membuat **JWT Secret** yang aman.
+4.  Menjalankan migrasi database (membuat tabel).
+5.  Menjalankan seeder (mengisi data awal).
+
+### 3. Jalankan Server Development
+
+```bash
+npm run dev
+```
+
+Server akan berjalan di `http://localhost:4000` (atau port yang Anda tentukan di `.env`).
+
+## Struktur Direktori
+
+Berikut adalah struktur folder standar Lapeh Framework:
+
+```
+my-app/
+├── bin/                  # Script CLI untuk npx
+├── doc/                  # Dokumentasi proyek
+├── prisma/               # Konfigurasi Database & Schema
+│   ├── migrations/       # File history migrasi database
+│   ├── base.prisma.template # Template konfigurasi database
+│   ├── schema.prisma     # File schema gabungan (Auto-generated)
+│   └── seed.ts           # Script untuk mengisi data awal
+├── scripts/              # Script utility (Generator, Compiler)
+├── src/                  # Source code utama aplikasi
+│   ├── controllers/      # Logika bisnis (Handler request)
+│   ├── core/             # Konfigurasi inti (DB, Redis, Server)
+│   ├── middleware/       # Middleware Express (Auth, RateLimit)
+│   ├── models/           # Definisi Schema Prisma per-fitur
+│   ├── routes/           # Definisi routing API
+│   ├── utils/            # Helper function (Response, Validator)
+│   └── index.ts          # Entry point aplikasi
+├── .env                  # Variabel lingkungan (Rahasia)
+├── package.json          # Dependensi & Script NPM
+└── tsconfig.json         # Konfigurasi TypeScript
+```
+
+## Konfigurasi Environment (.env)
+
+File `.env` menyimpan konfigurasi penting. Berikut adalah variabel kunci:
+
+```ini
+# Server
+PORT=4000
+NODE_ENV=development
+
+# Database (Ganti sesuai kredensial Anda)
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"
+
+# Security
+JWT_SECRET="rahasia-super-panjang-dan-acak"
+ACCESS_TOKEN_EXPIRES_IN=3600 # 1 jam
+
+# Redis (Opsional - otomatis mock jika tidak ada)
+REDIS_URL="redis://localhost:6379"
+NO_REDIS=false # Set true untuk memaksa mode mock
+```
+
+## Langkah Selanjutnya
+
+- Pelajari cara menggunakan **[CLI Tools](CLI.md)** untuk mempercepat development.
+- Pahami **[Fitur & Konsep Inti](FEATURES.md)** framework.
+- Ikuti **[Tutorial Studi Kasus](TUTORIAL.md)** untuk membangun fitur nyata.

package/doc/INTRODUCTION.md

@@ -0,0 +1,60 @@
+# Pengenalan Lapeh Framework
+
+## Apa itu Lapeh?
+
+**Lapeh** adalah framework Backend untuk Node.js yang dibangun di atas **Express** dan **TypeScript**.
+
+Jika Anda pernah menggunakan **Laravel** (PHP) atau **NestJS** (Node.js), Anda akan merasa sangat familiar. Lapeh mengambil filosofi kemudahan & struktur rapi dari Laravel, namun tetap mempertahankan fleksibilitas dan kecepatan Express.
+
+Nama "Lapeh" diambil dari bahasa Minang yang berarti "Lepas" atau "Bebas", melambangkan kebebasan developer untuk membangun aplikasi dengan cepat tanpa terbebani konfigurasi yang rumit.
+
+## Mengapa Lapeh Dibuat?
+
+Di ekosistem Node.js, developer sering mengalami "Decision Fatigue" (Kelelahan memilih):
+- "Pakai ORM apa? Prisma, TypeORM, atau Drizzle?"
+- "Validasi pakai Joi, Zod, atau express-validator?"
+- "Struktur foldernya gimana? MVC? Clean Architecture?"
+- "Auth-nya gimana?"
+
+Lapeh menjawab semua itu dengan **Opinionated Defaults**:
+1.  **ORM**: Prisma (Standar industri saat ini).
+2.  **Validasi**: Zod (dengan wrapper syntax ala Laravel).
+3.  **Struktur**: MVC Modular (Controller, Model, Route terpisah tapi kohesif).
+4.  **Auth**: JWT + RBAC (Role Based Access Control) siap pakai.
+
+## Perbandingan dengan Framework Lain
+
+| Fitur | Express (Raw) | NestJS | Lapeh Framework |
+| :--- | :--- | :--- | :--- |
+| **Learning Curve** | Rendah (tapi bingung struktur) | Tinggi (Angular-style, Decorators) | **Sedang** (Express + Struktur Jelas) |
+| **Boilerplate** | Kosong | Sangat Banyak | **Pas (Ready to use)** |
+| **Type Safety** | Manual | Strict | **Strict (TypeScript Native)** |
+| **Kecepatan Dev** | Lambat (setup manual) | Sedang | **Cepat (CLI Generator)** |
+| **Fleksibilitas** | Sangat Tinggi | Kaku | **Tinggi** |
+
+## Filosofi "The Lapeh Way"
+
+1.  **Developer Experience (DX) First**: CLI tools, error message yang jelas, dan hot-reload adalah prioritas.
+2.  **Performance by Default**: Serialisasi JSON cepat (Fastify-style) dan Redis caching terintegrasi.
+3.  **Explicit is Better than Implicit**: Tidak ada "sihir" yang terlalu gelap. Kode controller Anda adalah kode Express biasa yang Anda mengerti.
+4.  **Production Ready**: Security (Helmet, Rate Limit) dan Scalability (Docker, Cluster) bukan pikiran belakangan, tapi bawaan.
+
+## Siklus Hidup Request (Request Lifecycle)
+
+Bagaimana Lapeh menangani satu permintaan dari user?
+
+1.  **Request Masuk** (`GET /api/users`)
+2.  **Security Middleware**: Helmet (Headers), CORS, Rate Limiter.
+3.  **Global Middleware**: Request Logger, Body Parser (JSON).
+4.  **Routing**: Mencocokkan URL di `src/routes/`.
+5.  **Auth Middleware** (Opsional): Cek token JWT & Role.
+6.  **Validator** (Opsional): Validasi input body/query.
+7.  **Controller**: Logika bisnis utama dijalankan.
+    - Panggil Database (Prisma).
+    - Panggil Cache (Redis).
+8.  **Serializer**: Data diformat & disanitasi (misal: hide password).
+9.  **Response**: JSON dikirim kembali ke user.
+
+---
+
+**Selanjutnya:** Pelajari struktur folder di [Struktur Proyek](STRUCTURE.md).

package/doc/PACKAGES.md

@@ -0,0 +1,66 @@
+# Referensi Package & Dependencies
+
+Dokumen ini menjelaskan fungsi dari setiap library (package) yang terinstall di Lapeh Framework, sehingga Anda mengerti kegunaan "alat-alat" yang ada di dalam kotak peralatan Anda.
+
+## Core Framework (Fondasi)
+
+Package-package ini adalah nyawa dari framework ini.
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`express`** | Web Framework untuk Node.js. | Standar industri, ringan, dan komunitasnya terbesar. |
+| **`dotenv`** | Memuat variabel dari file `.env`. | Agar konfigurasi rahasia (DB password, API Key) tidak di-hardcode. |
+| **`cors`** | Cross-Origin Resource Sharing. | Mengizinkan frontend (React/Vue) dari domain berbeda untuk mengakses API kita. |
+| **`helmet`** | Middleware keamanan HTTP headers. | Melindungi aplikasi dari serangan umum (XSS, Clickjacking) dengan mengatur header HTTP secara otomatis. |
+
+## Database & ORM
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`@prisma/client`** | Query builder & ORM. | Type-safe query database. Autocomplete-nya sangat membantu developer. |
+| **`pg`** | Driver PostgreSQL. | Driver native untuk koneksi ke database Postgres. |
+| **`@prisma/adapter-*`** | Adapter serverless. | (Opsional) Persiapan untuk deployment ke environment serverless (seperti Vercel/Neon). |
+
+## Authentication & Security
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`jsonwebtoken`** | Implementasi JWT. | Standar token untuk autentikasi stateless (API). |
+| **`bcryptjs`** | Hashing password. | Mengamankan password user di database (satu arah). |
+| **`express-rate-limit`** | Pembatas request. | Mencegah serangan DDoS ringan atau Brute Force login. |
+
+## Utilities & Helper
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`zod`** | Schema validation library. | Memvalidasi input user (req.body) dengan syntax yang kuat dan mudah dibaca. |
+| **`fast-json-stringify`** | Serializer JSON cepat. | Mengubah object ke JSON string 2x-3x lebih cepat dari `JSON.stringify` bawaan. |
+| **`uuid`** | Generator ID unik. | Membuat string acak unik (UUID v4). |
+| **`slugify`** | String formatter. | Mengubah "Judul Artikel Keren" menjadi `judul-artikel-keren` (URL friendly). |
+| **`multer`** | Middleware upload file. | Menangani `multipart/form-data` untuk upload gambar/dokumen. |
+| **`winston`** | Logger library. | Mencatat log aplikasi (error/info) ke file atau console dengan format rapi. |
+
+## Realtime & Caching
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`socket.io`** | Library WebSocket. | Fitur komunikasi real-time dua arah (chat, notifikasi live). |
+| **`ioredis`** | Client Redis yang robust. | Driver terbaik untuk Redis di Node.js. |
+| **`ioredis-mock`** | Simulasi Redis di memori. | Memungkinkan development tanpa perlu install Redis server asli (sangat berguna untuk pemula). |
+
+## Development Tools (DevDependencies)
+
+Package ini hanya dipakai saat koding, tidak ikut terinstall di server production.
+
+| Package | Deskripsi | Fungsi |
+| :--- | :--- | :--- |
+| **`typescript`** | Compiler TS. | Mengubah kode `.ts` menjadi `.js`. |
+| **`nodemon`** | Auto-restarter. | Restart server otomatis setiap kita save file. |
+| **`eslint`** | Linter (Polisi Kode). | Mencari potensi error dan variabel yang tidak terpakai. |
+| **`@types/*`** | Definisi Tipe. | Memberikan intellisense (saran kode) untuk library JavaScript biasa. |
+| **`prisma`** | Prisma CLI. | Alat untuk migrasi database (`prisma migrate`) dan generate client. |
+| **`tsc-alias`** | Path resolver. | Mengubah alias `@/core` menjadi path relatif `../core` saat build production. |
+
+---
+
+Dengan memahami daftar ini, Anda tahu persis apa yang terjadi di balik layar aplikasi Anda. Tidak ada "Bloatware", setiap package punya tujuan spesifik.

package/doc/ROADMAP.md

@@ -0,0 +1,93 @@
+# Roadmap & Future Requests (Rencana Pengembangan)
+
+Dokumen ini berisi daftar fitur yang direncanakan untuk membuat **Lapeh Framework** setara dengan framework backend enterprise lainnya (seperti NestJS, Laravel, atau Django).
+
+Ini adalah **Undangan Terbuka** bagi para kontributor! Jika Anda tertarik mengerjakan salah satu fitur di bawah ini, silakan buat Issue/PR.
+
+---
+
+## 🏗️ Core & Architecture
+
+### 1. Dependency Injection (DI) Container
+*   **Tujuan**: Membuat kode lebih testable dan modular.
+*   **Konsep**: Saat ini Lapeh menggunakan pendekatan import langsung. Implementasi DI sederhana (seperti `InversifyJS` atau custom container) akan memudahkan unit testing dan decoupling.
+*   **Inspirasi**: NestJS Providers, Angular DI.
+
+### 2. Event Emitter (Pub/Sub)
+*   **Tujuan**: Decoupling logic antar modul.
+*   **Contoh**: Saat user register -> Emit event `UserRegistered` -> Listener `SendWelcomeEmail` & `CreateWallet` berjalan terpisah.
+*   **Status**: Belum ada (bisa pakai `eventemitter3`).
+
+### 3. API Documentation Generator (Swagger/OpenAPI)
+*   **Tujuan**: Auto-generate dokumentasi API interaktif.
+*   **Rencana**: Membaca file route dan validator schema, lalu men-generate spesifikasi Swagger UI secara otomatis di `/api/docs`.
+
+---
+
+## 🛠️ Fitur Enterprise (The "Missing" Parts)
+
+### 4. Job Queues & Background Workers
+*   **Tujuan**: Memproses tugas berat di background agar tidak memblokir HTTP request.
+*   **Teknologi**: Integrasi dengan **BullMQ** (Redis).
+*   **Fitur**:
+    *   Decorators/Helpers untuk mendefinisikan Job.
+    *   Dashboard monitoring job (seperti Horizon di Laravel).
+    *   Retry mechanism & Failed job handling.
+
+### 5. Task Scheduling (Cron Jobs)
+*   **Tujuan**: Menjalankan tugas berkala (misal: "Kirim rekap email setiap jam 12 malam").
+*   **Rencana**: Wrapper di atas `node-cron` yang terintegrasi dengan struktur framework.
+*   **CLI**: `npm run schedule:run`.
+
+### 6. Storage Abstraction Layer
+*   **Tujuan**: Satu interface untuk upload file ke berbagai provider (Local, AWS S3, Google Cloud Storage, MinIO).
+*   **Konsep**:
+    ```typescript
+    // Tidak peduli drivernya apa, kodenya sama:
+    await Storage.disk('s3').put('avatars/1.jpg', fileBuffer);
+    ```
+
+### 7. Mailer Service
+*   **Tujuan**: Standarisasi pengiriman email.
+*   **Fitur**:
+    *   Support SMTP, Mailgun, SES.
+    *   Support Template Engine (Handlebars/EJS) untuk body email.
+    *   Queue integration (kirim email di background).
+
+---
+
+## 🧪 Testing & Quality Assurance
+
+### 8. Native Testing Suite
+*   **Tujuan**: Memudahkan user menulis test.
+*   **Rencana**:
+    *   Integrasi **Vitest** atau **Jest** pre-configured.
+    *   Helper untuk HTTP Testing (supertest wrapper).
+    *   Helper untuk Database Transaction (rollback setelah test selesai).
+    *   Command: `npm run test`, `npm run make:test`.
+
+---
+
+## 🌐 Globalization & Security
+
+### 9. Localization (i18n)
+*   **Tujuan**: Mendukung respon API dalam berbagai bahasa.
+*   **Fitur**: Mendeteksi header `Accept-Language` dan mengembalikan pesan error/success sesuai bahasa user.
+
+### 10. API Versioning
+*   **Tujuan**: Mendukung multiple versi API (v1, v2) tanpa merusak klien lama.
+*   **Rencana**: Routing strategy berbasis URL prefix (`/api/v1/...`) atau Header.
+
+---
+
+## 💻 CLI Enhancements
+
+### 11. Interactive CLI (TUI)
+*   **Tujuan**: Membuat CLI lebih user friendly.
+*   **Ide**: Saat menjalankan `npx lapeh`, muncul menu interaktif untuk memilih fitur yang mau diinstall (pilih DB, pilih mau pakai Redis atau tidak, dll).
+
+---
+
+## Tertarik Berkontribusi?
+
+Pilih salah satu topik di atas, buat Issue di GitHub dengan judul `[Proposal] Nama Fitur`, dan mari kita diskusikan cara implementasinya! 🚀

package/doc/SECURITY.md

@@ -0,0 +1,93 @@
+# Security Best Practices (Panduan Keamanan)
+
+Keamanan bukan fitur tambahan, melainkan prioritas utama. Lapeh Framework sudah dikonfigurasi dengan standar keamanan yang baik (Secure by Default), namun Anda tetap perlu memahami cara menjaga aplikasi tetap aman.
+
+## 1. Perlindungan Bawaan (Built-in Protection)
+
+Secara default, Lapeh sudah mengaktifkan:
+
+### Helmet (HTTP Headers)
+
+Mengamankan aplikasi dari serangan umum web vulnerabilities dengan mengatur HTTP headers yang tepat.
+
+- **XSS Filter**: Aktif.
+- **Frameguard**: Mencegah Clickjacking.
+- **HSTS**: Memaksa browser menggunakan HTTPS (di production).
+
+### Rate Limiting
+
+Mencegah serangan _Brute Force_ dan _DDoS_ sederhana.
+
+- **Default**: 100 request per 15 menit per IP.
+- **Lokasi Config**: `src/middleware/rateLimit.ts`.
+
+### CORS (Cross-Origin Resource Sharing)
+
+Mengontrol domain mana yang boleh mengakses API Anda.
+
+- **Lokasi Config**: `src/core/server.ts`.
+- **Saran**: Di production, ubah `origin: "*"` menjadi domain frontend spesifik Anda (misal `origin: "https://frontend-anda.com"`).
+
+## 2. Praktik Terbaik Developer
+
+Framework tidak bisa melindungi dari kode yang buruk. Berikut hal yang WAJIB Anda lakukan:
+
+### a. Validasi Input (Wajib!)
+
+Jangan pernah mempercayai input user. Selalu gunakan `Validator`.
+
+**❌ Tidak Aman (Raw Query):**
+
+```typescript
+// Bahaya SQL Injection jika pakai raw query manual (walau Prisma aman, tetap hati-hati)
+const user =
+  await prisma.$queryRaw`SELECT * FROM users WHERE email = ${req.body.email}`;
+```
+
+**✅ Aman (Validator + Prisma Client):**
+
+```typescript
+const valid = await Validator.make(req.body, { email: "required|email" });
+// Prisma Client otomatis sanitize input
+const user = await prisma.user.findUnique({
+  where: { email: valid.validated().email },
+});
+```
+
+### b. Manajemen Password
+
+- **Hashing**: Jangan pernah simpan password plain text. Gunakan `bcryptjs` (sudah terintegrasi di AuthController).
+- **Strength**: Validasi password minimal 8 karakter.
+  ```typescript
+  password: "required|string|min:8";
+  ```
+
+### c. JWT & Session
+
+- **Secret Key**: Pastikan `JWT_SECRET` di `.env` adalah string acak yang panjang (32+ karakter).
+- **Expiration**: Token akses (`ACCESS_TOKEN_EXPIRES_IN`) sebaiknya pendek (misal 15 menit - 1 jam). Gunakan Refresh Token (fitur roadmap) untuk sesi panjang.
+
+### d. Error Handling
+
+Jangan pernah mengekspos detail error sistem (stack trace) ke user di Production.
+
+**❌ Buruk:**
+
+```typescript
+res.status(500).json({ error: err.message, stack: err.stack }); // Hacker bisa lihat struktur folder server
+```
+
+**✅ Aman (Lapeh Default):**
+Lapeh sudah menangani ini. Di mode `production`, error internal hanya akan menampilkan "Internal Server Error" tanpa detail sensitif.
+
+## 3. Checklist Sebelum Deploy
+
+- [ ] Pastikan `NODE_ENV=production` di server.
+- [ ] Ganti `JWT_SECRET` default dengan yang baru (`npm run generate:jwt`).
+- [ ] Batasi CORS origin hanya ke domain frontend Anda.
+- [ ] Pastikan database tidak bisa diakses publik (gunakan firewall/private IP).
+- [ ] Gunakan HTTPS (SSL/TLS). API tanpa HTTPS sangat mudah disadap.
+
+## 4. Melaporkan Celah Keamanan
+
+Jika Anda menemukan celah keamanan di framework ini, mohon **JANGAN** buat Issue publik. Kirim email langsung ke maintainer (lihat `package.json`) agar bisa diperbaiki (patched) sebelum diexploitasi orang jahat.

package/doc/STRUCTURE.md

@@ -0,0 +1,72 @@
+# Bedah Struktur Proyek
+
+Untuk memahami Lapeh Framework sepenuhnya, Anda perlu tahu apa fungsi setiap file dan folder. Berikut adalah "Tour" lengkap ke dalam direktori proyek.
+
+## Root Directory
+
+| File/Folder | Deskripsi |
+| :--- | :--- |
+| `bin/` | Berisi script eksekusi untuk CLI (`npx lapeh`). Anda jarang menyentuh ini. |
+| `doc/` | Dokumentasi proyek ini berada. |
+| `prisma/` | Jantung konfigurasi Database. |
+| `scripts/` | Kumpulan script Node.js untuk utility (generator, compiler schema, dll). |
+| `src/` | **Source Code Utama**. 99% kodingan Anda ada di sini. |
+| `.env` | Variabel rahasia (Database URL, API Keys). **Jangan commit file ini ke Git!** |
+| `docker-compose.yml` | Konfigurasi Docker untuk menjalankan Database & Redis lokal. |
+| `nodemon.json` | Konfigurasi auto-restart saat development. |
+| `package.json` | Daftar library (dependencies) dan perintah (`npm run ...`). |
+| `tsconfig.json` | Konfigurasi TypeScript. |
+
+## Folder `src/` (Source Code)
+
+Ini adalah tempat Anda bekerja setiap hari.
+
+### `src/controllers/`
+Berisi logika aplikasi. Controller menerima Request, memprosesnya, dan mengembalikan Response.
+- **Contoh**: `authController.ts` menangani login/register.
+- **Tips**: Jangan taruh *business logic* yang terlalu kompleks di sini. Gunakan Service (opsional) jika controller sudah terlalu gemuk.
+
+### `src/models/`
+Berisi definisi tabel database (Schema Prisma).
+- **Unik di Lapeh**: Kami memecah `schema.prisma` yang besar menjadi file-file kecil per fitur (misal `user.prisma`, `product.prisma`) agar mudah di-manage. Script `prisma:migrate` akan menggabungkannya nanti.
+
+### `src/routes/`
+Mendefinisikan URL endpoint.
+- Menghubungkan URL (misal `/api/login`) ke fungsi di Controller.
+- Menempelkan Middleware (misal `requireAuth`).
+
+### `src/middleware/`
+Kode yang berjalan *sebelum* Controller.
+- `auth.ts`: Cek JWT Token.
+- `rateLimit.ts`: Batasi jumlah request.
+- `requestLogger.ts`: Log setiap request yang masuk.
+
+### `src/utils/`
+Fungsi bantuan (Helper) yang bisa dipakai di mana saja.
+- `validator.ts`: Validasi input ala Laravel.
+- `response.ts`: Standar format JSON response (`sendSuccess`, `sendError`).
+- `logger.ts`: Sistem logging (Winston).
+
+### `src/core/`
+Bagian "Mesin" framework. Anda jarang perlu mengubah ini kecuali ingin memodifikasi behavior dasar framework.
+- `server.ts`: Setup Express App.
+- `database.ts`: Instance Prisma Client.
+- `redis.ts`: Koneksi Redis.
+- `serializer.ts`: Logic caching JSON Schema.
+
+## Folder `prisma/`
+
+- `migrations/`: History perubahan database (SQL file). Jangan diedit manual.
+- `base.prisma.template`: Header dari schema database (berisi konfigurasi datasource db).
+- `seed.ts`: Script untuk mengisi data awal (Data Seeding).
+
+## Folder `scripts/`
+
+Script-script "Magic" yang dijalankan `npm run`.
+- `make-controller.js`: Generator controller.
+- `compile-schema.js`: Penggabung file `.prisma`.
+- `init-project.js`: Wizard setup awal.
+
+---
+
+Dengan memahami struktur ini, Anda tidak akan tersesat saat ingin menambah fitur baru atau mencari bug.

package/doc/TUTORIAL.md

@@ -0,0 +1,192 @@
+# Tutorial: Membangun API Perpustakaan
+
+Dalam tutorial ini, kita akan membangun fitur "Manajemen Buku" sederhana menggunakan semua fitur unggulan Lapeh Framework:
+1.  **CLI** untuk generate kode.
+2.  **Validator** untuk validasi input.
+3.  **Fast Serialization** untuk respon cepat.
+4.  **RBAC** untuk proteksi delete (Admin only).
+
+## Langkah 1: Generate Model Database
+
+Kita butuh tabel `books`. Gunakan CLI `make:model`.
+
+```bash
+npm run make:model Book
+```
+
+File baru akan muncul di `src/models/book.prisma`. Edit file tersebut:
+
+```prisma
+// src/models/book.prisma
+
+model Book {
+  id          BigInt   @id @default(autoincrement())
+  title       String
+  author      String
+  isbn        String   @unique
+  publishedAt DateTime
+  stock       Int      @default(0)
+  created_at  DateTime @default(now())
+  updated_at  DateTime @updatedAt
+
+  @@map("books")
+}
+```
+
+Terapkan perubahan ke database:
+
+```bash
+npm run prisma:migrate
+```
+
+## Langkah 2: Generate Module (Controller & Route)
+
+Kita buat controller dan route sekaligus.
+
+```bash
+npm run make:module Book
+```
+
+Framework akan membuat:
+- `src/controllers/bookController.ts`
+- `src/routes/book.ts`
+
+## Langkah 3: Implementasi Controller
+
+Buka `src/controllers/bookController.ts` dan kita implementasikan fitur **Create** dan **List** dengan standar framework.
+
+### Setup Import & Serializer
+
+```typescript
+import { Request, Response } from "express";
+import { prisma } from "@/core/database";
+import { sendFastSuccess, sendError } from "@/utils/response";
+import { Validator } from "@/utils/validator";
+import { getSerializer, createResponseSchema } from "@/core/serializer";
+
+// 1. Definisikan Schema Output (untuk Fastify Serialization)
+const bookSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" }, // BigInt -> String
+    title: { type: "string" },
+    author: { type: "string" },
+    isbn: { type: "string" },
+    stock: { type: "number" }
+  }
+};
+
+// 2. Buat Serializer
+const bookDetailSerializer = getSerializer("book-detail", createResponseSchema(bookSchema));
+const bookListSerializer = getSerializer("book-list", createResponseSchema({
+  type: "array",
+  items: bookSchema
+}));
+```
+
+### Implementasi Create (dengan Validasi)
+
+```typescript
+export async function createBook(req: Request, res: Response) {
+  // 1. Validasi Input
+  const validator = await Validator.make(req.body, {
+    title: "required|string|min:3",
+    author: "required|string",
+    isbn: "required|string|unique:books,isbn", // Cek unik di tabel books
+    stock: "required|number|min:1",
+    publishedAt: "required|string" // Format tanggal ISO
+  });
+
+  if (validator.fails()) {
+    return sendError(res, 400, "Validation Error", validator.errors());
+  }
+
+  const data = validator.validated();
+
+  // 2. Simpan ke Database
+  const book = await prisma.book.create({
+    data: {
+      title: data.title,
+      author: data.author,
+      isbn: data.isbn,
+      stock: data.stock,
+      publishedAt: new Date(data.publishedAt)
+    }
+  });
+
+  // 3. Return Response Cepat
+  return sendFastSuccess(res, 201, bookDetailSerializer, {
+    status: "success",
+    message: "Buku berhasil ditambahkan",
+    data: { ...book, id: book.id.toString() } // Konversi BigInt manual jika perlu
+  });
+}
+```
+
+### Implementasi List (High Performance)
+
+```typescript
+export async function getBooks(req: Request, res: Response) {
+  const books = await prisma.book.findMany({
+    take: 50, // Limit 50
+    orderBy: { created_at: "desc" }
+  });
+
+  // Convert BigInt to string sebelum passing ke serializer (opsional, tapi aman)
+  const safeBooks = books.map(b => ({ ...b, id: b.id.toString() }));
+
+  return sendFastSuccess(res, 200, bookListSerializer, {
+    status: "success",
+    message: "Daftar buku",
+    data: safeBooks
+  });
+}
+```
+
+## Langkah 4: Daftarkan Route & Proteksi
+
+Buka `src/routes/book.ts` (atau file yang digenerate). Pastikan route terhubung dan tambahkan middleware auth.
+
+```typescript
+import { Router } from "express";
+import { createBook, getBooks } from "../controllers/bookController";
+import { requireAuth, requireAdmin } from "../middleware/auth";
+
+export const bookRouter = Router();
+
+// Public route (bisa diakses siapa saja)
+bookRouter.get("/", getBooks);
+
+// Admin only (Butuh login + role admin)
+bookRouter.post("/", requireAuth, requireAdmin, createBook);
+```
+
+Terakhir, daftarkan router ini di `src/routes/index.ts` (jika belum otomatis):
+
+```typescript
+import { bookRouter } from "./book";
+// ...
+router.use("/books", bookRouter);
+```
+
+## Langkah 5: Testing
+
+Jalankan server:
+```bash
+npm run dev
+```
+
+Coba hit endpoint:
+1. **POST /api/books** (Tanpa token) -> 401 Unauthorized.
+2. **POST /api/books** (Token User Biasa) -> 403 Forbidden.
+3. **POST /api/books** (Token Admin + Data Invalid) -> 400 Validation Error.
+4. **POST /api/books** (Token Admin + Data Valid) -> 201 Created.
+5. **GET /api/books** -> 200 OK (Super Cepat).
+
+## Kesimpulan
+
+Dengan Lapeh Framework, Anda telah membuat API yang:
+- **Aman** (Validasi, Auth, RBAC).
+- **Cepat** (Fast Serialization).
+- **Rapi** (Struktur terstandarisasi).
+- **Mudah** (CLI Generator).