sproutboat 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sproutboat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# sproutboat
+
+The CLI for [Sproutboat](https://github.com/baronunread/sproutboat) — a
+Wrangler-shaped tool for deploying workers to any Sproutboat control plane.
+MIT licensed.
+
+```sh
+bunx sproutboat login --api-url https://control.example.com
+bunx sproutboat init hello
+cd hello
+bunx sproutboat deploy
+```
+
+Or install it once and drop the `bunx`:
+
+```sh
+bun add -g sproutboat     # then: sproutboat deploy, sproutboat tail, ...
+```
+
+Want it shorter? Alias it yourself: `alias sprout='sproutboat'`.
+
+For CI, skip `login` and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init [name]` | Scaffold `sproutboat.jsonc` + `src/index.js` |
+| `check` | Validate the config and entry point |
+| `build` | Cross-compile the worker artifact |
+| `deploy [--dry-run] [--artifact <dir>]` | Build and upload (`--dry-run` prints the report only) |
+| `login [--api-url <url>] [--token <token>]` | Browser device flow, or store a token |
+| `tail [name]` | Recent logs |
+| `versions list [name]` | Deployed versions |
+| `rollback <id>` | Activate a previous version |
+| `delete --yes` | Delete the project |
+
+Credentials are keyed by API URL in `~/.config/sproutboat/credentials.json`, so
+you can hold logins for several instances at once.
+
+## Config
+
+`sproutboat.jsonc` — the entry point plus Cloudflare-shaped `env.*` bindings:
+
+```jsonc
+{
+  "name": "app",
+  "main": "src/index.js",
+  "compatibility_date": "2026-08-26",
+
+  "vars": { "SITE": "hi" },
+  "secrets": ["API_KEY"],
+  "kv_namespaces": ["CACHE"],
+  "d1_databases": ["DB"],
+  "r2_buckets": ["UPLOADS"],
+  "queues": ["JOBS"],
+  "analytics_engine_datasets": ["METRICS"],
+  "durable_objects": { "COUNTER": "Counter" },
+  "outbound": ["api.example.com"],
+  "triggers": { "crons": ["*/5 * * * *"] },
+  "assets": { "directory": "public", "binding": "ASSETS" }
+}
+```
+
+The handler is one `export default { fetch }`, optionally with `scheduled` /
+`queue` handlers and exported Durable Object classes. See
+[`examples/kitchen-sink/`](examples/kitchen-sink) for one app that uses every
+binding, with an Astro UI and a runnable end-to-end harness.
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.4+
+- `git` and `make` on `PATH` (first build only — compiles uWebSockets once)
+- No Docker. Builds cross-compile to a static `linux-x86_64` binary with Porffor
+  and Zig. Windows: build from WSL.
+
+## Limits (v1)
+
+Binding values are text/JSON and travel one at a time over a loopback frame; an
+upload is capped at 1 MiB by the worker's HTTP server (large-object R2 is
+[#56](https://github.com/baronunread/sproutboat/issues/56)). No WebSockets yet.
+
+---
+
+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.

package/SURFACE.md

@@ -0,0 +1,49 @@
+# sproutboat — surface
+
+> 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.2.0 · runs on Bun (use `bunx`, not `npx`)
+
+## Commands
+
+| Command | Arguments | Summary |
+| --- | --- | --- |
+| `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
+| `check` | `[project-dir]` | Validate the config and entry point without building. |
+| `build` | `[project-dir]` | Cross-compile the native-fetch worker (Porffor + Zig). |
+| `deploy` | `[project-dir] [--dry-run] [--artifact <dir>]` | Build (unless --artifact), print the report, upload. --dry-run stops before upload. |
+| `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
+| `tail` | `[project-dir]` | Print the project's recent request logs. |
+| `versions` | `list [project-dir]` | List the project's deployed versions. |
+| `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
+| `delete` | `--yes [project-dir]` | Delete the project and every version. |
+
+```
+usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] | login [--api-url <url>] [--token <token>] | tail [project-dir] | versions list [project-dir] | rollback <version-id> [project-dir] | delete --yes [project-dir]>
+```
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `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_COMPILE_TIMEOUT_MS` | Porffor compile timeout in ms (default 600000). |
+| `SPROUTBOAT_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
+| `XDG_CONFIG_HOME` | Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset. |
+| `PORFFOR_VERSION` | Override the Porffor identity string recorded in the manifest. |
+| `SB_BROKER_PORT` | Loopback port of the binding broker, read by the compiled worker at runtime (set by the control plane, or by `src/broker.ts` for local runs). |
+| `SB_BROKER_TOKEN` | Per-deployment auth token the worker sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT). |
+| `SB_WORKER_URL` | http://127.0.0.1:<PORT> of the worker; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it. |
+
+## Build toolchain (pinned)
+
+| | |
+| --- | --- |
+| Zig | `0.16.0` (`zig cc -target x86_64-linux-musl`, static) |
+| Provenance stamp | `zig-musl/0.16.0+porffor/a415d19+uws/360c276d` |
+| Artifact schema | `2` |
+| Runtime | `native-fetch` |
+| Capability profile | `http-sync-v0` |

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "sproutboat",
+  "version": "0.2.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",
+    "porffor",
+    "serverless",
+    "edge",
+    "wrangler"
+  ],
+  "bin": {
+    "sproutboat": "src/main.ts"
+  },
+  "files": [
+    "src",
+    "!src/*.test.ts",
+    "SURFACE.md"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "example:kitchen-sink": "bun examples/kitchen-sink/harness.ts",
+    "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"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2",
+    "porffor": "github:CanadaHonk/porffor#alpha-4"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "5.9.2"
+  }
+}

package/src/assets.ts

@@ -0,0 +1,77 @@
+/**
+ * Static-asset manifest. `sproutboat build` copies the project's `assets`
+ * directory next to the artifact and writes `assets.json` (this manifest); the
+ * edge serves matching files directly (assets-first, like Cloudflare), and the
+ * broker's `assets.get` op backs `env.<ASSETS>.fetch(request)` for the paths
+ * the worker chooses to serve itself.
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+
+export type AssetEntry = { hash: string; size: number; type: string };
+/** `/absolute/posix/path` -> entry. Serialised into `assets.json`. */
+export type AssetFiles = { [path: string]: AssetEntry };
+export type AssetManifest = {
+  /** Fallback for requests that match no file, applied by the broker. */
+  notFound: "none" | "single-page-application" | "404-page";
+  /** `true` = every path to the sprout first; string[] = selective (leading `!` negates). */
+  runSproutFirst: boolean | string[];
+  files: AssetFiles;
+};
+
+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"],
+  ["webmanifest", "application/manifest+json"],
+]);
+
+export function contentType(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return (dot >= 0 ? TYPES.get(name.slice(dot + 1).toLowerCase()) : undefined) ?? "application/octet-stream";
+}
+
+/** Walk `dir` recursively, returning `{ "/path": {hash,size,type} }`. */
+export function walkAssets(dir: string) {
+  const out: AssetFiles = {};
+  const recurse = (abs: string, rel: string): void => {
+    for (const ent of readdirSync(abs, { withFileTypes: true })) {
+      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.isFile()) continue;
+      const body = readFileSync(childAbs);
+      out[`/${childRel}`] = { hash: createHash("sha256").update(body).digest("hex"), size: body.byteLength, type: contentType(ent.name) };
+    }
+  };
+  recurse(dir, "");
+  return out;
+}
+
+/** Does `pathname` hit the sprout before assets, given a `runSproutFirst` spec? */
+export function isSproutFirst(spec: boolean | string[], pathname: string): boolean {
+  if (!Array.isArray(spec)) return spec;
+  let matched = false;
+  for (const raw of spec) {
+    const negate = raw.startsWith("!");
+    const pattern = negate ? raw.slice(1) : raw;
+    if (globMatch(pattern, pathname)) matched = !negate;
+  }
+  return matched;
+}
+
+/** `*` matches within a segment, `**` across segments. Anchored both ends. */
+function globMatch(pattern: string, path: string): boolean {
+  const rx = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, " ")
+    .replace(/\*/g, "[^/]*")
+    .replace(/ /g, ".*");
+  return new RegExp(`^${rx}$`).test(path);
+}