@payconductor/houndsman 0.3.0 → 0.4.0

package/src/core/project-config.ts

@@ -2,17 +2,16 @@
  * Configuração do projeto (domínio) — resolve defaults e expõe o registry.
  *
  * Evita o "data clump" de passar `HoundsmanConfig` para dezenas de funções:
- * quem precisa de `artifactDir`/orçamento/concorrência/watchdogs pede aqui.
+ * quem precisa de orçamento/concorrência/watchdogs pede aqui.
  * O contrato do consumidor (`houndsman.config.ts`) não muda.
  */
 
-import type { HoundsmanConfig } from "./config";
+import type { HoundsmanConfig, HoundsmanStorage } from "./config";
 import {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
-import { ARTIFACT_DIR } from "./paths";
 import { WatchdogRegistry } from "./watchdog-registry";
 
 /** Configuração resolvida do projeto. */
@@ -29,8 +28,8 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.projectName;
 	}
 
-	get artifactDir(): string {
-		return this.raw.artifactDir ?? ARTIFACT_DIR;
+	get storage(): HoundsmanStorage {
+		return this.raw.storage ?? {};
 	}
 
 	get maxFilesPerBrief(): number {

package/src/core/renderers/manifest-writer.ts

@@ -1,20 +1,20 @@
 /**
- * Manifesto da run (biblioteca) — monta e grava o `manifest.json`.
+ * Manifesto da run (biblioteca) — monta e grava o artefato `manifest.json`.
  *
  * Concentra o resumo do que foi ativado (watchdogs, orçamento, churn, contexto,
- * Jev e incremental), hoje espalhado em helpers do orquestrador.
+ * Jev e incremental). O manifesto vive no storage; os caminhos de briefs e
+ * findings apontam para o staging da review.
  */
 
 import { Classification } from "../domain/classification";
 import type { ClassificationResult } from "../file-classifier";
 import type { JevCandidatesFile } from "../jev";
-import { OUTPUT_FORMAT_PATH, relFromRoot } from "../paths";
-import { readContextSummary } from "../pr-context";
+import { OUTPUT_FORMAT_PATH } from "../paths";
 import type { ProjectConfig } from "../project-config";
 import type { MergedFinding } from "../report-builder";
-import type { RunLayout } from "../run-layout";
 import { systemClock } from "../services/clock";
-import { ProjectFiles } from "../services/project-files";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import type { ReviewWorkArea } from "../storage/work-area";
 
 /** Opções do manifesto (subset do `ReviewOptions`). */
 export type ManifestOptions = {
@@ -32,12 +32,22 @@ export type ManifestClassification = ClassificationResult & {
 
 /** Escreve o `manifest.json` de uma run. */
 export class ManifestWriter {
-	private readonly layout: RunLayout;
+	private readonly storage: StorageProvider;
+	private readonly review: ReviewRecord;
+	private readonly work: ReviewWorkArea;
 	private readonly project: ProjectConfig;
 	private readonly options: ManifestOptions;
 
-	constructor(layout: RunLayout, project: ProjectConfig, options: ManifestOptions) {
-		this.layout = layout;
+	constructor(
+		storage: StorageProvider,
+		review: ReviewRecord,
+		work: ReviewWorkArea,
+		project: ProjectConfig,
+		options: ManifestOptions,
+	) {
+		this.storage = storage;
+		this.review = review;
+		this.work = work;
 		this.project = project;
 		this.options = options;
 	}
@@ -60,16 +70,16 @@ export class ManifestWriter {
 				name: this.project.watchdogs.nameOf(id),
 				files: selection.selected,
 				overflow: selection.overflow.length,
-				brief: relFromRoot(this.layout.briefFile(id)),
-				findings: relFromRoot(this.layout.findingFile(id)),
+				brief: this.work.briefFile(id),
+				findings: this.work.findingFile(id),
 				status: pending.includes(id) ? "pending" : "done",
 			};
 		});
 
-		const summary = readContextSummary(this.layout.contextPaths.summary);
+		const summary = this.work.readContextSummary();
 		const manifest = {
-			branch: this.layout.branch,
-			slug: this.layout.slug,
+			branch: this.review.branch,
+			slug: this.review.slug,
 			base: this.options.base,
 			head: this.options.head,
 			headSha: classification.headSha,
@@ -104,9 +114,10 @@ export class ManifestWriter {
 			excludedCount: classification.excludedCount,
 		};
 
-		new ProjectFiles().write(
-			this.layout.manifestFile,
-			`${JSON.stringify(manifest, null, 2)}\n`,
-		);
+		this.storage.writeArtifact(this.review.id, {
+			name: "manifest.json",
+			kind: "manifest",
+			content: `${JSON.stringify(manifest, null, 2)}\n`,
+		});
 	}
 }

package/src/core/run-layout.ts

@@ -1,108 +1,8 @@
 /**
- * Layout de uma run (biblioteca) — único ponto que conhece os nomes/estrutura
- * dos artefatos em `.houndsman/.runs/<slug>/`.
+ * Removido: o layout de artefatos do projeto deu lugar ao staging global por
+ * review (`ReviewWorkArea` em `core/storage/work-area.ts`).
  *
- * Evita o "data clump" de `(dir, branch)`/`(outDir, branch)` espalhado pelo
- * motor: quem precisa de um caminho pede ao layout.
+ * Mantido apenas para não quebrar imports antigos de tipos.
  */
 
-import { join } from "node:path";
-import {
-	CONTEXT_BRIEF_FILE,
-	CONTEXT_FILE,
-	CONTEXT_SUMMARY_FILE,
-	RUN_STATUS_FILE,
-	STATE_FILE,
-	VERIFY_FILE,
-} from "./paths";
-import { sanitizeBranch } from "./report-builder";
-
-/** Caminhos dos artefatos de contexto da PR. */
-export type ContextPaths = {
-	dir: string;
-	context: string;
-	summary: string;
-	brief: string;
-};
-
-/** Diretório e caminhos de uma run (branch-slug). */
-export class RunLayout {
-	readonly artifactDir: string;
-	readonly branch: string;
-
-	constructor(artifactDir: string, branch: string) {
-		this.artifactDir = artifactDir;
-		this.branch = branch;
-	}
-
-	get slug(): string {
-		return sanitizeBranch(this.branch);
-	}
-
-	get outDir(): string {
-		return join(this.artifactDir, this.slug);
-	}
-
-	get briefsDir(): string {
-		return join(this.outDir, "briefs");
-	}
-
-	get findingsDir(): string {
-		return join(this.outDir, "findings");
-	}
-
-	/** Caminho de um arquivo dentro da pasta da run. */
-	file(name: string): string {
-		return join(this.outDir, name);
-	}
-
-	briefFile(id: string): string {
-		return join(this.briefsDir, `${id}.md`);
-	}
-
-	findingFile(id: string): string {
-		return join(this.findingsDir, `${id}.json`);
-	}
-
-	get classificationFile(): string {
-		return this.file("classification.json");
-	}
-
-	get manifestFile(): string {
-		return this.file("manifest.json");
-	}
-
-	get candidatesFile(): string {
-		return this.file("candidates.json");
-	}
-
-	get reviewFile(): string {
-		return this.file("review.md");
-	}
-
-	get stateFile(): string {
-		return this.file(STATE_FILE);
-	}
-
-	get runStatusFile(): string {
-		return this.file(RUN_STATUS_FILE);
-	}
-
-	get verifyFile(): string {
-		return this.file(VERIFY_FILE);
-	}
-
-	/** Relatório isolado de um watchdog (`review.<id>.md`). */
-	domainReportFile(id: string): string {
-		return this.file(`review.${sanitizeBranch(id)}.md`);
-	}
-
-	get contextPaths(): ContextPaths {
-		return {
-			dir: this.outDir,
-			context: this.file(CONTEXT_FILE),
-			summary: this.file(CONTEXT_SUMMARY_FILE),
-			brief: this.file(CONTEXT_BRIEF_FILE),
-		};
-	}
-}
+export type { ContextPaths } from "./storage/work-area";

package/src/core/run-status.ts

@@ -1,23 +1,20 @@
 /**
- * Status do run (biblioteca) — persistido em `.houndsman/.runs/<slug>/run.json`.
+ * Status do run (biblioteca) — colunas da review no storage.
  *
  * Diz à UI em que pé está uma run: `reviewing` (revisando) → `review_done`
  * (revisão finalizada) → `fixing` (corrigindo) → `fix_done` (correção finalizada).
  *
- * Toda ação que muda o estado faz um **ping** no `updatedAt`, mantendo o arquivo
- * "quente". Timeout é **display-only** (a UI compara `updatedAt` com o agora) —
- * não é um status persistido.
+ * Toda ação que muda o estado faz um **ping** no `updatedAt`. Timeout é
+ * **display-only** (a UI compara `updatedAt` com o agora) — não é um status
+ * persistido.
  */
 
-import { join } from "node:path";
 import type { FindingsStateFile } from "./findings-state";
-import { RUN_STATUS_FILE } from "./paths";
-import { sanitizeBranch } from "./report-builder";
 import { systemClock } from "./services/clock";
-import { ProjectFiles } from "./services/project-files";
+import type { ReviewRecord, ReviewStatus, StorageProvider } from "./storage/types";
 
 /** Estados de execução de uma run (persistidos). */
-export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+export type RunStatus = ReviewStatus;
 
 /** Valores canônicos de status (ordem de exibição/lifecycle). */
 export const RUN_STATUSES: readonly RunStatus[] = [
@@ -27,56 +24,34 @@ export const RUN_STATUSES: readonly RunStatus[] = [
 	"fix_done",
 ];
 
-export const RUN_STATUS_VERSION = 1;
-
-/** Conteúdo do `run.json`. */
-export type RunStatusFile = {
-	version: 1;
-	slug: string;
-	branch: string;
-	status: RunStatus;
-	/** Início do ciclo de revisão atual (reiniciado a cada `prepare`). */
-	startedAt: string;
-	/** Última ação importante (ping). */
-	updatedAt: string;
-};
-
-/** Caminho do `run.json` dentro da pasta da run. */
-export function runStatusPath(runDir: string): string {
-	return join(runDir, RUN_STATUS_FILE);
-}
-
-/** Lê o `run.json` da run (null se ausente/inválido). */
-export function readRunStatus(runDir: string): RunStatusFile | null {
-	return new ProjectFiles().readJson<RunStatusFile>(runStatusPath(runDir));
+/** Lê o status atual (null se a review não existir). */
+export function readRunStatus(
+	storage: StorageProvider,
+	reviewId: string,
+): ReviewRecord | null {
+	return storage.getReview(reviewId);
 }
 
 export type WriteRunStatusOptions = {
-	branch: string;
 	status: RunStatus;
 	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
 	resetStartedAt?: boolean;
 	now?: string;
 };
 
-/** Grava/atualiza o `run.json` (ping no `updatedAt`). */
+/** Grava/atualiza o status da review (ping no `updatedAt`). */
 export function writeRunStatus(
-	runDir: string,
+	storage: StorageProvider,
+	reviewId: string,
 	options: WriteRunStatusOptions,
-): RunStatusFile {
-	const files = new ProjectFiles();
-	const now = options.now ?? systemClock();
-	const previous = readRunStatus(runDir);
-	const file: RunStatusFile = {
-		version: RUN_STATUS_VERSION,
-		slug: sanitizeBranch(options.branch),
-		branch: options.branch,
+): ReviewRecord {
+	const updated = storage.updateReview(reviewId, {
 		status: options.status,
-		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
-		updatedAt: now,
-	};
-	files.write(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
-	return file;
+		resetStartedAt: options.resetStartedAt,
+		updatedAt: options.now ?? systemClock(),
+	});
+	if (!updated) throw new Error(`Review '${reviewId}' não encontrada.`);
+	return updated;
 }
 
 /**
@@ -105,14 +80,14 @@ export function statusAfterFindingsChange(
 	return previous ?? "review_done";
 }
 
-/** Ping: deriva o status da mudança nos findings e grava o `run.json`. */
+/** Ping: deriva o status da mudança nos findings e grava na review. */
 export function pingFindingsStatus(
-	runDir: string,
+	storage: StorageProvider,
+	reviewId: string,
 	state: FindingsStateFile,
-): RunStatusFile {
-	const previous = readRunStatus(runDir)?.status ?? null;
-	return writeRunStatus(runDir, {
-		branch: state.branch,
+): ReviewRecord {
+	const previous = storage.getReview(reviewId)?.status ?? null;
+	return writeRunStatus(storage, reviewId, {
 		status: statusAfterFindingsChange(previous, state),
 	});
 }

package/src/core/services/git-repository.ts

@@ -52,6 +52,22 @@ export class GitRepository {
 		return branch.length > 0 ? branch : null;
 	}
 
+	/** Raiz do repositório; `null` fora de um repo git. */
+	rootPath(): string | null {
+		const result = this.tryRun(["rev-parse", "--show-toplevel"]);
+		if (!result.ok) return null;
+		const root = result.stdout.trim();
+		return root.length > 0 ? root : null;
+	}
+
+	/** URL de um remote (default `origin`); `null` se ausente. */
+	remoteUrl(name = "origin"): string | null {
+		const result = this.tryRun(["remote", "get-url", name]);
+		if (!result.ok) return null;
+		const url = result.stdout.trim();
+		return url.length > 0 ? url : null;
+	}
+
 	/**
 	 * `true` se `ancestor` é ancestral de `descendant`. Qualquer outro desfecho
 	 * (ref desconhecida, exit ≠ 0) devolve `false` — cai no review completo.

package/src/core/services/project-files.ts

@@ -6,7 +6,14 @@
  * manter o comportamento fail-open do motor.
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 
 /** Leitor de arquivos relativos à raiz do projeto (injetável nos testes). */
@@ -67,6 +74,11 @@ export class ProjectFiles {
 		mkdirSync(this.resolve(path), { recursive: true });
 	}
 
+	/** Remove um diretório (recursivo, best-effort). */
+	removeDir(path: string): void {
+		rmSync(this.resolve(path), { recursive: true, force: true });
+	}
+
 	/** `true` se o caminho existe. */
 	exists(path: string): boolean {
 		return existsSync(this.resolve(path));

package/src/core/storage/factory.ts

@@ -0,0 +1,24 @@
+/**
+ * Fábrica do provider de persistência (biblioteca).
+ *
+ * Default: SQLite no diretório global. `storage.provider: "file"` mantém o
+ * backend em arquivos sob o mesmo home — útil para debug ou rollback.
+ */
+
+import type { HoundsmanConfig } from "../config";
+import { FileStorageProvider } from "./file/file-storage";
+import { databasePath, fileRoot } from "./paths";
+import { SQLiteStorageProvider } from "./sqlite/sqlite-storage";
+import type { StorageProvider } from "./types";
+
+/** Cria o provider configurado pelo projeto. */
+export function createStorage(config: HoundsmanConfig): StorageProvider {
+	return config.storage?.provider === "file"
+		? new FileStorageProvider(fileRoot(config))
+		: new SQLiteStorageProvider(databasePath(config));
+}
+
+/** Provider SQLite em memória (testes). */
+export function createMemoryStorage(): StorageProvider {
+	return new SQLiteStorageProvider(":memory:");
+}