@solidrt/cli 0.0.24 → 0.0.26

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/state.ts

@@ -0,0 +1,46 @@
+// 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
+  /** 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; 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,
+  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" },
@@ -75,6 +76,7 @@ Commands:
   bundle <file>          Transpile TS/JS/TSX/JSX to JS or bytecode
   render <file.tsx|jsx>  Replay a script (optional) and render frames for video generation
   pack <file>            Bundle + compile to a standalone executable (experimental)
+  mcp                    MCP server (stdio) exposing the running dev server to coding agents
 
 init options:
   -t, --template <name>  Start from a named template (skips the interactive picker)
@@ -83,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/commands/init.ts

@@ -16,6 +16,7 @@ const TEMPLATE_FILES: Array<{ from: string; to: string }> = [
   { from: "package.json", to: "package.json" },
   { from: "tsconfig.json", to: "tsconfig.json" },
   { from: "gitignore", to: ".gitignore" },
+  { from: "mcp.json", to: ".mcp.json" },
   { from: "AGENTS.md", to: "AGENTS.md" },
 ]
 

package/src/commands/mcp.ts

@@ -0,0 +1,158 @@
+// The MCP bridge: a stdio Model Context Protocol server exposing the dev
+// server's control API (/__control__/) as tools for coding agents. Stateless
+// glue: every tool call is one HTTP request to the running dev server, so the
+// bridge works no matter which process (or how many agents) spawned it.
+//
+// stdout is the JSON-RPC channel; nothing here may print to it.
+
+import { DEV_PORT } from "../dev-server"
+
+const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
+
+type ControlResult = { ok: true; body: any } | { ok: false; message: string }
+
+async function control(path: string): Promise<ControlResult> {
+  let resp
+  try {
+    resp = await fetch(CONTROL_BASE + path)
+  } catch {
+    return {
+      ok: false,
+      message: "Dev server not running. Start it in the project first: srt run src/index.tsx (or srt server)",
+    }
+  }
+  let body: any = null
+  try {
+    body = await resp.json()
+  } catch {}
+  if (!resp.ok) return { ok: false, message: String(body?.error ?? `Dev server responded with HTTP ${resp.status}`) }
+  return { ok: true, body }
+}
+
+let TOOLS = [
+  {
+    name: "list_clients",
+    description:
+      "List the app clients connected to the SolidRT dev server. Each entry has id (pass it as `client` to the other tools), platform, runtime version, and the capability names compiled into that client's runtime.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "get_logs",
+    description:
+      "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text) plus `latest`, the newest seq. Pass `since` (a seq or `latest` from a previous call) to only get newer entries; pass `wait_ms` to hold the call until new output arrives, e.g. right after triggering a reload.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since: {
+          type: "integer",
+          description: "Only return entries with seq greater than this (default 0: the whole buffer)",
+        },
+        wait_ms: {
+          type: "integer",
+          description: "If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_stats",
+    description:
+      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_render_tree",
+    description:
+      "Snapshot of a running app client's render tree: node id, kind, window-relative box (x, y, width, height), text content, and children. Use it to verify what the app actually rendered and where.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_snapshot",
+    description:
+      "Capture a PNG image of any node in a running app client's render tree, by node id (get ids from get_render_tree). Returns the rendered pixels of that node's subtree, so you can see what the app actually drew. The node must be currently mounted and have a non-zero layout box.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "integer", description: "Id of the node to capture, from get_render_tree" },
+        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
+      },
+      required: ["nodeId"],
+      additionalProperties: false,
+    },
+  },
+]
+
+function clientParam(args: any): string {
+  return typeof args?.client === "number" ? `?client=${args.client}` : ""
+}
+
+async function callTool(name: string, args: any): Promise<ControlResult> {
+  switch (name) {
+    case "list_clients":
+      return control("/clients")
+    case "get_logs": {
+      let params = new URLSearchParams()
+      if (typeof args?.since === "number") params.set("since", String(args.since))
+      if (typeof args?.wait_ms === "number") params.set("wait", String(args.wait_ms))
+      let qs = params.toString()
+      return control(qs ? `/logs?${qs}` : "/logs")
+    }
+    case "get_stats":
+      return control(`/stats${clientParam(args)}`)
+    case "get_render_tree":
+      return control(`/tree${clientParam(args)}`)
+    case "get_snapshot": {
+      if (typeof args?.nodeId !== "number") return { ok: false, message: "get_snapshot requires a numeric nodeId" }
+      let params = new URLSearchParams({ node: String(args.nodeId) })
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/snapshot?${params.toString()}`)
+    }
+    default:
+      return { ok: false, message: `Unknown tool: ${name}` }
+  }
+}
+
+export async function runMcpCommand() {
+  let { Server } = await import("@modelcontextprotocol/sdk/server/index.js")
+  let { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js")
+  let { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js")
+
+  let server = new Server({ name: "solidrt", version: "0.0.0" }, { capabilities: { tools: {} } })
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+    let name = request.params.name
+    let result = await callTool(name, request.params.arguments ?? {})
+    if (!result.ok) {
+      return { content: [{ type: "text", text: result.message }], isError: true }
+    }
+    if (name === "get_snapshot") {
+      let { pngBase64, width, height } = result.body
+      return {
+        content: [
+          { type: "image", data: pngBase64, mimeType: "image/png" },
+          { type: "text", text: `Captured node snapshot: ${width}x${height} px` },
+        ],
+      }
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result.body, null, 2) }] }
+  })
+
+  // The stdin read keeps the process alive; it exits when the agent host
+  // closes the pipe.
+  await server.connect(new StdioServerTransport())
+}

package/src/commands/server.ts

@@ -2,44 +2,39 @@ import pkg from "../../package.json"
 import { source, isSource, isPrebuilt, values } from "../args"
 import { state, shutdown } from "../util"
 import { bundle, codeFromOutputs } from "../bundler"
-import { startServer, showBuildFailure } from "../dev-server"
+import { startServer, buildReload, sendReload, showBuildFailure } from "../dev-server"
 import { startRepl } from "../repl"
 import { startWatcher } from "../watcher"
-import * as cache from "../cache"
 import { resolve, dirname } from "path"
-import { writeFileSync } from "node:fs"
 
-// Brings up the dev server (HTTP/WS + initial bundle + repl + watcher). The
-// `run` command spawns a local client on top of this from main.ts.
+// Brings up the dev server (a spawned flux script serving HTTP/WS) plus the
+// initial bundle, repl, and watcher in this process. The `run` command spawns
+// a local client on top of this from main.ts.
 export async function runServerCommand() {
   // Initialize state from args
   state.source = source
   state.sourceDir = source ? dirname(resolve(source)) : process.cwd()
   state.stats = values.stats
   state.capture = values.capture ? resolve(values.capture) : undefined
-  state.captureStartMs = Date.now()
-  // Start each capture from an empty file: appendFileSync (dev-server.ts)
-  // would otherwise tack onto whatever a previous run left behind.
-  if (state.capture) writeFileSync(state.capture, "")
 
-  if (values["proxy-http"]) {
-    cache.initCache({ dir: process.cwd() })
-    console.log("[cli] HTTP cache enabled")
-  }
-
-  startServer()
+  // Spawns the server process and waits until it answers; it owns the QR and
+  // address announcements, the capture file, and the proxy cache.
+  await startServer()
 
   // Bundle initial code if source file given (after server start so the
-  // dev base URL is available to the bundler).
+  // dev base URL is available to the bundler), and latch it on the server
+  // for the clients about to connect.
   if (source && isSource) {
     let initialResult = await bundle()
     if (initialResult) {
       state.currentCode = await codeFromOutputs(initialResult.outputs)
+      await sendReload(buildReload({ code: state.currentCode }), { latch: true })
     } else {
-      showBuildFailure()
+      await showBuildFailure()
     }
   } else if (source && isPrebuilt && source.endsWith(".srt.js")) {
     state.currentCode = await Bun.file(resolve(source)).text()
+    await sendReload(buildReload({ code: state.currentCode }), { latch: true })
   }
 
   process.on("SIGINT", shutdown)
@@ -49,4 +44,4 @@ export async function runServerCommand() {
   console.log(`[cli] Welcome to SolidRT${version}!`)
   startRepl()
   startWatcher()
-}
+}

package/src/dev-client.ts

@@ -1,20 +1,7 @@
-import { state, print, requireBinary } from "./util"
-import { DEV_HOST, DEV_PORT } from "./dev-server"
+import { state, print, requireBinary, pipeAbovePrompt, shutdown } from "./util"
+import { DEV_HOST, DEV_PORT, getClients, shutdownWhenEmpty } from "./dev-server"
 import { values } from "./args"
 
-function pipeAbovePrompt(stream: ReadableStream<Uint8Array>, out: NodeJS.WriteStream) {
-  let reader = stream.getReader()
-  ;(async () => {
-    while (true) {
-      let { done, value } = await reader.read()
-      if (done || !value) break
-      process.stdout.write("\r\x1b[K")
-      out.write(value)
-      state.rl?.prompt(true)
-    }
-  })()
-}
-
 export function spawnClient() {
   let runner = requireBinary("solidrt-go")
   // The local client and dev server share this machine, so connect straight to
@@ -30,11 +17,13 @@ export function spawnClient() {
   if (state.child.stderr && typeof state.child.stderr !== "number")
     pipeAbovePrompt(state.child.stderr, process.stderr)
 
-  state.child.exited.then(() => {
-    if (state.clients.size === 0) {
-      state.server?.stop()
-      process.exit(0)
+  state.child.exited.then(async () => {
+    let clients = await getClients().catch(() => [])
+    if (clients.length === 0) {
+      shutdown()
     }
-    print(`[cli] Local client exited, ${state.clients.size} remote client(s) still connected`)
+    print(`[cli] Local client exited, ${clients.length} remote client(s) still connected`)
+    // From here, exit once the last remote client disconnects.
+    shutdownWhenEmpty()
   })
-}
+}