@thejoseki/clawform 0.0.1 → 2.2.0

package/src/commands/deploy.js

@@ -0,0 +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}`);
+  }
+}

package/src/commands/diff.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { GetTemplateCommand } from '@aws-sdk/client-cloudformation';
+import { createPatch } from 'diff';
+import chalk from 'chalk';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+
+export default async function diff({ stack, file }) {
+  const localPath = file ?? `cfn/${stack}.yaml`;
+  logger.step(`clawform diff ${stack}  ↔  ${localPath}`);
+
+  if (!existsSync(localPath)) {
+    throw new Error(`Local template not found: ${localPath}. Pass --file <path> to override.`);
+  }
+  // Normalize line endings before comparison. CFN's GetTemplate returns LF, but
+  // fs.readFile preserves whatever bytes are on disk — on Windows checkouts (git's
+  // default core.autocrlf=true) every line of an identical template differs by a
+  // trailing \r, producing a wall-of-red diff that destroys the command's value.
+  const local = (await readFile(localPath, 'utf8')).replace(/\r\n/g, '\n');
+
+  const client = cfnClient();
+  const out = await client.send(new GetTemplateCommand({ StackName: stack, TemplateStage: 'Original' }));
+  const live = (out.TemplateBody ?? '').replace(/\r\n/g, '\n');
+
+  if (live === local) {
+    logger.ok('No diff. Local template matches live stack.');
+    return;
+  }
+
+  const patch = createPatch(stack, live, local, 'live', 'local', { context: 3 });
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('+++ ') || line.startsWith('--- ')) console.log(chalk.bold(line));
+    else if (line.startsWith('+')) console.log(chalk.green(line));
+    else if (line.startsWith('-')) console.log(chalk.red(line));
+    else if (line.startsWith('@@')) console.log(chalk.cyan(line));
+    else console.log(line);
+  }
+}

package/src/commands/drift.js

@@ -0,0 +1,35 @@
+import chalk from 'chalk';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import { detectAndWait, listResourceDrifts } from '../aws/drift.js';
+
+export default async function drift({ stack }) {
+  logger.step(`clawform drift ${stack}`);
+  const client = cfnClient();
+
+  logger.info('Detecting drift (this can take a few minutes)…');
+  const summary = await detectAndWait(client, { stackName: stack });
+  logger.info(`StackDriftStatus: ${summary.stackDriftStatus}  ·  drifted resources: ${summary.driftedResourceCount}`);
+
+  if (summary.stackDriftStatus === 'IN_SYNC') {
+    logger.ok('No drift.');
+    return;
+  }
+
+  const drifts = await listResourceDrifts(client, stack);
+  for (const d of drifts) {
+    logger.info('');
+    logger.info(`${chalk.yellow(d.driftStatus)}  ${d.logicalId} (${d.resourceType})`);
+    for (const p of d.propertyDifferences) {
+      const status = p.DifferenceType ?? '?';
+      logger.info(`  ${chalk.dim('@')}${p.PropertyPath ?? '/'}  ${status}`);
+      if (p.ExpectedValue !== undefined) logger.info(`    expected: ${truncate(p.ExpectedValue)}`);
+      if (p.ActualValue !== undefined)   logger.info(`    actual:   ${truncate(p.ActualValue)}`);
+    }
+  }
+}
+
+function truncate(v, max = 120) {
+  const s = typeof v === 'string' ? v : JSON.stringify(v);
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}

package/src/commands/init-plugin.js

@@ -0,0 +1,168 @@
+// clawform init plugin [--global|--project] — materialize the plugin into a
+// self-contained dir under ~/.clawform and register it with Claude Code.
+//
+// Opt 2 (chosen): decrypt the content library (skills/commands/agents/rules/
+// templates) and copy the plaintext CLI parts (src/, hooks/, .claude-plugin/,
+// CLAUDE.md) into ~/.clawform/plugin, then run `claude plugin marketplace add`
+// on that dir. Claude Code loads it as a real plugin, so CLAUDE_PLUGIN_ROOT is
+// set and the skills resolve rules/templates with no edits — and because we
+// never hand-write into the user's own .claude, there is nothing to back up.
+//
+// Enforcement: this command IS license-gated. The decrypt key ships in the CLI
+// (model 1a), so encryption alone does not stop a non-buyer — refusing to run
+// this without an active license is what does. While the vendor client is
+// dormant (pre-launch) the gate passes, exactly like the value commands.
+
+import { createHash } from 'node:crypto';
+import {
+  readFileSync, writeFileSync, mkdirSync, cpSync, existsSync, readdirSync, statSync,
+} from 'node:fs';
+import { homedir as osHomedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../lib/logger.js';
+import { resolveClient } from '../lib/license-client.js';
+import { readLicense as storeRead } from '../lib/license-store.js';
+import { assertLicensed } from '../lib/license.js';
+import { obtainKit } from '../lib/kit-source.js';
+import { KIT_SERVICE_URL } from '../lib/license-config.js';
+import { contentWatermark, licensedToBody } from '../lib/watermark.js';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(MODULE_DIR, '..', '..');
+
+// The mechanism, shipped in cleartext because it has to be runnable by path —
+// `bin/` is the npm bin entry, and `src/hooks/*.js` is what hooks.json tells
+// Claude Code to execute (${CLAUDE_PLUGIN_ROOT}/src/hooks/*.js). Nothing else
+// belongs here: every inert file the plugin needs, hooks.json and the manifests
+// included, rides in the encrypted payload and lands in this same dir at
+// decrypt time.
+export const PLAINTEXT_PLUGIN_PARTS = ['bin', 'src'];
+
+function sha256File(abs) {
+  return createHash('sha256').update(readFileSync(abs)).digest('hex');
+}
+
+function walkRel(dir, root, out) {
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name);
+    if (statSync(abs).isDirectory()) walkRel(abs, root, out);
+    else out.push(abs.slice(root.length + 1).split('\\').join('/'));
+  }
+}
+
+const RECEIPT_FILENAME = '.licensed-to';
+
+// Files the manifest deliberately ignores: it exists to tell our content from
+// the user's edits, and both of these are per-install metadata (the receipt
+// carries a timestamp, so it would report churn on every run).
+const MANIFEST_EXCLUDED = new Set(['install-manifest.json', RECEIPT_FILENAME]);
+
+// Build the plugin dir. Pure filesystem work — no license check, no network, no
+// child process — so it tests against temp dirs. Returns the manifest.
+//
+// Takes the kit as `entries` rather than reading it: how the kit is OBTAINED is
+// a separate concern that now involves a licence check and a network call, and
+// folding that in here would make the only pure part of this command untestable
+// without a server.
+//
+// `licenseRecord` is optional: without an active one (dev, or pre-launch while
+// the gate is dormant) nothing is watermarked and no receipt is written.
+export function assemblePlugin({ packageRoot, destDir, entries, licenseRecord, now = () => new Date().toISOString() }) {
+  mkdirSync(destDir, { recursive: true });
+
+  // 1. Write the content library into the dir. Every file is rewritten from the
+  //    kit, so step 3 always stamps a clean copy — re-running cannot
+  //    double-stamp.
+  const written = [];
+  for (const { path, content } of entries) {
+    const abs = join(destDir, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content, 'utf8');
+    written.push({ path, abs });
+  }
+
+  // 2. Copy the plaintext CLI parts alongside it.
+  for (const part of PLAINTEXT_PLUGIN_PARTS) {
+    const src = join(packageRoot, part);
+    if (existsSync(src)) cpSync(src, join(destDir, part), { recursive: true });
+  }
+
+  // 3. Watermark the content so a copied directory stays traceable to the seat
+  //    it came from. SKILL.md only: appending to a YAML archetype risks tripping
+  //    cfn-lint, and markdown renders an HTML comment invisibly.
+  const stamp = contentWatermark(licenseRecord);
+  if (stamp) {
+    for (const { path, abs } of written) {
+      if (!path.endsWith('/SKILL.md')) continue;
+      const body = readFileSync(abs, 'utf8');
+      if (body.includes(stamp)) continue;
+      writeFileSync(abs, `${body.replace(/\s*$/, '')}\n\n${stamp}\n`, 'utf8');
+    }
+    writeFileSync(join(destDir, RECEIPT_FILENAME), licensedToBody(licenseRecord, now()), 'utf8');
+  }
+
+  // 4. Manifest: sha256 of every file written, so a later upgrade/uninstall can
+  //    tell our files from anything the user added (the AgentKit pattern).
+  const rels = [];
+  walkRel(destDir, destDir, rels);
+  const files = rels
+    .filter((r) => !MANIFEST_EXCLUDED.has(r))
+    .sort()
+    .map((r) => ({ path: r, sha256: sha256File(join(destDir, r)) }));
+  const manifest = { v: 1, files };
+  writeFileSync(join(destDir, 'install-manifest.json'), JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+export default async function initPlugin({ scope = 'global' } = {}, {
+  packageRoot = PACKAGE_ROOT,
+  homedir = osHomedir,
+  client = resolveClient(),
+  readLicense = storeRead,
+  runClaude = defaultRunClaude,
+  getKit = obtainKit,
+  log = (m) => logger.ok(m),
+} = {}) {
+  // Gate first — refuse before touching disk when enforcement is on.
+  await assertLicensed({ command: 'init-plugin', client, readLicense });
+
+  const vendorHome = join(homedir(), '.clawform');
+  const pluginDir = join(vendorHome, 'plugin');
+  logger.step('clawform init plugin');
+
+  // Fetch (or reuse the cached) kit before writing anything: a service failure
+  // should leave the existing plugin dir exactly as it was, not half-replaced.
+  const entries = await getKit({
+    licenseKey: readLicense()?.key,
+    serviceUrl: KIT_SERVICE_URL,
+    cacheDir: vendorHome,
+  });
+
+  assemblePlugin({ packageRoot, destDir: pluginDir, entries, licenseRecord: readLicense() });
+  log(`Plugin materialized at ${pluginDir}`);
+
+  // Register with Claude Code. The exact marketplace/scope flags are Claude
+  // Code semantics that must be confirmed against a live install (clean-room
+  // C3) — the runner is injected so this stays testable, and --project vs
+  // --global is passed through for that verification.
+  const scopeFlag = scope === 'project' ? ['--project'] : [];
+  const add = await runClaude(['plugin', 'marketplace', 'add', pluginDir, ...scopeFlag]);
+  if (add.code !== 0) throw new Error(`claude plugin marketplace add failed: ${add.stderr ?? `exit ${add.code}`}`);
+  const install = await runClaude(['plugin', 'install', 'clawform@clawform', ...scopeFlag]);
+  if (install.code !== 0) throw new Error(`claude plugin install failed: ${install.stderr ?? `exit ${install.code}`}`);
+
+  log(`Clawform plugin installed (${scope}). Restart Claude Code to pick it up.`);
+}
+
+async function defaultRunClaude(args) {
+  const { execa } = await import('execa');
+  try {
+    const r = await execa('claude', args, { reject: false });
+    return { code: r.exitCode, stderr: r.stderr };
+  } catch (err) {
+    // `claude` not on PATH is the common case — report it as a failed run, not
+    // a thrown stack trace, so the command's own error message can guide.
+    return { code: 127, stderr: err?.shortMessage ?? String(err) };
+  }
+}