From 0464aa01a8fa7dfc6c1ce183111bc59b1c0f14dc Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 13:39:17 +0000 Subject: [PATCH] docs: add code queue PR preflight template --- AGENTS.md | 2 +- docs/reference/cli.md | 1 + docs/reference/code-queue-supervision.md | 42 ++++ scripts/code-queue-pr-preflight-example.ts | 229 +++++++++++++++++++++ scripts/gh-cli-pr-contract-test.ts | 52 ++++- scripts/src/check.ts | 4 + 6 files changed, 323 insertions(+), 7 deletions(-) create mode 100644 scripts/code-queue-pr-preflight-example.ts diff --git a/AGENTS.md b/AGENTS.md index 712026aa..77fcc941 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`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描和 PR 创建/评论；`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 扫描、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 ]`：通过 backend-core 私有代理提交 Code Queue 任务；控制面默认走主 server `code-queue-mgr` 写入 PostgreSQL，`--dry-run` 可只检查请求体不入队，规则见 `docs/reference/cli.md`。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index d1c88691..8aaf9b01 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -35,6 +35,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI - `gh issue update --mode replace|append --body-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 ` 或 `--expect-body-sha `，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。 - `gh issue edit 24 --body-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 scan-escape [--repo owner/name] [--limit N]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape 和 ANSI escape 字符串，输出 issue/comment id、url、kind、snippet，不自动修复。`gh pr list|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --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`。 - `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`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`。 - `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/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 2c1f3cf4..d3c68905 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -80,6 +80,48 @@ PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。 PR 支持本身是 Code Queue 能力的一部分。当前 UniDesk CLI 支持 `gh pr list|view|create|update|comment create|comment delete|close|reopen`，其中 create 需要显式 `--title`、`--base`、`--head` 和正文来源，update 需要显式 PR number、正文来源和 `--mode replace|append`，comment create 需要显式 PR number 和正文来源，且推荐使用 `--body-file`。`pr create --dry-run`、`pr update --dry-run` 与 `pr comment create --dry-run` 只返回 planned operation，不创建 PR、不更新正文、不写评论；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，append 更新会先读取当前 PR body。`gh pr delete` 和 `gh pr merge` 仍是后续范围，本阶段没有 `--confirm` 可以启用真实 merge，也不能伪造硬删除；需要移除活跃 PR 时使用 `gh pr close`。普通 worker 不应隐式依赖未实现的 PR 合并能力；需要 PR 交付时，prompt 必须明确允许的人工或后续工具路径，并报告未覆盖范围。 +### PR 驱动派单模板 + +PR 驱动是 Code Queue 协作的未来默认方向：worker 在独立 head branch 上提交，创建面向目标分支的 PR，指挥官审查后再合并并更新 issue/#20/#24。当前仍处于 runner GitHub 可达性补齐阶段；在 #19 的 runner GitHub 可达性未验收前，派单 prompt 必须自包含完整需求、约束、写入范围和验收标准，不能只贴 GitHub issue 链接。issue URL 只能作为辅助引用。 + +PR 型派单 prompt 至少包含以下字段： + +- `目标 issue`：写明 issue 编号、URL 和本次任务要关闭或推进的验收点；不要假设 runner 能读取 issue。 +- `目标分支`：明确 `master` 或经批准的维护分支；普通开发集成使用 `master`。 +- `head branch`：使用可追踪命名，例如 `code-queue/issue-35-pr-dry-run-probe`、`code-queue/issue-<number>-<short-topic>` 或包含 task id 的等价短名；head branch 必须从最新 `origin/<目标分支>` 创建。 +- `禁止动作`：禁止直接 push 目标分支，禁止 merge PR，禁止改 release/v1 运行态服务，禁止输出 token，禁止跑本任务未要求的重型 check/e2e/Playwright。 +- `必须动作`：提交前运行轻量自测；push head branch；创建面向目标分支的 PR；PR body 写清关联 issue、修改文件、验证命令和风险；若创建 PR 前需要探测，先运行只读或 dry-run preflight。 +- `final response 字段`：实际分支、目标分支、head branch、PR URL、远端 head commit、是否已创建 PR、是否未 merge、修改文件、验证命令和结果、遗留风险；如果 PR 未能创建，报告结构化原因和 runnerDisposition。 + +PR 型 prompt 可直接嵌入以下 Git 指令约束： + +```text +Git/PR 交付要求： +- 目标分支：master。 +- 从最新 origin/master 创建 head branch：code-queue/issue-<number>-<short-topic>。 +- 不得直接 push master 或 release/v1。 +- 必须 push head branch 并创建 PR 到 master；不得 merge PR。 +- 创建 PR 前先运行只读/dry-run preflight，确认 GH_TOKEN/GITHUB_TOKEN、GitHub egress 和 repo 可见性，不得打印 token。 +- final response 必须报告 head branch、PR URL、远端 head commit、修改文件、验证命令、是否未 merge。 +``` + +Runner preflight 示例： + +```bash +bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head code-queue/issue-35-pr-dry-run-probe --comment-pr 1 +``` + +该脚本只读调用 `gh auth status`，并执行 `gh pr create --dry-run` 与 `gh pr comment --dry-run`。它检查 `GH_TOKEN/GITHUB_TOKEN` 是否存在、GitHub REST egress 是否可达、repo 是否可见，并且只输出 token 来源和存在性，不输出 token 值。`--comment-pr` 只是 dry-run 计划中的 PR number，不会写评论。 + +指挥官审查 checklist： + +- PR base 是声明的目标分支，head branch 命名可追踪，远端 head commit 可 fetch。 +- diff 只覆盖派单 ownership，未混入 release/v1 运行态服务或无关 dirty worktree。 +- PR body 和 final response 都包含关联 issue、修改文件、验证证据、未完成风险和未 merge 状态。 +- contract/dry-run 证据覆盖本次 PR 能力：`pr create --dry-run`、`pr list/view`、`pr comment --dry-run`，并确认 `gh pr merge` 返回结构化 unsupported。 +- 没有 token、凭证、临时日志或构建产物进入 commit、PR body 或评论。 +- 合并前由指挥官审查并决定是否 merge；合并后再验证目标分支远端 commit 可见，并按态势更新 issue/#20/#24。 + ## 监控 指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。 diff --git a/scripts/code-queue-pr-preflight-example.ts b/scripts/code-queue-pr-preflight-example.ts new file mode 100644 index 00000000..082fd324 --- /dev/null +++ b/scripts/code-queue-pr-preflight-example.ts @@ -0,0 +1,229 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +type JsonRecord = Record<string, unknown>; + +interface CliResult { + status: number | null; + ok: boolean; + json: JsonRecord | null; + stdoutBytes: number; + stderrBytes: number; + stdoutPreview?: string; + stderrPreview?: string; +} + +const DEFAULT_REPO = "pikasTech/unidesk"; +const DEFAULT_BASE = "master"; +const DEFAULT_HEAD = "code-queue/pr-preflight-example"; +const DEFAULT_COMMENT_PR = "1"; +const PREVIEW_CHARS = 400; + +function optionValue(args: string[], name: string, defaultValue: string): string { + const index = args.indexOf(name); + if (index === -1) return defaultValue; + const value = args[index + 1]; + if (value === undefined || value.length === 0 || value.startsWith("--")) throw new Error(`${name} requires a value`); + return value; +} + +function secrets(): string[] { + return [process.env.GH_TOKEN, process.env.GITHUB_TOKEN].filter((value): value is string => value !== undefined && value.length > 0); +} + +function redactText(text: string): string { + let redacted = text; + for (const secret of secrets()) { + redacted = redacted.split(secret).join("<redacted>"); + } + return redacted; +} + +function redactUnknown(value: unknown): unknown { + if (typeof value === "string") return redactText(value); + if (Array.isArray(value)) return value.map(redactUnknown); + if (typeof value === "object" && value !== null) { + const entries = Object.entries(value).map(([key, entry]) => [key, redactUnknown(entry)]); + return Object.fromEntries(entries); + } + return value; +} + +function preview(text: string): string { + return redactText(text.length > PREVIEW_CHARS ? `${text.slice(0, PREVIEW_CHARS)}...` : text); +} + +function runCli(args: string[]): CliResult { + const result = spawnSync("bun", ["scripts/cli.ts", ...args], { + cwd: process.cwd(), + env: process.env, + encoding: "utf8", + timeout: 30_000, + }); + const stdout = result.stdout ?? ""; + const stderr = result.stderr ?? ""; + let json: JsonRecord | null = null; + try { + json = redactUnknown(JSON.parse(stdout) as unknown) as JsonRecord; + } catch { + json = null; + } + return { + status: result.status, + ok: result.status === 0 && json?.ok === true, + json, + stdoutBytes: Buffer.byteLength(stdout), + stderrBytes: Buffer.byteLength(stderr), + ...(json === null && stdout.length > 0 ? { stdoutPreview: preview(stdout) } : {}), + ...(stderr.length > 0 ? { stderrPreview: preview(stderr) } : {}), + }; +} + +function dataOf(result: CliResult): JsonRecord | null { + const data = result.json?.data; + return typeof data === "object" && data !== null && !Array.isArray(data) ? data as JsonRecord : null; +} + +function envTokenProbe(): JsonRecord { + if (process.env.GH_TOKEN && process.env.GH_TOKEN.length > 0) return { ok: true, present: true, source: "GH_TOKEN" }; + if (process.env.GITHUB_TOKEN && process.env.GITHUB_TOKEN.length > 0) return { ok: true, present: true, source: "GITHUB_TOKEN" }; + return { + ok: false, + present: false, + source: null, + message: "Runner PR workflow requires GH_TOKEN or GITHUB_TOKEN in the environment; token values must never be printed.", + }; +} + +function dryRunSummary(result: CliResult): JsonRecord { + const data = dataOf(result); + return { + ok: result.ok, + status: result.status, + stdoutBytes: result.stdoutBytes, + stderrBytes: result.stderrBytes, + ...(data === null ? {} : { + command: data.command, + dryRun: data.dryRun, + planned: data.planned, + repo: data.repo, + base: data.base, + head: data.head, + issueNumber: data.issueNumber, + bodyChars: data.bodyChars, + request: data.request, + }), + ...(result.stdoutPreview === undefined ? {} : { stdoutPreview: result.stdoutPreview }), + ...(result.stderrPreview === undefined ? {} : { stderrPreview: result.stderrPreview }), + }; +} + +function main(): void { + const args = process.argv.slice(2); + if (args.includes("--help") || args.includes("-h")) { + process.stdout.write(`${JSON.stringify({ + ok: true, + command: "code-queue-pr-preflight-example", + usage: "bun scripts/code-queue-pr-preflight-example.ts [--repo owner/name] [--base branch] [--head branch] [--comment-pr number]", + note: "Read-only/dry-run runner preflight. It checks GH_TOKEN/GITHUB_TOKEN presence, GitHub REST egress and repo visibility through gh auth status, then exercises PR create/comment dry-run paths without creating or merging a PR.", + }, null, 2)}\n`); + return; + } + + const repo = optionValue(args, "--repo", DEFAULT_REPO); + const base = optionValue(args, "--base", DEFAULT_BASE); + const head = optionValue(args, "--head", process.env.CODE_QUEUE_HEAD_BRANCH ?? DEFAULT_HEAD); + const commentPr = optionValue(args, "--comment-pr", DEFAULT_COMMENT_PR); + const tmp = mkdtempSync(join(tmpdir(), "unidesk-pr-preflight-")); + const bodyFile = join(tmp, "body.md"); + writeFileSync(bodyFile, [ + "# Code Queue PR preflight", + "", + "This file is used only for local dry-run planning.", + "", + ].join("\n"), "utf8"); + + try { + const token = envTokenProbe(); + const auth = runCli(["gh", "auth", "status", "--repo", repo]); + const createDryRun = runCli([ + "gh", + "pr", + "create", + "--repo", + repo, + "--title", + "Code Queue PR preflight dry run", + "--body-file", + bodyFile, + "--base", + base, + "--head", + head, + "--dry-run", + ]); + const commentDryRun = runCli([ + "gh", + "pr", + "comment", + commentPr, + "--repo", + repo, + "--body-file", + bodyFile, + "--dry-run", + ]); + const authData = dataOf(auth); + const ok = token.ok === true && auth.ok && createDryRun.ok && commentDryRun.ok; + process.stdout.write(`${JSON.stringify({ + ok, + command: "code-queue-pr-preflight-example", + repo, + base, + head, + commentPr, + checks: { + envToken: token, + githubAuthStatus: { + ok: auth.ok, + status: auth.status, + stdoutBytes: auth.stdoutBytes, + stderrBytes: auth.stderrBytes, + ...(authData === null ? {} : { + degraded: authData.degraded, + token: authData.token, + probes: authData.probes, + restFallback: authData.restFallback, + }), + ...(auth.stdoutPreview === undefined ? {} : { stdoutPreview: auth.stdoutPreview }), + ...(auth.stderrPreview === undefined ? {} : { stderrPreview: auth.stderrPreview }), + }, + prCreateDryRun: dryRunSummary(createDryRun), + prCommentDryRun: dryRunSummary(commentDryRun), + }, + safety: { + writesRemote: false, + createsPullRequest: false, + commentsPullRequest: false, + mergesPullRequest: false, + tokenValuesPrinted: false, + }, + }, null, 2)}\n`); + if (!ok) process.exitCode = 1; + } finally { + rmSync(tmp, { recursive: true, force: true }); + } +} + +try { + main(); +} catch (error) { + process.stdout.write(`${JSON.stringify({ + ok: false, + command: "code-queue-pr-preflight-example", + error: redactText(error instanceof Error ? error.message : String(error)), + }, null, 2)}\n`); + process.exitCode = 1; +} diff --git a/scripts/gh-cli-pr-contract-test.ts b/scripts/gh-cli-pr-contract-test.ts index e30c6097..986cf252 100644 --- a/scripts/gh-cli-pr-contract-test.ts +++ b/scripts/gh-cli-pr-contract-test.ts @@ -7,16 +7,16 @@ import { tmpdir } from "node:os"; type JsonRecord = Record<string, unknown>; -function assertCondition(condition: unknown, message: string, detail: JsonRecord = {}): void { +function assertCondition(condition: unknown, message: string, detail: unknown = {}): void { if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`); } -function runCli(args: string[], env: Record<string, string> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: JsonRecord | null }> { +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", ["scripts/cli.ts", ...args], { - cwd: process.cwd(), - env: { ...process.env, ...env }, - }); + 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))); @@ -40,6 +40,10 @@ function runCli(args: string[], env: Record<string, string> = {}): Promise<{ sta }); } +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); +} + interface MockRequest { method: string; url: string; @@ -79,10 +83,18 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque const server = createServer(async (req, res) => { const body = await collectBody(req); requests.push({ method: req.method ?? "", url: req.url ?? "", body }); + if (req.method === "GET" && req.url === "/rate_limit") { + sendJson(res, 200, { resources: { core: { limit: 5000, remaining: 4999 } } }); + return; + } if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk") { sendJson(res, 200, { id: 1, full_name: "pikasTech/unidesk", private: true, default_branch: "master", permissions: { pull: true, push: true } }); return; } + if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues?per_page=1&state=all") { + sendJson(res, 200, []); + return; + } if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/pulls?state=all&per_page=4") { sendJson(res, 200, [pullRequest]); return; @@ -154,6 +166,34 @@ export async function runGhCliPrContract(): Promise<JsonRecord> { assertCondition(pullRequest.number === 42 && pullRequest.url === "https://github.com/pikasTech/unidesk/pull/42", "pr view should expose PR details", viewData); const selected = viewData.json as JsonRecord; assertCondition(selected.body === "PR body" && selected.title === "contract PR", "pr view --json should select fields", viewData); + + const preflight = await runBun([ + "scripts/code-queue-pr-preflight-example.ts", + "--repo", + "pikasTech/unidesk", + "--base", + "master", + "--head", + "feature/pr-contract", + "--comment-pr", + "42", + ], env); + assertCondition(preflight.status === 0, "PR preflight example should succeed against mock GitHub", preflight.json ?? { stdout: preflight.stdout }); + assertCondition(preflight.json?.ok === true, "PR preflight example should report ok=true", preflight.json ?? {}); + assertCondition(!preflight.stdout.includes("contract-token"), "PR preflight example must not print token values", { stdout: preflight.stdout }); + assertCondition(typeof preflight.json?.checks === "object" && preflight.json.checks !== null && !Array.isArray(preflight.json.checks), "PR preflight should expose checks", preflight.json ?? {}); + const preflightChecks = preflight.json?.checks as JsonRecord; + const envToken = preflightChecks.envToken as JsonRecord; + assertCondition(envToken.present === true && envToken.source === "GH_TOKEN", "PR preflight should require env token source", envToken); + const authStatus = preflightChecks.githubAuthStatus as JsonRecord; + assertCondition(authStatus.ok === true, "PR preflight should prove GitHub REST egress and repo visibility", authStatus); + const preflightCreate = preflightChecks.prCreateDryRun as JsonRecord; + const preflightComment = preflightChecks.prCommentDryRun as JsonRecord; + assertCondition(preflightCreate.ok === true && preflightCreate.dryRun === true && preflightCreate.planned === true, "PR preflight create must stay dry-run", preflightCreate); + assertCondition(preflightComment.ok === true && preflightComment.dryRun === true && preflightComment.planned === true, "PR preflight comment must stay dry-run", preflightComment); + assertCondition(mock.requests.some((request) => request.method === "GET" && request.url === "/rate_limit"), "PR preflight should probe REST egress", mock.requests); + assertCondition(mock.requests.some((request) => request.method === "GET" && request.url === "/repos/pikasTech/unidesk"), "PR preflight should probe repo visibility", mock.requests); + assertCondition(mock.requests.every((request) => request.method === "GET"), "initial mock phase should remain read-only", mock.requests); } finally { await mock.close(); } diff --git a/scripts/src/check.ts b/scripts/src/check.ts index 122c4001..4835be32 100644 --- a/scripts/src/check.ts +++ b/scripts/src/check.ts @@ -284,6 +284,8 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default fileItem("scripts/src/ci.ts"), fileItem("scripts/src/e2e.ts"), fileItem("scripts/code-queue-prompt-observation-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"), fileItem("scripts/src/artifact-registry.ts"), fileItem("src/components/microservices/k3sctl-adapter/k3s/ci/unidesk-ci.pipeline.yaml"), @@ -303,6 +305,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(commandItem("code-queue:oa-publisher-degraded-visible", ["bun", "scripts/code-queue-liveness-diagnostics-test.ts", "--only", "code-queue:oa-publisher-degraded-visible"], 30_000)); items.push(commandItem("baidu-netdisk:artifact-guard-contract", ["bun", "scripts/baidu-netdisk-artifact-guard-contract-test.ts"], 30_000)); items.push(commandItem("schedule:cli-contract", ["bun", "scripts/schedule-cli-contract-test.ts"], 30_000)); + items.push(commandItem("gh:pr-contract", ["bun", "scripts/gh-cli-pr-contract-test.ts"], 30_000)); } else { items.push(skippedItem("typescript:scripts", "scripts TypeScript typecheck is opt-in", "--scripts-typecheck or --full")); items.push(skippedItem("code-queue:prompt-observation-contract", "prompt observation contract is opt-in with script checks", "--scripts-typecheck or --full")); @@ -311,6 +314,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(skippedItem("code-queue:liveness-diagnostics-fixtures", "Code Queue liveness diagnostics fixtures are opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("baidu-netdisk:artifact-guard-contract", "Baidu Netdisk artifact guard contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("schedule:cli-contract", "Schedule CLI 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")); } if (options.logs) { items.push(unifiedLogRotationItem());