From c33dd9a7b3d2084dee348b839fedc7766ea99a69 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 23 May 2026 05:17:33 +0000 Subject: [PATCH] fix: add REST PR file summary CLI --- AGENTS.md | 2 +- TEST.md | 2 +- docs/reference/cli.md | 4 +- scripts/gh-cli-pr-files-contract-test.ts | 230 +++++++++++++++++++++++ scripts/src/check.ts | 3 + scripts/src/gh.ts | 175 ++++++++++++++++- 6 files changed, 409 insertions(+), 7 deletions(-) create mode 100644 scripts/gh-cli-pr-files-contract-test.ts diff --git a/AGENTS.md b/AGENTS.md index d79bf114..de3a6d5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts dev-env validate [--manifest path] [--kubectl-dry-run]` / `dev-env prewarm-images`：离线校验 D601 `unidesk-dev` 生产隔离护栏和 dev workload manifests，或把开发底座基础镜像预热到 D601 原生 k3s containerd，规则见 `docs/reference/deploy.md` 与 `docs/reference/microservices.md`。 - `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`findjob`/`pipeline` 支持 D601 direct dev/prod，`met-nonlinear` 和 `k3sctl-adapter` 只给受限计划路径，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。 - `bun scripts/cli.ts auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`：查看 Auth Broker P0 Rust skeleton 与 CLI adapter contract，runner 无 `GH_TOKEN`/`GITHUB_TOKEN` 时返回结构化 `auth-missing`/`broker-needed`，不读取或打印 token 值，规则见 `docs/reference/auth-broker.md`。 -- `bun scripts/cli.ts gh auth status|issue ...|pr list|read|view|create|edit|update|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 +- `bun scripts/cli.ts gh auth status|issue ...|pr list|files|diff --stat|read|view|create|edit|update|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合和 ClaudeQQ 高风险请示草案；当前只返回 dry-run 计划，不接 live bridge、不接管人工指挥官，不发送消息，规则见 `docs/reference/host-codex-commander.md`。 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。 - `bun scripts/cli.ts codex deploy `：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。 diff --git a/TEST.md b/TEST.md index 5630d6ab..c4d982d6 100644 --- a/TEST.md +++ b/TEST.md @@ -137,7 +137,7 @@ ## T26 GitHub CLI PR 安全写入口 -阅读 `AGENTS.md` 和 `docs/reference/cli.md`，然后用 cli 手动测试以下内容：准备一份包含真实换行、反引号和 Markdown 表格的临时正文文件，运行 `bun scripts/cli.ts gh help`，确认 help 中包含 `gh pr create`、`gh pr edit`、`gh pr comment`、`gh pr read ` 和 `--raw|--full`。运行 `bun scripts/gh-cli-pr-contract-test.ts`，确认 mock GitHub 覆盖 PR read/view 的 `owner/repo#number` shorthand、`--raw` 完整披露、冲突 `--repo` 结构化失败、PR closeout GraphQL 字段、PR edit/update REST PATCH payload、stdin `--body-file -` 和不回显完整正文。运行 `bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title --body-file <file> --base master --head <branch> --draft --dry-run`，确认命令不访问 GitHub、不创建 PR，JSON 中包含 `dryRun=true`、`planned=true`、repo、title、base、head、draft、bodyChars、bodyPreviewLines、request plan，并且正文预览保留真实换行和反引号。运行 `bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-file <file> --dry-run`，确认命令使用 REST PATCH 计划、不访问 GitHub Projects Classic GraphQL/projectCards，JSON 只包含 repo、PR number、changedFields、url、body 长度/SHA/source 和 request plan，不默认回显完整正文；再运行 `cat <file> | bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --body-file - --dry-run`，确认 stdin source 标记为 `kind=stdin` 且同样低噪声。运行 `bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run`，确认命令不写评论，JSON 中包含 PR number、bodyChars、bodySource 和 request plan，且没有把换行污染成字面量 `\n`。运行 `bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk`，确认返回非零状态和结构化 JSON，`degradedReason=unsupported-command`、`runnerDisposition=business-failed`，且不会真实 merge。需要测试真实创建、编辑或评论时，只允许使用明确的 throwaway 源分支和 PR，并在记录中写明 PR URL、number、源/目标分支和清理动作；默认验收只做 dry-run，不创建或修改真实 PR。 +阅读 `AGENTS.md` 和 `docs/reference/cli.md`，然后用 cli 手动测试以下内容：准备一份包含真实换行、反引号和 Markdown 表格的临时正文文件，运行 `bun scripts/cli.ts gh help`，确认 help 中包含 `gh pr create`、`gh pr edit`、`gh pr comment`、`gh pr read <number|owner/repo#number>`、`--raw|--full`、`gh pr files <number>` 和 `gh pr diff <number> --stat`。运行 `bun scripts/gh-cli-pr-contract-test.ts`，确认 mock GitHub 覆盖 PR read/view 的 `owner/repo#number` shorthand、`--raw` 完整披露、冲突 `--repo` 结构化失败、PR closeout GraphQL 字段、PR edit/update REST PATCH payload、stdin `--body-file -` 和不回显完整正文。运行 `bun scripts/gh-cli-pr-files-contract-test.ts`，确认 mock GitHub 覆盖 `gh pr files` 的 REST changed-file/stat JSON、bounded file list、truncation metadata、next command、无 raw patch，以及 `gh pr diff --stat` 兼容别名和无 `--stat` raw diff 的结构化拒绝。对真实仓库只读观察可运行 `bun scripts/cli.ts gh pr files <number> --repo pikasTech/unidesk --limit 30` 或 `bun scripts/cli.ts gh pr diff <number> --repo pikasTech/unidesk --stat --limit 30`，确认输出固定 JSON 且默认不含 raw diff。运行 `bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <branch> --draft --dry-run`，确认命令不访问 GitHub、不创建 PR，JSON 中包含 `dryRun=true`、`planned=true`、repo、title、base、head、draft、bodyChars、bodyPreviewLines、request plan，并且正文预览保留真实换行和反引号。运行 `bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-file <file> --dry-run`，确认命令使用 REST PATCH 计划、不访问 GitHub Projects Classic GraphQL/projectCards，JSON 只包含 repo、PR number、changedFields、url、body 长度/SHA/source 和 request plan，不默认回显完整正文；再运行 `cat <file> | bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --body-file - --dry-run`，确认 stdin source 标记为 `kind=stdin` 且同样低噪声。运行 `bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run`，确认命令不写评论，JSON 中包含 PR number、bodyChars、bodySource 和 request plan，且没有把换行污染成字面量 `\n`。运行 `bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk`，确认返回非零状态和结构化 JSON，`degradedReason=unsupported-command`、`runnerDisposition=business-failed`，且不会真实 merge。需要测试真实创建、编辑或评论时，只允许使用明确的 throwaway 源分支和 PR，并在记录中写明 PR URL、number、源/目标分支和清理动作；默认验收只做 dry-run，不创建或修改真实 PR。 ## T27 GitHub Issue/Comment 换行转义卫生扫描 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 94023a35..3834e5e7 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -39,8 +39,8 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI - `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是 legacy #24 指挥简报的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。每日滚动简报 issue 可用普通 `gh issue update <number> --body-profile commander-brief --dry-run` 和并发 guard 更新，但此通知 helper 仍只支持 #24。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`，可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 覆盖。 - `gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run]` 是总看板只读结构审计入口，默认 repo 为 `pikasTech/unidesk`、board issue 为 `20`、输出 JSON 且不 PATCH/POST/DELETE GitHub。它只读取目标 board issue 正文，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表是否覆盖全部 issue。兼容字段 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`openInClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions` 仍保留，但固定为空数组或 0，用于避免旧调用方因字段缺失失败。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 `gh issue board-row list|get|update|add|move|delete|upsert` 的行级结构化入口。 - `gh issue board-row list --board-issue 20 [--state open|closed|all] [--dry-run]`、`gh issue board-row get <issueNumber> --board-issue 20` 和 `gh issue board-row update <issueNumber> --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text> [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256]` 是 #20 看板表格单行结构化入口。list/get 复用 board-audit parser，只读返回 row、cells、fields、section、lineNumber、bodySha 和 rowValidationWarnings。update 只替换命中的一行里一个单元格，返回 old/new row、old/new body SHA、body guard、request plan 和 parser 结果；默认没有并发期望时即使不写 `--dry-run` 也只做 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射固定为：`branch` -> Branch，`progress` -> 进度，`status`/`validation` -> 验收状态，`tasks` -> 相关 Code Queue 任务，`focus` -> 当前关注点。单元格值中的 Markdown 表格管道会转义为 `\|`，真实换行会折叠为空格，避免新增字面量 `\n` 污染。`gh issue board-row upsert <issueNumber> --board-issue 20 --section open|closed [--category text] --branch <branch> --tasks <task> --summary <text> --focus <text> --validation <text> --progress <text> [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at]` 是行级补齐入口：若 issue 已存在则只更新传入字段并返回 `operation=update`，未传字段保留原值；若不存在则按目标 section 表头生成完整行并返回 `operation=add`。新增时 `--section` 必需，且目标表头中的 category/branch/tasks/summary/focus/validation/progress 列都必须有对应值；若表没有独立 Summary/摘要列，`--summary` 会并入 Issue 单元格。upsert 不关闭、不删除、不重开 GitHub issue，也不做 OPEN/CLOSED 迁移；已存在行的 `--section` 或 `--status` 与当前 section 冲突时会结构化失败并提示使用 `board-row move`。`gh issue board-row add <issueNumber> --board-issue 20 --section open|closed --row-file <file> [--dry-run] [--expect-body-sha|--expect-updated-at]`、`move <issueNumber> --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at]` 和 `delete <issueNumber> --board-issue 20 [--dry-run] [--expect-body-sha|--expect-updated-at]` 是 row-scoped #20 结构化写入口。add 校验一行 `--row-file` 的 Issue 列、列数和 GitHub 状态列与目标 section 一致；move 允许跨 OPEN/CLOSED 表迁移并在需要时同步 GitHub 状态列；delete 仅删除匹配行。四类写入口默认 dry-run，非 dry-run 必须带 `--expect-body-sha` 或 `--expect-updated-at`，并返回 old/new row、body SHA、line/section 计划和 parser 结果；duplicate/ambiguous row、列数不匹配、缺少新增必填字段、section/status 冲突或 body SHA 不匹配都会结构化失败，不会 fallback 到整篇 body 手工替换。 -- `gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape、escaped backtick、ANSI escape 字符串、短 body、blank body 和 null body。输出固定 JSON，`findings` 会带 `bodyKind=issue-body|comment-body`、`issueNumber`、`issueId`、`commentId`、`lineNumber`、`column`、`kind`、`snippet` 和 `classification=suspected-pollution|explanatory-mention|risk`，用于区分说明性提到 `\n` 和疑似污染；`cleanupSuggestions` 只给 dry-run 清理建议、body/comment 定位和 diff-like preview，不 PATCH、不 DELETE、不真实清理历史 comment。`gh issue cleanup-plan` 是同一只读能力的别名，默认 `dryRun=true`。`gh pr list [--state open|closed|all] [--json ...]` 提供 REST 列表，默认 `state=all` 以保持既有 UniDesk CLI 行为，字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`gh pr read|view <number|owner/repo#number> [--json ...] [--raw|--full]` 继续稳定返回这些字段，并额外支持 `headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`owner/repo#number` shorthand 和冲突 `--repo` 规则与 issue read/view 相同。`headRefName` 与 `baseRefName` 来自 REST `head.ref`/`base.ref`；`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 只在 read/view 明确请求这些字段或用 `--raw|--full` 显式完整披露时通过 GitHub GraphQL 查询，GraphQL 权限不足、网络失败或 GitHub 暂未计算完成时会结构化失败或返回 GitHub 原始 `UNKNOWN`/null 状态。此时收口人员应优先重试一次；若仍缺失、需要完整 `gh pr view --json` 等 GitHub 官方字段、或需要执行 merge/review 这类 UniDesk CLI 尚未开放的操作，回退到系统 `gh` 只读观察或人工 GitHub UI，不要把空字段当作可合并证据。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr edit <number> [--title ...] [--body-file <file>|--body-file -|--body <text>] [--dry-run]`、`gh pr update <number> --mode replace|append [--body-file <file>|--body-file -|--body <text>] [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr edit/update` 使用 REST `PATCH /repos/{owner}/{repo}/pulls/{number}`，只发送显式提供的 `title` 和/或 `body` 字段，完全避开 GitHub Projects Classic GraphQL/projectCards；输出低噪声 JSON：`ok`、`repo`、PR number、`changedFields`、`url`、body 长度/SHA/source 元数据和 request plan，不默认回显完整正文。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。 -- PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --state open --limit 5 --json number,title,state,url,head,base` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 做只读 PR 观察和收口元数据检查；`bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-file <file> --dry-run` 或 `cat <file> | bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --body-file - --dry-run` 检查低噪声 PR 标题/正文编辑计划；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。 +- `gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape、escaped backtick、ANSI escape 字符串、短 body、blank body 和 null body。输出固定 JSON，`findings` 会带 `bodyKind=issue-body|comment-body`、`issueNumber`、`issueId`、`commentId`、`lineNumber`、`column`、`kind`、`snippet` 和 `classification=suspected-pollution|explanatory-mention|risk`，用于区分说明性提到 `\n` 和疑似污染；`cleanupSuggestions` 只给 dry-run 清理建议、body/comment 定位和 diff-like preview，不 PATCH、不 DELETE、不真实清理历史 comment。`gh issue cleanup-plan` 是同一只读能力的别名，默认 `dryRun=true`。`gh pr list [--state open|closed|all] [--json ...]` 提供 REST 列表，默认 `state=all` 以保持既有 UniDesk CLI 行为，字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`gh pr files <number> [--limit N]` 是 PR changed-file/stat summary 的稳定 REST 入口，返回 bounded `files`、`filesReturned`、`summary.files/additions/deletions/changes/commits`、`truncation` 和 `next.command`，默认不输出 raw diff 或 patch；`gh pr diff <number> --stat` 是兼容别名，返回同一 JSON，未带 `--stat` 的 raw diff 请求会结构化拒绝。`gh pr read|view <number|owner/repo#number> [--json ...] [--raw|--full]` 继续稳定返回这些字段，并额外支持 `headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`owner/repo#number` shorthand 和冲突 `--repo` 规则与 issue read/view 相同。`headRefName` 与 `baseRefName` 来自 REST `head.ref`/`base.ref`；`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 只在 read/view 明确请求这些字段或用 `--raw|--full` 显式完整披露时通过 GitHub GraphQL 查询，GraphQL 权限不足、网络失败或 GitHub 暂未计算完成时会结构化失败或返回 GitHub 原始 `UNKNOWN`/null 状态。此时收口人员应优先重试一次；若仍缺失、需要完整 `gh pr view --json` 等 GitHub 官方字段、或需要执行 merge/review 这类 UniDesk CLI 尚未开放的操作，回退到系统 `gh` 只读观察或人工 GitHub UI，不要把空字段当作可合并证据。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr edit <number> [--title ...] [--body-file <file>|--body-file -|--body <text>] [--dry-run]`、`gh pr update <number> --mode replace|append [--body-file <file>|--body-file -|--body <text>] [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr edit/update` 使用 REST `PATCH /repos/{owner}/{repo}/pulls/{number}`，只发送显式提供的 `title` 和/或 `body` 字段，完全避开 GitHub Projects Classic GraphQL/projectCards；输出低噪声 JSON：`ok`、`repo`、PR number、`changedFields`、`url`、body 长度/SHA/source 元数据和 request plan，不默认回显完整正文。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。 +- PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --state open --limit 5 --json number,title,state,url,head,base`、`bun scripts/cli.ts gh pr files <number> --repo pikasTech/unidesk --limit 30` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 做只读 PR 观察、文件统计和收口元数据检查；`bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-file <file> --dry-run` 或 `cat <file> | bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --body-file - --dry-run` 检查低噪声 PR 标题/正文编辑计划；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。 - `ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。 - `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule list`、`schedule get`、`schedule runs --limit N` 和 `schedule runs <scheduleId> --limit N` 是只读观察入口；`schedule run`、`schedule retry-run`、`schedule delete` 和 `schedule upsert-pgdata-backup` 会触发运行或写入配置，生产恢复时必须有明确授权。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。当 backend-core 目标容器缺失或只观察到 verify-only 容器时，schedule/microservice 命令必须以非零退出并返回 `failureKind=target-stack-not-running`、`runnerDisposition=infra-blocked`、`readOnlyCommands` 和 `authorizationRequiredForRecovery`，不得把 Docker 的 `No such container` 当成成功的空历史。 - `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。 diff --git a/scripts/gh-cli-pr-files-contract-test.ts b/scripts/gh-cli-pr-files-contract-test.ts new file mode 100644 index 00000000..cd995870 --- /dev/null +++ b/scripts/gh-cli-pr-files-contract-test.ts @@ -0,0 +1,230 @@ +import { spawn } from "node:child_process"; +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; +import type { AddressInfo } from "node:net"; + +type JsonRecord = Record<string, unknown>; + +interface MockRequest { + method: string; + url: string; + body: string; +} + +function assertCondition(condition: unknown, message: string, detail: unknown = {}): void { + if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`); +} + +function runBun(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> { + return new Promise((resolve, reject) => { + const child = spawn("bun", args, { + cwd: process.cwd(), + env: { ...process.env, ...env }, + }); + const stdoutChunks: Buffer[] = []; + const stderrChunks: Buffer[] = []; + child.stdout.on("data", (chunk) => stdoutChunks.push(Buffer.from(chunk))); + child.stderr.on("data", (chunk) => stderrChunks.push(Buffer.from(chunk))); + child.on("error", reject); + child.on("close", (status) => { + const stdout = Buffer.concat(stdoutChunks).toString("utf8"); + let json: JsonRecord | null = null; + try { + json = JSON.parse(stdout) as JsonRecord; + } catch { + json = null; + } + resolve({ + status, + stdout, + stderr: Buffer.concat(stderrChunks).toString("utf8"), + json, + }); + }); + }); +} + +function runCli(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> { + return runBun(["scripts/cli.ts", ...args], env); +} + +function collectBody(req: IncomingMessage): Promise<string> { + return new Promise((resolve) => { + const chunks: Buffer[] = []; + req.on("data", (chunk) => chunks.push(Buffer.from(chunk))); + req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8"))); + }); +} + +function sendJson(res: ServerResponse, status: number, payload: unknown): void { + res.statusCode = status; + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify(payload)); +} + +function prFixture(): JsonRecord { + return { + id: 4200, + number: 42, + title: "CLI summary fixture", + body: "fixture body", + state: "open", + html_url: "https://github.example/pikasTech/unidesk/pull/42", + draft: false, + user: { login: "runner" }, + head: { ref: "feature/pr-files", sha: "abc123" }, + base: { ref: "master", sha: "def456" }, + additions: 12, + deletions: 3, + changed_files: 2, + commits: 1, + created_at: "2026-05-23T00:00:00Z", + updated_at: "2026-05-23T00:10:00Z", + }; +} + +function prFilesFixture(): JsonRecord[] { + return [ + { + sha: "aaa", + filename: "scripts/src/gh.ts", + status: "modified", + additions: 10, + deletions: 2, + changes: 12, + blob_url: "https://github.example/blob/scripts/src/gh.ts", + raw_url: "https://github.example/raw/scripts/src/gh.ts", + contents_url: "https://api.github.example/contents/scripts/src/gh.ts", + patch: "@@ raw diff must not be returned @@", + }, + { + sha: "bbb", + filename: "scripts/gh-cli-pr-files-contract-test.ts", + status: "added", + additions: 2, + deletions: 1, + changes: 3, + blob_url: "https://github.example/blob/scripts/gh-cli-pr-files-contract-test.ts", + raw_url: "https://github.example/raw/scripts/gh-cli-pr-files-contract-test.ts", + contents_url: "https://api.github.example/contents/scripts/gh-cli-pr-files-contract-test.ts", + patch: "@@ raw diff must not be returned either @@", + }, + ]; +} + +async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockRequest[]; close: () => Promise<void> }> { + const requests: MockRequest[] = []; + const server = createServer(async (req, res) => { + const body = await collectBody(req); + requests.push({ method: req.method ?? "", url: req.url ?? "", body }); + const url = new URL(req.url ?? "/", "http://localhost"); + if (req.method === "GET" && url.pathname === "/repos/pikasTech/unidesk/pulls/42") { + sendJson(res, 200, prFixture()); + return; + } + if (req.method === "GET" && url.pathname === "/repos/pikasTech/unidesk/pulls/42/files") { + const perPage = Number(url.searchParams.get("per_page") ?? "30"); + const page = Number(url.searchParams.get("page") ?? "1"); + const offset = (page - 1) * perPage; + sendJson(res, 200, prFilesFixture().slice(offset, offset + perPage)); + return; + } + sendJson(res, 404, { message: `unexpected ${req.method} ${req.url}` }); + }); + await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve)); + const address = server.address(); + assertCondition(typeof address === "object" && address !== null, "mock server should expose address"); + const port = (address as AddressInfo).port; + assertCondition(typeof port === "number", "mock server should expose port"); + return { + baseUrl: `http://127.0.0.1:${port}`, + requests, + close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())), + }; +} + +function dataOf(response: JsonRecord): JsonRecord { + assertCondition(response.ok === true, "CLI command should succeed", response); + assertCondition(typeof response.data === "object" && response.data !== null && !Array.isArray(response.data), "response data should be object", response); + return response.data as JsonRecord; +} + +function failedDataOf(response: JsonRecord): JsonRecord { + assertCondition(response.ok === false, "CLI command should fail", response); + assertCondition(typeof response.data === "object" && response.data !== null && !Array.isArray(response.data), "failure data should be object", response); + return response.data as JsonRecord; +} + +export async function runGhCliPrFilesContract(): Promise<JsonRecord> { + const help = await runCli(["gh", "help"]); + assertCondition(help.status === 0, "gh help should succeed", help.json ?? { stdout: help.stdout }); + const helpData = dataOf(help.json ?? {}); + const usage = Array.isArray(helpData.usage) ? helpData.usage.map((value) => String(value)) : []; + const notes = Array.isArray(helpData.notes) ? helpData.notes.map((value) => String(value)) : []; + assertCondition(usage.some((line) => line.includes("gh pr files <number>")), "help should document gh pr files", { usage }); + assertCondition(usage.some((line) => line.includes("gh pr diff <number> --stat")), "help should document gh pr diff --stat", { usage }); + assertCondition(notes.some((line) => line.includes("PR files is the canonical compact changed-file/stat summary")), "help should document PR files disclosure boundary", { notes }); + + const mock = await startMockGitHub(); + const env = { + GH_TOKEN: "contract-token", + UNIDESK_GITHUB_API_URL: mock.baseUrl, + }; + const checks: string[] = ["gh help documents pr files and pr diff --stat"]; + try { + mock.requests.length = 0; + const files = await runCli(["gh", "pr", "files", "42", "--repo", "pikasTech/unidesk", "--limit", "1"], env); + assertCondition(files.status === 0, "gh pr files should succeed", files.json ?? { stdout: files.stdout, stderr: files.stderr }); + const filesData = dataOf(files.json ?? {}); + assertCondition(filesData.command === "pr files", "command name should be pr files", filesData); + assertCondition(filesData.rawDiffIncluded === false, "rawDiffIncluded must be false", filesData); + const summary = filesData.summary as JsonRecord; + assertCondition(summary.files === 2, "summary must include total changed files", summary); + assertCondition(summary.additions === 12, "summary additions should come from PR REST", summary); + assertCondition(summary.deletions === 3, "summary deletions should come from PR REST", summary); + assertCondition(summary.changes === 15, "summary changes should include additions plus deletions", summary); + assertCondition(filesData.filesReturned === 1, "limit 1 should return one file", filesData); + const fileRows = filesData.files as JsonRecord[]; + assertCondition(Array.isArray(fileRows) && fileRows.length === 1, "files list should be bounded", filesData); + assertCondition(fileRows[0]?.filename === "scripts/src/gh.ts", "first file filename mismatch", fileRows[0]); + assertCondition(fileRows[0]?.patch === undefined, "raw patch must not be emitted", fileRows[0]); + assertCondition(fileRows[0]?.raw_url === undefined, "raw_url field casing must not leak", fileRows[0]); + const truncation = filesData.truncation as JsonRecord; + assertCondition(truncation.truncated === true, "limit 1 should mark truncation", truncation); + assertCondition(truncation.totalFiles === 2, "truncation should expose totalFiles", truncation); + const next = filesData.next as JsonRecord; + assertCondition(String(next.command).includes("--limit 2"), "next command should request the bounded full file count", next); + assertCondition(mock.requests.some((request) => request.method === "GET" && request.url === "/repos/pikasTech/unidesk/pulls/42/files?per_page=1&page=1"), "files endpoint should use bounded per_page", mock.requests); + checks.push("gh pr files returns bounded REST file/stat JSON without raw patches"); + + mock.requests.length = 0; + const stat = await runCli(["gh", "pr", "diff", "42", "--stat", "--repo", "pikasTech/unidesk", "--limit", "2"], env); + assertCondition(stat.status === 0, "gh pr diff --stat should succeed", stat.json ?? { stdout: stat.stdout, stderr: stat.stderr }); + const statData = dataOf(stat.json ?? {}); + assertCondition(statData.command === "pr diff --stat", "diff --stat should report alias command name", statData); + assertCondition(statData.rawDiffIncluded === false, "diff --stat must not include raw diff", statData); + assertCondition(statData.filesReturned === 2, "diff --stat should return requested files", statData); + const statRows = statData.files as JsonRecord[]; + assertCondition(statRows.every((file) => file.patch === undefined), "diff --stat file rows must not include patch", statRows); + checks.push("gh pr diff --stat is a compact summary alias"); + + const rawDiff = await runCli(["gh", "pr", "diff", "42", "--repo", "pikasTech/unidesk"], env); + assertCondition(rawDiff.status !== 0, "gh pr diff without --stat should fail closed", rawDiff.json ?? { stdout: rawDiff.stdout, stderr: rawDiff.stderr }); + const rawData = failedDataOf(rawDiff.json ?? {}); + assertCondition(rawData.degradedReason === "unsupported-command", "raw diff should fail as unsupported-command", rawData); + assertCondition(rawData.rawDiffIncluded === false, "raw diff failure should state rawDiffIncluded=false", rawData); + checks.push("gh pr diff without --stat fails closed without raw diff output"); + + return { ok: true, checks }; + } finally { + await mock.close(); + } +} + +if (import.meta.main) { + runGhCliPrFilesContract() + .then((result) => console.log(JSON.stringify(result, null, 2))) + .catch((error) => { + console.error(error instanceof Error ? error.stack ?? error.message : String(error)); + process.exitCode = 1; + }); +} diff --git a/scripts/src/check.ts b/scripts/src/check.ts index 6bab0eca..cc702d29 100644 --- a/scripts/src/check.ts +++ b/scripts/src/check.ts @@ -325,6 +325,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default fileItem("scripts/decision-center-desired-state-contract-test.ts"), fileItem("scripts/code-queue-prompt-observation-test.ts"), fileItem("scripts/gh-cli-issue-guard-contract-test.ts"), + fileItem("scripts/gh-cli-pr-files-contract-test.ts"), fileItem("scripts/gh-cli-pr-contract-test.ts"), fileItem("scripts/code-queue-pr-preflight-example.ts"), fileItem("scripts/schedule-cli-contract-test.ts"), @@ -370,6 +371,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(commandItem("schedule:cli-contract", ["bun", "scripts/schedule-cli-contract-test.ts"], 30_000)); items.push(commandItem("server:cleanup-plan-contract", ["bun", "scripts/server-cleanup-plan-contract-test.ts"], 30_000)); items.push(commandItem("gh:issue-guard-contract", ["bun", "scripts/gh-cli-issue-guard-contract-test.ts"], 30_000)); + items.push(commandItem("gh:pr-files-contract", ["bun", "scripts/gh-cli-pr-files-contract-test.ts"], 30_000)); items.push(commandItem("gh:pr-contract", ["bun", "scripts/gh-cli-pr-contract-test.ts"], 30_000)); items.push(commandItem("auth-broker:p0-contract", ["bun", "scripts/auth-broker-contract-test.ts"], 30_000)); } else { @@ -396,6 +398,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(skippedItem("schedule:cli-contract", "Schedule CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("server:cleanup-plan-contract", "Server cleanup dry-run contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("gh:issue-guard-contract", "GitHub issue CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); + items.push(skippedItem("gh:pr-files-contract", "GitHub PR files/stat contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("gh:pr-contract", "GitHub PR CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("auth-broker:p0-contract", "Auth Broker P0 skeleton and CLI adapter contract is opt-in with script checks", "--scripts-typecheck or --full")); } diff --git a/scripts/src/gh.ts b/scripts/src/gh.ts index 83bbc2e9..25d630c3 100644 --- a/scripts/src/gh.ts +++ b/scripts/src/gh.ts @@ -13,6 +13,7 @@ const DEFAULT_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL = "http://backend-core:8080/api/ const DEFAULT_COMMANDER_BRIEF_CLAUDEQQ_USER_ID = "645275593"; const CODE_QUEUE_BOARD_TARGET_ISSUE = 20; const COMMANDER_BRIEF_TARGET_ISSUE = 24; +const MAX_PR_FILES_LIMIT = 3000; const DEFAULT_BOARD_KNOWN_META_ISSUES = [CODE_QUEUE_BOARD_TARGET_ISSUE, COMMANDER_BRIEF_TARGET_ISSUE] as const; const BOARD_AUDIT_REQUIRED_COLUMNS = ["branch", "acceptance", "relatedTask", "progress"] as const; const BOARD_ROW_FIELDS = ["progress", "status", "validation", "branch", "tasks", "focus"] as const; @@ -404,12 +405,30 @@ interface GitHubPullRequest { user?: { login?: string }; head?: { ref?: string; sha?: string }; base?: { ref?: string; sha?: string }; + additions?: number; + deletions?: number; + changed_files?: number; + commits?: number; mergeable?: string | null; merge_state_status?: string | null; created_at?: string; updated_at?: string; } +interface GitHubPullRequestFile { + sha?: string; + filename: string; + status?: string; + additions?: number; + deletions?: number; + changes?: number; + blob_url?: string; + raw_url?: string; + contents_url?: string; + previous_filename?: string; + patch?: string; +} + interface GitHubPullRequestGraphqlStatusContext { __typename?: string; name?: string | null; @@ -640,7 +659,7 @@ function parseBoardRowUpsertValues(args: string[]): BoardRowUpsertValues { function validateKnownOptions(args: string[]): void { const valueOptions = new Set(["--repo", "--limit", "--board-issue", "--known-meta-issue", "--ignore-issue", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label", "--field", "--value", "--section", "--to", "--status", "--row-file", "--category", "--branch", "--tasks", "--summary", "--focus", "--validation", "--progress"]); - const flagOptions = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body", "--raw", "--full"]); + const flagOptions = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body", "--raw", "--full", "--stat"]); for (let index = 0; index < args.length; index += 1) { const arg = args[index]; if (!arg.startsWith("--")) continue; @@ -657,12 +676,13 @@ function parseOptions(args: string[]): GitHubOptions { validateKnownOptions(args); const [top, sub] = args; const requestedJsonFields = commaListOption(args, "--json"); + const limitMax = top === "pr" && (sub === "files" || sub === "diff") ? MAX_PR_FILES_LIMIT : 100; return { repo: optionValue(args, "--repo") ?? DEFAULT_REPO, dryRun: hasFlag(args, "--dry-run"), raw: hasFlag(args, "--raw"), full: hasFlag(args, "--full"), - limit: positiveIntegerOption(args, "--limit", top === "issue" && sub === "board-audit" ? 100 : 30, 100), + limit: positiveIntegerOption(args, "--limit", top === "issue" && sub === "board-audit" ? 100 : 30, limitMax), boardIssue: positiveIntegerSingleOption(args, "--board-issue", CODE_QUEUE_BOARD_TARGET_ISSUE), knownMetaIssues: positiveIntegerValuesOption(args, "--known-meta-issue"), ignoredIssues: positiveIntegerValuesOption(args, "--ignore-issue"), @@ -3557,6 +3577,49 @@ function prSummary(pr: GitHubPullRequest): Record<string, unknown> { }; } +function numberOrNull(value: number | undefined): number | null { + return typeof value === "number" && Number.isFinite(value) ? value : null; +} + +function prCompactSummary(pr: GitHubPullRequest): Record<string, unknown> { + return { + id: pr.id, + number: pr.number, + title: pr.title, + state: pr.state, + draft: pr.draft ?? false, + url: pr.html_url, + author: pr.user?.login ?? null, + head: { ref: pr.head?.ref ?? null, sha: pr.head?.sha ?? null }, + base: { ref: pr.base?.ref ?? null, sha: pr.base?.sha ?? null }, + createdAt: pr.created_at ?? null, + updatedAt: pr.updated_at ?? null, + }; +} + +function prFileSummary(file: GitHubPullRequestFile): Record<string, unknown> { + return { + filename: file.filename, + status: file.status ?? null, + additions: numberOrNull(file.additions), + deletions: numberOrNull(file.deletions), + changes: numberOrNull(file.changes), + previousFilename: file.previous_filename ?? null, + sha: file.sha ?? null, + blobUrl: file.blob_url ?? null, + contentsUrl: file.contents_url ?? null, + }; +} + +function sumPrFileStats(files: GitHubPullRequestFile[]): { additions: number; deletions: number; changes: number } { + return files.reduce((accumulator, file) => { + accumulator.additions += file.additions ?? 0; + accumulator.deletions += file.deletions ?? 0; + accumulator.changes += file.changes ?? ((file.additions ?? 0) + (file.deletions ?? 0)); + return accumulator; + }, { additions: 0, deletions: 0, changes: 0 }); +} + function selectedPrJson(summary: Record<string, unknown>, fields: readonly string[]): Record<string, unknown> { const selected: Record<string, unknown> = {}; for (const field of fields) selected[field] = summary[field]; @@ -4839,6 +4902,75 @@ async function prList(repo: string, token: string, state: PrListState, limit: nu }; } +async function prFiles(repo: string, token: string, number: number, limit: number, commandName = "pr files"): Promise<GitHubCommandResult> { + const { owner, name } = repoParts(repo); + const boundedLimit = Math.min(limit, MAX_PR_FILES_LIMIT); + const pr = await githubRequest<GitHubPullRequest>(token, "GET", `/repos/${owner}/${name}/pulls/${number}`); + if (isGitHubError(pr)) return commandError(commandName, repo, pr, { number }); + const perPage = Math.max(1, Math.min(100, boundedLimit)); + const files: GitHubPullRequestFile[] = []; + let page = 1; + while (files.length < boundedLimit) { + const remaining = boundedLimit - files.length; + const pageSize = Math.min(perPage, remaining); + const path = `/repos/${owner}/${name}/pulls/${number}/files?per_page=${pageSize}&page=${page}`; + const pageFiles = await githubRequest<GitHubPullRequestFile[]>(token, "GET", path); + if (isGitHubError(pageFiles)) return commandError(commandName, repo, pageFiles, { number, phase: "fetch-pr-files", filesReturned: files.length }); + files.push(...pageFiles); + if (pageFiles.length < pageSize || pageFiles.length === 0) break; + page += 1; + } + const totalFiles = numberOrNull(pr.changed_files); + const listedStats = sumPrFileStats(files); + const totalAdditions = numberOrNull(pr.additions); + const totalDeletions = numberOrNull(pr.deletions); + const fullStatsAvailable = totalAdditions !== null && totalDeletions !== null; + const totalChanges = fullStatsAvailable ? totalAdditions + totalDeletions : listedStats.changes; + const truncated = totalFiles !== null ? files.length < totalFiles : files.length >= boundedLimit; + const nextLimit = totalFiles === null ? MAX_PR_FILES_LIMIT : Math.min(totalFiles, MAX_PR_FILES_LIMIT); + const nextCommand = truncated + ? `bun scripts/cli.ts gh pr files ${number} --repo ${repo} --limit ${nextLimit}` + : `bun scripts/cli.ts gh pr read ${number} --repo ${repo} --json body,title,state,head,base`; + return { + ok: true, + command: commandName, + repo, + readOnly: true, + rawDiffIncluded: false, + pullRequest: prCompactSummary(pr), + summary: { + files: totalFiles ?? files.length, + additions: totalAdditions ?? listedStats.additions, + deletions: totalDeletions ?? listedStats.deletions, + changes: totalChanges, + commits: numberOrNull(pr.commits), + source: fullStatsAvailable && totalFiles !== null ? "pull-request-rest" : "listed-files-rest", + }, + files: files.map(prFileSummary), + filesReturned: files.length, + limit: boundedLimit, + truncation: { + truncated, + requestedLimit: limit, + appliedLimit: boundedLimit, + returned: files.length, + totalFiles, + maxLimit: MAX_PR_FILES_LIMIT, + }, + next: { + command: nextCommand, + purpose: truncated ? "Fetch a larger bounded file summary page." : "Fetch full PR metadata/body; raw diffs remain intentionally excluded.", + }, + request: { + method: "GET", + paths: [ + `/repos/${owner}/${name}/pulls/${number}`, + `/repos/${owner}/${name}/pulls/${number}/files`, + ], + }, + }; +} + async function prRead(repo: string, token: string, number: number, jsonFields: PrReadJsonField[] | undefined, commandName = "pr read", disclosure: Record<string, unknown> | null = null): Promise<GitHubCommandResult> { const { owner, name } = repoParts(repo); const pr = await githubRequest<GitHubPullRequest>(token, "GET", `/repos/${owner}/${name}/pulls/${number}`); @@ -4889,6 +5021,8 @@ export function ghHelp(): unknown { "bun scripts/cli.ts gh issue board-row move <issueNumber> [--repo owner/name] --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha sha256]", "bun scripts/cli.ts gh issue board-row delete <issueNumber> [--repo owner/name] --board-issue 20 [--dry-run] [--expect-body-sha sha256]", "bun scripts/cli.ts gh pr list [--repo owner/name] [--state open|closed|all] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]", + "bun scripts/cli.ts gh pr files <number> [--repo owner/name] [--limit N]", + "bun scripts/cli.ts gh pr diff <number> --stat [--repo owner/name] [--limit N] [compatibility alias for pr files; no raw diff]", "bun scripts/cli.ts gh pr read <number|owner/repo#number> [--repo owner/name] [--json body,title,state,head,base,draft,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup] [--raw|--full]", "bun scripts/cli.ts gh pr view <number|owner/repo#number> [--repo owner/name] [--raw|--full] [compatibility alias for pr read]", "bun scripts/cli.ts gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--repo owner/name] [--draft] [--dry-run]", @@ -4924,6 +5058,7 @@ export function ghHelp(): unknown { "issue edit 24 --notify-claudeqq-brief-diff remains the legacy #24 notification helper: it reads the old issue body, PATCHes the new body, and sends only newly added '## 更新 ... 北京时间' sections to ClaudeQQ; ClaudeQQ failure does not roll back GitHub.", "Commander brief ClaudeQQ defaults to private target 645275593 through backend-core /api/microservices/claudeqq/proxy; UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_* env vars can override target, base URL, timeout, and enabled state.", "comment delete is supported because GitHub supports deleting issue comments; issue/pr hard delete is unsupported and close is the lifecycle alternative.", + "PR files is the canonical compact changed-file/stat summary. It uses GitHub REST, returns bounded file rows, additions/deletions/changes when available, truncation metadata, and a next command for full details. Raw diff patches are not emitted by default; gh pr diff <number> --stat is a compatibility alias for the same JSON summary.", "PR read is the canonical read path; view remains a compatibility alias. PR read/view accept owner/repo#number shorthand and derive --repo unless an explicit conflicting --repo is supplied, which fails structurally with suggested commands. PR read/view supports closeout fields headRefName, baseRefName, mergeable, mergeStateStatus, and statusCheckRollup; mergeability and status rollup are fetched through GitHub GraphQL only when requested or when --raw/--full requests full disclosure.", "PR edit/update PATCHes /repos/{owner}/{repo}/pulls/{number} through REST only, never GitHub Projects Classic GraphQL/projectCards, and returns low-noise JSON with repo, PR number, changedFields, url, and body size/SHA metadata instead of echoing the full body.", "PR create/update/comment are safe-write operations with dry-run planning; merge is intentionally unsupported in this phase.", @@ -4971,6 +5106,15 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult ], }); } + if (optionWasProvided(args, "--stat") && !(top === "pr" && sub === "diff")) { + const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh"; + return validationError(command, options.repo, "--stat is only supported by gh pr diff <number> --stat.", { + supportedCommands: [ + "bun scripts/cli.ts gh pr files <number> --repo owner/name --limit 30", + "bun scripts/cli.ts gh pr diff <number> --stat --repo owner/name --limit 30", + ], + }); + } if (optionWasProvided(args, "--mode") && !((top === "issue" && (sub === "update" || sub === "edit")) || (top === "pr" && (sub === "update" || sub === "edit")))) { const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh"; return validationError(command, options.repo, "--mode is only supported by gh issue update/edit and gh pr update/edit"); @@ -5110,6 +5254,31 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult } if (top === "pr") { + if (sub === "diff") { + const number = parseNumberForCommand(options.repo, third, "pr diff"); + if (typeof number !== "number") return number; + if (!optionWasProvided(args, "--stat")) { + return unsupportedCommand("pr diff", options.repo, "Raw PR diff output is intentionally unsupported by UniDesk CLI; use gh pr diff <number> --stat or gh pr files for a bounded REST file/stat summary.", { + rawDiffIncluded: false, + supportedCommands: [ + `bun scripts/cli.ts gh pr files ${number} --repo ${options.repo} --limit 30`, + `bun scripts/cli.ts gh pr diff ${number} --stat --repo ${options.repo} --limit 30`, + ], + }); + } + const { token, probe } = resolveToken(true); + const missing = authRequired(options.repo, "pr diff --stat", probe); + if (missing !== null || token === null) return missing ?? authRequired(options.repo, "pr diff --stat", { present: false, source: null, ghFallbackAttempted: true }); + return prFiles(options.repo, token, number, options.limit, "pr diff --stat"); + } + if (sub === "files") { + const number = parseNumberForCommand(options.repo, third, "pr files"); + if (typeof number !== "number") return number; + const { token, probe } = resolveToken(true); + const missing = authRequired(options.repo, "pr files", probe); + if (missing !== null || token === null) return missing ?? authRequired(options.repo, "pr files", { present: false, source: null, ghFallbackAttempted: true }); + return prFiles(options.repo, token, number, options.limit, "pr files"); + } if (sub === "delete") return unsupportedCommand("pr delete", options.repo, "GitHub REST does not support hard-deleting pull requests; use gh pr close for lifecycle deletion semantics."); if (sub === "comment" && third === "delete") { const commentId = parseNumberForCommand(options.repo, args[3], "pr comment delete"); @@ -5172,7 +5341,7 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult return unsupportedCommand("pr merge", options.repo, "PR merge is intentionally unsupported in this phase; use create/comment/read only."); } if (sub !== "list" && !isPrReadCommand(sub)) { - return unsupportedCommand(`pr ${sub ?? ""}`.trim(), options.repo, "PR supported commands are list, read/view, create, update/edit, close, reopen, comment create/delete, and unsupported merge/delete."); + return unsupportedCommand(`pr ${sub ?? ""}`.trim(), options.repo, "PR supported commands are list, files, diff --stat, read/view, create, update/edit, close, reopen, comment create/delete, and unsupported merge/delete."); } if (sub === "read" || sub === "view") { const resolved = resolveReadViewNumberReference("pr", sub, third, options, args);