@payconductor/houndsman 0.3.0 → 0.5.0

package/src/core/storage/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Contrato de persistência do houndsman (biblioteca).
+ *
+ * Tudo que hoje é "run" (reviews, findings, artefatos) passa por aqui. As
+ * implementações (`SQLiteStorageProvider` e `FileStorageProvider`) compartilham
+ * esta interface — trocar o backend é só trocar a config.
+ */
+
+import type { FindingsStateFile } from "../findings-state";
+
+/** Estados de execução de uma run. */
+export type ReviewStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+
+/** Identidade estável de um repositório (remote normalizado ou raiz git). */
+export type RepoIdentity = {
+	/** Chave usada para escopar as runs (`remote:<...>` ou `path:<...>`). */
+	key: string;
+	/** Raiz absoluta do repositório no disco. */
+	root: string;
+	/** Remote `origin` cru, quando existir. */
+	remote?: string;
+};
+
+/** Registro de uma revisão (run de uma branch). */
+export type ReviewRecord = {
+	id: string;
+	repoKey: string;
+	repoRoot: string;
+	repoRemote?: string;
+	branch: string;
+	slug: string;
+	base?: string;
+	head?: string;
+	headSha?: string;
+	reviewedSha?: string;
+	reviewedAt?: string;
+	status: ReviewStatus | null;
+	startedAt?: string;
+	/**
+	 * Último sinal de vida de uma execução ativa (`reviewing`/`fixing`).
+	 * Diferente de `updatedAt`: não muda com triagem/sync — só com a execução.
+	 */
+	heartbeatAt?: string;
+	createdAt: string;
+	updatedAt: string;
+};
+
+/** Campos mutáveis de uma review (os demais são identidade). */
+export type ReviewPatch = Partial<
+	Pick<
+		ReviewRecord,
+		| "branch"
+		| "slug"
+		| "base"
+		| "head"
+		| "headSha"
+		| "reviewedSha"
+		| "reviewedAt"
+		| "status"
+		| "startedAt"
+		| "heartbeatAt"
+		| "updatedAt"
+	>
+> & {
+	/** Reinicia o `startedAt` no início de um novo ciclo de revisão. */
+	resetStartedAt?: boolean;
+	/** Limpa o heartbeat (execução terminou). */
+	resetHeartbeat?: boolean;
+};
+
+/** Entrada de `getOrCreateReview`. */
+export type CreateReviewInput = {
+	repo: RepoIdentity;
+	branch: string;
+	slug: string;
+	base?: string;
+	head?: string;
+	now?: string;
+};
+
+/** Espécie de artefato (orienta a UI e o manifesto). */
+export type ArtifactKind =
+	| "brief"
+	| "classification"
+	| "manifest"
+	| "candidates"
+	| "context"
+	| "context-brief"
+	| "context-summary"
+	| "finding-report"
+	| "review"
+	| "resume"
+	| "domain-review"
+	| "verify"
+	| "other";
+
+/** Artefato persistido de uma review. */
+export type ArtifactRecord = {
+	id: string;
+	reviewId: string;
+	name: string;
+	kind: ArtifactKind;
+	content: string;
+	contentType: string;
+	createdAt: string;
+	updatedAt: string;
+};
+
+/** Entrada de `writeArtifact`. */
+export type WriteArtifactInput = {
+	name: string;
+	kind: ArtifactKind;
+	content: string;
+	contentType?: string;
+};
+
+/**
+ * Persistência síncrona de reviews, findings e artefatos.
+ *
+ * Síncrona de propósito: `bun:sqlite` e o filesystem são síncronos, e o motor
+ * inteiro já trabalha nesse modelo.
+ */
+export interface StorageProvider {
+	readonly kind: "sqlite" | "file";
+
+	/** Recupera ou cria a review de uma branch (identidade = repo + branch). */
+	getOrCreateReview(input: CreateReviewInput): ReviewRecord;
+	findReview(repoKey: string, branch: string): ReviewRecord | null;
+	getReview(id: string): ReviewRecord | null;
+	/** Reviews do repositório (mais recentes primeiro); sem chave = todas. */
+	listReviews(repoKey?: string): ReviewRecord[];
+	updateReview(id: string, patch: ReviewPatch): ReviewRecord | null;
+	deleteReview(id: string): void;
+
+	/** Estado de triagem completo; null se a review ainda não tem findings. */
+	readFindings(reviewId: string): FindingsStateFile | null;
+	/** Substitui o estado de triagem (transacional no SQLite). */
+	writeFindings(reviewId: string, state: FindingsStateFile): void;
+
+	readArtifact(reviewId: string, name: string): ArtifactRecord | null;
+	writeArtifact(reviewId: string, input: WriteArtifactInput): ArtifactRecord;
+	listArtifacts(reviewId: string): ArtifactRecord[];
+	deleteArtifact(reviewId: string, name: string): void;
+
+	/** Manutenção do backend (SQLite: `PRAGMA optimize` + `VACUUM`). */
+	maintain(): void;
+
+	/** Referência legível do armazenamento de uma review (diagnóstico/logs). */
+	location(reviewId: string): string;
+
+	close(): void;
+}

package/src/core/storage/work-area.ts

@@ -0,0 +1,191 @@
+/**
+ * Área de trabalho (staging) de uma review — biblioteca.
+ *
+ * O banco é a fonte de verdade de reviews/findings/artefatos. Este diretório
+ * guarda só o que os subagentes leem e escrevem: briefs, findings brutos e o
+ * contexto da PR. Vive em `<HOUNDSMAN_HOME>/work/<reviewId>/` e é limpo após o
+ * `finalize`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	CONTEXT_BRIEF_FILE,
+	CONTEXT_FILE,
+	CONTEXT_SUMMARY_FILE,
+	displayPath,
+} from "../paths";
+import type { ContextPaths } from "../pr-context";
+import {
+	type ContextSummary,
+	parseContextSummary,
+	parseWatchdogReport,
+	type WatchdogReport,
+} from "../report-builder";
+import { systemClock } from "../services/clock";
+import { workRoot } from "./paths";
+import type { ReviewRecord } from "./types";
+
+export type { ContextPaths };
+
+/** Resultado da leitura dos findings brutos de uma rodada. */
+export type FindingsIngest = {
+	reports: WatchdogReport[];
+	pending: string[];
+	warnings: string[];
+};
+
+/** Staging de uma review (briefs/findings/contexto). */
+export class ReviewWorkArea {
+	readonly review: ReviewRecord;
+	readonly root: string;
+
+	constructor(review: ReviewRecord, base: string = workRoot()) {
+		this.review = review;
+		this.root = join(base, review.id);
+	}
+
+	get branch(): string {
+		return this.review.branch;
+	}
+
+	get slug(): string {
+		return this.review.slug;
+	}
+
+	get briefsDir(): string {
+		return join(this.root, "briefs");
+	}
+
+	get findingsDir(): string {
+		return join(this.root, "findings");
+	}
+
+	/** Caminho de um arquivo dentro da área de trabalho. */
+	file(name: string): string {
+		return join(this.root, name);
+	}
+
+	briefFile(id: string): string {
+		return join(this.briefsDir, `${id}.md`);
+	}
+
+	findingFile(id: string): string {
+		return join(this.findingsDir, `${id}.json`);
+	}
+
+	get contextPaths(): ContextPaths {
+		return {
+			dir: this.root,
+			context: this.file(CONTEXT_FILE),
+			summary: this.file(CONTEXT_SUMMARY_FILE),
+			brief: this.file(CONTEXT_BRIEF_FILE),
+		};
+	}
+
+	/** Garante os diretórios; `clean` recria a área do zero. */
+	ensure(clean = false): void {
+		if (clean) this.clean();
+		mkdirSync(this.briefsDir, { recursive: true });
+		mkdirSync(this.findingsDir, { recursive: true });
+	}
+
+	/** Remove todo o staging da review. */
+	clean(): void {
+		rmSync(this.root, { recursive: true, force: true });
+	}
+
+	/** Remove só os findings brutos (equivalente ao antigo `--clean`). */
+	cleanFindings(): void {
+		rmSync(this.findingsDir, { recursive: true, force: true });
+		mkdirSync(this.findingsDir, { recursive: true });
+	}
+
+	writeBrief(id: string, content: string): void {
+		mkdirSync(this.briefsDir, { recursive: true });
+		writeFileSync(this.briefFile(id), content);
+	}
+
+	writeContext(context: unknown, brief: string): void {
+		mkdirSync(this.root, { recursive: true });
+		writeFileSync(this.contextPaths.context, `${JSON.stringify(context, null, 2)}\n`);
+		writeFileSync(this.contextPaths.brief, `${brief}\n`);
+	}
+
+	/** Finds brutos gravados pelos subagentes (um JSON por watchdog). */
+	readFindings(activeIds: string[]): FindingsIngest {
+		const reports: WatchdogReport[] = [];
+		const pending: string[] = [];
+		const warnings: string[] = [];
+		for (const id of activeIds) {
+			const path = this.findingFile(id);
+			if (!existsSync(path)) {
+				pending.push(id);
+				continue;
+			}
+			try {
+				const raw = JSON.parse(readFileSync(path, "utf8"));
+				const report = parseWatchdogReport(raw, path, (message) =>
+					warnings.push(message),
+				);
+				if (report) reports.push(report);
+				else pending.push(id);
+			} catch (err) {
+				warnings.push(
+					`[houndsman] ${displayPath(path)} inválido: ${err instanceof Error ? err.message : err}`,
+				);
+				pending.push(id);
+			}
+		}
+		return { reports, pending, warnings };
+	}
+
+	/** Resumo do contexto gravado pelo subagente (null se ausente/inválido). */
+	readContextSummary(): ContextSummary | null {
+		const path = this.contextPaths.summary;
+		if (!existsSync(path)) return null;
+		try {
+			return parseContextSummary(JSON.parse(readFileSync(path, "utf8")));
+		} catch {
+			return null;
+		}
+	}
+
+	/** Conteúdo cru do resumo (para persistir como artefato). */
+	readContextSummaryRaw(): string | null {
+		const path = this.contextPaths.summary;
+		if (!existsSync(path)) return null;
+		try {
+			return readFileSync(path, "utf8");
+		} catch {
+			return null;
+		}
+	}
+
+	/** Contexto bruto da PR (para persistir como artefato). */
+	readContextRaw(): string | null {
+		const path = this.contextPaths.context;
+		if (!existsSync(path)) return null;
+		try {
+			return readFileSync(path, "utf8");
+		} catch {
+			return null;
+		}
+	}
+
+	/** Brief do subagente de contexto (para persistir como artefato). */
+	readContextBriefRaw(): string | null {
+		const path = this.contextPaths.brief;
+		if (!existsSync(path)) return null;
+		try {
+			return readFileSync(path, "utf8");
+		} catch {
+			return null;
+		}
+	}
+
+	/** Toque de `updatedAt` (diagnóstico). */
+	touch(): string {
+		return systemClock();
+	}
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export type {
 	HoundsmanConcurrency,
 	HoundsmanConfig,
 	HoundsmanConfigInput,
+	HoundsmanStorage,
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
@@ -75,6 +76,7 @@ export type {
 	FindingDecision,
 	FindingExecState,
 	FindingHistoryEntry,
+	FindingIdResolution,
 	FindingState,
 	FindingsFilter,
 	FindingsStateFile,
@@ -85,7 +87,6 @@ export type {
 export {
 	applyFindingUpdate,
 	buildStateFromFindings,
-	buildStateFromRunDir,
 	compareFindings,
 	emptyState,
 	FINDING_DECISIONS,
@@ -99,20 +100,18 @@ export {
 	filterFindings,
 	newFindingId,
 	reorder,
-	runDir,
-	stateFile,
+	resolveFindingId,
 	summarize,
 	syncState,
 } from "./core/findings-state";
 export type { GitResult, GitRunner } from "./core/git-runner";
 export {
-	ARTIFACT_DIR,
 	CORE_DIR,
 	CORE_SKILL_DIR,
+	displayPath,
 	OUTPUT_FORMAT_PATH,
 	PROJECT_DIR,
 	relFromRoot,
-	STATE_FILE,
 } from "./core/paths";
 export { ProjectConfig } from "./core/project-config";
 export { checkRegistry } from "./core/registry-check";
@@ -121,7 +120,6 @@ export { ManifestWriter } from "./core/renderers/manifest-writer";
 export { ReportRenderer } from "./core/renderers/report-renderer";
 export type { DomainReport } from "./core/report-builder";
 export { renderDomainReport } from "./core/report-builder";
-export { RunLayout } from "./core/run-layout";
 export type { Clock } from "./core/services/clock";
 export { systemClock } from "./core/services/clock";
 export { FileClassifier } from "./core/services/file-classifier";
@@ -131,6 +129,29 @@ export { GhClient } from "./core/services/gh-client";
 export { GitRepository } from "./core/services/git-repository";
 export { ProjectFiles } from "./core/services/project-files";
 export { Verifier } from "./core/services/verifier";
+export {
+	createMemoryStorage,
+	createStorage,
+} from "./core/storage/factory";
+export { FileStorageProvider } from "./core/storage/file/file-storage";
+export {
+	buildRepoIdentity,
+	normalizeRemote,
+	resolveRepoIdentity,
+} from "./core/storage/repo-identity";
+export { SQLiteStorageProvider } from "./core/storage/sqlite/sqlite-storage";
+export type {
+	ArtifactKind,
+	ArtifactRecord,
+	CreateReviewInput,
+	RepoIdentity,
+	ReviewPatch,
+	ReviewRecord,
+	ReviewStatus,
+	StorageProvider,
+	WriteArtifactInput,
+} from "./core/storage/types";
+export { ReviewWorkArea } from "./core/storage/work-area";
 export type {
 	ChurnMap,
 	ClassifyRule,

package/src/server/artifacts.ts

@@ -1,67 +1,14 @@
 /**
- * Descoberta de runs e leitura segura de artefatos (servidor).
+ * Validação do slug da run (`branch-slug`) usado nas URLs do servidor.
  *
- * Toda leitura é restrita à pasta da run — `readRunFile` barra path traversal.
+ * Os dados vivem no storage global; a única preocupação restante aqui é barrar
+ * slugs malformados antes de consultar o provider.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+/** Slugs aceitos: letras, números, ponto, underscore e hífen. */
+const SLUG_PATTERN = /^[a-zA-Z0-9._-]+$/;
 
-/** Arquivos que marcam uma pasta como "run" do houndsman. */
-const RUN_MARKERS = [
-	"manifest.json",
-	"state.json",
-	"run.json",
-	"classification.json",
-	"review.md",
-] as const;
-
-/** Slugs (nomes de pasta) das runs sob o `artifactDir`. */
-export function listRunSlugs(artifactDir: string): string[] {
-	if (!existsSync(artifactDir)) return [];
-	try {
-		return readdirSync(artifactDir, { withFileTypes: true })
-			.filter((entry) => entry.isDirectory())
-			.map((entry) => entry.name)
-			.filter((slug) =>
-				RUN_MARKERS.some((marker) => existsSync(join(artifactDir, slug, marker))),
-			)
-			.sort();
-	} catch {
-		return [];
-	}
-}
-
-/** Diretório absoluto de uma run; null se o slug for inválido/inexistente. */
-export function runDirForSlug(artifactDir: string, slug: string): string | null {
-	if (!/^[a-zA-Z0-9._-]+$/.test(slug)) return null;
-	const dir = join(artifactDir, slug);
-	if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
-	return dir;
-}
-
-/** Lê um arquivo DENTRO da run; null se ausente ou fora do diretório. */
-export function readRunFile(runDir: string, name: string): string | null {
-	const root = resolve(runDir);
-	const target = resolve(root, name);
-	const rel = relative(root, target);
-	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
-	try {
-		return existsSync(target) && statSync(target).isFile()
-			? readFileSync(target, "utf8")
-			: null;
-	} catch {
-		return null;
-	}
-}
-
-/** Lê e faz parse de um JSON da run (null se ausente/inválido). */
-export function readRunJson<T>(runDir: string, name: string): T | null {
-	const raw = readRunFile(runDir, name);
-	if (raw === null) return null;
-	try {
-		return JSON.parse(raw) as T;
-	} catch {
-		return null;
-	}
+/** `true` se o slug é seguro/plausível. */
+export function isSlug(value: string): boolean {
+	return SLUG_PATTERN.test(value);
 }

package/src/server/client/App.tsx

@@ -1,25 +1,31 @@
 /**
  * App: layout do servidor — sidebar de execuções, header fixo (abas segmentadas,
- * auto-refresh e reancoragem), KPIs, filtros e os painéis de findings/artefatos.
- * Concentra o estado e as chamadas à API.
+ * auto-refresh e reancoragem), KPIs, filtros e os painéis de resumo/findings/
+ * artefatos. Concentra o estado e as chamadas à API.
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { ArtifactsPanel } from "./ArtifactsPanel";
 import { AutoRefresh } from "./AutoRefresh";
-import { api, computeSummary } from "./api";
-import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./constants";
 import { Filters, type FiltersState } from "./Filters";
 import { FindingsList } from "./FindingsList";
-import { Layers, ListIcon, Refresh, Send } from "./icons";
+import { FileText, Layers, ListIcon, Refresh, Send } from "./icons";
+import { ResumePanel } from "./ResumePanel";
 import { RunList } from "./RunList";
 import { SubmitModal } from "./SubmitModal";
 import { SummaryBar } from "./SummaryBar";
-import type { Finding, FindingsResponse, RunSummary } from "./types";
+import { api, computeSummary } from "./utils/api";
+import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./utils/constants";
+import type { Finding, FindingsResponse, RunSummary } from "./utils/types";
 
-type Tab = "findings" | "artifacts";
+type Tab = "resume" | "findings" | "artifacts";
 
 const TABS: { id: Tab; label: string; hint: string }[] = [
+	{
+		id: "resume",
+		label: "Resumo",
+		hint: "Visão principal da revisão: negócio, números e pontos técnicos",
+	},
 	{
 		id: "findings",
 		label: "Findings",
@@ -36,7 +42,7 @@ export function App() {
 	const [runs, setRuns] = useState<RunSummary[]>([]);
 	const [slug, setSlug] = useState<string | null>(null);
 	const [data, setData] = useState<FindingsResponse | null>(null);
-	const [tab, setTab] = useState<Tab>("findings");
+	const [tab, setTab] = useState<Tab>("resume");
 	const [filters, setFilters] = useState<FiltersState>({
 		query: "",
 		decision: "all",
@@ -200,7 +206,9 @@ export function App() {
 								class={`seg-btn${tab === item.id ? " active" : ""}`}
 								onClick={() => setTab(item.id)}
 							>
-								{item.id === "findings" ? (
+								{item.id === "resume" ? (
+									<FileText size={15} />
+								) : item.id === "findings" ? (
 									<ListIcon size={15} />
 								) : (
 									<Layers size={15} />
@@ -254,6 +262,15 @@ export function App() {
 					</div>
 					{error && <p class="error">{error}</p>}
 
+					{slug && tab === "resume" && data && (
+						<ResumePanel
+							slug={slug}
+							branch={branch}
+							findings={data.findings}
+							summary={summary}
+							onOpenArtifacts={() => setTab("artifacts")}
+						/>
+					)}
 					{slug && tab === "findings" && data && (
 						<>
 							<SummaryBar summary={summary} />