exisjs 0.6.1 → 0.7.1

package/dist/docs/content/boundaries.mdx

@@ -0,0 +1,151 @@
+---
+nextUrl: "/docs/validation"
+nextTitle: "Validation"
+---
+
+# Boundaries (Config & Request Pipeline)
+
+A `boundary.ts` acts as a folder-scoped configuration and request pipeline in your file-system routing architecture.
+
+Any `boundary.ts` applies to every route in its folder and all subfolders recursively. Instead of manually registering middleware chains or route guards, placing a `boundary.ts` configures **CORS**, **Headers**, **Excluded Paths**, **Dependency Injection**, and an **auto-detected request pipeline** cleanly scoped to that sub-tree.
+
+---
+
+## Anatomy of a Boundary
+
+A `boundary.ts` has two distinct, independent parts:
+
+1. **Config** — pure data, declared via `defineBoundary()` (functional) or the `@Boundary()` class decorator (OOP). It configures CORS, headers, DI providers, timeout, and exclusion rules.
+2. **Pipeline** — real code, auto-detected by function signature. No manual pipeline registration is needed.
+
+| Signature | Detected as | Execution timing |
+|---|---|---|
+| `(req, res, next)` | Chain Step | Runs in file/declaration order, before the route |
+| `(ctx, next)` — default export (functional) or class method `handle(ctx, next)` (OOP) | Request Wrapper | Wraps around all chain steps and the nested route/boundary |
+
+---
+
+## 1. Functional Paradigm
+
+In functional style, export `config = defineBoundary(...)`, export named middleware functions `(req, res, next)` for chain steps, and optionally provide a `default export` function `(ctx, next)` as an onion-style wrapper.
+
+```typescript filename="src/http/admin/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+import type { Request, Response, Next, BoundaryContext } from 'exisjs/router'
+import { UnauthorizedError } from 'exisjs/error'
+
+// 1. Configuration (CORS, Headers, Exclusions, DI Providers)
+export const config = defineBoundary({
+  cors: {
+    origin: ['https://admin.yourdomain.com'],
+    credentials: true,
+  },
+  headers: {
+    'X-Admin-Api-Version': '2.0',
+  },
+  exclude: [
+    '/admin/health',
+    { path: '/admin/public/*', method: 'GET' }
+  ],
+})
+
+// 2. Chain Step (auto-detected by (req, res, next) signature)
+export function requireAuth(req: Request, res: Response, next: Next) {
+  if (!req.headers['x-api-key']) {
+    throw new UnauthorizedError('Missing API key')
+  }
+  next()
+}
+
+// 3. Wrapper (auto-detected as default export with (ctx, next) signature)
+export default async function (ctx: BoundaryContext, next: Next) {
+  const start = Date.now()
+  try {
+    const result = await next()
+    const duration = Date.now() - start
+    ctx.res.setHeader('X-Response-Time', `${duration}ms`)
+    return { success: true, data: result }
+  } catch (err: any) {
+    return {
+      success: false,
+      error: { message: err.message || 'Internal error' },
+    }
+  }
+}
+```
+
+---
+
+## 2. Class-Based (OOP) Paradigm
+
+In OOP style, decorate a class with `@Boundary(...)`. Named methods taking `(req, res, next)` are auto-detected as chain steps, and a method named `handle(ctx, next)` serves as the request wrapper.
+
+```typescript filename="src/http/admin/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
+import type { Request, Response, Next, BoundaryContext } from 'exisjs/router'
+import { UnauthorizedError } from 'exisjs/error'
+
+@Boundary({
+  cors: {
+    origin: ['https://admin.yourdomain.com'],
+    credentials: true,
+  },
+  headers: {
+    'X-Admin-Api-Version': '2.0',
+  },
+  exclude: ['/admin/health'],
+})
+export default class AdminBoundary {
+  // Chain step
+  requireAuth(req: Request, res: Response, next: Next) {
+    if (!req.headers['x-api-key']) {
+      throw new UnauthorizedError('Missing API key')
+    }
+    next()
+  }
+
+  // Wrapper
+  async handle(ctx: BoundaryContext, next: Next) {
+    const start = Date.now()
+    const result = await next()
+    ctx.res.setHeader('X-Response-Time', `${Date.now() - start}ms`)
+    return result
+  }
+}
+```
+
+---
+
+## Cascading & Inheritance
+
+Boundaries cascade down the directory tree. For instance:
+
+```text
+src/http/
+├── boundary.ts       # Root Boundary (applies to /api/*)
+└── admin/
+    ├── boundary.ts   # Admin Boundary (applies to /api/admin/*)
+    └── users/
+        └── route.ts  # Handled by both Root Boundary and Admin Boundary
+```
+
+1. **Wrappers & Chain Steps**: Outer boundaries execute first. Root wrappers wrap nested wrappers, and root chain steps run before nested chain steps.
+2. **CORS & Headers**: Sub-boundaries inherit and merge or override parent headers and CORS policies.
+3. **Exclusions**: When a route matches an exclusion pattern (e.g. `/admin/health` in `exclude`), that boundary's chain steps and wrappers are bypassed for the request.
+
+---
+
+## Dependency Injection via Providers
+
+Boundaries also act as IoC module scopes. You can scope providers to a directory tree using `providers`:
+
+```typescript filename="src/http/users/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
+import { UsersRepository } from './repository'
+
+export const config = defineBoundary({
+  providers: [
+    ['UsersRepository', { useClass: UsersRepository }],
+  ],
+})
+```

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

@@ -3,212 +3,174 @@ nextUrl: "/docs"
 nextTitle: "Introduction"
 ---
 
-# CLI command reference
+# CLI Command Reference
 
-### `exisjs init`
-
-Creates a new ExisJS project.
-
-```bash
-$ npx exisjs init
-```
-
-**Description**
-Creates and initializes a new ExisJS project. Prompts for configuration options (such as whether to include TypeScript, ESLint, Database integrations, etc.) and generates a boilerplate project structure for you.
-
----
-
-### `exisjs generate`
+### `exisjs dev`
 
-Generates and/or modifies files based on a schematic.
+Starts the development server with live reload and automatic port collision avoidance.
 
 ```bash
-$ npx exisjs generate <type> <name> [options]
-$ npx exisjs g <type> <name> [options]
+$ npx exisjs dev [options]
 ```
 
-**Description**
-Generates new features for your application, such as routes, plugins, middleware, or tests.
-
-**Arguments**
-
-| Argument | Description |
-| :--- | :--- |
-| `<type>` | The type of the feature to generate. See the Schematics table below. |
-| `<name>` | The name of the generated component. |
-
 **Options**
 
 | Option | Description |
 | :--- | :--- |
-| `--oop` | Generate using Class-Based (OOP) paradigm instead of Functional. |
-
-**Schematics**
+| `-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`). |
 
-| Name | Alias | Description |
-| :--- | :--- | :--- |
-| `route` | `r` | Generates a new Route controller. |
-| `plugin` | `p` | Generates a new ExisJS Plugin module. |
-| `middleware` | `m` | Generates a new Middleware function. |
-| `test` | `t` | Generates a new test suite file. |
+- **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.
 
 ---
 
 ### `exisjs build`
 
-Compiles an application or workspace into an output folder.
+Compiles TypeScript to production JavaScript and produces route manifests.
 
 ```bash
 $ npx exisjs build [options]
 ```
 
-**Description**
-Compiles TypeScript to production JavaScript.
-
 **Options**
 
 | Option | Description |
 | :--- | :--- |
-| `-o, --out-dir <dir>` | Output directory (default: dist). |
-| `--no-clean` | Skip cleaning the output directory. |
+| `-o, --out-dir <dir>` | Output directory (default: `.exis/server` or `dist`). |
+| `--no-clean` | Skip cleaning the output directory before compilation. |
+
+- **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.
 
 ---
 
 ### `exisjs start`
 
-Compiles and runs an application from the compiled `dist` directory.
+Starts the compiled production server.
 
 ```bash
 $ npx exisjs start [options]
 ```
 
-**Description**
-Starts the production server by executing the compiled application entry file.
-
 **Options**
 
 | Option | Description |
 | :--- | :--- |
-| `-p, --port <port>` | Port to listen on (overrides `.env`). |
-| `-e, --entry <file>` | Custom compiled entry file path (default: `dist/http/server.js`). |
+| `-p, --port <port>` | Port to listen on. |
+| `-H, --host <host>` | Host to bind to. |
+| `-e, --entry <file>` | Custom compiled entry file path. |
 
 ---
 
-### `exisjs dev`
+### `exisjs generate`
 
-Starts the development server with Hot Module Replacement (HMR) and automatic restarts.
+Scaffolds framework components and files according to ExisJS core conventions.
 
 ```bash
-$ npx exisjs dev [options]
+$ npx exisjs generate <type> <name> [options]
+$ npx exisjs g <type> <name> [options]
 ```
 
-**Description**
-Starts the development server and handles TypeScript compilation on the fly.
-- **Port Detection:** If your requested port is already in use by another process, it detects the collision, automatically increments the port, and binds to the next available one.
-- **Lazy Routing (.exis):** ExisJS leverages the hidden `.exis` folder during development to lazy-load routes on demand.
+**Arguments**
+
+| Argument | Description |
+| :--- | :--- |
+| `<type>` | The schematic type to generate. |
+| `<name>` | The name of the feature / folder. |
 
 **Options**
 
 | Option | Description |
 | :--- | :--- |
-| `-p, --port <port>` | Port to listen on (overrides `.env`). |
-| `-h, --host <host>` | Host to bind to. |
-| `-e, --entry <file>` | Custom entry file path (default: `src/http/server.ts`). |
+| `--oop` | Generates using Class-Based (OOP) decorators instead of Functional syntax. |
+
+**Supported Schematics**
+
+| Schematic | Alias | Description | Output Path |
+| :--- | :--- | :--- | :--- |
+| `resource` | | Complete domain slice (`schema.ts`, `service.ts`, `boundary.ts`, `route.ts`) | `src/http/<name>/` |
+| `route` | `r`, `c`, `controller` | HTTP route file | `src/http/<name>/route.ts` |
+| `service` | `s` | Injectable service / business logic | `src/http/<name>/service.ts` |
+| `schema` | `sc` | Validation schemas powered by `tex` | `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` |
 
 ---
 
-### `exisjs test`
+### `exisjs routes`
 
-Runs the native Node.js test runner (`node:test`) across your project.
+Analyzes and prints the application routing table to the terminal.
 
 ```bash
-$ npx exisjs test [files...] [options]
+$ npx exisjs routes [options]
 ```
 
-**Description**
-Automatically sets up the ExisJS environment and parses TypeScript natively to run tests using the built-in `node:test` runner.
-
-**Arguments**
-
-| Argument | Description |
-| :--- | :--- |
-| `[files...]` | Specific test files or directories to run (optional). |
-
 **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 tests. |
+| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
 
 ---
 
-### `exisjs routes`
+### `exisjs init`
 
-Analyzes your application and prints a tabular representation of your entire routing table to the terminal.
+Initializes a new ExisJS project in the current directory using `@exisjs/create`.
 
 ```bash
-$ npx exisjs routes [options]
+$ npx exisjs init
 ```
 
-**Description**
-Loads your application context and outputs a formatted table showing all registered HTTP routes.
+---
+
+### `exisjs test`
+
+Runs the native Node.js test runner (`node:test`) across the project.
+
+```bash
+$ npx exisjs test [files...] [options]
+```
 
 **Options**
 
 | Option | Description |
 | :--- | :--- |
-| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
+| `--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. |
 
 ---
 
 ### `exisjs repl`
 
-Starts an interactive Read-Eval-Print Loop (REPL) console loaded with your application's context.
+Starts an interactive Node.js REPL console loaded with your application context.
 
 ```bash
 $ npx exisjs repl [options]
 $ npx exisjs console [options]
 ```
 
-**Description**
-Provides an interactive command-line environment with direct access to your application's database, plugins, and services.
-
-**Options**
-
-| Option | Description |
-| :--- | :--- |
-| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
-
 ---
 
 ### `exisjs exports`
 
-Lists all the available framework exports and public APIs exposed by ExisJS.
+Lists all available framework exports and public subpaths exposed by `exisjs/*`.
 
 ```bash
 $ npx exisjs exports
 ```
 
-**Description**
-Outputs a list of everything that can be imported from the `exisjs` package.
-
 ---
 
 ### `exisjs info`
 
-Displays environment and version information for debugging and bug reporting.
+Displays runtime environment, Node.js version, platform, architecture, and ExisJS version.
 
 ```bash
 $ npx exisjs info
 ```
-
-**Description**
-Prints out the current ExisJS version, Node.js version, platform, and architecture.
-
----
-
-## Requirements
-
-ExisJS CLI requires a Node.js binary. We recommend Node.js v20+ to ensure compatibility with modern native features (like the built-in test runner).

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

@@ -5,50 +5,49 @@ nextTitle: "CLI Usage"
 
 # Overview
 
-The ExisJS CLI is a command-line interface tool that helps you initialize, develop, and maintain your ExisJS applications. It assists in scaffolding the project, serving it in development mode, and building the application for production. 
+The ExisJS CLI (`exis` / `exisjs`) is a developer tool that assists in initializing, developing, building, and running ExisJS applications.
 
-An ExisJS application is a standard TypeScript application that needs to be compiled to JavaScript before execution. The CLI provides a standard build and execute process with reasonable defaults, while ensuring developers can access the underlying tools (like `tsc` and `node`) to customize them if necessary.
+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.
 
 ## Installation
 
-You have several options available for managing how your OS command line resolves the location of the `exisjs` binary file. 
-
-You can install the CLI globally using the `npm install -g` command. This provides convenience and ensures the `exisjs` binary is available across your system.
+The CLI can be run on-demand via `npx` or installed globally via npm:
 
 ```bash
+# Run on-demand (recommended for scaffolding new projects)
+$ npx exisjs init my-api
+
+# Or install globally
 $ npm install -g exisjs
 ```
 
-> [!NOTE]
-> Alternatively, you can use `npx exisjs` to run the CLI without installing it globally. This ensures you run the latest version or a managed local version.
+Inside an initialized ExisJS project, the CLI is locally available and executed via `npx exisjs` or `npm run <script>`.
 
-## Basic workflow
+## Basic Workflow
 
-Once installed, you can invoke CLI commands directly from your OS command line through the `exisjs` executable. See the available commands by entering the following:
+Once in your terminal, invoke CLI commands directly:
 
 ```bash
-$ exisjs --help
-```
+# View help for all commands
+$ npx exisjs --help
 
-Get help on an individual command using the `--help` flag. Substitute any command to get detailed help:
-
-```bash
-$ exisjs generate --help
+# View help for a specific command
+$ npx exisjs generate --help
 ```
 
-To create, build, and run a new basic ExisJS project in development mode, navigate to the folder that should be the parent of your new project, and run the following commands:
+To create and run a new project:
 
 ```bash
-$ exisjs init my-project
-$ cd my-project
+$ npx exisjs init my-app
+$ cd my-app
 $ npm run dev
 ```
 
-In your browser, open `http://localhost:3000` to see the new application running. The application will automatically recompile and reload when you change any source files.
+Open `http://localhost:4000` (or the dynamically resolved available port) to access your running API.
 
-## CLI command syntax
+## CLI Command Syntax
 
-All `exisjs` commands follow the same format:
+All ExisJS CLI commands follow this standard structure:
 
 ```bash
 exisjs <command> [arguments] [options]
@@ -57,36 +56,27 @@ exisjs <command> [arguments] [options]
 For example:
 
 ```bash
-$ exisjs generate route users --oop
-```
-
-Here, `generate` is the command, `route` and `users` are the arguments, and `--oop` is the option. 
+# Scaffold a new route with functional syntax
+$ npx exisjs generate route users
 
-Most commands and some options have aliases. For example, `generate` can be invoked as `g`:
+# Scaffold with class-based (OOP) decorators
+$ npx exisjs generate route users --oop
 
-```bash
-$ exisjs g route users --oop
+# Use the short alias
+$ npx exisjs g r users --oop
 ```
 
-## Command overview
-
-Run `exisjs <command> --help` for any of the following commands to see command-specific options.
-
-See [CLI Commands](/docs/cli/commands) for detailed descriptions of each command.
+## Command Overview
 
 | Command | Alias | Description |
 | :--- | :--- | :--- |
-| `init` | | Creates and initializes a new ExisJS project. |
-| `generate` | `g` | Generates features based on schematics (routes, plugins, etc.). |
-| `build` | | Compiles an application into an output folder. |
-| `start` | | Runs an application from the compiled directory. |
-| `dev` | | Starts the development server with hot module replacement. |
-| `test` | | Runs the native Node.js test runner across your project. |
-| `routes` | | Prints a tabular representation of your routing table. |
-| `repl` | `console` | Starts an interactive REPL console loaded with your application context. |
-| `exports` | | Lists all available framework exports. |
-| `info` | | Displays environment and version information. |
-
-## Requirements
-
-The ExisJS CLI requires a Node.js binary. We recommend Node.js v20+ to ensure compatibility with modern native features, such as the built-in test runner.
+| `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. |
+| `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. |
+| `init` | | Initializes a new ExisJS application in the current directory. |

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

@@ -5,19 +5,21 @@ nextTitle: "CLI Commands"
 
 # CLI Usage
 
-The ExisJS CLI can be executed in two primary contexts: **globally** via your operating system's PATH, or **locally** via your project's `package.json` scripts. Understanding the distinction between these execution contexts is critical for maintaining stable development environments.
+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.
 
 ## Global vs. Local Execution
 
-When you install the CLI globally (`npm install -g exisjs`) or run it on-demand via `npx`, the binary operates outside of your project's dependency tree. While this is necessary for initializing new projects, it presents a challenge for long-term maintenance: if two developers have different global versions of the CLI installed, they may experience inconsistent build outputs or behavior.
+When bootstrapping a brand-new project, invoke the initialization tool using `npx`:
 
-To solve this, ExisJS manages its build and execution tools as **local development dependencies**. When you run `exisjs init`, the framework automatically installs the `exisjs` package into your `node_modules` and wires it up to your `package.json` scripts. 
+```bash
+$ npx exisjs init my-api
+```
 
-By executing the CLI through `npm run`, npm automatically resolves the binary to the exact version pinned in your `package.json`, ensuring deterministic behavior across your entire engineering team and CI/CD pipelines.
+Once inside an initialized ExisJS project, execution through `npm run` ensures deterministic behavior pinned to the local `exisjs` version in `node_modules`.
 
 ## Default Package Scripts
 
-Every ExisJS project is scaffolded with a standard set of `package.json` scripts that wrap the underlying CLI commands:
+Every ExisJS project scaffolded with `init` includes the standard script targets in `package.json`:
 
 ```json
 {
@@ -30,32 +32,44 @@ Every ExisJS project is scaffolded with a standard set of `package.json` scripts
 }
 ```
 
-You invoke these scripts using your package manager:
+Invoke these scripts using your package manager:
 
 ```bash
 $ npm run dev
 $ npm run build
 $ npm run start
+$ npm test
 ```
 
 ## Passing Arguments via Scripts
 
-If you need to pass additional arguments or options to the CLI while using package scripts, append a double-dash (`--`) before the CLI options. This instructs npm to pass the remaining arguments directly to the underlying `exisjs` command.
-
-For example, to start the development server on a custom port:
+To pass options through `npm run`, append a double-dash (`--`) before the CLI flags:
 
 ```bash
-$ npm run dev -- --port 4000
+# Start the dev server on port 5000
+$ npm run dev -- -p 5000
+
+# Run a specific test file
+$ npm test -- tests/users.test.ts
 ```
 
-To generate a new route using `npx` (which bypasses the script requirement while still using the local binary):
+Direct commands can also be called via `npx exisjs`:
 
 ```bash
-$ npx exisjs generate route users
+# Scaffold a new resource slice
+$ npx exisjs g resource users
+
+# Print the routing table
+$ npx exisjs routes
+
+# Inspect available public exports
+$ npx exisjs exports
 ```
 
 ## Recommended Workflow
 
-1. Use the global CLI (or `npx exisjs`) **only** for scaffolding new projects (`exisjs init`).
-2. Use the `package.json` scripts (e.g., `npm run dev`) for all day-to-day development, building, and testing.
-3. Use `npx exisjs` inside an existing project directory for one-off commands (like `generate`, `routes`, or `repl`).
+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.