@solidrt/cli 0.0.9 → 0.0.11

package/AGENTS.md

@@ -0,0 +1,46 @@
+# @solidrt/cli - agent notes
+
+Dense, self-contained facts for running and verifying a SolidRT app. Full docs
+live in docs/ (and the website). For the authoring model (elements, props,
+reactivity), see @solidrt/core (its AGENTS.md).
+
+`srt` is the dev tool. Bun is a dev prerequisite only; SolidRT apps run on the
+bundled `flux` runtime, not on Bun. Invoke via `bunx srt <command>`.
+
+## Commands
+
+- `bunx srt run src/index.tsx` - dev server + a local client window, watches and
+  hot-reloads. NEEDS A DISPLAY (opens a GUI window). Not usable headless.
+- `bunx srt bundle src/index.tsx` - transpile to `<file>.srt.js`. With
+  `--compile`, emits `.srt.bin` bytecode. `--minify`, `--dev`, `--stdout`,
+  `--output` also available.
+- `bunx srt record src/index.tsx [flags]` - render OFFSCREEN to PNG frames.
+- `bunx srt server [file]` / `bunx srt client` - the two halves of `run`
+  separately (server distributes code; clients on other devices connect to it).
+
+## Verifying without a display (headless / CI / agent box)
+
+Two reliable checks that need no GUI:
+
+1. `bunx srt bundle src/index.tsx` - exit 0 means the app compiles. Fast.
+2. `bunx srt record src/index.tsx --size 480x640 --duration 1 --fps 2` -
+   renders offscreen via EGL/wgpu and writes `frame-NNNNNN.png`. This actually
+   proves the app renders. Combine with `--fps`/`--duration` (defaults
+   1280x720, 60fps, 1s).
+
+`record` gotchas:
+- Frames are written to the RUNTIME's working dir (`~/.local/share/SolidRT/go/`),
+  NOT the directory you ran the command from. Look there for the PNGs.
+- The recording includes a debug overlay (FPS/REQ/MiB/CPU) in a corner.
+- Run from the project directory. There is no `bunx --cwd` flag.
+
+## Dev server proxies (when clients on other devices need your machine's data)
+
+- `--proxy-http` - route `fetch` through the dev server; responses cached in
+  `.srt-cache.db` (delete the file to clear).
+- `--proxy-files` - route flux:fs (`file`/`dir`/`write`) through the dev server.
+  Exposes your dev machine's files to all clients; use with care.
+
+## REPL (opened by `run`/`server`)
+
+`load <file>`, `reload [n]`, `stop [n]`, `list`, `!<cmd>`, `quit`/`exit`.

package/README.md

@@ -2,6 +2,8 @@
 
 Developer tooling for SolidRT. Provides a development environment for `@solidrt/core` applications.
 
+> LLM agents: see [AGENTS.md](./AGENTS.md) for a dense, self-contained quickstart.
+
 ## Commands
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -10,21 +10,22 @@
   "files": [
     "bin/",
     "src/",
-    "LICENSE"
+    "AGENTS.md"
   ],
   "dependencies": {
     "@babel/core": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
     "babel-preset-solid": "2.0.0-beta.14",
+    "bonjour-service": "^1.4.0",
     "qrcode-generator": "^2.0.4"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.9",
-    "@solidrt/linux-x64-gnu": "0.0.9",
-    "@solidrt/win32-x64-msvc": "0.0.9"
+    "@solidrt/darwin-arm64": "0.0.11",
+    "@solidrt/linux-x64-gnu": "0.0.11",
+    "@solidrt/win32-x64-msvc": "0.0.11"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.9",
+    "@solidrt/core": "0.0.11",
     "typescript": "^5"
   },
   "devDependencies": {

package/src/args.ts

@@ -5,7 +5,7 @@ export let { values, positionals } = parseArgs({
     dev: { type: "boolean", short: "d", default: false },
     minify: { type: "boolean", short: "m", default: false },
     compile: { type: "boolean", short: "c", default: false },
-    flux: { type: "boolean", default: false },
+    flux: { type: "boolean", short: "f", default: false },
     stdout: { type: "boolean", default: false },
     output: { type: "string", short: "o" },
     "proxy-files": { type: "boolean", default: false },
@@ -13,6 +13,7 @@ export let { values, positionals } = parseArgs({
     fps: { type: "string" },
     duration: { type: "string" },
     size: { type: "string" },
+    stats: { type: "boolean", default: false },
     android: { type: "boolean", default: false },
     device: { type: "string" },
   },
@@ -35,8 +36,11 @@ function usage(line: string): never {
 export function validateArgs() {
   switch (command) {
     case "bundle":
-      if (!source || (!isSource && !isPrebuilt))
+      if (values.flux) {
+        if (!source || !isTs) usage("srt bundle --flux [options] <entry.[ts|js]>")
+      } else if (!source || (!isSource && !isPrebuilt)) {
         usage("srt bundle [options] <entry.[tsx|jsx|ts|js|srt.js|srt.bin]>")
+      }
       break
     case "record":
       if (!source || !isTsx) usage("srt record <entry.[tsx|jsx]>")
@@ -74,12 +78,14 @@ run/server options:
 
 run/client options:
       --size <WxH>       Window size (default: 1280x720)
+      --stats            Show the debug stats overlay (FPS, memory, frame timings)
 
 client options:
       --android          Install and launch the client on a connected Android device
-      --device <serial>  Target a specific adb device (when several are connected)
+      --device <serial>  Target a specific adb device by serial or unique prefix
 
 bundle options:
+  -f, --flux             Bundle for the bare Flux runtime, without SolidJS (entry must be .ts|.js)
   -d, --dev              Use development build of SolidJS (default: production)
   -m, --minify           Minify the output
   -c, --compile          Compile to bytecode
@@ -87,7 +93,7 @@ bundle options:
       --stdout           Write bundle to stdout
 
 pack options:
-      --flux             Pack for the bare Flux runtime instead of SolidRT (entry must be .ts|.js)
+  -f, --flux             Pack for the bare Flux runtime instead of SolidRT (entry must be .ts|.js)
   -m, --minify           Minify the output
   -o, --output <name>    Output filename
 

package/src/bundler.ts

@@ -41,7 +41,7 @@ export async function bundle(entry = source) {
       target: "browser",
       format: "esm",
       minify: values.minify,
-      external: ["flux:*"],
+      external: ["flux:*", "srt:*"],
       define,
       plugins: [solidPlugin()],
     })

package/src/cache.ts

@@ -46,6 +46,22 @@ export function isEnabled(): boolean {
   return enabled
 }
 
+// Strings returned by bun:sqlite carry an internal representation that
+// Headers.set() rejects, even when value-identical to an acceptable string
+// (Bun bug oven-sh/bun#28266, present through 1.3.14). Rebuilding each char
+// yields a clean string.
+function reflatten(s: string): string {
+  return Array.from(s, (c) => String.fromCharCode(c.charCodeAt(0))).join("")
+}
+
+function reflattenHeaders(obj: Record<string, string>): Record<string, string> {
+  let out: Record<string, string> = {}
+  for (let key in obj) {
+    out[reflatten(key)] = reflatten(obj[key]!)
+  }
+  return out
+}
+
 function keyFor(method: string, url: string): string {
   let h = createHash("sha256")
   h.update(method)
@@ -101,7 +117,7 @@ export function get(method: string, url: string): Entry | null {
     method: row.method,
     url: row.url,
     status: row.status,
-    headers: JSON.parse(row.headers),
+    headers: reflattenHeaders(JSON.parse(row.headers)),
     body: row.body,
     cachedAt: row.cached_at,
   }

package/src/commands/bundle.ts

@@ -1,7 +1,16 @@
 import { values, source, isPrebuilt } from "../args"
-import { bundle, bundleTo, compileToBytecode } from "../bundler"
+import { bundle, bundleTo, bundleFlux, compileToBytecode } from "../bundler"
 import { resolve } from "path"
 
+// Write to stdout and resolve only once the whole payload is flushed.
+// process.stdout.write to a pipe is async and applies backpressure; the
+// callback fires after every byte is drained, so it is safe to exit after.
+function writeStdout(data: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(data, (err) => (err ? reject(err) : resolve()))
+  })
+}
+
 // Compile JS to a .srt.bin file and report its size.
 async function writeBytecode(jsCode: string, outfile: string) {
   let bytecode = await compileToBytecode(jsCode)
@@ -11,6 +20,22 @@ async function writeBytecode(jsCode: string, outfile: string) {
 }
 
 export async function runBundleCommand() {
+  if (values.flux) {
+    let baseName = values.output ?? source!.replace(/\.[jt]s$/, "")
+    let jsCode = await bundleFlux(source!)
+
+    if (values.stdout) {
+      await writeStdout(jsCode)
+    } else if (values.compile) {
+      await writeBytecode(jsCode, baseName + ".flux.bin")
+    } else {
+      let outfile = baseName + ".flux.js"
+      await Bun.write(outfile, jsCode)
+      console.log(`>> wrote ${jsCode.length} bytes to ${outfile}`)
+    }
+    process.exit()
+  }
+
   if (isPrebuilt) {
     if (!source!.endsWith(".srt.js")) {
       console.error("Can only compile .srt.js files. .srt.bin is already compiled.")
@@ -31,7 +56,7 @@ export async function runBundleCommand() {
       process.exit(1)
     }
     for (let output of result.outputs) {
-      process.stdout.write(await output.text())
+      await writeStdout(await output.text())
     }
     process.exit()
   }

package/src/dev-android.ts

@@ -1,20 +1,79 @@
 import { print, requireAdb } from "./util"
 import { resolveApk } from "./artifacts"
 import { values } from "./args"
+import { DEV_PORT } from "./dev-server"
 
-// Launch component of the "go" dev-client flavor (see lattice/Makefile.x-android).
+// Launch component of the "go" dev-client flavor (see lattice/Makefile.android).
 let PACKAGE_ACTIVITY = "com.solidrt.go/com.solidrt.app.MainActivity"
 
-// Prefix adb args with `-s <serial>` only when the user pinned a device; with a
-// single connected device adb selects it on its own.
-function adbArgs(extra: string[]) {
-  return values.device ? ["-s", values.device, ...extra] : extra
+// Forward the device's loopback DEV_PORT to the host dev server, so the client
+// reaches it at 127.0.0.1:DEV_PORT (see lattice/src/go/connection.rs). This is
+// the adb-reverse path: it works for the emulator (behind NAT, cannot reach the
+// host via LAN mDNS discovery) and for USB-tethered devices alike, and is
+// harmless on any adb connection. (Android only uses this path; the client's
+// mDNS discovery is desktop-only -- see lattice/src/go/connection.rs.)
+function setupAdbReverse(adb: string, target: string) {
+  print(`[cli] Forwarding 127.0.0.1:${DEV_PORT} on ${target} to host dev server`)
+  let res = Bun.spawnSync([adb, "-s", target, "reverse", `tcp:${DEV_PORT}`, `tcp:${DEV_PORT}`], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  if (res.exitCode !== 0) {
+    print(`[cli] adb reverse failed (client will fall back to discovery):\n${res.stderr.toString()}`)
+  }
+}
+
+// Serials of connected, authorized devices (excludes offline/unauthorized).
+function listDevices(adb: string): string[] {
+  let listed = Bun.spawnSync([adb, "devices"], { stdout: "pipe", stderr: "pipe" })
+  return listed.stdout
+    .toString()
+    .split("\n")
+    .slice(1)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .filter((l) => l.endsWith("\tdevice"))
+    .map((l) => l.split("\t")[0])
+    .filter((s): s is string => Boolean(s))
+}
+
+// Resolve the target device serial. With --device, treat the value as a serial
+// prefix and require it to match exactly one connected device; without it, use
+// the sole connected device. Exits with a clear message on any ambiguity.
+function resolveTarget(adb: string): string {
+  let devices = listDevices(adb)
+
+  if (values.device) {
+    let prefix = values.device
+    let matches = devices.filter((d) => d.startsWith(prefix))
+    if (matches.length > 1) {
+      console.error(`--device "${prefix}" is ambiguous; matches: ${matches.join(", ")}`)
+      process.exit(1)
+    }
+    let [match] = matches
+    if (!match) {
+      console.error(`No connected device matches --device "${prefix}". Connected: ${devices.join(", ") || "none"}`)
+      process.exit(1)
+    }
+    return match
+  }
+
+  if (devices.length > 1) {
+    console.error(`Multiple devices connected (${devices.join(", ")}); pick one with --device <serial or prefix>.`)
+    process.exit(1)
+  }
+  let [only] = devices
+  if (!only) {
+    console.error("No authorized Android device found. Enable USB debugging and check `adb devices`.")
+    process.exit(1)
+  }
+  return only
 }
 
-// Install + launch the Android client on a connected device over adb, then let
-// the device discover the running dev server over LAN UDP (the same path as a
-// manually launched client). Fire-and-forget: the client's lifecycle is tracked
-// via WS connect/disconnect in dev-server.ts, not as a child process here.
+// Install + launch the Android client on a connected device over adb, forwarding
+// its loopback to the host dev server so the client connects at 127.0.0.1 (see
+// setupAdbReverse). Fire-and-forget: the client's lifecycle is tracked via WS
+// connect/disconnect in dev-server.ts, not as a child process here.
 export async function spawnAndroidClient() {
   let adb = requireAdb()
 
@@ -25,38 +84,18 @@ export async function spawnAndroidClient() {
     process.exit(1)
   }
 
-  // Resolve the target device: 0 -> error, 1 -> use it, many -> require --device.
-  let target = values.device
-  if (!target) {
-    let listed = Bun.spawnSync([adb, "devices"], { stdout: "pipe", stderr: "pipe" })
-    let devices = listed.stdout
-      .toString()
-      .split("\n")
-      .slice(1)
-      .map((l) => l.trim())
-      .filter(Boolean)
-      .filter((l) => l.endsWith("\tdevice"))
-      .map((l) => l.split("\t")[0])
-
-    if (devices.length === 0) {
-      console.error("No authorized Android device found. Enable USB debugging and check `adb devices`.")
-      process.exit(1)
-    }
-    if (devices.length > 1) {
-      console.error(`Multiple devices connected (${devices.join(", ")}); pick one with --device <serial>.`)
-      process.exit(1)
-    }
-    target = devices[0]
-  }
+  let target = resolveTarget(adb)
 
   print(`[cli] Installing SolidRT-Go on ${target}`)
-  let install = Bun.spawn([adb, ...adbArgs(["install", "-r", apk])], { stdout: "pipe", stderr: "pipe" })
+  let install = Bun.spawn([adb, "-s", target, "install", "-r", apk], { stdout: "pipe", stderr: "pipe" })
   if ((await install.exited) !== 0) {
     console.error("adb install failed:\n" + (await new Response(install.stderr).text()))
     process.exit(1)
   }
 
-  let start = Bun.spawn([adb, ...adbArgs(["shell", "am", "start", "-n", PACKAGE_ACTIVITY])], {
+  setupAdbReverse(adb, target)
+
+  let start = Bun.spawn([adb, "-s", target, "shell", "am", "start", "-n", PACKAGE_ACTIVITY], {
     stdout: "pipe",
     stderr: "pipe",
   })
@@ -65,5 +104,5 @@ export async function spawnAndroidClient() {
     process.exit(1)
   }
 
-  print(`[cli] Launched SolidRT-Go on ${target}; waiting for it to discover the dev server...`)
+  print(`[cli] Launched SolidRT-Go on ${target}; waiting for it to connect to the dev server...`)
 }

package/src/dev-server.ts

@@ -1,7 +1,7 @@
 import { resolve } from "path"
 import { stat as fsStat, readdir } from "node:fs/promises"
 import { networkInterfaces } from "node:os"
-import { createSocket } from "node:dgram"
+import { Bonjour } from "bonjour-service"
 import qrcode from "qrcode-generator"
 import { state, print } from "./util"
 import { values } from "./args"
@@ -28,7 +28,6 @@ function headersToObject(h: Headers): Record<string, string> {
   })
   return out
 }
-
 async function handleProxy(req: Request): Promise<Response> {
   let target = req.headers.get("x-srt-proxy-url")
   if (!target) {
@@ -156,6 +155,9 @@ export function startServer() {
       open(ws) {
         state.clients.set(ws, { platform: "unknown", version: "unknown" })
         print(`[cli] Client connected ${ws.remoteAddress}`)
+        // Advertise our real LAN address so clients dialed over the adb loopback
+        // can show/remember the directly reachable address (see connection.rs).
+        ws.send(JSON.stringify({ type: "welcome", address: state.serverUrl, stats: values.stats }))
         if (state.currentCode) {
           ws.send(buildReload({ code: state.currentCode }))
         }
@@ -199,31 +201,43 @@ export function startServer() {
   qr.addData(serverUrl)
   qr.make()
   let modCount = qr.getModuleCount()
-  for (let y = 0; y < modCount; y += 2) {
-    let row = "  "
-    for (let x = 0; x < modCount; x++) {
-      let top = qr.isDark(y, x)
-      let bot = y + 1 < modCount && qr.isDark(y + 1, x)
+  // Render as a white tile with black modules (explicit ANSI colors) plus the
+  // 4-module quiet zone the QR spec requires. Drawing with the terminal's
+  // default foreground inverts the code on dark themes, which standard
+  // decoders reject.
+  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)
+    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)
 
   console.log("")
   console.log(`[cli] WebSocket server on ws://${serverUrl}`)
 
-  // UDP discovery
-  let udp = createSocket("udp4")
-  udp.on("message", (msg, rinfo) => {
-    if (msg.toString() === "SRT_DISCOVER") {
-      print(`[cli] Discovery request from ${rinfo.address}:${rinfo.port}`)
-      udp.send("SRT_SERVER", rinfo.port, rinfo.address)
-    }
-  })
-  udp.bind(DEV_PORT, () => {
-    udp.setBroadcast(true)
-    print("[cli] UDP discovery listener on port " + DEV_PORT)
-  })
+  // LAN discovery: advertise the dev server as a DNS-SD service so go clients on
+  // the same network can find it (see lattice/src/go/connection.rs). Stored on
+  // state so shutdown() can send the mDNS goodbye.
+  state.bonjour = new Bonjour()
+  state.bonjour.publish({ name: "SolidRT Dev Server", type: "solidrt", protocol: "tcp", port: DEV_PORT })
+  print(`[cli] Advertising _solidrt._tcp on port ${DEV_PORT} via mDNS`)
 
   // Keepalive
   setInterval(() => {

package/src/util.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs"
 import { resolve } from "node:path"
 import type { Interface as ReadlineInterface } from "node:readline"
 import type { Server as BunServer } from "bun"
+import type { Bonjour } from "bonjour-service"
 
 export let state = {
   clients: new Map<any, { platform: string; version: string }>(),
@@ -13,11 +14,12 @@ export let state = {
   server: null as BunServer<undefined> | null,
   serverUrl: null as string | null,
   rl: null as ReadlineInterface | null,
+  bonjour: null as Bonjour | null,
 }
 
 // Build target per binary, for the "not found" hint. Run from the repo root.
 let BUILD_HINTS: Record<string, string> = {
-  "solidrt-go": "make solidrt-go",
+  "solidrt-go": "make client",
   solidrt: "make runtime",
   flux: "make -C flux flux",
   fluxc: "make -C flux fluxc",
@@ -82,5 +84,6 @@ export function printErr(...args: any[]) {
 export function shutdown() {
   if (state.child) state.child.kill()
   if (state.server) state.server.stop()
+  if (state.bonjour) state.bonjour.destroy()
   process.exit(0)
 }