@geekmidas/cli 1.10.35 → 1.10.37

package/docs/dev-server-resilience-design.md

@@ -0,0 +1,189 @@
+# 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?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cli",
-  "version": "1.10.35",
+  "version": "1.10.37",
   "description": "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs",
   "private": false,
   "type": "module",
@@ -56,11 +56,11 @@
     "prompts": "~2.4.2",
     "tsx": "~4.20.3",
     "yaml": "~2.8.2",
-    "@geekmidas/constructs": "~3.0.9",
-    "@geekmidas/envkit": "~1.0.5",
+    "@geekmidas/constructs": "~3.0.10",
+    "@geekmidas/envkit": "~1.0.6",
     "@geekmidas/errors": "~1.0.0",
     "@geekmidas/logger": "~1.0.1",
-    "@geekmidas/schema": "~1.0.0"
+    "@geekmidas/schema": "~1.0.1"
   },
   "devDependencies": {
     "@types/lodash.kebabcase": "^4.1.9",

package/src/__tests__/openapi.spec.ts

@@ -2,12 +2,6 @@ import { existsSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import {
-	generateOpenApi,
-	OPENAPI_OUTPUT_PATH,
-	openapiCommand,
-	resolveOpenApiConfig,
-} from '../openapi';
 import type { GkmConfig } from '../types';
 import {
 	cleanupDir,
@@ -16,6 +10,33 @@ import {
 	createTestFile,
 } from './test-helpers';
 
+const spawnCalls: Array<{ cmd: string; args: string[]; cwd: string }> = [];
+let mockSpawnExitCode = 0;
+
+vi.mock('node:child_process', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('node:child_process')>();
+	return {
+		...actual,
+		spawn: vi.fn((cmd: string, args: string[], opts: any) => {
+			spawnCalls.push({ cmd, args: args ?? [], cwd: opts?.cwd ?? '' });
+			const child: any = {
+				on(event: string, cb: (code?: number) => void) {
+					if (event === 'close') queueMicrotask(() => cb(mockSpawnExitCode));
+					return child;
+				},
+			};
+			return child;
+		}),
+	};
+});
+
+const {
+	generateOpenApi,
+	OPENAPI_OUTPUT_PATH,
+	openapiCommand,
+	resolveOpenApiConfig,
+} = await import('../openapi');
+
 describe('resolveOpenApiConfig', () => {
 	const baseConfig: GkmConfig = {
 		routes: './src/endpoints/**/*.ts',
@@ -483,7 +504,7 @@ describe('openapiCommand - workspace mode', () => {
 		vi.restoreAllMocks();
 	});
 
-	it('should generate OpenAPI for backend app in workspace', async () => {
+	it('should generate OpenAPI for a single app via --app flag', async () => {
 		// Create workspace structure
 		const apiDir = join(tempDir, 'apps/api');
 		await mkdir(apiDir, { recursive: true });
@@ -515,10 +536,11 @@ describe('openapiCommand - workspace mode', () => {
 			}),
 		);
 
-		process.chdir(tempDir);
+		// Subprocess invocation simulated: CWD = appPath, --app passed
+		process.chdir(apiDir);
 		const consoleSpy = vi.spyOn(console, 'log');
 
-		await openapiCommand({ cwd: tempDir });
+		await openapiCommand({ cwd: tempDir, app: 'api' });
 
 		// Should generate OpenAPI in the backend app's .gkm folder
 		const outputPath = join(apiDir, OPENAPI_OUTPUT_PATH);
@@ -532,4 +554,72 @@ describe('openapiCommand - workspace mode', () => {
 			expect.stringContaining('[api] Generated OpenAPI'),
 		);
 	});
+
+	it('should throw when --app references unknown app', async () => {
+		await createTestFile(
+			tempDir,
+			'gkm.config.json',
+			JSON.stringify({
+				name: 'test-workspace',
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/endpoints/**/*.ts',
+						openapi: { enabled: true },
+					},
+				},
+			}),
+		);
+
+		await expect(
+			openapiCommand({ cwd: tempDir, app: 'missing' }),
+		).rejects.toThrow(/App "missing" not found/);
+	});
+
+	it('should spawn one subprocess per backend app in multi-app mode', async () => {
+		// Create workspace with two backend apps
+		const apiDir = join(tempDir, 'apps/api');
+		const adminDir = join(tempDir, 'apps/admin');
+		await mkdir(apiDir, { recursive: true });
+		await mkdir(adminDir, { recursive: true });
+
+		await createTestFile(
+			tempDir,
+			'gkm.config.json',
+			JSON.stringify({
+				name: 'test-workspace',
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/endpoints/**/*.ts',
+						openapi: { enabled: true },
+					},
+					admin: {
+						type: 'backend',
+						path: 'apps/admin',
+						port: 3001,
+						routes: './src/endpoints/**/*.ts',
+						openapi: { enabled: true },
+					},
+				},
+			}),
+		);
+
+		spawnCalls.length = 0;
+		mockSpawnExitCode = 0;
+
+		await openapiCommand({ cwd: tempDir });
+
+		expect(spawnCalls).toHaveLength(2);
+		expect(spawnCalls[0]?.cwd).toBe(apiDir);
+		expect(spawnCalls[0]?.args).toContain('--app');
+		expect(spawnCalls[0]?.args).toContain('api');
+		expect(spawnCalls[1]?.cwd).toBe(adminDir);
+		expect(spawnCalls[1]?.args).toContain('--app');
+		expect(spawnCalls[1]?.args).toContain('admin');
+	});
 });

package/src/build/__tests__/workspace-build.spec.ts

@@ -103,13 +103,13 @@ describe('Workspace Build Command', () => {
 		it('should have correct structure for failed build', () => {
 			const result: AppBuildResult = {
 				appName: 'web',
-				type: 'frontend',
+				type: 'web',
 				success: false,
 				error: 'Build failed',
 			};
 
 			expect(result.appName).toBe('web');
-			expect(result.type).toBe('frontend');
+			expect(result.type).toBe('web');
 			expect(result.success).toBe(false);
 			expect(result.error).toBe('Build failed');
 			expect(result.outputPath).toBeUndefined();
@@ -137,14 +137,14 @@ describe('Workspace Build Command', () => {
 						routes: './src/**/*.ts',
 					},
 					web: {
-						type: 'frontend',
+						type: 'web',
 						path: 'apps/web',
 						port: 3002,
 						dependencies: ['api', 'auth'],
 						framework: 'nextjs',
 					},
 					admin: {
-						type: 'frontend',
+						type: 'web',
 						path: 'apps/admin',
 						port: 3003,
 						dependencies: ['api'],
@@ -159,7 +159,7 @@ describe('Workspace Build Command', () => {
 
 			const apps = Object.entries(workspace.apps);
 			const backendApps = apps.filter(([, app]) => app.type === 'backend');
-			const frontendApps = apps.filter(([, app]) => app.type === 'frontend');
+			const frontendApps = apps.filter(([, app]) => app.type === 'web');
 
 			expect(backendApps).toHaveLength(2);
 			expect(frontendApps).toHaveLength(2);
@@ -181,7 +181,7 @@ describe('Workspace Build Command', () => {
 						dependencies: [],
 					},
 					web: {
-						type: 'frontend',
+						type: 'web',
 						path: 'apps/web',
 						port: 3001,
 						dependencies: [],
@@ -207,7 +207,7 @@ describe('Workspace Build Command', () => {
 			const frontendOutputPath = join(
 				workspace.root,
 				frontendApp.path,
-				frontendApp.type === 'frontend' ? '.next' : '.gkm',
+				frontendApp.type === 'web' ? '.next' : '.gkm',
 			);
 			expect(frontendOutputPath).toBe('/workspace/apps/web/.next');
 		});

package/src/build/index.ts

@@ -362,7 +362,7 @@ async function buildForProvider(
  */
 export interface AppBuildResult {
 	appName: string;
-	type: 'backend' | 'frontend';
+	type: 'backend' | 'web' | 'mobile';
 	success: boolean;
 	outputPath?: string;
 	error?: string;
@@ -415,7 +415,7 @@ export async function workspaceBuildCommand(
 	const results: AppBuildResult[] = [];
 	const apps = Object.entries(workspace.apps);
 	const backendApps = apps.filter(([, app]) => app.type === 'backend');
-	const frontendApps = apps.filter(([, app]) => app.type === 'frontend');
+	const frontendApps = apps.filter(([, app]) => app.type === 'web');
 
 	logger.log(`\n🏗️  Building workspace: ${workspace.name}`);
 	logger.log(
@@ -486,7 +486,12 @@ export async function workspaceBuildCommand(
 		// Summary
 		logger.log(`\n📋 Build Summary:`);
 		for (const result of results) {
-			const icon = result.type === 'backend' ? '⚙️' : '🌐';
+			const icon =
+				result.type === 'backend'
+					? '⚙️'
+					: result.type === 'mobile'
+						? '📱'
+						: '🌐';
 			logger.log(
 				`   ${icon} ${result.appName}: ${result.outputPath || 'built'}`,
 			);
@@ -522,13 +527,24 @@ function getAppOutputPath(
 ): string {
 	const appPath = join(workspace.root, app.path);
 
-	if (app.type === 'frontend') {
-		// Next.js standalone output
-		return join(appPath, '.next');
-	} else {
-		// Backend .gkm output
-		return join(appPath, '.gkm');
+	if (app.type === 'mobile') {
+		// Mobile builds are produced by the framework's own toolchain
+		// (e.g. EAS Build) — no local output path.
+		return '';
+	}
+	if (app.type === 'web') {
+		switch (app.framework) {
+			case 'vite':
+			case 'tanstack-start':
+				return join(appPath, 'dist');
+			case 'remix':
+				return join(appPath, 'build');
+			default:
+				return join(appPath, '.next');
+		}
 	}
+	// Backend .gkm output
+	return join(appPath, '.gkm');
 }
 
 /**

package/src/credentials/__tests__/helpers.ts

@@ -76,7 +76,7 @@ export function createWorkspaceConfig(
 			const deps = app.dependencies
 				? `dependencies: [${app.dependencies.map((d) => `'${d}'`).join(', ')}],`
 				: '';
-			if (app.type === 'frontend') {
+			if (app.type === 'web') {
 				const framework = app.framework ?? 'nextjs';
 				return `    ${name}: {
       type: '${app.type}',

package/src/credentials/__tests__/workspaceCredentials.spec.ts

@@ -45,7 +45,7 @@ describe('workspace credentials', () => {
 				{
 					api: { type: 'backend', path: 'apps/api', port: 3001 },
 					web: {
-						type: 'frontend',
+						type: 'web',
 						path: 'apps/web',
 						port: 3002,
 						dependencies: ['api'],

package/src/deploy/__tests__/domain.spec.ts

@@ -55,7 +55,7 @@ describe('resolveHost', () => {
 	});
 
 	it('should return base domain for main frontend app', () => {
-		const app = createApp({ type: 'frontend' });
+		const app = createApp({ type: 'web' });
 		const host = resolveHost('web', app, 'production', dokployConfig, true);
 		expect(host).toBe('myapp.com');
 	});
@@ -100,7 +100,7 @@ describe('resolveHost', () => {
 });
 
 describe('isMainFrontendApp', () => {
-	const createApp = (type: 'backend' | 'frontend'): NormalizedAppConfig => ({
+	const createApp = (type: 'backend' | 'web'): NormalizedAppConfig => ({
 		type,
 		path: 'apps/test',
 		port: 3000,
@@ -111,7 +111,7 @@ describe('isMainFrontendApp', () => {
 	it('should return false for backend apps', () => {
 		const apps = {
 			api: createApp('backend'),
-			web: createApp('frontend'),
+			web: createApp('web'),
 		};
 		expect(isMainFrontendApp('api', apps.api, apps)).toBe(false);
 	});
@@ -119,8 +119,8 @@ describe('isMainFrontendApp', () => {
 	it('should return true for app named "web" if it is frontend', () => {
 		const apps = {
 			api: createApp('backend'),
-			web: createApp('frontend'),
-			admin: createApp('frontend'),
+			web: createApp('web'),
+			admin: createApp('web'),
 		};
 		expect(isMainFrontendApp('web', apps.web, apps)).toBe(true);
 	});
@@ -128,8 +128,8 @@ describe('isMainFrontendApp', () => {
 	it('should return true for first frontend app when no "web" app', () => {
 		const apps = {
 			api: createApp('backend'),
-			dashboard: createApp('frontend'),
-			admin: createApp('frontend'),
+			dashboard: createApp('web'),
+			admin: createApp('web'),
 		};
 		expect(isMainFrontendApp('dashboard', apps.dashboard, apps)).toBe(true);
 		expect(isMainFrontendApp('admin', apps.admin, apps)).toBe(false);
@@ -138,22 +138,22 @@ describe('isMainFrontendApp', () => {
 	it('should return false for non-first frontend when no "web" app', () => {
 		const apps = {
 			api: createApp('backend'),
-			dashboard: createApp('frontend'),
-			admin: createApp('frontend'),
+			dashboard: createApp('web'),
+			admin: createApp('web'),
 		};
 		expect(isMainFrontendApp('admin', apps.admin, apps)).toBe(false);
 	});
 
 	it('should return false when no frontend apps in allApps (edge case)', () => {
 		// Edge case: checking a frontend app against an empty allApps
-		const frontendApp = createApp('frontend');
+		const frontendApp = createApp('web');
 		expect(isMainFrontendApp('myapp', frontendApp, {})).toBe(false);
 	});
 });
 
 describe('generatePublicUrlBuildArgs', () => {
 	const createApp = (dependencies: string[]): NormalizedAppConfig => ({
-		type: 'frontend',
+		type: 'web',
 		path: 'apps/web',
 		port: 3001,
 		dependencies,
@@ -214,7 +214,7 @@ describe('generatePublicUrlBuildArgs', () => {
 
 describe('getPublicUrlArgNames', () => {
 	const createApp = (dependencies: string[]): NormalizedAppConfig => ({
-		type: 'frontend',
+		type: 'web',
 		path: 'apps/web',
 		port: 3001,
 		dependencies,

package/src/deploy/__tests__/env-resolver.spec.ts

@@ -517,6 +517,34 @@ describe('resolveEnvVar', () => {
 				expect(resolveEnvVar('NEXT_PUBLIC_AUTH_URL', context)).toBeUndefined();
 			});
 		});
+
+		describe('VITE_ prefix', () => {
+			it('should resolve VITE_API_URL from dependencyUrls.api', () => {
+				const context = createContext({
+					dependencyUrls: { api: 'https://api.example.com' },
+				});
+
+				expect(resolveEnvVar('VITE_API_URL', context)).toBe(
+					'https://api.example.com',
+				);
+			});
+
+			it('should resolve all of AUTH_URL, NEXT_PUBLIC_AUTH_URL, and VITE_AUTH_URL to the same value', () => {
+				const context = createContext({
+					dependencyUrls: { auth: 'https://auth.example.com' },
+				});
+
+				expect(resolveEnvVar('AUTH_URL', context)).toBe(
+					'https://auth.example.com',
+				);
+				expect(resolveEnvVar('NEXT_PUBLIC_AUTH_URL', context)).toBe(
+					'https://auth.example.com',
+				);
+				expect(resolveEnvVar('VITE_AUTH_URL', context)).toBe(
+					'https://auth.example.com',
+				);
+			});
+		});
 	});
 });
 
@@ -710,7 +738,7 @@ describe('Docker build arg extraction', () => {
 		overrides: Partial<EnvResolverContext> = {},
 	): EnvResolverContext => ({
 		app: {
-			type: 'frontend',
+			type: 'web',
 			path: 'apps/web',
 			port: 3001,
 			dependencies: ['api', 'auth'],