@solidrt/cli 0.0.50 → 0.0.52

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

@@ -23,13 +23,13 @@ const KEY_FILE = "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 <keyDir>/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
+ * without re-scanning: the UDP port follows the dev server's remembered port
+ * (ephemeral on a first run), and the secret key is persisted in
+ * <keyDir>/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, keyDir: string): Promise<Endpoint> {
+export async function createTunnelEndpoint(port: number | null, keyDir: string): Promise<Endpoint> {
   let keyPath = join(keyDir, KEY_FILE)
 
   let secretKey: string | undefined
@@ -39,7 +39,7 @@ export async function createTunnelEndpoint(port: number, keyDir: string): Promis
     if (saved.length === 64) secretKey = saved
   }
 
-  let endpoint = await Endpoint.create({ local: true, protocols: [TUNNEL_PROTOCOL], port, secretKey })
+  let endpoint = await Endpoint.create({ local: true, protocols: [TUNNEL_PROTOCOL], ...(port !== null ? { port } : {}), secretKey })
 
   // First run (no saved key): persist the freshly generated one so the next run
   // reuses it and the ticket stays the same.

package/src/server/watcher.ts

@@ -0,0 +1,121 @@
+import { dir } from "flux:fs"
+import { state } from "./state"
+import { dirname } from "./mode"
+import { rebuildAndBroadcast, showBuildFailure } from "./rebuild"
+
+// Reload-on-save. Not a directory watch: the watch set is the bundle's own
+// input list (BundleOutput.inputs: the app's modules, the dependency modules
+// bundled in, inlined files, package.json, tsconfig.json), so a source file
+// the running app does not import, or a dependency it does not use, never
+// triggers anything, while an edit to a workspace package it does import
+// does. Each input's parent directory is watched (never the file itself: an
+// editor's atomic save replaces the inode, which a file watch would lose)
+// and events are matched by name within that directory. On top of that, in
+// project mode, the whole assets/ tree: the manifest lists the tree, so any
+// change to it is a new version. While the last build failed the input list
+// is gone, so the source directory is watched as a whole until a build
+// succeeds again (the missing-import case: the file the build waits for is
+// not in any list yet). Every hit debounces into the one
+// rebuildAndBroadcast() path, which re-arms the watch from the new inputs.
+// Paused by the MCP pause_watch tool while an agent edits (state.watchPaused):
+// changes made meanwhile are not pushed; the agent's reload is.
+
+const DEBOUNCE_MS = 100
+const SOURCE_EXT = /\.(tsx?|jsx?)$/
+
+let offs: (() => void)[] = []
+let timer: ReturnType<typeof setTimeout> | null = null
+let changed = new Set<string>()
+let building = false
+let dirty = false
+
+function basename(path: string): string {
+  return path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1)
+}
+
+// A path with a dot component (below `root` when given) is never a source:
+// .srt-data in particular is this server's own output, and rebuilding on it
+// would rebuild forever. node_modules is the same in file mode, where the
+// source directory may be a project root.
+function isToolingPath(path: string, root: string): boolean {
+  let rel = path.startsWith(root) ? path.slice(root.length) : path
+  return rel.split(/[\\/]/).some((part) => part.startsWith(".") || part === "node_modules")
+}
+
+/** Arm the watch from a build's inputs; null (a failed build) watches the source tree as a whole. */
+export function armWatcher(inputs: string[] | null) {
+  stopWatcher()
+  let config = state.config
+  let hit = (path: string) => onChange(path)
+  try {
+    if (inputs) {
+      let byDir = new Map<string, Set<string>>()
+      for (let input of inputs) {
+        let parent = dirname(input)
+        let names = byDir.get(parent)
+        if (!names) byDir.set(parent, (names = new Set()))
+        names.add(basename(input))
+      }
+      for (let [parent, names] of byDir) {
+        offs.push(dir(parent).watch((e) => names.has(basename(e.path)) && hit(e.path)))
+      }
+    } else {
+      let root = config.sourceDir
+      offs.push(
+        dir(root).watch((e) => SOURCE_EXT.test(e.path) && !isToolingPath(e.path, root) && hit(e.path), { recursive: true }),
+      )
+    }
+    if (config.projectDir) {
+      let assets = `${config.projectDir}/assets`
+      dir(assets)
+        .exists()
+        .then((exists) => {
+          if (exists && offs.length) offs.push(dir(assets).watch((e) => !isToolingPath(e.path, assets) && hit(e.path), { recursive: true }))
+        })
+    }
+  } catch (e) {
+    console.error(`[cli] Watch failed: ${e instanceof Error ? e.message : e}`)
+    stopWatcher()
+  }
+}
+
+/** Drop every watch; the engine loop can go idle. */
+export function stopWatcher() {
+  for (let off of offs) off()
+  offs = []
+  if (timer !== null) clearTimeout(timer)
+  timer = null
+  changed.clear()
+}
+
+function onChange(path: string) {
+  if (state.watchPaused) return
+  changed.add(path)
+  if (building) {
+    dirty = true
+    return
+  }
+  if (timer !== null) clearTimeout(timer)
+  timer = setTimeout(() => void rebuild(), DEBOUNCE_MS)
+}
+
+// One rebuild per burst; a change that lands while the bundle runs queues
+// exactly one more, since the running build cannot have seen it.
+async function rebuild() {
+  timer = null
+  building = true
+  let root = state.config.projectDir ?? state.config.sourceDir
+  let names = [...changed].map((p) => (p.startsWith(root) ? p.slice(root.length + 1) : p))
+  changed.clear()
+  console.log(`[cli] Change detected: ${names.slice(0, 3).join(", ")}${names.length > 3 ? ` (+${names.length - 3})` : ""}`)
+  let error = await rebuildAndBroadcast()
+  if (error) {
+    console.error(error)
+    showBuildFailure()
+  }
+  building = false
+  if (dirty) {
+    dirty = false
+    onChange(names[0] ?? root)
+  }
+}

package/src/tool/main.ts

@@ -0,0 +1,70 @@
+import { readdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { source, toolArgs } from "../lib/args"
+
+// srt tool: the tools the installed @solidrt packages ship - build-time
+// helpers that belong to an extension, not to core (a model converter in
+// @solidrt/3d, say). Discovery is by convention, like demos: every
+// `<package>/tools/<name>.ts` is a tool named `<package>/<name>`, run with
+// bun in the caller's cwd with the arguments after the tool name passed
+// through untouched. srt knows nothing about what a tool does; a tool
+// prints its own usage.
+
+type Tool = { name: string; script: string }
+
+const SCOPE = join("node_modules", "@solidrt")
+
+/** Every tool installed here, sorted so the listing is stable. The cwd and
+ * nothing above it - the same rule demos follow, so this lists what THIS
+ * project installed. */
+function discover(): Tool[] {
+  let tools: Tool[] = []
+  for (let pkg of names(SCOPE)) {
+    let dir = join(SCOPE, pkg, "tools")
+    for (let file of names(dir)) {
+      if (!file.endsWith(".ts")) continue
+      tools.push({ name: `${pkg}/${file.slice(0, -".ts".length)}`, script: resolve(dir, file) })
+    }
+  }
+  return tools
+}
+
+// A missing folder is the normal case (most packages ship no tools), so it
+// reads as an empty one rather than an error.
+function names(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort()
+  } catch {
+    return []
+  }
+}
+
+function list(tools: Tool[]) {
+  for (let tool of tools) console.log(`  ${tool.name}`)
+}
+
+export async function main(): Promise<void> {
+  let tools = discover()
+  if (tools.length === 0) {
+    console.error(`No tools installed in ${process.cwd()} (looked in ${SCOPE}/*/tools/)`)
+    process.exit(1)
+  }
+
+  if (source === undefined) {
+    list(tools)
+    console.log("\nRun one with: srt tool <pkg>/<name> [arguments]")
+    return
+  }
+
+  let picked = tools.find((t) => t.name === source)
+  if (!picked) {
+    console.error(`No such tool: ${source}`)
+    list(tools)
+    process.exit(1)
+  }
+
+  let proc = Bun.spawn([process.execPath, picked.script, ...toolArgs], {
+    stdio: ["inherit", "inherit", "inherit"],
+  })
+  process.exit(await proc.exited)
+}

package/src/types/bundle.d.ts

@@ -0,0 +1,24 @@
+// What `srt bundle --json` (src/bundle/main.ts, a bun subprocess of the
+// dev server) writes to stdout as one JSON object and the dev server
+// (src/server/rebuild.ts) reads back. src/types/ holds the type-only contracts
+// between the two programs: each has its own tsconfig (bun types on one
+// side, flux types on the other), both include this folder, so nothing here
+// may reference either runtime.
+
+export type BundleOutput = {
+  code: string
+  /** Composed sourcemap JSON (bundle -> original .tsx sources), dev builds only. */
+  map: string | null
+  /** Version manifest JSON for this bundle; clients install pushes under its hash. */
+  manifest: string
+  /** The app's isolate bundles, one per "use isolate" module, in id order; maps dev builds only. */
+  isolates: { id: string; code: string; map: string | null }[]
+  /**
+   * Every file this bundle was built from, absolute and sorted: the app's
+   * modules, the dependency modules bundled in, files inlined by import
+   * attribute, and the project's package.json / tsconfig.json. The assets/
+   * tree is not listed (the manifest carries it). What the dev server
+   * watches for reload-on-save.
+   */
+  inputs: string[]
+}

package/src/types/control.d.ts

@@ -0,0 +1,90 @@
+// The control API (/__control__/, server/control.ts) response shapes the
+// MCP bridge (src/mcp/main.ts) reads fields from. Only the server-held
+// answers are shaped here; queries forwarded to a client return whatever the
+// client runtime answers. See bundle.d.ts for the folder.
+
+export type ClientEntry = {
+  id: number
+  platform: string
+  /** The client runtime's version (git describe). */
+  version: string
+  /** Build profile: debug or release. */
+  profile: string
+  capabilities: string[]
+  /** Query kinds this client's runtime answers (empty on runtimes that predate
+   * the advertisement); dev tools plan their verification surface from it. */
+  queries: string[]
+  /** The client's storage tree on its own machine (`<data-root>/client<N>`
+   * for a dev client, the install folder for the launcher or a packed app),
+   * or null when it runs without writable storage or predates the field. */
+  clientDir: string | null
+  /** Whether its stats overlay is drawn (see POST /stats). */
+  stats: boolean
+  /** Its time scale as the client last reported it to POST /clock: 0 paused,
+   * 1 real time. Back to 1 on every push (a reload restarts the clock). */
+  timeScale: number
+  /** The client's process id on its own machine. */
+  pid: number | null
+  /** The runtime binary it runs. */
+  execPath: string | null
+  /** Its machine's hostname. */
+  host: string | null
+  /** The OS as a person names it ("Linux (Ubuntu 24.04)", "Android 15 on Pixel 9 Pro"). */
+  os: string | null
+  /** The kernel version. */
+  kernel: string | null
+  /** The SDL video driver ("wayland", "x11", "android", "offscreen", ...). */
+  videoDriver: string | null
+  /** The GPU strings as GL reports them; null on a client that connected
+   * before its GL context existed (a reconnect fills it in). */
+  gpu: GpuInfo | null
+}
+
+export type GpuInfo = { vendor: string; renderer: string; version: string }
+
+/** GET /clients */
+export type ClientsResponse = {
+  /** Identity of this server run: client ids and log cursors are only valid within one. */
+  generation: number
+  key: string
+  mode: "project" | "file"
+  entry: string
+  projectDir: string | null
+  /** Whether the user's own input is muted on every client (see /mute). */
+  userInputMuted: boolean
+  /** Whether reload-on-save is paused (see /watch). */
+  watchPaused: boolean
+  clients: ClientEntry[]
+}
+
+export type LogEntry = { seq: number; at: number; client: number; level: string; text: string }
+
+/** GET /logs */
+export type LogsResponse = {
+  /** Consecutive identical entries come back as one, with `repeats`. */
+  entries: (LogEntry & { repeats?: number })[]
+  /** The next `since` cursor. */
+  latest: number
+  generation: number
+}
+
+/** POST /reload */
+export type ReloadResponse = { ok: true; clients: number }
+
+/** POST /load: the canonical entry now served. */
+export type LoadResponse = { ok: true; entry: string; clients: number }
+
+/** POST /mute: the mute state now in force and the clients told. */
+export type MuteResponse = { ok: true; active: boolean; clients: number }
+
+/** POST /stats: whether the overlay is now on, and on how many clients. */
+export type StatsResponse = { ok: true; active: boolean; clients: number }
+
+/** POST /watch: whether reload-on-save is now active. */
+export type WatchResponse = { ok: true; active: boolean }
+
+/** GET /snapshot and /texture: png by default, RGBA8 bytes with format=raw. */
+export type ImageResponse = { width: number; height: number; pngBase64?: string; rgbaBase64?: string }
+
+/** Every non-2xx answer. */
+export type ControlError = { error: string }

package/src/types/registry.d.ts

@@ -0,0 +1,16 @@
+// The dev server registry record: ~/.solidrt/servers/<key hash>/live.json,
+// written by the server (server/registry.ts) and read by srt client, srt mcp
+// and the launcher (src/lib/registry.ts). See bundle.d.ts for the folder.
+
+export type LiveRecord = {
+  pid: number
+  port: number
+  address: string
+  /** The canonical project root or file path (see src/lib/mode.ts). */
+  key: string
+  mode: "project" | "file"
+  entry: string
+  projectDir: string | null
+  /** ISO timestamp of the bind. */
+  started: string
+}