Local development: createBoolClient apiKey + the bool CLI (link, types, entities, deploy)

[HomemadeToast57]

The SDK half of using a Bool project as a managed backend from your own machine (companion PR codehs/bool#487 adds the platform endpoints + MCP tools).

Client

createBoolClient({ ..., apiKey }) — a Bool data key (boolsk_ project admin, or boolk_ end-user) rides the api_key header on every gateway call (db / users / ai planes), so the client now works from Node scripts, a local Vite app, or CI. Without apiKey, behavior is byte-for-byte unchanged.

CLI (bool, zero dependencies)

• bool link --project <id> — fetches the project's connection descriptor, writes bool.config.json (public), puts the owner-only admin data key in .env.bool (and gitignores it), and pulls entity types.
• bool types — regenerates bool/types.d.ts from the project's entity schemas so bool.entities.<name> is fully typed locally.
• bool entities — prints the declared models + fields.
• bool entities pull / bool entities push — round-trip the entity schema files (bool/entities/*.jsonc) between the project and disk: pull writes them verbatim (paths confined to bool/entities/), push declares every local file on the project (additive migrations server-side; per-file results + warnings; exit 1 if any fail).
• bool deploy — zips the app source (store-only zero-dep zip writer; node_modules/.git/build output/env files excluded) and publishes via the drop pipeline: POST /api/drops → PUT the archive → poll the signed status URL to ready/failed. Bool builds in the cloud; the project URL stays stable.

Platform calls authenticate with a personal access token (--token / BOOL_TOKEN). All command logic lives in src/cli.ts behind an injectable-deps seam; src/cli-entry.ts is the bin shim.

Tests

• src/cli.test.ts — hermetic (stubbed fetch + temp dirs): link happy path + non-owner + v1-project error, types refresh, entities push (per-file results, warnings, failure exit) and pull (verbatim write + hostile-path confinement), deploy happy path / failed build / exclusion rules, entities listing, arg parsing, token errors.
• src/zip.test.ts — CRC-32 check vector, structural validation of the archive, and an unzip round-trip when the system unzip exists.
• src/client.test.ts — new "local development" block pinning the api_key header on all three planes (and its absence without the option).
• bun test 94 pass / 0 fail; bun run typecheck and bun run build green (bin shebang verified).

Release

0.2.0-next.11 on the canary channel; CHANGELOG + README updated. Requires the platform endpoints from codehs/bool#487.

🤖 Generated with Claude Code

https://claude.ai/code/session_011zKXrczjUj4pce5BH9Y1HL

[HomemadeToast57]

Verified this branch end-to-end from a local session against a real dev stack (dev Supabase + local platform server running codehs/bool#488, which speaks the same REST contract as #487):

• bool link --project … --token … → wrote bool.config.json, fetched the owner boolsk_ key into .env.bool, pulled entity types ✓
• bool types → refreshed the combined .d.ts (picked up a newly-defined entity) ✓
• createBoolClient({ …, apiKey }) from a Node process: create / filter({ $regex }) / update / delete through the real gateway, all green ✓

One behavior worth documenting in the README/CLI output: on a private entity, admin-key creates must pass owner_id explicitly (auth.uid() is NULL on the admin path, and the column is NOT NULL) — public entities are unaffected.

🤖 Generated with Claude Code

[HomemadeToast57]

Thanks for the end-to-end verification! Documented the private-entity owner_id behavior in d3b2f2b (README local-dev section + bool link's next-steps output), and fixed the MCP create_record description on the platform side (codehs/bool@8b558388) — it previously only described the nullable-column case, not the NOT-NULL rejection on fresh private tables.

---

Generated by Claude Code