lecodes-cli 0.19.0 → 0.19.2

package/src/commands/app.ts

@@ -0,0 +1,891 @@
+import { execFileSync } from "node:child_process"
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, dirname, join, resolve } from "node:path"
+import { readManifest, type Manifest } from "../manifest"
+import { loadConfig, requireApiUrl } from "../config"
+import { compileShell, type BundleResource } from "./compile"
+import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+import {
+  ACCENT_COLOR_JSON, APP_DELEGATE, APP_ICON_JSON, ASSETS_ROOT_JSON, IOS_README, LAUNCH_STORYBOARD,
+  SCENE_DELEGATE, SCHEME_XML, VIEW_CONTROLLER, entitlementsTemplate, infoPlistTemplate,
+  pbxprojTemplate, runtimePackageTemplate, runtimeSwiftTemplate,
+  type RuntimePlugin, type SdkVariant, type ShellIdentity,
+} from "./appTemplates"
+import {
+  FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, detectEngines, ensureShellIgnored,
+  fetchLatestSdkVersion, latestPluginTag, projectRoot, readJson, resolvePlugin, resolveSdkVersion,
+  resolveVariant, runTool, slugify, writeJson, VERSION_RE, type AppConfig, type LockEntry,
+} from "./appShared"
+import {
+  ANDROID_SDK_MIN_VERSION, ANDROID_SDK_REPO, buildAndroid, doctorAndroidChecks, initAndroid,
+  openAndroid, shellSdkVersionAndroid, syncAndroid, type SyncArtifacts,
+} from "./appAndroid"
+import { buildDesktop, initDesktop } from "./appDesktop"
+import { loadIconMaster, writeIosAppIcon } from "./appIcon"
+
+/*
+ * `lecodes app` — native app shells for a LeCodes project (docs/xcode-app-plan.md).
+ *
+ *   app init ios     scaffold <project>/ios/ (Xcode shell + LeCodesRuntime local package)
+ *                    and app.json; `ios/` is added to .lecodesignore (never pushed).
+ *                    The native SDK version is resolved to the latest published release and
+ *                    pinned in app.json ios.sdk (set it to "latest" to re-resolve every sync).
+ *   app update       move the pins forward: app.json ios.sdk → the newest lecodes-ios-sdk
+ *                    release, plugins.lock.json → the newest tag of each unpinned plugin,
+ *                    then re-sync. `--check` reports what's available without writing.
+ *   app sync         make the shell match the project: compile the bundle-first app.js into
+ *                    ios/App/Resources/ + embed every asset it references (server-backed
+ *                    projects included — offline by default; app.json resources.remote globs
+ *                    opt heavy assets back into streaming), pick the SDK variant
+ *                    (core/2d/3d/full) from the engines the bundle uses — plus the filament
+ *                    resources bundle when it bears 3D — vendor the plugins listed in
+ *                    app.json (from their git repos, pinned in plugins.lock.json), regenerate
+ *                    the CLI-owned files (LeCodesRuntime package, Info.plist, versions).
+ *                    app.json "update" configures native OTA: the shell checks that URL at
+ *                    launch and swaps in newer JS on the next one (LeCodesUpdater).
+ *   app plugin …     list / add / remove plugin entries in app.json.
+ *
+ * Ownership contract: App/*.swift are the USER's after init (sync never touches them);
+ * Info.plist, LeCodesRuntime/, App/Resources/ and the shell README are CLI-owned (sync
+ * regenerates); the pbxproj is written once — sync only restamps the version values inside it.
+ */
+
+const SDK_REPO = "letary/lecodes-ios-sdk"
+
+// Oldest lecodes-ios-sdk a generated shell can use — 1.2.0 = variant matrix (core/2d/3d/full)
+// + LeCodesUpdater (native OTA), both of which the generated files assume. The version a shell
+// actually links is app.json `ios.sdk` (init pins the newest release, `app update` moves it);
+// this floor is only the last-resort fallback when the network is unavailable at init.
+const SDK_MIN_VERSION = "1.2.0"
+
+
+// First lecodes-ios-sdk release with `LeCodesEngine.bootProjectUuid` — the shell's world
+// identity (docs/push-plan.md). On older SDKs sync simply doesn't bake the uuid (and warns
+// when push is installed) instead of generating code the linked release can't compile.
+const SDK_IDENTITY_VERSION = "1.6.0"
+
+/** The SDK version a synced shell currently links (Package.swift is CLI-owned, so its
+ *  `exact:` pin is the truth) — the offline fallback, so a sync without network never
+ *  silently downgrades a shell. `from:` is the pre-pin shape, still read for old shells. */
+const shellSdkVersion = (iosDir: string): string | null => {
+  const path = join(iosDir, "LeCodesRuntime", "Package.swift")
+  if (!existsSync(path)) return null
+  const m = /lecodes-ios-sdk\.git",\s*(?:exact|from):\s*"([^"]+)"/.exec(readFileSync(path, "utf8"))
+  return m && VERSION_RE.test(m[1]) ? m[1] : null
+}
+
+const IOS_SDK_OPTS = { repo: SDK_REPO, minVersion: SDK_MIN_VERSION, configKey: "ios.sdk" }
+
+/* --------------------------------------- init --------------------------------------- */
+
+const appInit = async (args: Args) => {
+  const platform = args._[1]
+  if (platform === "android") return initAndroid(args)
+  if (platform === "desktop") return initDesktop(args)
+  if (platform !== "ios") {
+    throw new CliError(platform
+      ? `Unsupported platform "${platform}" — use ios, android or desktop.`
+      : "Usage: lecodes app init <ios|android|desktop> [--name <display name>] [--bundle-id <id>] [--team <team id>] [--variant auto|core|2d|3d|full] [--app-id <application id>] [--sdk <version|latest>]")
+  }
+
+  const root = projectRoot()
+  const iosDir = join(root, "ios")
+  if (existsSync(iosDir)) {
+    throw new CliError("ios/ already exists — run `lecodes app sync` to update it.")
+  }
+
+  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const variant = flagStr(args, "variant") ?? existing.ios?.variant ?? "auto"
+  if (variant !== "auto" && !SDK_VARIANTS.includes(variant as SdkVariant)) {
+    throw new CliError(`--variant must be auto, ${SDK_VARIANTS.join(", ")} (got "${variant}")`)
+  }
+
+  // The native SDK: a new shell starts on the newest published release, pinned into app.json so
+  // builds stay reproducible (`lecodes app update` moves the pin). `--sdk latest` opts into
+  // re-resolving on every sync instead.
+  const sdkFlag = flagStr(args, "sdk") ?? existing.ios?.sdk
+  const sdkVersion = await resolveSdkVersion(process.env.LECODES_IOS_SDK ?? sdkFlag ?? "latest", null, IOS_SDK_OPTS)
+  const sdk = sdkFlag === "latest" ? "latest" : sdkVersion
+
+  const name = flagStr(args, "name") ?? existing.name ?? basename(root)
+  const config: AppConfig = {
+    ...existing,
+    name,
+    version: existing.version ?? "1.0.0",
+    plugins: existing.plugins ?? {},
+    ios: {
+      bundleId: flagStr(args, "bundle-id") ?? existing.ios?.bundleId ?? `com.example.${slugify(name)}`,
+      teamId: flagStr(args, "team") ?? existing.ios?.teamId ?? "",
+      variant,
+      sdk,
+      buildNumber: existing.ios?.buildNumber ?? 1,
+    },
+  }
+  writeJson(join(root, "app.json"), config)
+  log(`${c.green("written")}   app.json`)
+
+  // Never push the shell to the platform.
+  ensureShellIgnored(root, "ios")
+
+  const identity: ShellIdentity = {
+    displayName: name,
+    bundleId: config.ios!.bundleId!,
+    teamId: config.ios!.teamId!,
+    version: config.version!,
+    buildNumber: config.ios!.buildNumber!,
+  }
+
+  const write = (rel: string, content: string) => {
+    const abs = join(iosDir, rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+    log(`${c.green("created")}   ios/${rel}`)
+  }
+
+  write("README.md", IOS_README)
+  write("App.xcodeproj/project.pbxproj", pbxprojTemplate(identity))
+  write("App.xcodeproj/xcshareddata/xcschemes/App.xcscheme", SCHEME_XML)
+  write("App/AppDelegate.swift", APP_DELEGATE)
+  write("App/SceneDelegate.swift", SCENE_DELEGATE)
+  write("App/ViewController.swift", VIEW_CONTROLLER)
+  write("App/Info.plist", infoPlistTemplate({}))
+  write("App/App.entitlements", entitlementsTemplate({}))
+  write("App/Base.lproj/LaunchScreen.storyboard", LAUNCH_STORYBOARD)
+  write("App/Assets.xcassets/Contents.json", ASSETS_ROOT_JSON)
+  write("App/Assets.xcassets/AccentColor.colorset/Contents.json", ACCENT_COLOR_JSON)
+  write("App/Assets.xcassets/AppIcon.appiconset/Contents.json", APP_ICON_JSON)
+  // "auto" resolves at sync time (the compiled bundle says which engines it uses); until the
+  // first sync the shell gets the slimmest product as a placeholder.
+  write("LeCodesRuntime/Package.swift", runtimePackageTemplate(sdkVersion, variant === "auto" ? "core" : variant as SdkVariant, []))
+  write("LeCodesRuntime/Sources/LeCodesRuntime/LeCodesRuntime.swift", runtimeSwiftTemplate([]))
+
+  log("")
+  log(`${c.green("sdk")}       lecodes-ios-sdk ${sdkVersion}${sdk === "latest" ? c.dim("  (ios.sdk: latest — re-resolved on every sync)") : c.dim("  (pinned in app.json ios.sdk — `lecodes app update` moves it)")}`)
+  success(`iOS shell for ${c.bold(name)} ready.`)
+  log(`  ${c.bold("lecodes app sync")}          embed the compiled bundle (+ plugins) into the shell`)
+  log(`  ${c.bold("open ios/App.xcodeproj")}    then run on your device from Xcode`)
+  log(`  App icon: set app.json "icon" to a square ≥1024px image — sync renders every size (or drop a PNG into App/Assets.xcassets/AppIcon.appiconset/)`)
+}
+
+/* --------------------------------------- sync --------------------------------------- */
+
+
+/** The filament resources bundle that must ship beside any CreatorGL-bearing variant (3d/full).
+ *  Published as a release asset next to the SDK binaries; downloaded once per SDK version into
+ *  ~/.lecodes/sdk-resources/. `LECODES_SDK_RESOURCES` overrides with a local .bundle — the
+ *  SDK-development loop, like LECODES_PLUGINS_DIR for plugins. */
+const ensureSdkResourcesBundle = async (sdkVersion: string): Promise<string> => {
+  const override = process.env.LECODES_SDK_RESOURCES
+  if (override) {
+    note(`Using local resources bundle ${override} (LECODES_SDK_RESOURCES)`)
+    return resolve(override)
+  }
+  const dir = join(homedir(), ".lecodes", "sdk-resources", sdkVersion)
+  const bundle = join(dir, "LeCodesSDKResources.bundle")
+  if (existsSync(bundle)) return bundle
+  const url = `https://github.com/${SDK_REPO}/releases/download/${sdkVersion}/LeCodesSDKResources.bundle.zip`
+  note(`Downloading LeCodesSDKResources.bundle (SDK ${sdkVersion})…`)
+  const res = await fetch(url)
+  if (!res.ok) throw new CliError(`Resources bundle download failed (HTTP ${res.status}) — ${url}`)
+  mkdirSync(dir, { recursive: true })
+  const zip = join(dir, "LeCodesSDKResources.bundle.zip")
+  writeFileSync(zip, new Uint8Array(await res.arrayBuffer()))
+  execFileSync("ditto", ["-x", "-k", zip, dir])   // release zips are ditto archives (--keepParent)
+  rmSync(zip)
+  if (!existsSync(bundle)) throw new CliError(`No LeCodesSDKResources.bundle inside the release asset ${url}`)
+  return bundle
+}
+
+/** Resolve app.json "update" to the URL the shell's native updater checks. `true` means the
+ *  project's live bundle on the platform (`/code/<uuid>.js` — needs a server-backed project);
+ *  strings / { url } pass through. Warns on http: ATS blocks it on device. */
+const resolveUpdateUrl = (update: AppConfig["update"], root: string): string | undefined => {
+  if (!update) return undefined
+  let url = typeof update === "string" ? update : typeof update === "object" ? update.url : undefined
+  if (!url) {
+    let manifest: Manifest | null = null
+    try { manifest = readManifest(root) } catch { /* not a project dir */ }
+    if (!manifest) {
+      warn(`app.json "update": true needs a server-backed project — use "update": {"url": "https://…/app.js"} for custom hosting. OTA left unconfigured.`)
+      return undefined
+    }
+    url = `${requireApiUrl(loadConfig())}/code/${manifest.uuid}.js`
+  }
+  if (!url.startsWith("https://")) warn(`update URL is not https — iOS blocks it on device (ATS): ${url}`)
+  return url
+}
+
+/** `lecodes app sync [ios|android]` — no platform syncs every shell dir that exists. A
+ *  dual-shell project compiles the bundle ONCE (the iOS pass) and the Android pass reuses
+ *  the byte-identical output. */
+const appSync = async (args: Args) => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const platform = args._[1]
+  if (platform !== undefined && platform !== "ios" && platform !== "android") {
+    throw new CliError(`Unknown platform "${platform}" — use ios or android.`)
+  }
+  const hasIos = !!config?.ios && existsSync(join(root, "ios"))
+  const hasAndroid = !!config?.android && existsSync(join(root, "android"))
+  if (platform === "ios" && !hasIos) throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  if (platform === "android" && !hasAndroid) throw new CliError("No Android shell here — run `lecodes app init android` first.")
+  if (!platform && !hasIos && !hasAndroid) {
+    throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  }
+
+  let iosArtifacts: SyncArtifacts | null = null
+  if (hasIos && platform !== "android") iosArtifacts = await syncIos(root, config!)
+  if (hasAndroid && platform !== "ios") await syncAndroid(root, config!, iosArtifacts)
+}
+
+const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts> => {
+  const iosDir = join(root, "ios")
+  if (!config.ios) throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  // The variant is resolved after the compile below (the bundle header says which engines the
+  // project uses) — but reject a mistyped forced value before doing any work.
+  const requestedVariant = config.ios.variant ?? "auto"
+  if (requestedVariant !== "auto" && !SDK_VARIANTS.includes(requestedVariant as SdkVariant)) {
+    throw new CliError(`app.json ios.variant must be "auto" or one of ${SDK_VARIANTS.join(", ")} (got "${requestedVariant}").`)
+  }
+
+  // The native SDK release this shell links: app.json ios.sdk, or — for shells scaffolded before
+  // that key existed — whatever Package.swift already names, so a routine sync never moves a
+  // project's native SDK on its own (`lecodes app update` does that). "latest" re-resolves here,
+  // degrading to the linked version when offline.
+  const linkedSdk = shellSdkVersion(iosDir)
+  const sdkPin = process.env.LECODES_IOS_SDK ?? config.ios.sdk ?? linkedSdk ?? "latest"
+  const sdkVersion = await resolveSdkVersion(sdkPin, linkedSdk, IOS_SDK_OPTS)
+
+  // ---- plugins: vendor sources, collect registration + Info.plist keys, pin the lock ----
+  const lockPath = join(root, "plugins.lock.json")
+  const oldLock = readJson<{ plugins?: Record<string, LockEntry> }>(lockPath)?.plugins ?? {}
+  const pluginSpecs = Object.entries(config.plugins ?? {})
+  const runtimePlugins: RuntimePlugin[] = []
+  const infoValues: Record<string, string[]> = {}
+  const entitlementValues: Record<string, unknown[]> = {}
+  const newLock: Record<string, LockEntry> = {}
+
+  const sourcesDir = join(iosDir, "LeCodesRuntime", "Sources")
+  for (const [id, spec] of pluginSpecs) {
+    const plugin = resolvePlugin(id, spec, oldLock[id], "ios")
+    const ios = plugin.manifest.ios!
+    const module = ios.module
+    const register = ios.register
+    if (!module || !register) throw new CliError(`Plugin "${id}": manifest ios.module / ios.register missing`)
+
+    const src = join(plugin.dir, ios.sources ?? "ios")
+    if (!existsSync(src)) throw new CliError(`Plugin "${id}": sources dir ${src} missing`)
+    const dest = join(sourcesDir, module)
+    rmSync(dest, { recursive: true, force: true })
+    cpSync(src, dest, { recursive: true })
+
+    // Hard error, not a warning: below minSdk the vendored sources reference SDK API that
+    // does not exist in the linked release, so the shell cannot compile anyway.
+    if (ios.minSdk && VERSION_RE.test(ios.minSdk) && cmpVersion(sdkVersion, ios.minSdk) < 0) {
+      throw new CliError(`Plugin "${id}" needs lecodes-ios-sdk ${ios.minSdk} but the shell links ${sdkVersion} — run \`lecodes app update\` (or set app.json ios.sdk).`)
+    }
+    for (const [key, value] of Object.entries(ios.infoPlist ?? {})) {
+      (infoValues[key] ??= []).push(value)
+    }
+    for (const [key, value] of Object.entries(ios.entitlements ?? {})) {
+      (entitlementValues[key] ??= []).push(value)
+    }
+    runtimePlugins.push({ id, module, register })
+    newLock[id] = plugin.lock
+    log(`${c.green("plugin")}    ${id}@${plugin.lock.version} (${plugin.lock.tag} → Sources/${module})`)
+  }
+
+  // Remove targets of uninstalled plugins (everything under Sources/ except the runtime itself).
+  const keep = new Set(["LeCodesRuntime", ...runtimePlugins.map(p => p.module)])
+  for (const entry of existsSync(sourcesDir) ? readdirSync(sourcesDir) : []) {
+    if (!keep.has(entry) && statSync(join(sourcesDir, entry)).isDirectory()) {
+      rmSync(join(sourcesDir, entry), { recursive: true })
+      log(`${c.yellow("removed")}   ios/LeCodesRuntime/Sources/${entry}  (plugin uninstalled)`)
+    }
+  }
+
+  // ---- bundle: compile self-contained into Resources/, then embed the assets it references ----
+  const remotePatterns = config.resources?.remote ?? []
+  if (!Array.isArray(remotePatterns) || remotePatterns.some((p) => typeof p !== "string")) {
+    throw new CliError('app.json "resources.remote" must be an array of glob strings (e.g. ["videos/**"]).')
+  }
+  const resourcesDir = join(iosDir, "App", "Resources")
+  rmSync(resourcesDir, { recursive: true, force: true })
+  mkdirSync(resourcesDir, { recursive: true })
+  const resources = await compileShell({ _: [], flags: { o: join(resourcesDir, "app.js") } }, { remotePatterns })
+
+  // ---- variant: the smallest SDK product covering what the bundle uses (or the forced one) ----
+  const bundleJs = readFileSync(join(resourcesDir, "app.js"), "utf8")
+  const { variant, detected } = resolveVariant(requestedVariant, bundleJs)
+  const WHY: Record<SdkVariant, string> = {
+    core: "UI only", "2d": "uses the 2D engine", "3d": "uses the 3D engine", full: "uses the 3D + 2D engines",
+  }
+  log(`${c.green("variant")}   ${variant}${requestedVariant === "auto" ? ` (auto: ${WHY[detected]})` : " (forced by ios.variant)"}`)
+  const sdkWhy = sdkPin === "latest" ? "latest" : config.ios.sdk ? "pinned by ios.sdk" : "from the shell — set ios.sdk or run `lecodes app update`"
+  log(`${c.green("sdk")}       lecodes-ios-sdk ${sdkVersion}${c.dim(`  (${sdkWhy})`)}`)
+
+  // The filament resources ride along with any CreatorGL-bearing variant. Its files also back
+  // fetchLocal for SDK built-ins (lit.filamat & co), so the embed step below can skip them.
+  const sdkProvided = new Set<string>()
+  if (variant === "3d" || variant === "full") {
+    const sdkResources = await ensureSdkResourcesBundle(sdkVersion)
+    cpSync(sdkResources, join(resourcesDir, "LeCodesSDKResources.bundle"), { recursive: true })
+    for (const f of readdirSync(sdkResources)) if (f !== "Info.plist") sdkProvided.add(f)
+    log(`${c.green("resources")} LeCodesSDKResources.bundle (filament) → ios/App/Resources/`)
+  }
+
+  // Embed exactly what the bundle resolves locally: the `// preload:` header names every
+  // fetchLocal resource (vendored fonts included). resources.remote entries stayed URLs, and
+  // an asset the code never references isn't shipped. Copies are flat by lookup name — the
+  // host's setFetchLocal reads Resources/ by basename, falling back to the SDK resources
+  // bundle for the sdkProvided names.
+  const preload = /^\/\/ preload: (.*)$/m.exec(bundleJs)?.[1].split(";").map((s) => s.trim()).filter(Boolean) ?? []
+  const IMPLICIT_PRELOADS = new Set(["uberarchive", "capture"]) // engine-synthesized, not project files
+  const byName = new Map<string, BundleResource[]>()
+  for (const r of resources) {
+    if (r.remote || !r.absPath) continue
+    const list = byName.get(r.name) ?? []
+    list.push(r)
+    byName.set(r.name, list)
+  }
+  let embedded = 0
+  for (const name of preload) {
+    if (IMPLICIT_PRELOADS.has(name)) continue
+    const candidates = byName.get(name) ?? []
+    if (candidates.length === 0) {
+      if (!sdkProvided.has(name)) warn(`bundle needs local asset "${name}" but no project file provides it — it won't load on device`)
+      continue
+    }
+    if (candidates.length > 1) warn(`asset name collision: ${name} (${candidates.map((r) => r.path).join(", ")}) — embedding ${candidates[0].path}`)
+    cpSync(candidates[0].absPath!, join(resourcesDir, name))
+    embedded++
+  }
+  if (embedded > 0) log(`${c.green("assets")}    ${embedded} file(s) embedded → ios/App/Resources/`)
+  const streamed = resources.filter((r) => r.remote)
+  if (streamed.length > 0) log(`${c.green("remote")}    ${streamed.length} resource(s) stay on the server (resources.remote): ${streamed.map((r) => r.path).join(", ")}`)
+
+  // ---- identity: a server-backed shell bakes its project uuid into the runtime, so
+  // identity-gated services (push registration) see the app's own uuid. Gated on the SDK
+  // release that carries LeCodesEngine.bootProjectUuid — on older SDKs the uuid is simply
+  // not baked (register() rejects "unavailable" exactly as before).
+  let shellUuid: string | undefined
+  try { shellUuid = readManifest(root).uuid } catch { /* local-only project — unattributed */ }
+  if (shellUuid && cmpVersion(sdkVersion, SDK_IDENTITY_VERSION) < 0) {
+    if (runtimePlugins.some(p => p.id === "push")) {
+      warn(`push needs the shell's world identity, which lecodes-ios-sdk ${SDK_IDENTITY_VERSION}+ carries — this shell links ${sdkVersion}, so Push.register() will reject "unavailable". Run \`lecodes app update\` when ${SDK_IDENTITY_VERSION} is out.`)
+    }
+    shellUuid = undefined
+  }
+  if (shellUuid) log(`${c.green("identity")}  project ${shellUuid} baked into the shell (world identity)`)
+
+  // ---- regenerate the CLI-owned files ----
+  writeFileSync(join(iosDir, "README.md"), IOS_README)
+  writeFileSync(join(iosDir, "LeCodesRuntime", "Package.swift"), runtimePackageTemplate(sdkVersion, variant, runtimePlugins))
+  writeFileSync(join(sourcesDir, "LeCodesRuntime", "LeCodesRuntime.swift"), runtimeSwiftTemplate(runtimePlugins, shellUuid))
+
+  const mergedKeys: Record<string, string> = {}
+  for (const [key, values] of Object.entries(infoValues)) mergedKeys[key] = [...new Set(values)].join(" ")
+  const updateUrl = resolveUpdateUrl(config.update, root)
+  writeFileSync(join(iosDir, "App", "Info.plist"), infoPlistTemplate(mergedKeys, updateUrl))
+  if (updateUrl) log(`${c.green("update")}    OTA source ${updateUrl} — checked natively at launch, new code applies next launch`)
+  else if (!config.update) {
+    // Discoverability: server-backed projects get OTA with one app.json key, but nothing
+    // else ever mentions it. One dim line, only while unconfigured.
+    let manifest: Manifest | null = null
+    try { manifest = readManifest(root) } catch { /* not a project dir */ }
+    if (manifest) note(`tip: add "update": true to app.json for over-the-air JS updates — ship with \`lecodes push --publish\`, no store release`)
+  }
+
+  if (pluginSpecs.length > 0 || existsSync(lockPath)) writeJson(lockPath, { plugins: newLock })
+
+  // Version restamp — values only, never structure (the pbxproj is otherwise init-owned).
+  const pbxPath = join(iosDir, "App.xcodeproj", "project.pbxproj")
+  let pbx = readFileSync(pbxPath, "utf8")
+    .replace(/MARKETING_VERSION = [^;]+;/g, `MARKETING_VERSION = ${config.version ?? "1.0.0"};`)
+    .replace(/CURRENT_PROJECT_VERSION = [^;]+;/g, `CURRENT_PROJECT_VERSION = ${config.ios.buildNumber ?? 1};`)
+
+  // ---- entitlements: the capabilities the installed plugins declare (push's aps-environment).
+  // App/App.entitlements is CLI-owned and regenerated whenever the pbxproj references it (every
+  // shell scaffolded with one) or a plugin needs one. Shells from before the entitlements era
+  // get the CODE_SIGN_ENTITLEMENTS reference injected the first time a plugin brings a
+  // capability — the ONE structural pbxproj edit sync ever makes, idempotent and line-shaped.
+  const mergedEntitlements: Record<string, unknown> = {}
+  for (const [key, values] of Object.entries(entitlementValues)) {
+    if (values.every(v => Array.isArray(v))) {
+      const seen = new Set<string>()
+      mergedEntitlements[key] = (values as unknown[][]).flat()
+        .filter(v => { const s = JSON.stringify(v); if (seen.has(s)) return false; seen.add(s); return true })
+    } else {
+      if (new Set(values.map(v => JSON.stringify(v))).size > 1) {
+        warn(`entitlement ${key}: plugins declare conflicting values — keeping ${JSON.stringify(values[0])}`)
+      }
+      mergedEntitlements[key] = values[0]
+    }
+  }
+  const hasEntitlements = Object.keys(mergedEntitlements).length > 0
+  if (pbx.includes("CODE_SIGN_ENTITLEMENTS") || hasEntitlements) {
+    writeFileSync(join(iosDir, "App", "App.entitlements"), entitlementsTemplate(mergedEntitlements))
+    if (hasEntitlements) log(`${c.green("caps")}      App/App.entitlements: ${Object.keys(mergedEntitlements).sort().join(", ")}`)
+    if (!pbx.includes("CODE_SIGN_ENTITLEMENTS")) {
+      const patched = pbx.replace(/^(\s*)CODE_SIGN_STYLE = /gm, `$1CODE_SIGN_ENTITLEMENTS = "App/App.entitlements";\n$1CODE_SIGN_STYLE = `)
+      if (patched === pbx) {
+        warn(`couldn't wire App.entitlements into the pbxproj — add CODE_SIGN_ENTITLEMENTS = "App/App.entitlements" to the App target's build settings in Xcode.`)
+      } else {
+        pbx = patched.replace(/^(\s*)membershipExceptions = \(\n(\s*)Info\.plist,/m, `$1membershipExceptions = (\n$2App.entitlements,\n$2Info.plist,`)
+        log(`${c.green("updated")}   App.xcodeproj: CODE_SIGN_ENTITLEMENTS → App/App.entitlements`)
+      }
+    }
+  }
+  writeFileSync(pbxPath, pbx)
+
+  // ---- icons: rendered from app.json "icon" when set (the appiconset becomes a CLI-owned
+  // carve-out like Resources/) — absent, a hand-dropped AppIcon.png stays untouched ----
+  if (config.icon) {
+    await writeIosAppIcon(iosDir, await loadIconMaster(root, config))
+  }
+
+  log("")
+  success(`Shell synced: app.js + ${runtimePlugins.length} plugin(s), SDK ${sdkVersion}, variant ${variant}, v${config.version ?? "1.0.0"} (${config.ios.buildNumber ?? 1}).`)
+  note("Build & run from Xcode (open ios/App.xcodeproj) — user files in ios/App/*.swift were not touched.")
+  return { bundleJs, resources }
+}
+
+/* -------------------------------------- plugin -------------------------------------- */
+
+const appPlugin = async (args: Args) => {
+  const sub = args._[1]
+  const root = projectRoot()
+  const configPath = join(root, "app.json")
+  const config = readJson<AppConfig>(configPath)
+  if (!config) throw new CliError("No app.json here — run `lecodes app init <ios|android>` first.")
+  config.plugins ??= {}
+
+  if (sub === "list" || sub === undefined) {
+    const entries = Object.entries(config.plugins)
+    if (entries.length === 0) { log("No plugins installed."); return }
+    const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
+    for (const [id, spec] of entries) {
+      const pin = lock[id] ? c.dim(`  ${lock[id].repo} ${lock[id].tag} (${lock[id].commit.slice(0, 7)})`) : c.dim("  (not synced)")
+      log(`${c.bold(id)} ${spec}${pin}`)
+    }
+    return
+  }
+
+  const id = args._[2]
+  if (!id) throw new CliError(`Usage: lecodes app plugin ${sub} <id | github:owner/repo[@tag]>`)
+
+  if (sub === "add") {
+    if (id.startsWith("github:")) {
+      const bare = id.slice("github:".length).split("@")[0].split("/").pop()!
+      config.plugins[bare] = id
+      log(`${c.green("added")}     ${bare} → ${id}  ${c.dim("(third-party native code — review it before shipping)")}`)
+    } else if (FIRST_PARTY_PLUGINS[id]) {
+      config.plugins[id] = "*"
+      log(`${c.green("added")}     ${id}`)
+    } else {
+      throw new CliError(`Unknown plugin "${id}" — known: ${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}, or use github:owner/repo[@tag].`)
+    }
+    writeJson(configPath, config)
+    note("Run `lecodes app sync` to vendor it into the shell.")
+    return
+  }
+
+  if (sub === "remove") {
+    if (!(id in config.plugins)) throw new CliError(`Plugin "${id}" is not installed.`)
+    delete config.plugins[id]
+    writeJson(configPath, config)
+    log(`${c.yellow("removed")}   ${id}`)
+    note("Run `lecodes app sync` to drop its sources from the shell.")
+    return
+  }
+
+  throw new CliError(`Unknown subcommand "plugin ${sub}" — use list, add or remove.`)
+}
+
+/* ---------------------------------- build & upload ----------------------------------- */
+
+const exportOptionsPlist = (method: string, teamId: string, destination?: "upload"): string => `<?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>method</key>
+	<string>${method}</string>
+	<key>signingStyle</key>
+	<string>automatic</string>${teamId ? `
+	<key>teamID</key>
+	<string>${teamId}</string>` : ""}${destination ? `
+	<key>destination</key>
+	<string>${destination}</string>` : ""}
+</dict>
+</plist>
+`
+
+const requireShell = (): { root: string, config: AppConfig } => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  if (!config?.ios || !existsSync(join(root, "ios"))) {
+    throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  }
+  return { root, config }
+}
+
+/* -------------------------------------- update --------------------------------------- */
+
+/** One platform's SDK-pin movement inside `app update` — identical flow for both arms, only
+ *  the labels/repos differ. Mutates config[platform].sdk (checkOnly writes nothing);
+ *  @return true when something changed. */
+const updateSdkPin = async (
+  root: string, config: AppConfig, args: Args, checkOnly: boolean,
+  platform: "ios" | "android",
+): Promise<boolean> => {
+  const [label, repo, minVersion, shellVersion] = platform === "ios"
+    ? ["lecodes-ios-sdk", SDK_REPO, SDK_MIN_VERSION, () => shellSdkVersion(join(root, "ios"))] as const
+    : ["lecodes-android-sdk", ANDROID_SDK_REPO, ANDROID_SDK_MIN_VERSION, () => shellSdkVersionAndroid(join(root, "android"))] as const
+  const section = config[platform]!
+  const wanted = flagStr(args, "sdk")
+  let changed = false
+
+  // No sdk key = an old shell: its CLI-owned build file is the pin sync would keep.
+  const pin = section.sdk ?? shellVersion() ?? "latest"
+  const current = pin === "latest" ? (shellVersion() ?? minVersion) : pin
+  let nextPin: string
+  if (wanted === "latest") {
+    nextPin = "latest"                                        // float: every sync re-resolves
+  } else if (wanted) {
+    if (!VERSION_RE.test(wanted)) throw new CliError(`--sdk must be "latest" or an exact x.y.z release (got "${wanted}").`)
+    if (cmpVersion(wanted, minVersion) < 0) throw new CliError(`--sdk ${wanted} is older than the ${minVersion} these generated shells need.`)
+    nextPin = wanted
+  } else {
+    nextPin = await fetchLatestSdkVersion(repo)
+  }
+  const nextVersion = nextPin === "latest" ? await fetchLatestSdkVersion(repo) : nextPin
+
+  if (nextVersion === current && nextPin === pin) {
+    log(`${c.green("sdk")}       ${label} ${current} ${c.dim("(already current)")}`)
+  } else if (nextVersion === current) {
+    log(`${c.green("sdk")}       ${label} ${current} → ${platform}.sdk ${nextPin} ${c.dim("(same version, pin mode changed)")}`)
+    changed = true
+  } else {
+    const verb = cmpVersion(nextVersion, current) < 0 ? c.yellow("downgrade") : c.green("update")
+    log(`${c.green("sdk")}       ${label} ${current} → ${c.bold(nextVersion)} ${c.dim(`(${verb})`)}`)
+    changed = true
+  }
+  if (!checkOnly && nextPin !== pin) {
+    section.sdk = nextPin
+    writeJson(join(root, "app.json"), config)
+  }
+  return changed
+}
+
+/** `lecodes app update [ios|android]` — move a shell's pins forward, the way `app sync` moves
+ *  its code: app.json ios.sdk / android.sdk → the newest published SDK release,
+ *  plugins.lock.json → the newest tag of every plugin whose app.json spec doesn't name one
+ *  (a `github:owner/repo@tag` spec is a deliberate pin and is left alone). Then re-syncs so
+ *  the shell actually carries the new versions — `--check` reports and writes nothing. */
+const appUpdate = async (args: Args) => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const platform = args._[1]
+  if (platform !== undefined && platform !== "ios" && platform !== "android") {
+    throw new CliError(`Unknown platform "${platform}" — use ios or android.`)
+  }
+  const hasIos = !!config?.ios && existsSync(join(root, "ios"))
+  const hasAndroid = !!config?.android && existsSync(join(root, "android"))
+  if (platform === "ios" && !hasIos) throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  if (platform === "android" && !hasAndroid) throw new CliError("No Android shell here — run `lecodes app init android` first.")
+  if (!hasIos && !hasAndroid) throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  const doIos = hasIos && platform !== "android"
+  const doAndroid = hasAndroid && platform !== "ios"
+  if (flagStr(args, "sdk") && doIos && doAndroid) {
+    throw new CliError("--sdk is ambiguous with two shells — run `lecodes app update ios --sdk …` or `lecodes app update android --sdk …`.")
+  }
+
+  const checkOnly = flagBool(args, "check")
+  let changed = false
+
+  // ---- SDK pins ----
+  if (doIos) changed = (await updateSdkPin(root, config!, args, checkOnly, "ios")) || changed
+  if (doAndroid) changed = (await updateSdkPin(root, config!, args, checkOnly, "android")) || changed
+
+  // ---- plugins ----
+  const lockPath = join(root, "plugins.lock.json")
+  const lock = readJson<{ plugins?: Record<string, LockEntry> }>(lockPath)?.plugins ?? {}
+  const specs = Object.entries(config!.plugins ?? {})
+  if (specs.length > 0 && !flagBool(args, "no-plugins")) {
+    const kept: Record<string, LockEntry> = {}
+    for (const [id, spec] of specs) {
+      const entry = lock[id]
+      if (spec.startsWith("github:") && spec.includes("@")) {
+        log(`${c.green("plugin")}    ${id} ${c.dim(`pinned by app.json (${spec}) — not updated`)}`)
+        if (entry) kept[id] = entry
+        continue
+      }
+      const repo = spec.startsWith("github:") ? spec.slice("github:".length) : FIRST_PARTY_PLUGINS[id]
+      const tag = repo ? latestPluginTag(repo) : null
+      if (!tag) {
+        log(`${c.yellow("plugin")}    ${id} ${c.dim("could not read its latest tag — left as is")}`)
+        if (entry) kept[id] = entry
+        continue
+      }
+      if (entry && entry.tag === tag) {
+        log(`${c.green("plugin")}    ${id} ${entry.tag} ${c.dim("(already current)")}`)
+        kept[id] = entry
+        continue
+      }
+      log(`${c.green("plugin")}    ${id} ${entry?.tag ?? "—"} → ${c.bold(tag)}`)
+      changed = true                                          // dropped from the lock: sync re-pins it
+    }
+    if (!checkOnly && existsSync(lockPath)) writeJson(lockPath, { plugins: kept })
+  }
+
+  log("")
+  if (checkOnly) {
+    note(changed ? "Run `lecodes app update` to apply." : "Everything is up to date.")
+    return
+  }
+  if (!changed) { success("Already up to date."); return }
+  if (flagBool(args, "no-sync")) {
+    success("Pins updated — run `lecodes app sync` to apply them to the shell.")
+    return
+  }
+  await appSync({ _: platform ? ["sync", platform] : [], flags: {} })
+}
+
+const appDoctor = async (_args: Args) => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const hasIos = !!config?.ios && existsSync(join(root, "ios"))
+  const hasAndroid = !!config?.android && existsSync(join(root, "android"))
+  if (!hasIos && !hasAndroid) {
+    throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+  }
+  let failed = 0
+  const check = (ok: boolean, label: string, hint = "", fatal = true) => {
+    log(`${ok ? c.green("✓") : (fatal ? c.red("✗") : c.yellow("!"))} ${label}${ok || !hint ? "" : c.dim("  — " + hint)}`)
+    if (!ok && fatal) failed++
+  }
+
+  if (config?.icon) {
+    check(existsSync(join(root, config.icon)), `Icon master ${config.icon}`, `app.json "icon" points at a missing file — sync will fail`)
+  }
+  if (hasIos) await doctorIosChecks(root, config!, check)
+  if (hasAndroid) {
+    await doctorAndroidChecks(root, config!, check)
+    if (!hasIos) {
+      const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
+      const wanted = Object.keys(config!.plugins ?? {})
+      const inSync = wanted.every(id => lock[id]) && Object.keys(lock).every(id => wanted.includes(id))
+      check(wanted.length === 0 || inSync, "Plugins synced", "run `lecodes app sync`")
+    }
+  }
+
+  log("")
+  if (failed > 0) throw new CliError(`${failed} check(s) failed.`)
+  success("Ready to build.")
+}
+
+const doctorIosChecks = async (
+  root: string, config: AppConfig,
+  check: (ok: boolean, label: string, hint?: string, fatal?: boolean) => void,
+) => {
+  let xcodeVersion = ""
+  try { xcodeVersion = runTool(root, "xcodebuild", ["-version"]).split("\n")[0] } catch { /* absent */ }
+  check(xcodeVersion !== "", `Xcode CLI (${xcodeVersion || "not found"})`, "install Xcode + command line tools")
+  check(!!config.ios!.teamId, "Development team set", "lecodes app init wrote app.json — fill ios.teamId", false)
+
+  const iconDir = join(root, "ios", "App", "Assets.xcassets", "AppIcon.appiconset")
+  const hasIcon = existsSync(iconDir) && readdirSync(iconDir).some(f => f.endsWith(".png"))
+  check(hasIcon, "App icon present", "drop a 1024×1024 PNG into ios/App/Assets.xcassets/AppIcon.appiconset/ (App Store requires it)", false)
+
+  const bundle = join(root, "ios", "App", "Resources", "app.js")
+  check(existsSync(bundle), "Bundled app.js", "run `lecodes app sync`")
+
+  // Variant sanity: valid config value; the synced shell links the product the bundle needs
+  // and carries the filament resources when that product bears CreatorGL.
+  const requestedVariant = config.ios!.variant ?? "auto"
+  const validVariant = requestedVariant === "auto" || SDK_VARIANTS.includes(requestedVariant as SdkVariant)
+  check(validVariant, `ios.variant "${requestedVariant}"`, `use "auto" or one of ${SDK_VARIANTS.join(", ")}`)
+  if (existsSync(bundle) && validVariant) {
+    const { variant } = resolveVariant(requestedVariant, readFileSync(bundle, "utf8"))
+    const pkg = readFileSync(join(root, "ios", "LeCodesRuntime", "Package.swift"), "utf8")
+    const needsResources = variant === "3d" || variant === "full"
+    const hasResources = existsSync(join(root, "ios", "App", "Resources", "LeCodesSDKResources.bundle"))
+    check(pkg.includes(`"LeCodesSDK-${variant}"`) && (!needsResources || hasResources),
+      `SDK variant ${variant}${needsResources ? " (+ filament resources)" : ""}`, "run `lecodes app sync`")
+  }
+
+  // SDK: the shell must link the version app.json asks for, and (soft, needs network) that
+  // should be the newest published release.
+  const linked = shellSdkVersion(join(root, "ios"))
+  const pin = config.ios!.sdk ?? "latest"
+  check(!!linked, `SDK ${linked ?? "version unreadable"}`, "run `lecodes app sync`")
+  if (linked && pin !== "latest") {
+    check(linked === pin, `SDK matches app.json ios.sdk (${pin})`, "run `lecodes app sync`")
+  }
+  if (linked) {
+    try {
+      const latest = await fetchLatestSdkVersion(SDK_REPO)
+      check(cmpVersion(linked, latest) >= 0, `SDK is the latest release (${latest})`, "run `lecodes app update`", false)
+    } catch { /* offline — not a preflight failure */ }
+  }
+
+  const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
+  const wanted = Object.keys(config.plugins ?? {})
+  const inSync = wanted.every(id => lock[id]) && Object.keys(lock).every(id => wanted.includes(id))
+  check(wanted.length === 0 || inSync, "Plugins synced", "run `lecodes app sync`")
+
+  // The pbxproj references App/App.entitlements → the file must exist or signing fails.
+  const pbxFile = join(root, "ios", "App.xcodeproj", "project.pbxproj")
+  if (existsSync(pbxFile) && readFileSync(pbxFile, "utf8").includes("CODE_SIGN_ENTITLEMENTS")) {
+    check(existsSync(join(root, "ios", "App", "App.entitlements")), "App/App.entitlements present", "run `lecodes app sync`")
+  }
+
+  // Push registration is identity-gated: the synced runtime must carry the baked uuid
+  // (server-backed project + lecodes-ios-sdk ≥ SDK_IDENTITY_VERSION + a sync since).
+  if (wanted.includes("push")) {
+    const runtimeSwift = join(root, "ios", "LeCodesRuntime", "Sources", "LeCodesRuntime", "LeCodesRuntime.swift")
+    const baked = existsSync(runtimeSwift) && readFileSync(runtimeSwift, "utf8").includes("bootProjectUuid")
+    check(baked, "Push world identity baked",
+      `without it Push.register() rejects "unavailable" — needs a pushed project (uuid), lecodes-ios-sdk ${SDK_IDENTITY_VERSION}+ and \`lecodes app sync\``, false)
+  }
+
+  if (config.update) {
+    const plist = readFileSync(join(root, "ios", "App", "Info.plist"), "utf8")
+    check(plist.includes("<key>LeCodesUpdateURL</key>"), "OTA update URL in Info.plist", "run `lecodes app sync`", false)
+    // The plist key is necessary but not sufficient: the user-owned ViewController must route
+    // the launch through LeCodesUpdater. Shells generated before OTA existed read Bundle.main
+    // directly — downloads land but never run, and sync can't rewrite App/*.swift. Doctor is
+    // the only place that can catch it.
+    const appDir = join(root, "ios", "App")
+    const callsUpdater = readdirSync(appDir).some(f =>
+      f.endsWith(".swift") && readFileSync(join(appDir, f), "utf8").includes("LeCodesUpdater.activeBundle"))
+    check(callsUpdater, "App code launches via LeCodesUpdater",
+      `no App/*.swift calls LeCodesUpdater.activeBundle() — downloaded updates would never run; see "Over-the-air updates" in ios/README.md for the ViewController snippet`, false)
+  }
+
+  const asc = readJson<{ keyPath?: string }>(join(homedir(), ".lecodes", "asc.json"))
+  check(!!asc?.keyPath, "App Store Connect API key configured", "pass --key-path/--key-id/--issuer-id to `lecodes app upload` once to store it", false)
+}
+
+const ARCHIVE_PATH = "ios/build/App.xcarchive"
+
+const appBuild = async (args: Args) => {
+  const platform = args._[1]
+  if (platform === "android") return buildAndroid(args)
+  if (platform === "desktop") return buildDesktop(args)
+  if (platform !== undefined && platform !== "ios") {
+    throw new CliError(`Unknown platform "${platform}" — use ios, android or desktop.`)
+  }
+  const { root, config } = requireShell()
+  const configuration = flagStr(args, "configuration") ?? "Release"
+  const method = flagStr(args, "method") ?? "app-store-connect"
+
+  if (!flagBool(args, "no-sync")) await appSync({ _: ["sync", "ios"], flags: {} })
+
+  note(`Archiving (${configuration})… this takes a few minutes`)
+  runTool(root, "xcodebuild", [
+    "-project", "ios/App.xcodeproj", "-scheme", "App",
+    "-destination", "generic/platform=iOS", "-configuration", configuration,
+    "archive", "-archivePath", ARCHIVE_PATH, "-allowProvisioningUpdates",
+  ])
+  success(`Archive: ios/build/App.xcarchive`)
+
+  if (flagBool(args, "no-export")) return
+  const optionsPath = join(root, "ios", "build", "ExportOptions.plist")
+  writeFileSync(optionsPath, exportOptionsPlist(method, config.ios!.teamId ?? ""))
+  note(`Exporting (.ipa, method ${method})…`)
+  runTool(root, "xcodebuild", [
+    "-exportArchive", "-archivePath", ARCHIVE_PATH,
+    "-exportOptionsPlist", optionsPath, "-exportPath", "ios/build/export",
+    "-allowProvisioningUpdates",
+  ])
+  success("Export: ios/build/export/  — upload with `lecodes app upload ios`")
+}
+
+const appUpload = async (args: Args) => {
+  if (args._[1] === "android") {
+    throw new CliError("Play upload isn't wired yet — upload android/app/build/outputs/bundle/release/*.aab in the Play Console (`lecodes app build android` produces it).")
+  }
+  const { root, config } = requireShell()
+  if (!existsSync(join(root, ARCHIVE_PATH))) {
+    throw new CliError("No archive at ios/build/App.xcarchive — run `lecodes app build ios` first.")
+  }
+
+  // App Store Connect API key: flags on first use, then ~/.lecodes/asc.json.
+  const ascPath = join(homedir(), ".lecodes", "asc.json")
+  const stored = readJson<{ keyPath?: string, keyId?: string, issuerId?: string }>(ascPath) ?? {}
+  const keyPath = flagStr(args, "key-path") ?? stored.keyPath
+  const keyId = flagStr(args, "key-id") ?? stored.keyId
+  const issuerId = flagStr(args, "issuer-id") ?? stored.issuerId
+  if (!keyPath || !keyId || !issuerId) {
+    throw new CliError("App Store Connect API key needed: --key-path <AuthKey.p8> --key-id <id> --issuer-id <id>\n(create one at appstoreconnect.apple.com → Users and Access → Integrations; stored in ~/.lecodes/asc.json after first use)")
+  }
+  if (!existsSync(keyPath)) throw new CliError(`API key file not found: ${keyPath}`)
+  if (flagStr(args, "key-path")) {
+    mkdirSync(dirname(ascPath), { recursive: true })
+    writeJson(ascPath, { keyPath, keyId, issuerId })
+    note("Stored the key reference in ~/.lecodes/asc.json")
+  }
+
+  const optionsPath = join(root, "ios", "build", "UploadOptions.plist")
+  writeFileSync(optionsPath, exportOptionsPlist("app-store-connect", config.ios!.teamId ?? "", "upload"))
+  note("Uploading to App Store Connect… (processing continues on Apple's side)")
+  runTool(root, "xcodebuild", [
+    "-exportArchive", "-archivePath", ARCHIVE_PATH,
+    "-exportOptionsPlist", optionsPath, "-exportPath", "ios/build/upload",
+    "-authenticationKeyPath", resolve(keyPath),
+    "-authenticationKeyID", keyId,
+    "-authenticationKeyIssuerID", issuerId,
+    "-allowProvisioningUpdates",
+  ])
+
+  // A successful upload consumes this build number — bump for the next one.
+  const configPath = join(root, "app.json")
+  const fresh = readJson<AppConfig>(configPath)!
+  fresh.ios!.buildNumber = (fresh.ios!.buildNumber ?? 1) + 1
+  writeJson(configPath, fresh)
+  success(`Uploaded build ${(fresh.ios!.buildNumber ?? 2) - 1} — check App Store Connect / TestFlight once processing finishes.`)
+  note(`ios.buildNumber bumped to ${fresh.ios!.buildNumber} for the next build.`)
+}
+
+/* --------------------------------------- open ---------------------------------------- */
+
+/** `lecodes app open [ios|android]` — open the native shell in its IDE (Xcode / Android
+ *  Studio). No platform: open whichever single shell exists. */
+const appOpen = async (args: Args) => {
+  const root = projectRoot()
+  let platform = args._[1]
+  if (!platform) {
+    const hasIos = existsSync(join(root, "ios"))
+    const hasAndroid = existsSync(join(root, "android"))
+    if (hasIos && hasAndroid) throw new CliError("Both shells exist — `lecodes app open ios` or `lecodes app open android`.")
+    platform = hasAndroid ? "android" : "ios"
+  }
+
+  if (platform === "ios") {
+    const proj = join(root, "ios", "App.xcodeproj")
+    if (!existsSync(proj)) throw new CliError("No iOS shell here — run `lecodes app init ios` first.")
+    if (process.platform !== "darwin") throw new CliError("Opening Xcode requires macOS.")
+    execFileSync("open", [proj], { stdio: "ignore" })
+    success("Opened ios/App.xcodeproj in Xcode.")
+    return
+  }
+  if (platform === "android") return openAndroid()
+  throw new CliError(`Unknown platform "${platform}" — use ios or android.`)
+}
+
+/* --------------------------------------- entry --------------------------------------- */
+
+export const app = async (args: Args) => {
+  const sub = args._[0]
+  if (sub === "init") return appInit(args)
+  if (sub === "sync") return appSync(args)
+  if (sub === "update") return appUpdate(args)
+  if (sub === "plugin") return appPlugin(args)
+  if (sub === "doctor") return appDoctor(args)
+  if (sub === "build") return appBuild(args)
+  if (sub === "upload") return appUpload(args)
+  if (sub === "open") return appOpen(args)
+  throw new CliError("Usage: lecodes app <init ios|android|desktop | sync | update | open | plugin list|add|remove | doctor | build ios|android|desktop | upload ios> — see `lecodes help`.")
+}