@geekmidas/cli 0.3.0 → 0.4.0

package/dist/openapi-DhK4b0lB.cjs

@@ -0,0 +1,56 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const require_config = require('./config-BVIJpAsa.cjs');
+const require_EndpointGenerator = require('./EndpointGenerator-BxNCkus4.cjs');
+const require_OpenApiTsGenerator = require('./OpenApiTsGenerator-NBNEoaeO.cjs');
+const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const __geekmidas_constructs_endpoints = require_chunk.__toESM(require("@geekmidas/constructs/endpoints"));
+
+//#region src/openapi.ts
+async function openapiCommand(options = {}) {
+	const logger = console;
+	try {
+		const config = await require_config.loadConfig(options.cwd);
+		const endpointGenerator = new require_EndpointGenerator.EndpointGenerator();
+		const loadedEndpoints = await endpointGenerator.load(config.routes);
+		if (loadedEndpoints.length === 0) {
+			logger.log("No valid endpoints found");
+			return;
+		}
+		const endpoints = loadedEndpoints.map(({ construct }) => construct);
+		const isJson = options.json === true;
+		const defaultOutput = isJson ? "openapi.json" : "openapi.ts";
+		const outputPath = options.output || (0, node_path.join)(process.cwd(), defaultOutput);
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(outputPath), { recursive: true });
+		if (isJson) {
+			const spec = await __geekmidas_constructs_endpoints.Endpoint.buildOpenApiSchema(endpoints, {
+				title: "API Documentation",
+				version: "1.0.0",
+				description: "Auto-generated API documentation from endpoints"
+			});
+			await (0, node_fs_promises.writeFile)(outputPath, JSON.stringify(spec, null, 2));
+			logger.log(`OpenAPI JSON spec generated: ${outputPath}`);
+		} else {
+			const tsGenerator = new require_OpenApiTsGenerator.OpenApiTsGenerator();
+			const tsContent = await tsGenerator.generate(endpoints, {
+				title: "API Documentation",
+				version: "1.0.0",
+				description: "Auto-generated API documentation from endpoints"
+			});
+			await (0, node_fs_promises.writeFile)(outputPath, tsContent);
+			logger.log(`OpenAPI TypeScript module generated: ${outputPath}`);
+		}
+		logger.log(`Found ${endpoints.length} endpoints`);
+	} catch (error) {
+		throw new Error(`OpenAPI generation failed: ${error.message}`);
+	}
+}
+
+//#endregion
+Object.defineProperty(exports, 'openapiCommand', {
+  enumerable: true,
+  get: function () {
+    return openapiCommand;
+  }
+});
+//# sourceMappingURL=openapi-DhK4b0lB.cjs.map

package/dist/openapi-DhK4b0lB.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-DhK4b0lB.cjs","names":["options: OpenAPIOptions","EndpointGenerator","OpenApiTsGenerator"],"sources":["../src/openapi.ts"],"sourcesContent":["#!/usr/bin/env -S npx tsx\n\nimport { mkdir, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { Endpoint } from '@geekmidas/constructs/endpoints';\nimport { loadConfig } from './config.js';\nimport { EndpointGenerator } from './generators/EndpointGenerator.js';\nimport { OpenApiTsGenerator } from './generators/OpenApiTsGenerator.js';\n\ninterface OpenAPIOptions {\n  output?: string;\n  json?: boolean;\n  cwd?: string;\n}\n\nexport async function openapiCommand(\n  options: OpenAPIOptions = {},\n): Promise<void> {\n  const logger = console;\n\n  try {\n    // Load config using existing function\n    const config = await loadConfig(options.cwd);\n    const endpointGenerator = new EndpointGenerator();\n\n    // Load all endpoints using the refactored function\n    const loadedEndpoints = await endpointGenerator.load(config.routes);\n\n    if (loadedEndpoints.length === 0) {\n      logger.log('No valid endpoints found');\n      return;\n    }\n\n    // Extract just the endpoint instances for OpenAPI generation\n    const endpoints = loadedEndpoints.map(({ construct }) => construct);\n\n    // Determine output format (TypeScript is default)\n    const isJson = options.json === true;\n    const defaultOutput = isJson ? 'openapi.json' : 'openapi.ts';\n    const outputPath = options.output || join(process.cwd(), defaultOutput);\n\n    // Ensure output directory exists\n    await mkdir(dirname(outputPath), { recursive: true });\n\n    if (isJson) {\n      // Generate JSON OpenAPI spec (legacy)\n      const spec = await Endpoint.buildOpenApiSchema(endpoints, {\n        title: 'API Documentation',\n        version: '1.0.0',\n        description: 'Auto-generated API documentation from endpoints',\n      });\n\n      await writeFile(outputPath, JSON.stringify(spec, null, 2));\n      logger.log(`OpenAPI JSON spec generated: ${outputPath}`);\n    } else {\n      // Generate TypeScript OpenAPI module (default)\n      const tsGenerator = new OpenApiTsGenerator();\n      const tsContent = await tsGenerator.generate(endpoints, {\n        title: 'API Documentation',\n        version: '1.0.0',\n        description: 'Auto-generated API documentation from endpoints',\n      });\n\n      await writeFile(outputPath, tsContent);\n      logger.log(`OpenAPI TypeScript module generated: ${outputPath}`);\n    }\n\n    logger.log(`Found ${endpoints.length} endpoints`);\n  } catch (error) {\n    throw new Error(`OpenAPI generation failed: ${(error as Error).message}`);\n  }\n}\n"],"mappings":";;;;;;;;;AAeA,eAAsB,eACpBA,UAA0B,CAAE,GACb;CACf,MAAM,SAAS;AAEf,KAAI;EAEF,MAAM,SAAS,MAAM,0BAAW,QAAQ,IAAI;EAC5C,MAAM,oBAAoB,IAAIC;EAG9B,MAAM,kBAAkB,MAAM,kBAAkB,KAAK,OAAO,OAAO;AAEnE,MAAI,gBAAgB,WAAW,GAAG;AAChC,UAAO,IAAI,2BAA2B;AACtC;EACD;EAGD,MAAM,YAAY,gBAAgB,IAAI,CAAC,EAAE,WAAW,KAAK,UAAU;EAGnE,MAAM,SAAS,QAAQ,SAAS;EAChC,MAAM,gBAAgB,SAAS,iBAAiB;EAChD,MAAM,aAAa,QAAQ,UAAU,oBAAK,QAAQ,KAAK,EAAE,cAAc;AAGvE,QAAM,4BAAM,uBAAQ,WAAW,EAAE,EAAE,WAAW,KAAM,EAAC;AAErD,MAAI,QAAQ;GAEV,MAAM,OAAO,MAAM,0CAAS,mBAAmB,WAAW;IACxD,OAAO;IACP,SAAS;IACT,aAAa;GACd,EAAC;AAEF,SAAM,gCAAU,YAAY,KAAK,UAAU,MAAM,MAAM,EAAE,CAAC;AAC1D,UAAO,KAAK,+BAA+B,WAAW,EAAE;EACzD,OAAM;GAEL,MAAM,cAAc,IAAIC;GACxB,MAAM,YAAY,MAAM,YAAY,SAAS,WAAW;IACtD,OAAO;IACP,SAAS;IACT,aAAa;GACd,EAAC;AAEF,SAAM,gCAAU,YAAY,UAAU;AACtC,UAAO,KAAK,uCAAuC,WAAW,EAAE;EACjE;AAED,SAAO,KAAK,QAAQ,UAAU,OAAO,YAAY;CAClD,SAAQ,OAAO;AACd,QAAM,IAAI,OAAO,6BAA8B,MAAgB,QAAQ;CACxE;AACF"}

package/dist/openapi.cjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env -S npx tsx
-require('./config-D1EpSGk6.cjs');
+require('./config-BVIJpAsa.cjs');
 require('./Generator-CDoEXCDg.cjs');
-require('./EndpointGenerator-C73wNoih.cjs');
-const require_openapi = require('./openapi-CewcfoRH.cjs');
+require('./EndpointGenerator-BxNCkus4.cjs');
+require('./OpenApiTsGenerator-NBNEoaeO.cjs');
+const require_openapi = require('./openapi-DhK4b0lB.cjs');
 
 exports.openapiCommand = require_openapi.openapiCommand;

package/dist/openapi.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env -S npx tsx
-import "./config-U-mdW-7Y.mjs";
+import "./config-AFmFKmU0.mjs";
 import "./Generator-UanJW0_V.mjs";
-import "./EndpointGenerator-CWh18d92.mjs";
-import { openapiCommand } from "./openapi-BTHbPrxS.mjs";
+import "./EndpointGenerator-CzDhG7Or.mjs";
+import "./OpenApiTsGenerator-q3aWNkuM.mjs";
+import { openapiCommand } from "./openapi-DRTRGhTt.mjs";
 
 export { openapiCommand };

package/docs/OPENAPI_TYPESCRIPT_DESIGN.md

@@ -0,0 +1,408 @@
+# OpenAPI TypeScript Generation - Design Document
+
+## Overview
+
+This document describes the design for generating TypeScript OpenAPI specifications with integrated authentication support. The feature extends `gkm openapi` with a `--ts` flag that outputs a TypeScript module instead of JSON, enabling:
+
+1. **Type-safe paths** - Full TypeScript interface for API routes
+2. **Runtime auth map** - Per-endpoint authentication requirements
+3. **Reusable schemas** - TypeScript interfaces extracted from Zod/Valibot schemas
+4. **Security scheme definitions** - OpenAPI security schemes as typed constants
+
+## Motivation
+
+### Current Flow (JSON-based)
+
+```
+Endpoints → gkm openapi → openapi.json → openapi-typescript → types.d.ts
+                                      ↓
+                          (no auth info at runtime)
+```
+
+**Problems:**
+- Auth requirements lost at runtime - OpenAPI security info exists but isn't usable by the fetcher
+- Two-step generation - need external tool (`openapi-typescript`) for types
+- No schema reuse - generated types are isolated, can't reference shared interfaces
+
+### Proposed Flow (TypeScript-native)
+
+```
+Endpoints → gkm openapi --ts → openapi.ts
+                                   ↓
+                          Exports:
+                          ├── paths (type)
+                          ├── endpointAuth (runtime map)
+                          ├── securitySchemes (runtime definitions)
+                          └── schema interfaces (reusable types)
+```
+
+## Command Interface
+
+```bash
+# Default: generates TypeScript
+gkm openapi --output ./src/api/openapi.ts
+
+# Explicit JSON output (legacy)
+gkm openapi --json --output ./openapi.json
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Generate JSON instead of TypeScript (legacy) | `false` |
+| `--output` | Output file path | `openapi.ts` |
+
+## Generated Output Structure
+
+### File: `openapi.ts`
+
+```typescript
+// Auto-generated by @geekmidas/cli - DO NOT EDIT
+import type { OpenAPIV3_1 } from 'openapi-types';
+
+// ============================================================
+// Security Schemes
+// ============================================================
+
+/**
+ * Available security schemes for this API.
+ * Maps authorizer names to OpenAPI security scheme definitions.
+ */
+export const securitySchemes = {
+  bearer: {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+  },
+  iam: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'Authorization',
+    'x-amazon-apigateway-authtype': 'awsSigv4',
+  },
+  apiKey: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-API-Key',
+  },
+} as const satisfies Record<string, OpenAPIV3_1.SecuritySchemeObject>;
+
+export type SecuritySchemeId = keyof typeof securitySchemes;
+
+// ============================================================
+// Endpoint Authentication Map
+// ============================================================
+
+/**
+ * Runtime map of endpoints to their required authentication scheme.
+ * `null` indicates a public endpoint (no auth required).
+ */
+export const endpointAuth = {
+  'POST /tenants': 'iam',
+  'GET /tenants/{id}': 'bearer',
+  'PUT /tenants/{id}': 'bearer',
+  'DELETE /tenants/{id}': 'bearer',
+  'GET /health': null,
+  'GET /docs': null,
+} as const satisfies Record<string, SecuritySchemeId | null>;
+
+export type AuthenticatedEndpoint = {
+  [K in keyof typeof endpointAuth]: typeof endpointAuth[K] extends null ? never : K;
+}[keyof typeof endpointAuth];
+
+export type PublicEndpoint = {
+  [K in keyof typeof endpointAuth]: typeof endpointAuth[K] extends null ? K : never;
+}[keyof typeof endpointAuth];
+
+// ============================================================
+// Schema Definitions (Reusable Types)
+// ============================================================
+
+export interface Tenant {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateTenantInput {
+  name: string;
+}
+
+export interface UpdateTenantInput {
+  name?: string;
+}
+
+// ============================================================
+// OpenAPI Paths
+// ============================================================
+
+export interface paths {
+  '/tenants': {
+    post: {
+      requestBody: {
+        content: {
+          'application/json': CreateTenantInput;
+        };
+      };
+      responses: {
+        201: {
+          content: {
+            'application/json': Tenant;
+          };
+        };
+      };
+    };
+  };
+  '/tenants/{id}': {
+    parameters: {
+      path: {
+        id: string;
+      };
+    };
+    get: {
+      responses: {
+        200: {
+          content: {
+            'application/json': Tenant;
+          };
+        };
+      };
+    };
+    put: {
+      requestBody: {
+        content: {
+          'application/json': UpdateTenantInput;
+        };
+      };
+      responses: {
+        200: {
+          content: {
+            'application/json': Tenant;
+          };
+        };
+      };
+    };
+    delete: {
+      responses: {
+        204: {
+          content: never;
+        };
+      };
+    };
+  };
+  '/health': {
+    get: {
+      responses: {
+        200: {
+          content: {
+            'application/json': { status: string };
+          };
+        };
+      };
+    };
+  };
+}
+
+// ============================================================
+// Full OpenAPI Specification (Optional)
+// ============================================================
+
+export const spec = {
+  openapi: '3.1.0',
+  info: {
+    title: 'Tenant API',
+    version: '1.0.0',
+  },
+  paths: { /* ... */ },
+  components: {
+    securitySchemes,
+    schemas: { /* ... */ },
+  },
+} as const satisfies OpenAPIV3_1.Document;
+```
+
+## Implementation Details
+
+### 1. Authorizer to Security Scheme Mapping
+
+The `Authorizer.type` field maps to OpenAPI security schemes:
+
+| Authorizer Type | OpenAPI Security Scheme |
+|-----------------|------------------------|
+| `jwt`, `bearer` | `{ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }` |
+| `iam`, `aws-sigv4` | `{ type: 'apiKey', in: 'header', name: 'Authorization', 'x-amazon-apigateway-authtype': 'awsSigv4' }` |
+| `apiKey` | `{ type: 'apiKey', in: metadata.in, name: metadata.name }` |
+| `oauth2` | `{ type: 'oauth2', flows: { ... } }` |
+| `oidc` | `{ type: 'openIdConnect', openIdConnectUrl: metadata.issuer }` |
+| `none` / undefined | `null` (public endpoint) |
+
+### 2. Schema Extraction
+
+Schemas are extracted from StandardSchema (Zod/Valibot) definitions:
+
+```typescript
+// From endpoint definition
+const endpoint = e
+  .post('/tenants')
+  .body(z.object({ name: z.string() }))
+  .output(z.object({ id: z.string(), name: z.string() }))
+  .handle(async ({ body }) => { ... });
+
+// Extracted as
+export interface CreateTenantInput {
+  name: string;
+}
+
+export interface CreateTenantOutput {
+  id: string;
+  name: string;
+}
+```
+
+### 3. Naming Strategy
+
+| Schema Location | Generated Name |
+|-----------------|----------------|
+| Body schema | `{OperationId}Input` or `{Method}{Route}Input` |
+| Output schema | `{OperationId}Output` or `{Method}{Route}Output` |
+| Params schema | `{OperationId}Params` |
+| Query schema | `{OperationId}Query` |
+
+### 4. Component Collector Enhancement
+
+```typescript
+// packages/schema/src/openapi.ts
+export interface ComponentCollector {
+  schemas: Record<string, OpenAPIV3_1.SchemaObject>;
+  securitySchemes: Record<string, OpenAPIV3_1.SecuritySchemeObject>;
+  addSchema(id: string, schema: OpenAPIV3_1.SchemaObject): void;
+  addSecurityScheme(id: string, scheme: OpenAPIV3_1.SecuritySchemeObject): void;
+  getReference(id: string): OpenAPIV3_1.ReferenceObject;
+}
+```
+
+## Integration with Auth-Aware Fetcher
+
+The generated `endpointAuth` map enables automatic auth handling:
+
+```typescript
+// packages/client/src/auth-fetcher.ts
+import { endpointAuth, securitySchemes, type paths } from './openapi';
+import { TokenClient } from '@geekmidas/auth/client';
+
+export function createAuthAwareFetcher<Paths>(options: AuthFetcherOptions) {
+  const { tokenClient, awsSigner, apiKeyProvider } = options;
+
+  return async <T extends TypedEndpoint<Paths>>(
+    endpoint: T,
+    config?: FilteredRequestConfig<Paths, T>,
+  ) => {
+    const authScheme = endpointAuth[endpoint as keyof typeof endpointAuth];
+    let headers: Record<string, string> = {};
+
+    if (authScheme) {
+      const scheme = securitySchemes[authScheme];
+
+      switch (scheme.type) {
+        case 'http':
+          if (scheme.scheme === 'bearer') {
+            headers = await tokenClient.createValidAuthHeaders();
+          }
+          break;
+        case 'apiKey':
+          if (scheme['x-amazon-apigateway-authtype'] === 'awsSigv4') {
+            headers = await awsSigner.sign(endpoint, config);
+          } else {
+            headers[scheme.name] = await apiKeyProvider.getKey();
+          }
+          break;
+      }
+    }
+
+    return baseFetcher.request(endpoint, {
+      ...config,
+      headers: { ...headers, ...config?.headers },
+    });
+  };
+}
+```
+
+## File Structure Changes
+
+```
+packages/
+├── cli/
+│   └── src/
+│       ├── openapi.ts              # Updated: add --ts support
+│       └── generators/
+│           └── OpenApiTsGenerator.ts  # New: TypeScript generation
+├── schema/
+│   └── src/
+│       └── openapi.ts              # Updated: security scheme support
+└── client/
+    └── src/
+        └── auth-fetcher.ts         # New: auth-aware fetcher
+```
+
+## Migration Path
+
+### Breaking Change
+
+TypeScript is now the default output format. Existing JSON users must add `--json` flag.
+
+### Existing JSON Users
+
+```bash
+# Before
+gkm openapi --output ./openapi.json
+
+# After (explicit JSON)
+gkm openapi --json --output ./openapi.json
+```
+
+### Adopting TypeScript Output (New Default)
+
+1. Run `gkm openapi --output ./src/api/openapi.ts`
+2. Update imports from `./openapi-types` to `./openapi`
+3. Use `createAuthAwareFetcher` instead of `createTypedFetcher`
+
+## Testing Strategy
+
+1. **Unit Tests**
+   - Authorizer → security scheme mapping
+   - Schema extraction from StandardSchema
+   - TypeScript code generation
+
+2. **Integration Tests**
+   - Full endpoint → TypeScript output pipeline
+   - Generated code compiles without errors
+   - Auth map matches endpoint authorizers
+
+3. **E2E Tests**
+   - Auth-aware fetcher selects correct auth per endpoint
+   - Bearer endpoints get JWT headers
+   - IAM endpoints get SigV4 signatures
+   - Public endpoints get no auth headers
+
+## Open Questions
+
+1. **Schema naming conflicts** - What if two endpoints have the same operationId?
+   - Proposal: Append route hash suffix if conflict detected
+
+2. **Circular schema references** - How to handle `User { friends: User[] }`?
+   - Proposal: Use TypeScript `interface` declarations which support self-reference
+
+3. **Optional vs required auth** - Some endpoints allow optional auth (return more data if authenticated)
+   - Proposal: Add `optional` auth type: `'bearer' | 'bearer?' | null`
+
+## Timeline
+
+| Phase | Description | Estimate |
+|-------|-------------|----------|
+| 1 | Schema package updates (ComponentCollector) | - |
+| 2 | CLI TypeScript generator | - |
+| 3 | Client auth-aware fetcher | - |
+| 4 | Documentation and examples | - |
+| 5 | Testing and refinement | - |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@geekmidas/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
+  "description": "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,11 +45,17 @@
     "@geekmidas/testkit": "0.0.17"
   },
   "peerDependencies": {
-    "@geekmidas/constructs": "~0.0.22",
-    "@geekmidas/envkit": "~0.0.8",
+    "@geekmidas/constructs": "~0.1.0",
+    "@geekmidas/envkit": "~0.1.0",
     "@geekmidas/logger": "~0.0.1",
+    "@geekmidas/telescope": "~0.0.1",
     "@geekmidas/schema": "~0.0.2"
   },
+  "peerDependenciesMeta": {
+    "@geekmidas/telescope": {
+      "optional": true
+    }
+  },
   "scripts": {
     "ts": "tsc --noEmit --skipLibCheck src/**/*.ts",
     "test": "vitest",