@bravemobile/react-native-code-push 13.1.0-beta.2 → 13.1.0-beta.4

package/cli/dist/commands/releaseCommand/index.test.js

@@ -10,6 +10,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,
     }),
@@ -26,6 +27,8 @@ const ARG_INDEX = {
     bundleDirectory: 16,
     baseBundlePath: 19,
     onOversizedPatch: 20,
+    bundleDownloader: 21,
+    diffBaseCount: 22,
 };
 /**
  * Parses a `release` invocation against the real command definition. Commander is asked
@@ -93,4 +96,26 @@ 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) => {
+            throw new Error(`process.exit(${code})`);
+        }));
+        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/dist/commands/releaseCommand/release.js

@@ -4,8 +4,12 @@ import { bundleCodePush, resolveJsBundleName } from "../bundleCommand/bundleCode
 import { addToReleaseHistory } from "./addToReleaseHistory.js";
 import { generatePackageHashFromDirectory } from "../../utils/hash-utils.js";
 import { unzip } from "../../utils/unzip.js";
+import { ASSET_DIFF_ARCHIVE_INFIX, makeAssetDiffBundle } from "../../functions/makeAssetDiffBundle.js";
+import { resolveAssetDiffBases } from "../../functions/resolveAssetDiffBases.js";
 import { BINARY_PATCH_ARCHIVE_SUFFIX, BINARY_PATCH_BASE_RECORD_NAME, DEFAULT_OVERSIZED_PATCH_POLICY, extractCodePushBundleContents, formatBinaryPatchSummary, hashBundleFile, isPatchArchiveOversized, makeBinaryPatchBundle, readBinaryPatchBaseRecord, } from "../../functions/makeBinaryPatchBundle.js";
-export async function release(bundleUploader, getReleaseHistory, setReleaseHistory, binaryVersion, appVersion, framework, platform, identifier, outputPath, entryFile, jsBundleName, mandatory, enable, rollout, skipBundle, skipCleanup, bundleDirectory, outputMetroDir, hashCalc, baseBundlePath, onOversizedPatch = DEFAULT_OVERSIZED_PATCH_POLICY) {
+/** How many of the most recent releases a release builds asset diff archives against. */
+export const DEFAULT_DIFF_BASE_COUNT = 3;
+export async function release(bundleUploader, getReleaseHistory, setReleaseHistory, binaryVersion, appVersion, framework, platform, identifier, outputPath, entryFile, jsBundleName, mandatory, enable, rollout, skipBundle, skipCleanup, bundleDirectory, outputMetroDir, hashCalc, baseBundlePath, onOversizedPatch = DEFAULT_OVERSIZED_PATCH_POLICY, bundleDownloader, diffBaseCount = DEFAULT_DIFF_BASE_COUNT) {
     if (baseBundlePath) {
         // Checked before the bundler runs, so the wrong base bundle costs a second rather
         // than a full build.
@@ -36,15 +40,59 @@ export async function release(bundleUploader, getReleaseHistory, setReleaseHisto
             onOversizedPatch,
         })
         : null;
+    // A diff is the patch archive with what a base package already holds taken out, so it
+    // only exists where a patch does - and only a consumer that can hand back a released
+    // archive can supply the bases to diff against.
+    const assetDiffArtifacts = binaryPatch && bundleDownloader && diffBaseCount > 0
+        ? await makeAssetDiffArtifacts({
+            patchBundleFilePath: binaryPatch.patchBundleFilePath,
+            releaseHistory: await getReleaseHistory(binaryVersion, platform, identifier),
+            diffBaseCount,
+            bundleDownloader,
+            bundleDirectory,
+            packageHash,
+            targetBinaryVersion: binaryVersion,
+            platform,
+            identifier,
+        })
+        : [];
     // Every artifact is uploaded before the release history is touched, so a failed
     // upload leaves the history describing only updates that can actually be downloaded.
-    const downloadUrl = await uploadArtifact(bundleUploader, bundleFilePath, platform, identifier, 'bundle');
+    const downloadUrl = await uploadArtifact(bundleUploader, bundleFilePath, platform, identifier, {
+        type: 'full-bundle',
+        targetBinaryVersion: binaryVersion,
+        packageHash,
+    }, 'bundle');
     let patchDownloadUrl;
     if (binaryPatch) {
-        patchDownloadUrl = await uploadArtifact(bundleUploader, binaryPatch.patchBundleFilePath, platform, identifier, 'binary patch bundle');
+        patchDownloadUrl = await uploadArtifact(bundleUploader, binaryPatch.patchBundleFilePath, platform, identifier, {
+            type: 'binary-patch',
+            targetBinaryVersion: binaryVersion,
+            packageHash,
+        }, 'binary patch bundle');
         console.log(`log: Binary patch archive uploaded (download url: ${patchDownloadUrl})`);
     }
-    await addToReleaseHistory(appVersion, binaryVersion, downloadUrl, patchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout);
+    const diffPackages = {};
+    for (const { basePackageHash, filePath } of assetDiffArtifacts) {
+        // A diff is an optimisation on top of the patch archive, which is uploaded by now:
+        // one that cannot be uploaded is left out of the history instead of failing the
+        // release the other two artifacts are ready for.
+        try {
+            const diffDownloadUrl = await uploadFile(bundleUploader, filePath, platform, identifier, {
+                type: 'asset-diff',
+                targetBinaryVersion: binaryVersion,
+                packageHash,
+                basePackageHash,
+            });
+            diffPackages[basePackageHash] = diffDownloadUrl;
+            console.log(`log: Asset diff archive against ${basePackageHash} uploaded (download url: ${diffDownloadUrl})`);
+        }
+        catch (error) {
+            console.warn(`warn: Skipping the asset diff archive against ${basePackageHash}: it could not be uploaded ` +
+                `(${error instanceof Error ? error.message : String(error)}).`);
+        }
+    }
+    await addToReleaseHistory(appVersion, binaryVersion, downloadUrl, patchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, Object.keys(diffPackages).length > 0 ? diffPackages : undefined);
     if (!skipCleanup) {
         cleanUpOutputs(outputPath);
     }
@@ -53,9 +101,9 @@ function cleanUpOutputs(dir) {
     fs.rmSync(dir, { recursive: true });
 }
 function readBundleFileNameFrom(bundleDirectory) {
-    // A previous release of the same bundle may have left its patch archive here, and
-    // that archive is derived from the bundle file rather than a candidate for release.
-    const files = fs.readdirSync(bundleDirectory).filter((file) => !file.endsWith(BINARY_PATCH_ARCHIVE_SUFFIX));
+    // A previous release of the same bundle may have left its patch and diff archives
+    // here, and those are derived from the bundle file rather than candidates for release.
+    const files = fs.readdirSync(bundleDirectory).filter((file) => !file.endsWith(BINARY_PATCH_ARCHIVE_SUFFIX) && !file.includes(ASSET_DIFF_ARCHIVE_INFIX));
     if (files.length !== 1) {
         console.error('The bundlePath must contain only one file.');
         process.exit(1);
@@ -137,6 +185,52 @@ async function makeBinaryPatchArtifact({ baseBundlePath, contentsPath, bundleFil
         }
     }
 }
+/**
+ * Builds a diff artifact per recently released package, for the clients holding one.
+ *
+ * A base that cannot be downloaded or verified is left out by the resolver, and a diff
+ * that comes out no smaller than the patch archive is not published. Either way the
+ * release goes out with its full and patch archives, serving fewer diffs.
+ *
+ * @return {Promise<AssetDiffArtifact[]>} The diff archives to upload, each naming the package it was built against.
+ */
+async function makeAssetDiffArtifacts({ patchBundleFilePath, releaseHistory, diffBaseCount, bundleDownloader, bundleDirectory, packageHash, targetBinaryVersion, platform, identifier, }) {
+    const bases = await resolveAssetDiffBases({
+        releaseHistory,
+        diffBaseCount,
+        bundleDownloader,
+        platform,
+        identifier,
+        targetBinaryVersion,
+    });
+    const artifacts = [];
+    const builtAgainst = new Set();
+    for (const base of bases) {
+        // Releasing identical contents twice leaves two history entries describing one
+        // package, and their diff is the same archive built - and named - twice.
+        if (builtAgainst.has(base.basePackageHash)) {
+            continue;
+        }
+        builtAgainst.add(base.basePackageHash);
+        try {
+            const assetDiff = await makeAssetDiffBundle({
+                patchBundleFilePath,
+                baseBundleFilePath: base.baseBundleFilePath,
+                bundleDirectory,
+                packageHash,
+                basePackageHash: base.basePackageHash,
+            });
+            if (assetDiff) {
+                artifacts.push({ basePackageHash: base.basePackageHash, filePath: assetDiff.diffBundleFilePath });
+            }
+        }
+        catch (error) {
+            console.warn(`warn: Skipping the asset diff against ${base.basePackageHash}: it could not be built ` +
+                `(${error instanceof Error ? error.message : String(error)}).`);
+        }
+    }
+    return artifacts;
+}
 /**
  * Cross-checks the base bundle against the record a build hook exported next to it.
  *
@@ -198,13 +292,17 @@ function warnOnBaseBundleMismatch(outputPath, baseBundlePath) {
             'The patch is valid but larger than an aligned one.');
     }
 }
-async function uploadArtifact(bundleUploader, filePath, platform, identifier, artifactName) {
+/** Uploads an artifact the release cannot go out without, so a failure ends the program. */
+async function uploadArtifact(bundleUploader, filePath, platform, identifier, artifact, artifactName) {
     try {
-        const { downloadUrl } = await bundleUploader(filePath, platform, identifier);
-        return downloadUrl;
+        return await uploadFile(bundleUploader, filePath, platform, identifier, artifact);
     }
     catch (error) {
         console.error(`Failed to upload the ${artifactName} file. Exiting the program.\n`, error);
         process.exit(1);
     }
 }
+async function uploadFile(bundleUploader, filePath, platform, identifier, artifact) {
+    const { downloadUrl } = await bundleUploader(filePath, platform, identifier, artifact);
+    return downloadUrl;
+}

package/cli/dist/commands/releaseCommand/release.test.js

@@ -1,9 +1,11 @@
+import crypto from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, jest } from "@jest/globals";
 import { release } from "./release.js";
 import { makeCodePushBundle } from "../../functions/makeCodePushBundle.js";
+import { ASSET_DIFF_ARCHIVE_INFIX, assetDiffArchiveName } from "../../functions/makeAssetDiffBundle.js";
 import { BINARY_PATCH_ARCHIVE_SUFFIX, BINARY_PATCH_BASE_RECORD_NAME, BINARY_PATCH_MANIFEST_NAME, hashBundleFile, writeBinaryPatchBaseRecord, } from "../../functions/makeBinaryPatchBundle.js";
 import { applyPatch } from "../../utils/binaryPatch.js";
 import { generatePackageHashFromDirectory } from "../../utils/hash-utils.js";
@@ -64,33 +66,37 @@ class ProcessExitError extends Error {
     }
 }
 function recordingUploader(uploads, failOn) {
-    return async (filePath) => {
+    return async (filePath, _platform, _identifier, artifact) => {
         if (failOn?.(filePath)) {
             throw new Error(`upload rejected: ${path.basename(filePath)}`);
         }
         const downloadUrl = `https://cdn.example.com/${path.basename(filePath)}`;
-        uploads.push({ filePath, downloadUrl, logCountBeforeUpload: logs.length });
+        uploads.push({ artifact, filePath, downloadUrl, logCountBeforeUpload: logs.length });
         return { downloadUrl };
     };
 }
-function historyStore() {
+function historyStore(existingHistory = {}, onSave) {
     const saved = [];
     return {
         saved,
-        getReleaseHistory: async () => ({}),
+        getReleaseHistory: async () => existingHistory,
         setReleaseHistory: async (_binaryVersion, _jsonFilePath, releaseInfo) => {
+            onSave?.();
             saved.push(releaseInfo);
         },
     };
 }
 async function runRelease(staged, overrides = {}) {
     const uploads = overrides.uploads ?? [];
-    const history = historyStore();
+    const uploadCountsWhenHistorySaved = [];
+    const history = historyStore(overrides.releaseHistory, () => {
+        uploadCountsWhenHistorySaved.push(uploads.length);
+    });
     await release(recordingUploader(uploads, overrides.uploadFailsFor), history.getReleaseHistory, history.setReleaseHistory, BINARY_VERSION, APP_VERSION, undefined, overrides.platform ?? 'ios', undefined, staged.outputPath, 'index.ts', 
     // Left unset unless the case is about -j, the way commander leaves it.
     overrides.jsBundleName, false, true, undefined, true, // skipBundle
-    overrides.skipCleanup ?? true, staged.bundleDirectory, undefined, undefined, overrides.binaryBundlePath, overrides.onOversizedPatch);
-    return { uploads, releaseHistories: history.saved };
+    overrides.skipCleanup ?? true, staged.bundleDirectory, undefined, undefined, overrides.binaryBundlePath, overrides.onOversizedPatch, overrides.bundleDownloader, overrides.diffBaseCount);
+    return { uploads, releaseHistories: history.saved, uploadCountsWhenHistorySaved };
 }
 let logs;
 beforeAll(() => {
@@ -118,11 +124,21 @@ afterEach(() => {
     fs.rmSync(path.resolve(process.cwd(), `${BINARY_VERSION}.json`), { force: true });
 });
 describe("release without --binary-bundle-path", () => {
+    it("keeps existing three-argument uploaders callable", async () => {
+        const legacyUploader = async (source, _platform, _identifier) => ({ downloadUrl: source });
+        const uploader = legacyUploader;
+        await expect(uploader('bundle.zip', 'ios')).resolves.toEqual({ downloadUrl: 'bundle.zip' });
+    });
     it("uploads the full bundle only, exactly as before binary patches existed", async () => {
         const staged = await stageBundleOutput("full-only");
         const { uploads, releaseHistories } = await runRelease(staged);
         expect(uploads).toHaveLength(1);
         expect(uploads[0].filePath).toBe(`${staged.bundleDirectory}/${staged.bundleFileName}`);
+        expect(uploads[0].artifact).toEqual({
+            type: 'full-bundle',
+            targetBinaryVersion: BINARY_VERSION,
+            packageHash: staged.bundleFileName,
+        });
         expect(fs.readdirSync(staged.bundleDirectory)).toEqual([staged.bundleFileName]);
         expect(releaseHistories[0][APP_VERSION]).toEqual({
             enabled: true,
@@ -365,3 +381,185 @@ describe("release --on-oversized-patch", () => {
         expect(uploads).toHaveLength(2);
     });
 });
+/**
+ * A release can also ship a diff per recently released package: the patch archive without
+ * the files that package already holds. The bases come out of the release history and are
+ * downloaded through the consumer's `bundleDownloader`, so a release only builds diffs
+ * where the consumer supplied one.
+ */
+describe("release with asset diff bases", () => {
+    /**
+     * The asset both packages hold. Sized like a real asset because a diff is only shipped
+     * when it comes out smaller than the patch archive it was derived from.
+     */
+    const sharedAsset = crypto.randomBytes(4096);
+    const PREVIOUS_APP_VERSION = '9.9.9';
+    function updateFiles() {
+        return { 'main.jsbundle': fs.readFileSync(targetFixture), 'assets/keep.png': sharedAsset };
+    }
+    /**
+     * A package released earlier, as the history describes it and as the CDN serves it.
+     *
+     * @param ownAsset An asset only this release holds, which is what makes two staged base releases two packages rather than one.
+     */
+    async function stageBaseRelease(caseName, ownAsset) {
+        const caseDir = fs.mkdtempSync(path.join(workDir, `${caseName}-base-`));
+        const contentsPath = path.join(caseDir, CONTENTS_DIR_NAME);
+        const files = {
+            'main.jsbundle': fs.readFileSync(baseFixture),
+            'assets/keep.png': sharedAsset,
+            ...(ownAsset === undefined ? {} : { 'assets/dropped.png': ownAsset }),
+        };
+        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);
+        }
+        const archiveDir = path.join(caseDir, 'archive');
+        const { bundleFileName } = await makeCodePushBundle(contentsPath, archiveDir);
+        return {
+            downloadUrl: `https://cdn.example.com/released/${bundleFileName}`,
+            packageHash: bundleFileName,
+            archivePath: path.join(archiveDir, bundleFileName),
+        };
+    }
+    function releaseHistoryOf(base, versions = [PREVIOUS_APP_VERSION]) {
+        return Object.fromEntries(versions.map((version) => [
+            version,
+            {
+                enabled: true,
+                mandatory: false,
+                downloadUrl: base.downloadUrl,
+                packageHash: base.packageHash,
+            },
+        ]));
+    }
+    /** Serves the staged base archives, and records which releases were asked for. */
+    function recordingDownloader(bases, downloads) {
+        return async (archive) => {
+            downloads.push(archive.downloadUrl);
+            const base = bases.find((candidate) => candidate.downloadUrl === archive.downloadUrl);
+            if (!base) {
+                throw new Error(`the downloader was called with an unexpected url: ${archive.downloadUrl}`);
+            }
+            return { downloadedFilePath: base.archivePath };
+        };
+    }
+    it("publishes asset diff archives against recent releases and records them in the history", async () => {
+        const staged = await stageBundleOutput("asset-diff", updateFiles());
+        const base = await stageBaseRelease("asset-diff");
+        const downloads = [];
+        const { uploads, releaseHistories, uploadCountsWhenHistorySaved } = await runRelease(staged, {
+            binaryBundlePath: baseFixture,
+            releaseHistory: releaseHistoryOf(base),
+            bundleDownloader: recordingDownloader([base], downloads),
+        });
+        const diffFileName = `${staged.bundleFileName}${ASSET_DIFF_ARCHIVE_INFIX}${base.packageHash}.zip`;
+        // The diff is the last artifact: it is an optimisation on top of the patch, which
+        // is itself an optimisation on top of the full archive.
+        expect(uploads.map(({ filePath }) => path.basename(filePath))).toEqual([
+            staged.bundleFileName,
+            `${staged.bundleFileName}${BINARY_PATCH_ARCHIVE_SUFFIX}`,
+            diffFileName,
+        ]);
+        expect(uploads.map(({ artifact }) => artifact)).toEqual([
+            {
+                type: 'full-bundle',
+                targetBinaryVersion: BINARY_VERSION,
+                packageHash: staged.bundleFileName,
+            },
+            {
+                type: 'binary-patch',
+                targetBinaryVersion: BINARY_VERSION,
+                packageHash: staged.bundleFileName,
+            },
+            {
+                type: 'asset-diff',
+                targetBinaryVersion: BINARY_VERSION,
+                packageHash: staged.bundleFileName,
+                basePackageHash: base.packageHash,
+            },
+        ]);
+        expect(downloads).toEqual([base.downloadUrl]);
+        // Every artifact is uploaded before the history points at any of them.
+        expect(uploadCountsWhenHistorySaved).toEqual([3]);
+        expect(releaseHistories[0][APP_VERSION].diffPackages).toEqual({
+            [base.packageHash]: uploads[2].downloadUrl,
+        });
+        expect(fs.existsSync(path.join(staged.bundleDirectory, diffFileName))).toBe(true);
+    });
+    it("publishes without diff archives when the config has no bundle downloader", async () => {
+        const staged = await stageBundleOutput("no-downloader", updateFiles());
+        const base = await stageBaseRelease("no-downloader");
+        const { uploads, releaseHistories } = await runRelease(staged, {
+            binaryBundlePath: baseFixture,
+            releaseHistory: releaseHistoryOf(base),
+        });
+        expect(uploads).toHaveLength(2);
+        // A release without diffs says nothing about them, so a client reading this history
+        // behaves exactly as it did before asset diffs existed.
+        expect(releaseHistories[0][APP_VERSION]).not.toHaveProperty('diffPackages');
+    });
+    it("publishes without diff archives when --diff-base-count is zero", async () => {
+        const staged = await stageBundleOutput("zero-bases", updateFiles());
+        const base = await stageBaseRelease("zero-bases");
+        const downloads = [];
+        const { uploads, releaseHistories } = await runRelease(staged, {
+            binaryBundlePath: baseFixture,
+            releaseHistory: releaseHistoryOf(base),
+            bundleDownloader: recordingDownloader([base], downloads),
+            diffBaseCount: 0,
+        });
+        expect(uploads).toHaveLength(2);
+        expect(downloads).toEqual([]);
+        expect(releaseHistories[0][APP_VERSION]).not.toHaveProperty('diffPackages');
+    });
+    it("builds one diff archive when two releases hold the same package", async () => {
+        const staged = await stageBundleOutput("repeated-base", updateFiles());
+        const base = await stageBaseRelease("repeated-base");
+        const downloads = [];
+        const { uploads, releaseHistories } = await runRelease(staged, {
+            binaryBundlePath: baseFixture,
+            releaseHistory: releaseHistoryOf(base, ['9.9.8', PREVIOUS_APP_VERSION]),
+            bundleDownloader: recordingDownloader([base], downloads),
+        });
+        expect(downloads).toHaveLength(2);
+        expect(uploads.filter(({ filePath }) => filePath.includes(ASSET_DIFF_ARCHIVE_INFIX))).toHaveLength(1);
+        expect(releaseHistories[0][APP_VERSION].diffPackages).toEqual({
+            [base.packageHash]: uploads[2].downloadUrl,
+        });
+    });
+    it("releases the diffs that uploaded when one of them is rejected", async () => {
+        const staged = await stageBundleOutput("diff-upload-failure", updateFiles());
+        // Two packages to diff against, one of whose diffs the storage backend refuses.
+        const rejected = await stageBaseRelease("diff-upload-failure-rejected");
+        const kept = await stageBaseRelease("diff-upload-failure-kept", 'an asset of the older release');
+        const downloads = [];
+        const { uploads, releaseHistories } = await runRelease(staged, {
+            binaryBundlePath: baseFixture,
+            releaseHistory: {
+                ...releaseHistoryOf(kept, ['9.9.8']),
+                ...releaseHistoryOf(rejected, [PREVIOUS_APP_VERSION]),
+            },
+            bundleDownloader: recordingDownloader([kept, rejected], downloads),
+            uploadFailsFor: (filePath) => filePath.includes(rejected.packageHash),
+        });
+        expect(uploads.map(({ filePath }) => path.basename(filePath))).toEqual([
+            staged.bundleFileName,
+            `${staged.bundleFileName}${BINARY_PATCH_ARCHIVE_SUFFIX}`,
+            `${staged.bundleFileName}${ASSET_DIFF_ARCHIVE_INFIX}${kept.packageHash}.zip`,
+        ]);
+        // The release goes out with the two artifacts it needs, and describes only the diff
+        // a client can actually download.
+        expect(releaseHistories[0][APP_VERSION].diffPackages).toEqual({
+            [kept.packageHash]: uploads[2].downloadUrl,
+        });
+        expect(logs.filter((line) => line.startsWith('warn:')).join('\n')).toMatch(new RegExp(`Skipping the asset diff archive against ${rejected.packageHash}`));
+    });
+    it("still picks the full bundle when diff archives sit in the output directory", async () => {
+        const staged = await stageBundleOutput("leftover-diff");
+        fs.writeFileSync(path.join(staged.bundleDirectory, assetDiffArchiveName('stale', 'stale-base')), 'stale');
+        const { uploads } = await runRelease(staged, { binaryBundlePath: baseFixture });
+        expect(path.basename(uploads[0].filePath)).toBe(staged.bundleFileName);
+    });
+});

package/cli/dist/functions/makeAssetDiffBundle.js

@@ -0,0 +1,114 @@
+/**
+ * Builds the diff artifact a client can install on top of one particular base package.
+ *
+ * A diff archive is the patch archive of this release with every file the base package
+ * already holds byte for byte taken out, plus a manifest naming the files the base holds
+ * that the update dropped. A client copies its installed base package, applies the
+ * deletions, rebuilds the JS bundle from the patch and overlays what the diff shipped -
+ * which leaves it holding exactly the contents of the full archive, and therefore the
+ * same `packageHash`. One release can serve a diff per base it was built against.
+ *
+ * The diff is derived from the artifacts the release already produced rather than from
+ * the bundler, so it costs no extra bundling and cannot drift from what was published.
+ */
+import fs from "fs";
+import path from "path";
+import shell from "shelljs";
+import { normalizePath } from "../utils/file-utils.js";
+import { walk } from "../utils/promisfied-fs.js";
+import { zipDirectoryContents } from "../utils/zip.js";
+import { BINARY_PATCH_MANIFEST_NAME, extractCodePushBundleContents, } from "./makeBinaryPatchBundle.js";
+/**
+ * Manifest listing what a client must delete from its copy of the base package. It sits
+ * at the archive root, outside the contents directory, because that is where the native
+ * clients look for it - and because a file inside the contents would change the package
+ * hash the merged folder has to reproduce.
+ */
+export const ASSET_DIFF_MANIFEST_NAME = 'hotcodepush.json';
+/** Separates the two hashes, so a diff archive names both the update and the base it needs. */
+export const ASSET_DIFF_ARCHIVE_INFIX = '-diff-';
+const TEMP_ASSET_DIFF_DIR_NAME = 'temp_contents_for_asset_diff';
+export function assetDiffArchiveName(packageHash, basePackageHash) {
+    return `${packageHash}${ASSET_DIFF_ARCHIVE_INFIX}${basePackageHash}.zip`;
+}
+/**
+ * Creates the diff archive for a release against one base package.
+ *
+ * @param patchBundleFilePath {string} Patch archive this release already built
+ * @param baseBundleFilePath {string} Full archive of the base release, downloaded locally
+ * @param bundleDirectory {string} Directory the release artifacts are written to
+ * @param packageHash {string} Package hash of this release
+ * @param basePackageHash {string} Package hash of the base release
+ * @return The diff archive, or `null` when it is not smaller than the patch archive it
+ * was derived from, in which case there is nothing to gain from publishing it.
+ */
+export async function makeAssetDiffBundle({ patchBundleFilePath, baseBundleFilePath, bundleDirectory, packageHash, basePackageHash, }) {
+    // Kept next to the release output rather than in the system temp directory so a crash
+    // leaves the leftovers where the rest of the build output is cleaned up. Named after
+    // the base so building the diffs of one release against several bases at once cannot
+    // have two of them share a working directory.
+    const tempRoot = path.join(path.dirname(path.resolve(bundleDirectory)), `${TEMP_ASSET_DIFF_DIR_NAME}_${basePackageHash}`);
+    const stagingRoot = path.join(tempRoot, 'archive');
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+    try {
+        // Extracted into separate parents: `extractCodePushBundleContents` reuses one
+        // directory name, so a shared parent would have the second unpack wipe the first.
+        const { contentsPath: patchContents } = await extractCodePushBundleContents(patchBundleFilePath, path.join(tempRoot, 'patch-archive'));
+        const { contentsPath: baseContents } = await extractCodePushBundleContents(baseBundleFilePath, path.join(tempRoot, 'base-archive'));
+        const patchManifest = JSON.parse(fs.readFileSync(path.join(patchContents, BINARY_PATCH_MANIFEST_NAME), 'utf8'));
+        // Manifest paths are compared against archive-relative paths, which are POSIX.
+        const patchFile = normalizePath(patchManifest.patchFile);
+        const bundlePath = normalizePath(patchManifest.bundlePath);
+        // What the full archive of this release holds: the patch archive without its two
+        // patch-only files, plus the bundle the patch rebuilds. Deletions are worked out
+        // against that set, not against the subset the diff happens to ship.
+        const patchFiles = await listFilesRelative(patchContents);
+        const updateFiles = new Set(patchFiles.filter((relativePath) => relativePath !== BINARY_PATCH_MANIFEST_NAME && relativePath !== patchFile));
+        updateFiles.add(bundlePath);
+        // The archive root directory name is part of the contents layout, so the diff
+        // archive has to reuse the name the full archive used.
+        const contentsDirName = path.basename(patchContents);
+        const stagedContents = path.join(stagingRoot, contentsDirName);
+        fs.cpSync(patchContents, stagedContents, { recursive: true });
+        for (const relativePath of patchFiles) {
+            const baseFile = path.join(baseContents, relativePath);
+            if (fs.existsSync(baseFile) && sameBytes(path.join(patchContents, relativePath), baseFile)) {
+                fs.rmSync(path.join(stagedContents, relativePath));
+            }
+        }
+        const manifest = {
+            deletedFiles: (await listFilesRelative(baseContents))
+                .filter((relativePath) => !updateFiles.has(relativePath))
+                .map((relativePath) => `${contentsDirName}/${relativePath}`),
+        };
+        fs.writeFileSync(path.join(stagingRoot, ASSET_DIFF_MANIFEST_NAME), JSON.stringify(manifest, null, 2));
+        const diffArchiveZipPath = await zipDirectoryContents(stagingRoot);
+        if (fs.statSync(diffArchiveZipPath).size >= fs.statSync(patchBundleFilePath).size) {
+            // A diff that costs a client as much as the patch archive is never the better
+            // artifact of the two, and the release still publishes that patch archive.
+            fs.rmSync(diffArchiveZipPath);
+            return null;
+        }
+        const diffBundleFilePath = path.join(bundleDirectory, assetDiffArchiveName(packageHash, basePackageHash));
+        shell.mkdir('-p', bundleDirectory);
+        shell.mv(diffArchiveZipPath, diffBundleFilePath);
+        return { diffBundleFilePath };
+    }
+    finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+}
+/** Every file below `directoryPath`, as POSIX paths relative to it. */
+async function listFilesRelative(directoryPath) {
+    const files = await walk(directoryPath);
+    return files.map((filePath) => normalizePath(path.relative(directoryPath, filePath)));
+}
+function sameBytes(left, right) {
+    // A base that holds a directory where the update holds a file has nothing the update
+    // can be spared from downloading, so the file ships.
+    const rightStats = fs.statSync(right);
+    if (!rightStats.isFile() || fs.statSync(left).size !== rightStats.size) {
+        return false;
+    }
+    return fs.readFileSync(left).equals(fs.readFileSync(right));
+}