@geekmidas/cli 0.2.4 → 0.4.0

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,
+    });
+  });
+});

package/src/dev/index.ts

@@ -3,8 +3,9 @@ import { mkdir } from 'node:fs/promises';
 import { createServer } from 'node:net';
 import { join } from 'node:path';
 import chokidar from 'chokidar';
+import fg from 'fast-glob';
 import { resolveProviders } from '../build/providerResolver';
-import type { BuildContext } from '../build/types';
+import type { BuildContext, NormalizedTelescopeConfig } from '../build/types';
 import { loadConfig } from '../config';
 import {
   CronGenerator,
@@ -12,7 +13,12 @@ import {
   FunctionGenerator,
   SubscriberGenerator,
 } from '../generators';
-import type { LegacyProvider } from '../types';
+import type {
+  GkmConfig,
+  LegacyProvider,
+  Runtime,
+  TelescopeConfig,
+} from '../types';
 
 const logger = console;
 
@@ -62,6 +68,38 @@ export async function findAvailablePort(
   );
 }
 
+/**
+ * Normalize telescope configuration
+ * @internal Exported for testing
+ */
+export function normalizeTelescopeConfig(
+  config: GkmConfig['telescope'],
+): NormalizedTelescopeConfig | undefined {
+  if (config === false) {
+    return undefined;
+  }
+
+  // Default to enabled in development mode
+  const isEnabled =
+    config === true || config === undefined || config.enabled !== false;
+
+  if (!isEnabled) {
+    return undefined;
+  }
+
+  const telescopeConfig: TelescopeConfig =
+    typeof config === 'object' ? config : {};
+
+  return {
+    enabled: true,
+    path: telescopeConfig.path ?? '/__telescope',
+    ignore: telescopeConfig.ignore ?? [],
+    recordBody: telescopeConfig.recordBody ?? true,
+    maxEntries: telescopeConfig.maxEntries ?? 1000,
+    websocket: telescopeConfig.websocket ?? true,
+  };
+}
+
 export interface DevOptions {
   port?: number;
   enableOpenApi?: boolean;
@@ -102,11 +140,18 @@ export async function devCommand(options: DevOptions): Promise<void> {
       ? '{ logger }'
       : `{ ${loggerName} as 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,
   };
 
   // Build initial version
@@ -117,31 +162,70 @@ export async function devCommand(options: DevOptions): Promise<void> {
     resolved.enableOpenApi,
   );
 
+  // Determine runtime (default to node)
+  const runtime: Runtime = config.runtime ?? 'node';
+
   // Start the dev server
   const devServer = new DevServer(
     resolved.providers[0] as LegacyProvider,
     options.port || 3000,
     resolved.enableOpenApi,
+    telescope,
+    runtime,
   );
 
   await devServer.start();
 
   // Watch for file changes
+  const envParserFile = config.envParser.split('#')[0];
+  const loggerFile = config.logger.split('#')[0];
+
   const watchPatterns = [
     config.routes,
     ...(config.functions ? [config.functions] : []),
     ...(config.crons ? [config.crons] : []),
     ...(config.subscribers ? [config.subscribers] : []),
-    config.envParser.split('#')[0],
-    config.logger.split('#')[0],
+    // Add .ts extension if not present for config files
+    envParserFile.endsWith('.ts') ? envParserFile : `${envParserFile}.ts`,
+    loggerFile.endsWith('.ts') ? loggerFile : `${loggerFile}.ts`,
   ].flat();
 
-  logger.log(`👀 Watching for changes in: ${watchPatterns.join(', ')}`);
+  // Normalize patterns - remove leading ./ when using cwd option
+  const normalizedPatterns = watchPatterns.map((p) =>
+    p.startsWith('./') ? p.slice(2) : p,
+  );
+
+  logger.log(`👀 Watching for changes in: ${normalizedPatterns.join(', ')}`);
+
+  // Resolve glob patterns to actual files (chokidar 4.x doesn't support globs)
+  const resolvedFiles = await fg(normalizedPatterns, {
+    cwd: process.cwd(),
+    absolute: false,
+    onlyFiles: true,
+  });
+
+  // Also watch the directories for new files
+  const dirsToWatch = [
+    ...new Set(resolvedFiles.map((f) => f.split('/').slice(0, -1).join('/'))),
+  ];
+
+  logger.log(
+    `📁 Found ${resolvedFiles.length} files in ${dirsToWatch.length} directories`,
+  );
 
-  const watcher = chokidar.watch(watchPatterns, {
+  const watcher = chokidar.watch([...resolvedFiles, ...dirsToWatch], {
     ignored: /(^|[\/\\])\../, // ignore dotfiles
     persistent: true,
     ignoreInitial: true,
+    cwd: process.cwd(),
+  });
+
+  watcher.on('ready', () => {
+    logger.log('🔍 File watcher ready');
+  });
+
+  watcher.on('error', (error) => {
+    logger.error('❌ Watcher error:', error);
   });
 
   let rebuildTimeout: NodeJS.Timeout | null = null;
@@ -229,6 +313,8 @@ class DevServer {
     private provider: LegacyProvider,
     private requestedPort: number,
     private enableOpenApi: boolean,
+    private telescope?: NormalizedTelescopeConfig,
+    private runtime: Runtime = 'node',
   ) {
     this.actualPort = requestedPort;
   }
@@ -260,12 +346,14 @@ class DevServer {
     logger.log(`\n✨ Starting server on port ${this.actualPort}...`);
 
     // Start the server using tsx (TypeScript execution)
+    // Use detached: true so we can kill the entire process tree
     this.serverProcess = spawn(
       'npx',
       ['tsx', serverEntryPath, '--port', this.actualPort.toString()],
       {
         stdio: 'inherit',
         env: { ...process.env, NODE_ENV: 'development' },
+        detached: true,
       },
     );
 
@@ -292,19 +380,39 @@ class DevServer {
           `📚 API Docs available at http://localhost:${this.actualPort}/docs`,
         );
       }
+      if (this.telescope) {
+        logger.log(
+          `🔭 Telescope available at http://localhost:${this.actualPort}${this.telescope.path}`,
+        );
+      }
     }
   }
 
   async stop(): Promise<void> {
     if (this.serverProcess && this.isRunning) {
-      this.serverProcess.kill('SIGTERM');
+      const pid = this.serverProcess.pid;
+
+      // Kill the entire process group (negative PID kills the group)
+      if (pid) {
+        try {
+          process.kill(-pid, 'SIGTERM');
+        } catch {
+          // Process might already be dead
+        }
+      }
 
       // Wait for process to exit
       await new Promise<void>((resolve) => {
         const timeout = setTimeout(() => {
-          this.serverProcess?.kill('SIGKILL');
+          if (pid) {
+            try {
+              process.kill(-pid, 'SIGKILL');
+            } catch {
+              // Process might already be dead
+            }
+          }
           resolve();
-        }, 5000);
+        }, 3000);
 
         this.serverProcess?.on('exit', () => {
           clearTimeout(timeout);
@@ -318,7 +426,21 @@ class DevServer {
   }
 
   async restart(): Promise<void> {
+    const portToReuse = this.actualPort;
     await this.stop();
+
+    // Wait for port to be released (up to 3 seconds)
+    let attempts = 0;
+    while (attempts < 30) {
+      if (await isPortAvailable(portToReuse)) {
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      attempts++;
+    }
+
+    // Force reuse the same port
+    this.requestedPort = portToReuse;
     await this.start();
   }
 
@@ -333,6 +455,24 @@ class DevServer {
       join(dirname(serverPath), 'app.js'),
     );
 
+    const serveCode =
+      this.runtime === 'bun'
+        ? `Bun.serve({
+      port,
+      fetch: app.fetch,
+    });`
+        : `const { serve } = await import('@hono/node-server');
+    const server = serve({
+      fetch: app.fetch,
+      port,
+    });
+    // Inject WebSocket support if available
+    const injectWs = (app as any).__injectWebSocket;
+    if (injectWs) {
+      injectWs(server);
+      console.log('🔌 Telescope real-time updates enabled');
+    }`;
+
     const content = `#!/usr/bin/env node
 /**
  * Development server entry point
@@ -344,27 +484,14 @@ const port = process.argv.includes('--port')
   ? Number.parseInt(process.argv[process.argv.indexOf('--port') + 1])
   : 3000;
 
-const { app, start } = createApp(undefined, ${this.enableOpenApi});
+// createApp is async to support optional WebSocket setup
+const { app, start } = await createApp(undefined, ${this.enableOpenApi});
 
 // Start the server
 start({
   port,
   serve: async (app, port) => {
-    // Detect runtime and use appropriate server
-    if (typeof Bun !== 'undefined') {
-      // Bun runtime
-      Bun.serve({
-        port,
-        fetch: app.fetch,
-      });
-    } else {
-      // Node.js runtime with @hono/node-server
-      const { serve } = await import('@hono/node-server');
-      serve({
-        fetch: app.fetch,
-        port,
-      });
-    }
+    ${serveCode}
   },
 }).catch((error) => {
   console.error('Failed to start server:', error);

package/src/generators/EndpointGenerator.ts

@@ -249,7 +249,7 @@ export class EndpointGenerator extends ConstructGenerator<
         any
       >
     >[],
-    context: BuildContext,
+    _context: BuildContext,
   ): Promise<string> {
     const endpointsFileName = 'endpoints.ts';
     const endpointsPath = join(outputDir, endpointsFileName);
@@ -333,6 +333,69 @@ export function setupEndpoints(
       context.envParserPath,
     );
 
+    // Generate telescope imports and setup if enabled
+    const telescopeEnabled = context.telescope?.enabled;
+    const telescopeWebSocketEnabled = context.telescope?.websocket;
+    const telescopeImports = telescopeEnabled
+      ? `import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`
+      : '';
+
+    const telescopeWebSocketSetupCode = telescopeWebSocketEnabled
+      ? `
+  // Setup WebSocket for real-time telescope updates
+  try {
+    const { createNodeWebSocket } = await import('@hono/node-ws');
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app: honoApp });
+    // Add WebSocket route directly to main app (sub-app routes don't support WS upgrade)
+    honoApp.get('${context.telescope!.path}/ws', upgradeWebSocket(() => ({
+      onOpen: (_event: Event, ws: any) => {
+        telescope.addWsClient(ws);
+      },
+      onClose: (_event: Event, ws: any) => {
+        telescope.removeWsClient(ws);
+      },
+      onMessage: (event: MessageEvent, ws: any) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === 'ping') {
+            ws.send(JSON.stringify({ type: 'pong' }));
+          }
+        } catch {
+          // Ignore invalid messages
+        }
+      },
+    })));
+    // Store injectWebSocket for server entry to call after serve()
+    (honoApp as any).__injectWebSocket = injectWebSocket;
+    logger.info('Telescope WebSocket enabled');
+  } catch (e) {
+    logger.warn({ error: e }, 'WebSocket support not available - install @hono/node-ws for real-time updates');
+  }
+`
+      : '';
+
+    const telescopeSetup = telescopeEnabled
+      ? `
+  // Setup Telescope for debugging/monitoring
+  const telescopeStorage = new InMemoryStorage({ maxEntries: ${context.telescope!.maxEntries} });
+  const telescope = new Telescope({
+    enabled: true,
+    path: '${context.telescope!.path}',
+    ignorePatterns: ${JSON.stringify(context.telescope!.ignore)},
+    recordBody: ${context.telescope!.recordBody},
+    storage: telescopeStorage,
+  });
+${telescopeWebSocketSetupCode}
+  // Add telescope middleware (before endpoints to capture all requests)
+  honoApp.use('*', createMiddleware(telescope));
+
+  // Mount telescope UI
+  const telescopeUI = createUI(telescope);
+  honoApp.route('${context.telescope!.path}', telescopeUI);
+`
+      : '';
+
     const content = `/**
  * Generated server application
  *
@@ -346,6 +409,7 @@ import { setupEndpoints } from './endpoints.js';
 import { setupSubscribers } from './subscribers.js';
 import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
 import ${context.loggerImportPattern} from '${relativeLoggerPath}';
+${telescopeImports}
 
 export interface ServerApp {
   app: HonoType;
@@ -366,7 +430,7 @@ export interface ServerApp {
  * // With Bun
  * import { createApp } from './.gkm/server/app.js';
  *
- * const { app, start } = createApp();
+ * const { app, start } = await createApp();
  *
  * await start({
  *   port: 3000,
@@ -380,7 +444,7 @@ export interface ServerApp {
  * import { serve } from '@hono/node-server';
  * import { createApp } from './.gkm/server/app.js';
  *
- * const { app, start } = createApp();
+ * const { app, start } = await createApp();
  *
  * await start({
  *   port: 3000,
@@ -389,9 +453,9 @@ export interface ServerApp {
  *   }
  * });
  */
-export function createApp(app?: HonoType, enableOpenApi: boolean = true): ServerApp {
+export async function createApp(app?: HonoType, enableOpenApi: boolean = true): Promise<ServerApp> {
   const honoApp = app || new Hono();
-
+${telescopeSetup}
   // Setup HTTP endpoints
   setupEndpoints(honoApp, envParser, logger, enableOpenApi);