rn-update-cli 1.0.0

package/lib/standalone-publish.js

@@ -0,0 +1,433 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishStandalone = publishStandalone;
+exports.retryStandalonePublish = retryStandalonePublish;
+exports.registerStandalonePdiff = registerStandalonePdiff;
+/**
+ * [INPUT]: 依赖独立 Go API、对象上传、渠道/原生包查询与版本参数契约
+ * [OUTPUT]: 对外提供 UpdatePackage/Deployment 上传（含受热更配额校验的 source map 归档）、默认 100% 全量的交互或显式目标解析、准确 ID 重试及逐构建 pdiff 登记
+ * [POS]: CLI 独立服务投放编排层；一个包可在多个渠道×原生版本目标上原子保存并发布
+ */
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const api_1 = require("./api");
+const app_1 = require("./app");
+const package_1 = require("./package");
+const utils_1 = require("./utils");
+const hermes_base_1 = require("./utils/hermes-base");
+const slim_sourcemap_1 = require("./utils/slim-sourcemap");
+const http_helper_1 = require("./utils/http-helper");
+const i18n_1 = require("./utils/i18n");
+const options_1 = require("./utils/options");
+const DEFAULT_STANDALONE_ROLLOUT = 100;
+function hasStandaloneTargetSelection(options) {
+    return Boolean(options.targets ||
+        options.packageId ||
+        options.packageVersion ||
+        options.packageVersionRange ||
+        options.minPackageVersion ||
+        options.maxPackageVersion);
+}
+function resolveTargetRollout(value) {
+    const rollout = value === undefined ? DEFAULT_STANDALONE_ROLLOUT : Number(value);
+    if (!Number.isInteger(rollout) || rollout < 1 || rollout > 100) {
+        throw new Error((0, i18n_1.t)('rolloutRangeError'));
+    }
+    return rollout;
+}
+function nativePackageVersion(pkg) {
+    return String(pkg.versionName ?? pkg.name ?? '').trim();
+}
+/** Choose the native build that receives an interactively published package. */
+async function chooseStandaloneTarget(appId, options) {
+    const channels = await (0, api_1.getChannels)(appId);
+    const allPackages = (await (0, api_1.getAllPackages)(appId)) ?? [];
+    const requestedChannel = String(options.channel || '').trim().toLowerCase();
+    let packages = allPackages;
+    if (requestedChannel) {
+        const channel = channels.find((item) => item.id === requestedChannel ||
+            item.code.trim().toLowerCase() === requestedChannel);
+        if (!channel) {
+            throw new Error(`渠道 ${requestedChannel} 尚未在应用中登记。`);
+        }
+        packages = allPackages.filter((pkg) => pkg.channelId === channel.id);
+    }
+    if (packages.length === 0) {
+        throw new Error(requestedChannel
+            ? `渠道 ${requestedChannel} 下没有可绑定的原生包。`
+            : (0, i18n_1.t)('noPackagesFound', { appId }));
+    }
+    const channelNames = new Map(channels.map((channel) => [channel.id, channel.code]));
+    const displayPackages = packages.map((pkg) => ({
+        ...pkg,
+        channel: pkg.channel || channelNames.get(pkg.channelId || ''),
+    }));
+    const selected = await (0, package_1.choosePackage)(appId, displayPackages);
+    const channelId = String(selected.channelId || '').trim();
+    const packageVersion = nativePackageVersion(selected);
+    if (!channelId || !packageVersion) {
+        throw new Error('所选原生包缺少渠道或版本信息，无法创建投放目标。');
+    }
+    return {
+        channelId,
+        packageVersion,
+        rollout: resolveTargetRollout(options.rollout),
+    };
+}
+function standaloneOperationKey(appId, packageId, deploymentIds) {
+    const identity = [appId, packageId, ...deploymentIds].sort().join("\x00");
+    return `cli-${(0, hermes_base_1.sha256Hex)(Buffer.from(identity)).slice(0, 64)}`;
+}
+function standaloneDraftOperationKey(appId, packageId, targets) {
+    const identity = [
+        appId,
+        packageId,
+        'save',
+        ...targets
+            .map((target) => `${target.channelId}\x00${target.packageVersion}\x00${target.rollout}`)
+            .sort(),
+    ].join('\x00');
+    return `cli-${(0, hermes_base_1.sha256Hex)(Buffer.from(identity)).slice(0, 64)}`;
+}
+/** Keep Hermes verification fields separate from the user's opaque metaInfo. */
+function standaloneHermesOutcomeFields(value) {
+    if (!value?.hermesBaseOutcome)
+        return {};
+    const fields = {
+        hermesBaseOutcome: value.hermesBaseOutcome,
+    };
+    const detail = (0, hermes_base_1.truncateHermesBaseDetail)(value.hermesBaseDetail);
+    if (detail)
+        fields.hermesBaseDetail = detail;
+    return fields;
+}
+async function findStandalonePackageByHash(appId, hash) {
+    const pageSize = 100;
+    for (let page = 1;; page += 1) {
+        const response = await (0, api_1.get)((0, api_1.servicePath)(`/apps/${encodeURIComponent(appId)}/update-packages?page=${page}&pageSize=${pageSize}`));
+        const result = (0, api_1.unwrapData)(response);
+        const existing = result.items?.find((item) => item.hash === hash);
+        if (existing)
+            return existing;
+        if (!result.items?.length || (result.total !== undefined && page * pageSize >= result.total)) {
+            return undefined;
+        }
+    }
+}
+/** Convert CLI channel codes/targets into UUID targets used by the Go API. */
+async function resolveStandaloneTargets(appId, options, dryRun = false) {
+    const channels = await (0, api_1.getChannels)(appId);
+    const byCode = new Map(channels.map((channel) => [channel.code, channel]));
+    const byId = new Map(channels.map((channel) => [channel.id, channel]));
+    let rawTargets;
+    if (options.targets) {
+        let parsed;
+        try {
+            parsed = JSON.parse(fs_1.default.readFileSync(String(options.targets), 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`无法读取 targets 文件：${error instanceof Error ? error.message : String(error)}`);
+        }
+        const candidate = Array.isArray(parsed)
+            ? parsed
+            : parsed &&
+                typeof parsed === 'object' &&
+                Array.isArray(parsed.targets)
+                ? parsed.targets
+                : null;
+        if (!candidate) {
+            throw new Error('targets.json 必须是数组，或包含 targets 数组。');
+        }
+        rawTargets = candidate;
+    }
+    else if (options.packageId) {
+        const packages = (await (0, api_1.getAllPackages)(appId)) ?? [];
+        const selected = packages.find((pkg) => String(pkg.id) === String(options.packageId));
+        if (!selected) {
+            throw new Error((0, i18n_1.t)('nativePackageIdNotFound', { id: options.packageId }));
+        }
+        const packageVersion = nativePackageVersion(selected);
+        if (!selected.channelId || !packageVersion) {
+            throw new Error('指定的原生包缺少渠道或版本信息，无法创建投放目标。');
+        }
+        rawTargets = [
+            {
+                channelId: selected.channelId,
+                packageVersion,
+            },
+        ];
+    }
+    else {
+        rawTargets = [
+            {
+                channel: options.channel || 'default',
+                packageVersion: options.packageVersion,
+            },
+        ];
+    }
+    if (rawTargets.length === 0) {
+        throw new Error('至少指定一个渠道版本组。');
+    }
+    return Promise.all(rawTargets.map(async (target) => {
+        const rawChannel = target.channel || options.channel || 'default';
+        let channel = target.channelId
+            ? byId.get(target.channelId)
+            : byCode.get(rawChannel.trim().toLowerCase());
+        if (!channel && !target.channelId && !dryRun) {
+            const resolved = await (0, app_1.getOrCreateChannel)(appId, rawChannel);
+            channel = resolved.channel;
+            if (resolved.created) {
+                console.log((0, i18n_1.t)('channelAutoCreated', { channel: rawChannel.trim().toLowerCase() }));
+            }
+        }
+        if (!channel) {
+            throw new Error(`渠道 ${target.channelId || target.channel || options.channel || 'default'} 尚未在应用中登记。`);
+        }
+        const packageVersion = String(target.packageVersion || options.packageVersion || '').trim();
+        if (!packageVersion) {
+            throw new Error('独立服务发布必须指定 packageVersion。');
+        }
+        const targetRollout = resolveTargetRollout(target.rollout === undefined ? options.rollout : target.rollout);
+        return { channelId: channel.id, packageVersion, rollout: targetRollout };
+    }));
+}
+async function publishStandalone(fn, appId, options) {
+    const nonInteractive = (0, options_1.getBooleanOption)(options, 'no-interactive', false) || (0, utils_1.isNonInteractive)();
+    const hasExplicitTargets = hasStandaloneTargetSelection(options);
+    let targets;
+    if (hasExplicitTargets || options.dryRun) {
+        targets = await resolveStandaloneTargets(appId, options, Boolean(options.dryRun));
+    }
+    else if (nonInteractive) {
+        throw new Error((0, i18n_1.t)('standaloneTargetRequired'));
+    }
+    if (options.dryRun) {
+        console.log(JSON.stringify({ appId, targets, dryRun: true }, null, 2));
+        return String(options.name || 'dry-run');
+    }
+    const hash = (0, hermes_base_1.sha256Hex)(fs_1.default.readFileSync(fn));
+    const sourcemapPath = typeof options.sourcemap === 'string' && options.sourcemap.trim()
+        ? options.sourcemap.trim()
+        : undefined;
+    if (sourcemapPath && !fs_1.default.existsSync(sourcemapPath)) {
+        throw new Error((0, i18n_1.t)('sourceMapNotFound', { path: sourcemapPath }));
+    }
+    // Source maps are hot-update artifacts. Pack the map before upload so the
+    // server checks the bytes that will actually be archived, while retaining
+    // the CLI's relative-path/sourceContent slimming contract.
+    let uploadSourcemapPath = sourcemapPath;
+    let packTempDir;
+    if (sourcemapPath) {
+        packTempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'rnu-sourcemap-'));
+        uploadSourcemapPath = path_1.default.join(packTempDir, path_1.default.basename(sourcemapPath));
+        fs_1.default.writeFileSync(uploadSourcemapPath, (0, slim_sourcemap_1.packSourceMap)(fs_1.default.readFileSync(sourcemapPath, 'utf8'), process.cwd()));
+    }
+    let packageValue;
+    let createdNewPackage = false;
+    const existing = await findStandalonePackageByHash(appId, hash);
+    if (existing) {
+        packageValue = existing;
+        if (uploadSourcemapPath) {
+            console.log(chalk_1.default.yellow((0, i18n_1.t)('sourceMapAlreadyArchivedWarning')));
+        }
+        if (packTempDir) {
+            fs_1.default.rmSync(packTempDir, { recursive: true, force: true });
+        }
+    }
+    else {
+        const name = options.name ||
+            (nonInteractive ? '' : await (0, utils_1.question)((0, i18n_1.t)('versionNameQuestion'))) ||
+            (0, i18n_1.t)('unnamed');
+        const description = options.description ??
+            (nonInteractive ? '' : await (0, utils_1.question)((0, i18n_1.t)('versionDescriptionQuestion')));
+        const metaInfo = options.metaInfo ??
+            (nonInteractive ? '' : await (0, utils_1.question)((0, i18n_1.t)('versionMetaInfoQuestion')));
+        try {
+            const [uploaded, sourceMapUpload] = await Promise.all([
+                (0, api_1.uploadFile)(fn, undefined, appId),
+                uploadSourcemapPath ? (0, api_1.uploadFile)(uploadSourcemapPath, undefined, appId) : Promise.resolve(undefined),
+            ]);
+            const fullKey = uploaded.key || uploaded.hash;
+            const sourceMapKey = sourceMapUpload?.key || sourceMapUpload?.hash;
+            const response = await (0, api_1.post)((0, api_1.servicePath)(`/apps/${encodeURIComponent(appId)}/update-packages`), {
+                name,
+                hash,
+                description,
+                metaInfo,
+                ...standaloneHermesOutcomeFields(options.hermesBase),
+                diffVersion: 0,
+                ...(options.diffFromHash ? { diffFromHash: options.diffFromHash } : {}),
+                fullKey,
+                diffKey: '',
+                pdiffKey: '',
+                ...(sourceMapKey ? { sourceMapKey } : {}),
+            });
+            packageValue = (0, api_1.unwrapData)(response);
+            createdNewPackage = true;
+        }
+        catch (error) {
+            const raced = await findStandalonePackageByHash(appId, hash);
+            if (!raced)
+                throw error;
+            packageValue = raced;
+        }
+        finally {
+            if (packTempDir) {
+                fs_1.default.rmSync(packTempDir, { recursive: true, force: true });
+            }
+        }
+    }
+    if (!targets) {
+        const bind = await (0, utils_1.question)((0, i18n_1.t)('updateNativePackageQuestion'));
+        if (bind.toLowerCase() !== 'y') {
+            if (createdNewPackage) {
+                console.log((0, i18n_1.t)('packageUploadSuccess', { id: packageValue.id }));
+            }
+            return packageValue.id;
+        }
+        targets = [await chooseStandaloneTarget(appId, options)];
+    }
+    const deploymentResponse = await (0, api_1.get)((0, api_1.servicePath)(`/update-packages/${encodeURIComponent(packageValue.id)}/deployments`));
+    const existingDeployments = (0, api_1.unwrapData)(deploymentResponse);
+    const existingByTarget = new Map(existingDeployments.map((deployment) => [
+        `${deployment.channelId}\x00${deployment.packageVersion}`,
+        deployment,
+    ]));
+    const duplicateTargets = new Set();
+    for (const target of targets) {
+        const targetKey = `${target.channelId}\x00${target.packageVersion}`;
+        if (duplicateTargets.has(targetKey)) {
+            throw new Error(`targets.json 重复指定目标：${target.channelId}/${target.packageVersion}。`);
+        }
+        duplicateTargets.add(targetKey);
+    }
+    const missingTargets = targets.filter((target) => !existingByTarget.has(`${target.channelId}\x00${target.packageVersion}`));
+    const savedByTarget = new Map();
+    if (missingTargets.length > 0) {
+        const draftIdempotencyKey = standaloneDraftOperationKey(appId, packageValue.id, missingTargets);
+        const response = await (0, api_1.post)((0, api_1.servicePath)(`/apps/${encodeURIComponent(appId)}/deployments/batch`), {
+            idempotencyKey: draftIdempotencyKey,
+            commands: missingTargets.map((target) => ({
+                packageId: packageValue.id,
+                channelId: target.channelId,
+                packageVersion: target.packageVersion,
+                rollout: target.rollout,
+                forceBoot: false,
+                action: 'save',
+            })),
+        });
+        const saved = (0, api_1.unwrapData)(response);
+        for (const deployment of saved) {
+            savedByTarget.set(`${deployment.channelId}\x00${deployment.packageVersion}`, deployment);
+        }
+    }
+    const created = targets.map((target) => {
+        const targetKey = `${target.channelId}\x00${target.packageVersion}`;
+        const deployment = existingByTarget.get(targetKey) || savedByTarget.get(targetKey);
+        if (!deployment) {
+            throw new Error(`服务端未返回目标策略：${target.channelId}/${target.packageVersion}。`);
+        }
+        return { ...deployment, ...target, packageId: packageValue.id };
+    });
+    const idempotencyKey = standaloneOperationKey(appId, packageValue.id, created.map((deployment) => deployment.id));
+    try {
+        await (0, api_1.post)((0, api_1.servicePath)(`/apps/${encodeURIComponent(appId)}/deployments/batch`), {
+            idempotencyKey,
+            commands: created.map((deployment) => ({ id: deployment.id, packageId: packageValue.id, channelId: deployment.channelId, packageVersion: deployment.packageVersion, rollout: deployment.rollout, forceBoot: false, action: 'publish', expectedRevision: deployment.revision })),
+        });
+    }
+    catch (error) {
+        console.error(`发布失败，投放 ID：${created.map((deployment) => deployment.id).join(', ')}`);
+        throw error;
+    }
+    console.log(JSON.stringify({ packageId: packageValue.id, deploymentIds: created.map((deployment) => deployment.id), idempotencyKey, targets }, null, 2));
+    return packageValue.id;
+}
+/** Retry publishing deployments returned by a failed standalone publish.
+ *
+ * Retry uses exact deployment ids and revisions; no artifact upload or new
+ * package is created.
+ */
+async function retryStandalonePublish(appId, releaseIdsInput, dryRun = false) {
+    const deploymentIds = releaseIdsInput
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (deploymentIds.length === 0) {
+        throw new Error('deploymentIds 不能为空。');
+    }
+    const deployments = await Promise.all(deploymentIds.map(async (deploymentId) => {
+        const response = await (0, api_1.get)((0, api_1.servicePath)(`/deployments/${encodeURIComponent(deploymentId)}`));
+        const deployment = (0, api_1.unwrapData)(response);
+        if (!deployment || deployment.applicationId !== appId || !deployment.packageId || !deployment.channelId || !deployment.packageVersion) {
+            throw new Error(`投放 ${deploymentId} 不属于应用 ${appId} 或缺少目标身份。`);
+        }
+        return deployment;
+    }));
+    const commands = deployments.map(({ id, packageId, channelId, packageVersion, rollout, forceBoot, revision }) => ({ id, packageId, channelId, packageVersion, rollout, forceBoot, revision, action: 'publish' }));
+    const packageIds = [...new Set(deployments.map((deployment) => deployment.packageId))];
+    if (packageIds.length !== 1) {
+        throw new Error('deploymentIds 必须属于同一个热更新包。');
+    }
+    const idempotencyKey = standaloneOperationKey(appId, packageIds[0], deploymentIds);
+    if (dryRun) {
+        console.log(JSON.stringify({ appId, deploymentIds, idempotencyKey, commands, dryRun: true }, null, 2));
+        return deploymentIds.join(',');
+    }
+    await (0, api_1.post)((0, api_1.servicePath)(`/apps/${encodeURIComponent(appId)}/deployments/batch`), { idempotencyKey, commands });
+    console.log(JSON.stringify({ deploymentIds, idempotencyKey, commands, retried: true }, null, 2));
+    return deploymentIds.join(',');
+}
+/**
+ * Upload and register one native-package patch for one exact build.
+ *
+ * The server deliberately does not expose a group-wide pdiff field for this
+ * command: a patch is only valid against the nativeVersionId it was built
+ * from. A dry-run resolves local arguments but never uploads or mutates a
+ * release mapping.
+ */
+async function registerStandalonePdiff(filePath, options) {
+    if (!(0, http_helper_1.isStandaloneService)()) {
+        throw new Error('逐构建 pdiff 登记需要独立服务（请设置 RNU_SERVICE_URL）。');
+    }
+    const deploymentId = String(options.deploymentId || options.releaseId || '').trim();
+    const nativeVersionId = String(options.nativeVersionId || '').trim();
+    const diffFromHash = String(options.diffFromHash || '').trim().toLowerCase();
+    if (!deploymentId || !nativeVersionId || !diffFromHash) {
+        throw new Error('pdiff 登记需要 --deploymentId、--nativeVersionId 和 --diffFromHash。');
+    }
+    if (!/^[0-9a-f]{64}$/.test(diffFromHash)) {
+        throw new Error('--diffFromHash 必须是 64 位小写 SHA-256 摘要。');
+    }
+    if (!filePath || !fs_1.default.existsSync(filePath)) {
+        throw new Error(`pdiff 文件不存在：${filePath || '(未指定)'}`);
+    }
+    const patchSuffixes = ['.apk.patch', '.ipa.patch', '.hap.patch', '.app.patch'];
+    if (!patchSuffixes.some((suffix) => filePath.toLowerCase().endsWith(suffix))) {
+        throw new Error('pdiff 文件必须以 .apk.patch、.ipa.patch、.hap.patch 或 .app.patch 结尾。');
+    }
+    const appId = await (0, app_1.resolveAppId)(options);
+    if (options.dryRun) {
+        const preview = { appId, deploymentId, nativeVersionId, diffFromHash, filePath, dryRun: true };
+        console.log(JSON.stringify(preview, null, 2));
+        return deploymentId;
+    }
+    const uploaded = await (0, api_1.uploadFile)(filePath, undefined, appId);
+    const key = uploaded.key || uploaded.hash;
+    const response = await (0, api_1.put)((0, api_1.servicePath)(`/deployments/${encodeURIComponent(deploymentId)}/pdiffs/${encodeURIComponent(nativeVersionId)}`), { diffFromHash, key });
+    const mapping = (0, api_1.unwrapData)(response);
+    const result = {
+        deploymentId,
+        nativeVersionId,
+        diffFromHash,
+        key: mapping?.key || key,
+        id: mapping?.id,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    return deploymentId;
+}

package/lib/symbolicate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * [INPUT]: 依赖 source-map、服务端版本查询、应用选择、网络运行时与 source map 裁剪器
+ * [OUTPUT]: 对外提供 FrameConsumer、symbolicateStack 与 symbolicateCommands
+ * [POS]: CLI 崩溃栈符号化边界，把发布 bundle 的栈位置映射回源码，不参与 bundle 构建
+ */
+export interface FrameConsumer {
+    originalPositionFor(position: {
+        line: number;
+        column: number;
+    }): {
+        source?: string | null;
+        line?: number | null;
+        column?: number | null;
+        name?: string | null;
+    };
+}
+/**
+ * Rewrites every bundle frame of `stack` to its original source position.
+ * JS engines report 1-based columns, so they are shifted to the 0-based
+ * columns source maps use; Hermes bytecode frames (`address at`) carry the
+ * bytecode offset, which the composed hermes map keys directly.
+ */
+export declare function symbolicateStack(stack: string, consumer: FrameConsumer): {
+    text: string;
+    mapped: number;
+};
+export declare const symbolicateCommands: {
+    symbolicate: ({ args, options, }: {
+        args: string[];
+        options: Record<string, unknown>;
+    }) => Promise<{
+        versionId: string;
+        mapped: number;
+    }>;
+};

package/lib/symbolicate.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * [INPUT]: 依赖 source-map、服务端版本查询、应用选择、网络运行时与 source map 裁剪器
+ * [OUTPUT]: 对外提供 FrameConsumer、symbolicateStack 与 symbolicateCommands
+ * [POS]: CLI 崩溃栈符号化边界，把发布 bundle 的栈位置映射回源码，不参与 bundle 构建
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symbolicateCommands = void 0;
+exports.symbolicateStack = symbolicateStack;
+const fs_1 = __importDefault(require("fs"));
+const source_map_1 = require("source-map");
+const api_1 = require("./api");
+const app_1 = require("./app");
+const i18n_1 = require("./utils/i18n");
+const runtime_1 = require("./utils/runtime");
+const slim_sourcemap_1 = require("./utils/slim-sourcemap");
+const versions_1 = require("./versions");
+// A frame location inside a shipped bundle: `<bundle>:<line>:<column>`. Covers
+// `index.bundlejs`, `index.android.bundle`, `main.jsbundle`, `bundle.harmony.js`
+// and plain `.js`/`.hbc` names; an optional `address at ` prefix marks a
+// Hermes bytecode frame (column = bytecode offset, already 0-based).
+const FRAME_PATTERN = /(address at )?((?:[\w.-]+\/)*[\w.-]+\.(?:bundlejs|jsbundle|bundle|hbc|js))(?:\?[^\s:)]*)?:(\d+):(\d+)/g;
+/**
+ * Rewrites every bundle frame of `stack` to its original source position.
+ * JS engines report 1-based columns, so they are shifted to the 0-based
+ * columns source maps use; Hermes bytecode frames (`address at`) carry the
+ * bytecode offset, which the composed hermes map keys directly.
+ */
+function symbolicateStack(stack, consumer) {
+    let mapped = 0;
+    const text = stack.replace(FRAME_PATTERN, (frame, hermes, _bundle, line, column) => {
+        const position = consumer.originalPositionFor({
+            line: Number(line),
+            column: hermes ? Number(column) : Math.max(0, Number(column) - 1),
+        });
+        if (!position.source ||
+            position.line === null ||
+            position.line === undefined) {
+            return frame;
+        }
+        mapped++;
+        const original = `${position.source}:${position.line}:${(position.column ?? 0) + 1}`;
+        return position.name ? `${original} (${position.name})` : original;
+    });
+    return { text, mapped };
+}
+async function findVersionByHash(appId, hash) {
+    const limit = 100;
+    // The list is newest-first; crashes are usually about recent versions.
+    for (let offset = 0; offset < 100 * limit; offset += limit) {
+        const page = await (0, versions_1.fetchVersions)(appId, offset, limit);
+        const found = page.find((version) => version.hash === hash);
+        if (found) {
+            return found;
+        }
+        if (page.length < limit) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function readStack(source) {
+    if (!source || source === '-') {
+        // No file and an interactive terminal: nothing is piped in, so waiting on
+        // stdin would just hang. `-` is an explicit request for stdin either way.
+        if (!source && process.stdin.isTTY) {
+            throw new Error((0, i18n_1.t)('symbolicateUsage'));
+        }
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            process.stdin.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            process.stdin.on('error', reject);
+        });
+    }
+    return fs_1.default.readFileSync(source, 'utf8');
+}
+exports.symbolicateCommands = {
+    symbolicate: async ({ args, options, }) => {
+        const hash = typeof options.hash === 'string' ? options.hash : '';
+        const versionIdOption = typeof options.versionId === 'string' ? options.versionId : '';
+        if (!hash && !versionIdOption) {
+            throw new Error((0, i18n_1.t)('symbolicateUsage'));
+        }
+        const platform = await (0, app_1.getPlatform)(typeof options.platform === 'string'
+            ? options.platform
+            : undefined);
+        const appId = typeof options.appId === 'string' && options.appId
+            ? options.appId
+            : (await (0, app_1.getSelectedApp)(platform, options.config))
+                .appId;
+        let versionId = versionIdOption;
+        if (!versionId) {
+            const version = await findVersionByHash(appId, hash);
+            if (!version) {
+                throw new Error((0, i18n_1.t)('symbolicateVersionNotFound', { hash }));
+            }
+            versionId = String(version.id);
+        }
+        const located = await (0, api_1.get)(`/app/${appId}/version/${versionId}/sourceMap`);
+        if (!located?.url) {
+            throw new Error((0, i18n_1.t)('symbolicateNoSourceMap', { id: versionId }));
+        }
+        const response = await (0, runtime_1.webFetch)(located.url);
+        if (!response.ok) {
+            throw new Error(`Failed to download source map: HTTP ${response.status}`);
+        }
+        // Maps archived by recent CLI versions are gzipped; older ones are plain
+        // JSON, and unpackSourceMap accepts both.
+        const rawMap = JSON.parse((0, slim_sourcemap_1.unpackSourceMap)(Buffer.from(await response.arrayBuffer())));
+        const consumer = new source_map_1.SourceMapConsumer(rawMap);
+        const stack = await readStack(args[0]);
+        const { text, mapped } = symbolicateStack(stack, consumer);
+        if (typeof options.output === 'string' && options.output) {
+            fs_1.default.writeFileSync(options.output, text);
+        }
+        else {
+            process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+        }
+        console.error((0, i18n_1.t)('symbolicateDone', {
+            count: mapped,
+            id: versionId,
+            hash: located.hash ?? hash,
+        }));
+        return { versionId, mapped };
+    },
+};