@geekmidas/cli 0.3.0 → 0.4.0

package/README.md

@@ -5,6 +5,8 @@ A powerful CLI tool for building and managing TypeScript-based backend APIs with
 ## Features
 
 - **Multi-Provider Support**: Generate handlers for AWS Lambda (API Gateway v1/v2) and server applications
+- **Development Server**: Hot-reload development server with file watching
+- **Telescope Integration**: Laravel-style debugging dashboard for inspecting requests, logs, and exceptions
 - **OpenAPI Generation**: Auto-generate OpenAPI 3.0 specifications from your endpoints
 - **Type-Safe Configuration**: Configuration with TypeScript support and validation
 - **Endpoint Auto-Discovery**: Automatically find and load endpoints from your codebase
@@ -51,6 +53,12 @@ const config: GkmConfig = {
 
   // Logger configuration
   logger: './src/logger.ts#logger',
+
+  // Optional: Telescope debugging dashboard (enabled by default in dev)
+  telescope: {
+    enabled: true,
+    path: '/__telescope',
+  },
 };
 
 export default config;
@@ -166,8 +174,8 @@ npx gkm build --provider aws-apigatewayv1
 # Generate server application
 npx gkm build --provider server
 
-# Generate OpenAPI specification
-npx gkm openapi --output api-docs.json
+# Generate OpenAPI TypeScript module
+npx gkm openapi --output src/api.ts
 ```
 
 ## CLI Commands
@@ -197,19 +205,141 @@ gkm build --provider server
 
 ### `gkm openapi`
 
-Generate OpenAPI 3.0 specification from your endpoints.
+Generate OpenAPI TypeScript module from your endpoints. This is the recommended approach as it provides full type safety and a ready-to-use API client.
 
 ```bash
 gkm openapi [options]
 ```
 
 **Options:**
-- `--output <path>`: Output file path (default: `openapi.json`)
+- `--output <path>`: Output file path (default: `openapi.ts`)
+- `--json`: Generate legacy JSON format instead of TypeScript module
+
+**Example:**
+```bash
+# Generate TypeScript module (recommended)
+gkm openapi --output src/api.ts
+
+# Generate legacy JSON format
+gkm openapi --output docs/api.json --json
+```
+
+#### Generated TypeScript Module
+
+The generated TypeScript module includes:
+
+```typescript
+// src/api.ts (auto-generated)
+
+// Security schemes defined in your endpoints
+export const securitySchemes = {
+  jwt: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+  apiKey: { type: 'apiKey', in: 'header', name: 'X-API-Key' },
+} as const;
+
+export type SecuritySchemeId = 'jwt' | 'apiKey';
+
+// Endpoint-to-auth mapping
+export const endpointAuth = {
+  'GET /users': 'jwt',
+  'POST /users': 'jwt',
+  'GET /health': null,
+} as const;
+
+// TypeScript interfaces for request/response types
+export interface GetUsersOutput {
+  id: string;
+  name: string;
+}
+
+// OpenAPI paths interface
+export interface paths {
+  '/users': {
+    get: {
+      responses: {
+        200: { content: { 'application/json': GetUsersOutput[] } };
+      };
+    };
+  };
+}
+
+// Ready-to-use API client factory
+export function createApi(options: CreateApiOptions) {
+  // ... implementation
+}
+```
+
+#### Using the Generated Client
+
+```typescript
+import { createApi } from './api';
+
+const api = createApi({
+  baseURL: 'https://api.example.com',
+  authStrategies: {
+    jwt: {
+      type: 'bearer',
+      tokenProvider: async () => localStorage.getItem('token'),
+    },
+  },
+});
+
+// Imperative fetching
+const users = await api('GET /users');
+
+// React Query hooks
+const { data } = api.useQuery('GET /users');
+const mutation = api.useMutation('POST /users');
+```
+
+### `gkm dev`
+
+Start a development server with hot-reload and optional Telescope debugging dashboard.
+
+```bash
+gkm dev [options]
+```
+
+**Options:**
+- `--port <port>`: Server port (default: `3000`)
+
+**Features:**
+- Hot-reload on file changes (endpoints, functions, crons, subscribers)
+- Automatic port switching if requested port is in use
+- Telescope debugging dashboard (enabled by default)
+- Real-time WebSocket updates in Telescope
 
 **Example:**
 ```bash
-# Generate OpenAPI spec
-gkm openapi --output docs/api.json
+# Start development server on port 3000
+gkm dev
+
+# Start on custom port
+gkm dev --port 8080
+```
+
+**Output:**
+```
+🚀 Starting development server...
+Loading routes from: ./src/endpoints/**/*.ts
+Loading subscribers from: ./src/subscribers/**/*.ts
+Using envParser: ./src/config/env
+🔭 Telescope enabled at /__telescope
+Generated server with 5 endpoints
+
+✨ Starting server on port 3000...
+🔌 Telescope real-time updates enabled
+
+🎉 Server running at http://localhost:3000
+🔭 Telescope available at http://localhost:3000/__telescope
+👀 Watching for changes in: src/endpoints/**/*.ts, src/subscribers/**/*.ts
+```
+
+When files change, the server automatically rebuilds and restarts:
+```
+📝 File changed: src/endpoints/users.ts
+🔄 Rebuilding...
+✅ Rebuild complete, restarting server...
 ```
 
 ### Future Commands
@@ -231,6 +361,20 @@ interface GkmConfig {
   routes: string | string[];     // Glob patterns for endpoint files
   envParser: string;             // Path to environment parser
   logger: string;                // Path to logger configuration
+  functions?: string | string[]; // Glob patterns for function files
+  crons?: string | string[];     // Glob patterns for cron files
+  subscribers?: string | string[];// Glob patterns for subscriber files
+  runtime?: 'node' | 'bun';      // Runtime environment (default: 'node')
+  telescope?: boolean | TelescopeConfig; // Telescope debugging config
+}
+
+interface TelescopeConfig {
+  enabled?: boolean;       // Enable/disable (default: true in dev)
+  path?: string;           // Dashboard path (default: '/__telescope')
+  ignore?: string[];       // URL patterns to ignore
+  recordBody?: boolean;    // Record request/response bodies (default: true)
+  maxEntries?: number;     // Max entries to keep (default: 1000)
+  websocket?: boolean;     // Enable real-time updates (default: true)
 }
 ```
 
@@ -282,6 +426,65 @@ logger: './src/logger.ts#logger'
 logger: './src/utils.ts#appLogger'
 ```
 
+#### `telescope`
+
+Configuration for the Telescope debugging dashboard. Telescope is enabled by default when using `gkm dev`.
+
+```typescript
+// Disable telescope
+telescope: false
+
+// Enable with defaults
+telescope: true
+
+// Custom configuration
+telescope: {
+  enabled: true,
+  path: '/__telescope',
+  ignore: ['/health', '/metrics'],
+  recordBody: true,
+  maxEntries: 1000,
+  websocket: true,
+}
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable/disable Telescope |
+| `path` | `string` | `/__telescope` | Dashboard URL path |
+| `ignore` | `string[]` | `[]` | URL patterns to exclude from recording |
+| `recordBody` | `boolean` | `true` | Record request/response bodies |
+| `maxEntries` | `number` | `1000` | Maximum entries per type to keep |
+| `websocket` | `boolean` | `true` | Enable real-time WebSocket updates |
+
+**Logger Integration:**
+
+Telescope automatically captures logs when using `gkm dev`. To manually integrate with your logger:
+
+```typescript
+// Pino Transport
+import pino from 'pino';
+import { createPinoDestination } from '@geekmidas/telescope/logger/pino';
+
+const logger = pino(
+  { level: 'debug' },
+  pino.multistream([
+    { stream: process.stdout },
+    { stream: createPinoDestination({ telescope }) }
+  ])
+);
+
+// ConsoleLogger wrapper
+import { createTelescopeLogger } from '@geekmidas/telescope/logger/console';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+
+const logger = createTelescopeLogger(telescope, new ConsoleLogger());
+```
+
+See the [@geekmidas/telescope documentation](../telescope/README.md) for more details.
+
 ## Providers
 
 ### AWS API Gateway v1
@@ -366,95 +569,193 @@ The CLI generates files in the `.gkm/<provider>` directory:
 ├── aws-apigatewayv1/
 │   ├── getUsers.ts          # Individual Lambda handler
 │   ├── createUser.ts        # Individual Lambda handler
-│   └── manifest.json        # Build manifest
 ├── server/
 │   ├── app.ts               # Server application
-│   └── manifest.json        # Build manifest
+│   ├── endpoints.ts         # Endpoint exports
+├── manifest/
+│   ├── aws.ts               # AWS manifest with types
+│   └── server.ts            # Server manifest with types
 └── openapi.json             # OpenAPI specification
 ```
 
 ### Build Manifest
 
-Each provider generates a `manifest.json` file with build information:
+The CLI generates TypeScript manifests with full type information in the `.gkm/manifest/` directory. These manifests export both the data and derived types for type-safe usage.
 
-```json
-{
-  "routes": [
+#### AWS Manifest (`.gkm/manifest/aws.ts`)
+
+```typescript
+export const manifest = {
+  routes: [
     {
-      "path": "/users",
-      "method": "GET",
-      "handler": ".gkm/aws-apigatewayv1/getUsers.handler"
+      path: '/users',
+      method: 'GET',
+      handler: '.gkm/aws-apigatewayv1/getUsers.handler',
+      authorizer: 'jwt',
     },
     {
-      "path": "/users",
-      "method": "POST",
-      "handler": ".gkm/aws-apigatewayv1/createUser.handler"
-    }
+      path: '/users',
+      method: 'POST',
+      handler: '.gkm/aws-apigatewayv1/createUser.handler',
+      authorizer: 'jwt',
+    },
   ],
-  "functions": [
+  functions: [
     {
-      "name": "processData",
-      "handler": ".gkm/aws-lambda/functions/processData.handler",
-      "timeout": 60,
-      "memorySize": 256
-    }
+      name: 'processData',
+      handler: '.gkm/aws-lambda/functions/processData.handler',
+      timeout: 60,
+      memorySize: 256,
+    },
   ],
-  "crons": [
+  crons: [
     {
-      "name": "dailyCleanup",
-      "handler": ".gkm/aws-lambda/crons/dailyCleanup.handler",
-      "schedule": "rate(1 day)",
-      "timeout": 300,
-      "memorySize": 512
-    }
-  ]
+      name: 'dailyCleanup',
+      handler: '.gkm/aws-lambda/crons/dailyCleanup.handler',
+      schedule: 'rate(1 day)',
+      timeout: 300,
+      memorySize: 512,
+    },
+  ],
+  subscribers: [],
+} as const;
+
+// Derived types
+export type Route = (typeof manifest.routes)[number];
+export type Function = (typeof manifest.functions)[number];
+export type Cron = (typeof manifest.crons)[number];
+export type Subscriber = (typeof manifest.subscribers)[number];
+
+// Useful union types
+export type Authorizer = Route['authorizer'];
+export type HttpMethod = Route['method'];
+export type RoutePath = Route['path'];
+```
+
+#### Server Manifest (`.gkm/manifest/server.ts`)
+
+```typescript
+export const manifest = {
+  app: {
+    handler: '.gkm/server/app.ts',
+    endpoints: '.gkm/server/endpoints.ts',
+  },
+  routes: [
+    { path: '/users', method: 'GET', authorizer: 'jwt' },
+    { path: '/users', method: 'POST', authorizer: 'jwt' },
+  ],
+  subscribers: [
+    { name: 'orderHandler', subscribedEvents: ['order.created'] },
+  ],
+} as const;
+
+// Derived types
+export type Route = (typeof manifest.routes)[number];
+export type Subscriber = (typeof manifest.subscribers)[number];
+
+// Useful union types
+export type Authorizer = Route['authorizer'];
+export type HttpMethod = Route['method'];
+export type RoutePath = Route['path'];
+```
+
+#### Using Manifest Types
+
+Import the manifest types for type-safe infrastructure configuration:
+
+```typescript
+import { manifest, type Route, type Authorizer } from './.gkm/manifest/aws';
+
+// Type-safe route iteration
+for (const route of manifest.routes) {
+  console.log(`${route.method} ${route.path} -> ${route.handler}`);
+}
+
+// Use union types for validation
+function isValidMethod(method: string): method is HttpMethod {
+  return manifest.routes.some((r) => r.method === method);
 }
+
+// Access authorizer names
+const authorizers = new Set(manifest.routes.map((r) => r.authorizer));
 ```
 
 ## OpenAPI Generation
 
-The CLI automatically generates OpenAPI 3.0 specifications from your endpoints:
+The CLI generates a TypeScript module with full type safety and a ready-to-use API client:
 
 ```bash
-gkm openapi --output api-docs.json
+gkm openapi --output src/api.ts
 ```
 
-**Generated OpenAPI:**
-```json
-{
-  "openapi": "3.0.0",
-  "info": {
-    "title": "API Documentation",
-    "version": "1.0.0",
-    "description": "Auto-generated API documentation from endpoints"
+**Generated TypeScript Module:**
+
+The generated module exports:
+
+| Export | Description |
+|--------|-------------|
+| `securitySchemes` | OpenAPI security scheme definitions |
+| `SecuritySchemeId` | Union type of security scheme names |
+| `endpointAuth` | Map of endpoints to their auth requirements |
+| `paths` | TypeScript interface for OpenAPI paths |
+| `createApi()` | Factory function to create typed API client |
+
+**Example Generated Output:**
+
+```typescript
+// Security schemes from your endpoint authorizers
+export const securitySchemes = {
+  jwt: {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
   },
-  "paths": {
-    "/users": {
-      "get": {
-        "summary": "Get Users",
-        "responses": {
-          "200": {
-            "description": "Success",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "id": { "type": "string" },
-                      "name": { "type": "string" }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
+} as const;
+
+export type SecuritySchemeId = 'jwt';
+
+// Which endpoints require which auth
+export const endpointAuth = {
+  'GET /users': 'jwt',
+  'POST /users': 'jwt',
+  'GET /health': null,  // Public endpoint
+} as const;
+
+// Type-safe paths interface
+export interface paths {
+  '/users': {
+    get: {
+      responses: {
+        200: { content: { 'application/json': GetUsersOutput[] } };
+      };
+    };
+    post: {
+      requestBody: { content: { 'application/json': CreateUserInput } };
+      responses: {
+        201: { content: { 'application/json': GetUsersOutput } };
+      };
+    };
+  };
 }
+
+// Factory to create API client
+export interface CreateApiOptions {
+  baseURL: string;
+  authStrategies: Record<SecuritySchemeId, AuthStrategy>;
+  queryClient?: QueryClient;
+}
+
+export function createApi(options: CreateApiOptions) {
+  // Returns callable fetcher with React Query hooks
+}
+```
+
+### Legacy JSON Output
+
+For compatibility with other tools, you can still generate JSON:
+
+```bash
+gkm openapi --output api-docs.json --json
 ```
 
 ## Deployment Examples
@@ -556,6 +857,97 @@ export const envParser = new EnvironmentParser(process.env)
   .parse();
 ```
 
+### Authentication Integration
+
+Integrate `@geekmidas/auth` for JWT/OIDC authentication in your endpoints:
+
+```typescript
+// src/env.ts
+import { EnvironmentParser } from '@geekmidas/envkit';
+
+export const envParser = new EnvironmentParser(process.env)
+  .create((get) => ({
+    auth: {
+      jwtSecret: get('JWT_SECRET').string(),
+      jwtIssuer: get('JWT_ISSUER').string().optional(),
+      jwtAudience: get('JWT_AUDIENCE').string().optional(),
+    },
+  }))
+  .parse();
+```
+
+#### With Hono Middleware (Server Provider)
+
+```typescript
+// src/routes/protected.ts
+import { e } from '@geekmidas/constructs/endpoints';
+import { JwtMiddleware } from '@geekmidas/auth/hono/jwt';
+import { envParser } from '../env.js';
+
+const jwt = new JwtMiddleware({
+  config: {
+    secret: envParser.auth.jwtSecret,
+    issuer: envParser.auth.jwtIssuer,
+    audience: envParser.auth.jwtAudience,
+  },
+});
+
+// Apply middleware to Hono app
+app.use('/api/*', jwt.handler());
+app.use('/public/*', jwt.optional());
+```
+
+#### With Lambda Authorizers (AWS Provider)
+
+```typescript
+// src/authorizers/jwt.ts
+import { JwtAuthorizer } from '@geekmidas/auth/lambda/jwt';
+import { envParser } from '../env.js';
+
+const authorizer = new JwtAuthorizer({
+  config: {
+    secret: envParser.auth.jwtSecret,
+    issuer: envParser.auth.jwtIssuer,
+  },
+  getContext: (claims) => ({
+    userId: claims.sub!,
+  }),
+});
+
+export const handler = authorizer.requestHandler();
+```
+
+#### With OIDC (Auth0, Cognito, etc.)
+
+```typescript
+// src/env.ts
+export const envParser = new EnvironmentParser(process.env)
+  .create((get) => ({
+    oidc: {
+      issuer: get('OIDC_ISSUER').string().url(),
+      audience: get('OIDC_AUDIENCE').string(),
+    },
+  }))
+  .parse();
+
+// src/authorizers/oidc.ts
+import { OidcAuthorizer } from '@geekmidas/auth/lambda/oidc';
+import { envParser } from '../env.js';
+
+const authorizer = new OidcAuthorizer({
+  config: {
+    issuer: envParser.oidc.issuer,
+    audience: envParser.oidc.audience,
+  },
+  getContext: (claims) => ({
+    userId: claims.sub!,
+    email: claims.email,
+  }),
+});
+
+export const handler = authorizer.requestHandler();
+```
+
 ### Custom Logger Configuration
 
 Set up structured logging with different levels:
@@ -635,11 +1027,12 @@ Error: OpenAPI generation failed: Invalid endpoint schema
 ```json
 {
   "scripts": {
+    "dev": "gkm dev",
+    "dev:port": "gkm dev --port 8080",
     "build": "gkm build",
     "build:lambda": "gkm build --provider aws-apigatewayv1",
     "build:server": "gkm build --provider server",
-    "docs": "gkm openapi --output docs/api.json",
-    "dev": "npm run build:server && node server.js"
+    "docs": "gkm openapi --output src/api.ts"
   }
 }
 ```
@@ -734,11 +1127,29 @@ DEBUG=gkm:* npx gkm build
 // Provider options
 type Provider = 'server' | 'aws-apigatewayv1' | 'aws-apigatewayv2';
 
+// Runtime options
+type Runtime = 'node' | 'bun';
+
 // Configuration interface
 interface GkmConfig {
   routes: string | string[];
   envParser: string;
   logger: string;
+  functions?: string | string[];
+  crons?: string | string[];
+  subscribers?: string | string[];
+  runtime?: Runtime;
+  telescope?: boolean | TelescopeConfig;
+}
+
+// Telescope configuration
+interface TelescopeConfig {
+  enabled?: boolean;
+  path?: string;
+  ignore?: string[];
+  recordBody?: boolean;
+  maxEntries?: number;
+  websocket?: boolean;
 }
 
 // Build options
@@ -746,6 +1157,12 @@ interface BuildOptions {
   provider: Provider;
 }
 
+// Dev options
+interface DevOptions {
+  port?: number;
+  enableOpenApi?: boolean;
+}
+
 // Route information
 interface RouteInfo {
   path: string;