feat: add VPC CLI flags to create and add commands [2/3] (#425)

tejaskash · web-flow · commit c75f4cd60e4b · 2026-02-24T18:17:16.000-05:00
* feat: add VPC network mode to schema

Fix NetworkModeSchema enum from PUBLIC|PRIVATE to PUBLIC|VPC to match
the AWS API. Add NetworkConfigSchema for subnet and security group
validation, and networkConfig field to AgentEnvSpec with cross-field
validation requiring networkConfig when networkMode is VPC.

Changes:
- Fix NetworkModeSchema enum: PRIVATE → VPC
- Add NetworkConfigSchema (subnet/SG ID regex, min/max array bounds)
- Add networkConfig optional field to AgentEnvSpec
- Add superRefine cross-field validation
- Update LLM-compacted schema documentation
- Add 13 new unit tests for VPC schema validation

* feat: add VPC CLI flags to create and add commands

Add --network-mode, --subnets, and --security-groups flags to both
the create and add agent CLI commands. Extract shared VPC parsing
and validation utilities. Propagate VPC configuration through
GenerateConfig and schema mapper to AgentEnvSpec.

Changes:
- Add shared/vpc-utils.ts with parseCommaSeparatedList and
  validateVpcOptions helpers
- Add VPC fields to GenerateConfig and CreateOptions/AddAgentOptions
- Update schema-mapper to propagate VPC fields to AgentEnvSpec
- Add VPC flags to create command with validation
- Add VPC flags to add agent command with validation
- Update BYO agent path to support VPC configuration
- Add 13 new unit tests for CLI validation and schema mapping
diff --git a/src/cli/commands/add/__tests__/validate.test.ts b/src/cli/commands/add/__tests__/validate.test.ts
@@ -162,6 +162,52 @@ describe('validate', () => {
       expect(validateAddAgentOptions(validAgentOptionsByo)).toEqual({ valid: true });
       expect(validateAddAgentOptions(validAgentOptionsCreate)).toEqual({ valid: true });
     });
+
+    // VPC validation tests
+    it('rejects invalid network mode', () => {
+      const result = validateAddAgentOptions({ ...validAgentOptionsCreate, networkMode: 'INVALID' as any });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Invalid network mode');
+    });
+
+    it('rejects VPC mode without subnets', () => {
+      const result = validateAddAgentOptions({
+        ...validAgentOptionsCreate,
+        networkMode: 'VPC',
+        securityGroups: 'sg-12345678',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--subnets is required');
+    });
+
+    it('rejects VPC mode without security groups', () => {
+      const result = validateAddAgentOptions({
+        ...validAgentOptionsCreate,
+        networkMode: 'VPC',
+        subnets: 'subnet-12345678',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--security-groups is required');
+    });
+
+    it('rejects subnets without VPC mode', () => {
+      const result = validateAddAgentOptions({
+        ...validAgentOptionsCreate,
+        subnets: 'subnet-12345678',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('require --network-mode VPC');
+    });
+
+    it('passes for valid VPC options', () => {
+      const result = validateAddAgentOptions({
+        ...validAgentOptionsCreate,
+        networkMode: 'VPC',
+        subnets: 'subnet-12345678',
+        securityGroups: 'sg-12345678',
+      });
+      expect(result.valid).toBe(true);
+    });
   });
 
   describe('validateAddGatewayOptions', () => {
diff --git a/src/cli/commands/add/actions.ts b/src/cli/commands/add/actions.ts
@@ -7,6 +7,7 @@ import type {
   GatewayAuthorizerType,
   MemoryStrategyType,
   ModelProvider,
+  NetworkMode,
   SDKFramework,
   TargetLanguage,
 } from '../../../schema';
@@ -29,6 +30,7 @@ import { createRenderer } from '../../templates';
 import type { MemoryOption } from '../../tui/screens/generate/types';
 import type { AddGatewayConfig, AddMcpToolConfig } from '../../tui/screens/mcp/types';
 import { DEFAULT_EVENT_EXPIRY } from '../../tui/screens/memory/types';
+import { parseCommaSeparatedList } from '../shared/vpc-utils';
 import type { AddAgentResult, AddGatewayResult, AddIdentityResult, AddMcpToolResult, AddMemoryResult } from './types';
 import { mkdirSync } from 'fs';
 import { dirname, join } from 'path';
@@ -43,6 +45,9 @@ export interface ValidatedAddAgentOptions {
   modelProvider: ModelProvider;
   apiKey?: string;
   memory?: MemoryOption;
+  networkMode?: NetworkMode;
+  subnets?: string;
+  securityGroups?: string;
   codeLocation?: string;
   entrypoint?: string;
 }
@@ -120,6 +125,9 @@ async function handleCreatePath(options: ValidatedAddAgentOptions, configBaseDir
     modelProvider: options.modelProvider,
     memory: options.memory!,
     language: options.language,
+    networkMode: options.networkMode,
+    subnets: parseCommaSeparatedList(options.subnets),
+    securityGroups: parseCommaSeparatedList(options.securityGroups),
   };
 
   const agentPath = join(projectRoot, APP_DIR, options.name);
@@ -186,14 +194,23 @@ async function handleByoPath(
 
   const project = await configIO.readProjectSpec();
 
+  const networkMode = options.networkMode ?? 'PUBLIC';
   const agent: AgentEnvSpec = {
     type: 'AgentCoreRuntime',
     name: options.name,
     build: options.buildType,
     entrypoint: (options.entrypoint ?? 'main.py') as FilePath,
     codeLocation: codeLocation as DirectoryPath,
     runtimeVersion: 'PYTHON_3_12',
-    networkMode: 'PUBLIC',
+    networkMode,
+    ...(networkMode === 'VPC' && options.subnets && options.securityGroups
+      ? {
+          networkConfig: {
+            subnets: parseCommaSeparatedList(options.subnets)!,
+            securityGroups: parseCommaSeparatedList(options.securityGroups)!,
+          },
+        }
+      : {}),
   };
 
   project.agents.push(agent);
diff --git a/src/cli/commands/add/command.tsx b/src/cli/commands/add/command.tsx
@@ -40,6 +40,9 @@ async function handleAddAgentCLI(options: AddAgentOptions): Promise<void> {
     modelProvider: options.modelProvider!,
     apiKey: options.apiKey,
     memory: options.memory,
+    networkMode: options.networkMode,
+    subnets: options.subnets,
+    securityGroups: options.securityGroups,
     codeLocation: options.codeLocation,
     entrypoint: options.entrypoint,
   });
@@ -227,6 +230,9 @@ export function registerAdd(program: Command) {
     .option('--model-provider <provider>', 'Model provider: Bedrock, Anthropic, OpenAI, Gemini [non-interactive]')
     .option('--api-key <key>', 'API key for non-Bedrock providers [non-interactive]')
     .option('--memory <mem>', 'Memory: none, shortTerm, longAndShortTerm (create path only) [non-interactive]')
+    .option('--network-mode <mode>', 'Network mode: PUBLIC or VPC (default: PUBLIC) [non-interactive]')
+    .option('--subnets <ids>', 'Comma-separated subnet IDs (required for VPC mode) [non-interactive]')
+    .option('--security-groups <ids>', 'Comma-separated security group IDs (required for VPC mode) [non-interactive]')
     .option('--code-location <path>', 'Path to existing code (BYO path only) [non-interactive]')
     .option('--entrypoint <file>', 'Entry file relative to code-location (BYO, default: main.py) [non-interactive]')
     .option('--json', 'Output as JSON [non-interactive]')
diff --git a/src/cli/commands/add/types.ts b/src/cli/commands/add/types.ts
@@ -1,4 +1,4 @@
-import type { GatewayAuthorizerType, ModelProvider, SDKFramework, TargetLanguage } from '../../../schema';
+import type { GatewayAuthorizerType, ModelProvider, NetworkMode, SDKFramework, TargetLanguage } from '../../../schema';
 import type { MemoryOption } from '../../tui/screens/generate/types';
 
 // Agent types
@@ -11,6 +11,9 @@ export interface AddAgentOptions {
   modelProvider?: ModelProvider;
   apiKey?: string;
   memory?: MemoryOption;
+  networkMode?: NetworkMode;
+  subnets?: string;
+  securityGroups?: string;
   codeLocation?: string;
   entrypoint?: string;
   json?: boolean;
diff --git a/src/cli/commands/add/validate.ts b/src/cli/commands/add/validate.ts
@@ -7,6 +7,7 @@ import {
   TargetLanguageSchema,
   getSupportedModelProviders,
 } from '../../../schema';
+import { validateVpcOptions } from '../shared/vpc-utils';
 import type {
   AddAgentOptions,
   AddGatewayOptions,
@@ -102,6 +103,9 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes
     }
   }
 
+  const vpcResult = validateVpcOptions(options);
+  if (!vpcResult.valid) return vpcResult;
+
   return { valid: true };
 }
 
diff --git a/src/cli/commands/create/__tests__/validate.test.ts b/src/cli/commands/create/__tests__/validate.test.ts
@@ -132,6 +132,90 @@ describe('validateCreateOptions', () => {
     expect(result.valid).toBe(true);
   });
 
+  // VPC validation tests
+  it('rejects invalid network mode', () => {
+    const result = validateCreateOptions(
+      {
+        name: 'VpcTest1',
+        language: 'Python',
+        framework: 'Strands',
+        modelProvider: 'Bedrock',
+        memory: 'none',
+        networkMode: 'INVALID',
+      },
+      testDir
+    );
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('Invalid network mode');
+  });
+
+  it('rejects VPC mode without subnets', () => {
+    const result = validateCreateOptions(
+      {
+        name: 'VpcTest2',
+        language: 'Python',
+        framework: 'Strands',
+        modelProvider: 'Bedrock',
+        memory: 'none',
+        networkMode: 'VPC',
+        securityGroups: 'sg-12345678',
+      },
+      testDir
+    );
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('--subnets is required');
+  });
+
+  it('rejects VPC mode without security groups', () => {
+    const result = validateCreateOptions(
+      {
+        name: 'VpcTest3',
+        language: 'Python',
+        framework: 'Strands',
+        modelProvider: 'Bedrock',
+        memory: 'none',
+        networkMode: 'VPC',
+        subnets: 'subnet-12345678',
+      },
+      testDir
+    );
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('--security-groups is required');
+  });
+
+  it('rejects subnets without VPC mode', () => {
+    const result = validateCreateOptions(
+      {
+        name: 'VpcTest4',
+        language: 'Python',
+        framework: 'Strands',
+        modelProvider: 'Bedrock',
+        memory: 'none',
+        subnets: 'subnet-12345678',
+      },
+      testDir
+    );
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('require --network-mode VPC');
+  });
+
+  it('returns valid with VPC mode and required options', () => {
+    const result = validateCreateOptions(
+      {
+        name: 'VpcTest5',
+        language: 'Python',
+        framework: 'Strands',
+        modelProvider: 'Bedrock',
+        memory: 'none',
+        networkMode: 'VPC',
+        subnets: 'subnet-12345678',
+        securityGroups: 'sg-12345678',
+      },
+      testDir
+    );
+    expect(result.valid).toBe(true);
+  });
+
   it('returns invalid for unsupported framework/model combination', () => {
     // GoogleADK only supports certain providers, not all
     const result = validateCreateOptions(
diff --git a/src/cli/commands/create/action.ts b/src/cli/commands/create/action.ts
@@ -4,6 +4,7 @@ import type {
   BuildType,
   DeployedState,
   ModelProvider,
+  NetworkMode,
   SDKFramework,
   TargetLanguage,
 } from '../../../schema';
@@ -120,6 +121,9 @@ export interface CreateWithAgentOptions {
   modelProvider: ModelProvider;
   apiKey?: string;
   memory: MemoryOption;
+  networkMode?: NetworkMode;
+  subnets?: string[];
+  securityGroups?: string[];
   skipGit?: boolean;
   skipPythonSetup?: boolean;
   onProgress?: ProgressCallback;
@@ -135,6 +139,9 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
     modelProvider,
     apiKey,
     memory,
+    networkMode,
+    subnets,
+    securityGroups,
     skipGit,
     skipPythonSetup,
     onProgress,
@@ -172,6 +179,9 @@ export async function createProjectWithAgent(options: CreateWithAgentOptions): P
       apiKey,
       memory,
       language,
+      networkMode,
+      subnets,
+      securityGroups,
     };
 
     // Resolve credential strategy FIRST (new project has no existing credentials)
diff --git a/src/cli/commands/create/command.tsx b/src/cli/commands/create/command.tsx
@@ -1,8 +1,9 @@
 import { getWorkingDirectory } from '../../../lib';
-import type { BuildType, ModelProvider, SDKFramework, TargetLanguage } from '../../../schema';
+import type { BuildType, ModelProvider, NetworkMode, SDKFramework, TargetLanguage } from '../../../schema';
 import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { CreateScreen } from '../../tui/screens/create';
+import { parseCommaSeparatedList } from '../shared/vpc-utils';
 import { type ProgressCallback, createProject, createProjectWithAgent, getDryRunInfo } from './action';
 import type { CreateOptions } from './types';
 import { validateCreateOptions } from './validate';
@@ -120,6 +121,9 @@ async function handleCreateCLI(options: CreateOptions): Promise<void> {
         modelProvider: options.modelProvider as ModelProvider,
         apiKey: options.apiKey,
         memory: options.memory as 'none' | 'shortTerm' | 'longAndShortTerm',
+        networkMode: options.networkMode as NetworkMode | undefined,
+        subnets: parseCommaSeparatedList(options.subnets),
+        securityGroups: parseCommaSeparatedList(options.securityGroups),
         skipGit: options.skipGit,
         skipPythonSetup: options.skipPythonSetup,
         onProgress,
@@ -152,6 +156,9 @@ export const registerCreate = (program: Command) => {
     .option('--model-provider <provider>', 'Model provider (Bedrock, Anthropic, OpenAI, Gemini) [non-interactive]')
     .option('--api-key <key>', 'API key for non-Bedrock providers [non-interactive]')
     .option('--memory <option>', 'Memory option (none, shortTerm, longAndShortTerm) [non-interactive]')
+    .option('--network-mode <mode>', 'Network mode: PUBLIC or VPC (default: PUBLIC) [non-interactive]')
+    .option('--subnets <ids>', 'Comma-separated subnet IDs (required for VPC mode) [non-interactive]')
+    .option('--security-groups <ids>', 'Comma-separated security group IDs (required for VPC mode) [non-interactive]')
     .option('--output-dir <dir>', 'Output directory (default: current directory) [non-interactive]')
     .option('--skip-git', 'Skip git repository initialization [non-interactive]')
     .option('--skip-python-setup', 'Skip Python virtual environment setup [non-interactive]')
@@ -179,6 +186,9 @@ export const registerCreate = (program: Command) => {
           options.modelProvider ??
           options.apiKey ??
           options.memory ??
+          options.networkMode ??
+          options.subnets ??
+          options.securityGroups ??
           options.outputDir ??
           options.skipGit ??
           options.skipPythonSetup ??
diff --git a/src/cli/commands/create/types.ts b/src/cli/commands/create/types.ts
@@ -8,6 +8,9 @@ export interface CreateOptions {
   modelProvider?: string;
   apiKey?: string;
   memory?: string;
+  networkMode?: string;
+  subnets?: string;
+  securityGroups?: string;
   outputDir?: string;
   skipGit?: boolean;
   skipPythonSetup?: boolean;
diff --git a/src/cli/commands/create/validate.ts b/src/cli/commands/create/validate.ts
@@ -6,6 +6,7 @@ import {
   TargetLanguageSchema,
   getSupportedModelProviders,
 } from '../../../schema';
+import { validateVpcOptions } from '../shared/vpc-utils';
 import type { CreateOptions } from './types';
 import { existsSync } from 'fs';
 import { join } from 'path';
@@ -121,5 +122,8 @@ export function validateCreateOptions(options: CreateOptions, cwd?: string): Val
     }
   }
 
+  const vpcResult = validateVpcOptions(options);
+  if (!vpcResult.valid) return vpcResult;
+
   return { valid: true };
 }
diff --git a/src/cli/commands/shared/vpc-utils.ts b/src/cli/commands/shared/vpc-utils.ts
diff --git a/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts b/src/cli/operations/agent/generate/__tests__/schema-mapper.test.ts
diff --git a/src/cli/operations/agent/generate/schema-mapper.ts b/src/cli/operations/agent/generate/schema-mapper.ts
diff --git a/src/cli/tui/screens/generate/types.ts b/src/cli/tui/screens/generate/types.ts

Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,7 @@ import {`
`7`	`7`	`TargetLanguageSchema,`
`8`	`8`	`getSupportedModelProviders,`
`9`	`9`	`} from '../../../schema';`
	`10`	`+import { validateVpcOptions } from '../shared/vpc-utils';`
`10`	`11`	`import type {`
`11`	`12`	`AddAgentOptions,`
`12`	`13`	`AddGatewayOptions,`
`@@ -102,6 +103,9 @@ export function validateAddAgentOptions(options: AddAgentOptions): ValidationRes`
`102`	`103`	`}`
`103`	`104`	`}`
`104`	`105`
	`106`	`+ const vpcResult = validateVpcOptions(options);`
	`107`	`+ if (!vpcResult.valid) return vpcResult;`
	`108`	`+`
`105`	`109`	`return { valid: true };`
`106`	`110`	`}`
`107`	`111`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ import {`
`6`	`6`	`TargetLanguageSchema,`
`7`	`7`	`getSupportedModelProviders,`
`8`	`8`	`} from '../../../schema';`
	`9`	`+import { validateVpcOptions } from '../shared/vpc-utils';`
`9`	`10`	`import type { CreateOptions } from './types';`
`10`	`11`	`import { existsSync } from 'fs';`
`11`	`12`	`import { join } from 'path';`
`@@ -121,5 +122,8 @@ export function validateCreateOptions(options: CreateOptions, cwd?: string): Val`
`121`	`122`	`}`
`122`	`123`	`}`
`123`	`124`
	`125`	`+ const vpcResult = validateVpcOptions(options);`
	`126`	`+ if (!vpcResult.valid) return vpcResult;`
	`127`	`+`
`124`	`128`	`return { valid: true };`
`125`	`129`	`}`