@thejoseki/clawform 0.0.1 → 2.2.0

package/src/commands/activate.js

@@ -0,0 +1,105 @@
+// clawform activate <key> — claim one activation slot for this machine and
+// cache the verdict locally. All I/O seams are injectable for the tests; the
+// CLI passes nothing and gets the real store, fingerprint and vendor client.
+
+import { logger } from '../lib/logger.js';
+import { resolveClient, resolveTrialBenefitIds } from '../lib/license-client.js';
+import { writeLicense } from '../lib/license-store.js';
+import { machineFingerprint } from '../lib/fingerprint.js';
+import { claimTrialDevice } from '../lib/trial-claim.js';
+
+const maskKey = (key) => `…${String(key).slice(-4)}`;
+
+export default async function activate({ key } = {}, {
+  client = resolveClient(),
+  write = writeLicense,
+  fingerprint = machineFingerprint,
+  trialBenefitIds = resolveTrialBenefitIds(),
+  claimTrial = claimTrialDevice,
+  now = Date.now,
+  log = (m) => logger.ok(m),
+} = {}) {
+  if (!key || typeof key !== 'string') {
+    throw new Error('A license key is required: clawform activate <key> (it is in your purchase email).');
+  }
+
+  const fp = fingerprint();
+
+  // Which tier this key belongs to decides whether our own service is consulted
+  // at all. A PAID activation must never depend on it: someone who has just
+  // paid, blocked by our downtime, is the failure the deploy/rollback invariant
+  // exists to prevent — moved to the worst possible moment.
+  //
+  // Costs one extra validate call. That is a once-per-machine command, and the
+  // alternative is threading a callback through the vendor adapter so the
+  // branch can happen mid-activation.
+  let pre = null;
+  try { pre = await client.validate(key); } catch { /* fall through to activate, which reports it */ }
+
+  if (pre?.status === 'valid' && trialBenefitIds.includes(pre.benefitId)) {
+    // Claim BEFORE the slot is taken. A device refused after activation would
+    // keep the activation it had already spent.
+    //
+    // Fail-open on any error: our downtime must cost a lead, never a purchase.
+    // The window allows 14 more days of the cheap CLI commands — a far smaller
+    // loss than a would-be buyer who hit an error once and never came back.
+    let claim = { allowed: true };
+    try { claim = await claimTrial({ licenseKey: key, fingerprint: fp }); } catch { /* fail open */ }
+
+    if (claim && claim.allowed === false) {
+      throw new Error(
+        'This machine has already used a Clawform trial, so a second one cannot start here. '
+        + 'Buy a seat at https://clawform.thejoseki.com — or, if you believe this is a mistake, '
+        + 'write to support@thejoseki.com and it will be sorted out by a person.',
+      );
+    }
+  }
+
+  // Hand the walk we already paid for to the adapter, so it does not repeat it.
+  // Without this one command made about ten Polar calls and got rate-limited.
+  const res = await client.activate(key, fp, pre?.status === 'valid' ? { validated: pre } : {});
+
+  if (res.status === 'valid') {
+    write({
+      status: 'active',
+      key,
+      instanceId: res.instanceId,
+      holder: res.holder,
+      fingerprint: fp,
+      lastValidatedAt: new Date(now()).toISOString(),
+      // Only when the vendor gave one. A perpetual seat carrying
+      // `expiresAt: undefined` would read as "expired at the epoch" to the
+      // gate's date arithmetic — every paying customer refused on day one.
+      ...(res.expiresAt ? { expiresAt: res.expiresAt } : {}),
+    });
+    log(`License ${maskKey(key)} activated on this machine${res.holder ? ` for ${res.holder}` : ''}.`);
+    return;
+  }
+
+  if (res.status === 'invalid') {
+    if (res.reason === 'limit_reached') {
+      throw new Error(
+        'This key has used all of its activation slots. Free one with `clawform deactivate` on a ' +
+        'machine you no longer use — CI should use the CLAWFORM_LICENSE_KEY env var, which never ' +
+        'takes a slot.',
+      );
+    }
+    throw new Error(`The license service rejected this key (${res.reason ?? 'invalid'}). Check for typos in the key from your purchase email.`);
+  }
+
+  // Throttling reads as unreachable to the generic branch below, and its
+  // advice — "try again once you are online" — is false for someone who is
+  // online and whose own retries caused this. Say what happened instead.
+  if (res.reason === 'rate_limited') {
+    throw new Error(
+      'The license service is rate-limiting this key. Nothing was activated. ' +
+      'Wait about a minute and run the same command again — repeating it immediately ' +
+      'extends the limit rather than clearing it.',
+    );
+  }
+
+  throw new Error(
+    `Could not reach the license service (${res.reason ?? 'network error'}). ` +
+    'Nothing was activated — try again once you are online.',
+  );
+}

package/src/commands/ci-init.js

@@ -0,0 +1,212 @@
+// clawform ci init — generate a .gitlab-ci.yml for the Clawform CI model:
+// GitLab On-Prem is the source of truth; AWS just runs the pipeline.
+//
+//   validate (every MR, offline)  →  deploy:upload (protected branch)
+//   - validate: cfn-lint the cfn/ templates on a GitLab Runner. No AWS creds,
+//     so it's safe on any runner and fast on every merge request. cfn-lint is
+//     the CI floor — local `clawform validate` adds cfn-guard + cfn-nag +
+//     lint-overrides on top; the generated file says so.
+//   - deploy:upload: zip the repo and put it to the pipeline's SourceBucket as
+//     source.zip, which triggers the CodePipeline stood up by
+//     templates/cicd-pipeline.yaml (validate → manual approval → execute).
+//
+// The CLI writes the file and prints the next steps; it does NOT touch AWS.
+// renderGitlabCi() is a pure string builder so it's unit-tested without I/O.
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { logger } from '../lib/logger.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const BUCKET_PLACEHOLDER = '<PIPELINE_SOURCE_BUCKET>';
+
+export function renderGitlabCi({ cfnDir = 'cfn', branch = 'main', sourceBucket } = {}) {
+  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
+  return `# Generated by \`clawform ci init\`. Clawform CI for GitLab On-Prem.
+# Model: GitLab is the source of truth; AWS runs the pipeline. The protected
+# branch uploads a source bundle to S3, which triggers the CodePipeline from
+# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
+#
+# Required CI/CD variables (Settings -> CI/CD -> Variables), protected + masked:
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
+#     s3:PutObject on the pipeline SourceBucket (or use a runner instance role)
+#   AWS_DEFAULT_REGION                          -> the pipeline's region
+
+stages:
+  - validate
+  - deploy
+
+# Every merge request: lint the templates. Offline — no AWS credentials needed.
+# NOTE: cfn-lint is the CI *floor*. Local \`clawform validate\` additionally runs
+# cfn-guard (the shipped rules.guard, incl. the Rule #4 retention checks) and
+# cfn-nag — run it before merging; green CI is not the same as a green /validate.
+validate:cfn:
+  stage: validate
+  image: python:3.12-slim
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  cache:
+    key: clawform-pip
+    paths:
+      - .cache/pip
+  script:
+    - pip install --quiet cfn-lint
+    - cfn-lint ${cfnDir}/*.yaml
+
+# Protected branch only: bundle the repo and hand it to the pipeline. CodePipeline
+# re-validates, builds a change-set, and waits for a human to approve in the
+# CodePipeline console before executing (Rule #5 approval gate, off-TTY).
+# The entrypoint override is REQUIRED: amazon/aws-cli's Docker ENTRYPOINT is the
+# aws binary itself, so without it the runner cannot start a shell in the container.
+deploy:upload:
+  stage: deploy
+  image:
+    name: amazon/aws-cli:latest
+    entrypoint: [""]
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "${branch}"'
+  before_script:
+    - yum install -y -q zip
+  script:
+    # Bundle the template dir plus the optional config/params paths that exist.
+    # Built explicitly (no stderr suppression, no || fallback) so a real zip
+    # failure fails the job instead of uploading a partial bundle.
+    - BUNDLE_PATHS="${cfnDir}"
+    - for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
+    - echo "Bundling: $BUNDLE_PATHS"
+    - zip -r source.zip $BUNDLE_PATHS
+    - aws s3 cp source.zip "s3://${bucket}/source.zip"
+  # The pipeline takes over from here — approve the change-set in CodePipeline.
+`;
+}
+
+// Same Git → S3 → CodePipeline model as the GitLab variant, expressed as a
+// GitHub Actions workflow. Pure string builder, unit-tested without I/O.
+export function renderGithubActions({ cfnDir = 'cfn', branch = 'main', sourceBucket } = {}) {
+  const bucket = sourceBucket || BUCKET_PLACEHOLDER;
+  return `# Generated by \`clawform ci init --provider github\`. Clawform CI for GitHub.
+# Model: GitHub is the source of truth; AWS runs the pipeline. The protected
+# branch uploads a source bundle to S3, which triggers the CodePipeline from
+# templates/cicd-pipeline.yaml (validate -> manual approval -> execute).
+#
+# Required repository secrets (Settings -> Secrets and variables -> Actions):
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY  -> an IAM user scoped to
+#     s3:PutObject on the pipeline SourceBucket
+#   AWS_DEFAULT_REGION                          -> the pipeline's region
+
+name: clawform-cfn
+
+on:
+  pull_request:
+  push:
+    branches: [ ${branch} ]
+
+jobs:
+  # Every pull request: lint the templates. Offline — no AWS credentials.
+  # NOTE: cfn-lint is the CI floor. Local \`clawform validate\` additionally runs
+  # cfn-guard (rules.guard, incl. Rule #4 retention) and cfn-nag — green CI is
+  # not the same as a green /validate.
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install --quiet cfn-lint
+      - run: cfn-lint ${cfnDir}/*.yaml
+
+  # Protected branch only: bundle the repo and hand it to the pipeline, which
+  # re-validates, builds a change-set, and waits for a human to approve in the
+  # CodePipeline console before executing (Rule #5 approval gate, off-TTY).
+  upload:
+    if: github.ref == 'refs/heads/${branch}'
+    needs: validate
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: \${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_DEFAULT_REGION: \${{ secrets.AWS_DEFAULT_REGION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Bundle and upload source
+        run: |
+          # Bundle the template dir plus the optional config/params paths that
+          # exist. Built explicitly (no stderr suppression, no || fallback) so a
+          # real zip failure fails the job instead of uploading a partial bundle.
+          BUNDLE_PATHS="${cfnDir}"
+          for p in clawform.config.json params; do [ -e "$p" ] && BUNDLE_PATHS="$BUNDLE_PATHS $p"; done
+          echo "Bundling: $BUNDLE_PATHS"
+          zip -r source.zip $BUNDLE_PATHS
+          aws s3 cp source.zip "s3://${bucket}/source.zip"
+      # The pipeline takes over from here — approve the change-set in CodePipeline.
+`;
+}
+
+export default async function ciInit({ sourceBucket, cfnDir = 'cfn', branch = 'main', force, projectDir, provider = 'gitlab' } = {}) {
+  await assertLicensed({ command: 'ci-init', client: resolveLicenseClient() });
+  const dir = projectDir || process.cwd();
+
+  // Provider decides both the rendered content and where it lands. Default is
+  // gitlab so the pre-existing call shape keeps working.
+  const isGithub = provider === 'github';
+  const content = isGithub
+    ? renderGithubActions({ cfnDir, branch, sourceBucket })
+    : renderGitlabCi({ cfnDir, branch, sourceBucket });
+
+  const primary = isGithub
+    ? join(dir, '.github', 'workflows', 'clawform-cfn.yml')
+    : join(dir, '.gitlab-ci.yml');
+  const sample = isGithub
+    ? join(dir, '.github', 'workflows', 'clawform-cfn.clawform.yml')
+    : join(dir, '.gitlab-ci.clawform.yml');
+
+  await mkdir(dirname(primary), { recursive: true });
+  const exists = existsSync(primary);
+  // Never clobber an existing pipeline config silently — write a sample alongside
+  // it and let the user merge, unless they explicitly asked to overwrite.
+  const target = exists && !force ? sample : primary;
+  await writeFile(target, content, 'utf8');
+
+  logger.step(`clawform ci init`);
+  if (target === primary) {
+    logger.ok(`Wrote ${target}`);
+  } else {
+    logger.warn(`${primary} already exists — wrote a sample to ${target} instead. Merge it in (or re-run with --force to overwrite).`);
+  }
+
+  logger.info('');
+  logger.info('Next steps:');
+  logger.info('  1. Stand up the pipeline stack FIRST (it creates the SourceBucket this CI uploads to):');
+  logger.info('       clawform deploy templates/cicd-pipeline.yaml <env> \\');
+  logger.info('         --stack-name <env>-<customer>-<project>-pipeline --project <project> \\');
+  logger.info('         --params params/<env>-pipeline.json --capabilities CAPABILITY_NAMED_IAM');
+  logger.info('     The params file must set ALL template parameters: EnvName, CustomerName, ProjectName,');
+  logger.info('     TargetStackName, TemplatePathInBundle, ApprovalEmail, CfnDeployRoleArn');
+  if (cfnDir !== 'cfn') {
+    logger.info(`     — and CfnDirInBundle="${cfnDir}" (you used --cfn-dir, so the pipeline's lint stage must match).`);
+  } else {
+    logger.info('     (CfnDirInBundle defaults to "cfn" and matches this CI file).');
+  }
+  if (!sourceBucket) {
+    logger.warn(`  2. Replace ${BUCKET_PLACEHOLDER} in the generated file with the stack's SourceBucketName output`);
+    logger.info('     (or re-run: clawform ci init --source-bucket <name> --force).');
+  } else {
+    logger.info(`  2. SourceBucket is set to "${sourceBucket}".`);
+  }
+  logger.info('  3. In GitLab → Settings → CI/CD → Variables, add (protected + masked):');
+  logger.info('       AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (IAM user scoped to s3:PutObject on the bucket),');
+  logger.info('       AWS_DEFAULT_REGION.');
+  logger.info('  4. Know the pipeline\'s limits: it enforces the Rule #5 SHAPE (changeset → approval → execute)');
+  logger.info('     but NOT the CLI\'s other gates (account guard, legacy-freeze, export-lock, data-resource');
+  logger.info('     retype). The approver MUST open the change-set link and check for Replace on data');
+  logger.info('     resources before approving. Details: templates/cicd-pipeline.yaml header.');
+  logger.info('  5. Older account that still has CodeCommit and prefers a Git mirror? Point GitLab repository');
+  logger.info('     mirroring at a CodeCommit repo and swap the pipeline Source action to CodeCommit — see');
+  logger.info('     the prose header in templates/cicd-pipeline.yaml.');
+}

package/src/commands/cost-report.js

@@ -0,0 +1,166 @@
+// clawform cost-report — month-to-date AWS spend, grouped by the Project / Env /
+// CostCenter tag (or by service). The POST-deploy half of cost governance:
+// cost-guard estimates before you commit a resource; this reads Cost Explorer
+// for what actually got billed, so a team without a FinOps function can see the
+// real number broken down the same way their stacks are tagged.
+//
+// Cost Explorer is a GLOBAL service with only a us-east-1 endpoint — the client
+// is pinned there regardless of the project's deploy region, and (unlike the
+// CFN commands) no AWS_REGION/AWS_PROFILE is *required*: the SDK's default
+// credential chain (env keys, SSO, instance role) is enough, which matters for
+// CI/cron use. CE bills ~$0.01 per GetCostAndUsage request; one logical query
+// per invocation (followed across NextPageToken pages — truncating silently
+// would understate the TOTAL, the one number this command exists to get right).
+//
+// Pure helpers (monthRange / groupByDef / parseCostRows / renderRows) are
+// exported and unit-tested without AWS; costReport() is the thin SDK wrapper.
+
+import { CostExplorerClient, GetCostAndUsageCommand } from '@aws-sdk/client-cost-explorer';
+import { logger } from '../lib/logger.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const GROUP_BY = {
+  project: { Type: 'TAG', Key: 'Project' },
+  env: { Type: 'TAG', Key: 'Env' },
+  costcenter: { Type: 'TAG', Key: 'CostCenter' },
+  service: { Type: 'DIMENSION', Key: 'SERVICE' },
+};
+
+// Resolve the CE GroupBy definition. Defaults to the Project tag — the grouping
+// that matches how every clawform deploy tags its stacks (rules/tagging.md).
+export function groupByDef(groupBy = 'project') {
+  const key = String(groupBy).toLowerCase();
+  const def = GROUP_BY[key];
+  if (!def) {
+    throw new Error(`Unknown --group-by "${groupBy}". Expected one of: ${Object.keys(GROUP_BY).join(' | ')}.`);
+  }
+  return { key, def };
+}
+
+function pad2(n) { return String(n).padStart(2, '0'); }
+function ymd(d) { return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`; }
+
+// Compute the CE TimePeriod for a month. `month` is 'YYYY-MM' (defaults to the
+// month containing `today`). CE's End is EXCLUSIVE and may not be in the future,
+// so for the current month we clamp End to tomorrow (month-to-date); for a past
+// month End is the first of the next month (the full month).
+//
+// `today` is injected so the computation is deterministic in tests.
+export function monthRange(month, today) {
+  const now = today instanceof Date ? today : new Date();
+  let year, mon; // mon is 1-12
+  if (month) {
+    const m = /^(\d{4})-(\d{2})$/.exec(String(month).trim());
+    if (!m) throw new Error(`Invalid --month "${month}". Expected YYYY-MM.`);
+    year = Number(m[1]);
+    mon = Number(m[2]);
+    if (mon < 1 || mon > 12) throw new Error(`Invalid month number in "${month}".`);
+  } else {
+    year = now.getUTCFullYear();
+    mon = now.getUTCMonth() + 1;
+  }
+
+  const start = new Date(Date.UTC(year, mon - 1, 1));
+  const nextMonthFirst = new Date(Date.UTC(year, mon, 1));
+  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+
+  if (start >= tomorrow) {
+    throw new Error(`Month ${year}-${pad2(mon)} is in the future — no cost data yet.`);
+  }
+  const end = nextMonthFirst < tomorrow ? nextMonthFirst : tomorrow;
+  // "partial" = the reported month is still accruing charges, i.e. it's the
+  // current UTC month — NOT "end was clamped": on the month's last day the
+  // clamp is a no-op (tomorrow == nextMonthFirst) but today's spend is still
+  // incomplete, and the label must say so. All date math is UTC because Cost
+  // Explorer's day boundaries are UTC.
+  const partial = year === now.getUTCFullYear() && mon === now.getUTCMonth() + 1;
+  return { Start: ymd(start), End: ymd(end), label: `${year}-${pad2(mon)}`, partial };
+}
+
+// Flatten a CE GetCostAndUsage response into sorted rows. Sums each group key
+// across every period returned (we use MONTHLY granularity, so usually one).
+// TAG group keys arrive as "Project$value" — strip to the value; an empty value
+// becomes "(untagged)" so unallocated spend is visible, not hidden.
+export function parseCostRows(response) {
+  const totals = new Map();
+  let unit = 'USD';
+  for (const period of response?.ResultsByTime ?? []) {
+    for (const g of period.Groups ?? []) {
+      const rawKey = g.Keys?.[0] ?? '';
+      const value = rawKey.includes('$') ? rawKey.slice(rawKey.indexOf('$') + 1) : rawKey;
+      const key = value === '' ? '(untagged)' : value;
+      const metric = g.Metrics?.UnblendedCost ?? {};
+      const amount = Number(metric.Amount ?? 0);
+      if (metric.Unit) unit = metric.Unit;
+      totals.set(key, (totals.get(key) ?? 0) + (Number.isFinite(amount) ? amount : 0));
+    }
+  }
+  const rows = [...totals.entries()]
+    .map(([key, amount]) => ({ key, amount, unit }))
+    .sort((a, b) => b.amount - a.amount);
+  const total = rows.reduce((s, r) => s + r.amount, 0);
+  return { rows, total, unit };
+}
+
+export function renderRows({ rows, total, unit }, meta) {
+  const lines = [];
+  const span = meta.partial ? `${meta.label} (month-to-date)` : meta.label;
+  lines.push(`Cost by ${meta.groupBy} — ${span} — ${meta.Start} → ${meta.End} (exclusive)`);
+  lines.push('');
+  if (rows.length === 0) {
+    lines.push('  (no cost data for this period)');
+    return lines.join('\n');
+  }
+  const width = Math.max(8, ...rows.map((r) => r.key.length));
+  for (const r of rows) {
+    lines.push(`  ${r.key.padEnd(width)}  ${r.amount.toFixed(2).padStart(10)} ${r.unit}`);
+  }
+  lines.push('');
+  lines.push(`  ${'TOTAL'.padEnd(width)}  ${total.toFixed(2).padStart(10)} ${unit}`);
+
+  const untagged = rows.find((r) => r.key === '(untagged)');
+  if (untagged && total > 0 && untagged.amount / total > 0.5 && meta.def.Type === 'TAG') {
+    lines.push('');
+    lines.push(
+      `  Note: >50% of spend is (untagged) for tag "${meta.def.Key}". Activate it under ` +
+      `Billing → Cost allocation tags so per-${meta.groupBy} breakdown becomes meaningful ` +
+      `(activation is not retroactive).`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export default async function costReport({ month, groupBy, profile, today } = {}) {
+  await assertLicensed({ command: 'cost-report', client: resolveLicenseClient() });
+  const { key, def } = groupByDef(groupBy);
+  const range = monthRange(month, today);
+
+  // Unlike the CFN commands, no profile/region is REQUIRED here: CE is global
+  // (us-east-1) and the SDK's default credential chain covers env keys / SSO /
+  // instance roles — the common CI shapes. An explicit --profile still wins.
+  if (profile) process.env.AWS_PROFILE = profile;
+
+  const client = new CostExplorerClient({ region: 'us-east-1' });
+
+  logger.step(`clawform cost-report — ${range.label} by ${key}`);
+
+  // GetCostAndUsage paginates via NextPageToken; follow it — a truncated group
+  // list silently understates the TOTAL.
+  const results = [];
+  let nextPageToken;
+  do {
+    const resp = await client.send(new GetCostAndUsageCommand({
+      TimePeriod: { Start: range.Start, End: range.End },
+      Granularity: 'MONTHLY',
+      Metrics: ['UnblendedCost'],
+      GroupBy: [def],
+      ...(nextPageToken ? { NextPageToken: nextPageToken } : {}),
+    }));
+    results.push(...(resp.ResultsByTime ?? []));
+    nextPageToken = resp.NextPageToken;
+  } while (nextPageToken);
+
+  const parsed = parseCostRows({ ResultsByTime: results });
+  console.log(renderRows(parsed, { ...range, groupBy: key, def }));
+}

package/src/commands/deactivate.js

@@ -0,0 +1,36 @@
+// clawform deactivate — release this machine's activation slot and clear the
+// local cache. Local-first: the cache clears even when the vendor can't be
+// reached, because the buyer's next step (activate elsewhere) needs this
+// machine forgotten locally either way — we just warn that the vendor-side
+// slot may still be counted until support or a later retry releases it.
+
+import { logger } from '../lib/logger.js';
+import { resolveClient } from '../lib/license-client.js';
+import { readLicense, clearLicense } from '../lib/license-store.js';
+
+export default async function deactivate(_opts = {}, {
+  client = resolveClient(),
+  read = readLicense,
+  clear = clearLicense,
+  log = (m) => logger.ok(m),
+  warn = (m) => logger.warn(m),
+} = {}) {
+  const record = read();
+  if (record.status !== 'active' || !record.key) {
+    log('Nothing to deactivate — no license is active on this machine.');
+    return;
+  }
+
+  const res = await client.deactivate(record.key, record.instanceId);
+  clear();
+
+  if (res.status === 'valid') {
+    log('License deactivated — the activation slot is free for another machine.');
+    return;
+  }
+  warn(
+    'The local license was cleared, but the license service could not confirm the release ' +
+    `(${res.reason ?? res.status}) — the activation slot may still be counted. ` +
+    'Rerun `clawform activate` here later to reclaim it, or contact support.',
+  );
+}