@geekmidas/cli 0.7.0 → 0.8.0

package/src/__tests__/EndpointGenerator.hooks.spec.ts

@@ -0,0 +1,204 @@
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { e } from '@geekmidas/constructs/endpoints';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { BuildContext } from '../build/types';
+import { EndpointGenerator } from '../generators/EndpointGenerator';
+import type { GeneratedConstruct } from '../generators/Generator';
+
+// Create a minimal mock endpoint for testing
+const mockEndpoint = e.get('/test').handle(async () => ({ ok: true }));
+
+describe('EndpointGenerator hooks generation', () => {
+  const testOutputDir = join(process.cwd(), '.test-output');
+  let generator: EndpointGenerator;
+
+  // Mock endpoint construct for testing
+  const mockConstruct: GeneratedConstruct<typeof mockEndpoint> = {
+    key: 'testEndpoint',
+    construct: mockEndpoint,
+    path: {
+      relative: '/project/src/endpoints/test.ts',
+      absolute: '/project/src/endpoints/test.ts',
+    },
+  };
+
+  beforeEach(async () => {
+    generator = new EndpointGenerator();
+    await mkdir(testOutputDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testOutputDir, { recursive: true, force: true });
+  });
+
+  const baseContext: BuildContext = {
+    envParserPath: '/project/src/config/env.ts',
+    envParserImportPattern: '{ envParser }',
+    loggerPath: '/project/src/config/logger.ts',
+    loggerImportPattern: 'logger',
+  };
+
+  describe('generateAppFile', () => {
+    it('should not include hooks when hooks config is undefined', async () => {
+      await generator.build(baseContext, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      expect(appContent).not.toContain('serverHooks');
+      expect(appContent).not.toContain('beforeSetup');
+      expect(appContent).not.toContain('afterSetup');
+    });
+
+    it('should include hooks imports when hooks config is provided', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: '/project/src/config/hooks.ts',
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      expect(appContent).toContain('import * as serverHooks from');
+      expect(appContent).toContain('hooks.ts');
+    });
+
+    it('should include beforeSetup hook call', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: '/project/src/config/hooks.ts',
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      expect(appContent).toContain(
+        "if (typeof serverHooks.beforeSetup === 'function')",
+      );
+      expect(appContent).toContain(
+        'await serverHooks.beforeSetup(honoApp, { envParser, logger })',
+      );
+    });
+
+    it('should include afterSetup hook call', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: '/project/src/config/hooks.ts',
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      expect(appContent).toContain(
+        "if (typeof serverHooks.afterSetup === 'function')",
+      );
+      expect(appContent).toContain(
+        'await serverHooks.afterSetup(honoApp, { envParser, logger })',
+      );
+    });
+
+    it('should place telescope before beforeSetup, and beforeSetup before endpoints', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: '/project/src/config/hooks.ts',
+        },
+        telescope: {
+          enabled: true,
+          path: '/__telescope',
+          maxEntries: 100,
+          recordBody: true,
+          ignore: [],
+          websocket: false,
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      // Use specific patterns to find the actual calls (not imports/comments)
+      const telescopeIndex = appContent.indexOf('createMiddleware(telescope)');
+      const beforeSetupCallIndex = appContent.indexOf(
+        'serverHooks.beforeSetup(honoApp',
+      );
+      const setupEndpointsIndex = appContent.indexOf(
+        'await setupEndpoints(honoApp',
+      );
+
+      expect(telescopeIndex).toBeGreaterThan(0);
+      expect(beforeSetupCallIndex).toBeGreaterThan(0);
+      expect(setupEndpointsIndex).toBeGreaterThan(0);
+      // Telescope middleware first (to capture all requests)
+      expect(telescopeIndex).toBeLessThan(beforeSetupCallIndex);
+      // Then beforeSetup hook
+      expect(beforeSetupCallIndex).toBeLessThan(setupEndpointsIndex);
+    });
+
+    it('should place afterSetup after setupEndpoints', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: '/project/src/config/hooks.ts',
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      // Use specific patterns to find the actual calls (not imports/comments)
+      const setupEndpointsIndex = appContent.indexOf(
+        'await setupEndpoints(honoApp',
+      );
+      const afterSetupCallIndex = appContent.indexOf(
+        'serverHooks.afterSetup(honoApp',
+      );
+
+      expect(setupEndpointsIndex).toBeGreaterThan(0);
+      expect(afterSetupCallIndex).toBeGreaterThan(0);
+      expect(afterSetupCallIndex).toBeGreaterThan(setupEndpointsIndex);
+    });
+
+    it('should generate correct relative import path for hooks', async () => {
+      const contextWithHooks: BuildContext = {
+        ...baseContext,
+        hooks: {
+          serverHooksPath: join(testOutputDir, '../../src/config/hooks.ts'),
+        },
+      };
+
+      await generator.build(contextWithHooks, [mockConstruct], testOutputDir, {
+        provider: 'server',
+      });
+
+      const appContent = await readFile(join(testOutputDir, 'app.ts'), 'utf-8');
+
+      // Should have a relative import path
+      expect(appContent).toMatch(
+        /import \* as serverHooks from '\.\.\/.*hooks\.ts'/,
+      );
+    });
+  });
+});

package/src/__tests__/normalizeHooksConfig.spec.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { normalizeHooksConfig } from '../dev';
+
+describe('normalizeHooksConfig', () => {
+  const originalCwd = process.cwd();
+
+  beforeEach(() => {
+    vi.spyOn(process, 'cwd').mockReturnValue('/test/project');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should return undefined when hooks config is undefined', () => {
+    const result = normalizeHooksConfig(undefined);
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined when hooks config is empty object', () => {
+    const result = normalizeHooksConfig({});
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined when server hooks path is not provided', () => {
+    const result = normalizeHooksConfig({ server: undefined });
+    expect(result).toBeUndefined();
+  });
+
+  it('should normalize path with .ts extension', () => {
+    const result = normalizeHooksConfig({ server: './src/hooks.ts' });
+
+    expect(result).toBeDefined();
+    expect(result!.serverHooksPath).toBe('/test/project/src/hooks.ts');
+  });
+
+  it('should add .ts extension when missing', () => {
+    const result = normalizeHooksConfig({ server: './src/hooks' });
+
+    expect(result).toBeDefined();
+    expect(result!.serverHooksPath).toBe('/test/project/src/hooks.ts');
+  });
+
+  it('should resolve relative paths from cwd', () => {
+    const result = normalizeHooksConfig({ server: 'config/server-hooks' });
+
+    expect(result).toBeDefined();
+    expect(result!.serverHooksPath).toBe(
+      '/test/project/config/server-hooks.ts',
+    );
+  });
+
+  it('should handle nested directory paths', () => {
+    const result = normalizeHooksConfig({
+      server: './src/config/hooks/server',
+    });
+
+    expect(result).toBeDefined();
+    expect(result!.serverHooksPath).toBe(
+      '/test/project/src/config/hooks/server.ts',
+    );
+  });
+});

package/src/build/index.ts

@@ -5,7 +5,7 @@ import type { Endpoint } from '@geekmidas/constructs/endpoints';
 import type { Function } from '@geekmidas/constructs/functions';
 import type { Subscriber } from '@geekmidas/constructs/subscribers';
 import { loadConfig, parseModuleConfig } from '../config';
-import { normalizeTelescopeConfig } from '../dev';
+import { normalizeHooksConfig, normalizeTelescopeConfig } from '../dev';
 import {
   CronGenerator,
   EndpointGenerator,
@@ -55,12 +55,19 @@ export async function buildCommand(options: BuildOptions): Promise<void> {
     logger.log(`🔭 Telescope enabled at ${telescope.path}`);
   }
 
+  // Normalize hooks configuration
+  const hooks = normalizeHooksConfig(config.hooks);
+  if (hooks) {
+    logger.log(`🪝 Server hooks enabled`);
+  }
+
   const buildContext: BuildContext = {
     envParserPath,
     envParserImportPattern,
     loggerPath,
     loggerImportPattern,
     telescope,
+    hooks,
   };
 
   // Initialize generators

package/src/build/types.ts

@@ -50,6 +50,11 @@ export interface NormalizedStudioConfig {
   schema: string;
 }
 
+export interface NormalizedHooksConfig {
+  /** Path to server hooks module */
+  serverHooksPath: string;
+}
+
 export interface BuildContext {
   envParserPath: string;
   envParserImportPattern: string;
@@ -57,6 +62,7 @@ export interface BuildContext {
   loggerImportPattern: string;
   telescope?: NormalizedTelescopeConfig;
   studio?: NormalizedStudioConfig;
+  hooks?: NormalizedHooksConfig;
 }
 
 export interface ProviderBuildResult {

package/src/dev/index.ts

@@ -1,4 +1,4 @@
-import { type ChildProcess, spawn } from 'node:child_process';
+import { type ChildProcess, execSync, spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { createServer } from 'node:net';
@@ -9,6 +9,7 @@ import fg from 'fast-glob';
 import { resolveProviders } from '../build/providerResolver';
 import type {
   BuildContext,
+  NormalizedHooksConfig,
   NormalizedStudioConfig,
   NormalizedTelescopeConfig,
 } from '../build/types';
@@ -19,7 +20,11 @@ import {
   FunctionGenerator,
   SubscriberGenerator,
 } from '../generators';
-import { generateOpenApi, resolveOpenApiConfig } from '../openapi';
+import {
+  OPENAPI_OUTPUT_PATH,
+  generateOpenApi,
+  resolveOpenApiConfig,
+} from '../openapi';
 import type {
   GkmConfig,
   LegacyProvider,
@@ -200,6 +205,29 @@ export function normalizeStudioConfig(
   };
 }
 
+/**
+ * Normalize hooks configuration
+ * @internal Exported for testing
+ */
+export function normalizeHooksConfig(
+  config: GkmConfig['hooks'],
+): NormalizedHooksConfig | undefined {
+  if (!config?.server) {
+    return undefined;
+  }
+
+  // Resolve the path (handle .ts extension)
+  const serverPath = config.server.endsWith('.ts')
+    ? config.server
+    : `${config.server}.ts`;
+
+  const resolvedPath = resolve(process.cwd(), serverPath);
+
+  return {
+    serverHooksPath: resolvedPath,
+  };
+}
+
 export interface DevOptions {
   port?: number;
   enableOpenApi?: boolean;
@@ -260,12 +288,18 @@ export async function devCommand(options: DevOptions): Promise<void> {
     logger.log(`🗄️  Studio enabled at ${studio.path}`);
   }
 
+  // Normalize hooks configuration
+  const hooks = normalizeHooksConfig(config.hooks);
+  if (hooks) {
+    logger.log(`🪝 Server hooks enabled from ${config.hooks?.server}`);
+  }
+
   // Resolve OpenAPI configuration
   const openApiConfig = resolveOpenApiConfig(config);
   // Enable OpenAPI docs endpoint if either root config or provider config enables it
   const enableOpenApi = openApiConfig.enabled || resolved.enableOpenApi;
   if (enableOpenApi) {
-    logger.log(`📄 OpenAPI output: ${openApiConfig.output}`);
+    logger.log(`📄 OpenAPI output: ${OPENAPI_OUTPUT_PATH}`);
   }
 
   const buildContext: BuildContext = {
@@ -275,6 +309,7 @@ export async function devCommand(options: DevOptions): Promise<void> {
     loggerImportPattern,
     telescope,
     studio,
+    hooks,
   };
 
   // Build initial version
@@ -309,6 +344,9 @@ export async function devCommand(options: DevOptions): Promise<void> {
   const envParserFile = config.envParser.split('#')[0];
   const loggerFile = config.logger.split('#')[0];
 
+  // Get hooks file path for watching
+  const hooksFile = config.hooks?.server?.split('#')[0];
+
   const watchPatterns = [
     config.routes,
     ...(config.functions ? [config.functions] : []),
@@ -317,6 +355,10 @@ export async function devCommand(options: DevOptions): Promise<void> {
     // Add .ts extension if not present for config files
     envParserFile.endsWith('.ts') ? envParserFile : `${envParserFile}.ts`,
     loggerFile.endsWith('.ts') ? loggerFile : `${loggerFile}.ts`,
+    // Add hooks file to watch list
+    ...(hooksFile
+      ? [hooksFile.endsWith('.ts') ? hooksFile : `${hooksFile}.ts`]
+      : []),
   ].flat();
 
   // Normalize patterns - remove leading ./ when using cwd option
@@ -391,11 +433,21 @@ export async function devCommand(options: DevOptions): Promise<void> {
   });
 
   // Handle graceful shutdown
-  const shutdown = async () => {
+  let isShuttingDown = false;
+  const shutdown = () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
     logger.log('\n🛑 Shutting down...');
-    await watcher.close();
-    await devServer.stop();
-    process.exit(0);
+
+    // Use sync-style shutdown to ensure it completes before exit
+    Promise.all([watcher.close(), devServer.stop()])
+      .catch((err) => {
+        logger.error('Error during shutdown:', err);
+      })
+      .finally(() => {
+        process.exit(0);
+      });
   };
 
   process.on('SIGINT', shutdown);
@@ -530,40 +582,41 @@ class DevServer {
   }
 
   async stop(): Promise<void> {
+    const port = this.actualPort;
+
     if (this.serverProcess && this.isRunning) {
       const pid = this.serverProcess.pid;
 
-      // Kill the entire process group (negative PID kills the group)
+      // Use SIGKILL directly since the server ignores SIGTERM
       if (pid) {
         try {
-          process.kill(-pid, 'SIGTERM');
+          process.kill(-pid, 'SIGKILL');
         } catch {
-          // Process might already be dead
+          try {
+            process.kill(pid, 'SIGKILL');
+          } catch {
+            // Process might already be dead
+          }
         }
       }
 
-      // Wait for process to exit
-      await new Promise<void>((resolve) => {
-        const timeout = setTimeout(() => {
-          if (pid) {
-            try {
-              process.kill(-pid, 'SIGKILL');
-            } catch {
-              // Process might already be dead
-            }
-          }
-          resolve();
-        }, 3000);
-
-        this.serverProcess?.on('exit', () => {
-          clearTimeout(timeout);
-          resolve();
-        });
-      });
-
       this.serverProcess = null;
       this.isRunning = false;
     }
+
+    // Also kill any processes still holding the port
+    this.killProcessesOnPort(port);
+  }
+
+  private killProcessesOnPort(port: number): void {
+    try {
+      // Use lsof to find PIDs on the port and kill them with -9
+      execSync(`lsof -ti tcp:${port} | xargs kill -9 2>/dev/null || true`, {
+        stdio: 'ignore',
+      });
+    } catch {
+      // Ignore errors - port may already be free
+    }
   }
 
   async restart(): Promise<void> {

package/src/generators/EndpointGenerator.ts

@@ -384,6 +384,30 @@ import { createStudioApp } from '@geekmidas/studio/server/hono';`;
       }
     }
 
+    // Generate imports for server hooks
+    let hooksImports = '';
+    let beforeSetupCall = '';
+    let afterSetupCall = '';
+    if (context.hooks?.serverHooksPath) {
+      const relativeHooksPath = relative(
+        dirname(appPath),
+        context.hooks.serverHooksPath,
+      );
+      hooksImports = `import * as serverHooks from '${relativeHooksPath}';`;
+      beforeSetupCall = `
+  // Call beforeSetup hook if defined
+  if (typeof serverHooks.beforeSetup === 'function') {
+    await serverHooks.beforeSetup(honoApp, { envParser, logger });
+  }
+`;
+      afterSetupCall = `
+  // Call afterSetup hook if defined
+  if (typeof serverHooks.afterSetup === 'function') {
+    await serverHooks.afterSetup(honoApp, { envParser, logger });
+  }
+`;
+    }
+
     const telescopeWebSocketSetupCode = telescopeWebSocketEnabled
       ? `
   // Setup WebSocket for real-time telescope updates
@@ -480,6 +504,7 @@ import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
 import ${context.loggerImportPattern} from '${relativeLoggerPath}';
 ${telescopeImports}
 ${studioImports}
+${hooksImports}
 
 export interface ServerApp {
   app: HonoType;
@@ -525,9 +550,10 @@ export interface ServerApp {
  */
 export async function createApp(app?: HonoType, enableOpenApi: boolean = true): Promise<ServerApp> {
   const honoApp = app || new Hono();
-${telescopeSetup}${studioSetup}
+${telescopeSetup}${beforeSetupCall}${studioSetup}
   // Setup HTTP endpoints
   await setupEndpoints(honoApp, envParser, logger, enableOpenApi);
+${afterSetupCall}
 
   return {
     app: honoApp,

package/src/types.ts

@@ -64,6 +64,34 @@ export interface OpenApiConfig {
   description?: string;
 }
 
+export interface HooksConfig {
+  /**
+   * Path to a module exporting server lifecycle hooks.
+   * The module should export `beforeSetup` and/or `afterSetup` functions.
+   *
+   * @example
+   * ```typescript
+   * // src/config/hooks.ts
+   * import type { Hono } from 'hono';
+   * import type { Logger } from '@geekmidas/logger';
+   * import type { EnvironmentParser } from '@geekmidas/envkit';
+   *
+   * // Called BEFORE gkm endpoints are registered
+   * export function beforeSetup(app: Hono, ctx: { envParser: EnvironmentParser; logger: Logger }) {
+   *   app.use('*', cors());
+   *   app.get('/custom/health', (c) => c.json({ status: 'ok' }));
+   * }
+   *
+   * // Called AFTER gkm endpoints are registered
+   * export function afterSetup(app: Hono, ctx: { envParser: EnvironmentParser; logger: Logger }) {
+   *   app.notFound((c) => c.json({ error: 'Not found' }, 404));
+   *   app.onError((err, c) => c.json({ error: err.message }, 500));
+   * }
+   * ```
+   */
+  server?: string;
+}
+
 export interface ProvidersConfig {
   aws?: {
     apiGateway?: {
@@ -86,6 +114,16 @@ export interface GkmConfig {
   envParser: string;
   logger: string;
   providers?: ProvidersConfig;
+  /**
+   * Server lifecycle hooks for customizing the Hono app.
+   * Allows adding custom routes, middleware, error handlers, etc.
+   *
+   * @example
+   * hooks: {
+   *   server: './src/config/hooks'
+   * }
+   */
+  hooks?: HooksConfig;
   /**
    * Telescope configuration for debugging/monitoring.
    * Can be: