@geekmidas/cli 2.0.2 → 10.0.0-alpha.0

package/docs/OPENAPI_TYPESCRIPT_DESIGN.md

@@ -1,408 +0,0 @@
-# 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/docs/dev-server-resilience-design.md

@@ -1,189 +0,0 @@
-# Dev Server Resilience Design
-
-Status: parked / not yet started
-Owner: TBD
-Scope: `packages/cli/src/dev/index.ts`, `packages/cli/src/generators/Generator.ts`
-
-## Background
-
-Running `gkm dev` against a real workspace (e.g. `rezgo`: api, auth, web, app/Expo)
-exposes three classes of failure. None are caused by user code; they are
-limitations of the current dev orchestrator and hot-reload implementation.
-
-## Issue 1 — Hot reload misses new files and serves stale transitive modules
-
-### Symptoms
-
-- Adding a new route file does not trigger a rebuild.
-- After adding a new export to a non-route file, route files that import it
-  fail with:
-  `SyntaxError: The requested module '~/.../foo.ts' does not provide an export named 'bar'`
-- Some changes "just don't get picked up" until the dev server is restarted.
-
-### Root causes
-
-1. **`add`/`unlink` events are ignored.** The chokidar watcher in `dev/index.ts`
-   only listens for `change`:
-   ```ts
-   watcher.on('change', async (path) => { ... });
-   ```
-   New or deleted files never trigger a rebuild.
-
-2. **Cache-bust is shallow.** `Generator.ts:load()` appends `?t=<now>` only to
-   the top-level globbed route file URL. Node's ESM cache is keyed by URL, so
-   any *transitive* import (services, domain modules, env, etc.) is served from
-   cache forever within the CLI process. When a transitive module is edited,
-   the route file is re-evaluated against the stale cached version → the
-   "does not provide an export named" error above.
-
-3. **Watch patterns are too narrow.** Only `routes`, `functions`, `crons`,
-   `subscribers` (plus envParser / logger / hooks files) are watched. Edits to
-   `src/domain/**`, `src/services/**`, etc. don't fire any rebuild even though
-   those files are pulled in transitively at openapi/build time.
-
-### Proposed fix
-
-- Subscribe to `add` and `unlink` on the watcher and re-resolve the glob set
-  before rebuilding.
-- Broaden the watch pattern to cover the app's `src/**/*.{ts,tsx}` (configurable),
-  not just construct entry directories.
-- Bust transitive caches. Two viable approaches:
-  - **Worker thread per rebuild** (preferred): move `EndpointGenerator.load` /
-    `FunctionGenerator.load` / etc. into a short-lived `worker_threads` worker
-    that gets recreated on each rebuild. Each worker has a fresh module graph,
-    so transitive imports are guaranteed fresh. Cost is one worker spawn per
-    rebuild (~50-100ms), but avoids the unbounded-memory leak of accumulating
-    `?t=N` URLs in the main process.
-  - **Custom loader hook**: install a Node loader that rewrites every resolved
-    URL to include the current rebuild generation. Cheaper per rebuild but
-    fragile (loader compatibility with tsx, source maps, etc.).
-
-Worker thread is the recommended path.
-
-## Issue 2 — Ctrl+C orphans `tsx`/`node` processes
-
-### Symptoms
-
-After pressing Ctrl+C in a workspace `gkm dev`, the shell returns but
-`tsx` and `node` processes remain alive. Workaround is `killall node`.
-
-### Process chain in workspace mode
-
-```
-shell
-  └── gkm dev (top-level, workspace)
-        └── pnpm turbo run dev          [spawned with detached: true]
-              ├── @rezgo/api: gkm dev   (per-app)
-              │     └── tsx              [spawned with detached: true]
-              │           └── node       (Hono server)
-              ├── @rezgo/auth: ...
-              └── @rezgo/app: ...
-```
-
-### Root cause
-
-The per-app `gkm dev` spawns `tsx` with `detached: true`
-(`dev/index.ts:1521`). That moves tsx into a *new process group* outside the
-turbo subtree. The workspace shutdown handler only sends SIGTERM/SIGKILL to
-turbo's pgid; tsx's pgid is never targeted. After SIGKILL hits turbo's group,
-the per-app gkm processes die *before* their async shutdown finishes calling
-`process.kill(-tsxPgid, 'SIGKILL')`. tsx and its node child are orphaned.
-
-The `detached: true` flag exists because the user's running Hono server may
-ignore SIGTERM, so we need to kill its whole group. The design conflict is:
-detaching tsx is necessary to forcibly kill it, but it also escapes the
-top-level reachability tree.
-
-### Proposed fix
-
-Track every tsx PID centrally:
-
-- Each `DevServer` registers its `tsx` pid into a shared `Set<number>` at the
-  workspace level (or writes to a state file under `.gkm/`).
-- Workspace shutdown iterates that set and issues `process.kill(-pid, 'SIGKILL')`
-  for each known tsx pgid *before* falling back to the turbo-pgid SIGKILL.
-- As belt-and-suspenders, drain the registry on per-app `gkm dev` exit so dead
-  pids are not retargeted.
-
-This makes the kill reachable regardless of process-group escape.
-
-## Issue 3 — One app's crash brings down the whole workspace
-
-### Symptoms
-
-`@rezgo/app` (Expo) crashed with a Metro `DependencyGraph._onHasteChange`
-TypeError. Within seconds, `@rezgo/api`, `@rezgo/auth`, `@rezgo/web` all
-received SIGTERM and shut down. The user lost 21 minutes of warmed dev state.
-
-### Root causes
-
-1. **Turbo's persistent-task semantics.** When a persistent task in
-   `turbo run dev` exits non-zero, turbo cancels sibling persistent tasks. There
-   is no flag (as of turbo 2.x) that keeps survivors running through a sibling
-   crash. `--continue` only affects scheduling of *queued* tasks, not running
-   persistent ones.
-2. **gkm's orchestrator treats turbo's non-zero exit as fatal.** In
-   `workspaceDevCommand`:
-   ```ts
-   turboProcess.on('exit', (code) => {
-     if (code !== null && code !== 0) {
-       reject(new Error(`Turbo exited with code ${code}`));
-     }
-   });
-   ```
-   The reject fires the shutdown handler, which kills any survivors that
-   turbo hadn't already torn down.
-
-### Proposed fix
-
-Stop using `turbo run dev` for the persistent dev loop. Build an in-process
-supervisor inside `workspaceDevCommand`:
-
-- Resolve dependency order via the existing `getAppBuildOrder` (we still use
-  turbo's task graph indirectly via workspace config).
-- For each app, `spawn` its dev command directly (`pnpm dev` in that app's
-  cwd, or for backend apps invoke the per-app gkm dev codepath directly without
-  going through pnpm/turbo).
-- Supervise each child:
-  - `on('exit', code)`: log the crash, do **not** propagate, schedule a restart
-    with exponential backoff (start at 1s, cap at 30s, reset after a 60s clean
-    run).
-  - Stream stdout/stderr to the parent with an app-name prefix so output stays
-    readable.
-- Centralize the PID registry from Issue 2 here.
-- Ctrl+C handler: iterate registry, SIGKILL each child group, then exit.
-
-Turbo remains the build-time orchestrator (`gkm build`, dependency-ordered
-package builds). Only the dev persistent loop is moved off it.
-
-### Why not fix turbo's behavior instead
-
-Tried first. `--continue=dependencies-successful` and friends don't apply to
-sibling persistent tasks. Filing it upstream is fine, but the dev experience
-needs to be fixed now and the supervisor pattern is also what makes Issues 1
-and 2 solvable cleanly.
-
-## Implementation order (when unparked)
-
-1. Land the in-process supervisor (Issue 3 fix). This gives us a single owner
-   of the dev process tree.
-2. Move tsx PID registration into the supervisor (Issue 2 fix).
-3. Move hot-reload (worker thread + broadened watcher + `add`/`unlink`) into
-   the per-app branch of the supervisor (Issue 1 fix).
-
-Each step is shippable independently. Order matters: 1 unblocks the cleanest
-form of 2 and 3.
-
-## Out of scope
-
-- Replacing `tsx` (e.g. with `node --experimental-strip-types`).
-- Native Bun runtime for dev — separate decision.
-- Replacing chokidar.
-
-## Open questions
-
-- Should the supervisor expose a `--no-restart` flag for CI-like local runs?
-- Restart backoff thresholds — should they be configurable per app in
-  workspace config, or fixed?
-- Should we surface a small status line ("3 of 4 apps running") when one app
-  is dead but the rest are healthy?