Merge branch 'nativefier:master' into gh-pages

.dockerignore

@@ -0,0 +1,56 @@
+# git
+.git*
+
+# OSX
+.DS_Store
+
+# Node.js
+
+# ignore compiled lib files
+lib/*
+app/lib/*
+built-tests
+dist
+app/dist
+
+# Docs
+docs
+*.md
+
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://docs.npmjs.com/misc/faq#should-i-check-my-node-modules-folder-into-git
+node_modules
+app/node_modules
+
+# IntelliJ project files
+.idea
+*.iml
+out
+gen
+
+.vscode

.editorconfig

@@ -0,0 +1,27 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+# Matches multiple files with brace expansion notation
+# Set default charset
+[*.{js,py}]
+charset = utf-8
+indent_style = space
+indent_size = 2
+
+# 2 space indentation
+[*.{html,css,less,scss,yml,json}]
+indent_style = space
+indent_size = 2
+
+# Tab indentation (no size specified)
+[Makefile]
+indent_style = tab
+
+trim_trailing_whitespace = true

.env

@@ -0,0 +1 @@
+PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

.github/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Nativefier
+
+## Issues
+
+Please include the following in your new issue:
+
+- Version of Nativefier (run `$ nativefier --version`)
+- Version of Node.js (run `$ node --version`)
+- Command line parameters
+- OS and architecture you are running Nativefier from
+- Stack trace from the error message (if any)
+- Instructions to reproduce the issue
+
+## Pull Requests
+
+See [here](https://github.com/nativefier/nativefier/blob/master/HACKING.md) for instructions on how to set up a development environment.
+
+We follow the [Airbnb Style Guide](https://github.com/airbnb/javascript), please make sure tests and lints pass when you submit your pull request. 
+
+The following commands might be helpful:
+
+```bash
+# Run specs only
+npm run test
+
+# Run linter only
+npm run lint
+```
+
+Thank you so much for your contribution!

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,93 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report 🙂! Help us help you, **fill this form thoroughly**. An incomplete bug report is a useless bug report.
+  - type: checkboxes
+    id: homework
+    attributes:
+      label: Homework
+      options:
+        - label: I took the time to write a good, descriptive issue title
+          required: true
+        - label: I read `nativefier --help` and [API.md](https://github.com/nativefier/nativefier/blob/master/API.md).
+          required: true
+        - label: I checked [CATALOG.md](https://github.com/nativefier/nativefier/blob/master/CATALOG.md) for community suggestions & workarounds.
+          required: true
+        - label: I searched [existing issues, open & closed](https://github.com/nativefier/nativefier/issues?q=is%3Aissue). Yes, my bug is new.
+          required: true
+        - label: I'm running the [latest version](https://github.com/nativefier/nativefier/releases).
+          required: true
+  - type: input
+    id: nativefier-command
+    attributes:
+      label: Nativefier command
+      description: "Your ***full*** nativefier command, on a ***public*** site."
+      placeholder: nativefier --verbose --some-option https://mysite.com
+    validations:
+      required: true
+  - type: textarea
+    id: steps-to-repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. I did this...
+        2. And then that...
+        3. Finally, I clicked here.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      placeholder: What you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual behavior
+      placeholder: What happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: debug-info
+    attributes:
+      label: Debug info
+      placeholder: |
+        - Logs of your full build command, with the `--verbose` flag. Put them in a ```code block``` !
+        - If the bug happens at app run time, the in-app DevTools console logs (open it with F12)
+        - Error messages, screenshots, screencasts, anything relevant!
+    validations:
+      required: false
+  - type: input
+    id: nativefier-version
+    attributes:
+      label: Nativefier version
+      placeholder: "nativefier --version"
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: "node --version"
+    validations:
+      required: true
+  - type: input
+    id: npm-version
+    attributes:
+      label: npm version
+      placeholder: "npm --version"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "For example: Windows 10 build 1809"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,45 @@
+name: Feature request
+description: Suggest an idea for Nativefier
+labels: ["feature-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this feature request 🙂! Help us help you, **fill this form thoroughly**. An incomplete feature request is a useless feature request.
+  - type: checkboxes
+    id: homework
+    attributes:
+      label: Homework
+      options:
+        - label: I took the time to write a good, descriptive issue title
+          required: true
+        - label: I read `nativefier --help` and [API.md](https://github.com/nativefier/nativefier/blob/master/API.md), no existing option fits my needs.
+          required: true
+        - label: I checked [CATALOG.md](https://github.com/nativefier/nativefier/blob/master/CATALOG.md) for community suggestions & workarounds.
+          required: true
+        - label: I searched [existing issues, open & closed](https://github.com/nativefier/nativefier/issues?q=is%3Aissue). Yes, my feature request is new.
+          required: true
+        - label: I'm running the [latest version](https://github.com/nativefier/nativefier/releases). Yes, the feature I'm requesting isn't in it.
+          required: true
+    validations:
+      required: true
+  - type: textarea
+    id: problem-statement
+    attributes:
+      label: Problem statement
+      description: A clear and concise description of what your feature would be.
+      placeholder: |
+        For example:
+        Nativefier should XYZ, ... details details details...
+        Existing option --something is not what I want, because ...
+    validations:
+      required: true
+  - type: textarea
+    id: motivation-and-context
+    attributes:
+      label: Motivation & context
+      placeholder: |
+        What makes you want this feature?
+        Where does it come from?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,78 @@
+name: Question
+description: Ask for help
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report 🙂! Help us help you, **fill this form thoroughly**. A cryptic question is a question unlikely to be answered.
+  - type: checkboxes
+    id: homework
+    attributes:
+      label: Homework
+      options:
+        - label: I took the time to write a good, descriptive issue title
+          required: true
+        - label: I read `nativefier --help` and [API.md](https://github.com/nativefier/nativefier/blob/master/API.md).
+          required: true
+        - label: I checked [CATALOG.md](https://github.com/nativefier/nativefier/blob/master/CATALOG.md) for community suggestions & workarounds.
+          required: true
+        - label: I searched [existing issues, open & closed](https://github.com/nativefier/nativefier/issues?q=is%3Aissue). Yes, my question is new.
+          required: true
+        - label: I'm running the [latest version](https://github.com/nativefier/nativefier/releases).
+          required: true
+    validations:
+      required: false
+  - type: textarea
+    id: question
+    attributes:
+      label: Your question
+      description: Your question, expressed clearly and concisely.
+    validations:
+      required: true
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to reproduce
+      description: "If you already have a Nativefier command you're struggling with, paste ***full*** nativefier command and its logs, with the ***`--verbose` flag***, on a ***public*** site:"
+      value: |
+        ```
+        nativefier --verbose --some-option https://mysite.com
+        <paste your verbose build logs, if relevant to your question>
+        ```
+    validations:
+      required: false
+  - type: textarea
+    id: debug-info
+    attributes:
+      label: Debug info
+      placeholder: |
+        Error messages, screenshots, screencasts, anything relevant!
+  - type: input
+    id: nativefier-version
+    attributes:
+      label: Nativefier version
+      placeholder: "nativefier --version"
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: "node --version"
+    validations:
+      required: true
+  - type: input
+    id: npm-version
+    attributes:
+      label: npm version
+      placeholder: "npm --version"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "For example: Windows 10 build 1809"
+    validations:
+      required: true

.github/generate-changelog

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+
+# Updates the changelog and version in the package.json
+# Will also create a commit with these changes locally
+#
+# Usage:
+# ./.github/generate-changelog -- "7.0.0"
+#
+# Prerequisites:
+# - On master branch
+# - No uncommitted changes
+#
+# Dependencies:
+# - git-extras: https://github.com/tj/git-extras/blob/master/Installation.md
+# - jq: https://stedolan.github.io/jq/download/
+
+set -eo pipefail
+
+echo 'HEY YOU. Before you release, here is a report of outdated dependencies.'
+echo ' - Red upgrades fulfill semver and do *not* need any action'
+echo ' - Yellow upgrades *do* need looking at changelogs for breaking changes, and updating package.json'
+echo
+echo 'CLI:'
+npm out || true
+echo
+echo 'App:'
+cd app; npm out || true; cd ..
+echo
+echo 'Okay with this, or care to do/plan a few upgrades?'
+echo 'Press any key to continue, or Ctrl+C to abort'
+read -r
+
+echo 'HEY YOU, again. Did you run the quick pre-release smoke test? ( npm run test:manual )'
+echo 'Press any key to continue, or Ctrl+C to abort'
+read -r
+
+# Checks if we are on the master branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [[ "$BRANCH" != 'master' ]]; then
+  echo 'ERROR: not on master branch' >&2
+  exit 1;
+fi
+
+# Checks if there are uncommitted changes
+git diff-index --quiet HEAD -- || (echo 'ERROR: there are uncommitted changes' >&2 && exit 1)
+
+VERSION="$1"
+
+# Validates the $VERSION
+SEMVER_REGEX='^([0-9]+\.){2}([0-9]+)$'
+if ! [[ $VERSION =~ $SEMVER_REGEX ]]; then
+ echo "ERROR: Version '$VERSION' is invalid " >&2
+ exit 1
+fi
+
+# 1. Update the version in the package.json
+cat package.json | jq ".version = \"$VERSION\"" > package.json.tmp
+mv package.json.tmp package.json  # workaround for in-place jq editing
+
+# 2. Compile new commits from CHANGELOG.md, and open it in your EDITOR for cleanup
+git changelog CHANGELOG.md --tag "$VERSION"
+
+# 3. Commit the changes
+git add CHANGELOG.md
+git add package.json
+git commit -m "Update changelog for \`v$VERSION\`"
+
+# 4. Create an annotated tag
+git tag -a "v$VERSION" -m "v$VERSION"
+
+# 5. List remaining work
+echo
+echo 'Please verify commit & tag look fine in Git, then:'
+echo ' 1. Push:  git push --follow-tags origin master'
+echo ' 2. Create a GitHub Release at https://github.com/nativefier/nativefier/releases ,'
+echo "    using created tag v$VERSION and with title \"Nativefier v$VERSION\" (yes, with a \"v\")."
+echo
+echo 'GitHub Action "publish" will react on the new release, and publish it to npm.'
+echo 'The new version will be visible on npm within a few minutes/hours.'

.github/manual-test

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Manual test to validate some hard-to-programmatically-test features work.
+set -eo pipefail
+
+missingDeps=false
+if ! command -v mktemp > /dev/null; then echo "Missing mktemp"; missingDeps=true; fi
+if ! command -v uname > /dev/null; then echo "Missing uname"; missingDeps=true; fi
+if ! command -v node > /dev/null; then echo "Missing node"; missingDeps=true; fi
+if [ "$missingDeps" = true ]; then exit 1; fi
+
+function launch_app() {
+  printf '\n*** Running app\n'
+  if [ "$(uname -s)" = "Darwin" ]; then
+    open -a "$1/$2-darwin-x64/$2.app"
+  elif [ "$(uname -o)" = "Msys" ]; then
+    "$1/$2-win32-x64/$2.exe"
+  else
+    "$1/$2-linux-x64/$2"
+  fi
+}
+
+function do_cleanup() {
+  if [ -n "$1" ]; then
+    printf '\n***** Deleting test dir %s *****\n' "$1"
+    rm -rf "$1"
+    printf '\n'
+  fi
+}
+
+function request_feedback() {
+  printf '\nDid everything work as expected? [yN] '
+  read -r response
+
+  do_cleanup "$1"
+
+  if [ "$response" != 'y' ]; then
+    echo "Back to fixing"
+    exit 1
+  fi
+  echo "Yayyyyyyyyyyy"
+}
+
+printf "\n***** SMOKE TEST 1: Setting up test and building app... *****\n"
+script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+nativefier_dir="$script_dir/.."
+pushd "$nativefier_dir"
+tmp_dir=$(mktemp -d -t nativefier-manual-test-XXXXX)
+name="nativefier-smoke-test-1"
+resources_dir="$tmp_dir/resources"
+mkdir "$resources_dir"
+injected_css="$resources_dir/inject.css"
+injected_js="$resources_dir/inject.js"
+echo '* { background-color: blue; }' > "$injected_css"
+echo 'alert("hello world from inject");' > "$injected_js"
+
+node ./lib/cli.js 'https://npmjs.com/' \
+  --inject "$injected_css" \
+  --inject "$injected_js" \
+  --name "$name" \
+  "$tmp_dir"
+
+printf '\n***** SMOKE TEST 1: Test checklist *****
+- Context menu -> Open Link In New Window works
+- MAC ONLY: Context menu -> Open Link In New Tab works
+- Keyboard shortcuts: {back, forward, zoom in/out/zero} work
+- Console: no Electron runtime deprecation warnings/error logged'
+launch_app "$tmp_dir" "$name"
+request_feedback "$tmp_dir"
+
+# ------------------------------------------------------------------------------
+
+printf '\n***** SMOKE TEST 2: Setting up test and building app... *****\n'
+tmp_dir=$(mktemp -d -t nativefier-manual-test-tray-XXXXX)
+name='nativefier-smoke-test-2'
+node ./lib/cli.js 'https://google.com/' \
+  --name "$name" \
+  --tray \
+  "$tmp_dir"
+
+printf '\n***** SMOKE TEST 2: Test checklist *****
+- Should have an app with a tray icon
+- Console: no Electron runtime deprecation warnings/error logged'
+
+launch_app "$tmp_dir" "$name"
+request_feedback "$tmp_dir"
+
+# ------------------------------------------------------------------------------
+
+printf '\n***** SMOKE TEST 3: Setting up test and building app... *****\n'
+tmp_dir=$(mktemp -d -t nativefier-manual-test-start-in-tray-XXXXX)
+name='nativefier-smoke-test-3'
+node ./lib/cli.js 'https://google.com/' \
+  --name "$name" \
+  --tray start-in-tray \
+  "$tmp_dir"
+
+printf '\n***** SMOKE TEST 3: Test checklist *****
+- Should have an app that does not show a window initially,
+  but will have a tray icon that will show the window.
+- Console: no Electron runtime deprecation warnings/error logged'
+
+launch_app "$tmp_dir" "$name"
+request_feedback "$tmp_dir"
+
+# ------------------------------------------------------------------------------
+
+printf '\n***** SMOKE TEST 4: Setting up test and building app... *****\n'
+tmp_dir=$(mktemp -d -t nativefier-manual-test-get-media-devices)
+name='nativefier-smoke-test-4'
+node ./lib/cli.js 'https://meet.jit.si/nativefier-test' \
+  --name "$name" \
+  "$tmp_dir"
+
+printf '\n***** SMOKE TEST 4: Test checklist *****
+- Join the Jitsi meeting and try to share your screen
+  (third button from the left in the bottom bar)
+- An overlay should appear where you can select a screen/window to share
+  This presently does not work in MacOS as you would have to give the app
+  "Screen Recording" permissions, but you can''t for an app in the temp directory.
+- After selecting a screen, a thumbnail of the shared screen should appear on
+  the top right
+- Console: no Electron runtime deprecation warnings/error logged'
+
+launch_app "$tmp_dir" "$name"
+request_feedback "$tmp_dir"

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+# - Bumping the *minimum* required Node version? You must bump:
+#   1. package.json -> engines.node
+#   2. package.json -> devDependencies.@types/node
+#   3. tsconfig.json -> {target, lib}
+#   4. .github/workflows/ci.yml -> node-version
+# - Bumping the *maximum* tested Node version? You must bump also: publish.yml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 20
+        uses: actions/setup-node@v2
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: |
+            npm-shrinkwrap.json
+            app/npm-shrinkwrap.json
+            package-lock.json
+            app/package-lock.json
+      - env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        run: npm ci --no-fund # Will also (via `prepare` hook): 1. install ./app, 2. build
+      - run: npm run lint
+  playwright:
+    runs-on: windows-latest # Doesn't work on headless ubuntu, and is slow on mac
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 20
+        uses: actions/setup-node@v2
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: |
+            npm-shrinkwrap.json
+            app/npm-shrinkwrap.json
+            package-lock.json
+            app/package-lock.json
+      - env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        run: npm ci --no-fund # Will also (via `prepare` hook): 1. install ./app, 2. build
+      - run: npm run test:playwright
+        timeout-minutes: 5
+        # Useful to debug PlayWright tests failing in CI
+        # env:
+        #   DEBUG: pw:browser*
+  tests:
+    strategy:
+      matrix:
+        node-version:
+          - '20'
+          - '16' # the oldest we require in package.json -> engines.node, to check we run on this minimum
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          cache-dependency-path: |
+            npm-shrinkwrap.json
+            app/npm-shrinkwrap.json
+            package-lock.json
+            app/package-lock.json
+      - env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        run: npm ci --no-fund # Will also (via `prepare` hook): 1. install ./app, 2. build
+      - run: npm run test:noplaywright

.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: publish
+on:
+  release:
+    types:
+      - created
+jobs:
+  playwright:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2 # Setup .npmrc file to publish to npm
+        with:
+          node-version: '20' # Align the version of Node here with ci.yml.
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci --no-fund # Will also (via `prepare` hook): 1. install ./app, 2. build
+      - run: npm run test:playwright
+        timeout-minutes: 5
+
+  build:
+    needs: playwright
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2 # Setup .npmrc file to publish to npm
+        with:
+          node-version: '20' # Align the version of Node here with ci.yml.
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci --no-fund # Will also (via `prepare` hook): 1. install ./app, 2. build
+      - run: npm run test:noplaywright
+      - run: npm run lint
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  docker:
+    needs: [ playwright, build ]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build Docker image
+        run: docker build . --file Dockerfile --tag "nativefier/nativefier:latest"
+      - name: Login to Docker Hub
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Tag and push Docker image
+        run: |
+          docker tag "nativefier/nativefier:latest" "nativefier/nativefier:${GITHUB_REF_NAME}"
+          docker push "nativefier/nativefier:latest"
+          docker push "nativefier/nativefier:${GITHUB_REF_NAME}"

.gitignore

@@ -0,0 +1,67 @@
+# OSX
+.DS_Store
+
+# ignore compiled lib files
+lib*
+app/lib/*
+app/dist/*
+built-tests
+
+# commit a placeholder to keep the app/lib directory
+app/inject
+!app/inject/_placeholder
+!app/lib/.placeholder
+
+dist
+package-lock.json
+app/package-lock.json
+
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://docs.npmjs.com/misc/faq#should-i-check-my-node-modules-folder-into-git
+node_modules
+
+# Python virtual environment in case it's created for the Castlabs code signing tool
+venv
+
+# IntelliJ project files
+.idea
+*.iml
+.run
+out
+gen
+
+# Builds when testing npm pack
+nativefier*.tgz
+
+.vscode
+
+# https://github.com/nektos/act
+.actrc
+
+tsconfig.tsbuildinfo
+scripts

.npmignore

@@ -0,0 +1,23 @@
+/*
+!lib/
+!icon-scripts
+!npm-shrinkwrap.json
+.DS_Store
+src/
+*eslintrc.js
+*eslintrc.yml
+*tsconfig.tsbuildinfo
+*tsconfig.json
+*jestSetupFiles*
+*-test.js
+*-test.js.map
+*.test.d.ts
+*.test.js
+*.test.js.map
+app/*
+!app/lib/
+!app/inject/
+!app/nativefier.json
+!app/package.json
+!app/npm-shrinkwrap.json
+.vscode/

.npmrc

@@ -0,0 +1 @@
+package-lock=false

.nvmrc

@@ -0,0 +1 @@
+16

CATALOG.md

@@ -0,0 +1,300 @@
+# Build Commands Catalog
+
+Below you'll find a list of build commands contributed by the Nativefier community. They are here as examples, to help you nativefy "complicated" apps that need a bit of elbow grease to work. We need your help to enrich it, as long as you follow these two guidelines:
+
+1. Only add sites that require something special! No need to document here that `simplesite.com` works with a simple `nativefier simplesite.com` 🙂.
+2. Please add commands with the _strict necessary_ to make an app work. For example,
+   - Yes to mention that `--widevine` or some `--browserwindow-options` are necessary...
+   - ... but don't add other flags that are pure personal preference (e.g. `--disable-dev-tools` or `--disk-cache-size`).
+
+---
+
+## General recipes
+
+### Videos don’t play
+
+Some sites like [HBO Max](https://github.com/nativefier/nativefier/issues/1153) and [Udemy](https://github.com/nativefier/nativefier/issues/1147) host videos using [DRM](https://en.wikipedia.org/wiki/Digital_rights_management).
+
+For those, try passing the [`--widevine`](API.md#widevine) option.
+
+### Settings cached between app rebuilds
+
+You might be surprised to see settings persist after rebuilding your app.
+This occurs because the app cache lives separately from the app.
+
+Try deleting your app's cache, found at `<your_app_name_lower_case>-nativefier-<random_id>` in your OS’s "App Data" directory (Linux: `$XDG_CONFIG_HOME` or `~/.config` , MacOS: `~/Library/Application Support/` , Windows: `%APPDATA%` or `C:\Users\yourprofile\AppData\Roaming`)
+
+### Window size and position
+
+This allows the last set window size and position to be remembered and applied
+after your app is restarted. Note: PR welcome for a built-in fix for that :) .
+
+```sh
+nativefier 'https://open.google.com/'
+  --inject window.js
+```
+
+Note: [Inject](https://github.com/nativefier/nativefier/blob/master/API.md#inject)
+the following javascript as `windows.js` to prevent the window size and position to reset.
+```javascript
+function storeWindowPos() {
+  window.localStorage.setItem('windowX', window.screenX);
+  window.localStorage.setItem('windowY', window.screenY);
+}
+window.moveTo(window.localStorage.getItem('windowX'), window.localStorage.getItem('windowY'));
+setInterval(storeWindowPos, 250);
+```
+
+---
+
+## Site-specific recipes
+
+### Google apps
+
+Lying about the User Agent is required, else Google Login will notice your
+"Chrome" isn't a real Chrome, and will: 1. Refuse login, 2. Break notifications.
+
+This example documents Google Sheets, but is applicable to other Google apps,
+e.g. Google Calendar, GMail, etc. If `firefox` doesn’t work, try `safari` .
+
+```sh
+nativefier 'https://docs.google.com/spreadsheets' \
+  --user-agent firefox
+```
+
+### Outlook
+
+```sh
+nativefier 'https://outlook.office.com/mail'
+  --internal-urls '.*?(outlook.live.com|outlook.office365.com).*?'
+  --file-download-options '{"saveAs": true}'
+  --browserwindow-options '{"webPreferences": { "webviewTag": true, "nodeIntegration": true, "nodeIntegrationInSubFrames": true } }'
+```
+
+Note: `--browserwindow-options` is needed to allow pop-outs when creating/editing an email.
+
+### Udemy
+
+```sh
+nativefier 'https://www.udemy.com/'
+  --internal-urls '.*?udemy.*?'
+  --file-download-options '{"saveAs": true}'
+  --widevine
+```
+
+Note: most videos will work, but to play some DRMed videos you must pass `--widevine` AND [sign the app](https://github.com/nativefier/nativefier/issues/1147#issuecomment-828750362).
+
+### HBO Max
+
+```sh
+nativefier 'https://play.hbomax.com/'
+  --widevine
+  --enable-es3-apis
+&& python -m castlabs_evs.vmp sign-pkg 'name_of_the_generated_hbo_app'
+```
+
+Note: as for Udemy, `--widevine` + [app signing](https://github.com/nativefier/nativefier/issues/1147#issuecomment-828750362) is necessary.
+
+### WhatsApp
+
+```sh
+nativefier 'https://web.whatsapp.com/'
+  --inject whatsapp.js
+```
+
+With this `--inject` in `whatsapp.js` (and maybe more, see [#1112](https://github.com/nativefier/nativefier/issues/1112)):
+
+```javascript
+if ('serviceWorker' in navigator) {
+  caches.keys().then(function (cacheNames) {
+    cacheNames.forEach(function (cacheName) {
+      caches.delete(cacheName);
+    });
+  });
+}
+```
+
+Another option to see WhatsApp or WhatsApp Business more macOS-like (macos only):
+
+```sh
+nativefier https://web.whatsapp.com --name 'WhatsApp Business' --counter true --darwin-dark-mode-support true --title-bar-style hidden --inject whatsappmacos.css
+```
+
+with this `whatsappmacos.css` to make the window draggable, and move the user avatar to the right:
+```css
+header > div:first-child {
+    flex: 0 0 auto;
+    margin-right: 15px;
+}
+div#app > div.os-mac > span:first-child {
+    position: fixed;
+    top: 0;
+    z-index: 1000;
+    width: 100%;
+    height: 59px;
+    pointer-events: none;
+    -webkit-app-region: drag;
+}
+```
+
+### Spotify
+
+```sh
+nativefier 'https://open.spotify.com/'
+  --widevine
+  --inject spotify.js
+  --inject spotify.css
+```
+
+Notes:
+
+- You might have to pass `--user-agent firefox` to circumvent Spotify's detection that your browser isn't a real Chrome. But [maybe not](https://github.com/nativefier/nativefier/issues/1195#issuecomment-855003776).
+- [Inject](https://github.com/nativefier/nativefier/blob/master/API.md#inject) the following javascript as `spotify.js` to prevent "Unsupported Browser" messages.
+
+```javascript
+function dontShowBrowserNoticePage() {
+  const browserNotice = document.getElementById('browser-support-notice');
+  console.log({ browserNotice });
+  if (browserNotice) {
+    // When Spotify displays the browser notice, it's not just the notice,
+    // but the entire page is focused on not allowing you to proceed.
+    // So in this case, we hide the body element (so nothing shows)
+    // until our JS deletes the service worker and reload (which will actually load the player)
+    document.getElementsByTagName('body')[0].style.display = 'none';
+  }
+}
+
+function reload() {
+  window.location.href = window.location.href;
+}
+
+function nukeWorkers() {
+  dontShowBrowserNoticePage();
+  if ('serviceWorker' in navigator) {
+    caches.keys().then(function (cacheNames) {
+      cacheNames.forEach(function (cacheName) {
+        console.debug('Deleting cache', cacheName);
+        caches.delete(cacheName);
+      });
+    });
+    navigator.serviceWorker.getRegistrations().then((registrations) => {
+      registrations.forEach((worker) =>
+        worker
+          .unregister()
+          .then((u) => {
+            console.debug('Unregistered worker', worker);
+            reload();
+          })
+          .catch((e) =>
+            console.error('Unable to unregister worker', error, { worker }),
+          ),
+      );
+    });
+  }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  nukeWorkers();
+});
+
+if (document.readyState === 'interactive') {
+  nukeWorkers();
+}
+```
+
+- It is also required to [sign the app](https://github.com/nativefier/nativefier/blob/master/API.md#widevine), or many songs will not play.
+- To hide all download links (as if you were in the actual app), [inject](https://github.com/nativefier/nativefier/blob/master/API.md#inject) the following CSS as `spotify.css`:
+
+```css
+a[href='/download'] {
+  display: none;
+}
+```
+
+
+### Notion
+
+You can use Notion pages with Nativefier without much hassle, but Notion itself does not present an easy way to use HTML buttons. As such, if you want to use Notion Pages as a quick way to make dashboards and interactive panels, you will be restricted to only plain links and standard components. 
+
+With Nativefier you can now extend Notion's functionality and possibilities by adding HTML buttons that can call other javascript functions, since it enables you to inject custom Javascript and CSS.
+
+```sh
+nativefier 'YOUR_NOTION_PAGE_SHARE_URL'
+  --inject notion.js
+  --inject notion.css
+```
+
+Notes:
+
+- You can inject the notion.js and notion.css files by copying them to the resources/app/inject folder of your nativefier app.
+- In your Notion page, use [notionbutton]BUTTON_TEXT|BUTTON_ACTION[/notionbutton], where BUTTON_TEXT is the text contained in your button and BUTTON_ACTION is the action which will be called in your JS function.
+```javascript
+/* notion.js */
+
+// First, we replace all placeholders in our Notion page to add our interactive buttons to it.
+window.onload = 
+  setTimeout(function(){
+    let htmlCode = document.body.getElementsByTagName("*");
+    for (let i = 0; i <= htmlCode.length; i++) {
+      if(htmlCode[i] && htmlCode[i].innerHTML){
+        let match = htmlCode[i].innerHTML.match(/\[notionbutton\]([\s\S]*?)\[\/notionbutton\]/);
+        if (match && typeof match == 'object'){
+          let btnarray = match['1'].split("|");
+          let btn_text = btnarray[0];
+          let btn_action = btnarray[1];
+          htmlCode[i].innerHTML = htmlCode[i].innerHTML.replace(match['0'], "<button class=\"btn-notion\" btnaction=\"" + btn_action + "\"  >"+btn_text+"</button>");
+        }
+      }
+    }
+    let buttons = document.querySelectorAll(".btn-notion");
+    for (let j=0; j <= buttons.length; j++){
+      if(buttons[j].hasAttribute("btnaction")){
+        buttons[j].onclick = function () { runAction(buttons[j].getAttribute("btnaction")) };
+      }
+    }
+  }, 3000);
+
+// And then we define your action below, according to our needs
+function runAction(action) {
+    switch(action){
+      case '1':
+        alert('Nice One!');
+        break;
+      default:
+        alert('Hello World!');
+    }
+}
+```
+
+After that, set your css file as follows:
+```css
+.notion-topbar{ /* hiding notion's default navigation bar for a more "app" feeling */
+  display:none; 
+}
+.btn-notion{ /* defining some style for our buttons */
+  background-color:#FFC300;
+  color: #333333;
+}
+.notion-selectable.notion-page-block.notion-collection-item span{
+  pointer-events: auto !important; /* notion prevents clicks on items inside databases. Use this to remove that. */
+}
+```
+
+### Microsoft Teams
+
+You can get an almost macOS look-alike using this:
+
+```sh
+nativefier https://teams.microsoft.com --name 'Microsoft Teams' --counter true --darwin-dark-mode-support true --title-bar-style hidden --internal-urls "(.*)" --inject teamsapp.css
+```
+Note that the `--internal-urls` argument is necessary to login.
+
+Inject the following `teamsapp.css` file to hide the download button at the bottom left and the Office 365 apps waffle button at the top left:
+```css
+get-app-button.ts-sym.app-bar-link {
+    display: none;
+}
+button#ts-waffle-button {
+    display: none;
+}
+```

Dockerfile

@@ -0,0 +1,55 @@
+FROM --platform=linux/amd64 node:lts-alpine
+LABEL description="Alpine image to build Nativefier apps"
+
+
+# Install dependencies and cleanup extraneous files
+RUN apk update \
+    && apk add bash wine imagemagick dos2unix \
+    && rm -rf /var/cache/apk/* \
+    && mkdir /nativefier && chown node:node /nativefier
+
+# Use node (1000) as default user not root
+USER node
+
+ENV NPM_PACKAGES="/home/node/npm-packages"
+ENV PATH="$PATH:$NPM_PACKAGES/bin"
+ENV MANPATH="$MANPATH:$NPM_PACKAGES/share/man"
+
+# Setup a global packages location for "node" user so we can npm link
+RUN mkdir $NPM_PACKAGES \
+    && npm config set prefix $NPM_PACKAGES
+
+WORKDIR /nativefier
+
+# Add sources with node as the owner so that it has the power it needs to build in /nativefier
+COPY --chown=node:node . .
+
+# Fix line endings that may have gotten mangled in Windows
+RUN find ./icon-scripts ./src ./app -type f -print0 | xargs -0 dos2unix
+
+# Link (which will install and build)
+# Run tests (to ensure we don't Docker build & publish broken stuff)
+# Cleanup leftover files in this step to not waste Docker layer space
+# Make sure nativefier is executable
+RUN npm i \
+    && npm link \
+    && npm run test:noplaywright \
+    && rm -rf /tmp/nativefier* ~/.npm/_cacache ~/.cache/electron \
+    && chmod +x $NPM_PACKAGES/bin/nativefier
+
+# Run a {lin,mac,win} build
+# 1. to check installation was sucessful
+# 2. to cache electron distributables and avoid downloads at runtime
+# Also delete generated apps so they don't get added to the Docker layer
+# !Important! The `rm -rf` command must be in the same `RUN` command (using an `&&`), to not waste Docker layer space
+RUN nativefier https://github.com/nativefier/nativefier /tmp/nativefier \
+    && nativefier -p osx https://github.com/nativefier/nativefier /tmp/nativefier \
+    && nativefier -p windows https://github.com/nativefier/nativefier /tmp/nativefier \
+    && rm -rf /tmp/nativefier
+
+
+RUN echo Generated Electron cache size: $(du -sh ~/.cache/electron) \
+    && echo Final image size: $(du -sh / 2>/dev/null)
+
+ENTRYPOINT ["nativefier"]
+CMD ["--help"]

HACKING.md

@@ -0,0 +1,255 @@
+# Development Guide
+
+Welcome, soon-to-be contributor 🙂! This document sums up
+what you need to know to get started hacking on Nativefier.
+
+## Guidelines
+
+1. **Before starting work on a huge change, gauge the interest**
+   of community & maintainers through a GitHub issue. For big changes,
+   create a **[RFC](https://en.wikipedia.org/wiki/Request_for_Comments)**
+   issue to enable a good peer review.
+
+2. Do your best to **avoid adding new Nativefier command-line options**.
+   If a new option is inevitable for what you want to do, sure,
+   but as much as possible try to see if you change works without.
+   Nativefier already has a ton of them, making it hard to use.
+
+3. Do your best to **limit breaking changes**.
+   Only introduce breaking changes when necessary, when required by deps, or when
+   not breaking would be unreasonable. When you can, support the old thing forever.
+   For example, keep maintaining old flags; to "replace" an flag you want to replace
+   with a better version, you should keep honoring the old flag, and massage it
+   to pass parameters to the new flag, maybe using a wrapper/adapter.
+   Yes, our code will get a tiny bit uglier than it could have been with a hard
+   breaking change, but that would be to ignore our users.
+   Introducing breaking changes willy nilly is a comfort to us developers, but is
+   disrespectful to end users who must constantly bend to the flow of breaking changes
+   pushed by _all their software_ who think it's "just one breaking change".
+   See [Rich Hickey - Spec-ulation](https://www.youtube.com/watch?v=oyLBGkS5ICk).
+
+4. **Avoid adding npm dependencies**. Each new dep is a complexity & security liability.
+   You might be thinking your extra dep is _"just a little extra dep"_, and maybe
+   you found one that is high-quality & dependency-less. Still, it's an extra dep,
+   and over the life of Nativefier we requested changes to _dozens_ of PRs to avoid
+   "just a little extra dep". Without this constant attention, Nativefier would be
+   more bloated, less stable for users, more annoying to maintainers. Now, don't go
+   rewriting zlib if you need a zlib dep, for sure use a dep. But if you can write a
+   little helper function saving us a dep for a mundane task, go for the helper :) .
+   Also, an in-tree helper will always be less complex than a dep, as inherently
+   more tailored to our use case, and less complexity is good.
+
+5. Use **types**, avoid `any`, write **tests**.
+
+6. **Document for users** in `API.md`
+
+7. **Document for other devs** in comments, jsdoc, commits, PRs.
+   Say _why_ more than _what_, the _what_ is your code!
+
+## Setup
+
+First, clone the project:
+
+```bash
+git clone https://github.com/nativefier/nativefier.git
+cd nativefier
+```
+
+Install dependencies (for both the CLI and the Electron app):
+
+```bash
+npm ci
+```
+
+The above `npm ci` will build automatically (through the `prepare` hook).
+When you need to re-build Nativefier,
+
+```bash
+npm run build
+```
+
+Set up a symbolic link so that running `nativefier` calls your dev version with your changes:
+
+```bash
+npm link
+which nativefier
+# -> Should return a path, e.g. /home/youruser/.node_modules/lib/node_modules/nativefier
+# If not, be sure your `npm_config_prefix` env var is set and in your `PATH`
+```
+
+After doing so, you can run Nativefier with your test parameters:
+
+```bash
+nativefier --your-awesome-new-flag 'https://your-test-site.com'
+```
+
+Then run your nativefier app _through the command line too_ (to see logs & errors):
+
+```bash
+# Under Linux
+./your-test-site-linux-x64/your-test-site
+
+# Under Windows
+your-test-site-win32-x64/your-test-site.exe
+
+# Under macOS
+./YourTestSite-darwin-x64/YourTestSite.app/Contents/MacOS/YourTestSite --verbose
+```
+
+## Linting & formatting
+
+Nativefier uses [Prettier](https://prettier.io/), which will shout at you for
+not formatting code exactly like it expects. This guarantees a homogenous style,
+but is painful to do manually. Do yourself a favor and install a
+[Prettier plugin for your editor](https://prettier.io/docs/en/editors.html).
+
+## Tests
+
+- To run all tests, `npm t`
+- To run only unit tests, `npm run test:unit`
+- To run only integration tests, `npm run test:integration`
+- Logging is suppressed by default in tests, to avoid polluting Jest output.
+  To get debug logs, `npm run test:withlog` or set the `LOGLEVEL` env. var.
+- For a good live experience, open two terminal panes/tabs running code/tests watchers:
+  1. Run a TSC watcher: `npm run build:watch`
+  2. Run a Jest unit tests watcher: `npm run test:watch`
+  3. Here is [a screencast of how the live-reload experience should look like](https://user-images.githubusercontent.com/522085/120407694-abdf3f00-c31b-11eb-9ab5-a531a929adb9.mp4)
+- Alternatively, you can run both test processes in the same terminal by running: `npm run watch`
+
+## Maintainers corner
+
+### Deps: major-upgrading Electron
+
+When a new major [Electron release](https://github.com/electron/electron/releases) occurs,
+
+1. Wait a few weeks to let it stabilize. Never upgrade Nativefier to a `.0.0`.
+2. Thoroughly digest the new version's [breaking changes](https://www.electronjs.org/docs/breaking-changes)
+   (also via the [Releases page](https://github.com/electron/electron/releases) and [the blog](https://www.electronjs.org/blog/), the content is different),
+   grepping our codebase for every changed API.
+   - If called for by the breaking changes, perform the necessary API changes
+3. Bump
+   - `src/constants.ts` / `DEFAULT_ELECTRON_VERSION` & `DEFAULT_CHROME_VERSION`
+   - `package.json / devDeps / electron`
+   - `app / package.json / devDeps / electron`
+4. On Windows, macOS, Linux, test for regression and crashes:
+   1. With `npm test` and `npm run test:manual`
+   2. With extra manual testing
+5. When confident enough, release it in a regression-spelunking-friendly way:
+   1. If `master` has unreleased commits, make a patch/minor release with them, but without the major Electron bump.
+   2. Commit your Electron major bump and release it as a major new Nativefier version. Help users identify the breaking change by using a bold **[BREAKING]** marker in `CHANGELOG.md` and in the GitHub release.
+
+### Deps updates
+
+It is important to stay afloat of dependencies upgrades.
+In packages ecosystems like npm, there's only one way: forward.
+The best time to do package upgrades is now / progressively, because:
+
+1. Slacking on doing these upgrades means you stay behind, and it becomes
+   risky to do them. Upgrading a woefully out-of-date dep from 3.x to 9.x is
+   scarier than 3.x to 4.x, release, then 4.x to 5.x, release, etc... to 9.x.
+
+2. Also, dependencies applying security patches to old major versions are rare
+   in npm. So, by slacking on upgrades, it becomes more and more probable that
+   we get impacted by a vulnerability. And when this happens, it then becomes
+   urgent & stressful to A. fix the vulnerability, B. do the required major upgrades.
+
+So: do upgrade CLI & App deps regularly! Our release script will remind you about it.
+
+### Deps lockfile / shrinkwrap
+
+We do use lockfiles (`npm-shrinkwrap.json` & `app/npm-shrinkwrap.json`), for:
+
+1. Security (avoiding supply chain attacks)
+2. Reproducibility
+3. Performance
+
+It means you might have to update these lockfiles when adding a dependency.
+`npm run relock` will help you with that.
+
+Note: we do use `npm-shrinkwrap.json` rather than `package-lock.json` because
+the latter is tailored to libraries, and is not publishable.
+As [documented](https://docs.npmjs.com/cli/v6/configuring-npm/shrinkwrap-json),
+CLI tools like Nativefier should use shrinkwrap.
+
+### Release
+
+While on `master`, with no uncommitted changes, run:
+
+```bash
+npm run changelog -- $VERSION
+# With no 'v'. For example: npm run changelog -- '42.5.0'
+```
+
+Do follow semantic versioning, and give visibility to breaking changes
+in release notes by prefixing their line with **[BREAKING]**.
+
+### Triage
+
+These are the guidelines we (try to) follow when triaging [issues](https://github.com/nativefier/nativefier/issues):
+
+1. Do your best to conciliate **empathy & efficiency, and keep your cool**.
+   It’s not always easy 😄😬😭🤬. Get away from triaging if you feel grouchy.
+
+2. **Rename** issues. Most issues are badly named, with titles ranging from
+   unclear to flat out wrong. A good backlog is a backlog of issues with clear
+   concise titles, understandable with only the title after you read them once.
+   Rename and clarify.
+
+3. **Ask for clarification & details** when needed, and add a `need-info` label.
+
+   1. In particular, if the issue isn’t reproducible (e.g. a non-trivial bug
+      happening on an internal site), express that we can’t work without a
+      repro scenario, and flag as `need-info`.
+
+4. **Label** issues with _category/sorting_ labels (e.g. `mac` / `linux` / `windows`,
+   `bug` / `feature-request` ...) and _status_ labels (e.g. `upstream`, `wontfix`,
+   `need-info`, `cannot-reproduce`).
+
+5. **Close if needed, but not too much**. We _do_ want to close what deserves it,
+   but closing _too_ ruthlessly frustrates and disappoints users, and does us a
+   disservice of not having a clear honest backlog available to us & users. So,
+
+   1. When in doubt, leave issues open and triaged as `bug` / `feature-request`.
+      It’s okay, reaching 0 open issues is _not_ an objective. Or if it is,
+      it deserves to be a development objective, not a triage one.
+   2. That being said, do close what’s `upstream`, with a kind message.
+   3. Also do close bugs that have been `need-info` or `cannot-reproduce` for
+      too long (weeks / months), with a kind message explaining we’re okay to
+      re-open if the requested info / scenario is provided.
+   4. Finally, carefully close issues we do not want to address, e.g. requests
+      going against project goals, or bugs & feature requests that are so niche
+      or far-fetched that there’s zero chance of ever seeing them addressed.
+      But if in doubt, remain at point 1. above: leave open, renamed, labelled.
+
+6. **Close duplicates issues** and link to the original issue.
+
+   1. To be able to notice dups implies you must know the backlog (one more
+      reason to keep it tidy and palatable). Once in a blue moon, do a
+      "full pass" of the whole backlog from beginning to end, you’ll often
+      find lots of now-irrelevant bugs, and duplicates.
+
+7. **Use [GitHub saved replies](https://github.com/settings/replies)** to
+   automate asking for info and being nice on closing as noanswer / stale-needinfo.
+
+8. **Transform findings stemming from issues discussion** into documentation
+   (chiefly, [CATALOG.md](CATALOG.md) & [API.md](API.md)), or into code comments.
+
+9. **Don’t scold authors of lame "+1" comments**, this only adds to the noise
+   you’re trying to avoid. Instead, hide useless comments as `Off-topic`.
+   From personal experience, users do understand this signal, and such hidden
+   comments do avoid an avalanche of extra "+1" comments.
+
+   1. There are shades of lame. A literal `"+1"` comment is frankly useless and
+      is worth hiding. But a comment like `"same for me on Windows"` at least
+      brings an extra bit of information, so can remain visible.
+
+   2. In a perfect world, GitHub would let us add a note when hiding comments to
+      express _"Please use a 👍 reaction on the issue to vote for it instead of_
+      _posting a +1 comment"_. In a perfecter world, GitHub would use their AI
+      skillz to automatically detect such comments, discourage them and nudge
+      towards a 👍 reaction. We’re not there yet, so “hidden as off-topic” will do.
+
+10. **Don’t let yourself be abused** by abrasive / entitled users. There are
+    plenty of articles documenting open-source burnout and trolls-induced misery.
+    Find an article that speaks to you, and point problematic users to it.
+    I like [Brett Cannon - The social contract of open source](https://snarky.ca/the-social-contract-of-open-source/).

LICENSE.md

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2016` `Goh Jia Hao`
+
+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 the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,101 @@
+Note: Nativefier is unmaintained, please see https://github.com/nativefier/nativefier/issues/1577.
+
+# Nativefier
+
+![Example of Nativefier app in the macOS dock](.github/dock-screenshot.png)
+
+You want to make a native-looking wrapper for WhatsApp Web (or any web page).
+
+```bash
+nativefier 'web.whatsapp.com'
+```
+
+![Walkthrough animation](.github/nativefier-walkthrough.gif)
+
+You're done.
+
+## Introduction
+
+Nativefier is a command-line tool to easily create a “desktop app” for any web site
+with minimal fuss. Apps are wrapped by [Electron](https://www.electronjs.org/)
+(which uses Chromium under the hood) in an OS executable (`.app`, `.exe`, etc)
+usable on Windows, macOS and Linux.
+
+I built this because I grew tired of having to Alt-Tab to my browser and then search
+through numerous open tabs when using Messenger or
+Whatsapp Web ([HN thread](https://news.ycombinator.com/item?id=10930718)). Nativefier features:
+
+- Automatically retrieval of app icon / name
+- Injection of custom JS & CSS
+- Many more, see the [API docs](API.md) or `nativefier --help`
+
+## Installation
+
+Install Nativefier globally with `npm install -g nativefier` . Requirements:
+
+- macOS 10.13+ / Windows / Linux
+- [Node.js](https://nodejs.org/) ≥ 16.9 and npm ≥ 7.10
+
+Optional dependencies:
+
+- [ImageMagick](http://www.imagemagick.org/) or [GraphicsMagick](http://www.graphicsmagick.org/) to convert icons.
+  Be sure `convert` + `identify` or `gm` are in your `$PATH`.
+- [Wine](https://www.winehq.org/) to build Windows apps from non-Windows platforms.
+  Be sure `wine` is in your `$PATH`.
+
+<details>
+  <summary>Or install with Docker (click to expand)</summary>
+
+  - Pull the image from [Docker Hub](https://hub.docker.com/r/nativefier/nativefier): `docker pull nativefier/nativefier`
+  - ... or build it yourself: `docker build -t local/nativefier .`
+    (in this case, replace `nativefier/` in the below examples with `local/`)
+
+  By default, `nativefier --help` will be executed.
+  To build e.g. a Gmail app into `~/nativefier-apps`,
+
+  ```bash
+  docker run --rm -v ~/nativefier-apps:/target/ nativefier/nativefier https://mail.google.com/ /target/
+  ```
+
+  You can pass Nativefier flags, and mount volumes to pass local files. E.g. to use an icon,
+
+  ```bash
+  docker run --rm -v ~/my-icons-folder/:/src -v $TARGET-PATH:/target nativefier/nativefier --icon /src/icon.png --name whatsApp -p linux -a x64 https://web.whatsapp.com/ /target/
+  ```
+</details>
+
+<details>
+  <summary>Or install with Snap & AUR (click to expand)</summary>
+
+  These repos are *not* managed by Nativefier maintainers; use at your own risk.
+  If using them, for your security, please inspect the build script.
+
+  - [Snap](https://snapcraft.io/nativefier)
+  - [AUR](https://aur.archlinux.org/packages/nodejs-nativefier)
+</details>
+
+## Usage
+
+To create an app for medium.com, simply `nativefier 'medium.com'`
+
+Nativefier will try to determine the app name, and well as other options that you
+can override. For example, to override the name, `nativefier --name 'My Medium App' 'medium.com'`
+
+**Read the [API docs](API.md) or run `nativefier --help`**
+to learn about command-line flags and configure your app.
+
+## Troubleshooting
+
+**See [CATALOG.md](CATALOG.md) for site-specific ideas & workarounds contributed by the community**.
+
+If this doesn’t help, go look at our [issue tracker](https://github.com/nativefier/nativefier/issues).
+
+## Development
+
+Help welcome on [bugs](https://github.com/nativefier/nativefier/issues?q=is%3Aopen+is%3Aissue+label%3Abug) and
+[feature requests](https://github.com/nativefier/nativefier/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request)!
+
+Docs: [Developer / build / hacking](HACKING.md), [API / flags](API.md),
+[Changelog](CHANGELOG.md).
+
+License: [MIT](LICENSE.md).

app/.eslintrc.js

@@ -0,0 +1,21 @@
+const base = require('../base-eslintrc');
+
+// # https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md
+module.exports = {
+  parser: base.parser,
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+  },
+  plugins: base.plugins,
+  extends: base.extends,
+  rules: base.rules,
+  // https://eslint.org/docs/user-guide/configuring/ignoring-code#ignorepatterns-in-config-files
+  ignorePatterns: [
+    'node_modules/**',
+    'lib/**',
+    'dist/**',
+    'built-tests/**',
+    'coverage/**',
+  ],
+};

app/nativefier.json

@@ -0,0 +1,8 @@
+{
+  "name": "Google",
+  "targetUrl": "http://google.com",
+  "badge": false,
+  "width": 1280,
+  "height": 800,
+  "showMenuBar": false
+}

app/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "nativefier-placeholder",
+  "version": "1.0.0",
+  "description": "Placeholder for the nativefier cli to override with a target url",
+  "main": "lib/main.js",
+  "author": "Jia Hao",
+  "license": "MIT",
+  "keywords": [
+    "desktop",
+    "electron",
+    "placeholder"
+  ],
+  "scripts": {},
+  "dependencies": {
+    "electron-context-menu": "^3.6.1",
+    "electron-dl": "^3.5.0",
+    "electron-squirrel-startup": "^1.0.0",
+    "electron-window-state": "^5.0.3",
+    "loglevel": "^1.8.1",
+    "source-map-support": "^0.5.21"
+  },
+  "devDependencies": {
+    "electron": "^25.7.0"
+  }
+}

app/src/components/contextMenu.ts

@@ -0,0 +1,84 @@
+import {
+  BrowserWindow,
+  ContextMenuParams,
+  Event as ElectronEvent,
+} from 'electron';
+import contextMenu from 'electron-context-menu';
+
+import { nativeTabsSupported, openExternal } from '../helpers/helpers';
+import * as log from '../helpers/loggingHelper';
+import { setupNativefierWindow } from '../helpers/windowEvents';
+import { createNewWindow } from '../helpers/windowHelpers';
+import {
+  OutputOptions,
+  outputOptionsToWindowOptions,
+} from '../../../shared/src/options/model';
+
+export function initContextMenu(
+  options: OutputOptions,
+  window?: BrowserWindow,
+): void {
+  log.debug('initContextMenu');
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  contextMenu({
+    prepend: (actions: contextMenu.Actions, params: ContextMenuParams) => {
+      log.debug('contextMenu.prepend', { actions, params });
+      const items = [];
+      if (params.linkURL && window) {
+        items.push({
+          label: 'Open Link in Default Browser',
+          click: () => {
+            openExternal(params.linkURL).catch((err) =>
+              log.error('contextMenu Open Link in Default Browser ERROR', err),
+            );
+          },
+        });
+        items.push({
+          label: 'Open Link in New Window',
+          click: () =>
+            createNewWindow(
+              outputOptionsToWindowOptions(options, nativeTabsSupported()),
+              setupNativefierWindow,
+              params.linkURL,
+              // window,
+            ),
+        });
+        if (nativeTabsSupported()) {
+          items.push({
+            label: 'Open Link in New Tab',
+            click: () =>
+              // // Fire a new window event for a foreground tab
+              // // Previously we called createNewTab directly, but it had incosistent and buggy behavior
+              // // as it was mostly designed for running off of events. So this will create a new event
+              // // for a foreground-tab for the event handler to grab and take care of instead.
+              // (window as BrowserWindow).webContents.emit(
+              //   // event name
+              //   'new-window',
+              //   // event object
+              //   {
+              //     // Leave to the default for a NewWindowWebContentsEvent
+              //     newGuest: undefined,
+              //     ...new Event('new-window'),
+              //   }, // as NewWindowWebContentsEvent,
+              //   // url
+              //   params.linkURL,
+              //   // frameName
+              //   window?.webContents.mainFrame.name ?? '',
+              //   // disposition
+              //   'foreground-tab',
+              // ),
+              window.emit('new-window-for-tab', {
+                ...new Event('new-window-for-tab'),
+                url: params.linkURL,
+              } as ElectronEvent<{ url: string }>),
+          });
+        }
+      }
+      return items;
+    },
+    showCopyImage: true,
+    showCopyImageAddress: true,
+    showSaveImage: true,
+  });
+}

app/src/components/loginWindow.ts

@@ -0,0 +1,39 @@
+import * as path from 'path';
+
+import { BrowserWindow, ipcMain } from 'electron';
+
+import * as log from '../helpers/loggingHelper';
+import { nativeTabsSupported } from '../helpers/helpers';
+
+export async function createLoginWindow(
+  loginCallback: (username?: string, password?: string) => void,
+  parent?: BrowserWindow,
+): Promise<BrowserWindow> {
+  log.debug('createLoginWindow', {
+    loginCallback,
+    parent,
+  });
+
+  const loginWindow = new BrowserWindow({
+    parent: nativeTabsSupported() ? undefined : parent,
+    width: 300,
+    height: 400,
+    frame: false,
+    resizable: false,
+    webPreferences: {
+      nodeIntegration: true, // TODO work around this; insecure
+      contextIsolation: false, // https://github.com/electron/electron/issues/28017
+      sandbox: false, // https://www.electronjs.org/blog/electron-20-0#default-changed-renderers-without-nodeintegration-true-are-sandboxed-by-default
+    },
+  });
+  await loginWindow.loadURL(
+    `file://${path.join(__dirname, 'static/login.html')}`,
+  );
+
+  ipcMain.once('login-message', (event, usernameAndPassword: string[]) => {
+    log.debug('login-message', { event, username: usernameAndPassword[0] });
+    loginCallback(usernameAndPassword[0], usernameAndPassword[1]);
+    loginWindow.close();
+  });
+  return loginWindow;
+}

app/src/components/mainWindow.ts

@@ -0,0 +1,336 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import {
+  desktopCapturer,
+  ipcMain,
+  BrowserWindow,
+  Event,
+  HandlerDetails,
+} from 'electron';
+import windowStateKeeper from 'electron-window-state';
+
+import { initContextMenu } from './contextMenu';
+import { createMenu } from './menu';
+import {
+  getAppIcon,
+  getCounterValue,
+  isOSX,
+  nativeTabsSupported,
+} from '../helpers/helpers';
+import * as log from '../helpers/loggingHelper';
+import { IS_PLAYWRIGHT } from '../helpers/playwrightHelpers';
+import { onNewWindow, setupNativefierWindow } from '../helpers/windowEvents';
+import {
+  clearCache,
+  createNewTab,
+  getDefaultWindowOptions,
+  hideWindow,
+} from '../helpers/windowHelpers';
+import {
+  OutputOptions,
+  outputOptionsToWindowOptions,
+} from '../../../shared/src/options/model';
+
+export const APP_ARGS_FILE_PATH = path.join(__dirname, '..', 'nativefier.json');
+
+type SessionInteractionRequest = {
+  id?: string;
+  func?: string;
+  funcArgs?: unknown[];
+  property?: string;
+  propertyValue?: unknown;
+};
+
+type SessionInteractionResult<T = unknown> = {
+  id?: string;
+  value?: T | Promise<T>;
+  error?: Error;
+};
+
+/**
+ * @param {{}} nativefierOptions AppArgs from nativefier.json
+ * @param {function} setDockBadge
+ */
+export async function createMainWindow(
+  nativefierOptions: OutputOptions,
+  setDockBadge: (value: number | string, bounce?: boolean) => void,
+): Promise<BrowserWindow> {
+  const options = { ...nativefierOptions };
+
+  const mainWindowState = windowStateKeeper({
+    defaultWidth: options.width || 1280,
+    defaultHeight: options.height || 800,
+  });
+
+  const mainWindow = new BrowserWindow({
+    frame: !options.hideWindowFrame,
+    width: mainWindowState.width,
+    height: mainWindowState.height,
+    minWidth: options.minWidth,
+    minHeight: options.minHeight,
+    maxWidth: options.maxWidth,
+    maxHeight: options.maxHeight,
+    x: options.x,
+    y: options.y,
+    autoHideMenuBar: !options.showMenuBar,
+    icon: getAppIcon(),
+    fullscreen: options.fullScreen,
+    // Whether the window should always stay on top of other windows. Default is false.
+    alwaysOnTop: options.alwaysOnTop,
+    titleBarStyle: options.titleBarStyle ?? 'default',
+    // Maximize window visual glitch on Windows fix
+    // We want a consistent behavior on all OSes, but Windows needs help to not glitch.
+    // So, we manually mainWindow.show() later, see a few lines below
+    show: options.tray !== 'start-in-tray' && process.platform !== 'win32',
+    backgroundColor: options.backgroundColor,
+    ...getDefaultWindowOptions(
+      outputOptionsToWindowOptions(options, nativeTabsSupported()),
+    ),
+  });
+
+  // Just load about:blank to start, gives playwright something to latch onto initially for testing.
+  if (IS_PLAYWRIGHT) {
+    await mainWindow.loadURL('about:blank');
+  }
+
+  mainWindowState.manage(mainWindow);
+
+  // after first run, no longer force maximize to be true
+  if (options.maximize) {
+    mainWindow.maximize();
+    options.maximize = undefined;
+    saveAppArgs(options);
+  }
+
+  if (options.tray === 'start-in-tray') {
+    mainWindow.hide();
+  } else if (process.platform === 'win32') {
+    // See other "Maximize window visual glitch on Windows fix" comment above.
+    mainWindow.show();
+  }
+
+  const windowOptions = outputOptionsToWindowOptions(
+    options,
+    nativeTabsSupported(),
+  );
+  createMenu(options, mainWindow);
+  createContextMenu(options, mainWindow);
+  setupNativefierWindow(windowOptions, mainWindow);
+
+  // Note it is important to add these handlers only to the *main* window,
+  // else we run into weird behavior like opening tabs twice
+  mainWindow.webContents.setWindowOpenHandler((details: HandlerDetails) => {
+    return onNewWindow(
+      windowOptions,
+      setupNativefierWindow,
+      details,
+      mainWindow,
+    );
+  });
+  mainWindow.on('new-window-for-tab', (event?: Event<{ url?: string }>) => {
+    log.debug('mainWindow.new-window-for-tab', { event });
+    createNewTab(
+      windowOptions,
+      setupNativefierWindow,
+      event?.url ?? options.targetUrl,
+      true,
+      // mainWindow,
+    );
+  });
+
+  if (options.counter) {
+    setupCounter(options, mainWindow, setDockBadge);
+  } else {
+    setupNotificationBadge(options, mainWindow, setDockBadge);
+  }
+
+  ipcMain.on('notification-click', () => {
+    log.debug('ipcMain.notification-click');
+    mainWindow.show();
+  });
+
+  setupSessionInteraction(mainWindow);
+  setupSessionPermissionHandler(mainWindow);
+
+  if (options.clearCache) {
+    await clearCache(mainWindow);
+  }
+
+  setupCloseEvent(options, mainWindow);
+
+  return mainWindow;
+}
+
+function createContextMenu(
+  options: OutputOptions,
+  window: BrowserWindow,
+): void {
+  if (!options.disableContextMenu) {
+    initContextMenu(options, window);
+  }
+}
+
+export function saveAppArgs(newAppArgs: OutputOptions): void {
+  try {
+    fs.writeFileSync(APP_ARGS_FILE_PATH, JSON.stringify(newAppArgs, null, 2));
+  } catch (err: unknown) {
+    log.warn(
+      `WARNING: Ignored nativefier.json rewrital (${(err as Error).message})`,
+    );
+  }
+}
+
+function setupCloseEvent(options: OutputOptions, window: BrowserWindow): void {
+  window.on('close', (event: Event) => {
+    log.debug('mainWindow.close', event);
+    if (window.isFullScreen()) {
+      if (nativeTabsSupported()) {
+        window.moveTabToNewWindow();
+      }
+      window.setFullScreen(false);
+      window.once('leave-full-screen', (event: Event) =>
+        hideWindow(
+          window,
+          event,
+          options.fastQuit ?? false,
+          options.tray ?? 'false',
+        ),
+      );
+    }
+    hideWindow(
+      window,
+      event,
+      options.fastQuit ?? false,
+      options.tray ?? 'false',
+    );
+
+    if (options.clearCache) {
+      clearCache(window).catch((err) => log.error('clearCache ERROR', err));
+    }
+  });
+}
+
+function setupCounter(
+  options: OutputOptions,
+  window: BrowserWindow,
+  setDockBadge: (value: number | string, bounce?: boolean) => void,
+): void {
+  window.on('page-title-updated', (event, title) => {
+    log.debug('mainWindow.page-title-updated', { event, title });
+    const counterValue = getCounterValue(title);
+    if (counterValue) {
+      setDockBadge(counterValue, options.bounce);
+    } else {
+      setDockBadge('');
+    }
+  });
+}
+
+function setupSessionPermissionHandler(window: BrowserWindow): void {
+  window.webContents.session.setPermissionCheckHandler(() => {
+    return true;
+  });
+  window.webContents.session.setPermissionRequestHandler(
+    (_webContents, _permission, callback) => {
+      callback(true);
+    },
+  );
+  ipcMain.handle('desktop-capturer-get-sources', () => {
+    return desktopCapturer.getSources({
+      types: ['screen', 'window'],
+    });
+  });
+}
+
+function setupNotificationBadge(
+  options: OutputOptions,
+  window: BrowserWindow,
+  setDockBadge: (value: number | string, bounce?: boolean) => void,
+): void {
+  ipcMain.on('notification', () => {
+    log.debug('ipcMain.notification');
+    if (!isOSX() || window.isFocused()) {
+      return;
+    }
+    setDockBadge('•', options.bounce);
+  });
+  window.on('focus', () => {
+    log.debug('mainWindow.focus');
+    setDockBadge('');
+  });
+}
+
+function setupSessionInteraction(window: BrowserWindow): void {
+  // See API.md / "Accessing The Electron Session"
+  ipcMain.on(
+    'session-interaction',
+    (event, request: SessionInteractionRequest) => {
+      log.debug('ipcMain.session-interaction', { event, request });
+
+      const result: SessionInteractionResult = { id: request.id };
+      let awaitingPromise = false;
+      try {
+        if (request.func !== undefined) {
+          // If no funcArgs provided, we'll just use an empty array
+          if (request.funcArgs === undefined || request.funcArgs === null) {
+            request.funcArgs = [];
+          }
+
+          // If funcArgs isn't an array, we'll be nice and make it a single item array
+          if (typeof request.funcArgs[Symbol.iterator] !== 'function') {
+            request.funcArgs = [request.funcArgs];
+          }
+
+          // Call func with funcArgs
+          // @ts-expect-error accessing a func by string name
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+          result.value = window.webContents.session[request.func](
+            ...request.funcArgs,
+          );
+
+          if (result.value !== undefined && result.value instanceof Promise) {
+            // This is a promise. We'll resolve it here otherwise it will blow up trying to serialize it in the reply
+            (result.value as Promise<unknown>)
+              .then((trueResultValue) => {
+                result.value = trueResultValue;
+                log.debug('ipcMain.session-interaction:result', result);
+                event.reply('session-interaction-reply', result);
+              })
+              .catch((err) =>
+                log.error('session-interaction ERROR', request, err),
+              );
+            awaitingPromise = true;
+          }
+        } else if (request.property !== undefined) {
+          if (request.propertyValue !== undefined) {
+            // Set the property
+            // @ts-expect-error setting a property by string name
+            window.webContents.session[request.property] =
+              request.propertyValue;
+          }
+
+          // Get the property value
+          // @ts-expect-error accessing a property by string name
+          result.value = window.webContents.session[request.property];
+        } else {
+          // Why even send the event if you're going to do this? You're just wasting time! ;)
+          throw new Error(
+            'Received neither a func nor a property in the request. Unable to process.',
+          );
+        }
+
+        // If we are awaiting a promise, that will return the reply instead, else
+        if (!awaitingPromise) {
+          log.debug('session-interaction:result', result);
+          event.reply('session-interaction-reply', result);
+        }
+      } catch (err: unknown) {
+        log.error('session-interaction:error', err, event, request);
+        result.error = err as Error;
+        result.value = undefined; // Clear out the value in case serializing the value is what got us into this mess in the first place
+        event.reply('session-interaction-reply', result);
+      }
+    },
+  );
+}

app/src/components/menu.test.ts

@@ -0,0 +1,167 @@
+import { BrowserWindow, MenuItemConstructorOptions } from 'electron';
+
+jest.mock('../helpers/helpers');
+import { isOSX } from '../helpers/helpers';
+import { generateMenu } from './menu';
+
+describe('generateMenu', () => {
+  let window: BrowserWindow;
+  const mockIsOSX: jest.SpyInstance = isOSX as jest.Mock;
+  let mockIsFullScreen: jest.SpyInstance;
+  let mockIsFullScreenable: jest.SpyInstance;
+  let mockIsSimpleFullScreen: jest.SpyInstance;
+  let mockSetFullScreen: jest.SpyInstance;
+  let mockSetSimpleFullScreen: jest.SpyInstance;
+
+  beforeEach(() => {
+    window = new BrowserWindow();
+    mockIsOSX.mockReset();
+    mockIsFullScreen = jest
+      .spyOn(window, 'isFullScreen')
+      .mockReturnValue(false);
+    mockIsFullScreenable = jest
+      .spyOn(window, 'isFullScreenable')
+      .mockReturnValue(true);
+    mockIsSimpleFullScreen = jest
+      .spyOn(window, 'isSimpleFullScreen')
+      .mockReturnValue(false);
+    mockSetFullScreen = jest.spyOn(window, 'setFullScreen');
+    mockSetSimpleFullScreen = jest.spyOn(window, 'setSimpleFullScreen');
+  });
+
+  afterAll(() => {
+    mockIsFullScreen.mockRestore();
+    mockIsFullScreenable.mockRestore();
+    mockIsSimpleFullScreen.mockRestore();
+    mockSetFullScreen.mockRestore();
+    mockSetSimpleFullScreen.mockRestore();
+  });
+
+  test('does not have fullscreen if not supported', () => {
+    mockIsOSX.mockReturnValue(false);
+    mockIsFullScreenable.mockReturnValue(false);
+
+    const menu = generateMenu(
+      {
+        nativefierVersion: '1.0.0',
+        zoom: 1.0,
+        disableDevTools: false,
+      },
+      window,
+    );
+
+    const editMenu = menu.filter((item) => item.label === '&View');
+
+    const fullscreen = (
+      editMenu[0].submenu as MenuItemConstructorOptions[]
+    ).filter((item) => item.label === 'Toggle Full Screen');
+
+    expect(fullscreen).toHaveLength(1);
+    expect(fullscreen[0].enabled).toBe(false);
+    expect(fullscreen[0].visible).toBe(false);
+
+    expect(mockIsOSX).toHaveBeenCalled();
+    expect(mockIsFullScreenable).toHaveBeenCalled();
+  });
+
+  test('has fullscreen no matter what on mac', () => {
+    mockIsOSX.mockReturnValue(true);
+    mockIsFullScreenable.mockReturnValue(false);
+
+    const menu = generateMenu(
+      {
+        nativefierVersion: '1.0.0',
+        zoom: 1.0,
+        disableDevTools: false,
+      },
+      window,
+    );
+
+    const editMenu = menu.filter((item) => item.label === '&View');
+
+    const fullscreen = (
+      editMenu[0].submenu as MenuItemConstructorOptions[]
+    ).filter((item) => item.label === 'Toggle Full Screen');
+
+    expect(fullscreen).toHaveLength(1);
+    expect(fullscreen[0].enabled).toBe(true);
+    expect(fullscreen[0].visible).toBe(true);
+
+    expect(mockIsOSX).toHaveBeenCalled();
+    expect(mockIsFullScreenable).toHaveBeenCalled();
+  });
+
+  test.each([true, false])(
+    'has a fullscreen menu item that toggles fullscreen',
+    (isFullScreen) => {
+      mockIsOSX.mockReturnValue(false);
+      mockIsFullScreenable.mockReturnValue(true);
+      mockIsFullScreen.mockReturnValue(isFullScreen);
+
+      const menu = generateMenu(
+        {
+          nativefierVersion: '1.0.0',
+          zoom: 1.0,
+          disableDevTools: false,
+        },
+        window,
+      );
+
+      const editMenu = menu.filter((item) => item.label === '&View');
+
+      const fullscreen = (
+        editMenu[0].submenu as MenuItemConstructorOptions[]
+      ).filter((item) => item.label === 'Toggle Full Screen');
+
+      expect(fullscreen).toHaveLength(1);
+      expect(fullscreen[0].enabled).toBe(true);
+      expect(fullscreen[0].visible).toBe(true);
+
+      expect(mockIsOSX).toHaveBeenCalled();
+      expect(mockIsFullScreenable).toHaveBeenCalled();
+
+      // @ts-expect-error click is here TypeScript...
+      fullscreen[0].click(null, window);
+
+      expect(mockSetFullScreen).toHaveBeenCalledWith(!isFullScreen);
+      expect(mockSetSimpleFullScreen).not.toHaveBeenCalled();
+    },
+  );
+
+  test.each([true, false])(
+    'has a fullscreen menu item that toggles simplefullscreen as a fallback on mac',
+    (isFullScreen) => {
+      mockIsOSX.mockReturnValue(true);
+      mockIsFullScreenable.mockReturnValue(false);
+      mockIsSimpleFullScreen.mockReturnValue(isFullScreen);
+
+      const menu = generateMenu(
+        {
+          nativefierVersion: '1.0.0',
+          zoom: 1.0,
+          disableDevTools: false,
+        },
+        window,
+      );
+
+      const editMenu = menu.filter((item) => item.label === '&View');
+
+      const fullscreen = (
+        editMenu[0].submenu as MenuItemConstructorOptions[]
+      ).filter((item) => item.label === 'Toggle Full Screen');
+
+      expect(fullscreen).toHaveLength(1);
+      expect(fullscreen[0].enabled).toBe(true);
+      expect(fullscreen[0].visible).toBe(true);
+
+      expect(mockIsOSX).toHaveBeenCalled();
+      expect(mockIsFullScreenable).toHaveBeenCalled();
+
+      // @ts-expect-error click is here TypeScript...
+      fullscreen[0].click(null, window);
+
+      expect(mockSetSimpleFullScreen).toHaveBeenCalledWith(!isFullScreen);
+      expect(mockSetFullScreen).not.toHaveBeenCalled();
+    },
+  );
+});

app/src/components/menu.ts

@@ -0,0 +1,424 @@
+import * as fs from 'fs';
+import path from 'path';
+
+import {
+  BrowserWindow,
+  clipboard,
+  Menu,
+  MenuItem,
+  MenuItemConstructorOptions,
+} from 'electron';
+
+import { cleanupPlainText, isOSX, openExternal } from '../helpers/helpers';
+import * as log from '../helpers/loggingHelper';
+import {
+  clearAppData,
+  getCurrentURL,
+  goBack,
+  goForward,
+  goToURL,
+  zoomIn,
+  zoomOut,
+  zoomReset,
+} from '../helpers/windowHelpers';
+import { OutputOptions } from '../../../shared/src/options/model';
+
+type BookmarksLink = {
+  type: 'link';
+  title: string;
+  url: string;
+  shortcut?: string;
+};
+
+type BookmarksSeparator = {
+  type: 'separator';
+};
+
+type BookmarkConfig = BookmarksLink | BookmarksSeparator;
+
+type BookmarksMenuConfig = {
+  menuLabel: string;
+  bookmarks: BookmarkConfig[];
+};
+
+export function createMenu(
+  options: OutputOptions,
+  mainWindow: BrowserWindow,
+): void {
+  log.debug('createMenu', { options });
+  const menuTemplate = generateMenu(options, mainWindow);
+
+  injectBookmarks(menuTemplate);
+
+  const menu = Menu.buildFromTemplate(menuTemplate);
+  Menu.setApplicationMenu(menu);
+}
+
+export function generateMenu(
+  options: {
+    disableDevTools: boolean;
+    nativefierVersion: string;
+    zoom?: number;
+  },
+  mainWindow: BrowserWindow,
+): MenuItemConstructorOptions[] {
+  const { nativefierVersion, zoom, disableDevTools } = options;
+  const zoomResetLabel =
+    !zoom || zoom === 1.0
+      ? 'Reset Zoom'
+      : `Reset Zoom (to ${(zoom * 100).toFixed(1)}%, set at build time)`;
+
+  const editMenu: MenuItemConstructorOptions = {
+    label: '&Edit',
+    submenu: [
+      {
+        label: 'Undo',
+        accelerator: 'CmdOrCtrl+Z',
+        role: 'undo',
+      },
+      {
+        label: 'Redo',
+        accelerator: 'Shift+CmdOrCtrl+Z',
+        role: 'redo',
+      },
+      {
+        type: 'separator',
+      },
+      {
+        label: 'Cut',
+        accelerator: 'CmdOrCtrl+X',
+        role: 'cut',
+      },
+      {
+        label: 'Copy',
+        accelerator: 'CmdOrCtrl+C',
+        role: 'copy',
+      },
+      {
+        label: 'Copy as Plain Text',
+        accelerator: 'CmdOrCtrl+Shift+C',
+        click: (): void => {
+          // We use clipboard.readText to strip down formatting
+          const text = clipboard.readText('selection');
+          clipboard.writeText(cleanupPlainText(text), 'clipboard');
+        },
+      },
+      {
+        label: 'Copy Current URL',
+        accelerator: 'CmdOrCtrl+L',
+        click: (): void => clipboard.writeText(getCurrentURL()),
+      },
+      {
+        label: 'Paste',
+        accelerator: 'CmdOrCtrl+V',
+        role: 'paste',
+      },
+      {
+        label: 'Paste and Match Style',
+        // https://github.com/nativefier/nativefier/issues/404
+        // Apple's HIG lists this shortcut for paste and match style
+        // https://support.apple.com/en-us/HT209651
+        accelerator: isOSX() ? 'Option+Shift+Cmd+V' : 'Ctrl+Shift+V',
+        role: 'pasteAndMatchStyle',
+      },
+      {
+        label: 'Select All',
+        accelerator: 'CmdOrCtrl+A',
+        role: 'selectAll',
+      },
+      {
+        label: 'Clear App Data',
+        click: (
+          item: MenuItem,
+          focusedWindow: BrowserWindow | undefined,
+        ): void => {
+          log.debug('Clear App Data.click', {
+            item,
+            focusedWindow,
+            mainWindow,
+          });
+          if (!focusedWindow) {
+            focusedWindow = mainWindow;
+          }
+          clearAppData(focusedWindow).catch((err) =>
+            log.error('clearAppData ERROR', err),
+          );
+        },
+      },
+    ],
+  };
+
+  const viewMenu: MenuItemConstructorOptions = {
+    label: '&View',
+    submenu: [
+      {
+        label: 'Back',
+        accelerator: isOSX() ? 'Cmd+Left' : 'Alt+Left',
+        click: goBack,
+      },
+      {
+        label: 'BackAdditionalShortcut',
+        visible: false,
+        acceleratorWorksWhenHidden: true,
+        accelerator: 'CmdOrCtrl+[', // What old versions of Nativefier used, kept for backwards compat
+        click: goBack,
+      },
+      {
+        label: 'Forward',
+        accelerator: isOSX() ? 'Cmd+Right' : 'Alt+Right',
+        click: goForward,
+      },
+      {
+        label: 'ForwardAdditionalShortcut',
+        visible: false,
+        acceleratorWorksWhenHidden: true,
+        accelerator: 'CmdOrCtrl+]', // What old versions of Nativefier used, kept for backwards compat
+        click: goForward,
+      },
+      {
+        label: 'Reload',
+        role: 'reload',
+      },
+      {
+        type: 'separator',
+      },
+      {
+        label: 'Toggle Full Screen',
+        accelerator: isOSX() ? 'Ctrl+Cmd+F' : 'F11',
+        enabled: mainWindow.isFullScreenable() || isOSX(),
+        visible: mainWindow.isFullScreenable() || isOSX(),
+        click: (
+          item: MenuItem,
+          focusedWindow: BrowserWindow | undefined,
+        ): void => {
+          log.debug('Toggle Full Screen.click()', {
+            item,
+            focusedWindow,
+            isFullScreen: focusedWindow?.isFullScreen(),
+            isFullScreenable: focusedWindow?.isFullScreenable(),
+          });
+          if (!focusedWindow) {
+            focusedWindow = mainWindow;
+          }
+          if (focusedWindow.isFullScreenable()) {
+            focusedWindow.setFullScreen(!focusedWindow.isFullScreen());
+          } else if (isOSX()) {
+            focusedWindow.setSimpleFullScreen(
+              !focusedWindow.isSimpleFullScreen(),
+            );
+          }
+        },
+      },
+      {
+        label: 'Zoom In',
+        accelerator: 'CmdOrCtrl+=',
+        click: zoomIn,
+      },
+      {
+        label: 'ZoomInAdditionalShortcut',
+        visible: false,
+        acceleratorWorksWhenHidden: true,
+        accelerator: 'CmdOrCtrl+numadd',
+        click: zoomIn,
+      },
+      {
+        label: 'Zoom Out',
+        accelerator: 'CmdOrCtrl+-',
+        click: zoomOut,
+      },
+      {
+        label: 'ZoomOutAdditionalShortcut',
+        visible: false,
+        acceleratorWorksWhenHidden: true,
+        accelerator: 'CmdOrCtrl+numsub',
+        click: zoomOut,
+      },
+      {
+        label: zoomResetLabel,
+        accelerator: 'CmdOrCtrl+0',
+        click: (): void => zoomReset(options),
+      },
+      {
+        label: 'ZoomResetAdditionalShortcut',
+        visible: false,
+        acceleratorWorksWhenHidden: true,
+        accelerator: 'CmdOrCtrl+num0',
+        click: (): void => zoomReset(options),
+      },
+    ],
+  };
+
+  if (!disableDevTools) {
+    (viewMenu.submenu as MenuItemConstructorOptions[]).push(
+      {
+        type: 'separator',
+      },
+      {
+        label: 'Toggle Developer Tools',
+        accelerator: isOSX() ? 'Alt+Cmd+I' : 'Ctrl+Shift+I',
+        click: (item: MenuItem, focusedWindow: BrowserWindow | undefined) => {
+          log.debug('Toggle Developer Tools.click()', { item, focusedWindow });
+          if (!focusedWindow) {
+            focusedWindow = mainWindow;
+          }
+          focusedWindow.webContents.toggleDevTools();
+        },
+      },
+    );
+  }
+
+  const windowMenu: MenuItemConstructorOptions = {
+    label: '&Window',
+    role: 'window',
+    submenu: [
+      {
+        label: 'Minimize',
+        accelerator: 'CmdOrCtrl+M',
+        role: 'minimize',
+      },
+      {
+        label: 'Close',
+        accelerator: 'CmdOrCtrl+W',
+        role: 'close',
+      },
+    ],
+  };
+
+  const helpMenu: MenuItemConstructorOptions = {
+    label: '&Help',
+    role: 'help',
+    submenu: [
+      {
+        label: `Built with Nativefier v${nativefierVersion}`,
+        click: (): void => {
+          openExternal('https://github.com/nativefier/nativefier').catch(
+            (err: unknown): void =>
+              log.error(
+                'Built with Nativefier v${nativefierVersion}.click ERROR',
+                err,
+              ),
+          );
+        },
+      },
+      {
+        label: 'Report an Issue',
+        click: (): void => {
+          openExternal('https://github.com/nativefier/nativefier/issues').catch(
+            (err: unknown): void =>
+              log.error('Report an Issue.click ERROR', err),
+          );
+        },
+      },
+    ],
+  };
+
+  let menuTemplate: MenuItemConstructorOptions[];
+
+  if (isOSX()) {
+    const electronMenu: MenuItemConstructorOptions = {
+      label: 'E&lectron',
+      submenu: [
+        {
+          label: 'Services',
+          role: 'services',
+          submenu: [],
+        },
+        {
+          type: 'separator',
+        },
+        {
+          label: 'Hide App',
+          accelerator: 'Cmd+H',
+          role: 'hide',
+        },
+        {
+          label: 'Hide Others',
+          accelerator: 'Cmd+Shift+H',
+          role: 'hideOthers',
+        },
+        {
+          label: 'Show All',
+          role: 'unhide',
+        },
+        {
+          type: 'separator',
+        },
+        {
+          label: 'Quit',
+          accelerator: 'Cmd+Q',
+          role: 'quit',
+        },
+      ],
+    };
+    (windowMenu.submenu as MenuItemConstructorOptions[]).push(
+      {
+        type: 'separator',
+      },
+      {
+        label: 'Bring All to Front',
+        role: 'front',
+      },
+    );
+    menuTemplate = [electronMenu, editMenu, viewMenu, windowMenu, helpMenu];
+  } else {
+    menuTemplate = [editMenu, viewMenu, windowMenu, helpMenu];
+  }
+
+  return menuTemplate;
+}
+
+function injectBookmarks(menuTemplate: MenuItemConstructorOptions[]): void {
+  const bookmarkConfigPath = path.join(__dirname, '..', 'bookmarks.json');
+
+  if (!fs.existsSync(bookmarkConfigPath)) {
+    return;
+  }
+
+  try {
+    const bookmarksMenuConfig = JSON.parse(
+      fs.readFileSync(bookmarkConfigPath, 'utf-8'),
+    ) as BookmarksMenuConfig;
+    const submenu: MenuItemConstructorOptions[] =
+      bookmarksMenuConfig.bookmarks.map((bookmark) => {
+        switch (bookmark.type) {
+          case 'link':
+            if (!('title' in bookmark && 'url' in bookmark)) {
+              throw new Error(
+                'All links in the bookmarks menu must have a title and url.',
+              );
+            }
+            try {
+              new URL(bookmark.url);
+            } catch {
+              throw new Error('Bookmark URL "' + bookmark.url + '"is invalid.');
+            }
+            return {
+              label: bookmark.title,
+              click: (): void => {
+                goToURL(bookmark.url)?.catch((err: unknown): void =>
+                  log.error(`${bookmark.title}.click ERROR`, err),
+                );
+              },
+              accelerator:
+                'shortcut' in bookmark ? bookmark.shortcut : undefined,
+            };
+          case 'separator':
+            return {
+              type: 'separator',
+            };
+          default:
+            throw new Error(
+              'A bookmarks menu entry has an invalid type; type must be one of "link", "separator".',
+            );
+        }
+      });
+    const bookmarksMenu: MenuItemConstructorOptions = {
+      label: bookmarksMenuConfig.menuLabel,
+      submenu,
+    };
+    // Insert custom bookmarks menu between menus "View" and "Window"
+    menuTemplate.splice(menuTemplate.length - 2, 0, bookmarksMenu);
+  } catch (err: unknown) {
+    log.error('Failed to load & parse bookmarks configuration JSON file.', err);
+  }
+}

app/src/components/trayIcon.ts

@@ -0,0 +1,88 @@
+import { app, Tray, Menu, ipcMain, nativeImage, BrowserWindow } from 'electron';
+
+import { getAppIcon, getCounterValue, isOSX } from '../helpers/helpers';
+import * as log from '../helpers/loggingHelper';
+import { OutputOptions } from '../../../shared/src/options/model';
+
+export function createTrayIcon(
+  nativefierOptions: OutputOptions,
+  mainWindow: BrowserWindow,
+): Tray | undefined {
+  const options = { ...nativefierOptions };
+
+  if (options.tray && options.tray !== 'false') {
+    const iconPath = getAppIcon();
+    if (!iconPath) {
+      throw new Error('Icon path not found found to use with tray option.');
+    }
+    const nimage = nativeImage.createFromPath(iconPath);
+    const appIcon = new Tray(nativeImage.createEmpty());
+
+    if (isOSX()) {
+      //sets the icon to the height of the tray.
+      appIcon.setImage(
+        nimage.resize({ height: appIcon.getBounds().height - 2 }),
+      );
+    } else {
+      appIcon.setImage(nimage);
+    }
+
+    const onClick = (): void => {
+      log.debug('onClick');
+      if (mainWindow.isVisible()) {
+        mainWindow.hide();
+      } else {
+        mainWindow.show();
+      }
+    };
+
+    const contextMenu = Menu.buildFromTemplate([
+      {
+        label: options.name,
+        click: onClick,
+      },
+      {
+        label: 'Quit',
+        click: (): void => app.exit(0),
+      },
+    ]);
+
+    appIcon.on('click', onClick);
+
+    if (options.counter) {
+      mainWindow.on('page-title-updated', (event, title) => {
+        log.debug('mainWindow.page-title-updated', { event, title });
+        const counterValue = getCounterValue(title);
+        if (counterValue) {
+          appIcon.setToolTip(
+            `(${counterValue})  ${options.name ?? 'Nativefier'}`,
+          );
+        } else {
+          appIcon.setToolTip(options.name ?? '');
+        }
+      });
+    } else {
+      ipcMain.on('notification', () => {
+        log.debug('ipcMain.notification');
+        if (mainWindow.isFocused()) {
+          return;
+        }
+        if (options.name) {
+          appIcon.setToolTip(`•  ${options.name}`);
+        }
+      });
+
+      mainWindow.on('focus', () => {
+        log.debug('mainWindow.focus');
+        appIcon.setToolTip(options.name ?? '');
+      });
+    }
+
+    appIcon.setToolTip(options.name ?? '');
+    appIcon.setContextMenu(contextMenu);
+
+    return appIcon;
+  }
+
+  return undefined;
+}

app/src/helpers/helpers.test.ts

@@ -0,0 +1,348 @@
+import { shell } from 'electron';
+jest.mock('./windowHelpers');
+
+import {
+  cleanupPlainText,
+  getCounterValue,
+  linkIsInternal,
+  openExternal,
+  removeUserAgentSpecifics,
+} from './helpers';
+import { showNavigationBlockedMessage } from './windowHelpers';
+
+const internalUrl = 'https://medium.com/';
+const internalUrlWww = 'https://www.medium.com/';
+const internalUrlSubPathRegex = /https:\/\/www.medium.com\/.*/;
+const sameBaseDomainUrl = 'https://app.medium.com/';
+const internalUrlCoUk = 'https://medium.co.uk/';
+const differentBaseDomainUrlCoUk = 'https://other.domain.co.uk/';
+const sameBaseDomainUrlCoUk = 'https://app.medium.co.uk/';
+const sameBaseDomainUrlTidalListen = 'https://listen.tidal.com/';
+const sameBaseDomainUrlTidalLogin = 'https://login.tidal.com/';
+const sameBaseDomainUrlTidalRegex = /https:\/\/(login|listen).tidal.com\/.*/;
+const internalUrlSubPath = 'topic/technology';
+const externalUrl = 'https://www.wikipedia.org/wiki/Electron';
+const wildcardRegex = /.*/;
+
+test('the original url should be internal without --strict-internal-urls', () => {
+  expect(
+    linkIsInternal(internalUrl, internalUrl, undefined, undefined),
+  ).toEqual(true);
+});
+
+test('the original url should be internal with --strict-internal-urls off', () => {
+  expect(linkIsInternal(internalUrl, internalUrl, undefined, false)).toEqual(
+    true,
+  );
+});
+
+test('the original url should be internal with --strict-internal-urls on', () => {
+  expect(linkIsInternal(internalUrl, internalUrl, undefined, true)).toEqual(
+    true,
+  );
+});
+
+test('sub-paths of the original url should be internal with --strict-internal-urls off', () => {
+  expect(
+    linkIsInternal(
+      internalUrl,
+      internalUrl + internalUrlSubPath,
+      undefined,
+      false,
+    ),
+  ).toEqual(true);
+});
+
+test('sub-paths of the original url should not be internal with --strict-internal-urls on', () => {
+  expect(
+    linkIsInternal(
+      internalUrl,
+      internalUrl + internalUrlSubPath,
+      undefined,
+      true,
+    ),
+  ).toEqual(false);
+});
+
+test('sub-paths of the original url should be internal with using a regex and --strict-internal-urls on', () => {
+  expect(
+    linkIsInternal(
+      internalUrl,
+      internalUrl + internalUrlSubPath,
+      internalUrlSubPathRegex,
+      true,
+    ),
+  ).toEqual(false);
+});
+
+test("'about:blank' should always be internal", () => {
+  expect(linkIsInternal(internalUrl, 'about:blank', undefined, true)).toEqual(
+    true,
+  );
+});
+
+test('urls from different sites should not be internal', () => {
+  expect(linkIsInternal(internalUrl, externalUrl, undefined, false)).toEqual(
+    false,
+  );
+});
+
+test('all urls should be internal with wildcard regex', () => {
+  expect(linkIsInternal(internalUrl, externalUrl, wildcardRegex, true)).toEqual(
+    true,
+  );
+});
+
+test('a "www." of a domain should be considered internal', () => {
+  expect(linkIsInternal(internalUrl, internalUrlWww, undefined, false)).toEqual(
+    true,
+  );
+});
+
+test('urls on the same "base domain" should be considered internal', () => {
+  expect(
+    linkIsInternal(internalUrl, sameBaseDomainUrl, undefined, false),
+  ).toEqual(true);
+});
+
+test('urls on the same "base domain" should NOT be considered internal using --strict-internal-urls', () => {
+  expect(
+    linkIsInternal(internalUrl, sameBaseDomainUrl, undefined, true),
+  ).toEqual(false);
+});
+
+test('urls on the same "base domain" should be considered internal, even with a www', () => {
+  expect(
+    linkIsInternal(internalUrlWww, sameBaseDomainUrl, undefined, false),
+  ).toEqual(true);
+});
+
+test('urls on the same "base domain" should be considered internal, even with different sub domains', () => {
+  expect(
+    linkIsInternal(
+      sameBaseDomainUrlTidalListen,
+      sameBaseDomainUrlTidalLogin,
+      undefined,
+      false,
+    ),
+  ).toEqual(true);
+});
+
+test('urls should support sub domain matching with a regex', () => {
+  expect(
+    linkIsInternal(
+      sameBaseDomainUrlTidalListen,
+      sameBaseDomainUrlTidalLogin,
+      sameBaseDomainUrlTidalRegex,
+      false,
+    ),
+  ).toEqual(true);
+});
+
+test('urls on the same "base domain" should NOT be considered internal with different sub domains when using --strict-internal-urls', () => {
+  expect(
+    linkIsInternal(
+      sameBaseDomainUrlTidalListen,
+      sameBaseDomainUrlTidalLogin,
+      undefined,
+      true,
+    ),
+  ).toEqual(false);
+});
+
+test('urls on the same "base domain" should be considered internal, long SLD', () => {
+  expect(
+    linkIsInternal(internalUrlCoUk, sameBaseDomainUrlCoUk, undefined, false),
+  ).toEqual(true);
+});
+
+test('urls on the a different "base domain" are considered NOT internal, long SLD', () => {
+  expect(
+    linkIsInternal(
+      internalUrlCoUk,
+      differentBaseDomainUrlCoUk,
+      undefined,
+      false,
+    ),
+  ).toEqual(false);
+});
+
+const testLoginPages = [
+  'https://amazon.co.uk/signin',
+  'https://amazon.com/signin',
+  'https://amazon.de/signin',
+  'https://amazon.com/ap/signin',
+  'https://facebook.co.uk/login',
+  'https://facebook.com/login',
+  'https://facebook.de/login',
+  'https://github.co.uk/login',
+  'https://github.com/login',
+  'https://github.de/login',
+  // GitHub 2FA flow with FIDO token
+  'https://github.com/session',
+  'https://github.com/sessions/two-factor/webauth',
+  'https://accounts.google.co.uk',
+  'https://accounts.google.com',
+  'https://mail.google.com/accounts/SetOSID',
+  'https://mail.google.co.uk/accounts/SetOSID',
+  'https://accounts.google.de',
+  'https://linkedin.co.uk/uas/login',
+  'https://linkedin.com/uas/login',
+  'https://linkedin.de/uas/login',
+  'https://login.live.co.uk',
+  'https://login.live.com',
+  'https://login.live.de',
+  'https://login.microsoftonline.com/common/oauth2/authorize',
+  'https://login.microsoftonline.co.uk/common/oauth2/authorize',
+  'https://login.microsoftonline.de/common/oauth2/authorize',
+  'https://okta.co.uk',
+  'https://okta.com',
+  'https://subdomain.okta.com',
+  'https://okta.de',
+  'https://twitter.co.uk/oauth/authenticate',
+  'https://twitter.com/oauth/authenticate',
+  'https://twitter.de/oauth/authenticate',
+  'https://appleid.apple.com/auth/authorize',
+  'https://id.atlassian.com',
+  'https://auth.atlassian.com',
+  'https://vmware.workspaceair.com',
+  'https://vmware.auth.securid.com',
+];
+
+test.each(testLoginPages)(
+  '%s login page should be internal',
+  (loginUrl: string) => {
+    expect(linkIsInternal(internalUrl, loginUrl, undefined, false)).toEqual(
+      true,
+    );
+  },
+);
+
+// Ensure that we don't over-match service pages
+const testNonLoginPages = [
+  'https://www.amazon.com/Node-Cookbook-techniques-server-side-development-ebook',
+  'https://github.com/nativefier/nativefier',
+  'https://github.com/org/nativefier',
+  'https://microsoft.com',
+  'https://office.microsoftonline.com',
+  'https://twitter.com/marcoroth_/status/1325938620906287104',
+  'https://appleid.apple.com/account',
+  'https://mail.google.com/',
+  'https://atlassian.com',
+];
+
+test.each(testNonLoginPages)(
+  '%s page should not be internal',
+  (url: string) => {
+    expect(linkIsInternal(internalUrl, url, undefined, false)).toEqual(false);
+  },
+);
+
+const smallCounterTitle = 'Inbox (11) - nobody@example.com - Gmail';
+const largeCounterTitle = 'Inbox (8,756) - nobody@example.com - Gmail';
+const hourCounterTitle = 'Today (1:23) - nobody@example.com - TimeTracker';
+const noCounterTitle = 'Inbox - nobody@example.com - Gmail';
+
+test('getCounterValue should return undefined for titles without counter numbers', () => {
+  expect(getCounterValue(noCounterTitle)).toEqual(undefined);
+});
+
+test('getCounterValue should return a string for small counter numbers in the title', () => {
+  expect(getCounterValue(smallCounterTitle)).toEqual('11');
+});
+
+test('getCounterValue should return a string for large counter numbers in the title', () => {
+  expect(getCounterValue(largeCounterTitle)).toEqual('8,756');
+});
+
+test('getCounterValue should return a string for hour counter numbers in the title', () => {
+  expect(getCounterValue(hourCounterTitle)).toEqual('1:23');
+});
+
+describe('removeUserAgentSpecifics', () => {
+  const userAgentFallback =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) app-nativefier-804458/1.0.0 Chrome/89.0.4389.128 Electron/12.0.7 Safari/537.36';
+  test('removes Electron and App specific info', () => {
+    expect(
+      removeUserAgentSpecifics(
+        userAgentFallback,
+        'app-nativefier-804458',
+        '1.0.0',
+      ),
+    ).not.toBe(
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.128 Safari/537.36',
+    );
+  });
+
+  test('should not have multiple spaces in a row', () => {
+    expect(
+      removeUserAgentSpecifics(
+        userAgentFallback,
+        'app-nativefier-804458',
+        '1.0.0',
+      ),
+    ).toEqual(expect.not.stringMatching(/\s{2,}/));
+  });
+});
+
+describe('cleanupPlainText', () => {
+  test('removes extra spaces from text', () => {
+    expect(cleanupPlainText('  this is a  test  ')).toBe('this is a test');
+  });
+});
+
+describe('openExternal', () => {
+  const mockShellOpenExternal: jest.SpyInstance = jest.spyOn(
+    shell,
+    'openExternal',
+  );
+  const mockShowNavigationBlockedMessage: jest.SpyInstance =
+    showNavigationBlockedMessage as jest.Mock;
+
+  beforeEach(() => {
+    mockShellOpenExternal.mockReset();
+    mockShowNavigationBlockedMessage
+      .mockReset()
+      .mockReturnValue(Promise.resolve(undefined));
+  });
+
+  afterAll(() => {
+    mockShellOpenExternal.mockRestore();
+    mockShowNavigationBlockedMessage.mockRestore();
+  });
+
+  test('https urls scheme should *not* be blocked', async () => {
+    await openExternal('https://whatever.foo');
+
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockShellOpenExternal).toHaveBeenCalled();
+  });
+
+  test('urls with whitelisted scheme should *not* be blocked', async () => {
+    await openExternal('ircs://irc.libera.chat/whatever');
+
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockShellOpenExternal).toHaveBeenCalled();
+  });
+
+  test('urls with non-allowlisted scheme *should* be blocked', async () => {
+    await openExternal('barf://whatever.foo');
+
+    expect(mockShowNavigationBlockedMessage).toHaveBeenCalledTimes(1);
+    expect(mockShellOpenExternal).not.toHaveBeenCalled();
+  });
+
+  test('potentially-malicious urls *should* be blocked', async () => {
+    await openExternal('https://hello.com/wor%00ld');
+
+    expect(mockShowNavigationBlockedMessage).toHaveBeenCalledTimes(1);
+    expect(mockShellOpenExternal).not.toHaveBeenCalled();
+  });
+
+  test('malformed urls *should* be blocked', async () => {
+    await openExternal('zombocom');
+
+    expect(mockShowNavigationBlockedMessage).toHaveBeenCalledTimes(1);
+    expect(mockShellOpenExternal).not.toHaveBeenCalled();
+  });
+});

app/src/helpers/helpers.ts

@@ -0,0 +1,315 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { BrowserWindow, OpenExternalOptions, shell } from 'electron';
+
+import * as log from '../helpers/loggingHelper';
+import { showNavigationBlockedMessage } from './windowHelpers';
+
+export const INJECT_DIR = path.join(__dirname, '..', 'inject');
+
+/**
+ * Firefox's list of protocols for which opening an external handler is allowed without confirmation.
+ * Taken from Firefox's. Location might vary in codebase, search for one of them, e.g.
+ * https://searchfox.org/mozilla-central/search?q=%22xmpp%22&path=&case=false&regexp=false
+ */
+const URL_PROTOCOLS_NOCONFIRMATION_FIREFOX = [
+  'bitcoin:',
+  'ftp:',
+  'ftps:',
+  'geo:',
+  'im:',
+  'irc:',
+  'ircs:',
+  'magnet:',
+  'mailto:',
+  'matrix:',
+  'mms:',
+  'news:',
+  'nntp:',
+  'openpgp4fpr:',
+  'sftp:',
+  'sip:',
+  'sms:',
+  'smsto:',
+  'ssh:',
+  'tel:',
+  'urn:',
+  'webcal:',
+  'wtai:',
+  'xmpp:',
+];
+/**
+ * Our extension to Firefox's list. If extending this list too much, we should
+ * really add a confirmation modal (for now we just block), like browsers do.
+ * But for now, since nobody shouts at us for bluntly blocking anything else,
+ * let's keep rolling with it.
+ */
+const URL_PROTOCOLS_NOCONFIRMATION_EXTRA = ['zoommtg:'];
+/**
+ * List of protocols for which opening an external handler is allowed without confirmation.
+ * Note: "without confirmation" is currently a lie. It was implemented this way
+ * as a way to know from user feedback what protocols would cause users to shout,
+ * but there wasn't much shouting happening, so we currently don't have a confirmation
+ * mechanism, we just bluntly block. That might need to change at some point.
+ */
+const URL_PROTOCOLS_NOCONFIRMATION = [
+  'http:',
+  'https:',
+  ...URL_PROTOCOLS_NOCONFIRMATION_FIREFOX,
+  ...URL_PROTOCOLS_NOCONFIRMATION_EXTRA,
+];
+const SHELL_SAFETY_FEEDBACK_STR =
+  'If you believe this URL should open, you might be right, and our validation might be excessive.' +
+  'Please share this error & URL at https://github.com/nativefier/nativefier/issues/1459';
+
+export function isUrlShellSafe(
+  urlToGo: string,
+): { blocked: false } | { blocked: true; reason: string } {
+  let url: URL;
+  try {
+    url = new URL(urlToGo.toLowerCase());
+  } catch (err: unknown) {
+    return {
+      blocked: true,
+      reason: `URL appears malformed. ${SHELL_SAFETY_FEEDBACK_STR}`,
+    };
+  }
+
+  if (!URL_PROTOCOLS_NOCONFIRMATION.includes(url.protocol)) {
+    return {
+      blocked: true,
+      reason: `URL protocol is disallowed. ${SHELL_SAFETY_FEEDBACK_STR}`,
+    };
+  }
+
+  // https://cwe.mitre.org/data/definitions/177.html
+  if (
+    urlToGo.includes('%00') ||
+    urlToGo.includes('%0a') ||
+    urlToGo.includes('%2e') ||
+    urlToGo.includes('%2f') ||
+    urlToGo.includes('%5c')
+  ) {
+    return {
+      blocked: true,
+      reason: `URL might be malicious. ${SHELL_SAFETY_FEEDBACK_STR}`,
+    };
+  }
+
+  return { blocked: false };
+}
+
+/**
+ * Helper to print debug messages from the main process in the browser window
+ */
+export function debugLog(browserWindow: BrowserWindow, message: string): void {
+  // Need a delay, as it takes time for the preloaded js to be loaded by the window
+  setTimeout(() => {
+    browserWindow.webContents.send('debug', message);
+  }, 3000);
+  log.debug(message);
+}
+
+/**
+ * Helper to determine domain-ish equality for many cases, the trivial ones
+ * and the trickier ones, e.g. `blog.foo.com` and `shop.foo.com`,
+ * in a way that is "good enough", and doesn't need a list of SLDs.
+ * See chat at https://github.com/nativefier/nativefier/pull/1171#pullrequestreview-649132523
+ */
+function domainify(url: string): string {
+  // So here's what we're doing here:
+  // Get the hostname from the url
+  const hostname = new URL(url).hostname;
+  // Drop the first section if the domain
+  const domain = hostname.split('.').slice(1).join('.');
+  // Check the length, if it's too short, the hostname was probably the domain
+  // Or if the domain doesn't have a . in it we went too far
+  if (domain.length < 6 || domain.split('.').length === 0) {
+    return hostname;
+  }
+  // This SHOULD be the domain, but nothing is 100% guaranteed
+  return domain;
+}
+
+export function getAppIcon(): string | undefined {
+  // Prefer ICO under Windows, see
+  // https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions
+  // https://www.electronjs.org/docs/api/native-image#supported-formats
+  if (isWindows()) {
+    const ico = path.join(__dirname, '..', 'icon.ico');
+    if (fs.existsSync(ico)) {
+      return ico;
+    }
+  }
+  const png = path.join(__dirname, '..', 'icon.png');
+  if (fs.existsSync(png)) {
+    return png;
+  }
+}
+
+export function getCounterValue(title: string): string | undefined {
+  const itemCountRegex = /[([{]([\d.,:]*)\+?[}\])]/;
+  const match = itemCountRegex.exec(title);
+  return match ? match[1] : undefined;
+}
+
+export function getCSSToInject(): string {
+  let cssToInject = '';
+  const cssFiles = fs
+    .readdirSync(INJECT_DIR, { withFileTypes: true })
+    .filter(
+      (injectFile) => injectFile.isFile() && injectFile.name.endsWith('.css'),
+    )
+    .map((cssFileStat) =>
+      path.resolve(path.join(INJECT_DIR, cssFileStat.name)),
+    );
+  for (const cssFile of cssFiles) {
+    log.debug('Injecting CSS file', cssFile);
+    const cssFileData = fs.readFileSync(cssFile);
+    cssToInject += `/* ${cssFile} */\n\n ${cssFileData.toString()}\n\n`;
+  }
+  return cssToInject;
+}
+
+export function isOSX(): boolean {
+  return os.platform() === 'darwin';
+}
+
+export function isLinux(): boolean {
+  return os.platform() === 'linux';
+}
+
+export function isWindows(): boolean {
+  return os.platform() === 'win32';
+}
+
+function isInternalLoginPage(url: string): boolean {
+  // Making changes? Remember to update the tests in helpers.test.ts and in API.md
+  const internalLoginPagesArray = [
+    'amazon\\.[a-zA-Z\\.]*/[a-zA-Z\\/]*signin', // Amazon
+    `facebook\\.[a-zA-Z\\.]*\\/login`, // Facebook
+    'github\\.[a-zA-Z\\.]*\\/(?:login|session)', // GitHub
+    'accounts\\.google\\.[a-zA-Z\\.]*', // Google
+    'mail\\.google\\.[a-zA-Z\\.]*\\/accounts/SetOSID', // Google
+    'linkedin\\.[a-zA-Z\\.]*/uas/login', // LinkedIn
+    'login\\.live\\.[a-zA-Z\\.]*', // Microsoft
+    'login\\.microsoftonline\\.[a-zA-Z\\.]*', // Microsoft
+    'okta\\.[a-zA-Z\\.]*', // Okta
+    'twitter\\.[a-zA-Z\\.]*/oauth/authenticate', // Twitter
+    'appleid\\.apple\\.com/auth/authorize', // Apple
+    '(?:id|auth)\\.atlassian\\.[a-zA-Z]+', // Atlassian
+    '.*\\.workspaceair\\.com', // VMWare Workspace One SSO
+    '.*\\.securid\\.com', // SecurID for VMWare Workspace One SSO
+  ];
+  // Making changes? Remember to update the tests in helpers.test.ts and in API.md
+  const regex = RegExp(internalLoginPagesArray.join('|'));
+  return regex.test(url);
+}
+
+export function linkIsInternal(
+  currentUrl: string,
+  newUrl: string,
+  internalUrlRegex: string | RegExp | undefined,
+  isStrictInternalUrlsEnabled: boolean | undefined,
+): boolean {
+  log.debug('linkIsInternal', { currentUrl, newUrl, internalUrlRegex });
+  if (newUrl.split('#')[0] === 'about:blank') {
+    return true;
+  }
+
+  if (isInternalLoginPage(newUrl)) {
+    return true;
+  }
+
+  if (internalUrlRegex) {
+    const regex = RegExp(internalUrlRegex);
+    if (regex.test(newUrl)) {
+      return true;
+    }
+  }
+
+  if (isStrictInternalUrlsEnabled) {
+    return currentUrl == newUrl;
+  }
+
+  try {
+    // Consider as "same domain-ish", without TLD/SLD list:
+    // 1. app.foo.com and foo.com
+    // 2. www.foo.com and foo.com
+    // 3. www.foo.com and app.foo.com
+
+    // Only use the tld and the main domain for domain-ish test
+    // Enables domain-ish equality for blog.foo.com and shop.foo.com
+    return domainify(currentUrl) === domainify(newUrl);
+  } catch (err: unknown) {
+    log.error(
+      'Failed to parse domains as determining if link is internal. From:',
+      currentUrl,
+      'To:',
+      newUrl,
+      err,
+    );
+    return false;
+  }
+}
+
+export function nativeTabsSupported(): boolean {
+  return isOSX();
+}
+
+/**
+ * Open the given external protocol URL in the desktop's default manner
+ * (e.g. `mailto:` URLs in the user's default mail agent), with extra validation.
+ */
+export function openExternal(
+  url: string,
+  options?: OpenExternalOptions,
+): Promise<void> {
+  const urlShellSafety = isUrlShellSafe(url);
+  log.debug('openExternal', { url, options, urlShellSafety });
+  if (urlShellSafety.blocked) {
+    return new Promise((resolve) => {
+      showNavigationBlockedMessage(
+        `Navigation blocked to ${url}\n\n${urlShellSafety.reason}`,
+      )
+        .then(() => resolve())
+        .catch((err: unknown) => {
+          throw err;
+        });
+    });
+  }
+
+  return shell.openExternal(url, options);
+}
+
+// Copy-pastaed as unable to get imports to work in preload.
+// If modifying, update also app/src/preload.ts
+export function isWayland(): boolean {
+  return (
+    isLinux() &&
+    (Boolean(process.env.WAYLAND_DISPLAY) ||
+      process.env.XDG_SESSION_TYPE === 'wayland')
+  );
+}
+
+export function removeUserAgentSpecifics(
+  userAgentFallback: string,
+  appName: string,
+  appVersion: string,
+): string {
+  // Electron userAgentFallback is the user agent used if none is specified when creating a window.
+  // For our purposes, it's useful because its format is similar enough to a real Chrome's user agent to not need
+  // to infer the userAgent. userAgentFallback normally looks like this:
+  // Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) app-nativefier-804458/1.0.0 Chrome/89.0.4389.128 Electron/12.0.7 Safari/537.36
+  // We just need to strip out the appName/1.0.0 and Electron/electronVersion
+  return userAgentFallback
+    .replace(`Electron/${process.versions.electron} `, '')
+    .replace(`${appName}/${appVersion} `, '');
+}
+
+/** Removes extra spaces from a text */
+export function cleanupPlainText(text: string): string {
+  return text.trim().replace(/\s+/g, ' ');
+}

app/src/helpers/inferFlash.ts

@@ -0,0 +1,90 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { isOSX, isWindows, isLinux } from './helpers';
+import * as log from './loggingHelper';
+
+type fsError = Error & { code: string };
+
+/**
+ * Find a file or directory
+ */
+function findSync(
+  pattern: RegExp,
+  basePath: string,
+  limitSearchToDirectories = false,
+): string[] {
+  const matches: string[] = [];
+
+  (function findSyncRecurse(base): void {
+    let children: string[];
+    try {
+      children = fs.readdirSync(base);
+    } catch (err: unknown) {
+      if ((err as fsError).code === 'ENOENT') {
+        return;
+      }
+      throw err;
+    }
+
+    for (const child of children) {
+      const childPath = path.join(base, child);
+      const childIsDirectory = fs.lstatSync(childPath).isDirectory();
+      const patternMatches = pattern.test(childPath);
+
+      if (!patternMatches) {
+        if (!childIsDirectory) {
+          return;
+        }
+        findSyncRecurse(childPath);
+        return;
+      }
+
+      if (!limitSearchToDirectories) {
+        matches.push(childPath);
+        return;
+      }
+
+      if (childIsDirectory) {
+        matches.push(childPath);
+      }
+    }
+  })(basePath);
+  return matches;
+}
+
+function findFlashOnLinux(): string {
+  return findSync(/libpepflashplayer\.so/, '/opt/google/chrome')[0];
+}
+
+function findFlashOnWindows(): string {
+  return findSync(
+    /pepflashplayer\.dll/,
+    'C:\\Program Files (x86)\\Google\\Chrome',
+  )[0];
+}
+
+function findFlashOnMac(): string {
+  return findSync(
+    /PepperFlashPlayer.plugin/,
+    '/Applications/Google Chrome.app/',
+    true,
+  )[0];
+}
+
+export function inferFlashPath(): string | undefined {
+  if (isOSX()) {
+    return findFlashOnMac();
+  }
+
+  if (isWindows()) {
+    return findFlashOnWindows();
+  }
+
+  if (isLinux()) {
+    return findFlashOnLinux();
+  }
+
+  log.warn('Unable to determine OS to infer flash player');
+  return undefined;
+}

app/src/helpers/loggingHelper.ts

@@ -0,0 +1,82 @@
+// This helper allows logs to either be printed to the console as they would normally or if
+// the USE_LOG_FILE environment variable is set (such as through our playwright tests), then
+// the logs can be diverted from the command line to a log file, so that they can be displayed
+// later (such as at the end of a playwright test run to help diagnose potential failures).
+// Use this instead of loglevel whenever logging messages inside the app.
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import loglevel from 'loglevel';
+
+import { safeGetEnv } from './playwrightHelpers';
+
+const USE_LOG_FILE = safeGetEnv('USE_LOG_FILE') === '1';
+const LOG_FILE_DIR = safeGetEnv('LOG_FILE_DIR') ?? process.cwd();
+const LOG_FILENAME = path.join(LOG_FILE_DIR, `${new Date().getTime()}.log`);
+
+const logLevelNames = ['TRACE', 'DEBUG', 'INFO ', 'WARN ', 'ERROR'];
+
+function _logger(
+  logFunc: (...args: unknown[]) => void,
+  level: loglevel.LogLevelNumbers,
+  ...args: unknown[]
+): void {
+  if (USE_LOG_FILE && loglevel.getLevel() >= level) {
+    for (const arg of args) {
+      try {
+        const lines =
+          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+          JSON.stringify(arg, null, 2)?.split('\n') ?? `${arg}`.split('\n');
+        for (const line of lines) {
+          fs.appendFileSync(
+            LOG_FILENAME,
+            `${new Date().getTime()} ${logLevelNames[level]} ${line}\n`,
+          );
+        }
+      } catch {
+        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+        fs.appendFileSync(LOG_FILENAME, `${logLevelNames[level]} ${arg}\n`);
+      }
+    }
+  } else {
+    logFunc(...args);
+  }
+}
+
+export function debug(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.debug, loglevel.levels.DEBUG, ...args);
+}
+
+export function error(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.error, loglevel.levels.ERROR, ...args);
+}
+
+export function info(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.info, loglevel.levels.INFO, ...args);
+}
+
+export function log(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.info, loglevel.levels.INFO, ...args);
+}
+
+export function setLevel(
+  level: loglevel.LogLevelDesc,
+  persist?: boolean,
+): void {
+  loglevel.setLevel(level, persist);
+}
+
+export function trace(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.trace, loglevel.levels.TRACE, ...args);
+}
+
+export function warn(...args: unknown[]): void {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  _logger(loglevel.warn, loglevel.levels.WARN, ...args);
+}

app/src/helpers/playwrightHelpers.ts

@@ -0,0 +1,6 @@
+export const IS_PLAYWRIGHT = safeGetEnv('PLAYWRIGHT_TEST') === '1';
+export const PLAYWRIGHT_CONFIG = safeGetEnv('PLAYWRIGHT_CONFIG');
+
+export function safeGetEnv(key: string): string | undefined {
+  return key in process.env ? process.env[key] : undefined;
+}

app/src/helpers/windowEvents.test.ts

@@ -0,0 +1,353 @@
+jest.mock('./helpers');
+jest.mock('./windowEvents');
+jest.mock('./windowHelpers');
+
+import { dialog, BrowserWindow, HandlerDetails, WebContents } from 'electron';
+import { WindowOptions } from '../../../shared/src/options/model';
+import { linkIsInternal, openExternal, nativeTabsSupported } from './helpers';
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const {
+  onNewWindowHelper,
+  onWillNavigate,
+  onWillPreventUnload,
+}: {
+  onNewWindowHelper: (
+    options: WindowOptions,
+    setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+    details: Partial<HandlerDetails>,
+    parent?: BrowserWindow,
+  ) => ReturnType<Parameters<WebContents['setWindowOpenHandler']>[0]>;
+  onWillNavigate: (
+    options: {
+      blockExternalUrls: boolean;
+      internalUrls?: string | RegExp;
+      targetUrl: string;
+    },
+    event: unknown,
+    urlToGo: string,
+  ) => Promise<void>;
+  onWillPreventUnload: (event: unknown) => void;
+} = jest.requireActual('./windowEvents');
+import {
+  showNavigationBlockedMessage,
+  createAboutBlankWindow,
+  createNewTab,
+} from './windowHelpers';
+
+describe('onNewWindowHelper', () => {
+  const originalURL = 'https://medium.com/';
+  const internalURL = 'https://medium.com/topics/technology';
+  const externalURL = 'https://www.wikipedia.org/wiki/Electron';
+  const foregroundDisposition = 'foreground-tab';
+  const backgroundDisposition = 'background-tab';
+  const baseOptions = {
+    autoHideMenuBar: true,
+    blockExternalUrls: false,
+    insecure: false,
+    name: 'TEST_APP',
+    targetUrl: originalURL,
+    zoom: 1.0,
+  } as WindowOptions;
+  const mockShowNavigationBlockedMessage: jest.SpyInstance =
+    showNavigationBlockedMessage as jest.Mock;
+  const mockCreateAboutBlank: jest.SpyInstance =
+    createAboutBlankWindow as jest.Mock;
+  const mockCreateNewTab: jest.SpyInstance = createNewTab as jest.Mock;
+  const mockLinkIsInternal: jest.SpyInstance = (
+    linkIsInternal as jest.Mock
+  ).mockImplementation(() => true);
+  const mockNativeTabsSupported: jest.SpyInstance =
+    nativeTabsSupported as jest.Mock;
+  const mockOpenExternal: jest.SpyInstance = openExternal as jest.Mock;
+  const setupWindow = jest.fn();
+
+  beforeEach(() => {
+    mockShowNavigationBlockedMessage
+      .mockReset()
+      .mockReturnValue(Promise.resolve(undefined));
+    mockCreateAboutBlank.mockReset();
+    mockCreateNewTab.mockReset();
+    mockLinkIsInternal.mockReset().mockReturnValue(true);
+    mockNativeTabsSupported.mockReset().mockReturnValue(false);
+    mockOpenExternal.mockReset();
+    setupWindow.mockReset();
+  });
+
+  afterAll(() => {
+    mockShowNavigationBlockedMessage.mockRestore();
+    mockCreateAboutBlank.mockRestore();
+    mockCreateNewTab.mockRestore();
+    mockLinkIsInternal.mockRestore();
+    mockNativeTabsSupported.mockRestore();
+    mockOpenExternal.mockRestore();
+  });
+
+  test('internal urls should not be handled', () => {
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: internalURL,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('allow');
+  });
+
+  test('external urls should be opened externally', () => {
+    mockLinkIsInternal.mockReturnValue(false);
+
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: externalURL,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).toHaveBeenCalledTimes(1);
+    expect(result.action).toEqual('deny');
+  });
+
+  test('external urls should be ignored if blockExternalUrls is true', () => {
+    mockLinkIsInternal.mockReturnValue(false);
+    const options = {
+      ...baseOptions,
+      blockExternalUrls: true,
+    };
+    const result = onNewWindowHelper(options, setupWindow, {
+      url: externalURL,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).toHaveBeenCalledTimes(1);
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('deny');
+  });
+
+  test('tab disposition should be ignored if tabs are not enabled', () => {
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: internalURL,
+      disposition: foregroundDisposition,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('allow');
+  });
+
+  test('tab disposition should be ignored if url is external', () => {
+    mockLinkIsInternal.mockReturnValue(false);
+
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: externalURL,
+      disposition: foregroundDisposition,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).toHaveBeenCalledTimes(1);
+    expect(result.action).toEqual('deny');
+  });
+
+  test('foreground tabs with internal urls should be opened in the foreground', () => {
+    mockNativeTabsSupported.mockReturnValue(true);
+
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: internalURL,
+      disposition: foregroundDisposition,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).toHaveBeenCalledTimes(1);
+    expect(mockCreateNewTab).toHaveBeenCalledWith(
+      baseOptions,
+      setupWindow,
+      internalURL,
+      true,
+    );
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('deny');
+  });
+
+  test('background tabs with internal urls should be opened in background tabs', () => {
+    mockNativeTabsSupported.mockReturnValue(true);
+
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: internalURL,
+      disposition: backgroundDisposition,
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).toHaveBeenCalledTimes(1);
+    expect(mockCreateNewTab).toHaveBeenCalledWith(
+      baseOptions,
+      setupWindow,
+      internalURL,
+      false,
+    );
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('deny');
+  });
+
+  test('about:blank urls should be handled', () => {
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: 'about:blank',
+    });
+
+    expect(mockCreateAboutBlank).toHaveBeenCalledTimes(1);
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('deny');
+  });
+
+  test('about:blank#blocked urls should be handled', () => {
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: 'about:blank#blocked',
+    });
+
+    expect(mockCreateAboutBlank).toHaveBeenCalledTimes(1);
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('deny');
+  });
+
+  test('about:blank#other urls should not be handled', () => {
+    const result = onNewWindowHelper(baseOptions, setupWindow, {
+      url: 'about:blank#other',
+    });
+
+    expect(mockCreateAboutBlank).not.toHaveBeenCalled();
+    expect(mockCreateNewTab).not.toHaveBeenCalled();
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(result.action).toEqual('allow');
+  });
+});
+
+describe('onWillNavigate', () => {
+  const originalURL = 'https://medium.com/';
+  const internalURL = 'https://medium.com/topics/technology';
+  const externalURL = 'https://www.wikipedia.org/wiki/Electron';
+
+  const mockShowNavigationBlockedMessage: jest.SpyInstance =
+    showNavigationBlockedMessage as jest.Mock;
+  const mockLinkIsInternal: jest.SpyInstance = linkIsInternal as jest.Mock;
+  const mockOpenExternal: jest.SpyInstance = openExternal as jest.Mock;
+  const preventDefault = jest.fn();
+
+  beforeEach(() => {
+    mockShowNavigationBlockedMessage
+      .mockReset()
+      .mockReturnValue(Promise.resolve(undefined));
+    mockLinkIsInternal.mockReset().mockReturnValue(false);
+    mockOpenExternal.mockReset();
+    preventDefault.mockReset();
+  });
+
+  afterAll(() => {
+    mockShowNavigationBlockedMessage.mockRestore();
+    mockLinkIsInternal.mockRestore();
+    mockOpenExternal.mockRestore();
+  });
+
+  test('internal urls should not be handled', async () => {
+    mockLinkIsInternal.mockReturnValue(true);
+    const options = {
+      blockExternalUrls: false,
+      targetUrl: originalURL,
+    };
+    const event = { preventDefault };
+    await onWillNavigate(options, event, internalURL);
+
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+
+  test('external urls should be opened externally', async () => {
+    const options = {
+      blockExternalUrls: false,
+      targetUrl: originalURL,
+    };
+    const event = { preventDefault };
+    await onWillNavigate(options, event, externalURL);
+
+    expect(mockShowNavigationBlockedMessage).not.toHaveBeenCalled();
+    expect(mockOpenExternal).toHaveBeenCalledTimes(1);
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+  });
+
+  test('external urls should be blocked if blockExternalUrls is true', async () => {
+    const options = {
+      blockExternalUrls: true,
+      targetUrl: originalURL,
+    };
+    const event = { preventDefault };
+    await onWillNavigate(options, event, externalURL);
+
+    expect(mockShowNavigationBlockedMessage).toHaveBeenCalledTimes(1);
+    expect(mockOpenExternal).not.toHaveBeenCalled();
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('onWillPreventUnload', () => {
+  const mockFromWebContents: jest.SpyInstance = jest
+    .spyOn(BrowserWindow, 'fromWebContents')
+    .mockImplementation(() => new BrowserWindow());
+  const mockShowDialog: jest.SpyInstance = jest.spyOn(
+    dialog,
+    'showMessageBoxSync',
+  );
+  const preventDefault: jest.SpyInstance = jest.fn();
+
+  beforeEach(() => {
+    mockFromWebContents.mockReset();
+    mockShowDialog.mockReset().mockReturnValue(undefined);
+    preventDefault.mockReset();
+  });
+
+  afterAll(() => {
+    mockFromWebContents.mockRestore();
+    mockShowDialog.mockRestore();
+  });
+
+  test('with no sender', () => {
+    const event = {};
+    onWillPreventUnload(event);
+
+    expect(mockFromWebContents).not.toHaveBeenCalled();
+    expect(mockShowDialog).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+
+  test('shows dialog and calls preventDefault on ok', () => {
+    mockShowDialog.mockReturnValue(0);
+
+    const event = { preventDefault, sender: {} };
+    onWillPreventUnload(event);
+
+    expect(mockFromWebContents).toHaveBeenCalledWith(event.sender);
+    expect(mockShowDialog).toHaveBeenCalled();
+    expect(preventDefault).toHaveBeenCalledWith();
+  });
+
+  test('shows dialog and does not call preventDefault on cancel', () => {
+    mockShowDialog.mockReturnValue(1);
+
+    const event = { preventDefault, sender: {} };
+    onWillPreventUnload(event);
+
+    expect(mockFromWebContents).toHaveBeenCalledWith(event.sender);
+    expect(mockShowDialog).toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+});

app/src/helpers/windowEvents.ts

@@ -0,0 +1,188 @@
+import {
+  dialog,
+  BrowserWindow,
+  Event,
+  WebContents,
+  HandlerDetails,
+} from 'electron';
+
+import { linkIsInternal, nativeTabsSupported, openExternal } from './helpers';
+import * as log from './loggingHelper';
+import {
+  createAboutBlankWindow,
+  createNewTab,
+  injectCSS,
+  sendParamsOnDidFinishLoad,
+  setProxyRules,
+  showNavigationBlockedMessage,
+} from './windowHelpers';
+import { WindowOptions } from '../../../shared/src/options/model';
+
+type NewWindowHandlerResult = ReturnType<
+  Parameters<WebContents['setWindowOpenHandler']>[0]
+>;
+
+export function onNewWindow(
+  options: WindowOptions,
+  setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+  details: HandlerDetails,
+  parent?: BrowserWindow,
+): NewWindowHandlerResult {
+  log.debug('onNewWindow', {
+    details,
+  });
+  return onNewWindowHelper(
+    options,
+    setupWindow,
+    details,
+    nativeTabsSupported() ? undefined : parent,
+  );
+}
+
+export function onNewWindowHelper(
+  options: WindowOptions,
+  setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+  details: HandlerDetails,
+  parent?: BrowserWindow,
+): NewWindowHandlerResult {
+  log.debug('onNewWindowHelper', {
+    options,
+    details,
+  });
+  try {
+    if (
+      !linkIsInternal(
+        options.targetUrl,
+        details.url,
+        options.internalUrls,
+        options.strictInternalUrls,
+      )
+    ) {
+      if (options.blockExternalUrls) {
+        showNavigationBlockedMessage(
+          `Navigation to external URL blocked by options: ${details.url}`,
+        )
+          .then(() => {
+            // blockExternalURL(details.url).then(resolve).catch((err: unknown) => {
+            //   log.error('blockExternalURL', err);
+            // });
+          })
+          .catch((err: unknown) => {
+            throw err;
+          });
+        return { action: 'deny' };
+      } else {
+        openExternal(details.url).catch((err: unknown) => {
+          log.error('openExternal', err);
+        });
+        return { action: 'deny' };
+      }
+    }
+    // Normally the following would be:
+    // if (urlToGo.startsWith('about:blank'))...
+    // But due to a bug we resolved in https://github.com/nativefier/nativefier/issues/1197
+    // Some sites use about:blank#something to use as placeholder windows to fill
+    // with content via JavaScript. So we'll stay specific for now...
+    else if (['about:blank', 'about:blank#blocked'].includes(details.url)) {
+      createAboutBlankWindow(
+        options,
+        setupWindow,
+        nativeTabsSupported() ? undefined : parent,
+      );
+      return { action: 'deny' };
+    } else if (nativeTabsSupported()) {
+      createNewTab(
+        options,
+        setupWindow,
+        details.url,
+        details.disposition === 'foreground-tab',
+      );
+      return { action: 'deny' };
+    }
+    return { action: 'allow' };
+  } catch (err: unknown) {
+    return { action: 'deny' };
+  }
+}
+
+export function onWillNavigate(
+  options: WindowOptions,
+  event: Event,
+  urlToGo: string,
+): Promise<void> {
+  log.debug('onWillNavigate', urlToGo);
+  if (
+    !linkIsInternal(
+      options.targetUrl,
+      urlToGo,
+      options.internalUrls,
+      options.strictInternalUrls,
+    )
+  ) {
+    event.preventDefault();
+    if (options.blockExternalUrls) {
+      return new Promise((resolve) => {
+        showNavigationBlockedMessage(
+          `Navigation to external URL blocked by options: ${urlToGo}`,
+        )
+          .then(() => resolve())
+          .catch((err: unknown) => {
+            throw err;
+          });
+      });
+    } else {
+      return openExternal(urlToGo);
+    }
+  }
+  return Promise.resolve(undefined);
+}
+
+export function onWillPreventUnload(
+  event: Event & { sender?: WebContents },
+): void {
+  log.debug('onWillPreventUnload', event);
+
+  const webContents = event.sender;
+  if (!webContents) {
+    return;
+  }
+
+  const browserWindow =
+    BrowserWindow.fromWebContents(webContents) ??
+    BrowserWindow.getFocusedWindow();
+  if (browserWindow) {
+    const choice = dialog.showMessageBoxSync(browserWindow, {
+      type: 'question',
+      buttons: ['Proceed', 'Stay'],
+      message:
+        'You may have unsaved changes, are you sure you want to proceed?',
+      title: 'Changes you made may not be saved.',
+      defaultId: 0,
+      cancelId: 1,
+    });
+    if (choice === 0) {
+      event.preventDefault();
+    }
+  }
+}
+
+export function setupNativefierWindow(
+  options: WindowOptions,
+  window: BrowserWindow,
+): void {
+  if (options.proxyRules) {
+    setProxyRules(window, options.proxyRules);
+  }
+
+  injectCSS(window);
+
+  window.webContents.on('will-navigate', (event: Event, url: string) => {
+    onWillNavigate(options, event, url).catch((err) => {
+      log.error('window.webContents.on.will-navigate ERROR', err);
+      event.preventDefault();
+    });
+  });
+  window.webContents.on('will-prevent-unload', onWillPreventUnload);
+
+  sendParamsOnDidFinishLoad(options, window);
+}

app/src/helpers/windowHelpers.test.ts

@@ -0,0 +1,292 @@
+import { dialog, BrowserWindow } from 'electron';
+jest.mock('loglevel');
+import { error } from 'loglevel';
+import { WindowOptions } from '../../../shared/src/options/model';
+
+jest.mock('./helpers');
+import { getCSSToInject } from './helpers';
+jest.mock('./windowEvents');
+import { clearAppData, createNewTab, injectCSS } from './windowHelpers';
+
+describe('clearAppData', () => {
+  let window: BrowserWindow;
+  let mockClearCache: jest.SpyInstance;
+  let mockClearStorageData: jest.SpyInstance;
+  const mockShowDialog: jest.SpyInstance = jest.spyOn(dialog, 'showMessageBox');
+
+  beforeEach(() => {
+    window = new BrowserWindow();
+    mockClearCache = jest.spyOn(window.webContents.session, 'clearCache');
+    mockClearStorageData = jest.spyOn(
+      window.webContents.session,
+      'clearStorageData',
+    );
+    mockShowDialog.mockReset().mockResolvedValue(undefined);
+  });
+
+  afterAll(() => {
+    mockClearCache.mockRestore();
+    mockClearStorageData.mockRestore();
+    mockShowDialog.mockRestore();
+  });
+
+  test('will not clear app data if dialog canceled', async () => {
+    mockShowDialog.mockResolvedValue(1);
+
+    await clearAppData(window);
+
+    expect(mockShowDialog).toHaveBeenCalledTimes(1);
+    expect(mockClearCache).not.toHaveBeenCalled();
+    expect(mockClearStorageData).not.toHaveBeenCalled();
+  });
+
+  test('will clear app data if ok is clicked', async () => {
+    mockShowDialog.mockResolvedValue(0);
+
+    await clearAppData(window);
+
+    expect(mockShowDialog).toHaveBeenCalledTimes(1);
+    expect(mockClearCache).not.toHaveBeenCalledTimes(1);
+    expect(mockClearStorageData).not.toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('createNewTab', () => {
+  // const window = new BrowserWindow();
+  const options: WindowOptions = {
+    autoHideMenuBar: true,
+    blockExternalUrls: false,
+    insecure: false,
+    name: 'Test App',
+    targetUrl: 'https://github.com/nativefier/natifefier',
+    zoom: 1.0,
+  } as WindowOptions;
+  const setupWindow = jest.fn();
+  const url = 'https://github.com/nativefier/nativefier';
+  const mockAddTabbedWindow: jest.SpyInstance = jest.spyOn(
+    BrowserWindow.prototype,
+    'addTabbedWindow',
+  );
+  const mockFocus: jest.SpyInstance = jest.spyOn(
+    BrowserWindow.prototype,
+    'focus',
+  );
+  const mockLoadURL: jest.SpyInstance = jest.spyOn(
+    BrowserWindow.prototype,
+    'loadURL',
+  );
+
+  test('creates new foreground tab', () => {
+    const foreground = true;
+
+    const tab = createNewTab(options, setupWindow, url, foreground);
+
+    expect(mockAddTabbedWindow).toHaveBeenCalledWith(tab);
+    expect(setupWindow).toHaveBeenCalledWith(options, tab);
+    expect(mockLoadURL).toHaveBeenCalledWith(url);
+    expect(mockFocus).not.toHaveBeenCalled();
+  });
+
+  test('creates new background tab', () => {
+    const foreground = false;
+
+    const tab = createNewTab(
+      options,
+      setupWindow,
+      url,
+      foreground,
+      // window
+    );
+
+    expect(mockAddTabbedWindow).toHaveBeenCalledWith(tab);
+    expect(setupWindow).toHaveBeenCalledWith(options, tab);
+    expect(mockLoadURL).toHaveBeenCalledWith(url);
+    expect(mockFocus).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('injectCSS', () => {
+  jest.setTimeout(10000);
+
+  const mockGetCSSToInject: jest.SpyInstance = getCSSToInject as jest.Mock;
+  const mockLogError: jest.SpyInstance = error as jest.Mock;
+
+  const css = 'body { color: white; }';
+  let responseHeaders: Record<string, string[]>;
+
+  beforeEach(() => {
+    mockGetCSSToInject.mockReset().mockReturnValue('');
+    mockLogError.mockReset();
+    responseHeaders = { 'x-header': ['value'], 'content-type': ['test/other'] };
+  });
+
+  afterAll(() => {
+    mockGetCSSToInject.mockRestore();
+    mockLogError.mockRestore();
+  });
+
+  test('will not inject if getCSSToInject is empty', () => {
+    const window = new BrowserWindow();
+    const mockWebContentsInsertCSS: jest.SpyInstance = jest
+      .spyOn(window.webContents, 'insertCSS')
+      .mockResolvedValue('');
+    jest
+      .spyOn(window.webContents, 'getURL')
+      .mockReturnValue('https://example.com');
+
+    injectCSS(window);
+
+    expect(mockGetCSSToInject).toHaveBeenCalled();
+    expect(mockWebContentsInsertCSS).not.toHaveBeenCalled();
+  });
+
+  test('will inject on did-navigate + onResponseStarted', () => {
+    mockGetCSSToInject.mockReturnValue(css);
+    const window = new BrowserWindow();
+    const mockWebContentsInsertCSS: jest.SpyInstance = jest
+      .spyOn(window.webContents, 'insertCSS')
+      .mockResolvedValue('');
+    jest
+      .spyOn(window.webContents, 'getURL')
+      .mockReturnValue('https://example.com');
+
+    injectCSS(window);
+
+    expect(mockGetCSSToInject).toHaveBeenCalled();
+
+    window.webContents.emit('did-navigate');
+    // @ts-expect-error this function doesn't exist in the actual electron version, but will in our mock
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    window.webContents.session.webRequest.send('onResponseStarted', {
+      responseHeaders,
+      webContents: window.webContents,
+    });
+
+    expect(mockWebContentsInsertCSS).toHaveBeenCalledWith(css);
+  });
+
+  test.each<string>(['application/json', 'font/woff2', 'image/png'])(
+    'will not inject for content-type %s',
+    (contentType: string) => {
+      mockGetCSSToInject.mockReturnValue(css);
+      const window = new BrowserWindow();
+      const mockWebContentsInsertCSS: jest.SpyInstance = jest
+        .spyOn(window.webContents, 'insertCSS')
+        .mockResolvedValue('');
+      jest
+        .spyOn(window.webContents, 'getURL')
+        .mockReturnValue('https://example.com');
+
+      responseHeaders['content-type'] = [contentType];
+
+      injectCSS(window);
+
+      expect(mockGetCSSToInject).toHaveBeenCalled();
+
+      expect(window.webContents.emit('did-navigate')).toBe(true);
+      mockWebContentsInsertCSS.mockReset().mockResolvedValue(undefined);
+      // @ts-expect-error this function doesn't exist in the actual electron version, but will in our mock
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      window.webContents.session.webRequest.send('onResponseStarted', {
+        responseHeaders,
+        webContents: window.webContents,
+        url: `test-${contentType}`,
+      });
+      // insertCSS will still run once for the did-navigate
+      expect(mockWebContentsInsertCSS).not.toHaveBeenCalled();
+    },
+  );
+
+  test.each<string>(['text/html'])(
+    'will inject for content-type %s',
+    (contentType: string) => {
+      mockGetCSSToInject.mockReturnValue(css);
+      const window = new BrowserWindow();
+      const mockWebContentsInsertCSS: jest.SpyInstance = jest
+        .spyOn(window.webContents, 'insertCSS')
+        .mockResolvedValue('');
+      jest
+        .spyOn(window.webContents, 'getURL')
+        .mockReturnValue('https://example.com');
+
+      responseHeaders['content-type'] = [contentType];
+
+      injectCSS(window);
+
+      expect(mockGetCSSToInject).toHaveBeenCalled();
+
+      window.webContents.emit('did-navigate');
+      mockWebContentsInsertCSS.mockReset().mockResolvedValue(undefined);
+      // @ts-expect-error this function doesn't exist in the actual electron version, but will in our mock
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      window.webContents.session.webRequest.send('onResponseStarted', {
+        responseHeaders,
+        webContents: window.webContents,
+        url: `test-${contentType}`,
+      });
+
+      expect(mockWebContentsInsertCSS).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  test.each<string>(['image', 'script', 'stylesheet', 'xhr'])(
+    'will not inject for resource type %s',
+    (resourceType: string) => {
+      mockGetCSSToInject.mockReturnValue(css);
+      const window = new BrowserWindow();
+      const mockWebContentsInsertCSS: jest.SpyInstance = jest
+        .spyOn(window.webContents, 'insertCSS')
+        .mockResolvedValue('');
+      jest
+        .spyOn(window.webContents, 'getURL')
+        .mockReturnValue('https://example.com');
+
+      injectCSS(window);
+
+      expect(mockGetCSSToInject).toHaveBeenCalled();
+
+      window.webContents.emit('did-navigate');
+      mockWebContentsInsertCSS.mockReset().mockResolvedValue(undefined);
+      // @ts-expect-error this function doesn't exist in the actual electron version, but will in our mock
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      window.webContents.session.webRequest.send('onResponseStarted', {
+        responseHeaders,
+        webContents: window.webContents,
+        resourceType,
+        url: `test-${resourceType}`,
+      });
+      // insertCSS will still run once for the did-navigate
+      expect(mockWebContentsInsertCSS).not.toHaveBeenCalled();
+    },
+  );
+
+  test.each<string>(['html', 'other'])(
+    'will inject for resource type %s',
+    (resourceType: string) => {
+      mockGetCSSToInject.mockReturnValue(css);
+      const window = new BrowserWindow();
+      const mockWebContentsInsertCSS: jest.SpyInstance = jest
+        .spyOn(window.webContents, 'insertCSS')
+        .mockResolvedValue('');
+      jest
+        .spyOn(window.webContents, 'getURL')
+        .mockReturnValue('https://example.com');
+
+      injectCSS(window);
+
+      expect(mockGetCSSToInject).toHaveBeenCalled();
+
+      window.webContents.emit('did-navigate');
+      mockWebContentsInsertCSS.mockReset().mockResolvedValue(undefined);
+      // @ts-expect-error this function doesn't exist in the actual electron version, but will in our mock
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      window.webContents.session.webRequest.send('onResponseStarted', {
+        responseHeaders,
+        webContents: window.webContents,
+        resourceType,
+        url: `test-${resourceType}`,
+      });
+      expect(mockWebContentsInsertCSS).toHaveBeenCalledTimes(1);
+    },
+  );
+});

app/src/helpers/windowHelpers.ts

@@ -0,0 +1,365 @@
+import path from 'path';
+
+import {
+  dialog,
+  BrowserWindow,
+  BrowserWindowConstructorOptions,
+  Event,
+  MessageBoxReturnValue,
+  WebPreferences,
+  OnResponseStartedListenerDetails,
+} from 'electron';
+
+import { getCSSToInject, isOSX, nativeTabsSupported } from './helpers';
+import * as log from './loggingHelper';
+import { TrayValue, WindowOptions } from '../../../shared/src/options/model';
+import { randomUUID } from 'crypto';
+
+const ZOOM_INTERVAL = 0.1;
+
+export function adjustWindowZoom(adjustment: number): void {
+  withFocusedWindow((focusedWindow: BrowserWindow) => {
+    focusedWindow.webContents.zoomFactor =
+      focusedWindow.webContents.zoomFactor + adjustment;
+  });
+}
+
+export function showNavigationBlockedMessage(
+  message: string,
+): Promise<MessageBoxReturnValue> {
+  return new Promise((resolve, reject) => {
+    withFocusedWindow((focusedWindow) => {
+      dialog
+        .showMessageBox(focusedWindow, {
+          message,
+          type: 'error',
+          title: 'Navigation blocked',
+        })
+        .then((result) => resolve(result))
+        .catch((err) => {
+          reject(err);
+        });
+    });
+  });
+}
+
+export async function clearAppData(window: BrowserWindow): Promise<void> {
+  const response = await dialog.showMessageBox(window, {
+    type: 'warning',
+    buttons: ['Yes', 'Cancel'],
+    defaultId: 1,
+    title: 'Clear cache confirmation',
+    message:
+      'This will clear all data (cookies, local storage etc) from this app. Are you sure you wish to proceed?',
+  });
+
+  if (response.response !== 0) {
+    return;
+  }
+  await clearCache(window);
+}
+
+export async function clearCache(window: BrowserWindow): Promise<void> {
+  const { session } = window.webContents;
+  await session.clearStorageData();
+  await session.clearCache();
+}
+
+export function createAboutBlankWindow(
+  options: WindowOptions,
+  setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+  parent?: BrowserWindow,
+): BrowserWindow {
+  const window = createNewWindow(
+    { ...options, show: false },
+    setupWindow,
+    'about:blank',
+    nativeTabsSupported() ? undefined : parent,
+  );
+  window.webContents.once('did-stop-loading', () => {
+    if (window.webContents.getURL() === 'about:blank') {
+      window.close();
+    } else {
+      window.show();
+    }
+  });
+  return window;
+}
+
+export function createNewTab(
+  options: WindowOptions,
+  setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+  url: string,
+  foreground: boolean,
+): BrowserWindow | undefined {
+  const focusedWindow = BrowserWindow.getFocusedWindow();
+  log.debug('createNewTab', {
+    url,
+    foreground,
+    focusedWindow,
+  });
+  return withFocusedWindow((focusedWindow) => {
+    const newTab = createNewWindow(options, setupWindow, url);
+    log.debug('createNewTab.withFocusedWindow', { focusedWindow, newTab });
+    focusedWindow.addTabbedWindow(newTab);
+    if (!foreground) {
+      focusedWindow.focus();
+    }
+    return newTab;
+  });
+}
+
+export function createNewWindow(
+  options: WindowOptions,
+  setupWindow: (options: WindowOptions, window: BrowserWindow) => void,
+  url: string,
+  parent?: BrowserWindow,
+): BrowserWindow {
+  log.debug('createNewWindow', {
+    url,
+    parent,
+  });
+  const window = new BrowserWindow({
+    parent: nativeTabsSupported() ? undefined : parent,
+    ...getDefaultWindowOptions(options),
+  });
+  setupWindow(options, window);
+  window.loadURL(url).catch((err) => log.error('window.loadURL ERROR', err));
+  return window;
+}
+
+export function getCurrentURL(): string {
+  return withFocusedWindow((focusedWindow) =>
+    focusedWindow.webContents.getURL(),
+  ) as unknown as string;
+}
+
+export function getDefaultWindowOptions(
+  options: WindowOptions,
+): BrowserWindowConstructorOptions {
+  const browserwindowOptions: BrowserWindowConstructorOptions = {
+    ...options.browserwindowOptions,
+  };
+  // We're going to remove this and merge it separately into DEFAULT_WINDOW_OPTIONS.webPreferences
+  // Otherwise the browserwindowOptions.webPreferences object will completely replace the
+  // webPreferences specified in the DEFAULT_WINDOW_OPTIONS with itself
+  delete browserwindowOptions.webPreferences;
+
+  const webPreferences: WebPreferences = {
+    ...(options.browserwindowOptions?.webPreferences ?? {}),
+  };
+
+  const defaultOptions: BrowserWindowConstructorOptions = {
+    autoHideMenuBar: options.autoHideMenuBar,
+    fullscreenable: true,
+    tabbingIdentifier: nativeTabsSupported()
+      ? options.tabbingIdentifier ?? randomUUID()
+      : undefined,
+    title: options.name,
+    webPreferences: {
+      javascript: true,
+      nodeIntegration: false, // `true` is *insecure*, and cause trouble with messenger.com
+      preload: path.join(__dirname, 'preload.js'),
+      plugins: true,
+      sandbox: false, // https://www.electronjs.org/blog/electron-20-0#default-changed-renderers-without-nodeintegration-true-are-sandboxed-by-default
+      webSecurity: !options.insecure,
+      zoomFactor: options.zoom,
+      // `contextIsolation` was switched to true in Electron 12, which:
+      // 1. Breaks access to global variables in `--inject`-ed scripts:
+      //    https://github.com/nativefier/nativefier/issues/1269
+      // 2. Might break notifications under Windows, although this was refuted:
+      //    https://github.com/nativefier/nativefier/issues/1292
+      // So, it was flipped to false in https://github.com/nativefier/nativefier/pull/1308
+      //
+      // If attempting to set it back to `true` (for security),
+      // do test exhaustively these two areas, and more.
+      contextIsolation: false,
+      ...webPreferences,
+    },
+    ...browserwindowOptions,
+  };
+
+  log.debug('getDefaultWindowOptions', {
+    options,
+    webPreferences,
+    defaultOptions,
+  });
+
+  return defaultOptions;
+}
+
+export function goBack(): void {
+  log.debug('onGoBack');
+  withFocusedWindow((focusedWindow) => {
+    focusedWindow.webContents.goBack();
+  });
+}
+
+export function goForward(): void {
+  log.debug('onGoForward');
+  withFocusedWindow((focusedWindow) => {
+    focusedWindow.webContents.goForward();
+  });
+}
+
+export function goToURL(url: string): Promise<void> | undefined {
+  return withFocusedWindow((focusedWindow) => focusedWindow.loadURL(url));
+}
+
+export function hideWindow(
+  window: BrowserWindow,
+  event: Event,
+  fastQuit: boolean,
+  tray: TrayValue,
+): void {
+  if (isOSX() && !fastQuit) {
+    // this is called when exiting from clicking the cross button on the window
+    event.preventDefault();
+    window.hide();
+  } else if (!fastQuit && tray !== 'false') {
+    event.preventDefault();
+    window.hide();
+  }
+  // will close the window on other platforms
+}
+
+export function injectCSS(browserWindow: BrowserWindow): void {
+  const cssToInject = getCSSToInject();
+
+  if (!cssToInject) {
+    return;
+  }
+
+  browserWindow.webContents.on('did-navigate', () => {
+    log.debug(
+      'browserWindow.webContents.did-navigate',
+      browserWindow.webContents.getURL(),
+    );
+
+    browserWindow.webContents
+      .insertCSS(cssToInject)
+      .catch((err: unknown) =>
+        log.error('browserWindow.webContents.insertCSS', err),
+      );
+
+    // We must inject css early enough; so onResponseStarted is a good place.
+    browserWindow.webContents.session.webRequest.onResponseStarted(
+      { urls: [] }, // Pass an empty filter list; null will not match _any_ urls
+      (details: OnResponseStartedListenerDetails): void => {
+        log.debug('onResponseStarted', {
+          resourceType: details.resourceType,
+          url: details.url,
+        });
+        injectCSSIntoResponse(details, cssToInject).catch((err: unknown) => {
+          log.error('injectCSSIntoResponse ERROR', err);
+        });
+      },
+    );
+  });
+}
+
+function injectCSSIntoResponse(
+  details: OnResponseStartedListenerDetails,
+  cssToInject: string,
+): Promise<string | undefined> {
+  const contentType =
+    details.responseHeaders && 'content-type' in details.responseHeaders
+      ? details.responseHeaders['content-type'][0]
+      : undefined;
+
+  log.debug('injectCSSIntoResponse', { details, cssToInject, contentType });
+
+  // We go with a denylist rather than a whitelist (e.g. only text/html)
+  // to avoid "whoops I didn't think this should have been CSS-injected" cases
+  const nonInjectableContentTypes = [
+    /application\/.*/,
+    /font\/.*/,
+    /image\/.*/,
+  ];
+  const nonInjectableResourceTypes = ['image', 'script', 'stylesheet', 'xhr'];
+
+  if (
+    (contentType &&
+      nonInjectableContentTypes.filter((x) => {
+        const matches = x.exec(contentType);
+        return matches && matches?.length > 0;
+      })?.length > 0) ||
+    nonInjectableResourceTypes.includes(details.resourceType) ||
+    !details.webContents
+  ) {
+    log.debug(
+      `Skipping CSS injection for:\n${details.url}\nwith resourceType ${
+        details.resourceType
+      } and content-type ${contentType as string}`,
+    );
+    return Promise.resolve(undefined);
+  }
+
+  log.debug(
+    `Injecting CSS for:\n${details.url}\nwith resourceType ${
+      details.resourceType
+    } and content-type ${contentType as string}`,
+  );
+  return details.webContents.insertCSS(cssToInject);
+}
+
+export function sendParamsOnDidFinishLoad(
+  options: WindowOptions,
+  window: BrowserWindow,
+): void {
+  window.webContents.on('did-finish-load', () => {
+    log.debug(
+      'sendParamsOnDidFinishLoad.window.webContents.did-finish-load',
+      window.webContents.getURL(),
+    );
+    // In children windows too: Restore pinch-to-zoom, disabled by default in recent Electron.
+    // See https://github.com/nativefier/nativefier/issues/379#issuecomment-598612128
+    // and https://github.com/electron/electron/pull/12679
+    window.webContents
+      .setVisualZoomLevelLimits(1, 3)
+      .catch((err) => log.error('webContents.setVisualZoomLevelLimits', err));
+
+    window.webContents.send('params', JSON.stringify(options));
+  });
+}
+
+export function setProxyRules(
+  window: BrowserWindow,
+  proxyRules?: string,
+): void {
+  window.webContents.session
+    .setProxy({
+      proxyRules,
+      pacScript: '',
+      proxyBypassRules: '',
+    })
+    .catch((err) => log.error('session.setProxy ERROR', err));
+}
+
+export function withFocusedWindow<T>(
+  block: (window: BrowserWindow) => T,
+): T | undefined {
+  const focusedWindow = BrowserWindow.getFocusedWindow();
+  if (focusedWindow) {
+    return block(focusedWindow);
+  }
+
+  return undefined;
+}
+
+export function zoomOut(): void {
+  log.debug('zoomOut');
+  adjustWindowZoom(-ZOOM_INTERVAL);
+}
+
+export function zoomReset(options: { zoom?: number }): void {
+  log.debug('zoomReset');
+  withFocusedWindow((focusedWindow) => {
+    focusedWindow.webContents.zoomFactor = options.zoom ?? 1.0;
+  });
+}
+
+export function zoomIn(): void {
+  log.debug('zoomIn');
+  adjustWindowZoom(ZOOM_INTERVAL);
+}

app/src/main.ts

@@ -0,0 +1,458 @@
+import 'source-map-support/register';
+
+import fs from 'fs';
+import * as path from 'path';
+
+import electron, {
+  app,
+  dialog,
+  globalShortcut,
+  systemPreferences,
+  BrowserWindow,
+  Event,
+} from 'electron';
+import electronDownload from 'electron-dl';
+
+import { createLoginWindow } from './components/loginWindow';
+import {
+  createMainWindow,
+  saveAppArgs,
+  APP_ARGS_FILE_PATH,
+} from './components/mainWindow';
+import { createTrayIcon } from './components/trayIcon';
+import {
+  isOSX,
+  isWayland,
+  isWindows,
+  removeUserAgentSpecifics,
+} from './helpers/helpers';
+import { inferFlashPath } from './helpers/inferFlash';
+import * as log from './helpers/loggingHelper';
+import {
+  IS_PLAYWRIGHT,
+  PLAYWRIGHT_CONFIG,
+  safeGetEnv,
+} from './helpers/playwrightHelpers';
+import { OutputOptions } from '../../shared/src/options/model';
+
+// Entrypoint for Squirrel, a windows update framework. See https://github.com/nativefier/nativefier/pull/744
+if (require('electron-squirrel-startup')) {
+  app.exit();
+}
+
+if (process.argv.indexOf('--verbose') > -1 || safeGetEnv('VERBOSE') === '1') {
+  log.setLevel('DEBUG');
+  process.traceDeprecation = true;
+  process.traceProcessWarnings = true;
+  process.argv.slice(1);
+}
+
+let mainWindow: BrowserWindow;
+
+const appArgs =
+  IS_PLAYWRIGHT && PLAYWRIGHT_CONFIG
+    ? (JSON.parse(PLAYWRIGHT_CONFIG) as OutputOptions)
+    : (JSON.parse(
+        fs.readFileSync(APP_ARGS_FILE_PATH, 'utf8'),
+      ) as OutputOptions);
+
+log.debug('appArgs', appArgs);
+// Do this relatively early so that we can start storing appData with the app
+if (appArgs.portable) {
+  log.debug(
+    'App was built as portable; setting appData and userData to the app folder: ',
+    path.resolve(path.join(__dirname, '..', 'appData')),
+  );
+  app.setPath('appData', path.join(__dirname, '..', 'appData'));
+  app.setPath('userData', path.join(__dirname, '..', 'appData'));
+}
+
+if (!appArgs.userAgentHonest) {
+  if (appArgs.userAgent) {
+    app.userAgentFallback = appArgs.userAgent;
+  } else {
+    app.userAgentFallback = removeUserAgentSpecifics(
+      app.userAgentFallback,
+      app.getName(),
+      app.getVersion(),
+    );
+  }
+}
+
+// this step is required to allow app names to be displayed correctly in notifications on windows
+// https://www.electronjs.org/docs/latest/api/app#appsetappusermodelidid-windows
+// https://www.electronjs.org/docs/latest/tutorial/notifications#windows
+if (isWindows()) {
+  app.setAppUserModelId(app.getName());
+}
+
+const urlArgv = process.argv.filter((a) => a.startsWith('http'));
+
+// Take in a URL on the command line as an override
+if (urlArgv.length > 0) {
+  const maybeUrl = urlArgv[0];
+  try {
+    new URL(maybeUrl);
+    appArgs.targetUrl = maybeUrl;
+    log.info('Loading override URL passed as argument:', maybeUrl);
+  } catch (err: unknown) {
+    log.error(
+      'Not loading override URL passed as argument, because failed to parse:',
+      maybeUrl,
+      err,
+    );
+  }
+}
+
+// Nativefier is a browser, and an old browser is an insecure / badly-performant one.
+// Given our builder/app design, we currently don't have an easy way to offer
+// upgrades from the app themselves (like browsers do).
+// As a workaround, we ask for a manual upgrade & re-build if the build is old.
+// The period in days is chosen to be not too small to be exceedingly annoying,
+// but not too large to be exceedingly insecure.
+const OLD_BUILD_WARNING_THRESHOLD_DAYS = 90;
+const OLD_BUILD_WARNING_THRESHOLD_MS =
+  OLD_BUILD_WARNING_THRESHOLD_DAYS * 24 * 60 * 60 * 1000;
+
+const fileDownloadOptions = { ...appArgs.fileDownloadOptions };
+electronDownload(fileDownloadOptions);
+
+if (appArgs.processEnvs) {
+  let processEnvs: Record<string, string> =
+    appArgs.processEnvs as unknown as Record<string, string>;
+  // This is compatibility if just a string was passed.
+  if (typeof appArgs.processEnvs === 'string') {
+    try {
+      processEnvs = JSON.parse(appArgs.processEnvs) as Record<string, string>;
+    } catch {
+      // This wasn't JSON. Fall back to the old code
+      processEnvs = {};
+      process.env.processEnvs = appArgs.processEnvs;
+    }
+  }
+  Object.keys(processEnvs)
+    .filter((key) => key !== undefined)
+    .forEach((key) => {
+      process.env[key] = processEnvs[key];
+    });
+}
+
+if (typeof appArgs.flashPluginDir === 'string') {
+  app.commandLine.appendSwitch('ppapi-flash-path', appArgs.flashPluginDir);
+} else if (appArgs.flashPluginDir) {
+  const flashPath = inferFlashPath();
+  app.commandLine.appendSwitch('ppapi-flash-path', flashPath);
+}
+
+if (appArgs.ignoreCertificate) {
+  app.commandLine.appendSwitch('ignore-certificate-errors');
+}
+
+if (appArgs.disableGpu) {
+  app.disableHardwareAcceleration();
+}
+
+if (appArgs.ignoreGpuBlacklist) {
+  app.commandLine.appendSwitch('ignore-gpu-blacklist');
+}
+
+if (appArgs.enableEs3Apis) {
+  app.commandLine.appendSwitch('enable-es3-apis');
+}
+
+if (appArgs.diskCacheSize) {
+  app.commandLine.appendSwitch(
+    'disk-cache-size',
+    appArgs.diskCacheSize.toString(),
+  );
+}
+
+if (appArgs.basicAuthUsername) {
+  app.commandLine.appendSwitch(
+    'basic-auth-username',
+    appArgs.basicAuthUsername,
+  );
+}
+
+if (appArgs.basicAuthPassword) {
+  app.commandLine.appendSwitch(
+    'basic-auth-password',
+    appArgs.basicAuthPassword,
+  );
+}
+
+if (isWayland()) {
+  app.commandLine.appendSwitch('enable-features', 'WebRTCPipeWireCapturer');
+}
+
+if (appArgs.lang) {
+  const langParts = appArgs.lang.split(',');
+  // Convert locales to languages, because for some reason locales don't work. Stupid Chromium
+  const langPartsParsed = Array.from(
+    // Convert to set to dedupe in case something like "en-GB,en-US" was passed
+    new Set(langParts.map((l) => l.split('-')[0])),
+  );
+  const langFlag = langPartsParsed.join(',');
+  log.debug('Setting --lang flag to', langFlag);
+  app.commandLine.appendSwitch('--lang', langFlag);
+}
+
+let currentBadgeCount = 0;
+const setDockBadge = isOSX()
+  ? (count?: number | string, bounce = false): void => {
+      if (count !== undefined) {
+        app.dock.setBadge(count.toString());
+        if (bounce && typeof count === 'number' && count > currentBadgeCount)
+          app.dock.bounce();
+        currentBadgeCount = typeof count === 'number' ? count : 0;
+      }
+    }
+  : (): void => undefined;
+
+app.on('window-all-closed', () => {
+  log.debug('app.window-all-closed');
+  if (!isOSX() || appArgs.fastQuit || IS_PLAYWRIGHT) {
+    app.quit();
+  }
+});
+
+app.on('before-quit', () => {
+  log.debug('app.before-quit');
+  // not fired when the close button on the window is clicked
+  if (isOSX()) {
+    // need to force a quit as a workaround here to simulate the osx app hiding behaviour
+    // Somehow sokution at https://github.com/atom/electron/issues/444#issuecomment-76492576 does not work,
+    // e.prevent default appears to persist
+
+    // might cause issues in the future as before-quit and will-quit events are not called
+    app.exit(0);
+  }
+});
+
+app.on('will-quit', (event) => {
+  log.debug('app.will-quit', event);
+});
+
+app.on('quit', (event, exitCode) => {
+  log.debug('app.quit', { event, exitCode });
+});
+
+app.on('will-finish-launching', () => {
+  log.debug('app.will-finish-launching');
+});
+
+app.on('open-url', (event, url) => {
+  log.debug('app.open-url', { event, url });
+
+  event.preventDefault();
+  if (mainWindow) {
+    mainWindow.webContents.send('open-url', url);
+  }
+});
+
+if (appArgs.widevine) {
+  // @ts-expect-error This event only appears on the widevine version of electron, which we'd see at runtime
+  app.on('widevine-ready', (version: string, lastVersion: string) => {
+    log.debug('app.widevine-ready', { version, lastVersion });
+    onReady().catch((err) => log.error('onReady ERROR', err));
+  });
+
+  app.on(
+    // @ts-expect-error This event only appears on the widevine version of electron, which we'd see at runtime
+    'widevine-update-pending',
+    (currentVersion: string, pendingVersion: string) => {
+      log.debug('app.widevine-update-pending', {
+        currentVersion,
+        pendingVersion,
+      });
+    },
+  );
+
+  // @ts-expect-error This event only appears on the widevine version of electron, which we'd see at runtime
+  app.on('widevine-error', (error: Error) => {
+    log.error('app.widevine-error', error);
+  });
+} else {
+  app.on('ready', () => {
+    log.debug('ready');
+    onReady().catch((err) => log.error('onReady ERROR', err));
+  });
+}
+
+app.on('activate', (event: electron.Event, hasVisibleWindows: boolean) => {
+  log.debug('app.activate', { event, hasVisibleWindows });
+  if (isOSX() && !IS_PLAYWRIGHT) {
+    // this is called when the dock is clicked
+    if (!hasVisibleWindows) {
+      mainWindow.show();
+    }
+  }
+});
+
+// quit if singleInstance mode and there's already another instance running
+const shouldQuit = appArgs.singleInstance && !app.requestSingleInstanceLock();
+if (shouldQuit) {
+  app.quit();
+} else {
+  app.on('second-instance', () => {
+    log.debug('app.second-instance');
+    if (mainWindow) {
+      if (!mainWindow.isVisible()) {
+        // try
+        mainWindow.show();
+      }
+      if (mainWindow.isMinimized()) {
+        // minimized
+        mainWindow.restore();
+      }
+      mainWindow.focus();
+    }
+  });
+}
+
+app.on('new-window-for-tab', (event: Event) => {
+  log.debug('app.new-window-for-tab', { event });
+  if (mainWindow) {
+    mainWindow.emit('new-window-for-tab', event);
+  }
+});
+
+app.on(
+  'login',
+  (
+    event,
+    webContents,
+    request,
+    authInfo,
+    callback: (username?: string, password?: string) => void,
+  ) => {
+    log.debug('app.login', { event, request });
+    // for http authentication
+    event.preventDefault();
+
+    if (appArgs.basicAuthUsername && appArgs.basicAuthPassword) {
+      callback(appArgs.basicAuthUsername, appArgs.basicAuthPassword);
+    } else {
+      createLoginWindow(
+        callback,
+        // mainWindow
+      ).catch((err) => log.error('createLoginWindow ERROR', err));
+    }
+  },
+);
+
+async function onReady(): Promise<void> {
+  // Warning: `mainWindow` below is the *global* unique `mainWindow`, created at init time
+  mainWindow = await createMainWindow(appArgs, setDockBadge);
+
+  createTrayIcon(appArgs, mainWindow);
+
+  // Register global shortcuts
+  if (appArgs.globalShortcuts) {
+    appArgs.globalShortcuts.forEach((shortcut) => {
+      globalShortcut.register(shortcut.key, () => {
+        shortcut.inputEvents.forEach((inputEvent) => {
+          // @ts-expect-error without including electron in our models, these will never match
+          mainWindow.webContents.sendInputEvent(inputEvent);
+        });
+      });
+    });
+
+    if (isOSX() && appArgs.accessibilityPrompt) {
+      const mediaKeys = [
+        'MediaPlayPause',
+        'MediaNextTrack',
+        'MediaPreviousTrack',
+        'MediaStop',
+      ];
+      const globalShortcutsKeys = appArgs.globalShortcuts.map((g) => g.key);
+      const mediaKeyWasSet = globalShortcutsKeys.find((g) =>
+        mediaKeys.includes(g),
+      );
+      if (
+        mediaKeyWasSet &&
+        !systemPreferences.isTrustedAccessibilityClient(false)
+      ) {
+        // Since we're trying to set global keyboard shortcuts for media keys, we need to prompt
+        // the user for permission on Mac.
+        // For reference:
+        // https://www.electronjs.org/docs/api/global-shortcut?q=MediaPlayPause#globalshortcutregisteraccelerator-callback
+        const accessibilityPromptResult = dialog.showMessageBoxSync(
+          mainWindow,
+          {
+            type: 'question',
+            message: 'Accessibility Permissions Needed',
+            buttons: ['Yes', 'No', 'No and never ask again'],
+            defaultId: 0,
+            detail:
+              `${appArgs.name} would like to use one or more of your keyboard's media keys (start, stop, next track, or previous track) to control it.\n\n` +
+              `Would you like Mac OS to ask for your permission to do so?\n\n` +
+              `If so, you will need to restart ${appArgs.name} after granting permissions for these keyboard shortcuts to begin working.`,
+          },
+        );
+        switch (accessibilityPromptResult) {
+          // User clicked Yes, prompt for accessibility
+          case 0:
+            systemPreferences.isTrustedAccessibilityClient(true);
+            break;
+          // User cliecked Never Ask Me Again, save that info
+          case 2:
+            appArgs.accessibilityPrompt = false;
+            saveAppArgs(appArgs);
+            break;
+          // User clicked No
+          default:
+            break;
+        }
+      }
+    }
+  }
+  if (
+    !appArgs.disableOldBuildWarning &&
+    new Date().getTime() - appArgs.buildDate > OLD_BUILD_WARNING_THRESHOLD_MS
+  ) {
+    const oldBuildWarningText =
+      appArgs.oldBuildWarningText ||
+      'This app was built a long time ago. Nativefier uses the Chrome browser (through Electron), and it is insecure to keep using an old version of it. Please upgrade Nativefier and rebuild this app.';
+    dialog
+      .showMessageBox(mainWindow, {
+        type: 'warning',
+        message: 'Old build detected',
+        detail: oldBuildWarningText,
+      })
+      .catch((err) => log.error('dialog.showMessageBox ERROR', err));
+  }
+
+  if (appArgs.targetUrl) {
+    await mainWindow.loadURL(appArgs.targetUrl);
+  }
+}
+
+app.on(
+  'accessibility-support-changed',
+  (event: Event, accessibilitySupportEnabled: boolean) => {
+    log.debug('app.accessibility-support-changed', {
+      event,
+      accessibilitySupportEnabled,
+    });
+  },
+);
+
+app.on(
+  'activity-was-continued',
+  (event: Event, type: string, userInfo: unknown) => {
+    log.debug('app.activity-was-continued', { event, type, userInfo });
+  },
+);
+
+app.on('browser-window-blur', () => {
+  log.debug('app.browser-window-blur');
+});
+
+app.on('browser-window-created', () => {
+  log.debug('app.browser-window-created');
+});
+
+app.on('browser-window-focus', () => {
+  log.debug('app.browser-window-focus');
+});

app/src/mocks/electron.ts

@@ -0,0 +1,160 @@
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { EventEmitter } from 'events';
+
+/*
+  These mocks are PURPOSEFULLY minimal. A few reasons as to why:
+  1. I'm l̶a̶z̶y̶ a busy person :)
+  2. The less we have in here, the less we'll need to fix if an electron API changes
+  3. Only mocking what we need as we need it helps reveal areas under test where electron
+     is being accessed in previously unaccounted for ways
+  4. These mocks will get fleshed out as more unit tests are added, so if you need
+     something here as you are adding unit tests, then feel free to add exactly what you
+     need (and no more than that please).
+
+  As well, please resist the urge to turn this into a reimplimentation of electron.
+  When adding functions/classes, keep your implementation to only the minimal amount of code
+  it takes for TypeScript to recognize what you are doing. For anything more complex (including
+  implementation code and return values) please do that within your tests via jest with
+  mockImplementation or mockReturnValue.
+*/
+
+class MockBrowserWindow extends EventEmitter {
+  webContents: MockWebContents;
+
+  constructor(options?: unknown) {
+    // @ts-expect-error options is really EventEmitterOptions, but events.d.ts doesn't expose it...
+    super(options);
+    this.webContents = new MockWebContents();
+  }
+
+  addTabbedWindow(tab: MockBrowserWindow): void {
+    return;
+  }
+
+  focus(): void {
+    return;
+  }
+
+  static fromWebContents(webContents: MockWebContents): MockBrowserWindow {
+    return new MockBrowserWindow();
+  }
+
+  static getFocusedWindow(window: MockBrowserWindow): MockBrowserWindow {
+    return window ?? new MockBrowserWindow();
+  }
+
+  isSimpleFullScreen(): boolean {
+    throw new Error('Not implemented');
+  }
+
+  isFullScreen(): boolean {
+    throw new Error('Not implemented');
+  }
+
+  isFullScreenable(): boolean {
+    throw new Error('Not implemented');
+  }
+
+  loadURL(url: string, options?: unknown): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  setFullScreen(flag: boolean): void {
+    return;
+  }
+
+  setSimpleFullScreen(flag: boolean): void {
+    return;
+  }
+}
+
+class MockDialog {
+  static showMessageBox(
+    browserWindow: MockBrowserWindow,
+    options: unknown,
+  ): Promise<number> {
+    throw new Error('Not implemented');
+  }
+
+  static showMessageBoxSync(
+    browserWindow: MockBrowserWindow,
+    options: unknown,
+  ): number {
+    throw new Error('Not implemented');
+  }
+}
+
+class MockSession extends EventEmitter {
+  webRequest: MockWebRequest;
+
+  constructor() {
+    super();
+    this.webRequest = new MockWebRequest();
+  }
+
+  clearCache(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  clearStorageData(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+class MockWebContents extends EventEmitter {
+  session: MockSession;
+
+  constructor() {
+    super();
+    this.session = new MockSession();
+  }
+
+  getURL(): string {
+    throw new Error('Not implemented');
+  }
+
+  insertCSS(css: string, options?: unknown): Promise<string> {
+    throw new Error('Not implemented');
+  }
+}
+
+class MockWebRequest {
+  emitter: InternalEmitter;
+
+  constructor() {
+    this.emitter = new InternalEmitter();
+  }
+
+  onResponseStarted(
+    filter: unknown,
+    listener: ((details: unknown) => void) | null,
+  ): void {
+    if (listener) {
+      this.emitter.addListener('onResponseStarted', (details: unknown) =>
+        listener(details),
+      );
+    }
+  }
+
+  send(event: string, ...args: unknown[]): void {
+    this.emitter.emit(event, ...args);
+  }
+}
+
+class InternalEmitter extends EventEmitter {}
+
+const mockShell = {
+  openExternal(url: string, options?: unknown): Promise<void> {
+    return new Promise((resolve) => resolve());
+  },
+};
+
+export {
+  MockDialog as dialog,
+  MockBrowserWindow as BrowserWindow,
+  MockSession as Session,
+  MockWebContents as WebContents,
+  MockWebRequest as WebRequest,
+  mockShell as shell,
+};

app/src/preload.ts

@@ -0,0 +1,352 @@
+/**
+ * Preload file that will be executed in the renderer process.
+ * Note: This needs to be attached **prior to imports**, as imports
+ * would delay the attachment till after the event has been raised.
+ */
+document.addEventListener('DOMContentLoaded', () => {
+  injectScripts(); // eslint-disable-line @typescript-eslint/no-use-before-define
+});
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { ipcRenderer } from 'electron';
+import { OutputOptions } from '../../shared/src/options/model';
+
+// Do *NOT* add 3rd-party imports here in preload (except for webpack `externals` like electron).
+// They will work during development, but break in the prod build :-/ .
+// Electron doc isn't explicit about that, so maybe *we*'re doing something wrong.
+// At any rate, that's what we have now. If you want an import here, go ahead, but
+// verify that apps built with a non-devbuild nativefier (installed from tarball) work.
+// Recipe to monkey around this, assuming you git-cloned nativefier in /opt/nativefier/ :
+// cd /opt/nativefier/ && rm -f nativefier-43.1.0.tgz && npm run build && npm pack && mkdir -p ~/n4310/ && cd ~/n4310/ \
+//    && rm -rf ./* && npm i /opt/nativefier/nativefier-43.1.0.tgz && ./node_modules/.bin/nativefier 'google.com'
+// See https://github.com/nativefier/nativefier/issues/1175
+// and https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions / preload
+
+const log = console; // since we can't have `loglevel` here in preload
+
+export const INJECT_DIR = path.join(__dirname, '..', 'inject');
+
+/**
+ * Patches window.Notification to:
+ * - set a callback on a new Notification
+ * - set a callback for clicks on notifications
+ * @param createCallback
+ * @param clickCallback
+ */
+function setNotificationCallback(
+  createCallback: {
+    (title: string, opt: NotificationOptions): void;
+    (...args: unknown[]): void;
+  },
+  clickCallback: { (): void; (this: Notification, ev: Event): unknown },
+): void {
+  const OldNotify = window.Notification;
+  const newNotify = function (
+    title: string,
+    opt: NotificationOptions,
+  ): Notification {
+    createCallback(title, opt);
+    const instance = new OldNotify(title, opt);
+    instance.addEventListener('click', clickCallback);
+    return instance;
+  };
+  newNotify.requestPermission = OldNotify.requestPermission.bind(OldNotify);
+  Object.defineProperty(newNotify, 'permission', {
+    get: () => OldNotify.permission,
+  });
+
+  // @ts-expect-error TypeScript says its not compatible, but it works?
+  window.Notification = newNotify;
+}
+
+async function getDisplayMedia(
+  sourceId: number | string,
+): Promise<MediaStream> {
+  type OriginalVideoPropertyType = boolean | MediaTrackConstraints | undefined;
+  if (!window?.navigator?.mediaDevices) {
+    throw Error('window.navigator.mediaDevices is not present');
+  }
+  // Electron supports an outdated specification for mediaDevices,
+  // see https://www.electronjs.org/docs/latest/api/desktop-capturer/
+  const stream = await window.navigator.mediaDevices.getUserMedia({
+    audio: false,
+    video: {
+      mandatory: {
+        chromeMediaSource: 'desktop',
+        chromeMediaSourceId: sourceId,
+      },
+    } as unknown as OriginalVideoPropertyType,
+  });
+
+  return stream;
+}
+
+function setupScreenSharePickerStyles(id: string): void {
+  const screenShareStyles = document.createElement('style');
+  screenShareStyles.id = id;
+  screenShareStyles.innerHTML = `
+  .desktop-capturer-selection {
+    --overlay-color: hsla(0, 0%, 11.8%, 0.75);
+    --highlight-color: highlight;
+    --text-content-color: #fff;
+    --selection-button-color: hsl(180, 1.3%, 14.7%);
+  }
+  .desktop-capturer-selection {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100vh;
+    background: var(--overlay-color);
+    color: var(--text-content-color);
+    z-index: 10000000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .desktop-capturer-selection__close {
+    -moz-appearance: none;
+    -webkit-appearance: none;
+    appearance: none;
+    padding: 1rem;
+    color: inherit;
+    position: absolute;
+    left: 1rem;
+    top: 1rem;
+    cursor: pointer;
+  }
+  .desktop-capturer-selection__scroller {
+    width: 100%;
+    max-height: 100vh;
+    overflow-y: auto;
+  }
+  .desktop-capturer-selection__list {
+    max-width: calc(100% - 100px);
+    margin: 50px;
+    padding: 0;
+    display: flex;
+    flex-wrap: wrap;
+    list-style: none;
+    overflow: hidden;
+    justify-content: center;
+  }
+  .desktop-capturer-selection__item {
+    display: flex;
+    margin: 4px;
+  }
+  .desktop-capturer-selection__btn {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    width: 145px;
+    margin: 0;
+    border: 0;
+    border-radius: 3px;
+    padding: 4px;
+    background: var(--selection-button-color);
+    text-align: left;
+    transition: background-color .15s, box-shadow .15s;
+  }
+  .desktop-capturer-selection__btn:hover,
+  .desktop-capturer-selection__btn:focus {
+    background: var(--highlight-color);
+  }
+  .desktop-capturer-selection__thumbnail {
+    width: 100%;
+    height: 81px;
+    object-fit: cover;
+  }
+  .desktop-capturer-selection__name {
+    margin: 6px 0 6px;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+  }
+  @media (prefers-color-scheme: light) {
+    .desktop-capturer-selection {
+      --overlay-color: hsla(0, 0%, 90.2%, 0.75);
+      --text-content-color: hsl(0, 0%, 12.9%);
+      --selection-button-color: hsl(180, 1.3%, 85.3%);
+    }
+  }`;
+  document.head.appendChild(screenShareStyles);
+}
+
+function setupScreenSharePickerElement(
+  id: string,
+  sources: Electron.DesktopCapturerSource[],
+): void {
+  const selectionElem = document.createElement('div');
+  selectionElem.classList.add('desktop-capturer-selection');
+  selectionElem.id = id;
+  selectionElem.innerHTML = `
+    <button class="desktop-capturer-selection__close" id="${id}-close" aria-label="Close screen share picker" type="button">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="32" height="32">
+      <path fill="currentColor" d="m12 10.586 4.95-4.95 1.414 1.414-4.95 4.95 4.95 4.95-1.414 1.414-4.95-4.95-4.95 4.95-1.414-1.414 4.95-4.95-4.95-4.95L7.05 5.636z"/>   
+      </svg>
+    </button>
+    <div class="desktop-capturer-selection__scroller">
+      <ul class="desktop-capturer-selection__list">
+        ${sources
+          .map(
+            ({ id, name, thumbnail }) => `
+          <li class="desktop-capturer-selection__item">
+            <button class="desktop-capturer-selection__btn" data-id="${id}" title="${name}">
+              <img class="desktop-capturer-selection__thumbnail" src="${thumbnail.toDataURL()}" />
+              <span class="desktop-capturer-selection__name">${name}</span>
+            </button>
+          </li>
+        `,
+          )
+          .join('')}
+      </ul>
+    </div>
+    `;
+  document.body.appendChild(selectionElem);
+}
+
+function setupScreenSharePicker(
+  resolve: (value: MediaStream | PromiseLike<MediaStream>) => void,
+  reject: (reason?: unknown) => void,
+  sources: Electron.DesktopCapturerSource[],
+): void {
+  const baseElementsId = 'native-screen-share-picker';
+  const pickerStylesElementId = baseElementsId + '-styles';
+
+  setupScreenSharePickerElement(baseElementsId, sources);
+  setupScreenSharePickerStyles(pickerStylesElementId);
+
+  const clearElements = (): void => {
+    document.getElementById(pickerStylesElementId)?.remove();
+    document.getElementById(baseElementsId)?.remove();
+  };
+
+  document
+    .getElementById(`${baseElementsId}-close`)
+    ?.addEventListener('click', () => {
+      clearElements();
+      reject('Screen share was cancelled by the user.');
+    });
+
+  document
+    .querySelectorAll('.desktop-capturer-selection__btn')
+    .forEach((button) => {
+      button.addEventListener('click', () => {
+        const id = button.getAttribute('data-id');
+        if (!id) {
+          log.error("Couldn't find `data-id` of element");
+          clearElements();
+          return;
+        }
+        const source = sources.find((source) => source.id === id);
+        if (!source) {
+          log.error(`Source with id "${id}" does not exist`);
+          clearElements();
+          return;
+        }
+
+        getDisplayMedia(source.id)
+          .then((stream) => {
+            resolve(stream);
+          })
+          .catch((err) => {
+            log.error('Error selecting desktop capture source:', err);
+            reject(err);
+          })
+          .finally(() => {
+            clearElements();
+          });
+      });
+    });
+}
+
+function setDisplayMediaPromise(): void {
+  // Since no implementation for `getDisplayMedia` exists in Electron we write our own.
+  if (!window?.navigator?.mediaDevices) {
+    return;
+  }
+  window.navigator.mediaDevices.getDisplayMedia = (): Promise<MediaStream> => {
+    return new Promise((resolve, reject) => {
+      const sources = ipcRenderer.invoke(
+        'desktop-capturer-get-sources',
+      ) as Promise<Electron.DesktopCapturerSource[]>;
+      sources
+        .then(async (sources) => {
+          if (isWayland()) {
+            // No documentation is provided wether the first element is always PipeWire-picked or not
+            // i.e. maybe it's not deterministic, we are only taking a guess here.
+            const stream = await getDisplayMedia(sources[0].id);
+            resolve(stream);
+          } else {
+            setupScreenSharePicker(resolve, reject, sources);
+          }
+        })
+        .catch((err) => {
+          reject(err);
+        });
+    });
+  };
+}
+
+function injectScripts(): void {
+  const needToInject = fs.existsSync(INJECT_DIR);
+  if (!needToInject) {
+    return;
+  }
+  // Dynamically require scripts
+  try {
+    const jsFiles = fs
+      .readdirSync(INJECT_DIR, { withFileTypes: true })
+      .filter(
+        (injectFile) => injectFile.isFile() && injectFile.name.endsWith('.js'),
+      )
+      .map((jsFileStat) => path.join('..', 'inject', jsFileStat.name));
+    for (const jsFile of jsFiles) {
+      log.debug('Injecting JS file', jsFile);
+      require(jsFile);
+    }
+  } catch (err: unknown) {
+    log.error('Error encoutered injecting JS files', err);
+  }
+}
+
+function notifyNotificationCreate(
+  title: string,
+  opt: NotificationOptions,
+): void {
+  ipcRenderer.send('notification', title, opt);
+}
+function notifyNotificationClick(): void {
+  ipcRenderer.send('notification-click');
+}
+
+// @ts-expect-error TypeScript thinks these are incompatible but they aren't
+setNotificationCallback(notifyNotificationCreate, notifyNotificationClick);
+setDisplayMediaPromise();
+
+ipcRenderer.on('params', (event, message: string) => {
+  log.debug('ipcRenderer.params', { event, message });
+  const appArgs: unknown = JSON.parse(message) as OutputOptions;
+  log.info('nativefier.json', appArgs);
+});
+
+ipcRenderer.on('debug', (event, message: string) => {
+  log.debug('ipcRenderer.debug', { event, message });
+});
+
+// Copy-pastaed as unable to get imports to work in preload.
+// If modifying, update also app/src/helpers/helpers.ts
+function isWayland(): boolean {
+  return (
+    isLinux() &&
+    (Boolean(process.env.WAYLAND_DISPLAY) ||
+      process.env.XDG_SESSION_TYPE === 'wayland')
+  );
+}
+
+function isLinux(): boolean {
+  return os.platform() === 'linux';
+}

app/src/static/.eslintrc.yml

@@ -0,0 +1,2 @@
+env:
+  browser: true

app/src/static/login.css

@@ -0,0 +1,57 @@
+label, input {
+  display: block;
+}
+
+* {
+  font-family: Verdana, sans-serif;
+}
+
+html, body {
+  height: 100%;
+  margin: 0;
+  -webkit-app-region: drag;
+}
+.login-form {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+}
+
+.login-form > div {
+  margin-bottom: 30px;
+}
+
+.login-form > div > label {
+  margin-bottom: 25px;
+  letter-spacing: 5px;
+  font-weight: 100;
+  text-transform: uppercase;
+  font-size: 18px;
+  text-align: center;
+  color: rgba(0, 0, 0, 0.7);
+}
+
+.login-form > div > input {
+  height: 30px;
+  width: 225px;
+  font-size: 16px;
+  -webkit-app-region: no-drag;
+}
+
+.login-form > div > button {
+  border: 0;
+  font-size: 15px;
+  font-weight: 100;
+  text-transform: uppercase;
+  height: 35px;
+  width: 225px;
+  background-color: #2196F3;
+  color: white;
+  -webkit-app-region: no-drag;
+}
+
+button:hover {
+  background-color: #0D47A1;
+}

app/src/static/login.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Login</title>
+  <link rel="stylesheet" type="text/css" href="login.css">
+</head>
+<body>
+<form class="login-form" id="login-form">
+  <div>
+    <label for="username-input">Username</label>
+    <input type="text" id="username-input" autofocus/>
+  </div>
+  <div>
+    <label for="password-input">Password</label>
+    <input type="password" id="password-input"/>
+  </div>
+  <div>
+    <button id="submit-form-button" type="submit">Login</button>
+  </div>
+</form>
+<script src="login.js"></script>
+</body>
+</html>

app/src/static/login.js

@@ -0,0 +1,10 @@
+const { ipcRenderer } = require('electron');
+
+document.getElementById('login-form').addEventListener('submit', (event) => {
+  event.preventDefault();
+  const usernameInput = document.getElementById('username-input');
+  const username = usernameInput.nodeValue || usernameInput.value;
+  const passwordInput = document.getElementById('password-input');
+  const password = passwordInput.nodeValue || passwordInput.value;
+  ipcRenderer.send('login-message', [username, password]);
+});

app/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    // Here in app/tsconfig.json, we want to set the `target` and `lib` keys to
+    // the "best" values for the version of Node **coming with the chosen Electron**.
+    // Careful: we're *not* talking about Nativefier's (CLI) required Node version,
+    // we're talking about the version of the Node runtime **bundled with Electron**.
+    //
+    // Like in our main tsconfig.json, we want to be as conservative as possible,
+    // to support (as much as reasonable) users using old versions of Electron.
+    // Then, at some point, an app dependency (declared in app/package.json)
+    // will require a more recent Node, then it's okay to bump our app compilerOptions
+    // to what's supported by the more recent Node.
+    //
+    // TS doesn't offer any easy "preset" for this, so the best we have is to
+    // believe people who know which {syntax, library} parts of current EcmaScript
+    // are supported for the version of Node coming with the Electron being used,
+    // and use what they recommend. For the current Node version, I followed
+    // https://stackoverflow.com/questions/51716406/typescript-tsconfig-settings-for-node-js-10
+    // and 'dom' to tell tsc it's okay to use the URL object (which is in Node >= 7)
+    "target": "es2018",
+    "lib": [
+      "es2018",
+      "dom"
+    ]
+  },
+  "include": [
+    "./src/**/*"
+  ],
+  "references": [
+    {
+      "path": "../shared"
+    }
+  ]
+}

app/webpack.config.js

@@ -0,0 +1,36 @@
+const path = require('path');
+
+// Q: Why do you use webpack?
+// A: https://github.com/nativefier/nativefier/commit/cde5c1e13bdc2739604cab04bac64eae0d719ed1
+module.exports = {
+  target: 'node',
+  entry: './src/main.ts',
+  devtool: 'source-map', // https://webpack.js.org/configuration/devtool/
+  module: {
+    rules: [
+      {
+        test: /\.ts$/,
+        use: 'ts-loader', // https://webpack.js.org/guides/typescript/
+        exclude: /node_modules/,
+      },
+    ],
+  },
+  // Don't mock __dirname; https://webpack.js.org/configuration/node/#root
+  node: {
+    __dirname: false,
+  },
+  // Prevent bundling of certain imported packages and instead retrieve these
+  // external deps at runtime. This is what we want for electron, placed in the
+  // app by electron-packager. https://webpack.js.org/configuration/externals/
+  externals: {
+    electron: 'commonjs electron',
+  },
+  resolve: {
+    extensions: [ '.ts', '.js' ],
+  },
+  output: {
+    filename: 'main.js',
+    path: path.resolve(__dirname, 'lib'),
+  },
+  mode: 'none'
+};

base-eslintrc.js

@@ -0,0 +1,39 @@
+// # https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint', 'prettier'],
+  extends: [
+    'eslint:recommended',
+    'prettier',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+  ],
+  rules: {
+    'no-console': 'error',
+    'prettier/prettier': [
+      'error',
+      {
+        endOfLine: 'auto',
+      },
+    ],
+    '@typescript-eslint/explicit-function-return-type': 'error',
+    '@typescript-eslint/no-confusing-non-null-assertion': 'error',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-extraneous-class': 'error',
+    '@typescript-eslint/no-invalid-void-type': 'error',
+    '@typescript-eslint/prefer-ts-expect-error': 'error',
+    '@typescript-eslint/type-annotation-spacing': 'error',
+    '@typescript-eslint/typedef': 'error',
+    '@typescript-eslint/unified-signatures': 'error',
+  },
+  // https://eslint.org/docs/user-guide/configuring/ignoring-code#ignorepatterns-in-config-files
+  ignorePatterns: [
+    'node_modules/**',
+    'app/node_modules/**',
+    'app/lib/**',
+    'lib/**',
+    'built-tests/**',
+    'coverage/**',
+  ],
+};

icon-scripts/convertToIcns

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+### USAGE
+
+# ./convertToIcns <input png> <outp icns>
+# Example
+# ./convertToIcns ~/sample.png ~/Desktop/converted.icns
+
+# exit the shell script on error immediately
+set -e
+
+# Exec Paths
+HAVE_IMAGEMAGICK=
+HAVE_ICONUTIL=
+HAVE_SIPS=
+HAVE_GRAPHICSMAGICK=
+
+type convert &>/dev/null && HAVE_IMAGEMAGICK=true
+type iconutil &>/dev/null && HAVE_ICONUTIL=true
+type sips &>/dev/null && HAVE_SIPS=true
+type gm &>/dev/null && gm version | grep GraphicsMagick &>/dev/null && HAVE_GRAPHICSMAGICK=true
+
+[[ -z "$HAVE_ICONUTIL" ]] && { echo >&2 "Cannot find required iconutil executable"; exit 1; }
+[[ -z "$HAVE_IMAGEMAGICK" && -z "$HAVE_SIPS" && -z "$HAVE_GRAPHICSMAGICK" ]] && { echo >&2 "Cannot find required image converter, please install sips, imagemagick or graphicsmagick"; exit 1; }
+
+# Parameters
+SOURCE="$1"
+DEST="$2"
+
+# Check source and destination arguments
+if [ -z "${SOURCE}" ]; then
+	echo "No source image specified"
+	exit 1
+fi
+
+if [ -z "${DEST}" ]; then
+	echo "No destination specified"
+	exit 1
+fi
+
+TEMP_DIR="$(mktemp -d -t nativefier-icns-XXXXXX)"
+ICONSET="${TEMP_DIR}/converted.iconset"
+
+function cleanUp() {
+    rm -rf "${TEMP_DIR}"
+}
+
+trap cleanUp EXIT
+
+"${BASH_SOURCE%/*}/convertToIconset" "${SOURCE}" "${ICONSET}"
+
+# Create an icns file lefrom the iconset
+iconutil -c icns "${ICONSET}" -o "${DEST}"
+
+trap - EXIT
+cleanUp

icon-scripts/convertToIco

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+# USAGE
+
+# ./convertToIco <input png or ico> <outfilename>.ico
+# Example
+# ./convertToPng ~/sample.png ~/converted.ico
+
+set -e
+
+CONVERT=
+
+type gm &>/dev/null && gm version | grep GraphicsMagick &>/dev/null && CONVERT="gm convert"
+type convert &>/dev/null && CONVERT="convert"
+
+[[ -z "$CONVERT" ]] && { echo >&2 "Cannot find required ImageMagick Convert or GraphicsMagick executable"; exit 1; }
+
+SOURCE=$1
+DEST=$2
+
+if [ -z "${SOURCE}" ]; then
+	echo "No source image specified"
+	exit 1
+fi
+
+if [ -z "${DEST}" ]; then
+	echo "No destination specified"
+	exit 1
+fi
+
+NAME=$(basename "${SOURCE}")
+EXT="${NAME##*.}"
+
+if [ "${EXT}" == "ico" ]; then
+    cp "${SOURCE}" "${DEST}"
+    exit 0
+fi
+
+$CONVERT "${SOURCE}" -resize 256x256 "${DEST}"

icon-scripts/convertToIconset

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+### USAGE
+
+# ./convertToIconset <input png> <outp iconset>
+# Example
+# ./convertToIconset ~/sample.png ~/Desktop/converted.iconset
+
+# exit the shell script on error immediately
+set -e
+
+make_iconset_imagemagick() {
+  local file iconset
+  file="${1}"
+  iconset="${2}"
+
+  mkdir "$iconset"
+
+  for size in {16,32,64,128,256,512}; do
+    $CONVERT "${file}" -define png:big-depth=16 -define png:color-type=6 -sample "${size}x${size}" "${iconset}/icon_${size}x${size}.png"
+    $CONVERT "${file}" -define png:big-depth=16 -define png:color-type=6 -sample "$((size * 2))x$((size * 2))" "${iconset}/icon_${size}x${size}@2x.png"
+  done
+}
+
+make_iconset_sips() {
+  local file iconset
+  file="${1}"
+  iconset="${2}"
+
+  mkdir "$iconset"
+
+  for size in {16,32,64,128,256,512}; do
+    sips --setProperty format png --resampleHeightWidth "${size}" "${size}" "${file}" --out "${iconset}/icon_${size}x${size}.png" &> /dev/null
+    sips --setProperty format png --resampleHeightWidth "$((size * 2))" "$((size * 2))" "${file}" --out "${iconset}/icon_${size}x${size}@2x.png" &> /dev/null
+  done
+}
+
+# Parameters
+SOURCE="$1"
+DEST="$2"
+
+# Check source and destination arguments
+if [ -z "${SOURCE}" ]; then
+	echo >&2 "No source image specified"; exit 1
+fi
+
+if [ -z "${DEST}" ]; then
+	echo >&2 "No destination specified"; exit 1
+fi
+
+HAVE_IMAGEMAGICK=
+HAVE_SIPS=
+HAVE_GRAPHICSMAGICK=
+CONVERT=
+
+type gm &>/dev/null && gm version | grep GraphicsMagick &>/dev/null && HAVE_GRAPHICSMAGICK=true && CONVERT="gm convert"
+type convert &>/dev/null && HAVE_IMAGEMAGICK=true && CONVERT="convert"
+type sips &>/dev/null && HAVE_SIPS=true
+
+if [[ -n "$HAVE_IMAGEMAGICK" || -n "$HAVE_GRAPHICSMAGICK" ]]; then
+  PNG_PATH="$(mktemp -d -t nativefier-iconset-XXXXXX)/icon.png"
+  "${BASH_SOURCE%/*}/convertToPng" "${SOURCE}" "${PNG_PATH}"
+  make_iconset_imagemagick "${PNG_PATH}" "${DEST}"
+elif [[ -n "$HAVE_SIPS" ]]; then
+  make_iconset_sips "${SOURCE}" "${DEST}"
+else
+  echo >&2 "Cannot find convert or sips executables"; exit 1;
+fi

icon-scripts/convertToPng

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+
+# USAGE
+
+# ./convertToPng <input png or ico> <outfilename>.png
+# Example
+# ./convertToPng ~/sample.ico ~/Desktop/converted.png
+
+set -e
+
+HAVE_IMAGEMAGICK=
+HAVE_GRAPHICSMAGICK=
+
+type convert &>/dev/null && type identify &>/dev/null && HAVE_IMAGEMAGICK=true
+type gm &>/dev/null && gm version | grep GraphicsMagick &>/dev/null && HAVE_GRAPHICSMAGICK=true
+
+if [[ -z "$HAVE_IMAGEMAGICK" && -z "$HAVE_GRAPHICSMAGICK" ]]; then
+	type convert >/dev/null 2>&1 || echo >&2 "Cannot find required ImageMagick 'convert' executable"
+	type identify >/dev/null 2>&1 || echo >&2 "Cannot find required ImageMagick 'identify' executable"
+	type gm &>/dev/null && gm version | grep GraphicsMagick &>/dev/null && echo >&2 "Cannot find GraphicsMagick"
+	echo >&2 "ImageMagic or GraphicsMagic is required, please ensure they are in your PATH"
+	exit 1
+fi
+
+CONVERT="convert"
+IDENTIFY="identify"
+if [[ -z "$HAVE_IMAGEMAGICK" ]]; then
+	# we must have GraphicsMagick then
+	CONVERT="gm convert"
+	IDENTIFY="gm identify"
+fi
+
+# Parameters
+SOURCE="$1"
+DEST="$2"
+
+# Check source and destination arguments
+if [ -z "${SOURCE}" ]; then
+	echo "No source image specified"
+	exit 1
+fi
+
+if [ -z "${DEST}" ]; then
+	echo "No destination specified"
+	exit 1
+fi
+
+# File Infrastructure
+NAME=$(basename "${SOURCE}")
+BASE="${NAME%.*}"
+TEMP_DIR="convert_temp"
+
+function cleanUp() {
+    rm -rf "${TEMP_DIR}"
+}
+
+trap cleanUp EXIT
+
+mkdir -p "${TEMP_DIR}"
+
+# check if .ico is a sequence
+# pipe into cat so no exit code is given for grep if no matches are found
+IS_ICO_SET="$($IDENTIFY "${SOURCE}" | grep -e "\w\.ico\[0" | cat )"
+
+$CONVERT "${SOURCE}" "${TEMP_DIR}/${BASE}.png"
+if [ "${IS_ICO_SET}" ]; then
+	# extract the largest(?) image from the set
+    cp "${TEMP_DIR}/${BASE}-0.png" "${DEST}"
+else
+    cp "${TEMP_DIR}/${BASE}.png" "${DEST}"
+fi
+
+rm -rf "${TEMP_DIR}"
+
+trap - EXIT
+cleanUp

icon-scripts/convertToTrayIcon

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+# USAGE
+
+# ./convertToTrayIcon <input png or icns> <outfilename>.png
+# Example
+# ./convertToTrayIcon ~/sample.icns ~/converted.png
+
+set -e
+
+SOURCE=$1
+DEST=$2
+
+if [ -z "${SOURCE}" ]; then
+	echo "No source image specified"
+	exit 1
+fi
+
+if [ -z "${DEST}" ]; then
+	echo "No destination specified"
+	exit 1
+fi
+
+NAME=$(basename "${SOURCE}")
+EXT="${NAME##*.}"
+
+if [ "${EXT}" == "png" ]; then
+    cp "${SOURCE}" "${DEST}"
+    exit 0
+fi
+
+sips --setProperty format png --resampleHeightWidth "256" "256" "${SOURCE}" --out "${DEST}"

package.json

@@ -0,0 +1,145 @@
+{
+  "name": "nativefier",
+  "version": "52.0.0",
+  "description": "Wrap web apps natively",
+  "license": "MIT",
+  "author": "Goh Jia Hao",
+  "engines_README": "Bumping the minimum required Node version? You must bump: 1. package.json -> engines.node, 2. package.json -> devDependencies.@types/node , 3. tsconfig.json -> {target, lib} , 4. .github/workflows/ci.yml -> node-version",
+  "engines_READMEforEnginesNode": "Here in engines.node, we require a version as old as possible, for Nativefier to be easily installable using the stock Node.js shipped by conservative Linux distros. It's a balancing act between this, and our own dependencies requiring more a recent Node; as much as possible, try to keep supporting Debian stable; https://packages.debian.org/search?suite=stable&keywords=nodejs",
+  "engines": {
+    "node": ">= 16.16.0",
+    "npm": ">= 8.11.0"
+  },
+  "keywords": [
+    "desktop",
+    "electron",
+    "app",
+    "native",
+    "wrapper"
+  ],
+  "main": "lib/main.js",
+  "typings": "lib/main.d.ts",
+  "bin": {
+    "nativefier": "lib/cli.js"
+  },
+  "homepage": "https://github.com/nativefier/nativefier",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nativefier/nativefier.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nativefier/nativefier/issues"
+  },
+  "scripts": {
+    "build-app": "cd app && webpack",
+    "build-app-static": "ncp app/src/static/ app/lib/static/ && ncp app/dist/preload.js app/lib/preload.js && ncp app/dist/preload.js.map app/lib/preload.js.map",
+    "build": "npm run clean && tsc --build shared src app && npm run build-app && npm run build-app-static",
+    "build:watch": "npm run clean && tsc --build shared src app --watch",
+    "changelog": "./.github/generate-changelog",
+    "clean": "rimraf coverage/ lib/ app/lib/ app/dist/ shared/lib",
+    "clean:full": "npm run clean && rimraf app/node_modules/ node_modules/",
+    "lint:fix": "cd src && eslint . --ext .ts --fix && cd ../shared && eslint src --ext .ts --fix && cd ../app && eslint src --ext .ts --fix",
+    "lint:format": "prettier --write 'src/**/*.ts' 'app/src/**/*.ts' 'shared/src/**/*.ts'",
+    "lint": "eslint shared app src --ext .ts",
+    "list-outdated-deps": "npm out -l; cd app && npm out -l; true",
+    "prepare": "cd app && npm ci && cd .. && npm run build",
+    "relock:cli": "rm -rf ./node_modules/ ./npm-shrinkwrap.json && npm install --ignore-scripts --package-lock && mv package-lock.json npm-shrinkwrap.json && npm out -l",
+    "relock:app": "rm -rf ./app/node_modules/ ./app/npm-shrinkwrap.json && cd app && npm install --ignore-scripts --package-lock && mv package-lock.json npm-shrinkwrap.json && npm out -l",
+    "relock": "npm run relock:cli; npm run relock:app",
+    "test:integration": "jest --testRegex=integration-test",
+    "test:manual": "npm run build && bash .github/manual-test",
+    "test:playwright": "jest --detectOpenHandles --testRegex=playwright-test",
+    "test:noplaywright": "jest --testPathIgnorePatterns=playwright",
+    "test:unit": "jest",
+    "test:watch": "echo 'Remember to run npm run build:watch for the test watcher to work!' && jest --watchAll --collectCoverage=false",
+    "test:watch:unit": "echo 'Remember to run npm run build:watch for the test watcher to work!' && jest --watchAll --collectCoverage=false --testPathIgnorePatterns=integration --testPathIgnorePatterns=playwright",
+    "test:withlog": "LOGLEVEL=trace npm run test",
+    "test": "jest",
+    "watch": "npx concurrently \"npm:*:watch\""
+  },
+  "dependencies": {
+    "@electron/asar": "^3.2.4",
+    "axios": "^1.4.0",
+    "electron-packager": "^17.1.1",
+    "fs-extra": "^11.1.1",
+    "gitcloud": "^0.2.4",
+    "hasbin": "^1.2.3",
+    "loglevel": "^1.8.1",
+    "ncp": "^2.0.0",
+    "page-icon": "^0.4.0",
+    "sanitize-filename": "^1.6.3",
+    "source-map-support": "^0.5.21",
+    "tmp": "^0.2.1",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.8",
+    "@types/fs-extra": "^11.0.1",
+    "@types/hasbin": "^1.2.0",
+    "@types/jest": "^29.5.4",
+    "@types/ncp": "^2.0.5",
+    "@types/node": "^20.5.6",
+    "@types/page-icon": "^0.3.4",
+    "@types/tmp": "^0.2.3",
+    "@types/yargs": "^17.0.24",
+    "@typescript-eslint/eslint-plugin": "^6.4.1",
+    "@typescript-eslint/parser": "^6.4.1",
+    "electron": "^25.7.0",
+    "eslint": "^8.46.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "jest": "^29.6.2",
+    "playwright": "^1.36.2",
+    "prettier": "^3.0.1",
+    "rimraf": "^5.0.1",
+    "ts-loader": "^9.4.4",
+    "typescript": "^5.1.6",
+    "webpack": "^5.88.2",
+    "webpack-cli": "^5.1.4"
+  },
+  "jest_COMMENTS": {
+    "testPathIgnorePatterns": "See https://jestjs.io/docs/configuration#testpathignorepatterns-arraystring . We set it to 1. ignore coverage for deps, and 2. be sure we test the compiled JS, which is in `lib`, not `src` or `dist`",
+    "watchPathIgnorePatterns": "See https://jestjs.io/docs/configuration#watchpathignorepatterns-arraystring . We set it for `jest --watch` (a.k.a. `npm run test:watch`) to trigger only after `tsc --watch` (a.k.a. `npm run build:watch`) completes its incremental compilation. Else, jest will pick up immediately on changes in `src` when TSC is barely running, hence testing not-recompiled-yet code and being super confusing, as 1. your changes won't be taken during this first run, and 2. the *next* run (e.g. after a second 'Save' in your editor) will actually have the new code :D"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "./app/dist/**/*.js",
+      "./lib/**/*.js",
+      "./shared/lib/**/*.js"
+    ],
+    "coveragePathIgnorePatterns": [
+      "[.-]test.js$"
+    ],
+    "moduleNameMapper": {
+      "^electron$": "<rootDir>/app/dist/mocks/electron.js"
+    },
+    "setupFiles": [
+      "./lib/jestSetupFiles"
+    ],
+    "testEnvironment": "node",
+    "testPathIgnorePatterns": [
+      "<rootDir>/app/node_modules.*",
+      "<rootDir>/app/src.*",
+      "<rootDir>/app/lib.*",
+      "<rootDir>/src.*",
+      ".+\\.d\\.ts",
+      ".+\\.js\\.map"
+    ],
+    "testRegex": "test\\.js",
+    "testTimeout": 15000,
+    "watchPathIgnorePatterns": [
+      "<rootDir>/app/lib.*",
+      "<rootDir>/app/src.*",
+      "<rootDir>/app/tsconfig.json",
+      "<rootDir>/shared/tsconfig.json",
+      "<rootDir>/src.*",
+      "<rootDir>/tsconfig-base.json"
+    ]
+  },
+  "prettier": {
+    "arrowParens": "always",
+    "singleQuote": true,
+    "trailingComma": "all"
+  }
+}

shared/.eslintrc.js

@@ -0,0 +1,14 @@
+const base = require('../base-eslintrc');
+
+// # https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md
+module.exports = {
+  parser: base.parser,
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+  },
+  plugins: base.plugins,
+  extends: base.extends,
+  rules: base.rules,
+  ignorePatterns: ['lib/**'],
+};

shared/src/options/model.ts

@@ -0,0 +1,238 @@
+import { CreateOptions } from '@electron/asar';
+import { randomUUID } from 'crypto';
+import * as electronPackager from 'electron-packager';
+
+export type TitleBarValue =
+  | 'default'
+  | 'hidden'
+  | 'hiddenInset'
+  | 'customButtonsOnHover';
+export type TrayValue = 'true' | 'false' | 'start-in-tray';
+
+export interface ElectronPackagerOptions extends electronPackager.Options {
+  arch: string;
+  portable: boolean;
+  platform?: string;
+  targetUrl: string;
+  upgrade: boolean;
+  upgradeFrom?: string;
+}
+
+export interface AppOptions {
+  packager: ElectronPackagerOptions;
+  nativefier: {
+    accessibilityPrompt: boolean;
+    alwaysOnTop: boolean;
+    backgroundColor?: string;
+    basicAuthPassword?: string;
+    basicAuthUsername?: string;
+    blockExternalUrls: boolean;
+    bookmarksMenu?: string;
+    bounce: boolean;
+    browserwindowOptions?: BrowserWindowOptions;
+    clearCache: boolean;
+    counter: boolean;
+    crashReporter?: string;
+    disableContextMenu: boolean;
+    disableDevTools: boolean;
+    disableGpu: boolean;
+    disableOldBuildWarning: boolean;
+    diskCacheSize?: number;
+    electronVersionUsed?: string;
+    enableEs3Apis: boolean;
+    fastQuit: boolean;
+    fileDownloadOptions?: Record<string, unknown>;
+    flashPluginDir?: string;
+    fullScreen: boolean;
+    globalShortcuts?: GlobalShortcut[];
+    hideWindowFrame: boolean;
+    ignoreCertificate: boolean;
+    ignoreGpuBlacklist: boolean;
+    inject?: string[];
+    insecure: boolean;
+    internalUrls?: string;
+    lang?: string;
+    maximize: boolean;
+    nativefierVersion: string;
+    processEnvs?: string;
+    proxyRules?: string;
+    quiet?: boolean;
+    showMenuBar: boolean;
+    singleInstance: boolean;
+    strictInternalUrls: boolean;
+    titleBarStyle?: TitleBarValue;
+    tray: TrayValue;
+    userAgent?: string;
+    userAgentHonest: boolean;
+    verbose: boolean;
+    versionString?: string;
+    width?: number;
+    widevine: boolean;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    x?: number;
+    y?: number;
+    zoom: number;
+  };
+}
+
+export type BrowserWindowOptions = Record<string, unknown> & {
+  webPreferences?: Record<string, unknown>;
+};
+
+export type GlobalShortcut = {
+  key: string;
+  inputEvents: {
+    type:
+      | 'mouseDown'
+      | 'mouseUp'
+      | 'mouseEnter'
+      | 'mouseLeave'
+      | 'contextMenu'
+      | 'mouseWheel'
+      | 'mouseMove'
+      | 'keyDown'
+      | 'keyUp'
+      | 'char';
+    keyCode: string;
+  }[];
+};
+
+export type NativefierOptions = Partial<
+  AppOptions['packager'] & AppOptions['nativefier']
+>;
+
+export type OutputOptions = NativefierOptions & {
+  blockExternalUrls: boolean;
+  browserwindowOptions?: BrowserWindowOptions;
+  buildDate: number;
+  companyName?: string;
+  disableDevTools: boolean;
+  fileDownloadOptions?: Record<string, unknown>;
+  internalUrls: string | RegExp | undefined;
+  isUpgrade: boolean;
+  name: string;
+  nativefierVersion: string;
+  oldBuildWarningText: string;
+  strictInternalUrls: boolean;
+  tabbingIdentifier?: string;
+  targetUrl: string;
+  userAgent?: string;
+  zoom?: number;
+};
+
+export type PackageJSON = {
+  name: string;
+};
+
+export type RawOptions = {
+  accessibilityPrompt?: boolean;
+  alwaysOnTop?: boolean;
+  appCopyright?: string;
+  appVersion?: string;
+  arch?: string;
+  asar?: boolean | CreateOptions;
+  backgroundColor?: string;
+  basicAuthPassword?: string;
+  basicAuthUsername?: string;
+  blockExternalUrls?: boolean;
+  bookmarksMenu?: string;
+  bounce?: boolean;
+  browserwindowOptions?: BrowserWindowOptions;
+  buildVersion?: string;
+  clearCache?: boolean;
+  conceal?: boolean;
+  counter?: boolean;
+  crashReporter?: string;
+  darwinDarkModeSupport?: boolean;
+  disableContextMenu?: boolean;
+  disableDevTools?: boolean;
+  disableGpu?: boolean;
+  disableOldBuildWarning?: boolean;
+  disableOldBuildWarningYesiknowitisinsecure?: boolean;
+  diskCacheSize?: number;
+  electronVersion?: string;
+  electronVersionUsed?: string;
+  enableEs3Apis?: boolean;
+  fastQuit?: boolean;
+  fileDownloadOptions?: Record<string, unknown>;
+  flashPath?: string;
+  flashPluginDir?: string;
+  fullScreen?: boolean;
+  globalShortcuts?: string | GlobalShortcut[];
+  height?: number;
+  hideWindowFrame?: boolean;
+  icon?: string;
+  ignoreCertificate?: boolean;
+  ignoreGpuBlacklist?: boolean;
+  inject?: string[];
+  insecure?: boolean;
+  internalUrls?: string;
+  lang?: string;
+  maxHeight?: number;
+  maximize?: boolean;
+  maxWidth?: number;
+  minHeight?: number;
+  minWidth?: number;
+  name?: string;
+  nativefierVersion?: string;
+  out?: string;
+  overwrite?: boolean;
+  platform?: string;
+  portable?: boolean;
+  processEnvs?: string;
+  proxyRules?: string;
+  quiet?: boolean;
+  showMenuBar?: boolean;
+  singleInstance?: boolean;
+  strictInternalUrls?: boolean;
+  targetUrl?: string;
+  titleBarStyle?: TitleBarValue;
+  tray?: TrayValue;
+  upgrade?: string | boolean;
+  upgradeFrom?: string;
+  userAgent?: string;
+  userAgentHonest?: boolean;
+  verbose?: boolean;
+  versionString?: string;
+  widevine?: boolean;
+  width?: number;
+  win32metadata?: electronPackager.Win32MetadataOptions;
+  x?: number;
+  y?: number;
+  zoom?: number;
+};
+
+export type WindowOptions = {
+  autoHideMenuBar: boolean;
+  blockExternalUrls: boolean;
+  browserwindowOptions?: BrowserWindowOptions;
+  insecure: boolean;
+  internalUrls?: string | RegExp;
+  strictInternalUrls?: boolean;
+  name: string;
+  proxyRules?: string;
+  show?: boolean;
+  tabbingIdentifier?: string;
+  targetUrl: string;
+  userAgent?: string;
+  zoom: number;
+};
+
+export function outputOptionsToWindowOptions(
+  options: OutputOptions,
+  generateTabbingIdentifierIfMissing: boolean,
+): WindowOptions {
+  return {
+    ...options,
+    autoHideMenuBar: !options.showMenuBar,
+    insecure: options.insecure ?? false,
+    tabbingIdentifier: generateTabbingIdentifierIfMissing
+      ? options.tabbingIdentifier ?? randomUUID()
+      : options.tabbingIdentifier,
+    zoom: options.zoom ?? 1.0,
+  };
+}

shared/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./lib",
+    // Here we want to set target and lib to the *worst* of app/tsconfig.json and src/tsconfig.json
+    // (plus "dom"), because shared code will run both in CLI Node and app Node.
+    // See comments in app/tsconfig.json and src/tsconfig.json
+    "target": "es2018",
+    "lib": [
+      "es2018",
+      "dom"
+    ]
+  },
+  "include": [
+    "./src/**/*"
+  ],
+}

src/.eslintrc.js

@@ -0,0 +1,13 @@
+const base = require('../base-eslintrc');
+
+// # https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/README.md
+module.exports = {
+  parser: base.parser,
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+  },
+  plugins: base.plugins,
+  extends: base.extends,
+  rules: base.rules,
+};

src/build/buildIcon.ts

@@ -0,0 +1,97 @@
+import * as path from 'path';
+
+import * as log from 'loglevel';
+
+import { isOSX } from '../helpers/helpers';
+import {
+  convertToPng,
+  convertToIco,
+  convertToIcns,
+  convertToTrayIcon,
+} from '../helpers/iconShellHelpers';
+import { AppOptions } from '../../shared/src/options/model';
+
+function iconIsIco(iconPath: string): boolean {
+  return path.extname(iconPath) === '.ico';
+}
+
+function iconIsPng(iconPath: string): boolean {
+  return path.extname(iconPath) === '.png';
+}
+
+function iconIsIcns(iconPath: string): boolean {
+  return path.extname(iconPath) === '.icns';
+}
+
+/**
+ * Will convert a `.png` icon to the appropriate arch format (if necessary),
+ * and return adjusted options
+ */
+export function convertIconIfNecessary(options: AppOptions): void {
+  if (!options.packager.icon) {
+    log.debug('Option "icon" not set, skipping icon conversion.');
+    return;
+  }
+
+  if (options.packager.platform === 'win32') {
+    if (iconIsIco(options.packager.icon)) {
+      log.debug(
+        'Building for Windows and icon is already a .ico, no conversion needed',
+      );
+      return;
+    }
+
+    try {
+      const iconPath = convertToIco(options.packager.icon);
+      options.packager.icon = iconPath;
+      return;
+    } catch (err: unknown) {
+      log.warn('Failed to convert icon to .ico, skipping.', err);
+      return;
+    }
+  }
+
+  if (options.packager.platform === 'linux') {
+    if (iconIsPng(options.packager.icon)) {
+      log.debug(
+        'Building for Linux and icon is already a .png, no conversion needed',
+      );
+      return;
+    }
+
+    try {
+      const iconPath = convertToPng(options.packager.icon);
+      options.packager.icon = iconPath;
+      return;
+    } catch (err: unknown) {
+      log.warn('Failed to convert icon to .png, skipping.', err);
+      return;
+    }
+  }
+
+  if (iconIsIcns(options.packager.icon)) {
+    log.debug(
+      'Building for macOS and icon is already a .icns, no conversion needed',
+    );
+  }
+
+  if (!isOSX()) {
+    log.warn(
+      'Skipping icon conversion to .icns, conversion is only supported on macOS',
+    );
+    return;
+  }
+
+  try {
+    if (!iconIsIcns(options.packager.icon)) {
+      const iconPath = convertToIcns(options.packager.icon);
+      options.packager.icon = iconPath;
+    }
+    if (options.nativefier.tray !== 'false') {
+      convertToTrayIcon(options.packager.icon);
+    }
+  } catch (err: unknown) {
+    log.warn('Failed to convert icon to .icns, skipping.', err);
+    options.packager.icon = undefined;
+  }
+}

src/build/buildNativefierApp.ts

@@ -0,0 +1,267 @@
+import * as path from 'path';
+
+import * as electronGet from '@electron/get';
+import electronPackager from 'electron-packager';
+import * as fs from 'fs-extra';
+import * as log from 'loglevel';
+
+import { convertIconIfNecessary } from './buildIcon';
+import {
+  getTempDir,
+  hasWine,
+  isWindows,
+  isWindowsAdmin,
+} from '../helpers/helpers';
+import { useOldAppOptions, findUpgradeApp } from '../helpers/upgrade/upgrade';
+import { AppOptions, RawOptions } from '../../shared/src/options/model';
+import { getOptions } from '../options/optionsMain';
+import { prepareElectronApp } from './prepareElectronApp';
+
+const OPTIONS_REQUIRING_WINDOWS_FOR_WINDOWS_BUILD = [
+  'icon',
+  'appCopyright',
+  'appVersion',
+  'buildVersion',
+  'versionString',
+  'win32metadata',
+];
+
+/**
+ * For Windows & Linux, we have to copy over the icon to the resources/app
+ * folder, which the BrowserWindow is hard-coded to read the icon from
+ */
+async function copyIconsIfNecessary(
+  options: AppOptions,
+  appPath: string,
+): Promise<void> {
+  log.debug('Copying icons if necessary');
+  if (!options.packager.icon) {
+    log.debug('No icon specified in options; aborting');
+    return;
+  }
+
+  if (
+    options.packager.platform === 'darwin' ||
+    options.packager.platform === 'mas'
+  ) {
+    if (options.nativefier.tray !== 'false') {
+      //tray icon needs to be .png
+      log.debug('Copying icon for tray application');
+      const trayIconFileName = `tray-icon.png`;
+      const destIconPath = path.join(appPath, 'icon.png');
+      await fs.copy(
+        `${path.dirname(options.packager.icon)}/${trayIconFileName}`,
+        destIconPath,
+      );
+    } else {
+      log.debug('No copying necessary on macOS; aborting');
+    }
+    return;
+  }
+
+  // windows & linux: put the icon file into the app
+  const destFileName = `icon${path.extname(options.packager.icon)}`;
+  const destIconPath = path.join(appPath, destFileName);
+
+  log.debug(`Copying icon ${options.packager.icon} to`, destIconPath);
+  await fs.copy(options.packager.icon, destIconPath);
+}
+
+/**
+ * Checks the app path array to determine if packaging completed successfully
+ */
+function getAppPath(appPath: string | string[]): string | undefined {
+  if (!Array.isArray(appPath)) {
+    return appPath;
+  }
+
+  if (appPath.length === 0) {
+    return undefined; // directory already exists and `--overwrite` not set
+  }
+
+  if (appPath.length > 1) {
+    log.warn(
+      'Warning: This should not be happening, packaged app path contains more than one element:',
+      appPath,
+    );
+  }
+
+  return appPath[0];
+}
+
+function isUpgrade(rawOptions: RawOptions): boolean {
+  if (
+    rawOptions.upgrade !== undefined &&
+    typeof rawOptions.upgrade === 'string' &&
+    rawOptions.upgrade !== ''
+  ) {
+    rawOptions.upgradeFrom = rawOptions.upgrade;
+    rawOptions.upgrade = true;
+    return true;
+  }
+  return false;
+}
+
+function trimUnprocessableOptions(options: AppOptions): void {
+  if (options.packager.platform === 'win32' && !isWindows() && !hasWine()) {
+    const optionsPresent = Object.entries(options)
+      .filter(
+        ([key, value]) =>
+          OPTIONS_REQUIRING_WINDOWS_FOR_WINDOWS_BUILD.includes(key) && !!value,
+      )
+      .map(([key]) => key);
+    if (optionsPresent.length === 0) {
+      return;
+    }
+    log.warn(
+      `*Not* setting [${optionsPresent.join(', ')}], as couldn't find Wine.`,
+      'Wine is required when packaging a Windows app under on non-Windows platforms.',
+      'Also, note that Windows apps built under non-Windows platforms without Wine *will lack* certain',
+      'features, like a correct icon and process name. Do yourself a favor and install Wine, please.',
+    );
+    for (const keyToUnset of optionsPresent) {
+      (options as unknown as Record<string, undefined>)[keyToUnset] = undefined;
+    }
+  }
+}
+
+function getOSRunHelp(platform?: string): string {
+  if (platform === 'win32') {
+    return `the contained .exe file.`;
+  } else if (platform === 'linux') {
+    return `the contained executable file (prefixing with ./ if necessary)\nMenu/desktop shortcuts are up to you, because Nativefier cannot know where you're going to move the app. Search for "linux .desktop file" for help, or see https://wiki.archlinux.org/index.php/Desktop_entries`;
+  } else if (platform === 'darwin') {
+    return `the app bundle.`;
+  }
+  return '';
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export async function buildNativefierApp(
+  rawOptions: RawOptions,
+): Promise<string> {
+  // early-suppress potential logging before full options handling
+  if (rawOptions.quiet) {
+    log.setLevel('silent');
+  }
+
+  log.warn(
+    '\n\n    Hi! Nativefier is minimally maintained these days, and needs more hands.\n' +
+      '    If you have the time & motivation, help with bugfixes and maintenance is VERY welcome.\n' +
+      '    Please go to https://github.com/nativefier/nativefier and help how you can. Thanks.\n\n',
+  );
+
+  log.info('\nProcessing options...');
+
+  let finalOutDirectory = rawOptions.out ?? process.cwd();
+
+  if (isUpgrade(rawOptions)) {
+    log.debug('Attempting to upgrade from', rawOptions.upgradeFrom);
+    const oldApp = findUpgradeApp(rawOptions.upgradeFrom as string);
+    if (!oldApp) {
+      throw new Error(
+        `Could not find an old Nativfier app in "${
+          rawOptions.upgradeFrom as string
+        }"`,
+      );
+    }
+    rawOptions = useOldAppOptions(rawOptions, oldApp);
+    if (rawOptions.out === undefined && rawOptions.overwrite) {
+      finalOutDirectory = oldApp.appRoot;
+      rawOptions.out = getTempDir('appUpgrade', 0o755);
+    }
+  }
+  log.debug('rawOptions', rawOptions);
+
+  const options = await getOptions(rawOptions);
+  log.debug('options', options);
+
+  if (options.packager.platform === 'darwin' && isWindows()) {
+    // electron-packager has to extract the desired electron package for the target platform.
+    // For a target platform of Mac, this zip file contains symlinks. And on Windows, extracting
+    // files that are symlinks need Admin permissions. So we'll check if the user is an admin, and
+    // fail early if not.
+    // For reference
+    // https://github.com/electron/electron-packager/issues/933
+    // https://github.com/electron/electron-packager/issues/1194
+    // https://github.com/electron/electron/issues/11094
+    if (!isWindowsAdmin()) {
+      throw new Error(
+        'Building an app with a target platform of Mac on a Windows machine requires admin priveleges to perform. Please rerun this command in an admin command prompt.',
+      );
+    }
+  }
+
+  log.info('\nPreparing Electron app...');
+  const tmpPath = getTempDir('app', 0o755);
+  await prepareElectronApp(options.packager.dir, tmpPath, options);
+
+  log.info('\nConverting icons...');
+  options.packager.dir = tmpPath;
+  convertIconIfNecessary(options);
+  await copyIconsIfNecessary(options, tmpPath);
+
+  options.packager.quiet = !rawOptions.verbose;
+
+  log.info(
+    "\nPackaging... This will take a few seconds, maybe minutes if the requested Electron isn't cached yet...",
+  );
+  trimUnprocessableOptions(options);
+  electronGet.initializeProxy(); // https://github.com/electron/get#proxies
+  const appPathArray = await electronPackager(options.packager);
+
+  log.info('\nFinalizing build...');
+  let appPath = getAppPath(appPathArray);
+
+  if (!appPath) {
+    throw new Error('App Path could not be determined.');
+  }
+
+  if (
+    options.packager.upgrade &&
+    options.packager.upgradeFrom &&
+    options.packager.overwrite
+  ) {
+    if (options.packager.platform === 'darwin') {
+      try {
+        // This is needed due to a funky thing that happens when copying Squirrel.framework
+        // over where it gets into a circular file reference somehow.
+        await fs.remove(
+          path.join(
+            finalOutDirectory,
+            `${options.packager.name ?? ''}.app`,
+            'Contents',
+            'Frameworks',
+          ),
+        );
+      } catch (err: unknown) {
+        log.warn(
+          'Encountered an error when attempting to pre-delete old frameworks:',
+          err,
+        );
+      }
+      await fs.copy(
+        path.join(appPath, `${options.packager.name ?? ''}.app`),
+        path.join(finalOutDirectory, `${options.packager.name ?? ''}.app`),
+        {
+          overwrite: options.packager.overwrite,
+          preserveTimestamps: true,
+        },
+      );
+    } else {
+      await fs.copy(appPath, finalOutDirectory, {
+        overwrite: options.packager.overwrite,
+        preserveTimestamps: true,
+      });
+    }
+    await fs.remove(appPath);
+    appPath = finalOutDirectory;
+  }
+
+  const osRunHelp = getOSRunHelp(options.packager.platform);
+  log.info(
+    `App built to ${appPath}, move to wherever it makes sense for you and run ${osRunHelp}`,
+  );
+
+  return appPath;
+}

src/build/prepareElectronApp.test.ts

@@ -0,0 +1,11 @@
+import { normalizeAppName } from './prepareElectronApp';
+
+describe('normalizeAppName', () => {
+  test('it is stable', () => {
+    // Non-determinism / unstability would cause using a different appName
+    // at each app regen, thus a different appData folder, which would cause
+    // losing user state, including login state through cookies.
+    const normalizedTrello = normalizeAppName('Trello', 'https://trello.com');
+    expect(normalizedTrello).toBe('trello-nativefier-679e8e');
+  });
+});

src/build/prepareElectronApp.ts

@@ -0,0 +1,219 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+
+import * as log from 'loglevel';
+
+import { generateRandomSuffix } from '../helpers/helpers';
+import {
+  AppOptions,
+  OutputOptions,
+  PackageJSON,
+} from '../../shared/src/options/model';
+import { parseJson } from '../utils/parseUtils';
+import { DEFAULT_APP_NAME } from '../constants';
+
+/**
+ * Only picks certain app args to pass to nativefier.json
+ */
+function pickElectronAppArgs(options: AppOptions): OutputOptions {
+  return {
+    accessibilityPrompt: options.nativefier.accessibilityPrompt,
+    alwaysOnTop: options.nativefier.alwaysOnTop,
+    appBundleId: options.packager.appBundleId,
+    appCategoryType: options.packager.appCategoryType,
+    appCopyright: options.packager.appCopyright,
+    appVersion: options.packager.appVersion,
+    arch: options.packager.arch,
+    asar: options.packager.asar,
+    backgroundColor: options.nativefier.backgroundColor,
+    basicAuthPassword: options.nativefier.basicAuthPassword,
+    basicAuthUsername: options.nativefier.basicAuthUsername,
+    blockExternalUrls: options.nativefier.blockExternalUrls,
+    bounce: options.nativefier.bounce,
+    browserwindowOptions: options.nativefier.browserwindowOptions,
+    buildDate: new Date().getTime(),
+    buildVersion: options.packager.buildVersion,
+    clearCache: options.nativefier.clearCache,
+    counter: options.nativefier.counter,
+    crashReporter: options.nativefier.crashReporter,
+    darwinDarkModeSupport: options.packager.darwinDarkModeSupport,
+    derefSymlinks: options.packager.derefSymlinks,
+    disableContextMenu: options.nativefier.disableContextMenu,
+    disableDevTools: options.nativefier.disableDevTools,
+    disableGpu: options.nativefier.disableGpu,
+    disableOldBuildWarning: options.nativefier.disableOldBuildWarning,
+    diskCacheSize: options.nativefier.diskCacheSize,
+    download: options.packager.download,
+    electronVersionUsed: options.packager.electronVersion,
+    enableEs3Apis: options.nativefier.enableEs3Apis,
+    executableName: options.packager.executableName,
+    fastQuit: options.nativefier.fastQuit,
+    fileDownloadOptions: options.nativefier.fileDownloadOptions,
+    flashPluginDir: options.nativefier.flashPluginDir,
+    fullScreen: options.nativefier.fullScreen,
+    globalShortcuts: options.nativefier.globalShortcuts,
+    height: options.nativefier.height,
+    helperBundleId: options.packager.helperBundleId,
+    hideWindowFrame: options.nativefier.hideWindowFrame,
+    ignoreCertificate: options.nativefier.ignoreCertificate,
+    ignoreGpuBlacklist: options.nativefier.ignoreGpuBlacklist,
+    insecure: options.nativefier.insecure,
+    internalUrls: options.nativefier.internalUrls,
+    isUpgrade: options.packager.upgrade,
+    junk: options.packager.junk,
+    lang: options.nativefier.lang,
+    maximize: options.nativefier.maximize,
+    maxHeight: options.nativefier.maxHeight,
+    maxWidth: options.nativefier.maxWidth,
+    minHeight: options.nativefier.minHeight,
+    minWidth: options.nativefier.minWidth,
+    name: options.packager.name ?? DEFAULT_APP_NAME,
+    nativefierVersion: options.nativefier.nativefierVersion,
+    osxNotarize: options.packager.osxNotarize,
+    osxSign: options.packager.osxSign,
+    portable: options.packager.portable,
+    processEnvs: options.nativefier.processEnvs,
+    protocols: options.packager.protocols,
+    proxyRules: options.nativefier.proxyRules,
+    prune: options.packager.prune,
+    quiet: options.packager.quiet,
+    showMenuBar: options.nativefier.showMenuBar,
+    singleInstance: options.nativefier.singleInstance,
+    strictInternalUrls: options.nativefier.strictInternalUrls,
+    targetUrl: options.packager.targetUrl,
+    titleBarStyle: options.nativefier.titleBarStyle,
+    tray: options.nativefier.tray,
+    usageDescription: options.packager.usageDescription,
+    userAgent: options.nativefier.userAgent,
+    userAgentHonest: options.nativefier.userAgentHonest,
+    versionString: options.nativefier.versionString,
+    width: options.nativefier.width,
+    widevine: options.nativefier.widevine,
+    win32metadata: options.packager.win32metadata,
+    x: options.nativefier.x,
+    y: options.nativefier.y,
+    zoom: options.nativefier.zoom,
+    // OLD_BUILD_WARNING_TEXT is an undocumented env. var to let *packagers*
+    // tweak the message shown on warning about an old build, to something
+    // more tailored to their audience (who might not even know Nativefier).
+    // See https://github.com/kelyvin/Google-Messages-For-Desktop/issues/34#issuecomment-812731144
+    // and https://github.com/nativefier/nativefier/issues/1131#issuecomment-812646988
+    oldBuildWarningText: process.env.OLD_BUILD_WARNING_TEXT || '',
+  };
+}
+
+async function maybeCopyScripts(
+  srcs: string[] | undefined,
+  dest: string,
+): Promise<void> {
+  if (!srcs || srcs.length === 0) {
+    log.debug('No files to inject, skipping copy.');
+    return;
+  }
+
+  const supportedInjectionExtensions = ['.css', '.js'];
+
+  log.debug(`Copying ${srcs.length} files to inject in app.`);
+  for (const src of srcs) {
+    if (!fs.existsSync(src)) {
+      throw new Error(
+        `File ${src} not found. Note that Nativefier expects *local* files, not URLs.`,
+      );
+    }
+
+    if (supportedInjectionExtensions.indexOf(path.extname(src)) < 0) {
+      log.warn('Skipping unsupported injection file', src);
+      continue;
+    }
+
+    const postFixHash = generateRandomSuffix();
+    const destFileName = `inject-${postFixHash}${path.extname(src)}`;
+    const destPath = path.join(dest, 'inject', destFileName);
+    log.debug(`Copying injection file "${src}" to "${destPath}"`);
+    await fs.copy(src, destPath);
+  }
+}
+
+/**
+ * Use a basic 6-character hash to prevent collisions. The hash is deterministic url & name,
+ * so that an upgrade (same URL) of an app keeps using the same appData folder.
+ * Warning! Changing this normalizing & hashing will change the way appNames are generated,
+ *          changing appData folder, and users will get logged out of their apps after an upgrade.
+ */
+export function normalizeAppName(appName: string, url: string): string {
+  const hash = crypto.createHash('md5');
+  hash.update(url);
+  const postFixHash = hash.digest('hex').substring(0, 6);
+  const normalized = appName
+    .toLowerCase()
+    .replace(/[,:.]/g, '')
+    .replace(/[\s_]/g, '-');
+  return `${normalized}-nativefier-${postFixHash}`;
+}
+
+function changeAppPackageJsonName(
+  appPath: string,
+  name: string,
+  url: string,
+): string {
+  const packageJsonPath = path.join(appPath, '/package.json');
+  const packageJson = parseJson<PackageJSON>(
+    fs.readFileSync(packageJsonPath).toString(),
+  );
+  if (!packageJson) {
+    throw new Error(`Could not load package.json from ${packageJsonPath}`);
+  }
+  const normalizedAppName = normalizeAppName(name, url);
+  packageJson.name = normalizedAppName;
+  log.debug(`Updating ${packageJsonPath} 'name' field to ${normalizedAppName}`);
+
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+
+  return normalizedAppName;
+}
+
+/**
+ * Creates a temporary directory, copies the './app folder' inside,
+ * and adds a text file with the app configuration.
+ */
+export async function prepareElectronApp(
+  src: string,
+  dest: string,
+  options: AppOptions,
+): Promise<void> {
+  log.debug(`Copying electron app from ${src} to ${dest}`);
+  try {
+    await fs.copy(src, dest);
+  } catch (err: unknown) {
+    throw `Error copying electron app from ${src} to temp dir ${dest}. Error: ${
+      (err as Error).message
+    }`;
+  }
+
+  const appJsonPath = path.join(dest, '/nativefier.json');
+  const pickedOptions = pickElectronAppArgs(options);
+  log.debug(`Writing app config to ${appJsonPath}`, pickedOptions);
+  await fs.writeFile(appJsonPath, JSON.stringify(pickedOptions));
+
+  if (options.nativefier.bookmarksMenu) {
+    const bookmarksJsonPath = path.join(dest, '/bookmarks.json');
+    try {
+      await fs.copy(options.nativefier.bookmarksMenu, bookmarksJsonPath);
+    } catch (err: unknown) {
+      log.error('Error copying bookmarks menu config file.', err);
+    }
+  }
+
+  try {
+    await maybeCopyScripts(options.nativefier.inject, dest);
+  } catch (err: unknown) {
+    log.error('Error copying injection files.', err);
+  }
+  const normalizedAppName = changeAppPackageJsonName(
+    dest,
+    options.packager.name as string,
+    options.packager.targetUrl,
+  );
+  options.packager.appBundleId = `com.electron.nativefier.${normalizedAppName}`;
+}

src/cli.test.ts

@@ -0,0 +1,326 @@
+import 'source-map-support/register';
+
+import { initArgs, parseArgs } from './cli';
+import { parseJson } from './utils/parseUtils';
+
+describe('initArgs + parseArgs', () => {
+  let mockExit: jest.SpyInstance;
+
+  beforeEach(() => {
+    mockExit = jest.spyOn(process, 'exit').mockImplementation();
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+  });
+
+  test('--help forces exit', () => {
+    // Mock console.log to not pollute the log with the yargs help text
+    const mockLog = jest.spyOn(console, 'log').mockImplementation();
+    initArgs(['https://www.google.com', '--help']);
+    expect(mockExit).toHaveBeenCalledTimes(1);
+    expect(mockLog).toBeCalled();
+    mockLog.mockRestore();
+  });
+
+  test('--version forces exit', () => {
+    // Mock console.log to not pollute the log with the yargs help text
+    const mockLog = jest.spyOn(console, 'log').mockImplementation();
+    initArgs(['https://www.google.com', '--version']);
+    expect(mockExit).toHaveBeenCalledTimes(1);
+    expect(mockLog).toBeCalled();
+    mockLog.mockRestore();
+  });
+
+  // Positional options
+
+  test('first positional becomes targetUrl', () => {
+    const args = parseArgs(initArgs(['https://google.com']));
+    expect(args.targetUrl).toBe('https://google.com');
+    expect(args.upgrade).toBeUndefined();
+  });
+
+  test('second positional becomes out', () => {
+    const args = parseArgs(initArgs(['https://google.com', 'tmp']));
+    expect(args.out).toBe('tmp');
+    expect(args.targetUrl).toBe('https://google.com');
+    expect(args.upgrade).toBeUndefined();
+  });
+
+  // App Creation Options
+  test('upgrade arg', () => {
+    const args = parseArgs(initArgs(['--upgrade', 'pathToUpgrade']));
+    expect(args.upgrade).toBe('pathToUpgrade');
+    expect(args.targetUrl).toBeUndefined();
+  });
+
+  test('upgrade arg with out dir', () => {
+    const args = parseArgs(initArgs(['tmp', '--upgrade', 'pathToUpgrade']));
+    expect(args.upgrade).toBe('pathToUpgrade');
+    expect(args.out).toBe('tmp');
+    expect(args.targetUrl).toBeUndefined();
+  });
+
+  test('upgrade arg with targetUrl', () => {
+    expect(() =>
+      parseArgs(
+        initArgs(['https://www.google.com', '--upgrade', 'path/to/upgrade']),
+      ),
+    ).toThrow();
+  });
+
+  test('multi-inject', () => {
+    const args = parseArgs(
+      initArgs([
+        'https://google.com',
+        '--inject',
+        'test.js',
+        '--inject',
+        'test2.js',
+        '--inject',
+        'test.css',
+        '--inject',
+        'test2.css',
+      ]),
+    );
+    expect(args.inject).toEqual([
+      'test.js',
+      'test2.js',
+      'test.css',
+      'test2.css',
+    ]);
+  });
+
+  test.each([
+    { arg: 'app-copyright', shortArg: '', value: '(c) Nativefier' },
+    { arg: 'app-version', shortArg: '', value: '2.0.0' },
+    { arg: 'background-color', shortArg: '', value: '#FFAA88' },
+    { arg: 'basic-auth-username', shortArg: '', value: 'user' },
+    { arg: 'basic-auth-password', shortArg: '', value: 'p@ssw0rd' },
+    { arg: 'bookmarks-menu', shortArg: '', value: 'bookmarks.json' },
+    {
+      arg: 'browserwindow-options',
+      shortArg: '',
+      value: '{"test": 456}',
+      isJsonString: true,
+    },
+    { arg: 'build-version', shortArg: '', value: '3.0.0' },
+    {
+      arg: 'crash-reporter',
+      shortArg: '',
+      value: 'https://crash-reporter.com',
+    },
+    { arg: 'electron-version', shortArg: 'e', value: '1.0.0' },
+    {
+      arg: 'file-download-options',
+      shortArg: '',
+      value: '{"test": 789}',
+      isJsonString: true,
+    },
+    { arg: 'flash-path', shortArg: '', value: 'pathToFlash' },
+    { arg: 'global-shortcuts', shortArg: '', value: 'shortcuts.json' },
+    { arg: 'icon', shortArg: 'i', value: 'icon.png' },
+    { arg: 'internal-urls', shortArg: '', value: '.*' },
+    { arg: 'lang', shortArg: '', value: 'fr' },
+    { arg: 'name', shortArg: 'n', value: 'Google' },
+    {
+      arg: 'process-envs',
+      shortArg: '',
+      value: '{"test": 123}',
+      isJsonString: true,
+    },
+    { arg: 'proxy-rules', shortArg: '', value: 'RULE: PROXY' },
+    { arg: 'tray', shortArg: '', value: 'true' },
+    { arg: 'user-agent', shortArg: 'u', value: 'FIREFOX' },
+    {
+      arg: 'win32metadata',
+      shortArg: '',
+      value: '{"ProductName": "Google"}',
+      isJsonString: true,
+    },
+  ])('test string arg %s', ({ arg, shortArg, value, isJsonString }) => {
+    const args = parseArgs(
+      initArgs(['https://google.com', `--${arg}`, value]),
+    ) as unknown as Record<string, string>;
+    if (!isJsonString) {
+      expect(args[arg]).toBe(value);
+    } else {
+      expect(args[arg]).toEqual(parseJson(value));
+    }
+
+    if (shortArg) {
+      const argsShort = parseArgs(
+        initArgs(['https://google.com', `-${shortArg}`, value]),
+      ) as unknown as Record<string, string>;
+      if (!isJsonString) {
+        expect(argsShort[arg]).toBe(value);
+      } else {
+        expect(argsShort[arg]).toEqual(parseJson(value));
+      }
+    }
+  });
+
+  test.each([
+    { arg: 'arch', shortArg: 'a', value: 'x64', badValue: '486' },
+    { arg: 'platform', shortArg: 'p', value: 'mac', badValue: 'os2' },
+    {
+      arg: 'title-bar-style',
+      shortArg: '',
+      value: 'hidden',
+      badValue: 'cool',
+    },
+  ])('limited choice arg %s', ({ arg, shortArg, value, badValue }) => {
+    const args = parseArgs(
+      initArgs(['https://google.com', `--${arg}`, value]),
+    ) as unknown as Record<string, string>;
+    expect(args[arg]).toBe(value);
+
+    // Mock console.error to not pollute the log with the yargs help text
+    const mockError = jest.spyOn(console, 'error').mockImplementation();
+    initArgs(['https://google.com', `--${arg}`, badValue]);
+    expect(mockExit).toHaveBeenCalledTimes(1);
+    expect(mockError).toBeCalled();
+    mockExit.mockClear();
+    mockError.mockClear();
+
+    if (shortArg) {
+      const argsShort = parseArgs(
+        initArgs(['https://google.com', `-${shortArg}`, value]),
+      ) as unknown as Record<string, string>;
+      expect(argsShort[arg]).toBe(value);
+
+      initArgs(['https://google.com', `-${shortArg}`, badValue]);
+      expect(mockExit).toHaveBeenCalledTimes(1);
+      expect(mockError).toBeCalled();
+    }
+    mockError.mockRestore();
+  });
+
+  test.each([
+    { arg: 'always-on-top', shortArg: '' },
+    { arg: 'block-external-urls', shortArg: '' },
+    { arg: 'bounce', shortArg: '' },
+    { arg: 'clear-cache', shortArg: '' },
+    { arg: 'conceal', shortArg: 'c' },
+    { arg: 'counter', shortArg: '' },
+    { arg: 'darwin-dark-mode-support', shortArg: '' },
+    { arg: 'disable-context-menu', shortArg: '' },
+    { arg: 'disable-dev-tools', shortArg: '' },
+    { arg: 'disable-gpu', shortArg: '' },
+    { arg: 'disable-old-build-warning-yesiknowitisinsecure', shortArg: '' },
+    { arg: 'enable-es3-apis', shortArg: '' },
+    { arg: 'fast-quit', shortArg: 'f' },
+    { arg: 'flash', shortArg: '' },
+    { arg: 'full-screen', shortArg: '' },
+    { arg: 'hide-window-frame', shortArg: '' },
+    { arg: 'honest', shortArg: '' },
+    { arg: 'ignore-certificate', shortArg: '' },
+    { arg: 'ignore-gpu-blacklist', shortArg: '' },
+    { arg: 'insecure', shortArg: '' },
+    { arg: 'maximize', shortArg: '' },
+    { arg: 'portable', shortArg: '' },
+    { arg: 'show-menu-bar', shortArg: 'm' },
+    { arg: 'single-instance', shortArg: '' },
+    { arg: 'strict-internal-urls', shortArg: '' },
+    { arg: 'verbose', shortArg: '' },
+    { arg: 'widevine', shortArg: '' },
+  ])('test boolean arg %s', ({ arg, shortArg }) => {
+    const defaultArgs = parseArgs(
+      initArgs(['https://google.com']),
+    ) as unknown as Record<string, boolean>;
+    expect(defaultArgs[arg]).toBe(false);
+
+    const args = parseArgs(
+      initArgs(['https://google.com', `--${arg}`]),
+    ) as unknown as Record<string, boolean>;
+    expect(args[arg]).toBe(true);
+    if (shortArg) {
+      const argsShort = parseArgs(
+        initArgs(['https://google.com', `-${shortArg}`]),
+      ) as unknown as Record<string, boolean>;
+      expect(argsShort[arg]).toBe(true);
+    }
+  });
+
+  test.each([{ arg: 'no-overwrite', shortArg: '' }])(
+    'test inversible boolean arg %s',
+    ({ arg, shortArg }) => {
+      const inverse = arg.startsWith('no-') ? arg.substr(3) : `no-${arg}`;
+
+      const defaultArgs = parseArgs(
+        initArgs(['https://google.com']),
+      ) as unknown as Record<string, boolean>;
+      expect(defaultArgs[arg]).toBe(false);
+      expect(defaultArgs[inverse]).toBe(true);
+
+      const args = parseArgs(
+        initArgs(['https://google.com', `--${arg}`]),
+      ) as unknown as Record<string, boolean>;
+      expect(args[arg]).toBe(true);
+      expect(args[inverse]).toBe(false);
+
+      if (shortArg) {
+        const argsShort = parseArgs(
+          initArgs(['https://google.com', `-${shortArg}`]),
+        ) as unknown as Record<string, boolean>;
+        expect(argsShort[arg]).toBe(true);
+        expect(argsShort[inverse]).toBe(true);
+      }
+    },
+  );
+
+  test.each([
+    { arg: 'disk-cache-size', shortArg: '', value: 100 },
+    { arg: 'height', shortArg: '', value: 200 },
+    { arg: 'max-height', shortArg: '', value: 300 },
+    { arg: 'max-width', shortArg: '', value: 400 },
+    { arg: 'min-height', shortArg: '', value: 500 },
+    { arg: 'min-width', shortArg: '', value: 600 },
+    { arg: 'width', shortArg: '', value: 700 },
+    { arg: 'x', shortArg: '', value: 800 },
+    { arg: 'y', shortArg: '', value: 900 },
+  ])('test numeric arg %s', ({ arg, shortArg, value }) => {
+    const args = parseArgs(
+      initArgs(['https://google.com', `--${arg}`, `${value}`]),
+    ) as unknown as Record<string, number>;
+    expect(args[arg]).toBe(value);
+
+    const badArgs = parseArgs(
+      initArgs(['https://google.com', `--${arg}`, 'abcd']),
+    ) as unknown as Record<string, number>;
+    expect(badArgs[arg]).toBeNaN();
+
+    if (shortArg) {
+      const shortArgs = parseArgs(
+        initArgs(['https://google.com', `-${shortArg}`, `${value}`]),
+      ) as unknown as Record<string, number>;
+      expect(shortArgs[arg]).toBe(value);
+
+      const badShortArgs = parseArgs(
+        initArgs(['https://google.com', `-${shortArg}`, 'abcd']),
+      ) as unknown as Record<string, number>;
+      expect(badShortArgs[arg]).toBeNaN();
+    }
+  });
+
+  test.each([
+    { arg: 'tray', value: 'true' },
+    { arg: 'tray', value: 'false' },
+    { arg: 'tray', value: 'start-in-tray' },
+    { arg: 'tray', value: '' },
+  ])('test tray valyue %s', ({ arg, value }) => {
+    const args = parseArgs(
+      initArgs(['https://google.com', `--${arg}`, `${value}`]),
+    ) as unknown as Record<string, number>;
+    if (value !== '') {
+      expect(args[arg]).toBe(value);
+    } else {
+      expect(args[arg]).toBe('true');
+    }
+  });
+
+  test('test tray value defaults to false', () => {
+    const args = parseArgs(initArgs(['https://google.com']));
+    expect(args.tray).toBe('false');
+  });
+});

src/cli.ts

@@ -0,0 +1,705 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+
+import electronPackager = require('electron-packager');
+import * as log from 'loglevel';
+import yargs from 'yargs';
+
+import { DEFAULT_ELECTRON_VERSION } from './constants';
+import {
+  camelCased,
+  checkInternet,
+  getProcessEnvs,
+  isArgFormatInvalid,
+} from './helpers/helpers';
+import { supportedArchs, supportedPlatforms } from './infer/inferOs';
+import { buildNativefierApp } from './main';
+import { RawOptions } from '../shared/src/options/model';
+import { parseJson } from './utils/parseUtils';
+
+// @types/yargs@17.x started pretending yargs.argv can be a promise:
+// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/8e17f9ca957a06040badb53ae7688fbb74229ccf/types/yargs/index.d.ts#L73
+// Dunno in which case it happens, but it doesn't for us! So, having to await
+// (and end up having to flag sync code as async) would be useless and annoying.
+// So, copy-pastaing and axing the Promise half of yargs's type definition,
+// to have a *non*-promise type. Maybe that's wrong. If it is, this type should
+// be dropped, and extra async-ness should be added where needed.
+type YargsArgvSync<T> = {
+  [key in keyof yargs.Arguments<T> as
+    | key
+    | yargs.CamelCaseKey<key>]: yargs.Arguments<T>[key];
+};
+
+export function initArgs(argv: string[]): yargs.Argv<RawOptions> {
+  const sanitizedArgs = sanitizeArgs(argv);
+  const args = yargs(sanitizedArgs)
+    .scriptName('nativefier')
+    .usage(
+      '$0 <targetUrl> [outputDirectory] [other options]\nor\n$0 --upgrade <pathToExistingApp> [other options]',
+    )
+    .example(
+      '$0 <targetUrl> -n <name>',
+      'Make an app from <targetUrl> and set the application name to <name>',
+    )
+    .example(
+      '$0 --upgrade <pathToExistingApp>',
+      'Upgrade (in place) the existing Nativefier app at <pathToExistingApp>',
+    )
+    .example(
+      '$0 <targetUrl> -p <platform> -a <arch>',
+      'Make an app from <targetUrl> for the OS <platform> and CPU architecture <arch>',
+    )
+    .example(
+      'for more examples and help...',
+      'See https://github.com/nativefier/nativefier/blob/master/CATALOG.md',
+    )
+    .positional('targetUrl', {
+      description:
+        'the URL that you wish to to turn into a native app; required if not using --upgrade',
+      type: 'string',
+    })
+    .positional('outputDirectory', {
+      defaultDescription:
+        'defaults to the current directory, or env. var. NATIVEFIER_APPS_DIR if set',
+      description: 'the directory to generate the app in',
+      normalize: true,
+      type: 'string',
+    })
+    // App Creation Options
+    .option('a', {
+      alias: 'arch',
+      choices: supportedArchs,
+      defaultDescription: "current Node's arch",
+      description: 'the CPU architecture to build for',
+      type: 'string',
+    })
+    .option('c', {
+      alias: 'conceal',
+      default: false,
+      description: 'package the app source code into an asar archive',
+      type: 'boolean',
+    })
+    .option('e', {
+      alias: 'electron-version',
+      defaultDescription: DEFAULT_ELECTRON_VERSION,
+      description:
+        "specify the electron version to use (without the 'v'); see https://github.com/electron/electron/releases",
+    })
+    .option('global-shortcuts', {
+      description:
+        'define global keyboard shortcuts via a JSON file; See https://github.com/nativefier/nativefier/blob/master/API.md#global-shortcuts',
+      normalize: true,
+      type: 'string',
+    })
+    .option('i', {
+      alias: 'icon',
+      description:
+        'the icon file to use as the icon for the app (.ico on Windows, .icns/.png on macOS, .png on Linux)',
+      normalize: true,
+      type: 'string',
+    })
+    .option('n', {
+      alias: 'name',
+      defaultDescription: 'the title of the page passed via targetUrl',
+      description: 'specify the name of the app',
+      type: 'string',
+    })
+    .option('no-overwrite', {
+      default: false,
+      description: 'do not overwrite output directory if it already exists',
+      type: 'boolean',
+    })
+    .option('overwrite', {
+      // This is needed to have the `no-overwrite` flag to work correctly
+      default: true,
+      hidden: true,
+      type: 'boolean',
+    })
+    .option('p', {
+      alias: 'platform',
+      choices: supportedPlatforms,
+      defaultDescription: 'current operating system',
+      description: 'the operating system platform to build for',
+      type: 'string',
+    })
+    .option('portable', {
+      default: false,
+      description:
+        'make the app store its user data in the app folder; WARNING: see https://github.com/nativefier/nativefier/blob/master/API.md#portable for security risks',
+      type: 'boolean',
+    })
+    .option('upgrade', {
+      description:
+        'upgrade an app built by an older version of Nativefier\nYou must pass the full path to the existing app executable (app will be overwritten with upgraded version by default)',
+      normalize: true,
+      type: 'string',
+    })
+    .option('widevine', {
+      default: false,
+      description:
+        "use a Widevine-enabled version of Electron for DRM playback (use at your own risk, it's unofficial, provided by CastLabs)",
+      type: 'boolean',
+    })
+    .group(
+      [
+        'arch',
+        'conceal',
+        'electron-version',
+        'global-shortcuts',
+        'icon',
+        'name',
+        'no-overwrite',
+        'platform',
+        'portable',
+        'upgrade',
+        'widevine',
+      ],
+      decorateYargOptionGroup('App Creation Options'),
+    )
+    // App Window Options
+    .option('always-on-top', {
+      default: false,
+      description: 'enable always on top window',
+      type: 'boolean',
+    })
+    .option('background-color', {
+      description:
+        "set the app background color, for better integration while the app is loading. Example value: '#2e2c29'",
+      type: 'string',
+    })
+    .option('bookmarks-menu', {
+      description:
+        'create a bookmarks menu (via JSON file); See https://github.com/nativefier/nativefier/blob/master/API.md#bookmarks-menu',
+      normalize: true,
+      type: 'string',
+    })
+    .option('browserwindow-options', {
+      coerce: parseJson,
+      description:
+        'override Electron BrowserWindow options (via JSON string); see https://github.com/nativefier/nativefier/blob/master/API.md#browserwindow-options',
+    })
+    .option('disable-context-menu', {
+      default: false,
+      description: 'disable the context menu (right click)',
+      type: 'boolean',
+    })
+    .option('disable-dev-tools', {
+      default: false,
+      description: 'disable developer tools (Ctrl+Shift+I / F12)',
+      type: 'boolean',
+    })
+    .option('full-screen', {
+      default: false,
+      description: 'always start the app full screen',
+      type: 'boolean',
+    })
+    .option('height', {
+      defaultDescription: '800',
+      description: 'set window default height in pixels',
+      type: 'number',
+    })
+    .option('hide-window-frame', {
+      default: false,
+      description: 'disable window frame and controls',
+      type: 'boolean',
+    })
+    .option('m', {
+      alias: 'show-menu-bar',
+      default: false,
+      description: 'set menu bar visible',
+      type: 'boolean',
+    })
+    .option('max-height', {
+      defaultDescription: 'unlimited',
+      description: 'set window maximum height in pixels',
+      type: 'number',
+    })
+    .option('max-width', {
+      defaultDescription: 'unlimited',
+      description: 'set window maximum width in pixels',
+      type: 'number',
+    })
+    .option('maximize', {
+      default: false,
+      description: 'always start the app maximized',
+      type: 'boolean',
+    })
+    .option('min-height', {
+      defaultDescription: '0',
+      description: 'set window minimum height in pixels',
+      type: 'number',
+    })
+    .option('min-width', {
+      defaultDescription: '0',
+      description: 'set window minimum width in pixels',
+      type: 'number',
+    })
+    .option('process-envs', {
+      coerce: getProcessEnvs,
+      description:
+        'a JSON string of key/value pairs to be set as environment variables before any browser windows are opened',
+    })
+    .option('single-instance', {
+      default: false,
+      description: 'allow only a single instance of the app',
+      type: 'boolean',
+    })
+    .option('tray', {
+      default: 'false',
+      description:
+        "allow app to stay in system tray. If 'start-in-tray' is set as argument, don't show main window on first start",
+      choices: ['true', 'false', 'start-in-tray'],
+    })
+    .option('width', {
+      defaultDescription: '1280',
+      description: 'app window default width in pixels',
+      type: 'number',
+    })
+    .option('x', {
+      description: 'set window x location in pixels from left',
+      type: 'number',
+    })
+    .option('y', {
+      description: 'set window y location in pixels from top',
+      type: 'number',
+    })
+    .option('zoom', {
+      default: 1.0,
+      description: 'set the default zoom factor for the app',
+      type: 'number',
+    })
+    .group(
+      [
+        'always-on-top',
+        'background-color',
+        'bookmarks-menu',
+        'browserwindow-options',
+        'disable-context-menu',
+        'disable-dev-tools',
+        'full-screen',
+        'height',
+        'hide-window-frame',
+        'm',
+        'max-width',
+        'max-height',
+        'maximize',
+        'min-height',
+        'min-width',
+        'process-envs',
+        'single-instance',
+        'tray',
+        'width',
+        'x',
+        'y',
+        'zoom',
+      ],
+      decorateYargOptionGroup('App Window Options'),
+    )
+    // Internal Browser Options
+    .option('file-download-options', {
+      coerce: parseJson,
+      description:
+        'a JSON string defining file download options; see https://github.com/sindresorhus/electron-dl',
+    })
+    .option('inject', {
+      description:
+        'path to a CSS/JS file to be injected; pass multiple times to inject multiple files',
+      string: true,
+      type: 'array',
+    })
+    .option('lang', {
+      defaultDescription: 'os language at runtime of the app',
+      description:
+        'set the language or locale to render the web site as (e.g., "fr", "en-US", "es", etc.)',
+      type: 'string',
+    })
+    .option('u', {
+      alias: 'user-agent',
+      description:
+        "set the app's user agent string; may also use 'edge', 'firefox', or 'safari' to have one auto-generated",
+      type: 'string',
+    })
+    .option('user-agent-honest', {
+      alias: 'honest',
+      default: false,
+      description:
+        'prevent the normal changing of the user agent string to appear as a regular Chrome browser',
+      type: 'boolean',
+    })
+    .group(
+      [
+        'file-download-options',
+        'inject',
+        'lang',
+        'user-agent',
+        'user-agent-honest',
+      ],
+      decorateYargOptionGroup('Internal Browser Options'),
+    )
+    // Internal Browser Cache Options
+    .option('clear-cache', {
+      default: false,
+      description: 'prevent the app from preserving cache between launches',
+      type: 'boolean',
+    })
+    .option('disk-cache-size', {
+      defaultDescription: 'chromium default',
+      description:
+        'set the maximum disk space (in bytes) to be used by the disk cache',
+      type: 'number',
+    })
+    .group(
+      ['clear-cache', 'disk-cache-size'],
+      decorateYargOptionGroup('Internal Browser Cache Options'),
+    )
+    // URL Handling Options
+    .option('block-external-urls', {
+      default: false,
+      description: `forbid navigation to URLs not considered "internal" (see '--internal-urls').  Instead of opening in an external browser, attempts to navigate to external URLs will be blocked`,
+      type: 'boolean',
+    })
+    .option('internal-urls', {
+      defaultDescription: 'URLs sharing the same base domain',
+      description: `regex of URLs to consider "internal"; by default matches based on domain (see '--strict-internal-urls'); all other URLs will be opened in an external browser`,
+      type: 'string',
+    })
+    .option('strict-internal-urls', {
+      default: false,
+      description: 'disable domain-based matching on internal URLs',
+      type: 'boolean',
+    })
+    .option('proxy-rules', {
+      description:
+        'proxy rules; see https://www.electronjs.org/docs/api/session#sessetproxyconfig',
+      type: 'string',
+    })
+    .group(
+      [
+        'block-external-urls',
+        'internal-urls',
+        'strict-internal-urls',
+        'proxy-rules',
+      ],
+      decorateYargOptionGroup('URL Handling Options'),
+    )
+    // Auth Options
+    .option('basic-auth-password', {
+      description: 'basic http(s) auth password',
+      type: 'string',
+    })
+    .option('basic-auth-username', {
+      description: 'basic http(s) auth username',
+      type: 'string',
+    })
+    .group(
+      ['basic-auth-password', 'basic-auth-username'],
+      decorateYargOptionGroup('Auth Options'),
+    )
+    // Graphics Options
+    .option('disable-gpu', {
+      default: false,
+      description: 'disable hardware acceleration',
+      type: 'boolean',
+    })
+    .option('enable-es3-apis', {
+      default: false,
+      description: 'force activation of WebGL 2.0',
+      type: 'boolean',
+    })
+    .option('ignore-gpu-blacklist', {
+      default: false,
+      description: 'force WebGL apps to work on unsupported GPUs',
+      type: 'boolean',
+    })
+    .group(
+      ['disable-gpu', 'enable-es3-apis', 'ignore-gpu-blacklist'],
+      decorateYargOptionGroup('Graphics Options'),
+    )
+    // (In)Security Options
+    .option('disable-old-build-warning-yesiknowitisinsecure', {
+      default: false,
+      description:
+        'disable warning shown when opening an app made too long ago; Nativefier uses the Chrome browser (through Electron), and it is dangerous to keep using an old version of it',
+      type: 'boolean',
+    })
+    .option('ignore-certificate', {
+      default: false,
+      description: 'ignore certificate-related errors',
+      type: 'boolean',
+    })
+    .option('insecure', {
+      default: false,
+      description: 'enable loading of insecure content',
+      type: 'boolean',
+    })
+    .group(
+      [
+        'disable-old-build-warning-yesiknowitisinsecure',
+        'ignore-certificate',
+        'insecure',
+      ],
+      decorateYargOptionGroup('(In)Security Options'),
+    )
+    // Flash Options (DEPRECATED)
+    .option('flash', {
+      default: false,
+      deprecated: true,
+      description: 'enable Adobe Flash',
+      hidden: true,
+      type: 'boolean',
+    })
+    .option('flash-path', {
+      deprecated: true,
+      description: 'path to Chrome flash plugin; find it in `chrome://plugins`',
+      hidden: true,
+      normalize: true,
+      type: 'string',
+    })
+    // Platform Specific Options
+    .option('app-copyright', {
+      description:
+        '(macOS, windows only) set a human-readable copyright line for the app; maps to `LegalCopyright` metadata property on Windows, and `NSHumanReadableCopyright` on macOS',
+      type: 'string',
+    })
+    .option('app-version', {
+      description:
+        '(macOS, windows only) set the version of the app; maps to the `ProductVersion` metadata property on Windows, and `CFBundleShortVersionString` on macOS',
+      type: 'string',
+    })
+    .option('bounce', {
+      default: false,
+      description:
+        '(macOS only) make the dock icon bounce when the counter increases',
+      type: 'boolean',
+    })
+    .option('build-version', {
+      description:
+        '(macOS, windows only) set the build version of the app; maps to `FileVersion` metadata property on Windows, and `CFBundleVersion` on macOS',
+      type: 'string',
+    })
+    .option('counter', {
+      default: false,
+      description:
+        '(macOS only) set a dock count badge, determined by looking for a number in the window title',
+      type: 'boolean',
+    })
+    .option('darwin-dark-mode-support', {
+      default: false,
+      description: '(macOS only) enable Dark Mode support on macOS 10.14+',
+      type: 'boolean',
+    })
+    .option('f', {
+      alias: 'fast-quit',
+      default: false,
+      description: '(macOS only) quit app on window close',
+      type: 'boolean',
+    })
+    .option('title-bar-style', {
+      choices: ['hidden', 'hiddenInset'],
+      description:
+        '(macOS only) set title bar style; consider injecting custom CSS (via --inject) for better integration',
+      type: 'string',
+    })
+    .option('win32metadata', {
+      coerce: (value: string) =>
+        parseJson<electronPackager.Win32MetadataOptions>(value),
+      description:
+        '(windows only) a JSON string of key/value pairs (ProductName, InternalName, FileDescription) to embed as executable metadata',
+    })
+    .group(
+      [
+        'app-copyright',
+        'app-version',
+        'bounce',
+        'build-version',
+        'counter',
+        'darwin-dark-mode-support',
+        'fast-quit',
+        'title-bar-style',
+        'win32metadata',
+      ],
+      decorateYargOptionGroup('Platform-Specific Options'),
+    )
+    // Debug Options
+    .option('crash-reporter', {
+      description: 'remote server URL to send crash reports',
+      type: 'string',
+    })
+    .option('verbose', {
+      default: false,
+      description: 'enable verbose/debug/troubleshooting logs',
+      type: 'boolean',
+    })
+    .option('quiet', {
+      default: false,
+      description: 'suppress all logging',
+      type: 'boolean',
+    })
+    .group(
+      ['crash-reporter', 'verbose', 'quiet'],
+      decorateYargOptionGroup('Debug Options'),
+    )
+    .version()
+    .help()
+    .group(['version', 'help'], 'Other Options')
+    .wrap(yargs.terminalWidth());
+
+  // We must access argv in order to get yargs to actually process args
+  // Do this now to go ahead and get any errors out of the way
+  args.argv as YargsArgvSync<RawOptions>;
+
+  return args as yargs.Argv<RawOptions>;
+}
+
+function decorateYargOptionGroup(value: string): string {
+  return `====== ${value} ======`;
+}
+
+export function parseArgs(args: yargs.Argv<RawOptions>): RawOptions {
+  const parsed = { ...(args.argv as YargsArgvSync<RawOptions>) };
+  // In yargs, the _ property of the parsed args is an array of the positional args
+  // https://github.com/yargs/yargs/blob/master/docs/examples.md#and-non-hyphenated-options-too-just-use-argv_
+  // So try to extract the targetUrl and outputDirectory from these
+  parsed.targetUrl = parsed._.length > 0 ? parsed._[0].toString() : undefined;
+  parsed.out = parsed._.length > 1 ? (parsed._[1] as string) : undefined;
+
+  if (parsed.upgrade && parsed.targetUrl) {
+    let targetAndUpgrade = false;
+    if (!parsed.out) {
+      // If we're upgrading, the first positional args might be the outputDirectory, so swap these if we can
+      try {
+        // If this succeeds, we have a problem
+        new URL(parsed.targetUrl);
+        targetAndUpgrade = true;
+      } catch {
+        // Cool, it's not a URL
+        parsed.out = parsed.targetUrl;
+        parsed.targetUrl = undefined;
+      }
+    } else {
+      // Someone supplied a targetUrl, an outputDirectory, and --upgrade. That's not cool.
+      targetAndUpgrade = true;
+    }
+
+    if (targetAndUpgrade) {
+      throw new Error(
+        'ERROR: Nativefier must be called with either a targetUrl or the --upgrade option, not both.\n',
+      );
+    }
+  }
+
+  if (!parsed.targetUrl && !parsed.upgrade) {
+    throw new Error(
+      'ERROR: Nativefier must be called with either a targetUrl or the --upgrade option.\n',
+    );
+  }
+
+  parsed.noOverwrite = parsed['no-overwrite'] = !parsed.overwrite;
+
+  // Since coerce in yargs seems to have broken since
+  // https://github.com/yargs/yargs/pull/1978
+  for (const arg of [
+    'win32metadata',
+    'browserwindow-options',
+    'file-download-options',
+  ]) {
+    if (parsed[arg] && typeof parsed[arg] === 'string') {
+      parsed[arg] = parseJson(parsed[arg] as string);
+      // sets fileDownloadOptions and browserWindowOptions
+      // as parsed object as they were still strings in `nativefier.json`
+      // because only their snake-cased variants were being parsed above
+      parsed[camelCased(arg)] = parsed[arg];
+    }
+  }
+  if (parsed['process-envs'] && typeof parsed['process-envs'] === 'string') {
+    parsed['process-envs'] = getProcessEnvs(parsed['process-envs']);
+  }
+
+  return parsed;
+}
+
+function sanitizeArgs(argv: string[]): string[] {
+  const sanitizedArgs: string[] = [];
+  argv.forEach((arg) => {
+    if (isArgFormatInvalid(arg)) {
+      throw new Error(
+        `Invalid argument passed: ${arg} .\nNativefier supports short options (like "-n") and long options (like "--name"), all lowercase. Run "nativefier --help" for help.\nAborting`,
+      );
+    }
+    const isLastArg = sanitizedArgs.length + 1 === argv.length;
+    if (sanitizedArgs.length > 0) {
+      const previousArg = sanitizedArgs[sanitizedArgs.length - 1];
+
+      log.debug({ arg, previousArg, isLastArg });
+
+      // Work around commander.js not supporting default argument for options
+      if (
+        previousArg === '--tray' &&
+        !['true', 'false', 'start-in-tray'].includes(arg)
+      ) {
+        sanitizedArgs.push('true');
+      }
+    }
+    sanitizedArgs.push(arg);
+
+    if (arg === '--tray' && isLastArg) {
+      // Add a true if --tray is last so it gets enabled
+      sanitizedArgs.push('true');
+    }
+  });
+
+  return sanitizedArgs;
+}
+
+if (require.main === module) {
+  let args: yargs.Argv<RawOptions> | undefined = undefined;
+  let parsedArgs: RawOptions;
+  try {
+    args = initArgs(process.argv.slice(2));
+    parsedArgs = parseArgs(args);
+  } catch (err: unknown) {
+    if (args) {
+      log.error(err);
+      args.showHelp();
+    } else {
+      log.error('Failed to parse command-line arguments. Aborting.', err);
+    }
+    process.exit(1);
+  }
+
+  const options: RawOptions = {
+    ...parsedArgs,
+  };
+
+  if (options.verbose) {
+    log.setLevel('trace');
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+      require('debug').enable('electron-packager');
+    } catch (err: unknown) {
+      log.debug(
+        'Failed to enable electron-packager debug output. This should not happen,',
+        'and suggests their internals changed. Please report an issue.',
+      );
+    }
+
+    log.debug(
+      'Running in verbose mode! This will produce a mountain of logs and',
+      'is recommended only for troubleshooting or if you like Shakespeare.',
+    );
+  } else if (options.quiet) {
+    log.setLevel('silent');
+  } else {
+    log.setLevel('info');
+  }
+
+  checkInternet();
+
+  if (!options.out && process.env.NATIVEFIER_APPS_DIR) {
+    options.out = process.env.NATIVEFIER_APPS_DIR;
+  }
+
+  buildNativefierApp(options).catch((error) => {
+    log.error('Error during build. Run with --verbose for details.', error);
+  });
+}

src/constants.ts

@@ -0,0 +1,29 @@
+import * as path from 'path';
+
+export const DEFAULT_APP_NAME = 'APP';
+
+// Upgrade both DEFAULT_ELECTRON_VERSION and DEFAULT_CHROME_VERSION together, and
+//   - upgrade app / package.json / "devDependencies" / "electron"
+//   - upgrade       package.json / "devDependencies" / "electron"
+// Doing a *major* upgrade? Read https://github.com/nativefier/nativefier/blob/master/HACKING.md#deps-major-upgrading-electron
+export const DEFAULT_ELECTRON_VERSION = '25.7.0';
+// https://atom.io/download/atom-shell/index.json
+// https://www.electronjs.org/releases/stable
+export const DEFAULT_CHROME_VERSION = '114.0.5735.289';
+
+// Update each of these periodically
+// https://product-details.mozilla.org/1.0/firefox_versions.json
+export const DEFAULT_FIREFOX_VERSION = '116.0.3';
+
+// https://en.wikipedia.org/wiki/Safari_version_history
+export const DEFAULT_SAFARI_VERSION = {
+  majorVersion: 16,
+  version: '16.6',
+  webkitVersion: '605.1.15',
+};
+
+export const ELECTRON_MAJOR_VERSION = parseInt(
+  DEFAULT_ELECTRON_VERSION.split('.')[0],
+  10,
+);
+export const PLACEHOLDER_APP_DIR = path.join(__dirname, './../', 'app');

src/helpers/fsHelpers.ts

@@ -0,0 +1,19 @@
+import * as fs from 'fs';
+
+export function dirExists(dirName: string): boolean {
+  try {
+    const dirStat = fs.statSync(dirName);
+    return dirStat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function fileExists(fileName: string): boolean {
+  try {
+    const fileStat = fs.statSync(fileName);
+    return fileStat.isFile();
+  } catch {
+    return false;
+  }
+}

src/helpers/helpers.test.ts

@@ -0,0 +1,84 @@
+import {
+  isArgFormatInvalid,
+  generateRandomSuffix,
+  camelCased,
+} from './helpers';
+
+describe('isArgFormatInvalid', () => {
+  test('is false for correct short args', () => {
+    expect(isArgFormatInvalid('-t')).toBe(false);
+  });
+
+  test('is true for improperly double-dashed short args', () => {
+    expect(isArgFormatInvalid('--t')).toBe(true);
+  });
+
+  test('is false for --x and --y (backwards compat, we should have made these short, oh well)', () => {
+    expect(isArgFormatInvalid('--x')).toBe(false);
+    expect(isArgFormatInvalid('--y')).toBe(false);
+  });
+
+  test('is false for correct long args', () => {
+    expect(isArgFormatInvalid('--test')).toBe(false);
+  });
+
+  test('is true for improperly triple-dashed long args', () => {
+    expect(isArgFormatInvalid('---test')).toBe(true);
+  });
+
+  test('is true for improperly single-dashed long args', () => {
+    expect(isArgFormatInvalid('-test')).toBe(true);
+  });
+
+  test('is false for correct long args with dashes', () => {
+    expect(isArgFormatInvalid('--test-run')).toBe(false);
+  });
+
+  test('is false for correct long args with many dashes', () => {
+    expect(isArgFormatInvalid('--test-run-with-many-dashes')).toBe(false);
+  });
+});
+
+describe('generateRandomSuffix', () => {
+  test('is not empty', () => {
+    expect(generateRandomSuffix()).not.toBe('');
+  });
+
+  test('is not null', () => {
+    expect(generateRandomSuffix()).not.toBeNull();
+  });
+
+  test('is not undefined', () => {
+    expect(generateRandomSuffix()).toBeDefined();
+  });
+
+  test('is different per call', () => {
+    expect(generateRandomSuffix()).not.toBe(generateRandomSuffix());
+  });
+
+  test('respects the length param', () => {
+    expect(generateRandomSuffix(10).length).toBe(10);
+  });
+});
+
+describe('camelCased', () => {
+  test('has no hyphens in camel case', () => {
+    expect(camelCased('file-download')).toEqual(expect.not.stringMatching(/-/));
+  });
+
+  test('returns camel cased string', () => {
+    expect(camelCased('file-download')).toBe('fileDownload');
+  });
+
+  test('has no spaces in camel case', () => {
+    expect(camelCased('--file--download--')).toBe('fileDownload');
+  });
+
+  test('handles multiple hyphens properly', () => {
+    expect(camelCased('file--download--options')).toBe('fileDownloadOptions');
+  });
+
+  test('does not affect non-snake cased strings', () => {
+    expect(camelCased('win32options')).toBe('win32options');
+  });
+});

src/helpers/helpers.ts

@@ -0,0 +1,211 @@
+import { spawnSync } from 'child_process';
+import * as crypto from 'crypto';
+import * as os from 'os';
+import * as path from 'path';
+
+import axios from 'axios';
+import * as dns from 'dns';
+import * as hasbin from 'hasbin';
+import * as log from 'loglevel';
+import * as tmp from 'tmp';
+
+import { parseJson } from '../utils/parseUtils';
+
+tmp.setGracefulCleanup(); // cleanup temp dirs even when an uncaught exception occurs
+
+const now = new Date();
+const TMP_TIME = `${now.getHours()}-${now.getMinutes()}-${now.getSeconds()}`;
+
+export type DownloadResult = {
+  data: Buffer;
+  ext: string;
+};
+
+type ProcessEnvs = Record<string, unknown>;
+
+export function hasWine(): boolean {
+  return hasbin.sync('wine');
+}
+
+// I tried to place this (and the other is* functions) in
+// a new shared helpers, but alas eslint gets real confused
+// about the type signatures and thinks they're all any.
+// TODO: Figure out a way to refactor duplicate code from
+// src/helpers/helpers.ts and app/src/helpers/helpers.ts
+// into the shared module
+
+export function isLinux(): boolean {
+  return os.platform() === 'linux';
+}
+
+export function isOSX(): boolean {
+  return os.platform() === 'darwin';
+}
+
+export function isWindows(): boolean {
+  return os.platform() === 'win32';
+}
+
+export function isWindowsAdmin(): boolean {
+  if (process.platform !== 'win32') {
+    return false;
+  }
+
+  // https://stackoverflow.com/questions/4051883/batch-script-how-to-check-for-admin-rights
+  // https://stackoverflow.com/questions/57009374/check-admin-or-non-admin-users-in-nodejs-or-javascript
+  return spawnSync('fltmc').status === 0;
+}
+
+/**
+ * Create a temp directory with a debug-friendly name, and return its path.
+ * Will be automatically deleted on exit.
+ */
+export function getTempDir(prefix: string, mode?: number): string {
+  return tmp.dirSync({
+    mode,
+    unsafeCleanup: true, // recursively remove tmp dir on exit, even if not empty.
+    prefix: `nativefier-${TMP_TIME}-${prefix}-`,
+  }).name;
+}
+
+export function downloadFile(
+  fileUrl: string,
+): Promise<DownloadResult | undefined> {
+  log.debug(`Downloading ${fileUrl}`);
+  return axios
+    .get<Buffer>(fileUrl, {
+      responseType: 'arraybuffer',
+    })
+    .then((response) => {
+      if (!response.data) {
+        return undefined;
+      }
+      return {
+        data: response.data,
+        ext: path.extname(fileUrl),
+      };
+    });
+}
+
+export function getAllowedIconFormats(platform: string): string[] {
+  const hasIdentify = hasbin.sync('identify') || hasbin.sync('gm');
+  const hasConvert = hasbin.sync('convert') || hasbin.sync('gm');
+  const hasIconUtil = hasbin.sync('iconutil');
+
+  const pngToIcns = hasConvert && hasIconUtil;
+  const pngToIco = hasConvert;
+  const icoToIcns = pngToIcns && hasIdentify;
+  const icoToPng = hasConvert;
+
+  // Unsupported
+  const icnsToPng = false;
+  const icnsToIco = false;
+
+  const formats: string[] = [];
+
+  // Shell scripting is not supported on windows, temporary override
+  if (isWindows()) {
+    switch (platform) {
+      case 'darwin':
+        formats.push('.icns');
+        break;
+      case 'linux':
+        formats.push('.png');
+        break;
+      case 'win32':
+        formats.push('.ico');
+        break;
+      default:
+        throw new Error(`Unknown platform ${platform}`);
+    }
+    log.debug(
+      `Allowed icon formats when building for ${platform} (limited on Windows):`,
+      formats,
+    );
+    return formats;
+  }
+
+  switch (platform) {
+    case 'darwin':
+      formats.push('.icns');
+      if (pngToIcns) {
+        formats.push('.png');
+      }
+      if (icoToIcns) {
+        formats.push('.ico');
+      }
+      break;
+    case 'linux':
+      formats.push('.png');
+      if (icoToPng) {
+        formats.push('.ico');
+      }
+      if (icnsToPng) {
+        formats.push('.icns');
+      }
+      break;
+    case 'win32':
+      formats.push('.ico');
+      if (pngToIco) {
+        formats.push('.png');
+      }
+      if (icnsToIco) {
+        formats.push('.icns');
+      }
+      break;
+    default:
+      throw new Error(`Unknown platform ${platform}`);
+  }
+  log.debug(`Allowed icon formats when building for ${platform}:`, formats);
+  return formats;
+}
+
+/**
+ * Refuse args like '--n' or '-name', we accept either short '-n' or long '--name'
+ */
+export function isArgFormatInvalid(arg: string): boolean {
+  return (
+    (arg.startsWith('---') ||
+      /^--[a-z]$/i.exec(arg) !== null ||
+      /^-[a-z]{2,}$/i.exec(arg) !== null) &&
+    !['--x', '--y'].includes(arg) // exception for long args --{x,y}
+  );
+}
+
+export function generateRandomSuffix(length = 6): string {
+  const hash = crypto.createHash('md5');
+  // Add a random salt to help avoid collisions
+  hash.update(crypto.randomBytes(256));
+  return hash.digest('hex').substring(0, length);
+}
+
+export function getProcessEnvs(val: string): ProcessEnvs | undefined {
+  if (!val) {
+    return undefined;
+  }
+  return parseJson<ProcessEnvs>(val);
+}
+
+export function checkInternet(): void {
+  dns.lookup('npmjs.com', (err) => {
+    if (err && err.code === 'ENOTFOUND') {
+      log.warn(
+        '\nNo Internet Connection\nTo offline build, download electron from https://github.com/electron/electron/releases\nand place in ~/AppData/Local/electron/Cache/ on Windows,\n~/.cache/electron on Linux or ~/Library/Caches/electron/ on Mac\nUse --electron-version to specify the version you downloaded.',
+      );
+    }
+  });
+}
+
+/**
+ * Takes in a snake-cased string and converts to camelCase
+ */
+export function camelCased(str: string): string {
+  return str
+    .split('-')
+    .filter((s) => s.length > 0)
+    .map((word, i) => {
+      if (i === 0) return word;
+      return `${word[0].toUpperCase()}${word.substring(1)}`;
+    })
+    .join('');
+}

src/helpers/iconShellHelpers.ts

@@ -0,0 +1,100 @@
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+import { isWindows, isOSX, getTempDir } from './helpers';
+import * as log from 'loglevel';
+
+const SCRIPT_PATHS = {
+  singleIco: path.join(__dirname, '../..', 'icon-scripts/singleIco'),
+  convertToPng: path.join(__dirname, '../..', 'icon-scripts/convertToPng'),
+  convertToIco: path.join(__dirname, '../..', 'icon-scripts/convertToIco'),
+  convertToIcns: path.join(__dirname, '../..', 'icon-scripts/convertToIcns'),
+  convertToTrayIcon: path.join(
+    __dirname,
+    '../..',
+    'icon-scripts/convertToTrayIcon',
+  ),
+};
+
+/**
+ * Executes a shell script with the form "./pathToScript param1 param2"
+ */
+function iconShellHelper(
+  shellScriptPath: string,
+  icoSource: string,
+  icoDestination: string,
+): string {
+  if (isWindows()) {
+    throw new Error(
+      'Icon conversion only supported on macOS or Linux. ' +
+        'If building for Windows, download/create a .ico and pass it with --icon favicon.ico . ' +
+        'If building for macOS/Linux, do it from macOS/Linux',
+    );
+  }
+
+  const shellCommand = `"${shellScriptPath}" "${icoSource}" "${icoDestination}"`;
+  log.debug(
+    `Converting icon ${icoSource} to ${icoDestination}.`,
+    `Calling shell command: ${shellCommand}`,
+  );
+  const { stdout, stderr, status } = spawnSync(
+    shellScriptPath,
+    [icoSource, icoDestination],
+    { timeout: 10000 },
+  );
+  if (status) {
+    throw new Error(
+      `Icon conversion failed with status code ${status}.\nstdout: ${stdout.toString()}\nstderr: ${stderr.toString()}`,
+    );
+  }
+  log.debug(`Conversion succeeded and produced icon at ${icoDestination}`);
+  return icoDestination;
+}
+
+export function singleIco(icoSrc: string): string {
+  return iconShellHelper(
+    SCRIPT_PATHS.singleIco,
+    icoSrc,
+    `${getTempDir('iconconv')}/icon.ico`,
+  );
+}
+
+export function convertToPng(icoSrc: string): string {
+  return iconShellHelper(
+    SCRIPT_PATHS.convertToPng,
+    icoSrc,
+    `${getTempDir('iconconv')}/icon.png`,
+  );
+}
+
+export function convertToIco(icoSrc: string): string {
+  return iconShellHelper(
+    SCRIPT_PATHS.convertToIco,
+    icoSrc,
+    `${getTempDir('iconconv')}/icon.ico`,
+  );
+}
+
+export function convertToIcns(icoSrc: string): string {
+  if (!isOSX()) {
+    throw new Error('macOS is required to convert to a .icns icon');
+  }
+
+  return iconShellHelper(
+    SCRIPT_PATHS.convertToIcns,
+    icoSrc,
+    `${getTempDir('iconconv')}/icon.icns`,
+  );
+}
+
+export function convertToTrayIcon(icoSrc: string): string {
+  if (!isOSX()) {
+    throw new Error('macOS is required to convert from a .icns icon');
+  }
+
+  return iconShellHelper(
+    SCRIPT_PATHS.convertToTrayIcon,
+    icoSrc,
+    `${path.dirname(icoSrc)}/tray-icon.png`,
+  );
+}

src/helpers/upgrade/executableHelpers.ts

@@ -0,0 +1,208 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import * as log from 'loglevel';
+
+import { NativefierOptions } from '../../../shared/src/options/model';
+import { getVersionString } from './rceditGet';
+import { fileExists } from '../fsHelpers';
+type ExecutableInfo = {
+  arch?: string;
+};
+
+function getExecutableBytes(executablePath: string): Uint8Array {
+  return fs.readFileSync(executablePath);
+}
+
+function getExecutableArch(
+  exeBytes: Uint8Array,
+  platform: string,
+): string | undefined {
+  switch (platform) {
+    case 'linux':
+      // https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
+      switch (exeBytes[0x12]) {
+        case 0x03:
+          return 'ia32';
+        case 0x28:
+          return 'armv7l';
+        case 0x3e:
+          return 'x64';
+        case 0xb7:
+          return 'arm64';
+        default:
+          return undefined;
+      }
+    case 'darwin':
+    case 'mas':
+      // https://opensource.apple.com/source/xnu/xnu-2050.18.24/EXTERNAL_HEADERS/mach-o/loader.h
+      switch ((exeBytes[0x04] << 8) + exeBytes[0x05]) {
+        case 0x0700:
+          return 'x64';
+        case 0x0c00:
+          return 'arm64';
+        default:
+          return undefined;
+      }
+    case 'win32':
+      // https://en.wikibooks.org/wiki/X86_Disassembly/Windows_Executable_Files#COFF_Header
+      switch ((exeBytes[0x7d] << 8) + exeBytes[0x7c]) {
+        case 0x014c:
+          return 'ia32';
+        case 0x8664:
+          return 'x64';
+        case 0xaa64:
+          return 'arm64';
+        default:
+          return undefined;
+      }
+    default:
+      return undefined;
+  }
+}
+
+function getExecutableInfo(
+  executablePath: string,
+  platform: string,
+): ExecutableInfo | undefined {
+  if (!fileExists(executablePath)) {
+    return undefined;
+  }
+
+  const exeBytes = getExecutableBytes(executablePath);
+  return {
+    arch: getExecutableArch(exeBytes, platform),
+  };
+}
+
+export function getOptionsFromExecutable(
+  appResourcesDir: string,
+  priorOptions: NativefierOptions,
+): NativefierOptions {
+  const newOptions: NativefierOptions = { ...priorOptions };
+  if (!newOptions.name) {
+    throw new Error(
+      'Can not extract options from executable with no name specified.',
+    );
+  }
+  const name: string = newOptions.name;
+  let executablePath: string | undefined = undefined;
+
+  const appRoot = path.resolve(path.join(appResourcesDir, '..', '..'));
+  const children = fs.readdirSync(appRoot, { withFileTypes: true });
+  const looksLikeMacOS =
+    children.filter((c) => c.name === 'MacOS' && c.isDirectory()).length > 0;
+  const looksLikeWindows =
+    children.filter((c) => c.name.toLowerCase().endsWith('.exe') && c.isFile())
+      .length > 0;
+  const looksLikeLinux =
+    children.filter((c) => c.name.toLowerCase().endsWith('.so') && c.isFile())
+      .length > 0;
+
+  if (looksLikeMacOS) {
+    log.debug('This looks like a MacOS app...');
+    if (newOptions.platform === undefined) {
+      newOptions.platform =
+        children.filter((c) => c.name === 'Library' && c.isDirectory()).length >
+        0
+          ? 'mas'
+          : 'darwin';
+    }
+    executablePath = path.join(
+      appRoot,
+      'MacOS',
+      fs.readdirSync(path.join(appRoot, 'MacOS'))[0],
+    );
+  } else if (looksLikeWindows) {
+    log.debug('This looks like a Windows app...');
+
+    if (newOptions.platform === undefined) {
+      newOptions.platform = 'win32';
+    }
+    executablePath = path.join(
+      appRoot,
+      children.filter(
+        (c) =>
+          c.name.toLowerCase() === `${name.toLowerCase()}.exe` && c.isFile(),
+      )[0].name,
+    );
+
+    if (newOptions.appVersion === undefined) {
+      // https://github.com/electron/electron-packager/blob/f1c159f4c844d807968078ea504fba40ca7d9c73/src/win32.js#L46-L48
+      newOptions.appVersion = getVersionString(
+        executablePath,
+        'ProductVersion',
+      );
+      log.debug(
+        `Extracted app version from executable: ${
+          newOptions.appVersion as string
+        }`,
+      );
+    }
+
+    if (newOptions.buildVersion === undefined) {
+      //https://github.com/electron/electron-packager/blob/f1c159f4c844d807968078ea504fba40ca7d9c73/src/win32.js#L50-L52
+      newOptions.buildVersion = getVersionString(executablePath, 'FileVersion');
+
+      if (newOptions.appVersion == newOptions.buildVersion) {
+        newOptions.buildVersion = undefined;
+      } else {
+        log.debug(
+          `Extracted build version from executable: ${
+            newOptions.buildVersion as string
+          }`,
+        );
+      }
+    }
+
+    if (newOptions.appCopyright === undefined) {
+      // https://github.com/electron/electron-packager/blob/f1c159f4c844d807968078ea504fba40ca7d9c73/src/win32.js#L54-L56
+      newOptions.appCopyright = getVersionString(
+        executablePath,
+        'LegalCopyright',
+      );
+      log.debug(
+        `Extracted app copyright from executable: ${
+          newOptions.appCopyright as string
+        }`,
+      );
+    }
+  } else if (looksLikeLinux) {
+    log.debug('This looks like a Linux app...');
+    if (newOptions.platform === undefined) {
+      newOptions.platform = 'linux';
+    }
+    executablePath = path.join(
+      appRoot,
+      children.filter((c) => c.name == name && c.isFile())[0].name,
+    );
+  }
+
+  if (!executablePath || !newOptions.platform) {
+    throw Error(
+      `Could not find executablePath or platform of app in ${appRoot}`,
+    );
+  }
+
+  log.debug(`Executable path: ${executablePath}`);
+
+  if (newOptions.arch === undefined) {
+    const executableInfo = getExecutableInfo(
+      executablePath,
+      newOptions.platform,
+    );
+    if (!executableInfo) {
+      throw new Error(
+        `Could not get executable info for executable path: ${executablePath}`,
+      );
+    }
+
+    newOptions.arch = executableInfo.arch;
+    log.debug(`Extracted arch from executable: ${newOptions.arch as string}`);
+  }
+  if (newOptions.platform === undefined || newOptions.arch == undefined) {
+    throw Error(`Could not determine platform / arch of app in ${appRoot}`);
+  }
+
+  return newOptions;
+}

src/helpers/upgrade/plistInfoXMLHelpers.ts

@@ -0,0 +1,39 @@
+export function extractBoolean(
+  infoPlistXML: string,
+  plistKey: string,
+): boolean | undefined {
+  const plistValue = extractRaw(infoPlistXML, plistKey);
+
+  return plistValue === undefined
+    ? undefined
+    : plistValue.split('<')[1].split('/>')[0].toLowerCase() === 'true';
+}
+
+export function extractString(
+  infoPlistXML: string,
+  plistKey: string,
+): string | undefined {
+  const plistValue = extractRaw(infoPlistXML, plistKey);
+
+  return plistValue === undefined
+    ? undefined
+    : plistValue.split('<string>')[1].split('</string>')[0];
+}
+
+function extractRaw(
+  infoPlistXML: string,
+  plistKey: string,
+): string | undefined {
+  // This would be easier with xml2js, but let's not add a dependency for something this minor.
+  const fullKey = `\n    <key>${plistKey}</key>`;
+
+  if (infoPlistXML.indexOf(fullKey) === -1) {
+    // This value wasn't set, so we'll stay agnostic to it
+    return undefined;
+  }
+
+  return infoPlistXML
+    .split(fullKey)[1]
+    .split('\n  </dict>')[0] // Get everything between here and the end of the main plist dict
+    .split('\n    <key>')[0]; // Get everything before the next key (if it exists)
+}

src/helpers/upgrade/rceditGet.ts

@@ -0,0 +1,42 @@
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+// A modification of https://github.com/electron/node-rcedit to support the retrieval
+// of information.
+
+export function getVersionString(
+  executablePath: string,
+  versionString: string,
+): string | undefined {
+  let rcedit = path.resolve(
+    __dirname,
+    '..',
+    '..',
+    '..',
+    'node_modules',
+    'rcedit',
+    'bin',
+    process.arch === 'x64' ? 'rcedit-x64.exe' : 'rcedit.exe',
+  );
+  const args = [executablePath, `--get-version-string`, versionString];
+
+  const spawnOptions = {
+    env: { ...process.env },
+  };
+
+  // Use Wine on non-Windows platforms except for WSL, which doesn't need it
+  if (process.platform !== 'win32' && !os.release().endsWith('Microsoft')) {
+    args.unshift(rcedit);
+    rcedit = process.arch === 'x64' ? 'wine64' : 'wine';
+    // Suppress "fixme:" stderr log messages
+    spawnOptions.env.WINEDEBUG = '-all';
+  }
+  try {
+    const child = spawnSync(rcedit, args, spawnOptions);
+    const result = child.output?.toString().split(',wine: ')[0];
+    return result.startsWith(',') ? result.substr(1) : result;
+  } catch {
+    return undefined;
+  }
+}

src/helpers/upgrade/upgrade.ts

@@ -0,0 +1,234 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import * as log from 'loglevel';
+
+import {
+  NativefierOptions,
+  RawOptions,
+} from '../../../shared/src/options/model';
+import { dirExists, fileExists } from '../fsHelpers';
+import { extractBoolean, extractString } from './plistInfoXMLHelpers';
+import { getOptionsFromExecutable } from './executableHelpers';
+import { parseJson } from '../../utils/parseUtils';
+
+export type UpgradeAppInfo = {
+  appResourcesDir: string;
+  appRoot: string;
+  options: NativefierOptions;
+};
+
+function findUpgradeAppResourcesDir(searchDir: string): string | null {
+  searchDir = dirExists(searchDir) ? searchDir : path.dirname(searchDir);
+  log.debug(`Searching for nativfier.json in ${searchDir}`);
+  const children = fs.readdirSync(searchDir, { withFileTypes: true });
+  if (fileExists(path.join(searchDir, 'nativefier.json'))) {
+    // Found 'nativefier.json', so this must be it!
+    return path.resolve(searchDir);
+  }
+  const childDirectories = children.filter((c) => c.isDirectory());
+  for (const childDir of childDirectories) {
+    // We must go deeper!
+    const result = findUpgradeAppResourcesDir(
+      path.join(searchDir, childDir.name, 'nativefier.json'),
+    );
+    if (result !== null) {
+      return path.resolve(result);
+    }
+  }
+
+  // Didn't find it down here
+  return null;
+}
+
+function getAppRoot(
+  appResourcesDir: string,
+  options: NativefierOptions,
+): string {
+  switch (options.platform) {
+    case 'darwin':
+      return path.resolve(path.join(appResourcesDir, '..', '..', '..', '..'));
+    case 'linux':
+    case 'win32':
+      return path.resolve(path.join(appResourcesDir, '..', '..'));
+    default:
+      throw new Error(
+        `Could not find the app root for platform: ${
+          options.platform ?? 'undefined'
+        }`,
+      );
+  }
+}
+
+function getIconPath(appResourcesDir: string): string | undefined {
+  const icnsPath = path.join(appResourcesDir, '..', 'electron.icns');
+  if (fileExists(icnsPath)) {
+    log.debug(`Found icon at: ${icnsPath}`);
+    return path.resolve(icnsPath);
+  }
+  const icoPath = path.join(appResourcesDir, 'icon.ico');
+  if (fileExists(icoPath)) {
+    log.debug(`Found icon at: ${icoPath}`);
+    return path.resolve(icoPath);
+  }
+  const pngPath = path.join(appResourcesDir, 'icon.png');
+  if (fileExists(pngPath)) {
+    log.debug(`Found icon at: ${pngPath}`);
+    return path.resolve(pngPath);
+  }
+
+  log.debug('Could not find icon file.');
+  return undefined;
+}
+
+function getInfoPListOptions(
+  appResourcesDir: string,
+  priorOptions: NativefierOptions,
+): NativefierOptions {
+  if (!fileExists(path.join(appResourcesDir, '..', '..', 'Info.plist'))) {
+    // Not a darwin/mas app, so this is irrelevant
+    return priorOptions;
+  }
+
+  const newOptions = { ...priorOptions };
+
+  const infoPlistXML: string = fs
+    .readFileSync(path.join(appResourcesDir, '..', '..', 'Info.plist'))
+    .toString();
+
+  if (newOptions.appCopyright === undefined) {
+    // https://github.com/electron/electron-packager/blob/0d3f84374e9ab3741b171610735ebc6be3e5e75f/src/mac.js#L230-L232
+    newOptions.appCopyright = extractString(
+      infoPlistXML,
+      'NSHumanReadableCopyright',
+    );
+    log.debug(
+      `Extracted app copyright from Info.plist: ${
+        newOptions.appCopyright as string
+      }`,
+    );
+  }
+
+  if (newOptions.appVersion === undefined) {
+    // https://github.com/electron/electron-packager/blob/0d3f84374e9ab3741b171610735ebc6be3e5e75f/src/mac.js#L214-L216
+    // This could also be the buildVersion, but since they end up in the same place, that SHOULDN'T matter
+    const bundleVersion = extractString(infoPlistXML, 'CFBundleVersion');
+    newOptions.appVersion =
+      bundleVersion === undefined || bundleVersion === '1.0.0' // If it's 1.0.0, that's just the default
+        ? undefined
+        : bundleVersion;
+    (newOptions.darwinDarkModeSupport =
+      newOptions.darwinDarkModeSupport === undefined
+        ? undefined
+        : newOptions.darwinDarkModeSupport === false),
+      log.debug(
+        `Extracted app version from Info.plist: ${
+          newOptions.appVersion as string
+        }`,
+      );
+  }
+
+  if (newOptions.darwinDarkModeSupport === undefined) {
+    // https://github.com/electron/electron-packager/blob/0d3f84374e9ab3741b171610735ebc6be3e5e75f/src/mac.js#L234-L236
+    newOptions.darwinDarkModeSupport = extractBoolean(
+      infoPlistXML,
+      'NSRequiresAquaSystemAppearance',
+    );
+    log.debug(
+      `Extracted Darwin dark mode support from Info.plist: ${
+        newOptions.darwinDarkModeSupport ? 'Yes' : 'No'
+      }`,
+    );
+  }
+
+  return newOptions;
+}
+
+function getInjectPaths(appResourcesDir: string): string[] | undefined {
+  const injectDir = path.join(appResourcesDir, 'inject');
+  if (!dirExists(injectDir)) {
+    return undefined;
+  }
+
+  const injectPaths = fs
+    .readdirSync(injectDir, { withFileTypes: true })
+    .filter(
+      (fd) =>
+        fd.isFile() &&
+        (fd.name.toLowerCase().endsWith('.css') ||
+          fd.name.toLowerCase().endsWith('.js')),
+    )
+    .map((fd) => path.resolve(path.join(injectDir, fd.name)));
+  log.debug(`CSS/JS Inject paths: ${injectPaths.join(', ')}`);
+  return injectPaths;
+}
+
+function isAsar(appResourcesDir: string): boolean {
+  const asar = fileExists(path.join(appResourcesDir, '..', 'electron.asar'));
+  log.debug(`Is this app an ASAR? ${asar ? 'Yes' : 'No'}`);
+  return asar;
+}
+
+export function findUpgradeApp(upgradeFrom: string): UpgradeAppInfo | null {
+  const searchDir = dirExists(upgradeFrom)
+    ? upgradeFrom
+    : path.dirname(upgradeFrom);
+  log.debug(`Looking for old options file in ${searchDir}`);
+  const appResourcesDir = findUpgradeAppResourcesDir(searchDir);
+  if (appResourcesDir === null) {
+    log.debug(`No nativefier.json file found in ${searchDir}`);
+    return null;
+  }
+
+  const nativefierJSONPath = path.join(appResourcesDir, 'nativefier.json');
+
+  log.debug(`Loading ${nativefierJSONPath}`);
+  let options = parseJson<NativefierOptions>(
+    fs.readFileSync(nativefierJSONPath, 'utf8'),
+  );
+
+  if (!options) {
+    throw new Error(
+      `Could not read Nativefier options from ${nativefierJSONPath}`,
+    );
+  }
+
+  options.electronVersion = undefined;
+
+  options = {
+    ...options,
+    ...getOptionsFromExecutable(appResourcesDir, options),
+  };
+
+  const appRoot = getAppRoot(appResourcesDir, options);
+
+  return {
+    appResourcesDir,
+    appRoot,
+    options: {
+      ...options,
+      ...getInfoPListOptions(appResourcesDir, options),
+      asar: options.asar !== undefined ? options.asar : isAsar(appResourcesDir),
+      icon: getIconPath(appResourcesDir),
+      inject: getInjectPaths(appResourcesDir),
+    },
+  };
+}
+
+export function useOldAppOptions(
+  rawOptions: RawOptions,
+  oldApp: UpgradeAppInfo,
+): RawOptions {
+  if (rawOptions.targetUrl !== undefined && dirExists(rawOptions.targetUrl)) {
+    // You got your ouput dir in my targetUrl!
+    rawOptions.out = rawOptions.targetUrl;
+  }
+
+  log.debug('oldApp', oldApp);
+
+  const combinedOptions = { ...rawOptions, ...oldApp.options };
+
+  log.debug('Combined options', combinedOptions);
+
+  return combinedOptions;
+}

src/infer/browsers/inferChromeVersion.ts

@@ -0,0 +1,58 @@
+import axios from 'axios';
+import * as log from 'loglevel';
+import {
+  DEFAULT_CHROME_VERSION,
+  DEFAULT_ELECTRON_VERSION,
+} from '../../constants';
+
+type ElectronRelease = {
+  version: string;
+  date: string;
+  node: string;
+  v8: string;
+  uv: string;
+  zlib: string;
+  openssl: string;
+  modules: string;
+  chrome: string;
+  files: string[];
+};
+
+const ELECTRON_VERSIONS_URL = 'https://releases.electronjs.org/releases.json';
+
+export async function getChromeVersionForElectronVersion(
+  electronVersion: string,
+  url = ELECTRON_VERSIONS_URL,
+): Promise<string> {
+  if (!electronVersion || electronVersion === DEFAULT_ELECTRON_VERSION) {
+    // Exit quickly for the scenario that we already know about
+    return DEFAULT_CHROME_VERSION;
+  }
+
+  try {
+    log.debug('Grabbing electron<->chrome versions file from', url);
+    const response = await axios.get<ElectronRelease[]>(url, { timeout: 5000 });
+    if (response.status !== 200) {
+      throw new Error(`Bad request: Status code ${response.status}`);
+    }
+    const electronReleases: ElectronRelease[] = response.data;
+    const electronVersionToChromeVersion: { [key: string]: string } = {};
+    for (const release of electronReleases) {
+      electronVersionToChromeVersion[release.version] = release.chrome;
+    }
+    if (!(electronVersion in electronVersionToChromeVersion)) {
+      throw new Error(
+        `Electron version '${electronVersion}' not found in retrieved version list!`,
+      );
+    }
+    const chromeVersion = electronVersionToChromeVersion[electronVersion];
+    log.debug(
+      `Associated electron v${electronVersion} to chrome v${chromeVersion}`,
+    );
+    return chromeVersion;
+  } catch (err: unknown) {
+    log.error('getChromeVersionForElectronVersion ERROR', err);
+    log.debug('Falling back to default Chrome version', DEFAULT_CHROME_VERSION);
+    return DEFAULT_CHROME_VERSION;
+  }
+}

src/infer/browsers/inferFirefoxVersion.ts

@@ -0,0 +1,49 @@
+import axios from 'axios';
+import * as log from 'loglevel';
+import { DEFAULT_FIREFOX_VERSION } from '../../constants';
+
+type FirefoxVersions = {
+  FIREFOX_AURORA: string;
+  FIREFOX_DEVEDITION: string;
+  FIREFOX_ESR: string;
+  FIREFOX_ESR_NEXT: string;
+  FIREFOX_NIGHTLY: string;
+  LAST_MERGE_DATE: string;
+  LAST_RELEASE_DATE: string;
+  LAST_SOFTFREEZE_DATE: string;
+  LATEST_FIREFOX_DEVEL_VERSION: string;
+  LATEST_FIREFOX_OLDER_VERSION: string;
+  LATEST_FIREFOX_RELEASED_DEVEL_VERSION: string;
+  LATEST_FIREFOX_VERSION: string;
+  NEXT_MERGE_DATE: string;
+  NEXT_RELEASE_DATE: string;
+  NEXT_SOFTFREEZE_DATE: string;
+};
+
+const FIREFOX_VERSIONS_URL =
+  'https://product-details.mozilla.org/1.0/firefox_versions.json';
+
+export async function getLatestFirefoxVersion(
+  url = FIREFOX_VERSIONS_URL,
+): Promise<string> {
+  try {
+    log.debug('Grabbing Firefox version data from', url);
+    const response = await axios.get<FirefoxVersions>(url, { timeout: 5000 });
+    if (response.status !== 200) {
+      throw new Error(`Bad request: Status code ${response.status}`);
+    }
+    const firefoxVersions: FirefoxVersions = response.data;
+
+    log.debug(
+      `Got latest Firefox version ${firefoxVersions.LATEST_FIREFOX_VERSION}`,
+    );
+    return firefoxVersions.LATEST_FIREFOX_VERSION;
+  } catch (err: unknown) {
+    log.error('getLatestFirefoxVersion ERROR', err);
+    log.debug(
+      'Falling back to default Firefox version',
+      DEFAULT_FIREFOX_VERSION,
+    );
+    return DEFAULT_FIREFOX_VERSION;
+  }
+}

src/infer/browsers/inferSafariVersion.ts

@@ -0,0 +1,77 @@
+import axios from 'axios';
+import * as log from 'loglevel';
+import { DEFAULT_SAFARI_VERSION } from '../../constants';
+
+export type SafariVersion = {
+  majorVersion: number;
+  version: string;
+  webkitVersion: string;
+};
+
+const SAFARI_VERSIONS_HISTORY_URL =
+  'https://en.wikipedia.org/wiki/Safari_version_history';
+
+export async function getLatestSafariVersion(
+  url = SAFARI_VERSIONS_HISTORY_URL,
+): Promise<SafariVersion> {
+  try {
+    log.debug('Grabbing apple version data from', url);
+    const response = await axios.get<string>(url, { timeout: 5000 });
+    if (response.status !== 200) {
+      throw new Error(`Bad request: Status code ${response.status}`);
+    }
+
+    // This would be easier with an HTML parser, but we're not going to include an extra dependency for something that dumb
+    const rawData: string = response.data;
+
+    const majorVersions = [
+      ...rawData.matchAll(
+        /class="mw-headline" id="Safari_[0-9]*">Safari ([0-9]*)</g,
+      ),
+    ].map((match) => match[1]);
+
+    const majorVersion = parseInt(majorVersions[majorVersions.length - 1]);
+
+    const majorVersionTable = rawData
+      .split('>Release history<')[2]
+      .split('<table')
+      .filter((table) => table.includes(`Safari ${majorVersion}.x`))[0];
+
+    const versionRows = majorVersionTable.split('<tbody')[1].split('<tr');
+
+    let version: string | undefined = undefined;
+    let webkitVersion: string | undefined = undefined;
+
+    for (const versionRow of versionRows.reverse()) {
+      const versionMatch = [
+        ...versionRow.matchAll(/>\s*(([0-9]*\.){2}[0-9])\s*</g),
+      ];
+      if (versionMatch.length > 0 && !version) {
+        version = versionMatch[0][1];
+      }
+
+      const webkitVersionMatch = [
+        ...versionRow.matchAll(/>\s*(([0-9]*\.){3,4}[0-9])\s*</g),
+      ];
+      if (webkitVersionMatch.length > 0 && !webkitVersion) {
+        webkitVersion = webkitVersionMatch[0][1];
+      }
+      if (version && webkitVersion) {
+        break;
+      }
+    }
+
+    if (version && webkitVersion) {
+      return {
+        majorVersion,
+        version,
+        webkitVersion,
+      };
+    }
+    return DEFAULT_SAFARI_VERSION;
+  } catch (err: unknown) {
+    log.error('getLatestSafariVersion ERROR', err);
+    log.debug('Falling back to default Safari version', DEFAULT_SAFARI_VERSION);
+    return DEFAULT_SAFARI_VERSION;
+  }
+}

src/infer/inferIcon.ts

@@ -0,0 +1,126 @@
+import * as path from 'path';
+import { writeFile } from 'fs';
+import { promisify } from 'util';
+
+import gitCloud = require('gitcloud');
+import pageIcon from 'page-icon';
+
+import {
+  downloadFile,
+  DownloadResult,
+  getAllowedIconFormats,
+  getTempDir,
+} from '../helpers/helpers';
+import * as log from 'loglevel';
+
+const writeFileAsync = promisify(writeFile);
+
+const GITCLOUD_SPACE_DELIMITER = '-';
+const GITCLOUD_URL = 'https://nativefier.github.io/nativefier-icons/';
+
+type GitCloudIcon = {
+  ext?: string;
+  name?: string;
+  score?: number;
+  url?: string;
+};
+
+function getMaxMatchScore(iconWithScores: GitCloudIcon[]): number {
+  const score = iconWithScores.reduce((maxScore, currentIcon) => {
+    const currentScore = currentIcon.score;
+    if (currentScore && currentScore > maxScore) {
+      return currentScore;
+    }
+    return maxScore;
+  }, 0);
+  log.debug('Max icon match score:', score);
+  return score;
+}
+
+function getMatchingIcons(
+  iconsWithScores: GitCloudIcon[],
+  maxScore: number,
+): GitCloudIcon[] {
+  return iconsWithScores.filter((item) => item.score === maxScore);
+}
+
+function mapIconWithMatchScore(
+  cloudIcons: { name: string; url: string }[],
+  targetUrl: string,
+): GitCloudIcon[] {
+  const normalisedTargetUrl = targetUrl.toLowerCase();
+  return cloudIcons.map((item) => {
+    const itemWords = item.name.split(GITCLOUD_SPACE_DELIMITER);
+    const score: number = itemWords.reduce(
+      (currentScore: number, word: string) => {
+        if (normalisedTargetUrl.includes(word)) {
+          return currentScore + 1;
+        }
+        return currentScore;
+      },
+      0,
+    );
+
+    return { ...item, ext: path.extname(item.url), score };
+  });
+}
+
+async function inferIconFromStore(
+  targetUrl: string,
+  platform: string,
+): Promise<DownloadResult | undefined> {
+  log.debug(`Inferring icon from store for ${targetUrl} on ${platform}`);
+  const allowedFormats = new Set<string | undefined>(
+    getAllowedIconFormats(platform),
+  );
+
+  const cloudIcons = await gitCloud(GITCLOUD_URL);
+  log.debug(`Got ${cloudIcons.length} icons from gitcloud`);
+  const iconWithScores = mapIconWithMatchScore(cloudIcons, targetUrl);
+  const maxScore = getMaxMatchScore(iconWithScores);
+
+  if (maxScore === 0) {
+    log.debug('No relevant icon in store.');
+    return undefined;
+  }
+
+  const iconsMatchingScore = getMatchingIcons(iconWithScores, maxScore);
+  const iconsMatchingExt = iconsMatchingScore.filter((icon) =>
+    allowedFormats.has(icon.ext ?? path.extname(icon.url as string)),
+  );
+  const matchingIcon = iconsMatchingExt[0];
+  const iconUrl = matchingIcon && matchingIcon.url;
+
+  if (!iconUrl) {
+    log.debug('Could not infer icon from store');
+    return undefined;
+  }
+  return downloadFile(iconUrl);
+}
+
+export async function inferIcon(
+  targetUrl: string,
+  platform: string,
+): Promise<string | undefined> {
+  log.debug(`Inferring icon for ${targetUrl} on ${platform}`);
+  const tmpDirPath = getTempDir('iconinfer');
+
+  let icon: { ext: string; data: Buffer } | undefined =
+    await inferIconFromStore(targetUrl, platform);
+  if (!icon) {
+    const ext = platform === 'win32' ? '.ico' : '.png';
+    log.debug(`Trying to extract a ${ext} icon from the page.`);
+    icon = await pageIcon(targetUrl, { ext });
+  }
+  if (!icon) {
+    return undefined;
+  }
+  log.debug(`Got an icon from the page.`);
+
+  const iconPath = path.join(tmpDirPath, `/icon${icon.ext}`);
+  log.debug(
+    `Writing ${(icon.data.length / 1024).toFixed(1)} kb icon to ${iconPath}`,
+  );
+  await writeFileAsync(iconPath, icon.data);
+  return iconPath;
+}

src/infer/inferOs.ts

@@ -0,0 +1,35 @@
+import * as os from 'os';
+
+import * as log from 'loglevel';
+
+// Ideally we'd get this list directly from electron-packager, but it's not
+// possible to convert a literal type to an array of strings in current TypeScript
+export const supportedArchs = ['x64', 'armv7l', 'arm64', 'universal'];
+export const supportedPlatforms = [
+  'darwin',
+  'linux',
+  'mac',
+  'mas',
+  'osx',
+  'win32',
+  'windows',
+];
+
+export function inferPlatform(): string {
+  const platform = os.platform();
+  if (['darwin', 'linux', 'win32'].includes(platform)) {
+    log.debug('Inferred platform', platform);
+    return platform;
+  }
+
+  throw new Error(`Untested platform ${platform} detected`);
+}
+
+export function inferArch(): string {
+  const arch = os.arch();
+  if (!supportedArchs.includes(arch)) {
+    throw new Error(`Incompatible architecture ${arch} detected`);
+  }
+  log.debug('Inferred arch', arch);
+  return arch;
+}

src/infer/inferTitle.test.ts

@@ -0,0 +1,25 @@
+import axios, { AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+
+import { inferTitle } from './inferTitle';
+
+test('it returns the correct title', async () => {
+  const axiosGetMock = jest.spyOn(axios, 'get');
+  const mockedResponse: AxiosResponse<string> = {
+    data: `
+      <HTML>
+        <head>
+          <title>TEST_TITLE</title>
+        </head>
+      </HTML>`,
+    status: 200,
+    statusText: 'OK',
+    headers: {},
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    config: {} as unknown as InternalAxiosRequestConfig<unknown>,
+  };
+  axiosGetMock.mockResolvedValue(mockedResponse);
+  const result = await inferTitle('someurl');
+
+  expect(axiosGetMock).toHaveBeenCalledTimes(1);
+  expect(result).toBe('TEST_TITLE');
+});

src/infer/inferTitle.ts

@@ -0,0 +1,20 @@
+import axios from 'axios';
+import * as log from 'loglevel';
+
+const USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Safari/605.1.15';
+
+export async function inferTitle(url: string): Promise<string> {
+  const { data } = await axios.get<string>(url, {
+    headers: {
+      // Fake user agent for pages like http://messenger.com
+      'User-Agent': USER_AGENT,
+    },
+  });
+  log.debug(`Fetched ${(data.length / 1024).toFixed(1)} kb page at`, url);
+  const inferredTitle =
+    /<\s*title.*?>(?<title>.+?)<\s*\/title\s*?>/i.exec(data)?.groups?.title ??
+    'Webapp';
+  log.debug('Inferred title:', inferredTitle);
+  return inferredTitle;
+}

src/integration-test.ts

@@ -0,0 +1,220 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { DEFAULT_ELECTRON_VERSION } from './constants';
+import { getTempDir } from './helpers/helpers';
+import { getChromeVersionForElectronVersion } from './infer/browsers/inferChromeVersion';
+import { getLatestFirefoxVersion } from './infer/browsers/inferFirefoxVersion';
+import { getLatestSafariVersion } from './infer/browsers/inferSafariVersion';
+import { inferArch } from './infer/inferOs';
+import { buildNativefierApp } from './main';
+import { userAgent } from './options/fields/userAgent';
+import {
+  GlobalShortcut,
+  NativefierOptions,
+  RawOptions,
+} from '../shared/src/options/model';
+import { parseJson } from './utils/parseUtils';
+
+async function checkApp(
+  appRoot: string,
+  inputOptions: RawOptions,
+): Promise<void> {
+  const arch = inputOptions.arch ? inputOptions.arch : inferArch();
+  if (inputOptions.out !== undefined) {
+    expect(
+      path.join(
+        inputOptions.out,
+        `npm-${inputOptions.platform as string}-${arch}`,
+      ),
+    ).toBe(appRoot);
+  }
+
+  let relativeResourcesDir = 'resources';
+
+  if (inputOptions.platform === 'darwin') {
+    relativeResourcesDir = path.join('npm.app', 'Contents', 'Resources');
+  }
+
+  const appPath = path.join(appRoot, relativeResourcesDir, 'app');
+
+  const configPath = path.join(appPath, 'nativefier.json');
+  const nativefierConfig: NativefierOptions | undefined =
+    parseJson<NativefierOptions>(fs.readFileSync(configPath).toString());
+  expect(nativefierConfig).not.toBeUndefined();
+
+  expect(inputOptions.targetUrl).toBe(nativefierConfig?.targetUrl);
+
+  // Test name inferring
+  expect(nativefierConfig?.name).toBe('npm');
+
+  // Test icon writing
+  const iconFile =
+    inputOptions.platform === 'darwin'
+      ? path.join('..', 'electron.icns')
+      : inputOptions.platform === 'linux'
+      ? 'icon.png'
+      : 'icon.ico';
+  const iconPath = path.join(appPath, iconFile);
+  expect(fs.existsSync(iconPath)).toEqual(true);
+  expect(fs.statSync(iconPath).size).toBeGreaterThan(1000);
+
+  // Test arch
+  if (inputOptions.arch !== undefined) {
+    expect(inputOptions.arch).toEqual(nativefierConfig?.arch);
+  } else {
+    expect(os.arch()).toEqual(nativefierConfig?.arch);
+  }
+
+  // Test electron version
+  expect(nativefierConfig?.electronVersionUsed).toBe(
+    inputOptions.electronVersion || DEFAULT_ELECTRON_VERSION,
+  );
+
+  // Test user agent
+  if (inputOptions.userAgent) {
+    const translatedUserAgent = await userAgent({
+      packager: {
+        platform: inputOptions.platform,
+        electronVersion:
+          inputOptions.electronVersion || DEFAULT_ELECTRON_VERSION,
+      },
+      nativefier: { userAgent: inputOptions.userAgent },
+    });
+    inputOptions.userAgent = translatedUserAgent || inputOptions.userAgent;
+  }
+
+  expect(nativefierConfig?.userAgent).toEqual(inputOptions.userAgent);
+
+  // Test lang
+  expect(nativefierConfig?.lang).toEqual(inputOptions.lang);
+
+  // Test global shortcuts
+  if (inputOptions.globalShortcuts) {
+    let shortcutData: GlobalShortcut[] | undefined = [];
+
+    if (typeof inputOptions.globalShortcuts === 'string') {
+      shortcutData = parseJson<GlobalShortcut[]>(
+        fs.readFileSync(inputOptions.globalShortcuts, 'utf8'),
+      );
+    } else {
+      shortcutData = inputOptions.globalShortcuts;
+    }
+
+    expect(nativefierConfig?.globalShortcuts).toStrictEqual(shortcutData);
+  }
+}
+
+describe('Nativefier', () => {
+  jest.setTimeout(300000);
+
+  test.each(['darwin', 'linux'])(
+    'builds a Nativefier app for platform %s',
+    async (platform) => {
+      const tempDirectory = getTempDir('integtest');
+      const options: RawOptions = {
+        lang: 'en-US',
+        out: tempDirectory,
+        overwrite: true,
+        platform,
+        targetUrl: 'https://npmjs.com/',
+      };
+      const appPath = await buildNativefierApp(options);
+      expect(appPath).not.toBeUndefined();
+      await checkApp(appPath, options);
+    },
+  );
+});
+
+function generateShortcutsFile(dir: string): string {
+  const shortcuts = [
+    {
+      key: 'MediaPlayPause',
+      inputEvents: [
+        {
+          type: 'keyDown',
+          keyCode: 'Space',
+        },
+      ],
+    },
+    {
+      key: 'MediaNextTrack',
+      inputEvents: [
+        {
+          type: 'keyDown',
+          keyCode: 'Right',
+        },
+      ],
+    },
+  ];
+
+  const filename = path.join(dir, 'shortcuts.json');
+  fs.writeFileSync(filename, JSON.stringify(shortcuts));
+
+  return filename;
+}
+
+describe('Nativefier upgrade', () => {
+  jest.setTimeout(300000);
+
+  test.each([
+    { platform: 'darwin', arch: 'x64' },
+    { platform: 'linux', arch: 'arm64', userAgent: 'FIREFOX 60' },
+    // Exhaustive integration testing here would be neat, but takes too long.
+    // -> For now, only testing a subset of platforms/archs
+    // { platform: 'win32', arch: 'x64' },
+    // { platform: 'darwin', arch: 'arm64' },
+    // { platform: 'linux', arch: 'x64' },
+    // { platform: 'linux', arch: 'armv7l' },
+  ])(
+    'can upgrade a Nativefier app for platform/arch: %s',
+    async (baseAppOptions) => {
+      const tempDirectory = getTempDir('integtestUpgrade1');
+      const shortcuts = generateShortcutsFile(tempDirectory);
+      const options: RawOptions = {
+        electronVersion: '11.2.3',
+        globalShortcuts: shortcuts,
+        out: tempDirectory,
+        overwrite: true,
+        targetUrl: 'https://npmjs.com/',
+        ...baseAppOptions,
+      };
+      const appPath = await buildNativefierApp(options);
+      expect(appPath).not.toBeUndefined();
+      await checkApp(appPath, options);
+
+      const upgradeOptions: RawOptions = {
+        upgrade: appPath,
+        overwrite: true,
+      };
+
+      const upgradeAppPath = await buildNativefierApp(upgradeOptions);
+      options.electronVersion = DEFAULT_ELECTRON_VERSION;
+      options.userAgent = baseAppOptions.userAgent;
+      expect(upgradeAppPath).not.toBeUndefined();
+      await checkApp(upgradeAppPath, options);
+    },
+  );
+});
+
+describe('Browser version retrieval', () => {
+  test('get chrome version with electron version', async () => {
+    await expect(getChromeVersionForElectronVersion('12.0.0')).resolves.toBe(
+      '89.0.4389.69',
+    );
+  });
+
+  test('get latest firefox version', async () => {
+    const firefoxVersion = await getLatestFirefoxVersion();
+
+    const majorVersion = parseInt(firefoxVersion.split('.')[0]);
+    expect(majorVersion).toBeGreaterThanOrEqual(88);
+  });
+
+  test('get latest safari version', async () => {
+    const safariVersion = await getLatestSafariVersion();
+
+    expect(safariVersion.majorVersion).toBeGreaterThanOrEqual(14);
+  });
+});

src/jestSetupFiles.ts

@@ -0,0 +1,9 @@
+import * as log from 'loglevel';
+
+if (process.env.LOGLEVEL) {
+  log.setLevel(process.env.LOGLEVEL as log.LogLevelDesc);
+} else {
+  log.disableAll();
+}
+
+process.traceDeprecation = true;

src/main.ts

@@ -0,0 +1,21 @@
+import 'source-map-support/register';
+
+import { buildNativefierApp } from './build/buildNativefierApp';
+import { RawOptions } from '../shared/src/options/model';
+
+export { buildNativefierApp };
+
+/**
+ * Only for compatibility with Nativefier <= 7.7.1 !
+ * Use the better, modern async `buildNativefierApp` instead if you can!
+ */
+function buildNativefierAppOldCallbackStyle(
+  options: RawOptions, // eslint-disable-line @typescript-eslint/explicit-module-boundary-types
+  callback: (err?: Error, result?: string) => void,
+): void {
+  buildNativefierApp(options)
+    .then((result) => callback(undefined, result))
+    .catch((err: Error) => callback(err));
+}
+
+export default buildNativefierAppOldCallbackStyle;

src/options/asyncConfig.ts

@@ -0,0 +1,12 @@
+import * as log from 'loglevel';
+
+import { processOptions } from './fields/fields';
+import { AppOptions } from '../../shared/src/options/model';
+
+/**
+ * Takes the options object and infers new values needing async work
+ */
+export async function asyncConfig(options: AppOptions): Promise<AppOptions> {
+  log.debug('\nPerforming async options post-processing.');
+  return await processOptions(options);
+}

src/options/fields/fields.test.ts

@@ -0,0 +1,105 @@
+import { AppOptions } from '../../../shared/src/options/model';
+import { processOptions } from './fields';
+describe('fields', () => {
+  let options: AppOptions;
+
+  beforeEach(() => {
+    options = {
+      nativefier: {
+        accessibilityPrompt: false,
+        alwaysOnTop: false,
+        backgroundColor: undefined,
+        basicAuthPassword: undefined,
+        basicAuthUsername: undefined,
+        blockExternalUrls: false,
+        bookmarksMenu: undefined,
+        bounce: false,
+        browserwindowOptions: undefined,
+        clearCache: false,
+        counter: false,
+        crashReporter: undefined,
+        disableContextMenu: false,
+        disableDevTools: false,
+        disableGpu: false,
+        disableOldBuildWarning: false,
+        diskCacheSize: undefined,
+        enableEs3Apis: false,
+        fastQuit: true,
+        fileDownloadOptions: undefined,
+        flashPluginDir: undefined,
+        fullScreen: false,
+        globalShortcuts: undefined,
+        height: undefined,
+        hideWindowFrame: false,
+        ignoreCertificate: false,
+        ignoreGpuBlacklist: false,
+        inject: [],
+        insecure: false,
+        internalUrls: undefined,
+        maximize: false,
+        maxHeight: undefined,
+        minWidth: undefined,
+        minHeight: undefined,
+        maxWidth: undefined,
+        nativefierVersion: '1.0.0',
+        processEnvs: undefined,
+        proxyRules: undefined,
+        showMenuBar: false,
+        singleInstance: false,
+        strictInternalUrls: false,
+        titleBarStyle: undefined,
+        tray: 'false',
+        userAgent: undefined,
+        userAgentHonest: false,
+        verbose: false,
+        versionString: '1.0.0',
+        width: undefined,
+        widevine: false,
+        x: undefined,
+        y: undefined,
+        zoom: 1,
+      },
+      packager: {
+        arch: process.arch,
+        dir: '',
+        platform: process.platform,
+        portable: false,
+        targetUrl: '',
+        upgrade: false,
+      },
+    };
+  });
+
+  test('fully-defined async options are returned as-is', async () => {
+    options.packager.icon = '/my/icon.png';
+    options.packager.name = 'my beautiful app ';
+    options.packager.platform = 'darwin';
+    options.nativefier.userAgent = 'random user agent';
+    await processOptions(options);
+
+    expect(options.packager.icon).toEqual('/my/icon.png');
+    expect(options.packager.name).toEqual('my beautiful app');
+    expect(options.nativefier.userAgent).toEqual('random user agent');
+  });
+
+  test('name has spaces stripped in linux', async () => {
+    options.packager.name = 'my beautiful app ';
+    options.packager.platform = 'linux';
+    await processOptions(options);
+
+    expect(options.packager.name).toEqual('mybeautifulapp');
+  });
+
+  test('user agent is ignored if not provided', async () => {
+    await processOptions(options);
+
+    expect(options.nativefier.userAgent).toBeUndefined();
+  });
+
+  test('user agent short code is populated', async () => {
+    options.nativefier.userAgent = 'edge';
+    await processOptions(options);
+
+    expect(options.nativefier.userAgent).not.toBe('edge');
+  });
+});

src/options/fields/fields.ts

@@ -0,0 +1,42 @@
+import { icon } from './icon';
+import { userAgent } from './userAgent';
+import { AppOptions } from '../../../shared/src/options/model';
+import { name } from './name';
+
+type OptionPostprocessor = {
+  namespace: 'nativefier' | 'packager';
+  option: 'icon' | 'name' | 'userAgent';
+  processor: (options: AppOptions) => Promise<string | undefined>;
+};
+
+const OPTION_POSTPROCESSORS: OptionPostprocessor[] = [
+  { namespace: 'nativefier', option: 'userAgent', processor: userAgent },
+  { namespace: 'packager', option: 'icon', processor: icon },
+  { namespace: 'packager', option: 'name', processor: name },
+];
+
+export async function processOptions(options: AppOptions): Promise<AppOptions> {
+  const processedOptions = await Promise.all(
+    OPTION_POSTPROCESSORS.map(async ({ namespace, option, processor }) => {
+      const result = await processor(options);
+      return {
+        namespace,
+        option,
+        result,
+      };
+    }),
+  );
+
+  for (const { namespace, option, result } of processedOptions) {
+    if (
+      result &&
+      namespace in options &&
+      options[namespace] &&
+      option in options[namespace]
+    ) {
+      // @ts-expect-error We're fiddling with objects at the string key level, which TS doesn't support well.
+      options[namespace][option] = result;
+    }
+  }
+  return options;
+}

src/options/fields/icon.test.ts

@@ -0,0 +1,60 @@
+import * as log from 'loglevel';
+
+import { icon } from './icon';
+import { inferIcon } from '../../infer/inferIcon';
+
+jest.mock('./../../infer/inferIcon');
+jest.mock('loglevel');
+
+const mockedResult = 'icon path';
+const ICON_PARAMS_PROVIDED = {
+  packager: {
+    icon: './icon.png',
+    targetUrl: 'https://google.com',
+    platform: 'mac',
+  },
+};
+const ICON_PARAMS_NEEDS_INFER = {
+  packager: {
+    targetUrl: 'https://google.com',
+    platform: 'mac',
+  },
+};
+
+describe('when the icon parameter is passed', () => {
+  test('it should return the icon parameter', async () => {
+    expect(inferIcon).toHaveBeenCalledTimes(0);
+    await expect(icon(ICON_PARAMS_PROVIDED)).resolves.toBeUndefined();
+  });
+});
+
+describe('when the icon parameter is not passed', () => {
+  test('it should call inferIcon', async () => {
+    (inferIcon as jest.Mock).mockImplementationOnce(() =>
+      Promise.resolve(mockedResult),
+    );
+    const result = await icon(ICON_PARAMS_NEEDS_INFER);
+
+    expect(result).toBe(mockedResult);
+    expect(inferIcon).toHaveBeenCalledWith(
+      ICON_PARAMS_NEEDS_INFER.packager.targetUrl,
+      ICON_PARAMS_NEEDS_INFER.packager.platform,
+    );
+  });
+
+  describe('when inferIcon resolves with an error', () => {
+    test('it should handle the error', async () => {
+      (inferIcon as jest.Mock).mockImplementationOnce(() =>
+        Promise.reject(new Error('some error')),
+      );
+      const result = await icon(ICON_PARAMS_NEEDS_INFER);
+
+      expect(result).toBeUndefined();
+      expect(inferIcon).toHaveBeenCalledWith(
+        ICON_PARAMS_NEEDS_INFER.packager.targetUrl,
+        ICON_PARAMS_NEEDS_INFER.packager.platform,
+      );
+      expect(log.warn).toHaveBeenCalledTimes(1); // eslint-disable-line @typescript-eslint/unbound-method
+    });
+  });
+});

src/options/fields/icon.ts

@@ -0,0 +1,38 @@
+import * as log from 'loglevel';
+
+import { inferIcon } from '../../infer/inferIcon';
+
+type IconParams = {
+  packager: {
+    icon?: string;
+    targetUrl: string;
+    platform?: string;
+  };
+};
+
+export async function icon(options: IconParams): Promise<string | undefined> {
+  if (options.packager.icon) {
+    log.debug('Got icon from options. Using it, no inferring needed');
+    return undefined;
+  }
+
+  if (!options.packager.platform) {
+    log.error('No platform specified. Icon can not be inferrerd.');
+    return undefined;
+  }
+
+  try {
+    return await inferIcon(
+      options.packager.targetUrl,
+      options.packager.platform,
+    );
+  } catch (err: unknown) {
+    // eslint-disable-next-line
+    const errorUrl: string = (err as any)?.config?.url;
+    log.warn(
+      'Cannot automatically retrieve the app icon:',
+      errorUrl ? `${(err as Error).message} on ${errorUrl}` : err,
+    );
+    return undefined;
+  }
+}

src/options/fields/name.test.ts

@@ -0,0 +1,110 @@
+import * as log from 'loglevel';
+
+import { name } from './name';
+import { DEFAULT_APP_NAME } from '../../constants';
+import { inferTitle } from '../../infer/inferTitle';
+import { sanitizeFilename } from '../../utils/sanitizeFilename';
+
+jest.mock('./../../infer/inferTitle');
+jest.mock('./../../utils/sanitizeFilename');
+jest.mock('loglevel');
+
+const inferTitleMockedResult = 'mock name';
+const NAME_PARAMS_PROVIDED = {
+  packager: {
+    name: 'appname',
+    targetUrl: 'https://google.com',
+    platform: 'linux',
+  },
+};
+const NAME_PARAMS_NEEDS_INFER = {
+  packager: {
+    targetUrl: 'https://google.com',
+    platform: 'mac',
+  },
+};
+beforeAll(() => {
+  (sanitizeFilename as jest.Mock).mockImplementation(
+    (_, filename: string) => filename,
+  );
+});
+
+describe('well formed name parameters', () => {
+  test('it should not call inferTitle', async () => {
+    const result = await name(NAME_PARAMS_PROVIDED);
+
+    expect(inferTitle).toHaveBeenCalledTimes(0);
+    expect(result).toBe(NAME_PARAMS_PROVIDED.packager.name);
+  });
+
+  test('it should call sanitize filename', async () => {
+    const result = await name(NAME_PARAMS_PROVIDED);
+
+    expect(sanitizeFilename).toHaveBeenCalledWith(
+      NAME_PARAMS_PROVIDED.packager.platform,
+      result,
+    );
+  });
+});
+
+describe('bad name parameters', () => {
+  beforeEach(() => {
+    (inferTitle as jest.Mock).mockResolvedValue(inferTitleMockedResult);
+  });
+
+  const params = { packager: { targetUrl: 'some url', platform: 'whatever' } };
+  test('it should call inferTitle when the name is undefined', async () => {
+    await name(params);
+    expect(inferTitle).toHaveBeenCalledWith(params.packager.targetUrl);
+  });
+
+  test('it should call inferTitle when the name is an empty string', async () => {
+    const testParams = {
+      ...params,
+      name: '',
+    };
+
+    await name(testParams);
+    expect(inferTitle).toHaveBeenCalledWith(params.packager.targetUrl);
+  });
+
+  test('it should call sanitize filename', async () => {
+    const result = await name(params);
+    expect(sanitizeFilename).toHaveBeenCalledWith(
+      params.packager.platform,
+      result,
+    );
+  });
+});
+
+describe('handling inferTitle results', () => {
+  test('it should return the result from inferTitle', async () => {
+    const result = await name(NAME_PARAMS_NEEDS_INFER);
+
+    expect(result).toEqual(inferTitleMockedResult);
+    expect(inferTitle).toHaveBeenCalledWith(
+      NAME_PARAMS_NEEDS_INFER.packager.targetUrl,
+    );
+  });
+
+  test('it should return the default app name when the returned pageTitle is falsey', async () => {
+    (inferTitle as jest.Mock).mockResolvedValue(null);
+    const result = await name(NAME_PARAMS_NEEDS_INFER);
+
+    expect(result).toEqual(DEFAULT_APP_NAME);
+    expect(inferTitle).toHaveBeenCalledWith(
+      NAME_PARAMS_NEEDS_INFER.packager.targetUrl,
+    );
+  });
+
+  test('it should return the default app name when inferTitle rejects', async () => {
+    (inferTitle as jest.Mock).mockRejectedValue('some error');
+    const result = await name(NAME_PARAMS_NEEDS_INFER);
+
+    expect(result).toEqual(DEFAULT_APP_NAME);
+    expect(inferTitle).toHaveBeenCalledWith(
+      NAME_PARAMS_NEEDS_INFER.packager.targetUrl,
+    );
+    expect(log.warn).toHaveBeenCalledTimes(1); // eslint-disable-line @typescript-eslint/unbound-method
+  });
+});

src/options/fields/name.ts

@@ -0,0 +1,36 @@
+import * as log from 'loglevel';
+
+import { sanitizeFilename } from '../../utils/sanitizeFilename';
+import { inferTitle } from '../../infer/inferTitle';
+import { DEFAULT_APP_NAME } from '../../constants';
+
+type NameParams = {
+  packager: {
+    name?: string;
+    platform?: string;
+    targetUrl: string;
+  };
+};
+
+async function tryToInferName(targetUrl: string): Promise<string> {
+  try {
+    log.debug('Inferring name for', targetUrl);
+    const pageTitle = await inferTitle(targetUrl);
+    return pageTitle || DEFAULT_APP_NAME;
+  } catch (err: unknown) {
+    log.warn(
+      `Unable to automatically determine app name, falling back to '${DEFAULT_APP_NAME}'.`,
+      err,
+    );
+    return DEFAULT_APP_NAME;
+  }
+}
+
+export async function name(options: NameParams): Promise<string> {
+  let name: string | undefined = options.packager.name;
+  if (!name) {
+    name = await tryToInferName(options.packager.targetUrl);
+  }
+
+  return sanitizeFilename(options.packager.platform, name);
+}

src/options/fields/userAgent.test.ts

@@ -0,0 +1,90 @@
+import { getChromeVersionForElectronVersion } from '../../infer/browsers/inferChromeVersion';
+import { getLatestFirefoxVersion } from '../../infer/browsers/inferFirefoxVersion';
+import { getLatestSafariVersion } from '../../infer/browsers/inferSafariVersion';
+import { userAgent } from './userAgent';
+
+jest.mock('./../../infer/browsers/inferChromeVersion');
+jest.mock('./../../infer/browsers/inferFirefoxVersion');
+jest.mock('./../../infer/browsers/inferSafariVersion');
+
+test('when a userAgent parameter is passed', async () => {
+  const params = {
+    packager: {},
+    nativefier: { userAgent: 'valid user agent' },
+  };
+  await expect(userAgent(params)).resolves.toBeUndefined();
+});
+
+test('no userAgent parameter is passed', async () => {
+  const params = {
+    packager: { platform: 'mac' },
+    nativefier: {},
+  };
+  await expect(userAgent(params)).resolves.toBeUndefined();
+});
+
+test('edge userAgent parameter is passed', async () => {
+  (getChromeVersionForElectronVersion as jest.Mock).mockImplementationOnce(() =>
+    Promise.resolve('99.0.0'),
+  );
+  const params = {
+    packager: { platform: 'darwin' },
+    nativefier: { userAgent: 'edge' },
+  };
+
+  const parsedUserAgent = await userAgent(params);
+
+  expect(parsedUserAgent).not.toBe(params.nativefier.userAgent);
+  expect(parsedUserAgent).toContain('Edg/99.0.0');
+});
+
+test('firefox userAgent parameter is passed', async () => {
+  (getLatestFirefoxVersion as jest.Mock).mockImplementationOnce(() =>
+    Promise.resolve('100.0.0'),
+  );
+  const params = {
+    packager: { platform: 'win32' },
+    nativefier: { userAgent: 'firefox' },
+  };
+
+  const parsedUserAgent = await userAgent(params);
+
+  expect(parsedUserAgent).not.toBe(params.nativefier.userAgent);
+  expect(parsedUserAgent).toContain('Firefox/100.0.0');
+});
+
+test('safari userAgent parameter is passed', async () => {
+  (getLatestSafariVersion as jest.Mock).mockImplementationOnce(() =>
+    Promise.resolve({
+      majorVersion: 101,
+      version: '101.0.0',
+      webkitVersion: '600.0.0.0',
+    }),
+  );
+  const params = {
+    packager: { platform: 'linux' },
+    nativefier: { userAgent: 'safari' },
+  };
+
+  const parsedUserAgent = await userAgent(params);
+
+  expect(parsedUserAgent).not.toBe(params.nativefier.userAgent);
+  expect(parsedUserAgent).toContain('Version/101.0.0 Safari');
+});
+
+test('short userAgent parameter is passed with an electronVersion', async () => {
+  (getChromeVersionForElectronVersion as jest.Mock).mockImplementationOnce(() =>
+    Promise.resolve('102.0.0'),
+  );
+
+  const params = {
+    packager: { electronVersion: '16.0.0', platform: 'darwin' },
+    nativefier: { userAgent: 'edge' },
+  };
+
+  const parsedUserAgent = await userAgent(params);
+
+  expect(parsedUserAgent).not.toBe(params.nativefier.userAgent);
+  expect(parsedUserAgent).toContain('102.0.0');
+  expect(getChromeVersionForElectronVersion).toHaveBeenCalledWith('16.0.0');
+});

src/options/fields/userAgent.ts

@@ -0,0 +1,93 @@
+import * as log from 'loglevel';
+import { DEFAULT_ELECTRON_VERSION } from '../../constants';
+
+import { getChromeVersionForElectronVersion } from '../../infer/browsers/inferChromeVersion';
+import { getLatestFirefoxVersion } from '../../infer/browsers/inferFirefoxVersion';
+import { getLatestSafariVersion } from '../../infer/browsers/inferSafariVersion';
+import { normalizePlatform } from '../optionsMain';
+
+export type UserAgentOpts = {
+  packager: {
+    electronVersion?: string;
+    platform?: string;
+  };
+  nativefier: {
+    userAgent?: string;
+  };
+};
+
+const USER_AGENT_PLATFORM_MAPS: Record<string, string> = {
+  darwin: 'Macintosh; Intel Mac OS X 10_15_7',
+  linux: 'X11; Linux x86_64',
+  win32: 'Windows NT 10.0; Win64; x64',
+};
+
+const USER_AGENT_SHORT_CODE_MAPS: Record<
+  string,
+  (platform: string, electronVersion: string) => Promise<string>
+> = {
+  edge: edgeUserAgent,
+  firefox: firefoxUserAgent,
+  safari: safariUserAgent,
+};
+
+export async function userAgent(
+  options: UserAgentOpts,
+): Promise<string | undefined> {
+  if (!options.nativefier.userAgent) {
+    // No user agent got passed. Let's handle it with the app.userAgentFallback
+    return undefined;
+  }
+
+  if (
+    !Object.keys(USER_AGENT_SHORT_CODE_MAPS).includes(
+      options.nativefier.userAgent.toLowerCase(),
+    )
+  ) {
+    // Real user agent got passed. No need to translate it.
+    log.debug(
+      `${options.nativefier.userAgent.toLowerCase()} not found in`,
+      Object.keys(USER_AGENT_SHORT_CODE_MAPS),
+    );
+    return undefined;
+  }
+
+  options.packager.platform = normalizePlatform(options.packager.platform);
+
+  const userAgentPlatform: string =
+    USER_AGENT_PLATFORM_MAPS[
+      options.packager.platform === 'mas' ? 'darwin' : options.packager.platform
+    ];
+
+  const mapFunction = USER_AGENT_SHORT_CODE_MAPS[options.nativefier.userAgent];
+
+  return await mapFunction(
+    userAgentPlatform,
+    options.packager.electronVersion ?? DEFAULT_ELECTRON_VERSION,
+  );
+}
+
+async function edgeUserAgent(
+  platform: string,
+  electronVersion: string,
+): Promise<string> {
+  const chromeVersion =
+    await getChromeVersionForElectronVersion(electronVersion);
+
+  return `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36 Edg/${chromeVersion}`;
+}
+
+async function firefoxUserAgent(platform: string): Promise<string> {
+  const firefoxVersion = await getLatestFirefoxVersion();
+
+  return `Mozilla/5.0 (${platform}; rv:${firefoxVersion}) Gecko/20100101 Firefox/${firefoxVersion}`.replace(
+    '10_15_7',
+    '10.15',
+  );
+}
+
+async function safariUserAgent(platform: string): Promise<string> {
+  const safariVersion = await getLatestSafariVersion();
+
+  return `Mozilla/5.0 (${platform}) AppleWebKit/${safariVersion.webkitVersion} (KHTML, like Gecko) Version/${safariVersion.version} Safari/${safariVersion.webkitVersion}`;
+}