webspresso 0.0.64 → 0.0.66

package/plugins/orm-cache-admin/api-handlers.js

@@ -0,0 +1,78 @@
+/**
+ * Admin API for ORM cache metrics and purge
+ * @module plugins/orm-cache-admin/api-handlers
+ */
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db
+ */
+function createOrmCacheAdminHandlers({ db }) {
+  function requireCache(res) {
+    if (!db.cache) {
+      res.status(503).json({ error: 'ORM cache is not enabled on this database' });
+      return null;
+    }
+    return db.cache;
+  }
+
+  async function getStats(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      res.json(cache.getMetrics());
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postPurge(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.purge();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postInvalidate(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      const body = req.body && typeof req.body === 'object' ? req.body : {};
+      if (Array.isArray(body.tags) && body.tags.length > 0) {
+        cache.invalidateTags(body.tags.map(String));
+        return res.json({ ok: true, mode: 'tags' });
+      }
+      if (typeof body.model === 'string' && body.model.trim()) {
+        cache.invalidateModel(body.model.trim());
+        return res.json({ ok: true, mode: 'model' });
+      }
+      res.status(400).json({ error: 'Provide { model: string } or { tags: string[] }' });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postResetMetrics(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.resetMetrics();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  return {
+    getStats,
+    postPurge,
+    postInvalidate,
+    postResetMetrics,
+  };
+}
+
+module.exports = { createOrmCacheAdminHandlers };

package/plugins/orm-cache-admin/index.js

@@ -0,0 +1,72 @@
+/**
+ * ORM Cache Admin — metrics, purge, invalidate (requires admin-panel + db.cache)
+ * @module plugins/orm-cache-admin
+ */
+
+const { createOrmCacheAdminHandlers } = require('./api-handlers');
+const { generateOrmCacheAdminComponent } = require('./admin-component');
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db - From createDatabase({ cache: true })
+ */
+function ormCacheAdminPlugin(options = {}) {
+  const { db } = options;
+
+  if (!db) {
+    throw new Error('orm-cache-admin plugin requires `db` (database instance from createDatabase)');
+  }
+
+  return {
+    name: 'orm-cache-admin',
+    version: '1.0.0',
+    description: 'Admin UI for ORM query cache metrics and purge',
+    dependencies: { 'admin-panel': '*' },
+
+    register() {},
+
+    onRoutesReady(ctx) {
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        console.warn('[orm-cache-admin] admin-panel not found, skipping registration');
+        return;
+      }
+
+      if (!db.cache) {
+        console.warn('[orm-cache-admin] db.cache is disabled; enable createDatabase({ cache: true })');
+        return;
+      }
+
+      const handlers = createOrmCacheAdminHandlers({ db });
+
+      adminApi.registerModule({
+        id: 'orm-cache',
+        pages: [{
+          id: 'orm-cache',
+          title: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          component: generateOrmCacheAdminComponent(),
+        }],
+        menu: [{
+          id: 'orm-cache',
+          label: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          order: 15,
+        }],
+        api: {
+          prefix: '/orm-cache',
+          routes: [
+            { method: 'get', path: '/stats', handler: handlers.getStats },
+            { method: 'post', path: '/purge', handler: handlers.postPurge },
+            { method: 'post', path: '/invalidate', handler: handlers.postInvalidate },
+            { method: 'post', path: '/metrics/reset', handler: handlers.postResetMetrics },
+          ],
+        },
+      });
+    },
+  };
+}
+
+module.exports = ormCacheAdminPlugin;

package/plugins/site-analytics/admin-component.js

@@ -187,6 +187,7 @@ var AnalyticsPage = {
     vnode.state.viewsOverTime = [];
     vnode.state.topPages = [];
     vnode.state.botActivity = [];
+    vnode.state.referrerSources = [];
     vnode.state.countries = [];
     vnode.state.recent = [];
     vnode.state.chartLoaded = false;
@@ -217,6 +218,7 @@ var AnalyticsPage = {
       analyticsApi('views-over-time', days),
       analyticsApi('top-pages', days),
       analyticsApi('bot-activity', days),
+      analyticsApi('referrer-sources', days),
       analyticsApi('countries', days),
       analyticsApi('client-errors', days),
       analyticsApi('recent', days),
@@ -225,9 +227,10 @@ var AnalyticsPage = {
       vnode.state.viewsOverTime = results[1];
       vnode.state.topPages = results[2];
       vnode.state.botActivity = results[3];
-      vnode.state.countries = results[4];
-      vnode.state.clientErrors = results[5];
-      vnode.state.recent = results[6];
+      vnode.state.referrerSources = results[4];
+      vnode.state.countries = results[5];
+      vnode.state.clientErrors = results[6];
+      vnode.state.recent = results[7];
       vnode.state.loading = false;
 
       if (chartInstance) {
@@ -279,11 +282,13 @@ var AnalyticsPage = {
         ? m('div.flex.justify-center.py-24', m(Spinner))
         : [
           // Stat cards
-          m('div.grid.grid-cols-1.sm:grid-cols-2.lg:grid-cols-4.gap-4.mb-6', [
+          m('div.grid.grid-cols-2.sm:grid-cols-3.lg:grid-cols-3.xl:grid-cols-6.gap-4.mb-6', [
             m(StatCard, { icon: '👁', label: 'Views', value: s.stats?.views, bgClass: 'bg-blue-100' }),
             m(StatCard, { icon: '👤', label: 'Visitors', value: s.stats?.visitors, bgClass: 'bg-green-100' }),
             m(StatCard, { icon: '📄', label: 'Unique Pages', value: s.stats?.uniquePages, bgClass: 'bg-yellow-100' }),
             m(StatCard, { icon: '🔗', label: 'Sessions', value: s.stats?.sessions, bgClass: 'bg-purple-100' }),
+            m(StatCard, { icon: '🏠', label: 'Direct traffic', value: s.stats?.directViews, bgClass: 'bg-slate-100' }),
+            m(StatCard, { icon: '🌐', label: 'With referrer', value: s.stats?.referredViews, bgClass: 'bg-cyan-100' }),
           ]),
 
           // Chart + Bot Activity row
@@ -413,6 +418,31 @@ var AnalyticsPage = {
             ]),
           ]),
 
+          // Referrer sources (hostname-level)
+          m('div.bg-white.rounded-lg.shadow.mb-6', [
+            m('div.px-5.py-4.border-b.border-gray-100.flex.items-center.justify-between', [
+              m('h3.text-sm.font-semibold.text-gray-900', 'Referrer sources'),
+              m('span.text-xs.text-gray-400', 'By hostname · last ' + s.days + ' days'),
+            ]),
+            m('div.p-4', [
+              !s.referrerSources || s.referrerSources.length === 0
+                ? m('p.text-gray-400.text-sm.text-center.py-4', 'No external referrer data (direct visits or missing Referer header)')
+                : (function() {
+                  var maxV = s.referrerSources[0]?.views || 1;
+                  return m('div.grid.grid-cols-1.sm:grid-cols-2.gap-x-8.gap-y-2', s.referrerSources.map(function(r) {
+                    return m('div.flex.items-center.gap-3.py-1', [
+                      m('span.text-sm.text-gray-700.flex-1.min-w-0.truncate', { title: r.source }, r.source),
+                      m('div.w-32.shrink-0', m(HBar, {
+                        pct: (r.views / maxV) * 100,
+                        color: 'bg-sky-500',
+                      })),
+                      m('span.text-xs.text-gray-500.w-12.text-right.tabular-nums', formatNumber(r.views)),
+                    ]);
+                  }));
+                })(),
+            ]),
+          ]),
+
           // Country Stats
           m('div.bg-white.rounded-lg.shadow.mb-6', [
             m('div.px-5.py-4.border-b.border-gray-100.flex.items-center.justify-between', [

package/plugins/site-analytics/api-handlers.js

@@ -29,6 +29,24 @@ function createAnalyticsApiHandlers(options) {
     return d.toISOString();
   }
 
+  /**
+   * Extract registrable hostname from Referer URL (strip www.)
+   * @param {string|null|undefined} referrer
+   * @returns {string|null}
+   */
+  function hostnameFromReferrer(referrer) {
+    if (!referrer || typeof referrer !== 'string' || !referrer.trim()) return null;
+    try {
+      const u = new URL(referrer);
+      const h = u.hostname;
+      if (!h) return null;
+      const norm = h.replace(/^www\./i, '').toLowerCase();
+      return norm || null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * GET /stats - Summary statistics
    */
@@ -42,6 +60,18 @@ function createAnalyticsApiHandlers(options) {
         .where('is_bot', false)
         .count('id as count');
 
+      const totalViews = parseInt(views.count) || 0;
+
+      const [directRow] = await knex(tableName)
+        .where('created_at', '>=', since)
+        .where('is_bot', false)
+        .where((qb) => {
+          qb.whereNull('referrer').orWhere('referrer', '');
+        })
+        .count('id as count');
+
+      const directViews = parseInt(directRow.count) || 0;
+
       const [visitors] = await knex(tableName)
         .where('created_at', '>=', since)
         .where('is_bot', false)
@@ -58,7 +88,9 @@ function createAnalyticsApiHandlers(options) {
         .countDistinct('session_id as count');
 
       res.json({
-        views: parseInt(views.count) || 0,
+        views: totalViews,
+        directViews,
+        referredViews: Math.max(0, totalViews - directViews),
         visitors: parseInt(visitors.count) || 0,
         uniquePages: parseInt(uniquePages.count) || 0,
         sessions: parseInt(sessions.count) || 0,
@@ -183,6 +215,46 @@ function createAnalyticsApiHandlers(options) {
     }
   }
 
+  /**
+   * GET /referrer-sources - Top referrer hostnames (aggregated from full Referer URLs)
+   */
+  async function getReferrerSources(req, res) {
+    try {
+      const days = parseDays(req);
+      const since = sinceDate(days);
+      const limit = Math.min(parseInt(req.query.limit) || 20, 50);
+      /** Max distinct full Referer URLs read before hostname merge (long tail capped). */
+      const referrerGroupLimit = 400;
+
+      const rows = await knex(tableName)
+        .select('referrer')
+        .where('created_at', '>=', since)
+        .where('is_bot', false)
+        .whereNotNull('referrer')
+        .where('referrer', '!=', '')
+        .count('id as views')
+        .groupBy('referrer')
+        .orderBy('views', 'desc')
+        .limit(referrerGroupLimit);
+
+      const byHost = new Map();
+      for (const r of rows) {
+        const host = hostnameFromReferrer(r.referrer) || 'Other';
+        const n = parseInt(r.views) || 0;
+        byHost.set(host, (byHost.get(host) || 0) + n);
+      }
+
+      const list = [...byHost.entries()]
+        .map(([source, views]) => ({ source, views }))
+        .sort((a, b) => b.views - a.views)
+        .slice(0, limit);
+
+      res.json(list);
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
   /**
    * GET /countries - Country breakdown
    */
@@ -262,6 +334,7 @@ function createAnalyticsApiHandlers(options) {
     getViewsOverTime,
     getTopPages,
     getBotActivity,
+    getReferrerSources,
     getCountries,
     getClientErrors,
     getRecent,

package/plugins/site-analytics/index.js

@@ -115,6 +115,7 @@ function siteAnalyticsPlugin(options = {}) {
             { method: 'get', path: '/views-over-time', handler: handlers.getViewsOverTime },
             { method: 'get', path: '/top-pages', handler: handlers.getTopPages },
             { method: 'get', path: '/bot-activity', handler: handlers.getBotActivity },
+            { method: 'get', path: '/referrer-sources', handler: handlers.getReferrerSources },
             { method: 'get', path: '/countries', handler: handlers.getCountries },
             { method: 'get', path: '/client-errors', handler: handlers.getClientErrors },
             { method: 'get', path: '/recent', handler: handlers.getRecent },

package/src/file-router.js

@@ -276,9 +276,58 @@ function detectLocale(req) {
 }
 
 /**
- * Resolve middleware from config - supports both functions and named strings
- * @param {Array} middlewareConfig - Array of middleware functions or names
- * @param {Object} middlewareRegistry - Named middleware registry
+ * True when the registry entry is (options) => (req, res, next) => …
+ * Express handlers typically have length >= 2 (req, res) or 3 (req, res, next).
+ */
+function isMiddlewareFactory(fn) {
+  return typeof fn === 'function' && fn.length <= 1;
+}
+
+/**
+ * Resolve a named middleware from createApp({ middlewares }).
+ * @param {string} name
+ * @param {Function} entry
+ * @param {boolean} fromTuple - true when route used ['name', options]
+ * @param {unknown} tupleOptions - second element of the tuple (only when fromTuple)
+ * @param {Object} middlewareRegistry - for error messages
+ * @returns {Function} Express middleware
+ */
+function resolveNamedMiddleware(name, entry, fromTuple, tupleOptions, middlewareRegistry) {
+  if (!entry) {
+    throw new Error(`Middleware "${name}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
+  }
+  if (typeof entry !== 'function') {
+    throw new Error(`Middleware "${name}" must be a function`);
+  }
+
+  if (fromTuple) {
+    if (!isMiddlewareFactory(entry)) {
+      throw new Error(
+        `Middleware "${name}" must be a factory (options) => (req, res, next) => … when using ["${name}", options] tuple form`
+      );
+    }
+    const produced = entry(tupleOptions);
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  if (isMiddlewareFactory(entry)) {
+    const produced = entry({});
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  return entry;
+}
+
+/**
+ * Resolve middleware from config — functions, string names, or [name, options] tuples
+ * @param {Array} middlewareConfig - middleware functions, names, or ['name', options] tuples
+ * @param {Object} middlewareRegistry - Named middleware registry (plain handlers or option factories)
  * @returns {Array} Array of resolved middleware functions
  */
 function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
@@ -292,17 +341,17 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
     }
     
     if (typeof mw === 'string') {
-      const resolved = middlewareRegistry[mw];
-      if (!resolved) {
-        throw new Error(`Middleware "${mw}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
-      }
-      if (typeof resolved !== 'function') {
-        throw new Error(`Middleware "${mw}" must be a function`);
-      }
-      return resolved;
+      return resolveNamedMiddleware(mw, middlewareRegistry[mw], false, undefined, middlewareRegistry);
+    }
+
+    if (Array.isArray(mw) && mw.length === 2 && typeof mw[0] === 'string') {
+      const name = mw[0];
+      return resolveNamedMiddleware(name, middlewareRegistry[name], true, mw[1], middlewareRegistry);
     }
     
-    throw new Error(`Invalid middleware at index ${index}: must be a function or string name`);
+    throw new Error(
+      `Invalid middleware at index ${index}: must be a function, string name, or [name, options] tuple`
+    );
   });
 }
 

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

@@ -164,6 +164,8 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **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`**.
 
 ---
@@ -180,6 +182,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `auditLogPlugin` | Admin mutation audit trail |
 | `recaptchaPlugin` | v2/v3 + middleware |
 | `seoCheckerPlugin` | Dev SEO panel |
+| `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.