lecodes-cli 0.20.2 → 2.0.0

package/src/commands/thumbs.ts

@@ -1,175 +1,185 @@
-import { createRequire } from "node:module"
-import { execFileSync } from "node:child_process"
-import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { extname, join, relative, resolve } from "node:path"
-import { loadPeer } from "../peerInstall"
-import { projectRootOf } from "./scene"
-import { CliError, c, endProgress, flagBool, flagStr, log, note, progress, toKey, warnErr, type Args } from "../util"
-
-/*
- * `lecodes thumbs [path…]` — the scene editor's asset thumbnails, generated from the COMMAND LINE.
- *
- * The editor renders previews in a hidden browser host (3D assets need an engine), but image
- * thumbnails need no engine at all — and a .ktx2 has no picture until something decodes it. This
- * command fills the same cache the editor reads (`.lecodes/preview/<asset>.<hash>.png`, owned by
- * lecodes-3d-editor's server/previewCache) with no browser in the loop, so opening the editor on a
- * texture-heavy project shows a full grid immediately instead of rendering 40 thumbnails on the
- * spot.
- *
- * Incremental by construction: the cache file name carries the first 10 hex of the SOURCE file's
- * sha256, so an asset whose preview is already there is skipped after one hash — re-running over a
- * big project is nearly free. `--force` ignores that.
- *
- * Decoders, in the order tried: sharp (through the optional `lecodes-assets` peer — handles webp),
- * else jimp (bundled with this CLI: png / jpeg / bmp / gif / tiff). KTX2 goes through
- * KTX-Software's `ktx extract` first (it is a GPU-compressed format; nothing in JS reads it), and
- * the extracted PNG then takes the same resize path.
- *
- * NOT covered: models, materials and prefabs — those are RENDERED, which needs an engine. The
- * editor still does them on demand (and `lecodes render --desktop` is the browserless renderer if
- * that ever becomes a batch job).
- */
-
-const DEFAULT_SIZE = 256
-const IMAGE_EXT = /\.(png|jpe?g|webp|bmp|gif|tiff?|ktx2)$/i
-const RENDERED_EXT = /\.(glb|gltf|material\.ts|scene\.ts)$/i
-
-/** KTX-Software's `ktx` CLI (v4.3+ has `extract`), resolved like lecodes-assets resolves toktx. */
-const findKtx = (): string | null => {
-  const exe = process.platform === "win32" ? "ktx.exe" : "ktx"
-  const candidates = [
-    process.env.LECODES_KTX,
-    process.env.KTX_CLI,
-    process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, exe),
-    process.platform === "win32" ? join(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
-    process.platform === "win32" ? join(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
-    "/usr/local/bin/ktx",
-    "/opt/homebrew/bin/ktx",
-  ].filter((p): p is string => !!p)
-  for (const path of candidates) { if (existsSync(path)) return path }
-  try {
-    execFileSync(exe, [ "--version" ], { stdio: "ignore" })
-    return exe
-  } catch { return null }
-}
-
-type Resizer = (file: string, size: number) => Promise<Uint8Array>
-
-/** sharp through the `lecodes-assets` peer (it declares it optional), or null when neither is
- *  installed — jimp then covers everything but webp. */
-const sharpResizer = (): Resizer | null => {
-  try {
-    const req = createRequire(import.meta.url)
-    const sharp = createRequire(req.resolve("lecodes-assets/cli"))("sharp")
-    return async (file, size) =>
-      sharp(file).resize({ width: size, height: size, fit: "inside", withoutEnlargement: true }).png().toBuffer()
-  } catch { return null }
-}
-
-const jimpResizer = (): Resizer => async (file, size) => {
-  const { Jimp } = await import("jimp")
-  const img = await Jimp.read(file)
-  if (Math.max(img.width, img.height) > size) img.scaleToFit({ w: size, h: size })
-  return await img.getBuffer("image/png")
-}
-
-/** KTX2 → a temporary PNG (level 0, transcoded to RGBA8 when the payload is Basis-compressed). */
-const ktxToPng = (ktx: string, file: string, out: string): void => {
-  const run = (args: string[]) => execFileSync(ktx, args, { stdio: [ "ignore", "ignore", "pipe" ], encoding: "utf8" })
-  try {
-    run([ "extract", "--transcode", "rgba8", "--level", "0", file, out ])
-  } catch (e: any) {
-    // Only Basis (ETC1S/UASTC) payloads are transcodable; a plain uncompressed KTX2 extracts as-is
-    run([ "extract", "--level", "0", file, out ])
-    if (!existsSync(out)) throw e
-  }
-}
-
-/** Every previewable file under a folder — the SAME sweep the editor's asset panel lists with
- *  (node_modules + dotfiles out, nothing else): what this command doesn't cover, the browser would
- *  end up rendering itself. */
-const collect = (dir: string): string[] => {
-  const out: string[] = []
-  for (const name of readdirSync(dir)) {
-    if (name === "node_modules" || name.startsWith(".")) continue
-    const full = join(dir, name)
-    if (statSync(full).isDirectory()) out.push(...collect(full))
-    else if (IMAGE_EXT.test(name)) out.push(full)
-  }
-  return out
-}
-
-export const thumbs = async (args: Args) => {
-  const root = projectRootOf(process.cwd())
-
-  // The scene editor owns the preview cache — installed into ~/.lecodes/peers on first use.
-  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes thumbs" })
-
-  const size = Number(flagStr(args, "size")) || DEFAULT_SIZE
-  const force = flagBool(args, "force")
-
-  // Targets: the paths given (a file or a folder each), else the whole project.
-  let files: string[] = []
-  const rendered: string[] = []
-  if (args._.length > 0) {
-    for (const arg of args._) {
-      const abs = resolve(process.cwd(), arg)
-      if (!existsSync(abs)) throw new CliError(`No such file or folder: ${arg}`)
-      if (statSync(abs).isDirectory()) files.push(...collect(abs))
-      else if (IMAGE_EXT.test(abs)) files.push(abs)
-      else if (RENDERED_EXT.test(abs)) rendered.push(arg)
-      else throw new CliError(`Not a previewable asset: ${arg}`)
-    }
-  } else {
-    files = collect(root)
-  }
-  files = [ ...new Set(files) ]
-
-  if (files.length === 0 && rendered.length === 0) {
-    log("No images to thumbnail.")
-    return
-  }
-
-  const ktx = files.some((f) => f.toLowerCase().endsWith(".ktx2")) ? findKtx() : null
-  const sharp = sharpResizer()
-  const resize = sharp ?? jimpResizer()
-  const tmp = mkdtempSync(join(tmpdir(), "lecodes-thumbs-"))
-
-  let made = 0, fresh = 0
-  const skipped: string[] = []
-  try {
-    for (const [ i, file ] of files.entries()) {
-      const asset = "./" + toKey(relative(root, file))
-      progress(i, files.length, asset)
-      const hash = sceneServer.hashAsset(root, asset)
-      if (!hash) continue
-      if (!force && sceneServer.previewIsCurrent(root, asset, hash)) { fresh++; continue }
-
-      const ext = extname(file).toLowerCase()
-      if (ext === ".webp" && !sharp) { skipped.push(`${asset} (webp needs sharp — npm install -g lecodes-assets)`); continue }
-      try {
-        let source = file
-        if (ext === ".ktx2") {
-          if (!ktx) { skipped.push(`${asset} (KTX2 needs KTX-Software's \`ktx\` — set LECODES_KTX or put it on PATH)`); continue }
-          source = join(tmp, `${i}.png`)
-          ktxToPng(ktx, file, source)
-        }
-        sceneServer.writePreviewFile(root, asset, await resize(source, size))
-        made++
-      } catch (e: any) {
-        skipped.push(`${asset} (${(e?.message ?? String(e)).split("\n")[0]})`)
-      }
-    }
-  } finally {
-    endProgress()
-    rmSync(tmp, { recursive: true, force: true })
-  }
-
-  log(`${c.bold(String(made))} generated · ${fresh} already current${skipped.length > 0 ? ` · ${skipped.length} skipped` : ""}`)
-  for (const s of skipped) warnErr(s)
-  if (rendered.length > 0) {
-    warnErr(`Models, materials and prefabs are RENDERED, not decoded — the scene editor does those: ${rendered.join(", ")}`)
-  }
-  note(`Cache: ${join(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`)
-}
+import { createRequire } from "node:module"
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { extname, join, relative, resolve } from "node:path"
+import { loadPeer } from "../hosts/peerInstall"
+import { projectRootOf } from "./scene"
+import { CliError, bool, c, defineCommand, endProgress, log, note, num, progress, warnErr } from "../cli"
+import { toKey } from "../project/paths"
+
+/*
+ * `lecodes thumbs [path…]` — the scene editor's asset thumbnails, generated from the COMMAND LINE.
+ *
+ * The editor renders previews in a hidden browser host (3D assets need an engine), but image
+ * thumbnails need no engine at all — and a .ktx2 has no picture until something decodes it. This
+ * command fills the same cache the editor reads (`.lecodes/preview/<asset>.<hash>.png`, owned by
+ * lecodes-3d-editor's server/previewCache) with no browser in the loop, so opening the editor on a
+ * texture-heavy project shows a full grid immediately instead of rendering 40 thumbnails on the
+ * spot.
+ *
+ * Incremental by construction: the cache file name carries the first 10 hex of the SOURCE file's
+ * sha256, so an asset whose preview is already there is skipped after one hash — re-running over a
+ * big project is nearly free. `--force` ignores that.
+ *
+ * Decoders, in the order tried: sharp (through the optional `lecodes-assets` peer — handles webp),
+ * else jimp (bundled with this CLI: png / jpeg / bmp / gif / tiff). KTX2 goes through
+ * KTX-Software's `ktx extract` first (it is a GPU-compressed format; nothing in JS reads it), and
+ * the extracted PNG then takes the same resize path.
+ *
+ * NOT covered: models, materials and prefabs — those are RENDERED, which needs an engine. The
+ * editor still does them on demand (and `lecodes render --desktop` is the browserless renderer if
+ * that ever becomes a batch job).
+ */
+
+const DEFAULT_SIZE = 256
+const IMAGE_EXT = /\.(png|jpe?g|webp|bmp|gif|tiff?|ktx2)$/i
+const RENDERED_EXT = /\.(glb|gltf|material\.ts|scene\.ts)$/i
+
+/** KTX-Software's `ktx` CLI (v4.3+ has `extract`), resolved like lecodes-assets resolves toktx. */
+const findKtx = (): string | null => {
+  const exe = process.platform === "win32" ? "ktx.exe" : "ktx"
+  const candidates = [
+    process.env.LECODES_KTX,
+    process.env.KTX_CLI,
+    process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, exe),
+    process.platform === "win32" ? join(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
+    process.platform === "win32" ? join(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
+    "/usr/local/bin/ktx",
+    "/opt/homebrew/bin/ktx",
+  ].filter((p): p is string => !!p)
+  for (const path of candidates) { if (existsSync(path)) return path }
+  try {
+    execFileSync(exe, [ "--version" ], { stdio: "ignore" })
+    return exe
+  } catch { return null }
+}
+
+type Resizer = (file: string, size: number) => Promise<Uint8Array>
+
+/** sharp through the `lecodes-assets` peer (it declares it optional), or null when neither is
+ *  installed — jimp then covers everything but webp. */
+const sharpResizer = (): Resizer | null => {
+  try {
+    const req = createRequire(import.meta.url)
+    const sharp = createRequire(req.resolve("lecodes-assets/cli"))("sharp")
+    return async (file, size) =>
+      sharp(file).resize({ width: size, height: size, fit: "inside", withoutEnlargement: true }).png().toBuffer()
+  } catch { return null }
+}
+
+const jimpResizer = (): Resizer => async (file, size) => {
+  const { Jimp } = await import("jimp")
+  const img = await Jimp.read(file)
+  if (Math.max(img.width, img.height) > size) img.scaleToFit({ w: size, h: size })
+  return await img.getBuffer("image/png")
+}
+
+/** KTX2 → a temporary PNG (level 0, transcoded to RGBA8 when the payload is Basis-compressed). */
+const ktxToPng = (ktx: string, file: string, out: string): void => {
+  const run = (args: string[]) => execFileSync(ktx, args, { stdio: [ "ignore", "ignore", "pipe" ], encoding: "utf8" })
+  try {
+    run([ "extract", "--transcode", "rgba8", "--level", "0", file, out ])
+  } catch (e: any) {
+    // Only Basis (ETC1S/UASTC) payloads are transcodable; a plain uncompressed KTX2 extracts as-is
+    run([ "extract", "--level", "0", file, out ])
+    if (!existsSync(out)) throw e
+  }
+}
+
+/** Every previewable file under a folder — the SAME sweep the editor's asset panel lists with
+ *  (node_modules + dotfiles out, nothing else): what this command doesn't cover, the browser would
+ *  end up rendering itself. */
+const collect = (dir: string): string[] => {
+  const out: string[] = []
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name.startsWith(".")) continue
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) out.push(...collect(full))
+    else if (IMAGE_EXT.test(name)) out.push(full)
+  }
+  return out
+}
+
+export default defineCommand({
+  name: "thumbs",
+  summary: "Asset thumbnails for the scene editor, without a browser",
+  usage: "[path…]",
+  description: "Decodes the project's images (KTX2 too, via KTX-Software's ktx tool) into the editor's preview cache. Incremental: the cached name carries the asset's content hash, so unchanged files are skipped. Models, materials and prefabs are rendered by the editor, not here.",
+  flags: {
+    force: bool("redo even the up-to-date ones"),
+    size: num("longest edge, px", { default: DEFAULT_SIZE }),
+  },
+  run: ({ args, flags }) => thumbs(args, flags.size, flags.force),
+})
+
+const thumbs = async (targets: string[], size: number, force: boolean): Promise<void> => {
+  const root = projectRootOf(process.cwd())
+
+  // The scene editor owns the preview cache — installed into ~/.lecodes/peers on first use.
+  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes thumbs" })
+
+  // Targets: the paths given (a file or a folder each), else the whole project.
+  let files: string[] = []
+  const rendered: string[] = []
+  if (targets.length > 0) {
+    for (const arg of targets) {
+      const abs = resolve(process.cwd(), arg)
+      if (!existsSync(abs)) throw new CliError(`No such file or folder: ${arg}`)
+      if (statSync(abs).isDirectory()) files.push(...collect(abs))
+      else if (IMAGE_EXT.test(abs)) files.push(abs)
+      else if (RENDERED_EXT.test(abs)) rendered.push(arg)
+      else throw new CliError(`Not a previewable asset: ${arg}`)
+    }
+  } else {
+    files = collect(root)
+  }
+  files = [ ...new Set(files) ]
+
+  if (files.length === 0 && rendered.length === 0) {
+    log("No images to thumbnail.")
+    return
+  }
+
+  const ktx = files.some((f) => f.toLowerCase().endsWith(".ktx2")) ? findKtx() : null
+  const sharp = sharpResizer()
+  const resize = sharp ?? jimpResizer()
+  const tmp = mkdtempSync(join(tmpdir(), "lecodes-thumbs-"))
+
+  let made = 0, fresh = 0
+  const skipped: string[] = []
+  try {
+    for (const [ i, file ] of files.entries()) {
+      const asset = "./" + toKey(relative(root, file))
+      progress(i, files.length, asset)
+      const hash = sceneServer.hashAsset(root, asset)
+      if (!hash) continue
+      if (!force && sceneServer.previewIsCurrent(root, asset, hash)) { fresh++; continue }
+
+      const ext = extname(file).toLowerCase()
+      if (ext === ".webp" && !sharp) { skipped.push(`${asset} (webp needs sharp — npm install -g lecodes-assets)`); continue }
+      try {
+        let source = file
+        if (ext === ".ktx2") {
+          if (!ktx) { skipped.push(`${asset} (KTX2 needs KTX-Software's \`ktx\` — set LECODES_KTX or put it on PATH)`); continue }
+          source = join(tmp, `${i}.png`)
+          ktxToPng(ktx, file, source)
+        }
+        sceneServer.writePreviewFile(root, asset, await resize(source, size))
+        made++
+      } catch (e: any) {
+        skipped.push(`${asset} (${(e?.message ?? String(e)).split("\n")[0]})`)
+      }
+    }
+  } finally {
+    endProgress()
+    rmSync(tmp, { recursive: true, force: true })
+  }
+
+  log(`${c.bold(String(made))} generated · ${fresh} already current${skipped.length > 0 ? ` · ${skipped.length} skipped` : ""}`)
+  for (const s of skipped) warnErr(s)
+  if (rendered.length > 0) {
+    warnErr(`Models, materials and prefabs are RENDERED, not decoded — the scene editor does those: ${rendered.join(", ")}`)
+  }
+  note(`Cache: ${join(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`)
+}

package/src/commands/update/index.ts

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import pkg from "../../../package.json"
+import { CliError, bool, c, defineCommand, log, note, readFlags, type Command } from "../../cli"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "../../hosts/peers"
+import { installPeers } from "../../hosts/peerInstall"
+import { updateDesktop } from "../../hosts/desktopRenderer"
+import { updateMatc } from "../../hosts/matcTool"
+import { refreshTypes } from "./types"
+import { compileShaders } from "../shaders"
+import app from "../app"
+
+/*
+ * `lecodes update` — one command that moves EVERYTHING a project depends on to its newest published
+ * state, in the order the pieces depend on each other:
+ *
+ *   1. desktop   the LeCodes Desktop host `desktop run` / `render --desktop` use   (= `desktop update`)
+ *   2. matc      Filament's material compiler for local shader compiles              (= `shaders update`)
+ *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
+ *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (types.ts)
+ *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
+ *   6. cli       the npm installs — every installed optional peer (lecodes-headless, lecodes-design,
+ *                lecodes-3d-editor, lecodes-assets, @napi-rs/canvas) and the CLI itself that is behind:
+ *                peers in ~/.lecodes/peers (first-use installs, peerInstall.ts) are re-installed there
+ *                — the renderer at THIS CLI's version, the rest at npm's latest in range; global ones
+ *                (`npm install -g`, the old way) via `npm install -g …@latest`; the CLI itself last
+ *                (the standalone binary can't come from npm — it says so and does the peers only)
+ *
+ * Every step is the existing subcommand, so nothing here can drift from what the individual
+ * commands do; this only sequences them and keeps going when one fails (the summary says which).
+ * Steps that the environment pins are SKIPPED, not overridden: LECODES_DESKTOP_EXE means a local
+ * host build (engine work — the cache is irrelevant), LECODES_MATC a local matc; the project steps
+ * need a project (a dir with app.json / .lecodes above the cwd) and the shell step a shell folder.
+ *
+ * `lecodes types` used to be its own command; the types step here replaced it (2026-09-04).
+ */
+
+/** The nearest project at or above `start`: a dir with app.json, or a .lecodes/ that holds a project's
+ *  manifest or types. NOT the bare `.lecodes/` marker projectEnv uses — the CLI's own config lives in
+ *  ~/.lecodes, so that rule would turn any folder under the home dir into a "project" and the types
+ *  step would scaffold .lecodes/types + tsconfig.json into it. */
+const findProjectDir = (start: string): string | null => {
+  const home = resolve(homedir())
+  let dir = resolve(start)
+  while (true) {
+    if (dir !== home && (existsSync(join(dir, "app.json")) || existsSync(join(dir, ".lecodes", "manifest.json")) || existsSync(join(dir, ".lecodes", "types")))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** Run another command's subcommand with its default flags — the step IS that command, so it can't drift. */
+const runSubcommand = async (parent: Command<any>, name: string): Promise<void> => {
+  const sub = parent.commands?.find((x) => x.name === name)
+  if (!sub?.run) throw new CliError(`lecodes ${parent.name} ${name} is not a runnable command`)
+  const path = [parent.name, name]
+  await sub.run({ args: [], flags: readFlags(sub.flags ?? {}, {}, path), raw: {}, argv: [], path })
+}
+
+type Outcome = "updated" | "ok" | "skipped" | "failed"
+type Step = { name: string, outcome: Outcome, detail?: string }
+
+const NPM = "https://registry.npmjs.org"
+
+/** `latest` dist-tag of an npm package, or null when npm is unreachable / the package is unknown. */
+const npmLatest = async (name: string): Promise<string | null> => {
+  try {
+    const res = await fetch(`${NPM}/${name}/latest`, { signal: AbortSignal.timeout(4000) })
+    if (!res.ok) return null
+    const json = await res.json() as { version?: string }
+    return json.version ?? null
+  } catch {
+    return null
+  }
+}
+
+const semverNewer = (a: string, b: string): number => {
+  const pa = a.split(/[.-]/).map(Number), pb = b.split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) { const d = (pa[i] ?? 0) - (pb[i] ?? 0); if (d) return d }
+  return 0
+}
+
+/** Running straight from the repo checkout (src/commands/update/index.ts), not a built dist/binary. */
+const FROM_SOURCE = /[\\/]src[\\/]commands[\\/]/.test(import.meta.url)
+/** The standalone release build: the bundle + chisel sit next to the executable (same test as index.ts). */
+const STANDALONE = existsSync(join(dirname(process.execPath), "runtime")) &&
+  existsSync(join(dirname(process.execPath), process.platform === "win32" ? "chisel.exe" : "chisel"))
+
+export default defineCommand({
+  name: "update",
+  summary: "Move everything the project depends on to its newest published state",
+  description: "In dependency order: the desktop host (`desktop update`), matc (`shaders update`), the project's shader compiles, the IDE types (.lecodes/types/ + tsconfig.json, from the server — the former `lecodes types`), the ios/android shell pins (`app update`), then the GLOBAL npm installs: every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor, lecodes-assets) and this CLI that is behind npm's latest gets `npm install -g`.\n\nPinned tools are skipped, not overridden: LECODES_DESKTOP_EXE / LECODES_MATC mean a local build. Keeps going when a step fails; the summary says which.",
+  flags: {
+    local: bool("types from the SDK bundled in this CLI"),
+    "no-shells": bool("leave ios/android pins alone (no re-sync)"),
+    check: bool("npm step: report what's behind, install nothing"),
+    "no-cli": bool("skip the npm step (offline)"),
+  },
+  examples: ["lecodes update", "lecodes update --check", "lecodes update --local --no-shells"],
+  run: async ({ flags }) => {
+    const steps: Step[] = []
+    const heading = (name: string, what: string) => log(`\n${c.bold(name)}  ${c.dim(what)}`)
+    const run = async (name: string, what: string, fn: () => Promise<Outcome | [Outcome, string]>) => {
+      heading(name, what)
+      try {
+        const r = await fn()
+        const [outcome, detail] = Array.isArray(r) ? r : [r, undefined]
+        steps.push({ name, outcome, detail })
+        if (outcome === "skipped" && detail) note(`skipped — ${detail}`)
+      } catch (e) {
+        const msg = e instanceof CliError ? e.message : e instanceof Error ? e.message : String(e)
+        log(c.red("✗ ") + msg)
+        steps.push({ name, outcome: "failed", detail: msg })
+      }
+    }
+
+    const root = findProjectDir(process.cwd())
+
+    // 1. desktop host
+    await run("desktop", "LeCodes Desktop host (desktop run / render --desktop)", async () => {
+      if (process.env.LECODES_DESKTOP_EXE) return ["skipped", `LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE} (a local build; \`lecodes desktop update\` refreshes the cache anyway)`]
+      await updateDesktop()
+      return "ok"
+    })
+
+    // 2. matc
+    await run("matc", "Filament material compiler for local shader compiles", async () => {
+      if (process.env.LECODES_MATC) return ["skipped", `LECODES_MATC=${process.env.LECODES_MATC} (a local matc)`]
+      await updateMatc()
+      return "ok"
+    })
+
+    // 3. shaders (project)
+    await run("shaders", "recompile the project's .mat shaders with the current matc", async () => {
+      if (!root) return ["skipped", "not inside a project"]
+      await compileShaders()
+      return "ok"
+    })
+
+    // 4. types (project)
+    await run("types", flags.local ? "IDE types from the SDK bundled in this CLI" : "IDE types from the server", async () => {
+      if (!root) return ["skipped", "not inside a project"]
+      await refreshTypes({ local: flags.local, check: false })
+      return "ok"
+    })
+
+    // 5. native shells (project)
+    await run("shells", "ios/ + android/ pins → newest SDK release + plugin tags, then re-sync", async () => {
+      if (!root) return ["skipped", "not inside a project"]
+      if (flags["no-shells"]) return ["skipped", "--no-shells"]
+      const present = ["ios", "android"].filter((d) => existsSync(join(root, d)) && readdirSync(join(root, d)).length > 0)
+      if (present.length === 0) return ["skipped", "no ios/ or android/ shell in this project (`lecodes app init ios|android`)"]
+      await runSubcommand(app, "update")
+      return "ok"
+    })
+
+    // 6. this CLI + its optional peers — the GLOBAL npm installs (`npm install -g`, how the CLI and its
+    // peers are installed): every installed one that is behind npm's latest moves forward. The peers go
+    // first, the CLI itself last — replacing the running CLI's files is fine (this process already
+    // holds its code), but its new version is what the next invocation runs, so nothing after it here.
+    // Peers that are NOT installed stay that way: they're optional, installing one is a choice.
+    await run("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
+      if (flags["no-cli"]) return ["skipped", "--no-cli"]
+      if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
+      // Where each peer lives decides how it moves: the CLI's own prefix (~/.lecodes/peers, filled on
+      // first use) is re-installed by peerInstall — the renderer there tracks THIS CLI's version, not
+      // npm's latest, because compiler and headless host are one ABI set; a global install
+      // (`npm install -g`, the old way) moves through npm like before.
+      const rows: { name: string, installed: string | null, latest: string | null, where: "global" | "prefix" | null }[] = []
+      for (const [name, probe] of OPTIONAL_PEERS) {
+        const where = peerSource(name, probe)
+        const installed = peerVersion(name, probe)
+        const latest = !installed ? null
+          : where === "prefix" && name === "lecodes-headless" ? pkg.version
+          : await npmLatest(name)
+        rows.push({ name, installed, latest, where })
+      }
+      rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli"), where: "global" })
+      if (rows.every((r) => r.latest === null)) return ["skipped", "npm unreachable"]
+      const behind = rows.filter((r) => r.installed && r.latest && semverNewer(r.latest, r.installed) > 0)
+      for (const r of rows) {
+        const state = !r.installed ? c.dim("not installed (optional — installed on first use)")
+          : !r.latest ? c.dim("(npm: unknown)")
+          : behind.includes(r) ? c.yellow("→ " + r.latest)
+          : c.dim("(up to date)")
+        log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + (r.where === "prefix" ? c.dim("peers ") : "") + state)
+      }
+      if (behind.length === 0) return "ok"
+      const prefixBehind = behind.filter((r) => r.where === "prefix")
+      const globalSpecs = behind.filter((r) => r.where !== "prefix").map((r) => r.name + "@latest")
+      if (flags.check) {
+        return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")]
+      }
+      const done: string[] = []
+      if (prefixBehind.length) {
+        await installPeers(prefixBehind.map((r) => r.name), "lecodes update", { yes: true })
+        done.push(...prefixBehind.map((r) => r.name))
+      }
+      if (STANDALONE && globalSpecs.some((s) => s.startsWith("lecodes-cli@"))) {
+        note("this is the standalone build — the CLI updates by re-installing the release archive, not through npm; peers still go through npm")
+      }
+      const toInstall = STANDALONE ? globalSpecs.filter((s) => !s.startsWith("lecodes-cli@")) : globalSpecs
+      if (toInstall.length) {
+        log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
+        const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
+        if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
+        done.push(...toInstall.map((s) => s.replace("@latest", "")))
+      }
+      if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
+      const cliToo = done.includes("lecodes-cli")
+      return ["updated", done.join(", ") + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
+    })
+
+    // Summary — one line per step so a scrolled-away failure can't hide.
+    log(`\n${c.bold("Summary")}`)
+    const width = Math.max(...steps.map((s) => s.name.length))
+    for (const s of steps) {
+      const mark = s.outcome === "failed" ? c.red("✗") : s.outcome === "skipped" ? c.dim("–") : c.green("✓")
+      log(`  ${mark} ${s.name.padEnd(width)}  ${s.outcome === "failed" ? c.red(s.detail ?? "failed") : s.outcome === "skipped" ? c.dim(s.detail ?? "skipped") : s.detail ?? s.outcome}`)
+    }
+    if (steps.some((s) => s.outcome === "failed")) process.exitCode = 1
+  },
+})