@thejoseki/clawform 0.0.1 → 2.2.1

package/src/lib/providers/polar.js

@@ -0,0 +1,215 @@
+// Polar adapter for the vendor-agnostic license client. Maps the Polar
+// customer-portal license-key API onto {status: valid|invalid|error}.
+//
+// The customer-portal endpoints authenticate with the license key + the
+// organization id alone — there is NO server secret to embed, which is why the
+// adapter can ship in a public tarball. Endpoints and error mapping verified
+// against polarsource/polar (2026-07):
+//   activate/validate/deactivate under /v1/customer-portal/license-keys/
+//   NotPermitted → 403 (limit reached / expired), ResourceNotFound → 404.
+
+const PATH = '/v1/customer-portal/license-keys';
+
+// A 403 body distinguishes "no slots left" from "expired" by its message; both
+// are terminal (status:'invalid') but the reason drives a different hint.
+function classify403(body) {
+  const detail = String(body?.detail ?? '').toLowerCase();
+  if (detail.includes('expired')) return 'expired';
+  if (detail.includes('limit')) return 'limit_reached';
+  return 'not_permitted';
+}
+
+// Polar answers 404 both for a key that does not exist and for a key that
+// belongs to a different product ("License key does not match given benefit.",
+// observed live). Collapsing them tells a buyer with a perfectly valid key to
+// go hunting for typos.
+function classify404(body) {
+  const detail = String(body?.detail ?? '').toLowerCase();
+  if (detail.includes('benefit')) return 'wrong_product';
+  return 'not_found';
+}
+
+export function createPolarClient({
+  fetch: fetchImpl = fetch,
+  baseUrl,
+  organizationId,
+  benefitIds,
+  ...rest
+} = {}) {
+  // `benefitId` (singular) was this option's name until tiers arrived. Left
+  // unhandled it destructures away, leaves the list empty, and yields a client
+  // that enforces nothing — a key from any product in the organization would
+  // then activate. Refuse loudly instead: a crash in the licence path is
+  // fail-closed, and silence here is the failure mode with no symptom.
+  if ('benefitId' in rest) {
+    throw new Error('createPolarClient: `benefitId` was superseded by `benefitIds` (a list, one entry per paid tier).');
+  }
+
+  // One benefit per paid tier: Polar carries limit_activations on the benefit,
+  // so a 3-device seat and a 10-device team seat cannot share one. A key is
+  // accepted when it matches ANY of them.
+  //
+  // A bare string is wrapped rather than ignored. Ignoring it would turn a
+  // config mistake into a client that enforces nothing — silently permissive is
+  // the one failure this whole check exists to prevent.
+  const ids = benefitIds == null ? [] : (Array.isArray(benefitIds) ? benefitIds : [benefitIds]);
+
+  // Which product this key was bought for. Polar nests it differently per
+  // endpoint: activate returns an activation with the licence inside, validate
+  // returns the licence itself. Reading both here keeps the asymmetry in one
+  // place instead of in each caller.
+  const wrongProduct = (body) => {
+    if (!ids.length) return false; // unset: constructor used in isolation
+    const found = body?.benefit_id ?? body?.license_key?.benefit_id;
+    return Boolean(found) && !ids.includes(found);
+  };
+
+  async function post(endpoint, body) {
+    // Any thrown fetch (DNS, connection, timeout), a 5xx, or a 429 is an
+    // OUTAGE or a throttle, not a rejection — it maps to 'error' so the
+    // caller's offline grace applies. Only a deliberate 403/404 from Polar is
+    // 'invalid'.
+    let resp;
+    try {
+      resp = await fetchImpl(`${baseUrl}${PATH}/${endpoint}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ organization_id: organizationId, ...body }),
+      });
+    } catch (err) {
+      return { kind: 'error', reason: err?.message ?? 'network error' };
+    }
+    if (resp.status >= 500) return { kind: 'error', reason: `HTTP ${resp.status}` };
+    // Throttling, observed against the live API when calls come in a burst.
+    // Named rather than passed through as a status code: the caller's generic
+    // error text tells the user to retry "once you are online", which is
+    // false here and unhelpful to someone whose retries caused it.
+    if (resp.status === 429) return { kind: 'error', reason: 'rate_limited' };
+    let json = {};
+    try { json = await resp.json(); } catch { /* empty body (e.g. 204) is fine */ }
+    return { kind: 'http', status: resp.status, ok: resp.ok, body: json };
+  }
+
+  // Asking the vendor to enforce the product beats comparing its answer.
+  // `benefit_id` is a documented request field and Polar rejects a mismatch
+  // with 404 "License key does not match given benefit." — verified live.
+  // Sent only when configured, so the constructor stays usable in isolation.
+  async function validateOnce(key, activationId, benefitId) {
+    const body = activationId ? { key, activation_id: activationId } : { key };
+    return post('validate', benefitId ? { ...body, benefit_id: benefitId } : body);
+  }
+
+  // A request carries one benefit, so several tiers means several attempts.
+  //
+  // Two stopping rules, both about not lying to the caller:
+  //
+  //   - Anything that is not a flat rejection ends the walk immediately. An
+  //     unreachable vendor must stay 'error', because that is what the 14-day
+  //     offline grace keys off; continuing and reporting whatever the last tier
+  //     said would lock a paying customer out during someone else's outage.
+  //   - A rejection that describes the KEY — it does not exist, it expired, it
+  //     is out of slots — is authoritative whatever tier answered, so it wins
+  //     over a mere "not this benefit". Only 'wrong_product' is worth retrying,
+  //     because only it is a statement about the benefit rather than the key.
+  // A successful walk also reports WHICH benefit answered. That is not
+  // bookkeeping: it is how a caller tells a trial key from a paid one, and
+  // therefore whether the vendor's own delivery service may be consulted at
+  // all. Deriving it a second time at the call site would mean a second copy of
+  // the tier list, which is the drift this whole module exists to prevent.
+  async function validateAcrossBenefits(key, activationId) {
+    if (!ids.length) return fromValidate(await validateOnce(key, activationId, null));
+
+    let last;
+    for (const benefitId of ids) {
+      const res = fromValidate(await validateOnce(key, activationId, benefitId));
+      if (res.status === 'valid') return { ...res, benefitId };
+      if (res.status !== 'invalid') return res;
+      if (res.reason !== 'wrong_product') return res;
+      last = res;
+    }
+    return last;
+  }
+
+  // Observed live: Polar puts `expires_at` on the 200 for a key that is still
+  // valid, so a trial's end date is known at activation rather than discovered
+  // when it lapses. Omitted entirely when the vendor gives none — a perpetual
+  // seat with `expiresAt: undefined` would read as "expired at the epoch" to
+  // anything doing date arithmetic.
+  const expiryOf = (body) => {
+    const at = body?.expires_at ?? body?.license_key?.expires_at;
+    return at ? { expiresAt: at } : {};
+  };
+
+  function fromValidate(r) {
+    if (r.kind === 'error') return { status: 'error', reason: r.reason };
+    if (r.ok) {
+      // Secondary, and fail-open by design: the server is authoritative, and
+      // a response that simply omits the field must not lock a buyer out.
+      if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
+      return { status: 'valid', ...expiryOf(r.body) };
+    }
+    if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
+    if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
+    return { status: 'error', reason: `HTTP ${r.status}` };
+  }
+
+  return {
+    configured: true,
+
+    async activate(key, fingerprint, { validated } = {}) {
+      // Prove the product BEFORE asking Polar to create anything. Checking the
+      // activate response is too late: the activation already exists, and it
+      // spent a slot on the other product's key. The person penalised is that
+      // product's paying customer, for running one wrong command.
+      //
+      // `validated` lets a caller that has ALREADY walked the list hand the
+      // answer over instead of paying for it twice. The CLI's activate has to
+      // validate first anyway — it branches on the matched benefit to decide
+      // whether the trial-claim service is consulted — and the duplication cost
+      // a real activation a 429. Opt-in, never the default: supply nothing and
+      // the pre-check still runs.
+      //
+      // The matched tier is carried through rather than re-derived from the
+      // activate response — the two endpoints nest the field differently, and
+      // one of the two paths is always the one that gets forgotten.
+      let benefitId;
+      let expiry = {};
+      if (ids.length) {
+        const pre = validated ?? await validateAcrossBenefits(key);
+        if (pre.status !== 'valid') return pre;
+        benefitId = pre.benefitId;
+        // The validate response is where the expiry lives; the activate
+        // response describes an activation, not the licence behind it.
+        if (pre.expiresAt) expiry = { expiresAt: pre.expiresAt };
+      }
+
+      const r = await post('activate', { key, label: `clawform ${fingerprint}` });
+      if (r.kind === 'error') return { status: 'error', reason: r.reason };
+      if (r.ok) {
+        if (wrongProduct(r.body)) return { status: 'invalid', reason: 'wrong_product' };
+        return {
+          status: 'valid',
+          instanceId: r.body?.id,
+          holder: r.body?.license_key?.customer?.email,
+          ...(benefitId ? { benefitId } : {}),
+          ...expiry,
+          ...expiryOf(r.body),
+        };
+      }
+      if (r.status === 403) return { status: 'invalid', reason: classify403(r.body) };
+      if (r.status === 404) return { status: 'invalid', reason: classify404(r.body) };
+      return { status: 'error', reason: `HTTP ${r.status}` };
+    },
+
+    async validate(key, activationId) {
+      return validateAcrossBenefits(key, activationId);
+    },
+
+    async deactivate(key, activationId) {
+      const r = await post('deactivate', { key, activation_id: activationId });
+      if (r.kind === 'error') return { status: 'error', reason: r.reason };
+      if (r.ok) return { status: 'valid' };
+      return { status: 'error', reason: `HTTP ${r.status}` };
+    },
+  };
+}

package/src/lib/rename-compat.js

@@ -0,0 +1,50 @@
+// Backward compatibility for the awsclaw -> clawform rename.
+//
+// Everything in this module exists so a project set up before the rename keeps
+// working, and is meant to be deleted wholesale at v3 — which is why it lives
+// here rather than being sprinkled through the loaders it serves.
+
+const DEPRECATION_PREFIX = '[clawform]';
+
+// Precedence is the array order: the current name first, the pre-rename name
+// as a fallback.
+export const CONFIG_FILENAMES = ['clawform.config.json', 'awsclaw.config.json'];
+
+export const ENV_PREFIX = 'CLAWFORM_';
+export const DEPRECATED_ENV_PREFIX = 'AWSCLAW_';
+
+export function isDeprecatedConfigFilename(name) {
+  return name === 'awsclaw.config.json';
+}
+
+export function warnDeprecatedConfigFilename(path) {
+  process.stderr.write(
+    `${DEPRECATION_PREFIX} ${path} uses the pre-rename filename. ` +
+    'Rename it to clawform.config.json — awsclaw.config.json stops being read in v3.\n',
+  );
+}
+
+// One warning per variable name, not per read: several call sites read the same
+// flag, and a wall of identical lines trains people to ignore it.
+const warnedEnvNames = new Set();
+
+// `name` is the suffix shared by both spellings, e.g. 'DEBUG' for
+// CLAWFORM_DEBUG / AWSCLAW_DEBUG.
+export function readEnv(name, env = process.env) {
+  const current = env[ENV_PREFIX + name];
+  // Presence, not truthiness: an explicit CLAWFORM_X="" is the user turning the
+  // flag off, and falling through to a stale AWSCLAW_X would overrule them.
+  if (current !== undefined) return current;
+
+  const deprecated = env[DEPRECATED_ENV_PREFIX + name];
+  if (deprecated === undefined) return undefined;
+
+  if (!warnedEnvNames.has(name)) {
+    warnedEnvNames.add(name);
+    process.stderr.write(
+      `${DEPRECATION_PREFIX} ${DEPRECATED_ENV_PREFIX}${name} is deprecated — ` +
+      `use ${ENV_PREFIX}${name}. The old name stops being read in v3.\n`,
+    );
+  }
+  return deprecated;
+}

package/src/lib/session-state.js

@@ -0,0 +1,91 @@
+// In-flight deploy state — survives `/clear` and new sessions.
+//
+// What clawform persists is NOT conversation (that's the consumer's kit's job) —
+// it's the AWS operation left mid-flight: a changeset created but not yet
+// executed. `clawform deploy` records it here right after CreateChangeSet and
+// clears it after ExecuteChangeSet; if the operator aborts at the confirm
+// prompt (or runs `/clear`), the entry survives so the SessionStart context
+// hook can warn the next session that a changeset is sitting unexecuted.
+//
+// State file: <projectDir>/.clawform-state.json (gitignored). Stores only
+// stack name + changeset name + env + createdAt — never account IDs, ARNs,
+// or template bodies. All reads fail-open: a missing or corrupt file yields
+// an empty state, never an exception, so a bad state file never blocks a
+// deploy or a session start.
+
+import { readFileSync as fsReadFileSync, writeFileSync as fsWriteFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const STATE_FILENAME = '.clawform-state.json';
+export const STATE_VERSION = 1;
+export const STALE_CHANGESET_DAYS = 7;
+
+function statePath(projectDir) {
+  return join(projectDir, STATE_FILENAME);
+}
+
+function emptyState() {
+  return { v: STATE_VERSION, pendingChangesets: [] };
+}
+
+export function readState(projectDir, { readFileSync = fsReadFileSync } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(statePath(projectDir), 'utf8');
+  } catch {
+    return emptyState();
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.v !== STATE_VERSION || !Array.isArray(parsed.pendingChangesets)) {
+      return emptyState();
+    }
+    return parsed;
+  } catch {
+    return emptyState();
+  }
+}
+
+export function writeState(projectDir, state, { writeFileSync = fsWriteFileSync } = {}) {
+  writeFileSync(statePath(projectDir), JSON.stringify(state, null, 2));
+}
+
+const changesetKey = (e) => `${e.stack} ${e.changeSetName}`;
+
+const DAY_MS = 86_400_000;
+
+// Entries older than the stale threshold are treated as abandoned — a
+// changeset the operator never executed and never will. We can't clear those
+// on the read path (the SessionStart hook must not write), so we self-heal on
+// the write path: every `addPendingChangeset` (i.e. every new deploy) drops any
+// entry past the threshold. This bounds accumulation and means a phantom entry
+// disappears on the next deploy without the operator hand-editing the file.
+function isStale(entry, now) {
+  const created = Date.parse(entry?.createdAt);
+  if (!Number.isFinite(created)) return true; // unparseable createdAt → treat as junk, prune
+  return now - created > STALE_CHANGESET_DAYS * DAY_MS;
+}
+
+// Record (or refresh) a pending changeset. Stores only the safe fields; a
+// repeated stack+changeset replaces the prior entry (latest createdAt wins).
+// Prunes stale/abandoned entries in the same write (self-healing).
+export function addPendingChangeset(projectDir, entry, deps = {}) {
+  const now = typeof deps.now === 'number' ? deps.now : Date.now();
+  const state = readState(projectDir, deps);
+  const next = state.pendingChangesets
+    .filter((e) => changesetKey(e) !== changesetKey(entry))
+    .filter((e) => !isStale(e, now));
+  next.push({
+    stack: entry.stack,
+    changeSetName: entry.changeSetName,
+    env: entry.env,
+    createdAt: entry.createdAt,
+  });
+  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
+}
+
+export function clearPendingChangeset(projectDir, { stack, changeSetName }, deps = {}) {
+  const state = readState(projectDir, deps);
+  const next = state.pendingChangesets.filter((e) => !(e.stack === stack && e.changeSetName === changeSetName));
+  writeState(projectDir, { ...state, pendingChangesets: next }, deps);
+}

package/src/lib/trial-claim.js

@@ -0,0 +1,65 @@
+// Claims one trial per machine, against the vendor's own delivery service.
+//
+// The abuse this exists for: trial expires, new email, new trial key, same
+// laptop. Polar cannot see that — it knows customers, not devices — so the
+// check has to happen somewhere we control, and it has to happen at ACTIVATE.
+// Claiming at the kit fetch would miss the case entirely: a machine that has
+// already trialled has the kit cached, so it never calls out again.
+//
+// Honest about its own reach: the fingerprint is computed on the client and
+// self-reported, so a changed hostname, a VM, or a patched CLI all pass. This
+// stops the casual repeat and produces a record of how often it is tried. It is
+// the same posture the product states publicly — a deterrent at the point of
+// action, not a sandbox.
+
+import { KIT_SERVICE_URL } from './license-config.js';
+
+// The one answer that is about the DEVICE. Shared with the service so the two
+// halves cannot drift into disagreeing about the word.
+export const DEVICE_REFUSED = 'device_already_trialled';
+
+/**
+ * @returns {Promise<{allowed: boolean, reason?: string}>}
+ *   `allowed: false` ONLY when the service deliberately refused. Every other
+ *   outcome — unreachable, throttled, 5xx — resolves to allowed, because our
+ *   downtime must cost a lead and never a purchase. The caller additionally
+ *   catches, so a thrown error is equally fail-open.
+ */
+export async function claimTrialDevice({
+  licenseKey,
+  fingerprint,
+  serviceUrl = KIT_SERVICE_URL,
+  fetch: fetchImpl = fetch,
+}) {
+  let resp;
+  try {
+    resp = await fetchImpl(`${serviceUrl}/trial-claim`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ license_key: licenseKey, fingerprint }),
+    });
+  } catch {
+    return { allowed: true, unverified: true };
+  }
+
+  // ONLY the device answer refuses here. The service also returns 403 when the
+  // licence itself is no good — wrong product, not found, expired — and reading
+  // those as "this machine already trialled" tells the user something false with
+  // full confidence. It happened for real: a service deployed before the trial
+  // benefit existed answered `wrong_product`, and the CLI announced a used
+  // trial. Licence problems are Polar's to report, and `activate` does report
+  // them accurately a moment later.
+  if (resp.status === 403) {
+    let detail = '';
+    try {
+      const body = await resp.json();
+      detail = String(body?.detail ?? '');
+    } catch { /* no body: cannot be attributed to the device */ }
+
+    if (detail === DEVICE_REFUSED) return { allowed: false, reason: DEVICE_REFUSED };
+    return { allowed: true, unverified: true };
+  }
+
+  // Anything else — a throttle, a 5xx, a bad gateway — lets the trial through.
+  return { allowed: true, unverified: !resp.ok };
+}

package/src/lib/watermark.js

@@ -0,0 +1,65 @@
+// Ownership watermarks. A shared copy identifies its source on sight — the
+// cheapest deterrent in the licensing stack, and the only one that reaches the
+// biggest leak path: a paying buyer zipping their materialised plugin folder
+// for the rest of the team.
+//
+// Two layers, deliberately at two exposure levels:
+//
+//   .licensed-to        full holder address. It is the buyer's own receipt on
+//                       their own machine, and it is the first thing anyone
+//                       leaking on purpose deletes — so it rarely travels.
+//   per-file comment    MASKED holder + key suffix. This is the layer that
+//                       SURVIVES a deliberate leak, so it exposes as little as
+//                       possible while staying instantly recognisable to the
+//                       buyer. Traceability does not depend on the address at
+//                       all: the key suffix is enough to look the buyer up with
+//                       the vendor.
+//
+// Neither layer ever carries a full licence key.
+
+const suffixOf = (key) => String(key ?? '').slice(-4);
+
+const isActive = (record) => Boolean(record && record.status === 'active' && record.key);
+
+// 'jane@acme.com' → 'j***@acme.com'. Anything that isn't an address → ''.
+export function maskEmail(email) {
+  const at = String(email ?? '').indexOf('@');
+  if (at < 1) return '';
+  return `${String(email)[0]}***${String(email).slice(at)}`;
+}
+
+// Appended to `--version`, where the buyer sees it every day.
+export function versionWatermark(record) {
+  if (!isActive(record)) return '';
+  const suffix = `…${suffixOf(record.key)}`;
+  return record.holder
+    ? ` — licensed to ${record.holder} (${suffix})`
+    : ` — licensed (${suffix})`;
+}
+
+// Appended to each materialised SKILL.md. Deliberately timestamp-free: a
+// timestamp would change every file's hash on each `init plugin`, destroying
+// the install manifest's ability to tell our files from the user's edits.
+export function contentWatermark(record) {
+  if (!isActive(record)) return '';
+  const who = maskEmail(record.holder);
+  const parts = ['Clawform', who && `licensed to ${who}`, `…${suffixOf(record.key)}`].filter(Boolean);
+  return `<!-- ${parts.join(' · ')} -->`;
+}
+
+// Contents of ~/.clawform/plugin/.licensed-to — the receipt. Full address here
+// on purpose; see the module header for why that is the safer split.
+export function licensedToBody(record, nowIso) {
+  const lines = [
+    'Clawform — this copy is licensed to a single seat.',
+    '',
+    `Holder:      ${record?.holder ?? '(unknown)'}`,
+    `Key:         …${suffixOf(record?.key)}`,
+    `Activation:  ${record?.instanceId ?? '(unknown)'}`,
+    `Materialised: ${nowIso}`,
+    '',
+    'Redistributing this directory is a licence violation. Every skill file',
+    'carries the same licence identity, so a shared copy remains traceable.',
+  ];
+  return `${lines.join('\n')}\n`;
+}