webspresso 0.0.95 → 0.0.96

package/src/services/builtins/file-manager.js

@@ -0,0 +1,178 @@
+/**
+ * Built-in File Manager Services
+ * @module src/services/builtins/file-manager
+ */
+
+const path = require('path');
+const fs = require('fs/promises');
+const { z } = require('zod');
+const { ValidationError, NotFoundError } = require('../../../core/errors');
+const {
+  listFiles,
+  createDirectory,
+  renameItem,
+  deleteItem,
+  moveItem,
+  saveUploadedFile,
+} = require('../../../plugins/file-manager/core');
+const { parseBase64 } = require('./media');
+
+/**
+ * Create built-in file manager services map
+ * @param {Object} [options]
+ * @param {string} [options.baseDir]
+ * @param {string} [options.publicBasePath]
+ * @returns {Record<string, Object>}
+ */
+function createFileManagerServices(options = {}) {
+  const defaultBaseDir = path.resolve(
+    options.baseDir || path.join(process.cwd(), 'public', 'uploads')
+  );
+  const defaultPublicBase = options.publicBasePath || '/uploads';
+
+  return {
+    'fileManager.list': {
+      schema: z.object({
+        path: z.string().optional().default(''),
+        search: z.string().optional(),
+        type: z.string().optional(),
+        sort: z.enum(['name', 'size', 'mtime', 'ext']).optional().default('name'),
+        order: z.enum(['asc', 'desc']).optional().default('asc'),
+        page: z.number().int().positive().optional(),
+        perPage: z.number().int().positive().optional(),
+        baseDir: z.string().optional(),
+        publicBasePath: z.string().optional(),
+      }),
+      async handler(input) {
+        const baseDir = input.baseDir ? path.resolve(input.baseDir) : defaultBaseDir;
+        const publicBasePath = input.publicBasePath || defaultPublicBase;
+
+        return listFiles(baseDir, input.path, {
+          search: input.search,
+          type: input.type,
+          sort: input.sort,
+          order: input.order,
+          page: input.page,
+          perPage: input.perPage,
+          publicBasePath,
+        });
+      },
+    },
+
+    'fileManager.mkdir': {
+      schema: z.object({
+        path: z.string().optional().default(''),
+        name: z.string().min(1, 'Directory name is required'),
+        baseDir: z.string().optional(),
+      }),
+      async handler(input) {
+        const baseDir = input.baseDir ? path.resolve(input.baseDir) : defaultBaseDir;
+        return createDirectory(baseDir, input.path, input.name);
+      },
+    },
+
+    'fileManager.rename': {
+      schema: z.object({
+        path: z.string().min(1, 'Target path is required'),
+        newName: z.string().min(1, 'New name is required'),
+        baseDir: z.string().optional(),
+      }),
+      async handler(input) {
+        const baseDir = input.baseDir ? path.resolve(input.baseDir) : defaultBaseDir;
+        return renameItem(baseDir, input.path, input.newName);
+      },
+    },
+
+    'fileManager.delete': {
+      schema: z.object({
+        path: z.string().min(1, 'Path is required'),
+        baseDir: z.string().optional(),
+      }),
+      async handler(input) {
+        const baseDir = input.baseDir ? path.resolve(input.baseDir) : defaultBaseDir;
+        return deleteItem(baseDir, input.path);
+      },
+    },
+
+    'fileManager.move': {
+      schema: z.object({
+        source: z.string().min(1, 'Source path is required'),
+        destination: z.string().optional().default(''),
+        baseDir: z.string().optional(),
+      }),
+      async handler(input) {
+        const baseDir = input.baseDir ? path.resolve(input.baseDir) : defaultBaseDir;
+        return moveItem(baseDir, input.source, input.destination);
+      },
+    },
+
+    'fileManager.upload': {
+      schema: z.object({
+        path: z.string().optional().default(''),
+        buffer: z.any().optional(),
+        base64: z.string().optional(),
+        filePath: z.string().optional(),
+        originalName: z.string().min(1).default('upload.bin'),
+        mimeType: z.string().optional(),
+        baseDir: z.string().optional(),
+        publicBasePath: z.string().optional(),
+      }),
+      async handler(input) {
+        let {
+          path: targetRelPath,
+          buffer,
+          base64,
+          filePath,
+          originalName,
+          mimeType,
+          baseDir: customBaseDir,
+          publicBasePath: customPublicBase,
+        } = input;
+        const baseDir = customBaseDir ? path.resolve(customBaseDir) : defaultBaseDir;
+        const publicBasePath = customPublicBase || defaultPublicBase;
+
+        if (buffer && !(buffer instanceof Buffer) && !(buffer instanceof Uint8Array)) {
+          if (typeof buffer === 'string') {
+            buffer = Buffer.from(buffer);
+          } else {
+            throw new ValidationError('Invalid buffer provided');
+          }
+        }
+
+        if (!buffer && base64) {
+          const parsed = parseBase64(base64);
+          buffer = parsed.buffer;
+          if (parsed.mimeType && (!mimeType || mimeType === 'application/octet-stream')) {
+            mimeType = parsed.mimeType;
+          }
+        } else if (!buffer && filePath) {
+          try {
+            buffer = await fs.readFile(path.resolve(filePath));
+            if (!originalName || originalName === 'upload.bin') {
+              originalName = path.basename(filePath);
+            }
+          } catch (err) {
+            throw new NotFoundError(`Source file not found: ${filePath}`, { cause: err });
+          }
+        }
+
+        if (!buffer || buffer.length === 0) {
+          throw new ValidationError('No file content provided');
+        }
+
+        return saveUploadedFile(
+          baseDir,
+          targetRelPath,
+          buffer,
+          originalName,
+          mimeType,
+          publicBasePath
+        );
+      },
+    },
+  };
+}
+
+module.exports = {
+  createFileManagerServices,
+};

package/src/services/index.js

@@ -43,6 +43,7 @@ function createServiceRegistry(options = {}) {
 const { createAuthServices } = require('./builtins/auth');
 const { createMailServices } = require('./builtins/mail');
 const { createMediaServices } = require('./builtins/media');
+const { createFileManagerServices } = require('./builtins/file-manager');
 const { createSystemServices } = require('./builtins/system');
 const { createExchangeServices } = require('./builtins/exchange');
 
@@ -54,6 +55,7 @@ module.exports = {
   createAuthServices,
   createMailServices,
   createMediaServices,
+  createFileManagerServices,
   createSystemServices,
   createExchangeServices,
   memoize,

package/bin/commands/skill.js

@@ -1,187 +0,0 @@
-/**
- * Skill Command — scaffold Agent Skill (SKILL.md) for Cursor / AI tools
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
-
-const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]$/;
-
-function validateSkillName(name) {
-  const t = String(name).trim().toLowerCase();
-  if (!t) return 'Skill name is required';
-  if (t.length > 64) return 'Skill name must be at most 64 characters';
-  if (!NAME_PATTERN.test(t)) {
-    return 'Use lowercase letters, numbers, and hyphens only (e.g. my-skill-name)';
-  }
-  return true;
-}
-
-function skillDir(base, skillName) {
-  return path.join(base, '.agents', 'skills', skillName);
-}
-
-
-function defaultDescription(skillName) {
-  const label = skillName.replace(/-/g, ' ');
-  return `Guides the agent through tasks for ${label}. Use when the user works on ${label} or asks about related workflows.`;
-}
-
-/** Bundled presets: CLI flag → template directory (all *.md copied) */
-const PRESETS = {
-  webspresso: {
-    skillName: 'webspresso-usage',
-    templateDir: path.join(__dirname, '../../templates/skills/webspresso-usage'),
-  },
-};
-
-function buildSkillMarkdown(skillName, description) {
-  const title = skillName
-    .split('-')
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join(' ');
-  const descYaml = JSON.stringify(description.trim());
-
-  return `---
-name: ${skillName}
-description: ${descYaml}
----
-
-# ${title}
-
-## Instructions
-
-- Describe step-by-step what the agent should do.
-- Add constraints, file paths, and conventions for this project.
-
-## When to use
-
-- List concrete user phrases or tasks that should trigger this skill.
-
-## Examples
-
-\`\`\`
-Example prompt or command
-\`\`\`
-
-`;
-
-}
-
-function registerCommand(program) {
-  program
-    .command('skill [name]')
-    .description('Create an Agent Skill folder with SKILL.md')
-    .option('-g, --global', 'Write to ~/.agents/skills/ instead of ./.agents/skills/')
-    .option('-d, --description <text>', 'Skill description (for YAML frontmatter)')
-    .option('-f, --force', 'Overwrite existing SKILL.md')
-    .option(
-      '-p, --preset <name>',
-      'Install bundled skill: webspresso → agent reference (SKILL.md + REFERENCE-*.md in .agents/skills/webspresso-usage/)',
-    )
-
-    .action(async (nameArg, options) => {
-      const presetKey = options.preset ? String(options.preset).trim().toLowerCase() : '';
-
-      if (presetKey) {
-        const preset = PRESETS[presetKey];
-        if (!preset) {
-          console.error(`❌ Unknown preset "${presetKey}". Available: ${Object.keys(PRESETS).join(', ')}`);
-          process.exit(1);
-        }
-        const templateDir = preset.templateDir;
-        if (!templateDir || !fs.existsSync(templateDir)) {
-          console.error(`❌ Preset template directory missing: ${templateDir}`);
-          process.exit(1);
-        }
-        const mdFiles = fs
-          .readdirSync(templateDir)
-          .filter((f) => f.endsWith('.md'));
-        if (mdFiles.length === 0) {
-          console.error(`❌ No .md files in preset: ${templateDir}`);
-          process.exit(1);
-        }
-        const root = options.global ? os.homedir() : process.cwd();
-        const dir = skillDir(root, preset.skillName);
-        const skillFile = path.join(dir, 'SKILL.md');
-
-        if (!options.force && fs.existsSync(skillFile)) {
-          console.error(`❌ Already exists: ${skillFile}`);
-          console.error('   Use --force to overwrite.');
-          process.exit(1);
-        }
-
-        fs.mkdirSync(dir, { recursive: true });
-        for (const file of mdFiles) {
-          fs.copyFileSync(path.join(templateDir, file), path.join(dir, file));
-        }
-
-        console.log(`\n✅ Installed bundled skill "${presetKey}" →\n   ${dir}/\n`);
-        console.log(`   Files: ${mdFiles.join(', ')}\n`);
-        console.log('   Edit if needed, then restart Cursor or reload the window.\n');
-        return;
-      }
-
-      let skillName = nameArg ? String(nameArg).trim().toLowerCase() : '';
-
-      if (!skillName) {
-        const { name } = await inquirer.prompt([
-          {
-            type: 'input',
-            name: 'name',
-            message: 'Skill name (kebab-case, e.g. review-api):',
-            validate: validateSkillName,
-          },
-        ]);
-        skillName = name.trim().toLowerCase();
-      } else {
-        const v = validateSkillName(skillName);
-        if (v !== true) {
-          console.error(`❌ ${v}`);
-          process.exit(1);
-        }
-        skillName = skillName.trim().toLowerCase();
-      }
-
-      let description = options.description;
-      if (!description) {
-        const { desc } = await inquirer.prompt([
-          {
-            type: 'input',
-            name: 'desc',
-            message: 'Short description (what/when the agent should use this skill):',
-            default: defaultDescription(skillName),
-          },
-        ]);
-        description = desc || defaultDescription(skillName);
-      }
-
-      const root = options.global ? os.homedir() : process.cwd();
-      const dir = skillDir(root, skillName);
-      const skillFile = path.join(dir, 'SKILL.md');
-
-      if (!options.force && fs.existsSync(skillFile)) {
-        console.error(`❌ Already exists: ${skillFile}`);
-        console.error('   Use --force to overwrite.');
-        process.exit(1);
-      }
-
-      fs.mkdirSync(dir, { recursive: true });
-
-      const body = buildSkillMarkdown(skillName, description);
-      fs.writeFileSync(skillFile, body, 'utf8');
-
-      console.log(`\n✅ Agent skill created:\n   ${skillFile}\n`);
-      console.log('   Edit SKILL.md, then restart Cursor or reload the window if needed.\n');
-    });
-}
-
-module.exports = { registerCommand };

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

@@ -1,289 +0,0 @@
-# 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
-
-- **Architecture**: Modern full-stack Node.js framework with Next.js/Nuxt-style file-based routing.
-- **SSR**: Native server-side rendering with **Nunjucks**; URLs map directly to files under `pages/`.
-- **API**: 100% file-based handlers under `pages/api/` with HTTP method suffixes (`.get.js`, `.post.js`, `[id].delete.js`) and declarative **Zod** validation (`req.input`).
-- ⚠️ **CRITICAL ANTI-PATTERN**: **NEVER** create a `routes/` or `src/routes/` directory. **NEVER** use `app.get()`, `app.post()`, or `express.Router()`. All application routes must live under `pages/` and `pages/api/`.
-- **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?: string \| Function, serverError?: string \| Function, timeout?: string \| Function }` — Nunjucks template path (e.g. `notFound: '404.njk'`, relative to `viewsDir`) or Express handler fn `(req, res, ctx) => ...`. Template context receives `{ fsy, locale, isDev, url, method }` (and `{ error, status }` for 500). 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)` | Low-level server extension hook (e.g. mounting third-party sub-apps or raw middleware). ⚠️ **NEVER** use `setupRoutes` to define application domain or API routes. All application endpoints **MUST** live under `pages/` and `pages/api/`. |
-
-**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**.
-
-### Dual authentication (Session + JWT & Refresh Tokens) — essentials
-
-- **Import:** `const { createAuth, quickAuth, hash, verify, signJwt, verifyJwt, decodeJwt, createRememberTokensTable } = require('webspresso/core/auth')` (published `core/` tree on npm; **not** re-exported from package root).
-- **Dual Architecture:**
-  - **Session + Cookie (Stateful):** Primary for browser SSR routes and Admin Panel (`/`, `/_admin`). Uses `httpOnly` secure cookies.
-  - **JWT + Refresh Token (Stateless):** Built-in zero-dependency HS256 auth for REST APIs, Mobile Apps, and SPAs (`/api/*`). Uses `Authorization: Bearer <token>` for access tokens and rotatable Refresh Tokens.
-- **`createAuth({ findUserById, findUserByCredentials, session: { secret }, jwt: { secret, refreshSecret, expiresIn, refreshExpiresIn }, rememberTokens?, ... })`** — adapter pattern; optional **remember-me** via `rememberTokens` and opt-in **JWT / Refresh Tokens**.
-- **`quickAuth({ db, userModel, identifierField, passwordField, rememberMe, jwt })`** — wires **`getRepository`** + bcrypt **`verify`**; optional Knex **`remember_tokens`** and **JWT / Refresh Token** manager (`jwt: true` or `jwt: { expiresIn: '15m', refreshExpiresIn: '30d' }`).
-- **JWT Helper Methods:**
-  - **`auth.generateUserToken(user, options)`** — generates short-lived access JWT (`type: 'access'`).
-  - **`auth.generateRefreshToken(user, options)`** — generates long-lived refresh JWT (`type: 'refresh'`).
-  - **`auth.refreshAccessToken(refreshToken, options)`** — verifies refresh token and issues new access token + rotated refresh token.
-  - **`auth.requireJwt()`** — guard middleware enforcing valid `Bearer` access token.
-- **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']` (SSR logged in), `middleware: ['jwt']` (API Bearer token), or `['guest']` (logged-out only). For JSON APIs mounted in **`setupRoutes`**, use **`ctx.authMiddleware.requireJwt()`** or **`requireAuth({ api: true })`**.
-- **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 & JWT)** 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 & Versioning:** `fsy.asset(path)` (returns versioned `?v=...` or Vite/Webpack manifest resolved URL), `fsy.css(href, attrs)` (generates `<link>` tag), `fsy.js(src, attrs)` (generates `<script>` tag with boolean attributes), `fsy.img(src, alt, attrs)` (generates `<img>` tag). Configured via `createApp({ assets: { version, manifestPath, prefix } })`.
-- **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`).
-- **`zdb.file()`:** varchar column for uploaded asset URL/path; admin forms render a file upload widget when `uploadPlugin` is registered (or `adminPanelPlugin({ uploadUrl })`). Optional `ui: { label, accept, maxBytes }`. For `zdb.string()` columns use `admin.customFields: { col: { type: 'file-upload' } }`.
-- **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`, `db:scaffold` (all models → create migrations).
-
-**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`**; supports custom HTML & external URL pages (`url`, `html`, `htmlFile`, `layout: false`) and SSR script/style imports (`scripts`, `styles`, `registerScript`, `registerStyle`); 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; pairs with admin **`zdb.file()`** / **`customFields.file-upload`** when registered before **`adminPanelPlugin`** |
-| `siteAnalyticsPlugin` | Self-hosted page views + admin charts |
-| `auditLogPlugin` | Admin mutation audit trail |
-| `recaptchaPlugin` | v2/v3 + middleware |
-| `emailPlugin` | MJML + Nodemailer sending with optional admin UI and auth bridge |
-| `polarPlugin` | Polar.sh billing: checkout, portal, webhooks, tier sync (`webspresso polar:migrate`) |
-| `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. **NEVER use Express routes (`app.get` / `routes/`)** — Webspresso is 100% file-based. Never create `routes/` or call `app.get()`. All routes must live in `pages/` and `pages/api/`.
-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)**.