@radhya/mach 2.0.9 → 2.0.11

package/docs/frameworks/README.md

@@ -0,0 +1,72 @@
+# Framework Guides
+
+Mach uses `mach.config.json` as the source of truth for framework behavior. Builds do not infer framework from `package.json`, because package scanning is fragile in real projects and can make Expo, bare React Native, and future Flutter support affect each other accidentally.
+
+## Choose Your Framework
+
+| If your project is... | Set `framework` to | Use this guide |
+| --- | --- | --- |
+| A vanilla React Native app with committed `ios/` and `android/` folders | `"react-native"` | [Bare React Native](react-native.md) |
+| An Expo app that should run `expo prebuild` during cloud builds | `"expo"` | [Expo](expo.md) |
+| A Flutter app | `"flutter"` | [Flutter](flutter.md) |
+
+`mach init` and `mach link` create:
+
+```json
+{
+  "framework": "react-native"
+}
+```
+
+Change this to `"expo"` before building an Expo project. Flutter is accepted in config for forward compatibility, but Flutter builds intentionally fail until the Flutter builder is implemented.
+
+## Why This Is Explicit
+
+The same repository can contain Expo packages, React Native native folders, custom build scripts, or migration leftovers. Automatic framework detection can pick the wrong pipeline and break a live build. Explicit config gives each project a stable contract:
+
+- React Native builds never run Expo prebuild.
+- Expo builds keep the existing Expo prebuild and dev-client behavior.
+- Flutter can be added later without changing `mach build` commands.
+- Documentation, CI, and support conversations can point to one clear setting.
+
+## Required Config
+
+Every buildable project should have this root field:
+
+```json
+{
+  "projectId": "your-mach-project-id",
+  "framework": "react-native",
+  "name": "MyApp",
+  "slug": "my-app"
+}
+```
+
+Allowed values:
+
+- `react-native`
+- `expo`
+- `flutter`
+
+Aliases such as `reactnative` and `react_native` are normalized to `react-native`, but new projects should use the canonical `react-native` value.
+
+## Common Commands
+
+The commands do not change between frameworks:
+
+```bash
+mach build --platform ios --profile staging
+mach build --platform android --profile staging
+mach build --platform ios --profile production --auto-submit
+mach build --platform android --profile production --auto-submit
+mach submit --latest --platform ios --profile production
+mach submit --latest --platform android --profile production
+```
+
+Framework selection only changes what happens inside the build runner.
+
+## Failure Messages
+
+If `framework` is missing, Mach stops before queuing the build and asks you to add one of the allowed values. If `framework` is invalid, Mach stops before upload and prints the accepted values. If `framework` is `flutter`, Mach currently stops with a clear "Flutter builds are not implemented yet" message.
+
+This is intentional. A build should fail early and clearly instead of silently running the wrong native pipeline.

package/docs/frameworks/expo.md

@@ -0,0 +1,148 @@
+# Expo Builds
+
+Use this guide when your app is an Expo project and Mach should run Expo prebuild before native compilation.
+
+## Required Config
+
+`mach.config.json` must declare Expo explicitly:
+
+```json
+{
+  "framework": "expo",
+  "ios": {
+    "bundleIdentifier": "com.example.app",
+    "buildNumber": "auto"
+  },
+  "android": {
+    "package": "com.example.app",
+    "versionCode": "auto"
+  }
+}
+```
+
+Mach does not infer Expo from `package.json`. This avoids accidental behavior changes when dependencies move or when a project contains Expo packages for a non-Expo reason.
+
+## When To Use This
+
+Use `framework: "expo"` when:
+
+- The app is configured through `app.json`, `app.config.js`, or `app.config.ts`.
+- Native folders may be generated or refreshed by Expo prebuild.
+- You use Expo config plugins.
+- You use Expo development client builds.
+- You expect Expo-managed Android/iOS native config to be applied before native compilation.
+
+Do not use this value for a bare React Native project whose `ios/` and `android/` folders are manually maintained and should not be regenerated.
+
+## Pipeline Behavior
+
+For Expo, Mach:
+
+- Installs JavaScript dependencies.
+- Runs `expo prebuild --platform ios --no-install` for iOS builds.
+- Runs `expo prebuild --platform android --no-install` for Android builds.
+- Sets Expo dotenv protection for builds.
+- Applies Expo dev-client exclusion for non-development builds.
+- Applies Expo-specific Android Gradle properties only for Expo builds.
+- Applies Mach signing, versioning, artifact upload, and optional store submission after prebuild.
+
+Mach does not:
+
+- Auto-enable Expo just because `expo` exists in `package.json`.
+- Run Expo prebuild for projects configured as `react-native`.
+- Treat Flutter projects as Expo projects.
+
+## Development Client
+
+For Expo development client builds:
+
+```json
+{
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "development",
+      "environment": "development"
+    }
+  }
+}
+```
+
+Then run:
+
+```bash
+mach build --platform ios --profile development
+mach build --platform android --profile development
+```
+
+For staging or production, leave `developmentClient` off unless you intentionally want a dev client artifact.
+
+## Project Layout
+
+Typical layout:
+
+```text
+my-app/
+  mach.config.json
+  package.json
+  app.json or app.config.*
+  ios/        optional before build
+  android/    optional before build
+```
+
+Mach can run Expo prebuild when native folders are absent or need to be regenerated. If you commit native folders and do not want them regenerated, use `framework: "react-native"` instead.
+
+## App Versioning
+
+For Android store builds, set:
+
+```json
+{
+  "android": {
+    "versionCode": "auto"
+  }
+}
+```
+
+For iOS store builds, set:
+
+```json
+{
+  "ios": {
+    "buildNumber": "auto"
+  }
+}
+```
+
+This updates native build numbers only. Apple also requires the marketing version to increase when a released version train is closed. In Expo projects, that is usually `expo.version` in `app.json` or `app.config.*`.
+
+## Common Commands
+
+```bash
+mach build --platform ios --profile staging
+mach build --platform android --profile staging
+mach build --platform ios --profile production --auto-version --auto-submit
+mach build --platform android --profile production --auto-version --auto-submit
+```
+
+## When Not To Use Expo Framework
+
+Do not set `framework: "expo"` if the native `ios/` and `android/` projects are maintained manually and should not be regenerated. Use `framework: "react-native"` instead.
+
+## Migration To Bare React Native
+
+If an Expo project has been fully ejected or moved to manually maintained native projects:
+
+1. Commit `ios/` and `android/`.
+2. Change `framework` from `"expo"` to `"react-native"`.
+3. Remove Expo prebuild assumptions from Mach prebuild hooks.
+4. Run a staging build for iOS and Android before production.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Mach says `framework` is missing | Add `"framework": "expo"` at the root of `mach.config.json`. |
+| Native folders are being regenerated unexpectedly | You are using the Expo pipeline. Switch to `react-native` only if the native folders are now manually owned. |
+| Expo dev-client is included in production | Ensure `developmentClient` is not enabled in the production profile. |
+| App Store submission fails because the version train is closed | Increase the marketing version (`expo.version` or equivalent config), rebuild, then submit again. |

package/docs/frameworks/flutter.md

@@ -0,0 +1,67 @@
+# Flutter Builds
+
+Flutter is reserved in Mach configuration so the CLI can support it without changing user-facing commands later.
+
+## Current Status
+
+`framework: "flutter"` is recognized as a valid config value, but Flutter cloud builders are not implemented yet. If you run a build with Flutter selected, Mach fails with a clear message instead of trying to run the React Native or Expo pipeline.
+
+## Planned Config Shape
+
+```json
+{
+  "framework": "flutter",
+  "ios": {
+    "bundleIdentifier": "com.example.app",
+    "buildNumber": "auto"
+  },
+  "android": {
+    "package": "com.example.app",
+    "versionCode": "auto"
+  }
+}
+```
+
+## Planned Behavior
+
+The Flutter builder should be separate from the React Native and Expo builders:
+
+- Android should run Flutter/Gradle commands from the Flutter project.
+- iOS should run Flutter build/archive commands and then the same managed signing/upload flow.
+- Expo prebuild and React Native Metro cache handling should not run for Flutter.
+- Store submission should keep using the same `mach submit` command surface.
+
+Until that builder exists, use `react-native` or `expo`.
+
+## Why It Is Already In Config
+
+Mach accepts `flutter` now so projects, Dashboard records, and docs can move toward a framework-neutral model before Flutter execution is enabled. This avoids another command change later. The command remains:
+
+```bash
+mach build --platform ios --profile production
+mach build --platform android --profile production
+```
+
+Only the internal build runner changes once Flutter is implemented.
+
+## Current Failure Mode
+
+If you run a build today with:
+
+```json
+{
+  "framework": "flutter"
+}
+```
+
+Mach stops before starting the React Native or Expo build pipeline and prints that Flutter builds are not implemented yet. This is safer than trying to run Gradle or Xcode with React Native assumptions.
+
+## Implementation Checklist
+
+When Flutter support is added, keep it isolated:
+
+- Add Flutter-specific Android and iOS build runners.
+- Keep Expo prebuild logic out of Flutter.
+- Keep React Native Metro and bundling assumptions out of Flutter.
+- Reuse Mach credentials, signing, artifact upload, build pages, and submission flows.
+- Keep `mach build`, `mach submit`, and Dashboard UX unchanged.

package/docs/frameworks/react-native.md

@@ -0,0 +1,159 @@
+# Bare React Native Builds
+
+Use this guide when your project is a vanilla React Native app with committed `ios/` and `android/` directories.
+
+## Required Config
+
+`mach.config.json` must declare the framework explicitly:
+
+```json
+{
+  "framework": "react-native",
+  "ios": {
+    "bundleIdentifier": "com.example.app",
+    "buildNumber": "auto"
+  },
+  "android": {
+    "package": "com.example.app",
+    "versionCode": "auto"
+  }
+}
+```
+
+Mach does not inspect `package.json` to decide whether a project is Expo or React Native. Keep this field accurate before running CI builds.
+
+## When To Use This
+
+Use `framework: "react-native"` when:
+
+- Your native projects are owned by the repository.
+- The app builds from `ios/` and `android/` directly.
+- You do not want Mach to regenerate native projects.
+- You may still use React Native libraries, CocoaPods, Gradle plugins, Firebase, Sentry, or other native integrations manually.
+
+Do not use this value for an Expo project that depends on prebuild to generate native files. Use `framework: "expo"` for that.
+
+## Pipeline Behavior
+
+For bare React Native, Mach:
+
+- Installs JavaScript dependencies.
+- Uses committed native projects.
+- Runs `pod install` for iOS when needed.
+- Runs Xcode archive/export for iOS.
+- Runs Gradle for Android.
+- Applies Mach signing, versioning, artifact upload, and optional store submission.
+
+Mach does not:
+
+- Run `expo prebuild`.
+- Inject Expo-only Gradle properties.
+- Set Expo dev-client exclusion variables.
+- Decide framework from Expo packages in `package.json`.
+
+## Common Commands
+
+```bash
+mach build --platform ios --profile staging
+mach build --platform android --profile staging
+mach build --platform ios --profile production --auto-submit
+mach build --platform android --profile production --auto-submit
+```
+
+## Project Layout
+
+Expected layout:
+
+```text
+my-app/
+  mach.config.json
+  package.json
+  ios/
+  android/
+```
+
+Android should include `android/gradlew`. iOS should include a usable workspace or project. If multiple iOS schemes exist, set the scheme explicitly.
+
+## iOS Notes
+
+Mach uses the existing native iOS project. If multiple schemes exist, set the scheme in config:
+
+```json
+{
+  "ios": {
+    "bundleIdentifier": "com.example.app",
+    "iosScheme": "MyApp",
+    "buildNumber": "auto"
+  }
+}
+```
+
+For store builds, upload iOS signing credentials and App Store Connect credentials from the Dashboard or CLI.
+
+## Android Notes
+
+Mach runs Gradle from `android/gradlew` when present. Production builds default to `bundleRelease`; internal builds default to `assembleRelease`; development-client style builds default to `assembleDebug`.
+
+Set package and version code at the root:
+
+```json
+{
+  "android": {
+    "package": "com.example.app",
+    "versionCode": "auto"
+  }
+}
+```
+
+For Google Play submission and Play-backed versionCode lookup, upload a Google Play service account credential for the exact package id.
+
+## Development Builds
+
+Bare React Native does not use Expo development-client behavior. If a profile contains `developmentClient`, Mach ignores Expo-only dev-client environment handling unless `framework` is `expo`.
+
+For iOS development signing, use:
+
+```json
+{
+  "build": {
+    "development": {
+      "distribution": "development",
+      "environment": "development"
+    }
+  }
+}
+```
+
+For Android debug-style builds, set a custom Gradle command if needed:
+
+```json
+{
+  "build": {
+    "development": {
+      "android": {
+        "buildCommand": "assembleDebug"
+      }
+    }
+  }
+}
+```
+
+## Migration From Expo
+
+If a project previously used Expo and now uses bare React Native:
+
+1. Change `framework` from `"expo"` to `"react-native"`.
+2. Commit the generated native projects.
+3. Remove Expo-only build assumptions from custom prebuild scripts.
+4. Run one staging build before production.
+
+Mach will stop running Expo prebuild as soon as the framework is set to `react-native`.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Build fails with missing `ios/` or `android/` | Commit the native project folders or switch to `framework: "expo"` if Expo should generate them. |
+| Expo prebuild is not running | This is expected for `react-native`. Change `framework` to `expo` only if the project is an Expo app. |
+| Android version code does not update in `app.json` | Bare React Native versioning is native-project driven. Keep native Gradle versioning wired to Mach's generated values. |
+| Dev-client behavior changed after migration | `developmentClient` is Expo-only. Use native debug/release config for bare React Native. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radhya/mach",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Mach CLI: Cloud Build Orchestrator for React Native & Expo",
   "main": "dist/index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "mach": "./dist/index.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "docs/frameworks/"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/commands/isolated-upload.ts --format esm --clean --minify --dts",