@bravemobile/react-native-code-push 13.1.0-beta.1 → 13.1.0-beta.3

package/README.md

@@ -332,6 +332,38 @@ CodePush.sync({
 ```
 
 
+#### 4-2. Asset Diff Archives
+
+A release published with a binary patch can carry **asset diff archives** as well - one per
+recently released version. A diff archive holds the patch of the JS bundle, only the assets
+that version does not already have, and a manifest of the files it has to drop. The client
+copies the update it already has installed, applies those, and ends up holding exactly the
+contents of the full archive.
+
+So one release has a full archive, a patch archive and up to `--diff-base-count` diff
+archives, and a client downloads one of them per attempt: the diff archive built against
+the update it is running, when the release has one, and the patch archive when it is
+running the bundle in the binary or an update this release was not diffed against.
+
+Diff archives are published only when all three of these hold:
+- the release is a binary patch release (`release --binary-bundle-path`),
+- `code-push.config.ts` implements `bundleDownloader`, so the CLI can fetch the earlier releases to diff against,
+- `--diff-base-count` is greater than `0` (it defaults to `3`).
+
+```ts
+bundleDownloader: async (downloadUrl) => {
+    const downloadedFilePath = path.join(os.tmpdir(), path.basename(new URL(downloadUrl).pathname));
+    // fetch the archive from your storage (S3, GCS, ...) to downloadedFilePath
+    return { downloadedFilePath };
+},
+```
+
+Rebuilding the update from a diff archive falls back the way a patch does: the update is
+downloaded in full instead, and `onBinaryPatchResult` reports it as
+`{ status: "fallback", fallbackReason: "package_verification_failed" }`. See
+[Asset diff archives](cli/README.md#asset-diff-archives) for what the release publishes.
+
+
 ### 5. Configure the CLI Tool
 
 > [!TIP]
@@ -339,7 +371,8 @@ CodePush.sync({
 
 **(1) Create a `code-push.config.ts` file in the root directory of your project.**
 
-Then, implement three functions to upload the bundle file and create/update the release history.
+Then, implement three functions to upload the bundle file and create/update the release history,
+plus an optional fourth one - `bundleDownloader` - if you publish [asset diff archives](#4-2-asset-diff-archives).
 The CLI tool uses these functions to release CodePush updates and manage releases.
 (These functions are not used at runtime by the library.)
 
@@ -377,6 +410,15 @@ const Config: CliConfigInterface = {
   ): Promise<void> => {
     // ...
   },
+
+  // Only needed to publish asset diff archives (see "4-2. Asset Diff Archives").
+  // bundleDownloader: async (
+  //   downloadUrl: string,
+  //   platform: "ios" | "android",
+  //   identifier,
+  // ): Promise<{downloadedFilePath: string}> => {
+  //   // ...
+  // },
 };
 
 module.exports = Config;

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushBinaryPatch.java

@@ -181,25 +181,39 @@ public class CodePushBinaryPatch {
      * An archive wraps its files in a single directory, and the manifest's paths are
      * relative to that directory rather than to the archive. An archive whose files are at
      * the top level is its own contents root, which is how the tooling that unpacks one
-     * reads it too.
+     * reads it too. A diff archive carries the manifest of the assets to delete beside that
+     * wrapper directory, at the root, so that file does not count against the shape.
      */
     private static File resolveContentsFolder(File unzippedFolder) {
         File[] entries = unzippedFolder.listFiles();
-        if (entries != null && entries.length == 1 && entries[0].isDirectory()) {
-            return entries[0];
+        if (entries == null) {
+            return unzippedFolder;
         }
 
-        return unzippedFolder;
+        File wrapper = null;
+        for (File entry : entries) {
+            if (entry.isFile() && entry.getName().equals(CodePushConstants.DIFF_MANIFEST_FILE_NAME)) {
+                continue;
+            }
+            if (wrapper == null && entry.isDirectory()) {
+                wrapper = entry;
+                continue;
+            }
+
+            return unzippedFolder;
+        }
+
+        return wrapper != null ? wrapper : unzippedFolder;
     }
 
     /**
-     * Resolves a path the manifest points at, refusing anything that would reach outside
-     * the archive - an archive is untrusted input, and its manifest is no more trusted
-     * than its entries.
+     * Resolves a path a manifest points at, refusing anything that would reach outside the
+     * folder it is relative to - an archive is untrusted input, and its manifest is no more
+     * trusted than its entries.
      *
      * @return the resolved file, or null when the path is unusable
      */
-    private static File resolveInsideFolder(File folder, String relativePath) {
+    static File resolveInsideFolder(File folder, String relativePath) {
         if (isNullOrEmpty(relativePath) || new File(relativePath).isAbsolute()) {
             return null;
         }

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushUpdateUtils.java

@@ -110,8 +110,11 @@ public class CodePushUpdateUtils {
             JSONArray deletedFiles = diffManifest.getJSONArray("deletedFiles");
             for (int i = 0; i < deletedFiles.length(); i++) {
                 String fileNameToDelete = deletedFiles.getString(i);
-                File fileToDelete = new File(newPackageFolderPath, fileNameToDelete);
-                if (fileToDelete.exists()) {
+                // The manifest is untrusted input, so an entry that reaches outside the
+                // package folder is ignored rather than followed. Whether skipping it left
+                // the update whole is the folder hash check's answer to give.
+                File fileToDelete = CodePushBinaryPatch.resolveInsideFolder(new File(newPackageFolderPath), fileNameToDelete);
+                if (fileToDelete != null && fileToDelete.exists()) {
                     fileToDelete.delete();
                 }
             }

package/android/app/src/test/java/com/microsoft/codepush/react/CodePushBinaryPatchTest.java

@@ -87,6 +87,43 @@ public class CodePushBinaryPatchTest {
         assertNoTemporaryFilesLeft();
     }
 
+    @Test
+    public void restoresTheBundleWhenTheDiffManifestSitsBesideTheContentsDirectory() throws IOException {
+        // A diff archive carries the manifest of the assets to delete at its root, beside
+        // the one directory its contents are wrapped in.
+        File unzippedFolder = mTemporaryFolder.newFolder("diff-archive");
+        File contentsFolder = new File(unzippedFolder, "CodePush");
+        assertTrue(contentsFolder.mkdirs());
+        File diffManifestFile = new File(unzippedFolder, CodePushConstants.DIFF_MANIFEST_FILE_NAME);
+        writeFile(diffManifestFile, bytes("{\"deletedFiles\":[]}"));
+        assertTrue(mManifestFile.renameTo(new File(contentsFolder, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME)));
+        assertTrue(mPatchFile.renameTo(new File(contentsFolder, PATCH_FILE_NAME)));
+        File assetFile = new File(contentsFolder, "logo.png");
+        writeFile(assetFile, bytes("an asset the diff brought along"));
+
+        BinaryPatchResult result = new CodePushBinaryPatch(providerOf(BASE_BUNDLE), succeedingApplier())
+                .restoreBundle(unzippedFolder.getAbsolutePath(), mWorkingFolder.getAbsolutePath(), BUNDLE_FILE_NAME);
+
+        assertTrue(result.succeeded());
+        assertArrayEquals(TARGET_BUNDLE, readFile(new File(contentsFolder, BUNDLE_FILE_NAME)));
+        assertFalse(new File(contentsFolder, PATCH_FILE_NAME).exists());
+        assertFalse(new File(contentsFolder, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME).exists());
+        assertTrue("the diff manifest is what tells the install which assets to delete", diffManifestFile.exists());
+        assertTrue("the rest of the contents is left as the archive delivered it", assetFile.exists());
+        assertNoTemporaryFilesLeft();
+    }
+
+    @Test
+    public void keepsARootHoldingLooseFilesBesidesTheDiffManifestAsItsOwnContentsRoot() throws IOException {
+        writeFile(new File(mContentsFolder, CodePushConstants.DIFF_MANIFEST_FILE_NAME), bytes("{\"deletedFiles\":[]}"));
+
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE, succeedingApplier());
+
+        assertTrue(result.succeeded());
+        assertArrayEquals(TARGET_BUNDLE, readFile(mBundleFile));
+        assertNoTemporaryFilesLeft();
+    }
+
     @Test
     public void removesWhatAnInterruptedAttemptLeftInTheWorkingDirectory() throws IOException {
         assertTrue(mWorkingFolder.mkdirs());

package/android/app/src/test/java/com/microsoft/codepush/react/CodePushUpdateManagerDownloadTest.java

@@ -34,6 +34,8 @@ import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.TreeMap;
+import java.util.TreeSet;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;
 
@@ -50,11 +52,18 @@ public class CodePushUpdateManagerDownloadTest {
     /** Every archive wraps its files in one directory, which the manifest paths are relative to. */
     private static final String CONTENTS_DIR_NAME = "CodePush";
     private static final String ASSET_PATH = "assets/logo.png";
+    /** An asset the update adds, so the diff archive is the only place it comes from. */
+    private static final String ADDED_ASSET_PATH = "assets/badge.png";
+    /** An asset the installed package holds and the update does without. */
+    private static final String DROPPED_ASSET_PATH = "assets/legacy.png";
 
     private static final byte[] BASE_BUNDLE = bytes("the bundle inside the app binary");
     private static final byte[] TARGET_BUNDLE = bytes("the bundle the update wants to run");
+    private static final byte[] INSTALLED_BUNDLE = bytes("the bundle of the update already installed");
     private static final byte[] PATCH = bytes("the difference between the two");
     private static final byte[] ASSET = bytes("an image the update ships with");
+    private static final byte[] ADDED_ASSET = bytes("an image only the newer update ships");
+    private static final byte[] DROPPED_ASSET = bytes("an image the newer update leaves behind");
     private static final byte[] ERROR_PAGE = bytes("<html><body>404 Not Found</body></html>");
 
     @Rule
@@ -161,6 +170,83 @@ public class CodePushUpdateManagerDownloadTest {
         assertFallbackResult(patchResult, BinaryPatchResult.REASON_PACKAGE_VERIFICATION_FAILED);
     }
 
+    @Test
+    public void installsAnAssetDiffUpdateByMergingWithTheInstalledPackage() throws IOException {
+        installBaseUpdate();
+        Map<String, byte[]> updateContents = assetDiffTargetContents();
+        String updateHash = packageHashOf(updateContents);
+        String diffUrl = serve("/diff.zip", zipOf(assetDiffArchiveContents(DROPPED_ASSET_PATH)));
+        String fullUrl = serve("/full.zip", zipOf(updateContents));
+
+        JSONObject patchResult = updateManager(applierWriting(TARGET_BUNDLE))
+                .downloadPackage(updatePackage(updateHash, fullUrl, diffUrl), BUNDLE_FILE_NAME, ignoreProgress());
+
+        assertEquals("the update is downloaded as its diff alone, the base being already installed",
+                Arrays.asList("/installed.zip", "/diff.zip"), mServer.requestedPaths());
+        assertEquals("applied", patchResult.optString("status", null));
+        assertFalse("an applied diff has nothing to report a reason for", patchResult.has("fallbackReason"));
+        // The asset the diff leaves out is carried over from the installed package, and the
+        // one its manifest names is not.
+        assertInstalledContents(updateHash, updateContents);
+    }
+
+    @Test
+    public void fallsBackToTheFullArchiveWhenTheAssetDiffMergeYieldsTheWrongContents() throws IOException {
+        // A manifest that deletes an asset the update keeps: the merge ends up missing a file
+        // the release was published with, and the update is not the one the hash is for.
+        installBaseUpdate();
+        Map<String, byte[]> updateContents = assetDiffTargetContents();
+        String updateHash = packageHashOf(updateContents);
+        String diffUrl = serve("/diff.zip", zipOf(assetDiffArchiveContents(ASSET_PATH)));
+        String fullUrl = serve("/full.zip", zipOf(updateContents));
+
+        JSONObject patchResult = updateManager(applierWriting(TARGET_BUNDLE))
+                .downloadPackage(updatePackage(updateHash, fullUrl, diffUrl), BUNDLE_FILE_NAME, ignoreProgress());
+
+        assertEquals(Arrays.asList("/installed.zip", "/diff.zip", "/full.zip"), mServer.requestedPaths());
+        assertFallbackResult(patchResult, BinaryPatchResult.REASON_PACKAGE_VERIFICATION_FAILED);
+        assertInstalledContents(updateHash, updateContents);
+    }
+
+    @Test
+    public void fallsBackToTheFullArchiveWhenAnAssetDiffArrivesWithNoInstalledPackage() throws IOException {
+        // Nothing is installed, so the assets the diff counts on being there already have
+        // nowhere to be copied from and the merge cannot make the update whole.
+        Map<String, byte[]> updateContents = assetDiffTargetContents();
+        String updateHash = packageHashOf(updateContents);
+        String diffUrl = serve("/diff.zip", zipOf(assetDiffArchiveContents(DROPPED_ASSET_PATH)));
+        String fullUrl = serve("/full.zip", zipOf(updateContents));
+
+        JSONObject patchResult = updateManager(applierWriting(TARGET_BUNDLE))
+                .downloadPackage(updatePackage(updateHash, fullUrl, diffUrl), BUNDLE_FILE_NAME, ignoreProgress());
+
+        assertEquals(Arrays.asList("/diff.zip", "/full.zip"), mServer.requestedPaths());
+        assertFallbackResult(patchResult, BinaryPatchResult.REASON_PACKAGE_VERIFICATION_FAILED);
+        assertInstalledContents(updateHash, updateContents);
+    }
+
+    @Test
+    public void leavesAFileOutsideThePackageFolderAloneWhenTheAssetDiffManifestNamesIt() throws IOException {
+        // A manifest entry that climbs out of the package folder: the client is not the one
+        // that wrote it, so it must not act on it.
+        installBaseUpdate();
+        File fileOutsideThePackage = mTemporaryFolder.newFile("keep-me.txt");
+        Map<String, byte[]> updateContents = assetDiffTargetContents();
+        String updateHash = packageHashOf(updateContents);
+        String diffUrl = serve("/diff.zip",
+                zipOf(assetDiffArchiveContents(DROPPED_ASSET_PATH, CONTENTS_DIR_NAME + "/../../../keep-me.txt")));
+        String fullUrl = serve("/full.zip", zipOf(updateContents));
+
+        JSONObject patchResult = updateManager(applierWriting(TARGET_BUNDLE))
+                .downloadPackage(updatePackage(updateHash, fullUrl, diffUrl), BUNDLE_FILE_NAME, ignoreProgress());
+
+        assertTrue("a manifest entry reaching outside the package folder deleted " + fileOutsideThePackage,
+                fileOutsideThePackage.exists());
+        // Skipping it costs the update nothing, so the diff still installs.
+        assertEquals("applied", patchResult.optString("status", null));
+        assertInstalledContents(updateHash, updateContents);
+    }
+
     @Test
     public void announcesEachDownloadOfAFallbackAsItsOwnProgressStream() throws IOException {
         byte[] fullArchive = zipOf(fullArchiveContents());
@@ -229,6 +315,58 @@ public class CodePushUpdateManagerDownloadTest {
         assertFalse(binaryPatchFolder.exists());
     }
 
+    /**
+     * The update installed under a hash is these contents and nothing else, which is the
+     * whole question for an update that was rebuilt from parts of two archives.
+     */
+    private void assertInstalledContents(String packageHash, Map<String, byte[]> expectedContents) throws IOException {
+        File packageFolder = new File(new File(mDocumentsDirectory, CodePushConstants.CODE_PUSH_FOLDER_PREFIX), packageHash);
+        Map<String, byte[]> installedFiles = filesUnder(packageFolder, "");
+        // Written last, so its presence also says the folder hash check passed.
+        assertTrue("the update is installed without its metadata",
+                installedFiles.remove(CodePushConstants.PACKAGE_FILE_NAME) != null);
+
+        assertEquals("the installed files", new TreeSet<>(expectedContents.keySet()), installedFiles.keySet());
+        for (Map.Entry<String, byte[]> expectedFile : expectedContents.entrySet()) {
+            assertArrayEquals("the contents of " + expectedFile.getKey(),
+                    expectedFile.getValue(), installedFiles.get(expectedFile.getKey()));
+        }
+    }
+
+    /** Every file in a folder, keyed by its path relative to that folder. */
+    private static Map<String, byte[]> filesUnder(File folder, String pathPrefix) throws IOException {
+        Map<String, byte[]> files = new TreeMap<>();
+        File[] entries = folder.listFiles();
+        if (entries == null) {
+            return files;
+        }
+
+        for (File entry : entries) {
+            String relativePath = pathPrefix.isEmpty() ? entry.getName() : pathPrefix + "/" + entry.getName();
+            if (entry.isDirectory()) {
+                files.putAll(filesUnder(entry, relativePath));
+            } else {
+                files.put(relativePath, readFile(entry));
+            }
+        }
+
+        return files;
+    }
+
+    /**
+     * Downloads an update in full and makes it the current package, which is what the asset
+     * diff of a later release is merged into.
+     */
+    private void installBaseUpdate() throws IOException {
+        Map<String, byte[]> contents = installedArchiveContents();
+        JSONObject installedPackage = fullUpdatePackage(
+                packageHashOf(contents), serve("/installed.zip", zipOf(contents)));
+
+        CodePushUpdateManager updateManager = updateManager(applierWriting(TARGET_BUNDLE));
+        updateManager.downloadPackage(installedPackage, BUNDLE_FILE_NAME, ignoreProgress());
+        updateManager.installPackage(installedPackage, false);
+    }
+
     private CodePushUpdateManager updateManager(CodePushBinaryPatch.PatchApplier applier) {
         CodePushBinaryPatch binaryPatch = new CodePushBinaryPatch(new CodePushBinaryPatch.BaseBundleProvider() {
             @Override
@@ -283,11 +421,60 @@ public class CodePushUpdateManagerDownloadTest {
         return contents;
     }
 
+    /** The full archive of the release that is installed when the asset diff arrives. */
+    private Map<String, byte[]> installedArchiveContents() {
+        Map<String, byte[]> contents = new LinkedHashMap<>();
+        contents.put(CONTENTS_DIR_NAME + "/" + BUNDLE_FILE_NAME, INSTALLED_BUNDLE);
+        contents.put(CONTENTS_DIR_NAME + "/" + ASSET_PATH, ASSET);
+        contents.put(CONTENTS_DIR_NAME + "/" + DROPPED_ASSET_PATH, DROPPED_ASSET);
+        return contents;
+    }
+
+    /**
+     * An asset diff archive: the patch archive carrying only the assets the update changes,
+     * plus the manifest of the files to delete at the archive root, beside the contents
+     * directory the manifest's paths are relative to. An asset the installed package already
+     * holds unchanged is not shipped at all - the client copies it over.
+     */
+    private Map<String, byte[]> assetDiffArchiveContents(String deletedAssetPath) {
+        Map<String, byte[]> contents = patchArchiveContents();
+        contents.remove(CONTENTS_DIR_NAME + "/" + ASSET_PATH);
+        contents.put(CONTENTS_DIR_NAME + "/" + ADDED_ASSET_PATH, ADDED_ASSET);
+        contents.put(CodePushConstants.DIFF_MANIFEST_FILE_NAME,
+                bytes("{\"deletedFiles\":[\"" + CONTENTS_DIR_NAME + "/" + deletedAssetPath + "\"]}"));
+        return contents;
+    }
+
+    /** The same archive, with one more path in its manifest of the files to delete. */
+    private Map<String, byte[]> assetDiffArchiveContents(String deletedAssetPath, String otherDeletedPath) {
+        Map<String, byte[]> contents = assetDiffArchiveContents(deletedAssetPath);
+        contents.put(CodePushConstants.DIFF_MANIFEST_FILE_NAME,
+                bytes("{\"deletedFiles\":[\"" + CONTENTS_DIR_NAME + "/" + deletedAssetPath + "\",\"" + otherDeletedPath + "\"]}"));
+        return contents;
+    }
+
+    /** What an asset diff has to add up to: the contents of the update's full archive. */
+    private Map<String, byte[]> assetDiffTargetContents() {
+        Map<String, byte[]> contents = fullArchiveContents();
+        contents.put(CONTENTS_DIR_NAME + "/" + ADDED_ASSET_PATH, ADDED_ASSET);
+        return contents;
+    }
+
     private JSONObject updatePackage(String downloadUrl, String binaryPatchDownloadUrl) {
+        return updatePackage(mPackageHash, downloadUrl, binaryPatchDownloadUrl);
+    }
+
+    private JSONObject updatePackage(String packageHash, String downloadUrl, String binaryPatchDownloadUrl) {
+        JSONObject updatePackage = fullUpdatePackage(packageHash, downloadUrl);
+        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.BINARY_PATCH_DOWNLOAD_URL_KEY, binaryPatchDownloadUrl);
+        return updatePackage;
+    }
+
+    /** A release with no second archive to try, so it is downloaded in full. */
+    private JSONObject fullUpdatePackage(String packageHash, String downloadUrl) {
         JSONObject updatePackage = new JSONObject();
-        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.PACKAGE_HASH_KEY, mPackageHash);
+        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.PACKAGE_HASH_KEY, packageHash);
         CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.DOWNLOAD_URL_KEY, downloadUrl);
-        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.BINARY_PATCH_DOWNLOAD_URL_KEY, binaryPatchDownloadUrl);
         return updatePackage;
     }
 

package/cli/commands/releaseCommand/addToReleaseHistory.ts

@@ -15,6 +15,7 @@ export async function addToReleaseHistory(
     mandatory: boolean,
     enable: boolean,
     rollout: number | undefined,
+    diffPackages: Record<string, string> | undefined,
 ): Promise<void> {
     const releaseHistory = await getReleaseHistory(binaryVersion, platform, identifier);
 
@@ -39,6 +40,12 @@ export async function addToReleaseHistory(
         newReleaseHistory[appVersion].binaryPatchDownloadUrl = binaryPatchDownloadUrl;
     }
 
+    // Same for the asset diffs: an entry only names the bases it actually published a
+    // diff archive for.
+    if (diffPackages && Object.keys(diffPackages).length > 0) {
+        newReleaseHistory[appVersion].diffPackages = diffPackages;
+    }
+
     if (typeof rollout === 'number') {
         newReleaseHistory[appVersion].rollout = rollout;
     }

package/cli/commands/releaseCommand/index.test.ts

@@ -12,6 +12,7 @@ jest.mock("./release.js");
 jest.mock("../../utils/fsUtils.js", () => ({
     findAndReadConfigFile: () => ({
         bundleUploader: async () => ({ downloadUrl: 'https://cdn.example.com/bundle' }),
+        bundleDownloader: async () => ({ downloadedFilePath: '/tmp/base.zip' }),
         getReleaseHistory: async () => ({}),
         setReleaseHistory: async () => undefined,
     }),
@@ -29,6 +30,8 @@ const ARG_INDEX = {
     bundleDirectory: 16,
     baseBundlePath: 19,
     onOversizedPatch: 20,
+    bundleDownloader: 21,
+    diffBaseCount: 22,
 } as const;
 
 /**
@@ -115,4 +118,33 @@ describe("release command options", () => {
         const { release } = await import("./release.js");
         expect(jest.mocked(release)).not.toHaveBeenCalled();
     });
+
+    it("hands the release the bundle downloader from the config and three diff bases by default", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1']);
+
+        expect(typeof args[ARG_INDEX.bundleDownloader]).toBe('function');
+        expect(args[ARG_INDEX.diffBaseCount]).toBe(3);
+    });
+
+    it("passes the chosen asset diff base count through to the release", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--diff-base-count', '5']);
+
+        expect(args[ARG_INDEX.diffBaseCount]).toBe(5);
+    });
+
+    it.each([
+        ['is negative', '-1'],
+        ['is not a number at all', 'many'],
+    ])("rejects an asset diff base count that %s", async (_caseName, value) => {
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+        jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+            throw new Error(`process.exit(${code})`);
+        }) as never);
+
+        await expect(parseReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--diff-base-count', value]))
+            .rejects.toThrow('process.exit(1)');
+
+        const { release } = await import("./release.js");
+        expect(jest.mocked(release)).not.toHaveBeenCalled();
+    });
 });

package/cli/commands/releaseCommand/index.ts

@@ -1,6 +1,6 @@
 import { program, Option } from "commander";
 import { findAndReadConfigFile } from "../../utils/fsUtils.js";
-import { release } from "./release.js";
+import { DEFAULT_DIFF_BASE_COUNT, release } from "./release.js";
 import {
     DEFAULT_OVERSIZED_PATCH_POLICY,
     OVERSIZED_PATCH_POLICIES,
@@ -30,6 +30,7 @@ type Options = {
     hashCalc?: boolean;
     binaryBundlePath?: string;
     onOversizedPatch: OversizedPatchPolicy;
+    diffBaseCount: number;
 }
 
 program.command('release')
@@ -55,6 +56,7 @@ program.command('release')
     .addOption(new Option('--on-oversized-patch <policy>', 'what to do when the binary patch bundle is not smaller than the full bundle: "skip" releases the full bundle only, "fail" stops the release before any upload')
         .choices(OVERSIZED_PATCH_POLICIES)
         .default(DEFAULT_OVERSIZED_PATCH_POLICY))
+    .option('--diff-base-count <number>', 'how many recent releases to build asset diff archives against (0 disables). Requires `bundleDownloader` in the config file.', parseDecimalInt, DEFAULT_DIFF_BASE_COUNT)
     .action(async (options: Options) => {
         const config = findAndReadConfigFile(process.cwd(), options.config);
 
@@ -63,6 +65,11 @@ program.command('release')
             process.exit(1);
         }
 
+        if (!Number.isInteger(options.diffBaseCount) || options.diffBaseCount < 0) {
+            console.error('--diff-base-count must be a whole number of releases, 0 or greater.');
+            process.exit(1);
+        }
+
         if (options.hashCalc && !options.skipBundle) {
             console.error('--hash-calc option can be used only when --skip-bundle is set to true.');
             process.exit(1);
@@ -93,11 +100,19 @@ program.command('release')
             options.hashCalc,
             baseBundlePath,
             options.onOversizedPatch,
+            config.bundleDownloader,
+            options.diffBaseCount,
         )
 
         console.log('🚀 Release completed.')
     });
 
+// Not `parseInt` itself: commander hands a coercion function the current value as its
+// second argument, which `parseInt` reads as the radix.
+function parseDecimalInt(value: string): number {
+    return parseInt(value, 10);
+}
+
 function parseBoolean(value: string): boolean | undefined {
     if (value === 'true') return true;
     if (value === 'false') return false;