@thejoseki/clawform 2.3.0 → 2.3.1

package/README.md

@@ -16,7 +16,7 @@ operations and the stacks you've marked frozen are refused.
 CloudFormation only — by design. Not Terraform, not CDK, not Pulumi.
 
 **Try it free for 14 days** — the full kit, email-only checkout, no card:
-<https://clawform.thejoseki.com>. When the trial lapses, `deploy` and
+<https://clawform.thejoseki.com/?utm_source=npm>. When the trial lapses, `deploy` and
 `rollback` keep working; an expired licence never strands a stack.
 
 ## Quickstart (10 minutes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejoseki/clawform",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Clawform — safe CloudFormation workflows for Claude Code",
   "homepage": "https://clawform.thejoseki.com",
   "type": "module",

package/src/commands/activate.js

@@ -1,105 +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.',
-  );
-}
+// 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/?utm_source=cli — 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/lib/license.js

@@ -1,150 +1,150 @@
-// 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(
-      // The one message every npm installer without a key will read — the only
-      // audience the product reliably has. It leads with the door that costs
-      // nothing, then the one for a key already bought.
-      `'clawform ${command}' needs an activated license. ` +
-      'New here? There is a free 14-day trial — full kit, no card — at https://clawform.thejoseki.com. ' +
-      'Already have a key (trial or purchase email)? Run: clawform activate <key>',
-    );
-  }
-
-  // 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.',
-  );
-}
+// 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(
+      // The one message every npm installer without a key will read — the only
+      // audience the product reliably has. It leads with the door that costs
+      // nothing, then the one for a key already bought.
+      `'clawform ${command}' needs an activated license. ` +
+      'New here? There is a free 14-day trial — full kit, no card — at https://clawform.thejoseki.com/?utm_source=cli. ' +
+      'Already have a key (trial or purchase email)? Run: clawform activate <key>',
+    );
+  }
+
+  // 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/?utm_source=cli 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.',
+  );
+}