@radhya/mach 2.0.41 → 2.0.43

package/docs/ota.md

@@ -0,0 +1,71 @@
+# Mach OTA Updates
+
+Mach OTA publishes JavaScript bundles and assets through Mach API and Mach-managed object storage. It does not publish releases to EAS Update, and mobile apps never receive storage credentials.
+
+## Supported apps
+
+Mach currently uses the open-source `expo-updates` runtime for both supported React Native workflows:
+
+| `framework` | Native workflow | OTA setup |
+| --- | --- | --- |
+| `expo` | Expo prebuild/CNG | Installs `expo-updates` and applies `@radhya/mach/expo-plugin` during prebuild. |
+| `react-native` | Committed `ios/` and `android/` projects | Installs Expo Modules when needed, installs `expo-updates`, and synchronizes its native configuration without running prebuild. |
+
+`mach-react-native` is reserved for a future Mach-owned client and is not a supported engine yet.
+
+## Initial setup
+
+Run setup from the project root:
+
+```bash
+mach ota setup
+mach ota verify
+```
+
+Setup reads project ID, framework, channel, runtime policy, and existing URL from `mach.config.json`. Command flags have higher precedence. It also refreshes an older project-local `@radhya/mach` package so Expo prebuild uses a plugin compatible with the running CLI. Interactive setup asks before installing dependencies; use `mach --yes ota setup` in automation. Use `--skip-install` only when dependencies are managed separately.
+
+For a bare React Native project, setup may make these intentional changes:
+
+- Install and configure the `expo` package and Expo Modules autolinking.
+- Install the React Native-version-compatible `expo-updates` package.
+- Add `@radhya/mach/expo-plugin` to Expo app config.
+- Synchronize the Mach URL, channel request header, and resolved runtime into Android native resources and `Expo.plist`.
+
+Expo's official `install-expo-modules` and `expo-updates configuration:syncnative` commands perform version-sensitive native changes. Mach does not maintain a separate set of native text patches.
+
+After setup, review the project diff and make one new native build:
+
+```bash
+mach build --platform ios --profile production
+mach build --platform android --profile production
+```
+
+Only binaries built after setup can receive Mach OTA updates.
+
+## Publish
+
+```bash
+mach ota publish --channel production --platform all --message "Fix checkout screen"
+```
+
+Mach exports through Expo CLI for both Expo and bare React Native, uploads the protocol manifest and assets, and activates the release for the matching project, channel, platform, and runtime version.
+
+The default `ON_LOAD` behavior downloads a compatible release on one cold launch and runs it on the next cold launch. The dashboard records unique downloaded, applied, and failed installations from Expo Updates request headers.
+
+## Runtime compatibility
+
+The native binary and OTA manifest must contain the same runtime version. Mach injects the resolved runtime into Expo config during builds and publishes, and synchronizes it into committed bare native projects before a Mach build. Runtime precedence is command `--runtime-version`, `ota.runtimeVersion`, `ota.runtimeVersionPolicy`, Expo config, then package version fallback. When Mach has a policy, old hardcoded Expo runtime values do not override it.
+
+`mach ota verify`, `mach ota publish`, and OTA-enabled Expo builds validate the final resolved Expo URL, channel, and runtime. They stop with a repair instruction if the project-local plugin would embed different values.
+
+The default `appVersion` policy uses the app/package version as the compatibility boundary. Use an explicit `ota.runtimeVersion` or `--runtime-version` only when deliberately managing compatibility yourself.
+
+## Operations
+
+```bash
+mach ota list
+mach ota rollback --update-id <updateId>
+mach ota promote --update-id <updateId>
+```
+
+Rollback disables the selected active release so compatible clients receive the previous active release on their next checks. Promotion changes the active channel without rebuilding assets.

package/expo-plugin/index.js

@@ -90,15 +90,16 @@ const resolveOta = config => {
   const ota = machConfig.ota || machConfig.update || {}
   if (ota.enabled === false) return { enabled: false }
   const projectId = nonEmpty(machConfig.projectId)
-  const engine = nonEmpty(ota.engine) || (machConfig.framework === 'expo' ? 'expo-updates' : undefined)
+  const engine = nonEmpty(ota.engine) || 'expo-updates'
   const url = first(
+    process.env.MACH_OTA_URL,
     ota.url,
     ota.deploymentUrl,
     projectId && engine !== 'mach-react-native' ? `https://mach-api.securejs.in/api/ota/expo/${projectId}` : undefined
   )
-  const runtimeVersion = nonEmpty(ota.runtimeVersion)
+  const runtimeVersion = first(process.env.MACH_OTA_RUNTIME_VERSION, ota.runtimeVersion)
   const runtimeVersionPolicy = nonEmpty(ota.runtimeVersionPolicy) || 'appVersion'
-  const channel = nonEmpty(ota.channel) || 'production'
+  const channel = first(process.env.MACH_OTA_CHANNEL, ota.channel) || 'production'
   return { ...ota, enabled: Boolean(url), projectId, engine, url, runtimeVersion, runtimeVersionPolicy, channel }
 }
 
@@ -122,7 +123,7 @@ module.exports = function withMachDeepLinks(config) {
     }
     if (ota.runtimeVersion) {
       config.runtimeVersion = ota.runtimeVersion
-    } else if (!config.runtimeVersion && ota.runtimeVersionPolicy) {
+    } else if (ota.runtimeVersionPolicy) {
       config.runtimeVersion = { policy: ota.runtimeVersionPolicy }
     }
     config.extra.mach = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radhya/mach",
-  "version": "2.0.41",
+  "version": "2.0.43",
   "description": "Mach CLI: Cloud Build Orchestrator for React Native & Expo",
   "main": "dist/index.js",
   "type": "module",
@@ -11,10 +11,12 @@
     "dist/",
     "expo-plugin/",
     "docs/frameworks/",
-    "docs/deep-links.md"
+    "docs/deep-links.md",
+    "docs/ota.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/commands/isolated-upload.ts --format esm --clean --minify --dts",
+    "test": "tsx --test src/**/*.test.ts && node --test tests/*.test.cjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "release": "semantic-release"