Add "Sideload Magisk Module" button (push .zip to a running instance)

[RobThePCGuy]

Problem

BlueStacks' in-app file picker hands Magisk/Kitsune a Windows-style URI that its module installer rejects with "Invalid Uri", so a module .zip on the Windows side can't be flashed from the picker.

Fix

A one-click "Sideload Magisk Module (.zip)" button that pushes the chosen module into a running instance's /sdcard/Download/ over BlueStacks' bundled ADB. The user then flashes it from Magisk/Kitsune's own storage picker (which reads guest storage fine): Modules → Install from storage → Download.

• adb_handler.py (new): finds HD-Adb.exe in the install dir, reads the target instance's adb_port from bluestacks.conf, connects, and pushes to /sdcard/Download/. Falls back to the sole attached device if the port isn't recorded yet. Surfaces clear errors ("start the instance…", "multiple instances running…", push failures).
• main.py: the button requires exactly one selected (running) instance, opens a file dialog, runs on the existing QThread worker like every other op, and shows the flash instructions in a dialog on success. Disabled while busy.

This is the only action in the app that needs the instance running (its ADB port must be open); everything else operates on shut-down disks.

Testing

14 offline unit tests for adb_handler (exe discovery, port parsing incl. no-substring-false-match, adb devices state parsing, push happy-path, missing file, no device reachable, push failure, and port-unknown → sole-device fallback) — all pass, using an injected runner so no real ADB/BlueStacks is needed. GUI builds headlessly; button is wired into the busy-state handling. py_compile clean; no new lint. The live push against a running instance is left for on-device verification.

[gemini-code-assist]

Code Review

This pull request introduces a new "Sideload Magisk Module" feature, allowing users to push module .zip files directly into a running BlueStacks instance's Download folder via ADB to bypass "Invalid Uri" errors. This includes the addition of adb_handler.py for ADB operations and UI updates in main.py to support the sideload action. The code review feedback suggests two key improvements in adb_handler.py: catching Exception instead of OSError when reading bluestacks.conf to prevent crashes from UnicodeDecodeError, and dynamically parsing the adb devices output instead of using a hardcoded slice index to handle potential daemon startup messages robustly.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When reading bluestacks.conf, open(..., encoding="utf-8") or iterating over the file can raise a UnicodeDecodeError if the file contains invalid UTF-8 bytes (e.g., due to corruption or a different encoding used by certain BlueStacks versions). Since UnicodeDecodeError inherits from ValueError (not OSError), it will bypass the except OSError: block and cause the application to crash.

We should catch Exception to ensure the application handles any read or decoding failures gracefully.

Suggested change

	except OSError:
	except Exception:

[gemini-code-assist]

Relying on a hardcoded slice index [1:] to skip the header line is fragile. If ADB outputs any daemon startup messages, warnings, or other diagnostic lines before "List of devices attached", the slice index will be incorrect, potentially skipping actual devices or attempting to parse daemon messages as device serials.

Instead, we should dynamically find the "List of devices attached" header line and only parse the lines following it.

Suggested change

	for line in stdout.splitlines()[1:]: # skip "List of devices attached"
	parts = line.split()
	if len(parts) >= 2 and parts[1] == "device":
	serials.append(parts[0])
	lines = stdout.splitlines()
	try:
	header_idx = next(i for i, line in enumerate(lines) if "List of devices attached" in line)
	device_lines = lines[header_idx + 1:]
	except StopIteration:
	device_lines = lines
	for line in device_lines:
	parts = line.split()
	if len(parts) >= 2 and parts[1] == "device":
	serials.append(parts[0])