@react-native-harness/cli 1.1.0 → 1.2.0

package/src/__tests__/platform-commands.test.ts

@@ -0,0 +1,232 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Config } from '@react-native-harness/config';
+import {
+  discoverPlatformCommands,
+  runPlatformCommand,
+} from '../platform-commands.js';
+
+const createCommandModuleUrl = (body: string) =>
+  `data:text/javascript,${encodeURIComponent(body)}`;
+
+const globalState = globalThis as typeof globalThis & {
+  __platformCommandCall?: unknown;
+};
+
+describe('platform CLI command discovery', () => {
+  afterEach(() => {
+    delete globalState.__platformCommandCall;
+  });
+
+  it('runs a discovered platform command', async () => {
+    const moduleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run(args, context) {
+          globalThis.__platformCommandCall = { args, context };
+        }
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios',
+            config: {},
+            runner: '/virtual/runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    expect(
+      await runPlatformCommand({
+        argv: ['xctest', 'build', '--destination', 'simulator'],
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).toBe(true);
+    expect(globalState.__platformCommandCall).toEqual({
+      args: ['build', '--destination', 'simulator'],
+      context: {
+        cwd: '/tmp/project',
+        projectRoot: '/tmp/project',
+      },
+    });
+  });
+
+  it('deduplicates platform CLI modules across runners', async () => {
+    const moduleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios-sim',
+            config: {},
+            runner: '/virtual/ios-sim-runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+          {
+            name: 'ios-device',
+            config: {},
+            runner: '/virtual/ios-device-runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    const discoveredCommands = await discoverPlatformCommands({
+      cwd: '/tmp/project',
+      loadConfig,
+    });
+
+    expect(discoveredCommands?.commands).toHaveLength(1);
+  });
+
+  it('returns false when no platform command matches', async () => {
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'android',
+            config: {},
+            runner: '/virtual/android-runner.js',
+            platformId: 'android',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    await expect(
+      runPlatformCommand({
+        argv: ['xctest', 'build'],
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).resolves.toBe(false);
+  });
+
+  it('throws when two platform modules define the same command', async () => {
+    const firstModuleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const secondModuleUrl = createCommandModuleUrl(`
+      // second module
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios',
+            config: {},
+            runner: '/virtual/ios-runner.js',
+            cli: firstModuleUrl,
+            platformId: 'ios',
+          },
+          {
+            name: 'android',
+            config: {},
+            runner: '/virtual/android-runner.js',
+            cli: secondModuleUrl,
+            platformId: 'android',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    await expect(
+      discoverPlatformCommands({
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).rejects.toThrow("Duplicate platform CLI command 'xctest'");
+  });
+});

package/src/index.ts

@@ -1,11 +1,135 @@
 import { run, yargsOptions } from 'jest-cli';
 import { getConfig } from '@react-native-harness/config';
 import { runInitWizard } from './wizard/index.js';
+import { runPlatformCommand } from './platform-commands.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const JEST_CONFIG_EXTENSIONS = ['.mjs', '.js', '.cjs'];
 const JEST_HARNESS_CONFIG_BASE = 'jest.harness.config';
+const SKILLS_DIRECTORY = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../skills'
+);
+
+type SkillMetadata = {
+  fileName: string;
+  name: string;
+  description: string;
+};
+
+const readSkillMetadata = (fileName: string): SkillMetadata => {
+  const filePath = path.join(SKILLS_DIRECTORY, fileName);
+  const content = fs.readFileSync(filePath, 'utf8');
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+
+  const metadata = {
+    name: fileName.replace(/\.md$/, ''),
+    description: '',
+  };
+
+  if (frontmatterMatch) {
+    for (const line of frontmatterMatch[1].split('\n')) {
+      const separatorIndex = line.indexOf(':');
+
+      if (separatorIndex === -1) {
+        continue;
+      }
+
+      const key = line.slice(0, separatorIndex).trim();
+      const value = line.slice(separatorIndex + 1).trim().replace(/^['"]|['"]$/g, '');
+
+      if (key === 'name') {
+        metadata.name = value;
+      }
+
+      if (key === 'description') {
+        metadata.description = value;
+      }
+    }
+  }
+
+  return {
+    fileName,
+    name: metadata.name,
+    description: metadata.description,
+  };
+};
+
+const listSkills = () =>
+  fs
+    .readdirSync(SKILLS_DIRECTORY)
+    .filter((file) => file.endsWith('.md'))
+    .map(readSkillMetadata)
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+const printSkillList = () => {
+  for (const skill of listSkills()) {
+    console.log(`${skill.name}: ${skill.description}`);
+  }
+};
+
+const printSkillUsage = () => {
+  console.log(`Usage: harness skill <command>
+
+Commands:
+  list                 List bundled skills
+  get <name>           Print a bundled skill file
+
+Examples:
+  harness skill list
+  harness skill get core`);
+};
+
+const getErrorMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+};
+
+const runSkillCommand = () => {
+  const [, , commandName, subcommand, skillName] = process.argv;
+
+  if (subcommand === undefined || subcommand === 'list') {
+    printSkillList();
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h') {
+    printSkillUsage();
+    return;
+  }
+
+  if (subcommand === 'get') {
+    if (!skillName) {
+      console.error('Missing skill name.');
+      printSkillUsage();
+      process.exit(1);
+    }
+
+    const skillPath = path.join(SKILLS_DIRECTORY, `${skillName}.md`);
+
+    if (!fs.existsSync(skillPath)) {
+      console.error(`Unknown skill '${skillName}'.`);
+      console.error(
+        `Available skills: ${listSkills()
+          .map((skill) => skill.name)
+          .join(', ')}`
+      );
+      process.exit(1);
+    }
+
+    console.log(fs.readFileSync(skillPath, 'utf8'));
+    return;
+  }
+
+  console.error(`Unknown ${commandName} subcommand '${subcommand}'.`);
+  printSkillUsage();
+  process.exit(1);
+};
 
 const checkForOldConfig = async () => {
   try {
@@ -73,9 +197,26 @@ const patchYargsOptions = () => {
   delete yargsOptions.logHeapUsage;
 };
 
-if (process.argv.includes('init')) {
-  runInitWizard();
-} else {
+const main = async () => {
+  if (process.argv[2] === 'skill' || process.argv[2] === 'skills') {
+    runSkillCommand();
+    return;
+  }
+
+  if (process.argv.includes('init')) {
+    runInitWizard();
+    return;
+  }
+
+  if (
+    await runPlatformCommand({
+      argv: process.argv.slice(2),
+      cwd: process.cwd(),
+    })
+  ) {
+    return;
+  }
+
   patchYargsOptions();
 
   const hasConfigArg =
@@ -96,5 +237,11 @@ if (process.argv.includes('init')) {
     }
   }
 
-  checkForOldConfig().then(() => run());
-}
+  await checkForOldConfig();
+  run();
+};
+
+main().catch((error) => {
+  console.error(getErrorMessage(error));
+  process.exit(1);
+});

package/src/platform-commands.ts

@@ -0,0 +1,148 @@
+import { ConfigNotFoundError, getConfig } from '@react-native-harness/config';
+import type { HarnessCliCommand } from '@react-native-harness/platforms';
+
+type ConfigLoader = typeof getConfig;
+
+type DiscoveredPlatformCommands = {
+  commands: HarnessCliCommand[];
+  projectRoot: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const getModuleCommands = (
+  importedModule: unknown,
+  modulePath: string
+): HarnessCliCommand[] => {
+  const moduleValue = isRecord(importedModule)
+    ? importedModule
+    : ({} as Record<string, unknown>);
+  const defaultExport = isRecord(moduleValue.default)
+    ? moduleValue.default
+    : undefined;
+  const commandsValue = moduleValue.commands ?? defaultExport?.commands;
+
+  if (!Array.isArray(commandsValue)) {
+    throw new Error(
+      `Invalid platform CLI module '${modulePath}': expected a commands array.`
+    );
+  }
+
+  return commandsValue.map((command, index) => {
+    if (!isRecord(command) || typeof command.name !== 'string') {
+      throw new Error(
+        `Invalid platform CLI module '${modulePath}': command #${index + 1} is missing a valid name.`
+      );
+    }
+
+    if (typeof command.run !== 'function') {
+      throw new Error(
+        `Invalid platform CLI module '${modulePath}': command '${command.name}' is missing a run handler.`
+      );
+    }
+
+    if (
+      command.aliases !== undefined &&
+      (!Array.isArray(command.aliases) ||
+        command.aliases.some((alias) => typeof alias !== 'string'))
+    ) {
+      throw new Error(
+        `Invalid platform CLI module '${modulePath}': command '${command.name}' has invalid aliases.`
+      );
+    }
+
+    return command as HarnessCliCommand;
+  });
+};
+
+const registerCommandNames = (
+  seenNames: Map<string, string>,
+  modulePath: string,
+  command: HarnessCliCommand
+) => {
+  const names = [command.name, ...(command.aliases ?? [])];
+
+  for (const name of names) {
+    const existingSource = seenNames.get(name);
+
+    if (existingSource !== undefined) {
+      throw new Error(
+        `Duplicate platform CLI command '${name}' in '${modulePath}' and '${existingSource}'.`
+      );
+    }
+
+    seenNames.set(name, modulePath);
+  }
+};
+
+export const discoverPlatformCommands = async (options: {
+  cwd: string;
+  loadConfig?: ConfigLoader;
+}): Promise<DiscoveredPlatformCommands | null> => {
+  const loadConfig = options.loadConfig ?? getConfig;
+
+  try {
+    const { config, projectRoot } = await loadConfig(options.cwd);
+    const modulePaths = [...new Set(config.runners.map((runner) => runner.cli))].filter(
+      (modulePath): modulePath is string => typeof modulePath === 'string'
+    );
+    const commands: HarnessCliCommand[] = [];
+    const seenNames = new Map<string, string>();
+
+    for (const modulePath of modulePaths) {
+      const importedModule = await import(modulePath);
+      const moduleCommands = getModuleCommands(importedModule, modulePath);
+
+      for (const command of moduleCommands) {
+        registerCommandNames(seenNames, modulePath, command);
+        commands.push(command);
+      }
+    }
+
+    return {
+      commands,
+      projectRoot,
+    };
+  } catch (error) {
+    if (error instanceof ConfigNotFoundError) {
+      return null;
+    }
+
+    throw error;
+  }
+};
+
+export const runPlatformCommand = async (options: {
+  argv: string[];
+  cwd: string;
+  loadConfig?: ConfigLoader;
+}): Promise<boolean> => {
+  const commandName = options.argv[0];
+
+  if (typeof commandName !== 'string' || commandName.length === 0) {
+    return false;
+  }
+
+  const discoveredCommands = await discoverPlatformCommands(options);
+
+  if (discoveredCommands === null) {
+    return false;
+  }
+
+  const command = discoveredCommands.commands.find(
+    (entry) =>
+      entry.name === commandName || entry.aliases?.includes(commandName) === true
+  );
+
+  if (command === undefined) {
+    return false;
+  }
+
+  await command.run(options.argv.slice(1), {
+    cwd: options.cwd,
+    projectRoot: discoveredCommands.projectRoot,
+  });
+
+  return true;
+};

package/src/wizard/bundleId.ts

@@ -59,7 +59,7 @@ export const getBundleIds = async (
         try {
           new URL(value);
           return;
-        } catch (_e) {
+        } catch {
           return 'Please enter a valid URL';
         }
       },