webspresso 0.0.104 → 0.0.106

package/bin/commands/console.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * Webspresso CLI - console Command
+ * Launches interactive REPL console with preloaded framework context
+ * @module bin/commands/console
+ */
+
+const { startConsole, evaluateInConsole } = require('../../core/console');
+
+function registerCommand(program) {
+  program
+    .command('console')
+    .alias('c')
+    .description('Start interactive Webspresso REPL console with preloaded db, models, and services')
+    .option('-e, --eval <code-string>', 'Evaluate JavaScript code and print result, then exit')
+    .option('-E, --env <environment>', 'Environment name (default: development)')
+    .option('-c, --config <path>', 'Path to database config file (optional)')
+    .option('--no-history', 'Disable command history persistence')
+    .option('--no-banner', 'Do not display startup banner')
+    .action(async (options) => {
+      try {
+        if (options.eval) {
+          const { output, error } = await evaluateInConsole(options.eval, {
+            configPath: options.config,
+            env: options.env,
+          });
+          if (error) {
+            console.error(error.stack || error.message);
+            process.exit(1);
+          }
+          if (output !== undefined && output !== 'undefined') {
+            console.log(output);
+          }
+          process.exit(0);
+        } else {
+          await startConsole({
+            configPath: options.config,
+            env: options.env,
+            history: options.history,
+            banner: options.banner,
+          });
+        }
+      } catch (err) {
+        console.error('❌ Failed to start Webspresso console:', err.message);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+};

package/bin/commands/db-migrate.js

@@ -4,6 +4,7 @@
  */
 
 const { loadDbConfig, createDbInstance } = require('../utils/db');
+const { runCloudMigration, freeStaleMigrationLock, getMigrationStatus } = require('../../core/orm/migrate-cloud');
 
 function registerCommand(program) {
   program
@@ -11,15 +12,59 @@ function registerCommand(program) {
     .description('Run pending database migrations')
     .option('-e, --env <environment>', 'Environment (development, production)', 'development')
     .option('-c, --config <path>', 'Path to database config file')
+    .option('--safe', 'Run in cloud-safe mode with connectivity retries and stale lock auto-healing')
+    .option('--dry-run', 'Preview pending migrations without applying them')
+    .option('--unlock-if-stale', 'Automatically release stale migration locks from aborted jobs')
+    .option('--force-unlock', 'Force release migration table lock immediately')
+    .option('--retries <n>', 'Database connection retry attempts', (v) => parseInt(v, 10), 5)
     .action(async (options) => {
       const { config, path: configPath } = loadDbConfig(options.config);
       console.log(`\n📦 Using config: ${configPath}`);
       console.log(`   Environment: ${options.env}\n`);
       
       const knex = await createDbInstance(config, options.env);
-      
+      const migrationConfig = config.migrations || {};
+
       try {
-        const migrationConfig = config.migrations || {};
+        if (options.forceUnlock) {
+          console.log('🔓 Releasing migration lock table...');
+          await freeStaleMigrationLock(knex, migrationConfig);
+          console.log('✅ Migration lock freed.\n');
+          return;
+        }
+
+        if (options.safe || options.dryRun || options.unlockIfStale) {
+          const result = await runCloudMigration(knex, {
+            migrationConfig,
+            dryRun: Boolean(options.dryRun),
+            unlockIfStale: Boolean(options.unlockIfStale || options.safe),
+            waitForDb: Boolean(options.safe),
+            retries: options.retries || 5,
+            logger: (msg) => console.log(`  → ${msg}`),
+          });
+
+          if (result.dryRun) {
+            if (result.pendingBefore.length === 0) {
+              console.log('✅ Dry-run: Database is up to date. No pending migrations.\n');
+            } else {
+              console.log(`\n🔍 Dry-run: ${result.pendingBefore.length} migration(s) pending:`);
+              for (const m of result.pendingBefore) {
+                console.log(`  ○ ${m}`);
+              }
+              console.log('');
+            }
+            return;
+          }
+
+          if (result.applied.length === 0) {
+            console.log('✅ Already up to date.\n');
+          } else {
+            console.log(`\n✅ Done. ${result.applied.length} migration(s) completed in ${result.durationMs}ms.\n`);
+          }
+          return;
+        }
+
+        // Standard knex migration run
         const [batch, migrations] = await knex.migrate.latest(migrationConfig);
         
         if (migrations.length === 0) {

package/bin/commands/db-studio.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * Webspresso CLI DB Studio Command
+ * Launches visual database browser and SQL console
+ * @module bin/commands/db-studio
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadDbConfig, createDbInstance } = require('../utils/db');
+const { startStudio } = require('../../core/studio');
+
+function registerCommand(program) {
+  program
+    .command('db:studio')
+    .alias('studio')
+    .description('Open interactive visual database browser and SQL runner in your browser')
+    .option('-p, --port <port>', 'Port to listen on', '4567')
+    .option('-H, --host <host>', 'Host to bind to', '127.0.0.1')
+    .option('-e, --env <environment>', 'Environment (development, production)', 'development')
+    .option('-c, --config <path>', 'Path to database config file')
+    .option('--open', 'Automatically open browser', true)
+    .option('--no-open', 'Do not open browser')
+    .action(async (options = {}) => {
+      const cwd = process.cwd();
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) {
+        console.error('❌ Not a Webspresso project! Run this command in your project directory.');
+        process.exit(1);
+      }
+
+      let dbConfig;
+      let configPath;
+
+      try {
+        const loaded = loadDbConfig(options.config);
+        dbConfig = loaded.config;
+        configPath = loaded.path;
+      } catch (err) {
+        console.error('❌ Database configuration could not be loaded:', err.message);
+        process.exit(1);
+      }
+
+      console.log(`\n📦 Using config: ${path.relative(cwd, configPath)} (${options.env})`);
+      const knex = await createDbInstance(dbConfig, options.env);
+
+      try {
+        const port = parseInt(options.port, 10) || 4567;
+        const host = options.host || '127.0.0.1';
+        const open = options.open !== false;
+
+        await startStudio({
+          knex,
+          port,
+          host,
+          open,
+          silent: false,
+        });
+
+        // Keep process open until interrupted
+        const cleanup = async () => {
+          console.log('\n🛑 Stopping DB Studio...');
+          try {
+            await knex.destroy();
+          } catch (_) {}
+          process.exit(0);
+        };
+
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+      } catch (err) {
+        console.error('❌ Failed to start DB Studio:', err.message);
+        try {
+          await knex.destroy();
+        } catch (_) {}
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+};

package/bin/commands/deploy-check.js

@@ -10,6 +10,26 @@ const fs = require('fs');
 const path = require('path');
 const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
 
+function resolveProjectDbConfig(dir, targetEnv) {
+  for (const filename of ['webspresso.db.js', 'knexfile.js']) {
+    const full = path.resolve(dir || process.cwd(), filename);
+    if (fs.existsSync(full)) {
+      try {
+        if (fs.statSync(full).isFile()) {
+          const loaded = require(full);
+          const resolved = (loaded && typeof loaded === 'object') ? (loaded[targetEnv] || loaded) : null;
+          if (resolved && typeof resolved === 'object' && resolved.client) {
+            return resolved;
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Known weak secret patterns that should never be used in production
  */
@@ -65,10 +85,14 @@ async function runDeployCheck(options = {}) {
   const successes = [];
   const warnings = [];
   const errors = [];
+  const remediations = [];
 
-  const addPass = (check, message) => successes.push({ check, message });
-  const addWarn = (check, message) => warnings.push({ check, message });
-  const addError = (check, message) => errors.push({ check, message });
+  const addPass = (check, message) => successes.push({ check, title: check, message });
+  const addWarn = (check, message) => warnings.push({ check, title: check, message });
+  const addError = (check, message) => errors.push({ check, title: check, message });
+  const addRemediation = (action) => {
+    if (!remediations.includes(action)) remediations.push(action);
+  };
 
   // Load environment variables from process.env and local .env files
   const localEnv = {
@@ -77,6 +101,25 @@ async function runDeployCheck(options = {}) {
     ...process.env,
   };
 
+  // ----------------------------------------------------
+  // Target Platform Detection
+  // ----------------------------------------------------
+  let targetPlatform = (options.platform || 'auto').toLowerCase();
+  const isPlatformAuto = targetPlatform === 'auto';
+  if (isPlatformAuto) {
+    if (localEnv.K_SERVICE || fs.existsSync(path.join(cwd, 'cloudbuild.yaml')) || fs.existsSync(path.join(cwd, '.gcloudignore'))) {
+      targetPlatform = 'cloudrun';
+    } else if (localEnv.AWS_EXECUTION_ENV || localEnv.AWS_LAMBDA_FUNCTION_NAME || fs.existsSync(path.join(cwd, 'apprunner.yaml')) || fs.existsSync(path.join(cwd, 'ecs-task-definition.json'))) {
+      targetPlatform = 'aws';
+    } else if (fs.existsSync(path.join(cwd, 'wrangler.toml'))) {
+      targetPlatform = 'cloudflare';
+    } else if (fs.existsSync(path.join(cwd, 'Dockerfile'))) {
+      targetPlatform = 'docker';
+    } else {
+      targetPlatform = 'generic';
+    }
+  }
+
   // ----------------------------------------------------
   // 1. Project & Server Basics
   // ----------------------------------------------------
@@ -194,22 +237,63 @@ async function runDeployCheck(options = {}) {
     const files = fs.readdirSync(migrationsDir).filter((f) => f.endsWith('.js') || f.endsWith('.ts'));
     addPass('Migrations', `Found ${files.length} migration file(s) in migrations/`);
 
-    // Try verifying migration status if db config exists
-    const dbConfig = resolveDbConfigIfExists(cwd, targetEnv);
+    // Try verifying migration status and connection pool if db config exists
+    const dbConfig = resolveProjectDbConfig(cwd, targetEnv);
     if (dbConfig) {
+      // Check connection pool for serverless/container scale-out
+      const isSqlite = dbConfig.client === 'better-sqlite3' || dbConfig.client === 'sqlite3';
+      if (!isSqlite && (dbConfig.client === 'pg' || dbConfig.client === 'mysql2' || dbConfig.client === 'mysql')) {
+        const pool = dbConfig.pool || {};
+        if (pool.max > 10) {
+          addWarn('DB Connection Pool', `DB pool max is ${pool.max}. Large pools per container can exhaust database connections when autoscaling. Consider max <= 5 or an external pooler.`);
+        } else if (pool.serverless || (pool.min === 0 && (pool.max || 5) <= 5)) {
+          addPass('DB Connection Pool', `Database connection pool configured for serverless scaling (min: ${pool.min ?? 0}, max: ${pool.max ?? 5})`);
+        }
+
+        if ((localEnv.K_SERVICE || localEnv.AWS_EXECUTION_ENV || pool.serverless) && pool.min > 0) {
+          addWarn('DB Connection Pool', `DB pool min is ${pool.min}. For serverless scale-to-zero, min: 0 is recommended so idle containers release connections.`);
+        }
+      }
+
       try {
-        const db = createDbInstance(dbConfig);
-        const status = await db.knex.migrate.status();
-        if (status > 0) {
-          addWarn('Pending Migrations', `There are ${status} pending database migration(s) to run (run: npx webspresso db:migrate)`);
-        } else if (status === 0) {
-          addPass('Pending Migrations', 'All database migrations are applied up to date');
+        const db = createDbInstance(dbConfig, targetEnv);
+        const knexInstance = db.knex || db;
+        if (knexInstance?.migrate?.status) {
+          const status = await knexInstance.migrate.status();
+          if (status > 0) {
+            addWarn('Pending Migrations', `There are ${status} pending database migration(s) to run (run: npx webspresso db:migrate)`);
+          } else if (status === 0) {
+            addPass('Pending Migrations', 'All database migrations are applied up to date');
+          }
+        }
+        if (knexInstance && typeof knexInstance.destroy === 'function') {
+          await knexInstance.destroy();
         }
-        await db.knex.destroy();
       } catch (err) {
         addWarn('Database Connectivity', `Could not check migration status: ${err.message}`);
       }
     }
+
+    // Check cloud migration job setup for Cloud Run or AWS
+    if (targetPlatform === 'cloudrun') {
+      const hasJob = fs.existsSync(path.join(cwd, 'cloudrun-job.yaml')) ||
+                     fs.existsSync(path.join(cwd, 'deploy-cloudrun-migration.sh')) ||
+                     (fs.existsSync(path.join(cwd, 'cloudbuild.yaml')) && fs.readFileSync(path.join(cwd, 'cloudbuild.yaml'), 'utf8').includes('run jobs'));
+      if (hasJob) {
+        addPass('Cloud Migration Strategy', 'Cloud Run migration job configuration found');
+      } else {
+        addWarn('Cloud Migration Strategy', 'Running migrations inside scaled web containers can cause race conditions. Scaffold an isolated Cloud Run Job: npx webspresso add:migration-job --platform cloudrun');
+      }
+    } else if (targetPlatform === 'aws') {
+      const hasEcsTask = fs.existsSync(path.join(cwd, 'ecs-migration-task.json')) ||
+                         fs.existsSync(path.join(cwd, 'deploy-aws-migration.sh')) ||
+                         (fs.existsSync(path.join(cwd, 'apprunner.yaml')) && fs.readFileSync(path.join(cwd, 'apprunner.yaml'), 'utf8').includes('db:migrate'));
+      if (hasEcsTask) {
+        addPass('Cloud Migration Strategy', 'AWS ECS Task or App Runner pre-deploy migration configuration found');
+      } else {
+        addWarn('Cloud Migration Strategy', 'Recommend running migrations as an isolated ECS Task or App Runner pre-run: npx webspresso add:migration-job --platform aws');
+      }
+    }
   } else {
     addPass('Migrations', 'No migrations directory (skipping migration status check)');
   }
@@ -249,13 +333,146 @@ async function runDeployCheck(options = {}) {
     }
   }
 
+  // ----------------------------------------------------
+  // 8. Stateless Scale-Out & Session Store
+  // ----------------------------------------------------
+  const hasRedis = Boolean(localEnv.REDIS_URL || localEnv.SESSION_STORE === 'redis');
+  if (hasRedis) {
+    addPass('Distributed Session Store', `Distributed session store configured for scale-out (${localEnv.SESSION_STORE || 'Redis'})`);
+  } else if (targetEnv === 'production' && serverCode && (serverCode.includes('auth') || serverCode.includes('session'))) {
+    addWarn('Distributed Session Store', 'In-memory session store detected in production. For stateless scale-out (Cloud Run, AWS ECS/Fargate, Kubernetes), configure a distributed store via REDIS_URL=redis://... or SESSION_STORE=redis.');
+  }
+
+  // ----------------------------------------------------
+  // 9. Platform-Specific Cloud Preflight
+  // ----------------------------------------------------
+  const dbConfig = resolveProjectDbConfig(cwd, targetEnv);
+  const isSqlite = !dbConfig || dbConfig.client === 'better-sqlite3' || dbConfig.client === 'sqlite3';
+
+  // 9.1 Ephemeral Storage (Database & Uploads)
+  if (isSqlite && (targetPlatform === 'cloudrun' || targetPlatform === 'aws')) {
+    const pName = targetPlatform === 'cloudrun' ? 'Google Cloud Run' : 'AWS (App Runner / ECS)';
+    const dbRec = targetPlatform === 'cloudrun' ? 'Google Cloud SQL (PostgreSQL/MySQL)' : 'AWS RDS / Aurora';
+    addWarn(
+      'Ephemeral Storage (Database)',
+      `${pName} uses an ephemeral container filesystem. Local SQLite databases will be lost on scale-down or redeploy. Migrate to ${dbRec}.`
+    );
+    addRemediation(`Configure managed database: Use ${dbRec} via webspresso.db.js or DATABASE_URL`);
+  }
+
+  if (serverCode && (serverCode.includes("storage: 'local'") || serverCode.includes('uploadPlugin({') || serverCode.includes('uploadPlugin()'))) {
+    const hasCloudStorage = serverCode.includes("storage: 'gcs'") || serverCode.includes("storage: 's3'") || serverCode.includes("storage: 'cloudflare'");
+    if (!hasCloudStorage && (targetPlatform === 'cloudrun' || targetPlatform === 'aws')) {
+      const pStorage = targetPlatform === 'cloudrun' ? 'Google Cloud Storage (GCS)' : 'AWS S3';
+      addWarn(
+        'Ephemeral Storage (Uploads)',
+        `Local disk file upload storage detected. Container restarts on ${targetPlatform === 'cloudrun' ? 'Cloud Run' : 'AWS'} will cause uploaded files to be lost. Configure ${pStorage}.`
+      );
+      addRemediation(`Configure ${pStorage}: uploadPlugin({ storage: '${targetPlatform === 'cloudrun' ? 'gcs' : 's3'}' })`);
+    }
+  }
+
+  // 9.2 Shutdown Timeout Alignment
+  if (targetPlatform === 'cloudrun') {
+    if (serverCode) {
+      const match = serverCode.match(/timeout:\s*(\d+)/);
+      if (match) {
+        const timeoutMs = parseInt(match[1], 10);
+        if (timeoutMs > 10000) {
+          addWarn('Shutdown Timeout Alignment', `Webspresso shutdown timeout (${timeoutMs}ms) exceeds Cloud Run default SIGTERM deadline (10000ms). Container may be forcibly SIGKILLed before draining.`);
+          addRemediation('Set shutdown timeout <= 10000ms in createApp({ server: { shutdown: { timeout: 9000 } } })');
+        } else {
+          addPass('Shutdown Timeout Alignment', `Shutdown timeout (${timeoutMs}ms) matches Cloud Run 10s SIGTERM deadline`);
+        }
+      } else {
+        addPass('Shutdown Timeout Alignment', 'Default shutdown timeout (10s) compatible with Cloud Run SIGTERM deadline');
+      }
+    }
+  } else if (targetPlatform === 'aws') {
+    addPass('Shutdown Timeout Alignment', 'Default shutdown timeout (10s) well within AWS ECS 30s stopTimeout');
+  }
+
+  // 9.3 Platform Artifacts & Secrets Inspection
+  if (targetPlatform === 'cloudrun') {
+    const gcloudignorePath = path.join(cwd, '.gcloudignore');
+    if (fs.existsSync(gcloudignorePath)) {
+      const gignore = fs.readFileSync(gcloudignorePath, 'utf8');
+      if (!gignore.includes('.env')) {
+        addError('Google Cloud Ignore', '.env is NOT excluded in .gcloudignore! Secrets may leak into Google Cloud Build.');
+        addRemediation('Add .env to .gcloudignore');
+      } else {
+        addPass('Google Cloud Ignore', '.gcloudignore present and properly excludes .env');
+      }
+    } else {
+      addWarn('Google Cloud Ignore', '.gcloudignore not found (recommend running: npx webspresso add:cloudrun)');
+      addRemediation('Generate Cloud Run configuration: npx webspresso add:cloudrun');
+    }
+
+    const cloudbuildPath = path.join(cwd, 'cloudbuild.yaml');
+    if (fs.existsSync(cloudbuildPath)) {
+      addPass('Cloud Build Pipeline', 'cloudbuild.yaml CI/CD pipeline found');
+    } else {
+      addWarn('Cloud Build Pipeline', 'cloudbuild.yaml not found (run: npx webspresso add:cloudrun)');
+    }
+
+    if (serverCode) {
+      if (serverCode.includes('process.env.PORT') || serverCode.includes('PORT')) {
+        addPass('Cloud Run PORT Binding', 'Binds to dynamic process.env.PORT (required for Cloud Run 8080)');
+      } else {
+        addWarn('Cloud Run PORT Binding', 'Ensure server listens on process.env.PORT (Cloud Run assigns port 8080)');
+        addRemediation('Listen on process.env.PORT: app.listen(process.env.PORT || 3000)');
+      }
+    }
+  } else if (targetPlatform === 'aws') {
+    const apprunnerPath = path.join(cwd, 'apprunner.yaml');
+    const ecsTaskPath = path.join(cwd, 'ecs-task-definition.json');
+
+    if (fs.existsSync(apprunnerPath)) {
+      addPass('AWS App Runner Config', 'apprunner.yaml found');
+    }
+    if (fs.existsSync(ecsTaskPath)) {
+      try {
+        const ecsTask = JSON.parse(fs.readFileSync(ecsTaskPath, 'utf8'));
+        if (ecsTask.containerDefinitions?.[0]?.logConfiguration?.logDriver === 'awslogs') {
+          addPass('AWS CloudWatch Logs', 'CloudWatch logDriver (awslogs) configured in ECS task definition');
+        }
+        addPass('AWS ECS Task Definition', 'ecs-task-definition.json found and valid JSON');
+      } catch (err) {
+        addError('AWS ECS Task Definition', `ecs-task-definition.json is invalid JSON: ${err.message}`);
+      }
+    }
+
+    if (!fs.existsSync(apprunnerPath) && !fs.existsSync(ecsTaskPath)) {
+      addWarn('AWS Configuration', 'Neither apprunner.yaml nor ecs-task-definition.json found');
+      addRemediation('Generate AWS configuration: npx webspresso add:aws');
+    }
+  } else if (targetPlatform === 'cloudflare') {
+    const wranglerPath = path.join(cwd, 'wrangler.toml');
+    if (fs.existsSync(wranglerPath)) {
+      const wrangler = fs.readFileSync(wranglerPath, 'utf8');
+      if (wrangler.includes('nodejs_compat')) {
+        addPass('Cloudflare Worker Config', 'wrangler.toml found with nodejs_compat flag');
+      } else {
+        addWarn('Cloudflare Worker Config', 'wrangler.toml missing compatibility_flags = ["nodejs_compat"]');
+        addRemediation('Add compatibility_flags = ["nodejs_compat"] to wrangler.toml');
+      }
+    } else {
+      addWarn('Cloudflare Worker Config', 'wrangler.toml not found (run: npx webspresso add:cloudflare)');
+      addRemediation('Generate Cloudflare Worker files: npx webspresso add:cloudflare');
+    }
+  }
+
   const passed = errors.length === 0;
 
   return {
     passed,
+    platform: targetPlatform,
+    isPlatformAuto,
     successes,
+    passes: successes,
     warnings,
     errors,
+    remediations,
   };
 }
 
@@ -269,6 +486,7 @@ function registerCommand(program) {
     .alias('check:deploy')
     .description('Run production preflight check (secrets, container hardening, database, and optimizations)')
     .option('-e, --env <environment>', 'Target environment to evaluate (default: production)', 'production')
+    .option('-p, --platform <platform>', 'Target cloud platform (cloudrun, aws, cloudflare, docker, or auto)', 'auto')
     .option('--strict', 'Fail with exit code 1 if any warnings are detected', false)
     .option('--json', 'Output preflight results as JSON', false)
     .action(async (...actionArgs) => {
@@ -280,6 +498,7 @@ function registerCommand(program) {
       const result = await runDeployCheck({
         cwd: process.cwd(),
         env: options.env || 'production',
+        platform: options.platform || 'auto',
       });
 
       if (options.json) {
@@ -291,7 +510,9 @@ function registerCommand(program) {
       }
 
       console.log('\n🚀 Webspresso Production Deployment Preflight');
-      console.log('=============================================\n');
+      console.log('=============================================');
+      console.log(`Target Platform : ${result.platform.toUpperCase()} ${result.isPlatformAuto ? '(auto-detected)' : ''}`);
+      console.log(`Environment     : ${options.env || 'production'}\n`);
 
       if (result.successes.length > 0) {
         console.log('Passed Checks:');
@@ -317,6 +538,14 @@ function registerCommand(program) {
         console.log('');
       }
 
+      if (result.remediations && result.remediations.length > 0) {
+        console.log('Recommended Actions:');
+        for (const rem of result.remediations) {
+          console.log(`  👉 ${rem}`);
+        }
+        console.log('');
+      }
+
       console.log('---------------------------------------------');
       console.log(`Summary: ${result.successes.length} passed, ${result.warnings.length} warning(s), ${result.errors.length} error(s).\n`);
 

package/bin/commands/dev.js

@@ -31,7 +31,7 @@ function registerCommand(program) {
   program
     .command('dev')
     .description('Start development server')
-    .option('-p, --port <port>', 'Port number', '3000')
+    .option('-p, --port <port>', 'Port number', '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) => {

package/bin/commands/export.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Webspresso CLI Export Command
+ * Prerender pages into static HTML files for static hosting
+ * @module bin/commands/export
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { exportStaticSite } = require('../../core/export');
+
+function registerCommand(program) {
+  program
+    .command('export')
+    .description('Export and prerender application pages into static HTML files for Cloudflare Pages, S3, or Vercel')
+    .option('-o, --out <dir>', 'Output directory for exported files', 'dist')
+    .option('-b, --base-url <url>', 'Base URL for canonical links and sitemap.xml')
+    .option('-c, --clean', 'Clean output directory before export', true)
+    .option('--no-clean', 'Do not clean output directory before export')
+    .option('--no-assets', 'Skip copying public static assets')
+    .option('--no-clean-urls', 'Generate "path.html" instead of "path/index.html"')
+    .option('--sitemap', 'Generate sitemap.xml for prerendered routes', false)
+    .option('--concurrency <n>', 'Number of concurrent render requests', '5')
+    .option('--silent', 'Suppress log output', false)
+    .action(async (options = {}) => {
+      const cwd = process.cwd();
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) {
+        console.error('❌ Not a Webspresso project! Run this command in your project directory.');
+        process.exit(1);
+      }
+
+      const outDir = options.out || 'dist';
+      const clean = options.clean !== false;
+      const cleanUrls = options.cleanUrls !== false;
+      const copyAssets = options.assets !== false;
+      const sitemap = options.sitemap || Boolean(options.baseUrl);
+      const baseUrl = options.baseUrl;
+      const concurrency = parseInt(options.concurrency, 10) || 5;
+      const silent = options.silent === true;
+
+      // Check if project has a custom server.js
+      let serverConfig = {};
+      const serverJsPath = path.join(cwd, 'server.js');
+      if (fs.existsSync(serverJsPath)) {
+        try {
+          // If server.js exports a function or config object
+          const srv = require(serverJsPath);
+          if (srv && typeof srv === 'object') {
+            serverConfig = srv;
+          }
+        } catch (_) {}
+      }
+
+      try {
+        const result = await exportStaticSite({
+          cwd,
+          outDir,
+          clean,
+          cleanUrls,
+          copyAssets,
+          sitemap,
+          baseUrl,
+          concurrency,
+          silent,
+          serverConfig,
+        });
+
+        if (result.errors && result.errors.length > 0) {
+          console.error(`⚠️  Static export completed with ${result.errors.length} error(s).`);
+          process.exitCode = 1;
+        } else {
+          if (!silent) {
+            console.log(`✅ Static export succeeded: ${result.rendered} page(s) ready in "${outDir}".`);
+          }
+        }
+      } catch (err) {
+        console.error('❌ Static export failed:', err.message);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+};

package/bin/commands/new.js

@@ -312,10 +312,10 @@ module.exports = { loadEnv };
 
 const envSchema = z.object({
   NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  PORT: z.coerce.number().int().positive().default(3000),
+  PORT: z.coerce.number().int().positive().default(7331),
   DEFAULT_LOCALE: z.string().min(1).default('en'),
   SUPPORTED_LOCALES: z.string().min(1).default('en,de'),
-  BASE_URL: z.string().url().default('http://localhost:3000'),
+  BASE_URL: z.string().url().default('http://localhost:7331'),
   DATABASE_URL: z.string().optional(),
 });
 
@@ -382,11 +382,11 @@ app.listen(env.PORT, () => {
       
       // Create .env.example (see config/load-env.js for merge order)
       let envExample = `# Copy to .env and adjust. Optional overrides: .env.local, .env.<NODE_ENV>, .env.<NODE_ENV>.local
-PORT=3000
+PORT=7331
 NODE_ENV=development
 DEFAULT_LOCALE=en
 SUPPORTED_LOCALES=en,de
-BASE_URL=http://localhost:3000
+BASE_URL=http://localhost:7331
 `;
       
       if (useDatabase && databaseType) {
@@ -645,7 +645,7 @@ cp .env.example .env
 npm run dev
 \`\`\`
 
-Visit http://localhost:3000
+Visit http://localhost:7331
 
 ## Configuration