webspresso 0.0.96 → 0.0.98

package/.agents/skills/webspresso-admin-and-plugins/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: webspresso-admin-and-plugins
+description: >-
+  Extend the Mithril.js Admin Panel SPA and configure official plugins in Webspresso.
+  Use when creating custom admin pages (component.js, page.json), custom field renderers,
+  dashboard widgets, actions, or configuring plugins like fileManager, xlsx, csv, polar, realtime, csrf, cors, and basicAuth.
+---
+
+# Webspresso Admin Panel & Plugins Skill
+
+The Admin Panel is a modular Mithril.js SPA mounted at `/_admin` powered by `adminPanelPlugin({ db })`.
+
+---
+
+## 1. Custom Admin Pages (`pagesDir` or `registerPageDir`)
+
+Folder structure for auto-discovered admin pages:
+```text
+admin/pages/
+└── system-stats/
+    ├── page.json
+    └── component.js
+```
+
+### `page.json`
+```json
+{
+  "id": "system-stats",
+  "label": "System Statistics",
+  "icon": "activity",
+  "order": 10,
+  "layout": true,
+  "permission": "admin"
+}
+```
+
+### `component.js` (Clean Mithril Component)
+```javascript
+module.exports = {
+  oninit(vnode) {
+    vnode.state.stats = null;
+    vnode.state.loading = true;
+    m.request({ method: 'GET', url: '/_admin/api/custom/stats' }).then((res) => {
+      vnode.state.stats = res;
+      vnode.state.loading = false;
+    });
+  },
+  view(vnode) {
+    if (vnode.state.loading) return m('.p-6', 'Loading stats...');
+    return m('.space-y-4', [
+      m('h2.text-xl.font-bold', 'System Overview'),
+      m('.grid.grid-cols-3.gap-4', [
+        m('.card.p-4.border.rounded', [
+          m('.text-sm.text-gray-500', 'Total Users'),
+          m('.text-2xl.font-semibold', vnode.state.stats.usersCount),
+        ]),
+      ]),
+    ]);
+  },
+};
+```
+
+---
+
+## 2. Admin Panel Extension Points
+
+```javascript
+// Register custom widget in dashboard
+registry.registerWidget('recent-signups', {
+  label: 'Recent Signups',
+  component: require('./widgets/recent-signups'),
+  width: 'half', // 'full' | 'half' | 'third'
+});
+
+// Register single record action button
+registry.registerAction('User', {
+  name: 'impersonate',
+  label: 'Impersonate',
+  icon: 'user-check',
+  handler: async (record) => { ... },
+});
+
+// Register custom field display/edit renderer
+registry.registerFieldRenderer('color-picker', {
+  display: (val) => m('.w-6.h-6.rounded', { style: { backgroundColor: val } }),
+  edit: (val, onChange) => m('input[type=color]', { value: val, onchange: (e) => onChange(e.target.value) }),
+});
+```
+
+---
+
+## 3. Official Plugin Catalog & Usage
+
+In `createApp({ plugins: [...] })`:
+
+```javascript
+const {
+  adminPanelPlugin,
+  fileManagerPlugin,
+  xlsxPlugin,
+  csvPlugin,
+  basicAuthPlugin,
+  corsPlugin,
+  csrfPlugin,
+  realtimePlugin,
+  polarPlugin,
+} = require('webspresso/plugins');
+
+createApp({
+  plugins: [
+    adminPanelPlugin({ db }),
+    fileManagerPlugin({ baseDir: './public/uploads', publicBasePath: '/uploads' }),
+    xlsxPlugin(),
+    csvPlugin(),
+    basicAuthPlugin({ users: { admin: process.env.ADMIN_BASIC_AUTH_PASS }, routes: ['/metrics'] }),
+    corsPlugin({ origin: ['https://example.com'], credentials: true }),
+    csrfPlugin({ cookie: true }),
+    realtimePlugin({ adapter: 'websocket' }),
+    polarPlugin({ apiKey: process.env.POLAR_ACCESS_TOKEN }),
+  ],
+});
+```

package/.agents/skills/webspresso-framework/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: webspresso-framework
+description: >-
+  Core workflow and guide for Webspresso, a lightweight, zero-dependency-sprawl full-stack
+  Node.js SSR and API framework. Use when scaffolding, architecting, building, or debugging
+  Webspresso applications, configuring plugins, dual auth, response compression, graceful shutdown,
+  and error boundaries.
+---
+
+# Webspresso Framework Master Guide
+
+Webspresso is a 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, and a customizable Mithril.js SPA Admin Panel.
+
+## 🛡️ 4-Step Mandatory Agent Workflow Protocol
+
+1. **Discover & Triage**: Identify relevant topic guides (`.agents/`) and inspect existing files in `pages/api/`, `models/`, `services/`.
+2. **Contract Adherence**: Export `{ schema, middleware, handler }` for APIs, `defineModel` for ORM, `defineService` for services.
+3. **Zero External Dependencies**: Core functionality relies strictly on native Node.js modules (`crypto`, `path`, `fs`, `zlib`, `events`). NEVER install ad-hoc packages for JWT, passport, express-session, or custom routers.
+4. **Targeted Verification**: Run specific Vitest unit tests (`npx vitest run tests/...`) to ensure zero regressions.
+
+---
+
+## ⚖️ Golden Rules & Anti-Patterns
+
+| Category | ❌ NEVER DO THIS (Anti-Pattern) | ✅ ALWAYS DO THIS (Webspresso Way) |
+| :--- | :--- | :--- |
+| **Routing** | `routes/index.js`, `express.Router()`, `app.get('/api/users')` | `pages/api/users.get.js` exporting `{ schema, handler }` |
+| **Database** | `db('users').where({ id }).select()` (Raw Knex) | `db.getRepository('User').findById(id)` |
+| **Business Logic** | `controllers/UserController.js` | `services/user/get.js` → `ctx.service('user.get', input)` |
+| **Auth** | `npm i jsonwebtoken passport express-session` | Built-in `req.auth`, `core/auth`, `middleware: ['jwt']` |
+| **SSR Rendering**| `res.render('profile.njk', data)` inside handlers | Companion loader `pages/profile.js` exporting `async function load()` |
+| **Exceptions** | `res.status(404).json({ error: 'Not found' })` | `throw new NotFoundError('User not found')` |
+| **Background** | `setTimeout(...)`, `npm i bullmq` | `jobs/user/welcome.js` → `req.queue.dispatch('user.welcome', data)` |
+
+---
+
+## 🚀 CLI Commands
+
+```bash
+webspresso dev              # Start dev server with hot reload
+webspresso start            # Start production server
+webspresso doctor           # Run system sanity checks
+webspresso db:migrate       # Run pending Knex migrations
+webspresso db:seed          # Run database seeders
+webspresso agents:init      # Scaffold AI Agent rules and skills
+```
+
+---
+
+## 🏗️ Core Architecture Overview
+
+- **`pages/` & `pages/api/`**: File-based SSR templates (`.njk`), companion data loaders (`.js`), and method-suffixed API endpoints (`.get.js`, `.post.js`).
+- **`services/`**: Auto-discovered domain services mapping to dot-separated names (`'user.create'`).
+- **`models/`**: Schema-driven ORM models with `zdb` definitions, repositories, relations, scopes, and query cache.
+- **`plugins/`**: Modular extension ecosystem (Admin Panel, Media Library, Polar Billing, CSV/XLSX, Realtime, CSRF, CORS, Basic Auth).
+- **`views/`**: Nunjucks layouts, partials, and `fsy` template helpers.

package/.agents/skills/webspresso-orm-and-database/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: webspresso-orm-and-database
+description: >-
+  Define models, run queries, handle transactions, manage relations, and scaffold migrations in
+  Webspresso ORM. Use when writing database models (defineModel), using zdb schema builders,
+  querying repositories (db.getRepository), configuring query cache, soft deletes, and ambient transactions.
+---
+
+# Webspresso ORM & Database Skill
+
+⚠️ **CRITICAL ANTI-PATTERN:** Never write raw Knex table queries (e.g. `db('users')` or `knex('users')`) in application code. Always use Repositories (`db.getRepository('ModelName')`).
+
+---
+
+## 1. Defining Models (`models/*.js`)
+
+```javascript
+const { defineModel, zdb } = require('webspresso');
+
+module.exports = defineModel({
+  name: 'Product',
+  table: 'products',
+  primaryKey: 'id',
+  
+  schema: zdb.object({
+    id: zdb.id(),
+    name: zdb.string().min(1).max(255),
+    slug: zdb.string().unique(),
+    price: zdb.decimal({ precision: 10, scale: 2 }),
+    in_stock: zdb.boolean().default(true),
+    metadata: zdb.json().optional(),
+    user_id: zdb.foreignKey('users.id'),
+    created_at: zdb.timestamp().autoCreate(),
+    updated_at: zdb.timestamp().autoUpdate(),
+    deleted_at: zdb.timestamp().nullable(),
+  }),
+
+  relations: {
+    user: {
+      type: 'belongsTo',
+      model: 'User',
+      foreignKey: 'user_id',
+    },
+    reviews: {
+      type: 'hasMany',
+      model: 'Review',
+      foreignKey: 'product_id',
+    },
+  },
+
+  scopes: {
+    softDelete: true, // enables deleted_at filtering automatically
+    active: (query) => query.where('in_stock', true),
+  },
+
+  hidden: ['metadata.internal_notes'], // stripped from output
+
+  cache: 'auto', // query caching ('auto' | 'smart' | true)
+
+  admin: {
+    enabled: true,
+    label: 'Products',
+    icon: 'package',
+    columns: ['name', 'price', 'in_stock', 'created_at'],
+    search: ['name', 'slug'],
+    filters: ['in_stock', 'user_id'],
+  },
+});
+```
+
+---
+
+## 2. Repositories API
+
+```javascript
+const repo = db.getRepository('Product');
+
+// Single Record Queries
+const item = await repo.findById(id);
+const item = await repo.findOne({ slug: 'espresso-blend' });
+
+// Multiple Records & Filtering
+const activeItems = await repo.find({ in_stock: true });
+
+// Insert & Update (auto-validates with schema & triggers lifecycle hooks)
+const created = await repo.create({
+  name: 'Espresso Blend',
+  slug: 'espresso-blend',
+  price: 14.99,
+  user_id: user.id,
+});
+
+const updated = await repo.update(created.id, { price: 16.99 });
+
+// Deletion (respects softDelete scope)
+await repo.delete(id);
+
+// Fluent Query Builder with Eager Loading & Pagination
+const results = await repo.query()
+  .where('price', '>=', 10)
+  .include('user', 'reviews')
+  .orderBy('created_at', 'desc')
+  .paginate({ page: 1, limit: 20 });
+// Returns: { data: [...], pagination: { total, page, limit, totalPages } }
+```
+
+---
+
+## 3. Ambient Transactions (`AsyncLocalStorage`)
+
+Inside `db.transaction()` or services declared with `transaction: true`, all repository operations automatically bind to the ambient transaction without manual `trx` passing:
+
+```javascript
+await db.transaction(async () => {
+  const user = await db.getRepository('User').create(userData);
+  const account = await db.getRepository('Account').create({ userId: user.id, balance: 100 });
+  // Automatically commits if promise resolves, or rolls back if an exception is thrown
+});
+```

package/.agents/skills/webspresso-routing-and-api/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: webspresso-routing-and-api
+description: >-
+  Build and declare file-based API endpoints and SSR pages in Webspresso using defineApi, definePage,
+  and defineModule. Use when writing route handlers, data loaders (load()), parameter brackets ([id]),
+  Zod input validation, response streaming, and route middleware.
+---
+
+# Webspresso Routing & API Skill
+
+Webspresso uses strictly file-based routing. Never use `express.Router()`, `app.get()`, or a `routes/` directory.
+
+---
+
+## 1. File-Based API Endpoints (`pages/api/...`)
+
+All API routes live in `pages/api/` and use HTTP method extensions:
+- `pages/api/notes.get.js` → `GET /api/notes`
+- `pages/api/notes.post.js` → `POST /api/notes`
+- `pages/api/notes/[id].get.js` → `GET /api/notes/:id`
+- `pages/api/notes/[id].delete.js` → `DELETE /api/notes/:id`
+
+### Standard `defineApi` Contract
+
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      title: z.string().min(1, 'Title is required'),
+      content: z.string().optional(),
+    }),
+    params: z.object({
+      id: z.string().optional(),
+    }),
+    query: z.object({
+      filter: z.string().optional(),
+    }),
+  }),
+  middleware: ['auth'], // optional named middleware string or array of middlewares
+  handler: async (req, res, ctx) => {
+    // 1. Validated input is automatically available in req.input
+    const { title, content } = req.input.body;
+
+    // 2. Repositories and Services are injected
+    const note = await req.db.getRepository('Note').create({ title, content });
+
+    // 3. Return response
+    return res.status(201).json(note);
+  },
+});
+```
+
+---
+
+## 2. SSR HTML Pages & Data Loaders (`pages/...`)
+
+- **Template**: `pages/products/[id].njk`
+- **Companion Loader**: `pages/products/[id].js`
+
+### Companion Loader (`definePage`)
+
+```javascript
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
+  middleware: ['auth'], // optional
+  head: {
+    title: 'Product Details',
+  },
+  load: async ({ req, res, db, ctx }) => {
+    const product = await db.getRepository('Product').findById(req.params.id);
+    if (!product) {
+      throw new ctx.errors.NotFoundError('Product not found');
+    }
+    return { product, title: product.name };
+  },
+});
+```
+
+### Template (`.njk`)
+
+```nunjucks
+{% extends "layout.njk" %}
+
+{% block content %}
+<div class="product-page">
+  <h1>{{ product.name }}</h1>
+  <p class="price">{{ fsy.formatCurrency(product.price) }}</p>
+  <p>{{ product.description }}</p>
+</div>
+{% endblock %}
+```
+
+---
+
+## 3. Modular Domain Architecture (`defineModule`)
+
+Encapsulate feature domains inside `src/modules/` or `modules/`:
+
+```javascript
+const { defineModule } = require('webspresso');
+
+module.exports = defineModule({
+  name: 'billing',
+  pages: './pages',     // auto-discovers pages under /billing/*
+  api: './api',         // auto-discovers API under /api/billing/*
+  services: './services', // auto-discovers services under 'billing.*'
+  middlewares: {
+    paidOnly: (req, res, next) => { ... },
+  },
+});
+```

package/.agents/skills/webspresso-services/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: webspresso-services
+description: >-
+  Encapsulate business logic, validations, transactions, and authorizations in Webspresso services.
+  Use when writing service files (services/domain/action.js), defining schemas (defineService),
+  configuring transaction: true, calling ctx.service() or req.service(), and adding RBAC guards.
+---
+
+# Webspresso Services Layer Skill
+
+⚠️ **CRITICAL ANTI-PATTERN:** Never create a `controllers/` folder or controller classes. Encapsulate multi-step business logic in `services/` and invoke via `ctx.service()` or `req.service()`.
+
+---
+
+## 1. File-Based Auto-Discovery (`services/`)
+
+Files in `services/` map directly to dot-separated service names:
+- `services/user/create.js` → `'user.create'`
+- `services/order/checkout.js` → `'order.checkout'`
+- `services/billing/process-refund.js` → `'billing.process-refund'` (and `'billing.processRefund'`)
+
+---
+
+## 2. Defining Services (`defineService`)
+
+```javascript
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  schema: ({ z }) => z.object({
+    userId: z.number().int().positive(),
+    amount: z.number().positive(),
+    reason: z.string().min(3),
+  }),
+
+  // Optional Declarative Auth / Role Guard
+  auth: ['admin', 'manager'], // or boolean true, or (ctx, input) => boolean
+
+  // Automatic ACID Transaction Propagation
+  transaction: true,
+
+  // Optional Service Result Cache
+  cache: {
+    ttl: 300, // seconds
+    key: (input) => `refund:${input.userId}:${input.amount}`,
+  },
+
+  // Execution Handler
+  handler: async (input, ctx) => {
+    // ctx.db, ctx.service, ctx.user, ctx.logger are automatically injected
+    const userRepo = ctx.db.getRepository('User');
+    const accountRepo = ctx.db.getRepository('Account');
+
+    const user = await userRepo.findById(input.userId);
+    if (!user) {
+      throw new ctx.errors.NotFoundError('User not found');
+    }
+
+    const account = await accountRepo.findOne({ userId: user.id });
+    const updatedAccount = await accountRepo.update(account.id, {
+      balance: account.balance + input.amount,
+    });
+
+    // Nested service call shares the same ambient transaction automatically
+    await ctx.service('audit.log', {
+      action: 'refund.processed',
+      userId: user.id,
+      amount: input.amount,
+    });
+
+    return {
+      success: true,
+      balance: updatedAccount.balance,
+    };
+  },
+});
+```
+
+---
+
+## 3. Invoking Services
+
+From SSR Companion Loaders:
+```javascript
+module.exports = definePage({
+  load: async ({ ctx }) => {
+    const data = await ctx.service('order.summary', { userId: ctx.user.id });
+    return { data };
+  },
+});
+```
+
+From API Route Handlers:
+```javascript
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const result = await req.service('order.checkout', req.input.body);
+    return res.status(200).json(result);
+  },
+});
+```

package/bin/commands/add-esbuild.js

@@ -0,0 +1,80 @@
+/**
+ * Add esbuild Command
+ * Add esbuild client bundling and incremental watch to the project
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function registerCommand(program) {
+  program
+    .command('add esbuild')
+    .alias('add:esbuild')
+    .description('Add esbuild client bundling and incremental watch to the project')
+    .action(async () => {
+      if (!fs.existsSync('package.json')) {
+        console.error('❌ Not a Webspresso project! Run this command in your project directory.');
+        process.exit(1);
+      }
+
+      console.log('\n⚡ Adding esbuild client bundler to your project...\n');
+
+      // Read package.json
+      const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+      packageJson.devDependencies = packageJson.devDependencies || {};
+      packageJson.devDependencies['esbuild'] = '^0.25.0';
+
+      packageJson.scripts = packageJson.scripts || {};
+      packageJson.scripts['build:js'] = 'esbuild src/client/main.js --bundle --outdir=public/js --minify --sourcemap';
+      packageJson.scripts['watch:js'] = 'esbuild src/client/main.js --bundle --outdir=public/js --sourcemap --watch';
+
+      fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n');
+      console.log('✅ Updated package.json (esbuild devDependency and build:js / watch:js scripts)');
+
+      // Create src/client directory
+      if (!fs.existsSync('src/client')) {
+        fs.mkdirSync('src/client', { recursive: true });
+      }
+
+      // Create src/client/main.js if not exists
+      const mainJsPath = path.join('src', 'client', 'main.js');
+      if (!fs.existsSync(mainJsPath)) {
+        const clientStarterCode = `// Client-side JavaScript entry point
+console.log('⚡ Webspresso client script loaded');
+
+document.addEventListener('DOMContentLoaded', () => {
+  // Client interactivity
+});
+`;
+        fs.writeFileSync(mainJsPath, clientStarterCode);
+        console.log('✅ Created src/client/main.js');
+      }
+
+      // Create public/js directory
+      if (!fs.existsSync(path.join('public', 'js'))) {
+        fs.mkdirSync(path.join('public', 'js'), { recursive: true });
+      }
+
+      // Update layout.njk to include script if not present
+      const layoutPath = path.join('views', 'layout.njk');
+      if (fs.existsSync(layoutPath)) {
+        let layoutContent = fs.readFileSync(layoutPath, 'utf-8');
+        if (!layoutContent.includes('/js/main.js')) {
+          layoutContent = layoutContent.replace(
+            /(<\/head>)/,
+            '  <script defer src="/js/main.js"></script>\n$1'
+          );
+          fs.writeFileSync(layoutPath, layoutContent);
+          console.log('✅ Updated views/layout.njk (<script defer src="/js/main.js"></script>)');
+        }
+      }
+
+      console.log('\n✅ esbuild setup complete!\n');
+      console.log('Next steps:');
+      console.log('  npm install');
+      console.log('  npm run build:js');
+      console.log('  npm run dev\n');
+    });
+}
+
+module.exports = { registerCommand };