react-native-bspatch 4.1.0 → 5.0.0

package/tools/doctor.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * doctor.js — checks the whole OTA setup of a project for one release + flavor, read-only.
+ * Run by `npx react-native-bspatch doctor` after the registry was synced from R2 (so the
+ * R2 credentials already work when this runs).
+ *
+ * Usage: node doctor.js <projectRoot> <registryPath> <appVersion> <flavor> <baseUrl> <baseFolder>
+ * Exit 1 when a check fails.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const [root, registryPath, appVersion, flavor, baseUrl, folder] = process.argv.slice(2);
+const tty = process.stdout.isTTY;
+const c = (code, text) => (tty ? `\x1b[${code}m${text}\x1b[0m` : text);
+let failed = 0;
+const line = (mark, label, text) => console.log(`  ${mark} ${c('36', label.padEnd(10))}${text}`);
+const ok = (label, text) => line(c('32', '✓'), label, text);
+const warn = (label, text) => line(c('33', '⚠'), label, text);
+const bad = (label, text) => {
+  failed++;
+  line(c('31', '✗'), label, text);
+};
+const read = (rel) => {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+};
+const find = (dir, name) => {
+  const out = [];
+  const walk = (d, depth) => {
+    if (depth > 10) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {}
+    for (const e of entries) {
+      if (['Pods', 'build', 'node_modules', '.gradle'].includes(e.name)) continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.name === name) out.push(full);
+    }
+  };
+  walk(path.join(root, dir), 0);
+  return out;
+};
+
+(async () => {
+  console.log(`\n  ${c('1', 'doctor')} ${c('2', `· ${appVersion} · ${flavor}`)}\n`);
+  const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  const group = registry.apps?.[appVersion]?.flavors?.[flavor];
+
+  // ── Storage: the URL the app reads serves what was uploaded to the bucket ──
+  if (/\.r2\.dev\b/.test(baseUrl)) warn('storage', `${baseUrl} is R2's rate-limited dev URL: connect a custom domain for production`);
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, '')}/${folder}/ota_registry.json?cb=${Date.now()}`, {
+      headers: { 'Cache-Control': 'no-cache' },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (res.status === 404 && !Object.keys(registry.apps || {}).length) {
+      warn('storage', `${new URL(baseUrl).host} works; nothing published to this bucket yet (the first patch creates the registry)`);
+      throw null;
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const served = await res.json();
+    if (JSON.stringify(served) === JSON.stringify(registry)) ok('storage', `${new URL(baseUrl).host} serves the bucket's registry`);
+    else bad('storage', `${new URL(baseUrl).host} serves a different registry than the bucket: OTA_BASE_URL in .env.${flavor} points at another bucket (or a stale cache)`);
+  } catch (e) {
+    if (e) bad('storage', `OTA_BASE_URL (${baseUrl}) doesn't serve ${folder}/ota_registry.json: ${e.message}`);
+  }
+
+  // ── Signing ──
+  const key = spawnSync('node', [path.join(__dirname, 'ensure_signing_key.js'), root, registryPath, '--check'], { encoding: 'utf8' });
+  const keyText = (key.stdout.trim() || key.stderr.trim().replace(/^\s*❌\s*/, '')).split('\n')[0];
+  if (key.status === 0) ok('signing', keyText);
+  else if (key.status === 2) warn('signing', keyText);
+  else bad('signing', keyText);
+  if (fs.existsSync(path.join(root, 'ota_private_key.backup.pem'))) {
+    warn('backup', 'ota_private_key.backup.pem is on this machine: keep it offline (password manager) and delete it here');
+  }
+
+  // ── Native wiring ──
+  const appDelegate = find('ios', 'AppDelegate.swift')[0];
+  if (!appDelegate) warn('iOS', 'no AppDelegate.swift found');
+  else if (fs.readFileSync(appDelegate, 'utf8').includes('OtaBundleResolver.resolve')) ok('iOS', 'AppDelegate loads the OTA bundle');
+  else bad('iOS', 'AppDelegate doesn\'t load the OTA bundle: run `npx react-native-bspatch setup`');
+  const pbxproj = find('ios', 'project.pbxproj')[0];
+  if (pbxproj && !fs.readFileSync(pbxproj, 'utf8').includes('[react-native-bspatch] runtime fingerprint')) {
+    bad('iOS', 'no runtime fingerprint build step: run `npx react-native-bspatch setup`, then rebuild');
+  }
+  const mainApp = find('android', 'MainApplication.kt')[0];
+  if (!mainApp) warn('Android', 'no MainApplication.kt found');
+  else if (fs.readFileSync(mainApp, 'utf8').includes('OtaBundleResolver.resolve')) ok('Android', 'MainApplication loads the OTA bundle');
+  else bad('Android', 'MainApplication doesn\'t load the OTA bundle: run `npx react-native-bspatch setup`');
+
+  let installed;
+  try {
+    installed = JSON.parse(read('node_modules/react-native-bspatch/package.json')).version;
+  } catch {}
+  const podVersion = read('ios/Podfile.lock').match(/- react-native-bspatch \(([^)]+)\)/)?.[1];
+  if (installed && podVersion && podVersion !== installed) {
+    bad('pods', `Podfile.lock has react-native-bspatch ${podVersion}, node_modules ${installed}: run pod install`);
+  }
+
+  // ── Native fingerprint vs what's live ──
+  for (const platform of ['ios', 'android']) {
+    const fp = spawnSync('node', [path.join(__dirname, 'fingerprint.js'), root, platform], { encoding: 'utf8' }).stdout.trim();
+    const live = (group?.patches || []).find(e => e.platform === platform);
+    if (!live) ok(platform, `fingerprint ${fp} ${c('2', '(no OTA live yet)')}`);
+    else if (!live.runtimeFingerprint) warn(platform, `fingerprint ${fp}; live v${live.toVersion} has none (published by an older CLI)`);
+    else if (live.runtimeFingerprint === fp) ok(platform, `fingerprint ${fp} = live v${live.toVersion}`);
+    else warn(platform, `fingerprint ${fp} ≠ live v${live.toVersion} (${live.runtimeFingerprint}): native code changed, the next OTA only reaches a new store build`);
+  }
+
+  // ── Tools ──
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < 18) bad('node', `Node ${process.versions.node}: 18+ needed`);
+  const hermesc = ['node_modules/hermes-compiler/hermesc', 'node_modules/react-native/sdks/hermesc']
+    .flatMap(d => ['osx-bin', 'linux64-bin'].map(b => path.join(root, d, b, 'hermesc')))
+    .find(p => fs.existsSync(p));
+  if (hermesc) ok('hermesc', path.relative(root, hermesc));
+  else bad('hermesc', 'not found in node_modules: is react-native installed?');
+
+  console.log(failed ? `\n  ${c('31', `${failed} problem(s)`)}\n` : `\n  ${c('32', 'all good')}\n`);
+  process.exit(failed ? 1 : 0);
+})();

package/tools/ensure_signing_key.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * ensure_signing_key.js — run by `patch` before building, so signing needs no setup step.
+ *
+ * The app embeds two public keys: the signing key and an offline backup
+ * (ota_private_key.backup.pem), so a lost or leaked signing key is replaced by promoting
+ * the backup, without a store build.
+ *
+ * Key present → every place the app has keys (Info.plist, Android resource, `publicKey:`
+ * in JS) must include it; it gets embedded natively, with a backup, if the app has none.
+ * Key missing → a new pair is created and embedded, but only for an app that has never
+ * been signed: a new key for an app whose installs verify the old one would make every
+ * update fail, so that case (and CI) stops with what to do instead.
+ *
+ * Usage: node ensure_signing_key.js <projectRoot> <registryPath> [--interactive | --check]
+ * --check (doctor): never writes; exit 2 when `patch` would create or embed something.
+ * stdout: one status line. Errors and guidance go to stderr; exit 1 on error.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const [root, registryPath, ...flags] = process.argv.slice(2);
+const interactive = flags.includes('--interactive');
+const checkOnly = flags.includes('--check');
+const KEY_FILE = path.join(root, 'ota_private_key.pem');
+const BACKUP_FILE = path.join(root, 'ota_private_key.backup.pem');
+const ANDROID_RES = path.join(root, 'android/app/src/main/res/values/bspatch_public_key.xml');
+
+const fail = (message) => {
+  console.error(message);
+  process.exit(1);
+};
+const rel = (p) => path.relative(root, p);
+const spki = (key) => crypto.createPublicKey(key).export({ type: 'spki', format: 'der' });
+const keyId = (der) => crypto.createHash('sha256').update(der).digest('hex').slice(0, 16);
+const split = (keys) => keys.split(/[\s,]+/).filter(Boolean);
+const newPrivateKey = () =>
+  crypto.generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+  }).privateKey;
+const ignore = (file) => {
+  const gitignore = path.join(root, '.gitignore');
+  const name = path.basename(file);
+  const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf8') : '';
+  if (!new RegExp(`^/?${name.replace(/\./g, '\\.')}$`, 'm').test(content)) {
+    fs.appendFileSync(gitignore, `${content.endsWith('\n') || !content ? '' : '\n'}${name}\n`);
+  }
+};
+/** The backup's public key, creating the backup (gitignored) if there is none */
+const backupPublicKey = () => {
+  if (!fs.existsSync(BACKUP_FILE)) {
+    fs.writeFileSync(BACKUP_FILE, newPrivateKey(), { mode: 0o600 });
+    ignore(BACKUP_FILE);
+    console.error(
+      `  ✓ Created the backup signing key ${rel(BACKUP_FILE)}: move it OFF this machine (password manager).\n` +
+        '    If the signing key is ever lost or leaked, put it back as ota_private_key.pem: installed apps already trust it.',
+    );
+  }
+  return spki(fs.readFileSync(BACKUP_FILE, 'utf8')).toString('base64');
+};
+
+/** The app target's Info.plist files (one per target/configuration), test targets excluded */
+const infoPlists = () => {
+  const iosDir = path.join(root, 'ios');
+  let projects = [];
+  try {
+    projects = fs.readdirSync(iosDir).filter(f => f.endsWith('.xcodeproj'));
+  } catch {
+    return [];
+  }
+  const plists = new Set();
+  for (const project of projects) {
+    const pbx = fs.readFileSync(path.join(iosDir, project, 'project.pbxproj'), 'utf8');
+    for (const [, value] of pbx.matchAll(/INFOPLIST_FILE = "?([^";]+)"?;/g)) {
+      if (/Tests/.test(value)) continue;
+      const file = path.join(iosDir, value.replace(/^\$\(SRCROOT\)\/?/, ''));
+      if (fs.existsSync(file)) plists.add(file);
+    }
+  }
+  return [...plists];
+};
+
+/** Public keys the app already ships: [{ where, keys, native }] */
+const appKeys = () => {
+  const keys = [];
+  for (const plist of infoPlists()) {
+    try {
+      const key = execFileSync('plutil', ['-extract', 'BsPatchPublicKey', 'raw', '-o', '-', plist], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).toString().trim();
+      if (key) keys.push({ where: rel(plist), keys: split(key), native: true });
+    } catch {} // no such key (or no plutil off macOS)
+  }
+  const res = fs.existsSync(ANDROID_RES) && fs.readFileSync(ANDROID_RES, 'utf8').match(/<string[^>]*>([^<]+)</);
+  if (res) keys.push({ where: rel(ANDROID_RES), keys: split(res[1]), native: true });
+  // `publicKey: '…'` passed to OtaProvider
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!['node_modules', 'ios', 'android', '.git'].includes(e.name) && !e.name.startsWith('.')) walk(full);
+      } else if (/\.(tsx?|jsx?)$/.test(e.name)) {
+        const m = fs.readFileSync(full, 'utf8').match(/publicKey\s*:\s*['"`]([A-Za-z0-9+/=\s-]{100,}?)['"`]/);
+        if (m) keys.push({ where: rel(full), keys: split(m[1]), native: false });
+      }
+    }
+  };
+  walk(root);
+  return keys;
+};
+
+/** Embeds the public keys natively (comma-separated); returns where they went */
+const embed = (publicKeys) => {
+  const publicKeyBase64 = publicKeys.join(',');
+  const written = [];
+  if (fs.existsSync(path.dirname(path.dirname(ANDROID_RES)))) {
+    fs.mkdirSync(path.dirname(ANDROID_RES), { recursive: true });
+    fs.writeFileSync(
+      ANDROID_RES,
+      `<?xml version="1.0" encoding="utf-8"?>
+<!-- react-native-bspatch: public key OTA updates are verified with (not a secret) -->
+<resources>
+    <string name="bspatch_public_key" translatable="false">${publicKeyBase64}</string>
+</resources>
+`,
+    );
+    written.push(rel(ANDROID_RES));
+  }
+  for (const plist of infoPlists()) {
+    execFileSync('plutil', ['-replace', 'BsPatchPublicKey', '-string', publicKeyBase64, plist]);
+    written.push(rel(plist));
+  }
+  return written;
+};
+
+const registrySigned = () => {
+  try {
+    const { apps = {} } = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    return Object.values(apps).some(app =>
+      Object.values(app.flavors || {}).some(f =>
+        (f.patches || []).some(e => e.entrySignature || e.bundleSignature || e.signature),
+      ),
+    );
+  } catch {
+    return false;
+  }
+};
+
+const known = appKeys();
+const privateKey = process.env.OTA_PRIVATE_KEY || (fs.existsSync(KEY_FILE) && fs.readFileSync(KEY_FILE, 'utf8'));
+
+if (privateKey) {
+  let der;
+  try {
+    der = spki(privateKey);
+  } catch (e) {
+    fail(`  ❌ The OTA signing key can't be read (${process.env.OTA_PRIVATE_KEY ? 'OTA_PRIVATE_KEY' : rel(KEY_FILE)}): ${e.message}`);
+  }
+  const publicKeyBase64 = der.toString('base64');
+  const wrong = known.filter(k => !k.keys.includes(publicKeyBase64));
+  if (wrong.length) {
+    fail(
+      `  ❌ The OTA signing key isn't one of the public keys in ${wrong.map(k => k.where).join(', ')}.\n` +
+        '     Installed apps would reject every update signed with it: use the original ota_private_key.pem\n' +
+        '     (or the backup key, if the app embeds it).',
+    );
+  }
+  if (checkOnly && !known.some(k => k.native)) {
+    console.log(`key ${keyId(der)} · not embedded in the app yet (the next patch embeds it)`);
+    process.exit(2);
+  }
+  if (known.some(k => k.native)) {
+    console.log(`key ${keyId(der)}`);
+  } else {
+    const where = embed([publicKeyBase64, backupPublicKey()]);
+    console.error(`  ✓ Embedded the signing + backup public keys in ${where.join(', ')}: commit them; store builds from now on verify updates.`);
+    console.log(`key ${keyId(der)} · embedded in app`);
+  }
+} else {
+  if (known.length || registrySigned()) {
+    fail(
+      `  ❌ ota_private_key.pem not found, but this app already ${
+        known.length ? `verifies updates with the keys in ${known.map(k => k.where).join(', ')}` : 'has signed releases'
+      }.\n` +
+        `     Copy the original key to ${KEY_FILE} (CI: set OTA_PRIVATE_KEY), or put the backup key there.\n` +
+        "     Don't create a new one: installed apps would reject every update signed with it.",
+    );
+  }
+  if (checkOnly) {
+    console.log('no signing key yet (the next patch in a terminal creates one)');
+    process.exit(2);
+  }
+  if (!interactive) {
+    fail(
+      '  ❌ No OTA signing key. Run `npx react-native-bspatch patch` once in a terminal: it creates one.\n' +
+        '     Then add the key to CI as OTA_PRIVATE_KEY.',
+    );
+  }
+  const pem = newPrivateKey();
+  fs.writeFileSync(KEY_FILE, pem, { mode: 0o600 });
+  ignore(KEY_FILE);
+  const der = spki(pem);
+  const where = embed([der.toString('base64'), backupPublicKey()]);
+  console.error(
+    `  ✓ Created the OTA signing key ${rel(KEY_FILE)} (gitignored) and embedded its public key, with the backup's, in:\n` +
+      where.map(w => `      ${w}\n`).join('') +
+      '    • Back the signing key up too (password manager, CI secret OTA_PRIVATE_KEY).\n' +
+      '    • Commit the files above: store builds from now on verify every update.',
+  );
+  console.log(`key ${keyId(der)} · created`);
+}

package/tools/fingerprint.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * fingerprint.js — native runtime fingerprint: what an OTA's JS needs from the binary.
+ *
+ * Stamped into the store build (Xcode build phase → bspatch_fingerprint.txt in the .app,
+ * Gradle → resValue bspatch_runtime_fingerprint) and recorded in every registry entry by
+ * `patch`. A client only installs an OTA whose fingerprint matches its binary, so JS that
+ * calls a native module the binary doesn't have never reaches it.
+ *
+ * Inputs (per platform): the react-native version, every direct dependency with native code
+ * for that platform (name@version), and the native dependency lock: ios/Podfile.lock on iOS,
+ * the dependency lines of the Gradle build files on Android. The app's own native sources
+ * are not included: changing AppDelegate/MainApplication needs a new store build anyway.
+ *
+ * Usage: node fingerprint.js <projectRoot> <ios|android> [--explain]
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const [root, platform, flag] = process.argv.slice(2);
+if (!root || !['ios', 'android'].includes(platform)) {
+  console.error('Usage: node fingerprint.js <projectRoot> <ios|android> [--explain]');
+  process.exit(1);
+}
+
+const read = (file) => {
+  try {
+    return fs.readFileSync(path.join(root, file), 'utf8');
+  } catch {
+    return '';
+  }
+};
+const pkg = JSON.parse(read('package.json') || '{}');
+
+const hasNative = (dir) => {
+  const has = (p) => fs.existsSync(path.join(dir, p));
+  if (platform === 'android') return has('android/build.gradle') || has('android/build.gradle.kts');
+  try {
+    return fs.readdirSync(dir).some(f => f.endsWith('.podspec')) || has('ios');
+  } catch {
+    return false;
+  }
+};
+
+/** Hash of a package's native sources (ios/, android/src, cpp/, *.podspec, android/build.gradle) */
+const nativeHash = (dir) => {
+  const hash = crypto.createHash('sha256');
+  const walk = (rel) => {
+    const full = path.join(dir, rel);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      return;
+    }
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(full).sort()) {
+        if (!['build', '.cxx', '.gradle'].includes(name)) walk(path.join(rel, name));
+      }
+    } else {
+      hash.update(rel).update(fs.readFileSync(full));
+    }
+  };
+  for (const rel of ['ios', 'android/src', 'android/build.gradle', 'cpp']) walk(rel);
+  for (const f of fs.readdirSync(dir).filter(f => f.endsWith('.podspec')).sort()) walk(f);
+  return hash.digest('hex').slice(0, 16);
+};
+
+const inputs = [];
+for (const name of Object.keys(pkg.dependencies || {}).sort()) {
+  const dir = path.join(root, 'node_modules', name);
+  let version;
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
+  } catch {
+    continue; // not installed: can't be linked either
+  }
+  if (name === 'react-native-bspatch') {
+    // Its own native code, not its version: a JS-only release of this library ships by OTA
+    inputs.push(`dep ${name}#${nativeHash(dir)}`);
+  } else if (name === 'react-native' || hasNative(dir)) {
+    inputs.push(`dep ${name}@${version}`);
+  }
+}
+
+if (platform === 'ios') {
+  // Skipped: COCOAPODS: (the CocoaPods version that wrote the file) and this library's own
+  // lines (its version and podspec checksum change with JS-only releases; nativeHash covers it)
+  for (const line of read('ios/Podfile.lock').split('\n')) {
+    if (line.trim() && !line.startsWith('COCOAPODS:') && !line.includes('react-native-bspatch')) {
+      inputs.push(`pod ${line.trimEnd()}`);
+    }
+  }
+} else {
+  for (const file of ['android/build.gradle', 'android/app/build.gradle', 'android/settings.gradle']) {
+    for (const line of read(file).split('\n')) {
+      if (/^\s*(implementation|api|classpath|compileOnly|runtimeOnly|include)\b/.test(line)) {
+        inputs.push(`gradle ${file}: ${line.trim()}`);
+      }
+    }
+  }
+  for (const line of read('android/gradle.properties').split('\n')) {
+    if (/^\s*(newArchEnabled|hermesEnabled)\s*=/.test(line)) inputs.push(`prop ${line.trim()}`);
+  }
+}
+
+const fingerprint = crypto.createHash('sha256').update(inputs.join('\n')).digest('hex').slice(0, 16);
+if (flag === '--explain') console.error(inputs.join('\n'));
+console.log(fingerprint);

package/tools/ios_fingerprint.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Xcode build phase step (wired by `react-native-bspatch setup`, run through RN's
+# with-environment.sh so NODE_BINARY is set): stamps the native runtime fingerprint
+# into the .app. An OTA only installs on a binary with the same fingerprint.
+set -e
+DIR=$(cd "$(dirname "$0")" && pwd)
+FP=$("$NODE_BINARY" "$DIR/fingerprint.js" "$SRCROOT/.." ios)
+echo "$FP" > "$TARGET_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/bspatch_fingerprint.txt"
+echo "react-native-bspatch: runtime fingerprint $FP"

package/tools/ota_admin.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * ota_admin.js — release controls and status for one release + flavor (run by build_ota.sh
+ * after it synced the registry).
+ *
+ *   status                      what's live per platform (+ its release_*.json details)
+ *   disable N | enable N        kill switch: no client installs vN
+ *   rollout N <percent>         staged rollout: that share of installs gets vN (100 = everyone)
+ *   mandatory N [--off]         apply vN as soon as it's ready instead of on the next launch
+ *   qa N --ids a,b | --off      only these install IDs (useOta().installId) get vN
+ *
+ * Controls live on the registry entries of the live version and aren't signed: they can
+ * only hold an update back or release one that is already signed.
+ *
+ * Usage: node ota_admin.js <command> <registry> <appVersion> <flavor> <releasesDir>
+ *        [--platform p] [--ids a,b] [--off] [--json] [N] [percent]
+ * Exit 3 when the registry changed (build_ota.sh uploads it), 1 on error.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const argv = process.argv.slice(2);
+const [command, registryPath, appVersion, flavor, releasesDir] = argv;
+const flag = (name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+};
+const platform = flag('--platform');
+const off = argv.includes('--off');
+const json = argv.includes('--json');
+const numbers = argv.slice(5).filter((a, i, all) => /^\d+$/.test(a) && !['--platform', '--ids'].includes(all[i - 1]));
+const [version, percent] = numbers.map(Number);
+
+const tty = process.stdout.isTTY;
+const c = (code, text) => (tty ? `\x1b[${code}m${text}\x1b[0m` : text);
+const fail = (message) => {
+  console.error(`  ❌ ${message}`);
+  process.exit(1);
+};
+
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+const group = registry.apps?.[appVersion]?.flavors?.[flavor];
+if (!group?.patches?.length) fail(`No OTA published for ${appVersion} / ${flavor} yet`);
+const entries = group.patches.filter(e => !platform || e.platform === platform);
+
+const controls = (e) =>
+  [
+    e.disabled && c('31', 'disabled'),
+    e.rolloutPercent !== undefined && c('33', `rollout ${e.rolloutPercent}%`),
+    e.allowInstallIds?.length && c('35', `QA ${e.allowInstallIds.length} install(s)`),
+    e.mandatory && c('36', 'mandatory'),
+  ].filter(Boolean);
+
+if (command === 'status') {
+  const platforms = [...new Set(entries.map(e => e.platform))].sort();
+  const report = platforms.map(p => {
+    const live = entries.filter(e => e.platform === p);
+    const full = live.find(e => !e.filename) || live[0];
+    const file = path.join(releasesDir, `release_${appVersion}_v${full.toVersion}_${p}_${flavor}.json`);
+    const release = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
+    return { platform: p, version: full.toVersion, patchesFrom: live.filter(e => e.filename).map(e => e.fromVersion), entry: full, release };
+  });
+  if (json) {
+    console.log(JSON.stringify({ appVersion, flavor, latestOtaVersion: group.latestOtaVersion, platforms: report }));
+    process.exit(0);
+  }
+  console.log(`  ${c('1', `${appVersion} · ${flavor}`)}  ${c('2', `latest v${group.latestOtaVersion}`)}\n`);
+  for (const { platform: p, version: v, patchesFrom, entry, release } of report) {
+    const state = controls(entry);
+    console.log(`  ${c('1', p.padEnd(8))} v${v}  ${state.length ? state.join(' · ') : c('32', 'live for everyone')}`);
+    const row = (k, text) => console.log(`    ${c('36', k.padEnd(10))}${text}`);
+    if (release) {
+      row('published', `${release.publishedAt.replace('T', ' ').slice(0, 16)} UTC by ${release.publishedBy || '?'}`);
+      if (release.notes) row('notes', release.notes);
+      if (release.git) row('commit', `${release.git.commit.slice(0, 7)} ${c('2', release.git.branch)}${release.git.dirty ? c('33', ' + uncommitted changes') : ''}`);
+      row('bundle', `${(release.bundle.gzipSize / 1048576).toFixed(1)} MB gzip · ${(release.bundle.size / 1048576).toFixed(1)} MB raw`);
+    }
+    row('patches', patchesFrom.length ? patchesFrom.map(f => `v${f}`).join(', ') : c('2', 'none (full bundle only)'));
+    row('native', `${entry.runtimeFingerprint || '?'} ${c('2', `· hermes bytecode ${entry.hermesBytecodeVersion ?? '?'}`)}`);
+    row('signed', entry.entrySignature ? c('32', '✓') : c('33', 'no'));
+    if (entry.allowInstallIds?.length) row('QA ids', entry.allowInstallIds.join(', '));
+    console.log('');
+  }
+  process.exit(0);
+}
+
+// ── Controls: on the live version only (older versions' entries are gone from the registry) ──
+if (!Number.isInteger(version)) fail(`${command} needs a version, e.g. ${command} ${group.latestOtaVersion}`);
+const targets = entries.filter(e => e.toVersion === version);
+if (!targets.length) {
+  fail(`v${version} isn't live for ${appVersion} / ${flavor}${platform ? ` / ${platform}` : ''} (latest is v${group.latestOtaVersion}): controls apply to the live version`);
+}
+const apply = (fn) => targets.forEach(fn);
+let summary;
+switch (command) {
+  case 'disable':
+    apply(e => (e.disabled = true));
+    summary = c('31', `v${version} disabled`) + ': no client installs it; clients already on it stay';
+    break;
+  case 'enable':
+    apply(e => delete e.disabled);
+    summary = c('32', `v${version} enabled`);
+    break;
+  case 'rollout':
+    if (!Number.isInteger(percent) || percent < 0 || percent > 100) fail('rollout needs a percent 0-100, e.g. rollout 7 20');
+    apply(e => (percent === 100 ? delete e.rolloutPercent : (e.rolloutPercent = percent)));
+    summary = percent === 100 ? c('32', `v${version} rolled out to everyone`) : c('33', `v${version} → ${percent}% of installs`);
+    break;
+  case 'mandatory':
+    apply(e => (off ? delete e.mandatory : (e.mandatory = true)));
+    summary = off ? `v${version} no longer mandatory` : c('36', `v${version} mandatory`) + ': applies as soon as it is downloaded';
+    break;
+  case 'qa': {
+    if (off) {
+      apply(e => delete e.allowInstallIds);
+      summary = `v${version} QA list removed`;
+      break;
+    }
+    const ids = (flag('--ids') || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (!ids.length) fail('qa needs --ids <installId,…> (useOta().installId) or --off');
+    apply(e => (e.allowInstallIds = ids));
+    summary = c('35', `v${version} → QA only`) + ` (${ids.length} install${ids.length > 1 ? 's' : ''})`;
+    break;
+  }
+  default:
+    fail(`Unknown command ${command}`);
+}
+fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+console.log(`  ${summary} ${c('2', `· ${[...new Set(targets.map(e => e.platform))].join(' + ')}`)}`);
+process.exit(3);