@geekmidas/cli 0.54.0 → 1.0.1

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}`,
+			}),
+		);
+	}
+}

package/src/deploy/StateProvider.ts

@@ -0,0 +1,171 @@
+/**
+ * State Provider Interface
+ *
+ * Abstracts the storage backend for deployment state.
+ * Built-in providers: LocalStateProvider, SSMStateProvider
+ * Users can also supply custom implementations.
+ */
+
+import type { DokployStageState } from './state';
+
+/**
+ * Interface for deployment state storage providers.
+ *
+ * Implementations must handle:
+ * - Reading state for a stage (returns null if not found)
+ * - Writing state for a stage (creates or updates)
+ */
+export interface StateProvider {
+	/**
+	 * Read deployment state for a stage.
+	 *
+	 * @param stage - The deployment stage (e.g., 'development', 'production')
+	 * @returns The state object or null if not found
+	 */
+	read(stage: string): Promise<DokployStageState | null>;
+
+	/**
+	 * Write deployment state for a stage.
+	 *
+	 * @param stage - The deployment stage
+	 * @param state - The state object to persist
+	 */
+	write(stage: string, state: DokployStageState): Promise<void>;
+}
+
+/**
+ * Valid AWS regions.
+ */
+export type AwsRegion =
+	| 'us-east-1'
+	| 'us-east-2'
+	| 'us-west-1'
+	| 'us-west-2'
+	| 'af-south-1'
+	| 'ap-east-1'
+	| 'ap-south-1'
+	| 'ap-south-2'
+	| 'ap-southeast-1'
+	| 'ap-southeast-2'
+	| 'ap-southeast-3'
+	| 'ap-southeast-4'
+	| 'ap-northeast-1'
+	| 'ap-northeast-2'
+	| 'ap-northeast-3'
+	| 'ca-central-1'
+	| 'eu-central-1'
+	| 'eu-central-2'
+	| 'eu-west-1'
+	| 'eu-west-2'
+	| 'eu-west-3'
+	| 'eu-south-1'
+	| 'eu-south-2'
+	| 'eu-north-1'
+	| 'me-south-1'
+	| 'me-central-1'
+	| 'sa-east-1';
+
+/**
+ * Local state provider config.
+ */
+export interface LocalStateConfig {
+	provider: 'local';
+}
+
+/**
+ * SSM state provider config (requires region).
+ */
+export interface SSMStateConfig {
+	provider: 'ssm';
+	/** AWS region (required for SSM provider) */
+	region: AwsRegion;
+}
+
+/**
+ * Custom state provider config.
+ */
+export interface CustomStateConfig {
+	/** Custom StateProvider implementation */
+	provider: StateProvider;
+}
+
+/**
+ * State configuration types.
+ */
+export type StateConfig = LocalStateConfig | SSMStateConfig | CustomStateConfig;
+
+/**
+ * Check if value is a StateProvider implementation.
+ */
+export function isStateProvider(value: unknown): value is StateProvider {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		typeof (value as StateProvider).read === 'function' &&
+		typeof (value as StateProvider).write === 'function'
+	);
+}
+
+export interface CreateStateProviderOptions {
+	/** State config from workspace */
+	config?: StateConfig;
+	/** Workspace root directory (for local provider) */
+	workspaceRoot: string;
+	/** Workspace name (for SSM parameter path) */
+	workspaceName: string;
+}
+
+/**
+ * Create a state provider based on configuration.
+ *
+ * - 'local': LocalStateProvider (default)
+ * - 'ssm': CachedStateProvider with SSM as source of truth
+ * - Custom: Use provided StateProvider implementation
+ */
+export async function createStateProvider(
+	options: CreateStateProviderOptions,
+): Promise<StateProvider> {
+	const { config, workspaceRoot, workspaceName } = options;
+
+	// Default to local provider if no config
+	if (!config) {
+		const { LocalStateProvider } = await import('./LocalStateProvider');
+		return new LocalStateProvider(workspaceRoot);
+	}
+
+	// Custom provider implementation
+	if (isStateProvider(config.provider)) {
+		return config.provider;
+	}
+
+	// Built-in providers (discriminated by provider string)
+	const provider = config.provider;
+
+	if (provider === 'local') {
+		const { LocalStateProvider } = await import('./LocalStateProvider');
+		return new LocalStateProvider(workspaceRoot);
+	}
+
+	if (provider === 'ssm') {
+		if (!workspaceName) {
+			throw new Error(
+				'Workspace name is required for SSM state provider. Set "name" in gkm.config.ts.',
+			);
+		}
+
+		const { LocalStateProvider } = await import('./LocalStateProvider');
+		const { SSMStateProvider } = await import('./SSMStateProvider');
+		const { CachedStateProvider } = await import('./CachedStateProvider');
+
+		const local = new LocalStateProvider(workspaceRoot);
+		const ssm = new SSMStateProvider({
+			workspaceName,
+			region: (config as SSMStateConfig).region,
+		});
+
+		return new CachedStateProvider(ssm, local);
+	}
+
+	// Should never reach here - custom providers handled above
+	throw new Error(`Unknown state provider: ${JSON.stringify(config)}`);
+}

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

@@ -0,0 +1,228 @@
+import { describe, expect, it } from 'vitest';
+import { CachedStateProvider } from '../CachedStateProvider';
+import type { StateProvider } from '../StateProvider';
+import type { DokployStageState } from '../state';
+
+const createMockProvider = (): StateProvider & {
+	readCalls: string[];
+	writeCalls: Array<{ stage: string; state: DokployStageState }>;
+	storage: Map<string, DokployStageState>;
+} => {
+	const storage = new Map<string, DokployStageState>();
+	const readCalls: string[] = [];
+	const writeCalls: Array<{ stage: string; state: DokployStageState }> = [];
+
+	return {
+		storage,
+		readCalls,
+		writeCalls,
+		async read(stage: string): Promise<DokployStageState | null> {
+			readCalls.push(stage);
+			return storage.get(stage) ?? null;
+		},
+		async write(stage: string, state: DokployStageState): Promise<void> {
+			writeCalls.push({ stage, state });
+			storage.set(stage, { ...state });
+		},
+	};
+};
+
+describe('CachedStateProvider', () => {
+	describe('read', () => {
+		it('should return local state if available', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const state: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'local_app' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+			local.storage.set('production', state);
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.read('production');
+
+			expect(result).toEqual(state);
+			expect(local.readCalls).toEqual(['production']);
+			expect(remote.readCalls).toEqual([]);
+		});
+
+		it('should fetch from remote and cache locally if local missing', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const state: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'remote_app' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+			remote.storage.set('production', state);
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.read('production');
+
+			expect(result).toEqual(state);
+			expect(local.readCalls).toEqual(['production']);
+			expect(remote.readCalls).toEqual(['production']);
+			expect(local.writeCalls.length).toBe(1);
+			expect(local.writeCalls[0].stage).toBe('production');
+		});
+
+		it('should return null if both local and remote are empty', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.read('nonexistent');
+
+			expect(result).toBeNull();
+			expect(local.readCalls).toEqual(['nonexistent']);
+			expect(remote.readCalls).toEqual(['nonexistent']);
+		});
+	});
+
+	describe('write', () => {
+		it('should write to both remote and local', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const state: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'app_123' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+
+			const cached = new CachedStateProvider(remote, local);
+			await cached.write('production', state);
+
+			expect(remote.writeCalls.length).toBe(1);
+			expect(remote.writeCalls[0].stage).toBe('production');
+			expect(local.writeCalls.length).toBe(1);
+			expect(local.writeCalls[0].stage).toBe('production');
+		});
+	});
+
+	describe('pull', () => {
+		it('should fetch from remote and update local', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const remoteState: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'remote_app' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+			remote.storage.set('production', remoteState);
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.pull('production');
+
+			expect(result).toEqual(remoteState);
+			expect(remote.readCalls).toEqual(['production']);
+			expect(local.writeCalls.length).toBe(1);
+		});
+
+		it('should return null if remote is empty', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.pull('nonexistent');
+
+			expect(result).toBeNull();
+			expect(local.writeCalls.length).toBe(0);
+		});
+	});
+
+	describe('push', () => {
+		it('should push local state to remote', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const localState: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'local_app' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+			local.storage.set('production', localState);
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.push('production');
+
+			expect(result).toEqual(localState);
+			expect(local.readCalls).toEqual(['production']);
+			expect(remote.writeCalls.length).toBe(1);
+		});
+
+		it('should return null if local is empty', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.push('nonexistent');
+
+			expect(result).toBeNull();
+			expect(remote.writeCalls.length).toBe(0);
+		});
+	});
+
+	describe('diff', () => {
+		it('should return both local and remote state', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const localState: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'local_app' },
+				services: {},
+				lastDeployedAt: '2024-01-01T00:00:00.000Z',
+			};
+			const remoteState: DokployStageState = {
+				provider: 'dokploy',
+				stage: 'production',
+				environmentId: 'env_123',
+				applications: { api: 'remote_app' },
+				services: {},
+				lastDeployedAt: '2024-01-02T00:00:00.000Z',
+			};
+
+			local.storage.set('production', localState);
+			remote.storage.set('production', remoteState);
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.diff('production');
+
+			expect(result.local).toEqual(localState);
+			expect(result.remote).toEqual(remoteState);
+		});
+
+		it('should handle missing states', async () => {
+			const local = createMockProvider();
+			const remote = createMockProvider();
+
+			const cached = new CachedStateProvider(remote, local);
+			const result = await cached.diff('nonexistent');
+
+			expect(result.local).toBeNull();
+			expect(result.remote).toBeNull();
+		});
+	});
+});