@expo-harmony/expo-modules-autolinking 55.0.25-harmony.1

package/src/harmony/transaction/stageProject.ts

@@ -0,0 +1,345 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import JSON5 from 'json5';
+
+import { RnohArtifacts, RnohCliPackage } from '../../config/constants';
+import { HarmonyAutolinkingError } from '../../errors';
+import { createManifest } from '../manifest/generate';
+import { normalizeLocalOhpmSpecifier } from '../ohpm/dependencies';
+import { canonicalizeOhpmManifest } from '../persistence/canonicalize';
+import {
+  isPathInside, pathExistsAsync, realpathExistingAsync, resolveInsideAsync,
+  resolvePackageFromProject, stringifyJson, sortedUniqueStrings,
+} from '../../utilities/values';
+
+async function findLocalOhpmDepsAsync(content, harmony) {
+  let dependencies;
+  try {
+    const parsed = JSON5.parse(content);
+    dependencies = parsed && typeof parsed.dependencies === 'object' && !Array.isArray(parsed.dependencies)
+      ? parsed.dependencies
+      : {};
+  } catch (_cause) {
+    return [];
+  }
+
+  const result = [];
+
+  for (const [name, specifier] of Object.entries(dependencies)) {
+    const relative = normalizeLocalOhpmSpecifier(specifier);
+    if (!relative) continue;
+
+    const harPath = path.resolve(harmony, relative);
+    if (!(await pathExistsAsync(harPath))) continue;
+
+    const marker = `${path.sep}node_modules${path.sep}`;
+    const markerIndex = harPath.lastIndexOf(marker);
+    if (markerIndex < 0) continue;
+
+    const rest = harPath.slice(markerIndex + marker.length).split(path.sep);
+    const packageSegments = rest[0]?.startsWith('@') ? rest.slice(0, 2) : rest.slice(0, 1);
+    if (packageSegments.length === 0 || packageSegments.some(segment => !segment)) continue;
+
+    const packageName = packageSegments.join('/');
+    const packageRoot = path.join(harPath.slice(0, markerIndex + marker.length), ...packageSegments);
+
+    try {
+      const packageJson = JSON.parse(await fs.promises.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+      if (packageJson.name !== packageName) continue;
+      result.push({
+        ohPackageName: name,
+        packageName,
+        packageRoot: await fs.promises.realpath(packageRoot),
+      });
+    } catch (_cause) {
+      // RNOH would not be able to preserve an unreadable package reference either.
+    }
+  }
+
+  return result;
+}
+
+async function findNodeModulesAsync(projectRoot) {
+  let directory = projectRoot;
+
+  while (true) {
+    const candidate = path.join(directory, 'node_modules');
+    if (await pathExistsAsync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) return path.join(projectRoot, 'node_modules');
+    directory = parent;
+  }
+}
+
+function buildRnohMetadata(descriptor) {
+  return {
+    ...(descriptor.rnoh.ohPackageName === undefined
+      ? {}
+      : {
+          ohPackageName: Array.isArray(descriptor.rnoh.ohPackageName)
+            ? descriptor.rnoh.ohPackageName.map(mapping => ({ ...mapping }))
+            : descriptor.rnoh.ohPackageName,
+        }),
+    mainHarPath: descriptor.rnoh.mainHarPath,
+    ...(descriptor.rnoh.etsPackageClassName
+      ? { etsPackageClassName: descriptor.rnoh.etsPackageClassName }
+      : {}),
+    ...(descriptor.rnoh.cppPackageClassName
+      ? { cppPackageClassName: descriptor.rnoh.cppPackageClassName }
+      : {}),
+    ...(descriptor.rnoh.cmakeLibraryTargetName
+      ? { cmakeLibraryTargetName: descriptor.rnoh.cmakeLibraryTargetName }
+      : {}),
+  };
+}
+
+async function stageCuratedPackageAsync(stage, descriptor) {
+  await fs.promises.mkdir(stage, { recursive: true });
+  await fs.promises.writeFile(path.join(stage, 'package.json'), stringifyJson({
+    name: descriptor.packageName,
+    version: descriptor.packageVersion,
+    ...(descriptor.rnoh.harPaths.length > 0
+      ? { harmony: { autolinking: buildRnohMetadata(descriptor) } }
+      : {}),
+  }));
+
+  const harPaths = sortedUniqueStrings([
+    ...descriptor.rnoh.harPaths,
+    ...(descriptor.arkTs ? [descriptor.arkTs.harPath] : []),
+  ]);
+
+  for (const harPath of harPaths) {
+    const source = await resolveInsideAsync(descriptor.packageRoot, harPath, 'descriptor HAR path', { packageName: descriptor.packageName, type: 'file' });
+    const destination = path.resolve(stage, ...harPath.split('/'));
+    if (!isPathInside(stage, destination)) {
+      throw new HarmonyAutolinkingError('PATH_OUTSIDE_PACKAGE', 'A curated HAR path escapes its staging package.', {
+        packageName: descriptor.packageName,
+        stage: 'staging',
+      });
+    }
+
+    await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+    await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_FICLONE);
+  }
+}
+
+async function updateOhpmManifestAsync(manifestPath, descriptors, options) {
+  let source;
+  try {
+    source = await fs.promises.readFile(manifestPath, 'utf8');
+  } catch (cause) {
+    throw new HarmonyAutolinkingError('INVALID_OPTIONS', 'Unable to read harmony/oh-package.json5.', {
+      cause,
+      stage: 'staging',
+    });
+  }
+  const manifest = createManifest(descriptors, { buildType: options.buildType });
+  const canonical = canonicalizeOhpmManifest(source, manifest, {
+    previousManagedOhpmPackageNames: options.previousManagedOhpmPackageNames,
+    harmonyProjectPath: options.harmonyProjectPath,
+    nodeModulesPath: options.nodeModulesPath,
+    stage: 'staging',
+  });
+
+  await fs.promises.writeFile(manifestPath, canonical.source);
+}
+
+async function stageProjectAsync(options) {
+  const projectRoot = await realpathExistingAsync(options.projectRoot, {
+    type: 'directory',
+    field: 'projectRoot',
+    stage: 'staging',
+  });
+
+  const harmony = await realpathExistingAsync(options.harmonyProjectPath, {
+    type: 'directory',
+    field: 'harmonyProjectPath',
+    stage: 'staging',
+  });
+
+  if (!isPathInside(projectRoot, harmony)) {
+    throw new HarmonyAutolinkingError('INVALID_OPTIONS', 'harmonyProjectPath must be inside projectRoot.', { stage: 'staging' });
+  }
+
+  const requested = options.nodeModulesPath || await findNodeModulesAsync(projectRoot);
+  const source = await realpathExistingAsync(requested, {
+    type: 'directory',
+    field: 'nodeModulesPath',
+    stage: 'staging',
+  });
+
+  const tmp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'expo-harmony-autolinking-'));
+  try {
+    const stageRoot = path.join(tmp, 'project');
+    const relative = path.relative(projectRoot, harmony);
+    const stageHarmony = path.join(stageRoot, relative);
+    const modules = path.join(stageRoot, 'node_modules');
+    await fs.promises.mkdir(stageHarmony, { recursive: true });
+    await fs.promises.writeFile(path.join(stageRoot, 'package.json'), stringifyJson({
+      name: 'expo-harmony-autolinking-stage',
+      private: true,
+    }));
+
+    let plugin = `${RnohCliPackage}/react-native.config.js`;
+    try {
+      const pkg = options.rnohCliPackageJsonPath
+        ? await fs.promises.realpath(options.rnohCliPackageJsonPath)
+        : resolvePackageFromProject(projectRoot, `${RnohCliPackage}/package.json`);
+      plugin = await fs.promises.realpath(path.join(path.dirname(pkg), 'react-native.config.js'));
+    } catch (_cause) {
+      // Preflight emits the actionable package/CLI diagnostic. Keeping the public
+      // package request here also lets callers inspect a stage without installing RNOH.
+    }
+
+    await fs.promises.writeFile(
+      path.join(stageRoot, 'react-native.config.js'),
+      `module.exports = require(${JSON.stringify(plugin)});\n`
+    );
+
+    const runtime = [];
+    if (options.modules === undefined) {
+      await fs.promises.symlink(source, modules, process.platform === 'win32' ? 'junction' : 'dir');
+    } else {
+      await fs.promises.mkdir(modules, { recursive: true });
+      const staged = options.modules.filter(descriptor => (
+        descriptor.rnoh.harPaths.length > 0 || descriptor.arkTs
+      ));
+
+      for (const descriptor of staged) {
+        const segments = descriptor.packageName.split('/');
+        const validName = segments.length === 1
+          ? segments[0] && !segments[0].startsWith('@')
+          : segments.length === 2 && segments[0].startsWith('@') && segments[0].length > 1 && segments[1];
+        if (!validName || segments.some(segment => segment === '.' || segment === '..' || segment.includes('\\'))) {
+          throw new HarmonyAutolinkingError('INVALID_METADATA', `Invalid npm package name for curated staging: ${descriptor.packageName}`, {
+            packageName: descriptor.packageName,
+            stage: 'staging',
+          });
+        }
+        const stage = path.join(modules, ...segments);
+        await fs.promises.mkdir(path.dirname(stage), { recursive: true });
+        await stageCuratedPackageAsync(stage, descriptor);
+      }
+
+      const actual = path.join(harmony, RnohArtifacts.ohPackage);
+      if (await pathExistsAsync(actual)) {
+        const content = await fs.promises.readFile(actual, 'utf8');
+        const previous = new Set(options.previousManagedOhpmPackageNames || []);
+        const verified = new Set(staged.map(item => item.packageName));
+
+        for (const dependency of await findLocalOhpmDepsAsync(content, harmony)) {
+          if (previous.has(dependency.ohPackageName)) continue;
+          if (verified.has(dependency.packageName)) continue;
+          const target = path.join(modules, ...dependency.packageName.split('/'));
+          if (!(await pathExistsAsync(target))) {
+            await fs.promises.mkdir(path.dirname(target), { recursive: true });
+            await fs.promises.symlink(
+              dependency.packageRoot,
+              target,
+              process.platform === 'win32' ? 'junction' : 'dir'
+            );
+          }
+          runtime.push(dependency.packageName);
+        }
+      }
+
+      try {
+        const packageName = '@react-native-community/cli';
+        const pkg = resolvePackageFromProject(projectRoot, `${packageName}/package.json`);
+        const packageRoot = await fs.promises.realpath(path.dirname(pkg));
+        const target = path.join(modules, ...packageName.split('/'));
+        if (!(await pathExistsAsync(target))) {
+          await fs.promises.mkdir(path.dirname(target), { recursive: true });
+          await fs.promises.symlink(packageRoot, target, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+        runtime.push(packageName);
+      } catch (_cause) {
+        // Explicit/fake executables need not install the React Native wrapper runtime.
+      }
+    }
+
+    for (const relativePath of Object.values(RnohArtifacts)) {
+      await fs.promises.mkdir(path.dirname(path.join(stageHarmony, relativePath)), { recursive: true });
+    }
+
+    const actual = path.join(harmony, RnohArtifacts.ohPackage);
+    const stage = path.join(stageHarmony, RnohArtifacts.ohPackage);
+    if (await pathExistsAsync(actual)) {
+      const stat = await fs.promises.lstat(actual);
+      if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new HarmonyAutolinkingError('INVALID_OPTIONS', 'harmony/oh-package.json5 must be a regular file.', { stage: 'staging' });
+      }
+      await fs.promises.copyFile(actual, stage);
+    } else {
+      await fs.promises.writeFile(stage, '{\n  dependencies: {}\n}\n');
+    }
+
+    if (options.modules !== undefined) {
+      await updateOhpmManifestAsync(stage, options.modules, {
+        buildType: options.buildType,
+        harmonyProjectPath: stageHarmony,
+        nodeModulesPath: modules,
+        previousManagedOhpmPackageNames: options.previousManagedOhpmPackageNames,
+      });
+    }
+
+    return {
+      projectRoot,
+      harmonyProjectPath: harmony,
+      sourceNodeModulesPath: source,
+      nodeModulesPath: modules,
+      rnohRuntimePackages: runtime,
+      temporaryRoot: tmp,
+      stageProjectRoot: stageRoot,
+      stageHarmonyProjectPath: stageHarmony,
+    };
+  } catch (cause) {
+    let warning;
+    try {
+      await fs.promises.rm(tmp, { recursive: true, force: true });
+    } catch (cleanupCause) {
+      warning = {
+        severity: 'warning',
+        code: 'ERR_EXPO_HARMONY_STAGING_CLEANUP_FAILED',
+        message: 'Unable to remove a partially-created Harmony autolinking staging directory.',
+        stage: 'cleanup',
+        details: { message: cleanupCause.message },
+      };
+    }
+
+    throw new HarmonyAutolinkingError(
+      typeof cause.code === 'string' ? cause.code : 'STAGING_FAILED',
+      cause.message || 'Unable to stage the Harmony project.',
+      {
+        cause,
+        stage: cause.stage || 'staging',
+        packageName: cause.packageName,
+        diagnostics: cause.diagnostics,
+        details: warning
+          ? { ...(cause.details || {}), cleanupWarning: warning }
+          : cause.details,
+      }
+    );
+  }
+}
+
+async function cleanupStagingProjectAsync(staging) {
+  try {
+    await fs.promises.rm(staging.temporaryRoot, { recursive: true, force: true });
+    return null;
+  } catch (cause) {
+    return {
+      severity: 'warning',
+      code: 'ERR_EXPO_HARMONY_STAGING_CLEANUP_FAILED',
+      message: 'Unable to remove the Harmony autolinking staging directory.',
+      stage: 'cleanup',
+      cause,
+    };
+  }
+}
+
+export {
+  cleanupStagingProjectAsync,
+  stageProjectAsync,
+};

package/src/metadata/descriptor.ts

@@ -0,0 +1,324 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import JSON5 from 'json5';
+
+import { HarmonyAutolinkingError } from '../errors';
+import type { BuildType, RnohMetadata } from '../types';
+import {
+  isValidOhpmPackageName,
+  normalizeHarmonyModuleMetadata,
+  normalizeRnohPackageMetadata,
+} from './schema';
+import { materializeModuleArtifactAsync } from '../harmony/materialize';
+import {
+  defaultCmakeTargetForNpmPackage, defaultOhPackageNameForNpmPackage,
+  ohPackageNameForHar,
+} from '../harmony/rnoh/packageMetadata';
+import {
+  compareText, isPathInside, isObject, normalizeSlashes, requireNonEmptyString,
+  resolveInsideAsync, sortedUniqueStrings,
+} from '../utilities/values';
+
+const HarScanIgnoredDirectories = new Set(['.git', 'build', 'node_modules', 'oh_modules']);
+const ArkTsLibraryManifestPath = 'harmony/library/oh-package.json5';
+const ArkTsLibraryHarPath = 'harmony/library.har';
+
+async function findHarPathsAsync(packageRoot, scanRoot, record): Promise<string[]> {
+  const harPaths: string[] = [];
+  const visited = new Set();
+
+  async function visit(directory) {
+    let real;
+    let entries;
+    try {
+      real = await fs.promises.realpath(directory);
+      entries = await fs.promises.readdir(directory, { withFileTypes: true });
+    } catch (cause) {
+      throw new HarmonyAutolinkingError('INVALID_METADATA', 'Unable to scan harmony.autolinking.mainHarPath.', {
+        cause,
+        packageName: record.packageName,
+        stage: 'metadata',
+      });
+    }
+
+    if (!isPathInside(packageRoot, real)) {
+      throw new HarmonyAutolinkingError('PATH_OUTSIDE_PACKAGE', 'harmony.autolinking.mainHarPath resolves outside package root.', { packageName: record.packageName, stage: 'metadata' });
+    }
+    if (visited.has(real)) return;
+    visited.add(real);
+
+    entries.sort((left, right) => compareText(left.name, right.name));
+    for (const entry of entries) {
+      const target = path.join(directory, entry.name);
+      let stat;
+      try {
+        stat = await fs.promises.lstat(target);
+      } catch (cause) {
+        throw new HarmonyAutolinkingError('INVALID_METADATA', 'A HAR scan entry is missing or unreadable.', {
+          cause,
+          packageName: record.packageName,
+          stage: 'metadata',
+        });
+      }
+
+      if (stat.isDirectory()) {
+        if (HarScanIgnoredDirectories.has(entry.name)) continue;
+        await visit(target);
+      } else if (path.extname(entry.name) === '.har') {
+        let realTarget;
+        try {
+          realTarget = await fs.promises.realpath(target);
+          if (!(await fs.promises.stat(realTarget)).isFile()) continue;
+        } catch (cause) {
+          throw new HarmonyAutolinkingError('INVALID_METADATA', 'A HAR scan entry is missing or unreadable.', {
+            cause,
+            packageName: record.packageName,
+            stage: 'metadata',
+          });
+        }
+
+        if (!isPathInside(packageRoot, realTarget)) {
+          throw new HarmonyAutolinkingError('PATH_OUTSIDE_PACKAGE', 'A HAR scan path resolves outside package root.', { packageName: record.packageName, stage: 'metadata' });
+        }
+
+        harPaths.push(normalizeSlashes(path.relative(packageRoot, target)));
+      }
+    }
+  }
+
+  await visit(scanRoot);
+
+  return sortedUniqueStrings(harPaths);
+}
+
+function resolveOhpmPackageName(raw, harPaths, record) {
+  const base = defaultOhPackageNameForNpmPackage(record.packageName);
+  const fallback = harPath => ({
+    harName: path.basename(harPath),
+    packageName: ohPackageNameForHar(base, harPath, harPaths.length),
+  });
+
+  if (raw === undefined) {
+    return harPaths.length === 1 ? base : harPaths.map(fallback);
+  }
+
+  if (typeof raw === 'string') {
+    return harPaths.length === 1
+      ? raw
+      : harPaths.map(harPath => ({
+          harName: path.basename(harPath),
+          packageName: ohPackageNameForHar(raw, harPath, harPaths.length),
+        }));
+  }
+
+  const harNames = new Set(harPaths.map(harPath => path.basename(harPath)));
+  const mappings = raw.map((mapping) => {
+    if (!harNames.has(mapping.harName)) {
+      throw new HarmonyAutolinkingError('INVALID_METADATA', `package.json#harmony.autolinking.ohPackageName mapping ${mapping.harName} does not match a discovered HAR.`, {
+        packageName: record.packageName,
+        stage: 'metadata',
+      });
+    }
+    return mapping;
+  });
+  const mapped = new Set(mappings.map(mapping => mapping.harName));
+  for (const harPath of harPaths) {
+    if (!mapped.has(path.basename(harPath))) mappings.push(fallback(harPath));
+  }
+
+  return mappings;
+}
+
+async function resolveArkTsModulePackageAsync(record, harmony) {
+  const hasHostExtensions = harmony.rootViewComponents.length > 0;
+  if (harmony.modules.length === 0 && !hasHostExtensions) return undefined;
+
+  const manifestPath = await resolveInsideAsync(
+    record.packageRoot,
+    ArkTsLibraryManifestPath,
+    'Harmony library OHPM manifest',
+    { packageName: record.packageName, type: 'file' }
+  );
+  let manifest;
+  try {
+    manifest = JSON5.parse(await fs.promises.readFile(manifestPath, 'utf8'));
+  } catch (cause) {
+    throw new HarmonyAutolinkingError(
+      'INVALID_METADATA',
+      `${ArkTsLibraryManifestPath} must contain valid JSON5.`,
+      { cause, packageName: record.packageName, stage: 'metadata' }
+    );
+  }
+  if (!isObject(manifest) || !isValidOhpmPackageName(manifest.name)) {
+    throw new HarmonyAutolinkingError(
+      'INVALID_METADATA',
+      `${ArkTsLibraryManifestPath} must declare a valid OHPM package name.`,
+      { packageName: record.packageName, stage: 'metadata' }
+    );
+  }
+  return {
+    harPath: ArkTsLibraryHarPath,
+    ohPackageName: manifest.name,
+  };
+}
+
+function normalizeExpoMetadata(record, canonical) {
+  if (!record.supportsHarmony) return {
+    rootViewComponents: [],
+  };
+
+  return {
+    rootViewComponents: canonical.rootViewComponents,
+  };
+}
+
+async function normalizeRnohMetadataAsync(record) {
+  if (record.rnohMetadata == null) {
+    return {
+      ohPackageName: undefined,
+      mainHarPath: undefined,
+      harPaths: [],
+      etsPackageClassName: undefined,
+      cppPackageClassName: undefined,
+      cmakeLibraryTargetName: undefined,
+    };
+  }
+
+  const metadata = normalizeRnohPackageMetadata(record.rnohMetadata, {
+    packageName: record.packageName,
+    packageVersion: record.packageVersion,
+  });
+
+  let main;
+  if (metadata.mainHarPath !== undefined) {
+    main = metadata.mainHarPath;
+  } else {
+    try {
+      const harmonyStat = await fs.promises.stat(path.join(record.packageRoot, 'harmony'));
+      main = harmonyStat.isDirectory() ? 'harmony' : '.';
+    } catch (_cause) {
+      main = '.';
+    }
+  }
+
+  const scanRoot = await resolveInsideAsync(
+    record.packageRoot,
+    main,
+    'harmony.autolinking.mainHarPath',
+    { packageName: record.packageName, type: 'directory' }
+  );
+  main = normalizeSlashes(path.relative(record.packageRoot, scanRoot)) || '.';
+
+  const harPaths = await findHarPathsAsync(record.packageRoot, scanRoot, record);
+  if (harPaths.length === 0) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', 'harmony.autolinking.mainHarPath does not contain a HAR file.', {
+      packageName: record.packageName,
+      stage: 'metadata',
+    });
+  }
+
+  const harBasenames = harPaths.map(harPath => path.basename(harPath));
+  if (new Set(harBasenames).size !== harBasenames.length) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', 'harmony.autolinking.mainHarPath contains duplicate HAR filenames.', {
+      packageName: record.packageName,
+      stage: 'metadata',
+    });
+  }
+
+  const name = resolveOhpmPackageName(metadata.ohPackageName, harPaths, record);
+  if (Array.isArray(name)) {
+    const order = new Map(name.map((mapping, index) => [mapping.harName, index]));
+    harPaths.sort((left, right) => {
+      return order.get(path.basename(left)) - order.get(path.basename(right));
+    });
+  }
+
+  const rnoh: RnohMetadata = {
+    ohPackageName: name,
+    mainHarPath: main,
+    harPaths,
+    etsPackageClassName: metadata.etsPackageClassName,
+    etsPackageImport: metadata.etsPackageImport,
+    cppPackageClassName: metadata.cppPackageClassName,
+    cmakeLibraryTargetName: metadata.cmakeLibraryTargetName
+      || defaultCmakeTargetForNpmPackage(record.packageName),
+  };
+
+  return rnoh;
+}
+
+function assertSearchRecord(record) {
+  if (!isObject(record)) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', 'Search record must be an object.', {
+      stage: 'metadata',
+    });
+  }
+
+  for (const field of ['packageName', 'packageVersion', 'packageRoot', 'source']) {
+    requireNonEmptyString(record[field], field, { packageName: record.packageName });
+  }
+}
+
+async function createDescriptorFromSearchRecordAsync(record, buildType: BuildType = 'debug') {
+  assertSearchRecord(record);
+
+  let packageRoot;
+  try {
+    packageRoot = await fs.promises.realpath(record.packageRoot);
+    if (!(await fs.promises.stat(packageRoot)).isDirectory()) throw new TypeError('not a directory');
+  } catch (cause) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `${record.packageName} packageRoot is not an existing directory.`, {
+      cause,
+      packageName: record.packageName,
+      stage: 'metadata',
+    });
+  }
+
+  const base = { ...record, packageRoot };
+  let link = packageRoot;
+  if (typeof record.revision?.originPath === 'string') {
+    const candidate = path.resolve(record.revision.originPath);
+    try {
+      if (await fs.promises.realpath(candidate) === packageRoot) link = candidate;
+    } catch (_cause) {
+      // The canonical package root remains the safe fallback for direct callers.
+    }
+  }
+
+  const expoConfig = isObject(base.expoModuleConfig) ? base.expoModuleConfig : null;
+  const harmony = normalizeHarmonyModuleMetadata(
+    expoConfig?.harmony,
+    { packageName: record.packageName, packageVersion: record.packageVersion }
+  );
+  const arkTs = await resolveArkTsModulePackageAsync(base, harmony);
+  const rnoh = await normalizeRnohMetadataAsync(base);
+  const expo = normalizeExpoMetadata(base, harmony);
+  const artifact = await materializeModuleArtifactAsync({
+    packageName: record.packageName,
+    packageRoot,
+    source: record.source,
+    buildType,
+    arkTs,
+    rnoh,
+  });
+
+  const descriptor = {
+    packageName: record.packageName,
+    packageVersion: record.packageVersion,
+    packageRoot,
+    packageLinkPath: link,
+    source: record.source,
+    expo,
+    rnoh,
+    harmony,
+    ...(arkTs ? { arkTs } : {}),
+    artifact,
+  };
+
+  return descriptor;
+}
+
+export {
+  createDescriptorFromSearchRecordAsync,
+};