webspresso 0.0.95 → 0.0.97

package/.agents/skills/webspresso-orm-and-database/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: webspresso-orm-and-database
+description: >-
+  Define models, run queries, handle transactions, manage relations, and scaffold migrations in
+  Webspresso ORM. Use when writing database models (defineModel), using zdb schema builders,
+  querying repositories (db.getRepository), configuring query cache, soft deletes, and ambient transactions.
+---
+
+# Webspresso ORM & Database Skill
+
+⚠️ **CRITICAL ANTI-PATTERN:** Never write raw Knex table queries (e.g. `db('users')` or `knex('users')`) in application code. Always use Repositories (`db.getRepository('ModelName')`).
+
+---
+
+## 1. Defining Models (`models/*.js`)
+
+```javascript
+const { defineModel, zdb } = require('webspresso');
+
+module.exports = defineModel({
+  name: 'Product',
+  table: 'products',
+  primaryKey: 'id',
+  
+  schema: zdb.object({
+    id: zdb.id(),
+    name: zdb.string().min(1).max(255),
+    slug: zdb.string().unique(),
+    price: zdb.decimal({ precision: 10, scale: 2 }),
+    in_stock: zdb.boolean().default(true),
+    metadata: zdb.json().optional(),
+    user_id: zdb.foreignKey('users.id'),
+    created_at: zdb.timestamp().autoCreate(),
+    updated_at: zdb.timestamp().autoUpdate(),
+    deleted_at: zdb.timestamp().nullable(),
+  }),
+
+  relations: {
+    user: {
+      type: 'belongsTo',
+      model: 'User',
+      foreignKey: 'user_id',
+    },
+    reviews: {
+      type: 'hasMany',
+      model: 'Review',
+      foreignKey: 'product_id',
+    },
+  },
+
+  scopes: {
+    softDelete: true, // enables deleted_at filtering automatically
+    active: (query) => query.where('in_stock', true),
+  },
+
+  hidden: ['metadata.internal_notes'], // stripped from output
+
+  cache: 'auto', // query caching ('auto' | 'smart' | true)
+
+  admin: {
+    enabled: true,
+    label: 'Products',
+    icon: 'package',
+    columns: ['name', 'price', 'in_stock', 'created_at'],
+    search: ['name', 'slug'],
+    filters: ['in_stock', 'user_id'],
+  },
+});
+```
+
+---
+
+## 2. Repositories API
+
+```javascript
+const repo = db.getRepository('Product');
+
+// Single Record Queries
+const item = await repo.findById(id);
+const item = await repo.findOne({ slug: 'espresso-blend' });
+
+// Multiple Records & Filtering
+const activeItems = await repo.find({ in_stock: true });
+
+// Insert & Update (auto-validates with schema & triggers lifecycle hooks)
+const created = await repo.create({
+  name: 'Espresso Blend',
+  slug: 'espresso-blend',
+  price: 14.99,
+  user_id: user.id,
+});
+
+const updated = await repo.update(created.id, { price: 16.99 });
+
+// Deletion (respects softDelete scope)
+await repo.delete(id);
+
+// Fluent Query Builder with Eager Loading & Pagination
+const results = await repo.query()
+  .where('price', '>=', 10)
+  .include('user', 'reviews')
+  .orderBy('created_at', 'desc')
+  .paginate({ page: 1, limit: 20 });
+// Returns: { data: [...], pagination: { total, page, limit, totalPages } }
+```
+
+---
+
+## 3. Ambient Transactions (`AsyncLocalStorage`)
+
+Inside `db.transaction()` or services declared with `transaction: true`, all repository operations automatically bind to the ambient transaction without manual `trx` passing:
+
+```javascript
+await db.transaction(async () => {
+  const user = await db.getRepository('User').create(userData);
+  const account = await db.getRepository('Account').create({ userId: user.id, balance: 100 });
+  // Automatically commits if promise resolves, or rolls back if an exception is thrown
+});
+```

package/.agents/skills/webspresso-routing-and-api/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: webspresso-routing-and-api
+description: >-
+  Build and declare file-based API endpoints and SSR pages in Webspresso using defineApi, definePage,
+  and defineModule. Use when writing route handlers, data loaders (load()), parameter brackets ([id]),
+  Zod input validation, response streaming, and route middleware.
+---
+
+# Webspresso Routing & API Skill
+
+Webspresso uses strictly file-based routing. Never use `express.Router()`, `app.get()`, or a `routes/` directory.
+
+---
+
+## 1. File-Based API Endpoints (`pages/api/...`)
+
+All API routes live in `pages/api/` and use HTTP method extensions:
+- `pages/api/notes.get.js` → `GET /api/notes`
+- `pages/api/notes.post.js` → `POST /api/notes`
+- `pages/api/notes/[id].get.js` → `GET /api/notes/:id`
+- `pages/api/notes/[id].delete.js` → `DELETE /api/notes/:id`
+
+### Standard `defineApi` Contract
+
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      title: z.string().min(1, 'Title is required'),
+      content: z.string().optional(),
+    }),
+    params: z.object({
+      id: z.string().optional(),
+    }),
+    query: z.object({
+      filter: z.string().optional(),
+    }),
+  }),
+  middleware: ['auth'], // optional named middleware string or array of middlewares
+  handler: async (req, res, ctx) => {
+    // 1. Validated input is automatically available in req.input
+    const { title, content } = req.input.body;
+
+    // 2. Repositories and Services are injected
+    const note = await req.db.getRepository('Note').create({ title, content });
+
+    // 3. Return response
+    return res.status(201).json(note);
+  },
+});
+```
+
+---
+
+## 2. SSR HTML Pages & Data Loaders (`pages/...`)
+
+- **Template**: `pages/products/[id].njk`
+- **Companion Loader**: `pages/products/[id].js`
+
+### Companion Loader (`definePage`)
+
+```javascript
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
+  middleware: ['auth'], // optional
+  head: {
+    title: 'Product Details',
+  },
+  load: async ({ req, res, db, ctx }) => {
+    const product = await db.getRepository('Product').findById(req.params.id);
+    if (!product) {
+      throw new ctx.errors.NotFoundError('Product not found');
+    }
+    return { product, title: product.name };
+  },
+});
+```
+
+### Template (`.njk`)
+
+```nunjucks
+{% extends "layout.njk" %}
+
+{% block content %}
+<div class="product-page">
+  <h1>{{ product.name }}</h1>
+  <p class="price">{{ fsy.formatCurrency(product.price) }}</p>
+  <p>{{ product.description }}</p>
+</div>
+{% endblock %}
+```
+
+---
+
+## 3. Modular Domain Architecture (`defineModule`)
+
+Encapsulate feature domains inside `src/modules/` or `modules/`:
+
+```javascript
+const { defineModule } = require('webspresso');
+
+module.exports = defineModule({
+  name: 'billing',
+  pages: './pages',     // auto-discovers pages under /billing/*
+  api: './api',         // auto-discovers API under /api/billing/*
+  services: './services', // auto-discovers services under 'billing.*'
+  middlewares: {
+    paidOnly: (req, res, next) => { ... },
+  },
+});
+```

package/.agents/skills/webspresso-services/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: webspresso-services
+description: >-
+  Encapsulate business logic, validations, transactions, and authorizations in Webspresso services.
+  Use when writing service files (services/domain/action.js), defining schemas (defineService),
+  configuring transaction: true, calling ctx.service() or req.service(), and adding RBAC guards.
+---
+
+# Webspresso Services Layer Skill
+
+⚠️ **CRITICAL ANTI-PATTERN:** Never create a `controllers/` folder or controller classes. Encapsulate multi-step business logic in `services/` and invoke via `ctx.service()` or `req.service()`.
+
+---
+
+## 1. File-Based Auto-Discovery (`services/`)
+
+Files in `services/` map directly to dot-separated service names:
+- `services/user/create.js` → `'user.create'`
+- `services/order/checkout.js` → `'order.checkout'`
+- `services/billing/process-refund.js` → `'billing.process-refund'` (and `'billing.processRefund'`)
+
+---
+
+## 2. Defining Services (`defineService`)
+
+```javascript
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  schema: ({ z }) => z.object({
+    userId: z.number().int().positive(),
+    amount: z.number().positive(),
+    reason: z.string().min(3),
+  }),
+
+  // Optional Declarative Auth / Role Guard
+  auth: ['admin', 'manager'], // or boolean true, or (ctx, input) => boolean
+
+  // Automatic ACID Transaction Propagation
+  transaction: true,
+
+  // Optional Service Result Cache
+  cache: {
+    ttl: 300, // seconds
+    key: (input) => `refund:${input.userId}:${input.amount}`,
+  },
+
+  // Execution Handler
+  handler: async (input, ctx) => {
+    // ctx.db, ctx.service, ctx.user, ctx.logger are automatically injected
+    const userRepo = ctx.db.getRepository('User');
+    const accountRepo = ctx.db.getRepository('Account');
+
+    const user = await userRepo.findById(input.userId);
+    if (!user) {
+      throw new ctx.errors.NotFoundError('User not found');
+    }
+
+    const account = await accountRepo.findOne({ userId: user.id });
+    const updatedAccount = await accountRepo.update(account.id, {
+      balance: account.balance + input.amount,
+    });
+
+    // Nested service call shares the same ambient transaction automatically
+    await ctx.service('audit.log', {
+      action: 'refund.processed',
+      userId: user.id,
+      amount: input.amount,
+    });
+
+    return {
+      success: true,
+      balance: updatedAccount.balance,
+    };
+  },
+});
+```
+
+---
+
+## 3. Invoking Services
+
+From SSR Companion Loaders:
+```javascript
+module.exports = definePage({
+  load: async ({ ctx }) => {
+    const data = await ctx.service('order.summary', { userId: ctx.user.id });
+    return { data };
+  },
+});
+```
+
+From API Route Handlers:
+```javascript
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const result = await req.service('order.checkout', req.input.body);
+    return res.status(200).json(result);
+  },
+});
+```

package/.cursorrules

@@ -0,0 +1,14 @@
+# Cursor Rules for Webspresso
+
+Webspresso is a full-stack Node.js framework with 100% file-based routing, Knex ORM repositories, and zero external dependencies for core utilities.
+
+## Critical Guidelines
+- Complete reference & guidebook: Read `AGENTS.md` and `.agents/AGENTS.md`.
+- Canonical API definitions: Check `index.d.ts`.
+
+## Strict Anti-Patterns & Requirements
+1. **NO `routes/` or `app.get()`**: All API routes belong in `pages/api/...` with method extensions (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
+2. **NO Raw `db('table')`**: Always use `req.db.getRepository('ModelName')` or `db.getRepository('ModelName')`.
+3. **NO `controllers/`**: Encapsulate multi-step business logic in `services/domain/action.js` and call via `ctx.service('domain.action', input)`.
+4. **NO external auth libraries**: Use built-in `req.auth` and `webspresso/core/auth`. Do not install `jsonwebtoken` or `passport`.
+5. **Zero regressions**: Run unit/integration tests with `npx vitest run tests/...` before completing tasks.

package/AGENTS.md

@@ -0,0 +1,175 @@
+# Webspresso Project Guidelines & Rules
+
+Webspresso is a lightweight, zero-dependency-sprawl full-stack Node.js SSR & API framework featuring Next.js/Nuxt-style file-based routing, an intuitive Knex-based ORM, a modular plugin ecosystem, and a customizable Mithril.js SPA Admin Panel.
+
+---
+
+## 🎯 Agent Intent Triage Matrix (Quick Guide Selection)
+
+When tasked with a feature or bugfix, **immediately consult the corresponding topic guide** before writing code:
+
+| Intent / Task | Canonical Topic Guide | Primary Directory / Ground Truth |
+| :--- | :--- | :--- |
+| **New API Route / Endpoint** | [`.agents/ROUTING.md`](.agents/ROUTING.md) | `pages/api/...` |
+| **SSR HTML Page / Layout / Loader** | [`.agents/ROUTING.md`](.agents/ROUTING.md) & [`.agents/STREAMING.md`](.agents/STREAMING.md) | `pages/*.njk`, `pages/*.js`, `views/` |
+| **Database Model / Migration / Query** | [`.agents/ORM.md`](.agents/ORM.md) | `models/*.js`, `core/orm`, `migrations/` |
+| **Business Logic / Transaction / Service** | [`.agents/SERVICES.md`](.agents/SERVICES.md) | `services/` |
+| **Admin Panel (Page, Widget, Action, UI)** | [`.agents/ADMIN.md`](.agents/ADMIN.md) | `plugins/admin-panel/` |
+| **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](.agents/AUTH.md) | `core/auth/` |
+| **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](.agents/QUEUE.md) | `jobs/` |
+| **API Signatures & Types Verification** | [`index.d.ts`](index.d.ts) | **Canonical Ground Truth** |
+
+---
+
+## 🛡️ 4-Step Mandatory Agent Workflow Protocol
+
+Every coding agent working on Webspresso **MUST** follow this 4-step execution discipline:
+
+1. **Discover & Triage**: Identify the relevant topic guide above and inspect existing similar files in the workspace (e.g. `pages/api/`, `models/`, `services/`).
+2. **Contract Adherence**: Follow the exact module contract exported by the framework (`{ schema, middleware, handler }` for routes, `defineModel` for ORM, `defineService` for services).
+3. **Zero External Dependencies**: Use native Node.js standard modules (`crypto`, `path`, `fs`, `zlib`, `events`) and built-in framework utilities. NEVER install ad-hoc npm packages for auth, jwt, routing, or templating.
+4. **Targeted Verification**: Run the specific Vitest test file (`npx vitest run tests/...`) to confirm zero regressions before marking the task complete.
+
+---
+
+## ⚖️ ❌ BAD vs ✅ GOOD Summary Matrix
+
+| Category | ❌ NEVER DO THIS (Anti-Pattern) | ✅ ALWAYS DO THIS (Webspresso Way) |
+| :--- | :--- | :--- |
+| **Routing** | `routes/index.js`, `express.Router()`, `app.get('/api/users')` | `pages/api/users.get.js` exporting `{ schema, handler }` |
+| **Database** | `db('users').where({ id }).select()` (Raw Knex queries) | `db.getRepository('User').findById(id)` |
+| **Business Logic** | `controllers/UserController.js` | `services/user/get.js` → `ctx.service('user.get', input)` |
+| **Auth** | `npm i jsonwebtoken passport express-session` | Built-in `req.auth`, `core/auth`, `middleware: ['jwt']` |
+| **SSR Rendering**| `res.render('profile.njk', data)` inside custom handlers | Companion loader `pages/profile.js` exporting `async function load()` |
+| **Exceptions** | `res.status(404).json({ error: 'Not found' })` | `throw new NotFoundError('User not found')` |
+| **Background** | `setTimeout(...)`, `npm i bullmq` | `jobs/user/welcome.js` → `req.queue.dispatch('user.welcome', data)` |
+
+---
+
+## 1. Codebase Architecture
+
+### 1.1 Core SSR & Routing (`pages/`, `views/`)
+- **File-based Routing**: Pages located in `pages/` automatically map to URL routes (e.g. `pages/index.njk` → `/`, `pages/products/[id].njk` → `/products/:id`).
+- **Data Loaders (`load()`)**: Page routes export `async function load({ req, res, db, ctx })` to fetch data server-side before template rendering.
+- **Templating & Helpers**: Nunjucks (`.njk`) templates rendered with layouts (e.g. `views/layout.njk`). Access helpers via `fsy` object in templates.
+- **Asset Versioning & Cache-Busting**: Configured via `createApp({ assets: { version, manifestPath, prefix } })`. Supports query-string versioning (`?v=1.2.3`), Vite/Webpack manifest resolution (`.vite/manifest.json`), CDN prefixing, and `fsy.asset()`, `fsy.css()`, `fsy.js()`, `fsy.img()` template helpers.
+- **Framework Exceptions & Central Error Boundary**: Built-in exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`, `ConfigurationError`, `PluginError`, `RouteNotFoundError`) and custom handler hook (`app.setErrorHandler`). Async route handlers automatically propagate rejected promises. Production responses mask 500 stack traces and error details.
+- **Graceful Shutdown & Lifecycle Management**: Configured via `createApp({ server: { shutdown: { enabled: true, mode: 'graceful'|'force', timeout: 10000 } } })`. Socket connection tracking, request draining with `Connection: close`, and reverse-order plugin disposer cleanup.
+- **HTTP Response Compression**: Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })` with Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold buffering (1 KB), and route-level opt-out (`res.compress(false)`).
+- **Custom Error & 404 Pages**: Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`. Supports template paths (e.g. `notFound: '404.njk'`) or custom handler functions, passing `{ fsy, locale, isDev, url, method }` to templates.
+- **Middleware & Hooks**: Route lifecycle hooks can be declared per-page or globally via `pages/_hooks.js`.
+- **API Endpoints & Routing Architecture**:
+  - ⚠️ **CRITICAL ANTI-PATTERN: NEVER create a `routes/` or `src/routes/` directory. NEVER use `express.Router()`, `app.get()`, or `app.post()` for application endpoints.**
+  - **100% File-Based Routing**: All API routes MUST be created inside `pages/api/...` with HTTP method extensions:
+    - `pages/api/notes.get.js` → `GET /api/notes`
+    - `pages/api/notes.post.js` → `POST /api/notes`
+    - `pages/api/notes/[id].get.js` → `GET /api/notes/:id`
+    - `pages/api/notes/[id].delete.js` → `DELETE /api/notes/:id`
+  - **Standard API Route Module Contract**:
+    ```javascript
+    const { defineApi } = require('webspresso');
+
+    module.exports = defineApi({
+      schema: ({ z }) => ({
+        body: z.object({ title: z.string().min(1) }),
+        params: z.object({ id: z.string().optional() }),
+      }),
+      middleware: ['auth'], // optional named or functional middleware
+      handler: async (req, res, ctx) => {
+        // req.db and req.service are automatically injected
+        // req.input.body contains the validated payload
+        const item = await req.db.getRepository('Note').create(req.input.body);
+        return res.status(201).json(item);
+      },
+    });
+    ```
+  - **Modular Architecture (`src/modules/` or `modules/`)**:
+    - Encapsulate domain features using `defineModule({ name, pages, api, services, middlewares })`.
+    - Auto-registers routes (`/auth/login`, `/api/auth/login`), services (`'auth.login'`), and scoped middlewares without manual router glue.
+
+### 1.2 Services Layer (`services/`, `src/services/`)
+- **File-based Auto-Discovery**: Services located in `services/` map directly to dot-separated service names (e.g. `services/user/create.js` → `'user.create'`) and camelCase aliases (`'user.reset-password'` & `'user.resetPassword'`).
+- **Declarative Validation & Authorization**: Define optional Zod `schema`, `auth` (boolean, role string/array, predicate), `timeout` (ms), `transaction: true` (ACID transaction propagation across nested calls), and `cache: { ttl, key }`.
+- **Unified Invocation**: Consumed via `ctx.service('service.name', input)` from SSR loaders, `req.service()` in API routes, or standalone `createServiceRegistry()`.
+
+### 1.3 ORM & Database Layer (`core/orm`, `models/`)
+- ⚠️ **CRITICAL ANTI-PATTERN: NEVER use raw Knex queries (e.g. `db('table')` or `knex('table')`) in application code.** Raw queries bypass schema validation, lifecycle hooks, soft-deletes, multi-tenant scopes, hidden fields, and query caching.
+- **ALWAYS Use Repositories**: Accessed via `db.getRepository('ModelName')` or `req.db.getRepository('ModelName')`:
+  - `await repo.findById(id)`
+  - `await repo.find({ status: 'active' })`
+  - `await repo.findOne({ slug })`
+  - `await repo.create(data)` *(validates schema & executes hooks)*
+  - `await repo.update(id, data)`
+  - `await repo.delete(id)` *(respects soft deletes)*
+  - `await repo.query().where('price', '>', 50).paginate({ page, limit })`
+  - `await repo.query().include('user', 'tags').find()` *(eager loading)*
+- **Model Definition**: Defined in `models/*.js` using `defineModel({ name, table, schema, relations, scopes, hidden, admin, cache })`.
+- **Schema & Types**: Built with `zdb` schema builder (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.boolean()`, `zdb.file()`, `zdb.json()`).
+- **Ambient Transactions**: Repositories automatically bind to ambient transactions (`AsyncLocalStorage`) inside `db.transaction()` and services (`transaction: true`) without manual `trx` passing.
+- **Query Caching**: Memory/provider query cache configured per database instance or model (`cache: 'auto'|'smart'|true`).
+- **Migrations**: Database schema changes managed via Knex migrations in `migrations/` (`webspresso db:migrate`).
+
+### 1.4 Admin Panel Architecture (`plugins/admin-panel`)
+- **SPA CRUD Engine**: Modular Mithril.js SPA mounted at `/_admin` powered by `adminPanelPlugin({ db })`.
+- **Admin Module Registration**: Registered using `adminApi.registerModule` or `adminApi.registerPageDir`.
+- **Custom Admin Pages**:
+  - `componentFile`: Path to a clean Mithril component `.js` file.
+  - `pagesDir`: Directory auto-discovery containing page folders with `page.json` and `component.js`.
+  - **Auto Layout Wrapping**: By default (`layout: true`), custom page views are automatically wrapped inside the Admin `Layout` and `Breadcrumb` containers without requiring manual `m(Layout, ...)` nesting. Set `layout: false` for full-screen / custom canvas pages.
+- **Extension Points**:
+  - Custom Field Renderers: `registry.registerFieldRenderer(type, { display, edit })`.
+  - Widgets: `registry.registerWidget(id, config)`.
+  - Actions & Bulk Actions: Single record buttons (`registerAction`) and multi-select table actions (`registerBulkAction`).
+- **Session Isolation**: Admin staff authentication uses a separate session (`req.session.adminUser` / `/_admin/api/auth/*`), isolated from public site auth (`req.user`).
+
+### 1.5 Plugin Ecosystem (`plugins/`)
+Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register(ctx)`, `onRoutesReady(ctx)`):
+- `adminPanelPlugin`: Model CRUD, custom pages, widgets, user management.
+- `fileManagerPlugin`: Media library, directory tree, file preview, and drag-and-drop uploads.
+- `basicAuthPlugin`: Zero-dependency HTTP Basic Authentication (RFC 7617) with named route middleware (`ctx.middlewares.basicAuth`) and global protection.
+- `contentPlugin`: Schema-driven CMS with inline editing and headless API.
+- `uploadPlugin`: Multipart file uploads with local/cloud storage providers.
+- `redirectPlugin`: Configurable HTTP 301–308 redirects.
+- `rateLimitPlugin`: Named rate limiters (`express-rate-limit`).
+- `siteAnalyticsPlugin`: Self-hosted page view analytics and client JS error tracking.
+- `emailPlugin`: MJML template compilation & Nodemailer integration.
+- `polarPlugin`: Polar.sh subscription billing (checkout, portal, webhooks, Customer State sync). Requires `rateLimitPlugin` before polar for rate limiters. Supports `hooks.isPaidUser`, `syncBeforeCheckout`, `syncBillingForAppUser`. See `docs/guides/polar-production-checklist.md`.
+- `auditLogPlugin`: Admin mutation audit logging.
+- `ormCacheAdminPlugin`: Cache inspection and invalidation dashboard.
+- `corsPlugin`: Zero-dependency Cross-Origin Resource Sharing handler.
+- `csrfPlugin`: CSRF token validation and Nunjucks form helpers.
+- `realtimePlugin`: Framework-agnostic, plugin-based realtime layer (`core/realtime`) with WebSocket, SSE, Socket.IO, and distributed Redis Pub/Sub adapters.
+- `restResourcePlugin`: Zero-boilerplate RESTful CRUD API generator directly from ORM models with eager loading, sanitization, filtering, pagination, and soft-delete scoping.
+- `xlsxPlugin`: Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and built-in services (`xlsx.generate`, `xlsx.parse`, `xlsx.exportModel`).
+- `csvPlugin`: RFC 4180 CSV generator, parser, Excel UTF-8 BOM compatibility, formula sanitization, streaming writer (`res.csv`), and built-in services (`csv.generate`, `csv.parse`, `csv.exportModel`).
+
+---
+
+## 2. Development & Testing Workflow
+
+### 2.1 Essential Commands
+- **Dev Server**: `npm run dev` or `webspresso dev`
+- **Run Vitest Unit Tests**: `npm test` or `npx vitest run tests/unit/admin-panel/`
+- **Run Migrations**: `npx webspresso db:migrate`
+- **Project Sanity Check**: `npx webspresso doctor`
+- **Scaffold AI Agent Rules**: `npx webspresso agents:init`
+
+### 2.2 Testing & Quality Assurance
+- **Zero Regression Policy**: Always run unit tests before declaring any task complete.
+- **Targeted Test Execution**: Run specific unit test files during development for fast feedback (`npx vitest run tests/unit/admin-panel/admin-module-files.test.js`).
+- **API Backward Compatibility**: Never break existing `registerModule`, `registerPage`, or `adminApi` contracts. Always add new parameters as optional or backward-compatible enhancements.
+
+---
+
+## 3. Coding Standards & Conventions
+
+1. **Strict Signature & Schema Verification**: Always verify function signatures and object schemas by viewing authoritative source files before calling or extending them.
+2. **File & Component Separation**: Keep client-side components in clean standalone JS files (`component.js` / `componentFile`) rather than escaping inline template strings.
+3. **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.
+4. **Strict File-Based Routing (NO `routes/` or `app.get()`)**: Webspresso is strictly file-based. Never create manual router files (`src/routes/*.js`), never call `app.get()`, and never use `express.Router()`. All application pages belong in `pages/` and all API endpoints belong in `pages/api/` with HTTP method extensions (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
+5. **Strict Repository Pattern (NO Raw `db('table')`)**: Never write raw Knex table queries in route handlers or services. Always use `req.db.getRepository('ModelName')` to ensure schema validation, hooks, scopes, and query caching are applied.
+6. **Strict Services Layer (NO `controllers/`)**: Never create a `controllers/` folder or controller classes. Encapsulate business logic in `services/domain/action.js` and call via `ctx.service('domain.action', input)`.
+7. **Native Dual Auth (NO External JWT/Passport Packages)**: Never install `jsonwebtoken`, `passport`, or `express-session`. Always use native `req.auth` and `webspresso/core/auth`.
+8. **Page Data Loaders (NO Manual `res.render()`)**: Never call `res.render()` inside custom handlers for web pages. Use companion loaders `pages/*.js` exporting `async function load({ req, res, db, ctx })`.
+9. **Semantic Exceptions (NO Generic Errors / Manual Responses)**: Never return manual `res.status(404).json(...)` inside services or loaders. Always throw semantic errors: `NotFoundError`, `ValidationError`, `UnauthorizedError`, `ForbiddenError`.
+10. **Background Jobs (NO BullMQ / `setTimeout`)**: Never use unmanaged `setTimeout` or external queues. Place job workers in `jobs/` and dispatch via `req.queue.dispatch()`.

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# Webspresso — Claude Code Assistant Guide
+
+Webspresso is a lightweight, zero-dependency-sprawl full-stack Node.js SSR & API framework.
+
+> [!IMPORTANT]
+> **Authoritative Rules & Architecture**: Always follow [AGENTS.md](AGENTS.md) and the modular topic guides in [.agents/](.agents/AGENTS.md).
+> **API & Types Ground Truth**: Inspect [index.d.ts](index.d.ts) for exact method signatures.
+
+---
+
+## ⚡ Essential Commands
+
+```bash
+# Run test suite (Node >= 20 required)
+npm test
+npx vitest run tests/unit/
+npx vitest run tests/integration/
+npx vitest run tests/security/
+
+# Development & diagnostics
+npm run dev
+npx webspresso doctor
+npx webspresso db:migrate
+```
+
+---
+
+## 🛡️ Critical Architecture Rules
+
+1. **100% File-Based Routing (NO `routes/` or `app.get()`)**:
+   - All endpoints live in `pages/api/...` with HTTP method extensions:
+     - `pages/api/notes.get.js` → `GET /api/notes`
+     - `pages/api/notes.post.js` → `POST /api/notes`
+     - `pages/api/notes/[id].get.js` → `GET /api/notes/:id`
+     - `pages/api/notes/[id].delete.js` → `DELETE /api/notes/:id`
+   - Contract: `module.exports = { schema: ({ z }) => ({ body, query, params }), middleware: ['auth'], handler: async (req, res) => ... }`
+
+2. **Strict Repository Pattern (NO Raw `db('table')`)**:
+   - Never run raw Knex queries (`req.db('table')`).
+   - Always use `req.db.getRepository('ModelName')` to ensure schema validation, hooks, scopes, and query caching.
+
+3. **Services Layer (NO `controllers/`)**:
+   - Place business logic in `services/domain/action.js` and invoke via `ctx.service('domain.action', input)`.
+
+4. **Zero-Dependency Native Dual Auth**:
+   - Never install `jsonwebtoken`, `passport`, or `express-session`.
+   - Use built-in `req.auth` and `webspresso/core/auth`.
+
+5. **Semantic Exceptions & Page Loaders**:
+   - Throw `NotFoundError`, `ValidationError`, `UnauthorizedError`, `ForbiddenError`.
+   - For SSR pages (`pages/name.njk`), use companion loaders `pages/name.js` exporting `async function load({ req, res, db, ctx })`. Never call `res.render()` manually.
+
+6. **Zero Regression Policy**:
+   - Always run the relevant Vitest tests before declaring any task complete.

package/README.md

@@ -28,7 +28,9 @@ Open **`http://localhost:3000`** in your browser.
 ## ✨ Why Webspresso?
 
 - **Zero-Dependency Sprawl**: Core framework features (Dual Auth, JWT signing, Error handling, Streaming Compression, Graceful Shutdown, Template Helpers) rely strictly on native Node.js standard modules (`crypto`, `path`, `fs`, `events`, `zlib`, `async_hooks`) without bloated dependency trees.
-- **File-Based Routing**: Templates in `pages/` automatically become public URL routes with support for dynamic params (`[id]`) and catch-all wildcards (`[...slug]`).
+- **File-Based Routing & API Suffixes**: Pages and APIs automatically map to clean URLs with dynamic params (`[id]`), wildcards (`[...slug]`), and method suffixes (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
+- **Feature Modules (`defineModule`)**: Domain-driven modular organization for large projects (`modules/{name}/pages`, `api`, `services`, `middleware`).
+- **Modern Page & API Helpers (`definePage`, `defineApi`)**: Declarative Zod request schemas, unified execution context, and automatic JSON response serialization.
 - **Server Data Prefetching (`load()`)**: Page routes export `async function load({ req, res, db, ctx })` to fetch data server-side before template compilation.
 - **Services Layer**: File-based auto-discovery in `services/` with declarative Zod validation, role/predicate authorization guards, and memoization.
 - **Ambient Transactions**: Knex database transactions automatically bind to `AsyncLocalStorage` (`core/orm/transaction.js`). Scoped repositories seamlessly participate in active transactions without manual `trx` passing.
@@ -78,33 +80,35 @@ app.listen(PORT, () => {
 
 ```javascript
 // pages/index.js
-module.exports = {
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
   async load({ req, ctx }) {
     return {
       title: 'Home Page',
       user: req.user || null,
     };
   },
-};
+});
 ```
 
 ### 3. Validated JSON API Endpoint (`pages/api/greet.post.js`)
 ```javascript
-module.exports = {
-  schema({ z }) {
-    return {
-      body: z.object({
-        name: z.string().min(2),
-      }),
-    };
+const { defineApi, z } = require('webspresso');
+
+module.exports = defineApi({
+  schema: {
+    body: z.object({
+      name: z.string().min(2),
+    }),
   },
 
-  async handler(req, res) {
+  async handler(req, res, ctx) {
     // req.input is typed and validated by Zod
-    const result = await req.service('user.greet', req.input.body);
-    res.json(result);
+    const result = await ctx.service('user.greet', req.input.body);
+    return result; // Automatically serialized as JSON (HTTP 200)
   },
-};
+});
 ```
 
 ---

package/bin/commands/admin-password.js

@@ -92,7 +92,8 @@ function registerCommand(program) {
         
         // Hash the password (same rounds as admin panel setup)
         const { hash } = require('../../core/auth/hash');
-        const hashedPassword = await hash(password, 10);
+        const rounds = process.env.NODE_ENV === 'test' ? 4 : 10;
+        const hashedPassword = await hash(password, rounds);
         
         // Update the password
         await db('admin_users')