sproutboat 0.3.0 → 0.4.2

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.3.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.4.2 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -11,16 +11,18 @@
 | --- | --- | --- |
 | `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. |
+| `build` | `[project-dir]` | Cross-compile the native-fetch sprout (Porffor + Zig). |
+| `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]` | Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check. |
 | `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. |
+| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `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. |
+| `domains` | `[list | add <host> | verify <host> | rm <host>] [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
+| `secrets` | `[list | set <NAME> [value] | rm <NAME>] [project-dir]` | Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy. |
+| `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
 
 ```
-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]>
+usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | login [--api-url <url>] [--token <token>] | tail [project-dir] [--sprout] | versions list [project-dir] | rollback <version-id> [project-dir] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes>
 ```
 
 ## Environment variables
@@ -32,14 +34,15 @@ usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | dep
 | `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_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 worker module. |
+| `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. |
 | `SPROUTBOAT_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
+| `NO_COLOR` | When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY. |
 | `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. |
+| `SB_BROKER_PORT` | Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs). |
+| `SB_BROKER_TOKEN` | Per-deployment auth token the sprout sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT). |
+| `SB_SPROUT_URL` | http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it. |
 
 ## Build toolchain (pinned)
 

package/package.json

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

package/src/assets.ts

@@ -3,7 +3,7 @@
  * 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.
+ * the sprout chooses to serve itself.
  */
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync } from "node:fs";

package/src/broker.ts

@@ -2,11 +2,11 @@
 /**
  * Per-deployment binding broker.
  *
- * A native-fetch worker has no syscalls of its own beyond an inbound HTTP
+ * A native-fetch sprout has no syscalls of its own beyond an inbound HTTP
  * server; the prelude's inline-C transport opens a loopback TCP connection to
  * this process for every `env.<KV>` / `env.<SECRET>` / `fetch()` call. The
  * supervisor starts one broker per deployment, on its own loopback port, and
- * passes `SB_BROKER_PORT` + `SB_BROKER_TOKEN` to the worker next to `$PORT`.
+ * passes `SB_BROKER_PORT` + `SB_BROKER_TOKEN` to the sprout next to `$PORT`.
  *
  * Wire frame (both directions): [u32 LE length][payload].
  *   request payload : "<token>\n<json>"
@@ -47,11 +47,11 @@ export type BrokerOptions = {
   bindings?: Partial<Bindings>;
   secrets?: Record<string, string>;
   /**
-   * `http://127.0.0.1:<PORT>` of this deployment's worker. When set, the broker
-   * runs the cron scheduler and the queue consumer, delivering to the worker
+   * `http://127.0.0.1:<PORT>` of this deployment's sprout. When set, the broker
+   * runs the cron scheduler and the queue consumer, delivering to the sprout
    * with an `x-sb-trigger` header authenticated by `token`.
    */
-  workerUrl?: string;
+  sproutUrl?: string;
   /** Directory of published static assets (its sibling `assets.json` is the manifest). Backs `assets.get`. */
   assetsDir?: string;
   /** Injected in tests; defaults to the global `fetch`. */
@@ -423,15 +423,15 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     }
   }
 
-  // --- cron + queue delivery (only when this broker knows its worker) --------
+  // --- cron + queue delivery (only when this broker knows its sprout) --------
   const timers: ReturnType<typeof setInterval>[] = [];
   const QUEUE_BATCH = 10;
   const QUEUE_MAX_ATTEMPTS = 5;
 
   async function deliverTrigger(kind: "scheduled" | "queue", body: unknown): Promise<Response | null> {
-    if (!opts.workerUrl) return null;
+    if (!opts.sproutUrl) return null;
     try {
-      return await doFetch(opts.workerUrl, {
+      return await doFetch(opts.sproutUrl, {
         method: "POST",
         headers: { "x-sb-trigger": kind, "x-sb-token": token, "content-type": "application/json" },
         body: JSON.stringify(body),
@@ -442,7 +442,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   }
 
   function drainQueuesOnce(): void {
-    if (!opts.workerUrl || bindings.queues.length === 0) return;
+    if (!opts.sproutUrl || bindings.queues.length === 0) return;
     const now = Date.now();
     for (const q of bindings.queues) {
       const rows = db.query<{ id: string; body: string; attempts: number }, [string, number, number]>(
@@ -458,7 +458,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         queue: q,
         messages: rows.map((r) => ({ id: r.id, body: r.body, timestamp: now, attempts: r.attempts + 1 })),
       }).then(async (res) => {
-        let ack: string[] = rows.map((r) => r.id); // default: ack all if the worker didn't say
+        let ack: string[] = rows.map((r) => r.id); // default: ack all if the sprout did not say
         let retry: string[] = [];
         if (res && res.ok) {
           try {
@@ -479,7 +479,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     }
   }
 
-  if (opts.workerUrl) {
+  if (opts.sproutUrl) {
     if (bindings.queues.length > 0) timers.push(setInterval(drainQueuesOnce, 500));
     if (bindings.crons.length > 0) {
       let lastTick = "";
@@ -574,7 +574,7 @@ if (import.meta.main) {
       "data-dir": { type: "string" },
       bindings: { type: "string" },
       secrets: { type: "string" },
-      "worker-url": { type: "string" },
+      "sprout-url": { type: "string" },
       "assets-dir": { type: "string" },
     },
   });
@@ -590,9 +590,9 @@ if (import.meta.main) {
     token: values.token ?? process.env.SB_BROKER_TOKEN,
     bindings,
     secrets,
-    workerUrl: values["worker-url"] ?? process.env.SB_WORKER_URL,
+    sproutUrl: values["sprout-url"] ?? process.env.SB_SPROUT_URL,
     assetsDir: values["assets-dir"],
   });
   const { port } = listen(broker, "127.0.0.1", Number(values.port ?? process.env.SB_BROKER_PORT ?? 0));
-  console.log(`sproutboat broker: 127.0.0.1:${port} db=${values.db ?? ":memory:"} worker=${values["worker-url"] ?? process.env.SB_WORKER_URL ?? "(none)"}`);
+  console.log(`sproutboat broker: 127.0.0.1:${port} db=${values.db ?? ":memory:"} sprout=${values["sprout-url"] ?? process.env.SB_SPROUT_URL ?? "(none)"}`);
 }

package/src/build.ts

@@ -3,7 +3,7 @@ import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { walkAssets, type AssetManifest } from "./assets";
 import type { SproutboatConfig } from "./config";
-import { compileWorker } from "./compile";
+import { compileSprout } from "./compile";
 import { ARTIFACT_SCHEMA_VERSION, CAPABILITY_PROFILE, RUNTIME, type ArtifactManifest } from "./manifest";
 import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
 
@@ -33,7 +33,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   const sourceHash = digest(source);
   const artifactId = sourceHash.slice("sha256:".length, 24);
   const artifactDir = resolve(input.projectDir, ".sproutboat/dist", artifactId);
-  const workerPath = resolve(artifactDir, "worker");
+  const sproutPath = resolve(artifactDir, "sprout");
   await mkdir(artifactDir, { recursive: true });
 
   const bindings = {
@@ -50,15 +50,15 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   };
 
   const zigBin = await ensureZig();
-  await compileWorker({
+  await compileSprout({
     sourcePath: input.sourcePath,
-    outPath: workerPath,
+    outPath: sproutPath,
     vars: input.config.vars ?? {},
     bindings,
     zigBin,
   });
 
-  const worker = await readFile(workerPath);
+  const sprout = await readFile(sproutPath);
   const manifest: ArtifactManifest = {
     schemaVersion: ARTIFACT_SCHEMA_VERSION,
     project: input.config.name,
@@ -69,8 +69,8 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     esbuildVersion: esbuildVersion(),
     buildImage: toolchainStamp(),
     sourceHash,
-    binaryHash: digest(worker),
-    binarySize: (await stat(workerPath)).size,
+    binaryHash: digest(sprout),
+    binarySize: (await stat(sproutPath)).size,
     builtAt: new Date().toISOString(),
   };
   await writeFile(resolve(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);

package/src/compile.ts

@@ -28,7 +28,7 @@ export type CompileInput = {
 };
 
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
-export async function compileWorker(input: CompileInput): Promise<void> {
+export async function compileSprout(input: CompileInput): Promise<void> {
   await ensurePorfforPatched();
 
   // Seed the Porffor uWebSockets cache from the prebuilt archive in `vendor/` so
@@ -54,7 +54,7 @@ export async function compileWorker(input: CompileInput): Promise<void> {
 
   const outDir = dirname(input.outPath);
   await mkdir(outDir, { recursive: true });
-  const generatedPath = resolve(outDir, "worker.generated.js");
+  const generatedPath = resolve(outDir, "sprout.generated.js");
   const [source, prelude] = await Promise.all([readFile(input.sourcePath, "utf8"), readFile(preludePath, "utf8")]);
   await writeFile(generatedPath, wrapNativeFetchHandler(source, prelude, input.vars, input.bindings ?? EMPTY_BINDINGS));
 

package/src/config.ts

@@ -10,7 +10,7 @@ export type SproutboatConfig = {
   kv_namespaces?: string[];
   /** Secret binding names, exposed as `env.<NAME>` (value fetched at use). */
   secrets?: string[];
-  /** Hostnames the worker's `fetch()` may reach (exact host match). */
+  /** Hostnames the sprout's `fetch()` may reach (exact host match). */
   outbound?: string[];
   /** D1 (SQLite) database binding names, exposed as `env.<NAME>`. */
   d1_databases?: string[];
@@ -35,7 +35,7 @@ export type AssetsConfig = {
   binding?: string;
   /** What to serve when a request matches no file (applied by the broker on `env.<BINDING>.fetch`). */
   not_found_handling?: "none" | "single-page-application" | "404-page";
-  /** `true` = run the worker before serving any asset; string[] = selective route patterns (`!` negates). */
+  /** `true` = run the sprout before serving any asset; string[] = selective route patterns (`!` negates). */
   run_sprout_first?: boolean | string[];
 };
 

package/src/main.ts

@@ -8,6 +8,7 @@ import { validateManifest, type ArtifactManifest } from "./manifest";
 import { printDeployReport } from "./report";
 import { activeApiUrl, savedToken, saveToken } from "./credentials";
 import { usageLine } from "./surface";
+import { amber, bold, dim, leaf, ok, rose } from "./style";
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
 
@@ -70,6 +71,16 @@ function parseUrlResponse(source: string): { url: string } | undefined {
   return record && isString(record.url) ? { url: record.url } : undefined;
 }
 
+/** #55: `{ from, to }` when this deploy moves the live version onto a different
+ *  Porffor pin. Deployed artifacts are frozen at their build-time compiler, so
+ *  the pin only changes by redeploying — and the alpha compiler's output can
+ *  differ between pins. */
+function parsePorfforDrift(source: string): { from: string; to: string } | undefined {
+  const drift = (() => { try { return jsonObject(parseJsonValue(source))?.porfforDrift; } catch { return undefined; } })();
+  const record = drift && jsonObject(drift as JsonValue);
+  return record && isString(record.from) && isString(record.to) ? { from: record.from, to: record.to } : undefined;
+}
+
 function parseAuthorization(source: string): CliAuthorization | undefined {
   const record = jsonObject(parseJsonValue(source));
   if (!record || !isString(record.deviceCode) || !isString(record.userCode) || !isString(record.verificationUri) || !isSafeInteger(record.interval) || !isString(record.expiresAt)) return undefined;
@@ -96,7 +107,7 @@ const starterHandler = `export default {
 `;
 
 function fail(message: string): never {
-  console.error(`sproutboat: ${message}`);
+  console.error(`${rose("✗")} ${message}`);
   process.exit(1);
 }
 
@@ -137,14 +148,14 @@ async function init(name = "hello") {
 
 async function check(directory?: string) {
   const project = await readProject(directory);
-  console.log(`check passed: ${project.config.name} (${project.config.main}, native-fetch)`);
+  console.log(ok(`check passed — ${project.config.name} (${project.config.main}, native-fetch)`));
 }
 
 async function build(directory?: string) {
   const project = await readProject(directory);
-  console.log("Compiling the native-fetch server with Porffor + Zig (linux-x86_64, static)...");
+  console.log(dim("Compiling the native-fetch server with Porffor + Zig (linux-x86_64, static)…"));
   const artifact = await buildArtifact({ projectDir: project.directory, config: project.config, sourcePath: project.sourcePath });
-  console.log(`Built ${project.config.name}`);
+  console.log(ok(`built ${project.config.name}`));
   console.log(artifact.artifactDir);
   return { project, artifact };
 }
@@ -166,8 +177,8 @@ async function deploy(args: string[]) {
     config = built.project.config;
   }
   const manifest = Bun.file(resolve(artifactDir, "manifest.json"));
-  const worker = Bun.file(resolve(artifactDir, "worker"));
-  if (!(await manifest.exists()) || !(await worker.exists())) fail("artifact must contain manifest.json and worker");
+  const sprout = Bun.file(resolve(artifactDir, "sprout"));
+  if (!(await manifest.exists()) || !(await sprout.exists())) fail("artifact must contain manifest.json and sprout");
   const manifestValidation = validateManifest(await manifest.json());
   if (!manifestValidation.ok) fail(`invalid artifact manifest: ${manifestValidation.errors.join(", ")}`);
   const artifactManifest: ArtifactManifest = manifestValidation.value;
@@ -176,7 +187,7 @@ async function deploy(args: string[]) {
   printDeployReport(
     config ?? { name: projectName, main: "", compatibility_date: "(prebuilt artifact)" },
     artifactManifest,
-    new Uint8Array(await worker.arrayBuffer()),
+    new Uint8Array(await sprout.arrayBuffer()),
     manifest.size,
   );
   if (dryRun) {
@@ -191,14 +202,33 @@ async function deploy(args: string[]) {
     if (!deployments) fail("could not parse deployment list response");
     const active = deployments.find((deployment) => deployment.active && deployment.artifact === digest);
     if (active) {
-      console.log(`Nothing to deploy — artifact ${digest.slice(0, 12)} is already active`);
+      console.log(ok(`nothing to deploy — artifact ${digest.slice(0, 12)} is already active`));
       console.log(`https://${active.hostname}`);
       return;
     }
   }
   const form = new FormData();
   form.set("manifest", new File([await manifest.arrayBuffer()], "manifest.json", { type: "application/json" }));
-  form.set("worker", new File([await worker.arrayBuffer()], "worker", { type: "application/octet-stream" }));
+  form.set("sprout", new File([await sprout.arrayBuffer()], "sprout", { type: "application/octet-stream" }));
+
+  // #1 — ship the sidecars `sproutboat build` produced so the server can start
+  // the binding broker and serve static assets. Without bindings.json the broker
+  // never spawns and every KV/D1/R2/secret/queue/cron/DO call is dead on the box.
+  const bindingsFile = Bun.file(resolve(artifactDir, "bindings.json"));
+  if (await bindingsFile.exists()) {
+    form.set("bindings", new File([await bindingsFile.arrayBuffer()], "bindings.json", { type: "application/json" }));
+  }
+  const assetsManifestFile = Bun.file(resolve(artifactDir, "assets.json"));
+  if (await assetsManifestFile.exists()) {
+    const assetsManifest: { files?: Record<string, unknown> } = await assetsManifestFile.json();
+    form.set("assets_manifest", new File([await assetsManifestFile.arrayBuffer()], "assets.json", { type: "application/json" }));
+    for (const key of Object.keys(assetsManifest.files ?? {})) {
+      const file = Bun.file(resolve(artifactDir, "assets", `.${key}`));
+      if (!(await file.exists())) fail(`assets.json lists ${key} but assets${key} is missing — rebuild`);
+      form.append("asset", new File([await file.arrayBuffer()], key));
+    }
+  }
+
   const response = await fetch(`${apiUrl.replace(/\/$/, "")}/api/projects/${projectName}/deployments`, {
     method: "POST",
     headers: { "x-api-key": token },
@@ -207,8 +237,40 @@ async function deploy(args: string[]) {
   const body = await responseText(response, "deployment rejected");
   const deployed = parseUrlResponse(body);
   if (!deployed) fail("deployment response did not include a URL");
-  console.log(`\nDeployed ${projectName}`);
-  console.log(`  ${deployed.url}`);
+  console.log(`\n${leaf("🌱")} ${bold(leaf(`Deployed ${projectName}`))}`);
+  console.log(`  ${bold(deployed.url)}`);
+  const drift = parsePorfforDrift(body);
+  if (drift) {
+    console.warn(amber(`\n! Porffor pin changed: ${drift.from} -> ${drift.to}`));
+    console.warn(dim(`  The previous live version stays frozen at ${drift.from}; this one is built with ${drift.to}.`));
+    console.warn(dim(`  The alpha compiler's output can differ between pins (see COMPAT.md) — roll back if this version misbehaves.`));
+  }
+  if (!args.includes("--no-wait")) {
+    const healthy = await waitForHealthy(deployed.url, 90_000);
+    console.log(healthy
+      ? `  ${ok("serving")}`
+      : amber("  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`)"));
+  }
+}
+
+/**
+ * Poll the deployment URL until the edge returns any non-5xx response. Connection
+ * and TLS errors (the cert is issued on the first HTTPS request) count as "not
+ * ready yet". Returns false on timeout without failing the deploy — the artifact
+ * is already active server-side.
+ */
+async function waitForHealthy(url: string, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  let wait = 1000;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { method: "HEAD", redirect: "manual" });
+      if (response.status < 500) return true;
+    } catch { /* DNS / TLS-not-yet-issued / connection refused — keep waiting */ }
+    await Bun.sleep(Math.min(wait, Math.max(0, deadline - Date.now())));
+    if (wait < 5000) wait += 1000;
+  }
+  return false;
 }
 
 function parseLoginArgs(args: string[]) {
@@ -255,7 +317,7 @@ async function login(args: string[]) {
     const token = parseToken(result);
     if (!token) fail("login response did not include a CLI token");
     await saveToken(apiUrl, token);
-    console.log("Login approved. Credentials were saved locally for this API endpoint.");
+    console.log(ok("login approved — credentials saved for this endpoint"));
     return;
   }
   fail("login expired before approval");
@@ -284,22 +346,131 @@ async function rollback(args: string[]) {
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments/${id}/activate`, { method: "POST", headers: { "x-api-key": token } });
   const deployment = parseUrlResponse(await responseText(response, "rollback rejected"));
   if (!deployment) fail("rollback response did not include a URL");
-  console.log(`Rolled back ${project.config.name}`);
+  console.log(ok(`rolled back ${project.config.name}`));
   console.log(deployment.url);
 }
 
 async function tail(args: string[]) {
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
-  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/logs/recent`, { headers: { "x-api-key": token } });
+  const sproutLog = args.includes("--sprout");
+  const dir = args.find((arg) => !arg.startsWith("-"));
+  const [project, { apiUrl, token }] = await Promise.all([readProject(dir), apiCredentials()]);
+  const path = sproutLog ? "logs/sprout" : "logs/recent";
+  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/${path}`, { headers: { "x-api-key": token } });
   process.stdout.write(await responseText(response, "could not read logs"));
 }
 
+type DomainView = { hostname: string; verified: boolean; verification: { type: string; name: string; value: string } | null };
+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 };
+}
+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(`  ${domain.verification.type}  ${domain.verification.name}  "${domain.verification.value}"`);
+  }
+}
+
+async function domains(args: string[]) {
+  const sub = args[0] && !args[0].startsWith("-") && ["list", "add", "verify", "rm"].includes(args[0]) ? args.shift()! : "list";
+  const host = sub === "list" ? undefined : args.shift();
+  if (sub !== "list" && !host) fail(`usage: sproutboat domains ${sub} <hostname> [project-dir]`);
+  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
+  const base = `${apiUrl}/api/projects/${project.config.name}/domains`;
+  const auth = { "x-api-key": token };
+
+  if (sub === "list") {
+    const response = await fetch(base, { headers: auth });
+    const body = await responseText(response, "could not list domains");
+    const list = parseJsonValue(body);
+    if (!Array.isArray(list)) fail("could not parse domains response");
+    if (list.length === 0) { console.log("no custom domains"); return; }
+    for (const entry of list) { const d = parseDomain(JSON.stringify(entry)); if (d) printDomain(d); }
+    return;
+  }
+  if (sub === "rm") {
+    const response = await fetch(`${base}/${host}`, { method: "DELETE", headers: auth });
+    await responseText(response, "delete rejected");
+    console.log(ok(`removed ${host}`));
+    return;
+  }
+  const url = sub === "add" ? base : `${base}/${host}/verify`;
+  const init = sub === "add"
+    ? { method: "POST", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify({ hostname: host }) }
+    : { method: "POST", headers: auth };
+  const response = await fetch(url, init);
+  const domain = parseDomain(await responseText(response, `${sub} rejected`));
+  if (!domain) fail(`${sub} response was not a domain record`);
+  printDomain(domain);
+}
+
+async function secrets(args: string[]) {
+  const sub = args[0] && ["list", "set", "rm"].includes(args[0]) ? args.shift()! : "list";
+  const name = sub === "list" ? undefined : args.shift();
+  if (sub !== "list" && !name) fail(`usage: sproutboat secrets ${sub} <NAME> [project-dir]`);
+  if (name && !/^[A-Z][A-Z0-9_]*$/.test(name)) fail("secret name must be UPPER_SNAKE_CASE");
+  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
+  const base = `${apiUrl}/api/projects/${project.config.name}/secrets`;
+  const auth = { "x-api-key": token };
+
+  if (sub === "list") {
+    const body = await responseText(await fetch(base, { headers: auth }), "could not list secrets");
+    const parsed = jsonObject(parseJsonValue(body));
+    const names = parsed && Array.isArray(parsed.names) ? parsed.names.filter(isString) : [];
+    console.log(names.length ? names.join("\n") : "no secrets");
+    return;
+  }
+  if (sub === "rm") {
+    await responseText(await fetch(`${base}/${name}`, { method: "DELETE", headers: auth }), "delete rejected");
+    console.log(ok(`removed ${name}`));
+    return;
+  }
+  // set: value from the next arg, else stdin (keeps it out of shell history).
+  const value = args[1] && !args[1].startsWith("-") && args[1] !== project.directory
+    ? args[1]
+    : (await Bun.stdin.text()).replace(/\r?\n$/, "");
+  if (!value) fail("no value — pass it as an argument or pipe it on stdin");
+  await responseText(
+    await fetch(`${base}/${name}`, { method: "PUT", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify({ value }) }),
+    "set rejected",
+  );
+  console.log(`Set ${name} — applies on the next deploy or sprout restart`);
+}
+
 async function deleteProject(args: string[]) {
-  if (args[0] !== "--yes") fail("refusing to delete without --yes");
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[1]), apiCredentials()]);
-  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}`, { method: "DELETE", headers: { "x-api-key": token } });
-  await responseText(response, "delete rejected");
-  console.log(`Deleted ${project.config.name}`);
+  // `sproutboat delete [project-dir] [--name <project>] --yes` — flags in any order.
+  const positional: string[] = [];
+  let confirmed = false;
+  let explicitName: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--yes" || arg === "-y") confirmed = true;
+    else if (arg === "--name") explicitName = args[(index += 1)];
+    else if (!arg.startsWith("-")) positional.push(arg);
+    else fail(`unknown flag ${arg}\nusage: sproutboat delete [project-dir] [--name <project>] --yes`);
+  }
+
+  const { apiUrl, token } = await apiCredentials();
+  const name = explicitName ?? (await readProject(positional[0])).config.name;
+  if (!confirmed) fail(`this permanently removes "${name}", every version, and its route — re-run with --yes`);
+
+  const url = `${apiUrl}/api/projects/${encodeURIComponent(name)}?confirm=${encodeURIComponent(name)}`;
+  const body = await responseText(await fetch(url, { method: "DELETE", headers: { "x-api-key": token } }), "delete rejected");
+
+  let result: JsonObject = {};
+  try { result = jsonObject(parseJsonValue(body)) ?? {}; } catch { /* a 2xx already confirmed the delete */ }
+  const versions = isSafeInteger(result.versionsRemoved) ? result.versionsRemoved : 0;
+  const routes = Array.isArray(result.routeRemoved) ? result.routeRemoved.filter(isString) : [];
+  const failed = Array.isArray(result.artifactCleanupFailed) ? result.artifactCleanupFailed.filter(isString) : [];
+
+  console.log(ok(`deleted ${name} — ${versions} version${versions === 1 ? "" : "s"} removed`));
+  for (const route of routes) console.log(`  released ${route}`);
+  if (failed.length) console.log(`  ! ${failed.length} artifact file(s) left on disk — remove them manually`);
 }
 
 function usage(): never {
@@ -316,6 +487,8 @@ switch (command) {
   case "deploy": await deploy(args); break;
   case "versions": await versions(args); break;
   case "rollback": await rollback(args); break;
+  case "domains": await domains(args); break;
+  case "secrets": await secrets(args); break;
   case "tail": await tail(args); break;
   case "delete": await deleteProject(args); break;
   default: usage();

package/src/native-fetch-prelude.js

@@ -31,6 +31,44 @@ function __sbStartupMark() {
 }
 __sbStartupMark();
 
+// #28 — process CPU time in ms (CLOCK_PROCESS_CPUTIME_ID). Marshalled back as a
+// string via the same primitives as __sbEnv / __sbRandomBytes (proven working),
+// then parsed — Porffor's number boxing for a bare inline-C assignment is not
+// relied on. `__sbEntry` samples it around the handler for per-invocation CPU.
+function __sbCpuMs() {
+  let res = '';
+  Porffor.c`
+    struct timespec __ts;
+    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &__ts);
+    double __ms = (double)__ts.tv_sec * 1000.0 + (double)__ts.tv_nsec / 1000000.0;
+    char __b[32];
+    int __n = snprintf(__b, sizeof(__b), "%.3f", __ms);
+    if (__n > 0) res = porf_box((f64)porf_native_fetch_alloc_bytestring(__b, (size_t)__n), 195);
+  `;
+  return res === '' ? 0 : parseFloat(res);
+}
+
+// #28 — stamp `x-sb-cpu-ms` onto a handler Response. Porffor alpha-4's
+// native-fetch serializer only reads headers from the plain object passed to
+// `new Response(body, { headers })` — a later `.set()` or a `Headers` instance
+// is ignored on the wire — so the metric is carried by rebuilding the Response
+// with one extra header. Safe only for a string body (the norm under
+// http-sync-v0) with no Set-Cookie to comma-fold; anything else is returned
+// untouched and the edge simply omits cpuMs for that request.
+function __sbTagCpu(res, t0) {
+  const cpu = __sbCpuMs() - t0;
+  try {
+    const body = res && res.body;
+    if (typeof body === 'string' && !res.headers.has('set-cookie')) {
+      const headers = {};
+      res.headers.forEach(function (value, name) { headers[name] = value; });
+      headers['x-sb-cpu-ms'] = (cpu >= 0 ? cpu : 0).toFixed(3);
+      return new Response(body, { status: res.status, headers: headers });
+    }
+  } catch (e) { /* fall through to the original response */ }
+  return res;
+}
+
 class __SproutboatURLSearchParams {
   constructor(init) {
     this._keys = [];
@@ -181,13 +219,13 @@ if (globalThis.crypto.randomUUID == null) {
 // Bindings: env.<KV>, env.<SECRET>, env.<D1>, env.<R2>, and globalThis.fetch,
 // backed by a Bun broker on a loopback TCP port. The transport is inline C —
 // blocking write/read per call over ONE long-lived connection (http-sync-v0: one
-// worker event-loop turn per request, so a blocking roundtrip is acceptable).
+// sprout event-loop turn per request, so a blocking roundtrip is acceptable).
 // Wire frame:
 //   [u32 LE len][ <token> "\n" <json> ]   reply: [u32 LE len][ <json> ]
 // SB_BROKER_PORT / SB_BROKER_TOKEN are set by the supervisor next to $PORT.
 // If SB_BROKER_PORT is unset the shims below are never installed (compile.ts
 // only emits the __sbInstallBindings call when the project declares bindings),
-// so a plain worker is byte-for-byte unchanged.
+// so a plain sprout is byte-for-byte unchanged.
 // ponytail: text values only; still AF_INET loopback, not AF_UNIX. A failed
 // exchange reconnects and resends once — a broker crash between "request applied"
 // and "reply read" can double-apply a non-idempotent op (queue.send, INSERT);
@@ -252,7 +290,7 @@ static int sb_broker_fd = -1;
 static int sb_broker_connect(void) {
   const char* port_s = getenv("SB_BROKER_PORT");
   if (!port_s) return -10;
-  signal(SIGPIPE, SIG_IGN); // a dead broker must yield EPIPE, not kill the worker
+  signal(SIGPIPE, SIG_IGN); // a dead broker must yield EPIPE, not kill the sprout
   int fd = socket(AF_INET, SOCK_STREAM, 0);
   if (fd < 0) return -1;
   int one = 1;
@@ -422,7 +460,7 @@ function __sbMakeD1(dbName) {
 }
 
 // R2: a Cloudflare-shaped object. When `body` is present the sync accessors
-// mirror R2ObjectBody's async ones (a worker may `await` them harmlessly).
+// mirror R2ObjectBody's async ones (a sprout may `await` them harmlessly).
 function __sbR2Object(meta, body) {
   const obj = {
     key: meta.key,
@@ -572,7 +610,7 @@ globalThis.__sbInstallBindings = function (target, bindings) {
   }
 
   // Static assets: env.<ASSETS>.fetch(request) -> broker `assets.get`. The edge
-  // already serves matching files directly; the worker only calls this for paths
+  // already serves matching files directly; the sprout only calls this for paths
   // it wants to own (SPA fallback, auth-gated files). Text assets only — binary
   // files go through the edge (the broker frame is UTF-8 JSON).
   if (bindings.assets) {
@@ -612,13 +650,13 @@ globalThis.__sbInstallBindings = function (target, bindings) {
 };
 
 // ---------------------------------------------------------------------------
-// Durable Objects. The class runs here in the sandboxed worker. There is exactly
-// one worker process per deployment (the supervisor model) and the native-fetch
+// Durable Objects. The class runs here in the sandboxed sprout. There is exactly
+// one sprout process per deployment (the supervisor model) and the native-fetch
 // runtime processes one turn at a time, so calls to a given object id are
 // already serialized — `env.<NS>.get(id).fetch()` invokes the instance directly,
 // no round-trip. Only `state.storage.*` goes to the broker (so object state
-// outlives a worker restart), scoped to (class, id).
-// ponytail: serialization relies on the single worker process; a multi-worker
+// outlives a sprout restart), scoped to (class, id).
+// ponytail: serialization relies on the single sprout process; a multi-sprout
 // deployment needs the broker to hold a per-id lock (cloud). Storage ops are one
 // key at a time; blockConcurrencyWhile just runs the fn.
 
@@ -747,7 +785,19 @@ function __sbTriggerAuthed(request) {
 
 globalThis.__sbEntry = function (handlers, request) {
   const trigger = request.headers.get('x-sb-trigger');
-  if (!trigger) return handlers.fetch(request);
+  if (!trigger) {
+    // #28 — per-invocation CPU time. One fetch turn per process (serial), so the
+    // process CPU delta across the handler is this invocation's CPU. Covers both
+    // sync handlers and async ones (via `.then`); the delta spans the whole turn.
+    // ponytail: serial-turn assumption; revisit if the profile ever allows
+    // concurrent in-process requests.
+    const __t0 = __sbCpuMs();
+    const __res = handlers.fetch(request);
+    if (__res && typeof __res.then === 'function') {
+      return __res.then(function (resolved) { return __sbTagCpu(resolved, __t0); });
+    }
+    return __sbTagCpu(__res, __t0);
+  }
   if (!__sbTriggerAuthed(request)) return new Response('forbidden', { status: 403 });
 
   if (trigger === 'scheduled') {

package/src/report.ts

@@ -1,8 +1,11 @@
+import { readFileSync } from "node:fs";
 import { gzipSync } from "bun";
 import type { SproutboatConfig } from "./config";
 import type { ArtifactManifest } from "./manifest";
+import { bold, dim, leaf, sprout } from "./style";
 
-const CLI_VERSION = "0.1.0";
+// Read from package.json so the banner never drifts from the published version.
+const CLI_VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
 
 function bytes(n: number): string {
   if (n < 1024) return `${n} B`;
@@ -11,55 +14,75 @@ function bytes(n: number): string {
   return `${(kib / 1024).toFixed(2)} MiB`;
 }
 
-/** Minimal box table. `align` marks columns to right-pad-left (numbers). */
+/** Minimal box table with a green frame. `align` marks columns to right-pad-left (numbers). */
 function table(headers: string[], rows: string[][], align: boolean[] = []): string {
   const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
-  const line = (l: string, m: string, r: string) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
-  const row = (cells: string[]) =>
-    "│ " + cells.map((c, i) => (align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]))).join(" │ ") + " │";
-  return [line("┌", "┬", "┐"), row(headers), line("├", "┼", "┤"), ...rows.map(row), line("└", "┴", "┘")].join("\n");
+  const rule = (l: string, m: string, r: string) => leaf(l + widths.map((w) => "─".repeat(w + 2)).join(m) + r);
+  const row = (cells: string[], head = false) =>
+    leaf("│ ") + cells.map((c, i) => {
+      const cell = align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]);
+      return head ? bold(cell) : cell;
+    }).join(leaf(" │ ")) + leaf(" │");
+  return [rule("┌", "┬", "┐"), row(headers, true), rule("├", "┼", "┤"), ...rows.map((r) => row(r)), rule("└", "┴", "┘")].join("\n");
+}
+
+/** Every binding the compiled sprout will see, flattened to (name, type, detail) rows. */
+function bindingRows(config: SproutboatConfig): string[][] {
+  const rows: string[][] = [];
+  for (const [name, value] of Object.entries(config.vars ?? {})) rows.push([`env.${name}`, "var", JSON.stringify(value)]);
+  const list = (names: string[] | undefined, type: string, detail = "") => {
+    for (const name of names ?? []) rows.push([`env.${name}`, type, detail]);
+  };
+  list(config.kv_namespaces, "kv");
+  list(config.secrets, "secret", "value withheld — set with `sproutboat secrets`");
+  list(config.d1_databases, "d1");
+  list(config.r2_buckets, "r2");
+  list(config.queues, "queue");
+  list(config.analytics_engine_datasets, "analytics");
+  for (const [name, className] of Object.entries(config.durable_objects ?? {})) rows.push([`env.${name}`, "durable object", className]);
+  for (const host of config.outbound ?? []) rows.push([`fetch()`, "outbound", host]);
+  for (const cron of config.triggers?.crons ?? []) rows.push([`scheduled()`, "cron", cron]);
+  if (config.assets?.binding) rows.push([`env.${config.assets.binding}`, "assets", config.assets.directory ?? ""]);
+  return rows;
 }
 
 /**
- * Wrangler-shaped build/deploy summary. Prints what the artifact contains, its
- * upload size, and the bindings the handler will see. Returns nothing.
+ * Wrangler-shaped build/deploy summary: what the artifact contains, its upload
+ * size, and every binding the handler will see. Returns nothing.
  */
 export function printDeployReport(
   config: SproutboatConfig,
   manifest: ArtifactManifest,
-  worker: Uint8Array,
+  sproutBin: Uint8Array,
   manifestBytes: number,
 ): void {
-  const gz = gzipSync(Uint8Array.from(worker)).length;
-  const total = worker.length + manifestBytes;
+  const gz = gzipSync(Uint8Array.from(sproutBin)).length;
+  const total = sproutBin.length + manifestBytes;
 
-  console.log(`\n🌱 sproutboat ${CLI_VERSION}`);
-  console.log("─".repeat(19));
-  console.log(`Compiled ${manifest.project} with Porffor ${manifest.porfforVersion}`);
-  console.log(`  toolchain  ${manifest.buildImage}`);
-  console.log(`  compat     ${config.compatibility_date}`);
+  console.log(`\n${sprout("🌱")} ${bold(leaf(`sproutboat ${CLI_VERSION}`))}`);
+  console.log(leaf("─".repeat(19)));
+  console.log(`Compiled ${bold(manifest.project)} with Porffor ${manifest.porfforVersion}`);
+  console.log(dim(`  toolchain  ${manifest.buildImage}`));
+  console.log(dim(`  compat     ${config.compatibility_date}`));
   console.log();
 
-  console.log("Artifact:");
+  console.log(bold("Artifact"));
   console.log(table(
     ["File", "Type", "Size"],
     [
-      ["worker", manifest.runtime, bytes(worker.length)],
+      ["sprout", manifest.runtime, bytes(sproutBin.length)],
       ["manifest.json", "json", bytes(manifestBytes)],
     ],
     [false, false, true],
   ));
-  console.log(`Total upload: ${bytes(total)}  (worker gzip: ${bytes(gz)})`);
+  console.log(`Total upload: ${bold(bytes(total))}  ${dim(`(sprout gzip: ${bytes(gz)})`)}`);
   console.log();
 
-  const vars = Object.entries(config.vars ?? {});
-  console.log("Bindings the handler will see:");
-  if (vars.length === 0) {
-    console.log("  (none — add [vars] to sproutboat.jsonc)");
+  const rows = bindingRows(config);
+  console.log(bold("Bindings the handler will see"));
+  if (rows.length === 0) {
+    console.log(dim("  (none — add vars / kv_namespaces / secrets / … to sproutboat.jsonc)"));
   } else {
-    console.log(table(
-      ["Binding", "Type", "Value"],
-      vars.map(([k, v]) => [`env.${k}`, "var", JSON.stringify(v)]),
-    ));
+    console.log(table(["Binding", "Type", "Detail"], rows));
   }
 }

package/src/style.ts

@@ -0,0 +1,18 @@
+/**
+ * Green/leaf terminal styling. Every helper is a no-op when stdout is not a TTY
+ * or NO_COLOR is set (https://no-color.org), so piped/CI output stays plain.
+ */
+const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code: string) => (text: string): string => (enabled ? `\x1b[${code}m${text}\x1b[0m` : text);
+
+export const leaf = paint("32");        // green — headings, structure, the accent
+export const sprout = paint("92");      // bright green — success
+export const dim = paint("2");          // secondary detail
+export const bold = paint("1");
+export const amber = paint("33");       // warnings
+export const rose = paint("31");        // errors
+
+/** "✓ message" with a green tick. */
+export const ok = (message: string): string => `${sprout("✓")} ${message}`;
+/** "▸ message" with a green marker — section headers. */
+export const step = (message: string): string => `${leaf("▸")} ${bold(message)}`;

package/src/surface.ts

@@ -10,13 +10,15 @@ export type Command = { name: string; args: string; summary: string };
 export const COMMANDS: readonly Command[] = [
   { name: "init", args: "[name]", summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
   { name: "check", args: "[project-dir]", summary: "Validate the config and entry point without building." },
-  { name: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch worker (Porffor + Zig)." },
-  { name: "deploy", args: "[project-dir] [--dry-run] [--artifact <dir>]", summary: "Build (unless --artifact), print the report, upload. --dry-run stops before upload." },
+  { name: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
+  { name: "deploy", args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]", summary: "Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check." },
   { name: "login", args: "[--api-url <url>] [--token <token>]", summary: "Device-code browser flow, or store <token> for <url> directly." },
-  { name: "tail", args: "[project-dir]", summary: "Print the project's recent request logs." },
+  { name: "tail", args: "[project-dir] [--sprout]", summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
   { name: "versions", args: "list [project-dir]", summary: "List the project's deployed versions." },
   { name: "rollback", args: "<version-id> [project-dir]", summary: "Re-activate a previous version." },
-  { name: "delete", args: "--yes [project-dir]", summary: "Delete the project and every version." },
+  { name: "domains", args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
+  { name: "secrets", args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
+  { name: "delete", args: "[project-dir] [--name <project>] --yes", summary: "Delete the project, every version, and its route." },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -27,14 +29,15 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SPROUTBOAT_ZIG", purpose: "Path to a Zig binary to use instead of downloading the pinned one." },
   { name: "SPROUTBOAT_UWS_TARBALL", purpose: "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)." },
   { name: "SPROUTBOAT_COMPILE_TIMEOUT_MS", purpose: "Porffor compile timeout in ms (default 600000)." },
-  { name: "SPROUTBOAT_VARS_JSON", purpose: "JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the worker module." },
+  { name: "SPROUTBOAT_VARS_JSON", purpose: "JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the sprout module." },
   { name: "SPROUTBOAT_BINDINGS_JSON", purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line." },
   { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
+  { name: "NO_COLOR", purpose: "When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY." },
   { name: "XDG_CONFIG_HOME", purpose: "Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset." },
   { name: "PORFFOR_VERSION", purpose: "Override the Porffor identity string recorded in the manifest." },
-  { name: "SB_BROKER_PORT", purpose: "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)." },
-  { name: "SB_BROKER_TOKEN", purpose: "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)." },
-  { name: "SB_WORKER_URL", purpose: "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." },
+  { name: "SB_BROKER_PORT", purpose: "Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs)." },
+  { name: "SB_BROKER_TOKEN", purpose: "Per-deployment auth token the sprout sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT)." },
+  { name: "SB_SPROUT_URL", purpose: "http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it." },
 ];
 
 /** One-line usage string, e.g. for `usage()` and `--help`. */

package/src/toolchain.ts

@@ -24,6 +24,10 @@ const ZIG_SHA256: Record<string, string> = {
 
 // Pinned Porffor identity — must match the `porffor` entry in package.json
 // (`github:CanadaHonk/porffor#alpha-4`, commit a415d19). PORFFOR_VERSION overrides.
+// When bumping this pin (#55): run the monorepo's `bun run diff` against the
+// frozen reference handlers and update its COMPAT.md for any new mismatch before
+// releasing — the alpha compiler's output can shift between pins. Checked by
+// hand at bump time, not in CI.
 const PORFFOR_CHANNEL = "alpha-4";
 const PORFFOR_COMMIT = "a415d19";
 

package/src/wrap.ts

@@ -1,5 +1,5 @@
 /**
- * The build-independent half of worker compilation: the binding/trigger wrapper
+ * The build-independent half of sprout compilation: the binding/trigger wrapper
  * that turns a user's `export default { fetch }` into a native-fetch module, plus
  * the `Bindings` shape and the `SPROUTBOAT_*_JSON` env readers.
  *
@@ -54,12 +54,12 @@ function hasBindings(b: Bindings): boolean {
  * `__sbEntry` (HTTP → `handlers.fetch`; `x-sb-trigger` → scheduled / queue / DO).
  *
  * With no bindings and no `scheduled`/`queue`/DO the output behaves exactly like
- * a plain `export default { fetch }` worker.
+ * a plain `export default { fetch }` sprout.
  *
  * `port` is only the baked fallback in `export default { port }`; the runtime
  * reads `$PORT` first. The monorepo's bench path overrides it.
  *
- * ponytail: the worker process is long-lived, so a handler that mutates `env`
+ * ponytail: the sprout process is long-lived, so a handler that mutates `env`
  * leaks that change to later requests. Freeze upstream once Porffor supports
  * Object.freeze in native mode.
  */