Prepare a USB stick with the post-install toolkit

[DevSecNinja]

Why

I download stock Windows 11 ISOs from the Visual Studio portal, and building a custom ISO is a lot of effort for something I do occasionally. What I actually want most of the time is: flash the stock ISO to a USB stick, install Windows, and have the documented change catalog applied without fetching this repo on the new machine.

post-install.ps1 already covers "machine already exists". This adds the missing middle step for "new machine from my own media", without requiring the full offline build path.

What this adds

prepare-usb.ps1 -> New-PostInstallUsb. You flash a stock ISO to a stick as usual, then point this at it once:

./prepare-usb.ps1 -Path E: -Profile opinionated -WhatIf   # validate + show the plan
./prepare-usb.ps1 -Path E: -Profile opinionated

It validates before writing anything (removable volume root, real Setup media, architecture from the UEFI boot loader, catalog-id validity, free space), stages the toolkit into a folder at the stick root, and generates a bootstrap that self-elevates, copies itself to %ProgramData%\windows-iso-maker so it survives unplugging and reboots, and runs post-install.ps1 under a transcript.

In the default FirstLogon mode it also writes a minimal Autounattend.xml containing only an oobeSystem FirstLogonCommands block. Windows Setup stays completely stock: interactive edition, partitioning and OOBE, including Entra ID sign-in. No DiskConfiguration, no WillWipeDisk, no edition selection, and no disk is ever wiped by this tool. -Mode Toolkit skips the answer file entirely.

This is deliberately a different artifact from the full build answer file in templates/autounattend/autounattend.xml.template, which does repartition, so a new firstlogon.xml.template was added rather than reusing that one.

The important caveat, and why the second commit exists

A rubber-duck review pushed back on the first-logon model, and it was right. Microsoft documents that FirstLogonCommands run elevated only if the first user to sign in is a local administrator; a standard user gets a consent prompt, and nothing runs if it is declined or if UAC is disabled. Whether an Entra ID account becomes a local admin is decided by Entra/Intune, so the automatic run is not guaranteed in exactly the scenario this targets. The docs originally asserted Entra compatibility as fact; they now state the caveat, cite the source, and point at -Mode Toolkit.

Since a silent no-op on a brand-new machine is the worst possible failure, the second commit makes every failure mode visible in %ProgramData%\windows-iso-maker\logs\bootstrap.log: discovery logs before it searches and says so when it finds nothing, and the bootstrap reports elevation failures with guidance.

Worth a careful look: running the real generated command end to end caught a bug the tests did not. Start-Process -Verb RunAs -Wait succeeding only means the process started, so a child that died immediately was reported as "Elevated run finished". It now checks the child's exit code.

Notes for review

• The bootstrap is generated as a string so settings are baked in, which means PSScriptAnalyzer cannot lint the output. Mitigated by asserting it parses via [scriptblock]::Create and by unit-testing the generators and the literal escaping. A static script plus a settings .psd1 would be lintable, and is a reasonable follow-up if you'd prefer it.
• Removable detection no longer relies on Win32_LogicalDisk DriveType alone, since USB SSDs report as fixed. A volume on a USB bus (MSFT_Disk BusType 7) is now accepted rather than requiring -Force.
• New .ps1 files are ASCII-only. Windows PowerShell 5.1 reads no-BOM files as ANSI, so an em dash inside a double-quoted string becomes a smart quote and breaks parsing. This bit during development and is why Autounattend.xml is now written BOM-less via UTF8Encoding($false) rather than Set-Content -Encoding UTF8.
• No new per-feature switches or catalog entries; this reuses Resolve-CatalogSelection and the existing profiles unchanged.

Validation

• PSScriptAnalyzer: 0 findings across src, tests, and all dispatchers.
• Pester: 1337 passing, 0 failing (30 in the new suite).
• Verified under real powershell.exe 5.1, not just the test host: module import, bootstrap execution, and the actual generated first-logon command driven from the rendered XML, covering both the "toolkit found" and "no toolkit found" paths (the latter via a subst drive root).
• No ISO build or DISM servicing was run; those paths are untouched.