Release 0.8.0: Windows installer, twelve fixes from a real Server 2019 install, operator docs

deploy/windows/installer/bundle-lock.ps1

@@ -50,6 +50,7 @@ $script:BundlePayloads = @(
     @{ Name = 'httpplatformhandler'; Required = $true;  What = 'the IIS module that launches waitress' }
     @{ Name = 'urlrewrite';          Required = $false; What = 'IIS URL Rewrite, for the client-IP rule' }
     @{ Name = 'mysqlclient';         Required = $false; What = 'mysql/mysqldump, for backups against a remote database' }
+    @{ Name = 'vcredist';            Required = $false; What = 'the Visual C++ runtime MySQL requires' }
     @{ Name = 'mysql';               Required = $false; What = 'MySQL, for the bundled-database option' }
 )
 
@@ -75,14 +76,35 @@ function Get-FileDigest {
 }
 
 function Get-PayloadFiles {
-    # Every file in the directory, keyed by its path RELATIVE to that directory
-    # with forward slashes, so a lock generated on Windows reads the same from
-    # the Bash builder.
+    <#
+      Every file in the directory, keyed by its path RELATIVE to that directory
+      with forward slashes, so a lock generated on Windows reads the same from
+      the Bash builder.
+
+      The root comes from Get-Item, NOT Resolve-Path, and the prefix is checked
+      before it is trimmed. Both matter, and a real install proved it:
+
+      Inno extracts the bundle under C:\Users\ADMINI~1\AppData\Local\Temp\... -
+      an 8.3 SHORT path. Resolve-Path kept that short form while Get-ChildItem
+      returned the long one (Administrator), so the root was five characters
+      shorter than the prefix it was slicing off. Every relative path came out
+      mangled - 'wheels/heels/flask.whl' - and the verifier reported all 96 files
+      as simultaneously missing and unexpected. The payload was fine; the
+      comparison was not.
+
+      Get-Item and Get-ChildItem go through the same provider, so their path
+      forms agree. The StartsWith guard means that if they ever disagree again
+      this fails loudly instead of inventing paths.
+    #>
     param([string] $Dir)
     $out = @{}
     if (-not (Test-Path $Dir)) { return $out }
-    $root = (Resolve-Path $Dir).Path.TrimEnd('\', '/')
-    foreach ($f in (Get-ChildItem $Dir -Recurse -File)) {
+    $rootItem = Get-Item -LiteralPath $Dir
+    $root = $rootItem.FullName.TrimEnd('\', '/')
+    foreach ($f in (Get-ChildItem -LiteralPath $rootItem.FullName -Recurse -File)) {
+        if (-not $f.FullName.StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)) {
+            throw ("cannot place '{0}' beneath '{1}' - path forms disagree (8.3 short name?)" -f $f.FullName, $root)
+        }
         $rel = $f.FullName.Substring($root.Length).TrimStart('\', '/').Replace('\', '/')
         $out[$rel] = @{ sha256 = (Get-FileDigest $f.FullName); size = $f.Length }
     }
@@ -137,7 +159,9 @@ function Test-BundleLock {
     )
     $problems = @()
     $payloads = Get-JsonProperty $Lock 'payloads'
-    if ($null -eq $payloads) { return @('bundle-lock.json has no "payloads" section') }
+    # ,@(...) for the same reason as the final return: a bare one-element array
+    # unrolls to a string, and the caller's .Count then measures the wrong thing.
+    if ($null -eq $payloads) { return ,@('bundle-lock.json has no "payloads" section') }
 
     foreach ($p in $script:BundlePayloads) {
         $name    = $p.Name
@@ -184,7 +208,11 @@ function Test-BundleLock {
         }
     }
     $problems += Test-WheelhouseCoversRequirements -BundleRoot $BundleRoot
-    return $problems
+    # The comma keeps this an ARRAY through the return. Without it PowerShell
+    # unrolls an empty result to $null and a single result to a bare string, and
+    # every caller that asks for .Count then behaves differently depending on how
+    # many problems there happen to be.
+    return ,$problems
 }
 
 function Test-WheelhouseCoversRequirements {