lecodes-cli 0.20.1 → 1.0.0

package/src/commands/lightmap.ts

@@ -2,11 +2,11 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, s
 import { spawn, spawnSync } from "node:child_process"
 import { tmpdir } from "node:os"
 import { join, relative, resolve } from "node:path"
-import { findProjectRoot } from "../manifest"
 import { buildBundle } from "./compile"
-import { readAppConfigAt, resolveDesktopRenderer } from "./appShared"
-import { runDesktopRender } from "../desktopRenderer"
-import { CliError, c, flagStr, flagBool, logErr, note, warnErr, type Args } from "../util"
+import { readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { CliError, bool, c, defineCommand, logErr, note, num, str, warnErr } from "../cli"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
 
 /*
  * `lecodes lightmap bake` — bake static shadows, ambient occlusion and the level's point lights for
@@ -33,12 +33,11 @@ import { CliError, c, flagStr, flagBool, logErr, note, warnErr, type Args } from
  * The props need lightmap UVs first: `lecodes assets doctor assets/props/*.glb --lightmap-uv`.
  */
 
-const num = (args: Args, key: string, fallback: number, min: number, max: number): number => {
-  const raw = flagStr(args, key)
-  if (raw === undefined) return fallback
-  const n = Number(raw)
-  if (!Number.isFinite(n) || n < min || n > max) throw new CliError(`--${key} wants a number in ${min}..${max}, got "${raw}".`)
-  return n
+/** A numeric flag the bake hands to the tracer: the framework parses it, the range is checked here
+ *  (a texel size of 0 or 10 000 sun rays is a mistake, not a setting). */
+const range = (name: string, value: number, min: number, max: number): number => {
+  if (value < min || value > max) throw new CliError(`--${name} wants a number in ${min}..${max}, got "${value}".`)
+  return value
 }
 
 // ---- toktx (KTX-Software) — same lookup as lecodes-assets' doctor --------------------------------
@@ -92,162 +91,6 @@ const encodeKtx2 = (toktx: string, png: string, ktx2: string): Promise<void> =>
 const pageFile = (stem: string, page: number, light: boolean, ext = ".ktx2"): string =>
   `${stem}${light ? "-light" : ""}${page > 0 ? `_${page}` : ""}${ext}`
 
-const bake = async (args: Args): Promise<void> => {
-  let root: string
-  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
-  const toktx = requireToktx()
-  const outDir = resolve(root, flagStr(args, "out") ?? "assets/lightmap")
-  const stem = flagStr(args, "name") ?? "lightmap"
-  if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
-  const entryFlag = flagStr(args, "entry")
-  const entryFile = entryFlag ?? "main.ts"
-  if (!existsSync(resolve(root, entryFile))) {
-    throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
-  }
-  const cfg = {
-    outDir: outDir.replace(/\\/g, "/"),
-    size: num(args, "size", 4096, 256, 16384),
-    texel: num(args, "texel", 0.02, 0.001, 2),
-    // atlas PAGES: the bake fills up to this many atlases of --size at the requested texel before it
-    // coarsens; every page is one more texture the scene lists under env.lightmap.texture
-    pages: num(args, "pages", 4, 1, 16),
-    sunRays: num(args, "sun-rays", 32, 1, 1024),
-    aoRays: num(args, "ao-rays", 64, 1, 4096),
-    aoDistance: num(args, "ao-distance", 2, 0.01, 1000),
-    bias: num(args, "bias", 0.02, 0.0001, 1),
-    sunAngle: num(args, "sun-angle", 0.5, 0.01, 30),
-    // point lights: shadow rays per light per texel, toward a disc of this radius at the light
-    lightRays: num(args, "light-rays", 16, 1, 256),
-    lightRadius: num(args, "light-radius", 0.1, 0.001, 5),
-    // One bounce of indirect from the lamps, gathered on the AO rays (the albedo it assumes for
-    // every surface it hits). Off by default: it is the difference between "a room lit by its
-    // lamps" and "lit fixtures in a black room", but it costs a full Intersect per AO ray.
-    bounce: num(args, "bounce", 0, 0, 1),
-    bounceDistance: num(args, "bounce-distance", 8, 0.5, 100),
-    bounceRays: num(args, "bounce-rays", 1, 1, 32),
-    coplanarSkip: num(args, "coplanar-skip", 0.05, 0, 1),
-    // geometry-aware denoise of the traced texels (radius in px; 0 = off)
-    denoise: num(args, "denoise", 2, 0, 4),
-    // the light volume for dynamic objects (docs/lightmap-plan.md §9); 0 = skip it
-    volumeCell: flagBool(args, "no-volume") ? 0 : num(args, "cell", 0.5, 0.05, 20),
-  }
-  const frames = num(args, "frames", 900, 30, 100000)
-  const win = readAppConfigAt(root)?.desktop?.window
-  const width = Number(flagStr(args, "width")) || win?.width || 1280
-  const height = Number(flagStr(args, "height")) || win?.height || 720
-  const logs = flagBool(args, "logs")
-
-  // The synthetic entry: bake mode flag first, then the real entry. It lives at the project root so
-  // the real entry's own relative imports resolve unchanged.
-  const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
-  const entryPath = "/.lightmap-entry.ts"
-  const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
-
-  // The bake files must exist BEFORE the compile: the scene references them through asset(), and
-  // a missing asset is a broken bundle (chisel emits the constant after its use — a TDZ crash at
-  // boot, seen 2026-08-26). The first bake starts from placeholders the real files overwrite;
-  // Lightmap.load on a placeholder applies nothing and says "rebake".
-  mkdirSync(outDir, { recursive: true })
-  ensurePlaceholders(outDir, stem)
-
-  const desktopRenderer = resolveDesktopRenderer(root, args)
-  const { js, resources } = await buildBundle(args, undefined, {
-    localAssets: true, desktopRenderer,
-    extraEntries: [{ path: entryPath, type: "text", text: entryText }],
-    entryOverride: entryPath,
-  })
-
-  // 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-"))
-  const outPng = join(scratch, "frame.png")
-  note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.aoRays} AO + ${cfg.lightRays} light rays)${cfg.volumeCell ? ` + a ${cfg.volumeCell} m light volume` : ""} → ${relative(root, outDir) || "."}/${stem}.*…`)
-  let output = ""
-  try {
-    // A bake is not interactive and a large level traces for a long time: no timeout unless asked
-    // (the host prints its progress once a second — a silent host is the thing to watch, not the clock).
-    const timeoutMs = Number(flagStr(args, "timeout")) || 24 * 3600 * 1000
-    const res = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs,
-      // the bake is synchronous inside Lightmap.load — once the marker is out there is nothing to wait for
-      stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
-      // no script: the frame cap ends the run once Lightmap.load has fired (the bake is synchronous)
-    })
-    output = res.output
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e)
-    // A run that baked and then hit the cap without a PNG is still a success — check the markers.
-    if (!/\[lightmap\] done/.test(msg)) throw e
-    output = msg
-  } finally {
-    try { rmSync(scratch, { recursive: true, force: true }) } catch { /* a killed host may hold the dir a moment longer */ }
-  }
-
-  const lines = output.split(/\r?\n/).filter((l) => l.startsWith("[lightmap]"))
-  for (const l of lines) {
-    const text = l.slice("[lightmap]".length).trim()
-    if (text === "done") continue
-    logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
-  }
-  if (/\[lightmap\] done/.test(output)) {
-    // the host writes `lightmap.*`; the stem is the CLI's, applied while the PNGs turn into KTX2
-    const bakePath = join(outDir, "lightmap.bake")
-    if (!existsSync(bakePath)) throw new CliError(`The host reported a bake but ${bakePath} is missing.`)
-    const data = JSON.parse(readFileSync(bakePath, "utf8")) as { pages?: number, textures?: string[], lightTextures?: string[], volume?: { file: string }, texture?: string }
-    const pages = Math.max(1, data.pages ?? 1)
-    const hasLight = !!data.lightTextures?.length
-    const t0 = Date.now()
-    let pngKb = 0, ktxKb = 0
-    const encodePage = async (page: number, light: boolean): Promise<void> => {
-      const png = join(outDir, pageFile("lightmap", page, light, ".png"))
-      const ktx2 = join(outDir, pageFile(stem, page, light))
-      if (!existsSync(png)) throw new CliError(`The host reported a bake but ${png} is missing.`)
-      await encodeKtx2(toktx, png, ktx2)
-      pngKb += statSync(png).size / 1024; ktxKb += statSync(ktx2).size / 1024
-      unlinkSync(png)
-    }
-    const encodes: Promise<void>[] = []
-    for (let p = 0; p < pages; p++) {
-      encodes.push(encodePage(p, false))
-      if (hasLight) encodes.push(encodePage(p, true))
-    }
-    await Promise.all(encodes)
-    // a page the previous bake had and this one does not: keep the file a scene may still list, as a placeholder
-    for (let p = pages; p < 16; p++) {
-      for (const light of [ false, true ]) {
-        const stale = join(outDir, pageFile(stem, p, light))
-        if (existsSync(stale) && statSync(stale).size !== PLACEHOLDER_KTX2.length) writeFileSync(stale, PLACEHOLDER_KTX2)
-      }
-    }
-    if (!hasLight) {
-      // no point lights in the level: a light atlas the scene may still reference goes back to a placeholder
-      const light = join(outDir, pageFile(stem, 0, true))
-      if (existsSync(light) && statSync(light).size !== PLACEHOLDER_KTX2.length) writeFileSync(light, PLACEHOLDER_KTX2)
-    }
-    // the .bake names the encoded files under the stem
-    data.texture = pageFile(stem, 0, false)
-    data.textures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, false))
-    if (hasLight) data.lightTextures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, true))
-    if (data.volume) data.volume.file = `${stem}.volume`
-    writeFileSync(join(outDir, `${stem}.bake`), JSON.stringify(data, null, 1) + "\n")
-    if (stem !== "lightmap") unlinkSync(bakePath)
-    const volumeSrc = join(outDir, "lightmap.volume")
-    const hasVolume = cfg.volumeCell > 0 && existsSync(volumeSrc)
-    if (hasVolume && stem !== "lightmap") { rmSync(join(outDir, `${stem}.volume`), { force: true }); renameSync(volumeSrc, join(outDir, `${stem}.volume`)) }
-    logErr(c.dim(`  encoded ${pages} page(s)${hasLight ? " + the light atlas" : ""} (UASTC + mips, ${Math.round(ktxKb)} KB from ${Math.round(pngKb)} KB of rasters) in ${((Date.now() - t0) / 1000).toFixed(1)} s`))
-    logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.textures.join(", ")}${hasLight ? ` + ${data.lightTextures!.join(", ")}` : ""}${hasVolume ? ` + ${stem}.volume` : ""}`))
-    const rel = (f: string): string => relative(root, join(outDir, f)).replace(/\\/g, "/")
-    const assets = (files: string[]): string => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f) => `asset('<rel>/${rel(f)}')`).join(", ")}]`
-    logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), texture: ${assets(data.textures)}${hasLight ? `, light: ${assets(data.lightTextures!)}` : ""}${hasVolume ? `, volume: asset('<rel>/${rel(`${stem}.volume`)}')` : ""} }  — asset() paths are relative to the scene file`))
-    return
-  }
-  if (lines.some((l) => /no bake module/.test(l))) {
-    throw new CliError("This desktop host has no bake module. Build packages/desktop (CREATOR_GL_LIGHTMAP is on there) 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 baking. Make sure the app calls Lightmap.load(...) after the static scene is built, and skips menus when Lightmap.baking is true (a title screen never reaches the scene). More load headroom: --frames <n>. Host output: --logs.")
-  throw new CliError("Nothing was baked.")
-}
-
 /** A 1x1 white UASTC KTX2 (the atlas' "no shadow, no occlusion" value; toktx v4.4.2, sRGB) + an empty
  *  bake — enough for the compiler to stage the files and for Lightmap.load to no-op with a "rebake"
  *  warning. */
@@ -283,8 +126,197 @@ const ensurePlaceholders = (outDir: string, stem: string): void => {
   if (missing(volume)) writeFileSync(volume, placeholderVolume())
 }
 
-export const lightmap = async (args: Args): Promise<void> => {
-  const sub = args._[0]
-  if (sub === "bake") return bake({ ...args, _: args._.slice(1) })
-  throw new CliError("Usage: lecodes lightmap bake [--out assets/lightmap] [--name lightmap] [--size 4096] [--pages 4] [--texel 0.02] [--sun-rays 32] [--ao-rays 64] [--ao-distance 2] [--bias 0.02] [--sun-angle 0.5] [--light-rays 16] [--light-radius 0.1] [--bounce 0..1] [--denoise 2] [--cell 0.5 | --no-volume] [--frames 900] [--timeout <ms>] [--entry main.ts] [--logs]   (needs KTX-Software's toktx)")
-}
+const bake = defineCommand({
+  name: "bake",
+  summary: "Bake static shadows + ambient occlusion (+ point lights) into a KTX2 lightmap atlas",
+  description: "Runs the app in the desktop host in bake mode: the statics are what the app registers with Lightmap.add, the bake fires at its Lightmap.load call. Writes <out>/<name>.bake + <name>[_n].ktx2 (+ <name>-light[_n].ktx2 for point lights, <name>.volume for movers). Needs KTX-Software's toktx on PATH (or KTX_TOKTX) and a desktop host with the bake module (LECODES_DESKTOP_EXE for a local build).\n\nProps need lightmap UVs first: lecodes assets doctor assets/props/*.glb --lightmap-uv",
+  flags: {
+    out: str("where the atlas lands", { value: "<dir>", default: "assets/lightmap" }),
+    name: str("file stem — one per baked level", { value: "<stem>", default: "lightmap" }),
+    ...bundleFlags,
+    entry: str("the file that builds the scene and calls Lightmap.load", { value: "<file>", default: "main.ts" }),
+    size: num("atlas edge (px)", { default: 4096 }),
+    texel: num("texel density (m per texel)", { default: 0.02 }),
+    pages: num("atlas pages to fill before the bake coarsens the texel", { default: 4 }),
+    "sun-rays": num("sun shadow rays per texel", { default: 32 }),
+    "ao-rays": num("ambient-occlusion rays per texel", { default: 64 }),
+    "ao-distance": num("AO reach (m)", { default: 2 }),
+    bias: num("ray start offset from the surface (m)", { default: 0.02 }),
+    "sun-angle": num("sun angular diameter (deg) — soft shadow edge", { default: 0.5 }),
+    "light-rays": num("point lights: shadow rays per light per texel", { default: 16 }),
+    "light-radius": num("point lights: source disc radius (m)", { default: 0.1 }),
+    bounce: num("one indirect bounce from the lamps, 0..1 = the albedo assumed for every surface (0 = off)", { default: 0 }),
+    "bounce-distance": num("(--bounce) gather reach (m)", { default: 8 }),
+    "bounce-rays": num("(--bounce) gather rays per AO ray", { default: 1 }),
+    "coplanar-skip": num("ignore hits closer than this fraction of the texel (self-shadowing on coplanar faces)", { default: 0.05 }),
+    denoise: num("geometry-aware denoise radius (px, 0 = off)", { default: 2 }),
+    cell: num("light-volume cell size for movers (m)", { default: 0.5 }),
+    "no-volume": bool("skip the light volume"),
+    frames: num("host frames to run before giving up — load headroom", { default: 900 }),
+    timeout: num("host time cap (ms; default: none)"),
+    width: num("host window width (default: app.json desktop.window, else 1280)"),
+    height: num("host window height (default: app.json desktop.window, else 720)"),
+    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 lightmap bake", "lecodes lightmap bake --name yard --size 2048 --texel 0.05 --logs", "lecodes lightmap bake --bounce 0.5 --no-volume"],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const toktx = requireToktx()
+    const outDir = resolve(root, flags.out)
+    const stem = flags.name
+    if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
+    const entryFile = flags.entry
+    if (!existsSync(resolve(root, entryFile))) {
+      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
+    }
+    const cfg = {
+      outDir: outDir.replace(/\\/g, "/"),
+      size: range("size", flags.size, 256, 16384),
+      texel: range("texel", flags.texel, 0.001, 2),
+      // atlas PAGES: the bake fills up to this many atlases of --size at the requested texel before it
+      // coarsens; every page is one more texture the scene lists under env.lightmap.texture
+      pages: range("pages", flags.pages, 1, 16),
+      sunRays: range("sun-rays", flags["sun-rays"], 1, 1024),
+      aoRays: range("ao-rays", flags["ao-rays"], 1, 4096),
+      aoDistance: range("ao-distance", flags["ao-distance"], 0.01, 1000),
+      bias: range("bias", flags.bias, 0.0001, 1),
+      sunAngle: range("sun-angle", flags["sun-angle"], 0.01, 30),
+      // point lights: shadow rays per light per texel, toward a disc of this radius at the light
+      lightRays: range("light-rays", flags["light-rays"], 1, 256),
+      lightRadius: range("light-radius", flags["light-radius"], 0.001, 5),
+      // One bounce of indirect from the lamps, gathered on the AO rays (the albedo it assumes for
+      // every surface it hits). Off by default: it is the difference between "a room lit by its
+      // lamps" and "lit fixtures in a black room", but it costs a full Intersect per AO ray.
+      bounce: range("bounce", flags.bounce, 0, 1),
+      bounceDistance: range("bounce-distance", flags["bounce-distance"], 0.5, 100),
+      bounceRays: range("bounce-rays", flags["bounce-rays"], 1, 32),
+      coplanarSkip: range("coplanar-skip", flags["coplanar-skip"], 0, 1),
+      // geometry-aware denoise of the traced texels (radius in px; 0 = off)
+      denoise: range("denoise", flags.denoise, 0, 4),
+      // the light volume for dynamic objects (docs/lightmap-plan.md §9); 0 = skip it
+      volumeCell: flags["no-volume"] ? 0 : range("cell", flags.cell, 0.05, 20),
+    }
+    const frames = range("frames", flags.frames, 30, 100000)
+    const win = readAppConfigAt(root)?.desktop?.window
+    const width = flags.width || win?.width || 1280
+    const height = flags.height || win?.height || 720
+    const logs = flags.logs
+
+    // The synthetic entry: bake mode flag first, then the real entry. It lives at the project root so
+    // the real entry's own relative imports resolve unchanged.
+    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+    const entryPath = "/.lightmap-entry.ts"
+    const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
+
+    // The bake files must exist BEFORE the compile: the scene references them through asset(), and
+    // a missing asset is a broken bundle (chisel emits the constant after its use — a TDZ crash at
+    // boot, seen 2026-08-26). The first bake starts from placeholders the real files overwrite;
+    // Lightmap.load on a placeholder applies nothing and says "rebake".
+    mkdirSync(outDir, { recursive: true })
+    ensurePlaceholders(outDir, stem)
+
+    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,
+    })
+
+    // 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-"))
+    const outPng = join(scratch, "frame.png")
+    note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.aoRays} AO + ${cfg.lightRays} light rays)${cfg.volumeCell ? ` + a ${cfg.volumeCell} m light volume` : ""} → ${relative(root, outDir) || "."}/${stem}.*…`)
+    let output = ""
+    try {
+      // A bake is not interactive and a large level traces for a long time: no timeout unless asked
+      // (the host prints its progress once a second — a silent host is the thing to watch, not the clock).
+      const timeoutMs = flags.timeout || 24 * 3600 * 1000
+      const res = await runDesktopRender(js, resources, {
+        renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs,
+        // the bake is synchronous inside Lightmap.load — once the marker is out there is nothing to wait for
+        stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
+        // no script: the frame cap ends the run once Lightmap.load has fired (the bake is synchronous)
+      })
+      output = res.output
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      // A run that baked and then hit the cap without a PNG is still a success — check the markers.
+      if (!/\[lightmap\] done/.test(msg)) throw e
+      output = msg
+    } finally {
+      try { rmSync(scratch, { recursive: true, force: true }) } catch { /* a killed host may hold the dir a moment longer */ }
+    }
+
+    const lines = output.split(/\r?\n/).filter((l) => l.startsWith("[lightmap]"))
+    for (const l of lines) {
+      const text = l.slice("[lightmap]".length).trim()
+      if (text === "done") continue
+      logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
+    }
+    if (/\[lightmap\] done/.test(output)) {
+      // the host writes `lightmap.*`; the stem is the CLI's, applied while the PNGs turn into KTX2
+      const bakePath = join(outDir, "lightmap.bake")
+      if (!existsSync(bakePath)) throw new CliError(`The host reported a bake but ${bakePath} is missing.`)
+      const data = JSON.parse(readFileSync(bakePath, "utf8")) as { pages?: number, textures?: string[], lightTextures?: string[], volume?: { file: string }, texture?: string }
+      const pages = Math.max(1, data.pages ?? 1)
+      const hasLight = !!data.lightTextures?.length
+      const t0 = Date.now()
+      let pngKb = 0, ktxKb = 0
+      const encodePage = async (page: number, light: boolean): Promise<void> => {
+        const png = join(outDir, pageFile("lightmap", page, light, ".png"))
+        const ktx2 = join(outDir, pageFile(stem, page, light))
+        if (!existsSync(png)) throw new CliError(`The host reported a bake but ${png} is missing.`)
+        await encodeKtx2(toktx, png, ktx2)
+        pngKb += statSync(png).size / 1024; ktxKb += statSync(ktx2).size / 1024
+        unlinkSync(png)
+      }
+      const encodes: Promise<void>[] = []
+      for (let p = 0; p < pages; p++) {
+        encodes.push(encodePage(p, false))
+        if (hasLight) encodes.push(encodePage(p, true))
+      }
+      await Promise.all(encodes)
+      // a page the previous bake had and this one does not: keep the file a scene may still list, as a placeholder
+      for (let p = pages; p < 16; p++) {
+        for (const light of [ false, true ]) {
+          const stale = join(outDir, pageFile(stem, p, light))
+          if (existsSync(stale) && statSync(stale).size !== PLACEHOLDER_KTX2.length) writeFileSync(stale, PLACEHOLDER_KTX2)
+        }
+      }
+      if (!hasLight) {
+        // no point lights in the level: a light atlas the scene may still reference goes back to a placeholder
+        const light = join(outDir, pageFile(stem, 0, true))
+        if (existsSync(light) && statSync(light).size !== PLACEHOLDER_KTX2.length) writeFileSync(light, PLACEHOLDER_KTX2)
+      }
+      // the .bake names the encoded files under the stem
+      data.texture = pageFile(stem, 0, false)
+      data.textures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, false))
+      if (hasLight) data.lightTextures = Array.from({ length: pages }, (_, p) => pageFile(stem, p, true))
+      if (data.volume) data.volume.file = `${stem}.volume`
+      writeFileSync(join(outDir, `${stem}.bake`), JSON.stringify(data, null, 1) + "\n")
+      if (stem !== "lightmap") unlinkSync(bakePath)
+      const volumeSrc = join(outDir, "lightmap.volume")
+      const hasVolume = cfg.volumeCell > 0 && existsSync(volumeSrc)
+      if (hasVolume && stem !== "lightmap") { rmSync(join(outDir, `${stem}.volume`), { force: true }); renameSync(volumeSrc, join(outDir, `${stem}.volume`)) }
+      logErr(c.dim(`  encoded ${pages} page(s)${hasLight ? " + the light atlas" : ""} (UASTC + mips, ${Math.round(ktxKb)} KB from ${Math.round(pngKb)} KB of rasters) in ${((Date.now() - t0) / 1000).toFixed(1)} s`))
+      logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.textures.join(", ")}${hasLight ? ` + ${data.lightTextures!.join(", ")}` : ""}${hasVolume ? ` + ${stem}.volume` : ""}`))
+      const rel = (f: string): string => relative(root, join(outDir, f)).replace(/\\/g, "/")
+      const assets = (files: string[]): string => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f) => `asset('<rel>/${rel(f)}')`).join(", ")}]`
+      logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), texture: ${assets(data.textures)}${hasLight ? `, light: ${assets(data.lightTextures!)}` : ""}${hasVolume ? `, volume: asset('<rel>/${rel(`${stem}.volume`)}')` : ""} }  — asset() paths are relative to the scene file`))
+      return
+    }
+    if (lines.some((l) => /no bake module/.test(l))) {
+      throw new CliError("This desktop host has no bake module. Build packages/desktop (CREATOR_GL_LIGHTMAP is on there) 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 baking. Make sure the app calls Lightmap.load(...) after the static scene is built, and skips menus when Lightmap.baking is true (a title screen never reaches the scene). More load headroom: --frames <n>. Host output: --logs.")
+    throw new CliError("Nothing was baked.")
+  },
+})
+
+export default defineCommand({
+  name: "lightmap",
+  summary: "Bake static shadows + ambient occlusion into a lightmap atlas (bake)",
+  commands: [bake],
+})

package/src/commands/link.ts

@@ -1,16 +1,17 @@
 import { existsSync } from "node:fs"
 import { basename, join, resolve } from "node:path"
-import { createProject, getCommits, getProject, type Project, type ProjectAsset } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { ensureGitignore, writeDefaultIgnore } from "../ignore"
-import { scanProject } from "../localFiles"
-import { findProjectRoot, LECODES_DIR, writeManifest, type FileKind, type ManifestFile, type Manifest } from "../manifest"
-import { buildPaths } from "../project"
-import { computeServerDiff } from "../serverDiff"
-import { materializeTypes, writeTsconfig } from "../types"
-import { CliError, c, confirm, flagBool, flagStr, info, log, note, sha256, success, warn, type Args } from "../util"
+import { CliError, bool, c, confirm, defineCommand, info, log, note, str, success, warn } from "../cli"
+import { createProject, getCommits, getProject, type Project, type ProjectAsset } from "../platform/api"
+import { computeServerDiff } from "../platform/serverDiff"
+import { ensureGitignore, writeDefaultIgnore } from "../project/ignore"
+import { scanProject } from "../project/localFiles"
+import { findProjectRoot, LECODES_DIR, writeManifest, type FileKind, type Manifest, type ManifestFile } from "../project/manifest"
+import { buildPaths } from "../project/materialize"
+import { sha256 } from "../project/paths"
+import { materializeTypes, writeTsconfig } from "../project/types"
 import { parseUuid } from "./clone"
-import { push } from "./push"
+import { pushFlags, runPush } from "./push"
+import { session } from "./shared"
 
 /*
  * `lecodes link [dir]` — connect an existing local folder (typically one made by `lecodes init`) to
@@ -38,110 +39,102 @@ const manifestFromServer = (project: Project): Record<string, ManifestFile> => {
   const files: Record<string, ManifestFile> = {}
   for (const asset of project.assets) {
     if (asset.type === "folder") continue
-    files[pathById.get(asset.id)!] = {
-      id: asset.id,
-      type: kindOf(asset.type),
-      sha: asset.type === "file" ? "" : sha256(asset.text ?? ""),
-    }
+    files[pathById.get(asset.id)!] = { id: asset.id, type: kindOf(asset.type), sha: asset.type === "file" ? "" : sha256(asset.text ?? "") }
   }
   return files
 }
 
 /** Show what a push from this folder would do to the project's server tree, and get a yes. */
-const confirmAdoption = async (root: string, project: Project, files: Record<string, ManifestFile>, args: Args): Promise<boolean> => {
+const confirmAdoption = async (root: string, project: Project, files: Record<string, ManifestFile>, skipAsk: boolean): Promise<boolean> => {
   const count = Object.keys(files).length
-  if (count === 0) {
-    info(c.dim(`Project ${c.bold(project.name)} is empty on the server — nothing to overwrite.`))
-    return true
-  }
+  if (count === 0) { info(c.dim(`Project ${c.bold(project.name)} is empty on the server — nothing to overwrite.`)); return true }
 
   const scan = scanProject(root, { files } as Manifest)
   const diff = computeServerDiff(project, scan)
-  if (diff.length === 0) {
-    info(c.dim(`Project ${c.bold(project.name)} (${count} file(s)) already matches this folder.`))
-    return true
-  }
+  if (diff.length === 0) { info(c.dim(`Project ${c.bold(project.name)} (${count} file(s)) already matches this folder.`)); return true }
 
   warn(`${c.bold(project.name)} already has ${count} file(s). Your next push would change the server:`)
   const label: Record<string, string> = { added: c.green("  create  "), removed: c.red("  delete  "), modified: c.yellow("  update  ") }
   for (const e of diff) log(label[e.status] + e.path + (e.binary ? c.dim(" (binary)") : ""))
   log("")
   note("`lecodes pull` after linking takes the server's version instead.")
-
-  if (flagBool(args, "y", "yes") || flagBool(args, "force") || !process.stdin.isTTY) return true
+  if (skipAsk || !process.stdin.isTTY) return true
   return confirm("Link this folder to that project?", false)
 }
 
-export const link = async (args: Args) => {
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
-
-  const dirArg = args._[0]
-  const root = dirArg ? resolve(dirArg) : process.cwd()
-  if (!existsSync(root)) throw new CliError(`No such directory: ${root}`)
-
-  // Already linked? Re-linking silently would orphan the old project's history.
-  if (existsSync(join(root, LECODES_DIR, "manifest.json")) && !flagBool(args, "force")) {
-    throw new CliError("This folder is already linked (.lecodes/manifest.json exists) — use `lecodes push`, or `lecodes link --force` to re-link it to another project.")
-  }
-  // …or sitting inside a linked project, where a nested manifest would shadow the real root.
-  let enclosing: string | null = null
-  try { enclosing = findProjectRoot(root) } catch { /* not inside a project — the normal case */ }
-  if (enclosing && enclosing !== root) {
-    throw new CliError(`This folder is inside the linked project at ${enclosing} — push from there instead.`)
-  }
-
-  const projectRef = flagStr(args, "project")
-  let uuid: string
-  let name: string
-  let files: Record<string, ManifestFile>
-
-  if (projectRef) {
-    uuid = parseUuid(projectRef)
-    const project = await getProject(apiUrl, token, uuid)
-    if (project.role === "viewer") {
-      throw new CliError(`You have view-only access to ${project.name} — linking would give you a checkout you can't push.`)
+export default defineCommand({
+  name: "link",
+  summary: "Connect an existing local folder to the platform (the reverse of clone)",
+  usage: "[dir]",
+  description: "Creates a project on the server, writes .lecodes/manifest.json and refreshes the types; nothing is uploaded until you push, so `status` shows what would go up first. `--project` 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.",
+  flags: {
+    name: str("project name (default: the folder name)", { value: "<s>" }),
+    team: str("create it inside a team", { value: "<uuid>" }),
+    project: str("adopt an existing project instead of creating one", { value: "<uuid|url>" }),
+    push: bool("push right after linking (--publish to deploy it live in the same step)"),
+    "no-types": bool("skip the .d.ts / tsconfig refresh"),
+    ...pushFlags,
+  },
+  examples: ["lecodes link", "lecodes link --project <uuid> && lecodes status", 'lecodes link --push -m "initial"'],
+  run: async ({ args, flags }) => {
+    const { apiUrl, token } = session()
+    const dirArg = args[0]
+    const root = dirArg ? resolve(dirArg) : process.cwd()
+    if (!existsSync(root)) throw new CliError(`No such directory: ${root}`)
+
+    // Already linked? Re-linking silently would orphan the old project's history.
+    if (existsSync(join(root, LECODES_DIR, "manifest.json")) && !flags.force) {
+      throw new CliError("This folder is already linked (.lecodes/manifest.json exists) — use `lecodes push`, or `lecodes link --force` to re-link it to another project.")
+    }
+    // …or sitting inside a linked project, where a nested manifest would shadow the real root.
+    let enclosing: string | null = null
+    try { enclosing = findProjectRoot(root) } catch { /* not inside a project — the normal case */ }
+    if (enclosing && enclosing !== root) throw new CliError(`This folder is inside the linked project at ${enclosing} — push from there instead.`)
+
+    let uuid: string
+    let name: string
+    let files: Record<string, ManifestFile>
+    if (flags.project) {
+      uuid = parseUuid(flags.project)
+      const project = await getProject(apiUrl, token, uuid)
+      if (project.role === "viewer") throw new CliError(`You have view-only access to ${project.name} — linking would give you a checkout you can't push.`)
+      files = manifestFromServer(project)
+      if (!(await confirmAdoption(root, project, files, flags.yes || flags.force))) { info(c.dim("Aborted — nothing was linked.")); return }
+      name = project.name
+    } else {
+      name = flags.name ?? basename(root)
+      info(c.dim(`Creating project ${c.bold(name)}…`))
+      uuid = (await createProject(apiUrl, token, name, flags.team)).uuid
+      files = {}                                    // fresh project: the whole folder is a pending add
     }
-    files = manifestFromServer(project)
-    if (!(await confirmAdoption(root, project, files, args))) { info(c.dim("Aborted — nothing was linked.")); return }
-    name = project.name
-  } else {
-    name = flagStr(args, "name") ?? basename(root)
-    info(c.dim(`Creating project ${c.bold(name)}…`))
-    uuid = (await createProject(apiUrl, token, name, flagStr(args, "team"))).uuid
-    files = {}                                    // fresh project: the whole folder is a pending add
-  }
 
-  const commits = await getCommits(apiUrl, token, uuid)
-  writeManifest(root, { uuid, apiUrl, name, baseHeadId: commits.headId, files })
-  log(`${c.green("linked")}    ${c.bold(name)} ${c.dim(uuid)}`)
+    const commits = await getCommits(apiUrl, token, uuid)
+    writeManifest(root, { uuid, apiUrl, name, baseHeadId: commits.headId, files })
+    log(`${c.green("linked")}    ${c.bold(name)} ${c.dim(uuid)}`)
 
-  // Now that there IS a server, take its type surface — it matches the runtime the project will
-  // actually run on, unlike the CLI-bundled copy `lecodes init` wrote.
-  if (!flagBool(args, "no-types")) {
-    await materializeTypes(root, apiUrl)
-    writeTsconfig(root)
-    log(`${c.green("written")}   ${LECODES_DIR}/types/ + tsconfig.json  ${c.dim("(from the server)")}`)
-  }
-  writeDefaultIgnore(root)
-  if (ensureGitignore(root)) log(`${c.green("written")}   .gitignore  ${c.dim("(.lecodes/ is per-checkout state)")}`)
+    // Now that there IS a server, take its type surface — it matches the runtime the project will
+    // actually run on, unlike the CLI-bundled copy `lecodes init` wrote.
+    if (!flags["no-types"]) {
+      await materializeTypes(root, apiUrl)
+      writeTsconfig(root)
+      log(`${c.green("written")}   ${LECODES_DIR}/types/ + tsconfig.json  ${c.dim("(from the server)")}`)
+    }
+    writeDefaultIgnore(root)
+    if (ensureGitignore(root)) log(`${c.green("written")}   .gitignore  ${c.dim("(.lecodes/ is per-checkout state)")}`)
+
+    if (flags.push) {
+      log("")
+      if (root !== process.cwd()) process.chdir(root)   // push works from the current project root
+      await runPush(flags)
+      return
+    }
 
-  if (flagBool(args, "push")) {
+    const pending = scanProject(root, { files } as Manifest).files.filter((f) => { const known = files[f.path]; return !known || known.sha !== f.sha }).length
     log("")
-    if (root !== process.cwd()) process.chdir(root)   // push works from the current project root
-    await push(args)
-    return
-  }
-
-  const pending = scanProject(root, { files } as Manifest).files.filter((f) => {
-    const known = files[f.path]
-    return !known || known.sha !== f.sha
-  }).length
-  log("")
-  success(`Connected to ${c.bold(name)}.`)
-  const cd = dirArg ? `cd ${dirArg} && ` : ""
-  log(`  ${c.bold(cd + "lecodes status")}             ${pending} file(s) would go up`)
-  log(`  ${c.bold(cd + 'lecodes push -m "initial"')}  push them as the first checkpoint`)
-  log(`  ${c.dim("(add --publish to deploy it live in the same step)")}`)
-}
+    success(`Connected to ${c.bold(name)}.`)
+    const cd = dirArg ? `cd ${dirArg} && ` : ""
+    log(`  ${c.bold(cd + "lecodes status")}             ${pending} file(s) would go up`)
+    log(`  ${c.bold(cd + 'lecodes push -m "initial"')}  push them as the first checkpoint`)
+    log(`  ${c.dim("(add --publish to deploy it live in the same step)")}`)
+  },
+})