@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/stack-errors.js

@@ -0,0 +1,14 @@
+/**
+ * CloudFormation CLI error classification, shared by every live read path.
+ *
+ * Lives in its own module (rather than in ./plugin.ts, where it started) so the
+ * deep reader (#1015) can classify the same failure the same way without
+ * importing the plugin that imports it. ./plugin.ts re-exports it, so the
+ * original import path is unchanged.
+ */
+/** True when a CloudFormation CLI error means the stack simply isn't there yet
+ * (`ValidationError … does not exist`) — the pre-first-apply state, which live
+ * queries should treat as "nothing deployed", not a failure. */
+export function stackDoesNotExist(stderr) {
+    return /does not exist/i.test(stderr);
+}

package/dist/taggable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taggable.d.ts","sourceRoot":"","sources":["../src/taggable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,CAAC,CAqBnD"}
+{"version":3,"file":"taggable.d.ts","sourceRoot":"","sources":["../src/taggable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,CAAC,CAoBnD"}

package/dist/taggable.js

@@ -0,0 +1,33 @@
+/**
+ * Shared taggable resource lookup — loads from the generated lexicon JSON.
+ *
+ * Lazy-loaded and cached for the lifetime of the process.
+ */
+import { readFileSync } from "fs";
+import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+let _cached;
+/**
+ * Load taggable resource types from the lexicon JSON.
+ * Result is cached after first call.
+ */
+export function loadTaggableResources() {
+    if (_cached)
+        return _cached;
+    const set = new Set();
+    try {
+        const lexiconPath = join(moduleSourceDir(import.meta.url), "generated", "lexicon-aws.json");
+        const content = readFileSync(lexiconPath, "utf-8");
+        const data = JSON.parse(content);
+        for (const [_name, entry] of Object.entries(data)) {
+            if (entry.kind === "resource" && entry.resourceType && entry.tagging?.taggable) {
+                set.add(entry.resourceType);
+            }
+        }
+    }
+    catch {
+        // Lexicon not available — skip
+    }
+    _cached = set;
+    return set;
+}

package/dist/teardown.js

@@ -0,0 +1,199 @@
+/**
+ * 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 { readOwnership } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+import { cfnQuery, xmlLeaves, xmlMembers, AwsReadError, } from "./api/read-client.js";
+import { awsDelete } from "./op/activities/aws-apply.js";
+/** The one candidate type this lexicon's teardown produces: whole stacks. */
+export const STACK_TYPE = "AWS::CloudFormation::Stack";
+/** The stacks an env teardown resolves to: `stacks[]`, else the single-stack convention. */
+export function resolveTeardownStacks(options) {
+    if (options.stacks && options.stacks.length > 0)
+        return options.stacks;
+    return [
+        {
+            name: options.stack ?? options.environment,
+            ...(options.region ? { region: options.region } : {}),
+        },
+    ];
+}
+/** A DescribeStacks miss — CloudFormation's "does not exist" ValidationError. */
+function isStackMissingError(err) {
+    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, region, read) {
+    let xml;
+    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 = {};
+    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, marker) {
+    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, deps = {}) {
+    const read = deps.read ?? {};
+    const candidates = [];
+    const holes = [];
+    for (const ref of resolveTeardownStacks(options)) {
+        let live;
+        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, deps = {}) {
+    const read = deps.read ?? {};
+    const regionByStack = new Map(resolveTeardownStacks(options).map((s) => [s.name, s.region]));
+    const outcomes = [];
+    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, region, marker, read, deps) {
+    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;
+    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" };
+}

package/dist/template-sections.js

@@ -0,0 +1,53 @@
+/**
+ * Template Description and Metadata — the template-level `Description` and
+ * `Metadata` sections of the synthesized CloudFormation template.
+ *
+ * Like `Transform` (./template-transform.ts), these belong to the template,
+ * not to a resource, so a project exports a declaration and the serializer
+ * lifts it to the top of the template. `chant import` writes them for the
+ * sections a template it imports has.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+/** Marker symbol for a template description or metadata declaration. */
+export const TEMPLATE_SECTION_MARKER = Symbol.for("chant.aws.templateSection");
+/** Type guard for TemplateSection. */
+export function isTemplateSection(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        TEMPLATE_SECTION_MARKER in value &&
+        value[TEMPLATE_SECTION_MARKER] === true);
+}
+function templateSection(section, value) {
+    return {
+        [TEMPLATE_SECTION_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "aws",
+        entityType: "chant:aws:templateSection",
+        section,
+        value,
+    };
+}
+/**
+ * Declare the template's top-level `Description`. One per template.
+ *
+ * @example
+ * ```ts
+ * export const description = templateDescription("Queue and its dead-letter queue");
+ * ```
+ */
+export function templateDescription(description) {
+    return templateSection("Description", description);
+}
+/**
+ * Declare entries in the template's top-level `Metadata`
+ * (`AWS::CloudFormation::Interface`, `cfn-lint` settings). Several
+ * declarations merge; keys chant writes itself are added after them.
+ *
+ * @example
+ * ```ts
+ * export const metadata = templateMetadata({ "cfn-lint": { config: { ignore_checks: ["W3005"] } } });
+ * ```
+ */
+export function templateMetadata(metadata) {
+    return templateSection("Metadata", metadata);
+}

package/dist/template-transform.js

@@ -0,0 +1,50 @@
+/**
+ * Template Transform — declares a top-level CloudFormation `Transform` macro
+ * for the synthesized template (e.g. `AWS::SecretsManager-2020-07-23` for a
+ * Secrets Manager `HostedRotationLambda`, or `AWS::LanguageExtensions`).
+ *
+ * CloudFormation's `Transform` is a template-level directive, not a resource
+ * property, so it can't be expressed as a normal Declarable's attributes. A
+ * project (or composite) exports a `templateTransform(...)` declaration and the
+ * serializer lifts it to the template's top-level `Transform` at synthesis time.
+ * Multiple declarations are merged and de-duplicated into a `Transform` list.
+ *
+ * Modeled exactly like `./default-tags.ts` — a marker-tagged Declarable the
+ * serializer detects and consumes rather than emitting as a resource.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+/** Marker symbol for template-transform identification. */
+export const TEMPLATE_TRANSFORM_MARKER = Symbol.for("chant.aws.templateTransform");
+/** Type guard for TemplateTransform. */
+export function isTemplateTransform(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        TEMPLATE_TRANSFORM_MARKER in value &&
+        value[TEMPLATE_TRANSFORM_MARKER] === true);
+}
+/**
+ * Declare a top-level CloudFormation `Transform` macro for the synthesized
+ * template. The serializer collects every `templateTransform(...)` in the
+ * project and emits their de-duplicated union as the template's `Transform`
+ * (a single string when there is one, a list when there are several).
+ *
+ * @param transform - The macro name, e.g. `"AWS::SecretsManager-2020-07-23"`.
+ * @returns A TemplateTransform Declarable.
+ *
+ * @example
+ * ```ts
+ * import { templateTransform } from "@intentius/chant-lexicon-aws";
+ *
+ * // Required whenever a resource uses SecretsManager HostedRotationLambda.
+ * export const rotationTransform = templateTransform("AWS::SecretsManager-2020-07-23");
+ * ```
+ */
+export function templateTransform(transform) {
+    return {
+        [TEMPLATE_TRANSFORM_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "aws",
+        entityType: "chant:aws:templateTransform",
+        transform,
+    };
+}