webspresso 0.0.73 → 0.0.75

package/README.md

@@ -19,6 +19,7 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Session authentication** (optional): `createAuth` / `quickAuth` in **`webspresso/core/auth`** — pass the manager to **`createApp({ auth })`** for `express-session`, `req.user` / `req.auth`, remember-me tokens, and policy-style authorization. Full walkthrough: **[`doc/index.html#authentication`](doc/index.html#authentication)**.
 - **Optional client runtime** (Alpine.js + [swup](https://swup.js.org/)): **`createApp({ clientRuntime: { alpine, swup } })`** serves scripts under **`/__webspresso/client-runtime/`** and exposes **`clientRuntime`** in Nunjucks; layouts can include **`views/partials/webspresso-client-runtime.njk`**. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`**. Demo: **`examples/alpine-swup-demo/`**. Details: **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
 - **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
+- **Application kernel (optional)**: In-process **`kernel`** API (`require('webspresso').kernel`) — event bus (`dispatch` / `publish`), **`kernel.createApp()`** (namespaced differently from SSR **`createApp`**), **`definePlugin`** / **`defineFlow`**, minimal **`{{ }}` view resolver**, and simulated **`BaseRepository`** with `orm.<resource>.*` events. Ships as **`core/kernel/`** on npm. Demo: **`node core/kernel/run-demo.js`**. Docs: **[`doc/index.html#application-kernel`](doc/index.html#application-kernel)**.
 
 ## Installation
 
@@ -40,6 +41,18 @@ Install **`@types/express`** in your app if you want full **`Express.Application
 
 Framework development (this repo): run **`npm run check:types`** to typecheck the declarations against a small smoke file (`tests/ts-smoke/`).
 
+## Application kernel (`kernel`)
+
+Do **not** confuse **`kernel.createApp()`** with the package root **`createApp`** used for SSR—it returns a different object (event bus, optional flows, and a minimal view resolver). It does **not** modify Knex ORM behavior or Express routing.
+
+```javascript
+const { kernel } = require('webspresso');
+const app = kernel.createApp();
+app.events.on('orm.post.afterCreate', async (ctx) => { /* ... */ });
+```
+
+See **[`doc/index.html#application-kernel`](doc/index.html#application-kernel)** · source modules: [`core/kernel/`](core/kernel/). Cursor skill: **`REFERENCE-kernel.md`** (installed via `webspresso skill --preset webspresso`).
+
 ## Quick Start
 
 ### Using CLI (Recommended)
@@ -234,7 +247,7 @@ webspresso doctor --strict
 
 Scaffold a **Cursor Agent Skill**: creates `.cursor/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.cursor/skills/` instead of the current project.
 
-**Bundled preset:** `--preset webspresso` copies the full **Webspresso usage** reference skill (framework routing, ORM, plugins, CLI, pitfalls) into `.cursor/skills/webspresso-usage/SKILL.md` — no prompts.
+**Bundled preset:** `--preset webspresso` copies **`SKILL.md`** (short index), **`REFERENCE-framework.md`** (SSR `createApp`, routes, ORM, auth, plugins, CLI), and **`REFERENCE-kernel.md`** (`kernel` event bus / flows) into **`.cursor/skills/webspresso-usage/`** — no prompts.
 
 ```bash
 webspresso skill my-workflow
@@ -533,6 +546,14 @@ Error templates receive these variables:
 - `500.njk`: `{ error, status, isDev }`
 - `503.njk`: `{ url, method, isDev }`
 
+**How errors reach this handler**
+
+Unhandled errors from file-based routes (`pages/**/*.njk` `load()` / middleware / render, and `pages/api/**/*.js` handlers) are forwarded with `next(err)`, so they go through this 4-argument Express error middleware. That means `errorPages.serverError` and `errorPages.timeout` apply to those failures as well (not only to routes you add with `setupRoutes`).
+
+- **`pages/_hooks.js` `onError(ctx, err)`** runs **before** the central handler (for both SSR and API file routes). Use it for logging or APM (`Sentry.captureException`, `newrelic.noticeError`, etc.). The error is also on **`ctx.error`**.
+
+- **JSON vs HTML:** Requests whose path starts with **`/api`** always get a **JSON** error body from the default branch (and the default **string** `serverError` / `timeout` Nunjucks templates are skipped for those paths). Other clients use **`Accept`** as before: prefer HTML when the client accepts HTML.
+
 **Request Timeout:**
 
 Configure request timeout with `connect-timeout`:
@@ -682,6 +703,22 @@ Options:
 - `path` - Custom dashboard path (default: `/_webspresso`)
 - `enabled` - Force enable/disable (default: auto based on NODE_ENV)
 
+**Redirect plugin:**
+- Runs in `register()` **before** file-based routes, so configured paths override SSR pages.
+- Rules: `from` (string or `RegExp`), `to` (path or URL), optional `status` (301/302/303/307/308), optional `methods` (`'*'` or a list; default plugin methods are `GET` and `HEAD` only).
+- `preserveQuery` (default `true`) appends the request query when `to` has no `?`. External `to` values require `allowExternal: true`.
+
+```javascript
+const { redirectPlugin } = require('webspresso/plugins');
+
+redirectPlugin({
+  rules: [
+    { from: '/old-blog', to: '/blog', status: 301 },
+    { from: /^\/wiki\/(.*)$/, to: '/docs' },
+  ],
+});
+```
+
 **Sitemap Plugin:**
 - Generates `/sitemap.xml` from routes automatically
 - **Dynamic Database Content**: Generate URLs from database records
@@ -764,10 +801,12 @@ const { app } = createApp({
 Options:
 - `db` (required) - Database instance
 - `path` - Admin panel path (default: `/_admin`)
-- `auth` - Auth manager for user management
-- `userManagement` - User management config (`enabled`, `model`, `fields`)
+- `auth` - Same **`AuthManager`** instance as **`createApp({ auth })`** when you use **`userManagement`** — enables **Active Sessions** / revoke APIs if **`rememberTokens`** (remember-me) is configured; optional for user CRUD-only
+- `userManagement` - Site-user admin UI (`enabled`, `model` matching ORM user table, optional `fields` map). SPA routes: `/_admin/users`, `/_admin/users/new`, …; APIs: `/_admin/api/users*`. Admin staff still use **`admin_users`** / `/_admin` login; this is separate from **`req.user`** on the public site
 - `configure` - Callback `(registry) => void` for manual setup
 
+See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.cursor/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
+
 **Custom Admin Pages (registerModule):**
 
 Plugins can add custom admin pages using `registerModule` in `onRoutesReady`:
@@ -2208,8 +2247,9 @@ npm run test:watch
 # Run tests with coverage
 npm run test:coverage
 
-# Micro-benchmarks (Vitest bench; also runs in CI on the test matrix)
+# Micro-benchmarks (Vitest bench; CI: main push uploads benchmark-baseline artifact, PRs compare against it)
 npm run bench
+# Local baseline + compare: npm run bench:ci:local
 ```
 
 ## License

package/bin/commands/orm-map.js

@@ -0,0 +1,139 @@
+/**
+ * ORM map — interactive single-page HTML of models and relationships
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { getWebspressoOrmForProject } = require('../utils/resolve-webspresso-orm');
+const { loadProjectModels } = require('../utils/orm-map-load');
+const { buildSnapshot, buildMermaidErDiagram } = require('../utils/orm-map-snapshot');
+const { buildOrmMapHtml, readPackageName } = require('../utils/orm-map-html');
+
+function ensureOpenInsideTrustedRoots(absFile, cwd) {
+  if (!fs.existsSync(absFile)) {
+    throw new Error(`File does not exist: ${absFile}`);
+  }
+  let realFile;
+  try {
+    realFile = fs.realpathSync(absFile);
+  } catch (e) {
+    throw new Error(`Cannot resolve file path: ${absFile}`, { cause: e });
+  }
+
+  /** @type {string[]} */
+  const roots = [];
+  for (const base of [os.tmpdir(), cwd]) {
+    const resolvedBase = path.resolve(base);
+    try {
+      roots.push(fs.realpathSync(resolvedBase));
+    } catch {
+      roots.push(resolvedBase);
+    }
+  }
+
+  const fileNorm = path.normalize(realFile + path.sep);
+  const trusted = roots.some((rootRaw) => {
+    const rr =
+      typeof rootRaw === 'string' && fs.existsSync(rootRaw)
+        ? fs.realpathSync(rootRaw)
+        : path.normalize(rootRaw);
+    const rp = rr.endsWith(path.sep) ? rr : rr + path.sep;
+    return realFile === rr || fileNorm.startsWith(path.normalize(rp));
+  });
+
+  if (!trusted) {
+    throw new Error('Refused to open file outside cwd or OS temp dir');
+  }
+}
+
+function openFile(filePath, cwd) {
+  const fp = path.resolve(filePath);
+  ensureOpenInsideTrustedRoots(fp, cwd);
+  if (process.platform === 'darwin') {
+    execFileSync('open', [fp], { stdio: 'ignore' });
+  } else if (process.platform === 'win32') {
+    execFileSync('cmd', ['/c', 'start', '', fp], { stdio: 'ignore' });
+  } else {
+    execFileSync('xdg-open', [fp], { stdio: 'ignore' });
+  }
+}
+
+function registerCommand(program) {
+  program
+    .command('orm:map')
+    .description(
+      'Generate a self-contained HTML map of ORM models and relations (opens in browser by default)',
+    )
+    .option('-o, --output <file>', 'Write HTML to this path instead of a temp file')
+    .option('--no-open', 'Do not open the browser')
+    .option('-c, --config <path>', 'Database config file (webspresso.db.js / knexfile.js) for models path')
+    .option('-e, --env <environment>', 'Config environment', 'development')
+    .option('-m, --models <dir>', 'Models directory (overrides config default ./models)')
+    .action((options) => {
+      const cwd = process.cwd();
+      const { modelsDir, loaded, errors } = loadProjectModels(cwd, {
+        modelsOverride: options.models,
+        configPath: options.config,
+        env: options.env,
+      });
+
+      for (const err of errors) {
+        if (!err.file) {
+          console.error(`❌ ${err.message}`);
+        } else {
+          console.warn(`⚠️  ${err.file}: ${err.message}`);
+        }
+      }
+
+      if (loaded.length === 0 && errors.some((e) => e.file === '')) {
+        process.exit(1);
+      }
+
+      const orm = getWebspressoOrmForProject(cwd);
+      const registry = orm.getAllModels();
+      if (registry.size === 0) {
+        console.error(
+          `❌ No models registered. Checked: ${modelsDir}\n` +
+            '   Add defineModel() files or pass --models <dir>.',
+        );
+        process.exit(1);
+      }
+
+      const snapshot = buildSnapshot(registry);
+      const mermaid = buildMermaidErDiagram(snapshot);
+      const pkg = readPackageName(cwd);
+      const html = buildOrmMapHtml(snapshot, mermaid, {
+        title: 'ORM model map',
+        packageName: pkg,
+      });
+
+      let outPath;
+      if (options.output) {
+        outPath = path.resolve(cwd, options.output);
+      } else {
+        outPath = path.join(
+          os.tmpdir(),
+          `webspresso-orm-map-${Date.now()}.html`,
+        );
+      }
+
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      fs.writeFileSync(outPath, html, 'utf8');
+
+      console.log(`\n✅ ORM map (${registry.size} model(s))`);
+      console.log(`   Models dir: ${modelsDir}`);
+      console.log(`   Written: ${outPath}\n`);
+
+      if (options.open !== false) {
+        try {
+          openFile(outPath, cwd);
+        } catch (e) {
+          console.warn(`⚠️  Could not open browser: ${e.message}`);
+        }
+      }
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/skill.js

@@ -28,11 +28,11 @@ function defaultDescription(skillName) {
   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 path under bin/ */
+/** Bundled presets: CLI flag → template directory (all *.md copied) */
 const PRESETS = {
   webspresso: {
     skillName: 'webspresso-usage',
-    templatePath: path.join(__dirname, '../../templates/skills/webspresso-usage/SKILL.md'),
+    templateDir: path.join(__dirname, '../../templates/skills/webspresso-usage'),
   },
 };
 
@@ -76,7 +76,10 @@ function registerCommand(program) {
     .option('-g, --global', 'Write to ~/.cursor/skills/ instead of ./.cursor/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 → full Webspresso agent reference (SKILL.md)')
+    .option(
+      '-p, --preset <name>',
+      'Install bundled skill: webspresso → agent reference (SKILL.md + REFERENCE-*.md in .cursor/skills/webspresso-usage/)',
+    )
     .action(async (nameArg, options) => {
       const presetKey = options.preset ? String(options.preset).trim().toLowerCase() : '';
 
@@ -86,8 +89,16 @@ function registerCommand(program) {
           console.error(`❌ Unknown preset "${presetKey}". Available: ${Object.keys(PRESETS).join(', ')}`);
           process.exit(1);
         }
-        if (!fs.existsSync(preset.templatePath)) {
-          console.error(`❌ Preset template missing: ${preset.templatePath}`);
+        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();
@@ -101,10 +112,13 @@ function registerCommand(program) {
         }
 
         fs.mkdirSync(dir, { recursive: true });
-        fs.copyFileSync(preset.templatePath, skillFile);
+        for (const file of mdFiles) {
+          fs.copyFileSync(path.join(templateDir, file), path.join(dir, file));
+        }
 
-        console.log(`\n✅ Installed bundled skill "${presetKey}" →\n   ${skillFile}\n`);
-        console.log('   Edit SKILL.md if needed, then restart Cursor or reload the window.\n');
+        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;
       }
 

package/bin/commands/upgrade.js

@@ -0,0 +1,146 @@
+/**
+ * Upgrade Command — bump the webspresso dependency in the current project
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const PKG_NAME = 'webspresso';
+
+/**
+ * @param {string} cwd
+ * @returns {'npm'|'pnpm'|'yarn'}
+ */
+function detectPackageManager(cwd) {
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/**
+ * @param {object} pkg
+ * @returns {{ specifier: string, saveDev: boolean } | null}
+ */
+function findWebspressoDep(pkg) {
+  if (!pkg || typeof pkg !== 'object') return null;
+  const prod = pkg.dependencies && pkg.dependencies[PKG_NAME];
+  const dev = pkg.devDependencies && pkg.devDependencies[PKG_NAME];
+  if (prod) return { specifier: String(prod), saveDev: false };
+  if (dev) return { specifier: String(dev), saveDev: true };
+  return null;
+}
+
+function isNonRegistrySpecifier(spec) {
+  return /^(file:|link:|workspace:|git\+|github:|http:|https:)/i.test(spec.trim());
+}
+
+/**
+ * @param {'npm'|'pnpm'|'yarn'} pm
+ * @param {string} tag
+ * @param {boolean} saveDev
+ * @returns {string[]}
+ */
+function buildInstallArgs(pm, tag, saveDev) {
+  const spec = `${PKG_NAME}@${tag}`;
+  if (pm === 'npm') {
+    return saveDev
+      ? ['install', spec, '--save-dev']
+      : ['install', spec, '--save'];
+  }
+  if (pm === 'pnpm') {
+    return saveDev ? ['add', '-D', spec] : ['add', spec];
+  }
+  /* yarn */
+  return saveDev ? ['add', '-D', spec] : ['add', spec];
+}
+
+function registerCommand(program) {
+  program
+    .command('upgrade')
+    .description(
+      'Upgrade the webspresso package in the current project (npm/pnpm/yarn)'
+    )
+    .option(
+      '-t, --tag <dist-tag>',
+      'npm dist-tag (e.g. latest, next)',
+      'latest'
+    )
+    .option('--pm <manager>', 'Force package manager: npm, pnpm, or yarn')
+    .option('--dry-run', 'Print the install command without running it')
+    .action((options) => {
+      const cwd = process.cwd();
+      const pkgPath = path.join(cwd, 'package.json');
+
+      if (!fs.existsSync(pkgPath)) {
+        console.error('❌ package.json not found. Run this from your project root.');
+        process.exit(1);
+      }
+
+      let pkg;
+      try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      } catch (e) {
+        console.error(`❌ Could not read package.json: ${e.message}`);
+        process.exit(1);
+      }
+
+      const found = findWebspressoDep(pkg);
+      if (!found) {
+        console.error(
+          `❌ No "${PKG_NAME}" entry in dependencies or devDependencies.`
+        );
+        console.error('   Add it first, e.g. npm install webspresso');
+        process.exit(1);
+      }
+
+      if (isNonRegistrySpecifier(found.specifier)) {
+        console.error(
+          `❌ "${PKG_NAME}" is not a registry semver range (current: ${found.specifier}).`
+        );
+        console.error(
+          '   For file:/link:/workspace: installs, change package.json manually or point to a published version.'
+        );
+        process.exit(1);
+      }
+
+      let pm = options.pm;
+      if (pm) {
+        pm = String(pm).toLowerCase();
+        if (!['npm', 'pnpm', 'yarn'].includes(pm)) {
+          console.error('❌ --pm must be npm, pnpm, or yarn');
+          process.exit(1);
+        }
+      } else {
+        pm = detectPackageManager(cwd);
+      }
+
+      const args = buildInstallArgs(pm, options.tag, found.saveDev);
+      const cmd = `${pm} ${args.join(' ')}`;
+
+      console.log('\nWebspresso upgrade');
+      console.log('==================\n');
+      console.log(`  Package manager: ${pm}`);
+      console.log(`  Target:          ${PKG_NAME}@${options.tag}`);
+      console.log(`  Save as:         ${found.saveDev ? 'devDependency' : 'dependency'}`);
+      console.log(`  Current range:   ${found.specifier}\n`);
+
+      if (options.dryRun) {
+        console.log(`Dry run — would run:\n  ${cmd}\n`);
+        return;
+      }
+
+      try {
+        execSync(cmd, { stdio: 'inherit', cwd, shell: true });
+        console.log(
+          '\n✅ Upgrade finished. If you use native addons (better-sqlite3, bcrypt, sharp), run:\n' +
+            '   npm run rebuild:native\n' +
+            '   (or: npm rebuild better-sqlite3 bcrypt sharp)\n'
+        );
+      } catch {
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { registerCommand, detectPackageManager, findWebspressoDep };