refactor(psutils): 迁移 GitHub CLI 下载器 helper

Author: mudssky

.trellis/spec/psutils/package/shared-config-resolver.md

@@ -26,6 +26,7 @@
   - `Get-ConfigValue -Values <hashtable> -Name <string> [-DefaultValue <object>]`
   - `Resolve-ConfigEnvPlaceholder -Value <string> -Context <string>`
   - `Resolve-ConfigPath -Path <string> -BasePath <string> -Context <string>`
+  - `Resolve-ConfigPlatformValue -Value <object> -Platform <pscustomobject> -Label <string> [-AllowScalar]`
   - `ConvertTo-ConfigKeyName -Name <string>`
   - `ConvertFrom-ConfigCliParameters -Parameters <hashtable> [-ExcludeKeys <string[]>]`
 - Scoped env:
@@ -43,6 +44,7 @@
 - `Get-ConfigValue` performs shallow case-insensitive lookup only; it must not expand paths, environment variables, nested paths, or normalize key names.
 - `Resolve-ConfigEnvPlaceholder` expands `${VAR}` and `%VAR%`; missing `${VAR}` throws with context instead of silently preserving the placeholder.
 - `Resolve-ConfigPath` expands env placeholders, supports `~`, resolves relative paths against `BasePath`, and returns an absolute path. It does not validate existence or create directories.
+- `Resolve-ConfigPlatformValue` reads platform maps in `<os>-<arch>` -> `<os>` -> `default` order; scalar strings are accepted only when `-AllowScalar` is explicitly set.
 - Missing file sources return an empty table by default; `-ErrorOnMissing` changes that to `配置文件不存在: <path>`.
 - `Invoke-WithScopedEnvironment` must restore overwritten variables and remove newly created variables even when the script block throws.
 - `psutils/modules/config.psm1` must export public resolver functions and must not contain a second implementation of the parser.
@@ -60,6 +62,7 @@
 | CLI parameter value is `$null` or whitespace | Omit it from merged config |
 | `${VAR}` placeholder references a missing env var | Throw `环境变量未设置: VAR（context）` |
 | `Resolve-ConfigPath` receives an empty path | Throw `路径配置不能为空: context` |
+| Platform map is a scalar without `-AllowScalar` | Throw `<label> 需要按平台配置` |
 
 ### 5. Good/Base/Bad Cases
 

.trellis/tasks/05-21-pwsh-shared-helper-extraction-round2/design.md

@@ -2,14 +2,29 @@
 
 ## Scope
 
-本轮处理上一轮建议顺序的第 2-5 项：
+本轮处理上一轮建议顺序的第 1-5 项：
 
-1. rclone 配置 helper 迁移。
-2. Docker Compose helper 抽取。
-3. JSON/manifest/原子写入工具。
-4. 文件同步/备份 helper。
+1. GitHub CLI 下载器通用 helper 迁移。
+2. rclone 配置 helper 迁移。
+3. Docker Compose helper 抽取。
+4. JSON/manifest/原子写入工具。
+5. 文件同步/备份 helper。
 
-`Install-GitHubCli.ps1` 明确不改。
+`Install-GitHubCli.ps1` 保留对外函数名，底层委托 `psutils`。
+
+## GitHub CLI Download Helpers
+
+GitHub CLI 下载器中的配置对象转换、平台描述、平台映射读取、归档解压、候选文件查找、
+可执行文件安装、PATH 检查与提示都属于通用基础设施。迁移到：
+
+* `psutils/modules/config.psm1`
+* `psutils/modules/os.psm1`
+* `psutils/modules/filesystem.psm1`
+* `psutils/modules/install.psm1`
+* `psutils/modules/env.psm1`
+
+脚本内保留 `ConvertTo-GitHubCliHashtable`、`New-GitHubCliPlatform`、`Expand-GitHubCliArchive`
+等旧函数名作为兼容 wrapper。
 
 ## Config Helpers
 

.trellis/tasks/05-21-pwsh-shared-helper-extraction-round2/implement.md

@@ -5,28 +5,32 @@
 1. 启动任务
    * 完成 `prd.md`、`design.md`、`implement.md`。
    * 执行 `task.py start`。
-2. rclone config helper 迁移
+2. GitHub CLI 下载器 helper 迁移
+   * 配置表、路径、平台映射 wrapper 委托 `psutils`。
+   * 归档解压、候选文件查找、可执行文件安装、PATH 检查与提示委托共享 helper。
+   * 保留脚本入口与原函数名。
+3. rclone config helper 迁移
    * `ConvertTo-RcloneOpsHashtable` 委托 `ConvertTo-ConfigHashtable`。
    * `Get-RcloneOpsConfigValue` 委托 `Get-ConfigValue`。
    * `Resolve-RcloneOpsEnvPlaceholder` 委托 `Resolve-ConfigEnvPlaceholder`，非字符串保持原样。
-3. Docker Compose helper
+4. Docker Compose helper
    * 新增 `psutils/modules/docker.psm1` 和测试。
    * 选择一个已有 start 脚本迁移到共享 helper。
-4. JSON helper
+5. JSON helper
    * 新增 `psutils/modules/json.psm1` 和测试。
    * 更新 `psutils/psutils.psd1`。
-5. File helper
+6. File helper
    * 更新 `psutils/modules/filesystem.psm1` 和测试。
    * `Sync-ClaudeConfig.ps1` 复用 JSON/文件 helper。
-6. 验证
+7. 验证
    * targeted Pester。
    * `pnpm qa`。
    * `pnpm test:pwsh:all`。
-7. 提交
+8. 提交
    * Conventional Commits，中文 subject。
 
 ## Review Gate
 
-* `Install-GitHubCli.ps1` 没有出现在本轮 diff。
+* `Install-GitHubCli.ps1` 只保留领域逻辑与兼容 wrapper，不再维护通用 helper 实现。
 * 新增 `psutils` helper 不包含 rclone/Claude/具体服务领域语义。
 * Docker Compose 只迁移有测试或行为足够简单的调用点。

.trellis/tasks/05-21-pwsh-shared-helper-extraction-round2/prd.md

@@ -6,7 +6,7 @@
 
 ## Requirements
 
-- 跳过前一轮建议中的第 1 项：不修改 `scripts/pwsh/download/Install-GitHubCli.ps1`。
+- 补做前一轮建议中的第 1 项：迁移 `scripts/pwsh/download/Install-GitHubCli.ps1` 中可复用的通用基础设施。
 - 迁移 rclone 运维脚本中的配置 helper，优先复用 `psutils/modules/config.psm1`。
 - 抽取 Docker Compose 相关通用 helper，并至少迁移一个已有 start 脚本调用点。
 - 抽取 JSON/manifest/原子写入 helper，不包含 Claude、Tailscale、rclone 等领域规则。
@@ -15,7 +15,7 @@
 
 ## Acceptance Criteria
 
-- [ ] `Install-GitHubCli.ps1` 未被修改。
+- [ ] `Install-GitHubCli.ps1` 保留现有脚本入口和测试可见函数名，但通用配置、平台、归档、PATH 与安装 helper 复用 `psutils`。
 - [ ] `rclone-ops.ps1` 不再维护重复的 env placeholder / hashtable / case-insensitive lookup 实现。
 - [ ] 至少一个 Docker Compose start 脚本复用共享 helper，原测试行为保持兼容。
 - [ ] `psutils` 提供 JSON 原子读写或稳定键 helper，并有 Pester 覆盖。
@@ -24,4 +24,4 @@
 
 ## Notes
 
-- 用户明确指定“2 3 4 5 改一下，1 先不改了”，此处的 1 指上一轮建议顺序中的 GitHub CLI 下载器迁移。
+- 用户最初指定“2 3 4 5 改一下，1 先不改了”，随后补充“第一项也改一下”；此处的 1 指上一轮建议顺序中的 GitHub CLI 下载器迁移。

psutils/modules/config.psm1

@@ -20,6 +20,7 @@ Export-ModuleMember -Function @(
     'Get-ConfigValue'
     'Resolve-ConfigEnvPlaceholder'
     'Resolve-ConfigPath'
+    'Resolve-ConfigPlatformValue'
     'ConvertTo-ConfigKeyName'
     'ConvertFrom-ConfigCliParameters'
     'Read-ConfigPowerShellDataFile'

psutils/modules/env.psm1

@@ -567,7 +567,7 @@ function Sync-PathFromBash {
             $source = 'bash-nologin-bashrc'
             if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($bashPathOutput)) {
                 Write-Warning "非登录模式获取 PATH 失败，尝试显式加载 ~/.bashrc。"
-                $bashPathOutput = bash --noprofile --norc -c 'source ~/.bashrc 2>/dev/null; echo $PATH'
+                $bashPathOutput = bash '--noprofile' '--norc' '-c' 'source ~/.bashrc 2>/dev/null; echo $PATH'
                 $source = 'bash-nologin-bashrc-fallback'
                 if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($bashPathOutput)) {
                     $msg = "无法从非登录模式获取 PATH。请检查 Bash 安装或 .bashrc 配置。"
@@ -662,5 +662,134 @@ function Sync-PathFromBash {
     }
 }
 
+function Test-DirectoryInPath {
+    <#
+    .SYNOPSIS
+        判断目录是否已经位于 PATH 中。
+
+    .DESCRIPTION
+        将目标目录和 PATH 中的条目都规范化为完整路径后比较。Windows 平台默认忽略大小写，
+        Linux/macOS 默认区分大小写；调用方也可以显式传入比较方式。
+
+    .PARAMETER Directory
+        待检查的目录路径。
+
+    .PARAMETER PathValue
+        可选 PATH 字符串；默认读取当前进程 PATH。
+
+    .PARAMETER Comparison
+        路径比较方式；未传入时根据平台自动选择。
+
+    .OUTPUTS
+        bool
+        目录已在 PATH 中时返回 true。
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Directory,
+
+        [AllowNull()]
+        [string]$PathValue = $env:PATH,
+
+        [AllowNull()]
+        [object]$Comparison = $null
+    )
+
+    if ([string]::IsNullOrWhiteSpace($PathValue)) {
+        return $false
+    }
+
+    [System.StringComparison]$effectiveComparison = if ($null -ne $Comparison) {
+        if ($Comparison -is [System.StringComparison]) {
+            $Comparison
+        }
+        else {
+            [System.StringComparison]::Parse([System.StringComparison], [string]$Comparison, $true)
+        }
+    }
+    elseif ($IsWindows) {
+        [System.StringComparison]::OrdinalIgnoreCase
+    }
+    else {
+        [System.StringComparison]::Ordinal
+    }
+
+    $target = [System.IO.Path]::GetFullPath($Directory).TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)
+    foreach ($entry in ($PathValue -split [regex]::Escape([System.IO.Path]::PathSeparator))) {
+        if ([string]::IsNullOrWhiteSpace($entry)) {
+            continue
+        }
+
+        try {
+            $entryPath = [System.IO.Path]::GetFullPath($entry.Trim()).TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)
+        }
+        catch {
+            continue
+        }
+
+        if ([string]::Equals($target, $entryPath, $effectiveComparison)) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-PathAddHint {
+    <#
+    .SYNOPSIS
+        生成平台化 PATH 添加提示。
+
+    .DESCRIPTION
+        根据平台输出适合展示给用户的 PATH 添加命令或操作方法。该函数只生成文本，
+        不修改环境变量。
+
+    .PARAMETER Directory
+        需要加入 PATH 的目录。
+
+    .PARAMETER OperatingSystem
+        目标操作系统，支持 `windows`、`linux`、`macos`。
+
+    .OUTPUTS
+        string[]
+        返回多行提示文本。
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Directory,
+
+        [ValidateSet('windows', 'linux', 'macos')]
+        [string]$OperatingSystem = $(if ($IsWindows) { 'windows' } elseif ($IsMacOS) { 'macos' } else { 'linux' })
+    )
+
+    $escapedForSingleQuote = $Directory -replace "'", "''"
+    switch ($OperatingSystem) {
+        'windows' {
+            return @(
+                '安装目录尚未在 PATH 中。可在 PowerShell 中执行：',
+                "[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ';$escapedForSingleQuote', 'User')",
+                '然后重新打开终端。'
+            )
+        }
+        'macos' {
+            return @(
+                '安装目录尚未在 PATH 中。zsh 用户可执行：',
+                "mkdir -p '$escapedForSingleQuote'",
+                ('echo ''export PATH="{0}:$PATH"'' >> ~/.zshrc' -f $escapedForSingleQuote),
+                '然后执行 source ~/.zshrc 或重新打开终端。'
+            )
+        }
+        default {
+            return @(
+                '安装目录尚未在 PATH 中。bash/zsh 用户可执行：',
+                "mkdir -p '$escapedForSingleQuote'",
+                ('echo ''export PATH="{0}:$PATH"'' >> ~/.profile' -f $escapedForSingleQuote),
+                '然后执行 source ~/.profile 或重新打开终端。'
+            )
+        }
+    }
+}
 
-Export-ModuleMember -Function Get-Dotenv, Install-Dotenv, Import-EnvPath, Set-EnvPath, Add-EnvPath, Get-EnvParam, Remove-FromEnvPath, Sync-PathFromBash
+Export-ModuleMember -Function Get-Dotenv, Install-Dotenv, Import-EnvPath, Set-EnvPath, Add-EnvPath, Get-EnvParam, Remove-FromEnvPath, Sync-PathFromBash, Test-DirectoryInPath, Get-PathAddHint