sproutboat 0.11.10 → 0.11.12

package/CHANGELOG.md

@@ -8,6 +8,28 @@ a breaking change.
 Reconstructed from git history on 2026-09-03 for everything through v0.4.11;
 maintained going forward by the `release` skill.
 
+## [0.11.12] - 2026-09-24
+
+### Changed
+- Porffor alpha 9 handles ESM modules without the external esbuild executable.
+  The CLI now requires `@sproutboat/toolchain@^0.4.12`, runtime `^0.12.1`,
+  and wire `^0.9.1`.
+  Removed the CLI's esbuild dependency, platform binary copies, and compile-time
+  PATH lookup. Handler validation and shimming still use Bun's built-in bundler.
+  The required `esbuildVersion` manifest field remains for older artifact
+  readers and now records `unused`.
+- Local `dev` rebuilds keep a stable generated entry path for each process, so
+  Porffor alpha 9 can reuse unchanged compiled C units. In a local `hello`
+  handler-edit comparison, compilation took 549 ms with the stable path versus
+  1,505 ms with changing paths. Candidate binaries remain isolated.
+
+## [0.11.11] - 2026-09-24
+### Fixed
+- Updated the native runtime to `0.12.0` so repeated HMAC signing uses the raw
+  digest bytes between rounds, matching WebCrypto and existing password hashes.
+- Updated the toolchain to `0.4.11` so `Uint8Array.from({ length: 16 }, mapFn)`
+  produces the intended key bytes in standalone native builds.
+- Added the two-round HMAC vector to broker and standalone conformance checks.
 ## [0.11.10] - 2026-09-18
 ### Changed
 - Bumped `@sproutboat/toolchain` to `0.4.10`, pinning Porffor to the
@@ -588,7 +610,9 @@ its own package.
 - Renamed the package to `sproutboat` (was `@sproutboat/cli`); dropped the
   `sprout` bin alias in favour of a user-defined shell alias.
 
-[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.9...HEAD
+[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.12...HEAD
+[0.11.12]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.11...v0.11.12
+[0.11.11]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.10...v0.11.11
 [0.11.10]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.9...v0.11.10
 [0.11.9]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.8...v0.11.9
 [0.11.8]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.7...v0.11.8

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.11.10 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.11.12 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -29,9 +29,10 @@
 | `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
 | `logout` | `[--api-url <url>]` | Forget the stored credential for the active endpoint, or for <url>. |
 | `whoami` | — | Show the active endpoint and the account the stored token belongs to. |
+| `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
 ```
 
 ## Environment variables
@@ -57,6 +58,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | `NO_COLOR` | When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY. |
 | `SPROUTBOAT_NO_UPDATE_CHECK` | When set, skips the once-a-day npm check for a newer `sproutboat` release (also skipped when CI is set). |
 | `XDG_CONFIG_HOME` | Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset. |
+| `SHELL` | Picks the default shell for `complete` with no argument (bash/zsh/fish). |
 | `PORFFOR_VERSION` | Override the Porffor identity string recorded in the manifest. |
 | `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). |
@@ -74,7 +76,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | | |
 | --- | --- |
 | Zig | `0.16.0` (`zig cc -target x86_64-linux-musl`, static) |
-| Provenance stamp | `zig-musl/0.16.0+porffor/8f01541+uws/360c276d` |
+| Provenance stamp | `zig-musl/0.16.0+porffor/de4eb58+uws/360c276d` |
 | Artifact schema | `2` |
 | Runtime | `native-fetch` |
 | Capability profile | `http-sync-v0` |

package/THIRD_PARTY_NOTICES.md

@@ -6,10 +6,9 @@ to its upstream source.
 
 | Component | Version or revision | Distribution role | License | Source |
 | --- | --- | --- | --- | --- |
-| Porffor | `a415d194e74948f0ac32b9d608153ea8720c71fd` | Acquired on first application build | MIT | https://github.com/CanadaHonk/porffor |
+| Porffor | `de4eb588264885b3a1596f75010e371a2052033f` | Acquired on first application build | MIT | https://github.com/CanadaHonk/porffor |
 | Zig | `0.16.0` | Acquired cross-compiler | MIT | https://ziglang.org |
 | uWebSockets and uSockets | `360c276d609d59af56ae6932adb95154ace9f15f` | Embedded source and static archive | Apache-2.0 | https://github.com/uNetworking/uWebSockets |
-| esbuild | `0.28.2` | Embedded platform executable | MIT | https://esbuild.github.io |
 | SQLite | `3.50.4` | Acquired for standalone builds | Public domain | https://sqlite.org |
 | BearSSL | `0.6` | Acquired for standalone builds | MIT | https://bearssl.org |
 
@@ -17,7 +16,7 @@ to its upstream source.
 
 | Component | SHA-256 |
 | --- | --- |
-| Porffor source archive | `677779c8be49efc28686378f665cd6fc4a8a2dd81e7b15a89298103ded960829` |
+| Porffor source archive | `1a62187a93356b36cb6ac703ce9770c8917e4fa65545fd7c33ee8a180ae5a4c9` |
 | Embedded uWebSockets archive | `e83736f3f8cf9d56a1ebe6ea61625a7af12386763374d47c14cff472ada7484a` |
 | SQLite amalgamation archive | `1d3049dd0f830a025a53105fc79fd2ab9431aea99e137809d064d8ee8356b032` |
 | BearSSL source archive | `6705bba1714961b41a728dfc5debbe348d2966c117649392f8c8139efc83ff14` |
@@ -25,5 +24,4 @@ to its upstream source.
 
 The complete Apache-2.0 notice for uWebSockets and uSockets is retained in the
 embedded source archive. Porffor and BearSSL retain their MIT notices in the
-source archives acquired at the revisions above. esbuild's MIT notice is
-available from its upstream distribution.
+source archives acquired at the revisions above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.11.10",
+  "version": "0.11.12",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -62,12 +62,11 @@
   },
   "dependencies": {
     "@sproutboat/artifact": "^0.2.0",
-    "@sproutboat/assets": "^0.2.0",
-    "@sproutboat/config": "^0.3.0",
-    "@sproutboat/runtime": "^0.9.6",
-    "@sproutboat/toolchain": "^0.4.10",
-    "@sproutboat/wire": "^0.7.0",
-    "esbuild": "^0.28.2"
+    "@sproutboat/assets": "^0.3.0",
+    "@sproutboat/config": "^0.4.0",
+    "@sproutboat/runtime": "^0.12.1",
+    "@sproutboat/toolchain": "^0.4.12",
+    "@sproutboat/wire": "^0.9.1"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.81.0",
@@ -78,10 +77,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.11.10",
-    "@sproutboat/cli-darwin-x64": "0.11.10",
-    "@sproutboat/cli-linux-arm64": "0.11.10",
-    "@sproutboat/cli-linux-x64": "0.11.10"
+    "@sproutboat/cli-darwin-arm64": "0.11.12",
+    "@sproutboat/cli-darwin-x64": "0.11.12",
+    "@sproutboat/cli-linux-arm64": "0.11.12",
+    "@sproutboat/cli-linux-x64": "0.11.12"
   },
   "engines": {
     "node": ">=18"

package/scripts/build-cli.ts

@@ -15,7 +15,7 @@
  * GitHub's only x64 macOS image (`macos-13`) routinely sits queued for half an
  * hour while every other leg finishes in one minute.
  */
-import { chmod, copyFile, mkdir } from "node:fs/promises";
+import { chmod, copyFile, mkdir, rm } from "node:fs/promises";
 import { resolve } from "node:path";
 import { ensureZigArchive, type ZigPlatform } from "../src/toolchain";
 
@@ -39,49 +39,11 @@ function hostTarget(): Target {
 
 const root = resolve(import.meta.dir, "..");
 
-/** esbuild ships one binary per platform (`@esbuild/<os>-<arch>`); a cross
- * target's copy is never installed locally (npm/bun refuse it — the package
- * declares `os`/`cpu` and gets skipped for any other host), so fetch that
- * platform's tarball from the registry instead, same shape as ensureZig's
- * prebuilt-archive fetches. */
-async function esbuildBinaryFor(target: Target): Promise<string> {
-  const host = hostTarget();
-  if (target.platform === host.platform && target.arch === host.arch) {
-    try {
-      return Bun.resolveSync(`@esbuild/${target.platform}-${target.arch}/bin/esbuild`, import.meta.dir);
-    } catch {
-      throw new Error("host esbuild binary is missing; run bun install first");
-    }
-  }
-  // SAFETY: package.json is this repo's own manifest, with a required esbuild dependency entry.
-  const pkg = (await Bun.file(resolve(root, "package.json")).json()) as { dependencies: { esbuild: string } };
-  const version = pkg.dependencies.esbuild.replace(/^[\^~]/, "");
-  const name = `${target.platform}-${target.arch}`;
-  const cacheDir = resolve(
-    process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? `${process.env.HOME}/.cache/sproutboat`,
-    `esbuild-${version}-${name}`,
-  );
-  const cached = resolve(cacheDir, "esbuild");
-  if (await Bun.file(cached).exists()) return cached;
-  const res = await fetch(`https://registry.npmjs.org/@esbuild/${name}/-/${name}-${version}.tgz`);
-  if (!res.ok) throw new Error(`could not fetch @esbuild/${name}@${version}: HTTP ${res.status}`);
-  const tarPath = resolve(cacheDir, "esbuild.tgz");
-  await mkdir(cacheDir, { recursive: true });
-  await Bun.write(tarPath, await res.arrayBuffer());
-  const untar = Bun.spawn(["tar", "-xzf", tarPath, "-C", cacheDir, "--strip-components=2", "package/bin/esbuild"], {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
-  if (code !== 0) throw new Error(`could not extract @esbuild/${name}: ${err.trim()}`);
-  await chmod(cached, 0o755);
-  return cached;
-}
-
 async function buildOne(target: Target): Promise<void> {
   const packageDir = resolve(root, "platform-packages", `${target.platform}-${target.arch}`);
   const out = resolve(packageDir, "bin", "sproutboat");
   await mkdir(resolve(out, ".."), { recursive: true });
+  await rm(resolve(packageDir, "bin", "esbuild"), { force: true });
   // SAFETY: package.json is this release's manifest and npm requires its version.
   const version = ((await Bun.file(resolve(root, "package.json")).json()) as { version: string }).version;
   // SAFETY: every checked-in platform package manifest owns a required string version.
@@ -103,9 +65,6 @@ async function buildOne(target: Target): Promise<void> {
     { cwd: root, stdout: "inherit", stderr: "inherit" },
   );
   if ((await child.exited) !== 0) throw new Error(`compile failed for ${target.platform}-${target.arch}`);
-  const esbuild = await esbuildBinaryFor(target);
-  const packagedEsbuild = resolve(packageDir, "bin", "esbuild");
-  await copyFile(esbuild, packagedEsbuild);
   // The compressed archive (~50 MB), not the ~400 MB extracted install: Zig's
   // lib/ carries libc/libc++ sources for every target it can cross-compile to,
   // which only matters once, on extract. `ensureZig` (src/toolchain.ts) looks
@@ -114,7 +73,6 @@ async function buildOne(target: Target): Promise<void> {
   // same shape as the vendored uWebSockets archive.
   await copyFile(await ensureZigArchive(target.zigPlatform), resolve(packageDir, "bin", "zig.tar.xz"));
   await copyFile(resolve(root, "THIRD_PARTY_NOTICES.md"), resolve(packageDir, "THIRD_PARTY_NOTICES.md"));
-  await chmod(packagedEsbuild, 0o755);
   await chmod(out, 0o755);
 }
 

package/src/build.ts

@@ -47,6 +47,8 @@ export type BuildInput = {
   reuseSproutPath?: string;
   /** An isolated artifact directory, used by dev candidates to avoid mixing snapshots. */
   outputDirectory?: string;
+  /** Stable compiler input used only by the local dev loop. */
+  generatedPath?: string;
 };
 
 export type BuildOutput = {
@@ -171,10 +173,18 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     bakedAssets = { manifest, files };
   }
 
+  // Hoisted above the compile: #126 bakes it into the binary, and the manifest
+  // records the same instant rather than a slightly later one.
+  const builtAt = new Date().toISOString();
+  const versionMetadata = input.config.version_metadata
+    ? { binding: input.config.version_metadata, id: artifactId, tag: input.config.name, timestamp: builtAt }
+    : undefined;
+
   if (input.reuseSproutPath) await cp(input.reuseSproutPath, sproutPath);
   else
     await compileSprout({
       sourcePath: input.sourcePath,
+      generatedPath: input.generatedPath,
       source: input.source,
       outPath: sproutPath,
       vars: input.config.vars ?? {},
@@ -188,6 +198,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       extraLink,
       extraCflags,
       optimize: input.optimize,
+      versionMetadata,
     });
 
   const sprout = await readFile(sproutPath);
@@ -204,7 +215,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     sourceHash,
     binaryHash: digest(sprout),
     binarySize: (await stat(sproutPath)).size,
-    builtAt: new Date().toISOString(),
+    builtAt,
   };
   await writeFile(resolve(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
   // Bindings live beside the manifest, not in it: the artifact manifest schema is

package/src/bundle.ts

@@ -1,9 +1,9 @@
 /**
  * #89 — bundle the handler before Porffor sees it.
  *
- * Porffor compiles one self-contained module, so until now a project was one
- * file with no imports: no router, no validation library, no SDK, no splitting
- * a codebase in two. Bundling first lifts that without touching the compiler.
+ * Porffor alpha 9 supports ESM imports. We still bundle first so capability
+ * validation sees every dependency and the runtime wrapper receives one
+ * controlled default export.
  *
  * Bun's bundler resolves relative imports across the project and bare
  * specifiers out of the project's own `node_modules`, then emits a single ESM

package/src/compile.ts

@@ -10,7 +10,6 @@
  * unusable it stops with its specific integrity or archive error. Contributors
  * may explicitly opt into Porffor's source fallback.
  */
-import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
@@ -50,6 +49,8 @@ const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 6
 
 export type CompileInput = {
   sourcePath: string;
+  /** Stable compiler input for dev rebuilds, independent of the candidate binary path. */
+  generatedPath?: string;
   /** The bundled module (#89). Falls back to reading `sourcePath` verbatim. */
   source?: string;
   outPath: string;
@@ -80,6 +81,8 @@ export type CompileInput = {
   optimize?: "dev" | "release";
   /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
   zigBin?: string;
+  /** #126 — `env.<binding> = { id, tag, timestamp }`, baked directly into the module. */
+  versionMetadata?: { binding: string; id: string; tag: string; timestamp: string };
   /**
    * `linux-x86_64` (default) cross-compiles the static musl binary every box
    * runs. `host` compiles for the machine doing the build (#62) so `sproutboat
@@ -193,7 +196,8 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   // OS may still be executing. The linker cannot overwrite either, so clear it
   // first rather than failing with "can't write output file".
   await rm(input.outPath, { force: true });
-  const generatedPath = resolve(outDir, "sprout.generated.js");
+  const generatedPath = input.generatedPath ?? resolve(outDir, "sprout.generated.js");
+  await mkdir(dirname(generatedPath), { recursive: true });
   const [source, prelude] = await Promise.all([
     input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
     loadPrelude(input.transport ?? "broker"),
@@ -210,6 +214,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
       input.appName,
       input.assets,
       input.transport,
+      input.versionMetadata,
     ),
   );
 
@@ -219,22 +224,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   // below instead and has no zigBin to contribute here.
   const zigDir = input.zigBin ? `${dirname(input.zigBin)}:` : "";
   const hostCompiler = input.target === "host" ? await resolveHostCompiler() : undefined;
-  // The per-platform binary ships esbuild next to it; a compiled build finds it
-  // there. Running from the npm package under Bun, `process.execPath` is Bun
-  // itself and `npm i -g` puts no dependency `.bin` on PATH, so resolve the
-  // esbuild dependency directly. `Bun.which` is the last resort.
-  const packagedEsbuild = resolve(dirname(process.execPath), "esbuild");
-  let esbuild: string | null = existsSync(packagedEsbuild) ? packagedEsbuild : null;
-  if (!esbuild) {
-    try {
-      esbuild = Bun.resolveSync("esbuild/bin/esbuild", import.meta.dir);
-    } catch {
-      esbuild = null;
-    }
-  }
-  esbuild ??= Bun.which("esbuild");
-  if (!esbuild) throw new Error("esbuild could not be located; install it or reinstall sproutboat");
-  const path = `${zigDir}${dirname(esbuild)}:${process.env.PATH ?? ""}`;
+  const path = `${zigDir}${process.env.PATH ?? ""}`;
   const command = PACKAGED
     ? [process.execPath, "__porffor", launcher]
     : [process.execPath, resolve(import.meta.dir, "main.ts"), "__porffor", launcher];

package/src/credentials.ts

@@ -59,23 +59,37 @@ export async function activeApiUrl(): Promise<string | undefined> {
   return (await readCredentials()).activeApiUrl;
 }
 
-/** #79 `logout`: drop one endpoint's token. Returns false when none was stored. */
-export async function forgetToken(apiUrl: string): Promise<boolean> {
+/**
+ * #79 `logout`: drop one endpoint's token. Returns `removed: false` when none
+ * was stored. baronunread/sproutboat#204 — used to repoint `activeApiUrl` to
+ * an arbitrary surviving profile chosen by object key order; now it just
+ * clears the active endpoint, so the next command falls through to
+ * `resolveApiUrl()`'s documented default instead of a silently-picked one.
+ */
+export async function forgetToken(apiUrl: string): Promise<{ removed: boolean; activeApiUrl?: string }> {
   const credentials = await readCredentials();
-  if (!credentials.profiles[apiUrl]) return false;
+  if (!credentials.profiles[apiUrl]) return { removed: false };
   delete credentials.profiles[apiUrl];
-  if (credentials.activeApiUrl === apiUrl) {
-    credentials.activeApiUrl = Object.keys(credentials.profiles)[0];
-  }
+  if (credentials.activeApiUrl === apiUrl) credentials.activeApiUrl = undefined;
   await writeCredentials(credentials);
-  return true;
+  return { removed: true, activeApiUrl: credentials.activeApiUrl };
 }
 
-export async function saveToken(apiUrl: string, token: string): Promise<void> {
+/**
+ * baronunread/sproutboat#204 — used to unconditionally repoint the
+ * machine-wide active endpoint to whatever was just logged into, so logging
+ * into a local dev control plane for one project silently became the deploy
+ * target for every unrelated project on the machine. Now the active endpoint
+ * is only set the first time (nothing saved yet); a later login to a second
+ * endpoint keeps the existing active endpoint and reports it, so the caller
+ * can say so instead of silently switching.
+ */
+export async function saveToken(apiUrl: string, token: string): Promise<{ activeApiUrl: string }> {
   const credentials = await readCredentials();
   credentials.profiles[apiUrl] = { token };
-  credentials.activeApiUrl = apiUrl;
+  if (!credentials.activeApiUrl) credentials.activeApiUrl = apiUrl;
   await writeCredentials(credentials);
+  return { activeApiUrl: credentials.activeApiUrl };
 }
 
 /** Atomic 0600 write of the whole credentials file. */

package/src/dev.ts

@@ -11,6 +11,7 @@
  * project, one port.
  */
 import { existsSync, watch, type FSWatcher } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { connect } from "node:net";
 import { dirname, resolve } from "node:path";
@@ -21,6 +22,7 @@ import { amber, dim, leaf, ok } from "./style";
 import type { SproutboatConfig } from "./config";
 
 const RESTART_DEBOUNCE_MS = 120;
+const DEV_COMPILE_SESSION = randomUUID();
 
 export type DevInput = {
   projectDir: string;
@@ -121,6 +123,14 @@ async function start(input: DevInput, port: number): Promise<Running> {
       optimize: "dev",
       reuseSproutPath: input.reuseSproutPath,
       outputDirectory: candidateDir,
+      // Alpha 9 keys its C-unit cache by the entry's absolute path. Keep that
+      // path fixed across saves while each candidate keeps its own binary.
+      generatedPath: resolve(
+        input.projectDir,
+        ".sproutboat/dev-compile",
+        `${process.pid}-${DEV_COMPILE_SESSION}`,
+        "sprout.generated.js",
+      ),
     });
   } catch (error) {
     await rm(candidateDir, { recursive: true, force: true });

package/src/main.ts

@@ -14,7 +14,7 @@ import { buildStandalone } from "./standalone-build";
 import { hostTarget, validateManifest, type ArtifactManifest } from "./manifest";
 import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
-import { helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type StorageProduct } from "./surface";
+import { CLI_NAME, COMMANDS, helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type StorageProduct } from "./surface";
 import { notifyIfOutdated } from "./update-check";
 import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
@@ -35,6 +35,26 @@ if (internalModeAt > 0) {
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
 
+type ApiUrlSource = "SPROUTBOAT_API_URL" | "--api-url" | "saved active endpoint" | "default";
+
+/**
+ * baronunread/sproutboat#204 — the single place `defaultApiUrl` and
+ * `activeApiUrl()` are read. Used to be implemented three different ways
+ * across `apiCredentials()`, `whoami()` and `parseLoginArgs()`, none of which
+ * told the user which endpoint it picked; `whoami` could report "not logged
+ * in" on a machine where `deploy` would happily target prod. Precedence: an
+ * explicit `--api-url` flag, then `SPROUTBOAT_API_URL`, then the saved active
+ * endpoint, then the default.
+ */
+async function resolveApiUrl(explicitApiUrl?: string): Promise<{ apiUrl: string; source: ApiUrlSource }> {
+  if (explicitApiUrl) return { apiUrl: explicitApiUrl.replace(/\/$/, ""), source: "--api-url" };
+  const envUrl = process.env.SPROUTBOAT_API_URL;
+  if (envUrl) return { apiUrl: envUrl.replace(/\/$/, ""), source: "SPROUTBOAT_API_URL" };
+  const saved = await activeApiUrl();
+  if (saved) return { apiUrl: saved.replace(/\/$/, ""), source: "saved active endpoint" };
+  return { apiUrl: defaultApiUrl, source: "default" };
+}
+
 /** Warn at most once per run: every API response carries the headers, and one
  *  command makes several calls. */
 let skewWarned = false;
@@ -407,10 +427,15 @@ async function provisionBindings(directory = process.cwd()): Promise<void> {
 
 /** #79 — wrangler parity: drop the stored credential for an endpoint. */
 async function logout(args: string[]) {
-  const { apiUrl } = parseLoginArgs(args);
-  console.log(
-    (await forgetToken(apiUrl)) ? ok(`forgot the credential for ${apiUrl}`) : `no stored credential for ${apiUrl}`,
-  );
+  const { apiUrl } = await parseLoginArgs(args);
+  const result = await forgetToken(apiUrl);
+  if (!result.removed) {
+    console.log(`no stored credential for ${apiUrl}`);
+    return;
+  }
+  console.log(ok(`forgot the credential for ${apiUrl}`));
+  if (result.activeApiUrl === undefined)
+    console.log(dim("no active endpoint remains — the next command falls through to the default"));
 }
 
 /**
@@ -419,13 +444,9 @@ async function logout(args: string[]) {
  * works rather than only reporting what is on disk.
  */
 async function whoami() {
-  const apiUrl = process.env.SPROUTBOAT_API_URL || (await activeApiUrl());
-  if (!apiUrl) {
-    console.log("not logged in — run `sproutboat login`");
-    return;
-  }
+  const { apiUrl, source } = await resolveApiUrl();
   const token = process.env.SPROUTBOAT_TOKEN || (await savedToken(apiUrl));
-  console.log(`endpoint  ${apiUrl}`);
+  console.log(`endpoint  ${apiUrl}  (${source})`);
   if (!token) {
     console.log(`account   ${dim("no stored token — run `sproutboat login`")}`);
     return;
@@ -489,7 +510,8 @@ async function deploy(args: string[]) {
     console.log("\n--dry-run: not uploading.");
     return;
   }
-  const { apiUrl, token } = await apiCredentials();
+  const { apiUrl, token, source } = await apiCredentials();
+  console.log(`endpoint  ${apiUrl}  (${source})`);
   const form = new FormData();
   form.set("manifest", new File([await manifest.arrayBuffer()], "manifest.json", { type: "application/json" }));
   form.set("sprout", new File([await sprout.arrayBuffer()], "sprout", { type: "application/octet-stream" }));
@@ -516,7 +538,7 @@ async function deploy(args: string[]) {
     }
   }
 
-  const response = await fetch(`${apiUrl.replace(/\/$/, "")}/api/projects/${projectName}/deployments`, {
+  const response = await fetch(`${apiUrl}/api/projects/${projectName}/deployments`, {
     method: "POST",
     headers: { "x-api-key": token },
     body: form,
@@ -579,25 +601,34 @@ async function waitForHealthy(url: string, timeoutMs: number): Promise<boolean>
   return false;
 }
 
-function parseLoginArgs(args: string[]) {
-  let apiUrl = process.env.SPROUTBOAT_API_URL || defaultApiUrl;
+async function parseLoginArgs(args: string[]) {
+  let explicitApiUrl: string | undefined;
   let token: string | undefined;
   for (let index = 0; index < args.length; index += 2) {
     const value = args[index + 1];
-    if (args[index] === "--api-url" && value) apiUrl = value;
+    if (args[index] === "--api-url" && value) explicitApiUrl = value;
     else if (args[index] === "--token" && value) token = value;
     else usageError(`login: unexpected argument "${args[index]}"`, "login [--api-url <url>] [--token <token>]");
   }
-  return { apiUrl: apiUrl.replace(/\/$/, ""), token };
+  const { apiUrl, source } = await resolveApiUrl(explicitApiUrl);
+  return { apiUrl, source, token };
+}
+
+/** Announce a login that left the machine's active endpoint pointed elsewhere. */
+function reportActiveEndpoint(apiUrl: string, active: string): void {
+  if (active !== apiUrl)
+    console.log(dim(`active endpoint remains ${active} — \`sproutboat logout\` it first to switch`));
 }
 
 async function login(args: string[]) {
-  const { apiUrl, token: directToken } = parseLoginArgs(args);
+  const { apiUrl, source, token: directToken } = await parseLoginArgs(args);
+  console.log(`endpoint  ${apiUrl}  (${source})`);
   // Self-hosted / non-interactive: skip the browser flow and store the token
   // the admin already holds (e.g. SPROUTBOAT_BOOTSTRAP_TOKEN).
   if (directToken) {
-    await saveToken(apiUrl, directToken);
+    const { activeApiUrl: active } = await saveToken(apiUrl, directToken);
     console.log(`Saved credentials for ${apiUrl}.`);
+    reportActiveEndpoint(apiUrl, active);
     return;
   }
   const response = await fetch(`${apiUrl}/api/cli/authorizations`, { method: "POST" });
@@ -620,7 +651,7 @@ async function login(args: string[]) {
   console.log(`Confirm code: ${authorization.userCode}`);
   while (new Date(authorization.expiresAt).getTime() > Date.now()) {
     await Bun.sleep(Math.max(authorization.interval, 1) * 1000);
-    const exchange = await fetch(`${apiUrl.replace(/\/$/, "")}/api/cli/authorizations/token`, {
+    const exchange = await fetch(`${apiUrl}/api/cli/authorizations/token`, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ deviceCode: authorization.deviceCode }),
@@ -630,18 +661,19 @@ async function login(args: string[]) {
     if (!exchange.ok) fail(`login failed (${exchange.status}): ${result}`);
     const token = parseToken(result);
     if (!token) fail("login response did not include a CLI token");
-    await saveToken(apiUrl, token);
+    const { activeApiUrl: active } = await saveToken(apiUrl, token);
     console.log(ok("login approved — credentials saved for this endpoint"));
+    reportActiveEndpoint(apiUrl, active);
     return;
   }
   fail("login expired before approval");
 }
 
 async function apiCredentials() {
-  const apiUrl = (process.env.SPROUTBOAT_API_URL || (await activeApiUrl()) || defaultApiUrl).replace(/\/$/, "");
+  const { apiUrl, source } = await resolveApiUrl();
   const token = process.env.SPROUTBOAT_TOKEN || (await savedToken(apiUrl));
   if (!token) fail("not logged in; run sproutboat login or set SPROUTBOAT_TOKEN for this command");
-  return { apiUrl, token };
+  return { apiUrl, token, source };
 }
 
 async function versions(args: string[]) {
@@ -1231,12 +1263,36 @@ async function toolchain(args: string[]): Promise<void> {
     console.log(`macOS SDK: ${report.prerequisites.sdk ?? "missing: run xcode-select --install"}`);
 }
 
+/** `sproutboat <command> --help`: that command's full usage line + summary, exit 0. */
+function commandHelp(name: string): never {
+  const found = COMMANDS.find((c) => c.name === name);
+  if (!found) usage();
+  console.log(`${dim(`usage: ${CLI_NAME} ${name}${found.args ? ` ${found.args}` : ""}`)}\n\n${found.summary}`);
+  process.exit(0);
+}
+
+const BASH_COMPLETION = (names: string) =>
+  `_sproutboat_complete() {\n  local cur=\${COMP_WORDS[COMP_CWORD]}\n  if [ "$COMP_CWORD" -eq 1 ]; then\n    COMPREPLY=($(compgen -W "${names}" -- "$cur"))\n  fi\n}\ncomplete -F _sproutboat_complete ${CLI_NAME}\n`;
+const ZSH_COMPLETION = (names: string) => `#compdef ${CLI_NAME}\n_arguments '1: :(${names})'\n`;
+const FISH_COMPLETION = (names: string) => `complete -c ${CLI_NAME} -n "__fish_use_subcommand" -a "${names}"\n`;
+
+/** `sproutboat complete [shell]`: a static completion script for the top-level commands. */
+function complete(shell?: string): void {
+  const names = COMMANDS.map((c) => c.name).join(" ");
+  const scripts = { bash: BASH_COMPLETION(names), zsh: ZSH_COMPLETION(names), fish: FISH_COMPLETION(names) };
+  const key = shell ?? process.env.SHELL?.split("/").pop() ?? "bash";
+  const script = key === "bash" || key === "zsh" || key === "fish" ? scripts[key] : undefined;
+  if (!script) usageError(`complete: unsupported shell "${key}"`, "complete [bash | zsh | fish]");
+  console.log(script);
+}
+
 const [command, ...args] = process.argv.slice(2);
 if (command === undefined || command === "help" || command === "-h" || command === "--help") help();
 if (command === "--version" || command === "-v") {
   console.log(`sproutboat ${CLI_VERSION}`);
   process.exit(0);
 }
+if (args.includes("-h") || args.includes("--help")) commandHelp(command);
 
 await notifyIfOutdated(CLI_VERSION);
 
@@ -1302,6 +1358,9 @@ switch (command) {
   case "delete":
     await deleteProject(args);
     break;
+  case "complete":
+    complete(args[0]);
+    break;
   default:
     usage();
 }

package/src/surface.ts

@@ -195,6 +195,13 @@ export const COMMANDS: readonly Command[] = [
     args: "",
     summary: "Show the active endpoint and the account the stored token belongs to.",
   },
+  {
+    name: "complete",
+    group: "Account",
+    emoji: "⌨",
+    args: "[bash | zsh | fish]",
+    summary: "Print a shell completion script for the top-level commands (defaults to $SHELL).",
+  },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -264,6 +271,7 @@ export const ENV_VARS: readonly EnvVar[] = [
     purpose: "When set, skips the once-a-day npm check for a newer `sproutboat` release (also skipped when CI is set).",
   },
   { name: "XDG_CONFIG_HOME", purpose: "Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset." },
+  { name: "SHELL", purpose: "Picks the default shell for `complete` with no argument (bash/zsh/fish)." },
   { name: "PORFFOR_VERSION", purpose: "Override the Porffor identity string recorded in the manifest." },
   {
     name: "SB_BROKER_PORT",

package/src/toolchain.ts

@@ -677,14 +677,9 @@ export function porfforVersion(): string {
 }
 
 export function esbuildVersion(): string {
-  try {
-    const pkg = Bun.resolveSync("esbuild/package.json", import.meta.dir);
-    // SAFETY: esbuild's package.json always has a string `version`; defaulted below.
-    const parsed = JSON.parse(readFileSync(pkg, "utf8")) as { version?: string };
-    return parsed.version || "unknown";
-  } catch {
-    return "unknown";
-  }
+  // Legacy artifact field, retained so older control planes can read manifests.
+  // Handler bundling uses Bun.build and Porffor alpha 9 needs no esbuild binary.
+  return "unused";
 }
 
 function uwsCommit(): string {

package/src/types-gen.ts

@@ -55,6 +55,9 @@ function entries(config: SproutboatConfig): Entry[] {
   if (config.assets?.binding) {
     out.push({ name: config.assets.binding, type: "Fetcher", note: `static assets: ${config.assets.directory}` });
   }
+  if (config.version_metadata) {
+    out.push({ name: config.version_metadata, type: "VersionMetadata" });
+  }
   return out;
 }
 

package/types/sproutboat.d.ts

@@ -14,12 +14,19 @@
 declare global {
   // ---------------------------------------------------------------- KV
 
+  interface KVPutOptions {
+    /** Seconds from now until the key expires. Must be at least 60, matching Cloudflare. */
+    expirationTtl?: number;
+    /** Absolute expiration as unix seconds. */
+    expiration?: number;
+  }
+
   interface KVNamespace {
-    /** The stored string, or `null`. Synchronous: no `await`. */
+    /** The stored string, or `null`. Synchronous: no `await`. An expired key reads as absent. */
     get(key: string): string | null;
-    put(key: string, value: string): void;
+    put(key: string, value: string, options?: KVPutOptions): void;
     delete(key: string): void;
-    /** Keys under `prefix` (all keys when omitted). */
+    /** Keys under `prefix` (all keys when omitted). Expired keys are omitted. */
     list(prefix?: string): string[];
   }
 
@@ -320,6 +327,20 @@ declare global {
     /** Runs after `storage.setAlarm`, with no request in flight. */
     alarm?(): void | Promise<void>;
   }
+
+  // ------------------------------------------------------- Version metadata
+
+  /**
+   * #126 — named by `version_metadata` in `sproutboat.jsonc`. Baked into the
+   * binary at build time from the artifact's own digest: `id` matches the
+   * `artifact` field `sproutboat versions list` prints for this build, `tag`
+   * is the project name, `timestamp` is when it was built.
+   */
+  interface VersionMetadata {
+    id: string;
+    tag: string;
+    timestamp: string;
+  }
 }
 
 export {};