lecodes-cli 0.20.2 → 1.0.0

package/src/index.ts

@@ -1,53 +1,32 @@
-import pkg from "../package.json"
-import { app } from "./commands/app"
-import { clone } from "./commands/clone"
-import { compile, previewLegacy } from "./commands/compile"
-import { create } from "./commands/create"
-import { desktop } from "./commands/desktop"
-import { design } from "./commands/design"
-import { dev } from "./commands/dev"
-import { diff } from "./commands/diff"
-import { init } from "./commands/init"
-import { link } from "./commands/link"
-import { lightmap } from "./commands/lightmap"
-import { navmesh } from "./commands/navmesh"
-import { login } from "./commands/login"
-import { shaders } from "./commands/shaders"
-import { render } from "./commands/render"
-import { pn } from "./commands/pn"
-import { pull } from "./commands/pull"
-import { push } from "./commands/push"
-import { scene } from "./commands/scene"
-import { thumbs } from "./commands/thumbs"
-import { assets } from "./commands/assets"
-import { status } from "./commands/status"
-import { test } from "./commands/test"
-import { update } from "./commands/update"
-import { existsSync, readFileSync, realpathSync } from "node:fs"
-import { createRequire } from "node:module"
+import { existsSync, realpathSync } from "node:fs"
 import { delimiter, dirname, join } from "node:path"
-import { install } from "./commands/install"
-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, peerSource, peerVersion } from "./peers"
+import pkg from "../package.json"
+import { c, log, reportError, runCli } from "./cli"
+import { commandGroups } from "./commands"
+import { installedDesktopVersions, selectedDesktopVersion } from "./hosts/desktopRenderer"
+import { installedMatcVersions } from "./hosts/matcTool"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "./hosts/peers"
+import { loadProjectEnv } from "./project/env"
+
+/*
+ * `lecodes` — the entry point. Everything a command is lives in src/commands (one file each, listed
+ * in src/commands/index.ts); this file only decides what the standalone binary shows and hands argv
+ * to the runner (src/cli/run.ts).
+ */
 
 /* `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/`
  * that scripts/build-bin.ts lays down beside the compiled binary. For an npm install process.execPath
- * is `node`, and for `bun run` it's `bun`; neither has those companions, so `install` is unavailable
- * there (omitted from help and unregistered → `lecodes install` reports an unknown command). */
+ * is `node`, and for `bun run` it's `bun`; neither has those companions, so `install` stays out of the
+ * help there (it still runs, for repair / install-over-the-top). */
 const STANDALONE = (() => {
   const dir = dirname(process.execPath)
   const chisel = process.platform === "win32" ? "chisel.exe" : "chisel"
   return existsSync(join(dir, "runtime")) && existsSync(join(dir, chisel))
 })()
 
-/* Are we ALREADY the installed copy — i.e. is a `lecodes` on PATH resolving to this very executable?
- * If so, re-installing is pointless, so we drop `install` from help (but keep it runnable for repair /
- * install-over-the-top). Running the freshly-unpacked archive instead: no PATH entry points back to it
- * → this is false → `install` is offered. */
+/* Already the installed copy — a `lecodes` on PATH resolves to this very executable? Then
+ * re-installing is pointless and `install` drops out of the help too. */
 const INSTALLED = STANDALONE && (() => {
   const exe = process.platform === "win32" ? "lecodes.exe" : "lecodes"
   const self = (() => { try { return realpathSync(process.execPath) } catch { return process.execPath } })()
@@ -57,455 +36,28 @@ const INSTALLED = STANDALONE && (() => {
   })
 })()
 
-const INSTALL_HELP = STANDALONE && !INSTALLED ? `
-  install                       Install this standalone build so 'lecodes' is on your PATH
-                                  (copies the bundle to a library folder + a symlink/PATH entry).
-                                  --modify-path   also add it to PATH (edits your shell rc / user PATH)
-                                  --system        install for all users (Linux/macOS; needs sudo)
-                                  --dir <path>    override the install/library folder
-                                  --bin <path>    override the symlink folder (Linux/macOS)` : ""
-
-const HELP = `${c.bold("lecodes")} — clone, edit and push LeCodes projects from your machine.
-
-${c.bold("Usage:")} lecodes <command> [options]
-
-${c.bold("Commands:")}
-  init [dir]                    Scaffold a new LOCAL project (no login/server): a starter
-                                  main.ts, a CLAUDE.md + passing flow test (the headless
-                                  render/test loop), IDE types + tsconfig, a .lecodesignore.
-                                  Run it with 'lecodes dev' or 'lecodes compile'.
-                                  --desktop       also write an app.json declaring the desktop
-                                                    target (window size; 'dev --desktop',
-                                                    'desktop run' and headless render/test
-                                                    pick it up)${INSTALL_HELP}
-  login                         Authorize in the browser and store an access token
-                                  --token <pat>   store a token from the web UI instead
-                                  --api <url>     API origin (default https://le.codes)
-                                  --web <url>     app origin for the browser flow
-  create <name> [dir]           Create a new project on the server and scaffold it locally
-                                  (types from the server + tsconfig + a starter main.ts)
-                                  --team <uuid>   create it inside a team
-  clone <uuid|url> [dir]        Download a project's files + types into a new folder
-                                  --no-types      skip the .d.ts / tsconfig generation
-  link [dir]                    Connect an existing local folder (e.g. one made by 'lecodes
-                                  init') to the platform — the reverse of clone. Creates a
-                                  project on the server, writes .lecodes/manifest.json and
-                                  refreshes the types; nothing is uploaded until you push
-                                  --name <s>          project name (default: folder name)
-                                  --team <uuid>       create it inside a team
-                                  --project <uuid|url>  adopt an EXISTING project instead —
-                                                      prints what your next push would change
-                                                      on its server tree, and confirms first
-                                  --push [-m <msg>]   push right after linking (--publish to
-                                                      deploy it live in the same step)
-                                  --force             re-link a folder that's already linked
-                                  --no-types          skip the .d.ts / tsconfig refresh
-  status                        Show local changes vs the last sync
-  diff [path…]                  Show a unified diff of local vs the current server state
-                                  --name-only     list changed paths + status only
-  pull [path…]                  Overwrite local files with the project's current state
-                                  (with path… : pull only those files/folders, keep other edits)
-                                  --force         discard uncommitted local changes
-  push                          Push local changes as one new checkpoint
-                                  -m, --message   checkpoint message
-                                  --publish       also deploy the project live (compile) with the push
-                                  --force         push even if the server moved on (shows + confirms
-                                                    which server files get overwritten)
-                                  -y, --yes       skip the --force overwrite confirmation
-  dev                           Run the project on a device from this machine, with hot reload:
-                                  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.
-                                  --port <n>      server port (default 4499)
-                                  --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)
-                                  --desktop       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           (--desktop) draw the host's frame counter
-  compile                       Compile the local project to JS (prints to stdout)
-                                  (was 'lecodes preview' — the old name still works)
-                                  -o, --out <file>   write to a file instead of stdout
-                                  --entry <path>     override the entrypoint
-                                  --no-header        omit the metadata header
-                                  --no-minify        keep the bundle readable (no compress/mangle)
-                                  --no-sourcemap     don't generate/inline the source map
-                                  --public-url <url> asset URL prefix (default: the API origin)
-  render [file]                 Render the local UI project to a semantic JSON description
-                                  (needs the optional 'lecodes-renderer' package; UI projects only)
-                                  [file]             render ONE screen module instead of the app:
-                                                       a file that default-exports a UIScreen (or a
-                                                       (state) => UIScreen) — every 'lecodes design'
-                                                       screen is written that way. A bare id
-                                                       ("login") resolves in design/screens/, and a
-                                                       design screen renders at its meta.json frame
-                                  --state <name>     ([file]) the state to pass a
-                                                       (state) => UIScreen screen
-                                  -o, --out <file>   write JSON to a file instead of stdout
-                                  --png [file]       rasterize a PNG (default screenshot.png;
-                                                       needs @napi-rs/canvas)
-                                  --map [file]       draw the 3D scene's annotated top-down map
-                                                       (grid + XZ footprints + named markers) as
-                                                       <file>.png + <file>.json world-space data
-                                                       (default map.png; --label-all, --max-px N;
-                                                       also a { "map": "f.png" } script step)
-                                  --script <file>    drive the app through a step list (tap/type/
-                                                       scroll/wait/expect/screenshot/json steps;
-                                                       games: frames/drag/hold/key/keyDown/keyUp,
-                                                       expect.log, screenshot clip)
-                                  --out-dir <dir>    where --script step outputs land (default .)
-                                  --clip <name|x,y,w,h>  (--png) crop to one node's rect or a
-                                                       logical-px rect — a component/region render
-                                  --fixtures <file>  canned fetch responses (URL pattern →
-                                                       { status?, json?, text? }) — make
-                                                       backend-gated screens reachable headless
-                                  --scale <n>        PNG device-pixel scale (default 2)
-                                  --width/--height   viewport size (default 390x844)
-                                  --entry <path>     override the entrypoint
-                                  --settle <ms>      wait for promises/timers/fetch before snapshot
-                                  --wait-network     let data fetches hit the real network
-                                  --logs             forward the app's console output (to stderr)
-                                  --desktop          render through the NATIVE desktop host instead:
-                                                       real Filament 3D + tgfx UI + 2D, composited.
-                                                       PNG only (--png). Downloads the LeCodes
-                                                       Desktop renderer on first use into
-                                                       ~/.lecodes/renderer (Windows/Linux;
-                                                       LECODES_DESKTOP_EXE overrides)
-                                  --frames <n>       (--desktop) frames to run before the shot —
-                                                       headroom for async loads (default 60)
-                                  --desktop --script <file>  drive the scenario through the native
-                                                       host: tap/drag/hold take { x, y } coordinates
-                                                       (no names — the host has no UI tree; type/
-                                                       scroll/clip unavailable), expect.log is
-                                                       checked, text/node/screen/value are skipped;
-                                                       per-step screenshots + final --png
-                                  --view <name>      (--desktop) inspection camera auto-fitted to the
-                                                       whole 3D scene: iso | top | front | side | back
-                                                       [--fov N]; the app's camera is untouched
-                                  --camera x,y,z --look-at x,y,z [--fov N]
-                                                     (--desktop) inspection camera at a fixed eye /
-                                                       look-at point (world units, Y up). In a
-                                                       --script run use { "view" } / { "camera" } steps
-                                  --fixed-dt <ms>    (--desktop) virtual app clock, ms per frame —
-                                                       deterministic game time (scripted runs
-                                                       default to 16; plain renders to wall clock)
-  test [name…]                  Run headless flow tests: tests/*.flow.json scenarios, plus flows
-                                  derived from the design graph (design/meta.json activator edges
-                                  — checks the built app against the designed navigation; needs
-                                  named elements + screen roots). Failing steps dump the frame
-                                  (JSON + PNG) under tests/.artifacts/<flow>/.
-                                  Design flows read tests/fixtures.json automatically (canned
-                                  fetch responses) so backend-gated transitions run headless;
-                                  file scenarios declare their own via the "fixtures" envelope.
-                                  --flows            run ONLY the design-derived flows
-                                  --no-flows         run ONLY the tests/*.flow.json files
-                                  --fixtures <file>  fixture pack for the design flows (overrides
-                                                       the tests/fixtures.json default)
-                                  --json             machine-readable report on stdout
-                                  --dir <folder>     tests folder (default tests/)
-                                  --design-dir <dir> design folder (default design/)
-                                  --artifacts <dir>  failure-artifact folder override
-                                  --desktop          run the file scenarios through the NATIVE host
-                                                       (coordinates only; expect.log checked,
-                                                       text/node/screen/value skipped; design flows
-                                                       stay headless). --frames / --fixed-dt as in
-                                                       render --desktop
-                                  (+ the render timing flags: --width/--height, --settle,
-                                   --device, --safe-area, --wait-network, --logs, --entry)
-  update                        Move everything a project depends on to its newest published
-                                  state, in dependency order: the desktop host ('desktop
-                                  update'), matc ('shaders update'), the project's shader
-                                  compiles, the IDE types (.lecodes/types/ + tsconfig.json,
-                                  from the server — the former 'lecodes types'), the
-                                  ios/android shell pins ('app update'), then the GLOBAL npm
-                                  installs: every installed optional peer (lecodes-renderer,
-                                  lecodes-design, lecodes-3d-editor, lecodes-assets) and this
-                                  CLI that is behind npm's latest gets 'npm install -g'.
-                                  Pinned tools are skipped, not overridden: LECODES_DESKTOP_EXE
-                                  / LECODES_MATC mean a local build. Keeps going when a step
-                                  fails; the summary says which.
-                                  --local            types from the SDK bundled in this CLI
-                                  --no-shells        leave ios/android pins alone (no re-sync)
-                                  --check            npm step: report what's behind, install nothing
-                                  --no-cli           skip the npm step (offline)
-  design [serve]                LeCodes Design — a live canvas of screens for AI-driven prototyping
-                                  (needs the optional 'lecodes-design' package; works inside a
-                                   cloned project or standalone in any folder)
-                                  --port <n>         dev-server port (default 4477)
-                                  --dir <folder>     design folder (default design/)
-                                  --no-open          don't open the browser
-  design init                   Scaffold the design folder (screens/, shared/, meta.json, CLAUDE.md)
-                                  --desktop          desktop-frame board (meta.json defaultSize
-                                                       [1280, 800] instead of the phone frame)
-  design snapshot [screen…]     Render design screens headless (needs 'lecodes-renderer')
-                                  one screen → JSON to stdout; else files in design/.snapshots/
-                                  --png              also rasterize PNGs (needs @napi-rs/canvas)
-                                  --out-dir <dir>    output folder override
-                                  --logs             forward the screens' console output (to stderr)
-  design comments               Review comments pinned to the board, grouped by screen (open first)
-                                  --all              include resolved threads
-                                  add "<text>" [--screen <id>] [--state <s>] [--element <name>]
-                                  reply <number> "<text>"  ·  resolve <number> [--reply "<text>"] [--reopen]
-                                  (--ai signs a write as Claude; sends with the next "lecodes push")
-  desktop [run|build|update]    The desktop target — the host 'lecodes render --desktop' uses too:
-                                  no args shows the version status (selected / downloaded /
-                                  newest published)
-                                  run     compile the current project and open it in a real
-                                          desktop window (size/min-size/title default from
-                                          app.json's desktop block; --width/--height/--title
-                                          override; --fullscreen/--windowed override the
-                                          app.json fullscreen; --scale <0.5..4|fit> overrides
-                                          the display scale — "fit" sizes a 1080p-designed app
-                                          to the monitor with the density raised to match;
-                                          --entry overrides the entrypoint; --fps draws the
-                                          host's frame counter in the corner — composited fps,
-                                          plus the 3D fps when they diverge; asset() resources
-                                          load from the working tree — --remote-assets or
-                                          --public-url <url> uses the server's copies instead);
-                                          --server [--port N] [--max-clients N] launches the
-                                          host as a multiplayer server, --connect ip:port as a
-                                          client — both only set Net.launch (the app decides)
-                                  build   stage a portable app folder (default dist/<name>/):
-                                          the cached host renamed to <Name>.exe + app.js +
-                                          assets/ (the project's files) + runtime/ (the engine's)
-                                          + app.json (the host reads title/size/fullscreen from
-                                          it) + app.ico from app.json "icon". Duplicate asset
-                                          basenames are a build error (they silently alias in
-                                          the bundle). Also spelled 'lecodes app build desktop'.
-                                          On macOS: a signed .app instead (the downloaded LeCodes
-                                          Desktop.app + the project inside it); app.json
-                                          desktop.macos = bundleId / buildNumber / category /
-                                          signing.identity / notarize.profile (a notarytool
-                                          keychain profile — notarized + stapled, so it opens
-                                          on any Mac without "Open Anyway").
-                                          -o <dir>       output folder (default dist/<name>)
-                                          --slug <name>  folder/zip name override (Latin-only)
-                                          --renderer <gl|vulkan>  host + shader variant
-                                          --probe        headless-render the staged folder to PNG
-                                                         (macOS: a brief windowed run + snapshot)
-                                          --zip          also pack the result for sending
-                                          --dmg          macOS: also build a drag-to-Applications
-                                                         disk image (signed + notarized too)
-                                          --sign <identity|adhoc>   macOS codesign identity
-                                          --notarize <profile> / --no-notarize   macOS
-                                          --zip          <out>.zip, UTF-8/forward-slash entries
-                                  update  move to the newest published release
-                                          (cached in ~/.lecodes/renderer)
-  lightmap bake                 Bake static shadows + ambient occlusion into a lightmap atlas
-                                  (assets/lightmap/lightmap.{png,bake}) by running the app in
-                                  the desktop host: the statics are what the app registers
-                                  with Lightmap.add, the bake fires at its Lightmap.load call.
-                                  Props need UVs first: lecodes assets doctor … --lightmap-uv
-                                  --out <dir>        where the atlas lands (assets/lightmap)
-                                  --size <px>        atlas edge (4096)   --texel <m> density (0.02)
-                                  --sun-rays/--ao-rays <n>   quality (32 / 64)
-                                  --ao-distance <m>  AO reach (2)        --sun-angle <deg> (0.5)
-                                  --frames <n>       load headroom (900) --logs  host output
-  navmesh bake                  Build the level's navigation mesh (assets/nav/<scene>.navmesh)
-                                  for NavAgent / NavMesh: the desktop host dumps every STATIC
-                                  body's collision triangles at the scene's env.navmesh (or
-                                  NavMesh.load) point, Recast builds the mesh here.
-                                  --out <dir>        where it lands (assets/nav)
-                                  --name <n>         file name (the scene file with env.navmesh)
-                                  --radius/--height/--climb/--slope   agent size (scene's)
-                                  --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|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);
-                                  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)
-                                  --port <n>         editor-server port (default 4488)
-                                  --no-open          don't open the browser
-                                  --no-mcp           don't register the MCP server in .mcp.json
-  thumbs [path…]                Asset thumbnails for the scene editor, WITHOUT a browser: decodes
-                                  the project's images (KTX2 too, via KTX-Software's ktx tool) into the
-                                  editor's preview cache. Incremental — the cached name carries the
-                                  asset's content hash, so unchanged files are skipped. Models,
-                                  materials and prefabs are rendered by the editor, not here
-                                  --force            redo even the up-to-date ones
-                                  --size <px>        longest edge (default 256)
-  assets convert <model.fbx|.glb> [--clips a.fbx b.fbx …] [-o out.glb] [--drop-model-clips]
-                                  [--fix] [--ktx2|--ktx2-hq]
-                                FBX → LeCodes-ready GLB: meters/Y-up, textures embedded, clips from
-                                  other FBX files merged by bone name (Mixamo: one FBX per animation);
-                                  --fix/--ktx2 run the doctor passes (needs 'lecodes-assets')
-                                  Unity .mat files next to the FBX are read for the real textures
-                                  (metallic/roughness/ORM/emission packed the glTF way); --no-unity
-                                  keeps the FBX references; --unity-index <unity-index.txt> resolves GUIDs
-                                  --list-nodes / --keep <node> … / --split [dir]: carve one variant out of a
-                                  multi-variant prop file, re-origined on the ground (or one GLB per node)
-                                  --merge-skins b.fbx …: modular character pieces onto ONE skeleton
-  assets unpack <pkg.unitypackage> [-o dir] [--only re …] [--list]
-                                Stream a .unitypackage to a folder: writes unity-index.txt (GUID → path,
-                                  what convert resolves textures with) and the matching assets + .meta
-  assets scene <map.unity> [-o level.json] [--filter re] [--group g] [--region x0,z0,x1,z1]
-                                Unity scene → placed prefabs / mesh objects with world TRS in LeCodes'
-                                  frame + a prefab table (FBX + --keep node per prefab)
-  assets probe <file.fbx|.glb> [--filmstrip [out.png]]
-                                Skeleton, clips (+ root motion / first-frame-vs-rest per clip), meshes,
-                                  materials, textures, bind sanity, duplicate names; --filmstrip renders
-                                  a CPU-skinned PNG strip per clip (no GPU)
-  assets sky <env.exr|.hdr> [-o dir] [--size N] [--ibl-size N] [--ibl-only]
-                                Equirectangular HDR → the two cubemaps a scene needs: sky.ktx (sharp,
-                                  for 'skybox: { texture }') and ibl.ktx (prefiltered + SH, lights the
-                                  scene) — they are NOT interchangeable. Reports where the sun is in
-                                  the environment so the scene's light can be aimed to match
-  assets terrain-pack <layer> … [-o dir] [--normals n0 n1 …] [--names a b …] [--size N] [--png]
-                                A terrain's splat layers (≤ 4) → <name>.ktx2 per layer + the packed
-                                  normal maps normals01/normals23.ktx2 (what Terrain.create's
-                                  layers/normals read). A layer = an albedo file or a FOLDER holding
-                                  *Albedo* + *Normal* (Unity packs). Prints the Terrain.create fragment
-  assets doctor <in.glb|dir> [--fix] [--ktx2] [--dump]
-                                Analyze / fix a GLB against engine limits (bone cap 256, texture
-                                  formats/size, KTX2 via toktx)
-  app init <ios|android|desktop>  Generate a native shell in <project>/ios/ or <project>/android/
-                                  (offline-first: runs the bundled app.js; never pushed to LeCodes).
-                                  desktop: no shell needed — writes app.json's desktop block
-                                  (window size; --fullscreen for kiosks)
-                                  --name <s>         display name (default: app.json / folder name)
-                                  --bundle-id <id>   iOS bundle identifier
-                                  --app-id <id>      Android applicationId (default com.example.<slug>)
-                                  --team <id>        Apple development team id
-                                  --variant <v>      iOS SDK variant: auto (default — sync picks the
-                                                     smallest of core/2d/3d/full covering what
-                                                     the bundle uses), or one of those to pin
-                                  --sdk <v>          native SDK release (default: the newest one,
-                                                     pinned in app.json ios.sdk / android.sdk);
-                                                     'latest' floats it — every sync re-resolves
-  app sync [ios|android]        Make every existing shell match the project: compile the bundle
-                                  + embed its assets (ios/App/Resources/ resp. the android
-                                  assets/; offline by default, also for server projects;
-                                  app.json "resources": {"remote": [globs]} keeps heavy assets
-                                  streaming), pick the iOS SDK variant from the bundle's engine
-                                  use, vendor app.json plugins (pinned in plugins.lock.json),
-                                  regenerate the CLI-owned shell files. app.json "update": true
-                                  (or {"url": …}) enables native OTA JS updates at launch (iOS).
-                                  app.json "icon" (square ≥1024px image) renders the app icons
-                                  every sync ("iconBackground": adaptive/flatten backdrop)
-  app update [ios|android]      Move the shell's pins forward — app.json ios.sdk / android.sdk
-                                  to the newest published SDK release, plugins.lock.json to each
-                                  plugin's newest tag — then re-sync
-                                  --sdk <v|latest>   pin that release instead of the newest
-                                  --check            report available updates, write nothing
-                                  --no-plugins       only move the SDK pin
-                                  --no-sync          update the pins without re-syncing
-  app plugin <list|add|remove>  Manage native plugins in app.json (then run 'lecodes app sync')
-                                  add takes a known id (camera, qr-scanner) or github:owner/repo[@tag]
-  app open [ios|android]        Open the native shell in its IDE (Xcode / Android Studio)
-  app doctor                    Preflight checks for building/uploading the shells
-  app build ios                 Sync, archive and export the .ipa (automatic signing)
-                                  --configuration <c>  build configuration (default Release)
-                                  --method <m>         export method (default app-store-connect)
-                                  --no-export          stop after the archive
-                                  --no-sync            skip the lecodes app sync step
-  app build android             Sync, then gradlew assembleRelease + bundleRelease (signing via
-                                  android/keystore.properties or LECODES_ANDROID_* env vars)
-                                  --configuration <c>  Release (default) or Debug
-                                  --no-aab             skip the .aab (APK only)
-                                  --no-sync            skip the lecodes app sync step
-  app build desktop             Same as 'lecodes desktop build' (kept for symmetry with the
-                                  ios/android shells) — see the desktop group above.
-  app upload ios                Upload the archive to App Store Connect (then bumps buildNumber)
-                                  --key-path <p8> --key-id <id> --issuer-id <id>
-                                                       ASC API key; stored in ~/.lecodes/asc.json
-  pn send --title <s>           Push notifications for this project ('lecodes pn' for the group).
-                                  Sends with your login — no push key needed to test.
-                                  --user <ids>    target Push.register({ user }) ids (comma-sep)
-                                  --to <pa_…>     target addresses (comma-separated)
-                                  --body/--url/--badge/--data   payload fields
-  pn devices                    Which devices registered (the 'why didn't it arrive?' command)
-                                  --user <id>     only that user's devices
-  pn keys [new|revoke]          Push keys for YOUR server: list, mint (owner only, shown once
-                                  — 'new --env' banks it in .env), revoke <id>
-
-Config lives in ~/.lecodes/config.json (override with LECODES_API / LECODES_TOKEN).
-A .env next to app.json is read at startup for LECODES_* / CREATOR_* keys (the shell's own
-environment wins; ./ paths resolve against the project; the file is never pushed) — e.g.
-LECODES_DESKTOP_EXE, LECODES_MATC, LECODES_NOTARY_PROFILE, LECODES_MACOS_SIGN_ID, LECODES_TOKEN.`
-
-// `preview` is the legacy name of `compile` — kept registered (and out of the help) for old scripts.
-const commands: Record<string, (args: Args) => Promise<void>> = { init, login, create, clone, link, status, diff, pull, push, compile, preview: previewLegacy, render, test, design, scene, thumbs, dev, app, pn, desktop, shaders, assets, lightmap, navmesh, update }
-if (STANDALONE) commands.install = install
-
-/** Package version, inlined at build time (the standalone binary has no package.json on disk). */
-const readVersion = (): string => pkg.version ?? "unknown"
-
-/** `--version`: the CLI version, every separately-installed optional peer (or "not installed"),
- *  and the desktop render host `render --desktop` would use (no network — cache state only). */
-const printVersion = () => {
-  const rows: [label: string, value: string][] = [["lecodes-cli", readVersion()]]
+/** `--version`: the CLI, every separately-installed optional peer (or "not installed"), and the
+ *  desktop host / matc `render --desktop` and the shader compile would use (cache state, no network). */
+const printVersion = (): void => {
+  const rows: [string, string][] = [["lecodes-cli", pkg.version ?? "unknown"]]
   for (const [name, probe] of OPTIONAL_PEERS) {
     const version = peerVersion(name, probe)
     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")])
+    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)
-    ? desktopVersion
-    : `${desktopVersion} ${c.dim("(not downloaded — fetched on first `render --desktop`)")}`])
+  rows.push(["lecodes-desktop", installedDesktopVersions().includes(desktopVersion) ? desktopVersion : `${desktopVersion} ${c.dim("(not downloaded — fetched on first `render --desktop`)")}`])
   const matcVersion = installedMatcVersions()[0]
   rows.push(["matc", matcVersion ?? c.dim("not downloaded — fetched on the first local shader compile")])
   const width = Math.max(...rows.map(([label]) => label.length))
   for (const [label, value] of rows) log(`${label.padEnd(width)}  ${value}`)
 }
 
-const main = async () => {
-  const argv = process.argv.slice(2)
-  const command = argv[0]
-  // 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)
-    return
-  }
-
-  if (command === "--version" || command === "-v" || command === "version") {
-    printVersion()
-    return
-  }
-
-  const run = commands[command]
-  if (!run) {
-    log(c.red(`Unknown command: ${command}`))
-    log(HELP)
-    process.exitCode = 1
-    return
-  }
-
-  // `assets` owns its own flag grammar (multi-value --clips …) — hand it the raw argv too.
-  await run(Object.assign(parseArgs(argv.slice(1)), { _raw: argv.slice(1) }))
-}
-
-main().catch((e: unknown) => {
-  if (e instanceof CliError) log(c.red("✗ ") + e.message)
-  else log(c.red("✗ Unexpected error: ") + (e instanceof Error ? e.message : String(e)))
-  process.exitCode = 1
-})
+runCli({
+  version: pkg.version ?? "unknown",
+  groups: commandGroups({ install: STANDALONE && !INSTALLED }),
+  footer: "Config lives in ~/.lecodes/config.json (override with LECODES_API / LECODES_TOKEN). A .env next to app.json is read at startup for LECODES_* / CREATOR_* keys (the shell's own environment wins; ./ paths resolve against the project; the file is never pushed) — e.g. LECODES_DESKTOP_EXE, LECODES_MATC, LECODES_TOKEN.",
+  printVersion,
+  // The project's .env before any command reads the environment; the real environment keeps precedence.
+  before: () => { loadProjectEnv() },
+}, process.argv.slice(2)).catch(reportError)