feat(desktop): Add an isolated debug run script for desktop (#22912)

* feat(desktop): Add an isolated debug run script

Running the desktop client from source shares app data, the SSH agent
socket and the IPC socket with an installed client, so a debug session
corrupts the real profile and the two fight over the same sockets.

debug-start.js runs the same watch + Electron pipeline as start.js but
redirects every piece of host state into a repo-root .debug/ directory,
and reaps the whole pipeline on Ctrl+C so no orphan client survives.

* add vscode config

* address feedback around unrelated electron apps being stopped
This commit is contained in:
Bernd Schoolmann
2026-09-12 01:01:33 +09:00
committed by GitHub
parent e743c2c338
commit da69481f74
8 changed files with 161 additions and 2 deletions

0
.debug/.gitkeep Normal file
View File

5
.gitignore vendored
View File

@@ -62,3 +62,8 @@ apps/**/config/local.json
# DevContainer generated files
.devcontainer/native-gui/docker-compose.override.yml
.devcontainer/common/.env
# Debug run artifacts (profiles, sockets, browser downloads)
.debug/**
!.debug/**/
!.debug/**/.gitkeep

12
.vscode/launch.json vendored
View File

@@ -38,7 +38,7 @@
"request": "attach",
"name": "Desktop: Main (attach)",
"port": 5858,
"restart": true,
"restart": false,
"continueOnAttach": true,
"sourceMaps": true,
"outFiles": ["${workspaceFolder}/apps/desktop/build/**/*.js"],
@@ -73,6 +73,16 @@
"Desktop: Renderer (attach)",
"Desktop: Main desktop-native rust debugger (attach)"
]
},
{
"name": "Desktop: Start and debug",
"preLaunchTask": "desktop: debug start",
"configurations": [
"Desktop: Main (attach)",
"Desktop: Renderer (attach)",
"Desktop: Main desktop-native rust debugger (attach)"
],
"stopAll": true
}
]
}

33
.vscode/tasks.json vendored Normal file
View File

@@ -0,0 +1,33 @@
{
"version": "2.0.0",
"tasks": [
{
// Backing task for the "Desktop: Start and debug" compound: runs the isolated debug
// pipeline (webpack watchers + Electron) so the attach configurations have something
// to attach to.
"label": "desktop: debug start",
"type": "npm",
"script": "debug:desktop",
"path": "",
"isBackground": true,
"presentation": {
"reveal": "always",
"panel": "dedicated",
"clear": true
},
"problemMatcher": {
"owner": "desktop-debug",
// The pipeline's own output is already readable in the terminal; nothing here should
// land in the Problems panel, so the pattern is deliberately inert.
"pattern": [{ "regexp": "^$", "file": 1, "location": 2, "message": 3 }],
"background": {
"activeOnStart": true,
"beginsPattern": ".*Building OSS Desktop App.*",
// Electron's main process prints this once --inspect=5858 is listening, which is
// exactly when the debuggers can attach.
"endsPattern": ".*Debugger listening on ws.*"
}
}
}
]
}

View File

@@ -43,6 +43,7 @@
"electron": "node ./scripts/start.js",
"electron:beta": "cross-env CHANNEL=beta npm run electron",
"electron:ignore": "node ./scripts/start.js --ignore-certificate-errors",
"debug:electron": "node ./scripts/debug-start.js",
"flatpak:dev": "npm run clean:dist && electron-builder --dir -p never && flatpak-builder --force-clean --install --user ../../.flatpak/ ./resources/com.bitwarden.desktop.devel.yaml && flatpak run com.bitwarden.desktop",
"clean:dist": "rimraf ./dist",
"pack:dir": "npm run clean:dist && electron-builder --dir -p never",

View File

@@ -0,0 +1,107 @@
/* eslint-disable @typescript-eslint/no-require-imports */
////
// Same watch + Electron pipeline as start.js, but state is isolated in `.debug`
// so it does not interfere with the host system's bitwarden desktop installation.
//
// .debug/desktop-profile/ app data (vault, settings, logs)
// .debug/.bitwarden-ssh-agent.sock SSH agent socket
// .debug/s.<name> IPC sockets
////
const { execFileSync } = require("child_process");
const path = require("path");
const concurrently = require("concurrently");
// Absolute path to the Electron binary, so it can be `exec`d directly (see the Elec command).
const electronBinary = require("electron");
const rimraf = require("rimraf");
const args = process.argv.splice(2);
const DEBUG_DIR = path.resolve(__dirname, "../../..", ".debug");
process.env.BITWARDEN_APPDATA_DIR = path.join(DEBUG_DIR, "desktop-profile");
process.env.BITWARDEN_SSH_AUTH_SOCK = path.join(DEBUG_DIR, ".bitwarden-ssh-agent.sock");
process.env.BITWARDEN_IPC_SOCKET_DIR = DEBUG_DIR;
process.env.NODE_ENV = "development";
const INSPECT_FLAG = "--inspect=5858";
// `npm run electron` in this checkout runs the very same Electron binary (electron/cli.js just
// spawns `require("electron")`) with the same debug ports, so neither the binary path nor a port
// can tell the two sessions apart. This marker is what killStrayClients matches on. The main
// process only ever scans argv for known flags, so an extra one is inert.
const DEBUG_MARKER = "--bitwarden-debug-run";
const WEBPACK = path.resolve(__dirname, "../../../node_modules/.bin/webpack");
// `exec` replaces the shell with the child, so kill signals reach the child itself instead of a
// wrapper that leaves an orphan behind. cmd.exe has no equivalent, but concurrently reaps the
// whole tree there via `taskkill /F /T`.
const EXEC = process.platform === "win32" ? "" : "exec ";
function watchCommand(configName) {
return `${EXEC}"${WEBPACK}" --config webpack.config.js --config-name ${configName} --watch`;
}
function killStrayClients() {
try {
// Match on the marker, not just the binary: a plain `npm run electron` session runs the
// same binary against the real app data dir and must be left alone.
execFileSync("pkill", ["-9", "-f", `${electronBinary}.*${DEBUG_MARKER}`]);
} catch {
// pkill exits non-zero when nothing matched, and does not exist on Windows.
}
}
killStrayClients();
process.on("exit", killStrayClients);
rimraf.sync("build");
const { commands } = concurrently(
[
{
name: "Main",
command: `npm run build-native && ${watchCommand("main")}`,
prefixColor: "yellow",
},
{
name: "Prel",
command: watchCommand("preload"),
prefixColor: "magenta",
},
{
name: "Rend",
command: watchCommand("renderer"),
prefixColor: "cyan",
},
{
name: "Elec",
command: `npx wait-on ./build/main.js ./build/index.html ./build/app/main.js && ${EXEC}"${electronBinary}" --no-sandbox ${INSPECT_FLAG} --remote-debugging-port=9222 ${DEBUG_MARKER} ${args.join(
" ",
)} ./build`,
prefixColor: "green",
},
],
{
prefix: "name",
outputStream: process.stdout,
killOthersOn: ["success", "failure"],
// Electron ignores SIGINT/SIGTERM here (tray + quit handlers keep it alive), which left an
// orphan client running after Ctrl+C. Nothing in a debug run needs a graceful shutdown.
killSignal: "SIGKILL",
},
);
// Ctrl+C: reap the whole pipeline before leaving. Electron ignores the terminal's SIGINT, and the
// watchers only see it when they share the terminal's process group.
for (const signal of ["SIGINT", "SIGTERM"]) {
process.on(signal, () => {
commands.forEach((command) => command.kill("SIGKILL"));
killStrayClients();
process.exit(0);
});
}

View File

@@ -753,6 +753,7 @@ export default tseslint.config(
"**/dist/",
"**/coverage/",
".angular/",
".debug/",
"storybook-static/",
"**/node_modules/",

View File

@@ -40,7 +40,9 @@
"icons:build": "ts-node scripts/material-icons/build-with-bwi-names.ts",
"icons:migrate": "ts-node scripts/material-icons/migrate-icon-names.ts",
"icons:reverse-migrate": "ts-node scripts/material-icons/reverse-migrate-icon-names.ts",
"dev:reverse-proxy": "node --experimental-strip-types scripts/reverse-proxy-emulator/index.ts"
"dev:reverse-proxy": "node --experimental-strip-types scripts/reverse-proxy-emulator/index.ts",
"debug:desktop": "npm run debug:electron --workspace @bitwarden/desktop",
"debug:desktop:automation": "cross-env USE_AUTOMATION_BIOMETRICS=true npm run debug:desktop"
},
"workspaces": [
"apps/*",