@geekmidas/cli 0.3.0 → 0.5.0

package/src/dev/index.ts

@@ -1,21 +1,62 @@
 import { type ChildProcess, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { createServer } from 'node:net';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import chokidar from 'chokidar';
+import { config as dotenvConfig } from 'dotenv';
+import fg from 'fast-glob';
 import { resolveProviders } from '../build/providerResolver';
-import type { BuildContext } from '../build/types';
-import { loadConfig } from '../config';
+import type { BuildContext, NormalizedTelescopeConfig } from '../build/types';
+import { loadConfig, parseModuleConfig } from '../config';
 import {
   CronGenerator,
   EndpointGenerator,
   FunctionGenerator,
   SubscriberGenerator,
 } from '../generators';
-import type { LegacyProvider } from '../types';
+import type {
+  GkmConfig,
+  LegacyProvider,
+  Runtime,
+  TelescopeConfig,
+} from '../types';
 
 const logger = console;
 
+/**
+ * Load environment files
+ * @internal Exported for testing
+ */
+export function loadEnvFiles(
+  envConfig: string | string[] | undefined,
+  cwd: string = process.cwd(),
+): { loaded: string[]; missing: string[] } {
+  const loaded: string[] = [];
+  const missing: string[] = [];
+
+  // Normalize to array
+  const envFiles = envConfig
+    ? Array.isArray(envConfig)
+      ? envConfig
+      : [envConfig]
+    : ['.env'];
+
+  // Load each env file in order (later files override earlier)
+  for (const envFile of envFiles) {
+    const envPath = resolve(cwd, envFile);
+    if (existsSync(envPath)) {
+      dotenvConfig({ path: envPath, override: true, quiet: true });
+      loaded.push(envFile);
+    } else if (envConfig) {
+      // Only report as missing if explicitly configured
+      missing.push(envFile);
+    }
+  }
+
+  return { loaded, missing };
+}
+
 /**
  * Check if a port is available
  * @internal Exported for testing
@@ -62,14 +103,81 @@ export async function findAvailablePort(
   );
 }
 
+/**
+ * Normalize telescope configuration
+ * @internal Exported for testing
+ */
+export function normalizeTelescopeConfig(
+  config: GkmConfig['telescope'],
+): NormalizedTelescopeConfig | undefined {
+  if (config === false) {
+    return undefined;
+  }
+
+  // Handle string path (e.g., './src/config/telescope')
+  if (typeof config === 'string') {
+    const { path: telescopePath, importPattern: telescopeImportPattern } =
+      parseModuleConfig(config, 'telescope');
+
+    return {
+      enabled: true,
+      telescopePath,
+      telescopeImportPattern,
+      path: '/__telescope',
+      ignore: [],
+      recordBody: true,
+      maxEntries: 1000,
+      websocket: true,
+    };
+  }
+
+  // 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;
 }
 
 export async function devCommand(options: DevOptions): Promise<void> {
+  // Load default .env file BEFORE loading config
+  // This ensures env vars are available when config and its dependencies are loaded
+  const defaultEnv = loadEnvFiles('.env');
+  if (defaultEnv.loaded.length > 0) {
+    logger.log(`📦 Loaded env: ${defaultEnv.loaded.join(', ')}`);
+  }
+
   const config = await loadConfig();
 
+  // Load any additional env files specified in config
+  if (config.env) {
+    const { loaded, missing } = loadEnvFiles(config.env);
+    if (loaded.length > 0) {
+      logger.log(`📦 Loaded env: ${loaded.join(', ')}`);
+    }
+    if (missing.length > 0) {
+      logger.warn(`⚠️  Missing env files: ${missing.join(', ')}`);
+    }
+  }
+
   // Force server provider for dev mode
   const resolved = resolveProviders(config, { provider: 'server' });
 
@@ -86,27 +194,24 @@ export async function devCommand(options: DevOptions): 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,
   };
 
   // Build initial version
@@ -117,31 +222,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 +373,8 @@ class DevServer {
     private provider: LegacyProvider,
     private requestedPort: number,
     private enableOpenApi: boolean,
+    private telescope?: NormalizedTelescopeConfig,
+    private runtime: Runtime = 'node',
   ) {
     this.actualPort = requestedPort;
   }
@@ -260,12 +406,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 +440,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 +486,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 +515,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 +544,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,98 @@ export function setupEndpoints(
       context.envParserPath,
     );
 
+    // Generate telescope imports and setup if enabled
+    const telescopeEnabled = context.telescope?.enabled;
+    const telescopeWebSocketEnabled = context.telescope?.websocket;
+    const usesExternalTelescope = !!context.telescope?.telescopePath;
+
+    // Generate imports based on whether telescope is external or inline
+    let telescopeImports = '';
+    if (telescopeEnabled) {
+      if (usesExternalTelescope) {
+        const relativeTelescopePath = relative(
+          dirname(appPath),
+          context.telescope!.telescopePath!,
+        );
+        telescopeImports = `import ${context.telescope!.telescopeImportPattern} from '${relativeTelescopePath}';
+import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`;
+      } else {
+        telescopeImports = `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');
+  }
+`
+      : '';
+
+    // Generate telescope setup - either use external instance or create inline
+    let telescopeSetup = '';
+    if (telescopeEnabled) {
+      if (usesExternalTelescope) {
+        // Use external telescope instance - no need to create one
+        telescopeSetup = `
+${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);
+`;
+      } else {
+        // Create inline telescope instance
+        telescopeSetup = `
+  // 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 +438,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 +459,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 +473,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 +482,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);