Skip to content

Commit 884b6d3

Browse files
mudsskymudssky
committed
refactor(psutils): 抽取共享 helper 并修复 QA
1 parent 30a9663 commit 884b6d3

22 files changed

Lines changed: 1988 additions & 3266 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# design: pwsh shared helper extraction round 2
2+
3+
## Scope
4+
5+
本轮处理上一轮建议顺序的第 2-5 项：
6+
7+
1. rclone 配置 helper 迁移。
8+
2. Docker Compose helper 抽取。
9+
3. JSON/manifest/原子写入工具。
10+
4. 文件同步/备份 helper。
11+
12+
`Install-GitHubCli.ps1` 明确不改。
13+
14+
## Config Helpers
15+
16+
`psutils/modules/config.psm1` 已提供 `ConvertTo-ConfigHashtable`、`Get-ConfigValue`、`Resolve-ConfigEnvPlaceholder` 与 `Resolve-ConfigSources`。`rclone-ops.ps1` 保留旧领域函数名作为兼容 wrapper，但内部委托共享 helper。
17+
18+
## Docker Compose Helpers
19+
20+
新增 `psutils/modules/docker.psm1`，只提供 Docker Compose 基础设施：
21+
22+
* `Test-DockerComposeAvailable`
23+
* `Assert-DockerComposeReady`
24+
* `Get-DockerComposeBaseArgs`
25+
* `Invoke-DockerComposeCommand`
26+
27+
调用脚本可保留本地 `Invoke-DockerCompose` 等旧函数名作为 wrapper，避免破坏测试和用户脚本习惯。
28+
29+
## JSON Helpers
30+
31+
新增 `psutils/modules/json.psm1`，提供：
32+
33+
* `Read-JsonHashtableFile`
34+
* `Write-JsonFileAtomic`
35+
* `Get-StableJsonKey`
36+
37+
这些 helper 只负责 JSON 读写与稳定键，不处理 Claude settings 合并、安全校验或 HuJSON 兼容。
38+
39+
## File Helpers
40+
41+
在 `psutils/modules/filesystem.psm1` 中补充：
42+
43+
* `Copy-FileSystemItemSafe`
44+
* `New-BackupSnapshot`
45+
46+
它们只处理文件系统复制/备份基础设施。Claude managed manifest 的 stale cleanup 仍保留在 `Sync-ClaudeConfig.ps1`。
47+
48+
## Compatibility
49+
50+
* 保留 rclone 与 Claude 同步脚本的对外函数名和命令行入口。
51+
* 保留测试依赖的关键错误文本。
52+
* Docker Compose 先迁移测试覆盖较好的调用点，避免一轮改完所有 start 脚本。
53+
54+
## Validation
55+
56+
* `psutils/tests/config.Tests.ps1`
57+
* `psutils/tests/filesystem.Tests.ps1`
58+
* `psutils/tests/json.Tests.ps1`
59+
* `psutils/tests/docker.Tests.ps1`
60+
* `tests/RcloneOps.Tests.ps1`
61+
* `tests/Sync-ClaudeConfig.Tests.ps1`
62+
* 迁移的 Docker Compose start 脚本对应测试
63+
* `pnpm qa`
64+
* `pnpm test:pwsh:all`

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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‎

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

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

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

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"id": "pwsh-shared-helper-extraction-round2",
3+
"name": "pwsh-shared-helper-extraction-round2",
4+
"title": "pwsh shared helper extraction round 2",
5+
"description": "",
6+
"status": "in_progress",
7+
"dev_type": null,
8+
"scope": null,
9+
"package": null,
10+
"priority": "P2",
11+
"creator": "mudssky",
12+
"assignee": "mudssky",
13+
"createdAt": "2026-05-21",
14+
"completedAt": null,
15+
"branch": null,
16+
"base_branch": "master",
17+
"worktree_path": null,
18+
"commit": null,
19+
"pr_url": null,
20+
"subtasks": [],
21+
"children": [],
22+
"parent": null,
23+
"relatedFiles": [],
24+
"notes": "",
25+
"meta": {}
26+
}

0 commit comments

Comments
 (0)