@solidrt/cli 0.0.51 → 0.0.52

package/{server → src/server}/control.ts

@@ -1,8 +1,20 @@
-import { file } from "flux:fs"
 import { state } from "./state"
 import { rebuildAndBroadcast } from "./rebuild"
 import { remapPositions } from "./remap"
+import { ENTRY_EXTENSIONS, absolute, dirname } from "./mode"
+import { file, realpath } from "flux:fs"
 import type { ServerWebSocket } from "flux:http"
+import type {
+  ClientEntry,
+  ClientsResponse,
+  LoadResponse,
+  LogEntry,
+  LogsResponse,
+  MuteResponse,
+  ReloadResponse,
+  StatsResponse,
+  WatchResponse,
+} from "../types/control"
 
 // The control API under /__control__/: read-only introspection of connected
 // app clients, served next to the file routes. The MCP bridge (srt mcp) is the
@@ -10,8 +22,6 @@ import type { ServerWebSocket } from "flux:http"
 // logs) and queries forwarded to a client over its websocket and correlated
 // back by id (tree, stats).
 
-export type LogEntry = { seq: number; at: number; client: number; level: string; text: string }
-
 // Ring buffer of forwarded client logs. Capped so a chatty app cannot grow the
 // server without bound; readers page through it with the `since` cursor.
 const LOG_CAP = 2000
@@ -54,7 +64,7 @@ export function resolveQuery(msg: { id?: number }) {
 // The connected-client list. `withAddress` adds each socket's peer address for
 // the internal API (the repl `list` display); the public control shape stays
 // without it.
-export function clientList(withAddress = false) {
+export function clientList(withAddress = false): (ClientEntry & { address?: string | null })[] {
   return [...state.clients.entries()].map(([ws, info]) => ({
     id: info.id,
     platform: info.platform,
@@ -62,6 +72,16 @@ export function clientList(withAddress = false) {
     profile: info.profile,
     capabilities: info.capabilities,
     queries: info.queries,
+    stats: info.stats,
+    timeScale: info.timeScale,
+    clientDir: info.clientDir,
+    pid: info.pid,
+    execPath: info.execPath,
+    host: info.host,
+    os: info.os,
+    kernel: info.kernel,
+    videoDriver: info.videoDriver,
+    gpu: info.gpu,
     ...(withAddress ? { address: ws.remoteAddr ?? null } : {}),
   }))
 }
@@ -105,6 +125,17 @@ function parseRect(query: Map<string, string>): { x: number; y: number; width: n
   return { x: x!, y: y!, width: width!, height: height! }
 }
 
+// Optional output format shared by /snapshot and /texture: "png" (default,
+// the reply carries pngBase64) or "raw" (rgbaBase64: RGBA8 bytes, rows
+// top-down, no decoder needed for pixel assertions). Returns undefined for
+// the default, or a 400 Response.
+function parseFormat(query: Map<string, string>): "raw" | undefined | Response {
+  let param = query.get("format")
+  if (param === undefined || param === "png") return undefined
+  if (param === "raw") return "raw"
+  return Response.json({ error: 'Format must be "png" or "raw"' }, { status: 400 })
+}
+
 // Optional integer magnification shared by /snapshot and /texture. Returns
 // undefined when absent or 1, a 400 Response when out of range.
 function parseScale(query: Map<string, string>): number | Response | undefined {
@@ -116,30 +147,46 @@ function parseScale(query: Map<string, string>): number | Response | undefined {
   return scale === 1 ? undefined : scale
 }
 
-async function handleQuery(
-  query: Map<string, string>,
+// Forward a query to one client and wait for its answer: the data it
+// replied with, or the error Response to send instead (no such client, a
+// timeout, or the client's own error).
+async function queryClient(
+  ws: ServerWebSocket,
   kind: string,
   extra?: Record<string, unknown>,
   timeoutMs: number = QUERY_TIMEOUT_MS,
-): Promise<Response> {
-  let target = findClient(query.get("client"))
-  if ("error" in target) return target.error
+): Promise<{ data: any } | { error: Response }> {
   let id = nextQueryId++
   let reply = new Promise<any>((resolve) => {
     pendingQueries.set(id, resolve)
   })
-  target.ws.send(JSON.stringify({ type: "query", kind, id, ...extra }))
+  ws.send(JSON.stringify({ type: "query", kind, id, ...extra }))
   let msg = await Promise.race([reply, sleep(timeoutMs)])
   pendingQueries.delete(id)
   if (!msg)
-    return Response.json(
-      { error: "Query timed out: the client is connected but did not answer (JS thread busy or app wedged?)" },
-      { status: 504 },
-    )
+    return {
+      error: Response.json(
+        { error: "Query timed out: the client is connected but did not answer (JS thread busy or app wedged?)" },
+        { status: 504 },
+      ),
+    }
   // Error strings may carry stack traces (e.g. a debug command threw); remap
   // bundle positions to .tsx sources like appendLog does for forwarded logs.
-  if (msg.error) return Response.json({ error: remapPositions(String(msg.error), state.currentMaps) }, { status: 502 })
-  return Response.json(msg.data)
+  if (msg.error)
+    return { error: Response.json({ error: remapPositions(String(msg.error), state.currentMaps) }, { status: 502 }) }
+  return { data: msg.data }
+}
+
+async function handleQuery(
+  query: Map<string, string>,
+  kind: string,
+  extra?: Record<string, unknown>,
+  timeoutMs: number = QUERY_TIMEOUT_MS,
+): Promise<Response> {
+  let target = findClient(query.get("client"))
+  if ("error" in target) return target.error
+  let result = await queryClient(target.ws, kind, extra, timeoutMs)
+  return "error" in result ? result.error : Response.json(result.data)
 }
 
 // Merge runs of consecutive identical entries (same client, level, text) into
@@ -160,9 +207,10 @@ function collapseRepeats(entries: LogEntry[]): (LogEntry & { repeats?: number })
   return out
 }
 
-// GET /__control__/logs?since=N&wait=MS&level=L1,L2&contains=TEXT: entries with
-// seq > since, plus the latest seq as the next cursor and the server
-// generation. `level` keeps only the listed levels; `contains` keeps entries
+// GET /__control__/logs?since=N&wait=MS&level=L1,L2&contains=TEXT&client=ID:
+// entries with seq > since, plus the latest seq as the next cursor and the
+// server generation. `client` keeps one client's entries (every client's
+// without); `level` keeps only the listed levels; `contains` keeps entries
 // whose text has the substring (case-insensitive). Consecutive identical
 // entries come back collapsed with a `repeats` count. With `wait`, holds the
 // response until an entry passes the filters or the timeout expires
@@ -176,10 +224,20 @@ async function handleLogs(query: Map<string, string>): Promise<Response> {
     .map((l) => l.trim())
     .filter(Boolean)
   let contains = query.get("contains")?.toLowerCase()
+  // The client filter takes any id, connected or not: a client that crashed
+  // is gone from /clients but its output is what the caller wants to read.
+  // Only a malformed id is refused, instead of silently disabling the filter.
+  let client: number | undefined
+  let clientParam = query.get("client")
+  if (clientParam !== undefined) {
+    client = parseInt(clientParam, 10)
+    if (!Number.isFinite(client)) return Response.json({ error: "Client must be a numeric id" }, { status: 400 })
+  }
   let select = () =>
     logs.filter(
       (e) =>
         e.seq > since &&
+        (client === undefined || e.client === client) &&
         (!levels || levels.length === 0 || levels.includes(e.level)) &&
         (!contains || e.text.toLowerCase().includes(contains)),
     )
@@ -197,21 +255,108 @@ async function handleLogs(query: Map<string, string>): Promise<Response> {
     })
     entries = select()
   }
-  return Response.json({ entries: collapseRepeats(entries), latest: logSeq, generation: state.generation })
+  let body: LogsResponse = { entries: collapseRepeats(entries), latest: logSeq, generation: state.generation }
+  return Response.json(body)
+}
+
+// Whether `path` lies under `root` (both canonical), never equal to it.
+function isUnder(path: string, root: string): boolean {
+  return path.length > root.length && path.startsWith(root) && (path[root.length] === "/" || path[root.length] === "\\")
+}
+
+// Load (or switch) the app entry and push it: the /load route (srt mcp's
+// load tool) and the repl's `load`. Moves the rebuild entry, then reuses the
+// reload path, so later reloads rebuild the new file. A project server stays
+// inside its project (the bundle resolves the project's dependencies and
+// assets, and the key keeps naming the project); a file server takes any
+// file, moving the file routes and the bundler's cwd along with the entry.
+// The key never moves: it names what the server was started for, and
+// /clients reports the entry next to it. `status` is the HTTP status the
+// error maps to (400 for a bad request, 502 for a failed build).
+export async function loadEntry(requested: string): Promise<{ entry: string } | { error: string; status: number }> {
+  if (!ENTRY_EXTENSIONS.some((ext) => requested.endsWith(ext))) {
+    return { error: `Not an app entry: ${requested} (expected .tsx, .jsx, .ts, .js or .srt.js)`, status: 400 }
+  }
+  let config = state.config
+  let path = absolute(requested, config.projectDir ?? config.sourceDir)
+  if (!(await file(path).exists())) return { error: `Entry not found: ${path}`, status: 400 }
+  let entry = await realpath(path)
+  if (config.projectDir && !isUnder(entry, config.projectDir)) {
+    return {
+      error: `Entry is outside the project: ${entry} is not under ${config.projectDir}. A project server only bundles sources inside its project; start srt for that file on its own.`,
+      status: 400,
+    }
+  }
+  config.entry = entry
+  config.entryArgs[0] = entry
+  if (!config.projectDir) {
+    config.sourceDir = dirname(entry)
+    config.cwd = config.sourceDir
+  }
+  console.log(`[cli] Loading ${entry}`)
+  let error = await rebuildAndBroadcast()
+  if (error) return { error, status: 502 }
+  return { entry }
+}
+
+// Mute or unmute the user's own input on every client (srt mcp's
+// mute_user_input/unmute_user_input, the repl's `mute`): while muted, a
+// measurement or an interaction test is not disturbed by a stray click;
+// synthetic /input still goes through. Latched for clients joining while
+// muted (the welcome message) and broadcast to the connected ones; no ack,
+// the mute takes effect on arrival.
+export function setUserInputMuted(on: boolean) {
+  if (on !== state.userInputMuted) {
+    console.log(on ? "[cli] User input muted on every client" : "[cli] User input unmuted")
+  }
+  state.userInputMuted = on
+  let text = JSON.stringify({ type: "mute", active: on })
+  for (let ws of state.clients.keys()) ws.send(text)
+}
+
+// Pause or resume reload-on-save (srt mcp's pause_watch/resume_watch, the
+// repl's `watch`): paused, an agent's saves are not pushed while it edits;
+// its explicit /reload is. Changes made while paused are not replayed on
+// resume.
+export function setWatchActive(on: boolean) {
+  if (on === state.watchPaused) {
+    console.log(on ? "[cli] Reload on save resumed" : "[cli] Reload on save paused")
+  }
+  state.watchPaused = !on
+}
+
+// Toggle the stats overlay on one client, or on every client (the repl's
+// `stats`) - then it is also the server's setting, which the welcome message
+// carries to clients joining later. Each client's entry remembers its own
+// state, so /clients reports what is actually drawn where.
+export function setStats(on: boolean, ws?: ServerWebSocket) {
+  let text = JSON.stringify({ type: "stats", stats: on })
+  let targets = ws ? [ws] : [...state.clients.keys()]
+  if (!ws) state.stats = on
+  for (let target of targets) {
+    let info = state.clients.get(target)
+    if (info) info.stats = on
+    target.send(text)
+  }
+  return targets.length
 }
 
 export async function handleControl(req: Request, path: string, query: Map<string, string>): Promise<Response> {
   switch (path) {
     case "/__control__/clients":
-      // `entry`/`projectDir` identify which app this server is serving: the
-      // fixed dev port means an agent can reach a different project's server
-      // than it thinks, and a repl/MCP `load` moves the entry mid-session.
-      return Response.json({
+      // `key`/`mode`/`entry` identify what this server serves, for a caller
+      // that resolved it from the registry and wants to confirm the match.
+      let body: ClientsResponse = {
         generation: state.generation,
-        entry: state.config.entry ?? null,
-        projectDir: state.projectDir,
+        key: state.config.key,
+        mode: state.config.mode,
+        entry: state.config.entry,
+        projectDir: state.config.projectDir,
+        userInputMuted: state.userInputMuted,
+        watchPaused: state.watchPaused,
         clients: clientList(),
-      })
+      }
+      return Response.json(body)
     case "/__control__/logs":
       return handleLogs(query)
     case "/__control__/tree": {
@@ -226,6 +371,24 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       return handleQuery(query, "tree", extra)
     }
     case "/__control__/stats": {
+      // GET reads one client's statistics; POST switches the overlay, on one
+      // client with ?client=<id> or on all of them without.
+      if (req.method === "POST") {
+        let active = query.get("active")
+        if (active !== "true" && active !== "false") {
+          return Response.json({ error: "Stats requires ?active=true or ?active=false" }, { status: 400 })
+        }
+        let on = active === "true"
+        let target = query.get("client")
+        let ws: ServerWebSocket | undefined
+        if (target !== undefined) {
+          let found = findClient(target)
+          if ("error" in found) return found.error
+          ws = found.ws
+        }
+        let body: StatsResponse = { ok: true, active: on, clients: setStats(on, ws) }
+        return Response.json(body)
+      }
       let extra: Record<string, unknown> = {}
       let windowMs = parseInt(query.get("window") ?? "", 10)
       if (Number.isFinite(windowMs)) extra.windowMs = windowMs
@@ -241,10 +404,16 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       let scale = parseScale(query)
       if (scale instanceof Response) return scale
       if (scale) extra.scale = scale
+      let format = parseFormat(query)
+      if (format instanceof Response) return format
+      if (format) extra.format = format
       return handleQuery(query, "snapshot", extra)
     }
-    case "/__control__/gpu":
-      return handleQuery(query, "gpu")
+    case "/__control__/gpu": {
+      // ?label=<text> keeps only resources created with exactly that label.
+      let label = query.get("label")
+      return handleQuery(query, "gpu", label === undefined ? undefined : { label })
+    }
     case "/__control__/debug": {
       // GET lists the app's registered debug commands; POST calls one, with
       // an optional JSON body as its args.
@@ -267,6 +436,9 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       let scale = parseScale(query)
       if (scale instanceof Response) return scale
       if (scale) extra.scale = scale
+      let format = parseFormat(query)
+      if (format instanceof Response) return format
+      if (format) extra.format = format
       return handleQuery(query, "texture", extra)
     }
     case "/__control__/clock": {
@@ -291,7 +463,15 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       }
       if (!("scale" in extra) && !("step" in extra))
         return Response.json({ error: "Clock requires ?scale=<x> or ?step=<n>" }, { status: 400 })
-      return handleQuery(query, "clock", extra)
+      // The reply is the clock as the client now has it; its scale is kept
+      // on the client's entry so /clients reports it (a push resets it).
+      let target = findClient(query.get("client"))
+      if ("error" in target) return target.error
+      let result = await queryClient(target.ws, "clock", extra)
+      if ("error" in result) return result.error
+      let info = state.clients.get(target.ws)
+      if (info && typeof result.data?.scale === "number") info.timeScale = result.data.scale
+      return Response.json(result.data)
     }
     case "/__control__/input": {
       // Synthetic input injection: POST {events: [...]} forwards a timed
@@ -339,69 +519,47 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       return handleQuery(query, "buffer", extra)
     }
     case "/__control__/reload": {
-      // Explicit rebuild-and-push, the primary way a coding agent applies its
-      // edits (srt mcp's reload tool). Unlike the repl's file watcher this is
-      // on demand, so a burst of edits collapses into one reload.
+      // Explicit rebuild-and-push, the way a coding agent applies its edits
+      // (srt mcp's reload tool): a burst of edits collapses into one reload,
+      // with reload-on-save paused meanwhile (/watch).
       if (req.method !== "POST") return Response.json({ error: "Reload requires POST" }, { status: 405 })
       let error = await rebuildAndBroadcast()
       if (error) return Response.json({ error }, { status: 502 })
-      state.watch = true
-      return Response.json({ ok: true, clients: state.clients.size })
+      let body: ReloadResponse = { ok: true, clients: state.clients.size }
+      return Response.json(body)
     }
     case "/__control__/load": {
-      // Load (or switch) the app entry and push it: srt mcp's load tool.
-      // Moves the rebuild entry and the file-serving root like the repl's
-      // `load` command, then reuses the reload path, so a later /reload
-      // rebuilds the newly loaded file. The srt process is not told: a
-      // watcher started on the launch-time source keeps watching that file.
       if (req.method !== "POST") return Response.json({ error: "Load requires POST" }, { status: 405 })
-      let entry = (await req.json().catch(() => null))?.entry
-      if (typeof entry !== "string" || !entry) {
-        return Response.json({ error: "Load requires { entry: <absolute source path> }" }, { status: 400 })
-      }
-      if (!(await file(entry).exists())) {
-        return Response.json({ error: `Entry not found: ${entry}` }, { status: 400 })
-      }
-      // An entry outside the project root cannot resolve the project's
-      // dependencies, so the bundler would fail with misleading "bun install"
-      // advice; name the real constraint instead.
-      // Windows paths are case-insensitive and the same drive shows up as both
-      // `c:` and `C:` (an editor-spawned bridge keeps its parent's spelling), so a
-      // drive-letter path folds case; a POSIX path stays exact.
-      let norm = (p: string) => {
-        let s = p.replace(/\\/g, "/")
-        return /^[a-zA-Z]:\//.test(s) ? s.toLowerCase() : s
+      let requested = (await req.json().catch(() => null))?.entry
+      if (typeof requested !== "string" || !requested) {
+        return Response.json({ error: "Load requires { entry: <source path> }" }, { status: 400 })
       }
-      let root = norm(state.projectDir).replace(/\/+$/, "") + "/"
-      if (!norm(entry).startsWith(root)) {
-        return Response.json(
-          {
-            error: `Entry is outside the project root: ${entry} is not under ${state.projectDir}. The dev server can only bundle sources inside the project it was started in - move the file into the project or start srt there.`,
-          },
-          { status: 400 },
-        )
+      let result = await loadEntry(requested)
+      if ("error" in result) return Response.json({ error: result.error }, { status: result.status })
+      let body: LoadResponse = { ok: true, entry: result.entry, clients: state.clients.size }
+      return Response.json(body)
+    }
+    case "/__control__/mute": {
+      if (req.method !== "POST") return Response.json({ error: "Mute requires POST" }, { status: 405 })
+      let active = query.get("active")
+      if (active !== "true" && active !== "false") {
+        return Response.json({ error: "Mute requires ?active=true or ?active=false" }, { status: 400 })
       }
-      state.config.entry = entry
-      let cut = Math.max(entry.lastIndexOf("/"), entry.lastIndexOf("\\"))
-      if (cut > 0) state.sourceDir = entry.slice(0, cut)
-      let error = await rebuildAndBroadcast()
-      if (error) return Response.json({ error }, { status: 502 })
-      state.watch = true
-      return Response.json({ ok: true, entry, clients: state.clients.size })
+      let on = active === "true"
+      setUserInputMuted(on)
+      let body: MuteResponse = { ok: true, active: on, clients: state.clients.size }
+      return Response.json(body)
     }
     case "/__control__/watch": {
-      // Pause/resume srt's auto-reload-on-save: the MCP watch tool. Latched
-      // here because the watcher lives in the srt process; it reads the flag
-      // via /__internal__/watch before acting on a change event. An agent
-      // pauses while creating or editing files so half-finished work is not
-      // pushed; a successful /reload or /load turns it back on.
       if (req.method !== "POST") return Response.json({ error: "Watch requires POST" }, { status: 405 })
-      let enabled = (await req.json().catch(() => null))?.enabled
-      if (typeof enabled !== "boolean") {
-        return Response.json({ error: "Watch requires { enabled: <boolean> }" }, { status: 400 })
+      let active = query.get("active")
+      if (active !== "true" && active !== "false") {
+        return Response.json({ error: "Watch requires ?active=true or ?active=false" }, { status: 400 })
       }
-      state.watch = enabled
-      return Response.json({ ok: true, enabled })
+      let on = active === "true"
+      setWatchActive(on)
+      let body: WatchResponse = { ok: true, active: on }
+      return Response.json(body)
     }
     default:
       return Response.json({ error: "Unknown control endpoint" }, { status: 404 })

package/src/server/docs.md

@@ -0,0 +1,51 @@
+# srt run and srt server
+
+`run` is the everyday command: it starts the dev server and a local client
+window together, and it is what `bun run dev` calls in a scaffolded project.
+
+{{ usage run }}
+
+Run from the project root to serve the project (the entry is
+`solidrt.entry` in package.json, default `src/index.tsx`); `srt run <file>`
+serves a single file outside a project. In a project root a file argument
+is ambiguous, so it takes `--project` (the project, with this entry) or
+`--file` (the file alone). Nothing searches upward for a package.json.
+
+The server pushes the bundle to every connected client, so one server can
+drive a desktop window and a phone at the same time. A save reaches them on
+its own: the server watches every file the running bundle was built from
+(the app's modules, the dependencies it bundles in, inlined files,
+package.json and tsconfig.json) plus the `assets/` tree, so a file the app
+does not import never triggers a rebuild, while an edit to a workspace
+package it does import does. A coding agent pauses this while it edits
+(`pause_watch`) and pushes with the MCP `reload` tool instead.
+
+`server` is the same without the local client, for clients on other devices
+(see [srt client](../client/docs.md)):
+
+{{ usage server }}
+
+One server per project or file. It keeps the port it had last time, else
+takes the first free one from 34884 up, and prints it, so projects run side
+by side without any numbering; `--port N` pins it. Loopback only unless
+`--lan`, which is what phones and other devices need; `--tunnel` accepts
+clients over a peer-to-peer connection instead, with no network setup.
+`--proxy-http` routes the app's `fetch` calls through the dev server, cached
+in `.srt-data/http-cache.db` in the project root (delete the file to
+clear), for clients on other devices that need your machine's data.
+`-- <args>` hands the app its own arguments (`flux:process` argv) on every
+client.
+
+Dev state lives in `~/.solidrt/`: `servers/<key hash>/` holds each server's
+registry record, remembered port and tunnel key; `clients/client<N>/` the
+data tree of a locally spawned client (`-c <N>` picks it, default 0;
+storage is per app inside a tree, so two projects share client 0).
+
+With a terminal on stdin, `run` and `server` take commands at the `srt>`
+prompt: `reload` and `stop` (every client, or the ids `list` prints),
+`load <file>` (switch the entry, same rules as the MCP `load` tool),
+`stats`, `watch on|off` (reload on save), `mute on|off` (the user's own
+input on the clients), `quit`. Tab completes commands and `load` paths,
+Up/Down recall earlier lines, Ctrl-C (or Ctrl-D on an empty line) quits.
+Without a terminal (a supervisor, the console, a background `&`) the
+server runs without the prompt and stops on a signal.