@geekmidas/cli 0.6.2 → 0.8.0

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';
@@ -7,7 +7,12 @@ 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 type {
+  BuildContext,
+  NormalizedHooksConfig,
+  NormalizedStudioConfig,
+  NormalizedTelescopeConfig,
+} from '../build/types';
 import { loadConfig, parseModuleConfig } from '../config';
 import {
   CronGenerator,
@@ -15,11 +20,16 @@ import {
   FunctionGenerator,
   SubscriberGenerator,
 } from '../generators';
-import { generateOpenApi, resolveOpenApiConfig } from '../openapi';
+import {
+  OPENAPI_OUTPUT_PATH,
+  generateOpenApi,
+  resolveOpenApiConfig,
+} from '../openapi';
 import type {
   GkmConfig,
   LegacyProvider,
   Runtime,
+  StudioConfig,
   TelescopeConfig,
 } from '../types';
 
@@ -153,6 +163,71 @@ export function normalizeTelescopeConfig(
   };
 }
 
+/**
+ * Normalize studio configuration
+ * @internal Exported for testing
+ */
+export function normalizeStudioConfig(
+  config: GkmConfig['studio'],
+): NormalizedStudioConfig | undefined {
+  if (config === false) {
+    return undefined;
+  }
+
+  // Handle string path (e.g., './src/config/studio')
+  if (typeof config === 'string') {
+    const { path: studioPath, importPattern: studioImportPattern } =
+      parseModuleConfig(config, 'studio');
+
+    return {
+      enabled: true,
+      studioPath,
+      studioImportPattern,
+      path: '/__studio',
+      schema: 'public',
+    };
+  }
+
+  // Default to enabled in development mode
+  const isEnabled =
+    config === true || config === undefined || config.enabled !== false;
+
+  if (!isEnabled) {
+    return undefined;
+  }
+
+  const studioConfig: StudioConfig = typeof config === 'object' ? config : {};
+
+  return {
+    enabled: true,
+    path: studioConfig.path ?? '/__studio',
+    schema: studioConfig.schema ?? 'public',
+  };
+}
+
+/**
+ * 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;
@@ -207,10 +282,24 @@ export async function devCommand(options: DevOptions): Promise<void> {
     logger.log(`🔭 Telescope enabled at ${telescope.path}`);
   }
 
+  // Normalize studio configuration
+  const studio = normalizeStudioConfig(config.studio);
+  if (studio) {
+    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);
-  if (openApiConfig.enabled) {
-    logger.log(`📄 OpenAPI output: ${openApiConfig.output}`);
+  // 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: ${OPENAPI_OUTPUT_PATH}`);
   }
 
   const buildContext: BuildContext = {
@@ -219,6 +308,8 @@ export async function devCommand(options: DevOptions): Promise<void> {
     loggerPath,
     loggerImportPattern,
     telescope,
+    studio,
+    hooks,
   };
 
   // Build initial version
@@ -226,11 +317,11 @@ export async function devCommand(options: DevOptions): Promise<void> {
     config,
     buildContext,
     resolved.providers[0] as LegacyProvider,
-    resolved.enableOpenApi,
+    enableOpenApi,
   );
 
   // Generate OpenAPI spec on startup
-  if (openApiConfig.enabled) {
+  if (enableOpenApi) {
     await generateOpenApi(config);
   }
 
@@ -241,8 +332,9 @@ export async function devCommand(options: DevOptions): Promise<void> {
   const devServer = new DevServer(
     resolved.providers[0] as LegacyProvider,
     options.port || 3000,
-    resolved.enableOpenApi,
+    enableOpenApi,
     telescope,
+    studio,
     runtime,
   );
 
@@ -252,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] : []),
@@ -260,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
@@ -317,11 +416,11 @@ export async function devCommand(options: DevOptions): Promise<void> {
           config,
           buildContext,
           resolved.providers[0] as LegacyProvider,
-          resolved.enableOpenApi,
+          enableOpenApi,
         );
 
         // Regenerate OpenAPI if enabled
-        if (openApiConfig.enabled) {
+        if (enableOpenApi) {
           await generateOpenApi(config, { silent: true });
         }
 
@@ -334,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);
@@ -392,6 +501,7 @@ class DevServer {
     private requestedPort: number,
     private enableOpenApi: boolean,
     private telescope?: NormalizedTelescopeConfig,
+    private studio?: NormalizedStudioConfig,
     private runtime: Runtime = 'node',
   ) {
     this.actualPort = requestedPort;
@@ -455,7 +565,7 @@ class DevServer {
       logger.log(`\n🎉 Server running at http://localhost:${this.actualPort}`);
       if (this.enableOpenApi) {
         logger.log(
-          `📚 API Docs available at http://localhost:${this.actualPort}/docs`,
+          `📚 API Docs available at http://localhost:${this.actualPort}/__docs`,
         );
       }
       if (this.telescope) {
@@ -463,44 +573,50 @@ class DevServer {
           `🔭 Telescope available at http://localhost:${this.actualPort}${this.telescope.path}`,
         );
       }
+      if (this.studio) {
+        logger.log(
+          `🗄️  Studio available at http://localhost:${this.actualPort}${this.studio.path}`,
+        );
+      }
     }
   }
 
   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

@@ -289,12 +289,12 @@ const endpoints: Endpoint<any, any, any, any, any, any, any, any, any, any, any,
   ${allExportNames.join(',\n  ')}
 ];
 
-export function setupEndpoints(
+export async function setupEndpoints(
   app: Hono,
   envParser: EnvironmentParser<any>,
   logger: Logger,
   enableOpenApi: boolean = true,
-): void {
+): Promise<void> {
   const serviceDiscovery = ServiceDiscovery.getInstance(
     logger,
     envParser
@@ -302,7 +302,7 @@ export function setupEndpoints(
 
   // Configure OpenAPI options based on enableOpenApi flag
   const openApiOptions: any = enableOpenApi ? {
-    docsPath: '/docs',
+    docsPath: '/__docs',
     openApiOptions: {
       title: 'API Documentation',
       version: '1.0.0',
@@ -311,6 +311,16 @@ export function setupEndpoints(
   } : { docsPath: false };
 
   HonoEndpoint.addRoutes(endpoints, serviceDiscovery, app, openApiOptions);
+
+  // Add Swagger UI if OpenAPI is enabled
+  if (enableOpenApi) {
+    try {
+      const { swaggerUI } = await import('@hono/swagger-ui');
+      app.get('/__docs/ui', swaggerUI({ url: '/__docs' }));
+    } catch {
+      // @hono/swagger-ui not installed, skip Swagger UI
+    }
+  }
 }
 `;
 
@@ -338,6 +348,10 @@ export function setupEndpoints(
     const telescopeWebSocketEnabled = context.telescope?.websocket;
     const usesExternalTelescope = !!context.telescope?.telescopePath;
 
+    // Generate studio imports and setup if enabled
+    const studioEnabled = context.studio?.enabled;
+    const usesExternalStudio = !!context.studio?.studioPath;
+
     // Generate imports based on whether telescope is external or inline
     let telescopeImports = '';
     if (telescopeEnabled) {
@@ -354,6 +368,46 @@ import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`;
       }
     }
 
+    // Generate imports for studio
+    let studioImports = '';
+    if (studioEnabled) {
+      if (usesExternalStudio) {
+        const relativeStudioPath = relative(
+          dirname(appPath),
+          context.studio!.studioPath!,
+        );
+        studioImports = `import ${context.studio!.studioImportPattern} from '${relativeStudioPath}';
+import { createStudioApp } from '@geekmidas/studio/server/hono';`;
+      } else {
+        studioImports = `// Studio requires a configured instance - use studio config path
+// 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
@@ -425,6 +479,16 @@ ${telescopeWebSocketSetupCode}
       }
     }
 
+    // Generate studio setup - requires external instance
+    let studioSetup = '';
+    if (studioEnabled && usesExternalStudio) {
+      studioSetup = `
+  // Mount Studio data browser UI
+  const studioApp = createStudioApp(studio);
+  honoApp.route('${context.studio!.path}', studioApp);
+`;
+    }
+
     const content = `/**
  * Generated server application
  *
@@ -439,6 +503,8 @@ import { setupSubscribers } from './subscribers.js';
 import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
 import ${context.loggerImportPattern} from '${relativeLoggerPath}';
 ${telescopeImports}
+${studioImports}
+${hooksImports}
 
 export interface ServerApp {
   app: HonoType;
@@ -484,9 +550,10 @@ export interface ServerApp {
  */
 export async function createApp(app?: HonoType, enableOpenApi: boolean = true): Promise<ServerApp> {
   const honoApp = app || new Hono();
-${telescopeSetup}
+${telescopeSetup}${beforeSetupCall}${studioSetup}
   // Setup HTTP endpoints
-  setupEndpoints(honoApp, envParser, logger, enableOpenApi);
+  await setupEndpoints(honoApp, envParser, logger, enableOpenApi);
+${afterSetupCall}
 
   return {
     app: honoApp,

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

@@ -111,7 +111,7 @@ describe('EndpointGenerator', () => {
     // Function signature always defaults to true
     expect(endpointsContent).toContain('enableOpenApi: boolean = true');
     // OpenAPI options are configured based on the parameter
-    expect(endpointsContent).toContain("docsPath: '/docs'");
+    expect(endpointsContent).toContain("docsPath: '/__docs'");
   });
 
   itWithDir(

package/src/init/generators/config.ts

@@ -11,7 +11,7 @@ export function generateConfigFiles(
   options: TemplateOptions,
   template: TemplateConfig,
 ): GeneratedFile[] {
-  const { telescope, routesStructure } = options;
+  const { telescope, studio, routesStructure } = options;
   const isServerless = template.name === 'serverless';
   const hasWorker = template.name === 'worker';
 
@@ -54,6 +54,11 @@ export default defineConfig({
   },`;
   }
 
+  if (studio) {
+    gkmConfig += `
+  studio: './src/config/studio#studio',`;
+  }
+
   // Always add openapi config (output path is fixed to .gkm/openapi.ts)
   gkmConfig += `
   openapi: {

package/src/init/generators/package.ts

@@ -12,7 +12,7 @@ export function generatePackageJson(
   options: TemplateOptions,
   template: TemplateConfig,
 ): GeneratedFile[] {
-  const { name, telescope, database, monorepo } = options;
+  const { name, telescope, database, studio, monorepo } = options;
 
   // Start with template dependencies
   const dependencies = { ...template.dependencies };
@@ -24,6 +24,10 @@ export function generatePackageJson(
     dependencies['@geekmidas/telescope'] = 'workspace:*';
   }
 
+  if (studio) {
+    dependencies['@geekmidas/studio'] = 'workspace:*';
+  }
+
   if (database) {
     dependencies['@geekmidas/db'] = 'workspace:*';
     dependencies['kysely'] = '~0.28.2';

package/src/init/index.ts

@@ -84,6 +84,12 @@ export async function initCommand(
         message: 'Include database support (Kysely)?',
         initial: true,
       },
+      {
+        type: (prev) => (options.yes ? null : prev ? 'confirm' : null),
+        name: 'studio',
+        message: 'Include Studio (database browser)?',
+        initial: true,
+      },
       {
         type: options.yes ? null : 'select',
         name: 'loggerType',
@@ -140,11 +146,13 @@ export async function initCommand(
 
   const monorepo =
     options.monorepo ?? (options.yes ? false : (answers.monorepo ?? false));
+  const database = options.yes ? true : (answers.database ?? true);
   const templateOptions: TemplateOptions = {
     name,
     template: options.template || answers.template || 'minimal',
     telescope: options.yes ? true : (answers.telescope ?? true),
-    database: options.yes ? true : (answers.database ?? true),
+    database,
+    studio: database && (options.yes ? true : (answers.studio ?? true)),
     loggerType: options.yes ? 'pino' : (answers.loggerType ?? 'pino'),
     routesStructure: options.yes
       ? 'centralized-endpoints'

package/src/init/templates/api.ts

@@ -195,6 +195,37 @@ export const telescope = new Telescope({
       });
     }
 
+    // Add Studio config if enabled (requires database)
+    if (options.studio && options.database) {
+      files.push({
+        path: 'src/config/studio.ts',
+        content: `import { Direction, InMemoryMonitoringStorage, Studio } from '@geekmidas/studio';
+import { Kysely, PostgresDialect } from 'kysely';
+import pg from 'pg';
+import type { Database } from '../services/database';
+import { config } from './env';
+
+// Create a Kysely instance for Studio
+const db = new Kysely<Database>({
+  dialect: new PostgresDialect({
+    pool: new pg.Pool({ connectionString: config.database.url }),
+  }),
+});
+
+export const studio = new Studio<Database>({
+  monitoring: {
+    storage: new InMemoryMonitoringStorage({ maxEntries: 100 }),
+  },
+  data: {
+    db,
+    cursor: { field: 'id', direction: Direction.Desc },
+  },
+  enabled: process.env.NODE_ENV === 'development',
+});
+`,
+      });
+    }
+
     return files;
   },
 };

package/src/init/templates/index.ts

@@ -29,6 +29,7 @@ export interface TemplateOptions {
   template: TemplateName;
   telescope: boolean;
   database: boolean;
+  studio: boolean;
   loggerType: LoggerType;
   routesStructure: RoutesStructure;
   monorepo: boolean;

package/src/init/templates/minimal.ts

@@ -95,6 +95,58 @@ export default e
       },
     ];
 
+    // Add database service if enabled
+    if (options.database) {
+      // Update env.ts to include database config
+      files[0] = {
+        path: 'src/config/env.ts',
+        content: `import { EnvironmentParser } from '@geekmidas/envkit';
+
+export const envParser = new EnvironmentParser(process.env);
+
+export const config = envParser
+  .create((get) => ({
+    port: get('PORT').string().transform(Number).default(3000),
+    nodeEnv: get('NODE_ENV').string().default('development'),
+    database: {
+      url: get('DATABASE_URL').string().default('postgresql://localhost:5432/mydb'),
+    },
+  }))
+  .parse();
+`,
+      };
+
+      files.push({
+        path: 'src/services/database.ts',
+        content: `import type { Service } from '@geekmidas/services';
+import { Kysely, PostgresDialect } from 'kysely';
+import pg from 'pg';
+
+// Define your database schema
+export interface Database {
+  // Add your tables here
+}
+
+export const databaseService = {
+  serviceName: 'database' as const,
+  async register(envParser) {
+    const config = envParser
+      .create((get) => ({
+        url: get('DATABASE_URL').string(),
+      }))
+      .parse();
+
+    return new Kysely<Database>({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool({ connectionString: config.url }),
+      }),
+    });
+  },
+} satisfies Service<'database', Kysely<Database>>;
+`,
+      });
+    }
+
     // Add Telescope config if enabled
     if (options.telescope) {
       files.push({
@@ -110,6 +162,37 @@ export const telescope = new Telescope({
       });
     }
 
+    // Add Studio config if enabled (requires database)
+    if (options.studio && options.database) {
+      files.push({
+        path: 'src/config/studio.ts',
+        content: `import { Direction, InMemoryMonitoringStorage, Studio } from '@geekmidas/studio';
+import { Kysely, PostgresDialect } from 'kysely';
+import pg from 'pg';
+import type { Database } from '../services/database';
+import { config } from './env';
+
+// Create a Kysely instance for Studio
+const db = new Kysely<Database>({
+  dialect: new PostgresDialect({
+    pool: new pg.Pool({ connectionString: config.database.url }),
+  }),
+});
+
+export const studio = new Studio<Database>({
+  monitoring: {
+    storage: new InMemoryMonitoringStorage({ maxEntries: 100 }),
+  },
+  data: {
+    db,
+    cursor: { field: 'id', direction: Direction.Desc },
+  },
+  enabled: process.env.NODE_ENV === 'development',
+});
+`,
+      });
+    }
+
     return files;
   },
 };