webspresso 0.0.73 → 0.0.75

package/src/server.js

@@ -11,7 +11,7 @@ const timeout = require('connect-timeout');
 const { setAppContext } = require('./app-context');
 const { mountClientRuntime } = require('./client-runtime/mount');
 const { resolveClientRuntime } = require('./client-runtime/resolve');
-const { mountPages } = require('./file-router');
+const { mountPages, detectLocale } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
 
@@ -57,6 +57,16 @@ function getDefaultHelmetConfig(isDev) {
   };
 }
 
+/**
+ * Use JSON error responses for `pages/api/*` routes and clients that do not prefer HTML.
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function preferJsonErrorResponse(req) {
+  if (req.path && req.path.startsWith('/api')) return true;
+  return !req.accepts('html');
+}
+
 /**
  * Shared CSS for built-in HTML error pages (viewport-safe, fluid type, dark mode)
  */
@@ -261,6 +271,7 @@ function haltOnTimedout(req, res, next) {
  * @param {Object} options.auth - Authentication manager instance (from createAuth)
  * @param {Object} options.db - Database instance (exposed as ctx.db to plugins)
  * @param {Object} [options.clientRuntime] - Optional client assets: `{ alpine?: boolean|object, swup?: boolean|object }`. Overridable by env `WEBSPRESSO_ALPINE` / `WEBSPRESSO_SWUP` (=1 or true). Serves `/__webspresso/client-runtime/*` when either flag is on.
+ * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean}} [options.pageAssets] - If truthy, route `load()` return values for `stylesheets` and `scripts` are reserved: removed from the root template context and passed as `pageHead` to Nunjucks, with `pageAssets: true` (for layout to emit `<link>` / `<script>`). Default off.
  * @param {function(import('express').Express, Object): void} [options.setupRoutes] - Called after file routes and plugins, before 404 handler
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
@@ -375,6 +386,12 @@ function createApp(options = {}) {
     middlewares.auth = authMiddleware.auth;
     middlewares.guest = authMiddleware.guest;
   }
+
+  // Under Vitest, shared API fixtures use `fixtureRequireAuth`; default no-op unless overridden.
+  const runsUnderVitest = process.env.VITEST === 'true' || process.env.VITEST_WORKER_ID !== undefined;
+  if (runsUnderVitest && middlewares.fixtureRequireAuth == null) {
+    middlewares.fixtureRequireAuth = (req, res, next) => next();
+  }
   
   // Static files (if publicDir provided)
   if (publicDir) {
@@ -420,8 +437,8 @@ function createApp(options = {}) {
     return d.toString();
   });
   
-  // Register plugins (sync)
-  const pluginContext = { app, nunjucksEnv, options };
+  // Register plugins (sync) — middlewares is the same object later passed to mountPages
+  const pluginContext = { app, nunjucksEnv, options, middlewares };
   pluginManager.registerSync(plugins, pluginContext);
   
   // Request logging middleware
@@ -448,6 +465,7 @@ function createApp(options = {}) {
     silent: isTest,
     db: options.db ?? null,
     clientRuntime,
+    pageAssets: options.pageAssets,
   });
 
   // Set route metadata in plugin manager
@@ -461,6 +479,7 @@ function createApp(options = {}) {
         app,
         nunjucksEnv,
         options,
+        middlewares,
         db: options.db ?? null,
         routes: pluginManager.routes,
         usePlugin: (n) => pluginManager.getPluginAPI(n),
@@ -499,7 +518,7 @@ function createApp(options = {}) {
   // Helper to create error page context with fsy
   function createErrorContext(req, extraData = {}) {
     const baseUrl = process.env.BASE_URL || `http://localhost:${process.env.PORT || 3000}`;
-    const locale = req.query?.lang || process.env.DEFAULT_LOCALE || 'en';
+    const locale = detectLocale(req);
     
     // Create fsy helpers
     const fsy = createHelpers({ req, res: {}, baseUrl, locale });
@@ -560,7 +579,7 @@ function createApp(options = {}) {
       }
       
       // Custom timeout template
-      if (typeof errorPages.timeout === 'string') {
+      if (typeof errorPages.timeout === 'string' && !preferJsonErrorResponse(req)) {
         try {
           const html = nunjucksEnv.render(errorPages.timeout, ctx);
           return res.send(html);
@@ -570,7 +589,7 @@ function createApp(options = {}) {
       }
       
       // Default timeout response
-      if (req.accepts('html')) {
+      if (!preferJsonErrorResponse(req)) {
         return res.send(default503Html());
       } else {
         return res.json({ error: 'Request Timeout', status: 503 });
@@ -589,8 +608,8 @@ function createApp(options = {}) {
       return errorPages.serverError(err, req, res, ctx);
     }
     
-    // Custom template
-    if (typeof errorPages.serverError === 'string') {
+    // Custom template (skipped for /api and JSON-preferring clients so they never get HTML)
+    if (typeof errorPages.serverError === 'string' && !preferJsonErrorResponse(req)) {
       try {
         const html = nunjucksEnv.render(errorPages.serverError, ctx);
         return res.send(html);
@@ -600,7 +619,7 @@ function createApp(options = {}) {
     }
     
     // Default response
-    if (req.accepts('html')) {
+    if (!preferJsonErrorResponse(req)) {
       res.send(default500Html(err, isDev));
     } else {
       res.json({ 

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -0,0 +1,276 @@
+# Webspresso — framework reference (SSR, API, ORM)
+
+Sections follow the source repo layout (`index.js`, `src/`, `core/orm`, `doc/index.html`).
+
+## 1. What this framework is
+
+- **SSR**: Express + **Nunjucks**; URLs map to files under `pages/`.
+- **API**: File-based handlers under `pages/api/` with method suffixes and optional **Zod** validation (`req.input`).
+- **i18n**: JSON locales; `t('key')` in templates.
+- **ORM**: Knex-backed layer in `core/orm` — `defineModel`, `zdb` schema helpers, repositories, query builder, migrations.
+- **Plugins**: Register in `createApp({ plugins })`; optional `db` passed as `ctx.db`.
+
+Public API surface: `require('webspresso')` / [`index.js`](../../../index.js) — `createApp`, **`resolveClientRuntime`**, **`CLIENT_RUNTIME_BASE`**, file-router utilities, `createHelpers`, plugin manager, ORM exports, built-in plugins. **Session auth** lives in [`core/auth`](../../../core/auth) — import **`require('webspresso/core/auth')`** (`createAuth`, `quickAuth`, `hash`, `verify`, `setupAuthMiddleware`, `createRememberTokensTable`, policy helpers); wire with **`createApp({ auth })`**.
+
+---
+
+## 2. Typical project layout
+
+```
+project/
+├── server.js                 # listen(); uses createApp()
+├── pages/
+│   ├── _hooks.js             # global lifecycle hooks (optional)
+│   ├── locales/en.json       # global i18n
+│   ├── index.njk             # GET /
+│   ├── about/index.njk       # GET /about
+│   ├── blog/[slug].njk       # dynamic
+│   └── api/
+│       ├── health.get.js
+│       └── posts.post.js
+├── views/                    # layouts (e.g. layout.njk)
+├── public/                   # static assets
+├── models/                   # ORM models (defineModel)
+├── migrations/
+├── webspresso.db.js          # or knexfile.js
+└── plugins/                  # app-specific plugins (optional)
+```
+
+---
+
+## 3. `createApp(options)` — essentials
+
+**Required**
+
+- `pagesDir` — path to `pages/`.
+
+**Common optional**
+
+| Option | Role |
+|--------|------|
+| `viewsDir` | Layouts / partials (Nunjucks paths) |
+| `publicDir` | Static files (`express.static`) |
+| `db` | DB instance from `createDatabase()` → **`ctx.db`** in `load`, `meta`, plugins |
+| `middlewares` | Named map; reference by string in route/API config (`middleware: ['auth']`) |
+| `plugins` | Array of plugin factories/objects |
+| `errorPages` | `{ notFound, serverError, timeout }` — function or template path. File-based SSR/API errors are passed to this Express error middleware via `next(err)`. **`serverError` / `timeout` as a template path** is not used for paths under **`/api`** (those get default JSON). |
+| `timeout` | e.g. `'30s'` or `false` |
+| `helmet` | `true` / `false` / object |
+| `assets` | `{ version, manifestPath, prefix }` for `fsy.asset` / `fsy.css` / `fsy.js` |
+| `pageAssets` | Opt-in **`true`** or **`{ enabled?, stylesheets?, scripts? }`**. When on, route **`load()`** may return reserved keys **`stylesheets`** (string or list; also `{ href, media? }` objects) and **`scripts`** (string, `{ src, defer?, async?, type? }`, or list). They are removed from the root Nunjucks context and passed as **`pageHead`** with **`pageAssets: true`**. The app layout must print them (see [`views/layout.njk`](../../../views/layout.njk) in the package). Default **off** — `stylesheets` / `scripts` in **`load()`** behave as normal data keys. |
+| `clientRuntime` | Opt-in **`{ alpine?: boolean \| object, swup?: boolean \| object }`**. Serves **`/__webspresso/client-runtime/*`** (Alpine 3, swup 4 + Head + Scripts plugins + bootstrap). Template context **`clientRuntime`**; include [`views/partials/webspresso-client-runtime.njk`](../../../views/partials/webspresso-client-runtime.njk) and set **`<main id="swup">`** when swup is on. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`** (`1` or `true`). Admin / dev dashboard HTML is unchanged (Mithril). Use **`data-no-swup`** on links for full page loads. HTMX is not used. |
+| `auth` | `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`webspresso/core/auth`). Mounts cookie parser + **`express-session`** + per-request **`authenticate`**; sets **`req.user`**, **`req.auth`**. Injects named route middleware **`auth`** and **`guest`** (overwrites same keys in `middlewares` if you passed both — avoid reusing those names for custom handlers). |
+| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. **`ctx.clientRuntime`** is the resolved flags. **`ctx.authMiddleware`** is set when `auth` was passed (guards: `requireAuth`, `requireGuest`, `requireCan`, `requireVerified`, …). Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
+
+**Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is **`null`** when `auth` was not configured.
+
+### Client runtime — implementation notes
+
+- **Package helpers:** `resolveClientRuntime(options)` merges **`createApp({ clientRuntime })`** with env; **`CLIENT_RUNTIME_BASE`** is **`/__webspresso/client-runtime`** (script URLs under that path).
+- **After swup navigation:** bootstrap runs **`Alpine.initTree`** on **`#swup`** on swup’s **`content:replace`** so new SSR markup gets Alpine bindings.
+- **Default `ignoreVisit` (bootstrap):** links under **`/_admin`**, **`/_webspresso`**, elements with **`data-no-swup`**, plus swup’s usual rules (e.g. `target="_blank"`, other origin).
+- **CSP / Helmet:** production **`script-src 'self'`** works for **`/__webspresso/client-runtime/`**; some Alpine builds may need **`unsafe-eval`** — validate for your version or use a stricter build.
+- **Longer doc:** **[`doc/index.html#client-runtime`](../../../doc/index.html#client-runtime)** · README **Client runtime**.
+
+### Session authentication — essentials
+
+- **Import:** `const { createAuth, quickAuth, hash, verify, createRememberTokensTable } = require('webspresso/core/auth')` (published `core/` tree on npm; **not** re-exported from package root).
+- **`createAuth({ findUserById, findUserByCredentials, session: { secret }, rememberTokens?, ... })`** — adapter pattern; optional **remember-me** via `rememberTokens: { create, find, delete, deleteAllForUser }` + **`createRememberTokensTable(knex)`** for the default table shape.
+- **`quickAuth({ db, userModel, identifierField, passwordField, rememberMe })`** — wires **`getRepository`** + bcrypt **`verify`**; optional Knex **`remember_tokens`** when `rememberMe: true`.
+- **Request API** (after global authenticate): **`req.auth.attempt(id, password, { remember })`**, **`login`**, **`logout`**, **`check`**, **`guest`**, **`user`**, **`id`**, **`can` / `cannot` / `authorize`** (policies: **`auth.definePolicy`**, **`defineGate`**, **`beforePolicy`**).
+- **Route config:** `middleware: ['auth']` (must be logged in) or `['guest']` (logged-out only). For JSON APIs mounted in **`setupRoutes`**, use **`ctx.authMiddleware.requireAuth({ api: true })`** for 401 JSON instead of redirect.
+- **Login page pitfall:** a **`pages/login.njk`** can register **before** `setupRoutes` and bypass **`requireGuest`**. Prefer login GET/POST in **`setupRoutes`** with templates under **`views/`** only, or omit **`pages/login.njk`** — see [`tests/e2e/auth.spec.js`](../../../tests/e2e/auth.spec.js).
+- **Admin panel** uses a **separate** session (`req.session.adminUser`, `/_admin/api/auth/*`); it does **not** replace **`createApp({ auth })`** for site users.
+- **Site users in the admin UI (`userManagement`):** Opt-in on **`adminPanelPlugin`**. Set **`userManagement: { enabled: true, model: 'User', fields?: { ... } }`** so the SPA shows **Users**: sidebar **All Users** / **Add User** link to **`/_admin/models/{model}`** and **`/_admin/models/{model}/new`** (same RecordList/RecordForm as other models). **`/_admin/users`**, **`/_admin/users/new`**, **`/_admin/users/:id/edit`** remain SPA aliases that redirect there; **`/_admin/users/sessions`** is **Active Sessions**. The **`model`** must match site auth (e.g. **`quickAuth({ userModel: 'User', ... })`** / **`createAuth`**) and must have **`admin: { enabled: true, ... }`** on **`defineModel`** so admin CRUD metadata loads; otherwise Users screens look empty. Pass **`auth: authManager`** with the **same** **`AuthManager`** as **`createApp({ auth: authManager })`** for **Active Sessions** / revoke (**`rememberTokens`** / **`remember_me`**); without **`auth`**, user CRUD still works via **`db.getRepository(model)`**, but session endpoints return empty or “not enabled”.
+- **Wiring:** `plugins: [ adminPanelPlugin({ db, auth: authManager, userManagement: { enabled: true, model: 'User' } }) ]` alongside `createApp({ ..., auth: authManager })`. Admin staff log in at **`/_admin`**; end users use your normal site login — two different cookies/sessions.
+
+Longer narrative: **[`doc/index.html#authentication`](../../../doc/index.html#authentication)** · **[`#admin-user-management`](../../../doc/index.html#admin-user-management)** · README **Authentication (session)** and **Admin Panel Plugin**.
+
+---
+
+## 4. File-based routing (SSR)
+
+| Path pattern | URL |
+|--------------|-----|
+| `pages/index.njk` | `/` |
+| `pages/about/index.njk` | `/about` |
+| `pages/tools/[slug].njk` | `/tools/:slug` |
+| `pages/docs/[...rest].njk` | `/docs/*` (catch-all) |
+
+**Route config** — sibling `.js` file (e.g. `pages/tools/index.js`):
+
+- `middleware` — array of Express functions, **string names** from `createApp({ middlewares })`, or **`['name', options]` tuples** when the registry entry is a **factory** `(options) => (req, res, next) => …` (bare string calls the factory with `{}`). Built-in **`auth`** / **`guest`** (with `createApp({ auth })`) are factories — e.g. **`['auth', { api: true }]`** for JSON 401 on APIs.
+- `load(req, ctx)` — async; return object merged into template context; use **`ctx.db`** when `createApp({ db })` is set.
+- `meta(req, ctx)` — title, description, etc.
+- `hooks` — `beforeLoad`, `afterRender`, etc. (see hook order below).
+
+---
+
+## 5. File-based API (`pages/api/`)
+
+| File | Route |
+|------|-------|
+| `api/health.get.js` | `GET /api/health` |
+| `api/items.post.js` | `POST /api/items` |
+| `api/users/[id].get.js` | `GET /api/users/:id` |
+
+**Shapes**
+
+1. **Function** — `module.exports = async (req, res) => { ... }`
+2. **Object** — **`handler`**, optional **`middleware`** (names, functions, or **`['name', options]`** tuples with factory registry entries), optional **`schema`**
+
+**Order:** `req.db` (if any) → **Zod** `schema` → **`middleware`** → **`handler`**.
+
+**Zod** — `schema: ({ z }) => ({ body, query, params, response })` → **`req.input`**; invalid → **400** `{ error: 'Validation Error', issues }`.
+
+---
+
+## 6. Global and route hooks
+
+**Global:** `pages/_hooks.js` exports `onRequest`, `beforeLoad`, `afterLoad`, `beforeRender`, `afterRender`, `onError`, etc.
+
+**`onError(ctx, err)`** — runs when an unhandled error occurs in a **file-based** SSR route or **`pages/api/*`** handler (after `console.error`, before the central `errorPages` handler). Optional second argument **`err`** matches **`ctx.error`**. Use for APM (Sentry, New Relic `noticeError`, …).
+
+**Rough order:** global `onRequest` → route middleware chain → `load` → render → `afterRender`. (See README “Hook Execution Order” for full list.)
+
+---
+
+## 7. i18n
+
+- **Global:** `pages/locales/<locale>.json` (nested keys).
+- **Route-specific:** `pages/<route>/locales/<locale>.json` overrides global.
+- Templates: `{{ t('nav.home') }}`.
+- Env: `DEFAULT_LOCALE`, `SUPPORTED_LOCALES` (comma-separated).
+
+---
+
+## 8. Template helpers (`fsy`)
+
+Available in all Nunjucks templates:
+
+- **URL:** `fsy.url`, `fsy.fullUrl`, `fsy.route`, `fsy.canonical`
+- **Request:** `fsy.q`, `fsy.param`, `fsy.hdr`
+- **Utils:** `fsy.slugify`, `fsy.truncate`, `fsy.prettyBytes`, `fsy.prettyMs`
+- **Dates:** `fsy.date`, `fsy.dateFormat`, `fsy.dateFromNow`, `fsy.dateDiff`, …
+- **Assets:** `fsy.asset`, `fsy.css`, `fsy.js`, `fsy.img` (with `assets` config)
+- **Dev:** `fsy.isDev()`
+- **SEO:** `fsy.jsonld`
+
+Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when configured.
+
+---
+
+## 9. ORM overview
+
+**Define schema** with **`zdb`** (`zdb.id()`, `zdb.uuid()`, `zdb.nanoid()`, `zdb.string({...})`, **`zdb.file({ maxLength, nullable })`** — URL/path string for uploaded assets, `zdb.foreignKey`, `zdb.foreignUuid`, `zdb.foreignNanoid`, `zdb.timestamp`, `zdb.json`, …).
+
+**Define model** with **`defineModel({ name, table, schema, relations, scopes, hidden, admin })`**.
+
+- **Relations:** `belongsTo`, `hasMany`, `hasOne` with `model: () => OtherModel`.
+- **Scopes:** `softDelete`, `timestamps`, optional `tenant` column.
+- **`hidden`:** columns never exposed in admin/API (e.g. `password_hash`).
+- **Nanoid PK:** `zdb.nanoid()` / `zdb.nanoid({ maxLength: 12 })` — string primary key; migrations use `string(length)`. On **`create()`**, omitting the PK auto-fills a URL-safe id (built-in generator, same alphabet as `nanoid`). Use **`zdb.foreignNanoid('table', { maxLength })`** when the parent uses nanoid PKs; **`generateNanoid`** is exported from `webspresso` for manual ids. In API **`schema`**, use **`z.nanoid()`** / **`z.nanoid(12)`** / **`z.nanoid({ maxLength })`** (the `z` from `schema: ({ z })` is extended by Webspresso). **`zodNanoid`** / **`extendZ`** are also exported for non-route use.
+
+**Database:** `createDatabase({ client, connection, models: './models' })` — auto-loads `models/*.js` (ignore `_prefix`).
+
+**Repository:** `db.getRepository('User')` → `findById`, `findOne`, `findAll`, `create`, `update`, `delete`, `query()`, …
+
+**Query builder:** `UserRepo.query().where(...).with('relation').orderBy(...).list()` / `.first()` / `.paginate()` / `.count()`. **`with()`** eager-loads relations; **`count()`** ignores builder `.limit`/`.offset` for total; see ORM docs for edge cases.
+
+**Migrations:** `webspresso db:migrate`, `db:rollback`, `db:status`, `db:make`.
+
+**Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
+
+**Query cache (optional):** `createDatabase({ ..., cache: true })` or `cache: { defaultStrategy: 'auto'|'smart', memory: { maxEntries, defaultTtlMs }, provider?: custom }`. Opt-in per model: `defineModel({ ..., cache: 'auto'|'smart'|true })`. API: `db.cache` → `getMetrics()`, `purge()`, `invalidateModel(name)`, `invalidateTags(tags[])`, `resetMetrics()`. Reads bypass cache when using a transaction knex. Admin UI: `ormCacheAdminPlugin({ db })` (needs `admin-panel` and `cache` enabled).
+
+Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins. **`pages/api/`** handlers receive **`req.db`** (and route **`middleware`** runs after it). Outside requests, use **`getDb()`** / **`hasDb()`**; for **`setupRoutes`**-only routes, use **`attachDbMiddleware`**.
+
+---
+
+## 10. Plugins (built-in — concise)
+
+| Plugin | Purpose |
+|--------|---------|
+| `dashboardPlugin` | Dev route `/_webspresso` — route list |
+| `sitemapPlugin` | `/sitemap.xml`, robots; optional DB-driven URLs |
+| `analyticsPlugin` | GA / GTM / Yandex / Bing / Facebook — `fsy` helpers |
+| `adminPanelPlugin` | SPA admin CRUD — needs **`db`**; optional **`uploadUrl`** (or infer from **`uploadPlugin`**); optional **`userManagement: { enabled, model, fields }`** + **`auth`** (same **`AuthManager`** as **`createApp({ auth })`**) for site-user CRUD + remember-me session UI — see **Session authentication** above |
+| `dataExchangePlugin` | Admin-only **Excel export** + **CSV/XLSX import** under `${adminPath}/api/data-exchange/*`; register **after** `adminPanelPlugin` with same `db` / `adminPath`; optional `maxRows`, `maxFileBytes`; adds UI buttons + bulk `export-xlsx` |
+| `redirectPlugin` | Configurable **301–308** redirects in `register()` — runs **before** file-based SSR routes; `rules` (`from` path or `RegExp`, `to`, `status`, `methods`), `preserveQuery`, `allowExternal`, `trailingSlash`, `defaultMethods`; docs **[`doc/index.html#plugins-redirect`](../../../doc/index.html#plugins-redirect)**, README **Redirect plugin** |
+| `uploadPlugin` | `POST` multipart (`multer`), `createLocalFileProvider` or custom `provider`; set **`mimeAllowlist`** / **`maxBytes`** in production |
+| `siteAnalyticsPlugin` | Self-hosted page views + admin charts |
+| `auditLogPlugin` | Admin mutation audit trail |
+| `recaptchaPlugin` | v2/v3 + middleware |
+| `seoCheckerPlugin` | Dev SEO panel |
+| `restResourcePlugin` | Opt-in REST CRUD from models; `?include=` uses ORM eager load (single-level relations only) |
+| `ormCacheAdminPlugin` | Admin page for ORM cache metrics / purge / invalidate (`db.cache` required) |
+
+**Custom plugin:** `name`, `version`, `register(ctx)`, `onRoutesReady(ctx)` — use `ctx.app`, `ctx.db`, `ctx.addHelper`, `ctx.addRoute`, `ctx.usePlugin('other')`. Plugin failures **warn**; app keeps running.
+
+---
+
+## 11. CLI (project directory)
+
+| Command | Role |
+|---------|------|
+| `webspresso new` | Scaffold project |
+| `webspresso new .` / `new ./` | Scaffold **into the current directory** |
+| `webspresso new … --yes` | **Non-interactive** (agents / CI); use `-i` to install deps |
+| `webspresso dev` / `start` | Servers |
+| `webspresso page` / `api` | Interactive scaffolding |
+| `webspresso db:*` | migrate, rollback, status, make |
+| `webspresso upgrade` | Bump **`webspresso`** in **`package.json`** |
+| `webspresso seed` | Seed data |
+| `webspresso doctor` | Sanity checks |
+| `webspresso skill` | Cursor **`SKILL.md`** scaffold |
+| `webspresso skill --preset webspresso` | Copy bundled Webspresso agent skill (`SKILL.md` + `REFERENCE-*.md`) |
+| `webspresso add tailwind` | Tailwind setup |
+| `webspresso favicon:generate` | Favicons + manifest |
+| `webspresso admin:setup` / `admin:password` | Admin users |
+| `webspresso audit:prune` | Audit log retention |
+
+**`webspresso new` — automation:** **`new .`** scaffolds in place. **Typical one-liners:** `webspresso new . --yes --no-tailwind` · `webspresso new . --yes -i`.
+
+---
+
+## 12. Environment variables (common)
+
+| Var | Notes |
+|-----|-------|
+| `NODE_ENV` | `development` / `production` |
+| `DEFAULT_LOCALE` | Default locale |
+| `SUPPORTED_LOCALES` | Comma-separated |
+| `BASE_URL` | Canonical / links |
+| `DATABASE_URL` | DB connection |
+| `SESSION_SECRET` | Session cookie signing |
+| `WEBSPRESSO_ALPINE` | Forces **`clientRuntime.alpine`** when `1` / `true` |
+| `WEBSPRESSO_SWUP` | Forces **`clientRuntime.swup`** when `1` / `true` |
+
+---
+
+## 13. Testing
+
+- **Unit / integration:** `npm test` (Vitest).
+- **E2E:** `npm run test:e2e` (Playwright).
+
+---
+
+## 14. Pitfalls (for agents)
+
+1. **Custom Express routes** — use **`setupRoutes`**, not only `app.use` after `createApp` returns.
+2. **File-router order** — understand precedence vs manual routes.
+3. **`ctx.db`** — only when `createApp({ db })` is set.
+4. **ORM hidden fields** — never expose to clients unintentionally.
+5. **Zod on API** — assume **`req.input`** when schema is set.
+6. **Built-in `auth`** — framework owns **`middlewares.auth`** / **`guest`** names.
+7. **`pages/login.njk`** — can shadow custom login; prefer **`setupRoutes`** + **`views/`**.
+8. **Client runtime + swup** — need **`<main id="swup">`** and the client-runtime partial when enabled.
+
+---
+
+## 15. When to read this file (framework)
+
+- Pages, API routes, ORM, migrations, **SSR `createApp`**, first-party **plugins**, i18n, **session auth**, **client runtime** (Alpine / swup).
+- Not for: in-process **application kernel** (event bus + `kernel.createApp`) — see **`REFERENCE-kernel.md`**.
+
+Authoritative long-form: **[README.md](../../../README.md)**, **[`doc/index.html`](../../../doc/index.html)**.

package/templates/skills/webspresso-usage/REFERENCE-kernel.md

@@ -0,0 +1,93 @@
+# Webspresso — application kernel (event bus, flows, views)
+
+This layer must **not** be confused with Express SSR. The package root **`createApp`** sets up file-based SSR; **`kernel.createApp`** is a lightweight in-process API with an event bus, optional view resolver, and flow registry.
+
+## Name clash
+
+| API | Purpose |
+|-----|---------|
+| `require('webspresso').createApp(...)` | SSR — `pages/`, Nunjucks, Express |
+| `require('webspresso').kernel.createApp(...)` | Kernel — `events`, `registerPlugin`, `registerFlow`, `view` |
+
+## Usage
+
+```javascript
+const { kernel } = require('webspresso');
+const app = kernel.createApp({
+  paths: {
+    appViews: './views', // optional app override root
+    themeViews: './themes/default',
+  },
+});
+```
+
+Module layout (source repo): [`core/kernel/`](../../../core/kernel/).
+
+## Event bus
+
+- **`events.dispatch(name, ctx)`** — Handlers for the same name run **sequentially** with `await`; `ctx` is mutable; errors stop the caller.
+- **`events.publish(name, ctx)`** — Handlers run concurrently via **`Promise.all`** (side effects / “after” events).
+- **`events.on(name, handler)`** / **`off`** — Subscribe / unsubscribe.
+- **`events.buildContext(payload, { source, requestId?, userId? })`** → `{ payload, meta: { source, createdAt, … } }`; `source`: `'orm' | 'auth' | 'route' | 'plugin' | 'system'`.
+
+Standalone bus: `kernel.createEventBus()`.
+
+## Simulated repository (ORM lifecycle)
+
+`kernel.BaseRepository` — in-memory store; events named by `resource`: `orm.<resource>.beforeCreate`, `afterCreate`, `beforeUpdate`, …
+
+Implementation: [`core/kernel/base-repository.js`](../../../core/kernel/base-repository.js).
+
+## Plugin shell
+
+```javascript
+const { kernel } = require('webspresso');
+const myPlugin = kernel.definePlugin({
+  name: 'my-plugin',
+  events(app) {
+    app.events.on('orm.post.afterCreate', async (ctx) => { /* ... */ });
+  },
+  views() {
+    return {
+      namespace: 'blog',
+      layouts: {},
+      pages: { home: '<h1>{{ title }}</h1>' },
+      partials: {},
+    };
+  },
+});
+app.registerPlugin(myPlugin);
+```
+
+## View resolver
+
+- Name shape: **`namespace::page`** (e.g. `blog::home`).
+- Resolution order: app file overrides → theme file overrides → inline plugin templates.
+- **`app.view.renderView('ns::id', data, { layout: 'ns::layoutName' })`**
+- **`app.view.renderPartial(...)`**
+- Minimal templates: `{{ field }}` interpolation.
+
+## Flow
+
+```javascript
+app.registerFlow(
+  kernel.defineFlow({
+    trigger: 'orm.post.afterCreate',
+    when: (ctx) => ctx.payload.record?.status === 'published',
+    actions: [async (ctx, kernApp) => { /* run in order */ }],
+  }),
+);
+```
+
+## Demo
+
+From the repo: `node core/kernel/run-demo.js` — plugin, flow, and view example.
+
+## When to read this file
+
+- Event-driven domain logic, “on afterCreate do X” automation.
+- When you want this minimal kernel instead of SSR routes or Knex ORM `ModelEvents` alone.
+
+Types: npm package **`index.d.ts`** (`kernel`, `KernelAppShell`, …).
+
+HTML section: **[`doc/index.html#application-kernel`](../../../doc/index.html#application-kernel)**.