rn-update-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoghourt Technology(BeiJing) Company Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# rn-update-cli · Pakta
+
+[简体中文](./README.zh-CN.md) · [Website](https://pakta.site) · [SDK](https://github.com/pakta-team/rn-update)
+
+The command-line and CI publishing tool for Pakta. Register native builds, create OTA artifacts, deploy by channel and symbolicate stacks for Android, iOS and HarmonyOS.
+
+## Install
+
+Requires Node.js 18.17+ and your platform build toolchain. Install the CLI globally and invoke `pakta` directly:
+
+```bash
+npm install -g rn-update-cli
+pakta help
+pakta list
+```
+
+## Connect and select an app
+
+The website is [pakta.site](https://pakta.site). These examples assume that domain proxies the repository’s Go service at `/admin/api/v1`; otherwise substitute your actual API URL. The CLI adds the management API prefix. Legacy defaults remain in the code, so explicitly set `RNU_SERVICE_URL` for your own service.
+
+Bash / Zsh:
+
+```bash
+export RNU_SERVICE_URL=https://pakta.site
+```
+
+PowerShell:
+
+```powershell
+$env:RNU_SERVICE_URL = 'https://pakta.site'
+```
+
+After registering and verifying your email in the dashboard, run from your React Native project root:
+
+```bash
+pakta login
+pakta apps --platform android
+pakta selectApp --platform android
+```
+
+Create an app with `pakta createApp --platform android --name MyApp` if needed. Select an app separately for each platform. `selectApp` writes app information to `update.json` for subsequent commands. Credentials are scoped by service URL.
+
+## Publish your first update
+
+Complete SDK native integration, then upload your distributed release binary as the baseline:
+
+```bash
+pakta uploadApk ./app-release.apk
+```
+
+For other formats use `uploadAab`, `uploadIpa` or HarmonyOS `uploadApp`. After changing JavaScript, bundle and publish:
+
+```bash
+pakta bundle --platform android --output .pakta/output/android.ppk --no-interactive
+pakta publish .pakta/output/android.ppk --platform android --name fix-001 --channel default --packageVersion 1.0.0 --rollout 10 --sourcemap .pakta/intermedia/android/index.bundlejs.map
+```
+
+Replace `default` and `1.0.0` with the registered channel and native version. `--rollout 10` deploys to 10%; the default is 100%. Explicit `--output` avoids guessing the default timestamped filename. Add `--expo` for Expo bundles.
+
+Interactive publishing without a target asks whether to bind a native build after upload; declining only stores the package. Non-interactive publishing requires `--targets`, `--packageId` or `--packageVersion`. `bundle --name ...` triggers publishing; omit `--name` to build only.
+
+## Channels and CI
+
+Channel identity comes from native metadata, defaulting to `default`. Upload `--channel` asserts identity without changing it. Standalone uploads/publishes create missing channels. One channel/native-version pair cannot have conflicting JS fingerprints; `buildTime` remains an opaque string.
+
+Create `targets.json`, with one independent deployment per entry:
+
+```json
+[
+  { "channel": "default", "packageVersion": "1.0.0", "rollout": 10 },
+  { "channel": "huawei", "packageVersion": "1.0.0", "rollout": 30 }
+]
+```
+
+Set `RNU_SERVICE_URL` in CI and inject `PAKTA_API_TOKEN` from your secret store, using a personal token created in account settings. Validate the built artifact’s targets, then publish:
+
+```bash
+pakta publish .pakta/output/android.ppk --platform android --targets targets.json --dryRun --no-interactive
+pakta publish .pakta/output/android.ppk --platform android --targets targets.json --name fix-001 --sourcemap .pakta/intermedia/android/index.bundlejs.map --no-interactive
+```
+
+`--dryRun` does not upload, create channels or write packages/deployments. A target’s `rollout` overrides the global value, falling back to 100%. Save the returned `packageId` and `deploymentIds` for exact retries:
+
+```bash
+pakta publish --deploymentIds DEPLOYMENT_ID_1,DEPLOYMENT_ID_2 --platform android --no-interactive
+```
+
+## Command reference
+
+| Purpose | Commands |
+| --- | --- |
+| Account | `login`, `logout`, `me` |
+| Apps | `createApp`, `apps`, `selectApp`, `deleteApp` |
+| Channels | `channels`, `createChannel`, `updateChannel`, `deleteChannel` |
+| Native builds | `uploadApk`, `uploadAab`, `uploadIpa`, `uploadApp`, `packages`, `deletePackage` |
+| Inspect | `parseApk`, `parseAab`, `parseIpa`, `parseApp`, `extractApk` |
+| OTA | `bundle`, `publish`, `versions`, `update`, `updateVersionInfo`, `deleteVersion` |
+| Patches | `hdiff`, `hdiffFromApk`, `hdiffFromIpa`, `hdiffFromApp`, `registerPdiff` |
+| Diagnostics | `symbolicate`, `cache`, `cache clean` |
+
+Local `hdiff*` commands only generate patches; register exact native-build patches separately with `registerPdiff`. Full options: [cli.json](./cli.json).
+
+## Hermes & sourcemaps
+
+`bundle` generates sourcemaps by default and composes the final Hermes map. Archive it with `publish --sourcemap`, then symbolicate:
+
+```bash
+pakta symbolicate stack.txt --platform android --hash UPDATE_HASH
+```
+
+The hash comes from the SDK’s `getUpdateMetadata().currentVersion`. Alternatively use `--versionId`, or `-` to read the stack from stdin.
+
+Hermes defaults to `--hermesBase auto`; use `none` to disable it or pass a `.hbc/.ppk/.apk/.ipa` path. Failed equivalence checks fall back to plain compilation; patch size depends on your build. See [Hermes base verification](./docs/hermes-base-verification.md).
+
+For Sentry, configure platform `sentry.properties`, use `@sentry/react-native/metro` for matching bundle/map Debug IDs, and use the `bundle` publishing flow for automatic uploads. Legacy Sentry accepts explicit `--sentry-release` and `--sentry-dist`, matching runtime values.
+
+## Provider API
+
+Install a development dependency when importing the API in build scripts:
+
+```bash
+npm install --save-dev rn-update-cli
+```
+
+Configure service and authentication first. Place this in an async function or a module supporting top-level await:
+
+```typescript
+import { CLIProviderImpl } from 'rn-update-cli';
+
+const provider = new CLIProviderImpl();
+const bundle = await provider.bundle({
+  platform: 'android',
+  output: '.pakta/output/android.ppk',
+  sourcemap: true,
+});
+if (!bundle.success) throw new Error(bundle.error);
+
+const release = await provider.publish({
+  filePath: '.pakta/output/android.ppk',
+  sourcemap: '.pakta/intermedia/android/index.bundlejs.map',
+  platform: 'android',
+  name: 'fix-001',
+  targets: 'targets.json',
+});
+if (!release.success) throw new Error(release.error);
+```
+
+Methods return `CommandResult`; check `success` before consuming `data`. Full interfaces: [src/types.ts](./src/types.ts).
+
+## Environment and automatic updates
+
+| Variable | Purpose |
+| --- | --- |
+| `RNU_SERVICE_URL` | Standalone service URL |
+| `PAKTA_API_TOKEN` | Personal access token for CI |
+| `NO_INTERACTIVE=true` | Disables prompts |
+| `RNU_LANG` | `zh` (default) or `en` |
+| `RNU_DEBUG=1` | Prints error stacks |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Proxies; lowercase names supported |
+| `PAKTA_CACHE_DIR` | Hermes base cache directory |
+| `RNU_AUTO_UPDATE=0` | Disables background updates |
+
+Global installations can update in the background after a successful command, retaining their package manager, registry, authentication, proxy and global prefix. CI, local dependencies and npx installs are not modified. Alternatively set `RNU_DISABLE_AUTO_UPDATE=1`, or select npm, pnpm, yarn or bun with `RNU_AUTO_UPDATE_PACKAGE_MANAGER`.
+
+License: [MIT](./LICENSE).
+
+Copyright (c) 2026 Yoghourt Technology(BeiJing) Company Limited.

package/README.zh-CN.md

@@ -0,0 +1,167 @@
+# rn-update-cli · Pakta
+
+[English](./README.md) · [官网](https://pakta.site) · [SDK](https://github.com/pakta-team/rn-update)
+
+Pakta 的命令行与 CI 发布工具。通过 `pakta` 为 Android、iOS 和 HarmonyOS 登记原生包、生成 OTA 制品、按渠道发布更新并还原错误堆栈。
+
+## 安装
+
+需要 Node.js 18.17+ 和目标平台的构建工具链。命令行全局安装，直接使用 `pakta`：
+
+```bash
+npm install -g rn-update-cli
+pakta help
+pakta list
+```
+
+## 连接服务与选择应用
+
+官网为 [pakta.site](https://pakta.site)。以下假设该域名已代理本仓库 Go 服务的 `/admin/api/v1`；否则请替换为实际 API 地址。CLI 会自动补充管理 API 前缀。当前默认端点仍为历史服务，必须显式设置 `RNU_SERVICE_URL` 才能连接自己的服务。
+
+Bash / Zsh:
+
+```bash
+export RNU_SERVICE_URL=https://pakta.site
+```
+
+PowerShell:
+
+```powershell
+$env:RNU_SERVICE_URL = 'https://pakta.site'
+```
+
+在控制台注册并验证邮箱后，从 React Native 工程根目录执行：
+
+```bash
+pakta login
+pakta apps --platform android
+pakta selectApp --platform android
+```
+
+没有应用时先运行 `pakta createApp --platform android --name MyApp`。各平台分别选择应用；`selectApp` 把应用信息写入 `update.json`，供后续命令使用。登录凭据按服务地址隔离。
+
+## 发布第一条更新
+
+先完成 SDK 原生接入，上传实际分发的 Release 原生包作为基线：
+
+```bash
+pakta uploadApk ./app-release.apk
+```
+
+其他格式使用 `uploadAab`、`uploadIpa` 或 HarmonyOS 的 `uploadApp`。修改 JavaScript 后，先打包再发布：
+
+```bash
+pakta bundle --platform android --output .pakta/output/android.ppk --no-interactive
+pakta publish .pakta/output/android.ppk --platform android --name fix-001 --channel default --packageVersion 1.0.0 --rollout 10 --sourcemap .pakta/intermedia/android/index.bundlejs.map
+```
+
+把 `default`、`1.0.0` 换成已登记原生包的渠道和版本。`--rollout 10` 表示 10% 投放，省略时默认 100%。固定 `--output` 避免误用带时间戳的默认文件名。Expo 打包增加 `--expo`。
+
+交互发布未指定目标时，上传后会询问是否绑定原生包；选择否只保存更新包。非交互发布必须提供 `--targets`、`--packageId` 或 `--packageVersion`。`bundle --name ...` 会触发发布，只打包时不要传 `--name`。
+
+## 多渠道与 CI
+
+渠道来自原生包元数据，缺省为 `default`；上传的 `--channel` 只做断言，不改写身份。独立服务上传/发布会自动创建缺失渠道。同渠道同原生版本不能登记不同 JS 指纹；`buildTime` 按原始字符串透传。
+
+创建 `targets.json`，每项是一条独立投放：
+
+```json
+[
+  { "channel": "default", "packageVersion": "1.0.0", "rollout": 10 },
+  { "channel": "huawei", "packageVersion": "1.0.0", "rollout": 30 }
+]
+```
+
+CI 中设置 `RNU_SERVICE_URL`，通过密钥管理注入账号设置生成的个人令牌 `PAKTA_API_TOKEN`。对已生成的制品先预检，再发布：
+
+```bash
+pakta publish .pakta/output/android.ppk --platform android --targets targets.json --dryRun --no-interactive
+pakta publish .pakta/output/android.ppk --platform android --targets targets.json --name fix-001 --sourcemap .pakta/intermedia/android/index.bundlejs.map --no-interactive
+```
+
+`--dryRun` 不上传、不创建渠道、不写更新包或投放。每项 `rollout` 优先于全局参数，两者均省略则为 100%。保存返回的 `packageId` 与 `deploymentIds`，失败后按准确投放 ID 重试：
+
+```bash
+pakta publish --deploymentIds DEPLOYMENT_ID_1,DEPLOYMENT_ID_2 --platform android --no-interactive
+```
+
+## 命令速查
+
+| 用途 | 命令 |
+| --- | --- |
+| 账号 | `login`, `logout`, `me` |
+| 应用 | `createApp`, `apps`, `selectApp`, `deleteApp` |
+| 渠道 | `channels`, `createChannel`, `updateChannel`, `deleteChannel` |
+| 原生包 | `uploadApk`, `uploadAab`, `uploadIpa`, `uploadApp`, `packages`, `deletePackage` |
+| 解析 | `parseApk`, `parseAab`, `parseIpa`, `parseApp`, `extractApk` |
+| OTA | `bundle`, `publish`, `versions`, `update`, `updateVersionInfo`, `deleteVersion` |
+| 差分 | `hdiff`, `hdiffFromApk`, `hdiffFromIpa`, `hdiffFromApp`, `registerPdiff` |
+| 诊断 | `symbolicate`, `cache`, `cache clean` |
+
+本地 `hdiff*` 只生成补丁，精确原生构建补丁需另行通过 `registerPdiff` 登记。完整选项见 [cli.json](./cli.json).
+
+## Hermes & sourcemaps
+
+`bundle` 默认生成 sourcemap，Hermes 工程会合成最终映射。用 `publish --sourcemap` 归档后还原错误堆栈：
+
+```bash
+pakta symbolicate stack.txt --platform android --hash UPDATE_HASH
+```
+
+hash 来自 SDK 的 `getUpdateMetadata().currentVersion`；也可使用 `--versionId`，`-` 表示从 stdin 读取堆栈。
+
+Hermes 默认 `--hermesBase auto` 复用历史基线，`none` 关闭，也可传 `.hbc/.ppk/.apk/.ipa` 路径。默认等价校验失败时回退普通编译；补丁大小取决于实际构建。详见 [Hermes base verification](./docs/hermes-base-verification.md).
+
+Sentry 需配置平台的 `sentry.properties`，通过 `@sentry/react-native/metro` 保持 bundle/map Debug ID 一致，并使用 `bundle` 发布流程自动上传。旧版 Sentry 可指定 `--sentry-release`、`--sentry-dist`，与运行时保持一致。
+
+## Provider API
+
+仅构建脚本导入 API 时，安装项目开发依赖：
+
+```bash
+npm install --save-dev rn-update-cli
+```
+
+先配置服务和认证。下面代码放入 async 函数或支持顶层 await 的模块：
+
+```typescript
+import { CLIProviderImpl } from 'rn-update-cli';
+
+const provider = new CLIProviderImpl();
+const bundle = await provider.bundle({
+  platform: 'android',
+  output: '.pakta/output/android.ppk',
+  sourcemap: true,
+});
+if (!bundle.success) throw new Error(bundle.error);
+
+const release = await provider.publish({
+  filePath: '.pakta/output/android.ppk',
+  sourcemap: '.pakta/intermedia/android/index.bundlejs.map',
+  platform: 'android',
+  name: 'fix-001',
+  targets: 'targets.json',
+});
+if (!release.success) throw new Error(release.error);
+```
+
+返回 `CommandResult`，消费 `data` 前检查 `success`。完整接口见 [src/types.ts](./src/types.ts).
+
+## 环境与自动更新
+
+| 变量 | 用途 |
+| --- | --- |
+| `RNU_SERVICE_URL` | 独立服务地址 |
+| `PAKTA_API_TOKEN` | CI 个人访问令牌 |
+| `NO_INTERACTIVE=true` | 关闭交互 |
+| `RNU_LANG` | `zh`（默认）或 `en` |
+| `RNU_DEBUG=1` | 输出错误堆栈 |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | 代理，支持小写形式 |
+| `PAKTA_CACHE_DIR` | Hermes base 缓存目录 |
+| `RNU_AUTO_UPDATE=0` | 关闭后台自动更新 |
+
+全局 CLI 在成功执行后可通过原包管理器后台更新，沿用 registry、认证、代理和全局目录配置。CI、本地依赖和 npx 安装不会被修改。也可设置 `RNU_DISABLE_AUTO_UPDATE=1` 关闭，或用 `RNU_AUTO_UPDATE_PACKAGE_MANAGER` 指定 npm、pnpm、yarn、bun。
+
+许可证：[MIT](./LICENSE)。
+
+Copyright (c) 2026 Yoghourt Technology(BeiJing) Company Limited.