@solidrt/cli 0.0.25 → 0.0.27

package/server/main.ts

@@ -0,0 +1,301 @@
+// The srt dev server as a flux script. srt (Bun) spawns this with one JSON
+// config argument; bundling, file watching, and the repl stay in srt, which
+// drives this process over the loopback-only /__internal__/ routes. The
+// shutdown-when-empty policy also lives in srt (it polls /__internal__/clients);
+// this process runs until srt kills it. See docs/flux-dev-server-plan.md.
+
+import { serve } from "flux:http"
+import type { FluxRequest, Server } from "flux:http"
+import { file, dir } from "flux:fs"
+import { argv } from "flux:process"
+import { resolveWithin, join } from "flux:path"
+import { state, type Config } from "./state"
+import * as cache from "./cache"
+import { handleProxy } from "./proxy"
+import { appendLog, clientList, handleControl, resolveQuery } from "./control"
+import { printQr } from "./qr"
+import { createTunnelEndpoint, TUNNEL_PROTOCOL } from "./tunnel"
+
+// argv layout differs between hosts; the config JSON is always the last argument.
+let config: Config = JSON.parse(argv[argv.length - 1]!)
+state.config = config
+state.sourceDir = config.sourceDir
+state.stats = config.stats
+state.serverUrl = `${config.address}:${config.port}`
+
+if (config.cache) {
+  await cache.initCache({ dir: config.cacheDir })
+  console.log("[cli] HTTP cache enabled")
+}
+
+if (config.capture) {
+  // Start each capture from an empty file: appends would otherwise tack onto
+  // whatever a previous run left behind.
+  await file(config.capture).write("")
+  state.captureStartMs = Date.now()
+}
+
+// Split an origin-form request URL ("/path?a=1&b=2") into its decoded path and
+// query parameters. flux has no URL global; this covers what the routes need.
+function splitQuery(url: string): { path: string; query: Map<string, string> } {
+  let i = url.indexOf("?")
+  let path = i < 0 ? url : url.slice(0, i)
+  let query = new Map<string, string>()
+  if (i >= 0) {
+    for (let pair of url.slice(i + 1).split("&")) {
+      if (!pair) continue
+      let j = pair.indexOf("=")
+      let k = j < 0 ? pair : pair.slice(0, j)
+      let v = j < 0 ? "" : pair.slice(j + 1)
+      query.set(decodeURIComponent(k), decodeURIComponent(v.replace(/\+/g, " ")))
+    }
+  }
+  return { path: decodeURIComponent(path), query }
+}
+
+// Send `text` to the clients with the given ids, or to every client when
+// `ids` is omitted.
+function sendTo(ids: number[] | undefined, text: string) {
+  for (let [ws, info] of state.clients) {
+    if (!ids || ids.includes(info.id)) ws.send(text)
+  }
+}
+
+// The srt -> server IPC under /__internal__/: only the srt process on this
+// machine may drive it, so reject any peer that is not loopback.
+async function handleInternal(req: FluxRequest, server: Server, path: string): Promise<Response> {
+  let ip = server.requestIP(req)
+  let loopback = ip && (ip.address === "127.0.0.1" || ip.address === "::1" || ip.address === "::ffff:127.0.0.1")
+  if (!loopback) return new Response("Forbidden", { status: 403 })
+
+  if (path === "/__internal__/clients") return Response.json(clientList(true))
+  if (req.method !== "POST") return new Response("Method not allowed", { status: 405 })
+
+  switch (path) {
+    case "/__internal__/reload": {
+      // { message, clients?, latch?, sourceDir?, map? }: send `message` (a full
+      // client-protocol message, built by srt) to the listed client ids, or to
+      // all when omitted. `latch` keeps it for late-joining clients (code
+      // reloads latch, one-shot bytecode loads do not); `sourceDir` moves the
+      // file-serving root (repl `load`); `map` is the bundle's sourcemap for
+      // log remapping, replaced on every reload (absent means none).
+      let body = await req.json()
+      if (typeof body.sourceDir === "string") state.sourceDir = body.sourceDir
+      // Keep the rebuild entry in sync when `load` moves it, so a later MCP
+      // reload bundles the newly loaded file, not the launch-time one.
+      if (typeof body.entry === "string") state.config.entry = body.entry
+      state.currentMap = typeof body.map === "string" ? body.map : null
+      let text = JSON.stringify(body.message)
+      if (body.latch) state.currentReload = text
+      sendTo(body.clients, text)
+      return new Response("", { status: 204 })
+    }
+    case "/__internal__/stop": {
+      let body = await req.json()
+      // A broadcast stop also forgets the latched reload, so a client that
+      // connects afterwards starts clean.
+      if (!body.clients) {
+        state.currentReload = null
+        state.currentMap = null
+      }
+      sendTo(body.clients, JSON.stringify({ type: "stop" }))
+      return new Response("", { status: 204 })
+    }
+    case "/__internal__/stats": {
+      let body = await req.json()
+      state.stats = !!body.stats
+      sendTo(undefined, JSON.stringify({ type: "stats", stats: state.stats }))
+      return new Response("", { status: 204 })
+    }
+    default:
+      return Response.json({ error: "Unknown internal endpoint" }, { status: 404 })
+  }
+}
+
+// The file routes: GET file (with single-range 206 support) or directory
+// listing, PUT file write. All paths are contained in the source directory.
+async function handleFiles(req: FluxRequest, path: string): Promise<Response> {
+  let filePath = resolveWithin(state.sourceDir, "." + path)
+  if (!filePath) {
+    return new Response("Forbidden", { status: 403 })
+  }
+
+  if (req.method === "PUT") {
+    console.log("[cli] put " + path)
+    let bytes = await req.bytes()
+    await file(filePath).write(bytes)
+    return new Response("", { status: 204 })
+  }
+
+  console.log("[cli] get " + path)
+
+  let stat
+  try {
+    stat = await file(filePath).stat()
+  } catch {
+    console.log(`[cli] file not found ${path}`)
+    return new Response("Not found", { status: 404 })
+  }
+
+  if (stat.type === "directory") {
+    let dirents = await dir(filePath).entries()
+    let entries = await Promise.all(
+      dirents.map(async (d) => {
+        let entry = { name: d.name, type: d.type === "directory" ? 2 : 1, size: 0, modified: 0 }
+        if (d.type !== "directory") {
+          try {
+            let s = await file(join(filePath, d.name)).stat()
+            entry.size = s.size
+            entry.modified = Math.floor(s.mtime ?? 0)
+          } catch {}
+        }
+        return entry
+      }),
+    )
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    return Response.json(entries, { headers: { "X-SRT-Type": "directory" } })
+  }
+
+  let baseHeaders: Record<string, string> = { "X-SRT-Type": "file", "Accept-Ranges": "bytes" }
+
+  // Honor a single byte-range request (e.g. streaming audio decoding on the
+  // client, which seeks and reads on demand). Only the common "bytes=a-b" /
+  // "bytes=a-" / "bytes=-n" forms; anything else falls through to the whole
+  // file. Range makes proxied streaming viable without pulling the whole
+  // track over the wire.
+  let range = req.headers.get("range")
+  let match = range ? /^bytes=(\d*)-(\d*)$/.exec(range.trim()) : null
+  if (match) {
+    let size = stat.size
+    let start: number
+    let end: number
+    if (match[1] === "") {
+      // Suffix range: the last N bytes.
+      let n = parseInt(match[2]!, 10)
+      start = isNaN(n) ? 0 : Math.max(0, size - n)
+      end = size - 1
+    } else {
+      start = parseInt(match[1]!, 10)
+      end = match[2] === "" ? size - 1 : Math.min(parseInt(match[2]!, 10), size - 1)
+    }
+    if (start > end || start >= size) {
+      return new Response("Range not satisfiable", {
+        status: 416,
+        headers: { ...baseHeaders, "Content-Range": `bytes */${size}` },
+      })
+    }
+    return new Response(await file(filePath).read(start, end - start + 1), {
+      status: 206,
+      headers: {
+        ...baseHeaders,
+        "Content-Range": `bytes ${start}-${end}/${size}`,
+        "Content-Length": String(end - start + 1),
+      },
+    })
+  }
+
+  return new Response(await file(filePath).bytes(), { headers: baseHeaders })
+}
+
+// Ticket-paired clients connect through this endpoint; serve() accepts its
+// connections directly alongside the TCP listener.
+let tunnel = config.tunnel ? await createTunnelEndpoint(config.port, config.cacheDir) : null
+
+serve({
+  port: config.port,
+  p2p: tunnel ? { endpoint: tunnel, protocol: TUNNEL_PROTOCOL } : undefined,
+  async fetch(req, server) {
+    if (server.upgrade(req)) return
+
+    let { path, query } = splitQuery(req.url)
+
+    if (path === "/__proxy__") {
+      return handleProxy(req)
+    }
+    if (path.startsWith("/__control__/")) {
+      return handleControl(req, path, query)
+    }
+    if (path.startsWith("/__internal__/")) {
+      return handleInternal(req, server, path)
+    }
+    return handleFiles(req, path)
+  },
+  websocket: {
+    open(ws) {
+      let id = state.nextClientId++
+      state.clients.set(ws, { platform: "unknown", version: "unknown", profile: "unknown", id, capabilities: [] })
+      console.log(`[cli] Client connected ${ws.remoteAddress ?? "unknown"}`)
+      // Advertise our real LAN address so clients dialed over a loopback hop
+      // can show/remember the directly reachable address (see connection.rs).
+      ws.send(
+        JSON.stringify({ type: "welcome", address: state.serverUrl, stats: state.stats, capture: !!config.capture }),
+      )
+      if (state.currentReload) {
+        ws.send(state.currentReload)
+      }
+    },
+    close(ws) {
+      let info = state.clients.get(ws)
+      state.clients.delete(ws)
+      console.log(`[cli] Client disconnected: ${info?.platform ?? "unknown"}`)
+    },
+    message(ws, msg) {
+      try {
+        let data = JSON.parse(typeof msg === "string" ? msg : new TextDecoder().decode(msg))
+        if (data.type === "info") {
+          let existing = state.clients.get(ws)
+          state.clients.set(ws, {
+            platform: data.platform ?? "unknown",
+            version: data.version ?? "unknown",
+            profile: data.profile ?? "unknown",
+            id: existing?.id ?? state.nextClientId++,
+            capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String) : [],
+          })
+          console.log(`[cli] Client info ${ws.remoteAddress ?? "unknown"} ${data.platform} (${data.version})`)
+        } else if (data.type === "log") {
+          // Forwarded console output / runtime errors from the client's
+          // engine logger, buffered for the control API (see control.ts).
+          // Not printed here: the local client already writes to this
+          // terminal, so echoing would duplicate every line.
+          let device = state.clients.get(ws)?.id ?? -1
+          appendLog(device, String(data.level ?? "log"), String(data.text ?? ""))
+        } else if (data.type === "result") {
+          // Reply to a query the control API forwarded to this client.
+          resolveQuery(data)
+        } else if (data.type === "capture" && config.capture) {
+          let device = state.clients.get(ws)?.id ?? -1
+          // Milliseconds, integer: Date.now() is already integer ms, so the
+          // delta needs no rounding.
+          let at = Date.now() - state.captureStartMs
+          let after = at - state.captureLastAt
+          state.captureLastAt = at
+          // JSON Lines: one event object per line, streamed to disk as it
+          // arrives rather than buffered - no in-memory growth for a long
+          // capture, and the file is always complete on disk mid-session.
+          // Appends are chained so events land in arrival order.
+          let line = JSON.stringify({ after, type: data.kind, key: data.key, device }) + "\n"
+          state.captureChain = state.captureChain.then(() => file(config.capture!).append(line))
+        }
+      } catch {}
+    },
+  },
+})
+
+// One QR on screen: with the tunnel on, the ticket QR (printed by
+// createTunnelEndpoint) is the pairing story and the address stays text-only;
+// without it, the address QR is the scan target as before.
+if (!config.tunnel) {
+  console.log("")
+  printQr(state.serverUrl)
+  console.log("")
+}
+console.log(`[cli] WebSocket server on ws://${state.serverUrl}`)
+// mDNS advertise is intentionally not implemented here: the p2p ticket is the
+// cross-device connect story (see docs/flux-dev-server-plan.md).
+
+// Keepalive
+setInterval(() => {
+  for (let ws of state.clients.keys()) {
+    ws.ping()
+  }
+}, 5000)

package/server/proxy.ts

@@ -0,0 +1,72 @@
+import * as cache from "./cache"
+
+// The /__proxy__ endpoint: forward a request to the URL in X-SRT-Proxy-Url,
+// buffering the upstream response, with the opt-in sqlite cache in front.
+
+function headersToObject(h: Headers): Record<string, string> {
+  let out: Record<string, string> = {}
+  h.forEach((v, k) => {
+    out[k] = v
+  })
+  return out
+}
+
+export async function handleProxy(req: Request): Promise<Response> {
+  let target = req.headers.get("x-srt-proxy-url")
+  if (!target) {
+    return new Response("Missing X-SRT-Proxy-Url", { status: 400 })
+  }
+
+  let forwardHeaders = new Headers(req.headers)
+  forwardHeaders.delete("host")
+  forwardHeaders.delete("x-srt-proxy-url")
+  forwardHeaders.delete("x-srt-cache")
+  forwardHeaders.delete("content-length")
+
+  let cacheStatus: cache.Decision = "skip"
+  let cacheable = !cache.shouldConsider(req.method, req.headers).skip
+  let bypass = cacheable && cache.isBypass(req.headers)
+
+  if (cacheable && !bypass) {
+    let hit = await cache.get(req.method, target)
+    if (hit) {
+      console.log(`[cli] proxy ${req.method} ${target} [cache hit]`)
+      let respHeaders = new Headers(hit.headers)
+      respHeaders.set("x-srt-cache", "hit")
+      return new Response(hit.body, { status: hit.status, headers: respHeaders })
+    }
+  }
+
+  let hasBody = req.method !== "GET" && req.method !== "HEAD"
+  if (cacheable) {
+    cacheStatus = bypass ? "bypass" : "miss"
+    console.log(`[cli] proxy ${req.method} ${target} [${cacheStatus}]`)
+  } else {
+    console.log(`[cli] proxy ${req.method} ${target}`)
+  }
+
+  try {
+    let upstream = await fetch(target, {
+      method: req.method,
+      headers: forwardHeaders,
+      body: hasBody ? await req.bytes() : undefined,
+    })
+    let respHeaders = new Headers(upstream.headers)
+    respHeaders.delete("content-encoding")
+    respHeaders.delete("transfer-encoding")
+
+    let bodyBytes = await upstream.bytes()
+    if (cacheable) {
+      await cache.put(req.method, target, upstream.status, headersToObject(respHeaders), bodyBytes)
+      respHeaders.set("x-srt-cache", cacheStatus)
+    }
+    return new Response(bodyBytes, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: respHeaders,
+    })
+  } catch (e) {
+    console.log(`[cli] proxy error ${target}: ${String(e)}`)
+    return new Response(`Proxy error: ${String(e)}`, { status: 502 })
+  }
+}

package/server/qr.ts

@@ -0,0 +1,35 @@
+import qrcode from "qrcode-generator"
+
+// Render `text` as a terminal QR code: a white tile with black modules
+// (explicit ANSI colors) plus the quiet zone the QR spec requires. Drawing with
+// the terminal's default foreground inverts the code on dark themes, which
+// standard decoders reject.
+export function printQr(text: string) {
+  let qr = qrcode(0, "L")
+  qr.addData(text)
+  qr.make()
+  let modCount = qr.getModuleCount()
+  const QR_INK = "\x1b[30;107m" // black modules on bright-white tile (tile = background)
+  const QR_TILE_FG = "\x1b[97m" // bright-white as foreground over the default background
+  const QR_RESET = "\x1b[0m"
+  const QUIET_ZONE = 2 // modules (spec says 4, but scanners cope and it reads tighter)
+  let qrWidth = modCount + 2 * QUIET_ZONE
+  let dark = (y: number, x: number) => y >= 0 && y < modCount && x >= 0 && x < modCount && qr.isDark(y, x)
+  // modCount is always odd, so the tile is a half-line taller than an even row
+  // count. The loop packs two module-rows per line via half-blocks and stops on
+  // the last content row, leaving the bottom quiet zone half a line short of the
+  // full-line top quiet zone.
+  for (let y = -QUIET_ZONE; y < modCount + QUIET_ZONE - 1; y += 2) {
+    let row = "  " + QR_INK
+    for (let x = -QUIET_ZONE; x < modCount + QUIET_ZONE; x++) {
+      let top = dark(y, x)
+      let bot = dark(y + 1, x)
+      row += top && bot ? "\u2588" : top ? "\u2580" : bot ? "\u2584" : " "
+    }
+    console.log(row + QR_RESET)
+  }
+  // Close that gap with a half-height tile line: upper half painted in the tile
+  // color (foreground), lower half the terminal background. The 0.5 here plus
+  // the 0.5 already under the last content row equal the full-line top margin.
+  console.log("  " + QR_TILE_FG + "\u2580".repeat(qrWidth) + QR_RESET)
+}

package/server/rebuild.ts

@@ -0,0 +1,54 @@
+import { command } from "flux:subprocess"
+import { state } from "./state"
+
+// Server-owned "rebuild and push": the single place the running app is rebuilt
+// from source on demand (an MCP reload). The srt repl still bundles in-process
+// for its own keystroke reloads, but both routes call the same bundle-cli, so
+// the bundling logic cannot drift. Making the server the rebuild authority is
+// the interim step toward folding the whole CLI into flux (see
+// okf/backlog/cli-flux-migration.md).
+
+// Build the reload message the same way srt's buildReload does, so a
+// server-triggered reload is indistinguishable from a repl-triggered one to
+// clients. proxyFiles/proxyHttp are message flags, not build inputs.
+function buildReload(code: string) {
+  let config = state.config
+  return { type: "reload", proxyFiles: config.proxyFiles, proxyHttp: config.proxyHttp, code }
+}
+
+// Rebuild from state.config.entry via the external bundle-cli subprocess, then
+// latch (for late-joining clients) and broadcast the reload to every connected
+// client. Resolves with an error message on failure (no entry configured, or a
+// build error), or null on success.
+export async function rebuildAndBroadcast(): Promise<string | null> {
+  let config = state.config
+  if (!config.entry) {
+    return "No app entry to rebuild. Start srt with a source file (srt run src/index.tsx)."
+  }
+
+  let params = JSON.stringify({
+    entry: config.entry,
+    devBase: state.serverUrl,
+    dev: true,
+    minify: config.minify,
+  })
+
+  let result = await command(config.bundlerCmd[0]!, [...config.bundlerCmd.slice(1), params]).output()
+  if (!result.success) {
+    let stderr = typeof result.stderr === "string" ? result.stderr : ""
+    return `Rebuild failed:\n${stderr.trim()}`
+  }
+
+  // bundle-cli writes one JSON object { code, map } to stdout.
+  let bundle: { code?: string; map?: string | null }
+  try {
+    bundle = JSON.parse(typeof result.stdout === "string" ? result.stdout : "")
+  } catch {
+    return "Rebuild failed: unreadable bundler output"
+  }
+  state.currentMap = bundle.map ?? null
+  let text = JSON.stringify(buildReload(bundle.code ?? ""))
+  state.currentReload = text
+  for (let ws of state.clients.keys()) ws.send(text)
+  return null
+}

package/server/remap.ts

@@ -0,0 +1,47 @@
+import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping"
+
+// Stack-trace remapping for forwarded client logs. The runtime evaluates the
+// bundle as module "main", so QuickJS frames cite bundle positions like
+// "at boom (main:212:9)". With the current reload's sourcemap latched on the
+// server (state.currentMap), those positions are rewritten to the original
+// .tsx sources before a log entry is buffered.
+
+// The parsed map is cached per map text; a reload swaps the text and the next
+// lookup rebuilds the tracer.
+let cachedText: string | null = null
+let tracer: TraceMap | null = null
+
+function tracerFor(map: string | null): TraceMap | null {
+  if (map !== cachedText) {
+    cachedText = map
+    tracer = null
+    if (map) {
+      try {
+        tracer = new TraceMap(JSON.parse(map))
+      } catch {
+        // A malformed map disables remapping until the next reload.
+      }
+    }
+  }
+  return tracer
+}
+
+/**
+ * Rewrite every "main:LINE:COL" (or "main:LINE") position in `text` to its
+ * original source position, e.g. "src/app.tsx:42:7". Positions the map has no
+ * entry for, and all text when `map` is null, pass through unchanged.
+ * QuickJS lines and columns are 1-based; sourcemap columns are 0-based.
+ */
+export function remapPositions(text: string, map: string | null): string {
+  if (!map || !text.includes("main:")) return text
+  let t = tracerFor(map)
+  if (!t) return text
+  return text.replace(/\bmain:(\d+)(?::(\d+))?\b/g, (frame, line, column) => {
+    let pos = originalPositionFor(t, {
+      line: parseInt(line, 10),
+      column: column ? Math.max(parseInt(column, 10) - 1, 0) : 0,
+    })
+    if (pos.source == null || pos.line == null) return frame
+    return `${pos.source}:${pos.line}:${(pos.column ?? 0) + 1}`
+  })
+}

package/server/state.ts

@@ -0,0 +1,62 @@
+// Server-side state shared by the route handlers. The srt process keeps the
+// bundler, watcher, and repl; this state is only what the protocol needs.
+
+import type { ServerWebSocket } from "flux:http"
+
+export type Config = {
+  port: number
+  /** Directory served by the file routes (updatable via /__internal__/reload). */
+  sourceDir: string
+  /** The address clients can reach this machine on (LAN IP or 127.0.0.1). */
+  address: string
+  proxyFiles: boolean
+  proxyHttp: boolean
+  /** The app entry (absolute .tsx/.jsx path) the server rebuilds on an
+   * MCP-triggered reload, or undefined when srt was started without a source.
+   * Moved by the repl `load` command via /__internal__/reload. */
+  entry?: string
+  /** Minify the rebuild output, mirroring the srt --minify flag. */
+  minify: boolean
+  /** How the server invokes the external bundler: [bunPath, bundleCliPath],
+   * spawned with a JSON params argument appended (see rebuild.ts). */
+  bundlerCmd: string[]
+  /** Enable the sqlite-backed proxy cache. */
+  cache: boolean
+  /** Directory holding .srt-cache.db. */
+  cacheDir: string
+  /** Destination for captured key events, or unset when off. */
+  capture?: string
+  stats: boolean
+  /** Accept ticket-paired clients through the p2p tunnel. */
+  tunnel: boolean
+}
+
+export type ClientInfo = { platform: string; version: string; profile: string; id: number; capabilities: string[] }
+
+export let state = {
+  config: undefined as unknown as Config,
+  clients: new Map<ServerWebSocket, ClientInfo>(),
+  nextClientId: 0,
+  /**
+   * The latched reload message (JSON text), replayed to late-joining clients.
+   * Set by /__internal__/reload posts with `latch`, cleared by a broadcast stop.
+   */
+  currentReload: null as string | null,
+  /**
+   * The running bundle's sourcemap (JSON text, bundle -> .tsx sources), used
+   * to remap stack traces in forwarded client logs (see control.ts). Replaced
+   * on every reload; a reload without a map clears it so frames are never
+   * remapped against a stale map.
+   */
+  currentMap: null as string | null,
+  sourceDir: "",
+  serverUrl: "",
+  stats: false,
+  // Capture events from all connected clients share one clock (captureStartMs,
+  // integer milliseconds) so they merge into one coherent timeline, tagged by
+  // `device`. Streamed to disk as JSON Lines - see main.ts's "capture" handling.
+  captureStartMs: 0,
+  captureLastAt: 0, // ms, same clock as captureStartMs
+  /** Serializes capture appends so events land on disk in arrival order. */
+  captureChain: Promise.resolve(),
+}

package/server/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "types": ["@solidrt/flux-types"]
+  },
+  "include": ["."]
+}

package/server/tunnel.ts

@@ -0,0 +1,53 @@
+// The p2p tunnel: an iroh endpoint carrying the dev protocol for clients that
+// pair by ticket instead of dialing the TCP port. serve() accepts connections
+// on the endpoint directly (the endpoint/protocol serve options), so the
+// HTTP/WS protocol is spoken straight over each connection's first bi-stream -
+// no pump. Local-only: the endpoint uses no relay and publishes nothing, so
+// the ticket (direct addresses) is the sole carrier of addressing. Off-LAN
+// relay support is a future opt-in flag, not the default.
+
+import { Endpoint } from "flux:p2p"
+import { file } from "flux:fs"
+import { join } from "flux:path"
+import { printQr } from "./qr"
+
+// The tunnel's ALPN. A protocol change bumps the suffix so old clients fail
+// the handshake instead of desyncing.
+export const TUNNEL_PROTOCOL = "solidrt-dev/0"
+
+// The persisted identity file, project-local next to the HTTP cache. Delete it
+// to rotate the tunnel's identity (which invalidates any old ticket).
+const KEY_FILE = ".srt-tunnel-key"
+
+/**
+ * Bind the tunnel endpoint and print its ticket (text + QR). The endpoint is
+ * kept stable across restarts so a paired client can re-dial the old ticket
+ * without re-scanning: the UDP port is pinned to the dev server's port, and the
+ * secret key is persisted in <cacheDir>/.srt-tunnel-key (generated on first
+ * run). Both are needed - a moving port or a fresh key each start would change
+ * the ticket. Stable across restarts on the same network only; a new machine IP
+ * still stales the ticket's addresses (that is the discovery/off-LAN story).
+ */
+export async function createTunnelEndpoint(port: number, cacheDir: string): Promise<Endpoint> {
+  let keyPath = join(cacheDir, KEY_FILE)
+
+  let secretKey: string | undefined
+  let keyFile = file(keyPath)
+  if (await keyFile.exists()) {
+    let saved = (await keyFile.text()).trim()
+    if (saved.length === 64) secretKey = saved
+  }
+
+  let endpoint = await Endpoint.create({ local: true, protocols: [TUNNEL_PROTOCOL], port, secretKey })
+
+  // First run (no saved key): persist the freshly generated one so the next run
+  // reuses it and the ticket stays the same.
+  if (!secretKey) await keyFile.write(endpoint.secretKey)
+
+  let ticket = await endpoint.ticket()
+  console.log("")
+  printQr(ticket)
+  console.log("")
+  console.log(`[cli] Tunnel ticket: ${ticket}`)
+  return endpoint
+}

package/src/args.ts

@@ -15,6 +15,7 @@ export let { values, positionals } = parseArgs({
     size: { type: "string" },
     script: { type: "string" },
     capture: { type: "string" },
+    tunnel: { type: "boolean", default: false },
     stats: { type: "boolean", default: false },
     android: { type: "boolean", default: false },
     device: { type: "string" },
@@ -84,6 +85,7 @@ run/server options:
       --proxy-files      Route file/dir access through the dev server
       --proxy-http       Route fetch calls through the dev server (HTTP cache enabled)
       --capture <file>   Record connected clients' key events to a script file
+      --tunnel           Accept ticket-paired clients through the p2p tunnel
 
 run/client options:
       --size <WxH>       Window size (default: 1280x720)

package/src/bundle-cli.ts

@@ -0,0 +1,12 @@
+// Standalone bundler entry, spawned by the dev server (a flux process) as a
+// Bun subprocess to rebuild the app on an MCP-triggered reload. flux cannot call
+// Bun.build, so the server shells out to this. Params arrive as one JSON
+// argument; one JSON object { code, map } goes to stdout and diagnostics to
+// stderr. On a build failure it exits non-zero with an empty stdout.
+
+import { bundleWith, type BundleOptions } from "./bundler"
+
+let params = JSON.parse(process.argv[2] ?? "{}") as BundleOptions
+let result = await bundleWith(params)
+if (!result) process.exit(1)
+process.stdout.write(JSON.stringify(result))