@thejoseki/clawform 2.3.1 → 2.4.0

package/src/aws/exports.js

@@ -1,213 +1,213 @@
-// Pre-flight checks on a stack's CloudFormation exports.
-//
-// Two day-2 traps live here, both computed from the LIVE stack's Outputs (which
-// CloudFormation reports with resolved OutputKey + ExportName) so neither needs
-// to resolve template intrinsics:
-//
-//   1. Export-lock (C1) — removing or un-exporting an Output whose export is
-//      still imported by another stack. CloudFormation rejects this at execute
-//      time with "Export <name> ... in use by <stack>", AFTER partial work and a
-//      rollback. We detect it before the changeset so the operator gets the
-//      two-step migration guidance instead of a wedged stack. See rules/limits.md.
-//
-//   2. Frozen-export (C2) — a stack whose NAME doesn't match a legacy prefix but
-//      that emits legacy-prefixed EXPORT names (e.g. stack `d-cfn-aao-vpc`
-//      exporting `OLDNET-VPC`). The name-only legacy gate in the PreToolUse hook
-//      can't see this (it's pure, no AWS access); the CLI can, because it has
-//      already fetched the live Outputs. See rules/legacy-freeze.md.
-
-import { ListImportsCommand } from '@aws-sdk/client-cloudformation';
-import { logger } from '../lib/logger.js';
-import { readEnv, ENV_PREFIX } from '../lib/rename-compat.js';
-
-// --- C1: export-lock --------------------------------------------------------
-
-/**
- * Live exports that the new template would remove.
- *
- * An export is "removed" when a live Output that carries an ExportName:
- *   - has an OutputKey NOT in `templateExportingKeys` (the set of Output keys
- *     the new template still exports — from extractExportingOutputKeys()), AND
- *   - has an ExportName NOT in `templateLiteralExportNames` (the literal
- *     Export.Name strings in the new template — from extractLiteralExportNames()).
- *
- * The second condition kills the OutputKey-rename false positive: renaming the
- * logical key while keeping the same literal Export.Name moves the export, it
- * doesn't remove it, and CloudFormation executes that fine. Intrinsic export
- * names (`!Sub …`) can't be matched offline — an export moved to a key whose
- * name became an intrinsic may still be flagged; ListImports then decides.
- *
- * Catches both "Output deleted entirely" and "Output kept but Export block
- * dropped". NOT caught (documented in rules/limits.md): an in-place rename that
- * keeps the OutputKey but changes Export.Name.
- *
- * @param liveOutputs               stack.Outputs from DescribeStacks: [{OutputKey, OutputValue, ExportName}]
- * @param templateExportingKeys     Set<string> of OutputKeys the new template exports
- * @param templateLiteralExportNames Set<string> of literal Export.Name strings in the new template
- * @returns Array<{ outputKey, exportName }>
- */
-export function findRemovedExports(liveOutputs, templateExportingKeys, templateLiteralExportNames = new Set()) {
-  const keys = templateExportingKeys instanceof Set ? templateExportingKeys : new Set(templateExportingKeys ?? []);
-  const out = [];
-  for (const o of liveOutputs ?? []) {
-    if (!o || !o.ExportName) continue; // only exported outputs can hit the lock
-    if (keys.has(o.OutputKey)) continue;                      // still exported under the same key
-    if (templateLiteralExportNames.has(o.ExportName)) continue; // moved to another key, same export name
-    out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
-  }
-  return out;
-}
-
-/**
- * Paginate ListImports for one export name. Importers found so far are pushed
- * into `sink` page-by-page, so a caller that catches a mid-pagination error
- * still sees the importers already confirmed — checkExportLock uses this to
- * fail CLOSED on partial proof.
- *
- * Hand-rolled NextToken loop instead of the SDK's paginateListImports on
- * purpose: the generated paginators hard-check `client instanceof
- * CloudFormationClient`, which would break every mocked-client test at this
- * seam (catalog.js/inventory.js can use them because they only ever run
- * against the real client).
- */
-export async function listImportsFor(client, exportName, sink = []) {
-  let nextToken;
-  do {
-    const resp = await client.send(new ListImportsCommand({ ExportName: exportName, NextToken: nextToken }));
-    for (const imp of resp.Imports ?? []) sink.push(imp);
-    nextToken = resp.NextToken;
-  } while (nextToken);
-  return sink;
-}
-
-/**
- * For each removed export, ask CloudFormation who still imports it. The
- * per-export checks are independent, so they run concurrently.
- *
- * Failure posture:
- *   - A confirmed in-use export → fail CLOSED (caller blocks the deploy): the
- *     changeset is guaranteed to fail, so blocking pre-flight strictly helps.
- *     This includes PARTIAL proof — importers seen on page 1 before page 2
- *     threw still block.
- *   - Our own inability to check (ListImports throws with zero importers seen —
- *     e.g. missing cloudformation:ListImports permission) → fail OPEN: record
- *     the error and let the deploy proceed rather than block on a check we
- *     couldn't run. CloudFormation still refuses a genuinely in-use removal.
- *
- * AWS quirk: ListImports throws a ValidationError ("Export ... is not imported
- * by any stack") when an export has zero importers. That's a CLEAN result, not
- * an error — treated as "no importers", not fail-open.
- *
- * @returns { blocked: Array<{exportName, importers}>, unchecked: Array<{exportName, error}> }
- */
-export async function checkExportLock(client, removedExports) {
-  const results = await Promise.all((removedExports ?? []).map(async ({ exportName }) => {
-    const importers = [];
-    try {
-      await listImportsFor(client, exportName, importers);
-      return importers.length > 0 ? { blocked: { exportName, importers } } : {};
-    } catch (err) {
-      if (importers.length > 0) return { blocked: { exportName, importers } }; // partial proof → fail closed
-      if (isNotImportedError(err)) return {}; // zero importers — safe to remove
-      return { unchecked: { exportName, error: err?.message ?? String(err) } };
-    }
-  }));
-  return {
-    blocked: results.map((r) => r.blocked).filter(Boolean),
-    unchecked: results.map((r) => r.unchecked).filter(Boolean),
-  };
-}
-
-function isNotImportedError(err) {
-  const msg = err?.message ?? '';
-  return err?.name === 'ValidationError' && /is not imported by any stack/i.test(msg);
-}
-
-// --- C2: frozen-export ------------------------------------------------------
-
-/**
- * Live export names matching the consumer's legacy prefixes.
- *
- * `legacyRe` must be the ANCHORED regex (buildAnchoredLegacyPrefixRegex) — the
- * prefix has to be the export name's LEADING segment. The hook's unanchored
- * command-line regex would false-positive on legacy tokens mid-name
- * (`p-acme-pri-lmd-payroll-OLDAPP-arn`). Null regex = no gate (fresh consumer).
- *
- * @returns Array<{ outputKey, exportName }>
- */
-export function findFrozenExports(liveOutputs, legacyRe) {
-  if (!legacyRe) return [];
-  const out = [];
-  for (const o of liveOutputs ?? []) {
-    if (!o || !o.ExportName) continue;
-    if (legacyRe.test(o.ExportName)) {
-      out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
-    }
-  }
-  return out;
-}
-
-// Break-glass for the frozen-export gates (mirrors CLAWFORM_SKIP_ACCOUNT_CHECK):
-// intentionally a noisy env var, not a CLI flag. Needed because a frozen-named
-// export, once live, would otherwise also block the remediation deploy that
-// removes it — and unlike the stack-NAME freeze there is no `# FORCE LEGACY`
-// hook path here (the hook never sees export names).
-// Suffix for the lookup, full name for anything a human reads.
-const SKIP_FROZEN_SUFFIX = 'SKIP_FROZEN_EXPORT_CHECK';
-const SKIP_FROZEN_ENV = `${ENV_PREFIX}${SKIP_FROZEN_SUFFIX}`;
-
-export function frozenExportCheckSkipped(action) {
-  if (readEnv(SKIP_FROZEN_SUFFIX) !== '1') return false;
-  logger.warn(
-    `${SKIP_FROZEN_ENV}=1 — bypassing the frozen-export gate for this ${action}. ` +
-    `Break-glass only; unset to re-enable.`,
-  );
-  return true;
-}
-
-/**
- * Shared C2 gate for deploy AND rollback: refuse a stack that EMITS
- * legacy-prefixed export names, even when the stack NAME isn't frozen. Closes
- * the "stack-name-only" gap in rules/legacy-freeze.md.
- *
- * @param action  'deploy' | 'recovery' — only changes the refusal wording.
- * Throws on a frozen export. Returns void when clean / skipped via break-glass.
- */
-export function assertNoFrozenExports({ liveOutputs, legacyRe, stackName, action = 'deploy' } = {}) {
-  const frozen = findFrozenExports(liveOutputs, legacyRe);
-  if (frozen.length === 0) return;
-  if (frozenExportCheckSkipped(action)) return;
-  const names = frozen.map((f) => f.exportName).join(', ');
-  throw new Error(
-    `Stack "${stackName}" emits export(s) matching a legacy prefix (${names}) from your clawform.config.json ` +
-    `legacy_prefixes — even though the stack NAME isn't frozen. Clawform treats legacy-named exports as frozen ` +
-    `too (rules/legacy-freeze.md). Refusing ${action === 'recovery' ? 'recovery' : 'to deploy'}.\n` +
-    `If this is intentional (e.g. retiring the legacy-named export itself), re-run with ` +
-    `${SKIP_FROZEN_ENV}=1, or use the raw aws cloudformation CLI.`,
-  );
-}
-
-/**
- * C2 introduction gate: refuse a TEMPLATE whose literal Export.Name strings
- * would CREATE a legacy-prefixed export. Without this, deploy would happily
- * mint e.g. `OLDNET-NewThing` on a clean-named stack (the live-outputs gate only
- * sees exports that already exist) — and the live gate would then freeze the
- * stack against its own tooling. Intrinsic Export.Names can't be checked
- * offline; legacy names are literal in practice.
- *
- * @param templateExportNames  Set<string> from extractLiteralExportNames()
- * Throws when a frozen name would be introduced. Honors the same break-glass.
- */
-export function assertNoFrozenTemplateExports({ templateExportNames, legacyRe, stackName } = {}) {
-  if (!legacyRe) return;
-  const frozen = [...(templateExportNames ?? [])].filter((n) => legacyRe.test(n));
-  if (frozen.length === 0) return;
-  if (frozenExportCheckSkipped('deploy')) return;
-  throw new Error(
-    `Template for stack "${stackName}" would CREATE export(s) named like a legacy prefix (${frozen.join(', ')}) ` +
-    `from your clawform.config.json legacy_prefixes. New exports must follow the going-forward convention ` +
-    `(rules/cfn-standards.md) — a legacy-prefixed export would immediately freeze this stack against ` +
-    `clawform deploy/rollback (rules/legacy-freeze.md). Rename the export. ` +
-    `Break-glass: ${SKIP_FROZEN_ENV}=1.`,
-  );
-}
+// Pre-flight checks on a stack's CloudFormation exports.
+//
+// Two day-2 traps live here, both computed from the LIVE stack's Outputs (which
+// CloudFormation reports with resolved OutputKey + ExportName) so neither needs
+// to resolve template intrinsics:
+//
+//   1. Export-lock (C1) — removing or un-exporting an Output whose export is
+//      still imported by another stack. CloudFormation rejects this at execute
+//      time with "Export <name> ... in use by <stack>", AFTER partial work and a
+//      rollback. We detect it before the changeset so the operator gets the
+//      two-step migration guidance instead of a wedged stack. See rules/limits.md.
+//
+//   2. Frozen-export (C2) — a stack whose NAME doesn't match a legacy prefix but
+//      that emits legacy-prefixed EXPORT names (e.g. stack `d-cfn-aao-vpc`
+//      exporting `OLDNET-VPC`). The name-only legacy gate in the PreToolUse hook
+//      can't see this (it's pure, no AWS access); the CLI can, because it has
+//      already fetched the live Outputs. See rules/legacy-freeze.md.
+
+import { ListImportsCommand } from '@aws-sdk/client-cloudformation';
+import { logger } from '../lib/logger.js';
+import { readEnv, ENV_PREFIX } from '../lib/rename-compat.js';
+
+// --- C1: export-lock --------------------------------------------------------
+
+/**
+ * Live exports that the new template would remove.
+ *
+ * An export is "removed" when a live Output that carries an ExportName:
+ *   - has an OutputKey NOT in `templateExportingKeys` (the set of Output keys
+ *     the new template still exports — from extractExportingOutputKeys()), AND
+ *   - has an ExportName NOT in `templateLiteralExportNames` (the literal
+ *     Export.Name strings in the new template — from extractLiteralExportNames()).
+ *
+ * The second condition kills the OutputKey-rename false positive: renaming the
+ * logical key while keeping the same literal Export.Name moves the export, it
+ * doesn't remove it, and CloudFormation executes that fine. Intrinsic export
+ * names (`!Sub …`) can't be matched offline — an export moved to a key whose
+ * name became an intrinsic may still be flagged; ListImports then decides.
+ *
+ * Catches both "Output deleted entirely" and "Output kept but Export block
+ * dropped". NOT caught (documented in rules/limits.md): an in-place rename that
+ * keeps the OutputKey but changes Export.Name.
+ *
+ * @param liveOutputs               stack.Outputs from DescribeStacks: [{OutputKey, OutputValue, ExportName}]
+ * @param templateExportingKeys     Set<string> of OutputKeys the new template exports
+ * @param templateLiteralExportNames Set<string> of literal Export.Name strings in the new template
+ * @returns Array<{ outputKey, exportName }>
+ */
+export function findRemovedExports(liveOutputs, templateExportingKeys, templateLiteralExportNames = new Set()) {
+  const keys = templateExportingKeys instanceof Set ? templateExportingKeys : new Set(templateExportingKeys ?? []);
+  const out = [];
+  for (const o of liveOutputs ?? []) {
+    if (!o || !o.ExportName) continue; // only exported outputs can hit the lock
+    if (keys.has(o.OutputKey)) continue;                      // still exported under the same key
+    if (templateLiteralExportNames.has(o.ExportName)) continue; // moved to another key, same export name
+    out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
+  }
+  return out;
+}
+
+/**
+ * Paginate ListImports for one export name. Importers found so far are pushed
+ * into `sink` page-by-page, so a caller that catches a mid-pagination error
+ * still sees the importers already confirmed — checkExportLock uses this to
+ * fail CLOSED on partial proof.
+ *
+ * Hand-rolled NextToken loop instead of the SDK's paginateListImports on
+ * purpose: the generated paginators hard-check `client instanceof
+ * CloudFormationClient`, which would break every mocked-client test at this
+ * seam (catalog.js/inventory.js can use them because they only ever run
+ * against the real client).
+ */
+export async function listImportsFor(client, exportName, sink = []) {
+  let nextToken;
+  do {
+    const resp = await client.send(new ListImportsCommand({ ExportName: exportName, NextToken: nextToken }));
+    for (const imp of resp.Imports ?? []) sink.push(imp);
+    nextToken = resp.NextToken;
+  } while (nextToken);
+  return sink;
+}
+
+/**
+ * For each removed export, ask CloudFormation who still imports it. The
+ * per-export checks are independent, so they run concurrently.
+ *
+ * Failure posture:
+ *   - A confirmed in-use export → fail CLOSED (caller blocks the deploy): the
+ *     changeset is guaranteed to fail, so blocking pre-flight strictly helps.
+ *     This includes PARTIAL proof — importers seen on page 1 before page 2
+ *     threw still block.
+ *   - Our own inability to check (ListImports throws with zero importers seen —
+ *     e.g. missing cloudformation:ListImports permission) → fail OPEN: record
+ *     the error and let the deploy proceed rather than block on a check we
+ *     couldn't run. CloudFormation still refuses a genuinely in-use removal.
+ *
+ * AWS quirk: ListImports throws a ValidationError ("Export ... is not imported
+ * by any stack") when an export has zero importers. That's a CLEAN result, not
+ * an error — treated as "no importers", not fail-open.
+ *
+ * @returns { blocked: Array<{exportName, importers}>, unchecked: Array<{exportName, error}> }
+ */
+export async function checkExportLock(client, removedExports) {
+  const results = await Promise.all((removedExports ?? []).map(async ({ exportName }) => {
+    const importers = [];
+    try {
+      await listImportsFor(client, exportName, importers);
+      return importers.length > 0 ? { blocked: { exportName, importers } } : {};
+    } catch (err) {
+      if (importers.length > 0) return { blocked: { exportName, importers } }; // partial proof → fail closed
+      if (isNotImportedError(err)) return {}; // zero importers — safe to remove
+      return { unchecked: { exportName, error: err?.message ?? String(err) } };
+    }
+  }));
+  return {
+    blocked: results.map((r) => r.blocked).filter(Boolean),
+    unchecked: results.map((r) => r.unchecked).filter(Boolean),
+  };
+}
+
+function isNotImportedError(err) {
+  const msg = err?.message ?? '';
+  return err?.name === 'ValidationError' && /is not imported by any stack/i.test(msg);
+}
+
+// --- C2: frozen-export ------------------------------------------------------
+
+/**
+ * Live export names matching the consumer's legacy prefixes.
+ *
+ * `legacyRe` must be the ANCHORED regex (buildAnchoredLegacyPrefixRegex) — the
+ * prefix has to be the export name's LEADING segment. The hook's unanchored
+ * command-line regex would false-positive on legacy tokens mid-name
+ * (`p-acme-pri-lmd-payroll-OLDAPP-arn`). Null regex = no gate (fresh consumer).
+ *
+ * @returns Array<{ outputKey, exportName }>
+ */
+export function findFrozenExports(liveOutputs, legacyRe) {
+  if (!legacyRe) return [];
+  const out = [];
+  for (const o of liveOutputs ?? []) {
+    if (!o || !o.ExportName) continue;
+    if (legacyRe.test(o.ExportName)) {
+      out.push({ outputKey: o.OutputKey, exportName: o.ExportName });
+    }
+  }
+  return out;
+}
+
+// Break-glass for the frozen-export gates (mirrors CLAWFORM_SKIP_ACCOUNT_CHECK):
+// intentionally a noisy env var, not a CLI flag. Needed because a frozen-named
+// export, once live, would otherwise also block the remediation deploy that
+// removes it — and unlike the stack-NAME freeze there is no `# FORCE LEGACY`
+// hook path here (the hook never sees export names).
+// Suffix for the lookup, full name for anything a human reads.
+const SKIP_FROZEN_SUFFIX = 'SKIP_FROZEN_EXPORT_CHECK';
+const SKIP_FROZEN_ENV = `${ENV_PREFIX}${SKIP_FROZEN_SUFFIX}`;
+
+export function frozenExportCheckSkipped(action) {
+  if (readEnv(SKIP_FROZEN_SUFFIX) !== '1') return false;
+  logger.warn(
+    `${SKIP_FROZEN_ENV}=1 — bypassing the frozen-export gate for this ${action}. ` +
+    `Break-glass only; unset to re-enable.`,
+  );
+  return true;
+}
+
+/**
+ * Shared C2 gate for deploy AND rollback: refuse a stack that EMITS
+ * legacy-prefixed export names, even when the stack NAME isn't frozen. Closes
+ * the "stack-name-only" gap in rules/legacy-freeze.md.
+ *
+ * @param action  'deploy' | 'recovery' — only changes the refusal wording.
+ * Throws on a frozen export. Returns void when clean / skipped via break-glass.
+ */
+export function assertNoFrozenExports({ liveOutputs, legacyRe, stackName, action = 'deploy' } = {}) {
+  const frozen = findFrozenExports(liveOutputs, legacyRe);
+  if (frozen.length === 0) return;
+  if (frozenExportCheckSkipped(action)) return;
+  const names = frozen.map((f) => f.exportName).join(', ');
+  throw new Error(
+    `Stack "${stackName}" emits export(s) matching a legacy prefix (${names}) from your clawform.config.json ` +
+    `legacy_prefixes — even though the stack NAME isn't frozen. Clawform treats legacy-named exports as frozen ` +
+    `too (rules/legacy-freeze.md). Refusing ${action === 'recovery' ? 'recovery' : 'to deploy'}.\n` +
+    `If this is intentional (e.g. retiring the legacy-named export itself), re-run with ` +
+    `${SKIP_FROZEN_ENV}=1, or use the raw aws cloudformation CLI.`,
+  );
+}
+
+/**
+ * C2 introduction gate: refuse a TEMPLATE whose literal Export.Name strings
+ * would CREATE a legacy-prefixed export. Without this, deploy would happily
+ * mint e.g. `OLDNET-NewThing` on a clean-named stack (the live-outputs gate only
+ * sees exports that already exist) — and the live gate would then freeze the
+ * stack against its own tooling. Intrinsic Export.Names can't be checked
+ * offline; legacy names are literal in practice.
+ *
+ * @param templateExportNames  Set<string> from extractLiteralExportNames()
+ * Throws when a frozen name would be introduced. Honors the same break-glass.
+ */
+export function assertNoFrozenTemplateExports({ templateExportNames, legacyRe, stackName } = {}) {
+  if (!legacyRe) return;
+  const frozen = [...(templateExportNames ?? [])].filter((n) => legacyRe.test(n));
+  if (frozen.length === 0) return;
+  if (frozenExportCheckSkipped('deploy')) return;
+  throw new Error(
+    `Template for stack "${stackName}" would CREATE export(s) named like a legacy prefix (${frozen.join(', ')}) ` +
+    `from your clawform.config.json legacy_prefixes. New exports must follow the going-forward convention ` +
+    `(rules/cfn-standards.md) — a legacy-prefixed export would immediately freeze this stack against ` +
+    `clawform deploy/rollback (rules/legacy-freeze.md). Rename the export. ` +
+    `Break-glass: ${SKIP_FROZEN_ENV}=1.`,
+  );
+}