@go-to-k/cdkd 0.23.1 → 0.24.0

package/README.md

@@ -582,15 +582,21 @@ cdkd import MyStack \
 # 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" }
+
+# CDK CLI compat: inline JSON (handy for non-TTY CI scripts).
+cdkd import MyStack --resource-mapping-inline '{"MyBucket":"my-bucket-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.
+When at least one `--resource` flag (or a `--resource-mapping` /
+`--resource-mapping-inline` payload) 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` /
+`--resource-mapping-inline`. cdkd validates that every override key is
+a real logical ID in the template; a typo aborts the run rather than
+silently importing nothing. `--resource-mapping` and
+`--resource-mapping-inline` are mutually exclusive — pick one source.
 
 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
@@ -641,6 +647,50 @@ services, anything in Cloud Control API), use the explicit
 exactly this case. Resource types whose provider does not implement
 import are reported as `unsupported` and skipped.
 
+### `cdkd import` vs upstream `cdk import`
+
+cdkd's `import` command mirrors the surface of upstream
+[`cdk import`](https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cmd-import.html)
+where it can, but the underlying mechanism is fundamentally different
+and a handful of upstream-only flags are not implemented. Use this
+table to predict behavior when migrating from `cdk import`.
+
+| Topic | `cdk import` (upstream) | `cdkd import` |
+| --- | --- | --- |
+| Mechanism | CloudFormation `CreateChangeSet` with `ResourcesToImport` — atomic, all-or-nothing. | Per-resource SDK calls (e.g. `s3:HeadBucket`, `lambda:GetFunction`, IAM `ListRoleTags`). **Not atomic.** |
+| Failure mode | Failed import rolls the changeset back; the stack is left unchanged. | Per-resource: `imported` / `skipped-not-found` / `skipped-no-impl` / `skipped-out-of-scope` / `failed` rows are summarized. State is written for whatever succeeded — but only after a confirmation prompt (or `--yes`), so a partial run is opt-in. To roll a partial import back, use `cdkd state orphan <stack>` (drops the state record only). |
+| Selective mode (`--resource-mapping <file>`) | Supported. Listed resources are imported; unlisted resources cause the changeset to fail. | Supported. Listed resources are imported; unlisted resources are reported as `out of scope` and left out of state (next `cdkd deploy` will CREATE them). |
+| Selective mode (`--resource <id>=<physical>` repeatable) | Not supported (upstream uses interactive prompts or a mapping file). | Supported as cdkd's CLI-friendly equivalent. |
+| `--resource-mapping-inline '<json>'` | Supported (use in non-TTY environments). | **Not supported.** Use `--resource <id>=<physical>` (repeatable) or `--resource-mapping <file>` instead. |
+| `--record-resource-mapping <file>` | Supported (writes the mapping the user typed at the prompt to a file for re-use). | **Not supported.** cdkd has no interactive prompt to record. |
+| Interactive prompt for missing IDs | Default in TTY — prompts for every resource not covered by a mapping file. | **Not supported.** cdkd is non-interactive: missing logical IDs are looked up by `aws:cdk:path` tag in `auto` / `hybrid` modes, or skipped as `out of scope` in selective mode. The only prompt is the final "write state?" confirmation, which `--yes` skips. |
+| Typo'd logical ID | Aborts with a clear error before any AWS calls. | Aborts with a clear error before any AWS calls — checked against the synthesized template. |
+| Whole-stack tag-based import | **Not supported.** | **cdkd-specific.** With no flags, cdkd looks every resource up by its `aws:cdk:path` tag — the typical case for adopting a stack previously deployed by `cdk deploy`. |
+| Hybrid mode (overrides + tag fallback) | **Not supported.** | **cdkd-specific.** `--auto` together with `--resource` lets listed resources use the explicit physical id while everything else still goes through tag lookup. |
+| Nested stacks (`AWS::CloudFormation::Stack`) | Explicitly unsupported. | Also unsupported in practice — cdkd does not deploy nested CloudFormation stacks at all (no `AWS::CloudFormation::Stack` provider). The `Stack` resource itself would be reported as `unsupported`. CDK Stages (separate top-level stacks) are fine: pass the stack's display path or physical name as the positional argument. |
+| 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.** |
+| `--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`
+
+- If you script around `--resource-mapping <file>`: behavior matches.
+  The file format (`{"LogicalId": "physical-id"}`) is the same.
+- If you script around `--resource-mapping-inline`: rewrite as
+  repeated `--resource <id>=<physical>` flags, or write a temp file.
+- If your workflow relies on the interactive prompt: rewrite as
+  `--resource-mapping <file>`. cdkd will not prompt.
+- If you rely on atomic rollback: cdkd cannot offer that — its
+  per-resource model writes state only after the full pass completes
+  (and after confirmation), so a partial run is bounded, but if a
+  later resource fails after several earlier ones already returned
+  successfully and you confirm the write, those earlier ones are
+  in cdkd state. Use `cdkd state orphan <stack>` to back out.
+- If you import nested stacks: neither tool supports this. Convert
+  to top-level CDK stacks first.
+
 ## State Management
 
 State is stored in S3. Keys are scoped by `(stackName, region)` so the same

package/dist/cli.js

@@ -7344,13 +7344,11 @@ var CustomResourceProvider = class _CustomResourceProvider {
       );
     }
     try {
-      const requestId = `cdkd-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-      const responseKey = this.getResponseKey(requestId);
-      const responseURL = await this.generateResponseURL(responseKey);
+      const invocation = await this.prepareInvocation();
       const request = {
         RequestType: "Create",
-        RequestId: requestId,
-        ResponseURL: responseURL,
+        RequestId: invocation.requestId,
+        ResponseURL: invocation.responseURL,
         ResourceType: resourceType,
         LogicalResourceId: logicalId,
         StackId: `arn:aws:cloudformation:us-east-1:000000000000:stack/cdkd-${logicalId}/cdkd`,
@@ -7360,7 +7358,7 @@ var CustomResourceProvider = class _CustomResourceProvider {
       const cfnResponse = await this.sendRequest(
         serviceToken,
         request,
-        responseKey,
+        invocation.responseKey,
         logicalId,
         "Create"
       );
@@ -7399,13 +7397,11 @@ var CustomResourceProvider = class _CustomResourceProvider {
       );
     }
     try {
-      const requestId = `cdkd-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-      const responseKey = this.getResponseKey(requestId);
-      const responseURL = await this.generateResponseURL(responseKey);
+      const invocation = await this.prepareInvocation();
       const request = {
         RequestType: "Update",
-        RequestId: requestId,
-        ResponseURL: responseURL,
+        RequestId: invocation.requestId,
+        ResponseURL: invocation.responseURL,
         ResourceType: resourceType,
         LogicalResourceId: logicalId,
         PhysicalResourceId: physicalId,
@@ -7417,7 +7413,7 @@ var CustomResourceProvider = class _CustomResourceProvider {
       const cfnResponse = await this.sendRequest(
         serviceToken,
         request,
-        responseKey,
+        invocation.responseKey,
         logicalId,
         "Update"
       );
@@ -7461,13 +7457,11 @@ var CustomResourceProvider = class _CustomResourceProvider {
       return;
     }
     try {
-      const requestId = `cdkd-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-      const responseKey = this.getResponseKey(requestId);
-      const responseURL = await this.generateResponseURL(responseKey);
+      const invocation = await this.prepareInvocation();
       const request = {
         RequestType: "Delete",
-        RequestId: requestId,
-        ResponseURL: responseURL,
+        RequestId: invocation.requestId,
+        ResponseURL: invocation.responseURL,
         ResourceType: resourceType,
         LogicalResourceId: logicalId,
         PhysicalResourceId: physicalId,
@@ -7478,7 +7472,7 @@ var CustomResourceProvider = class _CustomResourceProvider {
       const cfnResponse = await this.sendRequest(
         serviceToken,
         request,
-        responseKey,
+        invocation.responseKey,
         logicalId,
         "Delete"
       );
@@ -7597,6 +7591,28 @@ var CustomResourceProvider = class _CustomResourceProvider {
     const timeoutMs = isAsyncPattern ? this.asyncResponseTimeoutMs : this.SYNC_RESPONSE_TIMEOUT_MS;
     return await this.pollS3Response(responseKey, logicalId, operation, timeoutMs, isAsyncPattern);
   }
+  /**
+   * Prepare a single Custom Resource invocation: generate the request id,
+   * derive the S3 response key from it, sign the pre-signed PUT URL for that
+   * key, and return all three together.
+   *
+   * **The request id, response key, and response URL must all be derived from
+   * the SAME generation step.** Previously these were generated by separate
+   * calls inside `create` / `update` / `delete`, which made it possible for a
+   * future refactor (e.g. wrapping URL signing in a retry that re-rolls the
+   * id) to silently break the invariant — the Lambda would write to one S3
+   * key while cdkd polled a different one, hanging the deploy until the
+   * polling timeout (up to 1 hour). See issue #90.
+   *
+   * Centralising this in one helper makes that invariant impossible to
+   * violate at the call sites.
+   */
+  async prepareInvocation() {
+    const requestId = `cdkd-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    const responseKey = this.getResponseKey(requestId);
+    const responseURL = await this.generateResponseURL(responseKey);
+    return { requestId, responseKey, responseURL };
+  }
   /**
    * Generate a pre-signed S3 PUT URL for Lambda to send its response
    */
@@ -34054,7 +34070,11 @@ async function importCommand(stackArg, options) {
         `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);
+    const overrides = parseResourceOverrides(
+      options.resource,
+      options.resourceMapping,
+      options.resourceMappingInline
+    );
     if (overrides.size > 0) {
       logger.debug(`User-supplied physical IDs: ${[...overrides.keys()].join(", ")}`);
     }
@@ -34197,28 +34217,30 @@ async function importOne(task) {
     };
   }
 }
-function parseResourceOverrides(flags, mappingFile) {
+function parseResourceOverrides(flags, mappingFile, mappingInline) {
   const map = /* @__PURE__ */ new Map();
+  if (mappingFile && mappingInline) {
+    throw new Error(
+      "--resource-mapping and --resource-mapping-inline are mutually exclusive; pass only one."
+    );
+  }
   if (mappingFile) {
-    let parsed;
+    let raw;
     try {
-      parsed = JSON.parse(readFileSync5(mappingFile, "utf-8"));
+      raw = readFileSync5(mappingFile, "utf-8");
     } catch (err) {
       throw new Error(
         `Failed to read --resource-mapping file '${mappingFile}': ` + (err instanceof Error ? err.message : String(err))
       );
     }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error(
-        `--resource-mapping file '${mappingFile}' must be a JSON object {logicalId: physicalId}`
-      );
+    const parsed = parseMappingJson(raw, `--resource-mapping file '${mappingFile}'`);
+    for (const [key, value] of Object.entries(parsed)) {
+      map.set(key, value);
     }
+  }
+  if (mappingInline) {
+    const parsed = parseMappingJson(mappingInline, "--resource-mapping-inline");
     for (const [key, value] of Object.entries(parsed)) {
-      if (typeof value !== "string") {
-        throw new Error(
-          `--resource-mapping: value for '${key}' must be a string, got ${typeof value}`
-        );
-      }
       map.set(key, value);
     }
   }
@@ -34231,6 +34253,27 @@ function parseResourceOverrides(flags, mappingFile) {
   }
   return map;
 }
+function parseMappingJson(raw, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse ${source} as JSON: ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${source} must be a JSON object {logicalId: physicalId}`);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== "string") {
+      throw new Error(`${source}: value for '${key}' must be a string, got ${typeof value}`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
 function readCdkPath(resource) {
   const meta = resource.Metadata;
   if (!meta)
@@ -34331,7 +34374,10 @@ function createImportCommand() {
     []
   ).option(
     "--resource-mapping <file>",
-    "Path to a JSON file of {logicalId: physicalId} overrides (CDK CLI `cdk import --resource-mapping` compatible). Implies selective mode unless --auto is set."
+    "Path to a JSON file of {logicalId: physicalId} overrides (CDK CLI `cdk import --resource-mapping` compatible). Implies selective mode unless --auto is set. Mutually exclusive with --resource-mapping-inline."
+  ).option(
+    "--resource-mapping-inline <json>",
+    "Inline JSON object of {logicalId: physicalId} overrides (CDK CLI `cdk import --resource-mapping-inline` compatible). Same shape as --resource-mapping but supplied as a string \u2014 useful for non-TTY CI scripts that do not want a separate file. Implies selective mode unless --auto is set. Mutually exclusive with --resource-mapping."
   ).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).",
@@ -34377,7 +34423,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.23.1");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.24.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());