@go-to-k/cdkd 0.3.5 → 0.4.0

package/README.md

@@ -380,9 +380,15 @@ cdkd deploy Stack1 Stack2
 # Deploy all stacks
 cdkd deploy --all
 
-# Deploy with wildcard
+# Deploy with wildcard (matched against the physical CloudFormation stack name)
 cdkd deploy 'My*'
 
+# Deploy stacks under a CDK Stage using the hierarchical path (CDK CLI parity)
+# Patterns containing '/' are routed to the CDK display path; both forms work:
+cdkd deploy 'MyStage/*'        # all stacks under MyStage
+cdkd deploy MyStage/Api        # specific stack by display path
+cdkd deploy MyStage-Api        # same stack by physical CloudFormation name
+
 # Deploy with context values
 cdkd deploy -c env=staging -c featureFlag=true
 

package/dist/cli.js

@@ -527,6 +527,141 @@ var destroyOptions = [
   )
 ];
 
+// src/utils/live-renderer.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var FRAME_INTERVAL_MS = 80;
+var ESC = "\x1B[";
+var LiveRenderer = class {
+  constructor(stream = process.stdout) {
+    this.stream = stream;
+  }
+  tasks = /* @__PURE__ */ new Map();
+  active = false;
+  spinnerIndex = 0;
+  interval = null;
+  linesDrawn = 0;
+  cursorHidden = false;
+  exitListener = null;
+  isActive() {
+    return this.active;
+  }
+  /**
+   * Enable the live renderer. No-op if stdout is not a TTY or if
+   * `CDKD_NO_LIVE=1`. Returns true if successfully enabled.
+   */
+  start() {
+    if (this.active)
+      return true;
+    if (!this.stream.isTTY)
+      return false;
+    if (process.env["CDKD_NO_LIVE"] === "1")
+      return false;
+    this.active = true;
+    this.hideCursor();
+    if (!this.exitListener) {
+      this.exitListener = () => this.showCursor();
+      process.on("exit", this.exitListener);
+    }
+    this.interval = setInterval(() => this.draw(), FRAME_INTERVAL_MS);
+    if (typeof this.interval.unref === "function")
+      this.interval.unref();
+    return true;
+  }
+  stop() {
+    if (!this.active)
+      return;
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    this.clear();
+    this.showCursor();
+    if (this.exitListener) {
+      process.removeListener("exit", this.exitListener);
+      this.exitListener = null;
+    }
+    this.tasks.clear();
+    this.active = false;
+  }
+  addTask(id, label) {
+    this.tasks.set(id, { label, startedAt: Date.now() });
+    if (this.active)
+      this.draw();
+  }
+  removeTask(id) {
+    if (!this.tasks.delete(id))
+      return;
+    if (this.active)
+      this.draw();
+  }
+  /**
+   * Print content above the live area. Clears the live area, runs the writer,
+   * then redraws the live area. When the renderer is inactive, the writer
+   * runs directly so callers can use this unconditionally.
+   */
+  printAbove(write) {
+    if (!this.active) {
+      write();
+      return;
+    }
+    this.clear();
+    write();
+    this.draw();
+  }
+  clear() {
+    if (this.linesDrawn === 0)
+      return;
+    this.stream.write("\r");
+    for (let i = 0; i < this.linesDrawn; i++) {
+      this.stream.write(`${ESC}1A${ESC}2K`);
+    }
+    this.linesDrawn = 0;
+  }
+  draw() {
+    if (!this.active)
+      return;
+    this.clear();
+    if (this.tasks.size === 0)
+      return;
+    const frame = SPINNER_FRAMES[this.spinnerIndex % SPINNER_FRAMES.length];
+    this.spinnerIndex++;
+    const cols = this.stream.columns ?? 80;
+    const lines = [];
+    for (const task of this.tasks.values()) {
+      const elapsed = ((Date.now() - task.startedAt) / 1e3).toFixed(1);
+      const raw = `  ${frame} ${task.label} (${elapsed}s)`;
+      lines.push(this.truncate(raw, cols));
+    }
+    this.stream.write(lines.join("\n") + "\n");
+    this.linesDrawn = lines.length;
+  }
+  truncate(s, maxLen) {
+    if (s.length <= maxLen)
+      return s;
+    if (maxLen <= 1)
+      return "\u2026";
+    return s.substring(0, maxLen - 1) + "\u2026";
+  }
+  hideCursor() {
+    if (this.cursorHidden)
+      return;
+    this.stream.write(`${ESC}?25l`);
+    this.cursorHidden = true;
+  }
+  showCursor() {
+    if (!this.cursorHidden)
+      return;
+    this.stream.write(`${ESC}?25h`);
+    this.cursorHidden = false;
+  }
+};
+var globalRenderer = null;
+function getLiveRenderer() {
+  if (!globalRenderer)
+    globalRenderer = new LiveRenderer();
+  return globalRenderer;
+}
+
 // src/utils/logger.ts
 var colors = {
   reset: "\x1B[0m",
@@ -583,22 +718,26 @@ var ConsoleLogger = class {
   }
   debug(message, ...args) {
     if (this.shouldLog("debug")) {
-      console.debug(this.formatMessage("debug", message, ...args));
+      const formatted = this.formatMessage("debug", message, ...args);
+      getLiveRenderer().printAbove(() => console.debug(formatted));
     }
   }
   info(message, ...args) {
     if (this.shouldLog("info")) {
-      console.info(this.formatMessage("info", message, ...args));
+      const formatted = this.formatMessage("info", message, ...args);
+      getLiveRenderer().printAbove(() => console.info(formatted));
     }
   }
   warn(message, ...args) {
     if (this.shouldLog("warn")) {
-      console.warn(this.formatMessage("warn", message, ...args));
+      const formatted = this.formatMessage("warn", message, ...args);
+      getLiveRenderer().printAbove(() => console.warn(formatted));
     }
   }
   error(message, ...args) {
     if (this.shouldLog("error")) {
-      console.error(this.formatMessage("error", message, ...args));
+      const formatted = this.formatMessage("error", message, ...args);
+      getLiveRenderer().printAbove(() => console.error(formatted));
     }
   }
   /**
@@ -1243,6 +1382,7 @@ var AssemblyReader = class {
     }
     return {
       stackName,
+      displayName: artifact.displayName ?? stackName,
       artifactId,
       template,
       assetManifestPath,
@@ -11432,10 +11572,14 @@ var LambdaFunctionProvider = class {
   }
   /**
    * List Lambda-managed ENIs for the given function, paginating through
-   * DescribeNetworkInterfaces and filtering on Description substring.
+   * DescribeNetworkInterfaces and filtering on Description.
    *
-   * Server-side filter (`description`) does not support wildcards on this
-   * API, so we narrow with `requester-id` + match Description client-side.
+   * We filter directly on `description=AWS Lambda VPC ENI-*` (the EC2 API
+   * supports `*` wildcards on this filter — same approach as delstack). An
+   * earlier attempt narrowed with `requester-id=*:awslambda_*`, but real
+   * Lambda hyperplane ENIs carry a RequesterId of the form
+   * `AROAXXX...:<account-id>` (no literal "awslambda" substring), so that
+   * filter matched nothing and the cleanup loop quietly listed zero ENIs.
    */
   async listLambdaEnis(functionName) {
     const enis = [];
@@ -11444,10 +11588,7 @@ var LambdaFunctionProvider = class {
     do {
       const resp = await this.ec2Client.send(
         new DescribeNetworkInterfacesCommand({
-          Filters: [
-            // Lambda hyperplane ENIs are owned by the Lambda service principal.
-            { Name: "requester-id", Values: ["*:awslambda_*"] }
-          ],
+          Filters: [{ Name: "description", Values: [`${descriptionPrefix}*`] }],
           NextToken: nextToken
         })
       );
@@ -14407,7 +14548,10 @@ var EC2Provider = class {
         new DescribeNetworkInterfacesCommand2({
           Filters: [
             { Name: "subnet-id", Values: [subnetId] },
-            { Name: "requester-id", Values: ["*:awslambda_*"] }
+            // `description` filter is the only reliable way to find Lambda
+            // hyperplane ENIs — `requester-id` does not actually contain the
+            // string "awslambda" (it is an AROA principal id).
+            { Name: "description", Values: ["AWS Lambda VPC ENI-*"] }
           ]
         })
       );
@@ -14965,7 +15109,9 @@ var EC2Provider = class {
         new DescribeNetworkInterfacesCommand2({
           Filters: [
             { Name: "group-id", Values: [groupId] },
-            { Name: "requester-id", Values: ["*:awslambda_*"] }
+            // See cleanupSubnetLambdaEnis: requester-id does not contain
+            // "awslambda" — filter on description instead.
+            { Name: "description", Values: ["AWS Lambda VPC ENI-*"] }
           ]
         })
       );
@@ -25868,11 +26014,15 @@ var DeployEngine = class {
     this.logger.debug(`Starting deployment for stack: ${stackName}`);
     setCurrentStackName(stackName);
     await this.lockManager.acquireLockWithRetry(stackName, void 0, "deploy");
+    const renderer = getLiveRenderer();
+    renderer.start();
     this.interrupted = false;
     const sigintHandler = () => {
-      process.stderr.write(
-        "\nInterrupted \u2014 saving partial state after current operations complete...\n"
-      );
+      renderer.printAbove(() => {
+        process.stderr.write(
+          "\nInterrupted \u2014 saving partial state after current operations complete...\n"
+        );
+      });
       this.interrupted = true;
     };
     process.on("SIGINT", sigintHandler);
@@ -25987,6 +26137,7 @@ var DeployEngine = class {
         durationMs
       };
     } finally {
+      renderer.stop();
       process.removeListener("SIGINT", sigintHandler);
       try {
         await this.lockManager.releaseLock(stackName);
@@ -26415,6 +26566,10 @@ var DeployEngine = class {
   async provisionResource(logicalId, change, stateResources, stackName, template, parameterValues, conditions, counts, progress) {
     const resourceType = change.resourceType;
     const provider = this.providerRegistry.getProvider(resourceType);
+    const renderer = getLiveRenderer();
+    const needsReplacement = change.changeType === "UPDATE" && (change.propertyChanges?.some((pc) => pc.requiresReplacement) ?? false);
+    const verb = change.changeType === "CREATE" ? "Creating" : change.changeType === "DELETE" ? "Deleting" : needsReplacement ? "Replacing" : "Updating";
+    renderer.addTask(logicalId, `${verb} ${logicalId} (${resourceType})`);
     try {
       switch (change.changeType) {
         case "CREATE": {
@@ -26446,6 +26601,7 @@ var DeployEngine = class {
           if (progress)
             progress.current++;
           const createPrefix = progress ? `[${progress.current}/${progress.total}] ` : "  ";
+          renderer.removeTask(logicalId);
           this.logger.info(`${createPrefix}\u2705 ${logicalId} (${resourceType}) created`);
           break;
         }
@@ -26473,9 +26629,9 @@ var DeployEngine = class {
               counts.skipped++;
             break;
           }
-          const needsReplacement = change.propertyChanges?.some((pc) => pc.requiresReplacement);
+          const needsReplacement2 = change.propertyChanges?.some((pc) => pc.requiresReplacement);
           const dependencies = this.extractAllDependencies(template, logicalId);
-          if (needsReplacement) {
+          if (needsReplacement2) {
             const replacedProps = change.propertyChanges?.filter((pc) => pc.requiresReplacement).map((pc) => pc.path).join(", ");
             this.logger.info(
               `Replacing ${logicalId} (${resourceType}) - immutable properties changed: ${replacedProps}`
@@ -26519,6 +26675,7 @@ var DeployEngine = class {
             if (progress)
               progress.current++;
             const replacePrefix = progress ? `[${progress.current}/${progress.total}] ` : "  ";
+            renderer.removeTask(logicalId);
             this.logger.info(`${replacePrefix}\u2705 ${logicalId} (${resourceType}) replaced`);
           } else {
             this.logger.debug(`Updating ${logicalId} (${resourceType})`);
@@ -26594,6 +26751,7 @@ var DeployEngine = class {
             if (progress)
               progress.current++;
             const updatePrefix = progress ? `[${progress.current}/${progress.total}] ` : "  ";
+            renderer.removeTask(logicalId);
             this.logger.info(`${updatePrefix}\u2705 ${logicalId} (${resourceType}) updated`);
           }
           break;
@@ -26639,11 +26797,13 @@ var DeployEngine = class {
           if (progress)
             progress.current++;
           const deletePrefix = progress ? `[${progress.current}/${progress.total}] ` : "  ";
+          renderer.removeTask(logicalId);
           this.logger.info(`${deletePrefix}\u2705 ${logicalId} (${resourceType}) deleted`);
           break;
         }
       }
     } catch (error) {
+      renderer.removeTask(logicalId);
       const message = error instanceof Error ? error.message : String(error);
       this.logger.error(`Failed to ${change.changeType.toLowerCase()} ${logicalId}: ${message}`);
       throw new ProvisioningError(
@@ -26653,6 +26813,8 @@ var DeployEngine = class {
         stateResources[logicalId]?.physicalId,
         error instanceof Error ? error : void 0
       );
+    } finally {
+      renderer.removeTask(logicalId);
     }
   }
   /**
@@ -26916,10 +27078,43 @@ var DeployEngine = class {
 
 // src/cli/commands/deploy.ts
 init_aws_clients();
+
+// src/cli/stack-matcher.ts
+function matchStacks(stacks, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const stack of stacks) {
+    const matched = patterns.some((pattern) => stackMatchesPattern(stack, pattern));
+    if (matched && !seen.has(stack.stackName)) {
+      seen.add(stack.stackName);
+      result.push(stack);
+    }
+  }
+  return result;
+}
+function describeStack(stack) {
+  if (stack.displayName && stack.displayName !== stack.stackName) {
+    return `${stack.stackName} (${stack.displayName})`;
+  }
+  return stack.stackName;
+}
+function stackMatchesPattern(stack, pattern) {
+  const target = pattern.includes("/") ? stack.displayName ?? stack.stackName : stack.stackName;
+  if (pattern.includes("*")) {
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    return regex.test(target);
+  }
+  return target === pattern;
+}
+
+// src/cli/commands/deploy.ts
 async function deployCommand(stacks, options) {
   const logger = getLogger();
   if (options.verbose) {
     logger.setLevel("debug");
+    process.env["CDKD_NO_LIVE"] = "1";
   }
   if (!options.wait) {
     process.env["CDKD_NO_WAIT"] = "true";
@@ -26977,21 +27172,17 @@ async function deployCommand(stacks, options) {
     if (options.all) {
       targetStacks = allStacks;
     } else if (stackPatterns.length > 0) {
-      targetStacks = allStacks.filter(
-        (s) => stackPatterns.some(
-          (pattern) => pattern.includes("*") ? new RegExp("^" + pattern.replace(/\*/g, ".*") + "$").test(s.stackName) : s.stackName === pattern
-        )
-      );
+      targetStacks = matchStacks(allStacks, stackPatterns);
     } else if (allStacks.length === 1) {
       targetStacks = allStacks;
     } else {
       throw new Error(
-        `Multiple stacks found: ${allStacks.map((s) => s.stackName).join(", ")}. Specify stack name(s) or use --all`
+        `Multiple stacks found: ${allStacks.map(describeStack).join(", ")}. Specify stack name(s) or use --all`
       );
     }
     if (targetStacks.length === 0) {
       throw new Error(
-        stackPatterns.length > 0 ? `No stacks matching ${stackPatterns.join(", ")} found in assembly. Available: ${allStacks.map((s) => s.stackName).join(", ")}` : "No stacks found in assembly"
+        stackPatterns.length > 0 ? `No stacks matching ${stackPatterns.join(", ")} found in assembly. Available: ${allStacks.map(describeStack).join(", ")}` : "No stacks found in assembly"
       );
     }
     if (!options.exclusively) {
@@ -27152,7 +27343,10 @@ Deploying stack: ${stackInfo.stackName}${stackRegion !== baseRegion ? ` (region:
   }
 }
 function createDeployCommand() {
-  const cmd = new Command3("deploy").description("Deploy CDK app using SDK/Cloud Control API").argument("[stacks...]", "Stack name(s) to deploy (supports wildcards)").option("--all", "Deploy all stacks", false).action(withErrorHandling(deployCommand));
+  const cmd = new Command3("deploy").description("Deploy CDK app using SDK/Cloud Control API").argument(
+    "[stacks...]",
+    "Stack name(s) to deploy. Accepts physical CloudFormation names (e.g. 'MyStage-Api') or CDK display paths (e.g. 'MyStage/Api'). Supports wildcards (e.g. 'MyStage/*')."
+  ).option("--all", "Deploy all stacks", false).action(withErrorHandling(deployCommand));
   [
     ...commonOptions,
     ...appOptions,
@@ -27263,21 +27457,17 @@ async function diffCommand(stacks, options) {
     if (options.all) {
       targetStacks = allStacks;
     } else if (stackPatterns.length > 0) {
-      targetStacks = allStacks.filter(
-        (s) => stackPatterns.some(
-          (pattern) => pattern.includes("*") ? new RegExp("^" + pattern.replace(/\*/g, ".*") + "$").test(s.stackName) : s.stackName === pattern
-        )
-      );
+      targetStacks = matchStacks(allStacks, stackPatterns);
     } else if (allStacks.length === 1) {
       targetStacks = allStacks;
     } else {
       throw new Error(
-        `Multiple stacks found: ${allStacks.map((s) => s.stackName).join(", ")}. Specify stack name(s) or use --all`
+        `Multiple stacks found: ${allStacks.map(describeStack).join(", ")}. Specify stack name(s) or use --all`
       );
     }
     if (targetStacks.length === 0) {
       throw new Error(
-        stackPatterns.length > 0 ? `No stacks matching ${stackPatterns.join(", ")} found in assembly` : "No stacks found in assembly"
+        stackPatterns.length > 0 ? `No stacks matching ${stackPatterns.join(", ")} found in assembly. Available: ${allStacks.map(describeStack).join(", ")}` : "No stacks found in assembly"
       );
     }
     const stateConfig = {
@@ -27367,7 +27557,10 @@ ${createCount} to create, ${updateCount} to update, ${deleteCount} to delete`);
   }
 }
 function createDiffCommand() {
-  const cmd = new Command4("diff").description("Show difference between current state and desired state").argument("[stacks...]", "Stack name(s) to diff (supports wildcards)").option("--all", "Diff all stacks", false).action(withErrorHandling(diffCommand));
+  const cmd = new Command4("diff").description("Show difference between current state and desired state").argument(
+    "[stacks...]",
+    "Stack name(s) to diff. Accepts physical CloudFormation names (e.g. 'MyStage-Api') or CDK display paths (e.g. 'MyStage/Api'). Supports wildcards (e.g. 'MyStage/*')."
+  ).option("--all", "Diff all stacks", false).action(withErrorHandling(diffCommand));
   [...commonOptions, ...appOptions, ...stateOptions, ...stackOptions, ...contextOptions].forEach(
     (opt) => cmd.addOption(opt)
   );
@@ -27382,6 +27575,7 @@ async function destroyCommand(stackArgs, options) {
   const logger = getLogger();
   if (options.verbose) {
     logger.setLevel("debug");
+    process.env["CDKD_NO_LIVE"] = "1";
   }
   const region = options.region || process.env["AWS_REGION"] || "us-east-1";
   const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
@@ -27409,7 +27603,7 @@ async function destroyCommand(stackArgs, options) {
     registerAllProviders(providerRegistry);
     providerRegistry.setCustomResourceResponseBucket(stateBucket);
     const appCmd = options.app || resolveApp();
-    let appStackNames = [];
+    let appStacks = [];
     if (appCmd) {
       try {
         const synthesizer = new Synthesizer();
@@ -27419,17 +27613,21 @@ async function destroyCommand(stackArgs, options) {
           output: options.output || "cdk.out",
           ...Object.keys(context).length > 0 && { context }
         });
-        appStackNames = result.stacks.map((s) => s.stackName);
+        appStacks = result.stacks.map((s) => ({
+          stackName: s.stackName,
+          displayName: s.displayName
+        }));
       } catch {
         logger.debug("Could not synthesize app, falling back to state-based stack list");
       }
     }
     const allStateStacks = await stateBackend.listStacks();
     let candidateStacks;
-    if (appStackNames.length > 0) {
-      candidateStacks = appStackNames.filter((name) => allStateStacks.includes(name));
+    if (appStacks.length > 0) {
+      const stateSet = new Set(allStateStacks);
+      candidateStacks = appStacks.filter((s) => stateSet.has(s.stackName));
     } else if (stackArgs.length > 0 || options.stack || options.all) {
-      candidateStacks = allStateStacks;
+      candidateStacks = allStateStacks.map((name) => ({ stackName: name }));
     } else {
       throw new Error(
         "Could not determine which stacks belong to this app. Specify stack names explicitly, use --all, or ensure --app / cdk.json is configured."
@@ -27438,21 +27636,17 @@ async function destroyCommand(stackArgs, options) {
     const stackPatterns = stackArgs.length > 0 ? stackArgs : options.stack ? [options.stack] : [];
     let stackNames;
     if (options.all) {
-      stackNames = candidateStacks;
+      stackNames = candidateStacks.map((s) => s.stackName);
     } else if (stackPatterns.length > 0) {
-      stackNames = candidateStacks.filter(
-        (name) => stackPatterns.some(
-          (pattern) => pattern.includes("*") ? new RegExp("^" + pattern.replace(/\*/g, ".*") + "$").test(name) : name === pattern
-        )
-      );
+      stackNames = matchStacks(candidateStacks, stackPatterns).map((s) => s.stackName);
     } else if (candidateStacks.length === 1) {
-      stackNames = candidateStacks;
+      stackNames = candidateStacks.map((s) => s.stackName);
     } else if (candidateStacks.length === 0) {
       logger.info("No stacks found in state");
       return;
     } else {
       throw new Error(
-        `Multiple stacks found: ${candidateStacks.join(", ")}. Specify stack name(s) or use --all`
+        `Multiple stacks found: ${candidateStacks.map(describeStack).join(", ")}. Specify stack name(s) or use --all`
       );
     }
     if (stackNames.length === 0) {
@@ -27516,6 +27710,8 @@ Are you sure you want to destroy stack "${stackName}" and delete all ${resourceC
       logger.info(`
 Acquiring lock for stack ${stackName}...`);
       await lockManager.acquireLock(stackName, "destroy");
+      const renderer = getLiveRenderer();
+      renderer.start();
       try {
         logger.info("Building dependency graph...");
         const template = {
@@ -27579,6 +27775,7 @@ Acquiring lock for stack ${stackName}...`);
               logger.warn(`Resource ${logicalId} not found in state, skipping`);
               return;
             }
+            renderer.addTask(logicalId, `Deleting ${logicalId} (${resource.resourceType})`);
             try {
               const provider = destroyProviderRegistry.getProvider(resource.resourceType);
               let lastDeleteError;
@@ -27607,9 +27804,11 @@ Acquiring lock for stack ${stackName}...`);
               }
               if (lastDeleteError)
                 throw lastDeleteError;
+              renderer.removeTask(logicalId);
               logger.info(`  \u2705 ${logicalId} (${resource.resourceType}) deleted`);
               deletedCount++;
             } catch (error) {
+              renderer.removeTask(logicalId);
               const msg = error instanceof Error ? error.message : String(error);
               if (msg.includes("does not exist") || msg.includes("not found") || msg.includes("No policy found") || msg.includes("NoSuchEntity") || msg.includes("NotFoundException")) {
                 logger.debug(`  ${logicalId} already deleted, removing from state`);
@@ -27618,6 +27817,8 @@ Acquiring lock for stack ${stackName}...`);
                 logger.error(`  \u2717 Failed to delete ${logicalId}:`, String(error));
                 errorCount++;
               }
+            } finally {
+              renderer.removeTask(logicalId);
             }
           });
           await Promise.all(deletePromises);
@@ -27633,6 +27834,7 @@ Acquiring lock for stack ${stackName}...`);
 \u2713 Stack ${stackName} destroyed (${deletedCount} deleted, ${errorCount} errors)`
         );
       } finally {
+        renderer.stop();
         logger.debug("Releasing lock...");
         await lockManager.releaseLock(stackName);
         if (destroyAwsClients) {
@@ -27648,7 +27850,10 @@ Acquiring lock for stack ${stackName}...`);
   }
 }
 function createDestroyCommand() {
-  const cmd = new Command5("destroy").description("Destroy all resources in the stack").argument("[stacks...]", "Stack name(s) to destroy (supports wildcards)").option("--all", "Destroy all stacks", false).action(withErrorHandling(destroyCommand));
+  const cmd = new Command5("destroy").description("Destroy all resources in the stack").argument(
+    "[stacks...]",
+    "Stack name(s) to destroy. Accepts physical CloudFormation names (e.g. 'MyStage-Api') or CDK display paths (e.g. 'MyStage/Api'). Supports wildcards (e.g. 'MyStage/*')."
+  ).option("--all", "Destroy all stacks", false).action(withErrorHandling(destroyCommand));
   [
     ...commonOptions,
     ...appOptions,
@@ -27762,7 +27967,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command8();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.3.5");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.4.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createDeployCommand());