@go-to-k/cdkd 0.247.0 → 0.248.0

package/README.md

@@ -4,15 +4,14 @@
 [![Downloads](https://img.shields.io/npm/dw/@go-to-k/cdkd.svg)](https://www.npmjs.com/package/@go-to-k/cdkd)
 [![License: Apache-2.0](https://img.shields.io/npm/l/@go-to-k/cdkd.svg)](./LICENSE)
 
-Drop-in CDK CLI for existing CDK apps: up to 15x faster deploys via AWS SDK instead of CloudFormation.
+Drop-in CDK CLI for existing CDK apps — up to 15x faster deploys via direct AWS SDK calls instead of CloudFormation.
 
 - **Drop-in CDK compatible**: your existing CDK app code runs as-is.
 - **Up to 15x faster deploys**: direct SDK calls, aggressive parallelization, and `--no-wait` to skip slow stabilization waits.
-- **Local execution**: run your functions and APIs locally, with env vars, secrets, and resource references resolved from your deployed stack instead of hand-written `.env` files.
 
 ![cdk deploy vs cdkd deploy — side-by-side, 35s recording, real AWS deploy. cdkd finishes while cdk is still creating its CloudFormation changeset.](assets/cdk-vs-cdkd.gif)
 
-**cdkd complements the AWS CDK CLI rather than replacing it.** Use cdkd in dev/test for rapid iteration and SAM-style local execution; use the AWS CDK CLI in production for full CloudFormation tooling. Install cdkd alongside an existing `cdk deploy` workflow — no migration needed, `cdkd local *` reads deployed state directly via `--from-cfn-stack`. Bidirectional migration is also supported — [import](#importing-existing-resources) into cdkd or [export](#exporting-a-stack-back-to-cloudformation) back to CloudFormation when ready.
+**cdkd complements the AWS CDK CLI rather than replacing it.** Use cdkd in dev/test for rapid iteration and local execution; use the AWS CDK CLI in production for full CloudFormation tooling. Install cdkd alongside an existing `cdk deploy` workflow: no migration needed. Bidirectional migration is also supported: [import](#importing-existing-resources) into cdkd or [export](#exporting-a-stack-back-to-cloudformation) back to CloudFormation when ready.
 
 **A natural fit for AI-driven development.** AI coding agents iterate in tight spin-up / tear-down loops — and cdkd keeps each turn short, with fast deploys and an equally fast `cdkd destroy` that deletes via direct SDK calls instead of polling a CloudFormation stack-delete.
 
@@ -139,13 +138,14 @@ parsing → synthesis → asset publishing → per-stack deploy), see
 ## Prerequisites
 
 - **Node.js** >= 20.0.0
-- **AWS CDK Bootstrap: not required.** `cdkd bootstrap` (once per account) creates
-  everything cdkd needs, and per-region asset storage is added automatically on the
-  first `cdkd deploy` into each region. Existing setups, legacy-mode opt-outs, and
-  how this relates to `cdk bootstrap`: see
-  [Upgrading from an earlier cdkd version](#upgrading-from-an-earlier-cdkd-version).
 - **AWS credentials with admin-equivalent permissions** for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's `cdk-hnb659fds-deploy-role-*` is NOT sufficient — see [`--role-arn`](docs/cli-reference.md).
 
+AWS CDK's `cdk bootstrap` is not required. Instead, run `cdkd bootstrap` once per
+account: it creates everything cdkd needs, and per-region asset storage is added
+automatically on the first `cdkd deploy` into each region. Existing setups,
+legacy-mode opt-outs, and how this relates to `cdk bootstrap`: see
+[Upgrading from an earlier cdkd version](#upgrading-from-an-earlier-cdkd-version).
+
 ## Installation
 
 ```bash

package/dist/cli.js

@@ -60,7 +60,7 @@ import { AddTagsToStreamCommand, CreateStreamCommand, DecreaseStreamRetentionPer
 import { CreateScheduleCommand, DeleteScheduleCommand, GetScheduleCommand, ResourceNotFoundException as ResourceNotFoundException$9, SchedulerClient, UpdateScheduleCommand } from "@aws-sdk/client-scheduler";
 import { AccessPointNotFound, CreateAccessPointCommand, CreateFileSystemCommand, CreateMountTargetCommand, DeleteAccessPointCommand, DeleteFileSystemCommand, DeleteMountTargetCommand, DescribeAccessPointsCommand, DescribeBackupPolicyCommand, DescribeFileSystemPolicyCommand, DescribeFileSystemsCommand, DescribeLifecycleConfigurationCommand, DescribeMountTargetSecurityGroupsCommand, DescribeMountTargetsCommand, EFSClient, FileSystemNotFound, ModifyMountTargetSecurityGroupsCommand, MountTargetNotFound, PutBackupPolicyCommand, PutFileSystemPolicyCommand, PutLifecycleConfigurationCommand, UpdateFileSystemCommand, UpdateFileSystemProtectionCommand } from "@aws-sdk/client-efs";
 import { CreateFileSystemCommand as CreateFileSystemCommand$1, CreateFileSystemFromBackupCommand, DeleteFileSystemCommand as DeleteFileSystemCommand$1, DescribeFileSystemsCommand as DescribeFileSystemsCommand$1, FSxClient, FileSystemNotFound as FileSystemNotFound$1, TagResourceCommand as TagResourceCommand$18, UntagResourceCommand as UntagResourceCommand$18, UpdateFileSystemCommand as UpdateFileSystemCommand$1 } from "@aws-sdk/client-fsx";
-import { AddTagsCommand as AddTagsCommand$1, DescribeClusterCommand, EMRClient, InvalidRequestException, ModifyClusterCommand, PutAutoTerminationPolicyCommand, PutManagedScalingPolicyCommand, RemoveAutoTerminationPolicyCommand, RemoveManagedScalingPolicyCommand, RemoveTagsCommand as RemoveTagsCommand$1, RunJobFlowCommand, SetTerminationProtectionCommand, SetVisibleToAllUsersCommand, TerminateJobFlowsCommand } from "@aws-sdk/client-emr";
+import { AddTagsCommand as AddTagsCommand$1, DescribeClusterCommand, EMRClient, InvalidRequestException, ListClustersCommand as ListClustersCommand$1, ListInstanceFleetsCommand, ListInstanceGroupsCommand, ModifyClusterCommand, PutAutoTerminationPolicyCommand, PutManagedScalingPolicyCommand, RemoveAutoTerminationPolicyCommand, RemoveManagedScalingPolicyCommand, RemoveTagsCommand as RemoveTagsCommand$1, RunJobFlowCommand, SetTerminationProtectionCommand, SetVisibleToAllUsersCommand, TerminateJobFlowsCommand } from "@aws-sdk/client-emr";
 import { CreateDeliveryStreamCommand, DeleteDeliveryStreamCommand, DescribeDeliveryStreamCommand, FirehoseClient, ListDeliveryStreamsCommand, ListTagsForDeliveryStreamCommand, ResourceNotFoundException as ResourceNotFoundException$10, TagDeliveryStreamCommand, UntagDeliveryStreamCommand, UpdateDestinationCommand } from "@aws-sdk/client-firehose";
 import { AddTagsCommand as AddTagsCommand$2, CloudTrailClient, CreateTrailCommand, DeleteTrailCommand, GetEventSelectorsCommand, GetInsightSelectorsCommand, GetTrailCommand, GetTrailStatusCommand, ListTagsCommand as ListTagsCommand$1, ListTrailsCommand, PutEventSelectorsCommand, PutInsightSelectorsCommand, RemoveTagsCommand as RemoveTagsCommand$2, StartLoggingCommand, StopLoggingCommand, TrailNotFoundException, UpdateTrailCommand } from "@aws-sdk/client-cloudtrail";
 import { BatchGetProjectsCommand, CodeBuildClient, CreateProjectCommand, DeleteProjectCommand, ListProjectsCommand, ResourceNotFoundException as ResourceNotFoundException$11, UpdateProjectCommand } from "@aws-sdk/client-codebuild";
@@ -1891,7 +1891,7 @@ const FLUSH_INTERVAL_MS = 2e3;
 const FLUSH_EVENT_THRESHOLD = 50;
 /** Build-time cdkd version, with a dev fallback for non-built contexts. */
 function getCdkdVersion() {
-	return "0.247.0";
+	return "0.248.0";
 }
 /**
 * Generate a time-sortable unique run id, e.g.
@@ -35021,6 +35021,18 @@ const CREATE_READY_STATES = new Set(["WAITING", "RUNNING"]);
 */
 const TERMINAL_STATES = new Set(["TERMINATED", "TERMINATED_WITH_ERRORS"]);
 /**
+* Cluster states that mean "the cluster is alive" — the `ListClusters` filter
+* used by `import()` discovery so a long-gone `TERMINATED*` cluster is never
+* adopted. Everything except the two `TERMINAL_STATES`.
+*/
+const NON_TERMINATED_STATES = [
+	"STARTING",
+	"BOOTSTRAPPING",
+	"RUNNING",
+	"WAITING",
+	"TERMINATING"
+];
+/**
 * Top-level CFn properties that map to a MUTABLE EMR API surface. Every other
 * property is either registry-createOnly (routed through DELETE+CREATE by the
 * replacement-detection layer) or lives inside the `Instances` block (handled
@@ -35520,6 +35532,279 @@ var EMRClusterProvider = class {
 			default: return;
 		}
 	}
+	/**
+	* Adopt an existing EMR cluster into cdkd state.
+	*
+	* Lookup order:
+	*  1. `--resource <logicalId>=j-XXXX` override (`knownPhysicalId`) → verify
+	*     via `DescribeCluster`. There is no template name property that equals
+	*     the physical id — a cluster's id (`j-...`) is service-generated, while
+	*     the template `Name` is only the display name — so no name fallback
+	*     applies (`resolveExplicitPhysicalId(..., null)`).
+	*  2. Tag-based lookup: `ListClusters` filtered to the non-terminated states
+	*     (a `TERMINATED*` cluster is gone and must never be adopted), then a
+	*     `DescribeCluster` per candidate to read `Tags` (the list summaries do
+	*     NOT carry tags) and match `aws:cdk:path`.
+	*/
+	async import(input) {
+		const explicit = resolveExplicitPhysicalId(input, null);
+		if (explicit) {
+			const cluster = await this.describeClusterOrNull(explicit);
+			if (!cluster || cluster.Status?.State && TERMINAL_STATES.has(cluster.Status.State)) return null;
+			return {
+				physicalId: explicit,
+				attributes: this.buildAttributes(cluster)
+			};
+		}
+		if (!input.cdkPath) return null;
+		let marker;
+		do {
+			const list = await this.getClient().send(new ListClustersCommand$1({
+				ClusterStates: [...NON_TERMINATED_STATES],
+				...marker && { Marker: marker }
+			}));
+			for (const summary of list.Clusters ?? []) {
+				if (!summary.Id) continue;
+				const cluster = await this.describeClusterOrNull(summary.Id);
+				if (!cluster) continue;
+				if (matchesCdkPath(cluster.Tags, input.cdkPath)) return {
+					physicalId: summary.Id,
+					attributes: this.buildAttributes(cluster)
+				};
+			}
+			marker = list.Marker;
+		} while (marker);
+		return null;
+	}
+	/**
+	* `DescribeCluster` that maps a not-found (`InvalidRequestException` — the
+	* cluster id is unknown in this region / aged out of Describe) to `null`
+	* instead of throwing, so `import()` can treat it as "no match" rather than
+	* aborting the whole adoption run.
+	*/
+	async describeClusterOrNull(clusterId) {
+		try {
+			return (await this.getClient().send(new DescribeClusterCommand({ ClusterId: clusterId }))).Cluster;
+		} catch (err) {
+			if (err instanceof InvalidRequestException) return void 0;
+			throw err;
+		}
+	}
+	/**
+	* Read the currently-deployed properties for `cdkd drift` and to seed the
+	* `observedProperties` baseline right after `cdkd import`.
+	*
+	* The bulk of the work is reversing the flatten that `create()` applies to
+	* the CFn `Instances` block: `DescribeCluster` reports the cluster's
+	* `InstanceCollectionType`, and the instance groups / fleets themselves come
+	* from `ListInstanceGroups` / `ListInstanceFleets` as FLAT arrays with a
+	* per-entry `InstanceGroupType` / `InstanceFleetType` discriminator — the
+	* exact inverse of the role-keyed CFn `MasterInstanceGroup` /
+	* `CoreInstanceGroup` / `TaskInstanceGroups` (+ `*InstanceFleet(s)`) shape.
+	* `reverseInstancesToCfn` re-buckets them and folds in the flat
+	* `Ec2InstanceAttributes` (subnet / key name / security groups).
+	*
+	* Scope: the reversible property set — the reverse-mapped `Instances` block,
+	* `Tags` (via `normalizeAwsTagsToCfn`, `aws:*` stripped), and the top-level
+	* scalar fields `DescribeCluster` returns directly. Create-only sub-config
+	* that AWS does not read back faithfully (`ManagedScalingPolicy` /
+	* `AutoTerminationPolicy` — separate Get* APIs; `BootstrapActions` / `Steps`
+	* / `KerberosAttributes` / `Configurations` nesting / `AdditionalInfo` /
+	* `PlacementGroupConfigs`; `Instances` EBS / auto-scaling sub-specs) is
+	* declared in `getDriftUnknownPaths` so the drift comparator skips it on the
+	* `properties`-fallback path instead of firing a guaranteed false positive.
+	* On the normal path the baseline is `observedProperties` (captured via this
+	* same method), so observed == current and there is no phantom drift.
+	*
+	* Returns `undefined` when the cluster is gone (`InvalidRequestException`)
+	* so the caller reports drift-unknown rather than throwing — mirrors the
+	* optional `import` method's incremental opt-in shape.
+	*/
+	async readCurrentState(physicalId, _logicalId, _resourceType) {
+		const cluster = await this.describeClusterOrNull(physicalId);
+		if (!cluster) return void 0;
+		let instanceGroups = [];
+		let instanceFleets = [];
+		if (cluster.InstanceCollectionType === "INSTANCE_FLEET") instanceFleets = await this.listInstanceFleets(physicalId);
+		else instanceGroups = await this.listInstanceGroups(physicalId);
+		return {
+			Name: cluster.Name ?? "",
+			ReleaseLabel: cluster.ReleaseLabel ?? "",
+			ServiceRole: cluster.ServiceRole ?? "",
+			LogUri: cluster.LogUri ?? "",
+			LogEncryptionKmsKeyId: cluster.LogEncryptionKmsKeyId ?? "",
+			AutoScalingRole: cluster.AutoScalingRole ?? "",
+			ScaleDownBehavior: cluster.ScaleDownBehavior ?? "",
+			CustomAmiId: cluster.CustomAmiId ?? "",
+			OSReleaseLabel: cluster.OSReleaseLabel ?? "",
+			SecurityConfiguration: cluster.SecurityConfiguration ?? "",
+			EbsRootVolumeSize: cluster.EbsRootVolumeSize,
+			EbsRootVolumeIops: cluster.EbsRootVolumeIops,
+			EbsRootVolumeThroughput: cluster.EbsRootVolumeThroughput,
+			StepConcurrencyLevel: cluster.StepConcurrencyLevel,
+			VisibleToAllUsers: cluster.VisibleToAllUsers ?? false,
+			JobFlowRole: cluster.Ec2InstanceAttributes?.IamInstanceProfile ?? "",
+			Applications: cluster.Applications ?? [],
+			Tags: normalizeAwsTagsToCfn(cluster.Tags),
+			Instances: this.reverseInstancesToCfn(cluster, instanceGroups, instanceFleets)
+		};
+	}
+	/**
+	* State property paths this provider cannot read back from AWS faithfully,
+	* skipped by the drift comparator to avoid a guaranteed false positive on
+	* the `properties`-fallback path. See `readCurrentState`'s docstring.
+	*
+	* NOTE on the `Instances.*` entries: `reverseInstancesToCfn` deliberately
+	* reconstructs only the primary topology per group / fleet (role, type,
+	* count / capacity, market, bid price, name, custom AMI) — the lossy
+	* sub-specs `create()` reads (`EbsConfiguration` / `AutoScalingPolicy` /
+	* per-group `Configurations`; per-fleet `InstanceTypeConfigs` /
+	* `LaunchSpecifications` / `ResizeSpecifications`) and the top-level
+	* `Instances` fields AWS does not report back (`HadoopVersion` /
+	* `Placement` / `KeepJobFlowAliveWhenNoSteps`) are NOT reconstructed. On the
+	* NORMAL drift path both the `observedProperties` baseline and the current
+	* snapshot go through this same lossy reverse, so these paths are absent
+	* from both sides and never drift — ignoring them there is a no-op. On the
+	* `properties`-fallback path (no `observedProperties`) the baseline is the
+	* full template `Instances`, which DOES carry these sub-fields, so without
+	* the skip every one would fire guaranteed false-positive drift. The two
+	* `Task*` arrays are ignored WHOLE (the comparator compares arrays as leaves,
+	* so an element sub-field cannot be path-targeted); Master/Core groups and
+	* fleets are single objects, so their lossy sub-fields are targeted directly.
+	*/
+	getDriftUnknownPaths(_resourceType) {
+		return [
+			"AdditionalInfo",
+			"Applications",
+			"AutoTerminationPolicy",
+			"BootstrapActions",
+			"Configurations",
+			"Instances.HadoopVersion",
+			"Instances.KeepJobFlowAliveWhenNoSteps",
+			"Instances.Placement",
+			"Instances.CoreInstanceGroup.AutoScalingPolicy",
+			"Instances.CoreInstanceGroup.Configurations",
+			"Instances.CoreInstanceGroup.EbsConfiguration",
+			"Instances.MasterInstanceGroup.AutoScalingPolicy",
+			"Instances.MasterInstanceGroup.Configurations",
+			"Instances.MasterInstanceGroup.EbsConfiguration",
+			"Instances.CoreInstanceFleet.InstanceTypeConfigs",
+			"Instances.CoreInstanceFleet.LaunchSpecifications",
+			"Instances.CoreInstanceFleet.ResizeSpecifications",
+			"Instances.MasterInstanceFleet.InstanceTypeConfigs",
+			"Instances.MasterInstanceFleet.LaunchSpecifications",
+			"Instances.MasterInstanceFleet.ResizeSpecifications",
+			"Instances.TaskInstanceFleets",
+			"Instances.TaskInstanceGroups",
+			"KerberosAttributes",
+			"ManagedScalingPolicy",
+			"PlacementGroupConfigs",
+			"Steps"
+		];
+	}
+	async listInstanceGroups(clusterId) {
+		const groups = [];
+		let marker;
+		do {
+			const resp = await this.getClient().send(new ListInstanceGroupsCommand({
+				ClusterId: clusterId,
+				...marker && { Marker: marker }
+			}));
+			groups.push(...resp.InstanceGroups ?? []);
+			marker = resp.Marker;
+		} while (marker);
+		return groups;
+	}
+	async listInstanceFleets(clusterId) {
+		const fleets = [];
+		let marker;
+		do {
+			const resp = await this.getClient().send(new ListInstanceFleetsCommand({
+				ClusterId: clusterId,
+				...marker && { Marker: marker }
+			}));
+			fleets.push(...resp.InstanceFleets ?? []);
+			marker = resp.Marker;
+		} while (marker);
+		return fleets;
+	}
+	/**
+	* Reverse of `toJobFlowInstancesConfig` — re-bucket the flat SDK
+	* `InstanceGroup[]` / `InstanceFleet[]` (each carrying a role discriminator)
+	* back into the role-keyed CFn `Instances` shape, and fold in the flat
+	* `Ec2InstanceAttributes` (subnet / key name / security groups).
+	*
+	* Only the primary topology fields per group / fleet are reversed (role,
+	* type, count / capacity, market, bid price, name, custom AMI). Lossy
+	* sub-specs (EBS block-device / auto-scaling for groups; per-instance-type
+	* specs for fleets) are intentionally NOT reconstructed — they are covered
+	* by the drift baseline being `observedProperties` on the normal path.
+	*/
+	reverseInstancesToCfn(cluster, instanceGroups, instanceFleets) {
+		const ec2 = cluster.Ec2InstanceAttributes;
+		const instances = {};
+		const taskGroups = [];
+		for (const g of instanceGroups) {
+			const cfn = this.reverseInstanceGroup(g);
+			switch (g.InstanceGroupType) {
+				case "MASTER":
+					instances["MasterInstanceGroup"] = cfn;
+					break;
+				case "CORE":
+					instances["CoreInstanceGroup"] = cfn;
+					break;
+				case "TASK":
+					taskGroups.push(cfn);
+					break;
+			}
+		}
+		if (taskGroups.length > 0) instances["TaskInstanceGroups"] = taskGroups;
+		const taskFleets = [];
+		for (const f of instanceFleets) {
+			const cfn = this.reverseInstanceFleet(f);
+			switch (f.InstanceFleetType) {
+				case "MASTER":
+					instances["MasterInstanceFleet"] = cfn;
+					break;
+				case "CORE":
+					instances["CoreInstanceFleet"] = cfn;
+					break;
+				case "TASK":
+					taskFleets.push(cfn);
+					break;
+			}
+		}
+		if (taskFleets.length > 0) instances["TaskInstanceFleets"] = taskFleets;
+		if (ec2?.Ec2KeyName !== void 0) instances["Ec2KeyName"] = ec2.Ec2KeyName;
+		if (ec2?.Ec2SubnetId !== void 0) instances["Ec2SubnetId"] = ec2.Ec2SubnetId;
+		if (ec2?.RequestedEc2SubnetIds !== void 0) instances["Ec2SubnetIds"] = ec2.RequestedEc2SubnetIds;
+		if (ec2?.EmrManagedMasterSecurityGroup !== void 0) instances["EmrManagedMasterSecurityGroup"] = ec2.EmrManagedMasterSecurityGroup;
+		if (ec2?.EmrManagedSlaveSecurityGroup !== void 0) instances["EmrManagedSlaveSecurityGroup"] = ec2.EmrManagedSlaveSecurityGroup;
+		if (ec2?.ServiceAccessSecurityGroup !== void 0) instances["ServiceAccessSecurityGroup"] = ec2.ServiceAccessSecurityGroup;
+		if (ec2?.AdditionalMasterSecurityGroups !== void 0) instances["AdditionalMasterSecurityGroups"] = ec2.AdditionalMasterSecurityGroups;
+		if (ec2?.AdditionalSlaveSecurityGroups !== void 0) instances["AdditionalSlaveSecurityGroups"] = ec2.AdditionalSlaveSecurityGroups;
+		if (cluster.TerminationProtected !== void 0) instances["TerminationProtected"] = cluster.TerminationProtected;
+		if (cluster.UnhealthyNodeReplacement !== void 0) instances["UnhealthyNodeReplacement"] = cluster.UnhealthyNodeReplacement;
+		return instances;
+	}
+	reverseInstanceGroup(g) {
+		const out = {
+			InstanceType: g.InstanceType ?? "",
+			InstanceCount: g.RequestedInstanceCount ?? 0
+		};
+		if (g.Name !== void 0) out["Name"] = g.Name;
+		if (g.Market !== void 0) out["Market"] = g.Market;
+		if (g.BidPrice !== void 0) out["BidPrice"] = g.BidPrice;
+		if (g.CustomAmiId !== void 0) out["CustomAmiId"] = g.CustomAmiId;
+		return out;
+	}
+	reverseInstanceFleet(f) {
+		const out = {};
+		if (f.Name !== void 0) out["Name"] = f.Name;
+		if (f.TargetOnDemandCapacity !== void 0) out["TargetOnDemandCapacity"] = f.TargetOnDemandCapacity;
+		if (f.TargetSpotCapacity !== void 0) out["TargetSpotCapacity"] = f.TargetSpotCapacity;
+		return out;
+	}
 };
 
 //#endregion
@@ -60412,7 +60697,7 @@ function reorderArgs(argv) {
 async function main() {
 	installPipeCloseHandler();
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.247.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.248.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());