fix: Skip lipo if native module is already universal. Add native module fixtures for lipo tests (#126)

* fix: when native modules are already universal, don't lipo. adds `node-mac-permissions` fixture from https://github.com/codebytere/node-mac-permissions and resolves 3 `it.todo` test cases

* add test `different app dirs with different macho files (shim and lipo)`

* add additional test

* PR feedback

* gotta close `fd`

* use `stream` to read first 4 bytes. copy native fixture before packing into asar to leverage `unpack: "**/*.node"` properly.

* convert params to object

* rename `createTestApp` to `createStagingAppDir` and add jsdoc to the function

* compiler error from merge conflict

* update snapshots

* update snapshots

* only check x64Content since it's the tmp app

* compile macho binaries at runtime using hellow-world.c for fixtures in lipo tests

* Update jest.setup.ts

Co-authored-by: Erik Moura <erikian@erikian.dev>

* Update jest.setup.ts

Co-authored-by: Erik Moura <erikian@erikian.dev>

* remove unstable properties for specific keys

* force redo

* update snapshots

* stripping only hello-world from snapshot and only hash from macho-specific asar integrity

* optimize logic :)

---------

Co-authored-by: Erik Moura <erikian@erikian.dev>

.circleci/config.yml

@@ -1,35 +0,0 @@
-version: 2.1
-
-orbs:
-  cfa: continuousauth/npm@2.0.0
-  node: electronjs/node@2.1.0
-
-workflows:
-  test_and_release:
-    # Run the test jobs first, then the release only when all the test jobs are successful
-    jobs:
-      - node/test:
-          executor: node/macos
-          name: test-mac-<< matrix.node-version >>
-          override-ci-command: yarn install --frozen-lockfile --ignore-engines
-          test-steps:
-            - node/install-rosetta
-            - run: yarn build
-            - run: yarn lint
-            - run: yarn test
-          use-test-steps: true
-          matrix:
-            alias: test
-            parameters:
-              node-version:
-                - 20.5.0
-                - 18.17.0
-                - 16.20.1
-      - cfa/release:
-          requires:
-            - test
-          filters:
-            branches:
-              only:
-                - main
-          context: cfa-release

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/add-to-project.yml

@@ -21,7 +21,7 @@ jobs:
           creds: ${{ secrets.ECOSYSTEM_ISSUE_TRIAGE_GH_APP_CREDS }}
           org: electron
       - name: Add to Project
-        uses: dsanders11/project-actions/add-item@3a81985616963f32fae17d1d1b406c631f3201a1 # v1.1.0
+        uses: dsanders11/project-actions/add-item@2134fe7cc71c58b7ae259c82a8e63c6058255678 # v1.7.0
         with:
           field: Opened
           field-value: ${{ github.event.pull_request.created_at || github.event.issue.created_at }}

.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: test
+    environment: npm
+    permissions:
+      id-token: write # for CFA and npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20.x
+          cache: 'yarn'
+      - name: Install
+        run: yarn install --frozen-lockfile
+      - uses: continuousauth/action@4e8a2573eeb706f6d7300d6a9f3ca6322740b72d # v1.0.5
+        with:
+          project-id: ${{ secrets.CFA_PROJECT_ID }}
+          secret: ${{ secrets.CFA_SECRET }}
+          npm-token: ${{ secrets.NPM_TOKEN }}

.github/workflows/semantic.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: semantic-pull-request
-        uses: amannn/action-semantic-pull-request@c3cd5d1ea3580753008872425915e343e351ab54 # v5.2.0
+        uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:

.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: '0 22 * * 3'
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - '20.5'
+          - '18.17'
+          - '16.20'
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "${{ matrix.node-version }}"
+          cache: 'yarn'
+      - name: Install (Node.js v18+)
+        if : ${{ matrix.node-version != '16.20' }}
+        run: yarn install --frozen-lockfile
+      - name: Install (Node.js < v18)
+        if : ${{ matrix.node-version == '16.20' }}
+        run: yarn install --frozen-lockfile --ignore-engines
+      - name: Build
+        run: yarn build
+      - name: Lint
+        run: yarn lint
+      - name: Test
+        run: yarn test

.gitignore

@@ -5,3 +5,5 @@ entry-asar/*.ts
 *.app
 test/fixtures/apps
 coverage
+docs
+.vscode

.prettierrc.json

@@ -3,5 +3,13 @@
   "tabWidth": 2,
   "singleQuote": true,
   "printWidth": 100,
-  "parser": "typescript"
+  "parser": "typescript",
+  "overrides": [
+    {
+      "files": ["*.json", "*.jsonc", "*.json5"],
+      "options": {
+        "parser": "json"
+      }
+    }
+  ]
 }

README.md

@@ -2,12 +2,16 @@
 
 > Create universal macOS Electron applications
 
-[![CircleCI](https://circleci.com/gh/electron/universal/tree/main.svg?style=shield)](https://circleci.com/gh/electron/universal)
+[![Test](https://github.com/electron/universal/actions/workflows/test.yml/badge.svg)](https://github.com/electron/universal/actions/workflows/test.yml)
 [![NPM package](https://img.shields.io/npm/v/@electron/universal)](https://npm.im/@electron/universal)
 
-
 ## Usage
 
+This package takes an x64 app and an arm64 app and glues them together into a
+[Universal macOS binary](https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary).
+
+Note that parameters need to be **absolute** paths.
+
 ```typescript
 import { makeUniversalApp } from '@electron/universal';
 
@@ -18,20 +22,104 @@ await makeUniversalApp({
 });
 ```
 
+## Advanced configuration
+
+The basic usage patterns will work for most apps out of the box. Additional configuration
+options are available for advanced usecases.
+
+### Merging ASAR archives to reduce app size
+
+**Added in [v1.2.0](https://github.com/electron/universal/commit/38ab1c3559e25382957d608e49e624dc72a4409c)**
+
+If you are using ASAR archives to store your Electron app's JavaScript code, you can use the
+`mergeASARs` option to merge your x64 and arm64 ASAR files to reduce the bundle size of
+the output Universal app.
+
+If some files are present in only the x64 app but not the arm64 version (or vice-versa),
+you can exclude them from the merging process by specifying a `minimatch` pattern
+in `singleArchFiles`.
+
+```typescript
+import { makeUniversalApp } from '@electron/universal';
+
+await makeUniversalApp({
+  x64AppPath: 'path/to/App_x64.app',
+  arm64AppPath: 'path/to/App_arm64.app',
+  outAppPath: 'path/to/App_universal.app',
+  mergeASARs: true,
+  singleArchFiles: 'node_modules/some-native-module/lib/binding/Release/**', // if you have files in your asar that are unique to x64 or arm64 apps
+});
+```
+
+If `@electron/universal` detects an architecture-unique file that isn't covered by the
+`singleArchFiles` rule, an error will be thrown.
+
+### Skip lipo for certain binaries in your Universal app
+
+**Added in [1.3.0](https://github.com/electron/universal/commit/01dfb8a9636965fe154192b07934670dd42509f3)**
+
+If your Electron app contains binary resources that are already merged with the
+`lipo` tool, providing a [`minimatch`] pattern to matching files in the `x64ArchFiles`
+parameter will prevent `@electron/universal` from attempting to merge them a second time.
+
+```typescript
+import { makeUniversalApp } from '@electron/universal';
+
+await makeUniversalApp({
+  x64AppPath: 'path/to/App_x64.app',
+  arm64AppPath: 'path/to/App_arm64.app',
+  outAppPath: 'path/to/App_universal.app',
+  mergeASARs: true,
+  x64ArchFiles: '*/electron-helper', // `electron-helper` is a binary merged using `lipo`
+});
+```
+
+If `@electron/universal` detects a lipo'd file that isn't covered by the `x64ArchFiles` rule,
+an error will be thrown.
+
+### Including already codesigned app bundles into your Universal app
+
+**Added in [v1.4.0](https://github.com/electron/universal/commit/b02ce7697fd2a3c2c79e1f6ab6bf7052125865cc)**
+
+By default, the merging process will generate an `ElectronAsarIntegrity` key for
+any `Info.plist` files in your Electron app.
+
+If your Electron app bundles another `.app` that is already signed, you need to use
+the `infoPlistsToIgnore` option to avoid modifying that app's plist.
+
+```typescript
+import { makeUniversalApp } from '@electron/universal';
+
+await makeUniversalApp({
+  x64AppPath: 'path/to/App_x64.app',
+  arm64AppPath: 'path/to/App_arm64.app',
+  outAppPath: 'path/to/App_universal.app',
+  infoPlistsToIgnore: 'my-internal.app/Contents/Info.plist'
+});
+```
+
 ## FAQ
 
 #### The app is twice as big now, why?
 
-Well, a Universal app isn't anything magical.  It is literally the x64 app and
-the arm64 app glued together into a single application.  It's twice as big
-because it contains two apps in one.
+A Universal app is just the x64 app and the arm64 app glued together into a single application.
+It's twice as big because it contains two apps in one.
+
+Merging your ASAR bundles can yield significant app size reductions depending on how large
+your `app.asar` file is.
 
 #### What about native modules?
 
-The way `@electron/universal` works today means you don't need to worry about
-things like building universal versions of your native modules.  As long as
-your x64 and arm64 apps work in isolation the Universal app will work as well.
+Out of the box, you don't need to worry about building universal versions of your
+native modules. As long as your x64 and arm64 apps work in isolation, the Universal
+app will work as well.
+
+Note that if you are using `mergeASARs`, you may need to add architecture-specific
+binary resources to the `singleArchFiles` pattern.
+See [Merging ASARs usage](#merging-asar-archives-to-reduce-app-size) for an example.
 
 #### How do I build my app for Apple silicon in the first place?
 
-Check out the [Electron Apple silicon blog post](https://www.electronjs.org/blog/apple-silicon)
+Check out the [Electron Apple silicon blog post](https://www.electronjs.org/blog/apple-silicon).
+
+[`minimatch`]: https://github.com/isaacs/minimatch?tab=readme-ov-file#features

jest.config.js

@@ -3,12 +3,14 @@ module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
   transform: {
-    '.': [
+    '^.+\\.ts?$': [
       'ts-jest',
       {
-        tsconfig: 'tsconfig.jest.json'
-      }
-    ]
+        tsconfig: 'tsconfig.jest.json',
+      },
+    ],
   },
-  globalSetup: './jest.setup.ts'
+  testMatch: ['<rootDir>/test/**/*.spec.ts'],
+  globalSetup: './jest.setup.ts',
+  testTimeout: 10000,
 };

jest.setup.ts

@@ -1,39 +1,49 @@
-import { downloadArtifact } from '@electron/get';
-import * as zip from 'cross-zip';
+import { execFileSync } from 'child_process';
 import * as fs from 'fs-extra';
 import * as path from 'path';
+import { appsDir, asarsDir, fixtureDir, templateApp } from './test/util';
 
-const asarsDir = path.resolve(__dirname, 'test', 'fixtures', 'asars');
-const appsDir = path.resolve(__dirname, 'test', 'fixtures', 'apps');
+// generates binaries from hello-world.c
+// hello-world-universal, hello-world-x86_64, hello-world-arm64
+const generateMachO = () => {
+  const src = path.resolve(fixtureDir, 'hello-world.c');
 
-const templateApp = async (
-  name: string,
-  arch: string,
-  modify: (appPath: string) => Promise<void>,
-) => {
-  const electronZip = await downloadArtifact({
-    artifactName: 'electron',
-    version: '27.0.0',
-    platform: 'darwin',
-    arch,
+  const outputFiles = ['x86_64', 'arm64'].map((arch) => {
+    const machO = path.resolve(appsDir, `hello-world-${arch === 'x86_64' ? 'x64' : arch}`);
+    execFileSync('clang', ['-arch', arch, '-o', machO, src]);
+    return machO;
   });
-  const appPath = path.resolve(appsDir, name);
-  zip.unzipSync(electronZip, appsDir);
-  await fs.rename(path.resolve(appsDir, 'Electron.app'), appPath);
-  await fs.remove(path.resolve(appPath, 'Contents', 'Resources', 'default_app.asar'));
-  await modify(appPath);
+
+  execFileSync('lipo', [
+    ...outputFiles,
+    '-create',
+    '-output',
+    path.resolve(appsDir, 'hello-world-universal'),
+  ]);
 };
 
 export default async () => {
   await fs.remove(appsDir);
   await fs.mkdirp(appsDir);
-  await templateApp('Asar.app', 'arm64', async (appPath) => {
+
+  // generate mach-o binaries to be leveraged in lipo tests
+  generateMachO();
+
+  await templateApp('Arm64Asar.app', 'arm64', async (appPath) => {
     await fs.copy(
       path.resolve(asarsDir, 'app.asar'),
       path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
     );
   });
 
+  // contains `extra-file.txt`
+  await templateApp('Arm64AsarExtraFile.app', 'arm64', async (appPath) => {
+    await fs.copy(
+      path.resolve(asarsDir, 'app2.asar'),
+      path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
+    );
+  });
+
   await templateApp('X64Asar.app', 'x64', async (appPath) => {
     await fs.copy(
       path.resolve(asarsDir, 'app.asar'),
@@ -41,13 +51,21 @@ export default async () => {
     );
   });
 
-  await templateApp('NoAsar.app', 'arm64', async (appPath) => {
+  await templateApp('Arm64NoAsar.app', 'arm64', async (appPath) => {
     await fs.copy(
       path.resolve(asarsDir, 'app'),
       path.resolve(appPath, 'Contents', 'Resources', 'app'),
     );
   });
 
+  // contains `extra-file.txt`
+  await templateApp('Arm64NoAsarExtraFile.app', 'arm64', async (appPath) => {
+    await fs.copy(
+      path.resolve(asarsDir, 'app2'),
+      path.resolve(appPath, 'Contents', 'Resources', 'app'),
+    );
+  });
+
   await templateApp('X64NoAsar.app', 'x64', async (appPath) => {
     await fs.copy(
       path.resolve(asarsDir, 'app'),

package.json

@@ -12,7 +12,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/electron/universal.git"
+    "url": "git+https://github.com/electron/universal.git"
   },
   "engines": {
     "node": ">=16.4"
@@ -24,8 +24,12 @@
     "README.md"
   ],
   "author": "Samuel Attard",
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "build": "tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && tsc -p tsconfig.entry-asar.json",
+    "build:docs": "npx typedoc",
     "lint": "prettier --check \"{src,entry-asar,test}/**/*.ts\" \"*.ts\"",
     "prettier:write": "prettier --write \"{src,entry-asar,test}/**/*.ts\" \"*.ts\"",
     "prepublishOnly": "npm run build",
@@ -33,7 +37,6 @@
     "prepare": "husky install"
   },
   "devDependencies": {
-    "@continuous-auth/semantic-release-npm": "^4.0.0",
     "@electron/get": "^3.0.0",
     "@types/cross-zip": "^4.0.1",
     "@types/debug": "^4.1.10",
@@ -45,13 +48,14 @@
     "cross-zip": "^4.0.0",
     "husky": "^8.0.3",
     "jest": "^29.7.0",
-    "lint-staged": "^15.0.2",
+    "lint-staged": "^15.2.10",
     "prettier": "^3.0.3",
     "ts-jest": "^29.1.1",
+    "typedoc": "~0.25.13",
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "@electron/asar": "^3.2.7",
+    "@electron/asar": "^3.3.1",
     "@malept/cross-spawn-promise": "^2.0.0",
     "debug": "^4.3.1",
     "dir-compare": "^4.2.0",

src/asar-utils.ts

@@ -84,8 +84,10 @@ export const mergeASARs = async ({
 }: MergeASARsOptions): Promise<void> => {
   d(`merging ${x64AsarPath} and ${arm64AsarPath}`);
 
-  const x64Files = new Set(asar.listPackage(x64AsarPath).map(toRelativePath));
-  const arm64Files = new Set(asar.listPackage(arm64AsarPath).map(toRelativePath));
+  const x64Files = new Set(asar.listPackage(x64AsarPath, { isPack: false }).map(toRelativePath));
+  const arm64Files = new Set(
+    asar.listPackage(arm64AsarPath, { isPack: false }).map(toRelativePath),
+  );
 
   //
   // Build set of unpacked directories and files
@@ -146,14 +148,13 @@ export const mergeASARs = async ({
     const x64Content = asar.extractFile(x64AsarPath, file);
     const arm64Content = asar.extractFile(arm64AsarPath, file);
 
+    // Skip file if the same content
     if (x64Content.compare(arm64Content) === 0) {
       continue;
     }
 
-    if (
-      MACHO_UNIVERSAL_MAGIC.has(x64Content.readUInt32LE(0)) &&
-      MACHO_UNIVERSAL_MAGIC.has(arm64Content.readUInt32LE(0))
-    ) {
+    // Skip universal Mach-O files.
+    if (isUniversalMachO(x64Content)) {
       continue;
     }
 
@@ -221,3 +222,7 @@ export const mergeASARs = async ({
     await Promise.all([fs.remove(x64Dir), fs.remove(arm64Dir)]);
   }
 };
+
+export const isUniversalMachO = (fileContent: Buffer) => {
+  return MACHO_UNIVERSAL_MAGIC.has(fileContent.readUInt32LE(0));
+};

src/file-utils.ts

@@ -1,6 +1,7 @@
 import { spawn, ExitCodeError } from '@malept/cross-spawn-promise';
 import * as fs from 'fs-extra';
 import * as path from 'path';
+import { promises as stream } from 'node:stream';
 
 const MACHO_PREFIX = 'Mach-O ';
 
@@ -45,7 +46,7 @@ export const getAllAppFiles = async (appPath: string): Promise<AppFile[]> => {
           throw e;
         }
       }
-      if (p.includes('app.asar')) {
+      if (p.endsWith('.asar')) {
         fileType = AppFileType.APP_CODE;
       } else if (fileOutput.startsWith(MACHO_PREFIX)) {
         fileType = AppFileType.MACHO;
@@ -71,3 +72,14 @@ export const getAllAppFiles = async (appPath: string): Promise<AppFile[]> => {
 
   return files;
 };
+
+export const readMachOHeader = async (path: string) => {
+  const chunks: Buffer[] = [];
+  // no need to read the entire file, we only need the first 4 bytes of the file to determine the header
+  await stream.pipeline(fs.createReadStream(path, { start: 0, end: 3 }), async function* (source) {
+    for await (const chunk of source) {
+      chunks.push(chunk);
+    }
+  });
+  return Buffer.concat(chunks);
+};

src/index.ts

@@ -1,50 +1,74 @@
-import { spawn } from '@malept/cross-spawn-promise';
 import * as asar from '@electron/asar';
+import { spawn } from '@malept/cross-spawn-promise';
+import * as dircompare from 'dir-compare';
 import * as fs from 'fs-extra';
 import { minimatch } from 'minimatch';
 import * as os from 'os';
 import * as path from 'path';
 import * as plist from 'plist';
-import * as dircompare from 'dir-compare';
 
-import { AppFile, AppFileType, getAllAppFiles } from './file-utils';
-import { AsarMode, detectAsarMode, generateAsarIntegrity, mergeASARs } from './asar-utils';
+import { AsarMode, detectAsarMode, isUniversalMachO, mergeASARs } from './asar-utils';
+import { AppFile, AppFileType, getAllAppFiles, readMachOHeader } from './file-utils';
 import { sha } from './sha';
 import { d } from './debug';
+import { computeIntegrityData } from './integrity';
 
+/**
+ * Options to pass into the {@link makeUniversalApp} function.
+ *
+ * Requires absolute paths for input x64 and arm64 apps and an absolute path to the
+ * output universal app.
+ */
 export type MakeUniversalOpts = {
   /**
-   * Absolute file system path to the x64 version of your application.  E.g. /Foo/bar/MyApp_x64.app
+   * Absolute file system path to the x64 version of your application (e.g. `/Foo/bar/MyApp_x64.app`).
    */
   x64AppPath: string;
   /**
-   * Absolute file system path to the arm64 version of your application.  E.g. /Foo/bar/MyApp_arm64.app
+   * Absolute file system path to the arm64 version of your application (e.g. `/Foo/bar/MyApp_arm64.app`).
    */
   arm64AppPath: string;
   /**
-   * Absolute file system path you want the universal app to be written to.  E.g. /Foo/var/MyApp_universal.app
+   * Absolute file system path you want the universal app to be written to (e.g. `/Foo/var/MyApp_universal.app`).
    *
-   * If this file exists it will be overwritten ONLY if "force" is set to true
+   * If this file exists on disk already, it will be overwritten ONLY if {@link MakeUniversalOpts.force} is set to `true`.
    */
   outAppPath: string;
   /**
-   * Forcefully overwrite any existing files that are in the way of generating the universal application
+   * Forcefully overwrite any existing files that are in the way of generating the universal application.
+   *
+   * @defaultValue `false`
    */
   force?: boolean;
   /**
    * Merge x64 and arm64 ASARs into one.
+   *
+   * @defaultValue `false`
    */
   mergeASARs?: boolean;
   /**
-   * Minimatch pattern of paths that are allowed to be present in one of the ASAR files, but not in the other.
+   * If {@link MakeUniversalOpts.mergeASARs} is enabled, this property provides a
+   * {@link https://github.com/isaacs/minimatch?tab=readme-ov-file#features | minimatch}
+   * pattern of paths that are allowed to be present in one of the ASAR files, but not in the other.
+   *
    */
   singleArchFiles?: string;
   /**
-   * Minimatch pattern of binaries that are expected to be the same x64 binary in both of the ASAR files.
+   * A {@link https://github.com/isaacs/minimatch?tab=readme-ov-file#features | minimatch}
+   * pattern of binaries that are expected to be the same x64 binary in both
+   *
+   * Use this if your application contains binaries that have already been merged into a universal file
+   * using the `lipo` tool.
+   *
+   * @see Apple's {@link https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary | Building a universal macOS binary} documentation
+   *
    */
   x64ArchFiles?: string;
   /**
-   * Minimatch pattern of paths that should not receive an injected ElectronAsarIntegrity value
+   * A {@link https://github.com/isaacs/minimatch?tab=readme-ov-file#features | minimatch} pattern of `Info.plist`
+   * paths that should not receive an injected `ElectronAsarIntegrity` value.
+   *
+   * Use this if your application contains another bundle that's already signed.
    */
   infoPlistsToIgnore?: string;
 };
@@ -133,11 +157,20 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         );
       }
     }
-
+    const knownMergedMachOFiles = new Set();
     for (const machOFile of x64Files.filter((f) => f.type === AppFileType.MACHO)) {
       const first = await fs.realpath(path.resolve(tmpApp, machOFile.relativePath));
       const second = await fs.realpath(path.resolve(opts.arm64AppPath, machOFile.relativePath));
 
+      if (
+        isUniversalMachO(await readMachOHeader(first)) &&
+        isUniversalMachO(await readMachOHeader(second))
+      ) {
+        d(machOFile.relativePath, `is already universal across builds, skipping lipo`);
+        knownMergedMachOFiles.add(machOFile.relativePath);
+        continue;
+      }
+
       const x64Sha = await sha(path.resolve(opts.x64AppPath, machOFile.relativePath));
       const arm64Sha = await sha(path.resolve(opts.arm64AppPath, machOFile.relativePath));
       if (x64Sha === arm64Sha) {
@@ -170,6 +203,7 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         '-output',
         await fs.realpath(path.resolve(tmpApp, machOFile.relativePath)),
       ]);
+      knownMergedMachOFiles.add(machOFile.relativePath);
     }
 
     /**
@@ -185,8 +219,18 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         path.resolve(opts.arm64AppPath, 'Contents', 'Resources', 'app'),
         { compareSize: true, compareContent: true },
       );
+      const differences = comparison.diffSet!.filter((difference) => difference.state !== 'equal');
+      d(`Found ${differences.length} difference(s) between the x64 and arm64 folders`);
+      const nonMergedDifferences = differences.filter(
+        (difference) =>
+          !difference.name1 ||
+          !knownMergedMachOFiles.has(
+            path.join('Contents', 'Resources', 'app', difference.relativePath, difference.name1),
+          ),
+      );
+      d(`After discluding MachO files merged with lipo ${nonMergedDifferences.length} remain.`);
 
-      if (!comparison.same) {
+      if (nonMergedDifferences.length > 0) {
         d('x64 and arm64 app folders are different, creating dynamic entry ASAR');
         await fs.move(
           path.resolve(tmpApp, 'Contents', 'Resources', 'app'),
@@ -217,9 +261,6 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
       }
     }
 
-    const generatedIntegrity: Record<string, { algorithm: 'SHA256'; hash: string }> = {};
-    let didSplitAsar = false;
-
     /**
      * If we have an ASAR we just need to check if the two "app.asar" files have the same hash,
      * if they are, same as above, we can leave one there and call it a day.  If they're different
@@ -237,8 +278,6 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         outputAsarPath: output,
         singleArchFiles: opts.singleArchFiles,
       });
-
-      generatedIntegrity['Resources/app.asar'] = generateAsarIntegrity(output);
     } else if (x64AsarMode === AsarMode.HAS_ASAR) {
       d('checking if the x64 and arm64 asars are identical');
       const x64AsarSha = await sha(path.resolve(tmpApp, 'Contents', 'Resources', 'app.asar'));
@@ -247,7 +286,6 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
       );
 
       if (x64AsarSha !== arm64AsarSha) {
-        didSplitAsar = true;
         d('x64 and arm64 asars are different');
         const x64AsarPath = path.resolve(tmpApp, 'Contents', 'Resources', 'app-x64.asar');
         await fs.move(path.resolve(tmpApp, 'Contents', 'Resources', 'app.asar'), x64AsarPath);
@@ -295,18 +333,13 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         await fs.writeJson(path.resolve(entryAsar, 'package.json'), pj);
         const asarPath = path.resolve(tmpApp, 'Contents', 'Resources', 'app.asar');
         await asar.createPackage(entryAsar, asarPath);
-
-        generatedIntegrity['Resources/app.asar'] = generateAsarIntegrity(asarPath);
-        generatedIntegrity['Resources/app-x64.asar'] = generateAsarIntegrity(x64AsarPath);
-        generatedIntegrity['Resources/app-arm64.asar'] = generateAsarIntegrity(arm64AsarPath);
       } else {
         d('x64 and arm64 asars are the same');
-        generatedIntegrity['Resources/app.asar'] = generateAsarIntegrity(
-          path.resolve(tmpApp, 'Contents', 'Resources', 'app.asar'),
-        );
       }
     }
 
+    const generatedIntegrity = await computeIntegrityData(path.join(tmpApp, 'Contents'));
+
     const plistFiles = x64Files.filter((f) => f.type === AppFileType.INFO_PLIST);
     for (const plistFile of plistFiles) {
       const x64PlistPath = path.resolve(opts.x64AppPath, plistFile.relativePath);

src/integrity.ts

@@ -0,0 +1,51 @@
+import * as fs from 'fs-extra';
+import path from 'path';
+import { AppFileType, getAllAppFiles } from './file-utils';
+import { sha } from './sha';
+import { generateAsarIntegrity } from './asar-utils';
+
+type IntegrityMap = {
+  [filepath: string]: string;
+};
+
+export interface HeaderHash {
+  algorithm: 'SHA256';
+  hash: string;
+}
+
+export interface AsarIntegrity {
+  [key: string]: HeaderHash;
+}
+
+export async function computeIntegrityData(contentsPath: string): Promise<AsarIntegrity> {
+  const root = await fs.realpath(contentsPath);
+
+  const resourcesRelativePath = 'Resources';
+  const resourcesPath = path.resolve(root, resourcesRelativePath);
+
+  const resources = await getAllAppFiles(resourcesPath);
+  const resourceAsars = resources
+    .filter((file) => file.type === AppFileType.APP_CODE)
+    .reduce<IntegrityMap>(
+      (prev, file) => ({
+        ...prev,
+        [path.join(resourcesRelativePath, file.relativePath)]: path.join(
+          resourcesPath,
+          file.relativePath,
+        ),
+      }),
+      {},
+    );
+
+  // sort to produce constant result
+  const allAsars = Object.entries(resourceAsars).sort(([name1], [name2]) =>
+    name1.localeCompare(name2),
+  );
+  const hashes = await Promise.all(allAsars.map(async ([, from]) => generateAsarIntegrity(from)));
+  const asarIntegrity: AsarIntegrity = {};
+  for (let i = 0; i < allAsars.length; i++) {
+    const [asar] = allAsars[i];
+    asarIntegrity[asar] = hashes[i];
+  }
+  return asarIntegrity;
+}

test/asar-utils.spec.ts

@@ -1,6 +1,7 @@
 import * as path from 'path';
 
 import { AsarMode, detectAsarMode, generateAsarIntegrity } from '../src/asar-utils';
+import { describe, expect, it } from '@jest/globals';
 
 const asarsPath = path.resolve(__dirname, 'fixtures', 'asars');
 const appsPath = path.resolve(__dirname, 'fixtures', 'apps');
@@ -8,11 +9,13 @@ const appsPath = path.resolve(__dirname, 'fixtures', 'apps');
 describe('asar-utils', () => {
   describe('detectAsarMode', () => {
     it('should correctly detect an asar enabled app', async () => {
-      expect(await detectAsarMode(path.resolve(appsPath, 'Asar.app'))).toBe(AsarMode.HAS_ASAR);
+      expect(await detectAsarMode(path.resolve(appsPath, 'Arm64Asar.app'))).toBe(AsarMode.HAS_ASAR);
     });
 
     it('should correctly detect an app without an asar', async () => {
-      expect(await detectAsarMode(path.resolve(appsPath, 'NoAsar.app'))).toBe(AsarMode.NO_ASAR);
+      expect(await detectAsarMode(path.resolve(appsPath, 'Arm64NoAsar.app'))).toBe(
+        AsarMode.NO_ASAR,
+      );
     });
   });
 

test/file-utils.spec.ts

@@ -1,6 +1,7 @@
 import * as path from 'path';
 
 import { AppFile, AppFileType, getAllAppFiles } from '../src/file-utils';
+import { beforeAll, describe, expect, it } from '@jest/globals';
 
 const appsPath = path.resolve(__dirname, 'fixtures', 'apps');
 
@@ -10,8 +11,8 @@ describe('file-utils', () => {
     let noAsarFiles: AppFile[];
 
     beforeAll(async () => {
-      asarFiles = await getAllAppFiles(path.resolve(appsPath, 'Asar.app'));
-      noAsarFiles = await getAllAppFiles(path.resolve(appsPath, 'NoAsar.app'));
+      asarFiles = await getAllAppFiles(path.resolve(appsPath, 'Arm64Asar.app'));
+      noAsarFiles = await getAllAppFiles(path.resolve(appsPath, 'Arm64NoAsar.app'));
     });
 
     it('should correctly identify plist files', async () => {

test/fixtures/asars/app2/extra-file.txt

@@ -0,0 +1 @@
+erick was here!

test/fixtures/asars/app2/index.js

@@ -0,0 +1,2 @@
+console.log('I am an app.asar', process.arch);
+process.exit(0);

test/fixtures/asars/app2/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "app",
+  "main": "index.js"
+}

test/fixtures/hello-world.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+int main() {
+    printf("Hello, World!\n");
+    return 0;
+}

test/index.spec.ts

@@ -1,40 +1,419 @@
-import { spawn } from '@malept/cross-spawn-promise';
 import * as fs from 'fs-extra';
 import * as path from 'path';
 
-import { makeUniversalApp } from '../src/index';
+import { makeUniversalApp } from '../dist/cjs/index';
+import {
+  createStagingAppDir,
+  generateNativeApp,
+  templateApp,
+  VERIFY_APP_TIMEOUT,
+  verifyApp,
+} from './util';
+import { createPackage, createPackageWithOptions } from '@electron/asar';
+import { afterEach, describe, expect, it } from '@jest/globals';
 
 const appsPath = path.resolve(__dirname, 'fixtures', 'apps');
+const appsOutPath = path.resolve(__dirname, 'fixtures', 'apps', 'out');
 
-async function ensureUniversal(app: string) {
-  const exe = path.resolve(app, 'Contents', 'MacOS', 'Electron');
-  const result = await spawn(exe);
-  expect(result).toContain('arm64');
-  const result2 = await spawn('arch', ['-x86_64', exe]);
-  expect(result2).toContain('x64');
-}
-
+// See `jest.setup.ts` for app fixture setup process
 describe('makeUniversalApp', () => {
-  it('should correctly merge two identical asars', async () => {
-    const out = path.resolve(appsPath, 'MergedAsar.app');
-    await makeUniversalApp({
-      x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
-      arm64AppPath: path.resolve(appsPath, 'Asar.app'),
-      outAppPath: out,
-    });
-    await ensureUniversal(out);
-    // Only a single asar as they were identical
-    expect(
-      (await fs.readdir(path.resolve(out, 'Contents', 'Resources'))).filter((p) =>
-        p.endsWith('asar'),
-      ),
-    ).toEqual(['app.asar']);
-  }, 60000);
+  afterEach(async () => {
+    await fs.emptyDir(appsOutPath);
+  });
 
-  // TODO: Add tests for
-  // * different asar files
-  // * identical app dirs
-  // * different app dirs
-  // * different app dirs with different macho files
-  // * identical app dirs with universal macho files
+  it('throws an error if asar is only detected in one arch', async () => {
+    const out = path.resolve(appsOutPath, 'Error.app');
+    await expect(
+      makeUniversalApp({
+        x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+        arm64AppPath: path.resolve(appsPath, 'Arm64NoAsar.app'),
+        outAppPath: out,
+      }),
+    ).rejects.toThrow(
+      'Both the x64 and arm64 versions of your application need to have been built with the same asar settings (enabled vs disabled)',
+    );
+  });
+
+  it(
+    'works for lipo binary resources',
+    async () => {
+      const x64AppPath = await generateNativeApp({
+        appNameWithExtension: 'LipoX64.app',
+        arch: 'x64',
+        createAsar: true,
+      });
+      const arm64AppPath = await generateNativeApp({
+        appNameWithExtension: 'LipoArm64.app',
+        arch: 'arm64',
+        createAsar: true,
+      });
+
+      const out = path.resolve(appsOutPath, 'Lipo.app');
+      await makeUniversalApp({ x64AppPath, arm64AppPath, outAppPath: out, mergeASARs: true });
+      await verifyApp(out, true);
+    },
+    VERIFY_APP_TIMEOUT,
+  );
+
+  describe('force', () => {
+    it('throws an error if `out` bundle already exists and `force` is `false`', async () => {
+      const out = path.resolve(appsOutPath, 'Error.app');
+      await fs.mkdirp(out);
+      await expect(
+        makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64Asar.app'),
+          outAppPath: out,
+        }),
+      ).rejects.toThrow(/The out path ".*" already exists and force is not set to true/);
+    });
+
+    it(
+      'packages successfully if `out` bundle already exists and `force` is `true`',
+      async () => {
+        const out = path.resolve(appsOutPath, 'NoError.app');
+        await fs.mkdirp(out);
+        await makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64Asar.app'),
+          outAppPath: out,
+          force: true,
+        });
+        await verifyApp(out);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+  });
+
+  describe('asar mode', () => {
+    it(
+      'should correctly merge two identical asars',
+      async () => {
+        const out = path.resolve(appsOutPath, 'MergedAsar.app');
+        await makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64Asar.app'),
+          outAppPath: out,
+        });
+        await verifyApp(out);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'should create a shim if asars are different between architectures',
+      async () => {
+        const out = path.resolve(appsOutPath, 'ShimmedAsar.app');
+        await makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64AsarExtraFile.app'),
+          outAppPath: out,
+        });
+        await verifyApp(out);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'should merge two different asars when `mergeASARs` is enabled',
+      async () => {
+        const out = path.resolve(appsOutPath, 'MergedAsar.app');
+        await makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64AsarExtraFile.app'),
+          outAppPath: out,
+          mergeASARs: true,
+          singleArchFiles: 'extra-file.txt',
+        });
+        await verifyApp(out);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'throws an error if `mergeASARs` is enabled and `singleArchFiles` is missing a unique file',
+      async () => {
+        const out = path.resolve(appsOutPath, 'Error.app');
+        await expect(
+          makeUniversalApp({
+            x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+            arm64AppPath: path.resolve(appsPath, 'Arm64AsarExtraFile.app'),
+            outAppPath: out,
+            mergeASARs: true,
+            singleArchFiles: 'bad-rule',
+          }),
+        ).rejects.toThrow(/Detected unique file "extra-file\.txt"/);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'should not inject ElectronAsarIntegrity into `infoPlistsToIgnore`',
+      async () => {
+        const arm64AppPath = await templateApp('Arm64-1.app', 'arm64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('Arm64-1');
+          await createPackage(testPath, path.resolve(appPath, 'Contents', 'Resources', 'app.asar'));
+          await templateApp('SubApp-1.app', 'arm64', async (subArm64AppPath) => {
+            await fs.move(
+              subArm64AppPath,
+              path.resolve(appPath, 'Contents', 'Resources', path.basename(subArm64AppPath)),
+            );
+          });
+        });
+        const x64AppPath = await templateApp('X64-1.app', 'x64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('X64-1');
+          await createPackage(testPath, path.resolve(appPath, 'Contents', 'Resources', 'app.asar'));
+          await templateApp('SubApp-1.app', 'x64', async (subArm64AppPath) => {
+            await fs.move(
+              subArm64AppPath,
+              path.resolve(appPath, 'Contents', 'Resources', path.basename(subArm64AppPath)),
+            );
+          });
+        });
+        const outAppPath = path.resolve(appsOutPath, 'UnmodifiedPlist.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+          mergeASARs: true,
+          infoPlistsToIgnore: 'SubApp-1.app/Contents/Info.plist',
+        });
+        await verifyApp(outAppPath);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    // TODO: Investigate if this should even be allowed.
+    // Current logic detects all unpacked files as APP_CODE, which doesn't seem correct since it could also be a macho file requiring lipo
+    // https://github.com/electron/universal/blob/d90d573ccf69a5b14b91aa818c8b97e0e6840399/src/file-utils.ts#L48-L49
+    it.skip(
+      'should shim asars with different unpacked dirs',
+      async () => {
+        const arm64AppPath = await templateApp('UnpackedArm64.app', 'arm64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('UnpackedAppArm64');
+          await createPackageWithOptions(
+            testPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
+            {
+              unpackDir: 'var',
+              unpack: '*.txt',
+            },
+          );
+        });
+
+        const x64AppPath = await templateApp('UnpackedX64.app', 'x64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('UnpackedAppX64');
+          await createPackageWithOptions(
+            testPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
+            {},
+          );
+        });
+
+        const outAppPath = path.resolve(appsOutPath, 'UnpackedDir.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+        });
+        await verifyApp(outAppPath);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'should generate AsarIntegrity for all asars in the application',
+      async () => {
+        const { testPath } = await createStagingAppDir('app-2');
+        const testAsarPath = path.resolve(appsOutPath, 'app-2.asar');
+        await createPackage(testPath, testAsarPath);
+
+        const arm64AppPath = await templateApp('Arm64-2.app', 'arm64', async (appPath) => {
+          await fs.copyFile(
+            testAsarPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
+          );
+          await fs.copyFile(
+            testAsarPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'webapp.asar'),
+          );
+        });
+        const x64AppPath = await templateApp('X64-2.app', 'x64', async (appPath) => {
+          await fs.copyFile(
+            testAsarPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'app.asar'),
+          );
+          await fs.copyFile(
+            testAsarPath,
+            path.resolve(appPath, 'Contents', 'Resources', 'webbapp.asar'),
+          );
+        });
+        const outAppPath = path.resolve(appsOutPath, 'MultipleAsars.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+          mergeASARs: true,
+        });
+        await verifyApp(outAppPath);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+  });
+
+  describe('no asar mode', () => {
+    it(
+      'should correctly merge two identical app folders',
+      async () => {
+        const out = path.resolve(appsOutPath, 'MergedNoAsar.app');
+        await makeUniversalApp({
+          x64AppPath: path.resolve(appsPath, 'X64NoAsar.app'),
+          arm64AppPath: path.resolve(appsPath, 'Arm64NoAsar.app'),
+          outAppPath: out,
+        });
+        await verifyApp(out);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'should shim two different app folders',
+      async () => {
+        const arm64AppPath = await templateApp('ShimArm64.app', 'arm64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('shimArm64', {
+            'i-aint-got-no-rhythm.bin': 'boomshakalaka',
+          });
+          await fs.copy(testPath, path.resolve(appPath, 'Contents', 'Resources', 'app'));
+        });
+
+        const x64AppPath = await templateApp('ShimX64.app', 'x64', async (appPath) => {
+          const { testPath } = await createStagingAppDir('shimX64', {
+            'hello-world.bin': 'Hello World',
+          });
+          await fs.copy(testPath, path.resolve(appPath, 'Contents', 'Resources', 'app'));
+        });
+
+        const outAppPath = path.resolve(appsOutPath, 'ShimNoAsar.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+        });
+        await verifyApp(outAppPath);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'different app dirs with different macho files (shim and lipo)',
+      async () => {
+        const x64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentMachoAppX64-1.app',
+          arch: 'x64',
+          createAsar: false,
+          additionalFiles: {
+            'hello-world.bin': 'Hello World',
+          },
+        });
+        const arm64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentMachoAppArm64-1.app',
+          arch: 'arm64',
+          createAsar: false,
+          additionalFiles: {
+            'i-aint-got-no-rhythm.bin': 'boomshakalaka',
+          },
+        });
+
+        const outAppPath = path.resolve(appsOutPath, 'DifferentMachoApp1.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+        });
+        await verifyApp(outAppPath, true);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      "different app dirs with universal macho files (shim but don't lipo)",
+      async () => {
+        const x64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentButUniversalMachoAppX64-2.app',
+          arch: 'x64',
+          createAsar: false,
+          nativeModuleArch: 'universal',
+          additionalFiles: {
+            'hello-world.bin': 'Hello World',
+          },
+        });
+        const arm64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentButUniversalMachoAppArm64-2.app',
+          arch: 'arm64',
+          createAsar: false,
+          nativeModuleArch: 'universal',
+          additionalFiles: {
+            'i-aint-got-no-rhythm.bin': 'boomshakalaka',
+          },
+        });
+
+        const outAppPath = path.resolve(appsOutPath, 'DifferentButUniversalMachoApp.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath,
+        });
+        await verifyApp(outAppPath, true);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'identical app dirs with different macho files (e.g. do not shim, but still lipo)',
+      async () => {
+        const x64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentMachoAppX64-2.app',
+          arch: 'x64',
+          createAsar: false,
+        });
+        const arm64AppPath = await generateNativeApp({
+          appNameWithExtension: 'DifferentMachoAppArm64-2.app',
+          arch: 'arm64',
+          createAsar: false,
+        });
+
+        const out = path.resolve(appsOutPath, 'DifferentMachoApp2.app');
+        await makeUniversalApp({
+          x64AppPath,
+          arm64AppPath,
+          outAppPath: out,
+        });
+        await verifyApp(out, true);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+
+    it(
+      'identical app dirs with universal macho files (e.g., do not shim, just copy x64 dir)',
+      async () => {
+        const x64AppPath = await generateNativeApp({
+          appNameWithExtension: 'UniversalMachoAppX64.app',
+          arch: 'x64',
+          createAsar: false,
+          nativeModuleArch: 'universal',
+        });
+        const arm64AppPath = await generateNativeApp({
+          appNameWithExtension: 'UniversalMachoAppArm64.app',
+          arch: 'arm64',
+          createAsar: false,
+          nativeModuleArch: 'universal',
+        });
+
+        const out = path.resolve(appsOutPath, 'UniversalMachoApp.app');
+        await makeUniversalApp({ x64AppPath, arm64AppPath, outAppPath: out });
+        await verifyApp(out, true);
+      },
+      VERIFY_APP_TIMEOUT,
+    );
+  });
 });

test/sha.spec.ts

@@ -1,6 +1,7 @@
 import * as path from 'path';
 
 import { sha } from '../src/sha';
+import { describe, expect, it } from '@jest/globals';
 
 describe('sha', () => {
   it('should correctly hash a file', async () => {

test/util.ts

@@ -0,0 +1,251 @@
+import { downloadArtifact } from '@electron/get';
+import { spawn } from '@malept/cross-spawn-promise';
+import * as zip from 'cross-zip';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import plist from 'plist';
+import * as fileUtils from '../dist/cjs/file-utils';
+import { createPackageWithOptions, getRawHeader } from '@electron/asar';
+
+declare const expect: typeof import('@jest/globals').expect;
+
+// We do a LOT of verifications in `verifyApp` 😅
+// exec universal binary -> verify ALL asars -> verify ALL app dirs -> verify ALL asar integrity entries
+// plus some tests create fixtures at runtime
+export const VERIFY_APP_TIMEOUT = 80 * 1000;
+
+export const fixtureDir = path.resolve(__dirname, 'fixtures');
+export const asarsDir = path.resolve(fixtureDir, 'asars');
+export const appsDir = path.resolve(fixtureDir, 'apps');
+export const appsOutPath = path.resolve(appsDir, 'out');
+
+export const verifyApp = async (appPath: string, containsRuntimeGeneratedMacho = false) => {
+  await ensureUniversal(appPath);
+
+  const resourcesDir = path.resolve(appPath, 'Contents', 'Resources');
+  const resourcesDirContents = await fs.readdir(resourcesDir);
+
+  // sort for consistent result
+  const asars = resourcesDirContents.filter((p) => p.endsWith('.asar')).sort();
+  for await (const asar of asars) {
+    // verify header
+    const asarFs = getRawHeader(path.resolve(resourcesDir, asar));
+    expect(
+      removeUnstableProperties(asarFs.header, containsRuntimeGeneratedMacho ? ['hello-world'] : []),
+    ).toMatchSnapshot();
+  }
+
+  // check all app and unpacked dirs (incl. shimmed)
+  const dirsToSnapshot = [
+    'app',
+    'app.asar.unpacked',
+    'app-x64',
+    'app-x64.asar.unpacked',
+    'app-arm64',
+    'app-arm64.asar.unpacked',
+  ];
+  const appDirs = resourcesDirContents
+    .filter((p) => dirsToSnapshot.includes(path.basename(p)))
+    .sort();
+  for await (const dir of appDirs) {
+    await verifyFileTree(path.resolve(resourcesDir, dir));
+  }
+
+  const allFiles = await fileUtils.getAllAppFiles(appPath);
+  const infoPlists = allFiles
+    .filter(
+      (appFile) =>
+        appFile.type === fileUtils.AppFileType.INFO_PLIST &&
+        // These are test app fixtures, no need to snapshot within `TestApp.app/Contents/Frameworks`
+        !appFile.relativePath.includes(path.join('Contents', 'Frameworks')),
+    )
+    .map((af) => af.relativePath)
+    .sort();
+
+  const integrityMap: Record<string, string> = {};
+  const integrity = await Promise.all(
+    infoPlists.map((ip) => extractAsarIntegrity(path.resolve(appPath, ip))),
+  );
+  for (let i = 0; i < integrity.length; i++) {
+    const relativePath = infoPlists[i];
+    const asarIntegrity = integrity[i];
+    // note: `infoPlistsToIgnore` will not have integrity in sub-app plists
+    integrityMap[relativePath] = asarIntegrity
+      ? removeUnstableProperties(asarIntegrity, containsRuntimeGeneratedMacho ? ['hash'] : [])
+      : undefined;
+  }
+  expect(integrityMap).toMatchSnapshot();
+};
+
+const extractAsarIntegrity = async (infoPlist: string) => {
+  const { ElectronAsarIntegrity: integrity, ...otherData } = plist.parse(
+    await fs.readFile(infoPlist, 'utf-8'),
+  ) as any;
+  return integrity;
+};
+
+export const verifyFileTree = async (dirPath: string) => {
+  const dirFiles = await fileUtils.getAllAppFiles(dirPath);
+  const files = dirFiles.map((file) => {
+    const it = path.join(dirPath, file.relativePath);
+    const name = toSystemIndependentPath(file.relativePath);
+    if (it.endsWith('.txt') || it.endsWith('.json')) {
+      return { name, content: fs.readFileSync(it, 'utf-8') };
+    }
+    return name;
+  });
+  expect(files).toMatchSnapshot();
+};
+
+export const ensureUniversal = async (app: string) => {
+  const exe = path.resolve(app, 'Contents', 'MacOS', 'Electron');
+  const result = await spawn(exe);
+  expect(result).toContain('arm64');
+  const result2 = await spawn('arch', ['-x86_64', exe]);
+  expect(result2).toContain('x64');
+};
+
+export const toSystemIndependentPath = (s: string): string => {
+  return path.sep === '/' ? s : s.replace(/\\/g, '/');
+};
+
+export const removeUnstableProperties = (data: any, stripKeys: string[]) => {
+  const removeKeysRecursively: (obj: any, keysToRemove: string[]) => any = (obj, keysToRemove) => {
+    if (!obj || typeof obj !== 'object') {
+      return obj;
+    }
+    // if the value is an array, map over it
+    if (Array.isArray(obj)) {
+      return obj.map((item: any) => removeKeysRecursively(item, keysToRemove));
+    }
+    return Object.keys(obj).reduce<any>((acc, key) => {
+      // if the value of the current key is another object, make a recursive call to remove the key from the nested object
+      if (!keysToRemove.includes(key)) {
+        acc[key] = removeKeysRecursively(obj[key], keysToRemove);
+      } else {
+        acc[key] = '<stripped>';
+      }
+      return acc;
+    }, {});
+  };
+
+  const filteredData = removeKeysRecursively(data, stripKeys);
+  return JSON.parse(
+    JSON.stringify(filteredData, (name, value) => {
+      if (name === 'offset') {
+        return undefined;
+      }
+      return value;
+    }),
+  );
+};
+
+/**
+ * Creates an app directory at runtime for usage:
+ * - `testPath` can be used with `asar.createPackage`. Just set the output `.asar` path to `Test.app/Contents/Resources/<asar_name>.asar`
+ * - `testPath` can be utilized for logic paths involving `AsarMode.NO_ASAR` and copied directly to `Test.app/Contents/Resources`
+ *
+ * Directory structure:
+ * testName
+ * ├── private
+ * │   └── var
+ * │       ├── app
+ * │       │   └── file.txt -> ../file.txt
+ * │       └── file.txt
+ * └── var -> private/var
+ * ├── index.js
+ * ├── package.json
+ */
+export const createStagingAppDir = async (
+  testName: string | undefined,
+  additionalFiles: Record<string, string> = {},
+) => {
+  const outDir = (testName || 'app') + Math.floor(Math.random() * 100); // tests run in parallel, randomize dir suffix to prevent naming collisions
+  const testPath = path.join(appsDir, outDir);
+  await fs.remove(testPath);
+
+  await fs.copy(path.join(asarsDir, 'app'), testPath);
+
+  const privateVarPath = path.join(testPath, 'private', 'var');
+  const varPath = path.join(testPath, 'var');
+
+  await fs.mkdir(privateVarPath, { recursive: true });
+  await fs.symlink(path.relative(testPath, privateVarPath), varPath);
+
+  const files = {
+    'file.txt': 'hello world',
+    ...additionalFiles,
+  };
+  for await (const [filename, fileData] of Object.entries(files)) {
+    const originFilePath = path.join(varPath, filename);
+    await fs.writeFile(originFilePath, fileData);
+  }
+  const appPath = path.join(varPath, 'app');
+  await fs.mkdirp(appPath);
+  await fs.symlink('../file.txt', path.join(appPath, 'file.txt'));
+
+  return {
+    testPath,
+    varPath,
+    appPath,
+  };
+};
+
+export const templateApp = async (
+  name: string,
+  arch: string,
+  modify: (appPath: string) => Promise<void>,
+) => {
+  const electronZip = await downloadArtifact({
+    artifactName: 'electron',
+    version: '27.0.0',
+    platform: 'darwin',
+    arch,
+  });
+  const appPath = path.resolve(appsDir, name);
+  zip.unzipSync(electronZip, appsDir);
+  await fs.rename(path.resolve(appsDir, 'Electron.app'), appPath);
+  await fs.remove(path.resolve(appPath, 'Contents', 'Resources', 'default_app.asar'));
+  await modify(appPath);
+
+  return appPath;
+};
+
+export const generateNativeApp = async (options: {
+  appNameWithExtension: string;
+  arch: string;
+  createAsar: boolean;
+  nativeModuleArch?: string;
+  additionalFiles?: Record<string, string>;
+}) => {
+  const {
+    appNameWithExtension,
+    arch,
+    createAsar,
+    nativeModuleArch = arch,
+    additionalFiles,
+  } = options;
+  const appPath = await templateApp(appNameWithExtension, arch, async (appPath) => {
+    const resources = path.join(appPath, 'Contents', 'Resources');
+    const resourcesApp = path.resolve(resources, 'app');
+    if (!fs.existsSync(resourcesApp)) {
+      await fs.mkdir(resourcesApp);
+    }
+    const { testPath } = await createStagingAppDir(
+      path.basename(appNameWithExtension, '.app'),
+      additionalFiles,
+    );
+    await fs.copy(
+      path.join(appsDir, `hello-world-${nativeModuleArch}`),
+      path.join(testPath, 'hello-world'),
+    );
+    if (createAsar) {
+      await createPackageWithOptions(testPath, path.resolve(resources, 'app.asar'), {
+        unpack: '**/hello-world',
+      });
+    } else {
+      await fs.copy(testPath, resourcesApp);
+    }
+  });
+  return appPath;
+};

typedoc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "excludeInternal": true,
+  "sort": ["source-order"]
+}