lecodes-cli 0.20.2 → 2.0.0

package/src/commands/{appAndroid.ts → app/android.ts}

@@ -1,32 +1,35 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process"
-import { createHash } from "node:crypto"
+import { createHash, randomBytes } 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 { basename, dirname, join, relative, resolve } from "node:path"
+import { readManifest } from "../../project/manifest"
+import { compileShell, type BundleResource } from "../compile"
+import { CliError, UsageError, bool, c, defineCommand, log, note, promptHidden, str, success, warn, type FlagValues } from "../../cli"
+import { upsertDotEnv } from "../../project/env"
 import {
-  type AppConfig, SDK_VARIANTS, VERSION_RE, cmpVersion, ensureShellIgnored, fetchLatestSdkVersion,
+  type AppConfig, SDK_VARIANTS, VERSION_RE, childEnv, cmpVersion, ensureShellIgnored, fetchLatestSdkVersion,
   projectRoot, readJson, resolvePlugin, resolveSdkVersion, resolveVariant, runTool, slugify,
   writeJson, type LockEntry,
-} from "./appShared"
-import { loadIconMaster, restampManifestIcon, writeAndroidIcons } from "./appIcon"
+} from "./shared"
+import { loadIconMaster, restampManifestIcon, writeAndroidIcons } from "./icon"
 import {
-  ANDROID_GITIGNORE, ANDROID_README, COLORS_XML, GRADLE_PROPERTIES, GRADLE_VERSION,
+  ANDROID_GITIGNORE, ANDROID_README, APP_PROGUARD_RULES, 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"
+} from "./templates/android"
+import { GRADLEW_BAT, GRADLEW_SH } from "./templates/gradlew"
+import { type SdkVariant } from "./templates/ios"
 
-/* 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. */
+/* The Android arm of `lecodes app` — the mirror of the iOS flows in index.ts, over Gradle
+ * instead of Xcode: init / sync / open / doctor checks as functions the shared command nodes call,
+ * plus the two Android-only nodes defined here — `app build android` and `app keystore …`.
+ * Same ownership contract (see templates/android.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"
 
@@ -93,7 +96,10 @@ const rmrf = (path: string) => rmSync(path, { recursive: true, force: true, maxR
 
 /* ---------------------------------------- init ---------------------------------------- */
 
-export const initAndroid = async (args: Args) => {
+/** The `app init android` flags (index.ts declares the shared init node). */
+export interface AndroidInitOptions { name?: string, appId?: string, variant?: string, sdk?: string }
+
+export const initAndroid = async (opts: AndroidInitOptions) => {
   const root = projectRoot()
   const androidDir = join(root, "android")
   if (existsSync(androidDir)) {
@@ -102,7 +108,7 @@ export const initAndroid = async (args: Args) => {
 
   const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
 
-  const variant = flagStr(args, "variant") ?? existing.android?.variant ?? "auto"
+  const variant = opts.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}")`)
   }
@@ -110,11 +116,11 @@ export const initAndroid = 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.android?.sdk
+  const sdkFlag = opts.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)
+  const name = opts.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 = {
@@ -123,11 +129,12 @@ export const initAndroid = async (args: Args) => {
     version: existing.version ?? "1.0.0",
     plugins: existing.plugins ?? {},
     android: {
-      applicationId: flagStr(args, "app-id") ?? existing.android?.applicationId ?? defaultAppId,
+      applicationId: opts.appId ?? existing.android?.applicationId ?? defaultAppId,
       versionCode: existing.android?.versionCode ?? 1,
       sdk,
       variant,
       ...(existing.android?.signing ? { signing: existing.android.signing } : {}),
+      ...(existing.android?.minify === false ? { minify: false } : {}),
     },
   }
   writeJson(join(root, "app.json"), config)
@@ -164,7 +171,8 @@ export const initAndroid = async (args: Args) => {
   const wrapperJar = await ensureGradleWrapperJar()
   if (wrapperJar) write("gradle/wrapper/gradle-wrapper.jar", wrapperJar)
 
-  write("app/build.gradle.kts", appBuildGradleTemplate(identity))
+  write("app/build.gradle.kts", appBuildGradleTemplate(identity, config.android!.minify ?? true))
+  write("app/proguard-rules.pro", APP_PROGUARD_RULES)
   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))
@@ -233,7 +241,7 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
     bundleJs = prior.bundleJs
     resources = prior.resources
   } else {
-    resources = await compileShell({ _: [], flags: { o: join(assetsDir, "app.js") } }, { remotePatterns })
+    resources = await compileShell(join(assetsDir, "app.js"), { remotePatterns })
     bundleJs = readFileSync(join(assetsDir, "app.js"), "utf8")
   }
 
@@ -326,7 +334,9 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
   // 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
+  // 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
@@ -416,6 +426,16 @@ const restampAppBuildGradle = (androidDir: string, config: AppConfig, gradlePlug
     warn(`couldn't restamp versionCode in app/build.gradle.kts — set it to ${versionCode} yourself.`)
   }
 
+  // R8 on/off (app.json android.minify, default on) — the two values travel together: AGP
+  // refuses isShrinkResources without isMinifyEnabled.
+  const minify = config.android?.minify ?? true
+  const r8Keys = ["isMinifyEnabled", "isShrinkResources"]
+  if (r8Keys.every(k => new RegExp(`${k} = (true|false)`).test(content))) {
+    for (const k of r8Keys) content = content.replace(new RegExp(`${k} = (true|false)`), `${k} = ${minify}`)
+  } else {
+    warn(`couldn't restamp ${r8Keys.join("/")} in app/build.gradle.kts (a shell generated before R8 was on by default) — see android/README.md "Building" for the release block to add.`)
+  }
+
   // 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>()
@@ -461,7 +481,7 @@ const gradlew = (androidDir: string, tasks: string[]): string => {
   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,
+    maxBuffer: 128 * 1024 * 1024, windowsVerbatimArguments: true, env: childEnv(),
   })
   if (r.status !== 0) {
     const tail = ((r.stdout ?? "") + "\n" + (r.stderr ?? "")).split("\n").filter(l => l.trim()).slice(-25).join("\n")
@@ -470,7 +490,19 @@ const gradlew = (androidDir: string, tasks: string[]): string => {
   return r.stdout ?? ""
 }
 
-export const buildAndroid = async (args: Args) => {
+const androidBuildFlags = {
+  configuration: str("Release (default) or Debug", { value: "<c>", default: "Release" }),
+  apk: bool("only the .apk"),
+  aab: bool("only the .aab"),
+  "no-aab": bool("the old spelling of --apk"),
+  "allow-unsigned": bool("build a release without a signing key anyway"),
+  out: str("output dir (default dist/)", { alias: "o", value: "<dir>" }),
+  slug: str("file name stem (default: the app name)", { value: "<name>" }),
+  "no-sync": bool("skip the `lecodes app sync` step"),
+}
+
+/** `lecodes app build android` — sync, Gradle, then the artifacts copied under dist/. */
+const buildAndroid = async (flags: FlagValues<typeof androidBuildFlags>): Promise<void> => {
   const root = projectRoot()
   const config = readJson<AppConfig>(join(root, "app.json"))
   const androidDir = join(root, "android")
@@ -478,7 +510,43 @@ export const buildAndroid = async (args: Args) => {
     throw new CliError("No Android shell here — run `lecodes app init android` first.")
   }
 
-  if (!flagBool(args, "no-sync")) await syncAndroid(root, config, null)
+  const configuration = flags.configuration.toLowerCase()
+  if (configuration !== "release" && configuration !== "debug") {
+    throw new CliError(`--configuration must be Release or Debug (got "${configuration}")`)
+  }
+  // Artifacts: both by default; --apk / --aab pick one (both flags = both); --no-aab = the old
+  // spelling of --apk.
+  const apkFlag = flags.apk || flags["no-aab"]
+  const aabFlag = flags.aab && !flags["no-aab"]
+  const wantApk = apkFlag || !aabFlag
+  const wantAab = aabFlag || (!apkFlag && !flags["no-aab"])
+
+  // Signing is resolved HERE, before Gradle runs: a release that would come out unsigned is
+  // refused with the ways to fix it, instead of Gradle producing an app-release-unsigned.apk
+  // (and an .aab with the same name as a signed one) that can't be installed or uploaded.
+  let signing: AndroidSigning | null = null
+  if (configuration === "release") {
+    signing = resolveAndroidSigning(androidDir)
+    if (!signing) {
+      if (!flags["allow-unsigned"]) {
+        throw new CliError([
+          "No release signing key — the .apk/.aab would be unsigned (uninstallable, not uploadable).",
+          "  lecodes app keystore create          make one (path + passwords go to the project .env)",
+          "  lecodes app keystore use <file>      attach an existing keystore",
+          "  --allow-unsigned                     build anyway (throwaway builds only)",
+        ].join("\n"))
+      }
+      warn("Building UNSIGNED (--allow-unsigned) — the output can't be installed or uploaded.")
+    } else if (!existsSync(signing.storeFile)) {
+      throw new CliError(`Keystore ${signing.storeFile} (from ${signing.source}) does not exist.`)
+    } else {
+      const missing = (["storePassword", "keyAlias", "keyPassword"] as const).filter(k => !signing![k])
+      if (missing.length > 0) throw new CliError(`Signing from ${signing.source} is incomplete — missing ${missing.join(", ")} (see android/README.md "Release signing").`)
+      log(`${c.green("signing")}   ${signing.storeFile}  alias ${signing.keyAlias}${c.dim(`  (${signing.source})`)}`)
+    }
+  }
+
+  if (!flags["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"))) {
@@ -490,32 +558,362 @@ export const buildAndroid = async (args: Args) => {
     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"]
-
+  const cap = configuration === "release" ? "Release" : "Debug"
+  const tasks = [...(wantApk ? [`assemble${cap}`] : []), ...(wantAab ? [`bundle${cap}`] : [])]
   note(`Building (${tasks.join(" ")})… the first run downloads Gradle + dependencies`)
   gradlew(androidDir, tasks)
 
-  const outputs: string[] = []
+  // Gradle's outputs, then a copy under dist/ named by the app (the desktop build's convention)
+  // — the shell's build/ tree stays where Android Studio expects it.
+  const produced: 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 [dir, want] of [[apkDir, wantApk], [aabDir, wantAab]] as const) {
+    if (!want || !existsSync(dir)) continue
     for (const f of readdirSync(dir)) {
-      if (f.endsWith(".apk") || f.endsWith(".aab")) outputs.push(join(dir, f))
+      if (f.endsWith(".apk") || f.endsWith(".aab")) produced.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.")
+  if (produced.length === 0) throw new CliError("Gradle finished but produced no .apk/.aab — check android/app/build/outputs.")
+
+  const slug = flags.slug ?? slugify(config.name ?? basename(root))
+  const outDir = resolve(root, flags.out ?? join(root, "dist"))
+  mkdirSync(outDir, { recursive: true })
+  const stem = `${slug}-${config.version ?? "1.0.0"}-${config.android.versionCode ?? 1}${configuration === "debug" ? "-debug" : ""}`
+  for (const src of produced) {
+    const unsigned = configuration === "release" && !signing
+    const dest = join(outDir, `${stem}${unsigned ? "-unsigned" : ""}${src.endsWith(".aab") ? ".aab" : ".apk"}`)
+    cpSync(src, dest)
+    const size = (statSync(dest).size / (1024 * 1024)).toFixed(1)
+    log(`${c.green("output")}    ${relative(root, dest) || dest}${c.dim(`  (${size} MB)`)}`)
   }
   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).")
+    ? "Debug build done — `adb install` the .apk to test (or `lecodes dev --android --apk <file>`)."
+    : signing
+      ? "Release build done — upload the .aab in the Play Console (the .apk side-loads for testing)."
+      : "Unsigned release build done — sign it before it goes anywhere.")
+}
+
+export const androidBuild = defineCommand({
+  name: "android",
+  summary: "Sync, gradlew assembleRelease + bundleRelease, copy the results to dist/<name>-<version>-<versionCode>.apk|.aab",
+  description: "Signing comes from the project .env keys `lecodes app keystore` writes (LECODES_ANDROID_KEYSTORE_FILE / _KEYSTORE_PASSWORD / _KEY_ALIAS / _KEY_PASSWORD) or android/keystore.properties; a release build without a key is refused — --allow-unsigned builds one anyway (throwaway builds only). Release builds run R8 (app.json android.minify: false turns it off). Gradle needs the Android SDK location: android/local.properties, or written from ANDROID_HOME on the first build.\n\nBoth artifacts are built by default; --apk / --aab pick one. The shell's own build/ tree stays where Android Studio expects it — dist/ gets a copy named by the app.",
+  flags: androidBuildFlags,
+  examples: ["lecodes app build android", "lecodes app build android --configuration Debug --apk", "lecodes app build android -o out/"],
+  run: ({ flags }) => buildAndroid(flags),
+})
+
+/* --------------------------------------- signing --------------------------------------- */
+
+/** The four names the generated app/build.gradle.kts reads with System.getenv — the project
+ *  .env is where they normally live (projectEnv.ts loads it; never pushed). */
+export const ANDROID_SIGNING_ENV = {
+  storeFile: "LECODES_ANDROID_KEYSTORE_FILE",
+  storePassword: "LECODES_ANDROID_KEYSTORE_PASSWORD",
+  keyAlias: "LECODES_ANDROID_KEY_ALIAS",
+  keyPassword: "LECODES_ANDROID_KEY_PASSWORD",
+} as const
+
+export interface AndroidSigning {
+  /** Where `storeFile` came from — per key the file wins, exactly like the Gradle side. */
+  source: "keystore.properties" | "env"
+  /** Absolute. */
+  storeFile: string
+  storePassword?: string
+  keyAlias?: string
+  keyPassword?: string
+}
+
+/** The subset of java.util.Properties a keystore.properties uses: `key=value` / `key: value`,
+ *  `#` / `!` comments, `\\` `\:` `\=` escapes. */
+const readProperties = (path: string): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const raw of readFileSync(path, "utf8").split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith("#") || line.startsWith("!")) continue
+    const m = /^((?:\\.|[^=:\s])+)\s*[=:]?\s*(.*)$/.exec(line)
+    if (!m) continue
+    const unescape = (v: string) => v.replace(/\\(.)/g, "$1")
+    out[unescape(m[1])] = unescape(m[2])
+  }
+  return out
+}
+
+/** The signing chain exactly as the generated app/build.gradle.kts resolves it: per key,
+ *  android/keystore.properties first, then the LECODES_ANDROID_* environment (the project .env
+ *  has been loaded into it). A relative storeFile resolves against android/ like
+ *  `rootProject.file()` does; `./` values from .env arrive absolute already. Null = no key. */
+export const resolveAndroidSigning = (androidDir: string): AndroidSigning | null => {
+  const propsPath = join(androidDir, "keystore.properties")
+  const props = existsSync(propsPath) ? readProperties(propsPath) : {}
+  const pick = (key: keyof typeof ANDROID_SIGNING_ENV) => props[key] ?? process.env[ANDROID_SIGNING_ENV[key]]
+  const storeFile = pick("storeFile")
+  if (!storeFile) return null
+  return {
+    source: props.storeFile ? "keystore.properties" : "env",
+    storeFile: resolve(androidDir, storeFile),
+    storePassword: pick("storePassword"),
+    keyAlias: pick("keyAlias"),
+    keyPassword: pick("keyPassword"),
+  }
+}
+
+/** keytool: JAVA_HOME → PATH → the JBR inside Android Studio (the only JDK on many machines). */
+const findKeytool = (): string | null => {
+  const exe = process.platform === "win32" ? "keytool.exe" : "keytool"
+  const fromJavaHome = process.env.JAVA_HOME ? join(process.env.JAVA_HOME, "bin", exe) : null
+  if (fromJavaHome && existsSync(fromJavaHome)) return fromJavaHome
+  const onPath = spawnSync("keytool", ["-help"], { encoding: "utf8", env: childEnv() })
+  if (!onPath.error) return "keytool"
+  const studio = process.platform === "win32"
+    ? [join(process.env.LOCALAPPDATA ?? "", "Programs", "Android Studio", "jbr", "bin", exe), "C:\\Program Files\\Android\\Android Studio\\jbr\\bin\\keytool.exe"]
+    : process.platform === "darwin"
+      ? ["/Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/keytool"]
+      : [join(homedir(), "android-studio", "jbr", "bin", "keytool"), "/opt/android-studio/jbr/bin/keytool", "/usr/local/android-studio/jbr/bin/keytool"]
+  return studio.find(p => existsSync(p)) ?? null
+}
+
+/** Run keytool with English output (the alias listing is parsed) and passwords passed through
+ *  the environment (`-storepass:env`), never on the command line. */
+const keytool = (args: string[], secrets: Record<string, string> = {}): string => {
+  const exe = findKeytool()
+  if (!exe) throw new CliError("keytool not found — install a JDK (Android Studio ships one) or point JAVA_HOME at it.")
+  const r = spawnSync(exe, ["-J-Duser.language=en", ...args], { encoding: "utf8", env: childEnv(secrets), stdio: ["ignore", "pipe", "pipe"] })
+  if (r.status !== 0) {
+    const tail = ((r.stdout ?? "") + "\n" + (r.stderr ?? "")).split("\n").filter(l => l.trim()).slice(-6).join("\n")
+    throw new CliError(`keytool ${args[0]} failed:\n${tail}`)
+  }
+  return (r.stdout ?? "") + (r.stderr ?? "")
+}
+
+const KEYTOOL_PASS = "LECODES_KEYTOOL_PASS"
+
+/** PrivateKeyEntry aliases from `keytool -list` (English): "<alias>, <date>, PrivateKeyEntry,". */
+const listPrivateKeyAliases = (listing: string): string[] =>
+  listing.split(/\r?\n/).map(l => /^(.+?), .*?, PrivateKeyEntry,/.exec(l)?.[1]).filter((a): a is string => !!a)
+
+/** How a keystore path is spelled in .env: inside the project → `./…` (resolved against the
+ *  .env's own dir by projectEnv, so it survives `lecodes` running from a subdirectory); under
+ *  the home dir → `~/…`; elsewhere absolute. Forward slashes throughout. */
+const envPathFor = (root: string, abs: string): string => {
+  const fwd = (p: string) => p.replace(/\\/g, "/")
+  const rel = relative(root, abs)
+  if (rel && !rel.startsWith("..") && !rel.includes(":")) return `./${fwd(rel)}`
+  const home = relative(homedir(), abs)
+  if (home && !home.startsWith("..") && !home.includes(":")) return `~/${fwd(home)}`
+  return fwd(abs)
+}
+
+/** A .env value: raw when plain, double-quoted (with `"` / `\` escaped) when it carries whitespace,
+ *  `#` or quotes — the subset parseDotEnv unescapes. */
+const envValue = (v: string): string => /[\s#"'\\]/.test(v) ? `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : v
+
+/** The store password from --password, --generate (create only), or a hidden prompt. */
+const resolveKeystorePassword = async (opts: { password?: string, generate?: boolean }, create: boolean): Promise<string> => {
+  if (opts.password) {
+    if (create && opts.password.length < 6) throw new CliError("keytool needs a password of at least 6 characters.")
+    return opts.password
+  }
+  if (create && opts.generate) return randomBytes(24).toString("base64url")
+  if (!process.stdin.isTTY) {
+    throw new CliError(`No terminal to ask for the keystore password — pass --password <pw>${create ? " (or --generate)" : ""}.`)
+  }
+  const pw = await promptHidden(create ? "Keystore password (min 6 chars)" : "Keystore password")
+  if (create) {
+    if (pw.length < 6) throw new CliError("keytool needs a password of at least 6 characters.")
+    const again = await promptHidden("Repeat password")
+    if (again !== pw) throw new CliError("Passwords don't match.")
+  }
+  return pw
 }
 
+/** Bank the key in .env (+ .gitignore) and its metadata in app.json android.signing. */
+const writeSigningConfig = (root: string, config: AppConfig, storeFile: string, alias: string, storePassword: string, keyPassword: string) => {
+  const envPath = envPathFor(root, storeFile)
+  const touched = upsertDotEnv(root, {
+    [ANDROID_SIGNING_ENV.storeFile]: envPath,
+    [ANDROID_SIGNING_ENV.storePassword]: envValue(storePassword),
+    [ANDROID_SIGNING_ENV.keyAlias]: alias,
+    [ANDROID_SIGNING_ENV.keyPassword]: envValue(keyPassword),
+  })
+  for (const t of touched) log(`${c.green(t === ".env" ? "written" : "updated")}   ${t}${t === ".env" ? c.dim("  (LECODES_ANDROID_KEYSTORE_FILE / _KEYSTORE_PASSWORD / _KEY_ALIAS / _KEY_PASSWORD)") : ""}`)
+
+  // A keystore inside the project but outside android/ (which has its own .gitignore) must not
+  // end up in git either.
+  const rel = relative(root, storeFile)
+  if (rel && !rel.startsWith("..") && !rel.includes(":") && !rel.replace(/\\/g, "/").startsWith("android/")) {
+    const ignorePath = join(root, ".gitignore")
+    const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
+    if (!ignore.split("\n").some(l => l.trim() === "*.keystore")) {
+      writeFileSync(ignorePath, ignore + (!ignore || ignore.endsWith("\n") ? "" : "\n") + "*.keystore\n")
+      log(`${c.green("updated")}   .gitignore  (+ *.keystore)`)
+    }
+  }
+
+  const configPath = join(root, "app.json")
+  const fresh = readJson<AppConfig>(configPath) ?? config
+  fresh.android = { ...(fresh.android ?? {}), signing: { storeFile: envPath, keyAlias: alias } }
+  writeJson(configPath, fresh)
+  log(`${c.green("written")}   app.json  (android.signing — metadata only, no passwords)`)
+}
+
+/** Fingerprints + validity for one alias (`keytool -list -v`, English). */
+const printCertificate = (storeFile: string, alias: string, storePassword: string) => {
+  const out = keytool(["-list", "-v", "-keystore", storeFile, "-alias", alias, "-storepass:env", KEYTOOL_PASS], { [KEYTOOL_PASS]: storePassword })
+  for (const line of out.split(/\r?\n/)) {
+    const t = line.trim()
+    if (/^(Alias name|Owner|Valid from|SHA1|SHA256):/.test(t)) log(`  ${t}`)
+  }
+}
+
+const PLAY_APP_SIGNING_NOTE = "With Play App Signing (default for new Play apps) this is the UPLOAD key — Google keeps the app signing key, and a lost upload key can be reset through Play support. Without it, losing this file means the app can never be updated. Back it up either way."
+
+/** Every keystore subcommand starts from the project + its app.json (which may not exist yet). */
+const keystoreProject = (): { root: string, config: AppConfig } => {
+  const root = projectRoot()
+  return { root, config: readJson<AppConfig>(join(root, "app.json")) ?? {} }
+}
+
+const passwordFlag = { password: str("keystore password (else asked on the terminal)", { value: "<pw>" }) }
+
+const keystoreCreateFlags = {
+  alias: str("key alias", { value: "<a>", default: "upload" }),
+  out: str("keystore path (default android/release.keystore)", { alias: "o", value: "<file>" }),
+  ...passwordFlag,
+  generate: bool("a random password instead of asking"),
+  validity: str("certificate validity in days", { value: "<days>", default: "10000" }),
+  dname: str("X.500 distinguished name (default CN=<app name>)", { value: "<X.500>" }),
+  force: bool("overwrite an existing keystore / signing config"),
+}
+
+/** `lecodes app keystore create` — a new upload key, banked in .env. */
+const keystoreCreate = async (flags: FlagValues<typeof keystoreCreateFlags>): Promise<void> => {
+  const { root, config } = keystoreProject()
+  const alias = flags.alias
+  const storeFile = resolve(root, flags.out ?? join("android", "release.keystore"))
+  const validity = flags.validity
+  const dname = flags.dname ?? `CN=${(config.name ?? basename(root)).replace(/[,=+<>#;"\\]/g, " ").trim() || "app"}`
+  const force = flags.force
+
+  if (existsSync(storeFile) && !force) {
+    throw new CliError(`${relative(root, storeFile)} already exists — a signing key is not something to overwrite. \`lecodes app keystore use ${relative(root, storeFile)}\` attaches it; --force generates a new one over it.`)
+  }
+  const current = resolveAndroidSigning(join(root, "android"))
+  if (current && !force) {
+    throw new CliError(`Release signing is already configured (${current.storeFile}, from ${current.source}) — --force writes the new key over the .env lines (the old file stays).`)
+  }
+
+  const password = await resolveKeystorePassword(flags, true)
+  mkdirSync(dirname(storeFile), { recursive: true })
+  keytool([
+    "-genkeypair", "-keystore", storeFile, "-alias", alias, "-keyalg", "RSA", "-keysize", "2048",
+    "-validity", validity, "-dname", dname, "-storepass:env", KEYTOOL_PASS, "-keypass:env", KEYTOOL_PASS,
+  ], { [KEYTOOL_PASS]: password })
+  log(`${c.green("created")}   ${relative(root, storeFile)}  alias ${alias}, ${dname}, valid ${validity} days`)
+
+  writeSigningConfig(root, config, storeFile, alias, password, password)
+  printCertificate(storeFile, alias, password)
+  log("")
+  success("Release signing key ready — `lecodes app build android` signs with it.")
+  note(PLAY_APP_SIGNING_NOTE)
+}
+
+const keystoreUseFlags = {
+  alias: str("key alias (needed when the keystore holds several keys)", { value: "<a>" }),
+  ...passwordFlag,
+  "key-password": str("the key's own password when it differs from the store's (JKS)", { value: "<pw>" }),
+  copy: bool("copy the file into android/ and point the config at the copy"),
+  force: bool("(--copy) replace a same-named file in android/"),
+}
+
+/** `lecodes app keystore use <file>` — attach an existing keystore. */
+const keystoreUse = async (given: string | undefined, flags: FlagValues<typeof keystoreUseFlags>): Promise<void> => {
+  const { root, config } = keystoreProject()
+  if (!given) throw new UsageError("Which keystore? `lecodes app keystore use <file>`")
+  let storeFile = resolve(root, given.startsWith("~/") ? join(homedir(), given.slice(2)) : given)
+  if (!existsSync(storeFile)) throw new CliError(`Keystore not found: ${storeFile}`)
+
+  const password = await resolveKeystorePassword(flags, false)
+  const aliases = listPrivateKeyAliases(keytool(["-list", "-keystore", storeFile, "-storepass:env", KEYTOOL_PASS], { [KEYTOOL_PASS]: password }))
+  if (aliases.length === 0) throw new CliError("That keystore holds no private key entry — nothing to sign with.")
+  let alias = flags.alias
+  if (!alias) {
+    if (aliases.length > 1) throw new CliError(`Several keys in the keystore — pick one with --alias: ${aliases.join(", ")}`)
+    alias = aliases[0]
+  } else if (!aliases.includes(alias)) {
+    throw new CliError(`No key "${alias}" in the keystore — it has: ${aliases.join(", ")}`)
+  }
+  // PKCS12 stores use one password for store and key; a JKS key may have its own.
+  const keyPassword = flags["key-password"] ?? password
+
+  if (flags.copy) {
+    const dest = join(root, "android", basename(storeFile))
+    if (resolve(dest) !== storeFile) {
+      if (existsSync(dest) && !flags.force) throw new CliError(`${relative(root, dest)} already exists — --force to replace it.`)
+      mkdirSync(dirname(dest), { recursive: true })
+      cpSync(storeFile, dest)
+      log(`${c.green("copied")}    ${relative(root, dest)}`)
+      storeFile = dest
+    }
+  }
+
+  writeSigningConfig(root, config, storeFile, alias, password, keyPassword)
+  printCertificate(storeFile, alias, password)
+  log("")
+  success(`Release signing uses ${relative(root, storeFile) || storeFile} (alias ${alias}).`)
+  note(PLAY_APP_SIGNING_NOTE)
+}
+
+/** `lecodes app keystore info` — what the build would sign with, and its fingerprints. */
+const keystoreInfo = async (flags: FlagValues<typeof passwordFlag>): Promise<void> => {
+  const { root } = keystoreProject()
+  const signing = resolveAndroidSigning(join(root, "android"))
+  if (!signing) throw new CliError("No release signing configured — `lecodes app keystore create` or `lecodes app keystore use <file>`.")
+  log(`${c.green("keystore")}  ${signing.storeFile}${c.dim(`  (${signing.source})`)}`)
+  if (!existsSync(signing.storeFile)) throw new CliError("…and that file does not exist.")
+  const password = signing.storePassword ?? await resolveKeystorePassword(flags, false)
+  const aliases = listPrivateKeyAliases(keytool(["-list", "-keystore", signing.storeFile, "-storepass:env", KEYTOOL_PASS], { [KEYTOOL_PASS]: password }))
+  const alias = signing.keyAlias ?? (aliases.length === 1 ? aliases[0] : undefined)
+  log(`${c.green("alias")}     ${alias ?? c.yellow("not set")}${aliases.length > 1 ? c.dim(`  (keys: ${aliases.join(", ")})`) : ""}`)
+  if (!alias) return
+  if (!aliases.includes(alias)) throw new CliError(`Key "${alias}" is not in the keystore (it has: ${aliases.join(", ")}).`)
+  printCertificate(signing.storeFile, alias, password)
+}
+
+/** `lecodes app keystore` — the Android release signing key: create / use <file> / info. */
+export const keystore = defineCommand({
+  name: "keystore",
+  summary: "Android release signing key: create | use <file> | info",
+  description: "The key's path + passwords live in the project .env as LECODES_ANDROID_* (or in android/keystore.properties for Studio-only builds), never in app.json — it only carries the metadata (android.signing). `lecodes app build android` refuses a release without one.",
+  commands: [
+    defineCommand({
+      name: "create",
+      summary: "Generate an Android release signing key (keytool), banked in the project .env",
+      description: "The keystore path + passwords go to the project .env (LECODES_ANDROID_KEYSTORE_FILE / _KEYSTORE_PASSWORD / _KEY_ALIAS / _KEY_PASSWORD — loaded by every lecodes run, never pushed), the metadata to app.json android.signing. Refuses to overwrite an existing key or an already configured signing setup unless --force.\n\n" + PLAY_APP_SIGNING_NOTE,
+      flags: keystoreCreateFlags,
+      examples: ["lecodes app keystore create", "lecodes app keystore create --generate --alias upload"],
+      run: ({ flags }) => keystoreCreate(flags),
+    }),
+    defineCommand({
+      name: "use",
+      summary: "Attach an existing keystore (any path; --copy puts it in android/)",
+      usage: "<file>",
+      description: "Reads the keystore's private-key entries with keytool, picks the alias (asked for with --alias when there are several), then banks the path + passwords in the project .env and the metadata in app.json android.signing — exactly what `keystore create` writes. `~/…` paths resolve against the home dir.\n\n" + PLAY_APP_SIGNING_NOTE,
+      flags: keystoreUseFlags,
+      examples: ["lecodes app keystore use ~/keys/upload.keystore", "lecodes app keystore use release.jks --alias upload --copy"],
+      run: ({ args, flags }) => keystoreUse(args[0], flags),
+    }),
+    defineCommand({
+      name: "info",
+      summary: "Which key the build signs with + its SHA-1 / SHA-256 fingerprints",
+      description: "Resolves signing exactly like the build does (android/keystore.properties first, then the LECODES_ANDROID_* environment the project .env fills) and prints the keystore, the alias and the certificate lines Play / Firebase ask for.",
+      flags: passwordFlag,
+      examples: ["lecodes app keystore info"],
+      run: ({ flags }) => keystoreInfo(flags),
+    }),
+  ],
+})
+
 /* ---------------------------------------- open ----------------------------------------- */
 
 export const openAndroid = async () => {
@@ -593,8 +991,21 @@ export const doctorAndroidChecks = async (
     } 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)
+  const signing = resolveAndroidSigning(androidDir)
+  check(!!signing, "Release signing key", "`lecodes app keystore create` or `keystore use <file>` (release builds are refused without one)", false)
+  if (signing) {
+    check(existsSync(signing.storeFile), `Keystore ${signing.storeFile}`, `named by ${signing.source} but missing`, false)
+    const incomplete = (["storePassword", "keyAlias", "keyPassword"] as const).filter(k => !signing[k])
+    check(incomplete.length === 0, `Signing complete (${signing.source})`, `missing ${incomplete.join(", ")}`, false)
+  }
+  check(!!findKeytool(), "keytool", "install a JDK or set JAVA_HOME (`lecodes app keystore …` needs it)", false)
+
+  const appGradle = join(androidDir, "app", "build.gradle.kts")
+  const gradleText = existsSync(appGradle) ? readFileSync(appGradle, "utf8") : ""
+  check(gradleText.includes("abiFilters"), "abiFilters in app/build.gradle.kts",
+    "add `ndk { abiFilters += listOf(\"arm64-v8a\", \"armeabi-v7a\") }` to defaultConfig — x86_64 devices crash at launch without it", false)
+  check(["isMinifyEnabled", "isShrinkResources"].every(k => new RegExp(`${k} = (true|false)`).test(gradleText)), "R8 block in app/build.gradle.kts",
+    "shell predates R8-by-default — see android/README.md \"Building\"", false)
 
   if (Object.keys(config.plugins ?? {}).includes("push")) {
     check(existsSync(join(androidDir, "app", "google-services.json")), "google-services.json present (push)",