lecodes-cli 0.20.2 → 2.0.0

package/src/commands/dev.ts

@@ -2,31 +2,51 @@ import { existsSync, mkdirSync, readFileSync, watch, writeFileSync, type FSWatch
 import { randomBytes } from "node:crypto"
 import { networkInterfaces } from "node:os"
 import { basename, join } from "node:path"
-import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../manifest"
-import { loadIgnore } from "../ignore"
+import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../project/manifest"
+import { loadIgnore } from "../project/ignore"
 import { startDevServer } from "../dev/devServer"
-import { resolveWebRunnerDir } from "../dev/webRunner"
-import { openBrowser } from "../browserAuth"
-import { runDesktopDev } from "../desktopRenderer"
+import { resolveWebRunner } from "../dev/webRunner"
+import { openBrowser } from "../platform/browserAuth"
+import { runDesktopDev } from "../hosts/desktopRenderer"
 import { androidCrashLines, launchOnAndroid, type AndroidDevSession } from "../dev/androidDev"
-import { readAppConfigAt } from "./appShared"
+import { launchOnIos, type IosDevSession } from "../dev/iosDev"
+import { readAppConfigAt } from "./app/shared"
 import { resolveScale } from "./desktop"
-import { CliError, c, flagBool, flagStr, log, note, toKey, warnErr, type Args } from "../util"
+import { CliError, bool, c, defineCommand, log, note, num, str, warnErr } from "../cli"
+import { bundleFlags } from "./shared"
+import { toKey } from "../project/paths"
 
 /*
  * `lecodes dev` — run the project on a device straight from this machine, with hot reload.
  *
  * Starts a LAN dev server (compile + assets + reload channel), prints a QR code, and watches the
  * working tree. The device opens the QR URL like any project URL; every save recompiles and
- * hot-swaps the running app (`_creatorUtils.run` — fresh context, rollback on error). Device
+ * hot-swaps the running app (`_creatorApp.run` — fresh context, rollback on error). Device
  * console output and errors stream back to this terminal. Fully local: no login, no le.codes
  * backend. Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
  * only when matc can't be fetched do they fall back to server-compiled artifacts (push once).
  *
- * `--web` opens the same project in the browser: the dev server also serves the Web Lite runner
- * (viewer-lite's dist-embed, vendored as runtime/web) under /web/ — CSS-flexbox UI + OGL 3D + the
- * web twins of the camera/map plugins, no wasm. Same bundle and hot reload; browser console
- * output streams back here like a device's. The URL is printed whenever the runner is available.
+ * `--web` opens the same project in the browser: the dev server also serves, under /web/, the
+ * app in a device (lecodes-web-frame's page: the device, the orientation, the console) around the
+ * web player (lecodes-web-player's dist — the runtime as wasm: Filament, creator-2d, the tree UI,
+ * and the web halves of the plugins). A phone that opens the url gets the player alone, the app
+ * filling its window. Same bundle and hot reload; the browser's console output streams back here
+ * like a device's. The URL is printed whenever the player is available.
+ *
+ * `--android` opens the dev URL in the LeCodes app on the phone plugged in over adb (adb reverse:
+ * no Wi-Fi/LAN address needed — see dev/androidDev.ts). With `--time <s>` the run is bounded —
+ * screenshot to --png, force-stop, exit — which is the shape a scripted check wants; without it
+ * the app runs until Ctrl+C, and Ctrl+C force-stops it (a device run has no frame cap, and a 3D
+ * scene left rendering heats a charging phone).
+ *
+ * `--ios` is the Apple twin (dev/iosDev.ts): the LeCodes app on a booted simulator or a plugged-in
+ * iPhone through `xcrun simctl` / `devicectl`, the url as a launch argument. Same `--time` / `--png`
+ * shape (screenshots on a simulator).
+ *
+ * `--desktop` opens the dev URL in the native host too (same server, same hot reload — the host
+ * speaks the websocket channel). The window closing does NOT stop the server: phones stay
+ * connected, and re-running with --desktop is the reopen. Host errors degrade to a warning — the
+ * QR path must keep working.
  *
  * Works inside a cloned project or standalone in any folder with an entry .ts file.
  * The desktop host speaks websocket since 1.0.0 (host_ws); `?t=poll` remains the fallback
@@ -54,7 +74,7 @@ const WATCH_SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore"
  */
 const VIRTUAL_IFACE = /wsl|docker|hyper-v|vethernet|virtualbox|vmware|tap|tun|zerotier|tailscale|loopback/i
 
-const lanCandidates = (): { address: string, iface: string }[] => {
+export const lanCandidates = (): { address: string, iface: string }[] => {
   const nets = networkInterfaces()
   const out: { address: string, iface: string, rank: number }[] = []
   for (const iface of Object.keys(nets)) {
@@ -94,185 +114,243 @@ const printQr = async (url: string) => {
   }
 }
 
-export const dev = async (args: Args) => {
-  // Inside a cloned project the server runs at its root; anywhere else it runs standalone against
-  // the current directory (no login / manifest needed) — same rule as `lecodes design`.
-  let root: string
-  let manifest: Manifest | null
-  try {
-    root = findProjectRoot(process.cwd())
-    manifest = readManifest(root)
-  } catch {
-    root = process.cwd()
-    manifest = null
-  }
-  const name = manifest?.name ?? basename(root)
-
-  // Bun's node:http can't complete a websocket upgrade (writes to the upgraded socket are dropped),
-  // so the reload push would silently never reach devices. Node is the shipped runtime.
-  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") {
-    warnErr("Running under Bun: the websocket reload channel doesn't work here — run `lecodes dev` with Node (or use ?t=poll on the device URL).")
-  }
+export default defineCommand({
+  name: "dev",
+  summary: "Run the project on a device / the desktop / the browser from this machine, with hot reload",
+  description: "Starts a LAN dev server + prints a QR code; scan it with the LeCodes app. Saves recompile + hot-swap the running app; device logs/errors stream back here. No login needed. The /web/ URL (the web player) is served always; --web, --android and --desktop each also open the app on that host.",
+  flags: {
+    port: num("server port", { default: DEFAULT_PORT }),
+    host: str("LAN address to advertise (default: auto-detect)", { value: "<ip>" }),
+    entry: bundleFlags.entry,
+    "no-qr": bool("don't render the QR code"),
+    android: bool("open the dev url in the LeCodes app on the phone plugged in over adb (adb reverse: no Wi-Fi/LAN address needed); device logs stream here; Ctrl+C force-stops the app"),
+    serial: str("(--android) the device to use", { value: "<id>" }),
+    apk: str("(--android) install this build first", { value: "<file>" }),
+    package: str("(--android) the app's package (default com.letary.lecodes)", { value: "<name>" }),
+    time: num("(--android | --ios) bounded check: screenshot after this many seconds, force-stop, exit (exit 1 on a crash)", { value: "<s>" }),
+    png: str("(--android | --ios, with --time) where the device screenshot goes", { value: "<file>" }),
+    ios: bool("open the dev url in the LeCodes app on a booted simulator or a plugged-in iPhone (Mac + Xcode: simctl / devicectl); a simulator gets the 127.0.0.1 url, a phone the LAN url; Ctrl+C terminates the app"),
+    udid: str("(--ios) the simulator (udid or name) or device (udid or name) to use", { value: "<id>" }),
+    app: str("(--ios) install this LeCodesApp.app first", { value: "<dir>" }),
+    bundle: str("(--ios) the app's bundle id (default com.letary.lecodes)", { value: "<id>" }),
+    web: bool("also open the app in the browser (the web player in a device: same bundle + hot reload, the console)"),
+    desktop: bool("also open the app in the native desktop host (same hot reload; window from app.json's desktop block; closing it keeps the server)"),
+    fps: bool("(--desktop) draw the host's frame counter"),
+  },
+  examples: ["lecodes dev", "lecodes dev --web", "lecodes dev --android --time 12 --png phone.png", "lecodes dev --ios --time 12 --png sim.png", "lecodes dev --desktop --fps"],
+  run: async ({ flags }) => {
+    // Inside a cloned project the server runs at its root; anywhere else it runs standalone against
+    // the current directory (no login / manifest needed) — same rule as `lecodes design`.
+    let root: string
+    let manifest: Manifest | null
+    try {
+      root = findProjectRoot(process.cwd())
+      manifest = readManifest(root)
+    } catch {
+      root = process.cwd()
+      manifest = null
+    }
+    const name = manifest?.name ?? basename(root)
 
-  const port = Number(flagStr(args, "port")) || DEFAULT_PORT
-  const candidates = lanCandidates()
-  const host = flagStr(args, "host") ?? candidates[0]?.address
-  if (!host) throw new CliError("No LAN address found — pass one with --host <ip>.")
-  // A machine with several NICs can only be disambiguated by the human: name the runners-up so a
-  // device that can't reach the printed URL is one --host away from working, not a debugging session.
-  const alternatives = candidates.filter((c) => c.address !== host)
-  const origin = `http://${host}:${port}`
-  const token = loadDevToken(root)
+    // Bun's node:http can't complete a websocket upgrade (writes to the upgraded socket are dropped),
+    // so the reload push would silently never reach devices: a phone that scanned a websocket url
+    // sat on "Connected — loading the project…" forever. Under Bun every device url — the QR, the
+    // printed one, what --ios / --android open — is the POLL form (/dev-poll.js: a path, since the
+    // launcher only fetches urls that end in .js). Node is the shipped runtime.
+    const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
+    if (underBun) {
+      warnErr("Running under Bun: no websocket reload channel here — devices poll instead (the QR points at /dev-poll.js). Node is the shipped runtime.")
+    }
 
-  const webDir = resolveWebRunnerDir()
-  if (flagBool(args, "web") && !webDir) {
-    throw new CliError("No Web Lite runner found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build:embed` in packages/viewer-lite).")
-  }
-  const server = await startDevServer({
-    root, manifest, name, origin, port, token,
-    entryOverride: flagStr(args, "entry"),
-    webDir,
-    log: note,
-  }).catch((e: unknown) => {
-    const msg = e instanceof Error ? e.message : String(e)
-    throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
-  })
+    const port = flags.port || DEFAULT_PORT
+    const candidates = lanCandidates()
+    const host = flags.host ?? candidates[0]?.address
+    if (!host) throw new CliError("No LAN address found — pass one with --host <ip>.")
+    // A machine with several NICs can only be disambiguated by the human: name the runners-up so a
+    // device that can't reach the printed URL is one --host away from working, not a debugging session.
+    const alternatives = candidates.filter((c) => c.address !== host)
+    const origin = `http://${host}:${port}`
+    const token = loadDevToken(root)
 
-  note("Compiling…")
-  const first = await server.recompile()
-  if (first.ok) {
-    for (const w of first.warnings) warnErr(w)
-  } else {
-    warnErr(`Compile failed — fix it and save; devices connect once it compiles:\n${first.error}`)
-  }
+    const web = resolveWebRunner(note)
+    if (flags.web && !web) {
+      throw new CliError("No web player found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build` in hosts/web-player).")
+    }
+    const server = await startDevServer({
+      root, manifest, name, origin, port, token,
+      entryOverride: flags.entry,
+      web,
+      log: note,
+    }).catch((e: unknown) => {
+      const msg = e instanceof Error ? e.message : String(e)
+      throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
+    })
 
-  // ---- watcher: debounced whole-project recompile; a successful compile broadcasts the reload ----
-  const ignore = loadIgnore(root)
-  const shouldRecompile = (file: string | null): boolean => {
-    if (file === null) return true // event without a filename — assume project content
-    const parts = file.replace(/\\/g, "/").split("/")
-    if (parts.some((p) => WATCH_SKIP_DIRS.has(p))) return false
-    if (WATCH_SKIP_FILES.has(parts[parts.length - 1])) return false
-    try {
-      const key = toKey(file)
-      if (ignore(key, false)) return false
-    } catch { return false }
-    return true
-  }
+    note("Compiling…")
+    const first = await server.recompile()
+    if (first.ok) {
+      for (const w of first.warnings) warnErr(w)
+    } else {
+      warnErr(`Compile failed — fix it and save; devices connect once it compiles:\n${first.error}`)
+    }
 
-  const debug = process.env.LECODES_DEV_DEBUG === "1"
-  const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
-  let timer: NodeJS.Timeout | null = null
-  const onChange = (file: string | null) => {
-    if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
-    if (!shouldRecompile(file)) return
-    if (timer) clearTimeout(timer)
-    timer = setTimeout(async () => {
-      timer = null
-      const result = await server.recompile()
-      if (!result.ok) {
-        warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
-      } else if (result.changed) {
-        const devices = server.clientCount()
-        note(`✓ v${result.v} → ${devices} device${devices === 1 ? "" : "s"}`)
-        for (const w of result.warnings) warnErr(w)
-      }
-    }, DEBOUNCE_MS)
-  }
+    // ---- watcher: debounced whole-project recompile; a successful compile broadcasts the reload ----
+    const ignore = loadIgnore(root)
+    const shouldRecompile = (file: string | null): boolean => {
+      if (file === null) return true // event without a filename — assume project content
+      const parts = file.replace(/\\/g, "/").split("/")
+      if (parts.some((p) => WATCH_SKIP_DIRS.has(p))) return false
+      if (WATCH_SKIP_FILES.has(parts[parts.length - 1])) return false
+      try {
+        const key = toKey(file)
+        if (ignore(key, false)) return false
+      } catch { return false }
+      return true
+    }
 
-  let watcher: FSWatcher | null = null
-  try {
-    watcher = watch(root, { recursive: true }, (_type, file) => onChange(file))
-  } catch {
-    warnErr("fs.watch(recursive) unavailable on this platform — hot reload disabled (restart to pick up changes).")
-  }
-  watcher?.on("error", (e) => warnErr(`Watcher error — hot reload may have stopped (restart lecodes dev): ${e.message}`))
+    const debug = process.env.LECODES_DEV_DEBUG === "1"
+    let timer: NodeJS.Timeout | null = null
+    const onChange = (file: string | null) => {
+      if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
+      if (!shouldRecompile(file)) return
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(async () => {
+        timer = null
+        const result = await server.recompile()
+        if (!result.ok) {
+          warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
+        } else if (result.changed) {
+          const devices = server.clientCount()
+          note(`✓ v${result.v} → ${devices} device${devices === 1 ? "" : "s"}`)
+          for (const w of result.warnings) warnErr(w)
+        }
+      }, DEBOUNCE_MS)
+    }
 
-  // ---- banner ------------------------------------------------------------------------------------
-  log("")
-  log(`${c.bold("LeCodes Dev")} — ${name}`)
-  log("")
-  if (!flagBool(args, "no-qr")) await printQr(server.url)
-  log(`Scan the QR with the LeCodes app, or open:  ${c.bold(server.url)}`)
-  // The browser runner: localhost is a secure context (camera works there), the LAN address is
-  // what a phone's browser can reach.
-  const webLocal = server.webUrl ? server.webUrl.replace(`http://${host}:`, "http://localhost:") : null
-  if (server.webUrl && webLocal) log(`In the browser (Web Lite):                  ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
-  note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
-  if (alternatives.length > 0) {
-    note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
-  }
-  if (existsSync(join(root, LECODES_DIR, "manifest.json"))) note(`Token stored in ${LECODES_DIR}/dev.json (delete it to rotate the URL).`)
-  log("")
-  log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`)
+    let watcher: FSWatcher | null = null
+    try {
+      watcher = watch(root, { recursive: true }, (_type, file) => onChange(file))
+    } catch {
+      warnErr("fs.watch(recursive) unavailable on this platform — hot reload disabled (restart to pick up changes).")
+    }
+    watcher?.on("error", (e) => warnErr(`Watcher error — hot reload may have stopped (restart lecodes dev): ${e.message}`))
 
-  // --web: open the browser runner (the server keeps serving it either way).
-  if (flagBool(args, "web") && webLocal) {
-    note("Opening the browser…")
-    openBrowser(webLocal)
-  }
+    // ---- banner ------------------------------------------------------------------------------------
+    log("")
+    log(`${c.bold("LeCodes Dev")} — ${name}`)
+    log("")
+    // The url a device opens: the websocket form, or the poll form under Bun (see above).
+    const deviceUrl = underBun ? server.url.replace(/\/dev\.js$/, "/dev-poll.js") : server.url
+    if (!flags["no-qr"]) await printQr(deviceUrl)
+    log(`Scan the QR with the LeCodes app, or open:  ${c.bold(deviceUrl)}`)
+    // The browser runner: localhost is a secure context (camera works there), the LAN address is
+    // what a phone's browser can reach.
+    const webLocal = server.webUrl ? server.webUrl.replace(`http://${host}:`, "http://localhost:") : null
+    if (server.webUrl && webLocal) log(`In the browser:                             ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
+    if (!underBun) note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
+    if (alternatives.length > 0) {
+      note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
+    }
+    if (existsSync(join(root, LECODES_DIR, "manifest.json"))) note(`Token stored in ${LECODES_DIR}/dev.json (delete it to rotate the URL).`)
+    log("")
+    log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`)
 
-  // --android: open the dev URL in the LeCodes app on the phone (adb; see dev/androidDev.ts). With
-  // --time <s> the run is bounded — screenshot to --png, force-stop, exit — which is the shape a
-  // scripted check wants; without it the app runs until Ctrl+C, and Ctrl+C force-stops it (a
-  // device run has no frame cap, and a 3D scene left rendering heats a charging phone).
-  if (flagBool(args, "android")) {
-    const seconds = Number(flagStr(args, "time")) || 0
-    const png = flagStr(args, "png")
-    // Under Bun the websocket channel never delivers (see the warning above): the phone would sit on
-    // "Connected — loading the project…" forever. The path-form poll url works on both runtimes.
-    const deviceUrl = `http://127.0.0.1:${port}${server.url.slice(origin.length)}`.replace(/\/dev\.js$/, underBun ? "/dev-poll.js" : "/dev.js")
-    let session: AndroidDevSession
-    try {
-      session = launchOnAndroid({ port, url: deviceUrl, serial: flagStr(args, "serial"), apk: flagStr(args, "apk"), packageName: flagStr(args, "package") })
-    } catch (e) {
-      server.close(); watcher?.close()
-      throw e
+    // --web: open the browser runner (the server keeps serving it either way).
+    if (flags.web && webLocal) {
+      note("Opening the browser…")
+      openBrowser(webLocal)
     }
-    note(`Android: ${session.serial} → ${deviceUrl} (adb reverse; device logs stream here as [device:log])`)
-    const finish = (code: number) => {
-      session.stop()
-      server.close(); watcher?.close()
-      process.exit(code)
+
+    if (flags.android) {
+      const seconds = flags.time ?? 0
+      const png = flags.png
+      // adb reverse: the phone reaches the server through its own loopback.
+      const androidUrl = `http://127.0.0.1:${port}${deviceUrl.slice(origin.length)}`
+      let session: AndroidDevSession
+      try {
+        session = launchOnAndroid({ port, url: androidUrl, serial: flags.serial, apk: flags.apk, packageName: flags.package })
+      } catch (e) {
+        server.close(); watcher?.close()
+        throw e
+      }
+      note(`Android: ${session.serial} → ${androidUrl} (adb reverse; device logs stream here as [device:log])`)
+      const finish = (code: number) => {
+        session.stop()
+        server.close(); watcher?.close()
+        process.exit(code)
+      }
+      process.on("SIGINT", () => { note("Stopping the app on the phone…"); finish(0) })
+      if (seconds > 0) {
+        setTimeout(() => {
+          const crashes = androidCrashLines(session)
+          if (png) {
+            if (session.screenshot(png)) note(`Wrote ${png} (device screenshot after ${seconds} s)`)
+            else warnErr(`Screenshot failed (adb screencap).`)
+          }
+          if (crashes.length > 0) {
+            warnErr(`The app crashed on the phone:\n${crashes.join("\n")}`)
+            finish(1)
+          }
+          finish(0)
+        }, seconds * 1000)
+      }
     }
-    process.on("SIGINT", () => { note("Stopping the app on the phone…"); finish(0) })
-    if (seconds > 0) {
-      setTimeout(() => {
-        const crashes = androidCrashLines(session)
-        if (png) {
-          if (session.screenshot(png)) note(`Wrote ${png} (device screenshot after ${seconds} s)`)
-          else warnErr(`Screenshot failed (adb screencap).`)
-        }
-        if (crashes.length > 0) {
-          warnErr(`The app crashed on the phone:\n${crashes.join("\n")}`)
-          finish(1)
-        }
-        finish(0)
-      }, seconds * 1000)
+
+    if (flags.ios) {
+      const seconds = flags.time ?? 0
+      const png = flags.png
+      // A simulator shares the Mac's network: the loopback url, no Wi-Fi involved. A phone gets the
+      // LAN url the QR shows.
+      const path = deviceUrl.slice(origin.length)
+      let session: IosDevSession
+      try {
+        session = launchOnIos({ simulatorUrl: `http://127.0.0.1:${port}${path}`, deviceUrl, udid: flags.udid, app: flags.app, bundleId: flags.bundle })
+      } catch (e) {
+        server.close(); watcher?.close()
+        throw e
+      }
+      note(`iOS: ${session.name} → ${session.kind === "simulator" ? `http://127.0.0.1:${port}${path}` : deviceUrl} (device logs stream here as [device:log])`)
+      const finish = (code: number) => {
+        session.stop()
+        server.close(); watcher?.close()
+        process.exit(code)
+      }
+      process.on("SIGINT", () => { note(`Stopping the app on ${session.name}…`); finish(0) })
+      if (seconds > 0) {
+        setTimeout(() => {
+          const crashes = session.crashLines()
+          if (png) {
+            if (session.screenshot(png)) note(`Wrote ${png} (screenshot after ${seconds} s)`)
+            else warnErr(session.kind === "simulator" ? "Screenshot failed (simctl io screenshot)." : "Screenshots need a simulator (no capture channel to a phone).")
+          }
+          if (crashes.length > 0) {
+            warnErr(`The app crashed:\n${crashes.join("\n")}`)
+            finish(1)
+          }
+          finish(0)
+        }, seconds * 1000)
+      }
     }
-  }
 
-  // --desktop: open the dev URL in the native host too (same server, same hot reload — the host
-  // speaks the websocket channel). Window config comes from app.json's desktop block. The window
-  // closing does NOT stop the server: phones stay connected, and re-running with --desktop is the
-  // reopen. Errors (host not downloadable, unsupported OS) degrade to a warning — the QR path
-  // must keep working.
-  if (flagBool(args, "desktop")) {
-    const appCfg = readAppConfigAt(root)
-    const win = appCfg?.desktop?.window
-    note("Opening LeCodes Desktop against the dev server…")
-    // scale IS forwarded (density changes how the app looks — dev should match production);
-    // fullscreen deliberately is NOT (a fullscreen dev window hides the terminal).
-    void runDesktopDev(server.url, {
-      width: win?.width, height: win?.height,
-      minWidth: win?.minWidth, minHeight: win?.minHeight,
-      resizable: win?.resizable,
-      title: win?.title ?? appCfg?.name ?? name,
-      scale: resolveScale(undefined, win?.scale),
-      fps: flagBool(args, "fps"),
-    }).then(
-      () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),
-      (e: unknown) => warnErr(`Desktop host: ${e instanceof Error ? e.message : String(e)}`),
-    )
-  }
-}
+    if (flags.desktop) {
+      const appCfg = readAppConfigAt(root)
+      const win = appCfg?.desktop?.window
+      note("Opening LeCodes Desktop against the dev server…")
+      // scale IS forwarded (density changes how the app looks — dev should match production);
+      // fullscreen deliberately is NOT (a fullscreen dev window hides the terminal).
+      void runDesktopDev(server.url, {
+        width: win?.width, height: win?.height,
+        minWidth: win?.minWidth, minHeight: win?.minHeight,
+        resizable: win?.resizable,
+        title: win?.title ?? appCfg?.name ?? name,
+        scale: resolveScale(undefined, win?.scale),
+        // The frame-rate cap is forwarded too: it changes how the game FEELS, and dev should match production.
+        frameRate: appCfg?.desktop?.frameRate,
+        fps: flags.fps,
+      }).then(
+        () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),
+        (e: unknown) => warnErr(`Desktop host: ${e instanceof Error ? e.message : String(e)}`),
+      )
+    }
+  },
+})

package/src/commands/diff.ts

@@ -1,59 +1,47 @@
-import { getProject } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest } from "../manifest"
-import { scanProject } from "../localFiles"
-import { computeServerDiff, type ServerDiffEntry } from "../serverDiff"
-import { unifiedDiff } from "../textDiff"
-import { c, info, log, flagBool, toKey, type Args } from "../util"
+import { bool, c, defineCommand, info, log } from "../cli"
+import { getProject } from "../platform/api"
+import { computeServerDiff, type ServerDiffEntry } from "../platform/serverDiff"
+import { scanProject } from "../project/localFiles"
+import { toKey } from "../project/paths"
+import { unifiedDiff } from "../project/textDiff"
+import { linkedProject } from "./shared"
 
 /*
- * `lecodes diff [path…]` — compare the local working tree against the project's CURRENT server state
- * and print a unified diff. The "+" side is local, the "-" side is the server, so it answers "what
- * would my push change?" — including any edits made on the server (e.g. in the web editor) since you
- * cloned. The headline use is conflict resolution before `push --force`.
- *
- *   --name-only   list changed paths + status instead of full diffs
- *   [path…]       limit to these files / folders
+ * `lecodes diff [path…]` — the local working tree against the project's CURRENT server state as a
+ * unified diff. "+" is local, "-" is the server, so it answers "what would my push change?" —
+ * including edits made on the server (the web editor) since the clone. The headline use is
+ * conflict resolution before `push --force`.
  */
-export const diff = async (args: Args) => {
-  const root = findProjectRoot(process.cwd())
-  const manifest = readManifest(root)
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
+export default defineCommand({
+  name: "diff",
+  summary: "Show a unified diff of local vs the current server state",
+  usage: "[path…]",
+  flags: { "name-only": bool("list changed paths + status only") },
+  run: async ({ args, flags }) => {
+    const { root, manifest, apiUrl, token } = linkedProject()
+    info(c.dim("Comparing with the server…"))
+    const project = await getProject(apiUrl, token, manifest.uuid)
+    const scan = scanProject(root, manifest)
+    let entries = computeServerDiff(project, scan)
 
-  info(c.dim("Comparing with the server…"))
-  const project = await getProject(apiUrl, token, manifest.uuid)
-  const scan = scanProject(root, manifest)
-  let entries = computeServerDiff(project, scan)
-
-  // Optional path filter (a file, or a folder prefix).
-  if (args._.length > 0) {
-    const keys = args._.map(toKey)
-    entries = entries.filter(e => keys.some(k => e.path === k || e.path.startsWith(k + "/")))
-  }
-
-  if (entries.length === 0) {
-    info(c.dim("No differences between local and server."))
-    return
-  }
-
-  if (flagBool(args, "name-only")) {
-    for (const e of entries) log(statusLabel(e) + e.path + (e.binary ? c.dim(" (binary)") : ""))
-    return
-  }
+    // Optional path filter (a file, or a folder prefix).
+    if (args.length > 0) {
+      const keys = args.map(toKey)
+      entries = entries.filter(e => keys.some(k => e.path === k || e.path.startsWith(k + "/")))
+    }
+    if (entries.length === 0) { info(c.dim("No differences between local and server.")); return }
 
-  for (const e of entries) {
-    if (e.binary) {
-      log(statusLabel(e) + e.path + c.dim(" (binary — content not shown)"))
-      continue
+    if (flags["name-only"]) {
+      for (const e of entries) log(statusLabel(e) + e.path + (e.binary ? c.dim(" (binary)") : ""))
+      return
+    }
+    for (const e of entries) {
+      if (e.binary) { log(statusLabel(e) + e.path + c.dim(" (binary — content not shown)")); continue }
+      const d = unifiedDiff(e.serverText ?? "", e.localText ?? "", `server${e.path}`, `local${e.path}`)
+      if (d) log("\n" + d)
     }
-    const d = unifiedDiff(e.serverText ?? "", e.localText ?? "", `server${e.path}`, `local${e.path}`)
-    if (d) log("\n" + d)
-  }
-}
+  },
+})
 
 const statusLabel = (e: ServerDiffEntry): string =>
-  e.status === "added" ? c.green("  added    ")
-    : e.status === "removed" ? c.red("  removed  ")
-    : c.yellow("  modified ")
+  e.status === "added" ? c.green("  added    ") : e.status === "removed" ? c.red("  removed  ") : c.yellow("  modified ")