@radhya/mach 1.0.2 → 1.2.0

package/README.md

@@ -16,7 +16,7 @@ npm install -g @radhya/mach
 # Login to Mach Dashboard
 mach login
 
-# Initialize a project
+# Initialize a new project
 mach init
 
 # Link an existing project
@@ -45,6 +45,13 @@ mach build --platform android
 | `mach sitemap` | Generate sitemap.xml from Expo Router |
 | `mach audit` | Run automated security audit on the project |
 
+### Legacy Commands
+
+| Command | Description |
+|---------|-------------|
+| `mach credentials:setup` | Automated credential provisioning |
+| `mach credentials:service` | Upload service credentials (ASC API Key / Google Service JSON) |
+
 ## Cloud Builds
 
 Build your apps on cloud infrastructure using AWS Spot Instances — fast, cost-effective, and fully automated.
@@ -66,12 +73,36 @@ mach build --platform android --dry-run
 ### Build Options
 
 - `--platform <os>` — Target platform: `ios` or `android` (required)
-- `--profile <name>` — Build profile: `production`, `staging`, `development`
+- `--profile <name>` — Build profile from `mach.config.json` (e.g., `production`, `staging`, `development`)
+- `--auto-version` — **(Android)** Automatically resolve and increment versionCode via Google Play API
 - `--local` — Run build on local machine
 - `--dry-run` — Generate script without launching
 - `--verbose` — Enable verbose logging
 - `--simulator` — Build for iOS Simulator (no signing required)
 
+## Automated Versioning (Android)
+
+Mach can automatically resolve your next `versionCode` by querying the Google Play Store. This prevents "Duplicate Version Code" rejection errors.
+
+### Setup
+Ensure you have uploaded a **Google Service Account JSON** to the Mach Dashboard under Service Credentials.
+
+### usage
+Set the version code to `"auto"` in your config:
+```json
+"android": {
+  "versionCode": "auto"
+}
+```
+Or pass the flag via CLI:
+```bash
+mach build --platform android --auto-version
+```
+
+> [!TIP]
+> Mach queries all tracks (Internal, Alpha, Beta, Production), finds the highest existing version, and increments it by 1 for your new build.
+
+
 ## Store Submission
 
 Automate your App Store and Google Play submissions directly from the CLI.
@@ -115,24 +146,113 @@ Create a `mach.config.json` in your project root:
     "teamId": "XXXXXXXXXX"
   },
   "android": {
-    "package": "com.example.myapp"
+    "package": "com.example.myapp",
+    "versionCode": "auto"
   }
 }
 ```
 
 ### Build Profiles
 
-Define multiple build profiles for different environments:
+Define multiple build profiles under the `build` key. Profiles support deep inheritance via `extends`.
 
 ```json
 {
   "projectId": "your-project-id",
-  "profiles": {
+  "name": "MyApp",
+  "slug": "my-app",
+  "scheme": "myapp",
+  "android": { "package": "com.example.myapp" },
+  "ios": { "bundleIdentifier": "com.example.myapp" },
+  "build": {
+    "base": {},
     "development": {
-      "ios": { "configuration": "Debug", "exportMethod": "development" }
+      "extends": "base",
+      "developmentClient": true,
+      "environment": "development"
+    },
+    "staging": {
+      "extends": "base",
+      "distribution": "internal"
     },
     "production": {
-      "ios": { "configuration": "Release", "exportMethod": "app-store" }
+      "extends": "base",
+      "distribution": "store"
+    }
+  },
+  "submit": {
+    "production": {
+      "android": { "track": "internal" },
+      "ios": {
+        "ascAppId": "1234567890",
+        "appleTeamId": "XXXXXXXXXX"
+      }
+    }
+  }
+}
+```
+
+### Profile Properties
+
+| Property | Description |
+|----------|-------------|
+| `extends` | Inherit settings from another profile (recursive) |
+| `environment` | Map to a Dashboard Secret Environment (`development`, `staging`, `production`). Defaults to profile name. |
+| `developmentClient` | `true` to build with `expo-dev-client` |
+| `distribution` | `internal` (TestFlight/Play Console) or `store` (Production) |
+| `preBuild` / `postBuild` | Reference a script or run a raw command |
+| `envGroups` | Array of environment group names to merge into this profile |
+
+### Platform Overrides
+
+Any property can be overridden per platform using `ios` or `android` blocks:
+
+```json
+{
+  "build": {
+    "development": {
+      "extends": "base",
+      "developmentClient": true,
+      "ios": {
+        "simulator": true,
+        "iosDeploymentTarget": "15.0"
+      }
+    }
+  }
+}
+```
+
+### Environment Groups
+
+Define reusable sets of environment variables shared across profiles:
+
+```json
+{
+  "envGroups": {
+    "common": {
+      "API_URL": "https://api.example.com"
+    }
+  },
+  "build": {
+    "production": {
+      "envGroups": ["common"]
+    }
+  }
+}
+```
+
+### Scripts
+
+Define custom build hooks:
+
+```json
+{
+  "scripts": {
+    "clean": "rm -rf ios/build android/app/build"
+  },
+  "build": {
+    "production": {
+      "preBuild": "scripts.clean"
     }
   }
 }
@@ -140,14 +260,32 @@ Define multiple build profiles for different environments:
 
 ## Environment Variables
 
+Mach allows you to securely inject secrets directly into your cloud builds without exposing them in your codebase. All secrets are fully encrypted using AES-256-GCM.
+
 ```bash
-# Set environment variables
+# Set environment variables for the project (Defaults to Secret mode)
 mach env set API_URL=https://api.example.com SECRET_KEY=xxx
 
 # List all variables
 mach env list
 ```
 
+### Android Keystore Passwords
+For maximum security, your Android Keystore (`.jks`) file is stored in a separate encrypted S3 bucket away from its passwords. 
+
+To provide your passwords to the Cloud Builder, you **must** define them as Mach Environment variables (Secrets). Mach will automatically securely decrypt and inject them during the Gradle build process.
+
+```bash
+# Set the master password for the keystore (used for both the Keystore and the Key Alias)
+mach env set KEYSTORE_PASSWORD_PRODUCTION=my_super_secret_password
+
+# If your Keystore password and Key Alias password differ, you can set both independently:
+mach env set KEYSTORE_PASSWORD_PRODUCTION=my_key_pass KEYSTORE_STORE_PASSWORD_PRODUCTION=my_store_pass
+```
+
+*(Note: Replace `PRODUCTION` with `STAGING` or `DEVELOPMENT` depending on your targeted build profile).*
+
+
 ## Development Server
 
 ```bash
@@ -172,6 +310,36 @@ mach audit --fix
 mach audit --json  # CI/CD friendly output
 ```
 
+## Authentication
+
+### Interactive Login
+
+```bash
+mach login
+```
+
+Credentials are stored in `~/.mach/credentials.json`.
+
+### CI/CD (Token-based)
+
+Set the `MACH_TOKEN` environment variable for non-interactive authentication:
+
+```bash
+export MACH_TOKEN=your-personal-access-token
+mach build --platform ios --profile production
+```
+
+Generate tokens from the Mach Dashboard under Settings > Personal Access Tokens.
+
+## Environment Variables Reference
+
+| Variable | Description |
+|----------|-------------|
+| `MACH_TOKEN` | Personal access token for CI/CD (skips login) |
+| `MACH_API_URL` | Override the API endpoint (default: `https://mach-api.securejs.in`) |
+| `MACH_DEBUG` | Enable debug logging |
+| `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt) |
+
 ## Requirements
 
 - Node.js 18+
@@ -185,4 +353,4 @@ ISC
 
 ---
 
-Built by [Radhya Softlabs](https://radhya.com)
+Built by [Radhya Softlabs](https://radhyasoftlabs.com)