@geekmidas/cli 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs",
   "private": false,
   "type": "module",
@@ -55,9 +55,9 @@
     "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",
-    "@geekmidas/logger": "~1.0.0"
+    "@geekmidas/errors": "~1.0.0"
   },
   "devDependencies": {
     "@types/lodash.kebabcase": "^4.1.9",
@@ -67,7 +67,7 @@
     "typescript": "^5.8.2",
     "vitest": "^3.2.4",
     "zod": "~4.1.13",
-    "@geekmidas/testkit": "1.0.0"
+    "@geekmidas/testkit": "1.0.1"
   },
   "peerDependencies": {
     "@geekmidas/telescope": "~1.0.0"

package/scripts/sync-versions.ts

@@ -16,7 +16,6 @@ const PACKAGES = [
 	'audit',
 	'auth',
 	'cache',
-	'cli',
 	'client',
 	'cloud',
 	'constructs',
@@ -54,16 +53,39 @@ function generateVersionsFile(): string {
 		versions[`@geekmidas/${pkg}`] = `~${version}`;
 	}
 
-	const content = `/**
+	const content = `import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Load package.json - handles both bundled (flat dist/) and source (nested src/init/)
+function loadPackageJson(): { version: string } {
+	try {
+		// Try flat dist path first (../package.json from dist/)
+		return require('../package.json');
+	} catch {
+		// Fall back to nested source path (../../package.json from src/init/)
+		return require('../../package.json');
+	}
+}
+
+const pkg = loadPackageJson();
+
+/**
+ * CLI version resolved from package.json at runtime
+ */
+export const CLI_VERSION = \`~\${pkg.version}\`;
+
+/**
  * Package versions for @geekmidas packages
  *
- * AUTO-GENERATED - Do not edit manually
+ * AUTO-GENERATED (except CLI) - Do not edit manually
  * Run: pnpm --filter @geekmidas/cli sync-versions
  */
 export const GEEKMIDAS_VERSIONS = {
 ${Object.entries(versions)
 	.map(([pkg, version]) => `\t'${pkg}': '${version}',`)
 	.join('\n')}
+	'@geekmidas/cli': CLI_VERSION,
 } as const;
 
 export type GeekmidasPackage = keyof typeof GEEKMIDAS_VERSIONS;

package/src/deploy/SSMStateProvider.ts

@@ -12,6 +12,7 @@ import {
 	ParameterNotFound,
 	PutParameterCommand,
 	SSMClient,
+	type SSMClientConfig,
 } from '@aws-sdk/client-ssm';
 import type { AwsRegion, StateProvider } from './StateProvider';
 import type { DokployStageState } from './state';
@@ -19,8 +20,12 @@ import type { DokployStageState } from './state';
 export interface SSMStateProviderOptions {
 	/** Workspace name (used in parameter path) */
 	workspaceName: string;
-	/** AWS region (required) */
-	region: AwsRegion;
+	/** AWS region */
+	region?: AwsRegion;
+	/** AWS credentials (optional - uses default credential chain if not provided) */
+	credentials?: SSMClientConfig['credentials'];
+	/** Custom endpoint (for LocalStack or other S3-compatible services) */
+	endpoint?: string;
 }
 
 /**
@@ -30,14 +35,22 @@ export interface SSMStateProviderOptions {
  * Parameter path: /gkm/{workspaceName}/{stage}/state
  */
 export class SSMStateProvider implements StateProvider {
-	private readonly client: SSMClient;
-	private readonly workspaceName: string;
+	constructor(
+		readonly workspaceName: string,
+		private readonly client: SSMClient,
+	) {}
 
-	constructor(options: SSMStateProviderOptions) {
-		this.workspaceName = options.workspaceName;
-		this.client = new SSMClient({
+	/**
+	 * Create an SSMStateProvider with a new SSMClient.
+	 */
+	static create(options: SSMStateProviderOptions): SSMStateProvider {
+		const client = new SSMClient({
 			region: options.region,
+			credentials: options.credentials,
+			endpoint: options.endpoint,
 		});
+
+		return new SSMStateProvider(options.workspaceName, client);
 	}
 
 	/**

package/src/deploy/StateProvider.ts

@@ -158,7 +158,7 @@ export async function createStateProvider(
 		const { CachedStateProvider } = await import('./CachedStateProvider');
 
 		const local = new LocalStateProvider(workspaceRoot);
-		const ssm = new SSMStateProvider({
+		const ssm = SSMStateProvider.create({
 			workspaceName,
 			region: (config as SSMStateConfig).region,
 		});

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

@@ -44,14 +44,8 @@ describe('SSMStateProvider', () => {
 			},
 		});
 
-		provider = new SSMStateProvider({
-			workspaceName,
-			region: 'us-east-1',
-		});
-
-		// Override the client's endpoint for localstack
-		// @ts-expect-error - accessing private property for testing
-		provider.client = client;
+		// Create provider with injected client
+		provider = new SSMStateProvider(workspaceName, client);
 	});
 
 	afterEach(async () => {
@@ -70,6 +64,19 @@ describe('SSMStateProvider', () => {
 		client.destroy();
 	});
 
+	describe('static create', () => {
+		it('should create provider with options', () => {
+			const provider = SSMStateProvider.create({
+				workspaceName: 'my-workspace',
+				region: 'us-west-2',
+				endpoint: LOCALSTACK_ENDPOINT,
+			});
+
+			expect(provider).toBeInstanceOf(SSMStateProvider);
+			expect(provider.workspaceName).toBe('my-workspace');
+		});
+	});
+
 	describe('read', () => {
 		it('should return null when parameter does not exist', async () => {
 			const state = await provider.read('nonexistent-stage');

package/src/deploy/__tests__/state-e2e.spec.ts

@@ -0,0 +1,385 @@
+/**
+ * End-to-End State Provider Tests
+ *
+ * Tests the full flow from workspace config to state storage.
+ * - Local: verifies state is written to .gkm/deploy-{stage}.json
+ * - SSM: verifies state is written to AWS SSM Parameter Store (via LocalStack)
+ *
+ * SSM tests require LocalStack: docker compose up -d localstack
+ */
+
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+	DeleteParameterCommand,
+	GetParameterCommand,
+	PutParameterCommand,
+	SSMClient,
+} from '@aws-sdk/client-ssm';
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+} from 'vitest';
+import { normalizeWorkspace } from '../../workspace/index';
+import type { WorkspaceConfig } from '../../workspace/types';
+import { CachedStateProvider } from '../CachedStateProvider';
+import { LocalStateProvider } from '../LocalStateProvider';
+import { SSMStateProvider } from '../SSMStateProvider';
+import { createStateProvider } from '../StateProvider';
+import type { DokployStageState } from '../state';
+
+describe('State Provider E2E', () => {
+	const testStage = 'e2e-test';
+
+	const createTestState = (
+		overrides?: Partial<DokployStageState>,
+	): DokployStageState => ({
+		provider: 'dokploy',
+		stage: testStage,
+		environmentId: 'env_e2e_123',
+		applications: { api: 'app_e2e_123', web: 'app_e2e_456' },
+		services: { postgresId: 'pg_e2e_123', redisId: 'redis_e2e_123' },
+		lastDeployedAt: '2024-01-01T00:00:00.000Z',
+		...overrides,
+	});
+
+	describe('Local State Provider', () => {
+		let testDir: string;
+
+		beforeEach(async () => {
+			testDir = join(tmpdir(), `gkm-e2e-local-${Date.now()}`);
+			await mkdir(testDir, { recursive: true });
+		});
+
+		afterEach(async () => {
+			await rm(testDir, { recursive: true, force: true });
+		});
+
+		it('should write state to filesystem when config has state.provider = local', async () => {
+			// 1. Create workspace config with local state provider
+			const config: WorkspaceConfig = {
+				name: 'e2e-local-test',
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				state: { provider: 'local' },
+			};
+
+			// 2. Normalize the workspace (simulates loadWorkspaceConfig)
+			const workspace = normalizeWorkspace(config, testDir);
+
+			// 3. Verify state config is passed through
+			expect(workspace.state).toEqual({ provider: 'local' });
+
+			// 4. Create state provider from workspace config
+			const provider = await createStateProvider({
+				config: workspace.state,
+				workspaceRoot: workspace.root,
+				workspaceName: workspace.name,
+			});
+
+			// 5. Write state
+			const state = createTestState();
+			await provider.write(testStage, state);
+
+			// 6. Verify state was written to filesystem directly
+			const stateFilePath = join(testDir, '.gkm', `deploy-${testStage}.json`);
+			const fileContent = await readFile(stateFilePath, 'utf-8');
+			const storedState = JSON.parse(fileContent);
+
+			expect(storedState.provider).toBe('dokploy');
+			expect(storedState.stage).toBe(testStage);
+			expect(storedState.environmentId).toBe('env_e2e_123');
+			expect(storedState.applications).toEqual({
+				api: 'app_e2e_123',
+				web: 'app_e2e_456',
+			});
+			expect(storedState.services).toEqual({
+				postgresId: 'pg_e2e_123',
+				redisId: 'redis_e2e_123',
+			});
+			expect(storedState.lastDeployedAt).toBeDefined();
+		});
+
+		it('should write state to filesystem when state config is undefined (default)', async () => {
+			// 1. Create workspace config WITHOUT state (should default to local)
+			const config: WorkspaceConfig = {
+				name: 'e2e-default-test',
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				// No state config - should default to local
+			};
+
+			// 2. Normalize the workspace
+			const workspace = normalizeWorkspace(config, testDir);
+
+			// 3. Verify state config is undefined
+			expect(workspace.state).toBeUndefined();
+
+			// 4. Create state provider (should create LocalStateProvider)
+			const provider = await createStateProvider({
+				config: workspace.state,
+				workspaceRoot: workspace.root,
+				workspaceName: workspace.name,
+			});
+
+			// 5. Write state
+			const state = createTestState();
+			await provider.write(testStage, state);
+
+			// 6. Verify state was written to filesystem
+			const stateFilePath = join(testDir, '.gkm', `deploy-${testStage}.json`);
+			const fileContent = await readFile(stateFilePath, 'utf-8');
+			const storedState = JSON.parse(fileContent);
+
+			expect(storedState.environmentId).toBe('env_e2e_123');
+			expect(storedState.applications.api).toBe('app_e2e_123');
+		});
+
+		it('should read state back correctly through provider', async () => {
+			const config: WorkspaceConfig = {
+				name: 'e2e-read-test',
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				state: { provider: 'local' },
+			};
+
+			const workspace = normalizeWorkspace(config, testDir);
+			const provider = await createStateProvider({
+				config: workspace.state,
+				workspaceRoot: workspace.root,
+				workspaceName: workspace.name,
+			});
+
+			// Write state
+			const originalState = createTestState();
+			await provider.write(testStage, originalState);
+
+			// Read state back
+			const readState = await provider.read(testStage);
+
+			expect(readState).not.toBeNull();
+			expect(readState!.environmentId).toBe('env_e2e_123');
+			expect(readState!.applications).toEqual({
+				api: 'app_e2e_123',
+				web: 'app_e2e_456',
+			});
+		});
+	});
+
+	describe('SSM State Provider', () => {
+		const LOCALSTACK_ENDPOINT = 'http://localhost:4566';
+		const workspaceName = 'e2e-ssm-test';
+		let ssmClient: SSMClient;
+		let testDir: string;
+
+		beforeAll(() => {
+			process.env.AWS_ACCESS_KEY_ID = 'test';
+			process.env.AWS_SECRET_ACCESS_KEY = 'test';
+		});
+
+		beforeEach(async () => {
+			testDir = join(tmpdir(), `gkm-e2e-ssm-${Date.now()}`);
+			await mkdir(testDir, { recursive: true });
+
+			ssmClient = new SSMClient({
+				region: 'us-east-1',
+				endpoint: LOCALSTACK_ENDPOINT,
+				credentials: {
+					accessKeyId: 'test',
+					secretAccessKey: 'test',
+				},
+			});
+		});
+
+		afterEach(async () => {
+			// Clean up SSM parameter
+			try {
+				await ssmClient.send(
+					new DeleteParameterCommand({
+						Name: `/gkm/${workspaceName}/${testStage}/state`,
+					}),
+				);
+			} catch {
+				// Ignore if parameter doesn't exist
+			}
+
+			// Clean up test directory
+			await rm(testDir, { recursive: true, force: true });
+		});
+
+		afterAll(() => {
+			ssmClient.destroy();
+		});
+
+		it('should write state to SSM when config has state.provider = ssm', async () => {
+			// 1. Create workspace config with SSM state provider
+			const config: WorkspaceConfig = {
+				name: workspaceName,
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				state: { provider: 'ssm', region: 'us-east-1' },
+			};
+
+			// 2. Normalize the workspace
+			const workspace = normalizeWorkspace(config, testDir);
+
+			// 3. Verify state config is passed through
+			expect(workspace.state).toEqual({ provider: 'ssm', region: 'us-east-1' });
+
+			// 4. Create providers with injected SSM client (for LocalStack)
+			const local = new LocalStateProvider(workspace.root);
+			const ssm = new SSMStateProvider(workspace.name, ssmClient);
+			const provider = new CachedStateProvider(ssm, local);
+
+			// 5. Write state
+			const state = createTestState();
+			await provider.write(testStage, state);
+
+			// 6. Query SSM directly to verify state was written
+			const response = await ssmClient.send(
+				new GetParameterCommand({
+					Name: `/gkm/${workspaceName}/${testStage}/state`,
+					WithDecryption: true,
+				}),
+			);
+
+			expect(response.Parameter).toBeDefined();
+			expect(response.Parameter!.Value).toBeDefined();
+
+			const storedState = JSON.parse(response.Parameter!.Value!);
+			expect(storedState.provider).toBe('dokploy');
+			expect(storedState.stage).toBe(testStage);
+			expect(storedState.environmentId).toBe('env_e2e_123');
+			expect(storedState.applications).toEqual({
+				api: 'app_e2e_123',
+				web: 'app_e2e_456',
+			});
+			expect(storedState.services).toEqual({
+				postgresId: 'pg_e2e_123',
+				redisId: 'redis_e2e_123',
+			});
+		});
+
+		it('should read state from SSM correctly', async () => {
+			// 1. Pre-populate SSM with state
+			const preExistingState: DokployStageState = {
+				provider: 'dokploy',
+				stage: testStage,
+				environmentId: 'env_pre_existing',
+				applications: { api: 'app_pre_123' },
+				services: { postgresId: 'pg_pre_123' },
+				lastDeployedAt: '2024-06-01T00:00:00.000Z',
+			};
+
+			await ssmClient.send(
+				new PutParameterCommand({
+					Name: `/gkm/${workspaceName}/${testStage}/state`,
+					Value: JSON.stringify(preExistingState),
+					Type: 'SecureString',
+					Overwrite: true,
+				}),
+			);
+
+			// 2. Create workspace config with SSM state provider
+			const config: WorkspaceConfig = {
+				name: workspaceName,
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				state: { provider: 'ssm', region: 'us-east-1' },
+			};
+
+			const workspace = normalizeWorkspace(config, testDir);
+
+			// 3. Create providers with injected SSM client
+			const local = new LocalStateProvider(workspace.root);
+			const ssm = new SSMStateProvider(workspace.name, ssmClient);
+			const provider = new CachedStateProvider(ssm, local);
+
+			// 4. Read state through provider
+			const readState = await provider.read(testStage);
+
+			expect(readState).not.toBeNull();
+			expect(readState!.environmentId).toBe('env_pre_existing');
+			expect(readState!.applications.api).toBe('app_pre_123');
+		});
+
+		it('should use CachedStateProvider that syncs local and remote', async () => {
+			const config: WorkspaceConfig = {
+				name: workspaceName,
+				apps: {
+					api: {
+						type: 'backend',
+						path: 'apps/api',
+						port: 3000,
+						routes: './src/**/*.ts',
+					},
+				},
+				state: { provider: 'ssm', region: 'us-east-1' },
+			};
+
+			const workspace = normalizeWorkspace(config, testDir);
+
+			// Create providers with injected SSM client
+			const local = new LocalStateProvider(workspace.root);
+			const ssm = new SSMStateProvider(workspace.name, ssmClient);
+			const provider = new CachedStateProvider(ssm, local);
+
+			// Write state
+			const state = createTestState();
+			await provider.write(testStage, state);
+
+			// Verify both local and SSM have the state
+			// Check local file
+			const localFilePath = join(testDir, '.gkm', `deploy-${testStage}.json`);
+			const localContent = await readFile(localFilePath, 'utf-8');
+			const localState = JSON.parse(localContent);
+			expect(localState.environmentId).toBe('env_e2e_123');
+
+			// Check SSM directly
+			const ssmResponse = await ssmClient.send(
+				new GetParameterCommand({
+					Name: `/gkm/${workspaceName}/${testStage}/state`,
+					WithDecryption: true,
+				}),
+			);
+			const ssmState = JSON.parse(ssmResponse.Parameter!.Value!);
+			expect(ssmState.environmentId).toBe('env_e2e_123');
+		});
+	});
+});

package/src/init/__tests__/init.spec.ts

@@ -1,10 +1,13 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { initCommand } from '../index.js';
 
+// Project names used in tests - keystore directories are created at ~/.gkm/{name}
+const TEST_PROJECT_NAMES = ['my-api', 'my-monorepo', 'my-fullstack'];
+
 describe('initCommand', () => {
 	let tempDir: string;
 	let originalCwd: string;
@@ -19,6 +22,12 @@ describe('initCommand', () => {
 	afterEach(async () => {
 		process.chdir(originalCwd);
 		await rm(tempDir, { recursive: true, force: true });
+
+		// Clean up keystore directories created at ~/.gkm/{project-name}
+		const gkmDir = join(homedir(), '.gkm');
+		for (const name of TEST_PROJECT_NAMES) {
+			await rm(join(gkmDir, name), { recursive: true, force: true });
+		}
 	});
 
 	describe('non-monorepo', () => {

package/src/init/versions.ts

@@ -1,14 +1,35 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Load package.json - handles both bundled (flat dist/) and source (nested src/init/)
+function loadPackageJson(): { version: string } {
+	try {
+		// Try flat dist path first (../package.json from dist/)
+		return require('../package.json');
+	} catch {
+		// Fall back to nested source path (../../package.json from src/init/)
+		return require('../../package.json');
+	}
+}
+
+const pkg = loadPackageJson();
+
+/**
+ * CLI version resolved from package.json at runtime
+ */
+export const CLI_VERSION = `~${pkg.version}`;
+
 /**
  * Package versions for @geekmidas packages
  *
- * AUTO-GENERATED - Do not edit manually
+ * AUTO-GENERATED (except CLI) - Do not edit manually
  * Run: pnpm --filter @geekmidas/cli sync-versions
  */
 export const GEEKMIDAS_VERSIONS = {
 	'@geekmidas/audit': '~1.0.0',
 	'@geekmidas/auth': '~1.0.0',
 	'@geekmidas/cache': '~1.0.0',
-	'@geekmidas/cli': '~1.0.0',
 	'@geekmidas/client': '~1.0.0',
 	'@geekmidas/cloud': '~1.0.0',
 	'@geekmidas/constructs': '~1.0.0',
@@ -25,6 +46,7 @@ export const GEEKMIDAS_VERSIONS = {
 	'@geekmidas/studio': '~1.0.0',
 	'@geekmidas/telescope': '~1.0.0',
 	'@geekmidas/testkit': '~1.0.0',
+	'@geekmidas/cli': CLI_VERSION,
 } as const;
 
 export type GeekmidasPackage = keyof typeof GEEKMIDAS_VERSIONS;

package/src/secrets/__tests__/storage.spec.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import {
 	getSecretsDir,
@@ -56,6 +56,10 @@ describe('file operations', () => {
 		if (existsSync(tempDir)) {
 			await rm(tempDir, { recursive: true });
 		}
+
+		// Clean up keystore directory created at ~/.gkm/{tempDir-basename}
+		const keystoreDir = join(homedir(), '.gkm', basename(tempDir));
+		await rm(keystoreDir, { recursive: true, force: true });
 	});
 
 	describe('writeStageSecrets / readStageSecrets', () => {