sproutboat 0.9.0 → 0.10.1

package/src/dev.ts

@@ -11,7 +11,8 @@
  * project, one port.
  */
 import { existsSync, watch, type FSWatcher } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { connect } from "node:net";
 import { dirname, resolve } from "node:path";
 import { buildArtifact } from "./build";
 import { createBroker, listen, type Bindings, type Broker } from "./broker";
@@ -29,10 +30,27 @@ export type DevInput = {
   source: string;
   port: number;
   watch: boolean;
-  /** Re-bundle and re-validate after a file changes; throws with a readable message. */
-  rebuild: () => Promise<string>;
+  /** Re-read the complete project after a change; throws with a readable message. */
+  rebuild: () => Promise<Pick<DevInput, "config" | "sourcePath" | "source">>;
+  /** Set internally for an asset-only refresh, where recompiling is unnecessary. */
+  reuseSproutPath?: string;
+  /** Test seam: production always uses the native artifact starter below. */
+  candidateFactory?: (input: DevInput, port: number) => Promise<Running>;
+  /** Test seam: avoid terminating Bun's test process on a simulated signal. */
+  exitOnShutdown?: boolean;
+  /** Clock seam for reload observability tests. */
+  now?: () => number;
+  /** Called once a replacement is ready and the stable route has switched. */
+  onReload?: (timing: { editToReadyMs: number; downtimeMs: number }) => void;
 };
 
+export function isAssetOnlyRefresh(
+  current: Pick<DevInput, "config" | "source">,
+  next: Pick<DevInput, "config" | "source">,
+): boolean {
+  return next.source === current.source && JSON.stringify(next.config) === JSON.stringify(current.config);
+}
+
 /**
  * Secrets for local dev, `KEY=value` per line, from `.dev.vars` beside the
  * config — the same file Wrangler uses. Deployed secrets live in the control
@@ -70,70 +88,118 @@ async function readBindings(artifactDir: string): Promise<Partial<Bindings> | un
   return record as Partial<Bindings> | undefined;
 }
 
-type Running = {
+export type Running = {
   sprout: Bun.Subprocess;
+  sproutPath: string;
+  artifactDir: string;
   broker: Broker;
   stopBroker: () => void;
   /** Set before a kill we initiated, so its exit code is not reported as a crash. */
   expected: boolean;
+  port: number;
+  enableDispatch: () => void;
+  disableDispatch: () => void;
 };
 
-async function start(input: DevInput, source: string): Promise<Running> {
-  const artifact = await buildArtifact({
-    projectDir: input.projectDir,
-    config: input.config,
-    sourcePath: input.sourcePath,
-    source,
-    target: "host",
-    // Never deployable, rebuilt on every edit: buy the iteration loop.
-    optimize: "dev",
-  });
+async function start(input: DevInput, port: number): Promise<Running> {
+  const candidateDir = resolve(
+    input.projectDir,
+    ".sproutboat/dev-build",
+    `${Date.now()}-${Math.random().toString(16).slice(2)}`,
+  );
+  let artifact;
+  try {
+    artifact = await buildArtifact({
+      projectDir: input.projectDir,
+      config: input.config,
+      sourcePath: input.sourcePath,
+      source: input.source,
+      target: "host",
+      // Never deployable, rebuilt on every edit: buy the iteration loop.
+      optimize: "dev",
+      reuseSproutPath: input.reuseSproutPath,
+      outputDirectory: candidateDir,
+    });
+  } catch (error) {
+    await rm(candidateDir, { recursive: true, force: true });
+    throw error;
+  }
   const artifactDir = artifact.artifactDir;
   const sproutPath = resolve(artifactDir, "sprout");
-
-  // `new Database(path, { create: true })` creates the file, never the
-  // directory above it, so a first run would fail with SQLITE_CANTOPEN.
-  const stateDir = resolve(input.projectDir, ".sproutboat/dev");
-  await mkdir(stateDir, { recursive: true });
-  const assetsDir = resolve(artifactDir, "assets");
-  const broker = createBroker({
-    db: resolve(stateDir, "state.sqlite"),
-    dataDir: resolve(stateDir, "d1"),
-    resourceDir: resolve(stateDir, "resources"),
-    token: "sproutboat-dev",
-    bindings: await readBindings(artifactDir),
-    secrets: await readDevVars(input.projectDir),
-    sproutUrl: `http://127.0.0.1:${input.port}/`,
-    assetsDir: existsSync(assetsDir) ? assetsDir : undefined,
-  });
-  const server = listen(broker, "127.0.0.1", 0);
-
-  const sprout = Bun.spawn([sproutPath], {
-    cwd: dirname(sproutPath),
-    env: {
-      ...process.env,
-      PORT: String(input.port),
-      SB_BROKER_PORT: String(server.port),
-      SB_BROKER_TOKEN: "sproutboat-dev",
-    },
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-  return {
-    sprout,
-    broker,
-    stopBroker: () => {
+  let dispatchEnabled = false;
+  try {
+    const stateDir = resolve(input.projectDir, ".sproutboat/dev");
+    await mkdir(stateDir, { recursive: true });
+    const assetsDir = resolve(artifactDir, "assets");
+    const broker = createBroker({
+      db: resolve(stateDir, "state.sqlite"),
+      dataDir: resolve(stateDir, "d1"),
+      resourceDir: resolve(stateDir, "resources"),
+      token: "sproutboat-dev",
+      bindings: await readBindings(artifactDir),
+      secrets: await readDevVars(input.projectDir),
+      sproutUrl: `http://127.0.0.1:${port}/`,
+      assetsDir: existsSync(assetsDir) ? assetsDir : undefined,
+      dispatchEnabled: () => dispatchEnabled,
+    });
+    let server: ReturnType<typeof listen>;
+    try {
+      server = listen(broker, "127.0.0.1", 0);
+    } catch (error) {
+      broker.close();
+      throw error;
+    }
+    let sprout: Bun.Subprocess;
+    try {
+      sprout = Bun.spawn([sproutPath], {
+        cwd: dirname(sproutPath),
+        env: {
+          ...process.env,
+          PORT: String(port),
+          SB_BROKER_PORT: String(server.port),
+          SB_BROKER_TOKEN: "sproutboat-dev",
+        },
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+    } catch (error) {
       server.stop();
       broker.close();
-    },
-    expected: false,
-  };
+      throw error;
+    }
+    return {
+      sprout,
+      sproutPath,
+      artifactDir,
+      broker,
+      stopBroker: () => {
+        server.stop();
+        broker.close();
+      },
+      expected: false,
+      port,
+      enableDispatch: () => {
+        dispatchEnabled = true;
+      },
+      disableDispatch: () => {
+        dispatchEnabled = false;
+      },
+    };
+  } catch (error) {
+    await rm(candidateDir, { recursive: true, force: true });
+    throw error;
+  }
 }
 
 function stop(running: Running): void {
+  if (running.expected) return;
   running.expected = true;
+  running.disableDispatch();
   running.sprout.kill(9);
   running.stopBroker();
+  // Every candidate owns an isolated snapshot. Once it is no longer serving,
+  // remove it so repeated edits do not grow .sproutboat/dev-build forever.
+  void rm(running.artifactDir, { recursive: true, force: true });
 }
 
 /** Report a sprout that died on its own; a kill we asked for is not news. */
@@ -144,42 +210,173 @@ function watchExit(running: Running): void {
   });
 }
 
+/** Pick an unused loopback port without keeping it reserved. The candidate is
+ * started immediately afterwards; the tiny race is preferable to interrupting
+ * the current server just to discover a bad replacement. */
+function candidatePort(): number {
+  const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
+  const port = probe.port;
+  probe.stop();
+  if (port === undefined) throw new Error("could not allocate a candidate port");
+  return port;
+}
+
+async function waitUntilReady(running: Running): Promise<void> {
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline) {
+    if (running.expected) throw new Error("candidate stopped before becoming ready");
+    const exited = await Promise.race([running.sprout.exited.then(() => true), Bun.sleep(30).then(() => false)]);
+    if (exited) throw new Error("candidate sprout exited before becoming ready");
+    if (await tcpReady(running.port, Math.min(250, deadline - Date.now()))) return;
+  }
+  throw new Error("candidate sprout did not become ready within 3s");
+}
+
+/** Readiness is a bounded TCP connect, never an application request: booting a
+ * candidate must not execute user code or wait forever on a handler. */
+export function tcpReady(port: number, timeout: number): Promise<boolean> {
+  return new Promise((resolveReady) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const finish = (ready: boolean) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolveReady(ready);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(timeout, () => finish(false));
+  });
+}
+
 /** Build, run, and (optionally) rebuild on change. Resolves only on shutdown. */
 export async function runDev(input: DevInput): Promise<void> {
-  let running = await start(input, input.source);
+  let current = input;
+  const now = input.now ?? Date.now;
+  const startCandidate = input.candidateFactory ?? start;
+  let running = await startCandidate(current, candidatePort());
+  try {
+    await waitUntilReady(running);
+  } catch (error) {
+    stop(running);
+    throw error;
+  }
+  running.enableDispatch();
+  let activePort = running.port;
+  // Keep the public port stable while candidates boot on private ports. This is
+  // 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",
+      port: input.port,
+      fetch(request) {
+        const target = new URL(request.url);
+        target.host = `127.0.0.1:${activePort}`;
+        return fetch(target, {
+          method: request.method,
+          headers: request.headers,
+          body: request.body,
+          redirect: "manual",
+        }).catch(() => new Response("sprout unavailable", { status: 502 }));
+      },
+    });
+  } catch (error) {
+    stop(running);
+    throw error;
+  }
   watchExit(running);
   console.log(ok(`${input.config.name} running on ${leaf(`http://127.0.0.1:${input.port}`)}`));
   if (input.watch) console.log(dim("  watching for changes — ctrl-c to stop"));
 
-  const watchers: FSWatcher[] = [];
+  let watchers: FSWatcher[] = [];
   let shuttingDown = false;
   let resolveShutdown: (() => void) | null = null;
+  let pendingCandidate: Running | null = null;
   const shutdown = () => {
     if (shuttingDown) return;
     shuttingDown = true;
     for (const watcher of watchers) watcher.close();
+    proxy.stop();
+    if (pendingCandidate) stop(pendingCandidate);
     stop(running);
     resolveShutdown?.();
-    process.exit(0);
+    if (input.exitOnShutdown !== false) process.exit(0);
   };
-  for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, shutdown);
+  const signals = ["SIGINT", "SIGTERM"] as const;
+  for (const signal of signals) process.on(signal, shutdown);
+  let rebuildTask: Promise<void> | null = null;
 
   if (input.watch) {
     let pending: ReturnType<typeof setTimeout> | null = null;
     let rebuilding = false;
+    let dirty = false;
+    const resetWatchers = () => {
+      for (const watcher of watchers) watcher.close();
+      const next: FSWatcher[] = [
+        watch(dirname(current.sourcePath), { recursive: true }, onChange),
+        // Watch the containing directory as well: atomic-save editors replace
+        // the config inode, which otherwise silently detaches a file watcher.
+        watch(current.projectDir, { recursive: false }, onChange),
+      ];
+      if (current.config.assets) {
+        const assets = resolve(current.projectDir, current.config.assets.directory);
+        // The parent sees a generated directory being atomically replaced;
+        // the directory watcher sees updates inside an existing snapshot.
+        next.push(watch(dirname(assets), { recursive: false }, onChange));
+        if (existsSync(assets)) next.push(watch(assets, { recursive: true }, onChange));
+      }
+      watchers = next;
+    };
     const onChange = () => {
+      dirty = true;
       if (pending !== null) clearTimeout(pending);
       // Editors write a file in several syscalls; one save should be one build.
       pending = setTimeout(() => {
-        void (async () => {
+        rebuildTask = (async () => {
           if (rebuilding || shuttingDown) return;
           rebuilding = true;
           try {
-            const source = await input.rebuild();
+            dirty = false;
+            const editStartedAt = now();
+            const next = await current.rebuild();
             console.log(dim("  change detected, rebuilding…"));
-            stop(running);
-            running = await start(input, source);
+            const assetOnly = isAssetOnlyRefresh(current, next);
+            const candidate = await startCandidate(
+              { ...current, ...next, reuseSproutPath: assetOnly ? running.sproutPath : undefined },
+              candidatePort(),
+            );
+            pendingCandidate = candidate;
+            if (shuttingDown) {
+              stop(candidate);
+              pendingCandidate = null;
+              return;
+            }
+            try {
+              await waitUntilReady(candidate);
+            } catch (error) {
+              stop(candidate);
+              pendingCandidate = null;
+              throw error;
+            }
+            if (shuttingDown) {
+              stop(candidate);
+              pendingCandidate = null;
+              return;
+            }
+            // Only now is the public route switched. The old process stays up
+            // through compilation and candidate startup.
+            const previous = running;
+            previous.disableDispatch();
+            candidate.enableDispatch();
+            running = candidate;
+            pendingCandidate = null;
+            current = { ...current, ...next };
+            const switchedAt = now();
+            activePort = candidate.port;
+            resetWatchers();
+            stop(previous);
             watchExit(running);
+            input.onReload?.({ editToReadyMs: switchedAt - editStartedAt, downtimeMs: now() - switchedAt });
             console.log(ok(`  reloaded on http://127.0.0.1:${input.port}`));
           } catch (cause) {
             // Keep the last good build serving; a typo should not take the
@@ -191,14 +388,13 @@ export async function runDev(input: DevInput): Promise<void> {
             );
           } finally {
             rebuilding = false;
+            if (dirty && !shuttingDown) onChange();
           }
         })();
+        void rebuildTask;
       }, RESTART_DEBOUNCE_MS);
     };
-    // The entry's directory covers the usual `src/` layout; the config itself
-    // changes bindings, so it needs a rebuild too.
-    watchers.push(watch(dirname(input.sourcePath), { recursive: true }, onChange));
-    watchers.push(watch(resolve(input.projectDir, "sproutboat.jsonc"), onChange));
+    resetWatchers();
   }
 
   // Watching, we stay up until a signal: a crashed sprout is something to fix
@@ -208,8 +404,13 @@ export async function runDev(input: DevInput): Promise<void> {
     await new Promise<void>((resolve) => {
       resolveShutdown = resolve;
     });
+    // A signal can arrive while a candidate factory is building. Let that task
+    // return its newly-created resources to the coordinator, which observes
+    // `shuttingDown` and stops them, before declaring shutdown complete.
+    await rebuildTask;
   } else {
     await running.sprout.exited;
     stop(running);
   }
+  for (const signal of signals) process.off(signal, shutdown);
 }

package/src/json.ts

@@ -1,38 +1,3 @@
-/**
- * The one JSON contract the CLI decodes external payloads through: registry
- * responses, control-plane responses, broker request bodies. Parse at the I/O
- * boundary with `parseJsonValue`, then narrow with these guards — nothing
- * downstream should see an unparsed value.
- */
-export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
-export type JsonObject = { [key: string]: JsonValue };
-
-export function isString(value: JsonValue | undefined): value is string {
-  return value !== undefined && value === String(value);
-}
-
-export function isSafeInteger(value: JsonValue | undefined): value is number {
-  return Number.isSafeInteger(value);
-}
-
-export function isBoolean(value: JsonValue | undefined): value is boolean {
-  return value === true || value === false;
-}
-
-export function parseJsonValue(source: string): JsonValue {
-  const value = JSON.parse(source);
-  if (
-    value === null ||
-    value === true ||
-    value === false ||
-    value === String(value) ||
-    Number.isFinite(value) ||
-    value instanceof Object
-  )
-    return value;
-  throw new Error("response was not valid JSON");
-}
-
-export function jsonObject(value: JsonValue): JsonObject | undefined {
-  return value instanceof Object && !Array.isArray(value) ? value : undefined;
-}
+// Re-exported from @sproutboat/wire (moved verbatim with broker.ts).
+// This shim keeps every `./json` importer working.
+export * from "@sproutboat/wire";

package/src/main.ts

@@ -18,6 +18,19 @@ import { helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type StorageProduct } from "
 import { notifyIfOutdated } from "./update-check";
 import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
+import { pathToFileURL } from "node:url";
+
+// A compiled Bun executable is not a general-purpose `bun` command. Porffor
+// is acquired after installation, so run its external ESM launcher through an
+// explicit private mode inside the packaged runtime.
+const internalModeAt = process.argv.slice(1, 3).indexOf("__porffor") + 1;
+if (internalModeAt > 0) {
+  const launcher = process.argv[internalModeAt + 1];
+  if (!launcher) throw new Error("internal Porffor mode requires a launcher path");
+  process.argv.splice(1, internalModeAt + 1, launcher);
+  await import(pathToFileURL(launcher).href);
+  process.exit(0);
+}
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
 
@@ -165,7 +178,9 @@ function usageError(what: string, usage: string): never {
   process.exit(2);
 }
 
-async function readProject(directory = process.cwd()) {
+/** Read the project identity and configuration without touching application code.
+ * Management commands must remain usable when a local checkout is incomplete. */
+async function readProjectConfig(directory = process.cwd()) {
   const projectDirectory = resolve(directory);
   const configPath = resolve(projectDirectory, "sproutboat.jsonc");
   let configSource: string;
@@ -176,25 +191,31 @@ async function readProject(directory = process.cwd()) {
   }
   const parsed = parseConfig(configSource);
   if (!parsed.ok) fail(parsed.errors.join("\n"));
-  const sourcePath = resolve(projectDirectory, parsed.value.main);
+  return { directory: projectDirectory, config: parsed.value };
+}
+
+/** Full build input: configuration plus entry point, resolved imports and checks. */
+async function readProject(directory = process.cwd()) {
+  const project = await readProjectConfig(directory);
+  const sourcePath = resolve(project.directory, project.config.main);
   let source: string;
   try {
     source = await readFile(sourcePath, "utf8");
   } catch {
-    fail(`entry point not found: ${parsed.value.main}`);
+    fail(`entry point not found: ${project.config.main}`);
   }
   // #89 — resolve imports first, then hold the *bundled* module to the
   // capability rules. Validating the entry file instead would let a dependency
   // smuggle in a Node API the handler is not allowed to touch.
   let bundle: BundleResult;
   try {
-    bundle = await bundleHandler(sourcePath, projectDirectory);
+    bundle = await bundleHandler(sourcePath, project.directory);
   } catch (cause) {
     fail(cause instanceof BundleError ? cause.message : String(cause));
   }
-  const supported = validateHttpSyncSource(bundle.code, (parsed.value.outbound ?? []).length > 0);
+  const supported = validateHttpSyncSource(bundle.code, (project.config.outbound ?? []).length > 0);
   if (!supported.ok) fail(supported.errors.join("\n"));
-  return { directory: projectDirectory, config: parsed.value, sourcePath, source, bundle };
+  return { ...project, sourcePath, source, bundle };
 }
 
 async function init(name = "hello") {
@@ -329,7 +350,11 @@ async function dev(args: string[]) {
     watch: !args.includes("--no-watch"),
     // Re-read from disk on every rebuild: the point of watching is that the
     // files changed, so the bundle captured at startup is stale by definition.
-    rebuild: async () => (await readProject(directory)).bundle.code,
+    rebuild: async () => {
+      const next = await readProject(directory);
+      await refreshTypes(next.directory, next.config);
+      return { config: next.config, sourcePath: next.sourcePath, source: next.bundle.code };
+    },
   });
 }
 
@@ -631,7 +656,7 @@ async function versions(args: string[]) {
   if (sub === "view") {
     const id = args.shift();
     if (!id) usageError("versions view: missing <version-id>", "versions view <version-id> [project-dir]");
-    const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
+    const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(args[0]), apiCredentials()]);
     const body = await responseText(
       await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments/${encodeURIComponent(id)}`, {
         headers: { "x-api-key": token },
@@ -662,7 +687,7 @@ async function versions(args: string[]) {
     return;
   }
 
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(args[0]), apiCredentials()]);
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments`, {
     headers: { "x-api-key": token },
   });
@@ -677,7 +702,7 @@ async function versions(args: string[]) {
 async function rollback(args: string[]) {
   const id = args[0];
   if (!id) usageError("rollback: missing <version-id>", "rollback <version-id> [project-dir]");
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[1]), apiCredentials()]);
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(args[1]), apiCredentials()]);
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments/${id}/activate`, {
     method: "POST",
     headers: { "x-api-key": token },
@@ -691,7 +716,7 @@ async function rollback(args: string[]) {
 async function tail(args: string[]) {
   const sproutLog = args.includes("--sprout");
   const dir = args.find((arg) => !arg.startsWith("-"));
-  const [project, { apiUrl, token }] = await Promise.all([readProject(dir), apiCredentials()]);
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(dir), apiCredentials()]);
   const path = sproutLog ? "logs/sprout" : "logs/recent";
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/${path}`, {
     headers: { "x-api-key": token },
@@ -746,7 +771,7 @@ async function domains(args: string[]) {
   const host = sub === "list" ? undefined : args.shift();
   if (sub !== "list" && !host)
     usageError(`domains ${sub}: missing <hostname>`, `domains ${sub} <hostname> [project-dir]`);
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(args[0]), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}/domains`;
   const auth = { "x-api-key": token };
 
@@ -803,7 +828,7 @@ async function secrets(args: string[]) {
   const name = sub === "list" ? undefined : positional.shift();
   if (sub !== "list" && !name) usageError(`secrets ${sub}: missing <NAME>`, `secrets ${sub} <NAME> [project-dir]`);
   if (name && !/^[A-Z][A-Z0-9_]*$/.test(name)) fail("secret name must be UPPER_SNAKE_CASE");
-  const [project, { apiUrl, token }] = await Promise.all([readProject(positional[0]), apiCredentials()]);
+  const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(positional[0]), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}/secrets`;
   const auth = { "x-api-key": token };
 
@@ -1133,7 +1158,7 @@ async function deleteProject(args: string[]) {
   }
 
   const { apiUrl, token } = await apiCredentials();
-  const name = explicitName ?? (await readProject(positional[0])).config.name;
+  const name = explicitName ?? (await readProjectConfig(positional[0])).config.name;
   if (!confirmed) fail(`this permanently removes "${name}", every version, and its route — re-run with --yes`);
 
   const url = `${apiUrl}/api/projects/${encodeURIComponent(name)}?confirm=${encodeURIComponent(name)}`;