@intentius/chant-lexicon-aws 0.124.51 → 0.124.54

package/src/components/cfn-plan.test.ts

@@ -15,6 +15,7 @@ import { applyPrSet, planPrSet, prReport } from "@intentius/chant/components/pr-
 import { composeChangeSet } from "@intentius/chant/change-set";
 import { groupChangeSet, planSummaryHeadline } from "@intentius/chant/plan-summary";
 import { memberCounts, prStatusDescription, renderPrNote } from "@intentius/chant/pr-loop";
+import { PlanShapeMovedError } from "@intentius/chant/components/covered-round";
 import { CfnPlanMovedError, CfnReplacementBlockedError, cfnChangeEntry, createCfnDeployCapability, type CfnDeployInput } from "./apply";
 import { isPlanMovedError } from "@intentius/chant/components/capability";
 import { planMovedIn } from "@intentius/chant/components/driver";
@@ -122,6 +123,31 @@ describe("cfn-deploy plan (#4084)", () => {
     expect(planned.outputs).toEqual({ known: { Region: "us-east-1", TopicArn: "arn:topic" }, unknown: ["EnvName", "Imported", "QueueUrl", "TableArn"] });
   });
 
+  it("an output that is a plain string, or a Ref to a parameter this plan has a value for, is known at that value, changed or new (#4419)", async () => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { Port: { Type: "String" }, Later: { Type: "String" } },
+        Resources: { Setting: { Type: "AWS::SSM::Parameter" } },
+        Outputs: {
+          Literal: { Value: "8090" },
+          NewLiteral: { Value: "9000" },
+          Passed: { Value: { Ref: "Port" } },
+          NotYet: { Value: { Ref: "Later" } },
+          Setting: { Value: { Ref: "Setting" } },
+        },
+      }),
+    );
+    const { planned } = await planOne(
+      {
+        outputs: { Literal: "8080", Passed: "8080", NotYet: "x", Setting: "/setting" },
+        changes: [{ action: "Modify", logicalResourceId: "Setting", resourceType: "AWS::SSM::Parameter", replacement: false, replacementMode: "False" }],
+      },
+      { inputs: { Port: "8090" } },
+    );
+    expect(planned.outputs).toEqual({ known: { Literal: "8090", NewLiteral: "9000", Passed: "8090", Setting: "/setting" }, unknown: ["NotYet"] });
+  });
+
   it("a stack the change set creates says nothing of its outputs (#3999)", async () => {
     const { planned } = await planOne({ missing: true, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] });
     expect(planned.outputs).toBeUndefined();
@@ -240,7 +266,8 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
     expect(set.plannedOutputs).toEqual({ network: [] });
     expect(set.members.find((m) => m.member === "cluster-a")?.unknownInputs).toEqual(["network.TopicArn"]);
     const note = renderPrNote(report);
-    expect(note).toContain("| `cluster-a` | cluster-a | planned; inputs from network; re-checked on apply | ? | ? | ? | ? |");
+    // The member is previewed against a stand-in, so it counts its changes (#4419).
+    expect(note).toContain("| `cluster-a` | cluster-a | planned | 1 | 0 | 0 | 0 |");
     expect(note).toContain("Known only after apply: `cluster-a` reads `network.TopicArn`.");
   });
 
@@ -259,19 +286,28 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
     expect(created.find((c) => c.stackName === "cluster-a")?.parameters).toEqual({ TopicArn: "arn:topic" });
   });
 
-  it("a member whose inputs come from a stack the run creates first says so, with no counts and no change set", async () => {
+  it("a member whose inputs come from a stack the run creates first is previewed against a stand-in, and the stand-in is deleted (#4419)", async () => {
     const { mock, set, report } = await planBoth({
       network: { missing: true, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] },
-      "cluster-a": { missing: true },
+      "cluster-a": { missing: true, changes: [{ action: "Add", logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false }] },
     });
     const clusterA = set.doc.members.find((m) => m.member === "cluster-a")!;
-    expect(clusterA).toMatchObject({ status: "planned", holes: [{ address: "cluster-a", reason: "inputs from network; re-checked on apply" }] });
-    expect(set.doc.entries.filter((e) => e.member === "cluster-a")).toEqual([]);
-    expect(mock.calls.filter((c) => c.method === "createChangeSet").map((c) => (c.args as { stackName: string }).stackName)).toEqual(["network"]);
+    expect(clusterA).toMatchObject({ status: "planned", holes: [] });
+    expect(set.doc.entries.filter((e) => e.member === "cluster-a")).toHaveLength(1);
+    const created = mock.calls.filter((c) => c.method === "createChangeSet").map((c) => c.args as { stackName: string; parameters?: Record<string, string> });
+    expect(created.find((c) => c.stackName === "cluster-a")?.parameters).toEqual({ TopicArn: "known-after-apply" });
+    const deleted = mock.calls.filter((c) => c.method === "deleteChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+    expect(deleted.sort()).toEqual(["cluster-a", "network"]);
     const note = renderPrNote(report);
-    expect(note).toContain("| `cluster-a` | cluster-a | planned; inputs from network; re-checked on apply | ? | ? | ? | ? |");
+    expect(note).toContain("| `cluster-a` | cluster-a | planned | 1 | 0 | 0 | 0 |");
     expect(note).toContain("| `network` | network | planned | 1 | 0 | 0 | 0 |");
-    expect(prStatusDescription(report)).toContain("1 with holes");
+  });
+
+  it("a member whose upstream is unresolved but names no unknown input stays a hole", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: {} } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["up"] }, { stack: "network", template });
+    expect(planned.changeSet?.member.holes).toMatchObject([{ reason: "inputs from up; re-checked on apply" }]);
+    expect(mock.calls.filter((c) => c.method === "createChangeSet")).toEqual([]);
   });
 
   it("planning the same state twice gives the same digest, so the apply's plan matches the approved one", async () => {
@@ -335,7 +371,7 @@ describe("cfn-deploy applies the change set it planned (#3997)", () => {
     expect(methods(mock).slice(3)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
   });
 
-  it("a member with holes hands run no artifact, so run plans it afresh", async () => {
+  it("a member with a hole it could not preview hands run no artifact, so run plans it afresh", async () => {
     const mock = createMockCloudExecutor({ stacks: { network: { changes: [queueAdd] } } });
     const capability = createCfnDeployCapability(mock.executor);
     const planned = await capability.plan!({ ...ctx, unresolvedInputs: ["upstream"] }, { stack: "network", template });
@@ -438,3 +474,286 @@ describe("cfn-deploy targets (#4300)", () => {
     expect(targetRefusal(createCfnDeployCapability(createMockCloudExecutor().executor))).toMatch(/cfn-deploy can't narrow/);
   });
 });
+
+describe("cfn-deploy previews a member whose inputs are unknown, and checks the real change against it (#4419)", () => {
+  const eni = { action: "Modify" as const, logicalResourceId: "Eni", resourceType: "AWS::EC2::NetworkInterface", replacement: false, replacementMode: "False" as const };
+  const withDriver = (property: string, causingEntity = "SubnetId") => ({
+    ...eni,
+    details: [property, "Description"],
+    drivers: [{ property, changeSource: "ParameterReference", causingEntity }, { property: "Description", changeSource: "DirectModification" }],
+  });
+  const input = (): CfnDeployInput => ({ stack: "net", template, inputs: { SubnetId: undefined as never } });
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" }, Desc: { Type: "String", Default: "x" } },
+        Resources: {
+          Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" }, Description: "d" } },
+          Q: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "q-${SubnetId}" } } },
+        },
+      }),
+    );
+  });
+
+  const q = { action: "Add" as const, logicalResourceId: "Q", resourceType: "AWS::SQS::Queue", replacement: false };
+
+  it("creates the change set with an id-shaped stand-in, marks the driven properties unknown, and deletes the change set", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [withDriver("SubnetId"), q] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input());
+    const created = mock.calls.find((c) => c.method === "createChangeSet")!.args as { parameters: Record<string, string> };
+    expect(created.parameters).toEqual({ SubnetId: "subnet-00000000known-after-apply" });
+    const entries = planned.changeSet!.entries;
+    expect(entries.find((e) => e.address === "Eni")?.attributes).toEqual([
+      { path: "Description" },
+      { path: "SubnetId", unknown: true },
+    ]);
+    // A create names no properties; the template says which one reads the parameter.
+    expect(entries.find((e) => e.address === "Q")?.attributes).toEqual([{ path: "QueueName", unknown: true }]);
+    expect(planned.changeSet!.member.holes).toEqual([]);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet"]);
+    expect(planned.artifact).toMatchObject({ kind: "cfn-deploy-shape" });
+    // The preview reports its shape to core, unknown where a placeholder drives it (#4419).
+    expect(planned.shape).toMatchObject({ member: "net", unknownInputs: ["vpc"] });
+    expect(planned.shape!.entries.find((e) => e.logicalId === "Eni")).toMatchObject({ action: "update", replacement: "false", properties: ["Description", "SubnetId"], unknown: ["SubnetId"] });
+    expect(planned.shape!.entries.find((e) => e.logicalId === "Q")).toMatchObject({ action: "create", unknown: ["QueueName"] });
+  });
+
+  it("a previewed member still says the outputs that do not read an unknown input (#4419)", async () => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" }, Port: { Type: "String" } },
+        Resources: { Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" } } } },
+        Outputs: { Port: { Value: { Ref: "Port" } }, Fixed: { Value: "8080" }, Id: { Value: { Ref: "SubnetId" } } },
+      }),
+    );
+    const mock = createMockCloudExecutor({ stacks: { net: { outputs: { Port: "1", Fixed: "1", Id: "x" }, changes: [{ ...eni, action: "Add" as const, details: [] }] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, { stack: "net", template, inputs: { SubnetId: undefined as never, Port: "8080" } });
+    expect(planned.outputs).toEqual({ known: { Fixed: "8080", Port: "8080" }, unknown: ["Id"] });
+  });
+
+  it("a conditional replacement in the real change set is read as conditional", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [{ ...eni, replacementMode: "Conditional" as never }] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!(ctx, { stack: "net", template, inputs: { SubnetId: "subnet-1" } });
+    expect(planned.shape!.entries[0]).toMatchObject({ logicalId: "Eni", replacement: "conditional" });
+  });
+
+  it("falls back to a hole when CloudFormation refuses the stand-in", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [] } } });
+    const real = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async () => {
+      throw new Error("Parameter validation failed: parameter value subnet-00000000known-after-apply for parameter name SubnetId does not exist");
+    };
+    void real;
+    const planned = await createCfnDeployCapability(mock.executor).plan!(ctx, input());
+    expect(planned.artifact).toBeUndefined();
+    expect(planned.changeSet!.member.holes[0].reason).toMatch(/no preview: CloudFormation refused .*does not exist/);
+  });
+
+  async function previewThenRun(previewed: ReturnType<typeof withDriver>[], real: Array<typeof eni | typeof q | ReturnType<typeof withDriver>>) {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: previewed } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, input());
+    mock.setStack("net", { changes: real });
+    const result = await capability.run({ ...ctx, plans: { net: planned.artifact } }, { stack: "net", template, inputs: { SubnetId: "subnet-1" } }).catch((e: unknown) => e);
+    return { mock, result };
+  }
+
+  it("executes when the real change matches the preview", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [withDriver("SubnetId")]);
+    expect(result).toMatchObject({ stackStatus: expect.any(String) });
+    expect(methods(mock)).toContain("executeChangeSet");
+  });
+
+  it("executes when an unknown-driven property drops out because the real value equals the current one", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [{ ...eni, details: ["Description"] }]);
+    expect(result).toMatchObject({ stackStatus: expect.any(String) });
+    expect(methods(mock)).toContain("executeChangeSet");
+  });
+
+  it("refuses, executing nothing, when the real change adds a resource", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [withDriver("SubnetId"), q]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("net now plans to create Q, which the first plan did not");
+    expect((result as { planMoved?: boolean }).planMoved).toBe(true);
+    expect(methods(mock)).not.toContain("executeChangeSet");
+    expect(methods(mock).at(-1)).toBe("deleteChangeSet");
+  });
+
+  it("refuses when a property no unknown input drives stops changing", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [{ ...eni, details: ["SubnetId"] }]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("no longer changes Description on Eni");
+    expect(methods(mock)).not.toContain("executeChangeSet");
+  });
+
+  it("refuses when the real change replaces and the preview did not", async () => {
+    const { result } = await previewThenRun([withDriver("SubnetId")], [{ ...withDriver("SubnetId"), replacementMode: "Conditional" as never }]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("may now replace Eni, which the first plan did not show");
+  });
+});
+
+describe("pr-apply through AWS and core together: a previewed member in a round (#4422, #4423)", () => {
+  const queueAdd = { action: "Add" as const, logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false };
+  const extraAdd = { action: "Add" as const, logicalResourceId: "Extra", resourceType: "AWS::SNS::Topic", replacement: false };
+  const approvedFirst = { status: "approved" as const, approvedBy: ["github:rev"] };
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { TopicArn: { Type: "String" } },
+        Resources: { Topic: { Type: "AWS::SNS::Topic" }, clusterAQueue: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "q-${TopicArn}" } } } },
+      }),
+    );
+  });
+
+  const components = (): DriverComponent[] => [
+    { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template }] }] },
+    {
+      name: "cluster-a",
+      dependsOn: ["network"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "cluster-a", template, inputs: { TopicArn: { stackOutput: { stack: "network", name: "TopicArn" } } } }] }],
+    },
+  ];
+
+  async function planned(stacks: Record<string, FakeStackConfig>) {
+    const mock = createMockCloudExecutor({ stacks });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const all = components();
+    const plan = planFanOut({ components: all, changed: ["network"] });
+    const set = await planPrSet({ components: all, plan, registry, env: "local" });
+    return { mock, registry, all, plan, set };
+  }
+
+  const stacks = (): Record<string, FakeStackConfig> => ({
+    network: { outputs: { TopicArn: "arn:topic" }, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] },
+    "cluster-a": { changes: [queueAdd] },
+  });
+  const executed = (mock: ReturnType<typeof createMockCloudExecutor>) =>
+    mock.calls.filter((c) => c.method === "executeChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+
+  it("the real change set has the previewed shape: the first approval covers the round, nothing asks again, and both stacks are executed", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    expect(set.shapes?.["cluster-a"]).toMatchObject({ member: "cluster-a" });
+    let asked = 0;
+    const applied = await applyPrSet({
+      components: all,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(asked).toBe(0);
+    expect(applied.status).toBe("applied");
+    expect(executed(mock)).toEqual(["network", "cluster-a"]);
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, gate: "pr-apply-round-2", status: "applied", covered: { digest: set.doc.digest, filledInputs: ["network.TopicArn"] } });
+  });
+
+  it("a real change set with a resource the preview did not show is not executed: the member waits at pr-apply-round-2, naming the reason and the new digest", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    mock.setStack("cluster-a", { changes: [queueAdd, extraAdd] });
+    const seen: Array<{ gate: string; notCovered?: string; digest: string }> = [];
+    const applied = await applyPrSet({
+      components: all,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async ({ gate, notCovered, set: round }) => {
+        seen.push({ gate, ...(notCovered ? { notCovered } : {}), digest: round.doc.digest });
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(applied.status).toBe("waiting");
+    expect(executed(mock)).toEqual(["network"]);
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({ gate: "pr-apply-round-2", notCovered: "cluster-a now plans to create Extra, which the first plan did not" });
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, gate: "pr-apply-round-2", status: "waiting", digest: seen[0]!.digest, notCovered: seen[0]!.notCovered });
+    expect(applied.rounds?.[0]?.digest).not.toBe(set.doc.digest);
+    expect(applied.members.find((m) => m.member === "cluster-a")).toMatchObject({ status: "waiting", round: 2 });
+  });
+
+  it("a failure part way leaves what applied, applied, and the report says which member failed", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    const run = mock.executor.cloudformation.waitForStack;
+    mock.executor.cloudformation.waitForStack = async (name: string, ...rest: never[]) => {
+      if (name === "cluster-a") throw new Error("cluster-a: CREATE_FAILED");
+      return (run as (n: string) => ReturnType<typeof run>)(name, ...(rest as []));
+    };
+    const applied = await applyPrSet({ components: all, plan, registry, env: "local", set, approval: approvedFirst, decideRound: async () => ({ satisfied: false, approval: { status: "pending" } }) });
+    expect(applied.status).toBe("failed");
+    expect(applied.members.map((m) => [m.member, m.status])).toEqual([["cluster-a", "failed"], ["network", "applied"]]);
+  });
+});
+
+describe("the preview's digest and its cleanup (#4423)", () => {
+  const eni = { action: "Modify" as const, logicalResourceId: "Eni", resourceType: "AWS::EC2::NetworkInterface", replacement: false, replacementMode: "False" as const };
+  const driven = (property: string) => ({
+    ...eni,
+    details: [property],
+    drivers: [{ property, changeSource: "ParameterReference", causingEntity: "SubnetId" }],
+  });
+  const input = (): CfnDeployInput => ({ stack: "net", template, inputs: { SubnetId: undefined as never } });
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" } },
+        Resources: { Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" }, Description: "d" } } },
+      }),
+    );
+  });
+
+  const preview = async (config: FakeStackConfig, unresolved = ["vpc"]) => {
+    const mock = createMockCloudExecutor({ stacks: { net: config } });
+    const out = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: unresolved }, input());
+    return { mock, out };
+  };
+
+  it("the same inputs and template give the same digest across two plans; another preview shape gives another", async () => {
+    const a = await preview({ changes: [driven("SubnetId")] });
+    const b = await preview({ changes: [driven("SubnetId")] });
+    expect(a.out.artifact).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(b.out.planDigest).toBe(a.out.planDigest);
+    expect(b.out.changeSet!.member.planDigest).toBe(a.out.planDigest);
+    // The preview's digest is in it: a preview that shows another change set is another plan.
+    const other = await preview({ changes: [{ ...driven("SubnetId"), replacement: true, replacementMode: "True" as never }] });
+    expect(other.out.planDigest).not.toBe(a.out.planDigest);
+    // A member left a hole has the digest of its inputs alone.
+    const hole = await createCfnDeployCapability(createMockCloudExecutor({ stacks: { net: {} } }).executor).plan!({ ...ctx, unresolvedInputs: ["up"] }, { stack: "net", template });
+    expect(hole.planDigest).not.toBe(a.out.planDigest);
+  });
+
+  it("a preview that CloudFormation fails after creating the change set deletes the change set and the empty stack, and stays a hole", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { missing: true, changes: [driven("SubnetId")] } } });
+    const create = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async (args) => ({ ...(await create(args)), status: "FAILED", statusReason: "Parameter value for SubnetId is not valid", changes: [] });
+    const out = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input());
+    expect(out.artifact).toBeUndefined();
+    expect(out.changeSet!.member.holes[0]!.reason).toMatch(/no preview: CloudFormation could not create the change set with stand-in values: Parameter value for SubnetId is not valid/);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
+  });
+
+  it("a preview that throws while reading the change set still deletes the change set and the empty stack", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { missing: true, changes: [driven("SubnetId")] } } });
+    const create = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async (args) => {
+      const cs = await create(args);
+      return { ...cs, get changes(): never { throw new Error("could not read the change set"); } } as never;
+    };
+    await expect(createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input())).rejects.toThrow(/could not read the change set/);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
+  });
+});

package/src/components/cloud-executor.ts

@@ -54,6 +54,13 @@ export interface CfnChange {
   replacementMode?: "True" | "False" | "Conditional";
   /** Resource-specific detail, when the executor's changeset backend provides it (e.g. property/scope). */
   details?: string[];
+  /**
+   * What CloudFormation says drives each property change, when it says: the
+   * property, `ChangeSource` and `CausingEntity`. A property driven by a
+   * parameter reads `ParameterReference` with the parameter's name, which is
+   * how a preview marks it known after apply (#4419).
+   */
+  drivers?: Array<{ property: string; changeSource?: string; causingEntity?: string }>;
   /**
    * The logical ids of the nested stacks this change sits in, outermost
    * first (#3997). Absent for a change to the stack's own resources. Set when
@@ -74,8 +81,8 @@ export interface CfnChangeSet {
   statusReason?: string;
   /** True the first time this stack is created (no prior stack exists). */
   isCreate: boolean;
-  /** The change set's type: CREATE for a stack that does not exist yet or was never executed, else UPDATE. */
-  changeSetType?: "CREATE" | "UPDATE";
+  /** The change set's type: CREATE for a stack that does not exist yet or was never executed, else UPDATE; IMPORT for an adoption (#4536). */
+  changeSetType?: "CREATE" | "UPDATE" | "IMPORT";
   /**
    * True when no stack existed before this change set, so CloudFormation made
    * an empty `REVIEW_IN_PROGRESS` stack to hold it. A plan that deletes the
@@ -92,6 +99,18 @@ export interface CfnCreateChangeSetArgs {
   parameters?: Record<string, string>;
 }
 
+/** One existing resource an IMPORT change set brings under a stack (#4536). */
+export interface CfnResourceToImport {
+  resourceType: string;
+  logicalResourceId: string;
+  /** The type's primary identifier properties and their values (`{ BucketName: "logs" }`). */
+  resourceIdentifier: Record<string, string>;
+}
+
+export interface CfnCreateImportChangeSetArgs extends CfnCreateChangeSetArgs {
+  resourcesToImport: CfnResourceToImport[];
+}
+
 export interface CfnExecuteChangeSetArgs {
   stackName: string;
   changeSetName: string;
@@ -100,11 +119,21 @@ export interface CfnExecuteChangeSetArgs {
 export interface CfnStackStatus {
   stackStatus: string;
   outputs: Record<string, string>;
+  /** The stack's exports by export name (#4466c): the output each is and its value. Absent when it exports nothing or the backend does not say. */
+  exports?: Record<string, { output: string; value: string }>;
 }
 
 export interface CloudFormationClient {
   /** Create (but do not execute) a changeset, returning its proposed changes for preview/safety checks. */
   createChangeSet(args: CfnCreateChangeSetArgs): Promise<CfnChangeSet>;
+  /**
+   * Create (but do not execute) an IMPORT change set that brings existing
+   * resources under the stack (#4536, chant's CloudFormation adoption). A
+   * stack that does not exist yet is created by it. No stack tags are sent:
+   * chant's markers are written by the UPDATE that follows. Optional: a
+   * client without it cannot adopt.
+   */
+  createImportChangeSet?(args: CfnCreateImportChangeSetArgs): Promise<CfnChangeSet>;
   /** Execute a previously created changeset. */
   executeChangeSet(args: CfnExecuteChangeSetArgs): Promise<void>;
   /** Delete a changeset without executing it (used when a safety policy blocks the apply). */
@@ -122,6 +151,12 @@ export interface CloudFormationClient {
    * empty stack, and the next CREATE change set reuses it.
    */
   deleteStackShell?(stackName: string): Promise<boolean>;
+  /**
+   * The stacks that import `exportName` now (`ListImports`, #4466c), sorted;
+   * empty when none does. Optional: without it, a plan cannot say whether a
+   * change to an export is in use, and refuses nothing.
+   */
+  listImports?(exportName: string): Promise<string[]>;
 }
 
 // ── ECS ──────────────────────────────────────────────────────────────────��─
@@ -461,7 +496,7 @@ export interface DescribedCfnChangeSet {
       LogicalResourceId: string;
       ResourceType: string;
       Replacement?: string;
-      Details?: Array<{ Target?: { Name?: string } }>;
+      Details?: Array<{ Target?: { Name?: string }; ChangeSource?: string | null; CausingEntity?: string | null }>;
       /** Set on an `AWS::CloudFormation::Stack` change when the change set includes nested stacks: the nested change set's ARN. */
       ChangeSetId?: string | null;
     };
@@ -498,6 +533,15 @@ export async function readCfnChanges(
       replacement: rc.Replacement === "True",
       ...(rc.Replacement === "True" || rc.Replacement === "False" || rc.Replacement === "Conditional" ? { replacementMode: rc.Replacement } : {}),
       details: rc.Details?.map((d) => d.Target?.Name).filter((x): x is string => !!x),
+      ...(rc.Details?.some((d) => d.Target?.Name && (d.ChangeSource || d.CausingEntity))
+        ? {
+            drivers: rc.Details.filter((d) => d.Target?.Name).map((d) => ({
+              property: d.Target!.Name!,
+              ...(d.ChangeSource ? { changeSource: d.ChangeSource } : {}),
+              ...(d.CausingEntity ? { causingEntity: d.CausingEntity } : {}),
+            })),
+          }
+        : {}),
       ...(nestedStack.length > 0 ? { nestedStack } : {}),
     });
     if (rc.ResourceType === "AWS::CloudFormation::Stack" && rc.ChangeSetId) {
@@ -561,6 +605,53 @@ const realCloudFormation: CloudFormationClient = {
       changes: await readCfnChanges(described, describeNested),
     };
   },
+  async createImportChangeSet(args) {
+    const changeSetName = `cs-import-${Date.now()}`;
+    const params = Object.entries(args.parameters ?? {})
+      .map(([k, v]) => `ParameterKey=${k},ParameterValue=${v}`)
+      .join(" ");
+    const paramFlag = params ? ` --parameters ${params}` : "";
+    let body = "";
+    try {
+      body = readFileSync(args.templatePath, "utf8");
+    } catch { /* unreadable template — create-change-set reports it */ }
+    const capabilities = awsDeployCapabilitiesForBody(body).join(" ");
+    const { existed } = await cfnChangeSetType(args.stackName);
+    const dir = mkdtempSync(join(tmpdir(), "chant-cfn-import-"));
+    try {
+      const resourcesFile = join(dir, "resources-to-import.json");
+      writeFileSync(
+        resourcesFile,
+        JSON.stringify(
+          args.resourcesToImport.map((r) => ({ ResourceType: r.resourceType, LogicalResourceId: r.logicalResourceId, ResourceIdentifier: r.resourceIdentifier })),
+        ),
+      );
+      await run(
+        `aws cloudformation create-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)} ` +
+          `--change-set-type IMPORT --resources-to-import file://${resourcesFile} ` +
+          `--template-body file://${args.templatePath} --capabilities ${capabilities}${paramFlag}`,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    await run(
+      `aws cloudformation wait change-set-create-complete --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`,
+    ).catch(() => undefined);
+    const { stdout } = await run(
+      `aws cloudformation describe-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`,
+    );
+    const described = JSON.parse(stdout) as DescribedCfnChangeSet;
+    return {
+      changeSetName,
+      stackName: args.stackName,
+      status: described.Status,
+      statusReason: described.StatusReason ?? undefined,
+      isCreate: false,
+      changeSetType: "IMPORT",
+      stackCreated: !existed,
+      changes: await readCfnChanges(described, async () => ({ Status: "CREATE_COMPLETE" })),
+    };
+  },
   async executeChangeSet(args) {
     await run(
       `aws cloudformation execute-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(args.changeSetName)}`,
@@ -574,12 +665,34 @@ const realCloudFormation: CloudFormationClient = {
   async describeStack(stackName) {
     const { stdout } = await run(`aws cloudformation describe-stacks --stack-name ${q(stackName)}`);
     const described = JSON.parse(stdout) as {
-      Stacks: Array<{ StackStatus: string; Outputs?: Array<{ OutputKey: string; OutputValue: string }> }>;
+      Stacks: Array<{ StackStatus: string; Outputs?: Array<{ OutputKey: string; OutputValue: string; ExportName?: string }> }>;
     };
     const stack = described.Stacks[0];
     const outputs: Record<string, string> = {};
-    for (const o of stack?.Outputs ?? []) outputs[o.OutputKey] = o.OutputValue;
-    return { stackStatus: stack?.StackStatus ?? "UNKNOWN", outputs };
+    const exports: Record<string, { output: string; value: string }> = {};
+    for (const o of stack?.Outputs ?? []) {
+      outputs[o.OutputKey] = o.OutputValue;
+      if (o.ExportName) exports[o.ExportName] = { output: o.OutputKey, value: o.OutputValue };
+    }
+    return { stackStatus: stack?.StackStatus ?? "UNKNOWN", outputs, ...(Object.keys(exports).length > 0 ? { exports } : {}) };
+  },
+  async listImports(exportName) {
+    const stacks: string[] = [];
+    let token: string | undefined;
+    do {
+      let stdout: string;
+      try {
+        ({ stdout } = await run(`aws cloudformation list-imports --export-name ${q(exportName)}${token ? ` --next-token ${q(token)}` : ""}`));
+      } catch (err) {
+        // CloudFormation answers an export nobody imports with an error, not an empty list.
+        if (/is not imported by any stack/i.test(err instanceof Error ? err.message : String(err))) return [];
+        throw err;
+      }
+      const page = JSON.parse(stdout) as { Imports?: string[]; NextToken?: string };
+      stacks.push(...(page.Imports ?? []));
+      token = page.NextToken;
+    } while (token);
+    return [...new Set(stacks)].sort();
   },
   async waitForStack(stackName, opts) {
     const intervalMs = opts?.intervalMs ?? 10_000;