sproutboat 0.4.11 → 0.6.0

package/src/bundle.ts

@@ -0,0 +1,70 @@
+/**
+ * #89 — bundle the handler before Porffor sees it.
+ *
+ * Porffor compiles one self-contained module, so until now a project was one
+ * file with no imports: no router, no validation library, no SDK, no splitting
+ * a codebase in two. Bundling first lifts that without touching the compiler.
+ *
+ * Bun's bundler resolves relative imports across the project and bare
+ * specifiers out of the project's own `node_modules`, then emits a single ESM
+ * module. The capability bans (`process`, `Bun`, `node:`, WebSocket, …) are
+ * checked against that output rather than the entry file, so a dependency
+ * reaching for a Node API fails exactly as user code would.
+ */
+import { relative } from "node:path";
+
+export type BundleResult = {
+  /** One self-contained ESM module: what gets validated, hashed, and compiled. */
+  code: string;
+};
+
+export class BundleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BundleError";
+  }
+}
+
+const entryLabel = (entryPath: string, projectDir: string): string => relative(projectDir, entryPath) || entryPath;
+
+/** Bun reports resolution failures on `AggregateError.errors`; its own message is just "Bundle failed". */
+function bundleDetail(cause: unknown): string {
+  const errors = cause instanceof AggregateError ? cause.errors : [];
+  if (errors.length > 0)
+    return errors.map((error) => `  ${error instanceof Error ? error.message : String(error)}`).join("\n");
+  return `  ${cause instanceof Error ? cause.message : String(cause)}`;
+}
+
+/** Bundle `entryPath` into a single module, resolving imports from `projectDir`. */
+export async function bundleHandler(entryPath: string, projectDir: string): Promise<BundleResult> {
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [entryPath],
+      root: projectDir,
+      // `browser` keeps the output free of Node shims — a dependency that wants
+      // `process` must fail the capability check, not get a polyfill smuggled in.
+      target: "browser",
+      format: "esm",
+      // Readability over size: a compile error from Porffor should point at
+      // something a human can find, and Porffor strips the binary anyway.
+      minify: false,
+      splitting: false,
+      sourcemap: "none",
+    });
+  } catch (cause) {
+    // An unresolvable specifier arrives as an AggregateError whose `errors`
+    // carry the useful part ("Could not resolve: ./missing.js"); the top-level
+    // message is only "Bundle failed", which tells nobody which import broke.
+    throw new BundleError(`could not bundle ${entryLabel(entryPath, projectDir)}:\n${bundleDetail(cause)}`);
+  }
+
+  if (!built.success) {
+    const detail = built.logs.map((log) => `  ${log.message}`).join("\n");
+    throw new BundleError(`could not bundle ${entryLabel(entryPath, projectDir)}:\n${detail}`);
+  }
+  const [output] = built.outputs;
+  if (output === undefined) throw new BundleError("the bundler produced no output");
+
+  return { code: await output.text() };
+}

package/src/compile.ts

@@ -9,7 +9,7 @@
  * shipped in `vendor/` so this needs no `git` or `make`; if that archive is
  * unusable it falls back to Porffor's own git + make path (needs both on PATH).
  */
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
 import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
@@ -21,10 +21,20 @@ const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 6
 
 export type CompileInput = {
   sourcePath: string;
+  /** The bundled module (#89). Falls back to reading `sourcePath` verbatim. */
+  source?: string;
   outPath: string;
   vars: Record<string, string>;
   bindings?: Bindings;
-  zigBin: string;
+  /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
+  zigBin?: string;
+  /**
+   * `linux-x86_64` (default) cross-compiles the static musl binary every box
+   * runs. `host` compiles for the machine doing the build (#62) so `sproutboat
+   * dev` can actually serve a sprout on a developer's laptop — an arm64 Mac
+   * cannot execute the deploy artifact.
+   */
+  target?: "linux-x86_64" | "host";
 };
 
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
@@ -41,38 +51,56 @@ export async function compileSprout(input: CompileInput): Promise<void> {
     const haveGit = Bun.which("git");
     const haveMake = Bun.which("make");
     if (haveGit && haveMake) {
-      console.warn(`prebuilt uWebSockets unusable (${error.message.split("\n")[0]}); falling back to git + make (slower, one-time)`);
+      console.warn(
+        `prebuilt uWebSockets unusable (${error.message.split("\n")[0]}); falling back to git + make (slower, one-time)`,
+      );
     } else {
       const missing = [!haveGit && "git", !haveMake && "make"].filter(Boolean).join(" and ");
       throw new Error(
         `${error.message}\n\nThe prebuilt uWebSockets is unusable, and ${missing} ` +
-        `${missing.includes("and") ? "are" : "is"} not on PATH for the fallback build. ` +
-        `Install ${missing}, or set SPROUTBOAT_UWS_TARBALL to a valid archive.`,
+          `${missing.includes("and") ? "are" : "is"} not on PATH for the fallback build. ` +
+          `Install ${missing}, or set SPROUTBOAT_UWS_TARBALL to a valid archive.`,
       );
     }
   }
 
   const outDir = dirname(input.outPath);
   await mkdir(outDir, { recursive: true });
+  // The artifact dir is content-addressed, so rebuilding unchanged source lands
+  // on the previous binary — which `chmod 0555` left read-only, and which the
+  // OS may still be executing. The linker cannot overwrite either, so clear it
+  // first rather than failing with "can't write output file".
+  await rm(input.outPath, { force: true });
   const generatedPath = resolve(outDir, "sprout.generated.js");
-  const [source, prelude] = await Promise.all([readFile(input.sourcePath, "utf8"), readFile(preludePath, "utf8")]);
+  const [source, prelude] = await Promise.all([
+    input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
+    readFile(preludePath, "utf8"),
+  ]);
   await writeFile(generatedPath, wrapNativeFetchHandler(source, prelude, input.vars, input.bindings ?? EMPTY_BINDINGS));
 
   const porffor = porfforRoot();
   const launcher = resolve(porffor, "runtime/index.js");
   // Porffor shells bare `zig` and `esbuild`; put both on PATH for the child.
+  // A host build never shells `zig`, so it has no zigBin to contribute.
   const binDir = resolve(porffor, "../.bin");
-  const path = `${dirname(input.zigBin)}:${binDir}:${process.env.PATH ?? ""}`;
+  const zigDir = input.zigBin ? `${dirname(input.zigBin)}:` : "";
+  const path = `${zigDir}${binDir}:${process.env.PATH ?? ""}`;
 
   // `-s`: strip at link. The unstripped static-musl binary is ~90% DWARF that
   // nothing needs at runtime (12 MB -> ~1.3 MB for the kitchen-sink). Porffor
   // forwards `-s` straight to the `zig cc` link step.
+  // `--musl` is what makes it a cross-compile; a host build simply omits it and
+  // Porffor targets the machine it is running on.
+  const crossFlags = input.target === "host" ? [] : ["--musl"];
   const child = Bun.spawn(
-    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, "--musl", "-s"],
+    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, ...crossFlags, "-s"],
     { cwd: outDir, stdout: "pipe", stderr: "pipe", env: { ...process.env, PATH: path } },
   );
   let timedOut = false;
-  const timer = setTimeout(() => { timedOut = true; child.kill(); }, COMPILE_TIMEOUT_MS);
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill();
+  }, COMPILE_TIMEOUT_MS);
   const [code, stdout, stderr] = await Promise.all([
     child.exited,
     new Response(child.stdout).text(),

package/src/config.ts

@@ -4,14 +4,16 @@ const slugPattern = /^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])?$/;
  * A storage binding entry (#74). Either a bare `"BINDING"` — resolved to an
  * ephemeral local resource for `sproutboat dev`, rejected by a real deploy — or
  * `{ binding, id }` pointing at an account-level resource created with
- * `sproutboat resource create`. The id carries its own `<kind>_` prefix.
+ * `sproutboat <kv|d1|r2|queues> create`. The id carries its own `<kind>_` prefix.
  */
 export type ResourceBinding = { binding: string; id: string };
 export type ResourceRef = string | ResourceBinding;
 
 /** Normalizes a storage-binding array to `{ binding, id? }` rows. */
 export function resourceRefs(field: readonly ResourceRef[] | undefined): Array<{ binding: string; id?: string }> {
-  return (field ?? []).map((entry) => (isString(entry) ? { binding: entry } : { binding: entry.binding, id: entry.id }));
+  return (field ?? []).map((entry) =>
+    isString(entry) ? { binding: entry } : { binding: entry.binding, id: entry.id },
+  );
 }
 
 /**
@@ -73,9 +75,7 @@ export type AssetsConfig = {
   run_sprout_first?: boolean | string[];
 };
 
-export type ConfigValidation =
-  | { ok: true; value: SproutboatConfig }
-  | { ok: false; errors: string[] };
+export type ConfigValidation = { ok: true; value: SproutboatConfig } | { ok: false; errors: string[] };
 
 type JsonValue = string | number | boolean | null | ConfigJsonObject | JsonValue[];
 
@@ -86,8 +86,7 @@ interface ConfigJsonObject {
 type ConfigInput = JsonValue | undefined;
 
 function isRecord(value: ConfigInput): value is ConfigJsonObject {
-  return value !== null && Object(value) === value && !Array.isArray(value)
-    && !(value instanceof Function);
+  return value !== null && Object(value) === value && !Array.isArray(value) && !(value instanceof Function);
 }
 
 function isString(value: ConfigInput): value is string {
@@ -102,9 +101,21 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   const errors: string[] = [];
   if (!isRecord(value)) return { ok: false, errors: ["config must be an object"] };
   const allowed = new Set([
-    "$schema", "name", "main", "compatibility_date", "vars",
-    "kv_namespaces", "secrets", "outbound", "d1_databases", "r2_buckets",
-    "queues", "analytics_engine_datasets", "durable_objects", "triggers", "assets",
+    "$schema",
+    "name",
+    "main",
+    "compatibility_date",
+    "vars",
+    "kv_namespaces",
+    "secrets",
+    "outbound",
+    "d1_databases",
+    "r2_buckets",
+    "queues",
+    "analytics_engine_datasets",
+    "durable_objects",
+    "triggers",
+    "assets",
   ]);
   for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push(`unsupported config field: ${key}`);
   const name = isString(value.name) && isProjectSlug(value.name) ? value.name : null;
@@ -115,7 +126,10 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   if (main === null) {
     errors.push("main must be a relative entry point under src/");
   }
-  const compatibility_date = isString(value.compatibility_date) && /^\d{4}-\d{2}-\d{2}$/.test(value.compatibility_date) ? value.compatibility_date : null;
+  const compatibility_date =
+    isString(value.compatibility_date) && /^\d{4}-\d{2}-\d{2}$/.test(value.compatibility_date)
+      ? value.compatibility_date
+      : null;
   if (compatibility_date === null) {
     errors.push("compatibility_date must use YYYY-MM-DD");
   }
@@ -127,7 +141,8 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     else {
       vars = {};
       for (const [key, item] of Object.entries(value.vars)) {
-        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || !isString(item)) errors.push(`vars.${key} must be a string environment name`);
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || !isString(item))
+          errors.push(`vars.${key} must be a string environment name`);
         else vars[key] = item;
       }
     }
@@ -174,9 +189,14 @@ function validateConfig(value: ConfigInput): ConfigValidation {
       if (isString(entry)) {
         if (bindingName.test(entry)) out.push(entry);
         else errors.push(`${field}: "${entry}" must be an UPPER_SNAKE binding name`);
-      } else if (isRecord(entry) && isString(entry.binding) && isString(entry.id)
-        && bindingName.test(entry.binding) && idPattern.test(entry.id)
-        && Object.keys(entry).every((key) => key === "binding" || key === "id")) {
+      } else if (
+        isRecord(entry) &&
+        isString(entry.binding) &&
+        isString(entry.id) &&
+        bindingName.test(entry.binding) &&
+        idPattern.test(entry.id) &&
+        Object.keys(entry).every((key) => key === "binding" || key === "id")
+      ) {
         out.push({ binding: entry.binding, id: entry.id });
       } else {
         errors.push(`${field} entries must be an UPPER_SNAKE name or { binding: "NAME", id: "${kind}_…" }`);
@@ -189,7 +209,11 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   const outbound = stringArray("outbound", hostPattern, "hostnames");
   // Analytics Engine datasets aren't provisioned — the dataset name springs into
   // existence on first writeDataPoint(), so there's no resource id to bind (#74).
-  const analytics_engine_datasets = stringArray("analytics_engine_datasets", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const analytics_engine_datasets = stringArray(
+    "analytics_engine_datasets",
+    bindingName,
+    "binding names (UPPER_SNAKE_CASE)",
+  );
   const kv_namespaces = resourceArray("kv_namespaces", "kv");
   const d1_databases = resourceArray("d1_databases", "d1");
   const r2_buckets = resourceArray("r2_buckets", "r2");
@@ -198,7 +222,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   let durable_objects: Record<string, string> | undefined;
   if (value.durable_objects !== undefined) {
     if (!isRecord(value.durable_objects)) {
-      errors.push("durable_objects must be an object of { BINDING_NAME: \"ClassName\" }");
+      errors.push('durable_objects must be an object of { BINDING_NAME: "ClassName" }');
     } else {
       durable_objects = {};
       for (const [binding, className] of Object.entries(value.durable_objects)) {
@@ -230,15 +254,24 @@ function validateConfig(value: ConfigInput): ConfigValidation {
       errors.push("assets must be an object with a `directory`");
     } else {
       const raw = value.assets;
-      const dir = isString(raw.directory) && raw.directory.length > 0 && !raw.directory.includes("..")
-        ? raw.directory.replace(/^\.\//, "").replace(/\/$/, "")
-        : null;
+      const dir =
+        isString(raw.directory) && raw.directory.length > 0 && !raw.directory.includes("..")
+          ? raw.directory.replace(/^\.\//, "").replace(/\/$/, "")
+          : null;
       if (dir === null) errors.push("assets.directory must be a project-relative path");
-      const binding = raw.binding === undefined ? undefined
-        : isString(raw.binding) && bindingName.test(raw.binding) ? raw.binding : null;
+      const binding =
+        raw.binding === undefined
+          ? undefined
+          : isString(raw.binding) && bindingName.test(raw.binding)
+            ? raw.binding
+            : null;
       if (binding === null) errors.push("assets.binding must be a binding name (UPPER_SNAKE_CASE)");
-      const nfh = raw.not_found_handling === "none" || raw.not_found_handling === "single-page-application"
-        || raw.not_found_handling === "404-page" ? raw.not_found_handling : undefined;
+      const nfh =
+        raw.not_found_handling === "none" ||
+        raw.not_found_handling === "single-page-application" ||
+        raw.not_found_handling === "404-page"
+          ? raw.not_found_handling
+          : undefined;
       if (raw.not_found_handling !== undefined && nfh === undefined) {
         errors.push('assets.not_found_handling must be "none", "single-page-application", or "404-page"');
       }
@@ -259,16 +292,22 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     }
   }
 
-  const resourceNames = (refs: ResourceRef[] | undefined): string[] =>
-    resourceRefs(refs).map((ref) => ref.binding);
+  const resourceNames = (refs: ResourceRef[] | undefined): string[] => resourceRefs(refs).map((ref) => ref.binding);
   const bindingSlots = [
-    ...resourceNames(kv_namespaces), ...(secrets ?? []), ...resourceNames(d1_databases), ...resourceNames(r2_buckets),
-    ...resourceNames(queues), ...(analytics_engine_datasets ?? []), ...Object.keys(durable_objects ?? {}), ...Object.keys(vars ?? {}),
+    ...resourceNames(kv_namespaces),
+    ...(secrets ?? []),
+    ...resourceNames(d1_databases),
+    ...resourceNames(r2_buckets),
+    ...resourceNames(queues),
+    ...(analytics_engine_datasets ?? []),
+    ...Object.keys(durable_objects ?? {}),
+    ...Object.keys(vars ?? {}),
     ...(assets?.binding ? [assets.binding] : []),
   ];
   if (new Set(bindingSlots).size !== bindingSlots.length) errors.push("vars and binding names must not collide");
 
-  if (errors.length || name === null || main === null || compatibility_date === null || schema === null) return { ok: false, errors };
+  if (errors.length || name === null || main === null || compatibility_date === null || schema === null)
+    return { ok: false, errors };
   const config: SproutboatConfig = { name, main, compatibility_date };
   if ("$schema" in value) config.$schema = schema;
   if ("vars" in value) config.vars = vars;
@@ -307,6 +346,9 @@ export function parseConfig(source: string): ConfigValidation {
     json = json.replace(/,\s*([}\]])/g, "$1");
     return validateConfig(JSON.parse(json));
   } catch (error) {
-    return { ok: false, errors: [`invalid sproutboat.jsonc: ${error instanceof Error ? error.message : String(error)}`] };
+    return {
+      ok: false,
+      errors: [`invalid sproutboat.jsonc: ${error instanceof Error ? error.message : String(error)}`],
+    };
   }
 }

package/src/credentials.ts

@@ -59,12 +59,29 @@ export async function activeApiUrl(): Promise<string | undefined> {
   return (await readCredentials()).activeApiUrl;
 }
 
+/** #79 `logout`: drop one endpoint's token. Returns false when none was stored. */
+export async function forgetToken(apiUrl: string): Promise<boolean> {
+  const credentials = await readCredentials();
+  if (!credentials.profiles[apiUrl]) return false;
+  delete credentials.profiles[apiUrl];
+  if (credentials.activeApiUrl === apiUrl) {
+    credentials.activeApiUrl = Object.keys(credentials.profiles)[0];
+  }
+  await writeCredentials(credentials);
+  return true;
+}
+
 export async function saveToken(apiUrl: string, token: string): Promise<void> {
-  const directory = configDirectory();
-  const path = credentialsPath();
   const credentials = await readCredentials();
   credentials.profiles[apiUrl] = { token };
   credentials.activeApiUrl = apiUrl;
+  await writeCredentials(credentials);
+}
+
+/** Atomic 0600 write of the whole credentials file. */
+async function writeCredentials(credentials: Credentials): Promise<void> {
+  const directory = configDirectory();
+  const path = credentialsPath();
   await mkdir(directory, { recursive: true, mode: 0o700 });
   await chmod(directory, 0o700);
   const temporary = `${path}.tmp-${crypto.randomUUID()}`;

package/src/dev.ts

@@ -0,0 +1,213 @@
+/**
+ * #62 — `sproutboat dev`: the project running on this machine, rebuilt on save.
+ *
+ * The platform's own local stack (control + edge + supervisor) exists to serve
+ * *deployed* artifacts, which are linux-x86_64 and cannot execute on a laptop.
+ * This is the other half: build for the host (#62), stand up the same broker
+ * the supervisor would, and run the sprout against it — so `env.KV`, secrets,
+ * cron and the rest behave the way they will in production without a deploy.
+ *
+ * Deliberately not the platform: no control plane, no TLS, no routing. One
+ * project, one port.
+ */
+import { existsSync, watch, type FSWatcher } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildArtifact } from "./build";
+import { createBroker, listen, type Bindings, type Broker } from "./broker";
+import { jsonObject, parseJsonValue } from "./json";
+import { amber, dim, leaf, ok } from "./style";
+import type { SproutboatConfig } from "./config";
+
+const RESTART_DEBOUNCE_MS = 120;
+
+export type DevInput = {
+  projectDir: string;
+  config: SproutboatConfig;
+  sourcePath: string;
+  /** The bundled module (#89) — already validated by the caller. */
+  source: string;
+  port: number;
+  watch: boolean;
+  /** Re-bundle and re-validate after a file changes; throws with a readable message. */
+  rebuild: () => Promise<string>;
+};
+
+/**
+ * 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
+ * plane and are never on a developer's disk, so this is the only way a bound
+ * secret can resolve here.
+ */
+async function readDevVars(projectDir: string): Promise<Record<string, string>> {
+  const path = resolve(projectDir, ".dev.vars");
+  if (!existsSync(path)) return {};
+  const text = await readFile(path, "utf8");
+  return Object.fromEntries(
+    text.split("\n").flatMap((line): Array<[string, string]> => {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) return [];
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) return [];
+      const value = trimmed.slice(eq + 1).trim();
+      // Accept quoted values, since a secret can legitimately contain spaces.
+      const unquoted =
+        (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))
+          ? value.slice(1, -1)
+          : value;
+      return [[trimmed.slice(0, eq).trim(), unquoted]];
+    }),
+  );
+}
+
+/** `bindings.json` is written by the build whenever the project declares any. */
+async function readBindings(artifactDir: string): Promise<Partial<Bindings> | undefined> {
+  const path = resolve(artifactDir, "bindings.json");
+  if (!existsSync(path)) return undefined;
+  const record = jsonObject(parseJsonValue(await readFile(path, "utf8")));
+  // SAFETY: written by `buildArtifact` in this process moments ago, from the
+  // Bindings shape; the broker re-validates every field it reads anyway.
+  return record as Partial<Bindings> | undefined;
+}
+
+type Running = {
+  sprout: Bun.Subprocess;
+  broker: Broker;
+  stopBroker: () => void;
+  /** Set before a kill we initiated, so its exit code is not reported as a crash. */
+  expected: boolean;
+};
+
+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",
+  });
+  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: () => {
+      server.stop();
+      broker.close();
+    },
+    expected: false,
+  };
+}
+
+function stop(running: Running): void {
+  running.expected = true;
+  running.sprout.kill(9);
+  running.stopBroker();
+}
+
+/** Report a sprout that died on its own; a kill we asked for is not news. */
+function watchExit(running: Running): void {
+  void running.sprout.exited.then((code) => {
+    if (running.expected || code === 0) return;
+    console.error(amber(`sprout exited with status ${code} — fix it and save to rebuild`));
+  });
+}
+
+/** 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);
+  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 shuttingDown = false;
+  let resolveShutdown: (() => void) | null = null;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const watcher of watchers) watcher.close();
+    stop(running);
+    resolveShutdown?.();
+    process.exit(0);
+  };
+  for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, shutdown);
+
+  if (input.watch) {
+    let pending: ReturnType<typeof setTimeout> | null = null;
+    let rebuilding = false;
+    const onChange = () => {
+      if (pending !== null) clearTimeout(pending);
+      // Editors write a file in several syscalls; one save should be one build.
+      pending = setTimeout(() => {
+        void (async () => {
+          if (rebuilding || shuttingDown) return;
+          rebuilding = true;
+          try {
+            const source = await input.rebuild();
+            console.log(dim("  change detected, rebuilding…"));
+            stop(running);
+            running = await start(input, source);
+            watchExit(running);
+            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
+            // server down mid-edit.
+            console.error(
+              amber(
+                `  rebuild failed, still serving the previous build:\n  ${cause instanceof Error ? cause.message : String(cause)}`,
+              ),
+            );
+          } finally {
+            rebuilding = false;
+          }
+        })();
+      }, 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));
+  }
+
+  // Watching, we stay up until a signal: a crashed sprout is something to fix
+  // and save, not a reason to tear the whole session down. Without a watcher
+  // there is nothing to wait for but this one process.
+  if (input.watch) {
+    await new Promise<void>((resolve) => {
+      resolveShutdown = resolve;
+    });
+  } else {
+    await running.sprout.exited;
+    stop(running);
+  }
+}

package/src/json.ts

@@ -0,0 +1,38 @@
+/**
+ * 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;
+}