sproutboat 0.5.0 → 0.6.0

package/README.md

@@ -1,11 +1,23 @@
-# sproutboat
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
+  <img src="docs/logo-light.svg" alt="sproutboat" width="220" height="32">
+</picture>
 
-The CLI for [Sproutboat](https://github.com/baronunread/sproutboat). It is a
-Wrangler-shaped tool that compiles a `fetch` handler to a native binary and
-ships it to any Sproutboat control plane. MIT licensed.
+https://sproutboat.com
 
-Full reference: [sproutboat.com/docs](https://sproutboat.com/docs)
-(plain text for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
+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.
+
+## Overview
+
+Wrangler-shaped, MIT licensed. `build` and `deploy` cross-compile your handler
+to a static `linux-x86_64` binary with [Porffor](https://porffor.dev) and Zig —
+no Docker, no root, nothing to run as a daemon.
+
+Full reference: [sproutboat.com/docs](https://sproutboat.com/docs) (plain text
+for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
+
+## Using
 
 ```sh
 bunx sproutboat init hello
@@ -26,45 +38,30 @@ Or install it once and drop the `bunx`:
 bun add -g sproutboat     # then: sproutboat deploy, sproutboat tail, ...
 ```
 
-Want it shorter? Alias it yourself: `alias sprout='sproutboat'`.
-
-The `login` browser step is one-time. It writes a long-lived token to
+`login` is one-time. It writes a long-lived token to
 `~/.config/sproutboat/credentials.json`, keyed by API URL, so you can hold
-logins for several instances at once. For CI or an agent, skip `login`
-entirely and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN` (copy the token out
-of that file).
+logins for several instances at once. For CI or an agent, skip it and set
+`SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN`.
 
 ## Commands
 
+The everyday loop:
+
 | Command | What it does |
 | --- | --- |
 | `init [name]` | Scaffold `sproutboat.jsonc` + `src/index.js` |
-| `check` | Validate the config and entry point |
-| `dev [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save |
-| `build [--target host]` | Cross-compile the sprout binary (Porffor + Zig); `--target host` builds for this machine instead, for `dev` — not deployable |
-| `deploy [--dry-run] [--no-wait] [--no-provision] [--artifact <dir>]` | Build, auto-provision id-less storage bindings, upload, wait until the URL serves |
-| `login [--api-url <url>] [--token <token>]` | Browser device flow, or store a token directly |
-| `tail [name] [--sprout]` | Recent request logs; `--sprout` streams the running sprout + broker output |
-| `versions <list \| view <id>>` | Deployed versions, or one version's artifact and bindings |
-| `rollback <id>` | Activate a previous version |
-| `logout [--api-url <url>]` | Forget the stored credential |
-| `whoami` | Active endpoint and the account the token belongs to |
-| `kv <list \| create \| info \| rename \| delete>` | KV namespaces |
-| `d1 <list \| create \| info \| rename \| delete>` | D1 databases |
-| `r2 <list \| create \| info \| rename \| delete>` | R2 buckets |
-| `queues <list \| create \| info \| rename \| delete>` | Queues |
-| `secrets <list \| put <NAME> [--value <v>] \| delete <NAME>>` | Encrypted project secrets, read as `env.NAME` |
-| `domains <list \| add <host> \| verify <host> \| delete <host>>` | Attach your own hostname (TXT + A, apex allowed) |
-| `delete --yes` | Delete the project, every version, and its route |
-
-Each storage product is its own command with the same five verbs. Wrangler nests
-two of its four (`kv namespace create`, `r2 bucket create`) and leaves the other
-two flat; the nesting separates a container from its contents, which the verb
-already does, so ours are uniform. Contents get their own noun when they arrive
-(`kv key get`, `r2 object put`).
+| `dev [--port <n>]` | Run it here against a real broker, rebuilding on save |
+| `deploy` | Build, provision bindings, upload, wait until the URL serves |
+| `tail [--sprout]` | Recent request logs, or the running sprout's output |
+| `rollback <id>` | Re-activate a previous version |
+
+Then `check`, `build`, `versions`, `delete`, `login` / `logout` / `whoami`, and
+one command per storage product — `kv`, `d1`, `r2`, `queues`, `secrets`,
+`domains` — each with the same five verbs.
 
 Run `sproutboat` with no arguments for the grouped list.
-[`SURFACE.md`](SURFACE.md) is the generated inventory of every command and env var.
+[`SURFACE.md`](SURFACE.md) is the generated inventory: every command, every
+argument, every env var, kept honest by a drift test.
 
 ## Config
 
@@ -91,55 +88,47 @@ Run `sproutboat` with no arguments for the grouped list.
 ```
 
 A bare `"CACHE"` binding is auto-provisioned on `deploy`: the CLI creates an
-account-level resource, writes its id back into `sproutboat.jsonc`, and the
-store then survives redeploys. Pass `--no-provision` to keep it a throwaway
-per-deploy store instead, or `sproutboat kv create <name>` (or `d1`/`r2`/`queues`) to make one up front
-and share its id across projects.
-
-The handler is `export default { fetch(request) }`; it may import from other
-files in the project and from its own `node_modules`, and optionally export
-`scheduled(event)` / `queue(batch)` handlers and Durable Object classes.
-`env` is a global (not a parameter), and every binding call is synchronous.
-See [`examples/kitchen-sink/`](examples/kitchen-sink) for one app that uses
-every binding.
+account-level resource and writes its id back into `sproutboat.jsonc`, so the
+store survives redeploys. `--no-provision` keeps it a throwaway per-deploy
+store instead.
+
+The handler is `export default { fetch(request) }`. It may import from other
+files in the project and from its own `node_modules`, and may also export
+`scheduled(event)` / `queue(batch)` handlers and Durable Object classes. `env`
+is a global, not a parameter, and every binding call is synchronous.
+[`examples/kitchen-sink/`](examples/kitchen-sink) uses every binding.
 
 `sproutboat dev` runs against a real local broker, so bindings behave like
-production without a deploy — except `secrets`, which live only in the
-control plane. Give it a value with a `.dev.vars` file next to
-`sproutboat.jsonc` (`API_KEY=whatever`, one per line, gitignore it):
-`env.API_KEY` then resolves to that value under `dev` only.
+production without a deploy — except `secrets`, which live only in the control
+plane. Put values in a `.dev.vars` file next to `sproutboat.jsonc`
+(`API_KEY=whatever`, one per line, gitignored) and `env.API_KEY` resolves under
+`dev` only.
 
 ## Requirements
 
-- [Bun](https://bun.sh) 1.4+
-
-`build` / `deploy` cross-compile the handler to a static `linux-x86_64` binary
-with Porffor and Zig (the CLI fetches Zig automatically on first use). The
-package ships a prebuilt uWebSockets and compiles nothing else from source. No
-Docker, no root. On Windows, build from WSL.
-
-If that prebuilt is unusable (a `porffor` pin bump before the archive is
-refreshed), the first build falls back to compiling uWebSockets locally, which
-needs `git` and `make` on `PATH`. `SPROUTBOAT_UWS_TARBALL=<archive>` overrides
-the shipped one.
+[Bun](https://bun.sh) 1.4+. The CLI fetches Zig automatically on first use and
+ships a prebuilt uWebSockets, so it compiles nothing else from source. On
+Windows, build from WSL.
 
 ## Limits
 
 Capability profile `http-sync-v0`: one synchronous `fetch` handler, optional
 `scheduled` / `queue` handlers, no streaming, no WebSockets. Binding values are
-text/JSON and travel one at a time over the loopback frame (32 MiB cap);
-large-object R2 is [#56](https://github.com/baronunread/sproutboat/issues/56).
-The sprout upload caps at 16 MiB, assets at 64 MiB / 4096 files. The entry
-point is bundled before it compiles, so relative imports and npm dependencies
-from the project's own `node_modules` work; CommonJS `require`, dynamic
-`import()`, and any `process`/`Bun`/`Deno`/`node:*` reached even through a
-dependency do not. `new Proxy(...)` compiles but its traps are silently
-ignored by Porffor alpha, so it's rejected too. A parsed `Date` with a numeric
-timezone offset (`+02:00`) currently comes out wrong; plain ISO-8601 UTC
-strings are fine. `sproutboat check` catches most of this before a build.
-Full list at [sproutboat.com/docs](https://sproutboat.com/docs).
-
----
-
-Contributors: [`MIGRATION.md`](MIGRATION.md) maps this repo back to the monorepo.
-[`SURFACE.md`](SURFACE.md) is a generated inventory of every command and env var.
+text/JSON, one at a time over a 32 MiB loopback frame. Sprout uploads cap at
+16 MiB, assets at 64 MiB / 4096 files.
+
+Porffor is pre-1.0, so some JavaScript does not survive the compile — CommonJS
+`require`, dynamic `import()`, anything reaching `process`/`Bun`/`Deno`/`node:*`,
+and `new Proxy(...)` (it compiles, then silently ignores every trap).
+`sproutboat check` catches most of it before a build. The full list, and the
+current sharp edges, are at [sproutboat.com/docs](https://sproutboat.com/docs).
+
+## Bugs
+
+File issues at
+[baronunread/sproutboat/issues](https://github.com/baronunread/sproutboat/issues).
+
+## Contributing
+
+PRs welcome. [`MIGRATION.md`](MIGRATION.md) maps this repo back to the
+monorepo it was extracted from.

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.5.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.6.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 

package/package.json

@@ -1,27 +1,33 @@
 {
   "name": "sproutboat",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
-  "license": "MIT",
-  "type": "module",
-  "homepage": "https://github.com/baronunread/sproutboat-cli",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/baronunread/sproutboat-cli.git"
-  },
-  "bugs": "https://github.com/baronunread/sproutboat-cli/issues",
   "keywords": [
-    "sproutboat",
     "cli",
     "deploy",
+    "edge",
     "porffor",
     "serverless",
-    "edge",
+    "sproutboat",
     "wrangler"
   ],
+  "homepage": "https://github.com/baronunread/sproutboat-cli",
+  "bugs": "https://github.com/baronunread/sproutboat-cli/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baronunread/sproutboat-cli.git"
+  },
   "bin": {
     "sproutboat": "src/main.ts"
   },
+  "files": [
+    "src",
+    "!src/*.test.ts",
+    "vendor",
+    "SURFACE.md"
+  ],
+  "type": "module",
   "exports": {
     "./runtime/config": "./src/config.ts",
     "./runtime/source": "./src/source.ts",
@@ -32,18 +38,12 @@
     "./runtime/prelude": "./src/native-fetch-prelude.js",
     "./package.json": "./package.json"
   },
-  "files": [
-    "src",
-    "!src/*.test.ts",
-    "vendor",
-    "SURFACE.md"
-  ],
-  "engines": {
-    "bun": ">=1.4.0"
-  },
   "scripts": {
+    "prepare": "lefthook install || true",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
+    "fmt": "oxfmt .",
+    "fmt:check": "oxfmt --check .",
     "test": "bun test",
     "example:kitchen-sink": "bun examples/kitchen-sink/harness.ts",
     "surface": "UPDATE_SURFACE=1 bun test src/surface.test.ts",
@@ -58,7 +58,12 @@
   "devDependencies": {
     "@oxlint/plugins": "1.81.0",
     "@types/bun": "1.4.0",
+    "lefthook": "2.1.12",
+    "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
     "typescript": "5.9.2"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
   }
 }

package/src/assets.ts

@@ -21,13 +21,26 @@ export type AssetManifest = {
 };
 
 const TYPES = new Map<string, string>([
-  ["html", "text/html; charset=utf-8"], ["css", "text/css; charset=utf-8"],
-  ["js", "text/javascript; charset=utf-8"], ["mjs", "text/javascript; charset=utf-8"],
-  ["json", "application/json; charset=utf-8"], ["map", "application/json; charset=utf-8"],
-  ["txt", "text/plain; charset=utf-8"], ["xml", "application/xml; charset=utf-8"],
-  ["svg", "image/svg+xml"], ["png", "image/png"], ["jpg", "image/jpeg"], ["jpeg", "image/jpeg"],
-  ["gif", "image/gif"], ["webp", "image/webp"], ["avif", "image/avif"], ["ico", "image/x-icon"],
-  ["woff2", "font/woff2"], ["woff", "font/woff"], ["ttf", "font/ttf"], ["wasm", "application/wasm"],
+  ["html", "text/html; charset=utf-8"],
+  ["css", "text/css; charset=utf-8"],
+  ["js", "text/javascript; charset=utf-8"],
+  ["mjs", "text/javascript; charset=utf-8"],
+  ["json", "application/json; charset=utf-8"],
+  ["map", "application/json; charset=utf-8"],
+  ["txt", "text/plain; charset=utf-8"],
+  ["xml", "application/xml; charset=utf-8"],
+  ["svg", "image/svg+xml"],
+  ["png", "image/png"],
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["gif", "image/gif"],
+  ["webp", "image/webp"],
+  ["avif", "image/avif"],
+  ["ico", "image/x-icon"],
+  ["woff2", "font/woff2"],
+  ["woff", "font/woff"],
+  ["ttf", "font/ttf"],
+  ["wasm", "application/wasm"],
   ["webmanifest", "application/manifest+json"],
 ]);
 
@@ -68,10 +81,17 @@ export function walkAssets(dir: string) {
       if (ent.name.startsWith(".")) continue;
       const childAbs = join(abs, ent.name);
       const childRel = posix.join(rel, ent.name);
-      if (ent.isDirectory()) { recurse(childAbs, childRel); continue; }
+      if (ent.isDirectory()) {
+        recurse(childAbs, childRel);
+        continue;
+      }
       if (!ent.isFile()) continue;
       const body = readFileSync(childAbs);
-      out[`/${childRel}`] = { hash: createHash("sha256").update(body).digest("hex"), size: body.byteLength, type: contentType(ent.name) };
+      out[`/${childRel}`] = {
+        hash: createHash("sha256").update(body).digest("hex"),
+        size: body.byteLength,
+        type: contentType(ent.name),
+      };
     }
   };
   recurse(dir, "");