lecodes-cli 1.0.0 → 2.0.1

package/src/commands/navmesh.ts

@@ -22,7 +22,7 @@ import { loadCreatorNav, NavBuilder, readNgeo, navMeshTriangles, type BuildParam
  *
  * Running the build in the CLI keeps the host generic (a geometry dump, useful on its own),
  * lets the bake parameters iterate without a host rebuild, and is the same code a future headless
- * bake reuses. The desktop host must know the dump (built from packages/desktop, or a release that
+ * bake reuses. The desktop host must know the dump (built from hosts/desktop, or a release that
  * ships it: LECODES_DESKTOP_EXE for a local build until then).
  *
  * The agent size (--radius/--height/--climb/--slope) defaults to what the scene declares — the
@@ -183,7 +183,7 @@ const bake = defineCommand({
     }
     if (!/\[navmesh\] done/.test(output)) {
       if (lines.some((l) => /cannot dump collision geometry/.test(l))) {
-        throw new CliError("This desktop host has no collision-geometry dump. Build packages/desktop and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe, or update: lecodes desktop update.")
+        throw new CliError("This desktop host has no collision-geometry dump. Build hosts/desktop and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe, or update: lecodes desktop update.")
       }
       if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
       warnErr("The host ran to its frame cap without dumping geometry. Make sure the level declares `env.navmesh` (a scene file) or calls NavMesh.load(...) after its static bodies exist, and skips menus when NavMesh.baking is true. More load headroom: --frames <n>. Host output: --logs.")

package/src/commands/plugin.ts

@@ -0,0 +1,46 @@
+import { CliError, bool, c, defineCommand, info, log, success } from "../cli"
+import { generate } from "../plugin/generate"
+
+/*
+ * `lecodes plugin` — for the AUTHOR of a native plugin (the app's side is `lecodes app`, which
+ * installs plugins into a shell).
+ *
+ *   plugin gen   a plugin's contract.d.ts → the generated files beside its hand-written ones.
+ *                The contract is the one description of the channel; what is generated from it is
+ *                committed, and `--check` is what a CI runs to refuse a stale file.
+ */
+
+const gen = defineCommand({
+  name: "gen",
+  summary: "Generate a plugin's files from its contract.d.ts (--check: fail on a stale one)",
+  usage: "[path]",
+  description: "The path is one plugin (a directory with a contract.d.ts) or a repo that keeps its plugins in plugins/<id>/; the current directory when omitted.\n\nWrites sdk/<id>.gen.ts — the wrapper an app calls: the wire call by call, the class with the wire's methods as its own, and the public export when the plugin has no hand-written sdk/<id>.ts. Where the plugin has an ios/ folder, writes ios/<Name>.gen.swift — the contract's types, the protocol the plugin implements and the glue that reads a call off the wire. Where it has an android/ folder, writes the same as <Name>.gen.kt into the folder of the plugin's Kotlin package (android/ is laid out as a Gradle module: the package is the folder the path under android/src/main/java narrows down to). Where it has a web/ folder, writes web/<id>.gen.ts — the same for the web half, in a file that imports nothing; a web half that imports a LeCodes package is refused, because it would run on that host only. A contract the generator does not understand is an error with its line, and every problem of a file is reported at once.\n\nGenerated files are committed. Reading a contract needs TypeScript in the plugin's repo.",
+  flags: {
+    check: bool("write nothing; exit 1 when a generated file is missing or stale"),
+  },
+  examples: ["lecodes plugin gen", "lecodes plugin gen plugins/camera", "lecodes plugin gen --check"],
+  run: ({ args, flags }) => {
+    const report = generate(args[0] ?? ".", { check: flags.check })
+
+    for (const p of report.plugins) {
+      const channels = p.contract.channels.map(ch => `${ch.kind} "${ch.name}" v${ch.version}`).join(", ")
+      info(`${c.bold(p.id)}  ${c.dim(channels)}`)
+      for (const f of p.written) log(c.green(`  written   ${f}`))
+      for (const f of p.stale) log(c.red(`  stale     ${f}`))
+      for (const f of p.fresh) log(c.dim(`  fresh     ${f}`))
+    }
+    for (const failure of report.failures) log(c.red(failure))
+
+    const stale = report.plugins.reduce((n, p) => n + p.stale.length, 0)
+    if (report.failures.length) throw new CliError(`${report.failures.length} contract${report.failures.length === 1 ? "" : "s"} did not generate.`)
+    if (stale) throw new CliError(`${stale} generated file${stale === 1 ? " is" : "s are"} stale — run \`lecodes plugin gen\` and commit.`)
+    success(flags.check ? "Every generated file is fresh." : "Generated.")
+  },
+})
+
+export default defineCommand({
+  name: "plugin",
+  summary: "Write a native plugin: gen",
+  description: "For the author of a plugin — a capability an app reaches the same way on iOS, Android and the web. `lecodes app` is the other side: it installs plugins into an app's shell.",
+  commands: [gen],
+})

package/src/commands/render.ts

@@ -14,7 +14,7 @@ import { loadPeer } from "../hosts/peerInstall"
 /*
  * `lecodes render` — compile the local project and render it headless. By default it emits a
  * semantic JSON description (stdout or -o/--out); `--png [file]` also rasterizes a PNG. Rendering
- * runs locally via the optional `lecodes-renderer` package (canvas-ui + the layout WASM, and the
+ * runs locally via the optional `lecodes-headless` package (canvas-ui + the layout WASM, and the
  * GPU-free creator-2d WASM for 2D scenes); PNG also needs @napi-rs/canvas. UI and 2D (creator-2d)
  * scenes are both rendered — the 2D scene composites UNDER the UI. 3D (Filament) isn't rasterized,
  * but the scene graph is recorded and serialized into the JSON output as `scene3d` (hierarchy,
@@ -30,12 +30,12 @@ import { loadPeer } from "../hosts/peerInstall"
  *
  * `--script <file>` switches to an interactive run: the file lists steps (tap / type / scroll /
  * wait / expect / screenshot / json) executed against a live session — see the scenario schema in
- * lecodes-renderer (headless/scenario.ts). Step outputs land under --out-dir (default: the CWD);
+ * lecodes-headless (headless/scenario.ts). Step outputs land under --out-dir (default: the CWD);
  * the run stops at the first failed step and dumps the failing frame next to them.
  *
  * `--desktop` renders through the NATIVE desktop host instead of the headless renderer — the real
  * tgfx UI + Filament 3D + creator-2d pipeline, composited exactly as desktop users see it. PNG only
- * (the host has no semantic-JSON serializer), no lecodes-renderer / @napi-rs/canvas needed. The
+ * (the host has no semantic-JSON serializer), no lecodes-headless / @napi-rs/canvas needed. The
  * host binary downloads on first use (see desktopRenderer.ts); Windows + Linux for now.
  *
  * Works in both server-backed projects (login) and local `lecodes init` projects (no login) — see
@@ -65,6 +65,7 @@ export const viewportFlags = {
 /** `--desktop`: the NATIVE host in place of the headless renderer. */
 export const desktopRenderFlags = {
   desktop: bool("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)"),
+  sim: bool("run a --script scenario through the WINDOWLESS native host (lecodes-server, beside the desktop host; LECODES_SERVER_EXE overrides): the real engine — Jolt, animators, navmesh — with no GPU and no pixels, so it runs on a CI box or a container and in parallel with an open desktop window. expect.log / expect.paint only; input is scene input (key/look/stick/drag/tap by { x, y } straight to the scene — no UI, so no names, hover or type); no screenshots, no --png"),
   frames: num("(--desktop) frames to run before the shot — headroom for async loads", { default: 60 }),
   "fixed-dt": num("(--desktop) virtual app clock, ms per frame — deterministic game time (scripted runs default to 16; plain renders to wall clock)", { value: "<ms>" }),
   renderer: str("(--desktop) host + shader variant: gl | vulkan (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
@@ -100,8 +101,8 @@ export const resolveSafeAreaChoice = (explicit: string | undefined, device: stri
 }
 
 /** The optional renderer package — installed into ~/.lecodes/peers on first use (peerInstall.ts). */
-export const requireRenderer = async (): Promise<typeof import("lecodes-renderer/headless")> =>
-  loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes render" })
+export const requireRenderer = async (): Promise<typeof import("lecodes-headless/headless")> =>
+  loadPeer<typeof import("lecodes-headless/headless")>("lecodes-headless", "headless", { for: "lecodes render" })
 
 /** A file-writing ScenarioIO rooted at `dir` (creates parent folders as needed). */
 export const fileScenarioIO = (dir: string) => ({
@@ -130,7 +131,7 @@ type ScenarioFile = {
 export const resolveFixtures = (
   value: Record<string, unknown> | string | undefined,
   baseDir: string,
-): import("lecodes-renderer/headless").Fixtures | undefined => {
+): import("lecodes-headless/headless").Fixtures | undefined => {
   if (value === undefined) return undefined
   let map: unknown = value
   if (typeof value === "string") {
@@ -144,7 +145,7 @@ export const resolveFixtures = (
   if (typeof map !== "object" || map === null || Array.isArray(map)) {
     throw new CliError(`Fixtures must be an object mapping URL patterns to { status?, json?, text? }.`)
   }
-  return map as import("lecodes-renderer/headless").Fixtures
+  return map as import("lecodes-headless/headless").Fixtures
 }
 
 const readScenarioFile = (path: string): ScenarioFile => {
@@ -188,7 +189,7 @@ const renderFlags = {
   map: str("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; also a { \"map\": \"f.png\" } script step)", { value: "[file]", optional: true }),
   "label-all": bool("(--map) label every object, not only the named markers"),
   "max-px": num("(--map) longest edge of the map image, px"),
-  script: str("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). With --desktop: 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", { value: "<file>" }),
+  script: str("drive the app through a step list (tap/type/fill/scroll/hover/wait/expect/screenshot/json steps; games: frames/drag/hold/key/keyDown/keyUp, expect.log, screenshot clip). With --desktop the same steps, targets (a name or { x, y }) and expects run on the native host — only expect.audio and the json output are headless-only; per-step screenshots + final --png", { value: "<file>" }),
   "out-dir": str("where --script step outputs land", { value: "<dir>", default: "." }),
   clip: str("(--png) crop to one node's rect or a logical-px rect — a component / region render", { value: "<name|x,y,w,h>" }),
   fixtures: str("canned fetch responses (URL pattern → { status?, json?, text? }) — make backend-gated screens reachable headless; merged over the scenario file's own", { value: "<file>" }),
@@ -211,7 +212,7 @@ export default defineCommand({
   name: "render",
   summary: "Render the local project headless (JSON / PNG), or through the desktop host",
   usage: "[file]",
-  description: "Needs the optional lecodes-renderer package (installed on first use). [file] renders 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.\n\nasset() resources load from the working tree by default; --remote-assets / --public-url use the server's copies (then data needs --wait-network).",
+  description: "Needs the optional lecodes-headless package (installed on first use). [file] renders 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.\n\nasset() resources load from the working tree by default; --remote-assets / --public-url use the server's copies (then data needs --wait-network).",
   flags: renderFlags,
   examples: [
     "lecodes render -o ui.json",
@@ -220,7 +221,7 @@ export default defineCommand({
     "lecodes render --script tests/hero.flow.json --out-dir tests/.shots --logs",
     "lecodes render --desktop --png --view iso",
   ],
-  run: ({ args, flags }) => flags.desktop ? renderDesktop(flags, args[0]) : renderHeadless(flags, args[0]),
+  run: ({ args, flags }) => flags.desktop || flags.sim ? renderDesktop(flags, args[0]) : renderHeadless(flags, args[0]),
 })
 
 // ---- --desktop -------------------------------------------------------------------------------
@@ -259,6 +260,10 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
   // runs the same bundle, so a design screen renders through the real tgfx UI here.
   const screen = screenTargetFrom(root, { file, state: flags.state, entry: flags.entry, dir: flags.dir })
   const scenario = flags.script !== undefined ? readScenarioFile(flags.script) : null
+  // --sim: the windowless host — a scripted run judged by its log; nothing to render without a script.
+  const sim = flags.sim
+  if (sim && !scenario) throw new CliError("--sim runs a --script scenario (the windowless host paints nothing to render) — add --script <file>, or use --desktop for a PNG.")
+  if (sim && flags.png) throw new CliError("--sim produces no PNG (the windowless host paints nothing) — drop --png, or use --desktop.")
   const width = flags.width || scenario?.width || screen?.frame?.[0] || win?.width || 390
   const height = flags.height || scenario?.height || screen?.frame?.[1] || win?.height || 844
   const frames = flags.frames || 60
@@ -285,18 +290,19 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
   })
   // The host writes PNGs but never creates folders — make every output dir up front.
-  mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
+  if (!sim) mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
 
   if (scenario) {
     // Scripted native run: translate the scenario into the host's command file, let the host drive
     // it (it self-terminates), then read its markers back into per-step results.
     const outDir = flags["out-dir"]
-    const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames })
+    const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames, sim })
     for (const st of plan.steps) if (st.screenshot) mkdirSync(dirname(st.screenshot), { recursive: true })
     const timeoutMs = flags.timeout || (60000 + plan.steps.length * 5000)
-    note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (native)…`)
+    const label = sim ? "sim" : "native"
+    note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (${label})…`)
     const { output } = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer, pluginDirs,
+      renderer: desktopRenderer, host: sim ? "server" : "desktop", pluginDirs,
       width, height, frames: plan.frameCap, outPng: pngFlag, logs, timeoutMs, script: plan.text, fixedDtMs,
     })
     const result = evaluateDesktopRun(plan, output)
@@ -310,8 +316,8 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
     const skippedCount = result.steps.reduce((n, s) => n + s.skipped.length, 0)
     if (skippedCount > 0) logErr(c.dim(`  ${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped — the native host has no UI tree; run the same scenario headless to verify them.`))
     if (!result.ended) warnErr("The host stopped before the script finished (frame cap / crash) — later steps are reported as incomplete.")
-    logErr(result.ok ? c.green(`✓ ${result.steps.length}/${result.steps.length} steps passed (native)`) : c.red(`✗ ${result.steps.filter((s) => !s.ok).length} of ${result.steps.length} steps failed (native)`))
-    note(`Wrote ${pngFlag} (${width}x${height}, native render, final frame)`)
+    logErr(result.ok ? c.green(`✓ ${result.steps.length}/${result.steps.length} steps passed (${label})`) : c.red(`✗ ${result.steps.filter((s) => !s.ok).length} of ${result.steps.length} steps failed (${label})`))
+    if (!sim) note(`Wrote ${pngFlag} (${width}x${height}, native render, final frame)`)
     process.exit(result.ok ? 0 : 1)
   }
 

package/src/commands/scene.ts

@@ -124,13 +124,18 @@ export default defineCommand({
   run: async ({ args, flags }) => {
     const ctx = getContext(args[0])
     const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes scene" })
+    // The harness (the editor's half inside the scene's world) ships with the editor: the bundle is
+    // compiled with the one of the package the UI is served from.
+    if (typeof sceneServer.sceneHarness !== "function") {
+      throw new CliError("The installed lecodes-3d-editor is older than this CLI: it carries no scene harness (0.9.0 has one). Run `lecodes update`.")
+    }
     if (countScenes(ctx.root) === 0) warnErr(`No .scene.ts file under ${ctx.root} yet — add one and the editor will pick it up.`)
 
     const server = await sceneServer.startSceneServer({
       root: ctx.root,
       port: flags.port,
       log: note,
-      compile: (scenePath: string) => compileSceneEditor({ root: ctx.root, manifest: ctx.manifest, name: ctx.name, scenePath }),
+      compile: (scenePath: string) => compileSceneEditor({ root: ctx.root, manifest: ctx.manifest, name: ctx.name, scenePath, harness: sceneServer.sceneHarness() }),
       // live material patches load a shader's compiled artifact (matc'd for the Rendered mode,
       // the lite JSON otherwise) from the local shader cache
       shaderArtifact: (shaderText, platform) => localShaderArtifact(ctx.root, shaderText, platform),

package/src/commands/serve.ts

@@ -0,0 +1,58 @@
+import { basename } from "node:path"
+import { CliError, defineCommand, note, num, str } from "../cli"
+import { runDesktopApp } from "../hosts/desktopRenderer"
+import { desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { buildBundle } from "./compile"
+import { lanCandidates } from "./dev"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
+
+/*
+ * `lecodes serve` — run the current project as a dedicated multiplayer server (docs/multiplayer-plan.md):
+ * the WINDOWLESS native host (lecodes-server, beside the desktop host) with `--server`, so the app's
+ * `Net.launch.role` is "server" and its `Net.listen()` opens the port. No window, no GPU: the same
+ * engine as the desktop (Jolt, animators, navmesh) on Filament's NOOP backend, paced at 60 Hz on
+ * the wall clock. The process is the server — Ctrl+C tears the endpoint down (every client gets
+ * `disconnect`) and exits. `--connect` runs the same host as a headless CLIENT instead: a bot, or a
+ * scripted test player for a server under test.
+ */
+export default defineCommand({
+  name: "serve",
+  summary: "Run the current project as a dedicated multiplayer server (windowless host: no window, no GPU)",
+  description: "Compiles the project like `desktop run` and starts it in the windowless host with --server, so the app's Net.launch.role is \"server\" and its Net.listen() opens the port for clients (`desktop run --connect <ip:port>` on the same LAN, or a published game). Prints the LAN addresses clients can dial. The host runs the real engine without a GPU, so it also runs on a CI box or a container.\n\n--connect turns the same host into a headless client (a bot / a scripted test player) instead of a server.",
+  flags: {
+    port: num("listen port", { default: 40000 }),
+    "max-clients": num("client slots", { default: 16 }),
+    connect: str("join a server as a headless client instead of serving", { value: "<ip:port>" }),
+    ...bundleFlags,
+  },
+  examples: ["lecodes serve", "lecodes serve --port 7777 --max-clients 32", "lecodes serve --connect 192.168.1.10:40000"],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const appCfg = readAppConfigAt(root)
+    if (flags.port < 1 || flags.port > 65535) throw new CliError(`--port must be 1..65535 (got ${flags.port}).`)
+    if (flags["max-clients"] < 1 || flags["max-clients"] > 64) throw new CliError(`--max-clients must be 1..64 (yojimbo's cap; got ${flags["max-clients"]}).`)
+    // The renderer decides which .filamat gets staged; the NOOP backend accepts either, so the
+    // project's usual choice is fine — and it keeps the server bundle byte-identical to the desktop's.
+    const renderer = resolveDesktopRenderer(root, undefined)
+    const { js, resources } = await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer: renderer })
+    const { dirs: pluginDirs, files: pluginFiles } = desktopPluginLibraries(root)
+    if (pluginFiles.length > 0) note(`Native plugins: ${pluginFiles.map((f) => basename(f)).join(", ")}`)
+    const client = flags.connect !== undefined
+    if (client) {
+      note(`Joining ${flags.connect} as a headless client… (Ctrl+C to leave)`)
+    } else {
+      const lan = lanCandidates()
+      note(`Serving on port ${flags.port} (${flags["max-clients"]} slots)… (Ctrl+C to stop)`)
+      if (lan.length > 0) note(`Clients dial: ${lan.map((l) => `${l.address}:${flags.port}`).join("  ")}  (127.0.0.1:${flags.port} on this machine)`)
+    }
+    await runDesktopApp(js, resources, {
+      host: "server",
+      renderer,
+      pluginDirs,
+      storageScope: appCfg?.name,
+      net: client
+        ? { role: "client", address: flags.connect }
+        : { role: "server", port: flags.port, maxClients: flags["max-clients"] },
+    })
+  },
+})

package/src/commands/shaders/new.ts

@@ -19,7 +19,7 @@ import { CliError } from "../../cli"
 export const engineMaterialsDir = (): string | null => {
   const candidates = [
     join(distRoot, "runtime", "materials"),
-    join(distRoot, "..", "creator-gl", "materials", "src"),
+    join(distRoot, "..", "..", "engines", "gl", "materials", "src"),
   ]
   for (const c of candidates) if (existsSync(join(c, "unlit.mat"))) return c
   return null