Programmatic Stack Orchestrator

Automate the lifecycle of a stack using the package's automation API so that infrastructure can be deployed, inspected, and optionally torn down entirely through code.

Capabilities

Previews before applying updates

• Ensures the specified project and stack exist, applies the provided config, and runs a preview before any update. The preview summary in the result reports the total planned resource operations and whether any unknown values were present. Abort the update when the preview reports errors. @test

Deploys inline program and returns outputs

• Runs an inline program supplied by the caller that reads stack config and publishes stack outputs derived from those values, using the config keys as output names. After a successful update, return those outputs with their secret status and surface any change summary the engine provides for the update. @test

Handles secret config

• Config entries marked as secret are stored securely before previewing or updating. Any outputs that originate from secret config must remain marked as secret in the returned result, while non-secret values stay plain. @test

Optional cleanup

• When requested, destroy the stack after the update completes and indicate that cleanup happened. When not requested, leave the stack and outputs intact. @test

Implementation

@generates

API

export interface ProgramConfigEntry {
  value: string;
  secret?: boolean;
}

export interface RunOptions {
  projectName: string;
  stackName: string;
  workDir?: string;
  config: Record<string, ProgramConfigEntry>;
  inlineProgram: () => Promise<void> | void;
  destroyOnComplete?: boolean;
}

export interface PreviewSummary {
  changeCount: number;
  hasUnknownChanges: boolean;
  errorMessage?: string;
}

export interface DeploymentResult {
  preview: PreviewSummary;
  outputs: Record<string, { value: unknown; secret: boolean }>;
  updateChanges?: Record<string, number>;
  performedDestroy: boolean;
}

export async function runProgrammaticStack(options: RunOptions): Promise<DeploymentResult>;

Dependencies { .dependencies }

@pulumi/pulumi { .dependency }

Provides automation API for managing stacks programmatically.