win: categorize and rename network security #131

This commit restructures the categorization of network security-related
scripts to improve clarity and align with user expectations. It involves
renaming and reorganizing categories to more accurately reflect their
functions beyond just IIS configurations.

This reorganization helps users find and utilize network security
scripts more efficiently and ensures that the categorization accurately
reflects the broader application of the scripts beyond server
configurations.

Changes:

- Merge network security enhancements under a single category.
- Rename categories for simplicity and increased technical accuracy.
- Flatten nested categories to streamline navigation and enhance
  clarity.
- Update documentation to match the new category structures.
- Revise script recommendations to encourage broader use.
- Fix revert codes of some related scripts to reflect default OS
  settings.

.github/actions/setup-node/action.yml

@@ -6,4 +6,4 @@ runs:
       uses: actions/setup-node@v4
       with:
         node-version: 20.x
-        check-latest: true
+        # check-latest: true # Newest versions can potentially have undiscovered bugs or regressions

.github/workflows/checks.quality.yaml

@@ -1,4 +1,4 @@
-name: quality-checks
+name: checks.quality
 
 on: [ push, pull_request ]
 
@@ -28,3 +28,49 @@ jobs:
       -
         name: Lint
         run: ${{ matrix.lint-command }}
+
+  todo-check:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Scan latest commit for TODO comments
+        shell: bash
+        run: |-
+          readonly todo_comment_search_pattern='TODO'':' # Define search pattern in parts to prevent IDE from flagging this script line as a TODO item
+          if git grep "$todo_comment_search_pattern" HEAD; then
+            echo 'TODO comments found in the latest commit.'
+            exit 1
+          else
+            echo 'No TODO comments found in the latest commit.'
+            exit 0
+          fi
+
+  pylint:
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      matrix:
+        os: [ macos, ubuntu, windows ]
+      fail-fast: false # Still interested to see results from other combinations
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Setup node
+        uses: ./.github/actions/setup-node
+      -
+        name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      -
+        name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pylint
+      -
+        name: Analyzing the code with pylint
+        run: npm run lint:pylint

.github/workflows/checks.scripts.yaml

@@ -15,6 +15,10 @@ jobs:
       -
         name: Checkout
         uses: actions/checkout@v4
+      -
+        name: Install ImageMagick on macOS
+        if: matrix.os == 'macos'
+        run: brew install imagemagick
       -
         name: Setup node
         uses: ./.github/actions/setup-node
@@ -53,3 +57,31 @@ jobs:
       -
         name: Run install-deps
         run: ${{ matrix.install-command }}
+
+  configure-vscode:
+    runs-on: ${{ matrix.os.name }}-latest
+    strategy:
+      matrix:
+        os:
+          - name: macos
+            install-vscode-command: brew install --cask visual-studio-code
+          - name: ubuntu
+            install-vscode-command: sudo snap install code --classic
+          - name: windows
+            install-vscode-command: choco install vscode
+      fail-fast: false # Still interested to see results from other combinations
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      -
+        name: Install VSCode
+        run: ${{ matrix.os.install-vscode-command }}
+      -
+        name: Configure VSCode
+        run: python3 ./scripts/configure_vscode.py

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.13.2 (2024-04-15)
+
+* Update documentation for `logo-update.js` script | [4a9b430](https://github.com/undergroundwires/privacy.sexy/commit/4a9b430702bc6082426b50ecc3a06362b5720796)
+* win: improve and document removing Phone apps #279 | [8924337](https://github.com/undergroundwires/privacy.sexy/commit/89243371faa5d6aef5fce52b0d54a442143cdd39)
+* Fix bottom gap in card expansion panel | [79183d6](https://github.com/undergroundwires/privacy.sexy/commit/79183d64173e588d88bf074d5b50a52a71c2d885)
+* ci/cd: Fix macOS Docker build reliability issues | [8a5592f](https://github.com/undergroundwires/privacy.sexy/commit/8a5592f92be4366a806afc9eee9135696a1dd993)
+* ci/cd: fix IPv6 timeouts with `force-ipv4` action | [52fadcd](https://github.com/undergroundwires/privacy.sexy/commit/52fadcd6177ed06216be9c67dad57192ae02a4f9)
+* ci/cd: bump Node.js environment to 20.x | [59decd1](https://github.com/undergroundwires/privacy.sexy/commit/59decd17e273bada1493eaa855c43cbabf90308f)
+* ci/cd: trigger URL checks more, and limit amount | [4fb6302](https://github.com/undergroundwires/privacy.sexy/commit/4fb6302c67f2a3fedff419e8c22872593cf800ef)
+* Fix overflow in tree node content on small screens | [557cea3](https://github.com/undergroundwires/privacy.sexy/commit/557cea3f4866dc33236874f5fe4d2d69ee963dae)
+* Fix horizontal layout shift after script selection | [bc7e1fa](https://github.com/undergroundwires/privacy.sexy/commit/bc7e1faa1c3f2b61bf2046fdd6d6a4141b484662)
+* Fix card header expansion glitch on card collapse | [5d940b5](https://github.com/undergroundwires/privacy.sexy/commit/5d940b57ef2a4c219932cd15201401f8550cfb41)
+* Ignore `ResizeObserver` errors in Cypress tests | [4472c28](https://github.com/undergroundwires/privacy.sexy/commit/4472c2852e4b87083bda7979471ab9f377d17a01)
+* win: improve and document secret key scripts | [49f22f0](https://github.com/undergroundwires/privacy.sexy/commit/49f22f048f39e7388633c488b5fe59101b831984)
+* Fix card arrow not being animated in sync | [7b546c5](https://github.com/undergroundwires/privacy.sexy/commit/7b546c567c4683a37fe94595362f4c2bf92ffd59)
+* win: improve Windows feature disablement scripts | [b68711e](https://github.com/undergroundwires/privacy.sexy/commit/b68711ef88982c0ee2b1d41b4452e899821adc64)
+* Fix top script menu overflow on small screens | [b7a20d9](https://github.com/undergroundwires/privacy.sexy/commit/b7a20d9d41ea8bcefdd553b87641f3c22b4cde97)
+* win: fix Visual Studio remote analysis script #327 | [4142d08](https://github.com/undergroundwires/privacy.sexy/commit/4142d084f64a3b540487ff68b28032977d12006d)
+* win: improve firewall docs /w `winget` impact #142 | [ffd647d](https://github.com/undergroundwires/privacy.sexy/commit/ffd647d1529375474b81900cc7bee4c32fbf861f)
+* Centralize and use global spacing variables | [ae17200](https://github.com/undergroundwires/privacy.sexy/commit/ae172000a64416e5a3e2b2e32b7846f039f445f0)
+* win: improve service revert and docs | [b87b7aa](https://github.com/undergroundwires/privacy.sexy/commit/b87b7aac7d118a23a0d1bfb881e385347de4adb7)
+* Bump dependencies to latest, hold ESLint | [f3571ab](https://github.com/undergroundwires/privacy.sexy/commit/f3571abeafdbe1e6d152958fab26de91a9c08bc3)
+* Fix inability to tap outside modal on mobile | [cb144ae](https://github.com/undergroundwires/privacy.sexy/commit/cb144ae47273deeb7058d4b1380e480ebccdaf81)
+
+[compare](https://github.com/undergroundwires/privacy.sexy/compare/0.13.1...0.13.2)
+
 ## 0.13.1 (2024-03-22)
 
 * ci/cd: Fix cross-platform git command compability | [255c51c](https://github.com/undergroundwires/privacy.sexy/commit/255c51c8a0524d3ea8a3b16ffc1b178650525010)

README.md

@@ -60,8 +60,8 @@
   <br />
   <a href="https://github.com/undergroundwires/privacy.sexy/actions/workflows/checks.quality.yaml" target="_blank" rel="noopener noreferrer">
     <img
-      alt="Quality checks status"
+      alt="Status of quality checks"
-      src="https://github.com/undergroundwires/privacy.sexy/workflows/quality-checks/badge.svg"
+      src="https://github.com/undergroundwires/privacy.sexy/workflows/checks.quality/badge.svg"
     />
   </a>
   <a href="https://github.com/undergroundwires/privacy.sexy/actions/workflows/checks.build.yaml" target="_blank" rel="noopener noreferrer">
@@ -122,9 +122,12 @@
 ## Get started
 
 - 🌍️ **Online**: [https://privacy.sexy](https://privacy.sexy).
-- 🖥️ **Offline**: Download directly for: [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.1/privacy.sexy-Setup-0.13.1.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.1/privacy.sexy-0.13.1.dmg), [Linux](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.1/privacy.sexy-0.13.1.AppImage). For more options, see [here](#additional-install-options).
+- 🖥️ **Offline**: Download directly for: [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.2/privacy.sexy-Setup-0.13.2.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.2/privacy.sexy-0.13.2.dmg), [Linux](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.2/privacy.sexy-0.13.2.AppImage). For more options, see [here](#additional-install-options).
 
-For a detailed comparison of features between the desktop and web versions of privacy.sexy, see [Desktop vs. Web Features](./docs/desktop-vs-web-features.md).
+See also:
+
+- [Desktop vs. Web Features](./docs/desktop/desktop-vs-web-features.md): Differences and unique aspects of desktop and web versions.
+- [System Requirements](./docs/desktop/system-requirements.md): Hardware and software requirements for the desktop version.
 
 💡 Regularly applying your configuration with privacy.sexy is recommended, especially after each new release and major operating system updates. Each version updates scripts to enhance stability, privacy, and security.
 

SECURITY.md

@@ -43,10 +43,17 @@ privacy.sexy adopts a defense in depth strategy to protect users on multiple lay
   elevation of privileges for system modifications with explicit user consent and logs every action taken with high privileges. This
   approach actively minimizes potential security risks by limiting privileged operations and aligning with the principle of least privilege.
 - **Secure Script Execution/Storage:**
-  Before executing any script, the desktop application stores a copy to allow antivirus software to perform scans. This safeguards against
+  - **Antivirus scans:**
-  any unwanted modifications. Furthermore, the application incorporates integrity checks for tamper protection. If the script file differs from
+    Before executing any script, the desktop application stores a copy to allow antivirus software to perform scans.
-  the user's selected script, the application will not execute or save the script, ensuring the processing of authentic scripts.
+    This step allows confirming that the scripts are secure and safe to use.
-  Recognizing that some users prefer not to keep these records, privacy.sexy provides specialized scripts for deletion of these scripts.
+  - **Tamper protection:**
+    The application incorporates integrity checks for tamper protection.
+    If the script file differs from the user's selected script, the application will not execute or save the script, ensuring the processing
+    of authentic scripts.
+    This safeguards against any unwanted modifications.
+  - **Clean-up:**
+    Recognizing that some users prefer not to keep these records, privacy.sexy provides specialized scripts for deletion of these scripts.
+    This allows users to maintain their privacy by removing traces of their usage patterns or script preferences.
 
 ### Update Security and Integrity
 

build/README.md

@@ -1,5 +0,0 @@
-# build
-
-This folder contains files that are used by Electron to serve the desktop version.
-
-Icons are created from the main logo file and should not be changed manually, see [related documentation](./../img/README.md).

docs/desktop/desktop-vs-web-features.md

@@ -1,6 +1,6 @@
 # Desktop vs. Web Features
 
-This table highlights differences between the desktop and web versions of `privacy.sexy`.
+This table outlines the differences between the desktop and web versions of `privacy.sexy`.
 
 | Feature | Desktop | Web |
 | ------- | ------- | --- |
@@ -8,10 +8,8 @@ This table highlights differences between the desktop and web versions of `priva
 | [Offline usage](#offline-usage) | 🟢 Available | 🟡 Partially available |
 | [Auto-updates](#auto-updates) | 🟢 Available | 🟢 Available |
 | [Logging](#logging) | 🟢 Available | 🔴 Not available |
-| [Script execution](#script-execution) | 🟢 Available | 🔴 Not available |
-| [Error handling](#error-handling) | 🟢 Advanced | 🟡 Limited |
-| [Native dialogs](#native-dialogs) | 🟢 Available | 🔴 Not available |
 | [Secure script execution/storage](#secure-script-executionstorage) | 🟢 Available | 🔴 Not available |
+| [Native dialogs](#native-dialogs) | 🟢 Available | 🔴 Not available |
 
 ## Feature descriptions
 
@@ -30,11 +28,11 @@ Desktop version inherently allows offline usage.
 
 ### Auto-updates
 
-Both the desktop and web versions of privacy.sexy provide timely access to the latest features and security improvements. The updates are automatically deployed from source code, reflecting the latest changes for enhanced security and reliability. For more details, see [CI/CD documentation](./ci-cd.md).
+Both the desktop and web versions of privacy.sexy provide timely access to the latest features and security improvements. The updates are automatically deployed from source code, reflecting the latest changes for enhanced security and reliability. For more details, see [CI/CD documentation](./../ci-cd.md).
 
 The desktop version ensures secure delivery through cryptographic signatures and version checks.
 
-[Security is a top priority](./../SECURITY.md#update-security-and-integrity) at privacy.sexy.
+[Security is a top priority](./../../SECURITY.md#update-security-and-integrity) at privacy.sexy.
 
 > **Note for macOS users:** On macOS, the desktop version's auto-update process involves manual steps due to Apple's code signing costs.
 > Users get notified about updates but might need to complete the installation manually.
@@ -53,7 +51,7 @@ Log file locations vary by operating system:
 
 > 💡 privacy.sexy provides scripts to securely erase these logs.
 
-### Script execution
+### Secure script execution/storage
 
 The desktop version of privacy.sexy enables direct script execution, providing a seamless and integrated experience.
 This direct execution capability isn't available in the web version due to inherent browser restrictions.
@@ -69,31 +67,27 @@ These locations vary based on the operating system:
 
 > 💡 privacy.sexy provides scripts to securely erase your script execution history.
 
-### Error handling
+**Script antivirus scans:**
 
-The desktop version of privacy.sexy features advanced error handling capabilities.
+To enhance system protection, the desktop version of privacy.sexy automatically verifies the security of script
-It employs robust and reliable execution strategies, including self-healing mechanisms, and provides guidance and troubleshooting information to resolve issues effectively.
+execution files by reading them back.
-In contrast, the web version has more basic error handling due to browser limitations and the nature of web applications.
+This process triggers antivirus scans to verify that scripts are safe before the execution.
 
-### Native dialogs
+**Script integrity checks:**
-
-The desktop version uses native dialogs, offering more features and reliability compared to the browser's file system dialogs.
-These native dialogs provide a more integrated and user-friendly experience, aligning with the operating system's standard interface and functionalities.
-
-### Secure script execution/storage
-
-**Integrity checks:**
 
 The desktop version of privacy.sexy implements robust integrity checks for both script execution and storage.
 Featuring tamper protection, the application actively verifies the integrity of script files before executing or saving them.
 If the actual contents of a script file do not align with the expected contents, the application refuses to execute or save the script.
 This proactive approach ensures only unaltered and verified scripts undergo processing, thereby enhancing both security and reliability.
-Due to browser constraints, this feature is absent in the web version.
 
 **Error handling:**
 
+The desktop version of privacy.sexy features advanced error handling capabilities.
 In scenarios where script execution or storage encounters failure, the desktop application initiates automated troubleshooting and self-healing processes.
-It also guides users through potential issues with filesystem or third-party software, such as antivirus interventions.
+It employs robust and reliable execution strategies, including self-healing mechanisms, and provides guidance and troubleshooting information to resolve issues effectively.
-Specifically, the application is capable of identifying when antivirus software blocks or removes a script, providing users with tailored error messages
+This proactive error handling and user guidance enhances the application's security and reliability.
-and detailed resolution steps. This level of proactive error handling and user guidance enhances the application's security and reliability,
+
-offering a feature not achievable in the web version due to browser limitations.
+### Native dialogs
+
+The desktop version uses native dialogs, offering more features and reliability compared to the browser's file system dialogs.
+These native dialogs provide a more integrated and user-friendly experience, aligning with the operating system's standard interface and functionalities.

docs/desktop/system-requirements.md

@@ -0,0 +1,40 @@
+# System Requirements for the Desktop Version
+
+The following system requirements are the official ones for the desktop version.
+While we have tested and confirmed these requirements, the application might also work on other
+systems or configurations that haven't undergone official testing.
+
+## Windows
+
+- **Version:** Windows 10 and later.
+- **Processor:** Intel Pentium 4 or later.
+- **Architecture:** 64-bit (x64), ARM.
+
+> **⚠️ Compatibility Note:**
+> ARM version is only compatible with Windows 11 and later.
+> It runs non-natively, leading to slower performance due to emulation [1].
+
+## macOS
+
+- **Version:** macOS Catalina (10.15) and later.
+- **Architecture:** Intel-based (64-bit), Apple Silicon (ARM).
+
+> **⚠️ Compatibility Note:**
+> Apple Silicon version runs non-natively, leading to slower performance due to emulation [2].
+
+## Linux
+
+- **Version:** Ubuntu 18.04 and later, Fedora 32 and later, and Debian 10 and later.
+- **Processor:** Intel Pentium 4 or later.
+- **Architecture:** 64-bit (x64).
+
+## References
+
+System requirements reflect Electron's platform capabilities [3] and Chromium's recommended configurations [4].
+
+For details on the build process, see [electron-builder configuration file](./../../electron-builder.cjs).
+
+[1]: https://web.archive.org/web/20240428082726/https://learn.microsoft.com/en-us/windows/arm/add-arm-support#emulation-on-arm-based-devices-for-x86-or-x64-windows-apps "Add support Arm devices to your Windows app | Microsoft Learn | learn.microsoft.com"
+[2]: https://archive.today/2024.04.28-082901/https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary%23overview "Building a universal macOS binary | Apple Developer Documentation | developer.apple.com"
+[3]: https://archive.ph/2024.04.28-082958/https://github.com/electron/electron/blob/main/README.md#platform-support "Platform Support | electron/README.md at main · electron/electron · GitHub | github.com"
+[4]: https://web.archive.org/web/20240428082945/https://support.google.com/chrome/a/answer/7100626?hl=en "Chrome browser system requirements - Chrome Enterprise and Education Help | support.google.com"

docs/presentation.md

@@ -23,8 +23,10 @@ The presentation layer uses an event-driven architecture for bidirectional react
     - [**`styles/`**](./../src/presentation/assets/styles/): Contains shared styles.
       - [**`main.scss`**](./../src/presentation/assets/styles/main.scss): Main Sass file, imported by other components as single entrypoint..
   - [**`electron/`**](./../src/presentation/electron/): Contains Electron code.
-    - [`/main/` **`index.ts`**](./../src/presentation/main.ts): Main entry for Electron, managing application windows and lifecycle events.
+    - [`/main/` **`index.ts`**](./../src/presentation/electron/main/index.ts): Main entry for Electron, managing application windows and lifecycle events.
-    - [`/preload/` **`index.ts`**](./../src/presentation/main.ts): Script executed before the renderer, securing Node.js features for renderer use.
+    - [`/preload/` **`index.ts`**](./../src/presentation/electron/preload/index.ts): Script executed before the renderer, securing Node.js features for renderer use.
+    - [**`/shared/`**](./../src/presentation/electron/shared/): Shared logic between different Electron processes.
+    - [**`/build/`**](./../src/presentation/electron/build/): `electron-builder` build resources directory, [README.md](./../src/presentation/electron/build/README.md).
 - [**`/vite.config.ts`**](./../vite.config.ts): Contains Vite configurations for building web application.
 - [**`/electron.vite.config.ts`**](./../electron.vite.config.ts): Contains Vite configurations for building desktop applications.
 - [**`/postcss.config.cjs`**](./../postcss.config.cjs): Contains PostCSS configurations for Vite.

docs/script-guidelines.md

@@ -27,6 +27,7 @@ Key attributes of a good script:
   - `Minimize` over `Limit`, `Reduce`
   - `Maximize` over `Extend`, `Delay`, `Postpone`, `Prolong`
   - `Remove` over `Uninstall`
+  - `Improve` over `Increase`
 - Structure your phrases for clarity, examples:
   - Prefer `Disable XX telemetry` over `Disable telemetry in XX`
   - Prefer `Clear XX data` over `Clear data from XX`, or `Clear data of XX`.

electron-builder.cjs

@@ -1,7 +1,7 @@
 /* eslint-disable no-template-curly-in-string */
 
-const { join } = require('node:path');
+const { join, resolve } = require('node:path');
-const { readdirSync } = require('fs');
+const { readdirSync, existsSync } = require('node:fs');
 const { electronBundled, electronUnbundled } = require('./dist-dirs.json');
 
 /**
@@ -17,6 +17,7 @@ module.exports = {
   },
   directories: {
     output: electronBundled,
+    buildResources: resolvePathFromProjectRoot('src/presentation/electron/build'),
   },
   extraMetadata: {
     main: findMainEntryFile(
@@ -53,10 +54,18 @@ module.exports = {
  * Finds by accommodating different JS file extensions and module formats.
  */
 function findMainEntryFile(parentDirectory) {
-  const files = readdirSync(parentDirectory);
+  const absoluteParentDirectory = resolvePathFromProjectRoot(parentDirectory);
+  if (!existsSync(absoluteParentDirectory)) {
+    return null; // Avoid disrupting other processes such `npm install`.
+  }
+  const files = readdirSync(absoluteParentDirectory);
   const entryFile = files.find((file) => /^index\.(cjs|mjs|js)$/.test(file));
   if (!entryFile) {
-    throw new Error(`Main entry file not found in ${parentDirectory}.`);
+    throw new Error(`Main entry file not found in ${absoluteParentDirectory}.`);
   }
   return join(parentDirectory, entryFile);
 }
+
+function resolvePathFromProjectRoot(pathSegment) {
+  return resolve(__dirname, pathSegment);
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "privacy.sexy",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "private": true,
   "slogan": "Privacy is sexy",
   "description": "Enforce privacy & security best-practices on Windows, macOS and Linux, because privacy is sexy.",
@@ -14,7 +14,7 @@
     "test:integration": "vitest run --dir tests/integration",
     "test:cy:run": "start-server-and-test \"vite build && vite preview --port 7070\" http://localhost:7070 \"cypress run --config baseUrl=http://localhost:7070\"",
     "test:cy:open": "start-server-and-test \"vite --port 7070 --mode production\" http://localhost:7070 \"cypress open --config baseUrl=http://localhost:7070\"",
-    "lint": "npm run lint:md && npm run lint:md:consistency && npm run lint:md:relative-urls && npm run lint:eslint && npm run lint:yaml",
+    "lint": "npm run lint:md && npm run lint:md:consistency && npm run lint:md:relative-urls && npm run lint:eslint && npm run lint:yaml && npm run lint:pylint",
     "install-deps": "node scripts/npm-install.js",
     "icons:build": "node scripts/logo-update.js",
     "check:desktop": "vitest run --dir tests/checks/desktop-runtime-errors --environment node",
@@ -29,6 +29,7 @@
     "lint:md:consistency": "remark . --frail --use remark-preset-lint-consistent",
     "lint:md:relative-urls": "remark . --frail --use remark-validate-links",
     "lint:yaml": "yamllint **/*.yaml --ignore=node_modules/**/*.yaml",
+    "lint:pylint": "pylint **/*.py",
     "postinstall": "electron-builder install-app-deps",
     "postuninstall": "electron-builder install-app-deps"
   },
@@ -61,13 +62,11 @@
     "electron": "^29.3.0",
     "electron-builder": "^24.13.3",
     "electron-devtools-installer": "^3.2.0",
-    "electron-icon-builder": "^2.0.1",
     "electron-vite": "^2.1.0",
     "eslint": "8.57.0",
     "eslint-plugin-cypress": "^2.15.1",
     "eslint-plugin-vue": "^9.25.0",
     "eslint-plugin-vuejs-accessibility": "^2.2.1",
-    "icon-gen": "^4.0.0",
     "jsdom": "^24.0.0",
     "markdownlint-cli": "^0.39.0",
     "postcss": "^8.4.38",
@@ -77,7 +76,6 @@
     "remark-validate-links": "^13.0.1",
     "sass": "^1.75.0",
     "start-server-and-test": "^2.0.3",
-    "svgexport": "^0.4.2",
     "terser": "^5.30.3",
     "tslib": "^2.6.2",
     "typescript": "^5.4.5",

scripts/configure_vscode.py

@@ -1,6 +1,10 @@
 """
-This script configures project-level VSCode settings in '.vscode/settings.json' for 
+Description:
-development and installs recommended extensions from '.vscode/extensions.json'.
+  This script configures project-level VSCode settings in '.vscode/settings.json' for
+  development and installs recommended extensions from '.vscode/extensions.json'.
+
+Usage:
+  python3 ./scripts/configure_vscode.py
 """
 # pylint: disable=missing-function-docstring
 
@@ -40,7 +44,7 @@ def ensure_setting_file_exists() -> None:
             print_success(f"Created empty {VSCODE_SETTINGS_JSON_FILE}")
     except IOError as error:
         print_error(f"Error creating file {VSCODE_SETTINGS_JSON_FILE}: {error}")
-    print(f"📄 Created empty {VSCODE_SETTINGS_JSON_FILE}")
+    print_success(f"Created empty {VSCODE_SETTINGS_JSON_FILE}")
 
 def add_or_update_settings() -> None:
     configure_setting_key('eslint.validate', ['vue', 'javascript', 'typescript'])
@@ -98,7 +102,8 @@ def locate_vscode_cli() -> Optional[str]:
     if vscode_alias:
         return vscode_alias
     potential_vscode_cli_paths = [
-        '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code' # macOS VS Code may not register 'code' command in PATH
+        # VS Code on macOS may not register 'code' command in PATH
+        '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code'
     ]
     for vscode_cli_candidate_path in potential_vscode_cli_paths:
         if Path(vscode_cli_candidate_path).is_file():
@@ -109,7 +114,7 @@ def remove_json_comments(json_like: str) -> str:
     pattern: str = r'(?:"(?:\\.|[^"\\])*"|/\*[\s\S]*?\*/|//.*)|([^:]//.*$)'
     return re.sub(
         pattern,
-        lambda m: '' if m.group(1) else m.agroup(0), json_like, flags=re.MULTILINE,
+        lambda m: '' if m.group(1) else m.group(0), json_like, flags=re.MULTILINE,
     )
 
 def install_vscode_extensions(vscode_cli_path: str, extensions: list[str]) -> None:
@@ -166,16 +171,16 @@ def print_installation_results(successful_installations: int, total_extensions:
         print_error("Failed to install any of the recommended extensions.")
 
 def print_error(message: str) -> None:
-    print(f"💀 Error: {message}", file=sys.stderr)
+    print(f"[ERROR] {message}", file=sys.stderr)
 
 def print_success(message: str) -> None:
-    print(f"✅ Success: {message}")
+    print(f"[SUCCESS] {message}")
 
 def print_skip(message: str) -> None:
-    print(f"⏩ Skipped: {message}")
+    print(f"[SKIPPED] {message}")
 
 def print_warning(message: str) -> None:
-    print(f"⚠️ Warning: {message}", file=sys.stderr)
+    print(f"[WARNING] {message}", file=sys.stderr)
 
 if __name__ == "__main__":
     main()

scripts/logo-update.js

@@ -2,94 +2,119 @@
  * Description:
  *  This script updates the logo images across the project based on the primary
  *  logo file ('img/logo.svg' file).
+ *
  *  It handles the creation and update of various icon sizes for different purposes,
  *  including desktop launcher icons, tray icons, and web favicons from a single source
  *  SVG logo file.
  *
  * Usage:
- *   node ./scripts/logo-update.js
+ *    node ./scripts/logo-update.js
+ *
+ * Notes:
+ *    ImageMagick must be installed and accessible in the system's PATH
  */
 
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
-import { rm, mkdtemp, stat } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { URL, fileURLToPath } from 'node:url';
+import electronBuilderConfig from '../electron-builder.cjs';
 
-class Paths {
+class ImageAssetPaths {
-  constructor(selfDirectory) {
+  constructor(currentScriptDirectory) {
-    const projectRoot = resolve(selfDirectory, '../');
+    const projectRoot = resolve(currentScriptDirectory, '../');
     this.sourceImage = join(projectRoot, 'img/logo.svg');
     this.publicDirectory = join(projectRoot, 'src/presentation/public');
-    this.electronBuildDirectory = join(projectRoot, 'build');
+    this.electronBuildResourcesDirectory = electronBuilderConfig.directories.buildResources;
+  }
+
+  get electronTrayIconFile() {
+    return join(this.publicDirectory, 'icon.png');
+  }
+
+  get webFaviconFile() {
+    return join(this.publicDirectory, 'favicon.ico');
   }
 
   toString() {
-    return `Source image: ${this.sourceImage}\n`
+    return `Source image: ${this.sourceImage}`
-      + `Public directory: ${this.publicDirectory}\n`
+      + `\nPublic directory: ${this.publicDirectory}`
-      + `Electron build directory: ${this.electronBuildDirectory}`;
+      + `\n\t Electron tray icon file: ${this.electronTrayIconFile}`
+      + `\n\t Web favicon file: ${this.webFaviconFile}`
+      + `\nElectron build directory: ${this.electronBuildResourcesDirectory}`;
   }
 }
 
 async function main() {
-  const paths = new Paths(getCurrentScriptDirectory());
+  const paths = new ImageAssetPaths(getCurrentScriptDirectory());
   console.log(`Paths:\n\t${paths.toString().replaceAll('\n', '\n\t')}`);
-  await updateDesktopLauncherAndTrayIcon(paths.sourceImage, paths.publicDirectory);
+  const convertCommand = await findAvailableImageMagickCommand();
-  await updateWebFavicon(paths.sourceImage, paths.publicDirectory);
+  await generateDesktopAndTrayIcons(
-  await updateDesktopIcons(paths.sourceImage, paths.electronBuildDirectory);
+    paths.sourceImage,
+    paths.electronTrayIconFile,
+    convertCommand,
+  );
+  await generateWebFavicon(
+    paths.sourceImage,
+    paths.webFaviconFile,
+    convertCommand,
+  );
+  await generateDesktopIcons(
+    paths.sourceImage,
+    paths.electronBuildResourcesDirectory,
+    convertCommand,
+  );
   console.log('🎉 (Re)created icons successfully.');
 }
 
-async function updateDesktopLauncherAndTrayIcon(sourceImage, publicFolder) {
+async function generateDesktopAndTrayIcons(sourceImage, targetFile, convertCommand) {
+  // Reference: https://web.archive.org/web/20240502124306/https://www.electronjs.org/docs/latest/api/tray
+  console.log(`Updating desktop launcher and tray icon at ${targetFile}.`);
   await ensureFileExists(sourceImage);
-  await ensureFolderExists(publicFolder);
+  await ensureParentFolderExists(targetFile);
-  const electronTrayIconFile = join(publicFolder, 'icon.png');
+  await convertFromSvgToPng(
-  console.log(`Updating desktop launcher and tray icon at ${electronTrayIconFile}.`);
+    convertCommand,
-  await runCommand(
-    'npx',
-    'svgexport',
     sourceImage,
-    electronTrayIconFile,
+    targetFile,
+    '512x512',
   );
 }
 
-async function updateWebFavicon(sourceImage, faviconFolder) {
+async function generateWebFavicon(sourceImage, faviconFilePath, convertCommand) {
-  console.log('Updating favicon');
+  console.log(`Updating favicon at ${faviconFilePath}.`);
   await ensureFileExists(sourceImage);
-  await ensureFolderExists(faviconFolder);
+  await ensureParentFolderExists(faviconFilePath);
-  await runCommand(
+  await convertFromSvgToIco(
-    'npx',
+    convertCommand,
-    'icon-gen',
+    sourceImage,
-    `--input ${sourceImage}`,
+    faviconFilePath,
-    `--output ${faviconFolder}`,
+    [16, 24, 32, 48, 64, 128, 256],
-    '--ico',
-    '--ico-name \'favicon\'',
-    '--report',
   );
 }
 
-async function updateDesktopIcons(sourceImage, electronIconsDir) {
+async function generateDesktopIcons(sourceImage, electronBuildResourcesDirectory, convertCommand) {
+  console.log(`Creating Electron icon files to ${electronBuildResourcesDirectory}.`);
+  // Reference: https://web.archive.org/web/20240501103645/https://www.electron.build/icons.html
+  await ensureFolderExists(electronBuildResourcesDirectory);
   await ensureFileExists(sourceImage);
-  await ensureFolderExists(electronIconsDir);
+  const electronMainIconFile = join(electronBuildResourcesDirectory, 'icon.png');
-  const temporaryDir = await mkdtemp('icon-');
+  await convertFromSvgToPng(
-  const temporaryPngFile = join(temporaryDir, 'icon.png');
+    convertCommand,
-  console.log(`Converting from SVG (${sourceImage}) to PNG: ${temporaryPngFile}`); // required by `icon-builder`
-  await runCommand(
-    'npx',
-    'svgexport',
     sourceImage,
-    temporaryPngFile,
+    electronMainIconFile,
-    '1024:1024',
+    '1024x1024', // Should be at least 512x512
   );
-  console.log(`Creating electron icons to ${electronIconsDir}.`);
+  // Relying on `electron-builder`s conversion from png to ico results in pixelated look on Windows
-  await runCommand(
+  // 10 and 11 according to tests, see:
-    'npx',
+  //  - https://web.archive.org/web/20240502114650/https://github.com/electron-userland/electron-builder/issues/7328
-    'electron-icon-builder',
+  //  - https://web.archive.org/web/20240502115448/https://github.com/electron-userland/electron-builder/issues/3867
-    `--input="${temporaryPngFile}"`,
+  const electronWindowsIconFile = join(electronBuildResourcesDirectory, 'icon.ico');
-    `--output="${electronIconsDir}"`,
+  await convertFromSvgToIco(
-    '--flatten',
+    convertCommand,
+    sourceImage,
+    electronWindowsIconFile,
+    [16, 24, 32, 48, 64, 128, 256],
   );
-  console.log('Cleaning up temporary directory.');
-  await rm(temporaryDir, { recursive: true, force: true });
 }
 
 async function ensureFileExists(filePath) {
@@ -100,12 +125,60 @@ async function ensureFileExists(filePath) {
 }
 
 async function ensureFolderExists(folderPath) {
+  if (!folderPath) {
+    throw new Error('Path is missing');
+  }
   const path = await stat(folderPath);
   if (!path.isDirectory()) {
     throw new Error(`Not a directory: ${folderPath}`);
   }
 }
 
+function ensureParentFolderExists(filePath) {
+  return ensureFolderExists(dirname(filePath));
+}
+
+const BaseImageMagickConvertArguments = Object.freeze([
+  '-background none', // Transparent, so they do not get filled with white.
+  '-strip', // Strip metadata.
+  '-gravity Center', // Center the image when there's empty space
+]);
+
+async function convertFromSvgToIco(
+  convertCommand,
+  inputFile,
+  outputFile,
+  sizes,
+) {
+  await runCommand(
+    convertCommand,
+    ...BaseImageMagickConvertArguments,
+    `-density ${Math.max(...sizes).toString()}`, // High enough for sharpness
+    `-define icon:auto-resize=${sizes.map((s) => s.toString()).join(',')}`, // Automatically store multiple sizes in an ico image
+    '-compress None',
+    inputFile,
+    outputFile,
+  );
+}
+
+async function convertFromSvgToPng(
+  convertCommand,
+  inputFile,
+  outputFile,
+  size = undefined,
+) {
+  await runCommand(
+    convertCommand,
+    ...BaseImageMagickConvertArguments,
+    ...(size === undefined ? [] : [
+      `-resize ${size}`,
+      `-density ${size}`, // High enough for sharpness
+    ]),
+    inputFile,
+    outputFile,
+  );
+}
+
 async function runCommand(...args) {
   const command = args.join(' ');
   console.log(`Running command: ${command}`);
@@ -135,4 +208,27 @@ function getCurrentScriptDirectory() {
   return fileURLToPath(new URL('.', import.meta.url));
 }
 
+async function findAvailableImageMagickCommand() {
+  // Reference: https://web.archive.org/web/20240502120041/https://imagemagick.org/script/convert.php
+  const potentialBaseCommands = [
+    'convert', // Legacy command, usually available on Linux/macOS installations
+    'magick convert', // Newer command, available on Windows installations
+  ];
+  for (const baseCommand of potentialBaseCommands) {
+    const testCommand = `${baseCommand} -version`;
+    try {
+      await runCommand(testCommand); // eslint-disable-line no-await-in-loop
+      console.log(`Confirmed: ImageMagick command '${baseCommand}' is available and operational.`);
+      return baseCommand;
+    } catch (err) {
+      console.log(`Error: The command '${baseCommand}' is not found or failed to execute. Detailed error: ${err.message}"`);
+    }
+  }
+  throw new Error([
+    'Unable to locate any operational ImageMagick command.',
+    `Attempted commands were: ${potentialBaseCommands.join(', ')}.`,
+    'Please ensure ImageMagick is correctly installed and accessible.',
+  ].join('\n'));
+}
+
 await main();

src/application/CodeRunner/CodeRunner.ts

@@ -11,10 +11,11 @@ export type CodeRunErrorType =
   | 'FileWriteError'
   | 'FileReadbackVerificationError'
   | 'FilePathGenerationError'
-  | 'UnsupportedOperatingSystem'
+  | 'UnsupportedPlatform'
-  | 'FileExecutionError'
   | 'DirectoryCreationError'
-  | 'UnexpectedError';
+  | 'FilePermissionChangeError'
+  | 'FileExecutionError'
+  | 'ExternalProcessTermination';
 
 interface CodeRunStatus {
   readonly success: boolean;

src/application/Common/Timing/Throttle.ts

@@ -1,44 +1,156 @@
+/* eslint-disable max-classes-per-file */
 import { PlatformTimer } from './PlatformTimer';
 import type { Timer, TimeoutType } from './Timer';
 
 export type CallbackType = (..._: readonly unknown[]) => void;
 
+export interface ThrottleOptions {
+  /** Skip the immediate execution of the callback on the first invoke */
+  readonly excludeLeadingCall: boolean;
+  readonly timer: Timer;
+}
+
+const DefaultOptions: ThrottleOptions = {
+  excludeLeadingCall: false,
+  timer: PlatformTimer,
+};
+
 export function throttle(
   callback: CallbackType,
   waitInMs: number,
-  timer: Timer = PlatformTimer,
+  options: Partial<ThrottleOptions> = DefaultOptions,
 ): CallbackType {
-  const throttler = new Throttler(timer, waitInMs, callback);
+  const defaultedOptions: ThrottleOptions = {
+    ...DefaultOptions,
+    ...options,
+  };
+  const throttler = new Throttler(waitInMs, callback, defaultedOptions);
   return (...args: unknown[]) => throttler.invoke(...args);
 }
 
 class Throttler {
-  private queuedExecutionId: TimeoutType | undefined;
+  private lastExecutionTime: number | null = null;
 
-  private previouslyRun: number;
+  private executionScheduler: DelayedCallbackScheduler;
 
   constructor(
-    private readonly timer: Timer,
     private readonly waitInMs: number,
     private readonly callback: CallbackType,
+    private readonly options: ThrottleOptions,
   ) {
     if (!waitInMs) { throw new Error('missing delay'); }
     if (waitInMs < 0) { throw new Error('negative delay'); }
+    this.executionScheduler = new DelayedCallbackScheduler(options.timer);
   }
 
   public invoke(...args: unknown[]): void {
-    const now = this.timer.dateNow();
+    switch (true) {
-    if (this.queuedExecutionId !== undefined) {
+      case this.isLeadingCallWithinThrottlePeriod(): {
-      this.timer.clearTimeout(this.queuedExecutionId);
+        if (this.options.excludeLeadingCall) {
-      this.queuedExecutionId = undefined;
+          this.scheduleNext(args);
-    }
+          return;
-    if (!this.previouslyRun || (now - this.previouslyRun >= this.waitInMs)) {
+        }
-      this.callback(...args);
+        this.executeNow(args);
-      this.previouslyRun = now;
+        return;
-    } else {
+      }
-      const nextCall = () => this.invoke(...args);
+      case this.isAlreadyScheduled(): {
-      const nextCallDelayInMs = this.waitInMs - (now - this.previouslyRun);
+        this.updateNextScheduled(args);
-      this.queuedExecutionId = this.timer.setTimeout(nextCall, nextCallDelayInMs);
+        return;
+      }
+      case !this.isThrottlePeriodPassed(): {
+        this.scheduleNext(args);
+        return;
+      }
+      default:
+        throw new Error('Throttle logical error: no conditions for execution or scheduling were met.');
     }
   }
+
+  private isLeadingCallWithinThrottlePeriod(): boolean {
+    return this.isThrottlePeriodPassed()
+      && !this.isAlreadyScheduled();
+  }
+
+  private isThrottlePeriodPassed(): boolean {
+    if (this.lastExecutionTime === null) {
+      return true;
+    }
+    const timeSinceLastExecution = this.options.timer.dateNow() - this.lastExecutionTime;
+    const isThrottleTimePassed = timeSinceLastExecution >= this.waitInMs;
+    return isThrottleTimePassed;
+  }
+
+  private isAlreadyScheduled(): boolean {
+    return this.executionScheduler.getNext() !== null;
+  }
+
+  private scheduleNext(args: unknown[]): void {
+    if (this.executionScheduler.getNext()) {
+      throw new Error('An execution is already scheduled.');
+    }
+    this.executionScheduler.resetNext(
+      () => this.executeNow(args),
+      this.waitInMs,
+    );
+  }
+
+  private updateNextScheduled(args: unknown[]): void {
+    const nextScheduled = this.executionScheduler.getNext();
+    if (!nextScheduled) {
+      throw new Error('A non-existent scheduled execution cannot be updated.');
+    }
+    const nextDelay = nextScheduled.scheduledTime - this.dateNow();
+    this.executionScheduler.resetNext(
+      () => this.executeNow(args),
+      nextDelay,
+    );
+  }
+
+  private executeNow(args: unknown[]): void {
+    this.callback(...args);
+    this.lastExecutionTime = this.dateNow();
+  }
+
+  private dateNow(): number {
+    return this.options.timer.dateNow();
+  }
+}
+
+interface ScheduledCallback {
+  readonly scheduleTimeoutId: TimeoutType;
+  readonly scheduledTime: number;
+}
+
+class DelayedCallbackScheduler {
+  private scheduledCallback: ScheduledCallback | null = null;
+
+  constructor(
+    private readonly timer: Timer,
+  ) { }
+
+  public getNext(): ScheduledCallback | null {
+    return this.scheduledCallback;
+  }
+
+  public resetNext(
+    callback: () => void,
+    delayInMs: number,
+  ) {
+    this.clear();
+    this.scheduledCallback = {
+      scheduledTime: this.timer.dateNow() + delayInMs,
+      scheduleTimeoutId: this.timer.setTimeout(() => {
+        this.clear();
+        callback();
+      }, delayInMs),
+    };
+  }
+
+  private clear() {
+    if (this.scheduledCallback === null) {
+      return;
+    }
+    this.timer.clearTimeout(this.scheduledCallback.scheduleTimeoutId);
+    this.scheduledCallback = null;
+  }
 }

src/application/collections/linux.yaml

@@ -184,7 +184,7 @@ actions:
               > - Logs are valuable for diagnosing issues and understanding past actions [1].
               > - Script files can help review changes made to the system and aid in reverting those changes if needed.
 
-              [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+              [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
               [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
             children:
               -
@@ -202,7 +202,7 @@ actions:
                   > - This action is irreversible. Deleted script files cannot be retrieved.
                   > - These files might be necessary for troubleshooting if you experience issues after using privacy.sexy scripts.
 
-                  [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+                  [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
                   [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
                 call:
                   function: ClearDirectoryContents
@@ -223,7 +223,7 @@ actions:
                   > - Removing logs will prevent you from reviewing the application's activities, which could be helpful in diagnosing issues.
                   > - Logs can contain valuable information for technical support should you need assistance.
 
-                  [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+                  [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
                   [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
                 call:
                   function: ClearDirectoryContents
@@ -2761,7 +2761,7 @@ actions:
                 docs: |-
                   Firefox provides an option for Enhanced Tracking Protection [1], which blocks trackers that
                   gather information about your browsing behavior without disrupting site functionality [1].
-                  This feature also includes protections against harmful scripts such as malware that drains
+                  This feature also includes protections against harmful scripts such as malware that drain
                   your battery [1].
 
                   This script enables the `privacy.resistFingerprinting` preference,
@@ -2791,7 +2791,7 @@ actions:
                   This script enables the `privacy.resistFingerprinting` preference, activating
                   anti-fingerprinting [1][2].
 
-                  As an experimental feature, it might cause some website breakage [2], such as impacting web
+                  As an experimental feature, it might cause some website breakages [2], such as impacting web
                   speech functionality [3] and favicons [4].
 
                   [1]: https://web.archive.org/web/20221025201025/https://support.mozilla.org/en-US/kb/firefox-protection-against-fingerprinting "Firefox's protection against fingerprinting | Firefox Help | support.mozilla.org"
@@ -2876,7 +2876,7 @@ actions:
 
                   It's configured to be enabled in nightly, aurora, beta, or default (developer) builds.
                   In release builds, however, it's set to false [1]. This setting is hard-coded into the C++
-                  code to prevent easy disabling [2]. Developers have been approached about this issue but
+                  code to prevent easy disabling [2]. Developers have been approached about this issue, but
                   have rejected proposals to unlock it [3].
 
                   Mozilla's plan is to deprecate this setting eventually, followed by removal [1].
@@ -3012,7 +3012,7 @@ actions:
                     recommend: standard
                     docs: |-
                       This script sets `toolkit.telemetry.server` to be empty.
-                      This preference defines the server to which Telemetry pings are sent [1].
+                      This preference defines the server to which telemetry pings are sent [1].
 
                       [1]: https://web.archive.org/web/20221015102124/https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/internals/preferences.html "Preferences and Defines — Firefox Source Docs documentation | firefox-source-docs.mozilla.org"
                     call:
@@ -3133,7 +3133,7 @@ actions:
                 name: Disable Firefox Pioneer study monitoring
                 recommend: standard
                 docs: |-
-                  This script configures `toolkit.telemetry.pioneer-new-studies-available` to be disabled to opt out.
+                  This script configures `toolkit.telemetry.pioneer-new-studies-available` to be disabled to opt out
                   Firefox Pioneer program.
 
                   This setting disables availability check for Firefox Pioneer studies [1].
@@ -3711,7 +3711,7 @@ functions:
     #   User-specific:
     #     [~/.profile]
     #       User-specific shell initialization scripts.
-    #       ✅ Recomended by Debian to edit for user-specific environment variables.
+    #       ✅ Recommended by Debian to edit for user-specific environment variables.
     #     [~/.bashrc]
     #       User-based configuration file to set environment variables for Bash shell.
     #       ❌ Bash-specific.
@@ -3783,7 +3783,7 @@ functions:
       if [[ -f "$cronjob_path" ]]; then
         if [[ -x "$cronjob_path" ]]; then
           sudo chmod -x "$cronjob_path"
-          echo "Succesfully disabled cronjob \"$job_name\"."
+          echo "Successfully disabled cronjob \"$job_name\"."
         else
           echo "Skipping, cronjob \"$job_name\" is already disabled."
         fi
@@ -3797,7 +3797,7 @@ functions:
           echo "Skipping, cronjob \"$job_name\" is already enabled."
         else
           sudo chmod +x "$cronjob_path"
-          echo "Succesfully enabled cronjob \"$job_name\"."
+          echo "Successfully enabled cronjob \"$job_name\"."
         fi
       else
         >&2 echo "Failed to enable cronjob \"$job_name\" because it's missing."
@@ -3939,7 +3939,7 @@ functions:
         echo "Backup file exists: $file."
         sudo mv "$backup_file" "$file"
         echo "Moved to: $file."
-        echo "Succesfully restored."
+        echo "Successfully restored."
       else
         >&2 echo "Failed to restore, backup file could not be found at $backup_file."
         >&2 echo "Was the change initially applied by privacy.sexy?"

src/application/collections/macos.yaml

@@ -300,7 +300,7 @@ actions:
                             > - Logs are valuable for diagnosing issues and understanding past actions [1].
                             > - Script files can help review changes made to the system and aid in reverting those changes if needed.
 
-                            [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+                            [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
                             [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
                         children:
                             -
@@ -318,7 +318,7 @@ actions:
                                     > - This action is irreversible. Deleted script files cannot be retrieved.
                                     > - These files might be necessary for troubleshooting if you experience issues after using privacy.sexy scripts.
 
-                                    [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+                                    [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
                                     [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
                                 call:
                                     function: ClearDirectoryContents
@@ -339,7 +339,7 @@ actions:
                                     > - Removing logs will prevent you from reviewing the application's activities, which could be helpful in diagnosing issues.
                                     > - Logs can contain valuable information for technical support should you need assistance.
 
-                                    [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
+                                    [1]: https://github.com/undergroundwires/privacy.sexy/blob/master/docs/desktop/desktop-vs-web-features.md "Desktop vs. Web Features | privacy.sexy | github.com"
                                     [2]: https://github.com/undergroundwires/privacy.sexy/blob/master/SECURITY.md "SECURITY.md  | privacy.sexy | github.com"
                                 call:
                                     function: ClearDirectoryContents
@@ -1468,7 +1468,7 @@ actions:
 
                     > **Caution**:
                     > Disabling automatic updates can leave your system vulnerable to unpatched exploits.
-                    > Manually check and and apply updates to stay protected.
+                    > Manually check and apply updates to stay protected.
                 children:
                     -
                         name: Disable automatic checks for updates

src/infrastructure/CodeRunner/Execution/CommandDefinition/CommandDefinition.ts

@@ -0,0 +1,5 @@
+export interface CommandDefinition {
+  buildShellCommand(filePath: string): string;
+  isExecutionTerminatedExternally(exitCode: number): boolean;
+  isExecutablePermissionsRequiredOnFile(): boolean;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/LinuxVisibleTerminalCommand.ts

@@ -0,0 +1,61 @@
+import { PosixShellArgumentEscaper } from './ShellArgument/PosixShellArgumentEscaper';
+import type { CommandDefinition } from '../CommandDefinition';
+import type { ShellArgumentEscaper } from './ShellArgument/ShellArgumentEscaper';
+
+export const LinuxTerminalEmulator = 'x-terminal-emulator';
+
+export class LinuxVisibleTerminalCommand implements CommandDefinition {
+  constructor(
+    private readonly escaper: ShellArgumentEscaper = new PosixShellArgumentEscaper(),
+  ) { }
+
+  public buildShellCommand(filePath: string): string {
+    return `${LinuxTerminalEmulator} -e ${this.escaper.escapePathArgument(filePath)}`;
+    /*
+      🤔 Potential improvements:
+          Use user-friendly GUI sudo prompt (not terminal-based).
+          If `pkexec` exists, we could do `x-terminal-emulator -e pkexec 'path'`, which always
+          prompts with user-friendly GUI sudo prompt.
+      📝 Options:
+        `x-terminal-emulator -e 'path'`:
+            ✅  Visible terminal window
+            ❌  Terminal-based (not GUI) sudo prompt.
+        `x-terminal-emulator -e pkexec 'path'
+          ✅  Visible terminal window
+          ✅  Always prompts with user-friendly GUI sudo prompt.
+          🤔  Not using `pkexec` as it is not in all Linux distributions. It should have smarter
+              logic to handle if it does not exist.
+        `electron.shell.openPath`:
+          ❌  Opens the script in the default text editor, verified on
+              Debian/Ubuntu-based distributions.
+        `child_process.execFile()`:
+          ❌  Script execution in the background without a visible terminal.
+    */
+  }
+
+  public isExecutionTerminatedExternally(exitCode: number): boolean {
+    return exitCode === 137;
+    /*
+      `x-terminal-emulator` may return exit code `137` under specific circumstances like when the
+      user closes the terminal (observed with `gnome-terminal` on Pop!_OS). This exit code (128 +
+      Unix signal 9) indicates the process was terminated by a SIGKILL signal, which can occur due
+      to user action (cancelling the progress) or the system (e.g., due to memory shortages).
+
+      Additional exit codes noted for future consideration (currently not handled as they have not
+      been reproduced):
+
+      - 130 (130 = 128 + Unix signal 2): Indicates the script was terminated by the user
+        (Control-C), corresponding to a SIGINT signal.
+      - 143 (128 + Unix signal 15): Indicates termination by a SIGTERM signal, suggesting a request
+        to gracefully terminate the process.
+    */
+  }
+
+  public isExecutablePermissionsRequiredOnFile(): boolean {
+    /*
+      On Linux, a script file without executable permissions cannot be run directly by its path
+      without specifying a shell explicitly.
+    */
+    return true;
+  }
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/MacOsVisibleTerminalCommand.ts

@@ -0,0 +1,46 @@
+import { PosixShellArgumentEscaper } from './ShellArgument/PosixShellArgumentEscaper';
+import type { CommandDefinition } from '../CommandDefinition';
+import type { ShellArgumentEscaper } from './ShellArgument/ShellArgumentEscaper';
+
+export class MacOsVisibleTerminalCommand implements CommandDefinition {
+  constructor(
+    private readonly escaper: ShellArgumentEscaper = new PosixShellArgumentEscaper(),
+  ) { }
+
+  public buildShellCommand(filePath: string): string {
+    return `open -a Terminal.app ${this.escaper.escapePathArgument(filePath)}`;
+    /*
+      📝 Options:
+        `child_process.execFile()`
+        "path", `cmd.exe /c "path"`
+          ❌  Script execution in the background without a visible terminal.
+              This occurs only when the user runs the application as administrator, as seen
+              in Windows Pro VMs on Azure.
+        `PowerShell Start -Verb RunAs "path"`
+          ✅  Visible terminal window
+          ✅  GUI sudo prompt (through `RunAs` option)
+        `PowerShell Start "path"`
+        `explorer.exe "path"`
+        `electron.shell.openPath`
+        `start cmd.exe /c "$path"`
+          ✅  Visible terminal window
+          ✅  GUI sudo prompt (through `RunAs` option)
+          👍  Among all options `start` command is the most explicit one, being the most resilient
+              against the potential changes in Windows or Electron framework (e.g. https://github.com/electron/electron/issues/36765).
+              `%COMSPEC%` environment variable should be checked before defaulting to `cmd.exe.
+      Related docs: https://web.archive.org/web/20240106002357/https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows
+    */
+  }
+
+  public isExecutionTerminatedExternally(): boolean {
+    return false;
+  }
+
+  public isExecutablePermissionsRequiredOnFile(): boolean {
+    /*
+      On macOS, a script file without executable permissions cannot be run directly by its path
+      without specifying a shell explicitly.
+    */
+    return true;
+  }
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/PowerShellInvoke/EncodedPowerShellInvokeCmdCommandCreator.ts

@@ -0,0 +1,32 @@
+import type { PowerShellInvokeShellCommandCreator } from './PowerShellInvokeShellCommandCreator';
+
+/**
+  Encoding PowerShell commands resolve issues with quote handling.
+
+  There are known problems with PowerShell's handling of double quotes in command line arguments:
+  - Quote stripping in PowerShell command line arguments: https://web.archive.org/web/20240507102706/https://stackoverflow.com/questions/6714165/powershell-stripping-double-quotes-from-command-line-arguments
+  - privacy.sexy double quotes issue when calling PowerShell from command line: https://web.archive.org/web/20240507102841/https://github.com/undergroundwires/privacy.sexy/issues/351
+  - Challenges with single quotes in PowerShell command line: https://web.archive.org/web/20240507102047/https://stackoverflow.com/questions/20958388/command-line-escaping-single-quote-for-powershell
+
+  Using the `EncodedCommand` parameter is recommended by Microsoft for handling
+  complex quoting scenarios. This approach helps avoid issues by encoding the entire
+  command as a Base64 string:
+  - Microsoft's documentation on using the `EncodedCommand` parameter: https://web.archive.org/web/20240507102733/https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1#-encodedcommand-base64encodedcommand
+*/
+export class EncodedPowerShellInvokeCmdCommandCreator
+implements PowerShellInvokeShellCommandCreator {
+  public createCommandToInvokePowerShell(powerShellScript: string): string {
+    return generateEncodedPowershellCommand(powerShellScript);
+  }
+}
+
+function generateEncodedPowershellCommand(powerShellScript: string): string {
+  const encodedCommand = encodeForPowershellExecution(powerShellScript);
+  return `PowerShell -EncodedCommand ${encodedCommand}`;
+}
+
+function encodeForPowershellExecution(script: string): string {
+  // The string must be formatted using UTF-16LE character encoding, see: https://web.archive.org/web/20240507102733/https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1#-encodedcommand-base64encodedcommand
+  const buffer = Buffer.from(script, 'utf16le');
+  return buffer.toString('base64');
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/PowerShellInvoke/PowerShellInvokeShellCommandCreator.ts

@@ -0,0 +1,3 @@
+export interface PowerShellInvokeShellCommandCreator {
+  createCommandToInvokePowerShell(powerShellCommand: string): string;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PosixShellArgumentEscaper.ts

@@ -0,0 +1,18 @@
+import type { ShellArgumentEscaper } from './ShellArgumentEscaper';
+
+export class PosixShellArgumentEscaper implements ShellArgumentEscaper {
+  public escapePathArgument(pathArgument: string): string {
+    return posixShellPathArgumentEscape(pathArgument);
+  }
+}
+
+function posixShellPathArgumentEscape(pathArgument: string): string {
+  /*
+    - Wraps the path in single quotes, which is a standard practice in POSIX shells
+      (like bash and zsh) found on macOS/Linux to ensure that characters like spaces, '*', and
+      '?' are treated as literals, not as special characters.
+    - Escapes any single quotes within the path itself. This allows paths containing single
+      quotes to be correctly interpreted in POSIX-compliant systems, such as Linux and macOS.
+  */
+  return `'${pathArgument.replaceAll('\'', '\'\\\'\'')}'`;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PowerShellArgumentEscaper.ts

@@ -0,0 +1,15 @@
+import type { ShellArgumentEscaper } from './ShellArgumentEscaper';
+
+export class PowerShellArgumentEscaper implements ShellArgumentEscaper {
+  public escapePathArgument(pathArgument: string): string {
+    return powerShellPathArgumentEscape(pathArgument);
+  }
+}
+
+function powerShellPathArgumentEscape(pathArgument: string): string {
+  // - Encloses the path in single quotes to handle spaces and most special characters.
+  // - Single quotes are used in PowerShell to ensure the string is treated as a literal string.
+  // - Paths in Windows can include single quotes ('), so any internal single quotes are escaped
+  //   using double quotes.
+  return `'${pathArgument.replace(/'/g, "''")}'`;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaper.ts

@@ -0,0 +1,3 @@
+export interface ShellArgumentEscaper {
+  escapePathArgument(pathArgument: string): string;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/WindowsVisibleTerminalCommand.ts

@@ -0,0 +1,61 @@
+import type { Logger } from '@/application/Common/Log/Logger';
+import { ElectronLogger } from '@/infrastructure/Log/ElectronLogger';
+import { PowerShellArgumentEscaper } from './ShellArgument/PowerShellArgumentEscaper';
+import { EncodedPowerShellInvokeCmdCommandCreator } from './PowerShellInvoke/EncodedPowerShellInvokeCmdCommandCreator';
+import type { ShellArgumentEscaper } from './ShellArgument/ShellArgumentEscaper';
+import type { CommandDefinition } from '../CommandDefinition';
+import type { PowerShellInvokeShellCommandCreator } from './PowerShellInvoke/PowerShellInvokeShellCommandCreator';
+
+export class WindowsVisibleTerminalCommand implements CommandDefinition {
+  constructor(
+    private readonly escaper: ShellArgumentEscaper = new PowerShellArgumentEscaper(),
+    private readonly powershellCommandCreator: PowerShellInvokeShellCommandCreator
+    = new EncodedPowerShellInvokeCmdCommandCreator(),
+    private readonly logger: Logger = ElectronLogger,
+  ) { }
+
+  public buildShellCommand(filePath: string): string {
+    const powershellCommand = [
+      'Start-Process',
+      '-Verb RunAs', // Run as administrator with GUI sudo prompt
+      `-FilePath ${this.escaper.escapePathArgument(filePath)}`,
+    ].join(' ');
+    /*
+      Running PowerShell command is preferred due to its flexibility and the way it provides
+      GUI sudo prompt through `RunAs` argument.
+      Other options considered:
+        `child_process.execFile()`
+        "path", `cmd.exe /c "path"`
+          ❌  Script execution in the background without a visible terminal.
+              This occurs only when the user runs the application as administrator, as seen
+              in Windows Pro VMs on Azure.
+        `PowerShell Start -Verb RunAs "path"`
+          ✅  Visible terminal window
+          ✅  GUI sudo prompt (through `RunAs` option)
+        `PowerShell Start "path"`
+        `explorer.exe "path"`
+        `electron.shell.openPath`
+        `start cmd.exe /c "$path"`
+          ✅  Visible terminal window
+          ✅  GUI sudo prompt (through `RunAs` option)
+          👍  Among all options `start` command is the most explicit one, being the most resilient
+              against the potential changes in Windows or Electron framework (e.g. https://github.com/electron/electron/issues/36765).
+              `%COMSPEC%` environment variable should be checked before defaulting to `cmd.exe.
+      Related docs: https://web.archive.org/web/20240106002357/https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows
+    */
+    this.logger.info(`Building command for PowerShell execution:\n\tCommand: ${powershellCommand}`);
+    return this.powershellCommandCreator.createCommandToInvokePowerShell(powershellCommand);
+  }
+
+  public isExecutionTerminatedExternally(): boolean {
+    return false;
+  }
+
+  public isExecutablePermissionsRequiredOnFile(): boolean {
+    /*
+      In Windows, whether a file can be executed is determined by its file extension
+      (.exe, .bat, .cmd, etc.) rather than executable permissions set on the file.
+    */
+    return false;
+  }
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Factory/CommandDefinitionFactory.ts

@@ -0,0 +1,5 @@
+import type { CommandDefinition } from '../CommandDefinition';
+
+export interface CommandDefinitionFactory {
+  provideCommandDefinition(): CommandDefinition;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Factory/OsSpecificTerminalLaunchCommandFactory.ts

@@ -0,0 +1,40 @@
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import { CurrentEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironmentFactory';
+import type { RuntimeEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironment';
+import { WindowsVisibleTerminalCommand } from '../Commands/WindowsVisibleTerminalCommand';
+import { LinuxVisibleTerminalCommand } from '../Commands/LinuxVisibleTerminalCommand';
+import { MacOsVisibleTerminalCommand } from '../Commands/MacOsVisibleTerminalCommand';
+import type { CommandDefinitionFactory } from './CommandDefinitionFactory';
+import type { CommandDefinition } from '../CommandDefinition';
+
+export class OsSpecificTerminalLaunchCommandFactory implements CommandDefinitionFactory {
+  constructor(
+    private readonly environment: RuntimeEnvironment = CurrentEnvironment,
+  ) { }
+
+  public provideCommandDefinition(): CommandDefinition {
+    const { os } = this.environment;
+    if (os === undefined) {
+      throw new Error('Operating system could not be identified from environment.');
+    }
+    return getOperatingSystemCommandDefinition(os);
+  }
+}
+
+function getOperatingSystemCommandDefinition(
+  operatingSystem: OperatingSystem,
+): CommandDefinition {
+  const definition = SupportedDesktopCommandDefinitions[operatingSystem];
+  if (!definition) {
+    throw new Error(`Unsupported operating system: ${OperatingSystem[operatingSystem]}`);
+  }
+  return definition;
+}
+
+const SupportedDesktopCommandDefinitions: Readonly<Partial<Record<
+OperatingSystem,
+CommandDefinition>>> = {
+  [OperatingSystem.Windows]: new WindowsVisibleTerminalCommand(),
+  [OperatingSystem.Linux]: new LinuxVisibleTerminalCommand(),
+  [OperatingSystem.macOS]: new MacOsVisibleTerminalCommand(),
+} as const;

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/CommandDefinitionRunner.ts

@@ -0,0 +1,9 @@
+import type { ScriptFileExecutionOutcome } from '../../ScriptFileExecutor';
+import type { CommandDefinition } from '../CommandDefinition';
+
+export interface CommandDefinitionRunner {
+  runCommandDefinition(
+    commandDefinition: CommandDefinition,
+    filePath: string,
+  ): Promise<ScriptFileExecutionOutcome>;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ExecutableFileShellCommandDefinitionRunner.ts

@@ -0,0 +1,80 @@
+import type { CodeRunErrorType } from '@/application/CodeRunner/CodeRunner';
+import { FileSystemExecutablePermissionSetter } from './PermissionSetter/FileSystemExecutablePermissionSetter';
+import { LoggingNodeShellCommandRunner } from './ShellRunner/LoggingNodeShellCommandRunner';
+import type { FailedScriptFileExecution, ScriptFileExecutionOutcome } from '../../ScriptFileExecutor';
+import type { CommandDefinition } from '../CommandDefinition';
+import type { CommandDefinitionRunner } from './CommandDefinitionRunner';
+import type { ExecutablePermissionSetter } from './PermissionSetter/ExecutablePermissionSetter';
+import type { ShellCommandOutcome, ShellCommandRunner } from './ShellRunner/ShellCommandRunner';
+
+export class ExecutableFileShellCommandDefinitionRunner implements CommandDefinitionRunner {
+  constructor(
+    private readonly executablePermissionSetter: ExecutablePermissionSetter
+    = new FileSystemExecutablePermissionSetter(),
+    private readonly shellCommandRunner: ShellCommandRunner
+    = new LoggingNodeShellCommandRunner(),
+  ) { }
+
+  public async runCommandDefinition(
+    commandDefinition: CommandDefinition,
+    filePath: string,
+  ): Promise<ScriptFileExecutionOutcome> {
+    if (commandDefinition.isExecutablePermissionsRequiredOnFile()) {
+      const filePermissionsResult = await this.executablePermissionSetter
+        .makeFileExecutable(filePath);
+      if (!filePermissionsResult.success) {
+        return filePermissionsResult;
+      }
+    }
+    const command = commandDefinition.buildShellCommand(filePath);
+    const shellOutcome = await this.shellCommandRunner.runShellCommand(command);
+    return interpretShellOutcome(shellOutcome, commandDefinition);
+  }
+}
+
+function interpretShellOutcome(
+  outcome: ShellCommandOutcome,
+  commandDefinition: CommandDefinition,
+): ScriptFileExecutionOutcome {
+  switch (outcome.type) {
+    case 'RegularProcessExit':
+      if (outcome.exitCode === 0) {
+        return { success: true };
+      }
+      if (commandDefinition.isExecutionTerminatedExternally(outcome.exitCode)) {
+        return createFailureOutcome(
+          'ExternalProcessTermination',
+          `Process terminated externally: Exit code ${outcome.exitCode}.`,
+        );
+      }
+      return createFailureOutcome(
+        'FileExecutionError',
+        `Unexpected exit code: ${outcome.exitCode}.`,
+      );
+    case 'ExternallyTerminated':
+      return createFailureOutcome(
+        'ExternalProcessTermination',
+        `Process terminated by signal ${outcome.terminationSignal}.`,
+      );
+    case 'ExecutionError':
+      return createFailureOutcome(
+        'FileExecutionError',
+        `Execution error: ${outcome.error.message}.`,
+      );
+    default:
+      throw new Error(`Unknown outcome type: ${outcome}`);
+  }
+}
+
+function createFailureOutcome(
+  type: CodeRunErrorType,
+  errorMessage: string,
+): FailedScriptFileExecution {
+  return {
+    success: false,
+    error: {
+      type,
+      message: `Error during command execution: ${errorMessage}`,
+    },
+  };
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/PermissionSetter/ExecutablePermissionSetter.ts

@@ -0,0 +1,5 @@
+import type { ScriptFileExecutionOutcome } from '@/infrastructure/CodeRunner/Execution/ScriptFileExecutor';
+
+export interface ExecutablePermissionSetter {
+  makeFileExecutable(filePath: string): Promise<ScriptFileExecutionOutcome>;
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/PermissionSetter/FileSystemExecutablePermissionSetter.ts

@@ -0,0 +1,35 @@
+import { NodeElectronSystemOperations } from '@/infrastructure/CodeRunner/System/NodeElectronSystemOperations';
+import type { Logger } from '@/application/Common/Log/Logger';
+import { ElectronLogger } from '@/infrastructure/Log/ElectronLogger';
+import type { SystemOperations } from '@/infrastructure/CodeRunner/System/SystemOperations';
+import type { ScriptFileExecutionOutcome } from '@/infrastructure/CodeRunner/Execution/ScriptFileExecutor';
+import type { ExecutablePermissionSetter } from './ExecutablePermissionSetter';
+
+export class FileSystemExecutablePermissionSetter implements ExecutablePermissionSetter {
+  constructor(
+    private readonly system: SystemOperations = new NodeElectronSystemOperations(),
+    private readonly logger: Logger = ElectronLogger,
+  ) { }
+
+  public async makeFileExecutable(filePath: string): Promise<ScriptFileExecutionOutcome> {
+    /*
+      This is required on macOS and Linux otherwise the terminal emulators will refuse to
+      execute the script. It's not needed on Windows.
+    */
+    try {
+      this.logger.info(`Setting execution permissions for file at ${filePath}`);
+      await this.system.fileSystem.setFilePermissions(filePath, '755');
+      this.logger.info(`Execution permissions set successfully for ${filePath}`);
+      return { success: true };
+    } catch (error) {
+      this.logger.error(error);
+      return {
+        success: false,
+        error: {
+          type: 'FilePermissionChangeError',
+          message: `Error setting script file permission: ${error.message}`,
+        },
+      };
+    }
+  }
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ShellRunner/LoggingNodeShellCommandRunner.ts

@@ -0,0 +1,47 @@
+import type { Logger } from '@/application/Common/Log/Logger';
+import { ElectronLogger } from '@/infrastructure/Log/ElectronLogger';
+import type { SystemOperations } from '@/infrastructure/CodeRunner/System/SystemOperations';
+import { NodeElectronSystemOperations } from '@/infrastructure/CodeRunner/System/NodeElectronSystemOperations';
+import type { ShellCommandOutcome, ShellCommandRunner } from './ShellCommandRunner';
+
+export class LoggingNodeShellCommandRunner implements ShellCommandRunner {
+  constructor(
+    private readonly logger: Logger = ElectronLogger,
+    private readonly systemOps: SystemOperations = new NodeElectronSystemOperations(),
+  ) {
+  }
+
+  public runShellCommand(command: string): Promise<ShellCommandOutcome> {
+    this.logger.info(`Executing command: ${command}`);
+    return new Promise((resolve) => {
+      this.systemOps.command.exec(command)
+        // https://archive.today/2024.01.19-004011/https://nodejs.org/api/child_process.html#child_process_event_exit
+        .on('exit', (
+          code, // The exit code if the child exited on its own.
+          signal, // The signal by which the child process was terminated.
+        ) => {
+          // One of `code` or `signal` will always be non-null.
+          // If the process exited, code is the final exit code of the process, otherwise null.
+          if (code !== null) {
+            this.logger.info(`Command completed with exit code ${code}.`);
+            resolve({ type: 'RegularProcessExit', exitCode: code });
+            return; // Prevent further execution to avoid multiple promise resolutions and logs.
+          }
+          // If the process terminated due to receipt of a signal, signal is the string name of
+          // the signal, otherwise null.
+          resolve({ type: 'ExternallyTerminated', terminationSignal: signal as NodeJS.Signals });
+          this.logger.warn(`Command terminated by signal: ${signal}`);
+        })
+        .on('error', (error) => {
+          // https://archive.ph/20200912193803/https://nodejs.org/api/child_process.html#child_process_event_error
+          // The 'error' event is emitted whenever:
+          // - The process could not be spawned, or
+          // - The process could not be killed, or
+          // - Sending a message to the child process failed.
+          // The 'exit' event may or may not fire after an error has occurred.
+          this.logger.error('Command execution failed:', error);
+          resolve({ type: 'ExecutionError', error });
+        });
+    });
+  }
+}

src/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ShellRunner/ShellCommandRunner.ts

@@ -0,0 +1,23 @@
+export interface ShellCommandRunner {
+  runShellCommand(command: string): Promise<ShellCommandOutcome>;
+}
+
+export type ShellCommandOutcome = ProcessStatus & ({
+  readonly type: 'RegularProcessExit',
+  readonly exitCode: number;
+} | {
+  readonly type: 'ExternallyTerminated';
+  readonly terminationSignal: NodeJS.Signals;
+} | {
+  readonly type: 'ExecutionError';
+  readonly error: Error;
+});
+
+type ProcessOutcomeType = 'RegularProcessExit' | 'ExternallyTerminated' | 'ExecutionError';
+
+interface ProcessStatus {
+  readonly type: ProcessOutcomeType;
+  readonly error?: Error;
+  readonly terminationSignal?: NodeJS.Signals;
+  readonly exitCode?: number;
+}

src/infrastructure/CodeRunner/Execution/VisibleTerminalFileRunner.ts

@@ -0,0 +1,71 @@
+import type { Logger } from '@/application/Common/Log/Logger';
+import { ElectronLogger } from '@/infrastructure/Log/ElectronLogger';
+import { OsSpecificTerminalLaunchCommandFactory } from './CommandDefinition/Factory/OsSpecificTerminalLaunchCommandFactory';
+import { ExecutableFileShellCommandDefinitionRunner } from './CommandDefinition/Runner/ExecutableFileShellCommandDefinitionRunner';
+import type { ScriptFileExecutionOutcome, ScriptFileExecutor } from './ScriptFileExecutor';
+import type { CommandDefinitionFactory } from './CommandDefinition/Factory/CommandDefinitionFactory';
+import type { CommandDefinitionRunner } from './CommandDefinition/Runner/CommandDefinitionRunner';
+import type { CommandDefinition } from './CommandDefinition/CommandDefinition';
+
+export class VisibleTerminalFileRunner implements ScriptFileExecutor {
+  constructor(
+    private readonly logger: Logger = ElectronLogger,
+    private readonly commandFactory: CommandDefinitionFactory
+    = new OsSpecificTerminalLaunchCommandFactory(),
+    private readonly commandRunner: CommandDefinitionRunner
+    = new ExecutableFileShellCommandDefinitionRunner(),
+  ) { }
+
+  public async executeScriptFile(
+    filePath: string,
+  ): Promise<ScriptFileExecutionOutcome> {
+    this.logger.info(`Executing script file: ${filePath}.`);
+    const outcome = await this.findAndExecuteCommand(filePath);
+    this.logOutcome(outcome);
+    return outcome;
+  }
+
+  private async findAndExecuteCommand(
+    filePath: string,
+  ): Promise<ScriptFileExecutionOutcome> {
+    try {
+      let commandDefinition: CommandDefinition;
+      try {
+        commandDefinition = this.commandFactory.provideCommandDefinition();
+      } catch (error) {
+        return {
+          success: false,
+          error: {
+            type: 'UnsupportedPlatform',
+            message: `Error finding command: ${error.message}`,
+          },
+        };
+      }
+      const runOutcome = await this.commandRunner.runCommandDefinition(
+        commandDefinition,
+        filePath,
+      );
+      return runOutcome;
+    } catch (error) {
+      return {
+        success: false,
+        error: {
+          type: 'FileExecutionError',
+          message: `Unexpected error: ${error.message}`,
+        },
+      };
+    }
+  }
+
+  private logOutcome(outcome: ScriptFileExecutionOutcome) {
+    if (outcome.success) {
+      this.logger.info('Executed script file in terminal successfully.');
+      return;
+    }
+    this.logger.error(
+      'Failed to execute the script file in terminal.',
+      outcome.error.type,
+      outcome.error.message,
+    );
+  }
+}

src/infrastructure/CodeRunner/Execution/VisibleTerminalScriptFileExecutor.ts

@@ -1,214 +0,0 @@
-import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { CommandOps, SystemOperations } from '@/infrastructure/CodeRunner/System/SystemOperations';
-import type { Logger } from '@/application/Common/Log/Logger';
-import { ElectronLogger } from '@/infrastructure/Log/ElectronLogger';
-import type { RuntimeEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironment';
-import { NodeElectronSystemOperations } from '@/infrastructure/CodeRunner/System/NodeElectronSystemOperations';
-import { CurrentEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironmentFactory';
-import type { CodeRunErrorType } from '@/application/CodeRunner/CodeRunner';
-import { isString } from '@/TypeHelpers';
-import type { FailedScriptFileExecution, ScriptFileExecutionOutcome, ScriptFileExecutor } from './ScriptFileExecutor';
-
-export class VisibleTerminalScriptExecutor implements ScriptFileExecutor {
-  constructor(
-    private readonly system: SystemOperations = new NodeElectronSystemOperations(),
-    private readonly logger: Logger = ElectronLogger,
-    private readonly environment: RuntimeEnvironment = CurrentEnvironment,
-  ) { }
-
-  public async executeScriptFile(filePath: string): Promise<ScriptFileExecutionOutcome> {
-    const { os } = this.environment;
-    if (os === undefined) {
-      return this.handleError('UnsupportedOperatingSystem', 'Operating system could not be identified from environment.');
-    }
-    const filePermissionsResult = await this.setFileExecutablePermissions(filePath);
-    if (!filePermissionsResult.success) {
-      return filePermissionsResult;
-    }
-    const scriptExecutionResult = await this.runFileWithRunner(filePath, os);
-    if (!scriptExecutionResult.success) {
-      return scriptExecutionResult;
-    }
-    return {
-      success: true,
-    };
-  }
-
-  private async setFileExecutablePermissions(
-    filePath: string,
-  ): Promise<ScriptFileExecutionOutcome> {
-    /*
-      This is required on macOS and Linux otherwise the terminal emulators will refuse to
-      execute the script. It's not needed on Windows.
-    */
-    try {
-      this.logger.info(`Setting execution permissions for file at ${filePath}`);
-      await this.system.fileSystem.setFilePermissions(filePath, '755');
-      this.logger.info(`Execution permissions set successfully for ${filePath}`);
-      return { success: true };
-    } catch (error) {
-      return this.handleError('FileExecutionError', error);
-    }
-  }
-
-  private async runFileWithRunner(
-    filePath: string,
-    os: OperatingSystem,
-  ): Promise<ScriptFileExecutionOutcome> {
-    this.logger.info(`Executing script file: ${filePath} on ${OperatingSystem[os]}.`);
-    const runner = TerminalRunners[os];
-    if (!runner) {
-      return this.handleError('UnsupportedOperatingSystem', `Unsupported operating system: ${OperatingSystem[os]}`);
-    }
-    const context: TerminalExecutionContext = {
-      scriptFilePath: filePath,
-      commandOps: this.system.command,
-      logger: this.logger,
-    };
-    try {
-      await runner(context);
-      this.logger.info('Command script file successfully.');
-      return { success: true };
-    } catch (error) {
-      return this.handleError('FileExecutionError', error);
-    }
-  }
-
-  private handleError(
-    type: CodeRunErrorType,
-    error: Error | string,
-  ): FailedScriptFileExecution {
-    const errorMessage = 'Error during script file execution';
-    this.logger.error([type, errorMessage, ...(error ? [error] : [])]);
-    return {
-      success: false,
-      error: {
-        type,
-        message: `${errorMessage}: ${isString(error) ? error : errorMessage}`,
-      },
-    };
-  }
-}
-
-interface TerminalExecutionContext {
-  readonly scriptFilePath: string;
-  readonly commandOps: CommandOps;
-  readonly logger: Logger;
-}
-
-type TerminalRunner = (context: TerminalExecutionContext) => Promise<void>;
-
-export const LinuxTerminalEmulator = 'x-terminal-emulator';
-
-const TerminalRunners: Partial<Record<OperatingSystem, TerminalRunner>> = {
-  [OperatingSystem.Windows]: async (context) => {
-    const command = [
-      'PowerShell',
-      'Start-Process',
-      '-Verb RunAs', // Run as administrator with GUI sudo prompt
-      `-FilePath ${cmdShellPathArgumentEscape(context.scriptFilePath)}`,
-    ].join(' ');
-    /*
-      📝 Options:
-        `child_process.execFile()`
-        "path", `cmd.exe /c "path"`
-          ❌  Script execution in the background without a visible terminal.
-              This occurs only when the user runs the application as administrator, as seen
-              in Windows Pro VMs on Azure.
-        `PowerShell Start -Verb RunAs "path"`
-          ✅  Visible terminal window
-          ✅  GUI sudo prompt (through `RunAs` option)
-        `PowerShell Start "path"`
-        `explorer.exe "path"`
-        `electron.shell.openPath`
-        `start cmd.exe /c "$path"`
-          ✅  Visible terminal window
-          ✅  GUI sudo prompt (through `RunAs` option)
-          👍  Among all options `start` command is the most explicit one, being the most resilient
-              against the potential changes in Windows or Electron framework (e.g. https://github.com/electron/electron/issues/36765).
-              `%COMSPEC%` environment variable should be checked before defaulting to `cmd.exe.
-      Related docs: https://web.archive.org/web/20240106002357/https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows
-    */
-    await runCommand(command, context);
-  },
-  [OperatingSystem.Linux]: async (context) => {
-    const command = `${LinuxTerminalEmulator} -e ${posixShellPathArgumentEscape(context.scriptFilePath)}`;
-    /*
-      🤔 Potential improvements:
-          Use user-friendly GUI sudo prompt (not terminal-based).
-          If `pkexec` exists, we could do `x-terminal-emulator -e pkexec 'path'`, which always
-          prompts with user-friendly GUI sudo prompt.
-      📝 Options:
-        `x-terminal-emulator -e 'path'`:
-            ✅  Visible terminal window
-            ❌  Terminal-based (not GUI) sudo prompt.
-        `x-terminal-emulator -e pkexec 'path'
-          ✅  Visible terminal window
-          ✅  Always prompts with user-friendly GUI sudo prompt.
-          🤔  Not using `pkexec` as it is not in all Linux distributions. It should have smarter
-              logic to handle if it does not exist.
-        `electron.shell.openPath`:
-          ❌  Opens the script in the default text editor, verified on
-              Debian/Ubuntu-based distributions.
-        `child_process.execFile()`:
-          ❌  Script execution in the background without a visible terminal.
-    */
-    await runCommand(command, context);
-  },
-  [OperatingSystem.macOS]: async (context) => {
-    const command = `open -a Terminal.app ${posixShellPathArgumentEscape(context.scriptFilePath)}`;
-    // -a Specifies the application to use for opening the file
-    /* eslint-disable vue/max-len */
-    /*
-      🤔 Potential improvements:
-        Use user-friendly GUI sudo prompt for running the script.
-      📝 Options:
-        `open -a Terminal.app 'path'`
-          ✅  Visible terminal window
-          ❌  Terminal-based (not GUI) sudo prompt.
-          ❌  Terminal app requires many privileges to execute the script, this prompts user
-              to grant privileges to the Terminal app.
-        `osascript -e 'do shell script "'/tmp/test.sh'" with administrator privileges'`
-          ✅  Script as root
-          ✅  GUI sudo prompt.
-          ❌  Script execution in the background without a visible terminal.
-        `osascript -e 'do shell script "open -a 'Terminal.app' '/tmp/test.sh'" with administrator privileges'`
-          ❌  Script as user, not root
-          ✅  GUI sudo prompt.
-          ✅  Visible terminal window
-        `osascript -e 'do shell script "/System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal '/tmp/test.sh'" with administrator privileges'`
-          ✅  Script as root
-          ✅  GUI sudo prompt.
-          ✅  Visible terminal window
-        Useful resources about `do shell script .. with administrator privileges`:
-          - Change "osascript wants to make changes" prompt: https://web.archive.org/web/20240109191128/https://apple.stackexchange.com/questions/283353/how-to-rename-osascript-in-the-administrator-privileges-dialog
-          - More about `do shell script`: https://web.archive.org/web/20100906222226/http://developer.apple.com/mac/library/technotes/tn2002/tn2065.html
-    */
-    /* eslint-enable vue/max-len */
-    await runCommand(command, context);
-  },
-} as const;
-
-async function runCommand(command: string, context: TerminalExecutionContext): Promise<void> {
-  context.logger.info(`Executing command:\n${command}`);
-  await context.commandOps.exec(command);
-  context.logger.info('Executed command successfully.');
-}
-
-function posixShellPathArgumentEscape(pathArgument: string): string {
-  /*
-    - Wraps the path in single quotes, which is a standard practice in POSIX shells
-      (like bash and zsh) found on macOS/Linux to ensure that characters like spaces, '*', and
-      '?' are treated as literals, not as special characters.
-    - Escapes any single quotes within the path itself. This allows paths containing single
-      quotes to be correctly interpreted in POSIX-compliant systems, such as Linux and macOS.
-  */
-  return `'${pathArgument.replaceAll('\'', '\'\\\'\'')}'`;
-}
-
-function cmdShellPathArgumentEscape(pathArgument: string): string {
-  // - Encloses the path in double quotes, which is necessary for Windows command line (cmd.exe)
-  //   to correctly handle paths containing spaces.
-  // - Paths in Windows cannot include double quotes `"` themselves, so these are not escaped.
-  return `"${pathArgument}"`;
-}

src/infrastructure/CodeRunner/ScriptFileCodeRunner.ts

@@ -4,15 +4,15 @@ import type {
   CodeRunError, CodeRunOutcome, CodeRunner, FailedCodeRun,
 } from '@/application/CodeRunner/CodeRunner';
 import { ElectronLogger } from '../Log/ElectronLogger';
-import { VisibleTerminalScriptExecutor } from './Execution/VisibleTerminalScriptFileExecutor';
 import { ScriptFileCreationOrchestrator } from './Creation/ScriptFileCreationOrchestrator';
+import { VisibleTerminalFileRunner } from './Execution/VisibleTerminalFileRunner';
 import type { ScriptFileExecutor } from './Execution/ScriptFileExecutor';
 import type { ScriptFileCreator } from './Creation/ScriptFileCreator';
 
 export class ScriptFileCodeRunner implements CodeRunner {
   constructor(
     private readonly scriptFileExecutor
-    : ScriptFileExecutor = new VisibleTerminalScriptExecutor(),
+    : ScriptFileExecutor = new VisibleTerminalFileRunner(),
     private readonly scriptFileCreator: ScriptFileCreator = new ScriptFileCreationOrchestrator(),
     private readonly logger: Logger = ElectronLogger,
   ) { }

src/infrastructure/CodeRunner/System/NodeElectronSystemOperations.ts

@@ -6,6 +6,9 @@ import type {
   CommandOps, FileSystemOps, LocationOps, OperatingSystemOps, SystemOperations,
 } from './SystemOperations';
 
+/**
+ * Thin wrapper for Node and Electron APIs.
+ */
 export class NodeElectronSystemOperations implements SystemOperations {
   public readonly operatingSystem: OperatingSystemOps = {
     /*
@@ -49,13 +52,6 @@ export class NodeElectronSystemOperations implements SystemOperations {
   };
 
   public readonly command: CommandOps = {
-    exec: (command) => new Promise((resolve, reject) => {
+    exec,
-      exec(command, (error) => {
-        if (error) {
-          reject(error);
-        }
-        resolve();
-      });
-    }),
   };
 }

src/infrastructure/CodeRunner/System/SystemOperations.ts

@@ -1,3 +1,5 @@
+import type { exec } from 'node:child_process';
+
 export interface SystemOperations {
   readonly operatingSystem: OperatingSystemOps;
   readonly location: LocationOps;
@@ -14,7 +16,7 @@ export interface LocationOps {
 }
 
 export interface CommandOps {
-  exec(command: string): Promise<void>;
+  exec(command: string): ReturnType<typeof exec>;
 }
 
 export interface FileSystemOps {

src/presentation/assets/styles/base/_index.scss

@@ -13,11 +13,16 @@
 @use "_code-styling" as *;
 @use "_margin-padding" as *;
 @use "_link-styling" as *;
+@use "_prevent-scrollbar-layout-shift" as *;
 
 * {
   box-sizing: border-box;
 }
 
+html {
+  @include prevent-scrollbar-layout-shift;
+}
+
 body {
   background: $color-background;
   @include base-font-style;

src/presentation/assets/styles/base/_prevent-scrollbar-layout-shift.scss

@@ -0,0 +1,19 @@
+// This mixin prevents layout shifts caused by the appearance of a vertical scrollbar
+// in Chromium-based browsers on Linux and Windows.
+// It creates a reserved space for the scrollbar, ensuring content remains stable and does
+// not shift horizontally when the scrollbar appears.
+@mixin prevent-scrollbar-layout-shift {
+  scrollbar-gutter: stable;
+
+  @supports not (scrollbar-gutter: stable) { // https://caniuse.com/mdn-css_properties_scrollbar-gutter
+    // Safari workaround: Shift content to accommodate non-overlay scrollbar.
+    // An issue: On small screens, the appearance of the scrollbar can shift content, due to limited space for
+    // both content and scrollbar.
+    $full-width-including-scrollbar: 100vw;
+    $full-width-excluding-scrollbar: 100%;
+    $scrollbar-width: calc($full-width-including-scrollbar - $full-width-excluding-scrollbar);
+    padding-inline-start: $scrollbar-width; // Allows both right-to-left (RTL) and left-to-right (LTR) text direction support
+  }
+
+  // More details: https://web.archive.org/web/20240509122237/https://stackoverflow.com/questions/1417934/how-to-prevent-scrollbar-from-repositioning-web-page
+}

src/presentation/bootstrapping/DependencyProvider.ts

@@ -16,6 +16,7 @@ import { useCodeRunner } from '@/presentation/components/Shared/Hooks/UseCodeRun
 import { CurrentEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironmentFactory';
 import { useDialog } from '@/presentation/components/Shared/Hooks/Dialog/UseDialog';
 import { useScriptDiagnosticsCollector } from '@/presentation/components/Shared/Hooks/UseScriptDiagnosticsCollector';
+import { useAutoUnsubscribedEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
 
 export function provideDependencies(
   context: IApplicationContext,
@@ -77,6 +78,10 @@ export function provideDependencies(
       InjectionKeys.useScriptDiagnosticsCollector,
       useScriptDiagnosticsCollector,
     ),
+    useAutoUnsubscribedEventListener: (di) => di.provide(
+      InjectionKeys.useAutoUnsubscribedEventListener,
+      useAutoUnsubscribedEventListener,
+    ),
   };
   registerAll(Object.values(resolvers), api);
 }

src/presentation/components/Code/CodeButtons/CodeRunButton.vue

@@ -11,6 +11,7 @@
 import { defineComponent, computed } from 'vue';
 import { injectKey } from '@/presentation/injectionSymbols';
 import { OperatingSystem } from '@/domain/OperatingSystem';
+import type { CodeRunError } from '@/application/CodeRunner/CodeRunner';
 import IconButton from './IconButton.vue';
 import { createScriptErrorDialog } from './ScriptErrorDialog';
 
@@ -38,15 +39,19 @@ export default defineComponent({
         currentContext.state.collection.scripting.fileExtension,
       );
       if (!success) {
-        dialog.showError(...(await createScriptErrorDialog({
+        await handleCodeRunFailure(error);
-          errorContext: 'run',
-          errorType: error.type,
-          errorMessage: error.message,
-          isFileReadbackError: error.type === 'FileReadbackVerificationError',
-        }, scriptDiagnosticsCollector)));
       }
     }
 
+    async function handleCodeRunFailure(error: CodeRunError) {
+      dialog.showError(...(await createScriptErrorDialog({
+        errorContext: 'run',
+        errorType: error.type,
+        errorMessage: error.message,
+        isFileReadbackError: error.type === 'FileReadbackVerificationError',
+      }, scriptDiagnosticsCollector)));
+    }
+
     return {
       canRun,
       runCode,

src/presentation/components/Code/CodeButtons/ScriptErrorDialog.ts

@@ -1,21 +1,28 @@
+import type { CodeRunErrorType } from '@/application/CodeRunner/CodeRunner';
 import type { ScriptDiagnosticData, ScriptDiagnosticsCollector } from '@/application/ScriptDiagnostics/ScriptDiagnosticsCollector';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import type { Dialog } from '@/presentation/common/Dialog';
+import type { Dialog, SaveFileErrorType } from '@/presentation/common/Dialog';
+
+type ErrorDialogParameters = Parameters<Dialog['showError']>;
 
 export async function createScriptErrorDialog(
   information: ScriptErrorDetails,
   scriptDiagnosticsCollector: ScriptDiagnosticsCollector | undefined,
-): Promise<Parameters<Dialog['showError']>> {
+): Promise<ErrorDialogParameters> {
   const diagnostics = await scriptDiagnosticsCollector?.collectDiagnosticInformation();
   if (information.isFileReadbackError) {
     return createAntivirusErrorDialog(information, diagnostics);
   }
+  if (information.errorContext === 'run'
+    && information.errorType === 'ExternalProcessTermination') {
+    return createScriptInterruptedDialog(information);
+  }
   return createGenericErrorDialog(information, diagnostics);
 }
 
 export interface ScriptErrorDetails {
   readonly errorContext: 'run' | 'save';
-  readonly errorType: string;
+  readonly errorType: CodeRunErrorType | SaveFileErrorType;
   readonly errorMessage: string;
   readonly isFileReadbackError: boolean;
 }
@@ -23,7 +30,7 @@ export interface ScriptErrorDetails {
 function createGenericErrorDialog(
   information: ScriptErrorDetails,
   diagnostics: ScriptDiagnosticData | undefined,
-): Parameters<Dialog['showError']> {
+): ErrorDialogParameters {
   return [
     selectBasedOnErrorContext({
       runningScript: 'Error Running Script',
@@ -66,7 +73,7 @@ function createGenericErrorDialog(
 function createAntivirusErrorDialog(
   information: ScriptErrorDetails,
   diagnostics: ScriptDiagnosticData | undefined,
-): Parameters<Dialog['showError']> {
+): ErrorDialogParameters {
   const defenderSteps = generateDefenderSteps(information, diagnostics);
   return [
     'Possible Antivirus Script Block',
@@ -117,6 +124,33 @@ function createAntivirusErrorDialog(
   ];
 }
 
+function createScriptInterruptedDialog(
+  information: ScriptErrorDetails,
+): ErrorDialogParameters {
+  return [
+    'Script Stopped',
+    [
+      'The script stopped before it could finish.',
+      'This happens if the script is cancelled manually or if the system terminates the process.',
+      '\n',
+      generateUnorderedSolutionList({
+        title: 'To ensure successful script completion:',
+        solutions: [
+          'Keep the terminal window open during script execution.',
+          'If the script closed unexpectedly, try running it again.',
+          'Check for sufficient memory (RAM) and system resources.',
+          'Avoid running tasks that might disrupt the script.',
+        ],
+      }),
+      '\n',
+      'If you intentionally stopped the script, ignore this message.',
+      'Reach out to the community for further assistance.',
+      '\n',
+      generateTechnicalDetails(information),
+    ].join('\n'),
+  ];
+}
+
 interface SolutionListOptions {
   readonly solutions: readonly string[];
   readonly title: string;

src/presentation/components/DevToolkit/DevToolkit.vue

@@ -31,6 +31,7 @@ import { defineComponent, ref } from 'vue';
 import { injectKey } from '@/presentation/injectionSymbols';
 import FlatButton from '@/presentation/components/Shared/FlatButton.vue';
 import { dumpNames } from './DumpNames';
+import { useScrollbarGutterWidth } from './UseScrollbarGutterWidth';
 
 export default defineComponent({
   components: {
@@ -39,6 +40,7 @@ export default defineComponent({
   setup() {
     const { log } = injectKey((keys) => keys.useLogger);
     const isOpen = ref(true);
+    const scrollbarGutterWidth = useScrollbarGutterWidth();
 
     const devActions: readonly DevAction[] = [
       {
@@ -58,6 +60,7 @@ export default defineComponent({
       devActions,
       isOpen,
       close,
+      scrollbarGutterWidth,
     };
   },
 });
@@ -71,10 +74,14 @@ interface DevAction {
 <style scoped lang="scss">
 @use "@/presentation/assets/styles/main" as *;
 
+$viewport-edge-offset: $spacing-absolute-large; // close to Chromium gutter width (15px)
+
 .dev-toolkit-container {
   position: fixed;
-  top: 0;
+
-  right: 0;
+  top: $viewport-edge-offset;
+  right: max(v-bind(scrollbarGutterWidth), $viewport-edge-offset);
+
   background-color: rgba($color-on-surface, 0.5);
   color: $color-on-primary;
   padding: $spacing-absolute-medium;

src/presentation/components/DevToolkit/UseScrollbarGutterWidth.ts

@@ -0,0 +1,39 @@
+import {
+  computed, readonly, ref, watch,
+} from 'vue';
+import { throttle } from '@/application/Common/Timing/Throttle';
+import { useAutoUnsubscribedEventListener } from '../Shared/Hooks/UseAutoUnsubscribedEventListener';
+
+const RESIZE_EVENT_THROTTLE_MS = 200;
+
+export function useScrollbarGutterWidth() {
+  const scrollbarWidthInPx = ref(getScrollbarGutterWidth());
+
+  const { startListening } = useAutoUnsubscribedEventListener();
+  startListening(window, 'resize', throttle(() => {
+    scrollbarWidthInPx.value = getScrollbarGutterWidth();
+  }, RESIZE_EVENT_THROTTLE_MS));
+
+  const bodyWidth = useBodyWidth();
+  watch(() => bodyWidth.value, () => {
+    scrollbarWidthInPx.value = getScrollbarGutterWidth();
+  }, { immediate: false });
+
+  const scrollbarWidthStyle = computed(() => `${scrollbarWidthInPx.value}px`);
+  return readonly(scrollbarWidthStyle);
+}
+
+function getScrollbarGutterWidth(): number {
+  return document.documentElement.clientWidth - document.documentElement.offsetWidth;
+}
+
+function useBodyWidth() {
+  const width = ref(document.body.offsetWidth);
+  const observer = new ResizeObserver((entries) => throttle(() => {
+    for (const entry of entries) {
+      width.value = entry.borderBoxSize[0].inlineSize;
+    }
+  }, RESIZE_EVENT_THROTTLE_MS));
+  observer.observe(document.body, { box: 'border-box' });
+  return readonly(width);
+}

src/presentation/components/Scripts/View/Cards/CardList.vue

@@ -40,7 +40,7 @@
 
 <script lang="ts">
 import {
-  defineComponent, ref, onMounted, onUnmounted, computed,
+  defineComponent, ref, computed,
 } from 'vue';
 import { injectKey } from '@/presentation/injectionSymbols';
 import SizeObserver from '@/presentation/components/Shared/SizeObserver.vue';
@@ -54,6 +54,7 @@ export default defineComponent({
   },
   setup() {
     const { currentState, onStateChange } = injectKey((keys) => keys.useCollectionState);
+    const { startListening } = injectKey((keys) => keys.useAutoUnsubscribedEventListener);
 
     const width = ref<number | undefined>();
 
@@ -70,7 +71,7 @@ export default defineComponent({
       collapseAllCards();
     }, { immediate: true });
 
-    const outsideClickListener = (event: PointerEvent): void => {
+    startListening(document, 'click', (event) => {
       if (areAllCardsCollapsed()) {
         return;
       }
@@ -79,14 +80,6 @@ export default defineComponent({
       if (element && !element.contains(target)) {
         onOutsideOfActiveCardClicked(target);
       }
-    };
-
-    onMounted(() => {
-      document.addEventListener('click', outsideClickListener);
-    });
-
-    onUnmounted(() => {
-      document.removeEventListener('click', outsideClickListener);
     });
 
     function onOutsideOfActiveCardClicked(clickedElement: Element): void {

src/presentation/components/Scripts/View/Tree/TreeView/Node/UseKeyboardInteractionState.ts

@@ -1,6 +1,11 @@
-import { ref, onMounted, onUnmounted } from 'vue';
+import { ref } from 'vue';
+import { useAutoUnsubscribedEventListener, type UseEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
 
-export function useKeyboardInteractionState(window: WindowWithEventListeners = globalThis.window) {
+export function useKeyboardInteractionState(
+  eventTarget: EventTarget = DefaultEventSource,
+  useEventListener: UseEventListener = useAutoUnsubscribedEventListener,
+) {
+  const { startListening } = useEventListener();
   const isKeyboardBeingUsed = ref(false);
 
   const enableKeyboardFocus = () => {
@@ -17,20 +22,10 @@ export function useKeyboardInteractionState(window: WindowWithEventListeners = g
     isKeyboardBeingUsed.value = false;
   };
 
-  onMounted(() => {
+  startListening(eventTarget, 'keydown', enableKeyboardFocus);
-    window.addEventListener('keydown', enableKeyboardFocus, true);
+  startListening(eventTarget, 'click', disableKeyboardFocus);
-    window.addEventListener('click', disableKeyboardFocus, true);
-  });
-
-  onUnmounted(() => {
-    window.removeEventListener('keydown', enableKeyboardFocus);
-    window.removeEventListener('click', disableKeyboardFocus);
-  });
 
   return { isKeyboardBeingUsed };
 }
 
-export interface WindowWithEventListeners {
+export const DefaultEventSource = document;
-  addEventListener: typeof global.window.addEventListener;
-  removeEventListener: typeof global.window.removeEventListener;
-}

src/presentation/components/Scripts/View/Tree/TreeView/UseTreeKeyboardNavigation.ts

@@ -1,4 +1,5 @@
-import { onMounted, onUnmounted, type Ref } from 'vue';
+import { type Ref } from 'vue';
+import { useAutoUnsubscribedEventListener, type UseEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
 import { TreeNodeCheckState } from './Node/State/CheckState';
 import type { TreeNode } from './Node/TreeNode';
 import type { TreeRoot } from './TreeRoot/TreeRoot';
@@ -10,8 +11,10 @@ type TreeNavigationKeyCodes = 'ArrowLeft' | 'ArrowUp' | 'ArrowRight' | 'ArrowDow
 export function useTreeKeyboardNavigation(
   treeRootRef: Readonly<Ref<TreeRoot>>,
   treeElementRef: Readonly<Ref<HTMLElement | undefined>>,
+  useEventListener: UseEventListener = useAutoUnsubscribedEventListener,
 ) {
-  useKeyboardListener(treeElementRef, (event) => {
+  const { startListening } = useEventListener();
+  startListening(treeElementRef, 'keydown', (event) => {
     if (!treeElementRef.value) {
       return; // Not yet initialized?
     }
@@ -40,19 +43,6 @@ export function useTreeKeyboardNavigation(
   });
 }
 
-function useKeyboardListener(
-  elementRef: Readonly<Ref<HTMLElement | undefined>>,
-  handleKeyboardEvent: (event: KeyboardEvent) => void,
-) {
-  onMounted(() => {
-    elementRef.value?.addEventListener('keydown', handleKeyboardEvent, true);
-  });
-
-  onUnmounted(() => {
-    elementRef.value?.removeEventListener('keydown', handleKeyboardEvent);
-  });
-}
-
 interface TreeNavigationContext {
   readonly focus: SingleNodeFocusManager;
   readonly nodes: QueryableNodes;

src/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener.ts

@@ -0,0 +1,79 @@
+import {
+  onBeforeUnmount,
+  shallowRef,
+  watch,
+  type Ref,
+} from 'vue';
+
+export interface UseEventListener {
+  (): TargetEventListener;
+}
+
+export const useAutoUnsubscribedEventListener: UseEventListener = () => ({
+  startListening: (eventTargetSource, eventType, eventHandler) => {
+    const eventTargetRef = isEventTarget(eventTargetSource)
+      ? shallowRef(eventTargetSource)
+      : eventTargetSource;
+    return startListeningRef(
+      eventTargetRef,
+      eventType,
+      eventHandler,
+    );
+  },
+});
+
+type EventTargetRef = Readonly<Ref<EventTarget | undefined>>;
+
+type EventTargetOrRef = EventTargetRef | EventTarget;
+
+function isEventTarget(obj: EventTargetOrRef): obj is EventTarget {
+  return obj instanceof EventTarget;
+}
+
+export interface TargetEventListener {
+  startListening<TEvent extends keyof HTMLElementEventMap>(
+    eventTargetSource: EventTargetOrRef,
+    eventType: TEvent,
+    eventHandler: (event: HTMLElementEventMap[TEvent]) => void,
+  ): void;
+}
+
+function startListeningRef<TEvent extends keyof HTMLElementEventMap>(
+  eventTargetRef: Readonly<Ref<EventTarget | undefined>>,
+  eventType: TEvent,
+  eventHandler: (event: HTMLElementEventMap[TEvent]) => void,
+): void {
+  const eventListenerManager = new EventListenerManager();
+  watch(() => eventTargetRef.value, (element) => {
+    eventListenerManager.removeListenerIfExists();
+    if (!element) {
+      return;
+    }
+    eventListenerManager.addListener(element, eventType, eventHandler);
+  }, { immediate: true });
+
+  onBeforeUnmount(() => {
+    eventListenerManager.removeListenerIfExists();
+  });
+}
+
+class EventListenerManager {
+  private removeListener: (() => void) | null = null;
+
+  public removeListenerIfExists() {
+    if (this.removeListener === null) {
+      return;
+    }
+    this.removeListener();
+    this.removeListener = null;
+  }
+
+  public addListener<TEvent extends keyof HTMLElementEventMap>(
+    eventTarget: EventTarget,
+    eventType: TEvent,
+    eventHandler: (event: HTMLElementEventMap[TEvent]) => void,
+  ) {
+    eventTarget.addEventListener(eventType, eventHandler);
+    this.removeListener = () => eventTarget.removeEventListener(eventType, eventHandler);
+  }
+}

src/presentation/components/Shared/Modal/Hooks/ScrollLock/ScrollDomStateAccessor.ts

@@ -16,4 +16,6 @@ export interface ScrollDomStateAccessor {
   readonly htmlScrollHeight: number;
   readonly htmlClientWidth: number;
   readonly htmlClientHeight: number;
+  readonly htmlOffsetWidth: number;
+  readonly htmlOffsetHeight: number;
 }

src/presentation/components/Shared/Modal/Hooks/ScrollLock/UseLockBodyBackgroundScroll.ts

@@ -103,7 +103,6 @@ const BodyStyleLeft: DomPropertyMutator<{
   storeInitialState: (dom) => ({
     htmlScrollLeft: dom.htmlScrollLeft,
     bodyStyleLeft: dom.bodyStyleLeft,
-    bodyMarginLeft: dom.bodyComputedMarginLeft,
   }),
   onBlock: (initialState, dom) => {
     if (initialState.htmlScrollLeft === 0) {
@@ -206,13 +205,21 @@ const BodyPositionFixed: DomPropertyMutator<{
 
 const BodyWidth100Percent: DomPropertyMutator<{
   readonly bodyStyleWidth: string;
+  readonly htmlOffsetWidth: number;
+  readonly htmlClientWidth: number;
 }> = {
   storeInitialState: (dom) => ({
     bodyStyleWidth: dom.bodyStyleWidth,
+    htmlOffsetWidth: dom.htmlOffsetWidth,
+    htmlClientWidth: dom.htmlClientWidth,
   }),
-  onBlock: (_, dom) => {
+  onBlock: (initialState, dom) => {
-    dom.bodyStyleWidth = calculateBodyViewportStyleWithMargins(
+    dom.bodyStyleWidth = calculateAdjustedStyle(
-      [dom.bodyComputedMarginLeft, dom.bodyComputedMarginRight],
+      [
+        dom.bodyComputedMarginLeft,
+        dom.bodyComputedMarginRight,
+        calculateScrollbarGutterStyle(initialState.htmlClientWidth, initialState.htmlOffsetWidth),
+      ],
     );
     return ScrollRevertAction.RestoreRequired;
   },
@@ -223,13 +230,21 @@ const BodyWidth100Percent: DomPropertyMutator<{
 
 const BodyHeight100Percent: DomPropertyMutator<{
   readonly bodyStyleHeight: string;
+  readonly htmlOffsetHeight: number;
+  readonly htmlClientHeight: number;
 }> = {
   storeInitialState: (dom) => ({
     bodyStyleHeight: dom.bodyStyleHeight,
+    htmlOffsetHeight: dom.htmlOffsetHeight,
+    htmlClientHeight: dom.htmlClientHeight,
   }),
-  onBlock: (_, dom) => {
+  onBlock: (initialState, dom) => {
-    dom.bodyStyleHeight = calculateBodyViewportStyleWithMargins(
+    dom.bodyStyleHeight = calculateAdjustedStyle(
-      [dom.bodyComputedMarginTop, dom.bodyComputedMarginBottom],
+      [
+        dom.bodyComputedMarginTop,
+        dom.bodyComputedMarginBottom,
+        calculateScrollbarGutterStyle(initialState.htmlClientHeight, initialState.htmlOffsetHeight),
+      ],
     );
     return ScrollRevertAction.RestoreRequired;
   },
@@ -280,11 +295,20 @@ interface DomPropertyMutator<TInitialStateValue> {
   restoreStateOnUnblock(storedState: TInitialStateValue, dom: ScrollDomStateAccessor): void;
 }
 
-function calculateBodyViewportStyleWithMargins(
+/** Calculates allocated scrollbar gutter, adjusting for `scrollbar-gutter: stable` */
-  margins: readonly string[],
+function calculateScrollbarGutterStyle(
+  clientSize: number,
+  offsetSize: number,
+): string {
+  const scrollbarGutterSize = clientSize - offsetSize;
+  return scrollbarGutterSize !== 0 ? `${scrollbarGutterSize}px` : '';
+}
+
+function calculateAdjustedStyle(
+  spaceOffsets: readonly string[],
 ): string {
   let value = '100%';
-  const calculatedMargin = margins
+  const calculatedMargin = spaceOffsets
     .filter((marginText) => marginText.length > 0)
     .join(' + '); // without setting margins, it leads to layout shift if body has margin
   if (calculatedMargin) {

src/presentation/components/Shared/Modal/Hooks/ScrollLock/WindowScrollDomStateAccessor.ts

@@ -61,4 +61,8 @@ class WindowScrollDomState implements ScrollDomStateAccessor {
   get htmlClientWidth(): number { return HtmlElement.clientWidth; }
 
   get htmlClientHeight(): number { return HtmlElement.clientHeight; }
+
+  get htmlOffsetWidth(): number { return HtmlElement.offsetWidth; }
+
+  get htmlOffsetHeight(): number { return HtmlElement.offsetHeight; }
 }

src/presentation/components/Shared/Modal/Hooks/UseEscapeKeyListener.ts

@@ -1,17 +1,14 @@
-import { onBeforeMount, onBeforeUnmount } from 'vue';
+import { useAutoUnsubscribedEventListener, type UseEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
 
-export function useEscapeKeyListener(callback: () => void) {
+export function useEscapeKeyListener(
-  const onKeyUp = (event: KeyboardEvent) => {
+  callback: () => void,
+  eventTarget: EventTarget = document,
+  useEventListener: UseEventListener = useAutoUnsubscribedEventListener,
+): void {
+  const { startListening } = useEventListener();
+  startListening(eventTarget, 'keyup', (event) => {
     if (event.key === 'Escape') {
       callback();
     }
-  };
-
-  onBeforeMount(() => {
-    window.addEventListener('keyup', onKeyUp);
-  });
-
-  onBeforeUnmount(() => {
-    window.removeEventListener('keyup', onKeyUp);
   });
 }

src/presentation/components/Shared/Modal/ModalContainer.vue

@@ -19,7 +19,8 @@
 
 <script lang="ts">
 import {
-  defineComponent, ref, watchEffect, nextTick,
+  defineComponent, ref, watchEffect,
+  nextTick, inject,
 } from 'vue';
 import ModalOverlay from './ModalOverlay.vue';
 import ModalContent from './ModalContent.vue';
@@ -28,6 +29,8 @@ import { useCurrentFocusToggle } from './Hooks/UseCurrentFocusToggle';
 import { useEscapeKeyListener } from './Hooks/UseEscapeKeyListener';
 import { useAllTrueWatcher } from './Hooks/UseAllTrueWatcher';
 
+export const INJECTION_KEY_ESCAPE_LISTENER = Symbol('useEscapeKeyListener');
+
 export default defineComponent({
   components: {
     ModalOverlay,
@@ -49,6 +52,11 @@ export default defineComponent({
     /* eslint-enable @typescript-eslint/no-unused-vars */
   },
   setup(props, { emit }) {
+    const listenEscapeKey: typeof useEscapeKeyListener = inject(
+      INJECTION_KEY_ESCAPE_LISTENER,
+      useEscapeKeyListener,
+    );
+
     const isRendered = ref(false);
     const isOpen = ref(false);
     const overlayTransitionedOut = ref(false);
@@ -56,7 +64,7 @@ export default defineComponent({
 
     useLockBodyBackgroundScroll(isOpen);
     useCurrentFocusToggle(isOpen);
-    useEscapeKeyListener(() => handleEscapeKeyUp());
+    listenEscapeKey(() => handleEscapeKeyUp());
 
     const {
       onAllConditionsMet: onModalFullyTransitionedOut,

src/presentation/components/Shared/TooltipWrapper.vue

@@ -35,6 +35,9 @@ import {
 } from '@floating-ui/vue';
 import { defineComponent, shallowRef, computed } from 'vue';
 import { useResizeObserverPolyfill } from '@/presentation/components/Shared/Hooks/UseResizeObserverPolyfill';
+import { throttle } from '@/application/Common/Timing/Throttle';
+import { type TargetEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
+import { injectKey } from '@/presentation/injectionSymbols';
 import type { CSSProperties } from 'vue';
 
 const GAP_BETWEEN_TOOLTIP_AND_TRIGGER_IN_PX = 2;
@@ -48,9 +51,12 @@ export default defineComponent({
     const triggeringElement = shallowRef<HTMLElement | undefined>();
     const arrowElement = shallowRef<HTMLElement | undefined>();
 
+    const eventListener = injectKey((keys) => keys.useAutoUnsubscribedEventListener);
     useResizeObserverPolyfill();
 
-    const { floatingStyles, middlewareData, placement } = useFloating(
+    const {
+      floatingStyles, middlewareData, placement, update,
+    } = useFloating(
       triggeringElement,
       tooltipDisplayElement,
       {
@@ -68,6 +74,17 @@ export default defineComponent({
       },
     );
 
+    /*
+      Not using `float-ui`'s `autoUpdate` with `animationFrame: true` because it updates tooltips on
+      every frame through `requestAnimationFrame`. This behavior is analogous to a continuous loop
+      (often 60 updates per second and more depending on the refresh rate), which can be excessively
+      performance-intensive. It's overkill for the application needs and a monkey solution due to
+      its brute-force nature.
+    */
+    setupTransitionEndEvents(throttle(() => {
+      update();
+    }, 400, { excludeLeadingCall: true }), eventListener);
+
     const arrowStyles = computed<CSSProperties>(() => {
       if (!middlewareData.value.arrow) {
         return {
@@ -126,6 +143,19 @@ function getCounterpartBoxOffsetProperty(placement: Placement): keyof CSSPropert
   const currentSide = placement.split('-')[0] as Side;
   return sideCounterparts[currentSide];
 }
+
+function setupTransitionEndEvents(
+  handler: () => void,
+  listener: TargetEventListener,
+) {
+  const transitionEndEvents: readonly (keyof HTMLElementEventMap)[] = [
+    'transitionend',
+    'transitioncancel',
+  ];
+  transitionEndEvents.forEach((eventName) => {
+    listener.startListening(document.body, eventName, handler);
+  });
+}
 </script>
 
 <style scoped lang="scss">

src/presentation/electron/build/README.md

@@ -0,0 +1,13 @@
+# build
+
+This folder is the *build resources directory* [1] and contains files used by electron-build to
+create the desktop version of the application.
+
+Generate icons from the main logo file.
+Do not modify these icons manually.
+For more details, see the [related documentation](./../../../../img/README.md).
+
+The electron-builder [1] uses these files, as specified in the [configuration file](./../../../../electron-builder.cjs).
+
+For more information on icons in electron-builder,
+visit [Icons - electron-builder | www.electron.build](https://web.archive.org/web/20240501103645/https://www.electron.build/icons.html).

src/presentation/electron/main/index.ts

@@ -14,6 +14,8 @@ import {
 } from './ElectronConfig';
 import { registerAllIpcChannels } from './IpcRegistration';
 
+const hideWindowUntilLoaded = true;
+const openDevToolsOnDevelopment = true;
 const isDevelopment = !app.isPackaged;
 
 // Keep a global reference of the window object, if you don't, the window will
@@ -48,12 +50,12 @@ function createWindow() {
       preload: PRELOADER_SCRIPT_PATH,
     },
     icon: APP_ICON_PATH,
+    show: !hideWindowUntilLoaded,
   });
-
+  focusAndShowOnceLoaded(win);
   win.setMenuBarVisibility(false);
   configureExternalsUrlsOpenBrowser(win);
   loadApplication(win);
-
   win.on('closed', () => {
     win = null;
   });
@@ -101,9 +103,8 @@ function loadApplication(window: BrowserWindow) {
   } else {
     loadUrlWithNodeWorkaround(window, RENDERER_HTML_PATH);
   }
-  if (isDevelopment) {
+  openDevTools(window);
-    window.webContents.openDevTools();
+  if (!isDevelopment) {
-  } else {
     const updater = setupAutoUpdater();
     updater.checkForUpdates();
   }
@@ -165,3 +166,29 @@ function configureAppQuitBehavior() {
     });
   }
 }
+
+function focusAndShowOnceLoaded(window: BrowserWindow) {
+  window.once('ready-to-show', () => {
+    window.show(); // Shows and focuses
+    bringToFront(window);
+  });
+}
+
+function bringToFront(window: BrowserWindow) {
+  // Only needed for Windows, tested on GNOME 42.5, Windows 11 23H2 Pro and macOS Sonoma 14.4.1.
+  // Some report it's also needed for some versions of GNOME.
+  // - https://github.com/electron/electron/issues/2867#issuecomment-409858459
+  // - https://github.com/signalapp/Signal-Desktop/blob/0999df2d6e93da805b2135f788ffc739ba69832d/app/SystemTrayService.ts#L277-L284
+  window.setAlwaysOnTop(true);
+  window.setAlwaysOnTop(false);
+}
+
+function openDevTools(window: BrowserWindow) {
+  if (!isDevelopment) {
+    return;
+  }
+  if (!openDevToolsOnDevelopment) {
+    return;
+  }
+  window.webContents.openDevTools();
+}

src/presentation/injectionSymbols.ts

@@ -7,9 +7,10 @@ import type { useCurrentCode } from '@/presentation/components/Shared/Hooks/UseC
 import type { useAutoUnsubscribedEvents } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEvents';
 import type { useUserSelectionState } from '@/presentation/components/Shared/Hooks/UseUserSelectionState';
 import type { useLogger } from '@/presentation/components/Shared/Hooks/Log/UseLogger';
-import type { useCodeRunner } from './components/Shared/Hooks/UseCodeRunner';
+import type { useCodeRunner } from '@/presentation/components/Shared/Hooks/UseCodeRunner';
-import type { useDialog } from './components/Shared/Hooks/Dialog/UseDialog';
+import type { useDialog } from '@/presentation/components/Shared/Hooks/Dialog/UseDialog';
-import type { useScriptDiagnosticsCollector } from './components/Shared/Hooks/UseScriptDiagnosticsCollector';
+import type { useScriptDiagnosticsCollector } from '@/presentation/components/Shared/Hooks/UseScriptDiagnosticsCollector';
+import type { useAutoUnsubscribedEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
 
 export const InjectionKeys = {
   useCollectionState: defineTransientKey<ReturnType<typeof useCollectionState>>('useCollectionState'),
@@ -23,6 +24,7 @@ export const InjectionKeys = {
   useCodeRunner: defineTransientKey<ReturnType<typeof useCodeRunner>>('useCodeRunner'),
   useDialog: defineTransientKey<ReturnType<typeof useDialog>>('useDialog'),
   useScriptDiagnosticsCollector: defineTransientKey<ReturnType<typeof useScriptDiagnosticsCollector>>('useScriptDiagnostics'),
+  useAutoUnsubscribedEventListener: defineTransientKey<ReturnType<typeof useAutoUnsubscribedEventListener>>('useAutoUnsubscribedEventListener'),
 };
 
 export interface InjectionKeyWithLifetime<T> {

tests/e2e/no-unintended-layout-shifts.cy.ts

@@ -1,4 +1,4 @@
-import { ViewportTestScenarios } from './support/scenarios/viewport-test-scenarios';
+import { ViewportTestScenarios, LargeScreen } from './support/scenarios/viewport-test-scenarios';
 import { openCard } from './support/interactions/card';
 import { selectAllScripts, unselectAllScripts } from './support/interactions/script-selection';
 import { assertLayoutStability } from './support/assert/layout-stability';
@@ -62,4 +62,18 @@ describe('Layout stability', () => {
       });
     });
   });
+
+  // Regression test for bug on Chromium where horizontal scrollbar visibility causes layout shifts.
+  it('Scrollbar visibility', () => {
+    // arrange
+    cy.viewport(LargeScreen.width, LargeScreen.height);
+    cy.visit('/');
+    openCard({
+      cardIndex: 0,
+    });
+    // act
+    assertLayoutStability('.app__wrapper', () => {
+      cy.viewport(LargeScreen.width, 100); // Set small height to trigger horizontal scrollbar.
+    }, { excludeHeight: true });
+  });
 });

tests/e2e/support/assert/layout-stability.ts

@@ -1,7 +1,19 @@
 import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
 
-export function assertLayoutStability(selector: string, action: ()=> void): void {
+interface LayoutStabilityTestOptions {
+  excludeWidth: boolean;
+  excludeHeight: boolean;
+}
+
+export function assertLayoutStability(
+  selector: string,
+  action: ()=> void,
+  options: Partial<LayoutStabilityTestOptions> | undefined = undefined,
+): void {
   // arrange
+  if (options?.excludeWidth === true && options?.excludeHeight === true) {
+    throw new Error('Invalid test configuration: both width and height exclusions specified.');
+  }
   let initialMetrics: ViewportMetrics | undefined;
   captureViewportMetrics(selector, (metrics) => {
     initialMetrics = metrics;
@@ -11,10 +23,22 @@ export function assertLayoutStability(selector: string, action: ()=> void): void
   // assert
   captureViewportMetrics(selector, (metrics) => {
     const finalMetrics = metrics;
-    expect(initialMetrics).to.deep.equal(finalMetrics, formatAssertionMessage([
+    const assertionContext = [
       `Expected (initial metrics before action): ${JSON.stringify(initialMetrics)}`,
       `Actual (final metrics after action): ${JSON.stringify(finalMetrics)}`,
-    ]));
+    ];
+    if (options?.excludeWidth !== true) {
+      expect(initialMetrics?.x).to.equal(finalMetrics.x, formatAssertionMessage([
+        'Width instability detected',
+        ...assertionContext,
+      ]));
+    }
+    if (options?.excludeHeight !== true) {
+      expect(initialMetrics?.x).to.equal(finalMetrics.x, formatAssertionMessage([
+        'Height instability detected',
+        ...assertionContext,
+      ]));
+    }
   });
 }
 

tests/e2e/support/scenarios/viewport-test-scenarios.ts

@@ -1,7 +1,19 @@
+const SmallScreen: ViewportScenario = {
+  name: 'iPhone SE', width: 375, height: 667,
+};
+
+const MediumScreen: ViewportScenario = {
+  name: '13-inch Laptop', width: 1280, height: 800,
+};
+
+export const LargeScreen: ViewportScenario = {
+  name: '4K Ultra HD Desktop', width: 3840, height: 2160,
+};
+
 export const ViewportTestScenarios: readonly ViewportScenario[] = [
-  { name: 'iPhone SE', width: 375, height: 667 },
+  SmallScreen,
-  { name: '13-inch Laptop', width: 1280, height: 800 },
+  MediumScreen,
-  { name: '4K Ultra HD Desktop', width: 3840, height: 2160 },
+  LargeScreen,
 ] as const;
 
 interface ViewportScenario {

tests/integration/infrastructure/CodeRunner/ScriptFileCodeRunner.spec.ts

@@ -8,8 +8,8 @@ import { ScriptFileCreationOrchestrator } from '@/infrastructure/CodeRunner/Crea
 import { ScriptFileCodeRunner } from '@/infrastructure/CodeRunner/ScriptFileCodeRunner';
 import { CurrentEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironmentFactory';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import { LinuxTerminalEmulator } from '@/infrastructure/CodeRunner/Execution/VisibleTerminalScriptFileExecutor';
 import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
+import { LinuxTerminalEmulator } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/LinuxVisibleTerminalCommand';
 
 describe('ScriptFileCodeRunner', () => {
   it('executes simple script correctly', async ({ skip }) => {

tests/integration/presentation/bootstrapping/Modules/MobileSafariActivePseudoClassEnabler.spec.ts

@@ -1,7 +1,7 @@
 import { describe, it, afterEach } from 'vitest';
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import { MobileSafariActivePseudoClassEnabler } from '@/presentation/bootstrapping/Modules/MobileSafariActivePseudoClassEnabler';
-import { type EventName, createWindowEventSpies } from '@tests/shared/Spies/WindowEventSpies';
+import { createEventSpies } from '@tests/shared/Spies/EventTargetSpy';
 import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
 import { isTouchEnabledDevice } from '@/infrastructure/RuntimeEnvironment/Browser/TouchSupportDetection';
 import { BrowserRuntimeEnvironment } from '@/infrastructure/RuntimeEnvironment/Browser/BrowserRuntimeEnvironment';
@@ -14,9 +14,9 @@ describe('MobileSafariActivePseudoClassEnabler', () => {
     }) => {
       it(description, () => {
         // arrange
-        const expectedEvent: EventName = 'touchstart';
+        const expectedEvent: keyof WindowEventMap = 'touchstart';
         patchUserAgent(userAgent, afterEach);
-        const { isAddEventCalled, currentListeners } = createWindowEventSpies(afterEach);
+        const { isAddEventCalled, formatListeners } = createEventSpies(window, afterEach);
         const patchedEnvironment = new TouchSupportControlledBrowserEnvironment(supportsTouch);
         const sut = new MobileSafariActivePseudoClassEnabler(patchedEnvironment);
         // act
@@ -30,7 +30,7 @@ describe('MobileSafariActivePseudoClassEnabler', () => {
           `Touch supported\t\t: ${supportsTouch}`,
           `Current OS\t\t: ${patchedEnvironment.os === undefined ? 'unknown' : OperatingSystem[patchedEnvironment.os]}`,
           `Is desktop?\t\t: ${patchedEnvironment.isRunningAsDesktopApplication ? 'Yes (Desktop app)' : 'No (Browser)'}`,
-          `Listeners (${currentListeners.length})\t\t: ${JSON.stringify(currentListeners)}`,
+          `Listeners\t\t: ${formatListeners()}`,
         ]));
       });
     });

tests/integration/presentation/components/Scripts/View/Tree/Shared/Modal/Hooks/UseEscapeKeyListener.spec.ts

@@ -0,0 +1,74 @@
+import {
+  describe, it, expect,
+} from 'vitest';
+import { defineComponent } from 'vue';
+import { mount } from '@vue/test-utils';
+import { createEventSpies } from '@tests/shared/Spies/EventTargetSpy';
+import { useEscapeKeyListener } from '@/presentation/components/Shared/Modal/Hooks/UseEscapeKeyListener';
+import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
+
+const EventSource: EventTarget = document;
+type EventName = keyof DocumentEventMap;
+
+describe('UseEscapeKeyListener', () => {
+  it('executes the callback when the Escape key is pressed', () => {
+    // arrange
+    const expectedCallbackCall = true;
+    let callbackCalled = false;
+    const callback = () => {
+      callbackCalled = true;
+    };
+
+    // act
+    mountWrapperComponent(callback);
+    const event = new KeyboardEvent('keyup', { key: 'Escape' });
+    EventSource.dispatchEvent(event);
+
+    // assert
+    expect(callbackCalled).to.equal(expectedCallbackCall);
+  });
+
+  it('adds the event listener on component mount', () => {
+    // arrange
+    const expectedEventType: EventName = 'keyup';
+    const { isAddEventCalled, formatListeners } = createEventSpies(EventSource, afterEach);
+
+    // act
+    mountWrapperComponent();
+
+    // assert
+    const isAdded = isAddEventCalled(expectedEventType);
+    expect(isAdded).to.equal(true, formatAssertionMessage([
+      `Expected event type to be added: "${expectedEventType}".`,
+      `Current listeners: ${formatListeners()}`,
+    ]));
+  });
+
+  it('removes the event listener once unmounted', () => {
+    // arrange
+    const expectedEventType: EventName = 'keyup';
+    const { isRemoveEventCalled, formatListeners } = createEventSpies(EventSource, afterEach);
+
+    // act
+    const wrapper = mountWrapperComponent();
+    wrapper.unmount();
+
+    // assert
+    const isRemoved = isRemoveEventCalled(expectedEventType);
+    expect(isRemoved).to.equal(true, formatAssertionMessage([
+      `Expected event type to be removed: "${expectedEventType}".`,
+      `Remaining listeners: ${formatListeners()}`,
+    ]));
+  });
+});
+
+function mountWrapperComponent(
+  callback = () => {},
+) {
+  return mount(defineComponent({
+    setup() {
+      useEscapeKeyListener(callback);
+    },
+    template: '<div></div>',
+  }));
+}

tests/integration/presentation/components/Scripts/View/Tree/TreeView/Node/UseKeyboardInteractionState.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { shallowMount } from '@vue/test-utils';
+import { defineComponent } from 'vue';
+import { useKeyboardInteractionState } from '@/presentation/components/Scripts/View/Tree/TreeView/Node/UseKeyboardInteractionState';
+import { expectExists } from '@tests/shared/Assertions/ExpectExists';
+
+describe('useKeyboardInteractionState', () => {
+  describe('isKeyboardBeingUsed', () => {
+    it('`false` initially', () => {
+      // arrange
+      const expectedValue = false;
+      // act
+      const { returnObject } = mountWrapperComponent();
+      // assert
+      const actualValue = returnObject.isKeyboardBeingUsed.value;
+      expect(actualValue).to.equal(expectedValue);
+    });
+
+    it('`true` after any key is pressed', () => {
+      // arrange
+      const expectedValue = true;
+      // act
+      const { returnObject } = mountWrapperComponent();
+      triggerKeyPress();
+      // assert
+      const actualValue = returnObject.isKeyboardBeingUsed.value;
+      expect(actualValue).to.equal(expectedValue);
+    });
+
+    it('`false` after any key is pressed once detached', () => {
+      // arrange
+      const expectedValue = false;
+      // act
+      const { wrapper, returnObject } = mountWrapperComponent();
+      wrapper.unmount();
+      triggerKeyPress(); // should not react to it
+      // assert
+      const actualValue = returnObject.isKeyboardBeingUsed.value;
+      expect(actualValue).to.equal(expectedValue);
+    });
+  });
+});
+
+function triggerKeyPress() {
+  const eventSource: EventTarget = document;
+  const keydownEvent = new KeyboardEvent('keydown', { key: 'a' });
+  eventSource.dispatchEvent(keydownEvent);
+}
+
+function mountWrapperComponent() {
+  let returnObject: ReturnType<typeof useKeyboardInteractionState> | undefined;
+  const wrapper = shallowMount(defineComponent({
+    setup() {
+      returnObject = useKeyboardInteractionState();
+    },
+    template: '<div></div>',
+  }));
+  expectExists(returnObject);
+  return {
+    returnObject,
+    wrapper,
+  };
+}

tests/integration/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener.spec.ts

@@ -0,0 +1,67 @@
+import {
+  describe, it, expect,
+} from 'vitest';
+import { mount } from '@vue/test-utils';
+import { defineComponent } from 'vue';
+import { useAutoUnsubscribedEventListener } from '@/presentation/components/Shared/Hooks/UseAutoUnsubscribedEventListener';
+
+describe('UseAutoUnsubscribedEventListener', () => {
+  describe('event listening on different targets', () => {
+    const testCases: readonly {
+      readonly description: string;
+      readonly eventTarget: EventTarget;
+    }[] = [
+      {
+        description: 'a div element',
+        eventTarget: document.createElement('div'),
+      },
+      {
+        description: 'the document',
+        eventTarget: document,
+      },
+      {
+        description: 'the HTML element',
+        eventTarget: document.documentElement,
+      },
+      {
+        description: 'the body element',
+        eventTarget: document.body,
+      },
+      // `window` target is not working in tests due to how `jsdom` handles it
+    ];
+    testCases.forEach((
+      { description, eventTarget },
+    ) => {
+      it(description, () => {
+        // arrange
+        let actualEvent: KeyboardEvent | undefined;
+        const expectedEvent = new KeyboardEvent('keypress');
+        mountWrapperComponent(
+          ({ startListening }) => {
+            startListening(eventTarget, 'keypress', (event) => {
+              actualEvent = event;
+            });
+          },
+        );
+
+        // act
+        eventTarget.dispatchEvent(expectedEvent);
+
+        // assert
+        expect(actualEvent).to.equal(expectedEvent);
+      });
+    });
+  });
+});
+
+function mountWrapperComponent(
+  callback: (returnObject: ReturnType<typeof useAutoUnsubscribedEventListener>) => void,
+) {
+  return mount(defineComponent({
+    setup() {
+      const returnObject = useAutoUnsubscribedEventListener();
+      callback(returnObject);
+    },
+    template: '<div></div>',
+  }));
+}

tests/integration/presentation/components/Shared/Modal/ModalContainer.spec.ts

@@ -0,0 +1,29 @@
+import {
+  describe, it, expect,
+} from 'vitest';
+import { mount } from '@vue/test-utils';
+import ModalContainer from '@/presentation/components/Shared/Modal/ModalContainer.vue';
+
+describe('ModalContainer', () => {
+  it('closes on pressing ESC key', async () => {
+    // arrange
+    const wrapper = mountComponent({ modelValue: true });
+
+    // act
+    const escapeEvent = new KeyboardEvent('keyup', { key: 'Escape' });
+    document.dispatchEvent(escapeEvent);
+
+    // assert
+    expect(wrapper.emitted('update:modelValue')).to.deep.equal([[false]]);
+  });
+});
+
+function mountComponent(options: {
+  readonly modelValue: boolean,
+}) {
+  return mount(ModalContainer, {
+    props: {
+      modelValue: options.modelValue,
+    },
+  });
+}

tests/shared/Spies/EventTargetSpy.ts

@@ -0,0 +1,70 @@
+export function createEventSpies(
+  eventTarget: EventTarget,
+  restoreCallback: (restoreFunc: () => void) => void,
+) {
+  const originalAddEventListener = eventTarget.addEventListener;
+  const originalRemoveEventListener = eventTarget.removeEventListener;
+
+  const currentListeners = new Array<Parameters<typeof eventTarget.addEventListener>>();
+
+  const addEventListenerCalls = new Array<Parameters<typeof eventTarget.addEventListener>>();
+  const removeEventListenerCalls = new Array<Parameters<typeof eventTarget.removeEventListener>>();
+
+  eventTarget.addEventListener = (
+    ...args: Parameters<typeof eventTarget.addEventListener>
+  ): ReturnType<typeof eventTarget.addEventListener> => {
+    addEventListenerCalls.push(args);
+    currentListeners.push(args);
+    return originalAddEventListener.call(eventTarget, ...args);
+  };
+
+  eventTarget.removeEventListener = (
+    ...args: Parameters<typeof eventTarget.removeEventListener>
+  ): ReturnType<typeof eventTarget.removeEventListener> => {
+    removeEventListenerCalls.push(args);
+    const [type, listener] = args;
+    const registeredListener = findCurrentListener(type, listener);
+    if (registeredListener) {
+      const index = currentListeners.indexOf(registeredListener);
+      if (index > -1) {
+        currentListeners.splice(index, 1);
+      }
+    }
+    return originalRemoveEventListener.call(eventTarget, ...args);
+  };
+
+  function findCurrentListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+  ): Parameters<typeof eventTarget.addEventListener> | undefined {
+    return currentListeners.find((args) => {
+      const [eventType, eventListener] = args;
+      return eventType === type && listener === eventListener;
+    });
+  }
+
+  restoreCallback(() => {
+    eventTarget.addEventListener = originalAddEventListener;
+    eventTarget.removeEventListener = originalRemoveEventListener;
+  });
+
+  return {
+    isAddEventCalled(eventType: string): boolean {
+      const call = addEventListenerCalls.find((args) => {
+        const [type] = args;
+        return type === eventType;
+      });
+      return call !== undefined;
+    },
+    isRemoveEventCalled(eventType: string) {
+      const call = removeEventListenerCalls.find((args) => {
+        const [type] = args;
+        return type === eventType;
+      });
+      return call !== undefined;
+    },
+    formatListeners: () => {
+      return JSON.stringify(currentListeners);
+    },
+  };
+}

tests/shared/Spies/WindowEventSpies.ts

@@ -1,67 +0,0 @@
-export type EventName = keyof WindowEventMap;
-
-export function createWindowEventSpies(restoreCallback: (restoreFunc: () => void) => void) {
-  const originalAddEventListener = window.addEventListener;
-  const originalRemoveEventListener = window.removeEventListener;
-
-  const currentListeners = new Array<Parameters<typeof window.addEventListener>>();
-
-  const addEventListenerCalls = new Array<Parameters<typeof window.addEventListener>>();
-  const removeEventListenerCalls = new Array<Parameters<typeof window.removeEventListener>>();
-
-  window.addEventListener = (
-    ...args: Parameters<typeof window.addEventListener>
-  ): ReturnType<typeof window.addEventListener> => {
-    addEventListenerCalls.push(args);
-    currentListeners.push(args);
-    return originalAddEventListener.call(window, ...args);
-  };
-
-  window.removeEventListener = (
-    ...args: Parameters<typeof window.removeEventListener>
-  ): ReturnType<typeof window.removeEventListener> => {
-    removeEventListenerCalls.push(args);
-    const [type, listener] = args;
-    const registeredListener = findCurrentListener(type as EventName, listener);
-    if (registeredListener) {
-      const index = currentListeners.indexOf(registeredListener);
-      if (index > -1) {
-        currentListeners.splice(index, 1);
-      }
-    }
-    return originalRemoveEventListener.call(window, ...args);
-  };
-
-  function findCurrentListener(
-    type: EventName,
-    listener: EventListenerOrEventListenerObject,
-  ): Parameters<typeof window.addEventListener> | undefined {
-    return currentListeners.find((args) => {
-      const [eventType, eventListener] = args;
-      return eventType === type && listener === eventListener;
-    });
-  }
-
-  restoreCallback(() => {
-    window.addEventListener = originalAddEventListener;
-    window.removeEventListener = originalRemoveEventListener;
-  });
-
-  return {
-    isAddEventCalled(eventType: EventName): boolean {
-      const call = addEventListenerCalls.find((args) => {
-        const [type] = args;
-        return type === eventType;
-      });
-      return call !== undefined;
-    },
-    isRemoveEventCalled(eventType: EventName) {
-      const call = removeEventListenerCalls.find((args) => {
-        const [type] = args;
-        return type === eventType;
-      });
-      return call !== undefined;
-    },
-    currentListeners,
-  };
-}

tests/unit/application/Common/Timing/BatchedDebounce.spec.ts

@@ -4,7 +4,7 @@ import { TimerStub } from '@tests/unit/shared/Stubs/TimerStub';
 
 describe('batchedDebounce', () => {
   describe('immediate invocation', () => {
-    it('does not call the the callback immediately on the first call', () => {
+    it('does not call the callback immediately on the first call', () => {
       // arrange
       const { calledBatches, callback } = createObservableCallback();
       const callArg = 'first';

tests/unit/application/Common/Timing/Throttle.spec.ts

@@ -1,53 +1,116 @@
 import { describe, it, expect } from 'vitest';
 import { TimerStub } from '@tests/unit/shared/Stubs/TimerStub';
-import { throttle } from '@/application/Common/Timing/Throttle';
+import { throttle, type ThrottleOptions } from '@/application/Common/Timing/Throttle';
+import type { Timer } from '@/application/Common/Timing/Timer';
+import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
 
 describe('throttle', () => {
-  describe('validates parameters', () => {
+  describe('parameter validation', () => {
-    describe('throws if waitInMs is invalid', () => {
+    describe('throws for invalid waitInMs', () => {
-      // arrange
+      const testCases: readonly {
-      const testCases = [
+        readonly description: string;
+        readonly value: number;
+        readonly expectedError: string;
+      }[] = [
         {
-          name: 'given zero',
+          description: 'given zero',
           value: 0,
           expectedError: 'missing delay',
         },
         {
-          name: 'given negative',
+          description: 'given negative',
           value: -2,
           expectedError: 'negative delay',
         },
       ];
-      const noopCallback = () => { /* do nothing */ };
+      testCases.forEach((
-      for (const testCase of testCases) {
+        { description, expectedError, value: waitInMs },
-        it(`"${testCase.name}" throws "${testCase.expectedError}"`, () => {
+      ) => {
+        it(`"${description}" throws "${expectedError}"`, () => {
+          // arrange
+          const context = new TestContext()
+            .withWaitInMs(waitInMs);
           // act
-          const waitInMs = testCase.value;
+          const act = () => context.throttle();
-          const act = () => throttle(noopCallback, waitInMs);
           // assert
-          expect(act).to.throw(testCase.expectedError);
+          expect(act).to.throw(expectedError);
         });
-      }
+      });
     });
   });
-  it('should call the callback immediately', () => {
+  it('executes the leading callback immediately', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
-    const throttleFunc = throttle(callback, 500, timer);
+    const throttleFunc = new TestContext()
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
     // act
     throttleFunc();
+
     // assert
     expect(totalRuns).to.equal(1);
   });
-  it('should call the callback again after the timeout', () => {
+  it('executes the leading callback with initial arguments', () => {
+    // arrange
+    const expectedArguments = [1, 2, 3];
+    const timer = new TimerStub();
+    let lastArgs: readonly number[] | null = null;
+    const callback = (...args: readonly number[]) => { lastArgs = args; };
+    const waitInMs = 500;
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
+    // act
+    throttleFunc(...expectedArguments);
+    timer.tickNext(waitInMs / 3);
+    throttleFunc(4, 5, 6);
+    timer.tickNext(waitInMs / 3);
+    throttleFunc(7, 8, 9);
+
+    // assert
+    expect(lastArgs).to.deep.equal(expectedArguments);
+  });
+  it('executes the trailing callback with final arguments', () => {
+    // arrange
+    const expectedArguments = [1, 2, 3];
+    const timer = new TimerStub();
+    let lastArgs: readonly number[] | null = null;
+    const callback = (...args: readonly number[]) => { lastArgs = args; };
+    const waitInMs = 500;
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
+    // act
+    throttleFunc(1, 2, 3);
+    timer.tickNext(100);
+    throttleFunc(4, 5, 6);
+    timer.tickNext(100);
+    throttleFunc(lastArgs);
+
+    // assert
+    expect(lastArgs).to.deep.equal(expectedArguments);
+  });
+  it('executes the callback after the delay', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
     const waitInMs = 500;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
     throttleFunc();
     totalRuns--; // So we don't count the initial run
@@ -56,53 +119,207 @@ describe('throttle', () => {
     // assert
     expect(totalRuns).to.equal(1);
   });
-  it('should call the callback at most once at given time', () => {
+  it('limits calls to at most once per period', () => {
     // arrange
+    const totalExpectedCalls = 2; // leading and trailing only
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
-    const waitInMs = 500;
+    const waitInMs = 200;
     const totalCalls = 10;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
     for (let currentCall = 0; currentCall < totalCalls; currentCall++) {
       const currentTime = (waitInMs / totalCalls) * currentCall;
       timer.setCurrentTime(currentTime);
       throttleFunc();
     }
+    timer.tickNext(waitInMs);
     // assert
-    expect(totalRuns).to.equal(2); // one initial and one at the end
+    expect(totalRuns).to.equal(totalExpectedCalls);
   });
-  it('should call the callback as long as delay is waited', () => {
+  it('executes the callback after each complete delay period', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
     const waitInMs = 500;
     const expectedTotalRuns = 10;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
-    for (let i = 0; i < expectedTotalRuns; i++) {
+    Array.from({ length: expectedTotalRuns }).forEach(() => {
       throttleFunc();
       timer.tickNext(waitInMs);
-    }
+    });
     // assert
     expect(totalRuns).to.equal(expectedTotalRuns);
   });
-  it('should call arguments as expected', () => {
+  describe('leading call exclusion', () => {
-    // arrange
+    it('does not execute the callback immediately on the first call', () => {
-    const timer = new TimerStub();
+      // arrange
-    const expected = [1, 2, 3];
+      const timer = new TimerStub();
-    const actual = new Array<number>();
+      let totalRuns = 0;
-    const callback = (arg: number) => { actual.push(arg); };
+      const callback = () => totalRuns++;
-    const waitInMs = 500;
+      const throttleFunc = new TestContext()
-    const throttleFunc = throttle(callback, waitInMs, timer);
+        .withTimer(timer)
-    // act
+        .withCallback(callback)
-    for (const arg of expected) {
+        .withExcludeLeadingCall(true)
-      throttleFunc(arg);
+        .throttle();
+      // act
+      throttleFunc();
+      // assert
+      expect(totalRuns).to.equal(0);
+    });
+    it('executes the initial call after the initial wait time', () => {
+      // arrange
+      const timer = new TimerStub();
+      let totalRuns = 0;
+      const waitInMs = 200;
+      const callback = () => totalRuns++;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .withWaitInMs(waitInMs)
+        .throttle();
+      // act
+      throttleFunc();
       timer.tickNext(waitInMs);
-    }
+      // assert
-    // assert
+      expect(totalRuns).to.equal(1);
-    expect(expected).to.deep.equal(actual);
+    });
+    it('executes two calls after two wait periods', () => {
+      // arrange
+      const expectedTotalRuns = 2;
+      const calledArgs = new Array<string>();
+      const timer = new TimerStub();
+      const waitInMs = 300;
+      let totalRuns = 0;
+      const callback = (message: string) => {
+        totalRuns++;
+        calledArgs.push(message);
+      };
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withCallback(callback)
+        .withWaitInMs(waitInMs)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      Array.from({ length: expectedTotalRuns }).forEach((_, index) => {
+        throttleFunc(`Call ${index} (zero-based, where initial call is 0)`);
+        timer.tickNext(waitInMs);
+      });
+      // assert
+      expect(totalRuns).to.equal(expectedTotalRuns, formatAssertionMessage([
+        `Expected total runs to equal ${expectedTotalRuns}, but got ${totalRuns}.`,
+        'Detailed call information:',
+        ...calledArgs.map((message, index) => `${index + 1}) ${message}`),
+      ]));
+    });
+    it('only executes once when multiple calls are made during the initial wait period', () => {
+      // arrange
+      const timer = new TimerStub();
+      let totalRuns = 0;
+      const callback = () => { totalRuns++; };
+      const waitInMs = 300;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withWaitInMs(waitInMs)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      // assert
+      expect(totalRuns).to.equal(1);
+    });
+    it('executes the last provided arguments only after the wait period expires', () => {
+      // arrange
+      const expectedLastArg = 'trailing call';
+      const timer = new TimerStub();
+      let actualLastArg: string | null = null;
+      const callback = (arg: string) => {
+        actualLastArg = arg;
+      };
+      const waitInMs = 300;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withWaitInMs(waitInMs)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      throttleFunc('leading call');
+      timer.tickNext(waitInMs / 3);
+      throttleFunc('call in the middle');
+      timer.tickNext(waitInMs / 3);
+      throttleFunc(expectedLastArg);
+      timer.tickNext(waitInMs / 3);
+      // assert
+      expect(actualLastArg).to.equal(expectedLastArg);
+    });
   });
 });
+
+type CallbackType = Parameters<typeof throttle>[0];
+
+class TestContext {
+  private options: Partial<ThrottleOptions> | undefined = {
+    timer: new TimerStub(),
+  };
+
+  private waitInMs: number = 500;
+
+  private callback: CallbackType = () => { /* NO OP */ };
+
+  public withTimer(timer: Timer): this {
+    return this.withOptions({
+      ...(this.options ?? {}),
+      timer,
+    });
+  }
+
+  public withWaitInMs(waitInMs: number): this {
+    this.waitInMs = waitInMs;
+    return this;
+  }
+
+  public withCallback(callback: CallbackType): this {
+    this.callback = callback;
+    return this;
+  }
+
+  public withExcludeLeadingCall(excludeLeadingCall: boolean): this {
+    return this.withOptions({
+      ...(this.options ?? {}),
+      excludeLeadingCall,
+    });
+  }
+
+  public withOptions(options: Partial<ThrottleOptions> | undefined): this {
+    this.options = options;
+    return this;
+  }
+
+  public throttle(): ReturnType<typeof throttle> {
+    return throttle(
+      this.callback,
+      this.waitInMs,
+      this.options,
+    );
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/LinuxVisibleTerminalCommand.spec.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { LinuxVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/LinuxVisibleTerminalCommand';
+import type { ShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaper';
+import { ShellArgumentEscaperStub } from '@tests/unit/shared/Stubs/ShellArgumentEscaperStub';
+
+describe('LinuxVisibleTerminalCommand', () => {
+  describe('buildShellCommand', () => {
+    it('returns expected command for given escaped file path', () => {
+      // arrange
+      const escapedFilePath = '/escaped/file/path';
+      const expectedCommand = `x-terminal-emulator -e ${escapedFilePath}`;
+      const escaper = new ShellArgumentEscaperStub();
+      escaper.escapePathArgument = () => escapedFilePath;
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .build();
+      // act
+      const actualCommand = sut.buildShellCommand('unimportant');
+      // assert
+      expect(actualCommand).to.equal(expectedCommand);
+    });
+    it('escapes provided file path correctly', () => {
+      // arrange
+      const expectedFilePath = '/input';
+      const escaper = new ShellArgumentEscaperStub();
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .build();
+      // act
+      sut.buildShellCommand(expectedFilePath);
+      // assert
+      expect(escaper.callHistory).to.have.lengthOf(1);
+      const [actualFilePath] = escaper.callHistory[0].args;
+      expect(actualFilePath).to.equal(expectedFilePath);
+    });
+  });
+  describe('isExecutionTerminatedExternally', () => {
+    const testScenarios: readonly {
+      readonly givenExitCode: number;
+      readonly expectedResult: boolean;
+    }[] = [
+      {
+        givenExitCode: 137,
+        expectedResult: true,
+      },
+    ];
+    testScenarios.forEach((
+      { givenExitCode, expectedResult },
+    ) => {
+      it(`returns ${expectedResult} for exit code ${givenExitCode}`, () => {
+        // arrange
+        const expectedValue = true;
+        const sut = new CommandBuilder().build();
+        // act
+        const actualValue = sut.isExecutionTerminatedExternally(givenExitCode);
+        // assert
+        expect(expectedValue).to.equal(actualValue);
+      });
+    });
+  });
+  describe('isExecutablePermissionsRequiredOnFile', () => {
+    it('returns true', () => {
+      // arrange
+      const expectedValue = true;
+      const sut = new CommandBuilder().build();
+      // act
+      const actualValue = sut.isExecutablePermissionsRequiredOnFile();
+      // assert
+      expect(expectedValue).to.equal(actualValue);
+    });
+  });
+});
+
+class CommandBuilder {
+  private escaper: ShellArgumentEscaper = new ShellArgumentEscaperStub();
+
+  public withEscaper(escaper: ShellArgumentEscaper): this {
+    this.escaper = escaper;
+    return this;
+  }
+
+  public build(): LinuxVisibleTerminalCommand {
+    return new LinuxVisibleTerminalCommand(
+      this.escaper,
+    );
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/MacOsVisibleTerminalCommand.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { MacOsVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/MacOsVisibleTerminalCommand';
+import type { ShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaper';
+import { ShellArgumentEscaperStub } from '@tests/unit/shared/Stubs/ShellArgumentEscaperStub';
+
+describe('MacOsVisibleTerminalCommand', () => {
+  describe('buildShellCommand', () => {
+    it('returns expected command for given escaped file path', () => {
+      // arrange
+      const escapedFilePath = '/escaped/file/path';
+      const expectedCommand = `open -a Terminal.app ${escapedFilePath}`;
+      const escaper = new ShellArgumentEscaperStub();
+      escaper.escapePathArgument = () => escapedFilePath;
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .build();
+      // act
+      const actualCommand = sut.buildShellCommand('unimportant');
+      // assert
+      expect(actualCommand).to.equal(expectedCommand);
+    });
+    it('escapes provided file path correctly', () => {
+      // arrange
+      const expectedFilePath = '/input';
+      const escaper = new ShellArgumentEscaperStub();
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .build();
+      // act
+      sut.buildShellCommand(expectedFilePath);
+      // assert
+      expect(escaper.callHistory).to.have.lengthOf(1);
+      const [actualFilePath] = escaper.callHistory[0].args;
+      expect(actualFilePath).to.equal(expectedFilePath);
+    });
+  });
+  describe('isExecutionTerminatedExternally', () => {
+    it('returns `false`', () => {
+      // arrange
+      const expectedValue = false;
+      const sut = new CommandBuilder().build();
+      // act
+      const actualValue = sut.isExecutionTerminatedExternally();
+      // assert
+      expect(expectedValue).to.equal(actualValue);
+    });
+  });
+  describe('isExecutablePermissionsRequiredOnFile', () => {
+    it('returns `true`', () => {
+      // arrange
+      const expectedValue = true;
+      const sut = new CommandBuilder().build();
+      // act
+      const actualValue = sut.isExecutablePermissionsRequiredOnFile();
+      // assert
+      expect(expectedValue).to.equal(actualValue);
+    });
+  });
+});
+
+class CommandBuilder {
+  private escaper: ShellArgumentEscaper = new ShellArgumentEscaperStub();
+
+  public withEscaper(escaper: ShellArgumentEscaper): this {
+    this.escaper = escaper;
+    return this;
+  }
+
+  public build(): MacOsVisibleTerminalCommand {
+    return new MacOsVisibleTerminalCommand(
+      this.escaper,
+    );
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/PowerShellInvoke/EncodedPowerShellInvokeCmdCommandCreator.spec.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { EncodedPowerShellInvokeCmdCommandCreator } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/PowerShellInvoke/EncodedPowerShellInvokeCmdCommandCreator';
+
+describe('EncodedPowerShellInvokeCmdCommandCreator', () => {
+  describe('createCommandToInvokePowerShell', () => {
+    it('starts with PowerShell base command', () => {
+      // arrange
+      const sut = new EncodedPowerShellInvokeCmdCommandCreator();
+      // act
+      const command = sut.createCommandToInvokePowerShell('non-important-command');
+      // assert
+      expect(command.startsWith('PowerShell ')).to.equal(true);
+    });
+    it('includes encoded command as parameter', () => {
+      // arrange
+      const expectedParameterName = '-EncodedCommand';
+      const sut = new EncodedPowerShellInvokeCmdCommandCreator();
+      // act
+      const command = sut.createCommandToInvokePowerShell('non-important-command');
+      // assert
+      const args = parsePowerShellArgs(command);
+      const parameterNames = [...args.keys()];
+      expect(parameterNames).to.include(expectedParameterName);
+    });
+    it('correctly encode the command as utf16le base64', () => {
+      // arrange
+      const givenCode = 'Write-Output "Today is $(Get-Date -Format \'dddd, MMMM dd\')."';
+      const expectedEncodedCommand = 'VwByAGkAdABlAC0ATwB1AHQAcAB1AHQAIAAiAFQAbwBkAGEAeQAgAGkAcwAgACQAKABHAGUAdAAtAEQAYQB0AGUAIAAtAEYAbwByAG0AYQB0ACAAJwBkAGQAZABkACwAIABNAE0ATQBNACAAZABkACcAKQAuACIA';
+      const sut = new EncodedPowerShellInvokeCmdCommandCreator();
+      // act
+      const command = sut.createCommandToInvokePowerShell(givenCode);
+      // assert
+      const args = parsePowerShellArgs(command);
+      const actualEncodedCommand = args.get('-EncodedCommand');
+      expect(actualEncodedCommand).to.equal(expectedEncodedCommand);
+    });
+  });
+});
+
+function parsePowerShellArgs(command: string): Map<string, string | undefined> {
+  const argsMap = new Map<string, string | undefined>();
+  const argRegex = /(-\w+)(\s+([^ ]+))?/g;
+  let match = argRegex.exec(command);
+  while (match !== null) {
+    const arg = match[1];
+    const value = match[3];
+    argsMap.set(arg, value);
+    match = argRegex.exec(command);
+  }
+  return argsMap;
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PosixShellArgumentEscaper.spec.ts

@@ -0,0 +1,18 @@
+import { describe } from 'vitest';
+import { PosixShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PosixShellArgumentEscaper';
+import { runEscapeTests } from './ShellArgumentEscaperTestRunner';
+
+describe('PosixShellArgumentEscaper', () => {
+  runEscapeTests(() => new PosixShellArgumentEscaper(), [
+    {
+      description: 'encloses the path in quotes',
+      givenPath: '/usr/local/bin',
+      expectedPath: '\'/usr/local/bin\'',
+    },
+    {
+      description: 'escapes single quotes in path',
+      givenPath: 'f\'i\'le',
+      expectedPath: '\'f\'\\\'\'i\'\\\'\'le\'',
+    },
+  ]);
+});

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PowerShellArgumentEscaper.spec.ts

@@ -0,0 +1,23 @@
+import { describe } from 'vitest';
+import { PowerShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/PowerShellArgumentEscaper';
+import { runEscapeTests } from './ShellArgumentEscaperTestRunner';
+
+describe('PowerShellArgumentEscaper', () => {
+  runEscapeTests(() => new PowerShellArgumentEscaper(), [
+    {
+      description: 'encloses the path in single quotes',
+      givenPath: 'C:\\Program Files\\app.exe',
+      expectedPath: '\'C:\\Program Files\\app.exe\'',
+    },
+    {
+      description: 'escapes single internal single quotes',
+      givenPath: 'C:\\Users\\O\'Reilly\\Documents',
+      expectedPath: '\'C:\\Users\\O\'\'Reilly\\Documents\'',
+    },
+    {
+      description: 'escapes multiple internal single quotes',
+      givenPath: 'C:\\Program Files\\User\'s Files\\Today\'s Files',
+      expectedPath: '\'C:\\Program Files\\User\'\'s Files\\Today\'\'s Files\'',
+    },
+  ]);
+});

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaperTestRunner.ts

@@ -0,0 +1,23 @@
+import type { ShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaper';
+
+export function runEscapeTests(
+  escaperFactory: () => ShellArgumentEscaper,
+  testScenarios: ReadonlyArray<{
+    readonly description: string;
+    readonly givenPath: string;
+    readonly expectedPath: string;
+  }>,
+) {
+  testScenarios.forEach(({
+    description, givenPath, expectedPath,
+  }) => {
+    it(description, () => {
+      // arrange
+      const escaper = escaperFactory();
+      // act
+      const actualPath = escaper.escapePathArgument(givenPath);
+      // assert
+      expect(actualPath).to.equal(expectedPath);
+    });
+  });
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/WindowsVisibleTerminalCommand.spec.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import { WindowsVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/WindowsVisibleTerminalCommand';
+import type { ShellArgumentEscaper } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/ShellArgument/ShellArgumentEscaper';
+import { ShellArgumentEscaperStub } from '@tests/unit/shared/Stubs/ShellArgumentEscaperStub';
+import type { Logger } from '@/application/Common/Log/Logger';
+import { LoggerStub } from '@tests/unit/shared/Stubs/LoggerStub';
+import type { PowerShellInvokeShellCommandCreator } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/PowerShellInvoke/PowerShellInvokeShellCommandCreator';
+import { PowerShellInvokeShellCommandCreatorStub } from '@tests/unit/shared/Stubs/PowerShellInvokeShellCommandCreatorStub';
+import { expectExists } from '@tests/shared/Assertions/ExpectExists';
+
+describe('WindowsVisibleTerminalCommand', () => {
+  describe('buildShellCommand', () => {
+    it('creates a PowerShell command with the escaped path', () => {
+      // arrange
+      const escapedFilePath = '/escaped/file/path';
+      const expectedCommand = `Start-Process -Verb RunAs -FilePath ${escapedFilePath}`;
+      const escaper = new ShellArgumentEscaperStub();
+      escaper.escapePathArgument = () => escapedFilePath;
+      const powerShellCommandCreator = new PowerShellInvokeShellCommandCreatorStub();
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .withPowerShellCommandCreator(powerShellCommandCreator)
+        .build();
+      // act
+      sut.buildShellCommand('unimportant');
+      // assert
+      const calls = powerShellCommandCreator.callHistory.filter((c) => c.methodName === 'createCommandToInvokePowerShell');
+      expect(calls).to.have.lengthOf(1);
+      const [actualCommand] = calls[0].args;
+      expect(actualCommand).to.equal(expectedCommand);
+    });
+    it('returns a command to invoke PowerShell', () => {
+      // arrange
+      const expectedCommand = 'expected command from creator';
+      const powerShellCommandCreator = new PowerShellInvokeShellCommandCreatorStub();
+      powerShellCommandCreator.createCommandToInvokePowerShell = () => expectedCommand;
+      const sut = new CommandBuilder()
+        .withPowerShellCommandCreator(powerShellCommandCreator)
+        .build();
+      // act
+      const actualCommand = sut.buildShellCommand('unimportant');
+      // assert
+      expect(actualCommand).to.equal(expectedCommand);
+    });
+    it('logs the powershell command', () => {
+      // arrange
+      let expectedCommand: string | undefined;
+      const powerShellCommandCreator = new PowerShellInvokeShellCommandCreatorStub();
+      powerShellCommandCreator.createCommandToInvokePowerShell = (command) => {
+        expectedCommand = command;
+        return 'unimportant command';
+      };
+      const logger = new LoggerStub();
+      const sut = new CommandBuilder()
+        .withLogger(logger)
+        .withPowerShellCommandCreator(powerShellCommandCreator)
+        .build();
+      // act
+      sut.buildShellCommand('unimportant');
+      // assert
+      expectExists(expectedCommand);
+      logger.assertLogsContainMessagePart('info', expectedCommand);
+    });
+    it('escapes the provided file path', () => {
+      // arrange
+      const expectedFilePath = '/input';
+      const escaper = new ShellArgumentEscaperStub();
+      const sut = new CommandBuilder()
+        .withEscaper(escaper)
+        .build();
+      // act
+      sut.buildShellCommand(expectedFilePath);
+      // assert
+      expect(escaper.callHistory).to.have.lengthOf(1);
+      const [actualFilePath] = escaper.callHistory[0].args;
+      expect(actualFilePath).to.equal(expectedFilePath);
+    });
+  });
+  describe('isExecutionTerminatedExternally', () => {
+    it('returns `false`', () => {
+      // arrange
+      const expectedValue = false;
+      const sut = new CommandBuilder().build();
+      // act
+      const actualValue = sut.isExecutionTerminatedExternally();
+      // assert
+      expect(expectedValue).to.equal(actualValue);
+    });
+  });
+  describe('isExecutablePermissionsRequiredOnFile', () => {
+    it('returns `false`', () => {
+      // arrange
+      const expectedValue = false;
+      const sut = new CommandBuilder().build();
+      // act
+      const actualValue = sut.isExecutablePermissionsRequiredOnFile();
+      // assert
+      expect(expectedValue).to.equal(actualValue);
+    });
+  });
+});
+
+class CommandBuilder {
+  private escaper: ShellArgumentEscaper = new ShellArgumentEscaperStub();
+
+  private logger: Logger = new LoggerStub();
+
+  private powerShellCommandCreator
+  : PowerShellInvokeShellCommandCreator = new PowerShellInvokeShellCommandCreatorStub();
+
+  public withEscaper(escaper: ShellArgumentEscaper): this {
+    this.escaper = escaper;
+    return this;
+  }
+
+  public withPowerShellCommandCreator(
+    powerShellCommandCreator: PowerShellInvokeShellCommandCreator,
+  ): this {
+    this.powerShellCommandCreator = powerShellCommandCreator;
+    return this;
+  }
+
+  public withLogger(logger: Logger): this {
+    this.logger = logger;
+    return this;
+  }
+
+  public build(): WindowsVisibleTerminalCommand {
+    return new WindowsVisibleTerminalCommand(
+      this.escaper,
+      this.powerShellCommandCreator,
+      this.logger,
+    );
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Factory/OsSpecificTerminalLaunchCommandFactory.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { OsSpecificTerminalLaunchCommandFactory } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Factory/OsSpecificTerminalLaunchCommandFactory';
+import type { RuntimeEnvironment } from '@/infrastructure/RuntimeEnvironment/RuntimeEnvironment';
+import { RuntimeEnvironmentStub } from '@tests/unit/shared/Stubs/RuntimeEnvironmentStub';
+import { AllSupportedOperatingSystems, type SupportedOperatingSystem } from '@tests/shared/TestCases/SupportedOperatingSystems';
+import type { CommandDefinition } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/CommandDefinition';
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import { WindowsVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/WindowsVisibleTerminalCommand';
+import type { Constructible } from '@/TypeHelpers';
+import { LinuxVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/LinuxVisibleTerminalCommand';
+import { MacOsVisibleTerminalCommand } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Commands/MacOsVisibleTerminalCommand';
+
+describe('OsSpecificTerminalLaunchCommandFactory', () => {
+  describe('returns expected definitions for supported operating systems', () => {
+    const testScenarios: Record<SupportedOperatingSystem, Constructible<CommandDefinition>> = {
+      [OperatingSystem.Windows]: WindowsVisibleTerminalCommand,
+      [OperatingSystem.Linux]: LinuxVisibleTerminalCommand,
+      [OperatingSystem.macOS]: MacOsVisibleTerminalCommand,
+    };
+    AllSupportedOperatingSystems.forEach((operatingSystem) => {
+      it(`${OperatingSystem[operatingSystem]}`, () => {
+        // arrange
+        const expectedDefinitionType = testScenarios[operatingSystem];
+        const context = new TestContext()
+          .withOperatingSystem(operatingSystem);
+        // act
+        const actualDefinition = context.provideCommandDefinition();
+        // assert
+        expect(actualDefinition).to.be.instanceOf(expectedDefinitionType);
+      });
+    });
+  });
+
+  it('throws if the current operating system is undefined', () => {
+    // arrange
+    const expectedError = 'Operating system could not be identified from environment.';
+    const operatingSystem = undefined;
+    const context = new TestContext()
+      .withOperatingSystem(operatingSystem);
+    // act
+    const act = () => context.provideCommandDefinition();
+    // assert
+    expect(act).to.throw(expectedError);
+  });
+
+  it('throws for an unsupported operating system', () => {
+    // arrange
+    const unsupportedOperatingSystem = OperatingSystem.BlackBerryOS;
+    const expectedError = `Unsupported operating system: ${OperatingSystem[unsupportedOperatingSystem]}`;
+    const context = new TestContext()
+      .withOperatingSystem(unsupportedOperatingSystem);
+    // act
+    const act = () => context.provideCommandDefinition();
+    // assert
+    expect(act).to.throw(expectedError);
+  });
+});
+
+class TestContext {
+  private environment: RuntimeEnvironment = new RuntimeEnvironmentStub();
+
+  public withOperatingSystem(os: OperatingSystem | undefined): this {
+    this.environment = new RuntimeEnvironmentStub()
+      .withOs(os);
+    return this;
+  }
+
+  public provideCommandDefinition(): ReturnType<
+  OsSpecificTerminalLaunchCommandFactory['provideCommandDefinition']
+  > {
+    const sut = new OsSpecificTerminalLaunchCommandFactory(this.environment);
+    return sut.provideCommandDefinition();
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ExecutableFileShellCommandDefinitionRunner.spec.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from 'vitest';
+import type { CommandDefinition } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/CommandDefinition';
+import { ExecutableFileShellCommandDefinitionRunner } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ExecutableFileShellCommandDefinitionRunner';
+import type { ExecutablePermissionSetter } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/PermissionSetter/ExecutablePermissionSetter';
+import type { ShellCommandOutcome, ShellCommandRunner } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/ShellRunner/ShellCommandRunner';
+import { CommandDefinitionStub } from '@tests/unit/shared/Stubs/CommandDefinitionStub';
+import { ExecutablePermissionSetterStub } from '@tests/unit/shared/Stubs/ExecutablePermissionSetterStub';
+import { ShellCommandRunnerStub } from '@tests/unit/shared/Stubs/ShellCommandRunnerStub';
+import type { ScriptFileExecutionOutcome } from '@/infrastructure/CodeRunner/Execution/ScriptFileExecutor';
+import type { CodeRunErrorType } from '@/application/CodeRunner/CodeRunner';
+import { expectExists } from '@tests/shared/Assertions/ExpectExists';
+
+describe('ExecutableFileShellCommandDefinitionRunner', () => {
+  describe('runCommandDefinition', () => {
+    describe('handling file permissions', () => {
+      describe('conditional permission settings', () => {
+        it('sets permissions when required', async () => {
+          // arrange
+          const requireExecutablePermissions = true;
+          const definition = new CommandDefinitionStub()
+            .withExecutablePermissionsRequirement(requireExecutablePermissions);
+          const permissionSetter = new ExecutablePermissionSetterStub();
+          const context = new TestContext()
+            .withCommandDefinition(definition)
+            .withExecutablePermissionSetter(permissionSetter);
+          // act
+          await context.runCommandDefinition();
+          // assert
+          expect(permissionSetter.callHistory).to.have.lengthOf(1);
+        });
+        it('does not set permissions when not required', async () => {
+          // arrange
+          const requireExecutablePermissions = false;
+          const definition = new CommandDefinitionStub()
+            .withExecutablePermissionsRequirement(requireExecutablePermissions);
+          const permissionSetter = new ExecutablePermissionSetterStub();
+          const context = new TestContext()
+            .withCommandDefinition(definition)
+            .withExecutablePermissionSetter(permissionSetter);
+          // act
+          await context.runCommandDefinition();
+          // assert
+          expect(permissionSetter.callHistory).to.have.lengthOf(0);
+        });
+      });
+      it('applies permissions to the correct file', async () => {
+        // arrange
+        const expectedFilePath = 'expected-file-path';
+        const permissionSetter = new ExecutablePermissionSetterStub();
+        const context = new TestContext()
+          .withFilePath(expectedFilePath)
+          .withCommandDefinition(createExecutableCommandDefinition())
+          .withExecutablePermissionSetter(permissionSetter);
+
+        // act
+        await context.runCommandDefinition();
+
+        // assert
+        const calls = permissionSetter.callHistory.filter((call) => call.methodName === 'makeFileExecutable');
+        expect(calls.length).to.equal(1);
+        const [actualFilePath] = calls[0].args;
+        expect(actualFilePath).to.equal(expectedFilePath);
+      });
+      it('executes command after setting permissions', async () => {
+        // arrange
+        const expectedFilePath = 'expected-file-path';
+        let isExecutedOnExecutableFile = false;
+        let isFileMadeExecutable = false;
+        const permissionSetter = new ExecutablePermissionSetterStub();
+        permissionSetter.methodCalls.on(() => {
+          isFileMadeExecutable = true;
+        });
+        const commandRunner = new ShellCommandRunnerStub();
+        commandRunner.methodCalls.on(() => {
+          isExecutedOnExecutableFile = isFileMadeExecutable;
+        });
+        const context = new TestContext()
+          .withFilePath(expectedFilePath)
+          .withCommandDefinition(createExecutableCommandDefinition())
+          .withCommandRunner(commandRunner)
+          .withExecutablePermissionSetter(permissionSetter);
+
+        // act
+        await context.runCommandDefinition();
+
+        // assert
+        expect(isExecutedOnExecutableFile).to.equal(true);
+      });
+      it('returns an error if permission setting fails', async () => {
+        // arrange
+        const expectedOutcome: ScriptFileExecutionOutcome = {
+          success: false,
+          error: {
+            type: 'FilePermissionChangeError',
+            message: 'Expected error',
+          },
+        };
+        const permissionSetter = new ExecutablePermissionSetterStub()
+          .withOutcome(expectedOutcome);
+        const context = new TestContext()
+          .withCommandDefinition(createExecutableCommandDefinition())
+          .withExecutablePermissionSetter(permissionSetter);
+
+        // act
+        const actualOutcome = await context.runCommandDefinition();
+
+        // assert
+        expect(expectedOutcome).to.equal(actualOutcome);
+      });
+    });
+    describe('interpreting shell outcomes', () => {
+      it('returns success for exit code 0', async () => {
+        // arrange
+        const expectedSuccessResult = true;
+        const permissionSetter = new ShellCommandRunnerStub()
+          .withOutcome({
+            type: 'RegularProcessExit',
+            exitCode: 0,
+          });
+        const context = new TestContext()
+          .withCommandDefinition(createExecutableCommandDefinition())
+          .withCommandRunner(permissionSetter);
+
+        // act
+        const outcome = await context.runCommandDefinition();
+
+        // assert
+        expect(outcome.success).to.equal(expectedSuccessResult);
+      });
+      describe('handling shell command failures', async () => {
+        const testScenarios: readonly {
+          readonly description: string;
+          readonly shellOutcome: ShellCommandOutcome;
+          readonly commandDefinition?: CommandDefinition;
+          readonly expectedErrorType: CodeRunErrorType;
+          readonly expectedErrorMessage: string;
+        }[] = [
+          {
+            description: 'non-zero exit code without external termination',
+            shellOutcome: {
+              type: 'RegularProcessExit',
+              exitCode: 20,
+            },
+            commandDefinition: new CommandDefinitionStub()
+              .withExternalTerminationStatusForExitCode(20, false),
+            expectedErrorType: 'FileExecutionError',
+            expectedErrorMessage: 'Unexpected exit code: 20.',
+          },
+          {
+            description: 'non-zero exit code with external termination',
+            shellOutcome: {
+              type: 'RegularProcessExit',
+              exitCode: 5,
+            },
+            commandDefinition: new CommandDefinitionStub()
+              .withExternalTerminationStatusForExitCode(5, true),
+            expectedErrorType: 'ExternalProcessTermination',
+            expectedErrorMessage: 'Process terminated externally: Exit code 5.',
+          },
+          {
+            description: 'external termination',
+            shellOutcome: {
+              type: 'ExternallyTerminated',
+              terminationSignal: 'SIGABRT',
+            },
+            expectedErrorType: 'ExternalProcessTermination',
+            expectedErrorMessage: 'Process terminated by signal SIGABRT.',
+          },
+          {
+            description: 'execution errors',
+            shellOutcome: {
+              type: 'ExecutionError',
+              error: new Error('Expected message'),
+            },
+            expectedErrorType: 'FileExecutionError',
+            expectedErrorMessage: 'Execution error: Expected message.',
+          },
+        ];
+        testScenarios.forEach(({
+          description, shellOutcome, expectedErrorType, expectedErrorMessage, commandDefinition,
+        }) => {
+          it(description, async () => {
+            // arrange
+            const permissionSetter = new ShellCommandRunnerStub()
+              .withOutcome(shellOutcome);
+            const context = new TestContext()
+              .withCommandDefinition(commandDefinition ?? createExecutableCommandDefinition())
+              .withCommandRunner(permissionSetter);
+
+            // act
+            const outcome = await context.runCommandDefinition();
+
+            // assert
+            expect(outcome.success).to.equal(false);
+            expectExists(outcome.error);
+            expect(outcome.error.message).to.contain(expectedErrorMessage);
+            expect(outcome.error.type).to.equal(expectedErrorType);
+          });
+        });
+      });
+    });
+  });
+});
+
+function createExecutableCommandDefinition(): CommandDefinition {
+  return new CommandDefinitionStub()
+    .withExecutablePermissionsRequirement(true);
+}
+
+class TestContext {
+  private executablePermissionSetter
+  : ExecutablePermissionSetter = new ExecutablePermissionSetterStub();
+
+  private shellCommandRunner
+  : ShellCommandRunner = new ShellCommandRunnerStub();
+
+  private commandDefinition: CommandDefinition = new CommandDefinitionStub();
+
+  private filePath: string = 'test-file-path';
+
+  public withFilePath(filePath: string): this {
+    this.filePath = filePath;
+    return this;
+  }
+
+  public withCommandRunner(
+    shellCommandRunner: ShellCommandRunner,
+  ): this {
+    this.shellCommandRunner = shellCommandRunner;
+    return this;
+  }
+
+  public withCommandDefinition(
+    commandDefinition: CommandDefinition,
+  ): this {
+    this.commandDefinition = commandDefinition;
+    return this;
+  }
+
+  public withExecutablePermissionSetter(
+    executablePermissionSetter: ExecutablePermissionSetter,
+  ): this {
+    this.executablePermissionSetter = executablePermissionSetter;
+    return this;
+  }
+
+  public runCommandDefinition(): ReturnType<
+  ExecutableFileShellCommandDefinitionRunner['runCommandDefinition']
+  > {
+    const sut = new ExecutableFileShellCommandDefinitionRunner(
+      this.executablePermissionSetter,
+      this.shellCommandRunner,
+    );
+    return sut.runCommandDefinition(
+      this.commandDefinition,
+      this.filePath,
+    );
+  }
+}

tests/unit/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/PermissionSetter/FileSystemExecutablePermissionSetter.spec.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest';
+import type { CodeRunErrorType } from '@/application/CodeRunner/CodeRunner';
+import type { Logger } from '@/application/Common/Log/Logger';
+import { FileSystemExecutablePermissionSetter } from '@/infrastructure/CodeRunner/Execution/CommandDefinition/Runner/PermissionSetter/FileSystemExecutablePermissionSetter';
+import type { ScriptFileExecutionOutcome } from '@/infrastructure/CodeRunner/Execution/ScriptFileExecutor';
+import type { SystemOperations } from '@/infrastructure/CodeRunner/System/SystemOperations';
+import { expectTrue } from '@tests/shared/Assertions/ExpectTrue';
+import { FileSystemOpsStub } from '@tests/unit/shared/Stubs/FileSystemOpsStub';
+import { LoggerStub } from '@tests/unit/shared/Stubs/LoggerStub';
+import { SystemOperationsStub } from '@tests/unit/shared/Stubs/SystemOperationsStub';
+import { expectExists } from '@tests/shared/Assertions/ExpectExists';
+
+describe('FileSystemExecutablePermissionSetter', () => {
+  describe('makeFileExecutable', () => {
+    it('sets permissions on the specified file', async () => {
+      // arrange
+      const expectedFilePath = 'expected-file-path';
+      const fileSystem = new FileSystemOpsStub();
+      const context = new TestContext()
+        .withFilePath(expectedFilePath)
+        .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+      // act
+      await context.makeFileExecutable();
+
+      // assert
+      const calls = fileSystem.callHistory.filter((call) => call.methodName === 'setFilePermissions');
+      expect(calls.length).to.equal(1);
+      const [actualFilePath] = calls[0].args;
+      expect(actualFilePath).to.equal(expectedFilePath);
+    });
+
+    it('applies the correct permissions mode', async () => {
+      // arrange
+      const expectedMode = '755';
+      const fileSystem = new FileSystemOpsStub();
+      const context = new TestContext()
+        .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+      // act
+      await context.makeFileExecutable();
+
+      // assert
+      const calls = fileSystem.callHistory.filter((call) => call.methodName === 'setFilePermissions');
+      expect(calls.length).to.equal(1);
+      const [, actualMode] = calls[0].args;
+      expect(actualMode).to.equal(expectedMode);
+    });
+
+    it('reports success when permissions are set without errors', async () => {
+      // arrange
+      const fileSystem = new FileSystemOpsStub();
+      fileSystem.setFilePermissions = () => Promise.resolve();
+      const context = new TestContext()
+        .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+      // act
+      const result = await context.makeFileExecutable();
+
+      // assert
+      expectTrue(result.success);
+      expect(result.error).to.equal(undefined);
+    });
+
+    describe('error handling', () => {
+      it('returns error expected error message when filesystem throws', async () => {
+        // arrange
+        const thrownErrorMessage = 'File system error';
+        const expectedErrorMessage = `Error setting script file permission: ${thrownErrorMessage}`;
+        const fileSystem = new FileSystemOpsStub();
+        fileSystem.setFilePermissions = () => Promise.reject(new Error(thrownErrorMessage));
+        const context = new TestContext()
+          .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+        // act
+        const result = await context.makeFileExecutable();
+
+        // assert
+        expect(result.success).to.equal(false);
+        expectExists(result.error);
+        expect(result.error.message).to.equal(expectedErrorMessage);
+      });
+
+      it('returns expected error type when filesystem throws', async () => {
+        // arrange
+        const expectedErrorType: CodeRunErrorType = 'FilePermissionChangeError';
+        const fileSystem = new FileSystemOpsStub();
+        fileSystem.setFilePermissions = () => Promise.reject(new Error('File system error'));
+        const context = new TestContext()
+          .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+        // act
+        const result = await context.makeFileExecutable();
+
+        // assert
+        expect(result.success).to.equal(false);
+        expectExists(result.error);
+        const actualErrorType = result.error.type;
+        expect(actualErrorType).to.equal(expectedErrorType);
+      });
+
+      it('logs error when filesystem throws', async () => {
+        // arrange
+        const thrownErrorMessage = 'File system error';
+        const logger = new LoggerStub();
+        const fileSystem = new FileSystemOpsStub();
+        fileSystem.setFilePermissions = () => Promise.reject(new Error(thrownErrorMessage));
+        const context = new TestContext()
+          .withLogger(logger)
+          .withSystemOperations(new SystemOperationsStub().withFileSystem(fileSystem));
+
+        // act
+        await context.makeFileExecutable();
+
+        // assert
+        logger.assertLogsContainMessagePart('error', thrownErrorMessage);
+      });
+    });
+  });
+});
+
+class TestContext {
+  private filePath = `[${TestContext.name}] /file/path`;
+
+  private systemOperations: SystemOperations = new SystemOperationsStub();
+
+  private logger: Logger = new LoggerStub();
+
+  public withFilePath(filePath: string): this {
+    this.filePath = filePath;
+    return this;
+  }
+
+  public withLogger(logger: Logger): this {
+    this.logger = logger;
+    return this;
+  }
+
+  public withSystemOperations(systemOperations: SystemOperations): this {
+    this.systemOperations = systemOperations;
+    return this;
+  }
+
+  public makeFileExecutable(): Promise<ScriptFileExecutionOutcome> {
+    const sut = new FileSystemExecutablePermissionSetter(
+      this.systemOperations,
+      this.logger,
+    );
+    return sut.makeFileExecutable(this.filePath);
+  }
+}