@payconductor/houndsman 0.3.0 → 0.5.0

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 pinga o `updatedAt`. Execuções ativas têm um
+ * `heartbeatAt` próprio (renovado por `status ping` ou pela correção); a UI usa
+ * esse campo — não o `updatedAt` — para detectar timeout (display-only).
  */
 
-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,64 @@ 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);
+/** `true` para status de execução (recebem heartbeat e podem dar timeout). */
+export function isActiveRunStatus(status: RunStatus | null): boolean {
+	return status === "reviewing" || status === "fixing";
 }
 
-/** 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;
+	/**
+	 * Marca a execução como viva agora. Implícito no início de um ciclo
+	 * (`resetStartedAt`); pings explícitos usam `touchRunStatus`.
+	 */
+	touch?: 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();
+): ReviewRecord {
 	const now = options.now ?? systemClock();
-	const previous = readRunStatus(runDir);
-	const file: RunStatusFile = {
-		version: RUN_STATUS_VERSION,
-		slug: sanitizeBranch(options.branch),
-		branch: options.branch,
+	const active = isActiveRunStatus(options.status);
+	const touch = options.touch ?? options.resetStartedAt ?? false;
+	const updated = storage.updateReview(reviewId, {
 		status: options.status,
-		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
+		resetStartedAt: options.resetStartedAt,
+		heartbeatAt: active && touch ? now : undefined,
+		resetHeartbeat: !active,
 		updatedAt: now,
-	};
-	files.write(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
-	return file;
+	});
+	if (!updated) throw new Error(`Review '${reviewId}' não encontrada.`);
+	return updated;
+}
+
+/**
+ * Heartbeat explícito de uma execução em andamento (skill viva).
+ * Só age em `reviewing`/`fixing`; status terminal é devolvido sem alteração.
+ */
+export function touchRunStatus(
+	storage: StorageProvider,
+	reviewId: string,
+	now: string = systemClock(),
+): ReviewRecord {
+	const review = storage.getReview(reviewId);
+	if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+	if (!isActiveRunStatus(review.status)) return review;
+	return storage.updateReview(reviewId, { heartbeatAt: now, updatedAt: now }) ?? review;
 }
 
 /**
@@ -105,14 +110,18 @@ 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,
-		status: statusAfterFindingsChange(previous, state),
+): ReviewRecord {
+	const previous = storage.getReview(reviewId)?.status ?? null;
+	const status = statusAfterFindingsChange(previous, state);
+	return writeRunStatus(storage, reviewId, {
+		status,
+		// Só a correção em andamento é uma execução: triagem/reviewing não
+		// devem renovar o heartbeat (era a origem do "timeout falso").
+		touch: status === "fixing",
 	});
 }

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:");
+}

package/src/core/storage/file/file-storage.ts

@@ -0,0 +1,271 @@
+/**
+ * Provider de arquivos do houndsman (biblioteca) — fallback do SQLite.
+ *
+ * Mantém o formato antigo (JSON por review), mas sob o diretório global do
+ * houndsman. Serve para debug/rollback: trocar `storage.provider` para `"file"`.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { FINDINGS_STATE_VERSION, type FindingsStateFile } from "../../findings-state";
+import { systemClock } from "../../services/clock";
+import { ProjectFiles } from "../../services/project-files";
+import type {
+	ArtifactRecord,
+	CreateReviewInput,
+	ReviewPatch,
+	ReviewRecord,
+	StorageProvider,
+	WriteArtifactInput,
+} from "../types";
+
+const REVIEW_FILE = "review.json";
+const FINDINGS_FILE = "findings.json";
+const ARTIFACTS_FILE = "artifacts.json";
+
+/** Provider em arquivos sob uma raiz global. */
+export class FileStorageProvider implements StorageProvider {
+	readonly kind = "file" as const;
+	private readonly root: string;
+	private readonly files = new ProjectFiles();
+
+	constructor(root: string) {
+		this.root = root;
+	}
+
+	// -----------------------------------------------------------------------
+	// Reviews
+	// -----------------------------------------------------------------------
+
+	getOrCreateReview(input: CreateReviewInput): ReviewRecord {
+		const existing = this.findReview(input.repo.key, input.branch);
+		if (existing) {
+			if (
+				existing.repoRoot !== input.repo.root ||
+				existing.repoRemote !== input.repo.remote
+			) {
+				return this.writeReview({
+					...existing,
+					repoRoot: input.repo.root,
+					repoRemote: input.repo.remote,
+				});
+			}
+			return existing;
+		}
+
+		const now = input.now ?? systemClock();
+		const record: ReviewRecord = {
+			id: randomUUID(),
+			repoKey: input.repo.key,
+			repoRoot: input.repo.root,
+			repoRemote: input.repo.remote,
+			branch: input.branch,
+			slug: input.slug,
+			base: input.base,
+			head: input.head,
+			status: null,
+			createdAt: now,
+			updatedAt: now,
+		};
+		return this.writeReview(record);
+	}
+
+	findReview(repoKey: string, branch: string): ReviewRecord | null {
+		return (
+			this.readReviews(repoKey).find((review) => review.branch === branch) ?? null
+		);
+	}
+
+	getReview(id: string): ReviewRecord | null {
+		return this.readReviews().find((review) => review.id === id) ?? null;
+	}
+
+	listReviews(repoKey?: string): ReviewRecord[] {
+		return this.readReviews(repoKey).sort((a, b) =>
+			b.updatedAt.localeCompare(a.updatedAt),
+		);
+	}
+
+	updateReview(id: string, patch: ReviewPatch): ReviewRecord | null {
+		const review = this.getReview(id);
+		if (!review) return null;
+		const now = patch.updatedAt ?? systemClock();
+		const updated: ReviewRecord = { ...review };
+		if (patch.branch !== undefined) updated.branch = patch.branch;
+		if (patch.slug !== undefined) updated.slug = patch.slug;
+		if (patch.base !== undefined) updated.base = patch.base;
+		if (patch.head !== undefined) updated.head = patch.head;
+		if (patch.headSha !== undefined) updated.headSha = patch.headSha;
+		if (patch.reviewedSha !== undefined) updated.reviewedSha = patch.reviewedSha;
+		if (patch.reviewedAt !== undefined) updated.reviewedAt = patch.reviewedAt;
+		if (patch.status !== undefined) updated.status = patch.status;
+		if (patch.resetStartedAt) updated.startedAt = now;
+		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
+		if (patch.resetHeartbeat) updated.heartbeatAt = undefined;
+		else if (patch.heartbeatAt !== undefined) updated.heartbeatAt = patch.heartbeatAt;
+		updated.updatedAt = patch.updatedAt ?? now;
+		return this.writeReview(updated);
+	}
+
+	deleteReview(id: string): void {
+		const review = this.getReview(id);
+		if (!review) return;
+		this.files.removeDir(this.reviewDir(review));
+	}
+
+	// -----------------------------------------------------------------------
+	// Findings
+	// -----------------------------------------------------------------------
+
+	readFindings(reviewId: string): FindingsStateFile | null {
+		const review = this.getReview(reviewId);
+		if (!review) return null;
+		const raw = this.files.readJson<FindingsStateFile>(
+			join(this.reviewDir(review), FINDINGS_FILE),
+		);
+		if (!raw || raw.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
+		return raw;
+	}
+
+	writeFindings(reviewId: string, state: FindingsStateFile): void {
+		const review = this.getReview(reviewId);
+		if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+		this.writeJson(join(this.reviewDir(review), FINDINGS_FILE), state);
+		this.writeReview({
+			...review,
+			reviewedSha: state.reviewed?.headSha,
+			reviewedAt: state.reviewed?.at,
+			updatedAt: state.updatedAt || systemClock(),
+		});
+	}
+
+	// -----------------------------------------------------------------------
+	// Artefatos
+	// -----------------------------------------------------------------------
+
+	readArtifact(reviewId: string, name: string): ArtifactRecord | null {
+		const review = this.getReview(reviewId);
+		if (!review) return null;
+		return this.readArtifacts(review)[name] ?? null;
+	}
+
+	writeArtifact(reviewId: string, input: WriteArtifactInput): ArtifactRecord {
+		const review = this.getReview(reviewId);
+		if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+		const index = this.readArtifacts(review);
+		const now = systemClock();
+		const existing = index[input.name];
+		const contentType =
+			input.contentType ??
+			(input.name.toLowerCase().endsWith(".json")
+				? "application/json; charset=utf-8"
+				: "text/markdown; charset=utf-8");
+		const record: ArtifactRecord = {
+			id: existing?.id ?? randomUUID(),
+			reviewId,
+			name: input.name,
+			kind: input.kind,
+			content: input.content,
+			contentType,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		};
+		index[input.name] = record;
+		this.writeJson(join(this.reviewDir(review), ARTIFACTS_FILE), index);
+		return record;
+	}
+
+	listArtifacts(reviewId: string): ArtifactRecord[] {
+		const review = this.getReview(reviewId);
+		if (!review) return [];
+		return Object.values(this.readArtifacts(review)).sort((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+	}
+
+	deleteArtifact(reviewId: string, name: string): void {
+		const review = this.getReview(reviewId);
+		if (!review) return;
+		const index = this.readArtifacts(review);
+		if (!index[name]) return;
+		delete index[name];
+		this.writeJson(join(this.reviewDir(review), ARTIFACTS_FILE), index);
+	}
+
+	// -----------------------------------------------------------------------
+	// Manutenção / ciclo de vida
+	// -----------------------------------------------------------------------
+
+	maintain(): void {
+		// Nada a compactar: arquivos JSON são reescritos por inteiro.
+	}
+
+	location(reviewId: string): string {
+		const review = this.getReview(reviewId);
+		return review
+			? `file:${join(this.reviewDir(review), FINDINGS_FILE)}#${reviewId}`
+			: `file:${this.root}#${reviewId}`;
+	}
+
+	close(): void {
+		// Sem recurso aberto.
+	}
+
+	// -----------------------------------------------------------------------
+	// Internos
+	// -----------------------------------------------------------------------
+
+	private repoDir(repoKey: string): string {
+		const hash = createHash("sha256").update(repoKey).digest("hex").slice(0, 16);
+		return join(this.root, hash);
+	}
+
+	private reviewDir(review: ReviewRecord): string {
+		return join(this.repoDir(review.repoKey), review.slug);
+	}
+
+	private writeReview(record: ReviewRecord): ReviewRecord {
+		this.writeJson(join(this.reviewDir(record), REVIEW_FILE), record);
+		return record;
+	}
+
+	private readReviews(repoKey?: string): ReviewRecord[] {
+		const roots = repoKey ? [this.repoDir(repoKey)] : this.subdirectories(this.root);
+		const reviews: ReviewRecord[] = [];
+		for (const repoDir of roots) {
+			for (const slugDir of this.subdirectories(repoDir)) {
+				const review = this.files.readJson<ReviewRecord>(
+					join(slugDir, REVIEW_FILE),
+				);
+				if (review && (!repoKey || review.repoKey === repoKey)) {
+					reviews.push(review);
+				}
+			}
+		}
+		return reviews;
+	}
+
+	private readArtifacts(review: ReviewRecord): Record<string, ArtifactRecord> {
+		return (
+			this.files.readJson<Record<string, ArtifactRecord>>(
+				join(this.reviewDir(review), ARTIFACTS_FILE),
+			) ?? {}
+		);
+	}
+
+	private writeJson(path: string, value: unknown): void {
+		this.files.writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+	}
+
+	private subdirectories(dir: string): string[] {
+		if (!existsSync(dir)) return [];
+		try {
+			return readdirSync(dir)
+				.map((name) => join(dir, name))
+				.filter((path) => statSync(path).isDirectory());
+		} catch {
+			return [];
+		}
+	}
+}

package/src/core/storage/paths.ts

@@ -0,0 +1,64 @@
+/**
+ * Localização global do houndsman (biblioteca).
+ *
+ * O banco e o staging vivem no diretório de dados do usuário — nunca dentro do
+ * projeto nem da instalação npm. `HOUNDSMAN_HOME` sobrescreve tudo (útil em
+ * testes e para manter múltiplos ambientes).
+ */
+
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { HoundsmanConfig } from "../config";
+
+export const HOUNDSMAN_HOME_ENV = "HOUNDSMAN_HOME";
+
+/** Diretório-base global do houndsman. */
+export function houndsmanHome(): string {
+	const override = process.env[HOUNDSMAN_HOME_ENV];
+	if (override && override.trim().length > 0) return resolve(override);
+
+	const home = homedir();
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA;
+		return join(
+			local && local.length > 0 ? local : join(home, "AppData", "Local"),
+			"houndsman",
+		);
+	}
+	if (process.platform === "darwin") {
+		return join(home, "Library", "Application Support", "houndsman");
+	}
+	const xdg = process.env.XDG_DATA_HOME;
+	return join(xdg && xdg.length > 0 ? xdg : join(home, ".local", "share"), "houndsman");
+}
+
+/** Caminho do banco SQLite (config `storage.path` ou `<home>/houndsman.db`). */
+export function databasePath(config: HoundsmanConfig): string {
+	const configured = config.storage?.path;
+	if (configured && configured.trim().length > 0) return resolve(configured);
+	return join(houndsmanHome(), "houndsman.db");
+}
+
+/** Raiz das runs do provider de arquivos (config `storage.path` ou `<home>/runs`). */
+export function fileRoot(config: HoundsmanConfig): string {
+	const configured = config.storage?.path;
+	if (configured && configured.trim().length > 0) return resolve(configured);
+	return join(houndsmanHome(), "runs");
+}
+
+/** Raiz do staging por review (briefs/findings/contexto dos subagentes). */
+export function workRoot(): string {
+	return join(houndsmanHome(), "work");
+}
+
+/** Referência legível do storage configurado (diagnóstico). */
+export function storageLocation(config: HoundsmanConfig): string {
+	return config.storage?.provider === "file"
+		? `file:${fileRoot(config)}`
+		: `sqlite:${databasePath(config)}`;
+}
+
+/** Diretório de staging de uma review. */
+export function workDir(reviewId: string): string {
+	return join(workRoot(), reviewId);
+}

package/src/core/storage/repo-identity.ts

@@ -0,0 +1,70 @@
+/**
+ * Identidade do repositório (biblioteca).
+ *
+ * A UI e o CLI escopam runs por repositório. Preferimos o remote `origin`
+ * normalizado (`github.com/org/repo`) porque a pasta local pode ser movida;
+ * sem remote, caímos no caminho absoluto da raiz git.
+ */
+
+import { resolve } from "node:path";
+import { GitRepository } from "../services/git-repository";
+import type { RepoIdentity } from "./types";
+
+/** Normaliza um remote para `host/owner/repo` (sem protocolo, credencial ou `.git`). */
+export function normalizeRemote(raw: string): string | null {
+	const value = raw.trim().replace(/\/+$/, "");
+	if (value.length === 0) return null;
+
+	// SCP-like: `git@github.com:owner/repo.git`.
+	if (!value.includes("://")) {
+		const scp = value.match(/^(?:[^@/]+@)?([^:/]+):(.+)$/);
+		if (scp) return `${scp[1].toLowerCase()}/${stripGitSuffix(scp[2])}`;
+		// Caminho local — não é um remote utilizável para identidade.
+		return null;
+	}
+
+	try {
+		const url = new URL(value);
+		const host = url.hostname.toLowerCase();
+		const path = stripGitSuffix(url.pathname.replace(/^\/+/, "").replace(/\/+$/, ""));
+		return path.length > 0 ? `${host}/${path}` : host;
+	} catch {
+		return null;
+	}
+}
+
+function stripGitSuffix(value: string): string {
+	return value.replace(/\.git$/i, "").replace(/^\/+/, "");
+}
+
+/** Normaliza a raiz local para comparação (Windows é case-insensitive). */
+function normalizeRoot(root: string): string {
+	const normalized = resolve(root).replace(/\\/g, "/").replace(/\/+$/, "");
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+/** Monta a identidade a partir do remote cru e da raiz do repositório. */
+export function buildRepoIdentity(
+	remote: string | null | undefined,
+	root: string,
+): RepoIdentity {
+	const normalized = remote ? normalizeRemote(remote) : null;
+	const absoluteRoot = resolve(root);
+	if (normalized) {
+		return {
+			key: `remote:${normalized}`,
+			root: absoluteRoot,
+			remote: remote ?? undefined,
+		};
+	}
+	return { key: `path:${normalizeRoot(absoluteRoot)}`, root: absoluteRoot };
+}
+
+/** Resolve a identidade do repositório a partir do cwd (nunca lança). */
+export function resolveRepoIdentity(
+	git: GitRepository = new GitRepository(),
+	cwd: string = process.cwd(),
+): RepoIdentity {
+	const root = git.rootPath() ?? resolve(cwd);
+	return buildRepoIdentity(git.remoteUrl(), root);
+}