lecodes-cli 0.19.0 → 0.19.2

package/src/commands/appDesktopMac.ts

@@ -0,0 +1,470 @@
+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"
+
+/*
+ * `lecodes app build desktop` on macOS — the .app arm of appDesktop.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
+ * everything the app needs must live INSIDE the .app and be sealed by its signature. The host is
+ * the installed LeCodes Desktop.app (resolveDesktopExe finds it; LECODES_DESKTOP_EXE points at a
+ * dev build): it is copied, the project staged into Contents/Resources/project/ (app.js + app.json
+ * + assets/ — the host looks there first, see ProjectLaunch in the macOS host), Info.plist is
+ * rewritten for the app's own identity, then the bundle is re-signed as a whole and, given a
+ * notarytool profile, notarized + stapled.
+ *
+ * Why notarize at all: since macOS 10.15 a downloaded app (quarantine xattr — AirDrop, browsers and
+ * messengers all set it) that is Developer-ID-signed but NOT notarized is refused outright; the only
+ * way past is System Settings › Privacy & Security › "Open Anyway", which is exactly the prompt a
+ * distributed app must not have. Ad-hoc signatures are the same story. Notarized + stapled, it
+ * opens on any Mac (offline included) after the ordinary "downloaded from the internet" confirm.
+ *
+ * Config — app.json `desktop.macos`, every key optional — and what overrides it:
+ *   bundleId          CFBundleIdentifier (default codes.le.app.<slug>)
+ *   buildNumber       CFBundleVersion (default 1); the top-level `version` is CFBundleShortVersionString
+ *   category          LSApplicationCategoryType, e.g. "public.app-category.games"
+ *   signing.identity  codesign identity — a "Developer ID Application: …" cert, or "adhoc"
+ *                     (local only). Default: the keychain's Developer ID cert, else ad-hoc.
+ *                     --sign <identity|adhoc> / LECODES_MACOS_SIGN_ID win.
+ *   notarize.profile  a `xcrun notarytool store-credentials <name>` keychain profile.
+ *                     --notarize <name> / LECODES_NOTARY_PROFILE win; --no-notarize skips.
+ * Packaging flags: --zip (ditto archive) and --dmg (drag-to-Applications image); both may be given.
+ * Each is signed and notarized in its own right when a profile is set, so every artifact carries a
+ * ticket — that is two Apple round-trips for --dmg, which is why it is opt-in.
+ * Secrets never enter app.json: the profile NAME is config, the app-specific password lives in
+ * the keychain (the same split as android.signing vs keystore.properties).
+ */
+
+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) : e.isSymbolicLink() ? 0 : statSync(p).size)
+  }, 0)
+
+/** Bundle name: Finder shows it, so keep the display name — only path separators can't be in it. */
+const cleanBundleName = (name: string) => name.replace(/[/:]/g, "").trim() || "App"
+
+/* ------------------------------------- host bundle ------------------------------------- */
+
+/** The .app that owns a host executable (…/X.app/Contents/MacOS/lecodes-app → …/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.`,
+    )
+  }
+  return app
+}
+
+/** Every file name the host bundle itself can serve to fetchLocal (its SwiftPM resource
+ *  bundles: materials, IBL, initial.js …) — the macOS twin of the Windows host's assets/ dir. */
+export const macHostProvidedNames = (exe: string): Set<string> => {
+  const names = new Set<string>()
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) walk(join(dir, e.name))
+      else names.add(e.name)
+    }
+  }
+  const res = join(macHostAppOf(exe), "Contents", "Resources")
+  if (existsSync(res)) walk(res)
+  return names
+}
+
+const plistRead = (plist: string, key: string): string | null => {
+  const r = spawnSync("/usr/libexec/PlistBuddy", ["-c", `Print :${key}`, plist], { encoding: "utf8" })
+  return r.status === 0 ? r.stdout.trim() : null
+}
+
+/** Set-or-add a string key. PlistBuddy takes the value as the rest of its command line, so it is
+ *  double-quoted (with the two characters that matter inside quotes escaped). */
+const plistSet = (plist: string, key: string, value: string) => {
+  const quoted = `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`
+  const set = spawnSync("/usr/libexec/PlistBuddy", ["-c", `Set :${key} ${quoted}`, plist], { stdio: "ignore" })
+  if (set.status !== 0) execFileSync("/usr/libexec/PlistBuddy", ["-c", `Add :${key} string ${quoted}`, plist], { stdio: "ignore" })
+}
+
+/** The host's ENGINE version, for the build note and `lecodes desktop`. `LeCodesHostVersion` is
+ *  the stamped one (build-app.sh); CFBundleShortVersionString is the fallback for hosts built
+ *  before that key existed — and never the right field once a bundle has been rewritten for a
+ *  project, since that one then carries the project's version. */
+export const macHostVersion = (exe: string): string => {
+  const plist = join(macHostAppOf(exe), "Contents", "Info.plist")
+  return plistRead(plist, "LeCodesHostVersion") ?? plistRead(plist, "CFBundleShortVersionString") ?? "unknown"
+}
+
+/** What the host can do, from the `LeCodesHostFeatures` array its build script stamps into
+ *  Info.plist. A FEATURE list, not a version check: the macOS host's own version string has not
+ *  tracked the release line (the published 1.3.2 DMG reports 1.0.0), so a number proves nothing. */
+export const macHostFeatures = (exe: string): Set<string> => {
+  const raw = plistRead(join(macHostAppOf(exe), "Contents", "Info.plist"), "LeCodesHostFeatures") ?? ""
+  // PlistBuddy prints an array as "Array {\n    item\n    item\n}".
+  return new Set(raw.split("\n").map((l) => l.trim()).filter((l) => l && l !== "Array {" && l !== "}"))
+}
+
+/** The host must know to look in Contents/Resources/project/ — an older one boots to its own home
+ *  screen, and the built app would ship exactly that. */
+export const assertMacHostCanBundle = (exe: string) => {
+  if (macHostFeatures(exe).has("project-bundle")) return
+  throw new CliError(
+    `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).",
+  )
+}
+
+/* --------------------------------------- signing --------------------------------------- */
+
+export interface MacSigning {
+  /** A codesign identity, or "-" for ad-hoc. */
+  identity: string
+  /** notarytool keychain profile, or null = don't notarize. */
+  notaryProfile: string | null
+}
+
+/** "Developer ID Application: …" from the login keychain, if there is one. */
+export const developerIdInKeychain = (): string | null => {
+  const r = spawnSync("security", ["find-identity", "-v", "-p", "codesigning"], { encoding: "utf8" })
+  if (r.status !== 0) return null
+  return /"(Developer ID Application: [^"]+)"/.exec(r.stdout)?.[1] ?? null
+}
+
+/** Precedence: flag > env > app.json > keychain auto-detect > ad-hoc. Pure, so it's testable —
+ *  the keychain lookup is injected. */
+export const resolveMacSigning = (
+  cfg: MacDesktopConfig | undefined,
+  overrides: { sign?: string, notarize?: string, noNotarize?: boolean, env: NodeJS.ProcessEnv },
+  keychainDeveloperId: () => string | null,
+): MacSigning => {
+  let identity = overrides.sign ?? overrides.env.LECODES_MACOS_SIGN_ID ?? cfg?.signing?.identity
+  if (identity === undefined || identity === "" || identity === "auto") identity = keychainDeveloperId() ?? "-"
+  if (identity === "adhoc" || identity === "ad-hoc") identity = "-"
+  const notaryProfile = overrides.noNotarize
+    ? null
+    : overrides.notarize ?? overrides.env.LECODES_NOTARY_PROFILE ?? cfg?.notarize?.profile ?? null
+  if (notaryProfile && identity === "-") {
+    throw new CliError(
+      "Notarization needs a Developer ID signature — an ad-hoc-signed app can't be notarized.\n" +
+      "  Set desktop.macos.signing.identity (or --sign) to a \"Developer ID Application: …\" certificate, " +
+      "or drop the notarize profile (--no-notarize).",
+    )
+  }
+  return { identity, notaryProfile: notaryProfile || null }
+}
+
+/** Hardened-Runtime entitlements for the signature: the host's own (a signed LeCodes Desktop.app
+ *  carries them), else the one the JS engine needs — JavaScriptCore's JIT must be allowed under
+ *  Hardened Runtime or the app dies at boot. */
+const FALLBACK_ENTITLEMENTS = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.cs.allow-jit</key>
+  <true/>
+</dict>
+</plist>
+`
+
+const entitlementsFor = (hostApp: string): string => {
+  const r = spawnSync("codesign", ["-d", "--entitlements", "-", "--xml", hostApp], { encoding: "utf8" })
+  const xml = r.status === 0 ? r.stdout.trim() : ""
+  if (xml.startsWith("<?xml") && xml.includes("com.apple.security.cs.allow-jit")) return xml + "\n"
+  return FALLBACK_ENTITLEMENTS
+}
+
+/** codesign with a retry on Apple's timestamp service: a release signs several times in a row and
+ *  timestamp.apple.com throttles bursts ("The timestamp service is not available"). A secure
+ *  timestamp is REQUIRED for notarization, so dropping --timestamp is never the fix — waiting is.
+ *  Any other failure (bad identity, malformed bundle) is immediate. */
+const codesignRetrying = async (args: string[]) => {
+  for (let attempt = 1; ; attempt++) {
+    const r = spawnSync("codesign", args, { encoding: "utf8" })
+    if (r.status === 0) return
+    const out = (r.stdout + "\n" + r.stderr).trim()
+    if (!/timestamp/i.test(out) || attempt >= 5) throw new CliError(`codesign failed:\n${out}`)
+    const delay = attempt * 15
+    warn(`timestamp service unavailable (attempt ${attempt}/5) — retrying in ${delay}s…`)
+    await new Promise((r) => setTimeout(r, delay * 1000))
+  }
+}
+
+const signApp = async (app: string, signing: MacSigning, hostApp: string, tmp: string) => {
+  if (signing.identity === "-") {
+    note("Signing ad-hoc (runs on this Mac only — pass a Developer ID identity to distribute)…")
+    await codesignRetrying(["--force", "--sign", "-", app])
+    return
+  }
+  note(`Signing with "${signing.identity}" (Hardened Runtime + JIT entitlement)…`)
+  const ent = join(tmp, "entitlements.plist")
+  writeFileSync(ent, entitlementsFor(hostApp))
+  await codesignRetrying(["--force", "--options", "runtime", "--timestamp", "--entitlements", ent, "--sign", signing.identity, app])
+  const verify = spawnSync("codesign", ["--verify", "--strict", "--verbose=2", app], { encoding: "utf8" })
+  if (verify.status !== 0) throw new CliError(`The signature doesn't verify:\n${(verify.stdout + verify.stderr).trim()}`)
+}
+
+/* -------------------------------------- notarization -------------------------------------- */
+
+const notarize = (target: string, profile: string, tmp: string, what: string) => {
+  // notarytool takes a FLAT file: a .app is zipped first, a .dmg goes as it is.
+  const submission = target.endsWith(".app") ? join(tmp, `${basename(target, ".app")}.zip`) : target
+  if (submission !== target) execFileSync("ditto", ["-c", "-k", "--keepParent", target, submission])
+  note(`Notarizing the ${what} with profile "${profile}" — this waits on Apple (usually 1–5 minutes)…`)
+  const r = spawnSync("xcrun", ["notarytool", "submit", submission, "--keychain-profile", profile, "--wait"], { encoding: "utf8" })
+  const out = (r.stdout + "\n" + r.stderr).trim()
+  const id = /id: ([0-9a-f-]{36})/.exec(out)?.[1]
+  if (r.status !== 0 || !/status: Accepted/.test(out)) {
+    throw new CliError(
+      `Notarization failed:\n${out}\n` +
+      (id ? `  Details: xcrun notarytool log ${id} --keychain-profile ${profile}` : ""),
+    )
+  }
+  // The ticket is what makes it open OFFLINE; without it Gatekeeper has to reach Apple.
+  const staple = spawnSync("xcrun", ["stapler", "staple", target], { encoding: "utf8" })
+  if (staple.status !== 0) throw new CliError(`Stapling failed:\n${(staple.stdout + staple.stderr).trim()}`)
+  success(`Notarized + stapled (${what}).`)
+}
+
+/** `--dmg`: the signed app inside a drag-to-Applications disk image.
+ *
+ *  Worth having even though a notarized .zip passes Gatekeeper identically (verified): a DMG is
+ *  MOUNTED rather than unpacked, so "the recipient extracted it with something that mangled the
+ *  bundle", "the archive only half-extracted" and "it was launched from inside the unarchiver's
+ *  temp dir" all stop being possible. The /Applications alias also nudges people to move it there
+ *  instead of running it from Downloads, which is where App Translocation applies.
+ *
+ *  The image is signed and notarized in its OWN right, so its ticket travels with the download;
+ *  the app inside is already stapled, so it still opens offline once dragged out. */
+const buildDmg = async (app: string, out: string, appName: string, signing: MacSigning, tmp: string) => {
+  const dmg = join(out, `${appName}.dmg`)
+  rmSync(dmg, { force: true })
+  const stage = join(tmp, "dmg")
+  rmSync(stage, { recursive: true, force: true })
+  mkdirSync(stage, { recursive: true })
+  note("Building the disk image…")
+  // cp -R, not cpSync: the bundle's signature seals file modes and the resource fork layout, and
+  // Node's copy has been known to normalise both.
+  execFileSync("cp", ["-R", app, join(stage, basename(app))])
+  symlinkSync("/Applications", join(stage, "Applications"))
+  const r = spawnSync("hdiutil", [
+    "create", "-volname", appName, "-srcfolder", stage, "-fs", "HFS+", "-format", "UDZO", "-ov", dmg,
+  ], { encoding: "utf8" })
+  rmSync(stage, { recursive: true, force: true })
+  if (r.status !== 0) throw new CliError(`hdiutil failed:\n${(r.stdout + r.stderr).trim()}`)
+
+  if (signing.identity !== "-") {
+    await codesignRetrying(["--force", "--timestamp", "--sign", signing.identity, dmg])
+    if (signing.notaryProfile) notarize(dmg, signing.notaryProfile, tmp, "disk image")
+  }
+  success(`DMG: ${dmg} (${mb(statSync(dmg).size)})`)
+}
+
+/** Gatekeeper's own verdict on the bundle — the thing the recipient's Mac will decide. */
+const gatekeeperVerdict = (app: string): { accepted: boolean, line: string } => {
+  const r = spawnSync("spctl", ["-a", "-t", "exec", "-vv", app], { encoding: "utf8" })
+  const line = (r.stdout + r.stderr).trim().split("\n").filter((l) => l.includes("source=") || l.includes("rejected") || l.includes("accepted")).join("; ")
+  return { accepted: r.status === 0, line: line || (r.stdout + r.stderr).trim() }
+}
+
+/* ----------------------------------------- icon ----------------------------------------- */
+
+/** AppIcon.icns from the app.json icon master. macOS icons are NOT full-bleed: the system draws
+ *  them on a ~80% rounded square inside the 1024 canvas (Big Sur+ grid), so the flattened master
+ *  is inset and corner-rounded before iconutil packs the size ladder. */
+const writeIcns = async (root: string, config: AppConfig, dest: string, tmp: string) => {
+  const master = await loadIconMaster(root, config)
+  const { Jimp } = await import("jimp")
+  const SIZE = 1024, INSET = 100, RADIUS = 185          // Apple's icon grid: 824px tile, r≈22.5%
+  const tileSize = SIZE - 2 * INSET
+  const tile = new Jimp({ width: tileSize, height: tileSize, color: master.background })
+  const art = master.image.clone()
+  art.resize({ w: tileSize, h: tileSize })
+  tile.composite(art, 0, 0)
+  // Rounded corners: zero the alpha outside the corner circles.
+  const { data } = tile.bitmap
+  for (let y = 0; y < tileSize; y++) {
+    for (let x = 0; x < tileSize; x++) {
+      const cx = x < RADIUS ? RADIUS : x >= tileSize - RADIUS ? tileSize - RADIUS - 1 : x
+      const cy = y < RADIUS ? RADIUS : y >= tileSize - RADIUS ? tileSize - RADIUS - 1 : y
+      const dx = x - cx, dy = y - cy
+      if (dx * dx + dy * dy > RADIUS * RADIUS) data[(y * tileSize + x) * 4 + 3] = 0
+    }
+  }
+  const canvas = new Jimp({ width: SIZE, height: SIZE, color: 0x00000000 })
+  canvas.composite(tile, INSET, INSET)
+
+  const iconset = join(tmp, "AppIcon.iconset")
+  mkdirSync(iconset, { recursive: true })
+  for (const pt of [16, 32, 128, 256, 512]) {
+    for (const scale of [1, 2]) {
+      const px = pt * scale
+      const frame = canvas.clone()
+      frame.resize({ w: px, h: px })
+      writeFileSync(join(iconset, `icon_${pt}x${pt}${scale === 2 ? "@2x" : ""}.png`), await frame.getBuffer("image/png"))
+    }
+  }
+  execFileSync("iconutil", ["-c", "icns", "-o", dest, iconset])
+}
+
+/* ---------------------------------------- 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
+  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)…`)
+  await new Promise<void>((done, fail) => {
+    const child = spawn(join(app, "Contents", "MacOS", "lecodes-app"), [], {
+      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) },
+      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.")) }, 120_000)
+    child.on("error", (e) => { clearTimeout(killer); fail(new CliError(`Probe couldn't run: ${e.message}`)) })
+    child.on("exit", (code) => {
+      clearTimeout(killer)
+      const detail = tail.length > 0 ? `\n${tail.join("").trimEnd()}` : ""
+      if (code === 0 && existsSync(shot)) { success(`Probe: ${shot}`); done() }
+      else fail(new CliError(`Probe failed (exit ${code}).${detail}`))
+    })
+  })
+}
+
+/* ---------------------------------------- build ---------------------------------------- */
+
+export interface MacBuildInput {
+  root: string
+  config: AppConfig
+  name: string
+  slug: string
+  out: string
+  js: string
+  shipped: { name: string, path: string, absPath?: string }[]
+  hostExe: string
+  args: Args
+}
+
+export const buildMacApp = async (input: MacBuildInput) => {
+  const { root, config, name, slug, out, js, shipped, hostExe, args } = input
+  const hostApp = macHostAppOf(hostExe)
+  assertMacHostCanBundle(hostExe)
+  const mac = config.desktop?.macos ?? {}
+  const appName = cleanBundleName(name)
+  const app = join(out, `${appName}.app`)
+  const tmp = mkdtempSync(join(tmpdir(), "lecodes-macapp-"))
+  try {
+    note(`  host: LeCodes Desktop ${macHostVersion(hostExe)} (${hostApp})`)
+    rmSync(out, { recursive: true, force: true })
+    mkdirSync(out, { recursive: true })
+
+    // 1) The host bundle, whole. `cp -R` keeps the bundle layout; the quarantine xattr a downloaded
+    //    host may carry is dropped (it would be sealed into OUR signature otherwise), and the host's
+    //    signature + stapled ticket go — both are re-made for this app.
+    execFileSync("cp", ["-R", hostApp, app])
+    execFileSync("xattr", ["-cr", app])
+    rmSync(join(app, "Contents", "_CodeSignature"), { recursive: true, force: true })
+    rmSync(join(app, "Contents", "CodeResources"), { force: true })
+
+    // 2) The project, inside: Contents/Resources/project/{app.js, app.json, assets/}. The host
+    //    resolves fetchLocal against this dir (assets/ first), so the cwd never matters.
+    const proj = join(app, "Contents", "Resources", "project")
+    mkdirSync(join(proj, "assets"), { recursive: true })
+    writeFileSync(join(proj, "app.js"), js)
+    let assetBytes = 0, assetCount = 0
+    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(proj, "assets", r.name))
+      assetBytes += statSync(r.absPath).size
+      assetCount++
+    }
+    note(`  assets: ${assetCount} files, ${mb(assetBytes)} → Contents/Resources/project/assets/`)
+    writeJson(join(proj, "app.json"), { name, ...(config.desktop ? { desktop: { window: config.desktop.window } } : {}) })
+
+    // 3) Identity. Everything Finder / Gatekeeper / the Dock attribute to THIS app rather than the host.
+    const plist = join(app, "Contents", "Info.plist")
+    const bundleId = mac.bundleId ?? `codes.le.app.${slug.toLowerCase().replace(/[^a-z0-9.-]+/g, "-")}`
+    plistSet(plist, "CFBundleName", appName)
+    plistSet(plist, "CFBundleDisplayName", appName)
+    plistSet(plist, "CFBundleIdentifier", bundleId)
+    plistSet(plist, "CFBundleShortVersionString", config.version ?? "1.0")
+    plistSet(plist, "CFBundleVersion", String(mac.buildNumber ?? 1))
+    if (mac.category) plistSet(plist, "LSApplicationCategoryType", mac.category)
+    if (config.icon) {
+      await writeIcns(root, config, join(app, "Contents", "Resources", "AppIcon.icns"), tmp)
+      plistSet(plist, "CFBundleIconFile", "AppIcon")
+      note("  icon: AppIcon.icns rendered from " + config.icon)
+    }
+    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)
+    await signApp(app, signing, hostApp, tmp)
+    if (signing.notaryProfile) {
+      notarize(app, signing.notaryProfile, tmp, "app")
+    } else if (signing.identity !== "-") {
+      warn("Signed with Developer ID but NOT notarized — Gatekeeper refuses a downloaded copy on every other Mac.")
+      warn("  Set desktop.macos.notarize.profile in app.json (a `xcrun notarytool store-credentials` profile) or pass --notarize <profile>.")
+    }
+    const verdict = gatekeeperVerdict(app)
+    log(`${verdict.accepted ? c.green("gatekeeper") : c.yellow("gatekeeper")} ${verdict.line}`)
+    if (signing.notaryProfile && !verdict.accepted) {
+      throw new CliError("The app was notarized but Gatekeeper still rejects it — see the spctl line above.")
+    }
+
+    writeFileSync(join(out, "README.txt"), readmeText(appName, !!signing.notaryProfile, signing.identity !== "-"))
+    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")) {
+      // 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")) {
+      note("Tip: --zip packs the .app for sending; --dmg wraps it in a drag-to-Applications image.")
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+const readmeText = (name: string, notarized: boolean, developerId: boolean) => `${name}
+${"=".repeat(Math.max(name.length, 4))}
+
+A LeCodes desktop app for macOS (Apple Silicon). Nothing to install: unzip and double-click
+${name}.app — or drag it to Applications first.
+
+${notarized
+    ? "The app is signed and notarized by Apple: macOS asks once whether to open a downloaded app,\nthen it runs."
+    : developerId
+      ? "The app is signed but NOT notarized: macOS will refuse to open the downloaded copy. To run it\nanyway: System Settings › Privacy & Security › \"Open Anyway\" (after the first refused launch),\nor remove the quarantine flag in Terminal:  xattr -dr com.apple.quarantine \"" + name + ".app\""
+      : "The app is not signed for distribution: macOS will refuse to open the downloaded copy. To run it\nanyway: System Settings › Privacy & Security › \"Open Anyway\" (after the first refused launch),\nor remove the quarantine flag in Terminal:  xattr -dr com.apple.quarantine \"" + name + ".app\""}
+`

package/src/commands/appIcon.ts

@@ -0,0 +1,187 @@
+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"
+
+/* 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
+ * icon file, so hand-made icons (Xcode's appiconset, Android Studio's Image Asset output) stay
+ * as they are — and removing the key later just stops regeneration, it deletes nothing. With
+ * the key set, the generated files become CLI-owned carve-outs like assets/:
+ *   ios/App/Assets.xcassets/AppIcon.appiconset/  (AppIcon.png + Contents.json)
+ *   android/app/src/main/res/mipmap-* / values/lecodes_icon.xml
+ * jimp is imported lazily — it's a decode/encode stack most CLI invocations never need. */
+
+const MASTER_PX = 1024
+
+/** Launcher buckets, mdpi ×1 … xxxhdpi ×4. Legacy icons (API 23-25) are 48dp full-bleed;
+ *  adaptive layers (26+) live on a 108dp canvas of which launchers show the middle ~72dp. */
+const DENSITIES = [
+  { qualifier: "mdpi", scale: 1 },
+  { qualifier: "hdpi", scale: 1.5 },
+  { qualifier: "xhdpi", scale: 2 },
+  { qualifier: "xxhdpi", scale: 3 },
+  { qualifier: "xxxhdpi", scale: 4 },
+] as const
+
+export interface IconMaster {
+  image: JimpInstance      // square, MASTER_PX², straight alpha
+  background: number       // 0xRRGGBBFF for jimp canvases
+  backgroundHex: string    // "#RRGGBB" for resource files
+}
+
+export const loadIconMaster = async (root: string, config: AppConfig): Promise<IconMaster> => {
+  const rel = config.icon!
+  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
+
+  const { Jimp } = await import("jimp")
+  let image: JimpInstance
+  try {
+    image = (await Jimp.read(path)) as JimpInstance
+  } catch (e) {
+    throw new CliError(`Could not decode "icon" ${rel} (${(e as Error).message}) — use a square PNG or JPEG.`)
+  }
+  if (image.width !== image.height) {
+    warn(`"icon" ${rel} is ${image.width}×${image.height} — not square, so it gets center-cropped.`)
+  }
+  if (Math.min(image.width, image.height) < MASTER_PX) {
+    warn(`"icon" ${rel} is under ${MASTER_PX}px — it will be upscaled and may look soft.`)
+  }
+  image.cover({ w: MASTER_PX, h: MASTER_PX })
+  return { image, background, backgroundHex }
+}
+
+/* ------------------------------------------ iOS ------------------------------------------ */
+
+/** The init-time Contents.json plus the filename binding for the light icon; dark/tinted slots
+ *  stay unassigned and fall back to it (exactly what Xcode writes when a PNG is dropped in). */
+const IOS_CONTENTS_JSON = `{
+  "images" : [
+    {
+      "filename" : "AppIcon.png",
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "tinted"
+        }
+      ],
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
+`
+
+export const writeIosAppIcon = async (iosDir: string, master: IconMaster): Promise<void> => {
+  const { Jimp } = await import("jimp")
+  const dir = join(iosDir, "App", "Assets.xcassets", "AppIcon.appiconset")
+  mkdirSync(dir, { recursive: true })
+  // The App Store marketing icon must be fully opaque: flatten over the background and encode
+  // RGB (colorType 2) so no alpha channel survives for the validator to reject.
+  const flat = new Jimp({ width: MASTER_PX, height: MASTER_PX, color: master.background })
+  flat.composite(master.image, 0, 0)
+  writeFileSync(join(dir, "AppIcon.png"), await flat.getBuffer("image/png", { colorType: 2 }))
+  writeFileSync(join(dir, "Contents.json"), IOS_CONTENTS_JSON)
+  log(`${c.green("icon")}      AppIcon.png (${MASTER_PX}×${MASTER_PX}) → ios/App/Assets.xcassets/AppIcon.appiconset/`)
+}
+
+/* ---------------------------------------- Android ---------------------------------------- */
+
+const ADAPTIVE_ICON_XML = `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` from app.json "icon" — regenerated on every sync. -->
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/lecodes_icon_background" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
+</adaptive-icon>
+`
+
+const iconColorXml = (hex: string): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app sync\` from app.json "iconBackground" — regenerated on every sync. -->
+<resources>
+    <color name="lecodes_icon_background">${hex}</color>
+</resources>
+`
+
+export const writeAndroidIcons = async (androidDir: string, master: IconMaster): Promise<void> => {
+  const { Jimp } = await import("jimp")
+  const resDir = join(androidDir, "app", "src", "main", "res")
+  const writeRes = (rel: string, content: Uint8Array | string) => {
+    const abs = join(resDir, rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+  }
+
+  // Legacy (API 23-25) icons are shown as-is — full-bleed master flattened over the background.
+  const legacy = new Jimp({ width: MASTER_PX, height: MASTER_PX, color: master.background })
+  legacy.composite(master.image, 0, 0)
+
+  for (const { qualifier, scale } of DENSITIES) {
+    const legacyPx = Math.round(48 * scale)
+    const l = legacy.clone() as JimpInstance
+    l.resize({ w: legacyPx, h: legacyPx })
+    writeRes(`mipmap-${qualifier}/ic_launcher.png`, await l.getBuffer("image/png"))
+
+    // Adaptive foreground: the master at 72dp centered on the transparent 108dp canvas — the
+    // outer ring is parallax bleed that launcher masks crop, so content there would be lost.
+    const canvasPx = Math.round(108 * scale)
+    const contentPx = Math.round(72 * scale)
+    const fg = new Jimp({ width: canvasPx, height: canvasPx, color: 0x00000000 })
+    const content = master.image.clone() as JimpInstance
+    content.resize({ w: contentPx, h: contentPx })
+    fg.composite(content, Math.round((canvasPx - contentPx) / 2), Math.round((canvasPx - contentPx) / 2))
+    writeRes(`mipmap-${qualifier}/ic_launcher_foreground.png`, await fg.getBuffer("image/png"))
+  }
+
+  // The monochrome (Android 13 themed-icon) layer reuses the foreground: launchers tint its
+  // alpha silhouette, which is right for transparent-background marks and acceptable (a tinted
+  // rounded square) for full-bleed ones. Redefine @mipmap/ic_launcher_foreground to override.
+  writeRes("mipmap-anydpi-v26/ic_launcher.xml", ADAPTIVE_ICON_XML)
+  writeRes("values/lecodes_icon.xml", iconColorXml(master.backgroundHex))
+  log(`${c.green("icon")}      adaptive + legacy launcher icons → android/app/src/main/res/mipmap-*/`)
+}
+
+/** Point the USER-owned manifest at the generated set — a value-only restamp in the
+ *  versionName spirit: warn-not-fail when the user restructured the manifest. */
+export const restampManifestIcon = (androidDir: string): void => {
+  const path = join(androidDir, "app", "src", "main", "AndroidManifest.xml")
+  if (!existsSync(path)) return
+  const content = readFileSync(path, "utf8")
+  if (content.includes(`android:icon="@mipmap/ic_launcher"`)) return
+  if (!/android:icon="[^"]*"/.test(content)) {
+    warn(`couldn't find android:icon in app/src/main/AndroidManifest.xml — set it to "@mipmap/ic_launcher" yourself.`)
+    return
+  }
+  writeFileSync(path, content.replace(/android:icon="[^"]*"/, `android:icon="@mipmap/ic_launcher"`))
+  log(`${c.green("updated")}   android/app/src/main/AndroidManifest.xml: android:icon → @mipmap/ic_launcher`)
+}