exisjs 0.7.11 → 0.7.13

package/dist/docs/content/cli/usage.mdx

@@ -1,75 +1,152 @@
 ---
+title: "CLI Usage"
+description: "How to run the ExisJS CLI, configure package scripts, forward command-line arguments, and load environments."
 nextUrl: "/docs/cli/commands"
 nextTitle: "CLI Commands"
 ---
 
 # CLI Usage
 
-The ExisJS CLI (`exis` / `exisjs`) can be executed in two primary contexts: **globally / on-demand** via `npx`, or **locally** via your project's `package.json` scripts.
+The ExisJS CLI (`exisjs` or `exis`) can be executed through global package managers, on-demand runner utilities like `npx`, or locally defined `package.json` scripts.
 
-## Global vs. Local Execution
+---
+
+## Execution Methods
+
+### 1. On-Demand Execution (`npx`)
 
-When bootstrapping a brand-new project, invoke the initialization tool using `npx`:
+When initializing a new application or running ad-hoc commands without a global install:
 
 ```bash
-$ npx exisjs init my-api
+# Initialize a project in the current working directory
+npx exisjs init
+
+# Check environment diagnostics
+npx exisjs doctor
+
+# Print the application routing table
+npx exisjs routes
 ```
 
-Once inside an initialized ExisJS project, execution through `npm run` ensures deterministic behavior pinned to the local `exisjs` version in `node_modules`.
+### 2. Global Installation
+
+For system-wide command availability:
+
+```bash
+# Install globally
+npm install -g exisjs
+
+# Run directly
+exisjs dev
+exis routes
+```
+
+### 3. Project-Local Scripts (Recommended)
+
+When working inside an established project, invoking the CLI via `npm run` ensures consistent execution pinned to the local `exisjs` dependency in `node_modules`.
+
+---
 
 ## Default Package Scripts
 
-Every ExisJS project scaffolded with `init` includes the standard script targets in `package.json`:
+Applications initialized with `npx exisjs init` include standard npm lifecycle scripts in `package.json`:
 
 ```json
 {
+  "name": "my-exis-app",
+  "version": "1.0.0",
   "scripts": {
     "dev": "exisjs dev",
     "build": "exisjs build",
+    "clean": "exisjs clean",
     "start": "exisjs start",
-    "test": "exisjs test"
+    "test": "exisjs test",
+    "routes": "exisjs routes",
+    "doctor": "exisjs doctor"
+  },
+  "dependencies": {
+    "exisjs": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
   }
 }
 ```
 
-Invoke these scripts using your package manager:
+Run these scripts using your preferred package manager:
 
 ```bash
-$ npm run dev
-$ npm run build
-$ npm run start
-$ npm test
+# Start development server
+npm run dev
+
+# Compile TypeScript and build route manifests
+npm run build
+
+# Start production server
+npm run start
+
+# Run native test runner
+npm test
+
+# Print routing table
+npm run routes
 ```
 
-## Passing Arguments via Scripts
+---
+
+## Passing Arguments to Scripts
 
-To pass options through `npm run`, append a double-dash (`--`) before the CLI flags:
+When invoking CLI commands through `npm run`, use the double-dash delimiter (`--`) to forward flags and positional arguments to `exisjs`:
 
 ```bash
-# Start the dev server on port 5000
-$ npm run dev -- -p 5000
+# Run dev server on a custom port
+npm run dev -- -p 4000
 
 # Run a specific test file
-$ npm test -- tests/users.test.ts
+npm test -- tests/users.test.ts
+
+# Filter routes table by method and path
+npm run routes -- -m POST -f /api/v1
 ```
 
-Direct commands can also be called via `npx exisjs`:
+With `pnpm` or `yarn`:
 
 ```bash
-# Scaffold a new resource slice
-$ npx exisjs g resource users
+# pnpm forwards arguments directly
+pnpm dev -p 4000
+
+# yarn forwards arguments directly
+yarn dev -p 4000
+```
+
+---
+
+## Environment Configuration
 
-# Print the routing table
-$ npx exisjs routes
+The CLI automatically loads environment variables according to the current execution mode:
 
-# Inspect available public exports
-$ npx exisjs exports
+| File | Loaded In | Priority |
+| :--- | :--- | :--- |
+| `.env.local` | All modes (except test) | High |
+| `.env.<mode>` | Matching mode (e.g. `.env.production`) | Medium |
+| `.env` | All modes | Default |
+
+### Overriding the Environment Mode
+
+Use the `-m, --mode <mode>` flag or set `NODE_ENV`:
+
+```bash
+# Build with staging environment variables
+npx exisjs build --mode staging
+
+# Execute a script under staging configuration
+npx exisjs run scripts/seed.ts --mode staging
 ```
 
-## Recommended Workflow
+---
+
+## Next Steps
+
+- Explore the complete command catalog in the [CLI Command Reference](/docs/cli/commands).
+- Review global server configurations in the [Configuration Guide](/docs/config).
 
-1. Use `npx exisjs init <name>` to scaffold new applications.
-2. Use `npm run dev` for local hot-reloading development with automatic port conflict handling.
-3. Use `npx exisjs generate <type> <name>` to scaffold file conventions (`route`, `service`, `schema`, `boundary`, `resource`).
-4. Use `npm test` to run the integrated test runner.
-5. Use `npm run build` and `npm run start` for production deployment.

package/dist/docs/content/config.mdx

@@ -1,19 +1,19 @@
 ---
-nextUrl: '/docs/routing'
-nextTitle: 'Routing'
+title: "Configuration"
+description: "Global runtime configuration, phases, environment loading, server engine selection, and cluster options in exis.config.ts."
+nextUrl: "/docs/exisjs-mcp"
+nextTitle: "AI Integration (MCP)"
 ---
 
 # Configuration (`exis.config.ts`)
 
-ExisJS uses a fully typed configuration engine that closely resembles Vite or Next.js.
-
-By placing an `exis.config.ts` file in the root of your project, you gain complete control over the underlying server (Node.js or uWebSockets), middleware (CORS, Helmet, Compression), SSL, and the Plugin ecosystem.
+ExisJS uses a typed configuration file located at the project root (`exis.config.ts` or `exis.config.js`). It controls global server behavior, middleware defaults, file watcher options, cluster concurrency, and runtime environments.
 
 ---
 
-## 1. Basic Configuration
+## Static Configuration
 
-A basic configuration simply exports the result of `defineConfig`. This provides TypeScript autocomplete for all available options.
+Export the result of `defineConfig()` from `exis.config.ts` for full TypeScript type safety and autocompletion:
 
 ```typescript filename="exis.config.ts"
 import { defineConfig } from 'exisjs/config'
@@ -23,235 +23,233 @@ export default defineConfig({
   host: '0.0.0.0',
 
   cors: {
-    origin: '*',
+    origin: ['https://example.com', 'https://admin.example.com'],
     credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
   },
 
   logger: {
-    level: 'debug',
-    pretty: true,
+    level: 'info',
+    pretty: true
+  },
+
+  helmet: {
+    enabled: true,
+    xFrameOptions: 'SAMEORIGIN'
   },
+
+  bodyLimit: 10 * 1024 * 1024 // 10MB
 })
 ```
 
 ---
 
-## 2. Dynamic & Phase-Based Config
-
-Often, you'll need different configurations for Development, Production, or Testing (e.g., enabling pretty logging only in development, or changing the Database URL).
+## Dynamic Phase-Based Configuration
 
-ExisJS allows you to export an `async function` that provides the current `phase` (Environment).
+ExisJS supports exporting an asynchronous function that receives the current lifecycle `phase` and the framework's default configuration:
 
 ```typescript filename="exis.config.ts"
-import { defineConfig, PHASE_DEVELOPMENT_SERVER } from 'exisjs/config'
+import {
+  defineConfig,
+  PHASE_DEVELOPMENT_SERVER,
+  PHASE_PRODUCTION_SERVER,
+  PHASE_TEST
+} from 'exisjs/config'
 
 export default async (phase: string, { defaultConfig }: any) => {
   const isDev = phase === PHASE_DEVELOPMENT_SERVER
+  const isTest = phase === PHASE_TEST
 
   return defineConfig({
     port: Number(process.env.PORT) || 4000,
 
-    // Enable pretty logging only in Development
-    logger: isDev ? { level: 'debug', pretty: true } : false,
+    logger: isDev
+      ? { level: 'debug', pretty: true }
+      : isTest
+        ? false
+        : { level: 'info', pretty: false },
+
+    compression: !isDev && !isTest,
 
-    // Compress responses in Production
-    compression: !isDev,
+    cluster: {
+      workers: phase === PHASE_PRODUCTION_SERVER ? 'auto' : 1
+    }
   })
 }
 ```
 
-The available phases are:
+### Lifecycle Phase Constants
 
-- `PHASE_DEVELOPMENT_SERVER` (Triggered via `exis dev`)
-- `PHASE_PRODUCTION_SERVER` (Triggered via `exis start`)
-- `PHASE_TEST` (Triggered when `NODE_ENV=test`)
+| Constant | Value | Triggered By |
+| :--- | :--- | :--- |
+| `PHASE_DEVELOPMENT_SERVER` | `'phase-development-server'` | `exisjs dev` |
+| `PHASE_PRODUCTION_SERVER` | `'phase-production-server'` | `exisjs start` |
+| `PHASE_PRODUCTION_BUILD` | `'phase-production-build'` | `exisjs build` |
+| `PHASE_TEST` | `'phase-test'` | `exisjs test` / `NODE_ENV=test` |
 
 ---
 
-## 3. Type-Safe Environment Variables
+## Environment Variable Management
 
-We highly recommend using `v.env()` from `exisjs/validator` to strongly type and validate your environment variables before the server starts. You can create an `env.ts` file and import it directly into your `exis.config.ts`.
+ExisJS automatically loads and expands `.env` files in cascade priority:
 
-```typescript filename="env.ts"
+1. `.env.${NODE_ENV}.local`
+2. `.env.local` (ignored when `NODE_ENV=test`)
+3. `.env.${NODE_ENV}`
+4. `.env`
+
+### Type-Safe Validation with `tex`
+
+To ensure configuration values are valid before starting the HTTP server:
+
+```typescript filename="src/config/env.ts"
 import { tex } from 'exisjs/validator'
 
 export const env = tex
   .object({
-    PORT: tex.number({ coerce: true, optional: true }),
-    NODE_ENV: tex.string({ optional: true }),
-    MONGODB_URI: tex.string(),
+    PORT: tex.number({ coerce: true, default: 4000 }),
+    NODE_ENV: tex.enum(['development', 'production', 'test'], { default: 'development' }),
+    DATABASE_URL: tex.string(),
+    REDIS_URL: tex.string({ optional: true })
   })
   .parse(process.env)
 ```
 
 ```typescript filename="exis.config.ts"
 import { defineConfig } from 'exisjs/config'
-import { env } from './env.ts' // Fails fast if variables are missing!
+import { env } from './src/config/env'
 
 export default defineConfig({
   port: env.PORT,
-  logger: {
-    pretty: env.NODE_ENV !== 'production',
-  },
+  env: env.NODE_ENV
 })
 ```
 
 ---
 
-## 4. Background Jobs & Workers
-
-To enable the background job engine (which powers scheduled Cron jobs and the task queue), you must explicitly configure a `queue` driver in `exis.config.ts`.
-
-If this is missing, the job scheduler is completely disabled to save memory.
+## Configuration Options Reference
+
+### Network & Transport
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `port` | `number` | `4000` | Port number to bind the HTTP server to. |
+| `host` | `string` | `'0.0.0.0'` | Network host interface. |
+| `server` | `'auto' \| 'node' \| 'bun' \| 'uws'` | `'auto'` | Underlying server adapter engine. |
+| `ssl` | `{ key: string \| Buffer, cert: string \| Buffer }` | `undefined` | SSL certificate credentials for native HTTPS. |
+| `http2` | `boolean` | `true` | Enables HTTP/2 (active when SSL is configured). |
+| `redirectHttp` | `boolean \| number` | `false` | Automatically redirects plaintext HTTP traffic to HTTPS. |
+| `trustProxy` | `boolean \| number` | `false` | Respects `X-Forwarded-For` and `X-Forwarded-Proto` proxy headers. |
+| `keepAlive` | `boolean \| KeepAliveConfig` | `false` | Configures socket keep-alive (`timeoutMs`, `headersTimeoutMs`, `maxRequests`). |
+
+### Middleware Defaults & Security
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `cors` | `boolean \| CorsConfig` | `{ origin: '*' }` | Global CORS policy. Can be overridden in boundaries or routes. |
+| `helmet` | `boolean \| HelmetConfig` | `{ enabled: true }` | Security headers (CSP, X-Frame-Options, HSTS). |
+| `compression` | `boolean` | `false` | Gzip/Brotli HTTP response compression. |
+| `bodyLimit` | `number` | `10485760` (10MB) | Maximum request payload body size in bytes. |
+| `blockSuspiciousProbes` | `boolean \| BlockProbesOptions` | `false` | Blocks known vulnerability scanners and malicious probes (`.php`, `wp-admin`). |
+| `etag` | `boolean` | `false` | Generates weak ETags for cache validation on responses. |
+| `transformResponse` | `boolean \| Function` | `false` | Standardizes handler response payload envelopes. |
+
+### Logging & Diagnostics
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `logger` | `boolean \| LoggerConfig` | `false` | Pino logger settings (`level`, `pretty`, `redact`). |
+| `debugRouting` | `boolean` | `false` | Outputs detailed route resolution logs per request in development. |
+| `asyncContext` | `boolean` | `false` | Enables `AsyncLocalStorage` context tracking (`getContext()`). |
+| `docs` / `swagger` | `boolean \| SwaggerConfig` | `{ enabled: false }` | OpenAPI 3.1 specification and Swagger UI endpoint generation. |
+| `healthcheck` | `boolean \| HealthCheckConfig` | `{ enabled: false }` | System health endpoint (`path: '/_health'`). |
+| `metrics` | `boolean \| MetricsConfig` | `{ enabled: false }` | Prometheus metrics endpoint (`path: '/metrics'`). |
+| `telemetry` | `boolean \| TelemetryConfig` | `{ enabled: false }` | OpenTelemetry tracing and metrics export. |
+
+### Concurrency & Clustering
 
 ```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
 export default defineConfig({
-  queue: {
-    driver: 'memory', // Use 'redis' for multi-server production
-    enableWorkers: true, // Set to false to push jobs but not process them
-  },
+  cluster: {
+    // 1 (single-threaded), 'safe' (up to 2 cores), 'auto'/'max' (all available CPU cores)
+    workers: 'auto'
+  }
 })
 ```
 
 ---
 
-## 5. The Underlying Server Engine
+## File Watcher & Development Configuration
 
-By default, ExisJS uses the native Node.js HTTP/HTTPS modules. However, you can seamlessly switch the underlying engine to **uWebSockets.js (uWS)** for significantly higher throughput.
+The development server (`exisjs dev`) provides file watching with debounce and ignore rules:
 
 ```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
 export default defineConfig({
-  // 'auto' will use uWS if installed, otherwise gracefully fallback to Node
-  server: 'auto', // 'auto' | 'node' | 'bun'
+  watch: {
+    paths: ['src', '.env'],
+    ignore: [/tests\//, 'temp/**'],
+    extensions: ['.ts', '.tsx', '.js', '.json'],
+    debounceMs: 250
+  },
+
+  dev: {
+    usePolling: false, // Set to true for network mounts or WSL
+    interval: 100
+  }
 })
 ```
 
----
-
-## 6. Complete Options Reference
-
-Here is a full breakdown of the configuration schema:
-
-### Network & SSL
+### Automatically Excluded Artifacts
 
-- `port` _(number)_: The port the server will bind to. (Default: `4000`)
-- `host` _(string)_: The host interface to bind to. (Default: `'0.0.0.0'`)
-- `ssl` _(object)_: Provide `{ key, cert }` strings or Buffers to enable HTTPS natively.
-- `http2` _(boolean)_: Enables HTTP/2 support natively. (Defaults to `true` when SSL is provided).
-- `redirectHttp` _(boolean | number)_: Automatically intercepts HTTP requests and redirects them to HTTPS.
-
-### Global Middleware
-
-- `cors` _(object | boolean)_: Global CORS policy configuration. Supports:
-  - Exact string origins (e.g. `'https://example.com'` or `'*'`).
-  - Regular expressions (e.g. `/localhost:\d+/`).
-  - Arrays mixing strings and regexes (`['https://app.example.com', /https:\/\/.*\.domain\.com/']`).
-  - Dynamic callbacks: `(origin, cb) => ...` or async functions: `async (origin) => boolean` for multi-tenant setups.
-- `transformResponse` _(boolean | function)_: Automatically wraps all successful handler responses into a standardized envelope:
-  - When `true`: `{ success: true, data: ..., timestamp: ... }` (matching `HttpError`'s `{ success: false, error: ... }`).
-  - When a function: `(data, req, res) => ({ ... })` to provide your own custom envelope.
-- `helmet` _(object | boolean)_: Automatically secures your app with standard HTTP headers. (Enabled by default).
-- `compression` _(object | boolean)_: Enables Gzip/Brotli compression for all HTTP responses.
-- `logger` _(object | boolean)_: Configures the internal Pino-based logger (`level`, `pretty`).
-- `etag` _(boolean)_: Automatically generates ETag headers for cache-invalidation.
-
-### Performance & Security
-
-- `bodyLimit` _(number)_: The maximum allowed size (in bytes) for incoming request bodies. (Default: `10MB` / `10485760` bytes, raising HTTP 413 `PayloadTooLargeError` when exceeded)
-- `trustProxy` _(boolean | number)_: If true, respects `X-Forwarded-For` and `X-Forwarded-Host` headers (essential for apps deployed behind NGINX, Cloudflare, or AWS ELB). If a number, trusts that many hops.
-- `keepAlive` _(object | boolean)_: Tunes the Keep-Alive timeout and Header timeout limits.
-- `workers` _(number | 'safe' | 'max')_: Number of CPU workers for cluster mode. Defaults to 1. 'safe' caps to 2. 'max' uses all available cores.
-
-### Execution & Debugging
-
-- `env` _(string)_: Overrides the environment. Can be 'development', 'production', or 'test'.
-- `server` _('auto' | 'node' | 'uws')_: Server backend to use. Defaults to 'node'.
-- `debugRouting` _(boolean)_: Enables detailed logging of the resolved route file and applied gateways for every incoming request.
-- `test` _(object)_: Configuration for the native test runner (`include`, `exclude`, `setupFiles`, `concurrency`, `coverage`).
-
-### Development Server & File Watcher (`dev`)
-
-- `dev.watch` _(string[])_: Custom paths or glob patterns to watch during development (defaults to `[cwd]`).
-- `dev.ignored` _((string | RegExp)[])_: Additional files or patterns to ignore during watch restarts.
-- `dev.usePolling` _(boolean)_: Enables filesystem polling for cross-platform/Windows NTFS reliability (defaults to `true` on Windows).
-- `dev.interval` _(number)_: Polling interval in milliseconds (default: `100`).
-- `dev.binaryInterval` _(number)_: Polling binary interval in milliseconds (default: `300`).
-
-### Queues & Plugins
-
-- `queue` _(object)_: Configures the Global Job Queue driver (`memory` or `redis`) and backpressure settings.
-- `plugins` _(array)_: Registers framework-level plugins.
+ExisJS automatically excludes build output and temp folders from triggering watcher reloads:
+- **Folders**: `node_modules`, `.git`, `.exis`, `dist`, `build`, `out`, `.turbo`, `.next`, `.cache`, `logs`, `tmp`, `temp`, `tests`, `coverage`.
+- **Files**: `.log`, `.sqlite`, `.db`, `.png`, `.jpg`, `.svg`, `package-lock.json`, `*.d.ts`.
 
 ---
 
-## 7. ExisJS Plugin Ecosystem
-
-The ExisJS configuration file is also where you integrate native plugins and modules.
+## Plugin Integration
 
-You can easily build your own plugins using `defineModule` from `exisjs/module`. Under the hood, plugins get full access to the `app` instance to register routes, providers, or lifecycle hooks!
+Plugins extend framework capabilities by intercepting server configuration or registering global routes:
 
 ```typescript filename="exis.config.ts"
 import { defineConfig } from 'exisjs/config'
 import { defineModule } from 'exisjs/module'
 
-// 1. Create a custom plugin (e.g., a mock GraphQL endpoint)
-const graphqlPlugin = (options: { endpoint: string }) =>
-  defineModule({
-    name: 'graphql',
-    routes: (app) => {
-      app.post(options.endpoint, (req, res) =>
-        res.json({ data: 'GraphQL Response' })
-      )
-    },
-  })
+const metricsPlugin = defineModule({
+  name: 'custom-metrics',
+  routes: (app) => {
+    app.get('/metrics/live', (req, res) => {
+      res.json({ memory: process.memoryUsage() })
+    })
+  }
+})
 
-// 2. Register it in your config
 export default defineConfig({
-  plugins: [graphqlPlugin({ endpoint: '/graphql' })],
+  plugins: [metricsPlugin]
 })
 ```
 
 ---
 
-## 8. Process Model & Multi-Tenancy
-
-ExisJS expects a **One App Per Process** architecture.
-
-### Zero-Config Singletons
-
-ExisJS's highly ergonomic integrations (e.g., `redis.ts`, `prisma.ts`, `s3.ts`) are implemented using ES6 Proxies that cache the underlying clients at the module level. This means they are **process-wide singletons**.
-If you attempt to mount multiple `App` instances inside a single Node.js process to serve different tenants, they will **share the exact same database connections, redis pools, and caches**.
-
-### Multi-Tenant Guidance
-
-If you are building a multi-tenant B2B application, do not boot multiple ExisJS `App` instances per tenant. Instead, use one of the following standard approaches:
-
-1. **Row-Level Tenancy (Recommended)**: Run a single `App` connected to a single database. Use request context or middleware to inject the `tenantId` and scope all queries via Prisma/SQL.
-2. **Factory-Based Clients**: If you need true database-per-tenant isolation, do not use the zero-config singleton exports (like `import { db } from 'exisjs/prisma'`). Instead, manually construct the client factories inside a tenant-resolution middleware and attach them to the request context (`req.tenantDb`).
-3. **Containerized Deployments**: Run separate Node.js processes (Docker containers) for each tenant, passing tenant-specific `DATABASE_URL`s to each container.
-
----
-
-## 9. Graceful Shutdown & Zero-Downtime Deployments
+## Graceful Process Termination
 
-When deploying in Kubernetes, Docker Swarm, AWS ECS, or PM2, containers receive `SIGTERM` signals when being replaced. ExisJS handles graceful shutdown out of the box:
+ExisJS automatically listens for `SIGTERM` and `SIGINT` signals in containerized environments:
 
-1. **Stops Accepting New Connections**: Immediately closes the server listener so load balancers stop routing new traffic to the terminating instance.
-2. **Closes Idle Keep-Alive Connections**: Closes lingering idle HTTP keep-alive sockets instantly via `server.closeIdleConnections()`, preventing the process from hanging.
-3. **Drains In-Flight Requests**: Grants in-flight requests time to finish before terminating.
-4. **Lifecycle Teardown**: Automatically invokes your application's `onStop(app)` hook so you can cleanly disconnect databases, Redis pools, or message brokers.
+1. Closes the HTTP server listener to stop accepting incoming traffic.
+2. Closes idle keep-alive sockets (`server.closeIdleConnections()`).
+3. Executes registered `onStop(app)` hooks to disconnect databases, Redis pools, or message brokers.
 
 ```typescript filename="src/http/server.ts"
 import { exis } from 'exisjs'
-import { db } from './db'
+import { db } from '../database/db'
 
 export default exis({
-  async onStart(app) {
-    await db.connect()
-  },
   async onStop(app) {
-    // Cleanly close database pools when SIGTERM or SIGINT is received
     await db.disconnect()
-  },
+  }
 })
 ```