refactor(psutils): 抽取共享 helper 并修复 QA

Author: mudssky

.trellis/tasks/05-21-pwsh-shared-helper-extraction-round2/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

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

@@ -0,0 +1,64 @@
+# design: pwsh shared helper extraction round 2
+
+## Scope
+
+本轮处理上一轮建议顺序的第 2-5 项：
+
+1. rclone 配置 helper 迁移。
+2. Docker Compose helper 抽取。
+3. JSON/manifest/原子写入工具。
+4. 文件同步/备份 helper。
+
+`Install-GitHubCli.ps1` 明确不改。
+
+## Config Helpers
+
+`psutils/modules/config.psm1` 已提供 `ConvertTo-ConfigHashtable`、`Get-ConfigValue`、`Resolve-ConfigEnvPlaceholder` 与 `Resolve-ConfigSources`。`rclone-ops.ps1` 保留旧领域函数名作为兼容 wrapper，但内部委托共享 helper。
+
+## Docker Compose Helpers
+
+新增 `psutils/modules/docker.psm1`，只提供 Docker Compose 基础设施：
+
+* `Test-DockerComposeAvailable`
+* `Assert-DockerComposeReady`
+* `Get-DockerComposeBaseArgs`
+* `Invoke-DockerComposeCommand`
+
+调用脚本可保留本地 `Invoke-DockerCompose` 等旧函数名作为 wrapper，避免破坏测试和用户脚本习惯。
+
+## JSON Helpers
+
+新增 `psutils/modules/json.psm1`，提供：
+
+* `Read-JsonHashtableFile`
+* `Write-JsonFileAtomic`
+* `Get-StableJsonKey`
+
+这些 helper 只负责 JSON 读写与稳定键，不处理 Claude settings 合并、安全校验或 HuJSON 兼容。
+
+## File Helpers
+
+在 `psutils/modules/filesystem.psm1` 中补充：
+
+* `Copy-FileSystemItemSafe`
+* `New-BackupSnapshot`
+
+它们只处理文件系统复制/备份基础设施。Claude managed manifest 的 stale cleanup 仍保留在 `Sync-ClaudeConfig.ps1`。
+
+## Compatibility
+
+* 保留 rclone 与 Claude 同步脚本的对外函数名和命令行入口。
+* 保留测试依赖的关键错误文本。
+* Docker Compose 先迁移测试覆盖较好的调用点，避免一轮改完所有 start 脚本。
+
+## Validation
+
+* `psutils/tests/config.Tests.ps1`
+* `psutils/tests/filesystem.Tests.ps1`
+* `psutils/tests/json.Tests.ps1`
+* `psutils/tests/docker.Tests.ps1`
+* `tests/RcloneOps.Tests.ps1`
+* `tests/Sync-ClaudeConfig.Tests.ps1`
+* 迁移的 Docker Compose start 脚本对应测试
+* `pnpm qa`
+* `pnpm test:pwsh:all`

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

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

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

@@ -0,0 +1,32 @@
+# implement: pwsh shared helper extraction round 2
+
+## Checklist
+
+1. 启动任务
+   * 完成 `prd.md`、`design.md`、`implement.md`。
+   * 执行 `task.py start`。
+2. rclone config helper 迁移
+   * `ConvertTo-RcloneOpsHashtable` 委托 `ConvertTo-ConfigHashtable`。
+   * `Get-RcloneOpsConfigValue` 委托 `Get-ConfigValue`。
+   * `Resolve-RcloneOpsEnvPlaceholder` 委托 `Resolve-ConfigEnvPlaceholder`，非字符串保持原样。
+3. Docker Compose helper
+   * 新增 `psutils/modules/docker.psm1` 和测试。
+   * 选择一个已有 start 脚本迁移到共享 helper。
+4. JSON helper
+   * 新增 `psutils/modules/json.psm1` 和测试。
+   * 更新 `psutils/psutils.psd1`。
+5. File helper
+   * 更新 `psutils/modules/filesystem.psm1` 和测试。
+   * `Sync-ClaudeConfig.ps1` 复用 JSON/文件 helper。
+6. 验证
+   * targeted Pester。
+   * `pnpm qa`。
+   * `pnpm test:pwsh:all`。
+7. 提交
+   * Conventional Commits，中文 subject。
+
+## Review Gate
+
+* `Install-GitHubCli.ps1` 没有出现在本轮 diff。
+* 新增 `psutils` helper 不包含 rclone/Claude/具体服务领域语义。
+* Docker Compose 只迁移有测试或行为足够简单的调用点。

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

@@ -0,0 +1,27 @@
+# pwsh shared helper extraction round 2
+
+## Goal
+
+继续从 `psutils` 之外的大型 PowerShell 脚本里抽取通用基础设施，降低重复实现和后续维护成本。
+
+## Requirements
+
+- 跳过前一轮建议中的第 1 项：不修改 `scripts/pwsh/download/Install-GitHubCli.ps1`。
+- 迁移 rclone 运维脚本中的配置 helper，优先复用 `psutils/modules/config.psm1`。
+- 抽取 Docker Compose 相关通用 helper，并至少迁移一个已有 start 脚本调用点。
+- 抽取 JSON/manifest/原子写入 helper，不包含 Claude、Tailscale、rclone 等领域规则。
+- 抽取文件同步/备份中稳定通用的基础 helper；领域耦合过强的 managed manifest 清理保留在调用脚本中。
+- 保留现有脚本入口、参数、测试可见函数名和行为语义。
+
+## Acceptance Criteria
+
+- [ ] `Install-GitHubCli.ps1` 未被修改。
+- [ ] `rclone-ops.ps1` 不再维护重复的 env placeholder / hashtable / case-insensitive lookup 实现。
+- [ ] 至少一个 Docker Compose start 脚本复用共享 helper，原测试行为保持兼容。
+- [ ] `psutils` 提供 JSON 原子读写或稳定键 helper，并有 Pester 覆盖。
+- [ ] Claude config sync 复用通用 JSON/文件 helper，业务合并和安全校验仍留在脚本内。
+- [ ] 目标脚本现有 Pester 测试通过，根目录 `pnpm qa` 与 `pnpm test:pwsh:all` 通过。
+
+## Notes
+
+- 用户明确指定“2 3 4 5 改一下，1 先不改了”，此处的 1 指上一轮建议顺序中的 GitHub CLI 下载器迁移。

.trellis/tasks/05-21-pwsh-shared-helper-extraction-round2/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "pwsh-shared-helper-extraction-round2",
+  "name": "pwsh-shared-helper-extraction-round2",
+  "title": "pwsh shared helper extraction round 2",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "mudssky",
+  "assignee": "mudssky",
+  "createdAt": "2026-05-21",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}