@thejoseki/clawform 0.0.1 → 2.2.0

package/src/lib/license.js

@@ -0,0 +1,146 @@
+// License enforcement decision — the one function value commands call before
+// doing work. Everything impure is injected (store, clock, validation client,
+// env) so the state matrix tests deterministically; production call sites pass
+// nothing and get the real store + adapter.
+//
+// The client seam is vendor-agnostic on purpose: whichever vendor survives the
+// payout test implements `validate(key) → { status, reason? }` with statuses
+//   'valid'    — vendor confirmed the key
+//   'invalid'  — vendor answered and said no (revoked / refunded / not found)
+//   'error'    — vendor unreachable (network down, vendor outage)
+// The distinction between 'invalid' and 'error' is the whole design: outages
+// get the offline grace window, revocations do not.
+
+import { readLicense as storeRead, writeLicense as storeWrite } from './license-store.js';
+import { readEnv } from './rename-compat.js';
+import { logger } from './logger.js';
+import { GRACE_DAYS, REVALIDATE_HOURS, CLOCK_SKEW_HOURS } from './license-config.js';
+
+// Emergency operations are never license-gated: an expired card must not be
+// the reason a stuck production stack cannot be rolled back. Additions to this
+// list are a product decision, not a convenience — a test pins its contents.
+export const NEVER_GATED = new Set(['deploy', 'rollback']);
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+
+function hoursSince(iso, nowMs) {
+  const t = Date.parse(iso ?? '');
+  return Number.isFinite(t) ? (nowMs - t) / HOUR : Infinity;
+}
+
+export async function assertLicensed({
+  command,
+  readLicense = storeRead,
+  writeLicense = storeWrite,
+  client,
+  now = Date.now,
+  env = process.env,
+  warn = (m) => logger.warn(m),
+} = {}) {
+  if (NEVER_GATED.has(command)) return;
+
+  // Dormant gate: until a vendor adapter ships, there is no way to activate a
+  // key at all, so enforcement would lock every user out. A client that marks
+  // itself configured:false keeps the gate open; the adapter flips this, and a
+  // pinned test makes that flip a reviewed decision.
+  if (client?.configured === false) return;
+
+  // CI path: a key in the environment is validated on every run and nothing is
+  // persisted — CI boxes are ephemeral, so a local cache (and with it the
+  // offline grace window) would be meaningless there.
+  const envKey = readEnv('LICENSE_KEY', env);
+  if (envKey) {
+    const res = await client.validate(envKey);
+    if (res.status === 'valid') return;
+    if (res.status === 'invalid') {
+      throw new Error(
+        `CLAWFORM_LICENSE_KEY was rejected (${res.reason ?? 'invalid'}). ` +
+        'Check the key, or buy a seat — see the README for where.',
+      );
+    }
+    throw new Error(
+      `Could not verify CLAWFORM_LICENSE_KEY (${res.reason ?? 'network error'}) and CI has no ` +
+      'offline grace. Retry when the license service is reachable.',
+    );
+  }
+
+  const record = readLicense();
+  if (record.status !== 'active' || !record.key) {
+    throw new Error(
+      `'clawform ${command}' needs an activated license. Run: clawform activate <key> ` +
+      '(the key is in your purchase email).',
+    );
+  }
+
+  // A trial carries its own end date, handed over by the vendor at activation
+  // and covered by the record's signature so it cannot be edited outward.
+  //
+  // Checked BEFORE the freshness shortcut below, which returns without touching
+  // the network: a recently-validated record would otherwise sail past its own
+  // expiry for another day.
+  //
+  // Expiry is a property of the licence, not of connectivity, so the offline
+  // grace never reaches it — and the message says "trial", never "offline". A
+  // buyer told their connection failed will go looking for a fault that is not
+  // there.
+  //
+  // A record with no expiresAt is a perpetual seat, not one that expired at the
+  // epoch. Absence has to be checked explicitly.
+  if (record.expiresAt) {
+    const endsAt = Date.parse(record.expiresAt);
+    if (Number.isFinite(endsAt) && now() >= endsAt) {
+      throw new Error(
+        `Your Clawform trial ended on ${record.expiresAt.slice(0, 10)}, so 'clawform ${command}' `
+        + 'is no longer available. Buy a seat at https://clawform.thejoseki.com and run '
+        + '`clawform activate <key>`. Note that `clawform deploy` and `clawform rollback` keep '
+        + 'working either way — an expired licence never strands a stack.',
+      );
+    }
+  }
+
+  // Freshness has a floor as well as a ceiling. A record stamped in the future
+  // yields a negative age, which would read as "verified moments ago" forever —
+  // a permanent bypass that never contacts the vendor again. Below the floor we
+  // revalidate rather than refuse, so a genuinely fast clock costs a network
+  // call instead of an accusation.
+  const age = hoursSince(record.lastValidatedAt, now());
+  if (age >= -CLOCK_SKEW_HOURS && age < REVALIDATE_HOURS) return; // fresh verdict — no network
+
+  const res = await client.validate(record.key);
+
+  if (res.status === 'valid') {
+    // Carry a refreshed expiry through: the vendor is authoritative about it,
+    // and an extended trial should take effect without a re-activation.
+    writeLicense({
+      ...record,
+      lastValidatedAt: new Date(now()).toISOString(),
+      ...(res.expiresAt ? { expiresAt: res.expiresAt } : {}),
+    });
+    return;
+  }
+
+  if (res.status === 'invalid') {
+    throw new Error(
+      `This license is no longer valid (${res.reason ?? 'revoked'}). ` +
+      'If you believe this is a mistake, contact support with your purchase email.',
+    );
+  }
+
+  // Vendor unreachable — fall back on the grace window measured from the last
+  // SUCCESSFUL validation, so a machine that keeps failing to validate does not
+  // keep re-arming its own grace.
+  const graceLeftDays = GRACE_DAYS - age / 24;
+  if (graceLeftDays > 0) {
+    warn(
+      `Could not reach the license service to verify (${res.reason ?? 'offline'}). ` +
+      `Working offline — ${Math.ceil(graceLeftDays)} day(s) of grace remaining.`,
+    );
+    return;
+  }
+
+  throw new Error(
+    `The license could not be verified for more than ${GRACE_DAYS} days (offline or the ` +
+    'license service was unreachable). Reconnect once and the grace window resets.',
+  );
+}

package/src/lib/lint-overrides.js

@@ -0,0 +1,226 @@
+// Lint-override loader + cfn-guard SuppressedRules wrapper.
+//
+// Reads rules/lint-overrides.md (the single, audited allowlist), turns its
+// Markdown table into structured overrides, partitions expired rows, injects
+// the active ones into a CFN template's Metadata.guard.SuppressedRules so
+// cfn-guard skips them, and detects in-template suppressions that lack an
+// overrides-file row (anti-rot — "suppression without justification").
+//
+// Functions are pure where possible: every time-sensitive call (filterExpired)
+// takes the current Date as an argument so tests are deterministic. Callers
+// (src/commands/validate.js) supply `new Date()` at the call site.
+//
+// YAML round-trip uses the shared CFN short-tag schema in src/lib/cfn-yaml.js.
+// iam-audit / graph.js still carry local copies — they COULD import src/lib via
+// the same upward-probe graph.js already uses for project-config.js; folding
+// them onto cfn-yaml.js is a worthwhile follow-up (the copies have drifted
+// before: graph.js was missing `!Transform` until 1.2.0). The schema is
+// construct-only, so `!Sub "x"` round-trips to `Fn::Sub: x` — both forms are
+// valid CloudFormation and cfn-guard accepts either.
+
+import { readFileSync, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { CFN_SCHEMA } from './cfn-yaml.js';
+
+// --- loadOverrides ---------------------------------------------------------
+// Parse the Markdown table in rules/lint-overrides.md and return an array of
+//   { ruleId, scopeGlob, reason, expires, owner }
+//
+// Header-name driven: we normalize `rule-id` → `ruleId`, `scope` → `scopeGlob`.
+// The doc's `tool` column is read but discarded (cfn-guard SuppressedRules
+// don't distinguish source). `owner` is optional and defaults to null when the
+// column is absent or empty.
+//
+// Placeholder rows (empty rule-id, or markdown-italic markers like `_none yet_`)
+// are skipped — the bundled doc ships with one such row by design.
+//
+// Missing file: returns [] (a fresh consumer with no overrides is a valid
+// state, mirroring the legacy_prefixes contract).
+export function loadOverrides(mdPath) {
+  if (!existsSync(mdPath)) return [];
+  const text = readFileSync(mdPath, 'utf8');
+  return parseOverridesMarkdown(text);
+}
+
+export function parseOverridesMarkdown(text) {
+  const lines = text.split(/\r?\n/);
+  // Find the first table whose header includes a "rule-id" column.
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (isTableRow(line)) {
+      const header = splitRow(line);
+      const norm = header.map(normalizeHeader);
+      const idIdx = norm.indexOf('ruleId');
+      if (idIdx === -1) { i++; continue; }
+      // Next line should be the separator (|---|---|...). Skip it.
+      const sep = lines[i + 1];
+      if (!sep || !/^\s*\|?\s*:?-{2,}/.test(sep.trim())) { i++; continue; }
+      i += 2;
+      while (i < lines.length && isTableRow(lines[i])) {
+        const cells = splitRow(lines[i]);
+        const row = {};
+        for (let c = 0; c < norm.length; c++) row[norm[c]] = (cells[c] ?? '').trim();
+        const entry = rowToOverride(row);
+        if (entry) out.push(entry);
+        i++;
+      }
+      return out;
+    }
+    i++;
+  }
+  return out;
+}
+
+function isTableRow(line) {
+  return typeof line === 'string' && line.trim().startsWith('|') && line.trim().endsWith('|');
+}
+
+function splitRow(line) {
+  // Strip leading/trailing pipes then split on remaining pipes.
+  const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return trimmed.split('|').map((s) => s.trim());
+}
+
+function normalizeHeader(h) {
+  const k = h.trim().toLowerCase();
+  if (k === 'rule-id' || k === 'rule id' || k === 'ruleid') return 'ruleId';
+  if (k === 'scope' || k === 'scope-glob' || k === 'scopeglob') return 'scopeGlob';
+  return k;
+}
+
+function rowToOverride(row) {
+  const ruleId = row.ruleId;
+  if (!ruleId) return null;
+  // Skip markdown placeholder markers like `_none yet_`, `_pending_`, `n/a`.
+  if (/^_.*_$/.test(ruleId) || /^n\/a$/i.test(ruleId)) return null;
+  const scopeGlob = row.scopeGlob || '*';
+  const reason = row.reason || '';
+  const owner = row.owner ? row.owner : null;
+  const expires = parseExpires(row.expires);
+  return { ruleId, scopeGlob, reason, expires, owner };
+}
+
+function parseExpires(raw) {
+  if (!raw) return null;
+  const v = raw.trim();
+  if (!v || /^_.*_$/.test(v) || /^n\/a$/i.test(v) || v === '-') return null;
+  const d = new Date(v);
+  if (Number.isNaN(d.getTime())) return null;
+  return d;
+}
+
+// --- filterExpired ---------------------------------------------------------
+// Pure partition. `now` is REQUIRED — callers pass `new Date()` in production
+// and a fixed Date instance in tests. Entries with expires: null never expire.
+export function filterExpired(overrides, now) {
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
+    throw new TypeError('filterExpired(overrides, now): `now` must be a valid Date instance');
+  }
+  const active = [];
+  const expired = [];
+  for (const o of overrides) {
+    if (o.expires && o.expires.getTime() < now.getTime()) expired.push(o);
+    else active.push(o);
+  }
+  return { active, expired };
+}
+
+// --- glob matching for logical IDs ----------------------------------------
+// Tiny `*` → `.*` translator; `?` → `.`. `global` and `*` both mean match-all.
+// We intentionally don't pull a glob lib — overrides scope is a single token
+// against a CFN logical ID (alphanumeric), so the surface is small.
+export function matchesGlob(glob, value) {
+  if (!glob || glob === '*' || glob.toLowerCase() === 'global') return true;
+  const re = globToRegex(glob);
+  return re.test(value);
+}
+
+function globToRegex(glob) {
+  let out = '^';
+  for (const ch of glob) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  out += '$';
+  return new RegExp(out);
+}
+
+// --- injectSuppressions ----------------------------------------------------
+// For each resource in the template, append (deduped) any overrides whose
+// scopeGlob matches the logical ID to Metadata.guard.SuppressedRules. Does
+// NOT clobber pre-existing inline entries — a resource may legitimately carry
+// one (and detectUnauthorizedSuppressions decides if that's allowed).
+//
+// Returns the modified YAML string (long-form intrinsics — see schema note
+// at top of file).
+export function injectSuppressions(templateYaml, activeOverrides) {
+  let doc;
+  try {
+    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
+  } catch {
+    // Unknown short tag (e.g. `!Length`, language-extension tags we don't
+    // have a construct for), or any other YAML parse error. Returning the
+    // input unchanged preserves the contract "injection is best-effort, never
+    // a deploy-gate crash" — the real linters (cfn-lint / cfn-nag / cfn-guard)
+    // still run against the original file and will surface the parse problem
+    // with their own diagnostics.
+    return templateYaml;
+  }
+  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
+    return templateYaml;
+  }
+  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
+    if (!resource || typeof resource !== 'object') continue;
+    const ruleIds = [];
+    for (const o of activeOverrides) {
+      if (matchesGlob(o.scopeGlob, logicalId)) ruleIds.push(o.ruleId);
+    }
+    if (ruleIds.length === 0) continue;
+    resource.Metadata = resource.Metadata || {};
+    resource.Metadata.guard = resource.Metadata.guard || {};
+    const existing = Array.isArray(resource.Metadata.guard.SuppressedRules)
+      ? resource.Metadata.guard.SuppressedRules
+      : [];
+    const merged = Array.from(new Set([...existing, ...ruleIds]));
+    resource.Metadata.guard.SuppressedRules = merged;
+  }
+  return yaml.dump(doc, { schema: CFN_SCHEMA, lineWidth: 200, noRefs: true });
+}
+
+// --- detectUnauthorizedSuppressions ---------------------------------------
+// Walk the ORIGINAL template (not the injected copy) and return any inline
+// Metadata.guard.SuppressedRules entries that are NOT covered by an active
+// override row. "Covered" = some active override matches BOTH the resource's
+// logical ID (scopeGlob) AND the suppressed rule ID. This is the anti-rot
+// check — a hand-edited suppression in YAML must trace back to an audited row.
+export function detectUnauthorizedSuppressions(templateYaml, activeOverrides) {
+  const findings = [];
+  let doc;
+  try {
+    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
+  } catch {
+    // Same rationale as injectSuppressions: an unknown tag must not turn the
+    // anti-rot check into a Node crash that takes down the whole validate
+    // pipeline. The linters will report the parse problem; we report no
+    // unauthorized suppressions because we couldn't see them.
+    return findings;
+  }
+  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
+    return findings;
+  }
+  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
+    if (!resource || typeof resource !== 'object') continue;
+    const suppressed = resource?.Metadata?.guard?.SuppressedRules;
+    if (!Array.isArray(suppressed)) continue;
+    for (const ruleId of suppressed) {
+      const covered = activeOverrides.some(
+        (o) => o.ruleId === ruleId && matchesGlob(o.scopeGlob, logicalId),
+      );
+      if (!covered) findings.push({ resourceId: logicalId, ruleId });
+    }
+  }
+  return findings;
+}

package/src/lib/logger.js

@@ -0,0 +1,17 @@
+import chalk from 'chalk';
+import { readEnv } from './rename-compat.js';
+
+const ts = () => new Date().toISOString().slice(11, 19);
+
+export const logger = {
+  info: (msg) => console.log(`${chalk.gray(ts())} ${chalk.cyan('•')} ${msg}`),
+  ok: (msg) => console.log(`${chalk.gray(ts())} ${chalk.green('✓')} ${msg}`),
+  warn: (msg) => console.warn(`${chalk.gray(ts())} ${chalk.yellow('!')} ${msg}`),
+  error: (msg) => console.error(`${chalk.gray(ts())} ${chalk.red('✗')} ${msg}`),
+  step: (msg) => console.log(`${chalk.gray(ts())} ${chalk.magenta('→')} ${chalk.bold(msg)}`),
+  debug: (msg) => {
+    if (readEnv('DEBUG')) {
+      console.log(`${chalk.gray(ts())} ${chalk.gray('debug')} ${chalk.gray(msg)}`);
+    }
+  },
+};

package/src/lib/payload.js

@@ -0,0 +1,74 @@
+// Plugin payload codec: a bundle of text files → one compressed, encrypted
+// blob shipped inside the public npm tarball, decrypted at `init plugin` time
+// so a non-buyer cannot read the plugin content.
+//
+// Deterrence, not secrecy: the decrypt key ships in the CLI (the accepted "1a"
+// model). What this module guarantees is a lossless round-trip and that
+// tampering or a wrong key is CAUGHT (AES-256-GCM auth tag), never silently
+// turned into garbage. Uses only node:crypto + node:zlib — no dependency.
+//
+// The bundle is JSON {v, files:{path:content}} because every plugin file is
+// text (md/yaml/json/js/py). If a binary asset ever needs shipping, switch the
+// per-file encoding — the format version guards that migration.
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+
+const BUNDLE_VERSION = 1;
+const ALGO = 'aes-256-gcm';
+const IV_LEN = 12;   // GCM standard nonce length
+const TAG_LEN = 16;  // GCM auth tag length
+const KEY_LEN = 32;  // AES-256
+
+export function packFiles(entries) {
+  const files = {};
+  for (const { path, content } of entries) files[path] = content;
+  const json = JSON.stringify({ v: BUNDLE_VERSION, files });
+  return gzipSync(Buffer.from(json, 'utf8'));
+}
+
+export function unpackFiles(buffer) {
+  const obj = JSON.parse(gunzipSync(buffer).toString('utf8'));
+  if (obj.v !== BUNDLE_VERSION) {
+    throw new Error(`Unsupported payload bundle version ${obj.v} (expected ${BUNDLE_VERSION}).`);
+  }
+  // Preserve insertion order of the original entries — Object key order is
+  // stable for string keys, which is enough for a lossless round-trip.
+  return Object.entries(obj.files).map(([path, content]) => ({ path, content }));
+}
+
+function assertKey(key) {
+  if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+    throw new Error(`Encryption key must be a ${KEY_LEN}-byte Buffer.`);
+  }
+}
+
+// Output layout: iv (12) ‖ authTag (16) ‖ ciphertext. Self-describing so
+// decrypt needs only the key.
+export function encrypt(data, key) {
+  assertKey(key);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
+}
+
+export function decrypt(blob, key) {
+  assertKey(key);
+  const iv = blob.subarray(0, IV_LEN);
+  const tag = blob.subarray(IV_LEN, IV_LEN + TAG_LEN);
+  const ciphertext = blob.subarray(IV_LEN + TAG_LEN);
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  // .final() throws if the tag does not verify — a wrong key or a tampered
+  // blob both land here, so callers never see corrupt plaintext.
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+export function packAndEncrypt(entries, key) {
+  return encrypt(packFiles(entries), key);
+}
+
+export function decryptAndUnpack(blob, key) {
+  return unpackFiles(decrypt(blob, key));
+}

package/src/lib/project-config.js

@@ -0,0 +1,145 @@
+// Consumer-config loader for Clawform. Reads <projectDir>/clawform.config.json,
+// merges it onto the built-in defaults, returns a frozen object. Pure I/O — no
+// validation of "is customer set"; callers that need it (naming.js) check at
+// the point they need a value, with a focused error message.
+//
+// Merge order (low → high):
+//   1. DEFAULT_CONFIG                       (src/lib/defaults.js)
+//   2. <projectDir>/clawform.config.json     (consumer-committed, may be missing)
+//   3. caller-supplied overrides            (CLI flags)
+//
+// Missing file       → silently skipped (a fresh consumer is a valid state).
+// Malformed JSON     → throws with the file path and the parse error.
+// Wrong shape (e.g.  → throws — we'd rather fail loud than ship Acme's defaults under
+//   legacy_prefixes:   a wrong key.
+//   "OLDNET")
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { DEFAULT_CONFIG } from './defaults.js';
+import {
+  CONFIG_FILENAMES,
+  isDeprecatedConfigFilename,
+  warnDeprecatedConfigFilename,
+} from './rename-compat.js';
+
+const ARRAY_KEYS = new Set(['envs', 'legacy_prefixes', 'service_shortnames_extra']);
+const OBJECT_KEYS = new Set(['accounts', 'tags_defaults']);
+const STRING_KEYS = new Set(['customer', 'region']);
+
+// First match wins, so a project mid-rename that still has both files gets the
+// new one. Silent about the old name here — the warning belongs on the read,
+// not on every existence probe.
+export function findConfigPath(projectDir) {
+  if (!projectDir) return null;
+  for (const name of CONFIG_FILENAMES) {
+    const p = join(projectDir, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function readProjectConfig(projectDir) {
+  const p = findConfigPath(projectDir);
+  if (!p) return {};
+  if (isDeprecatedConfigFilename(basename(p))) warnDeprecatedConfigFilename(p);
+  let raw;
+  try {
+    raw = readFileSync(p, 'utf8');
+  } catch (err) {
+    throw new Error(`Failed to read ${p}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Malformed JSON in ${p}: ${err.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Expected JSON object in ${p}, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+  }
+  return validateShape(parsed, p);
+}
+
+function validateShape(cfg, sourcePath) {
+  const out = {};
+  for (const [k, v] of Object.entries(cfg)) {
+    if (k.startsWith('$')) continue;
+    if (STRING_KEYS.has(k)) {
+      if (typeof v !== 'string') throw new Error(`${sourcePath}: "${k}" must be a string`);
+      out[k] = v;
+    } else if (ARRAY_KEYS.has(k)) {
+      if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) {
+        throw new Error(`${sourcePath}: "${k}" must be an array of strings`);
+      }
+      out[k] = [...v];
+    } else if (OBJECT_KEYS.has(k)) {
+      if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        throw new Error(`${sourcePath}: "${k}" must be an object`);
+      }
+      out[k] = { ...v };
+    } else {
+      // Unknown key — keep verbatim so the consumer can add metadata, but don't
+      // act on it. This trades strictness for forward-compatibility.
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export function loadProjectConfig({ projectDir, overrides = {} } = {}) {
+  const fromFile = readProjectConfig(projectDir);
+  const merged = mergeShallow(DEFAULT_CONFIG, fromFile, overrides);
+  return Object.freeze(merged);
+}
+
+function mergeShallow(...sources) {
+  const out = {
+    ...DEFAULT_CONFIG,
+    accounts: { ...DEFAULT_CONFIG.accounts },
+    tags_defaults: { ...DEFAULT_CONFIG.tags_defaults },
+    envs: [...DEFAULT_CONFIG.envs],
+    legacy_prefixes: [...DEFAULT_CONFIG.legacy_prefixes],
+    service_shortnames_extra: [...DEFAULT_CONFIG.service_shortnames_extra],
+  };
+  for (const src of sources) {
+    if (!src) continue;
+    for (const [k, v] of Object.entries(src)) {
+      if (OBJECT_KEYS.has(k) && v && typeof v === 'object' && !Array.isArray(v)) {
+        out[k] = { ...out[k], ...v };
+      } else if (ARRAY_KEYS.has(k) && Array.isArray(v)) {
+        out[k] = [...v];
+      } else {
+        out[k] = v;
+      }
+    }
+  }
+  return out;
+}
+
+export function resolveProjectDir(explicit) {
+  return explicit || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+// Build the LEGACY_PREFIX_RE used by the hook from a runtime list. Returns null
+// when the list is empty — the hook treats null as "no legacy-freeze gate".
+//
+// Unanchored (\b...) on purpose: the hook applies it to a whole COMMAND LINE,
+// where the stack name appears mid-string. Do NOT reuse this against a bare
+// export/stack name — `\b` treats every hyphen as a boundary, so a legacy token
+// appearing mid-name (`p-acme-…-OLDAPP-arn`) would false-positive. Use the anchored
+// builder below for whole-name checks.
+export function buildLegacyPrefixRegex(prefixes) {
+  if (!Array.isArray(prefixes) || prefixes.length === 0) return null;
+  const escaped = prefixes.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`\\b(${escaped.join('|')})-[A-Za-z0-9-]+`);
+}
+
+// Anchored variant for matching a WHOLE name (export name, stack name) rather
+// than a substring of a command line: the legacy prefix must be the name's
+// leading segment. `OLDNET-VPC` matches; `p-acme-pri-lmd-payroll-OLDAPP-arn` does not.
+export function buildAnchoredLegacyPrefixRegex(prefixes) {
+  if (!Array.isArray(prefixes) || prefixes.length === 0) return null;
+  const escaped = prefixes.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`^(${escaped.join('|')})-`);
+}