lecodes-cli 0.16.0 → 0.16.2

package/README.md

@@ -8,17 +8,40 @@ The package is `lecodes-cli`; the command it installs is **`lecodes`**.
 ## Install
 
 ```sh
-npm i -g lecodes-cli      # then run: lecodes <command>
+npm install -g lecodes-cli      # then run: lecodes <command>
 # or without installing:
 npx lecodes-cli <command>
 ```
 
-The `render` command additionally needs the optional peer **[`lecodes-renderer`](https://www.npmjs.com/package/lecodes-renderer)** (`>= 0.2.0`, for UI + 2D rendering), plus `@napi-rs/canvas` for PNG output:
+### Optional peers
+
+Some commands live in separate packages the CLI loads on demand:
+
+| 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.
+
+Under `npx` neither placement is visible; name every package in one invocation:
 
 ```sh
-npm i -g lecodes-renderer @napi-rs/canvas
+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.
+
 **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
@@ -65,7 +88,7 @@ lecodes push -m "Tweak the menu"    # push as a new checkpoint
 | `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` | 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). 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 i -D lecodes-renderer@^0.2.0`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
+| `render` | 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). 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. |