webspresso 0.0.66 → 0.0.68

package/plugins/upload/index.js

@@ -0,0 +1,188 @@
+/**
+ * File upload plugin — multipart parsing, validation, pluggable storage.
+ * @module plugins/upload
+ */
+
+const multer = require('multer');
+const path = require('path');
+const { createLocalFileProvider } = require('./local-file-provider');
+
+/**
+ * @typedef {import('express').Request} ExpressRequest
+ */
+
+/**
+ * @typedef {Object} UploadPutArgs
+ * @property {Buffer} [buffer]
+ * @property {import('stream').Readable} [stream]
+ * @property {string} originalName
+ * @property {string} mimeType
+ * @property {number} size
+ * @property {ExpressRequest} req
+ */
+
+/**
+ * @typedef {Object} UploadPutResult
+ * @property {string} publicUrl
+ * @property {string} [key]
+ */
+
+/**
+ * @typedef {Object} UploadStorageProvider
+ * @property {(args: UploadPutArgs) => Promise<UploadPutResult>} put
+ */
+
+/**
+ * @param {string} [p]
+ * @returns {string}
+ */
+function normalizeRoutePath(p) {
+  const s = (p || '/api/upload').trim();
+  return s.startsWith('/') ? s : `/${s}`;
+}
+
+/**
+ * @param {string} [name]
+ * @returns {string} lowercase extension without dot
+ */
+function extensionFromName(name) {
+  return path.extname(path.basename(name || '')).replace(/^\./, '').toLowerCase();
+}
+
+/**
+ * @param {number} maxBytes
+ * @param {string} fieldName
+ * @returns {import('express').RequestHandler}
+ */
+function createMulterSingleMiddleware(maxBytes, fieldName) {
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: maxBytes, files: 1 },
+  });
+  return upload.single(fieldName);
+}
+
+/**
+ * @param {unknown} err
+ * @returns {{ status: number, message: string }}
+ */
+function multerErrorResponse(err) {
+  if (err instanceof multer.MulterError) {
+    if (err.code === 'LIMIT_FILE_SIZE') {
+      return { status: 413, message: 'File too large' };
+    }
+    if (err.code === 'LIMIT_FILE_COUNT' || err.code === 'LIMIT_UNEXPECTED_FILE') {
+      return { status: 400, message: 'Invalid upload (too many files or unexpected field)' };
+    }
+    return { status: 400, message: err.message || 'Upload error' };
+  }
+  return { status: 400, message: err instanceof Error ? err.message : String(err) };
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.path='/api/upload'] — POST route
+ * @param {UploadStorageProvider} [options.provider] — Storage backend; default: local disk
+ * @param {Object} [options.local] — Shorthand for createLocalFileProvider when provider omitted
+ * @param {string} [options.local.destDir]
+ * @param {string} [options.local.publicBasePath]
+ * @param {number} [options.maxBytes=10485760] — 10 MiB default
+ * @param {string[]|null} [options.mimeAllowlist] — If set, reject other MIME types (415)
+ * @param {string[]|null} [options.extensionAllowlist] — Optional extra guard on original extension
+ * @param {import('express').RequestHandler|import('express').RequestHandler[]} [options.middleware]
+ * @param {string} [options.fieldName='file'] — Multipart field name
+ * @returns {Object} Webspresso plugin
+ */
+function uploadPlugin(options = {}) {
+  const {
+    path: routePath = '/api/upload',
+    provider: userProvider,
+    local,
+    maxBytes = 10 * 1024 * 1024,
+    mimeAllowlist = null,
+    extensionAllowlist = null,
+    middleware = [],
+    fieldName = 'file',
+  } = options;
+
+  const normalizedPath = normalizeRoutePath(routePath);
+
+  const provider =
+    userProvider ||
+    createLocalFileProvider({
+      destDir: local?.destDir,
+      publicBasePath: local?.publicBasePath,
+    });
+
+  const mw = (Array.isArray(middleware) ? middleware : [middleware]).filter(Boolean);
+  const parseMultipart = createMulterSingleMiddleware(maxBytes, fieldName);
+
+  return {
+    name: 'upload',
+    version: '1.0.0',
+    description: 'Multipart file uploads with pluggable storage',
+
+    onRoutesReady(ctx) {
+      const { app } = ctx;
+      app.set('webspresso.uploadPath', normalizedPath);
+
+      const handler = (req, res) => {
+        parseMultipart(req, res, async (err) => {
+          if (err) {
+            const { status, message } = multerErrorResponse(err);
+            return res.status(status).json({ error: message, message });
+          }
+
+          const file = req.file;
+          if (!file || !file.buffer) {
+            return res.status(400).json({ error: 'No file uploaded', message: 'No file uploaded' });
+          }
+
+          const mime = file.mimetype || 'application/octet-stream';
+          const originalName = file.originalname || 'upload';
+          const ext = extensionFromName(originalName);
+
+          if (mimeAllowlist && mimeAllowlist.length && !mimeAllowlist.includes(mime)) {
+            return res.status(415).json({ error: 'MIME type not allowed', message: 'MIME type not allowed' });
+          }
+          if (
+            extensionAllowlist &&
+            extensionAllowlist.length &&
+            (!ext || !extensionAllowlist.includes(ext))
+          ) {
+            return res.status(400).json({ error: 'File extension not allowed', message: 'File extension not allowed' });
+          }
+
+          try {
+            const result = await provider.put({
+              buffer: file.buffer,
+              originalName,
+              mimeType: mime,
+              size: file.size,
+              req,
+            });
+            res.json({
+              url: result.publicUrl,
+              publicUrl: result.publicUrl,
+              key: result.key,
+            });
+          } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            res.status(500).json({ error: message, message });
+          }
+        });
+      };
+
+      ctx.addRoute('post', normalizedPath, ...mw, handler);
+
+      if (process.env.NODE_ENV !== 'production') {
+        console.log(`  Upload plugin: POST ${normalizedPath}`);
+      }
+    },
+  };
+}
+
+module.exports = {
+  uploadPlugin,
+  createLocalFileProvider,
+};

package/plugins/upload/local-file-provider.js

@@ -0,0 +1,122 @@
+/**
+ * Default upload storage: write files to local disk and expose a public URL path.
+ * @module plugins/upload/local-file-provider
+ */
+
+const fs = require('fs/promises');
+const path = require('path');
+const { randomBytes } = require('crypto');
+
+/**
+ * Common MIME → canonical extension (lowercase, with leading dot).
+ * Used so stored filenames match the MIME the server accepted (see uploadPlugin mimeAllowlist).
+ * Does not verify file content; spoofed MIME is a separate concern (allowlist + optional magic-byte later).
+ */
+const MIME_TO_EXT = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/gif': '.gif',
+  'image/webp': '.webp',
+  'image/svg+xml': '.svg',
+  'image/avif': '.avif',
+  'application/pdf': '.pdf',
+  'text/plain': '.txt',
+  'text/csv': '.csv',
+  'text/html': '.html',
+  'application/json': '.json',
+  'application/zip': '.zip',
+  'application/gzip': '.gz',
+  'video/mp4': '.mp4',
+  'video/webm': '.webm',
+  'audio/mpeg': '.mp3',
+  'audio/webm': '.weba',
+};
+
+/**
+ * Normalize public URL prefix (no trailing slash).
+ * @param {string} [publicBasePath]
+ * @returns {string}
+ */
+function normalizePublicBase(publicBasePath) {
+  let p = (publicBasePath == null || publicBasePath === '' ? '/uploads' : String(publicBasePath)).trim();
+  p = p.replace(/\/+$/, '');
+  if (!p.startsWith('/')) {
+    p = `/${p}`;
+  }
+  return p || '/uploads';
+}
+
+/**
+ * @param {string} [mimeType]
+ * @returns {string|null} extension with leading dot, or null if unknown
+ */
+function canonicalExtFromMime(mimeType) {
+  if (!mimeType || typeof mimeType !== 'string') return null;
+  const base = mimeType.split(';')[0].trim().toLowerCase();
+  return MIME_TO_EXT[base] || null;
+}
+
+/**
+ * Prefer a safe extension from the filename; align with MIME when we have a mapping.
+ * @param {string} [mimeType]
+ * @param {string} extFromName - already normalized (lowercase, with dot or '')
+ * @returns {string} extension with leading dot or empty string
+ */
+function resolveStoredExtension(mimeType, extFromName) {
+  const fromMime = canonicalExtFromMime(mimeType);
+  if (fromMime) {
+    if (!extFromName || extFromName !== fromMime) {
+      return fromMime;
+    }
+    return extFromName;
+  }
+  return extFromName || '';
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.destDir] — Absolute or cwd-relative directory for stored files
+ * @param {string} [options.publicBasePath='/uploads'] — URL prefix (first segment of public URL)
+ * @returns {import('./index').UploadStorageProvider}
+ */
+function createLocalFileProvider(options = {}) {
+  const destDir = path.resolve(
+    options.destDir || path.join(process.cwd(), 'public', 'uploads')
+  );
+  const publicBase = normalizePublicBase(options.publicBasePath);
+
+  return {
+    async put({ buffer, originalName, mimeType, size, req }) {
+      void size;
+      void req;
+      await fs.mkdir(destDir, { recursive: true });
+
+      const base = path.basename(originalName || 'upload');
+      let ext = path.extname(base).toLowerCase();
+      if (!/^\.[a-z0-9]{1,12}$/.test(ext)) {
+        ext = '';
+      }
+
+      ext = resolveStoredExtension(mimeType, ext);
+
+      const storedName = `${Date.now()}-${randomBytes(8).toString('hex')}${ext}`;
+      const target = path.join(destDir, storedName);
+      const resolvedDest = path.resolve(destDir);
+      if (!target.startsWith(resolvedDest + path.sep) && target !== resolvedDest) {
+        throw new Error('Invalid storage path');
+      }
+
+      await fs.writeFile(target, buffer);
+
+      const publicUrl = `${publicBase}/${storedName}`.replace(/\/{2,}/g, '/');
+      return { publicUrl, key: storedName };
+    },
+  };
+}
+
+module.exports = {
+  createLocalFileProvider,
+  normalizePublicBase,
+  canonicalExtFromMime,
+  resolveStoredExtension,
+};

package/src/client-runtime/bootstrap-alpine-swup.js

@@ -0,0 +1,34 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin, Alpine */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined' || typeof Alpine === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+
+  swup.hooks.on('content:replace', function () {
+    var root = document.querySelector('#swup');
+    if (root && typeof Alpine.initTree === 'function') {
+      Alpine.initTree(root);
+    }
+  });
+
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/bootstrap-swup.js

@@ -0,0 +1,26 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/mount.js

@@ -0,0 +1,65 @@
+/**
+ * Mount Express routes that serve vendored Alpine / Swup UMD builds from node_modules
+ * and framework bootstrap scripts from src/client-runtime/.
+ */
+
+const path = require('path');
+const express = require('express');
+
+const CLIENT_RUNTIME_BASE = '/__webspresso/client-runtime';
+
+/** Resolve a file next to the package's resolved main entry (works with package "exports"). */
+function pkgFileFromMain(pkg, ...segments) {
+  const entry = require.resolve(pkg);
+  return path.join(path.dirname(entry), ...segments);
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {{ alpine: boolean, swup: boolean }} flags
+ */
+function mountClientRuntime(app, flags) {
+  if (!flags || (!flags.alpine && !flags.swup)) return;
+
+  const router = express.Router();
+
+  function send(res, filePath) {
+    res.type('application/javascript');
+    res.sendFile(filePath);
+  }
+
+  if (flags.alpine) {
+    router.get('/alpine.min.js', (req, res) => {
+      send(res, pkgFileFromMain('alpinejs', 'cdn.min.js'));
+    });
+  }
+
+  if (flags.swup) {
+    router.get('/swup.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('swup', 'Swup.umd.js'));
+    });
+    router.get('/swup-head-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/head-plugin', 'index.umd.js'));
+    });
+    router.get('/swup-scripts-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/scripts-plugin', 'index.umd.js'));
+    });
+    const runtimeDir = __dirname;
+    if (flags.alpine) {
+      router.get('/bootstrap-alpine-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-alpine-swup.js'));
+      });
+    } else {
+      router.get('/bootstrap-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-swup.js'));
+      });
+    }
+  }
+
+  app.use(CLIENT_RUNTIME_BASE, router);
+}
+
+module.exports = {
+  mountClientRuntime,
+  CLIENT_RUNTIME_BASE,
+};

package/src/client-runtime/resolve.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve clientRuntime flags from createApp({ clientRuntime }) and optional env overrides.
+ * Env: WEBSPRESSO_ALPINE=1|true, WEBSPRESSO_SWUP=1|true (override explicit false from options when set).
+ */
+
+function envTruthy(name) {
+  const v = process.env[name];
+  if (v == null || v === '') return undefined;
+  return v === '1' || /^true$/i.test(String(v));
+}
+
+function optionEnabled(v) {
+  if (v === true) return true;
+  if (v && typeof v === 'object') return true;
+  return false;
+}
+
+/**
+ * @param {object} [options]
+ * @param {object} [options.clientRuntime]
+ * @param {boolean|object} [options.clientRuntime.alpine]
+ * @param {boolean|object} [options.clientRuntime.swup]
+ * @returns {{ alpine: boolean, swup: boolean }}
+ */
+function resolveClientRuntime(options = {}) {
+  const cr = options.clientRuntime;
+  let alpine = false;
+  let swup = false;
+  if (cr && typeof cr === 'object') {
+    alpine = optionEnabled(cr.alpine);
+    swup = optionEnabled(cr.swup);
+  }
+  const envA = envTruthy('WEBSPRESSO_ALPINE');
+  const envS = envTruthy('WEBSPRESSO_SWUP');
+  if (envA !== undefined) alpine = envA;
+  if (envS !== undefined) swup = envS;
+  return { alpine, swup };
+}
+
+module.exports = { resolveClientRuntime };

package/src/file-router.js

@@ -365,10 +365,22 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @param {Object} options.pluginManager - Plugin manager instance
  * @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)
  * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false, db = null } = options;
+  const {
+    pagesDir,
+    nunjucks,
+    middlewares = {},
+    pluginManager = null,
+    silent = false,
+    db = null,
+    clientRuntime: clientRuntimeOpt = null,
+  } = options;
+  const clientRuntime = clientRuntimeOpt && typeof clientRuntimeOpt === 'object'
+    ? { alpine: !!clientRuntimeOpt.alpine, swup: !!clientRuntimeOpt.swup }
+    : { alpine: false, swup: false };
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -548,7 +560,8 @@ function mountPages(app, options) {
             indexable: true,
             canonical: null
           },
-          fsy: { ...baseHelpers, ...pluginHelpers }
+          fsy: { ...baseHelpers, ...pluginHelpers },
+          clientRuntime,
         };
         
         // Execute hooks: onRequest
@@ -612,6 +625,7 @@ function mountPages(app, options) {
           locale: ctx.locale,
           t: ctx.t,
           fsy: ctx.fsy,
+          clientRuntime: ctx.clientRuntime,
           req: {
             path: req.path,
             query: req.query,

package/src/server.js

@@ -9,6 +9,8 @@ const nunjucks = require('nunjucks');
 const timeout = require('connect-timeout');
 
 const { setAppContext } = require('./app-context');
+const { mountClientRuntime } = require('./client-runtime/mount');
+const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
@@ -258,6 +260,7 @@ function haltOnTimedout(req, res, next) {
  * @param {string|boolean} options.timeout - Request timeout (default: '30s', false to disable)
  * @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 {function(import('express').Express, Object): void} [options.setupRoutes] - Called after file routes and plugins, before 404 handler
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
@@ -294,6 +297,8 @@ function createApp(options = {}) {
     throw new Error('pagesDir is required');
   }
 
+  const clientRuntime = resolveClientRuntime(options);
+
   setAppContext({ db: options.db ?? null });
   
   const app = express();
@@ -378,7 +383,9 @@ function createApp(options = {}) {
       etag: true
     }));
   }
-  
+
+  mountClientRuntime(app, clientRuntime);
+
   // Configure Nunjucks
   const templateDirs = viewsDir ? [pagesDir, viewsDir] : [pagesDir];
   
@@ -439,7 +446,8 @@ function createApp(options = {}) {
     middlewares,
     pluginManager,
     silent: isTest,
-    db: options.db ?? null
+    db: options.db ?? null,
+    clientRuntime,
   });
   
   // Set route metadata in plugin manager
@@ -480,6 +488,7 @@ function createApp(options = {}) {
       authMiddleware,
       pluginManager,
       options,
+      clientRuntime,
     });
   }