siltrun 0.1.0

package/src/dev.ts

@@ -0,0 +1,264 @@
+// `siltrun dev <contract.ts>` — the local authoritative-room dev loop.
+//
+// Pipeline (brief + hello-room.md §3):
+//   1. build the Go room-server binary if needed
+//   2. bundle the contract (Bun.build) to a stable temp path
+//   3. run the determinism doctor (CONTRACT §4) if room-host shipped one
+//   4. boot the room-server in compute mode, scraping its per-boot cert hash
+//   5. serve room-info on :4000 (SEAM §4) so `useRoom("http://localhost:4000")` works
+//   6. watch the contract; on change → rebuild → doctor → restart the room (simplest
+//      correct thing per the brief) → refresh room-info → print what happened
+//   7. Ctrl-C tears everything down.
+
+import { resolve, dirname, join } from "node:path";
+import { existsSync, statSync, watch, type FSWatcher } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+import type { DevOptions } from "./args.ts";
+import { paths, has, bunBin, platformKey } from "./paths.ts";
+import { ensureRoomServer, ServerBuildError } from "./server-build.ts";
+import { bundleContract, BundleError } from "./bundle.ts";
+import { runDoctor, type DoctorResult } from "./doctor.ts";
+import { ServerSupervisor } from "./supervisor.ts";
+import { startRoomInfoServer, type RoomInfo, type RoomInfoServer } from "./room-info.ts";
+import { printBoot, printDrift } from "./banner.ts";
+import { log, paint } from "./log.ts";
+
+export async function dev(opts: DevOptions): Promise<void> {
+  const contract = resolve(opts.contract);
+  if (!existsSync(contract)) {
+    log.error(`contract not found: ${contract}`);
+    process.exit(1);
+  }
+
+  // Compute mode needs room-host (owner B). Without it we can still boot the relay
+  // binary + serve room-info (useful standalone), but compute won't function.
+  const computeReady = has.roomHost();
+  const mode: RoomInfo["mode"] = computeReady ? "compute" : "relay";
+  if (!computeReady) {
+    // @siltrun/room-host ships as a dependency of this CLI — its absence means a broken
+    // install, not a missing feature. Say that, with the way out.
+    log.warn(
+      `room-host runtime not found (looked at ${paths.roomHostEntry}) — booting RELAY ONLY, ` +
+        `your contract will not run. @siltrun/room-host ships with the siltrun package: ` +
+        `reinstall (rm -rf node_modules && npm install), or set SILT_ROOM_HOST_ENTRY ` +
+        `to a host.ts.`,
+    );
+  }
+
+  // 1. build the server binary
+  let binPath: string;
+  try {
+    binPath = await ensureRoomServer();
+  } catch (e) {
+    // An installed `siltrun` ships a prebuilt room-server via the platform packages
+    // (@siltrun/room-server-<os>-<arch>, optionalDependencies). Reaching this with no
+    // repo checkout means the platform package is missing — an unsupported platform
+    // or an install that skipped optional deps. Say exactly that, with the way out.
+    if (e instanceof ServerBuildError && !existsSync(paths.roomServerDir)) {
+      log.warn(
+        `no room-server runtime for ${platformKey} — the prebuilt platform package ` +
+          `(@siltrun/room-server-${platformKey}) isn't installed. Reinstall without ` +
+          `--no-optional, or set SILT_ROOM_SERVER_BIN to a silt-room-server binary. ` +
+          `To ship a room to the hosted beta instead, use \`siltrun deploy <contract.ts>\`.`,
+      );
+      process.exit(1);
+    }
+    // Genuinely-broken cases (e.g. a `go build` compile failure) stay a hard red error.
+    if (e instanceof ServerBuildError) {
+      log.error(e.message);
+      if (e.detail) log.plain(paint.dim(e.detail));
+    } else {
+      log.error(`room-server build failed: ${String(e)}`);
+    }
+    process.exit(1);
+  }
+
+  // 2. bundle the contract into a stable temp path (reused across reloads)
+  const workDir = await mkdtemp(join(tmpdir(), "silt-dev-"));
+  const bundlePath = join(workDir, "contract.bundle.js");
+  try {
+    await bundleContract(contract, bundlePath);
+  } catch (e) {
+    reportBundleError(e);
+    process.exit(1);
+  }
+
+  // 3. doctor
+  let doctor: DoctorResult = opts.doctor
+    ? await runDoctor(bundlePath)
+    : { status: "skipped", note: "disabled with --no-doctor" };
+
+  // room-info state — cert refreshes on each (re)boot. The room name (SEAM §4:
+  // /room/<name>) comes from --room, or is derived from the contract path (args.ts);
+  // the server serves exactly this path and loudly rejects anything else.
+  const wtEndpoint = `https://${opts.wtHost}:${opts.wtPort}/room/${opts.room}`;
+  let certHash: string | null = null;
+  const getInfo = (): RoomInfo => ({ wtEndpoint, certHash, mode });
+
+  // 4. supervise the room-server.
+  // The server treats a non-empty --contract as "enable compute mode"; empty = relay.
+  // --room is passed ALWAYS (both modes) so the served path matches wtEndpoint above.
+  const computeArgs = computeReady ? ["--contract", bundlePath, "--host", paths.roomHostEntry] : [];
+  const supervisor = new ServerSupervisor({
+    binPath,
+    args: ["--room", opts.room, ...computeArgs],
+    cwd: existsSync(paths.roomServerDir) ? paths.roomServerDir : undefined,
+    // SILT_BUN: the server spawns the Bun room-host itself (compute.go) — hand it the
+    // exact runtime running this CLI so it never depends on `bun` being on PATH.
+    env: { WT_BIND: `${opts.wtHost}:${opts.wtPort}`, SILT_BUN: bunBin() },
+    onCert: (h) => {
+      certHash = h;
+    },
+  });
+
+  try {
+    await supervisor.start();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    log.error(`room-server failed to boot: ${msg}`);
+    // The documented stray-dev hazard: another siltrun dev already holds the default
+    // ports. When the server's own output says so, hand over the way out.
+    if (/address already in use|bind:/i.test(msg)) {
+      log.plain(
+        paint.dim(
+          `  port ${opts.wtPort} looks taken — another \`siltrun dev\` may be running. ` +
+            `Stop it, or pass --wt-port <n> (and --info-port <n>, pointing useRoom at it).`,
+        ),
+      );
+    }
+    process.exit(1);
+  }
+
+  // 5. room-info endpoint
+  let roomInfo: RoomInfoServer;
+  try {
+    roomInfo = startRoomInfoServer({ port: opts.infoPort, hostname: "127.0.0.1", getInfo });
+  } catch (e) {
+    log.error(`could not bind room-info on :${opts.infoPort}: ${String(e)}`);
+    log.plain(
+      paint.dim(
+        `  port ${opts.infoPort} is likely held by another \`siltrun dev\`. Stop it, or pass ` +
+          `--info-port <n> and point your client at http://localhost:<n> instead.`,
+      ),
+    );
+    await supervisor.stop();
+    process.exit(1);
+  }
+
+  printBoot({ roomInfoUrl: roomInfo.url, info: getInfo(), contract, doctor });
+  printDrift(doctor);
+
+  // 6. watch + reload
+  let reloading = false;
+  let queued = false;
+  let debounce: ReturnType<typeof setTimeout> | null = null;
+
+  async function reload() {
+    if (reloading) {
+      queued = true;
+      return;
+    }
+    reloading = true;
+    try {
+      await bundleContract(contract, bundlePath);
+    } catch (e) {
+      reportBundleError(e);
+      log.warn("keeping the last good room running — fix the contract to reload");
+      reloading = false;
+      if (queued) drainQueued();
+      return;
+    }
+
+    doctor = opts.doctor
+      ? await runDoctor(bundlePath)
+      : { status: "skipped", note: "disabled with --no-doctor" };
+
+    try {
+      await supervisor.restart();
+    } catch (e) {
+      log.error(`restart failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    printBoot({ roomInfoUrl: roomInfo.url, info: getInfo(), contract, doctor, reload: true });
+    printDrift(doctor);
+
+    reloading = false;
+    if (queued) drainQueued();
+  }
+
+  function drainQueued() {
+    queued = false;
+    void reload();
+  }
+
+  // Watch the contract's directory and decide by the FILE'S OWN mtime, not the event's
+  // filename: atomic-rename saves (vim, sed -i, many editors) emit their events under a
+  // TEMP filename, so a basename filter silently misses them (caught in the packaged
+  // cold walk, 2026-07-17). Any event in the dir is just a prompt to stat the contract.
+  let lastMtime = statSync(contract).mtimeMs;
+  let watcher: FSWatcher | null = null;
+  try {
+    watcher = watch(dirname(contract), () => {
+      // ONE stat, no existsSync pre-check: an atomic-rename save unlinks the old
+      // inode before the new one lands, and a stat racing that window throws
+      // ENOENT — the exists→stat gap is a TOCTOU that crashed `siltrun dev`. A null
+      // here means "not re-appeared yet"; the rename emits another event once the
+      // new file is in place and we re-stat then (the debounce/retry the loop
+      // already intends).
+      const mtime = statMtimeOrNull(contract);
+      if (mtime === null) return;
+      if (mtime === lastMtime) return; // an event for something else in the dir
+      lastMtime = mtime;
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => void reload(), 150);
+    });
+  } catch (e) {
+    log.warn(`could not watch ${contract} — reload disabled: ${String(e)}`);
+  }
+
+  // 7. teardown
+  let tearing = false;
+  const teardown = async (signal: string) => {
+    if (tearing) return;
+    tearing = true;
+    log.plain();
+    log.info(`${signal} — shutting down…`);
+    if (debounce) clearTimeout(debounce);
+    watcher?.close();
+    roomInfo.stop();
+    await supervisor.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void teardown("SIGINT"));
+  process.on("SIGTERM", () => void teardown("SIGTERM"));
+
+  // Keep the process alive (room-info server + watcher hold it, but be explicit).
+  await new Promise<never>(() => {});
+}
+
+function reportBundleError(e: unknown) {
+  if (e instanceof BundleError) {
+    log.error(e.message);
+    for (const l of e.logs) log.plain(paint.dim("  " + l));
+  } else {
+    log.error(`bundle failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+/**
+ * Stat `path` for its mtimeMs, tolerating the transient absence of an atomic-rename
+ * save. Returns null when the file isn't there right now (ENOENT) — the caller
+ * treats that as "not re-appeared yet" and waits for the next event. Any other
+ * stat error is genuine and rethrown. `statFn` is injectable so the ENOENT race
+ * is testable deterministically (the exists→stat TOCTOU can't be timed reliably).
+ */
+export function statMtimeOrNull(path: string, statFn: typeof statSync = statSync): number | null {
+  try {
+    return statFn(path).mtimeMs;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw e;
+  }
+}

package/src/doctor.test.ts

@@ -0,0 +1,31 @@
+import { test, expect, describe } from "bun:test";
+import { interpretDoctorExit, DOCTOR_TICKS } from "./doctor.ts";
+
+// B's doctor CLI contract (packages/room-host/doctor.ts):
+//   Exit: 0 green · 1 drift · 2 usage/replay failure
+describe("interpretDoctorExit", () => {
+  test("exit 0 -> ok", () => {
+    const r = interpretDoctorExit(0, "✓ 300 ticks bit-identical", 300);
+    expect(r.status).toBe("ok");
+    expect(r.note).toContain("300-tick");
+  });
+
+  test("exit 1 -> drift (B's real drift signal)", () => {
+    const r = interpretDoctorExit(1, "✗ FIRST DRIFT at tick 42", 300);
+    expect(r.status).toBe("drift");
+  });
+
+  test("exit 2 (usage/replay failure) -> errored, NOT drift", () => {
+    const r = interpretDoctorExit(2, "usage: bun doctor.ts <bundle.js> <ticks>", 300);
+    expect(r.status).toBe("errored");
+    expect(r.note).toContain("exit 2");
+  });
+
+  test("other non-zero exits -> errored, NOT drift", () => {
+    expect(interpretDoctorExit(127, "", 300).status).toBe("errored");
+  });
+
+  test("standard tick count is 300", () => {
+    expect(DOCTOR_TICKS).toBe(300);
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,74 @@
+// Runs the determinism doctor (CONTRACT §4) against a freshly-bundled contract.
+//
+// The doctor is owned by room-host (owner B). Per CONTRACT §4 it replays the tick
+// sequence twice (and across engines when present), hashing state per tick, and
+// reports drift at the exact tick + field. Its CLI (packages/room-host/doctor.ts):
+//
+//   Usage: bun doctor.ts <bundle.js> <ticks> [--seed <n>]
+//   Exit:  0 green · 1 drift · 2 usage/replay failure
+//
+// Only exit 1 is B's real drift signal; any other non-zero means the doctor itself
+// couldn't run — surfaced as a warning, never as drift.
+//
+// If B hasn't shipped doctor.ts yet, we degrade to a notice — dev keeps running.
+
+import { bunBin, has, paths } from "./paths.ts";
+
+// The standard replay length used across the reference build.
+export const DOCTOR_TICKS = 300;
+
+export type DoctorStatus = "ok" | "drift" | "skipped" | "errored";
+
+export interface DoctorResult {
+  status: DoctorStatus;
+  note: string;
+  output?: string;
+}
+
+/** Map a doctor exit code to a result (pure, testable). */
+export function interpretDoctorExit(code: number, output: string, ticks: number): DoctorResult {
+  if (code === 0) {
+    return { status: "ok", note: `deterministic — ${ticks}-tick replay matched`, output };
+  }
+  if (code === 1) {
+    return { status: "drift", note: "determinism drift detected", output };
+  }
+  return {
+    status: "errored",
+    note: `doctor could not run (exit ${code}) — not a drift verdict`,
+    output,
+  };
+}
+
+export async function runDoctor(
+  bundlePath: string,
+  ticks: number = DOCTOR_TICKS,
+): Promise<DoctorResult> {
+  if (!has.doctor()) {
+    return {
+      status: "skipped",
+      note: `determinism doctor not present (${paths.doctorEntry}) — skipping check`,
+    };
+  }
+
+  try {
+    // Run the doctor under the same bun that runs this CLI — never a PATH lookup,
+    // which doesn't exist for npm consumers (bun ships as a package, not a command).
+    const proc = Bun.spawn([bunBin(), paths.doctorEntry, bundlePath, String(ticks)], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [code, out, err] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const output = [out.trim(), err.trim()].filter(Boolean).join("\n");
+    return interpretDoctorExit(code, output, ticks);
+  } catch (e) {
+    return {
+      status: "errored",
+      note: `could not run doctor: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}

package/src/log.ts

@@ -0,0 +1,39 @@
+// Tiny zero-dependency logger. ANSI colors, auto-disabled when stdout is not a TTY
+// or when NO_COLOR is set (https://no-color.org).
+
+const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
+
+const wrap = (code: string) => (s: string) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+export const paint = {
+  dim: wrap("2"),
+  bold: wrap("1"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  cyan: wrap("36"),
+  gray: wrap("90"),
+};
+
+// A stable prefix so CLI output is visually distinct from the room-server's own logs.
+const tag = paint.cyan("silt");
+
+export const log = {
+  info(msg: string) {
+    console.log(`${tag} ${msg}`);
+  },
+  warn(msg: string) {
+    console.warn(`${tag} ${paint.yellow("warn")} ${msg}`);
+  },
+  error(msg: string) {
+    console.error(`${tag} ${paint.red("error")} ${msg}`);
+  },
+  // A raw line forwarded from a child process (room-server / host), visually demoted.
+  child(source: string, line: string) {
+    console.log(`${paint.gray(source.padEnd(6))} ${paint.gray(line)}`);
+  },
+  plain(msg = "") {
+    console.log(msg);
+  },
+};