Skip to content

v5.4 reliability pass: fix hangs, misreported errors and CI - #19

Merged
Pnwcomputers merged 2 commits into
mainfrom
claude/deploy-workstation-review-5089f8
Nov 17, 2026
Merged

Pnwcomputers merged 2 commits into
mainfrom
claude/deploy-workstation-review-5089f8

Conversation

@Pnwcomputers

Copy link
Copy Markdown
Owner

Summary

A reliability pass on DeployWorkstation.ps1 and the launchers, from a code review focused on function and error handling. It fixes one bug that can hang a whole run, several places where errors were misreported, and a CI workflow that hadn't run a single test since v5.3.

Highest impact

  • McAfee removal could hang forever. /S /quiet was added to MSI uninstall strings too. msiexec doesn't accept /S, so it opened a usage dialog in a hidden window and the script waited on it indefinitely. MSI entries now run msiexec /X{GUID} /qn /norestart, QuietUninstallString is used when present, there's a 20-minute timeout, and exit codes are checked (3010/1641 = success + restart, 1605 = already gone). Before, every product was logged as "Removed" whatever actually happened.
  • An outdated winget was never actually upgraded. Re-registering restored the same old version and was counted as success, so every install then failed on the 1.4+ flags. The version is now checked again after each step, and Repair-WinGetPackageManager is a last resort (it also installs the VCLibs/UI.Xaml dependencies). If winget still can't be upgraded, the run carries on without the newer flags instead of failing every install.
  • Offline runs reported every app as "Package ID not found". Only a real "not found" result (0x8A150014) counts as a bad ID now; any other winget show failure lets the install show the real error and use its retries.

Error handling

  • Two more temporary errors are retried: "install in progress" (0x8A150102, common right after first boot, with a 3× longer wait) and "download failed" (0x8A150008).
  • Bloatware removal: 0x8A15010A (restart required) was logged as "not installed"; uninstalls that finish after a restart are now OK and set the restart flag; the winget list exit code now skips uninstall attempts for patterns with nothing installed.
  • Appx and capability counters only count removals that actually succeeded; protected system packages (0x80073CFA) are reported as skipped. Provisioned packages are listed once per run instead of once per pattern.
  • Exit codes: 0 success, 2 completed with warnings, 1 critical error. The .bat launcher reports each.
  • New -NoPause switch for unattended/RMM runs (both launchers pass it and pause themselves); a critical error now pauses so it can be read.
  • The log and HTML report fall back to %ProgramData%\DeployWorkstation when the script folder is read-only.
  • HTML report: shows the real version (it said 5.2), update-mode counters and a restart banner.
  • Failure-reason messages used em-dashes, which Windows PowerShell 5.1 prints as — because the file has no BOM; they're now ASCII.
  • DeployWorkstation.bat option 1 printed a garbled (none - full run line (unescaped parenthesis).

CI / tests

  • The workflow passed -OutputFormat, which Pester 5 doesn't accept, so every run since v5.3 failed before testing. It now uses the Pester 5 configuration API with JUnit output, under both PowerShell 7 and Windows PowerShell 5.1.
  • The tests were rewritten for Pester 5's discovery rules, and 60 tests now load the script's real functions (via the AST, without running the script) against a fake winget: exit-code tables, ID resolution, retries, uninstall-string parsing, bloatware exit handling, localization keys, version consistency and the HTML report. A guard aborts if the fake winget isn't in effect.

Type of change

  • Bug fix
  • New feature (-NoPause, exit codes, log fallback)
  • Docs update
  • Refactor (install/update retry loops share Invoke-WingetWithRetry)
  • Other (describe):

Checklist

  • I ran tests locally and they pass: 60/60 under Windows PowerShell 5.1 with Pester 5.7.1
  • I updated docs/README as needed (README v5.4 section, parameters, exit codes; CHANGELOG 5.4 plus the missing 5.3 entry)
  • I linked related issues (none)
  • I followed the coding style & conventions

Verification notes for reviewers

  • Not done: an end-to-end run of the full script, because it removes apps from the machine it runs on. Please do one trial run on a spare machine or VM before field use.
  • The McAfee process-tree wait was checked on real processes: exit codes are captured, it waits for an uninstaller that hands off to a child process, and a hung process is stopped at the timeout with nothing left running.
  • The .bat launcher was run against a stand-in script: it reports exit codes 0, 2 and 1 correctly and passes -NoPause and the right flags.

Breaking changes

  • Exit code 2 now means "completed with warnings" (it used to be 0). RMM tools or scripts that check the exit code will flag those runs.
  • McAfee: a non-zero uninstaller exit is now WARN instead of always "Removed".
  • Outdated winget: recovery can take longer, since the script now actually upgrades it. The last-resort repair installs the NuGet provider and the Microsoft.WinGet.Client module; it only runs when the first two bootstrap steps fail.

Left alone on purpose: the permanent msstore source removal, the broad bloatware name patterns ('Teams', 'Outlook'), the JSON profiles that nothing reads yet, and the QuickStart menu numbering.

🤖 Generated with Claude Code

Pnwcomputers and others added 2 commits November 17, 2026 10:37
- McAfee: MSI uninstalls use /X{GUID} /qn instead of /S (msiexec showed a
  hidden usage dialog and hung the run); timeout and real exit codes
- Winget bootstrap re-checks the version after each step, adds a
  Repair-WinGetPackageManager fallback, and runs in compatibility mode
  rather than failing every install on an old winget
- Offline runs no longer report every app as "Package ID not found"
- Retry install-in-progress and download failures; handle restart codes
  correctly during bloatware removal
- Count Appx/capability removals only when they succeed
- Exit code 2 on warnings, -NoPause switch, log/report fallback to
  ProgramData, HTML report shows real version and update counters
- Fix CI (Pester 5 config, JUnit output, PS 5.1 run) and add unit tests
  that exercise the script's functions against a fake winget

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
codespell flagged valid es-ES localization words, code identifiers
(PressEnter, Pester's AfterAll) and the existing COMPATABILITY.md file
name; add them to the ignore list. Fix the one real typo (unparseable).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Pnwcomputers
Pnwcomputers merged commit 8fb8538 into main Nov 17, 2026
2 checks passed
@Pnwcomputers
Pnwcomputers deleted the claude/deploy-workstation-review-5089f8 branch November 17, 2026 18:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant