@nwutils/packager 0.6.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
@@ -143,14 +143,102 @@ It needs the NSIS compiler, `makensis`, installed on the host. It runs on
 Linux (`apt install nsis`) and MacOS (`brew install makensis`) too, so a Windows
 installer can be built from any platform. On Windows, `choco install nsis`.
 
+### Self updating NSIS installs
+
+Set `publish`, the same way as for [AppImages](#self-updating-appimages):
+
+- an `app-update.yml` describing `publish` is installed next to
+  `<appName>.exe`, and removed by the uninstaller
+- a `latest.yml` update info file (`latest-<arch>.yml` for architectures other
+  than `x64`) with the version, file name, size and SHA-512 of the installer is
+  written next to it in `outDir`
+
+```js
+await packager({
+  format: "nsis",
+  appDir: "./out",
+  appName: "Demo",
+  version: "1.2.0",
+  outDir: "./dist",
+  publish: { provider: "github", owner: "nwutils", repo: "demo" },
+});
+// ./dist/Demo-x64-Setup.exe
+// ./dist/latest.yml
+```
+
+Upload both the installer and `latest.yml` to every release.
+[`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater)'s
+`NsisUpdater` downloads the new installer, checks it, and runs it with
+`/S /UPDATE`. With `/UPDATE`, the installer waits up to 60 seconds for the
+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.
 
@@ -195,9 +283,30 @@ Options
 | desktopShortcut   | `boolean`                    | If true, create a desktop shortcut. Defaults to `true`                                                                |
 | startMenuShortcut | `boolean`                    | If true, create a Start Menu shortcut. Defaults to `true`                                                             |
 | makensisPath      | `string`                     | Path to the NSIS compiler. Defaults to `makensis` on the `PATH`                                                       |
+| publish           | `PublishOptions`             | Where releases are published. Installs `app-update.yml` and writes `latest[-<arch>].yml` to `outDir`                  |
 
 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.6.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/appImage.js

@@ -141,7 +141,7 @@ async function appImage({
   }
 
   if (publish !== undefined) {
-    validatePublish(publish);
+    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)}`,
@@ -280,15 +280,7 @@ async function appImage({
     if (publish !== undefined) {
       await fs.promises.writeFile(
         path.resolve(appImageDir, "app-update.yml"),
-        util.stringifyYaml(
-          publish.provider === "github"
-            ? {
-                provider: publish.provider,
-                owner: publish.owner,
-                repo: publish.repo,
-              }
-            : { provider: publish.provider, url: publish.url },
-        ),
+        util.appUpdateYaml(publish),
       );
     }
 
@@ -367,18 +359,14 @@ async function appImage({
     }
 
     if (publish !== undefined) {
-      const appImageSha512 = await util.sha512(appImageFilePath);
-      const { size } = await fs.promises.stat(appImageFilePath);
-      await fs.promises.writeFile(
-        path.resolve(resolvedOutDir, util.updateInfoFileName(resolvedArch)),
-        util.stringifyYaml({
-          version: /** @type {string} */ (version),
-          files: [{ url: appImageFileName, sha512: appImageSha512, size }],
-          path: appImageFileName,
-          sha512: appImageSha512,
-          releaseDate: new Date().toISOString(),
-        }),
-      );
+      await util.writeUpdateInfo({
+        filePath: appImageFilePath,
+        updateInfoPath: path.resolve(
+          resolvedOutDir,
+          util.updateInfoFileName(resolvedArch, "linux"),
+        ),
+        version: /** @type {string} */ (version),
+      });
     }
 
     return appImageFilePath;
@@ -387,71 +375,6 @@ async function appImage({
   }
 }
 
-/**
- * Throw if `publish` isn't a valid `PublishOptions` object.
- * @param {unknown} publish
- * @returns {asserts publish is PublishOptions}
- */
-function validatePublish(publish) {
-  if (typeof publish !== "object" || publish === null) {
-    throw new Error(
-      `Expected "options.publish" to be an object. Received: ${JSON.stringify(publish)}`,
-    );
-  }
-
-  const { provider } = /** @type {{provider?: unknown}} */ (publish);
-  /** @type {string[]} */
-  let requiredKeys;
-  if (provider === "github") {
-    requiredKeys = ["owner", "repo"];
-  } else if (provider === "generic") {
-    requiredKeys = ["url"];
-  } else {
-    throw new Error(
-      `Expected "options.publish.provider" to be "github" or "generic". Received: ${JSON.stringify(provider)}`,
-    );
-  }
-
-  for (const key of requiredKeys) {
-    const value = /** @type {Record<string, unknown>} */ (publish)[key];
-    if (typeof value !== "string" || value === "") {
-      throw new Error(
-        `Expected "options.publish.${key}" to be a non-empty string for provider "${provider}". Received: ${JSON.stringify(value)}`,
-      );
-    }
-  }
-
-  if (provider === "github") {
-    /*
-     * The characters GitHub allows in owner and repository names. Anything
-     * else - eg. "|", the update information's field separator - is rejected.
-     */
-    for (const key of requiredKeys) {
-      const value = /** @type {Record<string, string>} */ (publish)[key];
-      if (/^[A-Za-z0-9._-]+$/.test(value) === false) {
-        throw new Error(
-          `Expected "options.publish.${key}" to be a GitHub ${key} name (letters, digits, ".", "-" and "_"). Received: ${JSON.stringify(value)}`,
-        );
-      }
-    }
-  }
-
-  if (provider === "generic") {
-    const { url } = /** @type {GenericPublishOptions} */ (publish);
-    let protocol;
-    try {
-      protocol = new URL(url).protocol;
-    } catch {
-      protocol = undefined;
-    }
-    if (protocol !== "https:" && protocol !== "http:") {
-      throw new Error(
-        `Expected "options.publish.url" to be an http(s) URL. Received: ${JSON.stringify(url)}`,
-      );
-    }
-  }
-}
-
 /**
  * Build the AppImage update information string for `publish`, in the format
  * zsync based AppImage updaters understand.

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/nsis.js

@@ -21,6 +21,7 @@ import util from "./util.js";
  * @property {boolean}                      [desktopShortcut=true]   If true, create a desktop shortcut.
  * @property {boolean}                      [startMenuShortcut=true] If true, create a Start Menu shortcut.
  * @property {string}                       [makensisPath="makensis"] Path to the NSIS compiler. Defaults to `makensis` on the `PATH`.
+ * @property {import("./appImage.js").PublishOptions} [publish] Where releases are published. When set, an `app-update.yml` pointing at it is installed next to the executable and a `latest[-<arch>].yml` update info file is written next to the installer, for `@nwutils/updater` to self update from.
  */
 
 /**
@@ -46,6 +47,12 @@ const ARCH_CHECK_KV = {
   arm64: [["${IsNativeARM64}"]],
 };
 
+/**
+ * How long an update waits for the running application to exit.
+ * @type {number}
+ */
+const UPDATE_WAIT_SECONDS = 60;
+
 /**
  * Package a built NW.js Windows application as an NSIS installer.
  *
@@ -55,6 +62,10 @@ const ARCH_CHECK_KV = {
  * installing a new version first uninstalls the previous one. Both wait for
  * the application to be closed before touching its files.
  *
+ * Run with `/S /UPDATE`, as `@nwutils/updater` does, the installer instead
+ * waits for the running application to exit, updates it silently and starts
+ * the new version.
+ *
  * This composes with `@nwutils/builder`: run it against the `outDir` (and
  * `app.name`) that `@nwutils/builder` produced for `platform: "win"`.
  * `makensis` runs on Linux and macOS too, so the installer can be built on
@@ -78,6 +89,7 @@ async function nsis({
   desktopShortcut = true,
   startMenuShortcut = true,
   makensisPath = "makensis",
+  publish,
 }) {
   if (typeof appDir !== "string" || appDir === "") {
     throw new Error(
@@ -169,6 +181,10 @@ async function nsis({
     );
   }
 
+  if (publish !== undefined) {
+    util.validatePublish(publish);
+  }
+
   const resolvedIconPath =
     icon === undefined
       ? undefined
@@ -193,28 +209,45 @@ async function nsis({
     `${appName}-${resolvedArch}-Setup.exe`,
   );
 
-  const script = nsisScript({
-    appDir: resolvedAppDir,
-    appFiles: await listAppFiles(resolvedAppDir),
-    appName,
-    appId: resolvedAppId,
-    version,
-    fileVersion,
-    arch: resolvedArch,
-    installerPath,
-    iconPath: resolvedIconPath,
-    licensePath: resolvedLicensePath,
-    publisher,
-    copyright,
-    desktopShortcut,
-    startMenuShortcut,
-  });
+  const appFiles = await listAppFiles(resolvedAppDir);
 
   const scriptDir = await fs.promises.mkdtemp(
     path.join(os.tmpdir(), "nwutils-packager-nsis-"),
   );
 
   try {
+    /*
+     * Installed next to the NW.js executable, ie. at
+     * `path.dirname(process.execPath)` at runtime, which is where
+     * `@nwutils/updater` looks for it.
+     */
+    let appUpdateYamlPath;
+    if (publish !== undefined) {
+      appUpdateYamlPath = path.resolve(scriptDir, "app-update.yml");
+      await fs.promises.writeFile(
+        appUpdateYamlPath,
+        util.appUpdateYaml(publish),
+      );
+    }
+
+    const script = nsisScript({
+      appDir: resolvedAppDir,
+      appFiles,
+      appName,
+      appId: resolvedAppId,
+      version,
+      fileVersion,
+      arch: resolvedArch,
+      installerPath,
+      iconPath: resolvedIconPath,
+      licensePath: resolvedLicensePath,
+      publisher,
+      copyright,
+      desktopShortcut,
+      startMenuShortcut,
+      appUpdateYamlPath,
+    });
+
     const scriptPath = path.resolve(scriptDir, "installer.nsi");
     await fs.promises.writeFile(scriptPath, script, "utf-8");
 
@@ -234,6 +267,17 @@ async function nsis({
       throw error;
     }
 
+    if (publish !== undefined) {
+      await util.writeUpdateInfo({
+        filePath: installerPath,
+        updateInfoPath: path.resolve(
+          resolvedOutDir,
+          util.updateInfoFileName(resolvedArch, "win"),
+        ),
+        version,
+      });
+    }
+
     return installerPath;
   } finally {
     await fs.promises.rm(scriptDir, { recursive: true, force: true });
@@ -325,6 +369,7 @@ async function listAppFiles(appDir) {
  * @param  {string}                    options.copyright
  * @param  {boolean}                   options.desktopShortcut
  * @param  {boolean}                   options.startMenuShortcut
+ * @param  {string}                    [options.appUpdateYamlPath] Absolute path to an `app-update.yml` file to install next to the executable.
  * @returns {string}
  */
 function nsisScript({
@@ -342,6 +387,7 @@ function nsisScript({
   copyright,
   desktopShortcut,
   startMenuShortcut,
+  appUpdateYamlPath,
 }) {
   const e = util.nsisEscape;
   const p = util.nsisPath;
@@ -363,6 +409,10 @@ function nsisScript({
     '!include "LogicLib.nsh"',
     '!include "x64.nsh"',
     '!include "WinVer.nsh"',
+    '!include "FileFunc.nsh"',
+    "",
+    /* "1" when run with `/UPDATE`, ie. by `@nwutils/updater`. */
+    "Var IsUpdate",
     "",
     `Name "${e(appName)}"`,
     `OutFile "${p(installerPath)}"`,
@@ -405,7 +455,17 @@ function nsisScript({
   if (publisher !== undefined) {
     lines.push(`VIAddVersionKey "CompanyName" "${e(publisher)}"`);
   }
-  lines.push("", "Function .onInit", "  SetShellVarContext current");
+  lines.push(
+    "",
+    "Function .onInit",
+    "  SetShellVarContext current",
+    "  ${GetParameters} $R0",
+    "  ClearErrors",
+    '  ${GetOptions} $R0 "/UPDATE" $R1',
+    "  ${IfNot} ${Errors}",
+    '    StrCpy $IsUpdate "1"',
+    "  ${EndIf}",
+  );
   if (archChecks.length > 0) {
     /* Passing branches are left empty: only the final `${Else}` does anything. */
     lines.push(
@@ -471,11 +531,11 @@ function nsisScript({
     }
   }
 
-  lines.push(
-    '  SetOutPath "$INSTDIR"',
-    '  WriteUninstaller "$INSTDIR\\Uninstall.exe"',
-    "",
-  );
+  lines.push('  SetOutPath "$INSTDIR"');
+  if (appUpdateYamlPath !== undefined) {
+    lines.push(`  File "/oname=app-update.yml" "${p(appUpdateYamlPath)}"`);
+  }
+  lines.push('  WriteUninstaller "$INSTDIR\\Uninstall.exe"', "");
   if (startMenuShortcut) {
     lines.push(`  CreateShortcut "$SMPROGRAMS\\${e(appName)}.lnk" ${exe}`);
   }
@@ -500,6 +560,11 @@ function nsisScript({
     );
   }
   lines.push(
+    "",
+    /* An update runs silently, so the finish page's "Run" checkbox never shows. */
+    '  ${If} $IsUpdate == "1"',
+    `    Exec '${exe}'`,
+    "  ${EndIf}",
     "SectionEnd",
     "",
     "Function un.onInit",
@@ -516,6 +581,9 @@ function nsisScript({
   for (const dir of [...appFiles.dirs].reverse()) {
     lines.push(`  RMDir ${installed(dir)}`);
   }
+  if (appUpdateYamlPath !== undefined) {
+    lines.push('  Delete "$INSTDIR\\app-update.yml"');
+  }
   lines.push(
     '  Delete "$INSTDIR\\Uninstall.exe"',
     '  RMDir "$INSTDIR"',
@@ -534,7 +602,12 @@ function nsisScript({
  * the user to close it, so its files can be replaced or deleted. Windows
  * refuses to open a running executable for writing, which is how a running
  * copy is detected. Cancelling - which silent mode does straight away -
- * aborts the installer or uninstaller. Uses `$2`.
+ * aborts the installer or uninstaller.
+ *
+ * During an update (`$IsUpdate` is "1") nobody is there to answer the prompt:
+ * `@nwutils/updater` starts the installer and then quits the application, so
+ * it waits for up to `UPDATE_WAIT_SECONDS` instead, then aborts. Uses `$2`
+ * and `$3`.
  * @param  {string}  exePath  Quoted NSIS string with the executable's path, eg. `"$INSTDIR\Demo.exe"`.
  * @param  {string}  appName  Application name, shown in the prompt.
  * @param  {string}  indent   Indentation of the generated lines.
@@ -542,6 +615,7 @@ function nsisScript({
  */
 function waitForAppToClose(exePath, appName, indent) {
   return [
+    "StrCpy $3 0",
     "${Do}",
     `  \${IfNot} \${FileExists} ${exePath}`,
     "    ${Break}",
@@ -552,6 +626,14 @@ function waitForAppToClose(exePath, appName, indent) {
     "    FileClose $2",
     "    ${Break}",
     "  ${EndIf}",
+    '  ${If} $IsUpdate == "1"',
+    "    IntOp $3 $3 + 1",
+    `    \${If} $3 > ${UPDATE_WAIT_SECONDS * 2}`,
+    "      Abort",
+    "    ${EndIf}",
+    "    Sleep 500",
+    "    ${Continue}",
+    "  ${EndIf}",
     `  \${If} \${Cmd} \`MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "Close ${util.nsisEscape(appName)}, then select Retry." /SD IDCANCEL IDCANCEL\``,
     "    Abort",
     "  ${EndIf}",

package/src/util.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
 
 /**
  * Map nw-builder's architecture identifiers to the identifiers used in
@@ -114,14 +115,22 @@ function desktopExecArg(value) {
 }
 
 /**
- * Name of the update info file `@nwutils/updater` downloads to find the
- * latest release, following electron-builder's naming: `x64` gets the bare
- * `latest-linux.yml`, every other architecture gets an `-<arch>` suffix.
- * @param {"ia32" | "x64" | "arm64"} arch
+ * Name of the update info file `@nwutils/updater` downloads for `arch` on
+ * `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) {
-  return arch === "x64" ? "latest-linux.yml" : `latest-linux-${arch}.yml`;
+function updateInfoFileName(arch, platform = "linux") {
+  const base =
+    platform === "win"
+      ? "latest"
+      : platform === "osx"
+        ? "latest-mac"
+        : "latest-linux";
+  return arch === "x64" ? `${base}.yml` : `${base}-${arch}.yml`;
 }
 
 /**
@@ -165,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
@@ -269,8 +277,117 @@ function windowsVersion(version) {
   return parts.join(".");
 }
 
+/**
+ * Throw if `publish` isn't a valid `PublishOptions` object.
+ * @param {unknown} publish
+ * @returns {void}
+ */
+function validatePublish(publish) {
+  if (typeof publish !== "object" || publish === null) {
+    throw new Error(
+      `Expected "options.publish" to be an object. Received: ${JSON.stringify(publish)}`,
+    );
+  }
+
+  const { provider } = /** @type {{provider?: unknown}} */ (publish);
+  /** @type {string[]} */
+  let requiredKeys;
+  if (provider === "github") {
+    requiredKeys = ["owner", "repo"];
+  } else if (provider === "generic") {
+    requiredKeys = ["url"];
+  } else {
+    throw new Error(
+      `Expected "options.publish.provider" to be "github" or "generic". Received: ${JSON.stringify(provider)}`,
+    );
+  }
+
+  for (const key of requiredKeys) {
+    const value = /** @type {Record<string, unknown>} */ (publish)[key];
+    if (typeof value !== "string" || value === "") {
+      throw new Error(
+        `Expected "options.publish.${key}" to be a non-empty string for provider "${provider}". Received: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  if (provider === "github") {
+    /*
+     * The characters GitHub allows in owner and repository names. Anything
+     * else - eg. "|", the update information's field separator - is rejected.
+     */
+    for (const key of requiredKeys) {
+      const value = /** @type {Record<string, string>} */ (publish)[key];
+      if (/^[A-Za-z0-9._-]+$/.test(value) === false) {
+        throw new Error(
+          `Expected "options.publish.${key}" to be a GitHub ${key} name (letters, digits, ".", "-" and "_"). Received: ${JSON.stringify(value)}`,
+        );
+      }
+    }
+  }
+
+  if (provider === "generic") {
+    const { url } =
+      /** @type {import("./appImage.js").GenericPublishOptions} */ (publish);
+    let protocol;
+    try {
+      protocol = new URL(url).protocol;
+    } catch {
+      protocol = undefined;
+    }
+    if (protocol !== "https:" && protocol !== "http:") {
+      throw new Error(
+        `Expected "options.publish.url" to be an http(s) URL. Received: ${JSON.stringify(url)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Contents of the `app-update.yml` file `@nwutils/updater` reads to find out
+ * where releases are published. It is shipped next to the NW.js executable.
+ * @param {import("./appImage.js").PublishOptions} publish
+ * @returns {string}
+ */
+function appUpdateYaml(publish) {
+  return stringifyYaml(
+    publish.provider === "github"
+      ? { provider: publish.provider, owner: publish.owner, repo: publish.repo }
+      : { provider: publish.provider, url: publish.url },
+  );
+}
+
+/**
+ * Write the update info file `@nwutils/updater` compares the running version
+ * against, describing the packaged artifact at `filePath`. It must be uploaded
+ * to every release next to the artifact.
+ * @async
+ * @function
+ * @param  {object}  options
+ * @param  {string}  options.filePath        Path to the packaged artifact, eg. the AppImage or installer.
+ * @param  {string}  options.updateInfoPath  Path the update info file is written to.
+ * @param  {string}  options.version         Version of the application.
+ * @returns {Promise<void>}
+ */
+async function writeUpdateInfo({ filePath, updateInfoPath, version }) {
+  const fileName = path.basename(filePath);
+  const sha512Digest = await sha512(filePath);
+  const { size } = await fs.promises.stat(filePath);
+  await fs.promises.writeFile(
+    updateInfoPath,
+    stringifyYaml({
+      version,
+      files: [{ url: fileName, sha512: sha512Digest, size }],
+      path: fileName,
+      sha512: sha512Digest,
+      releaseDate: new Date().toISOString(),
+    }),
+  );
+}
+
 export default {
   APPIMAGE_ARCH_KV,
+  appUpdateYaml,
   desktopExecArg,
   fileExists,
   isWindowsFileName,
@@ -282,5 +399,7 @@ export default {
   stringifyDesktopEntry,
   stringifyYaml,
   updateInfoFileName,
+  validatePublish,
   windowsVersion,
+  writeUpdateInfo,
 };

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/nsis.d.ts

@@ -52,6 +52,10 @@ export type NsisOptions = {
      * Path to the NSIS compiler. Defaults to `makensis` on the `PATH`.
      */
     makensisPath?: string | undefined;
+    /**
+     * Where releases are published. When set, an `app-update.yml` pointing at it is installed next to the executable and a `latest[-<arch>].yml` update info file is written next to the installer, for `@nwutils/updater` to self update from.
+     */
+    publish?: import("./appImage.js").PublishOptions | undefined;
 };
 /**
  * The files and directories of a built application, relative to its root.
@@ -79,6 +83,10 @@ export type AppFiles = {
  * installing a new version first uninstalls the previous one. Both wait for
  * the application to be closed before touching its files.
  *
+ * Run with `/S /UPDATE`, as `@nwutils/updater` does, the installer instead
+ * waits for the running application to exit, updates it silently and starts
+ * the new version.
+ *
  * This composes with `@nwutils/builder`: run it against the `outDir` (and
  * `app.name`) that `@nwutils/builder` produced for `platform: "win"`.
  * `makensis` runs on Linux and macOS too, so the installer can be built on
@@ -88,7 +96,7 @@ export type AppFiles = {
  * @param  {NsisOptions}  options
  * @returns {Promise<string>}  Path to the resulting installer `.exe` file.
  */
-declare function nsis({ appDir, appName, version, arch, outDir, icon, appId, publisher, copyright, license, desktopShortcut, startMenuShortcut, makensisPath, }: NsisOptions): Promise<string>;
+declare function nsis({ appDir, appName, version, arch, outDir, icon, appId, publisher, copyright, license, desktopShortcut, startMenuShortcut, makensisPath, publish, }: NsisOptions): Promise<string>;
 /**
  * List the files and directories under `appDir`. Symbolic links are followed,
  * since NSIS copies what they point at.
@@ -120,9 +128,10 @@ export function listAppFiles(appDir: string): Promise<AppFiles>;
  * @param  {string}                    options.copyright
  * @param  {boolean}                   options.desktopShortcut
  * @param  {boolean}                   options.startMenuShortcut
+ * @param  {string}                    [options.appUpdateYamlPath] Absolute path to an `app-update.yml` file to install next to the executable.
  * @returns {string}
  */
-export function nsisScript({ appDir, appFiles, appName, appId, version, fileVersion, arch, installerPath, iconPath, licensePath, publisher, copyright, desktopShortcut, startMenuShortcut, }: {
+export function nsisScript({ appDir, appFiles, appName, appId, version, fileVersion, arch, installerPath, iconPath, licensePath, publisher, copyright, desktopShortcut, startMenuShortcut, appUpdateYamlPath, }: {
     appDir: string;
     appFiles: AppFiles;
     appName: string;
@@ -137,4 +146,5 @@ export function nsisScript({ appDir, appFiles, appName, appId, version, fileVers
     copyright: string;
     desktopShortcut: boolean;
     startMenuShortcut: boolean;
+    appUpdateYamlPath?: string | undefined;
 }): string;

package/types/util.d.ts

@@ -1,5 +1,6 @@
 declare namespace _default {
     export { APPIMAGE_ARCH_KV };
+    export { appUpdateYaml };
     export { desktopExecArg };
     export { fileExists };
     export { isWindowsFileName };
@@ -11,7 +12,9 @@ declare namespace _default {
     export { stringifyDesktopEntry };
     export { stringifyYaml };
     export { updateInfoFileName };
+    export { validatePublish };
     export { windowsVersion };
+    export { writeUpdateInfo };
 }
 export default _default;
 /**
@@ -20,6 +23,13 @@ export default _default;
  * @type {Record<"ia32" | "x64" | "arm64", string>}
  */
 declare const APPIMAGE_ARCH_KV: Record<"ia32" | "x64" | "arm64", string>;
+/**
+ * Contents of the `app-update.yml` file `@nwutils/updater` reads to find out
+ * where releases are published. It is shipped next to the NW.js executable.
+ * @param {import("./appImage.js").PublishOptions} publish
+ * @returns {string}
+ */
+declare function appUpdateYaml(publish: import("./appImage.js").PublishOptions): string;
 /**
  * Quote `value` as a single argument of a desktop entry's `Exec` key, per the
  * Desktop Entry Specification: `%` is doubled so it isn't read as a field
@@ -75,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
@@ -105,13 +114,21 @@ 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 to find the
- * latest release, following electron-builder's naming: `x64` gets the bare
- * `latest-linux.yml`, every other architecture gets an `-<arch>` suffix.
- * @param {"ia32" | "x64" | "arm64"} arch
+ * Name of the update info file `@nwutils/updater` downloads for `arch` on
+ * `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: "ia32" | "x64" | "arm64"): string;
+declare function updateInfoFileName(arch: string, platform?: "linux" | "win" | "osx"): string;
+/**
+ * Throw if `publish` isn't a valid `PublishOptions` object.
+ * @param {unknown} publish
+ * @returns {void}
+ */
+declare function validatePublish(publish: unknown): void;
 /**
  * Convert a version such as `"1.2.3"` or `"1.2.3-beta.1"` into the
  * `X.X.X.X` form Windows version resources (and NSIS' `VIProductVersion`)
@@ -121,3 +138,20 @@ declare function updateInfoFileName(arch: "ia32" | "x64" | "arm64"): string;
  * @returns {string}
  */
 declare function windowsVersion(version: string): string;
+/**
+ * Write the update info file `@nwutils/updater` compares the running version
+ * against, describing the packaged artifact at `filePath`. It must be uploaded
+ * to every release next to the artifact.
+ * @async
+ * @function
+ * @param  {object}  options
+ * @param  {string}  options.filePath        Path to the packaged artifact, eg. the AppImage or installer.
+ * @param  {string}  options.updateInfoPath  Path the update info file is written to.
+ * @param  {string}  options.version         Version of the application.
+ * @returns {Promise<void>}
+ */
+declare function writeUpdateInfo({ filePath, updateInfoPath, version }: {
+    filePath: string;
+    updateInfoPath: string;
+    version: string;
+}): Promise<void>;