feat(publish): archive source maps with published versions; add symbolicate

- bundle: --sourcemap on by default (the composed packager+hermes map)
- publish: uploads the map through /upload and reports sourceMapKey at
  version/create; warns when publishing without one, errors on a missing
  explicit path
- symbolicate: pushy symbolicate <stack|-> --hash <updateHash> (or
  --versionId, --output) downloads the archived map via
  GET /app/{appId}/version/{id}/sourceMap and rewrites bundle frames,
  including Hermes "address at" frames (source-map 0.6.1)
- provider API symbolicate(); Version.sourceMapKey; README (en/zh)

Requires pushy-go/cresc-go with the 20260830-versions-source-map
migration; older servers ignore sourceMapKey and lack the sourceMap route.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018tGFyF841jinkhw1933Zwp

Author: sunnylqm

README.md

@@ -68,13 +68,14 @@ const publishResult = await provider.publish({
 - `hdiffFromApp`: Generate hdiff from APP files
 - `hdiffFromIpa`: Generate hdiff from IPA files
 
-Hermes projects: `bundle` always runs hermesc with `-output-source-map`, so the debug info section is stripped from the bytecode (15–40% smaller, same as React Native's own release builds). The Hermes sourcemap stays in the intermediate directory (`.pushy/intermedia/<platform>/<bundle>.map`, never packed into the ppk); with `--sourcemap` it is composed with the packager map as before. Keep it if you want to symbolicate `address at` crash stacks later.
+Hermes projects: `bundle` always runs hermesc with `-output-source-map`, so the debug info section is stripped from the bytecode (15–40% smaller, same as React Native's own release builds). The Hermes sourcemap stays in the intermediate directory (`.pushy/intermedia/<platform>/<bundle>.map`, never packed into the ppk) and is composed with the packager map — `--sourcemap` is on by default since 2.23 (`--sourcemap false` opts out). When `bundle` publishes, that final map is uploaded and archived with the version (`sourceMapKey`), so `pushy symbolicate` can map crash stacks — including Hermes `address at` frames — back to source later. `pushy publish <ppk> --sourcemap <file.map>` archives a map for a ppk built elsewhere; publishing without a map prints a warning.
 
 Hermes delta mode (`-base-bytecode`): by default (`--hermesBase auto`) `bundle` compiles against the previous HBC of the same app, which keeps Hermes string IDs stable and makes hot-update patches 5–30× smaller. The base comes from the server (`GET /app/:id/hermesBase`), verified by sha256 and kept in a local cache (`.pushy/cache/<sha256>`, 500 MB / 20 files, `PUSHY_CACHE_DIR` / `--cacheMaxMb` to tune, `pushy cache [clean]` to inspect or clear). `--hermesBase none` disables it; `--hermesBase <file.hbc|.ppk|.apk|.ipa>` uses a local artifact (for example the store build). `--verifyHermesBase` (default on) additionally compiles without the base (concurrently with the base compile) and compares both disassemblies; on any mismatch or failure the CLI silently falls back to the plain compile, so the feature can never block a release. Only hermesc builds that include the upstream delta-mode fix are used (classic `react-native/sdks/hermesc`, or `hermes-compiler` ≥ 250829098). If a base compile fails, the full hermesc output is written to `hermes-base-error.log` next to the intermediate directory. `--resetCache false` skips Metro's `--reset-cache` and reuses its transform cache, which makes repeated bundles much faster.
 
 ### Version
 
-- `publish`: Publish a new version
+- `publish`: Publish a new version (`--sourcemap <file.map>` archives the source map with it)
+- `symbolicate`: Map a crash stack to source using the archived map: `pushy symbolicate stack.txt --hash <updateHash>` (`-` reads stdin, `--versionId` instead of `--hash`, `--output <file>`); the hash is `getUpdateMetadata().currentVersion` on the device
 - `versions`: List versions
 - `update`: Update version package rules
 - `updateVersionInfo`: Update version metadata

README.zh-CN.md

@@ -68,13 +68,14 @@ const publishResult = await provider.publish({
 - `hdiffFromApp`: 基于 APP 文件生成 hdiff
 - `hdiffFromIpa`: 基于 IPA 文件生成 hdiff
 
-Hermes 工程：`bundle` 调用 hermesc 时始终带 `-output-source-map`，因此字节码不含 debug info 段（小 15%～40%，与 React Native 自身 release 构建一致）。Hermes sourcemap 保留在中间目录（`.pushy/intermedia/<platform>/<bundle>.map`，不会打进 ppk）；传 `--sourcemap` 时照旧与 packager map 合成。留着它可以事后符号化 `address at` 形式的崩溃堆栈。
+Hermes 工程：`bundle` 调用 hermesc 时始终带 `-output-source-map`，因此字节码不含 debug info 段（小 15%～40%，与 React Native 自身 release 构建一致）。Hermes sourcemap 保留在中间目录（`.pushy/intermedia/<platform>/<bundle>.map`，不会打进 ppk），并与 packager map 合成——自 2.23 起 `--sourcemap` 默认开启（`--sourcemap false` 关闭）。`bundle` 发布时会把这份最终 map 上传并随版本归档（`sourceMapKey`），之后用 `pushy symbolicate` 即可把崩溃堆栈（含 Hermes 的 `address at` 帧）还原到源码。别处打好的 ppk 可用 `pushy publish <ppk> --sourcemap <file.map>` 归档；不带 map 发布会打印警告。
 
 Hermes delta 模式（`-base-bytecode`）：默认 `--hermesBase auto`，`bundle` 会以同一应用上一版的 HBC 为 base 编译，让 Hermes 字符串 ID 跨版本稳定，热更 patch 可缩小 5～30 倍。base 由服务端（`GET /app/:id/hermesBase`）给出、按 sha256 校验并存入本地缓存（`.pushy/cache/<sha256>`，默认 500 MB / 20 个，可用 `PUSHY_CACHE_DIR` / `--cacheMaxMb` 调整，`pushy cache [clean]` 查看或清空）。`--hermesBase none` 关闭；`--hermesBase <file.hbc|.ppk|.apk|.ipa>` 指定本地文件（比如商店包）作 base。`--verifyHermesBase`（默认开）会并行再做一次普通编译并比对两份反汇编；任何不一致或失败都静默回退到普通编译，不会阻塞发版。只有包含上游 delta 模式修复的 hermesc 才会启用（经典 `react-native/sdks/hermesc`，或 `hermes-compiler` ≥ 250829098）。base 编译失败时，完整的 hermesc 输出会写到中间目录旁边的 `hermes-base-error.log`。`--resetCache false` 可跳过 Metro 的 `--reset-cache`，复用其转换缓存，重复打包会快很多。
 
 ### Version
 
-- `publish`: 发布新版本
+- `publish`: 发布新版本（`--sourcemap <file.map>` 随版本归档 source map）
+- `symbolicate`: 用归档的 map 还原崩溃堆栈：`pushy symbolicate stack.txt --hash <热更 hash>`（`-` 读 stdin，可用 `--versionId` 代替 `--hash`，`--output <文件>` 写文件）；hash 即设备上 `getUpdateMetadata().currentVersion`
 - `versions`: 列出版本
 - `update`: 更新版本包规则
 - `updateVersionInfo`: 更新版本元信息

bun.lock

@@ -139,6 +139,9 @@
         },
         "dryRun": {
           "default": false
+        },
+        "sourcemap": {
+          "hasValue": true
         }
       }
     },
@@ -248,7 +251,7 @@
           "hasValue": true
         },
         "sourcemap": {
-          "default": false
+          "default": true
         },
         "taro": {
           "default": false
@@ -382,6 +385,23 @@
     "cache": {
       "description": "Inspect or clean the local bundle cache: cache [clean]",
       "options": {}
+    },
+    "symbolicate": {
+      "description": "Map a JS stack trace back to source using the source map archived with a published version.",
+      "options": {
+        "hash": {
+          "hasValue": true
+        },
+        "versionId": {
+          "hasValue": true
+        },
+        "platform": {
+          "hasValue": true
+        },
+        "output": {
+          "hasValue": true
+        }
+      }
     }
   },
   "globalOptions": {

cli.json

@@ -79,6 +79,7 @@
     "protobufjs": "^8.7.2",
     "read": "^4.1.0",
     "registry-auth-token": "^5.1.1",
+    "source-map": "0.6.1",
     "tty-table": "5.0",
     "yauzl": "^3.4.0",
     "yazl": "3.3.1"

package.json

@@ -7,6 +7,7 @@ import { cacheCommands } from './cache';
 import { diffCommands } from './diff';
 import { installCommands } from './install';
 import { packageCommands } from './package';
+import { symbolicateCommands } from './symbolicate';
 import { userCommands } from './user';
 import { printVersionCommand } from './utils';
 import { t } from './utils/i18n';
@@ -52,6 +53,7 @@ const commandHandlers: Record<string, CliCommandHandler> = {
   ...getAppCommands(),
   ...packageCommands,
   ...versionCommands,
+  ...symbolicateCommands,
   ...installCommands,
   help: printUsage,
 };

src/bin.ts

@@ -72,6 +72,8 @@ type PublishBundlePayload = {
   rollout?: string;
   dryRun?: boolean;
   hermesBase?: HermesBaseMeta;
+  /** path of the final source map to archive with the version */
+  sourcemap?: string;
 };
 
 function getAliasedOptionalStringOption(
@@ -108,7 +110,9 @@ export function normalizeBundleOptions(
       `${tempDir}/output/${platform}.\${time}.ppk`,
     ),
     dev: getBooleanOption(translatedOptions, 'dev', false) ? 'true' : 'false',
-    sourcemap: getBooleanOption(translatedOptions, 'sourcemap', false),
+    // On by default since 2.23: the map is archived with the published
+    // version (pushy symbolicate). --no-sourcemap / --sourcemap=false opts out.
+    sourcemap: getBooleanOption(translatedOptions, 'sourcemap', true),
     taro: getBooleanOption(translatedOptions, 'taro', false),
     expo: getBooleanOption(translatedOptions, 'expo', false),
     rncli: getBooleanOption(translatedOptions, 'rncli', false),
@@ -295,6 +299,10 @@ export const bundleCommands = {
         rollout: normalized.rollout,
         dryRun: normalized.dryRun,
         hermesBase: baseMeta,
+        sourcemap:
+          normalized.sourcemap || bundleParams.sourcemap
+            ? sourcemapOutput
+            : undefined,
       });
       await uploadSentryArtifactsIfNeeded(
         bundleParams.sentry,
@@ -315,6 +323,10 @@ export const bundleCommands = {
       if (v.toLowerCase() === 'y') {
         await publishBundleVersion(realOutput, platform, {
           hermesBase: baseMeta,
+          sourcemap:
+            normalized.sourcemap || bundleParams.sourcemap
+              ? sourcemapOutput
+              : undefined,
         });
         await uploadSentryArtifactsIfNeeded(
           bundleParams.sentry,

src/bundle.ts

@@ -130,6 +130,18 @@ This can reduce the risk of inconsistent dependencies and supply chain attacks.
   processingStringPool: 'Processing the string pool ...',
   publishUsage:
     'Usage: pushy publish <ppk file> --platform ios|android|harmony',
+  sourceMapNotFound: 'Source map not found: {{path}}',
+  sourceMapMissingWarning:
+    'No source map was archived with this version: crashes cannot be symbolicated later. Bundle with the default --sourcemap, or pass --sourcemap <file> to publish.',
+  sourceMapArchived: 'Source map archived with version {{id}}',
+  symbolicateUsage:
+    'Usage: pushy symbolicate <stack file | -> --hash <updateHash> [--platform ios|android|harmony] [--output <file>]',
+  symbolicateVersionNotFound:
+    'No published version with hash {{hash}} found for this app',
+  symbolicateNoSourceMap:
+    'Version {{id}} was published without a source map; nothing to symbolicate against',
+  symbolicateDone:
+    'Symbolicated {{count}} frame(s) against version {{id}} ({{hash}})',
   rnuVersionNotFound:
     'react-native-update: Cannot get the version number. Please run the command in the project directory',
   rolloutConfigSet:

src/locales/en.ts

@@ -118,6 +118,15 @@ export default {
   processingError: '处理文件时出错：{{error}}',
   processingPackage: '正在处理包 {{count}}...',
   processingStringPool: '正在处理字符串池...',
+  sourceMapNotFound: '找不到 source map：{{path}}',
+  sourceMapMissingWarning:
+    '本版本没有归档 source map，之后的崩溃堆栈将无法还原。请用默认的 --sourcemap 打包，或在 publish 时传 --sourcemap <文件>。',
+  sourceMapArchived: 'source map 已随版本 {{id}} 归档',
+  symbolicateUsage:
+    '用法：pushy symbolicate <堆栈文件 | -> --hash <热更 hash> [--platform ios|android|harmony] [--output <文件>]',
+  symbolicateVersionNotFound: '当前应用下找不到 hash 为 {{hash}} 的已发布版本',
+  symbolicateNoSourceMap: '版本 {{id}} 发布时未归档 source map，无法还原',
+  symbolicateDone: '已按版本 {{id}}（{{hash}}）还原 {{count}} 个堆栈帧',
   publishUsage:
     '使用方法: pushy publish ppk后缀文件 --platform ios|android|harmony',
   rnuVersionNotFound:

src/locales/zh.ts

@@ -8,6 +8,7 @@ import type {
   Platform,
   PublishOptions,
   Session,
+  SymbolicateOptions,
   UpdateVersionOptions,
   UploadOptions,
 } from './types';
@@ -128,6 +129,7 @@ export class CLIProviderImpl implements CLIProvider {
                 ? undefined
                 : String(options.rollout),
             dryRun: options.dryRun || false,
+            sourcemap: options.sourcemap,
           },
           options.filePath ? [options.filePath] : [],
         );
@@ -140,6 +142,28 @@ export class CLIProviderImpl implements CLIProvider {
     );
   }
 
+  async symbolicate(options: SymbolicateOptions): Promise<CommandResult> {
+    return this.runMessageCommand(
+      async () => {
+        const context = this.createContext(
+          {
+            hash: options.hash,
+            versionId: options.versionId,
+            platform: options.platform,
+            appId: options.appId,
+            config: options.config,
+            output: options.output,
+          },
+          options.stackFile ? [options.stackFile] : [],
+        );
+        const { symbolicateCommands } = await import('./symbolicate');
+        await symbolicateCommands.symbolicate(context);
+      },
+      'Unknown error during symbolication',
+      'Stack symbolicated',
+    );
+  }
+
   async upload(options: UploadOptions): Promise<CommandResult> {
     return this.runMessageCommand(
       async () => {