@nwutils/builder 0.1.0 → 0.1.1

package/LICENSE

@@ -1,7 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-2024 NW.js Utilities
-Copyright (c) 2014-2021 Steffen Müller
+Copyright (c) 2026 NW.js Utilities and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -1,5 +1,70 @@
 # @nwutils/builder
 
-Build NW.js applications for Linux, MacOS and Windows: assembles the app source and a cached NW.js runtime into a distributable package, and applies platform-specific metadata (Linux `.desktop` entry, Windows executable resources, MacOS `Info.plist` and helper app bundles).
+[![npm](https://img.shields.io/npm/v/@nwutils/builder/latest)](https://www.npmjs.com/package/@nwutils/builder/v/latest)
 
-Extracted from [nw-builder](../nw-builder)'s own build implementation so it can be developed, tested and versioned independently, the same way `@nwutils/getter` and `@nwutils/runner` already are. `nw-builder` depends on this package for its `build` mode; most users should keep using `nw-builder` (or `@nwutils/cli`) directly rather than this package on its own.
+Build NW.js applications for Linux, MacOS and Windows.
+
+## Getting Started
+
+1. `npm i` to install third party dependencies
+
+## Usage
+
+```js
+import build from "@nwutils/builder";
+
+await build({
+  version: "0.115.0",
+  flavor: "normal",
+  platform: "linux",
+  arch: "x64",
+  srcDir: "./src",
+  cacheDir: "./cache",
+  outDir: "./out",
+  app: {
+    name: "Demo",
+  },
+  glob: true,
+  managedManifest: false,
+  zip: false,
+  // The release info is from https://nwjs.io/versions.json
+  releaseInfo: {
+    ...,
+    components: {
+      "node": "26.7.0",
+      "chromium": "152.0.7977.42"
+    },
+  },
+});
+```
+
+## API Reference
+
+Options
+
+| Name            | Type                                      | Description                                                                                               |
+| --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| version         | `string \| "latest" \| "stable" \| "lts"` | Runtime version                                                                                           |
+| flavor          | `"normal" \| "sdk"`                       | Build flavor                                                                                              |
+| platform        | `"linux" \| "osx" \| "win"`               | Target platform                                                                                           |
+| arch            | `"ia32" \| "x64" \| "arm64"`              | Target architecture                                                                                       |
+| srcDir          | `string`                                  | Source directory                                                                                          |
+| cacheDir        | `string`                                  | Directory the target NW.js runtime is cached in (populated ahead of time by `@nwutils/getter`)            |
+| outDir          | `string`                                  | Directory to write the built application to                                                               |
+| app             | `object`                                  | Platform specific app metadata - see the `nw-builder` docs for the full shape per platform                |
+| glob            | `boolean`                                 | If true, `srcDir` is resolved via file globbing rather than copied as-is                                  |
+| managedManifest | `boolean \| string \| object`             | Managed manifest mode                                                                                     |
+| zip             | `false \| "zip" \| "tar" \| "tgz"`        | Compress the built application                                                                            |
+| releaseInfo     | `object`                                  | Version specific release metadata for the target runtime, e.g. `releaseInfo.components.chromium` on MacOS |
+
+## Contributing
+
+### External contributor
+
+- Use Node.js standard libraries whenever possible.
+- Prefer to use syncronous APIs over modern APIs which have been introduced in later versions.
+
+### Maintainer
+
+- npm Trusted Publishing with OIDC is used for releases
+- A package is released when a maintainer creates a release note for a specific version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwutils/builder",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Build NW.js applications for Linux, MacOS and Windows.",
   "keywords": [
     "NW.js",
@@ -27,9 +27,11 @@
   "license": "MIT",
   "main": "./src/main.js",
   "type": "module",
+  "types": "types/main.d.ts",
   "files": [
     "LICENSE",
-    "src"
+    "src",
+    "types"
   ],
   "homepage": "https://github.com/nwutils/nw-builder",
   "repository": {
@@ -39,6 +41,7 @@
   "scripts": {
     "lint": "eslint . ../../tests/specs/builder",
     "lint:fix": "eslint . ../../tests/specs/builder --fix",
+    "type": "tsc",
     "test": "node --test \"../../tests/specs/builder/*.test.js\""
   },
   "dependencies": {
@@ -51,6 +54,7 @@
     "tar": "^7.5.22"
   },
   "devDependencies": {
+    "@types/archiver": "^8.0.0",
     "base-volta-off-of-nwjs": "^1.0.5",
     "nw": "^0.115.0",
     "selenium-webdriver": "^4.47.0"

package/src/main.js

@@ -56,6 +56,7 @@ import setOsxConfig from "./osx.js";
  * @property {string} CFBundleShortVersionString      The release or version number of the bundle.
  * @property {string} NSHumanReadableCopyright        A human-readable copyright notice for the bundle.
  * @property {string} NSLocalNetworkUsageDescription  A human-readable description of why the application needs access to the local network.
+ * @property {boolean} LSFileQuarantineEnabled        Whether the app is subject to Gatekeeper file quarantine. See https://github.com/nwjs/nw.js/issues/7646
  */
 
 /**
@@ -80,7 +81,7 @@ import setOsxConfig from "./osx.js";
  * @property {string} productName       Name of the product with which the file is distributed. This string is required.
  * @property {string} productVersion    Version of the product with which the file is distributed—for example, 3.10 or 5.00.RC2. This string is required.
  * @property {string} specialBuild      Text that specifies how this version of the file differs from the standard version—for example, Private build for TESTER1 solving mouse problems on M250 and M250E computers. This string should be present only if VS_FF_SPECIALBUILD is specified in the fileflags parameter of the root block.
- * @property {string} languageCode      Language of the file, defined by Microsoft, see: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
+ * @property {number} languageCode      Language identifier (LCID) of the file, defined by Microsoft, see: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
  */
 
 /**
@@ -96,7 +97,7 @@ import setOsxConfig from "./osx.js";
  * @property {LinuxRc | WinRc | OsxRc}              [app]                                       Platform specific rc
  * @property {boolean}                              [glob = true]                               File globbing
  * @property {boolean | string | object}            [managedManifest = false]                   Manage manifest
- * @property {false | "zip" | "tar" | "tgz"}        [zip = false]                               Compress built artifacts
+ * @property {boolean | "zip" | "tar" | "tgz"}      [zip = false]                               Compress built artifacts
  * @property {object}                               [releaseInfo = {}]                          Version specific release metadata.
  */
 
@@ -110,8 +111,14 @@ import setOsxConfig from "./osx.js";
 async function build({
   version = "latest",
   flavor = "normal",
-  platform = util.PLATFORM_KV[process.platform],
-  arch = util.ARCH_KV[process.arch],
+  platform = /** @type {"linux" | "osx" | "win"} */ (
+    util.PLATFORM_KV[
+      /** @type {"darwin" | "linux" | "win32"} */ (process.platform)
+    ]
+  ),
+  arch = /** @type {"ia32" | "x64" | "arm64"} */ (
+    util.ARCH_KV[/** @type {"x64" | "ia32" | "arm64"} */ (process.arch)]
+  ),
   srcDir = "./src",
   cacheDir = "./cache",
   outDir = "./out",
@@ -142,7 +149,7 @@ async function build({
   await fs.promises.mkdir(nwProjectDir, { recursive: true });
 
   if (glob) {
-    for (let file of files) {
+    for (let file of /** @type {string[]} */ (files)) {
       const stats = await fs.promises.stat(file);
       if (stats.isDirectory()) {
         continue;
@@ -153,10 +160,14 @@ async function build({
       });
     }
   } else {
-    await fs.promises.cp(files, path.resolve(nwProjectDir), {
-      recursive: true,
-      verbatimSymlinks: true,
-    });
+    await fs.promises.cp(
+      /** @type {string} */ (files),
+      path.resolve(nwProjectDir),
+      {
+        recursive: true,
+        verbatimSymlinks: true,
+      },
+    );
   }
 
   const builtManifest = JSON.parse(
@@ -168,7 +179,7 @@ async function build({
 
   /* Set `product_string` in manifest for MacOS. This is used in renaming the Helper apps. */
   if (platform === "osx") {
-    builtManifest.product_string = app.name;
+    builtManifest.product_string = /** @type {OsxRc} */ (app).name;
     await fs.promises.writeFile(
       path.resolve(nwProjectDir, "package.json"),
       JSON.stringify(builtManifest, null, 2),
@@ -189,11 +200,16 @@ async function build({
   }
 
   if (platform === "linux") {
-    await setLinuxConfig({ app, outDir });
+    await setLinuxConfig({ app: /** @type {LinuxRc} */ (app), outDir });
   } else if (platform === "win") {
-    await setWinConfig({ app, outDir });
+    await setWinConfig({ app: /** @type {WinRc} */ (app), outDir });
   } else if (platform === "osx") {
-    await setOsxConfig({ version, app, outDir, releaseInfo });
+    await setOsxConfig({
+      version,
+      app: /** @type {OsxRc} */ (app),
+      outDir,
+      releaseInfo,
+    });
   }
 
   if (zip !== false) {
@@ -201,6 +217,14 @@ async function build({
   }
 }
 
+/**
+ * @param  {object}                        options
+ * @param  {object}                        options.nwPkg            Manifest built into the output NW.js app
+ * @param  {boolean | string | object}     options.managedManifest  Managed manifest mode
+ * @param  {string}                        options.outDir            Output directory
+ * @param  {"linux" | "osx" | "win"}       options.platform          Target platform
+ * @returns {Promise<void>}
+ */
 const manageManifest = async ({ nwPkg, managedManifest, outDir, platform }) => {
   let manifest = undefined;
 
@@ -213,7 +237,7 @@ const manageManifest = async ({ nwPkg, managedManifest, outDir, platform }) => {
   }
 
   if (typeof managedManifest === "string") {
-    manifest = JSON.parse(await fs.promises.readFile(managedManifest));
+    manifest = JSON.parse(await fs.promises.readFile(managedManifest, "utf8"));
   }
 
   if (manifest.devDependencies) {
@@ -245,12 +269,19 @@ const manageManifest = async ({ nwPkg, managedManifest, outDir, platform }) => {
   }
 };
 
+/**
+ * @param  {object}  options
+ * @param  {LinuxRc} options.app     Linux app configuration
+ * @param  {string}  options.outDir  Output directory
+ * @returns {Promise<void>}
+ */
 const setLinuxConfig = async ({ app, outDir }) => {
   if (process.platform === "win32") {
     console.warn(
       "Linux apps built on Windows platform do not preserve all file permissions. See #716",
     );
   }
+  /** @type {Record<string, unknown>} */
   let desktopEntryFile = {
     Type: "Application",
     Version: "1.5",
@@ -290,7 +321,14 @@ const setLinuxConfig = async ({ app, outDir }) => {
   await fs.promises.writeFile(filePath, fileContent);
 };
 
+/**
+ * @param  {object} options
+ * @param  {WinRc}  options.app     Windows app configuration
+ * @param  {string} options.outDir  Output directory
+ * @returns {Promise<void>}
+ */
 const setWinConfig = async ({ app, outDir }) => {
+  /** @type {Record<string, string>} */
   let versionString = {
     Comments: app.comments,
     CompanyName: app.company,
@@ -358,6 +396,12 @@ const setWinConfig = async ({ app, outDir }) => {
   await fs.promises.writeFile(outDirAppExe, outBuffer);
 };
 
+/**
+ * @param  {object}                          options
+ * @param  {boolean | "zip" | "tar" | "tgz"} options.zip     Compression format
+ * @param  {string}                          options.outDir  Directory to compress
+ * @returns {Promise<void>}
+ */
 const compress = async ({ zip, outDir }) => {
   if (zip === true || zip === "zip") {
     const archive = new ZipArchive();

package/src/osx.js

@@ -12,7 +12,7 @@ import semver from "semver";
  * @param {string} helperName            - Helper App Name
  * @param {string} helperId              - Helper App ID
  * @param {string} appCFBundleIdentifier - options.app.CFBundleIdentifier
- * @param {string} LSFileQuarantineEnabled - options.app.LSFileQuarantineEnabled
+ * @param {boolean} LSFileQuarantineEnabled - options.app.LSFileQuarantineEnabled
  */
 async function updateHelperPlist(
   plistPath,
@@ -22,6 +22,7 @@ async function updateHelperPlist(
   LSFileQuarantineEnabled,
 ) {
   const plistFullPath = path.resolve(plistPath, "Contents/Info.plist");
+  /** @type {any} */
   const plistJson = parse(await fs.promises.readFile(plistFullPath, "utf-8"));
   plistJson.CFBundleDisplayName = helperName;
   plistJson.CFBundleName = helperName;
@@ -35,9 +36,9 @@ async function updateHelperPlist(
  *
  * @param {object} options              - Options.
  * @param {string} options.version      - NW.js version.
- * @param {object} options.app          - Application configuration.
+ * @param {import("./main.js").OsxRc} options.app - Application configuration.
  * @param {string} options.outDir       - Output directory.
- * @param {string} options.releaseInfo  - Release information.
+ * @param {any} options.releaseInfo     - Release information, shaped by https://nwjs.io/versions.json.
  * @returns {Promise<void>}             - Promise.
  */
 export default async function setOsxConfig({
@@ -165,7 +166,7 @@ export default async function setOsxConfig({
 
     /**
      * JSON from `nwjs.app/Contents/Info.plist`
-     * @type {object}
+     * @type {any}
      */
     const contentsInfoPlistJson = parse(
       await fs.promises.readFile(contentsInfoPlistPath, "utf-8"),

package/src/util.js

@@ -19,7 +19,7 @@ const ARCH_KV = {
  * @param  {object}            options         - glob file options
  * @param  {string | string[]} options.srcDir  - app src dir
  * @param  {boolean}           options.glob    - glob flag
- * @returns {Promise<string[]>}                 - Returns array of file paths
+ * @returns {Promise<string[] | string>}        - Returns array of file paths, or `srcDir` as-is when `glob` is false
  */
 async function globFiles({ srcDir, glob }) {
   let files;

package/types/main.d.ts

@@ -0,0 +1,353 @@
+export type LinuxRc = {
+    /**
+     * Name of the application
+     */
+    name: string;
+    /**
+     * Generic name of the application
+     */
+    genericName: string;
+    /**
+     * If true the application is not displayed
+     */
+    noDisplay: boolean;
+    /**
+     * Tooltip for the entry, for example "View sites on the Internet".
+     */
+    comment: string;
+    /**
+     * Icon to display in file manager, menus, etc.
+     */
+    icon: string;
+    /**
+     * TBD
+     */
+    hidden: boolean;
+    /**
+     * A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+     */
+    onlyShowIn: string[];
+    /**
+     * A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+     */
+    notShowIn: string[];
+    /**
+     * A boolean value specifying if D-Bus activation is supported for this application
+     */
+    dBusActivatable: boolean;
+    /**
+     * Path to an executable file on disk used to determine if the program is actually installed
+     */
+    tryExec: string;
+    /**
+     * Program to execute, possibly with arguments.
+     */
+    exec: string;
+    /**
+     * If entry is of type Application, the working directory to run the program in.
+     */
+    path: string;
+    /**
+     * Whether the program runs in a terminal window.
+     */
+    terminal: boolean;
+    /**
+     * Identifiers for application actions.
+     */
+    actions: string[];
+    /**
+     * The MIME type(s) supported by this application.
+     */
+    mimeType: string[];
+    /**
+     * Categories in which the entry should be shown in a menu
+     */
+    categories: string[];
+    /**
+     * A list of interfaces that this application implements.
+     */
+    implements: string[];
+    /**
+     * A list of strings which may be used in addition to other metadata to describe this entry.
+     */
+    keywords: string[];
+    /**
+     * If true, it is KNOWN that the application will send a "remove" message when started with the DESKTOP_STARTUP_ID environment variable set. If false, it is KNOWN that the application does not work with startup notification at all.
+     */
+    startupNotify: boolean;
+    /**
+     * If specified, it is known that the application will map at least one window with the given string as its WM class or WM name hin
+     */
+    startupWMClass: string;
+    /**
+     * If true, the application prefers to be run on a more powerful discrete GPU if available.
+     */
+    prefersNonDefaultGPU: boolean;
+    /**
+     * If true, the application has a single main window, and does not support having an additional one opened.
+     */
+    singleMainWindow: string;
+};
+export type OsxRc = {
+    /**
+     * The name of the application
+     */
+    name: string;
+    /**
+     * The path to the icon file. It should be a .icns file.
+     */
+    icon: string;
+    /**
+     * The category that best describes your app for the App Store.
+     */
+    LSApplicationCategoryType: string;
+    /**
+     * A unique identifier for a bundle usually in reverse DNS format.
+     */
+    CFBundleIdentifier: string;
+    /**
+     * A user-visible short name for the bundle.
+     */
+    CFBundleName: string;
+    /**
+     * The user-visible name for the bundle.
+     */
+    CFBundleDisplayName: string;
+    /**
+     * A replacement for the app name in text-to-speech operations.
+     */
+    CFBundleSpokenName: string;
+    /**
+     * The version of the build that identifies an iteration of the bundle.
+     */
+    CFBundleVersion: string;
+    /**
+     * The release or version number of the bundle.
+     */
+    CFBundleShortVersionString: string;
+    /**
+     * A human-readable copyright notice for the bundle.
+     */
+    NSHumanReadableCopyright: string;
+    /**
+     * A human-readable description of why the application needs access to the local network.
+     */
+    NSLocalNetworkUsageDescription: string;
+    /**
+     * Whether the app is subject to Gatekeeper file quarantine. See https://github.com/nwjs/nw.js/issues/7646
+     */
+    LSFileQuarantineEnabled: boolean;
+};
+export type WinRc = {
+    /**
+     * The name of the application
+     */
+    name: string;
+    /**
+     * The version of the application
+     */
+    version: string;
+    /**
+     * Additional information that should be displayed for diagnostic purposes.
+     */
+    comments: string;
+    /**
+     * Company that produced the file—for example, Microsoft Corporation or Standard Microsystems Corporation, Inc. This string is required.
+     */
+    company: string;
+    /**
+     * File description to be presented to users. This string may be displayed in a list box when the user is choosing files to install. For example, Keyboard Driver for AT-Style Keyboards. This string is required.
+     */
+    fileDescription: string;
+    /**
+     * Version number of the file. For example, 3.10 or 5.00.RC2. This string is required.
+     */
+    fileVersion: string;
+    /**
+     * The path to the icon file. It should be a .ico file.
+     */
+    icon: string;
+    /**
+     * Internal name of the file, if one exists—for example, a module name if the file is a dynamic-link library. If the file has no internal name, this string should be the original filename, without extension. This string is required.
+     */
+    internalName: string;
+    /**
+     * Copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on. This string is optional.
+     */
+    legalCopyright: string;
+    /**
+     * Trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. This string is optional.
+     */
+    legalTrademark: string;
+    /**
+     * Original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.
+     */
+    originalFilename: string;
+    /**
+     * Information about a private version of the file—for example, Built by TESTER1 on \\TESTBED. This string should be present only if VS_FF_PRIVATEBUILD is specified in the fileflags parameter of the root block.
+     */
+    privateBuild: string;
+    /**
+     * Name of the product with which the file is distributed. This string is required.
+     */
+    productName: string;
+    /**
+     * Version of the product with which the file is distributed—for example, 3.10 or 5.00.RC2. This string is required.
+     */
+    productVersion: string;
+    /**
+     * Text that specifies how this version of the file differs from the standard version—for example, Private build for TESTER1 solving mouse problems on M250 and M250E computers. This string should be present only if VS_FF_SPECIALBUILD is specified in the fileflags parameter of the root block.
+     */
+    specialBuild: string;
+    /**
+     * Language identifier (LCID) of the file, defined by Microsoft, see: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
+     */
+    languageCode: number;
+};
+export type BuildOptions = {
+    /**
+     * Runtime version
+     */
+    version?: string | "latest" | "stable" | "lts";
+    /**
+     * Build flavor
+     */
+    flavor?: "normal" | "sdk";
+    /**
+     * Target platform
+     */
+    platform?: "linux" | "osx" | "win";
+    /**
+     * Target arch
+     */
+    arch?: "ia32" | "x64" | "arm64";
+    /**
+     * Versions manifest URI, https or file path
+     */
+    manifestUrl?: string;
+    /**
+     * Source directory
+     */
+    srcDir?: string;
+    /**
+     * Cache directory
+     */
+    cacheDir?: string;
+    /**
+     * Out directory
+     */
+    outDir?: string;
+    /**
+     * Platform specific rc
+     */
+    app?: LinuxRc | WinRc | OsxRc;
+    /**
+     * File globbing
+     */
+    glob?: boolean;
+    /**
+     * Manage manifest
+     */
+    managedManifest?: boolean | string | object;
+    /**
+     * Compress built artifacts
+     */
+    zip?: boolean | "zip" | "tar" | "tgz";
+    /**
+     * Version specific release metadata.
+     */
+    releaseInfo?: object;
+};
+/**
+ * References:
+ * https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html
+ * @typedef  {object}   LinuxRc               Linux configuration options
+ * @property {string}   name                  Name of the application
+ * @property {string}   genericName           Generic name of the application
+ * @property {boolean}  noDisplay             If true the application is not displayed
+ * @property {string}   comment               Tooltip for the entry, for example "View sites on the Internet".
+ * @property {string}   icon                  Icon to display in file manager, menus, etc.
+ * @property {boolean}  hidden                TBD
+ * @property {string[]} onlyShowIn            A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+ * @property {string[]} notShowIn             A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+ * @property {boolean}  dBusActivatable       A boolean value specifying if D-Bus activation is supported for this application
+ * @property {string}   tryExec               Path to an executable file on disk used to determine if the program is actually installed
+ * @property {string}   exec                  Program to execute, possibly with arguments.
+ * @property {string}   path                  If entry is of type Application, the working directory to run the program in.
+ * @property {boolean}  terminal              Whether the program runs in a terminal window.
+ * @property {string[]} actions               Identifiers for application actions.
+ * @property {string[]} mimeType              The MIME type(s) supported by this application.
+ * @property {string[]} categories            Categories in which the entry should be shown in a menu
+ * @property {string[]} implements            A list of interfaces that this application implements.
+ * @property {string[]} keywords              A list of strings which may be used in addition to other metadata to describe this entry.
+ * @property {boolean}  startupNotify         If true, it is KNOWN that the application will send a "remove" message when started with the DESKTOP_STARTUP_ID environment variable set. If false, it is KNOWN that the application does not work with startup notification at all.
+ * @property {string}   startupWMClass        If specified, it is known that the application will map at least one window with the given string as its WM class or WM name hin
+ * @property {boolean}  prefersNonDefaultGPU  If true, the application prefers to be run on a more powerful discrete GPU if available.
+ * @property {string}   singleMainWindow      If true, the application has a single main window, and does not support having an additional one opened.
+ */
+/**
+ * References:
+ * https://developer.apple.com/documentation/bundleresources/information_property_list
+ * @typedef  {object} OsxRc                           OSX resource configuration options
+ * @property {string} name                            The name of the application
+ * @property {string} icon                            The path to the icon file. It should be a .icns file.
+ * @property {string} LSApplicationCategoryType       The category that best describes your app for the App Store.
+ * @property {string} CFBundleIdentifier              A unique identifier for a bundle usually in reverse DNS format.
+ * @property {string} CFBundleName                    A user-visible short name for the bundle.
+ * @property {string} CFBundleDisplayName             The user-visible name for the bundle.
+ * @property {string} CFBundleSpokenName              A replacement for the app name in text-to-speech operations.
+ * @property {string} CFBundleVersion                 The version of the build that identifies an iteration of the bundle.
+ * @property {string} CFBundleShortVersionString      The release or version number of the bundle.
+ * @property {string} NSHumanReadableCopyright        A human-readable copyright notice for the bundle.
+ * @property {string} NSLocalNetworkUsageDescription  A human-readable description of why the application needs access to the local network.
+ * @property {boolean} LSFileQuarantineEnabled        Whether the app is subject to Gatekeeper file quarantine. See https://github.com/nwjs/nw.js/issues/7646
+ */
+/**
+ * References:
+ * https://learn.microsoft.com/en-us/windows/win32/msi/version
+ * https://learn.microsoft.com/en-gb/windows/win32/sbscs/application-manifests
+ * https://learn.microsoft.com/en-us/visualstudio/deployment/trustinfo-element-clickonce-application?view=vs-2022#requestedexecutionlevel
+ * https://learn.microsoft.com/en-gb/windows/win32/menurc/versioninfo-resource
+ * @typedef {object} WinRc              Windows configuration options. More info
+ * @property {string} name              The name of the application
+ * @property {string} version           The version of the application
+ * @property {string} comments          Additional information that should be displayed for diagnostic purposes.
+ * @property {string} company           Company that produced the file—for example, Microsoft Corporation or Standard Microsystems Corporation, Inc. This string is required.
+ * @property {string} fileDescription   File description to be presented to users. This string may be displayed in a list box when the user is choosing files to install. For example, Keyboard Driver for AT-Style Keyboards. This string is required.
+ * @property {string} fileVersion       Version number of the file. For example, 3.10 or 5.00.RC2. This string is required.
+ * @property {string} icon              The path to the icon file. It should be a .ico file.
+ * @property {string} internalName      Internal name of the file, if one exists—for example, a module name if the file is a dynamic-link library. If the file has no internal name, this string should be the original filename, without extension. This string is required.
+ * @property {string} legalCopyright    Copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on. This string is optional.
+ * @property {string} legalTrademark    Trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. This string is optional.
+ * @property {string} originalFilename  Original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.
+ * @property {string} privateBuild      Information about a private version of the file—for example, Built by TESTER1 on \\TESTBED. This string should be present only if VS_FF_PRIVATEBUILD is specified in the fileflags parameter of the root block.
+ * @property {string} productName       Name of the product with which the file is distributed. This string is required.
+ * @property {string} productVersion    Version of the product with which the file is distributed—for example, 3.10 or 5.00.RC2. This string is required.
+ * @property {string} specialBuild      Text that specifies how this version of the file differs from the standard version—for example, Private build for TESTER1 solving mouse problems on M250 and M250E computers. This string should be present only if VS_FF_SPECIALBUILD is specified in the fileflags parameter of the root block.
+ * @property {number} languageCode      Language identifier (LCID) of the file, defined by Microsoft, see: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
+ */
+/**
+ * @typedef {object} BuildOptions
+ * @property {string | "latest" | "stable" | "lts"} [version = "latest"]                        Runtime version
+ * @property {"normal" | "sdk"}                     [flavor = "normal"]                         Build flavor
+ * @property {"linux" | "osx" | "win"}              [platform]                                  Target platform
+ * @property {"ia32" | "x64" | "arm64"}             [arch]                                      Target arch
+ * @property {string}                               [manifestUrl = "https://nwjs.io/versions.json"] Versions manifest URI, https or file path
+ * @property {string}                               [srcDir = "./src"]                          Source directory
+ * @property {string}                               [cacheDir = "./cache"]                      Cache directory
+ * @property {string}                               [outDir = "./out"]                          Out directory
+ * @property {LinuxRc | WinRc | OsxRc}              [app]                                       Platform specific rc
+ * @property {boolean}                              [glob = true]                               File globbing
+ * @property {boolean | string | object}            [managedManifest = false]                   Manage manifest
+ * @property {boolean | "zip" | "tar" | "tgz"}      [zip = false]                               Compress built artifacts
+ * @property {object}                               [releaseInfo = {}]                          Version specific release metadata.
+ */
+/**
+ * Build NW.js application.
+ * @async
+ * @function
+ * @param  {BuildOptions}  options  - Build options
+ * @returns {Promise<void>}
+ */
+declare function build({ version, flavor, platform, arch, srcDir, cacheDir, outDir, app, glob, managedManifest, zip, releaseInfo, }: BuildOptions): Promise<void>;
+export default build;

package/types/osx.d.ts

@@ -0,0 +1,15 @@
+/**
+ *
+ * @param {object} options              - Options.
+ * @param {string} options.version      - NW.js version.
+ * @param {import("./main.js").OsxRc} options.app - Application configuration.
+ * @param {string} options.outDir       - Output directory.
+ * @param {any} options.releaseInfo     - Release information, shaped by https://nwjs.io/versions.json.
+ * @returns {Promise<void>}             - Promise.
+ */
+export default function setOsxConfig({ version, app, outDir, releaseInfo, }: {
+    version: string;
+    app: import("./main.js").OsxRc;
+    outDir: string;
+    releaseInfo: any;
+}): Promise<void>;

package/types/util.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Glob files.
+ * @async
+ * @function
+ * @param  {object}            options         - glob file options
+ * @param  {string | string[]} options.srcDir  - app src dir
+ * @param  {boolean}           options.glob    - glob flag
+ * @returns {Promise<string[] | string>}        - Returns array of file paths, or `srcDir` as-is when `glob` is false
+ */
+declare function globFiles({ srcDir, glob }: {
+    srcDir: string | string[];
+    glob: boolean;
+}): Promise<string[] | string>;
+declare const _default: {
+    PLATFORM_KV: {
+        darwin: string;
+        linux: string;
+        win32: string;
+    };
+    ARCH_KV: {
+        x64: string;
+        ia32: string;
+        arm64: string;
+    };
+    globFiles: typeof globFiles;
+};
+export default _default;