@radhya/mach 2.0.34 → 2.0.36

package/README.md

@@ -148,6 +148,8 @@ For Expo apps, `mach ota setup` writes `ota` config and wires `@radhya/mach/expo
 
 Command flags always win over config values. For example, `mach ota publish --channel staging --runtime-version 1.2.0` overrides `ota.channel` and `ota.runtimeVersion`.
 
+Runtime version is the OTA compatibility boundary. Mach resolves Expo-style `appVersion`, `sdkVersion`, and `nativeVersion` policies, stores the resolved runtime on each build, and serves OTA updates only to matching platform/channel/runtime combinations.
+
 Vanilla React Native uses the same command surface. The native OTA client and automatic native patching are intentionally guarded until the Mach RN client package is ready.
 
 ## Deep Links
@@ -217,7 +219,7 @@ mach agent uninstall
 | `--local`        | Run build on local machine                                                       |
 | `--dry-run`      | Generate build script without running it                                         |
 | `--simulator`    | iOS Simulator build (no signing needed)                                          |
-| `--auto-version` | Force Android versionCode or iOS buildNumber lookup from the store               |
+| `--auto-version` | Force Mach-managed Android versionCode or iOS buildNumber assignment             |
 | `--auto-submit`  | Submit the successful build to App Store Connect or Google Play                  |
 | `--verbose`      | Enable detailed build logging                                                    |
 | `--json-output`  | Write build metadata (`buildId`, Dashboard URL, status) to a JSON file for CI/CD |
@@ -339,9 +341,9 @@ mach credentials:service --platform ios
 
 The Dashboard also supports this under **Credentials → Android → package id → Service credentials**. Uploading a Google Play service key under `*` is legacy behavior; store submission now expects the service credential to match the Android package being submitted.
 
-App Store Connect keys are used for iOS TestFlight submission and iOS buildNumber auto-increment. Mach stores the key id, issuer id, Apple Developer Team ID, and App Store Connect provider/team metadata so build and submit commands can run without Apple ID prompts.
+App Store Connect keys are used for iOS TestFlight submission. Mach stores the key id, issuer id, Apple Developer Team ID, and App Store Connect provider/team metadata so submit commands can run without Apple ID prompts.
 
-Google Play service keys are only needed for store automation: Android submission and Play-backed versionCode resolution. They are not signing credentials. A dev package such as `com.example.app.dev` needs its own Google Play service key only if that exact package exists in Google Play and you explicitly ask Mach to query Play for it.
+Google Play service keys are only needed for Android store submission. They are not signing credentials. A dev package such as `com.example.app.dev` needs its own Google Play service key only if that exact package exists in Google Play and you submit that package.
 
 ## Configuration
 
@@ -402,12 +404,12 @@ Create a `mach.config.json` in your project root:
 
 | Property               | Description                                                                                                                    |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `ios.bundleIdentifier` | iOS bundle ID used for signing, App Store Connect lookup, and submit                                                           |
+| `ios.bundleIdentifier` | iOS bundle ID used for signing, version counter scoping, and submit                                                            |
 | `ios.appleTeamId`      | Optional global Apple Developer Team ID used for iOS signing. Profile-specific `submit.<profile>.ios.appleTeamId` overrides it |
-| `ios.ascAppId`         | App Store Connect app id. Optional when Mach can find the app by bundle ID; recommended for reliable iOS buildNumber lookup    |
-| `ios.buildNumber`      | Set to `"auto"` to let Mach resolve the next iOS CFBundleVersion from App Store Connect and seed the server-side build counter |
-| `android.package`      | Android package name used for signing, Google Play lookup, and submit                                                          |
-| `android.versionCode`  | Set to `"auto"` to let store builds resolve the next versionCode via Google Play                                               |
+| `ios.ascAppId`         | App Store Connect app id used for iOS submission                                                                                |
+| `ios.buildNumber`      | Set to `"auto"` to let Mach assign the next iOS CFBundleVersion from its Dashboard counter                                     |
+| `android.package`      | Android package name used for signing, version counter scoping, and submit                                                     |
+| `android.versionCode`  | Set to `"auto"` to let Mach assign the next Android versionCode from its Dashboard counter                                     |
 
 ### Profile Properties
 
@@ -473,11 +475,11 @@ The keystore file and its passwords are stored encrypted in the Dashboard when m
 
 ## Automated Versioning
 
-Mach can automatically determine the next Android `versionCode` and iOS `buildNumber` from the store, then increment safely to prevent duplicate upload rejections.
+Mach can automatically assign the next Android `versionCode` and iOS `buildNumber` from Dashboard counters, then increment atomically so concurrent builds do not receive the same native version.
 
-**Android setup:** Upload a Google Service Account JSON via `mach credentials` → Service Credentials for the exact Android package being queried.
+Counters are scoped by Android package name or iOS bundle identifier, so development, staging, and production apps can advance independently.
 
-**iOS setup:** Upload or create an App Store Connect API key with `mach credentials:service --platform ios`. Set `ios.ascAppId` in `mach.config.json` when possible so Mach can query the exact App Store Connect app.
+For existing apps already uploaded to App Store Connect or Google Play, seed the selected Dashboard environment once with the latest uploaded value (`BUILD_NUMBER` for iOS or `ANDROID_VERSION_CODE` for Android). Mach will assign the next value and continue from its own counter after that.
 
 **Usage:**
 
@@ -493,9 +495,9 @@ Or in config:
 "ios": { "buildNumber": "auto" }
 ```
 
-When `android.versionCode` is set to `"auto"`, Mach performs the Google Play lookup automatically for Android `store` builds. For `internal` builds, Mach skips the Play lookup by default so development packages do not need Google Play service keys. Pass `--auto-version` on an internal build only when that package is registered in Google Play and should be queried.
+When `android.versionCode` is set to `"auto"`, Mach assigns an Android versionCode automatically for store builds. For internal builds, pass `--auto-version` when you also want Mach to assign a versionCode.
 
-When `ios.buildNumber` is set to `"auto"`, Mach queries App Store Connect for the latest uploaded build number and seeds Mach's server-side counter from that value. If App Store Connect has build `81` and Mach's internal counter is still `1`, the next iOS build becomes at least `82`. Concurrent builds are still safe because the Dashboard API increments the counter atomically.
+When `ios.buildNumber` is set to `"auto"`, Mach assigns the next iOS CFBundleVersion from the scoped Dashboard counter. Concurrent builds are safe because the Dashboard API increments the counter atomically.
 
 This only changes iOS `CFBundleVersion` / build number. It does not bump the public App Store version (`CFBundleShortVersionString`, usually `expo.version` in `app.json`). After a version like `1.17.0` is approved/released, Apple closes that train for new uploads; bump the app version, for example to `1.17.1`, rebuild, then submit.