@nwutils/packager 0.7.0 → 0.8.0

package/README.md

@@ -13,7 +13,7 @@ Supported output formats, selected via `format`:
 | `rpm`      | Linux    | Planned     |
 | `msix`     | Windows  | Planned     |
 | `nsis`     | Windows  | Implemented |
-| `dmg`      | MacOS    | Planned     |
+| `dmg`      | MacOS    | Implemented |
 
 ## Getting Started
 
@@ -65,7 +65,7 @@ keyring. If the key is protected by a passphrase, set it in the
 ### Self updating AppImages
 
 Set `publish` to where releases are uploaded, and `version` to the app's
-version. This follows electron-builder's approach:
+version.
 
 - an `app-update.yml` describing `publish` is embedded next to the NW.js
   executable inside the AppImage, so the running app knows where to look
@@ -174,14 +174,71 @@ running application to exit instead of asking the user to close it, updates it
 silently, and starts the new version. Because it installs for the current user,
 updating never asks for administrator rights.
 
+### DMG
+
+Build the application with `platform: "osx"` first, then, on a MacOS host:
+
+```js
+const dmgPath = await packager({
+  format: "dmg",
+  appDir: "./out",
+  appName: "Demo",
+  arch: "arm64",
+  outDir: "./dist",
+  signIdentity: "Developer ID Application: ACME (TEAMID)",
+});
+// ./dist/Demo-arm64.dmg
+```
+
+The DMG holds the app next to a link to `/Applications`, so users install it by
+dragging the app onto the link. It is made with `hdiutil`, and the app is signed
+with `codesign` when `signIdentity` is set (`"-"` signs ad-hoc). Both are part
+of MacOS, so DMGs are built on a MacOS host. Notarize the DMG afterwards, eg.
+with `xcrun notarytool submit --wait` and `xcrun stapler staple`, so Gatekeeper
+lets users open it.
+
+### Self updating DMGs
+
+Set `publish` and `version`. Updates don't use the DMG:
+
+- an `app-update.yml` describing `publish` is added to the app's
+  `Contents/Resources`
+- a `<appName>-<arch>-mac.zip` of the app, made with `ditto` so permissions,
+  symbolic links and the signature survive, is written next to the DMG
+- a `latest-mac.yml` update info file (`latest-mac-<arch>.yml` for
+  architectures other than `x64`) describing the zip is written next to it
+
+```js
+await packager({
+  format: "dmg",
+  appDir: "./out",
+  appName: "Demo",
+  arch: "arm64",
+  outDir: "./dist",
+  version: "1.2.0",
+  signIdentity: "Developer ID Application: ACME (TEAMID)",
+  publish: { provider: "github", owner: "nwutils", repo: "demo" },
+});
+// ./dist/Demo-arm64.dmg
+// ./dist/Demo-arm64-mac.zip
+// ./dist/latest-mac-arm64.yml
+```
+
+Upload all three to every release.
+[`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater)'s
+`MacUpdater` downloads the zip, checks it, swaps it in for the running app and
+restarts it. Adding `app-update.yml` changes the app, so sign it here with
+`signIdentity` rather than before packaging. A signed app only accepts updates
+signed by the same team.
+
 ## API Reference
 
 ### `packager({ format, ...options })`
 
-| Name   | Type                                                        | Description                                                                  |
-| ------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| format | `"AppImage" \| "deb" \| "rpm" \| "msix" \| "nsis" \| "dmg"` | Which packager to run. `"AppImage"` and `"nsis"` are implemented today.      |
-| ...    | -                                                           | The remaining options are passed through to the packager for `format` as-is. |
+| Name   | Type                                                        | Description                                                                      |
+| ------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| format | `"AppImage" \| "deb" \| "rpm" \| "msix" \| "nsis" \| "dmg"` | Which packager to run. `"AppImage"`, `"nsis"` and `"dmg"` are implemented today. |
+| ...    | -                                                           | The remaining options are passed through to the packager for `format` as-is.     |
 
 Resolves with the path to the resulting packaged artifact.
 
@@ -230,6 +287,26 @@ Options
 
 Resolves with the path to the resulting installer `.exe` file.
 
+### `dmg(options)`
+
+Options
+
+| Name         | Type               | Description                                                                                                                         |
+| ------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| appDir       | `string`           | Path to a built NW.js MacOS application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "osx"`                      |
+| appName      | `string`           | Name of the application. Must match the `app.name` value used to build `appDir`: the bundle is expected at `<appDir>/<appName>.app` |
+| arch         | `"x64" \| "arm64"` | Architecture `appDir` was built for. Defaults to the host architecture                                                              |
+| outDir       | `string`           | Directory the resulting `<appName>-<arch>.dmg` file is written to. Defaults to the parent directory of `appDir`                     |
+| volumeName   | `string`           | Name of the volume the DMG mounts as. Defaults to `appName`                                                                         |
+| signIdentity | `string`           | Code signing identity to sign the app with, or `"-"` to sign ad-hoc. Not signed by default                                          |
+| version      | `string`           | Version of the application. Required with `publish`                                                                                 |
+| publish      | `PublishOptions`   | Where releases are published. Adds `app-update.yml` and writes `<appName>-<arch>-mac.zip` and `latest-mac[-<arch>].yml` to `outDir` |
+| hdiutilPath  | `string`           | Path to `hdiutil`. Defaults to `hdiutil` on the `PATH`                                                                              |
+| dittoPath    | `string`           | Path to `ditto`. Defaults to `ditto` on the `PATH`                                                                                  |
+| codesignPath | `string`           | Path to `codesign`. Defaults to `codesign` on the `PATH`                                                                            |
+
+Resolves with the path to the resulting `.dmg` file.
+
 ## Contributing
 
 ### External contributor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwutils/packager",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Package NW.js applications for Linux, MacOS and Windows.",
   "keywords": [
     "NW.js",
@@ -43,8 +43,8 @@
     "lint": "eslint . ../../tests/specs/packager ../../tests/fixtures/packager",
     "lint:fix": "eslint . ../../tests/specs/packager ../../tests/fixtures/packager --fix",
     "type": "tsc",
-    "test": "node --test --test-concurrency=1 \"../../tests/specs/packager/appImage.test.js\" \"../../tests/specs/packager/nsis.test.js\" \"../../tests/specs/packager/request.test.js\" \"../../tests/specs/packager/util.test.js\"",
-    "test:real": "node --test --test-concurrency=1 \"../../tests/specs/packager/appImage.real.test.js\" \"../../tests/specs/packager/nsis.real.test.js\""
+    "test": "node --test --test-concurrency=1 \"../../tests/specs/packager/appImage.test.js\" \"../../tests/specs/packager/dmg.test.js\" \"../../tests/specs/packager/nsis.test.js\" \"../../tests/specs/packager/request.test.js\" \"../../tests/specs/packager/util.test.js\"",
+    "test:real": "node --test --test-concurrency=1 \"../../tests/specs/packager/appImage.real.test.js\" \"../../tests/specs/packager/dmg.real.test.js\" \"../../tests/specs/packager/nsis.real.test.js\""
   },
   "dependencies": {},
   "devEngines": {

package/src/dmg.js

@@ -0,0 +1,277 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import util from "./util.js";
+
+/**
+ * @typedef  {object}                       DmgOptions
+ * @property {string}                       appDir             Path to a built NW.js MacOS application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "osx"`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the bundle is expected at `<appDir>/<appName>.app`.
+ * @property {"x64" | "arm64"}              [arch]             Architecture `appDir` was built for. Defaults to the host architecture.
+ * @property {string}                       [outDir]           Directory the resulting `<appName>-<arch>.dmg` file is written to. Defaults to the parent directory of `appDir`.
+ * @property {string}                       [volumeName]       Name of the volume the DMG mounts as. Defaults to `appName`.
+ * @property {string}                       [signIdentity]     Code signing identity, eg. `"Developer ID Application: ACME (TEAMID)"`, or `"-"` to sign ad-hoc. When set, the app is signed with `codesign` before it is put in the DMG. Sign here rather than before packaging when `publish` is set, since adding `app-update.yml` changes the bundle.
+ * @property {string}                       [version]          Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+ * @property {import("./appImage.js").PublishOptions} [publish] Where releases are published. When set, an `app-update.yml` pointing at it is added to the app's `Contents/Resources`, and a `<appName>-<arch>-mac.zip` update archive and a `latest-mac[-<arch>].yml` update info file are written next to the DMG, for `@nwutils/updater` to self update from.
+ * @property {string}                       [hdiutilPath="hdiutil"]   Path to `hdiutil`, which creates the DMG.
+ * @property {string}                       [dittoPath="ditto"]       Path to `ditto`, which creates the update archive.
+ * @property {string}                       [codesignPath="codesign"] Path to `codesign`, which signs the app.
+ */
+
+/**
+ * Package a built NW.js MacOS application as a DMG disk image.
+ *
+ * The DMG holds the app next to a link to `/Applications`, so users install it
+ * by dragging the app onto the link. Updates don't use the DMG: with
+ * `publish` set, a zip of the app is written next to it, which
+ * `@nwutils/updater`'s `MacUpdater` downloads and swaps in for the running
+ * app.
+ *
+ * This composes with `@nwutils/builder`: run it against the `outDir` (and
+ * `app.name`) that `@nwutils/builder` produced for `platform: "osx"`.
+ * `hdiutil`, `ditto` and `codesign` are part of MacOS, so this runs on a MacOS
+ * host.
+ * @async
+ * @function
+ * @param  {DmgOptions}  options
+ * @returns {Promise<string>}  Path to the resulting `.dmg` file.
+ */
+async function dmg({
+  appDir,
+  appName,
+  arch,
+  outDir,
+  volumeName,
+  signIdentity,
+  version,
+  publish,
+  hdiutilPath = "hdiutil",
+  dittoPath = "ditto",
+  codesignPath = "codesign",
+}) {
+  if (typeof appDir !== "string" || appDir === "") {
+    throw new Error(
+      `Expected "options.appDir" to be a non-empty string. Received: ${JSON.stringify(appDir)}`,
+    );
+  }
+
+  if ((await util.fileExists(appDir)) === false) {
+    throw new Error(`"options.appDir" does not exist: ${appDir}`);
+  }
+
+  /* `appName` names the bundle and the files written to `outDir`. */
+  if (
+    typeof appName !== "string" ||
+    appName === "" ||
+    appName.includes("/") ||
+    appName.startsWith(".") ||
+    hasControlCharacter(appName)
+  ) {
+    throw new Error(
+      `Expected "options.appName" to be a non-empty file name without "/" or control characters, not starting with ".". Received: ${JSON.stringify(appName)}`,
+    );
+  }
+
+  const resolvedArch =
+    /** @type {"x64" | "arm64" | undefined} */ (arch) ??
+    /** @type {"x64" | "arm64"} */ (/** @type {unknown} */ (process.arch));
+  if (resolvedArch !== "x64" && resolvedArch !== "arm64") {
+    throw new Error(
+      `Expected "options.arch" to be "x64" or "arm64". Received: ${JSON.stringify(arch ?? process.arch)}`,
+    );
+  }
+
+  const resolvedVolumeName = volumeName ?? appName;
+  if (
+    typeof resolvedVolumeName !== "string" ||
+    resolvedVolumeName === "" ||
+    hasControlCharacter(resolvedVolumeName)
+  ) {
+    throw new Error(
+      `Expected "options.volumeName" to be a non-empty string without control characters. Received: ${JSON.stringify(volumeName)}`,
+    );
+  }
+
+  if (
+    signIdentity !== undefined &&
+    (typeof signIdentity !== "string" || signIdentity === "")
+  ) {
+    throw new Error(
+      `Expected "options.signIdentity" to be a non-empty string. Received: ${JSON.stringify(signIdentity)}`,
+    );
+  }
+
+  if (publish !== undefined) {
+    util.validatePublish(publish);
+    if (typeof version !== "string" || version === "") {
+      throw new Error(
+        `Expected "options.version" to be a non-empty string when "options.publish" is set. Received: ${JSON.stringify(version)}`,
+      );
+    }
+  }
+
+  for (const [key, value] of Object.entries({
+    hdiutilPath,
+    dittoPath,
+    codesignPath,
+  })) {
+    if (typeof value !== "string" || value === "") {
+      throw new Error(
+        `Expected "options.${key}" to be a non-empty string. Received: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  const resolvedAppDir = path.resolve(appDir);
+  const appBundleName = `${appName}.app`;
+  const appBundlePath = path.resolve(resolvedAppDir, appBundleName);
+  if ((await util.fileExists(appBundlePath)) === false) {
+    throw new Error(
+      `Expected the app bundle to exist at ${appBundlePath}. Does "options.appName" match the "app.name" used to build "options.appDir" for "platform: \\"osx\\""?`,
+    );
+  }
+
+  const resolvedOutDir = path.resolve(outDir ?? path.dirname(resolvedAppDir));
+  await fs.promises.mkdir(resolvedOutDir, { recursive: true });
+  const dmgPath = path.resolve(
+    resolvedOutDir,
+    `${appName}-${resolvedArch}.dmg`,
+  );
+
+  const stagingDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "nwutils-packager-dmg-"),
+  );
+
+  try {
+    /* NW.js' frameworks are full of symbolic links, which must stay links for the signature to hold. */
+    const stagedAppPath = path.resolve(stagingDir, appBundleName);
+    await fs.promises.cp(appBundlePath, stagedAppPath, {
+      recursive: true,
+      verbatimSymlinks: true,
+    });
+
+    /*
+     * `Contents/Resources` is where `@nwutils/updater` looks for it.
+     * It's inside the signed bundle, so
+     * signing comes after.
+     */
+    if (publish !== undefined) {
+      await fs.promises.writeFile(
+        path.resolve(stagedAppPath, "Contents", "Resources", "app-update.yml"),
+        util.appUpdateYaml(publish),
+      );
+    }
+
+    if (signIdentity !== undefined) {
+      run(
+        codesignPath,
+        [
+          "--force",
+          "--deep",
+          "--sign",
+          signIdentity,
+          /* Notarization requires the hardened runtime and a secure timestamp, which ad-hoc signatures can't have. */
+          ...(signIdentity === "-"
+            ? []
+            : ["--options", "runtime", "--timestamp"]),
+          stagedAppPath,
+        ],
+        "codesign",
+        "codesignPath",
+      );
+    }
+
+    /* Lets users install by dragging the app onto it. */
+    await fs.promises.symlink(
+      "/Applications",
+      path.resolve(stagingDir, "Applications"),
+    );
+
+    run(
+      hdiutilPath,
+      [
+        "create",
+        "-volname",
+        resolvedVolumeName,
+        "-srcfolder",
+        stagingDir,
+        "-fs",
+        "HFS+",
+        "-format",
+        "UDZO",
+        "-ov",
+        dmgPath,
+      ],
+      "hdiutil",
+      "hdiutilPath",
+    );
+
+    if (publish !== undefined) {
+      /*
+       * `ditto` keeps the permissions, symbolic links and extended attributes
+       * a signed app bundle needs, unlike most zip tools. `--keepParent` puts
+       * `<appName>.app` itself at the archive's root.
+       */
+      const zipPath = path.resolve(
+        resolvedOutDir,
+        `${appName}-${resolvedArch}-mac.zip`,
+      );
+      run(
+        dittoPath,
+        ["-c", "-k", "--sequesterRsrc", "--keepParent", stagedAppPath, zipPath],
+        "ditto",
+        "dittoPath",
+      );
+      await util.writeUpdateInfo({
+        filePath: zipPath,
+        updateInfoPath: path.resolve(
+          resolvedOutDir,
+          util.updateInfoFileName(resolvedArch, "osx"),
+        ),
+        version: /** @type {string} */ (version),
+      });
+    }
+
+    return dmgPath;
+  } finally {
+    await fs.promises.rm(stagingDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function hasControlCharacter(value) {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 0x20 || code === 0x7f;
+  });
+}
+
+/**
+ * Run a MacOS tool, turning a missing tool into an error that says so.
+ * @param {string} toolPath  Path or name of the tool.
+ * @param {string[]} args
+ * @param {string} toolName  eg. `"hdiutil"`.
+ * @param {string} optionName  Option that overrides `toolPath`, eg. `"hdiutilPath"`.
+ * @returns {void}
+ */
+function run(toolPath, args, toolName, optionName) {
+  try {
+    child_process.execFileSync(toolPath, args, { stdio: "inherit" });
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+      throw new Error(
+        `Could not find ${JSON.stringify(toolPath)}. "${toolName}" is part of MacOS, so DMGs are built on a MacOS host. Otherwise pass its path as "options.${optionName}".`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
+export default dmg;

package/src/index.js

@@ -1,13 +1,14 @@
 import appImage from "./appImage.js";
+import dmg from "./dmg.js";
 import nsis from "./nsis.js";
 
 /**
  * Supported packaged output formats.
  *
  * `AppImage`, `deb` and `rpm` package a Linux build. `MSIX` and `NSIS`
- * package a Windows build. `"AppImage"` and `"nsis"` are implemented today -
- * the others are reserved so this option doesn't need to change shape once
- * they land.
+ * package a Windows build. `dmg` packages a MacOS build. `"AppImage"`,
+ * `"nsis"` and `"dmg"` are implemented today - the others are reserved so
+ * this option doesn't need to change shape once they land.
  * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
  */
 
@@ -20,7 +21,7 @@ import nsis from "./nsis.js";
  * Package a built NW.js application.
  * @async
  * @function
- * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage` or `nsis`) expects.
+ * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage`, `nsis` or `dmg`) expects.
  * @returns {Promise<string>}  Path to the resulting packaged artifact.
  */
 async function packager({ format, ...options }) {
@@ -29,12 +30,13 @@ async function packager({ format, ...options }) {
       return appImage(/** @type {any} */ (options));
     case "nsis":
       return nsis(/** @type {any} */ (options));
+    case "dmg":
+      return dmg(/** @type {any} */ (options));
     case "deb":
     case "rpm":
     case "msix":
-    case "dmg":
       throw new Error(
-        `options.format ${JSON.stringify(format)} is not implemented yet. Currently only "AppImage" and "nsis" are supported.`,
+        `options.format ${JSON.stringify(format)} is not implemented yet. Currently only "AppImage", "nsis" and "dmg" are supported.`,
       );
     default:
       throw new Error(

package/src/util.js

@@ -116,15 +116,20 @@ function desktopExecArg(value) {
 
 /**
  * Name of the update info file `@nwutils/updater` downloads for `arch` on
- * `platform`, matching electron-builder: `x64` gets the bare
- * `latest-linux.yml` (Linux) or `latest.yml` (Windows), every other
- * architecture gets an `-<arch>` suffix.
- * @param {string}           arch
- * @param {"linux" | "win"}  [platform="linux"]
+ * `platform`, gets the bare
+ * `latest-linux.yml` (Linux), `latest.yml` (Windows) or `latest-mac.yml`
+ * (MacOS), every other architecture gets an `-<arch>` suffix.
+ * @param {string}                  arch
+ * @param {"linux" | "win" | "osx"} [platform="linux"]
  * @returns {string}
  */
 function updateInfoFileName(arch, platform = "linux") {
-  const base = platform === "win" ? "latest" : "latest-linux";
+  const base =
+    platform === "win"
+      ? "latest"
+      : platform === "osx"
+        ? "latest-mac"
+        : "latest-linux";
   return arch === "x64" ? `${base}.yml` : `${base}-${arch}.yml`;
 }
 
@@ -169,8 +174,7 @@ function stringifyYaml(entries) {
 }
 
 /**
- * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
- * same encoding electron-builder writes into its update info files.
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`.
  * @async
  * @function
  * @param {string} filePath

package/types/dmg.d.ts

@@ -0,0 +1,80 @@
+export default dmg;
+export type DmgOptions = {
+    /**
+     * Path to a built NW.js MacOS application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "osx"`.
+     */
+    appDir: string;
+    /**
+     * Name of the application. Must match the `app.name` value used to build `appDir` - the bundle is expected at `<appDir>/<appName>.app`.
+     */
+    appName: string;
+    /**
+     * Architecture `appDir` was built for. Defaults to the host architecture.
+     */
+    arch?: "x64" | "arm64" | undefined;
+    /**
+     * Directory the resulting `<appName>-<arch>.dmg` file is written to. Defaults to the parent directory of `appDir`.
+     */
+    outDir?: string | undefined;
+    /**
+     * Name of the volume the DMG mounts as. Defaults to `appName`.
+     */
+    volumeName?: string | undefined;
+    /**
+     * Code signing identity, eg. `"Developer ID Application: ACME (TEAMID)"`, or `"-"` to sign ad-hoc. When set, the app is signed with `codesign` before it is put in the DMG. Sign here rather than before packaging when `publish` is set, since adding `app-update.yml` changes the bundle.
+     */
+    signIdentity?: string | undefined;
+    /**
+     * Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+     */
+    version?: string | undefined;
+    /**
+     * Where releases are published. When set, an `app-update.yml` pointing at it is added to the app's `Contents/Resources`, and a `<appName>-<arch>-mac.zip` update archive and a `latest-mac[-<arch>].yml` update info file are written next to the DMG, for `@nwutils/updater` to self update from.
+     */
+    publish?: import("./appImage.js").PublishOptions | undefined;
+    /**
+     * Path to `hdiutil`, which creates the DMG.
+     */
+    hdiutilPath?: string | undefined;
+    /**
+     * Path to `ditto`, which creates the update archive.
+     */
+    dittoPath?: string | undefined;
+    /**
+     * Path to `codesign`, which signs the app.
+     */
+    codesignPath?: string | undefined;
+};
+/**
+ * @typedef  {object}                       DmgOptions
+ * @property {string}                       appDir             Path to a built NW.js MacOS application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "osx"`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the bundle is expected at `<appDir>/<appName>.app`.
+ * @property {"x64" | "arm64"}              [arch]             Architecture `appDir` was built for. Defaults to the host architecture.
+ * @property {string}                       [outDir]           Directory the resulting `<appName>-<arch>.dmg` file is written to. Defaults to the parent directory of `appDir`.
+ * @property {string}                       [volumeName]       Name of the volume the DMG mounts as. Defaults to `appName`.
+ * @property {string}                       [signIdentity]     Code signing identity, eg. `"Developer ID Application: ACME (TEAMID)"`, or `"-"` to sign ad-hoc. When set, the app is signed with `codesign` before it is put in the DMG. Sign here rather than before packaging when `publish` is set, since adding `app-update.yml` changes the bundle.
+ * @property {string}                       [version]          Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+ * @property {import("./appImage.js").PublishOptions} [publish] Where releases are published. When set, an `app-update.yml` pointing at it is added to the app's `Contents/Resources`, and a `<appName>-<arch>-mac.zip` update archive and a `latest-mac[-<arch>].yml` update info file are written next to the DMG, for `@nwutils/updater` to self update from.
+ * @property {string}                       [hdiutilPath="hdiutil"]   Path to `hdiutil`, which creates the DMG.
+ * @property {string}                       [dittoPath="ditto"]       Path to `ditto`, which creates the update archive.
+ * @property {string}                       [codesignPath="codesign"] Path to `codesign`, which signs the app.
+ */
+/**
+ * Package a built NW.js MacOS application as a DMG disk image.
+ *
+ * The DMG holds the app next to a link to `/Applications`, so users install it
+ * by dragging the app onto the link. Updates don't use the DMG: with
+ * `publish` set, a zip of the app is written next to it, which
+ * `@nwutils/updater`'s `MacUpdater` downloads and swaps in for the running
+ * app.
+ *
+ * This composes with `@nwutils/builder`: run it against the `outDir` (and
+ * `app.name`) that `@nwutils/builder` produced for `platform: "osx"`.
+ * `hdiutil`, `ditto` and `codesign` are part of MacOS, so this runs on a MacOS
+ * host.
+ * @async
+ * @function
+ * @param  {DmgOptions}  options
+ * @returns {Promise<string>}  Path to the resulting `.dmg` file.
+ */
+declare function dmg({ appDir, appName, arch, outDir, volumeName, signIdentity, version, publish, hdiutilPath, dittoPath, codesignPath, }: DmgOptions): Promise<string>;

package/types/index.d.ts

@@ -3,9 +3,9 @@ export default packager;
  * Supported packaged output formats.
  *
  * `AppImage`, `deb` and `rpm` package a Linux build. `MSIX` and `NSIS`
- * package a Windows build. `"AppImage"` and `"nsis"` are implemented today -
- * the others are reserved so this option doesn't need to change shape once
- * they land.
+ * package a Windows build. `dmg` packages a MacOS build. `"AppImage"`,
+ * `"nsis"` and `"dmg"` are implemented today - the others are reserved so
+ * this option doesn't need to change shape once they land.
  */
 export type PackageFormat = "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
 /**
@@ -16,9 +16,9 @@ export type PublishOptions = import("./appImage.js").PublishOptions;
  * Supported packaged output formats.
  *
  * `AppImage`, `deb` and `rpm` package a Linux build. `MSIX` and `NSIS`
- * package a Windows build. `"AppImage"` and `"nsis"` are implemented today -
- * the others are reserved so this option doesn't need to change shape once
- * they land.
+ * package a Windows build. `dmg` packages a MacOS build. `"AppImage"`,
+ * `"nsis"` and `"dmg"` are implemented today - the others are reserved so
+ * this option doesn't need to change shape once they land.
  * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
  */
 /**
@@ -29,7 +29,7 @@ export type PublishOptions = import("./appImage.js").PublishOptions;
  * Package a built NW.js application.
  * @async
  * @function
- * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage` or `nsis`) expects.
+ * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage`, `nsis` or `dmg`) expects.
  * @returns {Promise<string>}  Path to the resulting packaged artifact.
  */
 declare function packager({ format, ...options }: {

package/types/util.d.ts

@@ -85,8 +85,7 @@ declare function nsisPath(value: string): string;
  */
 declare function parseDesktopEntry(contents: string): Record<string, string>;
 /**
- * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
- * same encoding electron-builder writes into its update info files.
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`.
  * @async
  * @function
  * @param {string} filePath
@@ -116,14 +115,14 @@ declare function stringifyDesktopEntry(entries: Record<string, string | undefine
 declare function stringifyYaml(entries: Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>): string;
 /**
  * Name of the update info file `@nwutils/updater` downloads for `arch` on
- * `platform`, matching electron-builder: `x64` gets the bare
- * `latest-linux.yml` (Linux) or `latest.yml` (Windows), every other
- * architecture gets an `-<arch>` suffix.
- * @param {string}           arch
- * @param {"linux" | "win"}  [platform="linux"]
+ * `platform`, gets the bare
+ * `latest-linux.yml` (Linux), `latest.yml` (Windows) or `latest-mac.yml`
+ * (MacOS), every other architecture gets an `-<arch>` suffix.
+ * @param {string}                  arch
+ * @param {"linux" | "win" | "osx"} [platform="linux"]
  * @returns {string}
  */
-declare function updateInfoFileName(arch: string, platform?: "linux" | "win"): string;
+declare function updateInfoFileName(arch: string, platform?: "linux" | "win" | "osx"): string;
 /**
  * Throw if `publish` isn't a valid `PublishOptions` object.
  * @param {unknown} publish