webspresso 0.0.94 → 0.0.96

package/.agents/ADMIN.md

@@ -0,0 +1,225 @@
+# 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
+  },
+});
+```
+
+### 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`).
+- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details.
+- `POST /_admin/api/models/:modelName/records` — Create new record.
+- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record.
+- `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.
+
+---
+
+## 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. 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),
+  }),
+});
+```
+
+---
+
+## 6. 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'),
+});
+```
+
+---
+
+## 7. 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();
+  },
+});
+
+// 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();
+  },
+});
+```
+
+---
+
+## 8. 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!');
+    }
+  });
+`);
+```
+
+---
+
+## 9. 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.
+

package/.agents/AGENTS.md

@@ -0,0 +1,72 @@
+# 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/` |
+| **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/`), 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, 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 18 built-in official plugins (including `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](.agents/CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `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, and Distributed Redis 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).
+
+---
+
+## 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.

package/.agents/ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# Webspresso Codebase Architecture & Structure
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+---
+
+## 1. Core SSR & Routing (`pages/`, `views/`, `src/`)
+
+- **File-based Routing**: Pages located in `pages/` automatically map to URL routes:
+  - `pages/index.njk` → `/`
+  - `pages/products/[id].njk` → `/products/:id`
+  - `pages/api/posts.post.js` → `POST /api/posts`
+  - ⚠️ **CRITICAL ANTI-PATTERN: NEVER create a `routes/` or `src/routes/` directory. NEVER use `express.Router()`, `app.get()`, or `app.post()`. All application endpoints must live under `pages/` and `pages/api/`. See [ROUTING.md](ROUTING.md).**
+- **Data Loaders (`load()`)**: Page routes export `async function load({ req, res, db, ctx })` to fetch data server-side before Nunjucks template rendering.
+- **API Endpoints**: Defined as file route modules in `pages/api/...` exporting `{ schema, middleware, handler }`. Input validation via Zod (`schema: ({ z }) => ({ body, query, params })`) assigns validated data to `req.input.body` / `req.input.query`.
+- **Modern Page & API Helpers (`definePage`, `defineApi`)**:
+  - `definePage({ middleware, load, head, render, layout })`: Pure JS or Nunjucks-backed page routes with unified execution context (`ctx: { req, res, params, query, service, db, redirect, error, fsy, locale, t }`).
+  - `defineApi({ description, tags, schema, middleware, handler })`: REST API endpoints with declarative Zod validation (`req.input`), middleware chain, and automatic JSON response formatting.
+- **Feature Modules (`src/modules/` or `modules/`, `defineModule`)**:
+  - Domain-oriented modular architecture bundling pages, APIs, services, and scoped middlewares into standalone units (`defineModule({ name, pages, api, services, middlewares, onInit, onDestroy })`).
+  - Automatic service prefixing (`'auth.login'`) and scoped route prefixing (`/auth/*`, `/api/auth/*`).
+- **Deterministic Route Compilation & Introspection (`RouteTable`, `app.routes.list()`)**:
+  - Discovered routes are compiled and sorted in deterministic priority order: Static $\to$ Deep Dynamic $\to$ Shallow Dynamic $\to$ Catch-All (`*`).
+  - Detects `METHOD + PATH` collision conflicts at startup and throws descriptive errors.
+  - Inspectable via `app.routes.list()` for CLI tools, documentation generation, and debugging.
+- **Templating & Helpers**: Nunjucks (`.njk`) templates rendered with layouts (e.g. `views/layout.njk`). Access helpers via `fsy` object in templates.
+- **Asset Management & Cache-Busting (`assets`, `AssetManager`, `fsy`)**:
+  - Configured via `createApp({ assets: { version, manifestPath, prefix, publicDir } })` or `configureAssets()`.
+  - **Static Query Versioning (`version`)**: Appends `?v=<version>` (or `&v=...`) to asset URLs (e.g. `version: '1.2.3'` or `process.env.APP_VERSION`) for cache busting.
+  - **Build Manifests (`manifestPath`)**: Automatically resolves hashed output files from Vite (`.vite/manifest.json` mapping `{ "css/style.css": { "file": "assets/style-abc.css" } }`) or Webpack manifests (`{ "/css/style.css": "/dist/style.abc.css" }`). Falls back gracefully if an asset is not in the manifest.
+  - **URL Prefix (`prefix`)**: Prepends CDN or mount path prefixes (e.g. `prefix: 'https://cdn.example.com'` or `'/static'`).
+  - **Template Helpers**:
+    - `{{ fsy.asset('/css/style.css') }}` → Resolves URL with manifest/versioning.
+    - `{{ fsy.css('/css/style.css', { media: 'print' }) | safe }}` → Generates `<link rel="stylesheet" ...>`.
+    - `{{ fsy.js('/js/app.js', { defer: true, type: 'module' }) | safe }}` → Generates `<script ...></script>`.
+    - `{{ fsy.img('/images/logo.png', 'Logo', { loading: 'lazy' }) | safe }}` → Generates `<img ...>` with escaped attributes.
+  - **Page-Level Assets (`pageAssets`)**: Route `load()` can return `stylesheets` and `scripts` arrays, which are promoted to `pageHead` for per-route asset loading.
+- **Framework Exceptions & Central Error Boundary (`core/errors`, `app.setErrorHandler`)**:
+  - Django-inspired hierarchy: `WebspressoError`, `HttpError` (400-429), `ValidationError` (422), `SecurityError`, `RequestAbortedError`, `ConfigurationError`, `PluginError`, `RouteNotFoundError`.
+  - Automatic async error wrapping: all rejected promises in route handlers pass automatically to `next(err)`.
+  - Safe production masking: 500 errors stripped of stack traces and internal messages; exposed strictly in development.
+- **Graceful Shutdown & Lifecycle Management (`core/shutdown`, `ShutdownManager`)**:
+  - Configured via `createApp({ server: { shutdown: { enabled: true, mode: 'graceful'|'force', timeout: 10000 } } })`.
+  - `NodeHttpAdapter` single-listener socket tracking, request draining with `Connection: close`, and reverse-order plugin disposer cleanup.
+- **HTTP Response Compression (`core/compression`)**:
+  - Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })`.
+  - Content negotiation for Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold filtering (1 KB), and `res.compress(false)` route opt-out.
+- **Custom Error & 404 Pages (`errorPages`)**:
+  - Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`.
+  - **404 Not Found (`notFound`)**: Template path (`'404.njk'`) or handler `(req, res, ctx) => ...`.
+  - **500 Server Error (`serverError`)**: Template path (`'errors/500.njk'`) or handler `(err, req, res, ctx) => ...`. Context: `{ fsy, locale, isDev, url, method, error, status }`.
+  - **503 Timeout (`timeout`)**: Template path (`'errors/503.njk'`) or handler `(req, res, ctx) => ...` when `timeout` (e.g. `'30s'`) is configured.
+- **i18n & Localization Engine (`loadI18n`, `createTranslator`, `detectLocale`)**:
+  - Zero-dependency internationalization built on native Node.js `Intl` APIs (`Intl.PluralRules`, `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`).
+  - **Hierarchical Dictionaries**: Global `pages/locales/[locale].json` merged with route-specific overrides `pages/[route]/locales/[locale].json` using `mtime` cache.
+  - **Pluralization**: Automatic CLDR plural selection (`zero`, `one`, `two`, `few`, `many`, `other`) or exact number mapping (`0`, `1`) via `t('key', { count })` or `t.plural(count, forms)`.
+  - **Fallback Chain**: Missing keys fall back to `DEFAULT_LOCALE` (`en`) automatically. Key check via `t.has('key')` or `t.exists('key')`.
+  - **Native Formatters on `t`**: `t.number(1234.5)`, `t.currency(199.99, 'TRY')`, `t.date(d)`, `t.relativeTime(-2, 'day')`.
+  - **Template Helpers & Filter**: `{{ fsy.localeUrl('tr') }}`, `{{ 'nav.home' | t }}`, `{{ t('key') }}`.
+- **Services Layer (`services/`, `ServiceRegistry`, `defineService`, `ctx.service`, `req.service`)**:
+  - Auto-discovered file-based service modules: `services/user/get.js` → `user.get`, `services/post/publish.js` → `post.publish`.
+  - **Shared Request Context**: Service-to-service composition (`ctx.service()`) shares the exact same `ctx` (`ctx.db`, `ctx.auth`, `ctx.session`, `ctx.user`).
+  - **Circular Call Protection**: Automatically tracks service call stack per request and aborts cycles (`user.get -> profile.get -> user.get`).
+  - **Optional Schema Validation**: Validates inputs with simple descriptors (`'number'`, `'string'`, `'email'`, etc.), custom functions, or Zod schemas before handler execution.
+  - **HTTP Independence**: Services can be executed without starting an HTTP server via `createServiceRegistry().call(name, input, mockCtx)`.
+- **Middleware & Hooks**: Route lifecycle hooks can be declared per-page (`module.exports = { middleware: ['auth', 'jwt'] }`) or globally via `pages/_hooks.js`.
+
+---
+
+## 2. ORM & Database Layer (`core/orm`, `models/`)
+
+- **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.uuid()`, `zdb.nanoid()`
+  - `zdb.string()`, `zdb.integer()`, `zdb.boolean()`
+  - `zdb.file({ maxLength, nullable })` (URL/path string for uploaded assets)
+  - `zdb.json()`, `zdb.timestamp()`
+- **Repositories**: Accessed via `db.getRepository(modelName)` or `ctx.db`. Supports `find`, `findById`, `findOne`, `create`, `update`, `delete`, and `query()`.
+- **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`).
+
+---
+
+## 3. 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**:
+  - Supports clean Mithril component `.js` files (`componentFile`), external URLs (`url` / `iframeUrl`), or custom HTML documents (`html` / `htmlFile`).
+  - **Auto Layout Wrapping**: Custom page views are automatically wrapped inside Admin `Layout` and `Breadcrumb` containers unless `layout: false` is configured for full-screen pages.
+  - **SSR Scripts & Styles**: `registerScript(url)` and `registerStyle(url)` inject external CSS/JS dependencies into Admin SPA markup.
+- **Session Isolation**: Admin staff authentication uses a separate session (`req.session.adminUser` / `/_admin/api/auth/*`), isolated from public site auth (`req.user`).
+
+---
+
+## 4. Plugin Ecosystem (`plugins/`)
+
+Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register(ctx)`, `onRoutesReady(ctx)`):
+
+| Plugin | Feature set | One-line purpose |
+|--------|-------------|------------------|
+| `basicAuthPlugin` | Security / HTTP | Zero-dependency RFC 7617 HTTP Basic Authentication with timing-safe comparison |
+| `realtimePlugin` | Realtime | Framework-agnostic realtime layer (`core/realtime`) with WebSocket, SSE, Socket.IO, and Redis adapters |
+| `adminPanelPlugin` | Admin / SPA | ORM-backed CRUD SPA with user management & custom pages |
+| `fileManagerPlugin` | Admin / Media | Media library, directory tree, file preview, and drag-and-drop uploads |
+| `contentPlugin` | Admin / CMS | Schema-driven CMS with inline editing and public REST API |
+| `uploadPlugin` | HTTP / Admin | Multipart upload endpoint + pluggable storage providers |
+| `redirectPlugin` | HTTP | Configurable HTTP 301–308 redirects before file routes |
+| `rateLimitPlugin` | HTTP | Named rate-limit middleware + optional global limiter |
+| `siteAnalyticsPlugin` | Analytics | Self-hosted page view analytics and client JS error tracking |
+| `emailPlugin` | Email | MJML template compilation & Nodemailer integration |
+| `csrfPlugin` | Security | Session & cookie double-submit CSRF protection + helpers |
+| `auditLogPlugin` | Security | Admin mutation audit logging |
+| `ormCacheAdminPlugin` | Admin / ORM | Cache inspection and invalidation dashboard |
+| `restResourcePlugin` | ORM / REST API | Auto RESTful CRUD endpoints from models with eager loading & sanitization |
+| `xlsxPlugin` | Excel / Export | Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and services |
+| `csvPlugin` | CSV / Export | RFC 4180 CSV generator, parser, Excel UTF-8 BOM, streaming writer (`res.csv`), and services |
+
+

package/.agents/AUTH.md

@@ -0,0 +1,103 @@
+# Webspresso Dual Authentication Architecture
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+---
+
+## 1. Overview
+
+Webspresso provides a zero-dependency **Dual Authentication** system (`webspresso/core/auth` — resolved via package exports, no `/index.js` suffix required):
+- **Stateful Session + Cookie**: Used for browser SSR routes and Admin Panel (`/`, `/_admin`).
+- **Stateless HS256 JWT + Refresh Tokens**: Used for REST APIs, Mobile Apps, and SPAs (`/api/*`).
+
+---
+
+## ⚠️ STRICT RULE: Use Native Dual Auth (NO External JWT/Passport Packages)
+
+- **NEVER** install `jsonwebtoken`, `bcryptjs`, `passport`, or `express-session`.
+- **ALWAYS** use Webspresso's native `req.auth` and `webspresso/core/auth`:
+  - Session login: `await req.auth.attempt(email, password, { remember: true })`
+  - Stateless JWT generation: `req.auth.generateUserToken(user)`
+  - Refresh Tokens: `req.auth.generateRefreshToken(user)` / `req.auth.refreshAccessToken(token)`
+  - Route Guards: `middleware: ['auth']` (web session) or `middleware: ['jwt']` (API Bearer token)
+
+---
+
+## 2. Token Generation & Rotation
+
+- **Access Token**: Short-lived HS256 JWT token generated via `req.auth.generateUserToken(user, options)`. Default duration is `15m` (configurable).
+- **Refresh Token**: Long-lived HS256 JWT token generated via `req.auth.generateRefreshToken(user, options)` with cryptographically unique `jti` nonces. Default duration is `30d` (configurable).
+- **Token Rotation**: `req.auth.refreshAccessToken(refreshToken, { rotate: true })` verifies the refresh token and generates a new Access Token alongside a rotated Refresh Token pair.
+
+---
+
+## 3. Request-Bound Auth Helper (`req.auth`)
+
+Attached to Express request during auth middleware execution:
+
+| Method | Description |
+|--------|-------------|
+| `req.auth.attempt(identifier, password, { remember })` | Authenticate user with credentials and login |
+| `req.auth.login(user, { remember })` | Log in user and establish session |
+| `req.auth.logout({ everywhere })` | Log out user and destroy session |
+| `req.auth.generateUserToken(user, options)` | Generate short-lived JWT Access Token |
+| `req.auth.generateRefreshToken(user, options)` | Generate long-lived JWT Refresh Token |
+| `req.auth.refreshAccessToken(refreshToken, options)` | Refresh access token & rotate refresh token |
+| `req.auth.check()` / `req.auth.guest()` | Check if user is authenticated or guest |
+| `req.auth.user()` / `req.auth.id()` | Get current user object or ID |
+
+---
+
+## 4. File-Based API Route Examples (`pages/api/*`)
+
+### 4.1 Login & Token Generation (`pages/api/auth/login.post.js`)
+```javascript
+module.exports = {
+  schema: ({ z }) => ({
+    body: z.object({
+      email: z.string().email(),
+      password: z.string().min(1),
+    }),
+  }),
+  async handler(req, res) {
+    const { email, password } = req.input.body;
+    const user = await req.auth.attempt(email, password);
+    if (!user) return res.status(401).json({ error: 'Invalid credentials' });
+
+    const accessToken = req.auth.generateUserToken(user);
+    const refreshToken = req.auth.generateRefreshToken(user);
+
+    return res.json({ accessToken, refreshToken, user: { id: user.id, email: user.email } });
+  },
+};
+```
+
+### 4.2 Token Refresh Endpoint (`pages/api/auth/refresh.post.js`)
+```javascript
+module.exports = {
+  schema: ({ z }) => ({
+    body: z.object({
+      refreshToken: z.string(),
+    }),
+  }),
+  async handler(req, res) {
+    const { refreshToken } = req.input.body;
+    try {
+      const result = await req.auth.refreshAccessToken(refreshToken, { rotate: true });
+      return res.json({ accessToken: result.accessToken, refreshToken: result.refreshToken });
+    } catch (err) {
+      return res.status(401).json({ error: err.message });
+    }
+  },
+};
+```
+
+### 4.3 Protected API Route (`pages/api/profile.get.js`)
+```javascript
+module.exports = {
+  middleware: ['jwt'],
+  async handler(req, res) {
+    return res.json({ user: req.user, token: req.token });
+  },
+};
+```

package/.agents/CLI.md

@@ -0,0 +1,115 @@
+# Webspresso CLI Tooling & Commands Reference
+
+The `webspresso` CLI utility (`bin/cli.js`) provides development commands for running local SSR servers, executing database migrations, analyzing project health, and generating favicons.
+
+---
+
+## 1. Development & Build Commands
+
+```bash
+# Start local development server with hot reloading
+npx webspresso dev
+# Flags:
+#   --port, -p <number> (default: 3001)
+#   --host <string> (default: localhost)
+
+# Build production bundle / verify assets
+npx webspresso build
+```
+
+---
+
+## 2. Project Health & Sanity Check (`doctor`)
+
+Scans routing structure, model definitions, and dynamic sibling collisions:
+
+```bash
+npx webspresso doctor
+
+# Strict mode: exits with status 1 if warnings are found
+npx webspresso doctor --strict
+```
+
+Checks performed:
+- Dynamic sibling collisions (e.g. `pages/[id].njk` vs `pages/[slug].njk`).
+- Naming conventions and lowercase file-based route paths.
+- Missing model schemas or invalid `zdb` column definitions.
+
+---
+
+## 3. Database Commands (`db:migrate`, `db:seed`)
+
+```bash
+# Run pending Knex database migrations
+npx webspresso db:migrate
+
+# Seed database records
+npx webspresso db:seed
+
+# Scaffold initial seed files
+npx webspresso db:seed --setup
+```
+
+---
+
+## 4. Favicon Generator (`favicon:generate`)
+
+Generates multi-resolution browser favicons, `manifest.json`, and `favicons.njk` partial from a PNG logo:
+
+```bash
+npx webspresso favicon:generate logo.png
+
+# Flags:
+#   --theme-color <hex> (default: #ffffff)
+#   --output-dir <path> (default: public)
+#   --no-layout (do not modify layout.njk auto-include)
+```
+
+---
+
+## 5. Polar Billing Migration (`polar:migrate`)
+
+Generates an idempotent Knex migration adding Polar billing columns to the user table:
+
+```bash
+npx webspresso polar:migrate
+
+# Flags:
+#   -c, --config <path>   Database config file
+#   -t, --table <name>    User table (default: users)
+#   -o, --output <path>   Custom migration output path
+```
+
+Then run `npx webspresso db:migrate`. See [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md).
+
+---
+
+## 6. Interactive Service Runner (`service`, `service:run`)
+
+Test and run services interactively without starting the HTTP server:
+
+```bash
+# Interactive selection & prompt mode
+npx webspresso service
+
+# Run specific service with JSON payload
+npx webspresso service user.get -i '{"id": 42}'
+
+# Run with key=value query string
+npx webspresso service payment.refund -i 'transactionId=tx_123 amount=49.99'
+```
+
+---
+
+## 7. AI Agent Guidelines Scaffolder (`agents:init`)
+
+Scaffolds and synchronizes AI coding agent rules into any Webspresso project:
+
+```bash
+# Scaffold full guidelines bundle (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)
+npx webspresso agents:init
+
+# Overwrite existing guidelines
+npx webspresso agents:init --force
+```
+