siltrun 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Brubaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,8 @@
 # `siltrun` — the Silt CLI
 
 Run an authoritative multiplayer room on your machine with one command. A room is a
-reducer (`tick(state, inputs)`); the server owns the truth. See `archive/rung4-design/hello-room.md`
-for the full quickstart.
+reducer (`tick(state, inputs)`); the server owns the truth. The full quickstart is at
+<https://silt.run/docs/quickstart/>.
 
 ```bash
 npx siltrun dev room.ts
@@ -21,13 +21,13 @@ const { state, send } = useRoom("http://localhost:4000", { id: crypto.randomUUID
 
 1. **Builds** the Go room-server binary if it is missing or stale (`go build`).
 2. **Bundles** your contract and its imports into a single module (Bun's bundler).
-3. **Runs the determinism doctor** (CONTRACT §4) if `packages/room-host/doctor.ts` is
-   present — it replays the tick sequence and reports drift at the exact tick/field. If
-   the doctor is not present yet, dev prints a notice and keeps running.
+3. **Runs the determinism doctor** if `@siltrun/room-host` is resolvable — it replays the
+   tick sequence and reports drift at the exact tick/field. If the doctor is not present,
+   dev prints a notice and keeps running.
 4. **Boots the room-server in compute mode** (`--contract <bundle> --host <host.ts>`) and
    scrapes the per-boot dev certificate hash it prints.
 5. **Serves room-info** on `:4000` — `GET /.well-known/silt` returns
-   `{ wtEndpoint, certHash, mode }` (SEAM §4) with permissive CORS, so a Vite app on
+   `{ wtEndpoint, certHash, mode }` with permissive CORS, so a Vite app on
    another port can discover the room and dial WebTransport with the cert pinned. **You
    never touch `serverCertificateHashes`.**
 6. **Watches** the contract. On save it rebundles, re-runs the doctor, and restarts the
@@ -42,14 +42,27 @@ restart (250ms → 5s cap), clearly logged, so a transient failure never ends yo
 
 ```
 siltrun dev <contract.ts> [options]
-  --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)
+  --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>  advertised WebTransport host (default 127.0.0.1, env SILT_WT_HOST)
+  --wt-bind <addr>  WebTransport bind address  (default: --wt-host, env SILT_WT_BIND)
   --no-doctor       skip the determinism check on (re)load
 ```
 
-Path overrides (mainly for the monorepo / tests): `SILT_ROOM_SERVER_DIR`,
-`SILT_ROOM_HOST_ENTRY`, `SILT_DOCTOR_ENTRY`.
+`--wt-host` is what the room *advertises*; `--wt-bind` is the address it *listens* on.
+They are the same by default. To reach the room from a second device, bind wide and let
+discovery answer for itself:
+
+```bash
+npx siltrun dev room.ts --wt-bind 0.0.0.0
+```
+
+room-info binds wherever WebTransport binds — a device that can reach the room can also
+discover it — and the advertised `wtEndpoint` follows the host each request arrived on, so
+a loopback fetch learns a loopback endpoint and a LAN or tailnet fetch learns that one.
+
+Path overrides (mainly for tests and for running against a local checkout):
+`SILT_ROOM_SERVER_DIR`, `SILT_ROOM_HOST_ENTRY`, `SILT_DOCTOR_ENTRY`.
 
 ## `siltrun deploy`
 
@@ -58,76 +71,50 @@ npx siltrun deploy room.ts
 ```
 
 Ships a contract to the hosted beta: bundle → local determinism doctor → upload
-(`SILT_DEPLOY_TOKEN` required; see `src/deploy.ts`). Prints the room endpoint and the
-check page on success.
-
-Deployed room names are capped at **12 chars** (charset `[A-Za-z0-9._-]`): the box
-maps each room to a Linux tap device `tap<room>`, and IFNAMSIZ caps interface names
-at 15. The CLI enforces this client-side, before upload, with the same reason the
-intake worker gives (DIG-676). Local `siltrun dev` has no length cap — no tap device.
-
-## Distribution — how the npm package is shaped
-
-`npm install siltrun` must work from an empty directory with **Node as the only
-prerequisite** (the wrangler/workerd bar). Three runtimes ship as packages:
-
-- **The CLI itself** runs on Bun, but its `bin` is a plain-Node shim
-  (`bin/silt.mjs`) that locates Bun and re-execs `src/cli.ts` under it. Bun arrives
-  through the official `bun` npm package (a dependency); the shim resolves it in
-  order: `SILT_BUN` env → the `bun` package's populated `bin/bun.exe` → the
-  `@oven/bun-<platform>` package directly (covers `--ignore-scripts` installs) →
-  `bun` on PATH. The resolved path is exported as `SILT_BUN` so every downstream
-  spawn (doctor, and the Go server spawning the room-host) uses the same runtime.
-- **The Go room-server** ships prebuilt in per-platform packages
-  (`@siltrun/room-server-<os>-<arch>`, `optionalDependencies` with `os`/`cpu` fields —
-  npm installs exactly the matching one). `paths.ts` resolves the installed binary;
-  in the monorepo the sibling Go source wins and is built/rebuilt from source.
-- **The Bun room-host** (host.ts, doctor, deterministic realm) ships as
-  `@siltrun/room-host` — plain TS source, zero runtime deps; the CLI resolves it from
-  node_modules, or from the sibling package in-repo.
-
-`create-siltrun` (`npm create siltrun my-game`) scaffolds the consumer project: `room.ts`
-at the root, a `src/Game.tsx` React client, and a `dev` script that runs
-`siltrun dev room.ts` + vite together.
-
-### Releasing
+(`SILT_DEPLOY_TOKEN` required). Prints the room endpoint and the check page on success.
 
-```bash
-bun tools/pack-release.ts        # build dist + platform binaries, pack ALL tarballs
-bun tools/pack-release.ts --current   # this machine's platform binary only
-```
+Deployed room names are capped at **12 chars**, charset `[A-Za-z0-9._-]`. The CLI
+enforces this before upload, so an over-long name fails on your machine in a second
+instead of after a round trip. Local `siltrun dev` has no length cap.
 
-Tarballs land in `dist-tarballs/`, with `workspace:*` deps mechanically rewritten to
-real versions by `bun pm pack` and verified by the script (it fails on any leaked
-`workspace:` and on a platform tarball missing its binary). Publishing is
-`npm publish <tarball>` per file. QA without touching the npm registry: publish the
-tarballs to a local registry (verdaccio) and walk `npm create siltrun` against it.
+## What gets installed
 
-## North star: the Vite-plugin blend (future)
+`npm install siltrun` works from an empty directory with **Node as the only
+prerequisite**. Three runtimes arrive as packages, and you do not install any of them
+yourself:
 
-`npx siltrun dev` is the standalone path. The tracked north star (CONTRACT §10, open item 3)
-is a **Vite plugin** so the room runs inside your existing `npm run dev` — one project,
-one terminal, one reload story, exactly how Next.js made API routes feel. `room.ts` should
-feel like adding a route, not running a game server. The plugin would host the room-info
-endpoint on the Vite dev server itself and own the same supervise/bundle/doctor pipeline
-this CLI implements today, so the standalone path stays the reference implementation.
+- **The CLI** runs on Bun, but its `bin` is a plain-Node shim that locates Bun and
+  re-execs under it. Bun arrives through the official `bun` npm package, a dependency.
+  Set `SILT_BUN` to point at a specific Bun binary if you need to; otherwise the shim
+  finds one, and every downstream spawn reuses the same runtime.
+- **The room-server** ships prebuilt in per-platform packages
+  (`@siltrun/room-server-<os>-<arch>`), declared as `optionalDependencies` with `os`
+  and `cpu` fields, so npm installs exactly the one matching your machine.
+- **The room-host** (the contract runtime, the doctor, and the deterministic realm)
+  ships as `@siltrun/room-host`, plain TypeScript source with zero runtime deps.
 
-## Notes for the reference build
+To start a project rather than add the CLI to one, `npm create siltrun@latest my-game`
+scaffolds `room.ts`, a React client, and a `dev` script that runs the room and Vite
+together.
 
-- **Runtime:** Bun. The room-host runs on Bun and the contract is bundled with Bun, so
-  Bun is the toolchain regardless; the CLI's own code runs under it (via the Node
-  shim above — never assume `bun` is on the user's PATH).
-- **Room route:** `/room/<name>` — named by `--room`, `SILT_ROOM`, or derived from the
-  contract path (generic basenames like `room.ts` defer to the parent directory). The
-  dev never types this path — only the room-info URL.
+## Where this is heading
 
-## Development
+`npx siltrun dev` is the standalone path. The intended future is a **Vite plugin**, so
+the room runs inside your existing `npm run dev`: one project, one terminal, one reload
+story, the way API routes feel in a web framework. `room.ts` should feel like adding a
+route rather than running a game server. The plugin would host the room-info endpoint on
+the Vite dev server itself and own the same supervise, bundle, and doctor pipeline this
+CLI implements today, so the standalone path stays the reference implementation.
 
-```bash
-bun install
-bun test          # room-info shape, bundling, arg parsing, cert-scrape
-bun run typecheck
-```
+## Notes
+
+- **Runtime:** Bun. The room-host runs on Bun and the contract is bundled with Bun, so
+  Bun is the toolchain either way. The CLI's own code runs under it through the Node
+  shim above, and never assumes `bun` is on your PATH.
+- **Room route:** `/room/<name>`, named by `--room`, `SILT_ROOM`, or derived from the
+  contract path (generic basenames like `room.ts` defer to the parent directory). You
+  never type this path yourself, only the room-info URL.
+
+## Docs
 
-End-to-end proof (a browser actually joining and moving a ship) belongs to the integration
-phase. These tests cover the pieces the CLI owns standalone.
+Full guides and API reference: <https://silt.run/docs/>

package/package.json

@@ -1,26 +1,50 @@
 {
   "name": "siltrun",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "license": "MIT",
   "description": "The Silt CLI — run an authoritative multiplayer room locally with `siltrun dev`.",
+  "keywords": [
+    "multiplayer",
+    "webtransport",
+    "realtime",
+    "game-server",
+    "silt",
+    "cli",
+    "dev-server",
+    "netcode",
+    "gamedev",
+    "authoritative-server"
+  ],
+  "homepage": "https://silt.run",
+  "bugs": {
+    "url": "https://github.com/siltrun/silt/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siltrun/silt.git",
+    "directory": "packages/cli"
+  },
   "type": "module",
   "bin": {
     "siltrun": "bin/silt.mjs"
   },
-  "files": ["bin", "src"],
+  "files": [
+    "bin",
+    "src"
+  ],
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
-  "repository": "https://github.com/digitalpine/silt",
   "dependencies": {
-    "@siltrun/room-host": "0.1.0",
+    "@siltrun/room-host": "0.2.0",
     "bun": "^1.3.0"
   },
   "optionalDependencies": {
-    "@siltrun/room-server-darwin-arm64": "0.1.0",
-    "@siltrun/room-server-darwin-x64": "0.1.0",
-    "@siltrun/room-server-linux-arm64": "0.1.0",
-    "@siltrun/room-server-linux-x64": "0.1.0"
+    "@siltrun/room-server-darwin-arm64": "0.2.0",
+    "@siltrun/room-server-darwin-x64": "0.2.0",
+    "@siltrun/room-server-linux-arm64": "0.2.0",
+    "@siltrun/room-server-linux-x64": "0.2.0"
   },
   "engines": {
     "node": ">=18"

package/src/args.test.ts

@@ -91,3 +91,21 @@ describe("deriveRoomName", () => {
     expect(deriveRoomName("examples/„…“/⚡.ts")).toBe("room");
   });
 });
+
+describe("wt-bind", () => {
+  const noEnv = {};
+  test("defaults to wtHost", () => {
+    const o = parseDevArgs(["room.ts", "--wt-host", "100.64.0.5"], noEnv);
+    expect(o.wtBind).toBe("100.64.0.5");
+  });
+  test("splits bind from advertised host", () => {
+    const o = parseDevArgs(["room.ts", "--wt-host", "100.64.0.5", "--wt-bind", "0.0.0.0"], noEnv);
+    expect(o.wtBind).toBe("0.0.0.0");
+    expect(o.wtHost).toBe("100.64.0.5");
+  });
+  test("reads SILT_WT_BIND from env", () => {
+    const o = parseDevArgs(["room.ts"], { SILT_WT_BIND: "0.0.0.0" });
+    expect(o.wtBind).toBe("0.0.0.0");
+    expect(o.wtHost).toBe("127.0.0.1");
+  });
+});

package/src/args.ts

@@ -9,6 +9,9 @@ export interface DevOptions {
   wtPort: number;
   infoPort: number;
   wtHost: string;
+  /** WT bind address; defaults to wtHost. Split so a host can bind 0.0.0.0 (serve
+   *  loopback AND a LAN/tailnet interface) while advertising one reachable host. */
+  wtBind: string;
   doctor: boolean;
 }
 
@@ -105,6 +108,7 @@ export function parseDevArgs(argv: string[], env: Record<string, string | undefi
   }
 
   const wtHost = (flags.get("wt-host") as string) || env.SILT_WT_HOST || "127.0.0.1";
+  const wtBind = (flags.get("wt-bind") as string) || env.SILT_WT_BIND || wtHost;
   const wtPort = intOpt((flags.get("wt-port") as string) ?? env.SILT_WT_PORT, "--wt-port", 4433);
   const infoPort = intOpt(
     (flags.get("info-port") as string) ?? env.SILT_INFO_PORT,
@@ -113,5 +117,5 @@ export function parseDevArgs(argv: string[], env: Record<string, string | undefi
   );
   const doctor = flags.get("no-doctor") !== true;
 
-  return { contract, room, wtPort, infoPort, wtHost, doctor };
+  return { contract, room, wtPort, infoPort, wtHost, wtBind, doctor };
 }

package/src/cli.ts

@@ -26,7 +26,9 @@ ${paint.bold("dev options")}
                        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)
+  --wt-host <host>     advertised WebTransport + room-info host (default: 127.0.0.1)
+  --wt-bind <addr>     WT bind address (default: --wt-host; use 0.0.0.0 to serve
+                       loopback and a LAN/tailnet interface at once)
   --no-doctor          skip the determinism check on (re)load
 
 ${paint.bold("deploy options")}

package/src/deploy.ts

@@ -36,8 +36,12 @@ import { log, paint } from "./log.ts";
 // 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 logged-out user goes next. Kept as a pointer so the "no credential" error is
+// actionable. This is the FIRST thing a stranger sees when they run `deploy` before
+// `login`, so it must resolve: the old https://silt.digitalpine.io/beta 404s (verified
+// 2026-08-02), and so does /beta on the current host. The docs quickstart is the live,
+// honest target and documents the login step this error is telling them to run.
+const ONBOARDING_DOC = "https://silt.run/docs/quickstart/";
 
 // 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).
@@ -221,7 +225,7 @@ export async function runDeploy(
   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}`));
+    logger.plain(paint.dim(`  Getting started: ${ONBOARDING_DOC}`));
     return { ok: false, status: "aborted", error: "no token" };
   }
   if (usingSession) {

package/src/dev.ts

@@ -93,9 +93,16 @@ export async function dev(opts: DevOptions): Promise<void> {
   // 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}`;
+  // The advertised WT host follows the host the info request arrived on (a loopback
+  // fetch gets a loopback endpoint, a tailnet fetch the tailnet one — cert pinning
+  // makes the hostname interchangeable); --wt-host is the fallback for callers with
+  // no request in hand (boot banner).
   let certHash: string | null = null;
-  const getInfo = (): RoomInfo => ({ wtEndpoint, certHash, mode });
+  const getInfo = (requestHost?: string): RoomInfo => ({
+    wtEndpoint: `https://${requestHost ?? opts.wtHost}:${opts.wtPort}/room/${opts.room}`,
+    certHash,
+    mode,
+  });
 
   // 4. supervise the room-server.
   // The server treats a non-empty --contract as "enable compute mode"; empty = relay.
@@ -107,7 +114,7 @@ export async function dev(opts: DevOptions): Promise<void> {
     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() },
+    env: { WT_BIND: `${opts.wtBind}:${opts.wtPort}`, SILT_BUN: bunBin() },
     onCert: (h) => {
       certHash = h;
     },
@@ -134,7 +141,11 @@ export async function dev(opts: DevOptions): Promise<void> {
   // 5. room-info endpoint
   let roomInfo: RoomInfoServer;
   try {
-    roomInfo = startRoomInfoServer({ port: opts.infoPort, hostname: "127.0.0.1", getInfo });
+    // Bind room-info wherever WebTransport binds: a device that can reach the room
+    // must also be able to discover it (the /.well-known/silt fetch carries the cert
+    // hash), and with --wt-bind 0.0.0.0 that includes loopback AND the external
+    // interface. Default flags keep this loopback-only, exactly as before.
+    roomInfo = startRoomInfoServer({ port: opts.infoPort, hostname: opts.wtBind, getInfo });
   } catch (e) {
     log.error(`could not bind room-info on :${opts.infoPort}: ${String(e)}`);
     log.plain(

package/src/room-info.test.ts

@@ -78,3 +78,24 @@ describe("room-info endpoint (SEAM §4)", () => {
     expect(res.status).toBe(404);
   });
 });
+
+describe("request-host advertisement", () => {
+  test("getInfo receives the hostname the request arrived on", async () => {
+    let seen: string | undefined = "unset" as string | undefined;
+    const s = startRoomInfoServer({
+      port: 0,
+      getInfo: (requestHost) => {
+        seen = requestHost;
+        return { wtEndpoint: `https://${requestHost}:4433/room/x`, certHash: null, mode: "compute" };
+      },
+    });
+    try {
+      const res = await fetch(`http://127.0.0.1:${s.port}${WELL_KNOWN_PATH}`);
+      const body = (await res.json()) as { wtEndpoint: string };
+      expect(seen).toBe("127.0.0.1");
+      expect(body.wtEndpoint).toBe("https://127.0.0.1:4433/room/x");
+    } finally {
+      s.stop();
+    }
+  });
+});

package/src/room-info.ts

@@ -31,12 +31,15 @@ export interface RoomInfoServer {
 
 /**
  * Serve room-info on `port`. `getInfo` is called per request so the served cert hash
- * tracks the live room-server across restarts (the cert changes each boot).
+ * tracks the live room-server across restarts (the cert changes each boot). It receives
+ * the hostname the request arrived on, so a multi-homed dev server (--wt-bind 0.0.0.0)
+ * can advertise a WT endpoint the asking client can actually reach — a loopback fetch
+ * learns a loopback endpoint, a tailnet fetch learns the tailnet one.
  */
 export function startRoomInfoServer(opts: {
   port: number;
   hostname?: string;
-  getInfo: () => RoomInfo;
+  getInfo: (requestHost?: string) => RoomInfo;
 }): RoomInfoServer {
   const hostname = opts.hostname ?? "127.0.0.1";
   const server = Bun.serve({
@@ -53,7 +56,8 @@ export function startRoomInfoServer(opts: {
         if (req.method !== "GET") {
           return new Response("method not allowed", { status: 405, headers: CORS });
         }
-        return Response.json(opts.getInfo(), { headers: CORS });
+        const requestHost = new URL(req.url).hostname || undefined;
+        return Response.json(opts.getInfo(requestHost), { headers: CORS });
       }
 
       return new Response("not found", { status: 404, headers: CORS });