sproutboat 0.3.0 → 0.4.0

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.0 · 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). |
+| `build` | `[project-dir]` | Cross-compile the native-fetch sprout (Porffor + Zig). |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>]` | Build (unless --artifact), print the report, upload. --dry-run stops before upload. |
 | `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
 | `tail` | `[project-dir]` | Print the project's recent request logs. |
 | `versions` | `list [project-dir]` | List the project's deployed versions. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
+| `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` | `--yes [project-dir]` | Delete the project and every version. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] | login [--api-url <url>] [--token <token>] | tail [project-dir] | versions list [project-dir] | rollback <version-id> [project-dir] | delete --yes [project-dir]>
+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] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete --yes [project-dir]>
 ```
 
 ## Environment variables
@@ -32,14 +34,14 @@ 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). |
 | `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.0",
   "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

@@ -70,6 +70,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;
@@ -166,8 +176,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 +186,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) {
@@ -198,7 +208,26 @@ async function deploy(args: string[]) {
   }
   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 },
@@ -209,6 +238,12 @@ async function deploy(args: string[]) {
   if (!deployed) fail("deployment response did not include a URL");
   console.log(`\nDeployed ${projectName}`);
   console.log(`  ${deployed.url}`);
+  const drift = parsePorfforDrift(body);
+  if (drift) {
+    console.warn(`\n! Porffor pin changed: ${drift.from} -> ${drift.to}`);
+    console.warn(`  The previous live version stays frozen at ${drift.from}; this one is built with ${drift.to}.`);
+    console.warn(`  The alpha compiler's output can differ between pins (see COMPAT.md) — roll back if this version misbehaves.`);
+  }
 }
 
 function parseLoginArgs(args: string[]) {
@@ -294,6 +329,89 @@ 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 };
+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(`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(`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()]);
@@ -316,6 +434,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

@@ -27,11 +27,11 @@ function table(headers: string[], rows: string[][], align: boolean[] = []): stri
 export function printDeployReport(
   config: SproutboatConfig,
   manifest: ArtifactManifest,
-  worker: Uint8Array,
+  sprout: Uint8Array,
   manifestBytes: number,
 ): void {
-  const gz = gzipSync(Uint8Array.from(worker)).length;
-  const total = worker.length + manifestBytes;
+  const gz = gzipSync(Uint8Array.from(sprout)).length;
+  const total = sprout.length + manifestBytes;
 
   console.log(`\n🌱 sproutboat ${CLI_VERSION}`);
   console.log("─".repeat(19));
@@ -44,12 +44,12 @@ export function printDeployReport(
   console.log(table(
     ["File", "Type", "Size"],
     [
-      ["worker", manifest.runtime, bytes(worker.length)],
+      ["sprout", manifest.runtime, bytes(sprout.length)],
       ["manifest.json", "json", bytes(manifestBytes)],
     ],
     [false, false, true],
   ));
-  console.log(`Total upload: ${bytes(total)}  (worker gzip: ${bytes(gz)})`);
+  console.log(`Total upload: ${bytes(total)}  (sprout gzip: ${bytes(gz)})`);
   console.log();
 
   const vars = Object.entries(config.vars ?? {});

package/src/surface.ts

@@ -10,12 +10,14 @@ 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: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch sprout (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: "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: "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: "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: "--yes [project-dir]", summary: "Delete the project and every version." },
 ];
 
@@ -27,14 +29,14 @@ 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: "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.
  */