webspresso 0.0.81 → 0.0.83

package/README.md

@@ -245,9 +245,10 @@ webspresso doctor --strict
 
 ### `webspresso skill`
 
-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.
+Scaffold an **Agent Skill**: creates `.agents/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.agents/skills/` instead of the current project.
+
+**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 **`.agents/skills/webspresso-usage/`** — 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
@@ -805,16 +806,18 @@ Options:
 - `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 })`**.
+See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.agents/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`:
+Plugins can add custom admin pages using `registerModule` (or `registerPageDir`) in `onRoutesReady`:
 
 ```javascript
 // In your plugin's onRoutesReady(ctx)
 const adminApi = ctx.usePlugin('admin-panel');
 if (adminApi) {
+  // Option 1: File-based registration with auto Layout wrapping
   adminApi.registerModule({
     id: 'my-module',
 
@@ -824,7 +827,8 @@ if (adminApi) {
       path: '/reports',
       icon: 'chart',
       description: 'View reports',
-      component: `window.__customPages["reports"] = { view: () => m("div", "My Report") };`,  // Mithril.js
+      componentFile: path.join(__dirname, 'admin/reports.js'), // JS component file
+      layout: true, // Auto-wraps view in Admin Layout (default: true)
     }],
 
     menu: [{ id: 'reports', label: 'Reports', path: '/reports', icon: 'chart', order: 5 }],
@@ -835,15 +839,10 @@ if (adminApi) {
         { method: 'get', path: '/summary', handler: getSummaryHandler, auth: true },
       ],
     },
-
-    widgets: [{
-      id: 'reports-widget',
-      title: 'Quick Stats',
-      dataLoader: async () => ({ count: 42 }),
-    }],
-
-    menuGroups: [{ id: 'analytics', label: 'Analytics', order: 2 }],
   });
+
+  // Option 2: Folder-based auto registration (dir containing page.json + component.js)
+  adminApi.registerPageDir(path.join(__dirname, 'admin/pages'));
 }
 ```
 
@@ -851,13 +850,41 @@ if (adminApi) {
 | Field | Description |
 |-------|-------------|
 | `id` | Unique module identifier (required) |
-| `pages` | Custom admin pages (each: `id`, `title`, `path`, `icon`, `description`, optional `component`) |
+| `pages` | Custom admin pages (`id`, `title`, `path`, `icon`, `description`, `componentFile`, `component`, `layout`) |
+| `pagesDir` | Path to directory containing page folders/configs for automatic discovery |
 | `menu` | Sidebar menu items (`id`, `label`, `path`, `icon`, `order`) |
 | `menuGroups` | Collapsible menu groups (`id`, `label`, `order`) |
 | `api` | API routes (`prefix`, `routes`: `method`, `path`, `handler`, `auth`) |
 | `widgets` | Dashboard widgets (`id`, `title`, `dataLoader`) |
 
-For pages with `component`: provide Mithril.js code that assigns to `window.__customPages[pageId]`. Without `component`, the page shows a static placeholder.
+Pages support `componentFile` (path to a `.js` file exporting/returning a Mithril component), `pagesDir` (directory auto-discovery), or `component` (code string). By default (`layout: true`), page views are automatically wrapped in the Admin Layout with Breadcrumbs. Set `layout: false` for full-screen / custom canvas pages.
+
+**Example component file (`admin/reports.js`):**
+
+```javascript
+// Clean Mithril.js component object (no manual m(Layout, ...) needed!)
+({
+  oninit: async (vnode) => {
+    vnode.state.data = [];
+    try {
+      const res = await api.get('/reports/summary');
+      vnode.state.data = res.data || [];
+      m.redraw();
+    } catch (err) {
+      console.error('Failed to load report data:', err);
+    }
+  },
+  view: (vnode) => {
+    const data = vnode.state.data || [];
+    return m('div.space-y-4', [
+      m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', 'Report Summary'),
+      m('p.text-gray-600.dark:text-slate-400', `Total records: ${data.length}`),
+    ]);
+  }
+})
+```
+
+
 
 **Manual registry API** (alternative to registerModule):
 

package/bin/commands/skill.js

@@ -20,9 +20,10 @@ function validateSkillName(name) {
 }
 
 function skillDir(base, skillName) {
-  return path.join(base, '.cursor', 'skills', 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.`;
@@ -72,14 +73,15 @@ Example prompt or command
 function registerCommand(program) {
   program
     .command('skill [name]')
-    .description('Create an Agent Skill folder with SKILL.md (Cursor / AI tools)')
-    .option('-g, --global', 'Write to ~/.cursor/skills/ instead of ./.cursor/skills/')
+    .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 .cursor/skills/webspresso-usage/)',
+      '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() : '';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",

package/plugins/admin-panel/app.js

@@ -221,6 +221,55 @@ var routes = {
   },
 };
 
+function wrapCustomPageWithLayout(page, rawComp) {
+  if (!rawComp) return createCustomPage(page);
+  if (page.layout === false) return rawComp;
+
+  return {
+    oninit: function(vnode) {
+      vnode.state.instance = typeof rawComp === 'function' ? rawComp.call(this, vnode) : rawComp;
+      if (vnode.state.instance && typeof vnode.state.instance.oninit === 'function') {
+        return vnode.state.instance.oninit.call(this, vnode);
+      }
+    },
+    oncreate: function(vnode) {
+      const comp = vnode.state.instance || rawComp;
+      if (comp && typeof comp.oncreate === 'function') return comp.oncreate.call(this, vnode);
+    },
+    onupdate: function(vnode) {
+      const comp = vnode.state.instance || rawComp;
+      if (comp && typeof comp.onupdate === 'function') return comp.onupdate.call(this, vnode);
+    },
+    onbeforeremove: function(vnode) {
+      const comp = vnode.state.instance || rawComp;
+      if (comp && typeof comp.onbeforeremove === 'function') return comp.onbeforeremove.call(this, vnode);
+    },
+    onremove: function(vnode) {
+      const comp = vnode.state.instance || rawComp;
+      if (comp && typeof comp.onremove === 'function') return comp.onremove.call(this, vnode);
+    },
+    view: function(vnode) {
+      const comp = vnode.state.instance || rawComp;
+      var content;
+      if (comp && typeof comp.view === 'function') {
+        content = comp.view.call(this, vnode);
+      } else if (typeof comp === 'function') {
+        content = comp.call(this, vnode);
+      } else {
+        content = comp;
+      }
+      if (content && (content.tag === Layout || (content.tag && content.tag.name === 'Layout'))) {
+        return content;
+      }
+      var breadcrumbs = [{ label: page.title, href: page.path }];
+      return m(Layout, [
+        m(Breadcrumb, { items: breadcrumbs }),
+        content
+      ]);
+    }
+  };
+}
+
 // Dynamic routes for custom pages registered via plugins
 var config = window.__ADMIN_CONFIG__;
 if (config && config.pages) {
@@ -234,7 +283,7 @@ if (config && config.pages) {
             return;
           }
           if (window.__customPages && window.__customPages[page.id]) {
-            return window.__customPages[page.id];
+            return wrapCustomPageWithLayout(page, window.__customPages[page.id]);
           }
           return createCustomPage(page);
         }
@@ -245,3 +294,4 @@ if (config && config.pages) {
 
 m.route(document.getElementById('app'), '/', routes);
 `;
+

package/plugins/admin-panel/core/admin-module.js

@@ -1,25 +1,118 @@
+const fs = require('fs');
+const path = require('path');
+
 /**
- * Admin Module Registration System
- * Declarative API for registering admin pages, menu items, API routes, and widgets
- * @module plugins/admin-panel/core/admin-module
+ * Format client component code to ensure it assigns to window.__customPages[pageId]
  */
+function formatClientComponent(pageId, rawCode) {
+  let code = (rawCode || '').trim();
+  if (!code) return '';
+  if (code.includes('window.__customPages')) {
+    return code;
+  }
+  if (code.startsWith('module.exports =')) {
+    code = code.replace(/^module\.exports\s*=\s*/, '');
+  }
+  if (code.endsWith(';')) {
+    code = code.slice(0, -1);
+  }
+  return `window.__customPages = window.__customPages || {};\nwindow.__customPages[${JSON.stringify(pageId)}] = ${code};`;
+}
+
+/**
+ * Load page definitions and components from a directory structure
+ */
+function loadPagesFromDir(dirPath) {
+  const resolvedDir = path.resolve(dirPath);
+  if (!fs.existsSync(resolvedDir)) {
+    throw new Error(`pagesDir directory not found: ${dirPath}`);
+  }
+  const stat = fs.statSync(resolvedDir);
+  if (!stat.isDirectory()) {
+    throw new Error(`pagesDir path is not a directory: ${dirPath}`);
+  }
+
+  const entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
+  const pages = [];
+  const menuItems = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+
+    let pageConfig = null;
+    let componentFile = null;
+
+    if (entry.isDirectory()) {
+      const folderPath = path.join(resolvedDir, entry.name);
+      const jsonCandidate = path.join(folderPath, 'page.json');
+      const configJsonCandidate = path.join(folderPath, 'config.json');
+
+      if (fs.existsSync(jsonCandidate)) {
+        pageConfig = JSON.parse(fs.readFileSync(jsonCandidate, 'utf8'));
+      } else if (fs.existsSync(configJsonCandidate)) {
+        pageConfig = JSON.parse(fs.readFileSync(configJsonCandidate, 'utf8'));
+      } else {
+        pageConfig = { id: entry.name, title: entry.name, path: '/' + entry.name };
+      }
+
+      const jsCandidates = ['component.js', 'index.js', 'page.js', `${entry.name}.js`];
+      for (const cand of jsCandidates) {
+        const fullCandPath = path.join(folderPath, cand);
+        if (fs.existsSync(fullCandPath)) {
+          componentFile = fullCandPath;
+          break;
+        }
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      const jsonPath = path.join(resolvedDir, entry.name);
+      pageConfig = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+      const baseName = entry.name.slice(0, -5);
+      const jsCandidate = path.join(resolvedDir, baseName + '.js');
+      if (fs.existsSync(jsCandidate)) {
+        componentFile = jsCandidate;
+      }
+    }
+
+    if (pageConfig) {
+      if (componentFile && !pageConfig.componentFile) {
+        pageConfig.componentFile = componentFile;
+      }
+      if (pageConfig.menu) {
+        if (pageConfig.menu === true) {
+          menuItems.push({
+            id: pageConfig.id,
+            label: pageConfig.title,
+            path: pageConfig.path,
+            icon: pageConfig.icon,
+          });
+        } else if (typeof pageConfig.menu === 'object') {
+          menuItems.push({
+            id: pageConfig.id,
+            label: pageConfig.title,
+            path: pageConfig.path,
+            icon: pageConfig.icon,
+            ...pageConfig.menu,
+          });
+        }
+      }
+      pages.push(pageConfig);
+    }
+  }
+
+  return { pages, menuItems };
+}
 
 /**
  * Register an admin module with all its components in a single declarative call
  * @param {Object} config - Module configuration
  * @param {string} config.id - Unique module identifier (required)
  * @param {Array} [config.pages] - Custom admin pages
+ * @param {string} [config.pagesDir] - Directory path containing page folders/configs
  * @param {Array} [config.menu] - Sidebar menu items
  * @param {Object} [config.menuGroups] - Menu group definitions
  * @param {Object} [config.api] - API endpoint definitions
  * @param {Array} [config.widgets] - Dashboard widgets
  * @param {Object} deps - Internal dependencies injected by admin-panel
- * @param {Object} deps.registry - AdminRegistry instance
- * @param {string} deps.adminPath - Admin panel base path
- * @param {Object} deps.ctx - Plugin context
- * @param {Function} deps.requireAuth - Auth middleware
- * @param {Function} deps.optionalAuth - Optional auth middleware
- * @param {Function} deps.serveAdminPanel - SPA HTML handler
  */
 function registerModule(config, deps) {
   if (!config || typeof config !== 'object') {
@@ -36,14 +129,36 @@ function registerModule(config, deps) {
     registerMenuGroups(config.menuGroups, registry);
   }
 
-  if (config.pages) {
-    registerPages(config.id, config.pages, { registry, adminPath, ctx, optionalAuth, serveAdminPanel });
+  if (config.pages !== undefined) {
+    if (!Array.isArray(config.pages)) {
+      throw new Error(`Module "${config.id}": pages must be an array`);
+    }
+  }
+
+  if (config.menu !== undefined) {
+    if (!Array.isArray(config.menu)) {
+      throw new Error('menu must be an array');
+    }
   }
 
-  if (config.menu) {
-    registerMenuItems(config.menu, registry);
+  let pagesList = config.pages ? [...config.pages] : [];
+  let menuList = config.menu ? [...config.menu] : [];
+
+  if (config.pagesDir) {
+    const { pages: dirPages, menuItems: dirMenuItems } = loadPagesFromDir(config.pagesDir);
+    pagesList = pagesList.concat(dirPages);
+    menuList = menuList.concat(dirMenuItems);
   }
 
+  if (pagesList.length > 0) {
+    registerPages(config.id, pagesList, { registry, adminPath, ctx, optionalAuth, serveAdminPanel });
+  }
+
+  if (menuList.length > 0) {
+    registerMenuItems(menuList, registry);
+  }
+
+
   if (config.api) {
     registerApiRoutes(config.id, config.api, { adminPath, ctx, requireAuth, optionalAuth });
   }
@@ -53,6 +168,20 @@ function registerModule(config, deps) {
   }
 }
 
+/**
+ * Register custom admin pages from a directory directly
+ * @param {string} dirPath - Directory path containing custom page folders/configs
+ * @param {Object} deps - Dependencies injected by admin-panel
+ */
+function registerPageDir(dirPath, deps) {
+  const { pages, menuItems } = loadPagesFromDir(dirPath);
+  const moduleId = path.basename(dirPath);
+  registerPages(moduleId, pages, deps);
+  if (menuItems.length > 0) {
+    registerMenuItems(menuItems, deps.registry);
+  }
+}
+
 function registerPages(moduleId, pages, deps) {
   if (!Array.isArray(pages)) {
     throw new Error(`Module "${moduleId}": pages must be an array`);
@@ -73,10 +202,20 @@ function registerPages(moduleId, pages, deps) {
       icon: page.icon,
       description: page.description,
       permission: page.permission,
+      layout: page.layout !== undefined ? page.layout : true,
     });
 
-    if (page.component) {
-      registry.registerClientComponent(pageId, page.component);
+    if (page.componentFile) {
+      const resolvedPath = path.resolve(page.componentFile);
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Module "${moduleId}", page "${pageId}": componentFile not found at ${page.componentFile}`);
+      }
+      const rawCode = fs.readFileSync(resolvedPath, 'utf8');
+      const formattedCode = formatClientComponent(pageId, rawCode);
+      registry.registerClientComponent(pageId, formattedCode);
+    } else if (page.component) {
+      const formattedCode = formatClientComponent(pageId, page.component);
+      registry.registerClientComponent(pageId, formattedCode);
     }
 
     ctx.addRoute('get', `${adminPath}${page.path}`, optionalAuth, serveAdminPanel);
@@ -126,7 +265,20 @@ function registerApiRoutes(moduleId, apiConfig, deps) {
     const useAuth = route.auth !== undefined ? route.auth : defaultAuth;
     const authMiddleware = useAuth ? requireAuth : optionalAuth;
 
-    ctx.addRoute(method, fullPath, authMiddleware, route.handler);
+    const safeHandler = async (req, res, next) => {
+      try {
+        await route.handler(req, res, next);
+      } catch (err) {
+        if (typeof next === 'function') {
+          next(err);
+        } else {
+          throw err;
+        }
+      }
+    };
+    safeHandler._originalHandler = route.handler;
+
+    ctx.addRoute(method, fullPath, authMiddleware, safeHandler);
   }
 }
 
@@ -143,4 +295,5 @@ function registerWidgets(widgets, registry) {
   }
 }
 
-module.exports = { registerModule };
+module.exports = { registerModule, registerPageDir, loadPagesFromDir, formatClientComponent };
+

package/plugins/admin-panel/core/registry.js

@@ -412,9 +412,12 @@ class AdminRegistry {
         title: p.title,
         path: p.path,
         icon: p.icon,
+        description: p.description,
         permission: p.permission,
+        layout: p.layout !== undefined ? p.layout : true,
         hasClientComponent: this.clientComponents.has(p.id),
       })),
+
       widgets: this.getWidgets().map(w => ({
         id: w.id,
         title: w.title,

package/plugins/admin-panel/index.js

@@ -15,7 +15,8 @@ const { registerDashboardWidgets, generateDashboardComponent } = require('./modu
 const { registerDefaultBulkActions, generateBulkActionsComponent } = require('./modules/bulk-actions');
 const { registerDefaultPages, createCustomPageApiHandlers, generateCustomPageComponent } = require('./modules/custom-pages');
 const { registerModelMenuItems, registerSystemMenuItems, generateMenuComponent } = require('./modules/menu');
-const { registerModule } = require('./core/admin-module');
+const { registerModule, registerPageDir } = require('./core/admin-module');
+
 
 /**
  * Admin Panel Plugin Factory
@@ -105,6 +106,21 @@ function adminPanelPlugin(options = {}) {
           serveAdminPanel,
         });
       },
+      registerPageDir(dirPath) {
+        const ctx = this.api?._ctx ?? this._ctx;
+        if (!ctx) {
+          throw new Error('registerPageDir can only be called during or after onRoutesReady');
+        }
+        return registerPageDir(dirPath, {
+          registry,
+          adminPath,
+          ctx,
+          requireAuth,
+          optionalAuth,
+          serveAdminPanel,
+        });
+      },
+
       _ctx: null,
     },
 

package/plugins/audit-log/admin-component.js

@@ -34,9 +34,11 @@ function generateAuditLogComponent(options = {}) {
         rows = res.data || [];
         total = (res.meta && res.meta.total) || 0;
         loading = false;
+        if (typeof m !== 'undefined' && m.redraw) m.redraw();
       }).catch(function(e) {
         error = e.message || String(e);
         loading = false;
+        if (typeof m !== 'undefined' && m.redraw) m.redraw();
       });
     }
 

package/templates/skills/webspresso-usage/SKILL.md

@@ -33,7 +33,8 @@ There are **three** files in this folder; open the reference that matches the ta
 | `webspresso dev` | Dev server (watch). |
 | `webspresso db:migrate` / `db:rollback` / `db:status` | ORM migrations. |
 | `webspresso doctor` | Environment / project sanity checks. |
-| `webspresso skill --preset webspresso` | Copies this skill bundle under `.cursor/skills/webspresso-usage/` (`SKILL.md` + `REFERENCE-*.md`). |
+| `webspresso skill --preset webspresso` | Copies this skill bundle under `.agents/skills/webspresso-usage/` (`SKILL.md` + `REFERENCE-*.md`). |
+
 
 ## When to use this skill