Merge branch 'main' into esm-asar-entrypoints

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

.circleci/config.yml

@@ -1,8 +1,8 @@
 version: 2.1
 
 orbs:
-  cfa: continuousauth/npm@2.0.0
-  node: electronjs/node@2.1.0
+  cfa: continuousauth/npm@2.1.0
+  node: electronjs/node@2.3.0
 
 workflows:
   test_and_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@eb760c48894b5702398529cbb8f6e98378e315d0 # v1.3.0
         with:
           field: Opened
           field-value: ${{ github.event.pull_request.created_at || github.event.issue.created_at }}

.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@cfb60706e18bc85e8aec535e3c577abe8f70378e # v5.5.2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:

.gitignore

@@ -1,7 +1,11 @@
 node_modules
 dist
-entry-asar/*.js*
-entry-asar/*.ts
+entry-asar/cjs/*.js*
+entry-asar/cjs/*.d.ts
+entry-asar/esm/*.?js*
+entry-asar/esm/*.d.?ts
 *.app
 test/fixtures/apps
-coverage
+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

@@ -5,9 +5,13 @@
 [![CircleCI](https://circleci.com/gh/electron/universal/tree/main.svg?style=shield)](https://circleci.com/gh/electron/universal)
 [![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

entry-asar/cjs/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": ".",
+  },
+  "include": [
+    ".",
+    "../ambient.d.ts"
+  ],
+  "exclude": []
+}

entry-asar/esm/has-asar.mts

@@ -0,0 +1,28 @@
+import { app } from 'electron';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+if (process.arch === 'arm64') {
+  await setPaths('arm64');
+} else {
+  await setPaths('x64');
+}
+
+async function setPaths(platform: string) {
+  // This should return the full path, ending in something like
+  // Notion.app/Contents/Resources/app.asar
+  const appPath = app.getAppPath();
+  const asarFile = `app-${platform}.asar`;
+
+  // Maybe we'll handle this in Electron one day
+  if (path.basename(appPath) === 'app.asar') {
+    const platformAppPath = path.join(path.dirname(appPath), asarFile);
+
+    // This is an undocumented API. It exists.
+    app.setAppPath(platformAppPath);
+  }
+
+  const require = createRequire(import.meta.url);
+  process._archPath = require.resolve(`../${asarFile}`);
+  await import(process._archPath);
+}

entry-asar/esm/no-asar.mts

@@ -0,0 +1,29 @@
+import { app } from 'electron';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+if (process.arch === 'arm64') {
+  await setPaths('arm64');
+} else {
+  await setPaths('x64');
+}
+
+async function setPaths(platform: string) {
+  // This should return the full path, ending in something like
+  // Notion.app/Contents/Resources/app
+  const appPath = app.getAppPath();
+  const appFolder = `app-${platform}`;
+
+  // Maybe we'll handle this in Electron one day
+  if (path.basename(appPath) === 'app') {
+    const platformAppPath = path.join(path.dirname(appPath), appFolder);
+
+    // This is an undocumented private API. It exists.
+    app.setAppPath(platformAppPath);
+  }
+
+   const require = createRequire(import.meta.url);
+   process._archPath = require.resolve(`../${appFolder}`);
+
+   await import(process._archPath);
+}

entry-asar/esm/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.esm.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "target":"ESNext",
+    "outDir": ".",
+  },
+  "include": [
+    ".",
+    "../ambient.d.ts"
+  ],
+  "exclude": []
+}

jest.setup.ts

@@ -27,13 +27,21 @@ const templateApp = async (
 export default async () => {
   await fs.remove(appsDir);
   await fs.mkdirp(appsDir);
-  await templateApp('Asar.app', 'arm64', async (appPath) => {
+  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 +49,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

@@ -20,12 +20,14 @@
   "files": [
     "dist/*",
     "entry-asar/*",
-    "!entry-asar/**/*.ts",
+    "!entry-asar/**/*.{ts,mts}",
+    "!entry-asar/**/tsconfig.json",
     "README.md"
   ],
   "author": "Samuel Attard",
   "scripts": {
-    "build": "tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && tsc -p tsconfig.entry-asar.json",
+    "build": "tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && tsc -p entry-asar/esm/tsconfig.json && tsc -p entry-asar/cjs/tsconfig.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 +35,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",
@@ -48,6 +49,7 @@
     "lint-staged": "^15.0.2",
     "prettier": "^3.0.3",
     "ts-jest": "^29.1.1",
+    "typedoc": "~0.25.13",
     "typescript": "^5.2.2"
   },
   "dependencies": {

src/index.ts

@@ -12,39 +12,62 @@ import { AsarMode, detectAsarMode, generateAsarIntegrity, mergeASARs } from './a
 import { sha } from './sha';
 import { d } from './debug';
 
+/**
+ * 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,7 +156,7 @@ 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));
@@ -170,6 +193,7 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
         '-output',
         await fs.realpath(path.resolve(tmpApp, machOFile.relativePath)),
       ]);
+      knownMergedMachOFiles.add(machOFile.relativePath);
     }
 
     /**
@@ -185,8 +209,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'),
@@ -199,14 +233,27 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
 
         const entryAsar = path.resolve(tmpDir, 'entry-asar');
         await fs.mkdir(entryAsar);
-        await fs.copy(
-          path.resolve(__dirname, '..', '..', 'entry-asar', 'no-asar.js'),
-          path.resolve(entryAsar, 'index.js'),
-        );
+
         let pj = await fs.readJson(
           path.resolve(opts.x64AppPath, 'Contents', 'Resources', 'app', 'package.json'),
         );
-        pj.main = 'index.js';
+
+        // Load a shim that redirects to the correct folder for the architecture.
+        // This needs to be a different file depending on if the app entrypoint is CommonJS or ESM.
+        if (pj.type === 'module' || pj.main.endsWith('.mjs')) {
+          await fs.copy(
+            path.resolve(__dirname, '..', '..', 'entry-asar', 'esm', 'no-asar.mjs'),
+            path.resolve(entryAsar, 'index.mjs'),
+          );
+          pj.main = 'index.mjs';
+        } else {
+          await fs.copy(
+            path.resolve(__dirname, '..', '..', 'entry-asar', 'cjs', 'no-asar.js'),
+            path.resolve(entryAsar, 'index.js'),
+          );
+          pj.main = 'index.js';
+        }
+
         await fs.writeJson(path.resolve(entryAsar, 'package.json'), pj);
         await asar.createPackage(
           entryAsar,
@@ -279,10 +326,6 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
 
         const entryAsar = path.resolve(tmpDir, 'entry-asar');
         await fs.mkdir(entryAsar);
-        await fs.copy(
-          path.resolve(__dirname, '..', '..', 'entry-asar', 'has-asar.js'),
-          path.resolve(entryAsar, 'index.js'),
-        );
         let pj = JSON.parse(
           (
             await asar.extractFile(
@@ -291,7 +334,23 @@ export const makeUniversalApp = async (opts: MakeUniversalOpts): Promise<void> =
             )
           ).toString('utf8'),
         );
-        pj.main = 'index.js';
+
+        // Load a shim that redirects to the correct `app.asar` for the architecture.
+        // This needs to be a different file depending on if the app entrypoint is CommonJS or ESM.
+        if (pj.type === 'module' || pj.main.endsWith('.mjs')) {
+          await fs.copy(
+            path.resolve(__dirname, '..', '..', 'entry-asar', 'esm', 'has-asar.mjs'),
+            path.resolve(entryAsar, 'index.mjs'),
+          );
+          pj.main = 'index.mjs';
+        } else {
+          await fs.copy(
+            path.resolve(__dirname, '..', '..', 'entry-asar', 'cjs', 'has-asar.js'),
+            path.resolve(entryAsar, 'index.js'),
+          );
+          pj.main = 'index.js';
+        }
+
         await fs.writeJson(path.resolve(entryAsar, 'package.json'), pj);
         const asarPath = path.resolve(tmpApp, 'Contents', 'Resources', 'app.asar');
         await asar.createPackage(entryAsar, asarPath);

test/asar-utils.spec.ts

@@ -8,11 +8,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

@@ -10,8 +10,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/index.spec.ts

@@ -2,9 +2,10 @@ 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';
 
 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');
@@ -14,27 +15,147 @@ async function ensureUniversal(app: string) {
   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,
+  afterEach(async () => {
+    await fs.emptyDir(appsOutPath);
+  });
+
+  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.todo('works for lipo binary resources');
+
+  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/);
     });
-    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);
+
+    it('packages successfully if `out` bundle already exists and `force` is `true`', async () => {
+      const out = path.resolve(appsOutPath, 'Error.app');
+      await fs.mkdirp(out);
+      await makeUniversalApp({
+        x64AppPath: path.resolve(appsPath, 'X64Asar.app'),
+        arm64AppPath: path.resolve(appsPath, 'Arm64Asar.app'),
+        outAppPath: out,
+        force: true,
+      });
+      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);
+  });
+
+  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 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);
+
+    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 ensureUniversal(out);
+      // We have three asars including the arch-agnostic shim
+      expect(
+        (await fs.readdir(path.resolve(out, 'Contents', 'Resources')))
+          .filter((p) => p.endsWith('asar'))
+          .sort(),
+      ).toEqual(['app.asar', 'app-x64.asar', 'app-arm64.asar'].sort());
+    }, 60000);
+
+    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 ensureUniversal(out);
+      // Only a single merged asar
+      expect(
+        (await fs.readdir(path.resolve(out, 'Contents', 'Resources'))).filter((p) =>
+          p.endsWith('asar'),
+        ),
+      ).toEqual(['app.asar']);
+    }, 60000);
+
+    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"/);
+    }, 60000);
+
+    it.todo('should not inject ElectronAsarIntegrity into `infoPlistsToIgnore`');
+  });
+
+  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 ensureUniversal(out);
+      // Only a single app folder as they were identical
+      expect(
+        (await fs.readdir(path.resolve(out, 'Contents', 'Resources'))).filter((p) =>
+          p.startsWith('app'),
+        ),
+      ).toEqual(['app']);
+    }, 60000);
+
+    it.todo('should shim two different app folders');
+  });
 
   // 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
 });

tsconfig.entry-asar.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "entry-asar",
-  },
-  "include": [
-    "entry-asar"
-  ],
-  "exclude": []
-}

tsconfig.json

@@ -17,7 +17,6 @@
     "declaration": true
   },
   "include": [
-    "src",
-    "entry-asar"
-  ]
+    "src"
+  ],
 }

typedoc.json

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