@nwutils/packager 0.5.0 → 0.7.0

package/README.md

@@ -12,7 +12,7 @@ Supported output formats, selected via `format`:
 | `deb`      | Linux    | Planned     |
 | `rpm`      | Linux    | Planned     |
 | `msix`     | Windows  | Planned     |
-| `nsis`     | Windows  | Planned     |
+| `nsis`     | Windows  | Implemented |
 | `dmg`      | MacOS    | Planned     |
 
 ## Getting Started
@@ -106,14 +106,82 @@ managers. `true` derives it from `publish`
 `zsyncmake` (usually packaged as `zsync`) installed on the host, and the
 `.zsync` file must be uploaded alongside the AppImage.
 
+### NSIS installer
+
+Build the application with `platform: "win"` first, then:
+
+```js
+const installerPath = await packager({
+  format: "nsis",
+  appDir: "./out",
+  appName: "Demo",
+  version: "1.2.0",
+  outDir: "./dist",
+  icon: "./icon.ico",
+  publisher: "ACME",
+  license: "./LICENSE.txt",
+});
+// ./dist/Demo-x64-Setup.exe
+```
+
+The installer walks the user through a wizard and installs for the current
+user only, into `%LOCALAPPDATA%\Programs\<appName>`, so it never asks for
+administrator rights. It adds Start Menu and desktop shortcuts, and registers
+an uninstaller in Windows' installed apps list. The uninstaller removes exactly
+the files that were installed. Installing a new version first uninstalls the
+previous one, matched by `appId`, and stops if that fails. If the application
+is running, the installer and uninstaller ask the user to close it first;
+in silent mode (`/S`) they exit with an error instead.
+
+The installer refuses to run on Windows machines that can't run `arch`: x64
+builds need x64 Windows, or ARM64 Windows 11, which emulates x64.
+
+Run the installer with `/S` to install silently, and `/D=<dir>` (last, unquoted)
+to choose the install directory.
+
+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.
+
 ## API Reference
 
 ### `packager({ format, ...options })`
 
-| Name   | Type                                               | Description                                                                  |
-| ------ | -------------------------------------------------- | ---------------------------------------------------------------------------- |
-| format | `"AppImage" \| "deb" \| "rpm" \| "MSIX" \| "NSIS"` | Which packager to run. Only `"AppImage"` is 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"` and `"nsis"` 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.
 
@@ -139,6 +207,29 @@ Options
 
 Resolves with the path to the resulting `.AppImage` file.
 
+### `nsis(options)`
+
+Options
+
+| Name              | Type                         | Description                                                                                                           |
+| ----------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| appDir            | `string`                     | Path to a built NW.js Windows application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "win"`      |
+| appName           | `string`                     | Name of the application. Must match the `app.name` value used to build `appDir`. Must be a valid Windows file name    |
+| version           | `string`                     | Version of the application, eg. `"1.2.0"`. Required                                                                   |
+| arch              | `"ia32" \| "x64" \| "arm64"` | Architecture `appDir` was built for. Defaults to the host architecture                                                |
+| outDir            | `string`                     | Directory the resulting `<appName>-<arch>-Setup.exe` file is written to. Defaults to the parent directory of `appDir` |
+| icon              | `string`                     | Path to a `.ico` icon for the installer and uninstaller. Defaults to NSIS' own icon                                   |
+| appId             | `string`                     | Name of the registry key the installation is recorded under. Defaults to `appName`. Keep it the same across releases  |
+| publisher         | `string`                     | Publisher shown in Windows' installed apps list                                                                       |
+| copyright         | `string`                     | Copyright notice written into the installer's version information                                                     |
+| license           | `string`                     | Path to a `.txt` or `.rtf` license file the user has to accept                                                        |
+| 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.
+
 ## Contributing
 
 ### External contributor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwutils/packager",
-  "version": "0.5.0",
+  "version": "0.7.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/request.test.js\" \"../../tests/specs/packager/util.test.js\"",
-    "test:real": "node --test \"../../tests/specs/packager/appImage.real.test.js\""
+    "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\""
   },
   "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/index.js

@@ -1,12 +1,13 @@
 import appImage from "./appImage.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. Only `"AppImage"` is implemented today - the
- * others are reserved so this option doesn't need to change shape once they
- * land.
+ * 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.
  * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
  */
 
@@ -19,20 +20,21 @@ import appImage from "./appImage.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`) expects.
+ * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage` or `nsis`) expects.
  * @returns {Promise<string>}  Path to the resulting packaged artifact.
  */
 async function packager({ format, ...options }) {
   switch (format) {
     case "AppImage":
       return appImage(/** @type {any} */ (options));
+    case "nsis":
+      return nsis(/** @type {any} */ (options));
     case "deb":
     case "rpm":
     case "msix":
-    case "nsis":
     case "dmg":
       throw new Error(
-        `options.format ${JSON.stringify(format)} is not implemented yet. Currently only "AppImage" is supported.`,
+        `options.format ${JSON.stringify(format)} is not implemented yet. Currently only "AppImage" and "nsis" are supported.`,
       );
     default:
       throw new Error(