sproutboat 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -10,6 +10,38 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.55.0] - 2026-11-13
+
+### Added
+
+- **`sproutboat init --template <name>` writes a starter, with the shape of `npm create cloudflare`.** Four starters, each standard Workers TypeScript that runs unchanged on workerd, with a README, tests (Node's own test runner, `npm test`), a `tsconfig.json` and a current `worker-configuration.d.ts`: `realtime-room` (a chat room on a Durable Object with hibernating WebSockets: `acceptWebSocket`, tags, `serializeAttachment`, presence, history), `api-d1` (a JSON API on D1 with a migration, validation and keyset pagination), `site-api` (static assets plus `/api/*` routes and KV in one Worker) and `jobs` (a cron trigger that enqueues, a queue consumer with retries and idempotence, KV for state). `--list-templates` prints them. In a terminal `init` asks for the template, the directory, whether to install dependencies and whether to use git (both default to yes); `-y` (`--yes`, `--accept-defaults`) takes every default, `--install` / `--no-install` and `--git` / `--no-git` decide the two steps, and without a terminal nothing runs that a flag did not ask for. `--git` makes a first commit and does nothing inside an existing repository. `init` without `--template` is the hello starter it always was. The starters are embedded in the CLI as text (`src/templates-embedded.ts`, about 90 KiB, rewritten by `bun run templates:embed`), so the compiled executable needs no network or files beside it.
+- **`sproutboat dev --ip <address>`.** `dev` listens on 127.0.0.1 as before; `--ip 0.0.0.0` makes it reachable from other machines, as `wrangler dev --ip` does.
+- **A project with `assets` and no `main` is a Worker with only static assets, as in Wrangler.** `check`, `dev`, `build` and `deploy` write a small entry into `.sproutboat/assets-only.js` that answers any request no file matched with `env.<binding>.fetch(request)`, so `not_found_handling` (the single-page app shell, the nearest 404 page, or a plain 404) applies as it does on Cloudflare. The assets binding is `assets.binding`, or `ASSETS` when the config names none. Nothing else in the config changes: a project with a `main` is untouched, and one with neither still gets `main must be a relative entry point under src/`.
+- **`domains list` works against a Cloud.** It prints the app's routes from its record, marked `built-in` (under `sproutboat.app`) or `custom`. `domains add`, `verify` and `delete` on a Cloud say that custom domains are added by an operator for now and that deploys keep them, instead of calling Community's `/api/projects/<name>/domains`, which a Cloud does not have. `domains` takes `--account <team>`.
+
+### Changed
+
+- **`examples/` holds only what a person reads.** The conformance, stress, runtime-comparison, workers-verbatim and workers-contract fixtures, the Cloudflare pattern ports (`cf-*`), `request`, `upload` and the harness library moved to `test/fixtures/`; `kitchen-sink` and `quote-service`, which are deployed on Sproutboat Cloud and check every generation swap, moved to `dogfood/`. Their deployed names and the `bun run kitchen-sink` scripts are unchanged.
+
+- **`sproutboat types` writes `worker-configuration.d.ts`, like `wrangler types`.** The file declares `interface Env` (and `Cloudflare.Env`, which `import { env } from "cloudflare:workers"` reads) with a type per binding, so a handler is typed as `export default { ... } satisfies ExportedHandler<Env>` and `env.KV`, `env.DB` and the rest autocomplete and are checked. Vars are literal types (`--strict-vars=false` makes them `string`); a Durable Object binding is typed with its class when the entry is TypeScript, so `await env.COUNTER.getByName("a").increment()` is checked. The command takes Wrangler's positional (the file to write), `--env-interface`, `--strict-vars`, `--include-runtime`, `--include-env` and `--check`, which exits 1 when the file is missing or out of date by the hash in its header. `--include-runtime` references the runtime types the CLI ships instead of copying them in, and there is no `--include-main-module`. The ambient types gain the Workers shapes the runtime already had: `ExportedHandler`, `ScheduledController`, `DurableObjectNamespaceAsync` with RPC stubs and `getByName`, `DurableObjectStorageAsync` with `sql`, `FetcherAsync`, `R2ObjectBodyAsync.writeHttpMetadata`, and a `cloudflare:workers` module (`DurableObject`, `WorkerEntrypoint`, `RpcTarget`, `env`). A project at or after compatibility date 2026-09-28 gets no global `env`; earlier ones still do. `dev` and `deploy` refresh the default file when a plain `sproutboat types` wrote it and the config has moved on, and leave one made with other flags alone.
+
+- **`deploy` to a Cloud sends every binding.** KV, D1, R2, queues, Analytics Engine, Durable Objects, rate limiters, the secret names, the assets binding and `triggers.crons` now go to the Cloud in the app record, in a build deploy and a module deploy alike, so `examples/kitchen-sink` runs there with all its bindings. The warning that they were "not sent to the Cloud by the CLI yet" is gone. Each app's Cloud storage is private to it, so the record's resource id is the binding name in lowercase (`DB` is `db`; a queue's is its queue name), and `d1 execute --remote` and `r2 object` address the binding name as before. Every queue is also a queue consumer (`max_batch_size`, `max_batch_timeout` in milliseconds, `max_retries`, `dead_letter_queue`, with Cloudflare's defaults). An account-level `id` in a binding is ignored with a warning. Before anything is uploaded the deploy refuses more than 16 crons, 16 queue consumers or 64 bindings (service bindings included), a cron or resource name the Cloud would refuse, and a `durable_objects` class the entry module does not export. `--dry-run` prints every binding, consumer and cron. A queue's `retry_delay` rides in the binding's config; the record has no field for it yet.
+- **`sproutboat dev` relays WebSockets.** The stable port now forwards an upgrade to the sprout and passes frames both ways, so a browser can use a WebSocket or a Durable Object chat under `dev`. Before, the upgrade went through a plain `fetch` and the client got a protocol error. Stopping `dev` closes open sockets instead of waiting for them.
+- **`examples/kitchen-sink` is a dashboard.** Every tile calls its real binding: a KV counter, a D1 guestbook that shows the SQL it ran, R2 upload and list, a Durable Object chat over WebSocket (hibernation API), a queue and cron feed read from D1, a service binding to `quote-service`, and secret names. Latency is measured in the worker with `performance.now()` and returned in `Server-Timing`; sizes are measured at build time. The Astro UI is gone; `sproutboat.standalone.jsonc` builds the same app as a standalone binary.
+
+- **Every example is a standard Cloudflare Worker, and CI says so.** `examples/*` are rewritten as TypeScript in the Workers style: `export default { async fetch(request, env, ctx) } satisfies ExportedHandler<Env>`, `scheduled(controller, env, ctx)`, `queue(batch, env, ctx)`, Durable Objects that extend `DurableObject` and are called over RPC (`env.COUNTERS.getByName(name).increment()`), a `WorkerEntrypoint` with an RPC method, every binding call awaited, `await request.json()`, `Response.json()`, and a schema created once instead of on every request. All are at compatibility date 2026-11-18, and each has a README (what it shows, run, deploy, curl lines) and a generated `worker-configuration.d.ts`. `bun run examples:workerd` translates each `sproutboat.jsonc` into a `wrangler.jsonc`, typechecks the entry against the runtime types `wrangler types` generates (no Sproutboat declaration in the program), runs it under workerd with `wrangler dev` and sends the same requests `bun run examples` sends the standalone binary; `bun test` runs it (so the CI check job does), and `bun run examples:types` verifies every `worker-configuration.d.ts` is current and typechecks, also under `bun test`. What is skipped is printed with its reason: `analytics` (`query()` is a Sproutboat extension) and `outbound-fetch` (the private-address refusal is Sproutboat policy) send only the requests Workers can answer. examples/README.md states the two rules the examples follow: standard Workers style, and no test-only code in examples.
+
+- **`examples/conformance`: the binding conformance suite has its own fixture.** The routes and vectors that existed only for tests (login and notes, the crypto vectors with `crypto.scryptVerify`, the async echo, the egress refusals, `/admin/stats`, the direct-transfer tickets, the service-binding probe) moved out of `examples/kitchen-sink/src/index.js` into a worker of their own, with its own checks on both backends (`bun run conformance`, `bun run conformance:standalone`: 34 and 37 checks). `kitchen-sink` is the demo only: the dashboard's API, its limits, the chat room and its cron jobs (77 and 75 checks), no `binary-fixture.bin` in the deployed site, no `ViewCounter` or `QUOTE_URL`. Its routes under `/api`, `/healthz` and the chat (`/api/chat`, the `?probe=1` probe, the 96 KiB history cap) are unchanged. `bun run kitchen-sink` and `kitchen-sink:standalone` still exist and run the demo's checks and then the conformance fixture's. Both harness pairs now share `examples/lib/backends.ts`.
+- **`kitchen-sink` is Workers-style and runs on workerd.** Its entry points take `env` as an argument (`fetch(request, env)`, `scheduled(controller, env)`, `queue(batch, env)`), `ChatRoom` extends `DurableObject`, and its tables are created once per process instead of on every request. Running it under workerd found two bugs that Sproutboat's runtime had hidden, both fixed: `env.SESSIONS.list("")` (the pre-2026-10-25 argument, which throws on Workers) and a chat broadcast that sent to a socket already closing. It has a `worker-configuration.d.ts` and JSDoc types for `env`; the entry stays JavaScript because the Code panels excerpt it and the harness compiles it as it is.
+
+### Fixed
+
+- **`deploy` to a Cloud no longer unroutes a custom domain.** A deploy used to write the app's whole `hosts` list as just `<project>.<team>.sproutboat.app`, so a domain an operator had routed (`sbcloud route add risulta.dev`, or `--host` in `tools/sbcloud-deploy`) was dropped by the next `sproutboat deploy`, silently. It now sends `hosts_patch: { add: [that name] }`, which the Cloud merges into the live list when the record is written (for a deploy from source, when the build is applied, so a domain added while it builds is kept too). Routes the deploy did not add stay, as `wrangler deploy` leaves dashboard routes alone when the config declares none. Against a Cloud that predates `hosts_patch` the CLI merges the live routes itself and says so. Needs no Cloud change to work, and is atomic once the Cloud has it.
+
+### Changed
+
+- **`sproutboat types` writes `worker-configuration.d.ts`, not `sproutboat-env.d.ts`, and its positional is the output file.** A positional that is an existing directory is still read as the project directory. The old file is removed when it is still exactly as the old command generated it; commit the new one and add it to your tsconfig `include`. The old file declared `env` as a global for every date; the new one declares `Env`, and `env` only for dates before 2026-09-28, where it is the only way to reach the bindings.
+
 ## [0.54.0] - 2026-11-11
 
 Built on `@sproutboat/runtime` 0.44.0, `@sproutboat/wire` 0.22.4 and `@sproutboat/toolchain` 0.24.2 (runtime and wire from 0.43.0 and 0.22.3). Runtime 0.44.0 adds service bindings between Cloud apps from compatibility date 2026-11-18; every app is recompiled on its next build, since the runtime prelude changed. The Cloud-only features below need a Cloud control plane with sproutboat-cloud#42, #45 and #49; remote D1 and R2 also need a host whose agent serves the data routes (sproutd#93).

package/README.md

@@ -1,6 +1,6 @@
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
-  <img src="docs/logo-light.svg" alt="sproutboat" width="220" height="32">
+  <img src="docs/logo-light.svg" alt="sproutboat" width="220" height="34">
 </picture>
 
 https://sproutboat.com
@@ -54,6 +54,20 @@ npm install
 npm run dev                # runs it right here, no control plane needed
 ```
 
+Want a starting point with more in it? `init` has four starters, each standard Workers TypeScript with a README,
+tests and a current `worker-configuration.d.ts`, and each one runs unchanged on Cloudflare:
+
+```sh
+npx sproutboat init --list-templates
+npx sproutboat init chat --template realtime-room   # Durable Object, hibernating WebSockets, presence
+npx sproutboat init tasks --template api-d1         # JSON API on D1 with migrations and validation
+npx sproutboat init site  --template site-api       # static site and its API routes in one Worker
+npx sproutboat init nightly --template jobs         # cron enqueues, a queue consumer works, KV holds state
+```
+
+In a terminal `init` asks for the template, the directory, whether to install and whether to use git, the way
+`npm create cloudflare` does; `-y` takes the defaults and `--no-install` / `--no-git` skip a step.
+
 Happy with it? Log in once, then ship it:
 
 ```sh
@@ -154,10 +168,20 @@ preselects the team on the approval page.
   app itself, or when `compatibility_date` is older than `2026-11-18`, the date
   from which the platform runtime serves service bindings between Cloud apps.
   Hosts need the matching sproutd support.
-- **Not sent yet.** Other bindings (KV, D1, R2, queues, Durable Objects) and cron
-  triggers in `sproutboat.jsonc` are not sent to the Cloud by the CLI yet; the
-  deploy warns and the app runs without them. `secrets` names in
-  `sproutboat.jsonc` only declare them. Static assets are uploaded by content hash.
+- **Every other binding.** `kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`,
+  `analytics_engine_datasets`, `durable_objects`, `ratelimiters`, the `secrets` names, the
+  `assets` binding and `triggers.crons` go to the Cloud in the app record. On the Cloud each
+  app's storage is private to it, so nothing is provisioned and no id is needed: the binding
+  is the name (`DB` is the database `d1 execute --remote` addresses, `UPLOADS` the bucket
+  `r2 object` addresses), and the record's resource id is that name in lowercase (a queue's
+  is its queue name). An account-level `id` pinned in `sproutboat.jsonc` is ignored, with a
+  warning. The worker consumes every queue it binds, so each queue becomes one queue
+  consumer carrying its `max_batch_size`, `max_batch_timeout`, `max_retries` and
+  `dead_letter_queue` (Cloudflare's defaults when unset). `deploy` refuses, before
+  uploading anything, more than 16 crons, 16 queues or 64 bindings in all, a cron or name the
+  Cloud would refuse, and a `durable_objects` class the entry module does not export.
+  `deploy --dry-run` lists what would be sent. Storage itself is created by the host on first
+  use and survives deploys.
 
 For self-hosted (Community) endpoints, `login` keeps the browser flow, and for
 CI or an agent you can skip it and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_API_TOKEN`.
@@ -168,8 +192,8 @@ The everyday loop:
 
 | Command | What it does |
 | --- | --- |
-| `init [name]` | Scaffold `sproutboat.jsonc`, `src/index.js` and a `package.json` that pins `sproutboat` |
-| `dev [--port <n>]` | Run it here against a real broker, rebuilding on save |
+| `init [name] [--template <name>]` | Scaffold a project: the hello starter, or one of four TypeScript starters with tests (`--list-templates`) |
+| `dev [--port <n>] [--ip <address>]` | Run it here against a real broker, rebuilding on save; `--ip 0.0.0.0` makes it reachable on your network |
 | `deploy` | Build, provision bindings, upload, wait until the URL serves |
 | `tail [filters]` | Live request events, console output and exceptions, like `wrangler tail` |
 | `rollback <id>` | Re-activate a previous version |
@@ -289,7 +313,7 @@ files in the project and from its own `node_modules`, and may also export
 is a global, not a parameter. Binding calls are synchronous until the compatibility
 date that makes each one return a Promise, as on Workers (D1 from 2026-10-24, KV from
 2026-10-25, R2 from 2026-10-26); `await` works at every date, so always await them.
-[`examples/kitchen-sink/`](examples/kitchen-sink) uses every binding.
+[`examples/`](examples) has one small example per binding.
 
 For objects larger than one request, use resumable R2 multipart uploads. The
 [large-object guide](docs/r2-large-objects.md) covers part sizing, browser

package/SURFACE.md

@@ -3,16 +3,16 @@
 > 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.54.0
+**Package:** `sproutboat` 0.55.0
 
 ## Commands
 
 | Command | Arguments | Summary |
 | --- | --- | --- |
-| `init` | `[name]` | Scaffold sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev, deploy and check scripts) in ./<name>. |
+| `init` | `[name] [--template <name>] [--list-templates] [--git | --no-git] [--install | --no-install] [-y, --yes]` | Scaffold a project in ./<name> (the last path segment is the app's name), with the shape of `npm create cloudflare`. Without --template it writes sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev, deploy and check scripts). `--template <name>` writes a starter instead, standard Workers TypeScript with tests, a README and a current worker-configuration.d.ts: realtime-room (a chat room on Durable Objects and hibernating WebSockets), api-d1 (a JSON API on D1 with migrations and validation), site-api (a static site and its API in one Worker) or jobs (a cron trigger, a queue and KV); `--list-templates` prints them with their descriptions. In a terminal it asks for the template, the directory, whether to install dependencies and whether to use git (both default to yes); `-y` takes every default without asking, and anywhere else nothing runs that a flag did not ask for. `--install` runs the project's package manager (npm, pnpm, yarn or bun, by lockfile, else the tool that launched the CLI); `--git` runs `git init` and makes a first commit, and does nothing inside an existing repository. It never overwrites a file. |
 | `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] [-e, --env <name>] [--env-file <file>]...` | Run the project on this machine with local storage, rebuilding on save. Secrets come from .dev.vars or the .env files (never both), as in Wrangler; a declared secret with no value is a warning. |
+| `types` | `[path] [--env-interface <name>] [--strict-vars[=false]] [--include-runtime[=false]] [--include-env[=false]] [--check]` | Generate the project's `Env` as TypeScript from sproutboat.jsonc, like `wrangler types`: the file is worker-configuration.d.ts unless <path> names another; it declares `interface Env` (and `Cloudflare.Env`, which `import { env } from "cloudflare:workers"` reads) with a type per binding, literal types for vars (--strict-vars=false makes them `string`), and a Durable Object binding typed with its class when the entry is TypeScript. It references the runtime types shipped with the CLI (--include-runtime=false leaves that out, for a project that brings its own) instead of copying them in, and there is no --include-main-module. Type a handler as `export default { ... } satisfies ExportedHandler<Env>`. --check exits 1 when the file is missing or out of date, by the hash in its first lines. KV, D1, R2, Durable Object and Fetcher types follow the compatibility date, as the runtime does. `dev` and `deploy` refresh the default file when it was written by a plain `sproutboat types` and the config has moved on; they leave one made with other flags alone. A positional that is an existing directory is still read as the project directory. The file earlier releases wrote, sproutboat-env.d.ts, is removed when it is still as generated. |
+| `dev` | `[project-dir] [--port <n>] [--ip <address>] [--no-watch] [-e, --env <name>] [--env-file <file>]...` | Run the project on this machine with local storage, rebuilding on save. It listens on 127.0.0.1 unless `--ip` names another address (`--ip 0.0.0.0` is reachable from other machines on the network, as in Wrangler). Secrets come from .dev.vars or the .env files (never both), as in Wrangler; a declared secret with no value is a warning. |
 | `run` | `[project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]` | Launch a standalone binary with its port, data directory and declared secrets supplied at launch, never baked in. Precedence: --port/--data-dir, then the --env-file files (later overrides earlier), then the environment. A missing declared secret fails the launch, like wrangler deploy; --check validates without starting. |
 | `build` | `[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--release] [--deploy-files] [--with-restore] [--emit-only]` | Compile the app to a native binary (Porffor + Zig), cross-compiled for Linux x64 by default. `--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 separate storage process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--release` makes a standalone build the full `-flto -O3` one to publish; without it the link skips LTO (1.5 to 2x faster cold, ~90 MB link memory instead of 1.1 to 1.6 GB, fewer requests per second); `SPROUTBOAT_RELEASE=1` does the same, and a non-standalone build is always the release build. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled. |
 | `toolchain` | `doctor [--json]` | Report the selected compiler inputs, cache locations, overrides, and host prerequisites without downloading or compiling anything. |
@@ -26,7 +26,7 @@
 | `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>> | execute <database> (--command <sql> | --file <path>) [--json] [--local | --remote] | migrations <create | list | apply> <database> ...` | D1 databases. `create` prints the id to bind from sproutboat.jsonc; `execute` runs SQL against the local dev database (.sproutboat/dev/d1/<BINDING>.sqlite) unless --remote, as in Wrangler, and prints JSON when stdout is not a terminal; `migrations create <database> <name>` writes migrations/NNNN_<name>.sql (migrations_dir in sproutboat.jsonc changes the folder), `migrations list` shows the ones not applied, and `migrations apply` applies them in order, each with its row in the d1_migrations table in one transaction, after a confirmation in a terminal. <database> is the binding name from d1_databases. --remote needs a Sproutboat Cloud endpoint (app:write to change data, app:read for SELECT only); self-hosted Community has no remote D1 route yet and says so. |
 | `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>> | object <get <bucket>/<key> [--file <path> | --pipe] | put <bucket>/<key> (--file <path> | --pipe) [--content-type <t>] [--cache-control <v>] ... | delete <bucket>/<key>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc; `object get | put | delete <bucket>/<key>` read and write the objects of a Cloud app's bucket (<bucket> is the binding name from r2_buckets) with Wrangler's flags (--file, --pipe, --content-type, --content-disposition, --content-encoding, --content-language, --cache-control, --expires; `get` without --file writes ./<key>), 64 MiB per object, remote only (--local is refused). A key is 1 to 1024 bytes with no control character, backslash, or empty, . or .. segment, checked before anything is sent. The key needs the data:read grant to get and data:write to put or delete (the error says which it lacks and how to get it). On self-hosted Community `get` reads through the existing route by bucket name, and `put` and `delete` say they are not supported yet. |
 | `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. |
-| `domains` | `<list | add <host> | verify <host> | delete <host>> [project-dir] [--api-url <url>]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
+| `domains` | `<list | add <host> | verify <host> | delete <host>> [project-dir] [--api-url <url>] [--account <team>]` | List the project's domains, or attach one (TXT-verified). On the Cloud only list works: custom domains are added by an operator, and deploys keep them. |
 | `secrets` | `<list | put <NAME> [--value <value>] | delete <NAME> | bulk [file.json | file.env]> [project-dir] [--no-deploy] [--api-url <url>] [--account <team>]` | Manage encrypted project secrets (read as env.NAME); `secret` is the same command, as in Wrangler. `put` reads the value from stdin unless --value is given, so it stays out of shell history. `bulk` takes the file of `wrangler secret bulk`: JSON {"NAME": "value", "OLD": null} (null deletes) or a .env file, from the file or stdin, at most 100 entries. On a Cloud endpoint secrets are per app and independent of deploys: put, delete and bulk act on the deployed app, and by default wait for a host to apply them as a new version of the running module (like wrangler secret, which deploys at once); --no-deploy returns as soon as the change is stored. Permissions secret:write and secret:list; an app that is not deployed yet says to deploy first or pass --secrets-file on the first deploy. Self-hosted Community applies secrets on the next deploy or restart of the app and has no redeploy route yet, so --no-deploy changes nothing there. |
 | `login` | `[--api-url <url>] [--token <token>] [--account <team>]` | Sign in, as the profile named by --profile (the first login makes `default`). On the Cloud: the device-code flow (RFC 8628), which prints a code and a link, opens the browser when it can, and stores an account API key named `CLI on <hostname>` for the team you approve (--account preselects it). Elsewhere the browser flow, or store <token> for <url> directly. |
 | `logout` | `[--api-url <url>] [--account <team>]` | Forget the stored credential of the profile in use, or for <url>. On the Cloud it also revokes the key on the server (the default team, or --account). |
@@ -35,7 +35,7 @@
 | `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] [-e, --env <name>] [--env-file <file>]... | run [project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check] | build [project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--release] [--deploy-files] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] [--api-url <url>] [--account <team>] [--module <file.so>] [--sproutd <dir> --generation <dir>] [--secrets-file <file>] | deployments <list | status | tail <id>> [--json] [--api-url <url>] [--account <team>] | versions <list | view <version-id>> [project-dir] [--api-url <url>] | rollback <version-id> [project-dir] [--api-url <url>] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]] [--api-url <url>] | delete [project-dir] [--name <project>] --yes [--api-url <url>] | 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>> | execute <database> (--command <sql> | --file <path>) [--json] [--local | --remote] | migrations <create | list | apply> <database> ... | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | object <get <bucket>/<key> [--file <path> | --pipe] | put <bucket>/<key> (--file <path> | --pipe) [--content-type <t>] [--cache-control <v>] ... | delete <bucket>/<key>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] [--api-url <url>] | secrets <list | put <NAME> [--value <value>] | delete <NAME> | bulk [file.json | file.env]> [project-dir] [--no-deploy] [--api-url <url>] [--account <team>] | login [--api-url <url>] [--token <token>] [--account <team>] | logout [--api-url <url>] [--account <team>] | whoami [--api-url <url>] [--account <team>] | profile <list | use <name>> | complete [bash | zsh | fish]>
+usage: sproutboat <init [name] [--template <name>] [--list-templates] [--git | --no-git] [--install | --no-install] [-y, --yes] | check [project-dir] | types [path] [--env-interface <name>] [--strict-vars[=false]] [--include-runtime[=false]] [--include-env[=false]] [--check] | dev [project-dir] [--port <n>] [--ip <address>] [--no-watch] [-e, --env <name>] [--env-file <file>]... | run [project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check] | build [project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--release] [--deploy-files] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] [--api-url <url>] [--account <team>] [--module <file.so>] [--sproutd <dir> --generation <dir>] [--secrets-file <file>] | deployments <list | status | tail <id>> [--json] [--api-url <url>] [--account <team>] | versions <list | view <version-id>> [project-dir] [--api-url <url>] | rollback <version-id> [project-dir] [--api-url <url>] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]] [--api-url <url>] | delete [project-dir] [--name <project>] --yes [--api-url <url>] | 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>> | execute <database> (--command <sql> | --file <path>) [--json] [--local | --remote] | migrations <create | list | apply> <database> ... | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | object <get <bucket>/<key> [--file <path> | --pipe] | put <bucket>/<key> (--file <path> | --pipe) [--content-type <t>] [--cache-control <v>] ... | delete <bucket>/<key>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] [--api-url <url>] [--account <team>] | secrets <list | put <NAME> [--value <value>] | delete <NAME> | bulk [file.json | file.env]> [project-dir] [--no-deploy] [--api-url <url>] [--account <team>] | login [--api-url <url>] [--token <token>] [--account <team>] | logout [--api-url <url>] [--account <team>] | whoami [--api-url <url>] [--account <team>] | profile <list | use <name>> | complete [bash | zsh | fish]>
 ```
 
 ## Global flags
@@ -68,7 +68,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | `CXX` | C++ compiler for a host build's native-fetch link step (default `c++` if present, else the vendored Zig cross-compiler targeting this host). |
 | `AR` | Archiver used to assemble uSockets.a for a host build (default `ar` if present, else Zig's). |
 | `SPROUTBOAT_COMPILE_TIMEOUT_MS` | Porffor compile timeout in ms (default 600000). |
-| `SPROUTBOAT_PORFFOR_CHANNEL` | Porffor channel for standalone builds: `alpha-22` (default) or `alpha-19` (the previous compiler, kept as a fallback for one release). |
+| `SPROUTBOAT_PORFFOR_CHANNEL` | Porffor channel for standalone builds: `alpha-23` (default), `alpha-22` or `alpha-19` (the oldest compiler, kept as a fallback for one release). |
 | `SPROUTBOAT_RELEASE` | Same as `build --standalone --release`: link with LTO. Any value but empty, `0` or `false` turns it on. |
 | `SPROUTBOAT_FLTO` | Overrides link-time optimization on alpha 22 builds: `1` turns it on, `0` turns it off. |
 | `SPROUTBOAT_TOOLCHAIN_CACHE` | Managed Porffor and compiler cache root (default ~/.cache/sproutboat). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -48,25 +48,32 @@
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
     "examples": "bun examples/smoke.ts",
+    "examples:types": "bun examples/typecheck.ts",
+    "examples:workerd": "bun examples/workerd.ts",
+    "templates:embed": "bun scripts/embed-templates.ts",
     "build:cli": "bun scripts/build-cli.ts",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
     "test": "bun test",
-    "example:kitchen-sink": "bun examples/kitchen-sink/harness.ts",
+    "example:kitchen-sink": "bun dogfood/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",
-    "kitchen-sink": "bun examples/kitchen-sink/harness.ts",
-    "kitchen-sink:standalone": "bun examples/kitchen-sink/harness-standalone.ts"
+    "kitchen-sink": "bun run kitchen-sink:demo && bun run conformance",
+    "kitchen-sink:demo": "bun dogfood/kitchen-sink/harness.ts",
+    "conformance": "bun test/fixtures/conformance/harness.ts",
+    "kitchen-sink:standalone": "bun run kitchen-sink:demo:standalone && bun run conformance:standalone",
+    "kitchen-sink:demo:standalone": "bun dogfood/kitchen-sink/harness-standalone.ts",
+    "conformance:standalone": "bun test/fixtures/conformance/harness-standalone.ts"
   },
   "dependencies": {
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.6.0",
-    "@sproutboat/runtime": "^0.44.0",
-    "@sproutboat/toolchain": "^0.24.2",
-    "@sproutboat/wire": "^0.22.4"
+    "@sproutboat/runtime": "^0.45.0",
+    "@sproutboat/toolchain": "^0.26.1",
+    "@sproutboat/wire": "^0.22.5"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -75,13 +82,14 @@
     "lefthook": "2.1.14",
     "oxfmt": "0.70.0",
     "oxlint": "1.85.0",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "wrangler": "4.161.0"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.54.0",
-    "@sproutboat/cli-darwin-x64": "0.54.0",
-    "@sproutboat/cli-linux-arm64": "0.54.0",
-    "@sproutboat/cli-linux-x64": "0.54.0"
+    "@sproutboat/cli-darwin-arm64": "0.55.0",
+    "@sproutboat/cli-darwin-x64": "0.55.0",
+    "@sproutboat/cli-linux-arm64": "0.55.0",
+    "@sproutboat/cli-linux-x64": "0.55.0"
   },
   "engines": {
     "node": ">=18"

package/scripts/embed-templates.ts

@@ -0,0 +1,87 @@
+/**
+ * Embed the starter templates in the CLI.
+ *
+ * `templates/<name>/` are real projects: CI runs each one (typecheck, tests, standalone, workerd). `sproutboat init
+ * --template <name>` has to find them in the compiled executable, which carries no files of its own, so this writes
+ * every text file of every template into `src/templates-embedded.ts`, a module the executable bundles like any other.
+ *
+ *   bun scripts/embed-templates.ts           # rewrite src/templates-embedded.ts
+ *   bun scripts/embed-templates.ts --check   # exit 1 when it is out of date (src/templates.test.ts runs this check)
+ *
+ * What is left out, because a project generates or installs it: worker-configuration.d.ts (`init` runs
+ * `sproutboat types` on the new project, so its hash matches the project's name), node_modules, build output,
+ * lockfiles and `.dev.vars`.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { isString, jsonObject, parseJsonValue } from "../src/json";
+
+const ROOT = resolve(import.meta.dir, "..");
+const TEMPLATES = join(ROOT, "templates");
+const OUTPUT = join(ROOT, "src/templates-embedded.ts");
+
+const SKIPPED_NAMES = new Set([
+  "worker-configuration.d.ts",
+  "node_modules",
+  ".sproutboat",
+  "dist",
+  ".dev.vars",
+  "package-lock.json",
+  "bun.lock",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  ".DS_Store",
+]);
+
+export interface EmbeddedTemplate {
+  description: string;
+  files: Map<string, string>;
+}
+
+function filesOf(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => !SKIPPED_NAMES.has(entry.name))
+    .flatMap((entry) => (entry.isDirectory() ? filesOf(join(dir, entry.name)) : [join(dir, entry.name)]))
+    .sort();
+}
+
+export function readTemplates(): Map<string, EmbeddedTemplate> {
+  const found = new Map<string, EmbeddedTemplate>();
+  if (!existsSync(TEMPLATES)) return found;
+  for (const entry of readdirSync(TEMPLATES, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || SKIPPED_NAMES.has(entry.name)) continue;
+    const dir = join(TEMPLATES, entry.name);
+    const files = new Map<string, string>();
+    for (const file of filesOf(dir)) files.set(relative(dir, file).split("\\").join("/"), readFileSync(file, "utf8"));
+    const description = jsonObject(parseJsonValue(files.get("package.json") ?? "{}"))?.description;
+    if (!isString(description))
+      throw new Error(`templates/${entry.name}/package.json needs a description: it is the listing`);
+    found.set(entry.name, { description, files });
+  }
+  return found;
+}
+
+export function render(templates: Map<string, EmbeddedTemplate>): string {
+  const plain = Object.fromEntries(
+    [...templates].map(([name, { description, files }]) => [name, { description, files: Object.fromEntries(files) }]),
+  );
+  return `// Generated by scripts/embed-templates.ts from templates/. Do not edit: run \`bun run templates:embed\`.
+// The starter templates \`sproutboat init --template\` writes, as text, so the compiled executable carries them.
+export const EMBEDDED_TEMPLATES: Record<string, { description: string; files: Record<string, string> }> = ${JSON.stringify(plain, null, 2)};
+`;
+}
+
+if (import.meta.main) {
+  const next = render(readTemplates());
+  if (process.argv.includes("--check")) {
+    const current = existsSync(OUTPUT) ? readFileSync(OUTPUT, "utf8") : "";
+    if (current !== next) {
+      console.error("src/templates-embedded.ts is out of date. Run `bun run templates:embed`.");
+      process.exit(1);
+    }
+    console.log("src/templates-embedded.ts is up to date.");
+  } else {
+    await Bun.write(OUTPUT, next);
+    console.log(`wrote src/templates-embedded.ts (${(next.length / 1024).toFixed(0)} KiB)`);
+  }
+}

package/src/account-field.ts

@@ -50,13 +50,44 @@ const MIGRATIONS_DIR_ERROR = 'migrations_dir must be a relative folder inside th
 const validMigrationsDir = (dir: JsonValue | undefined): boolean =>
   isString(dir) && dir !== "" && !dir.startsWith("/") && !/^[A-Za-z]:/.test(dir) && !dir.split(/[\\/]/).includes("..");
 
+/** The `main` a project with assets and no `main` gets: a file that does not exist, written by `readProject` into `.sproutboat/`. */
+export const ASSETS_ONLY_MAIN = "src/.assets-only.js";
+
+/**
+ * The entry a Worker with only static assets runs, as Wrangler allows (`assets` and no `main`). The platform serves a matching
+ * file before any code runs; a request that matches none reaches this, and `env.<binding>.fetch` answers it with the project's
+ * `not_found_handling`: the single-page app shell, the nearest 404 page, or a plain 404.
+ */
+export function assetsOnlySource(binding: string): string {
+  return [
+    "// Written by sproutboat: this project has `assets` and no `main`, so it is a Worker with only static assets.",
+    "export default {",
+    "  fetch(request, env) {",
+    `    return env.${binding}.fetch(request);`,
+    "  },",
+    "};",
+    "",
+  ].join("\n");
+}
+
+/** `assets` with a directory and no `main`: the assets-only case. The entry and the binding it calls are filled in. */
+function withAssetsOnlyEntry(config: JsonObject): JsonObject {
+  const assets = jsonObject(config.assets ?? null);
+  if (config.main !== undefined || assets === undefined) return config;
+  return { ...config, main: ASSETS_ONLY_MAIN, assets: { ...assets, binding: assets.binding ?? "ASSETS" } };
+}
+
 /**
  * parseConfig for a file that may carry the CLI-owned fields `account` and `migrations_dir`: they are validated here and
  * removed before the shared schema sees them.
  */
 export function parseProjectConfig(source: string): ConfigValidation {
   const loose = parseLoose(source);
-  if (loose === undefined || !("account" in loose || "migrations_dir" in loose)) return parseConfig(source);
+  if (loose === undefined) return parseConfig(source);
+  if (!("account" in loose || "migrations_dir" in loose)) {
+    const filled = withAssetsOnlyEntry(loose);
+    return filled === loose ? parseConfig(source) : parseConfig(JSON.stringify(filled));
+  }
   const errors: string[] = [];
   if ("account" in loose && (!isString(loose.account) || !ACCOUNT_RE.test(loose.account)))
     errors.push("account must be the URL name of a team (lowercase letters, digits and dashes)");
@@ -65,5 +96,5 @@ export function parseProjectConfig(source: string): ConfigValidation {
   const rest = Object.fromEntries(
     Object.entries(loose).filter(([key]) => key !== "account" && key !== "migrations_dir"),
   );
-  return parseConfig(JSON.stringify(rest));
+  return parseConfig(JSON.stringify(withAssetsOnlyEntry(rest)));
 }

package/src/build.ts

@@ -342,8 +342,8 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       generatedSource,
       target,
       optimize: input.optimize ?? "release",
-      // a non-LTO link is a different binary from the release one; only the alpha 22 channel honours it
-      lto: porfforChannel(input.withRestore) === "alpha-22" ? ltoEnabled({ ...input, target }) : true,
+      // a non-LTO link is a different binary from the release one; only the alpha 21 line's channels honour it
+      lto: porfforChannel(input.withRestore) !== "alpha-19" ? ltoEnabled({ ...input, target }) : true,
       toolchain: toolchainStamp(),
       toolchainPackageVersion,
       porffor: [PORFFOR_COMMIT_FULL, PORFFOR_ARCHIVE_SHA256],
@@ -351,7 +351,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       channel: porfforChannel(input.withRestore),
       // the alpha 22 channel's own inputs: the patched tree, the shim, the bridge, the build recipe, LTO
       channelInputs:
-        porfforChannel(input.withRestore) === "alpha-22"
+        porfforChannel(input.withRestore) !== "alpha-19"
           ? [A21_STANDALONE_FINGERPRINT, process.env.SPROUTBOAT_FLTO ?? ""]
           : null,
       native: embedded ? [sqliteStamp(), bearsslStamp()] : subtle ? [bearsslStamp()] : [],