@expo-harmony/expo-modules-autolinking 55.0.25-harmony.4 → 55.0.25-harmony.5

package/build/runtime.d.ts

@@ -7,7 +7,7 @@ export interface HarmonyNativeModule {
     artifacts: string[];
 }
 export interface HarmonyRuntimeContract {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
     platform: 'harmony';
     runtimeVersion: string;
     development: boolean;
@@ -22,8 +22,9 @@ export interface HarmonyRuntimeContract {
     modules: HarmonyNativeModule[];
     config: {
         nativeCompiler: string;
-        targetApiVersion: number;
-        compatibleApiVersion: number;
+        targetApiVersion: number | string;
+        compatibleApiVersion: number | string;
+        nativeLibFilterHash?: string;
         permissions: string[];
         querySchemes: string[];
         backgroundModes: string[];
@@ -40,6 +41,7 @@ export declare class HarmonyCompatibilityError extends Error {
     readonly code = "ERR_HARMONY_INCOMPATIBLE";
     constructor(issues: HarmonyCompatibilityIssue[]);
 }
+export declare function harmonyRuntimeSchemaVersion(config: HarmonyRuntimeContract['config']): 1 | 2;
 export declare function validateHarmonyRuntime(value: unknown): HarmonyCompatibilityIssue[];
 export declare function checkHarmonyCompatibility(client: unknown, requirements: unknown): HarmonyCompatibilityIssue[];
 export declare function assertHarmonyCompatibility(client: unknown, requirements: unknown): asserts requirements is HarmonyRuntimeContract;

package/build/runtime.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HarmonyCompatibilityError = void 0;
+exports.harmonyRuntimeSchemaVersion = harmonyRuntimeSchemaVersion;
 exports.validateHarmonyRuntime = validateHarmonyRuntime;
 exports.checkHarmonyCompatibility = checkHarmonyCompatibility;
 exports.assertHarmonyCompatibility = assertHarmonyCompatibility;
@@ -27,11 +28,37 @@ function strings(value) {
 }
 const Versions = ['runtimeVersion', 'expo', 'expoModulesCore', 'rnoh', 'react', 'hermes'];
 const Settings = ['permissions', 'querySchemes', 'backgroundModes', 'abiFilters'];
+function apiVersion(value, schema) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 13 && value < 26)
+        return [value, 0, 0];
+    if (schema === 2 && typeof value === 'string' && /^(?:[1-9]\d{1,2})\.(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d{0,2})$/.test(value)) {
+        const parts = value.split('.').map(Number);
+        if (parts[0] >= 26)
+            return parts;
+    }
+    return undefined;
+}
+function compareApiVersions(left, right) {
+    for (let index = 0; index < 3; index++) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return 0;
+}
+function harmonyRuntimeSchemaVersion(config) {
+    return typeof config.targetApiVersion === 'string' || typeof config.compatibleApiVersion === 'string'
+        || config.nativeLibFilterHash !== undefined
+        ? 2
+        : 1;
+}
 function validateHarmonyRuntime(value) {
     if (!record(value))
         return [{ code: 'INVALID_CONTRACT', field: '', message: 'Runtime contract must be an object.' }];
     const issues = [];
-    for (const [field, expected] of Object.entries({ schemaVersion: 1, platform: 'harmony', engine: 'hermes-v1', bundleFormat: 'js-source', renderer: 'rnoh' })) {
+    if (value.schemaVersion !== 1 && value.schemaVersion !== 2) {
+        issues.push({ code: 'INVALID_CONTRACT', field: 'schemaVersion', message: 'schemaVersion must be 1 or 2.' });
+    }
+    for (const [field, expected] of Object.entries({ platform: 'harmony', engine: 'hermes-v1', bundleFormat: 'js-source', renderer: 'rnoh' })) {
         if (value[field] !== expected) {
             issues.push({ code: field === 'platform' ? 'PLATFORM_MISMATCH' : 'INVALID_CONTRACT', field, message: `${field} must be ${expected}.` });
         }
@@ -62,10 +89,12 @@ function validateHarmonyRuntime(value) {
         }
     }
     const config = value.config;
+    const target = record(config) ? apiVersion(config.targetApiVersion, value.schemaVersion) : undefined;
+    const compatible = record(config) ? apiVersion(config.compatibleApiVersion, value.schemaVersion) : undefined;
     if (!record(config) || !token(config.nativeCompiler) || !Settings.every(field => strings(config[field]))
-        || !Number.isInteger(config.targetApiVersion) || Number(config.targetApiVersion) < 13
-        || !Number.isInteger(config.compatibleApiVersion) || Number(config.compatibleApiVersion) < 13
-        || Number(config.compatibleApiVersion) > Number(config.targetApiVersion)
+        || !target || !compatible || compareApiVersions(compatible, target) > 0
+        || (config.nativeLibFilterHash !== undefined && (value.schemaVersion !== 2
+            || typeof config.nativeLibFilterHash !== 'string' || !/^[a-f0-9]{64}$/.test(config.nativeLibFilterHash)))
         || (Array.isArray(config.abiFilters) && config.abiFilters.length === 0)) {
         issues.push({ code: 'INVALID_CONTRACT', field: 'config', message: 'Invalid native build configuration.' });
     }
@@ -103,7 +132,7 @@ function checkHarmonyCompatibility(client, requirements) {
             issues.push({ code: 'NATIVE_MODULE_MISMATCH', field: module.packageName, message: `Native contract differs for ${module.packageName}. Rebuild or select a matching client.` });
         }
     }
-    for (const field of ['nativeCompiler', 'targetApiVersion', 'compatibleApiVersion']) {
+    for (const field of ['nativeCompiler', 'targetApiVersion', 'compatibleApiVersion', 'nativeLibFilterHash']) {
         if (available.config[field] !== required.config[field]) {
             issues.push({ code: 'CONFIG_MISMATCH', field, message: `${field}: project requires ${required.config[field]}, client provides ${available.config[field]}.` });
         }

package/build/src/harmony/materialize.js

@@ -43,6 +43,7 @@ const path = __importStar(require("node:path"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const json5_1 = __importDefault(require("json5"));
 const dependencies_1 = require("./ohpm/dependencies");
+const mirror_1 = require("./ohpm/mirror");
 const toolCommand_1 = require("../utilities/toolCommand");
 const terminateProcess_1 = require("../utilities/terminateProcess");
 const errors_1 = require("../errors");
@@ -256,22 +257,25 @@ async function materializeLocalSourceAsync(options) {
         throw new errors_1.HarmonyAutolinkingError('INVALID_OPTIONS', `${module.packageName} is not a nativeModulesDir local-source module.`, { packageName: module.packageName, stage: 'artifact-materialize' });
     }
     const artifact = module.artifact;
-    const projectRoot = await fs.promises.realpath(options.projectRoot);
-    const packageRoot = await fs.promises.realpath(module.packageRoot);
-    if (!(0, values_1.isPathInside)(projectRoot, packageRoot)) {
+    const project = await fs.promises.realpath(options.projectRoot);
+    const root = await fs.promises.realpath(module.packageRoot);
+    if (!(0, values_1.isPathInside)(project, root)) {
         throw new errors_1.HarmonyAutolinkingError('UNSAFE_SOURCE_ARTIFACT', 'Harmony local modules must live inside the application project root.', { packageName: module.packageName, stage: 'artifact-materialize' });
     }
     if (!module.arkTs) {
         throw new errors_1.HarmonyAutolinkingError('INVALID_METADATA', `${module.packageName} local-source descriptor has no derived ArkTS package.`, { packageName: module.packageName, stage: 'artifact-materialize' });
     }
-    const harPath = await (0, values_1.resolveInsideAsync)(packageRoot, module.arkTs.harPath, 'Harmony materialized HAR path', { packageName: module.packageName, mustExist: false });
+    const har = await (0, values_1.resolveInsideAsync)(root, module.arkTs.harPath, 'Harmony materialized HAR path', { packageName: module.packageName, mustExist: false });
     const file = path.join(artifact.build.cwd, 'oh-package.json5');
     const original = await fs.promises.readFile(file, 'utf8');
     const config = json5_1.default.parse(original);
     const dependencies = (options.dependencies ?? []).filter(value => value.artifact.kind === 'bundled');
-    const overrides = Object.fromEntries((0, dependencies_1.collectOhpmDeps)(dependencies).map(({ descriptor, mapping }) => [
-        mapping.ohPackageName, (0, dependencies_1.resolveOhpmSpecifier)(descriptor, mapping, { harmonyProjectPath: artifact.build.cwd }),
-    ]));
+    const overrides = {};
+    const mirror = { ...process.env, ...options.env }.EXPO_HARMONY_CHECK_MIRROR_ROOT;
+    for (const { descriptor, mapping } of (0, dependencies_1.collectOhpmDeps)(dependencies)) {
+        const link = await (0, mirror_1.mirrorPackageLinkAsync)(descriptor.packageLinkPath, artifact.build.cwd, mirror);
+        overrides[mapping.ohPackageName] = (0, dependencies_1.resolveOhpmSpecifier)({ ...descriptor, packageLinkPath: link }, mapping, { harmonyProjectPath: artifact.build.cwd });
+    }
     try {
         await fs.promises.writeFile(file, JSON.stringify({ ...config, overrides: { ...config.overrides, ...overrides } }, null, 2) + '\n');
         for (const step of fixedLocalSourceBuildSteps(artifact.build)) {
@@ -283,19 +287,19 @@ async function materializeLocalSourceAsync(options) {
     }
     const ready = await isNonEmptyRegularHarAsync(artifact.outputPath, artifact.build.cwd, module.packageName);
     if (!ready) {
-        throw new errors_1.HarmonyAutolinkingError('SOURCE_BUILD_FAILED', `Hvigor did not produce a non-empty HAR at ${(0, values_1.normalizeSlashes)(path.relative(packageRoot, artifact.outputPath))}.`, { packageName: module.packageName, stage: 'artifact-materialize' });
+        throw new errors_1.HarmonyAutolinkingError('SOURCE_BUILD_FAILED', `Hvigor did not produce a non-empty HAR at ${(0, values_1.normalizeSlashes)(path.relative(root, artifact.outputPath))}.`, { packageName: module.packageName, stage: 'artifact-materialize' });
     }
     await (0, publish_1.publishArtifactsAsync)({
-        allowedRoot: projectRoot,
-        lockPath: path.join(projectRoot, '.expo/harmony/module-materialize.lock'),
-        files: [{ source: artifact.outputPath, target: harPath }],
+        allowedRoot: project,
+        lockPath: path.join(project, '.expo/harmony/module-materialize.lock'),
+        files: [{ source: artifact.outputPath, target: har }],
     });
-    if (!await isNonEmptyRegularHarAsync(harPath, packageRoot, module.packageName)) {
+    if (!await isNonEmptyRegularHarAsync(har, root, module.packageName)) {
         throw new errors_1.HarmonyAutolinkingError('SOURCE_BUILD_FAILED', 'Harmony HAR materialization produced a missing or empty file.', { packageName: module.packageName, stage: 'artifact-materialize' });
     }
     return {
         packageName: module.packageName,
-        harPath,
+        harPath: har,
     };
 }
 async function materializeLocalSourcesAsync(modules, options) {

package/build/src/harmony/ohpm/mirror.d.ts

@@ -0,0 +1 @@
+export declare function mirrorPackageLinkAsync(link: string, project: string, root?: string): Promise<string>;

package/build/src/harmony/ohpm/mirror.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mirrorPackageLinkAsync = mirrorPackageLinkAsync;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../../errors");
+const values_1 = require("../../utilities/values");
+async function mirrorPackageLinkAsync(link, project, root) {
+    if (!root)
+        return link;
+    const mirror = await promises_1.default.realpath(root);
+    const roots = [node_path_1.default.resolve(root, 'filesystem'), node_path_1.default.join(mirror, 'filesystem')];
+    if (!roots.some(root => (0, values_1.isPathInside)(root, project))
+        || roots.some(root => (0, values_1.isPathInside)(root, link)))
+        return link;
+    const source = node_path_1.default.resolve(link);
+    const parsed = node_path_1.default.parse(source);
+    const volume = parsed.root.replace(/[^A-Za-z0-9]+/gu, '') || 'root';
+    const target = node_path_1.default.join(mirror, 'filesystem', volume, source.slice(parsed.root.length));
+    let existing;
+    try {
+        existing = await promises_1.default.realpath(target);
+    }
+    catch (cause) {
+        if (cause.code !== 'ENOENT') {
+            throw new errors_1.HarmonyAutolinkingError('MIRROR_PATH_FAILED', `Cannot inspect the isolated dependency path: ${target}`, { cause, stage: 'artifact-materialize' });
+        }
+    }
+    if (existing !== undefined) {
+        if (existing !== await promises_1.default.realpath(source)) {
+            throw new errors_1.HarmonyAutolinkingError('UNSAFE_MIRROR_PATH', `The isolated dependency path conflicts with an existing file or link: ${target}`, { stage: 'artifact-materialize' });
+        }
+        return target;
+    }
+    // Do not create directories through a copied symlink into the original project.
+    let directory = mirror;
+    for (const segment of node_path_1.default.relative(mirror, node_path_1.default.dirname(target)).split(node_path_1.default.sep)) {
+        directory = node_path_1.default.join(directory, segment);
+        try {
+            await promises_1.default.mkdir(directory);
+        }
+        catch (cause) {
+            if (cause.code !== 'EEXIST') {
+                throw new errors_1.HarmonyAutolinkingError('MIRROR_PATH_FAILED', `Cannot create the isolated dependency directory: ${directory}`, { cause, stage: 'artifact-materialize' });
+            }
+            if (!(await promises_1.default.lstat(directory)).isDirectory()) {
+                throw new errors_1.HarmonyAutolinkingError('UNSAFE_MIRROR_PATH', `The isolated dependency path conflicts with an existing file or link: ${directory}`, { cause, stage: 'artifact-materialize' });
+            }
+        }
+    }
+    await promises_1.default.symlink(source, target, process.platform === 'win32' ? 'junction' : 'dir');
+    return target;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/expo-modules-autolinking",
-  "version": "55.0.25-harmony.4",
+  "version": "55.0.25-harmony.5",
   "description": "HarmonyOS port of expo-modules-autolinking",
   "keywords": [
     "react-native",

package/runtime.ts

@@ -8,7 +8,7 @@ export interface HarmonyNativeModule {
 }
 
 export interface HarmonyRuntimeContract {
-  schemaVersion: 1;
+  schemaVersion: 1 | 2;
   platform: 'harmony';
   runtimeVersion: string;
   development: boolean;
@@ -23,8 +23,9 @@ export interface HarmonyRuntimeContract {
   modules: HarmonyNativeModule[];
   config: {
     nativeCompiler: string;
-    targetApiVersion: number;
-    compatibleApiVersion: number;
+    targetApiVersion: number | string;
+    compatibleApiVersion: number | string;
+    nativeLibFilterHash?: string;
     permissions: string[];
     querySchemes: string[];
     backgroundModes: string[];
@@ -64,11 +65,40 @@ function strings(value: unknown): value is string[] {
 const Versions = ['runtimeVersion', 'expo', 'expoModulesCore', 'rnoh', 'react', 'hermes'] as const;
 const Settings = ['permissions', 'querySchemes', 'backgroundModes', 'abiFilters'] as const;
 
+function apiVersion(value: unknown, schema: unknown): number[] | undefined {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 13 && value < 26) return [value, 0, 0];
+  if (schema === 2 && typeof value === 'string' && /^(?:[1-9]\d{1,2})\.(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d{0,2})$/.test(value)) {
+    const parts = value.split('.').map(Number);
+    if (parts[0] >= 26) return parts;
+  }
+
+  return undefined;
+}
+
+function compareApiVersions(left: number[], right: number[]): number {
+  for (let index = 0; index < 3; index++) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+
+  return 0;
+}
+
+export function harmonyRuntimeSchemaVersion(config: HarmonyRuntimeContract['config']): 1 | 2 {
+  return typeof config.targetApiVersion === 'string' || typeof config.compatibleApiVersion === 'string'
+    || config.nativeLibFilterHash !== undefined
+    ? 2
+    : 1;
+}
+
 export function validateHarmonyRuntime(value: unknown): HarmonyCompatibilityIssue[] {
   if (!record(value)) return [{ code: 'INVALID_CONTRACT', field: '', message: 'Runtime contract must be an object.' }];
 
   const issues: HarmonyCompatibilityIssue[] = [];
-  for (const [field, expected] of Object.entries({ schemaVersion: 1, platform: 'harmony', engine: 'hermes-v1', bundleFormat: 'js-source', renderer: 'rnoh' })) {
+  if (value.schemaVersion !== 1 && value.schemaVersion !== 2) {
+    issues.push({ code: 'INVALID_CONTRACT', field: 'schemaVersion', message: 'schemaVersion must be 1 or 2.' });
+  }
+
+  for (const [field, expected] of Object.entries({ platform: 'harmony', engine: 'hermes-v1', bundleFormat: 'js-source', renderer: 'rnoh' })) {
     if (value[field] !== expected) {
       issues.push({ code: field === 'platform' ? 'PLATFORM_MISMATCH' : 'INVALID_CONTRACT', field, message: `${field} must be ${expected}.` });
     }
@@ -101,10 +131,13 @@ export function validateHarmonyRuntime(value: unknown): HarmonyCompatibilityIssu
   }
 
   const config = value.config;
+  const target = record(config) ? apiVersion(config.targetApiVersion, value.schemaVersion) : undefined;
+  const compatible = record(config) ? apiVersion(config.compatibleApiVersion, value.schemaVersion) : undefined;
+
   if (!record(config) || !token(config.nativeCompiler) || !Settings.every(field => strings(config[field]))
-    || !Number.isInteger(config.targetApiVersion) || Number(config.targetApiVersion) < 13
-    || !Number.isInteger(config.compatibleApiVersion) || Number(config.compatibleApiVersion) < 13
-    || Number(config.compatibleApiVersion) > Number(config.targetApiVersion)
+    || !target || !compatible || compareApiVersions(compatible, target) > 0
+    || (config.nativeLibFilterHash !== undefined && (value.schemaVersion !== 2
+      || typeof config.nativeLibFilterHash !== 'string' || !/^[a-f0-9]{64}$/.test(config.nativeLibFilterHash)))
     || (Array.isArray(config.abiFilters) && config.abiFilters.length === 0)) {
     issues.push({ code: 'INVALID_CONTRACT', field: 'config', message: 'Invalid native build configuration.' });
   }
@@ -150,7 +183,7 @@ export function checkHarmonyCompatibility(client: unknown, requirements: unknown
     }
   }
 
-  for (const field of ['nativeCompiler', 'targetApiVersion', 'compatibleApiVersion'] as const) {
+  for (const field of ['nativeCompiler', 'targetApiVersion', 'compatibleApiVersion', 'nativeLibFilterHash'] as const) {
     if (available.config[field] !== required.config[field]) {
       issues.push({ code: 'CONFIG_MISMATCH', field, message: `${field}: project requires ${required.config[field]}, client provides ${available.config[field]}.` });
     }

package/src/harmony/materialize.ts

@@ -3,6 +3,7 @@ import * as path from 'node:path';
 import spawn from 'cross-spawn';
 import JSON5 from 'json5';
 import { collectOhpmDeps, resolveOhpmSpecifier } from './ohpm/dependencies';
+import { mirrorPackageLinkAsync } from './ohpm/mirror';
 import { resolveHarmonyCommand } from '../utilities/toolCommand';
 import { terminateProcess } from '../utilities/terminateProcess';
 
@@ -314,6 +315,7 @@ async function materializeLocalSourceAsync(
   options: MaterializeLocalSourceOptions
 ): Promise<MaterializedLocalSource> {
   const module = options.module;
+
   if (module.source !== 'nativeModulesDir' || module.artifact.kind !== 'local-source') {
     throw new HarmonyAutolinkingError(
       'INVALID_OPTIONS',
@@ -323,9 +325,10 @@ async function materializeLocalSourceAsync(
   }
 
   const artifact = module.artifact;
-  const projectRoot = await fs.promises.realpath(options.projectRoot);
-  const packageRoot = await fs.promises.realpath(module.packageRoot);
-  if (!isPathInside(projectRoot, packageRoot)) {
+  const project = await fs.promises.realpath(options.projectRoot);
+  const root = await fs.promises.realpath(module.packageRoot);
+
+  if (!isPathInside(project, root)) {
     throw new HarmonyAutolinkingError(
       'UNSAFE_SOURCE_ARTIFACT',
       'Harmony local modules must live inside the application project root.',
@@ -340,8 +343,8 @@ async function materializeLocalSourceAsync(
     );
   }
 
-  const harPath = await resolveInsideAsync(
-    packageRoot,
+  const har = await resolveInsideAsync(
+    root,
     module.arkTs.harPath,
     'Harmony materialized HAR path',
     { packageName: module.packageName, mustExist: false }
@@ -351,12 +354,20 @@ async function materializeLocalSourceAsync(
   const original = await fs.promises.readFile(file, 'utf8');
   const config = JSON5.parse(original);
   const dependencies = (options.dependencies ?? []).filter(value => value.artifact.kind === 'bundled');
-  const overrides = Object.fromEntries(collectOhpmDeps(dependencies).map(({ descriptor, mapping }) => [
-    mapping.ohPackageName, resolveOhpmSpecifier(descriptor, mapping, { harmonyProjectPath: artifact.build.cwd }),
-  ]));
+  const overrides: Record<string, string> = {};
+  const mirror = { ...process.env, ...options.env }.EXPO_HARMONY_CHECK_MIRROR_ROOT;
+
+  for (const { descriptor, mapping } of collectOhpmDeps(dependencies)) {
+    const link = await mirrorPackageLinkAsync(descriptor.packageLinkPath, artifact.build.cwd, mirror);
+
+    overrides[mapping.ohPackageName] = resolveOhpmSpecifier(
+      { ...descriptor, packageLinkPath: link }, mapping, { harmonyProjectPath: artifact.build.cwd }
+    );
+  }
 
   try {
     await fs.promises.writeFile(file, JSON.stringify({ ...config, overrides: { ...config.overrides, ...overrides } }, null, 2) + '\n');
+
     for (const step of fixedLocalSourceBuildSteps(artifact.build)) {
       await runFixedBuildStepAsync(step, module.packageName, options);
     }
@@ -369,20 +380,22 @@ async function materializeLocalSourceAsync(
     artifact.build.cwd,
     module.packageName
   );
+
   if (!ready) {
     throw new HarmonyAutolinkingError(
       'SOURCE_BUILD_FAILED',
-      `Hvigor did not produce a non-empty HAR at ${normalizeSlashes(path.relative(packageRoot, artifact.outputPath))}.`,
+      `Hvigor did not produce a non-empty HAR at ${normalizeSlashes(path.relative(root, artifact.outputPath))}.`,
       { packageName: module.packageName, stage: 'artifact-materialize' }
     );
   }
 
   await publishArtifactsAsync({
-    allowedRoot: projectRoot,
-    lockPath: path.join(projectRoot, '.expo/harmony/module-materialize.lock'),
-    files: [{ source: artifact.outputPath, target: harPath }],
+    allowedRoot: project,
+    lockPath: path.join(project, '.expo/harmony/module-materialize.lock'),
+    files: [{ source: artifact.outputPath, target: har }],
   });
-  if (!await isNonEmptyRegularHarAsync(harPath, packageRoot, module.packageName)) {
+
+  if (!await isNonEmptyRegularHarAsync(har, root, module.packageName)) {
     throw new HarmonyAutolinkingError(
       'SOURCE_BUILD_FAILED',
       'Harmony HAR materialization produced a missing or empty file.',
@@ -392,7 +405,7 @@ async function materializeLocalSourceAsync(
 
   return {
     packageName: module.packageName,
-    harPath,
+    harPath: har,
   };
 }
 

package/src/harmony/ohpm/mirror.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { HarmonyAutolinkingError } from '../../errors';
+import { isPathInside } from '../../utilities/values';
+
+export async function mirrorPackageLinkAsync(
+  link: string,
+  project: string,
+  root?: string
+): Promise<string> {
+  if (!root) return link;
+
+  const mirror = await fs.realpath(root);
+  const roots = [path.resolve(root, 'filesystem'), path.join(mirror, 'filesystem')];
+
+  if (!roots.some(root => isPathInside(root, project))
+    || roots.some(root => isPathInside(root, link))) return link;
+
+  const source = path.resolve(link);
+  const parsed = path.parse(source);
+  const volume = parsed.root.replace(/[^A-Za-z0-9]+/gu, '') || 'root';
+  const target = path.join(mirror, 'filesystem', volume, source.slice(parsed.root.length));
+  let existing: string | undefined;
+
+  try {
+    existing = await fs.realpath(target);
+  } catch (cause) {
+    if (cause.code !== 'ENOENT') {
+      throw new HarmonyAutolinkingError(
+        'MIRROR_PATH_FAILED',
+        `Cannot inspect the isolated dependency path: ${target}`,
+        { cause, stage: 'artifact-materialize' }
+      );
+    }
+  }
+
+  if (existing !== undefined) {
+    if (existing !== await fs.realpath(source)) {
+      throw new HarmonyAutolinkingError(
+        'UNSAFE_MIRROR_PATH',
+        `The isolated dependency path conflicts with an existing file or link: ${target}`,
+        { stage: 'artifact-materialize' }
+      );
+    }
+
+    return target;
+  }
+
+  // Do not create directories through a copied symlink into the original project.
+  let directory = mirror;
+
+  for (const segment of path.relative(mirror, path.dirname(target)).split(path.sep)) {
+    directory = path.join(directory, segment);
+
+    try {
+      await fs.mkdir(directory);
+    } catch (cause) {
+      if (cause.code !== 'EEXIST') {
+        throw new HarmonyAutolinkingError(
+          'MIRROR_PATH_FAILED',
+          `Cannot create the isolated dependency directory: ${directory}`,
+          { cause, stage: 'artifact-materialize' }
+        );
+      }
+
+      if (!(await fs.lstat(directory)).isDirectory()) {
+        throw new HarmonyAutolinkingError(
+          'UNSAFE_MIRROR_PATH',
+          `The isolated dependency path conflicts with an existing file or link: ${directory}`,
+          { cause, stage: 'artifact-materialize' }
+        );
+      }
+    }
+  }
+
+  await fs.symlink(source, target, process.platform === 'win32' ? 'junction' : 'dir');
+
+  return target;
+}