Installer(wix6): complete WiX 6 build pipeline + parity/evidence tooling

Resolve Heat from repo/NuGet, normalize paths, and generate harvest .wxs before compile
Stabilize bundle StdBA payloads (theme/localization/logo/license) and align branding/version outputs
Improve MSI upgrade/ARP behavior and fix bundle UI/title + MSI-cancel handling
Add installer evidence capture + compare scripts, plus VS Code tasks for end-to-end installer checks
Add deterministic Hyper-V parity lane (WiX3 vs WiX6) with checkpoint restore, runs, and evidence publishing
Add installer artifact validation tests; set C# 8 defaults; update docs/specs and fix startup crash ordering

Author: johnml1135

.github/instructions/installer.instructions.md

@@ -3,42 +3,120 @@ applyTo: "FLExInstaller/**"
 name: "installer.instructions"
 description: "FieldWorks installer (WiX) development guidelines"
 ---
-# Installer development guidelines (WiX)
+# Installer development guidelines (WiX v6)
 
 ## Purpose & Scope
-Guidance for the installer project, packaging configuration, and localization of installer strings.
+Guidance for building, validating, and debugging the FieldWorks installer (WiX v6): MSI (`FieldWorks.msi`) and bootstrapper bundle (`FieldWorksBundle.exe`).
 
-## Context loading
-- Only build the installer when changing installer logic or packaging; prefer app/library builds in inner loop.
-- Review `FLExInstaller/` and related `.wxs/.wixproj` files; confirm WiX 3.14.x tooling.
-- See `Docs/installer-build-guide.md` for local build instructions and CI workflow details.
+## Key facts (FieldWorks repo)
+- WiX projects live in `FLExInstaller/`:
+	- `FieldWorks.Installer.wixproj` (MSI)
+	- `FieldWorks.Bundle.wixproj` (bundle)
+- Builds are orchestrated via `Build/Orchestrator.proj` (preferred entrypoints are `./build.ps1` and `./test.ps1`).
+- Default installer artifacts (Debug) land under:
+	- `FLExInstaller\bin\x64\Debug\en-US\FieldWorks.msi`
+	- `FLExInstaller\bin\x64\Debug\FieldWorksBundle.exe`
 
-## Quick Setup
+## Build commands
 ```powershell
-# Validate installer build prerequisites
-.\Build\Agent\Setup-InstallerBuild.ps1 -ValidateOnly
+# Preferred: traversal build wrapper (Debug)
+./build.ps1 -BuildInstaller
 
-# Set up for patch builds (downloads base artifacts)
-.\Build\Agent\Setup-InstallerBuild.ps1 -SetupPatch
+# Direct MSBuild (equivalent to the orchestration target)
+msbuild Build/Orchestrator.proj /t:BuildInstaller /p:Configuration=Debug /p:Platform=x64
+```
+
+## Debugging flow: “double-click does nothing”
+When a bundle/MSI exits with no UI, assume one of:
+1) immediate process exit (argument parsing, prerequisite detection, policy)
+2) crash before UI (bad BA init, missing dependency, load failure)
+3) UI suppressed (quiet/passive mode, elevation issue)
+
+Work from most observable → deepest inspection:
+
+### 1) Run via the repo helper script (recommended)
+Use the agent-friendly wrapper script to run the installer and collect logs in a deterministic evidence folder:
+```powershell
+# Bundle (default path for the chosen configuration/platform)
+.\scripts\Agent\Invoke-Installer.ps1 -InstallerType Bundle -Configuration Debug -Platform x64
+
+# Bundle with extra args and additional temp-log capture (useful for chained package logs)
+.\scripts\Agent\Invoke-Installer.ps1 -InstallerType Bundle -Configuration Release -Arguments @('/passive') -IncludeTempLogs
 
-# Build base installer
-msbuild Build/Orchestrator.proj /t:BuildInstaller /p:Configuration=Debug /p:Platform=x64 /p:config=release /m
+# MSI (direct Windows Installer engine, with /l*v logging)
+.\scripts\Agent\Invoke-Installer.ps1 -InstallerType Msi -Configuration Debug -Platform x64
 
-# Build patch installer (after -SetupPatch)
-msbuild Build/Orchestrator.proj /t:BuildPatchInstaller /p:Configuration=Debug /p:Platform=x64 /p:config=release /m
+# Custom path (if you're testing a copied artifact)
+.\scripts\Agent\Invoke-Installer.ps1 -InstallerType Bundle -InstallerPath 'C:\Path\To\FieldWorksBundle.exe'
 ```
 
-## Deterministic requirements
-- Versioning: Maintain consistent ProductCode/UpgradeCode policies; ensure patches use higher build numbers than bases.
-- Components/Features: Keep component GUID stability; avoid reshuffling that breaks upgrades.
-- Files: Use build outputs; avoid hand-copying artifacts.
-- Localization: Ensure installer strings align with repository localization patterns.
+Notes:
+- The script writes evidence under `Output\InstallerEvidence\<timestamp>\` and prints the primary log path.
+- `-IncludeTempLogs` copies common related logs from `%TEMP%` that were written during the run.
+
+### 1a) Manual commands (when you need full control)
+Create an evidence folder and run explicitly:
+```powershell
+$e = Join-Path $env:TEMP ('FwInstallerEvidence\\' + (Get-Date -Format yyyy-MM-dd))
+$null = New-Item -ItemType Directory -Force -Path $e
+
+# Bundle (preferred for end-user scenario)
+.\FLExInstaller\bin\x64\Debug\FieldWorksBundle.exe /log "$e\bundle.log"
+
+# MSI (direct Windows Installer engine)
+msiexec /i .\FLExInstaller\bin\x64\Debug\en-US\FieldWorks.msi /l*v "$e\msi-install.log"
+```
+
+Notes:
+- Windows Installer requires the target log directory to exist; if logging fails, create the folder first.
+
+### 2) Check Windows Event Viewer and crash dumps
+If there is still “nothing”, check for an early crash:
+- Event Viewer → Windows Logs → Application
+	- `.NET Runtime` and `Application Error`
+	- `MsiInstaller` events for MSI failures
+- Crash dumps: `%LOCALAPPDATA%\CrashDumps\` for `*.dmp` related to the bundle or `msiexec.exe`.
+
+### 3) Re-run with reduced noise (optional)
+MSI UI levels can hide dialogs; explicitly request UI:
+```powershell
+# Full UI (if authored):
+msiexec /i .\FLExInstaller\bin\x64\Debug\en-US\FieldWorks.msi /qf /l*v C:\Temp\FwInstallerEvidence\msi-ui.log
+
+# Basic UI (progress only):
+msiexec /i .\FLExInstaller\bin\x64\Debug\en-US\FieldWorks.msi /qb /l*v C:\Temp\FwInstallerEvidence\msi-basic.log
+```
+
+### 4) If the bundle starts but install fails: differentiate bundle vs MSI
+- Bundle log shows prerequisite detection, downloads, and chaining decisions.
+- MSI log shows property resolution, component/file install, registry writes, custom action execution.
+
+### 5) If custom actions are suspected
+- Search the MSI log for:
+	- `Return value 3` (classic MSI failure marker)
+	- `CustomAction` lines and the action name that failed
+- Prefer reproducing with a single variable change at a time (different App/Data dirs; feature set; upgrade vs clean).
+
+## WiX v6 build-time diagnostics (authoring/build)
+- WiX v6 is used via SDK-style `.wixproj` with MSBuild properties.
+- Useful knobs live on the project (or can be passed on the command line) such as:
+	- `DefineConstants` (preprocessor variables)
+	- `SuppressIces` / `Ices` / `SuppressValidation` (validation control)
+	- `VerboseOutput` (more build output)
+	- `*AdditionalOptions` properties to pass arbitrary `wix.exe` args
+
+## Harvesting note (WiX v6)
+- FieldWorks currently uses Heat (via `WixToolset.Heat` NuGet) to generate harvested `.wxs` inputs.
+- Heat emits a deprecation warning (HEAT5149) and is expected to go away in WiX v7; treat this as technical debt to retire.
 
-## Structured output
-- Always validate a local installer build when touching installer config.
-- Keep changes minimal and documented in commit messages.
+## Spec-backed verification (what to capture)
+- Verification matrix: `specs/001-wix-v6-migration/verification-matrix.md`
+- Golden install checklist: `specs/001-wix-v6-migration/golden-install-checklist.md`
+- Recommended evidence folder convention: `C:\Temp\FwInstallerEvidence\YYYY-MM-DD\`
 
 ## References
-- Build: See `Build/Installer.targets` and top-level build scripts.
-- CI: Patch/base installer workflows live under `.github/workflows/`.
-- Setup: `Build/Agent/Setup-InstallerBuild.ps1` for environment validation.
+- Windows Installer logging & command line:
+	- https://learn.microsoft.com/windows/win32/msi/windows-installer-logging
+	- https://learn.microsoft.com/windows/win32/msi/command-line-options
+- WiX v6 MSBuild SDK concepts/properties:
+	- https://docs.firegiant.com/wix/tools/msbuild/

.github/workflows/base-installer-cd.yml

@@ -22,10 +22,6 @@ on:
                 description: "Commit-ish for helps repository"
                 required: false
                 default: "develop"
-            installer_ref:
-                description: "Commit-ish for PatchableInstaller repository"
-                required: false
-                default: "master"
             localizations_ref:
                 description: "Commit-ish for localization repository"
                 required: false
@@ -77,15 +73,6 @@ jobs:
                   fetch-depth: 0
                   path: "DistFiles/Helps"
 
-            - name: Checkout PatchableInstaller
-              uses: actions/checkout@v4
-              id: installer-checkout
-              with:
-                  repository: "sillsdev/genericinstaller"
-                  ref: ${{ github.event.inputs.installer_ref || 'master' }}
-                  fetch-depth: 0
-                  path: "PatchableInstaller"
-
             - name: Checkout Localizations
               uses: actions/checkout@v4
               id: loc-checkout
@@ -99,7 +86,7 @@ jobs:
               id: liblcm-checkout
               with:
                   repository: "sillsdev/liblcm"
-                  ref: ${{ github.event.inputs.installer_ref || 'master' }}
+                  ref: ${{ github.event.inputs.lcm_ref || 'master' }}
                   fetch-depth: 0
                   path: "Localizations/LCM"
 
@@ -265,7 +252,7 @@ jobs:
                     $false
                   )
                   [System.IO.Compression.ZipFile]::CreateFromDirectory(
-                    "${{ github.workspace }}\PatchableInstaller\ProcRunner\ProcRunner\bin\Release\net48",
+                    "${{ github.workspace }}\FLExInstaller\Shared\ProcRunner\ProcRunner\bin\Release\net48",
                     "${{ github.workspace }}\ProcRunner.zip",
                     [System.IO.Compression.CompressionLevel]::Optimal,
                     $false

.github/workflows/patch-installer-cd.yml

@@ -22,10 +22,6 @@ on:
         description: "Commit-ish for helps repository"
         required: false
         default: "develop"
-      installer_ref:
-        description: "Commit-ish for PatchableInstaller repository"
-        required: false
-        default: "master"
       localizations_ref:
         description: "Commit-ish for localization repository"
         required: false
@@ -92,14 +88,6 @@ jobs:
           fetch-depth: 0
           path: "DistFiles/Helps"
 
-      - name: Checkout PatchableInstaller
-        uses: actions/checkout@v4
-        id: installer-checkout
-        with:
-          repository: "sillsdev/genericinstaller"
-          ref: ${{ github.event.inputs.installer_ref || 'master' }}
-          fetch-depth: 0
-          path: "PatchableInstaller"
 
       - name: Checkout Localizations
         uses: actions/checkout@v4
@@ -175,7 +163,7 @@ jobs:
           Write-Host "Expanded BuildDir.zip -> ./BuildDir"
 
           # Ensure ProcRunner target path exists
-          $procTarget = "PatchableInstaller/ProcRunner/ProcRunner/bin/Release/net48"
+          $procTarget = "FLExInstaller/Shared/ProcRunner/ProcRunner/bin/Release/net48"
           if (-not (Test-Path $procTarget)) {
             New-Item -ItemType Directory -Path $procTarget -Force | Out-Null
           }

.gitignore

@@ -26,7 +26,6 @@ Downloads/
 Installer/
 Localizations/
 packages/
-PatchableInstaller/
 Bin/_setLatestBuildConfig.bat
 Bin/_setroot.bat
 Lib/debug/DebugProcs.lib
@@ -186,3 +185,4 @@ TestResults/
 
 # Standard .NET
 bin/
+FLExInstaller/cabcache/*

.vscode/tasks.json

@@ -52,6 +52,30 @@
       "type": "promptString",
       "description": "Branch name for worktree (e.g., spec/my-branch or release/9.3)",
       "default": ""
+    },
+    {
+      "id": "installerSnapshotOut",
+      "type": "promptString",
+      "description": "Snapshot output path (file or directory)",
+      "default": "Output/InstallerEvidence/Snapshots"
+    },
+    {
+      "id": "installerSnapshotName",
+      "type": "promptString",
+      "description": "Snapshot name (used in filename when output is a directory)",
+      "default": "manual"
+    },
+    {
+      "id": "installerSnapshotBefore",
+      "type": "promptString",
+      "description": "Path to BEFORE snapshot JSON",
+      "default": ""
+    },
+    {
+      "id": "installerSnapshotAfter",
+      "type": "promptString",
+      "description": "Path to AFTER snapshot JSON",
+      "default": ""
     }
   ],
   "tasks": [
@@ -426,6 +450,45 @@
       },
       "problemMatcher": []
     },
+    {
+      "label": "Installer Evidence: Snapshot",
+      "type": "shell",
+      "command": "./scripts/Agent/Collect-InstallerSnapshot.ps1 -OutputPath '${input:installerSnapshotOut}' -Name '${input:installerSnapshotName}'",
+      "detail": "Collect a machine snapshot (registry/files/uninstall entries) for installer evidence",
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command"]
+        }
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Installer Evidence: Compare snapshots",
+      "type": "shell",
+      "command": "./scripts/Agent/Compare-InstallerSnapshots.ps1 -BeforeSnapshotPath '${input:installerSnapshotBefore}' -AfterSnapshotPath '${input:installerSnapshotAfter}'",
+      "detail": "Compare two snapshot JSON files and print a diff report",
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command"]
+        }
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Installer Check: Bundle (Debug, x64)",
+      "type": "shell",
+      "command": "./scripts/Agent/Invoke-InstallerCheck.ps1 -InstallerType Bundle -Configuration Debug -Platform x64",
+      "detail": "Run snapshot -> install bundle -> snapshot -> diff (writes evidence under Output/InstallerEvidence/<RunId>)",
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command"]
+        }
+      },
+      "problemMatcher": []
+    },
 
     // ==================== Git ====================
     {