webspresso 0.0.94 → 0.0.96

package/.agents/COMPRESSION.md

@@ -0,0 +1,59 @@
+# Webspresso HTTP Response Compression Guide
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+---
+
+## 1. Overview
+
+Webspresso provides a zero-dependency, streaming-first HTTP response compression layer built entirely with native `node:zlib`. It transparently compresses compressible responses (HTML, JSON, JS, CSS, SVG, XML) using Brotli (`br`), Gzip (`gzip`), or Deflate (`deflate`).
+
+---
+
+## 2. Configuration
+
+Compression is disabled by default to avoid unnecessary CPU overhead. Enable via `createApp`:
+
+```js
+const { app } = createApp({
+  pagesDir: './pages',
+  server: {
+    compression: true, // Enables default 1 KB threshold with Brotli + Gzip
+  },
+});
+```
+
+### Advanced Options:
+```js
+const { app } = createApp({
+  pagesDir: './pages',
+  server: {
+    compression: {
+      threshold: 2048,           // Only compress responses >= 2 KB (default: 1024)
+      encodings: ['br', 'gzip'], // Algorithm preference
+      level: 6,                  // Compression level (1-9)
+      filter: (req, res) => {
+        if (req.path.startsWith('/downloads')) return false;
+        return true;
+      },
+    },
+  },
+});
+```
+
+---
+
+## 3. Route-Level Opt-out
+
+Individual routes can opt-out of compression (e.g. to mitigate BREACH attacks or for already-compressed dynamic payloads):
+
+```js
+// pages/api/sensitive-export.get.js
+module.exports = async function handler(req, res) {
+  res.compress(false); // Disables compression for this response
+
+  res.json({
+    secretToken: 'xyz-secret-token',
+  });
+};
+```

package/.agents/CONVENTIONS.md

@@ -0,0 +1,46 @@
+# Webspresso Coding Standards & Conventions
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+---
+
+## 1. Core Policies
+
+1. **Zero External Dependencies Policy**: Core framework functionality (Auth, JWT, CORS, Routing, Nunjucks helpers) must avoid unnecessary third-party npm dependencies. Rely strictly on native Node.js standard library modules (`crypto`, `path`, `fs`, `events`, `async_hooks`).
+2. **Strict Signature & Schema Verification**: Always verify function signatures and object schemas by inspecting authoritative source files before calling or extending them.
+3. **File & Component Separation**: Keep client-side components in clean standalone JS files (`component.js` / `componentFile`) rather than escaping inline template strings.
+4. **Log & Traceback Inspection**: Base all bug fixes strictly on exact runtime error log tracebacks and empirical test output. Never swallow errors or return dummy fallbacks.
+5. **No Superficial Symptom Patches**: Never resolve errors by masking symptoms or deleting failing unit tests. Always resolve the underlying contract breakage.
+6. **Strict File-Based Routing Policy (NO Express `routes/` or `app.get()`)**:
+   - **NEVER** create a `routes/` or `src/routes/` directory.
+   - **NEVER** call `express.Router()`, `app.get()`, `app.post()`, or `app.use()` to register application API endpoints.
+   - **ALWAYS** define API routes under `pages/api/...` with HTTP method extensions:
+     - `GET /api/notes` → `pages/api/notes.get.js`
+     - `POST /api/notes` → `pages/api/notes.post.js`
+     - `GET /api/notes/:id` → `pages/api/notes/[id].get.js`
+     - `DELETE /api/notes/:id` → `pages/api/notes/[id].delete.js`
+   - Every file route module must export `{ schema, middleware, handler }` or an `async (req, res)` function. See [.agents/ROUTING.md](ROUTING.md) for full patterns.
+7. **Strict Repository Pattern Policy (NO Raw `db('table')`)**:
+   - **NEVER** write raw Knex table queries (`db('table')`, `req.db('table')`) in application code.
+   - **ALWAYS** access database models through `db.getRepository('ModelName')` or `req.db.getRepository('ModelName')`.
+   - Raw Knex queries bypass schema validation, lifecycle hooks, soft-deletes, multi-tenant scopes, hidden fields, and query caching. See [.agents/ORM.md](ORM.md) for full patterns.
+8. **Services Layer Over Controllers (NO `controllers/`)**:
+   - **NEVER** create a `controllers/` directory or write class-based controller singletons.
+   - **ALWAYS** encapsulate multi-step business logic, domain mutations, and reusable operations inside `services/domain/action.js`.
+   - Invoke services via `ctx.service('domain.action', input)` or `req.service('domain.action', input)`. This ensures declarative validation (`schema`), automatic ACID transaction propagation (`transaction: true`), and role guards (`auth`). See [.agents/SERVICES.md](SERVICES.md).
+9. **Native Dual Auth Over External Packages (NO `jsonwebtoken` or `passport`)**:
+   - **NEVER** install third-party auth packages like `jsonwebtoken`, `bcryptjs`, `passport`, or `express-session`.
+   - **ALWAYS** use Webspresso's built-in zero-dependency Dual Authentication (`webspresso/core/auth` & `req.auth`). Use `req.auth.attempt()`, `req.auth.generateUserToken()`, and guards `middleware: ['auth']` (web session) or `middleware: ['jwt']` (stateless API Bearer). See [.agents/AUTH.md](AUTH.md).
+10. **Page Data Loaders Over Manual `res.render()`**:
+   - **NEVER** manually call `res.render('view.njk', { ... })` inside custom handlers for web pages.
+   - **ALWAYS** declare SSR pages inside `pages/` (e.g. `pages/notes/[id].njk`) and provide server-side data via a companion loader in `pages/notes/[id].js` exporting `async function load({ req, res, db, ctx })`.
+11. **Framework Exceptions Over Generic Errors**:
+   - **NEVER** return manual error payloads like `return res.status(404).json(...)` inside services or loaders, and never throw generic `throw new Error('Not found')` for client-facing issues (which masks as a 500 error in production).
+   - **ALWAYS** throw semantic framework exceptions: `NotFoundError` (404), `ValidationError` (422), `UnauthorizedError` (401), `ForbiddenError` (403), `BadRequestError` (400). Import them from `webspresso` or `webspresso/core/errors`. See [.agents/ERRORS.md](ERRORS.md).
+12. **Background Queue Engine Over External BullMQ or `setTimeout`**:
+   - **NEVER** install `bullmq` / `agenda` or use unmanaged `setTimeout()` / `setInterval()` for background or deferred tasks.
+   - **ALWAYS** place background job handlers in `jobs/` (e.g. `jobs/email/send.js`) and dispatch them reliably using `req.queue.dispatch('email.send', payload)` or `ctx.queue.dispatch()`. See [.agents/QUEUE.md](QUEUE.md).
+13. **Package Subpath Imports (NO manual `/index.js` suffix)**:
+   - **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`.

package/.agents/EMAIL.md

@@ -0,0 +1,141 @@
+# Webspresso Email Plugin Guide (`plugins/email`)
+
+The `emailPlugin` provides responsive email template compilation (using MJML), Nodemailer transport management, database delivery audit logs, auth email integration (password reset / email verification), and an interactive Admin Panel management UI.
+
+---
+
+## 1. Overview & Setup
+
+```js
+import { createApp } from 'webspresso';
+import { emailPlugin } from 'webspresso/plugins/email';
+
+const email = emailPlugin({
+  db,
+  smtp: {
+    host: 'smtp.mailtrap.io',
+    port: 2525,
+    auth: { user: 'username', pass: 'password' },
+  },
+  defaults: {
+    from: 'Webspresso App <noreply@example.com>',
+  },
+  templatesDir: './emails',
+  logToDb: true,
+  includeAdminPage: true,
+});
+
+const { app } = createApp({
+  db,
+  plugins: [email],
+});
+```
+
+---
+
+## 2. Configuration Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `db` | `Object` | `null` | Knex database instance (for logging emails to DB) |
+| `transport` | `Object` | `null` | Pre-configured Nodemailer transport instance |
+| `smtp` | `Object` | `null` | SMTP configuration object `{ host, port, auth }` |
+| `defaults` | `Object` | `{}` | Default email headers (`from`, `replyTo`) |
+| `templatesDir` | `string` | `null` | Path to directory containing `.mjml` templates |
+| `templates` | `Object` | `{}` | In-memory map of MJML template strings |
+| `logToDb` | `boolean` | `true` | Log sent emails to database |
+| `tableName` | `string` | `'email_logs'` | Table name used for email logs |
+| `includeAdminPage` | `boolean` | `true` | Mount Email management UI inside Admin Panel (`/_admin/email`) |
+| `authEmails` | `Object` | `null` | Auth email bridge configuration |
+
+---
+
+## 3. Template Management & MJML Compilation
+
+Place `.mjml` templates inside `templatesDir` (e.g. `emails/welcome.mjml`):
+
+```xml
+<mjml>
+  <mj-body>
+    <mj-section>
+      <mj-column>
+        <mj-text font-size="20px">Welcome, {{ name }}!</mj-text>
+        <mj-button href="{{ activationUrl }}">Activate Account</mj-button>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+```
+
+Templates are dynamically compiled to responsive HTML with Nunjucks variable interpolation.
+
+---
+
+## 4. Plugin API (`emailPlugin().api`)
+
+The plugin exports helper methods under `.api`:
+
+```js
+const { api: emailApi } = email;
+
+// 1. Send compiled MJML template
+await emailApi.sendTemplate('welcome', {
+  to: 'user@example.com',
+  subject: 'Welcome to Webspresso!',
+  data: { name: 'Ahmet', activationUrl: 'https://example.com/activate' },
+});
+
+// 2. Direct raw email sending
+await emailApi.send({
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Direct HTML</p>',
+});
+
+// 3. Render HTML preview without sending
+const { html, subject } = await emailApi.preview('welcome', { name: 'Ahmet' });
+
+// 4. Register in-memory MJML template string dynamically
+emailApi.registerTemplate('notification', '<mjml><mj-body>...</mj-body></mjml>');
+
+// 5. Connection test & log management
+const isReady = await emailApi.verifyConnection();
+const logs = await emailApi.queryLogs({ status: 'sent', limit: 20 });
+await emailApi.purgeLogs({ olderThan: '30d' });
+```
+
+---
+
+## 5. Auth Email Bridge (`authEmails`)
+
+Automatically wires password reset and email verification flows with `AuthManager`:
+
+```js
+const email = emailPlugin({
+  db,
+  auth,
+  authEmails: {
+    enabled: true,
+    resetPassword: {
+      template: 'reset-password',
+      subject: 'Reset your password',
+      tokenExpiresIn: '1h',
+    },
+    emailVerification: {
+      template: 'verify-email',
+      subject: 'Verify your email address',
+    },
+  },
+});
+```
+
+---
+
+## 6. Admin Panel UI & Database Logs
+
+When `includeAdminPage: true` and `adminPanelPlugin` are present, an interactive Email Management module is mounted at `/_admin/email`:
+
+- **Live Template Preview**: Select any MJML template, edit mock JSON data, and preview rendered responsive HTML.
+- **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/ERRORS.md

@@ -0,0 +1,201 @@
+# Webspresso Framework Exceptions & Error Handling Guide
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+---
+
+## ⚠️ STRICT RULE: Throw Semantic Errors (NO Generic `new Error()` or Manual `res.status`)
+
+- **NEVER** return manual error payloads like `return res.status(404).json(...)` inside services or loaders.
+- **NEVER** throw a generic `throw new Error('Not found')` for business or client-facing issues. In production, unmapped `Error` instances are automatically masked as `500 Internal Server Error` with stack traces hidden!
+- **ALWAYS** throw semantic framework exceptions:
+  - `throw new NotFoundError('Item not found')` → returns HTTP 404
+  - `throw new ValidationError('Invalid data', { fields: { ... } })` → returns HTTP 422
+  - `throw new UnauthorizedError('Please log in')` → returns HTTP 401
+  - `throw new ForbiddenError('Access denied')` → returns HTTP 403
+  - `throw new BadRequestError('Invalid query')` → returns HTTP 400
+
+---
+
+## 1. Overview & Exception Hierarchy
+
+Webspresso features a centralized, lightweight, zero-dependency exception hierarchy inspired by Django's failure domain separation. Thrown synchronous and asynchronous exceptions are automatically caught by the global error boundary, normalized, and formatted as standardized JSON responses for API routes or styled HTML pages for web clients.
+
+```text
+WebspressoError (base class with cause, code, details)
+├── ConfigurationError (bootstrap & config errors)
+├── PluginError (plugin lifecycle & dependency errors)
+├── ValidationError (validation failures with fields, 422 default)
+├── SecurityError (suspicious requests, CSRF/cookie tampering, 400 default)
+├── RequestError
+│   └── RequestAbortedError (client socket disconnection, 499 default)
+├── RouterError
+│   ├── RouteNotFoundError (404 URL resolution error)
+│   └── RouteGenerationError (named route generation error)
+└── HttpError (base for HTTP-mapped exceptions)
+    ├── BadRequestError (400)
+    ├── UnauthorizedError (401)
+    ├── ForbiddenError (403)
+    ├── NotFoundError (404)
+    ├── MethodNotAllowedError (405)
+    ├── ConflictError (409)
+    ├── PayloadTooLargeError (413)
+    ├── UnsupportedMediaTypeError (415)
+    ├── UnprocessableEntityError (422)
+    └── TooManyRequestsError (429)
+```
+
+---
+
+## 2. Public Imports & Subpath
+
+```js
+import {
+  WebspressoError,
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  MethodNotAllowedError,
+  ConflictError,
+  PayloadTooLargeError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+  ValidationError,
+  ConfigurationError,
+  PluginError,
+  SecurityError,
+  RequestAbortedError,
+  RouteNotFoundError,
+  RouteGenerationError,
+} from 'webspresso';
+
+// Or via subpath:
+import { NotFoundError, ValidationError } from 'webspresso/errors';
+```
+
+---
+
+## 3. Usage Examples
+
+### 3.1 HTTP Exceptions in API Handlers
+```js
+// pages/api/users/[id].get.js
+import { NotFoundError } from 'webspresso';
+
+module.exports = async function handler(req, res) {
+  const user = await req.db.getRepository('User').findById(req.params.id);
+  if (!user) {
+    throw new NotFoundError('User not found', {
+      code: 'USER_NOT_FOUND',
+    });
+  }
+  res.json({ user });
+};
+```
+
+### 3.2 Structured Validation Errors (422)
+```js
+import { ValidationError } from 'webspresso';
+
+throw new ValidationError('Validation failed', {
+  code: 'INVALID_INPUT',
+  fields: {
+    email: ['Invalid email address'],
+    age: ['Must be at least 18'],
+  },
+});
+```
+
+### 3.3 Custom Error Classes
+```js
+import { HttpError } from 'webspresso';
+
+export class PaymentRequiredError extends HttpError {
+  constructor(message = 'Payment Required', options = {}) {
+    super(402, message, {
+      code: options.code || 'PAYMENT_REQUIRED',
+      expose: true,
+      ...options,
+    });
+  }
+}
+```
+
+### 3.4 Custom Error Handler (`app.setErrorHandler`)
+```js
+const { app } = createApp({ pagesDir: './pages' });
+
+app.setErrorHandler(async (err, req, res, next) => {
+  if (err instanceof ValidationError) {
+    return res.status(422).json({
+      success: false,
+      errors: err.fields,
+    });
+  }
+  // Re-throwing or returning unhandled delegates to Webspresso default handler
+});
+```
+
+---
+
+## 4. Response Contract & Production Masking
+
+### Default JSON Contract:
+```json
+{
+  "status": 404,
+  "error": "Not Found",
+  "message": "User not found",
+  "code": "USER_NOT_FOUND"
+}
+```
+
+### Development vs Production:
+- **Production (`NODE_ENV === 'production'`)**: 500 errors are masked to `"Internal Server Error"`. `stack`, `cause`, and internal file paths are never exposed to clients.
+- **Development**: Returns `stack`, `cause`, and a structured `trace` object identifying the exact route, module, source file, and execution phase.
+
+---
+
+## 5. Route Tracing & Request ID Observability
+
+Webspresso automatically correlates every request and enriches thrown errors with route-level execution metadata:
+
+### 5.1 Request Correlation ID (`req.id` / `X-Request-Id`)
+Every incoming request is assigned a unique UUID (`req.id`) available on `req.id` and returned in the `X-Request-Id` response header:
+```javascript
+// Access in services, loaders, or logs:
+const reqId = req.id; // e.g. "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+```
+
+### 5.2 Context-Enriched Trace Object (Development Mode)
+When an exception occurs during request execution in `definePage`, `defineApi`, or a feature module, the development JSON payload contains an explicit `trace` object:
+
+```json
+{
+  "status": 500,
+  "error": "Internal Server Error",
+  "message": "Database query failed",
+  "trace": {
+    "route": "/api/auth/me",
+    "method": "GET",
+    "source": "src/modules/auth/api/me.get.js",
+    "module": "auth",
+    "phase": "handler",
+    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+  },
+  "stack": "Error: Database query failed\n    at ...",
+  "cause": null
+}
+```
+
+### 5.3 Visual Console Error Banners
+In server logs, 500 errors are automatically highlighted with visual banners pinpointing the root cause:
+```txt
+[webspresso] 🚨 Error at GET /api/auth/me [module: auth] (reqId: 9b1deb4d-3b7d-...)
+  Source: src/modules/auth/api/me.get.js
+  Phase:  handler
+```
+

package/.agents/MCP.md

@@ -0,0 +1,103 @@
+# Webspresso Model Context Protocol (MCP) Guide
+
+The **Model Context Protocol (MCP)** plugin (`plugins/mcp`) connects Webspresso applications directly to AI agents, IDE assistants (Antigravity, Claude Desktop, Cursor, Zed, Windsurf), and autonomous coding tools.
+
+---
+
+## 1. Overview & Architecture
+
+Webspresso's architecture seamlessly bridges to MCP:
+- **Services (`services/`) → MCP Tools**: Every service defined in `services/` is automatically converted into an MCP tool with full JSON Schema input validation derived from its Zod `schema`.
+- **ORM Models (`models/`) → MCP Tools & Resources**: Models defined with `defineModel` provide query tools (`orm_find`, `orm_findById`), mutation tools (`orm_create`, `orm_update`, `orm_delete`), metadata tools (`orm_describe_model`), and resources (`webspresso://models`, `webspresso://models/{model}`, `webspresso://schema`).
+- **System Context → MCP Resources**: `webspresso://routes` (file routes, API routes, HTTP methods), `webspresso://services` (catalog of services), and `webspresso://health` (system metrics).
+- **Dual Transport**:
+  - **Stdio (`webspresso mcp`)**: Standard input/output JSON-RPC 2.0 lines for local IDEs and CLI.
+  - **HTTP & SSE (`/_mcp/sse`, `/_mcp/messages`, `/_mcp`)**: Server-Sent Events stream and Streamable HTTP for remote or web-accessible agents.
+
+---
+
+## 2. Using the Plugin in Webspresso App
+
+```javascript
+const { createApp, mcpPlugin } = require('webspresso');
+const db = require('./models');
+
+const { app } = createApp({
+  db,
+  plugins: [
+    mcpPlugin({
+      path: '/_mcp', // default: '/_mcp'
+      auth: {
+        token: process.env.MCP_SECRET_TOKEN, // Bearer token validation
+        localhostOnly: true, // Only allow connections from localhost
+      },
+      services: {
+        include: ['user.*', 'catalog.*'], // optional filter
+        readOnly: false, // set true to disable mutation services
+      },
+      orm: {
+        readOnly: false, // set true to allow only find/describe queries
+      },
+      discovery: true, // auto-discover custom mcp/ folder
+    }),
+  ],
+});
+```
+
+---
+
+## 3. CLI Command: `webspresso mcp`
+
+Start the MCP server over Stdio without starting the web server:
+
+```bash
+# Start MCP server over stdio
+npx webspresso mcp
+
+# Restrict to read-only mode (prevent mutations)
+npx webspresso mcp --read-only
+
+# Print configuration snippet for Claude Desktop / Cursor
+npx webspresso mcp --print-config
+```
+
+### IDE Configuration
+
+Add to `claude_desktop_config.json` or `.cursor/mcp.json` or Antigravity IDE `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-webspresso-app": {
+      "command": "npx",
+      "args": ["webspresso", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 4. Custom Tools, Resources, and Prompts (`mcp/` folder)
+
+When `discovery: true` (default), Webspresso scans the project's `mcp/` directory:
+
+```
+mcp/
+├── tools/
+│   └── deploy_preview.js   # exports { name, description, inputSchema, handler }
+├── resources/
+│   └── docs.js             # exports { uri, name, description, handler }
+└── prompts/
+    └── review_code.js      # exports { name, description, arguments, handler }
+```
+
+### Programmatic Registration via Runtime API
+```javascript
+const mcp = app.usePlugin('mcp'); // or ctx.mcp inside plugins
+mcp.registerTool({
+  name: 'custom_action',
+  description: 'Does something custom',
+  handler: async (args, ctx) => { ... },
+});
+```