@go-to-k/cdkd 0.30.2 → 0.31.1

package/README.md

@@ -24,7 +24,7 @@
 - **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
 - **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
 - **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
-- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache and return as soon as the create call returns (CloudFormation always blocks)
+- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
 
 > **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. If you encounter an unsupported resource type, deployment will fail with a clear error message.
 
@@ -372,11 +372,11 @@ cdkd state destroy MyStack --region us-east-1
 
 ## `--no-wait`: skip async-resource waits
 
-CloudFront Distributions, RDS Clusters/Instances, and ElastiCache
-typically take 3–15 minutes for AWS to fully propagate. By default
-cdkd waits for them to reach a ready state — the same behavior as
-CloudFormation. Pass `--no-wait` to return as soon as the create call
-returns:
+CloudFront Distributions, RDS Clusters/Instances, ElastiCache, and
+NAT Gateways typically take 1–15 minutes for AWS to fully provision.
+By default cdkd waits for them to reach a ready state — the same
+behavior as CloudFormation. Pass `--no-wait` to return as soon as the
+create call returns:
 
 ```bash
 cdkd deploy --no-wait
@@ -386,6 +386,25 @@ The resource is fully functional once AWS finishes the async
 deployment in the background. CloudFormation has no equivalent — once
 you submit a stack, you wait for everything.
 
+NAT Gateway is included as of v0.31. Provisioning typically takes
+1–2 minutes and is the dominant cost in many VPC stacks; with
+`cdkd deploy --no-wait`, `CreateNatGateway` returns the `NatGatewayId`
+immediately and dependent Routes that only reference the ID can
+proceed against a still-`pending` gateway. AWS continues NAT
+provisioning asynchronously after the deploy returns. Use this only
+when nothing in the deploy flow needs actual NAT-routed egress (e.g.
+no Lambda invoked during deploy that hits the internet).
+
+`--no-wait` is **deploy-only**. `cdkd destroy` always waits for NAT
+Gateway to reach `deleted` state — while the gateway is in
+`deleting` AWS keeps the ENI / EIP / route-table associations
+attached, so any concurrent `DeleteSubnet` / `DeleteInternetGateway`
+/ `DeleteVpc` returns `DependencyViolation` and the destroy enters a
+retry storm. Other `--no-wait` resources (CloudFront / RDS /
+ElastiCache) don't apply to destroy either — their providers are
+already non-blocking on delete because they're leaves in the destroy
+DAG.
+
 ## Other CLI flags
 
 For concurrency knobs (`--concurrency`, `--stack-concurrency`,
@@ -395,6 +414,24 @@ per-resource timeout flags (`--resource-warn-after`,
 and the rationale for the 30m default), see
 **[docs/cli-reference.md](docs/cli-reference.md)**.
 
+## Exit codes
+
+cdkd commands distinguish three outcomes via the process exit code so
+CI / bench scripts can react without grepping log output:
+
+| Exit | Meaning |
+|------|---------|
+| `0` | Success — command completed and no resources are in an error state |
+| `1` | Command-level failure — auth error, bad arguments, synth crash, unhandled exception |
+| `2` | **Partial failure** — work completed but one or more resources failed (state.json is preserved, re-running typically resolves it) |
+
+Exit `2` is currently emitted by `cdkd destroy` and `cdkd state
+destroy` when one or more per-resource deletes fail. The summary line
+also switches from `✓ Stack X destroyed` to `⚠ Stack X partially
+destroyed (...). State preserved — re-run 'cdkd destroy' / 'cdkd
+state destroy' to clean up.` so the visual marker matches the exit
+code.
+
 ## Example
 
 ```typescript

package/dist/cli.js

@@ -606,6 +606,10 @@ function validateResourceTimeouts(opts) {
     }
   }
 }
+var noWaitOption = new Option(
+  "--no-wait",
+  "Skip waiting for async resources to stabilize (CloudFront, RDS, ElastiCache, NAT Gateway)"
+);
 var deployOptions = [
   new Option("--concurrency <number>", "Maximum concurrent resource operations").default(10).argParser((value) => parseInt(value, 10)),
   new Option("--stack-concurrency <number>", "Maximum concurrent stack deployments").default(4).argParser((value) => parseInt(value, 10)),
@@ -617,7 +621,7 @@ var deployOptions = [
   new Option("--dry-run", "Show changes without applying").default(false),
   new Option("--skip-assets", "Skip asset publishing").default(false),
   new Option("--no-rollback", "Skip rollback on deployment failure"),
-  new Option("--no-wait", "Skip waiting for async resources (CloudFront, RDS, etc.)"),
+  noWaitOption,
   new Option(
     "-e, --exclusively",
     "Only deploy requested stacks, do not include dependencies"
@@ -1166,6 +1170,14 @@ var DependencyError = class _DependencyError extends CdkdError {
     Object.setPrototypeOf(this, _DependencyError.prototype);
   }
 };
+var PartialFailureError = class _PartialFailureError extends CdkdError {
+  exitCode = 2;
+  constructor(message, cause) {
+    super(message, "PARTIAL_FAILURE", cause);
+    this.name = "PartialFailureError";
+    Object.setPrototypeOf(this, _PartialFailureError.prototype);
+  }
+};
 function isCdkdError(error) {
   return error instanceof CdkdError;
 }
@@ -1189,7 +1201,8 @@ function handleError(error) {
   if (error instanceof Error && error.stack) {
     logger.debug("Stack trace:", error.stack);
   }
-  process.exit(1);
+  const exitCode = error instanceof PartialFailureError ? error.exitCode : 1;
+  process.exit(exitCode);
 }
 function withErrorHandling(fn) {
   return async (...args) => {
@@ -16790,6 +16803,11 @@ import {
   DeleteInternetGatewayCommand,
   AttachInternetGatewayCommand,
   DetachInternetGatewayCommand,
+  CreateNatGatewayCommand,
+  DeleteNatGatewayCommand,
+  DescribeNatGatewaysCommand,
+  waitUntilNatGatewayAvailable,
+  waitUntilNatGatewayDeleted,
   CreateRouteTableCommand,
   DeleteRouteTableCommand,
   CreateRouteCommand,
@@ -16835,6 +16853,20 @@ var EC2Provider = class {
     ],
     ["AWS::EC2::InternetGateway", /* @__PURE__ */ new Set(["Tags"])],
     ["AWS::EC2::VPCGatewayAttachment", /* @__PURE__ */ new Set(["VpcId", "InternetGatewayId"])],
+    [
+      "AWS::EC2::NatGateway",
+      /* @__PURE__ */ new Set([
+        "AllocationId",
+        "SubnetId",
+        "ConnectivityType",
+        "PrivateIpAddress",
+        "SecondaryAllocationIds",
+        "SecondaryPrivateIpAddresses",
+        "SecondaryPrivateIpAddressCount",
+        "MaxDrainDurationSeconds",
+        "Tags"
+      ])
+    ],
     ["AWS::EC2::RouteTable", /* @__PURE__ */ new Set(["VpcId", "Tags"])],
     [
       "AWS::EC2::Route",
@@ -16922,6 +16954,8 @@ var EC2Provider = class {
         return this.createInternetGateway(logicalId, resourceType, properties);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.createVpcGatewayAttachment(logicalId, resourceType, properties);
+      case "AWS::EC2::NatGateway":
+        return this.createNatGateway(logicalId, resourceType, properties);
       case "AWS::EC2::RouteTable":
         return this.createRouteTable(logicalId, resourceType, properties);
       case "AWS::EC2::Route":
@@ -16958,6 +16992,8 @@ var EC2Provider = class {
         return this.updateInternetGateway(logicalId, physicalId);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.updateVpcGatewayAttachment(logicalId, physicalId);
+      case "AWS::EC2::NatGateway":
+        return this.updateNatGateway(logicalId, physicalId);
       case "AWS::EC2::RouteTable":
         return this.updateRouteTable(logicalId, physicalId);
       case "AWS::EC2::Route":
@@ -17011,6 +17047,8 @@ var EC2Provider = class {
         return this.deleteInternetGateway(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::VPCGatewayAttachment":
         return this.deleteVpcGatewayAttachment(logicalId, physicalId, resourceType, context);
+      case "AWS::EC2::NatGateway":
+        return this.deleteNatGateway(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::RouteTable":
         return this.deleteRouteTable(logicalId, physicalId, resourceType, context);
       case "AWS::EC2::Route":
@@ -17579,6 +17617,118 @@ var EC2Provider = class {
       );
     }
   }
+  // ─── AWS::EC2::NatGateway ─────────────────────────────────────────
+  //
+  // CloudFormation parity: by default we wait for the new NAT gateway to
+  // reach `available` state before marking the resource created. NAT
+  // provisioning takes ~1–2 minutes (often the longest single step in a
+  // VPC stack). Pass `--no-wait` to skip the wait — `CreateNatGateway`
+  // returns the `NatGatewayId` immediately so dependent Routes /
+  // Subnets that only need the ID can proceed against a still-`pending`
+  // gateway. Anything that requires actual NAT-routed egress (e.g. a
+  // Lambda invocation that hits the internet during deploy) must not
+  // rely on the gateway being live; with `--no-wait`, AWS continues
+  // provisioning asynchronously after the deploy returns.
+  async createNatGateway(logicalId, resourceType, properties) {
+    this.logger.debug(`Creating NatGateway ${logicalId}`);
+    const subnetId = properties["SubnetId"];
+    if (!subnetId) {
+      throw new ProvisioningError(
+        `SubnetId is required for NatGateway ${logicalId}`,
+        resourceType,
+        logicalId
+      );
+    }
+    try {
+      const response = await this.ec2Client.send(
+        new CreateNatGatewayCommand({
+          SubnetId: subnetId,
+          AllocationId: properties["AllocationId"],
+          ConnectivityType: properties["ConnectivityType"] ?? void 0,
+          PrivateIpAddress: properties["PrivateIpAddress"],
+          SecondaryAllocationIds: properties["SecondaryAllocationIds"],
+          SecondaryPrivateIpAddresses: properties["SecondaryPrivateIpAddresses"],
+          SecondaryPrivateIpAddressCount: properties["SecondaryPrivateIpAddressCount"]
+        })
+      );
+      const natGatewayId = response.NatGateway.NatGatewayId;
+      await this.applyTags(natGatewayId, properties, logicalId);
+      if (process.env["CDKD_NO_WAIT"] !== "true") {
+        this.logger.debug(`Waiting for NatGateway ${natGatewayId} to reach available state...`);
+        await waitUntilNatGatewayAvailable(
+          // 15-min cap matches AWS's documented worst case for NAT
+          // provisioning. Per-resource `--resource-timeout` (default
+          // 30 min) still bounds the outer call as a backstop.
+          { client: this.ec2Client, maxWaitTime: 15 * 60 },
+          { NatGatewayIds: [natGatewayId] }
+        );
+        this.logger.debug(`NatGateway ${natGatewayId} is available`);
+      } else {
+        this.logger.debug(
+          `NatGateway ${natGatewayId} created (skipping available-state wait per --no-wait)`
+        );
+      }
+      this.logger.debug(`Successfully created NatGateway ${logicalId}: ${natGatewayId}`);
+      return {
+        physicalId: natGatewayId,
+        attributes: {
+          NatGatewayId: natGatewayId
+        }
+      };
+    } catch (error) {
+      const cause = error instanceof Error ? error : void 0;
+      throw new ProvisioningError(
+        `Failed to create NatGateway ${logicalId}: ${error instanceof Error ? error.message : String(error)}`,
+        resourceType,
+        logicalId,
+        void 0,
+        cause
+      );
+    }
+  }
+  updateNatGateway(logicalId, physicalId) {
+    this.logger.debug(`Updating NatGateway ${logicalId}: ${physicalId} (no-op)`);
+    return Promise.resolve({ physicalId, wasReplaced: false });
+  }
+  async deleteNatGateway(logicalId, physicalId, resourceType, context) {
+    this.logger.debug(`Deleting NatGateway ${logicalId}: ${physicalId}`);
+    try {
+      await this.ec2Client.send(new DeleteNatGatewayCommand({ NatGatewayId: physicalId }));
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        const clientRegion = await this.ec2Client.config.region();
+        assertRegionMatch(
+          clientRegion,
+          context?.expectedRegion,
+          resourceType,
+          logicalId,
+          physicalId
+        );
+        this.logger.debug(`NatGateway ${physicalId} does not exist, skipping deletion`);
+        return;
+      }
+      const cause = error instanceof Error ? error : void 0;
+      throw new ProvisioningError(
+        `Failed to delete NatGateway ${logicalId}: ${error instanceof Error ? error.message : String(error)}`,
+        resourceType,
+        logicalId,
+        physicalId,
+        cause
+      );
+    }
+    this.logger.debug(`Waiting for NatGateway ${physicalId} to reach deleted state...`);
+    try {
+      await waitUntilNatGatewayDeleted(
+        { client: this.ec2Client, maxWaitTime: 15 * 60 },
+        { NatGatewayIds: [physicalId] }
+      );
+    } catch (error) {
+      this.logger.warn(
+        `Wait for NatGateway ${physicalId} deletion did not complete cleanly: ${error instanceof Error ? error.message : String(error)} \u2014 proceeding with downstream delete steps`
+      );
+    }
+    this.logger.debug(`Successfully deleted NatGateway ${logicalId}`);
+  }
   // ─── AWS::EC2::RouteTable ─────────────────────────────────────────
   async createRouteTable(logicalId, resourceType, properties) {
     this.logger.debug(`Creating RouteTable ${logicalId}`);
@@ -18788,6 +18938,15 @@ var EC2Provider = class {
           const sg = resp.SecurityGroups?.[0];
           return sg?.GroupId ? { physicalId: sg.GroupId, attributes: {} } : null;
         }
+        case "AWS::EC2::NatGateway": {
+          const resp = await this.ec2Client.send(
+            new DescribeNatGatewaysCommand({
+              Filter: [{ Name: `tag:${CDK_PATH_TAG}`, Values: [input.cdkPath] }]
+            })
+          );
+          const gw = resp.NatGateways?.find((g) => g.State !== "deleted" && g.State !== "deleting");
+          return gw?.NatGatewayId ? { physicalId: gw.NatGatewayId, attributes: {} } : null;
+        }
         default:
           return null;
       }
@@ -18816,6 +18975,13 @@ var EC2Provider = class {
           );
           return resp.SecurityGroups?.[0] ? { physicalId, attributes: {} } : null;
         }
+        case "AWS::EC2::NatGateway": {
+          const resp = await this.ec2Client.send(
+            new DescribeNatGatewaysCommand({ NatGatewayIds: [physicalId] })
+          );
+          const gw = resp.NatGateways?.find((g) => g.State !== "deleted" && g.State !== "deleting");
+          return gw ? { physicalId, attributes: {} } : null;
+        }
         default:
           return null;
       }
@@ -31139,6 +31305,7 @@ function registerAllProviders(registry) {
   registry.register("AWS::EC2::Subnet", ec2Provider);
   registry.register("AWS::EC2::InternetGateway", ec2Provider);
   registry.register("AWS::EC2::VPCGatewayAttachment", ec2Provider);
+  registry.register("AWS::EC2::NatGateway", ec2Provider);
   registry.register("AWS::EC2::RouteTable", ec2Provider);
   registry.register("AWS::EC2::Route", ec2Provider);
   registry.register("AWS::EC2::SubnetRouteTableAssociation", ec2Provider);
@@ -33390,10 +33557,17 @@ Acquiring lock for stack ${stackName}...`);
     } else {
       logger.warn(`${result.errorCount} resource(s) failed to delete. State preserved.`);
     }
-    logger.info(
-      `
+    if (result.errorCount === 0) {
+      logger.info(
+        `
 \u2713 Stack ${stackName} destroyed (${result.deletedCount} deleted, ${result.errorCount} errors)`
-    );
+      );
+    } else {
+      logger.warn(
+        `
+\u26A0 Stack ${stackName} partially destroyed (${result.deletedCount} deleted, ${result.errorCount} errors). State preserved \u2014 re-run 'cdkd destroy' / 'cdkd state destroy' to clean up.`
+      );
+    }
   } finally {
     renderer.stop();
     logger.debug("Releasing lock...");
@@ -33513,6 +33687,7 @@ async function destroyCommand(stackArgs, options) {
       arr.push(ref);
       stateRefsByName.set(ref.stackName, arr);
     }
+    let totalErrors = 0;
     for (const stackName of stackNames) {
       logger.info(`
 Preparing to destroy stack: ${stackName}`);
@@ -33543,7 +33718,7 @@ Preparing to destroy stack: ${stackName}`);
         logger.warn(`No state found for stack ${stackName}, skipping`);
         continue;
       }
-      await runDestroyForStack(stackName, stateResult.state, {
+      const result = await runDestroyForStack(stackName, stateResult.state, {
         stateBackend,
         lockManager,
         providerRegistry,
@@ -33565,6 +33740,12 @@ Preparing to destroy stack: ${stackName}`);
           resourceTimeoutByType: options.resourceTimeout.perTypeMs
         }
       });
+      totalErrors += result.errorCount;
+    }
+    if (totalErrors > 0) {
+      throw new PartialFailureError(
+        `Destroy completed with ${totalErrors} resource error(s). State preserved \u2014 inspect 'cdkd state show <stack>' and re-run 'cdkd destroy' to retry.`
+      );
     }
   } finally {
     awsClients.destroy();
@@ -35262,8 +35443,8 @@ Preparing to destroy stack: ${stackName}${ref.region ? ` (${ref.region})` : ""}`
       }
     }
     if (totalErrors > 0) {
-      throw new Error(
-        `Destroy completed with ${totalErrors} resource error(s). Inspect 'cdkd state show <stack>' and re-run.`
+      throw new PartialFailureError(
+        `Destroy completed with ${totalErrors} resource error(s). State preserved \u2014 inspect 'cdkd state show <stack>' and re-run 'cdkd state destroy' to retry.`
       );
     }
   } finally {
@@ -36172,7 +36353,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command13();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.30.2");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.31.1");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());