@scalebun-release/react-native 2.5.0

package/bin/scalebun.js

@@ -0,0 +1,1004 @@
+#!/usr/bin/env node
+/**
+ * ScaleBun SDK CLI.
+ *
+ *   npx scalebun doctor
+ *
+ * Standalone, dependency-free Node script (no react-native / SDK runtime
+ * imports) so it runs anywhere npx does. It inspects the consumer project on
+ * disk — RN version, New Architecture/bridgeless flag, RNFirebase version,
+ * Firebase config files, Android manifest setup — replicates the SDK's adapter
+ * selection logic, and prints the selected push path plus exact fixes for
+ * anything missing (requirement 6).
+ *
+ * Keep the selection logic here in sync with src/push/adapters/selectAdapter.ts.
+ * Note: the ScaleBunEngage NATIVE token bridge ships inside this SDK, so once the SDK
+ * is installed and the app rebuilt, the native fallback is available wherever a
+ * Firebase config file is present — even when RNFirebase JS is absent/old.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const codemod = require('./lib/iosCodemod');
+const androidCodemod = require('./lib/androidCodemod');
+
+const MIN_BRIDGELESS_RNFIREBASE_MAJOR = 18;
+
+const CWD = process.cwd();
+
+// ─── tiny ANSI helpers (no deps) ────────────────────────────────────────────
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+};
+const supportsColor = process.stdout.isTTY;
+const paint = (s, color) => (supportsColor ? `${color}${s}${C.reset}` : String(s));
+const OK = () => paint('✓', C.green);
+const WARN = () => paint('!', C.yellow);
+const FAIL = () => paint('✗', C.red);
+
+function readJSON(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    } catch {
+        return null;
+    }
+}
+
+function exists(p) {
+    try {
+        return fs.existsSync(p);
+    } catch {
+        return false;
+    }
+}
+
+function firstExisting(globsDirs) {
+    for (const p of globsDirs) {
+        if (exists(p)) return p;
+    }
+    return null;
+}
+
+function pkgVersion(name) {
+    const p = path.join(CWD, 'node_modules', name, 'package.json');
+    const json = readJSON(p);
+    return json && json.version ? String(json.version) : null;
+}
+
+// ─── detection ──────────────────────────────────────────────────────────────
+
+function detect() {
+    const appPkg = readJSON(path.join(CWD, 'package.json')) || {};
+
+    const rnVersion = pkgVersion('react-native');
+    const rnMajorMinor = rnVersion
+        ? rnVersion.split('.').slice(0, 2).map((n) => parseInt(n, 10))
+        : null;
+
+    // New Architecture / bridgeless flags.
+    const gradleProps = readText(path.join(CWD, 'android', 'gradle.properties')) || '';
+    const androidNewArch = /(^|\n)\s*newArchEnabled\s*=\s*true/.test(gradleProps);
+
+    const podfile = readText(path.join(CWD, 'ios', 'Podfile')) || '';
+    const iosNewArchEnv = /RCT_NEW_ARCH_ENABLED\s*=\s*1/.test(podfile);
+
+    const isNewArchitecture = androidNewArch || iosNewArchEnv;
+    // RN >= 0.74 with New Arch defaults to bridgeless.
+    const bridgelessLikely =
+        isNewArchitecture &&
+        rnMajorMinor != null &&
+        (rnMajorMinor[0] > 0 || rnMajorMinor[1] >= 74);
+
+    const rnFirebaseVersion = pkgVersion('@react-native-firebase/app');
+    const hasMessaging = !!pkgVersion('@react-native-firebase/messaging');
+    const rnFirebaseMajor = rnFirebaseVersion
+        ? parseInt(rnFirebaseVersion.split('.')[0], 10)
+        : null;
+
+    const hasNotifee = !!pkgVersion('@notifee/react-native');
+
+    // Firebase config files.
+    const googleServicesJson = path.join(CWD, 'android', 'app', 'google-services.json');
+    const hasGoogleServicesJson = exists(googleServicesJson);
+
+    const iosPlist = firstExisting([
+        path.join(CWD, 'ios', 'GoogleService-Info.plist'),
+        ...listIosPlistCandidates(),
+    ]);
+
+    // The native token bridge ships with this SDK; it can acquire a token wherever
+    // a Firebase config file exists (Android google-services.json / iOS plist).
+    const hasNativeFirebaseConfig = hasGoogleServicesJson || !!iosPlist;
+
+    // Android manifest checks.
+    const manifestPath = path.join(
+        CWD,
+        'android',
+        'app',
+        'src',
+        'main',
+        'AndroidManifest.xml',
+    );
+    const manifest = readText(manifestPath) || '';
+    const hasPostNotifications = /android\.permission\.POST_NOTIFICATIONS/.test(manifest);
+    const hasChannelMeta = /default_notification_channel_id/.test(manifest);
+
+    return {
+        appName: appPkg.name || path.basename(CWD),
+        rnVersion,
+        isNewArchitecture,
+        bridgelessLikely,
+        rnFirebaseVersion,
+        rnFirebaseMajor,
+        hasMessaging,
+        hasNotifee,
+        hasGoogleServicesJson,
+        googleServicesJson,
+        iosPlist,
+        hasNativeFirebaseConfig,
+        manifestExists: !!readText(manifestPath),
+        hasPostNotifications,
+        hasChannelMeta,
+    };
+}
+
+function listIosPlistCandidates() {
+    const iosDir = path.join(CWD, 'ios');
+    const out = [];
+    try {
+        for (const entry of fs.readdirSync(iosDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                out.push(path.join(iosDir, entry.name, 'GoogleService-Info.plist'));
+            }
+        }
+    } catch {
+        // no ios dir
+    }
+    return out;
+}
+
+// ─── adapter selection (mirror of selectAdapter.ts) ─────────────────────────
+
+function rnFirebaseUsable(d) {
+    if (!d.hasMessaging) return false;
+    if (!d.bridgelessLikely) return true;
+    if (d.rnFirebaseMajor == null) return true;
+    return d.rnFirebaseMajor >= MIN_BRIDGELESS_RNFIREBASE_MAJOR;
+}
+
+function selectAdapter(d) {
+    if (rnFirebaseUsable(d)) {
+        if (!d.bridgelessLikely) {
+            return {
+                adapter: 'rnfirebase',
+                usable: true,
+                reason: `RNFirebase adapter (legacy bridge${
+                    d.rnFirebaseVersion ? `, v${d.rnFirebaseVersion}` : ''
+                }).`,
+            };
+        }
+        if (d.rnFirebaseMajor == null) {
+            return {
+                adapter: 'rnfirebase',
+                usable: true,
+                reason:
+                    'RNFirebase adapter (bridgeless) — version unverifiable; ensure >= ' +
+                    MIN_BRIDGELESS_RNFIREBASE_MAJOR,
+            };
+        }
+        return {
+            adapter: 'rnfirebase',
+            usable: true,
+            reason: `RNFirebase adapter (New Architecture/bridgeless, v${d.rnFirebaseVersion}).`,
+        };
+    }
+
+    // Native ScaleBunEngage bridge rescues otherwise-noop cases (token-only).
+    if (d.hasNativeFirebaseConfig) {
+        const why = d.hasMessaging
+            ? `@react-native-firebase v${d.rnFirebaseVersion} is incompatible with bridgeless`
+            : 'no RNFirebase JS installed';
+        return {
+            adapter: 'native',
+            usable: true,
+            reason:
+                `${why} — using the ScaleBunEngage native token bridge (token-only). ` +
+                `Foreground/opened callbacks need @react-native-firebase >= ${MIN_BRIDGELESS_RNFIREBASE_MAJOR} (e.g. v21).`,
+        };
+    }
+
+    if (d.hasMessaging) {
+        return {
+            adapter: 'noop',
+            usable: false,
+            reason:
+                `@react-native-firebase v${d.rnFirebaseVersion} is incompatible with the New ` +
+                'Architecture/bridgeless runtime. Upgrade to >= ' +
+                `${MIN_BRIDGELESS_RNFIREBASE_MAJOR} (e.g. v21), or use provider:"manual".`,
+        };
+    }
+    return {
+        adapter: 'noop',
+        usable: false,
+        reason:
+            'No push provider installed and no Firebase config found. Add ' +
+            '@react-native-firebase/messaging (>= ' +
+            `${MIN_BRIDGELESS_RNFIREBASE_MAJOR} for the New Architecture) + a Firebase config file, ` +
+            'or use enablePush({ provider:"manual", manualToken }).',
+    };
+}
+
+// ─── report ─────────────────────────────────────────────────────────────────
+
+function line(status, label, value) {
+    const v = value == null ? paint('(not detected)', C.dim) : value;
+    console.log(`  ${status} ${label.padEnd(28)} ${v}`);
+}
+
+function runDoctor() {
+    const d = detect();
+    const sel = selectAdapter(d);
+
+    console.log('');
+    console.log(paint('ScaleBun Doctor', C.bold + C.cyan) + paint(`  (${d.appName})`, C.dim));
+    console.log('');
+
+    console.log(paint('Environment', C.bold));
+    line(d.rnVersion ? OK() : FAIL(), 'React Native', d.rnVersion);
+    line(OK(), 'Architecture', d.isNewArchitecture
+        ? (d.bridgelessLikely ? 'New Arch (bridgeless)' : 'New Arch (TurboModules)')
+        : 'Legacy bridge');
+    line(d.hasMessaging ? OK() : WARN(), '@react-native-firebase', d.rnFirebaseVersion);
+    line(d.hasMessaging ? OK() : WARN(), '  messaging installed', d.hasMessaging ? 'yes' : 'no');
+    line(d.hasNotifee ? OK() : WARN(), '@notifee/react-native', d.hasNotifee ? 'yes' : 'no (FCM fallback channel)');
+
+    console.log('');
+    console.log(paint('Firebase config', C.bold));
+    line(d.hasGoogleServicesJson ? OK() : WARN(), 'google-services.json', d.hasGoogleServicesJson ? 'present' : null);
+    line(d.iosPlist ? OK() : WARN(), 'GoogleService-Info.plist', d.iosPlist ? 'present' : null);
+
+    console.log('');
+    console.log(paint('Android setup', C.bold));
+    line(d.hasPostNotifications ? OK() : WARN(), 'POST_NOTIFICATIONS perm', d.hasPostNotifications ? 'declared' : null);
+    line(d.hasChannelMeta ? OK() : WARN(), 'default channel meta', d.hasChannelMeta ? 'declared' : null);
+
+    console.log('');
+    console.log(paint('Selected push adapter (Android / FCM analysis)', C.bold));
+    const selStatus = sel.usable ? OK() : FAIL();
+    line(selStatus, sel.adapter, sel.usable ? 'usable' : paint('NOT usable', C.red));
+    console.log(`  ${paint('reason:', C.dim)} ${sel.reason}`);
+
+    console.log('');
+    console.log(paint('iOS push path', C.bold));
+    console.log(
+        '  ' + OK() + ' iOS uses ' + paint('Direct APNs', C.cyan) +
+            ' automatically (raw APNs device token, pushProvider:apns) — no Firebase required.',
+    );
+    console.log(paint('    Run `npx scalebun init ios --check` to verify the AppDelegate hooks.', C.dim));
+
+    // ─── fixes ──────────────────────────────────────────────────────────
+    const fixes = buildFixes(d, sel);
+    console.log('');
+    if (fixes.length === 0) {
+        console.log(paint('All good — push is ready to enable.', C.green));
+        console.log(paint('  await ScaleBun.enablePush();', C.dim));
+    } else {
+        console.log(paint('Action items', C.bold + C.yellow));
+        fixes.forEach((f, i) => console.log(`  ${i + 1}. ${f}`));
+    }
+    console.log('');
+
+    // Non-zero exit when the selected path can't actually deliver push.
+    process.exit(sel.usable ? 0 : 1);
+}
+
+function buildFixes(d, sel) {
+    const fixes = [];
+
+    if (!d.hasMessaging && (!sel || sel.adapter !== 'manual')) {
+        fixes.push(
+            'For full foreground/opened callbacks install RNFirebase: ' +
+                paint('yarn add @react-native-firebase/app @react-native-firebase/messaging', C.cyan) +
+                (d.bridgelessLikely ? ` (use v${MIN_BRIDGELESS_RNFIREBASE_MAJOR}+ for the New Architecture, e.g. v21)` : ''),
+        );
+    }
+
+    if (
+        d.hasMessaging &&
+        d.bridgelessLikely &&
+        d.rnFirebaseMajor != null &&
+        d.rnFirebaseMajor < MIN_BRIDGELESS_RNFIREBASE_MAJOR
+    ) {
+        fixes.push(
+            `Upgrade @react-native-firebase from v${d.rnFirebaseVersion} to >= ` +
+                `${MIN_BRIDGELESS_RNFIREBASE_MAJOR} (e.g. v21) for the full JS callback surface — the ` +
+                'native bridge still registers the token, but onForeground/onOpened need RNFirebase JS.',
+        );
+    }
+
+    if (!d.hasGoogleServicesJson) {
+        fixes.push(
+            'Add Firebase Android config: ' +
+                paint('android/app/google-services.json', C.cyan) +
+                ' (download from the Firebase console).',
+        );
+    }
+
+    if (!d.iosPlist) {
+        fixes.push(
+            'Add Firebase iOS config: ' +
+                paint('ios/<App>/GoogleService-Info.plist', C.cyan) +
+                ' (download from the Firebase console).',
+        );
+    }
+
+    if (d.manifestExists && !d.hasPostNotifications) {
+        fixes.push(
+            'Declare the Android 13+ permission in AndroidManifest.xml: ' +
+                paint('<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />', C.cyan),
+        );
+    }
+
+    if (d.manifestExists && !d.hasChannelMeta) {
+        fixes.push(
+            'Declare a default FCM channel meta-data in AndroidManifest.xml ' +
+                '(com.google.firebase.messaging.default_notification_channel_id) so backgrounded ' +
+                'notifications have a channel.',
+        );
+    }
+
+    return fixes;
+}
+
+// ─── `init ios` — AppDelegate codemod + capability checklist ─────────────────
+
+function findIosDir() {
+    const iosDir = path.join(CWD, 'ios');
+    return exists(iosDir) ? iosDir : null;
+}
+
+/** Detect iOS APNs project setup that the codemod cannot edit (Xcode/Apple). */
+function detectIosCapabilities(iosDir) {
+    const out = {
+        bundleId: null,
+        apsEnvironment: null, // 'development' | 'production' | null
+        hasRemoteNotificationBgMode: false,
+        entitlementsPath: null,
+        infoPlistPath: null,
+    };
+
+    // Walk ios/<App>/ dirs for entitlements + Info.plist.
+    let appDirs = [];
+    try {
+        appDirs = fs
+            .readdirSync(iosDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(iosDir, e.name));
+    } catch {
+        appDirs = [];
+    }
+
+    for (const dir of appDirs) {
+        // entitlements (first match wins)
+        if (!out.entitlementsPath) {
+            try {
+                const ent = fs
+                    .readdirSync(dir)
+                    .find((f) => f.endsWith('.entitlements'));
+                if (ent) {
+                    out.entitlementsPath = path.join(dir, ent);
+                    const txt = readText(out.entitlementsPath) || '';
+                    const m = /<key>aps-environment<\/key>\s*<string>([^<]+)<\/string>/.exec(txt);
+                    if (m) out.apsEnvironment = m[1].trim();
+                }
+            } catch {
+                /* ignore */
+            }
+        }
+        // Info.plist
+        const infoP = path.join(dir, 'Info.plist');
+        if (!out.infoPlistPath && exists(infoP)) {
+            out.infoPlistPath = infoP;
+            const txt = readText(infoP) || '';
+            const bg = /<key>UIBackgroundModes<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(txt);
+            if (bg && /remote-notification/.test(bg[1])) {
+                out.hasRemoteNotificationBgMode = true;
+            }
+        }
+    }
+
+    // Bundle id from the project file — prefer a non-template id.
+    try {
+        const pbxproj = firstExisting(
+            fs
+                .readdirSync(iosDir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && e.name.endsWith('.xcodeproj'))
+                .map((e) => path.join(iosDir, e.name, 'project.pbxproj')),
+        );
+        if (pbxproj) {
+            const txt = readText(pbxproj) || '';
+            const ids = [...txt.matchAll(/PRODUCT_BUNDLE_IDENTIFIER\s*=\s*"?([^";\n]+)"?/g)].map(
+                (m) => m[1].trim(),
+            );
+            out.bundleId =
+                ids.find((id) => id && !/org\.reactjs\.native\.example|\$\(/.test(id)) ||
+                ids[0] ||
+                null;
+        }
+    } catch {
+        /* ignore */
+    }
+
+    return out;
+}
+
+function printIosChecklist(caps) {
+    console.log('');
+    console.log(paint('iOS APNs project setup (Xcode / Apple — verify in Xcode)', C.bold));
+    line(caps.bundleId ? OK() : WARN(), 'Bundle ID / APNs topic', caps.bundleId);
+    line(
+        caps.apsEnvironment ? OK() : FAIL(),
+        'Push capability (aps-environment)',
+        caps.apsEnvironment ? `${caps.apsEnvironment} (${caps.apsEnvironment === 'production' ? 'production' : 'sandbox'} APNs)` : null,
+    );
+    line(
+        caps.hasRemoteNotificationBgMode ? OK() : WARN(),
+        'Background Modes: remote-notification',
+        caps.hasRemoteNotificationBgMode ? 'enabled' : null,
+    );
+
+    const todo = [];
+    if (!caps.apsEnvironment) {
+        todo.push(
+            'Xcode → Signing & Capabilities → + Capability → Push Notifications ' +
+                '(adds aps-environment to your .entitlements).',
+        );
+    }
+    if (!caps.hasRemoteNotificationBgMode) {
+        todo.push(
+            'Xcode → Signing & Capabilities → + Capability → Background Modes → ' +
+                'check "Remote notifications".',
+        );
+    }
+    todo.push(
+        'ScaleBun dashboard → upload your APNs Auth Key (.p8) + Key ID + Team ID; ' +
+            `set APNs topic = your Bundle ID${caps.bundleId ? ` (${caps.bundleId})` : ''}; ` +
+            'pick sandbox for dev builds / production for TestFlight + App Store.',
+    );
+    todo.push('A physical iPhone is required — the iOS Simulator has no APNs token.');
+
+    console.log('');
+    console.log(paint('Remaining manual setup (cannot be safely automated)', C.bold + C.yellow));
+    todo.forEach((t, i) => console.log(`  ${i + 1}. ${t}`));
+}
+
+function runInitIos(argv) {
+    const flags = new Set(argv);
+    const isCheck = flags.has('--check');
+    const isDryRun = flags.has('--dry-run');
+
+    const iosDir = findIosDir();
+    if (!iosDir) {
+        console.error(paint('✗ No ios/ directory found.', C.red));
+        console.error('  Run this from a React Native project root (the folder containing ios/).');
+        process.exit(2);
+    }
+
+    const found = codemod.findAppDelegate(iosDir, fs, path);
+    if (!found) {
+        console.error(paint('✗ Could not find an AppDelegate under ios/*/.', C.red));
+        console.error('  Expected ios/<App>/AppDelegate.mm, .m, or .swift.');
+        console.error('  This project uses a non-standard layout — patch your AppDelegate manually:');
+        console.error('');
+        console.error(codemod.swiftInstructions());
+        process.exit(2);
+    }
+
+    const rel = path.relative(CWD, found.path);
+    console.log('');
+    console.log(paint('ScaleBun init ios', C.bold + C.cyan));
+    console.log(`  AppDelegate: ${paint(rel, C.cyan)} (${found.kind})`);
+
+    // Swift: not auto-patched — print clear manual instructions, fail non-zero.
+    if (found.kind === 'swift') {
+        console.log('');
+        console.log(codemod.swiftInstructions());
+        console.log('');
+        const caps = detectIosCapabilities(iosDir);
+        printIosChecklist(caps);
+        process.exit(isCheck ? 1 : 2);
+    }
+
+    const original = readText(found.path) || '';
+
+    // --check: verify, never write.
+    if (isCheck) {
+        const a = codemod.analyzeObjc(original);
+        const pushWired = codemod.isFullyWiredObjc(original);
+        const wired = pushWired && a.hasOtaBundleUrl;
+        console.log('');
+        console.log(paint('Push hooks (APNs)', C.bold));
+        line(a.hasImport ? OK() : FAIL(), 'ScaleBun Swift import', a.hasImport ? 'present' : null);
+        line(a.hasFinishLaunchingCall ? OK() : FAIL(), 'didFinishLaunching forward', a.hasFinishLaunchingCall ? 'present' : null);
+        line(a.hasRegisterForward ? OK() : FAIL(), 'didRegister...DeviceToken forward', a.hasRegisterForward ? 'present' : null);
+        line(a.hasFailForward ? OK() : FAIL(), 'didFailToRegister forward', a.hasFailForward ? 'present' : null);
+        console.log('');
+        console.log(paint('OTA bundle resolution', C.bold));
+        line(a.hasOtaBundleUrl ? OK() : FAIL(), 'release bundleURL wiring', a.hasOtaBundleUrl ? 'present' : null);
+        const caps = detectIosCapabilities(iosDir);
+        printIosChecklist(caps);
+        console.log('');
+        if (wired) {
+            console.log(paint('✓ AppDelegate is fully wired for ScaleBun (Direct APNs + OTA).', C.green));
+            process.exit(0);
+        }
+        console.log(paint('✗ AppDelegate is missing ScaleBun wiring. Run `npx scalebun init ios`.', C.red));
+        process.exit(1);
+    }
+
+    const result = codemod.patchObjc(original);
+
+    if (!result.changed) {
+        console.log('');
+        console.log(paint('✓ Already wired — no changes needed (idempotent).', C.green));
+        if (result.manual.length) {
+            console.log('');
+            console.log(paint('Manual follow-ups', C.bold + C.yellow));
+            result.manual.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+        }
+        const caps0 = detectIosCapabilities(iosDir);
+        printIosChecklist(caps0);
+        process.exit(0);
+    }
+
+    console.log('');
+    console.log(paint(isDryRun ? 'Planned changes (--dry-run, nothing written)' : 'Changes', C.bold));
+    result.summary.forEach((sline, i) => console.log(`  ${i + 1}. ${sline}`));
+    if (result.manual.length) {
+        console.log('');
+        console.log(paint('Could not auto-apply (edit by hand)', C.bold + C.yellow));
+        result.manual.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+    }
+
+    if (isDryRun) {
+        console.log('');
+        console.log(paint('Dry run — no files written. Re-run without --dry-run to apply.', C.dim));
+        const caps1 = detectIosCapabilities(iosDir);
+        printIosChecklist(caps1);
+        process.exit(0);
+    }
+
+    // Apply. Never stage / commit — only edits the working-tree file.
+    fs.writeFileSync(found.path, result.source, 'utf8');
+    console.log('');
+    console.log(paint(`✓ Patched ${rel}`, C.green));
+    console.log(paint('  (working-tree edit only — nothing staged or committed)', C.dim));
+
+    const caps = detectIosCapabilities(iosDir);
+    printIosChecklist(caps);
+
+    console.log('');
+    console.log(paint('Next:', C.bold));
+    console.log('  cd ios && pod install');
+    console.log('  Then in app code:');
+    console.log(paint('    await ScaleBun.enablePush({ onForegroundNotification, onNotificationOpened });', C.dim));
+    console.log('');
+    process.exit(0);
+}
+
+// ─── `init android` — MainApplication OTA wiring + checklist ──────────────────
+
+function findAndroidDir() {
+    const androidDir = path.join(CWD, 'android');
+    return exists(androidDir) ? androidDir : null;
+}
+
+/** [major, minor] of the installed react-native, or null. */
+function rnMinor() {
+    const v = pkgVersion('react-native');
+    if (!v) return null;
+    const parts = v.split('.').map((n) => parseInt(n, 10));
+    return [parts[0] || 0, parts[1] || 0];
+}
+
+/**
+ * Detect Android setup that the codemod cannot apply — the checklist items
+ * (Firebase config, gradle plugin, manifest permissions, the New-Arch OTA
+ * version gate). Mirrors detectIosCapabilities.
+ */
+function detectAndroidCapabilities(androidDir) {
+    const rnVersion = pkgVersion('react-native');
+    const minor = rnMinor();
+
+    const gradleProps = readText(path.join(androidDir, 'gradle.properties')) || '';
+    const newArch = /(^|\n)\s*newArchEnabled\s*=\s*true/.test(gradleProps);
+
+    // Bridgeless ignored getJSBundleFile() until RN 0.76.1 — an OTA update installs
+    // and silently never runs on 0.74/0.75/0.76.0 with New Arch on.
+    const otaDeadZone =
+        newArch &&
+        minor != null &&
+        minor[0] === 0 &&
+        (minor[1] === 74 || minor[1] === 75 || (rnVersion || '').startsWith('0.76.0'));
+
+    const hasGoogleServicesJson = exists(path.join(androidDir, 'app', 'google-services.json'));
+
+    const manifestPath = path.join(androidDir, 'app', 'src', 'main', 'AndroidManifest.xml');
+    const manifest = readText(manifestPath) || '';
+    const hasPostNotifications = /android\.permission\.POST_NOTIFICATIONS/.test(manifest);
+    const hasChannelMeta = /default_notification_channel_id/.test(manifest);
+
+    return {
+        rnVersion,
+        newArch,
+        otaDeadZone,
+        hasGoogleServicesJson,
+        manifestExists: !!readText(manifestPath),
+        hasPostNotifications,
+        hasChannelMeta,
+    };
+}
+
+function printAndroidChecklist(caps) {
+    console.log('');
+    console.log(paint('Android setup (verify / apply by hand — cannot be safely automated)', C.bold));
+
+    if (caps.otaDeadZone) {
+        console.log(
+            '  ' + FAIL() + ' ' +
+                paint(
+                    `React Native ${caps.rnVersion} + New Architecture: OTA updates CANNOT LOAD.`,
+                    C.red,
+                ),
+        );
+        console.log(
+            paint(
+                '      Bridgeless ignored getJSBundleFile() until RN 0.76.1. Upgrade to >= 0.76.1,\n' +
+                    '      or set newArchEnabled=false. Until then updates install but never run.',
+                C.dim,
+            ),
+        );
+    }
+
+    line(caps.hasGoogleServicesJson ? OK() : WARN(), 'google-services.json', caps.hasGoogleServicesJson ? 'present' : null);
+    line(caps.hasPostNotifications ? OK() : WARN(), 'POST_NOTIFICATIONS perm', caps.hasPostNotifications ? 'declared' : null);
+    line(caps.hasChannelMeta ? OK() : WARN(), 'default channel meta', caps.hasChannelMeta ? 'declared' : null);
+
+    const todo = [];
+    if (!caps.hasGoogleServicesJson) {
+        todo.push(
+            'For push: add ' + paint('android/app/google-services.json', C.cyan) +
+                ' (Firebase console), apply the Google Services gradle plugin, and add ' +
+                paint('@react-native-firebase/messaging', C.cyan) + ' for real tokens.',
+        );
+    }
+    if (caps.manifestExists && !caps.hasPostNotifications) {
+        todo.push(
+            'Declare the Android 13+ permission in AndroidManifest.xml: ' +
+                paint('<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />', C.cyan),
+        );
+    }
+    if (caps.manifestExists && !caps.hasChannelMeta) {
+        todo.push(
+            'Declare a default FCM channel meta-data ' +
+                '(com.google.firebase.messaging.default_notification_channel_id) so backgrounded ' +
+                'notifications have a channel.',
+        );
+    }
+
+    if (todo.length) {
+        console.log('');
+        console.log(paint('Push follow-ups (skip if you only use OTA)', C.bold + C.yellow));
+        todo.forEach((t, i) => console.log(`  ${i + 1}. ${t}`));
+    }
+}
+
+function runInitAndroid(argv) {
+    const flags = new Set(argv);
+    const isCheck = flags.has('--check');
+    const isDryRun = flags.has('--dry-run');
+
+    const androidDir = findAndroidDir();
+    if (!androidDir) {
+        console.error(paint('✗ No android/ directory found.', C.red));
+        console.error('  Run this from a React Native project root (the folder containing android/).');
+        process.exit(2);
+    }
+
+    const found = androidCodemod.findMainApplication(androidDir, fs, path);
+    if (!found) {
+        console.error(paint('✗ Could not find MainApplication.kt or .java under android/app/src/main.', C.red));
+        console.error('  This project uses a non-standard layout — wire OTA bundle resolution manually.');
+        process.exit(2);
+    }
+
+    const minor = rnMinor();
+    const rel = path.relative(CWD, found.path);
+    console.log('');
+    console.log(paint('ScaleBun init android', C.bold + C.cyan));
+    console.log(`  MainApplication: ${paint(rel, C.cyan)} (${found.kind})`);
+
+    // Java: not auto-patched — print clear manual instructions, fail non-zero.
+    if (found.kind === 'java') {
+        console.log('');
+        console.log(androidCodemod.javaInstructions(minor));
+        printAndroidChecklist(detectAndroidCapabilities(androidDir));
+        process.exit(isCheck ? 1 : 2);
+    }
+
+    const original = readText(found.path) || '';
+
+    // --check: verify, never write.
+    if (isCheck) {
+        const a = androidCodemod.analyzeKotlin(original);
+        const wired = androidCodemod.isFullyWiredKotlin(original, minor);
+        console.log('');
+        console.log(paint('OTA wiring status', C.bold));
+        line(a.hasImport ? OK() : FAIL(), 'ScaleBunOtaModule import', a.hasImport ? 'present' : null);
+        line(a.hasBundleWiring ? OK() : FAIL(), 'getJSBundleFile wiring', a.hasBundleWiring ? 'present' : null);
+        if (androidCodemod.isReactHostEra(minor)) {
+            line(a.hasJsBundleFilePathArg ? OK() : FAIL(), 'jsBundleFilePath arg (RN >= 0.82)', a.hasJsBundleFilePathArg ? 'present' : null);
+        }
+        printAndroidChecklist(detectAndroidCapabilities(androidDir));
+        console.log('');
+        if (wired) {
+            console.log(paint('✓ MainApplication is wired for ScaleBun OTA bundle resolution.', C.green));
+            process.exit(0);
+        }
+        console.log(paint('✗ MainApplication is missing OTA bundle wiring. Run `npx scalebun init android`.', C.red));
+        process.exit(1);
+    }
+
+    const result = androidCodemod.patchKotlin(original, { minor });
+
+    if (!result.changed) {
+        console.log('');
+        if (result.manual.length) {
+            console.log(paint('Could not auto-apply — wire it by hand:', C.bold + C.yellow));
+            result.manual.forEach((m) => console.log(m));
+        } else {
+            console.log(paint('✓ Already wired — no changes needed (idempotent).', C.green));
+        }
+        printAndroidChecklist(detectAndroidCapabilities(androidDir));
+        process.exit(result.manual.length ? 1 : 0);
+    }
+
+    console.log('');
+    console.log(paint(isDryRun ? 'Planned changes (--dry-run, nothing written)' : 'Changes', C.bold));
+    result.summary.forEach((sline, i) => console.log(`  ${i + 1}. ${sline}`));
+    if (result.manual.length) {
+        console.log('');
+        console.log(paint('Could not auto-apply (edit by hand)', C.bold + C.yellow));
+        result.manual.forEach((m) => console.log(m));
+    }
+
+    if (isDryRun) {
+        console.log('');
+        console.log(paint('Dry run — no files written. Re-run without --dry-run to apply.', C.dim));
+        printAndroidChecklist(detectAndroidCapabilities(androidDir));
+        process.exit(0);
+    }
+
+    // Apply. Never stage / commit — only edits the working-tree file.
+    fs.writeFileSync(found.path, result.source, 'utf8');
+    console.log('');
+    console.log(paint(`✓ Patched ${rel}`, C.green));
+    console.log(paint('  (working-tree edit only — nothing staged or committed)', C.dim));
+
+    printAndroidChecklist(detectAndroidCapabilities(androidDir));
+
+    console.log('');
+    console.log(paint('Next:', C.bold));
+    console.log('  Rebuild the native app (a JS reload does not load the newly-wired native path):');
+    console.log(paint('    npx react-native run-android   # or your gradle build', C.dim));
+    console.log('');
+    process.exit(0);
+}
+
+// ─── entry ──────────────────────────────────────────────────────────────────
+
+function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    switch (cmd) {
+        case 'doctor':
+            runDoctor();
+            break;
+        case 'init': {
+            const target = argv[1];
+            if (target === 'ios') {
+                runInitIos(argv.slice(2));
+            } else if (target === 'android') {
+                runInitAndroid(argv.slice(2));
+            } else {
+                console.error(`Unknown init target: ${target ?? '(none)'}`);
+                console.error('Usage: npx scalebun init <ios|android> [--check | --dry-run]');
+                process.exit(2);
+            }
+            break;
+        }
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            printFullHelp();
+            break;
+        default:
+            // TWO PACKAGES, ONE COMMAND NAME.
+            //
+            // The OTA commands (login, ota publish, releases, rollout, quickstart…)
+            // live in @scalebun/cli, which declares the SAME `scalebun` bin as this
+            // package. Every doc and generated CI pipeline says `npx scalebun ota
+            // publish`, so whichever package won the bin race decided whether that
+            // worked — and when this one won, a new user's very first command died
+            // with "Unknown command: ota" and no way to find out why.
+            //
+            // Delegate instead of guessing: if @scalebun/cli is installed, run it.
+            // If not, say exactly what to install rather than what went wrong.
+            delegateToOtaCli(argv);
+    }
+}
+
+/** Resolve the bundled @scalebun/cli compiled entry, or null when absent. */
+function resolveOtaCli() {
+    try {
+        return require.resolve('@scalebun/cli/lib/index.js', {
+            paths: [process.cwd(), __dirname],
+        });
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Run the bundled CLI, showing a loader until it produces its first output.
+ *
+ * `npx scalebun <cmd>` pays npx + two Node startups + module loading (~0.5–1s)
+ * before anything appears — a blank terminal that reads as "hung". This spins a
+ * dependency-free loader in this (fast, dep-free) process while the CLI child
+ * boots, then clears it the instant the child writes.
+ *
+ * Only stdout is piped (so we can detect that first byte); stdin and stderr stay
+ * inherited, so masked token input and the delete/rollback confirmations — all of
+ * which key off `process.stdin.isTTY` — keep working. FORCE_COLOR keeps the
+ * child's colours despite the pipe. On a non-TTY (CI, pipes) we skip the loader
+ * and inherit everything, exactly as before.
+ */
+function runCli(cliEntry, args) {
+    const { spawn, spawnSync } = require('child_process');
+
+    if (!process.stdout.isTTY) {
+        const res = spawnSync(process.execPath, [cliEntry, ...args], { stdio: 'inherit' });
+        process.exit(res.status ?? 1);
+        return;
+    }
+
+    const env = { ...process.env };
+    if (!env.FORCE_COLOR) env.FORCE_COLOR = '1';
+
+    const child = spawn(process.execPath, [cliEntry, ...args], {
+        stdio: ['inherit', 'pipe', 'inherit'],
+        env,
+    });
+
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const label = ' Starting ScaleBun…';
+    let i = 0;
+    let spinning = true;
+    process.stdout.write('\x1b[?25l'); // hide cursor
+    const timer = setInterval(() => {
+        i = (i + 1) % frames.length;
+        process.stdout.write(`\r${paint(frames[i], C.cyan)}${label}`);
+    }, 80);
+    const stopSpinner = () => {
+        if (!spinning) return;
+        spinning = false;
+        clearInterval(timer);
+        // Erase the spinner line and restore the cursor.
+        process.stdout.write('\r' + ' '.repeat(label.length + 2) + '\r\x1b[?25h');
+    };
+
+    child.stdout.on('data', (chunk) => {
+        stopSpinner();
+        process.stdout.write(chunk);
+    });
+    child.on('error', () => {
+        stopSpinner();
+        process.exit(1);
+    });
+    child.on('exit', (code) => {
+        stopSpinner();
+        process.exit(code ?? 0);
+    });
+    // Defensive: never leave the terminal cursor hidden.
+    process.on('SIGINT', stopSpinner);
+    process.on('exit', () => {
+        if (spinning) process.stdout.write('\x1b[?25h');
+    });
+}
+
+/**
+ * Hand the invocation to @scalebun/cli, preserving argv and exit code.
+ * Falls back to an actionable install instruction when it is not present.
+ */
+function delegateToOtaCli(argv) {
+    const cliEntry = resolveOtaCli();
+
+    if (!cliEntry) {
+        const cmd = argv[0];
+        console.error('');
+        console.error(`"${cmd}" is an OTA command, provided by @scalebun/cli.`);
+        console.error('');
+        console.error('@scalebun/cli ships as a dependency of @scalebun/react-native, so it');
+        console.error('should already be present. It could not be resolved — your install may');
+        console.error('be incomplete or the dependency was pruned.');
+        console.error('');
+        console.error('Reinstall dependencies, then re-run:');
+        console.error('  npm install');
+        console.error(`  npx scalebun ${argv.join(' ')}`);
+        console.error('');
+        console.error('(Or install it explicitly:  npm i -D @scalebun/cli)');
+        console.error('');
+        process.exit(2);
+    }
+
+    runCli(cliEntry, argv);
+}
+
+/**
+ * Print the full, guided command surface.
+ *
+ * Delegates to the bundled @scalebun/cli's own banner (invoked with no args),
+ * which renders the "publish your first OTA update" getting-started flow,
+ * project setup (doctor + init ios/android), and every OTA subcommand — a single
+ * source of truth that cannot drift. `--help` on the CLI would only list
+ * top-level groups (so `ota generate-key-pair` etc. would stay hidden), which is
+ * exactly the discoverability gap this avoids. When the CLI cannot be resolved
+ * (should not happen — it is a dependency) we fall back to a static list.
+ */
+function printFullHelp() {
+    const cliEntry = resolveOtaCli();
+    if (cliEntry) {
+        // No args → the CLI prints its banner + status + full guided command list.
+        runCli(cliEntry, []);
+        return;
+    }
+
+    // Fallback: CLI unresolvable — show at least the setup commands + how to fix.
+    console.log('');
+    console.log(paint('ScaleBun CLI', C.bold));
+    console.log('');
+    console.log(paint('Publish your first OTA update:', C.bold));
+    console.log('  1. npx scalebun login                     Authenticate (paste a token)');
+    console.log('  2. npx scalebun apps                      Find your --app-id');
+    console.log('  3. npx scalebun init android | init ios   Wire the native app for OTA, then rebuild');
+    console.log('  4. npx scalebun ota publish --app-id <id> --hermes');
+    console.log('');
+    console.log(paint('Project setup:', C.bold));
+    console.log('  npx scalebun doctor                  Check the project is OTA-ready');
+    console.log('  npx scalebun init ios                Wire the iOS AppDelegate for OTA + Direct APNs');
+    console.log('  npx scalebun init android            Wire the Android MainApplication for OTA');
+    console.log(paint('    add --check to verify (exit 1 if missing) or --dry-run to preview', C.dim));
+    console.log('');
+    console.log(paint('The OTA & account commands come from @scalebun/cli, which ships with this', C.dim));
+    console.log(paint('package but could not be resolved — run `npm install`, then retry.', C.dim));
+    console.log('');
+}
+
+main();