@go-to-k/cdkd 0.5.1 → 0.6.0

package/README.md

@@ -428,6 +428,25 @@ cdkd destroy --all --force
 
 # Force-unlock a stale lock from interrupted deploy
 cdkd force-unlock MyStack
+
+# List stacks registered in the cdkd state bucket
+cdkd state list
+cdkd state ls --long          # include resource count, last-modified, lock status
+cdkd state list --json        # JSON output (alone, or combined with --long)
+
+# List resources of a single stack from state
+cdkd state resources MyStack          # aligned columns: LogicalID, Type, PhysicalID
+cdkd state resources MyStack --long   # per-resource block with dependencies and attributes
+cdkd state resources MyStack --json   # full JSON array
+
+# Show full state record for a stack (metadata, outputs, all resources incl. properties)
+cdkd state show MyStack
+cdkd state show MyStack --json        # raw {state, lock} JSON
+
+# Remove cdkd's state record for a stack (does NOT delete AWS resources)
+cdkd state rm MyStack                 # confirmation prompt (y/N)
+cdkd state rm MyStack --yes           # skip confirmation
+cdkd state rm StackA StackB --force   # also bypass the locked-stack refusal
 ```
 
 ### Concurrency Options

package/dist/cli.js

@@ -447,7 +447,7 @@ var init_aws_clients = __esm({
 });
 
 // src/cli/index.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/cli/commands/bootstrap.ts
 import { Command } from "commander";
@@ -3563,6 +3563,18 @@ var LockManager = class {
       );
     }
   }
+  /**
+   * Check whether a lock currently exists for a stack
+   *
+   * Returns true if a lock file is present in S3 (regardless of expiry).
+   * This is intended for read-only inspection (e.g. `cdkd state list --long`),
+   * not for acquisition decisions — use `acquireLock` for that, which has its
+   * own expired-lock cleanup logic.
+   */
+  async isLocked(stackName) {
+    const lockInfo = await this.getLockInfo(stackName);
+    return lockInfo !== null;
+  }
   /**
    * Release a lock for a stack
    */
@@ -28089,6 +28101,337 @@ function createForceUnlockCommand() {
   return cmd;
 }
 
+// src/cli/commands/state.ts
+import * as readline2 from "node:readline/promises";
+import { Command as Command9 } from "commander";
+init_aws_clients();
+async function setupStateBackend(options) {
+  const awsClients = new AwsClients({
+    ...options.region && { region: options.region },
+    ...options.profile && { profile: options.profile }
+  });
+  setAwsClients(awsClients);
+  const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+  const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
+  const prefix = options.statePrefix;
+  const stateConfig = { bucket, prefix };
+  const stateBackend = new S3StateBackend(awsClients.s3, stateConfig);
+  const lockManager = new LockManager(awsClients.s3, stateConfig);
+  await stateBackend.verifyBucketExists();
+  return {
+    stateBackend,
+    lockManager,
+    bucket,
+    prefix,
+    dispose: () => awsClients.destroy()
+  };
+}
+async function stateListCommand(options) {
+  const logger = getLogger();
+  if (options.verbose)
+    logger.setLevel("debug");
+  const setup = await setupStateBackend(options);
+  try {
+    const stackNames = (await setup.stateBackend.listStacks()).slice().sort();
+    if (!options.long && !options.json) {
+      for (const name of stackNames) {
+        process.stdout.write(`${name}
+`);
+      }
+      return;
+    }
+    if (options.json && !options.long) {
+      process.stdout.write(`${JSON.stringify(stackNames, null, 2)}
+`);
+      return;
+    }
+    const details = await Promise.all(
+      stackNames.map(async (stackName) => {
+        const [stateResult, locked] = await Promise.all([
+          setup.stateBackend.getState(stackName),
+          setup.lockManager.isLocked(stackName)
+        ]);
+        const state = stateResult?.state;
+        return {
+          stackName,
+          resourceCount: state ? Object.keys(state.resources).length : 0,
+          lastModified: state && typeof state.lastModified === "number" ? new Date(state.lastModified).toISOString() : null,
+          locked
+        };
+      })
+    );
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(details, null, 2)}
+`);
+      return;
+    }
+    const lines = [];
+    for (const detail of details) {
+      lines.push(detail.stackName);
+      lines.push(`  Resources: ${detail.resourceCount}`);
+      lines.push(`  Last Modified: ${detail.lastModified ?? "unknown"}`);
+      lines.push(`  Lock: ${detail.locked ? "locked" : "unlocked"}`);
+      lines.push("");
+    }
+    if (lines.length > 0) {
+      if (lines[lines.length - 1] === "") {
+        lines.pop();
+      }
+      process.stdout.write(`${lines.join("\n")}
+`);
+    }
+  } finally {
+    setup.dispose();
+  }
+}
+function createStateListCommand() {
+  const cmd = new Command9("list").alias("ls").description("List stacks registered in the cdkd state bucket").option("-l, --long", "Show resource count, last-modified time, and lock status", false).option("--json", "Output as JSON", false).action(withErrorHandling(stateListCommand));
+  [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+  return cmd;
+}
+async function stateResourcesCommand(stackName, options) {
+  const logger = getLogger();
+  if (options.verbose)
+    logger.setLevel("debug");
+  const setup = await setupStateBackend(options);
+  try {
+    const stateResult = await setup.stateBackend.getState(stackName);
+    if (!stateResult) {
+      throw new Error(
+        `No state found for stack '${stackName}' in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
+      );
+    }
+    const resources = stateResult.state.resources ?? {};
+    const details = Object.entries(resources).map(([logicalId, resource]) => ({
+      logicalId,
+      resourceType: resource.resourceType,
+      physicalId: resource.physicalId,
+      dependencies: resource.dependencies ?? [],
+      attributes: resource.attributes ?? {}
+    })).sort((a, b) => a.logicalId.localeCompare(b.logicalId));
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(details, null, 2)}
+`);
+      return;
+    }
+    if (details.length === 0) {
+      return;
+    }
+    if (options.long) {
+      const lines = [];
+      for (const detail of details) {
+        lines.push(detail.logicalId);
+        lines.push(`  Type: ${detail.resourceType}`);
+        lines.push(`  PhysicalID: ${detail.physicalId}`);
+        lines.push(
+          `  Dependencies: ${detail.dependencies.length > 0 ? detail.dependencies.join(", ") : "(none)"}`
+        );
+        const attrEntries = Object.entries(detail.attributes);
+        if (attrEntries.length === 0) {
+          lines.push("  Attributes: (none)");
+        } else {
+          lines.push("  Attributes:");
+          for (const [k, v] of attrEntries) {
+            lines.push(`    ${k}: ${formatAttributeValue(v)}`);
+          }
+        }
+        lines.push("");
+      }
+      if (lines[lines.length - 1] === "") {
+        lines.pop();
+      }
+      process.stdout.write(`${lines.join("\n")}
+`);
+      return;
+    }
+    const idWidth = Math.max(...details.map((d) => d.logicalId.length));
+    const typeWidth = Math.max(...details.map((d) => d.resourceType.length));
+    for (const detail of details) {
+      process.stdout.write(
+        `${detail.logicalId.padEnd(idWidth)}  ${detail.resourceType.padEnd(typeWidth)}  ${detail.physicalId}
+`
+      );
+    }
+  } finally {
+    setup.dispose();
+  }
+}
+function formatAttributeValue(value) {
+  if (value === null)
+    return "null";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60)
+    return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m${remainingSeconds}s`;
+}
+function formatLockSummary(lockInfo) {
+  if (!lockInfo)
+    return "unlocked";
+  const opStr = lockInfo.operation ? ` (operation: ${lockInfo.operation})` : "";
+  const expiresInMs = lockInfo.expiresAt - Date.now();
+  const expiresStr = expiresInMs > 0 ? `expires in ${formatDuration(expiresInMs)}` : `expired ${formatDuration(-expiresInMs)} ago`;
+  return `locked by ${lockInfo.owner}${opStr}, ${expiresStr}`;
+}
+function createStateResourcesCommand() {
+  const cmd = new Command9("resources").description("List resources recorded in a stack's state").argument("<stack>", "Stack name (physical CloudFormation name)").option("-l, --long", "Include dependencies and attributes per resource", false).option("--json", "Output as JSON", false).action(withErrorHandling(stateResourcesCommand));
+  [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+  return cmd;
+}
+async function stateShowCommand(stackName, options) {
+  const logger = getLogger();
+  if (options.verbose)
+    logger.setLevel("debug");
+  const setup = await setupStateBackend(options);
+  try {
+    const [stateResult, lockInfo] = await Promise.all([
+      setup.stateBackend.getState(stackName),
+      setup.lockManager.getLockInfo(stackName)
+    ]);
+    if (!stateResult) {
+      throw new Error(
+        `No state found for stack '${stackName}' in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
+      );
+    }
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify({ state: stateResult.state, lock: lockInfo }, null, 2)}
+`
+      );
+      return;
+    }
+    const state = stateResult.state;
+    const lines = [];
+    lines.push(`Stack: ${state.stackName}`);
+    if (state.region)
+      lines.push(`  Region: ${state.region}`);
+    lines.push(`  Version: ${state.version}`);
+    lines.push(`  Last Modified: ${new Date(state.lastModified).toISOString()}`);
+    lines.push(`  Lock: ${formatLockSummary(lockInfo)}`);
+    const outputEntries = Object.entries(state.outputs ?? {});
+    if (outputEntries.length > 0) {
+      lines.push("");
+      lines.push("Outputs:");
+      for (const [k, v] of outputEntries) {
+        lines.push(`  ${k}: ${formatAttributeValue(v)}`);
+      }
+    }
+    const resourceEntries = Object.entries(state.resources ?? {}).sort(
+      ([a], [b]) => a.localeCompare(b)
+    );
+    lines.push("");
+    lines.push(`Resources (${resourceEntries.length}):`);
+    for (const [logicalId, resource] of resourceEntries) {
+      lines.push("");
+      lines.push(logicalId);
+      lines.push(`  Type: ${resource.resourceType}`);
+      lines.push(`  PhysicalID: ${resource.physicalId}`);
+      const deps = resource.dependencies ?? [];
+      lines.push(`  Dependencies: ${deps.length > 0 ? deps.join(", ") : "(none)"}`);
+      const attrEntries = Object.entries(resource.attributes ?? {});
+      if (attrEntries.length === 0) {
+        lines.push("  Attributes: (none)");
+      } else {
+        lines.push("  Attributes:");
+        for (const [k, v] of attrEntries) {
+          lines.push(`    ${k}: ${formatAttributeValue(v)}`);
+        }
+      }
+      const propEntries = Object.entries(resource.properties ?? {});
+      if (propEntries.length === 0) {
+        lines.push("  Properties: (none)");
+      } else {
+        lines.push("  Properties:");
+        for (const [k, v] of propEntries) {
+          lines.push(`    ${k}: ${formatAttributeValue(v)}`);
+        }
+      }
+    }
+    process.stdout.write(`${lines.join("\n")}
+`);
+  } finally {
+    setup.dispose();
+  }
+}
+function createStateShowCommand() {
+  const cmd = new Command9("show").description("Show the full cdkd state record for a stack (metadata, outputs, resources)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--json", "Output the raw state and lock as JSON", false).action(withErrorHandling(stateShowCommand));
+  [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+  return cmd;
+}
+async function stateRmCommand(stackArgs, options) {
+  const logger = getLogger();
+  if (options.verbose)
+    logger.setLevel("debug");
+  if (stackArgs.length === 0) {
+    throw new Error("Stack name is required. Usage: cdkd state rm <stack> [<stack>...]");
+  }
+  const setup = await setupStateBackend(options);
+  try {
+    for (const stackName of stackArgs) {
+      const exists = await setup.stateBackend.stateExists(stackName);
+      if (!exists) {
+        logger.info(`No state found for stack: ${stackName}, skipping`);
+        continue;
+      }
+      if (!options.force) {
+        const locked = await setup.lockManager.isLocked(stackName);
+        if (locked) {
+          throw new Error(
+            `Stack '${stackName}' is locked. Run 'cdkd force-unlock ${stackName}' first, or pass --force to remove anyway.`
+          );
+        }
+      }
+      if (!options.yes && !options.force) {
+        process.stdout.write(
+          `
+WARNING: This removes cdkd's state record for '${stackName}' only. AWS resources will NOT be deleted.
+Use 'cdkd destroy ${stackName}' if you want to delete the actual resources.
+
+`
+        );
+        const rl = readline2.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        const answer = await rl.question(
+          `Remove state for stack '${stackName}' from s3://${setup.bucket}/${setup.prefix}/? (y/N): `
+        );
+        rl.close();
+        const trimmed = answer.trim().toLowerCase();
+        if (trimmed !== "y" && trimmed !== "yes") {
+          logger.info(`Cancelled removal of state for stack: ${stackName}`);
+          continue;
+        }
+      }
+      await setup.stateBackend.deleteState(stackName);
+      await setup.lockManager.forceReleaseLock(stackName);
+      logger.info(`\u2713 Removed state for stack: ${stackName}`);
+    }
+  } finally {
+    setup.dispose();
+  }
+}
+function createStateRmCommand() {
+  const cmd = new Command9("rm").description("Remove cdkd state for one or more stacks (does NOT delete AWS resources)").argument("<stacks...>", "Stack name(s) to remove from state").option("-f, --force", "Skip confirmation and remove even if the stack is locked", false).action(withErrorHandling(stateRmCommand));
+  [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+  return cmd;
+}
+function createStateCommand() {
+  const cmd = new Command9("state").description("Manage cdkd state stored in S3");
+  cmd.addCommand(createStateListCommand());
+  cmd.addCommand(createStateResourcesCommand());
+  cmd.addCommand(createStateShowCommand());
+  cmd.addCommand(createStateRmCommand());
+  return cmd;
+}
+
 // src/cli/index.ts
 var SUBCOMMANDS = /* @__PURE__ */ new Set([
   "bootstrap",
@@ -28099,7 +28442,8 @@ var SUBCOMMANDS = /* @__PURE__ */ new Set([
   "diff",
   "destroy",
   "publish-assets",
-  "force-unlock"
+  "force-unlock",
+  "state"
 ]);
 function reorderArgs(argv) {
   const prefix = argv.slice(0, 2);
@@ -28112,8 +28456,8 @@ function reorderArgs(argv) {
   return [...prefix, ...cmdAndAfter, ...beforeCmd];
 }
 async function main() {
-  const program = new Command9();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.5.1");
+  const program = new Command10();
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.6.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());
@@ -28122,6 +28466,7 @@ async function main() {
   program.addCommand(createDestroyCommand());
   program.addCommand(createPublishAssetsCommand());
   program.addCommand(createForceUnlockCommand());
+  program.addCommand(createStateCommand());
   const args = reorderArgs(process.argv);
   await program.parseAsync(args);
 }