webspresso 0.0.108 → 0.0.109

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Webspresso Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 
-A batteries-included, full-stack Node.js framework combining Next.js/Nuxt-style file-based routing, server-rendered Nunjucks streaming, a Knex-based ORM with ambient transactions, zero-dependency dual authentication, background queues, and a customizable Mithril.js SPA Admin Panel.
+A batteries-included, full-stack Node.js framework combining Next.js/Nuxt-style file-based routing, server-rendered Nunjucks streaming, a Knex-based ORM with ambient transactions, built-in native dual authentication, background queues, and a customizable Mithril.js SPA Admin Panel.
 
 ---
 
@@ -33,10 +33,10 @@ Open **`http://localhost:7331`** in your browser.
 | **Routing & SSR** | 100% file-based routing (`pages/`), method suffixes (`.get.js`, `.post.js`), nested layouts (`_layout.njk`), directory-level error boundaries (`_error.njk`), loading skeletons (`_loading.njk`), and out-of-order chunked response streaming (`res.renderStream`). |
 | **Performance & Cold Start** | Single-pass unified route discovery, dev mode JIT on-demand route evaluation, production AOT route manifest (`webspresso build`), AOT Nunjucks template precompilation (zero AST parsing at runtime), and on-demand lazy plugin mounting. |
 | **Database & ORM** | Built-in Knex ORM with `defineModel`, `zdb` schema builder, Repository pattern (`db.getRepository('Model')`), relations (`belongsTo`, `hasMany`), cascade soft-delete & restore, and ambient transactions via `AsyncLocalStorage`. |
-| **Dual Auth & Sessions** | Stateful cookies for SSR + stateless HS256 JWT rotation for APIs, magic links, active device management & remote session revocation, CSRF protection, and zero external auth dependencies. |
+| **Dual Auth & Sessions** | Stateful cookies for SSR + stateless HS256 JWT rotation for APIs, magic links, active device management & remote session revocation, CSRF protection, and built-in native auth. |
 | **Services & Queues** | File-based auto-discovery in `services/` with declarative Zod validation, role-based access guards, and ACID transaction propagation. Background worker queues in `jobs/`. |
 | **Admin Panel SPA** | Integrated Mithril.js single-page admin panel mounted at `/_admin` with auto-layout wrapping, CRUD views, custom dashboard widgets, and custom field renderers. Supports on-demand lazy mounting (`adminPanelPlugin({ lazy: true })`). |
-| **Plugin Ecosystem** | 20+ official plugins: Polar.sh billing, Webhooks dispatcher with HMAC signatures, Realtime (WebSocket/SSE), Site Analytics, API Keys, File Manager, CSV/Excel generation, On-demand Lazy Plugins (`lazyPlugin`), and more. |
+| **Plugin Ecosystem** | 20+ official plugins: Polar.sh billing, Webhooks dispatcher with HMAC signatures, Realtime client layer (WebSocket/SSE/Socket.IO adapters), Site Analytics, API Keys, File Manager, CSV/Excel generation, On-demand Lazy Plugins (`lazyPlugin`), and more. |
 | **DevOps & Production** | Built-in streaming zlib compression (`brotli`/`gzip`), socket connection draining & graceful shutdown, `webspresso deploy:check` production readiness auditor, and Docker scaffolding. |
 
 ---

package/bin/commands/add-esbuild.js

@@ -5,11 +5,15 @@
 
 const fs = require('fs');
 const path = require('path');
+const { getAddCommand } = require('../utils/add-command');
 
 function registerCommand(program) {
-  program
-    .command('add esbuild')
-    .alias('add:esbuild')
+  configureCommand(program.command('add:esbuild'));
+  configureCommand(getAddCommand(program).command('esbuild'));
+}
+
+function configureCommand(command) {
+  command
     .description('Add esbuild client bundling and incremental watch to the project')
     .action(async () => {
       if (!fs.existsSync('package.json')) {

package/bin/commands/add-tailwind.js

@@ -6,11 +6,15 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { getAddCommand } = require('../utils/add-command');
 
 function registerCommand(program) {
-  program
-    .command('add tailwind')
-    .alias('add:tailwind')
+  configureCommand(program.command('add:tailwind'));
+  configureCommand(getAddCommand(program).command('tailwind'));
+}
+
+function configureCommand(command) {
+  command
     .description('Add Tailwind CSS to the project with build process')
     .option('--v4', 'Use Tailwind CSS v4 (Oxide engine, LightningCSS, zero postcss config)')
     .option('--v3', 'Use Tailwind CSS v3 (legacy PostCSS engine)')
@@ -65,9 +69,9 @@ function registerCommand(program) {
         packageJson.scripts.dev = 'npm run watch:css & node --watch server.js';
       }
       
-      // Update start script to build CSS
+      // Update start script to build CSS (webspresso build runs Tailwind) and start cross-platform
       if (packageJson.scripts.start) {
-        packageJson.scripts.start = 'npm run build:css && NODE_ENV=production node server.js';
+        packageJson.scripts.start = 'webspresso build && webspresso start';
       }
       
       fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n');

package/bin/commands/build.js

@@ -6,7 +6,8 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { buildBundle } = require('../../src/bundle');
+const { buildBundle, findPageEntryPoints } = require('../../src/bundle');
+const { generateTypes, checkTemplateFormContracts } = require('../../src/dev/typegen');
 
 function registerCommand(program) {
   program
@@ -56,11 +57,14 @@ function registerCommand(program) {
         }
       }
 
-      // 2. Build JS Bundle with manifest.json (esbuild)
+      // 2. Build JS Bundle with manifest.json (esbuild or fallback)
       if (options.js !== false) {
-        const hasClientEntry = fs.existsSync(path.join(cwd, 'src', 'client', 'main.js')) ||
+        const discoveredClientPages = findPageEntryPoints(cwd);
+        const hasClientEntry =
+          fs.existsSync(path.join(cwd, 'src', 'client', 'main.js')) ||
           fs.existsSync(path.join(cwd, 'src', 'client', 'main.ts')) ||
-          fs.existsSync(path.join(cwd, 'src', 'client', 'index.js'));
+          fs.existsSync(path.join(cwd, 'src', 'client', 'index.js')) ||
+          Object.keys(discoveredClientPages).length > 0;
         const hasEsbuild = Boolean(
           (packageJson.devDependencies && packageJson.devDependencies.esbuild) ||
           (packageJson.dependencies && packageJson.dependencies.esbuild)
@@ -122,6 +126,18 @@ function registerCommand(program) {
         }
       }
 
+      // 5. Generate TypeScript & API Route Manifest (.webspresso/types.d.ts & .webspresso/api.d.ts) and check HTML form contracts
+      try {
+        generateTypes({ rootDir: cwd, silent: true });
+        const formCheck = checkTemplateFormContracts(cwd);
+        for (const w of formCheck.warnings) {
+          console.warn(`⚠️  [Form Check] ${w.message}`);
+        }
+        for (const e of formCheck.errors) {
+          console.warn(`❌ [Form Contract Mismatch] ${e.message}`);
+        }
+      } catch (_) {}
+
       console.log('\n✨ Asset build complete!\n');
       if (cssBuilt) console.log('  ✓ CSS: public/css/style.css');
       if (jsBuilt) console.log('  ✓ JS: public/dist/ & manifest.json');

package/bin/commands/dev.js

@@ -4,24 +4,60 @@
  */
 
 const fs = require('fs');
+const path = require('path');
 const { spawn } = require('child_process');
 
 /**
  * Build node --watch arguments with additional watch paths
+ * @param {string} [projectRoot=process.cwd()]
  * @returns {string[]} Node arguments
  */
-function buildWatchArgs() {
+function buildWatchArgs(projectRoot = process.cwd()) {
   const args = ['--watch'];
   
-  // Add watch paths for server-side code directories (services, models, config, pages)
-  // Note: views contains Nunjucks templates which are live-reloaded in-memory by devReloadHub
-  const watchPaths = ['pages', 'models', 'services', 'config'];
+  // Add watch paths for server-side code directories:
+  // - pages: File-based routing and companion loaders
+  // - models: ORM database models
+  // - services: Business logic services
+  // - jobs: Background queues and scheduled cron workers
+  // - listeners: Decoupled events and signals
+  // - modules / src/modules: Modular domain packages
+  // - plugins / src/plugins: Local plugin extensions
+  // - config: App config and credentials
+  // - migrations: DB migration definitions
+  const watchPaths = [
+    'pages',
+    'models',
+    'services',
+    'jobs',
+    'listeners',
+    'modules',
+    'plugins',
+    'config',
+    'migrations',
+    'src/models',
+    'src/services',
+    'src/jobs',
+    'src/listeners',
+    'src/modules',
+    'src/plugins',
+  ];
   
   for (const dir of watchPaths) {
-    if (fs.existsSync(dir)) {
+    const fullPath = path.isAbsolute(dir) ? dir : path.join(projectRoot, dir);
+    if (fs.existsSync(fullPath)) {
       args.push(`--watch-path=./${dir}`);
     }
   }
+
+  // Also watch .env files if present
+  const envFiles = ['.env', '.env.local', '.env.development'];
+  for (const envFile of envFiles) {
+    const fullPath = path.join(projectRoot, envFile);
+    if (fs.existsSync(fullPath)) {
+      args.push(`--watch-path=./${envFile}`);
+    }
+  }
   
   args.push('server.js');
   return args;
@@ -31,7 +67,7 @@ function registerCommand(program) {
   program
     .command('dev')
     .description('Start development server')
-    .option('-p, --port <port>', 'Port number', '7331')
+    .option('-p, --port <port>', 'Port number (default: $PORT or 7331)')
     .option('--no-css', 'Skip CSS watch (if Tailwind is set up)')
     .option('--no-js', 'Skip client JS watch (if esbuild / watch:js is set up)')
     .action((options) => {
@@ -40,6 +76,7 @@ function registerCommand(program) {
         process.exit(1);
       }
       
+      options.port = options.port || process.env.PORT || '7331';
       process.env.PORT = options.port;
       process.env.NODE_ENV = 'development';
       
@@ -74,6 +111,19 @@ function registerCommand(program) {
       if (shouldWatchCss) watchingLabels.push('CSS');
       if (shouldWatchJs) watchingLabels.push('JS (esbuild)');
 
+      // Generate initial .webspresso/types.d.ts and .webspresso/api.d.ts and warn on dynamic/mismatched HTML form fields
+      try {
+        const { generateTypes, checkTemplateFormContracts } = require('../../src/dev/typegen');
+        generateTypes({ rootDir: process.cwd(), silent: true });
+        const formCheck = checkTemplateFormContracts(process.cwd());
+        for (const w of formCheck.warnings) {
+          console.warn(`⚠️  [Form Check] ${w.message}`);
+        }
+        for (const e of formCheck.errors) {
+          console.warn(`❌ [Form Contract Mismatch] ${e.message}`);
+        }
+      } catch (_) {}
+
       console.log(`\n🚀 Starting development server on port ${options.port}...`);
       console.log(`   Watching: ${watchingLabels.join(', ')}\n`);
 
@@ -124,4 +174,4 @@ function registerCommand(program) {
     });
 }
 
-module.exports = { registerCommand };
+module.exports = { registerCommand, buildWatchArgs };

package/bin/commands/doctor.js

@@ -5,6 +5,13 @@
 const fs = require('fs');
 const path = require('path');
 const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
+const { isClientBrowserFile } = require('../../src/discovery/file-route-parser');
+const {
+  discoverClientControllers,
+  findDefaultEntryPoints,
+  validateClientBundleBoundaries,
+} = require('../../src/bundle');
+const { checkTemplateFormContracts } = require('../../src/dev/typegen');
 
 /**
  * @param {string} enginesNode - e.g. ">=18.0.0", "^20.1.0"
@@ -136,13 +143,17 @@ function registerCommand(program) {
           return name;
         }
 
-        const VALID_API_METHODS = ['.get.js', '.post.js', '.put.js', '.patch.js', '.delete.js'];
+        const VALID_API_METHODS = [
+          '.get.js', '.post.js', '.put.js', '.patch.js', '.delete.js',
+          '.get.ts', '.post.ts', '.put.ts', '.patch.ts', '.delete.ts',
+        ];
 
         function scanRoutes(dirPath, relativeDir = '', isApi = false) {
           const children = fs.readdirSync(dirPath);
           const kept = [];
 
           for (const child of children) {
+            if (isClientBrowserFile(child)) continue;
             const fullPath = path.join(dirPath, child);
             const relPath = relativeDir ? path.join(relativeDir, child) : child;
             const stats = fs.statSync(fullPath);
@@ -215,6 +226,36 @@ function registerCommand(program) {
         warnings += 1;
       }
 
+      console.log('\nClient Behavior & Form Contracts');
+      console.log('--------------------------------');
+      try {
+        const controllers = discoverClientControllers(cwd);
+        const entries = findDefaultEntryPoints(cwd);
+        validateClientBundleBoundaries(entries, cwd);
+        line('✓', `Client controllers verified (${controllers.length} controller(s), zero boundary leaks or collisions)`);
+      } catch (clientErr) {
+        line('✗', clientErr.message || String(clientErr));
+        errors += 1;
+      }
+
+      try {
+        const formCheck = checkTemplateFormContracts(cwd);
+        for (const w of formCheck.warnings) {
+          line('⚠', w.message);
+          warnings += 1;
+        }
+        for (const e of formCheck.errors) {
+          line('✗', e.message);
+          errors += 1;
+        }
+        if (formCheck.errors.length === 0 && formCheck.warnings.length === 0) {
+          line('✓', `Static HTML form contracts verified (${formCheck.checkedFormsCount} API form(s) checked)`);
+        }
+      } catch (formErr) {
+        line('⚠', `Form contract check skipped: ${formErr.message}`);
+        warnings += 1;
+      }
+
       console.log('\nTailwind CSS');
       console.log('------------');
       const inputCssPath = path.join(cwd, 'src', 'input.css');

package/bin/commands/favicon-generate.js

@@ -6,9 +6,16 @@
 const fs = require('fs');
 const path = require('path');
 function getSharp() {
-  return (process.env.NODE_ENV === 'test' || process.env.VITEST)
-    ? require('../../tests/mocks/sharp')
-    : require('sharp');
+  if (process.env.NODE_ENV === 'test' || process.env.VITEST) {
+    return require('../../tests/mocks/sharp');
+  }
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error(
+      "The 'sharp' package is required to generate favicons. Install it with: npm install sharp"
+    );
+  }
 }
 
 const APPLE_SIZES = [57, 60, 72, 76, 114, 120, 144, 152, 180];

package/bin/commands/new.js

@@ -12,6 +12,8 @@ const inquirer = {
 };
 const fs = require('fs');
 const path = require('path');
+
+const FRAMEWORK_VERSION = require('../../package.json').version;
 const { runInstallation, startDevServer } = require('../utils/project');
 const { getSeedFileTemplate } = require('../utils/seed');
 const { scaffoldAgentsFiles } = require('./agents-init');
@@ -250,10 +252,13 @@ function registerCommand(program) {
         main: 'server.js',
         scripts: {
           dev: 'webspresso dev',
-          start: 'NODE_ENV=production node server.js'
+          build: 'webspresso build',
+          // `webspresso start` sets NODE_ENV=production cross-platform; build first so the
+          // AOT route manifest and precompiled templates are used in production.
+          start: 'webspresso build && webspresso start'
         },
         dependencies: {
-          webspresso: '*',
+          webspresso: `^${FRAMEWORK_VERSION}`,
           dotenv: '^16.3.1',
           zod: '^3.23.0'
         }
@@ -728,7 +733,7 @@ module.exports = {
         }
         
         updatedPackageJson.scripts.dev = 'webspresso dev';
-        updatedPackageJson.scripts.start = 'npm run build:css && NODE_ENV=production node server.js';
+        updatedPackageJson.scripts.start = 'webspresso build && webspresso start';
         
         fs.writeFileSync(
           path.join(projectPath, 'package.json'),

package/bin/commands/start.js

@@ -10,13 +10,15 @@ function registerCommand(program) {
   program
     .command('start')
     .description('Start production server')
-    .option('-p, --port <port>', 'Port number', '7331')
+    .option('-p, --port <port>', 'Port number (default: $PORT or 7331)')
     .action((options) => {
       if (!fs.existsSync('server.js')) {
         console.error('❌ server.js not found! Make sure you are in a Webspresso project.');
         process.exit(1);
       }
       
+      // Respect the platform-provided PORT (Cloud Run, Render, Heroku...) unless --port is given
+      options.port = options.port || process.env.PORT || '7331';
       process.env.PORT = options.port;
       process.env.NODE_ENV = 'production';
       

package/bin/utils/add-command.js

@@ -0,0 +1,16 @@
+/**
+ * Shared `add` parent command
+ * Lets integrations register as `webspresso add <name>` subcommands without
+ * colliding with each other (each also registers its own `add:<name>` form).
+ */
+
+function getAddCommand(program) {
+  const existing = program.commands.find((cmd) => cmd.name() === 'add');
+  if (existing) return existing;
+
+  return program
+    .command('add')
+    .description('Add an integration to the project (e.g. add tailwind, add esbuild)');
+}
+
+module.exports = { getAddCommand };

package/core/app.js

@@ -176,9 +176,52 @@ class CoreApp {
       }
     }
 
+    // 6.5. Background Queue & Jobs auto-discovery
+    let resolvedQueue = options.queue;
+    if (resolvedQueue === undefined) {
+      const candidateJobsDir = options.jobsDir
+        ? (path.isAbsolute(options.jobsDir) ? options.jobsDir : path.join(this.rootDir, options.jobsDir))
+        : (fs.existsSync(path.join(this.rootDir, 'jobs'))
+          ? path.join(this.rootDir, 'jobs')
+          : (fs.existsSync(path.join(this.rootDir, 'src/jobs'))
+            ? path.join(this.rootDir, 'src/jobs')
+            : null));
+      if (candidateJobsDir && fs.existsSync(candidateJobsDir)) {
+        const { createQueueManager } = require('./queue');
+        resolvedQueue = createQueueManager({
+          jobsDir: candidateJobsDir,
+          autoStart: options.queueAutoStart !== undefined ? Boolean(options.queueAutoStart) : (process.env.NODE_ENV !== 'test'),
+          timeouts: options.timeouts,
+          adapter: options.queueAdapter,
+        });
+      }
+    } else if (resolvedQueue && typeof resolvedQueue === 'object' && typeof resolvedQueue.dispatch !== 'function') {
+      const { createQueueManager } = require('./queue');
+      resolvedQueue = createQueueManager({
+        autoStart: options.queueAutoStart !== undefined ? Boolean(options.queueAutoStart) : (process.env.NODE_ENV !== 'test'),
+        timeouts: options.timeouts,
+        ...resolvedQueue,
+      });
+    }
+
+    if (resolvedQueue && typeof resolvedQueue !== 'boolean') {
+      this.queue = resolvedQueue;
+      if (this.shutdownManager) {
+        this.shutdownManager.registerDisposer('queue', () => {
+          if (typeof resolvedQueue.drain === 'function') {
+            return resolvedQueue.drain();
+          } else if (typeof resolvedQueue.stop === 'function') {
+            return resolvedQueue.stop();
+          }
+        });
+      }
+    } else {
+      this.queue = null;
+    }
+
     // 7. Events Subsystem
     this.events = options.events || createEventDispatcher({
-      queue: options.queue || null,
+      queue: this.queue,
       logger: this.logger,
     });
     this.shutdownManager.onShutdown(() => {
@@ -238,9 +281,8 @@ class CoreApp {
       this.flags = null;
     }
 
-    // 10. Database & Queue
+    // 10. Database
     this.db = options.db ?? null;
-    this.queue = options.queue ?? null;
 
     // 10. Module Services discovery (if modules directory exists)
     this.moduleMiddlewares = {};

package/core/auth/authenticate.js

@@ -25,10 +25,10 @@ async function authenticateRequest(req, res, authManager) {
     req.auth = authManager.createRequestAuth(req, res);
   }
 
-  // 1. Check Bearer JWT token header first
+  // 1. Check Bearer JWT token header first (case-insensitive per RFC 6750)
   const authHeader = req.headers?.authorization || req.headers?.Authorization;
-  if (authHeader && authHeader.startsWith('Bearer ')) {
-    const token = authHeader.substring(7).trim();
+  if (authHeader && /^Bearer\s+/i.test(authHeader)) {
+    const token = authHeader.replace(/^Bearer\s+/i, '').trim();
     try {
       const payload = authManager.verifyJwt(token);
       req.token = token;