sproutboat 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,365 @@
+# 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.10.0] - 2026-09-11
+### Added
+- Per-platform native CLI: `npm install sproutboat` pulls a prebuilt binary for
+  the host (`@sproutboat/cli-{darwin,linux}-{arm64,x64}`) behind a thin launcher
+  that preserves signals and embeds its own version, so the CLI runs without Bun
+  on `PATH`.
+- Porffor is fetched on the first build, not installed as a dependency: the
+  pinned commit is downloaded into `~/.cache/sproutboat`, SHA-256 verified, and
+  patched there. Installation clones nothing and runs no Git, Make or compiler.
+- `request.cf.clientIp` in standalone builds, from a server-set
+  `x-sb-remote-addr`, with `SB_TRUSTED_PROXIES` for `X-Forwarded-For` resolution
+  behind a reverse proxy (baronunread/sproutboat#163).
+- `env.<D1>.backup(name?)` — an online, integrity-checked single-file snapshot
+  of a D1 database via `VACUUM INTO`, on both the embedded and broker transports
+  (baronunread/sproutboat#164).
+- Rate Limiting binding: `ratelimiters: [{ binding, limit, period }]` in
+  `sproutboat.jsonc` gives `env.<NAME>.limit({ key }) -> { success }`, a
+  fixed-window counter on both transports (baronunread/sproutboat#69).
+- `crypto.subtle` subset: `digest` (SHA-256/384/512) and HMAC
+  `importKey` / `sign` / `verify`, backed by reference SHA-2 as inline C so it
+  works on both transports (baronunread/sproutboat#133). No ECDSA or AES yet.
+- `crypto.scryptVerify(password, salt, expected, { N, r, p })` — a verify-only
+  scrypt (RFC 7914) for migrating password hashes made by Node/Bun `scrypt`
+  (baronunread/sproutboat#153). Not a blessed KDF for new credentials.
+- `x-sb-cpu-ms`: per-invocation CPU time, carried on the handler response.
+
+### Fixed
+- `303` (and every other status not in Porffor's table) no longer resets the
+  connection on standalone builds (baronunread/sproutboat#156).
+- Handler `console.log` / `console.error` reach stderr, unbuffered, in
+  standalone builds instead of vanishing (baronunread/sproutboat#165).
+- `sproutboat dev` no longer leaves the previous sprout running across a
+  rebuild, delivers no triggers to a candidate that failed to start, and cleans
+  up every failed setup path on rebuild and on shutdown.
+- The Zig toolchain cache is hardened against a partial or concurrent download.
+
+### Changed
+- Porffor pin bumped alpha-4 → **alpha-5** (`1f4ae4ae`); the same `UWS_COMMIT`,
+  so no uWebSockets re-vendor.
+- Config parsing, the artifact manifest, the binding broker, the wire assets and
+  the whole native-fetch runtime (prelude + transports) now come from published
+  `@sproutboat/*` packages; the CLI keeps thin re-export shims. The Porffor pin
+  and its source patches moved to `@sproutboat/toolchain`.
+- Broker cron / queue / alarm delivery is gated by a local signal, so only a
+  promoted candidate runs timers.
+
+### Performance
+- Embedded transport caches prepared statements per database (FIFO, 32/db)
+  instead of recompiling the SQL on every binding op — the op boundary drops
+  from ~0.6 ms to tens of µs (baronunread/sproutboat#155).
+- The broker's due-queue and due-alarm polls are indexed.
+
+### Docs
+- `docs/standalone.md` documents the single-threaded execution model and the
+  `SO_REUSEPORT` multi-process recipe for scaling past one core
+  (baronunread/sproutboat#154); the embedded transport also sets
+  `PRAGMA busy_timeout` so shared-data-dir writers wait instead of failing.
+  Also: the client-IP behaviour and backing up D1.
+
+## [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.10.0...HEAD
+[0.10.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.8.0...v0.9.0
+[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

@@ -8,6 +8,11 @@ https://sproutboat.com
 The CLI for [Sproutboat](https://github.com/baronunread/sproutboat). Compiles a
 `fetch` handler to a native binary and ships it to any Sproutboat control plane.
 
+## Issues
+
+Tracked centrally in [baronunread/sproutboat](https://github.com/baronunread/sproutboat/issues)
+(label `area:cli`). Please file there.
+
 ## Overview
 
 Wrangler-shaped, MIT licensed. `build` and `deploy` cross-compile your handler
@@ -19,10 +24,23 @@ for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
 
 ## Using
 
+The npm package installs a small Node launcher and the matching native
+platform package, so `npm install -g sproutboat` and `npm exec sproutboat` work
+without Bun on `darwin` and `linux` for `arm64` and `x64`. The self-hosted
+runtime exports remain in the root package for Bun-based platform integrations.
+Nothing is needed on the machine that *runs* a sprout: that gets a static
+binary.
+
+The first build downloads the pinned Porffor source into
+`~/.cache/sproutboat`, verifies its SHA-256, applies Sproutboat's compiler
+patches there, and publishes the cache entry atomically. Installation itself
+does not clone Porffor or invoke Git, Make, or a compiler. Warm-cache builds can
+run offline.
+
 ```sh
-bunx sproutboat init hello
+npm exec sproutboat init hello
 cd hello
-bunx sproutboat dev        # runs it right here, no control plane needed
+npm exec sproutboat dev    # runs it right here, no control plane needed
 ```
 
 Happy with it? Ship it:
@@ -32,10 +50,10 @@ 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 and drop the `npm exec`:
 
 ```sh
-bun add -g sproutboat     # then: sproutboat deploy, sproutboat tail, ...
+npm install -g sproutboat # then: sproutboat deploy, sproutboat tail, ...
 ```
 
 `login` is one-time. It writes a long-lived token to
@@ -63,6 +81,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.
@@ -81,6 +125,7 @@ argument, every env var, kept honest by a drift test.
   "queues": ["JOBS"],
   "analytics_engine_datasets": ["METRICS"],   // bare name only, no id
   "durable_objects": { "COUNTER": "Counter" },
+  "ratelimiters": [{ "binding": "API", "limit": 100, "period": 60 }], // env.API.limit({ key })
   "outbound": ["api.example.com"],
   "triggers": { "crons": ["*/5 * * * *"] },
   "assets": { "directory": "public", "binding": "ASSETS", "run_sprout_first": ["/api/*"] }

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.8.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] [--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] [--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>> | 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,8 +40,14 @@ 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_TOOLCHAIN_CACHE` | Managed Porffor and compiler cache root (default ~/.cache/sproutboat). |
+| `SPROUTBOAT_PORFFOR_DIR` | Contributor override for an existing Porffor source checkout. Required files are validated before use. |
+| `SPROUTBOAT_BUILD_UWS_FROM_SOURCE` | Set to 1 to explicitly allow the contributor-only Git and Make uWebSockets fallback. |
+| `SPROUTBOAT_CLI_VERSION` | CLI version embedded by the release executable build. Not normally set by users. |
 | `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. |
 | `SPROUTBOAT_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
@@ -64,7 +71,7 @@ usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port
 | | |
 | --- | --- |
 | Zig | `0.16.0` (`zig cc -target x86_64-linux-musl`, static) |
-| Provenance stamp | `zig-musl/0.16.0+porffor/a415d19+uws/360c276d` |
+| Provenance stamp | `zig-musl/0.16.0+porffor/1f4ae4a+uws/360c276d` |
 | Artifact schema | `2` |
 | Runtime | `native-fetch` |
 | Capability profile | `http-sync-v0` |

package/bin/sproutboat.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// npm only selects the packaged executable. The CLI itself always runs in Bun.
+const { spawn } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const platform = process.platform === "darwin" ? "darwin" : process.platform === "linux" ? "linux" : null;
+const arch = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "x64" : null;
+if (!platform || !arch) {
+  console.error(`sproutboat: unsupported platform ${process.platform}/${process.arch}`);
+  process.exit(1);
+}
+const packageName = `@sproutboat/cli-${platform}-${arch}`;
+let executable;
+try {
+  executable = require.resolve(`${packageName}/bin/sproutboat`);
+} catch {
+  console.error(`sproutboat: optional package ${packageName} is missing for ${platform}/${arch}`);
+  console.error("Reinstall sproutboat without --omit=optional, or use a direct release download.");
+  process.exit(1);
+}
+const child = spawn(resolve(executable), process.argv.slice(2), { stdio: "inherit" });
+child.once("error", (error) => {
+  console.error(`sproutboat: could not start bundled executable: ${error.message}`);
+  process.exit(1);
+});
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => child.kill(signal));
+}
+child.once("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -19,15 +19,19 @@
     "url": "git+https://github.com/baronunread/sproutboat-cli.git"
   },
   "bin": {
-    "sproutboat": "src/main.ts"
+    "sproutboat": "bin/sproutboat.cjs"
   },
   "files": [
+    "CHANGELOG.md",
+    "SURFACE.md",
     "src",
-    "!src/*.test.ts",
-    "vendor",
-    "SURFACE.md"
+    "bin/sproutboat.cjs",
+    "scripts",
+    "types",
+    "vendor"
   ],
   "type": "module",
+  "types": "./types/sproutboat.d.ts",
   "exports": {
     "./runtime/config": "./src/config.ts",
     "./runtime/source": "./src/source.ts",
@@ -35,13 +39,15 @@
     "./runtime/assets": "./src/assets.ts",
     "./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",
+    "build:cli": "bun scripts/build-cli.ts",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
     "test": "bun test",
@@ -54,8 +60,13 @@
     "kitchen-sink:standalone": "bun examples/kitchen-sink/harness-standalone.ts"
   },
   "dependencies": {
-    "esbuild": "^0.28.2",
-    "porffor": "github:CanadaHonk/porffor#alpha-4"
+    "@sproutboat/artifact": "^0.2.0",
+    "@sproutboat/assets": "^0.2.0",
+    "@sproutboat/config": "^0.3.0",
+    "@sproutboat/runtime": "^0.4.0",
+    "@sproutboat/toolchain": "^0.3.0",
+    "@sproutboat/wire": "^0.4.0",
+    "esbuild": "^0.28.2"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.81.0",
@@ -65,7 +76,13 @@
     "oxlint": "1.81.0",
     "typescript": "7.0.2"
   },
+  "optionalDependencies": {
+    "@sproutboat/cli-darwin-arm64": "0.10.0",
+    "@sproutboat/cli-darwin-x64": "0.10.0",
+    "@sproutboat/cli-linux-arm64": "0.10.0",
+    "@sproutboat/cli-linux-x64": "0.10.0"
+  },
   "engines": {
-    "bun": ">=1.4.0"
+    "node": ">=18"
   }
 }