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

package/cli/functions/runHermesEmitBinaryCommand.ts

@@ -5,8 +5,15 @@
 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
  *
@@ -14,6 +21,7 @@ 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(
@@ -21,6 +29,7 @@ export async function runHermesEmitBinaryCommand(
     outputPath: string,
     sourcemapOutput: string,
     extraHermesFlags: string[] = [],
+    projectRoot: string = process.cwd(),
 ): Promise<void> {
     const hermesArgs: string[] = [
         '-emit-binary',
@@ -37,10 +46,19 @@ export async function runHermesEmitBinaryCommand(
 
     return new Promise<void>((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');
@@ -58,7 +76,7 @@ export async function runHermesEmitBinaryCommand(
         }
 
         // 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');
         }
@@ -106,7 +124,48 @@ export async function runHermesEmitBinaryCommand(
     });
 }
 
-function getHermesCommand(): string {
+/**
+ * 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: string, projectRoot: string = process.cwd()): string[] {
+    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: string): boolean {
+    return helpOutput.includes(BASE_BYTECODE_FLAG);
+}
+
+function hermesSupportsBaseBytecode(projectRoot: string): boolean {
+    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: string): string {
     const fileExists = (file: string): boolean => {
         try {
             return fs.statSync(file).isFile();
@@ -115,7 +174,7 @@ function getHermesCommand(): string {
         }
     };
 
-    const hermescExecutable = path.join(getHermesCompilerPath(), getHermesOSBin(), getHermesOSExe());
+    const hermescExecutable = path.join(getHermesCompilerPath(projectRoot), getHermesOSBin(), getHermesOSExe());
     if (fileExists(hermescExecutable)) {
         return hermescExecutable;
     }
@@ -146,48 +205,75 @@ function getHermesOSExe(): string {
     }
 }
 
-function getComposeSourceMapsPath(): string | null {
+function getComposeSourceMapsPath(projectRoot: string): string | null {
     // 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(): string {
-    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: string): string {
+    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: string) {
+    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: string) {
+    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: string, packageName: string): string | null {
+    try {
+        const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+        const resolvedPath = projectRequire.resolve(packageName);
+        return findPackageRoot(packageName, resolvedPath);
+    } catch {
+        return null;
+    }
+}
+
+function findPackageRoot(packageName: string, resolvedPath: string): string | null {
+    let currentPath = path.dirname(resolvedPath);
+
+    while (true) {
+        const packageJsonPath = path.join(currentPath, 'package.json');
+
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as { name?: string };
+            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;
     }
 }
 

package/cli/jest.globalSetup.ts

@@ -0,0 +1,43 @@
+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(): void {
+    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/utils/binaryPatch.test.ts

@@ -0,0 +1,234 @@
+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(): string {
+    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: string;
+
+function sha256(filePath: string): string {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function workPath(name: string): string {
+    return path.join(workDir, name);
+}
+
+/** Writes a copy of `sourcePath` with `mutate` applied to its bytes. */
+function writeMutatedCopy(sourcePath: string, name: string, mutate: (bytes: Buffer) => Buffer): string {
+    const destination = workPath(name);
+    fs.writeFileSync(destination, mutate(fs.readFileSync(sourcePath)));
+    return destination;
+}
+
+function cCompiler(): string {
+    return process.env.CC || "cc";
+}
+
+function hasCCompiler(): boolean {
+    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: string | null = 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: string;
+
+    const runHostApplier = (oldPath: string, patch: string, outPath: string): number | null => {
+        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);
+    });
+});

package/cli/utils/binaryPatch.ts

@@ -0,0 +1,103 @@
+/**
+ * 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;
+
+export type BinaryPatchTool = 'hdiffz' | 'hpatchz';
+
+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: BinaryPatchTool): string {
+    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: string, targetPath: string, patchPath: string): void {
+    runTool('hdiffz', [...HDIFFZ_OPTIONS, basePath, targetPath, patchPath]);
+}
+
+/** Writes the bundle that `patchPath` produces from the bundle at `basePath`. */
+export function applyPatch(basePath: string, patchPath: string, outputPath: string): void {
+    runTool('hpatchz', [...HPATCHZ_OPTIONS, basePath, patchPath, outputPath]);
+}
+
+function runTool(tool: BinaryPatchTool, args: string[]): void {
+    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 ?? ''}`);
+    }
+}