sproutboat 0.11.10 → 0.11.11

package/CHANGELOG.md

@@ -8,6 +8,14 @@ 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.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 +596,8 @@ 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.11...HEAD
+[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.11 · 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). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.11.10",
+  "version": "0.11.11",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -62,11 +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",
+    "@sproutboat/assets": "^0.3.0",
+    "@sproutboat/config": "^0.4.0",
+    "@sproutboat/runtime": "^0.12.0",
+    "@sproutboat/toolchain": "^0.4.11",
+    "@sproutboat/wire": "^0.9.0",
     "esbuild": "^0.28.2"
   },
   "devDependencies": {
@@ -78,10 +78,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.11",
+    "@sproutboat/cli-darwin-x64": "0.11.11",
+    "@sproutboat/cli-linux-arm64": "0.11.11",
+    "@sproutboat/cli-linux-x64": "0.11.11"
   },
   "engines": {
     "node": ">=18"

package/src/build.ts

@@ -171,6 +171,13 @@ 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({
@@ -188,6 +195,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       extraLink,
       extraCflags,
       optimize: input.optimize,
+      versionMetadata,
     });
 
   const sprout = await readFile(sproutPath);
@@ -204,7 +212,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/compile.ts

@@ -80,6 +80,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
@@ -210,6 +212,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
       input.appName,
       input.assets,
       input.transport,
+      input.versionMetadata,
     ),
   );
 

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/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/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 {};