@go-to-k/cdkd 0.27.0 → 0.28.1

package/README.md

@@ -539,9 +539,6 @@ Both flags accept either form on each invocation:
 `TYPE` must look like `AWS::Service::Resource`; malformed types are rejected at parse time. `warn < timeout` is enforced both globally and per-type — so `--resource-warn-after AWS::X=10m --resource-timeout AWS::X=5m` is a parse-time error.
 
 ```bash
-# Bump the per-resource budget to one hour (matches the Custom Resource provider's polling cap)
-cdkd deploy --resource-timeout 1h
-
 # Surface "still running" warnings sooner on a fast-feedback dev loop
 cdkd deploy --resource-warn-after 90s --resource-timeout 10m
 
@@ -550,19 +547,25 @@ cdkd deploy \
   --resource-timeout 30m \
   --resource-timeout AWS::CloudFront::Distribution=1h \
   --resource-timeout AWS::RDS::DBCluster=1h30m
+
+# Force Custom Resources to abort earlier than their 1h self-reported polling cap
+cdkd deploy --resource-timeout AWS::CloudFormation::CustomResource=5m
 ```
 
 ### Why the default is 30m, not 1h
 
-cdkd's Custom Resource provider polls async handlers (`isCompleteHandler` pattern) for up to one hour before giving up. Setting the per-resource timeout to 1h by default would make a single hung Custom Resource hold the whole stack for an hour even though no other resource type ever needs more than a few minutes. A shorter default (`30m`) catches stuck operations faster, and stacks that legitimately rely on long-running Custom Resources opt into the higher budget explicitly with `--resource-timeout 1h`.
+cdkd's Custom Resource provider polls async handlers (`isCompleteHandler` pattern) for up to one hour before giving up. Setting the per-resource timeout to 1h by default would make a single hung non-CR resource hold the whole stack for an hour even though no other resource type ever needs more than a few minutes. The 30m global default catches stuck operations faster.
+
+For Custom Resources specifically, the provider self-reports its 1h polling cap to the engine via the `getMinResourceTimeoutMs()` interface — the deploy engine resolves the per-resource budget as `max(provider self-report, --resource-timeout global)`, so CR resources get their full hour automatically without the user having to remember `--resource-timeout 1h`. To force CR to abort earlier than its self-reported cap, pass an explicit per-type override (`--resource-timeout AWS::CloudFormation::CustomResource=5m`). Per-type overrides always win over the provider's self-report — they're the documented escape hatch.
 
-The error message on timeout names the resource, type, region, elapsed time, and operation, and reminds you to re-run with `--resource-timeout 1h` (or higher) for genuinely-long resources:
+The error message on timeout names the resource, type, region, elapsed time, and operation, and reminds you that long-running resources self-report their needed budget — when you see CR time out, the cause is genuinely the handler, not too-tight a default:
 
 ```text
 Resource MyBucket (AWS::S3::Bucket) in us-east-1 timed out after 30m during CREATE (elapsed 30m).
 This may indicate a stuck Cloud Control polling loop, hung Custom Resource, or
-slow ENI provisioning. Re-run with --resource-timeout 1h if the resource genuinely
-needs more time, or --verbose to see the underlying provider activity.
+slow ENI provisioning. Re-run with --resource-timeout AWS::S3::Bucket=<DURATION>
+to bump the budget for this resource type only, or --verbose to see the
+underlying provider activity.
 ```
 
 Note: `--resource-warn-after` must be less than `--resource-timeout`. Reversed values are rejected at parse time.
@@ -675,6 +678,20 @@ out of a larger stack — for example, you have one S3 bucket that was
 created manually that you want cdkd to manage, while the rest of the
 stack will be deployed fresh.
 
+**Selective mode is non-destructive.** When state already exists for
+the stack, listed resources are **merged** into it: unlisted entries
+already in state are preserved (no `--force` needed). `--force` is
+only required when a listed override would overwrite a resource
+already in state — that's the one case where the merge is destructive.
+This is the right command for "I have a deployed stack and want to
+adopt one more resource into it":
+
+```bash
+# Existing state has Queue + Topic; add Bucket without affecting them.
+cdkd import MyStack --resource MyBucket=my-bucket-name
+# Resulting state: Queue + Topic (preserved) + Bucket (newly imported).
+```
+
 ### Mode 3: hybrid (`--auto` with overrides)
 
 ```bash
@@ -695,7 +712,18 @@ the rest by tag automatically.
 | ----------- | ----------------------------------------------------------------------------- |
 | `--dry-run` | Preview what would be imported. State is NOT written.                         |
 | `--yes`     | Skip the confirmation prompt before writing state.                            |
-| `--force`   | Overwrite an existing state record. Without this, existing state aborts.      |
+| `--force`   | Confirm a destructive write to existing state — see below.                    |
+
+`--force` is only needed when the import would lose data:
+
+- **Auto / whole-stack mode + existing state**: required. The resource
+  map is rebuilt from the template, so any state entry not re-imported
+  is dropped.
+- **Selective mode + listed override already in state**: required.
+  The listed entry is overwritten with the new physical id.
+- **Selective mode without a conflict (pure merge)**: not required.
+  Unlisted state entries are preserved automatically.
+- **No existing state (first-time import)**: not required.
 
 ### After import
 
@@ -743,7 +771,7 @@ table to predict behavior when migrating from `cdk import`.
 | Bootstrap requirement | Bootstrap v12+ (deploy role needs to read the encrypted staging bucket). | cdkd's own state bucket; no CDK bootstrap version requirement. |
 | Resource-type coverage | Whatever [CloudFormation supports for import](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html). | The set of cdkd providers that implement `import()` (see [CLAUDE.md](CLAUDE.md) for the current list). For any other CC-API-supported type, use `--resource <id>=<physical>` to drive the Cloud Control API fallback. The two lists overlap heavily but are not identical. |
 | Confirmation prompt before writing state | n/a (CloudFormation operates atomically). | Yes — cdkd asks before writing the state file. Skip with `--yes`. |
-| `--force` | "Continue even if the diff includes updates or deletions" — about diff strictness. | "Overwrite an existing state record" — about state safety. **Same flag name, different meaning.** |
+| `--force` | "Continue even if the diff includes updates or deletions" — about diff strictness. | "Confirm a destructive write to existing state" — required for auto/whole-stack rebuild and for overwriting a listed entry already in state; not required for a pure selective merge. **Same flag name, different meaning.** |
 | `--dry-run` | Implied by `--no-execute` (creates the changeset without executing). | Native: shows the import plan and exits without writing state. |
 
 #### Practical implications when migrating from `cdk import`

package/dist/cli.js

@@ -1133,8 +1133,9 @@ var ResourceTimeoutError = class _ResourceTimeoutError extends CdkdError {
     super(
       `Resource ${logicalId} (${resourceType}) in ${region} timed out after ${timeoutLabel} during ${operation} (elapsed ${elapsedLabel}).
 This may indicate a stuck Cloud Control polling loop, hung Custom Resource, or
-slow ENI provisioning. Re-run with --resource-timeout 1h if the resource genuinely
-needs more time, or --verbose to see the underlying provider activity.`,
+slow ENI provisioning. Re-run with --resource-timeout ${resourceType}=<DURATION>
+to bump the budget for this resource type only, or --verbose to see the
+underlying provider activity.`,
       "RESOURCE_TIMEOUT"
     );
     this.logicalId = logicalId;
@@ -7448,6 +7449,23 @@ var CustomResourceProvider = class _CustomResourceProvider {
   logger = getLogger().child("CustomResourceProvider");
   responseBucket;
   responsePrefix;
+  /**
+   * Opt out of the deploy engine's outer transient-error retry loop.
+   *
+   * The loop re-invokes `provider.create()` from the top on a transient
+   * SDK error (IAM propagation, HTTP 429/503, etc.). Each invocation
+   * generates a brand-new RequestId and a brand-new pre-signed S3
+   * response URL via `prepareInvocation()`. If the underlying Lambda has
+   * already started — e.g. an outer retry fired between the placeholder
+   * `PutObject` and the `Invoke`, or after the `Invoke` returned but a
+   * spurious downstream error fired — the first attempt's Lambda
+   * response lands at an S3 key that nobody polls, hanging the deploy
+   * until the polling timeout. The provider already polls with its own
+   * exponential backoff for async patterns (CDK Provider framework with
+   * isCompleteHandler), so an outer retry adds nothing but the multi-
+   * key bug.
+   */
+  disableOuterRetry = true;
   /** Max time to wait for synchronous S3 response after Lambda invocation (30 seconds) */
   SYNC_RESPONSE_TIMEOUT_MS = 3e4;
   /** Max time to wait for async S3 response (CDK Provider framework with isCompleteHandler) */
@@ -7467,6 +7485,22 @@ var CustomResourceProvider = class _CustomResourceProvider {
     this.responsePrefix = config?.responsePrefix ?? "custom-resource-responses";
     this.asyncResponseTimeoutMs = config?.asyncResponseTimeoutMs ?? _CustomResourceProvider.DEFAULT_ASYNC_RESPONSE_TIMEOUT_MS;
   }
+  /**
+   * Self-reported minimum per-resource timeout.
+   *
+   * Custom Resource async invocations (CDK Provider framework with
+   * `isCompleteHandler`) poll for up to `asyncResponseTimeoutMs`
+   * (default 1 hour, matching CDK's `totalTimeout` default). The deploy
+   * engine's global `--resource-timeout` default is 30 minutes, which
+   * would abort a perfectly healthy CR mid-poll. By self-reporting the
+   * polling cap, the engine lifts the deadline to `max(self-report,
+   * global)` for CR resources only; a user-supplied per-type override
+   * (`--resource-timeout AWS::CloudFormation::CustomResource=5m`) still
+   * wins for explicit escape-hatching.
+   */
+  getMinResourceTimeoutMs() {
+    return this.asyncResponseTimeoutMs;
+  }
   /**
    * Set the S3 bucket for custom resource responses
    * Called by ProviderRegistry when state bucket is configured
@@ -31890,8 +31924,11 @@ var DeployEngine = class {
     const baseLabel = `${verb} ${logicalId} (${resourceType})`;
     renderer.addTask(logicalId, baseLabel);
     const operationKind = change.changeType === "CREATE" ? "CREATE" : change.changeType === "DELETE" ? "DELETE" : "UPDATE";
+    const provider = this.providerRegistry.getProvider(resourceType);
+    const providerMinTimeoutMs = provider.getMinResourceTimeoutMs?.() ?? 0;
     const warnAfterMs = this.options.resourceWarnAfterByType?.[resourceType] ?? this.options.resourceWarnAfterMs ?? DEFAULT_RESOURCE_WARN_AFTER_MS;
-    const timeoutMs = this.options.resourceTimeoutByType?.[resourceType] ?? this.options.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
+    const globalTimeoutMs = this.options.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
+    const timeoutMs = this.options.resourceTimeoutByType?.[resourceType] ?? Math.max(providerMinTimeoutMs, globalTimeoutMs);
     try {
       await withResourceDeadline(
         async () => {
@@ -31970,7 +32007,10 @@ var DeployEngine = class {
         const { provider: createProvider, properties: createProps } = this.selectProviderWithSafetyNet(provider, resourceType, resolvedProps, logicalId);
         const result = await this.withRetry(
           () => createProvider.create(logicalId, resourceType, createProps),
-          logicalId
+          logicalId,
+          void 0,
+          void 0,
+          provider
         );
         const dependencies = this.extractAllDependencies(template, logicalId);
         stateResources[logicalId] = {
@@ -32024,7 +32064,10 @@ var DeployEngine = class {
           const { provider: replaceProvider, properties: replaceProps } = this.selectProviderWithSafetyNet(provider, resourceType, resolvedProps, logicalId);
           const createResult = await this.withRetry(
             () => replaceProvider.create(logicalId, resourceType, replaceProps),
-            logicalId
+            logicalId,
+            void 0,
+            void 0,
+            provider
           );
           const updateReplacePolicy = template?.Resources?.[logicalId]?.UpdateReplacePolicy;
           if (updateReplacePolicy === "Retain") {
@@ -32075,7 +32118,10 @@ var DeployEngine = class {
                 updateProps,
                 currentProps
               ),
-              logicalId
+              logicalId,
+              void 0,
+              void 0,
+              provider
             );
           } catch (updateError) {
             const msg = updateError instanceof Error ? updateError.message : String(updateError);
@@ -32104,7 +32150,10 @@ var DeployEngine = class {
               const { provider: replProvider, properties: replProps } = this.selectProviderWithSafetyNet(provider, resourceType, resolvedProps, logicalId);
               const createResult = await this.withRetry(
                 () => replProvider.create(logicalId, resourceType, replProps),
-                logicalId
+                logicalId,
+                void 0,
+                void 0,
+                provider
               );
               result = {
                 physicalId: createResult.physicalId,
@@ -32161,7 +32210,8 @@ var DeployEngine = class {
             logicalId,
             3,
             // fewer retries for DELETE
-            5e3
+            5e3,
+            provider
           );
         } catch (deleteError) {
           const msg = deleteError instanceof Error ? deleteError.message : String(deleteError);
@@ -32338,8 +32388,18 @@ var DeployEngine = class {
    * Thin wrapper over `withRetry` from ./retry.js that injects this engine's
    * SIGINT-aware interrupt check and logger. The actual backoff schedule
    * lives there.
+   *
+   * When the provider opts out via `disableOuterRetry`, the operation is
+   * invoked exactly once and the retry loop is skipped entirely. The
+   * Custom Resource provider uses this to avoid re-running its `create()`
+   * — each invocation derives a fresh pre-signed S3 URL and RequestId,
+   * so an outer retry leaves the previous attempt's Lambda response
+   * stranded at an S3 key nobody polls.
    */
-  async withRetry(operation, logicalId, maxRetries, initialDelayMs) {
+  async withRetry(operation, logicalId, maxRetries, initialDelayMs, provider) {
+    if (provider?.disableOuterRetry) {
+      return operation();
+    }
     return withRetry(operation, logicalId, {
       ...maxRetries !== void 0 && { maxRetries },
       ...initialDelayMs !== void 0 && { initialDelayMs },
@@ -33019,16 +33079,19 @@ Acquiring lock for stack ${stackName}...`);
           logger.warn(`Resource ${logicalId} not found in state, skipping`);
           return;
         }
-        const warnAfterMs = ctx.resourceWarnAfterByType?.[resource.resourceType] ?? ctx.resourceWarnAfterMs ?? DEFAULT_RESOURCE_WARN_AFTER_MS;
-        const timeoutMs = ctx.resourceTimeoutByType?.[resource.resourceType] ?? ctx.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
         const baseLabel = `Deleting ${logicalId} (${resource.resourceType})`;
         renderer.addTask(logicalId, baseLabel);
         try {
           const provider = destroyProviderRegistry.getProvider(resource.resourceType);
+          const providerMinTimeoutMs = provider.getMinResourceTimeoutMs?.() ?? 0;
+          const warnAfterMs = ctx.resourceWarnAfterByType?.[resource.resourceType] ?? ctx.resourceWarnAfterMs ?? DEFAULT_RESOURCE_WARN_AFTER_MS;
+          const globalTimeoutMs = ctx.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
+          const timeoutMs = ctx.resourceTimeoutByType?.[resource.resourceType] ?? Math.max(providerMinTimeoutMs, globalTimeoutMs);
           await withResourceDeadline(
             async () => {
+              const maxAttempts = provider.disableOuterRetry ? 0 : 3;
               let lastDeleteError;
-              for (let attempt = 0; attempt <= 3; attempt++) {
+              for (let attempt = 0; attempt <= maxAttempts; attempt++) {
                 try {
                   await provider.delete(
                     logicalId,
@@ -33042,11 +33105,11 @@ Acquiring lock for stack ${stackName}...`);
                   lastDeleteError = retryError;
                   const msg = retryError instanceof Error ? retryError.message : String(retryError);
                   const isRetryable = msg.includes("Too Many Requests") || msg.includes("has dependencies") || msg.includes("can't be deleted since") || msg.includes("DependencyViolation");
-                  if (!isRetryable || attempt >= 3)
+                  if (!isRetryable || attempt >= maxAttempts)
                     break;
                   const delay = 5e3 * Math.pow(2, attempt);
                   logger.debug(
-                    `  \u23F3 Retrying delete ${logicalId} in ${delay / 1e3}s (attempt ${attempt + 1}/3)`
+                    `  \u23F3 Retrying delete ${logicalId} in ${delay / 1e3}s (attempt ${attempt + 1}/${maxAttempts})`
                   );
                   await new Promise((resolve4) => setTimeout(resolve4, delay));
                 }
@@ -35196,12 +35259,6 @@ async function importCommand(stackArg, options) {
     }
     const targetRegion = stackInfo.region || region;
     logger.info(`Target stack: ${stackInfo.stackName} (${targetRegion})`);
-    const existing = await stateBackend.stateExists(stackInfo.stackName, targetRegion);
-    if (existing && !options.force) {
-      throw new Error(
-        `State already exists for stack '${stackInfo.stackName}' (${targetRegion}). Pass --force to overwrite. (cdkd state import rebuilds the resource map from AWS, so the existing state \u2014 including any drift you've manually edited \u2014 will be lost.)`
-      );
-    }
     const overrides = parseResourceOverrides(
       options.resource,
       options.resourceMapping,
@@ -35216,6 +35273,34 @@ async function importCommand(stackArg, options) {
         `Selective mode: only importing the ${overrides.size} resource(s) you listed (${[...overrides.keys()].join(", ")}). Pass --auto to also tag-import the rest.`
       );
     }
+    const existingResult = await stateBackend.getState(stackInfo.stackName, targetRegion);
+    const existingState = existingResult?.state ?? null;
+    const existingEtag = existingResult?.etag;
+    const migrationPending = existingResult?.migrationPending ?? false;
+    if (existingState) {
+      if (!selectiveMode) {
+        if (!options.force) {
+          throw new Error(
+            `State already exists for stack '${stackInfo.stackName}' (${targetRegion}). Auto / whole-stack import rebuilds the entire resource map from the template, which would drop any state entry not re-imported. Pass --force to confirm. To add specific resources without affecting unlisted ones, use --resource <id>=<physicalId> (selective merge \u2014 no --force needed).`
+          );
+        }
+      } else {
+        const conflicts = [...overrides.keys()].filter(
+          (id) => Object.prototype.hasOwnProperty.call(existingState.resources, id)
+        );
+        if (conflicts.length > 0 && !options.force) {
+          throw new Error(
+            `Selective import would overwrite resource(s) already in state: ${conflicts.join(", ")}. Pass --force to confirm the overwrite, or remove these IDs from --resource / --resource-mapping.`
+          );
+        }
+        const preservedCount = Object.keys(existingState.resources).filter(
+          (id) => !overrides.has(id)
+        ).length;
+        logger.info(
+          `Merging into existing state for ${stackInfo.stackName} (${targetRegion}): preserving ${preservedCount} unlisted resource(s)` + (conflicts.length > 0 ? `, overwriting ${conflicts.length} listed entry(ies)` : "")
+        );
+      }
+    }
     const template = stackInfo.template;
     const templateParser = new TemplateParser();
     const resources = collectImportableResources(template);
@@ -35266,8 +35351,12 @@ async function importCommand(stackArg, options) {
         return;
       }
       if (!options.yes) {
+        const importedCount = importedRows.length;
+        const preservedCount = selectiveMode && existingState ? Object.keys(existingState.resources).filter((id) => !overrides.has(id)).length : 0;
+        const totalAfter = importedCount + preservedCount;
+        const breakdown = preservedCount > 0 ? ` (${importedCount} new/overwritten + ${preservedCount} preserved)` : "";
         const ok = await confirmPrompt3(
-          `Write state for ${stackInfo.stackName} (${targetRegion}) with ${importedRows.length} resource(s)?`
+          `Write state for ${stackInfo.stackName} (${targetRegion}) with ${totalAfter} resource(s)${breakdown}?`
         );
         if (!ok) {
           logger.info("Import cancelled.");
@@ -35279,9 +35368,18 @@ async function importCommand(stackArg, options) {
         targetRegion,
         rows,
         templateParser,
-        template
+        template,
+        existingState,
+        selectiveMode
       );
-      await stateBackend.saveState(stackInfo.stackName, targetRegion, stackState);
+      const saveOptions = {};
+      if (existingEtag) {
+        saveOptions.expectedEtag = existingEtag;
+      }
+      if (migrationPending) {
+        saveOptions.migrateLegacy = true;
+      }
+      await stateBackend.saveState(stackInfo.stackName, targetRegion, stackState, saveOptions);
       logger.info(`\u2713 State written: ${stackInfo.stackName} (${targetRegion})`);
       logger.info(
         `  ${importedRows.length} resource(s) imported. Run 'cdkd diff' to see how the imported state lines up with the template.`
@@ -35437,8 +35535,8 @@ function collectImportableResources(template) {
   }
   return out;
 }
-function buildStackState(stackName, region, rows, templateParser, template) {
-  const resources = {};
+function buildStackState(stackName, region, rows, templateParser, template, existingState, selectiveMode) {
+  const resources = selectiveMode && existingState ? { ...existingState.resources } : {};
   for (const row of rows) {
     if (row.outcome !== "imported" || !row.physicalId)
       continue;
@@ -35459,7 +35557,7 @@ function buildStackState(stackName, region, rows, templateParser, template) {
     stackName,
     region,
     resources,
-    outputs: {},
+    outputs: existingState?.outputs ?? {},
     lastModified: Date.now()
   };
 }
@@ -35534,7 +35632,7 @@ function createImportCommand() {
     false
   ).option("--dry-run", "Show planned imports without writing state", false).option(
     "--force",
-    "Overwrite an existing state record. Without this, an existing state file aborts the import.",
+    "Confirm a destructive write to existing state. Required for auto / whole-stack import when state already exists (rebuilds the entire resource map). Also required in selective mode if a listed override would overwrite a resource already in state. Not needed for a pure selective merge (adding new resources without touching unlisted entries).",
     false
   ).action(withErrorHandling(importCommand));
   [...commonOptions, ...appOptions, ...stateOptions, ...contextOptions].forEach(
@@ -35573,7 +35671,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.27.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.28.1");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());