@expo-harmony/config-plugins 55.0.10-harmony.2 → 55.0.10-harmony.3

package/build/paths.d.ts

@@ -3,7 +3,6 @@ export interface HarmonyManagedPaths {
     readonly projectBuildProfile: string;
     readonly rootOhPackage: string;
     readonly rootHvigor: string;
-    readonly nativeInputsStamp: string;
     readonly hvigorConfig: string;
     readonly entryBuildProfile: string;
     readonly entryOhPackage: string;
@@ -45,18 +44,21 @@ export interface HarmonyPathsApi {
     readonly RESOURCE_PATHS: HarmonyResourcePaths;
     assertNoExternalSymlink(root: string, target: string): Promise<void>;
     isInside(root: string, target: string): boolean;
-    resolveHarmonyPath(platformProjectRoot: string, relativePath: string): Promise<string>;
-    resolveProjectPath(projectRoot: string, modName: keyof HarmonyProjectPaths): Promise<string>;
-    toPosixRelative(projectRoot: string, target: string): string;
+    resolveHarmonyPath(directory: string, relative: string): Promise<string>;
+    resolveProjectPath(root: string, name: keyof HarmonyProjectPaths): Promise<string>;
+    toPosixRelative(root: string, target: string): string;
 }
-declare const ManagedPaths: HarmonyManagedPaths;
+declare const ManagedPaths: HarmonyManagedPaths & {
+    readonly nativeInputsStamp: string;
+};
 declare const ProjectPaths: HarmonyProjectPaths;
 declare const ProjectPathCandidates: HarmonyProjectPathCandidates;
 declare const ResourcePaths: HarmonyResourcePaths;
 export declare function isInside(root: string, target: string): boolean;
 export declare function assertNoExternalSymlink(root: string, target: string): Promise<void>;
-export declare function resolveHarmonyPath(platformProjectRoot: string, relativePath: string): Promise<string>;
-export declare function resolveProjectPath(projectRoot: string, modName: keyof HarmonyProjectPaths): Promise<string>;
-export declare function toPosixRelative(projectRoot: string, target: string): string;
-export declare const HarmonyPaths: HarmonyPathsApi;
-export { ManagedPaths, ProjectPathCandidates, ProjectPaths, ResourcePaths };
+export declare function resolveHarmonyPath(directory: string, relative: string): Promise<string>;
+export declare function resolveProjectPath(root: string, name: keyof HarmonyProjectPaths): Promise<string>;
+export declare function toPosixRelative(root: string, target: string): string;
+declare const NativeInputsStampPath: string;
+export declare const HarmonyPaths: Readonly<HarmonyPathsApi>;
+export { ManagedPaths, NativeInputsStampPath, ProjectPathCandidates, ProjectPaths, ResourcePaths };

package/build/paths.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResourcePaths = exports.ProjectPaths = exports.ProjectPathCandidates = exports.ManagedPaths = exports.HarmonyPaths = void 0;
+exports.ResourcePaths = exports.ProjectPaths = exports.ProjectPathCandidates = exports.NativeInputsStampPath = exports.ManagedPaths = exports.HarmonyPaths = void 0;
 exports.isInside = isInside;
 exports.assertNoExternalSymlink = assertNoExternalSymlink;
 exports.resolveHarmonyPath = resolveHarmonyPath;
@@ -37,8 +37,7 @@ const ProjectPaths = Object.freeze({
 });
 exports.ProjectPaths = ProjectPaths;
 const ProjectPathCandidates = Object.freeze({
-    // Keep this order aligned with @react-native-community/cli-config's async
-    // search places. The first entry is also the file created for new projects.
+    // Match React Native CLI lookup precedence; new projects use the first path.
     reactNativeConfig: Object.freeze([
         'react-native.config.js',
         'react-native.config.cjs',
@@ -69,55 +68,56 @@ function isInside(root, target) {
         || (!relative.startsWith(`..${node_path_1.default.sep}`) && relative !== '..' && !node_path_1.default.isAbsolute(relative));
 }
 async function assertNoExternalSymlink(root, target) {
-    const absoluteRoot = node_path_1.default.resolve(root);
-    const realRoot = await node_fs_1.default.promises.realpath(absoluteRoot).catch(() => absoluteRoot);
-    const relative = node_path_1.default.relative(absoluteRoot, target);
-    let cursor = absoluteRoot;
+    const absolute = node_path_1.default.resolve(root);
+    const canonical = await node_fs_1.default.promises.realpath(absolute).catch(() => absolute);
+    const relative = node_path_1.default.relative(absolute, target);
+    let current = absolute;
     for (const segment of relative.split(node_path_1.default.sep).filter(Boolean)) {
-        cursor = node_path_1.default.join(cursor, segment);
+        current = node_path_1.default.join(current, segment);
         let stat;
         try {
-            stat = await node_fs_1.default.promises.lstat(cursor);
+            stat = await node_fs_1.default.promises.lstat(current);
         }
         catch (cause) {
             if (cause.code === 'ENOENT')
                 break;
-            throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_INVALID', `Cannot inspect managed Harmony path ${cursor}: ${cause.message}`, { cause, file: cursor, operation: 'resolve-path' });
+            throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_INVALID', `Cannot inspect managed Harmony path ${current}: ${cause.message}`, { cause, file: current, operation: 'resolve-path' });
         }
         if (stat.isSymbolicLink()) {
-            const real = await node_fs_1.default.promises.realpath(cursor);
-            if (!isInside(realRoot, real)) {
-                throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Refusing to follow a symlink outside the Harmony project: ${cursor}`, { file: cursor, operation: 'resolve-path' });
+            const real = await node_fs_1.default.promises.realpath(current);
+            if (!isInside(canonical, real)) {
+                throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Refusing to follow a symlink outside the Harmony project: ${current}`, { file: current, operation: 'resolve-path' });
             }
         }
     }
 }
-async function resolveHarmonyPath(platformProjectRoot, relativePath) {
-    if (typeof relativePath !== 'string' || !relativePath || node_path_1.default.isAbsolute(relativePath)) {
-        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Invalid managed path: ${relativePath}`, { operation: 'resolve-path' });
+async function resolveHarmonyPath(directory, relative) {
+    if (typeof relative !== 'string' || !relative || node_path_1.default.isAbsolute(relative)) {
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Invalid managed path: ${relative}`, { operation: 'resolve-path' });
     }
-    const root = node_path_1.default.resolve(platformProjectRoot);
-    const target = node_path_1.default.resolve(root, relativePath);
+    const root = node_path_1.default.resolve(directory);
+    const target = node_path_1.default.resolve(root, relative);
     if (!isInside(root, target)) {
-        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Managed path escapes the Harmony project: ${relativePath}`, { file: target, operation: 'resolve-path' });
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_ESCAPE', `Managed path escapes the Harmony project: ${relative}`, { file: target, operation: 'resolve-path' });
     }
     await assertNoExternalSymlink(root, target);
     return target;
 }
-async function resolveProjectPath(projectRoot, modName) {
-    const candidates = ProjectPathCandidates[modName] || [ProjectPaths[modName]];
-    const resolved = await Promise.all(candidates.map(candidate => resolveHarmonyPath(projectRoot, candidate)));
-    const existing = resolved.filter(file => node_fs_1.default.existsSync(file));
-    if (existing.length > 1) {
-        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_CONFIG_INVALID', `Multiple files provide harmony.${modName}: ${existing.map(file => node_path_1.default.basename(file)).join(', ')}`, { file: existing[0], operation: `harmony.${modName}.read` });
+async function resolveProjectPath(root, name) {
+    const candidates = ProjectPathCandidates[name] || [ProjectPaths[name]];
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(root, candidate)))
+            return resolveHarmonyPath(root, candidate);
     }
-    return existing[0] || resolved[0];
+    return resolveHarmonyPath(root, candidates[0]);
 }
-function toPosixRelative(projectRoot, target) {
-    return node_path_1.default.relative(projectRoot, target).split(node_path_1.default.sep).join('/');
+function toPosixRelative(root, target) {
+    return node_path_1.default.relative(root, target).split(node_path_1.default.sep).join('/');
 }
-exports.HarmonyPaths = {
-    HARMONY_PATHS: ManagedPaths,
+const { nativeInputsStamp: NativeInputsStampPath, ...PublicManagedPaths } = ManagedPaths;
+exports.NativeInputsStampPath = NativeInputsStampPath;
+exports.HarmonyPaths = Object.freeze({
+    HARMONY_PATHS: Object.freeze(PublicManagedPaths),
     PROJECT_PATH_CANDIDATES: ProjectPathCandidates,
     PROJECT_PATHS: ProjectPaths,
     RESOURCE_PATHS: ResourcePaths,
@@ -126,4 +126,4 @@ exports.HarmonyPaths = {
     resolveHarmonyPath,
     resolveProjectPath,
     toPosixRelative,
-};
+});

package/build/permissions.d.ts

@@ -0,0 +1,12 @@
+import type { HarmonyPermission } from './config';
+import { type HarmonyModuleJson } from './manifest';
+import type { HarmonyConfigPlugin } from './pluginTypes';
+export declare function mergePermissions(current: readonly HarmonyPermission[], additions: readonly HarmonyPermission[]): HarmonyPermission[];
+export declare function ensurePermissions(manifest: HarmonyModuleJson, permissions: readonly HarmonyPermission[]): HarmonyModuleJson;
+export declare function removePermissions(manifest: HarmonyModuleJson, names: readonly string[]): HarmonyModuleJson;
+export declare const withHarmonyPermissions: HarmonyConfigPlugin<readonly HarmonyPermission[]>;
+export declare const HarmonyPermissions: Readonly<{
+    ensurePermissions: typeof ensurePermissions;
+    mergePermissions: typeof mergePermissions;
+    removePermissions: typeof removePermissions;
+}>;

package/build/permissions.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HarmonyPermissions = exports.withHarmonyPermissions = void 0;
+exports.mergePermissions = mergePermissions;
+exports.ensurePermissions = ensurePermissions;
+exports.removePermissions = removePermissions;
+const manifest_1 = require("./manifest");
+const mods_1 = require("./mods");
+const normalizeConfig_1 = require("./normalizeConfig");
+function mergePermissions(current, additions) {
+    const result = new Map();
+    for (const input of [...current, ...additions]) {
+        const permission = (0, normalizeConfig_1.normalizePermission)(input);
+        const existing = result.get(permission.name);
+        const scene = existing?.usedScene || permission.usedScene;
+        const abilities = [...new Set([
+                ...(existing?.usedScene?.abilities ?? []),
+                ...(permission.usedScene?.abilities ?? []),
+            ])];
+        result.set(permission.name, {
+            ...existing,
+            ...permission,
+            ...(scene
+                ? {
+                    usedScene: {
+                        ...(abilities.length ? { abilities } : {}),
+                        when: existing?.usedScene?.when === 'always' || permission.usedScene?.when === 'always' ? 'always' : 'inuse',
+                    },
+                }
+                : {}),
+        });
+    }
+    return [...result.values()];
+}
+function ensurePermissions(manifest, permissions) {
+    const module = (0, manifest_1.getModuleOrThrow)(manifest);
+    module.requestPermissions = mergePermissions(module.requestPermissions ?? [], permissions);
+    return manifest;
+}
+function removePermissions(manifest, names) {
+    const module = (0, manifest_1.getModuleOrThrow)(manifest);
+    if (module.requestPermissions) {
+        module.requestPermissions = module.requestPermissions.filter(permission => !names.includes(permission.name));
+    }
+    return manifest;
+}
+const withHarmonyPermissions = (config, permissions) => {
+    const additions = mergePermissions([], permissions);
+    if (config.harmony) {
+        config.harmony = { ...config.harmony, permissions: mergePermissions(config.harmony.permissions ?? [], additions) };
+    }
+    return (0, mods_1.withModuleJson)(config, (mod) => {
+        if (mod.modResults.module === undefined)
+            mod.modResults.module = {};
+        ensurePermissions(mod.modResults, additions);
+        return mod;
+    });
+};
+exports.withHarmonyPermissions = withHarmonyPermissions;
+exports.HarmonyPermissions = Object.freeze({ ensurePermissions, mergePermissions, removePermissions });

package/build/pluginTypes.d.ts

@@ -0,0 +1,15 @@
+import type { ExportedConfigWithProps } from '@expo/config-plugins';
+import type { ExpoConfigWithHarmony, ExpoHarmonyPlatform, HarmonyConfig } from './config';
+export type HarmonyConfigPlugin<Props = void> = <Config extends ExpoConfigWithHarmony>(config: Config, props: Props) => Config;
+export type HarmonyModConfig<T> = Omit<ExportedConfigWithProps<T>, 'platforms' | 'modRawConfig' | 'modRequest'> & {
+    platforms?: ExpoHarmonyPlatform[];
+    harmony?: HarmonyConfig;
+    modRawConfig: ExpoConfigWithHarmony;
+    modRequest: Omit<ExportedConfigWithProps<T>['modRequest'], 'platform' | 'nextMod'> & {
+        platform: 'harmony';
+        nextMod?: HarmonyModAction<T>;
+        modFile?: string;
+        modFileExists?: boolean;
+    };
+};
+export type HarmonyModAction<T = unknown> = (config: HarmonyModConfig<T>) => HarmonyModConfig<T> | Promise<HarmonyModConfig<T>>;

package/build/pluginTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/resources.d.ts

@@ -0,0 +1,13 @@
+export interface HarmonyResourceItem extends Record<string, unknown> {
+    name: string;
+    value: string;
+}
+export interface HarmonyResourceFile extends Record<string, unknown> {
+    string?: HarmonyResourceItem[];
+    color?: HarmonyResourceItem[];
+}
+export declare function setString(file: HarmonyResourceFile, item: HarmonyResourceItem): HarmonyResourceFile;
+export declare function removeString(file: HarmonyResourceFile, name: string): HarmonyResourceFile;
+export declare function setColor(file: HarmonyResourceFile, item: HarmonyResourceItem): HarmonyResourceFile;
+export declare function removeColor(file: HarmonyResourceFile, name: string): HarmonyResourceFile;
+export declare function toArgb(value: string | number): string;

package/build/resources.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setString = setString;
+exports.removeString = removeString;
+exports.setColor = setColor;
+exports.removeColor = removeColor;
+exports.toArgb = toArgb;
+const errors_1 = require("./errors");
+function setItem(file, kind, item) {
+    if (!item || typeof item.name !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(item.name)
+        || item.name.includes('..') || typeof item.value !== 'string') {
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_RESOURCE_INVALID', `Invalid Harmony ${kind} resource.`, { operation: 'edit-resource' });
+    }
+    const items = readItems(file, kind);
+    const existing = items.find(value => value?.name === item.name);
+    file[kind] = [...items.filter(value => value?.name !== item.name), { ...existing, ...item }];
+    return file;
+}
+function readItems(file, kind) {
+    if (file[kind] !== undefined && !Array.isArray(file[kind])) {
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_RESOURCE_INVALID', `Harmony ${kind} resources must be an array.`, { operation: 'edit-resource' });
+    }
+    return file[kind] ?? [];
+}
+function setString(file, item) {
+    return setItem(file, 'string', item);
+}
+function removeString(file, name) {
+    const items = readItems(file, 'string');
+    if (file.string)
+        file.string = items.filter(item => item?.name !== name);
+    return file;
+}
+function setColor(file, item) {
+    return setItem(file, 'color', item);
+}
+function removeColor(file, name) {
+    const items = readItems(file, 'color');
+    if (file.color)
+        file.color = items.filter(item => item?.name !== name);
+    return file;
+}
+function toArgb(value) {
+    let hex;
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0xffffffff) {
+        hex = value.toString(16).padStart(8, '0');
+    }
+    else if (typeof value === 'string' && /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i.test(value)) {
+        hex = value.slice(1);
+    }
+    else {
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_CONFIG_INVALID', 'Color must be #RRGGBB, #RRGGBBAA or an unsigned RGBA integer.', { operation: 'convert-color' });
+    }
+    return `#${hex.length === 8 ? hex.slice(6, 8) + hex.slice(0, 6) : hex}`.toUpperCase();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/config-plugins",
-  "version": "55.0.10-harmony.2",
+  "version": "55.0.10-harmony.3",
   "keywords": [
     "react-native",
     "expo",
@@ -29,12 +29,17 @@
       "require": "./build/index.js",
       "default": "./build/index.js"
     },
-    "./native-inputs": {
+    "./package.json": "./package.json",
+    "./internal": {
+      "types": "./build/internal.d.ts",
+      "require": "./build/internal.js",
+      "default": "./build/internal.js"
+    },
+    "./internal/native-inputs": {
       "types": "./build/nativeInputs.d.ts",
       "require": "./build/nativeInputs.js",
       "default": "./build/nativeInputs.js"
-    },
-    "./package.json": "./package.json"
+    }
   },
   "dependencies": {
     "@expo/config-plugins": "55.0.10",
@@ -44,11 +49,6 @@
   "peerDependencies": {
     "@expo/config": "55.0.17"
   },
-  "peerDependenciesMeta": {
-    "@expo/config": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@types/node": "18.19.0",
     "typescript": "^6.0.3"

package/src/compiler.ts

@@ -0,0 +1,21 @@
+import { compileModsAsync, type ExportedConfig, type ModPlatform } from '@expo/config-plugins';
+
+import type { ExpoConfigWithHarmony } from './config';
+import { withHarmonyBaseMods } from './mods';
+
+export interface HarmonyCompileOptions {
+  projectRoot: string;
+  introspect?: boolean;
+  ignoreExistingNativeFiles?: boolean;
+}
+
+export async function compileHarmonyModsAsync<Config extends ExpoConfigWithHarmony>(
+  config: Config,
+  options: HarmonyCompileOptions
+): Promise<Config> {
+  return await compileModsAsync(withHarmonyBaseMods(config) as ExportedConfig, {
+    ...options,
+    platforms: ['harmony' as ModPlatform],
+    assertMissingModProviders: true,
+  }) as Config;
+}

package/src/composition.ts

@@ -0,0 +1,45 @@
+import {
+  createRunOncePlugin as expoCreateRunOncePlugin,
+  withPlugins as expoWithPlugins,
+  withRunOnce as expoWithRunOnce,
+  withStaticPlugin as expoWithStaticPlugin,
+  type ConfigPlugin,
+} from '@expo/config-plugins';
+
+import type { HarmonyConfigPlugin } from './pluginTypes';
+import type { ExpoConfigWithHarmony } from './config';
+
+// Expo plugins accept the narrower platform union. Method variance allows them
+// alongside Harmony plugins without losing contextual types for inline callbacks.
+type CompatiblePlugin<Props = void> = {
+  apply(config: ExpoConfigWithHarmony, props: Props): ExpoConfigWithHarmony;
+}['apply'];
+
+export type HarmonyPluginReference = string | CompatiblePlugin<never>;
+export type HarmonyStaticPlugin = HarmonyPluginReference | [HarmonyPluginReference, unknown];
+
+export const withPlugins = expoWithPlugins as unknown as HarmonyConfigPlugin<HarmonyStaticPlugin[]>;
+export const withRunOnce = expoWithRunOnce as unknown as HarmonyConfigPlugin<{
+  plugin: CompatiblePlugin;
+  name: string;
+  version?: string;
+}>;
+export const withStaticPlugin = expoWithStaticPlugin as unknown as HarmonyConfigPlugin<{
+  plugin: HarmonyStaticPlugin;
+  projectRoot?: string;
+  fallback?: CompatiblePlugin<{ _resolverError: Error } & Record<string, unknown>>;
+}>;
+
+export function createRunOncePlugin<Props>(
+  plugin: HarmonyConfigPlugin<Props>, name: string, version?: string
+): HarmonyConfigPlugin<Props>;
+export function createRunOncePlugin<Props>(
+  plugin: ConfigPlugin<Props>, name: string, version?: string
+): HarmonyConfigPlugin<Props>;
+export function createRunOncePlugin(
+  plugin: ConfigPlugin<never> | HarmonyConfigPlugin<never>,
+  name: string,
+  version?: string
+): HarmonyConfigPlugin<never> {
+  return expoCreateRunOncePlugin(plugin as ConfigPlugin<never>, name, version) as HarmonyConfigPlugin<never>;
+}

package/src/config.ts

@@ -18,25 +18,14 @@ export interface HarmonyPermission {
   usedScene?: { abilities?: string[]; when?: 'inuse' | 'always' };
 }
 
+export type HarmonySkillUri = Record<string, string | number | boolean>;
+
 export interface HarmonySkill {
   entities?: string[];
   actions?: string[];
-  uris?: Array<Record<string, string>>;
-}
-
-export interface HarmonyFontDefinition {
-  path: string;
-  weight?: number;
-  style?: 'normal' | 'italic';
+  uris?: HarmonySkillUri[];
 }
 
-export type HarmonyFont
-  = | string
-    | {
-      fontFamily: string;
-      fontDefinitions: HarmonyFontDefinition[];
-    };
-
 export interface HarmonyConfig {
   bundleName: string;
   moduleName?: string;
@@ -46,14 +35,11 @@ export interface HarmonyConfig {
   versionCode?: number;
   versionName?: string;
   targetApiVersion?: number;
-  /** Harmony SDK label written to build-profile.json5, e.g. 6.0.0(20). Its API must match targetApiVersion. */
   targetSdkVersion?: number | string;
-  /** API number, or a full Harmony SDK label ending in the API number. */
   compatibleSdkVersion?: number | string;
   deviceTypes?: HarmonyDeviceType[];
   permissions?: HarmonyPermission[];
   skills?: HarmonySkill[];
-  /** URL schemes the app may inspect with Linking.canOpenURL. http, https, and expo.scheme are added automatically. */
   querySchemes?: string[];
   icon?: string;
   label?: string;
@@ -63,8 +49,6 @@ export interface HarmonyConfig {
   jsEngine?: 'hermes';
   abiFilters?: string[];
   signingConfigFile?: string;
-  /** Fonts bundled when the `@expo-harmony/expo-font` config plugin is registered. */
-  fonts?: HarmonyFont[];
 }
 
 export type ExpoConfigWithHarmony = Omit<ExpoConfig, 'platforms'> & {

package/src/customFiles.ts

@@ -0,0 +1,142 @@
+import fs from 'node:fs/promises';
+
+import { withBaseMod, type ExportedConfig, type ModPlatform } from '@expo/config-plugins';
+import JSON5 from 'json5';
+
+import { HarmonyConfigPluginError } from './errors';
+import { atomicWrite, stableJson } from './files';
+import { recordManagedFile, registerMod } from './mods';
+import { getHarmonyConfigPlugins, normalizeHarmonyConfigPlugins, registerHarmonyConfigPlugin } from './ownership';
+import { ManagedPaths, ResourcePaths, resolveHarmonyPath } from './paths';
+import type { HarmonyConfigPlugin, HarmonyModAction, HarmonyModConfig } from './pluginTypes';
+
+export interface HarmonyFileModOptions<T> {
+  path: string;
+  owner: string;
+  parse: (source: string | null) => T;
+  serialize: (value: T) => string;
+  isIntrospective?: boolean;
+}
+
+type Definition = Omit<HarmonyFileModOptions<unknown>, 'parse' | 'serialize'> & { parse: unknown; serialize: unknown };
+interface CustomProvider { expoHarmonyLateActions?: unknown }
+const providers = new WeakMap<object, Definition>();
+
+export function createHarmonyFileMod<T>(options: HarmonyFileModOptions<T>): HarmonyConfigPlugin<HarmonyModAction<T>> {
+  const definition = Object.freeze({ ...options });
+  const { path: relative, owner, parse, serialize, isIntrospective = false } = definition;
+
+  normalizeHarmonyConfigPlugins([{ owner, files: [relative] }]);
+
+  const reserved = Object.values(ManagedPaths).includes(relative)
+    || Object.values(ResourcePaths).some(scopes => Object.values(scopes).some(file => relative === file))
+    || Object.values(ResourcePaths.media).some(directory => relative.startsWith(`${directory}/`));
+  if (reserved || relative.split('/').some(part => part === '.git') || relative.startsWith('.expo/')) {
+    throw new HarmonyConfigPluginError('ERR_HARMONY_PATH_INVALID', `Use the built-in mod for reserved path ${relative}.`);
+  }
+  if (typeof parse !== 'function' || typeof serialize !== 'function') {
+    throw new TypeError('A file mod requires parse and serialize functions.');
+  }
+
+  const name = `file:${relative}`;
+
+  return (config, action) => {
+    const mods = (config as ExportedConfig).mods as Record<string, Record<string, CustomProvider>> | undefined;
+    const provider = mods?.harmony?.[name];
+    if (provider) {
+      const stored = providers.get(provider);
+      if (!stored || stored.owner !== owner || stored.parse !== parse
+        || stored.serialize !== serialize || !!stored.isIntrospective !== isIntrospective) {
+        throw new HarmonyConfigPluginError('ERR_HARMONY_CONFIG_INVALID', `Conflicting providers for ${relative}. Reuse the same file mod definition.`);
+      }
+    }
+
+    const claims = getHarmonyConfigPlugins(config).find(plugin => plugin.owner === owner);
+    registerHarmonyConfigPlugin(config, owner, {
+      ...claims, files: [...new Set([...(claims?.files ?? []), relative])],
+    });
+
+    if (!provider) {
+      const actions: HarmonyModAction<T>[] = [];
+      withBaseMod<T>(config as ExportedConfig, {
+        platform: 'harmony' as ModPlatform,
+        mod: name,
+        isProvider: true,
+        isIntrospective,
+        saveToInternal: isIntrospective,
+        async action(value) {
+          const { nextMod: _next, ...request } = value.modRequest;
+          const file = await resolveHarmonyPath(request.platformProjectRoot, relative);
+          let source: string | null = null;
+
+          if (!request.ignoreExistingNativeFiles) {
+            try {
+              source = await fs.readFile(file, 'utf8');
+            } catch (cause) {
+              if ((cause as NodeJS.ErrnoException).code !== 'ENOENT') {
+                throw new HarmonyConfigPluginError(
+                  'ERR_HARMONY_TEXT_INVALID',
+                  `Cannot read ${file}: ${(cause as Error).message}`,
+                  { cause, file, operation: `harmony.${name}.read` }
+                );
+              }
+            }
+          }
+
+          let result = {
+            ...value,
+            modRequest: { ...request, modFile: file, modFileExists: source !== null },
+            modResults: parse(source),
+          } as unknown as HarmonyModConfig<T>;
+          for (let index = actions.length - 1; index >= 0; index--) {
+            result = await actions[index](result) as HarmonyModConfig<T>;
+          }
+
+          const output = serialize(result.modResults);
+          if (typeof output !== 'string') throw new TypeError(`Serializer for ${relative} must return a string.`);
+
+          if (!request.introspect) {
+            await atomicWrite(file, output);
+            recordManagedFile(result, file, owner);
+          }
+
+          return result as unknown as typeof value;
+        },
+      });
+
+      const table = ((config as ExportedConfig).mods as Record<string, Record<string, CustomProvider>>).harmony;
+      table[name].expoHarmonyLateActions = actions;
+      providers.set(table[name], definition);
+
+      // CNG must fingerprint custom outputs after they have been written.
+      for (const stage of ['patch', 'manifest']) {
+        if (table[stage]) {
+          const provider = table[stage];
+          delete table[stage];
+          table[stage] = provider;
+        }
+      }
+    }
+
+    return registerMod(config, name, action);
+  };
+}
+
+function parseJson(source: string | null): Record<string, unknown> {
+  const value = source === null ? {} : JSON5.parse(source);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('A Harmony JSON file must contain an object.');
+  }
+
+  return value;
+}
+
+export interface HarmonyJsonFileOptions {
+  path: string;
+  owner: string;
+  action: HarmonyModAction<Record<string, unknown>>;
+}
+
+export const withHarmonyJsonFile: HarmonyConfigPlugin<HarmonyJsonFileOptions> = (config, { path, owner, action }) => (
+  createHarmonyFileMod({ path, owner, parse: parseJson, serialize: stableJson, isIntrospective: true })(config, action)
+);

package/src/files.ts

@@ -21,7 +21,7 @@ export function stableJson(value: unknown): string {
   return `${JSON.stringify(sortValue(value), null, 2)}\n`;
 }
 
-export async function readJson5<T>(file: string, fallback: T, modName: string): Promise<T> {
+export async function readJson5<T>(file: string, fallback: T, name: string): Promise<T> {
   try {
     const source = await fs.promises.readFile(file, 'utf8');
 
@@ -31,8 +31,8 @@ export async function readJson5<T>(file: string, fallback: T, modName: string):
 
     throw new HarmonyConfigPluginError(
       'ERR_HARMONY_JSON5_INVALID',
-      `Cannot parse ${file} for harmony.${modName}: ${(cause as Error).message}`,
-      { cause, file, operation: `harmony.${modName}.read` }
+      `Cannot parse ${file} for harmony.${name}: ${(cause as Error).message}`,
+      { cause, file, operation: `harmony.${name}.read` }
     );
   }
 }
@@ -74,6 +74,5 @@ export async function writeJson5(file: string, value: unknown): Promise<void> {
 
 export async function sha256File(file: string): Promise<string> {
   const data = Uint8Array.from(await fs.promises.readFile(file));
-
   return crypto.createHash('sha256').update(data).digest('hex');
 }