@callstack/brownfield-cli 6.0.0 → 6.1.0

package/src/brownfield/utils/destinationSdks.ts

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { RockError } from '@rock-js/tools';
+
+/** Xcode SDK a build product directory belongs to (`Release-iphoneos`, `Release-iphonesimulator`). */
+export type AppleSdk = 'iphoneos' | 'iphonesimulator';
+
+/** Both slices, in the order Rock's `packageIosAction` builds them. */
+export const ALL_APPLE_SDKS: AppleSdk[] = ['iphoneos', 'iphonesimulator'];
+
+/**
+ * Map a single `--destination` value onto the SDK(s) its build products land in.
+ *
+ * Mirrors `resolveDestination` in `@rock-js/platform-apple-helpers`: the aliases
+ * `device`/`simulator` plus any raw `xcodebuild -destination` string. A value we
+ * cannot classify (`id=<udid>`, `name=iPhone 17`) may resolve to either SDK, so it
+ * widens to both rather than silently dropping a slice.
+ */
+function resolveSdksForDestination(destination: string): AppleSdk[] {
+  const normalized = destination.trim().toLowerCase();
+
+  if (normalized === 'device') {
+    return ['iphoneos'];
+  }
+
+  if (normalized === 'simulator' || normalized.includes('simulator')) {
+    return ['iphonesimulator'];
+  }
+
+  if (normalized.includes('platform=ios')) {
+    return ['iphoneos'];
+  }
+
+  return ALL_APPLE_SDKS;
+}
+
+/**
+ * SDK slices a `package:ios` run produces for the given `--destination` values.
+ *
+ * Omitting `--destination` builds both slices, matching Rock's default.
+ */
+export function resolveDestinationSdks(
+  destination?: string[] | null
+): AppleSdk[] {
+  if (!destination || destination.length === 0) {
+    return ALL_APPLE_SDKS;
+  }
+
+  const sdks = new Set(destination.flatMap(resolveSdksForDestination));
+
+  // keep a stable order regardless of the order the flags were passed in
+  return ALL_APPLE_SDKS.filter((sdk) => sdks.has(sdk));
+}
+
+/**
+ * Whether `directoryPath` holds a build product `mergeFrameworks` can consume:
+ * either a real `.framework` bundle or the static library it synthesizes one from.
+ */
+export function hasFrameworkBuildProduct(
+  directoryPath: string,
+  frameworkName: string
+) {
+  return (
+    fs.existsSync(path.join(directoryPath, `${frameworkName}.framework`)) ||
+    fs.existsSync(path.join(directoryPath, `lib${frameworkName}.a`))
+  );
+}
+
+interface CollectFrameworkPathsOptions {
+  productsPath: string;
+  configuration: string;
+  sdks: AppleSdk[];
+  frameworkName: string;
+  /** Sub-directory of the configuration products dir, e.g. `Brownie` for a Pod target. */
+  productSubDir?: string;
+}
+
+/**
+ * `.framework` paths to merge into an XCFramework, limited to the slices that were
+ * actually built. Slices with no build product on disk are dropped, so a
+ * `--destination simulator` run merges the simulator slice alone instead of failing
+ * on a missing `-iphoneos` directory.
+ *
+ * Throws when no slice has a build product: passing an empty list to
+ * `mergeFrameworks` would surface as xcodebuild's opaque
+ * "at least one framework or library must be specified".
+ */
+export function collectFrameworkPaths({
+  productsPath,
+  configuration,
+  sdks,
+  frameworkName,
+  productSubDir,
+}: CollectFrameworkPathsOptions): string[] {
+  const searchedDirectories = sdks.map((sdk) =>
+    path.join(
+      productsPath,
+      `${configuration}-${sdk}`,
+      ...(productSubDir ? [productSubDir] : [])
+    )
+  );
+
+  const frameworkPaths = searchedDirectories
+    .filter((directoryPath) =>
+      hasFrameworkBuildProduct(directoryPath, frameworkName)
+    )
+    .map((directoryPath) =>
+      path.join(directoryPath, `${frameworkName}.framework`)
+    );
+
+  if (frameworkPaths.length === 0) {
+    throw new RockError(
+      `Could not find a build product for ${frameworkName} in the ${configuration} configuration. ` +
+        `Looked for ${frameworkName}.framework or lib${frameworkName}.a in:\n` +
+        searchedDirectories.map((dir) => `  - ${dir}`).join('\n') +
+        `\nIf the build produced an .app instead of a framework, the wrong scheme was built; pass --scheme with your brownfield framework scheme.`
+    );
+  }
+
+  return frameworkPaths;
+}

package/src/brownfield/utils/emitExpoSupportXcframeworks.ts

@@ -1,10 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { RockError } from '@rock-js/tools';
+import { logger, RockError } from '@rock-js/tools';
 
 import { normalizeCopiedXcframework } from './normalizeCopiedXcframework.js';
-import { getExpoSdkMajor, isExpoProject } from './project.js';
+import {
+  getExpoIosUsePrecompiledModules,
+  getExpoSdkMajor,
+  isExpoProject,
+} from './project.js';
 
 import { MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_EXPO } from './supportsPrebuiltExpo.js';
 
@@ -87,14 +91,32 @@ function resolveExpoFrameworkSourcePath(
   throw new RockError(`Unsupported Expo XCFramework: ${frameworkName}`);
 }
 
+function getPrebuiltExpoRemedy(projectRoot: string) {
+  const cause =
+    getExpoIosUsePrecompiledModules(projectRoot) === false
+      ? 'expo-build-properties sets ios.usePrecompiledModules to false, so prebuilt Expo XCFrameworks are never produced. '
+      : '';
+  return `${cause}Either re-run with --use-prebuilt-expo false to build Expo modules from source, or run \`pod install\` (with ios.usePrecompiledModules enabled) to materialize the prebuilts.`;
+}
+
 export function emitExpoSupportXcframeworks({
   projectRoot,
   packageDir,
   usePrebuiltExpo = true,
+  usePrebuiltExpoExplicit = true,
+  onDegradeToSource,
 }: {
   projectRoot: string;
   packageDir: string;
   usePrebuiltExpo?: boolean;
+  /**
+   * Whether `usePrebuiltExpo` was chosen by the user (CLI flag or brownfield.config.json)
+   * rather than inferred from the Expo SDK version. When inferred, missing prebuilts
+   * degrade to building Expo modules from source instead of throwing.
+   */
+  usePrebuiltExpoExplicit?: boolean;
+  /** Called when an inferred `usePrebuiltExpo` was degraded to `false` because prebuilts are absent */
+  onDegradeToSource?: () => void;
 }) {
   if (!isExpoProject(projectRoot)) {
     return false;
@@ -108,6 +130,22 @@ export function emitExpoSupportXcframeworks({
     return false;
   }
 
+  if (usePrebuiltExpo && !usePrebuiltExpoExplicit) {
+    const missingPrebuilts = ALL_EXPO_SUPPORT_XCFRAMEWORK_NAMES.filter(
+      (frameworkName) =>
+        !fs.existsSync(resolveExpoFrameworkSourcePath(projectRoot, frameworkName))
+    );
+    // ExpoModulesJSI ships in node_modules and is not a Pods prebuilt; only degrade
+    // when Pods-provided prebuilts are absent.
+    if (missingPrebuilts.some((name) => name !== 'ExpoModulesJSI')) {
+      logger.warn(
+        `Prebuilt Expo XCFrameworks were not found (${missingPrebuilts.join(', ')}). ${getPrebuiltExpoRemedy(projectRoot)} Continuing without prebuilt Expo (--use-prebuilt-expo false); pass --use-prebuilt-expo true to make this an error.`
+      );
+      usePrebuiltExpo = false;
+      onDegradeToSource?.();
+    }
+  }
+
   for (const frameworkName of getExpoSupportXcframeworkNames(usePrebuiltExpo)) {
     const sourcePath = resolveExpoFrameworkSourcePath(
       projectRoot,
@@ -115,7 +153,7 @@ export function emitExpoSupportXcframeworks({
     );
     if (!fs.existsSync(sourcePath)) {
       throw new RockError(
-        `Expected Expo SDK ${MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_EXPO}+ XCFramework not found: ${frameworkName}.xcframework at ${path.relative(projectRoot, sourcePath)}`
+        `Expected Expo SDK ${MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_EXPO}+ XCFramework not found: ${frameworkName}.xcframework at ${path.relative(projectRoot, sourcePath)}. ${getPrebuiltExpoRemedy(projectRoot)}`
       );
     }
 
@@ -124,7 +162,13 @@ export function emitExpoSupportXcframeworks({
       `${frameworkName}.xcframework`
     );
     fs.rmSync(destinationPath, { recursive: true, force: true });
-    fs.cpSync(sourcePath, destinationPath, { recursive: true });
+    // With precompiled Expo, CocoaPods symlinks expo-image's dependencies into
+    // node_modules. Copy what the link points to, so the package is portable
+    // and normalizing it doesn't modify node_modules.
+    fs.cpSync(fs.realpathSync(sourcePath), destinationPath, {
+      recursive: true,
+      verbatimSymlinks: true,
+    });
     normalizeCopiedXcframework(destinationPath);
   }
 

package/src/brownfield/utils/expo.ts

@@ -1,4 +1,6 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 import { logger } from '@rock-js/tools';
 
@@ -41,6 +43,34 @@ function getNpxCommand() {
   return process.platform === 'win32' ? 'npx.cmd' : 'npx';
 }
 
+function isGitIgnored(targetPath: string): boolean {
+  // `git check-ignore` exits 0 when ignored, 1 when not, 128 outside a repo.
+  const result = spawnSync('git', ['check-ignore', '-q', targetPath], {
+    cwd: path.dirname(targetPath),
+    stdio: 'ignore',
+  });
+  if (result.status !== 0 && result.status !== 1) {
+    logger.warn(
+      `Couldn't check with git whether ${path.basename(targetPath)}/ is gitignored, so it's treated as committed and expo prebuild is skipped. If this project uses Continuous Native Generation, run \`npx expo prebuild\` before packaging.`
+    );
+  }
+  return result.status === 0;
+}
+
+/**
+ * Whether the platform's native project is generated by `expo prebuild` (Continuous Native
+ * Generation) rather than maintained by hand. A bare React Native app that installed Expo modules
+ * commits its native directories; running prebuild there would wipe them (including the
+ * brownfield library module), so prebuild only runs when the directory is missing or gitignored.
+ */
+export function usesContinuousNativeGeneration(
+  projectRoot: string,
+  platform: ExpoPlatform
+): boolean {
+  const nativeDir = path.join(projectRoot, platform);
+  return !fs.existsSync(nativeDir) || isGitIgnored(nativeDir);
+}
+
 export async function runExpoPrebuildIfNeeded({
   projectRoot,
   platform,
@@ -52,6 +82,13 @@ export async function runExpoPrebuildIfNeeded({
     return false;
   }
 
+  if (!usesContinuousNativeGeneration(projectRoot, platform)) {
+    logger.info(
+      `Expo modules detected in a project with a committed ${platform} directory. Skipping expo prebuild.`
+    );
+    return false;
+  }
+
   logger.info(
     `Expo project detected. Running expo prebuild for ${platform}...`
   );

package/src/brownfield/utils/project.ts

@@ -81,6 +81,71 @@ export function isExpoProject(projectRoot: string): boolean {
   return hasExpoAppConfig(projectRoot) && projectDependsOnExpo(projectRoot);
 }
 
+type ExpoPluginEntry = string | [string, ...unknown[]] | unknown;
+
+/**
+ * Reads `ios.usePrecompiledModules` from the `expo-build-properties` plugin entry.
+ *
+ * `getExpoConfigIfIsExpo` uses `skipPlugins: true`, which makes `@expo/config`
+ * delete `exp.plugins`, so the plugins array is read from `rootConfig` (the raw
+ * static app.json / app.config.json) instead. `rootConfig` is the raw *static*
+ * config only, so a dynamic config (app.config.js/ts) exposes no plugins that
+ * way; for those we retry once with plugins enabled, which keeps the plugins
+ * array. That retry can throw for plugins that are not loadable as Node modules
+ * (the reason `skipPlugins` is set in the first place), so it is best-effort.
+ *
+ * @returns the explicit boolean value, or `undefined` if it is not set or not resolvable
+ */
+export function getExpoIosUsePrecompiledModules(
+  projectRoot: string
+): boolean | undefined {
+  const config = getExpoConfigIfIsExpo(projectRoot);
+  if (!config) {
+    return undefined;
+  }
+
+  const rootConfig = config.rootConfig as
+    | { plugins?: ExpoPluginEntry[]; expo?: { plugins?: ExpoPluginEntry[] } }
+    | undefined;
+  let plugins =
+    (config.exp as { plugins?: ExpoPluginEntry[] }).plugins ??
+    rootConfig?.expo?.plugins ??
+    rootConfig?.plugins;
+
+  if (!Array.isArray(plugins)) {
+    // Dynamic config: no static plugins array exists. Retry with plugins
+    // enabled, which preserves `exp.plugins`. Best-effort — plugin resolution
+    // can throw, and an unreadable config is treated the same as an unset value.
+    try {
+      plugins = (
+        getConfig(projectRoot, { skipSDKVersionRequirement: true }).exp as {
+          plugins?: ExpoPluginEntry[];
+        }
+      ).plugins;
+    } catch {
+      return undefined;
+    }
+  }
+
+  if (!Array.isArray(plugins)) {
+    return undefined;
+  }
+
+  for (const plugin of plugins) {
+    if (!Array.isArray(plugin) || plugin[0] !== 'expo-build-properties') {
+      continue;
+    }
+    const value = (
+      plugin[1] as { ios?: { usePrecompiledModules?: unknown } } | undefined
+    )?.ios?.usePrecompiledModules;
+    if (typeof value === 'boolean') {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
 export function getExpoSdkMajor(projectRoot: string): number | null {
   const rawExpoVersion = getExpoConfigIfIsExpo(projectRoot)?.exp.sdkVersion;
   if (!rawExpoVersion) {

package/src/brownfield/utils/resolvePackagedFrameworkName.ts

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { ALL_APPLE_SDKS, type AppleSdk } from './destinationSdks.js';
+
 type Resolution = 'explicit' | 'detected' | 'not_found' | 'ambiguous';
 
 export interface ResolvePackagedFrameworkNameResult {
@@ -13,6 +15,8 @@ interface ResolvePackagedFrameworkNameOptions {
   explicitScheme?: string;
   productsPath: string;
   configuration: string;
+  /** Slices the build produced; defaults to both. */
+  sdks?: AppleSdk[];
 }
 
 function collectFrameworkCandidates(configurationProductsPath: string): string[] {
@@ -61,6 +65,7 @@ export function resolvePackagedFrameworkName({
   explicitScheme,
   productsPath,
   configuration,
+  sdks = ALL_APPLE_SDKS,
 }: ResolvePackagedFrameworkNameOptions): ResolvePackagedFrameworkNameResult {
   if (explicitScheme) {
     return {
@@ -69,11 +74,17 @@ export function resolvePackagedFrameworkName({
     };
   }
 
-  const configurationProductsPath = path.join(
-    productsPath,
-    `${configuration}-iphoneos`
-  );
-  const candidates = collectFrameworkCandidates(configurationProductsPath);
+  // the JS bundle is emitted per slice, so scan every slice that was built rather
+  // than assuming the device one exists (`--destination simulator` skips it)
+  const candidates = [
+    ...new Set(
+      sdks.flatMap((sdk) =>
+        collectFrameworkCandidates(
+          path.join(productsPath, `${configuration}-${sdk}`)
+        )
+      )
+    ),
+  ].sort();
 
   if (candidates.length === 1) {
     return {

package/src/brownfield/utils/supportsPrebuiltExpo.ts

@@ -1,11 +1,69 @@
-import { getExpoSdkMajor, isExpoProject } from './project.js';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { getReactNativeVersion } from '@rock-js/tools';
+
+import { getExpoIosUsePrecompiledModules, getExpoSdkMajor, isExpoProject } from './project.js';
 
 export const MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_EXPO = 56;
 
 export type PrebuiltExpoSupportResult =
-  | { supported: true; enabledByDefault: boolean; reason?: never }
+  | {
+      supported: true;
+      enabledByDefault: boolean;
+      /** Why prebuilts are off by default even though they are supported. */
+      defaultDisabledReason?: string;
+      reason?: never;
+    }
   | { supported: false; enabledByDefault?: never; reason: string };
 
+function majorMinor(version: string): string {
+  return version.split('.').slice(0, 2).join('.');
+}
+
+/**
+ * The React Native version the installed Expo SDK pins. Expo ships its
+ * precompiled modules built against this version.
+ */
+export function getExpoReactNativeVersion(projectRoot: string): string | null {
+  try {
+    const require = createRequire(path.join(projectRoot, 'package.json'));
+    const expoPackageJson = require.resolve('expo/package.json');
+    const bundledNativeModules = JSON.parse(
+      fs.readFileSync(
+        path.join(path.dirname(expoPackageJson), 'bundledNativeModules.json'),
+        'utf8'
+      )
+    ) as Record<string, string>;
+    return bundledNativeModules['react-native'] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Describes a React Native version the Expo prebuilts were not built for, or
+ * returns null when they match. Prebuilt Expo modules link against React
+ * Native's C++ API, which changes between minor versions, so a mismatch
+ * crashes at runtime.
+ */
+export function getPrebuiltExpoReactNativeMismatch(
+  projectRoot: string
+): string | null {
+  const expected = getExpoReactNativeVersion(projectRoot);
+  const found = getReactNativeVersion(projectRoot);
+  if (!expected || found === 'unknown') {
+    return null;
+  }
+
+  if (majorMinor(expected) === majorMinor(found)) {
+    return null;
+  }
+
+  return `Expo's precompiled modules are built for React Native ${majorMinor(expected)}, but this project uses ${found}.`;
+}
+
 export function supportsPrebuiltExpo({
   projectRoot,
 }: {
@@ -27,8 +85,46 @@ export function supportsPrebuiltExpo({
     };
   }
 
+  const reactNativeMismatch = getPrebuiltExpoReactNativeMismatch(projectRoot);
+  if (reactNativeMismatch) {
+    return {
+      supported: true,
+      enabledByDefault: false,
+      defaultDisabledReason: reactNativeMismatch,
+    };
+  }
+
+  if (getExpoIosUsePrecompiledModules(projectRoot) === false) {
+    return {
+      supported: false,
+      reason:
+        "--use-prebuilt-expo is unsupported: expo-build-properties sets ios.usePrecompiledModules to false in your Expo config, so prebuilt Expo XCFrameworks are never produced. Set it to true (or remove it) and run 'pod install', or pass --use-prebuilt-expo false to build Expo modules from source.",
+    };
+  }
+
   return {
     supported: true,
     enabledByDefault: true,
   };
 }
+
+/**
+ * Whether the project's Podfile turns Expo's precompiled modules off. Expo
+ * Podfiles force `EXPO_USE_PRECOMPILED_MODULES` to '0' when
+ * `ios/Podfile.properties.json` sets it to "false", whatever the environment says.
+ */
+export function isPrecompiledExpoDisabledByPodfile(
+  projectRoot: string
+): boolean {
+  try {
+    const properties = JSON.parse(
+      fs.readFileSync(
+        path.join(projectRoot, 'ios', 'Podfile.properties.json'),
+        'utf8'
+      )
+    );
+    return properties.EXPO_USE_PRECOMPILED_MODULES === 'false';
+  } catch {
+    return false;
+  }
+}

package/src/expoPluginConfig.ts

@@ -28,6 +28,7 @@ export type BrownfieldPluginProps = {
     extraProguardRules?: string[];
     useLocalMaven?: boolean;
     missingDimensionStrategies?: string[];
+    excludeDependencies?: string[];
   };
 };
 
@@ -45,6 +46,7 @@ export type ResolvedBrownfieldPluginAndroidConfig = {
   extraProguardRules: string[];
   useLocalMaven: boolean;
   missingDimensionStrategies: string[];
+  excludeDependencies: string[];
 };
 
 export type ResolvedBrownfieldPluginIosConfig = {
@@ -214,6 +216,8 @@ export function resolveBrownfieldPluginConfig(
           useLocalMaven: effectiveProps.android?.useLocalMaven ?? false,
           missingDimensionStrategies:
             effectiveProps.android?.missingDimensionStrategies ?? [],
+          excludeDependencies:
+            effectiveProps.android?.excludeDependencies ?? [],
           ...(effectiveProps.android?.targetSdkVersion != null
             ? { targetSdkVersion: effectiveProps.android.targetSdkVersion }
             : {}),

package/src/index.ts

@@ -15,6 +15,18 @@ import navigationCommands, {
   groupName as navigationCommandsGroupName,
 } from './navigation/index.js';
 
+// CocoaPods (spawned by Rock) raises Encoding::CompatibilityError under a non-UTF-8
+// locale. Ruby resolves the character encoding as LC_ALL > LC_CTYPE > LANG, so check
+// them in that precedence. Default to UTF-8 only when the effective value is missing
+// or non-UTF-8.
+const inheritedCharset =
+  process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || '';
+if (!/utf-?8/i.test(inheritedCharset)) {
+  process.env.LANG = 'en_US.UTF-8';
+  process.env.LC_CTYPE = 'en_US.UTF-8';
+  process.env.LC_ALL = 'en_US.UTF-8';
+}
+
 const program = new Command();
 
 program

package/src/types.ts

@@ -113,10 +113,17 @@ export type BrownfieldExpoAndroidConfig = {
    */
   useLocalMaven?: boolean;
 
-  /**   
+  /**
    * Missing dimension strategies as dimension + flavor(s), e.g. "type, alpha".
    */
   missingDimensionStrategies?: string[];
+
+  /**
+   * Dependencies to keep out of the published AAR's POM and module.json, as
+   * "group:module" or "group" for a whole group. Written as Gradle excludes
+   * into the generated module, e.g. "com.caverock:androidsvg".
+   */
+  excludeDependencies?: string[];
 };
 
 /**