lecodes-cli 0.18.2 → 0.19.2

package/src/commands/navmesh.ts

@@ -0,0 +1,225 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, join, relative, resolve } from "node:path"
+import { findProjectRoot } from "../manifest"
+import { buildBundle } from "./compile"
+import { readAppConfigAt, resolveDesktopRenderer } from "./appShared"
+import { runDesktopRender } from "../desktopRenderer"
+import { CliError, c, flagStr, flagBool, logErr, note, warnErr, type Args } from "../util"
+import { loadCreatorNav, NavBuilder, readNgeo, navMeshTriangles, type BuildParams } from "lecodes-creator-nav"
+
+/*
+ * `lecodes navmesh bake` — build the level's navigation mesh (docs/navmesh-plan.md §4). Two halves:
+ *
+ *   1. The app is compiled with a synthetic entry that puts it in BAKE mode
+ *      (`globalThis.__lecodesNavmesh = { outDir, name }`, then `import "./main"`) and run in the
+ *      native desktop host; when the level is complete — the scene file's `env.navmesh`, or a
+ *      hand-written `NavMesh.load(...)` — the SDK calls `_creator.physicsStaticGeometry` instead of
+ *      loading: every STATIC Jolt body's triangles land in `<out>/<name>.navgeo`, and the host's
+ *      stdout carries `[navmesh] geometry …` / `[navmesh] config {…}` / `[navmesh] done`.
+ *   2. Recast runs HERE (creator-nav's wasm): the dump + the scene's agent size (+ the flags below)
+ *      → a tiled Detour navmesh → `<out>/<name>.navmesh` (LNAV: header JSON + tiles).
+ *
+ * Running the build in the CLI keeps the host generic (a geometry dump, useful on its own),
+ * lets the bake parameters iterate without a host rebuild, and is the same code a future headless
+ * bake reuses. The desktop host must know the dump (built from packages/desktop, or a release that
+ * ships it: LECODES_DESKTOP_EXE for a local build until then).
+ */
+
+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
+}
+
+type BakeConfigLine = {
+  agent: { radius: number, height: number, climb: number, slope: number }
+  areas: Record<string, number>
+  costs: Record<string, number>
+  data?: string
+}
+
+/** The first `*.scene.ts` under src/ (or the root) that declares `navmesh:` names the output by default. */
+const guessName = (root: string): string | null => {
+  const dirs = [ join(root, "src"), root ]
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue
+    let entries: string[]
+    try { entries = readdirSync(dir) } catch { continue }
+    for (const f of entries) {
+      if (!f.endsWith(".scene.ts")) continue
+      try {
+        if (/\bnavmesh\s*:/.test(readFileSync(join(dir, f), "utf8"))) return f.slice(0, -".scene.ts".length)
+      } catch { /* skip */ }
+    }
+  }
+  return null
+}
+
+/** An empty LNAV (header only, one dummy tile slot) so the compiler can stage the file before the
+ *  first bake; NavMesh.load reads `stats.polys === 0` as "placeholder — rebake". */
+const placeholderLnav = (): Buffer => {
+  const json = Buffer.from(JSON.stringify({ version: 1, placeholder: true, stats: { tiles: 0, polys: 0 } }), "utf8")
+  const jsonPadded = Buffer.alloc(Math.ceil(json.length / 4) * 4)
+  json.copy(jsonPadded)
+  const head = Buffer.alloc(12)
+  head.writeUInt32LE(0x56414e4c, 0)   // 'LNAV'
+  head.writeUInt32LE(1, 4)
+  head.writeUInt32LE(json.length, 8)
+  // dtNavMeshParams: orig[3] f32, tileWidth, tileHeight f32, maxTiles, maxPolys i32
+  const params = Buffer.alloc(28)
+  params.writeFloatLE(1, 12)
+  params.writeFloatLE(1, 16)
+  params.writeInt32LE(1, 20)
+  params.writeInt32LE(1, 24)
+  const tiles = Buffer.alloc(4)
+  return Buffer.concat([ head, jsonPadded, params, tiles ])
+}
+
+const writeObj = (path: string, tris: Float32Array): void => {
+  const lines: string[] = [ "# navmesh polygons — lecodes navmesh bake --obj" ]
+  for (let i = 0; i < tris.length; i += 3) lines.push(`v ${tris[i]!.toFixed(4)} ${tris[i + 1]!.toFixed(4)} ${tris[i + 2]!.toFixed(4)}`)
+  for (let i = 0; i < tris.length / 3; i += 3) lines.push(`f ${i + 1} ${i + 2} ${i + 3}`)
+  writeFileSync(path, lines.join("\n") + "\n")
+}
+
+const bake = async (args: Args): Promise<void> => {
+  let root: string
+  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
+  const outDir = resolve(root, flagStr(args, "out") ?? "assets/nav")
+  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 level: a scene file with env.navmesh, or code calling NavMesh.load).`)
+  }
+  const name = flagStr(args, "name") ?? guessName(root) ?? "scene"
+  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")
+  const keepGeometry = flagBool(args, "keep-geometry")
+  const obj = flagBool(args, "obj")
+
+  // The navmesh file must exist BEFORE the compile: the scene references it through asset(), and a
+  // missing asset is a broken bundle. The first bake starts from a placeholder the real file overwrites.
+  mkdirSync(outDir, { recursive: true })
+  const navmeshPath = join(outDir, `${name}.navmesh`)
+  if (!existsSync(navmeshPath)) writeFileSync(navmeshPath, placeholderLnav())
+
+  const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+  const entryPath = "/.navmesh-entry.ts"
+  const cfg = { outDir: outDir.replace(/\\/g, "/"), name }
+  const entryText = `globalThis.__lecodesNavmesh = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
+
+  const desktopRenderer = resolveDesktopRenderer(root, args)
+  const { js, resources } = await buildBundle(args, undefined, {
+    localAssets: true, desktopRenderer,
+    extraEntries: [{ path: entryPath, type: "text", text: entryText }],
+    entryOverride: entryPath,
+  })
+
+  const scratch = mkdtempSync(join(tmpdir(), "lecodes-navmesh-"))
+  const outPng = join(scratch, "frame.png")
+  note(`Dumping the level's static collision geometry through the desktop host → ${relative(root, outDir) || "."}/${name}.navgeo…`)
+  let output = ""
+  try {
+    const timeoutMs = Number(flagStr(args, "timeout")) || 600000
+    const res = await runDesktopRender(js, resources, {
+      renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs,
+      stopOnLine: (chunk) => chunk.includes("[navmesh] done") || chunk.includes("[navmesh] error"),
+    })
+    output = res.output
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    if (!/\[navmesh\] done/.test(msg)) throw e
+    output = msg
+  } finally {
+    rmSync(scratch, { recursive: true, force: true })
+  }
+
+  // the markers are console.log lines from the SDK — the host prefixes them ("[DEBUG] [navmesh] …")
+  const lines = output.split(/\r?\n/).filter((l) => l.includes("[navmesh]")).map((l) => l.slice(l.indexOf("[navmesh]")))
+  let config: BakeConfigLine | null = null
+  let triangles = 0
+  for (const l of lines) {
+    const text = l.slice("[navmesh]".length).trim()
+    if (text === "done") continue
+    if (text.startsWith("config ")) { try { config = JSON.parse(text.slice(7)) as BakeConfigLine } catch { /* reported below */ } continue }
+    const geo = /^geometry (\d+) triangles/.exec(text)
+    if (geo) triangles = Number(geo[1])
+    logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : c.dim(`  ${text}`))
+  }
+  if (!/\[navmesh\] done/.test(output)) {
+    if (lines.some((l) => /cannot dump collision geometry/.test(l))) {
+      throw new CliError("This desktop host has no collision-geometry dump. Build packages/desktop 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 dumping geometry. Make sure the level declares `env.navmesh` (a scene file) or calls NavMesh.load(...) after its static bodies exist, and skips menus when NavMesh.baking is true. More load headroom: --frames <n>. Host output: --logs.")
+    throw new CliError("Nothing was baked.")
+  }
+  if (!config) throw new CliError("The host reported a dump but no `[navmesh] config` line — SDK/host mismatch?")
+  const geoPath = join(outDir, `${name}.navgeo`)
+  if (!existsSync(geoPath)) throw new CliError(`The host reported a dump but ${geoPath} is missing.`)
+
+  // ---- Recast (wasm) ----
+  const geo = readNgeo(new Uint8Array(readFileSync(geoPath)))
+  const params: BuildParams = {
+    agentRadius: num(args, "radius", config.agent.radius, 0.05, 10),
+    agentHeight: num(args, "height", config.agent.height, 0.1, 20),
+    agentMaxClimb: num(args, "climb", config.agent.climb, 0, 10),
+    agentMaxSlope: num(args, "slope", config.agent.slope, 0, 89),
+    cellSize: num(args, "cell", 0.25, 0.01, 5),
+    cellHeight: num(args, "cell-height", 0.1, 0.01, 5),
+    tileSize: num(args, "tile", 48, 0, 1024),
+    regionMinSize: num(args, "region-min", 8, 0, 1000),
+    regionMergeSize: num(args, "region-merge", 20, 0, 1000),
+    edgeMaxLen: num(args, "edge-max", 12, 0, 1000),
+    edgeMaxError: num(args, "edge-error", 1.3, 0.1, 10),
+    detailSampleDist: num(args, "detail", 6, 0, 100),
+    detailMaxError: num(args, "detail-error", 1, 0, 100),
+  }
+  note(`Building the navmesh: ${geo.triangleCount} triangles from ${geo.bodyCount} static bodies, agent r ${params.agentRadius} / h ${params.agentHeight} / climb ${params.agentMaxClimb} / slope ${params.agentMaxSlope}°, cell ${params.cellSize} m…`)
+  const mod = await loadCreatorNav()
+  const builder = new NavBuilder(mod, params)
+  let result
+  try {
+    builder.addSoup(geo.triangles, geo.areas)
+    const meta = {
+      scene: name, areas: config.areas, costs: config.costs, bakedAt: new Date().toISOString(),
+      params, triangles: geo.triangleCount, bodies: geo.bodyCount,
+    }
+    let lastTile = -1
+    result = builder.run(meta, (tile, count, message) => {
+      if (message) logErr(c.dim(`  recast: ${message}`))
+      else if (count > 8 && tile !== lastTile && (tile + 1) % Math.max(1, Math.floor(count / 8)) === 0) { lastTile = tile; logErr(c.dim(`  tile ${tile + 1}/${count}`)) }
+    })
+  } finally {
+    builder.destroy()
+  }
+  if (result.polys === 0) {
+    throw new CliError("The build produced no polygons — nothing walkable for this agent. Check the cell size against the level's scale, the slope, and that the floor is a STATIC body (Shape + Physics { motion: 'static' }).")
+  }
+  writeFileSync(navmeshPath, result.data)
+  if (obj) {
+    const objPath = join(outDir, `${name}.navmesh.obj`)
+    writeObj(objPath, navMeshTriangles(mod, result.data))
+    logErr(c.dim(`  wrote ${relative(root, objPath)} (the polygon mesh, for inspection)`))
+  }
+  if (!keepGeometry) unlinkSync(geoPath)
+  const kb = Math.round(statSync(navmeshPath).size / 1024)
+  const b = result.bounds
+  logErr(c.dim(`  ${result.tiles} tiles, ${result.polys} polygons, ${(b.max[0] - b.min[0]).toFixed(0)} × ${(b.max[2] - b.min[2]).toFixed(0)} m, ${result.time.toFixed(1)} s`))
+  logErr(c.green(`✓ baked → ${relative(root, navmeshPath).replace(/\\/g, "/")} (${kb} KB)`))
+  if (!config.data) {
+    logErr(c.dim(`  load it with env.navmesh: { data: asset('<rel>/${basename(navmeshPath)}') } in the scene file, or NavMesh.load(scene, { data: asset(...) })`))
+  }
+}
+
+export const navmesh = async (args: Args): Promise<void> => {
+  const sub = args._[0]
+  if (sub === "bake") return bake({ ...args, _: args._.slice(1) })
+  throw new CliError("Usage: lecodes navmesh bake [--out assets/nav] [--name <scene>] [--entry main.ts] [--radius 0.4] [--height 1.8] [--climb 0.4] [--slope 50] [--cell 0.25] [--cell-height 0.1] [--tile 48] [--obj] [--keep-geometry] [--frames 900] [--logs]")
+}

package/src/commands/pn.ts

@@ -0,0 +1,305 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  createPushKey, forgetPushDevice, listPushDevices, listPushKeys, revokePushKey, sendPush,
+  type PushDevice, type PushSendPayload,
+} from "../api"
+import { loadConfig, requireApiUrl, requireToken } from "../config"
+import { findProjectRoot, readManifest } from "../manifest"
+import { CliError, c, confirm, flagBool, flagStr, info, log, success, warn, type Args } from "../util"
+
+/*
+ * `lecodes pn` — push notifications for this project (docs/push-plan.md). Named `pn` because
+ * `lecodes push` is already the code-upload command.
+ *
+ *   pn send      test-send using the PAT from `lecodes login` — /push/send accepts a
+ *                developer-role user token exactly like a project push key, so the dev loop
+ *                needs NO key at all.
+ *   pn devices   which devices actually registered — the first thing to check when a push
+ *                doesn't arrive (an empty list means the app never called Push.register()).
+ *   pn keys      mint / list / revoke the `lecodes_pk_…` keys. The SERVER generates these;
+ *                the plaintext exists in the mint response and nowhere else, so `keys new`
+ *                is the only moment it can be captured (--env captures it for you).
+ *
+ * Everything is scoped to the project in .lecodes/manifest.json — no uuid to look up.
+ */
+
+const ENV_VAR = "LECODES_PUSH_KEY"
+
+type Context = { root: string, uuid: string, name: string, apiUrl: string, token: string }
+
+const context = (): Context => {
+  const root = findProjectRoot(process.cwd())
+  const manifest = readManifest(root)
+  const config = loadConfig()
+  return { root, uuid: manifest.uuid, name: manifest.name, apiUrl: requireApiUrl(config), token: requireToken(config) }
+}
+
+/** A compact "3h ago" — absolute timestamps make these tables unreadable at a glance. */
+const ago = (iso: string | null): string => {
+  if (!iso) return c.dim("never")
+  const ms = Date.now() - new Date(iso).getTime()
+  if (!Number.isFinite(ms)) return c.dim("—")
+  const mins = Math.round(ms / 60_000)
+  if (mins < 1) return "just now"
+  if (mins < 60) return `${mins}m ago`
+  const hours = Math.round(mins / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.round(hours / 24)}d ago`
+}
+
+// Column widths must count PRINTED characters: on a TTY the cells carry ANSI color codes, and
+// padEnd would count those too — every colored column drifting a few chars wide.
+const ANSI = /\x1b\[[0-9;]*m/g
+const printed = (s: string) => s.replace(ANSI, "").length
+
+/** Print rows as aligned columns (last column unpadded so colors don't drag trailing spaces). */
+const table = (rows: string[][]) => {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map(r => printed(r[i] ?? ""))))
+  for (const row of rows) {
+    const cells = row.map((cell, i) =>
+      i === row.length - 1 ? cell : cell + " ".repeat(Math.max(0, widths[i] - printed(cell))))
+    log("  " + cells.join("  "))
+  }
+}
+
+/** Comma-separated list flag. parseArgs keeps only the LAST of a repeated `--user`, so repeats
+ *  would silently drop targets — commas are the form that can't lose one. */
+const listFlag = (args: Args, ...keys: string[]): string[] => {
+  const raw = flagStr(args, ...keys)
+  if (!raw) return []
+  return [ ...new Set(raw.split(",").map(s => s.trim()).filter(Boolean)) ]
+}
+
+/* ---------------------------------------- send ---------------------------------------- */
+
+/** `lecodes pn send --title … [--user u42] [--to pa_…]` — a real send through the relay,
+ *  authenticated with your own token. Targets are the same ones a production server uses. */
+const pnSend = async (args: Args) => {
+  const ctx = context()
+
+  const title = flagStr(args, "title", "t") ?? args._[1]
+  if (!title) throw new CliError('A title is required: lecodes pn send --title "Order shipped" --user u42')
+
+  const users = listFlag(args, "user", "users", "u")
+  const to = listFlag(args, "to", "address", "addresses")
+  if (users.length === 0 && to.length === 0) {
+    throw new CliError("Nothing to send to — pass --user <id> (from Push.register({ user })) or --to <pa_…>. `lecodes pn devices` lists both.")
+  }
+
+  const badgeRaw = flagStr(args, "badge")
+  const badge = badgeRaw === undefined ? undefined : Number(badgeRaw)
+  if (badge !== undefined && !Number.isInteger(badge)) throw new CliError(`--badge must be a whole number (got "${badgeRaw}")`)
+
+  const dataRaw = flagStr(args, "data")
+  let data: Record<string, unknown> | undefined
+  if (dataRaw !== undefined) {
+    try { data = JSON.parse(dataRaw) as Record<string, unknown> } catch { throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'") }
+    if (!data || typeof data !== "object" || Array.isArray(data)) throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'")
+  }
+
+  const payload: PushSendPayload = {
+    title,
+    body: flagStr(args, "body", "b"),
+    url: flagStr(args, "url"),
+    users: users.length ? users : undefined,
+    to: to.length ? to : undefined,
+    data,
+    badge,
+  }
+
+  const result = await sendPush(ctx.apiUrl, ctx.token, ctx.uuid, payload)
+
+  if (result.sent > 0) success(`Sent to ${result.sent} device${result.sent === 1 ? "" : "s"}.`)
+  if (result.failed.length === 0) {
+    if (result.sent === 0) {
+      warn("Matched 0 devices — nobody with that user id has registered. Run `lecodes pn devices` to see who has.")
+    }
+    return
+  }
+  warn(`${result.failed.length} failed:`)
+  for (const failure of result.failed) log(`  ${c.dim(failure.address)}  ${c.red(failure.reason)}`)
+}
+
+/* -------------------------------------- devices --------------------------------------- */
+
+const deviceLabel = (device: PushDevice): string => {
+  const env = device.environment === "sandbox" ? c.yellow(" sandbox") : ""
+  return `${device.platform}${env}`
+}
+
+/** `lecodes pn devices [--user u42] [--forget pa_…]` — the registration ledger. Raw OS tokens
+ *  never leave the backend, so this is address + who/where/when only. --forget drops a dead row
+ *  (rotated token, wrong project) that would otherwise sit here forever and fail every send. */
+const pnDevices = async (args: Args) => {
+  const ctx = context()
+  const user = flagStr(args, "user", "u")
+
+  const forget = flagStr(args, "forget")
+  if (forget) {
+    if (!flagBool(args, "yes", "y")) {
+      warn(`Forgetting ${c.bold(forget)} — sends to this address stop immediately. The device gets a NEW address on its next Push.register().`)
+      if (!await confirm("Forget it?")) return info("Cancelled.")
+    }
+    await forgetPushDevice(ctx.apiUrl, ctx.token, ctx.uuid, forget)
+    success(`Forgot ${c.bold(forget)}.`)
+    return
+  }
+
+  const { devices, truncated } = await listPushDevices(ctx.apiUrl, ctx.token, ctx.uuid, user)
+
+  if (devices.length === 0) {
+    info(user
+      ? `No devices registered for user ${c.bold(user)} in ${c.bold(ctx.name)}.`
+      : `No devices registered in ${c.bold(ctx.name)} yet.`)
+    info(c.dim("A device appears here after the app calls Push.register(). Note that `lecodes dev`"))
+    info(c.dim("bundles are unattributed — register() rejects there; open a PUBLISHED project via QR."))
+    return
+  }
+
+  info(`${devices.length} device${devices.length === 1 ? "" : "s"} in ${c.bold(ctx.name)}${user ? ` for user ${c.bold(user)}` : ""}:`)
+  table([
+    [c.dim("ADDRESS"), c.dim("PLATFORM"), c.dim("USER"), c.dim("HOST"), c.dim("LAST SEEN")],
+    ...devices.map(device => [
+      device.disabledAt ? c.dim(device.address) : device.address,
+      deviceLabel(device),
+      device.user ?? c.dim("—"),
+      device.hostApp,
+      device.disabledAt ? c.red("disabled") : ago(device.lastSeenAt),
+    ]),
+  ])
+  if (devices.some(d => d.disabledAt)) {
+    info(c.dim("Disabled = the provider reported a dead token; re-registering from the device revives it."))
+  }
+  if (truncated) warn("Showing the 200 most recently seen — there are more.")
+}
+
+/* ---------------------------------------- keys ---------------------------------------- */
+
+const pnKeysList = async (ctx: Context) => {
+  const keys = await listPushKeys(ctx.apiUrl, ctx.token, ctx.uuid)
+  if (keys.length === 0) {
+    info(`No push keys in ${c.bold(ctx.name)}.`)
+    info(c.dim("You only need one to send from your OWN server — `lecodes pn send` uses your login."))
+    info(c.dim("Mint one with `lecodes pn keys new \"prod server\" --env`."))
+    return
+  }
+  info(`${keys.length} push key${keys.length === 1 ? "" : "s"} in ${c.bold(ctx.name)}:`)
+  table([
+    [c.dim("ID"), c.dim("NAME"), c.dim("KEY"), c.dim("LAST USED")],
+    ...keys.map(key => [String(key.id), key.name, `${key.prefix}${c.dim("…")}`, ago(key.lastUsedAt)]),
+  ])
+}
+
+/** Append `LECODES_PUSH_KEY=…` to <root>/.env and make sure git can't swallow it. Returns the
+ *  paths touched. A key already in .env is REPLACED — rotating shouldn't leave two live lines. */
+const writeEnv = (root: string, key: string): string[] => {
+  const touched: string[] = []
+  const envPath = join(root, ".env")
+  const line = `${ENV_VAR}=${key}`
+
+  const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
+  if (new RegExp(`^${ENV_VAR}=`, "m").test(existing)) {
+    writeFileSync(envPath, existing.replace(new RegExp(`^${ENV_VAR}=.*$`, "m"), line))
+  } else {
+    const separator = !existing || existing.endsWith("\n") ? "" : "\n"
+    appendFileSync(envPath, `${separator}${line}\n`)
+  }
+  touched.push(".env")
+
+  // A push key in a committed .env is the one way this command could make things worse.
+  const ignorePath = join(root, ".gitignore")
+  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
+  if (!ignore.split("\n").some(l => l.trim() === ".env")) {
+    const separator = !ignore || ignore.endsWith("\n") ? "" : "\n"
+    appendFileSync(ignorePath, `${separator}.env\n`)
+    touched.push(".gitignore")
+  }
+  return touched
+}
+
+/** `lecodes pn keys new [name] [--env]` — the server mints it; this is the ONLY time the
+ *  plaintext exists anywhere, so print it loudly (or bank it in .env with --env). */
+const pnKeysNew = async (ctx: Context, args: Args) => {
+  const name = args._[2] ?? flagStr(args, "name")
+  const created = await createPushKey(ctx.apiUrl, ctx.token, ctx.uuid, name)
+
+  success(`Created push key ${c.bold(created.name)} (id ${created.id}).`)
+  log()
+  log(`  ${c.bold(created.key)}`)
+  log()
+
+  if (flagBool(args, "env")) {
+    const touched = writeEnv(ctx.root, created.key)
+    success(`Wrote ${ENV_VAR} to ${touched.join(" + ")}.`)
+  } else {
+    warn("Copy it now — it is never shown again. Lose it and you mint a new one.")
+    info(c.dim(`  Tip: \`lecodes pn keys new --env\` writes it straight into .env as ${ENV_VAR}.`))
+  }
+
+  log()
+  info(c.dim("Send from your server with:"))
+  log(c.dim(`  curl -X POST ${ctx.apiUrl}/api/projects/${ctx.uuid}/push/send \\`))
+  log(c.dim(`    -H "Authorization: Bearer $${ENV_VAR}" -H "Content-Type: application/json" \\`))
+  log(c.dim(`    -d '{"title":"Order shipped","users":["u42"]}'`))
+}
+
+/** `lecodes pn keys revoke <id>` — deletion, effective on the next request. Confirmed unless -y. */
+const pnKeysRevoke = async (ctx: Context, args: Args) => {
+  const raw = args._[2]
+  if (!raw) throw new CliError("Which key? `lecodes pn keys` lists their ids, then `lecodes pn keys revoke <id>`.")
+  const id = Number(raw)
+  if (!Number.isInteger(id)) throw new CliError(`"${raw}" is not a key id — run \`lecodes pn keys\` to see them.`)
+
+  const keys = await listPushKeys(ctx.apiUrl, ctx.token, ctx.uuid)
+  const key = keys.find(k => k.id === id)
+  if (!key) throw new CliError(`No push key with id ${id} in ${ctx.name}.`)
+
+  if (!flagBool(args, "yes", "y")) {
+    warn(`Revoking ${c.bold(key.name)} (${key.prefix}…) — any server still using it stops sending immediately.`)
+    if (!await confirm("Revoke it?")) return info("Cancelled.")
+  }
+  await revokePushKey(ctx.apiUrl, ctx.token, ctx.uuid, id)
+  success(`Revoked push key ${c.bold(key.name)}.`)
+}
+
+const pnKeys = async (args: Args) => {
+  const ctx = context()
+  const sub = args._[1]
+  if (!sub || sub === "list") return pnKeysList(ctx)
+  if (sub === "new" || sub === "create") return pnKeysNew(ctx, args)
+  if (sub === "revoke" || sub === "delete" || sub === "rm") return pnKeysRevoke(ctx, args)
+  throw new CliError(`Unknown keys command "${sub}" — use: lecodes pn keys [list | new [name] | revoke <id>]`)
+}
+
+/* --------------------------------------- entry ---------------------------------------- */
+
+const PN_HELP = `${c.bold("lecodes pn")} — push notifications for this project.
+
+${c.bold("Commands:")}
+  pn send --title <s>           Send a notification (uses your login — no key needed)
+                                  --body <s>      second line
+                                  --url <s>       deep link (also arrives as app.launchUrl)
+                                  --user <ids>    target Push.register({ user }) ids, comma-separated
+                                  --to <pa_…>     target addresses, comma-separated
+                                  --badge <n>     app icon badge
+                                  --data <json>   your JSON payload (≤ 2 KB)
+  pn devices                    List the devices that registered for this project
+                                  --user <id>     only that user's devices
+                                  --forget <pa_…> drop a dead registration (-y to skip confirm)
+  pn keys                       List this project's push keys
+  pn keys new [name]            Mint one for YOUR server (owner only; shown once)
+                                  --env           write it to .env as ${ENV_VAR} (+ gitignore)
+  pn keys revoke <id>           Revoke a key (-y to skip the confirmation)
+
+${c.dim("A push key is generated BY the server — you can't choose or recover one. It only sends")}
+${c.dim("for this project, which is why deploying it beats deploying a personal access token.")}`
+
+export const pn = async (args: Args) => {
+  const sub = args._[0]
+  if (!sub || sub === "help") return log(PN_HELP)
+  if (sub === "send") return pnSend(args)
+  if (sub === "devices" || sub === "device") return pnDevices(args)
+  if (sub === "keys" || sub === "key") return pnKeys(args)
+  throw new CliError(`Unknown pn command "${sub}" — use: lecodes pn <send | devices | keys>. Run \`lecodes pn\` for the full list.`)
+}

package/src/commands/projectTemplates.ts

@@ -0,0 +1,129 @@
+/* Templates `lecodes init` / `lecodes create` scaffold into a new APP project (the design folder
+ * has its own set — designTemplates.ts). CLAUDE.md is the AI-assistant counterpart of README.md:
+ * it teaches the headless feedback loop (render / --script / test) and the conventions that make
+ * an app testable, so an assistant opening the project drives the real app instead of guessing.
+ * Facts here mirror lecodes-renderer's scenario engine — update both when the format changes. */
+
+export const appClaudeMd = (name: string) => `# ${name} — LeCodes app
+
+Guidance for AI assistants working in this folder. Human docs: README.md. The whole SDK is
+available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) — no SDK imports. \`main.ts\` is
+the entry point; split code into other \`.ts\` files and import them (relative imports only) —
+a file no other file imports is treated as an entry candidate, so keep everything reachable
+from \`main.ts\`.
+
+## Feedback loop — run the app headless instead of guessing
+
+\`\`\`
+lecodes render                    # semantic JSON of the launched UI (structure, text, names, values)
+lecodes render --png shot.png     # pixels (needs @napi-rs/canvas installed)
+lecodes render --png card.png --clip card   # ONE component/region: a node name or x,y,w,h
+lecodes render src/screens/cart.ts   # ONE screen module, without booting the app: any file that
+                                  # \`export default\`s a UIScreen (or a (state) => UIScreen —
+                                  # --state <name> picks the branch). Same flags as above.
+lecodes render --desktop --png shot.png  # NATIVE render: real Filament 3D + UI + 2D composited —
+                                  # use this to SEE 3D scenes / procedural geometry (headless
+                                  # renders record 3D as JSON only). Windows/Linux; downloads
+                                  # the renderer on first use. --frames <n> for slow loads.
+lecodes render --script <file>    # drive the app through a scenario (format below)
+lecodes render --desktop --view iso --png iso.png   # 3D: inspection camera fitted to the WHOLE
+                                  # scene (iso|top|front|side|back [--fov N]) — or --camera x,y,z
+                                  # --look-at x,y,z; the app's camera is untouched. In scripts:
+                                  # { "view": "iso", "screenshot": "iso.png" } then { "view": "off" }
+lecodes render --desktop --script <file>  # the same scenario on the NATIVE host (3D/Jolt, real
+                                  # GPU): coordinates only ({ x, y }), expect.log checked,
+                                  # text/node/screen expects skipped; deterministic 16 ms frames
+lecodes test                      # all tests/*.flow.json + design-derived flows; run before "done"
+lecodes test --desktop            # the file flows on the NATIVE host (3D/Jolt/real GPU; coordinate
+                                  # flows only — design flows stay headless)
+\`\`\`
+
+Iterate with \`--script\` scenarios and keep the useful ones as \`tests/<name>.flow.json\` — they
+are the regression suite. A failing step dumps the failing frame (JSON + PNG) under
+\`tests/.artifacts/\` so a red step explains itself.
+
+## Scenario format (tests/*.flow.json and --script files)
+
+One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`, and for
+games: \`frames\` (advance N fixed 1/60 steps, no sleeping), \`drag\`+\`to\` [+\`ms\`], \`hold\`+\`ms\`,
+\`key\`+\`ms\` / \`keyDown\` / \`keyUp\` (KeyboardEvent.code: "ArrowRight", "KeyW", "Space" — mouse
+buttons are keys too: "MouseLeft"/"MouseRight"), \`look: [dx, dy]\` [+\`ms\`] (mouse motion for
+\`Input.mouse.delta\`), \`mouseTo: [x, y]\` (cursor position), \`wheel: [dx, dy]\`, gamepad:
+\`stick: { left: [x, y], right: [x, y], triggers: [l, r] }\` (values persist; \`index\` = pad),
+\`gamepad: "connect" | "disconnect"\`, pad buttons as keys: \`keyDown: "GamepadSouth"\`), then an
+optional \`expect\` (\`screen\`, \`node\`/\`notNode\`, \`text\`/\`notText\`,
+\`value: { target, equals }\`, \`log\` — a \`console.log\` line contains it), then outputs
+(\`screenshot\` [+\`clip\`: a node name or \`{ x, y, width, height }\`], \`json\`). Targets resolve by
+\`name\` → exact visible text → substring → input placeholder; a tap/drag on empty space reaches
+the 2D scene (sprite \`click\`/\`touchstart\`, \`ev.track()\`). Envelope keys: \`name\`,
+\`width\`/\`height\`, \`settle\`, \`fixtures\`, \`steps\`.
+
+\`\`\`json
+{ "steps": [
+  { "expect": { "screen": "home", "text": "Taps: 0" } },
+  { "tap": "tap", "expect": { "text": "Taps: 1" }, "screenshot": "after.png" },
+  { "key": "ArrowRight", "ms": 500, "expect": { "log": "hero x=" } },
+  { "frames": 60, "screenshot": "hud.png", "clip": "hud" }
+] }
+\`\`\`
+
+Game time is deterministic headless: \`setLoop\`, 2D physics/animation and aspect \`update(dt)\`
+advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` — never by a wall clock —
+so a flow that passes once passes every time. \`Input.key(code)\` reads the keys a flow holds and
+\`Input.on('keydown' | 'keyup', e => e.code)\` fires for each \`key\`/\`keyDown\`/\`keyUp\` step
+(events land before the next loop tick); \`stick\` values are what \`Input.gamepad(0).axis()\` reads.
+Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is captured as JSON and Jolt does
+not simulate — use \`--desktop\` for 3D pixels. \`console.log\` + \`expect.log\` is the assertion
+channel for game state that has no UI.
+
+## Make the app testable
+
+- Give interactive elements a \`name\`: \`UIButton(...).style({ name: "login" })\`.
+- Name every screen's ROOT node with the screen's id — \`expect.screen\` reads it.
+- If the project has a \`design/\` folder, keep the design's screen ids and activator \`name\`s
+  in the app code: \`lecodes test\` then checks the built app against the designed navigation
+  automatically (conventions in design/CLAUDE.md).
+- Backend-gated screens: canned responses in \`tests/fixtures.json\` (URL pattern →
+  \`{ status?, json?, text? }\`; \`*\` wildcards full-match, plain strings substring-match, first
+  match wins). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
+  with \`"fixtures": "fixtures.json"\` in its envelope.
+- \`fill\` fills every empty input — use it before tapping a disabled-until-filled submit.
+
+## SDK documentation
+
+\`.lecodes/types/\` is the exact API surface (signatures only; generated and gitignored — run
+\`lecodes update\` if it's missing, never commit \`.lecodes/\`). For semantics and examples,
+fetch the docs — they are served as raw markdown for AI tools:
+
+- https://le.codes/llms.txt — the docs map; fetch it first to find the right page
+- https://le.codes/en/docs/api/<area>/<page>.md — one reference page as raw markdown
+  (e.g. \`ui/styling.md\`, \`2d/scene2d.md\`, \`3d/scene.md\`, \`runtime/storage.md\`)
+- https://le.codes/en/docs/guide/<page>.md — guide pages (project anatomy, CLI, tracks)
+- https://le.codes/llms-full.txt — everything in one file (large; prefer per-page)
+
+Always fetch the \`.md\` URLs — the HTML routes are a JS app and return an empty shell.
+
+## Other commands
+
+\`lecodes dev\` (run on a device with hot reload + QR), \`lecodes compile -o app.js\`
+(single-file bundle), \`lecodes design\` (screen-design board — the living spec).
+`
+
+/** `.claude/settings.json` scaffolded next to CLAUDE.md: pre-approves doc fetches from
+ *  le.codes so the assistant can follow the "SDK documentation" pointers without a
+ *  per-domain permission prompt on first use. */
+export const CLAUDE_SETTINGS = JSON.stringify({
+  permissions: { allow: ["WebFetch(domain:le.codes)"] },
+}, null, 2) + "\n"
+
+/** A flow test that passes against init's starter counter app — proves the loop works out of the
+ *  box and gives an in-project example of the format (the button/screen carry matching names). */
+export const STARTER_FLOW = `{
+  "name": "counter",
+  "steps": [
+    { "expect": { "screen": "home", "text": "Taps: 0" } },
+    { "tap": "tap", "expect": { "text": "Taps: 1" } },
+    { "tap": "tap", "expect": { "text": "Taps: 2" } }
+  ]
+}
+`