@callstack/react-native-brownfield 5.2.0 → 6.0.0

package/src/expo-config-plugin/ios/xcodeHelpers.ts

@@ -11,6 +11,43 @@ import type { ResolvedBrownfieldPluginIosConfig } from '../types';
 import { SourceModificationError } from '../errors/SourceModificationError';
 import { getFrameworkSourceFiles } from './withIosFrameworkFiles';
 
+/**
+ * xcode@3.x addTarget() stores target names/comments quoted (e.g. name =
+ * "BrownfieldLib"), and the pbxproj parser keeps the quote characters on
+ * re-parse. That makes pbxTargetByName() (comment-based, unquoted) miss
+ * targets we previously wrote, so a second run would create a duplicate
+ * target. Match by unquoting the stored name as a fallback.
+ */
+function findFrameworkTargetByQuotedName(
+  project: XcodeProject,
+  frameworkName: string
+): ReturnType<XcodeProject['pbxTargetByName']> {
+  const nativeTargets = getRawProjectObjects(project).PBXNativeTarget as
+    | Record<string, PbxNativeTarget & { isa?: string }>
+    | undefined;
+
+  for (const [key, target] of Object.entries(nativeTargets ?? {})) {
+    if (key.endsWith('_comment') || target?.isa !== 'PBXNativeTarget') {
+      continue;
+    }
+    const name = unquotePbxString(target.name);
+    if (name === frameworkName) {
+      return target as any;
+    }
+  }
+
+  return null;
+}
+
+function unquotePbxString(value: string | undefined): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  return value.startsWith('"') && value.endsWith('"')
+    ? value.slice(1, -1)
+    : value;
+}
+
 /**
  * Adds a new Framework target to the Xcode project for Brownfield packaging
  * @throws If target creation fails
@@ -20,7 +57,10 @@ import { getFrameworkSourceFiles } from './withIosFrameworkFiles';
 export function addFrameworkTarget(
   project: XcodeProject,
   modRequest: ModProps<XcodeProject>,
-  options: ResolvedBrownfieldPluginIosConfig
+  options: ResolvedBrownfieldPluginIosConfig,
+  brownfieldOptions?: {
+    useExpoHost?: boolean;
+  }
 ): {
   frameworkTargetUUID: string;
   targetAlreadyExists: boolean;
@@ -28,7 +68,9 @@ export function addFrameworkTarget(
   const { frameworkName, bundleIdentifier } = options;
 
   // check if target already exists
-  const existingTarget = project.pbxTargetByName(frameworkName);
+  const existingTarget =
+    project.pbxTargetByName(frameworkName) ??
+    findFrameworkTargetByQuotedName(project, frameworkName);
   if (existingTarget) {
     Logger.logDebug(
       `Framework target "${frameworkName}" already exists, skipping creation`
@@ -131,7 +173,7 @@ export function addFrameworkTarget(
   });
 
   // create the framework group in the project
-  const filePaths = getFrameworkSourceFiles(options).map(
+  const filePaths = getFrameworkSourceFiles(options, brownfieldOptions).map(
     (file) => file.relativePath
   );
   const groupPath = path.join(modRequest.platformProjectRoot, frameworkName);
@@ -161,9 +203,12 @@ export function addFrameworkTarget(
 export function addSourceFilesBuildPhase(
   project: XcodeProject,
   frameworkTargetUUID: string,
-  options: ResolvedBrownfieldPluginIosConfig
+  options: ResolvedBrownfieldPluginIosConfig,
+  brownfieldOptions?: {
+    useExpoHost?: boolean;
+  }
 ) {
-  const filePaths = getFrameworkSourceFiles(options).map(
+  const filePaths = getFrameworkSourceFiles(options, brownfieldOptions).map(
     (file) => file.relativePath
   );
 
@@ -171,6 +216,26 @@ export function addSourceFilesBuildPhase(
     (filePath) => !filePath.endsWith('.plist')
   );
 
+  // Idempotency: skip when the target already has a sources phase with this
+  // comment, so re-running scaffolding does not duplicate the build phase.
+  const nativeTargets = getRawProjectObjects(project).PBXNativeTarget as
+    | Record<string, PbxNativeTarget>
+    | undefined;
+  const targetBuildPhases =
+    nativeTargets?.[frameworkTargetUUID]?.buildPhases ?? [];
+  const alreadyHasSourcePhase = targetBuildPhases.some((phase) =>
+    hasBuildPhaseComment(
+      { comment: typeof phase === 'string' ? undefined : phase.comment },
+      options.frameworkName
+    )
+  );
+  if (alreadyHasSourcePhase) {
+    Logger.logDebug(
+      `Sources build phase "${options.frameworkName}" already present on target ${frameworkTargetUUID}, skipping`
+    );
+    return;
+  }
+
   project.addBuildPhase(
     sourceFiles,
     'PBXSourcesBuildPhase',
@@ -613,6 +678,13 @@ export function copyBundleReactNativePhase(
         }
       );
 
+      // xcode's pbxShellScriptBuildPhaseObj only escapes quotes, leaving real
+      // newlines in the shellScript value — that produces an invalid pbxproj
+      // once the project is written. Encode both fields the same way the
+      // update path above does.
+      addedPhase.buildPhase.shellPath = encodePbxString(frameworkShellPath);
+      addedPhase.buildPhase.shellScript = encodePbxString(frameworkShellScript);
+
       if (existingPhase.showEnvVarsInLog !== undefined) {
         addedPhase.buildPhase.showEnvVarsInLog = existingPhase.showEnvVarsInLog;
       }

package/src/expo-config-plugin/template/android/ReactNativeHostManager.vanilla.kt

@@ -0,0 +1,35 @@
+package {{PACKAGE_NAME}}
+
+import android.app.Application
+import android.content.res.Configuration
+import com.callstack.reactnativebrownfield.OnJSBundleLoaded
+import com.callstack.reactnativebrownfield.ReactNativeBrownfield
+import com.facebook.react.PackageList
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
+import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
+
+object ReactNativeHostManager {
+    fun initialize(application: Application, onJSBundleLoaded: OnJSBundleLoaded? = null) {
+        loadReactNative(application)
+
+        val reactHost: ReactHost by lazy {
+            getDefaultReactHost(
+                context = application,
+                packageList = PackageList(application).packages,
+                jsMainModulePath = "index",
+                jsBundleAssetPath = "index.android.bundle",
+                jsBundleFilePath = null,
+                useDevSupport = BuildConfig.DEBUG,
+                jsRuntimeFactory = null
+            )
+        }
+
+        ReactNativeBrownfield.initialize(application, reactHost, onJSBundleLoaded)
+    }
+
+    fun onConfigurationChanged(application: Application, newConfig: Configuration) {
+        // no-op (kept for API symmetry with Expo variant)
+    }
+}
+

package/src/expo-config-plugin/template/android/consumer-rules.pro

@@ -0,0 +1,7 @@
+-keep interface com.callstack.reactnativebrownfield.OnJSBundleLoaded { *; }
+-keep interface com.callstack.reactnativebrownfield.OnDisplayMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.JSBundleTimings { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldDisplayMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldDisplayInterval { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldThreadMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldPerformanceModule { *; }

package/src/expo-config-plugin/template/ios/FrameworkInterface.vanilla.swift

@@ -0,0 +1,12 @@
+import Foundation
+
+// Re-export the Brownfield runtime so the native host app resolves
+// ReactNativeBrownfield.shared by importing only this framework, matching the
+// manual guide's interface file (docs getting-started/ios.mdx).
+@_exported import ReactBrownfield
+
+// Initializes a Bundle instance that points at the framework target.
+public let ReactNativeBundle = Bundle(for: InternalClassForBundle.self)
+
+class InternalClassForBundle {}
+

package/src/expo-config-plugin/template/ios/PodfileTargetBlock.vanilla.rb

@@ -0,0 +1,5 @@
+  # Brownfield framework target for packaging as XCFramework
+  target '{{FRAMEWORK_NAME}}' do
+    inherit! :complete
+  end
+

package/src/index.ts

@@ -1,7 +1,14 @@
-import { Platform } from 'react-native';
+import { NativeModules, Platform } from 'react-native';
 
 import ReactNativeBrownfieldModule from './NativeReactNativeBrownfieldModule';
 
+// NOTE: the scaffold API is intentionally NOT re-exported here. This module is
+// the package's `react-native`/`source` entry point, so anything reachable from
+// it is traversed by Metro when an app imports the package. The scaffold pulls
+// in node:fs, node:path, xcode and the Community CLI, which cannot bundle.
+// Node-side consumers import it from the dedicated subpath instead:
+// `@callstack/react-native-brownfield/scaffold`.
+
 export type { BrownfieldConfig } from '@callstack/brownfield-cli/types';
 
 export interface MessageEvent {
@@ -9,6 +16,18 @@ export interface MessageEvent {
 }
 
 const ReactNativeBrownfield = {
+  /**
+   * Finish this presentation's full-display measurement after data and UI are ready.
+   * Pass the `brownfieldPresentationID` injected into the root component's props.
+   * Native must opt in with `waitForFullDisplay: true`. Repeated/stale IDs are ignored.
+   * @platform android, ios
+   */
+  markFullyDisplayed: (presentationID: string): void => {
+    if (Platform.OS === 'ios' || Platform.OS === 'android') {
+      NativeModules.BrownfieldPerformance.markFullyDisplayed(presentationID);
+    }
+  },
+
   /**
    * Pop to the native screen.
    * @param animated - Whether to animate the transition (iOS only).

package/src/scaffold/index.ts

@@ -0,0 +1,395 @@
+// Emitted as a triple-slash reference into the generated scaffold .d.ts, so
+// consumers (e.g. @callstack/create-react-native-brownfield) resolve the untyped `xcode`
+// import through this single declaration instead of duplicating xcode.d.ts.
+/// <reference path="./xcode.d.ts" />
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import type { ModProps, XcodeProject } from '@expo/config-plugins';
+import type { UserConfig } from '@react-native-community/cli-types';
+import cliConfigImport from '@react-native-community/cli-config';
+import xcode from 'xcode';
+
+import { Logger } from '../expo-config-plugin/logging';
+import type {
+  ResolvedBrownfieldPluginConfigWithAndroid,
+  ResolvedBrownfieldPluginConfigWithIos,
+} from '../expo-config-plugin/types';
+import {
+  modifyRootBuildGradle,
+  modifySettingsGradle,
+} from '../expo-config-plugin/android/utils/gradleHelpers';
+import { createAndroidModule } from '../expo-config-plugin/android/withAndroidModuleFiles';
+import { modifyPodfile } from '../expo-config-plugin/ios/podfileHelpers';
+import {
+  addFrameworkTarget,
+  addSourceFilesBuildPhase,
+  copyBundleReactNativePhase,
+} from '../expo-config-plugin/ios/xcodeHelpers';
+import { createIosFramework } from '../expo-config-plugin/ios/withIosFrameworkFiles';
+import {
+  addBrownfieldDependencies,
+  addBrownfieldPackageScripts,
+  writeBrownfieldFileConfig,
+} from './projectFiles';
+
+// ESM/CJS interop shim: `@react-native-community/cli-config` ships CJS whose
+// default export is the function itself, but depending on how this module is
+// loaded (bundler/ESM interop) the import may be the module namespace object
+// with the function on `.default`. Unwrap to the callable either way —
+// do not remove, otherwise the scaffold crashes with "cliConfig is not a function".
+const cliConfig: typeof cliConfigImport =
+  typeof cliConfigImport === 'function'
+    ? cliConfigImport
+    : (cliConfigImport as any).default;
+
+export type BrownfieldScaffoldOptions = {
+  /**
+   * React Native project root directory (contains package.json).
+   * Defaults to current working directory.
+   */
+  projectRoot?: string;
+
+  /**
+   * iOS framework target name (also framework directory name).
+   * Defaults to "BrownfieldLib".
+   */
+  iosFrameworkName?: string;
+
+  /**
+   * Android library module folder / Gradle module name.
+   * Defaults to "brownfieldlib".
+   */
+  androidModuleName?: string;
+
+  /**
+   * Enables verbose logging.
+   */
+  debug?: boolean;
+};
+
+function findProjectRoot(startDir: string): string {
+  let currentDir = startDir;
+  while (true) {
+    if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+      return currentDir;
+    }
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
+  }
+  throw new Error('Could not find project root (no package.json found)');
+}
+
+function resolveUserConfig(projectRoot: string): UserConfig {
+  // Do not pass selectedPlatform: it restricts detection to a single platform
+  // and would leave project.android undefined.
+  return cliConfig({
+    projectRoot,
+  }) as UserConfig;
+}
+
+function readFileIfExists(filePath: string): string | null {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+}
+
+function writeFileIfChanged(filePath: string, next: string) {
+  const prev = readFileIfExists(filePath);
+  if (prev === next) return;
+  fs.writeFileSync(filePath, next, 'utf8');
+}
+
+function firstXcodeprojPath(iosDir: string): string {
+  const entries = fs.readdirSync(iosDir, { withFileTypes: true });
+  const xcodeproj = entries.find(
+    (e) => e.isDirectory() && e.name.endsWith('.xcodeproj')
+  );
+  if (!xcodeproj) {
+    throw new Error(
+      `Could not find an .xcodeproj under ${iosDir}. Did you run iOS project generation?`
+    );
+  }
+  return path.join(iosDir, xcodeproj.name);
+}
+
+function unquote(value: string): string {
+  return value.replace(/^"+|"+$/g, '');
+}
+
+function resolveIosAppBundleId(pbxproj: any): string | null {
+  const nativeTargets = pbxproj.pbxNativeTargetSection?.() ?? {};
+  const configLists = pbxproj.pbxXCConfigurationList?.() ?? {};
+  const buildConfigs = pbxproj.pbxXCBuildConfigurationSection?.() ?? {};
+
+  for (const [key, target] of Object.entries<any>(nativeTargets)) {
+    if (key.endsWith('_comment')) continue;
+    // heuristic: application targets usually have productType including "application"
+    if (
+      typeof target?.productType === 'string' &&
+      !target.productType.includes('application')
+    ) {
+      continue;
+    }
+
+    const configListId = target?.buildConfigurationList;
+    const configList = configLists?.[configListId];
+    const debugConfigId = configList?.buildConfigurations?.find?.(
+      (c: any) => c?.comment === 'Debug'
+    )?.value;
+    const debugConfig = debugConfigId ? buildConfigs?.[debugConfigId] : null;
+    const bundleId = debugConfig?.buildSettings?.PRODUCT_BUNDLE_IDENTIFIER;
+    if (typeof bundleId === 'string' && bundleId.length > 0) {
+      return unquote(bundleId);
+    }
+  }
+
+  return null;
+}
+
+function resolveReactNativeVersion(projectRoot: string): string {
+  // The shipped build is CommonJS, where bare `require` works. If this module
+  // is ever loaded as true ESM, bare `require` is undefined; fall back to an
+  // explicit `createRequire`. Anchored at cwd (not `import.meta.url`) because
+  // Babel keeps `import.meta` verbatim in the CJS output, which is a parse
+  // SyntaxError there.
+  const localRequire: NodeRequire =
+    typeof require === 'undefined'
+      ? createRequire(path.join(process.cwd(), 'noop.js'))
+      : require;
+  const rnPkgPath = localRequire.resolve('react-native/package.json', {
+    paths: [projectRoot],
+  });
+  const rnPkg = localRequire(rnPkgPath);
+  if (!rnPkg?.version) {
+    throw new Error('Could not resolve react-native version from package.json');
+  }
+  return rnPkg.version;
+}
+
+export async function scaffoldBrownfieldInRncCliProject(
+  options: BrownfieldScaffoldOptions = {}
+): Promise<void> {
+  const projectRoot = findProjectRoot(
+    path.resolve(options.projectRoot ?? process.cwd())
+  );
+  Logger.setIsDebug(options.debug ?? false);
+
+  const userConfig = resolveUserConfig(projectRoot);
+  const android = userConfig.project.android;
+  const ios = userConfig.project.ios;
+
+  if (!android) {
+    throw new Error('Android project not found.');
+  }
+  if (!ios) {
+    throw new Error('iOS project not found.');
+  }
+
+  const androidDir = path.isAbsolute(android.sourceDir)
+    ? android.sourceDir
+    : path.join(projectRoot, android.sourceDir || 'android');
+  // Honour the CLI-resolved iOS source directory (symmetry with Android
+  // above): a project that sets project.ios.sourceDir to a custom relative
+  // path makes the Community CLI resolve it to an absolute directory, and
+  // hard-coding <root>/ios would then miss the .xcodeproj or mutate the
+  // wrong directory. Note: an absolute sourceDir authored by the user is
+  // already rejected upstream (cli-config-apple joins it onto the project
+  // root), so the isAbsolute branch mainly guards the resolved value.
+  const iosSourceDir = ios.sourceDir;
+  const iosDir = path.isAbsolute(iosSourceDir)
+    ? iosSourceDir
+    : path.join(projectRoot, iosSourceDir || 'ios');
+
+  const rnVersion = resolveReactNativeVersion(projectRoot);
+
+  const iosFrameworkName = options.iosFrameworkName ?? 'BrownfieldLib';
+  const androidModuleName = options.androidModuleName ?? 'brownfieldlib';
+  const androidPackageName = android.packageName ?? android.applicationId;
+  if (!androidPackageName) {
+    throw new Error(
+      'Could not resolve Android package name from React Native CLI config.'
+    );
+  }
+
+  // Tracks the current mutation phase so a mid-way failure can name the step
+  // that failed and point users at fix-forward guidance (see catch below).
+  let currentStep = 'preconditions';
+
+  try {
+    currentStep = 'android-gradle';
+    // --- Android: root build.gradle + settings.gradle ---
+    const rootBuildGradlePath = path.join(androidDir, 'build.gradle');
+    const rootBuildGradle = readFileIfExists(rootBuildGradlePath);
+    if (!rootBuildGradle) {
+      throw new Error(`Missing ${rootBuildGradlePath}`);
+    }
+    writeFileIfChanged(
+      rootBuildGradlePath,
+      modifyRootBuildGradle(rootBuildGradle)
+    );
+
+    const settingsGradlePath = path.join(androidDir, 'settings.gradle');
+    const settingsGradle = readFileIfExists(settingsGradlePath);
+    if (!settingsGradle) {
+      throw new Error(`Missing ${settingsGradlePath}`);
+    }
+    writeFileIfChanged(
+      settingsGradlePath,
+      modifySettingsGradle(settingsGradle, androidModuleName)
+    );
+
+    const resolvedAndroidConfig: ResolvedBrownfieldPluginConfigWithAndroid = {
+      android: {
+        moduleName: androidModuleName,
+        packageName: androidPackageName,
+        // minSdk has no rootProject fallback in the shared build.gradle.kts
+        // template (it renders a literal), so keep the Expo plugin default.
+        // RN CLI rootProject.ext.minSdkVersion is 24 on current templates
+        // anyway; the generated build.gradle.kts stays readable.
+        minSdkVersion: 24,
+        // compile/target SDK are intentionally not hardcoded: leaving them
+        // unset makes the shared template fall back to
+        // resolveRootProjectInt("compileSdkVersion"/"targetSdkVersion"), i.e.
+        // the app's own rootProject.ext values (RN 0.87 needs compileSdk 37+;
+        // AGP 9 rejects library `targetSdk` entirely — see
+        // renderTargetSdkBlock). Proven against a real RN 0.87.1 app.
+        targetSdkVersion: undefined,
+        compileSdkVersion: undefined,
+        groupId: androidPackageName,
+        artifactId: androidModuleName,
+        version: '0.0.1-SNAPSHOT',
+        // Fields added to the resolved config after the original draft was
+        // written (BGP local-plugin wiring + flavor dimensions, #448/#458).
+        // Defaults match the Expo plugin defaults for RN CLI projects.
+        useLocalGradlePlugin: false,
+        useLocalMaven: false,
+        missingDimensionStrategies: [],
+      },
+      ios: null,
+      debug: options.debug ?? false,
+    };
+
+    currentStep = 'android-module';
+    createAndroidModule({
+      androidDir,
+      config: resolvedAndroidConfig,
+      rnVersion,
+      // 'vanilla' = non-Expo host (same axis as `useExpoHost: false` below).
+      templateVariant: 'vanilla',
+    });
+
+    // --- iOS: xcodeproj + Podfile + framework source files ---
+    currentStep = 'ios-project';
+    const xcodeprojPath = firstXcodeprojPath(iosDir);
+    const pbxprojPath = path.join(xcodeprojPath, 'project.pbxproj');
+    if (!fs.existsSync(pbxprojPath)) {
+      throw new Error(`Missing ${pbxprojPath}`);
+    }
+
+    const project = xcode.project(pbxprojPath);
+    project.parseSync();
+
+    const appBundleId = resolveIosAppBundleId(project);
+    const brownfieldBundleId = appBundleId
+      ? `${appBundleId}.brownfield`
+      : `com.brownfield.${iosFrameworkName.toLowerCase()}`;
+
+    const resolvedIosConfig: ResolvedBrownfieldPluginConfigWithIos = {
+      ios: {
+        frameworkName: iosFrameworkName,
+        bundleIdentifier: brownfieldBundleId,
+        buildSettings: {},
+        // Defaults aligned with the Expo plugin defaults (Expo's fallback
+        // when no deployment target can be derived; see
+        // resolveFrameworkDeploymentTarget). RN CLI config does not expose
+        // an iOS deployment target directly.
+        // TODO: derive from the Podfile `platform :ios` line or RN's
+        // min_ios_version_supported, or expose a flag.
+        deploymentTarget: '15.0',
+        // Standard CFBundleShortVersionString for the generated framework
+        // (matches the Expo plugin default); unrelated to package versioning.
+        frameworkVersion: '1',
+      },
+      android: null,
+      debug: options.debug ?? false,
+    };
+
+    // Contract: downstream helpers (xcodeHelpers.addFrameworkTarget /
+    // resolveAppTargetName) only read `platformProjectRoot` (framework group
+    // location) and `projectName` (app-target-name fallback), but the shared
+    // Expo-path signatures require a full ModProps, so we provide every field
+    // with scaffold-appropriate values (no mods are run here, so `introspect`
+    // is false and `nextMod` is omitted).
+    const modRequest: ModProps<XcodeProject> = {
+      projectRoot,
+      platformProjectRoot: iosDir,
+      modName: 'react-native-brownfield-scaffold',
+      platform: 'ios',
+      introspect: false,
+      projectName: path.basename(xcodeprojPath, '.xcodeproj'),
+    };
+
+    const { frameworkTargetUUID } = addFrameworkTarget(
+      project,
+      modRequest,
+      resolvedIosConfig.ios,
+      { useExpoHost: false }
+    );
+
+    copyBundleReactNativePhase(project, frameworkTargetUUID);
+    addSourceFilesBuildPhase(
+      project,
+      frameworkTargetUUID,
+      resolvedIosConfig.ios,
+      { useExpoHost: false }
+    );
+    // xcode@3.x writeSync() returns the serialized project but does not write it.
+    // This is the riskiest write: a failure here leaves a partially mutated
+    // pbxproj on disk (the in-memory changes are lost, not half-written).
+    fs.writeFileSync(pbxprojPath, project.writeSync());
+
+    currentStep = 'ios-podfile';
+    const podfilePath = path.join(iosDir, 'Podfile');
+    const podfile = readFileIfExists(podfilePath);
+    if (!podfile) {
+      throw new Error(`Missing ${podfilePath}`);
+    }
+    writeFileIfChanged(podfilePath, modifyPodfile(podfile, iosFrameworkName));
+
+    currentStep = 'ios-sources';
+    createIosFramework(iosDir, resolvedIosConfig, { useExpoHost: false });
+
+    // --- App package wiring: Brownfield deps + package:* scripts ---
+    // The scaffolded Kotlin host imports com.callstack.reactnativebrownfield.*,
+    // so the JS/runtime package must be an app dependency for native builds to
+    // resolve it. Idempotent: existing version specs are left untouched.
+    currentStep = 'package-dependencies';
+    addBrownfieldDependencies(projectRoot);
+
+    currentStep = 'package-scripts';
+    addBrownfieldPackageScripts(projectRoot);
+
+    // --- brownfield.config.json: packaging settings for `brownfield package:*` ---
+    // Deterministic content derived from the scaffolded names, so re-runs
+    // produce identical bytes (overwrite == no-op).
+    currentStep = 'brownfield-config';
+    writeBrownfieldFileConfig(projectRoot, {
+      iosFrameworkName,
+      androidModuleName,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    Logger.logInfo(
+      'Scaffolding failed mid-way; fix-forward: re-running the CLI is idempotent for completed steps (gradle settings, Podfile, xcodeproj target detection, package.json deps/scripts, brownfield.config.json) — inspect partial changes with git diff.'
+    );
+    throw new Error(
+      `Brownfield scaffolding failed during step "${currentStep}": ${message}`,
+      {
+        cause: error,
+      }
+    );
+  }
+
+  Logger.logInfo('Brownfield scaffolding complete.');
+}