gatefit 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-All notable Gatefit changes are listed here. The version heading matches `package.json`. Tag `v0.5.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
 

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 the last published tarball (`gatefit@0.4.0` until tag `v0.5.0`) at https://www.npmjs.com/package/gatefit. This repo is `0.5.0`. The named gate runs `npm publish --dry-run` only. A `v*` tag publishes with OIDC. See [Releasing](#releasing).
+- **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
 ```
 
-This repo is `0.5.0`. Registry: 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.5.0` is not cut yet. After a human pushes the annotated tag:
+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.5.0
+- uses: gatefit/gatefit@v0.5.1
   with:
     adapter: src/your-access-adapter.ts
 ```
@@ -55,12 +57,12 @@ Marketplace-ready Action lives at the repo root (`action.yml`). Tag `v0.5.0` is
 Nested path still works:
 
 ```yaml
-- uses: gatefit/gatefit/.github/actions/gatefit@v0.5.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 notes [docs/release-v0.5.0.md](docs/release-v0.5.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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatefit",
-  "version": "0.5.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/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/cli.ts

@@ -25,6 +25,7 @@ function usage(): string {
     "  gatefit run --suite chaos --adapter <path> [--seed <value>]",
     "  gatefit adapter-check",
     "  gatefit live --adapter <path> [--scenario <id>]",
+    "  gatefit --help",
     "  gatefit --version",
   ].join("\n");
 }
@@ -96,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();