@payconductor/houndsman 0.3.0 → 0.4.0

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/ArtifactsPanel.tsx

@@ -1,48 +1,162 @@
 /**
- * Painel de artefatos: abas para ver o conteúdo bruto dos arquivos da run.
+ * Painel de artefatos: lista todos os artefatos persistidos da run e renderiza
+ * o conteúdo bruto. JSON ganha destaque de sintaxe; briefs e relatórios são
+ * auditáveis pela mesma navegação.
  */
 
-import { useEffect, useState } from "preact/hooks";
-import { ARTIFACT_INFO, ARTIFACTS, type ArtifactName } from "./constants";
+import { useEffect, useMemo, useState } from "preact/hooks";
+import { api } from "./api";
+import {
+	ARTIFACT_KIND_LABELS,
+	describeArtifact,
+	displayArtifactName,
+	groupArtifacts,
+	isJsonArtifact,
+} from "./constants";
+import { formatJson, highlightJson } from "./json-highlight";
+import type { ArtifactMeta } from "./types";
+
+/** Prefere o relatório consolidado; senão, o primeiro artefato disponível. */
+function pickDefault(items: ArtifactMeta[]): string {
+	return (items.find((item) => item.name === "review.md") ?? items[0])?.name ?? "";
+}
+
+/** JSON com destaque de sintaxe (tokens em spans, sem lib externa). */
+function JsonView({ content }: { content: string }) {
+	const tokens = useMemo(() => highlightJson(formatJson(content)), [content]);
+	return (
+		<pre class="artifact-view json-view">
+			{tokens.map((token) => (
+				<span class={token.type === "plain" ? undefined : `json-${token.type}`}>
+					{token.text}
+				</span>
+			))}
+		</pre>
+	);
+}
 
 export function ArtifactsPanel({ slug }: { slug: string }) {
-	const [name, setName] = useState<ArtifactName>(ARTIFACTS[0]);
+	const [items, setItems] = useState<ArtifactMeta[]>([]);
+	const [name, setName] = useState("");
 	const [content, setContent] = useState("");
 	const [error, setError] = useState("");
+	const [loading, setLoading] = useState(false);
+
+	useEffect(() => {
+		let cancelled = false;
+		setError("");
+		api<{ artifacts: ArtifactMeta[] }>(`/api/runs/${slug}/artifacts`)
+			.then(({ artifacts }) => {
+				if (cancelled) return;
+				setItems(artifacts);
+				setName((current) =>
+					artifacts.some((item) => item.name === current)
+						? current
+						: pickDefault(artifacts),
+				);
+			})
+			.catch((err) => {
+				if (cancelled) return;
+				setItems([]);
+				setName("");
+				setError(String(err));
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, [slug]);
 
 	useEffect(() => {
+		if (!name) {
+			setContent("");
+			return;
+		}
+		let cancelled = false;
+		setLoading(true);
 		setError("");
-		fetch(`/api/runs/${slug}/artifacts/${name}`)
+		fetch(`/api/runs/${slug}/artifacts/${encodeURI(name)}`)
 			.then(async (res) => {
 				if (!res.ok) throw new Error(`HTTP ${res.status}`);
-				setContent(await res.text());
+				const text = await res.text();
+				if (!cancelled) setContent(text);
 			})
 			.catch((err) => {
+				if (cancelled) return;
 				setContent("");
 				setError(String(err));
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
 			});
+		return () => {
+			cancelled = true;
+		};
 	}, [slug, name]);
 
+	const groups = useMemo(() => groupArtifacts(items), [items]);
+	const selected = useMemo(
+		() => items.find((item) => item.name === name),
+		[items, name],
+	);
+
 	return (
 		<div class="artifacts">
-			<div class="artifact-tabs">
-				{ARTIFACTS.map((artifact) => (
-					<button
-						type="button"
-						title={ARTIFACT_INFO[artifact]}
-						class={`chip${artifact === name ? " active" : ""}`}
-						onClick={() => setName(artifact)}
-					>
-						{artifact}
-					</button>
-				))}
+			<div class="artifact-layout">
+				<nav class="artifact-list" aria-label="Artefatos da revisão">
+					{groups.map((group) => (
+						<div class="artifact-group" key={group.key}>
+							<p class="artifact-group-label">{group.label}</p>
+							{group.items.map((item) => (
+								<button
+									type="button"
+									key={item.name}
+									title={item.name}
+									class={`artifact-item${item.name === name ? " active" : ""}`}
+									onClick={() => setName(item.name)}
+								>
+									<span class="artifact-item-name">
+										{displayArtifactName(item)}
+									</span>
+									<span class="artifact-item-kind">
+										{ARTIFACT_KIND_LABELS[item.kind] ?? item.kind}
+									</span>
+								</button>
+							))}
+						</div>
+					))}
+					{items.length === 0 && !loading && (
+						<p class="empty">Nenhum artefato persistido nesta run.</p>
+					)}
+				</nav>
+
+				<section class="artifact-pane">
+					{selected ? (
+						<header class="artifact-head">
+							<div>
+								<h3 class="artifact-title">{selected.name}</h3>
+								<p class="artifact-desc">{describeArtifact(selected)}</p>
+							</div>
+							<span class="artifact-kind-badge">
+								{ARTIFACT_KIND_LABELS[selected.kind] ?? selected.kind}
+							</span>
+						</header>
+					) : null}
+
+					{error ? (
+						<p class="error">{error}</p>
+					) : loading ? (
+						<p class="empty">Carregando artefato…</p>
+					) : selected ? (
+						isJsonArtifact(selected) ? (
+							<JsonView content={content} />
+						) : (
+							<pre class="artifact-view">{content || "—"}</pre>
+						)
+					) : (
+						<p class="empty">Selecione um artefato para visualizar.</p>
+					)}
+				</section>
 			</div>
-			<p class="artifact-desc">{ARTIFACT_INFO[name]}</p>
-			{error ? (
-				<p class="error">{error}</p>
-			) : (
-				<pre class="artifact-view">{content}</pre>
-			)}
 		</div>
 	);
 }

package/src/server/client/FindingCard.tsx

@@ -6,8 +6,9 @@
  * poluição visual da triagem; reabrir volta a expandir.
  */
 
-import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { api } from "./api";
+import { highlightCode, languageFromFile } from "./code-highlight";
 import { DECISION_LABELS, DECISIONS, SEVERITY_LABELS } from "./constants";
 import { vscodeFileLink } from "./format";
 import {
@@ -19,6 +20,7 @@ import {
 	Spinner,
 	Watch,
 } from "./icons";
+import { MarkdownText } from "./MarkdownText";
 import type { Finding } from "./types";
 
 /** Debounce do auto-save do comentário (ms). */
@@ -102,6 +104,13 @@ export function FindingCard({
 
 	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
 	const href = finding.absFile ? vscodeFileLink(finding.absFile, finding.line) : null;
+	const highlighted = useMemo(
+		() =>
+			finding.evidence
+				? highlightCode(finding.evidence, languageFromFile(finding.file))
+				: null,
+		[finding.evidence, finding.file],
+	);
 	const toggle = () => setOpen((current) => !current);
 
 	return (
@@ -186,14 +195,36 @@ export function FindingCard({
 					<div class="meta-row">{finding.rule}</div>
 
 					<div class="action-block">
-						<p>
-							<Sparkles size={16} class="action-icon" />
+						<Sparkles size={16} class="action-icon" />
+						<div class="action-text">
 							<span class="action-label">Ação:</span>
-							{finding.action}
-						</p>
+							<MarkdownText text={finding.action} />
+						</div>
 					</div>
 
-					{finding.evidence && <pre class="evidence">{finding.evidence}</pre>}
+					{finding.evidence &&
+						(highlighted ? (
+							<div class="evidence-block">
+								<div class="evidence-head">
+									<span class="code-lang">{highlighted.label}</span>
+								</div>
+								<pre class="evidence code-evidence">
+									{highlighted.tokens.map((token) => (
+										<span
+											class={
+												token.type === "plain"
+													? undefined
+													: `tok-${token.type}`
+											}
+										>
+											{token.text}
+										</span>
+									))}
+								</pre>
+							</div>
+						) : (
+							<pre class="evidence">{finding.evidence}</pre>
+						))}
 
 					<div class="decision-tags-block">
 						<div class="decisions">