fixed a bug where electron.backup.exe was getting poisoned and added a clear-electron-debug-identity command (#248)

Co-authored-by: Nikola Metulev <711864+nmetulev@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Alexandre Zollinger Chohfi <alzollin@microsoft.com>

Author: 3 people

README.md

@@ -151,6 +151,7 @@ npx winapp --help
 
 - [`node create-addon`](./docs/usage.md#node-create-addon) - Generate native C# or C++ addons
 - [`node add-electron-debug-identity`](./docs/usage.md#node-add-electron-debug-identity) - Add identity to Electron processes
+- [`node clear-electron-debug-identity`](./docs/usage.md#node-clear-electron-debug-identity) - Remove identity from Electron processes
 - [Windows AI Addon for Electron](https://github.com/microsoft/winapp-windows-ai) - The Windows AI Addon for Electron is a Node.js native addon that provides access to the [Windows AI APIs](https://learn.microsoft.com/en-us/windows/ai/apis/) directly from JavaScript.
 
 The full CLI usage can be found here: [Documentation](/docs/usage.md)

docs/guides/electron/setup.md

@@ -193,9 +193,9 @@ Add the `--no-sandbox` flag to your start script in `package.json`. This works a
 **Important:** This issue does **not** affect full MSIX packaging - only debug identity during development.
 
 **To undo debug identity** (if needed for troubleshooting):
-1. Navigate to `node_modules\electron\dist\` in your project
-2. Delete `electron.exe`
-3. Rename `electron.backup.exe` to `electron.exe`
+```bash
+npx winapp node clear-electron-debug-identity
+```
 
 This restores the original Electron executable without the debug identity.
 

docs/usage.md

@@ -444,7 +444,7 @@ npx winapp node create-addon --name myWindowsAddon
 > [!IMPORTANT]  
 > There is a known issue with sparse packaging Electron applications which causes the app to crash on start or not render the web content. The issue has been fixed in Windows but it has not propagated to external Windows devices yet. If you are seeing this issue after calling `add-electron-debug-identity`, you can [disable sandboxing in your Electron app](https://www.electronjs.org/docs/latest/tutorial/sandbox#disabling-chromiums-sandbox-testing-only) for debug purposes with the `--no-sandbox` flag. This issue does not affect full MSIX packaging.
 <br /><br />
-To undo the Electron debug identity, the easiest approach is to clear your node_modules folder (or just the electron folder) and run `npm install` again.
+To undo the Electron debug identity, use `winapp node clear-electron-debug-identity`.
 
 ```bash
 npx winapp node add-electron-debug-identity [options]
@@ -465,6 +465,35 @@ npx winapp node add-electron-debug-identity
 
 ---
 
+### node clear-electron-debug-identity
+
+*(Available in NPM package only)* Remove package identity from the Electron debug process by restoring the original electron.exe from backup.
+
+```bash
+npx winapp node clear-electron-debug-identity [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--verbose` | Enable verbose output |
+
+**What it does:**
+
+- Restores electron.exe from the backup created by `add-electron-debug-identity`
+- Removes the backup files after restoration
+- Returns Electron to its original state without package identity
+
+**Examples:**
+
+```bash
+# Remove identity from Electron development process
+npx winapp node clear-electron-debug-identity
+```
+
+---
+
 ### Global Options
 
 All commands support these global options:

src/winapp-CLI/WinApp.Cli/Commands/CreateDebugIdentityCommand.cs

@@ -67,10 +67,10 @@ public override async Task<int> InvokeAsync(ParseResult parseResult, Cancellatio
                 }
                 catch (Exception error)
                 {
-                    return (1, $"{UiSymbols.Error} Failed to add MSIX identity: {error.Message}");
+                    return (1, $"{UiSymbols.Error} Failed to add package identity: {error.Message}");
                 }
 
-                return (0, "MSIX identity created successfully.");
+                return (0, "Package identity created successfully.");
             }, cancellationToken);
         }
     }

src/winapp-CLI/WinApp.Cli/Services/MsixService.cs

@@ -224,7 +224,7 @@ public static async Task<MsixIdentityResult> ParseAppxManifestFromPathAsync(File
             throw new FileNotFoundException($"AppX manifest not found at: {appxManifestPath}");
         }
 
-        // Read and extract MSIX identity from appxmanifest.xml
+        // Read and extract package identity from appxmanifest.xml
         var appxManifestContent = await File.ReadAllTextAsync(appxManifestPath.FullName, Encoding.UTF8, cancellationToken);
 
         return ParseAppxManifestAsync(appxManifestContent);

src/winapp-npm/src/cli.ts

@@ -2,7 +2,7 @@
 
 import { generateCppAddonFiles } from './cpp-addon-utils';
 import { generateCsAddonFiles } from './cs-addon-utils';
-import { addElectronDebugIdentity } from './msix-utils';
+import { addElectronDebugIdentity, clearElectronDebugIdentity } from './msix-utils';
 import { getWinappCliPath, callWinappCli, WINAPP_CLI_CALLER_VALUE } from './winapp-cli-utils';
 import { spawn } from 'child_process';
 import * as fs from 'fs';
@@ -125,12 +125,14 @@ async function showCombinedHelp(): Promise<void> {
   console.log('');
   console.log('Node.js Subcommands:');
   console.log('  node create-addon         Generate native addon files for Electron');
-  console.log('  node add-electron-debug-identity  Add MSIX identity to Electron debug process');
+  console.log('  node add-electron-debug-identity  Add package identity to Electron debug process');
+  console.log('  node clear-electron-debug-identity  Remove package identity from Electron debug process');
   console.log('');
   console.log('Examples:');
   console.log(`  ${CLI_NAME} node create-addon --name myAddon`);
   console.log(`  ${CLI_NAME} node create-addon --template cs --name myAddon`);
   console.log(`  ${CLI_NAME} node add-electron-debug-identity`);
+  console.log(`  ${CLI_NAME} node clear-electron-debug-identity`);
 }
 
 async function showVersion(): Promise<void> {
@@ -186,14 +188,16 @@ async function handleNode(args: string[]): Promise<void> {
     console.log('Node.js-specific commands');
     console.log('');
     console.log('Subcommands:');
-    console.log('  create-addon                Generate native addon files for Electron');
-    console.log('  add-electron-debug-identity Add MSIX identity to Electron debug process');
+    console.log('  create-addon                  Generate native addon files for Electron');
+    console.log('  add-electron-debug-identity   Add package identity to Electron debug process');
+    console.log('  clear-electron-debug-identity Remove package identity from Electron debug process');
     console.log('');
     console.log('Examples:');
     console.log(`  ${CLI_NAME} node create-addon --help`);
     console.log(`  ${CLI_NAME} node create-addon --name myAddon`);
     console.log(`  ${CLI_NAME} node create-addon --name myCsAddon --template cs`);
     console.log(`  ${CLI_NAME} node add-electron-debug-identity`);
+    console.log(`  ${CLI_NAME} node clear-electron-debug-identity`);
     console.log('');
     console.log(`Use "${CLI_NAME} node <subcommand> --help" for detailed help on each subcommand.`);
     return;
@@ -211,6 +215,10 @@ async function handleNode(args: string[]): Promise<void> {
       await handleAddonElectronDebugIdentity(subcommandArgs);
       break;
 
+    case 'clear-electron-debug-identity':
+      await handleClearElectronDebugIdentity(subcommandArgs);
+      break;
+
     default:
       console.error(`❌ Unknown node subcommand: ${subcommand}`);
       console.error(`Run "${CLI_NAME} node" for available subcommands.`);
@@ -340,14 +348,14 @@ async function handleAddonElectronDebugIdentity(args: string[]): Promise<void> {
   if (options.help) {
     console.log(`Usage: ${CLI_NAME} node add-electron-debug-identity [options]`);
     console.log('');
-    console.log('Add MSIX identity to Electron debug process');
+    console.log('Add package identity to Electron debug process');
     console.log('');
     console.log('This command will:');
     console.log('  1. Create a backup of node_modules/electron/dist/electron.exe');
     console.log(
       '  2. Generate a sparse MSIX manifest in .winapp/debug folder, and assets in node_modules/electron/dist/ folder'
     );
-    console.log('  3. Add MSIX identity to the Electron executable');
+    console.log('  3. Add package identity to the Electron executable');
     console.log('  4. Register the sparse package with external location');
     console.log('');
     console.log('Options:');
@@ -372,6 +380,46 @@ async function handleAddonElectronDebugIdentity(args: string[]): Promise<void> {
   }
 }
 
+async function handleClearElectronDebugIdentity(args: string[]): Promise<void> {
+  const options = parseArgs(args, {
+    verbose: false,
+  });
+
+  if (options.help) {
+    console.log(`Usage: ${CLI_NAME} node clear-electron-debug-identity [options]`);
+    console.log('');
+    console.log('Remove package identity from Electron debug process');
+    console.log('');
+    console.log('This command will:');
+    console.log('  1. Restore electron.exe from the backup created by add-electron-debug-identity');
+    console.log('  2. Remove the backup files');
+    console.log('');
+    console.log('Options:');
+    console.log('  --verbose             Enable verbose output (default: false)');
+    console.log('  --help                Show this help');
+    console.log('');
+    console.log('Note: This command must be run from the root of an Electron project');
+    console.log('      (directory containing node_modules/electron)');
+    return;
+  }
+
+  try {
+    const result = await clearElectronDebugIdentity({
+      verbose: options.verbose as boolean,
+    });
+
+    if (result.restoredFromBackup) {
+      console.log(`✅ Electron debug identity cleared successfully!`);
+    } else {
+      console.log(`ℹ️  No backup found - electron.exe may already be clean.`);
+    }
+  } catch (error) {
+    const err = error as Error;
+    console.error(`❌ Failed to clear Electron debug identity: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 function parseArgs(args: string[], defaults: ParsedArgs = {}): ParsedArgs {
   const result: ParsedArgs = { ...defaults };
 

src/winapp-npm/src/index.ts

@@ -1,13 +1,18 @@
 // Main entry point for the Windows SDK BuildTools package
 import { execSyncWithBuildTools } from './buildtools-utils';
-import { addMsixIdentityToExe, addElectronDebugIdentity } from './msix-utils';
+import { addMsixIdentityToExe, addElectronDebugIdentity, clearElectronDebugIdentity } from './msix-utils';
 import { getGlobalWinappPath, getLocalWinappPath } from './winapp-path-utils';
 
 // Re-export types from child_process for convenience
 export type { ExecSyncOptions } from 'child_process';
 
 // Re-export types
-export { MsixIdentityOptions, MsixIdentityResult, ElectronDebugIdentityResult } from './msix-utils';
+export {
+  MsixIdentityOptions,
+  MsixIdentityResult,
+  ElectronDebugIdentityResult,
+  ClearElectronDebugIdentityResult,
+} from './msix-utils';
 export { CallWinappCliOptions, CallWinappCliResult } from './winapp-cli-utils';
 export { GenerateCppAddonOptions, GenerateCppAddonResult } from './cpp-addon-utils';
 export { GenerateCsAddonOptions, GenerateCsAddonResult } from './cs-addon-utils';
@@ -20,6 +25,7 @@ export {
   // MSIX manifest utilities
   addMsixIdentityToExe,
   addElectronDebugIdentity,
+  clearElectronDebugIdentity,
 
   // winapp directory utilities
   getGlobalWinappPath,
@@ -31,6 +37,7 @@ export default {
   execWithBuildTools: execSyncWithBuildTools,
   addMsixIdentityToExe,
   addElectronDebugIdentity,
+  clearElectronDebugIdentity,
   getGlobalWinappPath,
   getLocalWinappPath,
 };