qhttpx 1.8.0

package/dist/tests/task-metrics.test.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("../src/index");
+(0, vitest_1.describe)('Task Metrics', () => {
+    let app;
+    (0, vitest_1.afterEach)(async () => {
+        if (app) {
+            await app.close();
+            app = undefined;
+        }
+    });
+    (0, vitest_1.it)('exposes task metrics in /__qhttpx/metrics', async () => {
+        app = new index_1.QHTTPX();
+        // Register a simple task
+        app.task('simple-task', async () => {
+            // do nothing
+        });
+        const { port } = await app.listen(0, '127.0.0.1');
+        // Enqueue the task a few times
+        await app.enqueue('simple-task', {});
+        await app.enqueue('simple-task', {});
+        // Allow some time for async tasks to complete
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        const response = await fetch(`http://127.0.0.1:${port}/__qhttpx/metrics`);
+        (0, vitest_1.expect)(response.status).toBe(200);
+        const json = (await response.json());
+        (0, vitest_1.expect)(json.tasks).toBeDefined();
+        (0, vitest_1.expect)(json.tasks.registeredTasks).toBe(1);
+        (0, vitest_1.expect)(json.tasks.totalEnqueued).toBe(2);
+        (0, vitest_1.expect)(json.tasks.totalCompleted).toBe(2);
+        (0, vitest_1.expect)(json.tasks.totalFailed).toBe(0);
+        (0, vitest_1.expect)(json.tasks.totalOverloaded).toBe(0);
+    });
+    (0, vitest_1.it)('counts failed tasks', async () => {
+        app = new index_1.QHTTPX();
+        app.task('failing-task', async () => {
+            throw new Error('Task failed');
+        }, { maxRetries: 1 }); // 1 retry
+        const { port } = await app.listen(0, '127.0.0.1');
+        try {
+            await app.enqueue('failing-task', {});
+        }
+        catch {
+        }
+        // Allow time for retry and failure
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        const response = await fetch(`http://127.0.0.1:${port}/__qhttpx/metrics`);
+        const json = (await response.json());
+        (0, vitest_1.expect)(json.tasks.totalFailed).toBe(1);
+        (0, vitest_1.expect)(json.tasks.totalRetried).toBe(1); // 1 retry attempt
+    });
+});

package/dist/tests/tasks.test.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("../src/index");
+(0, vitest_1.describe)('Task engine', () => {
+    (0, vitest_1.it)('registers and executes a task', async () => {
+        const app = new index_1.QHTTPX();
+        const seen = [];
+        app.task('echo', async (payload) => {
+            seen.push(payload);
+        });
+        await app.enqueue('echo', { hello: 'world' });
+        (0, vitest_1.expect)(seen).toHaveLength(1);
+        (0, vitest_1.expect)(seen[0]).toEqual({ hello: 'world' });
+    });
+    (0, vitest_1.it)('retries failing tasks according to maxRetries', async () => {
+        const app = new index_1.QHTTPX();
+        const spy = vitest_1.vi.fn();
+        let attempts = 0;
+        app.task('sometimes-fails', () => {
+            spy();
+            attempts += 1;
+            if (attempts < 3) {
+                throw new Error('fail');
+            }
+        }, { maxRetries: 5 });
+        await app.enqueue('sometimes-fails', null);
+        (0, vitest_1.expect)(spy).toHaveBeenCalledTimes(3);
+    });
+    (0, vitest_1.it)('propagates errors after exceeding retries', async () => {
+        const app = new index_1.QHTTPX();
+        app.task('always-fails', () => {
+            throw new Error('boom');
+        }, { maxRetries: 1 });
+        await (0, vitest_1.expect)(app.enqueue('always-fails', null)).rejects.toThrow('boom');
+    });
+    (0, vitest_1.it)('integrates with HTTP route that enqueues a job', async () => {
+        const app = new index_1.QHTTPX();
+        const seen = [];
+        app.task('job', async (payload) => {
+            seen.push(payload);
+        });
+        app.post('/enqueue', async (ctx) => {
+            const body = ctx.body;
+            await app.enqueue('job', body.value);
+            ctx.json({ ok: true });
+        });
+        const { port } = await app.listen(0, '127.0.0.1');
+        const response = await fetch(`http://127.0.0.1:${port}/enqueue`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ value: 'hello' }),
+        });
+        (0, vitest_1.expect)(response.status).toBe(200);
+        const json = (await response.json());
+        (0, vitest_1.expect)(json.ok).toBe(true);
+        (0, vitest_1.expect)(seen).toEqual(['hello']);
+        await app.close();
+    });
+});

package/dist/tests/testing.test.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const src_1 = require("../src");
+(0, vitest_1.describe)('Testing utilities', () => {
+    (0, vitest_1.it)('creates a test client and handles requests', async () => {
+        const app = new src_1.QHTTPX();
+        app.get('/hello', (ctx) => {
+            ctx.json({ message: 'world' });
+        });
+        app.post('/echo', (ctx) => {
+            ctx.json(ctx.body);
+        });
+        const client = (0, src_1.createTestClient)(app);
+        try {
+            const res1 = await client.get('/hello');
+            (0, vitest_1.expect)(res1.status).toBe(200);
+            (0, vitest_1.expect)(await res1.json()).toEqual({ message: 'world' });
+            const res2 = await client.post('/echo', { foo: 'bar' });
+            (0, vitest_1.expect)(res2.status).toBe(200);
+            (0, vitest_1.expect)(await res2.json()).toEqual({ foo: 'bar' });
+        }
+        finally {
+            await client.stop();
+        }
+    });
+    (0, vitest_1.it)('handles custom headers and raw body', async () => {
+        const app = new src_1.QHTTPX();
+        app.post('/raw', (ctx) => {
+            ctx.send(ctx.req.headers['x-custom']);
+        });
+        const client = (0, src_1.createTestClient)(app);
+        try {
+            const res = await client.post('/raw', 'raw-body', {
+                headers: {
+                    'x-custom': 'custom-value',
+                    'content-type': 'text/plain',
+                },
+            });
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(await res.text()).toBe('custom-value');
+        }
+        finally {
+            await client.stop();
+        }
+    });
+});

package/dist/tests/validation.test.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const server_1 = require("../src/core/server");
+(0, vitest_1.describe)('Validation System', () => {
+    let app;
+    (0, vitest_1.afterEach)(async () => {
+        if (app)
+            await app.close();
+    });
+    (0, vitest_1.it)('should validate request body and return 400 on failure', async () => {
+        app = new server_1.QHTTPX();
+        const schema = {
+            body: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', min: 3 },
+                    age: { type: 'number', min: 18 }
+                }
+            }
+        };
+        app.post('/user', {
+            schema,
+            handler: (ctx) => {
+                ctx.json({ status: 'ok', body: ctx.body });
+            }
+        });
+        const { port } = await app.listen(0);
+        // Invalid request (age too low)
+        const res1 = await fetch(`http://localhost:${port}/user`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: 'Alice', age: 10 })
+        });
+        (0, vitest_1.expect)(res1.status).toBe(400);
+        const data1 = await res1.json();
+        (0, vitest_1.expect)(data1.error).toBe('Validation Error');
+        (0, vitest_1.expect)(data1.details).toContain('age');
+        // Valid request
+        const res2 = await fetch(`http://localhost:${port}/user`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: 'Alice', age: 20 })
+        });
+        (0, vitest_1.expect)(res2.status).toBe(200);
+        const data2 = await res2.json();
+        (0, vitest_1.expect)(data2.body).toEqual({ name: 'Alice', age: 20 });
+    });
+    (0, vitest_1.it)('should validate and coerce query parameters', async () => {
+        app = new server_1.QHTTPX();
+        const schema = {
+            query: {
+                type: 'object',
+                properties: {
+                    page: { type: 'number', min: 1 },
+                    sort: { type: 'string', enum: ['asc', 'desc'] }
+                }
+            }
+        };
+        app.get('/items', {
+            schema,
+            handler: (ctx) => {
+                // ctx.query should have numbers now
+                ctx.json({
+                    page: ctx.query.page,
+                    pageType: typeof ctx.query.page,
+                    sort: ctx.query.sort
+                });
+            }
+        });
+        const { port } = await app.listen(0);
+        // Valid query
+        const res1 = await fetch(`http://localhost:${port}/items?page=5&sort=desc`);
+        (0, vitest_1.expect)(res1.status).toBe(200);
+        const data1 = await res1.json();
+        (0, vitest_1.expect)(data1.page).toBe(5);
+        (0, vitest_1.expect)(data1.pageType).toBe('number'); // Coercion worked
+        (0, vitest_1.expect)(data1.sort).toBe('desc');
+        // Invalid query
+        const res2 = await fetch(`http://localhost:${port}/items?page=0&sort=foo`);
+        (0, vitest_1.expect)(res2.status).toBe(400);
+    });
+    (0, vitest_1.it)('should support legacy response schema (no validation)', async () => {
+        app = new server_1.QHTTPX();
+        // Legacy schema: just a JSON schema at root
+        const schema = {
+            type: 'object',
+            properties: {
+                hello: { type: 'string' }
+            }
+        };
+        app.get('/legacy', {
+            schema,
+            handler: (ctx) => {
+                // If validation ran, it might fail because ctx.body is undefined or not matching
+                // But here we check if it IGNORES validation and uses it for serialization
+                ctx.json({ hello: 'world', extra: 'hidden' });
+            }
+        });
+        const { port } = await app.listen(0);
+        const res = await fetch(`http://localhost:${port}/legacy`);
+        (0, vitest_1.expect)(res.status).toBe(200);
+        const data = await res.json();
+        (0, vitest_1.expect)(data.hello).toBe('world');
+        (0, vitest_1.expect)(data.extra).toBeUndefined(); // fast-json-stringify filters extra fields
+    });
+});

package/dist/tests/websocket.test.js

@@ -0,0 +1,146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const net = __importStar(require("net"));
+const ws_1 = __importDefault(require("ws"));
+const src_1 = require("../src");
+(0, vitest_1.describe)('WebSocket upgrade', () => {
+    (0, vitest_1.it)('handles websocket upgrade for registered path', async () => {
+        const app = new src_1.QHTTPX();
+        let upgraded = false;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        app.upgrade('/ws', (ws, req) => {
+            upgraded = true;
+            ws.close();
+        });
+        const { port } = await app.listen(0, '127.0.0.1');
+        const ws = new ws_1.default(`ws://127.0.0.1:${port}/ws`);
+        await new Promise((resolve, reject) => {
+            ws.on('open', () => {
+                resolve();
+            });
+            ws.on('error', (err) => {
+                reject(err);
+            });
+        });
+        (0, vitest_1.expect)(upgraded).toBe(true);
+        ws.close();
+        await app.close();
+    });
+    (0, vitest_1.it)('destroys socket when no upgrade handler is registered for path', async () => {
+        const app = new src_1.QHTTPX();
+        const { port } = await app.listen(0, '127.0.0.1');
+        const socket = net.createConnection({ port, host: '127.0.0.1' });
+        const done = new Promise((resolve) => {
+            let finished = false;
+            const finish = () => {
+                if (!finished) {
+                    finished = true;
+                    resolve();
+                }
+            };
+            socket.on('end', finish);
+            socket.on('close', finish);
+            socket.on('error', () => {
+                finish();
+            });
+            setTimeout(finish, 500);
+        });
+        const requestLines = [
+            'GET /no-ws HTTP/1.1',
+            'Host: 127.0.0.1',
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            '',
+            '',
+        ];
+        socket.write(requestLines.join('\r\n'));
+        await done;
+        await app.close();
+    });
+    (0, vitest_1.it)('supports rooms and broadcasting', async () => {
+        const app = new src_1.QHTTPX();
+        app.upgrade('/chat', (ws, req) => {
+            const url = new URL(req.url || '', 'http://localhost');
+            const room = url.searchParams.get('room');
+            if (room) {
+                ws.join(room);
+            }
+        });
+        app.post('/broadcast', (ctx) => {
+            const { room, message } = ctx.body;
+            app.websocket.to(room).emit(message);
+            ctx.json({ success: true });
+        });
+        const { port } = await app.listen(0, '127.0.0.1');
+        const baseUrl = `ws://127.0.0.1:${port}/chat`;
+        // Client A in room1
+        const wsA = new ws_1.default(`${baseUrl}?room=room1`);
+        const msgsA = [];
+        wsA.on('message', (data) => msgsA.push(data.toString()));
+        // Client B in room1
+        const wsB = new ws_1.default(`${baseUrl}?room=room1`);
+        const msgsB = [];
+        wsB.on('message', (data) => msgsB.push(data.toString()));
+        // Client C in room2
+        const wsC = new ws_1.default(`${baseUrl}?room=room2`);
+        const msgsC = [];
+        wsC.on('message', (data) => msgsC.push(data.toString()));
+        await Promise.all([
+            new Promise((resolve) => wsA.on('open', () => resolve())),
+            new Promise((resolve) => wsB.on('open', () => resolve())),
+            new Promise((resolve) => wsC.on('open', () => resolve())),
+        ]);
+        // Broadcast to room1
+        // We need to make a POST request.
+        // Since we are inside test, we can use fetch or http.request.
+        // Or just use app.websocket directly if we can access it?
+        // We can access app.websocket directly here since we have app instance.
+        app.websocket.to('room1').emit('hello room1');
+        // Wait a bit for messages
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        (0, vitest_1.expect)(msgsA).toContain('hello room1');
+        (0, vitest_1.expect)(msgsB).toContain('hello room1');
+        (0, vitest_1.expect)(msgsC).not.toContain('hello room1');
+        wsA.close();
+        wsB.close();
+        wsC.close();
+        await app.close();
+    });
+});

package/dist/vitest.config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("vitest/config");
+exports.default = (0, config_1.defineConfig)({
+    test: {
+        include: ['tests/**/*.test.ts'],
+        exclude: ['dist/**', 'node_modules/**'],
+    },
+});

package/docs/AEGIS.md

@@ -0,0 +1,76 @@
+# Aegis Rate Limiter
+
+**Aegis** is a high-performance, Token Bucket-based rate limiter built directly into QHTTPX. It is designed to protect your application from DDoS attacks, brute-force attempts, and API abuse while maintaining ultra-low latency.
+
+## Features
+
+- **Token Bucket Algorithm**: Smooths out traffic spikes while enforcing strict limits.
+- **Zero Dependencies**: Uses an efficient in-memory `Map` by default.
+- **Standard Compliance**: Automatically sets `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` headers.
+- **Flexible Keys**: Limit by IP, API Key, User ID, or any custom logic.
+- **Extensible Storage**: Interface-ready for Redis or other distributed stores.
+
+## Usage
+
+Import `rateLimit` from the middleware package:
+
+```typescript
+import { QHTTPX } from 'qhttpx';
+import { rateLimit } from 'qhttpx/middleware';
+
+const app = new QHTTPX();
+
+// 1. Global DDoS Protection
+app.use(rateLimit({
+  windowMs: 60 * 1000, // 1 minute
+  max: 100, // Limit each IP to 100 requests per window
+  message: { error: 'Too many requests, slow down!' }
+}));
+
+// 2. API Key Limits (Tiered)
+app.use(rateLimit({
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 5000,
+  keyGenerator: (ctx) => ctx.req.headers['x-api-key'] || ctx.req.socket.remoteAddress
+}));
+
+app.get('/', (ctx) => ctx.json({ message: 'Welcome!' }));
+
+app.listen(3000);
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|Params|---|---|---|
+| `windowMs` | `number` | `60000` | Time frame for which requests are checked/remembered. |
+| `max` | `number` | `100` | Max number of connections during `windowMs` before sending a 429 response. |
+| `message` | `string` \| `object` | `"Too many requests..."` | Error message returned to the client. |
+| `statusCode` | `number` | `429` | HTTP status code returned. |
+| `headers` | `boolean` | `true` | Enable/disable `X-RateLimit-*` headers. |
+| `keyGenerator` | `(ctx) => string` | `IP Address` | Function to generate a unique key for the client. |
+| `skip` | `(ctx) => boolean` | `undefined` | Function to bypass the limiter. |
+| `store` | `RateLimitStore` | `MemoryStore` | Custom storage backend (e.g., Redis). |
+
+## Custom Storage (Redis Example)
+
+You can easily swap the in-memory store for Redis to share limits across a cluster:
+
+```typescript
+import { RateLimitStore } from 'qhttpx/middleware';
+
+class RedisStore implements RateLimitStore {
+  constructor(private redis: RedisClient) {}
+
+  async increment(key: string, windowMs: number) {
+    // Implement Redis INCR + EXPIRE logic
+  }
+  
+  async decrement(key: string) { ... }
+  async reset(key: string) { ... }
+}
+
+app.use(rateLimit({
+  store: new RedisStore(redisClient)
+}));
+```

package/docs/BENCHMARKS.md

@@ -0,0 +1,36 @@
+# QHTTPX Benchmarks (Phase 8)
+
+This project includes a simple benchmark harness using `autocannon` to measure basic JSON response performance.
+
+## Setup
+
+Install dev dependencies:
+
+```bash
+npm install
+```
+
+## Run the benchmark
+
+```bash
+npm run bench
+```
+
+This will:
+
+- Build the TypeScript sources
+- Start a temporary QHTTPX server
+- Run an `autocannon` benchmark against `GET /json`
+- Shut down the server when the run completes
+
+## Scenario
+
+The current scenario measures:
+
+- Simple JSON endpoint: `GET /json`
+- Connections: 100
+- Pipelining: 10
+- Duration: 10 seconds
+
+You can adjust these parameters in `src/benchmarks/simple-json.ts`.
+

package/docs/CAPABILITIES.md

@@ -0,0 +1,70 @@
+# QHTTPX Capabilities & Limitations
+
+This document outlines the operational boundaries of the QHTTPX framework, detailing what it handles natively and what lies outside its scope. It is designed to help architects and developers decide if QHTTPX is the right tool for their specific use case.
+
+## ✅ What QHTTPX Handles (Core Capabilities)
+
+QHTTPX is designed first and foremost as a **high-concurrency runtime**. Its features focus on performance, stability under load, and operational efficiency.
+
+### 1. High-Performance Traffic Management
+*   **Request Fusion Engine (Layer 2 Coalescing)**: Automatically collapses simultaneous identical requests (same method, route, query, body) into a single execution. Ideal for high-traffic endpoints with "thundering herd" problems.
+*   **Aegis Rate Limiter**: A built-in, token-bucket based rate limiter that protects the application layer. Supports custom key generators (IP, API Key) and standard rate-limit headers.
+*   **Backpressure & Overload Protection**: Automatically detects CPU and memory pressure. It can queue requests or reject them gracefully (503 Service Unavailable) to prevent crashes, rather than stalling the event loop.
+
+### 2. Scalability & Runtime
+*   **Auto-Scaling Workers**: The CLI (`qhttpx start`) supports a cluster mode that automatically spawns workers based on available CPU cores (`workers: 'auto'`).
+*   **Hot Reload**: The `qhttpx dev` command provides instant feedback during development using `tsx` and filesystem watching.
+*   **Async-First Architecture**: The scheduler is designed to prioritize non-blocking tasks, ensuring that background jobs and HTTP requests share resources efficiently without starving each other.
+
+### 3. Modular Architecture
+*   **The Extension Protocol (Plugins)**: A robust plugin system allowing encapsulated modules. Supports `app.register()` with URL prefixes (scoped routing), making it easy to build modular monoliths or microservices.
+*   **Radix-Tree Routing**: Ultra-fast, O(1) static route resolution. Zero regex overhead for standard routes.
+
+### 4. Database Optimization
+*   **Query Fusion**: When using supported adapters (like SQLite), QHTTPX can automatically batch multiple individual `SELECT` queries into a single `IN (...)` query, reducing database round-trips significantly.
+*   **Dynamic Adapters**: Supports a driver-agnostic adapter pattern. Drivers (pg, better-sqlite3, mongodb) are optional peer dependencies, keeping the core bundle small.
+
+### 5. Developer Experience & Tooling
+*   **RPC Client (`hc`)**: A Hono-like RPC client that provides end-to-end type safety for frontend applications consuming QHTTPX APIs.
+*   **Structured Logging**: Built-in integration with `pino` for JSON-structured logs, essential for modern observability stacks.
+*   **CLI Scaffolding**: `qhttpx new` command to quickly bootstrap best-practice TypeScript projects.
+
+### 7. Extended Web Capabilities
+*   **Multipart Support**: Native support for `multipart/form-data` (file uploads) using Busboy integration. Files are automatically parsed and available in `ctx.files`.
+*   **View Engine**: Support for template engines via `ViewEngine` interface and `ctx.render()`.
+*   **Validation**: Extensible validation system with `ctx.validate()`. Includes a built-in `SimpleValidator` and supports **Zod** integration.
+*   **WebSocket Rooms**: Enhanced WebSocket support with Rooms/Channels and broadcasting capabilities.
+*   **Compression**: Smart compression middleware (Gzip/Brotli/Deflate) with thresholding and stream piping.
+*   **Server-Sent Events (SSE)**: Native support for real-time one-way event streaming via `createSSE()`.
+*   **Advanced Static Files**: Streaming support, `Range` requests (partial content/video), and HTTP Caching (`ETag`, `Last-Modified`) for high-performance asset serving.
+
+### 8. Ecosystem Compatibility (SaaS Ready)
+QHTTPX is an **Open Runtime**. It does not lock you into specific vendors.
+*   **Bring Your Own Stack**: Fully compatible with `jose` (JWT), `ioredis` (Caching), `Prisma`/`Drizzle` (ORM), and `@aws-sdk`.
+*   **Middleware Freedom**: The `(ctx, next)` signature allows easy integration of any logic.
+*   **[Read the Ecosystem Guide](./ECOSYSTEM.md)** for patterns on integrating Auth, Redis, and S3.
+
+---
+
+## ❌ What QHTTPX Does NOT Handle (Limitations)
+
+QHTTPX is a **runtime/micro-framework**, not a "batteries-included" monolith like NestJS, AdonisJS, or Laravel.
+
+### 1. No Built-in ORM
+*   **Limitation**: QHTTPX provides *adapters* to connect to databases and run raw queries (or fused queries), but it does **not** provide an Object-Relational Mapper (ORM).
+*   **Workaround**: You must use external ORMs like Prisma, Drizzle, or TypeORM if you need entity management, migrations, or complex relationship handling.
+
+### 2. No Built-in Authentication Strategies
+*   **Limitation**: There is no "Passport.js" equivalent built-in. No native OAuth, JWT signing, or Session management logic beyond setting cookies.
+*   **Workaround**: You are responsible for implementing auth logic (e.g., using `jose` for JWTs, or integrating with Auth0/Clerk). Middleware guards can be easily written, but the logic is yours to own.
+
+---
+
+## Summary: When to use QHTTPX?
+
+| Use QHTTPX If... | Do NOT Use QHTTPX If... |
+| :--- | :--- |
+| You need **maximum requests/second** on limited hardware. | You need a full-stack MVC with ORM included. |
+| You are building **high-traffic microservices**. | You want "Auth & User Management" pre-built. |
+| You face "thundering herd" issues (Request Fusion solves this). | |
+| You prefer **control** over magic (manual DB queries, custom auth). | |

package/docs/CLI.md

@@ -0,0 +1,43 @@
+# QHTTPX CLI
+
+The QHTTPX Command Line Interface (QCLI) is your companion for developing and deploying QHTTPX applications.
+
+## Installation
+
+The CLI is included with `qhttpx`. You can run it via `npx` or by adding a script to your `package.json`.
+
+```bash
+# Run directly
+npx qhttpx <command>
+
+# Or add to package.json
+"scripts": {
+  "dev": "qhttpx dev src/index.ts",
+  "start": "qhttpx start dist/index.js"
+}
+```
+
+## Commands
+
+### `dev <entry>`
+Starts the application in **Development Mode**.
+- **Hot Reload**: Automatically restarts the server when files change.
+- **TypeScript Support**: Uses `tsx` to run `.ts` files directly.
+- **Watcher**: Recursively watches your source directory.
+
+```bash
+npx qhttpx dev src/server.ts
+```
+
+### `start <entry>`
+Starts the application in **Production Cluster Mode**.
+- **Cluster**: Automatically forks workers equal to the number of CPU cores.
+- **Resilience**: Automatically restarts workers if they crash.
+- **Zero-Downtime**: (Coming soon) Rolling updates.
+
+```bash
+npx qhttpx start dist/server.js
+```
+
+### `new <name>`
+(Coming Soon) Scaffolds a new QHTTPX project with best practices.