@payconductor/houndsman 0.4.0 → 0.5.0

package/README.md

@@ -26,8 +26,8 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 
 - **Bun** — runtime obrigatório.
 - **git** — o diff usa `git diff <base>...<head>`.
-- Opcionais: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). A revisão
-  funciona normalmente sem eles; o `houndsman doctor` valida a credencial Jev quando presente.
+- **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
+- **`TYPESAFE_API_KEY`** (Opcional) — Env a ser informada na raiz, usada em pré-analise com JEV
 
 ### 2. Instale o CLI (global)
 
@@ -95,62 +95,38 @@ nenhum script à mão.
 
 O skill tem **4 capabilities**, todas em `/houndsman`:
 
-- **`hunt`** — revisa a PR (default: `/houndsman` = `/houndsman hunt`).
+- **`hunt`** — revisa a PR.
 - **`train`** — mantém/atualiza as regras dos watchdogs.
-- **`fix`** — corrige os findings marcados (`/houndsman fix`).
-- **`verify`** — confere se as violações foram resolvidas (`/houndsman verify`), sem re-revisar.
+- **`fix`** — corrige os findings marcados.
+- **`verify`** — confere se as violações foram resolvidas, sem re-revisar.
 
-- Revisão normal: `/houndsman` ou `/houndsman hunt` (a branch é detectada; base default `main`).
 - Revisar outra branch: `/houndsman hunt feature/minha-branch`.
-- Validar e triar na UI: `houndsman server --open` — marque os achados a executar (`execute`).
-- Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
-  `houndsman --finalize`.
-- CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
+- Validar na UI: `houndsman server --open` — marque os findings a executar (`execute`).
 
 ---
 
-## Triando os findings (opcional)
+## Validando os findings (opcional)
 
-Depois do `--finalize`, cada finding tem um `id` curto e um `fingerprint` de **conteúdo**
-no storage global. Você decide o que fazer com cada um — pela
-**UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
+Você decide o que fazer com cada finding pela **UI local**, informando se quer `Executar` ou `Ignorar`
 
 ```bash
 bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler artefatos
 ```
 
-- **decision:** `pending` · `execute` · `ignore` (+ comentário).
-- **execState:** `pending` · `in_progress` · `done` · `stale`.
-
-**Auto-fix pelo agente** — as linhas mudam depois do fix, e o motor reancora por conteúdo:
-
-```bash
-bun run houndsman findings batch --json     # grupo atual (agrupamento automático) + outros
-# ... o agente corrige apenas esse grupo ...
-bun run houndsman findings sync             # reancora por conteúdo
-bun run houndsman findings done <id>
-bun run houndsman findings verify           # confere o que resolveu (barato, sem re-revisar)
-```
-
-> A partir da 2ª revisão o `hunt` é **incremental**: revisa só os arquivos que mudaram desde
-> o último `--finalize` e **carrega** os findings dos arquivos inalterados. `--full` força
-> o review completo.
-
-> A identidade do finding é o **conteúdo** (fingerprint), não a linha: itens deslocados
-> pelo fix não se perdem. O estado mora no storage global (`<HOUNDSMAN_HOME>/houndsman.db`).
+> A partir da 2ª revisão o `hunt` é **incremental**: revisa apenas os arquivos que mudaram desde
+> a última revisão. `--full` força o review completo.
 
 ---
 
 ## Mantendo a configuração
 
 - **Persistência** → por default, SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`
-  (`HOUNDSMAN_HOME` sobrescreve o diretório de dados). Para voltar ao backend de arquivos,
-  troque só o provider — a interface `StorageProvider` é a mesma:
+  (`HOUNDSMAN_HOME` sobrescreve o diretório de dados). Caso queira storage base em arquivos, na config, troque provider para `file`:
 
   ```ts
   export const houndsmanConfig = {
     // ...
-    storage: { provider: "file", path: "./houndsman-runs" },
+    storage: { provider: "file", path: "./houndsman/runs" },
   };
   ```
 
@@ -165,8 +141,6 @@ bun run houndsman findings verify           # confere o que resolveu (barato, se
 
   O `update` reescreve **só** `.houndsman/core/**` e `.houndsman/.gitignore`. Seus arquivos
   (`watchdogs/`, `exclusions.ts`, `doc-mappings.ts`, `houndsman.config.ts`) nunca são tocados.
-- **Recomeçar a camada do zero** → `houndsman setup --force` (sobrescreve só os arquivos do
-  usuário; sem `--force` o `setup` é idempotente).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",

package/src/cli/commands/status-command.ts

@@ -0,0 +1,46 @@
+/** Comando `status` — mostra o status da run ou renova o heartbeat (`status ping`). */
+
+import { pingStatus, readStatus } from "../../core/commands/status";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+export class StatusCommand implements Command {
+	readonly name = "status";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		const action = parser.command();
+		const branch = parser.value("--branch");
+
+		if (action && action !== "ping" && action !== "show") {
+			context.err(
+				`Ação desconhecida em 'status': '${action}'. Use 'status' ou 'status ping'.`,
+			);
+			return 1;
+		}
+
+		const engine = await context.engine();
+		const result =
+			action === "ping"
+				? pingStatus(engine.storage, engine.repo, branch)
+				: readStatus(engine.storage, engine.repo, branch);
+
+		if (action === "ping") {
+			context.out(
+				result.heartbeatAt
+					? `Heartbeat atualizado — ${result.branch} · ${result.status ?? "sem status"} · ${result.heartbeatAt}`
+					: `Sem execução ativa — ${result.branch} · ${result.status ?? "sem status"}.`,
+			);
+		} else {
+			context.out(
+				[
+					`Branch: ${result.branch}`,
+					`Status: ${result.status ?? "—"}`,
+					`Heartbeat: ${result.heartbeatAt ?? "—"}`,
+					`Atualizado: ${result.updatedAt}`,
+				].join("\n"),
+			);
+		}
+		return 0;
+	}
+}

package/src/cli/help.ts

@@ -6,6 +6,7 @@ Comandos:
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
   findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
+  status [ping]       Mostra o status da run (ping renova o heartbeat da execução)
   server              Sobe a UI local de triagem (--port, --host, --open)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)

package/src/cli/index.ts

@@ -15,6 +15,7 @@
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
  *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
+ *   status [ping]        Mostra o status da run; `ping` renova o heartbeat da execução
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -38,6 +39,7 @@ import { CommandRegistry } from "./commands/registry";
 import { ReviewCommand } from "./commands/review-command";
 import { ServerCommand } from "./commands/server-command";
 import { SetupCommand, TestCommand, UpdateCommand } from "./commands/setup-command";
+import { StatusCommand } from "./commands/status-command";
 import { WatchdogCommand } from "./commands/watchdog-command";
 import { HELP } from "./help";
 
@@ -53,6 +55,7 @@ function buildRegistry(): CommandRegistry {
 		.register(new HelpCommand())
 		.register(new ContextCommand())
 		.register(new FindingsCommand())
+		.register(new StatusCommand())
 		.register(new WatchdogCommand())
 		.register(new ServerCommand())
 		.register(new SetupCommand())

package/src/core/commands/findings.ts

@@ -36,6 +36,7 @@ import {
 	type SubmitPreview,
 	type SubmitSelection,
 	submitFindings,
+	syncResolvedThreads,
 } from "../github-review";
 import { VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
@@ -214,6 +215,25 @@ function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
 	pingFindingsStatus(ctx.storage, ctx.review.id, state);
 }
 
+/**
+ * Resolve no GitHub as threads dos findings recém-resolvidos localmente.
+ * Fail-open (`gh` ausente/sem PR ⇒ só a mensagem). Devolve a linha para o
+ * output ou `null` quando não há vínculo remoto pendente.
+ */
+function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string | null {
+	if (ids.length === 0) return null;
+	const state = loadState(ctx);
+	const outcome = syncResolvedThreads({ state, ids });
+	if (outcome.checked === 0) return null;
+	if (outcome.updated.length > 0) ctx.storage.writeFindings(ctx.review.id, state);
+	if (!outcome.available) {
+		return `GitHub: threads não sincronizadas (${outcome.reason}).`;
+	}
+	const failures =
+		outcome.failed.length > 0 ? `, ${outcome.failed.length} falha(s)` : "";
+	return `GitHub: ${outcome.resolved.length} thread(s) resolvida(s), ${outcome.skipped.length} já resolvida(s)/pulada(s)${failures}.`;
+}
+
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
 	ctx: CommandContext,
@@ -309,10 +329,17 @@ function execute(
 			}
 			const finding = updateOne(ctx, input, update);
 			pingStatus(ctx, loadState(ctx));
+			const threads =
+				update.execState === "done" ? syncThreadsOutput(ctx, [finding.id]) : null;
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: `Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+					: [
+							`Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+							threads,
+						]
+							.filter(Boolean)
+							.join("\n"),
 				exitCode: 0,
 			};
 		}
@@ -320,8 +347,17 @@ function execute(
 			const ids = requireIds(parsed, "done");
 			const updated = updateMany(ctx, ids, { execState: "done" });
 			pingStatus(ctx, loadState(ctx));
+			const threads = syncThreadsOutput(
+				ctx,
+				updated.map((finding) => finding.id),
+			);
 			return {
-				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+				output: [
+					`Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+					threads,
+				]
+					.filter(Boolean)
+					.join("\n"),
 				exitCode: 0,
 			};
 		}
@@ -511,6 +547,9 @@ async function executeVerify(
 		pingStatus(ctx, current);
 	}
 
+	// Resolvidos localmente ⇒ resolve as conversas correspondentes no PR.
+	const threads = syncThreadsOutput(ctx, applied);
+
 	const output = parsed.bools.has("--json")
 		? JSON.stringify(
 				{
@@ -534,6 +573,7 @@ async function executeVerify(
 				parsed.bools.has("--apply")
 					? `Aplicados (done): ${applied.length > 0 ? applied.join(", ") : "—"}.`
 					: "",
+				threads,
 			]
 				.filter(Boolean)
 				.join("\n");
@@ -603,6 +643,21 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 		"",
 		`Enviados: ${outcome.posted.length} · Falhas: ${outcome.failed.length} · Pulados: ${outcome.skipped.length}`,
 	];
+	const review = outcome.review;
+	if (review?.id !== undefined) {
+		const target = review.url ? ` — ${review.url}` : "";
+		if (review.created) {
+			const status = review.finalized
+				? `finalizada (${review.event})`
+				: "criada, mas não finalizada";
+			lines.push(`Revisão #${review.id} ${status}${target}`);
+		} else {
+			lines.push(
+				`Comentários adicionados à revisão pendente #${review.id}${target}`,
+			);
+		}
+	}
+	if (review?.error) lines.push(`Revisão: ❌ ${review.error}`);
 	if (outcome.general) {
 		lines.push(
 			`Comentário geral: ${outcome.general.url ?? outcome.general.commentId} (${outcome.general.ids.length})`,
@@ -615,8 +670,9 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 }
 
 /**
- * Subcomando `findings submit` — envia os findings selecionados como comentários
- * na PR (via `gh`). `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
+ * Subcomando `findings submit` — envia os findings selecionados numa revisão da
+ * PR (via `gh`): reaproveita a revisão pendente ou cria/finaliza uma nova.
+ * `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
  */
 export async function runSubmitCommand(
 	config: HoundsmanConfig,
@@ -664,6 +720,6 @@ async function executeSubmit(
 
 	return {
 		output: renderSubmitOutcome(outcome, json),
-		exitCode: outcome.failed.length > 0 ? 1 : 0,
+		exitCode: outcome.failed.length > 0 || Boolean(outcome.review?.error) ? 1 : 0,
 	};
 }

package/src/core/commands/status.ts

@@ -0,0 +1,63 @@
+/**
+ * Status da run (biblioteca) — leitura e heartbeat para a UI.
+ *
+ * `status ping` é o sinal de vida de uma skill em execução (revisão ou
+ * correção). O heartbeat é separado de `updatedAt`: triagem/sync atualizam o
+ * segundo, mas não fingem que existe uma execução em andamento.
+ */
+
+import { currentBranch } from "../pr-context";
+import { type RunStatus, touchRunStatus } from "../run-status";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+
+export type StatusResult = {
+	branch: string;
+	status: RunStatus | null;
+	startedAt?: string;
+	heartbeatAt?: string;
+	updatedAt: string;
+};
+
+function toResult(review: ReviewRecord): StatusResult {
+	return {
+		branch: review.branch,
+		status: review.status,
+		startedAt: review.startedAt,
+		heartbeatAt: review.heartbeatAt,
+		updatedAt: review.updatedAt,
+	};
+}
+
+/** Resolve a review da branch (explícita ou a atual do git). */
+function findReview(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): ReviewRecord {
+	const target = branch ?? currentBranch();
+	const review = storage.findReview(repo.key, target);
+	if (!review) {
+		throw new Error(`Nenhuma revisão para '${target}'.`);
+	}
+	return review;
+}
+
+/** Lê o status atual da run. */
+export function readStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): StatusResult {
+	return toResult(findReview(storage, repo, branch));
+}
+
+/** Renova o heartbeat de uma execução ativa (`reviewing`/`fixing`). */
+export function pingStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+	now?: string,
+): StatusResult {
+	const review = findReview(storage, repo, branch);
+	return toResult(touchRunStatus(storage, review.id, now));
+}

package/src/core/engine/review-scope.ts

@@ -34,12 +34,21 @@ export type RunClassification = ClassificationResult & {
 	carryover?: MergedFinding[];
 };
 
-/** Resultado da resolução de escopo. */
-export type ReviewScope = {
-	classification: RunClassification;
-	diff: DiffSource;
-	reviewedFrom?: string;
-};
+/** Resultado da resolução de escopo: revisar ou nada a fazer. */
+export type ReviewScope =
+	| {
+			/** O `HEAD` é o mesmo commit já revisado — não há o que re-revisar. */
+			kind: "noop";
+			headSha: string;
+			/** Commit já coberto pelo review anterior. */
+			reviewedFrom: string;
+	  }
+	| {
+			kind: "review";
+			classification: RunClassification;
+			diff: DiffSource;
+			reviewedFrom?: string;
+	  };
 
 /** Decide entre review completo e incremental. */
 export class ReviewScopeResolver {
@@ -52,20 +61,29 @@ export class ReviewScopeResolver {
 	}
 
 	/**
+	 * No-op quando o `HEAD` é exatamente o commit já revisado (sem
+	 * `--full`/`--clean`): re-revisar a PR inteira seria desperdício, e o
+	 * relatório anterior continua válido.
+	 *
 	 * Incremental só quando há um `reviewed.headSha` anterior, o `HEAD` atual o
 	 * sucede (sem rebase) e não veio `--full`/`--clean`.
 	 */
 	resolve(previous: FindingsStateFile | null, headSha: string): ReviewScope {
 		const prevSha = previous?.reviewed?.headSha;
+
+		if (!this.options.full && !this.options.clean && prevSha === headSha) {
+			return { kind: "noop", headSha, reviewedFrom: headSha };
+		}
+
 		if (
 			this.options.full ||
 			this.options.clean ||
 			!prevSha ||
-			prevSha === headSha ||
 			!isAncestor(prevSha, headSha)
 		) {
 			const diff = collectDiff(this.options.base, this.options.head);
 			return {
+				kind: "review",
 				diff,
 				classification: {
 					...this.classifier
@@ -90,6 +108,6 @@ export class ReviewScopeResolver {
 			reviewedFrom: prevSha,
 			carryover: buildCarryover(previous, changedPaths),
 		};
-		return { classification, diff, reviewedFrom: prevSha };
+		return { kind: "review", classification, diff, reviewedFrom: prevSha };
 	}
 }

package/src/core/findings-state.ts

@@ -76,6 +76,10 @@ export type GitHubLink = {
 	pr: number;
 	/** Quando foi enviado (ISO). */
 	at: string;
+	/** Node ID da thread de revisão (GraphQL) — base para resolver a conversa. */
+	threadId?: string;
+	/** Quando a thread foi marcada como resolvida no GitHub (ISO). */
+	resolvedAt?: string;
 };
 
 /** Marco da revisão que originou o estado: commit revisado + quando. */
@@ -283,6 +287,12 @@ export type BuildStateOptions = {
 	reviewed?: FindingsReviewed;
 	/** SHA usado para carimbar `foundAtSha` de findings novos/re-reportados. */
 	headSha?: string;
+	/**
+	 * Arquivos efetivamente revisados neste ciclo (união de `reviewedFiles`).
+	 * Quando presente, só findings ausentes desses arquivos viram `done` — o que
+	 * ficou fora do orçamento/skipped não pode ser dado como resolvido.
+	 */
+	reviewedPaths?: ReadonlySet<string>;
 	now?: string;
 };
 
@@ -303,14 +313,21 @@ export function buildStateFromFindings(
 
 	const result: Record<string, FindingState> = {};
 	// 1. Preserva o estado anterior (marca como ausente até provar o contrário).
+	const reviewedPaths = options.reviewedPaths;
 	for (const prev of Object.values(previous?.findings ?? {})) {
+		// Ausente do novo relatório ⇒ corrigido manualmente entre revisões (ou
+		// some junto com o trecho): vira `done`. `ignore` é decisão explícita de
+		// não corrigir — preserva o estado original. Arquivo fora da revisão
+		// (orçamento/skipped) também preserva: ausência não prova resolução.
+		const wasReviewed = !reviewedPaths || reviewedPaths.has(prev.file);
+		const resolvedByReview =
+			wasReviewed && prev.present && prev.decision !== "ignore";
+		const queuedAndGone =
+			wasReviewed && prev.decision === "execute" && prev.execState === "pending";
 		result[prev.id] = {
 			...prev,
 			present: false,
-			execState:
-				prev.execState === "pending" && prev.decision === "execute"
-					? "done"
-					: prev.execState,
+			execState: resolvedByReview || queuedAndGone ? "done" : prev.execState,
 			updatedAt: now,
 		};
 	}