Skip to content

Commit 05d32f8

Browse files
johnml1135johnml1135
committed
Add wix6 skills
Update skills and specs Co-authored-by: Copilot <copilot@github.com> partial implementation More progress + add MCP server for winapp More progress Fix CI
1 parent db39df6 commit 05d32f8

44 files changed

Lines changed: 2901 additions & 323 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/skills/fieldworks-installer-diagnostics/SKILL.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
name: fieldworks-installer-diagnostics
3+
description: Use this skill for FieldWorks installer logging, diagnostics, evidence collection, and failure triage: double-click does nothing, bundle exits or hangs, uninstall hangs, ARP issues, prerequisite failures, custom action failures, MSI Return value 3, Burn detect/plan/apply analysis, Event Viewer/crash dumps, VM evidence folders, and before/after installer snapshots. Trigger for any FieldWorks installer debugging or diagnostic request.
4+
---
5+
6+
# FieldWorks Installer Diagnostics
7+
8+
This skill is evidence-first. Installer problems are often ambiguous until Burn logs, MSI logs, and machine state snapshots are collected.
9+
10+
## Load References When Needed
11+
12+
- Read `references/evidence-and-commands.md` for exact commands and evidence locations.
13+
- Read `references/log-triage.md` for Burn/MSI/custom action triage recipes.
14+
15+
## First Moves
16+
17+
1. Read `.github/instructions/installer.instructions.md` and `.github/instructions/debugging.instructions.md`.
18+
2. Read `scripts/Agent/Invoke-Installer.ps1`, `Invoke-InstallerCheck.ps1`, `Collect-InstallerSnapshot.ps1`, and `Compare-InstallerSnapshots.ps1` if changing or using diagnostics scripts.
19+
3. Read `specs/001-wix-v6-migration/verification-matrix.md`, `golden-install-checklist.md`, and `REMAINING_WIX6_ISSUES.md` for the expected evidence shape.
20+
4. Identify which artifact is under test: WiX 3 fallback/current default or WiX 6 migration path. Do not assume helper defaults point at WiX 6.
21+
22+
## Evidence-First Workflow
23+
24+
1. Create or choose an evidence folder. Repo convention: `Output/InstallerEvidence/<RunId>/` for agent scripts, or `C:\Temp\FwInstallerEvidence\YYYY-MM-DD\` for VM/manual runs.
25+
2. Capture the command, artifact path, version, SHA256 if relevant, and machine snapshot/VM state.
26+
3. Run the bundle or MSI with logging. For WiX 6 artifacts, pass explicit `-InstallerPath` when using helper scripts.
27+
4. Include temp logs when chained packages or Burn package logs may be separate.
28+
5. If the UI exits silently, capture Event Viewer entries and crash dumps.
29+
6. Summarize the first failing layer: Burn bootstrapper, chained package/MSI, custom action, Windows Installer engine, or environment.
30+
31+
## WinApp MCP Runtime Evidence
32+
33+
When the WinApp MCP server is available, use it to make UI diagnostics repeatable:
34+
35+
- Launch or attach to installer windows and wait for input idle before diagnosing UI state.
36+
- If the app snapshot is empty, list visible desktop windows and use `get_focused_element` plus keyboard navigation to identify and exercise controls.
37+
- Record the observed focus path and control names in the evidence notes, especially for silent/blank UI, MSI handoff, uninstall prompts, and ARP uninstall hangs.
38+
- For safe UI-only smoke tests, stop after proving the license checkbox/Install/Cancel path; do not proceed into install unless the scenario requires machine changes.
39+
- For hangs, combine WinApp focused-element/window evidence with bundle/MSI logs, before/after snapshots, Event Viewer entries, and process lists.
40+
- If the bundle reaches elevated MSI internal UI, a non-elevated WinApp host may be limited to observation. Treat visible-but-non-clickable MSI controls as an automation integrity boundary until proven otherwise; capture the focused element, MSI log action, screenshots, process integrity/window ownership evidence, and rerun elevated for full manual UI control.
41+
42+
## Commands
43+
44+
Prefer the repo helper for repeatable runs:
45+
46+
```powershell
47+
./scripts/Agent/Invoke-Installer.ps1 -InstallerType Bundle -InstallerPath '.\FLExInstaller\wix6\bin\x64\Debug\FieldWorksBundle.exe' -IncludeTempLogs
48+
./scripts/Agent/Invoke-Installer.ps1 -InstallerType Msi -InstallerPath '.\FLExInstaller\wix6\bin\x64\Debug\en-US\FieldWorks.msi' -IncludeTempLogs
49+
```
50+
51+
Use explicit manual commands when needed:
52+
53+
```powershell
54+
.\FLExInstaller\wix6\bin\x64\Debug\FieldWorksBundle.exe /log C:\Temp\FwInstallerEvidence\bundle.log
55+
msiexec /i .\FLExInstaller\wix6\bin\x64\Debug\en-US\FieldWorks.msi /l*v C:\Temp\FwInstallerEvidence\msi-install.log
56+
msiexec /x {PRODUCT-CODE} /l*v C:\Temp\FwInstallerEvidence\msi-uninstall.log
57+
```
58+
59+
For before/after evidence:
60+
61+
```powershell
62+
./scripts/Agent/Collect-InstallerSnapshot.ps1 -OutputPath C:\Temp\FwInstallerEvidence\before.json -Name before
63+
./scripts/Agent/Collect-InstallerSnapshot.ps1 -OutputPath C:\Temp\FwInstallerEvidence\after.json -Name after
64+
./scripts/Agent/Compare-InstallerSnapshots.ps1 -BeforeSnapshotPath C:\Temp\FwInstallerEvidence\before.json -AfterSnapshotPath C:\Temp\FwInstallerEvidence\after.json
65+
```
66+
67+
## Triage Priorities
68+
69+
- Bundle log first for Burn detection, prerequisite planning, cache/download failures, related bundle handling, and package log paths.
70+
- MSI verbose log first for directory properties, feature states, standard action sequencing, and custom action failures.
71+
- Search MSI logs for `Return value 3`, then walk upward to the failing action and property context.
72+
- Search bundle logs for `Detected package`, `Planned package`, `Applying execute package`, `Error 0x`, and final result code.
73+
- For custom actions, find the WiX action ID in `Framework.wxs`, then map it to the DllEntry in `CustomAction.cs`.
74+
- For hangs, identify the last completed phase/action and whether a UI prompt, process-close prompt, files-in-use dialog, or elevation prompt is waiting.
75+
76+
## Report Format
77+
78+
When reporting diagnostics, include:
79+
80+
- Artifact tested and command used.
81+
- Evidence folder and primary logs.
82+
- Failure layer and first meaningful error.
83+
- Relevant Burn/MSI action/package names.
84+
- Machine state: clean, prereqs present, old FieldWorks installed, offline, upgrade, repair, or uninstall.
85+
- Next smallest fix or next evidence needed.

‎.github/skills/fieldworks-installer-diagnostics/references/evidence-and-commands.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# FieldWorks Installer Evidence And Commands
2+
3+
## Artifact Paths
4+
5+
WiX 3 fallback/current default:
6+
7+
- `FLExInstaller/bin/x64/Debug/en-US/FieldWorks.msi`
8+
- `FLExInstaller/bin/x64/Debug/FieldWorksBundle.exe`
9+
10+
WiX 6 migration path:
11+
12+
- `FLExInstaller/wix6/bin/x64/Debug/en-US/FieldWorks.msi`
13+
- `FLExInstaller/wix6/bin/x64/Debug/FieldWorksBundle.exe`
14+
- `FLExInstaller/wix6/bin/x64/Debug/FieldWorksOfflineBundle.exe`
15+
16+
Adjust `Debug` to `Release` as needed.
17+
18+
## Helper Script Notes
19+
20+
- `scripts/Agent/Invoke-Installer.ps1` creates `Output/InstallerEvidence/<RunId>/` by default.
21+
- The helper's default artifact resolver historically points at `FLExInstaller/bin/...`; pass `-InstallerPath` explicitly for WiX 6 artifacts.
22+
- Use `-IncludeTempLogs` for Burn package logs and chained package logs.
23+
- Use `-SummarizeMsiFileAccess` when validating installed file payloads from MSI logs.
24+
25+
## Common Runs
26+
27+
Interactive WiX 6 bundle:
28+
29+
```powershell
30+
./scripts/Agent/Invoke-Installer.ps1 -InstallerType Bundle -InstallerPath '.\FLExInstaller\wix6\bin\x64\Debug\FieldWorksBundle.exe' -IncludeTempLogs
31+
```
32+
33+
Passive WiX 6 bundle:
34+
35+
```powershell
36+
./scripts/Agent/Invoke-Installer.ps1 -InstallerType Bundle -InstallerPath '.\FLExInstaller\wix6\bin\x64\Debug\FieldWorksBundle.exe' -Arguments @('/passive') -IncludeTempLogs
37+
```
38+
39+
Direct MSI full UI:
40+
41+
```powershell
42+
msiexec /i .\FLExInstaller\wix6\bin\x64\Debug\en-US\FieldWorks.msi /qf /l*v C:\Temp\FwInstallerEvidence\msi-ui.log
43+
```
44+
45+
Uninstall by product code:
46+
47+
```powershell
48+
msiexec /x {PRODUCT-CODE} /l*v C:\Temp\FwInstallerEvidence\msi-uninstall.log
49+
```
50+
51+
## Crash Evidence
52+
53+
- Event Viewer -> Windows Logs -> Application: `.NET Runtime`, `Application Error`, and `MsiInstaller`.
54+
- Crash dumps: `%LOCALAPPDATA%\CrashDumps\` for bundle, custom BA, or `msiexec.exe` crashes.
55+
- FieldWorks debug traces can be enabled with `FieldWorks.Diagnostics.config` as described in `.github/instructions/debugging.instructions.md`.

‎.github/skills/fieldworks-installer-diagnostics/references/log-triage.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Installer Log Triage
2+
3+
## Burn Bundle Log
4+
5+
Read in phase order:
6+
7+
1. Header/version/command line.
8+
2. Detect phase: `Detected package`, related bundle detection, registry searches, prerequisite state.
9+
3. Plan phase: `Planned package`, requested action, cache strategy, dependency registration, feature states.
10+
4. Cache/download phase: URL, payload hash/signature, cache path.
11+
5. Apply phase: `Applying execute package`, package arguments, package-specific log path.
12+
6. Completion: package result, restart state, final HRESULT.
13+
14+
Useful strings:
15+
16+
- `WixBundleLog`
17+
- `WixBundleLog_AppMsiPackage`
18+
- `Detected package:`
19+
- `Planned package:`
20+
- `Applying execute package:`
21+
- `Error 0x`
22+
- `restart:`
23+
- `Will not uninstall package`
24+
- `found dependents`
25+
26+
## MSI Verbose Log
27+
28+
Read around the first real failure, not the final summary only.
29+
30+
Useful strings:
31+
32+
- `Return value 3`
33+
- `CustomAction`
34+
- `Action start`
35+
- `Action ended`
36+
- `APPFOLDER`
37+
- `DATAFOLDER`
38+
- `WIX_UPGRADE_DETECTED`
39+
- `FindRelatedProducts`
40+
- `RemoveExistingProducts`
41+
- `InstallValidate`
42+
- `PATCH`
43+
- `PATCHNEWSUMMARYSUBJECT`
44+
45+
When `Return value 3` appears, walk upward to find the custom action or standard action that failed, then inspect properties and command line immediately before it.
46+
47+
## Custom Actions
48+
49+
Map WiX action ID to DLL entry:
50+
51+
- `CheckApplicationPath` -> `CheckAppPath`
52+
- `VerifyDataPath` -> `VerifyDataDirPath`
53+
- `CloseApplications` -> `ClosePrompt`
54+
- `DeleteRegistryVersionNumber` -> `DeleteVersionNumberFromRegistry`
55+
56+
Common causes:
57+
58+
- Required session properties not initialized before UI sequence.
59+
- Deferred action needs `CustomActionData` but reads session properties directly.
60+
- Missing `CustomActions.CA.dll` or runtime config in the Binary payload.
61+
- Process-close prompt waiting for user action.
62+
63+
## Symptom Shortcuts
64+
65+
- Double-click does nothing: run with `/log`; check Burn condition failures, BA/theme load failure, Event Viewer, crash dumps.
66+
- Bundle waits after detect: interactive bundle may be waiting for user action. Use `/passive` or full UI intentionally.
67+
- MSI UI missing from bundle: inspect `bal:DisplayInternalUICondition`, UI level, and package log.
68+
- Uninstall hangs: find whether Burn, MSI, files-in-use, CloseApplications, or ARP invocation is waiting.
69+
- Duplicate ARP entries: inventory bundle vs MSI registrations and check package visibility/ARP properties.

‎.github/skills/fieldworks-wix6-build-migration/SKILL.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
name: fieldworks-wix6-build-migration
3+
description: Use this skill for FieldWorks WiX Toolset build migration work: moving PatchableInstaller/genericinstaller behavior into WiX 6, fixing Build/Installer*.targets, SDK-style .wixproj files, InstallerToolset selection, prerequisite download/staging, CI installer builds, signing knobs, artifact paths, and local developer build failures. Trigger whenever the user mentions FieldWorks WiX build, Wix3/Wix6 toolset selection, PatchableInstaller migration, genericinstaller removal, or installer artifacts.
4+
---
5+
6+
# FieldWorks WiX 6 Build Migration
7+
8+
This skill handles build infrastructure and migration mechanics. Keep it separate from UI behavior, runtime diagnostics, and patch/upgrade validation unless those areas are the cause of a build failure.
9+
10+
## Load References When Needed
11+
12+
- Read `references/repo-build-map.md` for FieldWorks-specific targets, projects, commands, and artifact paths.
13+
- Read `references/official-wix-build-notes.md` for WiX Toolset v4/v6 migration and MSBuild facts.
14+
15+
## First Moves
16+
17+
1. Confirm current branch/worktree and whether the task is about the WiX 3 fallback, the WiX 6 migration path, or the switch to WiX 6 as default.
18+
2. Read `FLExInstaller/AGENTS.md`, `.github/instructions/installer.instructions.md`, and `.github/instructions/build.instructions.md`.
19+
3. Inspect `Build/InstallerBuild.proj` to confirm which target file is imported for `InstallerToolset=Wix3|Wix6`.
20+
4. Inspect `Build/Installer.targets`, `Build/Installer.Wix3.targets`, and relevant `.wixproj` files before editing.
21+
5. Search for active references to `PatchableInstaller`, `genericinstaller`, `candle.exe`, `light.exe`, `insignia.exe`, and `heat.exe`; classify each as WiX 3 legacy, WiX 6 active, or documentation/reference.
22+
23+
## FieldWorks Build Rules
24+
25+
- Current default installer build is WiX 3 fallback: `./build.ps1 -BuildInstaller`.
26+
- WiX 6 is currently selected explicitly: `./build.ps1 -BuildInstaller -InstallerToolset Wix6`; treat that path as the migration target.
27+
- Do not make WiX 6 schema changes in `FLExInstaller/` root files. Keep WiX 6 authoring under `FLExInstaller/wix6/`.
28+
- Do not reintroduce a `genericinstaller` submodule. If old behavior is needed, migrate the specific source/config into the repo and document why.
29+
- Do not remove or break the WiX 3 path during the transition.
30+
- Use pinned repo package versions, not whatever WiX happens to be globally installed.
31+
- WiX 6 projects should be SDK-style and use WiX extension `PackageReference`s such as Bal, Util, NetFx, UI, and Heat as appropriate.
32+
- WiX v6 source uses `http://wixtoolset.org/schemas/v4/wxs`; there is no v6 schema namespace.
33+
34+
## PatchableInstaller Migration Workflow
35+
36+
When moving behavior out of the old generic installer/PatchableInstaller model:
37+
38+
1. Identify the old source of behavior in `PatchableInstaller/`, `Build/Installer.legacy.targets`, or WiX 3 includes.
39+
2. Find the WiX 6 destination: `FLExInstaller/wix6/Shared/Base`, `Shared/Common`, `Shared/CustomActions`, `Shared/ProcRunner`, or a `.wixproj` target.
40+
3. Port only the needed behavior. Avoid copying whole legacy scripts or batch-driven assumptions into the WiX 6 path.
41+
4. Convert old command-line parameters into MSBuild properties and `DefineConstants` rather than batch variables.
42+
5. Add validation that fails loudly when required payloads or prerequisites are missing.
43+
6. Update specs/docs only when behavior or build commands change.
44+
45+
## Build Failure Workflow
46+
47+
1. Run or ask for the exact command and configuration, including `InstallerToolset`.
48+
2. Validate prerequisites with `./Build/Agent/Setup-InstallerBuild.ps1 -ValidateOnly` when the failure smells environmental.
49+
3. If WiX 6 fails, inspect `FieldWorks.Installer.wixproj`, `FieldWorks.Bundle.wixproj`, and `FieldWorks.OfflineBundle.wixproj` before touching MSBuild targets.
50+
4. For WiX errors, map the error to authoring/project/tooling. Do not hide warnings by suppression unless the repo already documents that suppression.
51+
5. Preserve `.wixpdb` outputs; they are useful for diagnostics and future patch baselines.
52+
53+
## Validation
54+
55+
Prefer these checks, scaled to the change:
56+
57+
- `./Build/Agent/Setup-InstallerBuild.ps1 -ValidateOnly`
58+
- `./build.ps1 -BuildInstaller -InstallerToolset Wix6 -Configuration Debug`
59+
- `./build.ps1 -BuildInstaller -InstallerToolset Wix6 -Configuration Release` for release-path changes
60+
- Confirm artifacts under `FLExInstaller/wix6/bin/x64/<Configuration>/` and `en-US/`.
61+
- For CI or pre-commit work, use the repo VS Code task `CI: Full local check` when appropriate.
62+
63+
## Output Expectations
64+
65+
When reporting a build migration result, include:
66+
67+
- The active toolset and entry point.
68+
- The target/project files touched.
69+
- The legacy behavior replaced or isolated.
70+
- The artifacts expected and where they land.
71+
- The validation run and remaining risk.

‎.github/skills/fieldworks-wix6-build-migration/references/official-wix-build-notes.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Official WiX Build And Migration Notes
2+
3+
Use these notes for WiX Toolset, not the Wix website builder.
4+
5+
## Official Sources
6+
7+
- WiX source: https://github.com/wixtoolset/wix
8+
- FireGiant docs: https://docs.firegiant.com/wix/
9+
- v3 to v4 migration WIP: https://docs.firegiant.com/wix/development/wips/4561-migrate-v3-source-code-to-v4/
10+
- MSBuild SDK docs: https://docs.firegiant.com/wix/tools/msbuild/
11+
- Preprocessor docs: https://docs.firegiant.com/wix/tools/preprocessor/
12+
- Extension docs: https://docs.firegiant.com/wix/tools/wixext/
13+
14+
## Migration Facts To Remember
15+
16+
- WiX v6 authoring still uses the v4 XML namespace.
17+
- v3 `candle.exe` and `light.exe` thinking maps to `wix build` or SDK-style MSBuild.
18+
- SDK-style `.wixproj` files can use `ProjectReference`s; WiX creates bind paths and preprocessor variables for referenced projects.
19+
- Extensions are NuGet packages in modern WiX, not only `-ext` paths to globally installed DLLs.
20+
- Useful MSBuild properties include `DefineConstants`, `BindPath`, `InstallerPlatform`, `OutputType`, `VerboseOutput`, `SuppressIces`, `SuppressValidation`, and `*AdditionalOptions`.
21+
- `Product` became `Package`; old `Package` metadata moved/reorganized.
22+
- `Component/@Win64` became `Bitness`; default bitness follows `InstallerPlatform`/`-arch`.
23+
- `RemotePayload` became package-specific payload elements such as `ExePackagePayload`, `MsiPackagePayload`, and `MspPackagePayload`.
24+
- `ExePackage` command attributes became `InstallArguments`, `RepairArguments`, and `UninstallArguments`.
25+
- `DisplayInternalUI` moved out of core Burn package authoring; use Bal `DisplayInternalUICondition` when appropriate.
26+
27+
## Build Quality Rules
28+
29+
- Do not suppress validation to get past real authoring problems.
30+
- Keep warnings visible unless the repo has an intentional suppression with a reason.
31+
- Preserve `.wixpdb` outputs for diagnostics and patch baselines.
32+
- Treat Heat as technical debt. If using generated fragments, guard component/file identity carefully.

0 commit comments

Comments
 (0)