@scalebun/react-native 1.5.0 → 1.6.1

package/README.md

@@ -18,6 +18,39 @@ yarn add @scalebun/react-native
 cd ios && pod install
 ```
 
+To wire the AppDelegate for Direct APNs push (optional):
+
+```sh
+npx scalebun init ios            # patch the AppDelegate (ObjC auto-patched; Swift prints steps)
+npx scalebun init ios --check    # verify hooks exist (exit 1 if missing)
+```
+
+### Android
+
+OTA updates need one wiring step in `MainApplication` so a downloaded bundle
+actually loads — without it an update installs, reports success, and the app
+silently keeps running the bundle baked into the APK. Run:
+
+```sh
+npx scalebun init android            # wire MainApplication for OTA bundle loading
+npx scalebun init android --check    # verify (exit 1 if missing)
+npx scalebun init android --dry-run  # preview changes without writing
+```
+
+This adds `ScaleBunOtaModule.getJSBundleFile(...)` in the form matching your
+React Native version (Kotlin is auto-patched; Java prints manual instructions).
+**Rebuild the native app afterwards** — a JS reload does not load the newly
+wired native path.
+
+For push on Android (optional): add `android/app/google-services.json`, apply
+the Google Services Gradle plugin with `@react-native-firebase/messaging`, and
+declare the `POST_NOTIFICATIONS` permission. Run `npx scalebun doctor` to see
+exactly what's missing.
+
+> Run `npx scalebun -h` to list every command — SDK setup (`doctor`, `init ios`,
+> `init android`) plus the OTA publishing commands (`login`, `ota publish`,
+> `rollout`, …).
+
 ### Optional peer dependencies
 
 Some features activate only when their peer package is installed:

package/bin/lib/androidCodemod.js

@@ -0,0 +1,370 @@
+'use strict';
+/**
+ * Android MainApplication codemod for `npx scalebun init android`.
+ *
+ * Pure, dependency-free string transforms (no fs / process / RN imports) so they
+ * are unit-testable with plain fixtures and safe to run anywhere. The CLI
+ * (bin/scalebun.js) handles disk IO, flags, and reporting; this module only
+ * decides WHAT the patched source should be.
+ *
+ * It wires OTA bundle resolution into the host app's MainApplication so a
+ * downloaded update actually LOADS instead of the app silently running the
+ * bundle baked into the APK. The required call is the static
+ * `ScaleBunOtaModule.getJSBundleFile(context)`, wired in one of two shapes
+ * depending on the React Native version:
+ *
+ *   - RN < 0.82 (ReactNativeHost still exists): add
+ *       override fun getJSBundleFile(): String? =
+ *         ScaleBunOtaModule.getJSBundleFile(this@MainApplication) ?: super.getJSBundleFile()
+ *     inside the `object : *ReactNativeHost { … }` block.
+ *
+ *   - RN >= 0.82 (ReactNativeHost removed): pass the path to getDefaultReactHost:
+ *       getDefaultReactHost(
+ *         …,
+ *         jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(applicationContext),
+ *       )
+ *
+ * The version decides the shape — mirroring the check in
+ * @scalebun/cli src/commands/doctor.ts. Every transform is idempotent (running
+ * twice is a no-op). Java MainApplication and unrecognized structures are NOT
+ * auto-patched — they return an exact manual snippet instead of a risky edit.
+ */
+
+const OTA_IMPORT = 'import com.scalebun.rn.ota.ScaleBunOtaModule';
+const BUNDLE_CALL = 'ScaleBunOtaModule.getJSBundleFile';
+const MANAGED_TAG = 'ScaleBun OTA bundle resolution';
+
+// ── MainApplication discovery ────────────────────────────────────────────────
+
+/**
+ * Find the host MainApplication under <androidDir>. Returns { path, kind } where
+ * kind is 'kotlin' (.kt) or 'java' (.java), or null when none is found. Kotlin
+ * is preferred. `fsLike`/`pathLike` are injected for testability.
+ */
+function findMainApplication(androidDir, fsLike, pathLike) {
+    const fs = fsLike;
+    const path = pathLike;
+    const root = path.join(androidDir, 'app', 'src', 'main');
+
+    // Walk src/main/{java,kotlin}/** for MainApplication.kt/.java.
+    const found = { kotlin: null, java: null };
+    const walk = (dir) => {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(p);
+            } else if (entry.name === 'MainApplication.kt' && !found.kotlin) {
+                found.kotlin = p;
+            } else if (entry.name === 'MainApplication.java' && !found.java) {
+                found.java = p;
+            }
+        }
+    };
+    walk(root);
+
+    if (found.kotlin) return { path: found.kotlin, kind: 'kotlin' };
+    if (found.java) return { path: found.java, kind: 'java' };
+    return null;
+}
+
+// ── version helper ────────────────────────────────────────────────────────────
+
+/**
+ * True when RN >= 0.82 (ReactNativeHost removed → must pass jsBundleFilePath to
+ * getDefaultReactHost). `minor` is [major, minor] or null when unknown; when
+ * unknown we assume the modern shape.
+ */
+function isReactHostEra(minor) {
+    if (!minor) return true;
+    return minor[0] > 0 || minor[1] >= 82;
+}
+
+// ── analysis ────────────────────────────────────────────────────────────────
+
+/** Report which OTA wiring pieces are already present in a Kotlin MainApplication. */
+function analyzeKotlin(source) {
+    const s = String(source);
+    return {
+        hasImport: s.includes(OTA_IMPORT),
+        hasBundleWiring: s.includes(BUNDLE_CALL),
+        hasReactNativeHostObject: /object\s*:\s*\w*ReactNativeHost\s*\(/.test(s),
+        hasGetDefaultReactHost: s.includes('getDefaultReactHost('),
+        hasJsBundleFilePathArg: s.includes('jsBundleFilePath'),
+    };
+}
+
+/**
+ * True when OTA bundle resolution is fully wired for this RN version (for
+ * --check). On RN >= 0.82 the wiring must go through the jsBundleFilePath arg;
+ * before that any getJSBundleFile call is enough.
+ */
+function isFullyWiredKotlin(source, minor) {
+    const a = analyzeKotlin(source);
+    if (!a.hasImport || !a.hasBundleWiring) return false;
+    if (isReactHostEra(minor)) return a.hasJsBundleFilePathArg;
+    return true;
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+/** Insert `lineToAdd` immediately after the last top-of-file Kotlin import. */
+function insertAfterLastImport(source, lineToAdd) {
+    const lines = source.split('\n');
+    let lastImport = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*import\b/.test(lines[i])) lastImport = i;
+        // Stop scanning once the class/object declaration begins.
+        if (/^\s*(class|object)\b/.test(lines[i])) break;
+    }
+    if (lastImport === -1) {
+        // No imports — put it after the package line, else prepend.
+        for (let i = 0; i < lines.length; i++) {
+            if (/^\s*package\b/.test(lines[i])) {
+                lines.splice(i + 1, 0, '', lineToAdd);
+                return lines.join('\n');
+            }
+        }
+        return lineToAdd + '\n' + source;
+    }
+    lines.splice(lastImport + 1, 0, lineToAdd);
+    return lines.join('\n');
+}
+
+/** Leading whitespace of the first non-empty line at/after `fromIdx`. */
+function bodyIndentAfter(source, fromIdx) {
+    const rest = source.slice(fromIdx).split('\n');
+    for (const line of rest) {
+        if (line.trim() === '') continue;
+        return (line.match(/^\s*/) || [''])[0];
+    }
+    return '        ';
+}
+
+/**
+ * Insert the getJSBundleFile() override into the `object : *ReactNativeHost(…) {`
+ * block (RN < 0.82). Returns { source, inserted, reason }.
+ */
+function insertIntoReactNativeHostObject(source, methodText) {
+    const objRe = /object\s*:\s*\w*ReactNativeHost\s*\([^)]*\)\s*\{/;
+    const m = objRe.exec(source);
+    if (!m) return { source, inserted: false, reason: 'no-object' };
+    const insertAt = m.index + m[0].length; // right after the opening `{`
+    const indent = bodyIndentAfter(source, insertAt);
+    const block = '\n' + methodText(indent);
+    return {
+        source: source.slice(0, insertAt) + block + source.slice(insertAt),
+        inserted: true,
+    };
+}
+
+/**
+ * Insert a named argument into a call, respecting single-line vs multi-line
+ * Kotlin argument style. Returns { source, inserted, reason }.
+ */
+function insertArgIntoCall(source, callName, argText) {
+    const callIdx = source.indexOf(callName + '(');
+    if (callIdx === -1) return { source, inserted: false, reason: 'no-call' };
+    const openIdx = source.indexOf('(', callIdx);
+
+    // Find the matching close paren (calls contain nested parens like
+    // PackageList(this).packages, so a naive indexOf(')') is wrong).
+    let depth = 0;
+    let closeIdx = -1;
+    for (let i = openIdx; i < source.length; i++) {
+        const c = source[i];
+        if (c === '(') depth++;
+        else if (c === ')') {
+            depth--;
+            if (depth === 0) {
+                closeIdx = i;
+                break;
+            }
+        }
+    }
+    if (closeIdx === -1) return { source, inserted: false, reason: 'no-close' };
+
+    const inner = source.slice(openIdx + 1, closeIdx);
+    const isMultiline = inner.includes('\n');
+
+    // Last meaningful (non-whitespace) char before the close paren.
+    let j = closeIdx - 1;
+    while (j > openIdx && /\s/.test(source[j])) j--;
+    const lastChar = source[j];
+
+    let insertText;
+    if (inner.trim() === '') {
+        insertText = argText;
+    } else if (isMultiline) {
+        // Align the new argument with the last existing argument line (the line
+        // where `j` sits) so the call reads consistently, not with the closing
+        // paren's indentation.
+        const argLineStart = source.lastIndexOf('\n', j) + 1;
+        const argIndent = (source.slice(argLineStart, j).match(/^\s*/) || [''])[0];
+        insertText =
+            lastChar === ','
+                ? `\n${argIndent}${argText},`
+                : `,\n${argIndent}${argText}`;
+    } else {
+        insertText = lastChar === ',' ? ` ${argText},` : `, ${argText}`;
+    }
+
+    return {
+        source: source.slice(0, j + 1) + insertText + source.slice(j + 1),
+        inserted: true,
+    };
+}
+
+// ── the patch ─────────────────────────────────────────────────────────────────
+
+/**
+ * Patch a Kotlin MainApplication for OTA bundle resolution. `opts.minor` is the
+ * [major, minor] React Native version (or null). Returns:
+ *   { changed, source, summary[], manual[] }
+ */
+function patchKotlin(source, opts = {}) {
+    let out = String(source);
+    const summary = [];
+    const manual = [];
+    const a = analyzeKotlin(out);
+    const reactHostEra = isReactHostEra(opts.minor);
+
+    // Already fully wired for this era → no-op.
+    if (isFullyWiredKotlin(out, opts.minor)) {
+        return { changed: false, source: out, summary, manual };
+    }
+
+    if (reactHostEra) {
+        // RN >= 0.82: pass jsBundleFilePath to getDefaultReactHost(...).
+        if (!a.hasGetDefaultReactHost) {
+            manual.push(reactHostManual());
+            return { changed: false, source: out, summary, manual };
+        }
+        if (!a.hasImport) {
+            out = insertAfterLastImport(out, OTA_IMPORT);
+            summary.push(`Added import: ${OTA_IMPORT}`);
+        }
+        if (!a.hasJsBundleFilePathArg) {
+            const r = insertArgIntoCall(
+                out,
+                'getDefaultReactHost',
+                'jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(applicationContext)',
+            );
+            if (r.inserted) {
+                out = r.source;
+                summary.push(
+                    'Patched getDefaultReactHost(...) → added jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(applicationContext)',
+                );
+            } else {
+                manual.push(reactHostManual());
+            }
+        }
+    } else {
+        // RN < 0.82: add getJSBundleFile() override inside the ReactNativeHost object.
+        if (!a.hasReactNativeHostObject) {
+            manual.push(legacyManual());
+            return { changed: false, source: out, summary, manual };
+        }
+        if (!a.hasImport) {
+            out = insertAfterLastImport(out, OTA_IMPORT);
+            summary.push(`Added import: ${OTA_IMPORT}`);
+        }
+        if (!a.hasBundleWiring) {
+            const r = insertIntoReactNativeHostObject(
+                out,
+                (indent) =>
+                    `${indent}// ${MANAGED_TAG} (added by \`npx scalebun init android\`)\n` +
+                    `${indent}override fun getJSBundleFile(): String? =\n` +
+                    `${indent}    ScaleBunOtaModule.getJSBundleFile(this@MainApplication) ?: super.getJSBundleFile()\n`,
+            );
+            if (r.inserted) {
+                out = r.source;
+                summary.push(
+                    'Added getJSBundleFile() override → ScaleBunOtaModule.getJSBundleFile(this@MainApplication)',
+                );
+            } else {
+                manual.push(legacyManual());
+            }
+        }
+    }
+
+    return { changed: out !== String(source), source: out, summary, manual };
+}
+
+// ── manual instructions ─────────────────────────────────────────────────────
+
+/** Manual snippet for RN >= 0.82 when the getDefaultReactHost call can't be found. */
+function reactHostManual() {
+    return [
+        'Could not locate getDefaultReactHost(...) in MainApplication. Wire OTA bundle',
+        'resolution manually (RN >= 0.82):',
+        '',
+        `  ${OTA_IMPORT}`,
+        '',
+        '  override val reactHost: ReactHost by lazy {',
+        '    getDefaultReactHost(',
+        '      context = applicationContext,',
+        '      packageList = PackageList(this).packages,',
+        '      jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(applicationContext),',
+        '    )',
+        '  }',
+    ].join('\n');
+}
+
+/** Manual snippet for RN < 0.82 when the ReactNativeHost object can't be found. */
+function legacyManual() {
+    return [
+        'Could not locate the ReactNativeHost object in MainApplication. Add the OTA',
+        'bundle-resolution override manually (RN < 0.82), inside your ReactNativeHost:',
+        '',
+        `  ${OTA_IMPORT}`,
+        '',
+        '  override fun getJSBundleFile(): String? =',
+        '    ScaleBunOtaModule.getJSBundleFile(this@MainApplication) ?: super.getJSBundleFile()',
+    ].join('\n');
+}
+
+/** Manual instructions for a Java MainApplication (auto-patch not supported). */
+function javaInstructions(minor) {
+    if (isReactHostEra(minor)) {
+        return [
+            'A Java MainApplication was detected. Automatic patching of Java is not',
+            'supported — wire OTA bundle resolution manually (RN >= 0.82):',
+            '',
+            '  import com.scalebun.rn.ota.ScaleBunOtaModule;',
+            '',
+            '  // where you build the ReactHost via DefaultReactHost.getDefaultReactHost(...),',
+            '  // pass the OTA bundle path:',
+            '  ScaleBunOtaModule.getJSBundleFile(getApplicationContext())',
+        ].join('\n');
+    }
+    return [
+        'A Java MainApplication was detected. Automatic patching of Java is not',
+        'supported — add this override inside your ReactNativeHost (RN < 0.82):',
+        '',
+        '  import com.scalebun.rn.ota.ScaleBunOtaModule;',
+        '',
+        '  @Override',
+        '  protected String getJSBundleFile() {',
+        '    String ota = ScaleBunOtaModule.getJSBundleFile(getApplicationContext());',
+        '    return ota != null ? ota : super.getJSBundleFile();',
+        '  }',
+    ].join('\n');
+}
+
+module.exports = {
+    OTA_IMPORT,
+    BUNDLE_CALL,
+    MANAGED_TAG,
+    findMainApplication,
+    isReactHostEra,
+    analyzeKotlin,
+    isFullyWiredKotlin,
+    patchKotlin,
+    javaInstructions,
+};

package/bin/scalebun.js

@@ -22,6 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const codemod = require('./lib/iosCodemod');
+const androidCodemod = require('./lib/androidCodemod');
 
 const MIN_BRIDGELESS_RNFIREBASE_MAJOR = 18;
 
@@ -597,6 +598,215 @@ function runInitIos(argv) {
     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() {
@@ -610,9 +820,11 @@ function main() {
             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 [--check | --dry-run]');
+                console.error('Usage: npx scalebun init <ios|android> [--check | --dry-run]');
                 process.exit(2);
             }
             break;
@@ -621,19 +833,7 @@ function main() {
         case 'help':
         case '--help':
         case '-h':
-            console.log('');
-            console.log(paint('ScaleBun SDK CLI', C.bold));
-            console.log('');
-            console.log('Usage:');
-            console.log('  npx scalebun doctor              Diagnose push-notification setup');
-            console.log('  npx scalebun init ios            Wire the iOS AppDelegate for Direct APNs');
-            console.log('  npx scalebun init ios --check    Verify hooks exist (exit 1 if missing)');
-            console.log('  npx scalebun init ios --dry-run  Preview changes without writing');
-            console.log('');
-            console.log('OTA commands (login, quickstart, ota publish, releases, rollout…)');
-            console.log('ship with this package (via the bundled @scalebun/cli) and are');
-            console.log('forwarded automatically — no extra install needed.');
-            console.log('');
+            printFullHelp();
             break;
         default:
             // TWO PACKAGES, ONE COMMAND NAME.
@@ -651,19 +851,23 @@ function main() {
     }
 }
 
-/**
- * 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) {
-    let cliEntry = null;
+/** Resolve the bundled @scalebun/cli compiled entry, or null when absent. */
+function resolveOtaCli() {
     try {
-        cliEntry = require.resolve('@scalebun/cli/lib/index.js', {
+        return require.resolve('@scalebun/cli/lib/index.js', {
             paths: [process.cwd(), __dirname],
         });
     } catch {
-        cliEntry = null;
+        return null;
     }
+}
+
+/**
+ * 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];
@@ -690,4 +894,40 @@ function delegateToOtaCli(argv) {
     process.exit(res.status ?? 1);
 }
 
+/**
+ * Print the full command surface: the SDK-setup commands this package handles
+ * directly, followed by the complete @scalebun/cli command tree.
+ *
+ * The CLI tree is rendered by delegating to `@scalebun/cli --help` rather than a
+ * hardcoded list, so it is a single source of truth and cannot drift. When the
+ * CLI cannot be resolved (should not happen — it is a dependency) we fall back to
+ * a prose note instead of an error, since this is a help screen.
+ */
+function printFullHelp() {
+    console.log('');
+    console.log(paint('ScaleBun SDK CLI', C.bold));
+    console.log('');
+    console.log(paint('SDK setup (bundled with @scalebun/react-native):', C.bold));
+    console.log('  npx scalebun doctor                  Diagnose push-notification setup');
+    console.log('  npx scalebun init ios                Wire the iOS AppDelegate for Direct APNs');
+    console.log('  npx scalebun init android            Wire Android MainApplication for OTA bundle loading');
+    console.log(paint('    add --check to verify (exit 1 if missing) or --dry-run to preview', C.dim));
+    console.log('');
+
+    const cliEntry = resolveOtaCli();
+    if (!cliEntry) {
+        console.log(paint('OTA & account commands:', C.bold));
+        console.log('  Provided by @scalebun/cli (login, quickstart, apps, ota publish,');
+        console.log('  releases, rollout…). It ships with this package but could not be');
+        console.log('  resolved — run `npm install`, then `npx scalebun --help` again.');
+        console.log('');
+        return;
+    }
+
+    console.log(paint('OTA & account commands (from @scalebun/cli):', C.bold));
+    const { spawnSync } = require('child_process');
+    spawnSync(process.execPath, [cliEntry, '--help'], { stdio: 'inherit' });
+    console.log('');
+}
+
 main();

package/dist/scalebun.full.js

@@ -489,7 +489,7 @@ var SDK_VERSION;
 var init_version = __esm({
   "lib/module/core/constants/version.js"() {
     "use strict";
-    SDK_VERSION = "1.5.0";
+    SDK_VERSION = "1.6.1";
   }
 });
 

package/dist/scalebun.slim.js

@@ -492,7 +492,7 @@ var SDK_VERSION;
 var init_version = __esm({
   "lib/module/core/constants/version.js"() {
     "use strict";
-    SDK_VERSION = "1.5.0";
+    SDK_VERSION = "1.6.1";
   }
 });
 

package/lib/commonjs/core/constants/version.js

@@ -9,5 +9,5 @@ exports.SDK_VERSION = void 0;
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-const SDK_VERSION = exports.SDK_VERSION = '1.5.0';
+const SDK_VERSION = exports.SDK_VERSION = '1.6.1';
 //# sourceMappingURL=version.js.map

package/lib/module/core/constants/version.js

@@ -3,5 +3,5 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export const SDK_VERSION = '1.5.0';
+export const SDK_VERSION = '1.6.1';
 //# sourceMappingURL=version.js.map

package/lib/typescript/core/constants/version.d.ts

@@ -3,5 +3,5 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export declare const SDK_VERSION = "1.5.0";
+export declare const SDK_VERSION = "1.6.1";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Production-grade React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -105,7 +105,7 @@
     "@babel/runtime": "^7.25.0",
     "@jridgewell/sourcemap-codec": "1.5.5",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@scalebun/cli": "^1.4.0"
+    "@scalebun/cli": "^1.6.1"
   },
   "codegenConfig": {
     "name": "ScaleBunSpec",

package/src/core/constants/version.ts

@@ -3,4 +3,4 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export const SDK_VERSION = '1.5.0';
+export const SDK_VERSION = '1.6.1';