@intentius/chant-lexicon-aws 0.44.13 → 0.45.0

package/src/lifecycle-integration.test.ts

@@ -28,8 +28,11 @@ const { awsPlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
 const { normalizeObservation } = await import("@intentius/chant/observation");
+const { buildLiveGraphIr } = await import("@intentius/chant/graph-ir");
 const { liveEvidenceFromChangeSet, reconcileStatus } = await import("@intentius/chant/lifecycle/status");
 const { describeObservationConformance } = await import("@intentius/chant-test-utils");
+const { observeResources } = await import("@intentius/chant/lifecycle/observe");
+const { DECLARABLE_MARKER } = await import("@intentius/chant/declarable");
 
 const liveTemplate = {
   AWSTemplateFormatVersion: "2010-09-09",
@@ -143,6 +146,49 @@ describe("aws lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "MyBucket")!.action).toBe("noop");
   });
 
+  // #1279 — a node's attributes are the resource's own. The stack's outputs
+  // used to be copied onto every member, so a VPC carried `expWebIp` and no
+  // `CidrBlock`; they now ride the envelope once, keyed by the stack.
+  test("an observed VPC carries its own properties; the stack carries the exports (#1279)", async () => {
+    stubCfn((action) =>
+      action === "DescribeStackResources"
+        ? { text: stackResourcesXml([{ logicalId: "vpc", type: "AWS::EC2::VPC", physicalId: "vpc-a5a41663" }]) }
+        : { text: stackOutputsXml({ expVpcId: "vpc-a5a41663", expWebIp: "54.1.2.3", expDbPassword: "hunter2" }) },
+    );
+    spawnMock.mockResolvedValue(
+      ok(JSON.stringify({ Vpcs: [{ VpcId: "vpc-a5a41663", CidrBlock: "10.0.0.0/16", IsDefault: false }] })),
+    );
+
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["vpc"],
+        entities: new Map(),
+      }),
+    );
+
+    const attrs = observed.resources.vpc?.attributes ?? {};
+    expect(attrs.CidrBlock).toBe("10.0.0.0/16");
+    expect(attrs.IsDefault).toBe(false);
+    expect(Object.keys(attrs).filter((k) => k.startsWith("exp"))).toEqual([]);
+
+    expect(observed.stackExports).toEqual({
+      prod: { expVpcId: "vpc-a5a41663", expWebIp: "54.1.2.3", expDbPassword: "[REDACTED]" },
+    });
+
+    // And through the graph: the exports land on the IR's `exports`, not on the node.
+    const ir = buildLiveGraphIr([{ lexicon: "aws", resources: observed.resources, stackExports: observed.stackExports }]);
+    const node = ir.nodes.find((n) => n.id === "vpc")!;
+    expect(node.attrs.CidrBlock).toBe("10.0.0.0/16");
+    expect(node.attrs.expVpcId).toBeUndefined();
+    expect(ir.exports).toEqual([
+      { name: "expDbPassword", value: "[REDACTED]", stack: "prod" },
+      { name: "expVpcId", value: "vpc-a5a41663", stack: "prod" },
+      { name: "expWebIp", value: "54.1.2.3", stack: "prod" },
+    ]);
+  });
+
   // #1647 — the carve state, end to end: terraform applied the bucket, carve
   // emitted a carveout declaring it by BucketName, and no CFN stack has ever
   // heard of it. The stack read alone said confirmed-absent (missing → a plan
@@ -303,6 +349,49 @@ describe("aws lifecycle integration (#163)", () => {
     });
     expect(cs.entries[0].action).toBe("create");
   });
+
+  // #1265 — the ownership notice printed once per `describeResources` call, so
+  // a four-stack project got four identical copies ahead of every answer. It
+  // is a property of the read path, not of a stack: the plugin now returns it
+  // as a note on the observation and core says it once per run.
+  test("owned read on a four-stack project: one ownership note, nothing printed", async () => {
+    stubCfn((action) =>
+      action === "DescribeStackResources"
+        ? { text: stackResourcesXml([{ logicalId: "MyBucket", type: "AWS::S3::Bucket", physicalId: "my-bucket" }]) }
+        : { text: stackOutputsXml() },
+    );
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const entities = new Map([
+      ["MyBucket", { [DECLARABLE_MARKER]: true as const, lexicon: "aws", entityType: "AWS::S3::Bucket", props: {} }],
+    ]);
+    const result = await observeResources(
+      "prod",
+      [awsPlugin],
+      { errors: [], warnings: [], entities, outputs: new Map([["aws", ""]]) } as never,
+      { owned: true, stacks: ["prod-net", "prod-data", "prod-app", "prod-edge"] },
+    );
+    const ownership = result.notes.filter((n) => n.includes("ownership filter unavailable"));
+    expect(ownership).toHaveLength(1);
+    expect(ownership[0]).toBe(
+      "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export",
+    );
+    expect(result.warnings.join("\n")).not.toContain("ownership filter unavailable");
+    expect(warn).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  test("an unowned read carries no ownership note", async () => {
+    stubCfn((action) =>
+      action === "DescribeStackResources"
+        ? { text: stackResourcesXml([{ logicalId: "MyBucket", type: "AWS::S3::Bucket", physicalId: "my-bucket" }]) }
+        : { text: stackOutputsXml() },
+    );
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({ environment: "prod", buildOutput: "", entityNames: ["MyBucket"], entities: new Map() }),
+    );
+    expect(observed.notes).toEqual([]);
+  });
 });
 
 // The shared conformance suite (#1089).

package/src/op/activities/aws-apply.test.ts

@@ -25,8 +25,16 @@ const describe_ = (status: string) => `<DescribeStacksResponse><Stacks><member><
 
 describe("CFN pure helpers (#awsApply)", () => {
   test("cfnUrl: endpoint override vs real regional host", () => {
-    expect(cfnUrl("http://localhost:4566")).toBe("http://localhost:4566/");
-    expect(cfnUrl(undefined, "eu-west-1")).toBe("https://cloudformation.eu-west-1.amazonaws.com/");
+    expect(cfnUrl("http://localhost:4566", undefined, {})).toBe("http://localhost:4566/");
+    expect(cfnUrl(undefined, "eu-west-1", {})).toBe("https://cloudformation.eu-west-1.amazonaws.com/");
+  });
+
+  test("cfnUrl: AWS_ENDPOINT_URL[_CLOUDFORMATION] is an override too, the same rule as the read client (#1694)", () => {
+    expect(cfnUrl(undefined, "eu-west-1", { AWS_ENDPOINT_URL: "http://localhost:4566" })).toBe("http://localhost:4566/");
+    expect(
+      cfnUrl(undefined, "eu-west-1", { AWS_ENDPOINT_URL: "http://all:1", AWS_ENDPOINT_URL_CLOUDFORMATION: "http://cfn:2" }),
+    ).toBe("http://cfn:2/");
+    expect(cfnUrl("http://opt:3", "eu-west-1", { AWS_ENDPOINT_URL: "http://all:1" })).toBe("http://opt:3/");
   });
 
   test("cfnForm stamps Action + Version", () => {
@@ -55,9 +63,9 @@ describe("CFN pure helpers (#awsApply)", () => {
   });
 });
 
-function tmpl(): string {
+function tmpl(extra: Record<string, unknown> = {}): string {
   const p = `/tmp/chant-cfn-${process.pid}-${Math.round(performance.now())}.json`;
-  writeFileSync(p, JSON.stringify({ Resources: { B: { Type: "AWS::S3::Bucket" } } }));
+  writeFileSync(p, JSON.stringify({ ...extra, Resources: { B: { Type: "AWS::S3::Bucket" } } }));
   return p;
 }
 
@@ -77,6 +85,34 @@ describe("awsApply flow (#awsApply)", () => {
     expect(calls).toEqual(["DescribeStacks", "CreateStack", "DescribeStacks"]);
   });
 
+  test("capabilities follow the template: NAMED_IAM alone, plus AUTO_EXPAND for a Transform (#980)", async () => {
+    const sent: Record<string, string>[] = [];
+    let described = 0;
+    const http: AwsHttp = async (_url, form) => {
+      if (form.Action === "DescribeStacks") return described++ % 2 === 0 ? { status: 400, text: MISSING } : { status: 200, text: describe_("CREATE_COMPLETE") };
+      sent.push(form);
+      return { status: 200, text: CREATE_OK };
+    };
+    const plain = tmpl();
+    await awsApply({ templatePath: plain, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(plain);
+    expect(sent[0]["Capabilities.member.1"]).toBe("CAPABILITY_NAMED_IAM");
+    expect(sent[0]["Capabilities.member.2"]).toBeUndefined();
+
+    const macro = tmpl({ Transform: "AWS::SecretsManager-2020-07-23" });
+    await awsApply({ templatePath: macro, stackName: "s", endpoint: "http://x", intervalMs: 1 }, undefined, http);
+    unlinkSync(macro);
+    expect(sent[1]["Capabilities.member.1"]).toBe("CAPABILITY_NAMED_IAM");
+    expect(sent[1]["Capabilities.member.2"]).toBe("CAPABILITY_AUTO_EXPAND");
+
+    // An explicit list still wins.
+    const explicit = tmpl({ Transform: "AWS::Serverless-2016-10-31" });
+    await awsApply({ templatePath: explicit, stackName: "s", endpoint: "http://x", intervalMs: 1, capabilities: ["CAPABILITY_IAM"] }, undefined, http);
+    unlinkSync(explicit);
+    expect(sent[2]["Capabilities.member.1"]).toBe("CAPABILITY_IAM");
+    expect(sent[2]["Capabilities.member.2"]).toBeUndefined();
+  });
+
   test("update path: existing stack → UpdateStack → UPDATE_COMPLETE", async () => {
     let described = 0;
     const http: AwsHttp = async (_url, form) => {

package/src/op/activities/aws-apply.ts

@@ -1,20 +1,28 @@
 import { readFileSync } from "node:fs";
 import { safeHeartbeat, sleep } from "@intentius/chant/op";
+import { awsDeployCapabilitiesForBody } from "../../components/cloud-executor.js";
+import { resolveEndpointOverride } from "../../api/read-client.js";
 
 const DEFAULT_REGION = "us-east-1";
 const CFN_API_VERSION = "2010-05-15";
-const DEFAULT_CAPABILITIES = ["CAPABILITY_NAMED_IAM"];
 
 export interface AwsApplyArgs {
   /** Path to a built CloudFormation template (JSON/YAML). */
   templatePath: string;
   /** CloudFormation stack name — the deploy boundary. */
   stackName: string;
-  /** CFN endpoint override (e.g. Floci `http://localhost:4566`). Default: real CloudFormation. */
+  /**
+   * CFN endpoint override (e.g. Floci `http://localhost:4566`). Omitted,
+   * `AWS_ENDPOINT_URL_CLOUDFORMATION` then `AWS_ENDPOINT_URL` answer — the same
+   * rule the read client applies (#1694). With neither: real CloudFormation.
+   */
   endpoint?: string;
   /** Region (real CFN host + `Version` context). Default: `us-east-1`. */
   region?: string;
-  /** Capabilities to acknowledge. Default: `["CAPABILITY_NAMED_IAM"]`. */
+  /**
+   * Capabilities to acknowledge. Default: `CAPABILITY_NAMED_IAM`, plus
+   * `CAPABILITY_AUTO_EXPAND` when the template has a top-level `Transform` (#980).
+   */
   capabilities?: string[];
   /** Stack-settle timeout in ms. Default: `300000`. */
   timeoutMs?: number;
@@ -37,9 +45,17 @@ const defaultHttp: AwsHttp = async (url, form, signal) => {
 
 // ── Pure helpers (CFN Query protocol) ─────────────────────────────────────────
 
-/** The CloudFormation endpoint URL — the override, or the real regional host. */
-export function cfnUrl(endpoint?: string, region = DEFAULT_REGION): string {
-  return `${(endpoint ?? `https://cloudformation.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
+/**
+ * The CloudFormation endpoint URL — the override, or the real regional host.
+ * `env` is what the ambient-variable fallback reads; injectable for tests.
+ */
+export function cfnUrl(
+  endpoint?: string,
+  region = DEFAULT_REGION,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const override = resolveEndpointOverride("cloudformation", endpoint, env);
+  return `${(override ?? `https://cloudformation.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
 }
 
 /** A CFN Query-protocol form body: `Action` + `Version` + params. */
@@ -122,8 +138,8 @@ export async function awsApply(
   http: AwsHttp = defaultHttp,
 ): Promise<{ stackName: string; status: string; action: "created" | "updated" | "unchanged" }> {
   const url = cfnUrl(args.endpoint, args.region);
-  const capabilities = args.capabilities ?? DEFAULT_CAPABILITIES;
   const templateBody = readFileSync(args.templatePath, "utf8");
+  const capabilities = args.capabilities ?? awsDeployCapabilitiesForBody(templateBody);
   const timeoutMs = args.timeoutMs ?? 300_000;
   const intervalMs = args.intervalMs ?? 3_000;
 

package/src/plugin.ts

@@ -47,8 +47,14 @@ export { stackDoesNotExist } from "./stack-errors";
  * Provides serializer, lint rules, template detection,
  * import parsing, and code generation for AWS CloudFormation.
  */
-/** #1265 — the ownership notice is about the environment, so it is said once. */
-let warnedOwnership = false;
+/**
+ * describe-stack-resources returns no tags, so the ownership filter cannot be
+ * applied on this read path. Returned as a run-level note rather than printed
+ * (#1265): core says it once per run, after the answer, however many stacks
+ * were read. The text is the contract consumers grep for.
+ */
+const OWNERSHIP_UNAVAILABLE_NOTE =
+  "ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export";
 
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
@@ -558,25 +564,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     // The applier's own transport, pointed at the read APIs (#1206). Multi-region
     // estates target this stack's region, not the ambient one.
     const client: AwsReadClientOptions = {
-      ...(process.env.AWS_ENDPOINT_URL ? { endpoint: process.env.AWS_ENDPOINT_URL } : {}),
       ...(options.region ? { region: options.region } : {}),
     };
 
-    if (options.owned) {
-      // describe-stack-resources does not return tags, so ownership cannot be
-      // determined here. Degrade to detect-only rather than silently filtering.
-      //
-      // Once per process, not once per stack (#1265). It is a property of the
-      // environment, not of each stack, and a four-stack project printed four
-      // identical copies ahead of every answer — enough that an agent piping
-      // `graph --format ir` with `2>&1` had to skip lines to find the JSON.
-      warnedOwnership ||
-        // eslint-disable-next-line no-console
-        console.warn(
-        "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export",
-        );
-      warnedOwnership = true;
-    }
+    // describe-stack-resources does not return tags, so ownership cannot be
+    // determined here. Degrade to detect-only rather than silently filtering,
+    // and say so as a note on the observation. It is a property of the
+    // environment, not of each stack: a four-stack project once printed four
+    // identical copies ahead of every answer (#1265) — enough that an agent
+    // piping `graph --format ir` with `2>&1` had to skip lines to find the
+    // JSON. Core dedupes the note across stacks and prints it with the footer.
+    const notes = options.owned ? [OWNERSHIP_UNAVAILABLE_NOTE] : undefined;
 
     // Derive stack name. A multi-stack project passes the explicit CloudFormation
     // stack this observation targets (see `stacks` in ChantConfig); otherwise the
@@ -600,7 +598,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       if (err instanceof AwsReadError && stackDoesNotExist(err.message)) {
         const { observeByIdentity } = await import("./identity-observe");
         const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
-        return observation({ ...resources, ...identity.resources }, undefined, identity.queried);
+        return observation({ ...resources, ...identity.resources }, undefined, identity.queried, notes);
       }
       // Any other failure (credentials, throttling, a region that can't be
       // reached) establishes nothing about what is deployed. Reporting every
@@ -617,6 +615,8 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           reason,
           `DescribeStackResources failed for stack "${stackName}": ${detail}`,
         ),
+        undefined,
+        notes,
       );
     }
 
@@ -633,20 +633,20 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       stackOutputs = {};
     }
 
+    // The outputs are the stack's, not any member's (#1279). They used to be
+    // copied onto every resource's `attributes`, so a VPC carried the stack's
+    // `expWebIp` and no `CidrBlock`. They ride the envelope once, keyed by the
+    // stack, scrubbed of anything that looks secret.
+    const exports: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(stackOutputs)) {
+      exports[key] = /password|secret|token|key/i.test(key) ? "[REDACTED]" : value;
+    }
+    const stackExports = Object.keys(exports).length > 0 ? { [stackName]: exports } : undefined;
+
     for (const entityName of options.entityNames) {
       const stackResource = stackResourceMap.get(entityName);
       if (!stackResource) continue;
 
-      const attributes: Record<string, unknown> = {};
-      // Include stack outputs as attributes (scrub sensitive ones)
-      for (const [key, value] of Object.entries(stackOutputs)) {
-        if (/password|secret|token|key/i.test(key)) {
-          attributes[key] = "[REDACTED]";
-        } else {
-          attributes[key] = value;
-        }
-      }
-
       resources[entityName] = {
         type: stackResource.type,
         physicalId: stackResource.physicalId ?? "",
@@ -657,7 +657,6 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
         // rather than leaving the field off and letting each consumer guess —
         // the change set never escalates `unknown` to a delete.
         ownership: "unknown",
-        attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
       };
     }
 
@@ -669,9 +668,9 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     const { observeByIdentity } = await import("./identity-observe");
     const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
 
-    // Each resource's OWN properties, on top of the stack outputs above (#1279).
-    // Until this, a node's `attrs` were the stack's exports replicated onto
-    // every member, so no instance carried its own `VpcId`.
+    // Each resource's OWN properties (#1279). Until this, a node's `attrs` were
+    // the stack's exports replicated onto every member, so no instance carried
+    // its own `VpcId`.
     const own = await describeOwnProperties(resources, options.region);
     const withProperties = stampProviderDefaults(stampRegion(own.resources, options.region));
 
@@ -701,13 +700,13 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           detail: `the stack was read, but this resource's own properties were not — ${own.failures.get(type) ?? "the describe call failed"}`,
         };
       }
-      return observation({ ...described, ...identity.resources }, holes, identity.queried);
+      return observation({ ...described, ...identity.resources }, holes, identity.queried, notes, stackExports);
     }
 
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an
     // absence, not a hole — unless the identity fallback saw it live (#1647).
-    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried);
+    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried, notes, stackExports);
   },
 
   /**

package/src/properties.test.ts

@@ -40,18 +40,18 @@ describe("describeOwnProperties (#1279)", () => {
     expect(spawnMock).toHaveBeenCalledTimes(1);
   });
 
-  it("keeps stack outputs, and lets the resource's own property win the name", async () => {
-    const withOutputs = {
+  it("keeps what the entry already carried, and lets the resource's own property win the name", async () => {
+    const withPrior = {
       web: {
         type: "AWS::EC2::Instance",
         status: "OK",
         physicalId: "i-1",
-        attributes: { expVpcId: "vpc-exported", VpcId: "stale" },
+        attributes: { region: "us-east-1", VpcId: "stale" },
       },
     };
     spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"))));
-    const { resources: merged } = await describeOwnProperties(withOutputs);
-    expect(merged.web.attributes?.expVpcId).toBe("vpc-exported");
+    const { resources: merged } = await describeOwnProperties(withPrior);
+    expect(merged.web.attributes?.region).toBe("us-east-1");
     expect(merged.web.attributes?.VpcId).toBe("vpc-a");
   });
 

package/src/properties.ts

@@ -16,9 +16,10 @@
  * A deep read (Cloud Control) answers this properly but is a per-resource call
  * and is not available on every endpoint. This is the cheap middle: one describe
  * per kind for the whole observation, joined back by physical id. Stack outputs
- * are kept — they were the only attributes for a long time and queries lean on
- * them — but a resource's own properties win a name collision, because they are
- * the resource's.
+ * no longer ride the resource at all — they are the stack's, and travel on the
+ * observation envelope's `stackExports`. Whatever a resource already carries is
+ * kept underneath its own properties, which win a name collision because they
+ * are the resource's.
  */
 
 import { applyAwsEndpointArgv } from "./components/cloud-executor";
@@ -177,8 +178,8 @@ export async function describeOwnProperties(
         for (const name of byId.get(id) ?? []) {
           merged[name] = {
             ...merged[name],
-            // Own properties last: a resource's `VpcId` outranks a stack output
-            // that happens to share the name.
+            // Own properties last: a resource's `VpcId` outranks anything the
+            // entry already carried under the same name.
             attributes: { ...(merged[name].attributes ?? {}), ...row },
           };
         }