fix: add REST PR file summary CLI

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;
+    });
+}

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"));
   }

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);