react-native-bspatch 1.1.2 → 1.1.4

package/src/ota/otaMetadata.ts

@@ -106,9 +106,51 @@ export const registerNewVersion = (
     };
 };
 
+/**
+ * Scans the OTA directory and removes old version directories and leftover temporary files
+ * that are no longer referenced in the active metadata.
+ */
+export const cleanupOldVersions = async (
+    metadata: OtaMetadata,
+    baseVersion: number,
+): Promise<void> => {
+    try {
+        if (!(await ReactNativeBlobUtil.fs.exists(OTA_DIR))) return;
+        const items = await ReactNativeBlobUtil.fs.ls(OTA_DIR);
+
+        // Retain current active version and rollback versions
+        const retainedVersions = new Set<number>([
+            metadata.currentVersion,
+            ...(metadata.previousVersions || []),
+        ]);
+
+        for (const item of items) {
+            // Check if directory matches "v<number>"
+            const versionMatch = item.match(/^v(\d+)$/);
+            if (versionMatch) {
+                const ver = parseInt(versionMatch[1], 10);
+                if (!retainedVersions.has(ver) && ver !== baseVersion) {
+                    const dirPath = `${OTA_DIR}/${item}`;
+                    await ReactNativeBlobUtil.fs.unlink(dirPath).catch(() => {});
+                    if (__DEV__) {
+                        console.log(`[otaMetadata] Cleaned up obsolete OTA version: ${item}`);
+                    }
+                }
+            }
+            // Clean up leftover temporary bundle files (.tmp)
+            if (item.endsWith('.tmp')) {
+                await ReactNativeBlobUtil.fs.unlink(`${OTA_DIR}/${item}`).catch(() => {});
+            }
+        }
+    } catch (e) {
+        console.warn('[otaMetadata] Cleanup old versions failed:', e);
+    }
+};
+
 /**
  * Marks the current session as healthy, indicating a successful boot.
  * This prevents the native bridge from rolling back the version on the next launch.
+ * Also cleans up obsolete version directories from disk.
  *
  * @param defaultVersion - Base version for metadata lookup fallback.
  * @returns The updated metadata.
@@ -117,16 +159,16 @@ export const markHealthy = async (
     defaultVersion: number,
 ): Promise<OtaMetadata> => {
     const metadata = await loadMetadata(defaultVersion);
-    if (metadata.lastLaunchSuccessful && metadata.rollbackCount === 0) {
-        return metadata;
-    }
-
     const updated: OtaMetadata = {
         ...metadata,
         lastLaunchSuccessful: true,
         rollbackCount: 0,
     };
     await saveMetadata(updated);
+
+    // Garbage collect older versions on disk to free storage
+    await cleanupOldVersions(updated, defaultVersion);
+
     return updated;
 };
 

package/src/ota/storage/CustomStorage.ts

@@ -7,8 +7,15 @@ interface TokenCache {
     expiresAt: number;
 }
 
+interface RegistryCache {
+    etag?: string;
+    patches: OtaPatch[];
+}
+
 /** Cache tokens per server endpoint so switching configs invalidates stale tokens. */
 const tokenCache = new Map<string, TokenCache>();
+/** Cache registry ETag and parsed patches to avoid redownloading unmodified manifests. */
+const registryCache = new Map<string, RegistryCache>();
 
 /**
  * Implementation for the custom MinIO-based storage server.
@@ -60,6 +67,8 @@ export class CustomStorageProvider implements OtaStorageProvider {
 
     const { baseUrl, channel, baseFolder = 'bspatch' } = config.customServer;
     const registryPath = `${baseFolder}/ota_registry.json`;
+    const regCacheKey = `${baseUrl}|${registryPath}|${config.appVersion}|${channel}`;
+    const cachedReg = registryCache.get(regCacheKey);
 
     try {
       const token = await this.getAccessToken(config);
@@ -74,11 +83,23 @@ export class CustomStorageProvider implements OtaStorageProvider {
       const registryUrl = linkJson.data;
       if (!registryUrl) throw new Error('Failed to generate registry download link');
 
-      const registryRes = await ReactNativeBlobUtil.fetch('GET', registryUrl);
+      const reqHeaders: Record<string, string> = {};
+      if (cachedReg?.etag) {
+        reqHeaders['If-None-Match'] = cachedReg.etag;
+      }
+
+      const registryRes = await ReactNativeBlobUtil.fetch('GET', registryUrl, reqHeaders);
+      if (registryRes.respInfo.status === 304 && cachedReg) {
+        return cachedReg.patches;
+      }
       if (registryRes.respInfo.status !== 200) {
         throw new Error(`Registry fetch failed with status ${registryRes.respInfo.status}`);
       }
 
+      const etag = registryRes.respInfo.headers?.['etag'] || registryRes.respInfo.headers?.['ETag'];
+      if (!config.appVersion) {
+        throw new Error('[CustomStorage] config.appVersion is required to query OTA registry');
+      }
       const registry = JSON.parse(registryRes.data);
       const appGroup = registry?.apps?.[config.appVersion];
       const flavorGroup = appGroup?.flavors?.[channel.toLowerCase()];
@@ -87,10 +108,12 @@ export class CustomStorageProvider implements OtaStorageProvider {
         return config.bundledPatches || [];
       }
 
-      return (flavorGroup.patches || []).filter((p: OtaPatch) => p.platform === Platform.OS);
+      const matchedPatches = (flavorGroup.patches || []).filter((p: OtaPatch) => p.platform === Platform.OS);
+      registryCache.set(regCacheKey, { etag, patches: matchedPatches });
+      return matchedPatches;
     } catch (error) {
       console.warn('[CustomStorage] Manifest fetch error:', (error as Error).message);
-      return config.bundledPatches || [];
+      return cachedReg?.patches || config.bundledPatches || [];
     }
   }
 

package/src/ota/storage/GitHubRawStorage.ts

@@ -61,6 +61,11 @@ export class GitHubRawStorageProvider implements OtaStorageProvider {
                     ? JSON.parse(res.data)
                     : res.data;
 
+            if (!config.appVersion) {
+                throw new Error(
+                    '[GitHubRawStorage] config.appVersion is required to query OTA registry',
+                );
+            }
             const appGroup = registry?.apps?.[config.appVersion];
             const flavorGroup = appGroup?.flavors?.[channelName];
 

package/src/ota/storage/GitHubReleaseStorage.ts

@@ -59,6 +59,11 @@ export class GitHubReleaseStorageProvider implements OtaStorageProvider {
             }
 
             // Structured: apps["1.0.0"].channels["production"].patches[]
+            if (!config.appVersion) {
+                throw new Error(
+                    '[GitHubReleaseStorage] config.appVersion is required to query OTA registry',
+                );
+            }
             const appGroup = registry?.apps?.[config.appVersion];
             const channelGroup = appGroup?.channels?.[config.githubRelease.repo] // use repo as channel fallback
                 ?? appGroup?.channels?.production

package/src/ota/types.ts

@@ -117,8 +117,8 @@ export type OtaNetworkStrategy = {
 };
 
 export type OtaConfig = {
-    /** Current app versionName (e.g. "1.0.0") */
-    appVersion: string;
+    /** Current app versionName (e.g. "1.0.0"). If omitted, auto-detected from native app. */
+    appVersion?: string;
     /** Initial version baked into the APK (usually 1) */
     baseAppVersion: number;
     /** Default patches if manifest fetch fails */
@@ -213,8 +213,12 @@ export type OtaState = {
     pendingCount: number;
     isChecking: boolean;
     metrics: OtaMetrics | null;
+    /** True if a background update has been downloaded and prepared silently */
+    isUpdateReady: boolean;
     applyUpdate: () => Promise<void>;
     resetToFactory: () => Promise<void>;
     markAsHealthy: () => Promise<void>;
     checkUpdate: () => Promise<void>;
+    /** Reload the React Native JS bundle immediately to apply downloaded update */
+    reloadBundle: () => void;
 };

package/tools/build_ota.sh

@@ -42,19 +42,44 @@ fi
 FLAVOR="dev"
 ACTION="ota"
 PLATFORM_ARG=""
+APP_VERSION_ARG=""
+NON_INTERACTIVE=false
+
+SEED_APK=""
+SEED_IPA=""
+SEED_BUNDLE=""
+FORCE_BASE=false
 
-PUSH_REMOTE=false
 # Arg parsing
 while [[ "$#" -gt 0 ]]; do
   case $1 in
     --platform) PLATFORM_ARG="$2"; shift ;;
     --flavor) FLAVOR="$2"; shift ;;
+    --app-version) APP_VERSION_ARG="$2"; shift ;;
+    --apk) SEED_APK="$2"; ACTION="seed"; shift ;;
+    --ipa) SEED_IPA="$2"; ACTION="seed"; shift ;;
+    --bundle) SEED_BUNDLE="$2"; ACTION="seed"; shift ;;
+    --force) FORCE_BASE=true ;;
+    -y|--yes|--non-interactive) NON_INTERACTIVE=true ;;
     --push) PUSH_REMOTE=true ;;
     reset|base) ACTION="$1" ;;
     setup) ACTION="$1" ;;
-    apk|ipa|seed) ACTION="base" ;; # Compatibility for legacy/seed actions
+    seed) ACTION="seed" ;;
+    apk|ipa) ACTION="base" ;; # Compatibility for legacy actions
     dev|staging|production) FLAVOR="$1" ;; # Support positional flavor
     [0-9]*) ;; # Ignore version if passed as $1 (pos 1 usually)
+    *)
+      if [[ "$1" == *.apk ]] || [[ "$1" == *.aab ]]; then
+        SEED_APK="$1"
+        ACTION="seed"
+      elif [[ "$1" == *.ipa ]]; then
+        SEED_IPA="$1"
+        ACTION="seed"
+      elif [[ "$1" == *.hbc ]] || [[ "$1" == *.bundle ]]; then
+        SEED_BUNDLE="$1"
+        ACTION="seed"
+      fi
+      ;;
   esac
   shift
 done
@@ -239,19 +264,111 @@ sha256() {
   shasum -a 256 "$1" | awk '{print $1}'
 }
 
-# ── Extract APP_VERSION from otaConfig.ts ─────────────────────────────────────
-APP_VERSION=$(node -e "
+# ── Auto-Detect APP_VERSION ──────────────────────────────────────────────────
+APP_VERSION_INFO=$(node -e "
   const fs = require('fs');
-  const content = fs.readFileSync('$ROOT/src/ota/otaConfig.ts', 'utf8');
-  const match = content.match(/export const APP_VERSION = ['\"](.+?)['\"]/);
-  console.log(match ? match[1] : 'unknown');
+  const path = require('path');
+  const root = '$ROOT';
+  const cliOverride = '$APP_VERSION_ARG';
+
+  if (cliOverride && cliOverride !== '') {
+    console.log(JSON.stringify({ version: cliOverride, source: 'CLI --app-version' }));
+    process.exit(0);
+  }
+
+  // 1. Try android/app/build.gradle (most reliable for Android release)
+  try {
+    const gradlePath = path.join(root, 'android/app/build.gradle');
+    if (fs.existsSync(gradlePath)) {
+      const content = fs.readFileSync(gradlePath, 'utf8');
+      const match = content.match(/versionName\\s+[\"']([^\"']+)[\"']/);
+      if (match && match[1] !== '0.0.0' && match[1] !== '0.0.1') {
+        console.log(JSON.stringify({ version: match[1], source: 'android/app/build.gradle' }));
+        process.exit(0);
+      }
+    }
+  } catch (e) {}
+
+  // 2. Try ios project.pbxproj (most reliable for iOS release)
+  try {
+    const iosDir = path.join(root, 'ios');
+    if (fs.existsSync(iosDir)) {
+      const files = fs.readdirSync(iosDir);
+      for (const f of files) {
+        if (f.endsWith('.xcodeproj')) {
+          const pbxPath = path.join(iosDir, f, 'project.pbxproj');
+          if (fs.existsSync(pbxPath)) {
+            const content = fs.readFileSync(pbxPath, 'utf8');
+            const match = content.match(/MARKETING_VERSION\\s*=\\s*([^;]+);/);
+            if (match && match[1].trim() !== '0.0.0' && match[1].trim() !== '0.0.1') {
+              console.log(JSON.stringify({ version: match[1].trim(), source: 'ios/' + f }));
+              process.exit(0);
+            }
+          }
+        }
+      }
+    }
+  } catch (e) {}
+
+  // 3. Try package.json
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.version && pkg.version !== '0.0.0' && pkg.version !== '0.0.1') {
+        console.log(JSON.stringify({ version: pkg.version, source: 'package.json' }));
+        process.exit(0);
+      }
+    }
+  } catch (e) {}
+
+  // 4. Fallback: src/ota/otaConfig.ts
+  try {
+    const otaConfigPath = path.join(root, 'src/ota/otaConfig.ts');
+    if (fs.existsSync(otaConfigPath)) {
+      const content = fs.readFileSync(otaConfigPath, 'utf8');
+      const match = content.match(/export const APP_VERSION = ['\"](.+?)['\"]/);
+      if (match) {
+        console.log(JSON.stringify({ version: match[1], source: 'src/ota/otaConfig.ts' }));
+        process.exit(0);
+      }
+    }
+  } catch (e) {}
+
+  console.log(JSON.stringify({ version: 'unknown', source: 'none' }));
 ")
 
-if [ "$APP_VERSION" == "unknown" ]; then
-  echo "ERROR: Could not find APP_VERSION in otaConfig.ts"
+APP_VERSION=$(node -e "try { console.log(JSON.parse('$APP_VERSION_INFO').version); } catch(e) { console.log('unknown'); }")
+APP_VERSION_SOURCE=$(node -e "try { console.log(JSON.parse('$APP_VERSION_INFO').source); } catch(e) { console.log('none'); }")
+
+# Interactive confirmation / prompt:
+# Prompt if running in an interactive terminal, not in reset mode, and no explicit flags passed
+if [ -t 0 ] && [ -z "$APP_VERSION_ARG" ] && [ "$NON_INTERACTIVE" = false ] && [ "$ACTION" != "reset" ]; then
+  echo ""
+  echo "────────────────────────────────────────────────────────"
+  if [ "$APP_VERSION" != "unknown" ]; then
+    echo "  Detected Native App Version: $APP_VERSION ($APP_VERSION_SOURCE)"
+    read -p "  Enter App Version to build [Press Enter for '$APP_VERSION']: " USER_INPUT_VER
+  else
+    read -p "  Enter Native App Version to build (e.g. 1.0.0): " USER_INPUT_VER
+  fi
+  echo "────────────────────────────────────────────────────────"
+  echo ""
+
+  if [ -n "$USER_INPUT_VER" ]; then
+    APP_VERSION=$(echo "$USER_INPUT_VER" | tr -d ' ')
+    APP_VERSION_SOURCE="User Input"
+  fi
+fi
+
+if [ "$APP_VERSION" == "unknown" ] || [ -z "$APP_VERSION" ]; then
+  echo "ERROR: Native App Version is required to build OTA updates."
+  echo "       Please enter a valid version or use: ./build_ota.sh --app-version <version>"
   exit 1
 fi
 
+echo "  ✓ Building OTA for APP_VERSION=$APP_VERSION (Source: $APP_VERSION_SOURCE)"
+
 # ── Reset ─────────────────────────────────────────────────────────────────────
 if [ "$ACTION" = "reset" ]; then
   echo "Resetting OTA registry and output for flavor '$FLAVOR_LOWER'..."
@@ -301,6 +418,22 @@ if [ ! -f "$BSDIFF" ]; then
   echo "  ✓ bsdiff compiled"
 fi
 
+find_hermesc() {
+  HERMESC_PATH="$ROOT/node_modules/hermes-compiler/hermesc/osx-bin/hermesc"
+  if [ ! -f "$HERMESC_PATH" ]; then
+      HERMESC_PATH="$ROOT/node_modules/react-native/sdks/hermesc/osx-bin/hermesc"
+  fi
+  if [ ! -f "$HERMESC_PATH" ]; then
+      HERMESC_PATH="$ROOT/node_modules/hermes-compiler/hermesc/linux64-bin/hermesc"
+  fi
+  if [ ! -f "$HERMESC_PATH" ]; then
+      HERMESC_PATH="$ROOT/node_modules/react-native/sdks/hermesc/linux64-bin/hermesc"
+  fi
+  if [ ! -f "$HERMESC_PATH" ]; then
+      HERMESC_PATH="$(which hermesc 2>/dev/null || echo "")"
+  fi
+}
+
 build_platform() {
   local PLATFORM="$1"
   local FLAVOR="$2"
@@ -316,9 +449,6 @@ build_platform() {
   echo ""
   echo ">>> Building $PLATFORM | Version: $APP_VERSION | OTA: v$CURRENT → v$NEXT"
 
-  # ── Bundle ──
-# ... (rest of the function omitted for space, but I'll make sure to replace correctly)
-
   # ── Bundle ──
   # Workspace for building
   local WORKSPACE="$OUTPUT/workspace"
@@ -350,10 +480,7 @@ build_platform() {
   fi
 
   # Ensure Hermes bytecode format (for both iOS and Android OTA bundles)
-  HERMESC_PATH="$ROOT/node_modules/hermes-compiler/hermesc/osx-bin/hermesc"
-  if [ ! -f "$HERMESC_PATH" ]; then
-      HERMESC_PATH="$ROOT/node_modules/react-native/sdks/hermesc/osx-bin/hermesc"
-  fi
+  find_hermesc
 
   IS_HBC=false
   if [ -f "$BUNDLE_SOURCE" ]; then
@@ -492,11 +619,159 @@ EOF
   bash "$SCRIPT_DIR/upload_ota_custom.sh" "$APP_VERSION" "$FLAVOR_LOWER" "$NEXT" "$NEW_BUNDLE_PATH" "$PLATFORM"
 }
 
+seed_platform() {
+  local PLATFORM="$1"
+  local FLAVOR="$2"
+  local BINARY_PATH="$3"
+  local FLAVOR_LOWER=$(echo "$FLAVOR" | tr '[:upper:]' '[:lower:]')
+  if [ "$FLAVOR_LOWER" = "dev" ]; then FLAVOR_LOWER="development"; fi
+  if [ "$FLAVOR_LOWER" = "prod" ]; then FLAVOR_LOWER="production"; fi
+
+  local OUTPUT="$ROOT/android/output"
+  if [ "$PLATFORM" == "ios" ]; then OUTPUT="$ROOT/ios/output"; fi
+  mkdir -p "$OUTPUT"
+
+  echo ""
+  echo ">>> Seeding Base Bundle (v1) | Platform: $PLATFORM | App: $APP_VERSION | Flavor: $FLAVOR_LOWER"
+  echo "  Source binary: $BINARY_PATH"
+
+  if [ ! -f "$BINARY_PATH" ]; then
+    echo "  ❌ ERROR: Source binary file not found: $BINARY_PATH"
+    exit 1
+  fi
+
+  local TARGET_BUNDLE="$OUTPUT/bundle_${APP_VERSION}_v1_${PLATFORM}_${FLAVOR_LOWER}.hbc"
+  local BASE_ASSET_MANIFEST="$OUTPUT/base-assets_${PLATFORM}_${FLAVOR_LOWER}.json"
+  local ASSET_MANIFEST_FILE="$OUTPUT/asset-manifest-v1_${FLAVOR_LOWER}.json"
+  local TMP_DIR=$(mktemp -d)
+
+  if [ "$PLATFORM" == "android" ]; then
+    echo "  Extracting index.android.bundle from Android binary..."
+    if unzip -l "$BINARY_PATH" 2>/dev/null | grep -q "assets/index.android.bundle"; then
+      unzip -p "$BINARY_PATH" assets/index.android.bundle > "$TMP_DIR/extracted.bundle"
+    elif unzip -l "$BINARY_PATH" 2>/dev/null | grep -q "base/assets/index.android.bundle"; then
+      unzip -p "$BINARY_PATH" base/assets/index.android.bundle > "$TMP_DIR/extracted.bundle"
+    elif [[ "$BINARY_PATH" == *.bundle ]] || [[ "$BINARY_PATH" == *.hbc ]]; then
+      cp "$BINARY_PATH" "$TMP_DIR/extracted.bundle"
+    else
+      echo "  ❌ ERROR: Could not find 'assets/index.android.bundle' inside $BINARY_PATH"
+      rm -rf "$TMP_DIR"
+      exit 1
+    fi
+  else
+    echo "  Extracting main.jsbundle from iOS binary..."
+    local IPA_ENTRY=$(unzip -l "$BINARY_PATH" 2>/dev/null | grep -o 'Payload/[^/]*\.app/main\.jsbundle' | head -n 1)
+    if [ -n "$IPA_ENTRY" ]; then
+      unzip -p "$BINARY_PATH" "$IPA_ENTRY" > "$TMP_DIR/extracted.bundle"
+    elif unzip -l "$BINARY_PATH" 2>/dev/null | grep -q "main.jsbundle"; then
+      local ANY_BUNDLE=$(unzip -l "$BINARY_PATH" 2>/dev/null | grep -o '[^ ]*main\.jsbundle' | head -n 1)
+      unzip -p "$BINARY_PATH" "$ANY_BUNDLE" > "$TMP_DIR/extracted.bundle"
+    elif [[ "$BINARY_PATH" == *.bundle ]] || [[ "$BINARY_PATH" == *.hbc ]]; then
+      cp "$BINARY_PATH" "$TMP_DIR/extracted.bundle"
+    else
+      echo "  ❌ ERROR: Could not find 'main.jsbundle' inside $BINARY_PATH"
+      rm -rf "$TMP_DIR"
+      exit 1
+    fi
+  fi
+
+  # Check Hermes bytecode format (0xc6 magic number)
+  FIRST_BYTE=$(od -An -N1 -t x1 "$TMP_DIR/extracted.bundle" | tr -d ' ' || echo "")
+  if [ "$FIRST_BYTE" == "c6" ]; then
+    echo "  ✓ Bundle is verified Hermes bytecode format."
+    cp "$TMP_DIR/extracted.bundle" "$TARGET_BUNDLE"
+  else
+    echo "  Bundle is JavaScript text. Compiling to Hermes bytecode..."
+    find_hermesc
+    if [ -z "$HERMESC_PATH" ] || [ ! -f "$HERMESC_PATH" ]; then
+      echo "  ❌ ERROR: hermesc compiler not found. Cannot compile bundle to bytecode."
+      rm -rf "$TMP_DIR"
+      exit 1
+    fi
+    "$HERMESC_PATH" -emit-binary -out "$TARGET_BUNDLE" "$TMP_DIR/extracted.bundle"
+  fi
+
+  # Extract base assets manifest
+  echo "  Scanning assets from binary for base manifest..."
+  local NEW_BASE_ASSETS="{"
+  local ASSET_JSON_LIST="["
+  local FIRST=true
+
+  if [ "$PLATFORM" == "android" ]; then
+    unzip -q -o "$BINARY_PATH" "res/drawable*/*" "res/raw/*" -d "$TMP_DIR/assets_unzipped" 2>/dev/null || true
+  else
+    unzip -q -o "$BINARY_PATH" "Payload/*.app/assets/*" -d "$TMP_DIR/assets_unzipped" 2>/dev/null || true
+  fi
+
+  if [ -d "$TMP_DIR/assets_unzipped" ]; then
+    while IFS= read -r -d '' ASSET_FILE; do
+      local HASH=$(sha256 "$ASSET_FILE")
+      local FNAME=$(basename "$ASSET_FILE")
+      local EX="${FNAME##*.}"
+      local REL_PATH="${ASSET_FILE#$TMP_DIR/assets_unzipped/}"
+      
+      if [ "$NEW_BASE_ASSETS" != "{" ]; then NEW_BASE_ASSETS+=", "; fi
+      NEW_BASE_ASSETS+="\"$REL_PATH\": \"$HASH\""
+
+      if [ "$FIRST" = true ]; then FIRST=false; else ASSET_JSON_LIST+=", "; fi
+      ASSET_JSON_LIST+="{\"hash\": \"$HASH\", \"ext\": \"$EX\", \"originalPath\": \"$REL_PATH\", \"isBase\": true}"
+    done < <(find "$TMP_DIR/assets_unzipped" -type f -print0 2>/dev/null)
+  fi
+
+  NEW_BASE_ASSETS+="}"
+  ASSET_JSON_LIST+="]"
+
+  echo "$NEW_BASE_ASSETS" > "$BASE_ASSET_MANIFEST"
+  cat > "$ASSET_MANIFEST_FILE" << EOF
+{ "version": 1, "appVersion": "$APP_VERSION", "platform": "$PLATFORM", "flavor": "$FLAVOR_LOWER", "assets": $ASSET_JSON_LIST }
+EOF
+
+  rm -rf "$TMP_DIR"
+
+  local BUNDLE_HASH=$(sha256 "$TARGET_BUNDLE")
+  echo "  ✓ Base bundle v1 successfully created: $(basename "$TARGET_BUNDLE")"
+  echo "    SHA-256: $BUNDLE_HASH"
+
+  # Update registry for v1
+  node "$SCRIPT_DIR/update_registry.js" "$REGISTRY_SHARED" "$APP_VERSION" "1" "[]" "$PLATFORM" "$ASSET_MANIFEST_FILE" "$FLAVOR_LOWER"
+
+  # Push if requested
+  if [ "$PUSH_REMOTE" = true ]; then
+    echo "  Pushing seeded base bundle to remote..."
+    bash "$SCRIPT_DIR/upload_ota_custom.sh" "$APP_VERSION" "$FLAVOR_LOWER" "1" "$TARGET_BUNDLE" "$PLATFORM"
+  fi
+
+  echo "  ✓ Seeding complete for $PLATFORM!"
+}
+
 # ── Main ───────────────────────────────────────────────────────────────────
-echo "=== OTA Dual Build | App: $APP_VERSION | Flavor: $FLAVOR ==="
+echo "=== OTA Build Pipeline | App: $APP_VERSION | Flavor: $FLAVOR ==="
 
-# Read current version once to coordinate across platforms
 FLAVOR_LOWER=$(echo "$FLAVOR" | tr '[:upper:]' '[:lower:]')
+if [ "$FLAVOR_LOWER" = "dev" ]; then FLAVOR_LOWER="development"; fi
+if [ "$FLAVOR_LOWER" = "prod" ]; then FLAVOR_LOWER="production"; fi
+
+# ── Seed Action ────────────────────────────────────────────────────────────
+if [ "$ACTION" = "seed" ]; then
+  if [ -n "$SEED_APK" ]; then
+    seed_platform "android" "$FLAVOR_LOWER" "$SEED_APK"
+  elif [ -n "$SEED_IPA" ]; then
+    seed_platform "ios" "$FLAVOR_LOWER" "$SEED_IPA"
+  elif [ -n "$SEED_BUNDLE" ]; then
+    PLATFORM="${PLATFORM_ARG:-android}"
+    seed_platform "$PLATFORM" "$FLAVOR_LOWER" "$SEED_BUNDLE"
+  else
+    echo "❌ Please provide a binary file to seed:"
+    echo "   ./build_ota.sh seed --apk <path-to-apk>"
+    echo "   ./build_ota.sh seed --ipa <path-to-ipa>"
+    exit 1
+  fi
+  echo ""
+  echo "=== Base Seeding Complete ==="
+  exit 0
+fi
+
+# Read current version once to coordinate across platforms
 CURRENT_TOTAL=0
 if [ -f "$REGISTRY_SHARED" ]; then
   CURRENT_TOTAL=$(node -e "
@@ -506,6 +781,79 @@ if [ -f "$REGISTRY_SHARED" ]; then
     } catch(e) { console.log(0); }
   ")
 fi
+
+# ── Fail-Safe Guard for OTA Updates ────────────────────────────────────────
+# If building an OTA patch but no base version (v1) exists in the registry:
+if [ "$ACTION" = "ota" ] && [ $CURRENT_TOTAL -eq 0 ]; then
+  echo "Checking for pre-existing Base Bundle v1..."
+  
+  CHECK_PLATFORMS=()
+  if [ -n "$PLATFORM_ARG" ]; then
+    CHECK_PLATFORMS=("$PLATFORM_ARG")
+  else
+    CHECK_PLATFORMS=("android" "ios")
+  fi
+
+  ALL_FOUND=true
+  MISSING_PLATFORM=""
+  for P in "${CHECK_PLATFORMS[@]}"; do
+    P_OUTPUT="$ROOT/$P/output"
+    P_BASE_BUNDLE="$P_OUTPUT/bundle_${APP_VERSION}_v1_${P}_${FLAVOR_LOWER}.hbc"
+    
+    # Check if local exists
+    if [ ! -f "$P_BASE_BUNDLE" ]; then
+      # Try downloading from remote if available
+      REMOTE_BASE_PATH="$BASE_FOLDER/$APP_VERSION/$FLAVOR_LOWER/$(basename "$P_BASE_BUNDLE")"
+      download_from_minio "$REMOTE_BASE_PATH" "$P_BASE_BUNDLE" || true
+    fi
+
+    if [ -f "$P_BASE_BUNDLE" ]; then
+      echo "  ✓ Found Base Bundle v1 for $P: $(basename "$P_BASE_BUNDLE")"
+      # Auto-adopt base bundle in registry
+      node "$SCRIPT_DIR/update_registry.js" "$REGISTRY_SHARED" "$APP_VERSION" "1" "[]" "$P" "" "$FLAVOR_LOWER"
+    else
+      ALL_FOUND=false
+      MISSING_PLATFORM="$P"
+    fi
+  done
+
+  if [ "$ALL_FOUND" = true ]; then
+    echo "  ✓ Base bundle v1 verified and registered. Proceeding with incremental OTA update..."
+    CURRENT_TOTAL=1
+  else
+    if [ "$FORCE_BASE" = true ]; then
+      echo "  ⚠ Warning: --force flag detected. Creating base bundle v1 from current working tree..."
+      ACTION="base"
+    else
+      echo ""
+      echo "╔══════════════════════════════════════════════════════════════════════════════════════════╗"
+      echo "║ ❌ CANNOT BUILD OTA: MISSING BASE BUNDLE (v1)                                            ║"
+      echo "╠══════════════════════════════════════════════════════════════════════════════════════════╣"
+      echo "║ App Version: $APP_VERSION | Flavor: $FLAVOR_LOWER | Missing: $MISSING_PLATFORM"
+      echo "║"
+      echo "║ No base bundle (v1) was found for this app version (neither locally nor on remote).     ║"
+      echo "║ If an OTA update is built now, it would generate a base bundle from your current         ║"
+      echo "║ working tree, which will MISMATCH the version installed on user devices and force a      ║"
+      echo "║ 100% full-bundle download (wasting bandwidth and bypassing patch benefits).              ║"
+      echo "║"
+      echo "║ How to resolve:                                                                          ║"
+      echo "║ 1. If you already have the release APK/IPA submitted to Google Play / App Store:         ║"
+      echo "║    Seed the exact base bundle from your release binary:                                  ║"
+      echo "║      ./build_ota.sh seed --apk <path-to-apk>                                             ║"
+      echo "║      ./build_ota.sh seed --ipa <path-to-ipa>                                             ║"
+      echo "║"
+      echo "║ 2. If you are preparing a brand new Store release right now from this commit:            ║"
+      echo "║      ./build_ota.sh base                                                                 ║"
+      echo "║"
+      echo "║ 3. If you really want to force create base v1 from current code:                         ║"
+      echo "║      ./build_ota.sh --force                                                              ║"
+      echo "╚══════════════════════════════════════════════════════════════════════════════════════════╝"
+      echo ""
+      exit 1
+    fi
+  fi
+fi
+
 TARGET_OTA=$((CURRENT_TOTAL + 1))
 
 if [ -n "$PLATFORM_ARG" ]; then