lecodes-cli 0.18.2 → 0.19.2

package/src/commands/appAndroid.ts

@@ -0,0 +1,603 @@
+import { execFileSync, spawn, spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, dirname, join } from "node:path"
+import { readManifest } from "../manifest"
+import { compileShell, type BundleResource } from "./compile"
+import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+import {
+  type AppConfig, SDK_VARIANTS, VERSION_RE, cmpVersion, ensureShellIgnored, fetchLatestSdkVersion,
+  projectRoot, readJson, resolvePlugin, resolveSdkVersion, resolveVariant, runTool, slugify,
+  writeJson, type LockEntry,
+} from "./appShared"
+import { loadIconMaster, restampManifestIcon, writeAndroidIcons } from "./appIcon"
+import {
+  ANDROID_GITIGNORE, ANDROID_README, COLORS_XML, GRADLE_PROPERTIES, GRADLE_VERSION,
+  GRADLE_PLUGIN_VERSIONS, IC_LAUNCHER_XML, aarWrapperBuildGradle, appBuildGradleTemplate,
+  appManifestTemplate, appViewModelTemplate, gradleWrapperProperties, mainActivityTemplate,
+  pluginBuildGradleTemplate, rootBuildGradleTemplate, runtimeBuildGradleTemplate,
+  runtimeKotlinTemplate, settingsGradleTemplate, stringsXmlTemplate, themesXmlTemplate,
+  type AndroidRuntimePlugin, type AndroidShellIdentity,
+} from "./appTemplatesAndroid"
+import { GRADLEW_BAT, GRADLEW_SH } from "./appTemplatesGradlew"
+import { type SdkVariant } from "./appTemplates"
+
+/* The Android arm of `lecodes app` — the mirror of the iOS flows in app.ts, over Gradle
+ * instead of Xcode. Same ownership contract (see appTemplatesAndroid.ts); the SDK is the
+ * lecodes-android fat AAR published as GitHub Release assets on the dist repo below and
+ * resolved by Gradle through an ivy repository over the release-download URL pattern. */
+
+export const ANDROID_SDK_REPO = "letary/lecodes-android-sdk"
+
+/** Oldest lecodes-android-sdk a generated shell can use — 1.2.0 moved system-back wiring into
+ *  engine.attach() and the template dropped its own dispatcher block, so an older SDK under
+ *  this template would leave the back button dead. */
+export const ANDROID_SDK_MIN_VERSION = "1.2.0"
+
+/** First lecodes-android-sdk release that publishes the variant matrix (lecodes-sdk-3d / -2d /
+ *  -core next to the full lecodes-sdk asset). Older pins always link the full artifact. */
+export const ANDROID_SDK_VARIANTS_MIN = "1.3.0"
+
+/** Release-asset / ivy artifact name for an SDK variant — full keeps the historic plain name so
+ *  pre-variant pins and shells keep resolving. */
+const variantArtifact = (variant: SdkVariant): string =>
+  variant === "full" ? "lecodes-sdk" : `lecodes-sdk-${variant}`
+
+const ANDROID_SDK_URL_DEFAULT = `https://github.com/${ANDROID_SDK_REPO}/releases/download`
+
+/** The ivy base URL shells resolve the SDK AAR from. `LECODES_ANDROID_SDK_URL` overrides for
+ *  the pre-publish dev loop (serve a staged AAR from a local static server). */
+const sdkRepoUrl = () => process.env.LECODES_ANDROID_SDK_URL ?? ANDROID_SDK_URL_DEFAULT
+
+export const ANDROID_SDK_OPTS = { repo: ANDROID_SDK_REPO, minVersion: ANDROID_SDK_MIN_VERSION, configKey: "android.sdk" }
+
+/** The SDK version a synced shell currently links — the CLI-owned runtime build file's pin is
+ *  the truth (the offline fallback, like Package.swift on iOS). */
+export const shellSdkVersionAndroid = (androidDir: string): string | null => {
+  const path = join(androidDir, "lecodes-runtime", "build.gradle.kts")
+  if (!existsSync(path)) return null
+  const m = /io\.letary:lecodes-sdk(?:-(?:core|2d|3d))?:(\d+\.\d+\.\d+)@aar/.exec(readFileSync(path, "utf8"))
+  return m ? m[1] : null
+}
+
+/* ------------------------------------ gradle wrapper ------------------------------------ */
+
+// The wrapper LAUNCHER jar (version-agnostic — the real distribution comes from
+// gradle-wrapper.properties), pinned to the gradle/gradle v8.13.0 tag and hash-verified.
+const GRADLE_WRAPPER_JAR_URL = "https://raw.githubusercontent.com/gradle/gradle/v8.13.0/gradle/wrapper/gradle-wrapper.jar"
+const GRADLE_WRAPPER_JAR_SHA256 = "81a82aaea5abcc8ff68b3dfcb58b3c3c429378efd98e7433460610fecd7ae45f"
+
+/** Fetch-and-cache gradle-wrapper.jar (~/.lecodes/gradle-wrapper/<ver>/). Null on failure —
+ *  init degrades with a warning instead of failing (Android Studio can repair a missing jar). */
+const ensureGradleWrapperJar = async (): Promise<Uint8Array | null> => {
+  const cached = join(homedir(), ".lecodes", "gradle-wrapper", GRADLE_VERSION, "gradle-wrapper.jar")
+  if (existsSync(cached)) return new Uint8Array(readFileSync(cached))
+  try {
+    const res = await fetch(GRADLE_WRAPPER_JAR_URL)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    const hash = createHash("sha256").update(bytes).digest("hex")
+    if (hash !== GRADLE_WRAPPER_JAR_SHA256) throw new Error(`sha256 mismatch (${hash})`)
+    mkdirSync(dirname(cached), { recursive: true })
+    writeFileSync(cached, bytes)
+    return bytes
+  } catch (e) {
+    warn(`Could not fetch gradle-wrapper.jar (${(e as Error).message}) — run \`gradle wrapper --gradle-version ${GRADLE_VERSION}\` inside android/, or open the project in Android Studio (it offers to repair the wrapper).`)
+    return null
+  }
+}
+
+/** Windows file locks (Android Studio's daemon) make first-try rmdir flaky — retry. */
+const rmrf = (path: string) => rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 })
+
+/* ---------------------------------------- init ---------------------------------------- */
+
+export const initAndroid = async (args: Args) => {
+  const root = projectRoot()
+  const androidDir = join(root, "android")
+  if (existsSync(androidDir)) {
+    throw new CliError("android/ already exists — run `lecodes app sync` to update it.")
+  }
+
+  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+
+  const variant = flagStr(args, "variant") ?? existing.android?.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.android?.sdk
+  const sdkVersion = await resolveSdkVersion(process.env.LECODES_ANDROID_SDK ?? sdkFlag ?? "latest", null, ANDROID_SDK_OPTS)
+  const sdk = sdkFlag === "latest" ? "latest" : sdkVersion
+
+  const name = flagStr(args, "name") ?? existing.name ?? basename(root)
+  // Dashes are legal in a slug but not in a Java package — strip them for the default id.
+  const defaultAppId = `com.example.${slugify(name).replace(/-/g, "")}`
+  const config: AppConfig = {
+    ...existing,
+    name,
+    version: existing.version ?? "1.0.0",
+    plugins: existing.plugins ?? {},
+    android: {
+      applicationId: flagStr(args, "app-id") ?? existing.android?.applicationId ?? defaultAppId,
+      versionCode: existing.android?.versionCode ?? 1,
+      sdk,
+      variant,
+      ...(existing.android?.signing ? { signing: existing.android.signing } : {}),
+    },
+  }
+  writeJson(join(root, "app.json"), config)
+  log(`${c.green("written")}   app.json`)
+
+  // Never push the shell to the platform.
+  ensureShellIgnored(root, "android")
+
+  const identity: AndroidShellIdentity = {
+    displayName: name,
+    applicationId: config.android!.applicationId!,
+    version: config.version!,
+    versionCode: config.android!.versionCode!,
+  }
+  const pkgPath = identity.applicationId.replace(/\./g, "/")
+
+  const write = (rel: string, content: string | Uint8Array) => {
+    const abs = join(androidDir, rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+    log(`${c.green("created")}   android/${rel}`)
+  }
+
+  write("README.md", ANDROID_README)
+  write(".gitignore", ANDROID_GITIGNORE)
+  write("settings.gradle.kts", settingsGradleTemplate(slugify(name), [], [], sdkRepoUrl()))
+  write("build.gradle.kts", rootBuildGradleTemplate([]))
+  write("gradle.properties", GRADLE_PROPERTIES)
+  write("gradle/wrapper/gradle-wrapper.properties", gradleWrapperProperties())
+  // gradlew LF / gradlew.bat CRLF — load-bearing for sh resp. cmd.
+  write("gradlew", GRADLEW_SH)
+  write("gradlew.bat", GRADLEW_BAT.replace(/\n/g, "\r\n"))
+  if (process.platform !== "win32") chmodSync(join(androidDir, "gradlew"), 0o755)
+  const wrapperJar = await ensureGradleWrapperJar()
+  if (wrapperJar) write("gradle/wrapper/gradle-wrapper.jar", wrapperJar)
+
+  write("app/build.gradle.kts", appBuildGradleTemplate(identity))
+  write("app/src/main/AndroidManifest.xml", appManifestTemplate())
+  write(`app/src/main/java/${pkgPath}/MainActivity.kt`, mainActivityTemplate(identity.applicationId))
+  write(`app/src/main/java/${pkgPath}/AppViewModel.kt`, appViewModelTemplate(identity.applicationId))
+  write("app/src/main/res/values/themes.xml", themesXmlTemplate())
+  write("app/src/main/res/values/colors.xml", COLORS_XML)
+  write("app/src/main/res/values/strings.xml", stringsXmlTemplate(name))
+  write("app/src/main/res/drawable/ic_launcher.xml", IC_LAUNCHER_XML)
+  // Like iOS init: no compiled bundle yet, so an "auto" variant starts on core — the first sync
+  // re-resolves from what the bundle actually uses. Pre-variant SDK pins get the full AAR.
+  const initVariant: SdkVariant = variant === "auto" ? "core" : variant as SdkVariant
+  const initArtifact = cmpVersion(sdkVersion, ANDROID_SDK_VARIANTS_MIN) >= 0 ? variantArtifact(initVariant) : "lecodes-sdk"
+  write("lecodes-runtime/build.gradle.kts", runtimeBuildGradleTemplate(sdkVersion, [], initArtifact))
+  write("lecodes-runtime/src/main/kotlin/io/letary/lecodes/runtime/LeCodesRuntime.kt", runtimeKotlinTemplate([]))
+
+  log("")
+  log(`${c.green("sdk")}       lecodes-android-sdk ${sdkVersion}${sdk === "latest" ? c.dim("  (android.sdk: latest — re-resolved on every sync)") : c.dim("  (pinned in app.json android.sdk — `lecodes app update` moves it)")}`)
+  success(`Android shell for ${c.bold(name)} ready.`)
+  log(`  ${c.bold("lecodes app sync")}            embed the compiled bundle (+ plugins) into the shell`)
+  log(`  ${c.bold("lecodes app open android")}    then run on your device from Android Studio`)
+  log(`  App icon: set app.json "icon" to a square ≥1024px image — sync renders every size (or use Android Studio → Image Asset)`)
+}
+
+/* ---------------------------------------- sync ---------------------------------------- */
+
+export interface SyncArtifacts { bundleJs: string, resources: BundleResource[] }
+
+/** One manifest gradlePlugins entry → { id, version } via the known-version table
+ *  (bare id) or an explicit "<id>:<version>" pin. */
+const resolveGradlePlugin = (pluginId: string, entry: string): { id: string, version: string } => {
+  const at = entry.lastIndexOf(":")
+  if (at > 0 && VERSION_RE.test(entry.slice(at + 1))) {
+    return { id: entry.slice(0, at), version: entry.slice(at + 1) }
+  }
+  const version = GRADLE_PLUGIN_VERSIONS[entry]
+  if (!version) {
+    throw new CliError(`Plugin "${pluginId}" requests unknown Gradle plugin "${entry}" — pin it as "<id>:<version>" in the manifest.`)
+  }
+  return { id: entry, version }
+}
+
+export const syncAndroid = async (root: string, config: AppConfig, prior: SyncArtifacts | null): Promise<void> => {
+  const androidDir = join(root, "android")
+
+  // The native SDK release this shell links: app.json android.sdk, or whatever the runtime
+  // build file already names, so a routine sync never moves a shell's SDK on its own.
+  const linkedSdk = shellSdkVersionAndroid(androidDir)
+  const sdkPin = process.env.LECODES_ANDROID_SDK ?? config.android?.sdk ?? linkedSdk ?? "latest"
+  const sdkVersion = await resolveSdkVersion(sdkPin, linkedSdk, ANDROID_SDK_OPTS)
+
+  // ---- bundle: compiled FIRST (into assets/, the one CLI-owned dir inside app/) — the SDK
+  // variant is read from its header, and the plugin build files generated below must pin the
+  // same SDK artifact as lecodes-runtime (two variant coordinates in one shell would put two
+  // copies of the SDK classes on the runtime classpath) ----
+  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 assetsDir = join(androidDir, "app", "src", "main", "assets")
+  rmrf(assetsDir)
+  mkdirSync(assetsDir, { recursive: true })
+  let bundleJs: string
+  let resources: BundleResource[]
+  if (prior) {
+    // The iOS pass of this same sync already compiled — reuse byte-identical output.
+    writeFileSync(join(assetsDir, "app.js"), prior.bundleJs)
+    bundleJs = prior.bundleJs
+    resources = prior.resources
+  } else {
+    resources = await compileShell({ _: [], flags: { o: join(assetsDir, "app.js") } }, { remotePatterns })
+    bundleJs = readFileSync(join(assetsDir, "app.js"), "utf8")
+  }
+
+  // ---- variant: the smallest SDK artifact covering what the bundle uses (or the forced one) ----
+  const requestedVariant = config.android?.variant ?? "auto"
+  if (requestedVariant !== "auto" && !SDK_VARIANTS.includes(requestedVariant as SdkVariant)) {
+    throw new CliError(`app.json android.variant must be "auto" or one of ${SDK_VARIANTS.join(", ")} (got "${requestedVariant}").`)
+  }
+  const { variant, detected } = resolveVariant(requestedVariant, bundleJs, "android.variant")
+  let sdkArtifact = variantArtifact(variant)
+  if (sdkArtifact !== "lecodes-sdk" && cmpVersion(sdkVersion, ANDROID_SDK_VARIANTS_MIN) < 0) {
+    warn(`lecodes-android-sdk ${sdkVersion} predates the variant matrix (${ANDROID_SDK_VARIANTS_MIN}) — linking the full lecodes-sdk AAR; run \`lecodes app update\` to pick up variant builds.`)
+    sdkArtifact = "lecodes-sdk"
+  }
+  const WHY: Record<SdkVariant, string> = {
+    full: "3D + 2D engines in use", "3d": "3D in use, no 2D", "2d": "2D in use, no 3D", core: "no 3D/2D engine use detected",
+  }
+  log(`${c.green("variant")}   ${variant} → ${sdkArtifact}${requestedVariant === "auto" ? c.dim(`  (auto: ${WHY[detected]})`) : c.dim("  (forced by android.variant)")}`)
+
+  // ---- plugins: vendor sources as Gradle modules, generate their build files, 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: AndroidRuntimePlugin[] = []
+  const gradlePlugins = new Map<string, string>()          // id → version
+  const aarWrapperPaths: string[] = []                     // ":plugins:<module>:libs:<name>"
+  const newLock: Record<string, LockEntry> = {}
+
+  const pluginsDir = join(androidDir, "plugins")
+  for (const [id, spec] of pluginSpecs) {
+    const plugin = resolvePlugin(id, spec, oldLock[id], "android")
+    const android = plugin.manifest.android!
+    const module = android.module
+    const register = android.register
+    if (!module || !register) throw new CliError(`Plugin "${id}": manifest android.module / android.register missing`)
+
+    const src = join(plugin.dir, android.sources ?? "android")
+    if (!existsSync(src)) throw new CliError(`Plugin "${id}": sources dir ${src} missing`)
+    const dest = join(pluginsDir, module)
+    rmrf(dest)
+    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 (android.minSdk && VERSION_RE.test(android.minSdk) && cmpVersion(sdkVersion, android.minSdk) < 0) {
+      throw new CliError(`Plugin "${id}" needs lecodes-android-sdk ${android.minSdk} but the shell links ${sdkVersion} — run \`lecodes app update\` (or set app.json android.sdk).`)
+    }
+    for (const entry of android.gradlePlugins ?? []) {
+      const resolved = resolveGradlePlugin(id, entry)
+      gradlePlugins.set(resolved.id, resolved.version)
+    }
+
+    // The generated module build file: namespace from the register FQN's package, local AARs
+    // and consumer rules by convention, Maven deps from the manifest. Each local AAR moves
+    // into a generated wrapper module (AGP forbids direct local .aar file deps in libraries).
+    const namespace = register.split(".").slice(0, -1).join(".")
+    const libsDir = join(dest, "libs")
+    const aarNames = existsSync(libsDir) ? readdirSync(libsDir).filter(f => f.endsWith(".aar")) : []
+    for (const aar of aarNames) {
+      const base = aar.replace(/\.aar$/, "")
+      const wrapDir = join(libsDir, base)
+      mkdirSync(wrapDir, { recursive: true })
+      renameSync(join(libsDir, aar), join(wrapDir, aar))
+      writeFileSync(join(wrapDir, "build.gradle.kts"), aarWrapperBuildGradle(aar))
+      aarWrapperPaths.push(`:plugins:${module}:libs:${base}`)
+    }
+    const hasConsumerRules = existsSync(join(dest, "consumer-rules.pro"))
+    writeFileSync(join(dest, "build.gradle.kts"),
+      pluginBuildGradleTemplate(id, module, namespace, sdkVersion, android.dependencies ?? [], aarNames, hasConsumerRules, sdkArtifact))
+
+    runtimePlugins.push({ id, module, register })
+    newLock[id] = plugin.lock
+    log(`${c.green("plugin")}    ${id}@${plugin.lock.version} (${plugin.lock.tag} → plugins/${module})`)
+  }
+
+  // Remove modules of uninstalled plugins.
+  const keep = new Set(runtimePlugins.map(p => p.module))
+  for (const entry of existsSync(pluginsDir) ? readdirSync(pluginsDir) : []) {
+    if (!keep.has(entry) && statSync(join(pluginsDir, entry)).isDirectory()) {
+      rmrf(join(pluginsDir, entry))
+      log(`${c.yellow("removed")}   android/plugins/${entry}  (plugin uninstalled)`)
+    }
+  }
+
+  const sdkWhy = sdkPin === "latest" ? "latest" : config.android?.sdk ? "pinned by android.sdk" : "from the shell — set android.sdk or run `lecodes app update`"
+  log(`${c.green("sdk")}       lecodes-android-sdk ${sdkVersion}${c.dim(`  (${sdkWhy})`)}`)
+
+  // Embed exactly what the bundle resolves locally (the `// preload:` header), flat by lookup
+  // name — the host reads assets/ by basename. Unlike iOS there is no separate SDK resources
+  // bundle to download: engine assets ride inside the variant AAR itself (GL-less variants
+  // simply ship without the Filament assets).
+  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) {
+      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(assetsDir, name))
+    embedded++
+  }
+  if (embedded > 0) log(`${c.green("assets")}    ${embedded} file(s) embedded → android/app/src/main/assets/`)
+  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: bake the project uuid as world identity (every published
+  // lecodes-android-sdk release carries bootProjectUuid — no version gate needed) ----
+  let shellUuid: string | undefined
+  try { shellUuid = readManifest(root).uuid } catch { /* local-only project — unattributed */ }
+  if (shellUuid) log(`${c.green("identity")}  project ${shellUuid} baked into the shell (world identity)`)
+
+  // ---- regenerate the CLI-owned files ----
+  const modules = runtimePlugins.map(p => p.module)
+  writeFileSync(join(androidDir, "README.md"), ANDROID_README)
+  writeFileSync(join(androidDir, "settings.gradle.kts"), settingsGradleTemplate(slugify(config.name ?? basename(root)), modules, aarWrapperPaths, sdkRepoUrl()))
+  writeFileSync(join(androidDir, "build.gradle.kts"), rootBuildGradleTemplate([...gradlePlugins].map(([id, version]) => ({ id, version }))))
+  writeFileSync(join(androidDir, "gradle.properties"), GRADLE_PROPERTIES)
+  writeFileSync(join(androidDir, "lecodes-runtime", "build.gradle.kts"), runtimeBuildGradleTemplate(sdkVersion, modules, sdkArtifact))
+  const runtimeKt = join(androidDir, "lecodes-runtime", "src", "main", "kotlin", "io", "letary", "lecodes", "runtime", "LeCodesRuntime.kt")
+  mkdirSync(dirname(runtimeKt), { recursive: true })
+  writeFileSync(runtimeKt, runtimeKotlinTemplate(runtimePlugins, shellUuid))
+
+  if (pluginSpecs.length > 0 || existsSync(lockPath)) writeJson(lockPath, { plugins: newLock })
+
+  // ---- user-file touch-ups (app/build.gradle.kts is USER-owned): values-only version
+  // restamps + the `// lecodes:plugin`-tagged Gradle-plugin lines ----
+  restampAppBuildGradle(androidDir, config, gradlePlugins)
+
+  // ---- icons: rendered from app.json "icon" when set (a CLI-owned carve-out inside the
+  // user-owned res/, like assets/) — absent, hand-made icons stay untouched ----
+  if (config.icon) {
+    await writeAndroidIcons(androidDir, await loadIconMaster(root, config))
+    restampManifestIcon(androidDir)
+  }
+
+  // ---- OTA: not on Android yet ----
+  if (config.update) {
+    note(`app.json "update" is iOS-only for now — the Android runtime has no native updater, so it's ignored for this shell.`)
+  }
+
+  log("")
+  success(`Android shell synced: app.js + ${runtimePlugins.length} plugin(s), SDK ${sdkVersion}, v${config.version ?? "1.0.0"} (${config.android?.versionCode ?? 1}).`)
+  note("Build & run from Android Studio (`lecodes app open android`) — user files in android/app/ were not touched.")
+}
+
+/** Values-only restamps + tagged-line management in the USER-owned app/build.gradle.kts —
+ *  the Android analog of the pbxproj MARKETING_VERSION restamp + CODE_SIGN_ENTITLEMENTS
+ *  injection: warn-not-fail when the user restructured, and the ONLY lines sync ever removes
+ *  are its own `// lecodes:plugin`-tagged ones. */
+const restampAppBuildGradle = (androidDir: string, config: AppConfig, gradlePlugins: Map<string, string>) => {
+  const path = join(androidDir, "app", "build.gradle.kts")
+  if (!existsSync(path)) {
+    warn("android/app/build.gradle.kts is missing — run `lecodes app init android` on a clean tree to regenerate the shell.")
+    return
+  }
+  let content = readFileSync(path, "utf8")
+  const before = content
+
+  const versionName = config.version ?? "1.0.0"
+  const versionCode = config.android?.versionCode ?? 1
+  if (/versionName = "[^"]*"/.test(content)) {
+    content = content.replace(/versionName = "[^"]*"/, `versionName = "${versionName}"`)
+  } else {
+    warn(`couldn't restamp versionName in app/build.gradle.kts — set it to "${versionName}" yourself.`)
+  }
+  if (/versionCode = \d+/.test(content)) {
+    content = content.replace(/versionCode = \d+/, `versionCode = ${versionCode}`)
+  } else {
+    warn(`couldn't restamp versionCode in app/build.gradle.kts — set it to ${versionCode} yourself.`)
+  }
+
+  // Which requested Gradle plugins actually get applied: google-services only once the app has
+  // its google-services.json (the plugin hard-fails the build without it).
+  const applied = new Set<string>()
+  for (const id of gradlePlugins.keys()) {
+    if (id === "com.google.gms.google-services" && !existsSync(join(androidDir, "app", "google-services.json"))) {
+      warn(`push needs android/app/google-services.json (download it from the le.codes Firebase project — the app's package name must be registered there). The google-services Gradle plugin stays un-applied until the file exists, so FCM registration will fail.`)
+      continue
+    }
+    applied.add(id)
+  }
+
+  // Remove tagged lines that are no longer required, add missing ones inside the first
+  // plugins { } block.
+  content = content.split("\n").filter(line => {
+    const m = /^\s*id\("([^"]+)"\)\s*\/\/ lecodes:plugin\s*$/.exec(line)
+    return !(m && !applied.has(m[1]))
+  }).join("\n")
+  for (const id of applied) {
+    if (new RegExp(`id\\("${id.replace(/\./g, "\\.")}"\\)`).test(content)) continue
+    const start = content.search(/^plugins\s*\{/m)
+    const end = start >= 0 ? content.indexOf("\n}", start) : -1
+    if (end < 0) {
+      warn(`couldn't find the plugins { } block in app/build.gradle.kts — add \`id("${id}")\` to it yourself.`)
+      continue
+    }
+    content = content.slice(0, end) + `\n    id("${id}")  // lecodes:plugin` + content.slice(end)
+    log(`${c.green("updated")}   android/app/build.gradle.kts: + id("${id}")`)
+  }
+
+  if (content !== before) writeFileSync(path, content)
+}
+
+/* ---------------------------------------- build ---------------------------------------- */
+
+const gradlew = (androidDir: string, tasks: string[]): string => {
+  // `sh gradlew` sidesteps a lost exec bit (zip/copy round-trips drop it).
+  if (process.platform !== "win32") return runTool(androidDir, "sh", ["gradlew", ...tasks])
+
+  // Windows: Node refuses to spawn a .bat directly (EINVAL), and a bare relative name breaks
+  // under NoDefaultCurrentDirectoryInExePath — so invoke by ABSOLUTE path through cmd.exe,
+  // with verbatim args in the canonical `/s /c ""<bat>" <tasks>"` shape (/s strips exactly
+  // the outer quotes, keeping the inner-quoted path intact even with spaces).
+  const line = `""${join(androidDir, "gradlew.bat")}" ${tasks.join(" ")}"`
+  const r = spawnSync("cmd.exe", ["/d", "/s", "/c", line], {
+    cwd: androidDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 128 * 1024 * 1024, windowsVerbatimArguments: true,
+  })
+  if (r.status !== 0) {
+    const tail = ((r.stdout ?? "") + "\n" + (r.stderr ?? "")).split("\n").filter(l => l.trim()).slice(-25).join("\n")
+    throw new CliError(`gradlew ${tasks[0] ?? ""} failed:\n${tail}`)
+  }
+  return r.stdout ?? ""
+}
+
+export const buildAndroid = async (args: Args) => {
+  const root = projectRoot()
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const androidDir = join(root, "android")
+  if (!config?.android || !existsSync(androidDir)) {
+    throw new CliError("No Android shell here — run `lecodes app init android` first.")
+  }
+
+  if (!flagBool(args, "no-sync")) await syncAndroid(root, config, null)
+
+  // Gradle needs the Android SDK location: local.properties, or written from the env.
+  if (!existsSync(join(androidDir, "local.properties"))) {
+    const sdkHome = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT
+    if (!sdkHome) {
+      throw new CliError("Android SDK not found — set ANDROID_HOME, or create android/local.properties with sdk.dir=…")
+    }
+    writeFileSync(join(androidDir, "local.properties"), `sdk.dir=${sdkHome.replace(/\\/g, "\\\\")}\n`)
+    note("Wrote android/local.properties (sdk.dir from the environment).")
+  }
+
+  const configuration = (flagStr(args, "configuration") ?? "Release").toLowerCase()
+  const tasks = configuration === "debug"
+    ? ["assembleDebug"]
+    : flagBool(args, "no-aab") ? ["assembleRelease"] : ["assembleRelease", "bundleRelease"]
+
+  note(`Building (${tasks.join(" ")})… the first run downloads Gradle + dependencies`)
+  gradlew(androidDir, tasks)
+
+  const outputs: string[] = []
+  const apkDir = join(androidDir, "app", "build", "outputs", "apk", configuration)
+  const aabDir = join(androidDir, "app", "build", "outputs", "bundle", configuration)
+  for (const dir of [apkDir, aabDir]) {
+    if (!existsSync(dir)) continue
+    for (const f of readdirSync(dir)) {
+      if (f.endsWith(".apk") || f.endsWith(".aab")) outputs.push(join(dir, f))
+    }
+  }
+  for (const out of outputs) log(`${c.green("output")}    ${out}`)
+  if (outputs.some(o => basename(o).includes("unsigned"))) {
+    note("The APK is UNSIGNED — create android/keystore.properties (see android/README.md) and rebuild to ship it.")
+  }
+  success(configuration === "debug"
+    ? "Debug build done — `adb install` the APK to test."
+    : "Release build done — upload the .aab in the Play Console (the .apk side-loads for testing).")
+}
+
+/* ---------------------------------------- open ----------------------------------------- */
+
+export const openAndroid = async () => {
+  const root = projectRoot()
+  const androidDir = join(root, "android")
+  if (!existsSync(join(androidDir, "settings.gradle.kts"))) {
+    throw new CliError("No Android shell here — run `lecodes app init android` first.")
+  }
+
+  if (process.platform === "darwin") {
+    try {
+      execFileSync("open", ["-a", "Android Studio", androidDir], { stdio: "ignore" })
+      success("Opened android/ in Android Studio.")
+      return
+    } catch { /* fall through */ }
+  } else if (process.platform === "win32") {
+    const candidates = [
+      join(process.env.LOCALAPPDATA ?? "", "Programs", "Android Studio", "bin", "studio64.exe"),
+      "C:\\Program Files\\Android\\Android Studio\\bin\\studio64.exe",
+    ]
+    for (const exe of candidates) {
+      if (!existsSync(exe)) continue
+      spawn(exe, [androidDir], { detached: true, stdio: "ignore" }).unref()
+      success("Opened android/ in Android Studio.")
+      return
+    }
+  } else {
+    try {
+      // JetBrains Toolbox / distro launcher script.
+      spawn("studio", [androidDir], { detached: true, stdio: "ignore" }).unref()
+      success("Opened android/ in Android Studio.")
+      return
+    } catch { /* fall through */ }
+  }
+  note("Open the android/ folder in Android Studio.")
+}
+
+/* --------------------------------------- doctor ---------------------------------------- */
+
+export const doctorAndroidChecks = async (
+  root: string, config: AppConfig,
+  check: (ok: boolean, label: string, hint?: string, fatal?: boolean) => void,
+) => {
+  const androidDir = join(root, "android")
+
+  // JDK ≥ 17 (AGP's floor for running Gradle; app code targets JVM 11 regardless).
+  const java = spawnSync("java", ["-version"], { encoding: "utf8" })
+  const javaOut = `${java.stderr ?? ""}${java.stdout ?? ""}`
+  const javaMajor = Number(/version "(\d+)/.exec(javaOut)?.[1] ?? 0)
+  check(javaMajor >= 17, `JDK ${javaMajor || "not found"}`, "install JDK 17+ (Android Studio ships one)")
+
+  const hasSdkHome = !!(process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT) || existsSync(join(androidDir, "local.properties"))
+  check(hasSdkHome, "Android SDK location", "set ANDROID_HOME or create android/local.properties")
+
+  const requestedVariant = config.android?.variant ?? "auto"
+  const validVariant = requestedVariant === "auto" || SDK_VARIANTS.includes(requestedVariant as SdkVariant)
+  check(validVariant, `android.variant "${requestedVariant}"`, `use "auto" or one of ${SDK_VARIANTS.join(", ")}`)
+
+  const wrapperJar = join(androidDir, "gradle", "wrapper", "gradle-wrapper.jar")
+  check(existsSync(wrapperJar) && statSync(wrapperJar).size > 0, "Gradle wrapper jar",
+    `run \`gradle wrapper --gradle-version ${GRADLE_VERSION}\` in android/ (or let Android Studio repair it)`)
+
+  check(existsSync(join(androidDir, "app", "src", "main", "assets", "app.js")), "Bundled app.js", "run `lecodes app sync`")
+
+  const linked = shellSdkVersionAndroid(androidDir)
+  const pin = config.android?.sdk ?? "latest"
+  check(!!linked, `SDK ${linked ?? "version unreadable"}`, "run `lecodes app sync`")
+  if (linked && pin !== "latest") {
+    check(linked === pin, `SDK matches app.json android.sdk (${pin})`, "run `lecodes app sync`")
+  }
+  if (linked) {
+    try {
+      const latest = await fetchLatestSdkVersion(ANDROID_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 hasKeystore = existsSync(join(androidDir, "keystore.properties")) || !!process.env.LECODES_ANDROID_KEYSTORE_FILE
+  check(hasKeystore, "Release signing configured", "android/keystore.properties or LECODES_ANDROID_* env (release builds come out unsigned without it)", false)
+
+  if (Object.keys(config.plugins ?? {}).includes("push")) {
+    check(existsSync(join(androidDir, "app", "google-services.json")), "google-services.json present (push)",
+      "download it from the le.codes Firebase project — FCM registration fails without it", false)
+  }
+}