@payconductor/houndsman 0.6.0 → 0.7.0

package/src/server/client/utils/types.ts

@@ -97,6 +97,86 @@ export type FindingsResponse = {
 	summary: Summary;
 };
 
+/** Editor detectado pelo servidor (base dos links de código). */
+export type EditorKind = "vscode" | "jetbrains" | "none";
+
+export type EditorContext = {
+	kind: EditorKind;
+	project?: string;
+	product?: string;
+};
+
+/** Estado da árvore de trabalho (bloqueia o checkout quando suja). */
+export type WorktreeState = {
+	available: boolean;
+	clean: boolean;
+	changes: number;
+	sample: string[];
+};
+
+/** PR aberta exibida na sidebar. */
+export type PrListItem = {
+	number: number;
+	title: string;
+	headRefName: string;
+	baseRefName: string;
+	author: string;
+	updatedAt?: string;
+	isDraft: boolean;
+	reviewDecision?: string;
+	url?: string;
+	runSlug?: string;
+};
+
+export type PrListResponse = {
+	available: boolean;
+	reason?: string;
+	currentBranch: string | null;
+	worktree: WorktreeState;
+	prs: PrListItem[];
+};
+
+export type CheckoutResponse =
+	| { ok: true; number: number; branch: string | null }
+	| {
+			ok: false;
+			reason: "dirty" | "git" | "gh";
+			detail: string;
+			changes?: string[];
+	  };
+
+/** Comentário normalizado da PR (thread ou geral). */
+export type PrCommentView = {
+	id: number;
+	author: string;
+	authorType: string;
+	body: string;
+	createdAt?: string;
+	url?: string;
+	path?: string;
+	line: number | null;
+	absFile?: string;
+	replyTo?: number | null;
+};
+
+export type PrCommentThread = {
+	id: number;
+	path: string;
+	line: number | null;
+	absFile: string;
+	comments: PrCommentView[];
+};
+
+export type PrCommentsResponse = {
+	available: boolean;
+	reason?: string;
+	target?: { number: number; repo: string; url?: string };
+	fetchedAt: string;
+	threads: PrCommentThread[];
+	issueComments: PrCommentView[];
+	counts: { threads: number; inline: number; issue: number };
+};
+
 /** Manifesto da run (subset consumido pela aba de resumo). */
 export type RunManifest = {
 	branch?: string;
@@ -149,6 +229,8 @@ export type SubmitCandidate = {
 	file: string;
 	line: number | null;
 	severity: Severity;
+	/** Decisão da triagem (`execute` = "a executar"). */
+	decision: Decision;
 	execState: ExecState;
 	rule: string;
 	message: string;

package/src/server/editor.ts

@@ -0,0 +1,129 @@
+/**
+ * Detecção do editor que hospeda o terminal do servidor (biblioteca do servidor).
+ *
+ * VS Code e JetBrains expõem variáveis próprias no terminal integrado. O
+ * contexto alimenta os links de código da UI (`vscode://` / `jetbrains://`).
+ * A detecção é pura e fail-open: sem pistas, o editor fica `none`.
+ */
+
+import { basename, resolve } from "node:path";
+
+/** Editores com esquema de URL próprio. */
+export type EditorKind = "vscode" | "jetbrains" | "none";
+
+/** Contexto usado pelo cliente para montar os links de código. */
+export type EditorContext = {
+	kind: EditorKind;
+	/** Nome do projeto aberto no IDE (basename da raiz do repositório). */
+	project?: string;
+	/** Código do produto JetBrains (`idea`, `webstorm`, `pycharm`…). */
+	product?: string;
+};
+
+type Env = Record<string, string | undefined>;
+
+/** Bundle macOS → código do produto usado no esquema `jetbrains://`. */
+const BUNDLE_PRODUCTS: Record<string, string> = {
+	"com.jetbrains.intellij": "idea",
+	"com.jetbrains.intellij.ce": "idea",
+	"com.jetbrains.pycharm": "pycharm",
+	"com.jetbrains.pycharm.ce": "pycharm",
+	"com.jetbrains.webstorm": "webstorm",
+	"com.jetbrains.goland": "goland",
+	"com.jetbrains.clion": "clion",
+	"com.jetbrains.rider": "rider",
+	"com.jetbrains.phpstorm": "phpstorm",
+	"com.jetbrains.rubymine": "rubymine",
+	"com.jetbrains.datagrip": "datagrip",
+	"com.jetbrains.appcode": "appcode",
+	"com.jetbrains.rustrover": "rustrover",
+};
+
+/** Variáveis `*_INITIAL_DIRECTORY` → produto JetBrains. */
+const DIR_PRODUCTS: [string, string][] = [
+	["IDEA_INITIAL_DIRECTORY", "idea"],
+	["PYCHARM_INITIAL_DIRECTORY", "pycharm"],
+	["WEBSTORM_INITIAL_DIRECTORY", "webstorm"],
+	["GOLAND_INITIAL_DIRECTORY", "goland"],
+	["CLION_INITIAL_DIRECTORY", "clion"],
+	["RIDER_INITIAL_DIRECTORY", "rider"],
+	["PHPSTORM_INITIAL_DIRECTORY", "phpstorm"],
+	["RUBYMINE_INITIAL_DIRECTORY", "rubymine"],
+	["DATAGRIP_INITIAL_DIRECTORY", "datagrip"],
+	["RUSTROVER_INITIAL_DIRECTORY", "rustrover"],
+];
+
+function projectName(repoRoot: string): string {
+	return basename(resolve(repoRoot));
+}
+
+/** Produto JetBrains detectado no ambiente (undefined quando ambíguo). */
+export function detectJetBrainsProduct(env: Env): string | undefined {
+	const bundle = env.__CFBundleIdentifier?.toLowerCase();
+	if (bundle) {
+		const exact = BUNDLE_PRODUCTS[bundle];
+		if (exact) return exact;
+		const prefix = Object.keys(BUNDLE_PRODUCTS).find((key) => bundle.startsWith(key));
+		if (prefix) return BUNDLE_PRODUCTS[prefix];
+	}
+	for (const [name, product] of DIR_PRODUCTS) {
+		if (env[name]) return product;
+	}
+	return undefined;
+}
+
+function isJetBrains(env: Env): boolean {
+	const bundle = env.__CFBundleIdentifier?.toLowerCase() ?? "";
+	return (
+		/jetbrains/i.test(env.TERMINAL_EMULATOR ?? "") ||
+		bundle.startsWith("com.jetbrains.") ||
+		DIR_PRODUCTS.some(([name]) => Boolean(env[name]))
+	);
+}
+
+function isVsCode(env: Env): boolean {
+	return (
+		env.TERM_PROGRAM === "vscode" ||
+		env.TERM_PROGRAM === "vscode-insiders" ||
+		Boolean(env.VSCODE_PID || env.VSCODE_IPC_HOOK_CLI || env.VSCODE_GIT_IPC_HANDLE)
+	);
+}
+
+/** Detecta o editor a partir do ambiente do terminal integrado. */
+export function detectEditor(env: Env, repoRoot: string): EditorContext {
+	const project = projectName(repoRoot);
+	if (isJetBrains(env)) {
+		return {
+			kind: "jetbrains",
+			project,
+			product: detectJetBrainsProduct(env) ?? "idea",
+		};
+	}
+	if (isVsCode(env)) return { kind: "vscode", project };
+	return { kind: "none", project };
+}
+
+/**
+ * Resolve a preferência do `--editor`.
+ *
+ * `auto` (ou ausente) detecta do ambiente; `vscode`/`jetbrains`/`none` forçam
+ * o comportamento. Valores desconhecidos caem na detecção automática.
+ */
+export function resolveEditor(
+	preference: string | undefined,
+	env: Env,
+	repoRoot: string,
+): EditorContext {
+	const value = preference?.trim().toLowerCase();
+	const project = projectName(repoRoot);
+	if (value === "vscode") return { kind: "vscode", project };
+	if (value === "jetbrains") {
+		return {
+			kind: "jetbrains",
+			project,
+			product: detectJetBrainsProduct(env) ?? "idea",
+		};
+	}
+	if (value === "none") return { kind: "none", project };
+	return detectEditor(env, repoRoot);
+}

package/src/server/index.ts

@@ -9,16 +9,20 @@
 import { mediaPath } from "../core/assets";
 import type { HoundsmanConfig } from "../core/config";
 import type { FindingUpdate } from "../core/findings-state";
+import { createGitRunner, type GitRunner } from "../core/git-runner";
 import {
 	defaultGhRunner,
 	type GhRunner,
 	type SubmitSelection,
 } from "../core/github-review";
 import { logger } from "../core/logging";
+import { GitRepository } from "../core/services/git-repository";
 import { createStorage } from "../core/storage/factory";
 import { resolveRepoIdentity } from "../core/storage/repo-identity";
 import type { RepoIdentity, StorageProvider } from "../core/storage/types";
 import { buildClientBundle } from "./client-build";
+import { type EditorContext, resolveEditor } from "./editor";
+import { PrInbox } from "./pr-inbox";
 import { RunRepository } from "./run-repository";
 
 type BunServer = ReturnType<typeof Bun.serve>;
@@ -59,8 +63,13 @@ function notFound(detail = "não encontrado"): Response {
 /** Repositório das runs (dados) — ver `run-repository.ts`. */
 type ServerDeps = {
 	ghRunner?: GhRunner;
+	gitRunner?: GitRunner;
 	storage?: StorageProvider;
 	repo?: RepoIdentity;
+	/** Contexto do editor injetado (testes). */
+	editor?: EditorContext;
+	/** Preferência do `--editor` (CLI). */
+	editorPreference?: string;
 };
 
 // ---------------------------------------------------------------------------
@@ -83,6 +92,8 @@ async function route(
 	request: Request,
 	runs: RunRepository,
 	ghRunner: GhRunner,
+	prs: PrInbox,
+	editor: EditorContext,
 ): Promise<Response> {
 	const url = new URL(request.url);
 	const path = url.pathname;
@@ -95,6 +106,21 @@ async function route(
 	}
 	if (path === `/assets/${LOGO_FILE}`) return serveLogo();
 	if (path === "/api/health") return json({ ok: true });
+	if (path === "/api/editor" && request.method === "GET") return json(editor);
+	if (path === "/api/prs" && request.method === "GET") {
+		return json(prs.list(runs.branchIndex()));
+	}
+	if (path === "/api/prs/checkout" && request.method === "POST") {
+		const body = (await request.json().catch(() => ({}))) as { number?: unknown };
+		const number = Number(body.number);
+		if (!Number.isInteger(number) || number <= 0) {
+			return json(
+				{ ok: false, reason: "invalid", detail: "Número de PR inválido." },
+				400,
+			);
+		}
+		return json(prs.checkout(number));
+	}
 
 	if (path === "/api/runs" && request.method === "GET") {
 		return json({ runs: runs.list() });
@@ -108,6 +134,11 @@ async function route(
 
 	if (rest === "" || rest === "/") return json(runs.detail(slug));
 
+	if (rest === "/comments" && request.method === "GET") {
+		return json(
+			runs.comments(slug, { refresh: url.searchParams.get("refresh") === "1" }),
+		);
+	}
 	if (rest === "/findings" && request.method === "GET") {
 		return json(runs.findings(slug, url.searchParams));
 	}
@@ -119,6 +150,7 @@ async function route(
 		const body = (await request.json().catch(() => ({}))) as SubmitSelection;
 		const selection: SubmitSelection = {
 			severities: body.severities,
+			decisions: body.decisions,
 			execStates: body.execStates,
 			includeSent: body.includeSent,
 		};
@@ -161,19 +193,27 @@ async function route(
 export class HoundsmanServer {
 	private readonly runs: RunRepository;
 	private readonly ghRunner: GhRunner;
+	private readonly prs: PrInbox;
+	private readonly editor: EditorContext;
 
 	constructor(config: HoundsmanConfig, deps: ServerDeps = {}) {
+		const repo = deps.repo ?? resolveRepoIdentity();
+		this.ghRunner = deps.ghRunner ?? defaultGhRunner;
 		this.runs = new RunRepository(
 			deps.storage ?? createStorage(config),
-			deps.repo ?? resolveRepoIdentity(),
+			repo,
+			this.ghRunner,
 		);
-		this.ghRunner = deps.ghRunner ?? defaultGhRunner;
+		this.editor =
+			deps.editor ?? resolveEditor(deps.editorPreference, process.env, repo.root);
+		const git = new GitRepository(deps.gitRunner ?? createGitRunner(repo.root));
+		this.prs = new PrInbox(this.ghRunner, git);
 	}
 
 	/** Handler de requisições (testável sem abrir porta). */
 	readonly handler = async (request: Request): Promise<Response> => {
 		try {
-			return await route(request, this.runs, this.ghRunner);
+			return await route(request, this.runs, this.ghRunner, this.prs, this.editor);
 		} catch (error) {
 			return json(
 				{ error: error instanceof Error ? error.message : String(error) },
@@ -223,17 +263,26 @@ export type ServerOptions = {
 	host?: string;
 	/** Runner do `gh` (injetável nos testes). */
 	ghRunner?: GhRunner;
+	/** Runner do git (injetável nos testes). */
+	gitRunner?: GitRunner;
 	/** Provider/storage injetável (testes). */
 	storage?: StorageProvider;
 	repo?: RepoIdentity;
+	/** Contexto de editor injetado (testes). */
+	editor?: EditorContext;
+	/** Preferência do `--editor` (auto|vscode|jetbrains|none). */
+	editorPreference?: string;
 };
 
 /** Sobe o servidor e devolve a instância + URL. */
 export function startServer(options: ServerOptions): { server: BunServer; url: string } {
 	return new HoundsmanServer(options.config, {
 		ghRunner: options.ghRunner,
+		gitRunner: options.gitRunner,
 		storage: options.storage,
 		repo: options.repo,
+		editor: options.editor,
+		editorPreference: options.editorPreference,
 	}).start({
 		port: options.port,
 		host: options.host,
@@ -295,6 +344,66 @@ code, pre, .mono { font-family:var(--font-mono); tab-size:4; }
 .status-review_done { color:var(--suggestion); }
 .status-fix_done { color:var(--success); }
 .status-timeout { color:var(--blocking); }
+.side-tabs { display:flex; gap:4px; padding:4px; background:var(--surface-2); border:1px solid var(--border); border-radius:999px; }
+.side-tab { flex:1; display:inline-flex; align-items:center; justify-content:center; gap:7px; font:inherit; font-size:12px; font-weight:600; cursor:pointer; color:var(--muted);
+  padding:7px 10px; background:transparent; border:1px solid transparent; border-radius:999px; transition:color .15s ease, background .15s ease; }
+.side-tab:hover { color:var(--fg); }
+.side-tab.active { color:#1b1305; background:linear-gradient(180deg, var(--accent-strong), var(--accent)); }
+.side-count { padding:1px 6px; font-family:var(--font-mono); font-size:10px; color:var(--muted); background:rgba(255,255,255,.08); border-radius:999px; }
+.side-tab.active .side-count { color:#1b1305; background:rgba(0,0,0,.14); }
+.icon-btn { display:inline-grid; place-items:center; width:26px; height:26px; color:var(--muted); background:transparent; border:1px solid var(--border); border-radius:8px; cursor:pointer; text-decoration:none; }
+.icon-btn:hover { color:var(--fg); border-color:var(--border-strong); }
+.icon-btn:disabled { opacity:.5; cursor:not-allowed; }
+.pr-toolbar { display:flex; align-items:center; justify-content:space-between; gap:8px; }
+.pr-toolbar .section-label { margin:0; }
+.prs { display:flex; flex-direction:column; gap:8px; }
+.pr { display:flex; flex-direction:column; gap:7px; padding:11px 12px; background:var(--card); border:1px solid var(--border); border-radius:var(--radius); }
+.pr.current { background:var(--accent-soft); border-color:var(--accent-line); }
+.pr-head { display:flex; align-items:center; gap:7px; font-family:var(--font-mono); font-size:11px; color:var(--muted); }
+.pr-icon { color:var(--muted-2); }
+.pr.current .pr-icon { color:var(--accent); }
+.pr-number { font-weight:600; color:var(--fg); }
+.pr-current { padding:1px 6px; font-size:9px; font-weight:700; letter-spacing:.08em; text-transform:uppercase; color:var(--accent); background:rgba(240,165,44,.12); border-radius:999px; }
+.pr-title { margin:0; font-size:12.5px; font-weight:600; line-height:1.4; word-break:break-word; }
+.pr-meta { display:flex; flex-wrap:wrap; align-items:center; gap:1px 5px; margin:0; font-family:var(--font-mono); font-size:10.5px; color:var(--muted-2); }
+.pr-branch { color:var(--suggestion); }
+.pr-review { margin:0; font-size:10.5px; font-weight:600; }
+.pr-review-APPROVED { color:var(--success); }
+.pr-review-CHANGES_REQUESTED { color:var(--blocking); }
+.pr-review-REVIEW_REQUIRED { color:var(--attention); }
+.pr-actions { display:flex; flex-wrap:wrap; gap:6px; margin-top:2px; }
+.pr-btn { display:inline-flex; align-items:center; gap:5px; font:inherit; font-size:10.5px; font-weight:600; cursor:pointer; padding:4px 9px; color:var(--muted);
+  background:transparent; border:1px solid var(--border-strong); border-radius:999px; text-decoration:none; }
+.pr-btn:hover { color:var(--fg); border-color:var(--accent-line); }
+.pr-btn:disabled { opacity:.45; cursor:not-allowed; }
+.pr-btn.danger { color:var(--accent); background:var(--accent-soft); border-color:var(--accent-line); }
+.pr-warning { margin:0; padding:8px 10px; font-size:11px; line-height:1.5; color:var(--attention);
+  background:rgba(237,161,58,.08); border:1px solid rgba(237,161,58,.24); border-radius:10px; }
+.pr-notice { margin:0; padding:8px 10px; font-size:11px; line-height:1.5; color:var(--success);
+  background:rgba(69,192,122,.08); border:1px solid rgba(69,192,122,.24); border-radius:10px; }
+.pr-current-branch { margin:0; font-family:var(--font-mono); font-size:10.5px; color:var(--muted-2); }
+.pr-current-branch code { color:var(--fg); }
+.comments { display:flex; flex-direction:column; gap:18px; }
+.comments-toolbar { display:flex; align-items:center; justify-content:space-between; gap:12px; }
+.comments-counts { display:flex; flex-wrap:wrap; align-items:center; gap:12px; font-size:11.5px; color:var(--muted); }
+.comments-counts b { font-family:var(--font-mono); font-weight:600; color:var(--fg); }
+.comment-group { display:flex; flex-direction:column; gap:10px; }
+.comment-group-title { margin:0; font-size:11px; font-weight:700; letter-spacing:.16em; text-transform:uppercase; color:var(--muted-2); }
+.comment-file-group { display:flex; flex-direction:column; gap:8px; }
+.comment-group-label { display:flex; align-items:center; gap:8px; margin:0; font-family:var(--font-mono); font-size:11.5px; color:var(--suggestion); }
+.comment-thread { display:flex; flex-direction:column; overflow:hidden; background:var(--card); border:1px solid var(--border); border-radius:var(--radius-lg); }
+.comment-thread-head { display:flex; align-items:center; gap:8px; padding:9px 13px; font-family:var(--font-mono); font-size:11px; color:var(--muted);
+  background:var(--surface-2); border-bottom:1px solid var(--border); }
+.comment-file { overflow:hidden; color:var(--fg); text-overflow:ellipsis; white-space:nowrap; }
+.pr-comment { display:flex; flex-direction:column; gap:7px; padding:12px 14px; border-top:1px solid var(--border); }
+.comment-thread .pr-comment:first-of-type { border-top:0; }
+.pr-comment.reply { margin-left:26px; background:rgba(255,255,255,.012); border-left:2px solid var(--accent-line); }
+.pr-comment-head { display:flex; align-items:center; gap:9px; font-size:11px; color:var(--muted-2); }
+.pr-comment-author { font-size:12px; font-weight:600; color:var(--fg); }
+.pr-comment-link { display:inline-flex; align-items:center; gap:5px; font-size:11px; color:var(--muted); text-decoration:none; }
+.pr-comment-link:hover { color:var(--accent); }
+.pr-comment-body { font-size:12.5px; line-height:1.6; color:#f0ece6; }
+.pr-comment-body .md-p, .pr-comment-body .md-list { font-size:12.5px; }
 .main { flex:1; min-width:0; display:flex; flex-direction:column; overflow-y:auto; }
 .topbar { position:sticky; top:0; z-index:10; display:flex; align-items:center; justify-content:space-between; gap:16px;
   padding:13px 24px; border-bottom:1px solid var(--border); background:rgba(16,16,20,.74);

package/src/server/pr-comments.ts

@@ -0,0 +1,256 @@
+/**
+ * Comentários de uma Pull Request (servidor) — threads de revisão + comentários
+ * gerais, lidos via `gh api`.
+ *
+ * A aba é lazy: só chama o GitHub quando o cliente pede. O resultado fica em
+ * cache por branch (TTL de 60s); `refresh` ignora o cache. Tudo fail-open: sem
+ * PR/gh/login, devolve `available:false` e a UI mostra o motivo.
+ */
+
+import { resolve } from "node:path";
+import { resolvePrTarget } from "../core/github-review";
+import { systemClock } from "../core/services/clock";
+import { describeGhError, type GhRunner } from "../core/services/gh-client";
+
+/** Cache do payload já processado (por raiz do repositório + branch). */
+const CACHE_TTL_MS = 60_000;
+const cache = new Map<string, { expiresAt: number; value: PrCommentsResponse }>();
+
+/** Limpa o cache (testes e shutdown). */
+export function clearPrCommentsCache(): void {
+	cache.clear();
+}
+
+/** Comentário já normalizado para a UI. */
+export type PrCommentView = {
+	id: number;
+	author: string;
+	authorType: string;
+	body: string;
+	createdAt?: string;
+	url?: string;
+	path?: string;
+	line: number | null;
+	absFile?: string;
+	replyTo?: number | null;
+};
+
+/** Thread de revisão (comentário raiz + respostas). */
+export type PrCommentThread = {
+	id: number;
+	path: string;
+	line: number | null;
+	absFile: string;
+	comments: PrCommentView[];
+};
+
+/** Resposta de `GET /api/runs/:slug/comments`. */
+export type PrCommentsResponse = {
+	available: boolean;
+	reason?: string;
+	target?: { number: number; repo: string; url?: string };
+	fetchedAt: string;
+	threads: PrCommentThread[];
+	issueComments: PrCommentView[];
+	counts: { threads: number; inline: number; issue: number };
+};
+
+type GhInlineComment = {
+	id?: number;
+	body?: string;
+	path?: string;
+	line?: number | null;
+	original_line?: number | null;
+	created_at?: string;
+	html_url?: string;
+	in_reply_to_id?: number | null;
+	user?: { login?: string; type?: string };
+};
+
+type GhIssueComment = {
+	id?: number;
+	body?: string;
+	created_at?: string;
+	html_url?: string;
+	user?: { login?: string; type?: string };
+};
+
+type ApiList = { ok: true; items: unknown[] } | { ok: false; reason: string };
+
+function unavailable(
+	reason: string,
+	target?: PrCommentsResponse["target"],
+): PrCommentsResponse {
+	return {
+		available: false,
+		reason,
+		target,
+		fetchedAt: systemClock(),
+		threads: [],
+		issueComments: [],
+		counts: { threads: 0, inline: 0, issue: 0 },
+	};
+}
+
+/** Lista paginada via `gh api`; `--slurp` junta as páginas num único array. */
+function ghApiList(runner: GhRunner, path: string): ApiList {
+	let result = runner(["api", "--paginate", "--slurp", path]);
+	if (!result.ok && /unknown flag|unknown shorthand|slurp/i.test(result.stderr)) {
+		result = runner(["api", path]);
+	}
+	if (!result.ok) return { ok: false, reason: describeGhError(result) };
+	try {
+		const parsed = JSON.parse(result.stdout);
+		if (Array.isArray(parsed)) {
+			// Dependendo da versão do gh, `--slurp` pode devolver `[[...], [...]]`
+			// (um array por página) ou um array já achatado.
+			const items: unknown[] = [];
+			for (const item of parsed) {
+				if (Array.isArray(item)) items.push(...item);
+				else items.push(item);
+			}
+			return { ok: true, items };
+		}
+		return { ok: false, reason: "Resposta inesperada do gh (esperava uma lista)." };
+	} catch {
+		return { ok: false, reason: "Resposta inválida do gh (JSON malformado)." };
+	}
+}
+
+function toView(
+	raw: GhInlineComment | GhIssueComment,
+	repoRoot: string,
+): PrCommentView | null {
+	const id = Number(raw.id);
+	const body = raw.body?.trim() ?? "";
+	if (!Number.isFinite(id) || body.length === 0) return null;
+	const path = "path" in raw ? raw.path : undefined;
+	const line = "line" in raw ? (raw.line ?? raw.original_line ?? null) : null;
+	return {
+		id,
+		author: raw.user?.login ?? "desconhecido",
+		authorType: raw.user?.type ?? "User",
+		body,
+		createdAt: raw.created_at,
+		url: raw.html_url,
+		path,
+		line,
+		absFile: path ? resolve(repoRoot, path) : undefined,
+		replyTo: "in_reply_to_id" in raw ? (raw.in_reply_to_id ?? null) : null,
+	};
+}
+
+/** Agrupa comentários inline em threads (raiz + respostas). */
+function buildThreads(
+	items: unknown[],
+	repoRoot: string,
+): {
+	threads: PrCommentThread[];
+	inline: number;
+} {
+	const raws = (items as GhInlineComment[])
+		.filter((raw) => raw && typeof raw === "object")
+		.sort(
+			(a, b) =>
+				(a.created_at ?? "").localeCompare(b.created_at ?? "") ||
+				Number(a.id ?? 0) - Number(b.id ?? 0),
+		);
+
+	const views: PrCommentView[] = [];
+	const parent = new Map<number, number | null>();
+	for (const raw of raws) {
+		const view = toView(raw, repoRoot);
+		if (!view) continue;
+		views.push(view);
+		parent.set(view.id, raw.in_reply_to_id ?? null);
+	}
+
+	const rootOf = (id: number): number => {
+		let current = id;
+		const seen = new Set<number>();
+		for (;;) {
+			const next = parent.get(current);
+			if (!next || seen.has(current)) return current;
+			seen.add(current);
+			current = next;
+		}
+	};
+
+	const byRoot = new Map<number, PrCommentThread>();
+	for (const view of views) {
+		const rootId = rootOf(view.id);
+		const existing = byRoot.get(rootId);
+		if (existing) {
+			existing.comments.push(view);
+			continue;
+		}
+		const path = view.path ?? "";
+		byRoot.set(rootId, {
+			id: rootId,
+			path,
+			line: view.line,
+			absFile: view.absFile ?? (path ? resolve(repoRoot, path) : ""),
+			comments: [view],
+		});
+	}
+
+	const threads = [...byRoot.values()].sort(
+		(a, b) =>
+			a.path.localeCompare(b.path) ||
+			(a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER) ||
+			a.id - b.id,
+	);
+	return { threads, inline: views.length };
+}
+
+/** Lê e agrupa os comentários da PR da branch (com cache de 60s). */
+export function fetchPrComments(options: {
+	runner: GhRunner;
+	branch: string;
+	repoRoot: string;
+	refresh?: boolean;
+	now?: number;
+}): PrCommentsResponse {
+	const { runner, branch, repoRoot, refresh = false } = options;
+	const now = options.now ?? Date.now();
+	const key = `${resolve(repoRoot)}\0${branch}`;
+	const cached = cache.get(key);
+	if (!refresh && cached && cached.expiresAt > now) return cached.value;
+
+	const target = resolvePrTarget(runner, branch);
+	if (!target.ok) return unavailable(target.reason);
+
+	const pr = {
+		number: target.target.number,
+		repo: target.target.repo,
+		url: target.target.url,
+	};
+	const inline = ghApiList(runner, `repos/${pr.repo}/pulls/${pr.number}/comments`);
+	if (!inline.ok) return unavailable(inline.reason, pr);
+
+	const issue = ghApiList(runner, `repos/${pr.repo}/issues/${pr.number}/comments`);
+	if (!issue.ok) return unavailable(issue.reason, pr);
+
+	const { threads, inline: inlineCount } = buildThreads(inline.items, repoRoot);
+	const issueComments = (issue.items as GhIssueComment[])
+		.map((raw) => toView(raw, repoRoot))
+		.filter((view): view is PrCommentView => view !== null)
+		.sort(
+			(a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? "") || a.id - b.id,
+		);
+
+	const value: PrCommentsResponse = {
+		available: true,
+		target: pr,
+		fetchedAt: systemClock(),
+		threads,
+		issueComments,
+		counts: {
+			threads: threads.length,
+			inline: inlineCount,
+			issue: issueComments.length,
+		},
+	};
+	cache.set(key, { expiresAt: now + CACHE_TTL_MS, value });
+	return value;
+}