sproutboat 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,304 @@
+# Changelog
+
+All notable changes to `sproutboat` (the CLI) are documented here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
+follows [SemVer](https://semver.org/), pre-1.0 so a minor bump can still carry
+a breaking change.
+
+Reconstructed from git history on 2026-09-03 for everything through v0.4.11;
+maintained going forward by the `release` skill.
+
+## [Unreleased]
+
+## [0.9.0] - 2026-09-07
+### Added
+- KV content management: `kv key get`, `put`, `delete`, and `list`; bounded
+  `kv bulk get`, `put`, and `delete`; and cursor-paginated `kv export` files
+  that can be restored with `kv bulk put`.
+- CLI integration coverage for pagination, bounded batches, text and file
+  output, overwrite refusal, and cleanup after failed exports.
+- `sproutboat-env.d.ts` generation from project bindings.
+- Focused runnable examples for every supported binding.
+
+### Fixed
+- Static assets keep arbitrary binary bytes when they travel through the broker.
+- KV exports use a permission-restricted temporary file and move into place only
+  after a complete export. Failed exports leave neither partial output nor a
+  temporary file behind.
+- First-host builds no longer require Git or Make.
+
+### Changed
+- Development binaries compile with Porffor `-O0` for faster iteration.
+- The installation docs state that the CLI requires Bun and should be invoked
+  with `bunx` rather than `npx`.
+
+## [0.8.0] — 2026-09-07
+### Added
+- `sproutboat build --standalone`: one executable that carries its own bindings.
+  SQLite is compiled into the sprout, so a ~2 MB file serves KV, D1, R2, queues,
+  Durable Objects, alarms, analytics and assets with nothing beside it on disk —
+  no Bun, no broker, no control plane. State lives in `<name>.data/store.sqlite`
+  plus `d1/<binding>.sqlite`, the same layout `sproutboat dev` writes, which is
+  what lets one conformance suite hold both backends to the same behaviour.
+  Secrets come from the environment (then `<data>/secrets.json`) and a missing
+  one refuses the boot, listing every name at once, rather than throwing on the
+  first request that needs it. Cron ticks, queue batches and DO alarms run on
+  in-process timers; assets are baked in, capped at 8 MB.
+- Outbound TLS from a standalone binary. `fetch("https://…")` verifies against
+  curl's Mozilla-derived root set via BearSSL, linked in beside SQLite
+  (1.86 → 2.02 MB). `SB_CA_BUNDLE` adds a private or corporate CA to that set;
+  it only ever adds trust, and nothing disables verification.
+- Durable Object alarms: `setAlarm` / `getAlarm` / `deleteAlarm` and the
+  `alarm()` handler. At most one alarm is pending per object and a later
+  `setAlarm` replaces it, matching Workers. Delivery claims before running, so
+  an `alarm()` that schedules its own next run is not erased by the delivery
+  that invoked it.
+- Service bindings: `env.<BINDING>.fetch()` reaches another deployment on the
+  same node through the edge on loopback. This is the CLI half; a binding that
+  resolves to nothing reports the target as undeployed rather than failing as a
+  502.
+- Binary values in the binding frame. An R2 object body now travels beside the
+  JSON rather than encoded inside it.
+- `SB_FETCH_MAX_BYTES` (32 MiB default) caps an outbound response body. An
+  unbounded upstream could previously drive a sprout's memory to whatever it
+  chose to send.
+
+### Fixed
+- `d1.exec` ran only the first statement of a multi-statement script, so a
+  schema built in one `exec()` call silently created only its first table.
+- `r2.get` / `head` / `put` / `list` returned flat fields where the shim reads
+  `r.object`, and `ae.query` omitted the `count` its caller reads.
+- Trigger authentication accepted *any* caller when no token was configured.
+  The hole predates this release; a standalone binary listening on a public
+  interface is what made it reachable.
+- Binary R2 values were corrupted in transit — `0x08` and `0x0c` arrived as
+  `b` and `f`.
+- A retried binding call could apply a write twice. Every request now carries an
+  id and the broker replays the cached reply for a repeat of a mutating op
+  instead of performing it again.
+
+### Changed
+- A dropped broker connection is retried four times with 0/5/25/100 ms backoff
+  instead of failing after one attempt, which covers a broker restart mid-call.
+- The bundled (Bun) standalone backend is gone. The embedded one passes the same
+  suite at 1.9 MB against 63 MB, and TLS removed its last real advantage.
+- A native-fetch binary cannot see `argv` — Porffor's runtime init calls
+  `porf_init(0, NULL)` — so a standalone binary is configured through `PORT`,
+  `SB_DATA_DIR` / `SPROUTBOAT_DATA` and the environment only, never flags.
+
+### Performance
+- An 8 MB R2 put through the broker went from 255 MB to 149 MB peak RSS.
+- The broker's frame reader no longer re-concatenates its buffer per chunk.
+
+## [0.7.0] — 2026-09-06
+### Added
+- `compatibility_date` now reaches the artifact instead of being validated and
+  dropped. It is recorded in `manifest.json` as `compatibilityDate` and baked
+  into the binary as `__sbCompat`, so a future runtime change can be gated on
+  `__sbCompat >= "YYYY-MM-DD"` and old binaries keep the semantics they were
+  compiled with. The manifest field is optional and `schemaVersion` stays at 2,
+  so artifacts built before this release remain deployable and rollback keeps
+  working.
+- A version-skew warning. Control planes advertise `x-sproutboat-control` and
+  `x-sproutboat-min-cli` on every `/api/` response; when this CLI is below the
+  advertised minimum it says so once per run, instead of leaving the user with
+  an unexplained 400. A control plane that predates the handshake sends no
+  headers and nothing changes.
+- `CONTRACTS.md`, generated from source in the same style as `SURFACE.md`: the
+  broker ops, storage tables, manifest fields and config keys that a release may
+  not break, plus golden fixtures for the manifest and the storage format so a
+  regression fails a test rather than a user's deployment.
+
+## [0.6.1] — 2026-09-06
+### Fixed
+- `sproutboat queues` help (and the generated `SURFACE.md`) claimed queue
+  consumers "are not implemented yet". They are implemented, and they run on
+  the deployed path as well as under `dev`: the supervisor passes
+  `--sprout-url` to the broker, which delivers messages in batches, retries a
+  failed or explicitly-retried message after 5s, and stops delivering it after
+  5 attempts. The summary now describes what actually happens.
+
+### Changed
+- Tooling only, no change to how the CLI behaves: oxfmt is scoped to the JS
+  family with the pre-commit hook's glob matched to it, TypeScript moves
+  5.9 → 7.0, and the GitHub Actions group is bumped.
+
+## [0.6.0] — 2026-09-05
+### Added
+- `bindings.json` now carries `vars` — the baked plain values a sprout was
+  built with — so the control plane can show what a version was compiled
+  against. They ride along for display only; the broker never serves them,
+  they are compiled into the sprout itself. A project whose only binding
+  config is `vars` now gets a sidecar written at all, where before it got
+  none.
+
+### Changed
+- Tooling only, no change to how the CLI behaves: the tree is now formatted
+  with oxfmt 0.66.0 (the config landed in 0.5.0 but was never run over the
+  tree), markdown is excluded from formatting, a lefthook pre-commit hook
+  formats staged files and lints, the last 10 oxlint warnings are cleared,
+  and CI gates lint alongside typecheck and test.
+- README rewritten shorter: a logo lockup that survives both GitHub themes
+  (`docs/logo-light.svg` / `docs/logo-dark.svg` behind a `<picture>`), the
+  everyday commands as a five-row table, and the full command inventory left
+  to the generated `SURFACE.md` instead of duplicated by hand.
+
+## [0.5.0] — 2026-09-03
+### Added
+- `dev [--port <n>] [--no-watch]` — run the project on this machine against a
+  real broker (KV/D1/secrets/etc. all work), rebuilding on save.
+- `build --target host` — compile for the machine doing the build instead of
+  cross-compiling for a box; what `dev` uses, and runnable standalone.
+- Handlers may now `import` — relative modules across the project, and npm
+  packages from the project's own `node_modules`. The entry point is bundled
+  before it reaches Porffor; the capability checks run against that bundled
+  output, so a dependency can't reach `process`/`Bun`/`node:*` any more than
+  hand-written code can.
+- `sproutboat init` scaffolds a `.gitignore` (`.sproutboat/`, `.dev.vars`,
+  `node_modules/`) alongside the project files, unless one already exists.
+
+### Fixed
+- Async `fetch` handlers hung indefinitely — `__sbEntry` chained the #28
+  CPU-time tag onto the handler's own promise, and Porffor's native-fetch
+  server only resolves a promise a handler returns directly, never one
+  derived from `.then()`.
+- `new Proxy(...)` compiles under Porffor alpha-4 and then silently ignores
+  every trap — a trapped property just reads back `undefined`. `check` now
+  rejects it before that reaches a deploy as an unexplained 502.
+- `sproutboat init` crashed with a raw `EEXIST` stack trace, and could leave
+  a half-scaffolded project, if `src/index.js` already existed but
+  `sproutboat.jsonc` didn't. Both targets are checked before either is
+  written.
+- Re-running `sproutboat build` (or `dev`'s rebuild-on-save) could fail to
+  link: the artifact directory is content-addressed, so an unchanged rebuild
+  targeted the previous binary, which was `chmod 0555` and possibly still
+  running.
+- The broker's local dev state directory was never created before opening
+  its SQLite file, so a first `sproutboat dev` run failed outright.
+
+### Changed
+- Lint: adopted the anti-slop Oxlint plugin and migrated the tree onto it —
+  no more bare `unknown`/`Record<string, unknown>` at binding boundaries,
+  every non-const type assertion carries a `SAFETY:` comment.
+
+## [0.4.11] — 2026-09-02
+### Changed
+- README rewritten for current commands and config; points at the docs site.
+
+## [0.4.10] — 2026-09-02
+### Changed
+- `domains`: prints the A record to add, and any DNS reachability warning.
+
+## [0.4.9] — 2026-09-02
+### Changed
+- `deploy` (#80): dropped the client-side dedup check in favour of trusting
+  the server's own no-op response.
+
+## [0.4.8] — 2026-09-02
+### Fixed
+- `deploy` (#80): no longer skipped the upload when only assets or bindings
+  had changed but the sprout binary hadn't.
+
+## [0.4.7] — 2026-09-02
+### Added
+- `deploy` auto-provisions an id-less storage binding (wrangler-style):
+  creates the account-level resource, writes its id back into
+  `sproutboat.jsonc`.
+
+## [0.4.6] — 2026-09-02
+### Added
+- `sproutboat resource` — manage account-level storage resources directly.
+- `sproutboat.jsonc` storage bindings accept `{ binding, id }`, not just a
+  bare name.
+### Changed
+- Broker keys KV/R2/queue/D1 stores by resource id when one is bound, so the
+  data survives a redeploy and can be shared across projects.
+
+## [0.4.5] — 2026-09-02
+### Changed
+- `deploy` dropped the "✓ serving" line — silence now means the health check
+  passed.
+
+## [0.4.4] — 2026-09-02
+### Added
+- `--version`, a once-a-day update-available notice, a richer deploy echo.
+### Changed
+- Misuse now exits `2` (getopt convention) instead of `1`.
+
+## [0.4.3] — 2026-09-02
+### Changed
+- `--help` output: grouped, emoji-labelled, aligned — was one wall-of-text
+  usage line.
+
+## [0.4.2] — 2026-09-02
+### Added
+- `tail --sprout` streams the running sprout's and broker's stdout/stderr.
+### Changed
+- `deploy` waits for the health check and prints every binding in the
+  report; `delete` takes flexible args plus `?confirm`; the banner reads the
+  real installed version.
+
+## [0.4.0] — 2026-09-01
+### Added
+- `sproutboat domains` and `sproutboat secrets` commands.
+- `deploy` uploads the `bindings.json` / `assets.json` sidecars alongside
+  the sprout binary.
+- The worker self-reports per-invocation CPU time (`x-sb-cpu-ms`).
+- Deploy surfaces a Porffor pin drift warning when the live version was
+  built against a different compiler pin than the one about to deploy.
+### Changed
+- Renamed "worker" to "sprout" throughout the CLI, broker, and examples.
+
+## [0.3.0] — 2026-09-01
+### Added
+- Published to npm via Trusted Publishing (OIDC) — no token secret in CI.
+### Changed
+- `src/wrap.ts` extracted with `runtime/*` subpath exports, so the monorepo
+  can consume the binding/manifest contracts as a dependency instead of a
+  hand-vendored copy.
+- CSPRNG-backed `crypto.getRandomValues`; the deploy binary is stripped.
+- One long-lived broker connection per worker instead of reconnecting on
+  every binding call; `env.<SECRET>` memoized; `assets.get` made synchronous
+  with the broker service; WAL + `synchronous=NORMAL` and parameterised
+  `LIMIT` back-ported from the monorepo's broker.
+
+## [0.2.1] — 2026-08-31
+### Changed
+- Ships a prebuilt uWebSockets archive, so the first build needs neither
+  `git` nor `make` on `PATH`.
+
+## [0.2.0] — 2026-08-31
+Initial release, extracted from the `sproutboat` monorepo (`apps/cli`) as
+its own package.
+### Added
+- Cross-compiles a handler to a static `linux-x86_64` binary with Porffor +
+  Zig — no Docker.
+- Static assets binding, with the `examples/kitchen-sink` Astro app as a
+  worked example.
+- `SURFACE.md`, generated and drift-checked against the actual command/env
+  surface.
+### Changed
+- Patches Porffor at build time rather than via a `postinstall` hook.
+- Renamed the package to `sproutboat` (was `@sproutboat/cli`); dropped the
+  `sprout` bin alias in favour of a user-defined shell alias.
+
+[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/baronunread/sproutboat-cli/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.11...v0.5.0
+[0.4.11]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.10...v0.4.11
+[0.4.10]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.9...v0.4.10
+[0.4.9]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.8...v0.4.9
+[0.4.8]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.7...v0.4.8
+[0.4.7]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.6...v0.4.7
+[0.4.6]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.5...v0.4.6
+[0.4.5]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.4...v0.4.5
+[0.4.4]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.3...v0.4.4
+[0.4.3]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/baronunread/sproutboat-cli/compare/v0.4.0...v0.4.2
+[0.4.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/baronunread/sproutboat-cli/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/baronunread/sproutboat-cli/releases/tag/v0.2.0

package/README.md

@@ -19,6 +19,12 @@ for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
 
 ## Using
 
+Sproutboat is a Bun tool. It needs **Bun 1.4+** on the machine you build from,
+and `bunx` rather than `npx`: the CLI runs on Bun's APIs, and `npm install`
+cannot resolve it today ([#134](https://github.com/baronunread/sproutboat/issues/134)).
+Nothing is needed on the machine that *runs* a sprout: that gets a static
+binary.
+
 ```sh
 bunx sproutboat init hello
 cd hello
@@ -32,7 +38,7 @@ bunx sproutboat login --api-url https://control.example.com   # one browser appr
 bunx sproutboat deploy
 ```
 
-Or install it once and drop the `bunx`:
+Or install it once with Bun and drop the `bunx`:
 
 ```sh
 bun add -g sproutboat     # then: sproutboat deploy, sproutboat tail, ...
@@ -63,6 +69,32 @@ Run `sproutboat` with no arguments for the grouped list.
 [`SURFACE.md`](SURFACE.md) is the generated inventory: every command, every
 argument, every env var, kept honest by a drift test.
 
+### KV data and waitlist export
+
+Manage one namespace by its account-level name:
+
+```sh
+sproutboat kv key list registrations --prefix email:
+sproutboat kv key get registrations email:person@example.com --text
+sproutboat kv key put registrations email:person@example.com joined
+sproutboat kv key delete registrations email:person@example.com --yes
+sproutboat kv export registrations --prefix email: --output registrations.json
+```
+
+Bulk put, and therefore exported dumps, use the version 1 text-value format:
+
+```json
+[
+  { "key": "email:person@example.com", "value": "joined" }
+]
+```
+
+`kv bulk get` and `kv bulk delete` accept a JSON array of key strings. `kv bulk
+put` accepts the entry array above. The CLI sends large inputs in bounded
+batches. Export pages through the namespace and writes incrementally to a
+permission-restricted temporary file, then renames it into place only after a
+complete export. Existing output files require `--force`.
+
 ## Config
 
 `sproutboat.jsonc`: the entry point plus Cloudflare-shaped `env.*` bindings.

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.7.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.9.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -11,13 +11,14 @@
 | --- | --- | --- |
 | `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
+| `types` | `[project-dir]` | Write sproutboat-env.d.ts from the config, so an editor knows what `env` holds. `dev` and `deploy` refresh it when the config is newer. |
 | `dev` | `[project-dir] [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save. |
-| `build` | `[project-dir] [--target host]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. |
+| `build` | `[project-dir] [--target host] [--standalone]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
 | `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
-| `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc. |
+| `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ...` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc; key and bulk operations manage contents, and export writes a restorable JSON dump. |
 | `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | D1 databases. `create` prints the id to bind from sproutboat.jsonc. |
 | `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc. |
 | `queues` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | Queues. `create` prints the id to bind from sproutboat.jsonc; consumers deliver in batches with retries, and stop after 5 attempts. |
@@ -29,7 +30,7 @@
 | `whoami` | — | Show the active endpoint and the account the stored token belongs to. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami>
 ```
 
 ## Environment variables
@@ -39,7 +40,9 @@ usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port
 | `SPROUTBOAT_API_URL` | Control-plane URL. Overrides the saved active endpoint. |
 | `SPROUTBOAT_TOKEN` | API token. Overrides the saved credential for the endpoint. |
 | `SPROUTBOAT_ZIG` | Path to a Zig binary to use instead of downloading the pinned one. |
-| `SPROUTBOAT_UWS_TARBALL` | Path to a prebuilt uWebSockets (x86_64-linux-musl) tarball to seed the Porffor cache with, instead of downloading it (removes the first-build git + make need). |
+| `SPROUTBOAT_UWS_TARBALL` | Path to a uWebSockets source tarball to seed the Porffor cache with, instead of the one vendored in the package. Both targets are seeded from it. |
+| `CC` | C compiler used to build uSockets for a host build (default `cc`). A host build needs one regardless: it is what Porffor compiles its own generated C with. |
+| `AR` | Archiver used to assemble uSockets.a for a host build (default `ar`). |
 | `SPROUTBOAT_COMPILE_TIMEOUT_MS` | Porffor compile timeout in ms (default 600000). |
 | `SPROUTBOAT_VARS_JSON` | JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the sprout module. |
 | `SPROUTBOAT_BINDINGS_JSON` | The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line. |
@@ -51,6 +54,13 @@ usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port
 | `SB_BROKER_PORT` | Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs). |
 | `SB_BROKER_TOKEN` | Per-deployment auth token the sprout sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT). |
 | `SB_SPROUT_URL` | http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it. |
+| `SB_DATA_DIR` | Where a standalone binary keeps store.sqlite and d1/ (#15). Read by the sprout itself in an embedded build; defaults to ./<name>.data. |
+| `SPROUTBOAT_DATA` | Data directory for a standalone binary, after --data and SB_DATA_DIR, before the ./<name>.data default (#15). |
+| `SB_CA_BUNDLE` | PEM bundle of extra certificate authorities a standalone binary should trust, on top of the compiled-in Mozilla root set (#15). Adds trust; nothing disables verification. |
+| `SB_FETCH_MAX_BYTES` | Largest outbound `fetch()` response body a sprout will read, in bytes (default 33554432). The size is the remote host's choice and the body is held whole, so this is the ceiling that stops one upstream exhausting memory. |
+| `SB_REQUEST_BODY_MAX` | Largest inbound request body the runtime accepts, in bytes (default 1048576). Anything larger is refused with 413 before the handler runs. |
+| `SB_EXTRA_CFLAGS` | Flags added to Porffor's native-fetch compile step, set by the build so inline C can include BearSSL's header (#15). |
+| `SB_EXTRA_LINK` | Objects to add to Porffor's native-fetch link line, set by the build so a standalone binary links SQLite and BearSSL (#15). |
 
 ## Build toolchain (pinned)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -22,12 +22,14 @@
     "sproutboat": "src/main.ts"
   },
   "files": [
+    "CHANGELOG.md",
+    "SURFACE.md",
     "src",
-    "!src/*.test.ts",
-    "vendor",
-    "SURFACE.md"
+    "types",
+    "vendor"
   ],
   "type": "module",
+  "types": "./types/sproutboat.d.ts",
   "exports": {
     "./runtime/config": "./src/config.ts",
     "./runtime/source": "./src/source.ts",
@@ -36,12 +38,14 @@
     "./runtime/broker": "./src/broker.ts",
     "./runtime/wrap": "./src/wrap.ts",
     "./runtime/prelude": "./src/native-fetch-prelude.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./types": "./types/sproutboat.d.ts"
   },
   "scripts": {
     "prepare": "lefthook install || true",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
+    "examples": "bun examples/smoke.ts",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
     "test": "bun test",
@@ -49,7 +53,9 @@
     "surface": "UPDATE_SURFACE=1 bun test src/surface.test.ts",
     "version": "bun run surface && git add SURFACE.md",
     "prepublishOnly": "bun run typecheck && bun test",
-    "style": "bunx style-doctor@latest --quiet"
+    "style": "bunx style-doctor@latest --quiet",
+    "kitchen-sink": "bun examples/kitchen-sink/harness.ts",
+    "kitchen-sink:standalone": "bun examples/kitchen-sink/harness-standalone.ts"
   },
   "dependencies": {
     "esbuild": "^0.28.2",

package/src/bearssl.ts

@@ -0,0 +1,180 @@
+/**
+ * #15 — the TLS client an embedded sprout links against.
+ *
+ * BearSSL (MIT), plus the Mozilla root set compiled in as trust anchors. Both
+ * are downloaded, checksummed and built once into ~/.cache/sproutboat, keyed by
+ * version and target, in the same shape as the SQLite object.
+ *
+ * Why compiled-in anchors: a static musl binary has no portable system trust
+ * store — locations differ per distro and macOS wants keychain calls — so the
+ * root set travels with the binary. celld does the same. `SB_CA_BUNDLE` can
+ * point at a different bundle at run time.
+ *
+ * Why BearSSL over mbedTLS: measured, not assumed. A complete static client
+ * with all 121 anchors came to 192 KB against a 1.9 MB sprout.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export const BEARSSL_VERSION = "0.6";
+const BEARSSL_URL = `https://bearssl.org/bearssl-${BEARSSL_VERSION}.tar.gz`;
+const BEARSSL_SHA256 = "6705bba1714961b41a728dfc5debbe348d2966c117649392f8c8139efc83ff14";
+
+/**
+ * The Mozilla root set, as curl publishes it. Pinned by hash like everything
+ * else: a root store that changed under us without a version bump would be a
+ * silent change to what the binary trusts.
+ *
+ * ponytail: pinned per CLI release, so a certificate authority added after this
+ * release is unknown until the next one. Fine while releases are frequent;
+ * revisit if a user is ever stuck on an old CLI for months.
+ */
+const CACERT_URL = "https://curl.se/ca/cacert.pem";
+const CACERT_SHA256 = "f66dff1bdf8f96060b8177976f8b7d9254bc89bc4db933d769f7384d28480bc9";
+
+const cacheDir = (): string => resolve(homedir(), ".cache/sproutboat", `bearssl-${BEARSSL_VERSION}`);
+
+export type BearsslInput = {
+  target: "linux-x86_64" | "host";
+  /** Zig binary, required for the linux target. */
+  zigBin?: string;
+};
+
+export type BearsslBuild = {
+  /** Add to the compile step so the prelude can `#include <bearssl.h>`. */
+  includeDir: string;
+  /** Objects to add to the link line: the library plus the trust anchors. */
+  objects: string[];
+};
+
+const run = (cmd: string, args: string[], cwd?: string): Promise<{ code: number; stderr: string }> =>
+  new Promise((done) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+    child.on("close", (code) => done({ code: code ?? 1, stderr }));
+  });
+
+async function download(url: string, expected: string, to: string): Promise<Buffer> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`could not download ${url}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (digest !== expected) throw new Error(`checksum mismatch for ${url}: expected ${expected}, got ${digest}`);
+  await writeFile(to, bytes);
+  return bytes;
+}
+
+/** Unpack the source tree once, and build the host tools we need from it. */
+async function sourceTree(): Promise<string> {
+  const dir = cacheDir();
+  const tree = resolve(dir, `bearssl-${BEARSSL_VERSION}`);
+  if (existsSync(resolve(tree, "inc/bearssl.h"))) return tree;
+  await mkdir(dir, { recursive: true });
+  const tarball = resolve(dir, "bearssl.tar.gz");
+  if (!existsSync(tarball)) await download(BEARSSL_URL, BEARSSL_SHA256, tarball);
+  const untar = await run("tar", ["xzf", tarball], dir);
+  if (untar.code !== 0) throw new Error(`could not unpack BearSSL: ${untar.stderr}`);
+  return tree;
+}
+
+/** Every .c under src/, which is what the library is. */
+async function sources(tree: string): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const path = resolve(dir, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.name.endsWith(".c")) found.push(path);
+    }
+  };
+  await walk(resolve(tree, "src"));
+  return found.sort();
+}
+
+/**
+ * `brssl ta` turns a PEM bundle into C trust-anchor structs. It is a host tool,
+ * so it is built with the host compiler whatever the sprout's target is.
+ */
+async function trustAnchorTool(tree: string): Promise<string> {
+  const tool = resolve(tree, "build/brssl");
+  if (existsSync(tool)) return tool;
+  const make = await run("make", ["-j8", "build/brssl"], tree);
+  if (!existsSync(tool)) throw new Error(`could not build brssl: ${make.stderr}`);
+  return tool;
+}
+
+/**
+ * Generate the trust anchors as linkable C.
+ *
+ * `brssl` emits them `static`, which is right for its own samples and useless
+ * to us: the prelude has to reach them from another translation unit. Rename
+ * the array and publish a count beside it.
+ */
+async function trustAnchorSource(tree: string): Promise<string> {
+  const out = resolve(cacheDir(), "trust-anchors.c");
+  if (existsSync(out)) return out;
+  const pem = resolve(cacheDir(), "cacert.pem");
+  if (!existsSync(pem)) await download(CACERT_URL, CACERT_SHA256, pem);
+  const tool = await trustAnchorTool(tree);
+
+  const generated = await new Promise<string>((done, fail) => {
+    const child = spawn(tool, ["ta", pem], { stdio: ["ignore", "pipe", "pipe"] });
+    let text = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => (text += String(chunk)));
+    child.stderr.on("data", (chunk) => (err += String(chunk)));
+    child.on("close", (code) => (code === 0 ? done(text) : fail(new Error(`brssl ta failed: ${err}`))));
+  });
+
+  const count = /#define TAs_NUM\s+(\d+)/.exec(generated)?.[1];
+  if (!count) throw new Error("brssl ta produced no TAs_NUM — its output format changed");
+  const linkable = generated
+    .replace(/static const br_x509_trust_anchor TAs\[/, "const br_x509_trust_anchor sb_trust_anchors[")
+    .replace(/#define TAs_NUM\s+\d+/, `const size_t sb_trust_anchor_count = ${count};`);
+  await writeFile(out, `#include <stddef.h>\n#include "bearssl.h"\n${linkable}\n`);
+  return out;
+}
+
+/** Compile one C file, caching on the output path. */
+async function compile(cc: string, prefix: string[], source: string, out: string, includes: string[]): Promise<void> {
+  if (existsSync(out)) return;
+  const result = await run(cc, [...prefix, "-c", source, "-o", out, "-Os", ...includes.flatMap((i) => ["-I", i])]);
+  if (result.code !== 0) throw new Error(`could not compile ${source}:\n${result.stderr}`);
+}
+
+/** BearSSL objects plus trust anchors for this target, building them on first use. */
+export async function ensureBearssl(input: BearsslInput): Promise<BearsslBuild> {
+  const tree = await sourceTree();
+  const includeDir = resolve(tree, "inc");
+  const objDir = resolve(cacheDir(), `obj-${input.target}`);
+  await mkdir(objDir, { recursive: true });
+
+  const [cc, prefix] =
+    input.target === "host"
+      ? (["cc", []] as const)
+      : ([input.zigBin ?? "zig", ["cc", "-target", "x86_64-linux-musl"]] as const);
+  const includes = [includeDir, resolve(tree, "src")];
+
+  const objects: string[] = [];
+  // Sequential rather than parallel: this runs once per target and a burst of
+  // ~180 compiler processes is a worse neighbour than a slow first build.
+  for (const source of await sources(tree)) {
+    const out = resolve(objDir, `${source.split("/").pop()!.replace(/\.c$/, "")}.o`);
+    await compile(cc, [...prefix], source, out, includes);
+    objects.push(out);
+  }
+
+  const anchors = await trustAnchorSource(tree);
+  const anchorObject = resolve(objDir, "trust-anchors.o");
+  await compile(cc, [...prefix], anchors, anchorObject, includes);
+  objects.push(anchorObject);
+
+  return { includeDir, objects };
+}
+
+export const bearsslStamp = (): string => `bearssl/${BEARSSL_VERSION}`;