lecodes-cli 0.20.2 → 2.0.0

package/src/commands/{appDesktop.ts → app/desktop.ts}

@@ -1,12 +1,13 @@
 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"
+import { buildBundle } from "../compile"
+import { resolveDesktopExe, selectedDesktopVersion } from "../../hosts/desktopRenderer"
+import { CliError, bool, c, defineCommand, log, note, num, str, success, warn, type FlagValues } from "../../cli"
+import { bundleFlags, bundleOptions } from "../shared"
+import { desktopPluginLibraries, projectRoot, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./shared"
+import { loadIconMaster } from "./icon"
+import { buildMacApp, macHostProvidedNames } from "./desktopMac"
 
 /*
  * `lecodes app init|build desktop` — the desktop arm of the native-app commands
@@ -14,7 +15,8 @@ import { buildMacApp, macHostProvidedNames } from "./appDesktopMac"
  * `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.
+ * in desktopMac.ts. The `build` node is defined here and mounted twice: `lecodes desktop build`
+ * (desktop.ts) and `lecodes app build desktop` (index.ts) are the same command.
  *
  * 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
@@ -32,16 +34,19 @@ const dirSize = (dir: string): number =>
 
 /* --------------------------------------- init ---------------------------------------- */
 
+/** The `app init desktop` flags (index.ts declares the shared init node). */
+export interface DesktopInitOptions { name?: string, fullscreen?: boolean }
+
 /** `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) => {
+export const initDesktop = async (opts: DesktopInitOptions): Promise<void> => {
   const root = projectRoot()
   const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
-  const name = flagStr(args, "name") ?? existing.name ?? basename(root)
+  const name = opts.name ?? existing.name ?? basename(root)
   const window = {
     width: 1280, height: 800, minWidth: 640, minHeight: 480,
     ...existing.desktop?.window,
-    ...(flagBool(args, "fullscreen") ? { fullscreen: true } : {}),
+    ...(opts.fullscreen ? { fullscreen: true } : {}),
   }
   const config: AppConfig = { ...existing, name, desktop: { ...existing.desktop, window } }
   writeJson(join(root, "app.json"), config)
@@ -60,12 +65,27 @@ const cleanFileName = (name: string) =>
 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 desktopBuildFlags = {
+  out: str("output folder (default dist/<name>)", { alias: "o", value: "<dir>" }),
+  slug: str("folder / zip name override (Latin-only)", { value: "<name>" }),
+  renderer: str("host + shader variant: gl | vulkan (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+  probe: bool("headless-render the staged folder to a PNG next to it (macOS: a brief windowed run + snapshot)"),
+  frames: num("(--probe) frames to render before the snapshot", { default: 90 }),
+  after: num("(--probe, macOS) seconds the app runs before the snapshot", { default: 8 }),
+  zip: bool("also pack the result for sending: <out>.zip with UTF-8 / forward-slash entries (macOS: a ditto archive of the .app)"),
+  dmg: bool("macOS: also build a drag-to-Applications disk image (signed + notarized too)"),
+  sign: str("macOS codesign identity — a \"Developer ID Application: …\" cert, or adhoc (local only)", { value: "<identity|adhoc>" }),
+  notarize: str("macOS: notarize + staple with this `xcrun notarytool store-credentials` keychain profile", { value: "<profile>" }),
+  "no-notarize": bool("macOS: skip notarization even when app.json / the environment names a profile"),
+  ...bundleFlags,
+}
+
+const buildDesktop = async (flags: FlagValues<typeof desktopBuildFlags>): Promise<void> => {
   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))
+  const slug = flags.slug ?? cleanFileName(name)
+  const out = resolve(root, flags.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.
@@ -78,24 +98,21 @@ export const buildDesktop = async (args: Args) => {
   }
 
   // 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
+  const bundle = bundleOptions(flags)
+  if (config.desktop?.entry && bundle.entry === undefined) bundle.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 renderer = resolveDesktopRenderer(root, flags.renderer)
 
   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)
+  const { js, resources } = await buildBundle(bundle, {
+    shell: { remotePatterns: config.resources?.remote ?? [] },
+    localShaders: true,
+    desktopRenderer: renderer,
+  })
 
   // 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
@@ -145,9 +162,14 @@ export const buildDesktop = async (args: Args) => {
     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.")
+  // macOS: one signed .app rather than a folder — see desktopMac.ts.
+  if (mac) {
+    return buildMacApp({
+      root, config, name, slug, out, js, shipped, hostExe: exe,
+      opts: { sign: flags.sign, notarize: flags.notarize, noNotarize: flags["no-notarize"], dmg: flags.dmg, zip: flags.zip, probe: flags.probe, after: flags.after },
+    })
+  }
+  if (flags.dmg) warn("--dmg is a macOS format — ignored on this platform.")
 
   const version = process.env.LECODES_DESKTOP_EXE ? "local build" : selectedDesktopVersion()
 
@@ -218,7 +240,7 @@ export const buildDesktop = async (args: Args) => {
     note("  app.ico rendered from " + config.icon)
   }
 
-  // 5) Native plugins (packages/desktop/plugin-sdk/lecodes_plugin.h): the project's plugins/ dir +
+  // 5) Native plugins (hosts/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).
@@ -236,11 +258,21 @@ export const buildDesktop = async (args: Args) => {
 
   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.`)
+  if (flags.probe) await probeBuild(out, exeName, config, flags.frames)
+  if (flags.zip) zipBuild(out)
+  if (!flags.probe) note(`Tip: --probe renders the staged folder headless to verify exactly what ships.`)
 }
 
+/** `lecodes desktop build` and `lecodes app build desktop` — the one node, mounted in both trees. */
+export const desktopBuild = defineCommand({
+  name: "build",
+  summary: "Stage a portable desktop app folder (dist/<name>/): host exe + app.js + assets + runtime",
+  description: "The cached host renamed to <Name>.exe + app.js + assets/ (the project's files) + runtime/ (the engine's) + app.json (the host reads title/size/fullscreen from it) + app.ico from app.json \"icon\". Duplicate asset basenames are a build error (they silently alias in the bundle). Also spelled `lecodes app build desktop`.\n\nOn macOS: a signed .app instead (the downloaded LeCodes Desktop.app + the project inside it); app.json desktop.macos = bundleId / buildNumber / category / signing.identity / notarize.profile (a notarytool keychain profile — notarized + stapled, so it opens on any Mac without \"Open Anyway\"). --sign / --notarize / --no-notarize override it per build; LECODES_MACOS_SIGN_ID / LECODES_NOTARY_PROFILE sit between the flags and app.json.",
+  flags: desktopBuildFlags,
+  examples: ["lecodes desktop build", "lecodes app build desktop --zip --probe", "lecodes desktop build -o out/kiosk --renderer vulkan", "lecodes app build desktop --dmg --notarize MyProfile"],
+  run: ({ flags }) => buildDesktop(flags),
+})
+
 /** 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) => {
@@ -272,9 +304,8 @@ const writeIco = async (root: string, config: AppConfig, dest: string) => {
 
 /** `--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 probeBuild = async (out: string, exeName: string, config: AppConfig, frames: number) => {
   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) => {

package/src/commands/{appDesktopMac.ts → app/desktopMac.ts}

@@ -2,12 +2,12 @@ import { execFileSync, spawn, spawnSync } from "node:child_process"
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { basename, join, resolve } from "node:path"
-import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
-import { writeJson, type AppConfig, type MacDesktopConfig } from "./appShared"
-import { loadIconMaster } from "./appIcon"
+import { CliError, c, log, note, success, warn } from "../../cli"
+import { writeJson, type AppConfig, type MacDesktopConfig } from "./shared"
+import { loadIconMaster } from "./icon"
 
 /*
- * `lecodes app build desktop` on macOS — the .app arm of appDesktop.ts.
+ * `lecodes app build desktop` on macOS — the .app arm of desktop.ts.
  *
  * Windows/Linux stage a portable FOLDER (exe + app.js + assets/ + runtime/). macOS has no such
  * thing: Gatekeeper judges one signed bundle as a whole, and a Finder launch runs with cwd "/", so
@@ -53,14 +53,14 @@ const cleanBundleName = (name: string) => name.replace(/[/:]/g, "").trim() || "A
 
 /* ------------------------------------- host bundle ------------------------------------- */
 
-/** The .app that owns a host executable (…/X.app/Contents/MacOS/lecodes-app → …/X.app). */
+/** The .app that owns a host executable (…/X.app/Contents/MacOS/lecodes-desktop → …/X.app). */
 export const macHostAppOf = (exe: string): string => {
   const app = resolve(exe, "..", "..", "..")
   if (!app.endsWith(".app") || !existsSync(join(app, "Contents", "Info.plist"))) {
     throw new CliError(
       `The macOS host must be an .app bundle (got ${exe}). Install LeCodes Desktop.app, or point ` +
-      `LECODES_DESKTOP_EXE at <Build>.app/Contents/MacOS/lecodes-app — a bare SwiftPM binary has no ` +
-      `resource bundles and can't be re-signed into an app.`,
+      `LECODES_DESKTOP_EXE at <Build>.app/Contents/MacOS/lecodes-desktop — a bare build-tree binary has no ` +
+      `Resources/runtime and can't be re-signed into an app (hosts/desktop/package-macos.sh makes the bundle).`,
     )
   }
   return app
@@ -120,7 +120,7 @@ export const assertMacHostCanBundle = (exe: string) => {
     `This LeCodes Desktop host (${macHostAppOf(exe)}) predates project bundles — an app built from it would ` +
     "open the host's home screen instead of the project.\n" +
     "  Run `lecodes desktop update` (needs a published macOS host with project-bundle support), or point " +
-    "LECODES_DESKTOP_EXE at a current build (…/LeCodes Desktop.app/Contents/MacOS/lecodes-app).",
+    "LECODES_DESKTOP_EXE at a current build (…/LeCodes Desktop.app/Contents/MacOS/lecodes-desktop).",
   )
 }
 
@@ -318,17 +318,17 @@ const writeIcns = async (root: string, config: AppConfig, dest: string, tmp: str
 
 /* ---------------------------------------- probe ---------------------------------------- */
 
-/** `--probe`: launch the built app for a few seconds and grab the presented 3D frame through the
- *  host's LECODES_SNAPSHOT hook. The window shows briefly — the macOS host has no hidden mode. */
-const probeMacApp = async (app: string, out: string, args: Args) => {
-  const after = Number(flagStr(args, "after")) || 8
+/** `--probe`: launch the built app for a few seconds and grab its last frame through the host's
+ *  headless render contract (CREATOR_MAX_FRAMES + CREATOR_DUMP_PNG, the same as render --desktop).
+ *  The window shows: the probe proves the SHIPPED bundle launches from cwd "/", not the hidden path. */
+const probeMacApp = async (app: string, out: string, after: number) => {
   const shot = join(out, `${basename(app, ".app")}-probe.png`)
   rmSync(shot, { force: true })
-  note(`Probe: launching the built app for ${after + 2}s (the window will show)…`)
+  note(`Probe: launching the built app for ~${after + 2}s (the window will show)…`)
   await new Promise<void>((done, fail) => {
-    const child = spawn(join(app, "Contents", "MacOS", "lecodes-app"), [], {
+    const child = spawn(join(app, "Contents", "MacOS", "lecodes-desktop"), [], {
       cwd: "/",   // what Finder gives a double-clicked app — proves nothing leans on the cwd
-      env: { ...process.env, LECODES_SNAPSHOT: shot, LECODES_SNAPSHOT_AFTER: String(after), LECODES_EXIT_AFTER: String(after + 2) },
+      env: { ...process.env, CREATOR_DUMP_PNG: shot, CREATOR_MAX_FRAMES: String((after + 2) * 60) },
       stdio: ["ignore", "pipe", "pipe"],
     })
     const tail: string[] = []
@@ -348,6 +348,18 @@ const probeMacApp = async (app: string, out: string, args: Args) => {
 
 /* ---------------------------------------- build ---------------------------------------- */
 
+/** The macOS-relevant `desktop build` flags (desktop.ts declares them; this is the typed subset). */
+export interface MacBuildOptions {
+  sign?: string
+  notarize?: string
+  noNotarize: boolean
+  dmg: boolean
+  zip: boolean
+  probe: boolean
+  /** `--probe`: seconds the app runs before the snapshot. */
+  after: number
+}
+
 export interface MacBuildInput {
   root: string
   config: AppConfig
@@ -357,11 +369,11 @@ export interface MacBuildInput {
   js: string
   shipped: { name: string, path: string, absPath?: string }[]
   hostExe: string
-  args: Args
+  opts: MacBuildOptions
 }
 
 export const buildMacApp = async (input: MacBuildInput) => {
-  const { root, config, name, slug, out, js, shipped, hostExe, args } = input
+  const { root, config, name, slug, out, js, shipped, hostExe, opts } = input
   const hostApp = macHostAppOf(hostExe)
   assertMacHostCanBundle(hostExe)
   const mac = config.desktop?.macos ?? {}
@@ -416,12 +428,7 @@ export const buildMacApp = async (input: MacBuildInput) => {
     note(`  bundle: ${bundleId} ${config.version ?? "1.0"} (${mac.buildNumber ?? 1})`)
 
     // 4) Sign the whole bundle (the project files are now sealed too), then notarize + staple.
-    const signing = resolveMacSigning(mac, {
-      sign: flagStr(args, "sign"),
-      notarize: flagStr(args, "notarize"),
-      noNotarize: flagBool(args, "no-notarize"),
-      env: process.env,
-    }, developerIdInKeychain)
+    const signing = resolveMacSigning(mac, { sign: opts.sign, notarize: opts.notarize, noNotarize: opts.noNotarize, env: process.env }, developerIdInKeychain)
     await signApp(app, signing, hostApp, tmp)
     if (signing.notaryProfile) {
       notarize(app, signing.notaryProfile, tmp, "app")
@@ -439,16 +446,16 @@ export const buildMacApp = async (input: MacBuildInput) => {
     success(`App: ${app}  (${mb(dirSize(app))})`)
 
     // The DMG goes before --probe/--zip so a failure there costs nothing already earned.
-    if (flagBool(args, "dmg")) await buildDmg(app, out, appName, signing, tmp)
-    if (flagBool(args, "probe")) await probeMacApp(app, out, args)
-    if (flagBool(args, "zip")) {
+    if (opts.dmg) await buildDmg(app, out, appName, signing, tmp)
+    if (opts.probe) await probeMacApp(app, out, opts.after)
+    if (opts.zip) {
       // ditto, not zip(1): it keeps the bundle's structure/xattrs (the stapled ticket rides in
       // Contents/CodeResources) exactly as Finder's "Compress" would.
       const zip = join(out, `${appName}.zip`)
       rmSync(zip, { force: true })
       execFileSync("ditto", ["-c", "-k", "--keepParent", app, zip])
       success(`Zip: ${zip} (${mb(statSync(zip).size)})`)
-    } else if (!flagBool(args, "dmg")) {
+    } else if (!opts.dmg) {
       note("Tip: --zip packs the .app for sending; --dmg wraps it in a drag-to-Applications image.")
     }
   } finally {

package/src/commands/{appIcon.ts → app/icon.ts}

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import type { JimpInstance } from "jimp"
-import { CliError, c, log, warn } from "../util"
-import type { AppConfig } from "./appShared"
+import { Color } from "lecodes-sdk/color"
+import { CliError, c, log, warn } from "../../cli"
+import type { AppConfig } from "./shared"
 
 /* App icons rendered from the one master image app.json "icon" names (a square ≥1024px
  * PNG/JPEG, project-root-relative). Strictly additive: without the key, sync never touches an
@@ -36,12 +37,14 @@ export const loadIconMaster = async (root: string, config: AppConfig): Promise<I
   const path = resolve(root, rel)
   if (!existsSync(path)) throw new CliError(`app.json "icon": ${rel} not found`)
 
-  const raw = (config.iconBackground ?? "#FFFFFF").trim()
-  const expanded = /^#[0-9a-fA-F]{3}$/.test(raw) ? "#" + [...raw.slice(1)].map(ch => ch + ch).join("") : raw
-  const m = /^#([0-9a-fA-F]{6})$/.exec(expanded)
-  if (!m) throw new CliError(`app.json "iconBackground" must be #RGB or #RRGGBB (got "${config.iconBackground}")`)
-  const backgroundHex = "#" + m[1].toUpperCase()
-  const background = (parseInt(m[1], 16) * 0x100 + 0xff) >>> 0
+  // Any CSS color, opaque (an icon backdrop has no alpha): the SDK's one parser.
+  const rgba = Color.tryParse(config.iconBackground ?? "#FFFFFF")
+  if (!rgba || (Color.toPackedRgba(rgba) & 0xff) !== 0xff) {
+    throw new CliError(`app.json "iconBackground" must be an opaque CSS color — #RRGGBB, a name, rgb() / hsl() (got ${JSON.stringify(config.iconBackground)})`)
+  }
+  const rgb = Color.toPackedRgb(rgba)
+  const backgroundHex = "#" + rgb.toString(16).padStart(6, "0").toUpperCase()
+  const background = (rgb * 0x100 + 0xff) >>> 0
 
   const { Jimp } = await import("jimp")
   let image: JimpInstance