gatefit 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable Gatefit changes are listed here. The heading version matches `package.json`. Tag `v0.4.0` is not cut in this change.
+
+## [0.4.0] - 2026-10-16
+
+Tag-ready pack. npm `gatefit@0.4.0` is live (`npx gatefit`, https://www.npmjs.com/package/gatefit). The docs site is live at https://gatefit.io. Polar checkout is the committed Gatefit Indie License link.
+
+### Added
+
+- Publishable `gatefit@0.4.0` CLI (`bin/gatefit.js`) and composite GitHub Action.
+- Callers, once a human tags the release commit: `uses: gatefit/gatefit@v0.4.0` and `uses: gatefit/gatefit/.github/actions/gatefit@v0.4.0`.
+- Fixture goldens for paid, cancel, refund, trial, past_due, duplicate delivery, seats, cancel-at-period-end, upgrade race, dispute, and unpaid retries.
+- Starlight docs app under `site/` and GHA-free `scripts/deploy-site.sh`.
+- `npm publish --dry-run` inside `./ci-local.sh`, with tarball checks that the bin is present and `site/` and secrets are absent.
+- Pro pack license gate. `GATEFIT_LICENSE_KEY` is checked with Polar's public validate endpoint. Free packs do not call it. Chaos mode is not in this release.
+
+### Not in this version
+
+- A docs deploy from this changelog. The site is already live at https://gatefit.io.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edipert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# gatefit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stripe Entitlement Edge Pack — CI that asserts the access DB survives ugly billing transitions.
+
+Fixture-first S1–S6 goldens, an `npx gatefit` CLI, and a GitHub Action. Node 22+. Not a billing UI.
+
+## Distribution
+
+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.
+- **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
+
+```bash
+npx gatefit --version
+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
+
+From a clone:
+
+```bash
+npm install
+node bin/gatefit.js --version
+node bin/gatefit.js adapter-check
+node bin/gatefit.js run --suite paid_grants_access --adapter ./src/your-access-adapter.ts
+```
+
+Named verify gate (fixture-first; do not set `GATEFIT_LIVE_CLOCK`):
+
+```bash
+bash ./ci-local.sh
+```
+
+Bring your own AccessAdapter in ≤30 minutes: [docs/bring-your-adapter.md](docs/bring-your-adapter.md).
+
+## 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:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: "22"
+- uses: gatefit/gatefit@v0.4.0
+  with:
+    adapter: src/your-access-adapter.ts
+```
+
+Nested path still works:
+
+```yaml
+- uses: gatefit/gatefit/.github/actions/gatefit@v0.4.0
+  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).
+
+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).
+
+## 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.
+
+```bash
+export GATEFIT_LICENSE_KEY='GATEFIT-…'
+```
+
+Validation is `POST https://api.polar.sh/v1/customer-portal/license-keys/validate` with the key and organization id `68556619-45ab-4a88-8ad8-08606c2b820e`. No Polar API token. A valid result is cached for 24 hours by sha256, never as the raw key. If Polar is unreachable, a cached valid result is reused with a warning. With no cache, the command warns and still runs. Details: [docs/license.md](docs/license.md).

package/action.yml

@@ -0,0 +1,23 @@
+name: Gatefit
+description: Run Gatefit S1–S6 entitlement goldens against an AccessAdapter (access DB, not Stripe HTTP 200)
+author: gatefit
+branding:
+  icon: shield
+  color: green
+inputs:
+  adapter:
+    description: Path to the AccessAdapter module, relative to the caller workspace
+    required: true
+  suite:
+    description: Golden file, directory, or id. Defaults to bundled S1–S6 goldens
+    required: false
+    default: ""
+runs:
+  using: composite
+  steps:
+    - name: Run gatefit
+      shell: bash
+      env:
+        GATEFIT_ADAPTER_INPUT: ${{ inputs.adapter }}
+        GATEFIT_SUITE_INPUT: ${{ inputs.suite }}
+      run: bash "${GITHUB_ACTION_PATH}/scripts/action-run.sh"

package/bin/gatefit.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cli = path.join(root, "src/cli.ts");
+const requireFromPackage = createRequire(path.join(root, "package.json"));
+
+function resolveTsxCli() {
+  try {
+    return path.join(path.dirname(requireFromPackage.resolve("tsx/package.json")), "dist/cli.mjs");
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxCli = resolveTsxCli();
+if (!tsxCli) {
+  console.error("gatefit: missing tsx (run npm install so the gatefit package can resolve tsx)");
+  process.exit(1);
+}
+
+process.env.GATEFIT_PACKAGE_ROOT ??= root;
+process.env.INIT_CWD ??= process.cwd();
+const result = spawnSync(process.execPath, [tsxCli, cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "gatefit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Stripe Entitlement Edge Pack — CI that asserts the access DB survives ugly billing transitions",
+  "type": "module",
+  "license": "MIT",
+  "author": "gatefit",
+  "bin": {
+    "gatefit": "./bin/gatefit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "tests/entitlements/goldens",
+    "action.yml",
+    "scripts/action-run.sh",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "gatefit": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test --test-concurrency=1 tests/entitlements/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gatefit/gatefit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gatefit/gatefit/issues"
+  },
+  "homepage": "https://github.com/gatefit/gatefit#readme",
+  "keywords": [
+    "stripe",
+    "entitlements",
+    "access",
+    "ci",
+    "webhooks",
+    "billing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "better-sqlite3": "^13.0.3",
+    "tsx": "^4.20.5",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.2"
+  }
+}

package/scripts/action-run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ -f "${GITHUB_ACTION_PATH}/package.json" && -f "${GITHUB_ACTION_PATH}/bin/gatefit.js" ]]; then
+  GATEFIT_ROOT="${GITHUB_ACTION_PATH}"
+else
+  GATEFIT_ROOT="$(cd "${GITHUB_ACTION_PATH}/../../.." && pwd)"
+fi
+ADAPTER="$(cd "${GITHUB_WORKSPACE}" && realpath "${GATEFIT_ADAPTER_INPUT}")"
+if [[ -n "${GATEFIT_SUITE_INPUT}" && -e "${GITHUB_WORKSPACE}/${GATEFIT_SUITE_INPUT}" ]]; then
+  SUITE="$(cd "${GITHUB_WORKSPACE}" && realpath "${GATEFIT_SUITE_INPUT}")"
+elif [[ -n "${GATEFIT_SUITE_INPUT}" ]]; then
+  SUITE="${GATEFIT_SUITE_INPUT}"
+else
+  SUITE="${GATEFIT_ROOT}/tests/entitlements/goldens"
+fi
+cd "${GATEFIT_ROOT}"
+npm install --ignore-scripts
+node "${GATEFIT_ROOT}/bin/gatefit.js" run --suite "${SUITE}" --adapter "${ADAPTER}"

package/src/access-adapter.ts

@@ -0,0 +1,88 @@
+import { pathToFileURL } from "node:url";
+import fs from "node:fs";
+import { resolveUserOrPackage } from "./paths.ts";
+
+export type AccessSnapshot = {
+  locked: boolean;
+  plan?: string;
+  seats?: number;
+  features?: string[];
+};
+
+export type BillingEvent = {
+  id: string;
+  type: string;
+  customerId: string;
+  plan?: string;
+  seats?: number;
+  features?: string[];
+  paid?: boolean;
+  canceled?: boolean;
+  refunded?: boolean;
+  status?: string;
+  httpStatus?: number;
+  stripeHttpStatus?: number;
+  cancel_at_period_end?: boolean;
+  period_end?: number;
+  now?: number;
+};
+
+export type AccessAdapter = {
+  apply(event: BillingEvent): void | Promise<void>;
+  snapshot(customerId: string): AccessSnapshot | Promise<AccessSnapshot>;
+  reset?: () => void | Promise<void>;
+};
+
+export type CompareResult = {
+  ok: boolean;
+  mismatches: string[];
+};
+
+const LIVE_KEY = /\bsk_live(?:_[A-Za-z0-9_]*)?/;
+
+export function assertNoLiveStripeSecret(haystack: string): void {
+  if (LIVE_KEY.test(haystack)) {
+    throw new Error("refuse sk_live: Gatefit will not load a live Stripe secret");
+  }
+}
+
+export function compareAccess(actual: AccessSnapshot, expected: AccessSnapshot): CompareResult {
+  const mismatches: string[] = [];
+  const keys = Object.keys(expected) as (keyof AccessSnapshot)[];
+  for (const key of keys) {
+    const want = expected[key];
+    const got = actual[key];
+    if (JSON.stringify(got) !== JSON.stringify(want)) {
+      mismatches.push(`${String(key)}: expected ${JSON.stringify(want)}, got ${JSON.stringify(got)}`);
+    }
+  }
+  return { ok: mismatches.length === 0, mismatches };
+}
+
+export async function loadAdapter(spec: string): Promise<AccessAdapter> {
+  const resolved = resolveUserOrPackage(spec);
+  const source = fs.readFileSync(resolved, "utf8");
+  assertNoLiveStripeSecret(source);
+  assertNoLiveStripeSecret(JSON.stringify(process.env));
+  const mod = (await import(pathToFileURL(resolved).href)) as {
+    createAdapter?: () => AccessAdapter;
+    default?: AccessAdapter | (() => AccessAdapter);
+    adapter?: AccessAdapter;
+  };
+  const adapter = instantiateAdapter(mod);
+  if (!adapter || typeof adapter.apply !== "function" || typeof adapter.snapshot !== "function") {
+    throw new Error(`adapter ${spec} must export createAdapter() or AccessAdapter with apply + snapshot`);
+  }
+  return adapter;
+}
+
+function instantiateAdapter(mod: {
+  createAdapter?: () => AccessAdapter;
+  default?: AccessAdapter | (() => AccessAdapter);
+  adapter?: AccessAdapter;
+}): AccessAdapter | undefined {
+  if (typeof mod.createAdapter === "function") return mod.createAdapter();
+  const candidate = mod.default ?? mod.adapter;
+  if (typeof candidate === "function") return candidate();
+  return candidate;
+}

package/src/access-rules.ts

@@ -0,0 +1,104 @@
+import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
+
+export type AccessStore = {
+  rows: Map<string, AccessSnapshot>;
+  seen: Set<string>;
+};
+
+export function emptyStore(): AccessStore {
+  return { rows: new Map(), seen: new Set() };
+}
+
+export function isPaid(event: BillingEvent): boolean {
+  return event.type === "invoice.paid" || event.paid === true;
+}
+
+export function isImmediateCancel(event: BillingEvent): boolean {
+  return (
+    event.canceled === true ||
+    event.type === "customer.subscription.deleted" ||
+    event.type === "customer.subscription.canceled"
+  );
+}
+
+export function isCanceled(event: BillingEvent): boolean {
+  return isImmediateCancel(event);
+}
+
+export function isCapePeriodEnded(event: BillingEvent): boolean {
+  return (
+    event.cancel_at_period_end === true &&
+    typeof event.now === "number" &&
+    typeof event.period_end === "number" &&
+    event.now >= event.period_end
+  );
+}
+
+export function isDispute(event: BillingEvent): boolean {
+  return (
+    event.type === "charge.dispute.created" ||
+    event.type === "radar.early_fraud_warning.created"
+  );
+}
+
+export function isRefund(event: BillingEvent): boolean {
+  return event.refunded === true || event.type === "charge.refunded";
+}
+
+export function isUnpaidExhaust(event: BillingEvent): boolean {
+  return event.status === "unpaid" || event.type === "invoice.marked_uncollectible";
+}
+
+export function isPastDue(event: BillingEvent): boolean {
+  return event.status === "past_due" || event.type === "invoice.payment_failed";
+}
+
+export function isTrialing(event: BillingEvent): boolean {
+  return event.status === "trialing";
+}
+
+function withEntitlements(base: AccessSnapshot, event: BillingEvent): AccessSnapshot {
+  const next: AccessSnapshot = { ...base };
+  if (event.plan !== undefined) next.plan = event.plan;
+  if (event.seats !== undefined) next.seats = event.seats;
+  if (event.features !== undefined) next.features = event.features;
+  return next;
+}
+
+export function nextSnapshot(current: AccessSnapshot, event: BillingEvent): AccessSnapshot {
+  if (isDispute(event)) {
+    return { ...current, locked: true, features: [] };
+  }
+  if (
+    isRefund(event) ||
+    isImmediateCancel(event) ||
+    isPastDue(event) ||
+    isUnpaidExhaust(event) ||
+    isTrialing(event)
+  ) {
+    return { ...current, locked: true };
+  }
+  if (isCapePeriodEnded(event)) {
+    return { ...current, locked: true };
+  }
+  if (isPaid(event)) {
+    return withEntitlements({ ...current, locked: false }, event);
+  }
+  if (
+    event.type === "customer.subscription.updated" &&
+    (event.cancel_at_period_end === true ||
+      event.seats !== undefined ||
+      event.plan !== undefined ||
+      event.features !== undefined)
+  ) {
+    return withEntitlements(current, event);
+  }
+  return current;
+}
+
+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));
+}

package/src/adapters/hardened.ts

@@ -0,0 +1,20 @@
+import type { AccessAdapter } from "../access-adapter.ts";
+import { applyBillingEvent, emptyStore } from "../access-rules.ts";
+
+export function createAdapter(): AccessAdapter {
+  const store = emptyStore();
+  return {
+    apply(event) {
+      applyBillingEvent(store, event);
+    },
+    snapshot(customerId) {
+      return store.rows.get(customerId) ?? { locked: true };
+    },
+    reset() {
+      store.rows.clear();
+      store.seen.clear();
+    },
+  };
+}
+
+export default createAdapter;

package/src/adapters/naive.ts

@@ -0,0 +1,25 @@
+import type { AccessAdapter, AccessSnapshot, BillingEvent } from "../access-adapter.ts";
+
+function stripeLooksPaid(event: BillingEvent): boolean {
+  return event.httpStatus === 200 || event.stripeHttpStatus === 200;
+}
+
+export function createAdapter(): AccessAdapter {
+  const rows = new Map<string, AccessSnapshot>();
+  return {
+    apply(event: BillingEvent) {
+      // Anti-pattern: treat Stripe HTTP 200 as access proof.
+      if (stripeLooksPaid(event)) {
+        rows.set(event.customerId, { locked: false, plan: event.plan });
+      }
+    },
+    snapshot(customerId: string) {
+      return rows.get(customerId) ?? { locked: true };
+    },
+    reset() {
+      rows.clear();
+    },
+  };
+}
+
+export default createAdapter;

package/src/adapters/sqlite.ts

@@ -0,0 +1,83 @@
+import { createRequire } from "node:module";
+import type { AccessAdapter, AccessSnapshot, BillingEvent } from "../access-adapter.ts";
+import { nextSnapshot } from "../access-rules.ts";
+
+const require = createRequire(import.meta.url);
+const Database = require("better-sqlite3") as typeof import("better-sqlite3");
+
+type AccessRow = {
+  customer_id: string;
+  locked: number;
+  plan: string | null;
+  seats: number | null;
+  features: string | null;
+};
+
+function rowToSnapshot(row: AccessRow | undefined): AccessSnapshot {
+  if (!row) return { locked: true };
+  const snap: AccessSnapshot = { locked: row.locked === 1 };
+  if (row.plan != null) snap.plan = row.plan;
+  if (row.seats != null) snap.seats = row.seats;
+  if (row.features != null) snap.features = JSON.parse(row.features) as string[];
+  return snap;
+}
+
+export function createAdapter(): AccessAdapter {
+  const filename = process.env.GATEFIT_SQLITE_PATH ?? ":memory:";
+  const db = new Database(filename);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS access (
+      customer_id TEXT PRIMARY KEY,
+      locked INTEGER NOT NULL,
+      plan TEXT,
+      seats INTEGER,
+      features TEXT
+    );
+    CREATE TABLE IF NOT EXISTS seen_events (
+      event_id TEXT PRIMARY KEY
+    );
+  `);
+  const seenAdd = db.prepare("INSERT OR IGNORE INTO seen_events (event_id) VALUES (?)");
+  const accessGet = db.prepare(
+    "SELECT customer_id, locked, plan, seats, features FROM access WHERE customer_id = ?",
+  );
+  const accessUpsert = db.prepare(`
+    INSERT INTO access (customer_id, locked, plan, seats, features)
+    VALUES (@customer_id, @locked, @plan, @seats, @features)
+    ON CONFLICT(customer_id) DO UPDATE SET
+      locked = excluded.locked,
+      plan = excluded.plan,
+      seats = excluded.seats,
+      features = excluded.features
+  `);
+  const clearAccess = db.prepare("DELETE FROM access");
+  const clearSeen = db.prepare("DELETE FROM seen_events");
+  const applyEvent = db.transaction((event: BillingEvent) => {
+    const inserted = seenAdd.run(event.id);
+    if (inserted.changes === 0) return;
+    const current = rowToSnapshot(accessGet.get(event.customerId) as AccessRow | undefined);
+    const next = nextSnapshot(current, event);
+    accessUpsert.run({
+      customer_id: event.customerId,
+      locked: next.locked ? 1 : 0,
+      plan: next.plan ?? null,
+      seats: next.seats ?? null,
+      features: next.features ? JSON.stringify(next.features) : null,
+    });
+  });
+
+  return {
+    apply(event: BillingEvent) {
+      applyEvent(event);
+    },
+    snapshot(customerId: string) {
+      return rowToSnapshot(accessGet.get(customerId) as AccessRow | undefined);
+    },
+    reset() {
+      clearAccess.run();
+      clearSeen.run();
+    },
+  };
+}
+
+export default createAdapter;