sproutboat 0.4.11 → 0.6.0

package/src/patch-porffor.ts

@@ -29,12 +29,15 @@ export async function ensurePorfforPatched(): Promise<void> {
   if (done) return;
   const file = resolve(porfforRoot(), "compiler/render.js");
   const src = await readFile(file, "utf8");
-  if (src.includes(MARKER)) { done = true; return; }
+  if (src.includes(MARKER)) {
+    done = true;
+    return;
+  }
   const anchorAt = src.indexOf(ANCHOR);
   if (anchorAt === -1) {
     throw new Error(
       `could not patch Porffor for $PORT: anchor not found in ${file}. ` +
-      "Porffor's native-fetch renderer changed — check patches/UPSTREAM.md.",
+        "Porffor's native-fetch renderer changed — check patches/UPSTREAM.md.",
     );
   }
   const patched = src.slice(0, anchorAt + ANCHOR.length) + INJECT + src.slice(anchorAt + ANCHOR.length);

package/src/report.ts

@@ -5,7 +5,11 @@ import type { ArtifactManifest } from "./manifest";
 import { bold, dim, leaf, sprout } from "./style";
 
 // Read from package.json so the banner never drifts from the published version.
-export const CLI_VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
+// SAFETY: our own package.json, shipped beside src/ by the `files` field; npm requires `version`.
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+  version: string;
+};
+export const CLI_VERSION = packageJson.version;
 
 function bytes(n: number): string {
   if (n < 1024) return `${n} B`;
@@ -19,23 +23,38 @@ function table(headers: string[], rows: string[][], align: boolean[] = []): stri
   const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
   const rule = (l: string, m: string, r: string) => leaf(l + widths.map((w) => "─".repeat(w + 2)).join(m) + r);
   const row = (cells: string[], head = false) =>
-    leaf("│ ") + cells.map((c, i) => {
-      const cell = align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]);
-      return head ? bold(cell) : cell;
-    }).join(leaf(" │ ")) + leaf(" │");
-  return [rule("┌", "┬", "┐"), row(headers, true), rule("├", "┼", "┤"), ...rows.map((r) => row(r)), rule("└", "┴", "┘")].join("\n");
+    leaf("│ ") +
+    cells
+      .map((c, i) => {
+        const cell = align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]);
+        return head ? bold(cell) : cell;
+      })
+      .join(leaf(" │ ")) +
+    leaf(" │");
+  return [
+    rule("┌", "┬", "┐"),
+    row(headers, true),
+    rule("├", "┼", "┤"),
+    ...rows.map((r) => row(r)),
+    rule("└", "┴", "┘"),
+  ].join("\n");
 }
 
 /** Every binding the compiled sprout will see, flattened to (name, type, detail) rows. */
 function bindingRows(config: SproutboatConfig): string[][] {
   const rows: string[][] = [];
-  for (const [name, value] of Object.entries(config.vars ?? {})) rows.push([`env.${name}`, "var", JSON.stringify(value)]);
+  for (const [name, value] of Object.entries(config.vars ?? {}))
+    rows.push([`env.${name}`, "var", JSON.stringify(value)]);
   const list = (names: string[] | undefined, type: string, detail = "") => {
     for (const name of names ?? []) rows.push([`env.${name}`, type, detail]);
   };
   const resourceList = (refs: Parameters<typeof resourceRefs>[0], type: string) => {
     for (const ref of resourceRefs(refs)) {
-      rows.push([`env.${ref.binding}`, type, ref.id ?? "deploy-scoped store (--no-provision) — drop the flag to auto-provision a persistent resource"]);
+      rows.push([
+        `env.${ref.binding}`,
+        type,
+        ref.id ?? "deploy-scoped store (--no-provision) — drop the flag to auto-provision a persistent resource",
+      ]);
     }
   };
   resourceList(config.kv_namespaces, "kv");
@@ -44,7 +63,8 @@ function bindingRows(config: SproutboatConfig): string[][] {
   resourceList(config.r2_buckets, "r2");
   resourceList(config.queues, "queue");
   list(config.analytics_engine_datasets, "analytics");
-  for (const [name, className] of Object.entries(config.durable_objects ?? {})) rows.push([`env.${name}`, "durable object", className]);
+  for (const [name, className] of Object.entries(config.durable_objects ?? {}))
+    rows.push([`env.${name}`, "durable object", className]);
   for (const host of config.outbound ?? []) rows.push([`fetch()`, "outbound", host]);
   for (const cron of config.triggers?.crons ?? []) rows.push([`scheduled()`, "cron", cron]);
   if (config.assets?.binding) rows.push([`env.${config.assets.binding}`, "assets", config.assets.directory ?? ""]);
@@ -72,14 +92,16 @@ export function printDeployReport(
   console.log();
 
   console.log(bold("Artifact"));
-  console.log(table(
-    ["File", "Type", "Size"],
-    [
-      ["sprout", manifest.runtime, bytes(sproutBin.length)],
-      ["manifest.json", "json", bytes(manifestBytes)],
-    ],
-    [false, false, true],
-  ));
+  console.log(
+    table(
+      ["File", "Type", "Size"],
+      [
+        ["sprout", manifest.runtime, bytes(sproutBin.length)],
+        ["manifest.json", "json", bytes(manifestBytes)],
+      ],
+      [false, false, true],
+    ),
+  );
   console.log(`Total upload: ${bold(bytes(total))}  ${dim(`(sprout gzip: ${bytes(gz)})`)}`);
   console.log();
 

package/src/source.ts

@@ -1,10 +1,25 @@
+import { neutraliseExports } from "./wrap";
+
 export type SourceValidation = { ok: true } | { ok: false; errors: string[] };
 
+// Checked against the *bundled* module (#89), not the entry file: after
+// bundling there are no imports left to reject, and a dependency reaching for a
+// Node API has to fail exactly as hand-written code would. A bare specifier
+// that resolves to nothing never gets this far — the bundler fails first.
 const alwaysForbidden: Array<[RegExp, string]> = [
-  [/^\s*import\s/m, "imports are not supported"],
+  [/^\s*import\s/m, "an import survived bundling — only static imports can be resolved at build time"],
+  [/\bimport\s*\(/, "dynamic import() is not supported: nothing can resolve it at build time"],
   [/\brequire\s*\(/, "CommonJS require is not supported"],
   [/\b(WebSocket|XMLHttpRequest)\s*\(/, "WebSocket / XMLHttpRequest are not supported"],
   [/\b(process|Bun|Deno|Buffer|node:)\b/, "Node, Bun, and Deno APIs are not supported"],
+  // Porffor alpha-4 compiles `new Proxy(...)` and then ignores the handler: a
+  // trapped property reads back as `undefined`, with no throw. Rejecting it
+  // here is the difference between a build error and a 502 nobody can explain.
+  // It is why itty-router and other Proxy-based routers do not work yet.
+  [
+    /\bnew\s+Proxy\s*\(|\bProxy\s*\.\s*revocable\s*\(/,
+    "Proxy is not supported by the compiler: its traps are silently ignored and the property reads back as undefined",
+  ],
 ];
 
 const fetchWithoutAllowlist: [RegExp, string] = [
@@ -17,7 +32,10 @@ export function validateHttpSyncSource(source: string, outboundAllowed = false):
   // The default export must be an object literal with a `fetch` method. A module
   // may also declare Durable Object classes / helpers before it, so this is not
   // anchored to the start of the file.
-  if (!/\bexport\s+default\s*\{/.test(source) || !/\bfetch\s*\(/.test(source)) {
+  // A hand-written file exports inline; a bundled one re-exports at the end.
+  // `neutraliseExports` is the same reader the compiler uses, so `check` cannot
+  // accept a module the build would then reject.
+  if (neutraliseExports(source) === null || !/\bfetch\s*\(/.test(source)) {
     errors.push("handler must default-export an object with fetch(request)");
   }
   for (const [pattern, message] of alwaysForbidden) if (pattern.test(source)) errors.push(message);

package/src/style.ts

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

package/src/surface.ts

@@ -9,7 +9,7 @@ export const CLI_NAME = "sproutboat";
 export const TAGLINE = "Deploy JavaScript handlers as tiny native binaries on your own VPS.";
 export const REPO_URL = "https://github.com/baronunread/sproutboat";
 
-export type Group = "Develop" | "Ship" | "Configure" | "Account";
+export type Group = "Develop" | "Ship" | "Storage" | "Configure" | "Account";
 
 export type Command = {
   name: string;
@@ -22,39 +22,162 @@ export type Command = {
   summary: string;
 };
 
+/**
+ * The storage products. Each is its own command with the same five verbs over
+ * its own `/api/<segment>` collection.
+ *
+ * Wrangler nests two of its four (`kv namespace create`, `r2 bucket create`)
+ * and leaves `d1 create` and `queues create` flat. That nesting separates a
+ * container from its contents, which the verb already does — so ours are
+ * uniform, and contents take their own noun when they exist (`kv key get`).
+ */
+export type StorageProduct = {
+  /** Command name, URL segment, and the dashboard's product page. */
+  name: "kv" | "d1" | "r2" | "queues";
+  /** One of them, for buttons and messages: "namespace", "bucket". */
+  noun: string;
+  /** Many of them, for list output and empty states. */
+  plural: string;
+  emoji: string;
+};
+
+export const STORAGE_PRODUCTS: readonly StorageProduct[] = [
+  { name: "kv", noun: "namespace", plural: "KV namespaces", emoji: "🗄" },
+  { name: "d1", noun: "database", plural: "D1 databases", emoji: "🛢" },
+  { name: "r2", noun: "bucket", plural: "R2 buckets", emoji: "🪣" },
+  { name: "queues", noun: "queue", plural: "queues", emoji: "📨" },
+];
+
+/** Every storage product answers to exactly these, in this order. */
+export const STORAGE_VERBS = ["list", "create", "info", "rename", "delete"] as const;
+
+const STORAGE_ARGS = "<list | create <name> | info <name> | rename <name> <new> | delete <name>>";
+
+const storageCommands: readonly Command[] = STORAGE_PRODUCTS.map((product) => ({
+  name: product.name,
+  group: "Storage" as const,
+  emoji: product.emoji,
+  args: STORAGE_ARGS,
+  brief: `<${STORAGE_VERBS.join(" | ")}>`,
+  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "queues" ? "; consumers are not implemented yet" : ""}.`,
+}));
+
 export const COMMANDS: readonly Command[] = [
-  { name: "init", group: "Develop", emoji: "🌱", args: "[name]",
-    summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
-  { name: "check", group: "Develop", emoji: "🔍", args: "[project-dir]",
-    summary: "Validate the config and entry point without building." },
-  { name: "build", group: "Develop", emoji: "🔨", args: "[project-dir]",
-    summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
-
-  { name: "deploy", group: "Ship", emoji: "🚀",
-    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]", brief: "[project-dir] [--dry-run]",
-    summary: "Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores." },
-  { name: "versions", group: "Ship", emoji: "📜", args: "list [project-dir]",
-    summary: "List the project's deployed versions." },
-  { name: "rollback", group: "Ship", emoji: "⏮", args: "<version-id> [project-dir]", brief: "<version-id>",
-    summary: "Re-activate a previous version." },
-  { name: "tail", group: "Ship", emoji: "📡", args: "[project-dir] [--sprout]",
-    summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
-
-  { name: "domains", group: "Configure", emoji: "🌐",
-    args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", brief: "[list | add | verify | rm]",
-    summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
-  { name: "secrets", group: "Configure", emoji: "🔑",
-    args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", brief: "[list | set | rm]",
-    summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
-  { name: "resource", group: "Configure", emoji: "📦",
-    args: "[list [kind] | create <kind> <name> | rename <id> <name> | delete <id>]", brief: "[list | create | rename | delete]",
-    summary: "Manage account-level storage resources (kv | d1 | r2 | queue). `create` prints the id to reference from sproutboat.jsonc bindings." },
-  { name: "delete", group: "Configure", emoji: "🗑",
-    args: "[project-dir] [--name <project>] --yes", brief: "[project-dir] --yes",
-    summary: "Delete the project, every version, and its route." },
-
-  { name: "login", group: "Account", emoji: "🔓", args: "[--api-url <url>] [--token <token>]", brief: "[--token <token>]",
-    summary: "Device-code browser flow, or store <token> for <url> directly." },
+  {
+    name: "init",
+    group: "Develop",
+    emoji: "🌱",
+    args: "[name]",
+    summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>.",
+  },
+  {
+    name: "check",
+    group: "Develop",
+    emoji: "🔍",
+    args: "[project-dir]",
+    summary: "Validate the config and entry point without building.",
+  },
+  {
+    name: "dev",
+    group: "Develop",
+    emoji: "⚡",
+    args: "[project-dir] [--port <n>] [--no-watch]",
+    brief: "[project-dir] [--port <n>]",
+    summary: "Run the project on this machine against a real broker, rebuilding on save.",
+  },
+  {
+    name: "build",
+    group: "Develop",
+    emoji: "🔨",
+    args: "[project-dir] [--target host]",
+    brief: "[project-dir]",
+    summary:
+      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable.",
+  },
+
+  {
+    name: "deploy",
+    group: "Ship",
+    emoji: "🚀",
+    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]",
+    brief: "[project-dir] [--dry-run]",
+    summary:
+      "Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores.",
+  },
+  {
+    name: "versions",
+    group: "Ship",
+    emoji: "📜",
+    args: "<list | view <version-id>> [project-dir]",
+    brief: "<list | view>",
+    summary: "List the project's deployed versions, or show one version's artifact and bindings.",
+  },
+  {
+    name: "rollback",
+    group: "Ship",
+    emoji: "⏮",
+    args: "<version-id> [project-dir]",
+    brief: "<version-id>",
+    summary: "Re-activate a previous version.",
+  },
+  {
+    name: "tail",
+    group: "Ship",
+    emoji: "📡",
+    args: "[project-dir] [--sprout]",
+    summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead.",
+  },
+
+  ...storageCommands,
+
+  {
+    name: "domains",
+    group: "Configure",
+    emoji: "🌐",
+    args: "<list | add <host> | verify <host> | delete <host>> [project-dir]",
+    brief: "<list | add | verify | delete>",
+    summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists.",
+  },
+  {
+    name: "secrets",
+    group: "Configure",
+    emoji: "🔑",
+    args: "<list | put <NAME> [--value <value>] | delete <NAME>> [project-dir]",
+    brief: "<list | put | delete>",
+    summary:
+      "Manage encrypted project secrets (read as env.NAME). `put` reads the value from stdin unless --value is given, so it stays out of shell history; applies on next deploy.",
+  },
+  {
+    name: "delete",
+    group: "Configure",
+    emoji: "🗑",
+    args: "[project-dir] [--name <project>] --yes",
+    brief: "[project-dir] --yes",
+    summary: "Delete the project, every version, and its route.",
+  },
+
+  {
+    name: "login",
+    group: "Account",
+    emoji: "🔓",
+    args: "[--api-url <url>] [--token <token>]",
+    brief: "[--token <token>]",
+    summary: "Device-code browser flow, or store <token> for <url> directly.",
+  },
+  {
+    name: "logout",
+    group: "Account",
+    emoji: "🔒",
+    args: "[--api-url <url>]",
+    summary: "Forget the stored credential for the active endpoint, or for <url>.",
+  },
+  {
+    name: "whoami",
+    group: "Account",
+    emoji: "👤",
+    args: "",
+    summary: "Show the active endpoint and the account the stored token belongs to.",
+  },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -63,21 +186,51 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SPROUTBOAT_API_URL", purpose: "Control-plane URL. Overrides the saved active endpoint." },
   { name: "SPROUTBOAT_TOKEN", purpose: "API token. Overrides the saved credential for the endpoint." },
   { 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_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 sprout module." },
-  { name: "SPROUTBOAT_BINDINGS_JSON", purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line." },
+  {
+    name: "SPROUTBOAT_VARS_JSON",
+    purpose:
+      "JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the sprout module.",
+  },
+  {
+    name: "SPROUTBOAT_BINDINGS_JSON",
+    purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line.",
+  },
   { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
-  { name: "NO_COLOR", purpose: "When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY." },
-  { name: "SPROUTBOAT_NO_UPDATE_CHECK", purpose: "When set, skips the once-a-day npm check for a newer `sproutboat` release (also skipped when CI is set)." },
+  {
+    name: "NO_COLOR",
+    purpose:
+      "When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY.",
+  },
+  {
+    name: "SPROUTBOAT_NO_UPDATE_CHECK",
+    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: "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 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." },
+  {
+    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.",
+  },
 ];
 
-const GROUP_ORDER: readonly Group[] = ["Develop", "Ship", "Configure", "Account"];
+const GROUP_ORDER: readonly Group[] = ["Develop", "Ship", "Storage", "Configure", "Account"];
 
 /** One-line usage string, e.g. for `usage()` and SURFACE.md. */
 export function usageLine(): string {

package/src/toolchain.ts

@@ -13,14 +13,17 @@ import { dirname, resolve } from "node:path";
 
 export const ZIG_VERSION = "0.16.0";
 
+/** The `<arch>-<os>` platforms ziglang.org publishes a tarball for that we pin. */
+type ZigPlatform = "x86_64-linux" | "aarch64-linux" | "x86_64-macos" | "aarch64-macos";
+
 // sha256 of the official ziglang.org tarballs for ZIG_VERSION, keyed by
 // `<arch>-<os>` (the download naming). Bump alongside ZIG_VERSION.
-const ZIG_SHA256: Record<string, string> = {
+const ZIG_SHA256 = {
   "x86_64-linux": "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00",
   "aarch64-linux": "ea4b09bfb22ec6f6c6ceac57ab63efb6b46e17ab08d21f69f3a48b38e1534f17",
   "x86_64-macos": "0387557ed1877bc6a2e1802c8391953baddba76081876301c522f52977b52ba7",
   "aarch64-macos": "b23d70deaa879b5c2d486ed3316f7eaa53e84acf6fc9cc747de152450d401489",
-};
+} satisfies Record<ZigPlatform, string>;
 
 // Pinned Porffor identity — must match the `porffor` entry in package.json
 // (`github:CanadaHonk/porffor#alpha-4`, commit a415d19). PORFFOR_VERSION overrides.
@@ -43,10 +46,13 @@ const UWS_COMMIT_FULL = "360c276d609d59af56ae6932adb95154ace9f15f";
 // or the `uws-prebuild` workflow.
 const UWS_TARBALL_SHA256 = "e83736f3f8cf9d56a1ebe6ea61625a7af12386763374d47c14cff472ada7484a";
 
-function platformKey(): string {
+function platformKey(): ZigPlatform {
   const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : null;
   const os = process.platform === "linux" ? "linux" : process.platform === "darwin" ? "macos" : null;
-  if (!arch || !os) throw new Error(`no pinned Zig for ${process.platform}/${process.arch} — set SPROUTBOAT_ZIG to a zig ${ZIG_VERSION} binary`);
+  if (!arch || !os)
+    throw new Error(
+      `no pinned Zig for ${process.platform}/${process.arch} — set SPROUTBOAT_ZIG to a zig ${ZIG_VERSION} binary`,
+    );
   return `${arch}-${os}`;
 }
 
@@ -85,7 +91,10 @@ export async function ensureZig(): Promise<string> {
   }
 
   // `tar -xJ` (xz) works on macOS bsdtar and GNU tar with xz on PATH.
-  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], { stdout: "pipe", stderr: "pipe" });
+  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], {
+    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 Zig (needs \`tar\` with xz support): ${err.trim()}`);
   await rm(archive, { force: true });
@@ -141,12 +150,17 @@ export async function ensureUWebSockets(): Promise<void> {
   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}`);
+      throw new UwsUnavailableError(
+        `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+      );
     }
   }
 
   await mkdir(dir, { recursive: true });
-  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], { stdout: "pipe", stderr: "pipe" });
+  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
   const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
   if (code !== 0) {
     await rm(dir, { recursive: true, force: true });

package/src/update-check.ts

@@ -7,6 +7,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { configDirectory } from "./credentials";
+import { isSafeInteger, isString, jsonObject, parseJsonValue } from "./json";
 import { dim } from "./style";
 
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
@@ -14,13 +15,25 @@ const REGISTRY = "https://registry.npmjs.org/sproutboat/latest";
 
 type Cache = { checkedAt: number; latest: string };
 
+/** Decode our own cache file, which a stale version or a partial write can corrupt. */
+function parseCache(source: string): Cache | undefined {
+  const record = jsonObject(parseJsonValue(source));
+  return record && isSafeInteger(record.checkedAt) && isString(record.latest)
+    ? { checkedAt: record.checkedAt, latest: record.latest }
+    : undefined;
+}
+
 function cachePath(): string {
   return resolve(configDirectory(), "update-check.json");
 }
 
 /** Numeric x.y.z compare; a trailing `-tag` (prerelease) sorts before its release. */
 function isNewer(latest: string, current: string): boolean {
-  const parts = (v: string) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const parts = (v: string) =>
+    v
+      .split("-")[0]
+      .split(".")
+      .map((n) => Number.parseInt(n, 10) || 0);
   const [a, b] = [parts(latest), parts(current)];
   for (let i = 0; i < 3; i++) {
     if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
@@ -30,18 +43,25 @@ function isNewer(latest: string, current: string): boolean {
 
 async function latestVersion(): Promise<string | undefined> {
   try {
-    const cached = JSON.parse(await readFile(cachePath(), "utf8")) as Cache;
-    if (Date.now() - cached.checkedAt < CACHE_TTL_MS && typeof cached.latest === "string") return cached.latest;
-  } catch { /* no cache yet, or unreadable — fetch below */ }
+    const cached = parseCache(await readFile(cachePath(), "utf8"));
+    if (cached && Date.now() - cached.checkedAt < CACHE_TTL_MS) return cached.latest;
+  } catch {
+    /* no cache yet, or unreadable — fetch below */
+  }
 
   try {
-    const response = await fetch(REGISTRY, { signal: AbortSignal.timeout(1000), headers: { accept: "application/json" } });
+    const response = await fetch(REGISTRY, {
+      signal: AbortSignal.timeout(1000),
+      headers: { accept: "application/json" },
+    });
     if (!response.ok) return undefined;
-    const latest = ((await response.json()) as { version?: string }).version;
-    if (typeof latest !== "string") return undefined;
+    const latest = jsonObject(parseJsonValue(await response.text()))?.version;
+    if (!isString(latest)) return undefined;
     await writeFile(cachePath(), JSON.stringify({ checkedAt: Date.now(), latest } satisfies Cache)).catch(() => {});
     return latest;
-  } catch { /* offline / slow / DNS — skip silently */ }
+  } catch {
+    /* offline / slow / DNS — skip silently */
+  }
   return undefined;
 }
 
@@ -50,6 +70,10 @@ export async function notifyIfOutdated(current: string): Promise<void> {
   if (process.env.SPROUTBOAT_NO_UPDATE_CHECK || process.env.CI) return;
   const latest = await latestVersion();
   if (latest && isNewer(latest, current)) {
-    console.error(dim(`  update available: sproutboat ${current} → ${latest}  ·  bump the dependency or run \`bunx sproutboat@latest\``));
+    console.error(
+      dim(
+        `  update available: sproutboat ${current} → ${latest}  ·  bump the dependency or run \`bunx sproutboat@latest\``,
+      ),
+    );
   }
 }