webspresso 0.0.103 → 0.0.105

package/.agents/ORM.md

@@ -116,11 +116,33 @@ const product = await productRepo.findById(1);
 const activeProducts = await productRepo.find({ active: true });
 const singleProduct = await productRepo.findOne({ slug: 'laptop' });
 
-// 2. Insert, Update, Delete
+// 2. Insert, Update, Delete & Batch Operations
 const newProduct = await productRepo.create({ name: 'Laptop', price: 999, category_id: 1 });
 const updated = await productRepo.update(newProduct.id, { price: 899 });
 await productRepo.delete(newProduct.id); // Soft or hard delete based on model config
 
+// 2.1 Batch Insert (Auto-Chunked with SQL Variable Limit Protection)
+// Automatically chunks rows to stay safely within SQLite/Postgres parameter limits (prevents 'too many SQL variables' error)
+// and executes inside an atomic transaction (all succeed or all rollback).
+const products = await productRepo.createBatch([
+  { name: 'Tablet', price: 499, category_id: 1 },
+  { name: 'Phone', price: 799, category_id: 1 },
+], { chunkSize: 500, transaction: true });
+
+// 2.2 Upsert & Batch Upsert (onConflict Merge)
+// Inserts new records or updates existing records on conflict target (e.g. sku or primaryKey)
+const upserted = await productRepo.upsert(
+  { sku: 'SKU-001', name: 'Keyboard', price: 59 },
+  'sku',
+  ['name', 'price']
+);
+
+const batchUpserted = await productRepo.upsertBatch(
+  catalogItems,
+  'sku',
+  { updateColumns: ['name', 'price', 'updated_at'] }
+);
+
 // 3. Query Builder & Pagination
 const result = await productRepo.query()
   .where('price', '>', 500)
@@ -468,5 +490,137 @@ const user = await UserFactory.create({ db });
 const admins = await UserFactory.count(3).apply('admin').create({ db });
 ```
 
+---
+
+## 12. Dynamic Model Row-Level Security (RLS)
+
+Webspresso ORM features zero-dependency, declarative Row-Level Security (RLS) directly on model definitions, ensuring data isolation across users, organizations, and multi-tenant systems.
+
+### 12.1 Declaring RLS Policies on Models
+
+Models declare row-level access rules with `rls` inside `defineModel`:
+
+```javascript
+const { defineModel, zdb } = require('webspresso');
+
+module.exports = defineModel({
+  name: 'Document',
+  table: 'documents',
+  schema: zdb.schema({
+    id: zdb.id(),
+    user_id: zdb.integer(),
+    tenant_id: zdb.string().optional(),
+    title: zdb.string(),
+    content: zdb.text(),
+    status: zdb.string().default('draft'),
+    is_public: zdb.boolean().default(false),
+  }),
+  rls: {
+    // Shorthand: automatically scopes queries and mutations to user.id
+    userColumn: 'user_id',
+
+    // Multi-tenant shorthand: scopes to user.tenant_id or scopeContext.tenantId
+    tenantColumn: 'tenant_id',
+
+    // Role-based bypass: admins and superadmins bypass RLS by default
+    bypassRoles: ['admin', 'superadmin'],
+
+    // Granular action rules:
+    // Read / Select: public documents are visible to anyone, drafts only to author
+    read: (user, qb) => {
+      if (!user) return { is_public: true };
+      return (q) => q.where('user_id', user.id).orWhere('is_public', true);
+    },
+
+    // Update: only allow modifying draft documents
+    update: (user, qb) => {
+      if (!user) return false;
+      return (q) => q.where('user_id', user.id).where('status', 'draft');
+    },
+
+    // Delete: completely disabled or owner only
+    delete: (user, qb) => {
+      if (!user) return false;
+      return { user_id: user.id };
+    },
+
+    // Create: auto-populates user_id, validates permissions or modifies payload
+    create: (user, data) => {
+      if (!user) return false; // Throws UnauthorizedError/ForbiddenError
+      return { status: 'draft' }; // Enforce default state
+    },
+  },
+});
+```
+
+### 12.2 Scoping Repositories and Query Builders
+
+Repositories and query builders provide fluent scoping methods:
+
+```javascript
+const repo = db.getRepository('Document');
+
+// Scoped to specific user:
+const userRepo = repo.forUser(currentUser);
+const myDocs = await userRepo.findAll();
+const myDoc = await userRepo.findById(docId); // null if not owned
+
+// Auto-populates user_id and rejects spoofed user IDs:
+const newDoc = await userRepo.create({ title: 'My Report' });
+
+// QueryBuilder chaining:
+const count = await repo.query().forUser(currentUser).where('status', 'draft').count();
+const paged = await repo.query().forUser(currentUser).paginate(1, 10);
+
+// Explicit bypass (system/admin operations):
+const allDocs = await repo.withoutRls().findAll();
+const total = await repo.query().withoutRls().count();
+
+// Multi-tenant scoping:
+const tenantRepo = repo.forTenant('org_acme');
+```
+
+### 12.3 Database Scoped Accessors
+
+```javascript
+// Scoped database instance:
+const userDb = db.forUser(currentUser);
+const docs = await userDb.getRepository('Document').findAll();
+const drafts = await userDb.query('Document').where('status', 'draft').list();
+
+// Ambient transaction scoping:
+await db.transaction(async (trx) => {
+  const noteRepo = trx.forUser(currentUser).getRepository('Document');
+  await noteRepo.create({ title: 'Transaction Document' });
+});
+```
+
+### 12.4 Automatic Express Integration (`rlsPlugin`)
+
+Register `rlsPlugin()` to automatically wrap `req.db.getRepository()` with `req.user` in API endpoints and SSR loaders:
+
+```javascript
+const { createApp, rlsPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    rlsPlugin({
+      bypassRoles: ['admin', 'superadmin'], // default
+      getUser: (req) => req.user,           // default
+    }),
+  ],
+});
+
+// Inside any API route (pages/api/documents.get.js):
+module.exports = defineApi({
+  handler: async (req, res) => {
+    // req.db.getRepository('Document') is automatically scoped to req.user!
+    const docs = await req.db.getRepository('Document').findAll();
+    return res.json(docs);
+  },
+});
+```
+
+
 
 

package/.agents/PLUGINS.md

@@ -692,3 +692,31 @@ Zero-dependency on-demand plugin hydration wrapper that defers heavy plugin init
   - Mounts a lightweight Express router proxy at `prefix`.
   - Stubs placeholder services into `ServiceRegistry` and proxy helpers into Nunjucks context.
   - Intercepts incoming requests/calls, executes the plugin factory function, runs `register(ctx)` and `onRoutesReady(ctx)`, replaces proxies seamlessly with the real router/services, and forwards the initial call with zero dropped requests.
+
+### 2.21 `rlsPlugin` (`plugins/rls`)
+Zero-dependency Dynamic Model Row-Level Security (RLS) plugin that bridges request authentication (`req.user`, `req.auth`, `req.tenantId`) to ORM repositories with automatic query scoping, role-based bypass, and route-level overrides.
+- **Why**: Eliminates manual `where({ user_id: req.user.id })` boilerplate across all API endpoints, prevents accidental cross-tenant/cross-user data leakage, and provides declarative data access boundaries.
+- **Options**:
+  - `bypassRoles`: Global roles that bypass RLS across all models (default: `['admin', 'superadmin']`). Set to `false` to disable.
+  - `getUser`: Custom extractor for current user from `req` (default: `req.user || req.adminUser || req.auth?.user`).
+  - `getTenantId`: Custom extractor for current tenant ID from `req` (default: `req.tenantId || req.user?.tenant_id`).
+  - `global`: Mount global middleware wrapping `req.db` (default: `true`).
+  - `enabled`: Toggle RLS plugin active state (default: `true`).
+- **Usage**:
+  ```javascript
+  const { createApp, rlsPlugin } = require('webspresso');
+
+  const app = createApp({
+    plugins: [
+      rlsPlugin({
+        bypassRoles: ['admin', 'superadmin'],
+      }),
+    ],
+  });
+  ```
+- **How It Works**:
+  - Automatically wraps `req.db.getRepository()` and `req.db.query()` with the active `user` and `tenantId`.
+  - Admins bypass filters automatically unless model specifies `bypassRoles: false`.
+  - Endpoints can explicitly bypass RLS when needed via `req.db.getRepository('Model').withoutRls()`.
+  - Named middleware `middleware: ['rls']` available for selective route application.
+

package/.agents/RESILIENCE.md

@@ -0,0 +1,235 @@
+# Enterprise Resilience, Circuit Breaker & Retry Engine (`core/resilience`)
+
+Webspresso includes a zero-dependency, enterprise-grade resilience and fault tolerance engine built directly on native Node.js primitives (`events`, `perf_hooks`, `async_hooks`). It prevents cascading downstream outages, protects critical services, and recovers automatically from transient network spikes.
+
+---
+
+## 🚦 Architectural Overview
+
+```
+                      ┌───────────────────────────────────────┐
+                      │            Incoming Request           │
+                      └───────────────────┬───────────────────┘
+                                          │
+                                          ▼
+                      ┌───────────────────────────────────────┐
+                      │    Circuit Breaker (Fast Fail / OPEN) │
+                      └───────┬───────────────────────▲───────┘
+                     (Closed) │                       │ (Trips on failure)
+                              ▼                       │
+                      ┌───────────────────────────────┴───────┐
+                      │    Retry Engine (Backoff + Jitter)    │
+                      └───────┬───────────────────────▲───────┘
+                     (Attempt)│                       │ (Transient Error)
+                              ▼                       │
+                      ┌───────────────────────────────┴───────┐
+                      │   Service Handler / Remote Upstream   │
+                      └───────────────────────────────────────┘
+```
+
+1. **State Machine (`CircuitBreaker`)**:
+   - `CLOSED`: Normal operation. Requests pass through. Failures are tracked in a rolling time window.
+   - `OPEN`: Downstream is degraded/unhealthy. Subsequent calls **fail fast immediately** with `CircuitBreakerOpenError` (HTTP 503) without hitting the downstream resource, or return a predefined `fallback`.
+   - `HALF_OPEN`: Trial recovery state entered automatically once `resetTimeout` elapses. A controlled number of probe requests (`successThreshold`) test the downstream. If they succeed, the breaker resets to `CLOSED`. If any probe fails, it trips back to `OPEN`.
+
+2. **Retry with Exponential Backoff & Full Jitter (`retry`, `withRetry`)**:
+   - Automatically retries transient network errors (`ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`, 429 Too Many Requests, and 5xx Gateway errors).
+   - Skips client-side 4xx errors (e.g. 400 Bad Request, 401, 403, 404, 422) since retrying client errors produces identical failures.
+   - Full jitter prevents synchronization spikes (the "thundering herd" problem) against recovering third-party services.
+   - Respects `AbortSignal` for cancellation.
+
+3. **Seamless Services Layer Integration**:
+   - Declare `circuitBreaker` and `retry` declaratively inside `defineService({ ... })`.
+   - Automatically protects service calls from SSR pages, API routes, or worker jobs.
+
+---
+
+## 🛠️ Quick Start & Usage Examples
+
+### 1. Declarative Service Protection (`defineService`)
+
+```javascript
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  // Automatic retry on transient network errors
+  retry: {
+    retries: 3,
+    delay: '100ms',
+    factor: 2,
+    jitter: true,
+  },
+
+  // Circuit breaker with fast-fail and graceful fallback
+  circuitBreaker: {
+    failureThreshold: 3,          // Open after 3 consecutive failures
+    failureRateThreshold: 0.5,    // Or if >= 50% fail in rolling window
+    rollingWindow: '10s',         // 10-second sample window
+    resetTimeout: '15s',          // Stay open for 15s before trial recovery
+    timeout: '3s',                // Per-call execution timeout (ms or string)
+    fallback: (err, input) => {
+      // Graceful fallback returned when OPEN or when all retries fail
+      return { fromCache: true, id: input.id, data: null, degraded: true };
+    },
+  },
+
+  schema: ({ z }) => ({
+    id: z.string(),
+  }),
+
+  handler: async (input, ctx) => {
+    // Call external payment or inventory API
+    const response = await fetch(`https://api.external.com/items/${input.id}`);
+    if (!response.ok) {
+      const err = new Error(`Upstream API responded with status ${response.status}`);
+      err.statusCode = response.status;
+      throw err;
+    }
+    return await response.json();
+  },
+});
+```
+
+### 2. Standalone Circuit Breaker Usage
+
+```javascript
+const { createCircuitBreaker } = require('webspresso');
+
+const paymentBreaker = createCircuitBreaker({
+  name: 'stripe-gateway',
+  failureThreshold: 5,
+  resetTimeout: '30s',
+  timeout: '5s',
+  fallback: (err) => {
+    return { status: 'queued_offline', message: 'Payment queued for processing' };
+  },
+});
+
+// Execute async function wrapped by breaker
+const result = await paymentBreaker.execute(async () => {
+  return await stripeClient.charges.create({ ... });
+});
+
+// Or wrap a function
+const safeCharge = paymentBreaker.wrap(chargeFunction);
+await safeCharge(args);
+```
+
+### 3. Standalone Retry Engine (`retry`)
+
+```javascript
+const { retry, isTransientError } = require('webspresso');
+
+const data = await retry(
+  async (attempt) => {
+    return await fetchRemoteData();
+  },
+  {
+    retries: 3,
+    delay: 200,          // Initial 200ms delay
+    factor: 2,           // 200ms -> 400ms -> 800ms
+    jitter: true,        // Randomized jitter
+    onRetry: ({ attempt, error, delayMs }) => {
+      console.warn(`Retry attempt ${attempt} after error: ${error.message} (waiting ${delayMs}ms)`);
+    },
+  }
+);
+```
+
+### 4. Accessing Breakers & Retry from Route Handlers & Context
+
+In API routes and SSR loaders:
+
+```javascript
+// Inside API route handler or SSR loader
+export async function handler(req, res) {
+  // Named circuit breaker from central registry
+  const crmBreaker = req.breaker('hubspot-api', { failureThreshold: 3 });
+
+  // Retry engine available on req
+  const lead = await req.retry(async () => {
+    return await pushLeadToCrm(req.body);
+  }, { retries: 2 });
+
+  return res.json(lead);
+}
+```
+
+In services handlers (`ctx`):
+
+```javascript
+module.exports = defineService({
+  handler: async (input, ctx) => {
+    // Access circuit breaker
+    const breaker = ctx.breaker('custom-api');
+    
+    // Access retry helper
+    return await ctx.retry(async (attempt) => {
+      return await queryDownstream();
+    });
+  },
+});
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+### `CircuitBreakerOptions`
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `'default'` | Identifier for logging and registry lookup. |
+| `failureThreshold` | `number` | `5` | Consecutive failures before opening circuit. |
+| `failureRateThreshold` | `number` | `null` | Failure rate (0.01 - 1.0) in rolling window to open circuit (e.g. `0.5` = 50%). |
+| `minimumRequests` | `number` | `5` | Minimum calls in rolling window before failure rate check activates. |
+| `rollingWindow` | `number \| string` | `10000` (10s) | Rolling time window for metrics sample pruning. |
+| `successThreshold` | `number` | `2` | Consecutive successes in `HALF_OPEN` state required to close circuit. |
+| `resetTimeout` | `number \| string` | `10000` (10s) | Duration circuit stays `OPEN` before attempting `HALF_OPEN` probe. |
+| `timeout` | `number \| string` | `0` (disabled) | Per-call execution timeout in milliseconds or duration string (`'2s'`). |
+| `fallback` | `Function` | `null` | Fallback handler `(error, ...args) => any` called when `OPEN` or call fails. |
+| `isFailure` | `Function` | `defaultIsFailure` | Predicate `(error) => boolean`. By default ignores 4xx client errors (except 429). |
+| `onStateChange` | `Function` | `null` | Callback `(fromState, toState, breaker) => void`. |
+
+### `RetryOptions`
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `retries` | `number` | `3` | Maximum retry attempts before giving up. |
+| `delay` / `minTimeout` | `number \| string` | `100` | Initial delay in ms or duration string (`'100ms'`). |
+| `maxTimeout` | `number \| string` | `10000` (10s) | Maximum capped delay for exponential backoff. |
+| `factor` | `number` | `2` | Exponential backoff multiplier. |
+| `jitter` | `boolean` | `true` | Apply full randomized jitter (`Math.random() * delay`). |
+| `shouldRetry` | `Function` | `isTransientError` | Predicate `(error, attempt) => boolean`. Retries network/5xx/429 errors. |
+| `onRetry` | `Function` | `null` | Hook `({ attempt, error, delayMs }) => void`. |
+| `signal` | `AbortSignal` | `null` | Optional signal to cancel pending retry delays immediately. |
+
+---
+
+## 📊 Telemetry & Monitoring
+
+Inspect health and failure metrics at any time:
+
+```javascript
+// Breaker instance stats
+const stats = breaker.getStats();
+// {
+//   name: 'stripe-gateway',
+//   state: 'CLOSED',
+//   totalCalls: 120,
+//   successfulCalls: 118,
+//   failedCalls: 2,
+//   rejectedCalls: 0,
+//   timedOutCalls: 0,
+//   fallbackCalls: 0,
+//   consecutiveFailures: 0,
+//   consecutiveSuccesses: 118,
+//   failureRate: 0.016,
+//   lastFailureTime: 1713430000000,
+//   lastSuccessTime: 1713430001000,
+//   lastStateChange: 1713429000000
+// }
+
+// Global registry stats across all breakers
+const allStats = app.breakers.getStats();
+```

package/AGENTS.md

@@ -18,6 +18,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](.agents/AUTH.md) | `core/auth/` |
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](.agents/QUEUE.md) | `jobs/` |
 | **Decoupled Events & Signals** | [`.agents/EVENTS.md`](.agents/EVENTS.md) | `core/events/`, `listeners/` |
+| **Fault Tolerance / Circuit Breaker / Retry** | [`.agents/RESILIENCE.md`](.agents/RESILIENCE.md) | `core/resilience/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -57,6 +58,11 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 - **Framework Exceptions & Central Error Boundary**: Built-in exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`, `ConfigurationError`, `PluginError`, `RouteNotFoundError`) and custom handler hook (`app.setErrorHandler`). Async route handlers automatically propagate rejected promises. Production responses mask 500 stack traces and error details.
 - **Graceful Shutdown & Lifecycle Management**: Configured via `createApp({ server: { shutdown: { enabled: true, mode: 'graceful'|'force', timeout: 10000 } } })`. Socket connection tracking, request draining with `Connection: close`, and reverse-order plugin disposer cleanup.
 - **HTTP Response Compression**: Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })` with Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold buffering (1 KB), and route-level opt-out (`res.compress(false)`).
+- **HTTP 103 Early Hints & Critical Asset Preloading**: Zero-dependency RFC 8288 / RFC 8297 Early Hints dispatcher configured via `createApp({ earlyHints: true })` or per-page `definePage({ earlyHints })`. Emits informational 103 status code with route CSS/JS preloads before async `load()` finishes to minimize TTFB, FCP and LCP, with safe fallback and `res.earlyHints(links)` / `ctx.earlyHints(links)` helpers.
+- **Configurable Payload Size Limits & DoS Protection**: Zero-dependency body limit enforcement configured via `createApp({ limits: { json: '1mb', urlencoded: '1mb', raw: false, text: false, parameterLimit: 1000, captureRawBody: false } })` or shorthand `limits: '5mb'`, with automatic HTTP 413 `PayloadTooLargeError` and HTTP 400 `BadRequestError` mapping, route overrides (`limits.routes`), streaming bypass (`limits.exclude`), and raw body capture on `req.rawBody` for webhook signatures.
+- **Native Cloud & Kubernetes Health & Readiness Probes**: Zero-dependency RFC-compliant liveness (`/healthz`), readiness (`/readyz`), and combined diagnostic (`/health`) endpoints configured via `createApp({ healthCheck: true })`. Includes non-blocking event loop lag monitoring (`perf_hooks.monitorEventLoopDelay`), database/queue connectivity tests, and automatic HTTP 503 draining integration with `ShutdownManager` when pods enter graceful termination.
+- **High-Performance In-Memory LRU & Tagged Cache Engine**: Zero-dependency memory-bounded caching (`core/cache`) configured via `createApp({ cache: { maxEntries: 1000, maxMemoryMb: 50, defaultTtl: '15m' } })` or shorthand `cache: true|false`. Provides O(1) LRU eviction, byte budget constraints preventing OOM, leak-free tag invalidation (`TaggedLruCache`), stampede protection (`getOrSet`), and powers ORM query caching and Zod schema caching.
+- **Enterprise Resilience & Fault Tolerance (Circuit Breaker & Retry Engine)**: Zero-dependency resilience system (`core/resilience`) featuring a three-state `CircuitBreaker` (`CLOSED`, `OPEN`, `HALF_OPEN`), rolling window failure rate tracking, per-call execution timeouts, graceful fallbacks, and an exponential backoff retry engine (`retry`, `withRetry`) with randomized jitter and transient error detection (`ECONNRESET`, 429, 5xx). Seamlessly integrated into the Services Layer (`defineService({ circuitBreaker, retry })`) and exposed via `app.breakers`, `app.getBreaker()`, `req.breaker()`, and `req.retry()`.
 - **Custom Error & 404 Pages**: Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`. Supports template paths (e.g. `notFound: '404.njk'`) or custom handler functions, passing `{ fsy, locale, isDev, url, method }` to templates.
 - **Cold Start & High-Performance Optimizations**:
   - Unified single-pass route scanner (`discoverAppRoutes`).

package/README.md

@@ -22,7 +22,7 @@ cd my-app
 npm run dev
 ```
 
-Open **`http://localhost:3000`** in your browser.
+Open **`http://localhost:7331`** in your browser.
 
 ---
 
@@ -147,7 +147,7 @@ const { app } = createApp({
   },
 });
 
-const PORT = process.env.PORT || 3000;
+const PORT = process.env.PORT || 7331;
 app.listen(PORT, () => {
   console.log(`Server running at http://localhost:${PORT}`);
 });

package/bin/commands/add-docker.js

@@ -56,13 +56,13 @@ function detectDatabase(cwd, pkg = {}) {
  * Generate production-grade multi-stage Dockerfile
  * @param {Object} options
  * @param {string} [options.node='22-alpine']
- * @param {number} [options.port=3000]
+ * @param {number} [options.port=7331]
  * @param {boolean} [options.hasBuildScript=false]
  * @returns {string}
  */
 function generateDockerfile(options = {}) {
   const nodeImage = normalizeNodeVersion(options.node || '22-alpine');
-  const port = options.port || 3000;
+  const port = options.port || 7331;
   const isAlpine = nodeImage.includes('alpine');
 
   return `# ==========================================
@@ -198,7 +198,7 @@ public/uploads/*
  * @param {string} options.appName
  * @param {'postgres'|'mysql'|'sqlite'|'none'} options.db
  * @param {boolean} [options.redis=false]
- * @param {number} [options.port=3000]
+ * @param {number} [options.port=7331]
  * @returns {string}
  */
 function generateDockerCompose(options = {}) {
@@ -206,7 +206,7 @@ function generateDockerCompose(options = {}) {
     appName = 'webspresso-app',
     db = 'sqlite',
     redis = false,
-    port = 3000,
+    port = 7331,
   } = options;
 
   let dbService = '';
@@ -338,7 +338,7 @@ function registerCommand(program) {
     .option('-n, --node <version>', 'Node.js base image version (default: 22-alpine)', '22-alpine')
     .option('-d, --db <type>', 'Database service to configure: postgres, mysql, sqlite, none (auto-detected by default)')
     .option('-r, --redis', 'Include Redis service in docker-compose.yml', false)
-    .option('-p, --port <port>', 'Application container port (default: 3000)', '3000')
+    .option('-p, --port <port>', 'Application container port (default: 7331)', '7331')
     .option('-f, --force', 'Overwrite existing Dockerfile and docker-compose.yml without prompting', false)
     .action(async (...actionArgs) => {
       const cmd = actionArgs[actionArgs.length - 1];
@@ -363,7 +363,7 @@ function registerCommand(program) {
       }
 
       const appName = pkg.name ? pkg.name.replace(/[^a-zA-Z0-9_-]/g, '-') : 'webspresso-app';
-      const port = parseInt(options.port || '3000', 10) || 3000;
+      const port = parseInt(options.port || '7331', 10) || 7331;
       const dbType = options.db || detectDatabase(cwd, pkg);
       const isRedis = Boolean(options.redis);
       const nodeVersion = options.node || '22-alpine';

package/bin/commands/dev.js

@@ -13,8 +13,9 @@ const { spawn } = require('child_process');
 function buildWatchArgs() {
   const args = ['--watch'];
   
-  // Add watch paths for common directories
-  const watchPaths = ['pages', 'models', 'views'];
+  // 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'];
   
   for (const dir of watchPaths) {
     if (fs.existsSync(dir)) {
@@ -30,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/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
 

package/bin/commands/openapi.js

@@ -23,7 +23,7 @@ function registerCommand(program) {
     .option('--title <title>', 'OpenAPI specification title override')
     .option('--api-version <version>', 'OpenAPI specification version override')
     .option('--description <desc>', 'OpenAPI specification description override')
-    .option('--server <url>', 'Default server URL in spec', 'http://localhost:3000')
+    .option('--server <url>', 'Default server URL in spec', 'http://localhost:7331')
     .option('--include-orm', 'Include ORM model schemas in components', false)
     .option('--indent <spaces>', 'JSON indentation spaces', '2')
     .option('-p, --print', 'Print specification JSON to stdout', false)

package/bin/commands/start.js

@@ -10,7 +10,7 @@ function registerCommand(program) {
   program
     .command('start')
     .description('Start production server')
-    .option('-p, --port <port>', 'Port number', '3000')
+    .option('-p, --port <port>', 'Port number', '7331')
     .action((options) => {
       if (!fs.existsSync('server.js')) {
         console.error('❌ server.js not found! Make sure you are in a Webspresso project.');

package/bin/utils/orm-map-html.js

@@ -4,6 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { escapeHtml } = require('../../core/utils/html');
 
 /**
  * @param {object} snapshot - { generatedAt, models }
@@ -661,14 +662,7 @@ function buildOrmMapHtml(snapshot, mermaidSource, meta = {}) {
 `;
 }
 
-function escapeHtml(s) {
-  if (s == null) return '';
-  return String(s)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+
 
 /**
  * Optional: read package name from cwd/package.json

package/bin/utils/project.js

@@ -56,7 +56,7 @@ function startDevServer(projectPath, useTailwind) {
       stdio: 'inherit',
       shell: true,
       cwd: projectPath,
-      env: { ...process.env, PORT: process.env.PORT || '3000', NODE_ENV: 'development' }
+      env: { ...process.env, PORT: process.env.PORT || '7331', NODE_ENV: 'development' }
     });
     
     // Handle exit
@@ -77,7 +77,7 @@ function startDevServer(projectPath, useTailwind) {
       stdio: 'inherit',
       shell: true,
       cwd: projectPath,
-      env: { ...process.env, PORT: process.env.PORT || '3000', NODE_ENV: 'development' }
+      env: { ...process.env, PORT: process.env.PORT || '7331', NODE_ENV: 'development' }
     });
     
     server.on('exit', (code) => {