@solidrt/cli 0.0.27 → 0.0.29

package/src/commands/check.ts

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { source } from "../args"
+import { bundleWith } from "../bundler"
+
+// srt check: verify the app without side effects. Bundles in memory (nothing
+// written, so no dev-server reload fires and no build outputs land in the
+// project) and typechecks with the project's own tsc, reporting only
+// diagnostics in app code. @solidrt packages ship raw .ts sources, so a strict
+// consumer config surfaces their internal errors too; those are counted and
+// hidden, not the caller's problem to wade through.
+
+// Walk up from the entry to the enclosing project (tsconfig.json or, failing
+// that, package.json).
+function findProjectRoot(entry: string): string | null {
+  let dir = dirname(resolve(entry))
+  let byConfig: string | null = null
+  let byPackage: string | null = null
+  while (true) {
+    if (!byConfig && existsSync(join(dir, "tsconfig.json"))) byConfig = dir
+    if (!byPackage && existsSync(join(dir, "package.json"))) byPackage = dir
+    let parent = dirname(dir)
+    if (parent === dir) return byConfig ?? byPackage
+    dir = parent
+  }
+}
+
+// One tsc --pretty false diagnostic: the "path(line,col): error TS...: ..."
+// head line plus any indented continuation lines.
+type Diagnostic = { head: string; lines: string[]; inDependencies: boolean }
+
+function parseDiagnostics(output: string): Diagnostic[] {
+  let diagnostics: Diagnostic[] = []
+  let current: Diagnostic | null = null
+  for (let line of output.split("\n")) {
+    let head = /^(.*?)\(\d+,\d+\): (error|warning) TS\d+: /.exec(line) ?? /^(error|warning) TS\d+: /.exec(line)
+    if (head) {
+      let file = line.includes("): ") ? head[1]! : ""
+      current = { head: line, lines: [line], inDependencies: file.includes("node_modules") }
+      diagnostics.push(current)
+    } else if (current && line.trim() !== "") {
+      current.lines.push(line)
+    }
+  }
+  return diagnostics
+}
+
+async function typecheck(root: string): Promise<{ app: Diagnostic[]; hidden: number } | null> {
+  let tsc = join(root, "node_modules", ".bin", process.platform === "win32" ? "tsc.exe" : "tsc")
+  if (!existsSync(tsc)) {
+    console.warn("Typecheck skipped: no tsc in the project (add the typescript devDependency)")
+    return null
+  }
+  let proc = Bun.spawn([tsc, "--noEmit", "--pretty", "false"], { cwd: root, stdout: "pipe", stderr: "pipe" })
+  let [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+  await proc.exited
+  let diagnostics = parseDiagnostics(out + err)
+  let app = diagnostics.filter((d) => !d.inDependencies)
+  return { app, hidden: diagnostics.length - app.length }
+}
+
+export async function runCheckCommand() {
+  let entry = source!
+  let failed = false
+
+  let result = await bundleWith({ entry, dev: true, minify: false })
+  if (!result) {
+    // bundleWith already printed the compile errors.
+    failed = true
+  }
+
+  let root = findProjectRoot(entry)
+  if (!root) {
+    console.warn("Typecheck skipped: no tsconfig.json or package.json above the entry")
+  } else {
+    let types = await typecheck(root)
+    if (types) {
+      for (let d of types.app) console.error(d.lines.join("\n"))
+      if (types.app.length > 0) {
+        failed = true
+        let hidden = types.hidden > 0 ? ` (${types.hidden} in dependencies hidden)` : ""
+        console.error(`${types.app.length} type error${types.app.length === 1 ? "" : "s"} in app code${hidden}`)
+      } else if (types.hidden > 0) {
+        console.log(`Types OK (${types.hidden} dependency-internal errors hidden)`)
+      } else {
+        console.log("Types OK")
+      }
+    }
+  }
+
+  if (failed) process.exit(1)
+  console.log("Check passed")
+  process.exit(0)
+}

package/src/commands/init.ts

@@ -29,23 +29,48 @@ function packageName(dir: string): string {
 }
 
 const DEFAULT_TEMPLATE = "default"
+const TEMPLATE_MANIFEST = "template.json"
+
+// Each template's template.json declares which level the scaffolded app is
+// written at: "core" (only @solidrt/core, no component framework) or
+// "components" (built with @solidrt/components). The level decides the
+// generated dependencies; the description labels the template in the picker.
+interface TemplateInfo {
+  name: string
+  level: "core" | "components"
+  description: string
+}
 
 // Templates are the directories under scaffold/templates/; each holds the files
-// that become the new project's src/. `default` sorts first as the starting
-// point, the rest alphabetically.
-async function listTemplates(): Promise<string[]> {
+// that become the new project's src/, plus a template.json manifest. `default`
+// sorts first as the starting point, the rest alphabetically.
+async function listTemplates(): Promise<TemplateInfo[]> {
   let entries = await readdir(TEMPLATES_DIR, { withFileTypes: true })
-  return entries
+  let names = entries
     .filter((e) => e.isDirectory())
     .map((e) => e.name)
     .sort((a, b) =>
       a === DEFAULT_TEMPLATE ? -1 : b === DEFAULT_TEMPLATE ? 1 : a.localeCompare(b),
     )
+  let templates: TemplateInfo[] = []
+  for (let name of names) {
+    // A missing manifest falls back to the components level: it keeps every
+    // dependency, so the scaffolded app works at either level.
+    let manifest = await readFile(join(TEMPLATES_DIR, name, TEMPLATE_MANIFEST), "utf8")
+      .then((raw) => JSON.parse(raw))
+      .catch(() => ({}))
+    templates.push({
+      name,
+      level: manifest.level === "core" ? "core" : "components",
+      description: typeof manifest.description === "string" ? manifest.description : "",
+    })
+  }
+  return templates
 }
 
 // Resolve which template to scaffold from: an explicit --template if valid, an
 // interactive picker on a TTY, else `default` (or the first available).
-async function resolveTemplate(): Promise<string> {
+async function resolveTemplate(): Promise<TemplateInfo> {
   let templates = await listTemplates()
   if (templates.length === 0) {
     console.error(`!! No templates found in ${TEMPLATES_DIR}`)
@@ -53,14 +78,25 @@ async function resolveTemplate(): Promise<string> {
   }
   let chosen = values.template
   if (chosen) {
-    if (!templates.includes(chosen)) {
-      console.error(`!! Unknown template "${chosen}"; choose from: ${templates.join(", ")}`)
+    let found = templates.find((t) => t.name === chosen)
+    if (!found) {
+      let names = templates.map((t) => t.name).join(", ")
+      console.error(`!! Unknown template "${chosen}"; choose from: ${names}`)
       process.exit(1)
     }
-    return chosen
+    return found
+  }
+  if (process.stdin.isTTY) {
+    let picked = await select(
+      "Select a template",
+      templates.map((t) => ({
+        label: t.description ? `${t.name} - ${t.description}` : t.name,
+        value: t.name,
+      })),
+    )
+    return templates.find((t) => t.name === picked)!
   }
-  if (process.stdin.isTTY) return select("Select a template", templates)
-  return templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0]!
+  return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
 }
 
 export async function runInitCommand() {
@@ -84,7 +120,7 @@ export async function runInitCommand() {
 
   let template = await resolveTemplate()
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template})`)
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template.name})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
@@ -93,19 +129,22 @@ export async function runInitCommand() {
   }
 
   // The chosen template's files become the project's src/. Entries may be
-  // nested directories (e.g. an asset folder), so copy recursively.
-  let templateDir = join(TEMPLATES_DIR, template)
+  // nested directories (e.g. an asset folder), so copy recursively. The
+  // manifest describes the template rather than belonging to the app.
+  let templateDir = join(TEMPLATES_DIR, template.name)
   await mkdir(join(dir, "src"), { recursive: true })
   for (let file of await readdir(templateDir)) {
+    if (file === TEMPLATE_MANIFEST) continue
     await cp(join(templateDir, file), join(dir, "src", file), { recursive: true })
     console.log(`   Write src/${file}`)
   }
 
   // The scaffold package.json carries a placeholder name; set it from the
-  // target folder.
+  // target folder. A core-level app gets no component framework dependency.
   let pkgPath = join(dir, "package.json")
   let pkg = JSON.parse(await readFile(pkgPath, "utf8"))
   pkg.name = packageName(dir)
+  if (template.level === "core") delete pkg.dependencies["@solidrt/components"]
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
 
   // Deps are declared in scaffold/package.json (Solid peers resolve via

package/src/commands/mcp.ts

@@ -9,6 +9,7 @@ import { z } from "zod"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
+import { resolve } from "node:path"
 import { DEV_PORT } from "../dev-server"
 
 const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
@@ -44,17 +45,39 @@ let CLIENT_ARG = z
   .describe("Client id from list_clients (default: the only connected client)")
   .optional()
 
-let TOOLS: { name: string; description: string; inputSchema: Record<string, z.ZodTypeAny> }[] = [
+let SAVE_TO_ARG = z
+  .string()
+  .describe(
+    "Also write the PNG to this file path (relative paths resolve against the project root; parent directories are created)",
+  )
+  .optional()
+
+// readOnly marks tools that only inspect state; it is surfaced as the
+// MCP-standard readOnlyHint annotation so agent harnesses that honor it can
+// auto-approve the inspection majority. load, reload, and call_debug mutate
+// the running app and keep the default hints (destructive, not idempotent);
+// `annotations` overrides those defaults where a mutating tool is benign
+// (watch: a reversible, idempotent toggle). Every tool gets
+// openWorldHint: false - the bridge only ever talks to the local dev server.
+let TOOLS: {
+  name: string
+  description: string
+  inputSchema: Record<string, z.ZodTypeAny>
+  readOnly?: boolean
+  annotations?: { destructiveHint?: boolean; idempotentHint?: boolean }
+}[] = [
   {
     name: "list_clients",
+    readOnly: true,
     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 (git describe; a -dirty suffix means the binary was built from uncommitted engine changes), build profile (debug/release), and the capability names compiled into that client's runtime. Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
+      "List the app clients connected to the SolidRT dev server. Returns `generation` (identity of this server run: client ids and log cursors are only valid within one generation, so if it changed since your last call, re-fetch ids and cursors) and `clients`. Each entry has id (pass it as `client` to the other tools), platform, runtime version (git describe; a -dirty suffix means the binary was built from uncommitted engine changes), build profile (debug/release), and the capability names compiled into that client's runtime. Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
     inputSchema: {},
   },
   {
     name: "get_logs",
+    readOnly: true,
     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.",
+      "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text; consecutive identical entries are collapsed into one with a `repeats` count and the run's last seq), plus `latest` (the newest seq) and `generation` (identity of this server run; if it changed since your last call, your seq cursor and client ids are stale - start over from since 0). 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; pass `level`/`contains` to filter, e.g. level \"error\" to skip chatty output.",
     inputSchema: {
       since: z
         .number()
@@ -64,39 +87,73 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
       wait_ms: z
         .number()
         .int()
-        .describe("If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)")
+        .describe("If nothing matches newer than `since`, wait up to this many milliseconds for new output (max 30000)")
+        .optional(),
+      level: z
+        .string()
+        .describe('Only return entries with one of these levels, comma-separated (e.g. "error" or "error,warn")')
+        .optional(),
+      contains: z
+        .string()
+        .describe("Only return entries whose text contains this substring (case-insensitive)")
         .optional(),
     },
   },
   {
     name: "get_stats",
+    readOnly: true,
     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.",
+      "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. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated).",
     inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_render_tree",
+    readOnly: true,
     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: { client: CLIENT_ARG },
+      "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. Whole trees get large: prefer `query` to find nodes by kind or text first, then `root` + `depth` to inspect the region around a match. A node whose children were cut off by `depth` carries `childCount`; descend into it with root=<its id>.",
+    inputSchema: {
+      root: z
+        .number()
+        .int()
+        .describe("Only return the subtree under this node id (default: the whole tree)")
+        .optional(),
+      depth: z
+        .number()
+        .int()
+        .describe("Levels of children to include below the root (default: unlimited; 0 = the root node only)")
+        .optional(),
+      query: z
+        .string()
+        .describe(
+          "Search instead of snapshot: return `matches`, nodes whose kind equals or text contains this " +
+            "(case-insensitive), each with a `path` of ancestor ids from the search root. Combine with `root` to " +
+            "scope the search; `depth` is ignored.",
+        )
+        .optional(),
+      client: CLIENT_ARG,
+    },
   },
   {
     name: "get_snapshot",
+    readOnly: true,
     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.",
+      "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. Works on an idle client (the capture requests its own frame); a timeout means the client's JS thread is busy or wedged, not that the app is idle.",
     inputSchema: {
       nodeId: z.number().int().describe("Id of the node to capture, from get_render_tree"),
+      save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
   },
   {
     name: "get_gpu_resources",
+    readOnly: true,
     description:
       "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount, depth, attribute layout, bound sampler texture ids, last-applied uniform values). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents.",
     inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_texture",
+    readOnly: true,
     description:
       "Read back any GPU texture from a running app client as a PNG, by texture id (from get_gpu_resources, or the id returned by createImage/createShader/createPipeline in app code). Works on sampled textures (atlases, data textures) and shader/pipeline render targets alike, without needing a frame. Pass x/y/width/height to crop, e.g. one tile of an atlas.",
     inputSchema: {
@@ -105,11 +162,13 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
       y: z.number().int().describe("Crop rect top edge in texture pixels").optional(),
       width: z.number().int().describe("Crop rect width in texture pixels").optional(),
       height: z.number().int().describe("Crop rect height in texture pixels").optional(),
+      save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
   },
   {
     name: "get_buffer",
+    readOnly: true,
     description:
       "Read back part of a GPU vertex buffer from a running app client, decoded to numbers. Returns values plus byteOffset/byteLength actually read and bufferByteLength. Reads are capped at 64 KiB per call; page through larger buffers with offset. Use it to verify geometry after a writeBuffer, e.g. the dynamic sprite tail of a vertex buffer.",
     inputSchema: {
@@ -122,6 +181,7 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     name: "list_debug",
+    readOnly: true,
     description:
       "List the debug commands the running app registered via registerDebug from srt:dev. Returns the command names; call one with call_debug. Empty when the app registered none.",
     inputSchema: { client: CLIENT_ARG },
@@ -139,9 +199,26 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   {
     name: "reload",
     description:
-      "Rebuild the app from source and push it to every connected client. Call this after editing the app's .tsx/.jsx source to apply the changes: it bundles once and reloads all clients, so a burst of edits becomes a single explicit reload. Returns the number of clients reloaded, or a build error if the source failed to compile. Follow with get_logs to see runtime output from the reloaded app.",
+      "Rebuild the app from source and push it to every connected client. Call this after editing the app's .tsx/.jsx source to apply the changes: it bundles once and reloads all clients, so a burst of edits becomes a single explicit reload. Returns the number of clients reloaded, or a build error if the source failed to compile. A successful reload re-enables the file watcher if you paused it with the watch tool. Follow with get_logs to see runtime output from the reloaded app.",
     inputSchema: {},
   },
+  {
+    name: "load",
+    description:
+      "Load an app entry: bundle the given .tsx/.jsx source file and push it to every connected client, replacing whatever is running. Use it when the dev server has no app loaded yet, or to switch to a different app; later reload calls rebuild this entry. Returns the number of clients loaded, or a build error if the source failed to compile. A successful load re-enables the file watcher if you paused it with the watch tool.",
+    inputSchema: {
+      entry: z.string().describe("App entry source file to load (relative paths resolve against the project root)"),
+    },
+  },
+  {
+    name: "watch",
+    annotations: { destructiveHint: false, idempotentHint: true },
+    description:
+      "Pause or resume the dev server's automatic reload-on-save. The srt file watcher pushes a rebuild whenever app source changes on disk; call watch with enabled: false BEFORE creating or editing source files so your half-finished work is not pushed to the user's screens mid-burst, then apply everything with one explicit reload (a successful reload or load re-enables the watcher, so pause again before the next burst of file changes). The human's own saves auto-reload only while the watcher is enabled, so do not leave it paused when you stop working.",
+    inputSchema: {
+      enabled: z.boolean().describe("false pauses auto-reload-on-save, true resumes it"),
+    },
+  },
 ]
 
 function clientParam(args: any): string {
@@ -156,15 +233,34 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       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))
+      if (typeof args?.level === "string") params.set("level", args.level)
+      if (typeof args?.contains === "string") params.set("contains", args.contains)
       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_render_tree": {
+      let params = new URLSearchParams()
+      if (typeof args?.root === "number") params.set("root", String(args.root))
+      if (typeof args?.depth === "number") params.set("depth", String(args.depth))
+      if (typeof args?.query === "string") params.set("query", args.query)
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      let qs = params.toString()
+      return control(qs ? `/tree?${qs}` : "/tree")
+    }
     case "reload":
       return control("/reload", "POST")
+    case "load": {
+      if (typeof args?.entry !== "string" || !args.entry) return { ok: false, message: "load requires an entry path" }
+      // Resolved here in the bridge: this process runs at the project root,
+      // the dev server may not.
+      return control("/load", "POST", { entry: resolve(args.entry) })
+    }
+    case "watch": {
+      if (typeof args?.enabled !== "boolean") return { ok: false, message: "watch requires enabled: true or false" }
+      return control("/watch", "POST", { enabled: args.enabled })
+    }
     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) })
@@ -204,15 +300,29 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
   }
 }
 
-function toContent(name: string, result: ControlResult): CallToolResult {
+async function toContent(name: string, result: ControlResult, args?: any): Promise<CallToolResult> {
   if (!result.ok) return { content: [{ type: "text", text: result.message }], isError: true }
   if (name === "get_snapshot" || name === "get_texture") {
     let { pngBase64, width, height } = result.body
     let label = name === "get_snapshot" ? "Captured node snapshot" : "Texture contents"
+    let text = `${label}: ${width}x${height} px`
+    // save_to is handled here in the bridge, not by the dev server: this
+    // process runs on the caller's machine, so the path lands where the
+    // agent expects it. The image content block alone is a dead end for
+    // that - the model sees the pixels but never the bytes.
+    if (typeof args?.save_to === "string") {
+      let path = resolve(args.save_to)
+      try {
+        await Bun.write(path, Buffer.from(pngBase64, "base64"))
+        text += `, saved to ${path}`
+      } catch (e) {
+        return { content: [{ type: "text", text: `Captured, but saving to ${path} failed: ${e}` }], isError: true }
+      }
+    }
     return {
       content: [
         { type: "image", data: pngBase64, mimeType: "image/png" },
-        { type: "text", text: `${label}: ${width}x${height} px` },
+        { type: "text", text },
       ],
     }
   }
@@ -225,8 +335,12 @@ export async function runMcpCommand() {
   for (let tool of TOOLS) {
     server.registerTool(
       tool.name,
-      { description: tool.description, inputSchema: tool.inputSchema },
-      async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {})),
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: { readOnlyHint: !!tool.readOnly, openWorldHint: false, ...tool.annotations },
+      },
+      async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {}), args),
     )
   }
 

package/src/dev-server.ts

@@ -51,6 +51,26 @@ export async function sendStats(stats: boolean) {
   await post("/stats", { stats })
 }
 
+/** Latch the auto-reload flag on the server (repl `watch on|off`). */
+export async function sendWatch(enabled: boolean) {
+  await post("/watch", { enabled })
+}
+
+/**
+ * Whether the watcher may auto-reload: agents pause it via the MCP watch
+ * tool, latched on the server. Fails open so an unreachable server surfaces
+ * as a reload error, not a silently ignored change.
+ */
+export async function watchAllowed(): Promise<boolean> {
+  try {
+    let resp = await fetch(`${INTERNAL_BASE}/watch`)
+    if (!resp.ok) return true
+    return (await resp.json()).enabled !== false
+  } catch {
+    return true
+  }
+}
+
 export type ClientEntry = {
   id: number
   platform: string

package/src/main.ts

@@ -3,6 +3,7 @@
 import { values, command, validateArgs, printUsage } from "./args"
 import { runInitCommand } from "./commands/init"
 import { runBundleCommand } from "./commands/bundle"
+import { runCheckCommand } from "./commands/check"
 import { runPackCommand } from "./commands/pack"
 import { runRenderCommand } from "./commands/render"
 import { runServerCommand } from "./commands/server"
@@ -41,6 +42,8 @@ if (command === "init") {
   await runInitCommand()
 } else if (command === "bundle") {
   await runBundleCommand()
+} else if (command === "check") {
+  await runCheckCommand()
 } else if (command === "pack") {
   await runPackCommand()
 } else if (command === "render") {

package/src/prompt.ts

@@ -15,16 +15,24 @@ export function text(message: string, def = ""): Promise<string> {
   })
 }
 
+export interface SelectOption {
+  label: string
+  value: string
+}
+
 // Minimal arrow-key single-select prompt, built on node:readline (same
 // dependency-free approach as repl.ts). Renders the option list, moves the
-// highlight on up/down, resolves the chosen value on enter. Callers guard on
-// process.stdin.isTTY; a non-TTY stdin here resolves the first option rather
-// than hanging on input that will never arrive.
-export function select(message: string, options: string[]): Promise<string> {
+// highlight on up/down, resolves the chosen value on enter. Options are plain
+// strings or { label, value } pairs when the display text differs from the
+// resolved value. Callers guard on process.stdin.isTTY; a non-TTY stdin here
+// resolves the first option rather than hanging on input that will never
+// arrive.
+export function select(message: string, options: Array<string | SelectOption>): Promise<string> {
+  let items = options.map((o) => (typeof o === "string" ? { label: o, value: o } : o))
   return new Promise((resolve) => {
     let input = process.stdin
     let output = process.stdout
-    if (!input.isTTY) return resolve(options[0]!)
+    if (!input.isTTY) return resolve(items[0]!.value)
 
     let selected = 0
     emitKeypressEvents(input)
@@ -34,13 +42,13 @@ export function select(message: string, options: string[]): Promise<string> {
     let render = (first = false) => {
       // After the first paint the cursor sits below the block; move it back up
       // to the message line so the list redraws in place.
-      if (!first) output.write(`\x1b[${options.length + 1}A`)
+      if (!first) output.write(`\x1b[${items.length + 1}A`)
       output.write(`\x1b[K? ${message}\n`)
-      for (let i = 0; i < options.length; i++) {
+      for (let i = 0; i < items.length; i++) {
         let active = i === selected
         let pointer = active ? "\x1b[36m> " : "  "
         let reset = active ? "\x1b[0m" : ""
-        output.write(`\x1b[K${pointer}${options[i]}${reset}\n`)
+        output.write(`\x1b[K${pointer}${items[i]!.label}${reset}\n`)
       }
     }
 
@@ -53,15 +61,15 @@ export function select(message: string, options: string[]): Promise<string> {
     let onKey = (_str: string, key: { name: string; ctrl: boolean } | undefined) => {
       if (!key) return
       if (key.name === "up") {
-        selected = (selected - 1 + options.length) % options.length
+        selected = (selected - 1 + items.length) % items.length
         render()
       } else if (key.name === "down") {
-        selected = (selected + 1) % options.length
+        selected = (selected + 1) % items.length
         render()
       } else if (key.name === "return" || key.name === "enter") {
         cleanup()
         output.write("\n")
-        resolve(options[selected]!)
+        resolve(items[selected]!.value)
       } else if (key.ctrl && (key.name === "c" || key.name === "d")) {
         cleanup()
         output.write("\n")

package/src/repl.ts

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline"
 import { resolve, dirname } from "path"
 import { readdirSync } from "node:fs"
 import { state, print, printErr, shutdown } from "./util"
-import { buildReload, getClients, sendReload, sendStop, sendStats, showBuildFailure } from "./dev-server"
+import { buildReload, getClients, sendReload, sendStop, sendStats, sendWatch, showBuildFailure } from "./dev-server"
 import { bundle } from "./bundler"
 import { startWatcher, stopWatcher } from "./watcher"
 
@@ -133,7 +133,7 @@ async function cmdLoad(file: string) {
   print(`[cli] Loaded ${file}`)
 }
 
-let COMMANDS = ["load ", "stop", "reload", "list", "stats", "quit", "exit", "help"]
+let COMMANDS = ["load ", "stop", "reload", "list", "stats", "watch ", "quit", "exit", "help"]
 let LOAD_EXTENSIONS = [".tsx", ".srt.js", ".srt.bin"]
 
 function completer(line: string): [string[], string] {
@@ -186,6 +186,11 @@ export function startRepl() {
       guard(cmdList())
     } else if (cmd === "stats" || cmd.startsWith("stats ")) {
       guard(cmdStats(cmd.slice(6).trim()))
+    } else if (cmd === "watch on" || cmd === "watch off") {
+      // Manual override for the agent-latched auto-reload pause (an agent
+      // that died mid-edit leaves it off; its reload normally restores it).
+      let enabled = cmd === "watch on"
+      guard(sendWatch(enabled).then(() => print(`[cli] Auto-reload on change ${enabled ? "on" : "off"}`)))
     } else if (cmd === "quit" || cmd === "exit") {
       shutdown()
     } else if (cmd.startsWith("!")) {
@@ -201,7 +206,7 @@ export function startRepl() {
         )
       }
     } else if (cmd === "help") {
-      print("Commands: load, stop, reload, list, stats, !<cmd>, quit, help")
+      print("Commands: load, stop, reload, list, stats, watch on|off, !<cmd>, quit, help")
     } else if (cmd) {
       print(`Unknown command: ${cmd}`)
     }

package/src/watcher.ts

@@ -1,7 +1,7 @@
 import { watch } from "node:fs"
 import { resolve, dirname } from "path"
 import { state, print, printErr } from "./util"
-import { buildReload, sendReload, showBuildFailure } from "./dev-server"
+import { buildReload, sendReload, showBuildFailure, watchAllowed } from "./dev-server"
 import { bundle } from "./bundler"
 
 let currentWatcher: ReturnType<typeof watch> | null = null
@@ -24,6 +24,11 @@ export function startWatcher() {
     if (!filename) return
     if (!/\.(tsx?|jsx?)$/.test(filename)) return
 
+    if (!(await watchAllowed())) {
+      print(`[cli] Change detected: ${filename} (auto-reload paused by agent; "watch on" resumes)`)
+      return
+    }
+
     print(`[cli] Change detected: ${filename}`)
     let result = await bundle(state.source)
     if (!result) {