webspresso 0.0.95 → 0.0.96

package/.agents/QUEUE.md

@@ -0,0 +1,113 @@
+# Webspresso Background Job Queue Guide
+
+Webspresso features a high-performance, zero-dependency background job queue engine (`core/queue`) and plugin (`plugins/queue`), supporting In-Memory, Knex Database, and Distributed Redis adapters, automatic retries with exponential backoff, priority scheduling, and graceful shutdown draining.
+
+---
+
+## 1. Quick Start
+
+### Basic Usage with `core/queue`
+```js
+const { createQueueManager } = require('webspresso/core/queue');
+
+const queue = createQueueManager({
+  concurrency: 4,
+  pollInterval: 200,
+});
+
+// 1. Define job handler
+queue.define('email.send', async (job, ctx) => {
+  const { to, subject, body } = job.data;
+  job.progress(20, 'Preparing template');
+  // ... send email ...
+  job.progress(100, 'Sent');
+  return { delivered: true };
+}, {
+  attempts: 3,
+  backoff: { type: 'exponential', delay: 1000 },
+  timeout: 10000,
+  priority: 20,
+});
+
+// 2. Dispatch job
+await queue.dispatch('email.send', {
+  to: 'user@example.com',
+  subject: 'Welcome!',
+}, {
+  priority: 50,
+  delay: 5000, // delay 5 seconds
+});
+```
+
+---
+
+## 2. Using the Plugin (`plugins/queue`)
+
+```js
+const { createApp, queuePlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    queuePlugin({
+      adapter: 'memory', // 'memory' | 'database' | 'redis'
+      concurrency: 4,
+      jobsDir: './jobs', // Auto-discovers jobs/ directory
+    }),
+  ],
+});
+
+// In Express route handlers:
+app.post('/api/export', async (req, res) => {
+  const job = await req.queue.dispatch('export.users', { format: 'csv' });
+  res.json({ jobId: job.id, status: job.status });
+});
+```
+
+---
+
+## 3. Adapters
+
+### 1. `MemoryQueueAdapter` (Default)
+Zero-dependency in-memory priority queue. Ideal for lightweight background tasks, single-process apps, and development.
+
+### 2. `DatabaseQueueAdapter`
+Persistent queue backed by Knex database table (`webspresso_jobs`) supporting SQLite, PostgreSQL, and MySQL with row-level locking.
+
+```js
+queuePlugin({
+  adapter: 'database',
+  db: appDb,
+  tableName: 'webspresso_jobs',
+});
+```
+
+### 3. `RedisQueueAdapter`
+Distributed queue backed by Redis for multi-instance PM2/Kubernetes cluster deployments.
+
+```js
+queuePlugin({
+  adapter: 'redis',
+  redisClient: redis,
+  prefix: 'app:queue:',
+});
+```
+
+---
+
+## 4. File-Based Auto-Discovery (`jobs/`)
+
+Files placed in `jobs/` are automatically mapped to dot-separated job names:
+- `jobs/email/send.js` → `'email.send'`
+- `jobs/user-report.js` → `'user-report'`
+
+```js
+// jobs/email/send.js
+module.exports = async function(job, ctx) {
+  // job.data
+};
+
+module.exports.options = {
+  attempts: 5,
+  backoff: { type: 'exponential', delay: 2000 },
+};
+```

package/.agents/REALTIME.md

@@ -0,0 +1,213 @@
+# Webspresso Realtime Layer & Adapters Guide
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+Webspresso features a framework-agnostic, plugin-based, adapter-driven Realtime layer (`core/realtime`) designed for universal browser execution with zero SSR hazards.
+
+---
+
+## 1. Architectural Overview
+
+```text
+Webspresso App / Client
+   │
+   ├── AuthManager (Token / Cookie / Custom / None)
+   ├── SubscriptionRegistry (identifier::params composite identity)
+   ├── ReconnectManager (exponential backoff + jitter)
+   │
+   └── Realtime Core
+           │
+           ├── Generic WebSocket Adapter (`core/realtime/adapters/websocket`)
+           ├── SSE Adapter (`core/realtime/adapters/sse`)
+           ├── Socket.IO Adapter (`core/realtime/adapters/socket-io`)
+           └── Redis Pub/Sub Adapter (`core/realtime/adapters/redis`)
+```
+
+### Core Tenets:
+1. **Zero SSR Network Hazards**: Server-side rendering execution never attempts socket connections or touches browser globals.
+2. **Unified Subscription Model**: All realtime technologies share identical public subscription interfaces (`subscribe`, `send`, `perform`, `unsubscribe`).
+3. **Deterministic Subscription Registry**: Subscriptions with identical identifiers and query parameters share channel instances without duplication.
+4. **Secret Sanitization**: Auth tokens and credentials are automatically stripped from error logs (`token=***`).
+5. **Distributed Cluster Sync**: Redis adapter allows multi-process / multi-container instances (PM2 cluster, K8s, Docker) to broadcast across all connected clients.
+
+---
+
+## 2. Core API Reference
+
+### 2.1 Factory Functions (`core/realtime`, `plugins/realtime`)
+```js
+const { createRealtime, realtime, realtimePlugin, redis, websocket, sse, socketIo } = require('webspresso');
+// Or via plugins
+const { realtimePlugin, redis, websocket, sse, socketIo } = require('webspresso/plugins');
+```
+
+- `createRealtime(options)`: Creates a standalone `RealtimeClient`.
+- `realtime(options)`: Universal helper returning `RealtimeClient` with `.plugin` property attached.
+- `realtimePlugin(options)`: Webspresso plugin mounting `app.realtime` and handling shutdown disposers.
+
+### 2.2 Options Configuration
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `adapter` | `RealtimeAdapter` | **Required** | Transport adapter (`websocket()`, `sse()`, `socketIo()`, `redis()`). |
+| `auth` | `Object` \| `false` | `false` | Strategy config: `{ strategy: 'token'|'cookie'|'custom' }`. |
+| `autoConnect` | `boolean` | `true` | Automatically connect when browser environment is ready. |
+| `reconnect` | `Object` | `{ enabled: true }` | Backoff settings (`baseDelay`, `maxDelay`, `factor`, `jitter`). |
+| `isBrowser` | `boolean` | `null` | Force browser mode (testing override). |
+
+---
+
+## 3. Adapters
+
+### 3.1 Generic WebSocket Adapter (`websocket`)
+```js
+const { websocket } = require('webspresso');
+
+const adapter = websocket({
+  url: 'wss://api.example.com/realtime', // string or async (ctx) => url
+  authTransport: 'query', // 'query' | 'header' | 'protocol' | 'message'
+  queryParamName: 'token',
+  messages: {
+    subscribe: ({ identifier, params }) => ({ type: 'subscribe', identifier, params }),
+    send: ({ identifier, data }) => ({ type: 'message', identifier, data }),
+    perform: ({ identifier, action, data }) => ({ type: 'perform', identifier, action, data }),
+  },
+});
+```
+
+### 3.2 Server-Sent Events (SSE) Adapter (`sse`)
+```js
+const { sse } = require('webspresso');
+
+const adapter = sse({
+  url: '/api/realtime/events',
+  queryParamName: 'token',
+});
+```
+*Note: SSE adapter is unidirectional and read-only. Calling `sub.send()` or `sub.perform()` will throw a clear `UNSUPPORTED_CAPABILITY` error.*
+
+### 3.3 Socket.IO Adapter (`socketIo`)
+```js
+const { socketIo } = require('webspresso');
+
+const adapter = socketIo({
+  url: 'https://socket.example.com',
+  path: '/socket.io',
+  socketOptions: { transports: ['websocket'] },
+});
+```
+
+### 3.4 Redis Pub/Sub Distributed Adapter (`redis`)
+Enables cross-process distributed event synchronization across PM2 clusters, Docker containers, and Kubernetes pods:
+
+```js
+const { createApp, realtimePlugin, redis } = require('webspresso');
+const Redis = require('ioredis');
+
+// Option A: Single client instance (adapter will duplicate for subClient)
+const pubsub = new Redis(process.env.REDIS_URL);
+const adapter = redis({
+  redis: pubsub,
+  channelPrefix: 'myapp:rt:',
+});
+
+// Option B: Explicit dual clients
+const pubClient = new Redis(process.env.REDIS_URL);
+const subClient = new Redis(process.env.REDIS_URL);
+const adapter = redis({
+  pubClient,
+  subClient,
+  channelPrefix: 'myapp:rt:',
+});
+
+// Option C: In-memory fallback (useful for local development & unit tests)
+const localAdapter = redis({ inMemory: true });
+
+const { app } = createApp({
+  plugins: [
+    realtimePlugin({
+      adapter,
+      autoConnect: true,
+    }),
+  ],
+});
+
+// Server-side broadcasting to all cluster nodes:
+await app.realtime.adapter.publish('room:general', { message: 'Cluster-wide notification' });
+```
+
+
+---
+
+## 4. Usage Recipes
+
+### 4.1 Webspresso Plugin Integration
+```js
+const { createApp } = require('webspresso');
+const { realtimePlugin, websocket } = require('webspresso/plugins');
+
+const { app } = createApp({
+  plugins: [
+    realtimePlugin({
+      adapter: websocket({ url: '/realtime' }),
+      auth: { strategy: 'cookie' },
+      autoConnect: true,
+    }),
+  ],
+});
+```
+
+### 4.2 Token Authentication & Automatic Refresh
+```js
+const { realtime, websocket } = require('webspresso');
+
+const client = realtime({
+  adapter: websocket({ url: 'wss://api.example.com/realtime' }),
+  auth: {
+    strategy: 'token',
+    getToken: async () => localStorage.getItem('jwt_token'),
+    refreshToken: async () => {
+      const res = await fetch('/api/auth/refresh', { method: 'POST' });
+      const { token } = await res.json();
+      localStorage.setItem('jwt_token', token);
+      return token;
+    },
+    onUnauthorized: (err) => {
+      window.location.href = '/login';
+    },
+  },
+});
+```
+
+### 4.3 Subscriptions & Remote Actions
+```js
+// Subscribe to channel
+const sub = app.realtime.subscribe('project:123', { role: 'editor' }, {
+  connected() {
+    console.log('Connected to project:123 channel');
+  },
+  disconnected() {
+    console.log('Temporarily disconnected');
+  },
+  received(data) {
+    console.log('New event:', data);
+  },
+  rejected(error) {
+    console.error('Subscription rejected:', error);
+  },
+});
+
+// Send raw message
+sub.send({ text: 'Hello!' });
+
+// Perform named action (RPC)
+sub.perform('cursor_move', { x: 120, y: 340 });
+
+// Unsubscribe
+sub.unsubscribe();
+```
+
+### 4.4 Re-authentication Workflow
+```js
+// Refresh credentials and restore all active subscriptions seamlessly
+await app.realtime.reauthenticate();
+```

package/.agents/ROUTING.md

@@ -0,0 +1,292 @@
+# Webspresso File-Based Routing & API Routes
+
+[← Back to AGENTS.md](AGENTS.md)
+
+Webspresso is a full-stack Node.js framework powered by **100% File-Based Routing** (similar to Next.js App Router / Nuxt 3).
+
+---
+
+## ⚠️ STRICT ANTI-PATTERNS (DO NOT DO THIS)
+
+### ❌ BAD vs ✅ GOOD Code Comparison
+
+```javascript
+// ❌ WRONG (Express / Legacy reflex — NEVER DO THIS)
+// File: src/routes/users.js
+const express = require('express');
+const router = express.Router();
+router.get('/users', async (req, res) => {
+  const users = await db('users').select('*'); // Raw query bypasses ORM!
+  res.json(users);
+});
+module.exports = router;
+
+// ✅ CORRECT (Webspresso 100% File-Based Routing)
+// File: pages/api/users.get.js
+'use strict';
+module.exports = {
+  schema: ({ z }) => ({
+    query: z.object({ limit: z.coerce.number().optional().default(20) }),
+  }),
+  middleware: ['auth'], // optional
+  handler: async (req, res) => {
+    const users = await req.db.getRepository('User').find(req.input.query);
+    return res.json({ success: true, data: users });
+  },
+};
+```
+
+1. **NEVER create a `routes/` or `src/routes/` folder.**
+2. **NEVER use `express.Router()` or `require('express').Router()`.**
+3. **NEVER call `app.get()`, `app.post()`, `app.put()`, or `app.delete()` for application endpoints.**
+4. **NEVER use `createApp({ setupRoutes: (app) => ... })` to mount domain/application routes.**
+5. **ALL application routes MUST live inside the `pages/` directory.**
+
+---
+
+## 1. Directory Structure & URL Mapping
+
+All routes are automatically discovered and registered from the `pages/` directory:
+
+| File Path | HTTP Method | URL Route | Description |
+| :--- | :--- | :--- | :--- |
+| `pages/index.njk` | `GET` | `/` | Home page (SSR Nunjucks) |
+| `pages/about.njk` | `GET` | `/about` | Static SSR page |
+| `pages/notes/[id].njk` | `GET` | `/notes/:id` | Dynamic SSR route with param |
+| `pages/api/notes.get.js` | `GET` | `/api/notes` | List notes API endpoint |
+| `pages/api/notes.post.js` | `POST` | `/api/notes` | Create note API endpoint |
+| `pages/api/notes/[id].get.js` | `GET` | `/api/notes/:id` | Get single note API endpoint |
+| `pages/api/notes/[id].put.js` | `PUT` | `/api/notes/:id` | Update note API endpoint |
+| `pages/api/notes/[id].delete.js` | `DELETE` | `/api/notes/:id` | Delete note API endpoint |
+
+### Method Extension Suffixes
+API route filenames **MUST** declare their HTTP method before the `.js` extension:
+- `.get.js`
+- `.post.js`
+- `.put.js`
+- `.patch.js`
+- `.delete.js`
+
+If no method suffix is provided (e.g. `pages/api/notes.js`), it defaults to `GET`.
+
+---
+
+## 2. Standard API Route Contract
+
+Every API route module exports an object with optional `schema`, optional `middleware`, and a `handler` function:
+
+```javascript
+// pages/api/notes.post.js
+'use strict';
+
+module.exports = {
+  // 1. Declarative Input Validation (Zod)
+  schema: ({ z }) => ({
+    body: z.object({
+      title: z.string().min(1, 'Title is required').max(200),
+      content: z.string().min(1, 'Content is required'),
+      isPublic: z.boolean().optional().default(false),
+    }),
+  }),
+
+  // 2. Named Middleware Guards (resolved from ctx.middlewares or global plugins)
+  middleware: ['auth'], // e.g. 'auth', 'jwt', 'basicAuth', or inline (req, res, next) => ...
+
+  // 3. Request Handler
+  handler: async (req, res) => {
+    // req.db: Injected database repository factory
+    // req.service(): Injected service registry invocation helper
+    // req.input.body: Type-safe, validated request payload
+    // req.auth / req.session: Authenticated user session
+
+    const noteRepo = req.db.getRepository('Note');
+    const note = await noteRepo.create({
+      ...req.input.body,
+      userId: req.session?.user?.id || req.auth?.user?.id,
+    });
+
+    return res.status(201).json({
+      success: true,
+      data: note,
+    });
+  },
+};
+```
+
+> [!IMPORTANT]
+> **NEVER use raw Knex queries** like `req.db('notes')` in route handlers. **ALWAYS use repositories**: `req.db.getRepository('Note')`. This guarantees schema validation, lifecycle hooks, soft deletes, and query caching are respected.
+
+---
+
+## 3. Dynamic Route Parameters (`[param]`)
+
+Dynamic path segments use square brackets:
+
+```javascript
+// pages/api/notes/[id].get.js
+'use strict';
+
+module.exports = {
+  schema: ({ z }) => ({
+    params: z.object({
+      id: z.string().min(1),
+    }),
+  }),
+
+  handler: async (req, res) => {
+    const { id } = req.params;
+    const note = await req.db.getRepository('Note').findById(id);
+
+    if (!note) {
+      return res.status(404).json({ error: 'Note not found' });
+    }
+
+    return res.json({ success: true, data: note });
+  },
+};
+```
+
+---
+
+## 4. SSR Page Routes (`load()` Loader)
+
+For server-rendered Nunjucks HTML pages, use `.njk` templates and companion `.js` loader files (or inline `async function load` in a `.js` file):
+
+```javascript
+// pages/notes/[id].js (Companion data loader for pages/notes/[id].njk)
+'use strict';
+
+module.exports = {
+  // Runs server-side before rendering the template
+  async load({ req, res, db, ctx }) {
+    const note = await db.getRepository('Note').findById(req.params.id);
+    if (!note) {
+      return { status: 404, notFound: true };
+    }
+
+    return {
+      note,
+      title: note.title,
+    };
+  },
+};
+```
+
+---
+
+## 5. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
+
+Webspresso supports clean, domain-driven module discovery alongside root-level pages and APIs:
+
+```txt
+src/
+  pages/                -> Global UI pages (definePage or Nunjucks)
+    index.js            -> GET /
+    about.js            -> GET /about
+    docs/[...path].js   -> GET /docs/*path
+
+  api/                  -> Global API endpoints (defineApi)
+    health.get.js       -> GET /api/health
+    users/[id].patch.js -> PATCH /api/users/:id
+
+  modules/              -> Feature-driven modules
+    auth/
+      auth.module.js    -> defineModule({ name: 'auth', ... })
+      pages/
+        login.js        -> GET /auth/login
+        register.js     -> GET /auth/register
+      api/
+        login.post.js   -> POST /api/auth/login
+        me.get.js       -> GET /api/auth/me
+      services/
+        login.js        -> ctx.service('auth.login', input)
+      middleware/
+        auth-guard.js   -> module-local named middleware 'authGuard'
+```
+
+### 5.1 `definePage()` Contract
+```javascript
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
+  middleware: ['authGuard'], // module or global middleware
+  load: async (ctx) => {
+    // ctx: { req, res, params, query, service, db, redirect, fsy, locale, t }
+    if (!ctx.req.user) {
+      return ctx.redirect('/auth/login', 302);
+    }
+    const profile = await ctx.service('user.profile', { id: ctx.req.user.id });
+    return { profile };
+  },
+  head: (data) => ({
+    title: `${data.profile.name}'s Profile`,
+  }),
+  render: (data, ctx) => `
+    <main>
+      <h1>${data.profile.name}</h1>
+      <p>Email: ${data.profile.email}</p>
+    </main>
+  `,
+});
+```
+
+### 5.2 `defineApi()` Contract
+```javascript
+const { defineApi, z } = require('webspresso');
+
+module.exports = defineApi({
+  description: 'Authenticate user and return session',
+  tags: ['Auth'],
+  middleware: ['rateLimit'],
+  schema: {
+    body: z.object({
+      email: z.string().email(),
+      password: z.string().min(8),
+    }),
+  },
+  handler: async (req, res, ctx) => {
+    // req.input.body contains validated payload
+    const result = await ctx.service('auth.login', req.input.body);
+    return res.json(result);
+  },
+});
+```
+
+### 5.3 `defineModule()` Contract
+```javascript
+const { defineModule } = require('webspresso');
+
+module.exports = defineModule({
+  name: 'auth',
+  version: '1.0.0',
+  pages: { prefix: '/auth' },       // default: /auth
+  api: { prefix: '/api/auth' },     // default: /api/auth
+  middlewares: {
+    authGuard: (req, res, next) => {
+      if (!req.user) return res.status(401).json({ error: 'Unauthorized' });
+      next();
+    },
+  },
+});
+```
+
+### 5.4 Route Introspection (`app.routes.list()`)
+Compiled routes are accessible at runtime for tooling, CLI inspection, and documentation:
+```javascript
+const routeList = app.routes.list();
+// [
+//   { method: 'GET', path: '/', type: 'page', source: 'src/pages/index.js' },
+//   { method: 'POST', path: '/api/auth/login', type: 'api', module: 'auth', description: 'Authenticate user' }
+// ]
+```
+
+---
+
+## 6. Summary Checklist for Agents
+
+When a user asks to add or modify endpoints:
+1. Identify the URL and method (e.g. `POST /api/auth/register` or `POST /auth/login`).
+2. Create in `pages/api/...`, `src/api/...`, or `modules/{module}/api/...` with HTTP method extension (`.post.js`).
+3. Use `defineApi()` or `{ schema, middleware, handler }`.
+4. Use `req.db.getRepository(...)` or `ctx.service(...)`.
+5. **NEVER touch `routes/` or create manual Express router files.**