@go-to-k/cdkd 0.21.0 → 0.23.0

package/README.md

@@ -429,13 +429,10 @@ cdkd destroy --all --force
 cdkd force-unlock MyStack
 
 # Adopt already-deployed AWS resources into cdkd state.
-# Reads the CDK app to find logical IDs, types, and dependencies; uses the
-# `aws:cdk:path` tag (or explicit overrides) to find each resource in AWS.
-cdkd import MyStack --app "npx ts-node app.ts" --dry-run            # preview
-cdkd import MyStack --app "npx ts-node app.ts" --yes                # auto-import via tags
-cdkd import MyStack --resource MyBucket=my-bucket-name --yes        # explicit override (repeatable)
-cdkd import MyStack --resource-mapping mapping.json --yes           # CDK CLI mapping-file compat
-cdkd import MyStack --force                                         # overwrite existing state
+# See "Importing existing resources" below for the full guide (auto / selective /
+# hybrid modes, --resource overrides, --resource-mapping CDK CLI compatibility).
+cdkd import MyStack --dry-run
+cdkd import MyStack --yes
 
 # Inspect state-bucket info on demand (bucket name, region, source, schema version, stack count).
 # Routine commands (deploy / destroy / etc.) no longer print the bucket banner by default —
@@ -543,6 +540,107 @@ Built on modern AWS tooling:
 - **Cloud Control API** - Fallback resource management for types without SDK Providers
 - **S3 Conditional Writes** - State locking via `If-None-Match`/`If-Match`
 
+## Importing existing resources
+
+`cdkd import` adopts AWS resources that are already deployed (e.g. via
+`cdk deploy`, manual creation, or another tool) into cdkd state, so the
+next `cdkd deploy` updates them in-place instead of trying to CREATE
+duplicates.
+
+It reads the CDK app to find logical IDs, resource types, and
+dependencies, then matches each logical ID to a real AWS resource in
+one of three modes:
+
+All examples below assume cdkd reads the CDK app command from `cdk.json`
+(the typical case). Pass `--app "<command>"` only if you're running cdkd
+outside the CDK project directory or want to override `cdk.json`.
+
+### Mode 1: auto (default — no flags)
+
+```bash
+cdkd import MyStack
+```
+
+Imports **every** resource in the synthesized template by tag. cdkd
+looks up each resource using its `aws:cdk:path` tag (which CDK
+automatically writes), so resources deployed by `cdk deploy` are found
+without any manual work. Useful for **adopting a whole stack** that was
+previously deployed by `cdk deploy`. This is cdkd's value-add over
+`cdk import` — CDK CLI does not have a tag-based bulk-import mode.
+
+### Mode 2: selective (CDK CLI parity — when explicit overrides are given)
+
+```bash
+# Import ONLY MyBucket; the other resources in the template are left alone.
+cdkd import MyStack --resource MyBucket=my-bucket-name
+
+# Several resources at once (--resource is repeatable).
+cdkd import MyStack \
+  --resource MyBucket=my-bucket-name \
+  --resource MyFn=my-function-name
+
+# CDK CLI compat: read overrides from a JSON file.
+cdkd import MyStack --resource-mapping mapping.json
+# mapping.json: { "MyBucket": "my-bucket-name", "MyFn": "my-function-name" }
+```
+
+When at least one `--resource` flag (or a `--resource-mapping` file) is
+supplied, **only the listed resources are imported**. Every other
+resource in the template is reported as `out of scope` and left out of
+state — the next `cdkd deploy` will treat them as new and CREATE them.
+This matches the semantics of `cdk import --resource-mapping`. cdkd
+validates that every override key is a real logical ID in the
+template; a typo aborts the run rather than silently importing nothing.
+
+Use selective mode when you want to **adopt a few specific resources**
+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.
+
+### Mode 3: hybrid (`--auto` with overrides)
+
+```bash
+cdkd import MyStack \
+  --resource MyBucket=my-bucket-name \
+  --auto
+```
+
+Listed resources use the explicit physical ID you supplied; **every
+other resource still goes through tag-based auto-import**. Useful when
+you have one resource whose tag-based lookup is unreliable (e.g. you
+deleted and re-created it without the tag) but you want cdkd to find
+the rest by tag automatically.
+
+### Common flags
+
+| Flag        | Purpose                                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| `--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.      |
+
+### After import
+
+Run `cdkd diff` to see how the imported state lines up with the
+template. If the resource's actual properties differ from the template,
+the next `cdkd deploy` will UPDATE them to match. If you imported only
+some resources (selective mode), the remaining template resources
+appear as `to create` in the diff.
+
+### Provider support
+
+Tag-based auto-lookup is implemented for the most-used resource types
+(S3 Bucket, Lambda Function, IAM Role, SNS Topic, SQS Queue, DynamoDB
+Table, Logs LogGroup, EventBridge EventBus, KMS Key/Alias, Secrets
+Manager Secret, SSM Parameter, EC2 VPC/Subnet/SecurityGroup, RDS,
+ECS Cluster/Service/TaskDefinition, CloudFront Distribution, Cognito
+User Pool — the full list is in [CLAUDE.md](CLAUDE.md)). For resource
+types without auto-lookup support (ApiGateway sub-resources, niche
+services, anything in Cloud Control API), use the explicit
+`--resource <id>=<physicalId>` override mode — selective mode handles
+exactly this case. Resource types whose provider does not implement
+import are reported as `unsupported` and skipped.
+
 ## State Management
 
 State is stored in S3. Keys are scoped by `(stackName, region)` so the same

package/dist/cli.js

@@ -7749,6 +7749,27 @@ var CustomResourceProvider = class _CustomResourceProvider {
   sleep(ms) {
     return new Promise((resolve4) => setTimeout(resolve4, ms));
   }
+  /**
+   * Adopt an existing custom resource into cdkd state.
+   *
+   * **Explicit override only.** A custom resource's identity is the
+   * `PhysicalResourceId` returned by its user-supplied Lambda handler at
+   * Create time — there is no AWS-side resource cdkd can introspect, no
+   * tag API, and no `aws:cdk:path` to look up by. cdkd cannot rediscover
+   * a custom resource without invoking the handler, which would mutate
+   * state.
+   *
+   * Users adopting an existing custom resource should pass
+   * `--resource <logicalId>=<physicalResourceId>` — the same value the
+   * handler returned originally.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/provider-registry.ts
@@ -11372,6 +11393,25 @@ var S3BucketPolicyProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing S3 bucket policy into cdkd state.
+   *
+   * **Explicit override only.** An `S3::BucketPolicy` is a policy document
+   * attached to a bucket via `PutBucketPolicy` — it has no standalone
+   * identity and is not independently taggable. There is no `aws:cdk:path`
+   * tag to look up by; only the bucket itself is taggable.
+   *
+   * Users adopting an existing bucket policy should pass
+   * `--resource <logicalId>=<bucketName>` (matching the physical id
+   * format returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/sqs-queue-provider.ts
@@ -11808,6 +11848,25 @@ var SQSQueuePolicyProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing SQS queue policy into cdkd state.
+   *
+   * **Explicit override only.** A `QueuePolicy` is an attachment applied to
+   * a queue via `SetQueueAttributes(Policy=...)` — it has no standalone
+   * identity and is not independently taggable. There is no `aws:cdk:path`
+   * tag to look up by; only the queue itself is taggable.
+   *
+   * Users adopting an existing queue policy should pass
+   * `--resource <logicalId>=<queueUrl>` (matching the physical id format
+   * returned by `create()`, which uses the first queue URL).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/sns-topic-provider.ts
@@ -12300,6 +12359,25 @@ var SNSSubscriptionProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing SNS subscription into cdkd state.
+   *
+   * **Explicit override only.** SNS subscriptions are attached to a parent
+   * topic and identified by their `SubscriptionArn`, but the SubscribeAPI
+   * does not accept tags and the AWS tag APIs do not cover subscriptions
+   * (only Topics are taggable). There is therefore no `aws:cdk:path` tag
+   * we could use for auto-lookup.
+   *
+   * Users adopting an existing subscription should pass
+   * `--resource <logicalId>=<subscriptionArn>`.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/sns-topic-policy-provider.ts
@@ -12439,6 +12517,26 @@ var SNSTopicPolicyProvider = class {
     }
     this.logger.debug(`Successfully deleted SNS topic policy ${logicalId}`);
   }
+  /**
+   * Adopt an existing SNS topic policy into cdkd state.
+   *
+   * **Explicit override only.** A `TopicPolicy` is an attachment to one or
+   * more SNS topics applied via `SetTopicAttributes(AttributeName=Policy)` —
+   * it has no standalone identity and is not independently taggable. There
+   * is no `aws:cdk:path` tag to look up by, and the policy has no name/ARN
+   * of its own.
+   *
+   * Users adopting an existing topic policy should pass
+   * `--resource <logicalId>=<comma-joined-topic-ARNs>` (matching the
+   * physical id format returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
   /**
    * Set the policy on a single SNS topic
    */
@@ -13294,6 +13392,26 @@ var LambdaPermissionProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing Lambda permission into cdkd state.
+   *
+   * **Explicit override only.** A `Lambda::Permission` is a single statement
+   * within a function's resource-based policy added via `AddPermission`. It
+   * has no independent ARN, no taggable identity, and the only way to find
+   * it is to call `GetPolicy` on the parent function and parse the JSON
+   * statements — which the user knows by `StatementId` already.
+   *
+   * Users adopting an existing permission should pass
+   * `--resource <logicalId>=<statementId>` (matching the physical id
+   * format returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: { Id: input.knownPhysicalId } };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/lambda-url-provider.ts
@@ -13427,6 +13545,26 @@ var LambdaUrlProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing Lambda Function URL into cdkd state.
+   *
+   * **Explicit override only.** A `Lambda::Url` is a configuration attached
+   * to a Lambda function — it has no standalone identity (the natural
+   * physical id is the parent function's ARN/name) and `FunctionUrlConfig`
+   * is not independently taggable. There is no `aws:cdk:path` tag to look
+   * up by; only the parent function carries the CDK path tag.
+   *
+   * Users adopting an existing function URL should pass
+   * `--resource <logicalId>=<functionArnOrName>` (matching the physical id
+   * format returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: {} };
+    }
+    return null;
+  }
   /**
    * Build CORS configuration from CDK properties
    */
@@ -13669,6 +13807,27 @@ var LambdaEventSourceMappingProvider = class {
       );
     }
   }
+  /**
+   * Adopt an existing Lambda event source mapping into cdkd state.
+   *
+   * **Explicit override only.** Event source mappings are identified by a
+   * UUID returned at create time. While Lambda event source mappings ARE
+   * taggable since 2020, CDK does NOT propagate the `aws:cdk:path` tag to
+   * them by default (the `Tags` property must be explicitly opted into),
+   * and the natural lookup is by `(FunctionName, EventSourceArn)` — which
+   * the user already knows.
+   *
+   * Users adopting an existing event source mapping should pass
+   * `--resource <logicalId>=<UUID>` (matching the physical id format
+   * returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: { Id: input.knownPhysicalId } };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/lambda-layer-provider.ts
@@ -19792,6 +19951,25 @@ var CloudFrontOAIProvider = class {
       `Unsupported attribute: ${attributeName} for AWS::CloudFront::CloudFrontOriginAccessIdentity`
     );
   }
+  /**
+   * Adopt an existing CloudFront Origin Access Identity into cdkd state.
+   *
+   * **Explicit override only.** OAIs do not support tags — their identity
+   * is the `CallerReference` set at create time, plus the auto-generated
+   * `Id`. There is no `aws:cdk:path` tag API to look up by; CloudFront's
+   * `ListCloudFrontOriginAccessIdentities` returns Id/Comment/CallerReference
+   * but no tags.
+   *
+   * Users adopting an existing OAI should pass
+   * `--resource <logicalId>=<oaiId>` (e.g. `E1ABCDEF123456`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return { physicalId: input.knownPhysicalId, attributes: { Id: input.knownPhysicalId } };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/cloudfront-distribution-provider.ts
@@ -20515,6 +20693,27 @@ var AgentCoreRuntimeProvider = class {
     }
     throw new Error(`Unsupported attribute: ${attributeName} for AWS::BedrockAgentCore::Runtime`);
   }
+  /**
+   * Adopt an existing BedrockAgentCore Runtime into cdkd state.
+   *
+   * **Explicit override only (for now).** The BedrockAgentCore SDK does
+   * expose `ListTagsForResource`, so a future PR could add full tag-based
+   * auto-lookup. For this batch we keep it override-only to ship
+   * consistently with the other batch-5 attachment-style providers; users
+   * adopting an existing runtime should pass
+   * `--resource <logicalId>=<agentRuntimeId>` (e.g. `runtime-12345`,
+   * matching the physical id format returned by `create()`).
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- explicit-override-only intentionally has no AWS calls
+  async import(input) {
+    if (input.knownPhysicalId) {
+      return {
+        physicalId: input.knownPhysicalId,
+        attributes: { AgentRuntimeId: input.knownPhysicalId }
+      };
+    }
+    return null;
+  }
 };
 
 // src/provisioning/providers/stepfunctions-provider.ts
@@ -33859,15 +34058,38 @@ async function importCommand(stackArg, options) {
     if (overrides.size > 0) {
       logger.debug(`User-supplied physical IDs: ${[...overrides.keys()].join(", ")}`);
     }
+    const selectiveMode = overrides.size > 0 && !options.auto;
+    if (selectiveMode) {
+      logger.info(
+        `Selective mode: only importing the ${overrides.size} resource(s) you listed (${[...overrides.keys()].join(", ")}). Pass --auto to also tag-import the rest.`
+      );
+    }
     const template = stackInfo.template;
     const templateParser = new TemplateParser();
     const resources = collectImportableResources(template);
     logger.info(`Found ${resources.length} resource(s) in template`);
+    const templateLogicalIds = new Set(resources.map((r) => r.logicalId));
+    for (const overrideId of overrides.keys()) {
+      if (!templateLogicalIds.has(overrideId)) {
+        throw new Error(
+          `--resource / --resource-mapping references logical ID '${overrideId}' which is not in the synthesized template for stack '${stackInfo.stackName}'. Available IDs: ${[...templateLogicalIds].join(", ")}`
+        );
+      }
+    }
     const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
     await lockManager.acquireLock(stackInfo.stackName, targetRegion, owner, "import");
     try {
       const rows = [];
       for (const { logicalId, resource } of resources) {
+        if (selectiveMode && !overrides.has(logicalId)) {
+          rows.push({
+            logicalId,
+            resourceType: resource.Type,
+            outcome: "skipped-out-of-scope",
+            reason: "not in --resource / --resource-mapping (use --auto to include)"
+          });
+          continue;
+        }
         const outcome = await importOne({
           logicalId,
           resource,
@@ -34057,6 +34279,7 @@ function printSummary(rows) {
     imported: 0,
     "skipped-no-impl": 0,
     "skipped-not-found": 0,
+    "skipped-out-of-scope": 0,
     failed: 0
   };
   logger.info("");
@@ -34069,7 +34292,7 @@ function printSummary(rows) {
   }
   logger.info("");
   logger.info(
-    `Summary: ${counts.imported} imported, ${counts["skipped-not-found"]} not found, ${counts["skipped-no-impl"]} unsupported, ${counts.failed} failed`
+    `Summary: ${counts.imported} imported, ${counts["skipped-not-found"]} not found, ${counts["skipped-no-impl"]} unsupported, ${counts["skipped-out-of-scope"]} out of scope, ${counts.failed} failed`
   );
 }
 function formatOutcome(outcome) {
@@ -34080,6 +34303,8 @@ function formatOutcome(outcome) {
       return "\xB7";
     case "skipped-no-impl":
       return "?";
+    case "skipped-out-of-scope":
+      return "-";
     case "failed":
       return "\u2717";
   }
@@ -34095,18 +34320,22 @@ async function confirmPrompt2(prompt) {
 }
 function createImportCommand() {
   const cmd = new Command12("import").description(
-    "Adopt already-deployed AWS resources into cdkd state. Reads the CDK app to find logical IDs, resource types, and dependencies; uses the aws:cdk:path tag (or explicit --resource overrides) to find each resource in AWS."
+    "Adopt already-deployed AWS resources into cdkd state. Reads the CDK app to find logical IDs, resource types, and dependencies. With no flags, imports every resource via the aws:cdk:path tag. With --resource / --resource-mapping, only the listed resources are imported (CDK CLI parity); pass --auto to also tag-import the rest."
   ).argument(
     "[stack]",
     "Stack to import. Optional when the synthesized app contains exactly one stack."
   ).option(
     "--resource <id=physical>",
-    "Explicit physical-id override for one logical ID. Repeatable. Bypasses tag-based auto-lookup for that resource only.",
+    "Explicit physical-id override for one logical ID. Repeatable. When at least one --resource is given, only listed resources are imported (CDK CLI parity). Pass --auto to also tag-import everything else.",
     collectMultiple,
     []
   ).option(
     "--resource-mapping <file>",
-    "Path to a JSON file of {logicalId: physicalId} overrides (CDK CLI `cdk import --resource-mapping` compatible)."
+    "Path to a JSON file of {logicalId: physicalId} overrides (CDK CLI `cdk import --resource-mapping` compatible). Implies selective mode unless --auto is set."
+  ).option(
+    "--auto",
+    "Hybrid mode: when explicit overrides are supplied, ALSO tag-import every other resource in the template. Without this flag, --resource / --resource-mapping behave as a whitelist (CDK CLI parity).",
+    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.",
@@ -34148,7 +34377,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.21.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.23.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());