lecodes-cli 0.19.0 → 0.19.2

package/src/index.ts

@@ -0,0 +1,491 @@
+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 { 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, 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/`
+ * 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). */
+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. */
+const INSTALLED = STANDALONE && (() => {
+  const exe = process.platform === "win32" ? "lecodes.exe" : "lecodes"
+  const self = (() => { try { return realpathSync(process.execPath) } catch { return process.execPath } })()
+  return (process.env.PATH ?? "").split(delimiter).some(d => {
+    if (!d) return false
+    try { const cand = join(d, exe); return existsSync(cand) && realpathSync(cand) === self } catch { return false }
+  })
+})()
+
+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
+                                  --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]      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)
+  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()]]
+  for (const [name, probe] of OPTIONAL_PEERS) {
+    const version = peerVersion(name, probe)
+    rows.push([name, version ?? c.dim("not installed")])
+  }
+  const desktopVersion = selectedDesktopVersion()
+  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()
+
+  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
+})

package/src/lecodes-3d-editor.d.ts

@@ -0,0 +1,41 @@
+// Types for the optional `lecodes-3d-editor` package's server entry (lazy-loaded by the `scene`
+// command). The real package is installed separately; this lets the dynamic import typecheck
+// without it present. Keep in sync with lecodes-tools/packages/lecodes-3d-editor/src/server/index.ts (the CLI↔tool
+// dist coupling: after a server-surface change, rebuild the editor's dist and update this file).
+declare module "lecodes-3d-editor/server" {
+  export type CompiledScene = { js: string | null, error?: string }
+
+  export type SceneServerOptions = {
+    root: string
+    compile: (scenePath: string) => Promise<CompiledScene>
+    /** A shader's compiled artifact file for a platform ("webgl-lite" / "webgl") from the host's
+     *  cache, null when absent (the server builds the lite JSON itself then). */
+    shaderArtifact?: (shaderText: string, platform: string) => string | null
+    port?: number
+    appDir?: string
+    log?: (message: string) => void
+  }
+
+  export type SceneServer = {
+    port: number
+    url: string
+    close: () => void
+  }
+
+  export function startSceneServer(options: SceneServerOptions): Promise<SceneServer>
+
+  /* The asset-preview cache (server/previewCache.ts) — `lecodes thumbs` writes into the same
+   * `.lecodes/preview/<asset>.<hash>.png` layout the editor reads. */
+
+  /** sha256 tag (10 hex) of an asset's current bytes; null when the file is gone. */
+  export function hashAsset(projectDir: string, assetPath: string): string | null
+  /** Whether the cached preview for THAT hash is already on disk (the incremental skip). */
+  export function previewIsCurrent(projectDir: string, assetPath: string, hash: string): boolean
+  /** Cache file name for an asset at a known hash. */
+  export function previewName(assetPath: string, hash: string): string
+  /** Store a preview PNG under the asset's current hash (older ones are dropped); returns the file
+   *  name written, or null when the asset itself is missing. */
+  export function writePreviewFile(projectDir: string, assetPath: string, png: Uint8Array): string | null
+  /** Asset path → cache file name, for every preview on disk. */
+  export function listPreviews(projectDir: string): Record<string, string>
+}

package/src/lecodes-assets.d.ts

@@ -0,0 +1,7 @@
+// Types for the optional `lecodes-assets` package's CLI entry (lazy-loaded by the `assets` command).
+// The real package is installed separately; this lets the dynamic import typecheck without it
+// present. Keep in sync with packages/lecodes-assets/src/cli.ts.
+declare module "lecodes-assets/cli" {
+  /** Runs `convert | probe | doctor` with the given argv (sub-command first). Resolves to the exit code. */
+  export function runAssetsCli(argv: string[]): Promise<number>
+}