webspresso 0.0.100 → 0.0.102

package/.agents/ADMIN.md

@@ -46,6 +46,31 @@ export default defineModel({
     sortableColumns: ['name', 'price'], // Optional whitelist of sortable columns
     sortable: true,          // Set false to disable table sorting completely
     readOnly: false,         // Disable create/edit/delete actions
+    
+    // Django Admin-inspired Features:
+    inlines: [               // Parent-child relational editing (Tabular/Stacked)
+      {
+        model: 'ProductVariant',
+        foreignKey: 'product_id',
+        fields: ['sku', 'price', 'inventory'],
+        title: 'Variants',
+      },
+    ],
+    listEditable: ['price', 'status'], // Direct table row quick-edit without opening edit form
+    dateHierarchy: 'created_at',        // Period drilldown navigation (Years -> Months -> Days)
+    listFilter: ['status'],             // Faceted filtering with record counts per value
+    actions: [                          // Declarative model-level bulk operations
+      {
+        id: 'mark-active',
+        label: 'Mark as Active',
+        handler: async ({ ids, repo, db, req, user }) => {
+          for (const id of ids) {
+            await repo.update(id, { status: 'active' });
+          }
+          return { updated: ids.length };
+        },
+      },
+    ],
   },
 });
 ```
@@ -68,13 +93,31 @@ Column sortability can be configured per-column:
 The Admin SPA communicates with the backend via JSON REST endpoints:
 
 - `GET /_admin/api/models` — List all models exposed to admin with schemas & metadata.
-- `GET /_admin/api/models/:modelName/records` — List paginated records (query params: `page`, `limit`, `search`, `filter`, `sort`).
-- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details.
-- `POST /_admin/api/models/:modelName/records` — Create new record.
-- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record.
+- `GET /_admin/api/models/:modelName/records` — List paginated records (query params: `page`, `limit`, `search`, `filter`, `sort`, `year`, `month`, `day`).
+- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details (auto-loads `_inlines` if defined).
+- `POST /_admin/api/models/:modelName/records` — Create new record (syncs `_inlines` automatically).
+- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record (syncs `_inlines` updates, additions, and deletions with `_delete: true`).
 - `DELETE /_admin/api/models/:modelName/records/:id` — Delete record (soft or hard delete).
 - `POST /_admin/api/models/:modelName/records/:id/restore` — Restore soft-deleted record.
 
+### Inline Model Relational Endpoints (Django Inlines)
+- `GET /_admin/api/models/:model/records/:id/inlines/:inlineModel` — List child items belonging to parent record.
+- `POST /_admin/api/models/:model/records/:id/inlines/:inlineModel` — Create a child item attached to parent.
+- `PUT /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Update specific child item.
+- `DELETE /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Delete child item.
+
+### Fast Inline & Batch Editing (Django `list_editable`)
+- `PATCH /_admin/api/models/:model/records/:id/quick-edit` — Quickly update allowed `listEditable` columns for a single row without full form submission.
+- `PATCH /_admin/api/models/:model/records/batch-edit` — Save multiple table row edits simultaneously (`{ updates: [{ id, changes }] }`).
+
+### Date Hierarchy & Faceted Filters (Django `date_hierarchy` & `list_filter`)
+- `GET /_admin/api/models/:model/date-hierarchy` — Drilldown periods with counts (`?year=...&month=...`).
+- `GET /_admin/api/models/:model/filter-facets` — Retrieve distinct values with record counts for `listFilter` columns.
+
+### Model Actions (Django Actions)
+- `POST /_admin/api/models/:model/actions/:actionId` — Execute declarative action on selected record IDs (`{ ids: [...] }`).
+
+
 ---
 
 ## 4. Custom Pages (`registerModule` / `registerPageDir`)

package/.agents/AGENTS.md

@@ -17,6 +17,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Admin Panel (Page, Widget, Action, UI)** | [`.agents/ADMIN.md`](ADMIN.md) | `plugins/admin-panel/` |
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](AUTH.md) | `core/auth/` |
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](QUEUE.md) | `jobs/` |
+| **Decoupled Events & Signals** | [`.agents/EVENTS.md`](EVENTS.md) | `core/events/`, `listeners/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](../index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -37,7 +38,7 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 This `.agents/` customization root is organized into modular topic guides:
 
 1. **[File-Based Routing & API Routes](.agents/ROUTING.md)** — File-based page routes (`pages/`), method-suffixed API routes (`pages/api/*.get.js`, `*.post.js`), parameter brackets (`[id]`), Zod request schemas, and the strict prohibition of manual `routes/` directories or `app.get()`.
-2. **[Architecture & Structure](.agents/ARCHITECTURE.md)** — File-based routing (`pages/`), Asset Management & Versioning (`AssetManager`, `fsy.asset`), ORM models & `zdb` schemas (`core/orm`), Mithril.js Admin Panel SPA (`plugins/admin-panel`), and Plugin Ecosystem.
+2. **[Architecture & Structure](.agents/ARCHITECTURE.md)** — File-based routing (`pages/`), Cold Start & AOT Optimizations (`discoverAppRoutes`, `lazyRoutes: true`, `routes.manifest.json`, `templates.compiled.js`, `lazyPlugin`), Asset Management & Versioning (`AssetManager`, `fsy.asset`), ORM models & `zdb` schemas (`core/orm`), Mithril.js Admin Panel SPA (`plugins/admin-panel`), and Plugin Ecosystem.
 3. **[Services Layer](.agents/SERVICES.md)** — File-based auto-discovery (`services/`), Zod validation, declarative `auth` & RBAC guards, automatic ACID transaction propagation (`transaction: true`), timeouts, and memoization.
 4. **[Exceptions & Error Handling](.agents/ERRORS.md)** — Django-inspired framework exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`), central error boundary, `app.setErrorHandler()`, and production error masking.
 5. **[Graceful Shutdown & Lifecycle](.agents/SHUTDOWN.md)** — `ShutdownManager`, `NodeHttpAdapter`, connection draining, force close mode, and reverse-order plugin disposer cleanup.
@@ -54,6 +55,7 @@ This `.agents/` customization root is organized into modular topic guides:
 16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, and Distributed Redis queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.
 17. **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Native HTTP chunked streaming (`res.renderStream()`), deferred data loader slots (`defer: { key: promise }`), and TTFB optimization.
 18. **Polar billing production checklist** — [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md) (env, webhooks, rate limits, external tier hooks, CSP). Plugin reference: [PLUGINS.md § polarPlugin](PLUGINS.md).
+19. **[Decoupled Events & Signals Architecture](.agents/EVENTS.md)** — Zero-dependency enterprise event dispatcher (`core/events`), sync/async/parallel/serial/waterfall dispatch, wildcard listeners (`order.*`), Django-style `Signal` and sender filtering, queue bridging, and listener auto-discovery.
 
 ---
 

package/.agents/ARCHITECTURE.md

@@ -23,6 +23,12 @@
   - Discovered routes are compiled and sorted in deterministic priority order: Static $\to$ Deep Dynamic $\to$ Shallow Dynamic $\to$ Catch-All (`*`).
   - Detects `METHOD + PATH` collision conflicts at startup and throws descriptive errors.
   - Inspectable via `app.routes.list()` for CLI tools, documentation generation, and debugging.
+- **High-Performance Architecture & Cold-Start Optimization**:
+  - **Single-Pass Unified Route Discovery (`discoverAppRoutes`)**: Discovers Page routes, API routes, and Route Groups in a single filesystem traversal pass, avoiding redundant tree walks during startup.
+  - **Dev-Mode On-Demand (JIT) Route Evaluation (`lazyRoutes: true`)**: In development (`NODE_ENV !== 'production'`), route handler modules (`pages/**/*.js`) are loaded on first incoming HTTP request instead of eager-evaluating all routes at boot, reducing dev boot time to ~15ms on large projects.
+  - **AOT Route Manifest (`webspresso build` & `routesManifest`)**: Production builds generate `.webspresso/routes.manifest.json`. When present (or configured via `createApp({ routesManifest: true })`), zero directory scanning or route sorting occurs at runtime.
+  - **AOT Nunjucks Template Precompilation (`precompileTemplates` & `precompiledTemplates`)**: `webspresso build` compiles all `.njk` templates in `pages/` and `views/` into `.webspresso/templates.compiled.js`. In production, templates execute without runtime parser/AST generation or disk reads.
+  - **On-Demand Lazy Plugins (`lazyPlugin`, `defineLazyPlugin`)**: Heavy plugins (e.g. `adminPanelPlugin({ lazy: true })`, `fileManagerPlugin({ lazy: true })`) mount Express proxy routers and hydrate in memory only when a matching HTTP request or service call arrives.
 - **Templating & Helpers**: Nunjucks (`.njk`) templates rendered with layouts (e.g. `views/layout.njk`). Access helpers via `fsy` object in templates.
 - **Asset Management & Cache-Busting (`assets`, `AssetManager`, `fsy`)**:
   - Configured via `createApp({ assets: { version, manifestPath, prefix, publicDir } })` or `configureAssets()`.
@@ -115,6 +121,11 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 | `restResourcePlugin` | ORM / REST API | Auto RESTful CRUD endpoints from models with eager loading & sanitization |
 | `xlsxPlugin` | Excel / Export | Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and services |
 | `csvPlugin` | CSV / Export | RFC 4180 CSV generator, parser, Excel UTF-8 BOM, streaming writer (`res.csv`), and services |
+| `lazyPlugin` | Core / Performance | On-demand plugin hydration wrapper deferring plugin setup until first request/call |
+
+- **On-Demand Lazy Plugins (`lazyPlugin`, `defineLazyPlugin`)**:
+  - Wrap any plugin via `lazyPlugin(() => heavyPlugin(), { prefix: '/path', services: ['service.name'] })`.
+  - Built-in shorthand support on resource-heavy plugins: `adminPanelPlugin({ db, lazy: true })` and `fileManagerPlugin({ lazy: true })`.
 
 ---
 

package/.agents/AUTH.md

@@ -514,5 +514,68 @@ auth.on('sessions:revoked_all', ({ userId, count }) => {
 });
 ```
 
+---
+
+## 9. Authorization & Policies (AdonisJS Bouncer & Django Permissions-inspired)
+
+Webspresso provides an authorization layer combining AdonisJS Bouncer policies/gates with Django-style permission matrices and superuser bypass:
+
+### 9.1 Defining Policies & Gates
+Define domain policies and simple gates using `definePolicy` and `defineGate`:
+
+```javascript
+const { definePolicy, defineGate } = require('webspresso');
+
+// 1. Resource Policy
+definePolicy('Post', {
+  view: (user, post) => true,
+  update: (user, post) => user && (user.id === post.user_id || user.role === 'admin'),
+  delete: (user, post) => user && user.role === 'admin',
+});
+
+// 2. Named Gate
+defineGate('admin-only', (user) => Boolean(user && user.role === 'admin'));
+```
+
+### 9.2 Request Bouncer (`req.bouncer`)
+Incoming requests automatically receive `req.bouncer` bound to `req.user`:
+
+```javascript
+// Inside API Route or Loader:
+if (req.bouncer.allows('Post.update', post)) {
+  // Authorized
+}
+
+if (req.bouncer.denies('admin-only')) {
+  // Denied
+}
+
+// Throws ForbiddenError (403) or UnauthorizedError (401) on failure:
+req.bouncer.authorize('Post.update', post);
+
+// Inline rule check:
+req.bouncer.authorize((user) => user.isVip);
+```
+
+### 9.3 Django Permissions Matrix & Superuser Bypass
+Users with permissions arrays or superuser flags are evaluated automatically:
+- `user.permissions = ['post.create', 'post.update']`
+- Wildcards: `user.permissions = ['post.*']` or `['*']`
+- Django Superuser: `user.isSuperuser = true` or `user.is_superuser = true` automatically bypasses all permission checks.
+- Custom methods: `user.hasPerm(perm, resource)` or `user.hasPermission(...)`.
+
+### 9.4 Nunjucks Template Helpers (`fsy.can`, `fsy.cannot`)
+Check permissions directly in `.njk` templates:
+
+```jinja
+{% if fsy.can('Post.update', post) %}
+  <a href="/posts/{{ post.id }}/edit" class="btn">Edit Post</a>
+{% endif %}
+
+{% if fsy.cannot('admin-only') %}
+  <p class="text-muted">Admin access required</p>
+{% endif %}
+```
+
 
 

package/.agents/CLI.md

@@ -354,3 +354,84 @@ npx webspresso deploy:check --json
 3. **Container Hardening**: Ensures `Dockerfile` runs as a non-root `USER`, configures a `HEALTHCHECK`, and uses multi-stage caching.
 4. **Database & Migrations**: Audits for pending unapplied migrations and warns against ephemeral SQLite storage.
 5. **Server Optimizations**: Validates HTTP compression (`compression: true`), graceful shutdown, and health check endpoints.
+
+---
+
+## 18. Custom Management Commands (`run`, `command:run`, `defineCommand`) [Django manage.py & Adonis Ace]
+
+Create and execute isolated management scripts, background cron tasks, data migrations, or maintenance routines with full framework dependency injection (`db`, `queue`, `services`, `mailer`, `events`, `logger`, `args`, `flags`):
+
+```bash
+# List all custom management commands in commands/
+npx webspresso run
+
+# Execute a custom command with positional arguments and options
+npx webspresso run sync-stripe --dry-run --limit 100
+```
+
+### Defining a Custom Command (`commands/<name>.js`):
+
+```javascript
+const { defineCommand } = require('webspresso');
+
+module.exports = defineCommand({
+  name: 'sync-stripe',
+  description: 'Synchronize customer subscriptions from Stripe',
+  options: [
+    { flags: '-d, --dry-run', description: 'Simulate without committing changes', defaultValue: false },
+    { flags: '-l, --limit <count>', description: 'Maximum customers to sync', defaultValue: 100 },
+  ],
+  handle: async ({ db, queue, services, mailer, events, logger, args, flags }) => {
+    logger.log('Starting sync, dryRun:', flags.dryRun);
+
+    const userRepo = db.getRepository('User');
+    const users = await userRepo.find({ active: true });
+
+    // Events, mailer, and background jobs are fully accessible:
+    events.emit('stripe:sync-started', { count: users.length });
+
+    return { synced: users.length };
+  },
+});
+```
+
+---
+
+## 19. Command Palette Index (`list`, `commands`)
+
+Print an organized catalog of all built-in commands (scaffolding, database, server, developer tools) alongside all auto-discovered custom commands in your project:
+
+```bash
+npx webspresso list
+# or
+npx webspresso commands
+```
+
+---
+
+## 20. Advanced Scaffolding Generators (`make:*`) [Adonis Ace style]
+
+Rapidly generate boilerplate code following Webspresso architectural conventions:
+
+```bash
+# 1. Custom Management Command
+npx webspresso make:command users:cleanup --desc "Purge unverified user accounts"
+# Outputs: commands/users/cleanup.js
+
+# 2. Authorization Policy (Bouncer)
+npx webspresso make:policy Article
+# Outputs: policies/article.policy.js
+
+# 3. Model Factory (Testing & Seeding)
+npx webspresso make:factory Product
+# Outputs: factories/product.factory.js
+
+# 4. Decoupled Event Listener
+npx webspresso make:event order:completed
+# Outputs: listeners/order-completed.js
+
+# 5. Declarative Mailable Class
+npx webspresso make:mail Welcome
+# Outputs: emails/WelcomeEmail.js
+```
+

package/.agents/CONVENTIONS.md

@@ -44,3 +44,7 @@
    - **ALWAYS** use published `package.json` export paths: `require('webspresso/core/auth')`, `require('webspresso/core/orm')`, `require('webspresso/plugins/polar/src/webhooks')`.
    - **NEVER** rely on deep relative paths from `node_modules/webspresso/...` or append `/index.js` unless documenting a pre-0.0.95 workaround.
    - Smoke test: `tests/unit/package-exports.test.js`.
+14. **Tailwind CSS v4 Standard (NO v3 PostCSS Boilerplate)**:
+   - **ALWAYS** prefer Tailwind CSS v4 using `npx webspresso add tailwind --v4` (powered by Oxide and `@tailwindcss/cli`).
+   - **ALWAYS** use CSS-first `@import "tailwindcss";` in `src/input.css` and compile to `public/css/style.css`.
+   - **NEVER** create redundant `tailwind.config.js` or `postcss.config.js` files unless custom legacy PostCSS plugins are specifically required.

package/.agents/EMAIL.md

@@ -102,11 +102,92 @@ emailApi.registerTemplate('notification', '<mjml><mj-body>...</mj-body></mjml>')
 const isReady = await emailApi.verifyConnection();
 const logs = await emailApi.queryLogs({ status: 'sent', limit: 20 });
 await emailApi.purgeLogs({ olderThan: '30d' });
+
+// 6. In-memory outbox inspection & clearing (memory backend / tests)
+const outbox = emailApi.getOutbox();
+const lastSent = emailApi.lastMessage();
+emailApi.clearOutbox();
+```
+
+---
+
+## 5. Declarative `Mailable` Classes (AdonisJS-style)
+
+Define structured, reusable, object-oriented emails by extending `Mailable`:
+
+```javascript
+import { Mailable } from 'webspresso';
+
+export class WelcomeEmail extends Mailable {
+  constructor(user) {
+    super();
+    this.user = user;
+  }
+
+  build() {
+    this.to(this.user.email, this.user.name)
+      .from('team@myapp.com', 'Acme Team')
+      .subject(`Welcome to Acme, ${this.user.name}!`)
+      .view('welcome', { user: this.user }) // references registered template
+      .attach({
+        filename: 'welcome-guide.pdf',
+        content: Buffer.from('...'),
+      });
+  }
+}
+
+// In route handlers or services:
+await req.mailer.send(new WelcomeEmail(user));
+// Or via email API:
+await emailApi.send(new WelcomeEmail(user));
+```
+
+### Fluent Mailable Methods
+
+- `to(address, name?)`, `cc(address, name?)`, `bcc(address, name?)`, `replyTo(address, name?)`, `from(address, name?)`
+- `subject(title)`
+- `view(templateName, data?)` or `template(templateName)`
+- `html(htmlContent)`, `text(textContent)`
+- `attach({ filename, content, path, contentType })`
+- `header(name, value)`
+- `prepare()` and `build()` lifecycle hooks
+- `toMessage()` serializes the definition into a message payload
+
+---
+
+## 6. Pluggable Transports (Django-style Backends)
+
+Configure backends via `backend`: `'smtp' | 'memory' | 'console' | 'file'`:
+
+```javascript
+const email = emailPlugin({
+  backend: process.env.NODE_ENV === 'production' ? 'smtp' : 'memory',
+  fileDir: './storage/emails', // when backend: 'file'
+  devInbox: true, // enables developer inbox web UI
+});
 ```
 
+- **`MemoryTransport`**: Stores messages in an in-memory inspectable outbox (`mailer.getOutbox()`). Automatically chosen in test environments.
+- **`ConsoleTransport`**: Pretty-prints sent emails to stdout/logger for zero-setup terminal debugging.
+- **`FileTransport`**: Writes JSON/EML email files to a local directory for disk-based inspection.
+- **`NodemailerTransport`**: Delivers real emails via SMTP or custom transport in production.
+
 ---
 
-## 5. Auth Email Bridge (`authEmails`)
+## 7. Developer Mail Preview & Dev Inbox (`/_webspresso/mail-preview`)
+
+When `devInbox: true` or running in `development` mode, Webspresso automatically mounts a local inbox viewer:
+
+- **Web UI Route**: `GET /_webspresso/mail-preview` (responsive inbox viewer with desktop, tablet, and mobile viewport switcher)
+- **JSON List Route**: `GET /_webspresso/mail-preview/api/messages`
+- **Single Message Route**: `GET /_webspresso/mail-preview/api/messages/:id`
+- **Iframe HTML View**: `GET /_webspresso/mail-preview/api/messages/:id/html`
+- **Clear Inbox Route**: `POST /_webspresso/mail-preview/api/clear`
+- **Template Preview**: `POST /_webspresso/mail-preview/api/preview`
+
+---
+
+## 8. Auth Email Bridge (`authEmails`)
 
 Automatically wires password reset and email verification flows with `AuthManager`:
 
@@ -131,7 +212,7 @@ const email = emailPlugin({
 
 ---
 
-## 6. Admin Panel UI & Database Logs
+## 9. Admin Panel UI & Database Logs
 
 When `includeAdminPage: true` and `adminPanelPlugin` are present, an interactive Email Management module is mounted at `/_admin/email`:
 
@@ -139,3 +220,4 @@ When `includeAdminPage: true` and `adminPanelPlugin` are present, an interactive
 - **Test Sender**: Send test emails directly from the Admin Panel to verify SMTP configuration.
 - **Audit Logs Inspector**: Filter sent email logs by status (`sent`, `failed`), view error tracebacks, and purge historic logs.
 - **Database Schema**: Log entries are stored in `email_logs` table (`id`, `to_email`, `subject`, `template_name`, `status`, `error`, `created_at`).
+

package/.agents/EVENTS.md

@@ -0,0 +1,179 @@
+# Webspresso Events & Signals Architecture
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+Webspresso provides an enterprise, zero-dependency **Decoupled Event & Signals System** (`core/events`), combining **AdonisJS Events** (wildcard matching, async parallel/serial/waterfall dispatch, queue bridging, and listener auto-discovery) with **Django Signals** (declarative `Signal` channels, sender filtering, and ORM model signals).
+
+---
+
+## 1. Overview & Key Capabilities
+
+- **Zero External Dependencies**: Built entirely with native Node.js standard modules (`events`, `path`, `fs`).
+- **Synchronous & Asynchronous Emission**:
+  - `events.emit(name, data)`: Fast sync/fire-and-forget dispatch.
+  - `await events.emitAsync(name, data)`: Parallel concurrent execution (`Promise.allSettled`).
+  - `await events.emitSerial(name, data)`: Sequential execution in priority order.
+  - `await events.emitWaterfall(name, initialData)`: Sequential pipeline where output of listener $N$ feeds listener $N+1$.
+- **Wildcard & Pattern Matching**:
+  - `events.on('order.*', (data, meta) => ...)`
+  - `events.on('system.**', (data, meta) => ...)`
+  - `events.onAny((eventName, data, meta) => ...)`
+- **Django-Style Signals & Sender Filtering**:
+  - `const orderPlaced = defineSignal('order_placed')`
+  - `orderPlaced.connect(receiver, { sender: 'Checkout' })`
+  - `orderPlaced.send({ orderId: 101 }, { sender: 'Checkout' })`
+- **Background Queue Bridging**:
+  - `events.listenAndQueue('user.created', 'send-welcome-email', { delay: 1000 })`
+  - Automatically bridges emitted events directly to Webspresso's job queue (`core/queue`).
+- **ORM Model Signals Auto-Bridge**:
+  - Automatically translates `ModelEvents` (`User.afterCreate`, `*.afterDelete`) to application events (`model:created`, `user:created`, `model:deleted`) with `sender: ctx.model`.
+- **Automatic Request & Context Decoration**:
+  - Injected onto `req.events` on every Express request.
+  - Available inside `req.context.events` for services: `ctx.events.emit('order.created', order)`.
+  - Accessible on `app.events` and plugin contexts.
+- **Graceful Shutdown Integration**:
+  - Cleaned up automatically on graceful shutdown via `ShutdownManager.onShutdown()`.
+
+---
+
+## 2. Using Events in API Routes & Services
+
+### 2.1 Emitting Events in File-Based Routes (`pages/api/...`)
+
+```javascript
+// pages/api/orders.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      total: z.number().positive(),
+      items: z.array(z.string()),
+    }),
+  }),
+  async handler(req, res) {
+    const order = await req.db.getRepository('Order').create(req.input.body);
+
+    // Synchronous fire-and-forget or awaited async parallel
+    req.events.emit('order.created', order, { sender: 'Order' });
+    // or: await req.events.emitAsync('order.created', order);
+
+    return res.status(201).json(order);
+  },
+});
+```
+
+### 2.2 Emitting Events inside Services (`services/...`)
+
+```javascript
+// services/order/checkout.js
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  transaction: true,
+  async handle(input, ctx) {
+    const order = await ctx.db.getRepository('Order').create(input);
+
+    // ctx.events is automatically available
+    ctx.events.emit('order.checkout.completed', { orderId: order.id, user: ctx.req?.user });
+
+    return order;
+  },
+});
+```
+
+---
+
+## 3. Registering Listeners
+
+### 3.1 Programmatic Subscriptions
+
+```javascript
+const { events } = require('webspresso');
+
+// 1. Basic Listener
+const unsub = events.on('order.created', (order, meta) => {
+  console.log(`Order ${order.id} received at ${meta.timestamp}`);
+});
+
+// 2. Wildcard Listener
+events.on('order.*', (data, meta) => {
+  console.log(`Order event ${meta.event} occurred`);
+});
+
+// 3. One-time Listener
+events.once('app.ready', () => {
+  console.log('Application initialized');
+});
+
+// 4. Priority Ordering (higher runs first)
+events.on('user.login', auditLogin, { priority: 100 });
+events.on('user.login', notifyFriends, { priority: 0 });
+```
+
+### 3.2 File-Based Discovery (`listeners/` directory)
+
+Webspresso auto-discovers listeners in the `listeners/` root directory:
+
+```javascript
+// listeners/send-welcome-email.js
+const { defineListener } = require('webspresso');
+
+module.exports = defineListener('user.created', async (user, meta) => {
+  console.log(`Sending welcome email to ${user.email}`);
+});
+```
+
+Or multiple listeners in a single file:
+
+```javascript
+// listeners/audit-events.js
+module.exports = [
+  {
+    event: 'order.*',
+    priority: 50,
+    handle: async (data, meta) => {
+      console.log(`Audit: ${meta.event}`, data);
+    },
+  },
+];
+```
+
+---
+
+## 4. Django-Style Signals
+
+For decoupled domain events with strict sender boundaries:
+
+```javascript
+const { defineSignal } = require('webspresso');
+
+// Define signal
+const invoicePaid = defineSignal('invoice_paid');
+
+// Connect receiver with sender filter
+invoicePaid.connect(
+  (invoice) => {
+    console.log(`Invoice ${invoice.id} processed for subscription`);
+  },
+  { sender: 'Subscription' }
+);
+
+// Trigger signal
+invoicePaid.send({ id: 'INV-100' }, { sender: 'Subscription' });
+```
+
+---
+
+## 5. Background Queue Bridging (`listenAndQueue`)
+
+Connect application events directly to background jobs without manual boilerplate:
+
+```javascript
+// In plugin or server setup:
+app.events.listenAndQueue('order.created', 'send-order-confirmation', {
+  delay: 2000,
+  attempts: 3,
+});
+```
+When `order.created` is emitted, Webspresso automatically calls `req.queue.dispatch('send-order-confirmation', order, options)`.

package/.agents/ORM.md

@@ -400,5 +400,64 @@ await authorRepo.restore(authorId, { cascade: false });
 
 If your data model contains circular relations (e.g. `User.partner` <-> `Partner.user`), Webspresso ORM uses an internal visited set (`model:id`) to terminate recursion cleanly without stack overflows.
 
+---
+
+## 10. Django-inspired Auto-Migrations (`db:makemigrations`)
+
+Webspresso supports automatic schema diffing against your live database, similar to Django's `makemigrations`. It inspects your `models/*.js` definitions, checks the current database schema, and automatically generates required Knex migration files (`createTable` or `alterTable` with `dropColumn` rollbacks):
+
+```bash
+# Preview changes without writing files
+npx webspresso db:makemigrations --dry-run
+
+# Detect model changes and generate migration file
+npx webspresso db:makemigrations
+
+# Custom migration name
+npx webspresso db:makemigrations --name add_profile_fields
+
+# Apply migrations
+npx webspresso db:migrate
+```
+
+Programmatic usage via `db.migrate`:
+```javascript
+// Check diff
+const diff = await db.migrate.diff();
+if (diff.hasChanges) {
+  console.log(diff.changes);
+}
+
+// Generate files
+const result = await db.migrate.makeMigrations();
+```
+
+---
+
+## 11. AdonisJS-inspired Model Factories (`defineFactory`)
+
+For unit testing, integration tests, and dev database seeding, Webspresso provides declarative Model Factories inspired by AdonisJS Lucid:
+
+```javascript
+import { defineFactory } from 'webspresso';
+
+export const UserFactory = defineFactory('User', ({ faker, index }) => ({
+  name: faker.person.fullName(),
+  email: faker.internet.email(),
+  role: 'user',
+  isActive: true,
+}))
+  .state('admin', () => ({ role: 'admin' }))
+  .state('suspended', () => ({ isActive: false }));
+
+// In-memory object generation (No DB hit)
+const fakeUser = UserFactory.make({ name: 'Custom Name' });
+const fakeUsers = UserFactory.count(5).make();
+
+// Database persistence via Repository
+const user = await UserFactory.create({ db });
+const admins = await UserFactory.count(3).apply('admin').create({ db });
+```
+