@thejoseki/clawform 0.0.1 → 2.2.1

package/src/commands/sync.js

@@ -0,0 +1,53 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../lib/logger.js';
+import { loadConfig } from '../lib/config.js';
+import { loadProjectConfig, resolveProjectDir } from '../lib/project-config.js';
+import { cfnClient } from '../lib/aws-client.js';
+import { fetchExports, groupExports, renderCatalog } from '../aws/catalog.js';
+import { fetchStacks, classifyStacks, renderInventory } from '../aws/inventory.js';
+import { ensureWorkflowInstalled } from '../lib/install-workflow.js';
+import { CATALOG_DIR_REL } from '../lib/constants.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export default async function sync(opts = {}) {
+  await assertLicensed({ command: 'sync', client: resolveLicenseClient() });
+  const cfg = loadConfig(opts);
+  logger.step('clawform sync — refresh catalog + inventory');
+  logger.info(`Profile: ${cfg.AWS_PROFILE}   Region: ${cfg.AWS_REGION}`);
+  const client = cfnClient(opts);
+
+  const meta = {
+    generatedAt: new Date().toISOString(),
+    account: cfg.ACCOUNT_DEV || '(unknown)',
+    region: cfg.AWS_REGION,
+  };
+
+  logger.info('Fetching exports + stacks in parallel…');
+  const [exports, stacks] = await Promise.all([fetchExports(client), fetchStacks(client)]);
+  logger.ok(`Got ${exports.length} exports, ${stacks.length} active stacks`);
+
+  const projectDir = resolveProjectDir();
+  const catalogDir = join(projectDir, CATALOG_DIR_REL);
+  const projectCfg = loadProjectConfig({ projectDir });
+  const catalogMd = renderCatalog(groupExports(exports), { ...meta, total: exports.length });
+  const classified = classifyStacks(stacks, new Date(), projectCfg.legacy_prefixes);
+  const inventoryMd = renderInventory(classified, meta);
+
+  await mkdir(catalogDir, { recursive: true });
+  await writeFile(join(catalogDir, 'outputs-catalog.md'), catalogMd);
+  await writeFile(join(catalogDir, 'stacks-inventory.md'), inventoryMd);
+  logger.ok(`${CATALOG_DIR_REL}/outputs-catalog.md  (${exports.length} exports)`);
+  logger.ok(
+    `${CATALOG_DIR_REL}/stacks-inventory.md  (legacy=${classified.legacy.length}, serverless=${classified.serverless.length}, active=${classified.active.length}, stale=${classified.stale.length})`,
+  );
+
+  const workflowResult = ensureWorkflowInstalled({ repoRoot: REPO_ROOT, projectDir });
+  if (workflowResult.installed) {
+    logger.ok('.claude/workflows/audit-all-stacks.js installed — invoke it via `/workflows` or `/audit-all-stacks`');
+  }
+}

package/src/commands/validate.js

@@ -0,0 +1,349 @@
+import { readFile, writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+import { execa } from 'execa';
+import { ValidateTemplateCommand } from '@aws-sdk/client-cloudformation';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import {
+  loadOverrides,
+  filterExpired,
+  injectSuppressions,
+  detectUnauthorizedSuppressions,
+} from '../lib/lint-overrides.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const LINT_LEVEL = { Error: 'E', Warning: 'W', Informational: 'I' };
+const OVERRIDES_PATH = join(process.cwd(), 'rules', 'lint-overrides.md');
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// cfn-guard rules ship with the clawform package. A consumer project that
+// installed clawform (plugin cache / node_modules) has no `rules.guard/` in
+// cwd — resolving relative to cwd used to make cfn-guard exit non-zero
+// ("missing rules dir"), which was counted as a CRITICAL and failed every
+// validate for exactly the installed-plugin case. Resolve from the package
+// root; a project-local `rules.guard/` (consumer-authored rules) wins when
+// present so consumers can extend without forking.
+export function resolveGuardRulesDir({ cwd = process.cwd(), pkgRoot = PKG_ROOT } = {}) {
+  const local = join(cwd, 'rules.guard');
+  if (existsSync(local)) return local;
+  return join(pkgRoot, 'rules.guard');
+}
+
+export default async function validate({ file, skipAws = false }) {
+  await assertLicensed({ command: 'validate', client: resolveLicenseClient() });
+  logger.step(`clawform validate ${file}`);
+  const body = await readFile(file, 'utf8');
+
+  const lint = await runCfnLint(file);
+  const nag = await runCfnNag(file);
+
+  // Wave 3 overrides hook: load the audited allowlist, partition expired,
+  // inject active suppressions into a temp copy for cfn-guard, then run the
+  // anti-rot check against the ORIGINAL template (inline suppressions without
+  // an overrides row are folded into the critical count and gate /deploy).
+  const overrides = loadOverrides(OVERRIDES_PATH);
+  const { active, expired } = filterExpired(overrides, new Date());
+  for (const e of expired) {
+    logger.warn(
+      `lint-override expired ${e.ruleId} (scope=${e.scopeGlob}, expired ${e.expires.toISOString().slice(0, 10)}). ` +
+      `Re-evaluate in rules/lint-overrides.md or remove the row.`,
+    );
+  }
+
+  const { guard, unauthorized } = await runCfnGuardWithOverrides(file, body, active);
+
+  for (const u of unauthorized) {
+    logger.error(`unauthorized inline SuppressedRules: ${u.resourceId} suppresses ${u.ruleId} with no rules/lint-overrides.md row`);
+  }
+
+  const aws = skipAws ? null : await runValidateTemplate(body);
+
+  const critical =
+    (lint?.errors ?? 0) + (nag?.failures ?? 0) + (guard?.failures ?? 0) + (aws?.errors ?? 0)
+    + unauthorized.length;
+  const warnings = (lint?.warnings ?? 0) + (nag?.warnings ?? 0) + (guard?.warnings ?? 0);
+  // A "skipped" tool contributes 0 errors AND 0 warnings under nullish-coalescing —
+  // before this gate, a fresh dev box with no cfn-lint / cfn-nag installed would
+  // print "All checks passed" exit 0 even though the only thing that ran was the
+  // shallow CloudFormation ValidateTemplate. That silently bypasses every Layer-2
+  // rule the rule files promise (W11/W12/F2/W2/W9/W35/W74/W2001/...).
+  const skipped = [
+    lint?.skipped ? 'cfn-lint' : null,
+    nag?.skipped ? 'cfn-nag' : null,
+    guard?.skipped ? 'cfn-guard' : null,
+    !aws ? 'ValidateTemplate (--skip-aws)' : null,
+  ].filter(Boolean);
+
+  logger.info('');
+  logger.info('Summary:');
+  logger.info(`  cfn-lint       ${formatCount(lint)}`);
+  logger.info(`  cfn-nag        ${formatCount(nag)}`);
+  logger.info(`  cfn-guard      ${formatCount(guard)}`);
+  logger.info(`  ValidateTemplate ${formatCount(aws)}`);
+  // Surface unauthorized inline suppressions in the Summary so a clean
+  // lint/nag/guard run still gives the user a visible cause for exit 1.
+  logger.info(`  lint-overrides ${unauthorized.length === 0 ? '✓ clean' : `🔴 ${unauthorized.length} unauthorized suppression(s)`}`);
+
+  if (critical > 0) {
+    logger.error(`${critical} CRITICAL finding(s). Fix before /deploy.`);
+    process.exit(1);
+  } else if (warnings > 0) {
+    logger.warn(`${warnings} warning(s). Review then proceed.`);
+  } else if (skipped.length > 0) {
+    // Don't print "All checks passed" when we didn't actually run every check.
+    logger.warn(
+      `Partial pass — ${skipped.length} tool(s) skipped: ${skipped.join(', ')}. ` +
+      `Install missing tools (pip install cfn-lint / gem install cfn-nag / cargo install cfn-guard --locked) before relying on this as a deploy gate.`,
+    );
+  } else {
+    logger.ok('All checks passed.');
+  }
+}
+
+function formatCount(r) {
+  if (!r) return '⊘ skipped';
+  if (r.skipped) return `⊘ skipped (${r.skipReason})`;
+  const e = r.errors ?? r.failures ?? 0;
+  const w = r.warnings ?? 0;
+  if (e === 0 && w === 0) return '✓ clean';
+  return `${e ? '🔴' : '🟡'} ${e} error(s), ${w} warning(s)`;
+}
+
+// Exported for unit tests (validate-runners.test.js). The default export is
+// still the orchestrator — these helpers stay internal to validate(), but the
+// runner tests need to drive them directly with a mocked execa.
+export async function runCfnLint(file) {
+  const result = await execa('cfn-lint', ['--format', 'json', file], { reject: false });
+  if (toolMissing(result)) {
+    logger.warn('cfn-lint not found. Install: pip install cfn-lint');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // M4 — cfn-lint exits non-zero on rule-engine errors (bad template path,
+  // unrecognized flag, broken plugin). Previously we fell through to JSON.parse
+  // and either crashed (M5) or silently returned 0/0. Surface a real error so
+  // /deploy is gated. cfn-lint ALSO exits non-zero when it just found
+  // findings — those are handled below via parsed JSON, so we only fail loud
+  // when stdout has no parseable findings AND stderr looks like a tool error.
+  // Empty stdout is valid (no findings) — short-circuit before the JSON path.
+  if (!stdout.trim()) {
+    if (result.failed && stderr.trim()) {
+      const firstLine = stderr.split(/\r?\n/)[0].trim();
+      return { errors: 1, warnings: 0, message: `cfn-lint exited non-zero: ${firstLine}` };
+    }
+    return { errors: 0, warnings: 0 };
+  }
+
+  // M5 — guard JSON.parse so a malformed stdout (rule-engine crashed mid-output,
+  // or cfn-lint printed a non-JSON banner) surfaces as a finding rather than
+  // crashing the whole validate command.
+  let findings;
+  try {
+    findings = JSON.parse(stdout);
+  } catch {
+    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
+    return {
+      errors: 1,
+      warnings: 0,
+      message: `cfn-lint returned non-JSON output (length ${stdout.length}): ${preview}`,
+    };
+  }
+  // P1 — JSON.parse can succeed on shapes that aren't a findings array
+  // (e.g. cfn-lint plugin returning `{ "error": "..." }`, or stdout being
+  // a bare `null`/string/number from a wrapped script). Surface as a
+  // warning so /deploy is not silently gated on a shape we can't iterate.
+  if (!Array.isArray(findings)) {
+    logger.warn(`cfn-lint returned unexpected JSON shape: ${typeof findings}`);
+    return { errors: 0, warnings: 1 };
+  }
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    const lvl = LINT_LEVEL[f.Level] ?? 'I';
+    if (lvl === 'E') {
+      errors++;
+      logger.error(`cfn-lint ${f.Rule?.Id ?? ''} ${f.Location?.Start ? `L${f.Location.Start.LineNumber}` : ''}: ${f.Message}`);
+    } else if (lvl === 'W') {
+      warnings++;
+      logger.warn(`cfn-lint ${f.Rule?.Id ?? ''}: ${f.Message}`);
+    }
+  }
+  return { errors, warnings };
+}
+
+export async function runCfnNag(file) {
+  const cmd = process.platform === 'win32' ? 'cfn_nag_scan.bat' : 'cfn_nag_scan';
+  // P3 — use the short form `-o json` for the output-format flag. Both `-o`
+  // and `--output-format` are valid cfn-nag flags, but the test suite asserts
+  // the short form so that a future refactor doesn't silently drop into
+  // cfn-nag's default text output (which would trip the M5 JSON.parse catch
+  // as a false-positive critical finding on every run).
+  const result = await execa(cmd, ['--input-path', file, '-o', 'json'], { reject: false });
+  if (toolMissing(result)) {
+    logger.warn('cfn-nag not found. Install: gem install cfn-nag');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // M4 — cfn-nag exits non-zero when violations are found AND when the tool
+  // itself fails (broken ruby env, malformed template path). cfn-nag with no
+  // findings emits a JSON array, so empty stdout typically means the tool
+  // crashed before producing output — surface that loudly instead of masking
+  // it as failures: 0.
+  if (!stdout.trim()) {
+    if (result.failed && stderr.trim()) {
+      const firstLine = stderr.split(/\r?\n/)[0].trim();
+      return { failures: 1, warnings: 0, message: `cfn-nag exited non-zero: ${firstLine}` };
+    }
+    // P2 — exit 0 with empty stdout is suspicious: even a clean cfn-nag run
+    // emits `[]` (or the per-file JSON array). True empty stdout usually means
+    // a wrapper/redirect ate the output. Emit an observability nudge but
+    // don't false-fail — we already know the tool exited clean.
+    logger.warn('cfn-nag produced no output (expected JSON findings array, empty)');
+    return { failures: 0, warnings: 0 };
+  }
+
+  // M5 — guard JSON.parse so a malformed stdout (ruby stack-trace, banner
+  // text from a flag mismatch) surfaces as a finding rather than crashing
+  // the whole validate command.
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
+    return {
+      failures: 1,
+      warnings: 0,
+      message: `cfn-nag returned non-JSON output (length ${stdout.length}): ${preview}`,
+    };
+  }
+  // P1 — even with successful JSON parse, the shape must be the per-file
+  // findings array. cfn-nag has historically returned `{ "violations": [...] }`
+  // in some wrappers and a bare object in error cases; either crashes the
+  // for..of below. Surface as a warning instead of an unhandled TypeError.
+  if (!Array.isArray(parsed)) {
+    logger.warn(`cfn-nag returned unexpected JSON shape: ${typeof parsed}`);
+    return { failures: 0, warnings: 1 };
+  }
+  let failures = 0;
+  let warnings = 0;
+  for (const entry of parsed) {
+    for (const v of entry.file_results?.violations ?? []) {
+      if (v.type === 'FAIL') {
+        failures++;
+        logger.error(`cfn-nag ${v.id}: ${v.message} (${v.logical_resource_ids?.join(', ') ?? ''})`);
+      } else if (v.type === 'WARN') {
+        warnings++;
+        logger.warn(`cfn-nag ${v.id}: ${v.message}`);
+      }
+    }
+  }
+  return { failures, warnings };
+}
+
+// Wraps runCfnGuard with the Wave 3 overrides flow: when there are no active
+// overrides, run cfn-guard against the original file (preserves the test
+// surface of runCfnGuard). When there are, write the injected copy to a
+// tmpdir and run cfn-guard against that temp path; clean up regardless.
+// Also runs the anti-rot detector against the ORIGINAL template body.
+async function runCfnGuardWithOverrides(file, body, activeOverrides) {
+  const unauthorized = detectUnauthorizedSuppressions(body, activeOverrides);
+  if (activeOverrides.length === 0) {
+    return { guard: await runCfnGuard(file), unauthorized };
+  }
+  const injected = injectSuppressions(body, activeOverrides);
+  const dir = await mkdtemp(join(tmpdir(), 'clawform-validate-'));
+  const tempPath = join(dir, 'template.yaml');
+  try {
+    await writeFile(tempPath, injected, 'utf8');
+    const guard = await runCfnGuard(tempPath);
+    return { guard, unauthorized };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function runCfnGuard(file) {
+  // Probe for the binary first so a missing install yields a clean "skipped"
+  // instead of confusing rule-engine output.
+  const probe = await execa('cfn-guard', ['--version'], { reject: false });
+  if (toolMissing(probe)) {
+    logger.warn('cfn-guard not found. Install: cargo install cfn-guard --locked');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+
+  const result = await execa(
+    'cfn-guard',
+    [
+      'validate',
+      '-d',
+      file,
+      '-r',
+      resolveGuardRulesDir(),
+      '--show-summary',
+      'all',
+      '--output-format',
+      'single-line-summary',
+    ],
+    { reject: false },
+  );
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // cfn-guard exits non-zero when any rule fails. Each failing rule line is
+  // surfaced as a critical finding; cfn-guard 3.x does not have a "warning"
+  // severity, so everything that fires is counted as a failure.
+  let failures = 0;
+  const warnings = 0;
+  if (result.exitCode !== 0) {
+    const lines = stdout.split(/\r?\n/).filter((l) => l.trim());
+    for (const line of lines) {
+      // single-line-summary emits one line per rule outcome; only count FAIL.
+      if (/\bFAIL\b/i.test(line) || /Status\s*=\s*FAIL/i.test(line)) {
+        failures++;
+        logger.error(`cfn-guard ${line.trim()}`);
+      }
+    }
+    if (failures === 0) {
+      // Non-zero exit but no parseable FAIL line — surface raw output so the
+      // user can debug rule-engine errors (bad rule syntax, missing rules dir).
+      failures = 1;
+      logger.error(`cfn-guard: ${stderr.trim() || stdout.trim() || 'non-zero exit'}`);
+    }
+  }
+  return { failures, warnings };
+}
+
+function toolMissing(r) {
+  if (!r.failed) return false;
+  const stderr = r.stderr ?? '';
+  const msg = r.shortMessage ?? r.message ?? '';
+  // Linux/Mac: spawn ENOENT. Windows cmd: "is not recognized as an internal or external command".
+  return r.code === 'ENOENT'
+    || r.errno === -2
+    || /\bENOENT\b/i.test(msg)
+    || /is not recognized as an internal or external command/i.test(stderr)
+    || /command not found/i.test(stderr);
+}
+
+async function runValidateTemplate(body) {
+  try {
+    const client = cfnClient();
+    const out = await client.send(new ValidateTemplateCommand({ TemplateBody: body }));
+    if (out.Capabilities?.length) {
+      logger.info(`Template requires capabilities: ${out.Capabilities.join(', ')} — pass via --capabilities on deploy.`);
+    }
+    return { errors: 0, warnings: 0 };
+  } catch (err) {
+    logger.error(`ValidateTemplate: ${err.message}`);
+    return { errors: 1, warnings: 0 };
+  }
+}

package/src/hooks/block-dangerous-eval.js

@@ -0,0 +1,160 @@
+import { LEGACY_OVERRIDE_PHRASE } from '../lib/constants.js';
+import { buildLegacyPrefixRegex } from '../lib/project-config.js';
+
+// Running a script file hands the guard an opaque blob: the commands inside
+// were written elsewhere and cannot be inspected. Warn rather than block —
+// blocking every `bash x.sh` would refuse ordinary build scripts in any
+// project, and a guard people switch off protects nothing.
+const OPAQUE_SCRIPT_RE = /\b(?:ba|z)?sh\s+(?!-)[^\s;&|]*\.sh\b/i;
+
+const MODIFYING_VERBS = /\b(update-stack|create-stack|create-change-set|execute-change-set|delete-stack|set-stack-policy|update-termination-protection|continue-update-rollback)\b/;
+
+// MCP tool surface from `awslabs.aws-api-mcp-server`. Two naming forms:
+//   standalone server:  mcp__<server-key>__<tool>            e.g. mcp__aws-api-mcp-server__call_aws
+//   plugin-bundled:     mcp__plugin_<plugin>_<server>__<tool>
+// Wildcard covers both. Only `call_aws` mutates AWS; `suggest_aws_commands` is
+// read-only LLM text generation and not intercepted.
+//
+// This is the AUTHORITATIVE gate: the PreToolUse matcher in hooks/hooks.json
+// ("mcp__.*__call_aws") only decides which events get routed here; this regex
+// re-checks the routed event so a too-broad matcher still fails safe.
+const MCP_CALL_AWS_RE = /^mcp__.+__call_aws$/;
+
+// Built-in blockers — always fire, regardless of consumer config. These are Clawform's
+// invariant convictions, not customer-specific data.
+const BUILTIN_BLOCKERS = [
+  {
+    hit: (c) => /\baws\s+cloudformation\s+delete-stack\b/i.test(c),
+    reason:
+      'Direct `aws cloudformation delete-stack` is blocked by Clawform. ' +
+      'Use the `/rollback` slash command (it inspects retained data resources first).',
+  },
+  {
+    hit: (c) => /\baws\s+s3\s+rb\b.*--force\b/i.test(c),
+    reason: 'Force-deleting S3 buckets is blocked. Empty + delete via the bucket\'s CloudFormation stack instead.',
+  },
+  // Destructive service-level deletes below bypass the stack lifecycle — and
+  // with it DeletionPolicy, changesets, and the confirm flow. Single-object /
+  // reversible variants (s3 rm of one key, delete-secret with its recovery
+  // window, kms disable-key, ec2 stop-instances) stay allowed.
+  {
+    hit: (c) => /\baws\s+s3\s+rm\b(?=.*--recursive\b)/i.test(c),
+    reason:
+      'Recursive S3 delete is blocked (same blast radius as `s3 rb --force`). ' +
+      'Manage the bucket through its CloudFormation stack; single-object `aws s3 rm` is allowed.',
+  },
+  {
+    hit: (c) => /\baws\s+rds\s+delete-db-(instance|cluster)\b/i.test(c),
+    reason:
+      'Deleting RDS instances/clusters directly is blocked — it sidesteps the stack\'s ' +
+      'DeletionPolicy/snapshot handling. Retire the resource through its CloudFormation stack (/rollback for stuck stacks).',
+  },
+  {
+    hit: (c) => /\baws\s+dynamodb\s+delete-table\b/i.test(c),
+    reason:
+      'Deleting DynamoDB tables directly is blocked. Remove the table through its ' +
+      'CloudFormation stack so DeletionPolicy applies; item-level deletes are allowed.',
+  },
+  {
+    hit: (c) => /\baws\s+secretsmanager\s+delete-secret\b(?=.*--force-delete-without-recovery\b)/i.test(c),
+    reason:
+      'Force-deleting a secret skips the 7-30 day recovery window. Plain `delete-secret` ' +
+      '(recoverable) is allowed; permanent removal goes through the secret\'s CloudFormation stack.',
+  },
+  {
+    hit: (c) => /\baws\s+kms\s+schedule-key-deletion\b/i.test(c),
+    reason:
+      'Scheduling KMS key deletion is blocked — everything encrypted under the key dies with it. ' +
+      'Use `kms disable-key` to take it out of service, and retire keys through their CloudFormation stack.',
+  },
+  {
+    hit: (c) => /\baws\s+ec2\s+terminate-instances\b/i.test(c),
+    reason:
+      'Terminating EC2 instances directly is blocked — stack-managed instances must go through ' +
+      'their CloudFormation stack. `ec2 stop-instances` is allowed.',
+  },
+  {
+    // Every iam delete-* subcommand: identity plumbing a stack created should
+    // die with its stack. Reads and reversible detach/remove stay allowed.
+    hit: (c) => /\baws\s+iam\s+delete-[a-z-]+/i.test(c),
+    reason:
+      'Deleting IAM resources directly is blocked — roles/policies/users a CloudFormation stack ' +
+      'created must be removed through that stack. Reads and `iam detach-*` are allowed.',
+  },
+  {
+    // The same destructive operations reached through an SDK instead of the
+    // CLI — boto3's delete_stack, the JS client's deleteStack, and friends.
+    // The parenthesis is what distinguishes a call from prose mentioning it.
+    hit: (c) => /\b(delete_stack|delete_db_instance|delete_db_cluster|delete_table|schedule_key_deletion|deleteStack|deleteDBInstance|deleteDBCluster|deleteTable|scheduleKeyDeletion)\s*\(/.test(c),
+    reason:
+      'Destructive AWS SDK calls are blocked for the same reason as the CLI equivalents — ' +
+      'they bypass the stack lifecycle. Remove the resource through its CloudFormation stack.',
+  },
+  {
+    hit: (c) => /\baws\s+s3api\s+delete-bucket\b/i.test(c),
+    reason:
+      'Deleting S3 buckets via s3api is blocked (same rule as `s3 rb`). Remove the bucket ' +
+      'through its CloudFormation stack; object-level `s3api delete-object` is allowed.',
+  },
+];
+
+/**
+ * Pure evaluator for the PreToolUse hook. Returns { block, reason? }.
+ *
+ * @param event   PreToolUse event from Claude Code (Bash or mcp__*__call_aws).
+ * @param config  { legacyPrefixes: string[] } — the consumer's frozen-prefix list.
+ *                Defaults to [] so existing built-in-blocker tests don't need rewiring
+ *                and so a consumer with no clawform.config.json still gets the built-ins.
+ */
+export function evaluate(event, config = {}) {
+  const legacyPrefixes = Array.isArray(config.legacyPrefixes) ? config.legacyPrefixes : [];
+  const legacyRe = buildLegacyPrefixRegex(legacyPrefixes);
+  const legacyDocList = legacyPrefixes.map((p) => `${p}-*`).join(', ');
+
+  const commands = extractCommands(event);
+  let opaque = null;
+  for (const cmd of commands) {
+    for (const b of BUILTIN_BLOCKERS) {
+      if (b.hit(cmd)) return { block: true, reason: b.reason };
+    }
+    // Remembered, not returned yet: a block found on a later command must win
+    // over a warning found on an earlier one.
+    if (!opaque && OPAQUE_SCRIPT_RE.test(cmd)) opaque = cmd;
+    if (legacyRe && MODIFYING_VERBS.test(cmd) && legacyRe.test(cmd) && !LEGACY_OVERRIDE_PHRASE.test(cmd)) {
+      return {
+        block: true,
+        reason:
+          `Modify on a legacy stack (${legacyDocList}) detected — frozen by your clawform.config.json legacy_prefixes list ` +
+          '(see rules/legacy-freeze.md and docs/config-schema.md). ' +
+          'Read-only commands (describe-*, list-*) are fine. To override, prefix the command with `# FORCE LEGACY: <reason>` on its own line.',
+      };
+    }
+  }
+
+  if (opaque) {
+    return {
+      block: false,
+      warn: true,
+      reason:
+        `Clawform cannot read the contents of the script in "${opaque.trim()}" — commands inside a ` +
+        'script file are invisible to this guard. Review it before letting the agent run it. ' +
+        '(The guard inspects commands it can see; it is a deterrent, not a sandbox.)',
+    };
+  }
+  return { block: false };
+}
+
+function extractCommands(event) {
+  const toolName = event?.tool_name;
+  if (toolName === 'Bash') {
+    const c = event?.tool_input?.command;
+    return typeof c === 'string' ? [c] : [];
+  }
+  if (typeof toolName === 'string' && MCP_CALL_AWS_RE.test(toolName)) {
+    const c = event?.tool_input?.cli_command;
+    if (typeof c === 'string') return [c];
+    if (Array.isArray(c)) return c.filter((x) => typeof x === 'string');
+    return [];
+  }
+  return [];
+}

package/src/hooks/block-dangerous.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Clawform PreToolUse hook — CLI entry. Reads JSON event from stdin, resolves
+ * the consumer's project root from the EVENT's `cwd` field (Claude Code sets
+ * this on every hook event), and delegates to the pure `evaluate` in
+ * block-dangerous-eval.js. Exits 2 with stderr on block.
+ *
+ * Why `event.cwd` instead of `process.env.CLAUDE_PROJECT_DIR`: the Claude Code
+ * hook docs (anthropic.com/docs/claude-code/hooks) document `cwd` as part of
+ * the stdin event payload but make no guarantee about CLAUDE_PROJECT_DIR being
+ * set in the hook process env, particularly when the hook is registered via a
+ * plugin's `hooks.json` (where `${CLAUDE_PLUGIN_ROOT}` substitutes into the
+ * command path but the runtime env is undocumented). Relying on the env var
+ * here risks a non-Acme consumer silently inheriting THIS repo's dogfood config
+ * — exactly the security bug the composable refactor exists to prevent.
+ * Fallback: process.env.CLAUDE_PROJECT_DIR → process.cwd() (the latter is
+ * useful for dev-mode invocations from the repo root).
+ *
+ * Fail-LOUD on event-parse error → write to stderr + exit 0 so a buggy hook
+ * never silently disables the safety net (the alternative — fail closed —
+ * would deny every Bash call on any unrelated parse problem).
+ *
+ * Fail-LOUD on config-load error → write to stderr + continue with an empty
+ * legacy-prefix list. Built-in blockers (delete-stack, s3 rb --force) still
+ * fire; only the legacy-freeze gate is dropped, which is the correct outcome
+ * when the consumer's clawform.config.json is broken or missing.
+ */
+
+import { readFileSync } from 'node:fs';
+import { evaluate } from './block-dangerous-eval.js';
+import { loadProjectConfig } from '../lib/project-config.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform hook] event parse failed (allowing tool call): ${err.message}\n`);
+  process.exit(0);
+}
+
+const projectDir = (typeof event?.cwd === 'string' && event.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+let legacyPrefixes = [];
+try {
+  const cfg = loadProjectConfig({ projectDir });
+  legacyPrefixes = cfg.legacy_prefixes || [];
+} catch (err) {
+  process.stderr.write(`[clawform hook] consumer config load failed at ${projectDir} (legacy-freeze gate disabled, built-ins still fire): ${err.message}\n`);
+}
+
+const { block, warn, reason } = evaluate(event, { legacyPrefixes });
+if (block) {
+  process.stderr.write(`[clawform hook] ${reason}\n`);
+  process.exit(2);
+}
+
+// Advisory: the command runs, but the operator is told what the guard could
+// not see. Same posture as the catalog-freshness hook.
+if (warn) {
+  process.stderr.write(`[clawform hook] ${reason}\n`);
+  process.exit(0);
+}

package/src/hooks/cfn-lint-after-edit-eval.js

@@ -0,0 +1,30 @@
+// Pure decision logic for the PostToolUse cfn-lint hook. Given a
+// PostToolUse event, returns { lint, file?, reason? } so the CLI shim
+// knows whether (and on which file) to spawn cfn-lint. Exported separately
+// so unit tests don't need to spawn anything.
+//
+// Trigger rules (intentionally narrow — we don't want to lint every YAML
+// the user touches):
+//   tool_name ∈ {Edit, Write, MultiEdit}
+//   tool_input.file_path is a string ending in .yaml or .yml
+//   the path contains a `cfn/` or `templates/` segment (path-separator agnostic)
+//
+// The path-segment check is what makes the hook safe to ship as a global
+// PostToolUse matcher: editing some-other-product/serverless.yaml elsewhere
+// won't trip cfn-lint just because it's a YAML file.
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+const YAML_RE = /\.ya?ml$/i;
+// `[/\\]` covers POSIX and Windows separators; `(^|...)` matches either an
+// initial segment or a sub-segment. `(?=[/\\])` ensures it's a directory.
+const CFN_DIR_RE = /(^|[/\\])(cfn|templates)(?=[/\\])/i;
+
+export function shouldLint(event) {
+  const toolName = event?.tool_name;
+  if (!EDIT_TOOLS.has(toolName)) return { lint: false };
+  const file = event?.tool_input?.file_path;
+  if (typeof file !== 'string') return { lint: false };
+  if (!YAML_RE.test(file)) return { lint: false };
+  if (!CFN_DIR_RE.test(file)) return { lint: false };
+  return { lint: true, file };
+}