gatefit 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-All notable Gatefit changes are listed here. The heading version matches `package.json`. Tag `v0.4.0` is not cut in this change.
+All notable Gatefit changes are listed here. The version heading matches `package.json`. Tag `v0.5.1` is not cut in this change.
+
+## [0.5.1] - 2026-10-16
+
+### Fixed
+
+- `better-sqlite3` is optional and loads only when the SQLite adapter opens a database. `--version`, `--help`, and `adapter-check` run when that module is missing. A SQLite command that cannot load it prints what is missing, that the package ships prebuilds and does not compile on install, and how to reinstall the prebuild or run `npm run build-release`, then exits non-zero.
+
+## [0.5.0] - 2026-10-16
+
+### Added
+
+- Chaos mode, a Pro pack. `gatefit run --suite chaos` replays every golden under seeded perturbations and compares the access row to the in-order replay. It requires `GATEFIT_LICENSE_KEY`.
+- License gate (`GATEFIT_LICENSE_KEY`), first shipped in 0.4.0.
+- Token-free npm trusted publishing. An annotated tag `vX.Y.Z` runs `.github/workflows/publish.yml` with GitHub OIDC. The publish job uses the GitHub environment `npm`. Provenance is automatic.
+
+### Not in this version
+
+- Provider packs.
+- A monthly plan.
 
 ## [0.4.0] - 2026-10-16
 

package/README.md

@@ -9,7 +9,7 @@ Fixture-first S1–S6 goldens, an `npx gatefit` CLI, and a GitHub Action. Node 2
 The CLI and GitHub Action in this repository stay free. The docs site is live. npm is live: `npx gatefit` ([gatefit](https://www.npmjs.com/package/gatefit)). Polar checkout is.
 
 - **Docs site:** live at https://gatefit.io. Cloudflare Pages project `gatefit`, hostname `gatefit-bdu.pages.dev`. From `site/`: `npm run build`, then `npx wrangler@4 pages deploy dist --project-name gatefit`. `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` come from the environment. GitHub Pages needs a public repository or a paid plan and is not the live host. `scripts/deploy-site.sh` can copy `site/dist` locally or deploy that Cloudflare target.
-- **npm:** live. `npx gatefit` is `gatefit@0.4.0` at https://www.npmjs.com/package/gatefit. CI runs `npm publish --dry-run` only.
+- **npm:** live. `npx gatefit` is the last published tarball (`gatefit@0.5.0` until tag `v0.5.1`) at https://www.npmjs.com/package/gatefit. This repo is `0.5.1`. The named gate runs `npm publish --dry-run` only. A `v*` tag publishes with OIDC. See [Releasing](#releasing).
 - **Polar checkout:** live. Gatefit Indie License is **$49** one-time at `https://buy.polar.sh/polar_cl_biyvx7HYtN2u19tUJCCkIuGOc98uVv7IG3gcB04eIJ0`. A plain `site` build and `scripts/deploy-site.sh` use that committed link. `PUBLIC_POLAR_CHECKOUT_URL` may override it. Any other value fails closed.
 
 ## Install / run
@@ -20,7 +20,9 @@ npx gatefit adapter-check
 npx gatefit run --suite paid_grants_access --adapter ./src/your-access-adapter.ts
 ```
 
-`gatefit@0.4.0`: https://www.npmjs.com/package/gatefit
+This repo is `0.5.1`. Registry: https://www.npmjs.com/package/gatefit
+
+`better-sqlite3` is optional and ships prebuilds for common platforms. It does not compile during `npm install`. `--version`, `--help`, and `adapter-check` run when the native module is missing. The reference SQLite adapter loads it only when that adapter runs. If the module is missing, that command tells you to reinstall the prebuild, or to install build tools and run `npm run build-release` in the `better-sqlite3` directory, then exits non-zero.
 
 From a clone:
 
@@ -41,13 +43,13 @@ Bring your own AccessAdapter in ≤30 minutes: [docs/bring-your-adapter.md](docs
 
 ## GitHub Action
 
-Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.4.0` is not cut yet. After a human tags the release commit:
+Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.5.0` is released. Tag `v0.5.1` is not cut yet. After a human pushes the annotated tag:
 
 ```yaml
 - uses: actions/setup-node@v4
   with:
     node-version: "22"
-- uses: gatefit/gatefit@v0.4.0
+- uses: gatefit/gatefit@v0.5.1
   with:
     adapter: src/your-access-adapter.ts
 ```
@@ -55,22 +57,43 @@ Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.4.0` is
 Nested path still works:
 
 ```yaml
-- uses: gatefit/gatefit/.github/actions/gatefit@v0.4.0
+- uses: gatefit/gatefit/.github/actions/gatefit@v0.5.1
   with:
     adapter: src/your-access-adapter.ts
 ```
 
-The Action wraps `gatefit run`. Adapter path is in *your* repo; goldens default to Gatefit’s S1–S6 pack. See [docs/publish.md](docs/publish.md) and the release draft [docs/release-v0.4.0.md](docs/release-v0.4.0.md).
+The Action wraps `gatefit run`. Adapter path is in *your* repo; goldens default to Gatefit’s S1–S6 pack. See [docs/publish.md](docs/publish.md) and the release notes [docs/release-v0.5.1.md](docs/release-v0.5.1.md).
 
 Do not set `GATEFIT_LIVE_CLOCK` for the named gate. Do not use `sk_live`. Never treat Stripe HTTP 200 as proof of access.
 
 Opt-in live Test Clocks (not default CI): [docs/live-clock.md](docs/live-clock.md).
 
+## Releasing
+
+Bump `version` in `package.json` and the lockfile `version` field, and add the matching `CHANGELOG.md` heading, in a pull request. Merge to `main`. Then push an annotated tag whose name is `v` plus that version:
+
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+The tag must match `v*`. The workflow fails when the tag without the leading `v` is not `package.json` `version`. That push runs `.github/workflows/publish.yml`: unit tests (`npm test`), the tarball checks (bin present, no `site/`, no secrets), then `npm publish --access public`. Provenance is automatic. The publish job requires the GitHub environment `npm`, so a required reviewer can be added there. `workflow_dispatch` runs the checks and does not publish. Do not set a registry token.
+
+One-time setup on npmjs.com for package `gatefit`: open Package settings, Trusted Publisher, GitHub Actions. Organization or user `gatefit`, repository `gatefit`, workflow filename `publish.yml`, environment name `npm`, and allow `npm publish`. Then set Publishing access to **Require two-factor authentication and disallow tokens**.
+
+`./ci-local.sh` stays the merge gate. It runs `npm publish --dry-run` and does not push tags.
+
 ## License
 
 S1–S6, seats/races, dispute/unpaid, and live Test Clocks stay free. Those packs do not read `GATEFIT_LICENSE_KEY` and do not call Polar.
 
-The $49 Gatefit Indie License unlocks Pro packs. Chaos mode is coming and is not in this release. Provider packs are not in this release. A missing, invalid, or revoked key exits non-zero and points at https://gatefit.io/#pricing.
+The $49 Gatefit Indie License unlocks Pro packs. Chaos mode is live. Provider packs are not in this release. A missing, invalid, or revoked key exits non-zero and points at https://gatefit.io/#pricing.
+
+```bash
+gatefit run --suite chaos --adapter src/adapters/hardened.ts --seed 1
+```
+
+Chaos mode replays every golden under a seeded set of delivery perturbations and compares the access row to the in-order replay. The perturbations are duplicated deliveries, reordered events, stale events, late events, dropped-then-replayed events, and the checkout-return page loading before the webhook. HTTP 200 is not access. The seed defaults to `1`. `--seed` wins over `GATEFIT_CHAOS_SEED`. The same seed prints the same bytes. A failure prints that seed and the perturbed events. Details: [docs/chaos.md](docs/chaos.md).
 
 ```bash
 export GATEFIT_LICENSE_KEY='GATEFIT-…'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatefit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Stripe Entitlement Edge Pack — CI that asserts the access DB survives ugly billing transitions",
   "type": "module",
   "license": "MIT",
@@ -46,10 +46,12 @@
     "access": "public"
   },
   "dependencies": {
-    "better-sqlite3": "^13.0.3",
     "tsx": "^4.20.5",
     "yaml": "^2.8.1"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^13.0.3"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^22.18.0",

package/src/access-adapter.ts

@@ -25,6 +25,8 @@ export type BillingEvent = {
   cancel_at_period_end?: boolean;
   period_end?: number;
   now?: number;
+  /** Original timeline position. Chaos folds on this so arrival order is not access. */
+  created?: number;
 };
 
 export type AccessAdapter = {

package/src/access-rules.ts

@@ -3,10 +3,12 @@ import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
 export type AccessStore = {
   rows: Map<string, AccessSnapshot>;
   seen: Set<string>;
+  events: BillingEvent[];
+  arrival: number;
 };
 
 export function emptyStore(): AccessStore {
-  return { rows: new Map(), seen: new Set() };
+  return { rows: new Map(), seen: new Set(), events: [], arrival: 0 };
 }
 
 export function isPaid(event: BillingEvent): boolean {
@@ -96,9 +98,26 @@ export function nextSnapshot(current: AccessSnapshot, event: BillingEvent): Acce
   return current;
 }
 
+function foldCustomer(store: AccessStore, customerId: string): void {
+  const ordered = store.events.filter((event) => event.customerId === customerId);
+  ordered.sort((a, b) => {
+    const byCreated = (a.created ?? 0) - (b.created ?? 0);
+    if (byCreated !== 0) return byCreated;
+    if (a.id < b.id) return -1;
+    if (a.id > b.id) return 1;
+    return 0;
+  });
+  let snapshot: AccessSnapshot = { locked: true };
+  for (const event of ordered) snapshot = nextSnapshot(snapshot, event);
+  store.rows.set(customerId, snapshot);
+}
+
 export function applyBillingEvent(store: AccessStore, event: BillingEvent): void {
   if (store.seen.has(event.id)) return;
   store.seen.add(event.id);
-  const current = store.rows.get(event.customerId) ?? { locked: true };
-  store.rows.set(event.customerId, nextSnapshot(current, event));
+  const stamped: BillingEvent = { ...event };
+  if (stamped.created === undefined) stamped.created = store.arrival;
+  store.arrival += 1;
+  store.events.push(stamped);
+  foldCustomer(store, event.customerId);
 }

package/src/adapters/hardened.ts

@@ -13,6 +13,8 @@ export function createAdapter(): AccessAdapter {
     reset() {
       store.rows.clear();
       store.seen.clear();
+      store.events.length = 0;
+      store.arrival = 0;
     },
   };
 }

package/src/adapters/sqlite.ts

@@ -3,7 +3,31 @@ import type { AccessAdapter, AccessSnapshot, BillingEvent } from "../access-adap
 import { nextSnapshot } from "../access-rules.ts";
 
 const require = createRequire(import.meta.url);
-const Database = require("better-sqlite3") as typeof import("better-sqlite3");
+
+function sqliteUnavailable(err: unknown): Error {
+  const detail = err instanceof Error ? err.message : String(err);
+  return new Error(
+      [
+        "gatefit: SQLite adapter cannot load better-sqlite3.",
+        "What is missing: the better-sqlite3 native module.",
+        "Why: better-sqlite3 is optional. Its package ships prebuilds for linux, darwin, and win32 (x64 and arm64) and does not compile during npm install. This process has no usable prebuild.",
+        "How to fix: reinstall so the prebuild is unpacked (npm install better-sqlite3, or reinstall gatefit). npm rebuild better-sqlite3 does not compile it. On a platform without a prebuild, install make and a C++ compiler (Xcode Command Line Tools on macOS, or build-essential on Linux), then in the better-sqlite3 directory run npm run build-release.",
+        "--version, --help, and adapter-check do not need this module.",
+        `Detail: ${detail}`,
+      ].join("\n"),
+  );
+}
+
+function loadDatabase(): typeof import("better-sqlite3") {
+  try {
+    const Database = require("better-sqlite3") as typeof import("better-sqlite3");
+    const probe = new Database(":memory:");
+    probe.close();
+    return Database;
+  } catch (err) {
+    throw sqliteUnavailable(err);
+  }
+}
 
 type AccessRow = {
   customer_id: string;
@@ -24,6 +48,7 @@ function rowToSnapshot(row: AccessRow | undefined): AccessSnapshot {
 
 export function createAdapter(): AccessAdapter {
   const filename = process.env.GATEFIT_SQLITE_PATH ?? ":memory:";
+  const Database = loadDatabase();
   const db = new Database(filename);
   db.exec(`
     CREATE TABLE IF NOT EXISTS access (

package/src/chaos.ts

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
+import { loadAdapter } from "./access-adapter.ts";
+import { listGoldens, loadGolden } from "./fixture-driver.ts";
+import type { GoldenSuite } from "./fixture-driver.ts";
+import { registerProPack } from "./packs.ts";
+import { goldenDir, resolveUserOrPackage } from "./paths.ts";
+
+export const CHAOS_DEFAULT_SEED = "1";
+
+const PERTURBATIONS = [
+  "duplicate",
+  "reorder",
+  "stale",
+  "late",
+  "dropped_replay",
+  "checkout_return",
+] as const;
+
+type Perturbation = (typeof PERTURBATIONS)[number];
+
+export function resolveChaosSeed(flag: string | undefined, envValue: string | undefined): string {
+  const raw = flag !== undefined ? flag : envValue;
+  const trimmed = (raw ?? "").trim();
+  return trimmed.length > 0 ? trimmed : CHAOS_DEFAULT_SEED;
+}
+
+function pickIndex(seed: string, goldenId: string, kind: string, salt: string, n: number): number {
+  const digest = createHash("sha256").update(`${seed}\0${goldenId}\0${kind}\0${salt}`).digest();
+  return digest.readUInt32BE(0) % n;
+}
+
+function cloneEvents(events: BillingEvent[]): BillingEvent[] {
+  return events.map((event) => ({ ...event }));
+}
+
+function stamp(suite: GoldenSuite): BillingEvent[] {
+  return suite.steps.map((step, index) => ({ ...step.event, created: index }));
+}
+
+function duplicate(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "duplicate", "i", next.length);
+  next.push({ ...next[index]! });
+  return next;
+}
+
+function reorder(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  if (next.length < 2) return next;
+  const left = pickIndex(seed, goldenId, "reorder", "a", next.length);
+  let right = pickIndex(seed, goldenId, "reorder", "b", next.length);
+  if (left === right) right = (right + 1) % next.length;
+  const swap = next[left]!;
+  next[left] = next[right]!;
+  next[right] = swap;
+  return next;
+}
+
+function moveToEnd(events: BillingEvent[], index: number): BillingEvent[] {
+  const next = cloneEvents(events);
+  const [picked] = next.splice(index, 1);
+  next.push(picked!);
+  return next;
+}
+
+function stale(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "stale", "i", events.length - 1);
+  return moveToEnd(events, index);
+}
+
+function late(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "late", "i", events.length);
+  return moveToEnd(events, index);
+}
+
+function droppedReplay(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "dropped_replay", "i", next.length);
+  next.splice(index, 1);
+  return [...next, ...cloneEvents(events)];
+}
+
+function checkoutReturn(suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  const page: BillingEvent = {
+    id: `evt_chaos_checkout_${suite.id}`,
+    type: "checkout.session.completed",
+    customerId: suite.subject,
+    httpStatus: 200,
+    stripeHttpStatus: 200,
+    created: -1,
+  };
+  return [page, ...cloneEvents(events)];
+}
+
+function perturb(kind: Perturbation, seed: string, suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  if (kind === "duplicate") return duplicate(seed, suite.id, events);
+  if (kind === "reorder") return reorder(seed, suite.id, events);
+  if (kind === "stale") return stale(seed, suite.id, events);
+  if (kind === "late") return late(seed, suite.id, events);
+  if (kind === "dropped_replay") return droppedReplay(seed, suite.id, events);
+  return checkoutReturn(suite, events);
+}
+
+function stableSnapshot(snapshot: AccessSnapshot): string {
+  const keys = (Object.keys(snapshot) as (keyof AccessSnapshot)[])
+    .filter((key) => snapshot[key] !== undefined)
+    .sort();
+  const ordered: Record<string, unknown> = {};
+  for (const key of keys) ordered[key] = snapshot[key];
+  return JSON.stringify(ordered);
+}
+
+async function replay(
+  adapter: { apply: (event: BillingEvent) => void | Promise<void>; snapshot: (id: string) => AccessSnapshot | Promise<AccessSnapshot>; reset?: () => void | Promise<void> },
+  subject: string,
+  events: BillingEvent[],
+): Promise<AccessSnapshot> {
+  if (adapter.reset) await adapter.reset();
+  for (const event of events) await adapter.apply(event);
+  return adapter.snapshot(subject);
+}
+
+function fail(seed: string, goldenId: string, kind: Perturbation, events: BillingEvent[], expected: string, actual: string): void {
+  console.error(`gatefit: FAIL chaos ${goldenId} perturbation ${kind}`);
+  console.error(`seed: ${seed}`);
+  console.error("repro:");
+  for (const event of events) console.error(JSON.stringify(event));
+  console.error(`access: expected ${expected} got ${actual}`);
+}
+
+export async function runChaos(adapterPath: string, seed: string): Promise<number> {
+  console.error(`gatefit chaos: seed ${seed}`);
+  if (process.env.GATEFIT_LIVE_CLOCK) {
+    console.error("gatefit chaos: refuses GATEFIT_LIVE_CLOCK; fixture order only");
+    return 1;
+  }
+  const adapter = await loadAdapter(resolveUserOrPackage(adapterPath));
+  if (typeof adapter.reset !== "function") {
+    console.error("gatefit chaos: adapter.reset is required");
+    return 1;
+  }
+  const files = listGoldens(goldenDir());
+  for (const file of files) {
+    const suite = loadGolden(file);
+    const ordered = stamp(suite);
+    const expected = stableSnapshot(await replay(adapter, suite.subject, ordered));
+    for (const kind of PERTURBATIONS) {
+      const events = perturb(kind, seed, suite, ordered);
+      const actual = stableSnapshot(await replay(adapter, suite.subject, events));
+      if (actual !== expected) {
+        fail(seed, suite.id, kind, events, expected, actual);
+        return 1;
+      }
+    }
+    console.error(`gatefit: PASS chaos ${suite.id}`);
+  }
+  console.error("gatefit: PASS chaos");
+  return 0;
+}
+
+registerProPack({
+  id: "chaos",
+  run({ adapterPath, seed }) {
+    return runChaos(adapterPath, seed);
+  },
+});

package/src/cli.ts

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { loadAdapter } from "./access-adapter.ts";
 import { listGoldens, loadGolden, requireReset, runGolden } from "./fixture-driver.ts";
 import { LIVE_SCENARIO_IDS, runLiveLane, type LiveScenarioId } from "./live-scenarios.ts";
+import { resolveChaosSeed } from "./chaos.ts";
 import { ensureProLicense } from "./license.ts";
 import { getProPack, isProPack } from "./packs.ts";
 import { goldenDir, packageRoot, readPackageVersion, resolveUserOrPackage, userCwd } from "./paths.ts";
@@ -21,8 +22,10 @@ function usage(): string {
   return [
     "Usage:",
     "  gatefit run --suite <dir|file|id> --adapter <path>",
+    "  gatefit run --suite chaos --adapter <path> [--seed <value>]",
     "  gatefit adapter-check",
     "  gatefit live --adapter <path> [--scenario <id>]",
+    "  gatefit --help",
     "  gatefit --version",
   ].join("\n");
 }
@@ -41,7 +44,7 @@ function resolveSuiteFiles(suite: string): string[] {
   throw new Error(`suite not found: ${suite}`);
 }
 
-async function cmdRun(suite: string, adapterPath: string): Promise<number> {
+async function cmdRun(suite: string, adapterPath: string, seed: string): Promise<number> {
   if (isProPack(suite)) {
     const gate = await ensureProLicense();
     if (!gate.ok) {
@@ -50,7 +53,7 @@ async function cmdRun(suite: string, adapterPath: string): Promise<number> {
     }
     if (gate.warning) console.error(gate.warning);
     const pack = getProPack(suite);
-    if (pack?.run) return pack.run({ adapterPath });
+    if (pack?.run) return pack.run({ adapterPath, seed });
     console.error(`gatefit: PASS ${suite}`);
     return 0;
   }
@@ -94,11 +97,19 @@ function isVersionFlag(arg: string | undefined): boolean {
   return arg === "--version" || arg === "-v";
 }
 
+function isHelpFlag(arg: string | undefined): boolean {
+  return arg === "--help" || arg === "-h";
+}
+
 async function main(argv: string[]): Promise<number> {
   if (isVersionFlag(argv[0])) {
     console.log(`gatefit ${readPackageVersion()}`);
     return 0;
   }
+  if (isHelpFlag(argv[0])) {
+    console.log(usage());
+    return 0;
+  }
   const command = argv[0];
   if (command === "adapter-check") {
     return cmdAdapterCheck();
@@ -109,13 +120,14 @@ async function main(argv: string[]): Promise<number> {
       options: {
         suite: { type: "string" },
         adapter: { type: "string" },
+        seed: { type: "string" },
       },
     });
     if (!values.suite || !values.adapter) {
       console.error(usage());
       return 1;
     }
-    return cmdRun(values.suite, values.adapter);
+    return cmdRun(values.suite, values.adapter, resolveChaosSeed(values.seed, process.env.GATEFIT_CHAOS_SEED));
   }
   if (command === "live") {
     const { values } = parseArgs({

package/src/packs.ts

@@ -1,10 +1,10 @@
 /**
- * Pro pack registry. H17 plugs chaos mode in by calling `registerProPack`
- * with a `run` function. The stub has no runner and is not a user-facing feature.
+ * Pro pack registry. Chaos mode registers here and runs only after the license gate.
+ * The stub has no runner and is not a user-facing feature.
  */
 export type ProPack = {
   id: string;
-  run?: (ctx: { adapterPath: string }) => Promise<number>;
+  run?: (ctx: { adapterPath: string; seed: string }) => Promise<number>;
 };
 
 const proPacks = new Map<string, ProPack>();