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

package/cli/dist/functions/runHermesEmitBinaryCommand.js

@@ -4,7 +4,13 @@
 import childProcess from "child_process";
 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
  *
@@ -12,9 +18,10 @@ import shell from "shelljs";
  * @param outputPath {string} Path to output .hbc file
  * @param sourcemapOutput {string} Path to output sourcemap file (Warning: if sourcemapOutput points to the outputPath, the sourcemap will be included in the CodePush bundle and increase the deployment size)
  * @param extraHermesFlags {string[]} Additional options to pass to `hermesc` command
+ * @param projectRoot {string} Root directory of the target app project used to resolve the app's React Native module and locate the matching Hermes compiler. Defaults to the current working directory.
  * @return {Promise<void>}
  */
-export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcemapOutput, extraHermesFlags = []) {
+export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcemapOutput, extraHermesFlags = [], projectRoot = process.cwd()) {
     const hermesArgs = [
         '-emit-binary',
         '-out',
@@ -28,9 +35,18 @@ export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcem
     console.log('Converting JS bundle to byte code via Hermes, running command:\n');
     return new Promise((resolve, reject) => {
         try {
-            const hermesCommand = getHermesCommand();
+            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);
@@ -47,7 +63,7 @@ export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcem
             return;
         }
         // compose-source-maps.js file path
-        const composeSourceMapsPath = getComposeSourceMapsPath();
+        const composeSourceMapsPath = getComposeSourceMapsPath(projectRoot);
         if (composeSourceMapsPath === null) {
             throw new Error('react-native compose-source-maps.js scripts is not found');
         }
@@ -87,7 +103,40 @@ export async function runHermesEmitBinaryCommand(bundleName, outputPath, sourcem
         });
     });
 }
-function getHermesCommand() {
+/**
+ * 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 {
             return fs.statSync(file).isFile();
@@ -96,7 +145,7 @@ function getHermesCommand() {
             return false;
         }
     };
-    const hermescExecutable = path.join(getHermesCompilerPath(), getHermesOSBin(), getHermesOSExe());
+    const hermescExecutable = path.join(getHermesCompilerPath(projectRoot), getHermesOSBin(), getHermesOSExe());
     if (fileExists(hermescExecutable)) {
         return hermescExecutable;
     }
@@ -124,45 +173,67 @@ function getHermesOSExe() {
             return hermesExecutableName;
     }
 }
-function getComposeSourceMapsPath() {
+function getComposeSourceMapsPath(projectRoot) {
     // detect if compose-source-maps.js script exists
-    const composeSourceMaps = path.join(getReactNativePackagePath(), 'scripts', 'compose-source-maps.js');
+    const composeSourceMaps = path.join(getReactNativePackagePath(projectRoot), 'scripts', 'compose-source-maps.js');
     if (fs.existsSync(composeSourceMaps)) {
         return composeSourceMaps;
     }
     return null;
 }
-function getReactNativePackagePath() {
-    const result = childProcess.spawnSync('node', [
-        '--print',
-        "require.resolve('react-native/package.json')",
-    ]);
-    const packagePath = path.dirname(result.stdout.toString());
-    if (result.status === 0 && directoryExistsSync(packagePath)) {
+function getReactNativePackagePath(projectRoot) {
+    const packagePath = resolvePackageRoot(projectRoot, 'react-native');
+    if (packagePath !== null) {
         return packagePath;
     }
-    return path.join('node_modules', 'react-native');
+    return path.join(projectRoot, 'node_modules', 'react-native');
 }
-function getHermescDirPathInHermesCompilerPackage() {
-    const result = childProcess.spawnSync('node', [
-        '--print',
-        "require.resolve('hermes-compiler/package.json')",
-    ]);
-    const packagePath = path.dirname(result.stdout.toString());
-    const hermescDirPath = path.join(packagePath, 'hermesc');
-    if (result.status === 0 && directoryExistsSync(hermescDirPath)) {
+function getHermescDirPathInHermesCompilerPackage(projectRoot) {
+    const reactNativePackagePath = getReactNativePackagePath(projectRoot);
+    const hermescDirPath = path.join(path.dirname(reactNativePackagePath), 'hermes-compiler', 'hermesc');
+    if (directoryExistsSync(hermescDirPath)) {
         return hermescDirPath;
     }
     return null;
 }
-function getHermesCompilerPath() {
-    const hermescDirPath = getHermescDirPathInHermesCompilerPackage();
+function getHermesCompilerPath(projectRoot) {
+    const hermescDirPath = getHermescDirPathInHermesCompilerPackage(projectRoot);
     if (hermescDirPath) {
         // Since react-native 0.83, Hermes compiler executables are in 'hermes-compiler' package
         return hermescDirPath;
     }
     else {
-        return path.join(getReactNativePackagePath(), 'sdks', 'hermesc');
+        return path.join(getReactNativePackagePath(projectRoot), 'sdks', 'hermesc');
+    }
+}
+function resolvePackageRoot(projectRoot, packageName) {
+    try {
+        const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+        const resolvedPath = projectRequire.resolve(packageName);
+        return findPackageRoot(packageName, resolvedPath);
+    }
+    catch {
+        return null;
+    }
+}
+function findPackageRoot(packageName, resolvedPath) {
+    let currentPath = path.dirname(resolvedPath);
+    while (true) {
+        const packageJsonPath = path.join(currentPath, 'package.json');
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            if (packageJson.name === packageName) {
+                return currentPath;
+            }
+        }
+        catch {
+            // Continue traversing upward until the package root is found.
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            return null;
+        }
+        currentPath = parentPath;
     }
 }
 function directoryExistsSync(dirname) {

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

@@ -0,0 +1,100 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterAll, afterEach, beforeAll, describe, expect, it, jest } from "@jest/globals";
+import { helpOutputSupportsBaseBytecode, resolveBaseBytecodeHermesFlags, } from "./runHermesEmitBinaryCommand.js";
+/**
+ * The base bytecode flag only exists in recent Hermes compilers, and the compiler that
+ * matters is the one inside the app being released - so the flag is decided by asking
+ * that binary, not by a version check.
+ */
+/** Excerpt of `hermesc --help` from a compiler that has the flag. */
+const HELP_WITH_BASE_BYTECODE = `OVERVIEW: Hermes driver
+
+USAGE: hermesc [options] <input>
+
+OPTIONS:
+  -Wno-direct-eval                   - Disable Warning when attempting a direct (local) eval
+  -base-bytecode=<string>            - input base bytecode for delta optimizing mode
+  -bytecode-output-manifest=<string> - Name of the manifest file generated when compiling multiple segments to bytecode
+  -commonjs                          - Use CommonJS modules
+`;
+/** The same excerpt from a compiler that predates the flag. */
+const HELP_WITHOUT_BASE_BYTECODE = `OVERVIEW: Hermes driver
+
+USAGE: hermesc [options] <input>
+
+OPTIONS:
+  -Wno-direct-eval                   - Disable Warning when attempting a direct (local) eval
+  -bytecode-output-manifest=<string> - Name of the manifest file generated when compiling multiple segments to bytecode
+  -commonjs                          - Use CommonJS modules
+`;
+function findRepoRoot() {
+    let dir = process.cwd();
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "node_modules", "react-native"))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`cannot locate the repository root from ${process.cwd()}`);
+        }
+        dir = parent;
+    }
+}
+function hermesOSBinDirName() {
+    switch (process.platform) {
+        case 'win32':
+            return 'win64-bin';
+        case 'darwin':
+            return 'osx-bin';
+        default:
+            return 'linux64-bin';
+    }
+}
+const repoRoot = findRepoRoot();
+const baseBundlePath = path.join(repoRoot, "cli", "fixtures", "binary-patch", "base.bundle");
+let workDir;
+/** A project whose Hermes compiler reports a help text without the flag. */
+function writeProjectWithFakeHermesc(helpOutput) {
+    const projectRoot = fs.mkdtempSync(path.join(workDir, "project-"));
+    const hermescDir = path.join(projectRoot, "node_modules", "react-native", "sdks", "hermesc", hermesOSBinDirName());
+    fs.mkdirSync(hermescDir, { recursive: true });
+    const hermescPath = path.join(hermescDir, "hermesc");
+    fs.writeFileSync(hermescPath, `#!/bin/sh\ncat <<'HELP'\n${helpOutput}HELP\n`);
+    fs.chmodSync(hermescPath, 0o755);
+    return projectRoot;
+}
+beforeAll(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "codepush-hermes-flags-"));
+});
+afterAll(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+describe("helpOutputSupportsBaseBytecode", () => {
+    it("detects the flag in the help output of a compiler that has it", () => {
+        expect(helpOutputSupportsBaseBytecode(HELP_WITH_BASE_BYTECODE)).toBe(true);
+    });
+    it("reports no support when the help output does not list the flag", () => {
+        expect(helpOutputSupportsBaseBytecode(HELP_WITHOUT_BASE_BYTECODE)).toBe(false);
+    });
+});
+describe("resolveBaseBytecodeHermesFlags", () => {
+    it("aligns the compilation with the base bundle when the compiler supports it", () => {
+        expect(resolveBaseBytecodeHermesFlags(baseBundlePath, repoRoot)).toEqual(['-base-bytecode', baseBundlePath]);
+    });
+    const itUnlessWindows = process.platform === 'win32' ? it.skip : it;
+    itUnlessWindows("warns and compiles without the flag when the compiler does not support it", () => {
+        const projectRoot = writeProjectWithFakeHermesc(HELP_WITHOUT_BASE_BYTECODE);
+        const warn = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        expect(resolveBaseBytecodeHermesFlags(baseBundlePath, projectRoot)).toEqual([]);
+        expect(warn.mock.calls.join('\n')).toMatch(/-base-bytecode/);
+    });
+    itUnlessWindows("uses the flag when the app's own compiler advertises it", () => {
+        const projectRoot = writeProjectWithFakeHermesc(HELP_WITH_BASE_BYTECODE);
+        expect(resolveBaseBytecodeHermesFlags(baseBundlePath, projectRoot)).toEqual(['-base-bytecode', baseBundlePath]);
+    });
+});

package/cli/dist/jest.globalSetup.js

@@ -0,0 +1,38 @@
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+/**
+ * Builds hdiffz/hpatchz once, before any test worker starts.
+ *
+ * Several suites generate and apply real patches, which is the only way to prove the
+ * committed patch format is what every applier understands. Provisioning the tools here
+ * rather than in each suite keeps a clean checkout - and CI - free of a manual setup
+ * step, without letting two workers run the same build at the same time.
+ *
+ * The build script installs into `HDIFFPATCH_TOOLS_DIR` when it is set and into
+ * `<repo>/.hdiffpatch-tools` otherwise, which is where the CLI looks for the tools. It
+ * is a no-op when they are already there, so the check below only decides whether to
+ * warn that this run has a multi-minute build ahead of it.
+ *
+ * Note that this module is loaded outside the jest module resolver, so it cannot import
+ * from the CLI sources.
+ */
+const REPO_ROOT = path.join(__dirname, '..');
+const BUILD_SCRIPT_PATH = path.join(REPO_ROOT, 'scripts', 'binary-patch', 'build-hdiffpatch.sh');
+const DEFAULT_TOOLS_DIR = path.join(REPO_ROOT, '.hdiffpatch-tools');
+export default function ensureBinaryPatchTools() {
+    const toolsDir = process.env.HDIFFPATCH_TOOLS_DIR || DEFAULT_TOOLS_DIR;
+    const alreadyInstalled = ['hdiffz', 'hpatchz'].every((tool) => fs.existsSync(path.join(toolsDir, tool)));
+    if (!alreadyInstalled) {
+        // Announced because a first build clones and compiles HDiffPatch, which takes
+        // minutes; a silent wait would look like a hang.
+        console.log(`Building hdiffz/hpatchz into ${toolsDir} (first run only)`);
+    }
+    const result = spawnSync(BUILD_SCRIPT_PATH, { encoding: 'utf8' });
+    if (result.error) {
+        throw new Error(`failed to run ${BUILD_SCRIPT_PATH}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`${BUILD_SCRIPT_PATH} failed:\n${result.stdout ?? ''}${result.stderr ?? ''}`);
+    }
+}

package/cli/dist/utils/binaryPatch.js

@@ -0,0 +1,86 @@
+/**
+ * Binary patch codec for CodePush updates.
+ *
+ * A binary patch update carries only the difference between the bundle that is
+ * already inside the app binary and the bundle a release wants to run, instead of
+ * the whole bundle. Patches are produced by HDiffPatch's `hdiffz` and applied on
+ * device by the native appliers; `hpatchz` is the reference applier used here so a
+ * patch can be verified right after it is produced.
+ *
+ * The tool options below are part of the format contract, not tuning knobs:
+ *   -m-6            the base bundle is held in memory while patching, which is what
+ *                   the native appliers do, and match score 6 suits bytecode
+ *   -c-zstd-21-24   zstd is the only decompressor the native appliers link
+ *   -f              overwrite the output file if it already exists
+ * Changing them produces patches the native appliers cannot read.
+ *
+ * A patch contains no checksum of the base data, and its zstd streams carry no
+ * content checksums, so a successful apply is not proof of a correct result: a base
+ * of the right size but the wrong content, or a corrupted patch body, can both apply
+ * "successfully" and yield wrong bytes. Callers must verify the base and target
+ * hashes themselves.
+ */
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+/**
+ * Identifies the patch format so a client can refuse a patch it cannot apply.
+ * Bump the format version whenever the tool options above change.
+ */
+export const BINARY_PATCH_ALGORITHM = 'hdiffpatch-m-zstd';
+export const BINARY_PATCH_FORMAT_VERSION = 1;
+const HDIFFZ_OPTIONS = ['-f', '-m-6', '-c-zstd-21-24'];
+const HPATCHZ_OPTIONS = ['-f', '-m'];
+const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
+const TOOLS_DIR_NAME = '.hdiffpatch-tools';
+const BUILD_SCRIPT_PATH = 'scripts/binary-patch/build-hdiffpatch.sh';
+/**
+ * Finds the hdiffz/hpatchz executable, looking at `HDIFFPATCH_TOOLS_DIR` first and
+ * then at a `.hdiffpatch-tools` directory in the working directory or any directory
+ * above it. The tools are built from source rather than installed as a package
+ * dependency, so the error explains how to get them.
+ */
+export function resolveBinaryPatchTool(tool) {
+    const configuredDir = process.env[TOOLS_DIR_ENV_NAME];
+    if (configuredDir) {
+        const configured = path.join(configuredDir, tool);
+        if (fs.existsSync(configured)) {
+            return configured;
+        }
+        throw new Error(`${TOOLS_DIR_ENV_NAME} is set to '${configuredDir}' but it does not contain '${tool}'. ` +
+            `Build the tools with '${BUILD_SCRIPT_PATH}'.`);
+    }
+    let directory = path.resolve(process.cwd());
+    for (;;) {
+        const candidate = path.join(directory, TOOLS_DIR_NAME, tool);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    throw new Error(`'${tool}' not found in any '${TOOLS_DIR_NAME}' directory at or above '${process.cwd()}'. ` +
+        `Build it with '${BUILD_SCRIPT_PATH}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`);
+}
+/** Writes the patch that turns the bundle at `basePath` into the one at `targetPath`. */
+export function generatePatch(basePath, targetPath, patchPath) {
+    runTool('hdiffz', [...HDIFFZ_OPTIONS, basePath, targetPath, patchPath]);
+}
+/** Writes the bundle that `patchPath` produces from the bundle at `basePath`. */
+export function applyPatch(basePath, patchPath, outputPath) {
+    runTool('hpatchz', [...HPATCHZ_OPTIONS, basePath, patchPath, outputPath]);
+}
+function runTool(tool, args) {
+    const executable = resolveBinaryPatchTool(tool);
+    const result = spawnSync(executable, args, { encoding: 'utf8' });
+    if (result.error) {
+        throw new Error(`failed to run ${tool}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const reason = result.status === null ? `signal ${result.signal}` : `exit code ${result.status}`;
+        throw new Error(`${tool} failed with ${reason}\n${result.stdout ?? ''}${result.stderr ?? ''}`);
+    }
+}

package/cli/dist/utils/binaryPatch.test.js

@@ -0,0 +1,190 @@
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterAll, beforeAll, describe, expect, it } from "@jest/globals";
+import { applyPatch, generatePatch, resolveBinaryPatchTool } from "./binaryPatch.js";
+/**
+ * Locks the binary patch codec contract: which bytes a patch restores, and which
+ * kinds of broken input the appliers do and do not catch.
+ *
+ * Everything here runs against real binaries and real bytes - hdiffz/hpatchz and a
+ * host build of the native applier - because the whole point is to prove that the
+ * committed patch format really is what every applier understands.
+ */
+/** Building the applier from source takes a while on a cold machine. */
+const BUILD_APPLIER_TIMEOUT_MS = 5 * 60 * 1000;
+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");
+const patchFixture = path.join(fixtureDir, "update.patch");
+/**
+ * One shared tree builds the applier for both platforms: iOS pulls it in through the
+ * podspec at the repository root, Android through externalNativeBuild.
+ */
+const applierDir = path.join(repoRoot, "cpp", "binarypatch");
+let workDir;
+function sha256(filePath) {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+function workPath(name) {
+    return path.join(workDir, name);
+}
+/** Writes a copy of `sourcePath` with `mutate` applied to its bytes. */
+function writeMutatedCopy(sourcePath, name, mutate) {
+    const destination = workPath(name);
+    fs.writeFileSync(destination, mutate(fs.readFileSync(sourcePath)));
+    return destination;
+}
+function cCompiler() {
+    return process.env.CC || "cc";
+}
+function hasCCompiler() {
+    return spawnSync(cCompiler(), ["--version"], { stdio: "ignore" }).status === 0;
+}
+beforeAll(() => {
+    // hdiffz/hpatchz are provisioned for the whole run by the jest global setup.
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "codepush-binary-patch-"));
+});
+afterAll(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+describe("generatePatch/applyPatch", () => {
+    it("restores the target bytes from a freshly generated patch", () => {
+        const generatedPatch = workPath("generated.patch");
+        const restored = workPath("restored-from-generated.bundle");
+        generatePatch(baseFixture, targetFixture, generatedPatch);
+        applyPatch(baseFixture, generatedPatch, restored);
+        expect(fs.statSync(generatedPatch).size).toBeGreaterThan(0);
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+    it("restores the target bytes from the committed patch fixture", () => {
+        const restored = workPath("restored-from-fixture.bundle");
+        applyPatch(baseFixture, patchFixture, restored);
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+    it("reports a missing patch tool with a message that says how to get it", () => {
+        const previous = process.env.HDIFFPATCH_TOOLS_DIR;
+        process.env.HDIFFPATCH_TOOLS_DIR = workPath("no-such-dir");
+        try {
+            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/build-hdiffpatch\.sh/);
+        }
+        finally {
+            if (previous === undefined) {
+                delete process.env.HDIFFPATCH_TOOLS_DIR;
+            }
+            else {
+                process.env.HDIFFPATCH_TOOLS_DIR = previous;
+            }
+        }
+    });
+});
+describe("applyPatch failure modes", () => {
+    it("fails on a patch with a corrupted header", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "corrupt-header.patch", (bytes) => {
+            // Byte 0 is inside the patch type string, which the header parser reads first.
+            bytes[0] ^= 0xff;
+            return bytes;
+        });
+        expect(() => applyPatch(baseFixture, corrupted, workPath("out-corrupt-header.bundle"))).toThrow(/hpatchz/);
+    });
+    it("fails on a truncated patch", () => {
+        const truncated = writeMutatedCopy(patchFixture, "truncated.patch", (bytes) => bytes.subarray(0, Math.floor(bytes.length / 2)));
+        expect(() => applyPatch(baseFixture, truncated, workPath("out-truncated.bundle"))).toThrow(/hpatchz/);
+    });
+});
+/**
+ * A compressed diff carries no checksum of the base data, and the zstd streams
+ * inside it are written without content checksums, so an applier cannot tell every
+ * kind of wrong input apart from a legitimate one. These tests pin that down: the
+ * apply step may report success, but it never produces the target bytes. Callers
+ * must therefore verify the base and target hashes themselves rather than treating
+ * a successful apply as proof of a correct result.
+ */
+describe("errors the codec cannot detect", () => {
+    it("never produces the target bytes when a byte inside the compressed diff data is corrupted", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "corrupt-body.patch", (bytes) => {
+            bytes[Math.floor(bytes.length / 2)] ^= 0xff;
+            return bytes;
+        });
+        const restored = workPath("out-corrupt-body.bundle");
+        // Whether the corruption is reported depends on where it lands: a flipped bit
+        // inside a zstd literals block decodes to different bytes without any error,
+        // while one that invalidates a block header does fail. Either way the result
+        // is not the target, which is all the caller can rely on.
+        let restoredHash = null;
+        try {
+            applyPatch(baseFixture, corrupted, restored);
+            restoredHash = sha256(restored);
+        }
+        catch {
+            restoredHash = null;
+        }
+        expect(restoredHash).not.toBe(sha256(targetFixture));
+    });
+    it("applies but produces wrong bytes when the base has the expected size and different content", () => {
+        const wrongBase = writeMutatedCopy(baseFixture, "wrong-base.bundle", (bytes) => {
+            bytes[1000] ^= 0xff;
+            return bytes;
+        });
+        const restored = workPath("out-wrong-base.bundle");
+        applyPatch(wrongBase, patchFixture, restored);
+        expect(fs.statSync(wrongBase).size).toBe(fs.statSync(baseFixture).size);
+        expect(sha256(restored)).not.toBe(sha256(targetFixture));
+    });
+});
+/**
+ * The native appliers on Android and iOS are built from the vendored sources, so a
+ * host build of the same sources is what proves they agree with hdiffz/hpatchz.
+ */
+const describeNativeApplier = hasCCompiler() ? describe : describe.skip;
+describeNativeApplier("host build of the native applier", () => {
+    let hostApplier;
+    const runHostApplier = (oldPath, patch, outPath) => {
+        const result = spawnSync(hostApplier, [oldPath, patch, outPath], { encoding: "utf8" });
+        return result.status;
+    };
+    beforeAll(() => {
+        hostApplier = workPath("apply_patch_host");
+        const script = path.join(applierDir, "host", "build.sh");
+        const result = spawnSync(script, [hostApplier], { encoding: "utf8", timeout: BUILD_APPLIER_TIMEOUT_MS });
+        if (result.status !== 0) {
+            throw new Error(`${script} failed:\n${result.stdout ?? ""}${result.stderr ?? ""}`);
+        }
+    }, BUILD_APPLIER_TIMEOUT_MS);
+    it("restores the same target bytes as the CLI applier", () => {
+        const restored = workPath("out-host.bundle");
+        expect(runHostApplier(baseFixture, patchFixture, restored)).toBe(0);
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+    it("reports a corrupted patch header as exit code 3", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "host-corrupt-header.patch", (bytes) => {
+            bytes[0] ^= 0xff;
+            return bytes;
+        });
+        expect(runHostApplier(baseFixture, corrupted, workPath("out-host-corrupt-header.bundle"))).toBe(3);
+    });
+    it("reports a base of unexpected size as exit code 5", () => {
+        const shortBase = writeMutatedCopy(baseFixture, "host-short-base.bundle", (bytes) => bytes.subarray(0, bytes.length - 16));
+        expect(runHostApplier(shortBase, patchFixture, workPath("out-host-short-base.bundle"))).toBe(5);
+    });
+    it("reports a truncated patch as exit code 6", () => {
+        const truncated = writeMutatedCopy(patchFixture, "host-truncated.patch", (bytes) => bytes.subarray(0, Math.floor(bytes.length / 2)));
+        expect(runHostApplier(baseFixture, truncated, workPath("out-host-truncated.bundle"))).toBe(6);
+    });
+});