@go-to-k/cdkd 0.48.0 → 0.49.0

package/README.md

@@ -171,6 +171,57 @@ the full per-type table.
 | CC API null value stripping | ✅ | Removes null values before API calls |
 | Retry with HTTP status codes | ✅ | 429/503 + cause chain inspection |
 
+### Drift detection
+
+`cdkd drift <stack>` (state-driven; no synth) compares each resource
+between the AWS-current snapshot returned by `provider.readCurrentState`
+and the **deploy-time AWS snapshot** stored in
+`ResourceState.observedProperties`. The observedProperties baseline is
+populated automatically on every successful `cdkd deploy` /
+`cdkd import`, so console-side changes to keys you did NOT template
+(IAM policies attached out-of-band, S3 public-access-block toggled,
+etc.) surface as drift instead of being silently ignored.
+
+State schema `version: 3` (the layout that carries observedProperties)
+is auto-migrated on the next write — no user action needed for new
+deploys. **For stacks already deployed with an older binary**, the
+upgrade story is:
+
+1. `cdkd 0.46.x` (or earlier) deployed your stack — state.json is
+   `version: 2`, no observedProperties on any resource.
+2. Upgrade cdkd to `0.47.0+`. The new binary reads v2 state cleanly,
+   and `cdkd drift` falls back to comparing against the user-templated
+   `properties` field (= the pre-v3 behavior) for any resource that
+   hasn't been refreshed yet.
+3. **Populate observedProperties** for the existing stack — pick one:
+
+   ```bash
+   # Option A (recommended): explicit refresh, no redeploy.
+   cdkd state refresh-observed MyStack
+
+   # Option B: trigger an UPDATE on each affected resource via the
+   # next `cdkd deploy`. NO_CHANGE-skipped resources are NOT refreshed
+   # by deploy alone — only the ones whose template changed get a
+   # readCurrentState call. Use this only if you're already changing
+   # the template; for an upgrade-and-refresh-only flow prefer A.
+   cdkd deploy MyStack
+   ```
+4. Re-run `cdkd drift MyStack` — now observed-baseline drift detection
+   is fully enabled.
+
+`cdkd state refresh-observed --all` does the same for every stack in
+the state bucket; `--dry-run` prints the per-stack refresh count
+without touching state. Resolve any drift the comparator finds with
+`cdkd drift <stack> --accept` (state ← AWS) or `--revert` (AWS ← state).
+
+`cdkd deploy --no-capture-observed-state` (or
+`cdk.json context.cdkd.captureObservedState: false`) opts out of the
+capture entirely if you care more about deploy speed than rich drift
+detection — drift then falls back to comparing against `properties`,
+the pre-v3 behavior. Bench measurements show roughly +0–4% deploy
+time with the capture on (lambda integ within noise; bench-cdk-sample
++3.4% median).
+
 ## Prerequisites
 
 - **Node.js** >= 20.0.0
@@ -300,6 +351,14 @@ cdkd drift MyStack --accept --yes
 # Resolve drift: AWS ← state (push state values back into AWS via provider.update)
 cdkd drift MyStack --revert --yes
 
+# Refresh the deploy-time AWS snapshot used as drift baseline.
+# Run this once after upgrading from a pre-v3 cdkd binary (= state schema
+# `version: 2`) so console-side changes to keys you didn't template can
+# be detected for resources that won't change in any near-future deploy.
+# Same idempotent behavior on the same v3 state — see "Drift detection"
+# below for the full upgrade story.
+cdkd state refresh-observed MyStack
+
 # Dry run (plan only, no changes)
 cdkd deploy --dry-run
 

package/dist/cli.js

@@ -39028,6 +39028,14 @@ async function runDriftForStack(stackName, region, stateBackend, providerRegistr
           resource.properties ?? {}
         );
       } else {
+        if (resource.resourceType.startsWith("Custom::")) {
+          outcomes.push({
+            kind: "unsupported",
+            logicalId,
+            resourceType: resource.resourceType
+          });
+          continue;
+        }
         if (CC_API_FALLBACK_DENY_LIST[resource.resourceType]) {
           outcomes.push({
             kind: "unsupported",
@@ -41846,6 +41854,215 @@ function createStateInfoCommand() {
   [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
   return cmd;
 }
+async function stateRefreshObservedCommand(stackArgs, options) {
+  const logger = getLogger();
+  if (options.verbose)
+    logger.setLevel("debug");
+  if (!options.all && stackArgs.length === 0) {
+    throw new Error(
+      "Stack name is required. Usage: cdkd state refresh-observed <stack> [<stack>...] | --all"
+    );
+  }
+  const setup = await setupStateBackend(options);
+  const providerRegistry = new ProviderRegistry();
+  registerAllProviders(providerRegistry);
+  providerRegistry.setCustomResourceResponseBucket(setup.bucket);
+  try {
+    const stateRefs = await setup.stateBackend.listStacks();
+    let targets;
+    if (options.all) {
+      targets = options.stackRegion ? stateRefs.filter((r) => r.region === options.stackRegion) : stateRefs;
+      if (targets.length === 0) {
+        logger.info("No stacks found in state");
+        return;
+      }
+    } else {
+      targets = [];
+      for (const stackName of stackArgs) {
+        const matches = stateRefs.filter((r) => r.stackName === stackName);
+        if (matches.length === 0) {
+          throw new Error(
+            `No state found for stack '${stackName}'. Run 'cdkd state list' to see available stacks.`
+          );
+        }
+        if (options.stackRegion) {
+          const ref = matches.find((r) => r.region === options.stackRegion);
+          if (!ref) {
+            const seen = matches.map((r) => r.region ?? "(legacy)").join(", ");
+            throw new Error(
+              `No state found for stack '${stackName}' in region '${options.stackRegion}'. Available regions: ${seen}.`
+            );
+          }
+          targets.push(ref);
+        } else if (matches.length === 1) {
+          targets.push(matches[0]);
+        } else {
+          const regions = matches.map((r) => r.region ?? "(legacy)").join(", ");
+          throw new Error(
+            `Stack '${stackName}' has state in multiple regions: ${regions}. Re-run with --stack-region <region> to disambiguate.`
+          );
+        }
+      }
+    }
+    if (!options.yes && !options.dryRun) {
+      const targetList = targets.map(formatStackRef).join(", ");
+      const ok = await confirmRefresh(
+        `Refresh observedProperties for ${targets.length} stack(s) (${targetList})?`
+      );
+      if (!ok) {
+        logger.info("Aborted.");
+        return;
+      }
+    }
+    let totalRefreshed = 0;
+    let totalUnsupported = 0;
+    let totalFailed = 0;
+    for (const target of targets) {
+      if (!target.region) {
+        throw new Error(
+          `Stack '${target.stackName}' has only a legacy state record without a region. Run 'cdkd deploy ${target.stackName}' (or any cdkd write) first to migrate it to the region-scoped layout, then re-run refresh-observed.`
+        );
+      }
+      const counts = await refreshObservedForStack(
+        target.stackName,
+        target.region,
+        setup.stateBackend,
+        setup.lockManager,
+        providerRegistry,
+        { dryRun: options.dryRun ?? false, logger }
+      );
+      totalRefreshed += counts.refreshed;
+      totalUnsupported += counts.unsupported;
+      totalFailed += counts.failed;
+    }
+    const summary = options.dryRun ? `Plan: ${totalRefreshed} resource(s) would be refreshed, ${totalUnsupported} unsupported, ${totalFailed} would fail (--dry-run, no state was written)` : `Done: ${totalRefreshed} resource(s) refreshed, ${totalUnsupported} unsupported, ${totalFailed} failed`;
+    logger.info(`
+${summary}`);
+    if (totalFailed > 0) {
+      throw new PartialFailureError(
+        `Refresh completed with ${totalFailed} per-resource readCurrentState failure(s). Affected resources keep their previous observedProperties (or no observedProperties at all). Re-run 'cdkd state refresh-observed' to retry.`
+      );
+    }
+  } finally {
+    setup.dispose();
+  }
+}
+async function refreshObservedForStack(stackName, region, stateBackend, lockManager, providerRegistry, opts) {
+  const { logger } = opts;
+  const result = await stateBackend.getState(stackName, region);
+  if (!result) {
+    throw new Error(
+      `No state found for stack '${stackName}' (${region}). Run 'cdkd state list' to see available stacks.`
+    );
+  }
+  const { state, etag, migrationPending } = result;
+  const entries = Object.entries(state.resources ?? {});
+  if (entries.length === 0) {
+    logger.info(`\u2713 ${stackName} (${region}): no resources in state, skipping`);
+    return { refreshed: 0, unsupported: 0, failed: 0 };
+  }
+  if (opts.dryRun) {
+    let wouldRefresh = 0;
+    let wouldUnsupported = 0;
+    for (const [, resource] of entries) {
+      let provider;
+      try {
+        provider = providerRegistry.getProvider(resource.resourceType);
+      } catch {
+        wouldUnsupported++;
+        continue;
+      }
+      if (provider.readCurrentState)
+        wouldRefresh++;
+      else
+        wouldUnsupported++;
+    }
+    logger.info(
+      `Plan ${stackName} (${region}): ${wouldRefresh} resource(s) would be refreshed, ${wouldUnsupported} unsupported`
+    );
+    return { refreshed: wouldRefresh, unsupported: wouldUnsupported, failed: 0 };
+  }
+  const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
+  await lockManager.acquireLock(stackName, region, owner, "state-refresh-observed");
+  try {
+    let refreshed = 0;
+    let unsupported = 0;
+    let failed = 0;
+    await withStackName(stackName, async () => {
+      const tasks = entries.map(async ([logicalId, resource]) => {
+        if (providerRegistry.shouldSkipResource(resource.resourceType)) {
+          unsupported++;
+          return;
+        }
+        let provider;
+        try {
+          provider = providerRegistry.getProvider(resource.resourceType);
+        } catch {
+          unsupported++;
+          return;
+        }
+        if (!provider.readCurrentState) {
+          unsupported++;
+          return;
+        }
+        try {
+          const observed = await provider.readCurrentState(
+            resource.physicalId,
+            logicalId,
+            resource.resourceType,
+            resource.properties ?? {}
+          );
+          if (observed === void 0) {
+            unsupported++;
+            return;
+          }
+          resource.observedProperties = observed;
+          refreshed++;
+        } catch (err) {
+          failed++;
+          logger.warn(
+            `  \u2717 ${stackName}/${logicalId} (${resource.resourceType}): readCurrentState failed \u2014 ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      });
+      await Promise.all(tasks);
+    });
+    state.lastModified = Date.now();
+    const saveOptions = {
+      expectedEtag: etag
+    };
+    if (migrationPending)
+      saveOptions.migrateLegacy = true;
+    await stateBackend.saveState(stackName, region, state, saveOptions);
+    logger.info(
+      `\u2713 ${stackName} (${region}): ${refreshed} refreshed, ${unsupported} unsupported, ${failed} failed`
+    );
+    return { refreshed, unsupported, failed };
+  } finally {
+    await lockManager.releaseLock(stackName, region).catch((err) => {
+      logger.warn(
+        `Failed to release lock for ${stackName} (${region}): ` + (err instanceof Error ? err.message : String(err))
+      );
+    });
+  }
+}
+async function confirmRefresh(prompt) {
+  const rl = readline5.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = await rl.question(`${prompt} [y/N] `);
+    return /^y(es)?$/i.test(ans.trim());
+  } finally {
+    rl.close();
+  }
+}
+function createStateRefreshObservedCommand() {
+  const cmd = new Command12("refresh-observed").description(
+    "Refresh observedProperties for every resource in a stack by calling provider.readCurrentState \u2014 populates the drift baseline for stacks deployed before state schema v3, without redeploying."
+  ).argument("[stacks...]", "Stack name(s) to refresh (physical CloudFormation names)").option("--all", "Refresh every stack in the state bucket", false).option("--dry-run", "Print the per-stack refresh count without writing state", false).addOption(stackRegionOption2()).action(withErrorHandling(stateRefreshObservedCommand));
+  [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
+  cmd.addOption(deprecatedRegionOption);
+  return cmd;
+}
 function createStateCommand() {
   const cmd = new Command12("state").description("Manage cdkd state stored in S3");
   cmd.addCommand(createStateInfoCommand());
@@ -41855,6 +42072,7 @@ function createStateCommand() {
   cmd.addCommand(createStateOrphanCommand());
   cmd.addCommand(createStateDestroyCommand());
   cmd.addCommand(createStateMigrateCommand());
+  cmd.addCommand(createStateRefreshObservedCommand());
   return cmd;
 }
 
@@ -42637,7 +42855,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command14();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.48.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.49.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());