react-native-update-cli/README.zh-CN.md

React Native Update CLI

这是一个统一的 React Native Update CLI，同时支持传统命令和模块化架构以及自定义发布流程。

🚀 特性

• 统一 CLI: 使用单个pushy命令提供所有功能
• 向后兼容: 所有现有命令都能正常工作
• 模块化架构: 将 CLI 功能拆分为独立的模块
• 自定义工作流: 支持创建自定义的发布流程
• 可扩展性: 用户可以导入和注册自定义模块
• 类型安全: 完整的 TypeScript 类型支持

📦 安装

npm install react-native-update-cli

🎯 快速开始

基本使用

# 使用统一CLI
npx pushy help

# 列出所有可用命令和工作流
npx pushy list

# 执行内置的工作流
npx pushy workflow setup-app

# 执行自定义工作流
npx pushy workflow custom-publish

编程方式使用

import { moduleManager, CLIProviderImpl } from 'react-native-update-cli';

// 获取CLI提供者
const provider = moduleManager.getProvider();

// 执行打包
const bundleResult = await provider.bundle({
  platform: 'ios',
  dev: false,
  sourcemap: true,
});

// 发布版本
const publishResult = await provider.publish({
  name: 'v1.2.3',
  description: 'Bug fixes and improvements',
  rollout: 100,
});

🔧 创建自定义模块

1. 定义模块

import type {
  CLIModule,
  CommandDefinition,
  CustomWorkflow,
} from 'react-native-update-cli';

export const myCustomModule: CLIModule = {
  name: 'my-custom',
  version: '1.0.0',

  commands: [
    {
      name: 'custom-command',
      description: 'My custom command',
      handler: async (context) => {
        console.log('Executing custom command...');
        return {
          success: true,
          data: { message: 'Custom command executed' },
        };
      },
      options: {
        param: { hasValue: true, description: 'Custom parameter' },
      },
    },
  ],

  workflows: [
    {
      name: 'my-workflow',
      description: 'My custom workflow',
      steps: [
        {
          name: 'step1',
          description: 'First step',
          execute: async (context, previousResult) => {
            console.log('Executing step 1...');
            return { step1Completed: true };
          },
        },
        {
          name: 'step2',
          description: 'Second step',
          execute: async (context, previousResult) => {
            console.log('Executing step 2...');
            return { ...previousResult, step2Completed: true };
          },
        },
      ],
    },
  ],

  init: (provider) => {
    console.log('Custom module initialized');
  },

  cleanup: () => {
    console.log('Custom module cleanup');
  },
};

2. 注册模块

import { moduleManager } from 'react-native-update-cli';
import { myCustomModule } from './my-custom-module';

// 注册自定义模块
moduleManager.registerModule(myCustomModule);

// 执行自定义命令
const result = await moduleManager.executeCommand('custom-command', {
  args: [],
  options: { param: 'value' },
});

// 执行自定义工作流
const workflowResult = await moduleManager.executeWorkflow('my-workflow', {
  args: [],
  options: {},
});

🔄 工作流系统

工作流步骤

每个工作流步骤包含：

• name: 步骤名称
• description: 步骤描述
• execute: 执行函数
• condition: 可选的条件函数

条件执行

{
  name: 'conditional-step',
  description: 'Only execute in production',
  execute: async (context, previousResult) => {
    // 执行逻辑
  },
  condition: (context) => {
    return context.options.environment === 'production';
  }
}

工作流验证

{
  name: 'validated-workflow',
  description: 'Workflow with validation',
  steps: [...],
  validate: (context) => {
    if (!context.options.requiredParam) {
      console.error('Required parameter missing');
      return false;
    }
    return true;
  }
}

📋 内置模块

Bundle 模块 (bundle)

• bundle: 打包 JavaScript 代码并可选发布
• diff: 生成两个 PPK 文件之间的差异
• hdiff: 生成两个 PPK 文件之间的 hdiff
• diffFromApk: 从 APK 文件生成差异
• hdiffFromApk: 从 APK 文件生成 hdiff
• hdiffFromApp: 从 APP 文件生成 hdiff
• diffFromIpa: 从 IPA 文件生成差异
• hdiffFromIpa: 从 IPA 文件生成 hdiff

Version 模块 (version)

• publish: 发布新版本
• versions: 列出所有版本
• update: 更新版本信息
• updateVersionInfo: 更新版本元数据

App 模块 (app)

• createApp: 创建新应用
• apps: 列出所有应用
• selectApp: 选择应用
• deleteApp: 删除应用

Package 模块 (package)

• uploadIpa: 上传 IPA 文件（支持 --version 参数覆盖提取的版本）
• uploadApk: 上传 APK 文件（支持 --version 参数覆盖提取的版本）
• uploadApp: 上传 APP 文件（支持 --version 参数覆盖提取的版本）
• parseApp: 解析 APP 文件信息
• parseIpa: 解析 IPA 文件信息
• parseApk: 解析 APK 文件信息
• packages: 列出包

User 模块 (user)

• login: 登录
• logout: 登出
• me: 显示用户信息

🛠️ CLI 提供者 API

核心功能

interface CLIProvider {
  // 打包
  bundle(options: BundleOptions): Promise<CommandResult>;

  // 发布
  publish(options: PublishOptions): Promise<CommandResult>;

  // 上传
  upload(options: UploadOptions): Promise<CommandResult>;

  // 应用管理
  getSelectedApp(
    platform?: Platform,
  ): Promise<{ appId: string; platform: Platform }>;
  listApps(platform?: Platform): Promise<CommandResult>;
  createApp(name: string, platform: Platform): Promise<CommandResult>;

  // 版本管理
  listVersions(appId: string): Promise<CommandResult>;
  getVersion(appId: string, versionId: string): Promise<CommandResult>;
  updateVersion(
    appId: string,
    versionId: string,
    updates: Partial<Version>,
  ): Promise<CommandResult>;

  // 包管理
  listPackages(appId: string, platform?: Platform): Promise<CommandResult>;
  getPackage(appId: string, packageId: string): Promise<CommandResult>;

  // 工具函数
  getPlatform(platform?: Platform): Promise<Platform>;
  loadSession(): Promise<Session>;
  saveToLocal(key: string, value: string): void;
  question(prompt: string): Promise<string>;

  // 工作流
  registerWorkflow(workflow: CustomWorkflow): void;
  executeWorkflow(
    workflowName: string,
    context: CommandContext,
  ): Promise<CommandResult>;
}

自定义命令

// 执行自定义打包命令
const bundleResult = await moduleManager.executeCommand('custom-bundle', {
  args: [],
  options: {
    platform: 'android',
    validate: true,
    optimize: true,
  },
});

// 生成差异文件
const diffResult = await moduleManager.executeCommand('diff', {
  args: [],
  options: {
    origin: './build/v1.0.0.ppk',
    next: './build/v1.1.0.ppk',
    output: './build/diff.patch',
  },
});

// 从APK文件生成差异
const apkDiffResult = await moduleManager.executeCommand('diffFromApk', {
  args: [],
  options: {
    origin: './build/app-v1.0.0.apk',
    next: './build/app-v1.1.0.apk',
    output: './build/apk-diff.patch',
  },
});

🔧 配置

环境变量

# 设置API端点
export PUSHY_REGISTRY=https://your-api-endpoint.com

# 设置非交互模式
export NO_INTERACTIVE=true

配置文件

创建 update.json 文件：

{
  "ios": {
    "appId": "your-ios-app-id",
    "appKey": "your-ios-app-key"
  },
  "android": {
    "appId": "your-android-app-id",
    "appKey": "your-android-app-key"
  }
}

🚨 注意事项

1. 向后兼容: 新的模块化 CLI 保持与现有 CLI 的兼容性
2. 类型安全: 所有 API 都有完整的 TypeScript 类型定义
3. 错误处理: 所有操作都返回标准化的结果格式
4. 资源清理: 模块支持清理函数来释放资源
5. 模块分离: 功能按逻辑分离到不同模块中，便于维护和扩展

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

🚀 Provider API 使用指南

Provider 提供了简洁的编程接口，适合在应用程序中集成 React Native Update CLI 功能。

📋 核心 API 方法

核心业务功能

// 打包应用
await provider.bundle({
  platform: 'ios',
  dev: false,
  sourcemap: true,
});

// 发布版本
await provider.publish({
  name: 'v1.0.0',
  description: 'Bug fixes',
  rollout: 100,
});

// 上传文件
await provider.upload({
  filePath: 'app.ipa',
  platform: 'ios',
});

应用管理

// 创建应用
await provider.createApp('MyApp', 'ios');

// 列出应用
await provider.listApps('ios');

// 获取当前应用
const { appId, platform } = await provider.getSelectedApp('ios');

版本管理

// 列出版本
await provider.listVersions('app123');

// 更新版本
await provider.updateVersion('app123', 'version456', {
  name: 'v1.1.0',
  description: 'New features',
});

工具函数

// 获取平台
const platform = await provider.getPlatform('ios');

// 加载会话
const session = await provider.loadSession();

🎯 使用场景

1. 自动化构建脚本

import { moduleManager } from 'react-native-update-cli';

async function buildAndPublish() {
  const provider = moduleManager.getProvider();

  // 1. 打包
  const bundleResult = await provider.bundle({
    platform: 'ios',
    dev: false,
    sourcemap: true,
  });

  if (!bundleResult.success) {
    throw new Error(`打包失败: ${bundleResult.error}`);
  }

  // 2. 发布
  const publishResult = await provider.publish({
    name: 'v1.2.3',
    description: 'Bug fixes and performance improvements',
    rollout: 100,
  });

  if (!publishResult.success) {
    throw new Error(`发布失败: ${publishResult.error}`);
  }

  console.log('构建和发布完成！');
}

2. CI/CD 集成

async function ciBuild() {
  const provider = moduleManager.getProvider();

  const result = await provider.bundle({
    platform: process.env.PLATFORM as 'ios' | 'android',
    dev: process.env.NODE_ENV !== 'production',
    sourcemap: process.env.NODE_ENV === 'production',
  });

  return result;
}

3. 应用管理服务

class AppManagementService {
  private provider = moduleManager.getProvider();

  async setupNewApp(name: string, platform: Platform) {
    // 创建应用
    const createResult = await this.provider.createApp(name, platform);

    if (createResult.success) {
      // 获取应用信息
      const { appId } = await this.provider.getSelectedApp(platform);

      // 列出版本
      await this.provider.listVersions(appId);

      return { appId, success: true };
    }

    return { success: false, error: createResult.error };
  }
}

⚠️ 注意事项

1. 错误处理: 所有 Provider 方法都返回CommandResult，需要检查success字段
2. 类型安全: Provider 提供完整的 TypeScript 类型支持
3. 会话管理: 使用前确保已登录，可通过loadSession()检查
4. 平台支持: 支持'ios' | 'android' | 'harmony'三个平台

🔧 高级功能

自定义工作流

// 注册自定义工作流
provider.registerWorkflow({
  name: 'quick-release',
  description: '快速发布流程',
  steps: [
    {
      name: 'bundle',
      execute: async () => {
        return await provider.bundle({ platform: 'ios', dev: false });
      },
    },
    {
      name: 'publish',
      execute: async (context, bundleResult) => {
        if (!bundleResult.success) {
          throw new Error('打包失败，无法发布');
        }
        return await provider.publish({ name: 'auto-release', rollout: 50 });
      },
    },
  ],
});

// 执行工作流
await provider.executeWorkflow('quick-release', { args: [], options: {} });

📚 完整示例

import { moduleManager } from 'react-native-update-cli';

class ReactNativeUpdateService {
  private provider = moduleManager.getProvider();

  async initialize() {
    // 加载会话
    await this.provider.loadSession();
  }

  async buildAndDeploy(platform: Platform, version: string) {
    try {
      // 1. 打包
      const bundleResult = await this.provider.bundle({
        platform,
        dev: false,
        sourcemap: true,
      });

      if (!bundleResult.success) {
        throw new Error(`打包失败: ${bundleResult.error}`);
      }

      // 2. 发布
      const publishResult = await this.provider.publish({
        name: version,
        description: `Release ${version}`,
        rollout: 100,
      });

      if (!publishResult.success) {
        throw new Error(`发布失败: ${publishResult.error}`);
      }

      return { success: true, data: publishResult.data };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

  async getAppInfo(platform: Platform) {
    const { appId } = await this.provider.getSelectedApp(platform);
    const versions = await this.provider.listVersions(appId);

    return { appId, versions };
  }
}

// 使用示例
const service = new ReactNativeUpdateService();
await service.initialize();
await service.buildAndDeploy('ios', 'v1.0.0');