@nexa-stack/framework 1.0.0

package/docs/EXAMPLES.md

@@ -0,0 +1,114 @@
+# Examples
+
+## ERP (full)
+
+See current `app.ts` in project root — 7 modules with relations and seed data.
+
+```bash
+bun run dev
+# → http://localhost:3333/admin
+```
+
+---
+
+## School (minimal)
+
+```ts
+import { start, resource, string, number, email, belongsTo } from "./packages/core/src/index.js";
+
+resource("students", {
+  name: string().required(),
+  email: email().required(),
+  age: number().required(),
+}, { label: "Students" }).admin();
+
+resource("courses", {
+  title: string().required(),
+  price: number().required(),
+}, { label: "Courses" }).admin();
+
+resource("enrollments", {
+  student: belongsTo("students").required(),
+  course: belongsTo("courses").required(),
+}, { label: "Enrollments" }).admin().auth();
+
+await start("./school.db");
+```
+
+---
+
+## Shop (minimal)
+
+```ts
+import { start, resource, string, money, getDb } from "./packages/core/src/index.js";
+
+resource("products", {
+  name: string().required(),
+  price: money().required(),
+}, { label: "Products" }).admin();
+
+resource("sales", {
+  total: money().required(),
+  items: string().required(),
+}, { label: "Sales" }).auth();
+
+await start("./shop.db");
+
+const db = getDb()!;
+if (db.findAll("products").length === 0) {
+  db.insert("products", { name: "Coffee", price: 5 });
+  db.insert("products", { name: "Tea", price: 3 });
+}
+```
+
+Cashier page: http://localhost:3333/cashier
+
+---
+
+## Warehouse (minimal)
+
+```ts
+import { start, resource, string, number, belongsTo } from "./packages/core/src/index.js";
+
+resource("items", {
+  name: string().required(),
+  sku: string().required(),
+  qty: number().required(),
+}, { label: "Items" }).admin();
+
+resource("movements", {
+  item: belongsTo("items").required(),
+  type: string().required(),
+  qty: number().required(),
+}, { label: "Movements" }).admin().auth();
+
+await start("./warehouse.db");
+```
+
+---
+
+## CRM (minimal)
+
+```ts
+import { start, resource, string, email, money, belongsTo } from "./packages/core/src/index.js";
+
+resource("leads", {
+  name: string().required(),
+  email: email().required(),
+  phone: string().required(),
+}, { label: "Leads" }).admin();
+
+resource("deals", {
+  lead: belongsTo("leads").required(),
+  amount: money().required(),
+  stage: string().required(),
+}, { label: "Deals" }).admin().auth();
+
+resource("tasks", {
+  deal: belongsTo("deals").required(),
+  note: string().required(),
+  done: boolean(),
+}, { label: "Tasks" }).admin().auth();
+
+await start("./crm.db");
+```

package/docs/FRAMEWORK.md

@@ -0,0 +1,226 @@
+# Nexa Framework Reference
+
+## Import
+
+```ts
+import {
+  start,
+  resource,
+  string,
+  number,
+  boolean,
+  text,
+  email,
+  money,
+  belongsTo,
+  hasMany,
+  file,
+  image,
+  on,
+  dispatch,
+  getDb,
+} from "./packages/core/src/index.js";
+```
+
+---
+
+## Commands (Vocabulary)
+
+### `resource(name, fields, options?)`
+
+Defines a database table + REST API.
+
+```ts
+resource("clients", {
+  name: string().required(),
+  phone: string().required(),
+  email: email(),
+}, { label: "Clients" });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Table name (plural, lowercase). API: `/api/clients` |
+| `fields` | object | Field builders (see below) |
+| `options.label` | string | Display name in admin UI |
+
+**Auto-generated:**
+- `GET    /api/{name}` — list
+- `GET    /api/{name}/:id` — get one
+- `POST   /api/{name}` — create
+- `PUT    /api/{name}/:id` — update
+- `DELETE /api/{name}/:id` — delete
+
+---
+
+### Field types
+
+| Function | Type | SQL | Example |
+|----------|------|-----|---------|
+| `string()` | text | TEXT | name, phone, status |
+| `number()` | number | REAL | age, qty, stock |
+| `money()` | money | REAL | price, total, salary |
+| `email()` | email | TEXT | email (validated) |
+| `text()` | long text | TEXT | notes, description |
+| `boolean()` | boolean | INTEGER | active, paid |
+| `belongsTo("table")` | relation | INTEGER | foreign key → `{name}_id` |
+| `hasMany("table")` | hasMany | — | loads related records (not stored) |
+| `file()` | file | TEXT | stores upload URL |
+| `image()` | image | TEXT | stores image upload URL |
+
+### Field modifiers
+
+| Modifier | Description |
+|----------|-------------|
+| `.required()` | Field is mandatory |
+| `.min(n)` | Minimum value (number) or length (string) |
+| `.max(n)` | Maximum value (number) or length (string) |
+
+```ts
+age: number().required().min(1).max(100)
+name: string().required().min(2)
+price: money().required()
+client: belongsTo("clients").required()
+```
+
+---
+
+### Chain methods
+
+| Method | Description |
+|--------|-------------|
+| `.admin()` | Show in admin UI at `/admin` |
+| `.auth(role?)` | Require login. Default role: `"admin"`. Admin role bypasses all checks |
+| `.policy(rules)` | Per-action authorization: `view`, `create`, `update`, `delete` |
+
+```ts
+resource("clients", { ... }).admin();                  // public CRUD + admin page
+resource("orders", { ... }).admin().auth();             // login required
+resource("employees", { ... }).admin().auth("admin");  // admin only
+```
+
+---
+
+### `await start(dbPath, port?)`
+
+Starts everything:
+1. Connects to database (SQLite, PostgreSQL, or MySQL/MariaDB)
+2. Creates all tables
+3. Sets up auth (login/register) + job queue
+4. Seeds admin user
+5. Starts HTTP server
+6. Serves admin UI from `public/`
+
+```ts
+await start("./app.db");       // default port 3333
+await start("./app.db", 8080); // custom port
+```
+
+**Default admin:** `admin@nexa.dev` / `123456`
+
+---
+
+## API Endpoints
+
+### Auth
+
+| Method | URL | Body | Description |
+|--------|-----|------|-------------|
+| POST | `/api/auth/login` | `{ email, password }` | Returns `{ user, token }` |
+| POST | `/api/auth/register` | `{ email, password }` | Create user |
+
+Use token: `Authorization: Bearer {token}`
+
+### Resources
+
+All resources follow REST pattern at `/api/{name}`.
+
+Response format:
+```json
+{ "data": [...], "meta": { "page": 1, "limit": 20 } }
+```
+
+Error format:
+```json
+{ "error": "message", "errors": [{ "field": "name", "message": "..." }] }
+```
+
+### Framework
+
+| Method | URL | Description |
+|--------|-----|------|-------------|
+| GET | `/api` | List all endpoints |
+| GET | `/api/schema` | Resource schemas (for admin UI) |
+| GET | `/api/dashboard` | Stats + revenue |
+
+### Pages
+
+| URL | Description |
+|-----|-------------|
+| `/admin` | Auto-generated admin panel |
+| `/cashier` | Cashier POS (if exists) |
+| `/` | Redirects to admin |
+
+---
+
+## Terminal
+
+```bash
+bun run dev              # start app.ts
+bun run our make clients # create resource file template
+bun run our test         # run tests
+bun run our migrate      # create tables only
+```
+
+---
+
+## Relations
+
+```ts
+resource("clients", { name: string().required() }, { label: "Clients" }).admin();
+
+resource("orders", {
+  client: belongsTo("clients").required(),
+  product: belongsTo("products").required(),
+  qty: number().required(),
+  total: money().required(),
+}, { label: "Orders" }).admin().auth();
+```
+
+- Creates column `client_id` referencing `clients.id`
+- API accepts `{ client: 1 }` or `{ client_id: 1 }`
+- GET responses include nested object: `{ client: { id: 1, name: "..." } }`
+- Admin UI shows dropdown for relation fields
+
+---
+
+## Seed data (optional)
+
+```ts
+await start("./app.db");
+
+const db = getDb()!;
+if (db.findAll("clients").length === 0) {
+  db.insert("clients", { name: "Al Noor Co", phone: "0501234567" });
+}
+```
+
+---
+
+## What NOT to do
+
+- Do NOT write Express/Fastify/NestJS routes
+- Do NOT write SQL manually
+- Do NOT write controllers or models
+- Do NOT install Laravel or other frameworks
+- Do NOT edit files in `packages/` unless extending the framework
+
+---
+
+## What TO do
+
+1. Edit `app.ts`
+2. Define `resource()` for each module
+3. Chain `.admin()` and `.auth()` as needed
+4. Call `await start("./my.db")`
+5. Open `/admin`

package/docs/LANGUAGE.md

@@ -0,0 +1,39 @@
+# Localization (English + Arabic)
+
+Default language is **English**.
+
+```
+lang/
+  en.json    ← default
+  ar.json    ← Arabic (optional)
+```
+
+## Labels
+
+Prefer `labelKey` for shared translations, or `.label("…")` for a fixed string:
+
+```ts
+resource("clients", {
+  name: string().required().label("Name"),
+}, { label: "Clients", labelKey: "clients" }).admin();
+```
+
+```json
+// lang/en.json
+{ "clients": "Clients", "ui": { "login": "Login" } }
+
+// lang/ar.json
+{ "clients": "العملاء", "ui": { "login": "دخول" } }
+```
+
+## Switching language
+
+Admin includes **EN / عربي** buttons.  
+API: `GET /api/schema?lang=en` or `?lang=ar`
+
+## Config
+
+```env
+APP_LOCALE=en
+# APP_LOCALE=ar
+```

package/docs/README.md

@@ -0,0 +1,7 @@
+# Nexa Docs
+
+1. **[START.md](./START.md)** — start here  
+2. **[REFERENCE.md](./REFERENCE.md)** — full API reference (developers & AI)  
+3. Everything else is optional when you need it  
+
+Default language: **English**. Arabic UI: `APP_LOCALE=ar`.

package/docs/READY.md

@@ -0,0 +1,51 @@
+# Nexa — Ready for review
+
+**Version:** 1.0.0  
+**Status:** Backend-first · Node.js · English default · publishable (`@nexa-stack/framework`)  
+**Tests:** `npm test`
+
+## Install
+
+```bash
+npm add @nexa-stack/framework
+```
+
+```ts
+import { resource, string, start, db, createClient, route } from "@nexa-stack/framework";
+```
+
+In this repo: `npm run serve`
+
+## Feature map
+
+| Area | Status | API |
+|------|--------|-----|
+| Resources | ✅ | `resource()` + `db.from()` |
+| Relations | ✅ | `belongsTo` / `hasMany` / `belongsToMany` |
+| Transactions | ✅ | `db.transaction()` |
+| Migrations | ✅ | auto ADD COLUMN + `migrate:rollback` |
+| REST API | ✅ | CRUD + `route()` |
+| Auth | ✅ | JWT · roles · reset · verify |
+| Soft deletes | ✅ | `.admin()` default |
+| Admin UI | ✅ | `/admin` (English default; Arabic optional) |
+| SQLite / PG / MySQL | ✅ | `.env` |
+| Queue | ✅ | retries · claim |
+| Notifications | ✅ | `notify` + `POST /api/notifications` |
+| Frontend bridge | ✅ thin | `createClient()` |
+| Dev Bar | ✅ | dev only |
+| npm | ✅ | `@nexa-stack/framework@1.0.0` |
+
+## Intentionally later
+
+- Full Nexa frontend UI framework  
+- whereHas / scopes / morphs  
+- Multi-tenancy, GraphQL, WebSockets  
+- Community growth  
+
+## Review
+
+1. `npm test`  
+2. `npm run serve` → `/admin`  
+3. Docs: [START](./START.md) · [REFERENCE](./REFERENCE.md)
+
+Login: `admin@nexa.dev` / `123456`

package/docs/REFERENCE.md

@@ -0,0 +1,255 @@
+# Nexa — API reference
+
+Production backend framework for **Node.js ≥ 20**.  
+Package: `@nexa-stack/framework` · CLI: `nexa` · Default locale: **English**
+
+## Install
+
+```bash
+npx @nexa-stack/framework new my-app
+cd my-app && npm install && npm run serve
+```
+
+- **CLI:** `nexa` (serve, new, make:resource, migrate, queue:work, …)  
+- **Import:** `from "@nexa-stack/framework"`  
+- **Requires:** Node.js ≥ 20  
+
+---
+
+## Core idea
+
+```ts
+import { resource, string, money, belongsTo } from "@nexa-stack/framework";
+
+resource("orders", {
+  client: belongsTo("clients").required().label("Client"),
+  total: money().required().label("Total"),
+}, { label: "Orders" }).admin();
+```
+
+One `resource` → table + REST API + admin UI.
+
+| Feature | Status |
+|---------|--------|
+| REST CRUD | ✅ |
+| Auth (JWT) | ✅ |
+| Soft delete (admin default) | ✅ |
+| Relations | belongsTo / hasMany / belongsToMany |
+| Query builder | `db.from().where().with()` |
+| Transactions | ✅ |
+| Smart migrations | ADD COLUMN auto |
+| Queue + retries | ✅ |
+| Notifications | `notify` + HTTP API |
+| Custom routes | `route()` |
+| Dev Bar | dev only |
+| i18n | `en` default · `ar` optional |
+
+---
+
+## Fields
+
+| Helper | DB | Notes |
+|--------|-----|--------|
+| `string()` | TEXT | |
+| `text()` | TEXT | long text |
+| `number()` | REAL/INT | |
+| `boolean()` | INT | API returns **true/false** |
+| `email()` | TEXT | validated |
+| `money()` | REAL | |
+| `date()` / `datetime()` | TEXT | |
+| `select([...])` | TEXT | |
+| `belongsTo("x")` | `x_id` | name the field `teacher`, not `teacher_id` |
+| `hasMany("x")` | — | |
+| `belongsToMany("x")` | pivot table | |
+| `file()` / `image()` | TEXT | URL path |
+
+Chain: `.required()` `.label("…")` `.min()` `.max()`
+
+SQL reserved names (`order`, `group`, …) throw a clear error — rename (e.g. `lesson_order`).
+
+---
+
+## REST API
+
+For `resource("products")`:
+
+| Method | URL |
+|--------|-----|
+| GET | `/api/products` |
+| GET | `/api/products/:id` |
+| POST | `/api/products` |
+| PUT | `/api/products/:id` |
+| DELETE | `/api/products/:id` |
+| POST | `/api/products/:id/restore` |
+| GET | `/api/products/export?format=csv` |
+
+List query: `?search=&sort=&order=&page=&limit=&trashed=only|with`
+
+### Notifications
+
+| Method | Path | Auth |
+|--------|------|------|
+| GET | `/api/notifications` | ✅ |
+| POST | `/api/notifications` | ✅ create (calls `notify`) |
+| POST | `/api/notifications/:id/read` | ✅ |
+| POST | `/api/notifications/read-all` | ✅ |
+
+Only **admin** may set `user_id` to notify another user.
+
+### Custom routes
+
+```ts
+import { route, start } from "@nexa-stack/framework";
+
+route("POST", "/api/checkout", async (req, user) => {
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+  return Response.json({ data: { ok: true } });
+});
+
+await start();
+```
+
+---
+
+## Query builder
+
+```ts
+import { db } from "@nexa-stack/framework";
+
+await db.from("orders").where("status", "paid").with("client").get();
+await db.transaction(async (tx) => { /* ... */ });
+```
+
+---
+
+## Auth
+
+| Endpoint | Notes |
+|----------|--------|
+| POST `/api/auth/login` | → `{ data: { user, token } }` |
+| POST `/api/auth/register` | off in production unless `AUTH_REGISTER=true` |
+| POST `/api/auth/forgot-password` | |
+| POST `/api/auth/reset-password` | |
+| POST `/api/auth/verify-email` | |
+
+`.admin()` implies auth. Use `.policy({ … })` for roles.
+
+---
+
+## Config (`.env`)
+
+```env
+PORT=3333
+APP_SECRET=change-me-in-production   # ≥32 chars in production
+APP_LOCALE=en                        # or ar
+DB_PATH=./app.db
+# DATABASE_URL=mysql://user:pass@localhost:3306/nexa
+# DATABASE_URL=postgresql://user:pass@localhost:5432/nexa
+AUTH_RATE_LIMIT=10
+RATE_LIMIT=120
+HOT_RELOAD=true                      # off in production
+```
+
+---
+
+## Localization
+
+Default UI language is **English**.
+
+```
+lang/en.json
+lang/ar.json   # optional Arabic
+```
+
+Admin: EN / عربي buttons. Schema: `/api/schema?lang=en`
+
+```env
+APP_LOCALE=en
+```
+
+---
+
+## CLI
+
+| Command | |
+|---------|---|
+| `nexa serve` | Start (hot reload in dev) |
+| `nexa new app` | New project |
+| `nexa make:resource X` | File under `resources/` |
+| `nexa migrate` | Sync tables |
+| `nexa migrate:rollback` | |
+| `nexa db:seed` | |
+| `nexa queue:work` | |
+| `nexa schedule:work` | |
+
+---
+
+## Hot reload (dev)
+
+Watches `app.ts` and `resources/*.ts`. Disabled when `NODE_ENV=production`.
+
+---
+
+## Dev Bar (dev only)
+
+Bottom toolbar on `/admin`, `/docs`, `/` — not shown in production.
+
+| Endpoint | |
+|----------|---|
+| `GET /api/dev/status` | port, resources, recent requests |
+| `GET /api/dev/routes` | route manifest |
+| `GET /dev-bar.js` | toolbar script |
+
+---
+
+## Admin / health
+
+| Path | |
+|------|---|
+| `/admin` | Admin UI |
+| `/docs` | Docs |
+| `/api/schema?lang=en` | Schema + UI strings |
+| `/health` | `{ ok: true }` |
+| `/ready` | DB check |
+
+---
+
+## Security (v0.5+)
+
+- Signed JWT (HMAC-SHA256)  
+- Mass assignment ignored for unknown fields  
+- `.admin()` requires auth  
+- Register closed in production by default  
+- Auth rate limit  
+- Strong `APP_SECRET` required in production  
+
+---
+
+## Project layout
+
+```
+app.ts
+resources/*.ts
+.env
+lang/en.json
+lang/ar.json
+public/
+database/migrations/
+database/seeders/
+schedule.ts          # optional
+```
+
+---
+
+## Checklist for testers (1.0.0)
+
+1. `npx @nexa-stack/framework new test-app && cd test-app && npm install`  
+2. Read project `README.md`  
+3. `npm run serve` → `/admin` (EN default) + `/docs`  
+4. `npx nexa make:resource products` → `/api/products` without restart  
+5. DELETE on `.admin()` resource → soft delete  
+6. `boolean()` JSON is `true`/`false`  
+7. Failed logins → 429 after threshold  
+8. Port in use → auto next port  
+9. Production without strong `APP_SECRET` → refuses to start  
+10. `package.json` has `"@nexa-stack/framework": "^1.0.x"`