lecodes-cli 0.19.0 → 0.20.0

package/src/commands/appTemplatesAndroid.ts

@@ -0,0 +1,599 @@
+/* Templates for `lecodes app init android` / `lecodes app sync` — the Android mirror of
+ * appTemplates.ts, distilled from the LetaryCreatorViewer host (lecodes-android :app). The
+ * same three ownership tiers: app/ is USER-owned after generation (init writes once, sync
+ * never touches it — except app/src/main/assets/, the Resources/ analog, and values-only
+ * versionName/versionCode restamps in app/build.gradle.kts); settings/root gradle files,
+ * lecodes-runtime/ and plugins/ are CLI-owned (sync regenerates); the gradle wrapper is
+ * written once at init. Unlike the pbxproj there is no structural-edit problem — every
+ * CLI-owned file is plain text and fully regenerated. */
+
+export const GRADLE_VERSION = "8.13"
+export const AGP_VERSION = "8.13.2"
+export const KOTLIN_VERSION = "2.1.0"
+export const COMPILE_SDK = 36
+export const MIN_SDK = 23
+export const TARGET_SDK = 36
+
+/** The fat AAR ships no POM (the ivy repository uses metadataSources { artifact() }), so the
+ *  SDK's own dependencies are declared explicitly in the generated build files. Keep in sync
+ *  with lecodes-android lecodes/build.gradle.kts per SDK release. */
+export const SDK_RUNTIME_DEPS = [
+  "androidx.core:core-ktx:1.18.0",
+  "androidx.appcompat:appcompat:1.7.1",
+  "com.squareup.okhttp3:okhttp:4.12.0",
+]
+
+/** Known app-level Gradle plugins a plugin manifest may request by bare id ("id:version" in
+ *  the manifest pins explicitly; an unknown bare id is a hard error at sync). */
+export const GRADLE_PLUGIN_VERSIONS: Record<string, string> = {
+  "com.google.gms.google-services": "4.5.0",
+}
+
+export interface AndroidShellIdentity {
+  displayName: string
+  applicationId: string
+  version: string
+  versionCode: number
+}
+
+export interface AndroidRuntimePlugin { id: string, module: string, register: string }
+
+/* ------------------------------ CLI-owned (regenerated) ------------------------------ */
+
+export const settingsGradleTemplate = (slug: string, pluginModules: string[], aarWrapperPaths: string[], sdkRepoUrl: string): string => {
+  const insecure = sdkRepoUrl.startsWith("http://")
+    ? "\n            isAllowInsecureProtocol = true   // LECODES_ANDROID_SDK_URL dev override"
+    : ""
+  const includes = pluginModules.map(m => `\ninclude(":plugins:${m}")`).join("")
+    + aarWrapperPaths.map(p => `\ninclude("${p}")`).join("")
+  return `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+        // The LeCodes Android SDK: a fat AAR attached to GitHub Releases of the dist repo,
+        // resolved straight off the release-download URL pattern (no Maven registry). The
+        // content filter keeps Gradle from probing GitHub for every other coordinate.
+        ivy {
+            url = uri("${sdkRepoUrl}")
+            patternLayout { artifact("[revision]/[artifact]-[revision].[ext]") }
+            metadataSources { artifact() }${insecure}
+            content { includeGroup("io.letary") }
+        }
+    }
+}
+rootProject.name = "${slug}"
+include(":app")
+include(":lecodes-runtime")${includes}
+`
+}
+
+export const rootBuildGradleTemplate = (extraPlugins: { id: string, version: string }[]): string => {
+  const extras = extraPlugins.map(p => `\n    id("${p.id}") version "${p.version}" apply false`).join("")
+  return `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+plugins {
+    id("com.android.application") version "${AGP_VERSION}" apply false
+    id("com.android.library") version "${AGP_VERSION}" apply false
+    id("org.jetbrains.kotlin.android") version "${KOTLIN_VERSION}" apply false${extras}
+}
+`
+}
+
+export const GRADLE_PROPERTIES = `# Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+kotlin.code.style=official
+`
+
+export const gradleWrapperProperties = (): string => `distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\\://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+`
+
+export const runtimeBuildGradleTemplate = (sdkVersion: string, pluginModules: string[], sdkArtifact = "lecodes-sdk"): string => {
+  const deps = SDK_RUNTIME_DEPS.map(d => `\n    api("${d}")`).join("")
+  const plugins = pluginModules.map(m => `\n    api(project(":plugins:${m}"))`).join("")
+  return `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+// The SDK pin lives here (\`lecodes app update\` moves it); everything is \`api\` so app code
+// sees the SDK and plugin classes through the single :lecodes-runtime dependency.
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "io.letary.lecodes.runtime"
+    compileSdk = ${COMPILE_SDK}
+    defaultConfig {
+        minSdk = ${MIN_SDK}
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+    }
+}
+
+dependencies {
+    // Exact pin — the release asset URL is derived from this artifact + version (see
+    // settings.gradle.kts). The artifact is the SDK variant sync picked (lecodes-sdk = full,
+    // -3d / -2d / -core = smaller engine builds); every variant vends the same Kotlin API.
+    api("io.letary:${sdkArtifact}:${sdkVersion}@aar")
+    // The fat AAR carries no POM, so its own dependencies ride here explicitly.${deps}${plugins}
+}
+`
+}
+
+/** lecodes-runtime/src/main/kotlin/io/letary/lecodes/runtime/LeCodesRuntime.kt — the generated
+ *  registration + host-hook surface. Plugins are called by FQN (no import collisions); the
+ *  activity hooks are always present and inert without a consuming plugin (the Android analog
+ *  of iOS's buffered LeCodesAppHooks — here the only launch-time state, a notification tap's
+ *  intent extra, survives until the host forwards it, so no buffering is needed). */
+export const runtimeKotlinTemplate = (plugins: AndroidRuntimePlugin[], projectUuid?: string): string => {
+  const identity = projectUuid ? `        engine.bootProjectUuid = "${projectUuid}"\n` : ""
+  const calls = plugins.map(p => `        ${p.register}.register(engine, context)\n`).join("")
+  const body = identity + calls
+  const push = plugins.find(p => p.id === "push")
+  const pushNs = push ? push.register.split(".").slice(0, -1).join(".") : null
+  return `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+package io.letary.lecodes.runtime
+
+import android.content.Context
+import android.content.Intent
+import io.letary.lecodes.LecodesEngine
+
+object LeCodesRuntime {
+
+    /** Register the plugins installed via app.json. Call from Activity.onCreate BEFORE the
+     *  engine runs the bundle — app code resolves plugin factories at synchronous top level. */
+    fun registerBundledPlugins(engine: LecodesEngine, context: Context) {
+${body === "" ? "        // no plugins installed\n" : body}    }
+
+    /** Cold create only (savedInstanceState == null): forward the launch intent so a plugin
+     *  can park launch-time state (a push notification tap) before the engine boots. */
+    fun onActivityLaunch(intent: Intent) {
+${push ? `        ${pushNs}.PushPlugin.parkLaunchPayload(intent)\n` : "        // no plugin consumes launch intents\n"}    }
+
+    /** Warm intent (Activity.onNewIntent). @return true when a plugin consumed it — the
+     *  caller must then SKIP its generic deep-link handling. */
+    fun onNewIntent(intent: Intent): Boolean {
+${push ? `        return ${pushNs}.PushPlugin.handleTapIntent(intent)\n` : "        return false\n"}    }
+
+    /** Activity.onResume(true) / onPause(false). */
+    fun setForeground(foreground: Boolean) {
+${push ? `        ${pushNs}.PushPlugin.setForeground(foreground)\n` : "        // no plugin tracks foreground state\n"}    }
+}
+`
+}
+
+export const pluginBuildGradleTemplate = (
+  id: string, module: string, namespace: string, sdkVersion: string,
+  dependencies: string[], aarNames: string[], hasConsumerRules: boolean,
+  sdkArtifact = "lecodes-sdk",
+): string => {
+  const consumer = hasConsumerRules ? `\n        consumerProguardFiles("consumer-rules.pro")` : ""
+  // AGP forbids direct local .aar file deps in library modules — each rides in its own
+  // generated wrapper module (libs/<name>/) consumed as a project dependency.
+  const aars = aarNames.map(n => `\n    implementation(project(":plugins:${module}:libs:${n.replace(/\.aar$/, "")}"))`).join("")
+  const sdkDeps = SDK_RUNTIME_DEPS.map(d => `\n    implementation("${d}")`).join("")
+  const manifestDeps = dependencies.map(d => d.startsWith("platform:")
+    ? `\n    implementation(platform("${d.slice("platform:".length)}"))`
+    : `\n    implementation("${d}")`).join("")
+  return `// Generated by \`lecodes app sync\` for plugin "${id}" — regenerated on every sync, do not edit.
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "${namespace}"
+    compileSdk = ${COMPILE_SDK}
+    defaultConfig {
+        minSdk = ${MIN_SDK}${consumer}
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+    }
+}
+
+dependencies {
+    // Same artifact (SDK variant) as lecodes-runtime — two different variant coordinates in one
+    // shell would put two copies of the SDK classes on the runtime classpath.
+    implementation("io.letary:${sdkArtifact}:${sdkVersion}@aar")${sdkDeps}${aars}${manifestDeps}
+}
+`
+}
+
+export const ANDROID_README = `# Android shell
+
+Generated by \`lecodes app init android\`. Daily workflow:
+
+\`\`\`
+lecodes app sync            # embed the compiled bundle + plugins into this shell
+lecodes app open android    # open in Android Studio
+lecodes app build android   # signed release APK + AAB (gradlew assembleRelease bundleRelease)
+\`\`\`
+
+## Ownership
+
+| Path | Owner |
+| --- | --- |
+| \`app/\` (sources, manifest, res, build.gradle.kts) | **Yours** after init — sync never rewrites them (it only restamps \`versionName\`/\`versionCode\` values, manages \`// lecodes:plugin\`-tagged lines in the plugins block, and — when \`app.json\` sets \`"icon"\` — the icon files below) |
+| \`app/src/main/assets/\` | CLI-owned — wiped and regenerated by every sync (the compiled \`app.js\` + its \`// preload:\` assets) |
+| \`res/mipmap-*/ic_launcher*\`, \`res/values/lecodes_icon.xml\` | CLI-owned **only when** \`app.json\` sets \`"icon"\` — regenerated by every sync (plus a value-only \`android:icon\` restamp in the manifest); without the key sync never touches icons |
+| \`settings.gradle.kts\`, \`build.gradle.kts\` (root), \`gradle.properties\`, \`lecodes-runtime/\`, \`plugins/\` | CLI-owned — regenerated by every sync |
+| \`gradle/\`, \`gradlew\`, \`gradlew.bat\` | Written once at init |
+
+## The SDK
+
+\`lecodes-runtime/build.gradle.kts\` pins the exact \`io.letary:lecodes-sdk\` release, resolved
+from the GitHub Releases of \`letary/lecodes-android-sdk\` through the ivy repository declared
+in \`settings.gradle.kts\`. \`lecodes app update\` moves the pin (or set \`app.json\`
+\`android.sdk\`). The SDK AAR ships no POM, so its own dependencies are declared explicitly in
+the generated runtime build file.
+
+## SDK variant
+
+Sync links the smallest SDK artifact covering the engines the compiled bundle actually uses —
+\`lecodes-sdk\` (full: 3D+2D), \`lecodes-sdk-3d\`, \`lecodes-sdk-2d\` or \`lecodes-sdk-core\`
+(UI only) — so an app without 3D scenes doesn't ship Filament. If the project starts using an
+engine, sync switches automatically on the next run; set \`android.variant\` in \`../app.json\`
+to force one (needs lecodes-android-sdk >= 1.3.0; older releases ship only the full AAR).
+
+Physics, navigation meshes and multiplayer ship in \`lecodes-sdk\` (full) ONLY —
+\`lecodes-sdk-3d\` is 3D rendering without the game stack. Auto-selection reads which RENDERING
+engines the bundle uses and cannot see those, so a project using \`Physics\`,
+\`CharacterController\`, \`NavMesh\` or networking must set \`android.variant: "full"\` in
+\`../app.json\` — otherwise those aspects silently do nothing on device.
+
+## App-local native code
+
+Drop Kotlin files into \`app/src/main/java/\` and register them in \`MainActivity\` after the
+\`LeCodesRuntime.registerBundledPlugins(...)\` call — \`engine.registerCallback\` for sync
+globals, \`engine.registerService\`/\`registerView\` for channels (see the SDK docs). Add any
+dependencies they need to \`app/build.gradle.kts\` — that file is yours.
+
+## Release signing
+
+Create \`android/keystore.properties\` (gitignored):
+
+\`\`\`
+storeFile=release.keystore
+storePassword=…
+keyAlias=…
+keyPassword=…
+\`\`\`
+
+or export \`LECODES_ANDROID_KEYSTORE_FILE\` / \`LECODES_ANDROID_KEYSTORE_PASSWORD\` /
+\`LECODES_ANDROID_KEY_ALIAS\` / \`LECODES_ANDROID_KEY_PASSWORD\`. Never put passwords in app.json.
+
+## Icons
+
+The easy path: set \`app.json\` \`"icon"\` to a square ≥1024px PNG/JPEG in the project (e.g.
+\`"icon": "icon.png"\`, optional \`"iconBackground": "#RRGGBB"\` — the adaptive-icon backdrop,
+default white). Every \`lecodes app sync\` then renders the full launcher set: legacy density
+PNGs, the API 26+ adaptive icon (your image at 72dp on the 108dp canvas), and an Android 13
+themed-icon (monochrome) layer that reuses the foreground silhouette.
+
+Prefer hand-made icons? Leave \`"icon"\` unset and use Android Studio (right-click \`res\` →
+New → Image Asset) — sync never touches icon files then. \`drawable/ic_launcher.xml\` is only
+the init-time placeholder.
+
+## Notes
+
+- No native OTA on Android yet — app.json \`"update"\` is ignored for this shell (iOS-only).
+- Push: the notification service needs \`app/google-services.json\` from the le.codes Firebase
+  project; \`lecodes app sync\` applies the google-services Gradle plugin only when that file
+  exists (and warns otherwise).
+`
+
+/* ---------------------------- USER-owned (written once) ---------------------------- */
+
+export const appBuildGradleTemplate = ({ applicationId, version, versionCode }: AndroidShellIdentity): string => `import java.util.Properties
+
+// Generated by \`lecodes app init\` — yours to edit. \`lecodes app sync\` only restamps the
+// versionName/versionCode VALUES and manages \`// lecodes:plugin\`-tagged lines in the plugins
+// block below; everything else is left alone.
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+// Release signing: android/keystore.properties (gitignored) or LECODES_ANDROID_* env vars —
+// see README.md. Without either, release builds come out unsigned.
+val keystoreProps = Properties().apply {
+    val f = rootProject.file("keystore.properties")
+    if (f.exists()) f.inputStream().use { load(it) }
+}
+fun signing(key: String, env: String): String? = keystoreProps.getProperty(key) ?: System.getenv(env)
+
+android {
+    namespace = "${applicationId}"
+    compileSdk = ${COMPILE_SDK}
+
+    defaultConfig {
+        applicationId = "${applicationId}"
+        minSdk = ${MIN_SDK}
+        targetSdk = ${TARGET_SDK}
+        versionCode = ${versionCode}
+        versionName = "${version}"
+    }
+
+    val storeFilePath = signing("storeFile", "LECODES_ANDROID_KEYSTORE_FILE")
+    if (storeFilePath != null) {
+        signingConfigs.create("release") {
+            storeFile = rootProject.file(storeFilePath)
+            storePassword = signing("storePassword", "LECODES_ANDROID_KEYSTORE_PASSWORD")
+            keyAlias = signing("keyAlias", "LECODES_ANDROID_KEY_ALIAS")
+            keyPassword = signing("keyPassword", "LECODES_ANDROID_KEY_PASSWORD")
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            signingConfig = signingConfigs.findByName("release")
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+    }
+}
+
+dependencies {
+    implementation(project(":lecodes-runtime"))
+    // App-local native code deps go here — this file is yours after init.
+}
+`
+
+export const appManifestTemplate = (): string => `<?xml version="1.0" encoding="utf-8"?>
+<!-- Generated by \`lecodes app init\` — yours to edit. Sync leaves it alone, except that with
+     app.json "icon" set it restamps the android:icon VALUE to the generated @mipmap set.
+     Plugin permissions/services arrive through the plugin modules' own manifests via the AGP
+     manifest merger, so installing/removing plugins needs no edits here. -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@drawable/ic_launcher"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.LeCodesApp">
+        <!-- singleTask: a warm deep link re-enters the SAME instance via onNewIntent (the "url"
+             app event) instead of stacking a second activity with its own engine. -->
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTask"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- le.codes/qr deep links (QR scans, notification taps). Editable — remove if the
+                 app should not claim them. -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" />
+                <data android:scheme="http" />
+                <data android:host="le.codes" />
+                <data android:pathPrefix="/qr" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>
+`
+
+export const mainActivityTemplate = (pkg: string): string => `//
+//  MainActivity.kt
+//  Generated by lecodes app init — yours to edit.
+//
+//  Runs the bundled app.js (produced by \`lecodes app sync\`) offline: everything the script
+//  needs is provided by the SDK core plus the plugins registered via LeCodesRuntime.
+//
+
+package ${pkg}
+
+import android.content.Intent
+import android.os.Bundle
+import android.view.KeyEvent
+import androidx.appcompat.app.AppCompatActivity
+import androidx.lifecycle.ViewModelProvider
+import io.letary.lecodes.LeCodesView
+import io.letary.lecodes.runtime.LeCodesRuntime
+
+class MainActivity : AppCompatActivity() {
+
+    lateinit var viewModel: AppViewModel
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        viewModel = ViewModelProvider(this)[AppViewModel::class.java]
+        setContentView(LeCodesView(engine = viewModel.engine, context = applicationContext))
+
+        viewModel.engine.setLanguage(resources.configuration.locales[0]?.language ?: "en")
+
+        // Plugins BEFORE the engine runs the bundle — app code resolves plugin factories at
+        // synchronous top level.
+        LeCodesRuntime.registerBundledPlugins(viewModel.engine, applicationContext)
+
+        // A cold start from a notification tap parks its payload BEFORE the engine boots (inert
+        // without the push plugin). Only on a fresh creation — a recreation must not re-park.
+        if (savedInstanceState == null) {
+            LeCodesRuntime.onActivityLaunch(intent)
+        }
+
+        // BEFORE onActivityCreate: the bundle reads the launch link synchronously at boot.
+        viewModel.engine.setLaunchUrl(intent.data?.toString())
+
+        viewModel.onActivityCreate(this)
+        // System back is wired inside engine.attach() (SDK >= 1.2.0): widget → destination →
+        // pager → router; an unhandled press is swallowed. To leave the app on unhandled back
+        // instead: viewModel.engine.onUnhandledBackPressed = { moveTaskToBack(true) }
+    }
+
+    // Physical-key state for Input.key(). Record, never consume.
+    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+        viewModel.engine.handleKeyEvent(event)
+        return super.dispatchKeyEvent(event)
+    }
+
+    override fun onResume() {
+        super.onResume()
+        LeCodesRuntime.setForeground(true)
+        viewModel.engine.resume()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        LeCodesRuntime.setForeground(false)
+        viewModel.engine.pause()
+    }
+
+    // Warm deep link (the activity is singleTask). A consumed intent (a notification tap the
+    // push plugin routed) must SKIP the generic path — a same-project tap must not reload the
+    // running app through its own link.
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        if (LeCodesRuntime.onNewIntent(intent)) return
+        val url = intent.data?.toString() ?: return
+        viewModel.engine.emitUrl(url)
+    }
+}
+`
+
+export const appViewModelTemplate = (pkg: string): string => `//
+//  AppViewModel.kt
+//  Generated by lecodes app init — yours to edit.
+//
+//  The engine lives here so it survives configuration changes (rotation recreates the
+//  Activity, not the ViewModel); onCleared is the one "never coming back" signal where the
+//  engine's system registrations are released.
+//
+
+package ${pkg}
+
+import android.app.Activity
+import android.app.Application
+import androidx.lifecycle.AndroidViewModel
+import io.letary.lecodes.LecodesEngine
+
+class AppViewModel(application: Application) : AndroidViewModel(application) {
+
+    val engine: LecodesEngine = LecodesEngine(application.applicationContext)
+
+    init {
+        // \`// preload:\` assets (images, fonts) resolve out of app/src/main/assets/ —
+        // \`lecodes app sync\` copies them there flat by name.
+        engine.onFetchLocal = { path ->
+            getApplication<Application>().assets.open(path).use { it.readBytes() }
+        }
+    }
+
+    override fun onCleared() {
+        engine.dispose()
+        super.onCleared()
+    }
+
+    private var isCreated = false
+    fun onActivityCreate(activity: Activity) {
+        engine.attach(activity)
+        if (!isCreated) {
+            val code = getApplication<Application>().assets.open("app.js").bufferedReader().use { it.readText() }
+            engine.run(code)
+            isCreated = true
+        }
+    }
+}
+`
+
+export const themesXmlTemplate = (): string => `<resources>
+    <style name="Theme.LeCodesApp" parent="Theme.AppCompat.Light.NoActionBar">
+        <item name="android:windowTranslucentNavigation">true</item>
+        <item name="android:statusBarColor">@android:color/transparent</item>
+        <item name="android:windowNoTitle">true</item>
+        <item name="android:windowTranslucentStatus">true</item>
+        <item name="android:windowBackground">@color/black</item>
+    </style>
+</resources>
+`
+
+export const COLORS_XML = `<resources>
+    <color name="black">#FF000000</color>
+</resources>
+`
+
+export const stringsXmlTemplate = (name: string): string => `<resources>
+    <string name="app_name">${name.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/'/g, "\\'")}</string>
+</resources>
+`
+
+/** Placeholder launcher icon — a plain vector (valid from API 21, no adaptive/mipmap set, no
+ *  binary assets). README points at Android Studio's Image Asset tool for the real one. */
+export const IC_LAUNCHER_XML = `<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#FF000000"
+        android:pathData="M0,0h108v108h-108z"/>
+    <path
+        android:fillColor="#FFFFFFFF"
+        android:pathData="M34,38 h40 a4,4 0 0 1 4,4 v24 a4,4 0 0 1 -4,4 h-40 a4,4 0 0 1 -4,-4 v-24 a4,4 0 0 1 4,-4 z M38,44 v20 h32 v-20 z"/>
+</vector>
+`
+
+export const ANDROID_GITIGNORE = `.gradle/
+build/
+local.properties
+keystore.properties
+*.keystore
+`
+
+/** libs/<name>/build.gradle.kts — wraps a plugin's local AAR as a consumable artifact
+ *  (the AGP-supported alternative to direct local .aar file deps in library modules). */
+export const aarWrapperBuildGradle = (aarName: string): string => `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
+configurations.maybeCreate("default")
+artifacts.add("default", file("${aarName}"))
+`

package/src/commands/appTemplatesGradlew.ts

@@ -0,0 +1,9 @@
+/* Gradle wrapper launcher scripts, verbatim from the gradle/gradle v8.13.0 tag (the same
+ * pinned source as the wrapper jar download in appAndroid.ts). JSON-escaped mechanically —
+ * regenerate from the tag rather than editing. gradlew must be written with LF and
+ * gradlew.bat with CRLF (initAndroid handles the conversion); both are version-agnostic
+ * launchers that read gradle/wrapper/gradle-wrapper.properties for the real distribution. */
+
+export const GRADLEW_SH: string = "#!/bin/sh\n\n#\n# Copyright © 2015-2021 the original authors.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n#      https://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n#\n# SPDX-License-Identifier: Apache-2.0\n#\n\n##############################################################################\n#\n#   Gradle start up script for POSIX generated by Gradle.\n#\n#   Important for running:\n#\n#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is\n#       noncompliant, but you have some other compliant shell such as ksh or\n#       bash, then to run this script, type that shell name before the whole\n#       command line, like:\n#\n#           ksh Gradle\n#\n#       Busybox and similar reduced shells will NOT work, because this script\n#       requires all of these POSIX shell features:\n#         * functions;\n#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,\n#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;\n#         * compound commands having a testable exit status, especially «case»;\n#         * various built-in commands including «command», «set», and «ulimit».\n#\n#   Important for patching:\n#\n#   (2) This script targets any POSIX shell, so it avoids extensions provided\n#       by Bash, Ksh, etc; in particular arrays are avoided.\n#\n#       The \"traditional\" practice of packing multiple parameters into a\n#       space-separated string is a well documented source of bugs and security\n#       problems, so this is (mostly) avoided, by progressively accumulating\n#       options in \"$@\", and eventually passing that to Java.\n#\n#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,\n#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;\n#       see the in-line comments for details.\n#\n#       There are tweaks for specific operating systems such as AIX, CygWin,\n#       Darwin, MinGW, and NonStop.\n#\n#   (3) This script is generated from the Groovy template\n#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt\n#       within the Gradle project.\n#\n#       You can find Gradle at https://github.com/gradle/gradle/.\n#\n##############################################################################\n\n# Attempt to set APP_HOME\n\n# Resolve links: $0 may be a link\napp_path=$0\n\n# Need this for daisy-chained symlinks.\nwhile\n    APP_HOME=${app_path%\"${app_path##*/}\"}  # leaves a trailing /; empty if no leading path\n    [ -h \"$app_path\" ]\ndo\n    ls=$( ls -ld \"$app_path\" )\n    link=${ls#*' -> '}\n    case $link in             #(\n      /*)   app_path=$link ;; #(\n      *)    app_path=$APP_HOME$link ;;\n    esac\ndone\n\n# This is normally unused\n# shellcheck disable=SC2034\nAPP_BASE_NAME=${0##*/}\n# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)\nAPP_HOME=$( cd -P \"${APP_HOME:-./}\" > /dev/null && printf '%s\\n' \"$PWD\" ) || exit\n\n# Use the maximum available, or set MAX_FD != -1 to use that value.\nMAX_FD=maximum\n\nwarn () {\n    echo \"$*\"\n} >&2\n\ndie () {\n    echo\n    echo \"$*\"\n    echo\n    exit 1\n} >&2\n\n# OS specific support (must be 'true' or 'false').\ncygwin=false\nmsys=false\ndarwin=false\nnonstop=false\ncase \"$( uname )\" in                #(\n  CYGWIN* )         cygwin=true  ;; #(\n  Darwin* )         darwin=true  ;; #(\n  MSYS* | MINGW* )  msys=true    ;; #(\n  NONSTOP* )        nonstop=true ;;\nesac\n\nCLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar\n\n\n# Determine the Java command to use to start the JVM.\nif [ -n \"$JAVA_HOME\" ] ; then\n    if [ -x \"$JAVA_HOME/jre/sh/java\" ] ; then\n        # IBM's JDK on AIX uses strange locations for the executables\n        JAVACMD=$JAVA_HOME/jre/sh/java\n    else\n        JAVACMD=$JAVA_HOME/bin/java\n    fi\n    if [ ! -x \"$JAVACMD\" ] ; then\n        die \"ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME\n\nPlease set the JAVA_HOME variable in your environment to match the\nlocation of your Java installation.\"\n    fi\nelse\n    JAVACMD=java\n    if ! command -v java >/dev/null 2>&1\n    then\n        die \"ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.\n\nPlease set the JAVA_HOME variable in your environment to match the\nlocation of your Java installation.\"\n    fi\nfi\n\n# Increase the maximum file descriptors if we can.\nif ! \"$cygwin\" && ! \"$darwin\" && ! \"$nonstop\" ; then\n    case $MAX_FD in #(\n      max*)\n        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.\n        # shellcheck disable=SC2039,SC3045\n        MAX_FD=$( ulimit -H -n ) ||\n            warn \"Could not query maximum file descriptor limit\"\n    esac\n    case $MAX_FD in  #(\n      '' | soft) :;; #(\n      *)\n        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.\n        # shellcheck disable=SC2039,SC3045\n        ulimit -n \"$MAX_FD\" ||\n            warn \"Could not set maximum file descriptor limit to $MAX_FD\"\n    esac\nfi\n\n# Collect all arguments for the java command, stacking in reverse order:\n#   * args from the command line\n#   * the main class name\n#   * -classpath\n#   * -D...appname settings\n#   * --module-path (only if needed)\n#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.\n\n# For Cygwin or MSYS, switch paths to Windows format before running java\nif \"$cygwin\" || \"$msys\" ; then\n    APP_HOME=$( cygpath --path --mixed \"$APP_HOME\" )\n    CLASSPATH=$( cygpath --path --mixed \"$CLASSPATH\" )\n\n    JAVACMD=$( cygpath --unix \"$JAVACMD\" )\n\n    # Now convert the arguments - kludge to limit ourselves to /bin/sh\n    for arg do\n        if\n            case $arg in                                #(\n              -*)   false ;;                            # don't mess with options #(\n              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath\n                    [ -e \"$t\" ] ;;                      #(\n              *)    false ;;\n            esac\n        then\n            arg=$( cygpath --path --ignore --mixed \"$arg\" )\n        fi\n        # Roll the args list around exactly as many times as the number of\n        # args, so each arg winds up back in the position where it started, but\n        # possibly modified.\n        #\n        # NB: a `for` loop captures its iteration list before it begins, so\n        # changing the positional parameters here affects neither the number of\n        # iterations, nor the values presented in `arg`.\n        shift                   # remove old arg\n        set -- \"$@\" \"$arg\"      # push replacement arg\n    done\nfi\n\n\n# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.\nDEFAULT_JVM_OPTS='-Dfile.encoding=UTF-8 \"-Xmx64m\" \"-Xms64m\"'\n\n# Collect all arguments for the java command:\n#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,\n#     and any embedded shellness will be escaped.\n#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be\n#     treated as '${Hostname}' itself on the command line.\n\nset -- \\\n        \"-Dorg.gradle.appname=$APP_BASE_NAME\" \\\n        -classpath \"$CLASSPATH\" \\\n        org.gradle.wrapper.GradleWrapperMain \\\n        \"$@\"\n\n# Stop when \"xargs\" is not available.\nif ! command -v xargs >/dev/null 2>&1\nthen\n    die \"xargs is not available\"\nfi\n\n# Use \"xargs\" to parse quoted args.\n#\n# With -n1 it outputs one arg per line, with the quotes and backslashes removed.\n#\n# In Bash we could simply go:\n#\n#   readarray ARGS < <( xargs -n1 <<<\"$var\" ) &&\n#   set -- \"${ARGS[@]}\" \"$@\"\n#\n# but POSIX shell has neither arrays nor command substitution, so instead we\n# post-process each arg (as a line of input to sed) to backslash-escape any\n# character that might be a shell metacharacter, then use eval to reverse\n# that process (while maintaining the separation between arguments), and wrap\n# the whole thing up as a single \"set\" statement.\n#\n# This will of course break if any of these variables contains a newline or\n# an unmatched quote.\n#\n\neval \"set -- $(\n        printf '%s\\n' \"$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS\" |\n        xargs -n1 |\n        sed ' s~[^-[:alnum:]+,./:=@_]~\\\\&~g; ' |\n        tr '\\n' ' '\n    )\" '\"$@\"'\n\nexec \"$JAVACMD\" \"$@\"\n"
+
+export const GRADLEW_BAT: string = "@rem\n@rem Copyright 2015 the original author or authors.\n@rem\n@rem Licensed under the Apache License, Version 2.0 (the \"License\");\n@rem you may not use this file except in compliance with the License.\n@rem You may obtain a copy of the License at\n@rem\n@rem      https://www.apache.org/licenses/LICENSE-2.0\n@rem\n@rem Unless required by applicable law or agreed to in writing, software\n@rem distributed under the License is distributed on an \"AS IS\" BASIS,\n@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n@rem See the License for the specific language governing permissions and\n@rem limitations under the License.\n@rem\n@rem SPDX-License-Identifier: Apache-2.0\n@rem\n\n@if \"%DEBUG%\"==\"\" @echo off\n@rem ##########################################################################\n@rem\n@rem  Gradle startup script for Windows\n@rem\n@rem ##########################################################################\n\n@rem Set local scope for the variables with windows NT shell\nif \"%OS%\"==\"Windows_NT\" setlocal\n\nset DIRNAME=%~dp0\nif \"%DIRNAME%\"==\"\" set DIRNAME=.\n@rem This is normally unused\nset APP_BASE_NAME=%~n0\nset APP_HOME=%DIRNAME%\n\n@rem Resolve any \".\" and \"..\" in APP_HOME to make it shorter.\nfor %%i in (\"%APP_HOME%\") do set APP_HOME=%%~fi\n\n@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.\nset DEFAULT_JVM_OPTS=-Dfile.encoding=UTF-8 \"-Xmx64m\" \"-Xms64m\"\n\n@rem Find java.exe\nif defined JAVA_HOME goto findJavaFromJavaHome\n\nset JAVA_EXE=java.exe\n%JAVA_EXE% -version >NUL 2>&1\nif %ERRORLEVEL% equ 0 goto execute\n\necho. 1>&2\necho ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2\necho. 1>&2\necho Please set the JAVA_HOME variable in your environment to match the 1>&2\necho location of your Java installation. 1>&2\n\ngoto fail\n\n:findJavaFromJavaHome\nset JAVA_HOME=%JAVA_HOME:\"=%\nset JAVA_EXE=%JAVA_HOME%/bin/java.exe\n\nif exist \"%JAVA_EXE%\" goto execute\n\necho. 1>&2\necho ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2\necho. 1>&2\necho Please set the JAVA_HOME variable in your environment to match the 1>&2\necho location of your Java installation. 1>&2\n\ngoto fail\n\n:execute\n@rem Setup the command line\n\nset CLASSPATH=%APP_HOME%\\gradle\\wrapper\\gradle-wrapper.jar\n\n\n@rem Execute Gradle\n\"%JAVA_EXE%\" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% \"-Dorg.gradle.appname=%APP_BASE_NAME%\" -classpath \"%CLASSPATH%\" org.gradle.wrapper.GradleWrapperMain %*\n\n:end\n@rem End local scope for the variables with windows NT shell\nif %ERRORLEVEL% equ 0 goto mainEnd\n\n:fail\nrem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of\nrem the _cmd.exe /c_ return code!\nset EXIT_CODE=%ERRORLEVEL%\nif %EXIT_CODE% equ 0 set EXIT_CODE=1\nif not \"\"==\"%GRADLE_EXIT_CONSOLE%\" exit %EXIT_CODE%\nexit /b %EXIT_CODE%\n\n:mainEnd\nif \"%OS%\"==\"Windows_NT\" endlocal\n\n:omega\n"

package/src/commands/assets.ts

@@ -0,0 +1,28 @@
+import { CliError, type Args } from "../util"
+import { resolveCmgenExe } from "../cmgenTool"
+
+/*
+ * `lecodes assets <convert|probe|doctor|sky> …` — the LeCodes asset pipeline (packages/lecodes-assets):
+ * FBX → GLB (ufbx wasm + glTF-Transform), `--clips` merged by bone name, textures embedded, GLB
+ * doctor (bone cap / texture normalize / KTX2). The package is an optional peer (like the design
+ * board and the renderer); its own argv parser handles the sub-command flags, so the raw argv is
+ * forwarded untouched (`assets` gets `_raw` from main). See docs/animation-plan.md §2.9.
+ */
+export const assets = async (args: Args & { _raw?: string[] }) => {
+  let mod: typeof import("lecodes-assets/cli")
+  try {
+    mod = await import("lecodes-assets/cli")
+  } catch {
+    throw new CliError("The asset pipeline isn't installed. Run:  npm install -g lecodes-assets")
+  }
+  const raw = args._raw ?? args._
+  // `sky` shells out to filament's cmgen, which the asset package deliberately never downloads
+  // itself (it stays network-free and usable standalone). The CLI owns release artifacts, so it
+  // resolves the binary — cache or first-use download — and hands it over through the env var the
+  // package already honours. An explicit LECODES_CMGEN wins, so a local filament build still rules.
+  if (raw[0] === "sky" && !process.env.LECODES_CMGEN) {
+    process.env.LECODES_CMGEN = await resolveCmgenExe()
+  }
+  const code = await mod.runAssetsCli(raw)
+  if (code !== 0) process.exitCode = code
+}