From 68ae2722abf6cf9a23c7930ca71e7fb49360ab32 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 21:20:57 +0000 Subject: [PATCH] feat: add issue board audit cli --- AGENTS.md | 2 +- docs/reference/cli.md | 1 + docs/reference/code-queue-supervision.md | 2 +- scripts/gh-cli-issue-guard-contract-test.ts | 113 ++++- scripts/src/gh.ts | 484 +++++++++++++++++++- 5 files changed, 597 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bc55993d..2296e4f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service ]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout、reviewed registry artifact consumers 和 D601 direct consumer validation，`findjob`/`pipeline` 是 D601 direct pull-only 样板，`met-nonlinear` dry-run blocked，`k3sctl-adapter` supervisor-only，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。 - `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 gh auth status|issue ...|pr list|view|create|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描与只读 cleanup-plan、PR 创建/评论 dry-run 和 runner PR preflight；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 +- `bun scripts/cli.ts gh auth status|issue ...|pr list|view|create|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR 创建/评论 dry-run 与 runner PR preflight；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.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`。 - `bun scripts/cli.ts codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue ]` / `codex pr-preflight [--remote]`：前者通过 backend-core 私有代理提交 Code Queue 任务；后者只读检查 D601 scheduler/runner 的 GitHub token、egress 和 PR 能力，PR 型派单前必须使用，规则见 `docs/reference/cli.md`。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index cc9dae12..25ae92d1 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -34,6 +34,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI - `gh issue view [--repo owner/name] [--json body,title,state,comments]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`gh issue create --title --body-file <file> [--label label[,label...]]... [--dry-run]`、`gh issue update <number> --mode replace|append --body-file <file> [--title ...] [--dry-run]`、`gh issue comment create <number> --body-file <file> [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--dry-run]` 都走 REST，不依赖 `gh` binary。`--label` 仅用于 `issue create`，支持重复传入和逗号分隔；`--dry-run` 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 `validation-failed`，不静默成功。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。 - `gh issue update <number> --mode replace|append --body-file <file>` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和 #24 指挥简报是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用结构 guard：#20 必须包含 `## 看板（OPEN）`，#24 必须包含 `## 常驻观察与长期建议`；也可显式使用 `--body-profile code-queue-board|commander-brief`。`--dry-run` 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格和 shell 污染信号；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入可带 `--expect-updated-at <updated_at>` 或 `--expect-body-sha <sha256>`，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。 - `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是指挥简报 #24 的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。带通知 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]` 是 #20 长期总看板只读覆盖审计入口，默认 repo 为 `pikasTech/unidesk`、board issue 为 `20`、输出 JSON 且不 PATCH/POST/DELETE GitHub。它读取 board body、GitHub open issue 列表和 closed issue 列表，对比 OPEN/CLOSED Markdown 表格并输出 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`openInClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions`。默认把 #20 和 #24 作为 `known-meta` 治理/简报 issue 忽略；需要扩展治理项用 `--known-meta-issue`，临时排除业务 issue 用 `--ignore-issue`。指挥官发现总看板可能漏行时，应先跑 board audit 获取结构化结果，再决定是否人工编辑 #20，而不是只靠 grep。 - `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|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <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 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 --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` 做只读 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`。 diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index e5723c6e..346ade75 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -70,7 +70,7 @@ issue 内容必须自包含，至少写清楚背景、外部收益、当前观 如果某个 worker 任务需要依赖 GitHub issue 内容，但 runner 的 issue 可达性尚未被单独验证，指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点，issue URL 只能作为辅助引用。若要把 issue 作为任务输入源，先单独做可达性探测，再决定是否把 issue 作为常规前置条件。 -GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan`、`gh pr list/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view <number> --json body` 是兼容入口，正文仍应从 `.data.issue.body` 读取；未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh pr list|view --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 +GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan/board-audit`、`gh pr list/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view <number> --json body` 是兼容入口，正文仍应从 `.data.issue.body` 读取；未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh issue board-audit --board-issue 20 --limit N --dry-run` 只读对比 GitHub open/closed issue 列表与 #20 的 OPEN/CLOSED Markdown 表格，输出 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions`，默认把 #20/#24 作为 known-meta 忽略。指挥官发现 #20 可能漏跟 open issue 或分表错误时，应先跑 board audit 取得结构化缺口，再人工审阅和编辑 #20，不要只靠 grep。`gh pr list|view --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 CLI 是短 shout 的需求原语，不是长驻服务器进程。CLI 功能不好用、兼容性不足、安全 guard 不够或输出不利于 runner/指挥官使用时，应默认创建 GitHub issue 并用 Code Queue 推进；这类 CLI 问题走 `master`、remote commit、轻量 contract test 和文档更新，不套用 backend-core、Code Queue runtime 这类运行态服务的重部署门禁。若 CLI 缺陷已经阻塞当前指挥，可以先做最小安全绕行，同时把长期修复写入 issue 并派单。 diff --git a/scripts/gh-cli-issue-guard-contract-test.ts b/scripts/gh-cli-issue-guard-contract-test.ts index 3a3c5662..2766225b 100644 --- a/scripts/gh-cli-issue-guard-contract-test.ts +++ b/scripts/gh-cli-issue-guard-contract-test.ts @@ -86,6 +86,28 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque created_at: "2026-05-20T00:00:00Z", updated_at: "2026-05-20T01:00:00Z", }; + const boardIssue = { + ...issue, + body: [ + "# Code Queue", + "", + "## 看板（OPEN）", + "", + "| Issue | Branch | 验收状态 | 相关任务 | 进度 |", + "| --- | --- | --- | --- | --- |", + "| #20 | master | meta | governance | active |", + "| #35 master：补齐 UniDesk CLI gh issue list 与 PR 驱动最小闭环前置能力 | master | pass | cq-35 | doing |", + "| #40 closed issue still in open | | | cq-40 | |", + "", + "## 看板（CLOSED）", + "", + "| Issue | Branch | 验收状态 | 相关任务 | 进度 |", + "| --- | --- | --- | --- | --- |", + "| #24 | master | meta | brief | active |", + "| #36 second issue | master | pending | cq-36 | misplaced |", + "", + ].join("\n"), + }; const issueList = [ { id: 2001, @@ -169,6 +191,64 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque updated_at: "2026-05-20T04:40:00Z", }, ]; + const boardOpenIssues = [ + { + id: 2000, + number: 20, + title: "长期总看板", + body: boardIssue.body, + state: "open", + html_url: "https://github.com/pikasTech/unidesk/issues/20", + comments: 1, + user: { login: "tester" }, + labels: [], + created_at: "2026-05-20T00:00:00Z", + updated_at: "2026-05-20T01:00:00Z", + }, + issueList[0], + issueList[1], + { + id: 2004, + number: 24, + title: "指挥简报", + body: "brief", + state: "open", + html_url: "https://github.com/pikasTech/unidesk/issues/24", + comments: 0, + user: { login: "tester" }, + labels: [], + created_at: "2026-05-20T01:00:00Z", + updated_at: "2026-05-20T02:00:00Z", + }, + ]; + const boardClosedIssues = [ + { + id: 2040, + number: 40, + title: "closed issue still in open", + body: "closed body", + state: "closed", + html_url: "https://github.com/pikasTech/unidesk/issues/40", + comments: 0, + user: { login: "runner" }, + labels: [], + created_at: "2026-05-19T02:00:00Z", + updated_at: "2026-05-20T03:00:00Z", + }, + { + id: 2041, + number: 41, + title: "closed issue missing from closed table", + body: "closed body", + state: "closed", + html_url: "https://github.com/pikasTech/unidesk/issues/41", + comments: 0, + user: { login: "runner" }, + labels: [], + created_at: "2026-05-19T02:05:00Z", + updated_at: "2026-05-20T03:05:00Z", + }, + ]; const comments = [ { id: 1, @@ -206,7 +286,7 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque const body = await collectBody(req); requests.push({ method: req.method ?? "", url: req.url ?? "", body }); if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues/20") { - sendJson(res, 200, issue); + sendJson(res, 200, boardIssue); return; } if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues/20/comments?per_page=100") { @@ -229,6 +309,14 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque sendJson(res, 200, scanIssues); return; } + if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues?state=open&per_page=100") { + sendJson(res, 200, boardOpenIssues); + return; + } + if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues?state=closed&per_page=100") { + sendJson(res, 200, boardClosedIssues); + return; + } for (const [issueNumber, issueComments] of Object.entries(scanComments)) { if (req.method === "GET" && req.url === `/repos/pikasTech/unidesk/issues/${issueNumber}/comments?per_page=100`) { sendJson(res, 200, issueComments); @@ -352,6 +440,28 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const cleanupPlanData = dataOf(cleanupPlan.json ?? {}); assertCondition(cleanupPlanData.command === "issue cleanup-plan" && cleanupPlanData.dryRun === true, "cleanup-plan should remain dry-run", cleanupPlanData); + const boardAuditRequestCountBefore = mock.requests.length; + const boardAudit = await runCli(["gh", "issue", "board-audit", "--repo", "pikasTech/unidesk", "--limit", "100", "--dry-run"], env); + assertCondition(boardAudit.status === 0, "issue board-audit should succeed as a read-only audit", boardAudit.json ?? { stdout: boardAudit.stdout, stderr: boardAudit.stderr }); + const boardAuditData = dataOf(boardAudit.json ?? {}); + assertCondition(boardAuditData.command === "issue board-audit" && boardAuditData.dryRun === true && boardAuditData.readOnly === true, "board-audit should be explicit read-only dry-run", boardAuditData); + const missingOpenIssues = boardAuditData.missingOpenIssues as JsonRecord[]; + assertCondition(Array.isArray(missingOpenIssues) && missingOpenIssues.some((issue) => issue.number === 36), "board-audit should report open issue missing from OPEN table", missingOpenIssues); + const closedInOpenRows = boardAuditData.closedInOpenRows as JsonRecord[]; + assertCondition(Array.isArray(closedInOpenRows) && closedInOpenRows.some((issue) => issue.number === 40), "board-audit should report closed issue still in OPEN table", closedInOpenRows); + const missingClosedRows = boardAuditData.missingClosedRows as JsonRecord[]; + assertCondition(Array.isArray(missingClosedRows) && missingClosedRows.some((issue) => issue.number === 40) && missingClosedRows.some((issue) => issue.number === 41), "board-audit should report closed issues missing from CLOSED table", missingClosedRows); + const openInClosedRows = boardAuditData.openInClosedRows as JsonRecord[]; + assertCondition(Array.isArray(openInClosedRows) && openInClosedRows.some((issue) => issue.number === 36), "board-audit should report open issue placed in CLOSED table", openInClosedRows); + const rowValidationWarnings = boardAuditData.rowValidationWarnings as JsonRecord[]; + assertCondition(Array.isArray(rowValidationWarnings) && rowValidationWarnings.some((warning) => warning.issueNumber === 40 && Array.isArray(warning.missingColumns) && (warning.missingColumns as unknown[]).includes("branch") && (warning.missingColumns as unknown[]).includes("acceptance") && (warning.missingColumns as unknown[]).includes("progress")), "board-audit should report missing required board columns", rowValidationWarnings); + const ignoredIssues = boardAuditData.ignoredIssues as JsonRecord[]; + assertCondition(Array.isArray(ignoredIssues) && ignoredIssues.some((issue) => issue.number === 20 && issue.reason === "known-meta") && ignoredIssues.some((issue) => issue.number === 24 && issue.reason === "known-meta"), "board-audit should ignore configured known meta issues", ignoredIssues); + const recommendedActions = boardAuditData.recommendedActions as JsonRecord[]; + assertCondition(Array.isArray(recommendedActions) && recommendedActions.some((action) => action.action === "add-open-row" && action.issueNumber === 36) && recommendedActions.some((action) => action.action === "move-open-row-to-closed" && action.issueNumber === 40), "board-audit should emit machine-readable recommended actions", recommendedActions); + const boardAuditWriteCount = mock.requests.slice(boardAuditRequestCountBefore).filter((request) => request.method === "PATCH" || request.method === "DELETE" || request.method === "POST").length; + assertCondition(boardAuditWriteCount === 0, "board-audit must not write GitHub", { requests: mock.requests.slice(boardAuditRequestCountBefore) }); + const badListField = await runCli(["gh", "issue", "list", "--repo", "pikasTech/unidesk", "--json", "number,body"], env); assertCondition(badListField.status !== 0, "issue list unsupported --json field should fail", badListField.json ?? { stdout: badListField.stdout }); const badListFieldData = failedDataOf(badListField.json ?? {}); @@ -518,6 +628,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "issue list default fields include labels and filter pull requests", "issue scan-escape classifies pollution, explanatory mentions, and body risks", "issue cleanup-plan remains dry-run with body/comment cleanup suggestions", + "issue board-audit reports missing open rows, closed/open section mismatches, missing closed rows, meta ignores, and row validation warnings without writes", "issue create dry-run parses repeated/comma labels and exposes request plan", "issue create sends labels through REST and preserves GitHub validation errors for missing labels", "issue list unsupported fields and states fail structurally", diff --git a/scripts/src/gh.ts b/scripts/src/gh.ts index 455878a5..45184bef 100644 --- a/scripts/src/gh.ts +++ b/scripts/src/gh.ts @@ -13,6 +13,8 @@ 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 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 ISSUE_VIEW_JSON_FIELDS = ["body", "title", "state", "comments", "number", "url", "author", "createdAt", "updatedAt"] as const; const ISSUE_LIST_JSON_FIELDS = ["number", "title", "state", "url", "updatedAt", "createdAt", "author", "labels"] as const; const PR_JSON_FIELDS = ["body", "title", "state", "number", "url", "author", "head", "base", "draft", "createdAt", "updatedAt"] as const; @@ -44,6 +46,8 @@ type EscapeFindingClassification = "suspected-pollution" | "explanatory-mention" type EscapeFindingSeverity = "low" | "medium" | "high"; type EscapeBodyKind = "issue-body" | "comment-body"; type CleanupSuggestionAction = "rewrite-issue-body-with-body-file" | "review-comment-manually" | "review-body-length" | "no-cleanup-needed"; +type BoardSectionKind = "open" | "closed"; +type BoardRequiredColumn = typeof BOARD_AUDIT_REQUIRED_COLUMNS[number]; type GitHubDegradedReason = | "missing-binary" @@ -175,6 +179,52 @@ interface EscapeScanErrorFinding { type EscapeScanEntry = EscapeMatchFinding | EscapeScanErrorFinding; +interface BoardTableRow { + section: BoardSectionKind; + lineNumber: number; + raw: string; + cells: string[]; + issueNumbers: number[]; + issueNumber: number | null; + title: string | null; + columns: Partial<Record<BoardRequiredColumn, string>>; +} + +interface BoardTableSection { + kind: BoardSectionKind; + heading: string; + headingLine: number; + headerLine: number; + headers: string[]; + rows: BoardTableRow[]; +} + +interface BoardIssueEntry { + number: number; + title: string; + state: string; + url: string; +} + +interface BoardIgnoredIssue { + number: number; + reason: "known-meta" | "ignored"; + title?: string; + state?: string; + url?: string; +} + +interface BoardRowValidationWarning { + issueNumber: number | null; + section: BoardSectionKind; + lineNumber: number; + kind: string; + message: string; + missingColumns?: BoardRequiredColumn[]; + columns?: Partial<Record<BoardRequiredColumn, string>>; + rowPreview: string; +} + interface GitHubCommandResult { ok: boolean; repo: string; @@ -197,6 +247,9 @@ interface GitHubOptions { repo: string; dryRun: boolean; limit: number; + boardIssue: number; + knownMetaIssues: number[]; + ignoredIssues: number[]; draft: boolean; notifyClaudeQqBriefDiff: boolean; allowShortBody: boolean; @@ -347,6 +400,31 @@ function labelsOption(args: string[]): string[] { return labels; } +function positiveIntegerValuesOption(args: string[], name: string): number[] { + const values: number[] = []; + const seen = new Set<number>(); + for (const raw of optionValues(args, name)) { + const parts = raw.split(",").map((value) => value.trim()).filter((value) => value.length > 0); + if (parts.length === 0) throw new Error(`${name} requires at least one positive integer`); + for (const part of parts) { + const value = Number(part.replace(/^#/u, "")); + if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} values must be positive issue numbers`); + if (seen.has(value)) continue; + values.push(value); + seen.add(value); + } + } + return values; +} + +function positiveIntegerSingleOption(args: string[], name: string, defaultValue: number): number { + const raw = optionValue(args, name); + if (raw === undefined) return defaultValue; + const value = Number(raw.replace(/^#/u, "")); + if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be a positive issue number`); + return value; +} + function positiveIntegerOption(args: string[], name: string, defaultValue: number, maxValue: number): number { const raw = optionValue(args, name); if (raw === undefined) return defaultValue; @@ -396,7 +474,7 @@ function parseIssueBodyProfile(args: string[]): IssueBodyProfileOption { } function validateKnownOptions(args: string[]): void { - const valueOptions = new Set(["--repo", "--limit", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label"]); + 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"]); const flagOptions = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body"]); for (let index = 0; index < args.length; index += 1) { const arg = args[index]; @@ -417,7 +495,10 @@ function parseOptions(args: string[]): GitHubOptions { return { repo: optionValue(args, "--repo") ?? DEFAULT_REPO, dryRun: hasFlag(args, "--dry-run"), - limit: positiveIntegerOption(args, "--limit", 30, 100), + limit: positiveIntegerOption(args, "--limit", top === "issue" && sub === "board-audit" ? 100 : 30, 100), + boardIssue: positiveIntegerSingleOption(args, "--board-issue", CODE_QUEUE_BOARD_TARGET_ISSUE), + knownMetaIssues: positiveIntegerValuesOption(args, "--known-meta-issue"), + ignoredIssues: positiveIntegerValuesOption(args, "--ignore-issue"), draft: hasFlag(args, "--draft"), notifyClaudeQqBriefDiff: hasFlag(args, "--notify-claudeqq-brief-diff"), allowShortBody: hasFlag(args, "--allow-short-body"), @@ -1100,6 +1181,227 @@ function issueListSummary(issue: GitHubIssue, fields: IssueListJsonField[]): Rec return selected; } +function boardIssueEntry(issue: GitHubIssue): BoardIssueEntry { + return { + number: issue.number, + title: issue.title, + state: issue.state, + url: issue.html_url, + }; +} + +function sortedIssueEntries(issues: BoardIssueEntry[]): BoardIssueEntry[] { + return issues.slice().sort((a, b) => a.number - b.number); +} + +function mergedKnownMetaIssues(options: GitHubOptions): number[] { + const seen = new Set<number>(); + const values: number[] = []; + for (const issueNumber of [...DEFAULT_BOARD_KNOWN_META_ISSUES, ...options.knownMetaIssues]) { + if (seen.has(issueNumber)) continue; + seen.add(issueNumber); + values.push(issueNumber); + } + return values; +} + +function boardIgnoreMap(options: GitHubOptions): Map<number, "known-meta" | "ignored"> { + const ignored = new Map<number, "known-meta" | "ignored">(); + for (const issueNumber of mergedKnownMetaIssues(options)) ignored.set(issueNumber, "known-meta"); + for (const issueNumber of options.ignoredIssues) ignored.set(issueNumber, "ignored"); + return ignored; +} + +function stripMarkdownInline(text: string): string { + return text + .replace(/\[[^\]]*]\(([^)]*)\)/g, "$1") + .replace(/<[^>]+>/g, "") + .replace(/[*_`~]/g, "") + .trim(); +} + +function normalizeBoardHeader(header: string): string { + return stripMarkdownInline(header).toLowerCase().replace(/\s+/g, ""); +} + +function boardHeaderColumnKind(header: string): BoardRequiredColumn | null { + const normalized = normalizeBoardHeader(header); + if (["branch", "分支", "目标分支", "工作分支"].includes(normalized)) return "branch"; + if (["acceptance", "验收", "验收状态", "验收结果", "验收标准"].includes(normalized)) return "acceptance"; + if (["relatedtask", "task", "codequeue", "codequeuetask", "相关任务", "任务", "codequeue任务", "cq任务"].includes(normalized)) return "relatedTask"; + if (["progress", "进度", "状态", "当前进度"].includes(normalized)) return "progress"; + return null; +} + +function markdownCells(line: string): string[] { + const trimmed = line.trim(); + const withoutOuterPipes = trimmed.replace(/^\|/u, "").replace(/\|$/u, ""); + return withoutOuterPipes.split("|").map((cell) => cell.trim()); +} + +function isMarkdownTableSeparator(line: string): boolean { + const cells = markdownCells(line); + return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/u.test(cell.trim())); +} + +function boardSectionKindFromHeading(line: string): BoardSectionKind | null { + const normalized = line.toLowerCase(); + if (!line.trimStart().startsWith("#")) return null; + if (normalized.includes("open") || normalized.includes("看板（open）") || normalized.includes("看板(open)") || normalized.includes("开放")) return "open"; + if (normalized.includes("closed") || normalized.includes("看板（closed）") || normalized.includes("看板(closed)") || normalized.includes("关闭") || normalized.includes("已关闭")) return "closed"; + return null; +} + +function extractIssueNumbers(text: string): number[] { + const numbers: number[] = []; + const seen = new Set<number>(); + const patterns = [/#(\d+)/g, /\/issues\/(\d+)/g]; + for (const pattern of patterns) { + pattern.lastIndex = 0; + let match = pattern.exec(text); + while (match !== null) { + const value = Number(match[1]); + if (Number.isInteger(value) && value > 0 && !seen.has(value)) { + seen.add(value); + numbers.push(value); + } + match = pattern.exec(text); + } + } + return numbers; +} + +function cellHasMeaningfulValue(value: string | undefined): boolean { + if (value === undefined) return false; + const stripped = stripMarkdownInline(value); + if (stripped.length === 0) return false; + return !["-", "—", "n/a", "na", "todo", "tbd", "待补", "未填", "无"].includes(stripped.toLowerCase()); +} + +function parseBoardTables(body: string): { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] } { + const lines = normalizeNewlines(body).split("\n"); + const sections: BoardTableSection[] = []; + const warnings: BoardRowValidationWarning[] = []; + let currentKind: BoardSectionKind | null = null; + let currentHeading = ""; + let currentHeadingLine = 0; + for (let index = 0; index < lines.length; index += 1) { + const headingKind = boardSectionKindFromHeading(lines[index]); + if (headingKind !== null) { + currentKind = headingKind; + currentHeading = lines[index].trim(); + currentHeadingLine = index + 1; + continue; + } + if (currentKind === null) continue; + if (!lines[index].trim().startsWith("|")) continue; + const separator = lines[index + 1]; + if (separator === undefined || !separator.trim().startsWith("|") || !isMarkdownTableSeparator(separator)) continue; + const headers = markdownCells(lines[index]); + const columnMap = new Map<BoardRequiredColumn, number>(); + headers.forEach((header, headerIndex) => { + const kind = boardHeaderColumnKind(header); + if (kind !== null && !columnMap.has(kind)) columnMap.set(kind, headerIndex); + }); + const rows: BoardTableRow[] = []; + let rowIndex = index + 2; + while (rowIndex < lines.length && lines[rowIndex].trim().startsWith("|")) { + if (!isMarkdownTableSeparator(lines[rowIndex])) { + const cells = markdownCells(lines[rowIndex]); + const issueNumbers = extractIssueNumbers(lines[rowIndex]); + const columns: Partial<Record<BoardRequiredColumn, string>> = {}; + for (const column of BOARD_AUDIT_REQUIRED_COLUMNS) { + const cellIndex = columnMap.get(column); + if (cellIndex !== undefined) columns[column] = cells[cellIndex] ?? ""; + } + const row: BoardTableRow = { + section: currentKind, + lineNumber: rowIndex + 1, + raw: lines[rowIndex], + cells, + issueNumbers, + issueNumber: issueNumbers[0] ?? null, + title: cells.find((cell) => extractIssueNumbers(cell).length > 0) ?? cells[0] ?? null, + columns, + }; + rows.push(row); + if (issueNumbers.length === 0) { + warnings.push({ + issueNumber: null, + section: currentKind, + lineNumber: row.lineNumber, + kind: "missing-issue-reference", + message: "Board table row does not contain a GitHub issue reference such as #36.", + rowPreview: preview(row.raw), + }); + } + if (issueNumbers.length > 1) { + warnings.push({ + issueNumber: row.issueNumber, + section: currentKind, + lineNumber: row.lineNumber, + kind: "multiple-issue-references", + message: "Board table row contains multiple issue references; audit uses the first number as the row key.", + rowPreview: preview(row.raw), + }); + } + const missingColumns = BOARD_AUDIT_REQUIRED_COLUMNS.filter((column) => !cellHasMeaningfulValue(columns[column])); + if (missingColumns.length > 0) { + warnings.push({ + issueNumber: row.issueNumber, + section: currentKind, + lineNumber: row.lineNumber, + kind: "missing-required-columns", + message: "Board table row is missing branch, acceptance, related task, or progress information.", + missingColumns, + columns, + rowPreview: preview(row.raw), + }); + } + } + rowIndex += 1; + } + sections.push({ + kind: currentKind, + heading: currentHeading, + headingLine: currentHeadingLine, + headerLine: index + 1, + headers, + rows, + }); + index = rowIndex - 1; + } + return { sections, warnings }; +} + +function boardRowsByIssue(rows: BoardTableRow[]): Map<number, BoardTableRow[]> { + const map = new Map<number, BoardTableRow[]>(); + for (const row of rows) { + if (row.issueNumber === null) continue; + const list = map.get(row.issueNumber); + if (list === undefined) map.set(row.issueNumber, [row]); + else list.push(row); + } + return map; +} + +function ignoredIssueList(issues: BoardIssueEntry[], ignoreMap: Map<number, "known-meta" | "ignored">): BoardIgnoredIssue[] { + return sortedIssueEntries(issues.filter((issue) => ignoreMap.has(issue.number))).map((issue) => ({ + number: issue.number, + reason: ignoreMap.get(issue.number) ?? "ignored", + title: issue.title, + state: issue.state, + url: issue.url, + })); +} + +function ignoredBoardOnlyIssues(issueNumbers: number[], issueMap: Map<number, BoardIssueEntry>, ignoreMap: Map<number, "known-meta" | "ignored">): BoardIgnoredIssue[] { + return issueNumbers + .filter((issueNumber) => ignoreMap.has(issueNumber) && !issueMap.has(issueNumber)) + .sort((a, b) => a - b) + .map((issueNumber) => ({ number: issueNumber, reason: ignoreMap.get(issueNumber) ?? "ignored" })); +} + function issueProfileFor(issueNumber: number, requested: IssueBodyProfileOption): IssueBodyProfileName | null { if (requested !== "auto") return requested; if (issueNumber === CODE_QUEUE_BOARD_TARGET_ISSUE) return "code-queue-board"; @@ -1652,6 +1954,172 @@ async function issueList(repo: string, token: string, state: IssueListState, lim }; } +async function issueBoardAudit(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> { + const commandName = "issue board-audit"; + const boardIssue = await getIssue(token, repo, options.boardIssue); + if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue }); + const [rawOpenIssues, rawClosedIssues] = await Promise.all([ + listIssues(token, repo, "open", options.limit), + listIssues(token, repo, "closed", options.limit), + ]); + if (isGitHubError(rawOpenIssues)) return commandError(commandName, repo, rawOpenIssues, { phase: "list-open-issues", boardIssue: options.boardIssue, limit: options.limit }); + if (isGitHubError(rawClosedIssues)) return commandError(commandName, repo, rawClosedIssues, { phase: "list-closed-issues", boardIssue: options.boardIssue, limit: options.limit }); + + const openIssues = rawOpenIssues.filter((issue) => issue.pull_request === undefined).slice(0, options.limit).map(boardIssueEntry); + const closedIssues = rawClosedIssues.filter((issue) => issue.pull_request === undefined).slice(0, options.limit).map(boardIssueEntry); + const allListedIssues = [...openIssues, ...closedIssues]; + const issueMap = new Map<number, BoardIssueEntry>(allListedIssues.map((issue) => [issue.number, issue])); + const ignoreMap = boardIgnoreMap(options); + const parsed = parseBoardTables(boardIssue.body ?? ""); + const rowValidationWarnings = parsed.warnings.filter((warning) => warning.issueNumber === null || !ignoreMap.has(warning.issueNumber)); + const openRows = parsed.sections.filter((section) => section.kind === "open").flatMap((section) => section.rows); + const closedRows = parsed.sections.filter((section) => section.kind === "closed").flatMap((section) => section.rows); + const openRowMap = boardRowsByIssue(openRows); + const closedRowMap = boardRowsByIssue(closedRows); + const openIssueNumbers = new Set(openIssues.map((issue) => issue.number)); + const closedIssueNumbers = new Set(closedIssues.map((issue) => issue.number)); + const boardIssueNumbers = Array.from(new Set([...openRowMap.keys(), ...closedRowMap.keys()])); + + const missingOpenIssues = sortedIssueEntries(openIssues.filter((issue) => !ignoreMap.has(issue.number) && !openRowMap.has(issue.number))); + const closedInOpenRows = sortedIssueEntries(closedIssues.filter((issue) => !ignoreMap.has(issue.number) && openRowMap.has(issue.number))).map((issue) => ({ + ...issue, + rows: (openRowMap.get(issue.number) ?? []).map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), + })); + const missingClosedRows = sortedIssueEntries(closedIssues.filter((issue) => !ignoreMap.has(issue.number) && !closedRowMap.has(issue.number))); + const openInClosedRows = sortedIssueEntries(openIssues.filter((issue) => !ignoreMap.has(issue.number) && closedRowMap.has(issue.number))).map((issue) => ({ + ...issue, + rows: (closedRowMap.get(issue.number) ?? []).map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), + })); + const staleOpenRows = Array.from(openRowMap.entries()) + .filter(([issueNumber]) => !ignoreMap.has(issueNumber) && !openIssueNumbers.has(issueNumber)) + .map(([issueNumber, rows]) => ({ + issueNumber, + knownState: closedIssueNumbers.has(issueNumber) ? "closed" : "not-in-listed-window", + rows: rows.map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), + })) + .sort((a, b) => a.issueNumber - b.issueNumber); + const boardOnlyRows = boardIssueNumbers + .filter((issueNumber) => !ignoreMap.has(issueNumber) && !issueMap.has(issueNumber)) + .sort((a, b) => a - b) + .map((issueNumber) => ({ + issueNumber, + sections: [ + ...(openRowMap.has(issueNumber) ? ["open"] : []), + ...(closedRowMap.has(issueNumber) ? ["closed"] : []), + ], + rows: [...(openRowMap.get(issueNumber) ?? []), ...(closedRowMap.get(issueNumber) ?? [])].map((row) => ({ + section: row.section, + lineNumber: row.lineNumber, + rowPreview: preview(row.raw), + })), + })); + const ignoredIssues = [ + ...ignoredIssueList(allListedIssues, ignoreMap), + ...ignoredBoardOnlyIssues(boardIssueNumbers, issueMap, ignoreMap), + ].sort((a, b) => a.number - b.number); + const recommendedActions = [ + ...missingOpenIssues.map((issue) => ({ + action: "add-open-row", + issueNumber: issue.number, + title: issue.title, + section: "open", + reason: "GitHub issue is open but no #20 OPEN table row was found.", + })), + ...closedInOpenRows.map((issue) => ({ + action: "move-open-row-to-closed", + issueNumber: issue.number, + title: issue.title, + reason: "GitHub issue is closed but still appears in the #20 OPEN table.", + })), + ...missingClosedRows.map((issue) => ({ + action: "add-closed-row", + issueNumber: issue.number, + title: issue.title, + section: "closed", + reason: "GitHub issue is closed but no #20 CLOSED table row was found.", + })), + ...openInClosedRows.map((issue) => ({ + action: "move-closed-row-to-open", + issueNumber: issue.number, + title: issue.title, + reason: "GitHub issue is open but appears in the #20 CLOSED table.", + })), + ...rowValidationWarnings.map((warning) => ({ + action: "fill-board-row-fields", + issueNumber: warning.issueNumber, + section: warning.section, + lineNumber: warning.lineNumber, + reason: warning.message, + missingColumns: warning.missingColumns ?? [], + })), + ]; + + return { + ok: true, + command: commandName, + repo, + dryRun: true, + planned: true, + readOnly: true, + boardIssue: { + number: boardIssue.number, + title: boardIssue.title, + state: boardIssue.state, + url: boardIssue.html_url, + bodyChars: (boardIssue.body ?? "").length, + updatedAt: boardIssue.updated_at ?? null, + }, + config: { + limit: options.limit, + knownMetaIssues: mergedKnownMetaIssues(options), + ignoredIssues: options.ignoredIssues, + requiredColumns: BOARD_AUDIT_REQUIRED_COLUMNS.slice(), + }, + summary: { + openIssues: openIssues.length, + closedIssues: closedIssues.length, + openRows: openRows.length, + closedRows: closedRows.length, + missingOpenIssues: missingOpenIssues.length, + closedInOpenRows: closedInOpenRows.length, + missingClosedRows: missingClosedRows.length, + openInClosedRows: openInClosedRows.length, + rowValidationWarnings: rowValidationWarnings.length, + ignoredIssues: ignoredIssues.length, + boardOnlyRows: boardOnlyRows.length, + staleOpenRows: staleOpenRows.length, + }, + sections: parsed.sections.map((section) => ({ + kind: section.kind, + heading: section.heading, + headingLine: section.headingLine, + headerLine: section.headerLine, + headers: section.headers, + rows: section.rows.length, + issueNumbers: section.rows.flatMap((row) => row.issueNumbers), + })), + missingOpenIssues, + closedInOpenRows, + missingClosedRows, + openInClosedRows, + staleOpenRows, + boardOnlyRows, + rowValidationWarnings, + ignoredIssues, + recommendedActions, + request: { + method: "GET", + paths: [ + `/repos/{owner}/{repo}/issues/${options.boardIssue}`, + "/repos/{owner}/{repo}/issues?state=open", + "/repos/{owner}/{repo}/issues?state=closed", + ], + query: { per_page: options.limit }, + }, + note: "Read-only board audit; no issue body was edited, no issue was closed, and no comments were written.", + }; +} + async function issueCreate(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> { if (options.title === undefined) throw new Error("issue create requires --title <title>"); const body = readBodyFile(options.bodyFile, "issue create"); @@ -2368,6 +2836,7 @@ export function ghHelp(): unknown { "bun scripts/cli.ts gh issue delete <number> [unsupported: use close]", "bun scripts/cli.ts gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]", "bun scripts/cli.ts gh issue cleanup-plan [--repo owner/name] [--limit N] [--dry-run]", + "bun scripts/cli.ts gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run]", "bun scripts/cli.ts gh pr list [--repo owner/name] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]", "bun scripts/cli.ts gh pr view <number> [--repo owner/name] [--json body,title,state,head,base,draft]", "bun scripts/cli.ts gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--repo owner/name] [--draft] [--dry-run]", @@ -2393,6 +2862,7 @@ export function ghHelp(): unknown { "When staging a body file from a shell, use a quoted heredoc such as cat <<'EOF' > /tmp/body.md so backticks and backslashes are not expanded before --body-file reads the file.", "For JSON request bodies in other CLI namespaces, prefer --body-file or --body-stdin over long inline shell arguments; GitHub Markdown writes intentionally use --body-file only.", "issue scan-escape classifies literal \\n findings as suspected-pollution, explanatory-mention, or risk, and emits cleanupSuggestions with body/comment ids plus diff-like previews. cleanup-plan is an alias that remains dry-run/read-only.", + "issue board-audit is read-only and defaults to repo pikasTech/unidesk plus board issue #20. It compares GitHub open/closed issue lists with the board OPEN/CLOSED tables and reports missingOpenIssues, closedInOpenRows, missingClosedRows, rowValidationWarnings, ignoredIssues, and recommendedActions. #20 and #24 are known meta issues by default.", "issue edit 24 --notify-claudeqq-brief-diff 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.", @@ -2437,6 +2907,10 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh"; return validationError(command, options.repo, "--allow-short-body, --expect-updated-at, --expect-body-sha, and --body-profile are only supported by gh issue update/edit"); } + if ((optionWasProvided(args, "--board-issue") || optionWasProvided(args, "--known-meta-issue") || optionWasProvided(args, "--ignore-issue")) && !(top === "issue" && sub === "board-audit")) { + const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh"; + return validationError(command, options.repo, "--board-issue, --known-meta-issue, and --ignore-issue are only supported by gh issue board-audit"); + } if (optionWasProvided(args, "--label") && !(top === "issue" && sub === "create")) { const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh"; return validationError(command, options.repo, "--label is only supported by gh issue create"); @@ -2471,6 +2945,12 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult if (missing !== null || token === null) return missing ?? authRequired(options.repo, commandName, { present: false, source: null, ghFallbackAttempted: true }); return issueScanEscape(options.repo, token, options.limit, options.dryRun || sub === "cleanup-plan", commandName); } + if (sub === "board-audit") { + const { token, probe } = resolveToken(true); + const missing = authRequired(options.repo, "issue board-audit", probe); + if (missing !== null || token === null) return missing ?? authRequired(options.repo, "issue board-audit", { present: false, source: null, ghFallbackAttempted: true }); + return issueBoardAudit(options.repo, token, options); + } if (options.dryRun) { if (sub === "create") return issueCreate(options.repo, "", options); if (sub === "edit") {