@payconductor/houndsman 0.7.0 → 0.8.0

package/src/core/services/git-repository.ts

@@ -75,6 +75,52 @@ export class GitRepository {
 	isAncestor(ancestor: string, descendant: string): boolean {
 		return this.tryRun(["merge-base", "--is-ancestor", ancestor, descendant]).ok;
 	}
+	/** SHA do merge-base entre duas refs; `null` quando não há ancestral comum. */
+	mergeBase(base: string, head: string): string | null {
+		const result = this.tryRun(["merge-base", base, head]);
+		const sha = result.ok ? result.stdout.trim() : "";
+		return sha.length > 0 ? sha : null;
+	}
+
+	/**
+	 * Diretório git comum (`.git`) em caminho absoluto. Em um worktree linkado
+	 * aponta para o `.git` do clone principal — é como descobrimos a raiz real.
+	 */
+	gitCommonDir(): string | null {
+		const result = this.tryRun([
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir",
+		]);
+		const dir = result.ok ? result.stdout.trim() : "";
+		return dir.length > 0 ? dir : null;
+	}
+
+	/** Saída crua de `git worktree list --porcelain` (vazia em erro). */
+	worktreeListRaw(): string {
+		const result = this.tryRun(["worktree", "list", "--porcelain"]);
+		return result.ok ? result.stdout : "";
+	}
+
+	/** Cria um worktree detached apontando para `ref` (lança em falha). */
+	addWorktree(path: string, ref: string): string {
+		return this.run(["worktree", "add", "--detach", path, ref]);
+	}
+
+	/** Remove um worktree; nunca lança (devolve o resultado para o chamador). */
+	removeWorktree(path: string, force = false): GitResult {
+		return this.tryRun(["worktree", "remove", ...(force ? ["--force"] : []), path]);
+	}
+
+	/** Remove metadados de worktrees cujo diretório sumiu. */
+	pruneWorktrees(): GitResult {
+		return this.tryRun(["worktree", "prune"]);
+	}
+
+	/** `git fetch --no-tags <remote> <refspecs...>` (nunca lança). */
+	fetch(remote: string, refspecs: readonly string[]): GitResult {
+		return this.tryRun(["fetch", "--no-tags", remote, ...refspecs]);
+	}
 
 	/** Conteúdo de um arquivo num commit; `null` se ausente. */
 	readFileAt(sha: string, path: string): string | null {

package/src/core/services/pr-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * Resolução de uma PR para revisão (biblioteca).
+ *
+ * Usa `gh pr view` para descobrir head/base e garante os commits localmente.
+ * O head é buscado em `refs/pull/<n>/head`, que funciona também para forks;
+ * o base vem de `origin/<baseRefName>`. Fail-open na leitura, mas a revisão só
+ * começa quando as refs necessárias existem (erro explícito caso contrário).
+ */
+
+import { describeGhError, type GhRunner } from "./gh-client";
+import type { GitRepository } from "./git-repository";
+
+const PR_FIELDS =
+	"number,title,headRefName,baseRefName,headRefOid,isCrossRepository,url,isDraft";
+
+/** Dados mínimos de uma PR para montar o worktree. */
+export type PullRequestInfo = {
+	number: number;
+	title?: string;
+	headRefName: string;
+	baseRefName: string;
+	/** Commit exato do head no momento da consulta. */
+	headSha?: string;
+	isCrossRepository: boolean;
+	isDraft: boolean;
+	url?: string;
+};
+
+/** Resultado da consulta ao `gh`. */
+export type PrResolveResult =
+	| { ok: true; pr: PullRequestInfo }
+	| { ok: false; reason: "gh" | "invalid"; detail: string };
+
+/** Refs locais preparadas para o diff. */
+export type PrRefs = {
+	base: string;
+	head: string;
+	/** `true` quando o fetch trouxe algo novo. */
+	fetched: boolean;
+	/** Aviso (ex.: fetch parcial) para o CLI imprimir. */
+	warning?: string;
+};
+
+type GhPrView = {
+	number?: unknown;
+	title?: unknown;
+	headRefName?: unknown;
+	baseRefName?: unknown;
+	headRefOid?: unknown;
+	isCrossRepository?: unknown;
+	isDraft?: unknown;
+	url?: unknown;
+};
+
+/** Cliente de PR sobre um runner injetável. */
+export class PrResolver {
+	constructor(
+		private readonly runner: GhRunner,
+		private readonly git: GitRepository,
+	) {}
+
+	/** Consulta a PR no GitHub (nunca lança). */
+	resolve(number: number): PrResolveResult {
+		const result = this.runner(["pr", "view", String(number), "--json", PR_FIELDS]);
+		if (!result.ok) {
+			return { ok: false, reason: "gh", detail: describeGhError(result) };
+		}
+
+		let parsed: GhPrView;
+		try {
+			parsed = JSON.parse(result.stdout) as GhPrView;
+		} catch {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "Resposta inválida do gh (JSON malformado).",
+			};
+		}
+
+		const headRefName =
+			typeof parsed.headRefName === "string" ? parsed.headRefName.trim() : "";
+		const baseRefName =
+			typeof parsed.baseRefName === "string" ? parsed.baseRefName.trim() : "";
+		const resolvedNumber = Number(parsed.number);
+		if (
+			!Number.isFinite(resolvedNumber) ||
+			resolvedNumber <= 0 ||
+			headRefName.length === 0 ||
+			baseRefName.length === 0
+		) {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "gh não devolveu número/head/base da PR.",
+			};
+		}
+
+		return {
+			ok: true,
+			pr: {
+				number: resolvedNumber,
+				title: typeof parsed.title === "string" ? parsed.title : undefined,
+				headRefName,
+				baseRefName,
+				headSha:
+					typeof parsed.headRefOid === "string"
+						? parsed.headRefOid.trim()
+						: undefined,
+				isCrossRepository: Boolean(parsed.isCrossRepository),
+				isDraft: Boolean(parsed.isDraft),
+				url: typeof parsed.url === "string" ? parsed.url : undefined,
+			},
+		};
+	}
+
+	/**
+	 * Garante base/head da PR no repositório local.
+	 *
+	 * Prefere o SHA informado pelo `gh`; cai para `refs/houndsman/pr-<n>` quando
+	 * o objeto não existe localmente.
+	 */
+	prepareRefs(pr: PullRequestInfo): PrRefs {
+		const headRef = `refs/houndsman/pr-${pr.number}`;
+		const headFetch = this.git.fetch("origin", [
+			`+refs/pull/${pr.number}/head:${headRef}`,
+		]);
+		const baseFetch = this.git.fetch("origin", [pr.baseRefName]);
+
+		const originBase = `origin/${pr.baseRefName}`;
+		const hasOriginBase = this.git.tryRun(["rev-parse", "--verify", originBase]).ok;
+		const base = hasOriginBase ? originBase : pr.baseRefName;
+
+		const hasSha = pr.headSha
+			? this.git.tryRun(["cat-file", "-e", `${pr.headSha}^{commit}`]).ok
+			: false;
+		const head = hasSha && pr.headSha ? pr.headSha : headRef;
+
+		const warning =
+			!headFetch.ok && !hasSha
+				? `Não foi possível buscar o head da PR: ${headFetch.stderr.trim()}`
+				: !baseFetch.ok
+					? `Não foi possível atualizar ${pr.baseRefName}: ${baseFetch.stderr.trim()}`
+					: undefined;
+
+		return { base, head, fetched: headFetch.ok || baseFetch.ok, warning };
+	}
+}

package/src/core/services/worktree-manager.ts

@@ -0,0 +1,269 @@
+/**
+ * Worktrees gerenciados pelo houndsman (biblioteca).
+ *
+ * Um worktree por branch revisada, criado em **detached HEAD** no commit da PR.
+ * Detached evita o conflito "branch já checada" com o clone principal e é o
+ * modo correto para revisão (somente leitura). Vive fora do projeto, em
+ * `<HOUNDSMAN_HOME>/worktrees/<repoSlug>/<branchSlug>`.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createGitRunner } from "../git-runner";
+import { sanitizeBranch } from "../report-builder";
+import { worktreesRoot } from "../storage/paths";
+import { GitRepository } from "./git-repository";
+
+/** Entrada de `git worktree list --porcelain`. */
+export type WorktreeEntry = {
+	path: string;
+	head?: string;
+	/** Ref completo (`refs/heads/...`) quando não detached. */
+	branch?: string;
+	detached: boolean;
+	bare: boolean;
+	prunable: boolean;
+	locked: boolean;
+};
+
+/** Entrada de criação de worktree. */
+export type EnsureWorktreeInput = {
+	branch: string;
+	/** Ref/SHA que o worktree deve apontar. */
+	ref: string;
+};
+
+/** Resultado da criação/reuso. */
+export type EnsureWorktreeResult = {
+	path: string;
+	/** Commit efetivamente checado (detached). */
+	head: string;
+	/** `true` quando o diretório foi criado agora. */
+	created: boolean;
+	/** `true` quando já existia apontando para o commit pedido. */
+	reused: boolean;
+};
+
+/** Resultado da remoção. */
+export type RemoveWorktreeResult = {
+	removed: boolean;
+	detail?: string;
+};
+
+/** Opções do gerenciador. */
+export type WorktreeManagerOptions = {
+	repoKey: string;
+	/** Raiz do clone principal. */
+	repoRoot: string;
+	/**
+	 * Raiz onde os diretórios por repositório são criados.
+	 * Default: `<HOUNDSMAN_HOME>/worktrees` (o CLI normalmente passa
+	 * `resolveWorktreesRoot(config.worktrees?.location, repoRoot)`).
+	 */
+	baseDir?: string;
+};
+
+/** Slug estável e legível para o diretório do repositório. */
+export function repoSlug(repoKey: string): string {
+	const clean = repoKey
+		.replace(/^(remote|path):/, "")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.toLowerCase();
+	const hash = createHash("sha1").update(repoKey).digest("hex").slice(0, 8);
+	return `${clean.slice(-60) || "repo"}-${hash}`;
+}
+
+/** Normaliza um path para comparação (Windows é case-insensitive). */
+function normalizePath(path: string): string {
+	const absolute = resolve(path).replace(/[\\/]+$/, "");
+	return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+
+/** `true` se `path` está dentro de `root`. */
+function isInside(root: string, path: string): boolean {
+	const rel = relative(resolve(root), resolve(path));
+	return rel === "" || (!rel.startsWith("..") && !rel.split(sep).includes(".."));
+}
+
+/** Fatia a saída de `git worktree list --porcelain` em entradas. */
+export function parseWorktreeList(raw: string): WorktreeEntry[] {
+	const entries: WorktreeEntry[] = [];
+	let current: WorktreeEntry | null = null;
+
+	const flush = (): void => {
+		if (current) entries.push(current);
+		current = null;
+	};
+
+	for (const line of raw.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			flush();
+			current = {
+				path: line.slice("worktree ".length).trim(),
+				detached: false,
+				bare: false,
+				prunable: false,
+				locked: false,
+			};
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("HEAD ")) current.head = line.slice(5).trim();
+		else if (line.startsWith("branch ")) current.branch = line.slice(7).trim();
+		else if (line === "detached") current.detached = true;
+		else if (line === "bare") current.bare = true;
+		else if (line.startsWith("prunable")) current.prunable = true;
+		else if (line.startsWith("locked")) current.locked = true;
+	}
+	flush();
+	return entries;
+}
+
+/** Gerencia os worktrees de um repositório. */
+export class WorktreeManager {
+	private readonly git: GitRepository;
+	private readonly repoKey: string;
+	private readonly rootDir: string;
+
+	constructor(git: GitRepository, options: WorktreeManagerOptions) {
+		this.git = git;
+		this.repoKey = options.repoKey;
+		this.rootDir = join(
+			options.baseDir ?? worktreesRoot(),
+			repoSlug(options.repoKey),
+		);
+	}
+
+	/**
+	 * Garante o diretório gerenciado e um `.gitignore` local (`*`), para que
+	 * worktrees dentro do repositório nunca sujem `git status` — mesmo que a
+	 * camada `.houndsman/.gitignore` ainda não tenha sido atualizada.
+	 */
+	private ensureRoot(): void {
+		mkdirSync(this.rootDir, { recursive: true });
+		const ignore = join(this.rootDir, ".gitignore");
+		if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
+	}
+
+	/** Diretório-base dos worktrees deste repositório. */
+	get baseDir(): string {
+		return this.rootDir;
+	}
+
+	/** Caminho determinístico do worktree de uma branch. */
+	pathFor(branch: string): string {
+		const slug = sanitizeBranch(branch) || "branch";
+		return join(this.rootDir, slug);
+	}
+
+	/** Todos os worktrees registrados no repositório. */
+	list(): WorktreeEntry[] {
+		return parseWorktreeList(this.git.worktreeListRaw());
+	}
+
+	/** Apenas os worktrees sob o diretório gerenciado. */
+	managed(): WorktreeEntry[] {
+		return this.list().filter((entry) => isInside(this.rootDir, entry.path));
+	}
+
+	/** Worktree registrado para uma branch (se existir). */
+	find(branch: string): WorktreeEntry | null {
+		const target = normalizePath(this.pathFor(branch));
+		return this.list().find((entry) => normalizePath(entry.path) === target) ?? null;
+	}
+
+	/**
+	 * Garante o worktree da branch no commit `ref`.
+	 *
+	 * Reusa quando o HEAD já é o commit pedido; tenta `checkout --detach` quando
+	 * existe e está em outro commit; recria quando o diretório está quebrado.
+	 */
+	ensure(input: EnsureWorktreeInput): EnsureWorktreeResult {
+		this.ensureRoot();
+		const path = this.pathFor(input.branch);
+		const target = this.git.resolveSha(input.ref);
+		const existing = this.list().find(
+			(entry) => normalizePath(entry.path) === normalizePath(path),
+		);
+
+		if (existing) {
+			if (existing.head === target) {
+				return { path, head: target, created: false, reused: true };
+			}
+			const checkout = new GitRepository(createGitRunner(path)).tryRun([
+				"checkout",
+				"--detach",
+				target,
+			]);
+			if (checkout.ok) {
+				return { path, head: target, created: false, reused: true };
+			}
+			// Worktree quebrado/inacessível: remove e recria do zero.
+			this.git.removeWorktree(path, true);
+			rmSync(path, { recursive: true, force: true });
+		} else if (existsSync(path)) {
+			// Diretório sobrou de um prune/remoção manual.
+			if (!isInside(this.rootDir, path)) {
+				throw new Error(`Worktree fora da raiz gerenciada: ${path}`);
+			}
+			rmSync(path, { recursive: true, force: true });
+		}
+
+		mkdirSync(dirname(path), { recursive: true });
+		try {
+			this.git.addWorktree(path, target);
+		} catch (error) {
+			// Corrida com outro processo ou metadado órfão: pruna e tenta 1x.
+			this.git.pruneWorktrees();
+			try {
+				this.git.addWorktree(path, target);
+			} catch (retry) {
+				const detail = retry instanceof Error ? retry.message : String(retry);
+				const original = error instanceof Error ? error.message : String(error);
+				throw new Error(
+					`Falha ao criar worktree em ${path}: ${detail || original}`,
+				);
+			}
+		}
+		return { path, head: target, created: true, reused: false };
+	}
+
+	/** Remove o worktree de uma branch (ou um path absoluto). */
+	remove(
+		branchOrPath: string,
+		options: { force?: boolean } = {},
+	): RemoveWorktreeResult {
+		const path = isAbsolute(branchOrPath) ? branchOrPath : this.pathFor(branchOrPath);
+		const entry = this.list().find(
+			(worktree) => normalizePath(worktree.path) === normalizePath(path),
+		);
+		if (!entry) {
+			if (existsSync(path) && isInside(this.rootDir, path)) {
+				rmSync(path, { recursive: true, force: true });
+			}
+			return { removed: false, detail: "worktree não registrado" };
+		}
+
+		const result = this.git.removeWorktree(path, options.force ?? false);
+		if (result.ok) return { removed: true };
+
+		if (options.force) {
+			rmSync(path, { recursive: true, force: true });
+			this.git.pruneWorktrees();
+			return { removed: true };
+		}
+		return { removed: false, detail: result.stderr.trim() };
+	}
+
+	/** Limpa metadados de worktrees que não existem mais. */
+	prune(): string {
+		return this.git.pruneWorktrees().stdout.trim();
+	}
+
+	/** Nome legível do repositório gerenciado (diagnóstico). */
+	get name(): string {
+		return basename(this.rootDir) || this.repoKey;
+	}
+}

package/src/core/storage/file/file-storage.ts

@@ -43,12 +43,17 @@ export class FileStorageProvider implements StorageProvider {
 		if (existing) {
 			if (
 				existing.repoRoot !== input.repo.root ||
-				existing.repoRemote !== input.repo.remote
+				existing.repoRemote !== input.repo.remote ||
+				(input.worktreePath !== undefined &&
+					existing.worktreePath !== input.worktreePath) ||
+				(input.prNumber !== undefined && existing.prNumber !== input.prNumber)
 			) {
 				return this.writeReview({
 					...existing,
 					repoRoot: input.repo.root,
 					repoRemote: input.repo.remote,
+					worktreePath: input.worktreePath ?? existing.worktreePath,
+					prNumber: input.prNumber ?? existing.prNumber,
 				});
 			}
 			return existing;
@@ -64,6 +69,8 @@ export class FileStorageProvider implements StorageProvider {
 			slug: input.slug,
 			base: input.base,
 			head: input.head,
+			worktreePath: input.worktreePath,
+			prNumber: input.prNumber,
 			status: null,
 			createdAt: now,
 			updatedAt: now,
@@ -99,11 +106,17 @@ export class FileStorageProvider implements StorageProvider {
 		if (patch.headSha !== undefined) updated.headSha = patch.headSha;
 		if (patch.reviewedSha !== undefined) updated.reviewedSha = patch.reviewedSha;
 		if (patch.reviewedAt !== undefined) updated.reviewedAt = patch.reviewedAt;
+		if (patch.worktreePath !== undefined) updated.worktreePath = patch.worktreePath;
+		if (patch.prNumber !== undefined) updated.prNumber = patch.prNumber;
 		if (patch.status !== undefined) updated.status = patch.status;
 		if (patch.resetStartedAt) updated.startedAt = now;
 		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
 		if (patch.resetHeartbeat) updated.heartbeatAt = undefined;
 		else if (patch.heartbeatAt !== undefined) updated.heartbeatAt = patch.heartbeatAt;
+		if (patch.resetWorkspace) {
+			updated.worktreePath = undefined;
+			updated.prNumber = undefined;
+		}
 		updated.updatedAt = patch.updatedAt ?? now;
 		return this.writeReview(updated);
 	}

package/src/core/storage/paths.ts

@@ -7,9 +7,11 @@
  */
 
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import type { HoundsmanConfig } from "../config";
+import { DEFAULT_WORKTREES_LOCATION } from "../defaults";
 import { ENV_NAMES, env } from "../env";
+import { PROJECT_DIR } from "../paths";
 
 export const HOUNDSMAN_HOME_ENV = ENV_NAMES.home;
 
@@ -52,6 +54,33 @@ export function workRoot(): string {
 	return join(houndsmanHome(), "work");
 }
 
+/** Raiz global dos worktrees (`worktrees.location: "home"`). */
+export function worktreesRoot(): string {
+	return join(houndsmanHome(), "worktrees");
+}
+
+/** Diretório de um worktree gerenciado. */
+export function worktreeDir(repoSlug: string, branchSlug: string): string {
+	return join(worktreesRoot(), repoSlug, branchSlug);
+}
+
+/**
+ * Raiz efetiva dos worktrees de um repositório.
+ *
+ * `workspace` (default) mantém tudo em `<repo>/.houndsman/worktrees` — dentro
+ * da pasta aberta no editor, o que evita prompts de permissão de agentes.
+ * `home` usa o diretório global; outros valores são caminhos do usuário.
+ */
+export function resolveWorktreesRoot(
+	location: string | undefined,
+	repoRoot: string,
+): string {
+	const value = location?.trim() || DEFAULT_WORKTREES_LOCATION;
+	if (value === "home") return worktreesRoot();
+	if (value === "workspace") return join(repoRoot, PROJECT_DIR, "worktrees");
+	return isAbsolute(value) ? value : resolve(repoRoot, value);
+}
+
 /** Referência legível do storage configurado (diagnóstico). */
 export function storageLocation(config: HoundsmanConfig): string {
 	return config.storage?.provider === "file"

package/src/core/storage/sqlite/mappers.ts

@@ -31,6 +31,8 @@ export type ReviewRow = {
 	status: string | null;
 	started_at: string | null;
 	heartbeat_at: string | null;
+	worktree_path: string | null;
+	pr_number: number | null;
 	created_at: string;
 	updated_at: string;
 };
@@ -95,6 +97,8 @@ export function reviewFromRow(row: ReviewRow): ReviewRecord {
 		headSha: row.head_sha ?? undefined,
 		reviewedSha: row.reviewed_sha ?? undefined,
 		reviewedAt: row.reviewed_at ?? undefined,
+		worktreePath: row.worktree_path ?? undefined,
+		prNumber: row.pr_number ?? undefined,
 		status: (row.status as ReviewRecord["status"]) ?? null,
 		startedAt: row.started_at ?? undefined,
 		heartbeatAt: row.heartbeat_at ?? undefined,

package/src/core/storage/sqlite/schema.ts

@@ -7,7 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS reviews (
@@ -25,6 +25,8 @@ CREATE TABLE IF NOT EXISTS reviews (
 	status TEXT,
 	started_at TEXT,
 	heartbeat_at TEXT,
+	worktree_path TEXT,
+	pr_number INTEGER,
 	created_at TEXT NOT NULL,
 	updated_at TEXT NOT NULL,
 	UNIQUE(repo_key, branch)
@@ -105,11 +107,19 @@ export function migrate(db: Database, path: string): void {
 	db.transaction(() => {
 		db.exec(DDL);
 		// v2: heartbeat explícito da execução (bancos v1 não tinham a coluna).
+		// v3: worktree/pr da revisão (revisões paralelas).
 		const columns = db.query("PRAGMA table_info(reviews)").all() as {
 			name: string;
 		}[];
-		if (!columns.some((column) => column.name === "heartbeat_at")) {
-			db.exec("ALTER TABLE reviews ADD COLUMN heartbeat_at TEXT");
+		const missing: [string, string][] = [
+			["heartbeat_at", "TEXT"],
+			["worktree_path", "TEXT"],
+			["pr_number", "INTEGER"],
+		];
+		for (const [name, type] of missing) {
+			if (!columns.some((column) => column.name === name)) {
+				db.exec(`ALTER TABLE reviews ADD COLUMN ${name} ${type}`);
+			}
 		}
 		db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 	})();