webspresso 0.0.97 → 0.0.99

package/.agents/ADMIN.md

@@ -133,7 +133,59 @@ registry.registerPageDir(path.join(__dirname, 'admin-pages'));
 
 ---
 
-## 5. Custom Field Renderers (`registerFieldRenderer`)
+## 5. Page & Plugin Title Management
+
+Admin Panel supports configurable base titles, title templates, and dynamic SPA page titles:
+
+### Plugin Configuration
+```js
+adminPanelPlugin({
+  db,
+  title: 'Acme Admin',           // Base title in <title> and header (default: 'Admin Panel')
+  titleTemplate: '%s | %b',      // Format template: %s = page title, %b = base title (default: '%s | %b')
+});
+```
+
+### Module & Page Title Configuration
+When registering modules and custom pages, titles are automatically propagated to navigation and browser document title:
+```js
+adminApi.registerModule({
+  id: 'reports',
+  title: 'Reports & Analytics',   // Module fallback title
+  pages: [
+    {
+      id: 'monthly-report',
+      title: 'Monthly Report',    // Document title -> "Monthly Report | Acme Admin"
+      path: '/reports/monthly',
+      component: ...,
+    },
+    {
+      id: 'live-dashboard',
+      documentTitle: 'Live Monitor (Fullscreen)', // Raw document.title override
+      path: '/reports/live',
+      layout: false,
+      component: ...,
+    }
+  ]
+});
+```
+
+### Dynamic Client-Side Title Helper (`setAdminPageTitle`)
+From any Mithril component or client script:
+```js
+// Dynamic title formatted with template (e.g. "Sales Overview | Acme Admin")
+window.setAdminPageTitle('Sales Overview');
+
+// Custom template override
+window.setAdminPageTitle('Sales Overview', { template: '%s — %b' });
+
+// Raw document title without template
+window.setAdminPageTitle('Sales Overview', { raw: true });
+```
+
+---
+
+## 6. Custom Field Renderers (`registerFieldRenderer`)
 
 Register custom display and edit renderers for specific column types:
 
@@ -152,7 +204,7 @@ registry.registerFieldRenderer('color-picker', {
 
 ---
 
-## 6. Dashboard Widgets (`registerWidget`)
+## 7. Dashboard Widgets (`registerWidget`)
 
 Register dashboard widgets for the Admin overview screen:
 
@@ -164,9 +216,20 @@ registry.registerWidget('recent-orders', {
 });
 ```
 
+### Built-in Dashboard Widgets
+- **`model-stats`**: Model overview cards displaying record counts, column counts, and last update timestamps.
+- **`database-storage`**: Database Storage & Health monitor showing:
+  - Database engine (SQLite, PostgreSQL, MySQL) & active file sizes
+  - Total tables and total record counts across the schema
+  - Storage health status badge with high-volume alerts for unpruned logs
+  - Top tables by row count with visual progress percentage bars
+  - Direct navigation links to model CRUD screens
+- **`quick-actions`**: Fast shortcuts to create new records across enabled models.
+- **`recent-activity`**: Timeline of recent administrative mutations (creates, updates, deletes) powered by `audit_logs` / `admin_activity_logs` with direct links to record changes.
+
 ---
 
-## 7. Single Record & Bulk Table Actions
+## 8. Single Record & Bulk Table Actions
 
 Add custom action buttons to model table views:
 
@@ -182,6 +245,16 @@ registry.registerAction('Product', {
   },
 });
 
+// Record action with navigation redirect (e.g. audit-timeline)
+registry.registerAction('Product', {
+  id: 'view-history',
+  label: 'History',
+  icon: 'clock',
+  handler: async (record, model) => {
+    return { redirect: `/_admin/audit-log?model=${model.name}&recordId=${record.id}` };
+  },
+});
+
 // Bulk multi-select table action
 registry.registerBulkAction('Product', {
   id: 'bulk-archive',
@@ -196,7 +269,7 @@ registry.registerBulkAction('Product', {
 
 ---
 
-## 8. Client Components & Custom Client Script Injections
+## 9. Client Components & Custom Client Script Injections
 
 Inject custom client-side JavaScript / Mithril components into the Admin SPA runtime:
 
@@ -213,7 +286,7 @@ registry.registerClientComponent('custom-banner', `
 
 ---
 
-## 9. Offline & Zero-CDN Architecture
+## 10. Offline & Zero-CDN Architecture
 
 The Admin Panel is 100% self-contained and operates completely offline without external CDN dependencies (`unpkg.com`, `cdn.jsdelivr.net`, or `cdn.tailwindcss.com`):
 - **Vendored Static Assets (`plugins/admin-panel/vendor/`)**:
@@ -223,3 +296,88 @@ The Admin Panel is 100% self-contained and operates completely offline without e
 - **Local Asset Serving**: Served locally at `GET /_admin/vendor/:file` with proper MIME types, path traversal protections, and `Cache-Control: public, max-age=86400` caching.
 - **Hardened CSP**: Works in air-gapped / intranet environments with strict `'self'` Content Security Policy without leaking third-party network requests.
 
+---
+
+## 11. Toast Notifications, Modal Confirmations & Session Expiry UX
+
+The Admin SPA includes a built-in reactive notification and modal system that replaces intrusive browser `alert()` and `confirm()` dialogs.
+
+### Toast Notifications (`window.notify`)
+Display auto-dismissing, animated toasts in the top-right corner with pause-on-hover:
+
+```js
+// Available on window.notify or as global helpers: notifySuccess, notifyError, notifyWarning, notifyInfo
+notify.success('Record created successfully');
+notify.error('Failed to save record: Validation error');
+notify.warning('Please review unsaved changes');
+notify.info('Export started in the background');
+
+// Custom duration (TTL in milliseconds, default 4000ms):
+notify.success('Saved!', 2000);
+```
+
+### Confirmation Modal (`window.confirmModal` / `confirmAction`)
+Display an accessible, styled modal dialog returning a Promise resolving to `true` or `false`:
+
+```js
+// Destructive confirmation (danger: true highlights the confirm button in red)
+const confirmed = await confirmAction({
+  title: 'Delete User',
+  message: 'Are you sure you want to permanently delete this user?',
+  confirmText: 'Delete',
+  cancelText: 'Cancel',
+  danger: true,
+});
+
+if (confirmed) {
+  await api.delete(`/users/${id}`);
+  notify.success('User deleted');
+}
+```
+
+### Session Expiration & Intended Return-To Redirection
+When an authenticated staff user's session expires or an API call returns `401 Unauthorized`:
+1. `redirectToLogin('expired')` captures the active route and redirects to `/_admin/#!/login?returnTo=<route>&reason=expired`.
+2. The login screen displays an informational notice banner: *"Your session has expired. Please sign in again."*
+3. After authenticating successfully, the user is automatically redirected to their intended route.
+4. **Open-Redirect Hardening**: All return destinations are strictly validated by `isSafeIntendedRoute(path)` to disallow protocol-relative URLs (`//evil.com`), foreign protocols (`http:`, `javascript:`), or backslashes.
+
+---
+
+## 12. Admin Login Brute-Force Protection & Rate Limiting
+
+The Admin Panel includes built-in in-memory rate limiting to defend staff login endpoints against credential stuffing and brute-force password guessing.
+
+### Configuration (`adminPanelPlugin`)
+
+```js
+import { createApp, adminPanelPlugin } from 'webspresso';
+
+const app = createApp({
+  plugins: [
+    adminPanelPlugin({
+      db,
+      // Configure or disable login rate limiting:
+      loginRateLimit: {
+        enabled: true,                  // Default: true
+        maxAttempts: 5,                 // Max failed attempts before blocking (default: 5)
+        windowMs: 15 * 60 * 1000,       // Tracking window (default: 15 minutes)
+        blockDurationMs: 15 * 60 * 1000 // Temporary block duration (default: 15 minutes)
+      },
+    }),
+  ],
+});
+```
+
+To disable rate limiting (e.g. in test or internal automated environments):
+```js
+adminPanelPlugin({ db, loginRateLimit: false });
+```
+
+### Protection Mechanics
+- **IP Tracking**: Tracks failed attempts keyed by client IP (`req.ip` or upstream trusted proxy headers).
+- **Automatic Block**: After `maxAttempts` failed logins within `windowMs`, returns HTTP 429 Too Many Requests with a `Retry-After: <seconds>` response header and JSON error payload.
+- **Success Reset**: A single successful login clears the failed attempt counter for that IP.
+- **Programmatic Reset**: Cleared automatically upon server restart or via `plugin.api.resetLoginAttempts(ip)`.
+
+

package/.agents/AGENTS.md

@@ -44,7 +44,7 @@ This `.agents/` customization root is organized into modular topic guides:
 6. **[HTTP Response Compression](.agents/COMPRESSION.md)** — Native streaming zlib compression (`server.compression`), Brotli/Gzip/Deflate negotiation, threshold handling, and `res.compress(false)` route opt-out.
 7. **[Dual Authentication System](.agents/AUTH.md)** — Stateful Session + Cookie & Stateless HS256 JWT + Refresh Token Rotation, `req.auth` helpers, and `middleware: ['jwt']` guard integrations.
 8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
-9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 18 built-in official plugins (including `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
+9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 19 built-in official plugins (including `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
 10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
 11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
 12. **[Admin Panel Customization](.agents/ADMIN.md)** — Extending Mithril.js Admin Panel SPA (Custom pages `component.js`, custom field renderers, widgets, single & bulk actions).

package/.agents/ARCHITECTURE.md

@@ -116,4 +116,14 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 | `xlsxPlugin` | Excel / Export | Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and services |
 | `csvPlugin` | CSV / Export | RFC 4180 CSV generator, parser, Excel UTF-8 BOM, streaming writer (`res.csv`), and services |
 
+---
+
+## 5. Developer Experience & Live/Hot Reload (`src/dev-reload/`)
+
+- **Zero-Dependency SSE Reload Hub**: Enabled via `createApp({ devReload: true })` (or `devReload: { watchTemplates: true, watchCss: true, debounce: 50 }`).
+- **Instant CSS Hot Swap**: Modifying `.css` files dynamically refreshes all `<link rel="stylesheet">` elements without page refresh or DOM state loss.
+- **Template & Layout Live Reload**: Modifying Nunjucks templates (`.njk`, `.html`) in `views/` or pages in `pages/` automatically invalidates frontmatter/loader caches and broadcasts a debounced `'full'` reload event to active browser tabs.
+- **Error Overlay Frame**: Client runtime script automatically renders terminal-free in-browser error frames for compile/build errors with line numbers and dismiss keyboard shortcuts (`Esc`).
+- **DevTools Toolbar & Dashboard**: Embedded via `fsy.devToolbar()` and available at `/_webspresso` for interactive inspection of routes, models, services, cache, and profiler metrics.
+
 

package/.agents/AUTH.md

@@ -101,3 +101,172 @@ module.exports = {
   },
 };
 ```
+
+---
+
+## 5. Zero-Dependency OAuth 2.0 & Social Login (`plugins/oauth`, `core/auth/oauth`)
+
+Webspresso includes a built-in, zero-dependency OAuth 2.0 client and plugin with RFC 7636 PKCE, HMAC-SHA256 signed anti-CSRF state tokens, profile normalization, and seamless Dual Auth integration:
+
+### 5.1 Plugin Configuration
+```javascript
+const { createApp, oauthPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    oauthPlugin({
+      secret: process.env.SESSION_SECRET,
+      providers: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+          // redirectUri is optional; auto-inferred from request host if omitted
+        },
+        github: {
+          clientId: process.env.GITHUB_CLIENT_ID,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        },
+      },
+      // Optional hook to find or create the user in your database
+      async findOrCreateUser({ provider, profile, tokens, db }) {
+        let user = await db.getRepository('User').findOne({ email: profile.email });
+        if (!user) {
+          user = await db.getRepository('User').create({
+            email: profile.email,
+            name: profile.name,
+            avatar_url: profile.avatarUrl,
+          });
+        }
+        return user;
+      },
+      defaultReturnTo: '/dashboard',
+    }),
+  ],
+});
+```
+
+### 5.2 Automatic Routes
+- `GET /auth/:provider` (e.g. `/auth/google?returnTo=/dashboard`): Generates PKCE code challenge and HMAC-signed state token with embedded return URL, redirecting the browser to the provider's authorization page.
+- `GET /auth/:provider/callback`: Validates anti-CSRF state, exchanges authorization code for tokens, fetches normalized profile, calls `findOrCreateUser`, automatically establishes session via `req.auth.login(user)`, and redirects to `returnTo`. For API/mobile clients (`format=json` or `Accept: application/json`), returns `{ success: true, user, token }`.
+
+### 5.3 Template Helper (`fsy.oauthUrl`)
+In Nunjucks templates:
+```html
+<a href="{{ fsy.oauthUrl('google') }}" class="btn">Sign in with Google</a>
+<a href="{{ fsy.oauthUrl('github', { returnTo: '/settings' }) }}" class="btn">Connect GitHub</a>
+```
+
+---
+
+## 6. Zero-Dependency Two-Factor Authentication (2FA / TOTP)
+
+Webspresso provides an enterprise-grade, zero-dependency 2FA/TOTP suite adhering strictly to **RFC 6238 (TOTP)**, **RFC 4226 (HOTP)**, and **RFC 4648 (Base32)**. It requires NO external npm libraries and features offline SVG QR code generation to prevent leaking secret keys to third-party APIs.
+
+### 6.1 Key Capabilities
+- **RFC 6238 Time-Based OTP**: Standard 30s step, 6/8 digits, HMAC-SHA1/SHA256/SHA512.
+- **Time Drift Tolerance**: Built-in clock drift window (`window: 1` verifies $t \pm 30s$) and detailed delta analysis.
+- **Offline QR Code Generator**: Generates crisp vector SVG strings and data URIs directly in pure Node.js.
+- **Single-Use Recovery Codes**: Cryptographically secure alphanumeric codes, SHA-256 hashed storage, and timing-safe single-use burning.
+- **Session & Guard Integration**: `req.auth.verify2Fa()`, `req.auth.is2FaVerified()`, and `middleware: ['2fa']`.
+
+### 6.2 Initializing 2FA Setup for a User
+```javascript
+const { totp } = require('webspresso');
+
+// In an API route: POST /api/user/2fa/setup
+module.exports = {
+  middleware: ['auth'],
+  async handler(req, res) {
+    const setup = totp.createTotpSetup({
+      user: req.user,
+      issuer: 'My SaaS App',
+      recoveryCodeCount: 8,
+    });
+
+    // 1. Temporarily save secret and hashed recovery codes to DB for confirmation
+    await req.db.getRepository('User').update(req.user.id, {
+      temp_totp_secret: setup.secret,
+      temp_recovery_codes: JSON.stringify(setup.recoveryCodesHashed),
+    });
+
+    // 2. Return QR SVG and plaintext recovery codes for user to record
+    return res.json({
+      secret: setup.secret,
+      qrSvg: setup.qrSvg,
+      qrDataUri: setup.qrDataUri,
+      recoveryCodes: setup.recoveryCodes,
+    });
+  },
+};
+```
+
+### 6.3 Confirming 2FA Activation
+```javascript
+// In an API route: POST /api/user/2fa/confirm
+module.exports = {
+  middleware: ['auth'],
+  schema: ({ z }) => ({
+    body: z.object({ token: z.string().min(6).max(8) }),
+  }),
+  async handler(req, res) {
+    const user = req.user;
+    const { token } = req.input.body;
+
+    const isValid = totp.verifyTotp(token, user.temp_totp_secret);
+    if (!isValid) {
+      return res.status(400).json({ error: 'Invalid verification code' });
+    }
+
+    // Activate 2FA on user record
+    await req.db.getRepository('User').update(user.id, {
+      two_factor_enabled: true,
+      totp_secret: user.temp_totp_secret,
+      recovery_codes: user.temp_recovery_codes,
+      temp_totp_secret: null,
+      temp_recovery_codes: null,
+    });
+
+    req.auth.set2FaVerified(true);
+    return res.json({ success: true, message: '2FA enabled successfully' });
+  },
+};
+```
+
+### 6.4 2FA Login Flow & Guard Middleware
+```javascript
+// Step 1: Initial password login
+const user = await req.auth.findUserByCredentials(email, password);
+if (user.two_factor_enabled) {
+  // Mark session as 2FA pending without full login
+  req.auth.set2FaPending(user);
+  return res.json({ require2Fa: true });
+}
+await req.auth.login(user);
+
+// Step 2: 2FA Verification Endpoint (accepts 6-digit TOTP token OR recovery code)
+const verification = req.auth.verify2Fa(tokenOrRecoveryCode, user);
+if (verification.success) {
+  if (verification.type === 'recovery_code') {
+    // Burn used recovery code
+    await req.db.getRepository('User').update(user.id, {
+      recovery_codes: JSON.stringify(verification.remainingHashedCodes),
+    });
+  }
+  await req.auth.login(user);
+  req.auth.set2FaVerified(true);
+  return res.json({ success: true });
+}
+```
+
+### 6.5 Route Protection with `middleware: ['2fa']`
+```javascript
+// In pages/api/account/billing.get.js or pages/security/index.njk
+module.exports = {
+  middleware: ['auth', '2fa'], // Rejects unverified users with 403 or redirects to /2fa
+  async handler(req, res) {
+    return res.json({ secureData: true });
+  },
+};
+```
+
+

package/.agents/CLI.md

@@ -13,8 +13,12 @@ npx webspresso dev
 #   --port, -p <number> (default: 3001)
 #   --host <string> (default: localhost)
 
-# Build production bundle / verify assets
+# Build production bundle / compile assets (Tailwind + esbuild with manifest.json)
 npx webspresso build
+# Flags:
+#   --no-css    (skip CSS build)
+#   --no-js     (skip JS bundle build)
+#   --no-hash   (disable content hashing in filenames)
 ```
 
 ---
@@ -113,3 +117,193 @@ npx webspresso agents:init
 npx webspresso agents:init --force
 ```
 
+---
+
+## 8. Tailwind CSS Setup & Migration (`add:tailwind`)
+
+Add or upgrade Tailwind CSS in a project:
+
+```bash
+# Add Tailwind CSS v4 (Oxide engine, LightningCSS, zero-config)
+npx webspresso add tailwind --v4
+
+# Add Tailwind CSS v3 (legacy PostCSS engine)
+npx webspresso add tailwind --v3
+
+# Upgrade existing Tailwind v3 project to v4
+npx webspresso add tailwind --upgrade
+```
+
+---
+
+## 9. Client Bundler Setup (`add:esbuild`)
+
+Add client-side JS/TS bundling with esbuild incremental watching:
+
+```bash
+# Scaffold esbuild client bundler setup
+npx webspresso add esbuild
+# or
+npx webspresso add:esbuild
+```
+
+---
+
+## 10. Data Retention & Storage Cleanup Commands
+
+Keep databases and storage clean by pruning historical records and unreferenced files:
+
+```bash
+# Delete audit log entries older than N days (default: 90)
+npx webspresso audit:prune --days 90
+
+# Delete email delivery logs older than N days (default: 90)
+npx webspresso email:prune --days 90
+
+# Delete completed/failed background jobs older than N days (default: 30)
+npx webspresso queue:prune --days 30
+
+# Delete expired site analytics visits & JS errors older than N days
+npx webspresso analytics:prune --days 90
+
+# Scan and delete orphaned uploads not referenced by any database model
+npx webspresso upload:prune
+
+# Dry run mode (inspect orphaned files without deleting)
+npx webspresso upload:prune --dry-run
+```
+
+---
+
+## 11. Routes Introspection (`routes`)
+
+List and inspect all compiled file-based and API routes in terminal:
+
+```bash
+# List all application routes in a colorized table
+npx webspresso routes
+
+# Filter to only API endpoints
+npx webspresso routes --api
+
+# Filter to only SSR page routes
+npx webspresso routes --pages
+
+# Output routes as machine-readable JSON
+npx webspresso routes --json
+```
+
+---
+
+## 12. Dev Server DX & Query Profiler
+
+When starting in development mode (`isDev: true` / `process.env.NODE_ENV !== 'production'`), Webspresso automatically:
+
+- **Displays Startup Banner**: ASCII box with Node/Framework version, Local & Admin URLs, Database dialect, and counts of routes, models, services, and plugins.
+- **Request Profiler & Logger**: Color-coded HTTP requests with status, response duration, and database metrics:
+  ```text
+  [GET 200] /api/notes — 14.2ms | 2 DB queries (2.8ms)
+  ```
+- **N+1 Query Detection**: Flags queries executing repeatedly against the same table within a single request:
+  ```text
+  ⚠️  [webspresso:n+1] Potential N+1 query pattern detected on table 'users' (5 queries, 6.4ms). Consider eager loading with repo.query().include('users') or batching.
+  ```
+- **Configuration (`dev` options in `createApp`)**:
+  ```javascript
+  createApp({
+    dev: {
+      banner: true,        // show startup banner (default: true in dev)
+      routeTable: true,    // show route table in banner (default: true)
+      profiler: true,      // enable request & DB profiler (default: true)
+      nPlusOne: true,      // detect N+1 queries (default: true)
+      nPlusOneThreshold: 4,// query count threshold for warning (default: 4)
+      slowQueryMs: 50,     // flag queries slower than N ms (default: 50)
+      verbose: false,      // log individual SQL statements
+    }
+  });
+  ```
+
+---
+
+## 13. Scaffolding & Code Generation (`make:*` Commands)
+
+Quickly generate boilerplate adhering strictly to Webspresso contracts:
+
+```bash
+# 1. Scaffold an ORM Model in models/<Name>.js with parsed zdb fields and Knex migration
+npx webspresso make:model Post --fields title:string,content:text,published:boolean,views:integer --migration
+# Flags:
+#   --fields <list>   (title:string,content:text,views:integer,price:number,published:boolean,authorId:id)
+#   --table <name>    (custom table name; defaults to pluralized lowercase)
+#   --migration, -m   (auto-generate timestamped Knex migration in migrations/)
+#   --soft-deletes    (include deletedAt column and default scope)
+
+# 2. Scaffold API Endpoints in pages/api/
+# Single endpoint with Zod validation and handler:
+npx webspresso make:api notes/export --method POST --auth
+
+# Full REST CRUD Suite (list, create, detail, update, delete) in pages/api/posts:
+npx webspresso make:api posts --crud --model Post
+
+# 3. Scaffold an SSR Page in pages/
+npx webspresso make:page blog/[slug]
+# Generates pages/blog/[slug].njk template + companion loader pages/blog/[slug].js
+
+# 4. Scaffold a Service in services/<domain>/<action>.js
+npx webspresso make:service order.process --transaction --auth admin
+
+# 5. Scaffold a Background Queue Worker in jobs/<name>.js
+npx webspresso make:job send-welcome-email --queue default --retries 3
+```
+
+---
+
+## 14. OpenAPI & API Documentation Export (`openapi` / `api:docs`)
+
+Generate and export standard OpenAPI 3.0 JSON specification from file-based API routes and Zod schemas:
+
+```bash
+# Print OpenAPI 3.0 specification to stdout
+npx webspresso openapi
+
+# Export directly to a JSON file
+npx webspresso openapi --out openapi.json
+
+# Export with custom title, version, and server URL
+npx webspresso api:docs --out public/openapi.json --title "My API" --api-version "2.0.0" --server "https://api.myapp.com"
+
+# Include ORM model schemas in components.schemas
+npx webspresso openapi --out openapi.json --include-orm
+```
+
+---
+
+## 15. TypeScript Definitions & IDE Auto-Complete Generator (`typegen` / `types`)
+
+Scan ORM models, business services, and routes to automatically generate typed TypeScript declaration files (`.webspresso/types.d.ts` and `webspresso-env.d.ts`) with module augmentation:
+
+```bash
+# Generate TypeScript definitions
+npx webspresso typegen
+
+# Aliases
+npx webspresso types
+npx webspresso generate:types
+
+# Watch mode (automatically regenerates on model/service/page edits)
+npx webspresso typegen --watch
+
+# Custom output destination
+npx webspresso typegen --out types/webspresso.d.ts --no-env-file
+```
+
+### Generated Capabilities & IDE DX:
+- **Typed Models (`db.getRepository('Model')`)**: Auto-completes model names and infers entity column types from Zod schemas.
+- **Typed Services (`req.service('name', input)`)**: Auto-completes registered service names and enforces validated input payloads.
+- **Typed Route Table (`AppRoute`, `AppRoutePath`)**: Union types for all discovered SSR and API routes.
+
+
+
+
+
+