@bravemobile/react-native-code-push 13.0.0 → 13.1.0-beta.0

package/cli/dist/functions/makeBinaryPatchBundle.js

@@ -0,0 +1,248 @@
+/**
+ * Builds the binary patch artifact that ships alongside a full CodePush update.
+ *
+ * A patch archive is the full archive with the JS bundle swapped for a patch against
+ * the bundle that is already inside the app binary, plus a manifest describing how to
+ * rebuild it. Every other file (assets and so on) is copied over untouched, so a
+ * client that applies the patch and drops the two patch-only files holds byte-for-byte
+ * the same contents as the full archive - and therefore computes the same
+ * `packageHash`. That is what lets one release serve both artifacts.
+ *
+ * The archive is produced from an already assembled contents directory rather than
+ * from the bundler, so it is independent of Metro and Hermes: whoever prepared the
+ * contents (a fresh bundle run, or an existing bundle file unpacked for
+ * `--skip-bundle`) gets the same artifact.
+ */
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import shell from "shelljs";
+import { BINARY_PATCH_ALGORITHM, BINARY_PATCH_FORMAT_VERSION, generatePatch, } from "../utils/binaryPatch.js";
+import { unzip } from "../utils/unzip.js";
+import { zip } from "../utils/zip.js";
+/** Manifest file a client reads to decide whether it can apply the patch, and how. */
+export const BINARY_PATCH_MANIFEST_NAME = 'codepush-binary-patch.json';
+/** Appended to the full archive name so the two artifacts of a release stay paired. */
+export const BINARY_PATCH_ARCHIVE_SUFFIX = '-patch.zip';
+/**
+ * Record the `bundle` command leaves in the output root - outside the update contents,
+ * so it never reaches the archive - to say which base bundle the JS bundle was
+ * compiled against. A later `release` compares it with the base it was given.
+ *
+ * The build hooks (`android/codepush-export.gradle`, `scripts/export-embedded-bundle.sh`)
+ * write a record of the same name next to the bundle they export from a native build,
+ * which is what makes that bundle self-describing when it is later passed to
+ * `release --binary-bundle-path`.
+ */
+export const BINARY_PATCH_BASE_RECORD_NAME = 'binary-patch-base.json';
+const TEMP_PATCH_CONTENTS_DIR_NAME = 'temp_contents_for_binary_patch';
+const TEMP_EXTRACTED_CONTENTS_DIR_NAME = 'temp_contents_from_bundle_file';
+const HASH_ALGORITHM = 'sha256';
+/** SHA-256 of a single file's bytes, which is what the manifest records. */
+export function hashBundleFile(filePath) {
+    return crypto.createHash(HASH_ALGORITHM).update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * Resolves the `--binary-bundle-path` option to an absolute path, rejecting anything
+ * that is not an existing file. Called before the bundler runs so a typo surfaces
+ * before minutes of bundling rather than after.
+ */
+export function resolveBaseBundlePath(binaryBundlePath) {
+    const resolved = path.resolve(binaryBundlePath);
+    let stats;
+    try {
+        stats = fs.statSync(resolved);
+    }
+    catch {
+        throw new Error(`--binary-bundle-path "${binaryBundlePath}" does not exist.`);
+    }
+    if (!stats.isFile()) {
+        throw new Error(`--binary-bundle-path "${binaryBundlePath}" is not a file.`);
+    }
+    return resolved;
+}
+/**
+ * Same as `resolveBaseBundlePath`, but reports the problem the way the other CLI
+ * options do. Returns `undefined` when the option was not passed at all.
+ */
+export function resolveBinaryBundlePathOption(binaryBundlePath) {
+    if (!binaryBundlePath) {
+        return undefined;
+    }
+    try {
+        return resolveBaseBundlePath(binaryBundlePath);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+/**
+ * Creates the patch archive for an update that has already been assembled.
+ *
+ * @param contentsPath {string} Directory holding the update contents that went into the full archive
+ * @param baseBundlePath {string} JS bundle from the target binary, which the patch is computed against
+ * @param bundleRelativePath {string} Target bundle path inside `contentsPath`
+ * @param bundleDirectory {string} Directory the full archive was written to
+ * @param packageHash {string} Package hash of the full archive, which names both artifacts
+ */
+export async function makeBinaryPatchBundle({ contentsPath, baseBundlePath, bundleRelativePath, bundleDirectory, packageHash, }) {
+    const resolvedContentsPath = path.resolve(contentsPath);
+    const targetBundlePath = path.join(resolvedContentsPath, bundleRelativePath);
+    if (!isFile(targetBundlePath)) {
+        throw new Error(`Target bundle "${bundleRelativePath}" was not found in the update contents ("${resolvedContentsPath}"). ` +
+            `Pass -j/--js-bundle-name if the bundle file has a different name.`);
+    }
+    const resolvedBaseBundlePath = resolveBaseBundlePath(baseBundlePath);
+    const baseBundleHash = hashBundleFile(resolvedBaseBundlePath);
+    const targetBundleHash = hashBundleFile(targetBundlePath);
+    if (baseBundleHash === targetBundleHash) {
+        console.warn('warn: The base bundle and the target bundle are identical, so the update changes nothing. Releasing anyway.');
+    }
+    // Kept next to the update contents rather than in the system temp directory so a
+    // crash leaves the leftovers where the rest of the build output is cleaned up.
+    const tempRoot = path.join(path.dirname(resolvedContentsPath), TEMP_PATCH_CONTENTS_DIR_NAME);
+    // The archive root directory name is part of the contents layout, so the patch
+    // archive has to reuse the name the full archive used.
+    const patchContentsPath = path.join(tempRoot, path.basename(resolvedContentsPath));
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+    try {
+        fs.cpSync(resolvedContentsPath, patchContentsPath, { recursive: true });
+        fs.rmSync(path.join(patchContentsPath, bundleRelativePath));
+        const patchRelativePath = `${bundleRelativePath}.patch`;
+        generatePatch(resolvedBaseBundlePath, targetBundlePath, path.join(patchContentsPath, patchRelativePath));
+        const manifest = {
+            formatVersion: BINARY_PATCH_FORMAT_VERSION,
+            algorithm: BINARY_PATCH_ALGORITHM,
+            bundlePath: bundleRelativePath,
+            patchFile: patchRelativePath,
+            baseBundleHash,
+            targetBundleHash,
+            targetBundleSize: fs.statSync(targetBundlePath).size,
+        };
+        fs.writeFileSync(path.join(patchContentsPath, BINARY_PATCH_MANIFEST_NAME), JSON.stringify(manifest, null, 2));
+        const patchArchiveZipPath = await zip(patchContentsPath);
+        const patchBundleFilePath = path.join(bundleDirectory, `${packageHash}${BINARY_PATCH_ARCHIVE_SUFFIX}`);
+        shell.mkdir('-p', bundleDirectory);
+        shell.mv(patchArchiveZipPath, patchBundleFilePath);
+        return { patchBundleFilePath, manifest };
+    }
+    finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+}
+/**
+ * Unpacks an already built CodePush bundle file, so `release --skip-bundle` can patch
+ * exactly the contents that were packed instead of bundling them again.
+ *
+ * @return The extraction directory, which the caller owns and must remove, and the
+ * update contents root inside it.
+ */
+export async function extractCodePushBundleContents(bundleFilePath, parentDirectory) {
+    const extractDir = path.resolve(path.join(parentDirectory, TEMP_EXTRACTED_CONTENTS_DIR_NAME));
+    fs.rmSync(extractDir, { recursive: true, force: true });
+    fs.mkdirSync(extractDir, { recursive: true });
+    try {
+        await unzip(path.resolve(bundleFilePath), extractDir);
+    }
+    catch (error) {
+        fs.rmSync(extractDir, { recursive: true, force: true });
+        throw error;
+    }
+    return { extractDir, contentsPath: resolveExtractedContentsPath(extractDir) };
+}
+/**
+ * A CodePush archive wraps its files in a single directory, so that directory - not
+ * the extraction directory - is the contents root.
+ */
+function resolveExtractedContentsPath(extractDir) {
+    const entries = fs.readdirSync(extractDir, { withFileTypes: true });
+    if (entries.length === 1 && entries[0].isDirectory()) {
+        return path.join(extractDir, entries[0].name);
+    }
+    return extractDir;
+}
+/** Records which base bundle the JS bundle in `outputRootPath` was compiled against. */
+export function writeBinaryPatchBaseRecord(outputRootPath, baseBundleHash) {
+    const recordPath = path.join(outputRootPath, BINARY_PATCH_BASE_RECORD_NAME);
+    const record = { baseBundleHash };
+    fs.mkdirSync(outputRootPath, { recursive: true });
+    fs.writeFileSync(recordPath, JSON.stringify(record, null, 2));
+    return recordPath;
+}
+/**
+ * Reads the record left by a previous `bundle` run. An unreadable record is treated as
+ * no record: it only feeds a warning, and must never be able to fail a release.
+ */
+export function readBinaryPatchBaseRecord(outputRootPath) {
+    const recordPath = path.join(outputRootPath, BINARY_PATCH_BASE_RECORD_NAME);
+    try {
+        const record = JSON.parse(fs.readFileSync(recordPath, 'utf8'));
+        if (typeof record.baseBundleHash !== 'string') {
+            return null;
+        }
+        return { baseBundleHash: record.baseBundleHash };
+    }
+    catch {
+        return null;
+    }
+}
+/** Accepted `--on-oversized-patch` values, in the order the help text lists them. */
+export const OVERSIZED_PATCH_POLICIES = ['skip', 'fail'];
+export const DEFAULT_OVERSIZED_PATCH_POLICY = 'skip';
+/**
+ * Whether the patch archive is worth publishing next to the full archive.
+ *
+ * Equal sizes count as oversized: a patch that saves nothing still costs a client the
+ * download plus an apply step, so it is never the better artifact of the two.
+ */
+export function isPatchArchiveOversized(fullArchiveSize, patchArchiveSize) {
+    return patchArchiveSize >= fullArchiveSize;
+}
+/**
+ * The operator-facing summary, printed before the artifacts are uploaded so the size of
+ * what is about to be published is on the record. When the patch is not smaller than the
+ * full archive and the release is going ahead without it, the summary says so rather
+ * than leaving a negative saving to be interpreted.
+ */
+export function formatBinaryPatchSummary({ platform, baseBundleHash, targetBundleHash, fullArchiveSize, patchArchiveSize, patchSkipped = false, }) {
+    const savedBytes = fullArchiveSize - patchArchiveSize;
+    const savedRatio = fullArchiveSize > 0 ? savedBytes / fullArchiveSize : 0;
+    const sizes = [fullArchiveSize, patchArchiveSize, savedBytes].map(formatBytes);
+    const sizeWidth = Math.max(...sizes.map((size) => size.length));
+    const [fullSize, patchSize, savedSize] = sizes.map((size) => size.padStart(sizeWidth));
+    const label = (text) => text.padEnd(23);
+    const lines = [
+        `Binary patch summary (${platform})`,
+        `${label('Base bundle SHA-256:')}${baseBundleHash}`,
+        `${label('Target bundle SHA-256:')}${targetBundleHash}`,
+        `${label('Full archive:')}${fullSize}`,
+        `${label('Patch archive:')}${patchSize}`,
+        `${label('Saved:')}${savedSize} (${(savedRatio * 100).toFixed(1)}%)`,
+    ];
+    if (patchSkipped) {
+        lines.push(`${label('Patch skipped:')}not smaller than the full archive; releasing the full bundle only (--on-oversized-patch skip)`);
+    }
+    return lines.join('\n');
+}
+function formatBytes(bytes) {
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    if (Math.abs(bytes) < 1024) {
+        return `${bytes} B`;
+    }
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (Math.abs(value) >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+function isFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/cli/dist/functions/makeBinaryPatchBundle.test.js

@@ -0,0 +1,321 @@
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterAll, afterEach, beforeAll, describe, expect, it, jest } from "@jest/globals";
+import { BINARY_PATCH_ARCHIVE_SUFFIX, BINARY_PATCH_BASE_RECORD_NAME, BINARY_PATCH_MANIFEST_NAME, extractCodePushBundleContents, formatBinaryPatchSummary, isPatchArchiveOversized, makeBinaryPatchBundle, readBinaryPatchBaseRecord, resolveBaseBundlePath, writeBinaryPatchBaseRecord, } from "./makeBinaryPatchBundle.js";
+import { makeCodePushBundle } from "./makeCodePushBundle.js";
+import { applyPatch, BINARY_PATCH_ALGORITHM, BINARY_PATCH_FORMAT_VERSION } from "../utils/binaryPatch.js";
+import { generatePackageHashFromDirectory } from "../utils/hash-utils.js";
+import { unzip } from "../utils/unzip.js";
+/**
+ * Exercises the patch artifact against real archives, real hdiffz output and real
+ * hashes: the artifact only has value if a client can rebuild the exact contents of
+ * the full archive from it, and only real bytes prove that.
+ */
+/** The directory a CodePush archive keeps its contents in, for legacy reasons. */
+const CONTENTS_DIR_NAME = 'CodePush';
+function findRepoRoot() {
+    let dir = process.cwd();
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "scripts", "binary-patch", "build-hdiffpatch.sh"))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`cannot locate the repository root from ${process.cwd()}`);
+        }
+        dir = parent;
+    }
+}
+const repoRoot = findRepoRoot();
+const fixtureDir = path.join(repoRoot, "cli", "fixtures", "binary-patch");
+const baseFixture = path.join(fixtureDir, "base.bundle");
+const targetFixture = path.join(fixtureDir, "target.bundle");
+let workDir;
+function sha256(filePath) {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+/** A unique directory per test so a failed run never leaks state into the next one. */
+function makeCaseDir(name) {
+    const caseDir = fs.mkdtempSync(path.join(workDir, `${name}-`));
+    return caseDir;
+}
+/**
+ * Writes an update contents directory shaped like the one the bundler produces: the
+ * JS bundle next to the assets that ship with it.
+ */
+function writeUpdateContents(caseDir, files) {
+    const contentsPath = path.join(caseDir, CONTENTS_DIR_NAME);
+    for (const [relativePath, content] of Object.entries(files)) {
+        const filePath = path.join(contentsPath, relativePath);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content);
+    }
+    return contentsPath;
+}
+function defaultContents(caseDir, bundleName = 'main.jsbundle') {
+    return writeUpdateContents(caseDir, {
+        [bundleName]: fs.readFileSync(targetFixture),
+        'assets/logo.png': Buffer.from('logo-bytes'),
+    });
+}
+async function unzipTo(archivePath, destination) {
+    fs.mkdirSync(destination, { recursive: true });
+    await unzip(archivePath, destination);
+    return path.join(destination, CONTENTS_DIR_NAME);
+}
+beforeAll(() => {
+    // hdiffz/hpatchz are provisioned for the whole run by the jest global setup.
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "codepush-patch-bundle-"));
+});
+afterAll(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+describe("resolveBaseBundlePath", () => {
+    it("returns an absolute path for an existing file", () => {
+        expect(resolveBaseBundlePath(path.relative(process.cwd(), baseFixture))).toBe(baseFixture);
+    });
+    it("fails with a message naming the option when the file does not exist", () => {
+        const missing = path.join(makeCaseDir("missing-base"), "no-such.bundle");
+        expect(() => resolveBaseBundlePath(missing)).toThrow(/--binary-bundle-path/);
+        expect(() => resolveBaseBundlePath(missing)).toThrow(/does not exist/);
+    });
+    it("fails when the path is a directory", () => {
+        expect(() => resolveBaseBundlePath(fixtureDir)).toThrow(/is not a file/);
+    });
+});
+describe("makeBinaryPatchBundle", () => {
+    it("writes a patch archive next to the full archive, named after the package hash", async () => {
+        const caseDir = makeCaseDir("names");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { bundleFileName: packageHash } = await makeCodePushBundle(contentsPath, bundleDirectory);
+        const { patchBundleFilePath } = await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash,
+        });
+        expect(path.basename(patchBundleFilePath)).toBe(`${packageHash}${BINARY_PATCH_ARCHIVE_SUFFIX}`);
+        expect(fs.existsSync(patchBundleFilePath)).toBe(true);
+        // The full archive stays exactly as it was uploaded before patches existed.
+        expect(fs.readdirSync(bundleDirectory).sort()).toEqual([packageHash, `${packageHash}${BINARY_PATCH_ARCHIVE_SUFFIX}`].sort());
+    });
+    it("pins the manifest to the codec contract and to the target bundle it describes", async () => {
+        const caseDir = makeCaseDir("manifest");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { patchBundleFilePath, manifest } = await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash: 'package-hash',
+        });
+        expect(manifest).toEqual({
+            formatVersion: BINARY_PATCH_FORMAT_VERSION,
+            algorithm: BINARY_PATCH_ALGORITHM,
+            bundlePath: 'main.jsbundle',
+            patchFile: 'main.jsbundle.patch',
+            baseBundleHash: sha256(baseFixture),
+            targetBundleHash: sha256(targetFixture),
+            targetBundleSize: fs.statSync(targetFixture).size,
+        });
+        const extracted = await unzipTo(patchBundleFilePath, path.join(caseDir, "extracted"));
+        expect(JSON.parse(fs.readFileSync(path.join(extracted, BINARY_PATCH_MANIFEST_NAME), 'utf8'))).toEqual(manifest);
+    });
+    it("replaces the target bundle with its patch and keeps every other file", async () => {
+        const caseDir = makeCaseDir("layout");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { patchBundleFilePath } = await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash: 'package-hash',
+        });
+        const extracted = await unzipTo(patchBundleFilePath, path.join(caseDir, "extracted"));
+        expect(fs.existsSync(path.join(extracted, 'main.jsbundle'))).toBe(false);
+        expect(fs.existsSync(path.join(extracted, 'main.jsbundle.patch'))).toBe(true);
+        expect(fs.readFileSync(path.join(extracted, 'assets/logo.png'), 'utf8')).toBe('logo-bytes');
+    });
+    it("restores the exact package hash of the full archive from the patch archive", async () => {
+        const caseDir = makeCaseDir("round-trip");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { bundleFileName: packageHash } = await makeCodePushBundle(contentsPath, bundleDirectory);
+        const { patchBundleFilePath, manifest } = await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash,
+        });
+        // Replay what a client does: apply the patch onto the bundle from the binary,
+        // then drop the patch artifacts that are not part of the update contents.
+        const extractRoot = path.join(caseDir, "extracted");
+        const extracted = await unzipTo(patchBundleFilePath, extractRoot);
+        applyPatch(baseFixture, path.join(extracted, manifest.patchFile), path.join(extracted, manifest.bundlePath));
+        fs.rmSync(path.join(extracted, manifest.patchFile));
+        fs.rmSync(path.join(extracted, BINARY_PATCH_MANIFEST_NAME));
+        expect(sha256(path.join(extracted, manifest.bundlePath))).toBe(sha256(targetFixture));
+        expect(await generatePackageHashFromDirectory(extracted, extractRoot)).toBe(packageHash);
+    });
+    it("patches only the bundle named by the caller, leaving another platform's bundle untouched", async () => {
+        const caseDir = makeCaseDir("android");
+        const contentsPath = writeUpdateContents(caseDir, {
+            'index.android.bundle': fs.readFileSync(targetFixture),
+            'main.jsbundle': Buffer.from('ios-bundle-bytes'),
+        });
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { patchBundleFilePath, manifest } = await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'index.android.bundle',
+            bundleDirectory,
+            packageHash: 'package-hash',
+        });
+        expect(manifest.bundlePath).toBe('index.android.bundle');
+        expect(manifest.patchFile).toBe('index.android.bundle.patch');
+        const extracted = await unzipTo(patchBundleFilePath, path.join(caseDir, "extracted"));
+        expect(fs.existsSync(path.join(extracted, 'index.android.bundle'))).toBe(false);
+        expect(fs.readFileSync(path.join(extracted, 'main.jsbundle'), 'utf8')).toBe('ios-bundle-bytes');
+    });
+    it("warns when the base and the target bundle are the same bytes", async () => {
+        const caseDir = makeCaseDir("identical");
+        const contentsPath = writeUpdateContents(caseDir, { 'main.jsbundle': fs.readFileSync(baseFixture) });
+        const warn = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory: path.join(caseDir, "bundleOutput"),
+            packageHash: 'package-hash',
+        });
+        expect(warn.mock.calls.join('\n')).toMatch(/identical/);
+    });
+    it("fails with an actionable error when the target bundle is not in the contents", async () => {
+        const caseDir = makeCaseDir("no-target");
+        const contentsPath = writeUpdateContents(caseDir, { 'index.android.bundle': Buffer.from('android') });
+        await expect(makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory: path.join(caseDir, "bundleOutput"),
+            packageHash: 'package-hash',
+        })).rejects.toThrow(/main\.jsbundle.*--js-bundle-name/s);
+    });
+    it("leaves no working directory behind, whether it succeeds or fails", async () => {
+        const caseDir = makeCaseDir("cleanup");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const entriesBefore = fs.readdirSync(caseDir).sort();
+        await makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: baseFixture,
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash: 'package-hash',
+        });
+        expect(fs.readdirSync(caseDir).sort()).toEqual([...entriesBefore, 'bundleOutput'].sort());
+        await expect(makeBinaryPatchBundle({
+            contentsPath,
+            baseBundlePath: path.join(caseDir, 'no-such-base.bundle'),
+            bundleRelativePath: 'main.jsbundle',
+            bundleDirectory,
+            packageHash: 'package-hash',
+        })).rejects.toThrow();
+        expect(fs.readdirSync(caseDir).sort()).toEqual([...entriesBefore, 'bundleOutput'].sort());
+    });
+});
+describe("binary patch base record", () => {
+    it("is written outside the update contents, so it cannot change the package hash", async () => {
+        const caseDir = makeCaseDir("record");
+        const contentsPath = defaultContents(caseDir);
+        const hashBefore = await generatePackageHashFromDirectory(contentsPath, caseDir);
+        const recordPath = writeBinaryPatchBaseRecord(caseDir, sha256(baseFixture));
+        expect(path.relative(contentsPath, recordPath).startsWith('..')).toBe(true);
+        expect(path.basename(recordPath)).toBe(BINARY_PATCH_BASE_RECORD_NAME);
+        expect(await generatePackageHashFromDirectory(contentsPath, caseDir)).toBe(hashBefore);
+        expect(readBinaryPatchBaseRecord(caseDir)).toEqual({ baseBundleHash: sha256(baseFixture) });
+    });
+    it("reads as absent when there is no record or the record is unreadable", () => {
+        const caseDir = makeCaseDir("record-missing");
+        expect(readBinaryPatchBaseRecord(caseDir)).toBeNull();
+        fs.writeFileSync(path.join(caseDir, BINARY_PATCH_BASE_RECORD_NAME), 'not json');
+        expect(readBinaryPatchBaseRecord(caseDir)).toBeNull();
+    });
+});
+describe("extractCodePushBundleContents", () => {
+    it("unpacks the contents of an already built bundle file so a patch can be built from it", async () => {
+        const caseDir = makeCaseDir("extract");
+        const contentsPath = defaultContents(caseDir);
+        const bundleDirectory = path.join(caseDir, "bundleOutput");
+        const { bundleFileName } = await makeCodePushBundle(contentsPath, bundleDirectory);
+        const { extractDir, contentsPath: extractedContents } = await extractCodePushBundleContents(path.join(bundleDirectory, bundleFileName), caseDir);
+        expect(await generatePackageHashFromDirectory(extractedContents, path.dirname(extractedContents))).toBe(bundleFileName);
+        expect(fs.existsSync(path.join(extractedContents, 'main.jsbundle'))).toBe(true);
+        fs.rmSync(extractDir, { recursive: true, force: true });
+    });
+});
+describe("isPatchArchiveOversized", () => {
+    it("keeps a patch that is smaller than the full archive", () => {
+        expect(isPatchArchiveOversized(100, 99)).toBe(false);
+    });
+    it("rejects a patch of exactly the same size, which saves a client nothing", () => {
+        expect(isPatchArchiveOversized(100, 100)).toBe(true);
+    });
+    it("rejects a patch that is larger than the full archive", () => {
+        expect(isPatchArchiveOversized(100, 101)).toBe(true);
+    });
+});
+describe("formatBinaryPatchSummary", () => {
+    it("reports both archive sizes and what the patch saves", () => {
+        const baseBundleHash = 'a'.repeat(64);
+        const targetBundleHash = 'b'.repeat(64);
+        const summary = formatBinaryPatchSummary({
+            platform: 'ios',
+            baseBundleHash,
+            targetBundleHash,
+            fullArchiveSize: 19293798,
+            patchArchiveSize: 3250586,
+        });
+        expect(summary).toBe([
+            'Binary patch summary (ios)',
+            `Base bundle SHA-256:   ${baseBundleHash}`,
+            `Target bundle SHA-256: ${targetBundleHash}`,
+            'Full archive:          18.4 MB',
+            'Patch archive:          3.1 MB',
+            'Saved:                 15.3 MB (83.2%)',
+        ].join('\n'));
+    });
+    it("reports a negative saving when the patch is larger than the full archive", () => {
+        const summary = formatBinaryPatchSummary({
+            platform: 'android',
+            baseBundleHash: 'a'.repeat(64),
+            targetBundleHash: 'b'.repeat(64),
+            fullArchiveSize: 1000,
+            patchArchiveSize: 1500,
+        });
+        expect(summary).toContain('Binary patch summary (android)');
+        expect(summary).toContain('Saved:                 -500 B (-50.0%)');
+        expect(summary).not.toContain('Patch skipped:');
+    });
+    it("states that the patch was skipped, and why, when it is not being released", () => {
+        const summary = formatBinaryPatchSummary({
+            platform: 'android',
+            baseBundleHash: 'a'.repeat(64),
+            targetBundleHash: 'b'.repeat(64),
+            fullArchiveSize: 1000,
+            patchArchiveSize: 1500,
+            patchSkipped: true,
+        });
+        expect(summary.split('\n').at(-1)).toBe('Patch skipped:         not smaller than the full archive; releasing the full bundle only (--on-oversized-patch skip)');
+    });
+});

package/cli/dist/functions/makeCodePushBundle.js

@@ -12,8 +12,10 @@ import { generatePackageHashFromDirectory } from "../utils/hash-utils.js";
 export async function makeCodePushBundle(contentsPath, bundleDirectory) {
     const updateContentsZipPath = await zip(contentsPath);
     const packageHash = await generatePackageHashFromDirectory(contentsPath, path.join(contentsPath, '..'));
-    shell.mkdir('-p', `./${bundleDirectory}`);
-    shell.mv(updateContentsZipPath, `./${bundleDirectory}/${packageHash}`);
+    // Joined rather than interpolated so an absolute bundle directory - which an
+    // absolute --output-path produces - is not turned into a path below the cwd.
+    shell.mkdir('-p', bundleDirectory);
+    shell.mv(updateContentsZipPath, path.join(bundleDirectory, packageHash));
     return {
         // To allow the "release" command to get the file and hash value from the result of the "bundle" command,
         // use the hash value as the name of the file.

package/cli/dist/functions/runHermesEmitBinaryCommand.js

@@ -6,6 +6,11 @@ import fs from "fs";
 import path from "path";
 import { createRequire } from "node:module";
 import shell from "shelljs";
+/**
+ * Tells Hermes to lay the compiled bytecode out like an existing bundle's, which keeps
+ * the binary patch between the two small. Older compilers do not have the flag.
+ */
+const BASE_BYTECODE_FLAG = '-base-bytecode';
 /**
  * Run Hermes compile CLI command
  *
@@ -32,7 +37,16 @@ export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcem
         try {
             const hermesCommand = getHermesCommand(projectRoot);
             const disableAllWarningsArg = '-w';
-            shell.exec(`${hermesCommand} ${hermesArgs.join(' ')} ${disableAllWarningsArg}`);
+            const compileResult = shell.exec(`${hermesCommand} ${hermesArgs.join(' ')} ${disableAllWarningsArg}`);
+            if (compileResult.code !== 0) {
+                // Reported here rather than left to the missing .hbc file, so a rejected
+                // flag - a base bundle that is not Hermes bytecode, for instance - fails
+                // the release instead of silently producing an unaligned bundle.
+                const extraFlagsHint = extraHermesFlags.length > 0
+                    ? ` Additional options: ${extraHermesFlags.join(' ')}`
+                    : '';
+                throw new Error(`"hermesc" command failed (exitCode=${compileResult.code}).${extraFlagsHint}`);
+            }
             // Copy HBC bundle to overwrite JS bundle
             const source = path.join(outputPath, bundleName + '.hbc');
             const destination = path.join(outputPath, bundleName);
@@ -89,6 +103,39 @@ export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcem
         });
     });
 }
+/**
+ * Builds the flags that align a compilation with the bundle already inside the app
+ * binary, so the binary patch between them stays small.
+ *
+ * When the app's Hermes compiler predates the flag the release still goes ahead
+ * without it: the patch is then computed against unaligned bytecode and is larger, but
+ * it is still a valid patch. A compiler that does accept the flag and fails is a
+ * different matter and fails the release, because the base input is then wrong.
+ *
+ * @param baseBundlePath {string} JS bundle from the target binary to align against
+ * @param projectRoot {string} Root directory of the target app project, used to locate its Hermes compiler
+ * @return {string[]} Flags to pass to `runHermesEmitBinaryCommand` as `extraHermesFlags`
+ */
+export function resolveBaseBytecodeHermesFlags(baseBundlePath, projectRoot = process.cwd()) {
+    if (!hermesSupportsBaseBytecode(projectRoot)) {
+        console.warn(`warn: The Hermes compiler of this app does not support "${BASE_BYTECODE_FLAG}". ` +
+            'Compiling without it, which makes the binary patch larger.');
+        return [];
+    }
+    return [BASE_BYTECODE_FLAG, baseBundlePath];
+}
+/** Whether a `hermesc --help` output advertises the base bytecode flag. */
+export function helpOutputSupportsBaseBytecode(helpOutput) {
+    return helpOutput.includes(BASE_BYTECODE_FLAG);
+}
+function hermesSupportsBaseBytecode(projectRoot) {
+    const hermesCommand = getHermesCommand(projectRoot);
+    const result = childProcess.spawnSync(hermesCommand, ['--help'], { encoding: 'utf8' });
+    if (result.error) {
+        throw new Error(`failed to run "${hermesCommand} --help": ${result.error.message}`);
+    }
+    return helpOutputSupportsBaseBytecode(`${result.stdout ?? ''}${result.stderr ?? ''}`);
+}
 function getHermesCommand(projectRoot) {
     const fileExists = (file) => {
         try {