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

package/src/normalizeConfig.ts

@@ -6,6 +6,7 @@ import type {
   HarmonySkill,
 } from './config';
 import { HarmonyConfigPluginError } from './errors';
+import { toArgb } from './resources';
 
 type HarmonyExpoConfig = ExpoConfigWithHarmony;
 
@@ -32,10 +33,10 @@ interface NormalizedHarmonyConfig {
   versionName: string;
 }
 
-const BundleNamePattern = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*){2,}$/;
+const BundlePattern = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*){2,}$/;
 const IdentifierPattern = /^[A-Za-z][A-Za-z0-9_]*$/;
 const ColorPattern = /^(#[0-9A-Fa-f]{6}|#[0-9A-Fa-f]{8})$/;
-const ValidOrientations = new Set([
+const Orientations = new Set([
   'default',
   'portrait',
   'landscape',
@@ -43,13 +44,14 @@ const ValidOrientations = new Set([
   'landscape_inverted',
   'auto_rotation',
 ]);
-const ValidDeviceTypes = new Set<HarmonyDeviceType>(['phone', 'tablet', '2in1']);
-const SupportedMinimumHarmonyApi = 13;
-const DefaultHarmonyCompatibleApi = 23;
-const DefaultHarmonyTargetApi = 24;
-const HarmonySdkVersions = new Map([
+const DeviceTypes = new Set<HarmonyDeviceType>(['phone', 'tablet', '2in1']);
+const MinimumApi = 13;
+const TargetApi = 24;
+const SdkVersions = new Map([
   [13, '5.0.1(13)'],
+  [14, '5.0.2(14)'],
   [20, '6.0.0(20)'],
+  [21, '6.0.1(21)'],
   [23, '6.1.0(23)'],
   [24, '6.1.1(24)'],
 ]);
@@ -91,11 +93,7 @@ function normalizeColor(value: unknown, field: string, fallback: string): string
     throw new HarmonyConfigError(`${field} must be #RRGGBB or #RRGGBBAA.`);
   }
 
-  const result = color.toUpperCase();
-
-  return result.length === 9
-    ? `#${result.slice(7, 9)}${result.slice(1, 7)}`
-    : result;
+  return toArgb(color);
 }
 
 function parseSdkApi(value: unknown, field: string): number | null {
@@ -127,11 +125,11 @@ function resolveSdkVersion(api: number, field: string, value?: unknown): string
       }
     } else {
       const version = readString(value, `harmony.${field}`);
-      const versionApi = parseSdkApi(version, field);
+      const parsed = parseSdkApi(version, field);
 
-      if (versionApi !== api) {
+      if (parsed !== api) {
         throw new HarmonyConfigError(
-          `harmony.${field} describes API ${versionApi}, but the configured API level is ${api}.`
+          `harmony.${field} describes API ${parsed}, but the configured API level is ${api}.`
         );
       }
 
@@ -139,7 +137,7 @@ function resolveSdkVersion(api: number, field: string, value?: unknown): string
     }
   }
 
-  const version = HarmonySdkVersions.get(api);
+  const version = SdkVersions.get(api);
 
   if (!version) {
     throw new HarmonyConfigError(
@@ -171,7 +169,7 @@ function normalizeStringArray<T extends string = string>(
   return result;
 }
 
-function normalizePermission(permission: HarmonyPermission) {
+export function normalizePermission(permission: HarmonyPermission) {
   if (!permission || typeof permission !== 'object') {
     throw new HarmonyConfigError('harmony.permissions entries must be objects.');
   }
@@ -196,6 +194,7 @@ function normalizePermission(permission: HarmonyPermission) {
     if (!permission.usedScene || typeof permission.usedScene !== 'object') {
       throw new HarmonyConfigError('permission.usedScene must be an object.');
     }
+
     const when: 'always' | 'inuse' = permission.usedScene.when === undefined
       ? 'inuse'
       : permission.usedScene.when;
@@ -221,7 +220,7 @@ function normalizeSkill(skill: HarmonySkill) {
   const result: {
     actions?: string[];
     entities?: string[];
-    uris?: Array<Record<string, string>>;
+    uris?: HarmonySkill['uris'];
   } = {};
 
   for (const field of ['entities', 'actions'] as const) {
@@ -238,9 +237,11 @@ function normalizeSkill(skill: HarmonySkill) {
         throw new HarmonyConfigError('Harmony skill URI must be an object.');
       }
 
-      const result: Record<string, string> = {};
+      const result: NonNullable<HarmonySkill['uris']>[number] = {};
       for (const [key, value] of Object.entries(uri)) {
-        result[key] = readString(value, `harmony.skills[].uris[].${key}`);
+        result[key] = typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))
+          ? value
+          : readString(value, `harmony.skills[].uris[].${key}`);
       }
 
       return result;
@@ -266,67 +267,57 @@ function normalizeHarmonyConfig(config: HarmonyExpoConfig): NormalizedHarmonyCon
     throw new HarmonyConfigError('Expo config must contain a harmony object.');
   }
 
-  const bundleName = readString(harmony.bundleName, 'harmony.bundleName');
-
-  if (!BundleNamePattern.test(bundleName)) {
+  const bundle = readString(harmony.bundleName, 'harmony.bundleName');
+  if (!BundlePattern.test(bundle)) {
     throw new HarmonyConfigError(
       'harmony.bundleName must contain at least three valid dot-separated segments.'
     );
   }
 
-  const moduleName = readString(harmony.moduleName, 'harmony.moduleName', 'entry');
-  const abilityName = readString(harmony.abilityName, 'harmony.abilityName', 'EntryAbility');
-
-  if (!IdentifierPattern.test(moduleName)) {
+  const module = readString(harmony.moduleName, 'harmony.moduleName', 'entry');
+  const ability = readString(harmony.abilityName, 'harmony.abilityName', 'EntryAbility');
+  if (!IdentifierPattern.test(module)) {
     throw new HarmonyConfigError('harmony.moduleName must be a valid Harmony identifier.');
   }
-  if (!IdentifierPattern.test(abilityName)) {
+  if (!IdentifierPattern.test(ability)) {
     throw new HarmonyConfigError('harmony.abilityName must be a valid Harmony identifier.');
   }
 
-  const versionName = readString(harmony.versionName, 'harmony.versionName', config.version || '1.0.0');
-  const versionCode = readPositiveInteger(harmony.versionCode, 'versionCode', 1);
-  const targetSdkApi = parseSdkApi(harmony.targetSdkVersion, 'targetSdkVersion');
-  const targetApi = readPositiveInteger(
+  const version = readString(harmony.versionName, 'harmony.versionName', config.version || '1.0.0');
+  const code = readPositiveInteger(harmony.versionCode, 'versionCode', 1);
+
+  const target = readPositiveInteger(
     harmony.targetApiVersion,
     'targetApiVersion',
-    targetSdkApi ?? DefaultHarmonyTargetApi
+    parseSdkApi(harmony.targetSdkVersion, 'targetSdkVersion') ?? TargetApi
   );
-  const compatibleSdkApi = parseSdkApi(harmony.compatibleSdkVersion, 'compatibleSdkVersion');
-  const compatibleApi = readPositiveInteger(
-    compatibleSdkApi ?? undefined,
+  const compatible = readPositiveInteger(
+    parseSdkApi(harmony.compatibleSdkVersion, 'compatibleSdkVersion') ?? undefined,
     'compatibleSdkVersion',
-    DefaultHarmonyCompatibleApi
+    MinimumApi
   );
 
-  if (compatibleApi < SupportedMinimumHarmonyApi) {
+  if (compatible < MinimumApi) {
     throw new HarmonyConfigError(
-      `Harmony compatible API must be ${SupportedMinimumHarmonyApi} or newer.`
+      `Harmony compatible API must be ${MinimumApi} or newer.`
     );
   }
-  if (compatibleApi > targetApi) {
+  if (compatible > target) {
     throw new HarmonyConfigError('Harmony compatibleSdkVersion cannot exceed targetApiVersion.');
   }
 
   const orientation = harmony.orientation || config.orientation || 'default';
-
-  if (!ValidOrientations.has(orientation)) {
+  if (!Orientations.has(orientation)) {
     throw new HarmonyConfigError(`Unsupported Harmony orientation: ${orientation}`);
   }
 
-  const style = harmony.userInterfaceStyle || config.userInterfaceStyle || 'light';
-
-  if (!['light', 'dark', 'automatic'].includes(style)) {
-    throw new HarmonyConfigError(`Unsupported Harmony UI style: ${style}`);
-  }
-
   const background = normalizeColor(
     harmony.backgroundColor || config.backgroundColor,
     'harmony.backgroundColor',
     '#FFFFFF'
   );
-  const engine = harmony.jsEngine || 'hermes';
 
+  const engine = harmony.jsEngine || 'hermes';
   if (engine !== 'hermes') {
     throw new HarmonyConfigError('Expo Harmony currently supports only the Hermes JavaScript engine.');
   }
@@ -359,6 +350,7 @@ function normalizeHarmonyConfig(config: HarmonyExpoConfig): NormalizedHarmonyCon
   }
 
   skills = [...new Map(skills.map(skill => [JSON.stringify(skill), skill])).values()];
+
   const queries = [...new Set([
     'http',
     'https',
@@ -378,40 +370,40 @@ function normalizeHarmonyConfig(config: HarmonyExpoConfig): NormalizedHarmonyCon
     : normalizeStringArray<HarmonyDeviceType>(
         harmony.deviceTypes,
         'harmony.deviceTypes',
-        ValidDeviceTypes
+        DeviceTypes
       );
 
   return Object.freeze({
     abiFilters: abis,
-    abilityName,
+    abilityName: ability,
     backgroundColor: background,
-    bundleName,
+    bundleName: bundle,
     compatibleSdkVersionString: resolveSdkVersion(
-      compatibleApi,
+      compatible,
       'compatibleSdkVersion',
       harmony.compatibleSdkVersion
     ),
     deviceTypes: devices,
     icon: harmony.icon || config.icon,
     label: readString(harmony.label, 'harmony.label', config.name),
-    moduleName,
+    moduleName: module,
     nativeOrientation: orientation === 'default' ? 'unspecified' : orientation,
     permissions,
     productName: readString(harmony.productName, 'harmony.productName', 'default'),
     querySchemes: queries,
     signingConfigFile: signing,
     skills,
-    targetApiVersion: targetApi,
+    targetApiVersion: target,
     targetSdkVersionString: resolveSdkVersion(
-      targetApi,
+      target,
       'targetSdkVersion',
       harmony.targetSdkVersion
     ),
     vendor: readString(harmony.vendor, 'harmony.vendor', 'expo-harmony'),
-    versionCode,
-    versionName,
+    versionCode: code,
+    versionName: version,
   });
 }
 
-export { HarmonySdkVersions, normalizeHarmonyConfig };
+export { normalizeHarmonyConfig };
 export type { HarmonyExpoConfig, NormalizedHarmonyConfig };

package/src/ownership.ts

@@ -1,7 +1,8 @@
-import type { ExpoConfig } from '@expo/config-types';
+import type { ExpoConfigWithHarmony } from './config';
 
 export interface HarmonyConfigPluginOwnership {
   readonly owner: string;
+  readonly files?: readonly string[];
   readonly ability?: Readonly<Partial<{
     startWindowBackground: string;
     startWindowIcon: string;
@@ -115,7 +116,19 @@ export function normalizeHarmonyConfigPlugins(value: unknown): readonly HarmonyC
 
     owners.add(plugin.owner);
 
+    let files: string[] | undefined;
+    if (plugin.files !== undefined) {
+      if (!Array.isArray(plugin.files) || plugin.files.some(file => typeof file !== 'string'
+        || !file || file.includes('\\') || file.includes('\0') || /^[A-Za-z]:/.test(file)
+        || file.split('/').some(part => !part || part === '.' || part === '..'))) {
+        throw new TypeError(`Invalid Harmony config-plugin ownership: ${plugin.owner}.files must contain relative file paths.`);
+      }
+
+      files = [...new Set(plugin.files as string[])].sort();
+    }
+
     return {
+      ...(files === undefined ? {} : { files }),
       ability: normalizeAbility(plugin.ability),
       owner: plugin.owner,
       resources: normalizeResources(plugin.resources),
@@ -125,15 +138,22 @@ export function normalizeHarmonyConfigPlugins(value: unknown): readonly HarmonyC
   return plugins.sort((left, right) => left.owner.localeCompare(right.owner, 'en'));
 }
 
-export function registerHarmonyConfigPlugin(
-  config: ExpoConfig,
+export function registerHarmonyConfigPlugin<Config extends ExpoConfigWithHarmony>(
+  config: Config,
   owner: string,
   claims: Omit<HarmonyConfigPluginOwnership, 'owner'> = {}
-): ExpoConfig {
+): Config {
   const plugin = normalizeHarmonyConfigPlugins([{ ...claims, owner }])[0];
 
   config._internal ??= {};
   const plugins = normalizeHarmonyConfigPlugins(config._internal.harmonyConfigPlugins);
+  for (const other of plugins) {
+    if (other.owner === owner) continue;
+
+    const duplicate = plugin.files?.find(file => other.files?.includes(file));
+    if (duplicate) throw new TypeError(`Harmony file ${duplicate} is claimed by both ${other.owner} and ${owner}.`);
+  }
+
   config._internal.harmonyConfigPlugins = normalizeHarmonyConfigPlugins([
     ...plugins.filter(item => item.owner !== owner),
     plugin,
@@ -142,6 +162,6 @@ export function registerHarmonyConfigPlugin(
   return config;
 }
 
-export function getHarmonyConfigPlugins(config: ExpoConfig): readonly HarmonyConfigPluginOwnership[] {
+export function getHarmonyConfigPlugins(config: ExpoConfigWithHarmony): readonly HarmonyConfigPluginOwnership[] {
   return normalizeHarmonyConfigPlugins(config?._internal?.harmonyConfigPlugins);
 }

package/src/paths.ts

@@ -8,7 +8,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;
@@ -44,12 +43,12 @@ 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;
 }
 
-const ManagedPaths: HarmonyManagedPaths = Object.freeze({
+const ManagedPaths: HarmonyManagedPaths & { readonly nativeInputsStamp: string } = Object.freeze({
   appJson: 'AppScope/app.json5',
   projectBuildProfile: 'build-profile.json5',
   rootOhPackage: 'oh-package.json5',
@@ -74,8 +73,7 @@ const ProjectPaths: HarmonyProjectPaths = Object.freeze({
 });
 
 const ProjectPathCandidates: HarmonyProjectPathCandidates = 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',
@@ -102,41 +100,40 @@ const ResourcePaths: HarmonyResourcePaths = Object.freeze({
 
 export function isInside(root: string, target: string): boolean {
   const relative = path.relative(root, target);
-
   return relative === ''
     || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
 
 export async function assertNoExternalSymlink(root: string, target: string): Promise<void> {
-  const absoluteRoot = path.resolve(root);
-  const realRoot = await fs.promises.realpath(absoluteRoot).catch(() => absoluteRoot);
-  const relative = path.relative(absoluteRoot, target);
-  let cursor = absoluteRoot;
+  const absolute = path.resolve(root);
+  const canonical = await fs.promises.realpath(absolute).catch(() => absolute);
+  const relative = path.relative(absolute, target);
+  let current = absolute;
 
   for (const segment of relative.split(path.sep).filter(Boolean)) {
-    cursor = path.join(cursor, segment);
+    current = path.join(current, segment);
 
     let stat: fs.Stats;
     try {
-      stat = await fs.promises.lstat(cursor);
+      stat = await fs.promises.lstat(current);
     } catch (cause) {
       if ((cause as NodeJS.ErrnoException).code === 'ENOENT') break;
 
       throw new HarmonyConfigPluginError(
         'ERR_HARMONY_PATH_INVALID',
-        `Cannot inspect managed Harmony path ${cursor}: ${(cause as Error).message}`,
-        { cause, file: cursor, operation: 'resolve-path' }
+        `Cannot inspect managed Harmony path ${current}: ${(cause as Error).message}`,
+        { cause, file: current, operation: 'resolve-path' }
       );
     }
 
     if (stat.isSymbolicLink()) {
-      const real = await fs.promises.realpath(cursor);
+      const real = await fs.promises.realpath(current);
 
-      if (!isInside(realRoot, real)) {
+      if (!isInside(canonical, real)) {
         throw new HarmonyConfigPluginError(
           'ERR_HARMONY_PATH_ESCAPE',
-          `Refusing to follow a symlink outside the Harmony project: ${cursor}`,
-          { file: cursor, operation: 'resolve-path' }
+          `Refusing to follow a symlink outside the Harmony project: ${current}`,
+          { file: current, operation: 'resolve-path' }
         );
       }
     }
@@ -144,24 +141,24 @@ export async function assertNoExternalSymlink(root: string, target: string): Pro
 }
 
 export async function resolveHarmonyPath(
-  platformProjectRoot: string,
-  relativePath: string
+  directory: string,
+  relative: string
 ): Promise<string> {
-  if (typeof relativePath !== 'string' || !relativePath || path.isAbsolute(relativePath)) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative)) {
     throw new HarmonyConfigPluginError(
       'ERR_HARMONY_PATH_ESCAPE',
-      `Invalid managed path: ${relativePath}`,
+      `Invalid managed path: ${relative}`,
       { operation: 'resolve-path' }
     );
   }
 
-  const root = path.resolve(platformProjectRoot);
-  const target = path.resolve(root, relativePath);
+  const root = path.resolve(directory);
+  const target = path.resolve(root, relative);
 
   if (!isInside(root, target)) {
     throw new HarmonyConfigPluginError(
       'ERR_HARMONY_PATH_ESCAPE',
-      `Managed path escapes the Harmony project: ${relativePath}`,
+      `Managed path escapes the Harmony project: ${relative}`,
       { file: target, operation: 'resolve-path' }
     );
   }
@@ -172,30 +169,25 @@ export async function resolveHarmonyPath(
 }
 
 export async function resolveProjectPath(
-  projectRoot: string,
-  modName: keyof HarmonyProjectPaths
+  root: string,
+  name: keyof HarmonyProjectPaths
 ): Promise<string> {
-  const candidates = ProjectPathCandidates[modName] || [ProjectPaths[modName]];
-  const resolved = await Promise.all(candidates.map(candidate => resolveHarmonyPath(projectRoot, candidate)));
-  const existing = resolved.filter(file => fs.existsSync(file));
-
-  if (existing.length > 1) {
-    throw new HarmonyConfigPluginError(
-      'ERR_HARMONY_CONFIG_INVALID',
-      `Multiple files provide harmony.${modName}: ${existing.map(file => path.basename(file)).join(', ')}`,
-      { file: existing[0], operation: `harmony.${modName}.read` }
-    );
+  const candidates = ProjectPathCandidates[name] || [ProjectPaths[name]];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(root, candidate))) return resolveHarmonyPath(root, candidate);
   }
 
-  return existing[0] || resolved[0];
+  return resolveHarmonyPath(root, candidates[0]);
 }
 
-export function toPosixRelative(projectRoot: string, target: string): string {
-  return path.relative(projectRoot, target).split(path.sep).join('/');
+export function toPosixRelative(root: string, target: string): string {
+  return path.relative(root, target).split(path.sep).join('/');
 }
 
-export const HarmonyPaths: HarmonyPathsApi = {
-  HARMONY_PATHS: ManagedPaths,
+const { nativeInputsStamp: NativeInputsStampPath, ...PublicManagedPaths } = ManagedPaths;
+
+export const HarmonyPaths: Readonly<HarmonyPathsApi> = Object.freeze({
+  HARMONY_PATHS: Object.freeze(PublicManagedPaths),
   PROJECT_PATH_CANDIDATES: ProjectPathCandidates,
   PROJECT_PATHS: ProjectPaths,
   RESOURCE_PATHS: ResourcePaths,
@@ -204,6 +196,6 @@ export const HarmonyPaths: HarmonyPathsApi = {
   resolveHarmonyPath,
   resolveProjectPath,
   toPosixRelative,
-};
+});
 
-export { ManagedPaths, ProjectPathCandidates, ProjectPaths, ResourcePaths };
+export { ManagedPaths, NativeInputsStampPath, ProjectPathCandidates, ProjectPaths, ResourcePaths };

package/src/permissions.ts

@@ -0,0 +1,68 @@
+import type { HarmonyPermission } from './config';
+import { getModuleOrThrow, type HarmonyModuleJson } from './manifest';
+import { withModuleJson } from './mods';
+import { normalizePermission } from './normalizeConfig';
+import type { HarmonyConfigPlugin } from './pluginTypes';
+
+export function mergePermissions(
+  current: readonly HarmonyPermission[],
+  additions: readonly HarmonyPermission[]
+): HarmonyPermission[] {
+  const result = new Map<string, HarmonyPermission>();
+  for (const input of [...current, ...additions]) {
+    const permission = 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()];
+}
+
+export function ensurePermissions(
+  manifest: HarmonyModuleJson,
+  permissions: readonly HarmonyPermission[]
+): HarmonyModuleJson {
+  const module = getModuleOrThrow(manifest);
+  module.requestPermissions = mergePermissions(module.requestPermissions ?? [], permissions);
+  return manifest;
+}
+
+export function removePermissions(manifest: HarmonyModuleJson, names: readonly string[]): HarmonyModuleJson {
+  const module = getModuleOrThrow(manifest);
+  if (module.requestPermissions) {
+    module.requestPermissions = module.requestPermissions.filter(permission => !names.includes(permission.name));
+  }
+
+  return manifest;
+}
+
+export const withHarmonyPermissions: HarmonyConfigPlugin<readonly HarmonyPermission[]> = (config, permissions) => {
+  const additions = mergePermissions([], permissions);
+  if (config.harmony) {
+    config.harmony = { ...config.harmony, permissions: mergePermissions(config.harmony.permissions ?? [], additions) };
+  }
+
+  return withModuleJson(config, (mod) => {
+    if (mod.modResults.module === undefined) mod.modResults.module = {};
+    ensurePermissions(mod.modResults, additions);
+    return mod;
+  });
+};
+
+export const HarmonyPermissions = Object.freeze({ ensurePermissions, mergePermissions, removePermissions });

package/src/pluginTypes.ts

@@ -0,0 +1,24 @@
+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/src/resources.ts

@@ -0,0 +1,65 @@
+import { HarmonyConfigPluginError } from './errors';
+
+export interface HarmonyResourceItem extends Record<string, unknown> {
+  name: string;
+  value: string;
+}
+
+export interface HarmonyResourceFile extends Record<string, unknown> {
+  string?: HarmonyResourceItem[];
+  color?: HarmonyResourceItem[];
+}
+
+function setItem(file: HarmonyResourceFile, kind: 'string' | 'color', item: HarmonyResourceItem): HarmonyResourceFile {
+  if (!item || typeof item.name !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(item.name)
+    || item.name.includes('..') || typeof item.value !== 'string') {
+    throw new 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: HarmonyResourceFile, kind: 'string' | 'color'): HarmonyResourceItem[] {
+  if (file[kind] !== undefined && !Array.isArray(file[kind])) {
+    throw new HarmonyConfigPluginError('ERR_HARMONY_RESOURCE_INVALID', `Harmony ${kind} resources must be an array.`, { operation: 'edit-resource' });
+  }
+
+  return file[kind] ?? [];
+}
+
+export function setString(file: HarmonyResourceFile, item: HarmonyResourceItem): HarmonyResourceFile {
+  return setItem(file, 'string', item);
+}
+
+export function removeString(file: HarmonyResourceFile, name: string): HarmonyResourceFile {
+  const items = readItems(file, 'string');
+  if (file.string) file.string = items.filter(item => item?.name !== name);
+  return file;
+}
+
+export function setColor(file: HarmonyResourceFile, item: HarmonyResourceItem): HarmonyResourceFile {
+  return setItem(file, 'color', item);
+}
+
+export function removeColor(file: HarmonyResourceFile, name: string): HarmonyResourceFile {
+  const items = readItems(file, 'color');
+  if (file.color) file.color = items.filter(item => item?.name !== name);
+  return file;
+}
+
+export function toArgb(value: string | number): string {
+  let hex: string;
+  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 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();
+}