@geekmidas/cli 1.10.29 → 1.10.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cli",
-  "version": "1.10.29",
+  "version": "1.10.31",
   "description": "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs",
   "private": false,
   "type": "module",
@@ -56,8 +56,8 @@
     "prompts": "~2.4.2",
     "tsx": "~4.20.3",
     "yaml": "~2.8.2",
-    "@geekmidas/constructs": "~3.0.6",
-    "@geekmidas/envkit": "~1.0.4",
+    "@geekmidas/constructs": "~3.0.7",
+    "@geekmidas/envkit": "~1.0.5",
     "@geekmidas/errors": "~1.0.0",
     "@geekmidas/logger": "~1.0.0",
     "@geekmidas/schema": "~1.0.0"

package/src/__tests__/openapi.spec.ts

@@ -532,319 +532,4 @@ describe('openapiCommand - workspace mode', () => {
 			expect.stringContaining('[api] Generated OpenAPI'),
 		);
 	});
-
-	it('should copy OpenAPI to frontend app with client.output', async () => {
-		// Create workspace structure
-		const apiDir = join(tempDir, 'apps/api');
-		const webDir = join(tempDir, 'apps/web');
-		await mkdir(apiDir, { recursive: true });
-		await mkdir(webDir, { recursive: true });
-
-		// Create endpoint in backend app
-		await createMockEndpointFile(
-			apiDir,
-			'src/endpoints/users.ts',
-			'getUsers',
-			'/users',
-			'GET',
-		);
-
-		// Create workspace config with frontend that depends on backend
-		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 },
-					},
-					web: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/web',
-						port: 3001,
-						dependencies: ['api'],
-						client: {
-							output: './src/api',
-						},
-					},
-				},
-			}),
-		);
-
-		process.chdir(tempDir);
-		const consoleSpy = vi.spyOn(console, 'log');
-
-		await openapiCommand({ cwd: tempDir });
-
-		// Should generate OpenAPI in backend app
-		const backendOutput = join(apiDir, OPENAPI_OUTPUT_PATH);
-		expect(existsSync(backendOutput)).toBe(true);
-
-		// Should copy to frontend app's client output path
-		const frontendOutput = join(webDir, 'src/api/openapi.ts');
-		expect(existsSync(frontendOutput)).toBe(true);
-
-		// Content should be the same
-		const backendContent = await readFile(backendOutput, 'utf-8');
-		const frontendContent = await readFile(frontendOutput, 'utf-8');
-		expect(frontendContent).toBe(backendContent);
-
-		expect(consoleSpy).toHaveBeenCalledWith(
-			expect.stringContaining('[web] ./src/api/openapi.ts'),
-		);
-	});
-
-	it('should only copy to frontend apps that depend on the backend', async () => {
-		// Create workspace structure with multiple apps
-		const apiDir = join(tempDir, 'apps/api');
-		const authDir = join(tempDir, 'apps/auth');
-		const webDir = join(tempDir, 'apps/web');
-		const adminDir = join(tempDir, 'apps/admin');
-		await mkdir(apiDir, { recursive: true });
-		await mkdir(authDir, { recursive: true });
-		await mkdir(webDir, { recursive: true });
-		await mkdir(adminDir, { recursive: true });
-
-		// Create endpoints
-		await createMockEndpointFile(
-			apiDir,
-			'src/endpoints/users.ts',
-			'getUsers',
-			'/users',
-			'GET',
-		);
-		await createMockEndpointFile(
-			authDir,
-			'src/endpoints/login.ts',
-			'login',
-			'/login',
-			'POST',
-		);
-
-		// Create workspace config
-		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 },
-					},
-					auth: {
-						type: 'backend',
-						path: 'apps/auth',
-						port: 3001,
-						routes: './src/endpoints/**/*.ts',
-						openapi: { enabled: true },
-					},
-					web: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/web',
-						port: 3002,
-						dependencies: ['api'], // Only depends on api
-						client: {
-							output: './src/api',
-						},
-					},
-					admin: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/admin',
-						port: 3003,
-						dependencies: ['auth'], // Only depends on auth
-						client: {
-							output: './src/client',
-						},
-					},
-				},
-			}),
-		);
-
-		process.chdir(tempDir);
-
-		await openapiCommand({ cwd: tempDir });
-
-		// Web should have api's OpenAPI (not auth's)
-		const webApiOutput = join(webDir, 'src/api/openapi.ts');
-		expect(existsSync(webApiOutput)).toBe(true);
-		const webContent = await readFile(webApiOutput, 'utf-8');
-		expect(webContent).toContain("'/users'");
-		expect(webContent).not.toContain("'/login'");
-
-		// Admin should have auth's OpenAPI (not api's)
-		const adminClientOutput = join(adminDir, 'src/client/openapi.ts');
-		expect(existsSync(adminClientOutput)).toBe(true);
-		const adminContent = await readFile(adminClientOutput, 'utf-8');
-		expect(adminContent).toContain("'/login'");
-		expect(adminContent).not.toContain("'/users'");
-	});
-
-	it('should not copy to frontend with empty dependencies array', async () => {
-		// Create workspace structure
-		const apiDir = join(tempDir, 'apps/api');
-		const webDir = join(tempDir, 'apps/web');
-		await mkdir(apiDir, { recursive: true });
-		await mkdir(webDir, { recursive: true });
-
-		await createMockEndpointFile(
-			apiDir,
-			'src/endpoints/users.ts',
-			'getUsers',
-			'/users',
-			'GET',
-		);
-
-		// Frontend with empty dependencies array (depends on nothing)
-		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 },
-					},
-					web: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/web',
-						port: 3001,
-						dependencies: [], // Empty array means depends on nothing
-						client: {
-							output: './src/api',
-						},
-					},
-				},
-			}),
-		);
-
-		process.chdir(tempDir);
-
-		await openapiCommand({ cwd: tempDir });
-
-		// Should NOT copy to frontend since it has no dependencies
-		const frontendOutput = join(webDir, 'src/api/openapi.ts');
-		expect(existsSync(frontendOutput)).toBe(false);
-	});
-
-	it('should skip frontend apps without client.output', async () => {
-		const apiDir = join(tempDir, 'apps/api');
-		const webDir = join(tempDir, 'apps/web');
-		await mkdir(apiDir, { recursive: true });
-		await mkdir(webDir, { recursive: true });
-
-		await createMockEndpointFile(
-			apiDir,
-			'src/endpoints/users.ts',
-			'getUsers',
-			'/users',
-			'GET',
-		);
-
-		// Frontend without client.output
-		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 },
-					},
-					web: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/web',
-						port: 3001,
-						dependencies: ['api'],
-						// No client.output configured
-					},
-				},
-			}),
-		);
-
-		process.chdir(tempDir);
-
-		await openapiCommand({ cwd: tempDir });
-
-		// Backend should still have OpenAPI generated
-		expect(existsSync(join(apiDir, OPENAPI_OUTPUT_PATH))).toBe(true);
-
-		// But no files should be created in frontend
-		expect(existsSync(join(webDir, 'src/api/openapi.ts'))).toBe(false);
-	});
-
-	it('should handle nested client.output paths', async () => {
-		const apiDir = join(tempDir, 'apps/api');
-		const webDir = join(tempDir, 'apps/web');
-		await mkdir(apiDir, { recursive: true });
-		await mkdir(webDir, { recursive: true });
-
-		await createMockEndpointFile(
-			apiDir,
-			'src/endpoints/users.ts',
-			'getUsers',
-			'/users',
-			'GET',
-		);
-
-		// Deeply nested client output path
-		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 },
-					},
-					web: {
-						type: 'frontend',
-						framework: 'nextjs',
-						path: 'apps/web',
-						port: 3001,
-						dependencies: ['api'],
-						client: {
-							output: './src/lib/api/generated',
-						},
-					},
-				},
-			}),
-		);
-
-		process.chdir(tempDir);
-
-		await openapiCommand({ cwd: tempDir });
-
-		// Should create nested directories and file
-		const frontendOutput = join(webDir, 'src/lib/api/generated/openapi.ts');
-		expect(existsSync(frontendOutput)).toBe(true);
-
-		const content = await readFile(frontendOutput, 'utf-8');
-		expect(content).toContain('export interface paths');
-	});
 });

package/src/build/__tests__/manifests.spec.ts

@@ -346,6 +346,72 @@ describe('generateServerManifest', () => {
 	});
 });
 
+describe('generateAwsManifest (optional env vars)', () => {
+	itWithDir(
+		'should preserve ? suffix on optional env vars in route environment',
+		async ({ dir }) => {
+			const routes: RouteInfo[] = [
+				{
+					path: '/users',
+					method: 'GET',
+					handler: '.gkm/aws/getUsers.handler',
+					authorizer: 'none',
+					environment: ['DATABASE_URL', 'PORT?', 'LOG_LEVEL?'],
+				},
+			];
+
+			await generateAwsManifest(dir, routes, [], [], []);
+
+			const content = await readFile(join(dir, 'manifest', 'aws.ts'), 'utf-8');
+
+			expect(content).toContain('"DATABASE_URL"');
+			expect(content).toContain('"PORT?"');
+			expect(content).toContain('"LOG_LEVEL?"');
+		},
+	);
+
+	itWithDir(
+		'should preserve ? suffix on optional env vars in function environment',
+		async ({ dir }) => {
+			const functions: FunctionInfo[] = [
+				{
+					name: 'processData',
+					handler: '.gkm/aws/processData.handler',
+					environment: ['DATABASE_URL', 'TIMEOUT?'],
+				},
+			];
+
+			await generateAwsManifest(dir, [], functions, [], []);
+
+			const content = await readFile(join(dir, 'manifest', 'aws.ts'), 'utf-8');
+
+			expect(content).toContain('"DATABASE_URL"');
+			expect(content).toContain('"TIMEOUT?"');
+		},
+	);
+
+	itWithDir(
+		'should preserve ? suffix on optional env vars in subscriber environment',
+		async ({ dir }) => {
+			const subscribers: SubscriberInfo[] = [
+				{
+					name: 'orderHandler',
+					handler: '.gkm/aws/orderHandler.handler',
+					subscribedEvents: ['order.created'],
+					environment: ['DATABASE_URL', 'RETRY_LIMIT?'],
+				},
+			];
+
+			await generateAwsManifest(dir, [], [], [], subscribers);
+
+			const content = await readFile(join(dir, 'manifest', 'aws.ts'), 'utf-8');
+
+			expect(content).toContain('"DATABASE_URL"');
+			expect(content).toContain('"RETRY_LIMIT?"');
+		},
+	);
+});
+
 describe('generateAwsManifest (partitioned)', () => {
 	itWithDir(
 		'should generate manifest with partitioned routes and flat functions',

package/src/build/index.ts

@@ -26,6 +26,7 @@ import {
 	type GeneratedConstruct,
 	SubscriberGenerator,
 } from '../generators';
+import { generateOpenApi, openapiCommand } from '../openapi.js';
 import {
 	type BuildOptions,
 	type BuildResult,
@@ -195,6 +196,26 @@ export async function buildCommand(
 	const rootOutputDir = join(process.cwd(), '.gkm');
 	await mkdir(rootOutputDir, { recursive: true });
 
+	// When --mark-optional is set, sniff env vars from the envParser to determine
+	// which are optional. Optional vars get a `?` suffix in each construct's
+	// environment array (e.g. `PORT?` instead of `PORT`).
+	let optionalVarSet: Set<string> | undefined;
+	if (options.markOptional && config.envParser) {
+		try {
+			const { _sniffEnvParser } = await import('../deploy/sniffer.js');
+			const sniffed = await _sniffEnvParser(
+				config.envParser,
+				process.cwd(),
+				process.cwd(),
+			);
+			if (sniffed.optionalEnvVars.length > 0) {
+				optionalVarSet = new Set(sniffed.optionalEnvVars);
+			}
+		} catch {
+			// Non-fatal — constructs are still built without optional markers
+		}
+	}
+
 	// Build for each provider and generate per-provider manifests
 	let result: BuildResult = {};
 	for (const provider of resolved.providers) {
@@ -213,12 +234,17 @@ export async function buildCommand(
 			resolved.enableOpenApi,
 			options.skipBundle ?? false,
 			options.stage,
+			optionalVarSet,
 		);
 		// Keep the master key from the server provider
 		if (providerResult.masterKey) {
 			result = providerResult;
 		}
 	}
+
+	// Generate OpenAPI spec as part of the build
+	await generateOpenApi(config, { bustCache: true });
+
 	return result;
 }
 
@@ -237,6 +263,7 @@ async function buildForProvider(
 	enableOpenApi: boolean,
 	skipBundle: boolean,
 	stage?: string,
+	optionalVarSet?: Set<string>,
 ): Promise<BuildResult> {
 	const outputDir = join(process.cwd(), '.gkm', provider);
 
@@ -246,7 +273,7 @@ async function buildForProvider(
 	logger.log(`\nGenerating handlers for provider: ${provider}`);
 
 	// Build all constructs in parallel
-	const [routes, functionInfos, cronInfos, subscriberInfos] = await Promise.all(
+	const [rawRoutes, rawFunctions, rawCrons, rawSubscribers] = await Promise.all(
 		[
 			endpointGenerator.build(context, endpoints, outputDir, {
 				provider,
@@ -258,6 +285,29 @@ async function buildForProvider(
 		],
 	);
 
+	// Apply optional marker (`?` suffix) to env vars in each construct's environment
+	const markEnv = optionalVarSet
+		? (vars: string[] | undefined) =>
+				vars?.map((v) => (optionalVarSet.has(v) ? `${v}?` : v))
+		: (vars: string[] | undefined) => vars;
+
+	const routes = rawRoutes.map((r) => ({
+		...r,
+		environment: markEnv(r.environment),
+	}));
+	const functionInfos = rawFunctions.map((f) => ({
+		...f,
+		environment: markEnv(f.environment),
+	}));
+	const cronInfos = rawCrons.map((c) => ({
+		...c,
+		environment: markEnv(c.environment),
+	}));
+	const subscriberInfos = rawSubscribers.map((s) => ({
+		...s,
+		environment: markEnv(s.environment),
+	}));
+
 	logger.log(
 		`Generated ${routes.length} routes, ${functionInfos.length} functions, ${cronInfos.length} crons, ${subscriberInfos.length} subscribers for ${provider}`,
 	);
@@ -472,6 +522,9 @@ export async function workspaceBuildCommand(
 
 		logger.log(`\n✅ Workspace build complete!`);
 
+		// Generate OpenAPI specs and copy to frontend apps
+		await openapiCommand({ cwd: workspace.root });
+
 		// Summary
 		logger.log(`\n📋 Build Summary:`);
 		for (const result of results) {

package/src/deploy/__tests__/__fixtures__/env-parsers/optional-env-parser.ts

@@ -0,0 +1,21 @@
+/**
+ * An envParser fixture that mixes required and optional/default variables.
+ * Used to test the markOptional feature.
+ */
+import type { SnifferEnvironmentParser } from '@geekmidas/envkit/sniffer';
+
+export function envParser(parser: SnifferEnvironmentParser) {
+	return parser.create((get) => ({
+		// Required
+		databaseUrl: get('DATABASE_URL').string(),
+		apiKey: get('API_KEY').string(),
+		// Optional via .optional()
+		logLevel: get('LOG_LEVEL').string().optional(),
+		// Optional via .default()
+		port: get('PORT').string().default('3000'),
+		// Optional via .default() after transform
+		timeout: get('TIMEOUT').string().transform(Number).default(5000),
+	}));
+}
+
+export default envParser;

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

@@ -193,6 +193,126 @@ describe('sniffAppEnvironment', () => {
 			const result = await sniffAppEnvironment(app, 'api', workspacePath);
 
 			expect(result.requiredEnvVars).toEqual([]);
+			expect(result.optionalEnvVars).toEqual([]);
+		});
+	});
+
+	describe('markOptional option', () => {
+		it('returns optionalEnvVars populated from envParser with optional/default vars', async () => {
+			const app = createApp({
+				path: envParserFixturesPath,
+				envParser: './optional-env-parser#envParser',
+			});
+
+			const result = await sniffAppEnvironment(
+				app,
+				'api',
+				envParserFixturesPath,
+				{
+					logWarnings: false,
+				},
+			);
+
+			// All vars present regardless of markOptional
+			expect(result.requiredEnvVars).toContain('DATABASE_URL');
+			expect(result.requiredEnvVars).toContain('API_KEY');
+			expect(result.requiredEnvVars).toContain('LOG_LEVEL');
+			expect(result.requiredEnvVars).toContain('PORT');
+			expect(result.requiredEnvVars).toContain('TIMEOUT');
+
+			// Optional vars populated (no ? suffix since markOptional not set)
+			expect(result.optionalEnvVars).toContain('LOG_LEVEL');
+			expect(result.optionalEnvVars).toContain('PORT');
+			expect(result.optionalEnvVars).toContain('TIMEOUT');
+			expect(result.optionalEnvVars).not.toContain('DATABASE_URL');
+			expect(result.optionalEnvVars).not.toContain('API_KEY');
+		});
+
+		it('suffixes optional vars with ? in requiredEnvVars when markOptional is true', async () => {
+			const app = createApp({
+				path: envParserFixturesPath,
+				envParser: './optional-env-parser#envParser',
+			});
+
+			const result = await sniffAppEnvironment(
+				app,
+				'api',
+				envParserFixturesPath,
+				{
+					logWarnings: false,
+					markOptional: true,
+				},
+			);
+
+			// Required vars unchanged
+			expect(result.requiredEnvVars).toContain('DATABASE_URL');
+			expect(result.requiredEnvVars).toContain('API_KEY');
+
+			// Optional vars suffixed with ?
+			expect(result.requiredEnvVars).toContain('LOG_LEVEL?');
+			expect(result.requiredEnvVars).toContain('PORT?');
+			expect(result.requiredEnvVars).toContain('TIMEOUT?');
+
+			// Plain names not present for optional vars
+			expect(result.requiredEnvVars).not.toContain('LOG_LEVEL');
+			expect(result.requiredEnvVars).not.toContain('PORT');
+			expect(result.requiredEnvVars).not.toContain('TIMEOUT');
+		});
+
+		it('does not add ? suffix when markOptional is false (default)', async () => {
+			const app = createApp({
+				path: envParserFixturesPath,
+				envParser: './optional-env-parser#envParser',
+			});
+
+			const result = await sniffAppEnvironment(
+				app,
+				'api',
+				envParserFixturesPath,
+				{
+					logWarnings: false,
+					markOptional: false,
+				},
+			);
+
+			// No ? suffixes regardless of optionality
+			for (const v of result.requiredEnvVars) {
+				expect(v).not.toMatch(/\?$/);
+			}
+		});
+
+		it('returns empty optionalEnvVars for apps with no optional vars', async () => {
+			const app = createApp({
+				path: envParserFixturesPath,
+				envParser: './valid-env-parser#envParser',
+			});
+
+			const result = await sniffAppEnvironment(
+				app,
+				'api',
+				envParserFixturesPath,
+				{
+					logWarnings: false,
+					markOptional: true,
+				},
+			);
+
+			expect(result.optionalEnvVars).toEqual([]);
+			// No ? suffixes when nothing is optional
+			for (const v of result.requiredEnvVars) {
+				expect(v).not.toMatch(/\?$/);
+			}
+		});
+
+		it('returns empty optionalEnvVars for frontend apps', async () => {
+			const app = createApp({
+				type: 'frontend',
+				dependencies: ['api'],
+			});
+
+			const result = await sniffAppEnvironment(app, 'web', workspacePath);
+
+			expect(result.optionalEnvVars).toEqual([]);
 		});
 	});
 });
@@ -234,16 +354,19 @@ describe('sniffAllApps', () => {
 		expect(results.get('api')).toEqual({
 			appName: 'api',
 			requiredEnvVars: [],
+			optionalEnvVars: [],
 		});
 
 		expect(results.get('auth')).toEqual({
 			appName: 'auth',
 			requiredEnvVars: [],
+			optionalEnvVars: [],
 		});
 
 		expect(results.get('web')).toEqual({
 			appName: 'web',
 			requiredEnvVars: ['NEXT_PUBLIC_API_URL', 'NEXT_PUBLIC_AUTH_URL'],
+			optionalEnvVars: [],
 		});
 	});
 

package/src/deploy/sniffer-worker.ts

@@ -57,9 +57,10 @@ async function sniff(): Promise<void> {
 	// Retrieve captured env vars from the global sniffer
 	const sniffer = globalThis.__envSniffer;
 	const envVars = sniffer ? sniffer.getEnvironmentVariables() : [];
+	const optionalEnvVars = sniffer ? sniffer.getOptionalVariables() : [];
 
 	// Output result as JSON
-	console.log(JSON.stringify({ envVars, error }));
+	console.log(JSON.stringify({ envVars, optionalEnvVars, error }));
 }
 
 // Handle unhandled rejections (fire-and-forget promises)