webspresso 0.0.1 → 0.0.3

package/README.md

@@ -180,6 +180,138 @@ Creates and configures the Express app.
 - `viewsDir` (optional): Path to views/layouts directory
 - `publicDir` (optional): Path to public/static directory
 - `logging` (optional): Enable request logging (default: true in development)
+- `helmet` (optional): Helmet security configuration
+  - `true` or `undefined`: Use default secure configuration
+  - `false`: Disable Helmet
+  - `Object`: Custom Helmet configuration (merged with defaults)
+- `middlewares` (optional): Named middleware registry for routes
+
+**Example with middlewares:**
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  middlewares: {
+    auth: (req, res, next) => {
+      if (!req.session?.user) {
+        return res.redirect('/login');
+      }
+      next();
+    },
+    admin: (req, res, next) => {
+      if (req.session?.user?.role !== 'admin') {
+        return res.status(403).send('Forbidden');
+      }
+      next();
+    },
+    rateLimit: require('express-rate-limit')({ windowMs: 60000, max: 100 })
+  }
+});
+```
+
+Then use in route configs by name:
+
+```javascript
+// pages/admin/index.js
+module.exports = {
+  middleware: ['auth', 'admin'], // Use named middlewares
+  load(req, ctx) { ... }
+};
+
+// pages/api/data.get.js
+module.exports = {
+  middleware: ['auth', 'rateLimit'],
+  handler: (req, res) => res.json({ data: 'protected' })
+};
+```
+
+**Custom Error Pages:**
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  errorPages: {
+    // Option 1: Custom handler function
+    notFound: (req, res) => {
+      res.render('errors/404.njk', { url: req.url });
+    },
+    
+    // Option 2: Template path (rendered with Nunjucks)
+    serverError: 'errors/500.njk'
+  }
+});
+```
+
+Error templates receive these variables:
+- `404.njk`: `{ url, method }`
+- `500.njk`: `{ error, status, isDev }`
+
+**Asset Management:**
+
+Configure asset handling with versioning and manifest support:
+
+```javascript
+const { createApp } = require('webspresso');
+const path = require('path');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  publicDir: './public',
+  assets: {
+    // Option 1: Simple versioning (cache busting)
+    version: '1.2.3',  // or process.env.APP_VERSION
+    
+    // Option 2: Manifest file (Vite, Webpack, etc.)
+    manifestPath: path.join(__dirname, 'public/.vite/manifest.json'),
+    
+    // URL prefix for assets
+    prefix: '/static'
+  }
+});
+```
+
+Use asset helpers in templates:
+
+```njk
+{# Using fsy helpers (auto-resolved) #}
+<link rel="stylesheet" href="{{ fsy.asset('/css/style.css') }}">
+
+{# Or generate full HTML tags #}
+{{ fsy.css('/css/style.css') | safe }}
+{{ fsy.js('/js/app.js', { defer: true, type: 'module' }) | safe }}
+{{ fsy.img('/images/logo.png', 'Site Logo', { class: 'logo', loading: 'lazy' }) | safe }}
+```
+
+Asset helpers available in `fsy`:
+- `asset(path)` - Returns versioned/manifest-resolved URL
+- `css(href, attrs)` - Generates `<link>` tag
+- `js(src, attrs)` - Generates `<script>` tag
+- `img(src, alt, attrs)` - Generates `<img>` tag
+
+**Manifest Support:**
+
+Works with Vite and Webpack manifest formats:
+
+```json
+// Vite manifest format (.vite/manifest.json)
+{
+  "css/style.css": { "file": "assets/style-abc123.css" },
+  "js/app.js": { "file": "assets/app-xyz789.js" }
+}
+
+// Webpack manifest format
+{
+  "/css/style.css": "/dist/style.abc123.css",
+  "/js/app.js": "/dist/app.xyz789.js"
+}
+```
 
 **Returns:** `{ app, nunjucksEnv }`
 

package/index.js

@@ -12,7 +12,13 @@ const {
   createTranslator,
   detectLocale
 } = require('./src/file-router');
-const { createHelpers, utils } = require('./src/helpers');
+const { 
+  createHelpers, 
+  utils, 
+  AssetManager, 
+  configureAssets, 
+  getAssetManager 
+} = require('./src/helpers');
 
 module.exports = {
   // Main API
@@ -29,6 +35,11 @@ module.exports = {
   
   // Template helpers
   createHelpers,
-  utils
+  utils,
+  
+  // Asset management
+  AssetManager,
+  configureAssets,
+  getAssetManager
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {
@@ -34,6 +34,7 @@
   "dependencies": {
     "commander": "^11.1.0",
     "express": "^4.18.2",
+    "helmet": "^7.2.0",
     "inquirer": "^8.2.6",
     "nunjucks": "^3.2.4"
   },

package/src/file-router.js

@@ -272,16 +272,48 @@ function detectLocale(req) {
   return process.env.DEFAULT_LOCALE || 'en';
 }
 
+/**
+ * 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
+ * @returns {Array} Array of resolved middleware functions
+ */
+function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
+  if (!middlewareConfig || !Array.isArray(middlewareConfig)) {
+    return [];
+  }
+  
+  return middlewareConfig.map((mw, index) => {
+    if (typeof mw === 'function') {
+      return mw;
+    }
+    
+    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;
+    }
+    
+    throw new Error(`Invalid middleware at index ${index}: must be a function or string name`);
+  });
+}
+
 /**
  * Mount all pages as routes on the Express app
  * @param {Object} app - Express app
  * @param {Object} options - Options
  * @param {string} options.pagesDir - Pages directory path
  * @param {Object} options.nunjucks - Nunjucks environment
+ * @param {Object} options.middlewares - Named middleware registry
  * @param {boolean} options.silent - Suppress console output
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, silent = false } = options;
+  const { pagesDir, nunjucks, middlewares = {}, silent = false } = options;
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -353,6 +385,7 @@ function mountPages(app, options) {
   for (const route of sortRoutes(apiRoutes)) {
     const handler = require(route.fullPath);
     const handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
+    const routeMiddleware = handler.middleware;
     
     if (typeof handlerFn !== 'function') {
       console.warn(`API route ${route.file} does not export a function`);
@@ -372,6 +405,20 @@ function mountPages(app, options) {
           ? currentHandler 
           : currentHandler.default || currentHandler.handler;
         
+        // Run middleware if defined
+        const mwConfig = isDev ? currentHandler.middleware : routeMiddleware;
+        if (mwConfig) {
+          const resolvedMw = resolveMiddlewares(mwConfig, middlewares);
+          for (const mw of resolvedMw) {
+            await new Promise((resolve, reject) => {
+              mw(req, res, (err) => {
+                if (err) reject(err);
+                else resolve();
+              });
+            });
+          }
+        }
+        
         await fn(req, res, next);
       } catch (err) {
         console.error(`API error ${route.routePath}:`, err);
@@ -429,8 +476,9 @@ function mountPages(app, options) {
         await executeHook(routeHooks, 'beforeMiddleware', ctx);
         
         // Run route middleware
-        if (config?.middleware && Array.isArray(config.middleware)) {
-          for (const mw of config.middleware) {
+        if (config?.middleware) {
+          const resolvedMiddlewares = resolveMiddlewares(config.middleware, middlewares);
+          for (const mw of resolvedMiddlewares) {
             await new Promise((resolve, reject) => {
               mw(req, res, (err) => {
                 if (err) reject(err);
@@ -515,6 +563,7 @@ module.exports = {
   scanDirectory,
   loadI18n,
   createTranslator,
-  detectLocale
+  detectLocale,
+  resolveMiddlewares
 };
 

package/src/helpers.js

@@ -4,6 +4,167 @@
  */
 
 const querystring = require('querystring');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Asset Manager - handles asset paths, versioning, and manifest
+ */
+class AssetManager {
+  constructor(options = {}) {
+    this.publicDir = options.publicDir || 'public';
+    this.manifestPath = options.manifestPath || null;
+    this.manifest = null;
+    this.version = options.version || null;
+    this.prefix = options.prefix || '';
+    
+    // Load manifest if path provided
+    if (this.manifestPath) {
+      this.loadManifest();
+    }
+  }
+  
+  /**
+   * Load asset manifest file (Vite, Webpack, etc.)
+   */
+  loadManifest() {
+    try {
+      const fullPath = path.resolve(this.manifestPath);
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        this.manifest = JSON.parse(content);
+      }
+    } catch (err) {
+      console.warn('Failed to load asset manifest:', err.message);
+      this.manifest = null;
+    }
+  }
+  
+  /**
+   * Resolve asset path from manifest or add version
+   * @param {string} assetPath - Asset path
+   * @returns {string}
+   */
+  resolve(assetPath) {
+    // Remove leading slash for manifest lookup
+    const lookupPath = assetPath.replace(/^\//, '');
+    
+    // Check manifest first
+    if (this.manifest) {
+      // Vite manifest format
+      if (this.manifest[lookupPath]) {
+        const entry = this.manifest[lookupPath];
+        const resolved = typeof entry === 'string' ? entry : entry.file;
+        return this.prefix + '/' + resolved;
+      }
+      
+      // Webpack manifest format (direct mapping)
+      if (this.manifest[assetPath]) {
+        return this.prefix + this.manifest[assetPath];
+      }
+    }
+    
+    // Add version query string if provided
+    let finalPath = assetPath.startsWith('/') ? assetPath : '/' + assetPath;
+    finalPath = this.prefix + finalPath;
+    
+    if (this.version) {
+      const separator = finalPath.includes('?') ? '&' : '?';
+      finalPath += `${separator}v=${this.version}`;
+    }
+    
+    return finalPath;
+  }
+  
+  /**
+   * Get asset URL
+   */
+  asset(assetPath) {
+    return this.resolve(assetPath);
+  }
+  
+  /**
+   * Generate CSS link tag
+   */
+  css(href, attributes = {}) {
+    const resolvedHref = this.resolve(href);
+    const attrs = this.buildAttributes({
+      rel: 'stylesheet',
+      href: resolvedHref,
+      ...attributes
+    });
+    return `<link ${attrs}>`;
+  }
+  
+  /**
+   * Generate JS script tag
+   */
+  js(src, attributes = {}) {
+    const resolvedSrc = this.resolve(src);
+    const attrs = this.buildAttributes({
+      src: resolvedSrc,
+      ...attributes
+    });
+    return `<script ${attrs}></script>`;
+  }
+  
+  /**
+   * Generate image tag
+   */
+  img(src, alt = '', attributes = {}) {
+    const resolvedSrc = this.resolve(src);
+    const attrs = this.buildAttributes({
+      src: resolvedSrc,
+      alt,
+      ...attributes
+    });
+    return `<img ${attrs}>`;
+  }
+  
+  /**
+   * Build HTML attributes string
+   */
+  buildAttributes(attrs) {
+    return Object.entries(attrs)
+      .filter(([_, v]) => v !== undefined && v !== null && v !== false)
+      .map(([k, v]) => v === true ? k : `${k}="${this.escapeHtml(String(v))}"`)
+      .join(' ');
+  }
+  
+  /**
+   * Escape HTML special characters
+   */
+  escapeHtml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+}
+
+// Global asset manager instance
+let globalAssetManager = null;
+
+/**
+ * Configure global asset manager
+ * @param {Object} options - Asset manager options
+ */
+function configureAssets(options = {}) {
+  globalAssetManager = new AssetManager(options);
+  return globalAssetManager;
+}
+
+/**
+ * Get or create asset manager
+ */
+function getAssetManager() {
+  if (!globalAssetManager) {
+    globalAssetManager = new AssetManager();
+  }
+  return globalAssetManager;
+}
 
 /**
  * Create the fsy helper object bound to the current request context
@@ -217,6 +378,47 @@ function createHelpers(ctx) {
         return regex.test(currentPath);
       }
       return false;
+    },
+
+    // Asset helpers
+    /**
+     * Get asset URL with versioning/manifest support
+     * @param {string} assetPath - Asset path
+     * @returns {string}
+     */
+    asset(assetPath) {
+      return getAssetManager().asset(assetPath);
+    },
+
+    /**
+     * Generate CSS link tag
+     * @param {string} href - CSS file path
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    css(href, attrs = {}) {
+      return getAssetManager().css(href, attrs);
+    },
+
+    /**
+     * Generate JS script tag
+     * @param {string} src - JS file path
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    js(src, attrs = {}) {
+      return getAssetManager().js(src, attrs);
+    },
+
+    /**
+     * Generate image tag
+     * @param {string} src - Image file path
+     * @param {string} alt - Alt text
+     * @param {Object} attrs - Additional attributes
+     * @returns {string}
+     */
+    img(src, alt = '', attrs = {}) {
+      return getAssetManager().img(src, alt, attrs);
     }
   };
 }
@@ -270,6 +472,9 @@ const utils = {
 
 module.exports = {
   createHelpers,
-  utils
+  utils,
+  AssetManager,
+  configureAssets,
+  getAssetManager
 };
 

package/src/server.js

@@ -4,9 +4,109 @@
  */
 
 const express = require('express');
+const helmet = require('helmet');
 const nunjucks = require('nunjucks');
-const path = require('path');
+
 const { mountPages } = require('./file-router');
+const { configureAssets } = require('./helpers');
+
+/**
+ * Get default Helmet configuration
+ * @param {boolean} isDev - Whether in development mode
+ * @returns {Object} Helmet configuration
+ */
+function getDefaultHelmetConfig(isDev) {
+  return {
+    // Disable CSP in development for easier development (Nunjucks hot reload, etc.)
+    contentSecurityPolicy: isDev ? false : {
+      directives: {
+        defaultSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"], // Allow inline styles for Tailwind
+        scriptSrc: ["'self'"],
+        imgSrc: ["'self'", "data:", "https:"],
+        fontSrc: ["'self'", "data:"],
+        connectSrc: ["'self'"],
+        frameSrc: ["'none'"],
+        objectSrc: ["'none'"],
+        upgradeInsecureRequests: []
+      }
+    },
+    // Other security headers
+    crossOriginEmbedderPolicy: false, // Disable for better compatibility
+    crossOriginOpenerPolicy: { policy: 'same-origin' },
+    crossOriginResourcePolicy: { policy: 'cross-origin' },
+    dnsPrefetchControl: true,
+    frameguard: { action: 'deny' },
+    hidePoweredBy: true,
+    hsts: {
+      maxAge: 31536000,
+      includeSubDomains: true,
+      preload: true
+    },
+    ieNoOpen: true,
+    noSniff: true,
+    originAgentCluster: true,
+    permittedCrossDomainPolicies: false,
+    referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+    xssFilter: true
+  };
+}
+
+/**
+ * Default 404 page HTML
+ */
+function default404Html() {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>404 - Not Found</title>
+  <style>
+    body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
+    .container { text-align: center; }
+    h1 { font-size: 4rem; margin: 0; color: #333; }
+    p { color: #666; margin: 1rem 0; }
+    a { color: #0066cc; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>404</h1>
+    <p>Page not found</p>
+    <a href="/">← Back to Home</a>
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Default 500 page HTML
+ */
+function default500Html(err, isDev) {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>500 - Server Error</title>
+  <style>
+    body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
+    .container { text-align: center; }
+    h1 { font-size: 4rem; margin: 0; color: #333; }
+    p { color: #666; margin: 1rem 0; }
+    pre { background: #fff; padding: 1rem; border-radius: 4px; text-align: left; overflow: auto; max-width: 600px; }
+    a { color: #0066cc; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>500</h1>
+    <p>Internal Server Error</p>
+    ${isDev && err ? `<pre>${err.stack || err.message}</pre>` : ''}
+    <a href="/">← Back to Home</a>
+  </div>
+</body>
+</html>`;
+}
 
 /**
  * Create and configure the Express app
@@ -15,6 +115,15 @@ const { mountPages } = require('./file-router');
  * @param {string} options.viewsDir - Path to views directory  
  * @param {string} options.publicDir - Path to public/static directory
  * @param {boolean} options.logging - Enable request logging (default: isDev)
+ * @param {Object|boolean} options.helmet - Helmet configuration (default: auto-configured, false to disable)
+ * @param {Object} options.middlewares - Named middleware registry for route configs
+ * @param {Object} options.assets - Asset manager configuration
+ * @param {string} options.assets.manifestPath - Path to asset manifest file (Vite, Webpack)
+ * @param {string} options.assets.version - Asset version for cache busting
+ * @param {string} options.assets.prefix - URL prefix for assets
+ * @param {Object} options.errorPages - Custom error page handlers
+ * @param {Function|string} options.errorPages.notFound - Custom 404 handler or template path
+ * @param {Function|string} options.errorPages.serverError - Custom 500 handler or template path
  * @returns {Object} { app, nunjucksEnv }
  */
 function createApp(options = {}) {
@@ -26,15 +135,35 @@ function createApp(options = {}) {
     pagesDir,
     viewsDir,
     publicDir,
-    logging = isDev && !isTest
+    logging = isDev && !isTest,
+    helmet: helmetConfig,
+    middlewares = {},
+    assets: assetsConfig = {},
+    errorPages = {}
   } = options;
   
+  // Configure asset manager
+  configureAssets({
+    publicDir: publicDir || 'public',
+    ...assetsConfig
+  });
+  
   if (!pagesDir) {
     throw new Error('pagesDir is required');
   }
   
   const app = express();
   
+  // Security headers with Helmet
+  if (helmetConfig !== false) {
+    const defaultConfig = getDefaultHelmetConfig(isDev);
+    const finalConfig = helmetConfig === undefined || helmetConfig === true
+      ? defaultConfig
+      : { ...defaultConfig, ...helmetConfig };
+    
+    app.use(helmet(finalConfig));
+  }
+  
   // Trust proxy (for correct req.ip, req.protocol behind reverse proxy)
   app.set('trust proxy', 1);
   
@@ -103,73 +232,73 @@ function createApp(options = {}) {
   mountPages(app, {
     pagesDir,
     nunjucks: nunjucksEnv,
+    middlewares,
     silent: isTest
   });
   
   // 404 handler
   app.use((req, res) => {
     res.status(404);
+    
+    // Custom handler function
+    if (typeof errorPages.notFound === 'function') {
+      return errorPages.notFound(req, res);
+    }
+    
+    // Custom template
+    if (typeof errorPages.notFound === 'string') {
+      try {
+        const html = nunjucksEnv.render(errorPages.notFound, {
+          url: req.url,
+          method: req.method
+        });
+        return res.send(html);
+      } catch (e) {
+        console.error('Error rendering 404 template:', e);
+      }
+    }
+    
+    // Default response
     if (req.accepts('html')) {
-      res.send(`
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>404 - Not Found</title>
-          <style>
-            body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-            .container { text-align: center; }
-            h1 { font-size: 4rem; margin: 0; color: #333; }
-            p { color: #666; margin: 1rem 0; }
-            a { color: #0066cc; text-decoration: none; }
-            a:hover { text-decoration: underline; }
-          </style>
-        </head>
-        <body>
-          <div class="container">
-            <h1>404</h1>
-            <p>Page not found</p>
-            <a href="/">← Back to Home</a>
-          </div>
-        </body>
-        </html>
-      `);
+      res.send(default404Html());
     } else {
-      res.json({ error: 'Not Found' });
+      res.json({ error: 'Not Found', status: 404 });
     }
   });
   
   // Error handler
   app.use((err, req, res, next) => {
     console.error('Server error:', err);
-    res.status(500);
+    res.status(err.status || 500);
+    
+    // Custom handler function
+    if (typeof errorPages.serverError === 'function') {
+      return errorPages.serverError(err, req, res);
+    }
+    
+    // Custom template
+    if (typeof errorPages.serverError === 'string') {
+      try {
+        const html = nunjucksEnv.render(errorPages.serverError, {
+          error: isDev ? err : { message: 'Internal Server Error' },
+          status: err.status || 500,
+          isDev
+        });
+        return res.send(html);
+      } catch (e) {
+        console.error('Error rendering 500 template:', e);
+      }
+    }
+    
+    // Default response
     if (req.accepts('html')) {
-      res.send(`
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>500 - Server Error</title>
-          <style>
-            body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-            .container { text-align: center; }
-            h1 { font-size: 4rem; margin: 0; color: #333; }
-            p { color: #666; margin: 1rem 0; }
-            pre { background: #fff; padding: 1rem; border-radius: 4px; text-align: left; overflow: auto; max-width: 600px; }
-            a { color: #0066cc; text-decoration: none; }
-            a:hover { text-decoration: underline; }
-          </style>
-        </head>
-        <body>
-          <div class="container">
-            <h1>500</h1>
-            <p>Internal Server Error</p>
-            ${isDev ? `<pre>${err.stack || err.message}</pre>` : ''}
-            <a href="/">← Back to Home</a>
-          </div>
-        </body>
-        </html>
-      `);
+      res.send(default500Html(err, isDev));
     } else {
-      res.json({ error: 'Internal Server Error' });
+      res.json({ 
+        error: 'Internal Server Error', 
+        status: err.status || 500,
+        ...(isDev && { message: err.message, stack: err.stack })
+      });
     }
   });