sproutboat 0.2.0

package/src/patch-porffor.ts

@@ -0,0 +1,43 @@
+/**
+ * Make Porffor's generated native-fetch server read its listen port from $PORT
+ * at runtime (falling back to the compiled `port:` value). Porffor renders the
+ * server as C text in `compiler/render.js`; we splice two lines into
+ * `porf_native_fetch_get_port()`.
+ *
+ * Done as an idempotent in-place edit rather than a `postinstall` hook: package
+ * managers block dependency lifecycle scripts by default, so a published
+ * `postinstall` would silently not run. This is called from the build path
+ * instead, where it always runs.
+ *
+ * Tracked upstream in patches/UPSTREAM.md — once Porffor reads $PORT (or exposes
+ * env to handlers) this whole file goes away.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { porfforRoot } from "./toolchain";
+
+// Splice INJECT in immediately after the opening brace, before the return.
+const ANCHOR = "f64 porf_native_fetch_get_port(void) {\n";
+const INJECT =
+  '  const char* __sb_port = getenv("PORT");\n' +
+  "  if (__sb_port && *__sb_port) { long __sb_v = strtol(__sb_port, NULL, 10); if (__sb_v > 0 && __sb_v < 65536) return (f64)__sb_v; }\n";
+const MARKER = 'getenv("PORT")';
+
+let done = false;
+
+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; }
+  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.",
+    );
+  }
+  const patched = src.slice(0, anchorAt + ANCHOR.length) + INJECT + src.slice(anchorAt + ANCHOR.length);
+  await writeFile(file, patched);
+  done = true;
+}

package/src/report.ts

@@ -0,0 +1,65 @@
+import { gzipSync } from "bun";
+import type { SproutboatConfig } from "./config";
+import type { ArtifactManifest } from "./manifest";
+
+const CLI_VERSION = "0.1.0";
+
+function bytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const kib = n / 1024;
+  if (kib < 1024) return `${kib.toFixed(2)} KiB`;
+  return `${(kib / 1024).toFixed(2)} MiB`;
+}
+
+/** Minimal box table. `align` marks columns to right-pad-left (numbers). */
+function table(headers: string[], rows: string[][], align: boolean[] = []): string {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+  const line = (l: string, m: string, r: string) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
+  const row = (cells: string[]) =>
+    "│ " + cells.map((c, i) => (align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]))).join(" │ ") + " │";
+  return [line("┌", "┬", "┐"), row(headers), line("├", "┼", "┤"), ...rows.map(row), line("└", "┴", "┘")].join("\n");
+}
+
+/**
+ * Wrangler-shaped build/deploy summary. Prints what the artifact contains, its
+ * upload size, and the bindings the handler will see. Returns nothing.
+ */
+export function printDeployReport(
+  config: SproutboatConfig,
+  manifest: ArtifactManifest,
+  worker: Uint8Array,
+  manifestBytes: number,
+): void {
+  const gz = gzipSync(Uint8Array.from(worker)).length;
+  const total = worker.length + manifestBytes;
+
+  console.log(`\n🌱 sproutboat ${CLI_VERSION}`);
+  console.log("─".repeat(19));
+  console.log(`Compiled ${manifest.project} with Porffor ${manifest.porfforVersion}`);
+  console.log(`  toolchain  ${manifest.buildImage}`);
+  console.log(`  compat     ${config.compatibility_date}`);
+  console.log();
+
+  console.log("Artifact:");
+  console.log(table(
+    ["File", "Type", "Size"],
+    [
+      ["worker", manifest.runtime, bytes(worker.length)],
+      ["manifest.json", "json", bytes(manifestBytes)],
+    ],
+    [false, false, true],
+  ));
+  console.log(`Total upload: ${bytes(total)}  (worker gzip: ${bytes(gz)})`);
+  console.log();
+
+  const vars = Object.entries(config.vars ?? {});
+  console.log("Bindings the handler will see:");
+  if (vars.length === 0) {
+    console.log("  (none — add [vars] to sproutboat.jsonc)");
+  } else {
+    console.log(table(
+      ["Binding", "Type", "Value"],
+      vars.map(([k, v]) => [`env.${k}`, "var", JSON.stringify(v)]),
+    ));
+  }
+}

package/src/source.ts

@@ -0,0 +1,26 @@
+export type SourceValidation = { ok: true } | { ok: false; errors: string[] };
+
+const alwaysForbidden: Array<[RegExp, string]> = [
+  [/^\s*import\s/m, "imports are not supported"],
+  [/\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"],
+];
+
+const fetchWithoutAllowlist: [RegExp, string] = [
+  /(?:\breturn\s+|\bawait\s+|=\s*)fetch\s*\(/,
+  "outbound networking needs an `outbound` host allowlist in sproutboat.jsonc",
+];
+
+export function validateHttpSyncSource(source: string, outboundAllowed = false): SourceValidation {
+  const errors: string[] = [];
+  // 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)) {
+    errors.push("handler must default-export an object with fetch(request)");
+  }
+  for (const [pattern, message] of alwaysForbidden) if (pattern.test(source)) errors.push(message);
+  if (!outboundAllowed && fetchWithoutAllowlist[0].test(source)) errors.push(fetchWithoutAllowlist[1]);
+  return errors.length ? { ok: false, errors } : { ok: true };
+}

package/src/surface.ts

@@ -0,0 +1,41 @@
+/**
+ * The CLI's public surface, as data. `main.ts` builds its usage string from
+ * this, and `surface.test.ts` renders it to `SURFACE.md` and checks that the
+ * command switch, the referenced env vars, and the doc can't drift apart.
+ */
+export const CLI_NAME = "sproutboat";
+
+export type Command = { name: string; args: string; summary: string };
+
+export const COMMANDS: readonly Command[] = [
+  { name: "init", args: "[name]", summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
+  { name: "check", args: "[project-dir]", summary: "Validate the config and entry point without building." },
+  { name: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch worker (Porffor + Zig)." },
+  { name: "deploy", args: "[project-dir] [--dry-run] [--artifact <dir>]", summary: "Build (unless --artifact), print the report, upload. --dry-run stops before upload." },
+  { name: "login", args: "[--api-url <url>] [--token <token>]", summary: "Device-code browser flow, or store <token> for <url> directly." },
+  { name: "tail", args: "[project-dir]", summary: "Print the project's recent request logs." },
+  { name: "versions", args: "list [project-dir]", summary: "List the project's deployed versions." },
+  { name: "rollback", args: "<version-id> [project-dir]", summary: "Re-activate a previous version." },
+  { name: "delete", args: "--yes [project-dir]", summary: "Delete the project and every version." },
+];
+
+export type EnvVar = { name: string; purpose: string };
+
+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_COMPILE_TIMEOUT_MS", purpose: "Porffor compile timeout in ms (default 600000)." },
+  { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
+  { name: "XDG_CONFIG_HOME", purpose: "Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset." },
+  { name: "PORFFOR_VERSION", purpose: "Override the Porffor identity string recorded in the manifest." },
+  { name: "SB_BROKER_PORT", purpose: "Loopback port of the binding broker, read by the compiled worker at runtime (set by the control plane, or by `src/broker.ts` for local runs)." },
+  { name: "SB_BROKER_TOKEN", purpose: "Per-deployment auth token the worker sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT)." },
+  { name: "SB_WORKER_URL", purpose: "http://127.0.0.1:<PORT> of the worker; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it." },
+];
+
+/** One-line usage string, e.g. for `usage()` and `--help`. */
+export function usageLine(): string {
+  const parts = COMMANDS.map((c) => (c.args ? `${c.name} ${c.args}` : c.name));
+  return `usage: ${CLI_NAME} <${parts.join(" | ")}>`;
+}

package/src/toolchain.ts

@@ -0,0 +1,125 @@
+/**
+ * The build toolchain: a pinned Zig (the linux-x86_64 cross-compiler Porffor
+ * shells out to for `--musl`) plus version stamps for the artifact manifest.
+ *
+ * Zig is fetched once to ~/.cache/sproutboat/zig-<version>/ and reused. No
+ * Docker, no root. Override with SPROUTBOAT_ZIG=/path/to/zig.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { chmod, mkdir, readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+export const ZIG_VERSION = "0.16.0";
+
+// 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> = {
+  "x86_64-linux": "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00",
+  "aarch64-linux": "ea4b09bfb22ec6f6c6ceac57ab63efb6b46e17ab08d21f69f3a48b38e1534f17",
+  "x86_64-macos": "0387557ed1877bc6a2e1802c8391953baddba76081876301c522f52977b52ba7",
+  "aarch64-macos": "b23d70deaa879b5c2d486ed3316f7eaa53e84acf6fc9cc747de152450d401489",
+};
+
+// Pinned Porffor identity — must match the `porffor` entry in package.json
+// (`github:CanadaHonk/porffor#alpha-4`, commit a415d19). PORFFOR_VERSION overrides.
+const PORFFOR_CHANNEL = "alpha-4";
+const PORFFOR_COMMIT = "a415d19";
+
+// uWebSockets commit Porffor alpha-4 fetches for the native-fetch server. Read
+// from node_modules/porffor at build time; this is the fallback for the stamp.
+const UWS_COMMIT = "360c276d";
+
+function platformKey(): string {
+  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`);
+  return `${arch}-${os}`;
+}
+
+async function sha256File(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  hash.update(await readFile(path));
+  return hash.digest("hex");
+}
+
+/** Absolute path to a usable `zig` binary, downloading it on first use. */
+export async function ensureZig(): Promise<string> {
+  const override = process.env.SPROUTBOAT_ZIG;
+  if (override) {
+    if (!existsSync(override)) throw new Error(`SPROUTBOAT_ZIG=${override} does not exist`);
+    return override;
+  }
+  const key = platformKey();
+  const home = homedir();
+  const dir = resolve(home, ".cache/sproutboat", `zig-${ZIG_VERSION}`);
+  const bin = resolve(dir, "zig");
+  if (existsSync(bin)) return bin;
+
+  const url = `https://ziglang.org/download/${ZIG_VERSION}/zig-${key}-${ZIG_VERSION}.tar.xz`;
+  const expected = ZIG_SHA256[key];
+  console.log(`Fetching Zig ${ZIG_VERSION} (${key}, one-time)...`);
+  await mkdir(dir, { recursive: true });
+  const archive = resolve(dir, "zig.tar.xz");
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`could not download Zig: ${url} (${response.status})`);
+  await Bun.write(archive, response);
+
+  const actual = await sha256File(archive);
+  if (expected && actual !== expected) {
+    await rm(dir, { recursive: true, force: true });
+    throw new Error(`Zig download sha256 mismatch\n  expected ${expected}\n  got      ${actual}`);
+  }
+
+  // `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 [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 });
+  if (!existsSync(bin)) throw new Error("Zig archive did not contain a `zig` binary");
+  await chmod(bin, 0o755);
+  return bin;
+}
+
+/** Directory holding node_modules/porffor (walks up from this file). */
+export function porfforRoot(start = import.meta.dir): string {
+  let dir = start;
+  for (;;) {
+    const candidate = resolve(dir, "node_modules/porffor");
+    if (existsSync(resolve(candidate, "runtime/index.js"))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error("node_modules/porffor not found — run `bun install`");
+    dir = parent;
+  }
+}
+
+export function porfforVersion(): string {
+  if (process.env.PORFFOR_VERSION) return process.env.PORFFOR_VERSION;
+  return `${PORFFOR_CHANNEL} (${PORFFOR_COMMIT})`;
+}
+
+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";
+  }
+}
+
+function uwsCommit(): string {
+  try {
+    const src = readFileSync(resolve(porfforRoot(), "compiler/uwebsockets.js"), "utf8");
+    return /UWS_COMMIT\s*=\s*['"]([0-9a-f]{7,40})/.exec(src)?.[1]?.slice(0, 8) || UWS_COMMIT;
+  } catch {
+    return UWS_COMMIT;
+  }
+}
+
+/** Compact provenance string for the artifact manifest. */
+export function toolchainStamp(): string {
+  return `zig-musl/${ZIG_VERSION}+porffor/${PORFFOR_COMMIT}+uws/${uwsCommit()}`;
+}