@payconductor/houndsman 0.12.0 → 0.13.0

package/src/core/logging/progress.ts

@@ -0,0 +1,282 @@
+/**
+ * Progresso visual do CLI (infraestrutura).
+ *
+ * `PhaseReporter` acompanha fases sequenciais (spinner em TTY; `→`/`✔` em
+ * pipe). `ProgressBoard` mantém tarefas concorrentes com loader e tempo
+ * decorrido — é o que o harness local usa por watchdog.
+ *
+ * Progresso é diagnóstico: nenhum método lança.
+ */
+
+import type { LoggerLike, SpinnerLike } from "./logger";
+
+/** Formata uma duração em ms (`820ms`, `12.3s`, `2m05s`). */
+export function formatDuration(ms: number): string {
+	const safe = Math.max(0, Math.round(ms));
+	if (safe < 1_000) return `${safe}ms`;
+	const seconds = safe / 1_000;
+	if (seconds < 10) return `${seconds.toFixed(1)}s`;
+	if (seconds < 60) return `${Math.round(seconds)}s`;
+	const minutes = Math.floor(seconds / 60);
+	const rest = Math.round(seconds % 60);
+	return `${minutes}m${String(rest).padStart(2, "0")}s`;
+}
+
+/** Relógio curto no formato `m:ss` (usado no loader). */
+function clock(ms: number): string {
+	const total = Math.max(0, Math.round(ms / 1_000));
+	const minutes = Math.floor(total / 60);
+	return `${minutes}:${String(total % 60).padStart(2, "0")}`;
+}
+
+/** Relógio de uma fase: spinner no TTY, linhas `→`/`✔` em pipe. */
+export class PhaseReporter {
+	private readonly logger: LoggerLike;
+	private active: { stage: string; spinner: SpinnerLike } | null = null;
+
+	constructor(logger: LoggerLike) {
+		this.logger = logger;
+	}
+
+	/** Abre a fase (substituindo qualquer loader anterior). */
+	begin(stage: string, message: string): void {
+		try {
+			this.stop();
+			const spinner = this.logger.spinner(message);
+			if (spinner) {
+				spinner.start();
+				this.active = { stage, spinner };
+				return;
+			}
+			this.logger.step(message);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Fecha a fase com a duração medida. */
+	end(stage: string, message: string, durationMs: number): void {
+		try {
+			const text = `${message} (${formatDuration(durationMs)})`;
+			if (this.active?.stage === stage) {
+				const { spinner } = this.active;
+				this.active = null;
+				spinner.succeed(text);
+				return;
+			}
+			this.logger.success(text);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Encerra um loader pendente (sem mensagem de sucesso). */
+	stop(): void {
+		if (!this.active) return;
+		const { spinner } = this.active;
+		this.active = null;
+		try {
+			spinner.stop();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+}
+
+/** Tarefa concorrente exibida pelo board. */
+type BoardTask = {
+	id: string;
+	detail: string;
+	startedMs: number;
+};
+
+export type ProgressBoardOptions = {
+	logger: LoggerLike;
+	/** Intervalo de repintura do loader em TTY (ms). */
+	frameMs?: number;
+	/** Intervalo do heartbeat textual fora de TTY (ms). */
+	heartbeatMs?: number;
+};
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * Board de tarefas concorrentes (watchdogs do `hunt`).
+ *
+ * Em TTY repinta um bloco com loader + tempo decorrido por tarefa. Fora de
+ * TTY mantém as linhas de início/fim e emite um heartbeat periódico com quem
+ * ainda está rodando — o log do CI continua mostrando progresso.
+ */
+export class ProgressBoard {
+	private readonly logger: LoggerLike;
+	private readonly frameMs: number;
+	private readonly heartbeatMs: number;
+	private readonly tasks = new Map<string, BoardTask>();
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private rendered = 0;
+	private frame = 0;
+	private done = 0;
+	private failed = 0;
+	private total = 0;
+	private lastHeartbeat = Date.now();
+
+	constructor(options: ProgressBoardOptions) {
+		this.logger = options.logger;
+		this.frameMs = options.frameMs ?? 200;
+		this.heartbeatMs = options.heartbeatMs ?? 30_000;
+	}
+
+	/** Define o total de tarefas do lote (rodapé do bloco). */
+	start(total: number): void {
+		this.total = Math.max(0, total);
+	}
+
+	/** Registra uma tarefa em execução. */
+	add(id: string, detail = "em execução"): void {
+		try {
+			this.tasks.set(id, { id, detail, startedMs: Date.now() });
+			if (!this.logger.interactive) this.logger.bullet(`${id}: ${detail}…`);
+			this.ensureTimer();
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Atualiza o detalhe de uma tarefa (ex.: tentativa atual). */
+	update(id: string, detail: string): void {
+		const task = this.tasks.get(id);
+		if (!task) return;
+		task.detail = detail;
+		this.paint();
+	}
+
+	/** Atualiza o detalhe e avisa em pipe (tentativas/retries). */
+	retry(id: string, detail: string, message: string): void {
+		try {
+			this.update(id, detail);
+			if (!this.logger.interactive) this.logger.bullet(message);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Conclui uma tarefa com a mensagem final. */
+	succeed(id: string, message: string): void {
+		try {
+			if (this.tasks.delete(id)) this.done++;
+			if (!this.logger.interactive) {
+				this.logger.success(message);
+				return;
+			}
+			this.clear();
+			this.logger.success(message);
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Falha uma tarefa com a mensagem final. */
+	fail(id: string, message: string): void {
+		try {
+			if (this.tasks.delete(id)) this.failed++;
+			if (!this.logger.interactive) {
+				this.logger.warn(message);
+				return;
+			}
+			this.clear();
+			this.logger.warn(message);
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Encerra o board (timer + bloco renderizado). */
+	stop(): void {
+		this.stopTimer();
+		this.clear();
+	}
+
+	private ensureTimer(): void {
+		if (this.timer) return;
+		const period = this.logger.interactive ? this.frameMs : this.heartbeatMs;
+		this.timer = setInterval(() => this.tick(), period);
+		// Nunca segura o processo vivo por causa de um loader.
+		(this.timer as unknown as { unref?: () => void }).unref?.();
+	}
+
+	private stopTimer(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = null;
+	}
+
+	private tick(): void {
+		if (this.tasks.size === 0) {
+			this.stopTimer();
+			return;
+		}
+		if (this.logger.interactive) {
+			this.frame++;
+			this.paint();
+			return;
+		}
+		if (Date.now() - this.lastHeartbeat < this.heartbeatMs) return;
+		this.lastHeartbeat = Date.now();
+		try {
+			const running = [...this.tasks.values()]
+				.map((task) => `${task.id} (${clock(Date.now() - task.startedMs)})`)
+				.join(", ");
+			this.logger.bullet(`${this.tasks.size} tarefa(s) em execução: ${running}`);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Linhas do bloco (ativas + rodapé). */
+	private lines(): string[] {
+		const now = Date.now();
+		const active = [...this.tasks.values()];
+		const width = Math.max(...active.map((task) => task.id.length), 0);
+		const spinner = FRAMES[this.frame % FRAMES.length];
+		const rows = active.map(
+			(task) =>
+				`  ${spinner} ${task.id.padEnd(width)}  ${task.detail} · ${clock(now - task.startedMs)}`,
+		);
+		const finished = this.done + this.failed;
+		const failures = this.failed > 0 ? ` · ${this.failed} falha(s)` : "";
+		rows.push(
+			`  ${finished}/${this.total} concluído(s)${failures} · ${active.length} em execução`,
+		);
+		return rows;
+	}
+
+	/** Repinta o bloco no lugar (movendo o cursor para cima). */
+	private paint(): void {
+		if (!this.logger.interactive) return;
+		const lines = this.lines();
+		const stream = this.logger.stream;
+		const total = Math.max(this.rendered, lines.length);
+		if (this.rendered > 0) stream.write(`\u001b[${this.rendered}A`);
+		for (let index = 0; index < total; index++) {
+			stream.write(`\u001b[2K${lines[index] ?? ""}\n`);
+		}
+		const extra = total - lines.length;
+		if (extra > 0) stream.write(`\u001b[${extra}A`);
+		this.rendered = lines.length;
+	}
+
+	/** Apaga o bloco renderizado (deixa o cursor no início dele). */
+	private clear(): void {
+		if (!this.logger.interactive || this.rendered === 0) return;
+		const stream = this.logger.stream;
+		stream.write(`\u001b[${this.rendered}A`);
+		for (let index = 0; index < this.rendered; index++) {
+			stream.write("\u001b[2K\n");
+		}
+		stream.write(`\u001b[${this.rendered}A`);
+		this.rendered = 0;
+	}
+}

package/src/core/orchestrator.ts

@@ -39,7 +39,11 @@ import { discoverDocs } from "./doc-discoverer";
 import { Classification } from "./domain/classification";
 import { Watchdog } from "./domain/watchdog";
 import { mergeCarryover } from "./engine/carryover";
-import { ReviewScopeResolver, type RunClassification } from "./engine/review-scope";
+import {
+	ReviewScopeResolver,
+	type RunClassification,
+	type ScopeProgress,
+} from "./engine/review-scope";
 import { ENV_NAMES } from "./env";
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
 import { buildStateFromFindings, fileReader } from "./findings-state";
@@ -437,7 +441,84 @@ function budgetMessage(
 }
 
 /** Resultado do prepare — mensagens para o CLI imprimir. */
-export type PrepareResult = { messages: string[] };
+export type PrepareResult = {
+	messages: string[];
+	/** Watchdogs ativos neste ciclo (vazio em no-op/sem arquivos). */
+	activeIds: string[];
+	/** Diretório dos briefs do ciclo (ausente quando não há briefs). */
+	briefsDir?: string;
+	/** Review do ciclo (ausente quando nada foi preparado). */
+	reviewId?: string;
+};
+
+/** Etapas do prepare reportadas ao CLI (o core não escreve saída). */
+export type PrepareStage =
+	| "diff"
+	| "ast"
+	| "classify"
+	| "impact"
+	| "jev"
+	| "context"
+	| "technical"
+	| "ai-plans"
+	| "briefs"
+	| "manifest";
+
+/** Evento de progresso de uma etapa do prepare. */
+export type PrepareProgressEvent =
+	| { type: "start"; stage: PrepareStage }
+	| { type: "done"; stage: PrepareStage; durationMs: number };
+
+/** Callback de progresso do prepare (falhas do callback são ignoradas). */
+export type PrepareProgress = (event: PrepareProgressEvent) => void;
+
+/** Encaminha o progresso do escopo como etapa do prepare. */
+function scopeProgress(onProgress?: PrepareProgress): ScopeProgress | undefined {
+	if (!onProgress) return undefined;
+	return (event) => emitProgress(onProgress, event);
+}
+
+/** Emite um evento de progresso sem deixar o callback derrubar a revisão. */
+function emitProgress(
+	onProgress: PrepareProgress | undefined,
+	event: PrepareProgressEvent,
+): void {
+	try {
+		onProgress?.(event);
+	} catch {
+		// Progresso nunca derruba a revisão.
+	}
+}
+
+/** Executa uma etapa reportando início/fim (sync ou async). */
+async function runStage<T>(
+	onProgress: PrepareProgress | undefined,
+	stage: PrepareStage,
+	run: () => Promise<T> | T,
+): Promise<T> {
+	if (!onProgress) return run();
+	const started = Date.now();
+	emitProgress(onProgress, { type: "start", stage });
+	try {
+		return await run();
+	} finally {
+		emitProgress(onProgress, {
+			type: "done",
+			stage,
+			durationMs: Date.now() - started,
+		});
+	}
+}
+
+/** Como `runStage`, mas só reporta quando a etapa realmente vai rodar. */
+async function runOptionalStage<T>(
+	onProgress: PrepareProgress | undefined,
+	enabled: boolean,
+	stage: PrepareStage,
+	run: () => Promise<T> | T,
+): Promise<T> {
+	return enabled ? runStage(onProgress, stage, run) : run();
+}
 
 /**
  * Classificação fallback por IA (opcional): atribui arquivos não classificados
@@ -595,6 +676,7 @@ export async function prepare(
 	ctx: ReviewContext,
 	ast?: AstService,
 	ai?: AiClient,
+	onProgress?: PrepareProgress,
 ): Promise<PrepareResult> {
 	const messages: string[] = [];
 	ctx.work.ensure();
@@ -609,6 +691,7 @@ export async function prepare(
 		config,
 		opts.noAst ? undefined : ast,
 		ctx.git,
+		scopeProgress(onProgress),
 	).resolve(previous, headSha);
 
 	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
@@ -626,7 +709,7 @@ export async function prepare(
 				? "Nada novo a preparar — o ciclo em andamento continua; rode `--finalize` quando os findings estiverem gravados."
 				: "Nada a revisar — o relatório anterior foi mantido. Use `--full` para re-revisar.",
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 
 	const { classification, diff } = scope;
@@ -643,7 +726,7 @@ export async function prepare(
 			messages.push(
 				`Nenhuma alteração entre ${opts.base}...${opts.head} — nenhuma run criada.`,
 			);
-			return { messages };
+			return { messages, activeIds: [] };
 		}
 	}
 
@@ -661,7 +744,10 @@ export async function prepare(
 	});
 
 	const astAnalyses = scope.ast;
-	const astImpact = astAnalyses && ast ? await ast.impact(astAnalyses) : undefined;
+	const astImpact =
+		astAnalyses && ast
+			? await runStage(onProgress, "impact", () => ast.impact(astAnalyses))
+			: undefined;
 	if (astAnalyses && ast?.enabled) {
 		const summary = {
 			enabled: true,
@@ -690,7 +776,13 @@ export async function prepare(
 		}
 	}
 
-	const jev = await resolveCandidates(opts, classification, ctx, config, diff, ai);
+	const jevWillRun = Boolean(
+		(ai && !opts.noAi && new AiPreAnalyzer(ai).enabled) ||
+			(!opts.noJev && new JevClient().isConfigured()),
+	);
+	const jev = await runOptionalStage(onProgress, jevWillRun, "jev", () =>
+		resolveCandidates(opts, classification, ctx, config, diff, ai),
+	);
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
@@ -700,14 +792,14 @@ export async function prepare(
 				? `Nenhuma alteração desde a última revisão (${shortSha(classification.reviewedFrom ?? "")}).`
 				: `Nenhuma alteração entre ${opts.base}...${opts.head}.`,
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 	if (activeIds.length === 0) {
 		writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
 		messages.push(
 			"Nenhum arquivo revisável (tudo excluído, deletado ou irrelevante).",
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 	if (classification.mode === "incremental") {
 		messages.push(
@@ -716,15 +808,21 @@ export async function prepare(
 	}
 
 	persistContext(ctx);
-	const context = await resolveContextSummary(ctx, ai, opts);
-	await resolveTechnicalSummary(ctx, ai, opts, {
-		branch,
-		classification,
-		context,
-		ast: astAnalyses,
-		impact: astImpact,
-		domains: activeIds.map((id) => findWatchdog(config, id)?.name ?? id),
-	});
+	const aiContext = ai && !opts.noAi ? new AiContextSummarizer(ai).enabled : false;
+	const context = await runOptionalStage(onProgress, aiContext, "context", () =>
+		resolveContextSummary(ctx, ai, opts),
+	);
+	const aiTechnical = ai && !opts.noAi ? new AiTechnicalSummarizer(ai).enabled : false;
+	await runOptionalStage(onProgress, aiTechnical, "technical", () =>
+		resolveTechnicalSummary(ctx, ai, opts, {
+			branch,
+			classification,
+			context,
+			ast: astAnalyses,
+			impact: astImpact,
+			domains: activeIds.map((id) => findWatchdog(config, id)?.name ?? id),
+		}),
+	);
 
 	const manifestAst: ManifestAst | undefined = astAnalyses
 		? {
@@ -745,15 +843,18 @@ export async function prepare(
 			}
 		: undefined;
 
-	const aiPlans = await buildAiPlans(
-		activeIds,
-		classification,
-		config,
-		context,
-		astAnalyses,
-		astImpact,
-		ai,
-		opts,
+	const aiBriefs = ai && !opts.noAi ? new AiBriefEnricher(ai).enabled : false;
+	const aiPlans = await runOptionalStage(onProgress, aiBriefs, "ai-plans", () =>
+		buildAiPlans(
+			activeIds,
+			classification,
+			config,
+			context,
+			astAnalyses,
+			astImpact,
+			ai,
+			opts,
+		),
 	);
 	if (aiPlans.size > 0) {
 		ctx.storage.writeArtifact(ctx.review.id, {
@@ -783,30 +884,33 @@ export async function prepare(
 				}
 			: undefined;
 
-	writeBriefs(
-		activeIds,
-		classification,
-		ctx,
-		branch,
-		context,
-		jev.candidates,
-		config,
-		astAnalyses,
-		astImpact,
-		aiPlans,
+	await runStage(onProgress, "briefs", () =>
+		writeBriefs(
+			activeIds,
+			classification,
+			ctx,
+			branch,
+			context,
+			jev.candidates,
+			config,
+			astAnalyses,
+			astImpact,
+			aiPlans,
+		),
 	);
-	writeManifest(
-		ctx,
-		config,
-		opts,
-		classification,
-		activeIds,
-		activeIds,
-		jev,
-		manifestAst,
-		manifestAi,
+	await runStage(onProgress, "manifest", () =>
+		writeManifest(
+			ctx,
+			config,
+			opts,
+			classification,
+			activeIds,
+			activeIds,
+			jev,
+			manifestAst,
+			manifestAi,
+		),
 	);
-
 	messages.push(
 		...discoveryMessages(activeIds, classification, ctx.work.briefsDir),
 		...budgetMessage(classification, config),
@@ -846,7 +950,12 @@ export async function prepare(
 		"Quando os findings estiverem gravados: bun run houndsman --finalize",
 	);
 
-	return { messages };
+	return {
+		messages,
+		activeIds,
+		briefsDir: ctx.work.briefsDir,
+		reviewId: ctx.review.id,
+	};
 }
 /** Persiste o contexto da PR (bruto + resumo) como artefatos, quando existirem. */
 function persistContext(ctx: ReviewContext): void {

package/src/core/project-config.ts

@@ -13,6 +13,7 @@ import type {
 	HoundsmanAiFeatures,
 	HoundsmanAst,
 	HoundsmanConfig,
+	HoundsmanHunt,
 	HoundsmanStorage,
 	HoundsmanWorktrees,
 } from "./config";
@@ -25,6 +26,9 @@ import {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_AST_MAX_FILE_BYTES,
 	DEFAULT_AST_MAX_IMPACT_FILES,
+	DEFAULT_HUNT_CONCURRENCY,
+	DEFAULT_HUNT_RETRIES,
+	DEFAULT_HUNT_TIMEOUT_MS,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	DEFAULT_WORKTREES_LOCATION,
@@ -162,6 +166,40 @@ export class ProjectConfig<TId extends string = string> {
 		const override = this.ai.watchdogs?.[watchdogId]?.model?.trim();
 		return override && override.length > 0 ? override : this.aiModel;
 	}
+
+	/** Config do harness local (objeto vazio quando ausente). */
+	get hunt(): HoundsmanHunt {
+		return this.raw.hunt ?? {};
+	}
+
+	/** Harness local habilitado (default: ligado; sem binário é fail-closed no comando). */
+	get huntEnabled(): boolean {
+		return this.hunt.enabled !== false;
+	}
+
+	/** Processos maki simultâneos. */
+	get huntConcurrency(): number {
+		return positive(this.hunt.concurrency, DEFAULT_HUNT_CONCURRENCY);
+	}
+
+	/** Timeout por watchdog (ms). */
+	get huntTimeoutMs(): number {
+		return positive(this.hunt.timeoutMs, DEFAULT_HUNT_TIMEOUT_MS);
+	}
+
+	/** Retentativas extras (0 desliga; valores negativos caem no default). */
+	get huntRetries(): number {
+		const value = this.hunt.retries;
+		return value !== undefined && Number.isInteger(value) && value >= 0
+			? value
+			: DEFAULT_HUNT_RETRIES;
+	}
+
+	/** Modelo base do harness local (sem prefixo de provider). */
+	get huntModel(): string {
+		const value = this.hunt.model?.trim();
+		return value && value.length > 0 ? value : this.aiModel;
+	}
 }
 
 /** Inteiro positivo ou o default. */

package/src/core/storage/types.ts

@@ -110,6 +110,7 @@ export type ArtifactKind =
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
+	| "hunt"
 	| "other";
 
 /** Artefato persistido de uma review. */