lecodes-cli 0.20.2 → 2.0.0

package/src/commands/{app.ts → app/index.ts}

@@ -2,49 +2,57 @@ 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 { readManifest, type Manifest } from "../../project/manifest"
+import { loadConfig, requireApiUrl } from "../../platform/config"
+import { compileShell, type BundleResource } from "../compile"
+import { CliError, UsageError, bool, c, defineCommand, log, note, str, success, warn } from "../../cli"
 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"
+} from "./templates/ios"
 import {
-  FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, detectEngines, ensureShellIgnored,
+  FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, ensureShellIgnored,
   fetchLatestSdkVersion, latestPluginTag, projectRoot, readJson, resolvePlugin, resolveSdkVersion,
   resolveVariant, runTool, slugify, writeJson, VERSION_RE, type AppConfig, type LockEntry,
-} from "./appShared"
+} from "./shared"
 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"
+  ANDROID_SDK_MIN_VERSION, ANDROID_SDK_REPO, androidBuild, doctorAndroidChecks, initAndroid,
+  keystore, openAndroid, shellSdkVersionAndroid, syncAndroid, type SyncArtifacts,
+} from "./android"
+import { desktopBuild, initDesktop } from "./desktop"
+import { loadIconMaster, writeIosAppIcon } from "./icon"
 
 /*
- * `lecodes app` — native app shells for a LeCodes project (docs/xcode-app-plan.md).
+ * `lecodes app` — native app shells for a LeCodes project (docs/xcode-app-plan.md). This file is
+ * the iOS arm plus the command tree; android.ts and desktop.ts hold the other two arms and the
+ * nodes that exist for one platform only (`build android`, `keystore`, `build desktop`).
  *
- *   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 init <ios|android|desktop>  scaffold <project>/ios/ or android/ (Xcode shell + the
+ *                    LeCodesRuntime local package / the Gradle shell) and app.json; the shell dir
+ *                    is added to .lecodesignore (never pushed). The native SDK version is
+ *                    resolved to the latest published release and pinned in app.json ios.sdk /
+ *                    android.sdk (set it to "latest" to re-resolve every sync). `desktop` needs no
+ *                    shell — it writes app.json's desktop block.
  *   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
+ *                    ios/App/Resources/ (resp. the android assets/) + 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 update       move the pins forward: app.json ios.sdk / android.sdk → the newest SDK
+ *                    release, plugins.lock.json → the newest tag of each unpinned plugin, then
+ *                    re-sync. `--check` reports what's available without writing.
  *   app plugin …     list / add / remove plugin entries in app.json.
+ *   app keystore …   Android release signing key: create / use <file> / info (android.ts) —
+ *                    the path + passwords go to the project .env, metadata to app.json.
+ *   app doctor       preflight for building / uploading; app build ios|android|desktop;
+ *   app upload ios   the archive to App Store Connect; app open [ios|android] the IDE.
  *
  * 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
@@ -59,7 +67,6 @@ const SDK_REPO = "letary/lecodes-ios-sdk"
 // 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.
@@ -77,18 +84,26 @@ const shellSdkVersion = (iosDir: string): string | null => {
 
 const IOS_SDK_OPTS = { repo: SDK_REPO, minVersion: SDK_MIN_VERSION, configKey: "ios.sdk" }
 
+/** Which shells a project has: app.json declares the platform AND the shell dir exists. */
+const shellsOf = (root: string, config: AppConfig | null): { hasIos: boolean, hasAndroid: boolean } => ({
+  hasIos: !!config?.ios && existsSync(join(root, "ios")),
+  hasAndroid: !!config?.android && existsSync(join(root, "android")),
+})
+
+/** The `[ios|android]` positional several commands take. */
+const mobilePlatform = (arg: string | undefined): "ios" | "android" | undefined => {
+  if (arg !== undefined && arg !== "ios" && arg !== "android") throw new CliError(`Unknown platform "${arg}" — use ios or android.`)
+  return arg
+}
+
+const NO_IOS_SHELL = "No iOS shell here — run `lecodes app init ios` first."
+const NO_ANDROID_SHELL = "No Android shell here — run `lecodes app init android` first."
+
 /* --------------------------------------- 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>]")
-  }
+interface IosInitOptions { name?: string, bundleId?: string, teamId?: string, variant?: string, sdk?: string }
 
+const initIos = async (opts: IosInitOptions): Promise<void> => {
   const root = projectRoot()
   const iosDir = join(root, "ios")
   if (existsSync(iosDir)) {
@@ -96,7 +111,7 @@ const appInit = async (args: Args) => {
   }
 
   const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
-  const variant = flagStr(args, "variant") ?? existing.ios?.variant ?? "auto"
+  const variant = opts.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}")`)
   }
@@ -104,19 +119,19 @@ const appInit = async (args: Args) => {
   // 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 sdkFlag = opts.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 name = opts.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 ?? "",
+      bundleId: opts.bundleId ?? existing.ios?.bundleId ?? `com.example.${slugify(name)}`,
+      teamId: opts.teamId ?? existing.ios?.teamId ?? "",
       variant,
       sdk,
       buildNumber: existing.ios?.buildNumber ?? 1,
@@ -168,8 +183,32 @@ const appInit = async (args: Args) => {
   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 --------------------------------------- */
+const init = defineCommand({
+  name: "init",
+  summary: "Generate a native shell in <project>/ios/ or <project>/android/, or declare the desktop target",
+  usage: "<ios|android|desktop>",
+  description: "The shell is offline-first (it runs the bundled app.js) and never pushed to LeCodes (the dir goes to .lecodesignore). The native SDK starts on the newest published release, pinned in app.json ios.sdk / android.sdk so builds stay reproducible — `lecodes app update` moves the pin; --sdk latest floats it instead (every sync re-resolves).\n\ndesktop: no shell needed — writes app.json's desktop block (window size; --fullscreen for kiosks). Re-running keeps existing app.json values.",
+  flags: {
+    name: str("display name (default: app.json / the folder name)", { value: "<s>" }),
+    "bundle-id": str("iOS bundle identifier (default com.example.<slug>)", { value: "<id>" }),
+    "app-id": str("Android applicationId (default com.example.<slug>)", { value: "<id>" }),
+    team: str("Apple development team id", { value: "<id>" }),
+    variant: str("SDK variant: auto (default — sync picks the smallest of core/2d/3d/full covering what the bundle uses), or one of those to pin", { value: "<v>" }),
+    sdk: str("native SDK release (default: the newest one, pinned in app.json); 'latest' floats it — every sync re-resolves", { value: "<v|latest>" }),
+    fullscreen: bool("(desktop) borderless fullscreen on the primary monitor — kiosks"),
+  },
+  examples: ["lecodes app init ios --team ABCDE12345", "lecodes app init android --app-id com.acme.game", "lecodes app init desktop --fullscreen"],
+  run: ({ args, flags }) => {
+    const platform = args[0]
+    if (platform === "android") return initAndroid({ name: flags.name, appId: flags["app-id"], variant: flags.variant, sdk: flags.sdk })
+    if (platform === "desktop") return initDesktop({ name: flags.name, fullscreen: flags.fullscreen })
+    if (platform === "ios") return initIos({ name: flags.name, bundleId: flags["bundle-id"], teamId: flags.team, variant: flags.variant, sdk: flags.sdk })
+    if (platform) throw new CliError(`Unsupported platform "${platform}" — use ios, android or desktop.`)
+    throw new UsageError("Which platform? `lecodes app init <ios|android|desktop>`")
+  },
+})
 
+/* --------------------------------------- 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
@@ -218,21 +257,15 @@ const resolveUpdateUrl = (update: AppConfig["update"], root: string): string | u
 
 /** `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) => {
+ *  the byte-identical output. `app update` and `app build ios` run it too. */
+export const runSync = async (platformArg?: string): Promise<void> => {
   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.")
-  }
+  const platform = mobilePlatform(platformArg)
+  const { hasIos, hasAndroid } = shellsOf(root, config)
+  if (platform === "ios" && !hasIos) throw new CliError(NO_IOS_SHELL)
+  if (platform === "android" && !hasAndroid) throw new CliError(NO_ANDROID_SHELL)
+  if (!platform && !hasIos && !hasAndroid) throw new CliError(NO_IOS_SHELL)
 
   let iosArtifacts: SyncArtifacts | null = null
   if (hasIos && platform !== "android") iosArtifacts = await syncIos(root, config!)
@@ -241,7 +274,7 @@ const appSync = async (args: Args) => {
 
 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.")
+  if (!config.ios) throw new CliError(NO_IOS_SHELL)
   // 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"
@@ -318,7 +351,7 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   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 })
+  const resources = await compileShell(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")
@@ -346,7 +379,9 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   // 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
+  // engine-synthesized, not project files: the ubershader archive, the capture flag and the
+  // engine's own materials (`material:<name>` — they ride the SDK)
+  const IMPLICIT_PRELOADS = { has: (name: string) => name === "uberarchive" || name === "capture" || name.startsWith("material:") }
   const byName = new Map<string, BundleResource[]>()
   for (const r of resources) {
     if (r.remote || !r.absPath) continue
@@ -456,99 +491,95 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   return { bundleJs, resources }
 }
 
+const sync = defineCommand({
+  name: "sync",
+  summary: "Make every existing shell match the project: bundle + assets + SDK variant + plugins + CLI-owned files",
+  usage: "[ios|android]",
+  description: "Compiles the bundle and embeds the assets it references (ios/App/Resources/ resp. the android assets/; offline by default, also for server projects — app.json \"resources\": {\"remote\": [globs]} keeps heavy assets streaming), picks the SDK variant from the bundle's engine use, vendors the app.json plugins (pinned in plugins.lock.json) and regenerates the CLI-owned shell files. User files (ios/App/*.swift, android/app/) are never touched.\n\napp.json \"update\": true (or {\"url\": …}) enables native OTA JS updates at launch (iOS). app.json \"icon\" (a square ≥1024px image) renders the app icons every sync (\"iconBackground\": the adaptive / flatten backdrop). No platform = every shell that exists; a dual-shell project compiles once.",
+  examples: ["lecodes app sync", "lecodes app sync android"],
+  run: ({ args }) => runSync(args[0]),
+})
+
 /* -------------------------------------- plugin -------------------------------------- */
 
-const appPlugin = async (args: Args) => {
-  const sub = args._[1]
+const pluginConfig = (): { root: string, configPath: string, config: AppConfig & { plugins: Record<string, string> } } => {
   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 ??= {}
+  return { root, configPath, config: config as AppConfig & { plugins: Record<string, string> } }
+}
 
-  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
+const pluginList = (): void => {
+  const { root, config } = pluginConfig()
+  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}`)
   }
+}
 
-  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
+const pluginAdd = (id: string | undefined): void => {
+  if (!id) throw new UsageError("Which plugin? `lecodes app plugin add <id | github:owner/repo[@tag]>`")
+  const { configPath, config } = pluginConfig()
+  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].`)
   }
-
-  throw new CliError(`Unknown subcommand "plugin ${sub}" — use list, add or remove.`)
+  writeJson(configPath, config)
+  note("Run `lecodes app sync` to vendor it into the shell.")
 }
 
-/* ---------------------------------- 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 }
+const pluginRemove = (id: string | undefined): void => {
+  if (!id) throw new UsageError("Which plugin? `lecodes app plugin remove <id>`")
+  const { configPath, config } = pluginConfig()
+  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.")
 }
 
+const plugin = defineCommand({
+  name: "plugin",
+  summary: "Manage native plugins in app.json: list | add | remove (then run `lecodes app sync`)",
+  description: `Bare \`lecodes app plugin\` lists them with their plugins.lock.json pins. \`add\` takes a first-party id (${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}) or github:owner/repo[@tag] for a third-party plugin (native code — review it before shipping). Nothing reaches the shell until the next sync.`,
+  commands: [
+    defineCommand({ name: "list", summary: "The plugins in app.json and their lock pins", run: () => pluginList() }),
+    defineCommand({
+      name: "add",
+      summary: "Add a plugin: a known id, or github:owner/repo[@tag]",
+      usage: "<id | github:owner/repo[@tag]>",
+      examples: ["lecodes app plugin add camera", "lecodes app plugin add github:acme/lecodes-plugin-thing@v1.2.0"],
+      run: ({ args }) => pluginAdd(args[0]),
+    }),
+    defineCommand({ name: "remove", summary: "Remove a plugin entry", usage: "<id>", run: ({ args }) => pluginRemove(args[0]) }),
+  ],
+  run: () => pluginList(),
+})
+
 /* -------------------------------------- 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,
+  root: string, config: AppConfig, wanted: string | undefined, 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.
@@ -583,41 +614,40 @@ const updateSdkPin = async (
   return changed
 }
 
+export interface AppUpdateOptions { platform?: string, sdk?: string, check?: boolean, noPlugins?: boolean, noSync?: boolean }
+
 /** `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) => {
+ *  the shell actually carries the new versions — `--check` reports and writes nothing.
+ *  `lecodes update` runs it as its shells step. */
+export const runAppUpdate = async (opts: AppUpdateOptions = {}): Promise<void> => {
   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 platform = mobilePlatform(opts.platform)
+  const { hasIos, hasAndroid } = shellsOf(root, config)
+  if (platform === "ios" && !hasIos) throw new CliError(NO_IOS_SHELL)
+  if (platform === "android" && !hasAndroid) throw new CliError(NO_ANDROID_SHELL)
+  if (!hasIos && !hasAndroid) throw new CliError(NO_IOS_SHELL)
   const doIos = hasIos && platform !== "android"
   const doAndroid = hasAndroid && platform !== "ios"
-  if (flagStr(args, "sdk") && doIos && doAndroid) {
+  if (opts.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")
+  const checkOnly = !!opts.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
+  if (doIos) changed = (await updateSdkPin(root, config!, opts.sdk, checkOnly, "ios")) || changed
+  if (doAndroid) changed = (await updateSdkPin(root, config!, opts.sdk, 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")) {
+  if (specs.length > 0 && !opts.noPlugins) {
     const kept: Record<string, LockEntry> = {}
     for (const [id, spec] of specs) {
       const entry = lock[id]
@@ -650,50 +680,33 @@ const appUpdate = async (args: Args) => {
     return
   }
   if (!changed) { success("Already up to date."); return }
-  if (flagBool(args, "no-sync")) {
+  if (opts.noSync) {
     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.")
+  await runSync(platform)
 }
 
-const doctorIosChecks = async (
-  root: string, config: AppConfig,
-  check: (ok: boolean, label: string, hint?: string, fatal?: boolean) => void,
-) => {
+const update = defineCommand({
+  name: "update",
+  summary: "Move the shell's pins forward (SDK release + plugin tags), then re-sync",
+  usage: "[ios|android]",
+  description: "app.json ios.sdk / android.sdk → the newest published SDK release, plugins.lock.json → each plugin's newest tag (a github:owner/repo@tag spec is a deliberate pin and is left alone), then `lecodes app sync` so the shell carries the new versions. `lecodes update` runs this as its shells step.",
+  flags: {
+    sdk: str("pin that release instead of the newest one; 'latest' floats the pin", { value: "<v|latest>" }),
+    check: bool("report available updates, write nothing"),
+    "no-plugins": bool("only move the SDK pin"),
+    "no-sync": bool("update the pins without re-syncing"),
+  },
+  examples: ["lecodes app update", "lecodes app update --check", "lecodes app update ios --sdk 1.6.0"],
+  run: ({ args, flags }) => runAppUpdate({ platform: args[0], sdk: flags.sdk, check: flags.check, noPlugins: flags["no-plugins"], noSync: flags["no-sync"] }),
+})
+
+/* -------------------------------------- doctor --------------------------------------- */
+
+type Check = (ok: boolean, label: string, hint?: string, fatal?: boolean) => void
+
+const doctorIosChecks = async (root: string, config: AppConfig, check: Check) => {
   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")
@@ -773,124 +786,221 @@ const doctorIosChecks = async (
   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 doctor = defineCommand({
+  name: "doctor",
+  summary: "Preflight checks for building / uploading the shells",
+  description: "Toolchain (Xcode / JDK + Android SDK), the synced bundle, SDK variant + version vs app.json, plugin lock, signing (team id / release keystore), icons, OTA wiring and the App Store Connect key. Fatal checks fail the command (exit 1); soft ones print a `!` and a hint.",
+  examples: ["lecodes app doctor"],
+  run: async () => {
+    const root = projectRoot()
+    const config = readJson<AppConfig>(join(root, "app.json"))
+    const { hasIos, hasAndroid } = shellsOf(root, config)
+    if (!hasIos && !hasAndroid) throw new CliError(NO_IOS_SHELL)
+    let failed = 0
+    const check: Check = (ok, label, hint = "", fatal = true) => {
+      log(`${ok ? c.green("✓") : (fatal ? c.red("✗") : c.yellow("!"))} ${label}${ok || !hint ? "" : c.dim("  — " + hint)}`)
+      if (!ok && fatal) failed++
+    }
 
-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`")
-}
+    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`")
+      }
+    }
 
-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.`)
-}
+    log("")
+    if (failed > 0) throw new CliError(`${failed} check(s) failed.`)
+    success("Ready to build.")
+  },
+})
 
-/* --------------------------------------- open ---------------------------------------- */
+/* ---------------------------------- 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>
+`
 
-/** `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 requireShell = (): { root: string, config: AppConfig } => {
   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.`)
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  if (!config?.ios || !existsSync(join(root, "ios"))) throw new CliError(NO_IOS_SHELL)
+  return { root, config }
 }
 
+const ARCHIVE_PATH = "ios/build/App.xcarchive"
+
+const iosBuild = defineCommand({
+  name: "ios",
+  summary: "Sync, archive and export the .ipa (automatic signing)",
+  description: "xcodebuild archive of ios/App.xcodeproj (generic iOS device, -allowProvisioningUpdates) into ios/build/App.xcarchive, then an export with the method given — the .ipa lands in ios/build/export/. `lecodes app upload ios` sends the archive to App Store Connect.",
+  flags: {
+    configuration: str("build configuration", { value: "<c>", default: "Release" }),
+    method: str("export method", { value: "<m>", default: "app-store-connect" }),
+    "no-export": bool("stop after the archive"),
+    "no-sync": bool("skip the `lecodes app sync` step"),
+  },
+  examples: ["lecodes app build ios", "lecodes app build ios --method ad-hoc"],
+  run: async ({ flags }) => {
+    const { root, config } = requireShell()
+    const configuration = flags.configuration
+    const method = flags.method
+
+    if (!flags["no-sync"]) await runSync("ios")
+
+    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 (flags["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 build = defineCommand({
+  name: "build",
+  summary: "Build a shippable artifact: ios (.ipa) | android (.apk/.aab) | desktop (portable folder / .app)",
+  // The desktop node is `lecodes desktop build` verbatim (same flags, same run); only its name
+  // differs here, where the platform is the word after `build`.
+  commands: [iosBuild, androidBuild, { ...desktopBuild, name: "desktop" }],
+})
+
+const iosUpload = defineCommand({
+  name: "ios",
+  summary: "Upload the archive to App Store Connect (then bumps ios.buildNumber)",
+  description: "Exports ios/build/App.xcarchive with destination `upload` through xcodebuild, authenticated with an App Store Connect API key: the three flags on first use, then ~/.lecodes/asc.json remembers them. A successful upload consumes the build number, so app.json ios.buildNumber is bumped for the next build.",
+  flags: {
+    "key-path": str("App Store Connect API key (AuthKey_XXXX.p8)", { value: "<p8>" }),
+    "key-id": str("the key's id", { value: "<id>" }),
+    "issuer-id": str("the key's issuer id", { value: "<id>" }),
+  },
+  examples: ["lecodes app upload ios --key-path ~/AuthKey_ABC123.p8 --key-id ABC123 --issuer-id 1234-…", "lecodes app upload ios"],
+  run: ({ flags }) => {
+    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 = flags["key-path"] ?? stored.keyPath
+    const keyId = flags["key-id"] ?? stored.keyId
+    const issuerId = flags["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 (flags["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.`)
+  },
+})
+
+const upload = defineCommand({
+  name: "upload",
+  summary: "Upload a build to the store: ios (App Store Connect)",
+  commands: [
+    iosUpload,
+    // Not wired yet — kept as a node so `app upload android` says what to do instead of "unknown command".
+    defineCommand({
+      name: "android",
+      summary: "Play upload (not wired yet)",
+      hidden: true,
+      run: () => { 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).") },
+    }),
+  ],
+})
+
+/* --------------------------------------- open ---------------------------------------- */
+
+const open = defineCommand({
+  name: "open",
+  summary: "Open the native shell in its IDE (Xcode / Android Studio)",
+  usage: "[ios|android]",
+  description: "No platform: opens whichever single shell exists. Xcode needs macOS; Android Studio is looked up in its default install locations (or `studio` on the PATH).",
+  examples: ["lecodes app open", "lecodes app open android"],
+  run: async ({ args }) => {
+    const root = projectRoot()
+    let platform = args[0]
+    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)
+      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`.")
-}
+export default defineCommand({
+  name: "app",
+  summary: "Native apps: iOS / Android shells and the portable desktop build (init, sync, update, build, upload)",
+  description: "A shell is a generated Xcode / Gradle project in <project>/ios/ or android/ that runs the compiled bundle offline; `sync` keeps it matching the project, `build` and `upload` ship it. The desktop target needs no shell — `build desktop` stages the host + bundle into a portable folder (a signed .app on macOS). app.json carries the identity, versions, plugins, icon and per-platform settings.",
+  commands: [init, sync, update, plugin, open, doctor, build, keystore, upload],
+})