siltrun 0.1.0

package/src/deploy.ts

@@ -0,0 +1,396 @@
+// `siltrun deploy <contract.ts> [--room <name>]` — ship a room to the hosted beta via the
+// pull-model intake worker (deploy/CONTROL-PLANE.md). The tester has no gcloud, no repo,
+// no config files — just a token + this CLI. Flow (client side of the contract):
+//
+//   1. bundle the contract (reuse bundle.ts) — same Bun.build the dev loop uses
+//   2. run the LOCAL determinism doctor (reuse doctor.ts) as a fast pre-gate; drift aborts
+//      BEFORE any upload (the box re-gates server-side regardless)
+//   3. POST the RAW bundle JS to /v0/deploy?room=<name> with Bearer <SILT_DEPLOY_TOKEN>
+//   4. poll GET /v0/deploy/<id> (~2s cadence, ~2min budget) with a live status line
+//   5. on live → print the URL; on failed → print the server error; on timeout → say so
+//
+// Sketch appetite: clean happy path + honest failures. Env + flags only — no retry
+// frameworks, no config-file system.
+
+import { resolve, join } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+import { deriveRoomName, ArgError } from "./args.ts";
+import { bundleContract, BundleError } from "./bundle.ts";
+import { runDoctor, type DoctorResult } from "./doctor.ts";
+import {
+  postDeploy,
+  getDeployStatus,
+  normalizeBase,
+  DeployHttpError,
+  type DeployRecord,
+  type DeployStatus,
+  type FetchLike,
+} from "./deploy-client.ts";
+import { loadCredentials } from "./credentials.ts";
+import { log, paint } from "./log.ts";
+
+// Baked default intake URL — the deployed silt-deploy-intake worker (beta). Overridable
+// any time via SILT_DEPLOY_URL for local mocks / miniflare.
+export const DEFAULT_INTAKE_URL = "https://silt-deploy-intake.ai-chat-game.workers.dev";
+
+// Where a tester gets a token. Kept as a pointer so the "no token" error is actionable.
+const ONBOARDING_DOC = "https://silt.digitalpine.io/beta";
+
+// Where a tester reports a failure that isn't theirs to fix (docs/SUPPORT.md — Discord
+// #support is THE channel; there is no support email).
+const SUPPORT_CHANNEL = "#support on Discord (discord.gg/2nbsnZfks5)";
+
+// Poll cadence + budget (contract: ~2s, ~2min).
+const POLL_INTERVAL_MS = 2000;
+const POLL_BUDGET_MS = 120_000;
+
+// Room names ride in a URL path/query — keep them path-safe. Mirrors args.ts's ROOM_NAME_RE
+// and the server-side validRoomName; duplicated here so `siltrun dev` parsing stays untouched.
+const ROOM_NAME_RE = /^[A-Za-z0-9._-]+$/;
+
+// DEPLOYED rooms carry a second, server-enforced rule (intake worker MAX_ROOM_LEN,
+// DIG-676): the box maps a room to a Linux tap device named `tap<room>`, and Linux's
+// IFNAMSIZ caps interface names at 15 chars — so a deployable room name is at most 12.
+// Local `siltrun dev` has no such cap (no tap device involved); enforce it HERE, before
+// any upload, with the same honest reason the server would give later.
+const MAX_ROOM_LEN = 12;
+const ROOM_LEN_REASON =
+  `deployed rooms map to a Linux network interface named tap<room>, ` +
+  `capped at 15 chars — so room names max out at ${MAX_ROOM_LEN}`;
+
+export interface DeployOptions {
+  contract: string;
+  /** room name; the deployed path is /room/<room>. Derived from the contract when not given. */
+  room: string;
+}
+
+/**
+ * Parse `siltrun deploy` arguments. `argv` is everything AFTER `deploy`. Room derivation matches
+ * `siltrun dev`: --room flag (validated), else SILT_ROOM env (validated), else derived from the
+ * contract path. Kept separate from parseDevArgs so dev's parser is never perturbed.
+ */
+export function parseDeployArgs(
+  argv: string[],
+  env: Record<string, string | undefined> = process.env,
+): DeployOptions {
+  const positionals: string[] = [];
+  const flags = new Map<string, string | boolean>();
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags.set(a.slice(2, eq), a.slice(eq + 1));
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next != null && !next.startsWith("--")) {
+          flags.set(key, next);
+          i++;
+        } else {
+          flags.set(key, true);
+        }
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+
+  const contract = positionals[0];
+  if (!contract) {
+    throw new ArgError("missing contract file — usage: siltrun deploy <contract.ts> [--room <name>]");
+  }
+
+  const explicitRoom = (flags.get("room") as string | undefined) ?? env.SILT_ROOM;
+  let room: string;
+  if (explicitRoom != null) {
+    if (
+      typeof explicitRoom !== "string" ||
+      !ROOM_NAME_RE.test(explicitRoom) ||
+      explicitRoom === "." ||
+      explicitRoom === ".."
+    ) {
+      throw new ArgError(`--room must match [A-Za-z0-9._-]+ (got ${JSON.stringify(explicitRoom)})`);
+    }
+    if (explicitRoom.length > MAX_ROOM_LEN) {
+      throw new ArgError(
+        `--room ${JSON.stringify(explicitRoom)} is ${explicitRoom.length} chars — ` +
+          `${ROOM_LEN_REASON}. Pick a shorter name.`,
+      );
+    }
+    room = explicitRoom;
+  } else {
+    room = deriveRoomName(contract);
+    if (room.length > MAX_ROOM_LEN) {
+      throw new ArgError(
+        `the room name derived from your contract path (${JSON.stringify(room)}, ` +
+          `${room.length} chars) is too long to deploy — ${ROOM_LEN_REASON}. ` +
+          `Pass --room <name> with ${MAX_ROOM_LEN} chars or fewer.`,
+      );
+    }
+  }
+
+  return { contract, room };
+}
+
+// A minimal logger surface so runDeploy's output is capturable in tests. Defaults to the
+// real CLI logger.
+export interface DeployLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+  plain(msg?: string): void;
+}
+
+export interface DeployDeps {
+  env: Record<string, string | undefined>;
+  fetchImpl: FetchLike;
+  sleep: (ms: number) => Promise<void>;
+  bundle: (contractPath: string, outPath: string) => Promise<string>;
+  doctor: (bundlePath: string) => Promise<DoctorResult>;
+  logger: DeployLogger;
+  pollIntervalMs: number;
+  pollBudgetMs: number;
+}
+
+export interface DeployResult {
+  ok: boolean;
+  /** "live" success; otherwise the honest failure kind. */
+  status: "live" | "failed" | "timeout" | "aborted";
+  deployId?: string;
+  url?: string;
+  error?: string;
+}
+
+function defaultDeps(): DeployDeps {
+  return {
+    env: process.env,
+    fetchImpl: fetch,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    bundle: bundleContract,
+    doctor: (bundlePath) => runDoctor(bundlePath),
+    logger: log,
+    pollIntervalMs: POLL_INTERVAL_MS,
+    pollBudgetMs: POLL_BUDGET_MS,
+  };
+}
+
+// Human labels for the live status line.
+const STATUS_LABEL: Record<DeployStatus, string> = {
+  queued: "queued",
+  provisioning: "provisioning room…",
+  live: "live",
+  failed: "failed",
+};
+
+/**
+ * The testable core. Does bundle + local doctor pre-gate, then POST + poll, logging as it
+ * goes. Returns a DeployResult; never calls process.exit (deploy() maps that). Every failure
+ * path is honest — it never claims success it didn't observe.
+ */
+export async function runDeploy(
+  opts: DeployOptions,
+  overrides: Partial<DeployDeps> = {},
+): Promise<DeployResult> {
+  const deps = { ...defaultDeps(), ...overrides };
+  const { logger, env } = deps;
+
+  const contract = resolve(opts.contract);
+  if (!existsSync(contract)) {
+    logger.error(`contract not found: ${contract}`);
+    return { ok: false, status: "aborted", error: "contract not found" };
+  }
+
+  const baseUrl = env.SILT_DEPLOY_URL || DEFAULT_INTAKE_URL;
+
+  // 1. Credential — fail fast and friendly before doing any work.
+  //    EXPLICIT BEATS AMBIENT: an explicitly-set SILT_DEPLOY_TOKEN wins over the
+  //    stored login session (a tester deliberately setting the env var means it).
+  //    The session is used only when no env token is present. The legacy tester
+  //    `t-` env path keeps working unchanged; a stored session still only counts
+  //    for the backend that minted it (pointing SILT_DEPLOY_URL elsewhere must
+  //    not leak the token there).
+  const creds = loadCredentials(env);
+  const sessionUsable = !!creds && normalizeBase(creds.intakeUrl) === normalizeBase(baseUrl);
+  const envToken = env.SILT_DEPLOY_TOKEN;
+  const usingSession = !envToken && sessionUsable;
+  const token = envToken || (sessionUsable ? creds!.token : undefined);
+  if (!token) {
+    logger.error("no deploy credential — run `siltrun login` (or set SILT_DEPLOY_TOKEN to a beta token)");
+    logger.plain(paint.dim(`  Beta info: ${ONBOARDING_DOC}`));
+    return { ok: false, status: "aborted", error: "no token" };
+  }
+  if (usingSession) {
+    logger.info(`deploying as ${paint.bold(creds!.login)}`);
+  } else if (envToken && sessionUsable) {
+    // Both present — the explicit env token wins; say so once so the operator
+    // isn't surprised their logged-in account was bypassed for this deploy.
+    logger.info(
+      "using SILT_DEPLOY_TOKEN (tester token) — logged-in account ignored for this deploy",
+    );
+  } else if (envToken && creds) {
+    // Logged in, but against a different backend than this deploy targets.
+    logger.plain(
+      paint.dim(
+        `  (logged-in session is for ${creds.intakeUrl}; using SILT_DEPLOY_TOKEN for ${baseUrl})`,
+      ),
+    );
+  }
+
+  // 2. Bundle (reuse the dev-loop bundler).
+  const workDir = await mkdtemp(join(tmpdir(), "silt-deploy-"));
+  const bundlePath = join(workDir, "contract.bundle.js");
+  try {
+    await deps.bundle(contract, bundlePath);
+  } catch (e) {
+    reportBundleError(e, logger);
+    return { ok: false, status: "aborted", error: "bundle failed" };
+  }
+  const bundleText = await Bun.file(bundlePath).text();
+
+  // 3. Local determinism doctor as a client-side pre-gate. Only real DRIFT aborts — a doctor
+  //    that can't run (or isn't present) is a warning, since the box re-gates server-side.
+  const doctor = await deps.doctor(bundlePath);
+  if (doctor.status === "drift") {
+    logger.error("determinism drift — deploy aborted before upload");
+    if (doctor.output) logger.plain(paint.dim("  " + doctor.output.split("\n").join("\n  ")));
+    logger.plain(paint.dim("  Fix the drift and re-run — a drifting room can't go live."));
+    return { ok: false, status: "aborted", error: "determinism drift" };
+  }
+  if (doctor.status === "ok") {
+    logger.info(paint.green("determinism ok") + paint.dim(` — ${doctor.note}`));
+  } else {
+    // skipped or errored: proceed, box re-gates. Calm NOTE (not a scary warn) — a first-timer
+    // on a bare install shouldn't read this as a failure; the server-side GREEN arrives below.
+    logger.plain(paint.dim("  determinism is verified server-side — verdict below ↓"));
+  }
+
+  // 4. POST the RAW bundle.
+  logger.info(`uploading room ${paint.bold(opts.room)} → ${paint.dim(baseUrl)}`);
+  let rec: DeployRecord;
+  try {
+    rec = await postDeploy(baseUrl, token, opts.room, bundleText, deps.fetchImpl);
+  } catch (e) {
+    if (e instanceof DeployHttpError) {
+      logger.error(e.message);
+      if (e.status === 401 && usingSession) {
+        logger.plain(paint.dim("  your login session may have expired — run `siltrun login` again"));
+      }
+    } else {
+      logger.error(`upload failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { ok: false, status: "aborted", error: "upload failed" };
+  }
+
+  logger.info(`queued ${paint.dim(`(deploy ${rec.deployId})`)}`);
+
+  // 5. Poll with a live status line.
+  const deadline = Date.now() + deps.pollBudgetMs;
+  let lastStatus: DeployStatus | null = rec.status;
+  logger.info(`status: ${paint.cyan(STATUS_LABEL[rec.status] ?? rec.status)}`);
+  if (rec.status === "live") return succeed(rec, baseUrl, logger);
+  if (rec.status === "failed") return fail(rec, logger);
+
+  while (Date.now() < deadline) {
+    await deps.sleep(deps.pollIntervalMs);
+    let cur: DeployRecord;
+    try {
+      cur = await getDeployStatus(baseUrl, token, rec.deployId, deps.fetchImpl);
+    } catch (e) {
+      // A transient poll error isn't fatal within the budget — note it and keep polling.
+      logger.warn(
+        `status poll hiccup: ${e instanceof Error ? e.message : String(e)} — retrying`,
+      );
+      continue;
+    }
+
+    if (cur.status !== lastStatus) {
+      logger.info(`status: ${paint.cyan(STATUS_LABEL[cur.status] ?? cur.status)}`);
+      lastStatus = cur.status;
+    }
+    if (cur.status === "live") return succeed(cur, baseUrl, logger);
+    if (cur.status === "failed") return fail(cur, logger);
+  }
+
+  // Honest timeout: we stopped WATCHING, we don't know the outcome. Note: re-running
+  // `siltrun deploy` queues a NEW deploy — it does not resume watching this one — so don't
+  // suggest it as a way to "check".
+  logger.error(
+    `stopped watching after ${Math.round(deps.pollBudgetMs / 1000)}s — deploy ${rec.deployId} ` +
+      `was still "${lastStatus}". It may yet come up on its own in the next few minutes.`,
+  );
+  logger.plain(
+    paint.dim(
+      `  If it doesn't, report it in ${SUPPORT_CHANNEL} with the reference ` +
+        `"deploy ${rec.deployId}" and we'll dig in.`,
+    ),
+  );
+  return { ok: false, status: "timeout", deployId: rec.deployId, error: "poll timeout" };
+}
+
+function succeed(rec: DeployRecord, baseUrl: string, logger: DeployLogger): DeployResult {
+  logger.plain();
+  logger.info(paint.green(paint.bold("live")) + ` — room ${paint.bold(rec.room)} is up`);
+  if (rec.url) {
+    // (a) the room URL — the WebTransport/QUIC endpoint the @siltrun/client dials. It is NOT
+    //     browser-navigable on its own (no TCP/HTTP surface), so we label it plainly.
+    logger.plain();
+    logger.plain(`  room:  ${paint.bold(paint.cyan(rec.url))}`);
+
+    // (b) the check/play URL with the room pre-filled — the tester OPENS THIS IN A BROWSER to
+    //     verify the room is live and watch its state in real time. Never hand-construct a URL.
+    const checkUrl = `${normalizeBase(baseUrl)}/check?room=${encodeURIComponent(rec.url)}`;
+    logger.plain();
+    logger.plain(`  ${paint.dim("open in a browser to verify + watch your room live:")}`);
+    logger.plain(`  ${paint.bold(paint.cyan(checkUrl))}`);
+    logger.plain();
+  }
+
+  // (c) the server-side determinism verdict, if the box reported one (CONTROL-PLANE v0.2 §B).
+  if (rec.doctorVerdict) {
+    logger.info(
+      paint.green("✓ determinism verified server-side") + paint.dim(` — ${rec.doctorVerdict}`),
+    );
+  }
+
+  return { ok: true, status: "live", deployId: rec.deployId, url: rec.url };
+}
+
+function fail(rec: DeployRecord, logger: DeployLogger): DeployResult {
+  // The server's reason is shown as-is: some reasons ARE the tester's to act on (name
+  // too long, empty bundle, beta at capacity). But many are operator diagnostics
+  // (journalctl hints, rootfs paths) a tester can't touch — so always close with the
+  // honest route: a reference id + the support channel. Vercel bar: every failure is
+  // either user-actionable or "it's ours — here's your reference".
+  logger.error(`deploy failed${rec.error ? `: ${rec.error}` : ""}`);
+  logger.plain(
+    paint.dim(
+      `  If the reason above isn't something you can act on, it's ours to fix — ` +
+        `report it in ${SUPPORT_CHANNEL} with the reference "deploy ${rec.deployId}".`,
+    ),
+  );
+  return { ok: false, status: "failed", deployId: rec.deployId, error: rec.error };
+}
+
+function reportBundleError(e: unknown, logger: DeployLogger) {
+  if (e instanceof BundleError) {
+    logger.error(e.message);
+    for (const l of e.logs) logger.plain(paint.dim("  " + l));
+  } else {
+    logger.error(`bundle failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+/**
+ * CLI entry. Parses argv (everything after `deploy`), runs the deploy, and exits non-zero on
+ * any non-live outcome so scripts/CI can gate on it.
+ */
+export async function deploy(argv: string[]): Promise<void> {
+  const opts = parseDeployArgs(argv);
+  const result = await runDeploy(opts);
+  if (!result.ok) process.exit(1);
+}

package/src/dev.test.ts

@@ -0,0 +1,59 @@
+// Regression test for the `siltrun dev` watcher TOCTOU (review finding #4).
+//
+// The watcher used existsSync(contract) then statSync(contract). An atomic-rename
+// save (vim, sed -i, most editors) unlinks the old inode before the new one lands;
+// a stat racing that window throws ENOENT AFTER existsSync returned true. That
+// uncaught throw inside the fs.watch callback crashed `siltrun dev`. The fix does a
+// single guarded stat (no exists pre-check) and treats ENOENT as "not re-appeared
+// yet". statMtimeOrNull is that stat; here we prove it swallows the race.
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { statMtimeOrNull } from "./dev.ts";
+
+describe("statMtimeOrNull (dev watcher TOCTOU)", () => {
+  test("returns the mtimeMs for a real, present file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "silt-dev-watch-"));
+    try {
+      const f = join(dir, "room.ts");
+      writeFileSync(f, "export default {}");
+      expect(statMtimeOrNull(f)).toBe(statSync(f).mtimeMs);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ENOENT during the stat (mid atomic-rename) → null, never throws", () => {
+    // The exact race: the event fired, but by the time we stat the file is gone
+    // for a beat. Injecting a statFn that throws ENOENT reproduces it determinist-
+    // ically (the real exists→stat gap is too small to time). Before the fix this
+    // ENOENT propagated out of the watch callback and killed the process.
+    const enoent = Object.assign(new Error("ENOENT: no such file"), { code: "ENOENT" });
+    const throwing = (() => {
+      throw enoent;
+    }) as unknown as typeof statSync;
+    expect(() => statMtimeOrNull("/whatever/room.ts", throwing)).not.toThrow();
+    expect(statMtimeOrNull("/whatever/room.ts", throwing)).toBeNull();
+  });
+
+  test("a genuinely-absent path (unlink+rename in flight) → null", () => {
+    const dir = mkdtempSync(join(tmpdir(), "silt-dev-watch-"));
+    try {
+      // No file created — stands in for the instant between unlink and rename.
+      expect(statMtimeOrNull(join(dir, "room.ts"))).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a non-ENOENT stat error is genuine and rethrown", () => {
+    const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" });
+    const throwing = (() => {
+      throw eacces;
+    }) as unknown as typeof statSync;
+    expect(() => statMtimeOrNull("/whatever/room.ts", throwing)).toThrow(/EACCES/);
+  });
+});