lecodes-cli 0.19.0 → 0.20.0

package/src/commands/appDesktop.ts

@@ -0,0 +1,339 @@
+import { execFileSync, spawn } from "node:child_process"
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { buildBundle } from "./compile"
+import { resolveDesktopExe, selectedDesktopVersion } from "../desktopRenderer"
+import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+import { assertRendererSupportsBundle, desktopPluginLibraries, projectRoot, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./appShared"
+import { loadIconMaster } from "./appIcon"
+import { buildMacApp, macHostProvidedNames } from "./appDesktopMac"
+
+/*
+ * `lecodes app init|build desktop` — the desktop arm of the native-app commands
+ * (docs/desktop-target-plan.md phase 3). Unlike iOS/Android there is no user-side toolchain:
+ * `build` stages the verified cached host + the compiled bundle + its assets into one portable
+ * folder that runs on a double-click. On macOS the same command produces a signed (and, with a
+ * notarytool profile, notarized) .app instead — the staging half is shared, the bundle half lives
+ * in appDesktopMac.ts.
+ *
+ * The staged folder is SELF-DESCRIBING: a pruned app.json (name + desktop.window) ships next to
+ * app.js, and the host (≥1.3.0) reads it for title/size/min-size/resizable/fullscreen — no
+ * launcher, no envs, works the same on Windows and Linux. Field-proven ancestor: the quiz
+ * kiosk's tools/pack-desktop.mjs (its BUG-REPORT.md drove the host fixes this relies on).
+ */
+
+const mb = (bytes: number) => `${(bytes / 1024 / 1024).toFixed(1)} MB`
+
+const dirSize = (dir: string): number =>
+  readdirSync(dir, { withFileTypes: true }).reduce((sum, e) => {
+    const p = join(dir, e.name)
+    return sum + (e.isDirectory() ? dirSize(p) : statSync(p).size)
+  }, 0)
+
+/* --------------------------------------- init ---------------------------------------- */
+
+/** `lecodes app init desktop` — declare the desktop target in app.json (mirrors
+ *  `lecodes init --desktop` for existing projects). Purely additive; re-running keeps edits. */
+export const initDesktop = async (args: Args) => {
+  const root = projectRoot()
+  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const name = flagStr(args, "name") ?? existing.name ?? basename(root)
+  const window = {
+    width: 1280, height: 800, minWidth: 640, minHeight: 480,
+    ...existing.desktop?.window,
+    ...(flagBool(args, "fullscreen") ? { fullscreen: true } : {}),
+  }
+  const config: AppConfig = { ...existing, name, desktop: { ...existing.desktop, window } }
+  writeJson(join(root, "app.json"), config)
+  log(`${c.green("written")}   app.json  (desktop.window ${window.width}×${window.height}${window.fullscreen ? ", fullscreen" : ""})`)
+  log(`Next: ${c.bold("lecodes dev --desktop")} to develop, ${c.bold("lecodes app build desktop")} to package.`)
+}
+
+/* --------------------------------------- build --------------------------------------- */
+
+/** Windows/file-system-clean name; non-ASCII is fine (the host is UTF-8-clean since 1.3.0). */
+const cleanFileName = (name: string) =>
+  name.replace(/[<>:"/\\|?*\u0000-\u001f]/g, "").replace(/[. ]+$/, "").trim() || "app"
+
+/** Where a built folder keeps the two kinds of file. Both are a HOST contract (see onFetchLocal and
+ *  the runtime-assets probe in desktop/src/main.cpp) — change them on both sides or not at all. */
+const ASSETS_DIR = "assets"    // the project's own files
+const RUNTIME_DIR = "runtime"  // the host's engine files (initial.js, built-in materials, IBL)
+
+export const buildDesktop = async (args: Args) => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const name = (config.name ?? basename(root)).trim() || "app"
+  const slug = flagStr(args, "slug") ?? cleanFileName(name)
+  const out = resolve(root, flagStr(args, "o", "out") ?? join(root, "dist", slug))
+
+  // Only a previous build output (or an empty/absent dir) may be replaced — never wipe a
+  // directory this command didn't produce.
+  if (existsSync(out)) {
+    const entries = readdirSync(out)
+    const looksLikeBuild = entries.length === 0 || entries.includes("app.js") || entries.some((e) => e.endsWith(".app"))
+    if (!looksLikeBuild) {
+      throw new CliError(`${out} exists and doesn't look like a previous desktop build — pick another -o or clear it yourself.`)
+    }
+  }
+
+  // Per-target entry (app.json desktop.entry); an explicit --entry wins.
+  if (config.desktop?.entry && flagStr(args, "entry") === undefined) args.flags.entry = config.desktop.entry
+
+  // ONE renderer decision: it selects the host binary staged into the folder AND the single
+  // .filamat variant compiled beside the bundle. Two independent reads of the config is how a
+  // build ships a Vulkan exe next to an OpenGL shader (a Filament abort at the first material).
+  const renderer = resolveDesktopRenderer(root, args)
+
+  const mac = process.platform === "darwin"
+  note(`Building "${name}" for ${mac ? "macOS" : "desktop"}${renderer === "vulkan" ? " (Vulkan)" : ""}…`)
+  const { js, resources } = await buildBundle(
+    args,
+    { remotePatterns: config.resources?.remote ?? [] },
+    { localShaders: true, desktopRenderer: renderer },
+  )
+
+  // The Vulkan host has no 2D engine — refuse now rather than shipping a folder that opens a blank
+  // window (see assertRendererSupportsBundle).
+  assertRendererSupportsBundle(renderer, js)
+
+  // Only what the bundle actually references ships — the compile inventory lists EVERY project
+  // resource (design/ references included), which would multiply the build size. asset() compiles
+  // to fetchLocal("<basename>"), so the bundle itself is the reference list.
+  const wanted = new Set([...js.matchAll(/fetchLocal\("([^"]+)"\)/g)].map((m) => m[1]))
+  // Compiled shader artifacts always ship: their name is built at runtime ("<hash>_" +
+  // _creator.backend + ".filamat" — one bundle serves every native backend), so no literal for
+  // the scan above to find. They only exist here when a shader was actually compiled locally.
+  const shipped = resources.filter((r) => !r.remote && (r.shader || wanted.has(r.name)))
+
+  // Duplicate basenames alias silently in a built app (asset() collapses to fetchLocal(basename),
+  // quiz BUG-REPORT §4) — a hard error for every referenced name, not a warning.
+  const byName = new Map<string, Set<string>>()
+  for (const r of resources) {
+    if (r.remote || r.shader || !wanted.has(r.name)) continue
+    const set = byName.get(r.name) ?? new Set<string>()
+    set.add(r.path)
+    byName.set(r.name, set)
+  }
+  const collisions = [...byName.entries()].filter(([, paths]) => paths.size > 1)
+  if (collisions.length > 0) {
+    throw new CliError(
+      "Asset file names must be unique across the whole project — the bundle refers to assets " +
+      "by BASENAME, so same-named files silently replace each other in the built app:\n" +
+      collisions.map(([n, paths]) => `  ${n}\n` + [...paths].map((p) => `    ${p}`).join("\n")).join("\n"))
+  }
+  // The host: same verified cache `render --desktop` uses; LECODES_DESKTOP_EXE overrides
+  // (points builds at a locally built host).
+  const exe = await resolveDesktopExe(renderer)
+  const hostDir = dirname(exe)
+
+  // A referenced name with no local file would 404 at runtime — fail here instead. The host
+  // supplies two classes of name itself, so neither counts as missing: the files in its assets/
+  // dir (the built-in materials `Material.lit`/`unlit`/… fetch — onFetchLocal falls back there
+  // after the app.js dir), and the engine-synthesized preloads. Same split the iOS/Android
+  // shells make with sdkProvided + IMPLICIT_PRELOADS.
+  const IMPLICIT_PRELOADS = new Set(["uberarchive", "capture"])
+  const hostProvided = mac ? macHostProvidedNames(exe) : new Set<string>()
+  if (!mac) {
+    try {
+      for (const f of readdirSync(join(hostDir, "assets"))) hostProvided.add(f)
+    } catch { /* checked properly below (assets/initial.js) */ }
+  }
+  const shippedNames = new Set(shipped.map((r) => r.name))
+  const missing = [...wanted].filter((n) => !shippedNames.has(n) && !hostProvided.has(n) && !IMPLICIT_PRELOADS.has(n))
+  if (missing.length > 0) {
+    throw new CliError(`The bundle references assets with no local file: ${missing.join(", ")}`)
+  }
+
+  // macOS: one signed .app rather than a folder — see appDesktopMac.ts.
+  if (mac) return buildMacApp({ root, config, name, slug, out, js, shipped, hostExe: exe, args })
+  if (flagBool(args, "dmg")) warn("--dmg is a macOS format — ignored on this platform.")
+
+  const version = process.env.LECODES_DESKTOP_EXE ? "local build" : selectedDesktopVersion()
+
+  rmSync(out, { recursive: true, force: true })
+  mkdirSync(out, { recursive: true })
+
+  // 1) Host files — a WHITELIST (exe + runtime DLLs + its assets/fonts dirs), so a
+  //    LECODES_DESKTOP_EXE override pointing into a build tree doesn't stage the whole ninja
+  //    output, and .pdb/README never ship. The exe is renamed to the app — the host is
+  //    name-agnostic and auto-runs the app.js next to itself.
+  //
+  //    The host's own assets land in `runtime/`, NOT `assets/`: that name belongs to the project's
+  //    files (step 2), and one shared folder would let a project `logo.png` overwrite the host's
+  //    splash — or a project `initial.js` stop the app booting at all. The host (≥1.5.0) looks for
+  //    `runtime/initial.js` first and falls back to `assets/`, so a downloaded older host cache
+  //    still stages correctly.
+  for (const entry of readdirSync(hostDir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.toLowerCase().endsWith(".dll")) {
+      cpSync(join(hostDir, entry.name), join(out, entry.name))
+    } else if (entry.isDirectory() && entry.name === "assets") {
+      cpSync(join(hostDir, entry.name), join(out, RUNTIME_DIR), { recursive: true })
+    } else if (entry.isDirectory() && entry.name === "fonts") {
+      cpSync(join(hostDir, entry.name), join(out, entry.name), { recursive: true })
+    }
+  }
+  if (!existsSync(join(out, RUNTIME_DIR, "initial.js"))) {
+    throw new CliError(`The host at ${hostDir} has no assets/initial.js next to it — a staged build can't boot. ` +
+      `(LECODES_DESKTOP_EXE must point at an exe with its runtime assets/ beside it.)`)
+  }
+  const exeName = process.platform === "win32" ? `${cleanFileName(name)}.exe` : cleanFileName(name)
+  cpSync(exe, join(out, exeName))
+  note(`  host: LeCodes Desktop ${version}`)
+
+  // 2) The bundle next to the exe (the host auto-runs it), its assets in `assets/` beside it —
+  //    fetchLocal resolves by BASENAME and searches `<app>/assets/` before the flat dir, so the
+  //    shipped folder stays readable instead of scattering the whole asset library in the root.
+  writeFileSync(join(out, "app.js"), js)
+  let assetBytes = 0, assetCount = 0
+  if (shipped.length > 0) mkdirSync(join(out, ASSETS_DIR), { recursive: true })
+  for (const r of shipped) {
+    if (!r.absPath || !existsSync(r.absPath) || !statSync(r.absPath).isFile()) {
+      warn(`asset "${r.name}" (${r.path}) has no local file — skipped`)
+      continue
+    }
+    cpSync(r.absPath, join(out, ASSETS_DIR, r.name))
+    assetBytes += statSync(r.absPath).size
+    assetCount++
+  }
+  note(`  assets: ${assetCount} files, ${mb(assetBytes)} → ${ASSETS_DIR}/`)
+
+  // 3) Pruned app.json — the host (≥1.3.0) reads name + desktop.window next to app.js, so the
+  //    folder carries its own window config (title/size/min/resizable/fullscreen).
+  writeJson(join(out, "app.json"), { name, ...(config.desktop ? { desktop: { window: config.desktop.window } } : {}) })
+
+  // 4) Window/taskbar icon (host ≥1.3.0 loads app.ico next to the exe at runtime).
+  if (config.icon) {
+    await writeIco(root, config, join(out, "app.ico"))
+    note("  app.ico rendered from " + config.icon)
+  }
+
+  // 5) Native plugins (packages/desktop/plugin-sdk/lecodes_plugin.h): the project's plugins/ dir +
+  //    every declared plugin's desktop library → plugins/ next to the exe, where a host WITH the plugin
+  //    loader (added after 1.4.0) scans at startup; an older host ignores the folder.
+  //    A declared library that's missing is a build error (strict).
+  {
+    const { files } = desktopPluginLibraries(root, { strict: true })
+    if (files.length > 0) {
+      mkdirSync(join(out, "plugins"), { recursive: true })
+      for (const f of files) cpSync(f, join(out, "plugins", basename(f)))
+      note(`  plugins: ${files.map((f) => basename(f)).join(", ")} → plugins/`)
+    }
+  }
+
+  // 6) A short README (BOM so double-click-Notepad shows it right).
+  writeFileSync(join(out, "README.txt"), "\uFEFF" + readmeText(name, exeName, version))
+
+  success(`Portable build: ${out}  (${mb(dirSize(out))})`)
+
+  if (flagBool(args, "probe")) await probeBuild(out, exeName, config, args)
+  if (flagBool(args, "zip")) zipBuild(out)
+  if (!flagBool(args, "probe")) note(`Tip: --probe renders the staged folder headless to verify exactly what ships.`)
+}
+
+/** app.ico from the app.json icon master: PNG-compressed frames (fine on the Win10+ the
+ *  distribution requires) at the sizes Windows asks for — no image tooling needed. */
+const writeIco = async (root: string, config: AppConfig, dest: string) => {
+  const { image } = await loadIconMaster(root, config)
+  const sizes = [16, 24, 32, 48, 64, 256]
+  const pngs: Buffer[] = []
+  for (const s of sizes) {
+    const frame = image.clone()
+    frame.resize({ w: s, h: s })
+    pngs.push(Buffer.from(await frame.getBuffer("image/png")))
+  }
+  const header = Buffer.alloc(6 + sizes.length * 16)
+  header.writeUInt16LE(0, 0)               // reserved
+  header.writeUInt16LE(1, 2)               // type: icon
+  header.writeUInt16LE(sizes.length, 4)
+  let offset = header.length
+  sizes.forEach((s, i) => {
+    const e = 6 + i * 16
+    header.writeUInt8(s === 256 ? 0 : s, e)       // width  (0 encodes 256)
+    header.writeUInt8(s === 256 ? 0 : s, e + 1)   // height
+    header.writeUInt16LE(1, e + 4)                // color planes
+    header.writeUInt16LE(32, e + 6)               // bits per pixel
+    header.writeUInt32LE(pngs[i].length, e + 8)
+    header.writeUInt32LE(offset, e + 12)
+    offset += pngs[i].length
+  })
+  writeFileSync(dest, Buffer.concat([header, ...pngs]))
+}
+
+/** `--probe`: run the STAGED folder hidden and dump a PNG next to it — verifies exactly what
+ *  ships (the staged host, its assets, the bundle), not the dev environment. */
+const probeBuild = async (out: string, exeName: string, config: AppConfig, args: Args) => {
+  const win = config.desktop?.window
+  const frames = Number(flagStr(args, "frames")) || 90
+  const shot = join(dirname(out), `${basename(out)}-probe.png`)
+  note(`Probe: hidden render of the staged folder (${frames} frames)…`)
+  await new Promise<void>((done, fail) => {
+    const child = spawn(join(out, exeName), [], {
+      cwd: out,
+      env: {
+        ...process.env,
+        CREATOR_HIDDEN: "1",
+        CREATOR_MAX_FRAMES: String(frames),
+        CREATOR_DUMP_PNG: shot,
+        // Explicit size keeps the probe meaningful on pre-1.3.0 hosts too (no sibling-config read).
+        CREATOR_WINDOW_SIZE: `${win?.width ?? 1280}x${win?.height ?? 720}`,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+    const tail: string[] = []
+    const sink = (d: unknown) => { tail.push(String(d)); while (tail.length > 60) tail.shift() }
+    child.stdout.on("data", sink)
+    child.stderr.on("data", sink)
+    const killer = setTimeout(() => {
+      child.kill()
+      fail(new CliError("The probe timed out after 120s — raise --frames headroom or check the app."))
+    }, 120_000)
+    child.on("error", (e) => { clearTimeout(killer); fail(new CliError(`Probe couldn't run: ${e.message}`)) })
+    child.on("exit", (code) => {
+      clearTimeout(killer)
+      if (code === 0 && existsSync(shot)) { success(`Probe: ${shot}`); done() }
+      else {
+        const detail = tail.length > 0 ? `\n${tail.join("").trimEnd()}` : ""
+        fail(new CliError(`Probe failed (exit ${code}).${detail}`))
+      }
+    })
+  })
+}
+
+/** `--zip`: <out>.zip with UTF-8 names + forward-slash entries. `Compress-Archive` writes
+ *  backslash entry paths and `tar -a` OEM-encodes non-ASCII names — both corrupt on
+ *  macOS/Linux unpackers, so on Windows the entries are written by hand. */
+const zipBuild = (out: string) => {
+  const zip = `${out}.zip`
+  rmSync(zip, { force: true })
+  note("Zipping…")
+  if (process.platform === "win32") {
+    const q = (s: string) => s.replaceAll("'", "''")
+    execFileSync("powershell", ["-NoProfile", "-Command", [
+      "Add-Type -AssemblyName System.IO.Compression.FileSystem;",
+      `$src='${q(out)}'; $base=Split-Path $src -Parent;`,
+      `$zip=[System.IO.Compression.ZipFile]::Open('${q(zip)}','Create');`,
+      "Get-ChildItem $src -Recurse -File | ForEach-Object {",
+      "  $rel=$_.FullName.Substring($base.Length+1).Replace('\\','/');",
+      "  [void][System.IO.Compression.ZipFileExtensions]::CreateEntryFromFile($zip,$_.FullName,$rel,'Optimal') };",
+      "$zip.Dispose()",
+    ].join(" ")], { stdio: ["ignore", "ignore", "pipe"] })
+  } else {
+    execFileSync("zip", ["-rq", zip, basename(out)], { cwd: dirname(out) })
+  }
+  success(`Zip: ${zip} (${mb(statSync(zip).size)})`)
+}
+
+const readmeText = (name: string, exeName: string, version: string) => `${name}
+${"=".repeat(Math.max(name.length, 4))}
+
+A LeCodes desktop app. Nothing to install: unpack the WHOLE folder anywhere and run ${exeName}.
+Keep the files together: assets/ holds the app's own content, runtime/ the engine it needs.
+
+On first run Windows may show a SmartScreen prompt (any unsigned app gets one):
+choose "More info", then "Run anyway".
+
+Requires 64-bit Windows 10/11.
+
+Built with LeCodes Desktop ${version}.
+`