sproutboat 0.8.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.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,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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.8.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",

package/src/broker.ts

@@ -196,14 +196,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       assetManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as AssetManifest;
     }
   }
-  const readAsset = (path: string): { type: string; hash: string; body: string } | null => {
+  const readAsset = (path: string): { type: string; hash: string; body: Uint8Array } | null => {
     if (!assetsDir || !assetManifest) return null;
     const entry = assetManifest.files[path];
     if (!entry) return null;
     // path keys are `/`-prefixed and `..`-free (walkAssets), but re-check.
     const abs = normalize(join(assetsDir, path));
     if (!abs.startsWith(assetsDir)) return null;
-    return { type: entry.type, hash: entry.hash, body: readFileSync(abs, "utf8") };
+    return { type: entry.type, hash: entry.hash, body: readFileSync(abs) };
   };
   const token = opts.token ?? "";
   /** #63 §3 — replies to recent non-idempotent requests, keyed by op and id. */
@@ -716,16 +716,38 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const reqPath = str(msg.path) || "/";
         const key = resolveAssetKey(reqPath, (k) => !!assetManifest?.files[k]);
         const hit = key ? readAsset(key) : null;
-        if (hit) return { ok: true, found: true, status: 200, type: hit.type, hash: hit.hash, body: hit.body };
+        if (hit)
+          return {
+            ok: true,
+            found: true,
+            status: 200,
+            type: hit.type,
+            hash: hit.hash,
+            body: new TextDecoder().decode(hit.body),
+          };
         const nfh = assetManifest?.notFound ?? "none";
         if (nfh === "single-page-application") {
           const shell = readAsset("/index.html");
           if (shell)
-            return { ok: true, found: true, status: 200, type: shell.type, hash: shell.hash, body: shell.body };
+            return {
+              ok: true,
+              found: true,
+              status: 200,
+              type: shell.type,
+              hash: shell.hash,
+              body: new TextDecoder().decode(shell.body),
+            };
         }
         if (nfh === "404-page") {
           const page = readAsset("/404.html");
-          if (page) return { ok: true, found: false, status: 404, type: page.type, body: page.body };
+          if (page)
+            return {
+              ok: true,
+              found: false,
+              status: 404,
+              type: page.type,
+              body: new TextDecoder().decode(page.body),
+            };
         }
         return { ok: true, found: false, status: 404, body: "Not Found" };
       }
@@ -775,6 +797,27 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       return { reply: { ok: true, found: true, object: r2Row(row) }, bytes: r2Bytes(row.body) };
     }
 
+    if (msg.op === "assets.get") {
+      if (!bindings.assets) throw new Error("assets not bound");
+      const reqPath = str(msg.path) || "/";
+      const key = resolveAssetKey(reqPath, (candidate) => !!assetManifest?.files[candidate]);
+      let hit = key ? readAsset(key) : null;
+      let found = Boolean(hit);
+      let status = hit ? 200 : 404;
+      if (!hit && assetManifest?.notFound === "single-page-application") {
+        hit = readAsset("/index.html");
+        found = Boolean(hit);
+        status = hit ? 200 : 404;
+      } else if (!hit && assetManifest?.notFound === "404-page") {
+        hit = readAsset("/404.html");
+      }
+      if (!hit) return { reply: { ok: true, found: false, status: 404 }, bytes: new TextEncoder().encode("Not Found") };
+      return {
+        reply: { ok: true, found, status, type: hit.type, hash: hit.hash },
+        bytes: hit.body,
+      };
+    }
+
     return { reply: await dispatchOnce(msg) };
   }
 

package/src/build.ts

@@ -35,6 +35,13 @@ export type BuildInput = {
   /** #15 — `embedded` compiles SQLite into the sprout instead of a broker
    *  transport. Defaults to the broker transport. */
   transport?: Transport;
+  /**
+   * `dev` compiles at -O0, which is roughly three times faster and produces a
+   * bigger binary. Only for artifacts that cannot be deployed: `deploy` refuses
+   * a host build already, and this defaults to `release` so a caller has to ask
+   * for the fast path deliberately.
+   */
+  optimize?: "dev" | "release";
 };
 
 export type BuildOutput = {
@@ -152,6 +159,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     assets: bakedAssets,
     extraLink,
     extraCflags,
+    optimize: input.optimize,
   });
 
   const sprout = await readFile(sproutPath);

package/src/compile.ts

@@ -12,7 +12,7 @@
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
-import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
+import { ensureUWebSockets, ensureUWebSocketsHost, porfforRoot, UwsUnavailableError } from "./toolchain";
 import {
   EMPTY_BINDINGS,
   preludePath,
@@ -54,6 +54,16 @@ export type CompileInput = {
   extraLink?: string[];
   /** #15 — flags for the compile step, so inline C can include BearSSL's header. */
   extraCflags?: string[];
+  /**
+   * How hard the C compiler works on the generated code.
+   *
+   * Porffor defaults to `-O3` (compiler/index.js reads `-O` from its own argv),
+   * which costs most of the build: `examples/hello` is 8.4s at -O3 against 2.9s
+   * at -O0 on an M-series host. `dev` pays that on every edit for a binary that
+   * never leaves the machine, so it compiles at -O0 and takes a ~55% larger
+   * file. Anything that could be deployed stays at -O3.
+   */
+  optimize?: "dev" | "release";
   /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
   zigBin?: string;
   /**
@@ -88,15 +98,42 @@ function compileEnv(path: string, extraLink?: string[], extraCflags?: string[])
   return { ...process.env, PATH: path, SB_EXTRA_LINK: link, SB_EXTRA_CFLAGS: cflags };
 }
 
+/**
+ * The argument list handed to Porffor, minus the launcher.
+ *
+ * Exported for the test: the one thing worth pinning is that `-O0` reaches only
+ * a build that cannot be deployed. `-s` strips at link, because the unstripped
+ * static-musl binary is ~90% DWARF that nothing needs at runtime (12 MB down to
+ * ~1.3 MB for the kitchen-sink). `--musl` is what makes it a cross-compile; a
+ * host build omits it and Porffor targets the machine it runs on.
+ */
+export function porfforArgs(
+  generatedPath: string,
+  outPath: string,
+  target: CompileInput["target"],
+  optimize: CompileInput["optimize"],
+): string[] {
+  const args = ["native", generatedPath, "-o", outPath];
+  if (target !== "host") args.push("--musl");
+  args.push("-s");
+  // Porffor reads -O from its own argv and defaults to -O3. -O0 is roughly
+  // three times faster to compile, so dev takes it and everything else does
+  // not: a deployable artifact is never built with it.
+  if (optimize === "dev" && target === "host") args.push("-O0");
+  return args;
+}
+
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
 export async function compileSprout(input: CompileInput): Promise<void> {
   await ensurePorfforPatched();
 
   // Seed the Porffor uWebSockets cache from the prebuilt archive in `vendor/` so
-  // the first build needs no `git` / `make`. Fall back to Porffor's own git+make
-  // path if the archive is missing or fails its checksum.
+  // the first build needs no `git` / `make`. The two targets keep separate
+  // cache trees and separate uSockets.a, so seed whichever this build wants.
+  // Fall back to Porffor's own git+make path if the archive is unusable.
   try {
-    await ensureUWebSockets();
+    if (input.target === "host") await ensureUWebSocketsHost();
+    else await ensureUWebSockets();
   } catch (error) {
     if (!(error instanceof UwsUnavailableError)) throw error;
     const haveGit = Bun.which("git");
@@ -149,14 +186,8 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   const zigDir = input.zigBin ? `${dirname(input.zigBin)}:` : "";
   const path = `${zigDir}${binDir}:${process.env.PATH ?? ""}`;
 
-  // `-s`: strip at link. The unstripped static-musl binary is ~90% DWARF that
-  // nothing needs at runtime (12 MB -> ~1.3 MB for the kitchen-sink). Porffor
-  // forwards `-s` straight to the `zig cc` link step.
-  // `--musl` is what makes it a cross-compile; a host build simply omits it and
-  // Porffor targets the machine it is running on.
-  const crossFlags = input.target === "host" ? [] : ["--musl"];
   const child = Bun.spawn(
-    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, ...crossFlags, "-s"],
+    [process.execPath, launcher, ...porfforArgs(generatedPath, input.outPath, input.target, input.optimize)],
     {
       cwd: outDir,
       stdout: "pipe",

package/src/dev.ts

@@ -85,6 +85,8 @@ async function start(input: DevInput, source: string): Promise<Running> {
     sourcePath: input.sourcePath,
     source,
     target: "host",
+    // Never deployable, rebuilt on every edit: buy the iteration loop.
+    optimize: "dev",
   });
   const artifactDir = artifact.artifactDir;
   const sproutPath = resolve(artifactDir, "sprout");