lecodes-cli 0.20.0 → 0.20.1

package/src/commands/update.ts

@@ -4,7 +4,8 @@ import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import pkg from "../../package.json"
 import { CliError, c, flagBool, log, note, type Args } from "../util"
-import { OPTIONAL_PEERS, peerVersion } from "../peers"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "../peers"
+import { installPeers } from "../peerInstall"
 import { updateDesktop } from "../desktopRenderer"
 import { updateMatc } from "../matcTool"
 import { types } from "./types"
@@ -20,10 +21,12 @@ import { app } from "./app"
  *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
  *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (= `types`)
  *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
- *   6. cli       the GLOBAL npm installs — every installed optional peer (lecodes-renderer,
- *                lecodes-design, lecodes-3d-editor, lecodes-assets) and the CLI itself that is behind
- *                npm's latest: `npm install -g …@latest` (peers first, the CLI last; the standalone
- *                binary can't come from npm — it says so and does the peers only)
+ *   6. cli       the npm installs — every installed optional peer (lecodes-renderer, lecodes-design,
+ *                lecodes-3d-editor, lecodes-assets, @napi-rs/canvas) and the CLI itself that is behind:
+ *                peers in ~/.lecodes/peers (first-use installs, peerInstall.ts) are re-installed there
+ *                — the renderer at THIS CLI's version, the rest at npm's latest in range; global ones
+ *                (`npm install -g`, the old way) via `npm install -g …@latest`; the CLI itself last
+ *                (the standalone binary can't come from npm — it says so and does the peers only)
  *
  * Every step is the existing subcommand, so nothing here can drift from what the individual
  * commands do; this only sequences them and keeps going when one fails (the summary says which).
@@ -148,35 +151,53 @@ export const update = async (args: Args) => {
   await run("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
     if (flagBool(args, "no-cli")) return ["skipped", "--no-cli"]
     if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
-    const rows: { name: string, installed: string | null, latest: string | null }[] = []
+    // Where each peer lives decides how it moves: the CLI's own prefix (~/.lecodes/peers, filled on
+    // first use) is re-installed by peerInstall — the renderer there tracks THIS CLI's version, not
+    // npm's latest, because compiler and headless host are one ABI set; a global install
+    // (`npm install -g`, the old way) moves through npm like before.
+    const rows: { name: string, installed: string | null, latest: string | null, where: "global" | "prefix" | null }[] = []
     for (const [name, probe] of OPTIONAL_PEERS) {
+      const where = peerSource(name, probe)
       const installed = peerVersion(name, probe)
-      rows.push({ name, installed, latest: installed ? await npmLatest(name) : null })
+      const latest = !installed ? null
+        : where === "prefix" && name === "lecodes-renderer" ? pkg.version
+        : await npmLatest(name)
+      rows.push({ name, installed, latest, where })
     }
-    rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli") })
+    rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli"), where: "global" })
     if (rows.every((r) => r.latest === null)) return ["skipped", "npm unreachable"]
     const behind = rows.filter((r) => r.installed && r.latest && semverNewer(r.latest, r.installed) > 0)
     for (const r of rows) {
-      const state = !r.installed ? c.dim("not installed (optional — npm install -g " + r.name + ")")
+      const state = !r.installed ? c.dim("not installed (optional — installed on first use)")
         : !r.latest ? c.dim("(npm: unknown)")
         : behind.includes(r) ? c.yellow("→ " + r.latest)
         : c.dim("(up to date)")
-      log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + state)
+      log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + (r.where === "prefix" ? c.dim("peers ") : "") + state)
     }
     if (behind.length === 0) return "ok"
-    const specs = behind.map((r) => r.name + "@latest")
-    if (flagBool(args, "check")) return ["updated", behind.length + " behind — run: npm install -g " + specs.join(" ")]
-    if (STANDALONE && behind.some((r) => r.name === "lecodes-cli")) {
+    const prefixBehind = behind.filter((r) => r.where === "prefix")
+    const globalSpecs = behind.filter((r) => r.where !== "prefix").map((r) => r.name + "@latest")
+    if (flagBool(args, "check")) {
+      return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")]
+    }
+    const done: string[] = []
+    if (prefixBehind.length) {
+      await installPeers(prefixBehind.map((r) => r.name), "lecodes update", { yes: true })
+      done.push(...prefixBehind.map((r) => r.name))
+    }
+    if (STANDALONE && globalSpecs.some((s) => s.startsWith("lecodes-cli@"))) {
       note("this is the standalone build — the CLI updates by re-installing the release archive, not through npm; peers still go through npm")
     }
-    const toInstall = STANDALONE ? specs.filter((s) => !s.startsWith("lecodes-cli@")) : specs
-    if (toInstall.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
-    log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
-    const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
-    if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
-    const names = toInstall.map((s) => s.replace("@latest", "")).join(", ")
-    const cliToo = toInstall.some((s) => s.startsWith("lecodes-cli@"))
-    return ["updated", names + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
+    const toInstall = STANDALONE ? globalSpecs.filter((s) => !s.startsWith("lecodes-cli@")) : globalSpecs
+    if (toInstall.length) {
+      log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
+      const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
+      if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
+      done.push(...toInstall.map((s) => s.replace("@latest", "")))
+    }
+    if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
+    const cliToo = done.includes("lecodes-cli")
+    return ["updated", done.join(", ") + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
   })
 
   // Summary — one line per step so a scrolled-away failure can't hide.

package/src/desktopRenderer.ts

@@ -284,6 +284,10 @@ export type DesktopWindowOpts = {
   minHeight?: number
   resizable?: boolean
   title?: string
+  /** localStorage scope (CREATOR_STORAGE_SCOPE, host ≥1.5.0): the app's stable identity — app.json
+   *  `name` — so a `desktop run` keeps its saved state across runs (the host would otherwise key the
+   *  storage by the launch path, which is a fresh temp dir every run). */
+  storageScope?: string
   /** Borderless fullscreen on the primary monitor (host ≥1.3.0; older hosts ignore the env). */
   fullscreen?: boolean
   /** Display scale: a fixed density (0.5–4) or "fit" (derive from design frame vs monitor/work
@@ -293,6 +297,12 @@ export type DesktopWindowOpts = {
   renderScale?: number
   /** 3D buffer cap [W, H] in px (host ≥1.4.0) — e.g. [1920, 1080] keeps a 4K fullscreen at 1080p 3D. */
   maxRenderSize?: [number, number]
+  /** The mouse button acts as a finger — click-drag scrolls/flings like touch (CREATOR_MOUSE_TOUCH;
+   *  every host reads the env). A CREATOR_MOUSE_TOUCH already in the environment (shell / .env) wins. */
+  mouseEmulateTouch?: boolean
+  /** On-screen keyboard for every input (app.json desktop.virtualKeyboard, host ≥1.5.5): `true` or
+   *  the block, forwarded verbatim as CREATOR_VIRTUAL_KEYBOARD JSON. A set env wins, like the mouse knob. */
+  virtualKeyboard?: boolean | object
   /** Draw the host's frame counter in the corner (host ≥1.5.0; older hosts ignore the env). Costs
    *  nothing to leave off and next to nothing on — the digits are rectangles, no UI behind them. */
   fps?: boolean
@@ -319,6 +329,7 @@ const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
   if (width && height) env.CREATOR_WINDOW_SIZE = `${width}x${height}`
   if (opts.minWidth && opts.minHeight) env.CREATOR_MIN_WINDOW_SIZE = `${opts.minWidth}x${opts.minHeight}`
   if (opts.title) env.CREATOR_WINDOW_TITLE = opts.title
+  if (opts.storageScope) env.CREATOR_STORAGE_SCOPE = opts.storageScope
   if (opts.resizable === false) env.CREATOR_WINDOW_FIXED = "1"
   if (opts.fullscreen !== undefined) env.CREATOR_WINDOW_FULLSCREEN = opts.fullscreen ? "1" : "0"
   if (opts.scale === "fit") env.CREATOR_UI_SCALE = "fit"
@@ -328,6 +339,12 @@ const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
     env.CREATOR_RENDER_MAX = `${Math.round(opts.maxRenderSize[0])}x${Math.round(opts.maxRenderSize[1])}`
   }
   if (opts.fps) env.CREATOR_FPS = "1"
+  if (opts.mouseEmulateTouch !== undefined && process.env.CREATOR_MOUSE_TOUCH === undefined) {
+    env.CREATOR_MOUSE_TOUCH = opts.mouseEmulateTouch ? "1" : "0"
+  }
+  if (opts.virtualKeyboard !== undefined && process.env.CREATOR_VIRTUAL_KEYBOARD === undefined) {
+    env.CREATOR_VIRTUAL_KEYBOARD = typeof opts.virtualKeyboard === "boolean" ? (opts.virtualKeyboard ? "1" : "0") : JSON.stringify(opts.virtualKeyboard)
+  }
   return env
 }
 

package/src/desktopScript.ts

@@ -40,7 +40,7 @@ export type DesktopPlan = {
 }
 
 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 SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value", "audio"]
 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")
 

package/src/dev/androidDev.ts

@@ -0,0 +1,154 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import { CliError, note, warnErr } from "../util"
+
+/*
+ * `lecodes dev --android` — open the dev URL in the LeCodes app on the connected phone, through adb.
+ *
+ * Why adb instead of "scan the QR": the phone reaches this machine over `adb reverse` (its
+ * 127.0.0.1:<port> is our port), so it works over USB with no Wi-Fi, no LAN-address guessing
+ * (WSL/Docker/VPN adapters), no firewall prompt. The launch is an EXPLICIT component intent — the
+ * app's VIEW filter is pinned to le.codes/qr, and an explicit start bypasses filter matching — with
+ * the plain dev.js url: the app's initial.js only fetches a url that ends in ".js", anything else is
+ * sent to le.codes/api/code, which answers 400 for a dev bundle (the "Произошла ошибка при открытии
+ * проекта" screen). That is also why the poll transport is a PATH (/dev-poll.js), never `?t=poll`.
+ *
+ * A device run has no frame cap (unlike the desktop host), so every exit path force-stops the app:
+ * a 3D scene left rendering is a sustained GPU load on a charging phone.
+ */
+
+export const DEFAULT_ANDROID_PACKAGE = "com.letary.lecodes"
+
+export type AndroidDevOptions = {
+  port: number
+  /** The device-side url to open (with `adb reverse` in place, 127.0.0.1:<port> is this machine). */
+  url: string
+  serial?: string
+  apk?: string
+  packageName?: string
+}
+
+export type AndroidDevSession = {
+  serial: string
+  packageName: string
+  adb: string
+  /** `adb exec-out screencap -p` → the file. */
+  screenshot: (file: string) => boolean
+  /** force-stop the app + drop the reverse forward. Idempotent. */
+  stop: () => void
+}
+
+const adbCandidates = (): string[] => {
+  const out: string[] = []
+  if (process.env.LECODES_ADB) out.push(process.env.LECODES_ADB)
+  out.push("adb")
+  const exe = process.platform === "win32" ? "adb.exe" : "adb"
+  for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+    if (home) out.push(join(home, "platform-tools", exe))
+  }
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) out.push(join(process.env.LOCALAPPDATA, "Android", "Sdk", "platform-tools", exe))
+  if (process.env.HOME) out.push(join(process.env.HOME, "Android", "Sdk", "platform-tools", exe), join(process.env.HOME, "Library", "Android", "sdk", "platform-tools", exe))
+  return out
+}
+
+const run = (adb: string, args: string[], input?: string): { ok: boolean, out: string } => {
+  const r = spawnSync(adb, args, { encoding: "utf8", input, windowsHide: true, maxBuffer: 64 * 1024 * 1024 })
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim()
+  return { ok: r.status === 0, out }
+}
+
+/** The adb binary: LECODES_ADB, PATH, then the usual SDK locations. */
+export const resolveAdb = (): string => {
+  for (const cand of adbCandidates()) {
+    if (cand !== "adb" && !existsSync(cand)) continue
+    const r = spawnSync(cand, ["version"], { encoding: "utf8", windowsHide: true })
+    if (r.status === 0) return cand
+  }
+  throw new CliError("adb not found — install Android platform-tools (or point LECODES_ADB at adb).")
+}
+
+/** Connected devices in the `device` state (unauthorized/offline ones are reported, not used). */
+export const listDevices = (adb: string): { serial: string, state: string, model?: string }[] => {
+  const { out } = run(adb, ["devices", "-l"])
+  const devices: { serial: string, state: string, model?: string }[] = []
+  for (const line of out.split(/\r?\n/).slice(1)) {
+    const m = /^(\S+)\s+(\S+)(.*)$/.exec(line.trim())
+    if (!m) continue
+    const model = /model:(\S+)/.exec(m[3] ?? "")?.[1]
+    devices.push({ serial: m[1], state: m[2], model })
+  }
+  return devices
+}
+
+const pickDevice = (adb: string, serial: string | undefined): string => {
+  const all = listDevices(adb)
+  if (serial) {
+    const d = all.find((x) => x.serial === serial)
+    if (!d) throw new CliError(`No device "${serial}" — adb sees: ${all.map((x) => `${x.serial} (${x.state})`).join(", ") || "nothing"}.`)
+    if (d.state !== "device") throw new CliError(`Device ${serial} is "${d.state}" — accept the USB-debugging prompt on the phone.`)
+    return serial
+  }
+  const ready = all.filter((d) => d.state === "device")
+  if (ready.length === 1) return ready[0].serial
+  if (ready.length === 0) {
+    const other = all.map((d) => `${d.serial} (${d.state})`).join(", ")
+    throw new CliError(other
+      ? `No usable device: adb sees ${other}. "unauthorized" = accept the USB-debugging prompt on the phone; "offline" = replug.`
+      : "No Android device: enable USB debugging (Developer options), plug the phone in, accept the prompt — or `adb connect <ip>:5555` for Wi-Fi debugging.")
+  }
+  throw new CliError(`Several devices: ${ready.map((d) => `${d.serial}${d.model ? ` (${d.model})` : ""}`).join(", ")} — pick one with --serial <id>.`)
+}
+
+/** Install (optional), forward the port, launch the app on the dev url. Returns the session handle. */
+export const launchOnAndroid = (opts: AndroidDevOptions): AndroidDevSession => {
+  const adb = resolveAdb()
+  const serial = pickDevice(adb, opts.serial)
+  const packageName = opts.packageName ?? process.env.LECODES_ANDROID_PACKAGE ?? DEFAULT_ANDROID_PACKAGE
+  const dev = (args: string[]) => run(adb, ["-s", serial, ...args])
+
+  if (opts.apk) {
+    if (!existsSync(opts.apk)) throw new CliError(`--apk: ${opts.apk} does not exist.`)
+    note(`Installing ${opts.apk}…`)
+    const r = dev(["install", "-r", opts.apk])
+    if (!r.ok || !/Success/.test(r.out)) {
+      throw new CliError(`adb install failed: ${r.out}${/USER_RESTRICTED/.test(r.out) ? "\n(MIUI: enable \"Install via USB\" in Developer options.)" : ""}`)
+    }
+  }
+  const installed = dev(["shell", "pm", "path", packageName])
+  if (!installed.ok || !installed.out.includes("package:")) {
+    throw new CliError(`${packageName} is not installed on ${serial} — pass --apk <file> (lecodes-android: .\\gradlew :app:assembleDebug → app/build/outputs/apk/debug/app-debug.apk).`)
+  }
+
+  // The phone's 127.0.0.1:<port> → this machine's dev server. Survives Wi-Fi changes and VPNs.
+  const rev = dev(["reverse", `tcp:${opts.port}`, `tcp:${opts.port}`])
+  if (!rev.ok) warnErr(`adb reverse failed (${rev.out}) — the phone must reach the LAN url instead.`)
+
+  dev(["shell", "am", "force-stop", packageName])
+  dev(["logcat", "-c"])
+  const start = dev(["shell", "am", "start", "-n", `${packageName}/.MainActivity`, "-a", "android.intent.action.VIEW", "-d", opts.url])
+  if (!start.ok || /Error/.test(start.out)) throw new CliError(`Could not launch ${packageName}: ${start.out}`)
+
+  let stopped = false
+  return {
+    serial, packageName, adb,
+    screenshot: (file: string) => {
+      const r = spawnSync(adb, ["-s", serial, "exec-out", "screencap", "-p"], { windowsHide: true, maxBuffer: 64 * 1024 * 1024 })
+      if (r.status !== 0 || !r.stdout || r.stdout.length === 0) return false
+      writeFileSync(file, r.stdout)
+      return true
+    },
+    stop: () => {
+      if (stopped) return
+      stopped = true
+      dev(["shell", "am", "force-stop", packageName])
+      dev(["reverse", "--remove", `tcp:${opts.port}`])
+    },
+  }
+}
+
+/** Crash lines for the app since the launch (logcat was cleared then): the native + Java fatals. */
+export const androidCrashLines = (session: AndroidDevSession): string[] => {
+  const { out } = run(session.adb, ["-s", session.serial, "logcat", "-d", "-v", "brief"])
+  return out.split(/\r?\n/).filter((l) => /FATAL EXCEPTION|Fatal signal|\[crash\]/.test(l) || (/AndroidRuntime/.test(l) && l.includes(session.packageName))).slice(-20)
+}

package/src/dev/devServer.ts

@@ -195,8 +195,8 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const t = url.searchParams.get("t")
     return t === "poll" ? "poll" : t === "web" ? "web" : "ws"
   }
-  const withPrelude = (js: string, url: URL, v: number) => {
-    const transport = transportOf(url)
+  const withPrelude = (js: string, url: URL, v: number, forced?: "poll") => {
+    const transport = forced ?? transportOf(url)
     return transport === "web" ? js : js + "\n" + renderPrelude({ origin, base, transport, v })
   }
   const webDir = options.webDir ?? null
@@ -212,6 +212,12 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     if (route === "/dev.js") {
       return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1))
     }
+    // The poll transport as a PATH: the Android app's initial.js only fetches a launch url that ends
+    // in ".js" (anything else goes to le.codes/api/code), so `?t=poll` can't reach it. Same bundle,
+    // prelude polls instead of the websocket — what `dev --android` opens under Bun (no ws there).
+    if (route === "/dev-poll.js") {
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, "poll"))
+    }
     if (route === "/bundle.js") {
       if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
       res.setHeader("x-lecodes-v", String(v))   // the browser runner learns the version it runs

package/src/index.ts

@@ -31,7 +31,7 @@ import { CliError, c, log, parseArgs, type Args } from "./util"
 import { installedDesktopVersions, selectedDesktopVersion } from "./desktopRenderer"
 import { installedMatcVersions } from "./matcTool"
 import { loadProjectEnv } from "./projectEnv"
-import { OPTIONAL_PEERS, peerVersion } from "./peers"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "./peers"
 
 /* `install` is a standalone-binary-only command: it installs the shipped bundle onto PATH, so it's only
  * meaningful when that bundle actually sits next to the executable — the `chisel` bundler + `runtime/`
@@ -120,6 +120,14 @@ ${c.bold("Commands:")}
                                   --host <ip>     LAN address to advertise (default: auto-detect)
                                   --entry <path>  override the entrypoint
                                   --no-qr         don't render the QR code
+                                  --android       open the dev url in the LeCodes app on the phone
+                                                    plugged in over adb (adb reverse: no Wi-Fi/LAN
+                                                    address needed). --serial <id> picks a device,
+                                                    --apk <file> installs first, --package <name>
+                                                    (default com.letary.lecodes). Device logs stream
+                                                    here. --time <s> --png <file>: bounded check —
+                                                    screenshot after <s> seconds, force-stop, exit
+                                                    (exit 1 on a crash). Ctrl+C force-stops the app.
                                   --web           also open the app in the browser (Web Lite host:
                                                     same bundle + hot reload, camera/map plugins
                                                     have web twins; the /web/ URL is served always)
@@ -315,12 +323,15 @@ ${c.bold("Commands:")}
                                   --cell <m> (0.25)  --cell-height <m> (0.1)  --tile <cells> (48)
                                   --obj              also write <n>.navmesh.obj to inspect
                                   --frames <n>       load headroom (900) --logs  host output
-  shaders [compile|update]      The project's custom shaders (.mat) and their local compile:
+  shaders [compile|update|new]  The project's custom shaders (.mat) and their local compile:
                                   no args lists the shaders + their compile state; compile
                                   compiles them all into .lecodes/shaders (the same pass
                                   'lecodes dev' runs on the fly — via Filament's matc,
                                   downloaded on first use to ~/.lecodes/matc); update
-                                  downloads the newest matc (run after an engine upgrade)
+                                  downloads the newest matc (run after an engine upgrade);
+                                  new <name> [--ref lit] [--dir d] [--force] writes a fresh
+                                  .mat + .material.ts: the starter, or a copy of the engine's
+                                  own lit / unlit / particles / … source to start from
   scene [path]                  LeCodes Scene Editor — visually edit a .scene.ts (tree, inspector,
                                   gizmo) on local files (needs the optional 'lecodes-3d-editor' package;
                                   works inside a cloned project or standalone in any folder)
@@ -446,7 +457,10 @@ const printVersion = () => {
   const rows: [label: string, value: string][] = [["lecodes-cli", readVersion()]]
   for (const [name, probe] of OPTIONAL_PEERS) {
     const version = peerVersion(name, probe)
-    rows.push([name, version ?? c.dim("not installed")])
+    const where = peerSource(name, probe)
+    rows.push([name, version
+      ? (where === "prefix" ? `${version} ${c.dim("(~/.lecodes/peers)")}` : version)
+      : c.dim("not installed — installed on first use")])
   }
   const desktopVersion = selectedDesktopVersion()
   rows.push(["lecodes-desktop", installedDesktopVersions().includes(desktopVersion)
@@ -464,6 +478,9 @@ const main = async () => {
   // The project's .env (LECODES_* / CREATOR_* next to app.json) — before any command reads the
   // environment; the real environment keeps precedence. See projectEnv.ts.
   loadProjectEnv()
+  // `--yes` / `-y` anywhere on the line also pre-approves first-use installs of optional peers
+  // (peerInstall.ts) — the same knob LECODES_YES=1 gives CI.
+  if (argv.includes("--yes") || argv.includes("-y")) process.env.LECODES_YES = "1"
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     log(HELP)

package/src/matcTool.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
-import { downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
 import { CliError, note } from "./util"
 
 /*
@@ -16,8 +16,11 @@ import { CliError, note } from "./util"
  * hosts ship). Cache: ~/.lecodes/matc/matc-<version>/. LECODES_MATC overrides resolution entirely
  * (local dev: point it at packages/desktop/build/creator-gl/filament/tools/matc/matc.exe).
  *
- * No version pin: a filamat's compatibility is tied to the vendored Filament, which changes
- * rarely — resolution takes the newest cached copy, else downloads `latest`. `lecodes shaders
+ * No version pin: a filamat's compatibility is tied to the vendored Filament, which changes rarely —
+ * resolution takes the newest cached copy, else downloads the newest release PUBLISHED FOR THIS
+ * PLATFORM (releases.ts newestForPlatform), NOT the product's `latest`: a release only ships the
+ * platforms whose machine ran it, so `latest` is often Windows-only and every other platform would
+ * read "not published" with a perfectly good older build sitting right there. `lecodes shaders
  * update` moves an existing cache forward after an engine upgrade.
  *
  * Platforms: windows-x64, linux-x64, macos-arm64. On Windows/Linux matc rides the DESKTOP build
@@ -80,15 +83,21 @@ export const installedMatcVersions = (): string[] => {
 export const fetchMatcManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
   fetchReleaseProduct("matc", "matc (shader compiler)")
 
-const downloadMatc = async (version: string, versions: ManifestVersion[], dest: string): Promise<void> => {
+/** The published matc this platform should get: the newest version carrying a build for it (see
+ *  newestForPlatform — a release often ships one platform, so `latest` is the wrong question). */
+const pickMatc = (versions: ManifestVersion[]): { version: string, file: ManifestFile } => {
   const key = platformKey()
-  const file = versions.find((v) => v.version === version)?.files[key]
-  if (!file) {
+  const hit = newestForPlatform(versions, key)
+  if (!hit) {
     throw new CliError(
-      `matc ${version} [${key}] isn't published — push the project once so shaders compile on the ` +
+      `matc isn't published for ${key} — push the project once so shaders compile on the ` +
       `server, or set LECODES_MATC to a locally built matc.`,
     )
   }
+  return hit
+}
+
+const downloadMatc = async (version: string, file: ManifestFile, dest: string): Promise<void> => {
   note(`Downloading the shader compiler (matc ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
   await downloadReleaseArchive(file, {
     cacheRoot: cacheRoot(),
@@ -109,29 +118,32 @@ export const resolveMatcExeCached = (): string | null => {
   return cached ? findMatc(join(cacheRoot(), `matc-${cached}`)) : null
 }
 
-/** The matc binary: LECODES_MATC override → newest cached version → download the latest release.
- *  Throws CliError when unavailable (callers degrade to the push-once server-compile warning). */
+/** The matc binary: LECODES_MATC override → newest cached version → download the newest release
+ *  published for this platform. Throws CliError when unavailable (callers degrade to the push-once
+ *  server-compile warning). */
 export const resolveMatcExe = async (): Promise<string> => {
   const cached = resolveMatcExeCached()
   if (cached) return cached
-  const { latest, versions } = await fetchMatcManifest()
-  const dir = join(cacheRoot(), `matc-${latest}`)
-  await downloadMatc(latest, versions, dir)
+  const { versions } = await fetchMatcManifest()
+  const { version, file } = pickMatc(versions)
+  const dir = join(cacheRoot(), `matc-${version}`)
+  await downloadMatc(version, file, dir)
   const exe = findMatc(dir)
   if (!exe) throw new CliError(`matc cache at ${dir} is broken — delete the folder and retry.`)
   return exe
 }
 
-/** `lecodes shaders update`: download the newest published matc (cached versions stay; the newest
- *  wins resolution). Run it after an engine upgrade so local shader artifacts match the hosts. */
+/** `lecodes shaders update`: download the newest matc published for this platform (cached versions
+ *  stay; the newest wins resolution). Run it after an engine upgrade so local artifacts match the hosts. */
 export const updateMatc = async (): Promise<void> => {
-  const { latest, versions } = await fetchMatcManifest()
+  const { versions } = await fetchMatcManifest()
+  const { version, file } = pickMatc(versions)
   const before = installedMatcVersions()[0]
-  const dir = join(cacheRoot(), `matc-${latest}`)
+  const dir = join(cacheRoot(), `matc-${version}`)
   if (existsSync(dir) && findMatc(dir) !== null) {
-    note(`Already up to date: matc ${latest}.`)
+    note(`Already up to date: matc ${version}.`)
     return
   }
-  await downloadMatc(latest, versions, dir)
-  note(before ? `matc updated to ${latest} (was ${before}).` : `matc ${latest} installed.`)
+  await downloadMatc(version, file, dir)
+  note(before ? `matc updated to ${version} (was ${before}).` : `matc ${version} installed.`)
 }