sproutboat 0.54.0 → 0.55.0

package/src/compile.ts

@@ -31,6 +31,7 @@ import {
   ensurePorfforA21,
   SHARED_PRELUDE_FILE,
   STANDALONE_A21_COMPILE_FLAGS,
+  standaloneA21Channel,
   standaloneChannel,
   type StandaloneChannel,
 } from "@sproutboat/toolchain/a21";
@@ -67,16 +68,16 @@ export {
 const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 600_000);
 
 /**
- * The Porffor channel a native compile uses: `alpha-22` by default (the alpha 21 line's compiler with
- * the toolchain's alpha 19 server shim over its bridge; sproutd-alpha22-standalone-port.md), or
- * `alpha-19` (`SPROUTBOAT_PORFFOR_CHANNEL=alpha-19`: Porffor's native-fetch server, the fallback pin
- * kept for one release). The toolchain's `standaloneChannel()` decides, so the CLI and the runtime's
- * native tests agree on the default.
+ * The Porffor channel a native compile uses: `alpha-23` by default (the alpha 21 line's compiler with
+ * the toolchain's alpha 19 server shim over its bridge; sproutd-alpha22-standalone-port.md), `alpha-22`
+ * (`SPROUTBOAT_PORFFOR_CHANNEL=alpha-22`: the same line one Porffor release back), or `alpha-19`
+ * (`SPROUTBOAT_PORFFOR_CHANNEL=alpha-19`: Porffor's native-fetch server, the fallback pin kept for one release).
+ * The toolchain's `standaloneChannel()` decides, so the CLI and the runtime's native tests agree on the default.
  *
  * `--with-restore` stays on alpha 19: its restore objects are built against alpha 19's native-fetch
  * C API, which the alpha 22 bridge does not provide, so they do not link there. Unless the channel is
- * set explicitly, such a build uses the alpha 19 compiler; `SPROUTBOAT_PORFFOR_CHANNEL=alpha-22` with
- * `--with-restore` is an error rather than a link failure.
+ * set explicitly, such a build uses the alpha 19 compiler; `SPROUTBOAT_PORFFOR_CHANNEL=alpha-22` or
+ * `alpha-23` with `--with-restore` is an error rather than a link failure.
  */
 export type PorfforChannel = StandaloneChannel;
 export function porfforChannel(withRestore = false): PorfforChannel {
@@ -84,7 +85,7 @@ export function porfforChannel(withRestore = false): PorfforChannel {
   if (!withRestore || channel === "alpha-19") return channel;
   if (process.env.SPROUTBOAT_PORFFOR_CHANNEL)
     throw new Error(
-      "--with-restore is not available on Porffor alpha 22 yet: unset SPROUTBOAT_PORFFOR_CHANNEL or set it to alpha-19",
+      "--with-restore is not available on Porffor alpha 22 or 23 yet: unset SPROUTBOAT_PORFFOR_CHANNEL or set it to alpha-19",
     );
   return "alpha-19";
 }
@@ -396,7 +397,7 @@ export async function compileSprout(input: CompileInput): Promise<void> {
       })
     : [];
 
-  if (porfforChannel(input.withRestore) === "alpha-22") {
+  if (porfforChannel(input.withRestore) !== "alpha-19") {
     await compileSproutA21(input, {
       alpha19Root: porffor,
       generatedPath,
@@ -449,9 +450,9 @@ export async function compileSprout(input: CompileInput): Promise<void> {
 }
 
 /**
- * The alpha 22 channel's native compile (sproutd-alpha22-standalone-port.md): the generated module is
+ * The alpha 21 line's native compile, alpha 23 or alpha 22 (sproutd-alpha22-standalone-port.md): the generated module is
  * compiled in sproutd's worker shape (the toolchain composes `shared-prelude.js` from it: alpha 19
- * helper names, the alpha 19 web classes, the dispatch shim), the alpha 22 compiler renders the split
+ * helper names, the alpha 19 web classes, the dispatch shim), the line's compiler renders the split
  * C units, and the toolchain's build recipe compiles them with the native-fetch bridge and the alpha
  * 19 uWebSockets shim rewritten over flat data, then links with this build's native objects (SQLite,
  * BearSSL, the restore objects) and the uSockets this target already has. Same inputs, same outputs,
@@ -469,7 +470,8 @@ async function compileSproutA21(
     uwsVariant?: string;
   },
 ): Promise<void> {
-  const alpha22 = await ensurePorfforA21("alpha-22");
+  const a21Channel = standaloneA21Channel(porfforChannel(input.withRestore));
+  const a21 = await ensurePorfforA21(a21Channel);
   const dir = dirname(build.generatedPath);
   const composed = composeStandaloneA21(await readFile(build.generatedPath, "utf8"), build.alpha19Root);
   // beside sprout.generated.js (which stays the wrapped module, for emit-only, dev and the cache key)
@@ -482,7 +484,7 @@ async function compileSproutA21(
   const render = Bun.spawn(
     [
       ...build.launch,
-      resolve(alpha22, "runtime/index.js"),
+      resolve(a21, "runtime/index.js"),
       "c",
       entry,
       "-o",
@@ -496,7 +498,8 @@ async function compileSproutA21(
     new Response(render.stdout).text(),
     new Response(render.stderr).text(),
   ]);
-  if (code !== 0) throw new Error(`Porffor (alpha 22) render failed: ${(stderr || stdout).trim() || `exit ${code}`}`);
+  if (code !== 0)
+    throw new Error(`Porffor (${a21Channel}) render failed: ${(stderr || stdout).trim() || `exit ${code}`}`);
 
   const host = input.target === "host";
   const triple = host ? undefined : linuxTriple(input.target);
@@ -524,5 +527,5 @@ async function compileSproutA21(
     musl: !host,
     strip: true,
   });
-  if (!(await Bun.file(input.outPath).exists())) throw new Error("alpha 22 build produced no binary");
+  if (!(await Bun.file(input.outPath).exists())) throw new Error("alpha 21 line build produced no binary");
 }

package/src/dev.ts

@@ -32,6 +32,8 @@ export type DevInput = {
   /** The bundled module (#89) — already validated by the caller. */
   source: string;
   port: number;
+  /** `--ip`: the address the public port listens on. Default 127.0.0.1; 0.0.0.0 makes it reachable on the network. */
+  host?: string;
   watch: boolean;
   /** #275: `--env-file` paths (absolute), in order. Default: `.dev.vars`, else the `.env` files. */
   envFiles?: string[];
@@ -105,6 +107,52 @@ export type Running = {
   disableDispatch: () => void;
 };
 
+/** One browser WebSocket and the connection to the sprout that answers it. */
+type SocketRelay = {
+  url: string;
+  protocols: string[];
+  /** Frames that arrived before the sprout side finished opening. */
+  queued: Array<string | Uint8Array<ArrayBuffer>>;
+  upstream?: WebSocket;
+};
+
+const socketRelay: Bun.WebSocketHandler<SocketRelay> = {
+  open(client) {
+    const relay = client.data;
+    const upstream = new WebSocket(relay.url, relay.protocols);
+    upstream.binaryType = "arraybuffer";
+    relay.upstream = upstream;
+    upstream.addEventListener("open", () => {
+      for (const frame of relay.queued.splice(0)) upstream.send(frame);
+    });
+    upstream.addEventListener("message", (event) => {
+      if (client.readyState !== 1) return;
+      // SAFETY: binaryType is "arraybuffer", so a frame is a string or an ArrayBuffer.
+      client.send(event.data as string | ArrayBuffer);
+    });
+    upstream.addEventListener("close", (event) => {
+      // 1005 and 1006 are reserved for the receiver to report; they cannot be sent.
+      const code =
+        event.code >= 1000 && event.code < 5000 && event.code !== 1005 && event.code !== 1006 ? event.code : 1000;
+      client.close(code, event.reason);
+    });
+    upstream.addEventListener("error", () => client.close(1011, "sprout unavailable"));
+  },
+  message(client, message) {
+    const upstream = client.data.upstream;
+    const frame = message instanceof Uint8Array ? new Uint8Array(message) : message;
+    if (upstream && upstream.readyState === 1) upstream.send(frame);
+    else client.data.queued.push(frame);
+  },
+  close(client, code, reason) {
+    const upstream = client.data.upstream;
+    if (!upstream || upstream.readyState > 1) return;
+    try {
+      upstream.close(code === 1005 || code === 1006 ? 1000 : code, reason);
+    } catch {}
+  },
+};
+
 async function start(input: DevInput, port: number): Promise<Running> {
   const candidateDir = resolve(
     input.projectDir,
@@ -285,12 +333,26 @@ export async function runDev(input: DevInput): Promise<void> {
   // what lets a failed startup leave the last known-good process reachable.
   let proxy: ReturnType<typeof Bun.serve>;
   try {
-    proxy = Bun.serve({
-      hostname: "127.0.0.1",
+    proxy = Bun.serve<SocketRelay>({
+      hostname: input.host ?? "127.0.0.1",
       port: input.port,
       maxRequestBodySize: 5 * 1024 * 1024 * 1024,
+      websocket: socketRelay,
       fetch(request, server) {
         const target = new URL(request.url);
+        // A WebSocket upgrade cannot go through fetch(): relay it, frame by frame, to the sprout.
+        if (request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+          target.protocol = "ws:";
+          target.host = `127.0.0.1:${activePort}`;
+          const protocols = request.headers.get("sec-websocket-protocol");
+          const data: SocketRelay = {
+            url: target.toString(),
+            protocols: protocols ? protocols.split(",").map((entry) => entry.trim()) : [],
+            queued: [],
+          };
+          if (server.upgrade(request, { data })) return undefined;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
         const directTransfer = /^\/__sb\/r2\/transfer\/[A-Z][A-Z0-9_]*\/[0-9a-f]{24}$/.test(target.pathname);
         if (directTransfer) server.timeout(request, 255);
         if (directTransfer && !activeTransferPort) return new Response("direct transfers unavailable", { status: 503 });
@@ -308,7 +370,7 @@ export async function runDev(input: DevInput): Promise<void> {
     throw error;
   }
   watchExit(running);
-  console.log(ok(`${input.config.name} running on ${leaf(`http://127.0.0.1:${input.port}`)}`));
+  console.log(ok(`${input.config.name} running on ${leaf(`http://${input.host ?? "127.0.0.1"}:${input.port}`)}`));
   if (input.watch) console.log(dim("  watching for changes — ctrl-c to stop"));
 
   let watchers: FSWatcher[] = [];
@@ -319,7 +381,8 @@ export async function runDev(input: DevInput): Promise<void> {
     if (shuttingDown) return;
     shuttingDown = true;
     for (const watcher of watchers) watcher.close();
-    proxy.stop();
+    // Close open sockets too: a graceful stop waits for a WebSocket the browser keeps open.
+    proxy.stop(true);
     if (pendingCandidate) stop(pendingCandidate);
     stop(running);
     resolveShutdown?.();

package/src/init.ts

@@ -0,0 +1,328 @@
+/**
+ * `sproutboat init`: scaffold a project, in the shape of `npm create cloudflare` (create-cloudflare, "C3").
+ *
+ *   sproutboat init [name] [--template <name>] [--git | --no-git] [--install | --no-install] [-y]
+ *   sproutboat init --list-templates
+ *
+ * Interactive in a terminal (it asks for the template, the directory, git and installing, with C3's defaults);
+ * silent everywhere else, where nothing runs that a flag did not ask for. Everything outside the filesystem
+ * (prompts, git, the package manager) goes through `InitIo`, so tests drive the whole flow without a terminal.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseConfig } from "./config";
+import {
+  detectPackageManager,
+  installCommand,
+  planPackageJson,
+  runScriptCommand,
+  type PackagePlan,
+} from "./init-package";
+import {
+  DEFAULT_TEMPLATE,
+  firstRunScript,
+  isTemplate,
+  listTemplates,
+  templateFiles,
+  type TemplateFile,
+} from "./templates";
+import { amber, dim } from "./style";
+import { parseTypesArgs, planTypes } from "./types-cmd";
+
+export type InitOptions = {
+  name?: string;
+  template?: string;
+  git?: boolean;
+  install?: boolean;
+  /** `-y`: take every default without asking, git and install included. */
+  yes: boolean;
+  list: boolean;
+};
+
+export type Choice = { value: string; label: string };
+
+export type InitIo = {
+  cwd: string;
+  cliVersion: string;
+  /** A person is here to answer: stdin and stdout are terminals. */
+  interactive: boolean;
+  log(line: string): void;
+  warn(line: string): void;
+  ask(question: string, fallback: string): Promise<string>;
+  /** Pick one of `choices` by number, `fallback` (a value) on an empty answer. */
+  choose(question: string, choices: readonly Choice[], fallback: string): Promise<string>;
+  confirm(question: string, fallback: boolean): Promise<boolean>;
+  /** Run a command with the terminal attached; resolves to its exit code (127 when it cannot start). */
+  run(command: string, args: readonly string[], cwd: string): Promise<number>;
+  /** Run a command and return its exit code and output. */
+  capture(command: string, args: readonly string[], cwd: string): Promise<{ code: number; stdout: string }>;
+  /** Called once when init ends, however it ends. */
+  close?(): void;
+};
+
+/** A failure the user can act on; `main.ts` prints the message and exits 1. */
+export class InitError extends Error {}
+
+const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])?$/;
+const NAME_ERROR = "project name must be a 3–32 character lowercase slug";
+
+export function parseInitArgs(args: readonly string[]): InitOptions | { error: string } {
+  const options: InitOptions = { yes: false, list: false };
+  for (let at = 0; at < args.length; at += 1) {
+    const arg = args[at]!;
+    if (arg === "--template") {
+      const value = args[(at += 1)];
+      if (value === undefined || value.startsWith("-")) return { error: "--template needs a template name" };
+      options.template = value;
+    } else if (arg === "--git") options.git = true;
+    else if (arg === "--no-git") options.git = false;
+    else if (arg === "--install") options.install = true;
+    else if (arg === "--no-install") options.install = false;
+    else if (arg === "-y" || arg === "--yes" || arg === "--accept-defaults") options.yes = true;
+    else if (arg === "--list-templates") options.list = true;
+    else if (arg.startsWith("-")) return { error: `unknown option ${arg}` };
+    else if (options.name === undefined) options.name = arg;
+    else return { error: `unexpected argument "${arg}": init takes one project name` };
+  }
+  return options;
+}
+
+export function templateListing(): string {
+  const width = Math.max(...listTemplates().map((template) => template.name.length));
+  return listTemplates()
+    .map(({ name, description }) => `  ${name.padEnd(width)}  ${description}`)
+    .join("\n");
+}
+
+// -------------------------------------------------------------- the hello starter
+
+const helloConfig = (name: string) => `{
+  "$schema": "https://sproutboat.com/schema.json",
+  "name": "${name}",
+  "main": "src/index.js",
+  "compatibility_date": "2026-09-28"
+}
+`;
+const helloHandler = `export default {
+  fetch(request, env, ctx) {
+    return new Response("hello from Sproutboat");
+  }
+};
+`;
+// .sproutboat/ holds build output (dist/) and `dev`'s local broker state
+// (dev/, including its SQLite files), neither of which belongs in version control.
+// .dev.vars carries secret values for `sproutboat dev`, same convention as
+// Wrangler's file of the same name.
+const gitignore = `.sproutboat/
+.dev.vars
+node_modules/
+`;
+
+// -------------------------------------------------------------- the flow
+
+export async function runInit(options: InitOptions, io: InitIo): Promise<void> {
+  try {
+    await scaffold(options, io);
+  } finally {
+    io.close?.();
+  }
+}
+
+async function scaffold(options: InitOptions, io: InitIo): Promise<void> {
+  if (options.list) {
+    io.log(`Templates (sproutboat init --template <name>):\n${templateListing()}`);
+    return;
+  }
+  const asking = io.interactive && !options.yes;
+
+  let template = options.template;
+  if (template !== undefined && !isTemplate(template))
+    throw new InitError(`unknown template "${template}". Templates:\n${templateListing()}`);
+  if (template === undefined)
+    template = asking
+      ? await io.choose(
+          "Which template would you like to use?",
+          listTemplates().map(({ name, description }) => ({ value: name, label: `${name}: ${description}` })),
+          DEFAULT_TEMPLATE,
+        )
+      : DEFAULT_TEMPLATE;
+
+  const fallbackName = template === DEFAULT_TEMPLATE ? "hello" : template;
+  const given =
+    options.name ??
+    (asking ? await io.ask("In which directory do you want to create your application?", fallbackName) : fallbackName);
+  // C3 takes a directory and names the app after it; so does this: `init apps/blog` makes ./apps/blog named "blog".
+  const directory = resolve(io.cwd, given);
+  const name = basename(directory);
+  if (!NAME_PATTERN.test(name)) throw new InitError(NAME_ERROR);
+  const shown = basename(directory);
+
+  const hello = template === DEFAULT_TEMPLATE;
+  const files: TemplateFile[] = hello
+    ? [
+        { path: "sproutboat.jsonc", content: helloConfig(name) },
+        { path: "src/index.js", content: helloHandler },
+      ]
+    : // An existing .gitignore is not a sign this is not a fresh project (the name can collide with an unrelated
+      // directory): keep it rather than fail or clobber it.
+      templateFiles(template, name, io.cliVersion).filter(
+        (file) => file.path !== ".gitignore" || !existsSync(join(directory, ".gitignore")),
+      );
+
+  // Check every target before writing any: `name` can collide with an unrelated existing directory, and a write
+  // failing partway through would leave a half-scaffolded project behind.
+  for (const file of files)
+    if (existsSync(join(directory, file.path))) throw new InitError(`${shown} already contains ${file.path}`);
+
+  // The hello starter merges into an existing package.json (and keeps an existing .gitignore); plan that before
+  // writing anything, so an unreadable one stops init instead of half-scaffolding.
+  const packagePath = join(directory, "package.json");
+  let packagePlan: PackagePlan | undefined;
+  if (hello) {
+    const existing = existsSync(packagePath) ? await readFile(packagePath, "utf8") : undefined;
+    try {
+      packagePlan = planPackageJson(name, existing, io.cliVersion);
+    } catch (cause) {
+      throw new InitError(`${shown}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+  }
+
+  for (const file of files) {
+    const path = join(directory, file.path);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, file.content, { flag: "wx" });
+    io.log(`Created ${shown}/${file.path}`);
+  }
+  if (packagePlan) {
+    if (!existsSync(join(directory, ".gitignore"))) {
+      await writeFile(join(directory, ".gitignore"), gitignore, { flag: "wx" });
+      io.log(`Created ${shown}/.gitignore`);
+    }
+    if (packagePlan.created || packagePlan.addedDependency || packagePlan.addedScripts.length > 0) {
+      await writeFile(packagePath, packagePlan.text);
+      io.log(`${packagePlan.created ? "Created" : "Updated"} ${shown}/package.json`);
+    }
+    for (const script of packagePlan.skippedScripts)
+      io.warn(
+        `  ! package.json already has a "${script}" script; left it as is (sproutboat's would be "sproutboat ${script}")`,
+      );
+  }
+
+  // A TypeScript template ships without worker-configuration.d.ts: it is written here, for this project's name.
+  if (existsSync(join(directory, "tsconfig.json"))) {
+    const config = parseConfig(await readFile(join(directory, "sproutboat.jsonc"), "utf8"));
+    const args = parseTypesArgs([]);
+    if (!config.ok || "error" in args) throw new InitError(`could not write worker-configuration.d.ts for ${shown}`);
+    const plan = await planTypes(args, config.value, directory, directory);
+    await writeFile(plan.path, plan.text);
+    io.log(`Created ${shown}/${basename(plan.path)}`);
+  }
+
+  const manager = detectPackageManager(directory);
+  const install =
+    options.install ??
+    (options.yes
+      ? true
+      : asking
+        ? await io.confirm(`Do you want to install dependencies with ${manager}?`, true)
+        : false);
+  const git =
+    options.git ??
+    (options.yes ? true : asking ? await io.confirm("Do you want to use git for version control?", true) : false);
+
+  let installed = false;
+  if (install) {
+    io.log(`Installing dependencies with ${manager}...`);
+    installed = (await io.run(manager, ["install"], directory)) === 0;
+    if (!installed) io.warn(`  ! ${installCommand(manager)} failed; run it yourself in ${shown}`);
+  }
+  if (git) await initGit(directory, shown, io);
+
+  const setup = firstRunScript(template);
+  const steps = [
+    `cd ${shown}`,
+    ...(installed ? [] : [installCommand(manager)]),
+    ...(setup ? [runScriptCommand(manager, setup)] : []),
+    runScriptCommand(manager, "dev"),
+  ];
+  io.log(`\nNext: ${steps.join(" && ")}`);
+  io.log(dim(`After "sproutboat login", ship it with ${runScriptCommand(manager, "deploy")}.`));
+}
+
+async function initGit(directory: string, shown: string, io: InitIo): Promise<void> {
+  if ((await io.capture("git", ["--version"], directory)).code !== 0) {
+    io.warn("  ! git is not installed; skipped git init");
+    return;
+  }
+  // A project made inside someone's repository belongs to that repository: do not nest a second one in it.
+  const inside = await io.capture("git", ["rev-parse", "--is-inside-work-tree"], directory);
+  if (inside.code === 0 && inside.stdout.trim() === "true") {
+    io.log(`  git: ${shown} is already inside a git repository; not creating another`);
+    return;
+  }
+  if ((await io.capture("git", ["init", "--quiet"], directory)).code !== 0) {
+    io.warn("  ! git init failed");
+    return;
+  }
+  await io.capture("git", ["add", "-A"], directory);
+  const commit = await io.capture("git", ["commit", "--quiet", "-m", "Initial commit (by sproutboat init)"], directory);
+  io.log(
+    commit.code === 0
+      ? `  git: initialized ${shown} with a first commit`
+      : `  git: initialized ${shown}; the first commit failed (is user.name set?)`,
+  );
+}
+
+// -------------------------------------------------------------- the terminal
+
+export function terminalInitIo(cliVersion: string): InitIo {
+  let lines: import("node:readline/promises").Interface | undefined;
+  const question = async (text: string): Promise<string> => {
+    const { createInterface } = await import("node:readline/promises");
+    lines ??= createInterface({ input: process.stdin, output: process.stdout });
+    return (await lines.question(text)).trim();
+  };
+  const spawn = (command: string, args: readonly string[], cwd: string) => {
+    try {
+      return Bun.spawnSync([command, ...args], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    } catch {
+      return undefined;
+    }
+  };
+  return {
+    cwd: process.cwd(),
+    cliVersion,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    log: (line) => console.log(line),
+    warn: (line) => console.log(amber(line)),
+    ask: async (text, fallback) => (await question(`${text} (${fallback}) `)) || fallback,
+    choose: async (text, choices, fallback) => {
+      console.log(text);
+      choices.forEach((choice, at) => console.log(`  ${at + 1}) ${choice.label}`));
+      for (;;) {
+        const answer = await question(`> (${choices.findIndex((choice) => choice.value === fallback) + 1}) `);
+        if (answer === "") return fallback;
+        const picked = choices[Number(answer) - 1] ?? choices.find((choice) => choice.value === answer);
+        if (picked) return picked.value;
+      }
+    },
+    confirm: async (text, fallback) => {
+      const answer = (await question(`${text} ${fallback ? "[Y/n]" : "[y/N]"} `)).toLowerCase();
+      return answer === "" ? fallback : answer.startsWith("y");
+    },
+    run: async (command, args, cwd) => {
+      try {
+        const child = Bun.spawn([command, ...args], { cwd, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+        return await child.exited;
+      } catch {
+        return 127;
+      }
+    },
+    capture: async (command, args, cwd) => {
+      const result = spawn(command, args, cwd);
+      return { code: result?.exitCode ?? 127, stdout: result?.stdout.toString() ?? "" };
+    },
+    close: () => lines?.close(),
+  };
+}