lecodes-cli 0.20.2 → 2.0.0

package/src/commands/desktop.ts

@@ -1,26 +1,19 @@
 import { basename } from "node:path"
-import { CliError, c, flagBool, flagStr, log, note, type Args } from "../util"
-import { findProjectRoot } from "../manifest"
-import { buildBundle } from "./compile"
-import { assertRendererSupportsBundle, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
-import { buildDesktop } from "./appDesktop"
+import { CliError, bool, c, defineCommand, log, note, num, str } from "../cli"
 import {
-  DESKTOP_RENDERER_VERSION,
-  fetchDesktopManifest,
-  findMacHostExe,
-  installedDesktopVersions,
-  runDesktopApp,
-  selectedDesktopVersion,
-  semverNewer,
-  updateDesktop,
-} from "../desktopRenderer"
+  DESKTOP_RENDERER_VERSION, fetchDesktopManifest, findMacHostExe, installedDesktopVersions, runDesktopApp,
+  selectedDesktopVersion, semverNewer, updateDesktop,
+} from "../hosts/desktopRenderer"
+import { desktopBuild } from "./app/desktop"
+import { desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { buildBundle } from "./compile"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
 
 /*
- * `lecodes desktop` — everything about the desktop target in one place.
+ * `lecodes desktop` — the desktop target, the host `lecodes render --desktop` uses too.
  *   (no args)   status: the version renders use, what's cached, what's published
  *   run         compile the current project and open it in a real desktop window
- *   build       stage a portable app folder (the same command as `lecodes app build desktop`,
- *               which stays for symmetry with the ios/android shells)
+ *   build       stage a portable app folder (the same as `lecodes app build desktop`)
  *   update      move the host to the newest published release (downloads it if needed)
  * The binary cache lives in ~/.lecodes/renderer/; LECODES_DESKTOP_EXE overrides everything.
  */
@@ -32,9 +25,7 @@ export const resolveScale = (flag: string | undefined, cfg: number | "fit" | "sy
   if (raw === undefined || raw === "system") return undefined
   if (raw === "fit") return "fit"
   const n = Number(raw)
-  if (!Number.isFinite(n) || n < 0.5 || n > 4) {
-    throw new CliError(`scale must be a number 0.5..4, "fit" or "system" (got "${raw}")`)
-  }
+  if (!Number.isFinite(n) || n < 0.5 || n > 4) throw new CliError(`scale must be a number 0.5..4, "fit" or "system" (got "${raw}")`)
   return n
 }
 
@@ -46,55 +37,75 @@ export const resolveRenderScale = (flag: string | undefined, cfg: number | undef
   return n
 }
 
-const run = async (args: Args) => {
-  // Window defaults come from app.json's desktop block (flags win); standalone projects
-  // without an app.json keep the host's built-in 1280×720.
-  let root: string
-  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
-  const appCfg = readAppConfigAt(root)
-  const win = appCfg?.desktop?.window
-  // ONE renderer decision per run: it picks the host binary AND which .filamat gets staged beside
-  // the bundle. Reading the config twice is how a Vulkan exe ends up next to an OpenGL shader.
-  const renderer = resolveDesktopRenderer(root, args)
-  const { js, resources } = await buildBundle(args, undefined, { localAssets: true, desktopRenderer: renderer })
-  assertRendererSupportsBundle(renderer, js)
-  // Native plugins: the project's plugins/ dir + declared plugin libraries, scanned by the host.
-  const { dirs: pluginDirs, files: pluginFiles } = desktopPluginLibraries(root)
-  if (pluginFiles.length > 0) note(`Native plugins: ${pluginFiles.map((f) => basename(f)).join(", ")}`)
-  note(`Launching LeCodes Desktop${renderer === "vulkan" ? " (Vulkan)" : ""}… (close the window to return)`)
-  await runDesktopApp(js, resources, {
-    renderer,
-    pluginDirs,
-    width: Number(flagStr(args, "width")) || win?.width,
-    height: Number(flagStr(args, "height")) || win?.height,
-    minWidth: win?.minWidth,
-    minHeight: win?.minHeight,
-    resizable: win?.resizable,
-    title: flagStr(args, "title") ?? win?.title ?? appCfg?.name,
-    storageScope: appCfg?.name,
-    // --fullscreen forces it on; --windowed forces it off (over app.json); else the config decides.
-    fullscreen: flagBool(args, "fullscreen") ? true : flagBool(args, "windowed") ? false : win?.fullscreen,
-    scale: resolveScale(flagStr(args, "scale"), win?.scale),
-    // 3D render resolution: --render-scale wins over app.json desktop.renderScale; the cap comes
-    // from app.json only. Both are desktop-level (the machine/app), not window-level.
-    renderScale: resolveRenderScale(flagStr(args, "render-scale"), appCfg?.desktop?.renderScale),
-    maxRenderSize: appCfg?.desktop?.maxRenderSize,
-    mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
-    virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
-    // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you
-    // switch on while looking at a frame, not a property of the app.
-    fps: flagBool(args, "fps"),
-    // Multiplayer (docs/multiplayer-plan.md): --server [--port N] [--max-clients N] starts the host as a
-    // dedicated server; --connect ip:port joins one. Both only set Net.launch — the app calls Net.listen/connect.
-    net: flagBool(args, "server")
-      ? { role: "server", port: Number(flagStr(args, "port")) || undefined, maxClients: Number(flagStr(args, "max-clients")) || undefined }
-      : flagStr(args, "connect")
-        ? { role: "client", address: flagStr(args, "connect") }
-        : undefined,
-  })
-}
+const run = defineCommand({
+  name: "run",
+  summary: "Compile the current project and open it in a desktop window",
+  description: "Window size / min size / title default from app.json's desktop block; asset() resources load from the working tree. Multiplayer: --server starts the host as a dedicated server, --connect joins one — both only set Net.launch (the app decides).",
+  flags: {
+    width: num("window width (logical px)"),
+    height: num("window height (logical px)"),
+    title: str("window title", { value: "<s>" }),
+    fullscreen: bool("force fullscreen (over app.json)"),
+    windowed: bool("force windowed (over app.json)"),
+    scale: str('display scale: 0.5..4, "fit" (size a 1080p-designed app to the monitor), or "system"', { value: "<n|fit>" }),
+    "render-scale": str("3D render resolution 0.25..1 (over app.json desktop.renderScale)", { value: "<n>" }),
+    renderer: str("host + shader variant: gl | vulkan (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    fps: bool("draw the host's frame counter in the corner (composited fps + the 3D fps when they diverge)"),
+    perf: bool("the host's profiler: a [perf] line a second (GPU frame time, CPU split, what the camera sees) + a second overlay row; implies --fps"),
+    server: bool("launch as a multiplayer server"),
+    port: num("(--server) listen port"),
+    "max-clients": num("(--server) client cap"),
+    connect: str("join a server as a client", { value: "<ip:port>" }),
+    ...bundleFlags,
+  },
+  examples: ["lecodes desktop run", "lecodes desktop run --scale fit --fps", "lecodes desktop run --perf", "lecodes desktop run --server --port 7777"],
+  run: async ({ flags, raw }) => {
+    // Window defaults come from app.json's desktop block (flags win); standalone projects
+    // without an app.json keep the host's built-in 1280×720.
+    const { root } = localProject()
+    const appCfg = readAppConfigAt(root)
+    const win = appCfg?.desktop?.window
+    // ONE renderer decision per run: it picks the host binary AND which .filamat gets staged beside
+    // the bundle. Reading the config twice is how a Vulkan exe ends up next to an OpenGL shader.
+    const renderer = resolveDesktopRenderer(root, flags.renderer)
+    const { js, resources } = await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer: renderer })
+    // Native plugins: the project's plugins/ dir + declared plugin libraries, scanned by the host.
+    const { dirs: pluginDirs, files: pluginFiles } = desktopPluginLibraries(root)
+    if (pluginFiles.length > 0) note(`Native plugins: ${pluginFiles.map((f) => basename(f)).join(", ")}`)
+    note(`Launching LeCodes Desktop${renderer === "vulkan" ? " (Vulkan)" : ""}… (close the window to return)`)
+    await runDesktopApp(js, resources, {
+      renderer,
+      pluginDirs,
+      width: flags.width || win?.width,
+      height: flags.height || win?.height,
+      minWidth: win?.minWidth,
+      minHeight: win?.minHeight,
+      resizable: win?.resizable,
+      title: flags.title ?? win?.title ?? appCfg?.name,
+      storageScope: appCfg?.name,
+      // --fullscreen forces it on; --windowed forces it off (over app.json); else the config decides.
+      fullscreen: flags.fullscreen ? true : flags.windowed ? false : win?.fullscreen,
+      scale: resolveScale(flags.scale, win?.scale),
+      // 3D render resolution: --render-scale wins over app.json desktop.renderScale; the cap comes
+      // from app.json only. Both are desktop-level (the machine/app), not window-level.
+      renderScale: resolveRenderScale(flags["render-scale"], appCfg?.desktop?.renderScale),
+      maxRenderSize: appCfg?.desktop?.maxRenderSize,
+      // Frame-rate cap (app.json only — like renderScale it is a property of the app, not of a run).
+      frameRate: appCfg?.desktop?.frameRate,
+      mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
+      virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
+      // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you
+      // switch on while looking at a frame, not a property of the app.
+      fps: flags.fps,
+      perf: flags.perf,
+      net: flags.server
+        ? { role: "server", port: flags.port, maxClients: flags["max-clients"] }
+        : flags.connect ? { role: "client", address: flags.connect } : undefined,
+    })
+  },
+})
 
-const status = async () => {
+const status = async (): Promise<void> => {
   const selected = selectedDesktopVersion()
   const installed = installedDesktopVersions()
   log(`renders with    ${selected}${installed.includes(selected) ? "" : c.dim("  (not downloaded yet — fetched on first render)")}`)
@@ -103,28 +114,29 @@ const status = async () => {
   if (process.env.LECODES_DESKTOP_EXE) log(`override        LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE}`)
   if (process.platform === "darwin") {
     // The cache is what runs/builds use; a hand-installed app only steps in when the manifest is unreachable.
-    const installed = findMacHostExe()
-    log(`installed       ${installed ?? c.dim("none")}   ${c.dim("(offline fallback only)")}`)
+    const mac = findMacHostExe()
+    log(`installed       ${mac ?? c.dim("none")}   ${c.dim("(offline fallback only)")}`)
   }
   try {
     const { latest } = await fetchDesktopManifest()
     const hint = semverNewer(selected, latest) > 0
       ? c.yellow("(newer — run `lecodes desktop update`)")
-      : latest === selected
-        ? c.dim("(up to date)")
-        : c.dim("(older than the CLI's minimum — this desktop release isn't published yet)")
+      : latest === selected ? c.dim("(up to date)") : c.dim("(older than the CLI's minimum — this desktop release isn't published yet)")
     log(`published       ${latest}   ${hint}`)
   } catch {
     log(`published       ${c.dim("unknown (couldn't reach the release manifest)")}`)
   }
 }
 
-export const desktop = async (args: Args) => {
-  const sub = args._[0]
-  if (sub === undefined) return status()
-  if (sub === "run") return run(args)
-  // `buildDesktop` reads only flags, never positionals, so it takes both spellings unchanged.
-  if (sub === "build") return buildDesktop(args)
-  if (sub === "update") return updateDesktop()
-  throw new CliError(`Unknown subcommand "desktop ${sub}". Use \`lecodes desktop\` (status), \`lecodes desktop run\`, \`lecodes desktop build\` or \`lecodes desktop update\`.`)
-}
+export default defineCommand({
+  name: "desktop",
+  summary: "The desktop host: status, run the project in a window, build a portable app, update",
+  description: "Bare `lecodes desktop` prints the version status: the host renders use, what is cached in ~/.lecodes/renderer, the newest published one. LECODES_DESKTOP_EXE points every desktop command at a local host build instead.",
+  commands: [
+    run,
+    // `buildDesktop` is shared with `lecodes app build desktop`; its flags live there.
+    desktopBuild,
+    defineCommand({ name: "update", summary: "Move the host to the newest published release", run: () => updateDesktop() }),
+  ],
+  run: () => status(),
+})