@nwutils/packager 0.5.0 → 0.7.0

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,17 @@ 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`, matching electron-builder: `x64` gets the bare
+ * `latest-linux.yml` (Linux) or `latest.yml` (Windows), every other
+ * architecture gets an `-<arch>` suffix.
+ * @param {string}           arch
+ * @param {"linux" | "win"}  [platform="linux"]
  * @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" : "latest-linux";
+  return arch === "x64" ? `${base}.yml` : `${base}-${arch}.yml`;
 }
 
 /**
@@ -180,14 +184,218 @@ 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(".");
+}
+
+/**
+ * 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,
+  nsisEscape,
+  nsisPath,
   parseDesktopEntry,
   sha512,
   shellQuote,
   stringifyDesktopEntry,
   stringifyYaml,
   updateInfoFileName,
+  validatePublish,
+  windowsVersion,
+  writeUpdateInfo,
 };

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,150 @@
+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;
+    /**
+     * 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.
+ */
+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.
+ *
+ * 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
+ * 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, publish, }: 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
+ * @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, appUpdateYamlPath, }: {
+    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;
+    appUpdateYamlPath?: string | undefined;
+}): string;