@payconductor/houndsman 0.2.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/core/verify.ts

@@ -19,6 +19,7 @@ import {
 	type FindingsStateFile,
 	filterFindings,
 } from "./findings-state";
+import { systemClock } from "./services/clock";
 import type { Severity } from "./types";
 
 /** Resultado da verificação de um finding. */
@@ -160,7 +161,7 @@ export function summarizeVerify(entries: readonly VerifyEntry[]): VerifySummary
 export function applyResolutions(
 	state: FindingsStateFile,
 	entries: readonly VerifyEntry[],
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): string[] {
 	const changed: string[] = [];
 	for (const entry of entries) {

package/src/core/watchdog-registry.ts

@@ -1,18 +1,70 @@
 /**
- * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
+ * Registry de watchdogs (biblioteca) — acesso tipado ao `HoundsmanConfig`.
  *
- * O motor não conhece ids concretos — tudo chega via `config`.
+ * O motor não conhece ids concretos: o registry resolve definições, contexto e
+ * casamento de arquivos por domínio. As funções antigas continuam como
+ * adaptadores para a API pública.
  */
 
 import type { HoundsmanConfig } from "./config";
+import { Watchdog, type WatchdogContext } from "./domain/watchdog";
 import type { WatchdogDefinition } from "./types";
 
+/** Coleção tipada de watchdogs do projeto. */
+export class WatchdogRegistry<TId extends string = string> {
+	private readonly config: HoundsmanConfig<TId>;
+
+	constructor(config: HoundsmanConfig<TId>) {
+		this.config = config;
+	}
+
+	/** Ids na ordem de declaração. */
+	get ids(): readonly TId[] {
+		return this.config.watchdogIds;
+	}
+
+	/** Definição de um watchdog (id string em runtime). */
+	get(watchdogId: string): WatchdogDefinition {
+		return this.config.watchdogs[watchdogId as TId];
+	}
+
+	/** Busca null-safe por id. */
+	find(watchdogId: string): Watchdog | null {
+		const definition = this.config.watchdogs[watchdogId as TId];
+		return definition ? new Watchdog(definition) : null;
+	}
+
+	/** Nome legível (default: o próprio id). */
+	nameOf(watchdogId: string): string {
+		return this.find(watchdogId)?.name ?? watchdogId;
+	}
+
+	/** Contexto essencial (sem regras). */
+	context(watchdogId: string): WatchdogContext {
+		return new Watchdog(this.get(watchdogId)).context();
+	}
+
+	/** Ids dos watchdogs que cobrem o arquivo. */
+	matching(filePath: string, content?: string): TId[] {
+		return this.config.watchdogIds.filter((id) =>
+			new Watchdog(this.config.watchdogs[id]).matches(filePath, content),
+		);
+	}
+
+	/** Todos os watchdogs (na ordem de declaração). */
+	all(): Watchdog[] {
+		return this.config.watchdogIds.map(
+			(id) => new Watchdog(this.config.watchdogs[id]),
+		);
+	}
+}
+
 /** Acesso tipado a um watchdog do projeto (id string em runtime). */
 export function getWatchdog<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
 ): WatchdogDefinition {
-	return config.watchdogs[watchdogId as TId];
+	return new WatchdogRegistry(config).get(watchdogId);
 }
 
 /** Busca null-safe por id string (runtime). */
@@ -20,23 +72,13 @@ export function findWatchdog<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
 ): WatchdogDefinition | null {
-	return config.watchdogs[watchdogId as TId] ?? null;
+	return new WatchdogRegistry(config).find(watchdogId)?.definition ?? null;
 }
 
 /** Contexto "essencial" do watchdog — SEM regras (docs/UI/inspeção). */
 export function getWatchdogContext<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
-) {
-	const { id, name, description, scope, reviewFocus, exclude, contextFiles } =
-		getWatchdog(config, watchdogId);
-	return {
-		id,
-		name,
-		description,
-		scope,
-		reviewFocus,
-		exclude,
-		contextFiles,
-	};
+): WatchdogContext {
+	return new WatchdogRegistry(config).context(watchdogId);
 }

package/src/index.ts

@@ -5,15 +5,18 @@
  * (`houndsman.config.ts`): watchdogs, tipos e helpers de autoria.
  */
 
+export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
+export { ProjectScaffolder } from "./core/commands/scaffold";
 export type {
 	HoundsmanBudgets,
 	HoundsmanConcurrency,
 	HoundsmanConfig,
 	HoundsmanConfigInput,
+	HoundsmanStorage,
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
@@ -36,6 +39,14 @@ export {
 	parseDiffIndex,
 	parseNumstat,
 } from "./core/diff-source";
+export { DocDiscoverer } from "./core/doc-discoverer";
+export { Classification } from "./core/domain/classification";
+export { Diff } from "./core/domain/diff";
+export { Watchdog } from "./core/domain/watchdog";
+export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
+export { HoundsmanEngine } from "./core/engine/houndsman-engine";
+export { ReviewScopeResolver } from "./core/engine/review-scope";
+export { ReviewSession } from "./core/engine/review-session";
 export {
 	churnOf,
 	classifyEntries,
@@ -65,6 +76,7 @@ export type {
 	FindingDecision,
 	FindingExecState,
 	FindingHistoryEntry,
+	FindingIdResolution,
 	FindingState,
 	FindingsFilter,
 	FindingsStateFile,
@@ -75,34 +87,71 @@ export type {
 export {
 	applyFindingUpdate,
 	buildStateFromFindings,
-	buildStateFromRunDir,
 	compareFindings,
 	emptyState,
 	FINDING_DECISIONS,
 	FINDING_EXEC_STATES,
 	FINDINGS_STATE_VERSION,
+	Finding,
+	FindingsRepository,
+	FindingsState,
 	FindingsStateStore,
 	fileReader,
 	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";
+export { BriefRenderer } from "./core/renderers/brief-renderer";
+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 type { Clock } from "./core/services/clock";
+export { systemClock } from "./core/services/clock";
+export { FileClassifier } from "./core/services/file-classifier";
+export { FixBatchBuilder } from "./core/services/fix-batch-builder";
+export type { GhResult, GhRunner } from "./core/services/gh-client";
+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,
@@ -127,6 +176,8 @@ export {
 	findWatchdog,
 	getWatchdog,
 	getWatchdogContext,
+	WatchdogRegistry,
 } from "./core/watchdog-registry";
 export type { ServerOptions } from "./server";
-export { createRequestHandler, startServer } from "./server";
+export { createRequestHandler, HoundsmanServer, startServer } from "./server";
+export { RunRepository } from "./server/run-repository";

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>
 	);
 }