siltrun 0.1.0

package/src/bundle.ts

@@ -0,0 +1,53 @@
+// Bundles a contract file (`room.ts` and its imports) into a single ESM module the
+// room-host can load. Uses Bun's programmatic bundler — the same `bun build` the demo
+// scripts use, but in-process so we control the exact output path across reloads.
+
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+
+export class BundleError extends Error {
+  constructor(
+    message: string,
+    readonly logs: string[] = [],
+  ) {
+    super(message);
+    this.name = "BundleError";
+  }
+}
+
+/**
+ * Bundle `contractPath` into `outPath` (an absolute .js path). The same outPath is
+ * reused across reloads so downstream `--contract <path>` args stay stable; the file
+ * contents are what change. Returns outPath on success, throws BundleError otherwise.
+ */
+export async function bundleContract(contractPath: string, outPath: string): Promise<string> {
+  const entry = resolve(contractPath);
+  if (!existsSync(entry)) {
+    throw new BundleError(`contract not found: ${entry}`);
+  }
+
+  let result: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    result = await Bun.build({
+      entrypoints: [entry],
+      target: "bun",
+      format: "esm",
+      // No minify: readable output makes doctor drift and host errors legible in dev.
+    });
+  } catch (e) {
+    // Bun.build throws an AggregateError on parse/resolve failures in some versions.
+    const errs = (e as { errors?: unknown[] })?.errors;
+    const logs = Array.isArray(errs)
+      ? errs.map((x) => (x instanceof Error ? x.message : String(x)))
+      : [e instanceof Error ? e.message : String(e)];
+    throw new BundleError(`failed to bundle ${entry}`, logs);
+  }
+
+  if (!result.success || result.outputs.length === 0) {
+    const logs = result.logs.map((l) => (typeof l === "string" ? l : l.message));
+    throw new BundleError(`failed to bundle ${entry}`, logs);
+  }
+
+  await Bun.write(outPath, result.outputs[0]!);
+  return outPath;
+}

package/src/cli.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+// The `siltrun` CLI entry. Runs under Bun (the room-host runs on Bun and the contract is
+// bundled with Bun's bundler, so Bun is the toolchain regardless). `npx siltrun` execs
+// this file; the shebang picks Bun.
+
+import { parseDevArgs, ArgError } from "./args.ts";
+import { dev } from "./dev.ts";
+import { deploy } from "./deploy.ts";
+import { login, logout, whoami } from "./login.ts";
+import { log, paint } from "./log.ts";
+
+const VERSION = "0.1.0";
+
+const USAGE = `${paint.bold("siltrun")} — authoritative multiplayer rooms
+
+${paint.bold("Usage")}
+  siltrun dev <contract.ts> [options]   run a local authoritative room + hot reload + doctor
+  siltrun deploy <contract.ts> [--room <name>]   ship to the hosted beta (bundle → doctor → upload)
+  siltrun login                         log in via your browser — deploys become account-keyed
+  siltrun logout                        remove the stored login
+  siltrun whoami                        show the logged-in account
+
+${paint.bold("dev options")}
+  --room <name>        room name, served at /room/<name> (default: derived from the
+                       contract filename — or its directory when the filename is
+                       generic like room.ts/index.ts; env SILT_ROOM)
+  --wt-port <n>        WebTransport port (default: 4433, env SILT_WT_PORT)
+  --info-port <n>      room-info port (default: 4000, env SILT_INFO_PORT)
+  --wt-host <host>     WebTransport bind host (default: 127.0.0.1)
+  --no-doctor          skip the determinism check on (re)load
+
+${paint.bold("deploy options")}
+  --room <name>        room name for the hosted room (default: derived from the contract,
+                       same rule as dev; env SILT_ROOM)
+  credential           'siltrun login' session first; env SILT_DEPLOY_TOKEN (legacy
+                       beta token) as the fallback
+  env SILT_DEPLOY_URL     override the intake URL (default: the baked hosted URL)
+
+${paint.bold("examples")}
+  siltrun dev room.ts
+  siltrun dev room.ts --room my-arena
+  npx siltrun dev room.ts --info-port 4100
+  siltrun deploy room.ts --room my-arena
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  if (cmd === "--version" || cmd === "-v") {
+    log.plain(VERSION);
+    return;
+  }
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    log.plain(USAGE);
+    return;
+  }
+
+  switch (cmd) {
+    case "dev": {
+      const opts = parseDevArgs(argv.slice(1));
+      await dev(opts);
+      return;
+    }
+    case "deploy": {
+      await deploy(argv.slice(1));
+      return;
+    }
+    case "login": {
+      await login(argv.slice(1));
+      return;
+    }
+    case "logout": {
+      await logout(argv.slice(1));
+      return;
+    }
+    case "whoami": {
+      await whoami(argv.slice(1));
+      return;
+    }
+    default:
+      log.error(`unknown command: ${cmd}`);
+      log.plain(USAGE);
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  if (e instanceof ArgError) {
+    log.error(e.message);
+    process.exit(1);
+  }
+  log.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});

package/src/credentials.ts

@@ -0,0 +1,73 @@
+// The CLI's stored identity — written by `siltrun login`, read by `siltrun deploy` /
+// `siltrun whoami`, removed by `siltrun logout`.
+//
+// Location: ~/.silt/credentials.json (override the dir with SILT_HOME — used by
+// tests and by anyone pointing the CLI at a non-default setup). The file holds a
+// SESSION token (`s-…`), which is a bearer credential: the dir is created 0700
+// and the file written 0600, and its contents must never be logged.
+//
+// A session token is minted BY a specific intake backend, so the credentials
+// remember which one (`intakeUrl`). Consumers only trust the stored token for
+// that same backend — pointing SILT_DEPLOY_URL somewhere else falls back to
+// SILT_DEPLOY_TOKEN rather than sending a foreign backend's token.
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+
+export interface Credentials {
+  /** The `s-` session token. A bearer secret — never log it. */
+  token: string;
+  /** Provider login (e.g. the GitHub username; a dev name under the stub). */
+  login: string;
+  /** Stable account id on the intake backend. */
+  accountId?: string;
+  /** The intake base URL this token was minted by (tokens are per-backend). */
+  intakeUrl: string;
+  createdAt: string;
+}
+
+type Env = Record<string, string | undefined>;
+
+export function configDir(env: Env = process.env): string {
+  return env.SILT_HOME || join(homedir(), ".silt");
+}
+
+export function credentialsPath(env: Env = process.env): string {
+  return join(configDir(env), "credentials.json");
+}
+
+/** Read stored credentials; null when absent or unreadable/malformed (an
+ *  unparseable file behaves like "not logged in" — `siltrun login` rewrites it). */
+export function loadCredentials(env: Env = process.env): Credentials | null {
+  const p = credentialsPath(env);
+  if (!existsSync(p)) return null;
+  try {
+    const c = JSON.parse(readFileSync(p, "utf8")) as Credentials;
+    if (!c || typeof c.token !== "string" || !c.token || typeof c.intakeUrl !== "string") {
+      return null;
+    }
+    return c;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(creds: Credentials, env: Env = process.env): string {
+  const dir = configDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const p = credentialsPath(env);
+  writeFileSync(p, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+  // writeFileSync's mode only applies on create — an existing file keeps its old
+  // bits, so re-assert.
+  chmodSync(p, 0o600);
+  return p;
+}
+
+/** Remove stored credentials. Returns true when there was something to remove. */
+export function clearCredentials(env: Env = process.env): boolean {
+  const p = credentialsPath(env);
+  if (!existsSync(p)) return false;
+  rmSync(p);
+  return true;
+}

package/src/deploy-client.ts

@@ -0,0 +1,143 @@
+// The client side of the v0 intake API (deploy/CONTROL-PLANE.md — "The intake API").
+// Pure HTTP: no logging, no process.exit, `fetch` injected so it's fully testable against
+// a local mock. The CLI (deploy.ts) wires this to real fetch + a live status line.
+//
+//   POST /v0/deploy?room=<name>   Bearer <tester-token>  body = raw bundled JS (text/javascript)
+//     -> 201 { deployId, room, status:"queued" }
+//   GET  /v0/deploy/<id>          Bearer <tester-token>
+//     -> 200 { deployId, room, status, url?, error? }
+//
+// The bundle rides as the RAW request body (never base64) — postDeploy sends the JS text
+// straight through as `text/javascript`.
+
+export type DeployStatus = "queued" | "provisioning" | "live" | "failed";
+
+export interface DeployRecord {
+  deployId: string;
+  room: string;
+  status: DeployStatus;
+  url?: string;
+  error?: string;
+  /**
+   * The raw in-guest determinism verdict the box reported (e.g.
+   * "SILT-DOCTOR: GREEN (300-tick replay deterministic)"), surfaced to the tester on `live`.
+   * Present once the box has run its server-side doctor gate (CONTROL-PLANE.md v0.2 §B).
+   */
+  doctorVerdict?: string;
+}
+
+/** A fetch-shaped function so tests can inject one; defaults to the global fetch. */
+export type FetchLike = typeof fetch;
+
+/** Thrown for transport/HTTP-contract failures. `status` is the HTTP code when there was one. */
+export class DeployHttpError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "DeployHttpError";
+  }
+}
+
+/** Strip a trailing slash so `${base}/v0/...` never doubles up. */
+export function normalizeBase(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+async function readError(res: Response): Promise<string> {
+  // The worker returns JSON errors when it can; fall back to raw text.
+  const raw = await res.text().catch(() => "");
+  if (!raw) return "";
+  try {
+    const j = JSON.parse(raw) as { error?: string; message?: string };
+    return j.error || j.message || raw;
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * POST the bundled contract to the intake worker. `bundleText` is sent as the RAW request
+ * body (text/javascript) — the transport contract forbids base64. Returns the queued record.
+ */
+export async function postDeploy(
+  baseUrl: string,
+  token: string,
+  room: string,
+  bundleText: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<DeployRecord> {
+  const url = `${normalizeBase(baseUrl)}/v0/deploy?room=${encodeURIComponent(room)}`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "text/javascript",
+      },
+      body: bundleText, // RAW — no base64, no JSON envelope.
+    });
+  } catch (e) {
+    throw new DeployHttpError(
+      `could not reach the intake service at ${normalizeBase(baseUrl)} — ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  if (res.status === 401) {
+    throw new DeployHttpError("token rejected (401) — your SILT_DEPLOY_TOKEN is not valid", 401);
+  }
+  if (res.status === 400) {
+    const detail = await readError(res);
+    throw new DeployHttpError(`upload rejected (400)${detail ? ` — ${detail}` : ""}`, 400);
+  }
+  if (!res.ok) {
+    const detail = await readError(res);
+    throw new DeployHttpError(
+      `intake returned ${res.status}${detail ? ` — ${detail}` : ""}`,
+      res.status,
+    );
+  }
+
+  const rec = (await res.json().catch(() => null)) as DeployRecord | null;
+  if (!rec || typeof rec.deployId !== "string" || !rec.deployId) {
+    throw new DeployHttpError("intake accepted the upload but returned no deployId");
+  }
+  return rec;
+}
+
+/** GET the current status of a deploy. */
+export async function getDeployStatus(
+  baseUrl: string,
+  token: string,
+  deployId: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<DeployRecord> {
+  const url = `${normalizeBase(baseUrl)}/v0/deploy/${encodeURIComponent(deployId)}`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (e) {
+    throw new DeployHttpError(
+      `could not reach the intake service — ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  if (res.status === 401) {
+    throw new DeployHttpError("token rejected (401) while polling status", 401);
+  }
+  if (!res.ok) {
+    const detail = await readError(res);
+    throw new DeployHttpError(
+      `status poll returned ${res.status}${detail ? ` — ${detail}` : ""}`,
+      res.status,
+    );
+  }
+
+  const rec = (await res.json().catch(() => null)) as DeployRecord | null;
+  if (!rec || typeof rec.status !== "string") {
+    throw new DeployHttpError("status poll returned an unrecognized body");
+  }
+  return rec;
+}