webspresso 0.0.72 → 0.0.74

package/src/file-router.js

@@ -140,6 +140,69 @@ function extractMethodFromFilename(filename) {
   return result;
 }
 
+/**
+ * Whether `load()` return values for `stylesheets` and `scripts` are promoted to
+ * `pageHead` in Nunjucks (see `createApp({ pageAssets })`).
+ * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean}|null|undefined} raw
+ * @returns {{ enabled: boolean, stylesheets: boolean, scripts: boolean }}
+ */
+function resolvePageAssets(raw) {
+  if (raw === true) {
+    return { enabled: true, stylesheets: true, scripts: true };
+  }
+  if (raw == null || raw === false) {
+    return { enabled: false, stylesheets: false, scripts: false };
+  }
+  if (typeof raw === 'object') {
+    const on = raw.enabled !== false;
+    if (!on) {
+      return { enabled: false, stylesheets: false, scripts: false };
+    }
+    return {
+      enabled: true,
+      stylesheets: raw.stylesheets !== false,
+      scripts: raw.scripts !== false,
+    };
+  }
+  return { enabled: false, stylesheets: false, scripts: false };
+}
+
+/**
+ * @param {unknown} v
+ * @returns {unknown[]}
+ */
+function toList(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+/**
+ * @param {{ enabled: boolean, stylesheets: boolean, scripts: boolean }} cfg
+ * @param {Object} data
+ * @returns {{ data: Object, pageHead: { stylesheets: unknown[], scripts: unknown[] }|null, pageAssets: boolean }}
+ */
+function applyPageAssetsToTemplateData(cfg, data) {
+  if (!cfg || !cfg.enabled) {
+    return { data, pageHead: null, pageAssets: false };
+  }
+  const out = { ...data };
+  let styles = [];
+  let scriptItems = [];
+  if (cfg.stylesheets && Object.prototype.hasOwnProperty.call(out, 'stylesheets')) {
+    styles = toList(out.stylesheets);
+    delete out.stylesheets;
+  }
+  if (cfg.scripts && Object.prototype.hasOwnProperty.call(out, 'scripts')) {
+    scriptItems = toList(out.scripts);
+    delete out.scripts;
+  }
+  return {
+    data: out,
+    pageHead: { stylesheets: styles, scripts: scriptItems },
+    pageAssets: true,
+  };
+}
+
 /**
  * Recursively scan a directory for files
  * @param {string} dir - Directory to scan
@@ -439,6 +502,7 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @param {boolean} options.silent - Suppress console output
  * @param {Object} options.db - Database instance (exposed as ctx.db in load/meta)
  * @param {{ alpine?: boolean, swup?: boolean }} [options.clientRuntime] - Passed to Nunjucks as `clientRuntime` (default both false)
+ * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean}} [options.pageAssets] - If set, `load()` may return `stylesheets` / `scripts` promoted to `pageHead` in templates
  * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
@@ -450,7 +514,9 @@ function mountPages(app, options) {
     silent = false,
     db = null,
     clientRuntime: clientRuntimeOpt = null,
+    pageAssets: pageAssetsOpt = null,
   } = options;
+  const pageAssetsResolved = resolvePageAssets(pageAssetsOpt);
   const clientRuntime = clientRuntimeOpt && typeof clientRuntimeOpt === 'object'
     ? { alpine: !!clientRuntimeOpt.alpine, swup: !!clientRuntimeOpt.swup }
     : { alpine: false, swup: false };
@@ -686,9 +752,9 @@ function mountPages(app, options) {
         await executeHook(globalHooks, 'beforeRender', ctx);
         await executeHook(routeHooks, 'beforeRender', ctx);
         
-        // Render the template
-        const templatePath = route.file.split(path.sep).join('/');
-        const html = nunjucks.render(templatePath, {
+        const pageAssetBundle = applyPageAssetsToTemplateData(pageAssetsResolved, ctx.data);
+        ctx.data = pageAssetBundle.data;
+        const renderContext = {
           ...ctx.data,
           meta: ctx.meta,
           locale: ctx.locale,
@@ -700,7 +766,15 @@ function mountPages(app, options) {
             query: req.query,
             params: req.params
           }
-        });
+        };
+        if (pageAssetBundle.pageAssets) {
+          renderContext.pageAssets = true;
+          renderContext.pageHead = pageAssetBundle.pageHead;
+        }
+        
+        // Render the template
+        const templatePath = route.file.split(path.sep).join('/');
+        const html = nunjucks.render(templatePath, renderContext);
         
         // Execute hooks: afterRender
         ctx.html = html;
@@ -769,5 +843,7 @@ module.exports = {
   resolveMiddlewares,
   routeRegistrationMeta,
   compareRouteRegistrationOrder,
+  resolvePageAssets,
+  applyPageAssetsToTemplateData,
 };
 

package/src/server.js

@@ -261,6 +261,7 @@ function haltOnTimedout(req, res, next) {
  * @param {Object} options.auth - Authentication manager instance (from createAuth)
  * @param {Object} options.db - Database instance (exposed as ctx.db to plugins)
  * @param {Object} [options.clientRuntime] - Optional client assets: `{ alpine?: boolean|object, swup?: boolean|object }`. Overridable by env `WEBSPRESSO_ALPINE` / `WEBSPRESSO_SWUP` (=1 or true). Serves `/__webspresso/client-runtime/*` when either flag is on.
+ * @param {boolean|{enabled?: boolean, stylesheets?: boolean, scripts?: boolean}} [options.pageAssets] - If truthy, route `load()` return values for `stylesheets` and `scripts` are reserved: removed from the root template context and passed as `pageHead` to Nunjucks, with `pageAssets: true` (for layout to emit `<link>` / `<script>`). Default off.
  * @param {function(import('express').Express, Object): void} [options.setupRoutes] - Called after file routes and plugins, before 404 handler
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
@@ -448,6 +449,7 @@ function createApp(options = {}) {
     silent: isTest,
     db: options.db ?? null,
     clientRuntime,
+    pageAssets: options.pageAssets,
   });
 
   // Set route metadata in plugin manager

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

@@ -68,6 +68,7 @@ project/
 | `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)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. **`ctx.clientRuntime`** is the resolved flags. **`ctx.authMiddleware`** is set when `auth` was passed (guards: `requireAuth`, `requireGuest`, `requireCan`, `requireVerified`, …). Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
@@ -91,8 +92,10 @@ project/
 - **Route config:** `middleware: ['auth']` (must be logged in) or `['guest']` (logged-out only). For JSON APIs mounted in **`setupRoutes`**, use **`ctx.authMiddleware.requireAuth({ api: true })`** for 401 JSON instead of redirect.
 - **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** (routes like **`/_admin/users`**, **`/_admin/users/new`**, **`/_admin/users/:id/edit`** — same Mithril shell as the rest of the panel). The **`model`** must be the ORM model your site auth uses (e.g. **`quickAuth({ userModel: 'User', ... })`** / **`createAuth`** adapters reading the same table). Pass **`auth: authManager`** with the **same** **`AuthManager`** instance as **`createApp({ auth: authManager })`** when you want **Active Sessions** / revoke APIs (**`rememberTokens`** / **`remember_me`**); without **`auth`**, list/create/update/delete users still work 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)** · README **Authentication (session)**.
+Longer narrative: **[`doc/index.html#authentication`](../../../doc/index.html#authentication)** · **[`#admin-user-management`](../../../doc/index.html#admin-user-management)** · README **Authentication (session)** and **Admin Panel Plugin**.
 
 ---
 
@@ -200,7 +203,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `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`; optional `uploadUrl` or infer from `uploadPlugin` order |
+| `adminPanelPlugin` | SPA admin CRUD — needs **`db`**; 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 |
 | `uploadPlugin` | `POST` multipart (`multer`), `createLocalFileProvider` or custom `provider`; set **`mimeAllowlist`** / **`maxBytes`** in production |
 | `siteAnalyticsPlugin` | Self-hosted page views + admin charts |
 | `auditLogPlugin` | Admin mutation audit trail |