Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
53 commits
Select commit Hold shift + click to select a range
5a4ecbc
feat(installer): preserve Explorer context menu selections
WilliamWang1721 Oct 3, 2026
a80783a
test(installer): adapt identity and native checklist checks
WilliamWang1721 Oct 3, 2026
d74d66b
test(installer): capture painted native checklist states
WilliamWang1721 Oct 3, 2026
f559d14
fix(installer): preserve unknown WSL verb descendants
WilliamWang1721 Oct 3, 2026
9b3d2b3
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 4, 2026
59fcb75
Merge upstream main into PR branch
WilliamWang1721 Oct 4, 2026
5576773
Merge upstream main into PR branch
WilliamWang1721 Oct 4, 2026
2341bb5
Merge branch 'main' into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 6, 2026
c281590
ci: rerun native tests after unrelated flaky failure
WilliamWang1721 Oct 6, 2026
bf75c93
Merge main into codex/issue-218-explorer-shell-selection
claude Oct 9, 2026
7f5386c
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 11, 2026
ec17079
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 11, 2026
831bd08
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 13, 2026
7e8f04e
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 13, 2026
fa781f5
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 14, 2026
993329c
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 14, 2026
1bfee13
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 14, 2026
718b6e2
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 15, 2026
9fe09c0
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 15, 2026
21740a1
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 16, 2026
3defa20
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 17, 2026
22cc73c
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 19, 2026
6b35bf6
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 21, 2026
8d1de41
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 21, 2026
b6fc8fa
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 22, 2026
f43794d
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 23, 2026
93bff0b
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 23, 2026
4509a9b
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 23, 2026
d922621
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 24, 2026
f17c904
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 24, 2026
1f0d382
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 25, 2026
7f881af
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 26, 2026
1b41efd
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 26, 2026
129f14e
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 27, 2026
54dd7fd
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 28, 2026
e28f99c
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 28, 2026
234b9cb
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 30, 2026
69611a3
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Oct 31, 2026
426bbfe
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 1, 2026
707caf3
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 2, 2026
88b7f5f
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 3, 2026
66c47ad
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 4, 2026
f4ad4a2
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 4, 2026
caa37e1
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 4, 2026
fc03814
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 17, 2026
6e7218d
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 17, 2026
daf3206
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 19, 2026
d6bc3c4
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 19, 2026
1edcc0c
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 20, 2026
1facce4
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 20, 2026
a12c6d4
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 21, 2026
94f0ca7
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 21, 2026
357b7c4
Merge upstream main into codex/issue-218-explorer-shell-selection
WilliamWang1721 Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Preserve Explorer menu choices across installer runs

## Status

Implemented; pending review and remote validation.

## Context

Issue [#218](https://github.com/Kuddev/pebrel/issues/218) requests individual
Explorer entries and a master switch, available during installation or in
settings. The current installer owns both the ordinary entry and the existing
WSL cascade; it registers every discovered distribution on each installation.

## Evidence

[`installer.iss`](../../../scripts/installer.iss) previously wrote the ordinary
entry unconditionally. [`installer-migration.iss`](../../../scripts/installer-migration.iss)
already discovers distributions through Lxss, excludes Docker plumbing, and
protects WSL registration with executable ownership checks. The application
does not have an Explorer-registration settings adapter.

## Decision

Use one native installer checklist for the master switch, ordinary entry and
discovered WSL distributions. Re-running the installer edits the selection.
Keep the existing WSL cascade and commands. Persist DWORD choices under
`HKCU\Software\Pebrel\ExplorerMenu`, independently of application preferences.
The ordinary entry continues to launch the configured default shell.

`Enabled` controls integration, `Default` controls the ordinary entry, and
`wsl:<distribution name>` records each distribution independently of enumeration
order. Absent choices inherit the existing all-enabled behavior until `Saved`
exists. Subsequently new distributions default to unchecked. Retain absent
distribution values so reinstalling a distribution restores its choice. Silent
upgrades read the same values. Turning the master off preserves individual values.

Remove unconditional ordinary registry writes. Reconcile both Explorer roots
using exact ordinary command ownership and the existing WSL owner validation.
Keep foreign commands and unknown child subtrees; conflicting registration fails
visibly. Save the selection after the registrations succeed.

Executable ownership alone cannot authorize recursive deletion: the previous
WSL check accepted a verb whose command still belonged to Pebrel even when a
user added descendants below the verb or its `command` key. A shared structural
check now requires one `command` child and no descendants below it for ordinary,
WSL cascade and legacy flat verbs. Unknown descendants preserve the whole menu.

## Rejected alternatives

- A second registry adapter in the application duplicates installer ownership
and requires settings/startup coordination without being necessary for the
issue's installation option.
- Index-based preference names would attach choices to a different distribution
after enumeration changes.
- A new menu hierarchy is unnecessary: the existing WSL cascade is retained.
- Unconditionally writing menu keys during upgrades loses the user's selection.

## Consequences

These choices apply to the Inno installation channel, and take effect when the
installer completes. Changing them requires re-running the installer. This does
not add individual local-shell launch verbs, nor MSIX/Scoop integration.
Preferences survive uninstall, matching the retained user-configuration policy.
Legacy Inno uninstall logs may still contain the former ordinary entry's
`uninsdeletekey` action; this change does not rewrite historical uninstall logs.

## Validation

The maintained Inno fixture uses only `HKCU\Software\PebrelTestFixtures`.
It covers both cwd arguments, add/remove, master disable/restore, persistence,
enumeration changes, new distributions and foreign/edited keys. The Windows
input fixture drives the production checklist with mouse and keyboard events,
checks registered results and captures its states. Remote execution and visual
review are required; fixture compilation is not Explorer launch acceptance.
The unknown-descendant regression covers both verb/command levels in both roots,
for all-WSL deselection, master disable, legacy flat removal and submenu rebuild.

## Supersedes

The all-distributions registration policy in
[`2026-09-23-wsl-context-menu-cascade.md`](2026-09-23-wsl-context-menu-cascade.md).
The cascade layout and ownership policy remain.

## Revisit when

Users need to change integration without running the installer, or another
installation channel requires the same registration ownership.
151 changes: 151 additions & 0 deletions scripts/installer-context-menu.iss
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
// Explorer choices belong to the installer, alongside its owned registrations.
var
ExplorerMenuPage: TInputOptionWizardPage;
ExplorerMenuDistros: TArrayOfString;
ExplorerMenuSettings: string;

function ExplorerMenuChoice(Key, Name: string; Default: Boolean): Boolean;
var
Value: Cardinal;
begin
Result := Default;
if RegQueryDWordValue(HKCU, Key, Name, Value) then
Result := Value <> 0;
end;

procedure ExplorerMenuSelectionChanged(Sender: TObject);
var
Index: Integer;
begin
for Index := 1 to ExplorerMenuPage.CheckListBox.Items.Count - 1 do
ExplorerMenuPage.CheckListBox.ItemEnabled[Index] := ExplorerMenuPage.Values[0];
end;

procedure CreateExplorerMenuPage(SettingsKey: string; Distros: TArrayOfString);
var
Index: Integer;
InitialSelection: Boolean;
begin
ExplorerMenuSettings := SettingsKey;
ExplorerMenuDistros := Distros;
InitialSelection := not RegValueExists(HKCU, SettingsKey, 'Saved');
ExplorerMenuPage := CreateInputOptionPage(wpSelectDir,
CustomMessage('ExplorerMenuTitle'), CustomMessage('ExplorerMenuDescription'),
CustomMessage('ExplorerMenuHelp'), False, True);
ExplorerMenuPage.Add(CustomMessage('ExplorerMenuEnabled'));
ExplorerMenuPage.Values[0] := ExplorerMenuChoice(SettingsKey, 'Enabled', True);
ExplorerMenuPage.Add(CustomMessage('OpenInPebrel'));
ExplorerMenuPage.Values[1] := ExplorerMenuChoice(SettingsKey, 'Default', True);
for Index := 0 to GetArrayLength(Distros) - 1 do begin
ExplorerMenuPage.Add(CustomMessage('OpenInPebrel') + ' (' + Distros[Index] + ')');
ExplorerMenuPage.Values[Index + 2] :=
ExplorerMenuChoice(SettingsKey, 'wsl:' + Distros[Index], InitialSelection);
end;
ExplorerMenuPage.CheckListBox.OnClickCheck := @ExplorerMenuSelectionChanged;
ExplorerMenuSelectionChanged(nil);
end;

procedure SaveExplorerMenuChoices;
var
Index: Integer;
begin
if not RegWriteDWordValue(HKCU, ExplorerMenuSettings, 'Enabled',
Ord(ExplorerMenuPage.Values[0])) or
not RegWriteDWordValue(HKCU, ExplorerMenuSettings, 'Default',
Ord(ExplorerMenuPage.Values[1])) then
RaiseException(CustomMessage('ExplorerMenuFailed'));
for Index := 0 to GetArrayLength(ExplorerMenuDistros) - 1 do
if not RegWriteDWordValue(HKCU, ExplorerMenuSettings, 'wsl:' + ExplorerMenuDistros[Index],
Ord(ExplorerMenuPage.Values[Index + 2])) then
RaiseException(CustomMessage('ExplorerMenuFailed'));
if not RegWriteDWordValue(HKCU, ExplorerMenuSettings, 'Saved', 1) then
RaiseException(CustomMessage('ExplorerMenuFailed'));
end;

function SelectedExplorerMenuDistros: TArrayOfString;
var
Index, Count: Integer;
begin
SetArrayLength(Result, GetArrayLength(ExplorerMenuDistros));
Count := 0;
if ExplorerMenuPage.Values[0] then
for Index := 0 to GetArrayLength(ExplorerMenuDistros) - 1 do
if ExplorerMenuPage.Values[Index + 2] then begin
Result[Count] := ExplorerMenuDistros[Index];
Count := Count + 1;
end;
SetArrayLength(Result, Count);
end;

function DefaultExplorerMenuCommand(Executable, DirectoryArgument: string): string;
begin
Result := '"' + Executable + '" --gpui --working-directory "' + DirectoryArgument + '"';
end;

function IsOwnedDefaultExplorerMenu(Key, Command: string): Boolean;
var
Existing: string;
begin
Result := IsSingleCommandVerb(Key) and
RegQueryStringValue(HKCU, Key + '\command', '', Existing) and
(CompareText(Existing, Command) = 0);
end;

procedure UpdateDefaultExplorerMenuAt(Root, Executable, DirectoryArgument: string;
Enabled: Boolean);
var
Key, Command: string;
begin
Key := Root + '\Pebrel';
Command := DefaultExplorerMenuCommand(Executable, DirectoryArgument);
if RegKeyExists(HKCU, Key) then begin
if not IsOwnedDefaultExplorerMenu(Key, Command) then begin
if Enabled then
RaiseException(FmtMessage(CustomMessage('ExplorerMenuConflict'), [Key]));
Exit;
end;
if not Enabled then begin
RemoveOwnedContextMenu(Key, Command);
Exit;
end;
end;
if not Enabled then
Exit;
if not RegWriteStringValue(HKCU, Key, 'MUIVerb', CustomMessage('OpenInPebrel')) or
not RegWriteStringValue(HKCU, Key, 'Icon', Executable + ',0') or
not RegWriteStringValue(HKCU, Key + '\command', '', Command) then
RaiseException(CustomMessage('ExplorerMenuFailed'));
end;

procedure UpdateExplorerMenusAt(Root, Executable, DirectoryArgument: string);
var
Distros: TArrayOfString;
begin
Distros := SelectedExplorerMenuDistros;
if GetArrayLength(Distros) > 0 then
RegisterWslContextMenuAt(Root, Executable, DirectoryArgument, Distros)
else
RemoveOwnedWslContextMenusAt(Root, Executable);
UpdateDefaultExplorerMenuAt(Root, Executable, DirectoryArgument,
ExplorerMenuPage.Values[0] and ExplorerMenuPage.Values[1]);
end;

procedure RegisterExplorerContextMenus;
var
Executable: string;
begin
Executable := ExpandConstant('{app}\pebrel.exe');
UpdateExplorerMenusAt('Software\Classes\Directory\shell', Executable, '%1');
UpdateExplorerMenusAt('Software\Classes\Directory\Background\shell', Executable, '%V');
SaveExplorerMenuChoices;
end;

procedure RemoveOwnedExplorerContextMenus;
var
Executable: string;
begin
Executable := ExpandConstant('{app}\pebrel.exe');
RemoveOwnedWslContextMenus;
UpdateDefaultExplorerMenuAt('Software\Classes\Directory\shell', Executable, '%1', False);
UpdateDefaultExplorerMenuAt('Software\Classes\Directory\Background\shell', Executable, '%V', False);
end;
42 changes: 20 additions & 22 deletions scripts/installer-migration.iss
Original file line number Diff line number Diff line change
Expand Up @@ -102,18 +102,6 @@ begin
ExpandConstant('{localappdata}\Programs\Pebrel'));
end;

procedure InitializeWizard;
begin
{ Reuse the registered directory for normal upgrades, so Inno recognizes it
as an existing installation. Keep the old-brand relocation suggestion and
an explicit /DIR selection intact. }
if (PreviousInstallDir <> '') and
(CompareText(ExtractFileName(NormalizedDirectory(PreviousInstallDir)), 'Nebula Terminal') = 0) and
(ExpandConstant('{param:DIR|}') = '') then
WizardForm.DirEdit.Text := SuggestedInstallDir(PreviousInstallDir,
ExpandConstant('{localappdata}\Programs\Pebrel'));
end;

procedure DiscoverLegacyInstallation;
var
Pending, UninstallCommand: string;
Expand Down Expand Up @@ -428,17 +416,26 @@ begin
end;
end;

procedure RegisterWslContextMenus;
var
Distros: TArrayOfString;
Executable: string;
#include "installer-context-menu.iss"

#ifndef MigrationFixture
procedure InitializeWizard;
begin
Distros := WslDistroNames;
Executable := ExpandConstant('{app}\pebrel.exe');
RegisterWslContextMenuAt('Software\Classes\Directory\shell', Executable, '%1', Distros);
RegisterWslContextMenuAt('Software\Classes\Directory\Background\shell', Executable, '%V', Distros);
{ Reuse the registered directory for normal upgrades, so Inno recognizes it
as an existing installation. Keep the old-brand relocation suggestion and
an explicit /DIR selection intact. }
if (PreviousInstallDir <> '') and
(CompareText(ExtractFileName(NormalizedDirectory(PreviousInstallDir)), 'Nebula Terminal') = 0) and
(ExpandConstant('{param:DIR|}') = '') then
WizardForm.DirEdit.Text := SuggestedInstallDir(PreviousInstallDir,
ExpandConstant('{localappdata}\Programs\Pebrel'));
#ifndef AcceptanceFixture
CreateExplorerMenuPage(ProductSettingsKey + '\ExplorerMenu', WslDistroNames);
#endif
end;

#endif

procedure MigrateLegacyIntegrations;
var
Executable, ExistingPath, Key: string;
Expand Down Expand Up @@ -508,8 +505,9 @@ procedure CurStepChanged(CurStep: TSetupStep);
begin
if CurStep <> ssPostInstall then
Exit;
{ 与旧版迁移无关,装完就要做:菜单项取决于本机装了哪些 WSL 发行版。 }
RegisterWslContextMenus;
#ifndef AcceptanceFixture
RegisterExplorerContextMenus;
#endif
if LegacyInstallDir = '' then
Exit;
try
Expand Down
23 changes: 14 additions & 9 deletions scripts/installer.iss
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,19 @@ chinesesimplified.MigrationFailed=Pebrel 已安装,但旧安装未能完全迁
chinesesimplified.MigrationPreflightFailed=无法检查旧安装:%1。尚未开始安装。
chinesesimplified.RemovePathFailed=无法从 PATH 中移除 Pebrel 安装目录。

english.ExplorerMenuTitle=Explorer context menu
english.ExplorerMenuDescription=Choose which Pebrel entries appear in Explorer.
english.ExplorerMenuHelp=Run this installer again to change these choices. Upgrades keep your selection. New WSL distributions start unchecked after you save a selection.
english.ExplorerMenuEnabled=Enable Explorer context menu integration
english.ExplorerMenuConflict=An existing Pebrel context menu belongs to another installation or was edited, so it was preserved: %1.
english.ExplorerMenuFailed=Unable to update Explorer context menu entries or save your selection.
chinesesimplified.ExplorerMenuTitle=资源管理器右键菜单
chinesesimplified.ExplorerMenuDescription=选择在资源管理器中显示哪些 Pebrel 入口。
chinesesimplified.ExplorerMenuHelp=重新运行此安装器即可修改选项。升级会保留选择;保存选择后,新安装的 WSL 发行版默认不勾选。
chinesesimplified.ExplorerMenuEnabled=启用资源管理器右键菜单集成
chinesesimplified.ExplorerMenuConflict=现有 Pebrel 右键菜单属于其他安装或已被修改,因此已保留:%1。
chinesesimplified.ExplorerMenuFailed=无法更新资源管理器右键菜单或保存选择。

[Tasks]
#ifndef AcceptanceFixture
Name: "installfont"; Description: "{cm:InstallFont}"
Expand Down Expand Up @@ -157,14 +170,6 @@ Root: HKCU; Subkey: "Software\Pebrel"; ValueType: dword; ValueName: "InstallerAd
Root: HKCU; Subkey: "Environment"; ValueType: expandsz; ValueName: "Path"; ValueData: "{olddata};{app}"; Tasks: addtopath; Check: NeedsAddToPath; Flags: preservestringtype
Root: HKCU; Subkey: "Software\Microsoft\Windows\CurrentVersion\App Paths\pebrel.exe"; ValueType: string; ValueName: ""; ValueData: "{app}\pebrel.exe"; Flags: uninsdeletekey
Root: HKCU; Subkey: "Software\Microsoft\Windows\CurrentVersion\App Paths\pebrel.exe"; ValueType: string; ValueName: "Path"; ValueData: "{app}"
; 目录背景使用 %V,选中的目录对象使用 %1;两者必须由 Explorer 展开后再交给 CLI。
; 每个动词使用独立的应用子键,卸载时只删除 Pebrel 自己注册的菜单。
Root: HKCU; Subkey: "Software\Classes\Directory\Background\shell\Pebrel"; ValueType: string; ValueName: "MUIVerb"; ValueData: "{cm:OpenInPebrel}"; Flags: uninsdeletekey
Root: HKCU; Subkey: "Software\Classes\Directory\Background\shell\Pebrel"; ValueType: string; ValueName: "Icon"; ValueData: "{app}\pebrel.exe,0"
Root: HKCU; Subkey: "Software\Classes\Directory\Background\shell\Pebrel\command"; ValueType: string; ValueName: ""; ValueData: """{app}\pebrel.exe"" --gpui --working-directory ""%V"""
Root: HKCU; Subkey: "Software\Classes\Directory\shell\Pebrel"; ValueType: string; ValueName: "MUIVerb"; ValueData: "{cm:OpenInPebrel}"; Flags: uninsdeletekey
Root: HKCU; Subkey: "Software\Classes\Directory\shell\Pebrel"; ValueType: string; ValueName: "Icon"; ValueData: "{app}\pebrel.exe,0"
Root: HKCU; Subkey: "Software\Classes\Directory\shell\Pebrel\command"; ValueType: string; ValueName: ""; ValueData: """{app}\pebrel.exe"" --gpui --working-directory ""%1"""
#endif

[Run]
Expand Down Expand Up @@ -200,7 +205,7 @@ begin

{ WSL 右键项是 [Code] 动态写的、没有 uninsdeletekey,必须自己认领删除;
这一步排在 PATH 那段的早退之前——两条互不依赖。 }
RemoveOwnedWslContextMenus;
RemoveOwnedExplorerContextMenus;

if not RegValueExists(HKCU, 'Software\Pebrel', 'InstallerAddedToPath') then
Exit;
Expand Down
Loading
Loading