@thejoseki/clawform 2.3.0 → 2.3.2

package/src/commands/deploy.js

@@ -1,413 +1,413 @@
-import { readFile } from 'node:fs/promises';
-import inquirer from 'inquirer';
-import chalk from 'chalk';
-import { readEnv } from '../lib/rename-compat.js';
-import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
-import { logger } from '../lib/logger.js';
-import { cfnClient } from '../lib/aws-client.js';
-import { loadConfig, resolveStackTags } from '../lib/config.js';
-import { loadProjectConfig, buildLegacyPrefixRegex, buildAnchoredLegacyPrefixRegex, resolveProjectDir } from '../lib/project-config.js';
-import { addPendingChangeset, clearPendingChangeset } from '../lib/session-state.js';
-import { ENVS, isDataResource } from '../lib/constants.js';
-import { loadCfnTemplate, extractExportingOutputKeys, extractLiteralExportNames } from '../lib/cfn-yaml.js';
-import {
-  findRemovedExports,
-  checkExportLock,
-  assertNoFrozenExports,
-  assertNoFrozenTemplateExports,
-} from '../aws/exports.js';
-import {
-  stackStatus,
-  decideChangeSetType,
-  createAndWait,
-  classifyChanges,
-  executeAndPoll,
-} from '../aws/changeset.js';
-
-// Runtime account guard: refuse to deploy when the caller's AWS account does
-// not match the consumer's clawform.config.json `accounts[env]` mapping.
-//
-// Why a separate exported helper:
-//   - Lets tests mock `@aws-sdk/client-sts` and drive the 4 branches
-//     (match, mismatch, no-guard-configured, break-glass) without standing up
-//     the rest of deploy().
-//   - Keeps the deploy() body linear — one call, one place to land the guard.
-//
-// Args:
-//   env             — env string ('d' | 'stg' | 'p').
-//   accounts        — projectCfg.accounts (already loaded by deploy()). May be
-//                     missing, empty, or {env: ''} — all "no guard" cases.
-//   region          — AWS region for the STS client (matches the CFN region).
-//   stsClientFactory — optional override; defaults to a fresh STSClient. Tests
-//                     use vi.mock('@aws-sdk/client-sts') instead and don't need
-//                     this. Kept for callers who want to inject a stub.
-//
-// Resolution order:
-//   1. CLAWFORM_SKIP_ACCOUNT_CHECK=1 → bypass with yellow warning (break-glass).
-//   2. accounts[env] empty / undefined → skip with yellow warning.
-//   3. STS get-caller-identity → compare → throw on mismatch.
-//
-// Throws on mismatch. Resolves with how it concluded — 'verified' (STS ran and
-// matched), 'skipped' (no account configured, non-prod), or 'bypassed'
-// (break-glass env var) — so callers can make the unattended-prod decision.
-export async function assertAccountMatches({ env, accounts, region, stsClientFactory } = {}) {
-  if (readEnv('SKIP_ACCOUNT_CHECK') === '1') {
-    logger.warn(
-      `CLAWFORM_SKIP_ACCOUNT_CHECK=1 — bypassing account-match guard for env '${env}'` +
-      `${env === 'p' ? ' (PRODUCTION)' : ''}. Break-glass only; unset to re-enable.`,
-    );
-    return 'bypassed';
-  }
-  const expectedRaw = accounts && typeof accounts === 'object' ? accounts[env] : undefined;
-  const expected = typeof expectedRaw === 'string' ? expectedRaw.trim() : '';
-  if (!expected) {
-    // Production is the one env where an unset guard is refused rather than
-    // warned past — a p deploy into the wrong account is the exact accident
-    // this check exists for. d/stg stay lenient: an account not yet pinned is
-    // a legitimate bootstrap state.
-    if (env === 'p') {
-      throw new Error(
-        `Env 'p' requires accounts.p in clawform.config.json — a production deploy without ` +
-        `an account guard is refused. Add the 12-digit account id (edit the file or rerun clawform init --force).`,
-      );
-    }
-    logger.warn(`No account guard configured for env '${env}' — skipping account-match check.`);
-    return 'skipped';
-  }
-  const client = stsClientFactory ? stsClientFactory() : new STSClient(region ? { region } : {});
-  const resp = await client.send(new GetCallerIdentityCommand({}));
-  const caller = resp && resp.Account ? String(resp.Account).trim() : '';
-  if (caller !== expected) {
-    throw new Error(
-      `Account mismatch: caller is ${caller || '(unknown)'} but env '${env}' is configured for ${expected} ` +
-      `in clawform.config.json. Refusing to deploy.`,
-    );
-  }
-  return 'verified';
-}
-
-// Unattended production deploys are fine for CI — CodePipeline's manual
-// approval already puts a human in the loop — but only when the account guard
-// genuinely ran and matched. autoApprove combined with a bypassed guard on p
-// would mean nothing checked which account is being written to.
-export function assertProdDeployAllowed({ env, autoApprove, accountCheckMode } = {}) {
-  if (env !== 'p' || !autoApprove) return;
-  if (accountCheckMode !== 'verified') {
-    throw new Error(
-      `--auto-approve is refused for a production deploy unless the account guard verified the ` +
-      `caller (guard was '${accountCheckMode}'). Configure accounts.p and unset CLAWFORM_SKIP_ACCOUNT_CHECK, ` +
-      `or run interactively.`,
-    );
-  }
-}
-
-// C1 (export-lock pre-check): an UPDATE that removes (or un-exports) a live
-// export still imported elsewhere is guaranteed to fail at execute time with
-// "Export ... in use by" and roll back. Detect it BEFORE creating the changeset
-// (all inputs — live Outputs and the template body — exist by then) and hand
-// the operator the two-step migration instead of a wedged stack (rules/limits.md).
-//
-// Fail-open on our own inability to check (parse failure, ListImports denied
-// with no importer seen) — CloudFormation still refuses the real removal if
-// it's genuinely in use. Fail-closed on any confirmed importer, including
-// partial pagination proof (see checkExportLock).
-export async function assertExportLockClear({ client, liveOutputs, templateBody } = {}) {
-  const exportsLive = (liveOutputs ?? []).filter((o) => o && o.ExportName);
-  if (exportsLive.length === 0) return;             // nothing exported → no lock possible
-  const doc = loadCfnTemplate(templateBody);
-  if (!doc) return;                                 // unparseable → linters own the error
-  const removed = findRemovedExports(
-    liveOutputs,
-    extractExportingOutputKeys(doc),
-    extractLiteralExportNames(doc), // same export name under a new OutputKey = moved, not removed
-  );
-  if (removed.length === 0) return;
-  const { blocked, unchecked } = await checkExportLock(client, removed);
-  for (const u of unchecked) {
-    logger.warn(
-      `Could not verify importers for export "${u.exportName}" (${u.error}) — proceeding; ` +
-      `CloudFormation will still refuse the removal if it's in use.`,
-    );
-  }
-  if (blocked.length === 0) return;
-  const lines = blocked.map((b) => `  • ${b.exportName} — imported by: ${b.importers.join(', ')}`);
-  throw new Error(
-    `Export-lock: this update removes ${blocked.length} export(s) still imported by other stack(s):\n` +
-    `${lines.join('\n')}\n` +
-    `CloudFormation will reject the changeset ("Export ... in use by") and roll back. ` +
-    `Use the two-step migration (rules/limits.md):\n` +
-    `  1. Keep the old export; add the new export alongside it and deploy this producer first.\n` +
-    `  2. Migrate each consumer to the new import, deploy them in dependency order, then retire the\n` +
-    `     old export in a final producer deploy once "aws cloudformation list-imports" is empty.`,
-  );
-}
-
-export default async function deploy({ file, env, stackName, project, params, capabilities, autoApprove }) {
-  if (!ENVS.includes(env)) {
-    throw new Error(`Invalid env "${env}". Expected one of: ${ENVS.join(' | ')}`);
-  }
-  if (!stackName) throw new Error('--stack-name is required.');
-  if (!project) throw new Error('--project is required (used as Project tag value).');
-
-  const projectDir = resolveProjectDir();
-  const projectCfg = loadProjectConfig({ projectDir });
-  const legacyRe = buildLegacyPrefixRegex(projectCfg.legacy_prefixes);
-  if (legacyRe && legacyRe.test(stackName)) {
-    const list = projectCfg.legacy_prefixes.map((p) => `${p}-*`).join(', ');
-    throw new Error(
-      `Stack "${stackName}" matches a legacy prefix (${list}) from your clawform.config.json.\n` +
-      `clawform deploy refuses to modify legacy stacks. See rules/legacy-freeze.md and docs/config-schema.md.\n` +
-      `Use raw aws cloudformation CLI with a "# FORCE LEGACY: <reason>" comment if modification is unavoidable.`,
-    );
-  }
-
-  // loadConfig() still gates AWS_PROFILE / AWS_REGION with the friendly error.
-  // OWNER / COST_CENTER are no longer required here — resolveStackTags() owns
-  // the env-var-then-tags_defaults chain and throws with a usable message
-  // when both sources are empty.
-  const cfg = loadConfig({});
-  const stackTags = resolveStackTags(projectCfg, env);
-
-  // Runtime account guard. Runs after loadConfig() so the friendly missing-creds
-  // error fires first; runs before any CFN call so the engineer doesn't have to
-  // wait on a changeset round-trip to discover they're pointed at the wrong AWS
-  // account. See docs/config-schema.md "Wired today" for resolution rules.
-  const accountCheckMode = await assertAccountMatches({
-    env,
-    accounts: projectCfg.accounts,
-    region: cfg.AWS_REGION,
-  });
-  assertProdDeployAllowed({ env, autoApprove, accountCheckMode });
-
-  const templateBody = await readFile(file, 'utf8');
-
-  // C2 introduction gate: refuse a template whose literal Export.Name strings
-  // would CREATE a legacy-prefixed export (covers CREATE deploys too — the
-  // live-outputs gate below only sees exports that already exist). Anchored
-  // regex: the prefix must lead the export name, so legacy tokens mid-name in
-  // convention-compliant exports don't false-positive.
-  const anchoredLegacyRe = buildAnchoredLegacyPrefixRegex(projectCfg.legacy_prefixes);
-  assertNoFrozenTemplateExports({
-    templateExportNames: extractLiteralExportNames(loadCfnTemplate(templateBody)),
-    legacyRe: anchoredLegacyRe,
-    stackName,
-  });
-
-  let parameters = [];
-  if (params) {
-    const raw = await readFile(params, 'utf8');
-    parameters = JSON.parse(raw);
-    if (!Array.isArray(parameters)) {
-      throw new Error(`${params}: expected JSON array of {ParameterKey, ParameterValue}.`);
-    }
-  }
-
-  // Tag key spelling pinned by rules/tagging.md — Env (not Environment), and
-  // the 5 mandatory keys (Project, Env, Owner, CostCenter, ManagedBy). Customer
-  // from resolveStackTags is informational and not emitted as a tag here.
-  const tags = [
-    { Key: 'Project', Value: project },
-    { Key: 'Env', Value: stackTags.Environment },
-    { Key: 'Owner', Value: stackTags.Owner },
-    { Key: 'CostCenter', Value: stackTags.CostCenter },
-    { Key: 'ManagedBy', Value: stackTags.ManagedBy },
-  ];
-
-  const caps = capabilities ? capabilities.split(',').map((s) => s.trim()).filter(Boolean) : [];
-
-  const client = cfnClient();
-  const status = await stackStatus(client, stackName);
-
-  if (status.exists) {
-    // C2: frozen-export gate — refuse a stack emitting legacy-prefixed exports
-    // even when its name doesn't match. Anchored regex (leading segment only).
-    assertNoFrozenExports({ liveOutputs: status.stack?.Outputs, legacyRe: anchoredLegacyRe, stackName });
-
-    // C1: export-lock pre-check. Runs BEFORE the changeset — both inputs (live
-    // Outputs, template body) already exist, and a blocked deploy should not
-    // pay a CreateChangeSet round-trip or leave an orphaned changeset behind.
-    await assertExportLockClear({ client, liveOutputs: status.stack?.Outputs, templateBody });
-  }
-
-  const changeSetType = decideChangeSetType(status);
-  logger.info(`Stack ${stackName}: ${status.exists ? status.status : '(does not exist)'} → ${changeSetType}`);
-
-  logger.step(`Creating change-set on ${stackName}…`);
-  const cs = await createAndWait(client, {
-    stackName,
-    changeSetType,
-    templateBody,
-    parameters,
-    tags,
-    capabilities: caps,
-  });
-
-  if (cs.isEmpty) {
-    logger.ok(`No changes (${cs.statusReason}). Empty change-set deleted.`);
-    return;
-  }
-
-  // In-flight state: the changeset now exists in AWS but hasn't executed. Record
-  // it so that if the operator aborts at the confirm prompt (or runs /clear),
-  // the next session's context hook warns a changeset is sitting unexecuted.
-  // Cleared after execute below. Fail-open — a state-write problem must never
-  // block the deploy.
-  try {
-    addPendingChangeset(projectDir, {
-      stack: stackName,
-      changeSetName: cs.name,
-      env,
-      createdAt: new Date().toISOString(),
-    });
-  } catch (err) {
-    logger.warn(`Could not record pending changeset state (continuing): ${err.message}`);
-  }
-
-  const buckets = classifyChanges(cs.changes);
-  renderChangeTable(buckets);
-
-  const dataRemove = buckets.remove.filter((r) => isDataResource(r.resourceType));
-  const needsRetype = buckets.dataResourceReplace.length > 0 || dataRemove.length > 0;
-
-  if (autoApprove) {
-    if (buckets.replace.length > 0 || needsRetype) {
-      throw new Error('--auto-approve refused: change-set includes Replace or data-resource removal.');
-    }
-    logger.info('Proceeding (--auto-approve, no Replace / data removal).');
-  } else {
-    // Production always earns the retype gate, whatever the changeset holds —
-    // the extra keystroke is the point. Folded into the same prompt as the
-    // data-resource retype so an operator never types the name twice.
-    const prodRetype = env === 'p';
-    if (prodRetype && !needsRetype) {
-      logger.warn(`Production deploy to '${stackName}' — confirm by retyping the stack name.`);
-    }
-    if (needsRetype || prodRetype) {
-      if (buckets.dataResourceReplace.length > 0) {
-        logger.warn(`${buckets.dataResourceReplace.length} data resource(s) will be REPLACED — physical resource recreated.`);
-        // A4 (plain language): spell out the consequence so a non-DevOps operator
-        // understands what "Replace" costs before they retype the stack name.
-        logger.warn('  In plain terms: a brand-new resource is created and the old one is destroyed. Live data');
-        logger.warn('  on the old resource is NOT migrated — it survives only as a snapshot if DeletionPolicy/');
-        logger.warn('  UpdateReplacePolicy is Snapshot (RDS/Aurora) or Retain. Verify that before continuing.');
-      }
-      if (dataRemove.length > 0) {
-        logger.warn(`${dataRemove.length} data resource(s) will be REMOVED from the stack — physical fate depends on DeletionPolicy (change-set does not expose it).`);
-        for (const r of dataRemove) logger.warn(`  ${r.logicalId} (${r.resourceType})`);
-        logger.warn('  In plain terms: CloudFormation stops managing these. If DeletionPolicy is Retain/Snapshot the');
-        logger.warn('  underlying data survives; otherwise it is deleted. Confirm the policy before continuing.');
-      }
-      const { typed } = await inquirer.prompt([{
-        type: 'input',
-        name: 'typed',
-        message: `Type the stack name EXACTLY to confirm:`,
-        validate: (v) => v.trim() === stackName ? true : `Type "${stackName}" exactly.`,
-      }]);
-      if (typed.trim() !== stackName) throw new Error('Aborted: stack name did not match.');
-    }
-    const { ok } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'ok',
-      message: `Execute change-set ${cs.name} on ${stackName}?`,
-      default: false,
-    }]);
-    if (!ok) {
-      logger.warn('Aborted by user. Change-set kept (delete via AWS console or rerun).');
-      return;
-    }
-  }
-
-  logger.step(`Executing change-set ${cs.name}…`);
-  const result = await executeAndPoll(client, {
-    stackName,
-    changeSetName: cs.name,
-    onEvent: (ev) => {
-      const color = EVENT_COLOR[ev.ResourceStatus] ?? ((s) => s);
-      const reason = ev.ResourceStatusReason ? ` ${chalk.gray('—')} ${ev.ResourceStatusReason}` : '';
-      logger.info(`  ${(ev.LogicalResourceId ?? '').padEnd(30)} ${color(ev.ResourceStatus)}${reason}`);
-    },
-  });
-
-  // The changeset has been executed (success or failure) — no longer pending.
-  try {
-    clearPendingChangeset(projectDir, { stack: stackName, changeSetName: cs.name });
-  } catch { /* fail-open — never let a state-write problem mask the deploy result */ }
-
-  if (/COMPLETE$/.test(result.stackStatus) && !/ROLLBACK/.test(result.stackStatus)) {
-    logger.ok(`Stack ${stackName} → ${result.stackStatus}`);
-    const outs = result.stack?.Outputs ?? [];
-    if (outs.length) {
-      logger.info('Outputs:');
-      for (const o of outs) {
-        logger.info(`  ${(o.OutputKey ?? '').padEnd(30)} = ${o.OutputValue ?? ''}`);
-      }
-      highlightEndpoints(outs);
-    }
-  } else {
-    logger.error(`Stack ${stackName} → ${result.stackStatus}. Use /rollback to investigate.`);
-    process.exit(1);
-  }
-}
-
-// D2 (post-deploy verification): a clean COMPLETE means CloudFormation finished,
-// not that the app works. Surface endpoint-like outputs so the operator has
-// something concrete to hit before calling the deploy done. Heuristic on the
-// OutputKey name — intentionally loose; a false highlight costs nothing.
-// Keep in sync with the canonical export suffixes in rules/cfn-standards.md
-// (-id, -arn, -name, -dns, -uri) — 'uri' in particular is the convention's own
-// endpoint suffix.
-const ENDPOINT_KEY_RE = /(url|uri|endpoint|dns|domain|address|hostname|fqdn)/i;
-
-export function highlightEndpoints(outs) {
-  const endpoints = (outs ?? []).filter((o) => ENDPOINT_KEY_RE.test(o.OutputKey ?? '') && o.OutputValue);
-  if (endpoints.length === 0) return;
-  logger.info('');
-  logger.info('Endpoints to verify:');
-  for (const o of endpoints) logger.info(`  ${chalk.cyan(o.OutputValue)}  ${chalk.gray(`(${o.OutputKey})`)}`);
-  logger.info(chalk.gray('A clean stack status means CloudFormation finished — confirm each endpoint actually responds before considering the deploy done.'));
-}
-
-const EVENT_COLOR = {
-  CREATE_COMPLETE: chalk.green,
-  UPDATE_COMPLETE: chalk.green,
-  CREATE_IN_PROGRESS: chalk.cyan,
-  UPDATE_IN_PROGRESS: chalk.cyan,
-  DELETE_COMPLETE: chalk.gray,
-  DELETE_IN_PROGRESS: chalk.gray,
-  CREATE_FAILED: chalk.red,
-  UPDATE_FAILED: chalk.red,
-  DELETE_FAILED: chalk.red,
-  ROLLBACK_IN_PROGRESS: chalk.yellow,
-  ROLLBACK_COMPLETE: chalk.yellow,
-};
-
-function renderChangeTable(buckets) {
-  logger.info('');
-  logger.info('Change-set summary:');
-  logger.info(`  ${chalk.green('+ Add')}     ${buckets.add.length}`);
-  logger.info(`  ${chalk.cyan('~ Modify')}  ${buckets.modify.length}`);
-  logger.info(`  ${chalk.yellow('! Replace')} ${buckets.replace.length}`);
-  logger.info(`  ${chalk.red('- Remove')}  ${buckets.remove.length}`);
-
-  if (buckets.dataResourceReplace.length > 0) {
-    logger.info('');
-    logger.warn('Data-resource Replace (DESTRUCTIVE):');
-    for (const r of buckets.dataResourceReplace) logger.warn(`  ${r.logicalId} (${r.resourceType})`);
-  }
-  printBucket('Add', buckets.add, chalk.green, '+');
-  printBucket('Modify', buckets.modify, chalk.cyan, '~', true);
-  printBucket('Replace', buckets.replace, chalk.yellow, '!');
-  printBucket('Remove', buckets.remove, chalk.red, '-');
-  logger.info('');
-}
-
-function printBucket(label, items, color, marker, showProps = false) {
-  if (items.length === 0) return;
-  logger.info('');
-  logger.info(`${label} (${items.length}):`);
-  for (const r of items) {
-    const props = showProps && r.detailsTargets.length ? ` props=[${r.detailsTargets.join(', ')}]` : '';
-    const repl = r.replacement && r.replacement !== 'False' ? ` replacement=${r.replacement}` : '';
-    logger.info(`  ${color(marker)} ${r.logicalId} (${r.resourceType})${repl}${props}`);
-  }
-}
+import { readFile } from 'node:fs/promises';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { readEnv } from '../lib/rename-compat.js';
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import { loadConfig, resolveStackTags } from '../lib/config.js';
+import { loadProjectConfig, buildLegacyPrefixRegex, buildAnchoredLegacyPrefixRegex, resolveProjectDir } from '../lib/project-config.js';
+import { addPendingChangeset, clearPendingChangeset } from '../lib/session-state.js';
+import { ENVS, isDataResource } from '../lib/constants.js';
+import { loadCfnTemplate, extractExportingOutputKeys, extractLiteralExportNames } from '../lib/cfn-yaml.js';
+import {
+  findRemovedExports,
+  checkExportLock,
+  assertNoFrozenExports,
+  assertNoFrozenTemplateExports,
+} from '../aws/exports.js';
+import {
+  stackStatus,
+  decideChangeSetType,
+  createAndWait,
+  classifyChanges,
+  executeAndPoll,
+} from '../aws/changeset.js';
+
+// Runtime account guard: refuse to deploy when the caller's AWS account does
+// not match the consumer's clawform.config.json `accounts[env]` mapping.
+//
+// Why a separate exported helper:
+//   - Lets tests mock `@aws-sdk/client-sts` and drive the 4 branches
+//     (match, mismatch, no-guard-configured, break-glass) without standing up
+//     the rest of deploy().
+//   - Keeps the deploy() body linear — one call, one place to land the guard.
+//
+// Args:
+//   env             — env string ('d' | 'stg' | 'p').
+//   accounts        — projectCfg.accounts (already loaded by deploy()). May be
+//                     missing, empty, or {env: ''} — all "no guard" cases.
+//   region          — AWS region for the STS client (matches the CFN region).
+//   stsClientFactory — optional override; defaults to a fresh STSClient. Tests
+//                     use vi.mock('@aws-sdk/client-sts') instead and don't need
+//                     this. Kept for callers who want to inject a stub.
+//
+// Resolution order:
+//   1. CLAWFORM_SKIP_ACCOUNT_CHECK=1 → bypass with yellow warning (break-glass).
+//   2. accounts[env] empty / undefined → skip with yellow warning.
+//   3. STS get-caller-identity → compare → throw on mismatch.
+//
+// Throws on mismatch. Resolves with how it concluded — 'verified' (STS ran and
+// matched), 'skipped' (no account configured, non-prod), or 'bypassed'
+// (break-glass env var) — so callers can make the unattended-prod decision.
+export async function assertAccountMatches({ env, accounts, region, stsClientFactory } = {}) {
+  if (readEnv('SKIP_ACCOUNT_CHECK') === '1') {
+    logger.warn(
+      `CLAWFORM_SKIP_ACCOUNT_CHECK=1 — bypassing account-match guard for env '${env}'` +
+      `${env === 'p' ? ' (PRODUCTION)' : ''}. Break-glass only; unset to re-enable.`,
+    );
+    return 'bypassed';
+  }
+  const expectedRaw = accounts && typeof accounts === 'object' ? accounts[env] : undefined;
+  const expected = typeof expectedRaw === 'string' ? expectedRaw.trim() : '';
+  if (!expected) {
+    // Production is the one env where an unset guard is refused rather than
+    // warned past — a p deploy into the wrong account is the exact accident
+    // this check exists for. d/stg stay lenient: an account not yet pinned is
+    // a legitimate bootstrap state.
+    if (env === 'p') {
+      throw new Error(
+        `Env 'p' requires accounts.p in clawform.config.json — a production deploy without ` +
+        `an account guard is refused. Add the 12-digit account id (edit the file or rerun clawform init --force).`,
+      );
+    }
+    logger.warn(`No account guard configured for env '${env}' — skipping account-match check.`);
+    return 'skipped';
+  }
+  const client = stsClientFactory ? stsClientFactory() : new STSClient(region ? { region } : {});
+  const resp = await client.send(new GetCallerIdentityCommand({}));
+  const caller = resp && resp.Account ? String(resp.Account).trim() : '';
+  if (caller !== expected) {
+    throw new Error(
+      `Account mismatch: caller is ${caller || '(unknown)'} but env '${env}' is configured for ${expected} ` +
+      `in clawform.config.json. Refusing to deploy.`,
+    );
+  }
+  return 'verified';
+}
+
+// Unattended production deploys are fine for CI — CodePipeline's manual
+// approval already puts a human in the loop — but only when the account guard
+// genuinely ran and matched. autoApprove combined with a bypassed guard on p
+// would mean nothing checked which account is being written to.
+export function assertProdDeployAllowed({ env, autoApprove, accountCheckMode } = {}) {
+  if (env !== 'p' || !autoApprove) return;
+  if (accountCheckMode !== 'verified') {
+    throw new Error(
+      `--auto-approve is refused for a production deploy unless the account guard verified the ` +
+      `caller (guard was '${accountCheckMode}'). Configure accounts.p and unset CLAWFORM_SKIP_ACCOUNT_CHECK, ` +
+      `or run interactively.`,
+    );
+  }
+}
+
+// C1 (export-lock pre-check): an UPDATE that removes (or un-exports) a live
+// export still imported elsewhere is guaranteed to fail at execute time with
+// "Export ... in use by" and roll back. Detect it BEFORE creating the changeset
+// (all inputs — live Outputs and the template body — exist by then) and hand
+// the operator the two-step migration instead of a wedged stack (rules/limits.md).
+//
+// Fail-open on our own inability to check (parse failure, ListImports denied
+// with no importer seen) — CloudFormation still refuses the real removal if
+// it's genuinely in use. Fail-closed on any confirmed importer, including
+// partial pagination proof (see checkExportLock).
+export async function assertExportLockClear({ client, liveOutputs, templateBody } = {}) {
+  const exportsLive = (liveOutputs ?? []).filter((o) => o && o.ExportName);
+  if (exportsLive.length === 0) return;             // nothing exported → no lock possible
+  const doc = loadCfnTemplate(templateBody);
+  if (!doc) return;                                 // unparseable → linters own the error
+  const removed = findRemovedExports(
+    liveOutputs,
+    extractExportingOutputKeys(doc),
+    extractLiteralExportNames(doc), // same export name under a new OutputKey = moved, not removed
+  );
+  if (removed.length === 0) return;
+  const { blocked, unchecked } = await checkExportLock(client, removed);
+  for (const u of unchecked) {
+    logger.warn(
+      `Could not verify importers for export "${u.exportName}" (${u.error}) — proceeding; ` +
+      `CloudFormation will still refuse the removal if it's in use.`,
+    );
+  }
+  if (blocked.length === 0) return;
+  const lines = blocked.map((b) => `  • ${b.exportName} — imported by: ${b.importers.join(', ')}`);
+  throw new Error(
+    `Export-lock: this update removes ${blocked.length} export(s) still imported by other stack(s):\n` +
+    `${lines.join('\n')}\n` +
+    `CloudFormation will reject the changeset ("Export ... in use by") and roll back. ` +
+    `Use the two-step migration (rules/limits.md):\n` +
+    `  1. Keep the old export; add the new export alongside it and deploy this producer first.\n` +
+    `  2. Migrate each consumer to the new import, deploy them in dependency order, then retire the\n` +
+    `     old export in a final producer deploy once "aws cloudformation list-imports" is empty.`,
+  );
+}
+
+export default async function deploy({ file, env, stackName, project, params, capabilities, autoApprove }) {
+  if (!ENVS.includes(env)) {
+    throw new Error(`Invalid env "${env}". Expected one of: ${ENVS.join(' | ')}`);
+  }
+  if (!stackName) throw new Error('--stack-name is required.');
+  if (!project) throw new Error('--project is required (used as Project tag value).');
+
+  const projectDir = resolveProjectDir();
+  const projectCfg = loadProjectConfig({ projectDir });
+  const legacyRe = buildLegacyPrefixRegex(projectCfg.legacy_prefixes);
+  if (legacyRe && legacyRe.test(stackName)) {
+    const list = projectCfg.legacy_prefixes.map((p) => `${p}-*`).join(', ');
+    throw new Error(
+      `Stack "${stackName}" matches a legacy prefix (${list}) from your clawform.config.json.\n` +
+      `clawform deploy refuses to modify legacy stacks. See rules/legacy-freeze.md and docs/config-schema.md.\n` +
+      `Use raw aws cloudformation CLI with a "# FORCE LEGACY: <reason>" comment if modification is unavoidable.`,
+    );
+  }
+
+  // loadConfig() still gates AWS_PROFILE / AWS_REGION with the friendly error.
+  // OWNER / COST_CENTER are no longer required here — resolveStackTags() owns
+  // the env-var-then-tags_defaults chain and throws with a usable message
+  // when both sources are empty.
+  const cfg = loadConfig({});
+  const stackTags = resolveStackTags(projectCfg, env);
+
+  // Runtime account guard. Runs after loadConfig() so the friendly missing-creds
+  // error fires first; runs before any CFN call so the engineer doesn't have to
+  // wait on a changeset round-trip to discover they're pointed at the wrong AWS
+  // account. See docs/config-schema.md "Wired today" for resolution rules.
+  const accountCheckMode = await assertAccountMatches({
+    env,
+    accounts: projectCfg.accounts,
+    region: cfg.AWS_REGION,
+  });
+  assertProdDeployAllowed({ env, autoApprove, accountCheckMode });
+
+  const templateBody = await readFile(file, 'utf8');
+
+  // C2 introduction gate: refuse a template whose literal Export.Name strings
+  // would CREATE a legacy-prefixed export (covers CREATE deploys too — the
+  // live-outputs gate below only sees exports that already exist). Anchored
+  // regex: the prefix must lead the export name, so legacy tokens mid-name in
+  // convention-compliant exports don't false-positive.
+  const anchoredLegacyRe = buildAnchoredLegacyPrefixRegex(projectCfg.legacy_prefixes);
+  assertNoFrozenTemplateExports({
+    templateExportNames: extractLiteralExportNames(loadCfnTemplate(templateBody)),
+    legacyRe: anchoredLegacyRe,
+    stackName,
+  });
+
+  let parameters = [];
+  if (params) {
+    const raw = await readFile(params, 'utf8');
+    parameters = JSON.parse(raw);
+    if (!Array.isArray(parameters)) {
+      throw new Error(`${params}: expected JSON array of {ParameterKey, ParameterValue}.`);
+    }
+  }
+
+  // Tag key spelling pinned by rules/tagging.md — Env (not Environment), and
+  // the 5 mandatory keys (Project, Env, Owner, CostCenter, ManagedBy). Customer
+  // from resolveStackTags is informational and not emitted as a tag here.
+  const tags = [
+    { Key: 'Project', Value: project },
+    { Key: 'Env', Value: stackTags.Environment },
+    { Key: 'Owner', Value: stackTags.Owner },
+    { Key: 'CostCenter', Value: stackTags.CostCenter },
+    { Key: 'ManagedBy', Value: stackTags.ManagedBy },
+  ];
+
+  const caps = capabilities ? capabilities.split(',').map((s) => s.trim()).filter(Boolean) : [];
+
+  const client = cfnClient();
+  const status = await stackStatus(client, stackName);
+
+  if (status.exists) {
+    // C2: frozen-export gate — refuse a stack emitting legacy-prefixed exports
+    // even when its name doesn't match. Anchored regex (leading segment only).
+    assertNoFrozenExports({ liveOutputs: status.stack?.Outputs, legacyRe: anchoredLegacyRe, stackName });
+
+    // C1: export-lock pre-check. Runs BEFORE the changeset — both inputs (live
+    // Outputs, template body) already exist, and a blocked deploy should not
+    // pay a CreateChangeSet round-trip or leave an orphaned changeset behind.
+    await assertExportLockClear({ client, liveOutputs: status.stack?.Outputs, templateBody });
+  }
+
+  const changeSetType = decideChangeSetType(status);
+  logger.info(`Stack ${stackName}: ${status.exists ? status.status : '(does not exist)'} → ${changeSetType}`);
+
+  logger.step(`Creating change-set on ${stackName}…`);
+  const cs = await createAndWait(client, {
+    stackName,
+    changeSetType,
+    templateBody,
+    parameters,
+    tags,
+    capabilities: caps,
+  });
+
+  if (cs.isEmpty) {
+    logger.ok(`No changes (${cs.statusReason}). Empty change-set deleted.`);
+    return;
+  }
+
+  // In-flight state: the changeset now exists in AWS but hasn't executed. Record
+  // it so that if the operator aborts at the confirm prompt (or runs /clear),
+  // the next session's context hook warns a changeset is sitting unexecuted.
+  // Cleared after execute below. Fail-open — a state-write problem must never
+  // block the deploy.
+  try {
+    addPendingChangeset(projectDir, {
+      stack: stackName,
+      changeSetName: cs.name,
+      env,
+      createdAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    logger.warn(`Could not record pending changeset state (continuing): ${err.message}`);
+  }
+
+  const buckets = classifyChanges(cs.changes);
+  renderChangeTable(buckets);
+
+  const dataRemove = buckets.remove.filter((r) => isDataResource(r.resourceType));
+  const needsRetype = buckets.dataResourceReplace.length > 0 || dataRemove.length > 0;
+
+  if (autoApprove) {
+    if (buckets.replace.length > 0 || needsRetype) {
+      throw new Error('--auto-approve refused: change-set includes Replace or data-resource removal.');
+    }
+    logger.info('Proceeding (--auto-approve, no Replace / data removal).');
+  } else {
+    // Production always earns the retype gate, whatever the changeset holds —
+    // the extra keystroke is the point. Folded into the same prompt as the
+    // data-resource retype so an operator never types the name twice.
+    const prodRetype = env === 'p';
+    if (prodRetype && !needsRetype) {
+      logger.warn(`Production deploy to '${stackName}' — confirm by retyping the stack name.`);
+    }
+    if (needsRetype || prodRetype) {
+      if (buckets.dataResourceReplace.length > 0) {
+        logger.warn(`${buckets.dataResourceReplace.length} data resource(s) will be REPLACED — physical resource recreated.`);
+        // A4 (plain language): spell out the consequence so a non-DevOps operator
+        // understands what "Replace" costs before they retype the stack name.
+        logger.warn('  In plain terms: a brand-new resource is created and the old one is destroyed. Live data');
+        logger.warn('  on the old resource is NOT migrated — it survives only as a snapshot if DeletionPolicy/');
+        logger.warn('  UpdateReplacePolicy is Snapshot (RDS/Aurora) or Retain. Verify that before continuing.');
+      }
+      if (dataRemove.length > 0) {
+        logger.warn(`${dataRemove.length} data resource(s) will be REMOVED from the stack — physical fate depends on DeletionPolicy (change-set does not expose it).`);
+        for (const r of dataRemove) logger.warn(`  ${r.logicalId} (${r.resourceType})`);
+        logger.warn('  In plain terms: CloudFormation stops managing these. If DeletionPolicy is Retain/Snapshot the');
+        logger.warn('  underlying data survives; otherwise it is deleted. Confirm the policy before continuing.');
+      }
+      const { typed } = await inquirer.prompt([{
+        type: 'input',
+        name: 'typed',
+        message: `Type the stack name EXACTLY to confirm:`,
+        validate: (v) => v.trim() === stackName ? true : `Type "${stackName}" exactly.`,
+      }]);
+      if (typed.trim() !== stackName) throw new Error('Aborted: stack name did not match.');
+    }
+    const { ok } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'ok',
+      message: `Execute change-set ${cs.name} on ${stackName}?`,
+      default: false,
+    }]);
+    if (!ok) {
+      logger.warn('Aborted by user. Change-set kept (delete via AWS console or rerun).');
+      return;
+    }
+  }
+
+  logger.step(`Executing change-set ${cs.name}…`);
+  const result = await executeAndPoll(client, {
+    stackName,
+    changeSetName: cs.name,
+    onEvent: (ev) => {
+      const color = EVENT_COLOR[ev.ResourceStatus] ?? ((s) => s);
+      const reason = ev.ResourceStatusReason ? ` ${chalk.gray('—')} ${ev.ResourceStatusReason}` : '';
+      logger.info(`  ${(ev.LogicalResourceId ?? '').padEnd(30)} ${color(ev.ResourceStatus)}${reason}`);
+    },
+  });
+
+  // The changeset has been executed (success or failure) — no longer pending.
+  try {
+    clearPendingChangeset(projectDir, { stack: stackName, changeSetName: cs.name });
+  } catch { /* fail-open — never let a state-write problem mask the deploy result */ }
+
+  if (/COMPLETE$/.test(result.stackStatus) && !/ROLLBACK/.test(result.stackStatus)) {
+    logger.ok(`Stack ${stackName} → ${result.stackStatus}`);
+    const outs = result.stack?.Outputs ?? [];
+    if (outs.length) {
+      logger.info('Outputs:');
+      for (const o of outs) {
+        logger.info(`  ${(o.OutputKey ?? '').padEnd(30)} = ${o.OutputValue ?? ''}`);
+      }
+      highlightEndpoints(outs);
+    }
+  } else {
+    logger.error(`Stack ${stackName} → ${result.stackStatus}. Use /rollback to investigate.`);
+    process.exit(1);
+  }
+}
+
+// D2 (post-deploy verification): a clean COMPLETE means CloudFormation finished,
+// not that the app works. Surface endpoint-like outputs so the operator has
+// something concrete to hit before calling the deploy done. Heuristic on the
+// OutputKey name — intentionally loose; a false highlight costs nothing.
+// Keep in sync with the canonical export suffixes in rules/cfn-standards.md
+// (-id, -arn, -name, -dns, -uri) — 'uri' in particular is the convention's own
+// endpoint suffix.
+const ENDPOINT_KEY_RE = /(url|uri|endpoint|dns|domain|address|hostname|fqdn)/i;
+
+export function highlightEndpoints(outs) {
+  const endpoints = (outs ?? []).filter((o) => ENDPOINT_KEY_RE.test(o.OutputKey ?? '') && o.OutputValue);
+  if (endpoints.length === 0) return;
+  logger.info('');
+  logger.info('Endpoints to verify:');
+  for (const o of endpoints) logger.info(`  ${chalk.cyan(o.OutputValue)}  ${chalk.gray(`(${o.OutputKey})`)}`);
+  logger.info(chalk.gray('A clean stack status means CloudFormation finished — confirm each endpoint actually responds before considering the deploy done.'));
+}
+
+const EVENT_COLOR = {
+  CREATE_COMPLETE: chalk.green,
+  UPDATE_COMPLETE: chalk.green,
+  CREATE_IN_PROGRESS: chalk.cyan,
+  UPDATE_IN_PROGRESS: chalk.cyan,
+  DELETE_COMPLETE: chalk.gray,
+  DELETE_IN_PROGRESS: chalk.gray,
+  CREATE_FAILED: chalk.red,
+  UPDATE_FAILED: chalk.red,
+  DELETE_FAILED: chalk.red,
+  ROLLBACK_IN_PROGRESS: chalk.yellow,
+  ROLLBACK_COMPLETE: chalk.yellow,
+};
+
+function renderChangeTable(buckets) {
+  logger.info('');
+  logger.info('Change-set summary:');
+  logger.info(`  ${chalk.green('+ Add')}     ${buckets.add.length}`);
+  logger.info(`  ${chalk.cyan('~ Modify')}  ${buckets.modify.length}`);
+  logger.info(`  ${chalk.yellow('! Replace')} ${buckets.replace.length}`);
+  logger.info(`  ${chalk.red('- Remove')}  ${buckets.remove.length}`);
+
+  if (buckets.dataResourceReplace.length > 0) {
+    logger.info('');
+    logger.warn('Data-resource Replace (DESTRUCTIVE):');
+    for (const r of buckets.dataResourceReplace) logger.warn(`  ${r.logicalId} (${r.resourceType})`);
+  }
+  printBucket('Add', buckets.add, chalk.green, '+');
+  printBucket('Modify', buckets.modify, chalk.cyan, '~', true);
+  printBucket('Replace', buckets.replace, chalk.yellow, '!');
+  printBucket('Remove', buckets.remove, chalk.red, '-');
+  logger.info('');
+}
+
+function printBucket(label, items, color, marker, showProps = false) {
+  if (items.length === 0) return;
+  logger.info('');
+  logger.info(`${label} (${items.length}):`);
+  for (const r of items) {
+    const props = showProps && r.detailsTargets.length ? ` props=[${r.detailsTargets.join(', ')}]` : '';
+    const repl = r.replacement && r.replacement !== 'False' ? ` replacement=${r.replacement}` : '';
+    logger.info(`  ${color(marker)} ${r.logicalId} (${r.resourceType})${repl}${props}`);
+  }
+}