@nwutils/packager 0.5.0 → 0.6.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,51 @@ 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`.
+
 ## 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 +176,28 @@ 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`                                                       |
+
+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.6.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/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(

package/src/nsis.js

@@ -0,0 +1,563 @@
+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}                       NsisOptions
+ * @property {string}                       appDir             Path to a built NW.js Windows application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "win"`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable is expected at `<appDir>/<appName>.exe`. Must be a valid Windows file name.
+ * @property {string}                       version            Version of the application, eg. `"1.2.0"`. Shown in Windows' installed apps list, and converted to `X.X.X.X` for the installer's own version resource.
+ * @property {"ia32" | "x64" | "arm64"}     [arch]             Architecture `appDir` was built for. Defaults to the host architecture. The installer refuses to run on Windows machines that can't run that architecture.
+ * @property {string}                       [outDir]           Directory the resulting `<appName>-<arch>-Setup.exe` file is written to. Defaults to the parent directory of `appDir`.
+ * @property {string}                       [icon]             Path to a `.ico` icon for the installer and uninstaller. Defaults to NSIS' own icon.
+ * @property {string}                       [appId]            Name of the registry key the installation is recorded under. Defaults to `appName`. Keep it the same across releases, so installing a new version replaces the previous one.
+ * @property {string}                       [publisher]        Publisher shown in Windows' installed apps list.
+ * @property {string}                       [copyright]        Copyright notice written into the installer's version information.
+ * @property {string}                       [license]          Path to a `.txt` or `.rtf` license file. When set, the installer shows it on a page the user has to accept.
+ * @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`.
+ */
+
+/**
+ * The files and directories of a built application, relative to its root.
+ * @typedef  {object}   AppFiles
+ * @property {string[]} files  Relative file paths, using the host's path separator.
+ * @property {string[]} dirs   Relative directory paths, parents before children.
+ * @property {number}   size   Total size of `files` in bytes.
+ */
+
+/**
+ * Map nw-builder's architecture identifiers to the `x64.nsh` and `WinVer.nsh`
+ * checks for whether the Windows machine running the installer can run that
+ * architecture. Each inner list is one way to pass, and all of its checks
+ * must pass. x64 builds run natively on x64 and, emulated, on ARM64 - but
+ * only from Windows 11, as ARM64 Windows 10 only emulates ia32. Every Windows
+ * machine runs ia32 builds.
+ * @type {Record<"ia32" | "x64" | "arm64", string[][]>}
+ */
+const ARCH_CHECK_KV = {
+  ia32: [],
+  x64: [["${IsNativeAMD64}"], ["${IsNativeARM64}", "${AtLeastWin11}"]],
+  arm64: [["${IsNativeARM64}"]],
+};
+
+/**
+ * Package a built NW.js Windows application as an NSIS installer.
+ *
+ * The installer installs for the current user only, into
+ * `%LOCALAPPDATA%\Programs\<appName>`, so it never asks for administrator
+ * rights. It registers an uninstaller in Windows' installed apps list, and
+ * installing a new version first uninstalls the previous one. Both wait for
+ * the application to be closed before touching its files.
+ *
+ * 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
+ * any host.
+ * @async
+ * @function
+ * @param  {NsisOptions}  options
+ * @returns {Promise<string>}  Path to the resulting installer `.exe` file.
+ */
+async function nsis({
+  appDir,
+  appName,
+  version,
+  arch,
+  outDir,
+  icon,
+  appId,
+  publisher,
+  copyright = "",
+  license,
+  desktopShortcut = true,
+  startMenuShortcut = true,
+  makensisPath = "makensis",
+}) {
+  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 files inside `appDir`, `outDir` and the install
+   * directory, and is written into the installer script.
+   */
+  if (
+    typeof appName !== "string" ||
+    util.isWindowsFileName(appName) === false
+  ) {
+    throw new Error(
+      `Expected "options.appName" to be a valid Windows file name. Received: ${JSON.stringify(appName)}`,
+    );
+  }
+
+  if (typeof version !== "string" || version === "") {
+    throw new Error(
+      `Expected "options.version" to be a non-empty string. Received: ${JSON.stringify(version)}`,
+    );
+  }
+  const fileVersion = util.windowsVersion(version);
+
+  const resolvedArch =
+    /** @type {"ia32" | "x64" | "arm64" | undefined} */ (arch) ??
+    /** @type {"ia32" | "x64" | "arm64"} */ (
+      /** @type {unknown} */ (process.arch)
+    );
+  /* `Object.hasOwn` so inherited keys such as "constructor" aren't mistaken for architectures. */
+  if (Object.hasOwn(ARCH_CHECK_KV, resolvedArch) === false) {
+    throw new Error(
+      `Expected "options.arch" to be "ia32", "x64" or "arm64". Received: ${JSON.stringify(arch)}`,
+    );
+  }
+
+  const resolvedAppId = appId ?? appName;
+  /* The installation is recorded under a registry key named after `appId`, and `\` separates registry keys. */
+  if (
+    typeof resolvedAppId !== "string" ||
+    resolvedAppId === "" ||
+    resolvedAppId.includes("\\") ||
+    [...resolvedAppId].some((character) => {
+      const code = character.charCodeAt(0);
+      return code < 0x20 || code === 0x7f;
+    })
+  ) {
+    throw new Error(
+      `Expected "options.appId" to be a non-empty string without "\\" or control characters. Received: ${JSON.stringify(appId)}`,
+    );
+  }
+
+  if (
+    publisher !== undefined &&
+    (typeof publisher !== "string" || publisher === "")
+  ) {
+    throw new Error(
+      `Expected "options.publisher" to be a non-empty string. Received: ${JSON.stringify(publisher)}`,
+    );
+  }
+
+  if (typeof copyright !== "string") {
+    throw new Error(
+      `Expected "options.copyright" to be a string. Received: ${JSON.stringify(copyright)}`,
+    );
+  }
+
+  for (const [key, value] of Object.entries({
+    desktopShortcut,
+    startMenuShortcut,
+  })) {
+    if (typeof value !== "boolean") {
+      throw new Error(
+        `Expected "options.${key}" to be a boolean. Received: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  if (typeof makensisPath !== "string" || makensisPath === "") {
+    throw new Error(
+      `Expected "options.makensisPath" to be a non-empty string. Received: ${JSON.stringify(makensisPath)}`,
+    );
+  }
+
+  const resolvedIconPath =
+    icon === undefined
+      ? undefined
+      : await resolveInputFile("icon", icon, [".ico"]);
+  const resolvedLicensePath =
+    license === undefined
+      ? undefined
+      : await resolveInputFile("license", license, [".txt", ".rtf"]);
+
+  const resolvedAppDir = path.resolve(appDir);
+  const executablePath = path.resolve(resolvedAppDir, `${appName}.exe`);
+  if ((await util.fileExists(executablePath)) === false) {
+    throw new Error(
+      `Expected the NW.js executable to exist at ${executablePath}. Does "options.appName" match the "app.name" used to build "options.appDir" for "platform: \\"win\\""?`,
+    );
+  }
+
+  const resolvedOutDir = path.resolve(outDir ?? path.dirname(resolvedAppDir));
+  await fs.promises.mkdir(resolvedOutDir, { recursive: true });
+  const installerPath = path.resolve(
+    resolvedOutDir,
+    `${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 scriptDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "nwutils-packager-nsis-"),
+  );
+
+  try {
+    const scriptPath = path.resolve(scriptDir, "installer.nsi");
+    await fs.promises.writeFile(scriptPath, script, "utf-8");
+
+    try {
+      child_process.execFileSync(
+        makensisPath,
+        ["-INPUTCHARSET", "UTF8", "-V2", scriptPath],
+        { stdio: "inherit" },
+      );
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+        throw new Error(
+          `Could not find the NSIS compiler at ${JSON.stringify(makensisPath)}. Install NSIS (eg. "apt install nsis", "brew install makensis" or "choco install nsis"), or pass its path as "options.makensisPath".`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+
+    return installerPath;
+  } finally {
+    await fs.promises.rm(scriptDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Resolve an input file option, and throw unless it exists and has one of
+ * `extensions`.
+ * @async
+ * @function
+ * @param  {string}   key         Option name, for error messages.
+ * @param  {unknown}  value       Option value.
+ * @param  {string[]} extensions  Accepted lowercase extensions, eg. `[".ico"]`.
+ * @returns {Promise<string>}  Absolute path to the file.
+ */
+async function resolveInputFile(key, value, extensions) {
+  if (typeof value !== "string" || value === "") {
+    throw new Error(
+      `Expected "options.${key}" to be a non-empty string. Received: ${JSON.stringify(value)}`,
+    );
+  }
+  const resolvedPath = path.resolve(value);
+  if (extensions.includes(path.extname(resolvedPath).toLowerCase()) === false) {
+    throw new Error(
+      `Expected "options.${key}" to be a ${extensions.join(" or ")} file. Received: ${resolvedPath}`,
+    );
+  }
+  if ((await util.fileExists(resolvedPath)) === false) {
+    throw new Error(`"options.${key}" does not exist: ${resolvedPath}`);
+  }
+  return resolvedPath;
+}
+
+/**
+ * List the files and directories under `appDir`. Symbolic links are followed,
+ * since NSIS copies what they point at.
+ * @async
+ * @function
+ * @param  {string}  appDir  Absolute path to the built application.
+ * @returns {Promise<AppFiles>}
+ */
+async function listAppFiles(appDir) {
+  /** @type {AppFiles} */
+  const appFiles = { files: [], dirs: [], size: 0 };
+
+  /**
+   * @param {string} relativeDir
+   * @returns {Promise<void>}
+   */
+  async function walk(relativeDir) {
+    const entries = await fs.promises.readdir(path.join(appDir, relativeDir));
+    for (const entry of entries.sort()) {
+      const relativePath = path.join(relativeDir, entry);
+      const stats = await fs.promises.stat(path.join(appDir, relativePath));
+      if (stats.isDirectory()) {
+        appFiles.dirs.push(relativePath);
+        await walk(relativePath);
+      } else {
+        appFiles.files.push(relativePath);
+        appFiles.size += stats.size;
+      }
+    }
+  }
+
+  await walk("");
+  return appFiles;
+}
+
+/**
+ * Generate the NSIS script for an installer.
+ *
+ * Every file is listed explicitly rather than copied with `File /r`, so the
+ * uninstaller deletes exactly the files that were installed. The user can
+ * choose any install directory - including one such as `C:\` that holds
+ * other files - so the uninstaller never deletes directories recursively.
+ * @param  {object}                    options
+ * @param  {string}                    options.appDir             Absolute path to the built application.
+ * @param  {AppFiles}                  options.appFiles           Files and directories under `appDir`.
+ * @param  {string}                    options.appName
+ * @param  {string}                    options.appId
+ * @param  {string}                    options.version
+ * @param  {string}                    options.fileVersion        `version` in `X.X.X.X` form.
+ * @param  {"ia32" | "x64" | "arm64"}  options.arch
+ * @param  {string}                    options.installerPath      Absolute path the installer is written to.
+ * @param  {string}                    [options.iconPath]         Absolute path to a `.ico` file.
+ * @param  {string}                    [options.licensePath]      Absolute path to a `.txt` or `.rtf` file.
+ * @param  {string}                    [options.publisher]
+ * @param  {string}                    options.copyright
+ * @param  {boolean}                   options.desktopShortcut
+ * @param  {boolean}                   options.startMenuShortcut
+ * @returns {string}
+ */
+function nsisScript({
+  appDir,
+  appFiles,
+  appName,
+  appId,
+  version,
+  fileVersion,
+  arch,
+  installerPath,
+  iconPath,
+  licensePath,
+  publisher,
+  copyright,
+  desktopShortcut,
+  startMenuShortcut,
+}) {
+  const e = util.nsisEscape;
+  const p = util.nsisPath;
+  /* Paths inside the install directory always use `\`, whichever host builds the installer. */
+  const installed = (/** @type {string} */ relativePath) =>
+    `"$INSTDIR\\${e(relativePath.split(path.sep).join("\\"))}"`;
+  const uninstallKey = `"Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\${e(appId)}"`;
+  const exe = installed(`${appName}.exe`);
+  const archChecks = ARCH_CHECK_KV[arch];
+
+  /** @type {string[]} */
+  const lines = [
+    "Unicode true",
+    "ManifestDPIAware true",
+    "RequestExecutionLevel user",
+    "SetCompressor /SOLID lzma",
+    "",
+    '!include "MUI2.nsh"',
+    '!include "LogicLib.nsh"',
+    '!include "x64.nsh"',
+    '!include "WinVer.nsh"',
+    "",
+    `Name "${e(appName)}"`,
+    `OutFile "${p(installerPath)}"`,
+    `InstallDir "$LOCALAPPDATA\\Programs\\${e(appName)}"`,
+    `InstallDirRegKey HKCU ${uninstallKey} "InstallLocation"`,
+    "",
+  ];
+
+  if (iconPath !== undefined) {
+    lines.push(
+      `!define MUI_ICON "${p(iconPath)}"`,
+      `!define MUI_UNICON "${p(iconPath)}"`,
+    );
+  }
+  lines.push(
+    "!define MUI_ABORTWARNING",
+    `!define MUI_FINISHPAGE_RUN ${exe}`,
+    "",
+    "!insertmacro MUI_PAGE_WELCOME",
+  );
+  if (licensePath !== undefined) {
+    lines.push(`!insertmacro MUI_PAGE_LICENSE "${p(licensePath)}"`);
+  }
+  lines.push(
+    "!insertmacro MUI_PAGE_DIRECTORY",
+    "!insertmacro MUI_PAGE_INSTFILES",
+    "!insertmacro MUI_PAGE_FINISH",
+    "!insertmacro MUI_UNPAGE_CONFIRM",
+    "!insertmacro MUI_UNPAGE_INSTFILES",
+    '!insertmacro MUI_LANGUAGE "English"',
+    "",
+    `VIProductVersion "${fileVersion}"`,
+    `VIFileVersion "${fileVersion}"`,
+    `VIAddVersionKey "ProductName" "${e(appName)}"`,
+    `VIAddVersionKey "ProductVersion" "${e(version)}"`,
+    `VIAddVersionKey "FileVersion" "${e(version)}"`,
+    `VIAddVersionKey "FileDescription" "${e(appName)} Setup"`,
+    `VIAddVersionKey "LegalCopyright" "${e(copyright)}"`,
+  );
+  if (publisher !== undefined) {
+    lines.push(`VIAddVersionKey "CompanyName" "${e(publisher)}"`);
+  }
+  lines.push("", "Function .onInit", "  SetShellVarContext current");
+  if (archChecks.length > 0) {
+    /* Passing branches are left empty: only the final `${Else}` does anything. */
+    lines.push(
+      ...archChecks.flatMap((checks, index) =>
+        checks.map(
+          (check, checkIndex) =>
+            `  \${${checkIndex > 0 ? "AndIf" : index === 0 ? "If" : "ElseIf"}} ${check}`,
+        ),
+      ),
+      "  ${Else}",
+      `    MessageBox MB_ICONSTOP "This installer is for ${arch} Windows, which this computer can't run." /SD IDOK`,
+      "    Abort",
+      "  ${EndIf}",
+    );
+  }
+  lines.push(
+    "FunctionEnd",
+    "",
+    'Section "Install"',
+    `  ReadRegStr $0 HKCU ${uninstallKey} "InstallLocation"`,
+    '  ${If} $0 != ""',
+    ...waitForAppToClose(`"$0\\${e(appName)}.exe"`, appName, "    "),
+    "  ${EndIf}",
+    ...waitForAppToClose(exe, appName, "  "),
+    /*
+     * Uninstall the previous version first, so files it had that this
+     * version doesn't are removed. `_?=` runs its uninstaller in place and
+     * waits for it, which leaves the uninstaller itself behind.
+     */
+    '  ${If} $0 != ""',
+    '  ${AndIf} ${FileExists} "$0\\Uninstall.exe"',
+    "    ClearErrors",
+    `    ExecWait '"$0\\Uninstall.exe" /S _?=$0' $1`,
+    "    ${If} ${Errors}",
+    "    ${OrIf} $1 != 0",
+    `      MessageBox MB_ICONSTOP "The previous version of ${e(appName)} couldn't be uninstalled." /SD IDOK`,
+    "      Abort",
+    "    ${EndIf}",
+    '    Delete "$0\\Uninstall.exe"',
+    '    RMDir "$0"',
+    "  ${EndIf}",
+    "",
+    '  SetOutPath "$INSTDIR"',
+  );
+
+  /* Group files by directory: `File` writes into the current `SetOutPath`. */
+  /** @type {Map<string, string[]>} */
+  const filesByDir = new Map([["", []]]);
+  for (const dir of appFiles.dirs) {
+    filesByDir.set(dir, []);
+  }
+  for (const file of appFiles.files) {
+    /** @type {string[]} */ (
+      filesByDir.get(path.dirname(file).replace(/^\.$/, ""))
+    ).push(file);
+  }
+  for (const [dir, files] of filesByDir) {
+    if (dir !== "") {
+      lines.push(`  SetOutPath ${installed(dir)}`);
+    }
+    for (const file of files) {
+      lines.push(`  File "${p(path.join(appDir, file))}"`);
+    }
+  }
+
+  lines.push(
+    '  SetOutPath "$INSTDIR"',
+    '  WriteUninstaller "$INSTDIR\\Uninstall.exe"',
+    "",
+  );
+  if (startMenuShortcut) {
+    lines.push(`  CreateShortcut "$SMPROGRAMS\\${e(appName)}.lnk" ${exe}`);
+  }
+  if (desktopShortcut) {
+    lines.push(`  CreateShortcut "$DESKTOP\\${e(appName)}.lnk" ${exe}`);
+  }
+  lines.push(
+    "",
+    `  WriteRegStr HKCU ${uninstallKey} "DisplayName" "${e(appName)}"`,
+    `  WriteRegStr HKCU ${uninstallKey} "DisplayVersion" "${e(version)}"`,
+    `  WriteRegStr HKCU ${uninstallKey} "DisplayIcon" ${exe}`,
+    `  WriteRegStr HKCU ${uninstallKey} "InstallLocation" "$INSTDIR"`,
+    `  WriteRegStr HKCU ${uninstallKey} "UninstallString" '"$INSTDIR\\Uninstall.exe"'`,
+    `  WriteRegStr HKCU ${uninstallKey} "QuietUninstallString" '"$INSTDIR\\Uninstall.exe" /S'`,
+    `  WriteRegDWORD HKCU ${uninstallKey} "EstimatedSize" ${Math.ceil(appFiles.size / 1024)}`,
+    `  WriteRegDWORD HKCU ${uninstallKey} "NoModify" 1`,
+    `  WriteRegDWORD HKCU ${uninstallKey} "NoRepair" 1`,
+  );
+  if (publisher !== undefined) {
+    lines.push(
+      `  WriteRegStr HKCU ${uninstallKey} "Publisher" "${e(publisher)}"`,
+    );
+  }
+  lines.push(
+    "SectionEnd",
+    "",
+    "Function un.onInit",
+    "  SetShellVarContext current",
+    "FunctionEnd",
+    "",
+    'Section "Uninstall"',
+    ...waitForAppToClose(exe, appName, "  "),
+  );
+  for (const file of appFiles.files) {
+    lines.push(`  Delete ${installed(file)}`);
+  }
+  /* Children before parents, and `RMDir` without `/r` only removes empty directories. */
+  for (const dir of [...appFiles.dirs].reverse()) {
+    lines.push(`  RMDir ${installed(dir)}`);
+  }
+  lines.push(
+    '  Delete "$INSTDIR\\Uninstall.exe"',
+    '  RMDir "$INSTDIR"',
+    `  Delete "$SMPROGRAMS\\${e(appName)}.lnk"`,
+    `  Delete "$DESKTOP\\${e(appName)}.lnk"`,
+    `  DeleteRegKey HKCU ${uninstallKey}`,
+    "SectionEnd",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate NSIS lines that wait until the application isn't running, asking
+ * 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`.
+ * @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.
+ * @returns {string[]}
+ */
+function waitForAppToClose(exePath, appName, indent) {
+  return [
+    "${Do}",
+    `  \${IfNot} \${FileExists} ${exePath}`,
+    "    ${Break}",
+    "  ${EndIf}",
+    "  ClearErrors",
+    `  FileOpen $2 ${exePath} a`,
+    "  ${IfNot} ${Errors}",
+    "    FileClose $2",
+    "    ${Break}",
+    "  ${EndIf}",
+    `  \${If} \${Cmd} \`MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "Close ${util.nsisEscape(appName)}, then select Retry." /SD IDCANCEL IDCANCEL\``,
+    "    Abort",
+    "  ${EndIf}",
+    "${Loop}",
+  ].map((line) => `${indent}${line}`);
+}
+
+export default nsis;
+export { listAppFiles, nsisScript };

package/src/util.js

@@ -180,14 +180,107 @@ async function sha512(filePath) {
   return hash.digest("base64");
 }
 
+/**
+ * Escape `value` for use inside a double quoted NSIS string. NSIS expands `$`
+ * variables and `$\` escapes there, so `$` is doubled and `"` is escaped.
+ * Line breaks are rejected rather than escaped: a raw one would end the
+ * command and let the value inject further script lines. The result is not
+ * quoted, so it can be joined with NSIS variables, eg. `"$INSTDIR\<value>"`.
+ * @param {string} value
+ * @returns {string}
+ */
+function nsisEscape(value) {
+  if (/[\r\n]/.test(value)) {
+    throw new Error(
+      `NSIS strings must not contain line breaks. Received: ${JSON.stringify(value)}`,
+    );
+  }
+  /* In a replacement string `$$` is a literal `$`, so "$$$$" writes "$$". */
+  return value.replaceAll("$", "$$$$").replaceAll('"', '$\\"');
+}
+
+/**
+ * Check a path on the host for use inside a double quoted NSIS string that
+ * `makensis` reads at compile time, eg. a `File` source or `OutFile`. Unlike
+ * runtime strings, those keep `$` literally, so nothing is escaped. Instead,
+ * the sequences `makensis` would still interpret are rejected: `${define}`
+ * expansions and `$\` escapes, and `"` - an escaped `$\"` doesn't survive
+ * being passed through a `!define`, as the icon and license paths are.
+ * @param {string} value
+ * @returns {string}  `value`, unchanged.
+ */
+function nsisPath(value) {
+  if (/[\r\n"]/.test(value) || value.includes("${") || value.includes("$\\")) {
+    throw new Error(
+      `Paths passed to NSIS must not contain line breaks, '"', "\${" or "$\\". Received: ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Names Windows reserves for devices, with or without an extension.
+ * @type {RegExp}
+ */
+const WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+
+/**
+ * Check that `value` can be used as a single Windows file name: no path
+ * separators, characters Windows forbids in file names, control characters,
+ * trailing dots or spaces, or reserved device names.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isWindowsFileName(value) {
+  const hasControlCharacter = [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 0x20 || code === 0x7f;
+  });
+  return (
+    value !== "" &&
+    /[<>:"/\\|?*]/.test(value) === false &&
+    hasControlCharacter === false &&
+    /[. ]$/.test(value) === false &&
+    WINDOWS_RESERVED_NAME.test(value) === false
+  );
+}
+
+/**
+ * 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`)
+ * require. Up to four leading numeric parts are kept, missing ones are
+ * filled with `0`, and any prerelease or build suffix is dropped.
+ * @param {string} version
+ * @returns {string}
+ */
+function windowsVersion(version) {
+  const match = version.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?/);
+  if (match === null) {
+    throw new Error(
+      `Expected a version starting with a number, eg. "1.2.3". Received: ${JSON.stringify(version)}`,
+    );
+  }
+  const parts = match.slice(1).map((part) => Number(part ?? 0));
+  if (parts.some((part) => part > 65535)) {
+    throw new Error(
+      `Expected each part of the version to be at most 65535. Received: ${JSON.stringify(version)}`,
+    );
+  }
+  return parts.join(".");
+}
+
 export default {
   APPIMAGE_ARCH_KV,
   desktopExecArg,
   fileExists,
+  isWindowsFileName,
+  nsisEscape,
+  nsisPath,
   parseDesktopEntry,
   sha512,
   shellQuote,
   stringifyDesktopEntry,
   stringifyYaml,
   updateInfoFileName,
+  windowsVersion,
 };

package/types/appImage.d.ts

@@ -1,3 +1,4 @@
+export default appImage;
 export type AppImageOptions = {
     /**
      * Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
@@ -10,48 +11,53 @@ export type AppImageOptions = {
     /**
      * Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
      */
-    icon?: string;
+    icon?: string | undefined;
     /**
      * Target architecture. Defaults to the host architecture. `appimagetool` runs as a native binary, so this must match the host unless the host has emulation (eg. QEMU/binfmt) configured for the target architecture.
      */
-    arch?: "ia32" | "x64" | "arm64";
+    arch?: "ia32" | "x64" | "arm64" | undefined;
     /**
      * Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
      */
-    outDir?: string;
+    outDir?: string | undefined;
     /**
      * Directory used to cache the downloaded `appimagetool` binary.
      */
-    cacheDir?: string;
+    cacheDir?: string | undefined;
     /**
      * If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
      */
-    cache?: boolean;
+    cache?: boolean | undefined;
     /**
      * Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release. Must be https, except for localhost.
      */
-    appImageToolUrl?: string;
+    appImageToolUrl?: string | undefined;
     /**
      * If true, embed a GPG signature in the AppImage. Requires `gpg` and a usable secret key on the host. A passphrase-protected key reads its passphrase from the `APPIMAGETOOL_SIGN_PASSPHRASE` environment variable.
      */
-    sign?: boolean;
+    sign?: boolean | undefined;
     /**
      * ID of the GPG key to sign with. Defaults to `gpg`'s default secret key. Requires `sign` to be true.
      */
-    signKey?: string;
+    signKey?: 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;
+    version?: string | undefined;
     /**
      * Where releases are published. When set, an `app-update.yml` pointing at it is embedded in the AppImage and a `latest-linux[-<arch>].yml` update info file is written next to it, for `@nwutils/updater` to self update from.
      */
-    publish?: PublishOptions;
+    publish?: PublishOptions | undefined;
     /**
      * AppImage update information for zsync based updaters (eg. AppImageUpdate, `appimageupdatetool`, AppImage managers). `true` derives it from `publish`. A string is embedded as-is, eg. `"gh-releases-zsync|owner|repo|latest|Demo-x86_64.AppImage.zsync"`. Requires `zsyncmake` on the host to produce the `.zsync` file.
      */
-    updateInformation?: string | boolean;
+    updateInformation?: string | boolean | undefined;
 };
+/**
+ * Publish to a GitHub repository's releases. The AppImage and update info
+ * file must be uploaded as assets of the latest (non draft, non prerelease)
+ * release.
+ */
 export type GitHubPublishOptions = {
     provider: "github";
     /**
@@ -63,6 +69,10 @@ export type GitHubPublishOptions = {
      */
     repo: string;
 };
+/**
+ * Publish to any static file server. The AppImage and update info file must
+ * be served from `url`.
+ */
 export type GenericPublishOptions = {
     provider: "generic";
     /**
@@ -128,11 +138,9 @@ declare function appImage({ appDir, appName, icon, arch, outDir, cacheDir, cache
  * @param  {boolean} options.cache             If true, reuse a cached binary. Otherwise redownload it.
  * @returns {Promise<string>}  Path to an executable `appimagetool` binary.
  */
-declare function getAppImageTool({ appImageToolArch, appImageToolUrl, cacheDir, cache, }: {
+export function getAppImageTool({ appImageToolArch, appImageToolUrl, cacheDir, cache, }: {
     appImageToolArch: string;
     appImageToolUrl: string;
     cacheDir: string;
     cache: boolean;
 }): Promise<string>;
-export default appImage;
-export { getAppImageTool };

package/types/index.d.ts

@@ -1,12 +1,24 @@
+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.
+ */
 export type PackageFormat = "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
+/**
+ * Where releases are published, for packagers that support self updating.
+ */
 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. 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
  */
 /**
@@ -17,10 +29,9 @@ 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`) 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.
  */
 declare function packager({ format, ...options }: {
     format: PackageFormat;
 } & Record<string, any>): Promise<string>;
-export default packager;

package/types/nsis.d.ts

@@ -0,0 +1,140 @@
+export default nsis;
+export type NsisOptions = {
+    /**
+     * Path to a built NW.js Windows application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "win"`.
+     */
+    appDir: string;
+    /**
+     * Name of the application. Must match the `app.name` value used to build `appDir` - the executable is expected at `<appDir>/<appName>.exe`. Must be a valid Windows file name.
+     */
+    appName: string;
+    /**
+     * Version of the application, eg. `"1.2.0"`. Shown in Windows' installed apps list, and converted to `X.X.X.X` for the installer's own version resource.
+     */
+    version: string;
+    /**
+     * Architecture `appDir` was built for. Defaults to the host architecture. The installer refuses to run on Windows machines that can't run that architecture.
+     */
+    arch?: "ia32" | "x64" | "arm64" | undefined;
+    /**
+     * Directory the resulting `<appName>-<arch>-Setup.exe` file is written to. Defaults to the parent directory of `appDir`.
+     */
+    outDir?: string | undefined;
+    /**
+     * Path to a `.ico` icon for the installer and uninstaller. Defaults to NSIS' own icon.
+     */
+    icon?: string | undefined;
+    /**
+     * Name of the registry key the installation is recorded under. Defaults to `appName`. Keep it the same across releases, so installing a new version replaces the previous one.
+     */
+    appId?: string | undefined;
+    /**
+     * Publisher shown in Windows' installed apps list.
+     */
+    publisher?: string | undefined;
+    /**
+     * Copyright notice written into the installer's version information.
+     */
+    copyright?: string | undefined;
+    /**
+     * Path to a `.txt` or `.rtf` license file. When set, the installer shows it on a page the user has to accept.
+     */
+    license?: string | undefined;
+    /**
+     * If true, create a desktop shortcut.
+     */
+    desktopShortcut?: boolean | undefined;
+    /**
+     * If true, create a Start Menu shortcut.
+     */
+    startMenuShortcut?: boolean | undefined;
+    /**
+     * Path to the NSIS compiler. Defaults to `makensis` on the `PATH`.
+     */
+    makensisPath?: string | undefined;
+};
+/**
+ * The files and directories of a built application, relative to its root.
+ */
+export type AppFiles = {
+    /**
+     * Relative file paths, using the host's path separator.
+     */
+    files: string[];
+    /**
+     * Relative directory paths, parents before children.
+     */
+    dirs: string[];
+    /**
+     * Total size of `files` in bytes.
+     */
+    size: number;
+};
+/**
+ * Package a built NW.js Windows application as an NSIS installer.
+ *
+ * The installer installs for the current user only, into
+ * `%LOCALAPPDATA%\Programs\<appName>`, so it never asks for administrator
+ * rights. It registers an uninstaller in Windows' installed apps list, and
+ * installing a new version first uninstalls the previous one. Both wait for
+ * the application to be closed before touching its files.
+ *
+ * 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
+ * any host.
+ * @async
+ * @function
+ * @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>;
+/**
+ * List the files and directories under `appDir`. Symbolic links are followed,
+ * since NSIS copies what they point at.
+ * @async
+ * @function
+ * @param  {string}  appDir  Absolute path to the built application.
+ * @returns {Promise<AppFiles>}
+ */
+export function listAppFiles(appDir: string): Promise<AppFiles>;
+/**
+ * Generate the NSIS script for an installer.
+ *
+ * Every file is listed explicitly rather than copied with `File /r`, so the
+ * uninstaller deletes exactly the files that were installed. The user can
+ * choose any install directory - including one such as `C:\` that holds
+ * other files - so the uninstaller never deletes directories recursively.
+ * @param  {object}                    options
+ * @param  {string}                    options.appDir             Absolute path to the built application.
+ * @param  {AppFiles}                  options.appFiles           Files and directories under `appDir`.
+ * @param  {string}                    options.appName
+ * @param  {string}                    options.appId
+ * @param  {string}                    options.version
+ * @param  {string}                    options.fileVersion        `version` in `X.X.X.X` form.
+ * @param  {"ia32" | "x64" | "arm64"}  options.arch
+ * @param  {string}                    options.installerPath      Absolute path the installer is written to.
+ * @param  {string}                    [options.iconPath]         Absolute path to a `.ico` file.
+ * @param  {string}                    [options.licensePath]      Absolute path to a `.txt` or `.rtf` file.
+ * @param  {string}                    [options.publisher]
+ * @param  {string}                    options.copyright
+ * @param  {boolean}                   options.desktopShortcut
+ * @param  {boolean}                   options.startMenuShortcut
+ * @returns {string}
+ */
+export function nsisScript({ appDir, appFiles, appName, appId, version, fileVersion, arch, installerPath, iconPath, licensePath, publisher, copyright, desktopShortcut, startMenuShortcut, }: {
+    appDir: string;
+    appFiles: AppFiles;
+    appName: string;
+    appId: string;
+    version: string;
+    fileVersion: string;
+    arch: "ia32" | "x64" | "arm64";
+    installerPath: string;
+    iconPath?: string | undefined;
+    licensePath?: string | undefined;
+    publisher?: string | undefined;
+    copyright: string;
+    desktopShortcut: boolean;
+    startMenuShortcut: boolean;
+}): string;

package/types/util.d.ts

@@ -1,3 +1,35 @@
+declare namespace _default {
+    export { APPIMAGE_ARCH_KV };
+    export { desktopExecArg };
+    export { fileExists };
+    export { isWindowsFileName };
+    export { nsisEscape };
+    export { nsisPath };
+    export { parseDesktopEntry };
+    export { sha512 };
+    export { shellQuote };
+    export { stringifyDesktopEntry };
+    export { stringifyYaml };
+    export { updateInfoFileName };
+    export { windowsVersion };
+}
+export default _default;
+/**
+ * Map nw-builder's architecture identifiers to the identifiers used in
+ * `appimagetool` release asset names and its `ARCH` environment variable.
+ * @type {Record<"ia32" | "x64" | "arm64", string>}
+ */
+declare const APPIMAGE_ARCH_KV: Record<"ia32" | "x64" | "arm64", 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
+ * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
+ * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
+ * required for every string value.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function desktopExecArg(value: string): string;
 /**
  * Check if a file or directory exists.
  * @async
@@ -6,6 +38,35 @@
  * @returns {Promise<boolean>}
  */
 declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Check that `value` can be used as a single Windows file name: no path
+ * separators, characters Windows forbids in file names, control characters,
+ * trailing dots or spaces, or reserved device names.
+ * @param {string} value
+ * @returns {boolean}
+ */
+declare function isWindowsFileName(value: string): boolean;
+/**
+ * Escape `value` for use inside a double quoted NSIS string. NSIS expands `$`
+ * variables and `$\` escapes there, so `$` is doubled and `"` is escaped.
+ * Line breaks are rejected rather than escaped: a raw one would end the
+ * command and let the value inject further script lines. The result is not
+ * quoted, so it can be joined with NSIS variables, eg. `"$INSTDIR\<value>"`.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function nsisEscape(value: string): string;
+/**
+ * Check a path on the host for use inside a double quoted NSIS string that
+ * `makensis` reads at compile time, eg. a `File` source or `OutFile`. Unlike
+ * runtime strings, those keep `$` literally, so nothing is escaped. Instead,
+ * the sequences `makensis` would still interpret are rejected: `${define}`
+ * expansions and `$\` escapes, and `"` - an escaped `$\"` doesn't survive
+ * being passed through a `!define`, as the icon and license paths are.
+ * @param {string} value
+ * @returns {string}  `value`, unchanged.
+ */
+declare function nsisPath(value: string): string;
 /**
  * Parse a freedesktop.org desktop entry file's `[Desktop Entry]` group into
  * a key/value map. Other groups (eg. `[Desktop Action ...]`) are ignored.
@@ -14,11 +75,14 @@ declare function fileExists(filePath: string): Promise<boolean>;
  */
 declare function parseDesktopEntry(contents: string): Record<string, string>;
 /**
- * Serialise a `[Desktop Entry]` key/value map back into a desktop entry file.
- * @param {Record<string, string | undefined>} entries
- * @returns {string}
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
+ * same encoding electron-builder writes into its update info files.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<string>}
  */
-declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
+declare function sha512(filePath: string): Promise<string>;
 /**
  * Quote `value` as a single POSIX shell word. Inside single quotes nothing is
  * expanded, so only single quotes themselves need escaping.
@@ -27,15 +91,19 @@ declare function stringifyDesktopEntry(entries: Record<string, string | undefine
  */
 declare function shellQuote(value: string): 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
- * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
- * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
- * required for every string value.
- * @param {string} value
+ * Serialise a `[Desktop Entry]` key/value map back into a desktop entry file.
+ * @param {Record<string, string | undefined>} entries
  * @returns {string}
  */
-declare function desktopExecArg(value: string): string;
+declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
+/**
+ * Serialise a map of scalars, and lists of maps of scalars, as YAML. This is
+ * the only shape the update info and `app-update.yml` files use, so it avoids
+ * pulling in a YAML library for a handful of lines.
+ * @param {Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>} entries
+ * @returns {string}
+ */
+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
@@ -45,31 +113,11 @@ declare function desktopExecArg(value: string): string;
  */
 declare function updateInfoFileName(arch: "ia32" | "x64" | "arm64"): string;
 /**
- * Serialise a map of scalars, and lists of maps of scalars, as YAML. This is
- * the only shape the update info and `app-update.yml` files use, so it avoids
- * pulling in a YAML library for a handful of lines.
- * @param {Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>} entries
+ * 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`)
+ * require. Up to four leading numeric parts are kept, missing ones are
+ * filled with `0`, and any prerelease or build suffix is dropped.
+ * @param {string} version
  * @returns {string}
  */
-declare function stringifyYaml(entries: Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>): string;
-/**
- * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
- * same encoding electron-builder writes into its update info files.
- * @async
- * @function
- * @param {string} filePath
- * @returns {Promise<string>}
- */
-declare function sha512(filePath: string): Promise<string>;
-declare const _default: {
-    APPIMAGE_ARCH_KV: Record<"arm64" | "ia32" | "x64", string>;
-    desktopExecArg: typeof desktopExecArg;
-    fileExists: typeof fileExists;
-    parseDesktopEntry: typeof parseDesktopEntry;
-    sha512: typeof sha512;
-    shellQuote: typeof shellQuote;
-    stringifyDesktopEntry: typeof stringifyDesktopEntry;
-    stringifyYaml: typeof stringifyYaml;
-    updateInfoFileName: typeof updateInfoFileName;
-};
-export default _default;
+declare function windowsVersion(version: string): string;