feat: multi-environment-deploy

src/cli/commands/deploy/__tests__/handleEnvDeploy.flags.test.ts

@@ -0,0 +1,72 @@
+import type { DeployToTargetsOptions } from '../../../operations/deploy/multi-target';
+import { handleEnvDeploy } from '../actions';
+import { describe, expect, it, vi } from 'vitest';
+
+// Capture every call to deployToTargets so we can assert the orchestrator
+// observes the parallel / continueOnError flags forwarded by handleEnvDeploy.
+const deployToTargetsMock = vi.fn((_targets: unknown, _options: DeployToTargetsOptions, _fn: unknown) =>
+  Promise.resolve({ successes: [], failures: [] })
+);
+
+vi.mock('../../../operations/deploy/multi-target', () => ({
+  deployToTargets: (targets: unknown, options: DeployToTargetsOptions, fn: unknown) =>
+    deployToTargetsMock(targets, options, fn),
+}));
+
+// Stub heavy ConfigIO + project operations so we never touch a real project.
+vi.mock('../../../../lib', () => ({
+  ConfigIO: class {
+    readAwsTargetsFull() {
+      return Promise.resolve({
+        targets: [{ name: 'dev-a', account: '111111111111', region: 'us-west-2' }],
+        environments: { dev: { targets: ['dev-a'] } },
+      });
+    }
+    resolveAWSDeploymentTargets() {
+      return Promise.resolve([{ name: 'dev-a', account: '111111111111', region: 'us-west-2' }]);
+    }
+  },
+  SecureCredentials: class {},
+}));
+
+vi.mock('../../../operations/deploy', () => ({
+  bootstrapEnvironment: vi.fn(),
+  buildCdkProject: vi.fn(),
+  checkBootstrapNeeded: vi.fn(),
+  checkStackDeployability: vi.fn(),
+  getAllCredentials: () => [],
+  hasIdentityApiProviders: () => false,
+  hasIdentityOAuthProviders: () => false,
+  performStackTeardown: vi.fn(),
+  setupApiKeyProviders: vi.fn(),
+  setupOAuth2Providers: vi.fn(),
+  setupTransactionSearch: vi.fn(),
+  synthesizeCdk: vi.fn(),
+  validateProject: vi.fn(),
+}));
+
+describe('handleEnvDeploy flag forwarding', () => {
+  it('forwards parallel + continueOnError to deployToTargets', async () => {
+    deployToTargetsMock.mockClear();
+    await handleEnvDeploy({
+      env: 'dev',
+      parallel: true,
+      continueOnError: true,
+      onLog: () => undefined,
+    });
+    expect(deployToTargetsMock).toHaveBeenCalledTimes(1);
+    const opts = deployToTargetsMock.mock.calls[0]![1];
+    expect(opts.environmentName).toBe('dev');
+    expect(opts.parallel).toBe(true);
+    expect(opts.continueOnError).toBe(true);
+  });
+
+  it('defaults parallel + continueOnError to undefined when not provided', async () => {
+    deployToTargetsMock.mockClear();
+    await handleEnvDeploy({ env: 'dev', onLog: () => undefined });
+    expect(deployToTargetsMock).toHaveBeenCalledTimes(1);
+    const opts = deployToTargetsMock.mock.calls[0]![1];
+    expect(opts.parallel).toBeUndefined();
+    expect(opts.continueOnError).toBeUndefined();
+  });
+});

src/cli/commands/deploy/__tests__/validate.test.ts

@@ -2,15 +2,45 @@ import { validateDeployOptions } from '../validate.js';
 import { describe, expect, it } from 'vitest';
 
 describe('validateDeployOptions', () => {
-  it('always returns valid', () => {
+  it('returns valid with no options', () => {
     expect(validateDeployOptions({})).toEqual({ valid: true });
   });
 
-  it('returns valid with all options set', () => {
+  it('returns valid with all non-conflicting options set', () => {
     expect(validateDeployOptions({ target: 'prod', yes: true, verbose: true, json: true })).toEqual({ valid: true });
   });
 
   it('returns valid with target only', () => {
     expect(validateDeployOptions({ target: 'default' })).toEqual({ valid: true });
   });
+
+  it('returns valid with --env only', () => {
+    expect(validateDeployOptions({ env: 'dev' })).toEqual({ valid: true });
+  });
+
+  it('rejects --env and --target used together with a clear error', () => {
+    const result = validateDeployOptions({ env: 'dev', target: 'prod' });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/--env.*--target/);
+  });
+
+  it('rejects --parallel without --env', () => {
+    const result = validateDeployOptions({ parallel: true });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/--parallel.*--env/);
+  });
+
+  it('rejects --continue-on-error without --env', () => {
+    const result = validateDeployOptions({ continueOnError: true });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/--continue-on-error.*--env/);
+  });
+
+  it('accepts --parallel together with --env', () => {
+    expect(validateDeployOptions({ env: 'dev', parallel: true })).toEqual({ valid: true });
+  });
+
+  it('accepts --continue-on-error together with --env', () => {
+    expect(validateDeployOptions({ env: 'dev', continueOnError: true })).toEqual({ valid: true });
+  });
 });

src/cli/commands/deploy/actions.ts

@@ -1,5 +1,11 @@
 import { ConfigIO, SecureCredentials } from '../../../lib';
-import type { AgentCoreMcpSpec, DeployedState } from '../../../schema';
+import type {
+  AgentCoreMcpSpec,
+  AwsDeploymentTarget,
+  DeployedState,
+  EnvironmentOverrides,
+  Environments,
+} from '../../../schema';
 import { applyTargetRegionToEnv } from '../../aws';
 import { validateAwsCredentials } from '../../aws/account';
 import { CdkToolkitWrapper, createSwitchableIoHost } from '../../cdk/toolkit-lib';
@@ -33,7 +39,9 @@ import {
   synthesizeCdk,
   validateProject,
 } from '../../operations/deploy';
+import { mergeOverrides, resolveEnvironment } from '../../operations/deploy/environment';
 import { formatTargetStatus, getGatewayTargetStatuses } from '../../operations/deploy/gateway-status';
+import { deployToTargets } from '../../operations/deploy/multi-target';
 import { deleteOrphanedABTests, setupABTests } from '../../operations/deploy/post-deploy-ab-tests';
 import {
   resolveConfigBundleComponentKeys,
@@ -51,6 +59,12 @@ export interface ValidatedDeployOptions {
   verbose?: boolean;
   plan?: boolean;
   diff?: boolean;
+  /**
+   * Optional env-var overrides applied in-memory to every runtime in the
+   * loaded project spec just before CDK synth. Set by --env deploys; never
+   * persisted to disk.
+   */
+  envVarOverrides?: EnvironmentOverrides;
   onProgress?: (step: string, status: 'start' | 'success' | 'error') => void;
   onResourceEvent?: (message: string) => void;
 }
@@ -142,6 +156,13 @@ export async function handleDeploy(options: ValidatedDeployOptions): Promise<Dep
     // Preflight: validate project
     startStep('Validate project');
     const context = await validateProject();
+    // Apply per-environment envVar overrides (in-memory only) before synth.
+    if (options.envVarOverrides && context.projectSpec.runtimes) {
+      context.projectSpec = {
+        ...context.projectSpec,
+        runtimes: context.projectSpec.runtimes.map(rt => mergeOverrides(rt, options.envVarOverrides)),
+      };
+    }
     endStep('success');
 
     // Teardown confirmation: if this is a teardown deploy, require --yes
@@ -705,3 +726,106 @@ export async function handleDeploy(options: ValidatedDeployOptions): Promise<Dep
  */
 // resolveConfigBundleComponentKeys and resolveComponentKey moved to
 // src/cli/operations/deploy/post-deploy-config-bundles.ts
+
+export interface EnvDeployOptions {
+  env: string;
+  autoConfirm?: boolean;
+  verbose?: boolean;
+  plan?: boolean;
+  diff?: boolean;
+  /** Run env targets concurrently via Promise.allSettled. */
+  parallel?: boolean;
+  /** Continue past per-target failures (sequential mode only). */
+  continueOnError?: boolean;
+  onProgress?: (step: string, status: 'start' | 'success' | 'error') => void;
+  onResourceEvent?: (message: string) => void;
+  /** Sink for orchestrator progress + summary lines. Defaults to console.log. */
+  onLog?: (line: string) => void;
+}
+
+export interface EnvDeployResult {
+  success: boolean;
+  envName: string;
+  results: DeployResult[];
+  /** Set when the env couldn't be resolved (no per-target results available). */
+  error?: string;
+}
+
+/**
+ * Read aws-targets.json supporting both the legacy array shape and the new
+ * `{ targets, environments }` object shape. Returns environments only when
+ * the file uses the object shape; otherwise environments is undefined.
+ */
+/**
+ * Read aws-targets.json with environments if present. Delegates to
+ * `ConfigIO.readAwsTargetsFull` and then applies region fallback so the same
+ * environment/profile precedence used by the rest of the CLI is honored.
+ */
+async function readAwsTargetsWithEnvironments(
+  configIO: ConfigIO
+): Promise<{ targets: AwsDeploymentTarget[]; environments?: Environments }> {
+  const full = await configIO.readAwsTargetsFull();
+  // Apply the standard region fallback (env vars / profile config) by going
+  // through resolveAWSDeploymentTargets — its result preserves saved regions
+  // and fills in only blanks, so we can safely substitute it for the targets
+  // we just read while keeping the environments map from the object shape.
+  const resolved = await configIO.resolveAWSDeploymentTargets();
+  return full.environments ? { targets: resolved, environments: full.environments } : { targets: resolved };
+}
+
+/**
+ * Deploy a named environment: resolve the env to its targets, apply any
+ * env-level overrides per target, and run them through the multi-target
+ * orchestrator. Sequential / fail-fast for v1 (T9 adds parallel + continue-on-error).
+ */
+export async function handleEnvDeploy(options: EnvDeployOptions): Promise<EnvDeployResult> {
+  const configIO = new ConfigIO();
+
+  let resolved;
+  try {
+    const awsTargets = await readAwsTargetsWithEnvironments(configIO);
+    resolved = resolveEnvironment(options.env, awsTargets);
+  } catch (err: unknown) {
+    return {
+      success: false,
+      envName: options.env,
+      results: [],
+      error: getErrorMessage(err),
+    };
+  }
+
+  const results: DeployResult[] = [];
+  const aggregate = await deployToTargets(
+    resolved.targets,
+    {
+      environmentName: options.env,
+      parallel: options.parallel,
+      continueOnError: options.continueOnError,
+      log: options.onLog,
+    },
+    async target => {
+      const result = await handleDeploy({
+        target: target.name,
+        autoConfirm: options.autoConfirm,
+        verbose: options.verbose,
+        plan: options.plan,
+        diff: options.diff,
+        envVarOverrides: resolved.overrides,
+        onProgress: options.onProgress,
+        onResourceEvent: options.onResourceEvent,
+      });
+      results.push(result);
+      if (!result.success) {
+        // Throw so the orchestrator records this as a failure (fail-fast).
+        throw new Error(result.error ?? `Deploy failed for target ${target.name}`);
+      }
+      return result;
+    }
+  );
+
+  return {
+    success: aggregate.failures.length === 0 && results.every(r => r.success),
+    envName: options.env,
+    results,
+  };
+}

src/cli/commands/deploy/command.tsx

@@ -2,7 +2,7 @@ import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject, requireTTY } from '../../tui/guards';
 import { DeployScreen } from '../../tui/screens/deploy/DeployScreen';
-import { handleDeploy } from './actions';
+import { handleDeploy, handleEnvDeploy } from './actions';
 import type { DeployOptions } from './types';
 import { validateDeployOptions } from './validate';
 import type { Command } from '@commander-js/extra-typings';
@@ -69,6 +69,34 @@ async function handleDeployCLI(options: DeployOptions): Promise<void> {
       }
     : undefined;
 
+  if (options.env) {
+    const envResult = await handleEnvDeploy({
+      env: options.env,
+      autoConfirm: options.yes,
+      verbose: options.verbose ?? options.diff,
+      plan: options.plan,
+      diff: options.diff,
+      parallel: options.parallel,
+      continueOnError: options.continueOnError,
+      onProgress,
+      onResourceEvent,
+      onLog: line => console.log(line),
+    });
+
+    if (spinner) {
+      clearInterval(spinner);
+      process.stdout.write('\r\x1b[K');
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(envResult));
+    } else if (!envResult.success) {
+      if (envResult.error) console.error(envResult.error);
+    }
+
+    process.exit(envResult.success ? 0 : 1);
+  }
+
   const result = await handleDeploy({
     target: options.target!,
     autoConfirm: options.yes,
@@ -141,6 +169,12 @@ export const registerDeploy = (program: Command) => {
     .alias('dp')
     .description(COMMAND_DESCRIPTIONS.deploy)
     .option('--target <target>', 'Deployment target name (default: "default") [non-interactive]')
+    .option('--env <name>', 'Environment name to deploy (deploys all targets in the environment) [non-interactive]')
+    .option('--parallel', 'Deploy environment targets concurrently (requires --env) [non-interactive]')
+    .option(
+      '--continue-on-error',
+      'Continue deploying remaining targets after a failure (requires --env) [non-interactive]'
+    )
     .option('-y, --yes', 'Auto-confirm prompts, read credentials from env [non-interactive]')
     .option('-v, --verbose', 'Show resource-level deployment events [non-interactive]')
     .option('--json', 'Output as JSON [non-interactive]')
@@ -149,6 +183,9 @@ export const registerDeploy = (program: Command) => {
     .action(
       async (cliOptions: {
         target?: string;
+        env?: string;
+        parallel?: boolean;
+        continueOnError?: boolean;
         yes?: boolean;
         verbose?: boolean;
         json?: boolean;
@@ -157,12 +194,21 @@ export const registerDeploy = (program: Command) => {
       }) => {
         try {
           requireProject();
-          if (cliOptions.json || cliOptions.target || cliOptions.dryRun || cliOptions.yes || cliOptions.verbose) {
+          if (
+            cliOptions.json ||
+            cliOptions.target ||
+            cliOptions.env ||
+            cliOptions.parallel ||
+            cliOptions.continueOnError ||
+            cliOptions.dryRun ||
+            cliOptions.yes ||
+            cliOptions.verbose
+          ) {
             // CLI mode - any flag triggers non-interactive mode
             const options = {
               ...cliOptions,
               plan: cliOptions.dryRun,
-              target: cliOptions.target ?? 'default',
+              target: cliOptions.env ? cliOptions.target : (cliOptions.target ?? 'default'),
               progress: !cliOptions.json,
             };
             await handleDeployCLI(options as DeployOptions);

src/cli/commands/deploy/types.ts

@@ -1,5 +1,8 @@
 export interface DeployOptions {
   target?: string;
+  env?: string;
+  parallel?: boolean;
+  continueOnError?: boolean;
   yes?: boolean;
   progress?: boolean;
   verbose?: boolean;