fix(pwsh): 修复 hosted runner 剩余测试失败

Author: mudssky

.trellis/spec/infra/install-orchestrator.md

@@ -58,6 +58,8 @@ pnpm provision:full [-NetworkMode China | -Step <id> | -FromStep <id>]
 - JSON 模式必须关闭运行进度；stdout 继续只有最终单个 JSON document，stderr 也不得出现 Text 进度行。
 - stdout/stderr 必须先并发复制原始字节，再优先按严格 UTF-8 解码；Windows 子进程若产生非法 UTF-8，才允许按当前文化 ANSI code page 兼容解码，最终文本不得包含替换字符。
 - 叶子等待必须使用有限轮询以响应中断，但不得把有限轮询解释为安装超时；等待异常或中断时必须终止仍存活的直接子进程树，再释放 `Process`。
+- `pwsh -File` 临时 UTF-8 wrapper 不得把 token 数组直接 splat 给目标脚本；数组 splatting 只按位置绑定。wrapper 必须读取目标 `ExternalScript` 参数元数据，把 `-Name value` 与 switch token 重建为 hashtable splatting，再调用真实脚本。
+- wrapper 属于内部临时资源，必须在 `finally` 使用不受调用方 `WhatIfPreference` 影响的文件 API 清理；不得让 `Remove-Item -WhatIf` 文本污染 JSON stdout 或留下临时脚本。
 
 ### 4. Validation & Error Matrix
 
@@ -81,6 +83,8 @@ pnpm provision:full [-NetworkMode China | -Step <id> | -FromStep <id>]
 | Text 模式叶子持续运行 | 启动时立即且仅一次写安全命令到 stderr；不输出 elapsed heartbeat，最终汇总和结果不变 |
 | JSON 模式执行同一叶子 | 不输出任何 Text 进度，stdout 仍可作为单个 JSON document 解析 |
 | 等待叶子时发生中断或异常 | 终止仍存活的直接子进程及其后代，不遗留下载或安装进程 |
+| `pwsh -File` wrapper 直接 `& $ScriptPath @tokenArray` | 命名参数退化为位置值并触发 `ValidateSet` 等绑定错误；必须重建 hashtable splatting |
+| 根调用启用 `-WhatIf` 时清理 wrapper | 仍真实删除内部临时文件，且 JSON stdout 不出现 `What if:` |
 
 ### 5. Good/Base/Bad Cases
 
@@ -103,6 +107,7 @@ pnpm provision:full [-NetworkMode China | -Step <id> | -FromStep <id>]
 - package scripts：`provision:list`、Core/Full preview smoke、参数透传，且不得触发 pnpm 依赖安装流程。
 - Text 输出：标题、步骤、source restore 与最终状态的多占位符格式必须完整输出，不抛 `FormatException`。
 - 进度：Text 仅一次启动行且无 elapsed heartbeat、JSON 静默，以及中断等待后无遗留直接子进程树。
+- `pwsh` wrapper：无参数、命名值、switch、长 UTF-8、多流、退出码、中断进程树，以及 `-WhatIf` 下仍清理临时文件且不污染 JSON。
 - 代码完成后运行 `pnpm qa` 与 `pnpm test:pwsh:all`。
 
 ### 7. Wrong vs Correct

.trellis/spec/pwsh-scripts/package/pester-performance.md

@@ -31,7 +31,8 @@ node scripts/pester-duration-report.mjs \
 - duration JSON 必须包含 `schemaVersion`、`command`、`lane`、`startedAt`、`endedAt`、`elapsedMs`、`exitCode`、`phases`、`nunitPath`、`coveragePath`、`files` 和 `testCases`。
 - `test:pwsh:all` 必须在启动 host lane 前检查 Docker CLI、daemon 和 Compose；缺失时输出 `pnpm test:pwsh:full` fallback，不启动长测试。
 - `Filter.ExcludeTag` 必须始终是独立字符串数组；PowerShell 条件表达式可能把单元素数组展开为标量，后续 `+=` 会退化成字符串拼接，因此应使用显式数组收集块构造标签。
-- hosted runner 回归测试不得假设机器预装 Pester 5.7.1、Scoop 或 WSL 发行版；旧版本模块使用临时 `PSModulePath` fixture，原生命令使用临时 PATH shim，无 WSL 发行版时只跳过依赖真实 guest 的用例。
+- hosted runner 回归测试不得假设机器预装 Pester 5.7.1、Scoop、WSL 发行版或仓库忽略的 `bin/` 生成产物；旧版本模块使用临时 `PSModulePath` fixture，原生命令使用临时 PATH shim，生成入口必须在 `$TestDrive` 通过真实生成器创建，无 WSL 发行版时只跳过依赖真实 guest 的用例。
+- Windows-only 测试块必须整体标记独立 `windowsOnly` 标签；纯 schema、registry、HTML 与 SSH 数据逻辑继续跨平台执行，不能为消除失败扩大整文件排除。
 - `pwsh` 叶子进程必须在写出端固定 UTF-8 标准流编码；父进程只负责并发复制原始字节和严格解码，不能在字符已被当前代码页替换后补救。
 
 ## 4. Validation & Error Matrix
@@ -47,7 +48,8 @@ node scripts/pester-duration-report.mjs \
 | 命令显式指定 `-PesterVersion` | artifact 的 `pesterVersion` 与该参数一致 |
 | pnpm 等间接入口未显式指定版本 | 依次使用 `PWSH_PESTER_VERSION`、`.pester-version`；两者都不存在时才探测已安装版本 |
 | 多个排除标签显示为 `SlowwindowsOnly` | 配置构造失败；必须保留 `Slow`、`windowsOnly` 等独立数组元素 |
-| hosted runner 缺少旧 Pester、Scoop 或 WSL guest | 使用隔离模块/命令 fixture；仅真实 WSL guest 用例按能力 Skip |
+| hosted runner 缺少旧 Pester、Scoop、WSL guest 或忽略的 `bin/` 生成入口 | 使用隔离模块/命令 fixture；入口由真实生成器写入 `$TestDrive`；仅真实 WSL guest 用例按能力 Skip |
+| 非 Windows 执行 Chromium Profile 生命周期或 `.lnk` 快捷方式用例 | 测试分组缺少 `windowsOnly` 标签；应只标记真正依赖 Windows 宿主的分组 |
 | Windows 子进程长 UTF-8 输出出现 `?` | 在 `pwsh -File` 临时 wrapper 中先设置 Console UTF-8，再执行真实脚本并透传退出码 |
 
 ## 5. Good / Base / Bad Cases
@@ -63,8 +65,9 @@ node scripts/pester-duration-report.mjs \
 - Windows 命令发现：present/missing、PATH 变化、Scoop cmd shim、WinGet module export、完整 `CommandAvailability`。
 - 编排器：状态机调用顺序与次数；真实 UTF-8、多流、Running、中断进程树清理。
 - 配置筛选：Windows 保留独立 `Slow`，Linux/macOS 保留独立 `Slow` 与 `windowsOnly`，禁止出现 `SlowwindowsOnly`。
-- hosted runner 隔离：旧 Pester 用标准版本模块目录注入临时 `PSModulePath`；Scoop 用临时 PATH shim；Windows 无 WSL 发行版时 guest smoke 明确 Skip。
-- `pwsh` 子进程：临时 UTF-8 wrapper 不出现在展示命令中，且长 stdout/stderr、退出码、`[Running]` 与中断进程树清理合同全部通过。
+- hosted runner 隔离：旧 Pester 用标准版本模块目录注入临时 `PSModulePath`；Scoop 用临时 PATH shim；忽略的 bin 入口在 `$TestDrive` 通过真实生成器创建；Windows 无 WSL 发行版时 guest smoke 明确 Skip。
+- 平台标签：只给 Chromium Profile 生命周期、进程所有权与 `.lnk` 快捷方式等真实 Windows 宿主分组标记 `windowsOnly`，纯逻辑分组继续在 Ubuntu/macOS 回归。
+- `pwsh` 子进程：临时 UTF-8 wrapper 不出现在展示命令中，重建命名值与 switch 的 hashtable splatting，并覆盖长 stdout/stderr、退出码、`[Running]`、中断进程树及 `WhatIf` 清理合同。
 - 性能验收：Windows host coverage-on 连续 3 轮，报告中位数、最慢值和 coverage；样本期间不得并发运行其他 Pester。
 
 ## 7. Wrong vs Correct

psutils/tests/web.Tests.ps1

@@ -120,8 +120,10 @@ Describe "New-WebShortcut Tests" {
             if ($IsLinux) {
                 # 需要 mock browser path 否则会 fallback 到 Html
                 Mock Get-BrowserPath { return "/usr/bin/fakebrowser" } -ModuleName web
-                Mock Test-Path { Microsoft.PowerShell.Management\Test-Path @PSBoundParameters } -ModuleName web
-                Mock Test-Path { return $true } -ParameterFilter { $Path -eq "/usr/bin/fakebrowser" } -ModuleName web
+                Mock Test-Path {
+                    param($Path)
+                    return $Path -eq '/usr/bin/fakebrowser' -or [System.IO.File]::Exists($Path) -or [System.IO.Directory]::Exists($Path)
+                } -ModuleName web
                 Mock Save-Icon { return $false } -ModuleName web
 
                 New-WebShortcut -Url "https://auto-test.com" -Name "AutoLinux" -Type Auto -SaveDir $TestDir

scripts/pwsh/install/InstallOrchestrator.psm1

@@ -750,11 +750,37 @@ param(
     [Parameter(Mandatory, Position = 0)]
     [string]$ScriptPath,
     [Parameter(ValueFromRemainingArguments = $true)]
-    [object[]]$RemainingArguments
+    [string[]]$RemainingArguments
 )
 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
 [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
-& $ScriptPath @RemainingArguments
+$command = Get-Command -Name $ScriptPath -CommandType ExternalScript -ErrorAction Stop
+$boundParameters = @{}
+$remainingTokens = @($RemainingArguments)
+if ($remainingTokens.Count -eq 1 -and [string]::IsNullOrEmpty([string]$remainingTokens[0])) {
+    $remainingTokens = @()
+}
+for ($index = 0; $index -lt $remainingTokens.Count; $index++) {
+    $token = [string]$remainingTokens[$index]
+    if ($token -notmatch '^-(?<Name>[A-Za-z][A-Za-z0-9-]*)$') {
+        throw "无法解析叶子参数: $token"
+    }
+    $parameterName = $Matches.Name
+    $parameter = $command.Parameters[$parameterName]
+    if ($null -eq $parameter) {
+        throw "叶子脚本不支持参数: -$parameterName"
+    }
+    if ($parameter.ParameterType -eq [System.Management.Automation.SwitchParameter]) {
+        $boundParameters[$parameterName] = $true
+        continue
+    }
+    $index++
+    if ($index -ge $remainingTokens.Count) {
+        throw "叶子参数缺少值: -$parameterName"
+    }
+    $boundParameters[$parameterName] = [string]$remainingTokens[$index]
+}
+& $ScriptPath @boundParameters
 exit $LASTEXITCODE
 '@
         [System.IO.File]::WriteAllText($wrapperPath, $wrapperContent, [System.Text.UTF8Encoding]::new($false))
@@ -841,8 +867,8 @@ exit $LASTEXITCODE
         $process.Dispose()
         $stdoutBuffer.Dispose()
         $stderrBuffer.Dispose()
-        if ($wrapperPath -and (Test-Path -LiteralPath $wrapperPath -PathType Leaf)) {
-            Remove-Item -LiteralPath $wrapperPath -Force -ErrorAction SilentlyContinue
+        if ($wrapperPath -and [System.IO.File]::Exists($wrapperPath)) {
+            [System.IO.File]::Delete($wrapperPath)
         }
     }
 }

tests/BrowserDebugProfile.Tests.ps1

@@ -132,9 +132,18 @@ if ($RemainingArgs[0] -eq '__complete') { 'profile' }
         Should -Invoke Read-BrowserDebugRegistry -Times 0
     }
 
-    It '通过真实 alias 与 ps1 入口调用内部补全且不终止当前会话' {
-        $completionPath = Join-Path $script:ToolRoot 'completion.ps1'
-        $commandPath = Join-Path $script:RepoRoot 'bin/browser-debug.ps1'
+    It '通过真实生成的 alias 与 ps1 入口调用内部补全且不终止当前会话' {
+        $generatedRoot = Join-Path $TestDrive 'generated-profile-root'
+        $generatedToolRoot = Join-Path $generatedRoot 'scripts/pwsh/devops/browser-debug'
+        New-Item -ItemType Directory -Path $generatedToolRoot -Force | Out-Null
+        Copy-Item -LiteralPath (Join-Path $script:RepoRoot 'Manage-BinScripts.ps1') -Destination $generatedRoot -Force
+        Copy-Item -LiteralPath (Join-Path $script:RepoRoot 'psutils/src/config') -Destination (Join-Path $generatedRoot 'psutils/src/config') -Recurse -Force
+        Copy-Item -Path (Join-Path $script:ToolRoot '*') -Destination $generatedToolRoot -Recurse -Force
+        & (Join-Path $generatedRoot 'Manage-BinScripts.ps1') -Action sync -Force *> $null
+
+        $completionPath = Join-Path $generatedToolRoot 'completion.ps1'
+        $commandPath = Join-Path $generatedRoot 'bin/browser-debug.ps1'
+        Test-Path -LiteralPath $commandPath -PathType Leaf | Should -BeTrue
         $childCommand = @"
 Remove-Item Env:\PWSH_TEST_SKIP_BROWSER_DEBUG_MAIN -ErrorAction SilentlyContinue
 . '$($completionPath.Replace("'", "''"))'
@@ -154,7 +163,7 @@ Register-BrowserDebugCompletion -CommandPath '$($commandPath.Replace("'", "''"))
     }
 }
 
-Describe 'browser-debug Profile 生命周期' {
+Describe 'browser-debug Profile 生命周期' -Tag 'windowsOnly' {
     BeforeEach {
         $script:RegistryPath = Join-Path $TestDrive 'registry.json'
         $script:ProfileRoot = Join-Path $TestDrive 'profiles'
@@ -559,7 +568,7 @@ Describe 'browser-debug User Data 克隆' {
     }
 }
 
-Describe 'browser-debug 快捷方式' {
+Describe 'browser-debug 快捷方式' -Tag 'windowsOnly' {
     It 'Local 与 LAN 快捷方式只引用 Profile 名称、显式模式并确认切换' {
         $pwshPath = (Get-Command pwsh.exe -ErrorAction Stop).Source
         $profile = [pscustomobject]@{ name = 'demo'; browserPath = $pwshPath; cdpPort = 9333 }

tests/Install.Tests.ps1

@@ -66,7 +66,7 @@ param([string]$Preset, [switch]$WhatIf)
             $verifyRelativePath = if ($IsWindows) { 'windows/99verifyInstall.ps1' } else { 'linux/99verifyInstall.ps1' }
             $verifyPath = Join-Path $script:TempRoot $verifyRelativePath
             New-Item -ItemType Directory -Path (Split-Path -Parent $verifyPath) -Force | Out-Null
-            Set-Content -LiteralPath $verifyPath -Encoding utf8NoBOM -Value "Write-Output 'verify-leaf-noise'`n"
+            Set-Content -LiteralPath $verifyPath -Encoding utf8NoBOM -Value "param([ValidateSet('Core', 'Full')][string]`$Preset)`nWrite-Output 'verify-leaf-noise'`n"
         }
 
         if (-not $IsWindows) {

tests/InstallOrchestrator.Tests.ps1

@@ -441,6 +441,36 @@ $stderrText = 'stderr-start|' + ('错误诊断-边界|' * 2500) + 'stderr-end'
         $result.Stderr | Should -Not -Match ([char]0xfffd)
     }
 
+    It 'binds named values and switches through the UTF-8 wrapper and removes it under WhatIf' {
+        $fixturePath = Join-Path $script:FixtureRoot 'named-arguments.ps1'
+        Set-Content -LiteralPath $fixturePath -Encoding utf8NoBOM -Value @'
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [ValidateSet('Core', 'Full')]
+    [string]$Preset,
+    [switch]$Enabled
+)
+[pscustomobject]@{ Preset = $Preset; Enabled = [bool]$Enabled } | ConvertTo-Json -Compress
+'@
+        $module = Get-Module InstallOrchestrator
+        $temporaryPattern = Join-Path ([System.IO.Path]::GetTempPath()) 'powershellScripts-install-*.ps1'
+        $wrappersBefore = @(Get-ChildItem -Path $temporaryPattern -ErrorAction SilentlyContinue).FullName
+
+        $result = & $module {
+            param($Path)
+            $WhatIfPreference = $true
+            Invoke-InstallLeafProcess -Runner pwsh -ScriptPath $Path -ArgumentList @('-Preset', 'Core', '-Enabled')
+        } $fixturePath
+        $document = $result.Stdout | ConvertFrom-Json
+
+        $result.ExitCode | Should -Be 0
+        $document.Preset | Should -Be 'Core'
+        $document.Enabled | Should -BeTrue
+        $result.Stdout | Should -Not -Match '^What if:'
+        $wrappersAfter = @(Get-ChildItem -Path $temporaryPattern -ErrorAction SilentlyContinue).FullName
+        @($wrappersAfter | Where-Object { $_ -notin $wrappersBefore }) | Should -BeNullOrEmpty
+    }
+
     It 'decodes a round-trippable Windows ANSI output fallback without replacement characters' -Skip:(-not $IsWindows) {
         $text = '本地编码诊断'
         $codePage = [System.Globalization.CultureInfo]::CurrentCulture.TextInfo.ANSICodePage