lecodes-cli 0.20.1 → 1.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()
 
@@ -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
@@ -320,8 +320,7 @@ const writeIcns = async (root: string, config: AppConfig, dest: string, tmp: str
 
 /** `--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
+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)…`)
@@ -348,6 +347,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 +368,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 +427,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 +445,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,8 @@
 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 { 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