exisjs 0.7.11 → 0.7.13

package/dist/docs/content/exisjs-mcp.mdx

@@ -1,36 +1,38 @@
 ---
-title: 'AI Assistants (MCP)'
-description: 'Connect AI agents like Claude and Cursor directly to your ExisJS projects.'
+title: "AI Integration (MCP)"
+description: "Model Context Protocol (MCP) server integration for ExisJS documentation lookups and code scaffolding."
+nextUrl: "/docs/cli/overview"
+nextTitle: "CLI Architecture"
 ---
 
-# ExisJS MCP Server
+# ExisJS MCP Server (`@exisjs/mcp`)
 
-The **Model Context Protocol (MCP)** is an open standard that allows AI coding assistants (like Claude, Cursor, and Google Antigravity) to access external tools and data sources.
+The **Model Context Protocol (MCP)** server allows AI coding assistants (such as Google Antigravity, Claude Code, Cursor, and Windsurf) to introspect your ExisJS project, query local framework documentation, and scaffold idiomatic boilerplate code.
 
-ExisJS provides an official MCP Server (`@exisjs/mcp`) that acts as a bridge between your AI agent and your local ExisJS workspace. It empowers the AI with the ability to dynamically read your framework documentation offline and flawlessly scaffold idiomatic ExisJS boilerplate code (routes, plugins, gateways, configurations).
+---
+
+## Overview
 
-<Info title="Why use the MCP?">
-  Without the MCP, AI agents often hallucinate Express or NestJS syntax when asked to write ExisJS code because ExisJS might not be fully present in their training data. By using the ExisJS MCP, the AI reads the exact documentation for your installed version and uses strict generators to scaffold perfect code.
-</Info>
+When developing with ExisJS, external AI models may occasionally generate outdated patterns from other frameworks. The `@exisjs/mcp` server connects your AI assistant directly to your local project environment, ensuring:
 
-## Prerequisites
+1. **Version-Matched Offline Documentation**: The AI queries documentation bundled directly with your project's installed `@exisjs` packages.
+2. **Deterministic Scaffolding**: The AI uses verified code generators for routes, boundaries, validation schemas, plugins, and configuration files across both Functional and OOP paradigms.
 
-- **Node.js (version >= 20.19)** installed on your machine.
-- An AI Coding Assistant that supports the Model Context Protocol (e.g., Claude Code, Cursor, Windsurf, or Google Antigravity).
+---
 
-## Installation
+## Installation & Setup
 
-The easiest way to install the MCP server across all your coding agents is by using the `add-mcp` CLI:
+### Automatic Installation (`add-mcp`)
 
-<div className="my-6 max-w-lg">
-  <CopyCommand command="npx add-mcp @exisjs/mcp@latest" />
-</div>
+You can install `@exisjs/mcp` across all detected local coding agents:
 
-Add `-y` to skip the prompt and install to all detected agents. Add `-g` to install globally across all projects.
+```bash
+npx add-mcp @exisjs/mcp@latest -y
+```
 
 ### Manual Configuration
 
-If you prefer to configure your AI client manually (or are using an unsupported client), you can add the following JSON to your client's MCP settings file:
+Add `@exisjs/mcp` to your IDE's MCP configuration settings (`mcp.json` or settings file):
 
 ```json filename="mcp.json"
 {
@@ -43,55 +45,63 @@ If you prefer to configure your AI client manually (or are using an unsupported
 }
 ```
 
-<details>
-<summary className="cursor-pointer font-medium text-foreground py-2">Claude Code Setup</summary>
+#### Claude Code Setup
 
 Run the following command in your terminal:
+
 ```bash
 claude mcp add exisjs-mcp npx @exisjs/mcp@latest
 ```
-</details>
 
-<details>
-<summary className="cursor-pointer font-medium text-foreground py-2">Cursor Setup</summary>
+#### Cursor Setup
 
-1. Open Cursor Settings.
-2. Navigate to **Features > MCP**.
+1. Open **Cursor Settings** (`Cmd+,` or `Ctrl+,`).
+2. Navigate to **Features** > **MCP**.
 3. Click **+ Add New MCP Server**.
-4. Type: `exisjs-mcp`
-5. Command: `npx -y @exisjs/mcp@latest`
-</details>
+4. Set **Name** to `exisjs-mcp`.
+5. Set **Command** to `npx -y @exisjs/mcp@latest`.
 
-## Available Tools
+---
 
-Once the MCP server is installed and running, your AI assistant automatically gains access to the following capabilities:
+## Available MCP Tools
 
-### 1. Documentation Readers
+Once initialized, the assistant gains access to the following toolset:
 
-ExisJS ships its official markdown documentation directly inside the npm package. The MCP server reads these files locally from your `node_modules`.
+### 1. Documentation Tools
 
-- **`exis_list_local_docs`**: Recursively scans and lists all available ExisJS documentation topics.
-- **`exis_read_local_docs`**: Reads the exact markdown file requested by the AI so it can learn ExisJS best practices.
+| Tool Name | Parameters | Description |
+| :--- | :--- | :--- |
+| `exis_list_local_docs` | `{}` | Scans and lists all available ExisJS documentation topics installed locally in `node_modules`. |
+| `exis_read_local_docs` | `{ topic: string }` | Reads the markdown content for a specific documentation topic. |
 
-*Because this runs locally, the AI reads the exact documentation that matches the ExisJS version installed in your project, preventing version mismatches!*
+### 2. Code Generation & Scaffolding Tools
 
-### 2. Code Generators
+| Tool Name | Parameters | Description |
+| :--- | :--- | :--- |
+| `exis_generate_route` | `{ filePath: string, paradigm: "functional" \| "oop" }` | Scaffolds an idiomatic route controller file (`route.ts`). |
+| `exis_generate_boundary` | `{ filePath: string, paradigm: "functional" \| "oop" }` | Scaffolds a directory boundary middleware file (`boundary.ts`). |
+| `exis_generate_schema` | `{ filePath: string }` | Scaffolds a typed `tex` validation schema file (`schema.ts`). |
+| `exis_generate_plugin` | `{ name: string, filePath?: string }` | Scaffolds an ExisJS plugin module definition. |
+| `exis_generate_config` | `{}` | Scaffolds a baseline `exis.config.ts` configuration file. |
 
-When you ask the AI to build a new feature, it will use these strict scaffolding tools to generate the correct file structures instead of guessing the syntax.
+---
 
-- **`exis_generate_route`**: Scaffolds an idiomatic ExisJS route controller (Functional or OOP).
-- **`exis_generate_plugin`**: Scaffolds a hybrid ExisJS plugin module.
-- **`exis_generate_gateway`**: Scaffolds a WebSockets gateway.
-- **`exis_generate_config`**: Scaffolds the strict `exis.config.ts` configuration system.
+## Practical AI Workflows
 
-## Usage Example
+### Example 1: Querying Framework APIs
 
-Once configured, simply open your ExisJS project in your AI IDE and ask it a question! 
+> **User Prompt**: *"How does dependency injection work with circular references in ExisJS?"*
+>
+> **AI Execution**:
+> 1. Invokes `exis_list_local_docs` to find relevant documentation keys.
+> 2. Invokes `exis_read_local_docs({ topic: "providers" })` to inspect `forwardRef()` and `@Inject()`.
+> 3. Generates the exact solution matching the installed version.
 
-Try asking:
-> *"I want to create a new WebSockets gateway in ExisJS. Can you read the docs on how Gateways work and then scaffold one for me?"*
+### Example 2: Scaffolding a Protected Route
 
-The AI will:
-1. Use `exis_list_local_docs` to find the documentation on Gateways.
-2. Use `exis_read_local_docs` to learn the exact syntax for your ExisJS version.
-3. Use `exis_generate_gateway` to safely write the boilerplate into your codebase.
+> **User Prompt**: *"Scaffold a functional route in src/http/admin/users/route.ts with a validation schema."*
+>
+> **AI Execution**:
+> 1. Invokes `exis_generate_route({ filePath: "src/http/admin/users/route.ts", paradigm: "functional" })`.
+> 2. Invokes `exis_generate_schema({ filePath: "src/http/admin/users/schema.ts" })`.
+> 3. Customizes the handlers to fit the user's business requirements.

package/dist/docs/content/installation.mdx

@@ -1,229 +1,315 @@
 ---
+title: 'Installation & Setup'
+description: 'System prerequisites, project scaffolding options with create-exisjs, manual setup, and TypeScript configuration.'
 nextUrl: '/docs/structure'
 nextTitle: 'Project Structure'
 ---
 
-# Getting Started
+# Installation & Setup
 
-In this guide, you'll learn the core fundamentals of ExisJS. To get familiar with the essential building blocks, we'll scaffold a new project, explore the file structure, and create our very first API server.
+This guide provides step-by-step instructions for creating a new ExisJS application with the `create-exisjs` scaffolding tool or installing the framework manually into an existing TypeScript project.
 
-<Info title="Language Support">
-  We recommend **TypeScript** for type-safety and automatic frontend client generation. However, ExisJS fully supports vanilla JavaScript as well. ExisJS leverages esbuild under the hood, meaning you do not need to manually run `tsc` to start your server.
-</Info>
+---
 
 ## Prerequisites
 
-Please make sure that **Node.js (version >= 20)** is installed on your operating system.
+Before starting, ensure your system satisfies the following requirements:
+
+- **Node.js**: `v20.0.0` or higher
+- **Package Manager**: `npm` (v10+), `pnpm` (v9+), `yarn` (v1.22+ or berry), or `bun` (v1.0+)
+- **Operating System**: macOS, Linux, or Windows (x64 and ARM64 architectures supported)
+
+Verify your Node.js version by running:
+
+```bash
+node -v
+```
+
+---
 
-## Setup
+## Scaffolding a New Project
 
-Setting up a new project can be done using our CLI tool. Open your terminal and run the following command to scaffold a new ExisJS project:
+The quickest way to start a new ExisJS project is with the official `create-exisjs` scaffolding tool.
 
-<div className="my-6 max-w-lg">
-  <CopyCommand command="npm create exisjs@latest my-backend" />
-</div>
+### Interactive Scaffolding
 
-You can also use your package manager of choice:
+Run the creation command using your preferred package manager:
 
 ```bash
 # npm
-$ npm create exisjs@latest my-backend
+npm create exisjs@latest my-api
 
 # pnpm
-$ pnpm create exisjs my-backend
+pnpm create exisjs my-api
 
 # yarn
-$ yarn create exisjs my-backend
+yarn create exisjs my-api
 
 # bun
-$ bun create exisjs my-backend
-
-# npx
-$ npx create-exisjs@latest my-backend
+bun create exisjs my-api
 ```
 
-The CLI will prompt you with a few simple questions to customize your project:
+The CLI prompts you with configuration options:
 
 ```text filename="Terminal"
-√ Would you like to use TypeScript? ... No / Yes
-√ Would you like to use ESLint? ... No / Yes
-√ Would you like your code inside a `src/` directory? ... No / Yes
-√ Would you like to customize the import alias (`@/*` by default)? ... No / Yes
-
-Creating a new Exis JS app in my-backend.
-```
-
-The CLI will then create the `my-backend` directory, install all required dependencies, and populate the project with a conventional base structure.
-
-## Core Files
-
-Once the installation is complete, your project directory will look something like this:
-
-<div className="bg-muted/30 border border-border/50 rounded-md p-4 mb-6 font-mono text-sm">
-  <div className="flex gap-4 mb-2">
-    <span className="text-muted-foreground w-40 shrink-0">exis.config.ts</span>{' '}
-    <span>
-      The root configuration for your application (CORS, Logger, Port).
-    </span>
-  </div>
-  <div className="flex gap-4 mb-2">
-    <span className="text-muted-foreground w-40 shrink-0">src/env.ts</span>{' '}
-    <span>Environment variable validation and typing.</span>
-  </div>
-  <div className="flex gap-4 mb-2">
-    <span className="text-muted-foreground w-40 shrink-0">src/http/</span>{' '}
-    <span>The file-system routing directory.</span>
-  </div>
-  <div className="flex gap-4 mb-2 pl-4">
-    <span className="text-muted-foreground w-36 shrink-0">server.ts</span>{' '}
-    <span>The strict entry point of your application.</span>
-  </div>
-  <div className="flex gap-4 pl-4">
-    <span className="text-muted-foreground w-36 shrink-0">route.ts</span>{' '}
-    <span>A basic GET endpoint mapped to the root route.</span>
-  </div>
-</div>
-
-## Your First Server
-
-Let's look at the generated `src/http/server.ts`. This is the strict entry point of your application, where you can connect to databases and register global plugins.
-
-### Functional Server Setup
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-
-export default exis({
-  async onStart(app) {
-    // 1. Connect to your database
-    // await db.connect()
-    // 2. Register plugins
-    // app.plugin(authPlugin)
-    // The Exis CLI automatically boots the server and file-system routes
-  },
+? What is your project named? › my-api
+? Would you like to use TypeScript? › Yes / No
+? Would you like to use ESLint? › Yes / No
+? Which routing paradigm do you prefer? › Functional (Default) / Class-Based (OOP)
+? Would you like to customize the import alias (`@/*` by default)? › No / Yes
+```
+
+---
+
+### Non-Interactive Command-Line Flags
+
+For automated environments, Docker initialization, or CI/CD pipelines, you can pass command-line flags to skip interactive prompts:
+
+```bash
+npx create-exisjs@latest my-api --ts --functional --eslint --yes
+```
+
+#### Complete CLI Flag Reference
+
+| Flag | Description | Default |
+| :--- | :--- | :---: |
+| `--ts`, `--typescript` | Configure project with TypeScript | `true` |
+| `--js`, `--javascript` | Configure project with plain JavaScript | `false` |
+| `--functional` | Configure project using functional paradigm (`controller()`, `route.*`) | `true` |
+| `--oop` | Configure project using class-based decorator paradigm (`@Controller()`, `@Get()`) | `false` |
+| `--eslint` | Generate ESLint flat config with TypeScript rules | `true` |
+| `--no-eslint` | Skip ESLint setup | `false` |
+| `--skip-install` | Scaffold directory tree and templates without installing dependencies | `false` |
+| `--skip-git` | Skip automatic `git init` initialization | `false` |
+| `--yes`, `-y` | Accept default configuration non-interactively | `false` |
+| `--use-pnpm` | Force dependency installation via `pnpm` | Auto-detected |
+| `--use-bun` | Force dependency installation via `bun` | Auto-detected |
+| `--use-yarn` | Force dependency installation via `yarn` | Auto-detected |
+| `--use-npm` | Force dependency installation via `npm` | Auto-detected |
 
-  async onClose(app) {
-    // Gracefully close database connections here
-    // await db.disconnect()
+---
+
+## Generated Project Layout
+
+Once the scaffolding finishes, your project contains the standard ExisJS directory layout:
+
+```
+my-api/
+├── .agents/
+│   └── rules/
+│       └── AGENTS.md            # Architecture rules and agent guidelines
+├── src/
+│   ├── common/
+│   │   └── guards/
+│   │       └── auth.guard.ts    # Reusable route guards
+│   ├── config/
+│   │   └── env.ts               # Type-safe environment validation (tex.env)
+│   ├── cron/
+│   │   └── cleanup.ts           # Scheduled background tasks
+│   ├── database/
+│   │   └── db.ts                # Database lifecycle and connection
+│   └── http/
+│       ├── health/
+│       │   └── route.ts         # Health check endpoint (/health)
+│       ├── users/
+│       │   ├── route.ts         # User routes (/users)
+│       │   ├── schema.ts        # Input validation schemas (tex.*)
+│       │   └── service.ts       # Service layer logic
+│       ├── boundary.ts          # Root middleware, CORS & error boundary
+│       ├── route.ts             # Root route handler (/)
+│       └── server.ts            # Application lifecycle (onStart / onClose)
+├── tests/
+│   └── users.e2e-spec.ts        # End-to-end test suite
+├── .env                         # Environment variables
+├── .gitignore
+├── .prettierrc
+├── eslint.config.mjs            # ESLint configuration (when selected)
+├── exis.config.ts               # Framework configuration
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Manual Installation
+
+To install ExisJS into an existing repository without scaffolding:
+
+### Step 1: Install Core Dependencies
+
+```bash
+npm install exisjs
+npm install -D typescript @types/node prettier
+```
+
+### Step 2: Configure `tsconfig.json`
+
+Create or update `tsconfig.json` to configure module resolution and metadata reflection:
+
+```json filename="tsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "types": ["node"]
   },
-})
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "*.config.ts",
+    "*.ts"
+  ],
+  "exclude": ["node_modules", ".exis", "dist", "build"]
+}
 ```
 
-### Class-Based (OOP) Server Setup
+> [!NOTE]
+> `experimentalDecorators` and `emitDecoratorMetadata` are required when using the class-based (OOP) paradigm (`@Controller()`, `@Injectable()`).
 
-```typescript filename="src/http/server.ts"
-import { Server } from 'exisjs/decorators'
-import type { App } from 'exisjs'
+### Step 3: Create `exis.config.ts`
 
-@Server()
-export default class RootServer {
-  async onStart(app: App) {
-    // 1. Connect to your database
-    // await db.connect()
-    // 2. Register plugins
-    // app.plugin(authPlugin)
-    // The Exis CLI automatically boots the server and file-system routes
-  }
+Create an `exis.config.ts` file in the project root:
 
-  async onClose(app: App) {
-    // Gracefully close database connections here
-    // await db.disconnect()
-  }
+```typescript filename="exis.config.ts"
+import type { ExisConfig } from 'exisjs/config'
+
+const config: ExisConfig = {
+  port: Number(process.env.PORT) || 4000,
+  host: '0.0.0.0',
+
+  cors: {
+    origin: process.env.CORS_ORIGIN || '*',
+    credentials: true,
+  },
+
+  logger: {
+    level: 'debug',
+    pretty: process.env.NODE_ENV !== 'production',
+  },
+
+  helmet: { enabled: true },
+  compression: true,
 }
+
+export default config
 ```
 
-With ExisJS, the framework automatically handles booting up your server and loading your routes based on the file system. You don't need to manually call `app.listen()`!
+### Step 4: Configure NPM Scripts
 
-## Your First Route
+Add the standard ExisJS CLI commands to `package.json`:
 
-ExisJS uses **folder-based routing**. Your API structure maps directly to your folders in `src/http/`.
+```json filename="package.json"
+{
+  "scripts": {
+    "dev": "exisjs dev",
+    "build": "exisjs build",
+    "start": "exisjs start",
+    "routes": "exisjs routes",
+    "test": "exisjs test",
+    "doctor": "exisjs doctor"
+  }
+}
+```
+
+---
 
-ExisJS supports two primary styles of writing routes: **Functional** and **OOP (Class-based)**. You are free to use whichever paradigm fits your team best.
+## Verifying the Installation
 
-### Functional Routing
+### 1. Create a Health Check Endpoint
 
-Functional routing provides a lean, inference-heavy developer experience similar to modern frontend frameworks. Let's declare our first route in `src/http/users/route.ts`:
+Create `src/http/health/route.ts`:
 
-```typescript filename="src/http/users/route.ts"
+#### Option A: Functional Route
+
+```typescript filename="src/http/health/route.ts"
 import { controller, route } from 'exisjs/router'
 
 export default controller({
-  getUsers: route.get('/', {
-    handle(req) {
-      // Return a realistic response structure
-      return { 
-        data: [
-          { id: 1, name: 'Alice' },
-          { id: 2, name: 'Bob' }
-        ],
-        total: 2 
-      }
-    },
+  check: route.get('/', {
+    summary: 'Service health check',
+    handle: () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+    }),
   }),
 })
 ```
 
-### OOP Routing
-
-If you prefer a highly-structured architecture heavily inspired by Angular and NestJS, ExisJS natively provides robust class-based routing using Decorators:
+#### Option B: Class-Based Route
 
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Req } from 'exisjs/decorators'
-import type { Request } from 'exisjs'
+```typescript filename="src/http/health/route.ts"
+import { Controller, Get, ApiOperation } from 'exisjs/decorators'
 
 @Controller()
-export default class UsersController {
+export default class HealthController {
   @Get('/')
-  getUsers(@Req() req: Request) {
-    // Return a realistic response structure
-    return { 
-      data: [
-        { id: 1, name: 'Alice' },
-        { id: 2, name: 'Bob' }
-      ],
-      total: 2 
+  @ApiOperation({ summary: 'Service health check' })
+  check() {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
     }
   }
 }
 ```
 
-In both examples, because this file is named `route.ts` and is located in the `users` folder, it automatically responds to `GET /users` requests. Whatever you return is automatically serialized to JSON.
+### 2. Start the Development Server
 
-## Running the Application
+Execute the `dev` script:
 
-Your generated `package.json` comes pre-configured with the Exis CLI commands. Start the development server with hot-reload by running:
-
-<div className="my-6 max-w-lg">
-  <CopyCommand command="npm run dev" />
-</div>
+```bash
+npm run dev
+```
 
-You will see the server boot up in your terminal:
+Output:
 
 ```text filename="Terminal"
-6:18:28 pm [exis] starting development server (v0.1.0)...
+[exis] starting development server (v0.7.12)...
+EXIS ready in 125 ms
+
+→ Local:   http://localhost:4000/
+→ Docs:    http://localhost:4000/docs
+→ Network: http://127.0.0.1:4000/
+```
+
+### 3. Verify the Endpoint
 
- EXIS v0.1.0 ready in 125 ms
+Send an HTTP GET request to verify the route:
 
- → Local:   http://localhost:4000/
- → Network: http://10.39.14.177:4000/
- → Environ: development
- → press h + enter to show help
+```bash
+curl http://localhost:4000/health
 ```
 
-Open your browser and navigate to [http://localhost:4000/](http://localhost:4000/) (or the port defined in your `.env`). You will see:
+Expected JSON response:
 
-```json filename="Response"
+```json
 {
-  "data": [
-    {
-      "id": 1,
-      "name": "Alice"
-    },
-    {
-      "id": 2,
-      "name": "Bob"
-    }
-  ],
-  "total": 2
+  "status": "ok",
+  "timestamp": "2026-10-02T11:35:00.000Z"
 }
 ```
+
+Open `http://localhost:4000/docs` in your browser to inspect the interactive Swagger UI.
+
+---
+
+## Next Steps
+
+- **[Project Structure](/docs/structure)**: Review directory conventions for routes, boundaries, services, and database models.
+- **[Routing & Endpoints](/docs/routing)**: Learn how folders map to HTTP verbs, path params, and catch-all routes.
+- **[Validation](/docs/validation)**: Build typed schemas with `tex` for body, query, and header validation.
+- **[Configuration Reference](/docs/config)**: Complete reference of all options in `exis.config.ts`.