@martel/calyx 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.2.0](https://github.com/bmartel/calyx/compare/v1.1.0...v1.2.0) (2026-07-01)
+
+
+### Features
+
+* enhance CLI new command with Dockerfile and Bun-native lifecycle scripts ([8037a35](https://github.com/bmartel/calyx/commit/8037a35a771e222398168b19cb77ad9ccfa2c49a))
+
+# [1.1.0](https://github.com/bmartel/calyx/compare/v1.0.0...v1.1.0) (2026-07-01)
+
+
+### Features
+
+* implement reflector, setMetadata, headers tuning, and Bun-native CLI ([5ebb132](https://github.com/bmartel/calyx/commit/5ebb132a05aea49da9a11fda9dff60e651393884))
+
 # 1.0.0 (2026-07-01)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 Calyx is a high-performance, compile-ready, Bun-native TypeScript API framework modeled after the modular architecture and design patterns of **NestJS**. 
 
-It provides 100% conceptual and syntax compatibility, letting developers easily migrate NestJS applications to a native Bun runtime for **~2.5x higher throughput** and **3.5x lower latency**, with the option to compile the server directly into a single self-contained binary file.
+It provides 100% conceptual and syntax compatibility, letting developers easily migrate NestJS applications to a native Bun runtime for **up to 4.7x higher throughput** and **5.6x lower latency**, with the option to compile the server directly into a single self-contained binary file.
 
 ---
 
@@ -10,71 +10,67 @@ It provides 100% conceptual and syntax compatibility, letting developers easily
 
 *   **⚡ Blazing Fast**: Engineered natively on `Bun.serve`, utilizing a fast radix routing engine and optimized request lifecycle executions.
 *   **🧩 NestJS Decorators Compatibility**: Direct mappings of `@Module()`, `@Injectable()`, `@Controller()`, `@UseGuards()`, `@UseInterceptors()`, `@UsePipes()`, and `@UseFilters()`.
-*   **📦 High Performance DI**: Fully featured Dependency Injection container with circular dependency protection, supporting custom (`useValue`/`useClass`/`useFactory`) and dynamic modules with **29x lower bootstrapping overhead**.
+*   **📦 High Performance DI**: Fully featured Dependency Injection container with circular dependency protection, supporting custom (`useValue`/`useClass`/`useFactory`) and dynamic modules with **18x lower bootstrapping overhead**.
 *   **🛡️ Complete Request Lifecycle**: Clean request pipelines with Guards, Interceptors, Pipe transforms (with metadata), and target exception Filters.
 *   **🚀 Binary Compilation**: Compiles down to a single standalone executable binary with zero external runtime dependencies using `bun build --compile`.
 
 ---
 
-## Installation
+## Getting Started (Quick Start)
 
-Initialize your project and install Calyx with your package manager:
+The easiest way to get started with Calyx is using the Bun-native CLI tool:
 
+### 1. Scaffold a New Project
 ```bash
-bun add @martel/calyx reflect-metadata
+bunx @martel/calyx new my-app
 ```
 
-Ensure your `tsconfig.json` has legacy decorators enabled:
+### 2. Run the Development Server (Watch Mode)
+```bash
+cd my-app
+bun run start:dev
+```
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
+### 3. Generate Components
+Generate modules, controllers, or service providers with automatic parent module registration:
+```bash
+bunx @martel/calyx g controller users
+bunx @martel/calyx g service users
+```
+
+### 4. Build and Compile Standalone Binary
+Calyx compiles your entire application into a single self-contained binary file with zero dependencies:
+```bash
+bun run build:compile
+./dist/server
+```
+
+### 5. Deploy with Docker
+Run your compiled binary in a secure, minimal multi-stage Docker container (under **40MB** total image size, containing no `node_modules` or runtime dependencies):
+```bash
+docker build -t my-app .
+docker run -p 3000:3000 my-app
 ```
 
 ---
 
-## Quick Start
+## Manual Installation
 
-```typescript
-import 'reflect-metadata';
-import { Module, Injectable, Controller, Get, Query, UseGuards, CanActivate, ExecutionContext, VerdantFactory } from '@martel/calyx';
+If you prefer to set up Calyx manually in an existing project:
 
-// 1. Define a Guard
-@Injectable()
-class AuthGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
-    const req = context.switchToHttp().getRequest<Request>();
-    return req.headers.get('Authorization') === 'secret-token';
-  }
-}
+```bash
+bun add @martel/calyx reflect-metadata
+```
 
-// 2. Define a Controller
-@Controller('items')
-class ItemsController {
-  @Get()
-  @UseGuards(AuthGuard)
-  getItems(@Query('limit') limit?: string) {
-    return { data: ['item1', 'item2'], limit: limit ? Number(limit) : 10 };
-  }
-}
+Ensure your `tsconfig.json` has legacy decorators enabled:
 
-// 3. Define a Module
-@Module({
-  controllers: [ItemsController],
-})
-class AppModule {}
-
-// 4. Bootstrap Server
-async function bootstrap() {
-  const app = await CalyxFactory.create(AppModule);
-  await app.listen(3000);
-  console.log('Calyx application is running on port 3000');
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
 }
-bootstrap();
 ```
 
 ---
@@ -85,9 +81,9 @@ Measured using process-isolated `autocannon` benchmarks (100 connections, 8s, no
 
 | Benchmark | Calyx (Bun Native) | NestJS (Express on Bun) | Speedup | Latency Improvement |
 | :--- | :--- | :--- | :--- | :--- |
-| **DI Bootstrapping** | **7.81 μs** | 227.56 μs | **~29x faster** | N/A |
-| **Raw Route Throughput** | **59,408 req/sec** | 23,148 req/sec | **2.57x faster** | **3.5x lower** (1.10ms vs 3.88ms) |
-| **Lifecycle Pipeline (Guards/Pipes)** | **25,152 req/sec** | 10,274 req/sec | **2.45x faster** | **2.8x lower** (3.25ms vs 9.28ms) |
+| **DI Bootstrapping** | **11.73 μs** | 220.39 μs | **18.79x faster** | N/A |
+| **Raw Route Throughput** | **63,356 req/sec** | 23,796 req/sec | **2.66x faster** | **3.4x lower** (1.05ms vs 3.61ms) |
+| **Lifecycle Pipeline (Guards/Pipes)** | **47,568 req/sec** | 9,961 req/sec | **4.78x faster** | **5.6x lower** (1.70ms vs 9.57ms) |
 
 ---
 
@@ -95,6 +91,7 @@ Measured using process-isolated `autocannon` benchmarks (100 connections, 8s, no
 
 For detailed guides, API reference, and examples, refer to the documentation in the repository:
 
+*   📖 **[Calyx CLI Reference](file:///e:/code/verdant/docs/cli.md)**: Scaffolding, schematic boilerplate generation, and watch modes.
 *   📖 **[Dependency Injection & Module System](file:///e:/code/verdant/docs/dependency-injection.md)**: Custom providers, modular structures, and resolution visibility.
 *   📖 **[Controllers & Routing](file:///e:/code/verdant/docs/controllers.md)**: HTTP request handlers, parameters, redirects, and manual response wrappers.
 *   📖 **[Request Lifecycle Pipeline](file:///e:/code/verdant/docs/lifecycle.md)**: How Guards, Interceptors, Pipes, and Exception Filters interact.

package/docs/cli.md

@@ -0,0 +1,154 @@
+# Calyx CLI
+
+Calyx CLI is a lightweight, Bun-native command-line utility built to replace the standard Nest CLI. It is written in TypeScript and executes natively using Bun, enabling fast project scaffolding, code generation, hot-reloading dev servers, and single-file bundling.
+
+---
+
+## Installation
+
+The CLI is bundled directly into the `@martel/calyx` package. You can run it on-demand using `bunx`:
+
+```bash
+bunx @martel/calyx --help
+```
+
+To install the CLI globally:
+
+```bash
+bun install -g @martel/calyx
+```
+
+---
+
+## Core Commands
+
+### 1. `calyx new <project-name>`
+Scaffolds a new, fully configured Calyx application with the recommended folder structure, initializes `tsconfig.json` with decorator metadata settings, and runs `bun install` automatically.
+
+```bash
+calyx new my-awesome-app
+```
+
+#### Generated Project Structure
+```text
+my-awesome-app/
+├── src/
+│   ├── app.controller.ts
+│   ├── app.module.ts
+│   ├── app.service.ts
+│   └── main.ts
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+### 2. `calyx generate` (or `g`)
+Generates boilerplate files for core Calyx components and automatically registers them in the nearest parent Module (e.g., updating the `controllers` or `providers` metadata array).
+
+**Usage:**
+```bash
+calyx g <schematic> <name>
+```
+
+#### Supported Schematics
+
+| Schematic | Shortcut | Description |
+| :--- | :--- | :--- |
+| `module` | `module` | Creates a new module file |
+| `controller` | `controller` | Creates a controller and registers it in the module |
+| `service` | `service` | Creates a service provider and registers it in the module |
+
+#### Examples
+```bash
+# Generate a new users module
+calyx g module users
+
+# Generate a new users controller and register it in UsersModule
+calyx g controller users
+
+# Generate a new users service provider and register it in UsersModule
+calyx g service users
+```
+
+---
+
+### 3. `calyx start`
+Runs the application from the entrypoint `src/main.ts`.
+
+```bash
+# Start standard execution
+calyx start
+
+# Start dev server with built-in hot reloading (Watch Mode)
+calyx start --watch
+# or shortcut:
+calyx start -w
+```
+
+---
+
+### 4. `calyx build`
+Bundles the application into a single production file (`dist/main.js`) using Bun's native compiler.
+
+```bash
+calyx build
+```
+
+---
+
+### 5. `calyx info`
+Displays current environment and system details, including Calyx version, Bun version, and OS.
+
+```bash
+calyx info
+```
+
+---
+
+## Scaffolding Lifecycle & Deployments
+
+When a new project is created with `calyx new`, it is pre-configured with industry-best practices for development, testing, compiling, and container deployment.
+
+### Bun-Native NPM Scripts
+The generated `package.json` includes the following scripts:
+
+| Command | Action | Description |
+| :--- | :--- | :--- |
+| `bun run start` | `calyx start` | Starts the production server |
+| `bun run start:dev` | `calyx start --watch` | Runs the server with hot-reloading |
+| `bun run build` | `calyx build` | Bundles TS assets into `dist/main.js` |
+| `bun run build:compile` | `bun build --compile` | Compiles application into a single standalone binary |
+| `bun run test` | `bun test` | Runs the Bun-native test runner |
+| `bun run test:watch` | `bun test --watch` | Runs tests in interactive watch mode |
+| `bun run test:cov` | `bun test --coverage` | Outputs test coverage details |
+| `bun run format` | `bunx prettier --write` | Standardizes format across project files |
+
+### Portability & Production Deployments (Docker)
+Calyx supports high-performance Docker builds out-of-the-box. A multi-stage `Dockerfile` is automatically scaffolded in the root folder.
+
+It compiles your TypeScript application into a **single self-contained binary** in the builder stage, and copies *only* the binary into a minimal Alpine linux image:
+
+```dockerfile
+# Multistage build for high performance, portability, and minimal size
+FROM oven/bun:1.1-alpine AS builder
+WORKDIR /app
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile || bun install
+COPY . .
+RUN bun run build:compile
+
+# Production runner (Distroless-style minimal Alpine)
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+WORKDIR /app
+COPY --from=builder /app/dist/server ./server
+EXPOSE 3000
+CMD ["./server"]
+```
+
+#### Why This is Optimized for Deployments:
+* **Size:** Under **40MB** total image size (compared to ~300MB+ for standard Node/Nest Docker images).
+* **Security:** Contains **no node_modules, no Bun/Node runtimes, and no source code files** in the final production stage. It only has your single executable.
+* **Speed:** The binary is pre-compiled for production, yielding faster startup times and maximum throughput.
+

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@martel/calyx",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
+  "bin": {
+    "calyx": "./src/cli/index.ts"
+  },
   "type": "module",
   "scripts": {
     "test": "bun test",

package/src/cli/index.ts

@@ -0,0 +1,368 @@
+#!/usr/bin/env bun
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+
+const args = Bun.argv.slice(2);
+const command = args[0];
+
+if (!command) {
+  printHelp();
+  process.exit(0);
+}
+
+switch (command) {
+  case 'info':
+    runInfo();
+    break;
+  case 'start':
+    runStart(args.slice(1));
+    break;
+  case 'build':
+    runBuild(args.slice(1));
+    break;
+  case 'new':
+    runNew(args[1]);
+    break;
+  case 'generate':
+  case 'g':
+    runGenerate(args[1], args[2]);
+    break;
+  default:
+    console.log(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+
+function printHelp() {
+  console.log(`
+Calyx CLI - Bun-native NestJS-compatible Framework CLI
+
+Usage:
+  calyx <command> [options]
+
+Commands:
+  new <name>            Scaffold a new Calyx application
+  generate, g <type> <name>   Generate a new schematic element (module, controller, service)
+  start                 Start the application
+    -w, --watch         Enable hot reload / watch mode
+  build                 Bundle the application using Bun compiler
+  info                  Display system and environment details
+  `);
+}
+
+function runInfo() {
+  console.log(`
+Calyx CLI Information:
+  Calyx Version: 0.1.0
+  Bun Version:   ${Bun.version}
+  OS Platform:   ${process.platform}
+  Node Compatibility: Yes
+  `);
+}
+
+function runStart(cmdArgs: string[]) {
+  const isWatch = cmdArgs.includes('--watch') || cmdArgs.includes('-w');
+  const mainPath = 'src/main.ts';
+
+  if (!existsSync(mainPath)) {
+    console.error(`Error: Cannot find entrypoint "${mainPath}". Make sure you are in a Calyx project root.`);
+    process.exit(1);
+  }
+
+  const spawnArgs = isWatch ? ['--watch', mainPath] : [mainPath];
+  console.log(`Starting Calyx application... (${isWatch ? 'Watch Mode' : 'Standard Mode'})`);
+  
+  const proc = spawnSync('bun', spawnArgs, { stdio: 'inherit' });
+  process.exit(proc.status ?? 0);
+}
+
+function runBuild(cmdArgs: string[]) {
+  const mainPath = 'src/main.ts';
+  if (!existsSync(mainPath)) {
+    console.error(`Error: Cannot find entrypoint "${mainPath}". Make sure you are in a Calyx project root.`);
+    process.exit(1);
+  }
+
+  console.log('Building Calyx application using bun build...');
+  const proc = spawnSync('bun', ['build', mainPath, '--outdir', './dist', '--target', 'bun'], { stdio: 'inherit' });
+  if (proc.status === 0) {
+    console.log('Build completed successfully. Output at ./dist/main.js');
+  }
+  process.exit(proc.status ?? 0);
+}
+
+function runNew(name: string) {
+  if (!name) {
+    console.error('Error: Please specify the project name. Example: calyx new my-app');
+    process.exit(1);
+  }
+
+  if (existsSync(name)) {
+    console.error(`Error: Directory "${name}" already exists.`);
+    process.exit(1);
+  }
+
+  console.log(`Scaffolding new Calyx application in "${name}"...`);
+
+  mkdirSync(name, { recursive: true });
+  mkdirSync(join(name, 'src'), { recursive: true });
+
+  // Write package.json
+  const isDevMode = existsSync(join(import.meta.dir, '../../package.json'));
+  const calyxDependency = isDevMode ? "link:../.." : "^0.1.0";
+
+  const packageJson = {
+    name,
+    version: '0.0.1',
+    description: 'Calyx application',
+    type: 'module',
+    scripts: {
+      "start": "calyx start",
+      "start:dev": "calyx start --watch",
+      "build": "calyx build",
+      "build:compile": "bun build src/main.ts --compile --outfile dist/server",
+      "test": "bun test",
+      "test:watch": "bun test --watch",
+      "test:cov": "bun test --coverage",
+      "format": "bunx prettier --write \"src/**/*.ts\""
+    },
+    dependencies: {
+      "@martel/calyx": calyxDependency,
+      "reflect-metadata": "^0.2.2"
+    }
+  };
+  writeFileSync(join(name, 'package.json'), JSON.stringify(packageJson, null, 2));
+
+  // Write tsconfig.json
+  const tsconfigJson = {
+    compilerOptions: {
+      module: "ESNext",
+      target: "ESNext",
+      moduleResolution: "bundler",
+      esModuleInterop: true,
+      experimentalDecorators: true,
+      emitDecoratorMetadata: true,
+      strict: true,
+      skipLibCheck: true
+    }
+  };
+  writeFileSync(join(name, 'tsconfig.json'), JSON.stringify(tsconfigJson, null, 2));
+
+  // Write Dockerfile
+  const dockerfile = `# Multistage build for high performance, portability, and minimal size
+FROM oven/bun:1.1-alpine AS builder
+WORKDIR /app
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile || bun install
+COPY . .
+RUN bun run build:compile
+
+# Production runner (Distroless-style minimal Alpine)
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+WORKDIR /app
+COPY --from=builder /app/dist/server ./server
+EXPOSE 3000
+CMD ["./server"]
+`;
+  writeFileSync(join(name, 'Dockerfile'), dockerfile);
+
+  // Write .dockerignore
+  const dockerignore = `node_modules
+dist
+.git
+.gitignore
+Dockerfile
+README.md
+`;
+  writeFileSync(join(name, '.dockerignore'), dockerignore);
+
+  // Write .gitignore
+  const gitignore = `node_modules
+dist
+*.log
+.env
+`;
+  writeFileSync(join(name, '.gitignore'), gitignore);
+
+  // Write src/app.service.ts
+  const appService = `import { Injectable } from '@martel/calyx';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}
+`;
+  writeFileSync(join(name, 'src/app.service.ts'), appService);
+
+  // Write src/app.controller.ts
+  const appController = `import { Controller, Get } from '@martel/calyx';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}
+`;
+  writeFileSync(join(name, 'src/app.controller.ts'), appController);
+
+  // Write src/app.module.ts
+  const appModule = `import { Module } from '@martel/calyx';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+@Module({
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+`;
+  writeFileSync(join(name, 'src/app.module.ts'), appModule);
+
+  // Write src/main.ts
+  const mainTs = `import 'reflect-metadata';
+import { CalyxFactory } from '@martel/calyx';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await CalyxFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Application is running on http://localhost:3000');
+}
+bootstrap();
+`;
+  writeFileSync(join(name, 'src/main.ts'), mainTs);
+
+  console.log('Installing dependencies...');
+  spawnSync('bun', ['install'], { cwd: name, stdio: 'inherit' });
+
+  console.log(`
+Calyx application successfully created!
+
+To start running your app:
+  cd ${name}
+  bun run start:dev
+  `);
+}
+
+function runGenerate(schematic: string, rawName: string) {
+  if (!schematic || !rawName) {
+    console.error('Error: Please specify schematic type and name. Example: calyx g controller users');
+    process.exit(1);
+  }
+
+  const name = rawName.toLowerCase();
+  const pascalName = rawName.charAt(0).toUpperCase() + rawName.slice(1);
+  const type = schematic.toLowerCase();
+
+  const srcDir = existsSync('src') ? 'src' : '.';
+  const targetDir = join(srcDir, name);
+
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  switch (type) {
+    case 'module': {
+      const filePath = join(targetDir, `${name}.module.ts`);
+      const content = `import { Module } from '@martel/calyx';
+
+@Module({})
+export class ${pascalName}Module {}
+`;
+      writeFileSync(filePath, content);
+      console.log(`CREATE ${filePath}`);
+      break;
+    }
+    case 'controller': {
+      const filePath = join(targetDir, `${name}.controller.ts`);
+      const content = `import { Controller, Get } from '@martel/calyx';
+
+@Controller('${name}')
+export class ${pascalName}Controller {
+  @Get()
+  findAll() {
+    return 'This action returns all ${name}';
+  }
+}
+`;
+      writeFileSync(filePath, content);
+      console.log(`CREATE ${filePath}`);
+      autoRegisterInModule(name, pascalName, 'controller');
+      break;
+    }
+    case 'service': {
+      const filePath = join(targetDir, `${name}.service.ts`);
+      const content = `import { Injectable } from '@martel/calyx';
+
+@Injectable()
+export class ${pascalName}Service {}
+`;
+      writeFileSync(filePath, content);
+      console.log(`CREATE ${filePath}`);
+      autoRegisterInModule(name, pascalName, 'service');
+      break;
+    }
+    default:
+      console.error(`Error: Unknown schematic type "${type}". Supported: module, controller, service`);
+      process.exit(1);
+  }
+}
+
+function autoRegisterInModule(name: string, pascalName: string, type: 'controller' | 'service') {
+  const srcDir = existsSync('src') ? 'src' : '.';
+  const modulePath = join(srcDir, name, `${name}.module.ts`);
+  const rootModulePath = join(srcDir, `app.module.ts`);
+
+  const pathToCheck = existsSync(modulePath) ? modulePath : (existsSync(rootModulePath) ? rootModulePath : null);
+  if (!pathToCheck) return;
+
+  let content = readFileSync(pathToCheck, 'utf-8');
+
+  // Insert import statement
+  const importName = `${pascalName}${type === 'controller' ? 'Controller' : 'Service'}`;
+  const importRelativePath = pathToCheck === rootModulePath ? `./${name}/${name}.${type}` : `./${name}.${type}`;
+  const importStatement = `import { ${importName} } from '${importRelativePath}';\n`;
+
+  // Find last import line and insert after it
+  const lines = content.split('\n');
+  let lastImportIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith('import ')) {
+      lastImportIdx = i;
+    }
+  }
+  lines.splice(lastImportIdx + 1, 0, importStatement.trim());
+  content = lines.join('\n');
+
+  // Add item into metadata decorator
+  const arrayName = type === 'controller' ? 'controllers' : 'providers';
+  const arrayRegex = new RegExp(`(${arrayName}\\s*:\\s*\\[)([^\\]]*)(\\])`);
+
+  if (arrayRegex.test(content)) {
+    content = content.replace(arrayRegex, (match, prefix, list, suffix) => {
+      const trimmedList = list.trim();
+      const newList = trimmedList ? `${trimmedList}, ${importName}` : importName;
+      return `${prefix}${newList}${suffix}`;
+    });
+  } else {
+    // Add the metadata property if it doesn't exist
+    const decoratorRegex = /(@Module\(\s*\{)([\s\S]*?)(\}\s*\))/;
+    content = content.replace(decoratorRegex, (match, prefix, body, suffix) => {
+      const trimmedBody = body.trim();
+      const newBody = trimmedBody ? `${trimmedBody},\n  ${arrayName}: [${importName}]` : `  ${arrayName}: [${importName}]`;
+      return `${prefix}\n${newBody}\n${suffix}`;
+    });
+  }
+
+  writeFileSync(pathToCheck, content);
+  console.log(`UPDATE ${pathToCheck} (Registered ${importName})`);
+}

package/src/core/decorators.ts

@@ -67,3 +67,33 @@ export function Global(): ClassDecorator {
 export function forwardRef(fn: () => any): ForwardReference {
   return { forwardRef: fn };
 }
+
+export interface CustomDecorator<TKey = any> {
+  (target: object, key?: string | symbol, descriptor?: any): any;
+  KEY: TKey;
+}
+
+export function SetMetadata<K = any, V = any>(metadataKey: K, metadataValue: V): CustomDecorator<K> {
+  const decoratorFn = (target: any, key?: string | symbol, descriptor?: any) => {
+    if (descriptor) {
+      Reflect.defineMetadata(metadataKey, metadataValue, descriptor.value);
+      return descriptor;
+    }
+    Reflect.defineMetadata(metadataKey, metadataValue, target);
+    return target;
+  };
+  decoratorFn.KEY = metadataKey;
+  return decoratorFn;
+}
+
+export function applyDecorators(...decorators: any[]) {
+  return (target: any, propertyKey?: string | symbol, descriptor?: any) => {
+    for (const decorator of decorators) {
+      if (target instanceof Function && !propertyKey) {
+        decorator(target);
+      } else {
+        decorator(target, propertyKey, descriptor);
+      }
+    }
+  };
+}

package/src/core/index.ts

@@ -2,3 +2,4 @@ export * from './metadata.ts';
 export * from './decorators.ts';
 export * from './module-ref.ts';
 export * from './container.ts';
+export * from './reflector.ts';

package/src/core/reflector.ts

@@ -0,0 +1,32 @@
+import { Injectable } from './decorators.ts';
+import { Type } from './metadata.ts';
+
+@Injectable()
+export class Reflector {
+  get<T = any>(metadataKey: any, target: Function | Type<any>): T {
+    return Reflect.getMetadata(metadataKey, target);
+  }
+
+  getAllAndOverride<T = any>(metadataKey: any, targets: (Function | Type<any>)[]): T {
+    for (const target of targets) {
+      if (!target) continue;
+      const val = Reflect.getMetadata(metadataKey, target);
+      if (val !== undefined) return val;
+    }
+    return undefined as any;
+  }
+
+  getAllAndMerge<T = any>(metadataKey: any, targets: (Function | Type<any>)[]): T {
+    const result: any[] = [];
+    for (const target of targets) {
+      if (!target) continue;
+      const val = Reflect.getMetadata(metadataKey, target);
+      if (Array.isArray(val)) {
+        result.push(...val);
+      } else if (val !== undefined) {
+        result.push(val);
+      }
+    }
+    return result as any as T;
+  }
+}

package/src/http/application.ts

@@ -8,7 +8,7 @@ import { CalyxArgumentsHost, CalyxExecutionContext } from '../lifecycle/context.
 
 export class CalyxResponse {
   statusCode = 200;
-  headers = new Headers();
+  headers: Record<string, string> = {};
   body: any = null;
   sent = false;
 
@@ -24,14 +24,14 @@ export class CalyxResponse {
   }
 
   json(body: any) {
-    this.headers.set('content-type', 'application/json');
+    this.headers['content-type'] = 'application/json';
     this.body = JSON.stringify(body);
     this.sent = true;
     return this;
   }
 
   set(name: string, value: string) {
-    this.headers.set(name, value);
+    this.headers[name.toLowerCase()] = value;
     return this;
   }
 }
@@ -608,10 +608,13 @@ export class CalyxApplication {
       ? resWrapper.statusCode 
       : (httpCode ?? (req.method === 'POST' ? 201 : 200));
 
-    // Build headers only if we have custom headers or content-type requirements
-    let responseHeaders = resWrapper && isPassthrough ? resWrapper.headers : new Headers();
+    // Build headers as a plain object Record<string, string>
+    const responseHeaders: Record<string, string> = resWrapper && isPassthrough 
+      ? { ...resWrapper.headers } 
+      : {};
+
     for (const header of headers) {
-      responseHeaders.set(header.name, header.value);
+      responseHeaders[header.name.toLowerCase()] = header.value;
     }
 
     if (result === undefined || result === null) {
@@ -623,7 +626,7 @@ export class CalyxApplication {
     }
 
     if (typeof result === 'object') {
-      responseHeaders.set('content-type', 'application/json');
+      responseHeaders['content-type'] = 'application/json';
       return new Response(JSON.stringify(result), { status, headers: responseHeaders });
     }
 

package/tests/cli.test.ts

@@ -0,0 +1,96 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { existsSync, rmSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const testAppName = 'scratch/my-cli-test-app';
+
+describe('Calyx CLI Integration Tests', () => {
+  beforeAll(() => {
+    if (existsSync(testAppName)) {
+      rmSync(testAppName, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(() => {
+    if (existsSync(testAppName)) {
+      rmSync(testAppName, { recursive: true, force: true });
+    }
+  });
+
+  test('should display version details on info command', () => {
+    const proc = spawnSync('bun', ['./src/cli/index.ts', 'info'], { encoding: 'utf-8' });
+    expect(proc.status).toBe(0);
+    expect(proc.stdout).toContain('Calyx CLI Information');
+    expect(proc.stdout).toContain('Calyx Version: 0.1.0');
+  });
+
+  test('should scaffold a new application on new command', () => {
+    console.log('Scaffolding app, this may take a few seconds to run bun install...');
+    const proc = spawnSync('bun', ['./src/cli/index.ts', 'new', testAppName], { stdio: 'inherit' });
+    expect(proc.status).toBe(0);
+
+    expect(existsSync(join(testAppName, 'package.json'))).toBe(true);
+    expect(existsSync(join(testAppName, 'tsconfig.json'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/main.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.module.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.controller.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'src/app.service.ts'))).toBe(true);
+    expect(existsSync(join(testAppName, 'Dockerfile'))).toBe(true);
+    expect(existsSync(join(testAppName, '.dockerignore'))).toBe(true);
+    expect(existsSync(join(testAppName, '.gitignore'))).toBe(true);
+    expect(existsSync(join(testAppName, 'node_modules'))).toBe(true);
+  });
+
+  test('should generate controllers, services, and modules with auto-registration', () => {
+    // Generate a controller
+    const genCtrl = spawnSync('bun', ['../../src/cli/index.ts', 'g', 'controller', 'users'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    expect(genCtrl.status).toBe(0);
+    expect(existsSync(join(testAppName, 'src/users/users.controller.ts'))).toBe(true);
+
+    // Verify registration inside app.module.ts
+    const moduleContent = readFileSync(join(testAppName, 'src/app.module.ts'), 'utf-8');
+    expect(moduleContent).toContain("import { UsersController } from './users/users.controller';");
+    expect(moduleContent).toContain('controllers: [AppController, UsersController]');
+
+    // Generate a service
+    const genSvc = spawnSync('bun', ['../../src/cli/index.ts', 'g', 'service', 'users'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    expect(genSvc.status).toBe(0);
+    expect(existsSync(join(testAppName, 'src/users/users.service.ts'))).toBe(true);
+
+    const moduleContent2 = readFileSync(join(testAppName, 'src/app.module.ts'), 'utf-8');
+    expect(moduleContent2).toContain("import { UsersService } from './users/users.service';");
+    expect(moduleContent2).toContain('providers: [AppService, UsersService]');
+  });
+
+  test('should build the application using Bun compiler', () => {
+    // Manually modify package.json to point to local CLI script for Windows/Link test compatibility
+    const pkgPath = join(testAppName, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    pkg.scripts.build = "bun ../../src/cli/index.ts build";
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+
+    // Manually add path mapping to tsconfig.json for TypeScript source resolution during tests
+    const tsconfigPath = join(testAppName, 'tsconfig.json');
+    const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf-8'));
+    tsconfig.compilerOptions.paths = {
+      "@martel/calyx": ["../../src/index.ts"]
+    };
+    writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+
+    const buildProc = spawnSync('bun', ['run', 'build'], {
+      cwd: testAppName,
+      encoding: 'utf-8',
+    });
+    console.log('Build STDOUT:', buildProc.stdout);
+    console.log('Build STDERR:', buildProc.stderr);
+    expect(buildProc.status).toBe(0);
+    expect(existsSync(join(testAppName, 'dist/main.js'))).toBe(true);
+  });
+});

package/tests/phase5.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  SetMetadata,
+  Reflector,
+  applyDecorators,
+  Controller,
+  Get,
+} from '../src/index.ts';
+
+describe('Phase 5: NestJS Parity Extensions (Reflector & Metadata)', () => {
+  test('should set and get metadata using SetMetadata and Reflector', () => {
+    const reflector = new Reflector();
+
+    @SetMetadata('roles', ['admin'])
+    class SecuredController {
+      @SetMetadata('permission', 'write')
+      handler() {}
+    }
+
+    const roles = reflector.get<string[]>('roles', SecuredController);
+    expect(roles).toEqual(['admin']);
+
+    const controllerInstance = new SecuredController();
+    const permission = reflector.get<string>('permission', controllerInstance.handler);
+    expect(permission).toBe('write');
+  });
+
+  test('should support Reflector.getAllAndOverride and getAllAndMerge', () => {
+    const reflector = new Reflector();
+
+    @SetMetadata('roles', ['user'])
+    class TestController {
+      @SetMetadata('roles', ['admin'])
+      handler() {}
+    }
+
+    const controllerInstance = new TestController();
+
+    // getAllAndOverride: returns first non-undefined (reverses targets parameter order in Nest, e.g. [handler, class])
+    const overridenRoles = reflector.getAllAndOverride<string[]>('roles', [
+      controllerInstance.handler,
+      TestController,
+    ]);
+    expect(overridenRoles).toEqual(['admin']);
+
+    // getAllAndMerge: merges values from targets
+    const mergedRoles = reflector.getAllAndMerge<string[]>('roles', [
+      controllerInstance.handler,
+      TestController,
+    ]);
+    expect(mergedRoles).toEqual(['admin', 'user']);
+  });
+
+  test('should support applyDecorators to group multiple decorators', () => {
+    const reflector = new Reflector();
+
+    function CustomSecured(permission: string, roles: string[]) {
+      return applyDecorators(
+        SetMetadata('permission', permission),
+        SetMetadata('roles', roles)
+      );
+    }
+
+    @CustomSecured('write', ['admin'])
+    class GroupSecuredController {}
+
+    const permission = reflector.get<string>('permission', GroupSecuredController);
+    const roles = reflector.get<string[]>('roles', GroupSecuredController);
+
+    expect(permission).toBe('write');
+    expect(roles).toEqual(['admin']);
+  });
+});