@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/mobile/ios/host-artifact.mjs

@@ -0,0 +1,819 @@
+import { spawnSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const IOS_HOST_XCFRAMEWORK_NAME = 'aurajs-host.xcframework';
+
+const IOS_HOST_FRAMEWORK_DIRECTORY = 'aurajs-host.framework';
+const IOS_HOST_FRAMEWORK_BINARY = 'aurajs-host';
+const IOS_HOST_DYNAMIC_LIBRARY = 'libaurajs_host.dylib';
+const IOS_HOST_STATIC_LIBRARY = 'libaurajs_host.a';
+const IOS_DEVICE_LIBRARY_IDENTIFIER = 'ios-arm64';
+const IOS_SIMULATOR_LIBRARY_IDENTIFIER = 'ios-arm64-simulator';
+const IOS_DEVICE_RUST_TARGET = 'aarch64-apple-ios';
+const IOS_SIMULATOR_RUST_TARGET = 'aarch64-apple-ios-sim';
+const REQUIRED_HOST_SYMBOLS = [
+  'aurajs_host_bootstrap_v1',
+  'aurajs_host_run_v1',
+];
+const DEFAULT_DIST_ROOT = resolve(
+  fileURLToPath(new URL('../../../../platform/dist/ios/', import.meta.url)),
+);
+const DEFAULT_RUST_HOST_ROOT = resolve(
+  fileURLToPath(new URL('../../../../rust-host/', import.meta.url)),
+);
+const DEFAULT_IOS_PATCHED_V8_ROOT = resolve(
+  fileURLToPath(new URL('./vendor/v8-0.92.0/', import.meta.url)),
+);
+const DEFAULT_IOS_HOST_DEPLOYMENT_TARGET = '15.0';
+
+export function produceIosHostArtifact(options = {}) {
+  const environment = options.environment || process.env;
+  const spawnSyncImpl = options.spawnSyncImpl || spawnSync;
+  const distRoot = resolve(options.distRoot || DEFAULT_DIST_ROOT);
+  const rustHostRoot = resolve(options.rustHostRoot || DEFAULT_RUST_HOST_ROOT);
+  const cargoManifestPath = resolve(options.cargoManifestPath || join(rustHostRoot, 'Cargo.toml'));
+  const outputPath = join(distRoot, IOS_HOST_XCFRAMEWORK_NAME);
+  const profile = cleanString(options.profile) || 'release';
+  const xcodebuildExecutable = cleanString(options.xcodebuildExecutable)
+    || cleanString(environment.AURA_IOS_XCODEBUILD)
+    || 'xcodebuild';
+  const cargoExecutable = cleanString(options.cargoExecutable)
+    || cleanString(environment.AURA_IOS_CARGO)
+    || 'cargo';
+  const nmExecutable = cleanString(options.nmExecutable)
+    || cleanString(environment.AURA_IOS_NM)
+    || 'nm';
+  const rustupExecutable = cleanString(options.rustupExecutable)
+    || cleanString(environment.AURA_IOS_RUSTUP)
+    || 'rustup';
+  const patchedV8Path = cleanString(options.patchedV8Path)
+    || cleanString(environment.AURA_IOS_PATCHED_V8_PATH)
+    || DEFAULT_IOS_PATCHED_V8_ROOT;
+
+  mkdirSync(distRoot, { recursive: true });
+
+  const existingDist = validateXcframework(outputPath, {
+    spawnSyncImpl,
+    nmExecutable,
+    cwd: rustHostRoot,
+    environment,
+  });
+  if (existingDist.ok) {
+    return {
+      ok: true,
+      reasonCode: 'ios_host_artifact_existing_dist',
+      detail: 'Reused the validated iOS host artifact from the deterministic dist handoff.',
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'existing_dist',
+      checks: null,
+    };
+  }
+
+  const explicitInputPath = cleanString(options.hostFrameworkPath)
+    ? resolve(options.hostFrameworkPath)
+    : null;
+  if (explicitInputPath) {
+    const validation = validateXcframework(explicitInputPath, {
+      spawnSyncImpl,
+      nmExecutable,
+      cwd: rustHostRoot,
+      environment,
+    });
+    if (!validation.ok) {
+      return {
+        ok: false,
+        reasonCode: 'ios_host_artifact_invalid_input',
+        detail: validation.detail,
+        artifactPath: outputPath,
+        distRoot,
+        sourceKind: 'explicit_input',
+        checks: null,
+      };
+    }
+
+    replaceDirectory(explicitInputPath, outputPath);
+    return {
+      ok: true,
+      reasonCode: 'ios_host_artifact_copied',
+      detail: 'Copied the validated iOS host artifact into the deterministic dist handoff.',
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'explicit_input',
+      checks: null,
+    };
+  }
+
+  if (String(environment.AURAJS_SKIP_XCODE_PROBE || '') === '1') {
+    return failedHostArtifactResult({
+      reasonCode: 'ios_xcode_probe_skipped',
+      detail: 'Xcode probing was skipped by AURAJS_SKIP_XCODE_PROBE=1.',
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild: {
+          available: false,
+          reasonCode: 'ios_xcode_probe_skipped',
+          detail: 'Xcode probing was skipped by AURAJS_SKIP_XCODE_PROBE=1.',
+          executablePath: xcodebuildExecutable,
+        },
+        cargo: null,
+        rustTargets: null,
+      },
+    });
+  }
+
+  const xcodebuild = probeExecutable({
+    spawnSyncImpl,
+    executablePath: xcodebuildExecutable,
+    args: ['-version'],
+    cwd: rustHostRoot,
+    environment,
+    missingReasonCode: 'ios_host_artifact_xcodebuild_missing',
+    successReasonCode: 'ios_host_artifact_xcodebuild_available',
+  });
+  if (!xcodebuild.available) {
+    return failedHostArtifactResult({
+      reasonCode: xcodebuild.reasonCode,
+      detail: xcodebuild.detail,
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo: null,
+        rustTargets: null,
+      },
+    });
+  }
+
+  if (!existsSync(cargoManifestPath)) {
+    return failedHostArtifactResult({
+      reasonCode: 'ios_host_artifact_rust_manifest_missing',
+      detail: `Missing Rust host manifest at ${cargoManifestPath}.`,
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo: null,
+        rustTargets: null,
+      },
+    });
+  }
+
+  const cargo = probeExecutable({
+    spawnSyncImpl,
+    executablePath: cargoExecutable,
+    args: ['--version'],
+    cwd: rustHostRoot,
+    environment,
+    missingReasonCode: 'ios_host_artifact_cargo_missing',
+    successReasonCode: 'ios_host_artifact_cargo_available',
+  });
+  if (!cargo.available) {
+    return failedHostArtifactResult({
+      reasonCode: cargo.reasonCode,
+      detail: cargo.detail,
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo,
+        rustTargets: null,
+      },
+    });
+  }
+
+  const rustTargets = probeRustTargets({
+    spawnSyncImpl,
+    executablePath: rustupExecutable,
+    cwd: rustHostRoot,
+    environment,
+  });
+  if (!rustTargets.available) {
+    return failedHostArtifactResult({
+      reasonCode: rustTargets.reasonCode,
+      detail: rustTargets.detail,
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo,
+        rustTargets,
+      },
+    });
+  }
+
+  const tempRoot = mkdtempSync(join(tmpdir(), 'aurajs-ios-host-artifact-'));
+  try {
+    const isolatedWorkspace = createIsolatedIosCargoWorkspace({
+      rustHostRoot,
+      patchedV8Path,
+      tempRoot,
+    });
+    const isolatedRustHostRoot = isolatedWorkspace.rustHostRoot;
+    const isolatedCargoManifestPath = isolatedWorkspace.cargoManifestPath;
+    const cargoTargetRoot = resolveCargoTargetRoot({
+      rustHostRoot: isolatedRustHostRoot,
+      environment,
+    });
+
+    runCargoBuild({
+      spawnSyncImpl,
+      executablePath: cargoExecutable,
+      manifestPath: isolatedCargoManifestPath,
+      rustHostRoot: isolatedRustHostRoot,
+      rustTarget: IOS_DEVICE_RUST_TARGET,
+      profile,
+      environment: createIosCargoBuildEnvironment(environment, IOS_DEVICE_RUST_TARGET),
+    });
+    runCargoBuild({
+      spawnSyncImpl,
+      executablePath: cargoExecutable,
+      manifestPath: isolatedCargoManifestPath,
+      rustHostRoot: isolatedRustHostRoot,
+      rustTarget: IOS_SIMULATOR_RUST_TARGET,
+      profile,
+      environment: createIosCargoBuildEnvironment(environment, IOS_SIMULATOR_RUST_TARGET),
+    });
+    const deviceHostLibraryPath = resolveBuiltHostLibraryPath({
+      cargoTargetRoot,
+      rustTarget: IOS_DEVICE_RUST_TARGET,
+      profile,
+    });
+    const simulatorHostLibraryPath = resolveBuiltHostLibraryPath({
+      cargoTargetRoot,
+      rustTarget: IOS_SIMULATOR_RUST_TARGET,
+      profile,
+    });
+    const deviceFrameworkPath = createStaticFrameworkBundle({
+      tempRoot,
+      sliceName: IOS_DEVICE_LIBRARY_IDENTIFIER,
+      libraryPath: deviceHostLibraryPath,
+    });
+    const simulatorFrameworkPath = createStaticFrameworkBundle({
+      tempRoot,
+      sliceName: IOS_SIMULATOR_LIBRARY_IDENTIFIER,
+      libraryPath: simulatorHostLibraryPath,
+    });
+    const tempOutputPath = join(tempRoot, IOS_HOST_XCFRAMEWORK_NAME);
+    const createResult = spawnSyncImpl(
+      xcodebuildExecutable,
+      [
+        '-create-xcframework',
+        '-framework',
+        deviceFrameworkPath,
+        '-framework',
+        simulatorFrameworkPath,
+        '-output',
+        tempOutputPath,
+      ],
+      {
+        cwd: isolatedRustHostRoot,
+        encoding: 'utf8',
+        env: environment,
+      },
+    );
+
+    if (createResult.status !== 0) {
+      return failedHostArtifactResult({
+        reasonCode: 'ios_host_artifact_xcframework_create_failed',
+        detail: formatSpawnFailure('xcodebuild -create-xcframework', createResult),
+        artifactPath: outputPath,
+        distRoot,
+        sourceKind: 'local_build',
+        checks: {
+          xcodebuild,
+          cargo,
+          rustTargets,
+        },
+      });
+    }
+
+    const builtArtifact = validateXcframework(tempOutputPath, {
+      spawnSyncImpl,
+      nmExecutable,
+      cwd: isolatedRustHostRoot,
+      environment,
+    });
+    if (!builtArtifact.ok) {
+      return failedHostArtifactResult({
+        reasonCode: 'ios_host_artifact_output_invalid',
+        detail: builtArtifact.detail,
+        artifactPath: outputPath,
+        distRoot,
+        sourceKind: 'local_build',
+        checks: {
+          xcodebuild,
+          cargo,
+          rustTargets,
+        },
+      });
+    }
+
+    replaceDirectory(tempOutputPath, outputPath);
+    return {
+      ok: true,
+      reasonCode: 'ios_host_artifact_built',
+      detail: 'Built the iOS host xcframework from the local Rust host and copied it into dist.',
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo,
+        rustTargets,
+      },
+    };
+  } catch (error) {
+    const reasonCode = error?.reasonCode || 'ios_host_artifact_cargo_build_failed';
+    const detail = error instanceof Error ? error.message : String(error);
+    if (reasonCode === 'ios_host_artifact_staticlib_missing' || reasonCode === 'ios_host_artifact_v8_patch_missing') {
+      return failedHostArtifactResult({
+        reasonCode,
+        detail,
+        artifactPath: outputPath,
+        distRoot,
+        sourceKind: 'local_build',
+        checks: {
+          xcodebuild,
+          cargo,
+          rustTargets,
+        },
+      });
+    }
+    return failedHostArtifactResult({
+      reasonCode,
+      detail,
+      artifactPath: outputPath,
+      distRoot,
+      sourceKind: 'local_build',
+      checks: {
+        xcodebuild,
+        cargo,
+        rustTargets,
+      },
+    });
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function failedHostArtifactResult({
+  reasonCode,
+  detail,
+  artifactPath,
+  distRoot,
+  sourceKind,
+  checks,
+}) {
+  return {
+    ok: false,
+    reasonCode,
+    detail,
+    artifactPath,
+    distRoot,
+    sourceKind,
+    checks,
+  };
+}
+
+function probeExecutable({
+  spawnSyncImpl,
+  executablePath,
+  args,
+  cwd,
+  environment,
+  missingReasonCode,
+  successReasonCode,
+}) {
+  const result = spawnSyncImpl(executablePath, args, {
+    cwd,
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    return {
+      available: false,
+      reasonCode: missingReasonCode,
+      executablePath,
+      detail: formatSpawnFailure(executablePath, result),
+    };
+  }
+  return {
+    available: true,
+    reasonCode: successReasonCode,
+    executablePath,
+    detail: firstNonEmptyLine(result.stdout) || null,
+  };
+}
+
+function probeRustTargets({
+  spawnSyncImpl,
+  executablePath,
+  cwd,
+  environment,
+}) {
+  const result = spawnSyncImpl(executablePath, ['target', 'list', '--installed'], {
+    cwd,
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    return {
+      available: false,
+      reasonCode: 'ios_host_artifact_rustup_missing',
+      executablePath,
+      detail: formatSpawnFailure(`${executablePath} target list --installed`, result),
+      installed: [],
+      missing: [IOS_DEVICE_RUST_TARGET, IOS_SIMULATOR_RUST_TARGET],
+    };
+  }
+
+  const installed = String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const missing = [IOS_DEVICE_RUST_TARGET, IOS_SIMULATOR_RUST_TARGET]
+    .filter((target) => !installed.includes(target));
+  if (missing.length > 0) {
+    return {
+      available: false,
+      reasonCode: 'ios_host_artifact_rust_target_missing',
+      executablePath,
+      detail: `Missing required iOS Rust targets: ${missing.join(', ')}.`,
+      installed,
+      missing,
+    };
+  }
+
+  return {
+    available: true,
+    reasonCode: 'ios_host_artifact_rust_targets_available',
+    executablePath,
+    detail: null,
+    installed,
+    missing: [],
+  };
+}
+
+function createIosCargoBuildEnvironment(environment, rustTarget) {
+  const buildEnvironment = {
+    ...environment,
+  };
+  const deploymentTarget = cleanString(buildEnvironment.AURA_IOS_DEPLOYMENT_TARGET)
+    || cleanString(buildEnvironment.IPHONEOS_DEPLOYMENT_TARGET)
+    || DEFAULT_IOS_HOST_DEPLOYMENT_TARGET;
+  const deploymentFlag = rustTarget === IOS_SIMULATOR_RUST_TARGET
+    ? `-mios-simulator-version-min=${deploymentTarget}`
+    : `-miphoneos-version-min=${deploymentTarget}`;
+
+  if (!cleanString(buildEnvironment.V8_FROM_SOURCE) && !cleanString(buildEnvironment.RUSTY_V8_ARCHIVE)) {
+    buildEnvironment.V8_FROM_SOURCE = '1';
+  }
+  if (!cleanString(buildEnvironment.PYTHON)) {
+    buildEnvironment.PYTHON = 'python3';
+  }
+  buildEnvironment.IPHONEOS_DEPLOYMENT_TARGET = deploymentTarget;
+  appendTargetShellFlag(buildEnvironment, 'CFLAGS', rustTarget, deploymentFlag);
+  appendTargetShellFlag(buildEnvironment, 'CXXFLAGS', rustTarget, deploymentFlag);
+  appendTargetShellFlag(buildEnvironment, 'OBJCFLAGS', rustTarget, deploymentFlag);
+  buildEnvironment.RUSTFLAGS = withShellFlag(
+    buildEnvironment.RUSTFLAGS,
+    `-C link-arg=${deploymentFlag}`,
+  );
+  buildEnvironment.GN_ARGS = withIosGnArgs(buildEnvironment.GN_ARGS, rustTarget, deploymentTarget);
+
+  return buildEnvironment;
+}
+
+function createIsolatedIosCargoWorkspace({
+  rustHostRoot,
+  patchedV8Path,
+  tempRoot,
+}) {
+  const resolvedPatchedV8Path = resolveExistingPath(patchedV8Path, 'patched iOS v8 crate');
+  const isolatedRustHostRoot = join(tempRoot, 'rust-host');
+  copyDirectoryExcluding(rustHostRoot, isolatedRustHostRoot, ['target', '.git', '.cargo']);
+  const cargoConfigDirectory = join(isolatedRustHostRoot, '.cargo');
+  mkdirSync(cargoConfigDirectory, { recursive: true });
+  writeFileSync(
+    join(cargoConfigDirectory, 'config.toml'),
+    [
+      '[patch.crates-io]',
+      `v8 = { path = ${JSON.stringify(resolvedPatchedV8Path)} }`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const cargoManifestPath = join(isolatedRustHostRoot, 'Cargo.toml');
+  if (!existsSync(cargoManifestPath)) {
+    const error = new Error(`Missing isolated Rust host manifest at ${cargoManifestPath}.`);
+    error.reasonCode = 'ios_host_artifact_rust_manifest_missing';
+    throw error;
+  }
+  return {
+    rustHostRoot: isolatedRustHostRoot,
+    cargoManifestPath,
+  };
+}
+
+function withIosGnArgs(existingGnArgs, rustTarget, deploymentTarget) {
+  const targetEnvironment = rustTarget === IOS_SIMULATOR_RUST_TARGET ? 'simulator' : 'device';
+  let gnArgs = cleanString(existingGnArgs) || '';
+
+  gnArgs = appendGnArgIfMissing(gnArgs, 'target_os', '"ios"');
+  gnArgs = appendGnArgIfMissing(gnArgs, 'target_environment', `"${targetEnvironment}"`);
+  gnArgs = appendGnArgIfMissing(gnArgs, 'ios_deployment_target', `"${deploymentTarget}"`);
+  gnArgs = appendGnArgIfMissing(gnArgs, 'ios_enable_code_signing', 'false');
+  gnArgs = appendGnArgIfMissing(gnArgs, 'enable_ios_bitcode', 'false');
+
+  return gnArgs;
+}
+
+function appendGnArgIfMissing(gnArgs, key, value) {
+  const pattern = new RegExp(`(?:^|\\s)${escapeRegExp(key)}=`);
+  if (pattern.test(gnArgs)) {
+    return gnArgs;
+  }
+  return gnArgs ? `${gnArgs} ${key}=${value}` : `${key}=${value}`;
+}
+
+function escapeRegExp(input) {
+  return String(input).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function withShellFlag(existingFlags, flag) {
+  let flags = cleanString(existingFlags) || '';
+  if (!flags.includes(flag)) {
+    flags = `${flags} ${flag}`.trim();
+  }
+  return flags;
+}
+
+function appendTargetShellFlag(environment, prefix, rustTarget, flag) {
+  const targetKey = `${prefix}_${rustTarget.replaceAll('-', '_')}`;
+  environment[targetKey] = withShellFlag(environment[targetKey], flag);
+}
+
+function resolveExistingPath(path, label) {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) {
+    const error = new Error(`Missing ${label}: ${resolved}`);
+    error.reasonCode = 'ios_host_artifact_v8_patch_missing';
+    throw error;
+  }
+  return resolved;
+}
+
+function runCargoBuild({
+  spawnSyncImpl,
+  executablePath,
+  manifestPath,
+  rustHostRoot,
+  rustTarget,
+  profile,
+  environment,
+}) {
+  const args = [
+    'build',
+    '--manifest-path',
+    manifestPath,
+    '--lib',
+    '--target',
+    rustTarget,
+  ];
+  if (profile === 'release') {
+    args.push('--release');
+  }
+  const result = spawnSyncImpl(executablePath, args, {
+    cwd: rustHostRoot,
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    const error = new Error(formatSpawnFailure(`${executablePath} build`, result));
+    error.reasonCode = 'ios_host_artifact_cargo_build_failed';
+    throw error;
+  }
+}
+
+function resolveCargoTargetRoot({ rustHostRoot, environment }) {
+  const configuredTargetDir = cleanString(environment.CARGO_TARGET_DIR);
+  if (!configuredTargetDir) {
+    return join(rustHostRoot, 'target');
+  }
+  return resolve(rustHostRoot, configuredTargetDir);
+}
+
+function resolveBuiltHostLibraryPath({ cargoTargetRoot, rustTarget, profile }) {
+  const outputRoot = join(cargoTargetRoot, rustTarget, profile);
+  const dynamicLibraryPath = join(outputRoot, IOS_HOST_DYNAMIC_LIBRARY);
+  if (existsSync(dynamicLibraryPath)) {
+    return dynamicLibraryPath;
+  }
+  const staticLibraryPath = join(outputRoot, IOS_HOST_STATIC_LIBRARY);
+  if (existsSync(staticLibraryPath)) {
+    return staticLibraryPath;
+  }
+  const error = new Error(
+    `Missing iOS host library output for ${rustTarget} under ${outputRoot}.`,
+  );
+  error.reasonCode = 'ios_host_artifact_staticlib_missing';
+  throw error;
+}
+
+function createStaticFrameworkBundle({ tempRoot, sliceName, libraryPath }) {
+  const frameworkRoot = join(tempRoot, sliceName, IOS_HOST_FRAMEWORK_DIRECTORY);
+  mkdirSync(frameworkRoot, { recursive: true });
+  cpSync(libraryPath, join(frameworkRoot, IOS_HOST_FRAMEWORK_BINARY), { force: true });
+  writeFileSync(
+    join(frameworkRoot, 'Info.plist'),
+    [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      '<dict>',
+      '  <key>CFBundleExecutable</key>',
+      `  <string>${IOS_HOST_FRAMEWORK_BINARY}</string>`,
+      '  <key>CFBundleIdentifier</key>',
+      `  <string>gg.aurajs.${sliceName}.${IOS_HOST_FRAMEWORK_BINARY}</string>`,
+      '  <key>CFBundleName</key>',
+      `  <string>${IOS_HOST_FRAMEWORK_BINARY}</string>`,
+      '  <key>CFBundlePackageType</key>',
+      '  <string>FMWK</string>',
+      '  <key>CFBundleShortVersionString</key>',
+      '  <string>1.0.0</string>',
+      '  <key>CFBundleVersion</key>',
+      '  <string>1</string>',
+      '</dict>',
+      '</plist>',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  return frameworkRoot;
+}
+
+function validateXcframework(
+  xcframeworkPath,
+  {
+    spawnSyncImpl = spawnSync,
+    nmExecutable = 'nm',
+    cwd = process.cwd(),
+    environment = process.env,
+  } = {},
+) {
+  try {
+    requireExistingPath(join(xcframeworkPath, 'Info.plist'), 'xcframework Info.plist');
+    const deviceBinaryPath = requireExistingPath(
+      join(
+        xcframeworkPath,
+        IOS_DEVICE_LIBRARY_IDENTIFIER,
+        IOS_HOST_FRAMEWORK_DIRECTORY,
+        IOS_HOST_FRAMEWORK_BINARY,
+      ),
+      'xcframework device binary',
+    );
+    const simulatorBinaryPath = requireExistingPath(
+      join(
+        xcframeworkPath,
+        IOS_SIMULATOR_LIBRARY_IDENTIFIER,
+        IOS_HOST_FRAMEWORK_DIRECTORY,
+        IOS_HOST_FRAMEWORK_BINARY,
+      ),
+      'xcframework simulator binary',
+    );
+    validateFrameworkBinarySymbols(deviceBinaryPath, 'device', {
+      spawnSyncImpl,
+      nmExecutable,
+      cwd,
+      environment,
+    });
+    validateFrameworkBinarySymbols(simulatorBinaryPath, 'simulator', {
+      spawnSyncImpl,
+      nmExecutable,
+      cwd,
+      environment,
+    });
+    return {
+      ok: true,
+      detail: null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function validateFrameworkBinarySymbols(
+  binaryPath,
+  sliceLabel,
+  {
+    spawnSyncImpl,
+    nmExecutable,
+    cwd,
+    environment,
+  },
+) {
+  const result = spawnSyncImpl(nmExecutable, ['-gU', binaryPath], {
+    cwd,
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `Failed to inspect exported iOS host symbols in ${sliceLabel} binary ${resolve(binaryPath)}: ${formatSpawnFailure(`${nmExecutable} -gU`, result)}`,
+    );
+  }
+  const exportedSymbols = String(result.stdout || '');
+  const missingSymbols = REQUIRED_HOST_SYMBOLS.filter((symbol) => {
+    const pattern = new RegExp(`(?:^|\\s)_?${escapeRegExp(symbol)}(?:\\s|$)`, 'm');
+    return !pattern.test(exportedSymbols);
+  });
+  if (missingSymbols.length > 0) {
+    throw new Error(
+      `Missing required iOS host symbol(s) in ${sliceLabel} binary ${resolve(binaryPath)}: ${missingSymbols.join(', ')}`,
+    );
+  }
+}
+
+function requireExistingPath(path, label) {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) {
+    throw new Error(`Missing ${label}: ${resolved}`);
+  }
+  return resolved;
+}
+
+function replaceDirectory(sourceRoot, destRoot) {
+  rmSync(destRoot, { recursive: true, force: true });
+  copyDirectory(sourceRoot, destRoot);
+}
+
+function copyDirectory(sourceRoot, destRoot) {
+  mkdirSync(destRoot, { recursive: true });
+  cpSync(sourceRoot, destRoot, {
+    recursive: true,
+    dereference: false,
+    force: true,
+  });
+}
+
+function copyDirectoryExcluding(sourceRoot, destRoot, excludedTopLevelNames) {
+  const excluded = new Set(excludedTopLevelNames);
+  mkdirSync(destRoot, { recursive: true });
+  cpSync(sourceRoot, destRoot, {
+    recursive: true,
+    dereference: false,
+    force: true,
+    filter(source) {
+      const rel = relative(sourceRoot, source);
+      if (!rel || rel === '') {
+        return true;
+      }
+      const topLevel = rel.split(/[\\/]/)[0];
+      return !excluded.has(topLevel);
+    },
+  });
+}
+
+function formatSpawnFailure(commandLabel, result) {
+  const detail = [result?.stdout, result?.stderr]
+    .filter((value) => typeof value === 'string' && value.trim().length > 0)
+    .join('\n')
+    .trim();
+  return detail.length > 0
+    ? detail
+    : `${commandLabel} was not available or returned a non-zero exit status.`;
+}
+
+function firstNonEmptyLine(value) {
+  return String(value || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .find(Boolean)
+    || null;
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+    ? value.trim()
+    : null;
+}