@geekmidas/cli 0.5.0 → 0.6.0

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

@@ -15,6 +15,7 @@ import {
   FunctionGenerator,
   SubscriberGenerator,
 } from '../generators';
+import { generateOpenApi, resolveOpenApiConfig } from '../openapi';
 import type {
   GkmConfig,
   LegacyProvider,
@@ -206,6 +207,12 @@ export async function devCommand(options: DevOptions): Promise<void> {
     logger.log(`🔭 Telescope enabled at ${telescope.path}`);
   }
 
+  // Resolve OpenAPI configuration
+  const openApiConfig = resolveOpenApiConfig(config);
+  if (openApiConfig.enabled) {
+    logger.log(`📄 OpenAPI output: ${openApiConfig.output}`);
+  }
+
   const buildContext: BuildContext = {
     envParserPath,
     envParserImportPattern,
@@ -222,6 +229,11 @@ export async function devCommand(options: DevOptions): Promise<void> {
     resolved.enableOpenApi,
   );
 
+  // Generate OpenAPI spec on startup
+  if (openApiConfig.enabled) {
+    await generateOpenApi(config);
+  }
+
   // Determine runtime (default to node)
   const runtime: Runtime = config.runtime ?? 'node';
 
@@ -307,6 +319,12 @@ export async function devCommand(options: DevOptions): Promise<void> {
           resolved.providers[0] as LegacyProvider,
           resolved.enableOpenApi,
         );
+
+        // Regenerate OpenAPI if enabled
+        if (openApiConfig.enabled) {
+          await generateOpenApi(config, { silent: true });
+        }
+
         logger.log('✅ Rebuild complete, restarting server...');
         await devServer.restart();
       } catch (error) {

package/src/init/generators/config.ts

@@ -11,17 +11,29 @@ export function generateConfigFiles(
   options: TemplateOptions,
   template: TemplateConfig,
 ): GeneratedFile[] {
-  const { telescope } = options;
+  const { telescope, routesStructure } = options;
   const isServerless = template.name === 'serverless';
   const hasWorker = template.name === 'worker';
 
+  // Get routes glob pattern based on structure
+  const getRoutesGlob = () => {
+    switch (routesStructure) {
+      case 'centralized-endpoints':
+        return './src/endpoints/**/*.ts';
+      case 'centralized-routes':
+        return './src/routes/**/*.ts';
+      case 'domain-based':
+        return './src/**/routes/*.ts';
+    }
+  };
+
   // Build gkm.config.ts
-  let gkmConfig = `import { defineConfig } from '@geekmidas/cli';
+  let gkmConfig = `import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
-  routes: './src/endpoints/**/*.ts',
-  envParser: './src/config/env',
-  logger: './src/config/logger',`;
+  routes: '${getRoutesGlob()}',
+  envParser: './src/config/env#envParser',
+  logger: './src/config/logger#logger',`;
 
   if (isServerless || hasWorker) {
     gkmConfig += `
@@ -42,6 +54,12 @@ export default defineConfig({
   },`;
   }
 
+  // Always add openapi config (output path is fixed to .gkm/openapi.ts)
+  gkmConfig += `
+  openapi: {
+    enabled: true,
+  },`;
+
   gkmConfig += `
 });
 `;

package/src/init/generators/package.ts

@@ -1,7 +1,8 @@
-import type {
-  GeneratedFile,
-  TemplateConfig,
-  TemplateOptions,
+import {
+  type GeneratedFile,
+  OPENAPI_OUTPUT_PATH,
+  type TemplateConfig,
+  type TemplateOptions,
 } from '../templates/index.js';
 
 /**
@@ -67,6 +68,12 @@ export function generatePackageJson(
     version: '0.0.1',
     private: true,
     type: 'module',
+    exports: {
+      './client': {
+        types: OPENAPI_OUTPUT_PATH,
+        import: OPENAPI_OUTPUT_PATH,
+      },
+    },
     scripts,
     dependencies: sortObject(dependencies),
     devDependencies: sortObject(devDependencies),

package/src/init/index.ts

@@ -13,7 +13,8 @@ import {
   type TemplateName,
   type TemplateOptions,
   getTemplate,
-  routeStyleChoices,
+  loggerTypeChoices,
+  routesStructureChoices,
   templateChoices,
 } from './templates/index.js';
 import {
@@ -85,9 +86,16 @@ export async function initCommand(
       },
       {
         type: options.yes ? null : 'select',
-        name: 'routeStyle',
-        message: 'Route organization:',
-        choices: routeStyleChoices,
+        name: 'loggerType',
+        message: 'Logger:',
+        choices: loggerTypeChoices,
+        initial: 0,
+      },
+      {
+        type: options.yes ? null : 'select',
+        name: 'routesStructure',
+        message: 'Routes structure:',
+        choices: routesStructureChoices,
         initial: 0,
       },
       {
@@ -137,9 +145,10 @@ export async function initCommand(
     template: options.template || answers.template || 'minimal',
     telescope: options.yes ? true : (answers.telescope ?? true),
     database: options.yes ? true : (answers.database ?? true),
-    routeStyle: options.yes
-      ? 'file-based'
-      : (answers.routeStyle ?? 'file-based'),
+    loggerType: options.yes ? 'pino' : (answers.loggerType ?? 'pino'),
+    routesStructure: options.yes
+      ? 'centralized-endpoints'
+      : (answers.routesStructure ?? 'centralized-endpoints'),
     monorepo,
     apiPath: monorepo ? (options.apiPath ?? answers.apiPath ?? 'apps/api') : '',
   };
@@ -199,6 +208,16 @@ export async function initCommand(
     } catch {
       console.error('\n  Warning: Failed to install dependencies.');
     }
+
+    // Format generated files with biome
+    try {
+      execSync('npx @biomejs/biome format --write --unsafe .', {
+        cwd: targetDir,
+        stdio: 'inherit',
+      });
+    } catch {
+      // Silently ignore format errors
+    }
   }
 
   // Print next steps

package/src/init/templates/api.ts

@@ -41,6 +41,30 @@ export const apiTemplate: TemplateConfig = {
   },
 
   files: (options: TemplateOptions): GeneratedFile[] => {
+    const { loggerType, routesStructure } = options;
+
+    const loggerContent = `import { createLogger } from '@geekmidas/logger/${loggerType}';
+
+export const logger = createLogger();
+`;
+
+    // Get route path based on structure
+    const getRoutePath = (file: string) => {
+      switch (routesStructure) {
+        case 'centralized-endpoints':
+          return `src/endpoints/${file}`;
+        case 'centralized-routes':
+          return `src/routes/${file}`;
+        case 'domain-based': {
+          const parts = file.split('/');
+          if (parts.length === 1) {
+            return `src/${file.replace('.ts', '')}/routes/index.ts`;
+          }
+          return `src/${parts[0]}/routes/${parts.slice(1).join('/')}`;
+        }
+      }
+    };
+
     const files: GeneratedFile[] = [
       // src/config/env.ts
       {
@@ -66,21 +90,15 @@ export const config = envParser
 `,
       },
 
-      // src/config/logger.ts - using pino
+      // src/config/logger.ts
       {
         path: 'src/config/logger.ts',
-        content: `import { PinoLogger } from '@geekmidas/logger/pino';
-
-export const logger = new PinoLogger({
-  app: '${options.name}',
-  level: process.env.LOG_LEVEL || 'info',
-});
-`,
+        content: loggerContent,
       },
 
-      // src/endpoints/health.ts
+      // health endpoint
       {
-        path: 'src/endpoints/health.ts',
+        path: getRoutePath('health.ts'),
         content: `import { e } from '@geekmidas/constructs/endpoints';
 
 export default e
@@ -91,46 +109,11 @@ export default e
   }));
 `,
       },
-    ];
-
-    // Add user endpoints based on route style
-    if (options.routeStyle === 'flat') {
-      files.push(
-        {
-          path: 'src/endpoints/users-list.ts',
-          content: `import { e } from '@geekmidas/constructs/endpoints';
-
-export default e
-  .get('/users')
-  .handle(async () => ({
-    users: [
-      { id: '1', name: 'Alice' },
-      { id: '2', name: 'Bob' },
-    ],
-  }));
-`,
-        },
-        {
-          path: 'src/endpoints/users-get.ts',
-          content: `import { e } from '@geekmidas/constructs/endpoints';
-import { z } from 'zod';
 
-export default e
-  .get('/users/:id')
-  .params(z.object({ id: z.string() }))
-  .handle(async ({ params }) => ({
-    id: params.id,
-    name: 'Alice',
-    email: 'alice@example.com',
-  }));
-`,
-        },
-      );
-    } else {
-      files.push(
-        {
-          path: 'src/endpoints/users/list.ts',
-          content: `import { e } from '@geekmidas/constructs/endpoints';
+      // users endpoints
+      {
+        path: getRoutePath('users/list.ts'),
+        content: `import { e } from '@geekmidas/constructs/endpoints';
 
 export default e
   .get('/users')
@@ -141,10 +124,10 @@ export default e
     ],
   }));
 `,
-        },
-        {
-          path: 'src/endpoints/users/get.ts',
-          content: `import { e } from '@geekmidas/constructs/endpoints';
+      },
+      {
+        path: getRoutePath('users/get.ts'),
+        content: `import { e } from '@geekmidas/constructs/endpoints';
 import { z } from 'zod';
 
 export default e
@@ -156,9 +139,8 @@ export default e
     email: 'alice@example.com',
   }));
 `,
-        },
-      );
-    }
+      },
+    ];
 
     // Add database service if enabled
     if (options.database) {