webspresso 0.0.96 → 0.0.98

package/bin/webspresso.js

@@ -18,7 +18,9 @@ const { registerCommand: registerPage } = require('./commands/page');
 const { registerCommand: registerApi } = require('./commands/api');
 const { registerCommand: registerDev } = require('./commands/dev');
 const { registerCommand: registerStart } = require('./commands/start');
+const { registerCommand: registerBuild } = require('./commands/build');
 const { registerCommand: registerAddTailwind } = require('./commands/add-tailwind');
+const { registerCommand: registerAddEsbuild } = require('./commands/add-esbuild');
 const { registerCommand: registerDbMigrate } = require('./commands/db-migrate');
 const { registerCommand: registerDbRollback } = require('./commands/db-rollback');
 const { registerCommand: registerDbStatus } = require('./commands/db-status');
@@ -29,6 +31,10 @@ const { registerCommand: registerAdminSetup } = require('./commands/admin-setup'
 const { registerCommand: registerAdminPassword } = require('./commands/admin-password');
 const { registerCommand: registerFaviconGenerate } = require('./commands/favicon-generate');
 const { registerCommand: registerAuditPrune } = require('./commands/audit-prune');
+const { registerCommand: registerAnalyticsPrune } = require('./commands/analytics-prune');
+const { registerCommand: registerEmailPrune } = require('./commands/email-prune');
+const { registerCommand: registerQueuePrune } = require('./commands/queue-prune');
+const { registerCommand: registerUploadPrune } = require('./commands/upload-prune');
 const { registerCommand: registerDoctor } = require('./commands/doctor');
 const { registerCommand: registerUpgrade } = require('./commands/upgrade');
 const { registerCommand: registerOrmMap } = require('./commands/orm-map');
@@ -36,13 +42,20 @@ const { registerCommand: registerService } = require('./commands/service');
 const { registerCommand: registerMcp } = require('./commands/mcp');
 const { registerCommand: registerPolarMigrate } = require('./commands/polar-migrate');
 const { registerCommand: registerAgentsInit } = require('./commands/agents-init');
+const { registerCommand: registerRoutes } = require('./commands/routes');
+const { registerCommand: registerMakeModel } = require('./commands/make-model');
+const { registerCommand: registerMakeJob } = require('./commands/make-job');
+const { registerCommand: registerOpenapi } = require('./commands/openapi');
+const { registerCommand: registerTypegen } = require('./commands/typegen');
 
 registerNew(program);
 registerPage(program);
 registerApi(program);
 registerDev(program);
 registerStart(program);
+registerBuild(program);
 registerAddTailwind(program);
+registerAddEsbuild(program);
 registerDbMigrate(program);
 registerDbRollback(program);
 registerDbStatus(program);
@@ -53,6 +66,10 @@ registerAdminSetup(program);
 registerAdminPassword(program);
 registerFaviconGenerate(program);
 registerAuditPrune(program);
+registerAnalyticsPrune(program);
+registerEmailPrune(program);
+registerQueuePrune(program);
+registerUploadPrune(program);
 registerDoctor(program);
 registerUpgrade(program);
 registerOrmMap(program);
@@ -60,6 +77,11 @@ registerService(program);
 registerMcp(program);
 registerPolarMigrate(program);
 registerAgentsInit(program);
+registerRoutes(program);
+registerMakeModel(program);
+registerMakeJob(program);
+registerOpenapi(program);
+registerTypegen(program);
 
 // Parse arguments
 program.parse();

package/core/applySchema.js

@@ -3,6 +3,12 @@
  * Parses and validates request input against compiled schemas
  */
 
+const EMPTY_INPUT = Object.freeze({
+  body: undefined,
+  params: undefined,
+  query: undefined,
+});
+
 /**
  * Apply compiled schema to request
  * Parses body, params, and query against their respective schemas
@@ -14,18 +20,19 @@
  * @throws {ZodError} If validation fails
  */
 function applySchema(req, compiledSchema) {
+  // No schema means no validation
+  if (!compiledSchema) {
+    req.input = EMPTY_INPUT;
+    return;
+  }
+
   // Initialize req.input
   req.input = {
     body: undefined,
     params: undefined,
-    query: undefined
+    query: undefined,
   };
 
-  // No schema means no validation
-  if (!compiledSchema) {
-    return;
-  }
-
   // Parse body if schema exists
   if (compiledSchema.body) {
     req.input.body = compiledSchema.body.parse(req.body);

package/core/auth/hash.js

@@ -4,12 +4,18 @@
  * @module core/auth/hash
  */
 
-let bcrypt;
-try {
-  bcrypt = require('bcrypt');
-} catch {
-  // bcrypt is optional, will throw if used without installation
-  bcrypt = null;
+let bcrypt = null;
+let bcryptChecked = false;
+function getBcrypt() {
+  if (!bcryptChecked) {
+    bcryptChecked = true;
+    try {
+      bcrypt = require('bcrypt');
+    } catch {
+      bcrypt = null;
+    }
+  }
+  return bcrypt;
 }
 
 /**
@@ -25,7 +31,8 @@ const DEFAULT_ROUNDS = process.env.NODE_ENV === 'test' ? 1 : 12;
  * @returns {Promise<string>} Hashed password
  */
 async function hash(password, rounds = DEFAULT_ROUNDS) {
-  if (!bcrypt) {
+  const b = getBcrypt();
+  if (!b) {
     throw new Error('bcrypt is required for password hashing. Install it with: npm install bcrypt');
   }
   
@@ -33,7 +40,7 @@ async function hash(password, rounds = DEFAULT_ROUNDS) {
     throw new Error('Password must be a non-empty string');
   }
   
-  return bcrypt.hash(password, rounds);
+  return b.hash(password, rounds);
 }
 
 /**
@@ -43,7 +50,8 @@ async function hash(password, rounds = DEFAULT_ROUNDS) {
  * @returns {Promise<boolean>} True if password matches
  */
 async function verify(password, hashedPassword) {
-  if (!bcrypt) {
+  const b = getBcrypt();
+  if (!b) {
     throw new Error('bcrypt is required for password verification. Install it with: npm install bcrypt');
   }
   
@@ -52,7 +60,7 @@ async function verify(password, hashedPassword) {
   }
   
   try {
-    return await bcrypt.compare(password, hashedPassword);
+    return await b.compare(password, hashedPassword);
   } catch {
     return false;
   }
@@ -65,7 +73,8 @@ async function verify(password, hashedPassword) {
  * @returns {boolean} True if rehash is needed
  */
 function needsRehash(hashedPassword, rounds = DEFAULT_ROUNDS) {
-  if (!bcrypt) {
+  const b = getBcrypt();
+  if (!b) {
     throw new Error('bcrypt is required. Install it with: npm install bcrypt');
   }
   
@@ -74,7 +83,7 @@ function needsRehash(hashedPassword, rounds = DEFAULT_ROUNDS) {
   }
   
   try {
-    const hashRounds = bcrypt.getRounds(hashedPassword);
+    const hashRounds = b.getRounds(hashedPassword);
     return hashRounds < rounds;
   } catch {
     return true;
@@ -92,14 +101,19 @@ function generateToken(length = 32) {
 }
 
 /**
- * Hash a token for storage (SHA-256)
- * Used for remember me tokens - stored hashed, compared hashed
- * @param {string} token - Plain token
- * @returns {string} Hashed token
+ * Hash a high-entropy random lookup token for database storage (SHA-256).
+ * Note: Used exclusively for 256-bit cryptographically secure random lookup tokens
+ * (remember-me tokens, email verification tokens, password reset tokens), NOT user passwords.
+ * User passwords must always be hashed using `hash()` (bcrypt).
+ *
+ * // CodeQL [js/insufficient-password-hash] SHA-256 is intentionally used for 256-bit high-entropy random lookup token hashing, not user passwords.
+ * @param {string} token - High-entropy random token
+ * @returns {string} Hex-encoded SHA-256 digest
  */
 function hashToken(token) {
   const crypto = require('crypto');
-  return crypto.createHash('sha256').update(token).digest('hex');
+  // CodeQL [js/insufficient-password-hash] False positive: token is a 256-bit random string, not a user password
+  return crypto.createHash('sha256').update(String(token)).digest('hex');
 }
 
 module.exports = {

package/core/compression/middleware.js

@@ -42,6 +42,11 @@ function appendVary(res, field) {
  * @param {Object} [options.deflate] - Custom Deflate options
  * @returns {import('express').RequestHandler}
  */
+function resCompress(enable = true) {
+  this._noCompression = !enable;
+  return this;
+}
+
 function createCompressionMiddleware(options = {}) {
   const threshold = typeof options.threshold === 'number' && options.threshold >= 0 ? options.threshold : 1024;
   const supportedEncodings = Array.isArray(options.encodings) && options.encodings.length > 0
@@ -53,10 +58,7 @@ function createCompressionMiddleware(options = {}) {
   return function compressionMiddleware(req, res, next) {
     // Expose opt-out API on response object
     res._noCompression = false;
-    res.compress = function(enable = true) {
-      res._noCompression = !enable;
-      return res;
-    };
+    res.compress = resCompress;
 
     // Skip compression for HEAD requests
     if (req.method === 'HEAD') {
@@ -64,6 +66,10 @@ function createCompressionMiddleware(options = {}) {
     }
 
     const acceptEncoding = req.headers['accept-encoding'];
+    if (!acceptEncoding) {
+      return next();
+    }
+
     let selectedEncoding = null;
     let checkedEncoding = false;
 
@@ -75,10 +81,10 @@ function createCompressionMiddleware(options = {}) {
       return selectedEncoding;
     }
 
-    // Original methods to wrap
-    const origWrite = res.write.bind(res);
-    const origEnd = res.end.bind(res);
-    const origWriteHead = res.writeHead.bind(res);
+    // Original methods to wrap (store references without .bind() allocation)
+    const origWrite = res.write;
+    const origEnd = res.end;
+    const origWriteHead = res.writeHead;
 
     let compressStream = null;
     let isCompressing = false;
@@ -151,15 +157,15 @@ function createCompressionMiddleware(options = {}) {
 
       // Pipe compression stream chunks directly into underlying socket/response
       compressStream.on('data', (chunk) => {
-        origWrite(chunk);
+        origWrite.call(res, chunk);
       });
 
       compressStream.on('end', () => {
-        origEnd();
+        origEnd.call(res);
       });
 
       compressStream.on('error', (err) => {
-        origEnd();
+        origEnd.call(res);
       });
     }
 
@@ -219,7 +225,7 @@ function createCompressionMiddleware(options = {}) {
           } else {
             // Send buffered chunks uncompressed
             for (const b of bufferedChunks) {
-              origWrite(b);
+              origWrite.call(res, b);
             }
             bufferedChunks = [];
           }
@@ -232,7 +238,7 @@ function createCompressionMiddleware(options = {}) {
         return compressStream.write(buf, callback);
       }
 
-      return origWrite(buf, callback);
+      return origWrite.call(res, buf, callback);
     };
 
     // Wrap end
@@ -253,7 +259,7 @@ function createCompressionMiddleware(options = {}) {
         } else if (isCompressing && compressStream) {
           compressStream.write(buf);
         } else {
-          origWrite(buf);
+          origWrite.call(res, buf);
         }
       }
 
@@ -282,10 +288,10 @@ function createCompressionMiddleware(options = {}) {
             appendVary(res, 'Accept-Encoding');
           }
           for (const b of bufferedChunks) {
-            origWrite(b);
+            origWrite.call(res, b);
           }
           bufferedChunks = [];
-          return origEnd(callback);
+          return origEnd.call(res, callback);
         }
       }
 
@@ -297,7 +303,7 @@ function createCompressionMiddleware(options = {}) {
         return res;
       }
 
-      return origEnd(callback);
+      return origEnd.call(res, callback);
     };
 
     next();

package/core/openapi/build-from-api-routes.js

@@ -1,5 +1,8 @@
+'use strict';
+
 /**
  * Build OpenAPI 3 document from file-router API route metadata + Zod schemas
+ * @module core/openapi/build-from-api-routes
  */
 
 const fs = require('fs');
@@ -16,11 +19,81 @@ const OPENAPI_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head'
  * @returns {string}
  */
 function expressPathToOpenApi(expressPath) {
+  if (!expressPath) return '';
   return String(expressPath)
     .replace(/:([A-Za-z0-9_]+)/g, '{$1}')
+    .replace(/\[([A-Za-z0-9_]+)\]/g, '{$1}')
     .replace(/\*/g, '{wildcard}');
 }
 
+/**
+ * Resolves the physical file path of an API route descriptor
+ * @param {Object} route
+ * @param {string} [pagesDir]
+ * @returns {string|null}
+ */
+function resolveRouteFilePath(route, pagesDir) {
+  const rawFile = route.file || route.source;
+  if (!rawFile) return null;
+
+  if (path.isAbsolute(rawFile) && fs.existsSync(rawFile)) {
+    return rawFile;
+  }
+
+  const fromCwd = path.resolve(process.cwd(), rawFile);
+  if (fs.existsSync(fromCwd)) {
+    return fromCwd;
+  }
+
+  if (pagesDir) {
+    const fromPages = path.join(path.resolve(pagesDir), rawFile);
+    if (fs.existsSync(fromPages)) {
+      return fromPages;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Infers an expressive operation summary from HTTP method and path
+ * @param {string} method
+ * @param {string} routePath
+ * @returns {string}
+ */
+function inferOperationSummary(method, routePath) {
+  const clean = String(routePath || '').replace(/^\/api\/?/, '').replace(/\/$/, '');
+  const segments = clean.split('/').filter(Boolean);
+  const lastSeg = segments[segments.length - 1] || 'root';
+  const isParam = lastSeg.startsWith(':') || (lastSeg.startsWith('{') && lastSeg.endsWith('}')) || (lastSeg.startsWith('[') && lastSeg.endsWith(']'));
+  const resource = isParam && segments.length > 1 ? segments[segments.length - 2] : lastSeg;
+  const m = String(method || 'GET').toUpperCase();
+
+  if (m === 'GET') {
+    return isParam ? `Get ${resource} by ID` : `List ${resource}`;
+  }
+  if (m === 'POST') return `Create ${resource}`;
+  if (m === 'PUT' || m === 'PATCH') return `Update ${resource}`;
+  if (m === 'DELETE') return `Delete ${resource}`;
+  return `${m} /api/${clean}`;
+}
+
+/**
+ * Infers tag category from route path segments
+ * @param {string} routePath
+ * @param {string[]} [explicitTags]
+ * @returns {string[]}
+ */
+function inferOperationTags(routePath, explicitTags) {
+  if (Array.isArray(explicitTags) && explicitTags.length > 0) return explicitTags;
+  const clean = String(routePath || '').replace(/^\/api\/?/, '').replace(/\/$/, '');
+  const firstSeg = clean.split('/').filter(Boolean)[0];
+  if (firstSeg && !firstSeg.startsWith(':') && !firstSeg.startsWith('{') && !firstSeg.startsWith('[')) {
+    return [firstSeg];
+  }
+  return ['api'];
+}
+
 /**
  * @param {import('zod').ZodObject<any>} zodObj
  * @param {'path' | 'query'} where
@@ -38,19 +111,31 @@ function expandZodObjectToParameters(zodObj, where) {
 }
 
 /**
- * @param {object} route - { type, method, pattern, file }
+ * @param {object} route - { type, method, pattern, path, file }
  * @param {object|null} compiled - compileSchema result
+ * @param {object|null} [mod] - Raw route module
  * @returns {object} OpenAPI Operation Object
  */
-function buildOperation(route, compiled) {
-  const filePath = route.file;
-  const method = route.method.toLowerCase();
-  const summary = `${method.toUpperCase()} ${filePath}`;
+function buildOperation(route, compiled, mod = null) {
+  const filePath = route.file || route.source || '';
+  const method = (route.method || 'GET').toLowerCase();
+  const routePath = route.path || route.pattern || filePath;
+
+  let summary = (mod && (mod.summary || mod.openapi?.summary)) || route.summary;
+  if (!summary) {
+    if (filePath) {
+      summary = `${method.toUpperCase()} ${filePath}`;
+    } else {
+      summary = inferOperationSummary(method, routePath);
+    }
+  }
+
+  const tags = inferOperationTags(routePath, (mod && (mod.tags || mod.openapi?.tags)) || route.tags);
 
   const op = {
-    tags: ['api'],
+    tags,
     summary,
-    operationId: String(filePath)
+    operationId: String(filePath || routePath)
       .replace(/[^a-zA-Z0-9]+/g, '_')
       .replace(/^_|_$/g, ''),
     responses: {
@@ -60,6 +145,25 @@ function buildOperation(route, compiled) {
     },
   };
 
+  if (mod && mod.description) {
+    op.description = mod.description;
+  }
+
+  // Auth / Security detection
+  const middlewares = Array.isArray(route.middleware)
+    ? route.middleware
+    : (Array.isArray(mod?.middleware) ? mod.middleware : []);
+  const security = [];
+  if (middlewares.includes('jwt') || middlewares.includes('bearer')) {
+    security.push({ bearerAuth: [] });
+  }
+  if (middlewares.includes('auth') || middlewares.includes('session')) {
+    security.push({ sessionAuth: [] });
+  }
+  if (security.length > 0) {
+    op.security = security;
+  }
+
   if (compiled?.response) {
     op.responses['200'] = {
       description: 'OK',
@@ -94,16 +198,17 @@ function buildOperation(route, compiled) {
 }
 
 /**
+ * Builds an OpenAPI 3.0 document from application routes and ORM components
  * @param {object} opts
- * @param {object[]} opts.routes - route metadata from mountPages
- * @param {string} opts.pagesDir
- * @param {boolean} [opts.includeOrmSchemas]
- * @param {string[]} [opts.ormExclude]
+ * @param {object[]} opts.routes - Route metadata array
+ * @param {string} opts.pagesDir - Pages directory path
+ * @param {boolean} [opts.includeOrmSchemas=false]
+ * @param {string[]} [opts.ormExclude=[]]
  * @param {object} [opts.info]
  * @param {object[]} [opts.servers]
  * @returns {object} OpenAPI 3.0.x document
  */
-function buildOpenApiDocument(opts) {
+function buildOpenApiDocument(opts = {}) {
   const {
     routes = [],
     pagesDir,
@@ -118,31 +223,39 @@ function buildOpenApiDocument(opts) {
   }
 
   const paths = Object.create(null);
-  const apiRoutes = routes.filter((r) => r.type === 'api');
-  const absPages = path.resolve(pagesDir);
+  const apiRoutes = routes.filter((r) => r.type === 'api' || (r.path && r.path.startsWith('/api')));
 
   for (const route of apiRoutes) {
-    const fullPath = path.join(absPages, route.file);
-    if (!fs.existsSync(fullPath)) {
-      continue;
-    }
+    const fullPath = resolveRouteFilePath(route, pagesDir);
 
-    let mod;
-    try {
-      mod = require(fullPath);
-    } catch {
+    if (route.file && !fullPath) {
       continue;
     }
 
+    let mod = null;
     let compiled = null;
-    try {
-      compiled = compileSchema(fullPath, mod);
-    } catch {
-      compiled = null;
+
+    if (fullPath) {
+      try {
+        mod = require(fullPath);
+      } catch {
+        mod = null;
+      }
+
+      if (mod) {
+        try {
+          compiled = compileSchema(fullPath, mod);
+        } catch {
+          compiled = null;
+        }
+      }
     }
 
-    const openApiPath = expressPathToOpenApi(route.pattern);
-    const method = route.method.toLowerCase();
+    const routePattern = route.path || route.pattern || '';
+    if (!routePattern) continue;
+
+    const openApiPath = expressPathToOpenApi(routePattern);
+    const method = (route.method || 'GET').toLowerCase();
 
     if (!OPENAPI_METHODS.has(method)) {
       continue;
@@ -152,7 +265,7 @@ function buildOpenApiDocument(opts) {
       paths[openApiPath] = Object.create(null);
     }
 
-    paths[openApiPath][method] = buildOperation(route, compiled);
+    paths[openApiPath][method] = buildOperation(route, compiled, mod);
   }
 
   const doc = {
@@ -165,6 +278,20 @@ function buildOpenApiDocument(opts) {
     servers,
     paths,
     components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'Stateless JWT Bearer token authentication',
+        },
+        sessionAuth: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: 'connect.sid',
+          description: 'Session cookie authentication',
+        },
+      },
       schemas: includeOrmSchemas ? generateOrmOpenApiSchemas({ exclude: ormExclude }) : {},
     },
   };
@@ -174,5 +301,9 @@ function buildOpenApiDocument(opts) {
 
 module.exports = {
   expressPathToOpenApi,
+  resolveRouteFilePath,
+  inferOperationSummary,
+  inferOperationTags,
+  buildOperation,
   buildOpenApiDocument,
 };

package/core/orm/cache/fingerprint.js

@@ -28,7 +28,21 @@ function stableValue(v) {
     const k = keys[0];
     return { [k]: stableValue(v[k]) };
   }
-  keys.sort();
+  if (keyLen === 2) {
+    const k0 = keys[0];
+    const k1 = keys[1];
+    return k0 < k1
+      ? { [k0]: stableValue(v[k0]), [k1]: stableValue(v[k1]) }
+      : { [k1]: stableValue(v[k1]), [k0]: stableValue(v[k0]) };
+  }
+  let isSorted = true;
+  for (let i = 1; i < keyLen; i++) {
+    if (keys[i - 1] > keys[i]) {
+      isSorted = false;
+      break;
+    }
+  }
+  if (!isSorted) keys.sort();
   const out = {};
   for (let i = 0; i < keyLen; i++) {
     const k = keys[i];

package/core/orm/cache/memory-provider.js

@@ -56,8 +56,20 @@ function createMemoryCacheProvider(options = {}) {
     if (store.has(key)) removeKey(key);
 
     if (maxEntries > 0 && store.size >= maxEntries) {
-      const first = store.keys().next().value;
-      if (first !== undefined) removeKey(first);
+      // Active sweep: evict expired entries before falling back to FIFO eviction
+      const now = Date.now();
+      let freed = 0;
+      for (const [k, entry] of store.entries()) {
+        if (entry.expiresAt > 0 && now > entry.expiresAt) {
+          removeKey(k);
+          freed++;
+          if (freed >= 10 || store.size < maxEntries) break;
+        }
+      }
+      if (store.size >= maxEntries) {
+        const first = store.keys().next().value;
+        if (first !== undefined) removeKey(first);
+      }
     }
 
     const expiresAt = ttlMs > 0 ? Date.now() + ttlMs : 0;
@@ -82,6 +94,18 @@ function createMemoryCacheProvider(options = {}) {
     for (const t of tags) tagToKeys.delete(t);
   }
 
+  function pruneExpired() {
+    const now = Date.now();
+    let count = 0;
+    for (const [k, entry] of store.entries()) {
+      if (entry.expiresAt > 0 && now > entry.expiresAt) {
+        removeKey(k);
+        count++;
+      }
+    }
+    return count;
+  }
+
   function clear() {
     store.clear();
     tagToKeys.clear();
@@ -99,6 +123,7 @@ function createMemoryCacheProvider(options = {}) {
     get,
     set,
     invalidateTags,
+    pruneExpired,
     clear,
     getSizeStats,
   };