create-cmp-cli 0.2.0

package/template/iosApp/iosApp/iOSApp.swift

@@ -0,0 +1,33 @@
+import SwiftUI
+import ComposeApp
+// >>> cmp:feature firebase
+import FirebaseCore
+// <<< cmp:feature firebase
+
+@main
+struct iOSApp: App {
+
+    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+
+class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool {
+        // >>> cmp:feature firebase
+        // Firebase native init (GitLive wraps the native SDK; reads GoogleService-Info.plist).
+        // MUST run before doInitKoin(), which wires the GitLive emulators.
+        FirebaseApp.configure()
+        // <<< cmp:feature firebase
+        // Koin initialisation for iOS.
+        KoinHelperKt.doInitKoin()
+        return true
+    }
+}

package/template/iosApp/project.yml

@@ -0,0 +1,56 @@
+name: iosApp
+options:
+  bundleIdPrefix: __IOS_BUNDLE_ID__
+  deploymentTarget:
+    iOS: "16.0"
+  createIntermediateGroups: true
+
+settings:
+  base:
+    SWIFT_VERSION: "5.0"
+    DEVELOPMENT_TEAM: ""
+    CODE_SIGN_STYLE: Automatic
+
+targets:
+  iosApp:
+    type: application
+    platform: iOS
+    sources:
+      - path: iosApp
+    info:
+      path: iosApp/Info.plist
+      properties:
+        CFBundleDisplayName: __APP_NAME__
+        CFBundleShortVersionString: "1.0"
+        CFBundleVersion: "1"
+        # Required by Compose Multiplatform on iOS (high-refresh-rate displays);
+        # the app crashes at launch (PlistSanityCheck) without it.
+        CADisableMinimumFrameDurationOnPhone: true
+        UILaunchScreen: {}
+        UISupportedInterfaceOrientations:
+          - UIInterfaceOrientationPortrait
+        UIApplicationSceneManifest:
+          UIApplicationSupportsMultipleScenes: false
+        NSCameraUsageDescription: "__APP_NAME__ uses the camera to capture photos."
+        NSPhotoLibraryUsageDescription: "__APP_NAME__ lets you attach photos to your profile."
+        NSLocationWhenInUseUsageDescription: "__APP_NAME__ uses your location to show nearby content."
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: __IOS_BUNDLE_ID__
+        PRODUCT_NAME: iosApp
+        ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon
+        ENABLE_USER_SCRIPT_SANDBOXING: NO
+        # KMP framework search path (populated by embedAndSignAppleFrameworkForXcode)
+        FRAMEWORK_SEARCH_PATHS:
+          - $(inherited)
+          - $(SRCROOT)/../composeApp/build/xcode-frameworks/$(CONFIGURATION)/$(SDK_NAME)
+        OTHER_LDFLAGS:
+          - $(inherited)
+          - -framework
+          - ComposeApp
+    preBuildScripts:
+      - name: "Compile & embed KMP framework (ComposeApp)"
+        basedOnDependencyAnalysis: false
+        script: |
+          cd "$SRCROOT/.."
+          ./gradlew :composeApp:embedAndSignAppleFrameworkForXcode

package/template/local.properties.example

@@ -0,0 +1,2 @@
+# Copy to local.properties and set your Android SDK location.
+sdk.dir=/Users/you/Library/Android/sdk

package/template/manifest.json

@@ -0,0 +1,125 @@
+{
+  "templateVersion": "1.0.0",
+  "description": "Golden Compose Multiplatform skeleton (green on Android + iOS). Stamp via token replacement + package-dir rename + feature-marker stripping.",
+  "placeholders": [
+    "__APP_NAME__",
+    "__PACKAGE__",
+    "__PACKAGE_PATH__",
+    "__IOS_BUNDLE_ID__",
+    "__REGION__",
+    "__THEME_PREFIX__"
+  ],
+  "placeholderNotes": {
+    "__APP_NAME__": "Human display name (Android label, iOS CFBundleDisplayName, Gradle rootProject.name). NOTE: rootProject.name in settings.gradle.kts cannot contain spaces — the engine must slugify the app name there (e.g. 'My App' -> 'MyApp' or 'my-app'). Used as a plain string elsewhere.",
+    "__PACKAGE__": "Reverse-DNS package id, e.g. com.acme.app. Replaces BOTH the Android namespace/applicationId AND every Kotlin `package`/`import` statement in file CONTENTS. Also used as iOS bundle id default.",
+    "__PACKAGE_PATH__": "Slash form of __PACKAGE__ (com/acme/app). Appears only inside string replacements where a path is needed; package SOURCE DIRECTORIES are stored literally as com/example/app and renamed by the engine (see packageSourceRoots + renameDirs).",
+    "__IOS_BUNDLE_ID__": "iOS bundle id (project.yml PRODUCT_BUNDLE_IDENTIFIER + bundleIdPrefix, Info.plist, GoogleService-Info.plist).",
+    "__REGION__": "Firebase Cloud Functions region, e.g. us-central1 (data/remote/FirebaseConfig.kt FIREBASE_FUNCTIONS_REGION).",
+    "__THEME_PREFIX__": "PascalCase theme symbol prefix (e.g. AcmeTheme, AcmeColors, AcmeTokens, AcmeShapes, rememberAcmeTypography)."
+  },
+  "tokenizationNotes": [
+    "Replace tokens in BOTH file contents and file/dir paths.",
+    "Package source directories are stored literally as `.../kotlin/com/example/app`. The engine renames the `com/example/app` segment to __PACKAGE_PATH__ for each root in packageSourceRoots. File CONTENTS use __PACKAGE__ in package/import lines (already tokenized).",
+    "The generated Compose resources accessor package is PINNED in composeApp/build.gradle.kts via `compose.resources { packageOfResClass = \"__PACKAGE__.generated.resources\" }`, so resource imports are stable and do NOT depend on rootProject.name. Do not remove that block.",
+    "Replacement order is safe because all tokens are distinct literals; replace __PACKAGE_PATH__ and __PACKAGE__ independently."
+  ],
+  "packageSourceRoots": [
+    "composeApp/src/commonMain/kotlin",
+    "composeApp/src/androidMain/kotlin",
+    "composeApp/src/androidDebug/kotlin",
+    "composeApp/src/androidRelease/kotlin",
+    "composeApp/src/iosMain/kotlin",
+    "composeApp/src/desktopMain/kotlin"
+  ],
+  "renameDirs": {
+    "literalSegment": "com/example/app",
+    "replaceWith": "__PACKAGE_PATH__",
+    "appliesTo": "each entry in packageSourceRoots"
+  },
+  "binaryAssets": [
+    "gradle/wrapper/gradle-wrapper.jar",
+    "composeApp/src/commonMain/composeResources/font/DMSans_Regular.ttf",
+    "composeApp/src/commonMain/composeResources/font/DMSans_Medium.ttf",
+    "composeApp/src/commonMain/composeResources/font/DMSans_SemiBold.ttf",
+    "composeApp/src/commonMain/composeResources/font/DMSans_Bold.ttf",
+    "composeApp/src/androidMain/res/mipmap-*/ic_launcher*.png",
+    "iosApp/iosApp/Assets.xcassets/**/*.png"
+  ],
+  "featureMarkers": {
+    "syntax": "// >>> cmp:feature <name>  ...  // <<< cmp:feature <name>",
+    "negation": "A name prefixed with ! (e.g. `cmp:feature !firebase`) marks a block kept ONLY when that feature is DISABLED. When the feature is ENABLED, the engine removes the whole negated block (markers + body); when DISABLED, it strips just the negated markers and keeps the body. Plain (non-negated) blocks are the inverse.",
+    "nesting": "Blocks may nest (e.g. `room` containing `ios` in composeApp/build.gradle.kts and KoinHelper.kt). Process as a stack: a child block is dropped if it OR any ancestor is dropped.",
+    "commentStyles": "Markers appear as Kotlin/Swift `//` comments, Ruby `#` comments (iosApp/Podfile), and could be any line-comment; match on the `cmp:feature` substring, not a fixed comment prefix.",
+    "whenEnabled": "Strip only the two marker lines, keep the body.",
+    "whenDisabled": "Remove the marker lines AND the body between them."
+  },
+  "features": {
+    "ios": {
+      "enabledByDefault": true,
+      "paths": [
+        "iosApp",
+        "composeApp/src/iosMain"
+      ],
+      "notes": "When off: delete the listed paths AND strip the `ios` marker blocks from composeApp/build.gradle.kts (iosX64/iosArm64/iosSimulatorArm64 targets, iosMain deps, ios KSP room.compiler rows, ExperimentalForeignApi optIn). Also drop iosApp from the build/verify."
+    },
+    "firebase": {
+      "enabledByDefault": true,
+      "paths": [
+        "composeApp/google-services.json",
+        "iosApp/iosApp/GoogleService-Info.plist"
+      ],
+      "notes": "GitLive deps + emulator wiring. When off: strip `firebase` marker blocks in composeApp/build.gradle.kts (GitLive deps + the google-services plugin + the firebase debug/release buildTypes), build.gradle.kts (google-services plugin), AppApplication.kt, KoinHelper.kt, iOSApp.swift, iosApp/Podfile; and KEEP the `!firebase` blocks in composeApp/build.gradle.kts (the no-Firebase debug/release buildTypes). Remove google-services.json + GoogleService-Info.plist. data/remote/FirebaseConfig.kt holds only a const and is harmless to leave, but may be removed. The google-services plugin REQUIRES a google-services.json whose client.android_client_info.package_name matches applicationId — the template ships a structurally-valid placeholder with __PACKAGE__ already in that field; instruct the user to replace it with the real file from the Firebase console."
+    },
+    "room": {
+      "enabledByDefault": true,
+      "paths": [
+        "composeApp/src/commonMain/kotlin/com/example/app/data/local",
+        "composeApp/src/androidMain/kotlin/com/example/app/data/local",
+        "composeApp/src/iosMain/kotlin/com/example/app/data/local",
+        "composeApp/src/desktopMain/kotlin/com/example/app/data/local",
+        "composeApp/schemas"
+      ],
+      "notes": "When off: strip `room` marker blocks in build.gradle.kts (ksp + room plugins), composeApp/build.gradle.kts (room/sqlite deps, kspAndroid/kspIos/kspDesktop room.compiler, the room {} schema block), AppApplication.kt, KoinHelper.kt and DesktopModule.kt (AppDatabase single + appContext). Delete the data/local dirs (incl. the desktopMain one when dev-client is on). The example `home` feature does NOT depend on Room (its ItemRepositoryImpl is in-memory), so it keeps building with Room off."
+    },
+    "appium": {
+      "enabledByDefault": true,
+      "paths": [
+        "qa/appium",
+        "tests/appium"
+      ],
+      "notes": "Appium harness (Python conftest + smoke, JS client + smoke runner). No in-file markers; toggled by deleting the listed paths."
+    },
+    "inspector": {
+      "enabledByDefault": true,
+      "paths": [
+        "composeApp/src/androidDebug/kotlin/com/example/app/inspector",
+        "composeApp/src/androidRelease/kotlin/com/example/app/inspector"
+      ],
+      "notes": "Live on-device inspector: debug-only loopback HTTP server on 127.0.0.1:9500 (GET /inspect/health|tree|design-system) serving the semantics tree + design-token catalog to the cmp-inspector MCP via `adb forward tcp:9500 tcp:9500`. The androidRelease dir holds only the no-op startInspector() twin — release builds contain no inspector code structurally. When off: delete both inspector dirs AND strip the `inspector` marker blocks in AppApplication.kt (import + startInspector() call) and composeApp/src/androidDebug/AndroidManifest.xml (INTERNET permission). Zero dependencies (java.net.ServerSocket + kotlinx-serialization from commonMain); no build-file markers needed."
+    },
+    "dev-client": {
+      "enabledByDefault": true,
+      "paths": [
+        "composeApp/src/desktopMain",
+        "docs/dev-client.md"
+      ],
+      "notes": "Desktop dev-client: a jvm(\"desktop\") target inside composeApp running the shared commonMain UI in a phone-sized JVM window (main.kt: __APP_NAME__ dev-client, 411x891dp), with Compose Hot Reload 1.1.1 attached (task hotRunDesktop; plain run task needs no JBR). GitLive Firebase 2.1.0 publishes JVM artifacts so commonMain deps resolve for the desktop target, but the dev-client NEVER initializes/contacts Firebase — desktopMain DI (DesktopModule.kt) binds only NetworkMonitor (always-online) + Room (BundledSQLiteDriver into the OS temp dir); the example ItemRepositoryImpl is in-memory on every platform. When off: delete the desktopMain dir + docs/dev-client.md AND strip the `dev-client` marker blocks in build.gradle.kts (hot-reload plugin apply false), settings.gradle.kts (foojay-resolver-convention for JBR auto-provisioning), composeApp/build.gradle.kts (hot-reload plugin, jvm(\"desktop\") target, desktopMain deps, kspDesktop room.compiler row — nested inside the room block, compose.desktop application block). The catalog keeps the declared coordinates by design (declared-but-unused)."
+    }
+  },
+  "verify": {
+    "android": "./gradlew :composeApp:assembleDebug",
+    "androidSmoke": "./gradlew :composeApp:installDebug && node qa/appium/run-android-smoke.mjs",
+    "iosLink": "./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64",
+    "ios": "cd iosApp && export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 && xcodegen generate && pod install && SIM_UDID=$(xcrun simctl list devices available | grep -Eo '[0-9A-F-]{36}' | head -1) && xcodebuild -workspace iosApp.xcworkspace -scheme iosApp -sdk iphonesimulator -configuration Debug ARCHS=arm64 ONLY_ACTIVE_ARCH=YES EXCLUDED_ARCHS=x86_64 -destination \"id=$SIM_UDID\" build",
+    "iosNote": "On Apple Silicon, the KMP embedAndSignAppleFrameworkForXcode prebuild phase produces ONLY the active-arch (arm64) slice of ComposeApp.framework. A `-destination generic/platform=iOS Simulator` build demands a universal arm64+x86_64 binary and FAILS at CreateUniversalBinary. Constrain to arm64 (ARCHS=arm64 EXCLUDED_ARCHS=x86_64) and target a concrete arm64 simulator UDID — matching the linkDebugFrameworkIosSimulatorArm64 gate."
+  },
+  "stampPipeline": [
+    "1. Copy template/ -> targetDir (preserve binary files).",
+    "2. Delete disabled-feature paths. MUST happen BEFORE the package-dir rename: feature paths are declared with the literal com/example/app segment, so deleting after the rename silently misses package-rooted paths (the --no-room stale-sources bug).",
+    "3. Strip/keep feature-marker blocks per the enabled feature set (stack-based; handle ! negation).",
+    "4. Replace placeholder tokens in all text-file CONTENTS.",
+    "5. Rename package source dirs com/example/app -> __PACKAGE_PATH__ under each packageSourceRoots entry.",
+    "6. Slugify __APP_NAME__ for settings.gradle.kts rootProject.name (no spaces).",
+    "7. Write local.properties (sdk.dir) and run verify.android (+ verify.ios on macOS when ios enabled)."
+  ]
+}

package/template/qa/appium/README.md

@@ -0,0 +1,23 @@
+# Appium harness — __APP_NAME__
+
+On-device UI testing for the Android app via Appium 3.x + UiAutomator2.
+
+## Prerequisites
+- Appium 3.x server + the `uiautomator2` driver (`appium driver install uiautomator2`).
+- A running Android emulator named `emulator-5554`.
+- The debug build installed: `./gradlew :composeApp:installDebug`.
+
+## Run the smoke (JS)
+```bash
+appium &                       # start the server on :4723
+npm --prefix qa/appium run smoke
+```
+
+## Run the BDD suite (Python)
+```bash
+pip install pytest requests
+pytest tests/appium/cmp -v
+```
+
+Both assert the generic bottom-nav shell renders (Home + Profile tabs) — the `--verify`
+gate the scaffolder runs to prove the stamped app is alive.

package/template/qa/appium/lib/appium-client.mjs

@@ -0,0 +1,225 @@
+import fs from 'node:fs/promises';
+
+export class AppiumClient {
+  constructor({ serverUrl, capabilities }) {
+    this.serverUrl = serverUrl.replace(/\/$/, '');
+    this.capabilities = capabilities;
+    this.sessionId = null;
+  }
+
+  async start() {
+    const result = await this.#request('/session', {
+      method: 'POST',
+      body: {
+        capabilities: {
+          alwaysMatch: this.capabilities,
+          firstMatch: [{}],
+        },
+      },
+    });
+    this.sessionId = result.sessionId ?? result.value?.sessionId;
+    return this.sessionId;
+  }
+
+  async stop() {
+    if (!this.sessionId) {
+      return;
+    }
+    await this.#request(`/session/${this.sessionId}`, { method: 'DELETE' });
+    this.sessionId = null;
+  }
+
+  async pause(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async back() {
+    await this.#sessionRequest('/back', { method: 'POST', body: {} });
+  }
+
+  async screenshot(filePath) {
+    const result = await this.#sessionRequest('/screenshot', { method: 'GET' });
+    await fs.mkdir(new URL('.', `file://${filePath}`).pathname, { recursive: true }).catch(() => {});
+    await fs.writeFile(filePath, Buffer.from(result.value, 'base64'));
+  }
+
+  async pageSource() {
+    const result = await this.#sessionRequest('/source', { method: 'GET' });
+    return result.value;
+  }
+
+  async clickByText(text, timeoutMs = 10000) {
+    await this.clickByXPath(`//*[@text=${escapeXPathText(text)}]`, timeoutMs);
+  }
+
+  async clickByTextContaining(text, timeoutMs = 10000) {
+    await this.clickByXPath(`//*[contains(@text,${escapeXPathText(text)})]`, timeoutMs);
+  }
+
+  async waitForTextContaining(text, timeoutMs = 10000) {
+    const safeText = escapeXPathText(text);
+    return this.waitForElement('xpath', `//*[contains(@text,${safeText})]`, timeoutMs);
+  }
+
+  async clickByAccessibilityId(label, timeoutMs = 10000) {
+    const elementId = await this.waitForElement('accessibility id', label, timeoutMs);
+    await this.clickElement(elementId);
+  }
+
+  async clickByXPath(xpath, timeoutMs = 10000) {
+    const elementId = await this.waitForElement('xpath', xpath, timeoutMs);
+    await this.clickElement(elementId);
+  }
+
+  async clickElement(elementId) {
+    await this.#sessionRequest(`/element/${elementId}/click`, { method: 'POST', body: {} });
+  }
+
+  async waitForText(text, timeoutMs = 10000) {
+    const safeText = escapeXPathText(text);
+    return this.waitForElement('xpath', `//*[@text=${safeText}]`, timeoutMs);
+  }
+
+  async elementExists(using, value) {
+    try {
+      await this.#sessionRequest('/element', {
+        method: 'POST',
+        body: { using, value },
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async typeByXPath(xpath, text, timeoutMs = 10000) {
+    const elementId = await this.waitForElement('xpath', xpath, timeoutMs);
+    await this.clickElement(elementId);
+    await this.clearElement(elementId);
+    await this.typeElement(elementId, text);
+    return elementId;
+  }
+
+  async typeIntoLabeledField(label, text, timeoutMs = 10000) {
+    const safeLabel = escapeXPathText(label);
+    return this.typeByXPath(`//android.widget.EditText[.//android.widget.TextView[@text=${safeLabel}]]`, text, timeoutMs);
+  }
+
+  async clearElement(elementId) {
+    await this.#sessionRequest(`/element/${elementId}/clear`, { method: 'POST', body: {} });
+  }
+
+  async typeElement(elementId, text) {
+    await this.#sessionRequest(`/element/${elementId}/value`, {
+      method: 'POST',
+      body: {
+        text,
+        value: Array.from(text),
+      },
+    });
+  }
+
+  async waitForTextGone(text, timeoutMs = 10000) {
+    const safeText = escapeXPathText(text);
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+      const exists = await this.elementExists('xpath', `//*[@text=${safeText}]`);
+      if (!exists) {
+        return;
+      }
+      await this.pause(300);
+    }
+    throw new Error(`Timed out waiting for text to disappear: ${text}`);
+  }
+
+  async getWindowRect() {
+    const result = await this.#sessionRequest('/window/rect', { method: 'GET' });
+    return result.value;
+  }
+
+  async swipe(startX, startY, endX, endY, durationMs = 350) {
+    await this.#sessionRequest('/actions', {
+      method: 'POST',
+      body: {
+        actions: [
+          {
+            type: 'pointer',
+            id: 'finger1',
+            parameters: { pointerType: 'touch' },
+            actions: [
+              { type: 'pointerMove', duration: 0, x: startX, y: startY },
+              { type: 'pointerDown', button: 0 },
+              { type: 'pause', duration: 100 },
+              { type: 'pointerMove', duration: durationMs, x: endX, y: endY },
+              { type: 'pointerUp', button: 0 },
+            ],
+          },
+        ],
+      },
+    });
+    await this.#sessionRequest('/actions', { method: 'DELETE', body: {} });
+  }
+
+  async swipeUp() {
+    const rect = await this.getWindowRect();
+    const midX = Math.round(rect.width / 2);
+    await this.swipe(midX, Math.round(rect.height * 0.8), midX, Math.round(rect.height * 0.35));
+  }
+
+  async waitForElement(using, value, timeoutMs = 10000) {
+    const startedAt = Date.now();
+    let lastError = null;
+    while (Date.now() - startedAt < timeoutMs) {
+      try {
+        const result = await this.#sessionRequest('/element', {
+          method: 'POST',
+          body: { using, value },
+        });
+        const element = result.value;
+        const elementId = element?.['element-6066-11e4-a52e-4f735466cecf'] ?? element?.ELEMENT;
+        if (elementId) {
+          return elementId;
+        }
+      } catch (error) {
+        lastError = error;
+      }
+      await this.pause(350);
+    }
+    throw new Error(`Timed out waiting for element ${using}=${value}: ${lastError?.message ?? 'not found'}`);
+  }
+
+  async #sessionRequest(path, options) {
+    if (!this.sessionId) {
+      throw new Error('Appium session has not been started');
+    }
+    return this.#request(`/session/${this.sessionId}${path}`, options);
+  }
+
+  async #request(path, { method, body } = {}) {
+    const response = await fetch(`${this.serverUrl}${path}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    const json = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      const message = json.value?.message ?? json.error ?? text;
+      throw new Error(message);
+    }
+    return json;
+  }
+}
+
+export function escapeXPathText(text) {
+  if (!text.includes("'")) {
+    return `'${text}'`;
+  }
+  if (!text.includes('"')) {
+    return `"${text}"`;
+  }
+  const parts = text.split("'").map((part) => `'${part}'`);
+  return `concat(${parts.join(', "\'", ')})`;
+}

package/template/qa/appium/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "__APP_NAME__-appium",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "smoke": "node run-android-smoke.mjs"
+  }
+}

package/template/qa/appium/run-android-smoke.mjs

@@ -0,0 +1,39 @@
+// Android smoke runner — asserts the app launches and the bottom-nav shell renders.
+// Prereqs: an Appium 3.x server on http://127.0.0.1:4723 and a running emulator-5554
+// with the debug APK installed (./gradlew :composeApp:installDebug).
+import { AppiumClient } from './lib/appium-client.mjs';
+
+const APP_PACKAGE = '__PACKAGE__';
+const APP_ACTIVITY = '__PACKAGE__.MainActivity';
+
+const client = new AppiumClient({
+  serverUrl: 'http://127.0.0.1:4723',
+  capabilities: {
+    platformName: 'Android',
+    'appium:automationName': 'UiAutomator2',
+    'appium:deviceName': 'emulator-5554',
+    'appium:udid': 'emulator-5554',
+    'appium:appPackage': APP_PACKAGE,
+    'appium:appActivity': APP_ACTIVITY,
+    'appium:forceAppLaunch': true,
+    'appium:newCommandTimeout': 120,
+  },
+});
+
+async function main() {
+  await client.start();
+  try {
+    await client.waitForText('Home', 20000);
+    await client.waitForText('Profile', 10000);
+    await client.clickByText('Profile', 10000);
+    await client.waitForTextContaining('stub screen', 10000);
+    console.log('SMOKE PASS: bottom-nav shell rendered and tab switch works.');
+  } finally {
+    await client.stop();
+  }
+}
+
+main().catch((err) => {
+  console.error('SMOKE FAIL:', err.message);
+  process.exit(1);
+});

package/template/settings.gradle.kts

@@ -0,0 +1,34 @@
+rootProject.name = "__APP_NAME__"
+enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
+
+pluginManagement {
+    repositories {
+        google {
+            mavenContent {
+                includeGroupByRegex(".*google.*")
+                includeGroupByRegex(".*android.*")
+            }
+        }
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+// >>> cmp:feature dev-client
+plugins {
+    // Compose Hot Reload runs the desktop dev-client on the JetBrains Runtime; this resolver
+    // lets Gradle auto-provision it (one-time download) when no local JBR is found.
+    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
+}
+// <<< cmp:feature dev-client
+
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        // GitLive Firebase KMP
+        maven("https://jitpack.io")
+    }
+}
+
+include(":composeApp")

package/template/tests/appium/cmp/conftest.py

@@ -0,0 +1,96 @@
+"""
+Shared Appium session configuration for the __APP_NAME__ Android app.
+Appium 3.x + UiAutomator2. Start an Appium server on 127.0.0.1:4723 and a running
+emulator-5554 before invoking pytest.
+"""
+import base64
+import os
+import re
+import time
+
+import pytest
+import requests
+
+APPIUM_URL = "http://127.0.0.1:4723"
+CAPABILITIES = {
+    "platformName": "Android",
+    "appium:automationName": "UiAutomator2",
+    "appium:deviceName": "emulator-5554",
+    "appium:udid": "emulator-5554",
+    "appium:appPackage": "__PACKAGE__",
+    "appium:appActivity": "__PACKAGE__.MainActivity",
+    "appium:noReset": False,
+    "appium:forceAppLaunch": True,
+    "appium:newCommandTimeout": 120,
+}
+SCREENSHOTS_DIR = "qa-artifacts/appium-cmp"
+
+
+def escape_xpath(text: str) -> str:
+    if "'" not in text:
+        return f"'{text}'"
+    if '"' not in text:
+        return f'"{text}"'
+    parts = text.split("'")
+    return "concat('" + "', \"'\", '".join(parts) + "')"
+
+
+class AppiumDriver:
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        self.base = f"{APPIUM_URL}/session/{session_id}"
+
+    def _req(self, method: str, path: str, body=None, timeout: int = 30) -> dict:
+        resp = requests.request(method, self.base + path, json=body, timeout=timeout)
+        return resp.json() if resp.content else {}
+
+    def source(self) -> str:
+        return self._req("GET", "/source").get("value", "")
+
+    def _find_xpath(self, xpath: str, timeout: int = 10) -> str:
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            r = requests.post(self.base + "/element",
+                              json={"using": "xpath", "value": xpath}, timeout=10)
+            if r.status_code == 200:
+                val = r.json().get("value", {})
+                if isinstance(val, dict) and val:
+                    return next(iter(val.values()))
+            time.sleep(0.5)
+        raise TimeoutError(f"Element not found: {xpath}")
+
+    def find_by_text(self, text: str, timeout: int = 10) -> str:
+        return self._find_xpath(f"//*[@text={escape_xpath(text)}]", timeout)
+
+    def text_exists(self, text: str, timeout: int = 5) -> bool:
+        try:
+            self.find_by_text(text, timeout)
+            return True
+        except TimeoutError:
+            return False
+
+    def click_text(self, text: str, timeout: int = 10):
+        self._req("POST", f"/element/{self.find_by_text(text, timeout)}/click")
+
+    def screenshot(self, name: str = "screenshot") -> str:
+        os.makedirs(SCREENSHOTS_DIR, exist_ok=True)
+        r = self._req("GET", "/screenshot", timeout=15)
+        if r.get("value"):
+            path = f"{SCREENSHOTS_DIR}/{name}_{int(time.time())}.png"
+            with open(path, "wb") as f:
+                f.write(base64.b64decode(r["value"]))
+            return path
+        return ""
+
+
+@pytest.fixture(scope="module")
+def driver():
+    resp = requests.post(f"{APPIUM_URL}/session",
+                         json={"capabilities": {"alwaysMatch": CAPABILITIES}}, timeout=60)
+    resp.raise_for_status()
+    data = resp.json()
+    session_id = data.get("sessionId") or data.get("value", {}).get("sessionId")
+    time.sleep(5)
+    drv = AppiumDriver(session_id)
+    yield drv
+    requests.delete(f"{APPIUM_URL}/session/{session_id}", timeout=15)

package/template/tests/appium/cmp/test_smoke.py

@@ -0,0 +1,17 @@
+"""
+Smoke test: the app launches and the generic bottom-nav shell renders.
+This is the `--verify` Appium gate the scaffolder runs to prove the stamped app is alive.
+"""
+
+
+def test_bottom_nav_renders(driver):
+    # Home tab title is present on first launch.
+    assert driver.text_exists("Home", timeout=20), "Home screen did not render"
+    # Both default tabs are present in the bottom nav.
+    assert driver.text_exists("Profile", timeout=10), "Profile tab not found in bottom nav"
+
+
+def test_can_switch_to_profile_tab(driver):
+    driver.click_text("Profile", timeout=10)
+    assert driver.text_exists("This is a stub screen.", timeout=10), \
+        "Profile tab content did not render after tapping the tab"