@go-to-k/cdkd 0.28.0 → 0.28.2

package/README.md

@@ -457,8 +457,10 @@ cdkd state show MyStack --json        # raw {state, lock} JSON
 
 # Orphan one or more RESOURCES from cdkd's state (does NOT delete AWS resources).
 # Per-resource, mirrors aws-cdk-cli's `cdk orphan --unstable=orphan`.
-# Synth-driven — needs --app / cdk.json. Construct paths look like the CDK
-# `aws:cdk:path` tag (`<StackName>/<Path/To/Resource>`).
+# Synth-driven — needs --app / cdk.json. Construct paths use CDK's L2-style form
+# (`<StackName>/<Path/To/Construct>`); the synthesized `/Resource` suffix is
+# matched implicitly. Passing an L2 wrapper that contains multiple CFn resources
+# orphans every child under it (matches upstream's prefix-match semantics).
 cdkd orphan MyStack/MyTable                    # confirmation prompt (y/N)
 cdkd orphan MyStack/MyTable --yes
 cdkd orphan MyStack/MyTable MyStack/MyBucket   # multiple resources, same stack
@@ -678,6 +680,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
@@ -698,7 +714,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
 
@@ -746,7 +773,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

@@ -33391,12 +33391,25 @@ function readCdkPath(resource) {
 function buildCdkPathIndex(template) {
   const index = /* @__PURE__ */ new Map();
   for (const [logicalId, resource] of Object.entries(template.Resources)) {
+    if (resource.Type === "AWS::CDK::Metadata")
+      continue;
     const path = readCdkPath(resource);
     if (path)
       index.set(path, logicalId);
   }
   return index;
 }
+function resolveCdkPathToLogicalIds(input, index) {
+  const seen = /* @__PURE__ */ new Map();
+  const prefix = `${input}/`;
+  for (const [path, logicalId] of index) {
+    if (path === input || path.startsWith(prefix)) {
+      if (!seen.has(logicalId))
+        seen.set(logicalId, path);
+    }
+  }
+  return [...seen.entries()].map(([logicalId, cdkPath]) => ({ logicalId, cdkPath }));
+}
 
 // src/analyzer/orphan-rewriter.ts
 var AttributeFetcher = class {
@@ -33952,19 +33965,20 @@ function resolveConstructPaths(paths, stacks) {
         `All construct paths must reference the same stack. Got '${stack.stackName}' and '${candidate.stackName}'. Run 'cdkd orphan' once per stack.`
       );
     }
-    const cdkPath = p;
     const index = buildCdkPathIndex(candidate.template);
-    const logicalId = index.get(cdkPath);
-    if (!logicalId) {
+    const matches = resolveCdkPathToLogicalIds(p, index);
+    if (matches.length === 0) {
       const available = [...index.keys()].sort().join("\n  ");
       throw new Error(
-        `Construct path '${cdkPath}' not found in template for stack '${candidate.stackName}'.
+        `Construct path '${p}' not found in template for stack '${candidate.stackName}'.
 Available paths:
   ${available}`
       );
     }
-    if (!logicalIds.includes(logicalId)) {
-      logicalIds.push(logicalId);
+    for (const { logicalId } of matches) {
+      if (!logicalIds.includes(logicalId)) {
+        logicalIds.push(logicalId);
+      }
     }
   }
   if (!stack) {
@@ -35259,12 +35273,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,
@@ -35279,6 +35287,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);
@@ -35329,8 +35365,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.");
@@ -35342,9 +35382,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.`
@@ -35500,8 +35549,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;
@@ -35522,7 +35571,7 @@ function buildStackState(stackName, region, rows, templateParser, template) {
     stackName,
     region,
     resources,
-    outputs: {},
+    outputs: existingState?.outputs ?? {},
     lastModified: Date.now()
   };
 }
@@ -35597,7 +35646,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(
@@ -35636,7 +35685,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.28.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.28.2");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());