lecodes-cli 2.4.10 → 2.5.0

package/src/commands/compile.ts

@@ -1,3 +1,4 @@
+import { readAppEnv } from "../project/env"
 import { writeFileSync } from "node:fs"
 import { basename, resolve } from "node:path"
 import { getProject } from "../platform/api"
@@ -229,7 +230,7 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
   }
   const serverUrl = await opts.backend?.start(entries, (w) => warnings.push(w))
   const { js, bakes } = await compileProjectBundle({
-    entries, name, publicUrl, entryOverride, serverUrl,
+    entries, name, publicUrl, entryOverride, serverUrl, env: readAppEnv(root),
     header: bundle.header ?? true,
     localAssets, fontsHeader, iconsHeader,
     minify: bundle.minify,

package/src/commands/hub/create.ts

@@ -0,0 +1,100 @@
+import { existsSync, realpathSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { CliError, UsageError, bool, c, defineCommand, log, note, prompt } from "../../cli"
+import { createRepo, whoami, type HubWhoami } from "../../hub/api"
+import { requireHubConfig } from "../../hub/config"
+import { git, gitOrThrow } from "../../hub/git"
+
+/*
+ * `lecodes hub create [ns/]name [--private]` — make the repo + project on hub for the app in this
+ * folder and connect the folder to it (LeCodesHub/docs/cli.md). A project is a folder with
+ * app.json and nothing else is required, so that is the one precondition. The order keeps a
+ * failure cheap: everything local that can refuse (no app.json, a `hub` remote already there) is
+ * checked before `POST /api/repos`; `git init -b main` and `git remote add hub` come after it.
+ *
+ * Without `ns/` the namespace comes from `GET /api/account`: the user's own account, or — when they
+ * are also in orgs and stdin is a terminal — the one they pick from a numbered list (own account
+ * first, the default). `ns` is always sent explicitly.
+ *
+ * The folder must be the ROOT of its git repo: hub reads `app.json` at the root of every pushed
+ * commit, so a project inside a bigger repo (a subfolder of a monorepo) gets its own repo here.
+ */
+
+const samePath = (a: string, b: string): boolean => {
+  const norm = (p: string): string => {
+    let r = resolve(p)
+    try { r = realpathSync.native(r) } catch { /* as given */ }
+    return process.platform === "win32" ? r.toLowerCase() : r
+  }
+  return norm(a) === norm(b)
+}
+
+/** `den/demo` → { ns: "den", name: "demo" }; `demo` → { name: "demo" } (the server picks the namespace). */
+export const parseRepoArg = (arg: string): { ns?: string, name: string } => {
+  const parts = arg.trim().split("/")
+  if (parts.length === 1 && parts[0]) return { name: parts[0] }
+  if (parts.length === 2 && parts[0] && parts[1]) return { ns: parts[0], name: parts[1] }
+  throw new UsageError(`"${arg}" is not [namespace/]name`)
+}
+
+/**
+ * The namespace to create in: the own account when it is the only one or nobody can answer
+ * (`ask` absent = stdin is not a terminal), else the user's pick — a number or a slug; Enter = 1.
+ */
+export const pickNamespace = async (me: HubWhoami, ask?: (question: string, fallback: string) => Promise<string>): Promise<string> => {
+  const own = me.account.slug
+  const list = [...(me.namespaces ?? [])].sort((a, b) => Number(b.slug === own) - Number(a.slug === own))
+  if (!list.some(n => n.slug === own)) list.unshift({ id: me.account.id, slug: own, name: me.account.name, kind: me.account.kind })
+  if (list.length === 1 || !ask) return own
+  log("Create the repository in:")
+  list.forEach((n, i) => log(`  ${i + 1}) ${c.bold(n.slug)}${c.dim(n.slug === own ? "  your account" : `  ${n.kind}${n.role ? `, ${n.role}` : ""}`)}`))
+  const answer = (await ask("Namespace", "1")).trim()
+  const byNumber = /^\d+$/.test(answer) ? list[Number(answer) - 1] : undefined
+  const chosen = byNumber ?? list.find(n => n.slug === answer)
+  if (!chosen) throw new CliError(`"${answer}" is none of the ${list.length} namespaces listed.`)
+  return chosen.slug
+}
+
+export default defineCommand({
+  name: "create",
+  summary: "Create a hub repo + project for the app in this folder and add it as the `hub` git remote",
+  usage: "[ns/]name",
+  description: "Needs app.json in the current folder (run `lecodes init` first otherwise). Calls hub to create the repository and its project (one production environment, deployed from `main`), runs `git init -b main` when the folder is not a repository yet, and adds the repository as the remote `hub`. Deploying is then a plain `git push hub main`.\n\nWithout a namespace the repo goes to your own account; when you are also a member of orgs, the CLI lists them and asks (in a terminal; otherwise your own account). The project is public unless `--private`.",
+  flags: {
+    private: bool("make the repository and its deployments private"),
+  },
+  examples: ["lecodes hub create demo", "lecodes hub create den/demo --private"],
+  run: async ({ args, flags }) => {
+    const cwd = process.cwd()
+    if (!existsSync(join(cwd, "app.json"))) {
+      throw new CliError("No app.json in this folder — a hub project is a folder with app.json. Run `lecodes init` first (or cd into the project).")
+    }
+    if (!args[0]) throw new UsageError("name the repository: lecodes hub create [ns/]name")
+    const { ns, name } = parseRepoArg(args[0])
+    const config = requireHubConfig()
+
+    const top = git(["rev-parse", "--show-toplevel"], cwd)
+    const isRepo = top.ok && samePath(top.stdout, cwd)
+    if (isRepo) {
+      const existing = git(["remote", "get-url", "hub"], cwd)
+      if (existing.ok) throw new CliError(`This repository already has a "hub" remote (${existing.stdout}). Remove it first: git remote remove hub`)
+    }
+
+    const namespace = ns ?? await pickNamespace(await whoami(config.url, config.token), process.stdin.isTTY ? prompt : undefined)
+    const visibility = flags.private ? "private" : "public"
+    const created = await createRepo(config.url, config.token, { ns: namespace, name, visibility })
+    if (!created || typeof created.remote !== "string") throw new CliError("hub answered without the repository's remote URL.")
+
+    if (!isRepo) {
+      if (top.ok) note(`(inside the repository at ${top.stdout} — this folder gets a repository of its own)`)
+      gitOrThrow(["init", "-b", "main"], cwd)
+    }
+    gitOrThrow(["remote", "add", "hub", created.remote], cwd)
+
+    const branch = git(["symbolic-ref", "--short", "HEAD"], cwd)
+    const pushLine = !branch.ok || branch.stdout === "main" ? "git push hub main" : `git push hub ${branch.stdout}:main`
+    log(`Created ${c.bold(created.remote.replace(/\.git$/, ""))} (${visibility})`)
+    log(`Remote "hub" added. Deploy with:`)
+    log(`  ${pushLine}`)
+  },
+})

package/src/commands/hub/credential.ts

@@ -0,0 +1,32 @@
+import { defineCommand } from "../../cli"
+import { loadHubConfig } from "../../hub/config"
+import { credentialAnswer } from "../../hub/git"
+
+/*
+ * `lecodes hub credential <get|store|erase>` — git's credential-helper protocol over
+ * ~/.lecodes/hub.json; git runs it (`hub login` configures `credential.<hub>.helper`), a person
+ * does not, so it stays out of the help. git writes `key=value` lines on stdin; `get` answers
+ * `username=token` / `password=<PAT>` on stdout only for the stored hub's host
+ * (src/hub/git.ts `credentialAnswer`), and says nothing otherwise. `store` and `erase` are no-ops:
+ * the token's only home is hub.json, and a refused push must not delete it (`hub login` replaces it).
+ */
+
+const readStdin = async (): Promise<string> => {
+  if (process.stdin.isTTY) return ""
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk)
+  return Buffer.concat(chunks).toString("utf8")
+}
+
+export default defineCommand({
+  name: "credential",
+  summary: "git credential helper for hub (internal: git runs it)",
+  usage: "<get|store|erase>",
+  hidden: true,
+  run: async ({ args }) => {
+    const action = args[0] ?? ""
+    const input = await readStdin()
+    const answer = credentialAnswer(action, input, loadHubConfig())
+    if (answer) process.stdout.write(answer)
+  },
+})

package/src/commands/hub/index.ts

@@ -0,0 +1,21 @@
+import { defineCommand } from "../../cli"
+import create from "./create"
+import credential from "./credential"
+import login from "./login"
+import status from "./status"
+
+/*
+ * `lecodes hub …` — the projects on hub (hub.le.codes): git repositories that deploy on push
+ * (LeCodesHub/docs/cli.md). The group adds only what git cannot do: signing in (and git's
+ * credentials with it), creating the repo + project, and reading the deployments. Pushing is
+ * `git push hub main`. The older `login` / `publish` / `releases` / `pull` / `push` / `clone` keep
+ * talking to le.codes and share nothing with this group (its own ~/.lecodes/hub.json, its own client
+ * in src/hub).
+ */
+export default defineCommand({
+  name: "hub",
+  summary: "Projects on hub.le.codes — git repositories that deploy on `git push`: login, create, status",
+  description: "A hub project is a git repository with app.json at its root; every push to `main` deploys to production and every other branch gets a preview URL. `lecodes hub login` signs in and sets up git's credentials, `lecodes hub create` makes the repository and adds the `hub` remote, `lecodes hub status` shows the environments and deployments. Everything else is git.",
+  commands: [login, create, status, credential],
+  examples: ["lecodes hub login", "lecodes hub create demo --private", "git push hub main", "lecodes hub status --follow"],
+})

package/src/commands/hub/login.ts

@@ -0,0 +1,89 @@
+import { hostname } from "node:os"
+import { CliError, c, defineCommand, log, note, str, success, warnErr } from "../../cli"
+import { HubApiError, pollDeviceLogin, startDeviceLogin, whoami, type HubWhoami } from "../../hub/api"
+import { DEFAULT_HUB, loadHubConfig, normalizeHubUrl, saveHubConfig } from "../../hub/config"
+import { configureCredentialHelper, tokenProtocol } from "../../hub/git"
+import { openBrowser } from "../../platform/browserAuth"
+
+/*
+ * `lecodes hub login` — sign this machine in to hub (LeCodesHub/docs/cli.md, accounts.md "Device
+ * flow"). RFC 8628 device flow: ask hub for a device code, show the user code and open the
+ * verification page, poll until the signed-in user approves; the answer is a normal PAT (scopes
+ * `repo` + `deploy`, named `cli on <hostname>`). `--token lch_…` stores a PAT made in the web
+ * instead. Either way the token is checked with `GET /api/account` before anything is written (a
+ * refused token leaves hub.json and the git config as they were), then it goes to ~/.lecodes/hub.json (0600) and git's credential helper for
+ * the hub host is pointed at `lecodes hub credential`, so `git push hub main` authenticates with no
+ * plaintext copy in `.git-credentials`.
+ */
+
+/** `lch_` + 40 of `[a-z0-9]` (accounts.md "Personal access tokens"). */
+const PAT = /^lch_[a-z0-9]{40}$/
+
+const SCOPES = ["repo", "deploy"]
+
+/** The account behind `token`; a 401 / 403 is "this token is refused", nothing else is asked of it. */
+const checkToken = async (url: string, token: string): Promise<HubWhoami> => {
+  try {
+    return await whoami(url, token)
+  } catch (e) {
+    if (e instanceof HubApiError && (e.status === 401 || e.status === 403)) {
+      throw new CliError(`${url} refused the token (${e.status}) — it is wrong, revoked or expired. Nothing was saved.`, e.status)
+    }
+    throw e
+  }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+/** The device flow against `base`: resolves the PAT once the user approved in the browser. */
+export const deviceLogin = async (base: string, open: (url: string) => void = openBrowser, wait = sleep): Promise<string> => {
+  const start = await startDeviceLogin(base, { scopes: SCOPES, name: `cli on ${hostname()}` })
+  const page = new URL(start.verificationUrl, base)
+  if (!page.searchParams.has("code")) page.searchParams.set("code", start.userCode)
+  log(`Open ${c.bold(page.toString())}`)
+  log(`and confirm the code ${c.bold(start.userCode)}`)
+  note("(waiting for the approval in the browser — Ctrl+C to cancel)")
+  open(page.toString())
+
+  let interval = Math.max(1, start.interval || 5) * 1000
+  const deadline = Date.now() + Math.max(1, start.expiresIn || 600) * 1000
+  for (;;) {
+    await wait(interval)
+    if (Date.now() > deadline) break
+    const poll = await pollDeviceLogin(base, start.deviceCode)
+    if (poll.kind === "token") return poll.token
+    if (poll.kind === "expired") break
+    if (poll.kind === "slow-down") interval += 5000
+  }
+  throw new CliError("The login request expired before it was approved. Run `lecodes hub login` again.")
+}
+
+export default defineCommand({
+  name: "login",
+  summary: "Sign this machine in to hub (browser device flow) and set up git's credentials for it",
+  description: "Prints a code and opens hub's approval page; once you approve it there (signed in), the CLI receives a personal access token (scopes repo + deploy, named `cli on <hostname>`) and stores it in ~/.lecodes/hub.json (mode 0600). git's credential helper for the hub host is then pointed at `lecodes hub credential` in your global git config, so `git push hub main` needs no password and no token is written to .git-credentials.\n\n`--token` stores a token you created on hub instead (CI, a machine without a browser). Either way hub is asked who the token belongs to first; a refused token saves nothing. `--url` points at another hub, a local one included (`http://` is accepted for localhost only).",
+  flags: {
+    token: str("store this personal access token instead of the browser flow", { value: "lch_…" }),
+    url: str(`the hub (default: the stored one, else ${DEFAULT_HUB})`, { value: "<url>" }),
+  },
+  examples: ["lecodes hub login", "lecodes hub login --token lch_…", "lecodes hub login --url http://localhost:3000"],
+  run: async ({ flags }) => {
+    const url = normalizeHubUrl(flags.url ?? loadHubConfig()?.url ?? DEFAULT_HUB)
+    if (!tokenProtocol(url)) throw new CliError(`${url}: a hub is reached over https (plain http only on localhost) — the token would travel in clear.`)
+    let token: string
+    if (flags.token !== undefined) {
+      token = flags.token.trim()
+      if (!PAT.test(token)) throw new CliError("--token: a hub token is `lch_` followed by 40 lowercase letters and digits.")
+    } else token = await deviceLogin(url)
+
+    const me = await checkToken(url, token)
+    const missing = SCOPES.filter(s => !(me.scopes ?? []).includes(s))
+    if (missing.length) warnErr(`The token lacks the ${missing.join(" + ")} scope${missing.length > 1 ? "s" : ""}: ${missing.includes("repo") ? "git push" : "the deployments API"} will be refused.`)
+
+    const file = saveHubConfig({ url, token })
+    const { key } = configureCredentialHelper(url)
+    success(`Signed in as ${c.bold(me.account.slug)} on ${url}`)
+    note(`  token: ${file}`)
+    note(`  git:   ${key} → lecodes hub credential (global config)`)
+  },
+})

package/src/commands/hub/status.ts

@@ -0,0 +1,109 @@
+import { CliError, bool, c, defineCommand, log, note, relativeTime, table } from "../../cli"
+import { HubApiError, followDeployLog, getDeploy, getProject, listDeploys, type HubDeploy, type HubProject } from "../../hub/api"
+import { loadHubConfig } from "../../hub/config"
+import { credentialScope, git, parseHubRemote } from "../../hub/git"
+import { openBrowser } from "../../platform/browserAuth"
+
+/*
+ * `lecodes hub status [--follow] [--open]` — the hub project of the repository in this folder,
+ * found by its `hub` remote (LeCodesHub/docs/cli.md): the environments with what they serve, then
+ * the last deployments. The API origin is the remote's own origin, and the stored token is sent
+ * only when that is the hub `hub login` signed in to — a public project answers without one, and a
+ * token is never handed to a host it was not minted for. `--follow` streams the running build's log
+ * (SSE, `…/log?follow=1`; one event = one or more whole lines) and ends with its outcome.
+ */
+
+const LAST = 10
+
+const paintStatus = (status: string): string =>
+  status === "ready" ? c.green(status)
+  : status === "failed" ? c.red(status)
+  : status === "building" || status === "queued" ? c.yellow(status)
+  : c.dim(status)
+
+const oneLine = (s: string | null | undefined, max = 48): string => {
+  const line = (s ?? "").split("\n")[0].trim()
+  return line.length > max ? line.slice(0, max - 1) + "…" : line
+}
+
+const url = (host: string): string => `https://${host}`
+
+const refName = (ref: string): string => ref.replace(/^refs\/(heads|tags)\//, "")
+
+export default defineCommand({
+  name: "status",
+  summary: "Show the hub project of this repository: environments, the last deployments, a running build's log",
+  description: "Reads the `hub` git remote (added by `lecodes hub create`) to find the project, then prints each environment with the deployment it serves and the last deployments with their status and URLs. `--follow` streams the log of the build that is running (or queued) until it finishes; `--open` opens the project's page on hub.",
+  flags: {
+    follow: bool("stream the running build's log until it finishes"),
+    open: bool("open the project's page in the browser"),
+  },
+  examples: ["lecodes hub status", "lecodes hub status --follow"],
+  run: async ({ flags }) => {
+    const remote = git(["remote", "get-url", "hub"])
+    if (!remote.ok) throw new CliError("This repository has no \"hub\" remote. Create the project with `lecodes hub create <name>` (or add the remote: git remote add hub <url>).")
+    const where = parseHubRemote(remote.stdout)
+    if (!where) throw new CliError(`The "hub" remote (${remote.stdout}) is not a hub repository URL (https://<hub>/<namespace>/<name>.git).`)
+    const { base, ns, name } = where
+    const config = loadHubConfig()
+    const token = config && credentialScope(config.url) === credentialScope(base) ? config.token : undefined
+    const page = `${base}/${ns}/${name}`
+
+    if (flags.open) openBrowser(page)
+
+    let project: HubProject, deploys: HubDeploy[]
+    try {
+      [project, deploys] = await Promise.all([getProject(base, token, ns, name), listDeploys(base, token, ns, name)])
+    } catch (e) {
+      if (e instanceof HubApiError && e.status === 404) {
+        throw new CliError(`${page}: no such project${token ? "" : " (or it is private — sign in with `lecodes hub login`)"}.`, 404)
+      }
+      throw e
+    }
+
+    log(`${c.bold(`${ns}/${name}`)}  ${page}${project.project?.visibility ? c.dim(`  (${project.project.visibility})`) : ""}`)
+
+    log("")
+    log(c.bold("Environments"))
+    if (!project.environments?.length) log(c.dim("  none"))
+    else table(project.environments.map(env => {
+      const cur = env.current
+      return [
+        env.name,
+        url(env.host),
+        cur ? `#${cur.number} ${paintStatus(cur.status)}` : c.dim("nothing deployed"),
+        cur ? cur.commit.slice(0, 7) : "",
+        cur ? relativeTime(cur.finishedAt ?? cur.createdAt) : "",
+      ]
+    }))
+
+    log("")
+    log(c.bold("Deployments"))
+    const last = deploys.slice(0, LAST)
+    if (!last.length) log(c.dim("  none yet — deploy with: git push hub main"))
+    else table(last.map(d => [
+      `#${d.number}`,
+      paintStatus(d.status),
+      d.environment ?? c.dim("preview"),
+      refName(d.ref),
+      d.commit.slice(0, 7),
+      oneLine(d.message),
+      relativeTime(d.createdAt),
+      d.status === "ready" ? url(d.host) : c.dim(url(d.host)),
+    ]))
+
+    if (!flags.follow) return
+    const running = deploys.find(d => d.status === "building") ?? deploys.find(d => d.status === "queued")
+    if (!running) { log(""); note("No build is running."); return }
+    log("")
+    note(`Following #${running.number} (${running.status}) — Ctrl+C stops following, not the build`)
+    await followDeployLog(base, token, ns, name, running.number, text => { process.stdout.write(text.endsWith("\n") ? text : text + "\n") })
+    const done = await getDeploy(base, token, ns, name, running.number)
+    log("")
+    if (done.status === "ready") log(`#${done.number} ${paintStatus(done.status)} → ${url(done.host)}`)
+    else {
+      log(`#${done.number} ${paintStatus(done.status)}${done.error ? `: ${done.error}` : ""}`)
+      if (done.status === "failed") process.exitCode = 1
+    }
+  },
+})

package/src/commands/index.ts

@@ -7,6 +7,7 @@ import create from "./create"
 import design from "./design"
 import desktop from "./desktop"
 import dev from "./dev"
+import hub from "./hub"
 import diff from "./diff"
 import init from "./init"
 import install from "./install"
@@ -20,10 +21,12 @@ import publish from "./publish"
 import pull from "./pull"
 import push from "./push"
 import releases from "./releases"
+import secrets from "./secrets"
 import render from "./render"
 import scene from "./scene"
 import serve from "./serve"
 import shaders from "./shaders"
+import level from "./level"
 import status from "./status"
 import test from "./test"
 import thumbs from "./thumbs"
@@ -35,7 +38,7 @@ import web from "./web"
  * here, in the group it belongs to (CONTRIBUTING.md). Order within a group is the help's order.
  */
 export const commandGroups = (opts: { install: boolean }): Group[] => [
-  { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, publish, releases, login] },
+  { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, publish, releases, secrets, login, hub] },
   { title: "Run & test", commands: [
     dev,
     web,
@@ -53,6 +56,7 @@ export const commandGroups = (opts: { install: boolean }): Group[] => [
   { title: "Content", commands: [
     assets,
     shaders,
+    level,
     lightmap,
     navmesh,
   ] },

package/src/commands/level.ts

@@ -0,0 +1,123 @@
+/**
+ * `lecodes level build` — the level's derived artifacts from ONE run of the level: the static level cache and the
+ * navigation mesh. The level is run the slow, complete way through the windowless host with the entry put in the
+ * tool runs' mode (`globalThis.__lecodesStatic` + `__lecodesNavmesh`, then `import "./<entry>"`); once it is loaded
+ * and its bake (if any) bound, the SDK snapshots the covered static subtrees into `<bake stem>.static` beside the
+ * `.bake` (gl/Statics.ts: placements, bodies, the bake's records per primitive) and dumps the static collision
+ * geometry, which Recast turns into the scene's own `env.navmesh` file here.
+ *
+ * What each tool owns: the SCENE FILE is the source (the `static` verdict, `foliage`, the bake() target, env.navmesh);
+ * the RUNTIME builds and snapshots; `lecodes lightmap bake` (lecodes-bake) traces and, when a cache exists, stitches
+ * its fresh records into it (a join by node path, no host run); this command joins the rest. Rerun it after a
+ * re-import or an edit of the statics (the cache carries their digest and declines itself until then); a rebake
+ * alone needs no rerun.
+ */
+
+import { existsSync, mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, dirname, join, resolve } from "node:path"
+import { buildBundle } from "./compile"
+import { readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { runDesktopRender, type HostKind } from "../hosts/desktopRenderer"
+import { CliError, bool, c, defineCommand, logErr, note, num, str, warnErr } from "../cli"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
+import { NAVMESH_FLAGS, finishNavmesh } from "./navmesh"
+
+const build = defineCommand({
+  name: "build",
+  summary: "The level's static cache + navmesh from one run of the level",
+  description: "Runs the level once through the windowless host (lecodes-server beside the desktop host; --host desktop for the window host) and writes: <bake stem>.static beside the level's .bake — the static subtree (models, colliders, the bake's rects per primitive) the engine rebuilds natively on every later load — and, when the level declares env.navmesh, its navmesh file through Recast (the one the scene names; a level's FIRST navmesh is `lecodes navmesh bake`'s, which starts from a placeholder). Rerun after a re-import or an edit of the statics; `lecodes lightmap bake` keeps the cache's records current on its own.",
+  flags: {
+    ...bundleFlags,
+    entry: str("the file that opens the level: a scene file with env.lightmap (and env.navmesh)", { value: "<file>", default: "main.ts" }),
+    ...NAVMESH_FLAGS,
+    host: str("which host runs the level: server (windowless, default) or desktop", { value: "<server|desktop>", default: "server" }),
+    frames: num("host frames to run before giving up — load headroom", { default: 6000 }),
+    timeout: num("host time cap (ms)", { default: 600000 }),
+    width: num("host window width (default: app.json desktop.window, else 1280)"),
+    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    logs: bool("forward the host's output"),
+  },
+  examples: ["lecodes level build --entry chernobyl.ts", "lecodes level build --entry chernobyl.ts --host desktop --logs"],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const entryFile = flags.entry
+    if (!existsSync(resolve(root, entryFile))) {
+      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that opens the level: a scene file with env.lightmap).`)
+    }
+    const host: HostKind = flags.host === "desktop" ? "desktop" : "server"
+    const frames = Math.max(30, Math.min(100000, flags.frames || 6000))
+    const win = readAppConfigAt(root)?.desktop?.window
+    const width = flags.width || win?.width || 1280
+    const height = win?.height || 720
+    const logs = flags.logs
+
+    // the entry in the tool runs' mode; the navmesh's place is filled in below, once the compile names the scene's file
+    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+    const entryPath = "/.level-entry.ts"
+    const cfgStatic = { root: root.replace(/\\/g, "/") }
+    const desktopRenderer = host === "server" ? ("gl" as const) : resolveDesktopRenderer(root, flags.renderer)
+    const compile = (navOutDir: string, navName: string) => buildBundle(bundleOptions(flags), {
+      localAssets: true, desktopRenderer,
+      extraEntries: [{ path: entryPath, type: "text", text: `globalThis.__lecodesStatic = ${JSON.stringify(cfgStatic)}\nglobalThis.__lecodesNavmesh = ${JSON.stringify({ outDir: navOutDir.replace(/\\/g, "/"), name: navName })}\nimport ${JSON.stringify(importPath)}\n` }],
+      entryOverride: entryPath,
+    })
+    // the navmesh goes where the scene's env.navmesh file is: the one .navmesh resource the bundle names
+    let { js, resources } = await compile(root, "level")
+    const named = new Set([ ...js.matchAll(/(?:fetchLocal|_creatorFetch\.local)\("([^"]+\.navmesh)"\)/g) ].map((m) => m[1]))
+    const navFiles = resources.filter((r) => !r.remote && r.absPath && named.has(r.name)).map((r) => r.absPath!)
+    let navOut: string | null = null, navName: string | null = null
+    if (navFiles.length === 1) {
+      navOut = dirname(navFiles[0]); navName = basename(navFiles[0]).replace(/\.navmesh$/, "")
+      ;({ js, resources } = await compile(navOut, navName))
+    } else if (navFiles.length > 1) {
+      throw new CliError(`${entryFile} reaches ${navFiles.length} navmesh files (${navFiles.map((f) => basename(f)).join(", ")}) — build one level per entry.`)
+    }
+
+    const scratch = mkdtempSync(join(tmpdir(), "lecodes-level-"))
+    const outPng = join(scratch, "frame.png")
+    note(`Loading the level through the ${host} host: the static cache${navName ? `, the collision geometry for ${navName}.navmesh` : ""}…`)
+    let output = ""
+    try {
+      const res = await runDesktopRender(js, resources, {
+        host, renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs: flags.timeout || 600000,
+        stopOnLine: (chunk) => chunk.includes("[static] done") || chunk.includes("[static] error"),
+      })
+      output = res.output
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/\[static\] done/.test(msg)) throw e
+      output = msg
+    } finally {
+      rmSync(scratch, { recursive: true, force: true })
+    }
+
+    // the static cache: the SDK's `[static]` lines
+    const lines = output.split(/\r?\n/).filter((l) => l.includes("[static]")).map((l) => l.slice(l.indexOf("[static]") + "[static]".length).trim())
+    let wrote: string | null = null
+    for (const text of lines) {
+      if (text === "done") continue
+      const m = /^wrote (.+?): (\d.*)$/.exec(text)
+      if (m) { wrote = m[1]; logErr(c.dim(`  ${m[2]}`)); continue }
+      logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : c.dim(`  ${text}`))
+    }
+    if (!/\[static\] done/.test(output)) {
+      warnErr("The host ran to its frame cap without writing the cache. Make sure the entry opens a scene file with env.lightmap (the cache lives beside the bake) and skips menus under a tool run. More load headroom: --frames <n>. Host output: --logs.")
+      throw new CliError("Nothing was written.")
+    }
+    if (!wrote) throw new CliError("The snapshot failed — see the lines above.")
+    logErr(c.green(`✓ static cache → ${wrote.replace(cfgStatic.root + "/", "")}`))
+    if (/no bake bound/.test(output)) logErr(c.dim("  (unbaked: placements and bodies only — `lecodes lightmap bake` adds the rects to it)"))
+
+    // the navmesh: only a level that declares env.navmesh dumped geometry
+    if (navOut && navName && /\[navmesh\] (config|error)/.test(output)) await finishNavmesh(root, navOut, navName, output, flags)
+    else logErr(c.dim("  no navmesh: the level declares no env.navmesh file"))
+    logErr(c.dim("  rerun after a re-import or an edit of the statics; a rebake (lecodes lightmap bake) updates the cache on its own"))
+  },
+})
+
+export default defineCommand({
+  name: "level",
+  summary: "A level's derived artifacts: the static cache and the navmesh (build)",
+  commands: [build],
+})