lapeeh 1.0.0

package/doc/en/ROADMAP.md

@@ -0,0 +1,104 @@
+# Roadmap & Future Requests (Rencana Pengembangan)
+
+Dokumen ini berisi daftar fitur yang direncanakan untuk membuat **lapeeh 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 lapeeh 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 lapeeh`, 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/en/SECURITY.md

@@ -0,0 +1,95 @@
+# Security Best Practices (Panduan Keamanan)
+
+Keamanan bukan fitur tambahan, melainkan prioritas utama. lapeeh 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, lapeeh 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`.
+
+**❌ Insecure (Raw Query):**
+
+```typescript
+// Danger of SQL Injection if using manual raw query without sanitization
+const user = await db.query(
+  `SELECT * FROM users WHERE email = '${req.body.email}'`
+);
+```
+
+**✅ Secure (Validator + Parameterized Query):**
+
+```typescript
+const valid = await Validator.make(req.body, { email: "required|email" });
+// Use parameterized query or your preferred ORM/Query Builder
+const user = await db.users.findOne({
+  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 (lapeeh Default):**
+lapeeh sudah menangani ini. Di mode `production`, error internal hanya akan menampilkan "Internal Server Error" tanpa detail sensitif.
+**✅ Aman (Lapeeh Default):**
+Lapeeh 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/en/STRUCTURE.md

@@ -0,0 +1,79 @@
+# 🏗️ Project Structure
+
+lapeeh Framework is designed to be **intuitive**. We separate your application code (_User Space_) from the framework engine (_Core_), so you can focus on building features without being distracted by system complexity.
+
+## 🗺️ Navigation Map
+
+Here is a mental map to understand lapeeh folders:
+
+| Folder         | Icon | Function                                                                | Status          |
+| :------------- | :--: | :---------------------------------------------------------------------- | :-------------- |
+| **`src/`**     |  🏠  | **YOUR APP CODE**. You work here every day.                             | **Must Edit**   |
+| **`scripts/`** |  🤖  | **Automation Assistants**. Scripts for release, module generation, etc. | **Can Edit**    |
+| **`bin/`**     |  🚀  | **CLI Tools**. Entry point for `npx lapeeh` commands.                   | **Rarely Edit** |
+| **`lib/`**     |  ⚙️  | **Framework Engine**. Core server & database logic.                     | **DO NOT Edit** |
+
+---
+
+## 1. 🏠 Folder `src/` (User Space)
+
+This is your "home". 99% of new feature code will be written here.
+
+### `src/modules/` (Modular Architecture)
+
+lapeeh uses a **Modular** approach. One feature = One folder.
+
+- **Example**: `src/modules/Auth/` folder contains all login/register logic.
+- **Benefit**: Code is neat, easy to find, and easy to delete if the feature is no longer used.
+
+### `src/routes/`
+
+Your API gateway.
+
+- Defines URLs (e.g., `/api/users`).
+- Connects URLs to **Controllers**.
+
+### `src/config/`
+
+Application settings center.
+
+- `app.ts`: Global configuration.
+- `cors.ts`: Domain access security.
+
+---
+
+## 2. 🤖 Folder `scripts/` (Robot Assistants)
+
+Don't do boring things manually! lapeeh provides robots here:
+
+- **`release.js`**: **Super Script** for releasing new versions.
+  - ✨ Automatic version bump (package.json).
+  - 📝 **Auto-Blog**: Automatically creates release articles from Git Commit history.
+  - 🔄 **Auto-Sync**: Synchronizes documentation to the website.
+  - 🚀 Push to Git & Publish to NPM in one command.
+- **`make-module.js`**: Generator to create new module folder structures instantly.
+
+---
+
+## 3. 🚀 Folder `bin/` (CLI & Update)
+
+This folder handles `npx lapeeh` terminal commands.
+
+- Provides **Auto-Update Check** feature when you run `npm run dev`.
+- Handles `upgrade` command to sync your project with the latest lapeeh version without breaking your code.
+
+---
+
+## 4. ⚙️ Folder `lib/` (The Core)
+
+lapeeh's "Engine Room". Contains Express setup, Database connection, Logger, and basic Middleware.
+
+> ⚠️ **Warning**: Changing the contents of this folder can make the application difficult to update to the next lapeeh version.
+
+---
+
+## 📄 Other Important Files
+
+- **`.env`**: **Secret Keys**. Store DB passwords and API Keys here. (Do not upload to Git!)
+- **`package.json`**: List of your project's library "shopping list".
+- **`ecosystem.config.js`**: Ready to deploy? This file configures how the application runs on a production server (VPS) using PM2.

package/doc/en/TUTORIAL.md

@@ -0,0 +1,145 @@
+# Tutorial: Building a Library API
+
+In this tutorial, we will build a simple "Book Management" feature using lapeeh Framework's core features:
+
+1.  **CLI** for code generation.
+2.  **Validator** for input validation.
+3.  **Fast Serialization** for high-performance responses.
+
+> **Note**: This tutorial uses an in-memory array for data storage to keep things simple. lapeeh v3.0.0 is database-agnostic, so you can easily swap this with Prisma, TypeORM, or any other DB library.
+
+## Step 1: Generate Module (Controller & Route)
+
+We will create a controller and route for our Book feature.
+
+```bash
+npm run make:module Book
+```
+
+The framework will generate:
+
+- `src/controllers/bookController.ts`
+- `src/routes/book.ts`
+
+## Step 2: Implement Controller
+
+Open `src/controllers/bookController.ts` and let's implement **Create** and **List** features.
+
+### Setup Import & Data Store
+
+```typescript
+import { Request, Response } from "express";
+import { sendFastSuccess, sendError } from "@/utils/response";
+import { Validator } from "@/utils/validator";
+import { getSerializer, createResponseSchema } from "@/core/serializer";
+
+// Simple in-memory store
+interface Book {
+  id: string;
+  title: string;
+  author: string;
+  isbn: string;
+  stock: number;
+}
+const books: Book[] = [];
+
+// 1. Define Output Schema (for Fastify Serialization)
+const bookSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    title: { type: "string" },
+    author: { type: "string" },
+    isbn: { type: "string" },
+    stock: { type: "number" },
+  },
+};
+
+// 2. Create Serializer
+const bookDetailSerializer = getSerializer(
+  "book-detail",
+  createResponseSchema(bookSchema)
+);
+const bookListSerializer = getSerializer(
+  "book-list",
+  createResponseSchema({
+    type: "array",
+    items: bookSchema,
+  })
+);
+```
+
+### Implement Create (with Validation)
+
+```typescript
+export async function createBook(req: Request, res: Response) {
+  // 1. Validate Input
+  const validator = await Validator.make(req.body, {
+    title: "required|string|min:3",
+    author: "required|string",
+    isbn: "required|string",
+    stock: "required|number|min:1",
+  });
+
+  if (validator.fails()) {
+    return sendError(res, 400, "Validation Error", validator.errors());
+  }
+
+  // 2. Save Data (In-Memory)
+  const newBook: Book = {
+    id: Date.now().toString(),
+    ...validator.validated(),
+  };
+  books.push(newBook);
+
+  // 3. Send Response (Serialized)
+  return sendFastSuccess(res, bookDetailSerializer(newBook), 201);
+}
+
+export async function listBooks(req: Request, res: Response) {
+  // Return all books
+  return sendFastSuccess(res, bookListSerializer(books));
+}
+```
+
+## Step 3: Register Route
+
+Open `src/routes/book.ts`. The CLI has already generated the basic structure. We just need to connect it to our controller functions.
+
+```typescript
+import { Router } from "express";
+import { createBook, listBooks } from "../controllers/bookController";
+
+const router = Router();
+
+router.post("/", createBook);
+router.get("/", listBooks);
+
+export default router;
+```
+
+## Step 4: Test Your API
+
+Run the server:
+
+```bash
+npm run dev
+```
+
+Test with curl or Postman:
+
+**Create Book:**
+
+```bash
+curl -X POST http://localhost:8000/api/book \
+  -H "Content-Type: application/json" \
+  -d '{"title":"lapeeh Guide", "author":"Team", "isbn":"12345", "stock":10}'
+```
+
+**List Books:**
+
+```bash
+curl http://localhost:8000/api/book
+```
+
+Congratulations! You have built a fast, validated API without getting bogged down in database configuration.

package/doc/id/ARCHITECTURE_GUIDE.md

@@ -0,0 +1,76 @@
+# Panduan Arsitektur: Menuju "Framework as a Dependency" (Next.js Style)
+
+Saat ini, lapeeh menggunakan pendekatan **Boilerplate** (seperti Laravel), di mana pengguna mendapatkan seluruh kode sumber (`src/`) dan bertanggung jawab atas `express`, `driver database`, dll.
+
+Untuk mengubahnya menjadi seperti **Next.js** (di mana pengguna hanya menginstall `lapeeh` dan `package.json` mereka bersih), kita perlu mengubah arsitektur menjadi **Library**.
+
+## 1. Perbedaan Utama
+
+| Fitur            | Boilerplate (lapeeh Saat Ini)              | Library (Next.js Style)              |
+| :--------------- | :----------------------------------------- | :----------------------------------- |
+| **Instalasi**    | `git clone` / `npx create-lapeeh`          | `npm install lapeeh`                 |
+| **package.json** | Banyak dependency (`express`, `cors`, dll) | Sedikit (`lapeeh`, `react`)          |
+| **Scripts**      | Panjang (`nodemon src/index.ts`)           | Pendek (`lapeeh dev`)                |
+| **Core Code**    | Terbuka di `src/core/`                     | Tersembunyi di `node_modules/lapeeh` |
+| **Update**       | Susah (harus merge manual)                 | Mudah (`npm update lapeeh`)          |
+
+## 2. Langkah Implementasi
+
+Saya telah memulai langkah pertama dengan menambahkan **CLI Runner** di `bin/index.js`.
+
+### A. Update CLI (`bin/index.js`) ✅ (Sudah Dilakukan)
+
+Saya sudah menambahkan command `dev`, `start`, dan `build` ke dalam CLI lapeeh. Ini memungkinkan pengguna menjalankan server tanpa tahu perintah aslinya.
+
+```javascript
+// Contoh penggunaan nanti:
+"scripts": {
+  "dev": "lapeeh dev",
+  "build": "lapeeh build",
+  "start": "lapeeh start"
+}
+```
+
+### B. Struktur Project Pengguna (Target)
+
+Nantinya, project pengguna lapeeh hanya akan berisi file bisnis mereka:
+
+```text
+my-app/
+├── src/
+│   ├── controllers/
+│   ├── routes/
+│   └── models/
+├── lapeeh.config.ts  <-- Konfigurasi framework (pengganti edit core)
+└── package.json
+```
+
+Dan `package.json` mereka akan terlihat seperti ini:
+
+```json
+{
+    "lapeeh": "^2.0.0"
+  "dependencies": {
+    "@lapeeh/lapeeh": "^2.0.0"
+  },
+  "scripts": {
+    "dev": "lapeeh dev",
+    "build": "lapeeh build",
+    "start": "lapeeh start"
+  }
+}
+```
+
+### C. Apa yang Harus Dilakukan Selanjutnya?
+
+1.  **Publish Package**: Anda perlu mempublish folder framework ini ke NPM (atau private registry).
+    - Pastikan `express`, `cors`, `helmet`, dll ada di `dependencies` (bukan `devDependencies`).
+2.  **Abstraksi `src/index.ts`**:
+    - Saat ini `src/index.ts` adalah entry point yang diedit user.
+    - Ubah agar `lapeeh dev` menjalankan server internal yang **mengimpor** routes/controller user secara dinamis (seperti Next.js pages router).
+3.  **Config Loader**:
+    - Buat sistem pembacaan `lapeeh.config.ts` untuk mengatur Port, Database URL, dll tanpa mengedit kode core.
+
+## 3. Kesimpulan
+
+Perubahan yang saya lakukan di `bin/index.js` adalah fondasi untuk CLI style. Untuk mencapai "Clean package.json" sepenuhnya, Anda harus memisahkan **Framework Core** (repo ini) dengan **User Project** (repo baru yang menginstall framework ini).