@intentius/chant-lexicon-aws 0.45.0 → 0.49.0

package/src/teardown.ts

@@ -0,0 +1,276 @@
+/**
+ * Env teardown for the aws lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair, at STACK granularity.
+ *
+ * Per-resource selection is impossible here by construction: the thin read
+ * (`describeResources`) is sourced from `describe-stack-resources`, which
+ * returns no tags, so no resource-level marker can be read on the teardown
+ * path. The stack is aws's ownership boundary anyway — the applier deploys
+ * whole stacks and deletes ride CloudFormation — so teardown enumerates the
+ * environment's stacks and verifies the marker on each STACK's own tags
+ * (`DescribeStacks` → `Tags`), stamped there by the apply paths from the
+ * template's `Metadata["chant:ownership"]` block.
+ *
+ * Which stacks are the environment's: the project's declared `stacks[]` when
+ * it is a multi-stack project, else the single-stack convention — the explicit
+ * `stack` option, else the stack named after the environment (the same rule
+ * `describeResources` and `exportResources` apply, see chant #932).
+ *
+ * Verification is tag-reading, never name-trusting. A resolved stack whose
+ * tags carry exactly the requested identity (managed-by + stack + env) is a
+ * candidate of type `AWS::CloudFormation::Stack`. A stack carrying a DIFFERENT
+ * marker identity verifiably belongs to another project or env — out of scope,
+ * silently, the way another env's resources are. A stack carrying NO marker at
+ * all is unknowable — a legacy chant stack from before stack tagging, or a
+ * foreign stack that happens to hold the env's name — and is reported as a
+ * hole (`filtered` / unverified-ownership), never deleted. An absent stack is
+ * knowledge, not a hole: nothing to tear down.
+ *
+ * Execution re-reads each candidate stack's tags immediately before deleting
+ * (the enumeration is a moment old at best, and a delete is not undoable),
+ * then rides the existing Query-API delete — `awsDelete`, DeleteStack polled
+ * to DELETE_COMPLETE. An identity that no longer matches is `not-prunable:
+ * unverified-ownership`; an already-absent stack is `deleted` (teardown is
+ * idempotent).
+ */
+
+import type {
+  TeardownCandidate,
+  TeardownEnumeration,
+  TeardownExecution,
+  TeardownHole,
+  TeardownOutcome,
+} from "@intentius/chant/lexicon";
+import { readOwnership, type OwnershipMarker } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import {
+  cfnQuery,
+  xmlLeaves,
+  xmlMembers,
+  AwsReadError,
+  type AwsReadClientOptions,
+} from "./api/read-client";
+import { awsDelete, type AwsHttp } from "./op/activities/aws-apply";
+
+/** The one candidate type this lexicon's teardown produces: whole stacks. */
+export const STACK_TYPE = "AWS::CloudFormation::Stack";
+
+export interface AwsTeardownOptions {
+  environment: string;
+  /** The identity to select on: this project's ownership stack + the env being torn down. */
+  marker: OwnershipMarker;
+  /** Explicit deployed stack name (single-stack override). */
+  stack?: string;
+  /** Region that stack is deployed in. */
+  region?: string;
+  /** A multi-stack project's declared stacks (chant.config `stacks[]`). */
+  stacks?: Array<{ name: string; region?: string }>;
+}
+
+/** Injectable transports/timeouts, so tests double the Query API (no network). */
+export interface AwsTeardownDeps {
+  /** Options for the read client's `DescribeStacks` calls (http injection, endpoint). */
+  read?: AwsReadClientOptions;
+  /** The applier transport `awsDelete` polls DeleteStack through. */
+  applyHttp?: AwsHttp;
+  /** DeleteStack settle timeout in ms (default `awsDelete`'s 300000). */
+  timeoutMs?: number;
+  /** DeleteStack poll interval in ms (default `awsDelete`'s 3000). */
+  intervalMs?: number;
+}
+
+/** The stacks an env teardown resolves to: `stacks[]`, else the single-stack convention. */
+export function resolveTeardownStacks(
+  options: AwsTeardownOptions,
+): Array<{ name: string; region?: string }> {
+  if (options.stacks && options.stacks.length > 0) return options.stacks;
+  return [
+    {
+      name: options.stack ?? options.environment,
+      ...(options.region ? { region: options.region } : {}),
+    },
+  ];
+}
+
+/** One live stack, as DescribeStacks answers for it. */
+interface LiveStack {
+  stackId?: string;
+  status?: string;
+  /** The stack's own tags, as a flat map. */
+  tags: Record<string, string>;
+}
+
+/** A DescribeStacks miss — CloudFormation's "does not exist" ValidationError. */
+function isStackMissingError(err: unknown): boolean {
+  return err instanceof AwsReadError && /does not exist/i.test(err.message);
+}
+
+/** `DescribeStacks` for one stack; `undefined` when the stack does not exist. */
+async function describeStack(
+  name: string,
+  region: string | undefined,
+  read: AwsReadClientOptions,
+): Promise<LiveStack | undefined> {
+  let xml: string;
+  try {
+    xml = await cfnQuery("DescribeStacks", { StackName: name }, {
+      ...read,
+      ...(region ? { region } : {}),
+    });
+  } catch (err) {
+    if (isStackMissingError(err)) return undefined;
+    throw err;
+  }
+  // One StackName queried → one stack member; `xmlLeaves` keeps the first
+  // occurrence of each scalar, which is that stack's StackId/StackStatus.
+  const leaves = xmlLeaves(xml);
+  const tags: Record<string, string> = {};
+  for (const m of xmlMembers(xml, "Tags")) {
+    if (m.Key) tags[m.Key] = m.Value ?? "";
+  }
+  return {
+    ...(leaves.StackId ? { stackId: leaves.StackId } : {}),
+    ...(leaves.StackStatus ? { status: leaves.StackStatus } : {}),
+    tags,
+  };
+}
+
+/** True when a live stack's own tags carry exactly the requested identity. */
+function matchesMarker(tags: Record<string, string>, marker: OwnershipMarker): boolean {
+  const read = readOwnership(tags, AWS_TAG_OWNERSHIP_KEYS);
+  return read !== undefined && read.stack === marker.stack && read.env === marker.env;
+}
+
+/**
+ * Enumerate the environment's marker-verified stacks — the aws half of
+ * `chant lifecycle teardown <env>` planning. Read-only.
+ */
+export async function teardownOwned(
+  options: AwsTeardownOptions,
+  deps: AwsTeardownDeps = {},
+): Promise<TeardownEnumeration> {
+  const read = deps.read ?? {};
+  const candidates: TeardownCandidate[] = [];
+  const holes: TeardownHole[] = [];
+
+  for (const ref of resolveTeardownStacks(options)) {
+    let live: LiveStack | undefined;
+    try {
+      live = await describeStack(ref.name, ref.region, read);
+    } catch (err) {
+      holes.push({
+        name: ref.name,
+        type: STACK_TYPE,
+        reason: "read-failed",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    // Absent is knowledge: the env-resolved stack does not exist, so there is
+    // nothing to tear down and nothing unknown about it.
+    if (live === undefined) continue;
+
+    const identity = readOwnership(live.tags, AWS_TAG_OWNERSHIP_KEYS);
+    if (identity !== undefined && identity.stack === options.marker.stack && identity.env === options.marker.env) {
+      candidates.push({
+        name: ref.name,
+        type: STACK_TYPE,
+        ...(live.stackId ? { physicalId: live.stackId } : {}),
+        marker: identity,
+      });
+      continue;
+    }
+    if (identity !== undefined) {
+      // A marker for a DIFFERENT identity is verifiably someone else's
+      // (another project's stack, another env's deployment of a shared stack
+      // name) — out of scope, the way any foreign-env resource is.
+      continue;
+    }
+    // No marker at all: a legacy chant stack deployed before stack tagging, or
+    // a foreign stack under the env's name — unknowable either way. Loud, and
+    // never deleted (#1089): unverified ownership reads as "do not touch",
+    // not as "clean".
+    holes.push({
+      name: ref.name,
+      type: STACK_TYPE,
+      reason: "filtered",
+      detail:
+        `unverified-ownership: the stack exists but its tags carry no chant ownership marker ` +
+        `(expected ${AWS_TAG_OWNERSHIP_KEYS.managedBy} + ${AWS_TAG_OWNERSHIP_KEYS.stack}=${options.marker.stack}` +
+        `${options.marker.env ? ` + ${AWS_TAG_OWNERSHIP_KEYS.env}=${options.marker.env}` : ""}) — ` +
+        `a chant stack deployed before stack tagging, or a foreign stack; re-deploy to stamp it, it will not be deleted`,
+    });
+  }
+
+  return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+
+/**
+ * Delete the handed-over stacks: re-verify each stack's own tags, then
+ * DeleteStack via `awsDelete`, polled to DELETE_COMPLETE. One outcome per
+ * candidate, always.
+ */
+export async function executeTeardown(
+  options: AwsTeardownOptions & { candidates: TeardownCandidate[] },
+  deps: AwsTeardownDeps = {},
+): Promise<TeardownExecution> {
+  const read = deps.read ?? {};
+  const regionByStack = new Map<string, string | undefined>(
+    resolveTeardownStacks(options).map((s) => [s.name, s.region]),
+  );
+
+  const outcomes: TeardownOutcome[] = [];
+  for (const candidate of options.candidates) {
+    outcomes.push(await deleteStackCandidate(candidate, regionByStack.get(candidate.name), options.marker, read, deps));
+  }
+  return { outcomes };
+}
+
+async function deleteStackCandidate(
+  candidate: TeardownCandidate,
+  region: string | undefined,
+  marker: OwnershipMarker,
+  read: AwsReadClientOptions,
+  deps: AwsTeardownDeps,
+): Promise<TeardownOutcome> {
+  const base = {
+    name: candidate.name,
+    type: STACK_TYPE,
+    ...(candidate.physicalId ? { physicalId: candidate.physicalId } : {}),
+  };
+
+  // Re-read and re-verify the stack's own tags right before deleting: the
+  // enumeration is a moment old at best, and a DeleteStack is not undoable.
+  let live: LiveStack | undefined;
+  try {
+    live = await describeStack(candidate.name, region, read);
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (live === undefined || live.status === "DELETE_COMPLETE") {
+    return { ...base, outcome: "deleted", detail: "already absent" };
+  }
+  if (!matchesMarker(live.tags, marker)) {
+    return {
+      ...base,
+      outcome: "not-prunable",
+      detail: "unverified-ownership: the live stack's tags no longer carry the requested marker identity",
+    };
+  }
+
+  try {
+    await awsDelete(
+      {
+        stackName: candidate.name,
+        ...(region ? { region } : {}),
+        ...(deps.timeoutMs !== undefined ? { timeoutMs: deps.timeoutMs } : {}),
+        ...(deps.intervalMs !== undefined ? { intervalMs: deps.intervalMs } : {}),
+      },
+      undefined,
+      deps.applyHttp,
+    );
+  } catch (err) {
+    return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
+  }
+  return { ...base, outcome: "deleted" };
+}