sproutboat 0.4.10 → 0.5.0

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). */
@@ -54,21 +64,34 @@ export async function compileSprout(input: CompileInput): Promise<void> {
 
   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;

package/src/config.ts

@@ -4,7 +4,7 @@ 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;

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,196 @@
+/**
+ * #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 { isString, 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,30 @@
+/**
+ * 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;
+}