@martel/calyx 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

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,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/cli/index.ts

@@ -109,6 +109,9 @@ function runNew(name: string) {
   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',
@@ -117,10 +120,15 @@ function runNew(name: string) {
     scripts: {
       "start": "calyx start",
       "start:dev": "calyx start --watch",
-      "build": "calyx build"
+      "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": "link:../..", // link back to Calyx package parent root for local tests
+      "@martel/calyx": calyxDependency,
       "reflect-metadata": "^0.2.2"
     }
   };
@@ -141,6 +149,43 @@ function runNew(name: string) {
   };
   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';
 

package/tests/cli.test.ts

@@ -36,6 +36,9 @@ describe('Calyx CLI Integration Tests', () => {
     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);
   });