webspresso 0.0.108 → 0.0.110

package/.agents/ADMIN.md

@@ -1,426 +0,0 @@
-# Mithril.js Admin Panel Customization & Extension Guide
-
-Webspresso includes a customizable, zero-build Mithril.js Single Page Application (SPA) Admin Panel (`plugins/admin-panel`). It provides automatic CRUD interfaces for ORM models and supports extension points for custom pages, widgets, custom field renderers, actions, and client-side component injections.
-
----
-
-## 1. Architecture & Session Isolation
-
-The Admin Panel operates as a self-contained Mithril.js SPA mounted at `/_admin`.
-
-- **Isolated Auth Session**: Admin staff authentication uses a dedicated session key (`req.session.adminUser`), isolated from public site user sessions (`req.user`).
-- **Auth Endpoints**:
-  - `POST /_admin/api/auth/setup` — Initial staff account setup (disabled once first admin exists).
-  - `POST /_admin/api/auth/login` — Staff authentication.
-  - `POST /_admin/api/auth/logout` — Terminate admin session.
-  - `GET /_admin/api/auth/me` — Current authenticated staff user details.
-  - `GET /_admin/api/auth/check` — Check if admin setup is required.
-
----
-
-## 2. Model Admin Metadata (`defineModel`)
-
-Configure model behavior in the Admin Panel using the `admin` property when calling `defineModel`:
-
-```js
-import { defineModel, zdb } from 'webspresso';
-
-export default defineModel({
-  name: 'Product',
-  table: 'products',
-  schema: zdb.schema({
-    id: zdb.id(),
-    name: zdb.string(),
-    slug: zdb.string(),
-    price: zdb.number(),
-    status: zdb.string({ default: 'active' }),
-  }),
-  admin: {
-    enabled: true,           // Expose in Admin navigation
-    label: 'Products',       // Display label
-    icon: '📦',             // Navigation icon
-    displayField: 'name',    // Field used for title/representation
-    searchFields: ['name', 'slug'], // Fields searched by table search input
-    filterable: ['status'],  // Column filters enabled in table header
-    defaultSort: { column: 'id', order: 'desc' },
-    sortableColumns: ['name', 'price'], // Optional whitelist of sortable columns
-    sortable: true,          // Set false to disable table sorting completely
-    readOnly: false,         // Disable create/edit/delete actions
-    
-    // Django Admin-inspired Features:
-    inlines: [               // Parent-child relational editing (Tabular/Stacked)
-      {
-        model: 'ProductVariant',
-        foreignKey: 'product_id',
-        fields: ['sku', 'price', 'inventory'],
-        title: 'Variants',
-      },
-    ],
-    listEditable: ['price', 'status'], // Direct table row quick-edit without opening edit form
-    dateHierarchy: 'created_at',        // Period drilldown navigation (Years -> Months -> Days)
-    listFilter: ['status'],             // Faceted filtering with record counts per value
-    actions: [                          // Declarative model-level bulk operations
-      {
-        id: 'mark-active',
-        label: 'Mark as Active',
-        handler: async ({ ids, repo, db, req, user }) => {
-          for (const id of ids) {
-            await repo.update(id, { status: 'active' });
-          }
-          return { updated: ids.length };
-        },
-      },
-    ],
-  },
-});
-```
-
-### 3-State Table Column Sorting
-Table column headers support interactive 3-state cycling:
-1. `Unsorted` (default, `↕` icon)
-2. `ASC` (1st click, `▲` icon)
-3. `DESC` (2nd click, `▼` icon)
-4. `Unsorted` (3rd click, reverts to default primary key order)
-
-Column sortability can be configured per-column:
-- `zdb.string({ sortable: true })` / `zdb.text({ sortable: false })`
-- `zdb.string().config({ sortable: false })`
-
----
-
-## 3. Admin REST API (`/_admin/api/*`)
-
-The Admin SPA communicates with the backend via JSON REST endpoints:
-
-- `GET /_admin/api/models` — List all models exposed to admin with schemas & metadata.
-- `GET /_admin/api/models/:modelName/records` — List paginated records (query params: `page`, `limit`, `search`, `filter`, `sort`, `year`, `month`, `day`).
-- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details (auto-loads `_inlines` if defined).
-- `POST /_admin/api/models/:modelName/records` — Create new record (syncs `_inlines` automatically).
-- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record (syncs `_inlines` updates, additions, and deletions with `_delete: true`).
-- `DELETE /_admin/api/models/:modelName/records/:id` — Delete record (soft or hard delete).
-- `POST /_admin/api/models/:modelName/records/:id/restore` — Restore soft-deleted record.
-
-### Inline Model Relational Endpoints (Django Inlines)
-- `GET /_admin/api/models/:model/records/:id/inlines/:inlineModel` — List child items belonging to parent record.
-- `POST /_admin/api/models/:model/records/:id/inlines/:inlineModel` — Create a child item attached to parent.
-- `PUT /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Update specific child item.
-- `DELETE /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Delete child item.
-
-### Fast Inline & Batch Editing (Django `list_editable`)
-- `PATCH /_admin/api/models/:model/records/:id/quick-edit` — Quickly update allowed `listEditable` columns for a single row without full form submission.
-- `PATCH /_admin/api/models/:model/records/batch-edit` — Save multiple table row edits simultaneously (`{ updates: [{ id, changes }] }`).
-
-### Date Hierarchy & Faceted Filters (Django `date_hierarchy` & `list_filter`)
-- `GET /_admin/api/models/:model/date-hierarchy` — Drilldown periods with counts (`?year=...&month=...`).
-- `GET /_admin/api/models/:model/filter-facets` — Retrieve distinct values with record counts for `listFilter` columns.
-
-### Model Actions (Django Actions)
-- `POST /_admin/api/models/:model/actions/:actionId` — Execute declarative action on selected record IDs (`{ ids: [...] }`).
-
-
----
-
-## 4. Custom Pages (`registerModule` / `registerPageDir`)
-
-Custom Admin pages support:
-1. **Clean Mithril.js Component Files** (`componentFile` / `component`)
-2. **Native Custom HTML Pages** (`html` / `htmlFile`) — e.g. EUIX Engine, Vue, Alpine apps rendered directly in the DOM with full Tailwind CSS styling.
-3. **External URL Pages** (`url` / `iframeUrl`) — Embedded in clean `<iframe>` containers.
-
-```js
-const { registry } = adminPanelPlugin({ db });
-
-// Example 1: Mithril Component
-registry.registerModule('analytics-report', {
-  label: 'Analytics Report',
-  icon: '📊',
-  category: 'Reports',
-  componentFile: path.join(__dirname, 'admin-pages/analytics/component.js'),
-  layout: true, // Auto-wrap inside Admin layout header & sidebar (set false for full-screen view)
-});
-
-// Example 2: EUIX Engine / Native HTML Page
-registry.registerModule('euix-module', {
-  id: 'euix-module',
-  scripts: ['https://unpkg.com/euixjs@latest/dist/EUIXEngine.umd.js'],
-  pages: [
-    {
-      id: 'euix-counter',
-      title: 'EUIX Counter',
-      path: '/euix-counter',
-      htmlFile: path.join(__dirname, 'admin-pages/euix-counter.html') // Rendered directly into DOM with Tailwind & scripts
-    }
-  ],
-  menu: [
-    { id: 'euix-counter', label: 'EUIX Counter', path: '/euix-counter', icon: 'zap' }
-  ]
-});
-```
-
-### Automatic Directory Discovery (`registerPageDir`)
-Directories containing page folders with `page.json` and `component.js` (or `index.html`) are auto-discovered:
-
-```text
-admin-pages/
-├── analytics/
-│   ├── page.json    # { "id": "analytics", "label": "Analytics", "icon": "📊", "layout": true }
-│   └── component.js # clean Mithril component (export default { view() { return m('div', 'Content'); } })
-└── custom-tool/
-    ├── page.json    # { "id": "custom-tool", "label": "Custom Tool", "icon": "⚡" }
-    └── index.html   # Native HTML file
-```
-
-```js
-registry.registerPageDir(path.join(__dirname, 'admin-pages'));
-```
-
----
-
-## 5. Page & Plugin Title Management
-
-Admin Panel supports configurable base titles, title templates, and dynamic SPA page titles:
-
-### Plugin Configuration
-```js
-adminPanelPlugin({
-  db,
-  title: 'Acme Admin',           // Base title in <title> and header (default: 'Admin Panel')
-  titleTemplate: '%s | %b',      // Format template: %s = page title, %b = base title (default: '%s | %b')
-});
-```
-
-### Module & Page Title Configuration
-When registering modules and custom pages, titles are automatically propagated to navigation and browser document title:
-```js
-adminApi.registerModule({
-  id: 'reports',
-  title: 'Reports & Analytics',   // Module fallback title
-  pages: [
-    {
-      id: 'monthly-report',
-      title: 'Monthly Report',    // Document title -> "Monthly Report | Acme Admin"
-      path: '/reports/monthly',
-      component: ...,
-    },
-    {
-      id: 'live-dashboard',
-      documentTitle: 'Live Monitor (Fullscreen)', // Raw document.title override
-      path: '/reports/live',
-      layout: false,
-      component: ...,
-    }
-  ]
-});
-```
-
-### Dynamic Client-Side Title Helper (`setAdminPageTitle`)
-From any Mithril component or client script:
-```js
-// Dynamic title formatted with template (e.g. "Sales Overview | Acme Admin")
-window.setAdminPageTitle('Sales Overview');
-
-// Custom template override
-window.setAdminPageTitle('Sales Overview', { template: '%s — %b' });
-
-// Raw document title without template
-window.setAdminPageTitle('Sales Overview', { raw: true });
-```
-
----
-
-## 6. Custom Field Renderers (`registerFieldRenderer`)
-
-Register custom display and edit renderers for specific column types:
-
-```js
-registry.registerFieldRenderer('color-picker', {
-  // 1. Table & detail view display
-  display: (value) => m('span.color-badge', { style: { backgroundColor: value } }, value),
-  
-  // 2. Form input editor
-  edit: (value, onChange, fieldConfig) => m('input[type=color]', {
-    value: value || '#000000',
-    oninput: (e) => onChange(e.target.value),
-  }),
-});
-```
-
----
-
-## 7. Dashboard Widgets (`registerWidget`)
-
-Register dashboard widgets for the Admin overview screen:
-
-```js
-registry.registerWidget('recent-orders', {
-  title: 'Recent Orders',
-  width: 'half', // 'full' | 'half' | 'third'
-  componentFile: path.join(__dirname, 'widgets/recent-orders.js'),
-});
-```
-
-### Built-in Dashboard Widgets
-- **`model-stats`**: Model overview cards displaying record counts, column counts, and last update timestamps.
-- **`database-storage`**: Database Storage & Health monitor showing:
-  - Database engine (SQLite, PostgreSQL, MySQL) & active file sizes
-  - Total tables and total record counts across the schema
-  - Storage health status badge with high-volume alerts for unpruned logs
-  - Top tables by row count with visual progress percentage bars
-  - Direct navigation links to model CRUD screens
-- **`quick-actions`**: Fast shortcuts to create new records across enabled models.
-- **`recent-activity`**: Timeline of recent administrative mutations (creates, updates, deletes) powered by `audit_logs` / `admin_activity_logs` with direct links to record changes.
-
----
-
-## 8. Single Record & Bulk Table Actions
-
-Add custom action buttons to model table views:
-
-```js
-// Single record button action
-registry.registerAction('Product', {
-  id: 'duplicate',
-  label: 'Duplicate',
-  icon: '📋',
-  handler: async (record, { request, reload }) => {
-    await request.post(`/api/products/${record.id}/duplicate`);
-    reload();
-  },
-});
-
-// Record action with navigation redirect (e.g. audit-timeline)
-registry.registerAction('Product', {
-  id: 'view-history',
-  label: 'History',
-  icon: 'clock',
-  handler: async (record, model) => {
-    return { redirect: `/_admin/audit-log?model=${model.name}&recordId=${record.id}` };
-  },
-});
-
-// Bulk multi-select table action
-registry.registerBulkAction('Product', {
-  id: 'bulk-archive',
-  label: 'Archive Selected',
-  icon: '📦',
-  handler: async (selectedIds, { request, reload }) => {
-    await request.post('/api/products/bulk-archive', { ids: selectedIds });
-    reload();
-  },
-});
-```
-
----
-
-## 9. Client Components & Custom Client Script Injections
-
-Inject custom client-side JavaScript / Mithril components into the Admin SPA runtime:
-
-```js
-registry.registerClientComponent('custom-banner', `
-  window.AdminRegistry.registerWidget('custom-banner', {
-    title: 'Custom Banner',
-    view: function() {
-      return m('.banner', 'Welcome to Custom Admin!');
-    }
-  });
-`);
-```
-
----
-
-## 10. Offline & Zero-CDN Architecture
-
-The Admin Panel is 100% self-contained and operates completely offline without external CDN dependencies (`unpkg.com`, `cdn.jsdelivr.net`, or `cdn.tailwindcss.com`):
-- **Vendored Static Assets (`plugins/admin-panel/vendor/`)**:
-  - `mithril.min.js` — Client SPA runtime (~28 KB).
-  - `tailwind.min.js` — Client utility compiler & style runtime (~412 KB).
-  - `quill.min.js` & `quill.snow.min.css` — Rich-text WYSIWYG editor.
-- **Local Asset Serving**: Served locally at `GET /_admin/vendor/:file` with proper MIME types, path traversal protections, and `Cache-Control: public, max-age=86400` caching.
-- **Hardened CSP**: Works in air-gapped / intranet environments with strict `'self'` Content Security Policy without leaking third-party network requests.
-
----
-
-## 11. Toast Notifications, Modal Confirmations & Session Expiry UX
-
-The Admin SPA includes a built-in reactive notification and modal system that replaces intrusive browser `alert()` and `confirm()` dialogs.
-
-### Toast Notifications (`window.notify`)
-Display auto-dismissing, animated toasts in the top-right corner with pause-on-hover:
-
-```js
-// Available on window.notify or as global helpers: notifySuccess, notifyError, notifyWarning, notifyInfo
-notify.success('Record created successfully');
-notify.error('Failed to save record: Validation error');
-notify.warning('Please review unsaved changes');
-notify.info('Export started in the background');
-
-// Custom duration (TTL in milliseconds, default 4000ms):
-notify.success('Saved!', 2000);
-```
-
-### Confirmation Modal (`window.confirmModal` / `confirmAction`)
-Display an accessible, styled modal dialog returning a Promise resolving to `true` or `false`:
-
-```js
-// Destructive confirmation (danger: true highlights the confirm button in red)
-const confirmed = await confirmAction({
-  title: 'Delete User',
-  message: 'Are you sure you want to permanently delete this user?',
-  confirmText: 'Delete',
-  cancelText: 'Cancel',
-  danger: true,
-});
-
-if (confirmed) {
-  await api.delete(`/users/${id}`);
-  notify.success('User deleted');
-}
-```
-
-### Session Expiration & Intended Return-To Redirection
-When an authenticated staff user's session expires or an API call returns `401 Unauthorized`:
-1. `redirectToLogin('expired')` captures the active route and redirects to `/_admin/#!/login?returnTo=<route>&reason=expired`.
-2. The login screen displays an informational notice banner: *"Your session has expired. Please sign in again."*
-3. After authenticating successfully, the user is automatically redirected to their intended route.
-4. **Open-Redirect Hardening**: All return destinations are strictly validated by `isSafeIntendedRoute(path)` to disallow protocol-relative URLs (`//evil.com`), foreign protocols (`http:`, `javascript:`), or backslashes.
-
----
-
-## 12. Admin Login Brute-Force Protection & Rate Limiting
-
-The Admin Panel includes built-in in-memory rate limiting to defend staff login endpoints against credential stuffing and brute-force password guessing.
-
-### Configuration (`adminPanelPlugin`)
-
-```js
-import { createApp, adminPanelPlugin } from 'webspresso';
-
-const app = createApp({
-  plugins: [
-    adminPanelPlugin({
-      db,
-      // Configure or disable login rate limiting:
-      loginRateLimit: {
-        enabled: true,                  // Default: true
-        maxAttempts: 5,                 // Max failed attempts before blocking (default: 5)
-        windowMs: 15 * 60 * 1000,       // Tracking window (default: 15 minutes)
-        blockDurationMs: 15 * 60 * 1000 // Temporary block duration (default: 15 minutes)
-      },
-    }),
-  ],
-});
-```
-
-To disable rate limiting (e.g. in test or internal automated environments):
-```js
-adminPanelPlugin({ db, loginRateLimit: false });
-```
-
-### Protection Mechanics
-- **IP Tracking**: Tracks failed attempts keyed by client IP (`req.ip` or upstream trusted proxy headers).
-- **Automatic Block**: After `maxAttempts` failed logins within `windowMs`, returns HTTP 429 Too Many Requests with a `Retry-After: <seconds>` response header and JSON error payload.
-- **Success Reset**: A single successful login clears the failed attempt counter for that IP.
-- **Programmatic Reset**: Cleared automatically upon server restart or via `plugin.api.resetLoginAttempts(ip)`.
-
-

package/.agents/AGENTS.md

@@ -1,96 +0,0 @@
-# Webspresso Project Guidelines & Rules
-
-Webspresso is a modern, 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, zero-dependency Dual Authentication (Session + JWT), Graceful Shutdown & Force Close, HTTP Response Compression, Centralized Framework Exceptions, 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`](ROUTING.md) | `pages/api/...` |
-| **SSR HTML Page / Layout / Loader** | [`.agents/ROUTING.md`](ROUTING.md) & [`.agents/STREAMING.md`](STREAMING.md) | `pages/*.njk`, `pages/*.js`, `views/` |
-| **Database Model / Migration / Query** | [`.agents/ORM.md`](ORM.md) | `models/*.js`, `core/orm`, `migrations/` |
-| **Business Logic / Transaction / Service** | [`.agents/SERVICES.md`](SERVICES.md) | `services/` |
-| **Admin Panel (Page, Widget, Action, UI)** | [`.agents/ADMIN.md`](ADMIN.md) | `plugins/admin-panel/` |
-| **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](AUTH.md) | `core/auth/` |
-| **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](QUEUE.md) | `jobs/` |
-| **Decoupled Events & Signals** | [`.agents/EVENTS.md`](EVENTS.md) | `core/events/`, `listeners/` |
-| **Fault Tolerance / Circuit Breaker / Retry** | [`.agents/RESILIENCE.md`](RESILIENCE.md) | `core/resilience/` |
-| **Stateless Scale-Out (Redis Sessions & DB Pool)** | [`.agents/SCALE_OUT.md`](SCALE_OUT.md) | `core/auth/redis-session.js`, `core/orm/pool.js` |
-| **Cloud Secrets (GCP & AWS Secret Manager)** | [`.agents/SECRETS.md`](SECRETS.md) | `core/secrets/`, `bin/commands/secrets-pull.js` |
-| **Cloud Metrics & Distributed Tracing** | [`.agents/METRICS.md`](METRICS.md) | `core/metrics/`, `/metrics` |
-| **Cloud Migration Jobs (Zero-Downtime DB Deploy)** | [`.agents/MIGRATION_JOBS.md`](MIGRATION_JOBS.md) | `bin/commands/add-migration-job.js`, `core/orm/migrate-cloud.js` |
-| **Rate Limiting Engine (Zero-Dependency & Redis)** | [`.agents/RATE_LIMIT.md`](RATE_LIMIT.md) | `core/rate-limit/` |
-| **Feature Flags & Canary Splitter (`core/flags`)** | [`.agents/FLAGS.md`](FLAGS.md) | `core/flags/` |
-| **Ambient Context & Composable Hooks (`core/context`)** | [`.agents/CONTEXT.md`](CONTEXT.md) | `core/context/` |
-| **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.
-
----
-
-## Agent Guidebook Index
-
-This `.agents/` customization root is organized into modular topic guides:
-
-1. **[File-Based Routing & API Routes](.agents/ROUTING.md)** — File-based page routes (`pages/`), method-suffixed API routes (`pages/api/*.get.js`, `*.post.js`), parameter brackets (`[id]`), Zod request schemas, and the strict prohibition of manual `routes/` directories or `app.get()`.
-2. **[Architecture & Structure](.agents/ARCHITECTURE.md)** — File-based routing (`pages/`), Cold Start & AOT Optimizations (`discoverAppRoutes`, `lazyRoutes: true`, `routes.manifest.json`, `templates.compiled.js`, `lazyPlugin`), Asset Management & Versioning (`AssetManager`, `fsy.asset`), ORM models & `zdb` schemas (`core/orm`), Mithril.js Admin Panel SPA (`plugins/admin-panel`), and Plugin Ecosystem.
-3. **[Services Layer](.agents/SERVICES.md)** — File-based auto-discovery (`services/`), Zod validation, declarative `auth` & RBAC guards, automatic ACID transaction propagation (`transaction: true`), timeouts, and memoization.
-4. **[Exceptions & Error Handling](.agents/ERRORS.md)** — Django-inspired framework exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`), central error boundary, `app.setErrorHandler()`, and production error masking.
-5. **[Graceful Shutdown & Lifecycle](.agents/SHUTDOWN.md)** — `ShutdownManager`, `NodeHttpAdapter`, connection draining, force close mode, and reverse-order plugin disposer cleanup.
-6. **[HTTP Response Compression](.agents/COMPRESSION.md)** — Native streaming zlib compression (`server.compression`), Brotli/Gzip/Deflate negotiation, threshold handling, and `res.compress(false)` route opt-out.
-7. **[Dual Authentication System](.agents/AUTH.md)** — Stateful Session + Cookie & Stateless HS256 JWT + Refresh Token Rotation, `req.auth` helpers, and `middleware: ['jwt']` guard integrations.
-8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, `zdb` vs `z` single source of truth, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
-9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 20 built-in official plugins (including `webhooksPlugin`, `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
-10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
-11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
-12. **[Admin Panel Customization](.agents/ADMIN.md)** — Extending Mithril.js Admin Panel SPA (Custom pages `component.js`, custom field renderers, widgets, single & bulk actions).
-13. **[CLI Tooling & Commands](CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `add:docker`, `add:cloudrun`, `add:aws`, `add:cloudflare`, `deploy:check`, `agents:init`.
-14. **[Development & Testing Workflow](.agents/WORKFLOW.md)** — CLI commands, Vitest unit/integration testing, Playwright E2E tests, TypeScript type checking, and zero regression policy.
-15. **[Coding Standards & Conventions](.agents/CONVENTIONS.md)** — Zero external dependencies policy, strict function signature & schema verification, clean component separation, and log traceback inspection rules.
-16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, Distributed Redis, AWS SQS, and Google Cloud Pub/Sub queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.
-17. **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Native HTTP chunked streaming (`res.renderStream()`), deferred data loader slots (`defer: { key: promise }`), and TTFB optimization.
-18. **Polar billing production checklist** — [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md) (env, webhooks, rate limits, external tier hooks, CSP). Plugin reference: [PLUGINS.md § polarPlugin](PLUGINS.md).
-19. **[Decoupled Events & Signals Architecture](.agents/EVENTS.md)** — Zero-dependency enterprise event dispatcher (`core/events`), sync/async/parallel/serial/waterfall dispatch, wildcard listeners (`order.*`), Django-style `Signal` and sender filtering, queue bridging, and listener auto-discovery.
-20. **[HTTP 103 Early Hints](.agents/EARLY_HINTS.md)** — Zero-dependency RFC 8288 / RFC 8297 Early Hints dispatcher (`core/early-hints`), preloading route CSS/JS and fonts before SSR loader execution, `createApp({ earlyHints })`, and `res.earlyHints(links)` / `ctx.earlyHints(links)` helpers.
-21. **[Payload Limits & DoS Protection](.agents/LIMITS.md)** — Zero-dependency request body limits and DoS protection (`core/limits`), `createApp({ limits })`, automatic `PayloadTooLargeError` (HTTP 413) mapping, route overrides (`limits.routes`), streaming bypass, and native HMAC webhook `req.rawBody` capture.
-22. **[Cloud & Kubernetes Health Probes](.agents/HEALTH.md)** — Zero-dependency RFC-compliant liveness (`/healthz`), readiness (`/readyz`), and combined diagnostic (`/health`) probes (`core/health`), event loop lag telemetry, database/queue health monitors, automatic HTTP 503 draining on graceful shutdown, and `createApp({ healthCheck: true })`.
-23. **[LRU & Tagged Cache Engine](.agents/CACHE.md)** — Zero-dependency, memory-bounded in-memory LRU cache (`core/cache`), byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (`getOrSet`), leak-free tag invalidation (`TaggedLruCache`), ORM query cache provider, and `createApp({ cache })`.
-24. **[Enterprise Resilience & Circuit Breaker](.agents/RESILIENCE.md)** — Zero-dependency fault tolerance engine (`core/resilience`), three-state `CircuitBreaker` (`CLOSED`, `OPEN`, `HALF_OPEN`), rolling window failure rate, per-call execution timeout, fallback handlers, and exponential backoff retry engine (`retry`, `withRetry`) with randomized jitter and transient error detection.
-25. **[Structured Cloud Logging & Distributed Tracing](.agents/LOGGING.md)** — Zero-dependency cloud logger (`core/logger`), GCP Cloud Logging, AWS CloudWatch, automatic trace propagation (`x-cloud-trace-context`, `x-amzn-trace-id`, `traceparent`), sensitive key redaction, and `req.logger` child context.
-26. **[Stateless Scale-Out & Database Pool Management](.agents/SCALE_OUT.md)** — Distributed Redis session store (`createRedisSessionStore`), Redis session tracker (`createRedisSessionTracker`), zero-dependency RESP client, serverless DB connection pool optimizer (`normalizeServerlessPoolConfig`), and scale-out preflight audits (`deploy:check`).
-27. **[Cloud Secrets Management](.agents/SECRETS.md)** — Zero-dependency Google Cloud Secret Manager & AWS Secrets Manager/SSM integration (`core/secrets`), in-memory caching with TTL, dot-notation JSON subkeys, process.env hydration, and `webspresso secrets:pull`.
-28. **[Cloud Metrics & Distributed Tracing](.agents/METRICS.md)** — Zero-dependency Prometheus exposition format (`/metrics`), JSON telemetry (`/metrics.json`), HTTP latency histograms, Node.js event loop/memory/pool/cache collectors, and W3C `traceparent` & `x-trace-id` propagation (`core/metrics`).
-29. **[Cloud Migration Jobs & Zero-Downtime Database Deploy](.agents/MIGRATION_JOBS.md)** — Dedicated pre-deploy migration jobs for Cloud Run, AWS ECS, and Kubernetes (`webspresso add:migration-job`), connection retries, and stale lock auto-healing (`webspresso db:migrate --safe`).
-30. **[Native Zero-Dependency Rate Limiting Engine](.agents/RATE_LIMIT.md)** — Framework-agnostic rate limiter (`core/rate-limit`), sliding window in-memory & Redis stores, RFC 6585 standard headers (`RateLimit-*`, `Retry-After`), Express & Hono dual support, and `rateLimit({ window, limit })`.
-31. **[Feature Flags & Canary Traffic Splitter](.agents/FLAGS.md)** — Zero-dependency feature flag and canary rollout engine (`core/flags`), deterministic FNV-1a bucketing, targeting rules (users, roles, email domains), A/B variants, SSR template helpers (`fsy.hasFeature`), and declarative API guards (`defineApi({ flag })`).
-32. **[Ambient Context & Composable Hooks](.agents/CONTEXT.md)** — Zero-dependency execution context powered by `AsyncLocalStorage` (`core/context`), eliminating prop drilling across loaders, services, models, and workers with `useContext`, `useDb`, `useAuth`, `useUser`, `useService`, `useLogger`, `useReq`, `useRes`, `useParams`, `useQuery`, `useTransaction`, and `withContext`.
-
----
-
-## Essential Rules Summary
-
-- **Strict File-Based Routing (NO `routes/` or `app.get()`)**: NEVER create a `routes/` or `src/routes/` directory. NEVER call `app.get()`, `app.post()`, or `express.Router()`. ALL application endpoints MUST be defined inside `pages/` and `pages/api/...` with HTTP method extensions (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
-- **Strict Repository Pattern (NO Raw `db('table')`)**: NEVER write raw Knex table queries in application code. ALWAYS access database models through repositories via `db.getRepository('ModelName')` or `req.db.getRepository('ModelName')` to ensure schema validation, hooks, scopes, and query caching are applied.
-- **Strict Services Layer (NO `controllers/`)**: NEVER create a `controllers/` folder or controller classes. Encapsulate multi-step business logic in `services/domain/action.js` and invoke via `ctx.service('domain.action', input)` to leverage automatic transaction propagation (`transaction: true`) and Zod validation.
-- **Native Dual Auth (NO External JWT/Passport Packages)**: NEVER install `jsonwebtoken`, `passport`, or `express-session`. ALWAYS use native `req.auth` and `webspresso/core/auth` (`middleware: ['jwt']` / `middleware: ['auth']`).
-- **Page Data Loaders (NO Manual `res.render()`)**: NEVER call `res.render()` inside custom handlers for SSR pages. Use companion loaders `pages/*.js` exporting `async function load({ req, res, db, ctx })`.
-- **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`.
-- **Background Jobs (NO BullMQ / `setTimeout`)**: NEVER use unmanaged `setTimeout` or external queues. Place job workers in `jobs/` and dispatch via `req.queue.dispatch()`.
-- **Zero External Dependencies**: Core framework functions (Auth, JWT, CORS, Routing, Errors, Compression, Shutdown, Nunjucks helpers) must rely strictly on native Node.js modules (`crypto`, `path`, `fs`, `events`, `zlib`, `async_hooks`).
-- **Zero Regression Policy**: Always run Vitest tests (`npm test` or `npx vitest run`) before declaring any task complete.
-- **Strict Verification**: Inspect authoritative source files for function signatures and schema definitions before writing consuming code.
-- **Log & Traceback Inspection**: Base all bug fixes strictly on exact runtime error log tracebacks and empirical test output.
-- **`zdb` vs `z` Single Source of Truth (NO `schema: z.object` in Models)**: NEVER wrap model schemas in `z.object({...})`. Pass a clean plain object `schema: { ... }` or functional schema `schema: ({ zdb, z }) => ({ ... })`. ALWAYS use `zdb.*` for persistent database columns in `models/*.js` (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.email()`, etc.) to generate migrations, query filters, and Admin UI controls. Use pure `z.*` ONLY for in-memory request/service payloads (`pages/api/...`, `services/...`). Access raw Zod primitives in models via `zdb.z` without importing `zod`.