@geekmidas/cli 0.4.0 → 0.5.1

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

@@ -1,15 +1,37 @@
+import type { AddressInfo } from 'node:net';
 import { createServer } from 'node:net';
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import {
   findAvailablePort,
   isPortAvailable,
   normalizeTelescopeConfig,
 } from '../index';
 
+// Track servers to clean up after each test
+const activeServers: ReturnType<typeof createServer>[] = [];
+
+afterEach(async () => {
+  // Close all servers and wait for them to fully close
+  await Promise.all(
+    activeServers.map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        }),
+    ),
+  );
+  activeServers.length = 0;
+  // Give OS time to release ports
+  await new Promise((resolve) => setTimeout(resolve, 50));
+});
+
 /**
- * Helper to occupy a port for testing
+ * Helper to occupy a port for testing.
+ * Pass port 0 to get a random available port.
  */
-function occupyPort(port: number): Promise<ReturnType<typeof createServer>> {
+function occupyPort(
+  port: number,
+): Promise<{ server: ReturnType<typeof createServer>; port: number }> {
   return new Promise((resolve, reject) => {
     const server = createServer();
 
@@ -18,7 +40,9 @@ function occupyPort(port: number): Promise<ReturnType<typeof createServer>> {
     });
 
     server.once('listening', () => {
-      resolve(server);
+      activeServers.push(server);
+      const actualPort = (server.address() as AddressInfo).port;
+      resolve({ server, port: actualPort });
     });
 
     server.listen(port);
@@ -28,127 +52,99 @@ function occupyPort(port: number): Promise<ReturnType<typeof createServer>> {
 describe('Port Availability Functions', () => {
   describe('isPortAvailable', () => {
     it('should return true for an available port', async () => {
-      // Use a high port number to avoid conflicts
-      const port = 45000;
+      // Get a random port, close it, then check availability
+      const { server, port } = await occupyPort(0);
+      server.close();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
       const available = await isPortAvailable(port);
       expect(available).toBe(true);
     });
 
     it('should return false for a port in use', async () => {
-      const port = 45001;
-      const server = await occupyPort(port);
-
-      try {
-        const available = await isPortAvailable(port);
-        expect(available).toBe(false);
-      } finally {
-        server.close();
-      }
+      const { port } = await occupyPort(0);
+
+      const available = await isPortAvailable(port);
+      expect(available).toBe(false);
+      // Server cleanup handled by afterEach
     });
 
     it('should handle multiple sequential checks correctly', async () => {
-      const port = 45002;
+      // Get a port to test with
+      const { server: tempServer, port } = await occupyPort(0);
+      tempServer.close();
+      await new Promise((resolve) => setTimeout(resolve, 50));
 
       // First check - port should be available
       const firstCheck = await isPortAvailable(port);
       expect(firstCheck).toBe(true);
 
       // Occupy the port
-      const server = await occupyPort(port);
-
-      try {
-        // Second check - port should be unavailable
-        const secondCheck = await isPortAvailable(port);
-        expect(secondCheck).toBe(false);
-      } finally {
-        server.close();
-      }
-
-      // Give a moment for the port to be released
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Third check - port should be available again
-      const thirdCheck = await isPortAvailable(port);
-      expect(thirdCheck).toBe(true);
+      await occupyPort(port);
+
+      // Second check - port should be unavailable
+      const secondCheck = await isPortAvailable(port);
+      expect(secondCheck).toBe(false);
+      // Server cleanup and third check handled by afterEach
     });
   });
 
   describe('findAvailablePort', () => {
     it('should return the preferred port if available', async () => {
-      const preferredPort = 45100;
+      // Get a random port, close it, then use as preferred
+      const { server, port: preferredPort } = await occupyPort(0);
+      server.close();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
       const foundPort = await findAvailablePort(preferredPort);
       expect(foundPort).toBe(preferredPort);
     });
 
     it('should return the next available port if preferred is in use', async () => {
-      const preferredPort = 45101;
-      const server = await occupyPort(preferredPort);
-
-      try {
-        const foundPort = await findAvailablePort(preferredPort);
-        expect(foundPort).toBe(preferredPort + 1);
-      } finally {
-        server.close();
-      }
+      const { port: preferredPort } = await occupyPort(0);
+
+      const foundPort = await findAvailablePort(preferredPort);
+      expect(foundPort).toBe(preferredPort + 1);
     });
 
     it('should skip multiple occupied ports', async () => {
-      const preferredPort = 45102;
-      const server1 = await occupyPort(preferredPort);
-      const server2 = await occupyPort(preferredPort + 1);
-      const server3 = await occupyPort(preferredPort + 2);
-
-      try {
-        const foundPort = await findAvailablePort(preferredPort);
-        expect(foundPort).toBe(preferredPort + 3);
-      } finally {
-        server1.close();
-        server2.close();
-        server3.close();
-      }
+      // Get a base port
+      const { port: basePort } = await occupyPort(0);
+      // Occupy consecutive ports
+      await occupyPort(basePort + 1);
+      await occupyPort(basePort + 2);
+
+      const foundPort = await findAvailablePort(basePort);
+      expect(foundPort).toBe(basePort + 3);
     });
 
     it('should throw error if no available port found within max attempts', async () => {
-      const preferredPort = 45103;
+      const { port: preferredPort } = await occupyPort(0);
       const maxAttempts = 3;
 
-      // Occupy ports 45103, 45104, 45105
-      const servers = await Promise.all([
-        occupyPort(preferredPort),
-        occupyPort(preferredPort + 1),
-        occupyPort(preferredPort + 2),
-      ]);
-
-      try {
-        await expect(
-          findAvailablePort(preferredPort, maxAttempts),
-        ).rejects.toThrow(
-          `Could not find an available port after trying ${maxAttempts} ports starting from ${preferredPort}`,
-        );
-      } finally {
-        servers.forEach((server) => server.close());
-      }
+      // Occupy consecutive ports
+      await occupyPort(preferredPort + 1);
+      await occupyPort(preferredPort + 2);
+
+      await expect(
+        findAvailablePort(preferredPort, maxAttempts),
+      ).rejects.toThrow(
+        `Could not find an available port after trying ${maxAttempts} ports starting from ${preferredPort}`,
+      );
     });
 
     it('should respect custom maxAttempts parameter', async () => {
-      const preferredPort = 45104;
+      const { port: preferredPort } = await occupyPort(0);
       const maxAttempts = 5;
 
-      // Occupy first 4 ports
-      const servers = await Promise.all([
-        occupyPort(preferredPort),
-        occupyPort(preferredPort + 1),
-        occupyPort(preferredPort + 2),
-        occupyPort(preferredPort + 3),
-      ]);
-
-      try {
-        const foundPort = await findAvailablePort(preferredPort, maxAttempts);
-        // Should find port at preferredPort + 4 (within 5 attempts)
-        expect(foundPort).toBe(preferredPort + 4);
-      } finally {
-        servers.forEach((server) => server.close());
-      }
+      // Occupy consecutive ports (4 total including base)
+      await occupyPort(preferredPort + 1);
+      await occupyPort(preferredPort + 2);
+      await occupyPort(preferredPort + 3);
+
+      const foundPort = await findAvailablePort(preferredPort, maxAttempts);
+      // Should find port at preferredPort + 4 (within 5 attempts)
+      expect(foundPort).toBe(preferredPort + 4);
     });
   });
 });
@@ -156,58 +152,57 @@ describe('Port Availability Functions', () => {
 describe('DevServer', () => {
   describe('port selection', () => {
     it('should use requested port when available', async () => {
-      // This is more of an integration test that would need the actual DevServer
-      // For now, we test the underlying logic
-      const requestedPort = 45200;
+      // Get a random port, close it, then use as requested
+      const { server, port: requestedPort } = await occupyPort(0);
+      server.close();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
       const actualPort = await findAvailablePort(requestedPort);
       expect(actualPort).toBe(requestedPort);
     });
 
     it('should select alternative port when requested is in use', async () => {
-      const requestedPort = 45201;
-      const server = await occupyPort(requestedPort);
-
-      try {
-        const actualPort = await findAvailablePort(requestedPort);
-        expect(actualPort).not.toBe(requestedPort);
-        expect(actualPort).toBeGreaterThan(requestedPort);
-        expect(actualPort).toBeLessThanOrEqual(requestedPort + 10);
-      } finally {
-        server.close();
-      }
+      const { port: requestedPort } = await occupyPort(0);
+
+      const actualPort = await findAvailablePort(requestedPort);
+      expect(actualPort).not.toBe(requestedPort);
+      expect(actualPort).toBeGreaterThan(requestedPort);
+      expect(actualPort).toBeLessThanOrEqual(requestedPort + 10);
     });
   });
 });
 
 describe('devCommand edge cases', () => {
   it('should handle port conflicts gracefully', async () => {
-    const port = 45300;
-    const server = await occupyPort(port);
-
-    try {
-      // The dev command should find an alternative port
-      const alternativePort = await findAvailablePort(port);
-      expect(alternativePort).toBeGreaterThan(port);
-    } finally {
-      server.close();
-    }
+    const { port } = await occupyPort(0);
+
+    // The dev command should find an alternative port
+    const alternativePort = await findAvailablePort(port);
+    expect(alternativePort).toBeGreaterThan(port);
   });
 
   it('should handle concurrent port checks', async () => {
-    const basePort = 45400;
+    // Get three random available ports as base
+    const { server: s1, port: p1 } = await occupyPort(0);
+    const { server: s2, port: p2 } = await occupyPort(0);
+    const { server: s3, port: p3 } = await occupyPort(0);
+    s1.close();
+    s2.close();
+    s3.close();
+    await new Promise((resolve) => setTimeout(resolve, 50));
 
     // Run multiple port checks concurrently
     const results = await Promise.all([
-      findAvailablePort(basePort),
-      findAvailablePort(basePort + 5),
-      findAvailablePort(basePort + 10),
+      findAvailablePort(p1),
+      findAvailablePort(p2),
+      findAvailablePort(p3),
     ]);
 
     // All should succeed and return valid ports
     expect(results).toHaveLength(3);
-    results.forEach((port) => {
-      expect(port).toBeGreaterThanOrEqual(basePort);
-    });
+    expect(results[0]).toBe(p1);
+    expect(results[1]).toBe(p2);
+    expect(results[2]).toBe(p3);
   });
 });
 

package/src/dev/index.ts

@@ -1,12 +1,14 @@
 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, NormalizedTelescopeConfig } from '../build/types';
-import { loadConfig } from '../config';
+import { loadConfig, parseModuleConfig } from '../config';
 import {
   CronGenerator,
   EndpointGenerator,
@@ -22,6 +24,39 @@ import type {
 
 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
@@ -79,6 +114,23 @@ export function normalizeTelescopeConfig(
     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;
@@ -106,8 +158,26 @@ export interface DevOptions {
 }
 
 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' });
 
@@ -124,21 +194,11 @@ 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);

package/src/generators/EndpointGenerator.ts

@@ -336,10 +336,23 @@ export function setupEndpoints(
     // 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 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
       ? `
@@ -375,8 +388,23 @@ import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`
 `
       : '';
 
-    const telescopeSetup = telescopeEnabled
-      ? `
+    // 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({
@@ -393,8 +421,9 @@ ${telescopeWebSocketSetupCode}
   // Mount telescope UI
   const telescopeUI = createUI(telescope);
   honoApp.route('${context.telescope!.path}', telescopeUI);
-`
-      : '';
+`;
+      }
+    }
 
     const content = `/**
  * Generated server application

package/src/index.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import pkg from '../package.json' assert { type: 'json' };
 import { buildCommand } from './build/index.ts';
 import { devCommand } from './dev/index.ts';
+import { type InitOptions, initCommand } from './init/index.ts';
 import { generateReactQueryCommand } from './openapi-react-query.ts';
 import { openapiCommand } from './openapi.ts';
 import type { LegacyProvider, MainProvider } from './types.ts';
@@ -16,6 +17,31 @@ program
   .version(pkg.version)
   .option('--cwd <path>', 'Change working directory');
 
+program
+  .command('init')
+  .description('Scaffold a new project')
+  .argument('[name]', 'Project name')
+  .option(
+    '--template <template>',
+    'Project template (minimal, api, serverless, worker)',
+  )
+  .option('--skip-install', 'Skip dependency installation', false)
+  .option('-y, --yes', 'Skip prompts, use defaults', false)
+  .option('--monorepo', 'Setup as monorepo with packages/models', false)
+  .option('--api-path <path>', 'API app path in monorepo (default: apps/api)')
+  .action(async (name: string | undefined, options: InitOptions) => {
+    try {
+      const globalOptions = program.opts();
+      if (globalOptions.cwd) {
+        process.chdir(globalOptions.cwd);
+      }
+      await initCommand(name, options);
+    } catch (error) {
+      console.error('Init failed:', (error as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('build')
   .description('Build handlers from endpoints, functions, and crons')