@martel/calyx 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@martel/calyx",
-  "version": "1.0.0",
+  "version": "1.1.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,323 @@
+#!/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 packageJson = {
+    name,
+    version: '0.0.1',
+    description: 'Calyx application',
+    type: 'module',
+    scripts: {
+      "start": "calyx start",
+      "start:dev": "calyx start --watch",
+      "build": "calyx build"
+    },
+    dependencies: {
+      "@martel/calyx": "link:../..", // link back to Calyx package parent root for local tests
+      "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 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,93 @@
+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, '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']);
+  });
+});