@geekmidas/cli 0.54.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cli",
-  "version": "0.54.0",
+  "version": "1.0.0",
   "description": "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs",
   "private": false,
   "type": "module",
@@ -40,6 +40,9 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
+    "@aws-sdk/client-route-53": "~3.971.0",
+    "@aws-sdk/client-ssm": "~3.971.0",
+    "@aws-sdk/credential-providers": "~3.971.0",
     "chokidar": "~4.0.3",
     "commander": "^12.1.0",
     "dotenv": "~17.2.3",
@@ -49,11 +52,12 @@
     "openapi-typescript": "^7.4.2",
     "pg": "~8.17.1",
     "prompts": "~2.4.2",
-    "@geekmidas/constructs": "~0.9.0",
-    "@geekmidas/envkit": "~0.7.0",
-    "@geekmidas/errors": "~0.1.0",
-    "@geekmidas/schema": "~0.1.0",
-    "@geekmidas/logger": "~0.4.0"
+    "tsx": "~4.20.3",
+    "@geekmidas/constructs": "~1.0.0",
+    "@geekmidas/envkit": "~1.0.0",
+    "@geekmidas/errors": "~1.0.0",
+    "@geekmidas/logger": "~1.0.0",
+    "@geekmidas/schema": "~1.0.0"
   },
   "devDependencies": {
     "@types/lodash.kebabcase": "^4.1.9",
@@ -63,10 +67,10 @@
     "typescript": "^5.8.2",
     "vitest": "^3.2.4",
     "zod": "~4.1.13",
-    "@geekmidas/testkit": "0.6.0"
+    "@geekmidas/testkit": "1.0.0"
   },
   "peerDependencies": {
-    "@geekmidas/telescope": "~0.6.0"
+    "@geekmidas/telescope": "~1.0.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/telescope": {

package/src/build/__tests__/handler-templates.spec.ts

@@ -528,7 +528,9 @@ describe('handler-templates', () => {
 				}),
 			];
 
-			const result = generateOptimizedSetupFunction(analyses, ['healthEndpoint']);
+			const result = generateOptimizedSetupFunction(analyses, [
+				'healthEndpoint',
+			]);
 
 			expect(result).toContain('export async function setupEndpoints');
 			expect(result).toContain('Minimal handlers (1 endpoints)');
@@ -548,7 +550,9 @@ describe('handler-templates', () => {
 				}),
 			];
 
-			const result = generateOptimizedSetupFunction(analyses, ['auditEndpoint']);
+			const result = generateOptimizedSetupFunction(analyses, [
+				'auditEndpoint',
+			]);
 
 			expect(result).toContain('import { HonoEndpoint }');
 			expect(result).toContain('HonoEndpoint.addRoutes');
@@ -603,7 +607,9 @@ describe('handler-templates', () => {
 				}),
 			];
 
-			const result = generateOptimizedSetupFunction(analyses, ['healthEndpoint']);
+			const result = generateOptimizedSetupFunction(analyses, [
+				'healthEndpoint',
+			]);
 
 			expect(result).toContain('if (enableOpenApi)');
 			expect(result).toContain('swaggerUI');
@@ -631,19 +637,18 @@ describe('handler-templates', () => {
 
 			const endpointImports = `import { healthEndpoint } from './endpoints/health';\nimport { createUserEndpoint } from './endpoints/users';`;
 
-			const result = generateOptimizedEndpointsFile(
-				analyses,
-				endpointImports,
-				['healthEndpoint', 'createUserEndpoint'],
-			);
+			const result = generateOptimizedEndpointsFile(analyses, endpointImports, [
+				'healthEndpoint',
+				'createUserEndpoint',
+			]);
 
 			expect(result).toContain('Generated optimized endpoints file');
 			expect(result).toContain('minimal: 1 endpoints');
 			expect(result).toContain('standard: 1 endpoints');
 			expect(result).toContain('full: 0 endpoints');
-			expect(result).toContain("import type { EnvironmentParser }");
-			expect(result).toContain("import { healthEndpoint }");
-			expect(result).toContain("import { createUserEndpoint }");
+			expect(result).toContain('import type { EnvironmentParser }');
+			expect(result).toContain('import { healthEndpoint }');
+			expect(result).toContain('import { createUserEndpoint }');
 			expect(result).toContain('validateBody');
 			expect(result).toContain('export async function setupEndpoints');
 		});
@@ -753,8 +758,10 @@ describe('handler-templates', () => {
 
 			expect(files['minimal.ts']).toContain('Minimal-tier endpoint handlers');
 			expect(files['minimal.ts']).toContain('1 endpoints');
-			expect(files['minimal.ts']).toContain('export function setupMinimalEndpoints');
-			expect(files['minimal.ts']).toContain("import { healthEndpoint }");
+			expect(files['minimal.ts']).toContain(
+				'export function setupMinimalEndpoints',
+			);
+			expect(files['minimal.ts']).toContain('import { healthEndpoint }');
 			expect(files['minimal.ts']).toContain("app.get('/health'");
 		});
 
@@ -798,8 +805,10 @@ describe('handler-templates', () => {
 
 			expect(files['standard.ts']).toContain('Standard-tier endpoint handlers');
 			expect(files['standard.ts']).toContain('1 endpoints');
-			expect(files['standard.ts']).toContain('export function setupStandardEndpoints');
-			expect(files['standard.ts']).toContain("import { usersEndpoint }");
+			expect(files['standard.ts']).toContain(
+				'export function setupStandardEndpoints',
+			);
+			expect(files['standard.ts']).toContain('import { usersEndpoint }');
 		});
 
 		it('should generate standard file with events import when needed', () => {
@@ -814,12 +823,17 @@ describe('handler-templates', () => {
 			];
 
 			const endpointImports = [
-				{ exportName: 'createOrderEndpoint', importPath: '../endpoints/orders' },
+				{
+					exportName: 'createOrderEndpoint',
+					importPath: '../endpoints/orders',
+				},
 			];
 
 			const files = generateEndpointFilesByTier(analyses, endpointImports);
 
-			expect(files['standard.ts']).toContain('import { publishConstructEvents }');
+			expect(files['standard.ts']).toContain(
+				'import { publishConstructEvents }',
+			);
 		});
 
 		it('should generate full file with HonoEndpoint', () => {
@@ -842,7 +856,7 @@ describe('handler-templates', () => {
 			expect(files['full.ts']).toContain('Full-tier endpoint handlers');
 			expect(files['full.ts']).toContain('import { HonoEndpoint }');
 			expect(files['full.ts']).toContain('HonoEndpoint.addRoutes');
-			expect(files['full.ts']).toContain("import { auditEndpoint }");
+			expect(files['full.ts']).toContain('import { auditEndpoint }');
 		});
 
 		it('should generate empty full file when no full endpoints', () => {
@@ -899,10 +913,12 @@ describe('handler-templates', () => {
 			expect(files['index.ts']).toContain('minimal: 1 endpoints');
 			expect(files['index.ts']).toContain('standard: 1 endpoints');
 			expect(files['index.ts']).toContain('full: 1 endpoints');
-			expect(files['index.ts']).toContain("import { setupMinimalEndpoints }");
-			expect(files['index.ts']).toContain("import { setupStandardEndpoints }");
-			expect(files['index.ts']).toContain("import { setupFullEndpoints }");
-			expect(files['index.ts']).toContain('export async function setupEndpoints');
+			expect(files['index.ts']).toContain('import { setupMinimalEndpoints }');
+			expect(files['index.ts']).toContain('import { setupStandardEndpoints }');
+			expect(files['index.ts']).toContain('import { setupFullEndpoints }');
+			expect(files['index.ts']).toContain(
+				'export async function setupEndpoints',
+			);
 		});
 
 		it('should include validator imports in minimal file when needed', () => {
@@ -922,7 +938,9 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesByTier(analyses, endpointImports);
 
-			expect(files['minimal.ts']).toContain("import { validateBody } from './validators.js'");
+			expect(files['minimal.ts']).toContain(
+				"import { validateBody } from './validators.js'",
+			);
 		});
 
 		it('should include validator imports in standard file when needed', () => {
@@ -942,7 +960,9 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesByTier(analyses, endpointImports);
 
-			expect(files['standard.ts']).toContain("import { validateBody } from './validators.js'");
+			expect(files['standard.ts']).toContain(
+				"import { validateBody } from './validators.js'",
+			);
 		});
 	});
 
@@ -987,9 +1007,15 @@ describe('handler-templates', () => {
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
 			expect(files).toHaveProperty('minimal/healthEndpoint.ts');
-			expect(files['minimal/healthEndpoint.ts']).toContain('Minimal endpoint: /health (GET)');
-			expect(files['minimal/healthEndpoint.ts']).toContain('export function setupHealthEndpoint');
-			expect(files['minimal/healthEndpoint.ts']).toContain("import { healthEndpoint }");
+			expect(files['minimal/healthEndpoint.ts']).toContain(
+				'Minimal endpoint: /health (GET)',
+			);
+			expect(files['minimal/healthEndpoint.ts']).toContain(
+				'export function setupHealthEndpoint',
+			);
+			expect(files['minimal/healthEndpoint.ts']).toContain(
+				'import { healthEndpoint }',
+			);
 		});
 
 		it('should generate individual endpoint files for standard tier', () => {
@@ -1010,9 +1036,15 @@ describe('handler-templates', () => {
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
 			expect(files).toHaveProperty('standard/usersEndpoint.ts');
-			expect(files['standard/usersEndpoint.ts']).toContain('Standard endpoint: /api/users (GET)');
-			expect(files['standard/usersEndpoint.ts']).toContain('export function setupUsersEndpoint');
-			expect(files['standard/usersEndpoint.ts']).toContain("import { usersEndpoint }");
+			expect(files['standard/usersEndpoint.ts']).toContain(
+				'Standard endpoint: /api/users (GET)',
+			);
+			expect(files['standard/usersEndpoint.ts']).toContain(
+				'export function setupUsersEndpoint',
+			);
+			expect(files['standard/usersEndpoint.ts']).toContain(
+				'import { usersEndpoint }',
+			);
 		});
 
 		it('should generate individual endpoint files for full tier', () => {
@@ -1033,9 +1065,15 @@ describe('handler-templates', () => {
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
 			expect(files).toHaveProperty('full/auditEndpoint.ts');
-			expect(files['full/auditEndpoint.ts']).toContain('Full endpoint: /api/audit (POST)');
-			expect(files['full/auditEndpoint.ts']).toContain('export function setupAuditEndpoint');
-			expect(files['full/auditEndpoint.ts']).toContain('import { HonoEndpoint }');
+			expect(files['full/auditEndpoint.ts']).toContain(
+				'Full endpoint: /api/audit (POST)',
+			);
+			expect(files['full/auditEndpoint.ts']).toContain(
+				'export function setupAuditEndpoint',
+			);
+			expect(files['full/auditEndpoint.ts']).toContain(
+				'import { HonoEndpoint }',
+			);
 		});
 
 		it('should generate tier index files that import individual endpoints', () => {
@@ -1061,10 +1099,18 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['minimal/index.ts']).toContain("import { setupHealthEndpoint } from './healthEndpoint.js'");
-			expect(files['minimal/index.ts']).toContain("import { setupReadyEndpoint } from './readyEndpoint.js'");
-			expect(files['minimal/index.ts']).toContain('setupHealthEndpoint(app, logger)');
-			expect(files['minimal/index.ts']).toContain('setupReadyEndpoint(app, logger)');
+			expect(files['minimal/index.ts']).toContain(
+				"import { setupHealthEndpoint } from './healthEndpoint.js'",
+			);
+			expect(files['minimal/index.ts']).toContain(
+				"import { setupReadyEndpoint } from './readyEndpoint.js'",
+			);
+			expect(files['minimal/index.ts']).toContain(
+				'setupHealthEndpoint(app, logger)',
+			);
+			expect(files['minimal/index.ts']).toContain(
+				'setupReadyEndpoint(app, logger)',
+			);
 		});
 
 		it('should generate empty tier index for tiers with no endpoints', () => {
@@ -1083,7 +1129,9 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['standard/index.ts']).toContain('No standard-tier endpoints');
+			expect(files['standard/index.ts']).toContain(
+				'No standard-tier endpoints',
+			);
 			expect(files['full/index.ts']).toContain('No full-tier endpoints');
 		});
 
@@ -1103,9 +1151,15 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['index.ts']).toContain("import { setupMinimalEndpoints } from './minimal/index.js'");
-			expect(files['index.ts']).toContain("import { setupStandardEndpoints } from './standard/index.js'");
-			expect(files['index.ts']).toContain("import { setupFullEndpoints } from './full/index.js'");
+			expect(files['index.ts']).toContain(
+				"import { setupMinimalEndpoints } from './minimal/index.js'",
+			);
+			expect(files['index.ts']).toContain(
+				"import { setupStandardEndpoints } from './standard/index.js'",
+			);
+			expect(files['index.ts']).toContain(
+				"import { setupFullEndpoints } from './full/index.js'",
+			);
 		});
 
 		it('should include validator imports in individual endpoint files when needed', () => {
@@ -1120,12 +1174,17 @@ describe('handler-templates', () => {
 			];
 
 			const endpointImports = [
-				{ exportName: 'createUserEndpoint', importPath: '../../endpoints/users' },
+				{
+					exportName: 'createUserEndpoint',
+					importPath: '../../endpoints/users',
+				},
 			];
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['minimal/createUserEndpoint.ts']).toContain("import { validateBody } from '../validators.js'");
+			expect(files['minimal/createUserEndpoint.ts']).toContain(
+				"import { validateBody } from '../validators.js'",
+			);
 		});
 
 		it('should include events import in standard endpoint files when needed', () => {
@@ -1140,12 +1199,17 @@ describe('handler-templates', () => {
 			];
 
 			const endpointImports = [
-				{ exportName: 'createOrderEndpoint', importPath: '../../endpoints/orders' },
+				{
+					exportName: 'createOrderEndpoint',
+					importPath: '../../endpoints/orders',
+				},
 			];
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['standard/createOrderEndpoint.ts']).toContain('import { publishConstructEvents }');
+			expect(files['standard/createOrderEndpoint.ts']).toContain(
+				'import { publishConstructEvents }',
+			);
 		});
 
 		it('should skip endpoints without matching imports', () => {
@@ -1192,7 +1256,9 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['standard/index.ts']).toContain('setupUsersEndpoint(app, serviceDiscovery, logger)');
+			expect(files['standard/index.ts']).toContain(
+				'setupUsersEndpoint(app, serviceDiscovery, logger)',
+			);
 		});
 
 		it('should generate full tier index with correct function calls', () => {
@@ -1212,7 +1278,9 @@ describe('handler-templates', () => {
 
 			const files = generateEndpointFilesNested(analyses, endpointImports);
 
-			expect(files['full/index.ts']).toContain('setupAuditEndpoint(app, serviceDiscovery, openApiOptions)');
+			expect(files['full/index.ts']).toContain(
+				'setupAuditEndpoint(app, serviceDiscovery, openApiOptions)',
+			);
 			expect(files['full/index.ts']).toContain('const openApiOptions');
 		});
 	});

package/src/deploy/CachedStateProvider.ts

@@ -0,0 +1,86 @@
+/**
+ * Cached State Provider
+ *
+ * Wraps a remote state provider (SSM) with local filesystem cache.
+ * - Read: Local first, then remote if missing
+ * - Write: Remote first, then update local cache
+ *
+ * This enables fast local development while keeping SSM as source of truth.
+ */
+
+import type { StateProvider } from './StateProvider';
+import type { DokployStageState } from './state';
+
+/**
+ * Cached state provider that wraps a remote provider with local cache.
+ */
+export class CachedStateProvider implements StateProvider {
+	constructor(
+		private readonly remote: StateProvider,
+		private readonly local: StateProvider,
+	) {}
+
+	async read(stage: string): Promise<DokployStageState | null> {
+		// Try local cache first
+		const localState = await this.local.read(stage);
+		if (localState) {
+			return localState;
+		}
+
+		// Fall back to remote
+		const remoteState = await this.remote.read(stage);
+		if (remoteState) {
+			// Update local cache
+			await this.local.write(stage, remoteState);
+		}
+
+		return remoteState;
+	}
+
+	async write(stage: string, state: DokployStageState): Promise<void> {
+		// Write to remote first (source of truth)
+		await this.remote.write(stage, state);
+
+		// Update local cache
+		await this.local.write(stage, state);
+	}
+
+	/**
+	 * Force pull from remote to local.
+	 * Used by `gkm state pull` command.
+	 */
+	async pull(stage: string): Promise<DokployStageState | null> {
+		const remoteState = await this.remote.read(stage);
+		if (remoteState) {
+			await this.local.write(stage, remoteState);
+		}
+		return remoteState;
+	}
+
+	/**
+	 * Force push from local to remote.
+	 * Used by `gkm state push` command.
+	 */
+	async push(stage: string): Promise<DokployStageState | null> {
+		const localState = await this.local.read(stage);
+		if (localState) {
+			await this.remote.write(stage, localState);
+		}
+		return localState;
+	}
+
+	/**
+	 * Get both local and remote state for comparison.
+	 * Used by `gkm state diff` command.
+	 */
+	async diff(stage: string): Promise<{
+		local: DokployStageState | null;
+		remote: DokployStageState | null;
+	}> {
+		const [local, remote] = await Promise.all([
+			this.local.read(stage),
+			this.remote.read(stage),
+		]);
+		return { local, remote };
+	}
+}

package/src/deploy/LocalStateProvider.ts

@@ -0,0 +1,57 @@
+/**
+ * Local Filesystem State Provider
+ *
+ * Stores deployment state in .gkm/deploy-{stage}.json files.
+ * This is the default provider for local development.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { StateProvider } from './StateProvider';
+import type { DokployStageState } from './state';
+
+/**
+ * Get the state file path for a stage.
+ */
+function getStateFilePath(workspaceRoot: string, stage: string): string {
+	return join(workspaceRoot, '.gkm', `deploy-${stage}.json`);
+}
+
+/**
+ * Local filesystem state provider.
+ *
+ * Stores state in .gkm/deploy-{stage}.json files in the workspace root.
+ */
+export class LocalStateProvider implements StateProvider {
+	constructor(private readonly workspaceRoot: string) {}
+
+	async read(stage: string): Promise<DokployStageState | null> {
+		const filePath = getStateFilePath(this.workspaceRoot, stage);
+
+		try {
+			const content = await readFile(filePath, 'utf-8');
+			return JSON.parse(content) as DokployStageState;
+		} catch (error) {
+			// File doesn't exist - return null
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+				return null;
+			}
+			// Log other errors but don't fail
+			console.warn(`Warning: Could not read deploy state: ${error}`);
+			return null;
+		}
+	}
+
+	async write(stage: string, state: DokployStageState): Promise<void> {
+		const filePath = getStateFilePath(this.workspaceRoot, stage);
+		const dir = join(this.workspaceRoot, '.gkm');
+
+		// Ensure .gkm directory exists
+		await mkdir(dir, { recursive: true });
+
+		// Update last deployed timestamp
+		state.lastDeployedAt = new Date().toISOString();
+
+		await writeFile(filePath, JSON.stringify(state, null, 2));
+	}
+}

package/src/deploy/SSMStateProvider.ts

@@ -0,0 +1,93 @@
+/**
+ * AWS SSM Parameter Store State Provider
+ *
+ * Stores deployment state as SecureString parameters in AWS SSM.
+ * Uses AWS-managed KMS key for encryption (free tier).
+ *
+ * Parameter naming: /gkm/{workspaceName}/{stage}/state
+ */
+
+import {
+	GetParameterCommand,
+	ParameterNotFound,
+	PutParameterCommand,
+	SSMClient,
+} from '@aws-sdk/client-ssm';
+import type { AwsRegion, StateProvider } from './StateProvider';
+import type { DokployStageState } from './state';
+
+export interface SSMStateProviderOptions {
+	/** Workspace name (used in parameter path) */
+	workspaceName: string;
+	/** AWS region (required) */
+	region: AwsRegion;
+}
+
+/**
+ * AWS SSM Parameter Store state provider.
+ *
+ * Stores state as encrypted SecureString parameters.
+ * Parameter path: /gkm/{workspaceName}/{stage}/state
+ */
+export class SSMStateProvider implements StateProvider {
+	private readonly client: SSMClient;
+	private readonly workspaceName: string;
+
+	constructor(options: SSMStateProviderOptions) {
+		this.workspaceName = options.workspaceName;
+		this.client = new SSMClient({
+			region: options.region,
+		});
+	}
+
+	/**
+	 * Get the SSM parameter name for a stage.
+	 */
+	private getParameterName(stage: string): string {
+		return `/gkm/${this.workspaceName}/${stage}/state`;
+	}
+
+	async read(stage: string): Promise<DokployStageState | null> {
+		const parameterName = this.getParameterName(stage);
+
+		try {
+			const response = await this.client.send(
+				new GetParameterCommand({
+					Name: parameterName,
+					WithDecryption: true,
+				}),
+			);
+
+			if (!response.Parameter?.Value) {
+				return null;
+			}
+
+			return JSON.parse(response.Parameter.Value) as DokployStageState;
+		} catch (error) {
+			// Parameter doesn't exist - return null (new deployment)
+			if (error instanceof ParameterNotFound) {
+				return null;
+			}
+
+			// Re-throw other errors (permission denied, network, etc.)
+			throw error;
+		}
+	}
+
+	async write(stage: string, state: DokployStageState): Promise<void> {
+		const parameterName = this.getParameterName(stage);
+
+		// Update last deployed timestamp
+		state.lastDeployedAt = new Date().toISOString();
+
+		await this.client.send(
+			new PutParameterCommand({
+				Name: parameterName,
+				Value: JSON.stringify(state),
+				Type: 'SecureString',
+				Overwrite: true,
+				Description: `GKM deployment state for ${this.workspaceName}/${stage}`,
+			}),
+		);
+	}
+}