exisjs 0.7.12 → 0.7.14

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

@@ -1,241 +1,264 @@
 ---
-nextUrl: "/docs"
-nextTitle: "Introduction"
+title: "CLI Commands"
+description: "Comprehensive command-line reference for all ExisJS development, build, diagnostic, and scaffolding commands."
+nextUrl: "/docs/reference/config"
+nextTitle: "Config Reference"
 ---
 
-# CLI Command Reference
+# CLI Commands
 
-### `exisjs dev`
+The ExisJS CLI provides tools for local development, production compilation, scaffolding, testing, database scripting, and environment auditing.
 
-Starts the development server with live reload and automatic port collision avoidance.
+---
+
+## `exisjs dev`
+
+Starts the development server with live file watching, TypeScript transpilation, and automatic port collision avoidance.
 
 ```bash
-$ npx exisjs dev [options]
+npx exisjs dev [options]
 ```
 
-**Options**
+### Options
 
-| Option | Description |
-| :--- | :--- |
-| `-p, --port <port>` | Port to listen on (overrides `.env` and `exis.config.ts`). |
-| `-H, --host <host>` | Host to bind to (e.g. `0.0.0.0` or `localhost`). |
-| `-e, --entry <file>` | Custom entry file path (default: `src/http/server.ts`). |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-p, --port <port>` | `number` | `3000` | Port to listen on (overrides `.env` and `exis.config.ts`). |
+| `-H, --host <host>` | `string` | `localhost` | Host address to bind to. |
+| `-e, --entry <file>` | `string` | `src/http/server.ts` | Custom entry file path to bootstrap the application. |
 
-- **Automatic Port Collision Detection**: If the designated port is occupied, the CLI detects the conflict and increments to the next available port automatically.
-- **PID Lockfile**: Manages a `.exis/dev.pid` lockfile to prevent accidentally spawning duplicate dev servers in the same directory.
+### Behavior
+- **Port Collision Detection**: If the specified port is in use, the CLI automatically increments to the next open port.
+- **PID Lockfile**: Manages `.exis/dev.pid` to prevent duplicate dev server processes in the same workspace.
 
 ---
 
-### `exisjs build`
+## `exisjs build`
 
-Compiles TypeScript to production JavaScript and produces route manifests.
+Compiles the TypeScript application to production JavaScript, performs type-checking, and generates static route manifests.
 
 ```bash
-$ npx exisjs build [options]
+npx exisjs build [options]
 ```
 
-**Options**
+### Options
 
-| Option | Description |
-| :--- | :--- |
-| `-o, --out-dir <dir>` | Output directory (default: `.exis/server` or `dist`). |
-| `--no-clean` | Skip cleaning the output directory before compilation. |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-o, --out-dir <dir>` | `string` | `.exis/server` | Output directory for compiled JavaScript assets. |
+| `--no-clean` | `boolean` | `false` | Skip cleaning the output directory prior to compilation. |
+| `--skip-env-check` | `boolean` | `false` | Skip build-time route and environment validation checks. |
+| `--dry-run` | `boolean` | `false` | Compile and bundle without halting on missing environment variables. |
+| `-m, --mode <mode>` | `string` | `production` | Environment mode to load (e.g. `production`, `staging`). |
 
-- **Type-Check**: Runs the TypeScript compiler in check-only mode (`noEmit`) to verify strict typing before compiling.
-- **Fast Bundling**: Emits JavaScript via esbuild.
-- **Route Manifest**: Generates `.exis/routes-manifest.js` to enable O(1) route discovery at runtime without filesystem directory walks.
+### Build Outputs
+- Compiles application source code into the specified `outDir`.
+- Emits pre-computed route manifests (`.exis/routes-manifest.js`) for O(1) route discovery at runtime.
+- Generates TypeScript environment definitions (`.exis/exis.d.ts`).
 
 ---
 
-### `exisjs start`
+## `exisjs clean`
 
-Starts the compiled production server.
+Removes temporary build artifacts, compiled files, and cached manifests.
 
 ```bash
-$ npx exisjs start [options]
+npx exisjs clean [options]
+npx exisjs cl [options]
 ```
 
-**Options**
+### Options
 
-| Option | Description |
-| :--- | :--- |
-| `-p, --port <port>` | Port to listen on. |
-| `-H, --host <host>` | Host to bind to. |
-| `-e, --entry <file>` | Custom compiled entry file path. |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-a, --all` | `boolean` | `false` | In addition to `.exis/`, also remove the `dist/` directory. |
+
+---
+
+## `exisjs start`
+
+Starts the compiled production server from the build output directory.
+
+```bash
+npx exisjs start [options]
+```
+
+### Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-p, --port <port>` | `number` | `3000` | Port to listen on. |
+| `-H, --host <host>` | `string` | `0.0.0.0` | Host address to bind to. |
+| `-e, --entry <file>` | `string` | `.exis/server/src/http/server.js` | Custom compiled entry file path. |
 
 ---
 
-### `exisjs generate`
+## `exisjs generate`
 
-Scaffolds framework components and files according to ExisJS core conventions.
+Scaffolds framework components and files according to ExisJS file conventions.
 
 ```bash
-$ npx exisjs generate <type> <name> [options]
-$ npx exisjs g <type> <name> [options]
+npx exisjs generate <type> [name] [options]
+npx exisjs g <type> [name] [options]
 ```
 
-**Arguments**
+### Arguments
 
 | Argument | Description |
 | :--- | :--- |
 | `<type>` | The schematic type to generate. |
-| `<name>` | The name of the feature / folder. |
+| `[name]` | The name of the feature or folder (required for all types except `error`). |
 
-**Options**
+### Options
 
-| Option | Description |
-| :--- | :--- |
-| `-n, --named` | Names generated files using the feature prefix (e.g. `<name>.route.ts`, `<name>.schema.ts`, `<name>.service.ts`). |
-| `--oop` | Generates using Class-Based (OOP) decorators instead of Functional syntax. |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-n, --named` | `boolean` | `false` | Names generated files using the feature prefix (e.g. `user.route.ts`, `user.schema.ts`). |
+| `--oop` | `boolean` | `false` | Generates using Class-Based (OOP) decorators instead of Functional syntax. |
 
-**Supported Schematics**
+### Supported Schematics
 
-| Schematic | Alias | Description | Output Path |
+| Schematic | Alias | Description | Output Location |
 | :--- | :--- | :--- | :--- |
-| `crud` | `resource` | Full 4-file CRUD slice (`schema.ts`, `service.ts`, `route.ts`, and `model.ts` entity), 100% database-agnostic | `src/http/<name>/` & `src/models/` |
-| `model` | | Standalone database-agnostic TypeScript entity and input types | `src/models/<Name>.ts` |
-| `route` | `r`, `c`, `controller` | HTTP route file | `src/http/<name>/route.ts` |
-| `service` | `s` | Injectable service / business logic with pagination helpers | `src/http/<name>/service.ts` |
-| `schema` | `sc` | Validation schemas powered by `tex` (includes pagination) | `src/http/<name>/schema.ts` |
-| `boundary` | `b` | Folder-scoped configuration and request pipeline | `src/http/<name>/boundary.ts` |
-| `plugin` | `p` | Distributable plugin module | `src/plugins/<name>.ts` |
-| `middleware` | `m` | Standalone middleware handler | `src/middleware/<name>.ts` |
-| `test` | `t` | Native test suite | `tests/<name>.test.ts` |
+| `crud` | `resource` | Generates full 4-file CRUD slice (`schema`, `service`, `route`, `model`). | `src/http/<name>/` & `src/models/` |
+| `model` | | Standalone database-agnostic TypeScript entity interface. | `src/models/<Name>.ts` |
+| `route` | `r`, `c`, `controller` | HTTP route endpoint definition. | `src/http/<name>/route.ts` |
+| `service` | `s` | Injectable service with pagination utilities. | `src/http/<name>/service.ts` |
+| `schema` | `sc` | Validation schemas with `tex` validators and pagination DTOs. | `src/http/<name>/schema.ts` |
+| `boundary` | `b` | Folder-level boundary middleware configuration. | `src/http/<name>/boundary.ts` |
+| `cron` | `job` | Scheduled cron background task. | `src/cron/<name>.ts` |
+| `error` | `err` | Global error handler fallback. | `src/http/error.ts` |
+| `plugin` | `p` | Reusable ExisJS plugin module. | `src/plugins/<name>.ts` |
+| `middleware` | `m` | Standalone middleware handler function. | `src/middleware/<name>.ts` |
+| `test` | `t` | Integration test file using `node:test` and `exisjs/testing`. | `tests/<name>.test.ts` |
 
 ---
 
-### `exisjs routes`
+## `exisjs routes`
 
-Analyzes and prints the application routing table to the terminal in an interactive, formatted grid with method badges and dynamic parameter highlighting.
+Inspects and displays the complete application routing table in formatted tabular output or raw JSON.
 
 ```bash
-$ npx exisjs routes [options]
+npx exisjs routes [options]
 ```
 
-**Options**
+### Options
 
-| Option | Description |
-| :--- | :--- |
-| `-e, --entry <file>` | Custom entry file path to bootstrap the app from (default: `src/http/server.ts`). |
-| `-m, --method <method>` | Filter endpoints by HTTP method (e.g. `GET`, `POST`, `PUT`, `DELETE`). |
-| `-f, --filter <keyword>` | Filter endpoints matching path, method, or source file keyword. |
-| `--json` | Output the parsed routes and middleware metadata directly as structured JSON. |
-
-**Features**
-- **Method Badges**: Visually styled badges (`GET`, `POST`, `PUT`, `PATCH`, `DEL`, `ALL`).
-- **Parameter Highlighting**: Dynamically distinguishes path parameters (`:id`, `*slug`).
-- **Middleware Counting**: Displays total attached middleware / boundary steps.
-- **Source Resolution**: Displays relative file source path (e.g. `src/http/users/user.route.ts`).
-- **Summary Metrics**: Displays total endpoint counts and method breakdown.
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-e, --entry <file>` | `string` | `src/http/server.ts` | Custom entry file path to discover routes from. |
+| `-m, --method <method>` | `string` | None | Filter endpoints by HTTP method (e.g. `GET`, `POST`). |
+| `-f, --filter <keyword>` | `string` | None | Filter endpoints by path, method, or source file keyword. |
+| `--json` | `boolean` | `false` | Output routes and middleware metadata in JSON format. |
 
 ---
 
-### `exisjs init`
+## `exisjs test`
 
-Initializes a new ExisJS project in the current directory using `create-exisjs`.
+Runs the test suite using the integrated Node.js test runner (`node:test`).
 
 ```bash
-$ npx exisjs init
+npx exisjs test [files...] [options]
 ```
 
+### Arguments & Options
+
+| Argument / Option | Type | Description |
+| :--- | :--- | :--- |
+| `[files...]` | `string[]` | Specific test files or glob patterns to run. |
+| `--watch` | `boolean` | Watch for file changes and re-execute tests automatically. |
+| `-u, --update` | `boolean` | Update snapshot assertions. |
+| `-e, --entry <file>` | `string` | Custom entry file path to bootstrap before test execution. |
+
 ---
 
-### `exisjs test`
+## `exisjs run`
 
-Runs the native Node.js test runner (`node:test`) across the project.
+Executes standalone scripts, migration utilities, or third-party CLI tools with ExisJS `.env` files automatically loaded into `process.env`.
 
 ```bash
-$ npx exisjs test [files...] [options]
+npx exisjs run <scriptOrCmd> [args...] [options]
+npx exisjs exec <scriptOrCmd> [args...] [options]
 ```
 
-**Options**
-
-| Option | Description |
-| :--- | :--- |
-| `--watch` | Watch for file changes and re-run tests. |
-| `-u, --update` | Update test snapshots. |
-| `-e, --entry <file>` | Custom entry file path to bootstrap before running tests. |
-
----
+### Options
 
-### `exisjs run`
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `-e, --env <file>` | `string` | Path to a specific environment file to load. |
+| `-m, --mode <mode>` | `string` | Environment mode to load (e.g. `production`, `staging`, `development`). |
 
-Executes any standalone TypeScript script, migration runner, or external tool (e.g. `drizzle-kit`, `prisma`, `knex`) with ExisJS `.env` files automatically loaded into `process.env`.
+### Examples
 
 ```bash
-$ npx exisjs run <scriptOrCmd> [args...] [options]
-$ npx exisjs exec <scriptOrCmd> [args...] [options]
+# Execute a TypeScript seed script
+npx exisjs run src/database/seed.ts
+
+# Run an external database CLI with ExisJS environment loaded
+npx exisjs run prisma migrate deploy
+npx exisjs run drizzle-kit push
 ```
 
-**Options**
+---
 
-| Option | Description |
-| :--- | :--- |
-| `-e, --env <file>` | Custom environment file to load. |
-| `-m, --mode <mode>` | Environment mode to load (e.g. `production`, `development`, `staging`). |
+## `exisjs console`
 
-**Examples**
+Starts an interactive Node.js REPL environment loaded with the application context.
 
 ```bash
-# Run Drizzle migrations with auto-loaded .env database credentials
-$ npx exisjs run drizzle-kit push
+npx exisjs console [options]
+npx exisjs repl [options]
+```
 
-# Execute a TypeScript database seed script
-$ npx exisjs run src/database/seed.ts
+### Options
 
-# Run with a custom environment file
-$ npx exisjs run scripts/report.ts --env .env.staging
-```
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `-e, --entry <file>` | `string` | `src/http/server.ts` | Custom entry file to bootstrap REPL context. |
 
 ---
 
-### `exisjs repl`
+## `exisjs doctor`
 
-Starts an interactive Node.js REPL console loaded with your application context.
+Runs an end-to-end diagnostic audit of the local project environment.
 
 ```bash
-$ npx exisjs repl [options]
-$ npx exisjs console [options]
+npx exisjs doctor
 ```
 
-**Options**
-
-| Option | Description |
-| :--- | :--- |
-| `-e, --entry <file>` | Custom entry file path to bootstrap the REPL context. |
+### Diagnostic Checks
+- **Runtime Environment**: Validates Node.js version compatibility (Node.js 18+).
+- **Native Acceleration**: Checks whether `@exisjs/rs` compiled native binaries are active.
+- **Project Structure**: Verifies `package.json`, `tsconfig.json`, and application entry points.
+- **Route Integrity**: Audits `src/http/` directory for naming conventions and orphan files.
 
 ---
 
-### `exisjs exports`
+## `exisjs info`
 
-Lists all available framework exports and public subpaths exposed by `exisjs/*`.
+Prints runtime environment details, including ExisJS version, Node.js version, platform, and operating system architecture.
 
 ```bash
-$ npx exisjs exports
+npx exisjs info
 ```
 
 ---
 
-### `exisjs info`
+## `exisjs exports`
 
-Displays runtime environment, Node.js version, platform, architecture, and ExisJS version.
+Lists all public subpath exports provided by the `exisjs` package.
 
 ```bash
-$ npx exisjs info
+npx exisjs exports
 ```
 
 ---
 
-### `exisjs doctor`
+## `exisjs init`
 
-Performs an end-to-end diagnostic audit of the local project environment, verifying Node.js version compatibility, native Rust hardware acceleration (`@exisjs/rs`), `tsconfig.json` strictness, entry-point resolution, route naming patterns, and file-system route counts.
+Initializes a new ExisJS project interactively in the current working directory.
 
 ```bash
-$ npx exisjs doctor
+npx exisjs init
 ```
 
-**Diagnostic Checks**
-- **Runtime**: Validates Node.js engine compatibility (v18+ recommended for N-API and worker thread pools).
-- **Native Engine**: Verifies `@exisjs/rs` compiled native binaries are active for hardware-accelerated radix tree traversal, off-heap caching, and native JSON serialization.
-- **Project Configuration**: Checks `package.json` root and `tsconfig.json` strict mode.
-- **Routes & Pipeline**: Confirms application entry point (`src/http/server.ts`), discovers active route slices, and flags non-standard or orphan file naming conventions.

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

@@ -1,84 +1,98 @@
 ---
+title: "CLI Overview"
+description: "Architecture, execution modes, and command structure of the ExisJS developer CLI."
 nextUrl: "/docs/cli/usage"
 nextTitle: "CLI Usage"
 ---
 
-# Overview
+# CLI Overview
 
-The ExisJS CLI (`exis` / `exisjs`) is a developer tool that assists in initializing, developing, building, and running ExisJS applications.
+The ExisJS CLI (`exisjs` or `exis`) is the command-line interface for developing, compiling, running, and diagnosing ExisJS applications.
 
-The CLI is engineered around ExisJS core conventions: file-system routing under `src/http/`, schema validation with `tex`, directory-scoped boundaries (`boundary.ts`), and high-performance production builds with route manifests.
+The CLI is structured around ExisJS core conventions:
+- File-system route discovery under `src/http/`.
+- Schema compilation with `tex`.
+- Pre-compiled route manifests (`.exis/routes-manifest.js`) for O(1) runtime lookup.
+- Environment variable cascading (`.env`).
+- Native test execution using `node:test`.
 
-## Installation
+---
+
+## Installation & Execution
 
-The CLI can be run on-demand via `npx` or installed globally via npm:
+### On-Demand via `npx`
+
+Run commands directly without global installation:
 
 ```bash
-# Run on-demand (recommended for scaffolding new projects)
-$ npx exisjs init my-api
+# Initialize a new project in a directory
+npx exisjs init
 
-# Or install globally
-$ npm install -g exisjs
+# Start the dev server
+npx exisjs dev
 ```
 
-Inside an initialized ExisJS project, the CLI is locally available and executed via `npx exisjs` or `npm run <script>`.
-
-## Basic Workflow
+### Global Installation
 
-Once in your terminal, invoke CLI commands directly:
+To install the `exisjs` / `exis` binary globally:
 
 ```bash
-# View help for all commands
-$ npx exisjs --help
-
-# View help for a specific command
-$ npx exisjs generate --help
+npm install -g exisjs
 ```
 
-To create and run a new project:
+### Project-Local Execution
 
-```bash
-$ npx exisjs init my-app
-$ cd my-app
-$ npm run dev
-```
+Inside an initialized ExisJS project, the CLI is available locally through `npm run` scripts or `npx exisjs`.
 
-Open `http://localhost:4000` (or the dynamically resolved available port) to access your running API.
+---
 
-## CLI Command Syntax
+## Command Syntax
 
-All ExisJS CLI commands follow this standard structure:
+All CLI commands adhere to the standard command structure:
 
 ```bash
 exisjs <command> [arguments] [options]
 ```
 
-For example:
+Or using the shorter alias:
 
 ```bash
-# Scaffold a new route with functional syntax
-$ npx exisjs generate route users
+exis <command> [arguments] [options]
+```
+
+### Examples
+
+```bash
+# Start development server on port 5000
+npx exisjs dev -p 5000
 
-# Scaffold with class-based (OOP) decorators
-$ npx exisjs generate route users --oop
+# Scaffold an HTTP route in Functional paradigm
+npx exisjs generate route users
 
-# Use the short alias
-$ npx exisjs g r users --oop
+# Scaffold with Class-Based (OOP) decorators
+npx exisjs generate route users --oop
+
+# Print the application routing table
+npx exisjs routes
 ```
 
-## Command Overview
+---
+
+## Command Summary
 
 | Command | Alias | Description |
 | :--- | :--- | :--- |
-| `dev` | | Starts the development server with HMR and automatic port collision avoidance. |
-| `build` | | Type-checks and compiles TypeScript to production JavaScript with route manifest generation. |
-| `start` | | Runs the compiled production server. |
-| `routes` | | Prints the application routing table to the terminal. |
-| `generate` | `g` | Scaffolds framework slices (resource, route, service, schema, boundary, plugin, middleware, test). |
-| `test` | | Runs the native Node.js test suite (`node:test`) with custom Jest-style reporting. |
-| `run` | `exec` | Executes a script or external tool (e.g. `drizzle-kit`, `prisma`) with auto-loaded `.env`. |
-| `repl` | `console` | Starts an interactive Node.js REPL loaded with the application context. |
-| `exports` | | Displays all available `@exisjs` and `exisjs/*` subpath exports. |
-| `info` | | Displays system, Node.js, and ExisJS runtime information. |
-| `doctor` | | Performs system, native Rust acceleration, TypeScript, and routing diagnostics. |
-| `init` | | Initializes a new ExisJS application in the current directory. |
+| `dev` | | Starts development server with file watching and automatic port collision avoidance. |
+| `build` | | Type-checks and compiles TypeScript to JavaScript, generating route manifests. |
+| `start` | | Starts the compiled production server. |
+| `clean` | `cl` | Removes `.exis` build artifacts and cached manifests (`-a` to include `dist/`). |
+| `routes` | | Analyzes and prints the application routing table to the terminal or JSON. |
+| `generate` | `g` | Scaffolds framework components (`crud`, `model`, `route`, `service`, `schema`, `boundary`, `plugin`, `middleware`, `test`). |
+| `test` | | Runs test suites using the native `node:test` runner. |
+| `run` | `exec` | Executes a script or external command with ExisJS `.env` files pre-loaded. |
+| `console` | `repl` | Launches an interactive Node.js REPL loaded with the application context. |
+| `doctor` | | Audits project health, native Rust bindings, configuration, and route structure. |
+| `info` | | Displays runtime environment, Node.js version, platform, and OS architecture. |
+| `exports` | | Lists all framework public subpath export modules. |
+| `init` | | Initializes an ExisJS application in the current working directory. |
+