lecodes-cli 0.20.1 → 1.0.0

package/README.md

@@ -1,10 +1,21 @@
 # lecodes-cli
 
-Clone, edit and push [LeCodes](https://le.codes) projects from your machine, with full TypeScript
-IntelliSense for the platform API in your editor.
+Build, run and ship [LeCodes](https://le.codes) projects from your machine: local projects with
+hot reload on a device, the desktop and the browser; headless render / flow tests; the design and
+scene editors; native iOS / Android / desktop shells; and the clone / push loop against the platform,
+with full TypeScript IntelliSense for the SDK in your editor.
 
 The package is `lecodes-cli`; the command it installs is **`lecodes`**.
 
+```
+lecodes --help              # every command, grouped
+lecodes <command> --help    # that command's options, subcommands and examples
+```
+
+The full reference is [docs/commands.md](docs/commands.md) — generated from the command
+definitions, so it always matches `--help`. How the code is organised and how to add a command:
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Install
 
 ```sh
@@ -15,37 +26,25 @@ npx lecodes-cli <command>
 
 ### Optional peers
 
-Some commands live in separate packages the CLI loads on demand:
+Some commands live in separate packages the CLI installs **on first use** into `~/.lecodes/peers`
+(after a prompt; `--yes` / `LECODES_YES=1` skips it):
 
 | Package | Needed by |
 |---|---|
-| [`lecodes-renderer`](https://www.npmjs.com/package/lecodes-renderer) (`>= 0.2.0`) + `@napi-rs/canvas` for PNG | `render`, `test`, `design`'s screen previews |
-| [`lecodes-design`](https://www.npmjs.com/package/lecodes-design) | `design` |
-| [`lecodes-3d-editor`](https://www.npmjs.com/package/lecodes-3d-editor) | `scene` |
-| `lecodes-assets` | `assets` (FBX → GLB, doctor, retarget) |
-
-```sh
-npm install -g lecodes-renderer @napi-rs/canvas
-```
-
-**Install them the same way you installed the CLI.** A peer is loaded by a bare `import`, which
-resolves upward from the CLI's own file — so a globally installed `lecodes` sees only *globally*
-installed peers, and a `npm i -D` copy in your project is invisible to it. If instead you keep
-`lecodes-cli` in a project's `devDependencies`, install the peers there too.
+| `lecodes-renderer` (pinned to the CLI's own version) + `@napi-rs/canvas` for PNG | `render`, `test`, `design snapshot` |
+| `lecodes-design` | `design` |
+| `lecodes-3d-editor` | `scene`, `thumbs` |
+| `lecodes-assets` | `assets` |
 
-Under `npx` neither placement is visible; name every package in one invocation:
-
-```sh
-npx -p lecodes-cli -p lecodes-assets lecodes assets convert hero.fbx -o hero.glb
-```
-
-The **standalone build** below resolves nothing outside its own bundle, so `render` / `design` /
-`scene` / `assets` need the npm install of the CLI.
+A copy you installed yourself (`npm install -g lecodes-renderer`, or in a project's
+`devDependencies` next to a local `lecodes-cli`) wins over the prefix. `lecodes --version` shows
+each peer's version and where it came from.
 
 **Standalone build** (the release archive, no Node/Bun needed): unpack it and run `./lecodes install`
 to copy the bundle to a library folder and put `lecodes` on your PATH — per-user by default, or
-`--system` for all users on Linux/macOS. (This archive ships the `lecodes` binary alongside the
-`chisel` bundler and a `runtime/` folder; keep them together, or let `install` place them for you.)
+`--system` for all users on Linux/macOS. The archive ships the `lecodes` binary alongside the `chisel`
+bundler and a `runtime/` folder; keep them together, or let `install` place them for you. The
+standalone build resolves no npm packages, so the peer-backed commands need the npm install.
 
 ## Quick start
 
@@ -56,8 +55,10 @@ lecodes init myapp                  # scaffold a local project (starter + types
 cd myapp
 #   …edit main.ts in VS Code (IntelliSense works out of the box)…
 lecodes dev                         # run it on a device with hot reload (scan the QR)
-lecodes dev --web                   # …and in the browser (Web Lite host; camera/map plugins have web twins)
-lecodes compile -o app.js           # compile to a self-contained bundle for LeCodes Desktop
+lecodes dev --web                   # …and in the browser (Web Lite host)
+lecodes dev --desktop               # …and in the native desktop host
+lecodes render --png shot.png       # a headless screenshot; `lecodes test` runs tests/*.flow.json
+lecodes compile -o app.js           # one self-contained bundle for LeCodes Desktop
 ```
 
 Or work against a project **on the platform**:
@@ -68,39 +69,37 @@ lecodes clone <project-uuid> myapp  # download files + types into ./myapp
 cd myapp
 #   …edit files in VS Code…
 lecodes status                      # see what changed
-lecodes push -m "Tweak the menu"    # push as a new checkpoint
+lecodes push -m "Tweak the menu"    # push as a new checkpoint (--publish deploys it live)
 ```
 
-## Commands
-
-| Command | What it does |
-| --- | --- |
-| `init [dir]` | Scaffold a new **local** project (no login, no server): a starter `main.ts`, the SDK types + a `tsconfig.json` for IntelliSense, and a `.lecodesignore`. Run it with `dev`, or compile it with `compile`. `dir` defaults to the current folder. Idempotent — existing files are kept. |
-| `install` | **Standalone build only.** Install the unpacked release bundle so `lecodes` is on your PATH: copies the `lecodes`+`chisel`+`runtime/` bundle to a library folder, then (Linux/macOS) symlinks it into a `bin` dir. PATH itself is edited only with `--modify-path` (appends `export PATH=…` to your shell rc on Linux/macOS, or adds the folder to your user PATH on Windows); otherwise it prints how to finish. Per-user by default; `--system` installs to `/usr/local` (needs sudo, and `/usr/local/bin` is already on PATH). `--dir <path>` overrides the library folder, `--bin <path>` the symlink folder. Refuses when run from an npm/source install (there, install globally with your package manager). |
-| `login` | Authorize in the browser; stores an access token in `~/.lecodes/config.json`. `--token <pat>` to use a token created in the web UI instead, `--api <url>` for the API origin (default `https://le.codes`), `--web <url>` for the app origin. |
-| `clone <uuid\|url> [dir]` | Download a project's file tree + binary resources, plus `.d.ts` types and a `tsconfig.json` for IntelliSense. `--no-types` to skip types. |
-| `link [dir]` | **Connect an existing local folder to the platform** — the reverse of `clone`, for a project started with `init`. Creates a project on the server (`--name`, `--team`), writes `.lecodes/manifest.json` and refreshes the types from the server; nothing is uploaded until you `push`, so `status` shows what would go up first. `--project <uuid\|url>` adopts an **existing** project instead: the manifest is built from its server tree and the command prints exactly what your next push would create/update/delete there before linking (then `push` to let local win, or `pull` to take the server's version). `--push [-m <msg>]` links and pushes in one step (`--publish` also deploys), `--force` re-links an already-linked folder, `--no-types` skips the type refresh. |
-| `status` | Show added / modified / moved / deleted files vs the last sync. |
-| `pull` | Overwrite local files with the project's current remote state. `--force` to discard local edits. |
-| `push` | Push all local changes as **one** new checkpoint. `-m`/`--message` for the message, `--force` to override the "server moved on" guard. |
-| `dev` | Run the project **on a device straight from your machine, with hot reload** — no login or server needed. Starts a LAN dev server and prints a QR code; scan it with the LeCodes app (or pass the URL to the desktop host with `?t=poll`). Every save recompiles and hot-swaps the running app in place (errors roll back to the last good version); the device's `console.log` and errors stream back to the terminal. Assets are served from the working tree; custom shaders still need a prior `push` (their artifacts compile server-side). `--port <n>` (default 4499), `--host <ip>` to override the auto-detected LAN address, `--entry <path>`, `--no-qr`. The URL stays stable across runs (token in `.lecodes/dev.json`). |
-| `compile` | Compile the project to a single JS bundle, printed to **stdout** (pipeable). Works on a cloned/created project (binary asset URLs resolved from the server) **or a local `init` project** (no login — `asset()` resources resolve on the host via `fetchLocal`, so the bundle is self-contained for LeCodes Desktop). `-o`/`--out <file>` to write a file, `--entry <path>` to override the entrypoint, `--no-header` to omit the metadata header, `--no-minify` to keep the bundle readable (skips chisel's compress + mangle — larger output, real identifier names), `--no-sourcemap` to skip the inlined source map (smaller output; runtime errors then report generated positions only), `--public-url <url>` to resolve assets from a URL prefix instead. Diagnostics go to stderr. Formerly `preview`, which still works as an alias. |
-| `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** (no login/project needed). Starts a dev server + browser board showing every `design/screens/*.ts` as a working prototype with the `meta.json` flow edges; screens hot-reload as files change. Drag an unselected screen anywhere to move it, click to select it — a selected screen is interactive (tap, scroll, type; arrow keys nudge it). The canvas edits `meta.json` directly: drag the connect handle onto another screen to draw an edge, click an edge to edit its label/activator (with a dropdown of the source screen's named elements) or delete it, click the header note to edit a description. Double-click any rendered text to edit it in place — the string literal is rewritten in the screen's source file (dynamic text is declined safely). Double-click an image (or drop an image file from your OS onto it) to replace it: the file is stored in `design/assets/` and the `asset()` path is rewritten. Hint mode (`H`) outlines interactive elements, editable texts and replaceable images; selecting or hovering an edge highlights its activator element on the source screen — and hovering that element highlights the edge. Middle-drag or scroll pans from anywhere; ctrl+wheel/pinch zooms. `--port <n>` (default 4477), `--dir <folder>` (default `design/`), `--no-open`. |
-| `design init` | Scaffold the design folder: `screens/`, `shared/`, `meta.json`, and a `CLAUDE.md` documenting the conventions for AI assistants. |
-| `design snapshot [screen…]` | Render design screens headless (needs `lecodes-renderer`). One screen → semantic JSON to stdout; otherwise JSON files in `design/.snapshots/`; `--png` also rasterizes PNGs (needs `@napi-rs/canvas`); `--out-dir <dir>`, `--logs`. |
-| `scene [path]` | **LeCodes Scene Editor** — visually edit a `.scene.ts` 3D scene (needs the optional `lecodes-3d-editor` package). Works inside a cloned project **or standalone in any folder**. Starts a local editor server + browser app: a scene tree, a per-node inspector, and a move/rotate/scale gizmo; add mesh/light/camera/model/aspect nodes; edits are written straight back to the `.scene.ts`, and external (IDE) edits hot-reload over SSE. Registers an MCP server in `.mcp.json` so Claude Code can call `scene_state` (scenes + models + aspect classes with field hints) and `check_scene` (compile status) — `--no-mcp` to skip. `path` is a folder or a `.scene.ts` to host (default: the current folder / enclosing project). `--port <n>` (default 4488), `--no-open`. |
-| `render [file]` | Render the local project (**UI + 2D**). By default emits a semantic JSON description (great for AI/automated checks) to stdout or `-o`/`--out <file>`; `--png [file]` rasterizes a PNG (default `screenshot.png`, `--scale <n>` for DPR). Naming a **screen module** (`lecodes render design/screens/login.ts`, or the bare id `login` for a `design/screens/` file) renders that one screen instead of the launched app — any file that `export default`s a `UIScreen`, or a `(state) => UIScreen` function whose branch `--state <name>` picks. It compiles as part of the project (imports and `asset()` files resolve normally), a design screen picks up its `meta.json` board frame, and the whole flag set applies — `--png`, `--clip`, `--device`, `--script`, `--desktop`. A creator-2d scene is composited **under** the UI; `--time <ms>` advances its physics/animation. `asset('./x.png')` resources (images, sprite textures) load from the local working tree by default — use `--remote-assets` (or an explicit `--public-url`) to fetch them from the server instead (which then needs `--wait-network`). `--width`/`--height` set the viewport (default 390×844). Requires the optional `lecodes-renderer` package (`npm install -g lecodes-renderer@^0.2.0`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
-| `pn` | **Push notifications** for the project (`pn send` / `pn devices` / `pn keys`). `pn send --title "Order shipped" --user u42` sends through the le.codes relay **on your login — no push key needed to test** (`--to <pa_…>` targets addresses instead; `--body`, `--url`, `--badge`, `--data '{…}'` fill the payload; comma-separate multiple targets). `pn devices` lists the devices that actually called `Push.register()` — the first thing to check when a notification doesn't arrive (`--user <id>` to filter). `pn keys` manages the `lecodes_pk_…` keys you deploy in **your own server's** env: the server generates them, so `pn keys new [name]` prints the value exactly once — `--env` writes it straight into `.env` as `LECODES_PUSH_KEY` and gitignores the file. `pn keys revoke <id>` deletes one (owner only for both). |
-| `types [dir]` | Re-materialize the IDE type surface (`.lecodes/types/` + `tsconfig.json`). Fetches `GET /api/types` from the server by default — so a project scaffolded offline by `init` picks up the SDK the platform actually runs — falling back to the copy bundled in this CLI when the server is unreachable. `--local` to use that bundled copy outright (fully offline), `--check` to report drift without writing (exits non-zero when stale — handy in CI), `--api <url>` for the server. IDE-only: the compiler always uses the SDK vendored in the CLI, and the command warns when the two disagree. |
+A local project joins the platform later with `lecodes link` (create) or
+`lecodes link --project <uuid>` (adopt an existing one — it shows what your next push would change
+there before connecting anything).
+
+## Commands at a glance
+
+| Group | Commands |
+|---|---|
+| Project | `init` `create` `clone` `link` `status` `diff` `pull` `push` `login` |
+| Run & test | `dev` `compile` `render` `test` `desktop` |
+| Editors | `design` `scene` `thumbs` |
+| Content | `assets` `shaders` `lightmap` `navmesh` |
+| Native apps | `app` (ios / android / desktop shells) `pn` (push notifications) |
+| Maintenance | `update` `install` |
 
 ## How it works
 
-- Project metadata and the path → asset map live in `.lecodes/` (commit it or not — it's like `.git`).
+- Project metadata and the path → asset map live in `.lecodes/` (per-checkout state, like `.git`;
+  keep it out of the project's own git — `init` / `clone` write the `.gitignore` line).
 - A **push** sends your whole working tree to the server, which atomically rebuilds the project's
   file tree (adds, edits, deletes, renames and moves all at once) and freezes a single checkpoint.
-  Renames/moves keep their history; unchanged binaries are never re-uploaded.
-- Types are fetched from the server on `clone`/`pull`, so they always match the deployed runtime.
-  A local `init` project starts with the copy bundled in the CLI instead; `lecodes types` refreshes
-  either kind on demand.
-
-Config can also be supplied via the `LECODES_API` and `LECODES_TOKEN` environment variables (useful in CI).
+  Renames / moves keep their history; unchanged binaries are never re-uploaded. `push` refuses to
+  overwrite a server that moved on; `diff` shows the conflict, `pull` takes the server's version,
+  `push --force` yours.
+- Types are fetched from the server on `clone` / `pull` / `link`, so they match the deployed runtime.
+  A local `init` project starts with the copy bundled in the CLI; `lecodes update` refreshes
+  either kind (and the desktop host, matc, the shader compiles, the native shell pins and the
+  optional peers).
+- Config lives in `~/.lecodes/config.json`; `LECODES_API` / `LECODES_TOKEN` override it (CI). 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, and the file is never pushed.