webspresso 0.0.99 → 0.0.101

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** |
 
 ---
@@ -44,16 +45,17 @@ This `.agents/` customization root is organized into modular topic guides:
 6. **[HTTP Response Compression](.agents/COMPRESSION.md)** — Native streaming zlib compression (`server.compression`), Brotli/Gzip/Deflate negotiation, threshold handling, and `res.compress(false)` route opt-out.
 7. **[Dual Authentication System](.agents/AUTH.md)** — Stateful Session + Cookie & Stateless HS256 JWT + Refresh Token Rotation, `req.auth` helpers, and `middleware: ['jwt']` guard integrations.
 8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
-9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 19 built-in official plugins (including `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
+9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 20 built-in official plugins (including `webhooksPlugin`, `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
 10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
 11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
 12. **[Admin Panel Customization](.agents/ADMIN.md)** — Extending Mithril.js Admin Panel SPA (Custom pages `component.js`, custom field renderers, widgets, single & bulk actions).
-13. **[CLI Tooling & Commands](.agents/CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `agents:init`.
+13. **[CLI Tooling & Commands](CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `add:docker`, `deploy:check`, `agents:init`.
 14. **[Development & Testing Workflow](.agents/WORKFLOW.md)** — CLI commands, Vitest unit/integration testing, Playwright E2E tests, TypeScript type checking, and zero regression policy.
 15. **[Coding Standards & Conventions](.agents/CONVENTIONS.md)** — Zero external dependencies policy, strict function signature & schema verification, clean component separation, and log traceback inspection rules.
 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/AUTH.md

@@ -45,6 +45,10 @@ Attached to Express request during auth middleware execution:
 | `req.auth.refreshAccessToken(refreshToken, options)` | Refresh access token & rotate refresh token |
 | `req.auth.check()` / `req.auth.guest()` | Check if user is authenticated or guest |
 | `req.auth.user()` / `req.auth.id()` | Get current user object or ID |
+| `req.auth.sessions()` | List active sessions & device info for current user |
+| `req.auth.revokeSession(sessionId)` | Revoke a specific session (remotely log out device) |
+| `req.auth.revokeOtherSessions()` | Revoke all sessions except the current active session |
+| `req.auth.revokeAllSessions(userId?)` | Revoke all active sessions (force logout from all devices) |
 
 ---
 
@@ -269,4 +273,309 @@ module.exports = {
 };
 ```
 
+---
+
+## 7. Magic Link & Passwordless Authentication
+
+Webspresso includes zero-dependency, cryptographically secure **Magic Link / Passwordless Authentication**:
+- **Single-Use Timed Tokens**: 32-byte cryptographically secure random tokens stored hashed (`SHA-256`) in the `auth_tokens` table (`type = 'magic_link'`) with a default 15-minute TTL.
+- **Anti-Enumeration Protection**: `requestMagicLink` returns `{ sent: true, userFound: false }` for unknown emails by default so attackers cannot probe user existence.
+- **Auto-Verification**: Successfully signing in via a magic link automatically marks `email_verified_at` if the user is not yet verified.
+- **Dual Session & JWT Support**: Seamlessly establishes web sessions (`req.auth.login`) and/or issues JWT access/refresh token pairs.
+- **Native Email Plugin Integration**: Built-in `auth-magic-link` MJML template, automated delivery via `plugins/email`'s `wireAuthEmails`, and pre-wired `/api/auth/magic-link` routes.
+
+### 7.1 Setup in `quickAuth`
+```javascript
+const { quickAuth } = require('webspresso/core/auth');
+
+const auth = quickAuth({
+  db,
+  userModel: 'User',
+  identifierField: 'email',
+  magicLink: true, // Automatically provisions Knex auth_tokens adapter
+});
+```
+
+### 7.2 Requesting a Magic Link (`pages/api/auth/magic-link.post.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      email: z.string().email(),
+    }),
+  }),
+  async handler(req, res) {
+    const { email } = req.input.body;
+
+    // Dispatches email notification via plugins/email (if active)
+    await req.auth.requestMagicLink(email, {
+      tokenTtlMs: 15 * 60 * 1000, // 15 mins (default)
+      path: '/auth/magic-link/verify',
+    });
+
+    return res.json({
+      ok: true,
+      message: 'If an account exists with this email, a sign-in link has been sent.',
+    });
+  },
+});
+```
+
+### 7.3 Verifying & Logging In (`pages/api/auth/magic-link/verify.get.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    query: z.object({
+      token: z.string().min(1),
+    }),
+  }),
+  async handler(req, res) {
+    const { token } = req.input.query;
+
+    // Verifies token, consumes it, marks email verified, logs into session and/or generates JWTs
+    const result = await req.auth.loginWithMagicLink(token, {
+      remember: true,
+      jwt: false, // Set to true to receive accessToken and refreshToken
+    });
+
+    // For browser requests, redirect to dashboard:
+    if (req.accepts('html')) {
+      return res.redirect('/dashboard');
+    }
+
+    return res.json({ ok: true, user: result.user });
+  },
+});
+```
+
+### 7.4 Using Built-in Route Middlewares
+You can also mount Webspresso's pre-configured Express middlewares directly:
+```javascript
+const {
+  createMagicLinkRequestHandler,
+  createMagicLinkVerifyMiddleware,
+} = require('webspresso/core/auth');
+
+// Request link: POST /auth/magic-link
+app.post('/auth/magic-link', createMagicLinkRequestHandler(authManager));
+
+// Verify & Login: GET /auth/magic-link/verify
+app.get('/auth/magic-link/verify', createMagicLinkVerifyMiddleware(authManager, {
+  redirectTo: '/dashboard',
+  failureRedirect: '/login?error=invalid_magic_link',
+  jwt: false,
+}));
+```
+
+### 7.5 AuthManager Magic Link Events
+`AuthManager` extends `EventEmitter`, allowing you to hook into magic link lifecycle events:
+```javascript
+authManager.on('magicLink:requested', ({ userId, email, expiresAt }) => {
+  console.log(`Magic link requested for ${email}, expires at ${expiresAt}`);
+});
+
+authManager.on('magicLink:verified', ({ userId }) => {
+  console.log(`User ${userId} signed in via magic link`);
+});
+```
+
+---
+
+## 8. Active Devices & Remote Session Revocation
+
+Webspresso provides a zero-dependency session management and device tracking system (`webspresso/core/auth`) allowing users to view all active logins, detect browser/OS/hardware types, and remotely revoke unwanted sessions.
+
+### 8.1 Database Migration
+Create the `user_sessions` table using the built-in migration helper:
+```javascript
+const { createUserSessionsTable } = require('webspresso/core/auth');
+
+exports.up = async function(knex) {
+  await createUserSessionsTable(knex);
+};
+
+exports.down = async function(knex) {
+  const { dropUserSessionsTable } = require('webspresso/core/auth');
+  await dropUserSessionsTable(knex);
+};
+```
+
+Schema columns:
+- `id`: Bigint primary key
+- `session_id`: Unique Express session ID
+- `user_id`: User ID reference
+- `ip_address`: Proxy-safe client IP (`x-forwarded-for`, `x-real-ip`, or socket)
+- `user_agent`: Raw User-Agent string
+- `browser`: Detected browser and version (e.g. `Chrome 128`, `Safari 17`, `Firefox 125`, `Edge 122`)
+- `os`: Detected operating system (e.g. `macOS 14`, `Windows 10/11`, `iOS 17.4`, `Android 14`, `Ubuntu Linux`)
+- `device`: Device form factor (`desktop`, `mobile`, `tablet`, `bot`)
+- `last_active_at`: Last seen timestamp (throttled to 60s by default to protect DB performance)
+- `created_at`: Initial login timestamp
+
+### 8.2 Enabling Session Tracking
+Enable session tracking in `createAuth` or `quickAuth`:
+```javascript
+const { quickAuth } = require('webspresso/core/auth');
+
+const auth = quickAuth({
+  db,
+  sessionTracking: true, // Automatically enables Knex session tracker and active session verification
+});
+```
+
+Or manually with custom options:
+```javascript
+const { createAuth, createKnexSessionTracker } = require('webspresso/core/auth');
+
+const auth = createAuth({
+  db,
+  sessionTracking: true,
+  sessionTracker: createKnexSessionTracker(db),
+  sessionTouchThrottleMs: 60000, // Touch session at most once per minute
+  // ...other config
+});
+```
+
+### 8.3 File-Based API Routes (`pages/api/*`)
+
+#### List Active Devices (`pages/api/auth/sessions.get.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  middleware: ['auth'],
+  async handler(req, res) {
+    // Returns array of active sessions with is_current flag for current device
+    const sessions = await req.auth.sessions();
+    return res.json({ ok: true, sessions });
+  },
+});
+```
+
+#### Revoke Session / Remote Logout (`pages/api/auth/sessions/revoke.post.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  middleware: ['auth'],
+  schema: ({ z }) => ({
+    body: z.object({
+      sessionId: z.string().optional(),
+      allOthers: z.boolean().optional(),
+    }),
+  }),
+  async handler(req, res) {
+    const { sessionId, allOthers } = req.input.body;
+
+    if (allOthers) {
+      // Revokes all sessions except current device
+      const count = await req.auth.revokeOtherSessions();
+      return res.json({ ok: true, revokedCount: count, message: 'All other sessions revoked' });
+    }
+
+    if (sessionId) {
+      // Revokes specified session (logs out current user if it is the current session)
+      await req.auth.revokeSession(sessionId);
+      return res.json({ ok: true, message: 'Session revoked' });
+    }
+
+    return res.status(400).json({ error: 'sessionId or allOthers is required' });
+  },
+});
+```
+
+### 8.4 Automatic Invalidation in Middleware
+When a session is revoked remotely, Webspresso's `authenticate` middleware automatically detects it on the next incoming request from that device:
+- The revoked session is destroyed in `req.sessionStore`.
+- `req.user` is set to `null`.
+- Any subsequent `requireAuth` or `middleware: ['auth']` guard immediately redirects or rejects the request with `401 Unauthorized`.
+
+### 8.5 Session Lifecycle Events
+`AuthManager` emits EventEmitter events for monitoring and security audits:
+```javascript
+auth.on('session:created', ({ sessionId, userId, ip, browser, os, device }) => {
+  console.log(`New session created for user ${userId} from ${device} (${browser} on ${os}) at ${ip}`);
+});
+
+auth.on('session:revoked', ({ sessionId, userId, revokedBy }) => {
+  console.log(`Session ${sessionId} was revoked`);
+});
+
+auth.on('sessions:revoked_others', ({ userId, currentSessionId, count }) => {
+  console.log(`User ${userId} revoked ${count} other sessions`);
+});
+
+auth.on('sessions:revoked_all', ({ userId, count }) => {
+  console.log(`All ${count} sessions revoked for user ${userId}`);
+});
+```
+
+---
+
+## 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

@@ -302,8 +302,136 @@ npx webspresso typegen --out types/webspresso.d.ts --no-env-file
 - **Typed Services (`req.service('name', input)`)**: Auto-completes registered service names and enforces validated input payloads.
 - **Typed Route Table (`AppRoute`, `AppRoutePath`)**: Union types for all discovered SSR and API routes.
 
+---
+
+## 16. Containerization & Docker Setup (`add:docker` / `docker`)
+
+Generate production-ready, security-hardened, multi-stage `Dockerfile`, `.dockerignore`, and `docker-compose.yml`:
+
+```bash
+# Generate Dockerfile, .dockerignore, and docker-compose.yml
+npx webspresso add:docker
+
+# Customize Node.js version, database service, or container port
+npx webspresso add:docker --node 22-alpine --db postgres --redis --port 3000
+
+# Overwrite existing files
+npx webspresso add:docker --force
+```
+
+### Generated Artifacts:
+- **Multi-Stage `Dockerfile`**:
+  - `deps` stage: caches production dependencies with native build tools (`python3`, `make`, `g++`).
+  - `builder` stage: runs asset build scripts (`npm run build`).
+  - `runner` stage: runs as unprivileged user `webspresso` (UID 1001), health check with `/health` and `/healthz`, and `SIGTERM` signal handling.
+- **`.dockerignore`**: Excludes `node_modules`, `.env`, local `.sqlite` databases, test files, and git metadata while preserving upload directories.
+- **`docker-compose.yml`**: Configures app container with persistent upload volumes, database services (PostgreSQL, MySQL, or SQLite), and optional Redis.
+- **`package.json` Scripts**: Adds `docker:build`, `docker:run`, `docker:up`, and `docker:down`.
+
+---
+
+## 17. Production Deployment Preflight Check (`deploy:check` / `check:deploy`)
+
+Run comprehensive pre-flight verification before deploying to Fly.io, Railway, Render, VPS, or Kubernetes:
+
+```bash
+# Run production preflight verification
+npx webspresso deploy:check
+
+# Run against a specific environment (.env.staging or .env.production)
+npx webspresso deploy:check --env staging
+
+# Strict mode: fail with exit code 1 on warnings as well as errors (ideal for CI/CD)
+npx webspresso deploy:check --strict
+
+# Machine-readable JSON output for automated deployment pipelines
+npx webspresso deploy:check --json
+```
+
+### Audited Verification Areas:
+1. **Secrets & Cryptography**: Ensures `SESSION_SECRET` or `APP_KEY` is set, >= 32 characters, and not using weak placeholder defaults.
+2. **Git & Leak Prevention**: Verifies `.env` and local database files are excluded in `.gitignore`.
+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/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`).
+