@nwutils/packager 0.1.0 → 0.2.0

package/README.md

@@ -2,10 +2,82 @@
 
 [![npm](https://img.shields.io/npm/v/@nwutils/packager/latest)](https://www.npmjs.com/package/@nwutils/packager/v/latest)
 
+Package NW.js applications for Linux, MacOS and Windows.
+
+Currently supported: packaging a Linux application as an [AppImage](https://appimage.org/).
+
 ## Getting Started
 
 1. `npm i` to install third party dependencies
 
+## Usage
+
+This composes with `@nwutils/builder`: run it against the `outDir` (and `app.name`)
+that `@nwutils/builder` produced for `platform: "linux"`.
+
+```js
+import build from "@nwutils/builder";
+import { appImage } from "@nwutils/packager";
+
+await build({
+  version: "0.115.0",
+  platform: "linux",
+  arch: "x64",
+  srcDir: "./src",
+  cacheDir: "./cache",
+  outDir: "./out",
+  app: {
+    name: "Demo",
+    icon: "icon.png",
+    categories: "Utility;",
+  },
+});
+
+const appImagePath = await appImage({
+  appDir: "./out",
+  appName: "Demo",
+  cacheDir: "./cache",
+  outDir: "./dist",
+});
+
+console.log(`AppImage written to ${appImagePath}`);
+```
+
+The first time it runs for a given architecture, `appImage()` downloads
+[`appimagetool`](https://github.com/AppImage/appimagetool) into `cacheDir` and
+reuses it on subsequent calls. `appimagetool` is a native Linux binary, so
+`appImage()` only runs on a Linux host, targeting the host's own architecture
+by default.
+
+`appimagetool` is invoked with `APPIMAGE_EXTRACT_AND_RUN=1`, so a FUSE mount is
+never required - useful in containers, CI runners and other sandboxes where
+FUSE is typically unavailable.
+
+## API Reference
+
+### `appImage(options)`
+
+Options
+
+| Name            | Type                         | Description                                                                                                              |
+| --------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| appDir          | `string`                     | Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`         |
+| appName         | `string`                     | Name of the application. Must match the `app.name` value used to build `appDir`                                          |
+| icon            | `string`                     | Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`                     |
+| arch            | `"ia32" \| "x64" \| "arm64"` | Target architecture. Defaults to the host architecture                                                                   |
+| outDir          | `string`                     | Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`                     |
+| cacheDir        | `string`                     | Directory used to cache the downloaded `appimagetool` binary. Defaults to `"./cache"`                                    |
+| cache           | `boolean`                    | If true, reuse a cached `appimagetool` binary. Otherwise redownload it. Defaults to `true`                               |
+| appImageToolUrl | `string`                     | Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" release |
+
+Resolves with the path to the resulting `.AppImage` file.
+
+The application's desktop entry file (`<appDir>/<appName>.desktop`, as written
+by `@nwutils/builder`) is copied into the AppImage with its `Exec` and `Icon`
+keys rewritten to match the AppImage's own layout, and a `Categories` key
+added (defaulting to `Utility;`) if one isn't already present, since
+`appimagetool` refuses to build an AppImage without one.
+
 ## Contributing
 
 ### External contributor

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwutils/packager",
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.2.0",
+  "description": "Package NW.js applications for Linux, MacOS and Windows.",
   "keywords": [
     "NW.js",
     "node-webkit",
@@ -26,10 +26,12 @@
   ],
   "license": "MIT",
   "main": "./src/index.js",
+  "types": "types/index.d.ts",
   "type": "module",
   "files": [
     "LICENSE",
-    "src"
+    "src",
+    "types"
   ],
   "homepage": "https://github.com/nwutils/nw-builder",
   "repository": {
@@ -37,10 +39,11 @@
     "url": "git+https://github.com/nwutils/nw-builder.git"
   },
   "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "lint": "eslint . ../../tests/specs/packager ../../tests/fixtures/packager",
+    "lint:fix": "eslint . ../../tests/specs/packager ../../tests/fixtures/packager --fix",
     "type": "tsc",
-    "test": "node --test \"../../tests/specs/packager/*.test.js\""
+    "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\""
   },
   "dependencies": {},
   "devDependencies": {}

package/src/appImage.js

@@ -0,0 +1,266 @@
+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 request from "./request.js";
+import util from "./util.js";
+
+/**
+ * Default location `appimagetool` is downloaded from. The `continuous` tag
+ * is rebuilt on every push to the default branch and publishes one asset per
+ * architecture, eg. `appimagetool-x86_64.AppImage`.
+ * @type {string}
+ */
+const APPIMAGETOOL_URL =
+  "https://github.com/AppImage/appimagetool/releases/download/continuous";
+
+/**
+ * @typedef  {object}                       AppImageOptions
+ * @property {string}                       appDir             Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+ * @property {string}                       [icon]             Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
+ * @property {"ia32" | "x64" | "arm64"}     [arch]             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.
+ * @property {string}                       [outDir]           Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
+ * @property {string}                       [cacheDir="./cache"] Directory used to cache the downloaded `appimagetool` binary.
+ * @property {boolean}                      [cache=true]       If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
+ * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+ */
+
+/**
+ * Package a built NW.js Linux application as an AppImage.
+ *
+ * This composes with `@nwutils/builder`: run it against the `outDir` (and
+ * `app.name`) that `@nwutils/builder` produced for `platform: "linux"`.
+ * @async
+ * @function
+ * @param  {AppImageOptions}  options
+ * @returns {Promise<string>}  Path to the resulting `.AppImage` file.
+ */
+async function appImage({
+  appDir,
+  appName,
+  icon,
+  arch,
+  outDir,
+  cacheDir = "./cache",
+  cache = true,
+  appImageToolUrl = APPIMAGETOOL_URL,
+}) {
+  if (process.platform !== "linux") {
+    throw new Error(
+      `AppImage packaging requires a Linux host, since "appimagetool" is a native Linux binary. Received host platform: ${process.platform}`,
+    );
+  }
+
+  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}`);
+  }
+
+  if (typeof appName !== "string" || appName === "") {
+    throw new Error(
+      `Expected "options.appName" to be a non-empty string. Received: ${JSON.stringify(appName)}`,
+    );
+  }
+
+  const resolvedArch =
+    /** @type {"ia32" | "x64" | "arm64" | undefined} */ (arch) ??
+    /** @type {"ia32" | "x64" | "arm64"} */ (
+      /** @type {unknown} */ (process.arch)
+    );
+
+  const appImageToolArch = util.APPIMAGE_ARCH_KV[resolvedArch];
+  if (appImageToolArch === undefined) {
+    throw new Error(
+      `Expected "options.arch" to be "ia32", "x64" or "arm64". Received: ${JSON.stringify(arch)}`,
+    );
+  }
+
+  const resolvedAppDir = path.resolve(appDir);
+  const executablePath = path.resolve(resolvedAppDir, appName);
+  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"?`,
+    );
+  }
+
+  const desktopFilePath = path.resolve(resolvedAppDir, `${appName}.desktop`);
+  if ((await util.fileExists(desktopFilePath)) === false) {
+    throw new Error(
+      `Expected a desktop entry file to exist at ${desktopFilePath}. Build "options.appDir" with "@nwutils/builder" for "platform: \\"linux\\"" first.`,
+    );
+  }
+  const desktopEntry = util.parseDesktopEntry(
+    await fs.promises.readFile(desktopFilePath, "utf-8"),
+  );
+
+  const resolvedIcon = icon ?? desktopEntry.Icon;
+  if (resolvedIcon === undefined || resolvedIcon === "") {
+    throw new Error(
+      'AppImage packaging requires an icon. Pass "options.icon", or ensure the "Icon" key in the desktop entry file points at an existing file.',
+    );
+  }
+  const resolvedIconPath = path.resolve(resolvedIcon);
+  if ((await util.fileExists(resolvedIconPath)) === false) {
+    throw new Error(`"options.icon" does not exist: ${resolvedIconPath}`);
+  }
+
+  const resolvedOutDir = path.resolve(outDir ?? path.dirname(resolvedAppDir));
+  await fs.promises.mkdir(resolvedOutDir, { recursive: true });
+
+  const resolvedCacheDir = path.resolve(cacheDir);
+  const appImageToolPath = await getAppImageTool({
+    appImageToolArch,
+    appImageToolUrl,
+    cacheDir: resolvedCacheDir,
+    cache,
+  });
+
+  const appImageDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "nwutils-packager-"),
+  );
+
+  try {
+    await fs.promises.cp(resolvedAppDir, appImageDir, {
+      recursive: true,
+      force: true,
+      verbatimSymlinks: true,
+    });
+
+    const iconFileName = path.basename(resolvedIconPath);
+    await fs.promises.cp(
+      resolvedIconPath,
+      path.resolve(appImageDir, iconFileName),
+      { force: true },
+    );
+
+    /*
+     * `Exec` and `Icon` are rewritten unconditionally: `Exec` may be unset or
+     * point at something other than the renamed binary, and `Icon` is an
+     * absolute build-time path - neither survives being relocated into an
+     * AppImage, whose root is what ends up mounted at runtime. `Categories`
+     * is only filled in when absent: `appimagetool` refuses to build an
+     * AppImage without one, but `@nwutils/builder`'s `app.categories` is
+     * optional, so most callers won't have set it.
+     */
+    const appImageDesktopEntry = {
+      ...desktopEntry,
+      Name: desktopEntry.Name ?? appName,
+      Exec: appName,
+      Icon: path.basename(iconFileName, path.extname(iconFileName)),
+      Categories: desktopEntry.Categories || "Utility;",
+    };
+    await fs.promises.writeFile(
+      path.resolve(appImageDir, `${appName}.desktop`),
+      util.stringifyDesktopEntry(appImageDesktopEntry),
+    );
+
+    const appRunPath = path.resolve(appImageDir, "AppRun");
+    await fs.promises.writeFile(
+      appRunPath,
+      [
+        "#!/bin/sh",
+        'HERE="$(dirname "$(readlink -f "${0}")")"',
+        `exec "\${HERE}/${appName}" "$@"`,
+        "",
+      ].join("\n"),
+    );
+    await fs.promises.chmod(appRunPath, 0o755);
+
+    const appImageFilePath = path.resolve(
+      resolvedOutDir,
+      `${appName}-${appImageToolArch}.AppImage`,
+    );
+
+    child_process.execFileSync(
+      appImageToolPath,
+      ["--no-appstream", appImageDir, appImageFilePath],
+      {
+        env: {
+          ...process.env,
+          ARCH: appImageToolArch,
+          /*
+           * `appimagetool` is itself distributed as an AppImage. Extract and
+           * run it directly instead of mounting it via FUSE, which is
+           * frequently unavailable in containers, CI runners and sandboxes.
+           */
+          APPIMAGE_EXTRACT_AND_RUN: "1",
+        },
+        stdio: "inherit",
+      },
+    );
+
+    return appImageFilePath;
+  } finally {
+    await fs.promises.rm(appImageDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Download (or reuse a cached) `appimagetool` binary for `appImageToolArch`.
+ * @async
+ * @function
+ * @param  {object}  options
+ * @param  {string}  options.appImageToolArch  `appimagetool` architecture identifier, eg. "x86_64".
+ * @param  {string}  options.appImageToolUrl   Base URL to download `appimagetool-<arch>.AppImage` from.
+ * @param  {string}  options.cacheDir          Directory used to cache the downloaded binary.
+ * @param  {boolean} options.cache             If true, reuse a cached binary. Otherwise redownload it.
+ * @returns {Promise<string>}  Path to an executable `appimagetool` binary.
+ */
+async function getAppImageTool({
+  appImageToolArch,
+  appImageToolUrl,
+  cacheDir,
+  cache,
+}) {
+  const appImageToolPath = path.resolve(
+    cacheDir,
+    `appimagetool-${appImageToolArch}.AppImage`,
+  );
+
+  if (cache === false) {
+    await fs.promises.rm(appImageToolPath, { force: true });
+  }
+
+  if ((await util.fileExists(appImageToolPath)) === false) {
+    await fs.promises.mkdir(cacheDir, { recursive: true });
+    await request(
+      `${appImageToolUrl}/appimagetool-${appImageToolArch}.AppImage`,
+      appImageToolPath,
+    );
+
+    /*
+     * `appimagetool-<arch>.AppImage` has no published checksum to verify
+     * against (the "continuous" release is rebuilt in place). Checking the
+     * ELF magic bytes at least catches an HTML error page or truncated
+     * download being saved and later executed as though it were the tool.
+     */
+    const magic = Buffer.alloc(4);
+    const fileHandle = await fs.promises.open(appImageToolPath, "r");
+    try {
+      await fileHandle.read(magic, 0, 4, 0);
+    } finally {
+      await fileHandle.close();
+    }
+    if (magic.toString("hex") !== "7f454c46") {
+      await fs.promises.rm(appImageToolPath, { force: true });
+      throw new Error(
+        `Downloaded "appimagetool" from ${appImageToolUrl}/appimagetool-${appImageToolArch}.AppImage does not look like an ELF binary.`,
+      );
+    }
+  }
+
+  await fs.promises.chmod(appImageToolPath, 0o755);
+
+  return appImageToolPath;
+}
+
+export default appImage;
+export { getAppImageTool };

package/src/index.js

@@ -1 +1,7 @@
-export default {};
+import appImage from "./appImage.js";
+
+export default {
+  appImage,
+};
+
+export { appImage };

package/src/request.js

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import process from "node:process";
+import { URL } from "node:url";
+
+/**
+ * Maximum number of HTTP redirects to follow before giving up.
+ * @type {number}
+ */
+const MAX_REDIRECTS = 5;
+
+/**
+ * Download from `url` and save at `filePath`.
+ * @param {string} url
+ * @param {string} filePath
+ * @param {number} [redirectCount] - Number of redirects already followed. Used internally for recursive calls.
+ * @returns {Promise<void>}
+ */
+export default function request(url, filePath, redirectCount = 0) {
+  const parsedUrl = new URL(url);
+  const client = parsedUrl.protocol === "https:" ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const writeStream = fs.createWriteStream(filePath);
+
+    /* Handle writeStream errors immediately */
+    writeStream.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+
+    /* Ctrl+C cleanup */
+    const onSigInt = () => {
+      writeStream.destroy();
+      /*
+       * Unlink unconditionally and swallow ENOENT: checking with existsSync
+       * first is a check-then-act race (CWE-367) - the file can vanish between
+       * the two calls, and on SIGINT there is no useful recovery either way.
+       */
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+        /* Nothing to clean up. */
+      }
+      process.exit();
+    };
+    process.once("SIGINT", onSigInt);
+
+    const req = client.get(
+      {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port || (parsedUrl.protocol === "https:" ? 443 : 80),
+        path: parsedUrl.pathname + parsedUrl.search,
+        headers: {
+          "User-Agent": "node:http(s)",
+        },
+      },
+      (res) => {
+        /* Redirect handling */
+        if (
+          res.statusCode &&
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          cleanup();
+
+          if (redirectCount >= MAX_REDIRECTS) {
+            return reject(
+              new Error(
+                `Too many redirects (> ${MAX_REDIRECTS}) while requesting ${url}`,
+              ),
+            );
+          }
+
+          const redirectedUrl = new URL(res.headers.location, parsedUrl);
+
+          /*
+           * A redirect response can be injected by a network attacker even
+           * when the original request can't be, so refuse one that would
+           * silently strip transport security from the rest of the chain.
+           */
+          if (
+            parsedUrl.protocol === "https:" &&
+            redirectedUrl.protocol === "http:"
+          ) {
+            return reject(
+              new Error(
+                `Refusing to follow redirect from ${url} to ${redirectedUrl.toString()}: downgrades from https to http.`,
+              ),
+            );
+          }
+
+          return resolve(
+            request(redirectedUrl.toString(), filePath, redirectCount + 1),
+          );
+        }
+
+        if (res.statusCode !== 200) {
+          cleanup();
+          return reject(
+            new Error(`Request failed. Status code: ${res.statusCode}`),
+          );
+        }
+
+        res.pipe(writeStream);
+
+        writeStream.on("finish", () => {
+          cleanup();
+          resolve();
+        });
+
+        res.on("error", (err) => {
+          cleanup();
+          reject(err);
+        });
+      },
+    );
+
+    req.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+
+    function cleanup() {
+      process.removeListener("SIGINT", onSigInt);
+      req.destroy();
+      writeStream.destroy();
+    }
+  });
+}

package/src/util.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+
+/**
+ * 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>}
+ */
+const APPIMAGE_ARCH_KV = {
+  ia32: "i686",
+  x64: "x86_64",
+  arm64: "aarch64",
+};
+
+/**
+ * Check if a file or directory exists.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(filePath) {
+  let exists = true;
+  try {
+    await fs.promises.stat(filePath);
+  } catch {
+    exists = false;
+  }
+  return exists;
+}
+
+/**
+ * Parse a freedesktop.org desktop entry file's `[Desktop Entry]` group into
+ * a key/value map. Other groups (eg. `[Desktop Action ...]`) are ignored.
+ * @param {string} contents
+ * @returns {Record<string, string>}
+ */
+function parseDesktopEntry(contents) {
+  /** @type {Record<string, string>} */
+  const entries = {};
+  let inDesktopEntryGroup = false;
+
+  for (const rawLine of contents.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    if (line.startsWith("[")) {
+      inDesktopEntryGroup = line === "[Desktop Entry]";
+      continue;
+    }
+    if (inDesktopEntryGroup === false) {
+      continue;
+    }
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim();
+    entries[key] = value;
+  }
+
+  return entries;
+}
+
+/**
+ * Serialise a `[Desktop Entry]` key/value map back into a desktop entry file.
+ * @param {Record<string, string | undefined>} entries
+ * @returns {string}
+ */
+function stringifyDesktopEntry(entries) {
+  let fileContent = "[Desktop Entry]\n";
+  for (const key of Object.keys(entries)) {
+    if (entries[key] !== undefined) {
+      fileContent += `${key}=${entries[key]}\n`;
+    }
+  }
+  return fileContent;
+}
+
+export default {
+  APPIMAGE_ARCH_KV,
+  fileExists,
+  parseDesktopEntry,
+  stringifyDesktopEntry,
+};

package/types/appImage.d.ts

@@ -0,0 +1,75 @@
+export type AppImageOptions = {
+    /**
+     * Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
+     */
+    appDir: string;
+    /**
+     * Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+     */
+    appName: string;
+    /**
+     * Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
+     */
+    icon?: string;
+    /**
+     * 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";
+    /**
+     * Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
+     */
+    outDir?: string;
+    /**
+     * Directory used to cache the downloaded `appimagetool` binary.
+     */
+    cacheDir?: string;
+    /**
+     * If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
+     */
+    cache?: boolean;
+    /**
+     * Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+     */
+    appImageToolUrl?: string;
+};
+/**
+ * @typedef  {object}                       AppImageOptions
+ * @property {string}                       appDir             Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+ * @property {string}                       [icon]             Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
+ * @property {"ia32" | "x64" | "arm64"}     [arch]             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.
+ * @property {string}                       [outDir]           Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
+ * @property {string}                       [cacheDir="./cache"] Directory used to cache the downloaded `appimagetool` binary.
+ * @property {boolean}                      [cache=true]       If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
+ * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+ */
+/**
+ * Package a built NW.js Linux application as an AppImage.
+ *
+ * This composes with `@nwutils/builder`: run it against the `outDir` (and
+ * `app.name`) that `@nwutils/builder` produced for `platform: "linux"`.
+ * @async
+ * @function
+ * @param  {AppImageOptions}  options
+ * @returns {Promise<string>}  Path to the resulting `.AppImage` file.
+ */
+declare function appImage({ appDir, appName, icon, arch, outDir, cacheDir, cache, appImageToolUrl, }: AppImageOptions): Promise<string>;
+/**
+ * Download (or reuse a cached) `appimagetool` binary for `appImageToolArch`.
+ * @async
+ * @function
+ * @param  {object}  options
+ * @param  {string}  options.appImageToolArch  `appimagetool` architecture identifier, eg. "x86_64".
+ * @param  {string}  options.appImageToolUrl   Base URL to download `appimagetool-<arch>.AppImage` from.
+ * @param  {string}  options.cacheDir          Directory used to cache the downloaded binary.
+ * @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, }: {
+    appImageToolArch: string;
+    appImageToolUrl: string;
+    cacheDir: string;
+    cache: boolean;
+}): Promise<string>;
+export default appImage;
+export { getAppImageTool };

package/types/index.d.ts

@@ -0,0 +1,6 @@
+import appImage from "./appImage.js";
+declare const _default: {
+    appImage: typeof appImage;
+};
+export default _default;
+export { appImage };

package/types/request.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Download from `url` and save at `filePath`.
+ * @param {string} url
+ * @param {string} filePath
+ * @param {number} [redirectCount] - Number of redirects already followed. Used internally for recursive calls.
+ * @returns {Promise<void>}
+ */
+export default function request(url: string, filePath: string, redirectCount?: number): Promise<void>;

package/types/util.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Check if a file or directory exists.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Parse a freedesktop.org desktop entry file's `[Desktop Entry]` group into
+ * a key/value map. Other groups (eg. `[Desktop Action ...]`) are ignored.
+ * @param {string} contents
+ * @returns {Record<string, string>}
+ */
+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}
+ */
+declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
+declare const _default: {
+    APPIMAGE_ARCH_KV: Record<"arm64" | "ia32" | "x64", string>;
+    fileExists: typeof fileExists;
+    parseDesktopEntry: typeof parseDesktopEntry;
+    stringifyDesktopEntry: typeof stringifyDesktopEntry;
+};
+export default _default;