@upfluxhq/cli 1.0.2 → 1.2.0

package/README.md

@@ -10,35 +10,61 @@ npm install -g @upfluxhq/cli
 pnpm add -g @upfluxhq/cli
 ```
 
+---
+
 ## Quick Start
 
 ```bash
-# 1. Authenticate with your publish keys (supports multiple!)
-upflux login --key <staging-publish-key>
-upflux login --key <production-publish-key>
+# 1. Initialize project config (creates upflux.json)
+upflux init
+
+# 2. Authenticate with your publish key (from Upflux dashboard)
+upflux login --key <publish-key>
 
-# 2. Upload a release (will prompt if multiple deployments)
-upflux release --label v1.0.0 --mandatory
+# 3. Publish a release (auto-increments buildNumber)
+upflux release
 
-# 3. Check release status
+# 4. Check deployment status
 upflux status
 ```
 
+---
+
 ## Commands
 
-### `login`
+### `init`
 
-Authenticate with the Upflux server. **Supports multiple credentials** - each login adds a new deployment.
+Interactive wizard to configure `upflux.json` in your project root. Replaces manual configuration in your app code with declarative deployment profiles.
 
 ```bash
-upflux login --key <publishKey>
+upflux init [options]
 ```
 
 | Option | Description |
 |--------|-------------|
-| `-k, --key <publishKey>` | Publish key for authentication |
+| `--force` | Overwrite existing `upflux.json` without prompting |
+
+**What it sets up:**
+- App ID & server URL
+- Initial `buildNumber` (`0`) and `runtimeVersion` (e.g. `1.0.0`)
+- Deployment profiles (`development`, `production`, etc.) with client keys (`upx_cli_*`)
+- Safe to commit to git — client keys are read-only
+
+---
+
+### `login`
+
+Authenticate with the Upflux server using your publish key. **Supports multiple credentials** — each login registers another deployment target.
 
-**Example output with multiple logins:**
+```bash
+upflux login --key <publishKey>
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `-k, --key <publishKey>` | ✓ | Publish key (`upx_pub_*`) from the dashboard |
+
+**Example output with multiple credentials:**
 ```
 🔐 Verifying with server...
 ✓ Login successful!
@@ -54,7 +80,7 @@ upflux login --key <publishKey>
 
 ### `logout`
 
-Remove stored credentials.
+Remove stored publish credentials.
 
 ```bash
 upflux logout [options]
@@ -62,14 +88,14 @@ upflux logout [options]
 
 | Option | Description |
 |--------|-------------|
-| `--all` | Remove all credentials |
+| `--all` | Remove all stored credentials |
 
 **Example:**
 ```bash
-# Interactive selection to remove one
+# Interactive selection:
 upflux logout
 
-# Remove all credentials
+# Clear all credentials:
 upflux logout --all
 ```
 
@@ -77,159 +103,105 @@ upflux logout --all
 
 ### `release`
 
-Bundle and upload a new release. **Prompts to select deployment** if multiple are stored.
+Bundle and upload a new OTA release. Prompts for target deployment if multiple are configured.
 
 Automatically detects project type:
-- **React Native**: Uses `react-native bundle` command
-- **Capacitor**: Zips the web directory (detected via `capacitor.config.*`)
+- **React Native**: Runs `react-native bundle` for iOS and Android
+- **Capacitor**: Archives the web assets folder (detected from `capacitor.config.*`)
 
 ```bash
 upflux release [options]
 ```
 
-| Option | Required | Description |
-|--------|----------|-------------|
-| `-l, --label <label>` | ✓ | Release label (e.g., v1.0.0) |
-| `--platform <platform>` | | Target platform: `all`, `ios`, or `android` (defaults to `all`) |
-| `-a, --app <appId>` | | Application ID (auto-detected from credentials) |
-| `-d, --deployment <deploymentId>` | | Deployment ID (prompts if multiple) |
-| `-e, --entry-file <path>` | | Entry file for bundler (default: `index.js`) |
-| `-o, --output-dir <path>` | | Output directory for bundle (default: `./dist`) |
-| `-b, --bundle <path>` | | Skip bundling, use existing bundle file |
-| `--assets <paths...>` | | Skip auto-detection, use these asset files |
-| `-m, --mandatory` | | Mark update as mandatory |
-| `-r, --rollout <number>` | | Rollout percentage (0-100, default: 100) |
-| `-v, --version-range <range>` | | Binary version range (e.g., >=1.0.0) |
-| `--min-binary-version <version>` | | Minimum native binary version required. Devices below this are directed to update from the App Store / Play Store before receiving this OTA. |
-| `--skip-native-check` | | Skip automatic native change detection (useful in CI/CD) |
-| `--dev` | | Create development bundle |
-| `--skip-bundle` | | Skip bundling, use existing files in output dir |
-| `--schedule` | | Create as draft, set schedule time in dashboard |
-| `--capacitor` | | Force Capacitor mode (auto-detected if capacitor.config exists) |
-| `--web-dir <path>` | | Web directory to bundle for Capacitor (default: from config or www) |
-
-**Examples:**
+| Option | Description |
+|--------|-------------|
+| `-l, --label <label>` | Release label (e.g. `v1.0.0`). **Optional** — if omitted, auto-increments `buildNumber` in `upflux.json` (e.g. `1.0.0+1`) |
+| `--platform <platform>` | Target platform: `all`, `ios`, or `android` (default: `all`) |
+| `-a, --app <appId>` | Application ID (auto-detected from stored credentials) |
+| `-d, --deployment <deploymentId>` | Target deployment ID (prompts if multiple exist) |
+| `-m, --mandatory` | Mark update as mandatory |
+| `-r, --rollout <number>` | Rollout percentage: `0`–`100` (default: `100`) |
+| `-v, --version-range <range>` | Target binary version semver range (e.g. `>=1.0.0`) |
+| `--min-binary-version <version>` | Minimum native binary version required. Devices below this receive store update prompts. |
+| `--skip-native-check` | Skip automatic git native change inspection |
+| `--schedule` | Create release as a draft to schedule release time via dashboard |
+| `-e, --entry-file <path>` | React Native entry file (default: `index.js`) |
+| `-o, --output-dir <path>` | Output directory for bundles (default: `./dist`) |
+| `-b, --bundle <path>` | Skip bundler, upload prebuilt bundle file |
+| `--assets <paths...>` | Explicit asset files or directories to include |
+| `--dev` | Create development bundle |
+| `--skip-bundle` | Skip bundling, reuse existing files in output directory |
+| `--capacitor` | Force Capacitor bundling mode |
+| `--web-dir <path>` | Custom web asset directory for Capacitor (default: from config or `www`) |
+
+#### Examples
 
 ```bash
-# Release to selected deployment (prompts if multiple)
-upflux release --label v1.2.0
+# Recommended: Auto-increment buildNumber from upflux.json (e.g. 1.0.0+1 -> 1.0.0+2)
+upflux release
 
-# iOS-only hotfix
-upflux release --label v1.2.1-ios-fix --platform ios
-
-# Android-only release with 50% rollout
-upflux release --label v1.2.2 --platform android --rollout 50
+# Release with explicit custom label
+upflux release --label v1.2.0
 
-# Mandatory update for all platforms
-upflux release --label v1.3.0 --mandatory
+# Mandatory release with gradual 25% rollout
+upflux release --mandatory --rollout 25
 
-# Schedule release (draft mode)
-upflux release --label v1.4.0 --schedule
+# iOS-only emergency hotfix
+upflux release --platform ios
 
-# Capacitor project with custom web directory
-upflux release --label v1.0.0 --capacitor --web-dir dist
-```
-
-**Example output:**
-```
-📦 Bundling for iOS...
-  ✓ iOS bundle created
-📦 Bundling for Android...
-  ✓ Android bundle created
-
-⬆ Uploading release...
-  App: app-970384d3
-  Deployment: 6933e683aa32fe18a1311bbb
-  Deployment Name: production
-  Label: v1.2.0
-  Platform: all
-  Bundle: ./dist/ios/index.ios.bundle
-  Assets: 24 file(s)
-  Rollout: 100%
-  Mandatory: No
-
-📋 Step 1/3: Requesting upload URLs...
-   ✓ Got 26 presigned URLs
-📤 Step 2/3: Uploading files directly to storage...
-   [1/26] index.ios.bundle
-   ...
-   ✓ Uploaded 26 files
-✅ Step 3/3: Confirming release...
-
-✓ Release uploaded successfully!
-──────────────────────────────────
-  ID: 693507a19f6d6a79267633e8
-  Label: v1.2.0
-  iOS Bundle: uploaded
-  Android Bundle: uploaded
-  Rollout: 100%
-  Mandatory: No
-  Status: active
-──────────────────────────────────
+# Capacitor release with custom build folder
+upflux release --capacitor --web-dir build
 ```
 
 ---
 
-## Native Change Detection
-
-The CLI automatically detects native code changes since your last release and warns you when a store update may be required. This helps prevent devices from receiving OTA updates that depend on native features not yet available in their installed binary.
-
-### How It Works
+## Auto-incrementing Build Numbers
 
-1. After each successful release, the CLI saves the current **git commit hash** to `.upflux`.
-2. On the next release, it runs `git diff <lastHash>..HEAD` against native files.
-3. If changes are found, it warns you and offers to auto-set `--min-binary-version`.
+When releasing without `--label`, the CLI reads `upflux.json` at your project root:
 
-> **Note:** Detection requires git. If the project is not a git repo, detection is silently skipped.
-
-### Files Watched
-
-| File | What is detected |
-|---|---|
-| `android/app/build.gradle` | `versionName` bump, `minSdkVersion` change |
-| `android/app/src/main/AndroidManifest.xml` | New permissions |
-| `ios/Podfile` | New native pods |
-| `ios/Podfile.lock` | Any pod version change |
-| `package.json` | New native dependency packages |
-
-### Example Interaction
+1. Reads `runtimeVersion` (e.g., `"1.0.0"`) and current `buildNumber` (e.g., `0`)
+2. Increments `buildNumber` by 1 (`1`)
+3. Generates release label: `1.0.0+1`
+4. Writes updated `buildNumber` back to `upflux.json`
+5. Embeds updated `upflux.json` into the native assets directory
 
+```json
+{
+  "version": 1,
+  "app": {
+    "id": "app-970384d3",
+    "buildNumber": 1,
+    "runtimeVersion": "1.0.0"
+  },
+  "deployments": { ... }
+}
 ```
-⚠️  Native changes detected since last release:
 
-   Android:
-   • build.gradle: versionName → 2.0.0
-   • AndroidManifest.xml: New permission: android.permission.CAMERA
+> 💡 **Best Practice:** Commit `upflux.json` to git after running `upflux release` so the build counter is synchronized across your team and CI/CD pipelines.
 
-   💡 Suggested flags:
-     --min-binary-version 2.0.0
-     --version-range ">=2.0.0"
+---
 
-? How would you like to handle these native changes?
-❯ Auto-apply suggested flags (--min-binary-version 2.0.0 --version-range ">=2.0.0")
-  Enter min-binary-version manually
-  Continue without (not recommended for native changes)
-```
+## Native Change Detection
 
-### Setting `--min-binary-version` Manually
+The CLI automatically inspects native changes since your last release to prevent pushing OTA updates that depend on unreleased native code.
 
-```bash
-# Require devices to have at least v2.0.0 binary before receiving this OTA
-upflux release --label v2.0.0-ota --min-binary-version 2.0.0 --version-range ">=2.0.0"
-```
+### Files Monitored
 
-### Skipping in CI/CD
+| File | Monitored Changes |
+|---|---|
+| `android/app/build.gradle` | `versionName` changes, `minSdkVersion` bumps |
+| `android/app/src/main/AndroidManifest.xml` | Added/removed Android permissions |
+| `ios/Podfile` | Added native CocoaPods |
+| `ios/Podfile.lock` | Updated CocoaPod versions |
+| `package.json` | Newly added native dependencies |
 
-```bash
-# In CI, skip interactive detection and pass flag explicitly
-upflux release --label v2.0.0 --min-binary-version 2.0.0 --skip-native-check
-```
+If changes are detected, the CLI prompts you to automatically set `--min-binary-version`. In CI/CD environments, use `--skip-native-check` or specify `--min-binary-version` directly.
 
 ---
 
 ### `status`
 
-Check deployment status and recent releases.
+View deployment status, active release, rollout percentage, and recent releases.
 
 ```bash
 upflux status [options]
@@ -237,34 +209,26 @@ upflux status [options]
 
 | Option | Description |
 |--------|-------------|
-| `-n, --limit <number>` | Number of releases to show (default: 5) |
+| `-n, --limit <number>` | Number of recent releases to display (default: 5) |
 
-**Example output:**
+**Example:**
 ```
 ⚡ Fetching deployment status...
 
 ╭────────────────────────────────────────────────╮
 │  📱 app-970384d3 → production                  │
 │  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
-│  Current Release: v1.2.0 (iOS & Android)       │
+│  Current Release: 1.0.0+4 (iOS & Android)      │
 │  Status: ● active • 100% rollout               │
-│  Published: 2h ago                             │
+│  Published: 15m ago                            │
 ╰────────────────────────────────────────────────╯
-
-📦 Recent Releases (15 total)
-
-  Label        Platform  Status      Rollout   Published
-  ────────────────────────────────────────────────────────
-  v1.2.0       all       ● active    100%      2h ago
-  v1.1.0       all       ○ expired   100%      3d ago
-  v1.0.0       ios       ○ expired   100%      1w ago
 ```
 
 ---
 
 ### `generate-manifest`
 
-Fetch and display the manifest for a specific release.
+Fetch and display or export the update manifest for a specific release ID.
 
 ```bash
 upflux generate-manifest [options]
@@ -273,51 +237,7 @@ upflux generate-manifest [options]
 | Option | Required | Description |
 |--------|----------|-------------|
 | `-r, --release-id <id>` | ✓ | Release ID (MongoDB ObjectId) |
-| `-o, --output <path>` | | Save manifest to file |
-
-**Example:**
-```bash
-# Print manifest to stdout
-upflux generate-manifest --release-id 693507a19f6d6a79267633e8
-
-# Save to file
-upflux generate-manifest --release-id 693507a19f6d6a79267633e8 --output manifest.json
-```
-
----
-
-## Scheduled Releases
-
-Schedule releases to go live at a specific date and time. Perfect for coordinating updates with marketing campaigns, feature launches, or maintenance windows.
-
-### How It Works
-
-1. Create a release with the `--schedule` flag
-2. The release is uploaded as a **Draft**
-3. Set the scheduled time in the Upflux Dashboard
-4. The release automatically goes live at the scheduled time
-
-### Creating a Scheduled Release
-
-```bash
-# Create a draft release for scheduling
-upflux release --label v2.0.0 --schedule
-
-# Output:
-# ✓ Release uploaded successfully!
-#   ...
-#   Status: DRAFT
-#   📅 Set schedule time in dashboard
-```
-
-### Use Cases
-
-- **Feature launches** - Coordinate with marketing announcements
-- **Global releases** - Release at optimal times for different regions
-- **Maintenance windows** - Deploy during low-traffic periods
-- **Campaign coordination** - Sync with promotional events
-
-> 💡 **Tip:** Combine scheduled releases with rollout percentages for safer deployments. For example, schedule a 10% rollout first, then manually increase after monitoring.
+| `-o, --output <path>` | | Save manifest JSON to file |
 
 ---
 
@@ -327,67 +247,16 @@ upflux release --label v2.0.0 --schedule
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `UPFLUX_API_URL` | API server URL | `https://api.upflux.in/api` |
-
-### Auth File
-
-The CLI stores credentials in `.upflux` in the current directory:
-
-```json
-{
-  "credentials": [
-    {
-      "key": "upflux_pub_xxx...",
-      "appId": "app-970384d3",
-      "deploymentId": "6933e683aa32fe18a1311bbb",
-      "deploymentName": "production"
-    },
-    {
-      "key": "upflux_pub_yyy...",
-      "appId": "app-970384d3",
-      "deploymentId": "6933e683aa32fe18a1311ccc",
-      "deploymentName": "staging"
-    }
-  ],
-  "activeIndex": 0,
-  "lastReleaseHash": "a3f8c12d...",
-  "lastReleaseLabel": "v1.5.0"
-}
-```
-
-> ⚠️ **Important:** Never commit the `.upflux` file to version control. It contains your publish keys. Add it to your `.gitignore`.
+| `UPFLUX_API_URL` | Upflux API server URL | `https://api.upflux.in/api` |
 
----
-
-## Publish Keys
-
-Publish keys are used to authenticate the CLI and can be found in the Upflux dashboard under **Settings → Keys**.
+### Auth Storage (`.upflux`)
 
-Key format: `upflux_pub_<prefix>_<secret>`
+Stored credentials and release metadata are saved in `.upflux` in the current project directory.
 
-Example: `upflux_pub_prod_a1b2c3d4e5f6...`
+> ⚠️ **Important:** Add `.upflux` to your `.gitignore`. It contains your publish keys (`upx_pub_*`).
 
 ---
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm run build
-
-# Run locally
-node dist/index.js --help
-```
-
-## Requirements
-
-- Node.js >= 18.0.0
-- For React Native projects: `react-native` CLI installed
-- For Capacitor projects: Built web assets in configured `webDir`
-
 ## License
 
 MIT

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+declare const init: Command;
+export default init;

package/dist/commands/init.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const UPFLUX_JSON_FILE = path_1.default.join(process.cwd(), "upflux.json");
+const DEFAULT_SERVER_URL = "https://api.upflux.in";
+/**
+ * Build the upflux.json content from collected answers
+ */
+function buildUpfluxJson(appId, serverUrl, runtimeVersion, profiles) {
+    const deployments = {};
+    for (const profile of profiles) {
+        const entry = {
+            clientKey: profile.clientKey,
+        };
+        if (profile.extendsProfile) {
+            entry.extends = profile.extendsProfile;
+        }
+        // Set sensible defaults per profile name
+        if (profile.name === "development") {
+            entry.checkOnLaunch = "always";
+            entry.installMode = "on_next_restart";
+        }
+        else if (profile.name === "production") {
+            entry.checkOnLaunch = "always";
+            entry.installMode = "immediate";
+        }
+        deployments[profile.name] = entry;
+    }
+    return {
+        version: 1,
+        app: Object.assign({ id: appId, buildNumber: 0, runtimeVersion }, (serverUrl !== DEFAULT_SERVER_URL ? { serverUrl } : {})),
+        deployments,
+    };
+}
+const init = new commander_1.Command("init")
+    .description("Scaffold upflux.json in your project root")
+    .option("--force", "Overwrite existing upflux.json")
+    .action(async (opts) => {
+    console.log(chalk_1.default.bold("\n🚀 Upflux Project Setup\n"));
+    // Check if upflux.json already exists
+    if (fs_1.default.existsSync(UPFLUX_JSON_FILE) && !opts.force) {
+        console.log(chalk_1.default.yellow("⚠️  upflux.json already exists."));
+        const { overwrite } = await inquirer_1.default.prompt([
+            {
+                type: "confirm",
+                name: "overwrite",
+                message: "Overwrite it?",
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(chalk_1.default.gray("Aborted."));
+            process.exit(0);
+        }
+    }
+    // Step 1: App ID
+    const { appId } = await inquirer_1.default.prompt([
+        {
+            type: "input",
+            name: "appId",
+            message: "App ID:",
+            validate: (val) => val.trim() ? true : "App ID is required",
+        },
+    ]);
+    // Step 2: Server URL
+    const { serverUrl } = await inquirer_1.default.prompt([
+        {
+            type: "input",
+            name: "serverUrl",
+            message: `Server URL (press Enter for ${DEFAULT_SERVER_URL}):`,
+            default: DEFAULT_SERVER_URL,
+        },
+    ]);
+    // Step 3: Runtime version (semver, used to form auto release labels)
+    const { runtimeVersion } = await inquirer_1.default.prompt([
+        {
+            type: "input",
+            name: "runtimeVersion",
+            message: "Runtime version (e.g. 1.0.0 — update when shipping a new binary):",
+            default: "1.0.0",
+            validate: (val) => {
+                if (!val.trim())
+                    return "Runtime version is required";
+                if (!/^\d+\.\d+\.\d+/.test(val.trim()))
+                    return "Use semver format, e.g. 1.0.0";
+                return true;
+            },
+        },
+    ]);
+    const { selectedProfiles } = await inquirer_1.default.prompt([
+        {
+            type: "checkbox",
+            name: "selectedProfiles",
+            message: "Deployment profiles to create:",
+            choices: [
+                { name: "production", checked: true },
+                { name: "staging", checked: true },
+                { name: "development", checked: true },
+            ],
+            validate: (selected) => selected.length > 0 ? true : "Select at least one profile",
+        },
+    ]);
+    // Step 4: Client keys per profile
+    const profiles = [];
+    for (const profileName of selectedProfiles) {
+        const { clientKey } = await inquirer_1.default.prompt([
+            {
+                type: "input",
+                name: "clientKey",
+                message: `Client key for "${chalk_1.default.cyan(profileName)}" ${chalk_1.default.gray("(upx_cli_xxxxx)")}:`,
+                validate: (val) => {
+                    if (!val.trim())
+                        return "Client key is required";
+                    if (val.trim().length < 10)
+                        return "Client key looks too short";
+                    return true;
+                },
+            },
+        ]);
+        profiles.push({ name: profileName, clientKey: clientKey.trim() });
+    }
+    // Build and write upflux.json
+    const content = buildUpfluxJson(appId.trim(), serverUrl.trim(), runtimeVersion.trim(), profiles);
+    fs_1.default.writeFileSync(UPFLUX_JSON_FILE, JSON.stringify(content, null, 2));
+    console.log(chalk_1.default.green("\n✓ Created upflux.json\n"));
+    // Show what was created
+    console.log(chalk_1.default.gray("Preview:"));
+    console.log(chalk_1.default.gray(JSON.stringify(content, null, 2)));
+    // Usage hint
+    console.log(chalk_1.default.bold("\n📦 SDK Usage:\n"));
+    console.log(chalk_1.default.white(`  import { Upflux } from '@upfluxhq/react-native';\n\n` +
+        `  // Auto-selects 'development' in dev, 'production' in release\n` +
+        `  // Auto-increments buildNumber on every release\n` +
+        `  await Upflux.init();\n\n` +
+        `  // Or specify a profile:\n` +
+        `  await Upflux.init('production');`));
+    // Security note about committing the file
+    console.log(chalk_1.default.cyan("\n💡 Tip: upflux.json is safe to commit to git.\n" +
+        "   upx_cli_* keys are read-only — they cannot publish releases.\n" +
+        "   Only upx_pub_* publish keys should be kept secret.\n"));
+});
+exports.default = init;

package/dist/commands/release.js

@@ -45,6 +45,7 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const archiver_1 = __importDefault(require("archiver"));
 const apiClient_1 = require("../client/apiClient");
 const configStore_1 = require("../config/configStore");
+const native_detector_1 = require("../utils/native-detector");
 /**
  * Default output directory for React Native bundle
  */
@@ -134,11 +135,41 @@ function isValidAppId(appId) {
     return /^[a-zA-Z0-9-_]+$/.test(appId) && appId.length >= 3;
 }
 /**
- * Validate release label format (semver-like)
+ * Validate release label format (semver-like, allows + build metadata)
  */
 function isValidReleaseLabel(label) {
-    // Allow v1.0.0, 1.0.0, v1.0.0-beta, etc.
-    return /^v?\d+\.\d+\.\d+(-[a-zA-Z0-9._-]+)?$/.test(label);
+    // Allow v1.0.0, 1.0.0, v1.0.0-beta, 1.0.0+5, 1.0.0-beta+5, etc.
+    return /^v?\d+\.\d+\.\d+(-[a-zA-Z0-9._-]+)?(\+[a-zA-Z0-9._-]+)?$/.test(label);
+}
+/** Read upflux.json from project root. Returns null if not found. */
+function readRootUpfluxJson() {
+    const filePath = path.resolve('upflux.json');
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** Increment app.buildNumber, write back to upflux.json, return new value. */
+function incrementBuildNumber(json) {
+    var _a;
+    const next = ((_a = json.app.buildNumber) !== null && _a !== void 0 ? _a : 0) + 1;
+    json.app.buildNumber = next;
+    fs.writeFileSync(path.resolve('upflux.json'), JSON.stringify(json, null, 2));
+    return next;
+}
+/**
+ * Generate an auto release label.
+ * With runtimeVersion: "1.0.0+6"   (semver + build counter)
+ * Without:            "v0.0.6"     (bare semver fallback — passes validator)
+ */
+function generateReleaseLabel(buildNumber, runtimeVersion) {
+    return runtimeVersion
+        ? `${runtimeVersion}+${buildNumber}`
+        : `v0.0.${buildNumber}`;
 }
 /**
  * Validate version range format
@@ -255,28 +286,25 @@ function collectAssets(dir) {
     return assets;
 }
 /**
- * Write upflux.json config file to the bundle output directory
+ * Write upflux.json config file to the bundle output directory.
  *
  * This file embeds the OTA version into the app bundle at build time.
- * The SDK reads this on fresh install to know which version the app ships with,
- * preventing unnecessary OTA downloads when the embedded bundle is already latest.
- *
- * @param outputDir - Directory to write upflux.json to
- * @param releaseLabel - The OTA version (e.g., "v1.0.0")
- * @param appId - The app ID
+ * `releaseLabel` is used by the SDK for identity check (am I running the latest?).
+ * `buildNumber` is stored as metadata for display/debugging.
  */
-function writeUpfluxConfig(outputDir, releaseLabel, appId) {
+function writeUpfluxConfig(outputDir, releaseLabel, appId, buildNumber) {
     const config = {
         releaseLabel,
         appId,
         createdAt: new Date().toISOString(),
     };
+    if (buildNumber !== undefined) {
+        config.buildNumber = buildNumber;
+    }
     const configContent = JSON.stringify(config, null, 2);
     const configPath = path.join(outputDir, "upflux.json");
     fs.writeFileSync(configPath, configContent);
-    console.log(chalk_1.default.gray(`   Created upflux.json with version: ${releaseLabel}`));
-    // Also copy to native asset directories so the SDK can read the
-    // embedded version at runtime and skip unnecessary OTA downloads
+    console.log(chalk_1.default.gray(`   Created upflux.json (label: ${releaseLabel}${buildNumber !== undefined ? `, build: ${buildNumber}` : ''})`));
     copyUpfluxConfigToNativeAssets(configContent);
 }
 /**
@@ -316,7 +344,7 @@ const release = new commander_1.Command("release")
     .description("Bundle and upload a new release to Upflux")
     .option("-a, --app <appId>", "Application ID (uses stored value if not provided)")
     .option("-d, --deployment <deploymentId>", "Deployment ID (uses stored value if not provided)")
-    .requiredOption("-l, --label <label>", "Release label (e.g., v1.0.0)")
+    .option("-l, --label <label>", "Release label (e.g., v1.0.0) — omit to auto-increment buildNumber from upflux.json")
     .option("--platform <platform>", "Target platform for the release: all, ios, or android (defaults to all)", "all")
     .option("-e, --entry-file <path>", "Entry file for bundler", DEFAULT_ENTRY_FILE)
     .option("-o, --output-dir <path>", "Output directory for bundle", DEFAULT_OUTPUT_DIR)
@@ -325,9 +353,11 @@ const release = new commander_1.Command("release")
     .option("-m, --mandatory", "Mark update as mandatory", false)
     .option("-r, --rollout <number>", "Rollout percentage (0-100)", "100")
     .option("-v, --version-range <range>", "Binary version range (e.g., >=1.0.0)")
+    .option("--min-binary-version <version>", "Minimum native binary version devices must have before receiving this OTA update. Devices below this version will be directed to update from the app store.")
     .option("--dev", "Create development bundle", false)
     .option("--schedule", "Create as draft, set schedule time in dashboard")
     .option("--skip-bundle", "Skip bundling, use existing files in output dir", false)
+    .option("--skip-native-check", "Skip automatic native change detection (useful in CI/CD)", false)
     .option("--capacitor", "Force Capacitor mode (auto-detected if capacitor.config exists)")
     .option("--web-dir <path>", "Web directory to bundle for Capacitor (default: from config or www)")
     .action(async (opts) => {
@@ -402,11 +432,41 @@ const release = new commander_1.Command("release")
             console.error(chalk_1.default.gray("Deployment ID should be a 24-character MongoDB ObjectId"));
             process.exit(1);
         }
-        // Validation 5: Release label format
-        if (!isValidReleaseLabel(opts.label)) {
-            console.error(chalk_1.default.red("✗ Invalid release label format"));
-            console.error(chalk_1.default.gray("Use semantic versioning: v1.0.0, 1.0.0-beta, etc."));
-            process.exit(1);
+        // ── Label Resolution ─────────────────────────────────────────────
+        // Two paths: manual (--label provided) or auto (buildNumber from upflux.json)
+        let resolvedLabel;
+        const rootJson = readRootUpfluxJson();
+        const currentBuildNumber = rootJson === null || rootJson === void 0 ? void 0 : rootJson.app.buildNumber;
+        if (opts.label) {
+            // Manual mode: validate semver (now allows + notation), still increment buildNumber for tracking
+            if (!isValidReleaseLabel(opts.label)) {
+                console.error(chalk_1.default.red("✗ Invalid release label format"));
+                console.error(chalk_1.default.gray("Use semantic versioning: v1.0.0, 1.0.0-beta, 1.0.0+5, etc."));
+                process.exit(1);
+            }
+            resolvedLabel = opts.label;
+            if (rootJson && currentBuildNumber !== undefined) {
+                const tracked = incrementBuildNumber(rootJson);
+                console.log(chalk_1.default.gray(`  buildNumber → ${tracked} (tracking)`));
+            }
+            console.log(chalk_1.default.gray(`  Label: ${resolvedLabel} (manual)`));
+        }
+        else {
+            // Auto mode: require upflux.json with buildNumber field
+            if (!rootJson) {
+                console.error(chalk_1.default.red("✗ No upflux.json found and no --label provided"));
+                console.error(chalk_1.default.gray("Run: upflux init   OR   upflux release --label v1.0.0"));
+                process.exit(1);
+            }
+            if (rootJson.app.buildNumber === undefined) {
+                console.error(chalk_1.default.red("✗ upflux.json is missing app.buildNumber"));
+                console.error(chalk_1.default.gray('Add "buildNumber": 0 to the app section, or use --label'));
+                process.exit(1);
+            }
+            const nextBuild = incrementBuildNumber(rootJson);
+            resolvedLabel = generateReleaseLabel(nextBuild, rootJson.app.runtimeVersion);
+            console.log(chalk_1.default.green(`  ✓ buildNumber: ${nextBuild - 1} → ${nextBuild}`));
+            console.log(chalk_1.default.gray(`  Label: ${resolvedLabel} (auto)`));
         }
         // Validation 6: Rollout percentage
         const rolloutValidation = isValidRollout(opts.rollout);
@@ -464,10 +524,10 @@ const release = new commander_1.Command("release")
             }
             // Write upflux.json to web directory BEFORE zipping
             // This embeds the OTA version into the Capacitor app bundle
-            writeUpfluxConfig(webDirPath, opts.label, appId);
+            writeUpfluxConfig(webDirPath, resolvedLabel, appId, rootJson === null || rootJson === void 0 ? void 0 : rootJson.app.buildNumber);
             // Zip the web directory
             console.log(chalk_1.default.blue(`📦 Zipping ${webDir}/ directory...`));
-            const zipPath = path.join(outputDir, `bundle-${opts.label}.zip`);
+            const zipPath = path.join(outputDir, `bundle-${resolvedLabel}.zip`);
             bundlePath = await zipDirectory(webDirPath, zipPath);
             console.log(chalk_1.default.green(`✓ Bundle created: ${bundlePath}`));
             // No separate assets for Capacitor - all in zip
@@ -569,8 +629,8 @@ const release = new commander_1.Command("release")
                     : collectAssets(androidAssetsPath);
                 // Write upflux.json to BOTH platform output directories
                 // React Native reads this from bundled assets to know embedded OTA version
-                writeUpfluxConfig(iosOutputDir, opts.label, appId);
-                writeUpfluxConfig(androidOutputDir, opts.label, appId);
+                writeUpfluxConfig(iosOutputDir, resolvedLabel, appId, rootJson === null || rootJson === void 0 ? void 0 : rootJson.app.buildNumber);
+                writeUpfluxConfig(androidOutputDir, resolvedLabel, appId, rootJson === null || rootJson === void 0 ? void 0 : rootJson.app.buildNumber);
                 // Set bundlePath and assetFiles for display (use iOS as primary for logging)
                 bundlePath = iosBundlePath;
                 assetFiles = [...iosAssetFiles, ...androidAssetFiles];
@@ -615,7 +675,81 @@ const release = new commander_1.Command("release")
                 }
                 // Write upflux.json to output directory
                 // React Native reads this from bundled assets to know embedded OTA version
-                writeUpfluxConfig(outputDir, opts.label, appId);
+                writeUpfluxConfig(outputDir, resolvedLabel, appId, rootJson === null || rootJson === void 0 ? void 0 : rootJson.app.buildNumber);
+            }
+        }
+        // ========================================
+        // NATIVE CHANGE DETECTION PHASE
+        // ========================================
+        if (!opts.skipNativeCheck) {
+            const gitStatus = (0, native_detector_1.getGitRepoStatus)();
+            if (!gitStatus) {
+                // Not a git repo or git not installed — skip silently
+                console.log(chalk_1.default.gray("   ⓘ  Git not detected — skipping native change check"));
+            }
+            else {
+                const lastHash = configStore_1.configStore.getLastReleaseHash();
+                const lastLabel = configStore_1.configStore.getLastReleaseLabel();
+                if (!lastHash) {
+                    // First release — nothing to compare against
+                    console.log(chalk_1.default.gray("   ⓘ  First release — native change detection will run from next release"));
+                }
+                else {
+                    console.log(chalk_1.default.gray(`   🔍 Checking native changes since ${lastLabel || lastHash.slice(0, 7)}...`));
+                    const detection = (0, native_detector_1.detectNativeChanges)(lastHash);
+                    if (detection.hasNativeChanges) {
+                        (0, native_detector_1.displayNativeChangeWarning)(detection);
+                        // Only prompt if --min-binary-version not already provided
+                        if (!opts.minBinaryVersion) {
+                            const choices = [
+                                ...(detection.suggestedMinBinaryVersion
+                                    ? [{
+                                            name: `Auto-apply suggested flags (--min-binary-version ${detection.suggestedMinBinaryVersion} --version-range "${detection.suggestedVersionRange}")`,
+                                            value: 'auto',
+                                        }]
+                                    : []),
+                                { name: 'Enter min-binary-version manually', value: 'custom' },
+                                { name: 'Continue without (not recommended for native changes)', value: 'skip' },
+                            ];
+                            const { action } = await inquirer_1.default.prompt([{
+                                    type: 'list',
+                                    name: 'action',
+                                    message: 'How would you like to handle these native changes?',
+                                    choices,
+                                }]);
+                            if (action === 'auto') {
+                                opts.minBinaryVersion = detection.suggestedMinBinaryVersion;
+                                if (!opts.versionRange && detection.suggestedVersionRange) {
+                                    opts.versionRange = detection.suggestedVersionRange;
+                                }
+                                console.log(chalk_1.default.green(`   ✓ --min-binary-version ${opts.minBinaryVersion}`));
+                                console.log(chalk_1.default.green(`   ✓ --version-range ${opts.versionRange}`));
+                            }
+                            else if (action === 'custom') {
+                                const { version } = await inquirer_1.default.prompt([{
+                                        type: 'input',
+                                        name: 'version',
+                                        message: 'Enter minimum binary version (e.g., 2.0.0):',
+                                        default: detection.suggestedMinBinaryVersion,
+                                        validate: (v) => /^\d+\.\d+\.\d+/.test(v) || 'Enter a valid semver version (e.g., 2.0.0)',
+                                    }]);
+                                opts.minBinaryVersion = version;
+                                if (!opts.versionRange) {
+                                    opts.versionRange = `>=${version}`;
+                                }
+                                console.log(chalk_1.default.green(`   ✓ --min-binary-version ${opts.minBinaryVersion}`));
+                                console.log(chalk_1.default.green(`   ✓ --version-range ${opts.versionRange}`));
+                            }
+                            // 'skip' — continue without setting flags
+                        }
+                        else {
+                            console.log(chalk_1.default.gray(`   ⓘ  --min-binary-version already set to ${opts.minBinaryVersion}`));
+                        }
+                    }
+                    else {
+                        console.log(chalk_1.default.green('   ✓ No native changes detected'));
+                    }
+                }
             }
         }
         // ========================================
@@ -625,7 +759,7 @@ const release = new commander_1.Command("release")
         console.log(`  App: ${appId}`);
         console.log(`  Deployment: ${deploymentId}`);
         console.log(`  Deployment Name: ${deploymentName}`);
-        console.log(`  Label: ${opts.label}`);
+        console.log(`  Label: ${resolvedLabel}`);
         console.log(`  Platform: ${platform}`);
         console.log(`  Bundle: ${bundlePath}`);
         console.log(`  Assets: ${assetFiles.length} file(s)`);
@@ -637,6 +771,9 @@ const release = new commander_1.Command("release")
         if (opts.versionRange) {
             console.log(`  Version Range: ${opts.versionRange}`);
         }
+        if (opts.minBinaryVersion) {
+            console.log(`  Min Binary Version: ${chalk_1.default.cyan(opts.minBinaryVersion)}`);
+        }
         // ========================================
         // PRESIGNED URL UPLOAD FLOW
         // ========================================
@@ -654,7 +791,7 @@ const release = new commander_1.Command("release")
         const initResponse = await apiClient_1.apiClient.post("/cli/releases/upload/init", {
             appId,
             deploymentId,
-            releaseLabel: opts.label,
+            releaseLabel: resolvedLabel,
             platform,
             files: fileManifest.map(f => ({
                 type: f.type,
@@ -701,18 +838,9 @@ const release = new commander_1.Command("release")
             }
         }
         // Step 3: Complete upload and create release record
-        const completeResponse = await apiClient_1.apiClient.post("/cli/releases/upload/complete", {
-            uploadId: initResponse.data.uploadId,
-            releaseLabel: opts.label,
-            mandatory: opts.mandatory,
-            rolloutPercentage: rolloutValidation.value,
-            binaryVersionRange: opts.versionRange,
-            platform,
-            isDraft: opts.schedule,
+        const completeResponse = await apiClient_1.apiClient.post("/cli/releases/upload/complete", Object.assign(Object.assign({ uploadId: initResponse.data.uploadId, releaseLabel: resolvedLabel, mandatory: opts.mandatory, rolloutPercentage: rolloutValidation.value, binaryVersionRange: opts.versionRange }, (opts.minBinaryVersion ? { minBinaryVersion: opts.minBinaryVersion } : {})), { platform, isDraft: opts.schedule, 
             // Include bundle sizes
-            iosBundleSize: bundleSizes.ios,
-            androidBundleSize: bundleSizes.android || bundleSizes.single,
-        }, {
+            iosBundleSize: bundleSizes.ios, androidBundleSize: bundleSizes.android || bundleSizes.single }), {
             headers: {
                 "x-publish-key": authKey,
                 "Content-Type": "application/json",
@@ -746,7 +874,16 @@ const release = new commander_1.Command("release")
         if (releaseData.binaryVersionRange) {
             console.log(`  Version Range: ${releaseData.binaryVersionRange}`);
         }
+        if (opts.minBinaryVersion) {
+            console.log(`  Min Binary Version: ${chalk_1.default.cyan(opts.minBinaryVersion)}`);
+        }
         console.log(chalk_1.default.gray("──────────────────────────────────"));
+        // Save git hash after successful release for next detection run
+        const gitStatus = (0, native_detector_1.getGitRepoStatus)();
+        if (gitStatus) {
+            configStore_1.configStore.saveLastReleaseHash(gitStatus.currentHash, resolvedLabel);
+            console.log(chalk_1.default.gray(`   ⓘ  Saved git snapshot for next release detection`));
+        }
     }
     catch (error) {
         console.error(chalk_1.default.red(`\n✗ Failed to upload release: ${error.message}`));

package/dist/config/configStore.d.ts

@@ -69,4 +69,18 @@ export declare const configStore: {
      * Check if authenticated
      */
     isAuthenticated(): boolean;
+    /**
+     * Save the git commit hash and release label from the last successful release.
+     * Used by the native change detector on the next release run.
+     */
+    saveLastReleaseHash(hash: string, label: string): void;
+    /**
+     * Get the git commit hash saved from the last release.
+     * Returns null if no release has been made yet.
+     */
+    getLastReleaseHash(): string | null;
+    /**
+     * Get the release label saved from the last release (for display).
+     */
+    getLastReleaseLabel(): string | null;
 };

package/dist/config/configStore.js

@@ -171,4 +171,30 @@ exports.configStore = {
     isAuthenticated() {
         return this.getCredentials().length > 0;
     },
+    // ============================================
+    // Native change detection helpers
+    // ============================================
+    /**
+     * Save the git commit hash and release label from the last successful release.
+     * Used by the native change detector on the next release run.
+     */
+    saveLastReleaseHash(hash, label) {
+        const config = readConfig();
+        config.lastReleaseHash = hash;
+        config.lastReleaseLabel = label;
+        writeConfig(config);
+    },
+    /**
+     * Get the git commit hash saved from the last release.
+     * Returns null if no release has been made yet.
+     */
+    getLastReleaseHash() {
+        return readConfig().lastReleaseHash || null;
+    },
+    /**
+     * Get the release label saved from the last release (for display).
+     */
+    getLastReleaseLabel() {
+        return readConfig().lastReleaseLabel || null;
+    },
 };

package/dist/index.js

@@ -10,11 +10,13 @@ const logout_1 = __importDefault(require("./commands/logout"));
 const release_1 = __importDefault(require("./commands/release"));
 const status_1 = __importDefault(require("./commands/status"));
 const generate_manifest_1 = __importDefault(require("./commands/generate-manifest"));
+const init_1 = __importDefault(require("./commands/init"));
 const program = new commander_1.Command();
 program
     .name("upflux")
     .description("Upflux CLI for OTA updates")
     .version("1.0.0");
+program.addCommand(init_1.default);
 program.addCommand(login_1.default);
 program.addCommand(logout_1.default);
 program.addCommand(release_1.default);

package/dist/utils/native-detector.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Native Change Detector
+ *
+ * Uses git diff to detect changes in native project files since the last
+ * Upflux release. Helps developers know when to set --min-binary-version.
+ *
+ * If git is not initialized or not available, detection is silently skipped.
+ */
+/**
+ * A single detected native change
+ */
+export interface NativeChange {
+    category: 'android' | 'ios' | 'dependencies';
+    file: string;
+    description: string;
+}
+/**
+ * Result of native change detection
+ */
+export interface DetectionResult {
+    hasNativeChanges: boolean;
+    changes: NativeChange[];
+    /** Extracted from build.gradle versionName +line — used as suggested min version */
+    suggestedMinBinaryVersion?: string;
+    /** e.g., ">=2.0.0" derived from suggestedMinBinaryVersion */
+    suggestedVersionRange?: string;
+}
+/**
+ * Check if git is available and the CWD is a git repository.
+ *
+ * Returns the current HEAD hash if git is usable.
+ * Returns null if git is not available or the directory is not a git repo —
+ * callers should skip detection entirely in this case.
+ */
+export declare function getGitRepoStatus(): {
+    currentHash: string;
+} | null;
+/**
+ * Run git diff between savedHash and HEAD for native files.
+ * Parses added lines (+) to extract structured, meaningful changes.
+ *
+ * @param savedHash - The git commit hash from the previous release
+ */
+export declare function detectNativeChanges(savedHash: string): DetectionResult;
+/**
+ * Pretty-print the detected native changes to the terminal.
+ */
+export declare function displayNativeChangeWarning(result: DetectionResult): void;

package/dist/utils/native-detector.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Native Change Detector
+ *
+ * Uses git diff to detect changes in native project files since the last
+ * Upflux release. Helps developers know when to set --min-binary-version.
+ *
+ * If git is not initialized or not available, detection is silently skipped.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitRepoStatus = getGitRepoStatus;
+exports.detectNativeChanges = detectNativeChanges;
+exports.displayNativeChangeWarning = displayNativeChangeWarning;
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Known native dependency prefixes for package.json scanning
+ */
+const KNOWN_NATIVE_PREFIXES = [
+    'react-native-',
+    '@react-native-community/',
+    '@react-native/',
+    'expo-',
+    '@react-native-firebase/',
+    '@react-native-async-storage/',
+];
+/**
+ * Native files to watch via git diff
+ */
+const NATIVE_FILES = [
+    'android/app/build.gradle',
+    'android/app/src/main/AndroidManifest.xml',
+    'ios/Podfile',
+    'ios/Podfile.lock',
+    'package.json',
+];
+/**
+ * Check if git is available and the CWD is a git repository.
+ *
+ * Returns the current HEAD hash if git is usable.
+ * Returns null if git is not available or the directory is not a git repo —
+ * callers should skip detection entirely in this case.
+ */
+function getGitRepoStatus() {
+    try {
+        (0, child_process_1.execSync)('git rev-parse --git-dir', { stdio: 'pipe' });
+        const hash = (0, child_process_1.execSync)('git rev-parse HEAD', {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        }).trim();
+        return { currentHash: hash };
+    }
+    catch (_a) {
+        // Not a git repo or git is not installed
+        return null;
+    }
+}
+/**
+ * Run git diff between savedHash and HEAD for native files.
+ * Parses added lines (+) to extract structured, meaningful changes.
+ *
+ * @param savedHash - The git commit hash from the previous release
+ */
+function detectNativeChanges(savedHash) {
+    let diffOutput = '';
+    try {
+        diffOutput = (0, child_process_1.execSync)(`git diff ${savedHash}..HEAD -- ${NATIVE_FILES.join(' ')}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    }
+    catch (_a) {
+        // git diff failed (e.g., hash no longer valid in shallow clone) — skip
+        return { hasNativeChanges: false, changes: [] };
+    }
+    if (!diffOutput.trim()) {
+        return { hasNativeChanges: false, changes: [] };
+    }
+    const changes = [];
+    let currentFile = '';
+    let suggestedMinBinaryVersion;
+    for (const line of diffOutput.split('\n')) {
+        // Track which file we are currently diffing
+        if (line.startsWith('+++ b/')) {
+            currentFile = line.replace('+++ b/', '');
+            continue;
+        }
+        // Only inspect added lines; skip diff metadata lines
+        if (!line.startsWith('+') || line.startsWith('+++'))
+            continue;
+        const added = line.slice(1);
+        // ── android/app/build.gradle ──────────────────────────────────────
+        if (currentFile === 'android/app/build.gradle') {
+            const versionMatch = added.match(/versionName\s+["']([^"']+)["']/);
+            if (versionMatch) {
+                suggestedMinBinaryVersion = versionMatch[1];
+                changes.push({
+                    category: 'android',
+                    file: 'build.gradle',
+                    description: `versionName → ${versionMatch[1]}`,
+                });
+            }
+            const minSdkMatch = added.match(/minSdkVersion\s+(\d+)/);
+            if (minSdkMatch) {
+                changes.push({
+                    category: 'android',
+                    file: 'build.gradle',
+                    description: `minSdkVersion → ${minSdkMatch[1]}`,
+                });
+            }
+        }
+        // ── android/app/src/main/AndroidManifest.xml ──────────────────────
+        if (currentFile === 'android/app/src/main/AndroidManifest.xml') {
+            const permMatch = added.match(/uses-permission.*android:name="([^"]+)"/);
+            if (permMatch) {
+                changes.push({
+                    category: 'android',
+                    file: 'AndroidManifest.xml',
+                    description: `New permission: ${permMatch[1]}`,
+                });
+            }
+        }
+        // ── ios/Podfile ────────────────────────────────────────────────────
+        if (currentFile === 'ios/Podfile') {
+            const podMatch = added.match(/^\s*pod\s+["']([^"']+)["']/);
+            if (podMatch) {
+                changes.push({
+                    category: 'ios',
+                    file: 'Podfile',
+                    description: `New pod: ${podMatch[1]}`,
+                });
+            }
+        }
+        // ── ios/Podfile.lock ───────────────────────────────────────────────
+        if (currentFile === 'ios/Podfile.lock') {
+            // Any change to the lock file is significant — report only once
+            if (!changes.some((c) => c.file === 'Podfile.lock')) {
+                changes.push({
+                    category: 'ios',
+                    file: 'Podfile.lock',
+                    description: 'Pod versions changed (Podfile.lock updated)',
+                });
+            }
+        }
+        // ── package.json ───────────────────────────────────────────────────
+        if (currentFile === 'package.json') {
+            // Match new native dependency entries on added lines
+            const depMatch = added.match(/"([^"]+)"\s*:/);
+            if (depMatch &&
+                KNOWN_NATIVE_PREFIXES.some((prefix) => depMatch[1].startsWith(prefix))) {
+                changes.push({
+                    category: 'dependencies',
+                    file: 'package.json',
+                    description: `New native dependency: ${depMatch[1]}`,
+                });
+            }
+        }
+    }
+    return {
+        hasNativeChanges: changes.length > 0,
+        changes,
+        suggestedMinBinaryVersion,
+        suggestedVersionRange: suggestedMinBinaryVersion
+            ? `>=${suggestedMinBinaryVersion}`
+            : undefined,
+    };
+}
+/**
+ * Pretty-print the detected native changes to the terminal.
+ */
+function displayNativeChangeWarning(result) {
+    var _a;
+    console.log(chalk_1.default.yellow('\n⚠️  Native changes detected since last release:\n'));
+    // Group by category for cleaner output
+    const byCategory = {};
+    for (const change of result.changes) {
+        (byCategory[_a = change.category] || (byCategory[_a] = [])).push(change);
+    }
+    for (const [category, items] of Object.entries(byCategory)) {
+        const label = category.charAt(0).toUpperCase() + category.slice(1);
+        console.log(chalk_1.default.bold(`   ${label}:`));
+        for (const item of items) {
+            console.log(chalk_1.default.yellow(`   • ${item.file}: ${item.description}`));
+        }
+    }
+    console.log();
+    if (result.suggestedMinBinaryVersion) {
+        console.log(chalk_1.default.cyan('   💡 These changes likely require a new binary from the app store.'));
+        console.log(chalk_1.default.cyan('      Suggested flags:'));
+        console.log(chalk_1.default.cyan(`        --min-binary-version ${result.suggestedMinBinaryVersion}`));
+        console.log(chalk_1.default.cyan(`        --version-range "${result.suggestedVersionRange}"`));
+    }
+    else {
+        console.log(chalk_1.default.cyan('   💡 Consider setting --min-binary-version and --version-range'));
+        console.log(chalk_1.default.cyan('      if these changes require a new binary from the app store.'));
+    }
+    console.log();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@upfluxhq/cli",
-    "version": "1.0.2",
+    "version": "1.2.0",
     "description": "Upflux CLI for managing OTA updates",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",