@pipeline-builder/pipeline-core 3.1.1

package/lib/core/network-types.d.ts

@@ -0,0 +1,200 @@
+import type { SecretValue } from 'aws-cdk-lib';
+import type { MetaDataType } from './pipeline-types';
+import type { SecurityGroupConfig } from './security-group-types';
+/**
+ * Network configuration using explicit subnet IDs
+ *
+ * Use when you know the exact subnet IDs where CodeBuild should run.
+ * Subnets are selected directly by ID; VPC is looked up from the provided vpcId.
+ *
+ * @example
+ * ```typescript
+ * const network: SubnetIdsNetwork = {
+ *   type: 'subnetIds',
+ *   options: {
+ *     vpcId: 'vpc-0a1b2c3d4e5f6a7b8',
+ *     subnetIds: ['subnet-0a1b2c3d', 'subnet-4e5f6a7b'],
+ *     securityGroupIds: ['sg-12345678']
+ *   }
+ * };
+ * ```
+ */
+export interface SubnetIdsNetwork {
+    readonly type: 'subnetIds';
+    readonly options: SubnetIdsNetworkOptions;
+}
+/**
+ * Network configuration using VPC lookup by ID
+ *
+ * Looks up an existing VPC by its ID and resolves subnets via subnetSelection filters.
+ *
+ * @example
+ * ```typescript
+ * const network: VpcIdNetwork = {
+ *   type: 'vpcId',
+ *   options: {
+ *     vpcId: 'vpc-0a1b2c3d4e5f6a7b8',
+ *     subnetType: 'PRIVATE_WITH_EGRESS',
+ *     securityGroupIds: ['sg-12345678']
+ *   }
+ * };
+ * ```
+ */
+export interface VpcIdNetwork {
+    readonly type: 'vpcId';
+    readonly options: VpcIdNetworkOptions;
+}
+/**
+ * Network configuration using VPC lookup by tags
+ *
+ * Looks up an existing VPC by tag filters and resolves subnets via subnetSelection filters.
+ *
+ * @example
+ * ```typescript
+ * const network: VpcLookupNetwork = {
+ *   type: 'vpcLookup',
+ *   options: {
+ *     tags: { 'aws:cloudformation:stack-name': 'NetworkStack' },
+ *     subnetType: 'PRIVATE_WITH_EGRESS',
+ *     availabilityZones: ['us-east-1a', 'us-east-1b']
+ *   }
+ * };
+ * ```
+ */
+export interface VpcLookupNetwork {
+    readonly type: 'vpcLookup';
+    readonly options: VpcLookupNetworkOptions;
+}
+/**
+ * Common subnet selection filters shared by VPC-based network options
+ */
+interface SubnetSelectionOptions {
+    /**
+     * Subnet type filter for subnet selection
+     * Maps to CDK SubnetType values
+     * @default 'PRIVATE_WITH_EGRESS'
+     */
+    readonly subnetType?: SubnetTypeName;
+    /**
+     * Filter subnets to specific availability zones
+     * @example ['us-east-1a', 'us-east-1b']
+     */
+    readonly availabilityZones?: string[];
+    /**
+     * Filter subnets by CDK subnet group name
+     * Matches the groupName assigned during VPC creation
+     */
+    readonly subnetGroupName?: string;
+    /**
+     * Security group IDs to attach to CodeBuild projects
+     * @example ['sg-12345678']
+     */
+    readonly securityGroupIds?: string[];
+}
+/**
+ * Configuration options for explicit subnet ID network
+ */
+export interface SubnetIdsNetworkOptions {
+    /**
+     * VPC ID that contains the subnets.
+     * Required because CDK CodeBuildStep needs a vpc reference.
+     * Can be a plain string or a SecretValue (e.g. from Secrets Manager).
+     * @example 'vpc-0a1b2c3d4e5f6a7b8'
+     */
+    readonly vpcId: SecretValue | string;
+    /**
+     * Explicit list of subnet IDs where CodeBuild projects will run
+     * @example ['subnet-0a1b2c3d', 'subnet-4e5f6a7b']
+     */
+    readonly subnetIds: string[];
+    /**
+     * Security group IDs to attach to CodeBuild projects
+     * @example ['sg-12345678']
+     */
+    readonly securityGroupIds?: string[];
+}
+/**
+ * Configuration options for VPC lookup by ID
+ */
+export interface VpcIdNetworkOptions extends SubnetSelectionOptions {
+    /**
+     * VPC ID to look up
+     * Can be a plain string or a SecretValue (e.g. from Secrets Manager).
+     * @example 'vpc-0a1b2c3d4e5f6a7b8'
+     */
+    readonly vpcId: SecretValue | string;
+}
+/**
+ * Configuration options for VPC lookup by tags
+ */
+export interface VpcLookupNetworkOptions extends SubnetSelectionOptions {
+    /**
+     * Tag key-value pairs to identify the VPC
+     * All tags must match for lookup to succeed
+     * @example { Environment: 'production', Team: 'platform' }
+     */
+    readonly tags: Record<string, string>;
+    /**
+     * Optional VPC name (value of the 'Name' tag) for additional filtering
+     */
+    readonly vpcName?: string;
+    /**
+     * Optional AWS region override for cross-region VPC lookup
+     * @example 'us-west-2'
+     */
+    readonly region?: string;
+}
+/**
+ * Subnet type names corresponding to CDK SubnetType enum values
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetType.html
+ */
+export type SubnetTypeName = 'PRIVATE_WITH_EGRESS' | 'PRIVATE_WITH_NAT' | 'PRIVATE_ISOLATED' | 'PUBLIC';
+/**
+ * Union type of all supported network configurations.
+ *
+ * Used at two independent levels:
+ * - Pipeline-level (`defaults.network`) — applies to all CodeBuild actions
+ * - Step-level (`synth.network`, `CodeBuildStepOptions.network`) — applies to an individual build step
+ *
+ * Each variant resolves to vpc, subnetSelection, and optional securityGroups:
+ * - SubnetIdsNetwork: VPC looked up by ID, subnets selected explicitly by ID
+ * - VpcIdNetwork: VPC looked up by ID, subnets resolved via subnetSelection filters
+ * - VpcLookupNetwork: VPC looked up by tags, subnets resolved via subnetSelection filters
+ */
+export type NetworkConfig = SubnetIdsNetwork | VpcIdNetwork | VpcLookupNetwork;
+/**
+ * Pipeline-level CodeBuild defaults applied to every CodeBuild action
+ * (synth, self-mutation, asset publishing) via `codeBuildDefaults`.
+ *
+ * @example
+ * ```typescript
+ * const defaults: CodeBuildDefaults = {
+ *   network: {
+ *     type: 'vpcId',
+ *     options: { vpcId: 'vpc-abc123', subnetType: 'PRIVATE_WITH_EGRESS' }
+ *   },
+ *   metadata: {
+ *     [MetadataKeys.PRIVILEGED]: true,
+ *   },
+ * };
+ * ```
+ */
+export interface CodeBuildDefaults {
+    /**
+     * Network configuration for all CodeBuild actions.
+     * Resolves to vpc, subnetSelection, and optional securityGroups.
+     */
+    readonly network?: NetworkConfig;
+    /**
+     * Standalone security groups for all CodeBuild actions.
+     * Merged with any security groups resolved from network config.
+     */
+    readonly securityGroups?: SecurityGroupConfig;
+    /**
+     * Metadata applied to all CodeBuild actions.
+     * Merged with step-level metadata; step-level keys take precedence.
+     */
+    readonly metadata?: MetaDataType;
+}
+export {};

package/lib/core/network-types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV0d29yay10eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb3JlL25ldHdvcmstdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0MiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHR5cGUgeyBTZWNyZXRWYWx1ZSB9IGZyb20gJ2F3cy1jZGstbGliJztcbmltcG9ydCB0eXBlIHsgTWV0YURhdGFUeXBlIH0gZnJvbSAnLi9waXBlbGluZS10eXBlcyc7XG5pbXBvcnQgdHlwZSB7IFNlY3VyaXR5R3JvdXBDb25maWcgfSBmcm9tICcuL3NlY3VyaXR5LWdyb3VwLXR5cGVzJztcblxuLyoqXG4gKiBOZXR3b3JrIGNvbmZpZ3VyYXRpb24gdXNpbmcgZXhwbGljaXQgc3VibmV0IElEc1xuICpcbiAqIFVzZSB3aGVuIHlvdSBrbm93IHRoZSBleGFjdCBzdWJuZXQgSURzIHdoZXJlIENvZGVCdWlsZCBzaG91bGQgcnVuLlxuICogU3VibmV0cyBhcmUgc2VsZWN0ZWQgZGlyZWN0bHkgYnkgSUQ7IFZQQyBpcyBsb29rZWQgdXAgZnJvbSB0aGUgcHJvdmlkZWQgdnBjSWQuXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IG5ldHdvcms6IFN1Ym5ldElkc05ldHdvcmsgPSB7XG4gKiAgIHR5cGU6ICdzdWJuZXRJZHMnLFxuICogICBvcHRpb25zOiB7XG4gKiAgICAgdnBjSWQ6ICd2cGMtMGExYjJjM2Q0ZTVmNmE3YjgnLFxuICogICAgIHN1Ym5ldElkczogWydzdWJuZXQtMGExYjJjM2QnLCAnc3VibmV0LTRlNWY2YTdiJ10sXG4gKiAgICAgc2VjdXJpdHlHcm91cElkczogWydzZy0xMjM0NTY3OCddXG4gKiAgIH1cbiAqIH07XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBTdWJuZXRJZHNOZXR3b3JrIHtcbiAgcmVhZG9ubHkgdHlwZTogJ3N1Ym5ldElkcyc7XG4gIHJlYWRvbmx5IG9wdGlvbnM6IFN1Ym5ldElkc05ldHdvcmtPcHRpb25zO1xufVxuXG4vKipcbiAqIE5ldHdvcmsgY29uZmlndXJhdGlvbiB1c2luZyBWUEMgbG9va3VwIGJ5IElEXG4gKlxuICogTG9va3MgdXAgYW4gZXhpc3RpbmcgVlBDIGJ5IGl0cyBJRCBhbmQgcmVzb2x2ZXMgc3VibmV0cyB2aWEgc3VibmV0U2VsZWN0aW9uIGZpbHRlcnMuXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IG5ldHdvcms6IFZwY0lkTmV0d29yayA9IHtcbiAqICAgdHlwZTogJ3ZwY0lkJyxcbiAqICAgb3B0aW9uczoge1xuICogICAgIHZwY0lkOiAndnBjLTBhMWIyYzNkNGU1ZjZhN2I4JyxcbiAqICAgICBzdWJuZXRUeXBlOiAnUFJJVkFURV9XSVRIX0VHUkVTUycsXG4gKiAgICAgc2VjdXJpdHlHcm91cElkczogWydzZy0xMjM0NTY3OCddXG4gKiAgIH1cbiAqIH07XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBWcGNJZE5ldHdvcmsge1xuICByZWFkb25seSB0eXBlOiAndnBjSWQnO1xuICByZWFkb25seSBvcHRpb25zOiBWcGNJZE5ldHdvcmtPcHRpb25zO1xufVxuXG4vKipcbiAqIE5ldHdvcmsgY29uZmlndXJhdGlvbiB1c2luZyBWUEMgbG9va3VwIGJ5IHRhZ3NcbiAqXG4gKiBMb29rcyB1cCBhbiBleGlzdGluZyBWUEMgYnkgdGFnIGZpbHRlcnMgYW5kIHJlc29sdmVzIHN1Ym5ldHMgdmlhIHN1Ym5ldFNlbGVjdGlvbiBmaWx0ZXJzLlxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCBuZXR3b3JrOiBWcGNMb29rdXBOZXR3b3JrID0ge1xuICogICB0eXBlOiAndnBjTG9va3VwJyxcbiAqICAgb3B0aW9uczoge1xuICogICAgIHRhZ3M6IHsgJ2F3czpjbG91ZGZvcm1hdGlvbjpzdGFjay1uYW1lJzogJ05ldHdvcmtTdGFjaycgfSxcbiAqICAgICBzdWJuZXRUeXBlOiAnUFJJVkFURV9XSVRIX0VHUkVTUycsXG4gKiAgICAgYXZhaWxhYmlsaXR5Wm9uZXM6IFsndXMtZWFzdC0xYScsICd1cy1lYXN0LTFiJ11cbiAqICAgfVxuICogfTtcbiAqIGBgYFxuICovXG5leHBvcnQgaW50ZXJmYWNlIFZwY0xvb2t1cE5ldHdvcmsge1xuICByZWFkb25seSB0eXBlOiAndnBjTG9va3VwJztcbiAgcmVhZG9ubHkgb3B0aW9uczogVnBjTG9va3VwTmV0d29ya09wdGlvbnM7XG59XG5cbi8qKlxuICogQ29tbW9uIHN1Ym5ldCBzZWxlY3Rpb24gZmlsdGVycyBzaGFyZWQgYnkgVlBDLWJhc2VkIG5ldHdvcmsgb3B0aW9uc1xuICovXG5pbnRlcmZhY2UgU3VibmV0U2VsZWN0aW9uT3B0aW9ucyB7XG4gIC8qKlxuICAgKiBTdWJuZXQgdHlwZSBmaWx0ZXIgZm9yIHN1Ym5ldCBzZWxlY3Rpb25cbiAgICogTWFwcyB0byBDREsgU3VibmV0VHlwZSB2YWx1ZXNcbiAgICogQGRlZmF1bHQgJ1BSSVZBVEVfV0lUSF9FR1JFU1MnXG4gICAqL1xuICByZWFkb25seSBzdWJuZXRUeXBlPzogU3VibmV0VHlwZU5hbWU7XG5cbiAgLyoqXG4gICAqIEZpbHRlciBzdWJuZXRzIHRvIHNwZWNpZmljIGF2YWlsYWJpbGl0eSB6b25lc1xuICAgKiBAZXhhbXBsZSBbJ3VzLWVhc3QtMWEnLCAndXMtZWFzdC0xYiddXG4gICAqL1xuICByZWFkb25seSBhdmFpbGFiaWxpdHlab25lcz86IHN0cmluZ1tdO1xuXG4gIC8qKlxuICAgKiBGaWx0ZXIgc3VibmV0cyBieSBDREsgc3VibmV0IGdyb3VwIG5hbWVcbiAgICogTWF0Y2hlcyB0aGUgZ3JvdXBOYW1lIGFzc2lnbmVkIGR1cmluZyBWUEMgY3JlYXRpb25cbiAgICovXG4gIHJlYWRvbmx5IHN1Ym5ldEdyb3VwTmFtZT86IHN0cmluZztcblxuICAvKipcbiAgICogU2VjdXJpdHkgZ3JvdXAgSURzIHRvIGF0dGFjaCB0byBDb2RlQnVpbGQgcHJvamVjdHNcbiAgICogQGV4YW1wbGUgWydzZy0xMjM0NTY3OCddXG4gICAqL1xuICByZWFkb25seSBzZWN1cml0eUdyb3VwSWRzPzogc3RyaW5nW107XG59XG5cbi8qKlxuICogQ29uZmlndXJhdGlvbiBvcHRpb25zIGZvciBleHBsaWNpdCBzdWJuZXQgSUQgbmV0d29ya1xuICovXG5leHBvcnQgaW50ZXJmYWNlIFN1Ym5ldElkc05ldHdvcmtPcHRpb25zIHtcbiAgLyoqXG4gICAqIFZQQyBJRCB0aGF0IGNvbnRhaW5zIHRoZSBzdWJuZXRzLlxuICAgKiBSZXF1aXJlZCBiZWNhdXNlIENESyBDb2RlQnVpbGRTdGVwIG5lZWRzIGEgdnBjIHJlZmVyZW5jZS5cbiAgICogQ2FuIGJlIGEgcGxhaW4gc3RyaW5nIG9yIGEgU2VjcmV0VmFsdWUgKGUuZy4gZnJvbSBTZWNyZXRzIE1hbmFnZXIpLlxuICAgKiBAZXhhbXBsZSAndnBjLTBhMWIyYzNkNGU1ZjZhN2I4J1xuICAgKi9cbiAgcmVhZG9ubHkgdnBjSWQ6IFNlY3JldFZhbHVlIHwgc3RyaW5nO1xuXG4gIC8qKlxuICAgKiBFeHBsaWNpdCBsaXN0IG9mIHN1Ym5ldCBJRHMgd2hlcmUgQ29kZUJ1aWxkIHByb2plY3RzIHdpbGwgcnVuXG4gICAqIEBleGFtcGxlIFsnc3VibmV0LTBhMWIyYzNkJywgJ3N1Ym5ldC00ZTVmNmE3YiddXG4gICAqL1xuICByZWFkb25seSBzdWJuZXRJZHM6IHN0cmluZ1tdO1xuXG4gIC8qKlxuICAgKiBTZWN1cml0eSBncm91cCBJRHMgdG8gYXR0YWNoIHRvIENvZGVCdWlsZCBwcm9qZWN0c1xuICAgKiBAZXhhbXBsZSBbJ3NnLTEyMzQ1Njc4J11cbiAgICovXG4gIHJlYWRvbmx5IHNlY3VyaXR5R3JvdXBJZHM/OiBzdHJpbmdbXTtcbn1cblxuLyoqXG4gKiBDb25maWd1cmF0aW9uIG9wdGlvbnMgZm9yIFZQQyBsb29rdXAgYnkgSURcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBWcGNJZE5ldHdvcmtPcHRpb25zIGV4dGVuZHMgU3VibmV0U2VsZWN0aW9uT3B0aW9ucyB7XG4gIC8qKlxuICAgKiBWUEMgSUQgdG8gbG9vayB1cFxuICAgKiBDYW4gYmUgYSBwbGFpbiBzdHJpbmcgb3IgYSBTZWNyZXRWYWx1ZSAoZS5nLiBmcm9tIFNlY3JldHMgTWFuYWdlcikuXG4gICAqIEBleGFtcGxlICd2cGMtMGExYjJjM2Q0ZTVmNmE3YjgnXG4gICAqL1xuICByZWFkb25seSB2cGNJZDogU2VjcmV0VmFsdWUgfCBzdHJpbmc7XG59XG5cbi8qKlxuICogQ29uZmlndXJhdGlvbiBvcHRpb25zIGZvciBWUEMgbG9va3VwIGJ5IHRhZ3NcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBWcGNMb29rdXBOZXR3b3JrT3B0aW9ucyBleHRlbmRzIFN1Ym5ldFNlbGVjdGlvbk9wdGlvbnMge1xuICAvKipcbiAgICogVGFnIGtleS12YWx1ZSBwYWlycyB0byBpZGVudGlmeSB0aGUgVlBDXG4gICAqIEFsbCB0YWdzIG11c3QgbWF0Y2ggZm9yIGxvb2t1cCB0byBzdWNjZWVkXG4gICAqIEBleGFtcGxlIHsgRW52aXJvbm1lbnQ6ICdwcm9kdWN0aW9uJywgVGVhbTogJ3BsYXRmb3JtJyB9XG4gICAqL1xuICByZWFkb25seSB0YWdzOiBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+O1xuXG4gIC8qKlxuICAgKiBPcHRpb25hbCBWUEMgbmFtZSAodmFsdWUgb2YgdGhlICdOYW1lJyB0YWcpIGZvciBhZGRpdGlvbmFsIGZpbHRlcmluZ1xuICAgKi9cbiAgcmVhZG9ubHkgdnBjTmFtZT86IHN0cmluZztcblxuICAvKipcbiAgICogT3B0aW9uYWwgQVdTIHJlZ2lvbiBvdmVycmlkZSBmb3IgY3Jvc3MtcmVnaW9uIFZQQyBsb29rdXBcbiAgICogQGV4YW1wbGUgJ3VzLXdlc3QtMidcbiAgICovXG4gIHJlYWRvbmx5IHJlZ2lvbj86IHN0cmluZztcbn1cblxuLyoqXG4gKiBTdWJuZXQgdHlwZSBuYW1lcyBjb3JyZXNwb25kaW5nIHRvIENESyBTdWJuZXRUeXBlIGVudW0gdmFsdWVzXG4gKlxuICogQHNlZSBodHRwczovL2RvY3MuYXdzLmFtYXpvbi5jb20vY2RrL2FwaS92Mi9kb2NzL2F3cy1jZGstbGliLmF3c19lYzIuU3VibmV0VHlwZS5odG1sXG4gKi9cbmV4cG9ydCB0eXBlIFN1Ym5ldFR5cGVOYW1lID1cbiAgfCAnUFJJVkFURV9XSVRIX0VHUkVTUydcbiAgfCAnUFJJVkFURV9XSVRIX05BVCdcbiAgfCAnUFJJVkFURV9JU09MQVRFRCdcbiAgfCAnUFVCTElDJztcblxuLyoqXG4gKiBVbmlvbiB0eXBlIG9mIGFsbCBzdXBwb3J0ZWQgbmV0d29yayBjb25maWd1cmF0aW9ucy5cbiAqXG4gKiBVc2VkIGF0IHR3byBpbmRlcGVuZGVudCBsZXZlbHM6XG4gKiAtIFBpcGVsaW5lLWxldmVsIChgZGVmYXVsdHMubmV0d29ya2ApIOKAlCBhcHBsaWVzIHRvIGFsbCBDb2RlQnVpbGQgYWN0aW9uc1xuICogLSBTdGVwLWxldmVsIChgc3ludGgubmV0d29ya2AsIGBDb2RlQnVpbGRTdGVwT3B0aW9ucy5uZXR3b3JrYCkg4oCUIGFwcGxpZXMgdG8gYW4gaW5kaXZpZHVhbCBidWlsZCBzdGVwXG4gKlxuICogRWFjaCB2YXJpYW50IHJlc29sdmVzIHRvIHZwYywgc3VibmV0U2VsZWN0aW9uLCBhbmQgb3B0aW9uYWwgc2VjdXJpdHlHcm91cHM6XG4gKiAtIFN1Ym5ldElkc05ldHdvcms6IFZQQyBsb29rZWQgdXAgYnkgSUQsIHN1Ym5ldHMgc2VsZWN0ZWQgZXhwbGljaXRseSBieSBJRFxuICogLSBWcGNJZE5ldHdvcms6IFZQQyBsb29rZWQgdXAgYnkgSUQsIHN1Ym5ldHMgcmVzb2x2ZWQgdmlhIHN1Ym5ldFNlbGVjdGlvbiBmaWx0ZXJzXG4gKiAtIFZwY0xvb2t1cE5ldHdvcms6IFZQQyBsb29rZWQgdXAgYnkgdGFncywgc3VibmV0cyByZXNvbHZlZCB2aWEgc3VibmV0U2VsZWN0aW9uIGZpbHRlcnNcbiAqL1xuZXhwb3J0IHR5cGUgTmV0d29ya0NvbmZpZyA9IFN1Ym5ldElkc05ldHdvcmsgfCBWcGNJZE5ldHdvcmsgfCBWcGNMb29rdXBOZXR3b3JrO1xuXG4vKipcbiAqIFBpcGVsaW5lLWxldmVsIENvZGVCdWlsZCBkZWZhdWx0cyBhcHBsaWVkIHRvIGV2ZXJ5IENvZGVCdWlsZCBhY3Rpb25cbiAqIChzeW50aCwgc2VsZi1tdXRhdGlvbiwgYXNzZXQgcHVibGlzaGluZykgdmlhIGBjb2RlQnVpbGREZWZhdWx0c2AuXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IGRlZmF1bHRzOiBDb2RlQnVpbGREZWZhdWx0cyA9IHtcbiAqICAgbmV0d29yazoge1xuICogICAgIHR5cGU6ICd2cGNJZCcsXG4gKiAgICAgb3B0aW9uczogeyB2cGNJZDogJ3ZwYy1hYmMxMjMnLCBzdWJuZXRUeXBlOiAnUFJJVkFURV9XSVRIX0VHUkVTUycgfVxuICogICB9LFxuICogICBtZXRhZGF0YToge1xuICogICAgIFtNZXRhZGF0YUtleXMuUFJJVklMRUdFRF06IHRydWUsXG4gKiAgIH0sXG4gKiB9O1xuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQ29kZUJ1aWxkRGVmYXVsdHMge1xuICAvKipcbiAgICogTmV0d29yayBjb25maWd1cmF0aW9uIGZvciBhbGwgQ29kZUJ1aWxkIGFjdGlvbnMuXG4gICAqIFJlc29sdmVzIHRvIHZwYywgc3VibmV0U2VsZWN0aW9uLCBhbmQgb3B0aW9uYWwgc2VjdXJpdHlHcm91cHMuXG4gICAqL1xuICByZWFkb25seSBuZXR3b3JrPzogTmV0d29ya0NvbmZpZztcblxuICAvKipcbiAgICogU3RhbmRhbG9uZSBzZWN1cml0eSBncm91cHMgZm9yIGFsbCBDb2RlQnVpbGQgYWN0aW9ucy5cbiAgICogTWVyZ2VkIHdpdGggYW55IHNlY3VyaXR5IGdyb3VwcyByZXNvbHZlZCBmcm9tIG5ldHdvcmsgY29uZmlnLlxuICAgKi9cbiAgcmVhZG9ubHkgc2VjdXJpdHlHcm91cHM/OiBTZWN1cml0eUdyb3VwQ29uZmlnO1xuXG4gIC8qKlxuICAgKiBNZXRhZGF0YSBhcHBsaWVkIHRvIGFsbCBDb2RlQnVpbGQgYWN0aW9ucy5cbiAgICogTWVyZ2VkIHdpdGggc3RlcC1sZXZlbCBtZXRhZGF0YTsgc3RlcC1sZXZlbCBrZXlzIHRha2UgcHJlY2VkZW5jZS5cbiAgICovXG4gIHJlYWRvbmx5IG1ldGFkYXRhPzogTWV0YURhdGFUeXBlO1xufVxuIl19

package/lib/core/network.d.ts

@@ -0,0 +1,20 @@
+import { ISecurityGroup, IVpc, SubnetSelection } from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import { UniqueId } from './id-generator';
+import type { NetworkConfig } from './network-types';
+/** Resolved CDK network props ready to spread into CodeBuildStep or codeBuildDefaults */
+export interface ResolvedNetwork {
+    vpc: IVpc;
+    subnetSelection: SubnetSelection;
+    securityGroups?: ISecurityGroup[];
+}
+/**
+ * Resolve a NetworkConfig into CDK props for CodeBuildStep or codeBuildDefaults.
+ * Uses discriminated union narrowing to delegate to the appropriate CDK lookups.
+ *
+ * @param scope - CDK construct scope
+ * @param id - UniqueId instance for generating unique construct IDs
+ * @param network - Network configuration to resolve
+ * @returns Resolved network props ready to spread into CDK constructs
+ */
+export declare function resolveNetwork(scope: Construct, id: UniqueId, network: NetworkConfig): ResolvedNetwork;

package/lib/core/network.js

@@ -0,0 +1,84 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNetwork = resolveNetwork;
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const pipeline_helpers_1 = require("./pipeline-helpers");
+/**
+ * Mapping from string subnet type names to CDK SubnetType enum values
+ */
+const SUBNET_TYPE_MAP = {
+    PRIVATE_WITH_EGRESS: aws_ec2_1.SubnetType.PRIVATE_WITH_EGRESS,
+    PRIVATE_WITH_NAT: aws_ec2_1.SubnetType.PRIVATE_WITH_NAT,
+    PRIVATE_ISOLATED: aws_ec2_1.SubnetType.PRIVATE_ISOLATED,
+    PUBLIC: aws_ec2_1.SubnetType.PUBLIC,
+};
+const DEFAULT_SUBNET_TYPE = 'PRIVATE_WITH_EGRESS';
+/**
+ * Resolve a NetworkConfig into CDK props for CodeBuildStep or codeBuildDefaults.
+ * Uses discriminated union narrowing to delegate to the appropriate CDK lookups.
+ *
+ * @param scope - CDK construct scope
+ * @param id - UniqueId instance for generating unique construct IDs
+ * @param network - Network configuration to resolve
+ * @returns Resolved network props ready to spread into CDK constructs
+ */
+function resolveNetwork(scope, id, network) {
+    switch (network.type) {
+        case 'subnetIds': {
+            const vpc = aws_ec2_1.Vpc.fromLookup(scope, id.generate('network:vpc'), {
+                vpcId: (0, pipeline_helpers_1.unwrapSecret)(network.options.vpcId),
+            });
+            const subnets = network.options.subnetIds.map((subnetId) => aws_ec2_1.Subnet.fromSubnetId(scope, id.generate('network:subnet'), subnetId));
+            return withSecurityGroups({ vpc, subnetSelection: { subnets } }, scope, id, network.options.securityGroupIds);
+        }
+        case 'vpcId': {
+            const vpc = aws_ec2_1.Vpc.fromLookup(scope, id.generate('network:vpc'), {
+                vpcId: (0, pipeline_helpers_1.unwrapSecret)(network.options.vpcId),
+            });
+            return withSecurityGroups({ vpc, subnetSelection: resolveSubnetSelection(network.options) }, scope, id, network.options.securityGroupIds);
+        }
+        case 'vpcLookup': {
+            const vpc = aws_ec2_1.Vpc.fromLookup(scope, id.generate('network:vpc'), {
+                tags: network.options.tags,
+                ...(network.options.vpcName && { vpcName: network.options.vpcName }),
+                ...(network.options.region && { region: network.options.region }),
+            });
+            return withSecurityGroups({ vpc, subnetSelection: resolveSubnetSelection(network.options) }, scope, id, network.options.securityGroupIds);
+        }
+        default: {
+            const _exhaustive = network;
+            throw new Error(`Unknown network config type: ${_exhaustive.type}`);
+        }
+    }
+}
+/**
+ * Attach resolved security groups to a network result when present.
+ */
+function withSecurityGroups(result, scope, id, securityGroupIds) {
+    const securityGroups = resolveSecurityGroups(scope, id, securityGroupIds);
+    return securityGroups ? { ...result, securityGroups } : result;
+}
+/**
+ * Build a SubnetSelection from options that carry subnetType, availabilityZones,
+ * and subnetGroupName. Shared by vpcId and vpcLookup branches.
+ */
+function resolveSubnetSelection(options) {
+    return {
+        subnetType: SUBNET_TYPE_MAP[options.subnetType ?? DEFAULT_SUBNET_TYPE],
+        ...(options.availabilityZones && { availabilityZones: options.availabilityZones }),
+        ...(options.subnetGroupName && { subnetGroupName: options.subnetGroupName }),
+    };
+}
+/**
+ * Resolve security group IDs into CDK security group references.
+ * Returns undefined when no IDs are provided.
+ */
+function resolveSecurityGroups(scope, id, securityGroupIds) {
+    if (!securityGroupIds?.length) {
+        return undefined;
+    }
+    return securityGroupIds.map((sgId) => aws_ec2_1.SecurityGroup.fromSecurityGroupId(scope, id.generate('network:sg'), sgId));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV0d29yay5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb3JlL25ldHdvcmsudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7O0FBdUN0Qyx3Q0FxREM7QUExRkQsaURBQW9IO0FBT3BILHlEQUFrRDtBQUVsRDs7R0FFRztBQUNILE1BQU0sZUFBZSxHQUF1QztJQUMxRCxtQkFBbUIsRUFBRSxvQkFBVSxDQUFDLG1CQUFtQjtJQUNuRCxnQkFBZ0IsRUFBRSxvQkFBVSxDQUFDLGdCQUFnQjtJQUM3QyxnQkFBZ0IsRUFBRSxvQkFBVSxDQUFDLGdCQUFnQjtJQUM3QyxNQUFNLEVBQUUsb0JBQVUsQ0FBQyxNQUFNO0NBQzFCLENBQUM7QUFFRixNQUFNLG1CQUFtQixHQUFtQixxQkFBcUIsQ0FBQztBQVNsRTs7Ozs7Ozs7R0FRRztBQUNILFNBQWdCLGNBQWMsQ0FDNUIsS0FBZ0IsRUFDaEIsRUFBWSxFQUNaLE9BQXNCO0lBRXRCLFFBQVEsT0FBTyxDQUFDLElBQUksRUFBRSxDQUFDO1FBQ3JCLEtBQUssV0FBVyxDQUFDLENBQUMsQ0FBQztZQUNqQixNQUFNLEdBQUcsR0FBRyxhQUFHLENBQUMsVUFBVSxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsUUFBUSxDQUFDLGFBQWEsQ0FBQyxFQUFFO2dCQUM1RCxLQUFLLEVBQUUsSUFBQSwrQkFBWSxFQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDO2FBQzNDLENBQUMsQ0FBQztZQUVILE1BQU0sT0FBTyxHQUFHLE9BQU8sQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FDM0MsQ0FBQyxRQUFRLEVBQUUsRUFBRSxDQUFDLGdCQUFNLENBQUMsWUFBWSxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsUUFBUSxDQUFDLGdCQUFnQixDQUFDLEVBQUUsUUFBUSxDQUFDLENBQ2xGLENBQUM7WUFFRixPQUFPLGtCQUFrQixDQUN2QixFQUFF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QUM7SUFDbkIsQ0FBQztJQUNELE9BQU8sZ0JBQWdCLENBQUMsR0FBRyxDQUN6QixDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsdUJBQWEsQ0FBQyxtQkFBbUIsQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQUMsRUFBRSxJQUFJLENBQUMsQ0FDcEYsQ0FBQztBQUNKLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgSVNlY3VyaXR5R3JvdXAsIElWcGMsIFNlY3VyaXR5R3JvdXAsIFN1Ym5ldCwgU3VibmV0U2VsZWN0aW9uLCBTdWJuZXRUeXBlLCBWcGMgfSBmcm9tICdhd3MtY2RrLWxpYi9hd3MtZWMyJztcbmltcG9ydCB7IENvbnN0cnVjdCB9IGZyb20gJ2NvbnN0cnVjdHMnO1xuaW1wb3J0IHsgVW5pcXVlSWQgfSBmcm9tICcuL2lkLWdlbmVyYXRvcic7XG5pbXBvcnQgdHlwZSB7XG4gIE5ldHdvcmtDb25maWcsXG4gIFN1Ym5ldFR5cGVOYW1lLFxufSBmcm9tICcuL25ldHdvcmstdHlwZXMnO1xuaW1wb3J0IHsgdW53cmFwU2VjcmV0IH0gZnJvbSAnLi9waXBlbGluZS1oZWxwZXJzJztcblxuLyoqXG4gKiBNYXBwaW5nIGZyb20gc3RyaW5nIHN1Ym5ldCB0eXBlIG5hbWVzIHRvIENESyBTdWJuZXRUeXBlIGVudW0gdmFsdWVzXG4gKi9cbmNvbnN0IFNVQk5FVF9UWVBFX01BUDogUmVjb3JkPFN1Ym5ldFR5cGVOYW1lLCBTdWJuZXRUeXBlPiA9IHtcbiAgUFJJVkFURV9XSVRIX0VHUkVTUzogU3VibmV0VHlwZS5QUklWQVRFX1dJVEhfRUdSRVNTLFxuICBQUklWQVRFX1dJVEhfTkFUOiBTdWJuZXRUeXBlLlBSSVZBVEVfV0lUSF9OQVQsXG4gIFBSSVZBVEVfSVNPTEFURUQ6IFN1Ym5ldFR5cGUuUFJJVkFURV9JU09MQVRFRCxcbiAgUFVCTElDOiBTdWJuZXRUeXBlLlBVQkxJQyxcbn07XG5cbmNvbnN0IERFRkFVTFRfU1VCTkVUX1RZUEU6IFN1Ym5ldFR5cGVOYW1lID0gJ1BSSVZBVEVfV0lUSF9FR1JFU1MnO1xuXG4vKiogUmVzb2x2ZWQgQ0RLIG5ldHdvcmsgcHJvcHMgcmVhZHkgdG8gc3ByZWFkIGludG8gQ29kZUJ1aWxkU3RlcCBvciBjb2RlQnVpbGREZWZhdWx0cyAqL1xuZXhwb3J0IGludGVyZmFjZSBSZXNvbHZlZE5ldHdvcmsge1xuICB2cGM6IElWcGM7XG4gIHN1Ym5ldFNlbGVjdGlvbjogU3VibmV0U2VsZWN0aW9uO1xuICBzZWN1cml0eUdyb3Vwcz86IElTZWN1cml0eUdyb3VwW107XG59XG5cbi8qKlxuICogUmVzb2x2ZSBhIE5ldHdvcmtDb25maWcgaW50byBDREsgcHJvcHMgZm9yIENvZGVCdWlsZFN0ZXAgb3IgY29kZUJ1aWxkRGVmYXVsdHMuXG4gKiBVc2VzIGRpc2NyaW1pbmF0ZWQgdW5pb24gbmFycm93aW5nIHRvIGRlbGVnYXRlIHRvIHRoZSBhcHByb3ByaWF0ZSBDREsgbG9va3Vwcy5cbiAqXG4gKiBAcGFyYW0gc2NvcGUgLSBDREsgY29uc3RydWN0IHNjb3BlXG4gKiBAcGFyYW0gaWQgLSBVbmlxdWVJZCBpbnN0YW5jZSBmb3IgZ2VuZXJhdGluZyB1bmlxdWUgY29uc3RydWN0IElEc1xuICogQHBhcmFtIG5ldHdvcmsgLSBOZXR3b3JrIGNvbmZpZ3VyYXRpb24gdG8gcmVzb2x2ZVxuICogQHJldHVybnMgUmVzb2x2ZWQgbmV0d29yayBwcm9wcyByZWFkeSB0byBzcHJlYWQgaW50byBDREsgY29uc3RydWN0c1xuICovXG5leHBvcnQgZnVuY3Rpb24gcmVzb2x2ZU5ldHdvcmsoXG4gIHNjb3BlOiBDb25zdHJ1Y3QsXG4gIGlkOiBVbmlxdWVJZCxcbiAgbmV0d29yazogTmV0d29ya0NvbmZpZyxcbik6IFJlc29sdmVkTmV0d29yayB7XG4gIHN3aXRjaCAobmV0d29yay50eXBlKSB7XG4gICAgY2FzZSAnc3VibmV0SWRzJzoge1xuICAgICAgY29uc3QgdnBjID0gVnBjLmZyb21Mb29rdXAoc2NvcGUsIGlkLmdlbmVyYXRlKCduZXR3b3JrOnZwYycpLCB7XG4gICAgICAgIHZwY0lkOiB1bndyYXBTZWNyZXQobmV0d29yay5vcHRpb25zLnZwY0lkKSxcbiAgICAgIH0pO1xuXG4gICAgICBjb25zdCBzdWJuZXRzID0gbmV0d29yay5vcHRpb25zLnN1Ym5ldElkcy5tYXAoXG4gICAgICAgIChzdWJuZXRJZCkgPT4gU3VibmV0LmZyb21TdWJuZXRJZChzY29wZSwgaWQuZ2VuZXJhdGUoJ25ldHdvcms6c3VibmV0JyksIHN1Ym5ldElkKSxcbiAgICAgICk7XG5cbiAgICAgIHJldHVybiB3aXRoU2VjdXJpdHlHcm91cHMoXG4gICAgICAgIHsgdnBjLCBzdWJuZXRTZWxlY3Rpb246IHsgc3VibmV0cyB9IH0sXG4gICAgICAgIHNjb3BlLFxuICAgICAgICBpZCxcbiAgICAgICAgbmV0d29yay5vcHRpb25zLnNlY3VyaXR5R3JvdXBJZHMsXG4gICAgICApO1xuICAgIH1cbiAgICBjYXNlICd2cGNJZCc6IHtcbiAgICAgIGNvbnN0IHZwYyA9IFZwYy5mcm9tTG9va3VwKHNjb3BlLCBpZC5nZW5lcmF0ZSgnbmV0d29yazp2cGMnKSwge1xuICAgICAgICB2cGNJZDogdW53cmFwU2VjcmV0KG5ldHdvcmsub3B0aW9ucy52cGNJZCksXG4gICAgICB9KTtcblxuICAgICAgcmV0dXJuIHdpdGhTZWN1cml0eUdyb3VwcyhcbiAgICAgICAgeyB2cGMsIHN1Ym5ldFNlbGVjdGlvbjogcmVzb2x2ZVN1Ym5ldFNlbGVjdGlvbihuZXR3b3JrLm9wdGlvbnMpIH0sXG4gICAgICAgIHNjb3BlLFxuICAgICAgICBpZCxcbiAgICAgICAgbmV0d29yay5vcHRpb25zLnNlY3VyaXR5R3JvdXBJZHMsXG4gICAgICApO1xuICAgIH1cbiAgICBjYXNlICd2cGNMb29rdXAnOiB7XG4gICAgICBjb25zdCB2cGMgPSBWcGMuZnJvbUxvb2t1cChzY29wZSwgaWQuZ2VuZXJhdGUoJ25ldHdvcms6dnBjJyksIHtcbiAgICAgICAgdGFnczogbmV0d29yay5vcHRpb25zLnRhZ3MsXG4gICAgICAgIC4uLihuZXR3b3JrLm9wdGlvbnMudnBjTmFtZSAmJiB7IHZwY05hbWU6IG5ldHdvcmsub3B0aW9ucy52cGNOYW1lIH0pLFxuICAgICAgICAuLi4obmV0d29yay5vcHRpb25zLnJlZ2lvbiAmJiB7IHJlZ2lvbjogbmV0d29yay5vcHRpb25zLnJlZ2lvbiB9KSxcbiAgICAgIH0pO1xuXG4gICAgICByZXR1cm4gd2l0aFNlY3VyaXR5R3JvdXBzKFxuICAgICAgICB7IHZwYywgc3VibmV0U2VsZWN0aW9uOiByZXNvbHZlU3VibmV0U2VsZWN0aW9uKG5ldHdvcmsub3B0aW9ucykgfSxcbiAgICAgICAgc2NvcGUsXG4gICAgICAgIGlkLFxuICAgICAgICBuZXR3b3JrLm9wdGlvbnMuc2VjdXJpdHlHcm91cElkcyxcbiAgICAgICk7XG4gICAgfVxuICAgIGRlZmF1bHQ6IHtcbiAgICAgIGNvbnN0IF9leGhhdXN0aXZlOiBuZXZlciA9IG5ldHdvcms7XG4gICAgICB0aHJvdyBuZXcgRXJyb3IoYFVua25vd24gbmV0d29yayBjb25maWcgdHlwZTogJHsoX2V4aGF1c3RpdmUgYXMgTmV0d29ya0NvbmZpZykudHlwZX1gKTtcbiAgICB9XG4gIH1cbn1cblxuLyoqXG4gKiBBdHRhY2ggcmVzb2x2ZWQgc2VjdXJpdHkgZ3JvdXBzIHRvIGEgbmV0d29yayByZXN1bHQgd2hlbiBwcmVzZW50LlxuICovXG5mdW5jdGlvbiB3aXRoU2VjdXJpdHlHcm91cHMoXG4gIHJlc3VsdDogT21pdDxSZXNvbHZlZE5ldHdvcmssICdzZWN1cml0eUdyb3Vwcyc+LFxuICBzY29wZTogQ29uc3RydWN0LFxuICBpZDogVW5pcXVlSWQsXG4gIHNlY3VyaXR5R3JvdXBJZHM/OiBzdHJpbmdbXSxcbik6IFJlc29sdmVkTmV0d29yayB7XG4gIGNvbnN0IHNlY3VyaXR5R3JvdXBzID0gcmVzb2x2ZVNlY3VyaXR5R3JvdXBzKHNjb3BlLCBpZCwgc2VjdXJpdHlHcm91cElkcyk7XG4gIHJldHVybiBzZWN1cml0eUdyb3VwcyA/IHsgLi4ucmVzdWx0LCBzZWN1cml0eUdyb3VwcyB9IDogcmVzdWx0O1xufVxuXG4vKipcbiAqIEJ1aWxkIGEgU3VibmV0U2VsZWN0aW9uIGZyb20gb3B0aW9ucyB0aGF0IGNhcnJ5IHN1Ym5ldFR5cGUsIGF2YWlsYWJpbGl0eVpvbmVzLFxuICogYW5kIHN1Ym5ldEdyb3VwTmFtZS4gU2hhcmVkIGJ5IHZwY0lkIGFuZCB2cGNMb29rdXAgYnJhbmNoZXMuXG4gKi9cbmZ1bmN0aW9uIHJlc29sdmVTdWJuZXRTZWxlY3Rpb24oXG4gIG9wdGlvbnM6IHsgc3VibmV0VHlwZT86IFN1Ym5ldFR5cGVOYW1lOyBhdmFpbGFiaWxpdHlab25lcz86IHN0cmluZ1tdOyBzdWJuZXRHcm91cE5hbWU/OiBzdHJpbmcgfSxcbik6IFN1Ym5ldFNlbGVjdGlvbiB7XG4gIHJldHVybiB7XG4gICAgc3VibmV0VHlwZTogU1VCTkVUX1RZUEVfTUFQW29wdGlvbnMuc3VibmV0VHlwZSA/PyBERUZBVUxUX1NVQk5FVF9UWVBFXSxcbiAgICAuLi4ob3B0aW9ucy5hdmFpbGFiaWxpdHlab25lcyAmJiB7IGF2YWlsYWJpbGl0eVpvbmVzOiBvcHRpb25zLmF2YWlsYWJpbGl0eVpvbmVzIH0pLFxuICAgIC4uLihvcHRpb25zLnN1Ym5ldEdyb3VwTmFtZSAmJiB7IHN1Ym5ldEdyb3VwTmFtZTogb3B0aW9ucy5zdWJuZXRHcm91cE5hbWUgfSksXG4gIH07XG59XG5cbi8qKlxuICogUmVzb2x2ZSBzZWN1cml0eSBncm91cCBJRHMgaW50byBDREsgc2VjdXJpdHkgZ3JvdXAgcmVmZXJlbmNlcy5cbiAqIFJldHVybnMgdW5kZWZpbmVkIHdoZW4gbm8gSURzIGFyZSBwcm92aWRlZC5cbiAqL1xuZnVuY3Rpb24gcmVzb2x2ZVNlY3VyaXR5R3JvdXBzKFxuICBzY29wZTogQ29uc3RydWN0LFxuICBpZDogVW5pcXVlSWQsXG4gIHNlY3VyaXR5R3JvdXBJZHM/OiBzdHJpbmdbXSxcbik6IElTZWN1cml0eUdyb3VwW10gfCB1bmRlZmluZWQge1xuICBpZiAoIXNlY3VyaXR5R3JvdXBJZHM/Lmxlbmd0aCkge1xuICAgIHJldHVybiB1bmRlZmluZWQ7XG4gIH1cbiAgcmV0dXJuIHNlY3VyaXR5R3JvdXBJZHMubWFwKFxuICAgIChzZ0lkKSA9PiBTZWN1cml0eUdyb3VwLmZyb21TZWN1cml0eUdyb3VwSWQoc2NvcGUsIGlkLmdlbmVyYXRlKCduZXR3b3JrOnNnJyksIHNnSWQpLFxuICApO1xufVxuIl19

package/lib/core/pipeline-helpers.d.ts

@@ -0,0 +1,53 @@
+import { SecretValue } from 'aws-cdk-lib';
+import { ComputeType as CDKComputeType } from 'aws-cdk-lib/aws-codebuild';
+import { CodeBuildStep, ManualApprovalStep, ShellStep } from 'aws-cdk-lib/pipelines';
+import { MetaDataType } from './pipeline-types';
+import type { CodeBuildStepOptions } from '../pipeline/step-types';
+/**
+ * Merge multiple metadata objects into one. Later sources override earlier ones.
+ */
+export declare function merge(...sources: Array<Partial<MetaDataType>>): MetaDataType;
+/**
+ * Extract non-namespaced metadata keys as environment variable strings.
+ * Keys starting with 'aws:cdk:' are reserved for CDK construct props
+ * (processed by metadata extraction functions) and are excluded here.
+ *
+ * All values are converted to strings for CodeBuild compatibility.
+ */
+export declare function extractMetadataEnv(metadata: MetaDataType): Record<string, string>;
+/**
+ * Create a CodeBuild step or Shell step based on plugin configuration.
+ *
+ * Metadata merge order (last wins):
+ *   1. Step-level metadata (from options.metadata)
+ *   2. Plugin metadata (from plugin.metadata in database)
+ *
+ * Environment merge order (last wins):
+ *   1. Plugin env vars (from plugin.env)
+ *   2. Custom env vars (from options.env)
+ *   3. WORKDIR from merged metadata
+ *
+ * CDK prop spread order (last wins):
+ *   programmatic defaults (input, commands, env, network) → metadata overrides
+ *
+ * This means metadata keys like `aws:cdk:pipelines:codebuildstep:commands`
+ * will override the plugin-derived commands when explicitly set.
+ */
+export declare function createCodeBuildStep(options: CodeBuildStepOptions): ShellStep | CodeBuildStep | ManualApprovalStep;
+/**
+ * Convert string or ComputeType enum to CDK ComputeType
+ */
+export declare function getComputeType(input?: string | CDKComputeType): CDKComputeType;
+/**
+ * Replaces all characters that are not letters or numbers with the specified value
+ * @param input - The string to process
+ * @param replaceValue - The character(s) to replace non-alphanumeric characters with (default: '_')
+ * @returns The string with non-alphanumeric characters replaced
+ */
+export declare function replaceNonAlphanumeric(input: string, replaceValue?: string): string;
+/**
+ * Unwrap a SecretValue | string into a plain string.
+ * When a SecretValue is provided (e.g. from Secrets Manager), calls unsafeUnwrap()
+ * to extract the underlying value.
+ */
+export declare function unwrapSecret(value: SecretValue | string): string;