@intentius/chant-lexicon-aws 0.18.26 → 0.18.27

package/src/lifecycle-integration.test.ts

@@ -102,4 +102,38 @@ describe("aws lifecycle integration (#163)", () => {
     });
     expect(cs2.entries.find((e) => e.name === "MyBucket")!.action).toBe("noop");
   });
+
+  describe("describeStackStatus (#57 — per-component stack presence)", () => {
+    const err = (stderr: string) => ({ stdout: "", stderr, exitCode: 255 });
+
+    test("present + healthy for a terminal-success stack", async () => {
+      spawnMock.mockResolvedValue(ok(JSON.stringify({ Stacks: [{ StackStatus: "CREATE_COMPLETE" }] })));
+      const obs = await awsPlugin.describeStackStatus!({ environment: "local", stack: "loom-local-a-loom-db" });
+      expect(obs).toEqual({ stack: "loom-local-a-loom-db", present: true, status: "CREATE_COMPLETE", healthy: true });
+    });
+
+    test("present but not healthy for a rollback/failed state", async () => {
+      spawnMock.mockResolvedValue(ok(JSON.stringify({ Stacks: [{ StackStatus: "ROLLBACK_COMPLETE" }] })));
+      const obs = await awsPlugin.describeStackStatus!({ environment: "local", stack: "s" });
+      expect(obs).toMatchObject({ present: true, status: "ROLLBACK_COMPLETE", healthy: false });
+    });
+
+    test("in-progress is present but not yet healthy", async () => {
+      spawnMock.mockResolvedValue(ok(JSON.stringify({ Stacks: [{ StackStatus: "UPDATE_IN_PROGRESS" }] })));
+      const obs = await awsPlugin.describeStackStatus!({ environment: "local", stack: "s" });
+      expect(obs).toMatchObject({ present: true, healthy: false });
+    });
+
+    test("absent (does-not-exist) reports present: false, not an error", async () => {
+      spawnMock.mockResolvedValue(err("ValidationError: Stack with id s does not exist"));
+      const obs = await awsPlugin.describeStackStatus!({ environment: "local", stack: "s" });
+      expect(obs).toEqual({ stack: "s", present: false });
+    });
+
+    test("any other CLI failure is indeterminate → null (never a false 'gone')", async () => {
+      spawnMock.mockResolvedValue(err("Unable to locate credentials"));
+      const obs = await awsPlugin.describeStackStatus!({ environment: "local", stack: "s" });
+      expect(obs).toBeNull();
+    });
+  });
 });

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -577,6 +577,34 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     return resources;
   },
 
+  async describeStackStatus(options: { environment: string; stack: string }): Promise<StackStatusObservation | null> {
+    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const rt = getRuntime();
+
+    const result = await rt.spawn(applyAwsEndpointArgv([
+      "aws", "cloudformation", "describe-stacks",
+      "--stack-name", options.stack,
+      "--output", "json",
+    ], process.env.AWS_ENDPOINT_URL));
+
+    if (result.exitCode !== 0) {
+      // A stack that doesn't exist yet is the pre-first-apply state (absent, not
+      // an error). Any other failure is indeterminate → null, so the caller
+      // degrades rather than reporting a healthy stack as gone.
+      if (stackDoesNotExist(result.stderr)) return { stack: options.stack, present: false };
+      return null;
+    }
+
+    const parsed = JSON.parse(result.stdout) as { Stacks?: Array<{ StackStatus?: string }> };
+    const status = parsed.Stacks?.[0]?.StackStatus;
+    if (!status) return { stack: options.stack, present: false };
+    // Healthy = a terminal *success* apply. Rollback/failed/in-progress/delete
+    // states are present-but-not-healthy, so a renderer can distinguish
+    // deployed-green from mid-deploy or broken.
+    const healthy = /^(CREATE|UPDATE|IMPORT)_COMPLETE$/.test(status);
+    return { stack: options.stack, present: true, status, healthy };
+  },
+
   async exportResources(options: {
     environment: string;
     stack?: string;