@solidrt/cli 0.0.25 → 0.0.26

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" },
@@ -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/commands/mcp.ts

@@ -79,6 +79,20 @@ let TOOLS = [
       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 {
@@ -100,6 +114,12 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       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}` }
   }
@@ -115,10 +135,20 @@ export async function runMcpCommand() {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
   server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
-    let result = await callTool(request.params.name, request.params.arguments ?? {})
+    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) }] }
   })
 

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()
   })
-}
+}