lecodes-cli 0.18.2 → 0.19.2

package/src/commands/install.ts

@@ -0,0 +1,198 @@
+import { execFileSync } from "node:child_process"
+import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, delimiter, dirname, join, resolve, sep } from "node:path"
+import { c, CliError, flagBool, flagStr, log, success, warn, type Args } from "../util"
+
+/*
+ * `lecodes install` — install this standalone build so `lecodes` is on your PATH.
+ *
+ * The packaged CLI is a small BUNDLE, not a single file: the `lecodes` binary + the `chisel` bundler +
+ * `runtime/` (the vendored SDK source + types). The binary resolves those companions next to its REAL
+ * path (process.execPath, which follows symlinks — verified), so "install" just means: copy the bundle
+ * into a stable library folder and expose the binary on PATH.
+ *   - Linux/macOS: copy to <libdir>/, symlink <bindir>/lecodes -> <libdir>/lecodes.
+ *   - Windows:     copy to <dir>\ and put that dir on PATH (no symlink, no admin needed).
+ *
+ * PATH is only edited on request (`--modify-path`); otherwise we place the files and print exactly how
+ * to finish (a one-liner for this shell, a line for the rc file, or `--system` which lands in
+ * /usr/local/bin and needs no PATH edit). Only meaningful for the release archive — from npm/monorepo
+ * source process.execPath has no bundle beside it, so it refuses.
+ */
+
+const isWin = process.platform === "win32"
+const HOME = homedir()
+
+/** Display a path with the home dir collapsed to `~` (for copy-pasteable hints). */
+const tildify = (p: string): string => (p === HOME || p.startsWith(HOME + sep)) ? "~" + p.slice(HOME.length) : p
+
+const safeRealpath = (p: string): string => { try { return realpathSync(p) } catch { return resolve(p) } }
+
+/** True if `dir` is already an entry in PATH (compared by resolved path). */
+const onPath = (dir: string): boolean => {
+  const want = safeRealpath(dir)
+  return (process.env.PATH ?? "").split(delimiter).some(p => {
+    if (!p) return false
+    try { return safeRealpath(p) === want } catch { return false }
+  })
+}
+
+export const install = async (args: Args): Promise<void> => {
+  const bundle = dirname(process.execPath)
+  const exeName = basename(process.execPath)               // "lecodes" | "lecodes.exe"
+  const chiselName = isWin ? "chisel.exe" : "chisel"
+
+  // Guard: this must be the packaged standalone bundle (chisel + runtime/ sit next to the binary).
+  // From npm / the monorepo, process.execPath is the bun/node binary and has no companions.
+  if (!existsSync(join(bundle, "runtime")) || !existsSync(join(bundle, chiselName))) {
+    throw new CliError(
+      "`lecodes install` only works from the packaged release build (the archive containing lecodes + " +
+      "chisel + runtime/). You appear to be running from source or an npm install — install globally " +
+      "with your package manager there instead.",
+    )
+  }
+
+  const companions = [exeName, chiselName, "runtime", "README.txt"].filter(f => existsSync(join(bundle, f)))
+  if (isWin) return installWindows(args, bundle, companions)
+  return installUnix(args, bundle, companions)
+}
+
+/** Copy the bundle's companion files into `target` (skipping the copy when target IS the bundle). */
+const copyBundle = (bundle: string, target: string, companions: string[]): void => {
+  mkdirSync(target, { recursive: true })
+  if (safeRealpath(target) === safeRealpath(bundle)) return   // installing in place — nothing to copy
+  for (const f of companions) {
+    const dest = join(target, f)
+    rmSync(dest, { recursive: true, force: true })
+    cpSync(join(bundle, f), dest, { recursive: true })
+  }
+}
+
+const permError = (e: unknown, dir: string, system: boolean): CliError => {
+  const code = (e as NodeJS.ErrnoException | null)?.code
+  if (code === "EACCES" || code === "EPERM") {
+    return new CliError(
+      `Permission denied writing to ${dir}.` +
+      (system ? " Re-run with sudo:  sudo lecodes install --system" : " Try without --system, or pick a writable --dir."),
+    )
+  }
+  return new CliError(`Install failed: ${e instanceof Error ? e.message : String(e)}`)
+}
+
+const installUnix = (args: Args, bundle: string, companions: string[]): void => {
+  const system = flagBool(args, "system")
+  const libDir = resolve(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join(HOME, ".local", "lib", "lecodes-cli")))
+  const binDir = resolve(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join(HOME, ".local", "bin")))
+  const link = join(binDir, "lecodes")
+
+  try {
+    copyBundle(bundle, libDir, companions)
+    chmodSync(join(libDir, "lecodes"), 0o755)
+    chmodSync(join(libDir, "chisel"), 0o755)
+  } catch (e) { throw permError(e, libDir, system) }
+
+  try {
+    mkdirSync(binDir, { recursive: true })
+    rmSync(link, { force: true })                            // replace a previous symlink/file
+    symlinkSync(join(libDir, "lecodes"), link)
+  } catch (e) { throw permError(e, binDir, system) }
+
+  success(`Installed to ${c.bold(libDir)}`)
+  log(`  ${c.dim(link + " → " + join(libDir, "lecodes"))}`)
+  finishPathUnix(args, binDir)
+}
+
+/** The shell startup file to persist PATH into, picked from $SHELL (bash/zsh handled; else ~/.profile,
+ *  which login shells read). Returns the absolute path and a ~-collapsed display name. */
+const shellRc = (): { file: string, name: string } => {
+  const shell = basename(process.env.SHELL ?? "")
+  if (shell === "zsh") return { file: join(HOME, ".zshrc"), name: "~/.zshrc" }
+  if (shell === "bash") return { file: join(HOME, ".bashrc"), name: "~/.bashrc" }
+  return { file: join(HOME, ".profile"), name: "~/.profile" }
+}
+
+const PATH_MARKER = "# Added by `lecodes install`"
+
+/** Append an `export PATH=…` line for `binDir` to the shell rc (idempotently). Returns the rc display
+ *  name on success, or null if the file couldn't be written. */
+const appendPathToShellRc = (binDir: string): string | null => {
+  const { file, name } = shellRc()
+  const line = `export PATH="${binDir}:$PATH"`
+  try {
+    const existing = existsSync(file) ? readFileSync(file, "utf8") : ""
+    if (existing.includes(line)) return name                 // already present — no duplicate
+    appendFileSync(file, `${existing && !existing.endsWith("\n") ? "\n" : ""}\n${PATH_MARKER}\n${line}\n`)
+    return name
+  } catch { return null }
+}
+
+/** Put `binDir` on PATH: verify (already there), or `--modify-path` (edit the rc), or print how. */
+const finishPathUnix = (args: Args, binDir: string): void => {
+  if (onPath(binDir)) {
+    log(`  Run ${c.bold("lecodes --version")} in a new shell to verify.`)
+    return
+  }
+  if (flagBool(args, "modify-path")) {
+    const rc = appendPathToShellRc(binDir)
+    if (rc) {
+      success(`Added ${c.bold(binDir)} to PATH in ${rc}.`)
+      log(`  Run ${c.bold(`source ${rc}`)} (or open a new terminal), then ${c.bold("lecodes --version")}.`)
+    } else {
+      warn("Couldn't edit your shell startup file. Add this line to it manually:")
+      log(`  ${c.bold(`export PATH="${binDir}:$PATH"`)}`)
+    }
+    return
+  }
+  const { name } = shellRc()
+  warn(`${binDir} is not on your PATH yet. To finish, either:`)
+  log(`  • this shell now:   ${c.bold(`export PATH="${binDir}:$PATH"`)}`)
+  log(`  • all new shells:   ${c.bold(`echo 'export PATH="${binDir}:$PATH"' >> ${name}`)} ${c.dim("(then reopen it)")}`)
+  log(`  • let install do it: re-run with ${c.bold("--modify-path")}`)
+  log(`  • or install system-wide (no PATH edit): ${c.bold("sudo lecodes install --system")}`)
+}
+
+const installWindows = (args: Args, bundle: string, companions: string[]): void => {
+  const target = resolve(flagStr(args, "dir") ?? join(process.env.LOCALAPPDATA ?? join(HOME, "AppData", "Local"), "Programs", "lecodes-cli"))
+
+  try {
+    copyBundle(bundle, target, companions)
+  } catch (e) {
+    throw new CliError(`Install failed writing to ${target}: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  success(`Installed to ${c.bold(target)}`)
+  // No symlink on Windows (they need admin) and no shim needed — the exe resolves chisel/runtime next to
+  // itself, so putting the install folder itself on PATH is enough.
+  if (onPath(target)) {
+    log(`  Already on PATH — run ${c.bold("lecodes --version")} in a new terminal.`)
+    return
+  }
+  if (flagBool(args, "modify-path")) {
+    if (addToUserPathWindows(target)) {
+      success(`Added ${c.bold(target)} to your user PATH.`)
+      log(`  ${c.yellow("Open a NEW terminal")} for it to take effect, then run ${c.bold("lecodes --version")}.`)
+    } else {
+      warn("Couldn't edit PATH automatically. Add this folder to your PATH manually:")
+      log(`  ${c.bold(target)}`)
+    }
+    return
+  }
+  warn(`${target} is not on your PATH yet. To finish, either:`)
+  log(`  • let install do it: re-run with ${c.bold("--modify-path")} (adds it to your user PATH)`)
+  log(`  • or add the folder manually via System → Environment Variables.`)
+}
+
+/** Append `dir` to the current user's Path via the .NET env API (PowerShell). Unlike `setx` this never
+ *  truncates a long Path. The dir is passed through an env var to avoid any quoting/injection. */
+const addToUserPathWindows = (dir: string): boolean => {
+  const script =
+    "$d = $env:LECODES_INSTALL_DIR;" +
+    "$p = [Environment]::GetEnvironmentVariable('Path','User'); if (-not $p) { $p = '' };" +
+    "$parts = @($p.Split(';') | Where-Object { $_ -ne '' });" +
+    "if ($parts -notcontains $d) { [Environment]::SetEnvironmentVariable('Path', (@($parts + $d) -join ';'), 'User') }"
+  try {
+    execFileSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", script],
+      { stdio: "ignore", env: { ...process.env, LECODES_INSTALL_DIR: dir } })
+    return true
+  } catch { return false }
+}

package/src/commands/lightmap.ts

@@ -0,0 +1,290 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+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"
+
+/*
+ * `lecodes lightmap bake` — bake static shadows, ambient occlusion and the level's point lights for
+ * the local project (docs/lightmap-plan.md). The app is compiled with a synthetic entry that puts it
+ * in BAKE mode (`globalThis.__lecodesLightmap = { outDir, … }`, then `import "./main"`) and run in the
+ * native desktop host; when the app calls `Lightmap.load(...)` — the point where its scene is
+ * complete — the SDK sees the flag and calls `_creator.lightmapBake` instead of loading: creator-gl
+ * traces every `Lightmap.add`-registered static against the scene's sun and point lights and writes
+ * its rasters (PNGs, INTERMEDIATES) + lightmap.bake into --out. The host's stdout carries
+ * "[lightmap] …" progress lines; "[lightmap] done" is the success marker. The atlases then ship as
+ * **KTX2**: the CLI runs KTX-Software's toktx (UASTC + zstd + mips, sRGB transfer function — the bake
+ * encodes sRGB on purpose, precision in the darks) and deletes the PNGs. toktx is REQUIRED — the
+ * command refuses to start without it, so a bake never leaves a half-finished output behind.
+ *
+ * Output, under --out with the --name stem (default `lightmap`, so a project with several baked
+ * levels gives each its own stem — `app build desktop` rejects two resources of one basename):
+ *   <name>.bake                 rects, pages, the baked lights (what the scene's `data` names)
+ *   <name>.ktx2, <name>_1.ktx2… the atlas pages — R = sun visibility, G = ambient occlusion
+ *   <name>-light[_n].ktx2       the point lights' baked irradiance, only when the level holds any
+ *   <name>.volume               the light volume for movers (unless --no-volume)
+ *
+ * Only the desktop host has the bake module (a dev tool — never in the wasm / mobile engines), so
+ * this needs a host with it: a local build via LECODES_DESKTOP_EXE until the release ships it.
+ * 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
+}
+
+// ---- toktx (KTX-Software) — same lookup as lecodes-assets' doctor --------------------------------
+
+const findToktx = (): string => {
+  const env = process.env.KTX_TOKTX
+  if (env && existsSync(env)) return env
+  for (const base of [ process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, "Programs"), process.env.ProgramFiles ]) {
+    if (!base) continue
+    const guess = join(base, "KTX-Software", "bin", "toktx.exe")
+    if (existsSync(guess)) return guess
+  }
+  return "toktx"   // on PATH
+}
+
+const checkToktx = (toktx: string): string | null => {
+  try {
+    const p = spawnSync(toktx, [ "--version" ], { encoding: "utf8" })
+    if (p.status === 0) return (p.stdout ?? "").toString().trim() || "toktx"
+  } catch { /* not found */ }
+  return null
+}
+
+const requireToktx = (): string => {
+  const toktx = findToktx()
+  if (!checkToktx(toktx)) {
+    throw new CliError("lecodes lightmap bake needs KTX-Software's toktx — the atlas ships as KTX2 (GPU-compressed, mipmapped).\n  Install it from https://github.com/KhronosGroup/KTX-Software/releases (make sure toktx is on PATH) or set KTX_TOKTX=<path to toktx>.")
+  }
+  return toktx
+}
+
+/** PNG raster → .ktx2: UASTC (the high-quality Basis codec — ETC1S blocks the shadow edges),
+ *  zstd supercompression, a full mip chain, sRGB transfer function (what the bake encodes and what
+ *  the ordinary texture path expects; the KTX2 reader refuses a mismatch instead of guessing). */
+// Async so the pages encode CONCURRENTLY: toktx's zstd + mip stages are serial per file, and the four
+// pages of a two-page bake with a light atlas took 23 s one after another against 10 s side by side.
+const encodeKtx2 = (toktx: string, png: string, ktx2: string): Promise<void> => new Promise((resolve, reject) => {
+  const args = [ "--t2", "--encode", "uastc", "--uastc_quality", "2", "--zcmp", "18", "--genmipmap", "--assign_oetf", "srgb", ktx2, png ]
+  const p = spawn(toktx, args, { stdio: [ "ignore", "pipe", "pipe" ] })
+  let out = ""
+  p.stdout.on("data", (d) => { out += String(d) })
+  p.stderr.on("data", (d) => { out += String(d) })
+  p.on("error", (e) => reject(new CliError(`toktx failed (${e.message}) while encoding ${ktx2}`)))
+  p.on("close", (status) => {
+    if (status === 0) resolve()
+    else reject(new CliError(`toktx failed (${status ?? "?"}) while encoding ${ktx2}:\n${out.trim()}`))
+  })
+})
+
+/** The bake's file names for `stem`: page 0 is `<stem>.ktx2`, page n `<stem>_n.ktx2`; the light atlas adds `-light`. */
+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. */
+const PLACEHOLDER_KTX2 = Buffer.from(
+  "q0tUWCAyMLsNChoKAAAAAAEAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAEAAAAAAAAAaAAAACwAAACUAAAAfAAAAAAAAAAAAAAAAAAAAAAAAAAQAQAAAAAAABAAAAAAAAAAEAAAAAAAAAAsAAAAAAAAAAIAKACmAQIAAwMAABAAAAAAAAAAAAB/AAAAAAAAAAAA/////xEAAABLVFhvcmllbnRhdGlvbgByAAAAACcAAABLVFh3cml0ZXIAdG9rdHggdjQuNC4yIC8gbGlia3R4IHY0LjQuMgAAMwAAAEtUWHdyaXRlclNjUGFyYW1zAC0tZW5jb2RlIHVhc3RjIC0tdWFzdGNfcXVhbGl0eSAwAAD3////H3zvAQAAAAAAAAAA",
+  "base64")
+
+/** A 1x1x1 white light volume ("LVOL" v1, one lit cell): Lightmap.load treats a single-cell volume as "nothing baked". */
+const placeholderVolume = (): Buffer => {
+  const b = Buffer.alloc(4 + 4 + 12 + 12 + 4 + 2)
+  b.write("LVOL", 0, "latin1")
+  b.writeUInt32LE(1, 4)
+  b.writeUInt32LE(1, 8); b.writeUInt32LE(1, 12); b.writeUInt32LE(1, 16)
+  b.writeFloatLE(0, 20); b.writeFloatLE(0, 24); b.writeFloatLE(0, 28)
+  b.writeFloatLE(1, 32)
+  b[36] = 255; b[37] = 255
+  return b
+}
+
+/** The files a scene may reference before the first bake exists: the .bake, page 0 of both atlases
+ *  and the volume (later pages come from a bake that needed them). An EMPTY file counts as missing —
+ *  a zero-byte KTX2 is what hand-made placeholders looked like, and the host cannot build a texture
+ *  from it. */
+const ensurePlaceholders = (outDir: string, stem: string): void => {
+  const missing = (f: string): boolean => !existsSync(f) || statSync(f).size === 0
+  const bake = join(outDir, `${stem}.bake`)
+  const ktx2 = join(outDir, pageFile(stem, 0, false))
+  const light = join(outDir, pageFile(stem, 0, true))
+  const volume = join(outDir, `${stem}.volume`)
+  if (missing(bake)) writeFileSync(bake, JSON.stringify({ version: 2, placeholder: true, size: 1, texel: 0, pages: 1, instances: [] }) + "\n")
+  if (missing(ktx2)) writeFileSync(ktx2, PLACEHOLDER_KTX2)
+  if (missing(light)) writeFileSync(light, PLACEHOLDER_KTX2)
+  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)")
+}

package/src/commands/link.ts

@@ -0,0 +1,147 @@
+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 { parseUuid } from "./clone"
+import { push } from "./push"
+
+/*
+ * `lecodes link [dir]` — connect an existing local folder (typically one made by `lecodes init`) to
+ * the platform, so `status` / `push` / `pull` work on it. The mirror image of `clone`.
+ *
+ * Everything push needs is <root>/.lecodes/manifest.json, so linking is exactly: pick the remote
+ * project (create a fresh one, or adopt an existing one via --project), write that manifest, and
+ * refresh the types from the server now that there is one. Nothing is uploaded — the first
+ * `lecodes push` does that, so the user sees `status` before anything leaves the machine.
+ *
+ * Adopting a NON-EMPTY project is the one sharp edge: push is a set-tree, so it would delete
+ * whatever the server has and the local folder doesn't. The manifest is therefore built from the
+ * SERVER's tree (not empty), which makes `status`/`diff` truthful, and the exact server-side
+ * consequence is printed and confirmed before the link is written.
+ */
+
+const kindOf = (type: ProjectAsset["type"]): FileKind => (type === "file" ? "resource" : type as FileKind)
+
+/** Manifest file map describing the project's CURRENT server state, without downloading anything.
+ *  Text assets carry their content, so their sha is exact and unchanged files show as unchanged;
+ *  binaries aren't fetched here — an empty sha reads as "changed", so the first push re-uploads
+ *  them. That costs bandwidth once and keeps linking a metadata-only operation. */
+const manifestFromServer = (project: Project): Record<string, ManifestFile> => {
+  const pathById = buildPaths(project.assets)
+  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 ?? ""),
+    }
+  }
+  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 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
+  }
+
+  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
+  }
+
+  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
+  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.`)
+    }
+    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)}`)
+
+  // 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)")}`)
+
+  if (flagBool(args, "push")) {
+    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)")}`)
+}

package/src/commands/login.ts

@@ -0,0 +1,24 @@
+import { getAccount } from "../api"
+import { DEFAULT_API, loadConfig, normalizeApiUrl, saveConfig } from "../config"
+import { browserLogin } from "../browserAuth"
+import { flagStr, success, c, type Args } from "../util"
+
+/*
+ * `lecodes login` — authorize this machine and store a personal access token in ~/.lecodes.
+ *   - default: open the browser, sign in / authorize on le.codes, capture the token.
+ *   - `--token <pat>`: store a token created in the web UI (headless / CI).
+ *   - `--api <url>`: API origin (defaults to https://le.codes).
+ *   - `--web <url>`: app origin for the browser flow (defaults to the API origin).
+ */
+export const login = async (args: Args) => {
+  const config = loadConfig()
+  const apiUrl = normalizeApiUrl(flagStr(args, "api") ?? config.apiUrl ?? DEFAULT_API)
+  const webBase = normalizeApiUrl(flagStr(args, "web") ?? apiUrl)
+
+  const token = flagStr(args, "token") ?? await browserLogin(webBase)
+
+  // Verify the token works against the API before persisting it.
+  const account = await getAccount(apiUrl, token)
+  saveConfig({ apiUrl, token })
+  success(`Logged in as ${c.bold(account.email)} on ${apiUrl}`)
+}