@aws-blocks/core 0.1.2 → 0.1.3

package/dist/pipeline/types.d.ts

@@ -1,351 +0,0 @@
-import type * as cdk from 'aws-cdk-lib';
-import type * as codebuild from 'aws-cdk-lib/aws-codebuild';
-/**
- * Configuration for the pipeline source (GitHub/CodeConnections).
- *
- * Uses AWS CodeConnections (formerly CodeStar Connections) for OAuth-based
- * access to GitHub repositories. No token management required — the
- * connection is created once via the AWS Console.
- */
-export interface PipelineSourceConfig {
-    /**
-     * Repository in `owner/repo` format.
-     *
-     * @example 'my-org/my-app'
-     */
-    readonly repo: string;
-    /**
-     * ARN of the AWS CodeConnections connection.
-     *
-     * **Important:** This connection requires a one-time OAuth handshake via the
-     * AWS Console before it can be used. After creating the connection resource
-     * (via CDK, CLI, or Console), you must complete the OAuth flow in the
-     * Console under **Developer Tools → Connections** — the connection will be
-     * in `PENDING` status until authorized.
-     *
-     * Steps:
-     * 1. Create the connection (Console or CLI)
-     * 2. Navigate to **Developer Tools → Connections** in the AWS Console
-     * 3. Select the pending connection and click "Update pending connection"
-     * 4. Authorize the GitHub app and select your repository/organization
-     * 5. The status changes to `AVAILABLE` — the pipeline can now pull source
-     *
-     * @see https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html
-     *
-     * @example 'arn:aws:codeconnections:us-east-1:123456789:connection/abc-def'
-     */
-    readonly connectionArn: string;
-    /**
-     * Whether to trigger the pipeline on push to the branch.
-     *
-     * @default true
-     */
-    readonly triggerOnPush?: boolean;
-    /**
-     * Path-based trigger filters for monorepo support.
-     *
-     * When specified, the pipeline only triggers on pushes that modify files
-     * matching these path patterns. Useful for monorepos where multiple
-     * pipelines share a single repository.
-     *
-     * @example ['packages/backend/**', 'shared/**']
-     */
-    readonly triggerFilters?: string[];
-}
-/**
- * Configuration for the synth step (build + CDK synth).
- *
- * The synth step installs dependencies and runs `cdk synth` to produce
- * the CloudFormation template. The pipeline is self-mutating: if the
- * synth output changes the pipeline definition, it updates itself first.
- */
-export interface PipelineSynthConfig {
-    /**
-     * Shell commands to run during the synth step.
-     *
-     * @default ['npm ci', 'npx cdk synth'] — installs dependencies and synthesizes the CDK app.
-     * Override if you need Node version upgrades, custom build steps, or a non-standard cdk.json app path.
-     * If your app requires Node 22+, prepend `'n 22'` to commands or use {@link installCommands}.
-     */
-    readonly commands?: string[];
-    /**
-     * Commands to run in the CodeBuild install phase (before synth commands).
-     *
-     * @default [] — no install commands. The default build image (Amazon Linux 2023 standard:5.0)
-     * includes Node 22. Set this if you need additional global tools or a different Node version.
-     *
-     * @example ['n 20'] — downgrade Node to version 20
-     */
-    readonly installCommands?: string[];
-    /**
-     * The CodeBuild build image to use for the synth step.
-     *
-     * The default image (Amazon Linux 2023 standard:5.0) includes Node 22 and
-     * Amazon Linux 2023. Override this if you need a different OS or runtime set.
-     *
-     * @default codebuild.LinuxBuildImage.AMAZON_LINUX_2023_5
-     */
-    readonly buildImage?: codebuild.IBuildImage;
-    /**
-     * Environment variables available during synth.
-     *
-     * Note: `NODE_OPTIONS` is automatically prepended with `--conditions=cdk`
-     * (required for ESM conditional exports). Your custom NODE_OPTIONS will be
-     * appended after this flag.
-     */
-    readonly env?: Record<string, string>;
-    /**
-     * Primary output directory for the CDK cloud assembly.
-     *
-     * Override this for monorepos where `cdk synth` outputs to a
-     * subdirectory (e.g., `packages/infra/cdk.out`).
-     *
-     * @default 'cdk.out'
-     */
-    readonly primaryOutputDirectory?: string;
-    /**
-     * Whether to enable Docker for the synth step.
-     *
-     * Required when your CDK app uses Docker image assets (e.g., Lambda
-     * container images, ECS task definitions with Dockerfile builds).
-     *
-     * @default false
-     */
-    readonly dockerEnabled?: boolean;
-    /**
-     * CodeBuild compute type for the synth step.
-     *
-     * Controls the CPU/memory allocation for the build environment.
-     * Increase this if you encounter OOM (exit code 137) during synth/bundling.
-     *
-     * - `SMALL`: 2 vCPU, 3 GB
-     * - `MEDIUM`: 4 vCPU, 7 GB
-     * - `LARGE`: 8 vCPU, 15 GB
-     *
-     * @default ComputeType.MEDIUM (7GB RAM, 4 vCPU) — sufficient for most apps with
-     * Lambda bundling + frontend builds. Use SMALL for trivial apps or LARGE for monorepos.
-     */
-    readonly computeType?: codebuild.ComputeType;
-}
-/**
- * Configuration for a deployment stage.
- *
- * Each stage represents a deployment environment (e.g., beta, prod).
- * Stages are deployed in the order they appear in the `stages` array.
- */
-export interface PipelineStageConfig<TConfig = Record<string, unknown>> {
-    /**
-     * Logical name for this stage (e.g., 'beta', 'prod').
-     * Used as the CDK Stage construct id.
-     */
-    readonly name: string;
-    /**
-     * Target AWS account and region for this stage.
-     * When omitted, deploys to the pipeline's own account/region.
-     */
-    readonly env?: cdk.Environment;
-    /**
-     * Whether to require manual approval before deploying to this stage.
-     *
-     * @default false
-     */
-    readonly requireApproval?: boolean;
-    /**
-     * Optional comment shown in the approval notification.
-     * Only relevant when `requireApproval` is true.
-     */
-    readonly approvalComment?: string;
-    /**
-     * Optional baking time after deployment before proceeding.
-     * Useful for canary validation — gives time for alarms to fire.
-     *
-     * Implemented as a CodeBuild `sleep` step (~$0.005/min on
-     * `BUILD_GENERAL1_SMALL`). An explicit timeout of bakeTime + 10 minutes
-     * is set on the CodeBuild step to prevent pipeline hangs.
-     *
-     * For longer baking periods, use `requireApproval: true` with
-     * external monitoring/alerting instead.
-     */
-    readonly bakeTime?: cdk.Duration;
-    /**
-     * User-defined configuration passed through to the `stageFactory`.
-     *
-     * Use this for per-stage settings like domain names, feature flags,
-     * scaling parameters, etc.
-     *
-     * @example { domain: 'myapp.com', enableCanary: true }
-     */
-    readonly config?: TConfig;
-    /**
-     * Environment variables to set on `process.env` when importing the app file for this stage.
-     *
-     * These are synthesis-time variables (available during `cdk synth`), not deployment-time.
-     * Use this for per-stage configuration that your CDK app reads from `process.env`
-     * (e.g., domain names, feature flags). Only applies when using the `appFile` prop.
-     *
-     * @example { DOMAIN: 'myapp.com', ENABLE_CANARY: 'true' }
-     */
-    readonly environment?: Record<string, string>;
-}
-/**
- * Configuration for a single branch pipeline.
- *
- * Each branch entry creates its own independent CodePipeline that triggers
- * on pushes to the specified branch and deploys through its own ordered stages.
- */
-export interface BranchConfig<TConfig = Record<string, unknown>> {
-    /**
-     * Git branch that triggers this pipeline.
-     *
-     * @example 'main'
-     */
-    readonly branch: string;
-    /**
-     * Ordered list of deployment stages for this branch's pipeline.
-     */
-    readonly stages: Array<PipelineStageConfig<TConfig>>;
-    /**
-     * Whether to trigger this branch's pipeline on push.
-     *
-     * Overrides the top-level `source.triggerOnPush` for this specific branch.
-     * Useful when you want most branches to auto-trigger but disable it for
-     * specific branches (e.g., a release branch that deploys on manual trigger only).
-     *
-     * @default inherits from source.triggerOnPush (which defaults to true)
-     */
-    readonly triggerOnPush?: boolean;
-}
-/**
- * Props for the {@link Pipeline} L3 construct.
- *
- * @example Multi-branch configuration
- * ```ts
- * new Pipeline(stack, 'Pipeline', {
- *   source: {
- *     repo: 'my-org/my-app',
- *     connectionArn: 'arn:aws:codeconnections:us-east-1:123456789:connection/abc',
- *   },
- *   branches: [
- *     {
- *       branch: 'main',
- *       stages: [
- *         { name: 'beta' },
- *         { name: 'prod', requireApproval: true, config: { domain: 'myapp.com' } },
- *       ],
- *     },
- *     {
- *       branch: 'develop',
- *       stages: [
- *         { name: 'alpha', config: { domain: 'alpha.myapp.com' } },
- *       ],
- *     },
- *   ],
- *   stageFactory: (scope, stageConfig) => {
- *     new MyAppStack(scope, 'App', {
- *       stackName: `my-app-${stageConfig.name}`,
- *       env: stageConfig.env,
- *     });
- *   },
- * });
- * ```
- *
- * @example With custom synth and bake time
- * ```ts
- * new Pipeline(stack, 'Pipeline', {
- *   source: {
- *     repo: 'my-org/my-app',
- *     connectionArn: 'arn:aws:codeconnections:...',
- *   },
- *   branches: [
- *     {
- *       branch: 'release',
- *       stages: [
- *         { name: 'beta' },
- *         { name: 'prod', requireApproval: true, bakeTime: Duration.minutes(30) },
- *       ],
- *     },
- *   ],
- *   synth: {
- *     commands: ['npm ci', 'npm run build', 'npx cdk synth'],
- *   },
- *   stageFactory: (scope, stageConfig) => {
- *     new MyAppStack(scope, 'App', { env: stageConfig.env });
- *   },
- * });
- * ```
- */
-export interface PipelineProps<TConfig = Record<string, unknown>> {
-    /** Source repository configuration. */
-    readonly source: PipelineSourceConfig;
-    /** Synth step configuration. */
-    readonly synth?: PipelineSynthConfig;
-    /**
-     * Branch configurations. Each entry creates a separate CodePipeline.
-     *
-     * A single source repository can have multiple branch pipelines, each
-     * with its own set of deployment stages and configuration.
-     */
-    readonly branches: Array<BranchConfig<TConfig>>;
-    /**
-     * Factory function that populates a CDK Stage with stacks.
-     *
-     * Called once per stage across all branches. The factory receives the Stage
-     * scope and the full stage configuration object (including `name`, `env`,
-     * and any user-defined `config`).
-     *
-     * May be async when using constructs that require async initialization
-     * (e.g., `BlocksStack.create()`). When async, use `Pipeline.create()` instead
-     * of `new Pipeline()` to ensure all stages are fully resolved before synth.
-     *
-     * Mutually exclusive with `appFile`. One of `stageFactory` or `appFile` must be provided
-     * for the sync constructor (`new Pipeline()`). When using `Pipeline.create()`, if neither
-     * is provided, `appFile` defaults to `'./index.cdk.ts'`.
-     *
-     * @param scope - The CDK Stage construct to add stacks to.
-     * @param stageConfig - The full stage configuration including name, env, and user-defined config.
-     */
-    readonly stageFactory?: (scope: cdk.Stage, stageConfig: PipelineStageConfig<TConfig>) => void | Promise<void>;
-    /**
-     * Path to the CDK app file to import for each stage.
-     *
-     * When provided, the pipeline will dynamically import this file once per stage,
-     * with the ambient `__PIPELINE_STAGE_SCOPE__` set on globalThis so that
-     * `BlocksStack.create()` automatically attaches to the correct stage scope.
-     *
-     * The path is resolved **relative to the calling file** (not CWD), using
-     * `Error.stack` to determine the caller's directory. Absolute paths are
-     * used as-is.
-     *
-     * Each stage's `environment` vars are set on `process.env` before the import
-     * and cleaned up afterward.
-     *
-     * Mutually exclusive with `stageFactory`. When using `Pipeline.create()` and
-     * neither `appFile` nor `stageFactory` is provided, defaults to `'./index.cdk.ts'`
-     * (resolved relative to the calling file).
-     *
-     * **Security:** This path is dynamically imported during CDK synth, executing
-     * the module's code in the synth process. It MUST originate from a trusted source
-     * (developer's pipeline definition file). Never wire this from external input
-     * (environment variables, build args, plugin configs, or user-supplied values).
-     * A path-containment check enforces that the resolved file stays within the
-     * project root, and only `.ts`, `.js`, `.mjs`, `.cjs` extensions are accepted.
-     *
-     * @default './index.cdk.ts' (when using Pipeline.create() without stageFactory)
-     * @example './infra/app.ts'
-     */
-    readonly appFile?: string;
-    /**
-     * Whether the pipeline should self-mutate (update its own definition).
-     *
-     * @default true
-     */
-    readonly selfMutation?: boolean;
-    /**
-     * Cross-account keys for artifact encryption.
-     * Enable when deploying to accounts different from the pipeline account.
-     *
-     * @default false
-     */
-    readonly crossAccountKeys?: boolean;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/pipeline/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/types.js

@@ -1,3 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-export {};