feat: add experimental support for HarmonyOS platform (#600)

* wip: initial harmony support

* make run and build work; remove signing for now

* add template

* fixups

* fingerprints

* add missing files and deps; change js entrypoint

* Skip copying metro.config.js for Harmony platform

* fixup template

* update fs-fingerprint, platform config, tests, validation

* add basic dependency config

* fix hvigor-plugin dep

* use React 18

* resolve @ohos from harmonyos registry; pnpm hoisted; community cli

* fix: use PascalCase

* versions and fixups

* add display name; update tests

* fixup nits from cursor review

* add/remove todos

* docs: add docs

* update docs

* moar docs updates

* fix linter

* changeset

* add harmony to supported types in fingerprint

* fix tests

Author: thymikee

.changeset/free-squids-walk.md

@@ -0,0 +1,10 @@
+---
+'@rock-js/platform-android': patch
+'@rock-js/platform-harmony': patch
+'create-rock': patch
+'@rock-js/tools': patch
+'rock': patch
+'rock-docs': patch
+---
+
+feat: add experimental support for HarmonyOS platform

packages/cli/src/lib/plugins/fingerprint.ts

@@ -33,7 +33,7 @@ function redactSensitiveSources(sources: FingerprintInputHash[]) {
 }
 
 type NativeFingerprintCommandOptions = {
-  platform: 'ios' | 'android';
+  platform: 'ios' | 'android' | 'harmony';
   raw?: boolean;
 };
 
@@ -44,7 +44,12 @@ export async function nativeFingerprintCommand(
 ) {
   validateOptions(options);
   const platform = options.platform;
-  const readablePlatformName = platform === 'ios' ? 'iOS' : 'Android';
+  const readablePlatformName =
+    platform === 'ios'
+      ? 'iOS'
+      : platform === 'android'
+        ? 'Android'
+        : 'HarmonyOS';
 
   if (options.raw || !isInteractive()) {
     const fingerprint = await nativeFingerprint(path, {
@@ -106,12 +111,16 @@ export async function nativeFingerprintCommand(
 function validateOptions(options: NativeFingerprintCommandOptions) {
   if (!options.platform) {
     throw new RockError(
-      'The --platform flag is required. Please specify either "ios" or "android".',
+      'The --platform flag is required. Please specify either "ios", "android" or "harmony".',
     );
   }
-  if (options.platform !== 'ios' && options.platform !== 'android') {
+  if (
+    options.platform !== 'ios' &&
+    options.platform !== 'android' &&
+    options.platform !== 'harmony'
+  ) {
     throw new RockError(
-      `Unsupported platform "${options.platform}". Please specify either "ios" or "android".`,
+      `Unsupported platform "${options.platform}". Please specify either "ios", "android" or "harmony".`,
     );
   }
 }

packages/cli/src/lib/plugins/logConfig.ts

@@ -74,7 +74,7 @@ export const logConfigPlugin =
       options: [
         {
           name: '-p, --platform <string>',
-          description: 'Select platform, e.g. ios or android',
+          description: 'Select platform, e.g. ios, android, or harmony',
         },
       ],
     });

packages/cli/src/lib/plugins/remoteCache.ts

@@ -426,13 +426,15 @@ export const remoteCachePlugin =
         },
         {
           name: '-p, --platform <string>',
-          description: 'Select platform, e.g. ios or android',
+          description:
+            'Select platform, e.g. ios, android, or harmony (experimental)',
         },
         {
           name: '-t, --traits <list>',
           description: `Comma-separated traits that construct final artifact name. Traits for Android are: variant; for iOS: destination and configuration. 
 Example iOS: --traits simulator,Release
-Example Android: --traits debug`,
+Example Android: --traits debug
+Example Harmony: --traits debug`,
           parse: (val: string) => val.split(','),
         },
         {

packages/create-app/src/lib/__tests__/bin.test.ts

@@ -7,13 +7,15 @@ test('should format config without plugins', () => {
     .toMatchInlineSnapshot(`
       "import { platformIOS } from '@rock-js/platform-ios';
       import { platformAndroid } from '@rock-js/platform-android';
+      import { platformHarmony } from '@rock-js/platform-harmony';
       import { pluginMetro } from '@rock-js/plugin-metro';
 
       export default {
         bundler: pluginMetro(),
         platforms: {
           ios: platformIOS(),
           android: platformAndroid(),
+          harmony: platformHarmony(),
         },
       };
       "
@@ -25,6 +27,7 @@ test('should format config with plugins', () => {
     {
       type: 'npm',
       name: 'test',
+      displayName: 'test',
       packageName: '@rock-js/plugin-test',
       version: 'latest',
       directory: 'template',

packages/create-app/src/lib/__tests__/templates.test.ts

@@ -6,6 +6,7 @@ test('resolveTemplateName with built-in templates', () => {
   expect(resolveTemplate(TEMPLATES, 'default')).toEqual({
     type: 'npm',
     name: 'default',
+    displayName: 'default',
     packageName: '@rock-js/template-default',
     version: 'latest',
     directory: '.',
@@ -16,6 +17,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, './directory/template-1')).toEqual({
     type: 'local',
     name: 'template-1',
+    displayName: 'template-1',
     localPath: path.resolve('./directory/template-1'),
     directory: '.',
     packageName: 'template-1',
@@ -24,6 +26,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, '../../up/up/away/template-2')).toEqual({
     type: 'local',
     name: 'template-2',
+    displayName: 'template-2',
     localPath: path.resolve('../../up/up/away/template-2'),
     directory: '.',
     packageName: 'template-2',
@@ -32,6 +35,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, '/absolute/path/template-3')).toEqual({
     type: 'local',
     name: 'template-3',
+    displayName: 'template-3',
     localPath: '/absolute/path/template-3',
     directory: '.',
     packageName: 'template-3',
@@ -42,6 +46,7 @@ test('resolveTemplateName with local paths', () => {
   ).toEqual({
     type: 'local',
     name: 'template-4',
+    displayName: 'template-4',
     localPath: '/url-based/path/template-4',
     directory: '.',
     packageName: 'template-4',
@@ -50,6 +55,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, './directory/template-5.tgz')).toEqual({
     type: 'local',
     name: 'template-5',
+    displayName: 'template-5',
     localPath: path.resolve('./directory/template-5.tgz'),
     directory: '.',
     packageName: 'template-5',
@@ -58,6 +64,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, '../up/template-6.tar')).toEqual({
     type: 'local',
     name: 'template-6',
+    displayName: 'template-6',
     localPath: path.resolve('../up/template-6.tar'),
     directory: '.',
     packageName: 'template-6',
@@ -66,6 +73,7 @@ test('resolveTemplateName with local paths', () => {
   expect(resolveTemplate(TEMPLATES, '/root/directory/template-7.tgz')).toEqual({
     type: 'local',
     name: 'template-7',
+    displayName: 'template-7',
     localPath: '/root/directory/template-7.tgz',
     directory: '.',
     packageName: 'template-7',
@@ -76,20 +84,23 @@ test('resolveTemplateName with npm packages', () => {
   expect(resolveTemplate(TEMPLATES, 'package-name')).toEqual({
     type: 'npm',
     name: 'package-name',
+    displayName: 'package-name',
     directory: '.',
     packageName: 'package-name',
     version: 'latest',
   });
   expect(resolveTemplate(TEMPLATES, '[email protected]')).toEqual({
     type: 'npm',
     name: 'package-name',
+    displayName: 'package-name',
     directory: '.',
     packageName: 'package-name',
     version: '1.2.3',
   });
   expect(resolveTemplate(TEMPLATES, '@scoped/[email protected]')).toEqual({
     type: 'npm',
     name: '@scoped/package-name',
+    displayName: '@scoped/package-name',
     directory: '.',
     packageName: '@scoped/package-name',
     version: '1.2.3',

packages/create-app/src/lib/bin.ts

@@ -165,7 +165,13 @@ export async function run() {
   for (const platform of platforms) {
     await extractPackage(absoluteTargetDir, platform);
   }
-  await extractPackage(absoluteTargetDir, bundler);
+  // Skip metro.config.js for Harmony platform as it's included in the platform template
+  const skipFiles = platforms
+    .map((platform) => platform.name)
+    .includes('harmony')
+    ? ['metro.config.js']
+    : undefined;
+  await extractPackage(absoluteTargetDir, bundler, skipFiles);
   for (const plugin of plugins ?? []) {
     await extractPackage(absoluteTargetDir, plugin);
   }
@@ -252,7 +258,11 @@ async function installDependencies(
   loader.stop(`Installed dependencies with ${pkgManager}`);
 }
 
-async function extractPackage(absoluteTargetDir: string, pkg: TemplateInfo) {
+async function extractPackage(
+  absoluteTargetDir: string,
+  pkg: TemplateInfo,
+  skipFiles?: string[],
+) {
   let tarballPath: string | null = null;
   // NPM package: download tarball file
   if (pkg.type === 'npm') {
@@ -282,7 +292,9 @@ async function extractPackage(absoluteTargetDir: string, pkg: TemplateInfo) {
       fs.unlinkSync(tarballPath);
     }
 
-    copyDirSync(path.join(localPath, pkg.directory ?? ''), absoluteTargetDir);
+    copyDirSync(path.join(localPath, pkg.directory ?? ''), absoluteTargetDir, {
+      skipFiles,
+    });
     removeDirSync(localPath);
 
     return;
@@ -292,6 +304,7 @@ async function extractPackage(absoluteTargetDir: string, pkg: TemplateInfo) {
     copyDirSync(
       path.join(pkg.localPath, pkg.directory ?? ''),
       absoluteTargetDir,
+      { skipFiles },
     );
 
     return;

packages/create-app/src/lib/templates.ts

@@ -9,6 +9,7 @@ export type TemplateInfo = NpmTemplateInfo | LocalTemplateInfo;
 export type NpmTemplateInfo = {
   type: 'npm';
   name: string;
+  displayName: string;
   version: string;
   packageName: string;
   /** Directory inside package that contains the template */
@@ -21,6 +22,7 @@ export type LocalTemplateInfo = {
   type: 'local';
   name: string;
   localPath: string;
+  displayName: string | undefined;
   packageName: string;
   directory: string | undefined;
   importName?: string;
@@ -31,6 +33,7 @@ export const TEMPLATES: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'default',
+    displayName: 'default',
     packageName: '@rock-js/template-default',
     version: 'latest',
     directory: '.',
@@ -41,6 +44,7 @@ export const PLUGINS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'brownfield-ios',
+    displayName: 'Brownfield iOS',
     packageName: '@rock-js/plugin-brownfield-ios',
     hint: 'Setup packaging React Native app as a XCFramework',
     version: 'latest',
@@ -50,6 +54,7 @@ export const PLUGINS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'brownfield-android',
+    displayName: 'Brownfield Android',
     packageName: '@rock-js/plugin-brownfield-android',
     hint: 'Setup packaging React Native app as an AAR',
     version: 'latest',
@@ -62,6 +67,7 @@ export const BUNDLERS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'metro',
+    displayName: 'Metro',
     packageName: '@rock-js/plugin-metro',
     version: 'latest',
     directory: 'template',
@@ -70,6 +76,7 @@ export const BUNDLERS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'repack',
+    displayName: 'Re.Pack',
     packageName: '@rock-js/plugin-repack',
     version: 'latest',
     directory: 'template',
@@ -81,6 +88,7 @@ export const PLATFORMS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'ios',
+    displayName: 'iOS',
     packageName: '@rock-js/platform-ios',
     version: 'latest',
     directory: 'template',
@@ -89,11 +97,21 @@ export const PLATFORMS: TemplateInfo[] = [
   {
     type: 'npm',
     name: 'android',
+    displayName: 'Android',
     packageName: '@rock-js/platform-android',
     version: 'latest',
     directory: 'template',
     importName: 'platformAndroid',
   },
+  {
+    type: 'npm',
+    name: 'harmony',
+    displayName: 'Harmony (experimental)',
+    packageName: '@rock-js/platform-harmony',
+    version: 'latest',
+    directory: 'template',
+    importName: 'platformHarmony',
+  },
 ];
 
 export function remoteCacheProviderToImportTemplate(
@@ -175,6 +193,7 @@ export function resolveTemplate(
     return {
       type: 'local',
       name: basename.slice(0, basename.length - ext.length),
+      displayName: basename.slice(0, basename.length - ext.length),
       localPath: resolveAbsolutePath(name),
       directory: '.',
       packageName: basename.slice(0, basename.length - ext.length),
@@ -187,6 +206,7 @@ export function resolveTemplate(
   return {
     type: 'npm',
     name: getNpmLibraryName(name),
+    displayName: getNpmLibraryName(name),
     packageName: getNpmLibraryName(name),
     directory: '.',
     version: getNpmLibraryVersion(name) ?? 'latest',

packages/create-app/src/lib/utils/edit-template.ts

@@ -12,11 +12,18 @@ const PLACEHOLDER_NAME = 'HelloWorld';
  */
 export function renameCommonFiles(projectPath: string) {
   const sourceGitIgnorePath = path.join(projectPath, 'gitignore');
-  if (!fs.existsSync(sourceGitIgnorePath)) {
-    return;
+  if (fs.existsSync(sourceGitIgnorePath)) {
+    fs.renameSync(sourceGitIgnorePath, path.join(projectPath, '.gitignore'));
   }
 
-  fs.renameSync(sourceGitIgnorePath, path.join(projectPath, '.gitignore'));
+  // Harmony platform has a separate gitignore file.
+  const harmonyGitIgnorePath = path.join(projectPath, 'harmony', 'gitignore');
+  if (fs.existsSync(harmonyGitIgnorePath)) {
+    fs.renameSync(
+      harmonyGitIgnorePath,
+      path.join(projectPath, 'harmony', '.gitignore'),
+    );
+  }
 }
 
 /**

packages/create-app/src/lib/utils/fs.ts

@@ -29,7 +29,7 @@ export function copyDirSync(
     } else {
       if (nodePath.basename(srcFile) === 'package.json') {
         mergePackageJsons(srcFile, distFile);
-      } else {
+      } else if (!skipFiles?.includes(nodePath.basename(srcFile))) {
         fs.copyFileSync(srcFile, distFile);
       }
     }