@thejoseki/clawform 0.0.1 → 2.2.1

package/src/commands/init.js

@@ -0,0 +1,360 @@
+// clawform init — interactive wizard that produces a consumer-specific
+// clawform.config.json at the project root, plus an optional starter
+// .claude/settings.local.json copied from the example.
+//
+// Three modes:
+//   1. Interactive  — TTY attached; uses `inquirer` to walk the operator
+//      through every field. Default mode.
+//   2. Non-interactive — non-TTY (CI) **or** any CLAWFORM_INIT_* env var is
+//      set. Reads every value from env vars; refuses with a clear message
+//      if a TTY is unavailable AND no env vars are present.
+//   3. Refuse-overwrite — if clawform.config.json already exists and --force
+//      was not passed, print the existing file's location + values and exit.
+//
+// Validators are deliberately shared between modes so the env-var path can
+// never write garbage that the interactive prompts would have rejected.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, copyFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { logger } from '../lib/logger.js';
+import { readEnv, ENV_PREFIX, DEPRECATED_ENV_PREFIX } from '../lib/rename-compat.js';
+import { CUSTOMER_RE, CUSTOMER_MAX_LEN } from '../lib/constants.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Single source of truth for both interactive validators and the env-var path.
+// Throw on invalid input — caller decides whether to translate the throw into
+// a prompt re-ask (inquirer expects validators that return true/string) or
+// surface it as a fatal CLI error.
+const VALID_REGIONS = [
+  'us-east-1', 'us-east-2', 'us-west-1', 'us-west-2',
+  'ap-northeast-1', 'ap-northeast-2', 'ap-northeast-3',
+  'ap-southeast-1', 'ap-southeast-2', 'ap-southeast-3', 'ap-southeast-4',
+  'ap-south-1', 'ap-east-1',
+  'eu-west-1', 'eu-west-2', 'eu-west-3',
+  'eu-central-1', 'eu-north-1', 'eu-south-1',
+  'ca-central-1', 'sa-east-1',
+];
+
+const ACCOUNT_RE = /^\d{12}$/;
+const ENV_TOKENS = ['d', 'stg', 'p'];
+
+export const validators = {
+  customer(value) {
+    if (typeof value !== 'string' || value.length === 0) return 'customer is required';
+    if (!CUSTOMER_RE.test(value)) {
+      return `customer must match ${CUSTOMER_RE.source} — lowercase alphanumeric, max ${CUSTOMER_MAX_LEN} chars (the AWS load-balancer name budget; see templates/alb.yaml)`;
+    }
+    return true;
+  },
+  region(value) {
+    if (typeof value !== 'string' || value.length === 0) return 'region is required';
+    if (!VALID_REGIONS.includes(value)) {
+      return `region "${value}" is not in the common-regions list. Add it to VALID_REGIONS if you really need it.`;
+    }
+    return true;
+  },
+  accountId(value) {
+    if (value === '' || value === undefined || value === null) return true; // blank is allowed
+    if (!ACCOUNT_RE.test(String(value).trim())) return 'account ID must be 12 digits (or blank to skip the guard)';
+    return true;
+  },
+  envs(value) {
+    if (!Array.isArray(value) || value.length === 0) return 'pick at least one env';
+    for (const v of value) {
+      if (!ENV_TOKENS.includes(v)) return `unknown env token "${v}" (allowed: ${ENV_TOKENS.join(', ')})`;
+    }
+    return true;
+  },
+};
+
+function assertValid(field, value) {
+  const result = validators[field](value);
+  if (result !== true) throw new Error(`${field}: ${result}`);
+}
+
+// Trim + drop empty entries; used for the comma-separated optional fields.
+function splitCsv(raw) {
+  if (!raw || typeof raw !== 'string') return [];
+  return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// Build a config object in the exact key order used by clawform.config.example.json
+// so diffs against the example stay clean.
+function buildConfig({ customer, envs, region, accounts, legacy_prefixes, service_shortnames_extra, tags_defaults }) {
+  return {
+    $schema: './docs/config-schema.md',
+    customer,
+    envs,
+    region,
+    accounts,
+    legacy_prefixes,
+    service_shortnames_extra,
+    tags_defaults,
+  };
+}
+
+function isInteractive() {
+  return Boolean(process.stdin?.isTTY && process.stdout?.isTTY);
+}
+
+// Non-interactive path: read every value from CLAWFORM_INIT_* env vars,
+// validate, and return the assembled config. Env-var presence (any one of
+// them set) is the SOLE trigger for non-interactive mode — there is no
+// separate commander flag.
+//
+// Env vars:
+//   CLAWFORM_INIT_CUSTOMER           required
+//   CLAWFORM_INIT_REGION             required
+//   CLAWFORM_INIT_ENVS               optional, csv, default "d,stg,p"
+//   CLAWFORM_INIT_ACCOUNT_D          optional, 12-digit
+//   CLAWFORM_INIT_ACCOUNT_STG        optional, 12-digit
+//   CLAWFORM_INIT_ACCOUNT_P          optional, 12-digit
+//   CLAWFORM_INIT_LEGACY_PREFIXES    optional, csv, default ""
+//   CLAWFORM_INIT_OWNER              optional
+//   CLAWFORM_INIT_COST_CENTER        optional
+//   CLAWFORM_INIT_SERVICE_SHORTNAMES_EXTRA  optional, csv
+export function hasNonInteractiveEnv(env = process.env) {
+  // Both spellings count as "the caller wants non-interactive mode", so a
+  // pre-rename CI job still skips the prompts. Referenced through the compat
+  // constants rather than written out, so a rename sweep cannot quietly
+  // collapse the two branches into the same string.
+  return Object.keys(env).some(
+    (k) => k.startsWith(`${ENV_PREFIX}INIT_`) || k.startsWith(`${DEPRECATED_ENV_PREFIX}INIT_`),
+  );
+}
+
+export function buildConfigFromEnv(env = process.env) {
+  const customer = (readEnv('INIT_CUSTOMER', env) ?? '').trim();
+  const region = (readEnv('INIT_REGION', env) ?? '').trim();
+  const envs = splitCsv(readEnv('INIT_ENVS', env) ?? 'd,stg,p');
+
+  assertValid('customer', customer);
+  assertValid('region', region);
+  assertValid('envs', envs);
+
+  const accounts = {};
+  for (const e of envs) {
+    const v = (readEnv(`INIT_ACCOUNT_${e.toUpperCase()}`, env) ?? '').trim();
+    assertValid('accountId', v);
+    accounts[e] = v;
+  }
+
+  const legacy_prefixes = splitCsv(readEnv('INIT_LEGACY_PREFIXES', env) ?? '');
+  const service_shortnames_extra = splitCsv(readEnv('INIT_SERVICE_SHORTNAMES_EXTRA', env) ?? '');
+
+  const tags_defaults = {};
+  const owner = (readEnv('INIT_OWNER', env) ?? '').trim();
+  const cost = (readEnv('INIT_COST_CENTER', env) ?? '').trim();
+  if (owner) tags_defaults.Owner = owner;
+  if (cost) tags_defaults.CostCenter = cost;
+
+  return buildConfig({ customer, envs, region, accounts, legacy_prefixes, service_shortnames_extra, tags_defaults });
+}
+
+async function promptInteractive() {
+  logger.step('Clawform — greenfield project wizard');
+  logger.info('Press Ctrl+C at any time to abort. Nothing is written until the final step.');
+
+  const base = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'customer',
+      message: 'Customer shortname (the <customer> slot in stack names):',
+      validate: validators.customer,
+    },
+    {
+      type: 'list',
+      name: 'region',
+      message: 'Default AWS region:',
+      choices: VALID_REGIONS,
+      default: 'ap-northeast-1',
+    },
+    {
+      type: 'checkbox',
+      name: 'envs',
+      message: 'Environments this project will deploy to:',
+      choices: ENV_TOKENS.map((e) => ({ name: e, value: e, checked: true })),
+      validate: (v) => (v.length === 0 ? 'pick at least one env' : true),
+    },
+  ]);
+
+  // Per-env account prompts depend on the envs answer, so they must be a
+  // separate prompt call. Each is optional — blank disables the account guard.
+  const accounts = {};
+  for (const env of base.envs) {
+    const { accountId } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'accountId',
+        message: `AWS account ID for env "${env}" (12 digits, blank = no account-match guard):`,
+        validate: validators.accountId,
+      },
+    ]);
+    accounts[env] = (accountId ?? '').trim();
+  }
+
+  const tail = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'legacy_prefixes_raw',
+      // The "empty is correct for a greenfield consumer" hint is critical —
+      // new operators see a blank default and assume they should fill it.
+      // Keep it in the `message` (not `suffix`) so it renders on every
+      // inquirer version we care about, and so it shows up in screen
+      // captures of the prompt rendering.
+      message: `Legacy stack-name prefixes the hook should refuse to modify (comma-separated). ${chalk.gray('Empty is correct for a greenfield consumer.')}`,
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'owner',
+      message: 'Default Owner tag (optional, blank to skip):',
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'cost_center',
+      message: 'Default CostCenter tag (optional, blank to skip):',
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'service_shortnames_extra_raw',
+      message: 'Extra service shortnames beyond the built-ins (comma-separated, optional):',
+      default: '',
+    },
+  ]);
+
+  const tags_defaults = {};
+  if (tail.owner.trim()) tags_defaults.Owner = tail.owner.trim();
+  if (tail.cost_center.trim()) tags_defaults.CostCenter = tail.cost_center.trim();
+
+  return buildConfig({
+    customer: base.customer.trim(),
+    envs: base.envs,
+    region: base.region,
+    accounts,
+    legacy_prefixes: splitCsv(tail.legacy_prefixes_raw),
+    service_shortnames_extra: splitCsv(tail.service_shortnames_extra_raw),
+    tags_defaults,
+  });
+}
+
+async function maybeBootstrapSettings(cwd) {
+  // The example lives in this repo's own .claude/. When clawform is installed
+  // as a plugin elsewhere, the example file is shipped via package.json
+  // `files` and resolved relative to this module. Same path on disk; resolve
+  // from __dirname so the plugin-install case works.
+  const target = join(cwd, '.claude', 'settings.local.json');
+  if (existsSync(target)) {
+    logger.info(`.claude/settings.local.json already exists — leaving it alone.`);
+    return;
+  }
+  const pluginRoot = join(__dirname, '..', '..');
+  const example = join(pluginRoot, '.claude', 'settings.local.json.example');
+  if (!existsSync(example)) {
+    logger.info('No settings.local.json.example found in plugin — skipping bootstrap.');
+    return;
+  }
+
+  const { create } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'create',
+      message: 'Create .claude/settings.local.json from the example (per-user env: AWS_PROFILE, etc.)?',
+      default: true,
+    },
+  ]);
+  if (!create) return;
+
+  const { profile } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'profile',
+      message: 'AWS_PROFILE to use locally (blank to keep the example default):',
+      default: '',
+    },
+  ]);
+
+  await mkdir(join(cwd, '.claude'), { recursive: true });
+  await copyFile(example, target);
+
+  if (profile.trim()) {
+    // Re-read what we just wrote and patch only AWS_PROFILE; never touch
+    // anything else, so the rest of the example (region defaults, etc.) is
+    // preserved exactly.
+    const raw = await readFile(target, 'utf8');
+    const parsed = JSON.parse(raw);
+    parsed.env = parsed.env || {};
+    parsed.env.AWS_PROFILE = profile.trim();
+    await writeFile(target, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+  }
+
+  logger.ok(`Wrote ${target}`);
+  logger.info('That file is gitignored — keep per-user secrets there, not in clawform.config.json.');
+}
+
+export default async function init(opts = {}) {
+  const cwd = process.cwd();
+  const configPath = join(cwd, 'clawform.config.json');
+
+  if (existsSync(configPath) && !opts.force) {
+    logger.warn(`Refusing to overwrite existing ${configPath}.`);
+    try {
+      const raw = await readFile(configPath, 'utf8');
+      logger.info('Current contents:');
+      console.log(raw);
+    } catch {
+      // existence check already succeeded; ignore read failures
+    }
+    logger.info('Re-run with --force to overwrite, or delete the file first.');
+    return;
+  }
+
+  const envHasInit = hasNonInteractiveEnv();
+  let config;
+
+  if (envHasInit) {
+    logger.step('Non-interactive mode (CLAWFORM_INIT_* env vars detected).');
+    config = buildConfigFromEnv();
+  } else if (!isInteractive()) {
+    throw new Error(
+      'No TTY detected and no CLAWFORM_INIT_* env vars set.\n' +
+      '  Run interactively, OR provide:\n' +
+      '    CLAWFORM_INIT_CUSTOMER=<shortname>\n' +
+      '    CLAWFORM_INIT_REGION=ap-northeast-1\n' +
+      '    CLAWFORM_INIT_ENVS=d,stg,p (optional, default d,stg,p)\n' +
+      '    CLAWFORM_INIT_ACCOUNT_D=<12-digit> (optional)\n' +
+      '    CLAWFORM_INIT_ACCOUNT_STG=<12-digit> (optional)\n' +
+      '    CLAWFORM_INIT_ACCOUNT_P=<12-digit> (optional)\n' +
+      '    CLAWFORM_INIT_LEGACY_PREFIXES=OLDNET,OLDAPP (optional, default empty)\n' +
+      '    CLAWFORM_INIT_OWNER=<name> (optional)\n' +
+      '    CLAWFORM_INIT_COST_CENTER=<code> (optional)\n' +
+      '    CLAWFORM_INIT_SERVICE_SHORTNAMES_EXTRA=<csv> (optional)'
+    );
+  } else {
+    config = await promptInteractive();
+  }
+
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  logger.ok(`Wrote ${configPath}`);
+
+  if (isInteractive()) {
+    await maybeBootstrapSettings(cwd);
+  } else {
+    logger.info('Skipping .claude/settings.local.json bootstrap (non-interactive).');
+  }
+
+  logger.step('Next steps:');
+  logger.info('  1. Open this project in Claude Code.');
+  logger.info('  2. Greenfield architecture: /clawform:scaffold-project');
+  logger.info('  3. Add a single stack:      /clawform:new-stack');
+  logger.info('  4. Validate a template:     /clawform:validate cfn/<name>.yaml');
+  logger.info('  5. Deploy:                  /clawform:deploy cfn/<name>.yaml <env>');
+  logger.info('Docs: docs/runbook.md (scenario-first) and CLAUDE.md (hard rules).');
+}

package/src/commands/license-status.js

@@ -0,0 +1,28 @@
+// clawform license [--check] — show what this machine holds. --check is the
+// scriptable form: silent success when active, a thrown (exit-1) error when
+// not, so skills can gate a workflow step on it without parsing output.
+
+import { logger } from '../lib/logger.js';
+import { readLicense } from '../lib/license-store.js';
+
+export default async function licenseStatus({ check = false } = {}, {
+  read = readLicense,
+  log = (m) => logger.info(m),
+} = {}) {
+  const record = read();
+  const active = record.status === 'active' && Boolean(record.key);
+
+  if (check) {
+    if (active) return;
+    throw new Error('No active license on this machine. Run: clawform activate <key>.');
+  }
+
+  if (!active) {
+    log('License: none — run `clawform activate <key>` (the key is in your purchase email).');
+    return;
+  }
+
+  log(`License: active${record.holder ? ` — ${record.holder}` : ''}`);
+  log(`Key: …${String(record.key).slice(-4)}`);
+  if (record.lastValidatedAt) log(`Last verified: ${record.lastValidatedAt}`);
+}

package/src/commands/rollback.js

@@ -0,0 +1,126 @@
+import {
+  DescribeStacksCommand,
+  DescribeStackResourcesCommand,
+} from '@aws-sdk/client-cloudformation';
+import chalk from 'chalk';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import { isDataResource } from '../lib/constants.js';
+import { loadProjectConfig, buildLegacyPrefixRegex, buildAnchoredLegacyPrefixRegex, resolveProjectDir } from '../lib/project-config.js';
+import { assertNoFrozenExports } from '../aws/exports.js';
+
+export default async function rollback({ stack }) {
+  logger.step(`clawform rollback ${stack}`);
+
+  // Legacy-freeze gate (mirrors deploy.js): the freeze applies to recovery,
+  // not just edits. The CLI refuses outright — no override flag. The
+  // documented escape hatch is running the raw aws CLI with a
+  // `# FORCE LEGACY: <reason>` comment, which goes through the PreToolUse
+  // hook, not this CLI. See rules/legacy-freeze.md.
+  const projectCfg = loadProjectConfig({ projectDir: resolveProjectDir() });
+  const legacyRe = buildLegacyPrefixRegex(projectCfg.legacy_prefixes);
+  if (legacyRe && legacyRe.test(stack)) {
+    const list = projectCfg.legacy_prefixes.map((p) => `${p}-*`).join(', ');
+    throw new Error(
+      `Stack "${stack}" matches a legacy prefix (${list}) from your clawform.config.json.\n` +
+      `clawform rollback refuses to suggest recovery commands for legacy stacks. See rules/legacy-freeze.md.\n` +
+      `If recovery is unavoidable, use the raw aws cloudformation CLI with a "# FORCE LEGACY: <reason>" comment on its own line.`,
+    );
+  }
+
+  const client = cfnClient();
+
+  const out = await client.send(new DescribeStacksCommand({ StackName: stack }));
+  const s = out.Stacks?.[0];
+  if (!s) throw new Error(`Stack ${stack} not found.`);
+
+  // C2: frozen-export gate — shared with deploy.js (src/aws/exports.js). A
+  // stack whose NAME isn't frozen may still emit legacy-prefixed EXPORT names;
+  // the freeze applies to recovery too (rules/legacy-freeze.md). Anchored
+  // regex: prefix must lead the export name.
+  assertNoFrozenExports({
+    liveOutputs: s.Outputs,
+    legacyRe: buildAnchoredLegacyPrefixRegex(projectCfg.legacy_prefixes),
+    stackName: stack,
+    action: 'recovery',
+  });
+
+  logger.info(`Status: ${s.StackStatus}`);
+
+  switch (s.StackStatus) {
+    case 'UPDATE_ROLLBACK_FAILED':
+    case 'ROLLBACK_FAILED':
+      await suggestContinueRollback(client, stack);
+      break;
+    case 'CREATE_FAILED':
+    case 'ROLLBACK_COMPLETE':
+      await suggestDelete(client, stack);
+      break;
+    case 'UPDATE_FAILED':
+      logger.info('CFN will normally auto-roll-back to UPDATE_ROLLBACK_COMPLETE. If stuck, wait then re-run /rollback.');
+      break;
+    case 'CREATE_COMPLETE':
+    case 'UPDATE_COMPLETE':
+    case 'UPDATE_ROLLBACK_COMPLETE':
+    case 'IMPORT_COMPLETE':
+      logger.ok('Stack is healthy — nothing to roll back.');
+      break;
+    default:
+      if (/_IN_PROGRESS$/.test(s.StackStatus)) {
+        logger.info('Stack is mid-operation. Wait for terminal status, then re-run /rollback.');
+      } else {
+        logger.warn(`Status ${s.StackStatus} has no automatic recovery suggestion.`);
+      }
+  }
+}
+
+async function suggestContinueRollback(client, stack) {
+  const failed = await fetchFailedResources(client, stack);
+  if (failed.length === 0) {
+    logger.info(chalk.bold('Suggested:'));
+    logger.info(`  aws cloudformation continue-update-rollback --stack-name ${stack}`);
+    return;
+  }
+  logger.info(`Failed resources (${failed.length}): ${failed.join(', ')}`);
+  logger.info(chalk.bold('Suggested:'));
+  logger.info(`  aws cloudformation continue-update-rollback --stack-name ${stack} \\`);
+  logger.info(`    --resources-to-skip ${failed.join(' ')}`);
+  logger.warn('Confirm each skipped resource is acceptable to leave in mixed state before running.');
+}
+
+async function suggestDelete(client, stack) {
+  const out = await client.send(new DescribeStackResourcesCommand({ StackName: stack }));
+  const dataResources = (out.StackResources ?? []).filter((r) => isDataResource(r.ResourceType));
+  if (dataResources.length > 0) {
+    logger.warn(`Stack contains ${dataResources.length} data resource(s):`);
+    for (const r of dataResources) logger.warn(`  ${r.LogicalResourceId} (${r.ResourceType}) → ${r.PhysicalResourceId ?? '(no physical)'}`);
+    logger.info('Delete is unsafe. Options:');
+    logger.info('  1. Verify each data resource has DeletionPolicy: Retain → delete-stack is safe (physical resource survives)');
+    logger.info('  2. Import data resources into a new stack first (see rules/legacy-freeze.md "replace pattern")');
+    return;
+  }
+  logger.ok('No data resources detected.');
+  logger.info(chalk.bold('Suggested:'));
+  logger.info(`  aws cloudformation delete-stack --stack-name ${stack}`);
+  logger.info('Then run: aws cloudformation wait stack-delete-complete --stack-name ' + stack);
+}
+
+export async function fetchFailedResources(client, stack) {
+  // Use DescribeStackResources, not DescribeStackEvents. Two reasons:
+  // 1. (bug_028) DescribeStackResources returns CURRENT per-resource status. The
+  //    previous DescribeStackEvents+filter walked event HISTORY and added any
+  //    resource that had ever-been-FAILED — so a resource that hit UPDATE_FAILED
+  //    early and was then auto-rolled-back to UPDATE_COMPLETE stayed in the
+  //    suggested --resources-to-skip list. AWS rejects continue-update-rollback
+  //    with "resource X is not in a state to be skipped" for those, defeating
+  //    the whole point of the suggestion.
+  // 2. (merged_bug_008) DescribeStackEvents is paginated and capped ~100/page;
+  //    after a long forward update + rollback the original FAILED events scroll
+  //    off page 1. DescribeStackResources avoids the pagination question entirely.
+  // The suggestDelete path already uses DescribeStackResources — this keeps the
+  // file consistent.
+  const out = await client.send(new DescribeStackResourcesCommand({ StackName: stack }));
+  return (out.StackResources ?? [])
+    .filter((r) => /_FAILED$/.test(r.ResourceStatus ?? '') && r.LogicalResourceId)
+    .map((r) => r.LogicalResourceId);
+}

package/src/commands/status.js

@@ -0,0 +1,150 @@
+// clawform status — a one-command day-2 health board for a project's stacks.
+//
+// For each live stack belonging to the project: its CloudFormation status, when
+// it was last deployed, and its LAST-KNOWN drift status (from the ListStacks
+// summary — this does NOT trigger a fresh drift detection, which costs time and
+// API calls; run `clawform drift <stack>` for that). It also flags whether the
+// project has a monitoring stack covering it, since "no alarms" is the silent
+// gap [[observability]] exists to catch.
+//
+// Read-only. Pure helpers (filterProjectStacks / summarize / monitoringPresent /
+// renderStatus) are unit-tested without AWS; status() is the thin SDK wrapper.
+
+import { ListStacksCommand } from '@aws-sdk/client-cloudformation';
+import chalk from 'chalk';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import { ENVS } from '../lib/constants.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+// Every status a non-deleted stack can be in. ListStacks with StackStatusFilter
+// returns ONLY the listed statuses, so an omission makes that stack VANISH from
+// the board — and a board that hides DELETE_FAILED (the classic wedged-teardown
+// state) is worse than no board. Named EXISTING (not LIVE) deliberately:
+// src/aws/inventory.js has a different LIVE_STATUSES meaning "stable/deployable",
+// and the two must not be unified.
+const EXISTING_STATUSES = [
+  'CREATE_COMPLETE', 'UPDATE_COMPLETE', 'UPDATE_ROLLBACK_COMPLETE',
+  'IMPORT_COMPLETE', 'ROLLBACK_COMPLETE',
+  'CREATE_FAILED', 'UPDATE_FAILED', 'UPDATE_ROLLBACK_FAILED',
+  'ROLLBACK_FAILED', 'DELETE_FAILED', 'IMPORT_ROLLBACK_FAILED',
+  'CREATE_IN_PROGRESS', 'UPDATE_IN_PROGRESS', 'ROLLBACK_IN_PROGRESS',
+  'DELETE_IN_PROGRESS', 'UPDATE_ROLLBACK_IN_PROGRESS',
+  'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS', 'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS',
+  'IMPORT_IN_PROGRESS', 'IMPORT_ROLLBACK_IN_PROGRESS',
+  'REVIEW_IN_PROGRESS',
+];
+
+// Hand-rolled pagination (ListStacksCommand + NextToken) instead of
+// paginateListStacks so a plain { send } stub mocks the seam in tests — the
+// generated paginator hard-checks `client instanceof CloudFormationClient`.
+export async function fetchStackSummaries(client) {
+  const out = [];
+  let nextToken;
+  do {
+    const resp = await client.send(new ListStacksCommand({
+      StackStatusFilter: EXISTING_STATUSES,
+      NextToken: nextToken,
+    }));
+    for (const s of resp.StackSummaries ?? []) {
+      out.push({
+        name: s.StackName,
+        status: s.StackStatus,
+        lastUpdatedTime: s.LastUpdatedTime ?? s.CreationTime ?? null,
+        driftStatus: s.DriftInformation?.StackDriftStatus ?? 'NOT_CHECKED',
+      });
+    }
+    nextToken = resp.NextToken;
+  } while (nextToken);
+  return out;
+}
+
+// Stacks belonging to a project: the `<project>` token appears as a hyphen-
+// delimited segment of the name (e.g. d-acme-pri-snet-myproj-zonea → 'myproj').
+// Optional env narrows to names starting `<env>-`.
+export function filterProjectStacks(summaries, { project, env } = {}) {
+  return (summaries ?? []).filter((s) => {
+    const segments = (s.name ?? '').split('-');
+    if (project && !segments.includes(project)) return false;
+    if (env && !(s.name ?? '').startsWith(`${env}-`)) return false;
+    return true;
+  });
+}
+
+// A monitoring stack is present if any stack in the set names the monitoring
+// archetype or carries the cwa (CloudWatch alarm) service token.
+export function monitoringPresent(stacks) {
+  return (stacks ?? []).some((s) => {
+    const segs = (s.name ?? '').split('-');
+    return segs.includes('monitoring') || segs.includes('cwa');
+  });
+}
+
+function healthOf(status) {
+  if (/_FAILED$/.test(status)) return 'failed'; // incl. DELETE_FAILED — a wedged teardown is broken, not gone
+  if (/_IN_PROGRESS$/.test(status)) return 'in-progress';
+  if (status === 'ROLLBACK_COMPLETE') return 'failed';
+  return 'ok';
+}
+
+export function summarize(stacks) {
+  return [...(stacks ?? [])]
+    .map((s) => ({
+      name: s.name,
+      status: s.status,
+      health: healthOf(s.status),
+      updated: s.lastUpdatedTime ? new Date(s.lastUpdatedTime).toISOString().slice(0, 10) : '—',
+      drift: s.driftStatus,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const HEALTH_COLOR = { ok: chalk.green, failed: chalk.red, 'in-progress': chalk.yellow };
+const DRIFT_COLOR = { DRIFTED: chalk.red, IN_SYNC: chalk.green };
+
+export function renderStatus(rows, meta) {
+  const lines = [];
+  const scope = [meta.env && `env ${meta.env}`, meta.project ? `project ${meta.project}` : 'all projects']
+    .filter(Boolean).join(', ');
+  lines.push(`Stack status — ${scope}`);
+  lines.push('');
+  if (rows.length === 0) {
+    lines.push('  (no matching stacks)');
+    return lines.join('\n');
+  }
+  const w = Math.max(20, ...rows.map((r) => r.name.length));
+  for (const r of rows) {
+    const statusColor = HEALTH_COLOR[r.health] ?? ((s) => s);
+    const driftColor = DRIFT_COLOR[r.drift] ?? chalk.gray;
+    lines.push(
+      `  ${r.name.padEnd(w)}  ${statusColor(r.status.padEnd(24))}  ${r.updated}  ${driftColor(r.drift)}`,
+    );
+  }
+  lines.push('');
+  const failed = rows.filter((r) => r.health === 'failed').length;
+  const drifted = rows.filter((r) => r.drift === 'DRIFTED').length;
+  lines.push(`  ${rows.length} stack(s) · ${failed} failed · ${drifted} drifted`);
+  if (!meta.hasMonitoring) {
+    lines.push(chalk.yellow('  ⚠ No monitoring stack detected for this scope — see observability (templates/monitoring.yaml).'));
+  }
+  lines.push(chalk.gray('  Drift = last known (not re-checked). Run `clawform drift <stack>` for a fresh detection.'));
+  return lines.join('\n');
+}
+
+export default async function status({ project, env, profile, region } = {}) {
+  await assertLicensed({ command: 'status', client: resolveLicenseClient() });
+  if (env && !ENVS.includes(env)) {
+    throw new Error(`Invalid --env "${env}". Expected one of: ${ENVS.join(' | ')}`);
+  }
+  const client = cfnClient({
+    ...(profile ? { AWS_PROFILE: profile } : {}),
+    ...(region ? { AWS_REGION: region } : {}),
+  });
+  logger.step(`clawform status${project ? ` — ${project}` : ''}`);
+
+  const all = await fetchStackSummaries(client);
+  const mine = filterProjectStacks(all, { project, env });
+  const rows = summarize(mine);
+  console.log(renderStatus(rows, { project, env, hasMonitoring: monitoringPresent(mine) }));
+}