sproutboat 0.4.9 → 0.4.11

package/README.md

@@ -1,11 +1,14 @@
 # sproutboat
 
-The CLI for [Sproutboat](https://github.com/baronunread/sproutboat) — a
-Wrangler-shaped tool for deploying workers to any Sproutboat control plane.
-MIT licensed.
+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.
+
+Full reference: [sproutboat.com/docs](https://sproutboat.com/docs)
+(plain text for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
 
 ```sh
-bunx sproutboat login --api-url https://control.example.com
+bunx sproutboat login --api-url https://control.example.com   # one browser approval
 bunx sproutboat init hello
 cd hello
 bunx sproutboat deploy
@@ -19,7 +22,11 @@ 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`.
+The `login` browser step 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).
 
 ## Commands
 
@@ -27,20 +34,23 @@ For CI, skip `login` and set `SPROUTBOAT_API_URL` + `SPROUTBOAT_TOKEN`.
 | --- | --- |
 | `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 |
+| `build` | Cross-compile the sprout binary (Porffor + Zig) |
+| `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 [name]` | Deployed versions |
 | `rollback <id>` | Activate a previous version |
-| `delete --yes` | Delete the project |
+| `secrets [list \| set <NAME> [value] \| rm <NAME>]` | Encrypted project secrets, read as `env.NAME` |
+| `resource [list \| create <kind> <name> \| rename <id> <name> \| delete <id>]` | Account-level KV / D1 / R2 / queue stores |
+| `domains [list \| add <host> \| verify <host> \| rm <host>]` | Attach your own hostname (TXT + A, apex allowed) |
+| `delete --yes` | Delete the project, every version, and its route |
 
-Credentials are keyed by API URL in `~/.config/sproutboat/credentials.json`, so
-you can hold logins for several instances at once.
+Run `sproutboat` with no arguments for the grouped list.
+[`SURFACE.md`](SURFACE.md) is the generated inventory of every command and env var.
 
 ## Config
 
-`sproutboat.jsonc` — the entry point plus Cloudflare-shaped `env.*` bindings:
+`sproutboat.jsonc`: the entry point plus Cloudflare-shaped `env.*` bindings.
 
 ```jsonc
 {
@@ -50,42 +60,54 @@ you can hold logins for several instances at once.
 
   "vars": { "SITE": "hi" },
   "secrets": ["API_KEY"],
-  "kv_namespaces": ["CACHE"],
+  "kv_namespaces": ["CACHE"],                 // bare name, or { "binding": "CACHE", "id": "kv_..." }
   "d1_databases": ["DB"],
   "r2_buckets": ["UPLOADS"],
   "queues": ["JOBS"],
-  "analytics_engine_datasets": ["METRICS"],
+  "analytics_engine_datasets": ["METRICS"],   // bare name only, no id
   "durable_objects": { "COUNTER": "Counter" },
   "outbound": ["api.example.com"],
   "triggers": { "crons": ["*/5 * * * *"] },
-  "assets": { "directory": "public", "binding": "ASSETS" }
+  "assets": { "directory": "public", "binding": "ASSETS", "run_sprout_first": ["/api/*"] }
 }
 ```
 
-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.
+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 resource create` to make one up front
+and share its id across projects.
+
+The handler is one `export default { fetch(request) }`, optionally with
+`scheduled(event)` / `queue(batch)` handlers and Durable Object classes above
+it. `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.
 
 ## Requirements
 
 - [Bun](https://bun.sh) 1.4+
 
 `build` / `deploy` cross-compile the handler to a static `linux-x86_64` binary
-with Porffor and Zig (Zig is fetched automatically on first use). The package
-ships a prebuilt uWebSockets, so nothing else is compiled from source. No Docker,
-no root. On Windows, build from WSL.
+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.
 
-## Limits (v1)
+## Limits
 
-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.
+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. Node
+compatibility is Porffor alpha, so `import`/`require`, `process`, `node:*`, and
+parsing date strings do not work; `sproutboat check` catches most of it. Full
+list at [sproutboat.com/docs](https://sproutboat.com/docs).
 
 ---
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",

package/src/main.ts

@@ -409,21 +409,32 @@ async function tail(args: string[]) {
   process.stdout.write(await responseText(response, "could not read logs"));
 }
 
-type DomainView = { hostname: string; verified: boolean; verification: { type: string; name: string; value: string } | null };
+type DomainView = {
+  hostname: string;
+  verified: boolean;
+  verification: { type: string; name: string; value: string } | null;
+  serverAddresses: string[];
+  warning?: string;
+};
 function parseDomain(source: string): DomainView | undefined {
   const record = jsonObject(parseJsonValue(source));
   if (!record || !isString(record.hostname) || typeof record.verified !== "boolean") return undefined;
   const v = jsonObject(record.verification ?? null);
   const verification = v && isString(v.type) && isString(v.name) && isString(v.value) ? { type: v.type, name: v.name, value: v.value } : null;
-  return { hostname: record.hostname, verified: record.verified, verification };
+  const serverAddresses = Array.isArray(record.serverAddresses) ? record.serverAddresses.filter(isString) : [];
+  return { hostname: record.hostname, verified: record.verified, verification, serverAddresses, warning: isString(record.warning) ? record.warning : undefined };
 }
 function printDomain(domain: DomainView) {
   const status = domain.verified ? "verified" : "unverified";
   console.log(`${status.padEnd(10)} ${domain.hostname}`);
   if (domain.verification) {
-    console.log(`  add this DNS record, then run: sproutboat domains verify ${domain.hostname}`);
+    console.log("  add these DNS records, then run: sproutboat domains verify " + domain.hostname);
     console.log(`  ${domain.verification.type}  ${domain.verification.name}  "${domain.verification.value}"`);
+    if (domain.serverAddresses[0]) {
+      console.log(`  A    ${domain.hostname}  ${domain.serverAddresses[0]}   (point the hostname here, DNS-only / not proxied)`);
+    }
   }
+  if (domain.warning) console.log(amber(`  ! ${domain.warning}`));
 }
 
 async function domains(args: string[]) {