sproutboat 0.10.2 → 0.11.0

package/src/toolchain.ts

@@ -15,7 +15,9 @@ import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 // @ts-expect-error Bun's file loader returns the embedded asset path in a compiled executable.
 import embeddedUwsArchive from "../vendor/uwebsockets-360c276d-musl.tar.xz" with { type: "file" };
+import { BEARSSL_VERSION } from "./bearssl";
 import { cachedPorfforRoot, PORFFOR_CHANNEL, PORFFOR_COMMIT } from "./porffor-toolchain";
+import { SQLITE_VERSION } from "./sqlite";
 
 export const ZIG_VERSION = "0.16.0";
 
@@ -59,7 +61,7 @@ function platformKey(): ZigPlatform {
 
 export class ZigToolchainError extends Error {
   constructor(
-    readonly kind: "download" | "integrity" | "archive" | "cache" | "unsupported",
+    readonly kind: "download" | "integrity" | "archive" | "cache" | "compiler" | "unsupported",
     message: string,
   ) {
     super(message);
@@ -73,6 +75,8 @@ export type EnsureZigOptions = {
   expectedSha256?: string;
   fetcher?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
   timeoutMs?: number;
+  /** Test hook: release acquisition always validates the cross-C++ toolchain. */
+  validate?: boolean;
 };
 
 async function sha256File(path: string): Promise<string> {
@@ -90,6 +94,7 @@ async function zigComplete(dir: string, key: ZigPlatform, expectedArchive: strin
       platform?: string;
       archiveSha256?: string;
       binarySha256?: string;
+      cValidated?: boolean;
     };
     const bin = resolve(dir, "zig");
     return (
@@ -97,6 +102,7 @@ async function zigComplete(dir: string, key: ZigPlatform, expectedArchive: strin
       manifest.platform === key &&
       manifest.archiveSha256 === expectedArchive &&
       manifest.binarySha256 !== undefined &&
+      manifest.cValidated !== undefined &&
       (await sha256File(bin)) === manifest.binarySha256
     );
   } catch {
@@ -144,6 +150,30 @@ async function zigDownloadUrls(
   return [official];
 }
 
+/** Confirm the downloaded compiler can produce the C target Sproutboat builds. */
+async function validateZigTarget(bin: string, root: string): Promise<void> {
+  const stage = resolve(root, `.zig-c-probe-${process.pid}-${crypto.randomUUID()}`);
+  try {
+    await mkdir(stage);
+    const source = resolve(stage, "main.c");
+    const out = resolve(stage, "probe");
+    await writeFile(source, "int main() { return 0; }\n");
+    const child = Bun.spawn([bin, "cc", "-target", "x86_64-linux-musl", "-static", source, "-o", out], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+    if (code !== 0 || !existsSync(out))
+      throw new ZigToolchainError(
+        "compiler",
+        `pinned Zig cannot link a linux-x86_64-musl C binary: ${stderr.trim() || `exit ${code}`}\n` +
+          "Set SPROUTBOAT_ZIG to a working Zig binary, then run `sproutboat toolchain doctor`.",
+      );
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}
+
 async function downloadZig(
   urls: string[],
   path: string,
@@ -218,19 +248,40 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
   const stage = resolve(root, `.zig-${ZIG_VERSION}-${key}-${process.pid}-${crypto.randomUUID()}`);
   const fetcher = options.fetcher ?? fetch;
   const sourceUrl = options.url ?? process.env.SPROUTBOAT_ZIG_URL;
-  const urls = sourceUrl ? [sourceUrl] : await zigDownloadUrls(key, fetcher, options.timeoutMs ?? 30_000);
-  console.log(`Fetching Zig ${ZIG_VERSION} (${key}, one-time)...`);
+  // A platform package ships its own host's Zig archive right beside the CLI
+  // executable (scripts/build-cli.ts stages it there at publish time, the same
+  // compressed .tar.xz an ordinary download would fetch), so a packaged
+  // install needs no network for Zig -- same pattern as the vendored
+  // uWebSockets archive. Only the default, no-`platform`/no-`url` call (every
+  // real caller) takes this path; build-cli.ts's own cross-target fetches and
+  // this file's tests always pass one of those and go straight to the network.
+  const vendored =
+    options.platform === undefined && !sourceUrl ? resolve(dirname(process.execPath), "zig.tar.xz") : null;
+  const usingVendored = vendored !== null && existsSync(vendored);
+  console.log(
+    usingVendored
+      ? `Extracting vendored Zig ${ZIG_VERSION} (${key}, one-time)...`
+      : `Fetching Zig ${ZIG_VERSION} (${key}, one-time)...`,
+  );
   try {
     if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
     await rm(dir, { recursive: true, force: true });
     await mkdir(stage);
     const archive = resolve(stage, "zig.tar.xz");
-    await downloadZig(urls, archive, fetcher, options.timeoutMs ?? 60_000);
+    if (usingVendored) {
+      // SAFETY: usingVendored is only true when `vendored` is the non-null path just checked.
+      await Bun.write(archive, Bun.file(vendored!));
+    } else {
+      // Zig's pinned archive is about 50 MB. Keep the fetch bounded while
+      // allowing a cold download to complete on ordinary consumer connections.
+      const urls = sourceUrl ? [sourceUrl] : await zigDownloadUrls(key, fetcher, options.timeoutMs ?? 30_000);
+      await downloadZig(urls, archive, fetcher, options.timeoutMs ?? 120_000);
+    }
     const actual = await sha256File(archive);
     if (actual !== expected)
       throw new ZigToolchainError(
         "integrity",
-        `Zig archive sha256 mismatch\n  expected ${expected}\n  got      ${actual}`,
+        `${usingVendored ? "vendored " : ""}Zig archive sha256 mismatch\n  expected ${expected}\n  got      ${actual}`,
       );
     const untar = Bun.spawn(["tar", "-xJf", archive, "-C", stage, "--strip-components=1"], {
       stdout: "pipe",
@@ -243,6 +294,7 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
     const bin = resolve(stage, "zig");
     if (!existsSync(bin)) throw new ZigToolchainError("archive", "Zig archive did not contain a `zig` binary");
     await chmod(bin, 0o755);
+    if (options.validate !== false) await validateZigTarget(bin, root);
     await writeFile(
       resolve(stage, ".sproutboat-complete"),
       JSON.stringify({
@@ -250,6 +302,7 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
         platform: key,
         archiveSha256: actual,
         binarySha256: await sha256File(bin),
+        cValidated: options.validate !== false,
       }),
       { mode: 0o444 },
     );
@@ -261,6 +314,134 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
   }
 }
 
+/**
+ * The verified, compressed Zig archive for `platform` -- not extracted, not
+ * necessarily this host's own. `scripts/build-cli.ts` uses this to fetch and
+ * stage another platform's archive into that platform's package for `--all`,
+ * where `ensureZig` itself cannot help: it extracts, validates, and caches for
+ * *this* host only, none of which makes sense for a foreign target's binary.
+ * Cached at `<cacheRoot>/zig-archive-<version>-<platform>.tar.xz` so a repeat
+ * `--all` run does not re-download all four.
+ */
+export async function ensureZigArchive(platform: ZigPlatform, cacheRoot?: string): Promise<string> {
+  const root = resolve(cacheRoot ?? process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"));
+  const archive = resolve(root, `zig-archive-${ZIG_VERSION}-${platform}.tar.xz`);
+  const expected = ZIG_SHA256[platform];
+  if (existsSync(archive) && (await sha256File(archive)) === expected) return archive;
+  await mkdir(root, { recursive: true });
+  const stage = `${archive}.${process.pid}.${crypto.randomUUID()}`;
+  const urls = await zigDownloadUrls(platform, fetch, 30_000);
+  await downloadZig(urls, stage, fetch, 120_000);
+  const actual = await sha256File(stage);
+  if (actual !== expected) {
+    await rm(stage, { force: true });
+    throw new ZigToolchainError(
+      "integrity",
+      `Zig archive sha256 mismatch\n  expected ${expected}\n  got      ${actual}`,
+    );
+  }
+  await rename(stage, archive);
+  return archive;
+}
+
+/** `cc [args...]`/`cxx [args...]`/`ar [args...]`, each as `[bin, ...leadingArgs]`
+ *  ready to spread before a call's own arguments. */
+export type HostCompiler = { cc: string[]; cxx: string[]; ar: string[]; usingZig: boolean };
+
+/**
+ * The C/C++/archiver toolchain for a **host** build (`dev`, `build --target
+ * host`, and every host-native object BearSSL/SQLite/uWebSockets compile).
+ *
+ * Prefers whatever the machine already has — no download, and unchanged
+ * behavior for every developer with Xcode Command Line Tools / build-essential
+ * installed. Falls back to the pinned Zig (already vendored for the musl
+ * cross-target) as a cross-compiler pointed at this same host, so the packaged
+ * CLI needs no system C toolchain at all — Zig ships a real native codegen
+ * backend for the host triple, not just cross-musl.
+ */
+export async function resolveHostCompiler(): Promise<HostCompiler> {
+  const cc = process.env.CC;
+  const cxx = process.env.CXX;
+  const ar = process.env.AR;
+  const haveCc = Boolean(cc || Bun.which("cc"));
+  const haveAr = Boolean(ar || Bun.which("ar"));
+  if (haveCc && haveAr) return { cc: [cc || "cc"], cxx: [cxx || "c++"], ar: [ar || "ar"], usingZig: false };
+  const zigBin = await ensureZig();
+  const [arch, os] = platformKey().split("-");
+  const triple = os === "macos" ? `${arch}-macos` : `${arch}-linux-gnu`;
+  return {
+    cc: [zigBin, "cc", "-target", triple],
+    cxx: [zigBin, "c++", "-target", triple],
+    ar: [zigBin, "ar"],
+    usingZig: true,
+  };
+}
+
+export type ToolchainDoctor = {
+  host: `${string}/${string}`;
+  cacheRoot: string;
+  porffor: { version: string; path: string; override: string | null; present: boolean };
+  zig: {
+    version: string;
+    platform: ZigPlatform | null;
+    path: string | null;
+    override: string | null;
+    present: boolean;
+  };
+  sqlite: { version: string; path: string; present: boolean };
+  bearssl: { version: string; path: string; present: boolean };
+  prerequisites: { cc: string | null; ar: string | null; tar: string | null; xcrun: string | null; sdk: string | null };
+};
+
+/** Inspect the selected toolchain without downloading, compiling, or mutating a cache. */
+export function inspectToolchain(): ToolchainDoctor {
+  const cacheRoot = resolve(process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"));
+  const porfforOverride = process.env.SPROUTBOAT_PORFFOR_DIR ? resolve(process.env.SPROUTBOAT_PORFFOR_DIR) : null;
+  const zigOverride = process.env.SPROUTBOAT_ZIG ? resolve(process.env.SPROUTBOAT_ZIG) : null;
+  let platform: ZigPlatform | null = null;
+  try {
+    platform = platformKey();
+  } catch {
+    /* doctor reports an unsupported host instead of throwing before its diagnostics */
+  }
+  const zigPath = zigOverride ?? (platform ? resolve(cacheRoot, `zig-${ZIG_VERSION}-${platform}`, "zig") : null);
+  const porfforPath = porfforOverride ?? cachedPorfforRoot(cacheRoot);
+  const sqlitePath = resolve(cacheRoot, `sqlite-${SQLITE_VERSION}`);
+  const bearsslPath = resolve(cacheRoot, `bearssl-${BEARSSL_VERSION}`);
+  const xcrun = process.platform === "darwin" ? Bun.which("xcrun") : null;
+  const sdk = (() => {
+    if (!xcrun) return null;
+    const probe = Bun.spawnSync([xcrun, "--show-sdk-path"], { stdout: "pipe", stderr: "ignore" });
+    return probe.exitCode === 0 ? probe.stdout.toString().trim() || null : null;
+  })();
+  return {
+    host: `${process.arch}/${process.platform}`,
+    cacheRoot,
+    porffor: {
+      version: porfforVersion(),
+      path: porfforPath,
+      override: porfforOverride,
+      present: existsSync(resolve(porfforPath, "runtime/index.js")),
+    },
+    zig: {
+      version: ZIG_VERSION,
+      platform,
+      path: zigPath,
+      override: zigOverride,
+      present: Boolean(zigPath && existsSync(zigPath)),
+    },
+    sqlite: { version: SQLITE_VERSION, path: sqlitePath, present: existsSync(sqlitePath) },
+    bearssl: { version: BEARSSL_VERSION, path: bearsslPath, present: existsSync(bearsslPath) },
+    prerequisites: {
+      cc: Bun.which(process.env.CC ?? "cc"),
+      ar: Bun.which(process.env.AR ?? "ar"),
+      tar: Bun.which("tar"),
+      xcrun,
+      sdk,
+    },
+  };
+}
+
 function uwsCommitFull(): string {
   try {
     const src = readFileSync(resolve(porfforRoot(), "compiler/uwebsockets.js"), "utf8");
@@ -280,6 +461,65 @@ export function uwsVendorArchive(short: string): string {
     : resolve(import.meta.dir, "..", "vendor", `uwebsockets-${short}-musl.tar.xz`);
 }
 
+const UWS_REQUIRED = ["src/App.h", "uSockets/uSockets.a"];
+
+async function uwsComplete(dir: string, command?: string[]): Promise<boolean> {
+  try {
+    // SAFETY: this manifest is private data written below. The files it names
+    // are fixed by this module and each recorded digest is recomputed.
+    const manifest = JSON.parse(await readFile(resolve(dir, ".sproutboat-complete"), "utf8")) as {
+      files?: Record<string, string>;
+      command?: string[];
+    };
+    return (
+      (command === undefined || JSON.stringify(manifest.command) === JSON.stringify(command)) &&
+      (
+        await Promise.all(
+          UWS_REQUIRED.map(async (file) => (await sha256File(resolve(dir, file))) === manifest.files?.[file]),
+        )
+      ).every(Boolean)
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function writeUwsManifest(dir: string, command?: string[]): Promise<void> {
+  const files = Object.fromEntries(
+    await Promise.all(UWS_REQUIRED.map(async (file) => [file, await sha256File(resolve(dir, file))] as const)),
+  );
+  const manifest = resolve(dir, ".sproutboat-complete");
+  const stage = `${manifest}.${process.pid}.${crypto.randomUUID()}`;
+  await writeFile(stage, JSON.stringify({ files, command }), { mode: 0o444 });
+  await rename(stage, manifest);
+}
+
+/** Serialize cache reconstruction and recover a lock left by an interrupted build. */
+async function withUwsLock<T>(dir: string, action: () => Promise<T>): Promise<T> {
+  await mkdir(dirname(dir), { recursive: true });
+  const lock = `${dir}.lock`;
+  const deadline = Date.now() + 30_000;
+  for (;;) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch {
+      if (Date.now() > deadline) throw new UwsUnavailableError(`timed out waiting for uWebSockets cache lock ${lock}`);
+      try {
+        if (Date.now() - (await stat(lock)).mtimeMs > 5 * 60_000) await rm(lock, { recursive: true, force: true });
+      } catch {
+        /* the active publisher released the lock between stat and rm */
+      }
+      await Bun.sleep(25);
+    }
+  }
+  try {
+    return await action();
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+
 /**
  * Seed `~/.cache/porffor/deps/uWebSockets-<commit>-musl/` with the checked-out,
  * patched, `x86_64-linux-musl`-built uWebSockets tree so Porffor's own
@@ -297,30 +537,33 @@ export async function ensureUWebSockets(): Promise<void> {
   const short = commit.slice(0, 8);
   const depsRoot = resolve(homedir(), ".cache/porffor/deps");
   const dir = resolve(depsRoot, `uWebSockets-${commit}-musl`);
-  if (existsSync(resolve(dir, "src/App.h")) && existsSync(resolve(dir, "uSockets/uSockets.a"))) return;
-
-  const archive = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(short);
-  if (!existsSync(archive)) {
-    throw new UwsUnavailableError(
-      process.env.SPROUTBOAT_UWS_TARBALL
-        ? `SPROUTBOAT_UWS_TARBALL=${archive} does not exist`
-        : `no vendored uWebSockets archive at ${archive} (porffor pin moved? run \`bun tools/prebuild-uws.ts\`)`,
-    );
-  }
-  if (!process.env.SPROUTBOAT_UWS_TARBALL) {
-    const actual = await sha256File(archive);
-    if (actual !== UWS_TARBALL_SHA256) {
+  if (await uwsComplete(dir)) return;
+
+  await withUwsLock(dir, async () => {
+    if (await uwsComplete(dir)) return;
+    const archive = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(short);
+    if (!existsSync(archive)) {
       throw new UwsUnavailableError(
-        `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+        process.env.SPROUTBOAT_UWS_TARBALL
+          ? `SPROUTBOAT_UWS_TARBALL=${archive} does not exist`
+          : `no vendored uWebSockets archive at ${archive} (porffor pin moved? run \`bun tools/prebuild-uws.ts\`)`,
       );
     }
-  }
-
-  await extractUws(archive, dir);
+    if (!process.env.SPROUTBOAT_UWS_TARBALL) {
+      const actual = await sha256File(archive);
+      if (actual !== UWS_TARBALL_SHA256) {
+        throw new UwsUnavailableError(
+          `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+        );
+      }
+    }
+    await extractUws(archive, dir);
+  });
 }
 
 /** Unpack the vendored source tree into `dir`. */
 async function extractUws(archive: string, dir: string): Promise<void> {
+  await rm(dir, { recursive: true, force: true });
   await mkdir(dir, { recursive: true });
   // External programs cannot read Bun's virtual /$bunfs paths. Materialize the
   // embedded release asset inside the destination before handing it to tar.
@@ -336,6 +579,12 @@ async function extractUws(archive: string, dir: string): Promise<void> {
     await rm(dir, { recursive: true, force: true });
     throw new UwsUnavailableError(`could not extract vendored uWebSockets: ${err.trim()}`);
   }
+  try {
+    await writeUwsManifest(dir);
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true });
+    throw new UwsUnavailableError(`could not validate vendored uWebSockets: ${String(error)}`);
+  }
 }
 
 /**
@@ -358,50 +607,54 @@ export async function ensureUWebSocketsHost(): Promise<void> {
   const dir = resolve(homedir(), ".cache/porffor/deps", `uWebSockets-${commit}`);
   const uSockets = resolve(dir, "uSockets");
   const archivePath = resolve(uSockets, "uSockets.a");
-  if (existsSync(resolve(dir, "src/App.h")) && existsSync(archivePath)) return;
-
-  const vendored = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(commit.slice(0, 8));
-  if (!existsSync(vendored)) {
-    throw new UwsUnavailableError(`no vendored uWebSockets archive at ${vendored}`);
-  }
-  if (!process.env.SPROUTBOAT_UWS_TARBALL) {
-    const actual = await sha256File(vendored);
-    if (actual !== UWS_TARBALL_SHA256) {
+  const { cc, ar, usingZig } = await resolveHostCompiler();
+  const command = [cc.join(" "), ar.join(" ")];
+  if (await uwsComplete(dir, command)) return;
+
+  await withUwsLock(dir, async () => {
+    if (await uwsComplete(dir, command)) return;
+    const vendored = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(commit.slice(0, 8));
+    if (!existsSync(vendored)) throw new UwsUnavailableError(`no vendored uWebSockets archive at ${vendored}`);
+    if (!process.env.SPROUTBOAT_UWS_TARBALL) {
+      const actual = await sha256File(vendored);
+      if (actual !== UWS_TARBALL_SHA256) {
+        throw new UwsUnavailableError(
+          `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+        );
+      }
+    }
+    await extractUws(vendored, dir);
+
+    // The archive carries the musl-built uSockets.a. Linking that into a host
+    // binary fails in a way nobody would connect to this, so it goes first.
+    await rm(archivePath, { force: true });
+
+    const sources = ["src/*.c", "src/eventing/*.c", "src/crypto/*.c", "src/io_uring/*.c"];
+    // Zig's cc needs `-fuse-ld=lld` wired up for LTO at link time; this is a
+    // `-c`-only compile step with no link, so LTO just isn't worth chasing here.
+    const flto = usingZig ? "" : "-flto ";
+    const compile = Bun.spawn(
+      ["sh", "-c", `${command[0]} -std=c11 -Isrc -DLIBUS_NO_SSL ${flto}-O3 -c ${sources.join(" ")}`],
+      { cwd: uSockets, stdout: "pipe", stderr: "pipe" },
+    );
+    const [ccCode, ccErr] = await Promise.all([compile.exited, new Response(compile.stderr).text()]);
+    if (ccCode !== 0) {
       throw new UwsUnavailableError(
-        `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+        `could not compile uSockets with ${command[0]}: ${ccErr.trim().split("\n").slice(-3).join(" ")}`,
       );
     }
-  }
-  if (!existsSync(resolve(dir, "src/App.h"))) await extractUws(vendored, dir);
 
-  // The archive carries the musl-built uSockets.a. Linking that into a host
-  // binary fails in a way nobody would connect to this, so it goes first.
-  await rm(archivePath, { force: true });
-
-  const sources = ["src/*.c", "src/eventing/*.c", "src/crypto/*.c", "src/io_uring/*.c"];
-  const cc = process.env.CC || "cc";
-  const ar = process.env.AR || "ar";
-  const compile = Bun.spawn(["sh", "-c", `${cc} -std=c11 -Isrc -DLIBUS_NO_SSL -flto -O3 -c ${sources.join(" ")}`], {
-    cwd: uSockets,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [ccCode, ccErr] = await Promise.all([compile.exited, new Response(compile.stderr).text()]);
-  if (ccCode !== 0) {
-    throw new UwsUnavailableError(
-      `could not compile uSockets with ${cc}: ${ccErr.trim().split("\n").slice(-3).join(" ")}`,
-    );
-  }
-
-  const archiveStep = Bun.spawn(["sh", "-c", `${ar} rvs uSockets.a *.o`], {
-    cwd: uSockets,
-    stdout: "pipe",
-    stderr: "pipe",
+    const archiveStep = Bun.spawn(["sh", "-c", `${command[1]} rvs uSockets.a *.o`], {
+      cwd: uSockets,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [arCode, arErr] = await Promise.all([archiveStep.exited, new Response(archiveStep.stderr).text()]);
+    if (arCode !== 0 || !existsSync(archivePath)) {
+      throw new UwsUnavailableError(`could not archive uSockets with ${command[1]}: ${arErr.trim()}`);
+    }
+    await writeUwsManifest(dir, command);
   });
-  const [arCode, arErr] = await Promise.all([archiveStep.exited, new Response(archiveStep.stderr).text()]);
-  if (arCode !== 0 || !existsSync(archivePath)) {
-    throw new UwsUnavailableError(`could not archive uSockets with ${ar}: ${arErr.trim()}`);
-  }
 }
 
 /** Directory holding node_modules/porffor (walks up from this file). */

package/types/sproutboat.d.ts

@@ -182,9 +182,13 @@ declare global {
    * A rate-limiter binding (#69). `limit` and `period` are fixed in
    * sproutboat.jsonc; `limit({ key })` counts one call against a fixed window
    * and reports whether the key is still under the cap.
+   *
+   * `resetAt` is epoch milliseconds for when the window rolls and the count
+   * clears — the same for a hit or a miss. Turn a rejection into a header with
+   * `Retry-After: Math.ceil((resetAt - Date.now()) / 1000)`.
    */
   interface RateLimit {
-    limit(options: { key: string }): { success: boolean };
+    limit(options: { key: string }): { success: boolean; resetAt: number };
   }
 
   // ------------------------------------ Crypto