lecodes-cli 0.19.0 → 0.20.0

package/src/desktopScript.ts

@@ -0,0 +1,276 @@
+import { resolve } from "node:path"
+import { CliError } from "./util"
+
+/*
+ * `lecodes render --desktop --script`: the same JSON scenario a headless run takes, driven through
+ * the NATIVE desktop host. The host has no semantic UI tree, so it can't resolve names or read text —
+ * it takes a line-based command file (CREATOR_SCRIPT, see packages/desktop/src/main.cpp `scriptStep`)
+ * with COORDINATES, and reports `[script] #<line> done <op>` on stdout as each command completes.
+ * This module does both halves: translate the scenario into that file (refusing, with guidance, the
+ * steps the host can't honour) and turn the host's stdout back into per-step results — `expect.log`
+ * is evaluated here against the console lines seen up to each step's marker; the semantic expects
+ * (`screen`/`node`/`text`/`value`) are reported as skipped, never silently passed.
+ */
+
+type Point = { x: number, y: number }
+const isPoint = (v: unknown): v is Point =>
+  typeof v === "object" && v !== null && typeof (v as Point).x === "number" && typeof (v as Point).y === "number"
+
+const FRAME_MS = 16
+
+export type DesktopPlanStep = {
+  index: number
+  desc: string
+  /** Script line numbers this step emitted; the LAST one's `done` marker completes the step. */
+  lines: number[]
+  expectLog?: string
+  /** Expect keys the native host can't evaluate (no semantic tree) — reported as skipped. */
+  skippedExpect: string[]
+  /** Outputs the native host can't produce (`json`). */
+  skippedOutputs: string[]
+  screenshot?: string
+}
+
+export type DesktopPlan = {
+  /** The CREATOR_SCRIPT file contents. */
+  text: string
+  steps: DesktopPlanStep[]
+  /** A safety cap for CREATOR_MAX_FRAMES: the script's own time in frames plus slack. */
+  frameCap: number
+}
+
+const ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"] as const
+const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"]
+const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
+const isVec3 = (v: unknown): v is [number, number, number] => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number")
+
+const pt = (p: Point) => `(${p.x},${p.y})`
+
+/** Translate scenario steps into the host's command file. `headroomFrames` runs first so the app
+ *  can load (the `--frames` value); screenshots land under `outDir`. Throws a CliError for steps the
+ *  native host can't honour (named targets, typing, scrolling, clips). */
+export const translateScenario = (rawSteps: unknown, opts: { outDir: string, headroomFrames: number }): DesktopPlan => {
+  if (!Array.isArray(rawSteps)) throw new CliError(`"steps" must be an array of step objects.`)
+  const lines: string[] = []
+  const steps: DesktopPlanStep[] = []
+  let budgetMs = 0
+  const emit = (line: string): number => { lines.push(line); return lines.length }
+  emit(`# generated by lecodes render --desktop --script`)
+  emit(`frames ${Math.max(0, opts.headroomFrames)}`)
+
+  const coord = (at: string, key: string, v: unknown): Point => {
+    if (isPoint(v)) return v
+    if (typeof v === "string") {
+      throw new CliError(`${at}: "${key}": "${v}" — the native host can't resolve names; give --desktop scripts { "x", "y" } coordinates (logical px), or run the scenario headless (without --desktop).`)
+    }
+    throw new CliError(`${at}: "${key}" must be { "x", "y" }.`)
+  }
+  const num = (at: string, key: string, v: unknown, def?: number): number => {
+    if (v === undefined && def !== undefined) return def
+    if (typeof v !== "number") throw new CliError(`${at}: "${key}" must be a number.`)
+    return v
+  }
+
+  // While an inspection camera is active, the app's raycasts read ITS camera, not what the shot shows —
+  // a tap/drag there would silently hit the wrong thing, so pointer steps are refused until `"off"`.
+  let inspecting = false
+  rawSteps.forEach((step, i) => {
+    const at = `steps[${i}]`
+    if (typeof step !== "object" || step === null || Array.isArray(step)) throw new CliError(`${at}: must be an object.`)
+    const s = step as Record<string, unknown>
+    const actions = ACTIONS.filter((k) => s[k] !== undefined)
+    if (actions.length > 1) throw new CliError(`${at}: one action per step (found ${actions.join(" + ")}).`)
+    const plan: DesktopPlanStep = { index: i, desc: "", lines: [], skippedExpect: [], skippedOutputs: [] }
+    const parts: string[] = []
+    const action = actions[0]
+
+    if (action === "type" || action === "fill" || action === "scroll") {
+      throw new CliError(`${at}: "${action}" isn't available with --desktop (the native host has no semantic tree / soft keyboard) — run this scenario headless, or drive the gesture with "drag" coordinates.`)
+    }
+    if ((action === "tap" || action === "drag" || action === "hold") && inspecting) {
+      throw new CliError(`${at}: "${action}" while an inspection camera is active — the app's hit-testing uses its own camera, not the one in the shot. Add { "view": "off" } (or { "camera": "off" }) first.`)
+    }
+    if (action === "view") {
+      const v = s.view
+      const fov = s.fov !== undefined ? num(at, "fov", s.fov) : undefined
+      if (v === "off") { plan.lines.push(emit("view off")); inspecting = false; parts.push("view off") }
+      else if (typeof v === "string" && VIEW_NAMES.includes(v)) {
+        plan.lines.push(emit(`view ${v}${fov !== undefined ? ` ${fov}` : ""}`)); inspecting = true
+        parts.push(`view ${v}${fov !== undefined ? ` (fov ${fov})` : ""}`)
+      } else throw new CliError(`${at}: "view" wants one of ${VIEW_NAMES.join(", ")} or "off".`)
+      budgetMs += 2 * FRAME_MS
+    } else if (action === "camera") {
+      const cam = s.camera
+      if (cam === "off") { plan.lines.push(emit("camera off")); inspecting = false; parts.push("camera off") }
+      else if (typeof cam === "object" && cam !== null && isVec3((cam as any).at) && isVec3((cam as any).lookAt)) {
+        const { at: eye, lookAt, fov } = cam as { at: number[], lookAt: number[], fov?: unknown }
+        const fovN = fov !== undefined ? num(at, "camera.fov", fov) : undefined
+        plan.lines.push(emit(`camera ${eye.join(" ")} ${lookAt.join(" ")}${fovN !== undefined ? ` ${fovN}` : ""}`)); inspecting = true
+        parts.push(`camera at (${eye.join(",")}) → (${lookAt.join(",")})`)
+      } else throw new CliError(`${at}: "camera" wants { "at": [x,y,z], "lookAt": [x,y,z], "fov"? } or "off".`)
+      budgetMs += 2 * FRAME_MS
+    }
+    if (s.fov !== undefined && action !== "view") throw new CliError(`${at}: "fov" only goes with "view" (inside "camera" use camera.fov).`)
+    if (action === "tap") {
+      const p = coord(at, "tap", s.tap)
+      plan.lines.push(emit(`tap ${p.x} ${p.y}`)); budgetMs += 4 * FRAME_MS
+      parts.push(`tap ${pt(p)}`)
+    } else if (action === "drag") {
+      const a = coord(at, "drag", s.drag), b = coord(at, "to", s.to)
+      const ms = num(at, "ms", s.ms, 300)
+      plan.lines.push(emit(`drag ${a.x} ${a.y} ${b.x} ${b.y} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
+      parts.push(`drag ${pt(a)} → ${pt(b)} over ${ms}ms`)
+    } else if (action === "hold") {
+      const p = coord(at, "hold", s.hold)
+      const ms = num(at, "ms", s.ms)
+      plan.lines.push(emit(`hold ${p.x} ${p.y} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
+      parts.push(`hold ${pt(p)} ${ms}ms`)
+    } else if (action === "key") {
+      if (typeof s.key !== "string") throw new CliError(`${at}: "key" must be a KeyboardEvent.code string.`)
+      const ms = num(at, "ms", s.ms)
+      plan.lines.push(emit(`key ${s.key} ${Math.round(ms)}`)); budgetMs += ms + 2 * FRAME_MS
+      parts.push(`key ${s.key} ${ms}ms`)
+    } else if (action === "keyDown" || action === "keyUp") {
+      const code = s[action]
+      if (typeof code !== "string") throw new CliError(`${at}: "${action}" must be a code string.`)
+      plan.lines.push(emit(`${action.toLowerCase()} ${code}`)); budgetMs += 2 * FRAME_MS
+      parts.push(`${action} ${code}`)
+    } else if (action === "look") {
+      const v = s.look
+      if (!Array.isArray(v) || v.length !== 2 || !v.every((n: unknown) => typeof n === "number")) throw new CliError(`${at}: "look" must be [dx, dy] (logical px of mouse motion).`)
+      const ms = num(at, "ms", s.ms, FRAME_MS)
+      plan.lines.push(emit(`look ${v[0]} ${v[1]} ${Math.round(ms)}`)); budgetMs += ms + 2 * FRAME_MS
+      parts.push(`look ${v[0]},${v[1]} over ${ms}ms`)
+    } else if (action === "mouseTo") {
+      const v = s.mouseTo
+      if (!Array.isArray(v) || v.length !== 2 || !v.every((n: unknown) => typeof n === "number")) throw new CliError(`${at}: "mouseTo" must be [x, y] (logical px).`)
+      plan.lines.push(emit(`mouseto ${v[0]} ${v[1]}`)); budgetMs += FRAME_MS
+      parts.push(`mouseTo ${v[0]},${v[1]}`)
+    } else if (action === "wheel") {
+      const v = s.wheel
+      if (!Array.isArray(v) || v.length !== 2 || !v.every((n: unknown) => typeof n === "number")) throw new CliError(`${at}: "wheel" must be [dx, dy] (notches).`)
+      plan.lines.push(emit(`wheel ${v[0]} ${v[1]}`)); budgetMs += 2 * FRAME_MS
+      parts.push(`wheel ${v[0]},${v[1]}`)
+    } else if (action === "stick") {
+      const st = s.stick
+      if (typeof st !== "object" || st === null) throw new CliError(`${at}: "stick" must be { left?: [x, y], right?: [x, y], triggers?: [l, r] }.`)
+      const pad = typeof s.index === "number" ? s.index : 0
+      const parts2: string[] = []
+      for (const k of ["left", "right", "triggers"] as const) {
+        const v = (st as any)[k]
+        if (v === undefined) continue
+        if (!Array.isArray(v) || v.length !== 2 || !v.every((n: unknown) => typeof n === "number")) throw new CliError(`${at}: "stick.${k}" must be a pair of numbers.`)
+        plan.lines.push(emit(`stick ${pad} ${k} ${v[0]} ${v[1]}`)); parts2.push(`${k}=${v[0]},${v[1]}`)
+      }
+      for (const k of Object.keys(st)) if (!["left", "right", "triggers"].includes(k)) throw new CliError(`${at}: "stick" knows left, right, triggers — not "${k}".`)
+      budgetMs += 2 * FRAME_MS
+      parts.push(`stick #${pad} ${parts2.join(" ")}`)
+    } else if (action === "gamepad") {
+      if (s.gamepad !== "connect" && s.gamepad !== "disconnect") throw new CliError(`${at}: "gamepad" must be "connect" or "disconnect".`)
+      const pad = typeof s.index === "number" ? s.index : 0
+      plan.lines.push(emit(`gamepad ${pad} ${s.gamepad}`)); budgetMs += 2 * FRAME_MS
+      parts.push(`gamepad ${s.gamepad} #${pad}`)
+    } else if (action === "wait") {
+      const ms = num(at, "wait", s.wait)
+      plan.lines.push(emit(`wait ${Math.round(ms)}`)); budgetMs += ms + FRAME_MS
+      parts.push(`wait ${ms}ms`)
+    } else if (action === "frames") {
+      const n = num(at, "frames", s.frames)
+      plan.lines.push(emit(`frames ${Math.round(n)}`)); budgetMs += n * FRAME_MS + FRAME_MS
+      parts.push(`advance ${n} frames`)
+    }
+
+    if (s.expect !== undefined) {
+      if (typeof s.expect !== "object" || s.expect === null) throw new CliError(`${at}: "expect" must be an object.`)
+      const e = s.expect as Record<string, unknown>
+      const bits: string[] = []
+      for (const k of Object.keys(e)) {
+        if (k === "log") {
+          if (typeof e.log !== "string") throw new CliError(`${at}: expect.log must be a string.`)
+          plan.expectLog = e.log
+          bits.push(`log~"${e.log}"`)
+        } else if (SEMANTIC_EXPECT.includes(k)) {
+          plan.skippedExpect.push(k)
+        } else {
+          throw new CliError(`${at}: unknown expect key "${k}".`)
+        }
+      }
+      if (bits.length > 0) parts.push(`expect ${bits.join(" · ")}`)
+    }
+    if (s.clip !== undefined) throw new CliError(`${at}: "clip" isn't available with --desktop (the native host dumps the whole window).`)
+    if (s.screenshot !== undefined) {
+      if (typeof s.screenshot !== "string") throw new CliError(`${at}: "screenshot" must be a path.`)
+      plan.screenshot = resolve(opts.outDir, s.screenshot)
+      // The shot lands AFTER the action settles (two frames), like the headless act → capture order.
+      plan.lines.push(emit(`frames 2`))
+      plan.lines.push(emit(`shot ${plan.screenshot}`)); budgetMs += 3 * FRAME_MS
+      parts.push(`→ ${s.screenshot}`)
+    }
+    if (s.json !== undefined) plan.skippedOutputs.push("json")
+    if (plan.lines.length === 0) {
+      // An expect-only step still needs a marker to anchor its evaluation.
+      plan.lines.push(emit(`frames 1`)); budgetMs += FRAME_MS
+    }
+    plan.desc = typeof s.name === "string" ? s.name : (parts.join(", ") || "(empty step)")
+    steps.push(plan)
+  })
+
+  const frameCap = Math.max(0, opts.headroomFrames) + Math.ceil(budgetMs / FRAME_MS) + 600
+  return { text: lines.join("\n") + "\n", steps, frameCap }
+}
+
+export type DesktopStepResult = { desc: string, ok: boolean, error?: string, skipped: string[] }
+export type DesktopRunResult = {
+  /** The host understood CREATOR_SCRIPT at all (an older host ignores it and just renders). */
+  loaded: boolean
+  ended: boolean
+  ok: boolean
+  steps: DesktopStepResult[]
+}
+
+/** Turn the host's stdout into per-step results. Console lines are every non-`[script]` line the
+ *  host printed up to a step's completion marker (the core prints `console.log` as `[DEBUG] …`). */
+export const evaluateDesktopRun = (plan: DesktopPlan, output: string): DesktopRunResult => {
+  const lines = output.split(/\r?\n/)
+  const doneAt = new Map<number, { at: number, error?: string }>()
+  const consoleLines: string[] = []
+  let loaded = false, ended = false
+  for (const line of lines) {
+    const m = /^\[script\] #(\d+) (done|error) (\S+)(?:: (.*))?$/.exec(line)
+    if (m) {
+      doneAt.set(Number(m[1]), { at: consoleLines.length, error: m[2] === "error" ? `${m[3]}: ${m[4] ?? "failed"}` : undefined })
+      continue
+    }
+    if (line.startsWith("[script] loaded")) { loaded = true; continue }
+    if (line === "[script] end") { ended = true; continue }
+    if (line.startsWith("[script]")) continue
+    consoleLines.push(line)
+  }
+
+  const steps: DesktopStepResult[] = []
+  let ok = true
+  for (const st of plan.steps) {
+    const skipped = [
+      ...st.skippedExpect.map((k) => `expect.${k} (no semantic tree on --desktop)`),
+      ...st.skippedOutputs.map((k) => `${k} output (no semantic tree on --desktop)`),
+    ]
+    let error: string | undefined
+    let cutoff = consoleLines.length
+    for (const ln of st.lines) {
+      const d = doneAt.get(ln)
+      if (!d) { error = error ?? "the host never completed this step (crashed, closed, or hit the frame cap before it)"; break }
+      if (d.error) { error = error ?? d.error; break }
+      cutoff = d.at
+    }
+    if (!error && st.expectLog !== undefined) {
+      const seen = consoleLines.slice(0, cutoff)
+      if (!seen.some((l) => l.includes(st.expectLog!))) {
+        const tail = seen.filter((l) => l.startsWith("[DEBUG]") || l.startsWith("[INFO]") || l.startsWith("[WARN]") || l.startsWith("[ERROR]")).slice(-8)
+        error = `expected a console line containing "${st.expectLog}" — ${tail.length === 0 ? "the app logged nothing" : `last lines: ${tail.map((l) => `"${l}"`).join(", ")}`}`
+      }
+    }
+    if (error) ok = false
+    steps.push({ desc: st.desc, ok: !error, error, skipped })
+  }
+  return { loaded, ended, ok: ok && loaded, steps }
+}

package/src/dev/clientTemplates.ts

@@ -0,0 +1,160 @@
+/*
+ * The on-device dev client for `lecodes dev`, shipped FROM the CLI (updatable without app
+ * releases). Two pieces:
+ *
+ * - DEV_SCREEN_TS — a tiny placeholder project (globals-only, like any user project) compiled
+ *   through the normal pipeline into `dev.js`, the URL the QR code points at. Its auto-generated
+ *   header says `// gl: disable`, so the app launcher creates no engine for it.
+ *
+ * - DEV_PRELUDE_JS — plain JS appended VERBATIM to every bundle the dev server serves (dev.js and
+ *   bundle.js alike). It only touches the raw `_creatorUtils` / `_creator` bridge — no SDK — so it
+ *   can ride along any compiled project without duplicating the injected runtime. Each
+ *   `_creatorUtils.run()` world therefore carries its own copy: the running world holds the live
+ *   connection; when it loads the next bundle, the NEW world's copy connects and the native
+ *   per-world socket teardown closes the old one. On eval error, run()'s rollback keeps the
+ *   current world (and its connection) alive, so the reject callback here reports + keeps serving.
+ *
+ * Placeholders (substituted by the dev server, see renderPrelude):
+ *   __DEV_ORIGIN__     http://<ip>:<port>
+ *   __DEV_BASE__       /t/<token>
+ *   __DEV_TRANSPORT__  "ws" | "poll"  (poll = hosts without a websocket bridge, e.g. the desktop host)
+ *   __DEV_V__          the bundle version this world runs (-1 for dev.js → always load latest)
+ */
+
+export const DEV_SCREEN_TS = `const title = "LeCodes Dev"
+const project = __DEV_NAME__
+
+UIScreen([
+  UIText(title).style({ fontSize: 30, fontWeight: 700, color: "#ffffff" }),
+  UIText(project).style({ fontSize: 16, color: "#9fb0d0", mt: 8 }),
+  UIText("Connected — loading the project…").style({ fontSize: 14, color: "#6b7a99", mt: 20 }),
+]).style({ bgColor: "#11131a", justifyContent: "center", alignItems: "center", p: 40 }).open()
+`
+
+export const DEV_PRELUDE_JS = `
+;(function () {
+  var ORIGIN = "__DEV_ORIGIN__"
+  var BASE = "__DEV_BASE__"
+  var TRANSPORT = "__DEV_TRANSPORT__"
+  var V = __DEV_V__
+  var wsId = null
+  var busy = false
+  var queued = null
+
+  function post(obj) {
+    var text = JSON.stringify(obj)
+    if (TRANSPORT === "ws") {
+      if (wsId !== null) { try { _creatorUtils.websocketSend(wsId, text) } catch (e) {} }
+      return
+    }
+    try {
+      _creatorUtils.fetch(ORIGIN + BASE + "/log", { method: "POST", body: text, headers: { "content-type": "application/json" } },
+        function (id) { try { _creatorUtils.disposeFetch(id) } catch (e) {} }, function () {})
+    } catch (e) {}
+  }
+
+  // An Error carries its stack (JSON.stringify would send a useless "{}"); the dev server maps the
+  // frames back to project positions before printing.
+  function describe(a) {
+    if (typeof a === "string") return a
+    if (a && typeof a.stack === "string" && typeof a.message === "string") {
+      return a.stack ? String(a) + "\\n" + a.stack : String(a)
+    }
+    try { return JSON.stringify(a) } catch (e) { return String(a) }
+  }
+
+  // Mirror console output to the dev terminal ('silent' guards recursion through wrapped calls).
+  var silent = false
+  ;["log", "warn", "error"].forEach(function (level) {
+    var orig = console[level]
+    console[level] = function () {
+      var parts = []
+      for (var i = 0; i < arguments.length; i++) parts.push(describe(arguments[i]))
+      try { orig.apply(console, arguments) } catch (e) {}
+      if (!silent) { silent = true; try { post({ type: "log", level: level, text: parts.join(" ") }) } finally { silent = false } }
+    }
+  })
+
+  function report(err) { post({ type: "error", text: describe(err) }) }
+
+  function load(v) {
+    if (busy) { queued = v; return }
+    busy = true
+    _creatorUtils.fetch(ORIGIN + BASE + "/bundle.js?v=" + v + "&t=" + TRANSPORT, {}, function (id, status) {
+      if (status >= 400) { busy = false; report("bundle fetch: HTTP " + status); return }
+      // Same engine bringup the app launcher does for a fresh launch (see desktop initial.ts).
+      var head = ""
+      try { head = _creatorUtils.fetchSlice(id, 0, 300) } catch (e) {}
+      var preloads = head.match(/\\/\\/ preload: (.+)/)
+      if (head.indexOf("// gl:") < 0) {
+        try { _creator.createEngine(preloads ? preloads[1].split(";") : []) } catch (e) { report("createEngine: " + String(e)) }
+      }
+      _creatorUtils.run(id, function (err) {
+        // Eval failed → native rollback kept THIS world (and its connection) alive. Keep serving.
+        busy = false
+        report(err)
+        if (queued !== null) { var q = queued; queued = null; load(q) }
+      })
+      // On success this world is torn down next tick — the new bundle carries its own prelude.
+    }, function (err) { busy = false; report("bundle fetch failed: " + String(err)) })
+  }
+
+  function onServer(data) {
+    var m = null
+    try { m = JSON.parse(data) } catch (e) { return }
+    if (m && m.type === "reload" && typeof m.v === "number" && m.v !== V) load(m.v)
+  }
+
+  if (TRANSPORT === "ws") {
+    var url = ORIGIN.replace("http", "ws") + BASE + "/ws"
+    var open = function () {
+      try {
+        wsId = _creatorUtils.websocketOpen(url, function (channel, data) {
+          if (channel === "open") {
+            try { _creatorUtils.websocketSend(wsId, JSON.stringify({ type: "hello", v: V })) } catch (e) {}
+          } else if (channel === "message") {
+            onServer(data)
+          } else if (channel === "close" || channel === "error") {
+            wsId = null
+            setTimeout(open, 2000)
+          }
+        })
+      } catch (e) { setTimeout(open, 2000) }
+    }
+    open()
+  } else {
+    var poll = function () {
+      _creatorUtils.fetch(ORIGIN + BASE + "/version", {}, function (id, status) {
+        var v = null
+        try { v = _creatorUtils.fetchToJson(id).v } catch (e) {}
+        try { _creatorUtils.disposeFetch(id) } catch (e) {}
+        setTimeout(poll, 700)
+        if (status < 400 && typeof v === "number" && v !== V && !busy) load(v)
+      }, function () { setTimeout(poll, 1500) })
+    }
+    poll()
+  }
+})();
+`
+
+export type PreludeParams = {
+  /** e.g. "http://192.168.1.5:4499" */
+  origin: string
+  /** e.g. "/t/a1b2c3d4" */
+  base: string
+  transport: "ws" | "poll"
+  /** The version baked into this bundle; -1 for dev.js (always loads the latest). */
+  v: number
+}
+
+/** The prelude with its placeholders substituted, ready to append to a compiled bundle. */
+export const renderPrelude = (p: PreludeParams): string =>
+  DEV_PRELUDE_JS
+    .split("__DEV_ORIGIN__").join(p.origin)
+    .split("__DEV_BASE__").join(p.base)
+    .split("__DEV_TRANSPORT__").join(p.transport)
+    .split("__DEV_V__").join(String(p.v))
+
+/** The dev.js placeholder-screen source with the project name baked in (as a JS string literal). */
+export const renderDevScreen = (name: string): string =>
+  DEV_SCREEN_TS.split("__DEV_NAME__").join(JSON.stringify(name))