@geekmidas/cli 0.3.0 → 0.5.0

package/src/__tests__/openapi.spec.ts

@@ -22,9 +22,8 @@ describe('OpenAPI Generation', () => {
     vi.restoreAllMocks();
   });
 
-  describe('openapiCommand', () => {
-    it('should generate OpenAPI spec for endpoints', async () => {
-      // Create endpoint file
+  describe('openapiCommand - TypeScript output (default)', () => {
+    it('should generate TypeScript module by default', async () => {
       await createMockEndpointFile(
         tempDir,
         'getUser.ts',
@@ -33,7 +32,6 @@ describe('OpenAPI Generation', () => {
         'GET',
       );
 
-      // Create config file
       await createTestFile(
         tempDir,
         'gkm.config.json',
@@ -42,56 +40,58 @@ describe('OpenAPI Generation', () => {
         }),
       );
 
-      const outputPath = join(tempDir, 'openapi.json');
-
-      // Mock process.cwd
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+      const outputPath = join(tempDir, 'openapi.ts');
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, cwd: tempDir });
 
-      // Verify file was created
       expect(existsSync(outputPath)).toBe(true);
 
-      // Verify content
       const content = await readFile(outputPath, 'utf-8');
-      const spec = JSON.parse(content);
 
-      expect(spec).toHaveProperty('openapi');
-      expect(spec).toHaveProperty('info');
-      expect(spec.info.title).toBe('API Documentation');
-      expect(spec).toHaveProperty('paths');
-      expect(Object.keys(spec.paths).length).toBeGreaterThan(0);
+      expect(content).toContain('// Auto-generated by @geekmidas/cli');
+      expect(content).toContain('export const securitySchemes');
+      expect(content).toContain('export const endpointAuth');
+      expect(content).toContain('export interface paths');
     });
 
-    it('should handle no endpoints found', async () => {
-      // Create config with no matching files
+    it('should include endpoint auth map', async () => {
+      await createMockEndpointFile(
+        tempDir,
+        'getUser.ts',
+        'getUser',
+        '/users/:id',
+        'GET',
+      );
+
       await createTestFile(
         tempDir,
         'gkm.config.json',
         JSON.stringify({
-          routes: [`${tempDir}/nonexistent/**/*.ts`],
+          routes: [`${tempDir}/**/*.ts`],
         }),
       );
 
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
-      const consoleSpy = vi.spyOn(console, 'log');
+      const outputPath = join(tempDir, 'openapi.ts');
 
-      await openapiCommand({ output: join(tempDir, 'openapi.json') });
+      await openapiCommand({ output: outputPath, cwd: tempDir });
 
-      expect(consoleSpy).toHaveBeenCalledWith('No valid endpoints found');
+      const content = await readFile(outputPath, 'utf-8');
+
+      expect(content).toContain('endpointAuth');
+      expect(content).toContain("'GET /users/{id}'");
     });
+  });
 
-    it('should use default output path when not specified', async () => {
-      // Create endpoint file
+  describe('openapiCommand - JSON output (legacy)', () => {
+    it('should generate JSON OpenAPI spec with --json flag', async () => {
       await createMockEndpointFile(
         tempDir,
-        'endpoint.ts',
-        'testEndpoint',
-        '/test',
+        'getUser.ts',
+        'getUser',
+        '/users/:id',
         'GET',
       );
 
-      // Create config
       await createTestFile(
         tempDir,
         'gkm.config.json',
@@ -100,16 +100,43 @@ describe('OpenAPI Generation', () => {
         }),
       );
 
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+      const outputPath = join(tempDir, 'openapi.json');
+
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
+
+      expect(existsSync(outputPath)).toBe(true);
+
+      const content = await readFile(outputPath, 'utf-8');
+      const spec = JSON.parse(content);
+
+      expect(spec).toHaveProperty('openapi');
+      expect(spec).toHaveProperty('info');
+      expect(spec.info.title).toBe('API Documentation');
+      expect(spec).toHaveProperty('paths');
+      expect(Object.keys(spec.paths).length).toBeGreaterThan(0);
+    });
+
+    it('should handle no endpoints found', async () => {
+      await createTestFile(
+        tempDir,
+        'gkm.config.json',
+        JSON.stringify({
+          routes: [`${tempDir}/nonexistent/**/*.ts`],
+        }),
+      );
+
+      const consoleSpy = vi.spyOn(console, 'log');
 
-      await openapiCommand();
+      await openapiCommand({
+        output: join(tempDir, 'openapi.json'),
+        json: true,
+        cwd: tempDir,
+      });
 
-      // Should create openapi.json in current directory
-      expect(existsSync(join(tempDir, 'openapi.json'))).toBe(true);
+      expect(consoleSpy).toHaveBeenCalledWith('No valid endpoints found');
     });
 
     it('should generate spec with multiple endpoints', async () => {
-      // Create multiple endpoint files
       await createMockEndpointFile(
         tempDir,
         'getUsers.ts',
@@ -132,7 +159,6 @@ describe('OpenAPI Generation', () => {
         'DELETE',
       );
 
-      // Create config
       await createTestFile(
         tempDir,
         'gkm.config.json',
@@ -142,19 +168,16 @@ describe('OpenAPI Generation', () => {
       );
 
       const outputPath = join(tempDir, 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       const content = await readFile(outputPath, 'utf-8');
       const spec = JSON.parse(content);
 
-      // Should have multiple paths
       expect(Object.keys(spec.paths).length).toBeGreaterThanOrEqual(1);
     });
 
     it('should create output directory if it does not exist', async () => {
-      // Create endpoint file
       await createMockEndpointFile(
         tempDir,
         'endpoint.ts',
@@ -163,7 +186,6 @@ describe('OpenAPI Generation', () => {
         'GET',
       );
 
-      // Create config
       await createTestFile(
         tempDir,
         'gkm.config.json',
@@ -173,15 +195,13 @@ describe('OpenAPI Generation', () => {
       );
 
       const outputPath = join(tempDir, 'nested', 'dir', 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       expect(existsSync(outputPath)).toBe(true);
     });
 
     it('should include API metadata in spec', async () => {
-      // Create endpoint
       await createMockEndpointFile(
         tempDir,
         'endpoint.ts',
@@ -190,7 +210,6 @@ describe('OpenAPI Generation', () => {
         'GET',
       );
 
-      // Create config
       await createTestFile(
         tempDir,
         'gkm.config.json',
@@ -200,9 +219,8 @@ describe('OpenAPI Generation', () => {
       );
 
       const outputPath = join(tempDir, 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       const content = await readFile(outputPath, 'utf-8');
       const spec = JSON.parse(content);
@@ -214,7 +232,7 @@ describe('OpenAPI Generation', () => {
       });
     });
 
-    it('should log generation success', async () => {
+    it('should log generation success for JSON', async () => {
       // Create endpoint
       await createMockEndpointFile(
         tempDir,
@@ -234,13 +252,12 @@ describe('OpenAPI Generation', () => {
       );
 
       const outputPath = join(tempDir, 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
       const consoleSpy = vi.spyOn(console, 'log');
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       expect(consoleSpy).toHaveBeenCalledWith(
-        expect.stringContaining('OpenAPI spec generated'),
+        expect.stringContaining('OpenAPI JSON spec generated'),
       );
       expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Found'));
       expect(consoleSpy).toHaveBeenCalledWith(
@@ -250,11 +267,9 @@ describe('OpenAPI Generation', () => {
 
     it('should throw error when config loading fails', async () => {
       // No config file created
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
-
-      await expect(openapiCommand()).rejects.toThrow(
-        /OpenAPI generation failed/,
-      );
+      await expect(
+        openapiCommand({ json: true, cwd: tempDir }),
+      ).rejects.toThrow(/OpenAPI generation failed/);
     });
 
     it('should throw error for invalid TypeScript files', async () => {
@@ -274,11 +289,13 @@ describe('OpenAPI Generation', () => {
         }),
       );
 
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
-
       // Should throw error for syntax errors
       await expect(
-        openapiCommand({ output: join(tempDir, 'openapi.json') }),
+        openapiCommand({
+          output: join(tempDir, 'openapi.json'),
+          json: true,
+          cwd: tempDir,
+        }),
       ).rejects.toThrow(/OpenAPI generation failed/);
     });
 
@@ -302,9 +319,8 @@ describe('OpenAPI Generation', () => {
       );
 
       const outputPath = join(tempDir, 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       const content = await readFile(outputPath, 'utf-8');
 
@@ -348,9 +364,8 @@ export const complexEndpoint = e
       );
 
       const outputPath = join(tempDir, 'openapi.json');
-      vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
 
-      await openapiCommand({ output: outputPath });
+      await openapiCommand({ output: outputPath, json: true, cwd: tempDir });
 
       const content = await readFile(outputPath, 'utf-8');
       const spec = JSON.parse(content);

package/src/build/index.ts

@@ -4,7 +4,8 @@ import type { Cron } from '@geekmidas/constructs/crons';
 import type { Endpoint } from '@geekmidas/constructs/endpoints';
 import type { Function } from '@geekmidas/constructs/functions';
 import type { Subscriber } from '@geekmidas/constructs/subscribers';
-import { loadConfig } from '../config';
+import { loadConfig, parseModuleConfig } from '../config';
+import { normalizeTelescopeConfig } from '../dev';
 import {
   CronGenerator,
   EndpointGenerator,
@@ -42,27 +43,24 @@ export async function buildCommand(options: BuildOptions): Promise<void> {
   }
   logger.log(`Using envParser: ${config.envParser}`);
 
-  // Parse envParser configuration
-  const [envParserPath, envParserName] = config.envParser.split('#');
-  const envParserImportPattern = !envParserName
-    ? 'envParser'
-    : envParserName === 'envParser'
-      ? '{ envParser }'
-      : `{ ${envParserName} as envParser }`;
-
-  // Parse logger configuration
-  const [loggerPath, loggerName] = config.logger.split('#');
-  const loggerImportPattern = !loggerName
-    ? 'logger'
-    : loggerName === 'logger'
-      ? '{ logger }'
-      : `{ ${loggerName} as logger }`;
+  // Parse envParser and logger configuration
+  const { path: envParserPath, importPattern: envParserImportPattern } =
+    parseModuleConfig(config.envParser, 'envParser');
+  const { path: loggerPath, importPattern: loggerImportPattern } =
+    parseModuleConfig(config.logger, 'logger');
+
+  // Normalize telescope configuration
+  const telescope = normalizeTelescopeConfig(config.telescope);
+  if (telescope) {
+    logger.log(`🔭 Telescope enabled at ${telescope.path}`);
+  }
 
   const buildContext: BuildContext = {
     envParserPath,
     envParserImportPattern,
     loggerPath,
     loggerImportPattern,
+    telescope,
   };
 
   // Initialize generators

package/src/build/types.ts

@@ -1,5 +1,6 @@
-import type { Cron, Function } from '@geekmidas/constructs';
-import type { Endpoint } from '@geekmidas/constructs';
+import type { Cron } from '@geekmidas/constructs/crons';
+import type { Endpoint } from '@geekmidas/constructs/endpoints';
+import type { Function } from '@geekmidas/constructs/functions';
 
 import type { CronInfo, FunctionInfo, RouteInfo } from '../types';
 
@@ -23,11 +24,26 @@ export interface ProcessedCron {
   schedule?: string;
 }
 
+export interface NormalizedTelescopeConfig {
+  enabled: boolean;
+  /** Path to user's telescope module (if provided) */
+  telescopePath?: string;
+  /** Import pattern for telescope (e.g., '{ telescope }' or 'telescope') */
+  telescopeImportPattern?: string;
+  /** UI path for telescope dashboard */
+  path: string;
+  ignore: string[];
+  recordBody: boolean;
+  maxEntries: number;
+  websocket: boolean;
+}
+
 export interface BuildContext {
   envParserPath: string;
   envParserImportPattern: string;
   loggerPath: string;
   loggerImportPattern: string;
+  telescope?: NormalizedTelescopeConfig;
 }
 
 export interface ProviderBuildResult {

package/src/config.ts

@@ -2,12 +2,71 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import type { GkmConfig } from './types.ts';
 
-export async function loadConfig(): Promise<GkmConfig> {
+/**
+ * Define GKM configuration with full TypeScript support.
+ * This is an identity function that provides type safety and autocomplete.
+ *
+ * @example
+ * ```ts
+ * // gkm.config.ts
+ * import { defineConfig } from '@geekmidas/cli/config';
+ *
+ * export default defineConfig({
+ *   routes: './src/endpoints/**\/*.ts',
+ *   envParser: './src/config/env',
+ *   logger: './src/config/logger',
+ *   telescope: true,
+ * });
+ * ```
+ */
+export function defineConfig(config: GkmConfig): GkmConfig {
+  return config;
+}
+
+export interface ParsedModuleConfig {
+  path: string;
+  importPattern: string;
+}
+
+/**
+ * Parse a module config string into path and import pattern.
+ *
+ * @param configString - Config string in format "./path/to/module" or "./path/to/module#exportName"
+ * @param defaultAlias - The default alias name to use if no export name specified
+ * @returns Object with path and import pattern
+ *
+ * @example
+ * parseModuleConfig('./src/config/env', 'envParser')
+ * // { path: './src/config/env', importPattern: 'envParser' }
+ *
+ * parseModuleConfig('./src/config/env#envParser', 'envParser')
+ * // { path: './src/config/env', importPattern: '{ envParser }' }
+ *
+ * parseModuleConfig('./src/config/env#myEnv', 'envParser')
+ * // { path: './src/config/env', importPattern: '{ myEnv as envParser }' }
+ */
+export function parseModuleConfig(
+  configString: string,
+  defaultAlias: string,
+): ParsedModuleConfig {
+  const [path, exportName] = configString.split('#');
+  const importPattern = !exportName
+    ? defaultAlias
+    : exportName === defaultAlias
+      ? `{ ${defaultAlias} }`
+      : `{ ${exportName} as ${defaultAlias} }`;
+
+  return { path, importPattern };
+}
+
+export async function loadConfig(
+  cwd: string = process.cwd(),
+): Promise<GkmConfig> {
   const files = ['gkm.config.json', 'gkm.config.ts', 'gkm.config.js'];
   let configPath = '';
 
   for (const file of files) {
-    const path = join(process.cwd(), file);
+    const path = join(cwd, file);
     if (existsSync(path)) {
       configPath = path;
       break;

package/src/dev/__tests__/index.spec.ts

@@ -1,6 +1,10 @@
 import { createServer } from 'node:net';
 import { describe, expect, it } from 'vitest';
-import { findAvailablePort, isPortAvailable } from '../index';
+import {
+  findAvailablePort,
+  isPortAvailable,
+  normalizeTelescopeConfig,
+} from '../index';
 
 /**
  * Helper to occupy a port for testing
@@ -206,3 +210,96 @@ describe('devCommand edge cases', () => {
     });
   });
 });
+
+describe('normalizeTelescopeConfig', () => {
+  it('should return undefined when config is false', () => {
+    const result = normalizeTelescopeConfig(false);
+    expect(result).toBeUndefined();
+  });
+
+  it('should return default config when config is true', () => {
+    const result = normalizeTelescopeConfig(true);
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__telescope',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: true,
+    });
+  });
+
+  it('should return default config when config is undefined', () => {
+    const result = normalizeTelescopeConfig(undefined);
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__telescope',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: true,
+    });
+  });
+
+  it('should return undefined when config.enabled is false', () => {
+    const result = normalizeTelescopeConfig({ enabled: false });
+    expect(result).toBeUndefined();
+  });
+
+  it('should merge custom config with defaults', () => {
+    const result = normalizeTelescopeConfig({
+      path: '/__debug',
+      ignore: ['/health', '/metrics'],
+      recordBody: false,
+      maxEntries: 500,
+    });
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__debug',
+      ignore: ['/health', '/metrics'],
+      recordBody: false,
+      maxEntries: 500,
+      websocket: true,
+    });
+  });
+
+  it('should use defaults for missing config values', () => {
+    const result = normalizeTelescopeConfig({
+      path: '/__custom',
+    });
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__custom',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: true,
+    });
+  });
+
+  it('should handle empty object config', () => {
+    const result = normalizeTelescopeConfig({});
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__telescope',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: true,
+    });
+  });
+
+  it('should allow disabling websocket', () => {
+    const result = normalizeTelescopeConfig({
+      websocket: false,
+    });
+    expect(result).toEqual({
+      enabled: true,
+      path: '/__telescope',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: false,
+    });
+  });
+});