webspresso 0.0.108 → 0.0.110

package/.agents/ERRORS.md

@@ -1,260 +0,0 @@
-# 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
-```
-
----
-
-## 6. Directory-Level Error Boundaries (`_error.njk` & `_error.js`)
-
-In addition to API JSON errors and the top-level 500 error page, Webspresso provides **Directory-Level Error Boundaries** for SSR pages (similar to Next.js `error.js` or Nuxt `error.vue`):
-
-```
-pages/
-├── _layout.njk                # Root site layout
-├── _error.njk                 # Global site error fallback
-└── dashboard/
-    ├── _layout.njk            # Dashboard layout (sidebar, header)
-    ├── _error.njk             # Dashboard-scoped error boundary
-    ├── _error.js              # Optional companion loader
-    ├── billing/
-    │   └── invoices.njk       # If load() fails here...
-    └── settings.njk
-```
-
-### 6.1 Isolated Error Containment
-When an unhandled error is thrown in a page route's `load()`, template rendering, or lifecycle hooks:
-1. Webspresso searches up the directory hierarchy (innermost leaf to root `pages/`) for the nearest `_error.njk`.
-2. The error boundary is rendered **inside** the ancestor cascading layouts (`_layout.njk`), ensuring that headers, sidebars, and navigation remain visible while displaying the isolated error state.
-3. The HTTP response status is preserved from `error.status || error.statusCode || 500` (e.g. throwing `NotFoundError` sets HTTP 404).
-
-### 6.2 Companion Loader (`_error.js`)
-An optional companion `_error.js` can prefetch support data, report errors to monitoring services, or enrich the context:
-
-```javascript
-// pages/dashboard/_error.js
-module.exports = {
-  load: async ({ error, req, res, ctx, db }) => {
-    return {
-      supportEmail: 'support@example.com',
-      incidentId: req.id,
-    };
-  },
-};
-```
-
-### 6.3 Template Context Variables
-Inside `_error.njk`, the following variables are injected:
-- `error`: `{ message, status, statusCode, code, name, details, fields, stack }` (stack is only exposed when `isDev === true`).
-- `route`: `{ routePath, file }`.
-- `req`: `{ path, query, params, method, url }`.
-- `fsy`: Template helper suite.
-- Plus any data returned by companion `_error.js` loader.
-
-### 6.4 Layout Opt-Out
-To render a full-page custom error view without the parent layout, set `layout: false` in `_error.js` or frontmatter:
-```yaml
----
-layout: false
----
-<div class="standalone-error-screen">
-  <h1>{{ error.status }} - {{ error.message }}</h1>
-</div>
-```
-

package/.agents/EVENTS.md

@@ -1,179 +0,0 @@
-# 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/FLAGS.md

@@ -1,118 +0,0 @@
-# Feature Flags & Canary Traffic Splitter (`core/flags`)
-
-Webspresso features an enterprise-grade, zero-dependency **Feature Flag & Canary Traffic Splitting Engine** in `core/flags/`. It enables gradual rollouts, multivariate A/B testing, user/role/domain targeting, and runtime overrides across Nunjucks SSR templates, API endpoints (`defineApi`), service layers, and Edge/Hono adapters.
-
----
-
-## 🎯 Key Capabilities
-
-1. **Sub-Microsecond Deterministic Bucketing**:
-   - FNV-1a 32-bit hashing algorithm (`getBucket`) maps user identifiers to deterministic integer buckets `0 .. 99` across distributed nodes without network calls.
-2. **Flexible Targeting Rules**:
-   - **Boolean Toggles**: `enabled: true | false`.
-   - **Canary Percentage Rollout**: `rollout: 10` (10% of traffic, consistent per user).
-   - **Targeted Whitelists**: `users: ['user_123', 'admin@corp.com']`.
-   - **Role-Based Targeting**: `roles: ['admin', 'beta_tester']`.
-   - **Email Domain Targeting**: `emailDomains: ['acme.com']`.
-   - **Multivariate A/B Variants**: `variants: [{ name: 'blue_button', weight: 50 }, { name: 'green_button', weight: 50 }]`.
-   - **Custom Predicates**: `condition: (ctx) => ctx.plan === 'enterprise'`.
-3. **Multi-Layer Integration**:
-   - **Express / Hono Middleware**: Automatically injects `req.flags`, `req.hasFeature()`, and `req.getVariant()`.
-   - **Nunjucks SSR Templates**: Access via `{{ fsy.hasFeature('new_ui') }}` and `{{ fsy.flag('theme') }}`.
-   - **Declarative API Route Guard**: `defineApi({ flag: 'beta_feature' })` returns HTTP 404 (or configured status) if disabled.
-   - **Environment Variable Overrides**: Instant runtime overrides via `FEATURE_<FLAG_NAME>=true|false`.
-
----
-
-## 🚀 Quick Start
-
-### 1. Application Configuration
-
-```javascript
-const { createApp } = require('webspresso');
-
-const app = createApp({
-  flags: {
-    // 1. Simple toggle
-    dark_mode: true,
-
-    // 2. 20% Canary rollout
-    new_checkout: {
-      rollout: 20,
-    },
-
-    // 3. User & Role targeting
-    ai_assistant: {
-      roles: ['pro', 'admin'],
-      users: ['vip_client_1'],
-    },
-
-    // 4. Multivariate A/B Test
-    pricing_page_test: {
-      variants: [
-        { name: 'control', weight: 50 },
-        { name: 'discount_banner', weight: 50 },
-      ],
-    },
-  },
-});
-```
-
-### 2. Nunjucks SSR Templates (`pages/*.njk`)
-
-```nunjucks
-{% if fsy.hasFeature('new_checkout') %}
-  {% include "components/new-checkout.njk" %}
-{% else %}
-  {% include "components/legacy-checkout.njk" %}
-{% endif %}
-
-{% if fsy.flag('pricing_page_test') == 'discount_banner' %}
-  <div class="banner">Special 20% Discount Applied!</div>
-{% endif %}
-```
-
-### 3. File-Based API Endpoints (`pages/api/...`)
-
-```javascript
-const { defineApi } = require('webspresso');
-
-module.exports = defineApi({
-  // Automatically blocks request with HTTP 404 if flag is disabled
-  flag: 'ai_assistant',
-  handler: async (req, res, ctx) => {
-    // Also accessible inside ctx or req
-    const isVip = ctx.hasFeature('vip_access');
-    return res.json({ success: true, isVip });
-  },
-});
-```
-
-### 4. Route Guard Middleware
-
-```javascript
-const { createFeatureFlagManager } = require('webspresso');
-
-const flags = createFeatureFlagManager({
-  flags: { secret_admin: { roles: ['admin'] } },
-});
-
-// Use as standalone route middleware
-app.get('/admin/secret', flags.guard('secret_admin', { statusCode: 403 }), (req, res) => {
-  res.send('Welcome, Admin!');
-});
-```
-
----
-
-## ⚙️ Environment Overrides
-
-Flags can be overridden at runtime without code deployment or restart:
-
-```bash
-# Enable flag
-FEATURE_NEW_CHECKOUT=true npm start
-
-# Disable flag
-FEATURE_NEW_CHECKOUT=false npm start
-```

package/.agents/HEALTH.md

@@ -1,118 +0,0 @@
-# Cloud & Kubernetes Health & Readiness Probes (`core/health`)
-
-Webspresso includes a zero-dependency, Docker & Kubernetes-native health inspection system. It provides standard liveness (`/healthz`), readiness (`/readyz`), and combined diagnostics endpoints with automatic database pings, background worker queue checks, event loop delay metrics, and instant graceful shutdown draining integration.
-
----
-
-## 🎯 Key Capabilities
-
-1. **Kubernetes Liveness Probe (`/healthz`)**:
-   - Confirms process vitality and responsiveness.
-   - Gathers memory footprint (`rss`, `heapUsed`, `heapTotal` formatted and raw bytes), process uptime, PID, platform, and event loop lag statistics (`meanMs`, `maxMs`, `p99Ms`).
-   - If event loop delay exceeds threshold (`eventLoopThresholdMs`), flags status as `degraded`.
-
-2. **Kubernetes Readiness Probe (`/readyz`)**:
-   - Confirms the container is fully prepared to handle live client traffic.
-   - **Database Connectivity**: Pings active Knex instance (`SELECT 1`) with timeout protection.
-   - **Queue Readiness**: Probes worker queue instance status.
-   - **Custom Probes**: Executes user-registered async checks concurrently (`checks: { redis, stripe }`).
-   - Returns `HTTP 200` (`{ ready: true, status: 'ready' }`) when all components are healthy.
-   - Returns `HTTP 503` (`{ ready: false, status: 'unhealthy', checks: ... }`) if any component fails.
-
-3. **Graceful Draining Integration (`ShutdownManager`)**:
-   - As soon as the server enters shutdown draining (`app.close()` or `SIGTERM`/`SIGINT`), `/readyz` immediately returns `HTTP 503` (`{ ready: false, status: 'draining' }`).
-   - Cloud load balancers (AWS ALB, K8s Ingress, Google Cloud, Cloudflare) immediately stop routing new traffic to this instance, while existing active requests drain cleanly without dropping a single connection.
-
----
-
-## 🚀 Configuration Examples
-
-### 1. Simple Enablement
-
-```javascript
-const { createApp } = require('webspresso');
-
-const app = createApp({
-  pagesDir: 'pages',
-  // Enables /healthz (liveness), /readyz (readiness), and /health (combined)
-  healthCheck: true,
-});
-```
-
-Shorthand custom path:
-```javascript
-const app = createApp({
-  pagesDir: 'pages',
-  healthCheck: '/api/status', // Mounts combined status on /api/status
-});
-```
-
-### 2. Full Production Configuration
-
-```javascript
-const app = createApp({
-  pagesDir: 'pages',
-  db: myDatabaseInstance,
-  queue: myQueueInstance,
-  healthCheck: {
-    enabled: true,
-    path: '/healthz',               // Liveness probe URL
-    readyPath: '/readyz',           // Readiness probe URL
-    combinedPath: '/health',        // Diagnostic summary URL
-    db: true,                       // Automatically probe database (SELECT 1)
-    queue: true,                    // Automatically probe worker queue
-    eventLoopLag: true,             // Monitor event loop delay
-    eventLoopThresholdMs: 300,      // Lag threshold in ms
-    timeoutMs: 2500,                // Probe timeout before marking down
-    checks: {                       // Custom dependency probes
-      redis: async () => redisClient.ping(),
-      stripe: async () => checkStripeHealth(),
-    },
-    headers: {
-      'Cache-Control': 'no-store, no-cache, must-revalidate',
-      'X-Content-Type-Options': 'nosniff',
-    },
-  },
-});
-```
-
----
-
-## ☸️ Kubernetes Pod Spec Example
-
-```yaml
-livenessProbe:
-  httpGet:
-    path: /healthz
-    port: 3000
-  initialDelaySeconds: 5
-  periodSeconds: 10
-  timeoutSeconds: 3
-  failureThreshold: 3
-
-readinessProbe:
-  httpGet:
-    path: /readyz
-    port: 3000
-  initialDelaySeconds: 2
-  periodSeconds: 5
-  timeoutSeconds: 2
-  failureThreshold: 2
-```
-
----
-
-## 🔍 Programmatic Inspection
-
-Access health state directly in code or CLI scripts:
-
-```javascript
-// Get complete diagnostic payload
-const status = await app.getHealthStatus();
-console.log('Liveness:', status.liveness);
-console.log('Readiness:', status.readiness);
-
-// Or via healthManager
-const liveness = await app.healthManager.getLiveness();
-const readiness = await app.healthManager.getReadiness();
-```