@payconductor/houndsman 0.6.0 → 0.8.0

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

package/src/server/pr-inbox.ts

@@ -0,0 +1,213 @@
+/**
+ * Caixa de entrada de Pull Requests do repositório atual (servidor).
+ *
+ * Lista as PRs abertas via `gh` e executa o checkout somente quando a árvore
+ * de trabalho está limpa. Fail-open: sem `gh` (ou sem git), devolve o motivo e
+ * a UI degrada sem quebrar as demais abas.
+ */
+
+import { describeGhError, type GhRunner } from "../core/services/gh-client";
+import type { GitRepository } from "../core/services/git-repository";
+
+/** Estado da árvore de trabalho (base do bloqueio do checkout). */
+export type WorktreeState = {
+	/** `false` quando o `git status` falhou. */
+	available: boolean;
+	clean: boolean;
+	changes: number;
+	/** Amostra dos caminhos alterados (limitada para a UI). */
+	sample: string[];
+};
+
+/** Run associada à branch de uma PR. */
+export type PrRunInfo = {
+	slug: string;
+	worktreePath?: string;
+	prNumber?: number;
+};
+
+/** 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;
+	/** Run local correspondente à branch, quando existir. */
+	runSlug?: string;
+	/** Worktree ativo da PR (revisão paralela). */
+	worktreePath?: string;
+};
+
+/** Resposta de `GET /api/prs`. */
+export type PrListResponse = {
+	available: boolean;
+	reason?: string;
+	currentBranch: string | null;
+	worktree: WorktreeState;
+	prs: PrListItem[];
+};
+
+/** Resultado do checkout de uma PR. */
+export type CheckoutResponse =
+	| { ok: true; number: number; branch: string | null }
+	| {
+			ok: false;
+			reason: "dirty" | "git" | "gh";
+			detail: string;
+			changes?: string[];
+	  };
+
+const PR_LIST_FIELDS =
+	"number,title,headRefName,baseRefName,author,updatedAt,isDraft,reviewDecision,url";
+
+type GhPrListItem = {
+	number?: number;
+	title?: string;
+	headRefName?: string;
+	baseRefName?: string;
+	author?: { login?: string; name?: string };
+	updatedAt?: string;
+	isDraft?: boolean;
+	reviewDecision?: string;
+	url?: string;
+};
+
+function toItem(
+	raw: GhPrListItem,
+	runs: ReadonlyMap<string, PrRunInfo>,
+): PrListItem | null {
+	const number = Number(raw.number);
+	const headRefName = raw.headRefName?.trim();
+	if (!Number.isFinite(number) || number <= 0 || !headRefName) return null;
+	const run = runs.get(headRefName);
+	return {
+		number,
+		title: raw.title?.trim() || `PR #${number}`,
+		headRefName,
+		baseRefName: raw.baseRefName?.trim() || "",
+		author: raw.author?.login ?? raw.author?.name ?? "desconhecido",
+		updatedAt: raw.updatedAt,
+		isDraft: Boolean(raw.isDraft),
+		reviewDecision: raw.reviewDecision?.trim() || undefined,
+		url: raw.url,
+		runSlug: run?.slug,
+		worktreePath: run?.worktreePath,
+	};
+}
+
+/** Acesso às PRs do repositório atual. */
+export class PrInbox {
+	constructor(
+		private readonly ghRunner: GhRunner,
+		private readonly git: GitRepository,
+	) {}
+
+	/** Estado da árvore de trabalho (`git status --porcelain`). */
+	worktree(): WorktreeState {
+		const result = this.git.tryRun(["status", "--porcelain"]);
+		if (!result.ok) {
+			return { available: false, clean: false, changes: 0, sample: [] };
+		}
+		const lines = result.stdout
+			.split("\n")
+			.map((line) => line.trimEnd())
+			.filter((line) => line.length > 0);
+		return {
+			available: true,
+			clean: lines.length === 0,
+			changes: lines.length,
+			sample: lines.slice(0, 20),
+		};
+	}
+
+	/** Lista as PRs abertas (limite 50) e o estado local do repositório. */
+	list(runs: ReadonlyMap<string, PrRunInfo> = new Map()): PrListResponse {
+		const currentBranch = this.git.currentBranch();
+		const worktree = this.worktree();
+		const result = this.ghRunner([
+			"pr",
+			"list",
+			"--state",
+			"open",
+			"--limit",
+			"50",
+			"--json",
+			PR_LIST_FIELDS,
+		]);
+
+		if (!result.ok) {
+			return {
+				available: false,
+				reason: describeGhError(result),
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(result.stdout);
+		} catch {
+			return {
+				available: false,
+				reason: "Resposta inválida do gh (JSON malformado).",
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+		if (!Array.isArray(parsed)) {
+			return {
+				available: false,
+				reason: "Resposta inesperada do gh (esperava uma lista de PRs).",
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+
+		const prs = (parsed as GhPrListItem[])
+			.map((item) => toItem(item, runs))
+			.filter((item): item is PrListItem => item !== null)
+			.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+
+		return { available: true, currentBranch, worktree, prs };
+	}
+
+	/**
+	 * Faz checkout da PR via `gh pr checkout`.
+	 *
+	 * A árvore precisa estar limpa: alterações locais não commitadas bloqueiam a
+	 * operação para não descartar trabalho do usuário.
+	 */
+	checkout(number: number): CheckoutResponse {
+		const worktree = this.worktree();
+		if (!worktree.available) {
+			return {
+				ok: false,
+				reason: "git",
+				detail: "Não foi possível ler o estado do git.",
+			};
+		}
+		if (!worktree.clean) {
+			return {
+				ok: false,
+				reason: "dirty",
+				detail: `${worktree.changes} alteração(ões) não commitada(s).`,
+				changes: worktree.sample,
+			};
+		}
+
+		const result = this.ghRunner(["pr", "checkout", String(number)]);
+		if (!result.ok) {
+			return { ok: false, reason: "gh", detail: describeGhError(result) };
+		}
+		return { ok: true, number, branch: this.git.currentBranch() };
+	}
+}

package/src/server/run-repository.ts

@@ -5,6 +5,7 @@
  * O slug continua sendo o branch-slug (estável nas URLs).
  */
 
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import {
 	applyFindingUpdate,
@@ -34,14 +35,23 @@ import {
 } from "../core/github-review";
 import { pingFindingsStatus } from "../core/run-status";
 import { systemClock } from "../core/services/clock";
+import { defaultGhRunner } from "../core/services/gh-client";
+import type { WorktreeManager } from "../core/services/worktree-manager";
+import { workRoot } from "../core/storage/paths";
 import type { RepoIdentity, ReviewRecord, StorageProvider } from "../core/storage/types";
+import { ReviewWorkArea } from "../core/storage/work-area";
 import type { Severity } from "../core/types";
 import { isSlug } from "./artifacts";
+import { fetchPrComments, type PrCommentsResponse } from "./pr-comments";
 
 /** Item da lista de execuções (sidebar) — já ordenado do mais recente ao antigo. */
 export type RunListItem = {
 	slug: string;
 	branch: string;
+	/** Worktree onde a run foi executada (ausente = clone principal). */
+	worktreePath?: string;
+	/** PR revisada (quando iniciada via `--pr`). */
+	prNumber?: number;
 	updatedAt?: string;
 	startedAt?: string;
 	heartbeatAt?: string;
@@ -53,6 +63,10 @@ export type RunListItem = {
 export type RunDetail = {
 	slug: string;
 	branch: string;
+	/** Worktree onde a run foi executada (ausente = clone principal). */
+	worktreePath?: string;
+	/** PR revisada (quando iniciada via `--pr`). */
+	prNumber?: number;
 	status: ReviewRecord | null;
 	manifest: unknown;
 	summary: FindingsSummary;
@@ -61,6 +75,18 @@ export type RunDetail = {
 	deleted: string[];
 };
 
+/** Resultado da exclusão de uma run. */
+export type DeleteRunResult = {
+	deleted: boolean;
+	/** O usuário pediu para remover o worktree. */
+	worktreeRequested: boolean;
+	/** O worktree foi de fato removido. */
+	worktreeRemoved: boolean;
+	worktreePath?: string;
+	/** Aviso quando o worktree não pôde ser removido. */
+	warning?: string;
+};
+
 /** Resultado do envio dos findings à PR. */
 export type SubmitResult =
 	| { available: false; reason: string }
@@ -78,10 +104,19 @@ export type ArtifactListItem = {
 export class RunRepository {
 	private readonly storage: StorageProvider;
 	private readonly repo: RepoIdentity;
+	private readonly ghRunner: GhRunner;
+	private readonly worktrees?: WorktreeManager;
 
-	constructor(storage: StorageProvider, repo: RepoIdentity) {
+	constructor(
+		storage: StorageProvider,
+		repo: RepoIdentity,
+		ghRunner: GhRunner = defaultGhRunner,
+		worktrees?: WorktreeManager,
+	) {
 		this.storage = storage;
 		this.repo = repo;
+		this.ghRunner = ghRunner;
+		this.worktrees = worktrees;
 	}
 
 	/** `true` se o slug aponta para uma run do repositório atual. */
@@ -96,6 +131,8 @@ export class RunRepository {
 			return {
 				slug: review.slug,
 				branch: review.branch,
+				worktreePath: review.worktreePath,
+				prNumber: review.prNumber,
 				updatedAt: review.updatedAt,
 				startedAt: review.startedAt,
 				heartbeatAt: review.heartbeatAt,
@@ -105,6 +142,32 @@ export class RunRepository {
 		});
 	}
 
+	/** Mapa branch → slug das runs (usado para casar PRs com execuções). */
+	branchIndex(): Map<string, string> {
+		return new Map(
+			this.storage
+				.listReviews(this.repo.key)
+				.map((review) => [review.branch, review.slug]),
+		);
+	}
+
+	/** Mapa branch → run + worktree (sidebar de PRs). */
+	workspaceIndex(): Map<
+		string,
+		{ slug: string; worktreePath?: string; prNumber?: number }
+	> {
+		return new Map(
+			this.storage.listReviews(this.repo.key).map((review) => [
+				review.branch,
+				{
+					slug: review.slug,
+					worktreePath: review.worktreePath,
+					prNumber: review.prNumber,
+				},
+			]),
+		);
+	}
+
 	/** Detalhe da run (null se o slug for inválido). */
 	detail(slug: string): RunDetail | null {
 		const review = this.findBySlug(slug);
@@ -118,6 +181,8 @@ export class RunRepository {
 		return {
 			slug: review.slug,
 			branch: review.branch,
+			worktreePath: review.worktreePath,
+			prNumber: review.prNumber,
 			status: review,
 			manifest: this.readArtifactJson(review, "manifest.json"),
 			summary: summarize(state),
@@ -127,6 +192,49 @@ export class RunRepository {
 		};
 	}
 
+	/**
+	 * Apaga a run por completo: staging local, findings, histórico, artefatos e a
+	 * review. Opcionalmente remove o worktree (com `--force`, pois a run foi
+	 * confirmada para exclusão).
+	 */
+	delete(
+		slug: string,
+		options: { removeWorktree?: boolean } = {},
+	): DeleteRunResult | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+
+		const worktreePath = review.worktreePath;
+		const removeWorktree = options.removeWorktree === true && Boolean(worktreePath);
+		let worktreeRemoved = false;
+		let warning: string | undefined;
+
+		if (removeWorktree && worktreePath) {
+			if (this.worktrees) {
+				const result = this.worktrees.remove(worktreePath, { force: true });
+				worktreeRemoved = result.removed;
+				if (!result.removed) {
+					warning = result.detail ?? "worktree não removido";
+				}
+			} else {
+				warning = "worktree não gerenciado por este servidor";
+			}
+		}
+
+		// Staging atual (dentro do worktree quando existe) + legado no home.
+		new ReviewWorkArea(review).clean();
+		new ReviewWorkArea(review, workRoot()).clean();
+
+		this.storage.deleteReview(review.id);
+		return {
+			deleted: true,
+			worktreeRequested: options.removeWorktree === true,
+			worktreeRemoved,
+			worktreePath,
+			warning,
+		};
+	}
+
 	/** Aplica `VACUUM`/`optimize` no backend (chamado no start do server). */
 	maintain(): void {
 		this.storage.maintain();
@@ -154,6 +262,12 @@ export class RunRepository {
 		return this.storage.readFindings(review.id) ?? emptyState(review.branch);
 	}
 
+	/** Raiz dos arquivos da review: worktree vivo ou clone principal. */
+	private rootOf(review: ReviewRecord): string {
+		const worktree = review.worktreePath;
+		return worktree && existsSync(worktree) ? worktree : this.repo.root;
+	}
+
 	private readArtifactJson<T>(review: ReviewRecord, name: string): T | null {
 		const artifact = this.storage.readArtifact(review.id, name);
 		if (!artifact) return null;
@@ -235,7 +349,7 @@ export class RunRepository {
 		const review = this.findBySlug(slug);
 		if (!review) return null;
 		const state = this.loadState(review);
-		const result = syncState(state, fileReader(process.cwd()));
+		const result = syncState(state, fileReader(this.rootOf(review)));
 		this.storage.writeFindings(review.id, state);
 		pingFindingsStatus(this.storage, review.id, state);
 		return { result, summary: summarize(state) };
@@ -273,6 +387,21 @@ export class RunRepository {
 		return { available: true, target: target.target, outcome };
 	}
 
+	/** Comentários da PR da run (null se o slug for inválido). */
+	comments(
+		slug: string,
+		options: { refresh?: boolean } = {},
+	): PrCommentsResponse | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		return fetchPrComments({
+			runner: this.ghRunner,
+			branch: review.branch,
+			repoRoot: review.repoRoot,
+			refresh: options.refresh,
+		});
+	}
+
 	/** Lista os artefatos da run (sem conteúdo). */
 	artifacts(slug: string): ArtifactListItem[] | null {
 		const review = this.findBySlug(slug);
@@ -304,5 +433,9 @@ function toClientFinding(
 	finding: FindingState,
 	review: ReviewRecord,
 ): FindingState & { absFile: string } {
-	return { ...finding, absFile: resolve(review.repoRoot, finding.file) };
+	const root =
+		review.worktreePath && existsSync(review.worktreePath)
+			? review.worktreePath
+			: review.repoRoot;
+	return { ...finding, absFile: resolve(root, finding.file) };
 }