lecodes-cli 2.4.10 → 2.5.1

package/src/commands/lightmap.ts

@@ -1,4 +1,4 @@
-import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { basename, dirname, join, relative, resolve, sep } from "node:path"
 import { deflateSync } from "node:zlib"
@@ -8,6 +8,7 @@ import { runDesktopRender } from "../hosts/desktopRenderer"
 import { loadPeer } from "../hosts/peerInstall"
 import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr } from "../cli"
 import { bundleFlags, bundleOptions, localProject } from "./shared"
+import { decodeStatics, encodeStatics, stitchStatics } from "lecodes-sdk/compile"
 
 /*
  * `lecodes lightmap` — the baked lighting of a level (engines/bake).
@@ -29,9 +30,10 @@ import { bundleFlags, bundleOptions, localProject } from "./shared"
  * The bake is not in the shipped desktop / server hosts: it runs in lecodes-bake (hosts/desktop CREATOR_DESKTOP_BAKE),
  * the windowless host with the bake built in — resolved by hosts/desktopRenderer.ts resolveBakeExe (LECODES_BAKE_EXE
  * for a local build, else the published release product "bake").
- * Lightmap UVs: before the host runs, every GLB the app references that has none is unwrapped IN PLACE (lecodes-assets
- * `unwrapGlbFiles`, what `lecodes assets unwrap` runs — the pre-step below); `--no-unwrap` skips it. A level in one GLB
- * that wants groups or a zone is unwrapped by hand first (`lecodes assets unwrap --groups`), and then left alone here.
+ * Lightmap UVs: a static without TEXCOORD_1 is unwrapped BY THE BAKE (creator-bake unwrap.cpp): its charts go into the
+ * -uv1.bin sidecar with the split geometry the runtime rebuilds the primitive from, and no GLB of the project is ever
+ * written. Vegetation (the foliage tier) is never unwrapped: it reads the ground's light. A file that carries its own
+ * lightmap uvs (`lecodes assets unwrap`, another tool) keeps them: the bake packs those charts as they are.
  */
 
 const range = (name: string, value: number, min: number, max: number): number => {
@@ -78,6 +80,18 @@ const cubePatternsOf = (argv: string[]): string[] => {
   return out.filter((p) => p !== "")
 }
 
+/** The static level cache beside a bake (`<stem>.static`, written by `lecodes level build`) takes the fresh bake's records:
+ *  a pure join by node path, no host run — the next load rebuilds the statics with the new rects. Nothing to do without one. */
+export const stitchLevelCache = (root: string, staticPath: string, bake: BakeData): void => {
+  if (!existsSync(staticPath)) return
+  const file = decodeStatics(new Uint8Array(readFileSync(staticPath)))
+  if (!file) { warnErr(`${relative(root, staticPath)} is not a level cache of this version — rerun \`lecodes level build\``); return }
+  const stitched = stitchStatics(file, bake)
+  writeFileSync(staticPath, encodeStatics(stitched))
+  const records = stitched.placements.reduce((n, p) => n + p.records.length, 0)
+  logErr(c.dim(`  level cache ${relative(root, staticPath).replace(/\\/g, "/")}: ${records} record(s) of this bake stitched in (${stitched.placements.length} placements)`))
+}
+
 /** The stem of a `.bake` path: `assets/lightmap/level.bake` → `level`. */
 const stemOf = (path: string): string => basename(path).replace(/\.bake$/i, "")
 
@@ -118,80 +132,10 @@ const bakeFileOf = (root: string, flag: string | undefined): string => {
   return resolve(root, found[0])
 }
 
-// ---- the unwrap pre-step --------------------------------------------------------------------------
-// The bake traces TEXCOORD_1, and a raw import has none: before the host runs, the GLBs the bundle names (asset()
-// compiles to `_creatorFetch.local("<name>")` — the reference list `app build desktop` ships by) whose JSON shows a
-// primitive the unwrap would lay out without one are unwrapped IN PLACE by lecodes-assets (`unwrapGlbFiles`, the
-// `lecodes assets unwrap` code). Nothing is rebuilt after it: the bundle names the files and carries none of their bytes,
-// and the run dir links them only when the host starts. A file that has TEXCOORD_1 is never opened past its JSON.
-
-type GltfJson = {
-  nodes?: { mesh?: number, skin?: number }[]
-  meshes?: { primitives?: { mode?: number, indices?: number, attributes?: Record<string, number> }[] }[]
-  accessors?: { count?: number }[]
-}
-
-/** A GLB's JSON chunk — the 20 header bytes and the chunk itself, never the binary one — or null when it is not a GLB. */
-const readGlbJson = (file: string): GltfJson | null => {
-  let fd: number | undefined
-  try {
-    fd = openSync(file, "r")
-    const head = Buffer.alloc(20)
-    if (readSync(fd, head, 0, 20, 0) !== 20) return null
-    if (head.readUInt32LE(0) !== 0x46546c67 || head.readUInt32LE(16) !== 0x4e4f534a) return null   // "glTF", then a "JSON" chunk
-    const json = Buffer.alloc(head.readUInt32LE(12))
-    if (readSync(fd, json, 0, json.length, 20) !== json.length) return null
-    return JSON.parse(json.toString("utf8")) as GltfJson
-  } catch {
-    return null
-  } finally {
-    if (fd !== undefined) closeSync(fd)
-  }
-}
-
-/** A primitive the unwrap lays out (a triangle list with a triangle in it, on a mesh no skinned node draws) without
- *  TEXCOORD_1 — lecodes-assets' planUnwrap verdict, read off the JSON. */
-const lacksLightmapUv = (g: GltfJson): boolean => {
-  const skinned = new Set((g.nodes ?? []).filter((n) => n.skin !== undefined && n.mesh !== undefined).map((n) => n.mesh))
-  const count = (accessor: number | undefined): number => (accessor === undefined ? 0 : g.accessors?.[accessor]?.count ?? 0)
-  return (g.meshes ?? []).some((mesh, i) => !skinned.has(i) && (mesh.primitives ?? []).some((p) => {
-    const pos = count(p.attributes?.POSITION)
-    return (p.mode ?? 4) === 4 && pos > 0 && (p.indices === undefined ? pos : count(p.indices)) >= 3 && p.attributes?.TEXCOORD_1 === undefined
-  }))
-}
-
-/** The project GLBs the bundle names. */
-const referencedGlbs = (js: string, resources: BundleResource[]): string[] => {
-  const wanted = new Set([ ...js.matchAll(/(?:fetchLocal|_creatorFetch\.local)\("([^"]+)"\)/g) ].map((m) => m[1]))
-  return [ ...new Set(resources.filter((r) => !r.remote && !r.shader && r.absPath && /\.glb$/i.test(r.name) && wanted.has(r.name)).map((r) => r.absPath!)) ]
-}
-
-const unwrapReferenced = async (js: string, resources: BundleResource[], root: string, texel: number): Promise<void> => {
-  const glbs = referencedGlbs(js, resources)
-  const raw = glbs.filter((f) => { const g = readGlbJson(f); return g !== null && lacksLightmapUv(g) })
-  if (raw.length === 0) { note(`Lightmap uvs: the ${glbs.length} GLB(s) the app references carry them`); return }
-  note(`Unwrapping ${raw.length} of the ${glbs.length} GLB(s) the app references — no lightmap uvs; written in place (--no-unwrap skips)…`)
-  const assets = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes lightmap bake (lightmap uvs)" })
-  if (typeof assets.unwrapGlbFiles !== "function") {
-    throw new CliError("The lecodes-assets this CLI loaded has no unwrapGlbFiles (it predates the bake's unwrap) — `lecodes update` moves it forward; --no-unwrap bakes the GLBs as they are.")
-  }
-  const t0 = performance.now()
-  const rel = (f: string): string => relative(root, f).replace(/\\/g, "/")
-  const reports = await assets.unwrapGlbFiles(raw, {
-    texel,
-    onFile: (r) => {
-      if (r.status === "failed") warnErr(`${rel(r.input)}: ${r.summary} — it bakes without lightmap uvs`)
-      else logErr(c.dim(`  ${r.status === "unwrapped" ? "unwrapped " : ""}${rel(r.input)}: ${r.summary}`))
-    },
-  })
-  const count = (s: string): number => reports.filter((r) => r.status === s).length
-  note(`Lightmap uvs: ${count("unwrapped")} file(s) unwrapped${count("skipped") ? `, ${count("skipped")} had nothing to unwrap` : ""}${count("failed") ? `, ${count("failed")} failed` : ""} in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
-}
-
 const bake = defineCommand({
   name: "bake",
   summary: "Bake the sun, the sky and the lamps into a lux atlas for the level's statics",
-  description: "Runs the app in bake mode in lecodes-bake — the windowless host with the bake built in (no physics, 2D, audio, net or navmesh), downloaded on first use like the desktop host; LECODES_BAKE_EXE points at a local build (hosts/desktop build.ps1 -Bake). The statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Needs a GPU with hardware ray tracing (--tracer).\n\nWhere: the level's own bake('<dir>/<stem>.bake') — env: { lightmap: bake('./assets/lightmap/level.bake') } in a scene file, the path relative to that file — names the target; nothing has to exist before the first bake. Writes into <dir>: <stem>.bake (the manifest: it names every file below, and the next compile reads it — nothing to paste into the scene) + <stem>-light[_n].ktx2 (irradiance, BC6H, a page per _n) + <stem>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <stem>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none) + <stem>.lgrid (the light grid the movers read; --volume 0 = none) + <stem>-uv1.bin (the packed lightmap uv1 the rects map) + with --split <stem>-direct[_n].ktx2 / <stem>-indirect[_n].ktx2.\n\nLightmap UVs: the GLBs the app references that have none (TEXCOORD_1) are unwrapped first, IN PLACE \u2014 the same as lecodes assets unwrap, run on just those files; a file that has them is left alone, --no-unwrap skips the step. A whole level in one GLB that wants --groups / --zone is unwrapped by hand first (lecodes assets unwrap --help).",
+  description: "Runs the app in bake mode in lecodes-bake — the windowless host with the bake built in (no physics, 2D, audio, net or navmesh), downloaded on first use like the desktop host; LECODES_BAKE_EXE points at a local build (hosts/desktop build.ps1 -Bake). The statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Needs a GPU with hardware ray tracing (--tracer).\n\nWhere: the level's own bake('<dir>/<stem>.bake') — env: { lightmap: bake('./assets/lightmap/level.bake') } in a scene file, the path relative to that file — names the target; nothing has to exist before the first bake. Writes into <dir>: <stem>.bake (the manifest: it names every file below, and the next compile reads it — nothing to paste into the scene) + <stem>-light[_n].ktx2 (irradiance, BC6H, a page per _n) + <stem>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <stem>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none) + <stem>.lgrid (the light grid the movers read; --volume 0 = none) + <stem>-uv1.bin (the packed lightmap uv1 the rects map) + with --split <stem>-direct[_n].ktx2 / <stem>-indirect[_n].ktx2.\n\nLightmap UVs: a static without TEXCOORD_1 is unwrapped by the bake itself; its charts land in <stem>-uv1.bin with the split geometry the runtime rebuilds the primitive from, and no GLB of the project is written. Vegetation (foliage: true) is never unwrapped: it reads the ground's light. A GLB that carries lightmap uvs of its own (lecodes assets unwrap) keeps them.",
   flags: {
     out: str("write the files into this folder instead of next to the level's .bake (a second seed for `lightmap diff`)", { value: "<dir>" }),
     name: str("bake the level whose bake() names <stem>.bake — when the entry reaches several", { value: "<stem>" }),
@@ -222,7 +166,7 @@ const bake = defineCommand({
     "probe-layout": str("rooms = every indoor point of the grid slides to the middle of its room and the points of one room merge: one probe per room, far from the walls, its box the room (stations every ~8 m along a room over 12 m), outdoor points stay on the grid; grid = everything stays on the grid. Either way the pages carry which probes each block of texels sees (rays at bake time)", { value: "<rooms|grid>", default: "rooms" }),
     "min-texels": num("instances smaller than this many ATLAS TEXELS along every axis (x --texel: 12 at 5 cm = 0.6 m) get no place in the atlas: they still cast their baked shadow and bounce, their own light is baked where they stand (six sides, no atlas texels) — cartridges, boxes, pipe elbows, a fire extinguisher: a baked shadow does not read on them and their tight charts are where the seams are. 0 = everything bakes; --dry-run lists what falls under it", { default: 12 }),
     "thin-texels": num("ROUND AND NARROW objects leave the atlas like --min-texels: an instance none of whose lightmap charts is wider than this many texels across its short side (at --texel) — a railing's tubes, a cable, a pipe run, blinds, a gun barrel. A strip of 1-3 texels around a tube cannot hold the light's change around it and its uv seam shows as a step (a railing: two texels 5 mm apart on the seam, one lit, one shadowed); the ambient cube baked where it stands is smooth. A flat object has a wide chart somewhere and stays. 0 = off; --dry-run lists what falls under it", { default: 4 }),
-    cube: str("BAKE AS CUBES BY NAME: a regular expression (ECMAScript, case-sensitive) searched in every record's key — <node path>@<ordinal>, one record per mesh of a model, so SM_pipe takes every pipe node and @1$ the second mesh of each. A record that matches leaves the atlas like a --min-texels / --thin-texels one, whatever its size or charts: an occluder whose own light is baked where it stands as ambient cubes (in slabs along a long one, --object-slab) — a pipe run, a fence, a prop whose lightmap seams show. Repeat the flag (--cube SM_pipe --cube SM_fence) or join with | in one (--cube \"SM_pipe|SM_fence\", quoted for the shell); a pattern that starts with - goes as --cube=<regex>. The level's bake() option cube adds its own patterns, a node's lightmap: 'cube' marks one node by hand; --dry-run lists what matches", { value: "<regex>" }),
+    cube: str("BAKE AS CUBES BY NAME: a regular expression (ECMAScript, case-sensitive) searched in every record's key — <node path>@<ordinal>, one record per node primitive of a model, so SM_pipe takes every pipe node and @1$ the second node primitive of each. A record that matches leaves the atlas like a --min-texels / --thin-texels one, whatever its size or charts: an occluder whose own light is baked where it stands as ambient cubes (in slabs along a long one, --object-slab) — a pipe run, a fence, a prop whose lightmap seams show. Repeat the flag (--cube SM_pipe --cube SM_fence) or join with | in one (--cube \"SM_pipe|SM_fence\", quoted for the shell); a pattern that starts with - goes as --cube=<regex>. The level's bake() option cube adds its own patterns, a node's lightmap: 'cube' marks one node by hand; --dry-run lists what matches", { value: "<regex>" }),
     "object-slab": num("A LONG object the atlas left out (--min-texels, --thin-texels, --cube) takes its light in SLABS of this many metres along the longest axis of its bounds — round(length / this) ambient cubes, 16 at most — a 6 m pipe run, a railing along a wall: one end under a lamp, the other in the dark, where one cube gave all of it the mean. The shader blends the two slabs around each pixel along that axis. 0 = one cube an object", { value: "<m>", default: 1 }),
     "emissive-nits": num("EMISSIVE SURFACES LIGHT THE LEVEL: cd/m² of emission 1.0 (emissive factor x strength x map) — every lit region of an emissive surface (a panel drawn in a ceiling's texture, a screen, a sign) bakes as a rectangle lamp. Default: what the level's camera makes of 1.0, 1.2 x 2^EV100, so a panel lights as brightly as it looks. 0 = emissive surfaces light nothing"),
     "detail-texels": num("A SMALL SURFACE GETS A FINER TEXEL: an instance whose surface is under this many atlas texels (area / texel²) is laid out denser by sqrt(this / its texels), 3x at most — a pipe of 1 m is ~300 texels at 5 cm, its charts a few texels wide and every chart edge a step; at 2000 it bakes at ~2 cm. 0 = off", { default: 2000 }),
@@ -236,7 +180,6 @@ const bake = defineCommand({
     height: num("the bake host's virtual viewport height (default: app.json desktop.window, else 720)"),
     renderer: str("ignored: the bake host is one binary (lecodes-bake, GL shaders on Filament's NOOP backend); kept so older scripts still parse", { value: "<gl|vulkan>" }),
     logs: bool("forward the host's output"),
-    "no-unwrap": bool("leave the referenced GLBs as they are: no lightmap unwrap of those without TEXCOORD_1 (they bake without lightmap uvs)"),
   },
   examples: [
     "lecodes lightmap bake",
@@ -305,6 +248,7 @@ const bake = defineCommand({
     const entryPath = "/.lightmap-entry.ts"
     const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
 
+    const tCommand = Date.now()
     const desktopRenderer = "gl" as const   // lecodes-bake is the GL tree on Filament's NOOP backend: `_creator.backend` "desktop" fetches the GL shaders
     const { js, resources, bakes } = await buildBundle(bundleOptions(flags), {
       localAssets: true, desktopRenderer,
@@ -318,7 +262,6 @@ const bake = defineCommand({
     mkdirSync(outDir, { recursive: true })
     if (debugDir) mkdirSync(debugDir, { recursive: true })
     note(`Target: ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")}${target.exists ? "" : " (the first bake: nothing there yet)"}${flags.out ? " (--out)" : ""}`)
-    if (!flags["no-unwrap"]) await unwrapReferenced(js, resources, root, cfg.texel)
 
     // The host writes the bake itself; the PNG the render driver insists on goes to a scratch dir.
     const scratch = mkdtempSync(join(tmpdir(), "lecodes-lightmap-"))
@@ -327,11 +270,18 @@ const bake = defineCommand({
     note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.skyRays} sky + ${cfg.lightRays} lamp rays${bounce}) → ${relative(root, outDir).split(sep).join("/") || "."}/${stem}.*…`)
     let output = ""
     if (flags["dry-run"]) process.env.CBK_LAYOUT_ONLY = "1"   // the host inherits it: creator-bake stops after the layout
+    // the wall clock: when the host's marker lines arrive (the compile is reported by the compile itself)
+    const tCompiled = Date.now()
+    const marks: Record<string, number> = {}
+    const MARKS: [RegExp, string][] = [[/initial\.js evaluated/, "up"], [/\[glb\] loads:/, "glb"], [/\[lightmap\] describing/, "level"], [/\[lightmap\] described in/, "described"], [/\[lightmap\] (done|error)\s*$/m, "done"]]
+    // the adapter's own `[lightmap] done` line ends the run - not creator-bake's "done: N page(s)…" summary, which comes first
+    const ended = (text: string) => /\[lightmap\] (done|error)\s*$/m.test(text) || /\[lightmap\] error:/.test(text)
     try {
       const timeoutMs = flags.timeout || 24 * 3600 * 1000
       const res = await runDesktopRender(js, resources, {
         host: "bake", renderer: desktopRenderer, width, height, frames, outPng, logs: flags.logs, timeoutMs,
-        stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
+        onChunk: (chunk) => { for (const [re, key] of MARKS) if (!(key in marks) && re.test(chunk)) marks[key] = Date.now() },
+        stopOnLine: ended,
       })
       output = res.output
     } catch (e) {
@@ -348,6 +298,17 @@ const bake = defineCommand({
       if (text === "done") continue
       logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
     }
+    {
+      // the command's wall clock, stage by stage (each from the previous mark; a stage whose mark never came is left out)
+      const tEnd = Date.now()
+      const secs = (ms: number) => `${(ms / 1000).toFixed(1)} s`
+      const stages: [string, number | undefined, number | undefined][] = [
+        ["compile", tCommand, tCompiled], ["host up", tCompiled, marks.up], ["glb loaded", marks.up, marks.glb], ["level built (js)", marks.glb, marks.level],
+        ["described", marks.level, marks.described], ["creator-bake", marks.described, marks.done], ["host stopped + files", marks.done, tEnd],
+      ]
+      const parts = stages.filter(([, a, b]) => a !== undefined && b !== undefined).map(([name, a, b]) => `${name} ${secs(b! - a!)}`)
+      logErr(c.dim(`  wall clock ${secs(tEnd - tCommand)}: ${parts.join(", ")}`))
+    }
     if (flags["dry-run"] && /\[lightmap\] done/.test(output)) {
       for (const l of lines) if (/atlas \d+ x|packed per file|largest rect|do not fit|fill:|--cube|lightmap: 'cube'/.test(l)) logErr(l.replace(/^\[lightmap\] /, "  "))
       logErr(c.green("✓ layout only — nothing written"))
@@ -364,6 +325,7 @@ const bake = defineCommand({
         ? `  written to --out: the level's bake() still reads ${target.path}`
         : `  the manifest names them: the next compile of ${entryFile} stages them (bake('…') in the scene reads it)`))
       if (debugDir) logErr(c.dim(`  debug layers: ${relative(root, debugDir)} (lecodes lightmap inspect --bake ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")} --debug-dir ${relative(root, debugDir).replace(/\\/g, "/")})`))
+      stitchLevelCache(root, join(outDir, `${stem}.static`), data)
       return
     }
     if (/\[lightmap\] error: this host has no bake module/.test(output)) {   // console.error: the host prefixes the line ("[ERROR] [lightmap] …")

package/src/commands/navmesh.ts

@@ -45,7 +45,7 @@ type BakeConfigLine = {
 }
 
 /** The first `*.scene.ts` under src/ (or the root) that declares `navmesh:` names the output by default. */
-const guessName = (root: string): string | null => {
+export const guessNavmeshName = (root: string): string | null => {
   const dirs = [ join(root, "src"), root ]
   for (const dir of dirs) {
     if (!existsSync(dir)) continue
@@ -63,7 +63,7 @@ const guessName = (root: string): string | null => {
 
 /** An empty LNAV (header only, one dummy tile slot) so the compiler can stage the file before the
  *  first bake; NavMesh.load reads `stats.polys === 0` as "placeholder — rebake". */
-const placeholderLnav = (): Buffer => {
+export const placeholderLnav = (): Buffer => {
   const json = Buffer.from(JSON.stringify({ version: 1, placeholder: true, stats: { tiles: 0, polys: 0 } }), "utf8")
   const jsonPadded = Buffer.alloc(Math.ceil(json.length / 4) * 4)
   json.copy(jsonPadded)
@@ -88,15 +88,8 @@ const writeObj = (path: string, tris: Float32Array): void => {
   writeFileSync(path, lines.join("\n") + "\n")
 }
 
-const bake = defineCommand({
-  name: "bake",
-  summary: "Build the level's navigation mesh for NavAgent / NavMesh",
-  description: "The desktop host dumps every STATIC body's collision triangles at the scene's env.navmesh (or NavMesh.load) point, then Recast builds the tiled mesh here → <out>/<name>.navmesh. The agent size defaults to what the scene declares. Needs a desktop host with the geometry dump (LECODES_DESKTOP_EXE for a local build).",
-  flags: {
-    out: str("where it lands", { value: "<dir>", default: "assets/nav" }),
-    name: str("file name (default: the scene file that declares navmesh:, else scene)", { value: "<n>" }),
-    ...bundleFlags,
-    entry: str("the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load", { value: "<file>", default: "main.ts" }),
+/** The Recast parameters `navmesh bake` and `level build` share. */
+export const NAVMESH_FLAGS = {
     radius: num("agent radius (m; default: the scene's)"),
     height: num("agent height (m; default: the scene's)"),
     climb: num("agent max step height (m; default: the scene's)"),
@@ -112,63 +105,17 @@ const bake = defineCommand({
     "detail-error": num("detail mesh max error (voxels)", { default: 1 }),
     obj: bool("also write <name>.navmesh.obj to inspect the polygons"),
     "keep-geometry": bool("keep the host's <name>.navgeo dump"),
-    frames: num("host frames to run before giving up — load headroom", { default: 900 }),
-    timeout: num("host time cap (ms)", { default: 600000 }),
-    width: num("host window width (default: app.json desktop.window, else 1280)"),
-    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
-    logs: bool("forward the host's output"),
-  },
-  examples: ["lecodes navmesh bake", "lecodes navmesh bake --name yard --cell 0.2 --obj --logs"],
-  run: async ({ flags }) => {
-    const { root } = localProject()
-    const outDir = resolve(root, flags.out)
-    const entryFile = flags.entry
-    if (!existsSync(resolve(root, entryFile))) {
-      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load).`)
-    }
-    const name = flags.name ?? guessName(root) ?? "scene"
-    const frames = range("frames", flags.frames, 900, 30, 100000)
-    const win = readAppConfigAt(root)?.desktop?.window
-    const width = flags.width || win?.width || 1280
-    const height = win?.height || 720
-    const logs = flags.logs
-
-    // The navmesh file must exist BEFORE the compile: the scene references it through asset(), and a
-    // missing asset is a broken bundle. The first bake starts from a placeholder the real file overwrites.
-    mkdirSync(outDir, { recursive: true })
-    const navmeshPath = join(outDir, `${name}.navmesh`)
-    if (!existsSync(navmeshPath)) writeFileSync(navmeshPath, placeholderLnav())
-
-    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
-    const entryPath = "/.navmesh-entry.ts"
-    const cfg = { outDir: outDir.replace(/\\/g, "/"), name }
-    const entryText = `globalThis.__lecodesNavmesh = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
-
-    const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
-    const { js, resources } = await buildBundle(bundleOptions(flags), {
-      localAssets: true, desktopRenderer,
-      extraEntries: [{ path: entryPath, type: "text", text: entryText }],
-      entryOverride: entryPath,
-    })
-
-    const scratch = mkdtempSync(join(tmpdir(), "lecodes-navmesh-"))
-    const outPng = join(scratch, "frame.png")
-    note(`Dumping the level's static collision geometry through the desktop host → ${relative(root, outDir) || "."}/${name}.navgeo…`)
-    let output = ""
-    try {
-      const res = await runDesktopRender(js, resources, {
-        renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs: flags.timeout || 600000,
-        stopOnLine: (chunk) => chunk.includes("[navmesh] done") || chunk.includes("[navmesh] error"),
-      })
-      output = res.output
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e)
-      if (!/\[navmesh\] done/.test(msg)) throw e
-      output = msg
-    } finally {
-      rmSync(scratch, { recursive: true, force: true })
-    }
+}
+export type NavmeshFlags = {
+  radius?: number, height?: number, climb?: number, slope?: number, cell?: number, "cell-height"?: number, tile?: number
+  "region-min"?: number, "region-merge"?: number, "edge-max"?: number, "edge-error"?: number, detail?: number, "detail-error"?: number
+  obj?: boolean, "keep-geometry"?: boolean
+}
 
+/** From the host's output to `<outDir>/<name>.navmesh`: the `[navmesh]` lines read, the geometry dump handed to Recast.
+ *  Shared by `navmesh bake` and `level build` (one host run serves both the navmesh and the static level cache). */
+export const finishNavmesh = async (root: string, outDir: string, name: string, output: string, flags: NavmeshFlags): Promise<void> => {
+  const navmeshPath = join(outDir, `${name}.navmesh`)
     // the markers are console.log lines from the SDK — the host prefixes them ("[DEBUG] [navmesh] …")
     const lines = output.split(/\r?\n/).filter((l) => l.includes("[navmesh]")).map((l) => l.slice(l.indexOf("[navmesh]")))
     let config: BakeConfigLine | null = null
@@ -245,6 +192,76 @@ const bake = defineCommand({
     if (!config.data) {
       logErr(c.dim(`  load it with env.navmesh: { data: asset('<rel>/${basename(navmeshPath)}') } in the scene file, or NavMesh.load(scene, { data: asset(...) })`))
     }
+}
+
+const bake = defineCommand({
+  name: "bake",
+  summary: "Build the level's navigation mesh for NavAgent / NavMesh",
+  description: "The desktop host dumps every STATIC body's collision triangles at the scene's env.navmesh (or NavMesh.load) point, then Recast builds the tiled mesh here → <out>/<name>.navmesh. The agent size defaults to what the scene declares. Needs a desktop host with the geometry dump (LECODES_DESKTOP_EXE for a local build).",
+  flags: {
+    out: str("where it lands", { value: "<dir>", default: "assets/nav" }),
+    name: str("file name (default: the scene file that declares navmesh:, else scene)", { value: "<n>" }),
+    ...bundleFlags,
+    entry: str("the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load", { value: "<file>", default: "main.ts" }),
+    ...NAVMESH_FLAGS,
+    frames: num("host frames to run before giving up — load headroom", { default: 900 }),
+    timeout: num("host time cap (ms)", { default: 600000 }),
+    width: num("host window width (default: app.json desktop.window, else 1280)"),
+    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    logs: bool("forward the host's output"),
+  },
+  examples: ["lecodes navmesh bake", "lecodes navmesh bake --name yard --cell 0.2 --obj --logs"],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const outDir = resolve(root, flags.out)
+    const entryFile = flags.entry
+    if (!existsSync(resolve(root, entryFile))) {
+      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load).`)
+    }
+    const name = flags.name ?? guessNavmeshName(root) ?? "scene"
+    const frames = range("frames", flags.frames, 900, 30, 100000)
+    const win = readAppConfigAt(root)?.desktop?.window
+    const width = flags.width || win?.width || 1280
+    const height = win?.height || 720
+    const logs = flags.logs
+
+    // The navmesh file must exist BEFORE the compile: the scene references it through asset(), and a
+    // missing asset is a broken bundle. The first bake starts from a placeholder the real file overwrites.
+    mkdirSync(outDir, { recursive: true })
+    const navmeshPath = join(outDir, `${name}.navmesh`)
+    if (!existsSync(navmeshPath)) writeFileSync(navmeshPath, placeholderLnav())
+
+    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+    const entryPath = "/.navmesh-entry.ts"
+    const cfg = { outDir: outDir.replace(/\\/g, "/"), name }
+    const entryText = `globalThis.__lecodesNavmesh = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
+
+    const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
+    const { js, resources } = await buildBundle(bundleOptions(flags), {
+      localAssets: true, desktopRenderer,
+      extraEntries: [{ path: entryPath, type: "text", text: entryText }],
+      entryOverride: entryPath,
+    })
+
+    const scratch = mkdtempSync(join(tmpdir(), "lecodes-navmesh-"))
+    const outPng = join(scratch, "frame.png")
+    note(`Dumping the level's static collision geometry through the desktop host → ${relative(root, outDir) || "."}/${name}.navgeo…`)
+    let output = ""
+    try {
+      const res = await runDesktopRender(js, resources, {
+        renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs: flags.timeout || 600000,
+        stopOnLine: (chunk) => chunk.includes("[navmesh] done") || chunk.includes("[navmesh] error"),
+      })
+      output = res.output
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/\[navmesh\] done/.test(msg)) throw e
+      output = msg
+    } finally {
+      rmSync(scratch, { recursive: true, force: true })
+    }
+
+    await finishNavmesh(root, outDir, name, output, flags)
   },
 })
 

package/src/commands/secrets.ts

@@ -0,0 +1,147 @@
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { join, relative } from "node:path"
+import { ENV_NAME, isPublicEnvName, isServerPath, scanEnvReads } from "lecodes-sdk/compile"
+import { CliError, UsageError, bool, c, defineCommand, info, log, note, promptHidden, relativeTime, str, success, table } from "../cli"
+import { listSecrets, removeSecret, setSecret } from "../platform/api"
+import { readAppEnv } from "../project/env"
+import { linkedProject } from "./shared"
+
+/*
+ * `lecodes secrets` — the project's keys on le.codes (Project Settings → Keys), what server code reads
+ * as `env.NAME` and the app as `env.PUBLIC_NAME`. On this machine the same keys live in the project's
+ * `.env`; this command carries them to the platform (never back: a value is set, replaced or removed,
+ * the platform shows no value). `list` is the one place both sides are seen together with what the
+ * code reads, so a missing key is found before a build says so.
+ */
+
+const SKIP_DIRS = new Set(["node_modules", ".lecodes", ".git", "dist", "design"])
+
+/** Every `env.NAME` read in the project's code: name → "server" | "app" | "both". */
+export const readsOf = (root: string): Map<string, "server" | "app" | "both"> => {
+  const out = new Map<string, "server" | "app" | "both">()
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith("_") || entry.startsWith(".") || SKIP_DIRS.has(entry)) continue
+      const path = join(dir, entry)
+      let isDir = false
+      try { isDir = statSync(path).isDirectory() } catch { continue }
+      if (isDir) { walk(path); continue }
+      if (!/\.[tj]s$/.test(entry) || entry.endsWith(".d.ts")) continue
+      const side = isServerPath(path) ? "server" : "app"
+      let text = ""
+      try { text = readFileSync(path, "utf8") } catch { continue }
+      for (const name of scanEnvReads(text)) {
+        const had = out.get(name)
+        out.set(name, had && had !== side ? "both" : side)
+      }
+    }
+  }
+  walk(root)
+  return out
+}
+
+const checkName = (name: string | undefined): string => {
+  if (!name) throw new UsageError("A key name is needed: lecodes secrets set NAME")
+  if (!ENV_NAME.test(name)) throw new CliError(`"${name}" is not a key name — capital letters, digits and underscores (STRIPE_KEY, PUBLIC_MAPS_KEY)`)
+  return name
+}
+
+const list = defineCommand({
+  name: "list",
+  summary: "The project's keys: on le.codes, in .env, and what the code reads",
+  run: async () => {
+    const { root, manifest, apiUrl, token } = linkedProject()
+    // the platform lists a name the code reads before anyone set it (`set: false`): here the code is scanned on disk
+    const remote = new Map((await listSecrets(apiUrl, token, manifest.uuid)).filter(s => s.set !== false).map(s => [s.name, s]))
+    const local = readAppEnv(root)
+    const reads = readsOf(root)
+    const names = [...new Set([...remote.keys(), ...Object.keys(local), ...reads.keys()])].sort()
+    if (!names.length) { info("No keys: none on le.codes, none in .env, none read by the code."); return }
+    const rows = names.map(name => {
+      const r = remote.get(name)
+      const by = reads.get(name)
+      const flag = by && !r ? c.yellow("missing on le.codes") : by && !(name in local) ? c.dim("not in .env") : ""
+      return [name, r ? `le.codes ${c.dim(relativeTime(r.updatedAt))}` : c.dim("—"), name in local ? ".env" : c.dim("—"), by ? `read by ${by === "both" ? "server + app" : by}` : c.dim("not read"), flag]
+    })
+    table(rows)
+    const secretsInApp = names.filter(n => !isPublicEnvName(n) && (reads.get(n) === "app" || reads.get(n) === "both"))
+    if (secretsInApp.length) log(c.red(`  ${secretsInApp.join(", ")}: read by app code — a key that is not PUBLIC_* is a secret; read it in a *.server.ts file`))
+    note("A value never comes back from le.codes: `secrets set NAME --from-env` sends the .env one, `secrets push` sends them all.")
+  },
+})
+
+const set = defineCommand({
+  name: "set",
+  summary: "Set (or replace) a key on le.codes",
+  usage: "<NAME>",
+  flags: {
+    "from-env": bool("Take the value from the project's .env instead of asking"),
+    value: str("The value itself (visible in the shell history — prefer the prompt or --from-env)", { value: "<value>", optional: true }),
+  },
+  description: "The value is asked for without echo unless --from-env (the .env line of that name) or --value gives it. Only the project's owner may set a key; a developer sees the names (`list`).",
+  run: async ({ args, flags }) => {
+    const name = checkName(args[0])
+    const { root, manifest, apiUrl, token } = linkedProject()
+    let value = flags.value
+    if (flags["from-env"]) {
+      const local = readAppEnv(root)
+      if (!(name in local)) throw new CliError(`${name} is not in ${relative(process.cwd(), join(root, ".env")) || ".env"} — add a line \`${name}=value\` first`)
+      value = local[name]
+    }
+    if (value === undefined) {
+      if (!process.stdin.isTTY) throw new CliError("No terminal to ask the value in: pass --from-env or --value")
+      value = await promptHidden(`Value for ${name}`)
+    }
+    if (!value) throw new CliError("An empty value — nothing set")
+    await setSecret(apiUrl, token, manifest.uuid, name, value)
+    success(`${name} set on le.codes — ${isPublicEnvName(name) ? "the app gets it with its next build" : "the server gets it with the next build"}`)
+  },
+})
+
+const remove = defineCommand({
+  name: "remove",
+  summary: "Remove a key from le.codes (the .env line stays)",
+  usage: "<NAME>",
+  aliases: ["rm", "delete"],
+  run: async ({ args }) => {
+    const name = checkName(args[0])
+    const { manifest, apiUrl, token } = linkedProject()
+    await removeSecret(apiUrl, token, manifest.uuid, name)
+    success(`${name} removed from le.codes`)
+  },
+})
+
+const push = defineCommand({
+  name: "push",
+  summary: "Send every key of the project's .env to le.codes",
+  usage: "[NAME...]",
+  description: "Every app key of .env (the capital names that are not the CLI's LECODES_* / CREATOR_*), or only the names given. A key already on le.codes is replaced.",
+  run: async ({ args }) => {
+    const { root, manifest, apiUrl, token } = linkedProject()
+    const local = readAppEnv(root)
+    const names = args.length ? args.map(checkName) : Object.keys(local).sort()
+    if (!names.length) { info("Nothing to send: .env has no app keys (a capital NAME=value line)."); return }
+    for (const name of names) {
+      if (!(name in local)) throw new CliError(`${name} is not in .env`)
+      await setSecret(apiUrl, token, manifest.uuid, name, local[name])
+      log(`  ${c.green("set")}  ${name}`)
+    }
+    success(`${names.length} key${names.length === 1 ? "" : "s"} on le.codes — picked up with the next build`)
+  },
+})
+
+export default defineCommand({
+  name: "secrets",
+  summary: "The project's keys on le.codes (env.NAME in code)",
+  aliases: ["keys"],
+  description: "A key — a token, a client secret, a maps key — is read in code as env.NAME: every key in *.server.ts files, only PUBLIC_* ones in the app (its bundle is public). On this machine the keys live in the project's .env (NAME=value, never pushed); on le.codes in Project Settings → Keys, which these commands edit. A value never comes back from le.codes.\n\nNames are capital letters, digits and underscores. `lecodes dev` and the builds say which key the code reads and does not have.",
+  commands: [list, set, remove, push],
+  examples: [
+    "lecodes secrets list",
+    "lecodes secrets set STRIPE_KEY              # asks for the value, no echo",
+    "lecodes secrets set STRIPE_KEY --from-env   # the .env line",
+    "lecodes secrets push                        # every .env key",
+    "lecodes secrets remove STRIPE_KEY",
+  ],
+  run: (ctx) => list.run!(ctx),
+})