@payconductor/houndsman 0.2.0 → 0.3.0

package/src/core/commands/findings.ts

@@ -27,7 +27,6 @@ import {
 	type FindingsFilter,
 	type FindingsStateFile,
 	FindingsStateStore,
-	type FindingsSummary,
 	type FindingUpdate,
 	fileReader,
 	filterFindings,
@@ -35,7 +34,6 @@ import {
 	summarize,
 	syncState,
 } from "../findings-state";
-import { buildFixBatch, type FixBatchResult } from "../fix-batch";
 import {
 	buildSubmitPreview,
 	defaultGhRunner,
@@ -47,11 +45,13 @@ import {
 } from "../github-review";
 import { relFromRoot, VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
+import { BatchPresenter } from "../renderers/batch-presenter";
+import { FindingsPresenter } from "../renderers/findings-presenter";
+import { VerifyPresenter } from "../renderers/verify-presenter";
 import { pingFindingsStatus } from "../run-status";
-import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
-// Tipos são apagados no transpile (custo zero). Os **valores** de `../verify` e de
-// `../jev` (axios) entram por import dinâmico — só o subcomando `verify` os usa.
-import type { VerifyEntry, VerifyStatus, VerifySummary } from "../verify";
+import { FixBatchBuilder } from "../services/fix-batch-builder";
+import { Verifier } from "../services/verifier";
+import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
 	output: string;
@@ -134,90 +134,16 @@ function loadState(config: HoundsmanConfig, parsed: ParsedArgs): FindingsStateFi
 }
 
 // ---------------------------------------------------------------------------
-// Render
+// Apresentação
 // ---------------------------------------------------------------------------
 
-function decisionLabel(decision: FindingDecision): string {
-	return decision;
-}
-
-/** Uma linha compacta por finding (uso no agente). */
-function renderFindingLine(finding: FindingState): string[] {
-	const emoji = SEVERITY_EMOJI[finding.severity];
-	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-	const flags = `${decisionLabel(finding.decision)}/${finding.execState}`;
-	const count = finding.count > 1 ? ` ×${finding.count}` : "";
-	const lines = [
-		`- \`${finding.id}\` ${emoji} **${finding.severity}** \`${location}\` — ${finding.rule}${count}`,
-		`  ${finding.message}`,
-		`  _${flags}_ · watchdogs: ${finding.watchdogIds.join(", ") || "—"}`,
-	];
-	if (finding.comment) lines.push(`  **Comentário:** ${finding.comment}`);
-	return lines;
-}
-
-function renderList(state: FindingsStateFile, findings: FindingState[]): string {
-	if (findings.length === 0) return "Nenhum finding para o filtro informado.";
-	const lines = [`# Findings — ${state.branch} (${findings.length})`, ""];
-	for (const finding of findings) lines.push(...renderFindingLine(finding));
-	return lines.join("\n");
-}
-
-function renderSummary(state: FindingsStateFile, summary: FindingsSummary): string {
-	const decisions = FINDING_DECISIONS.map((d) => `${d} ${summary.byDecision[d]}`).join(
-		" · ",
-	);
-	const exec = FINDING_EXEC_STATES.map((e) => `${e} ${summary.byExecState[e]}`).join(
-		" · ",
-	);
-	const severities = SEVERITY_ORDER.map((s) => `${s} ${summary.bySeverity[s]}`).join(
-		" · ",
-	);
-	return [
-		`# Triagem — ${state.branch}`,
-		"",
-		`Total: ${summary.total} (presentes: ${summary.present})`,
-		`Decisões: ${decisions}`,
-		`Execução: ${exec}`,
-		`Severidade: ${severities}`,
-	].join("\n");
-}
-
-/** Mix de severidade compacto (ex.: `❌1 ⚠️2`). */
-function severityBreakdown(bySeverity: Record<Severity, number>): string {
-	return SEVERITY_ORDER.filter((severity) => bySeverity[severity] > 0)
-		.map((severity) => `${SEVERITY_EMOJI[severity]}${bySeverity[severity]}`)
-		.join(" ");
-}
-
-/** Render do lote de correção: grupo atual paginado + outros grupos. */
-function renderBatch(result: FixBatchResult): string {
-	const { dimension, current, others, totals } = result;
-	if (totals.queue === 0) return "Nenhum finding pendente de correção.";
+const presenters = {
+	findings: new FindingsPresenter(),
+	batch: new BatchPresenter(),
+	verify: new VerifyPresenter(),
+};
 
-	const lines = [
-		`# Lote de correção — agrupado por ${dimension} (${totals.groups} grupo(s))`,
-		"",
-		`## Grupo atual — ${current.key} (${current.total} finding(s), mostrando ${current.returned})`,
-	];
-	for (const finding of current.findings) lines.push(...renderFindingLine(finding));
-	if (current.remaining > 0) {
-		lines.push("", `_… +${current.remaining} neste grupo (use \`--offset\`)._`);
-	}
-	if (others.length > 0) {
-		lines.push("", "## Outros grupos disponíveis");
-		for (const group of others) {
-			lines.push(
-				`- ${group.key} — ${group.count} (${severityBreakdown(group.bySeverity)})`,
-			);
-		}
-	}
-	lines.push(
-		"",
-		`fila: ${totals.queue} · retornados: ${totals.returned} · grupos: ${totals.groups}`,
-	);
-	return lines.join("\n");
-}
+const fixBatchBuilder = new FixBatchBuilder();
 
 // ---------------------------------------------------------------------------
 // Execução
@@ -332,7 +258,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(findings, null, 2)
-					: renderList(state, findings),
+					: presenters.findings.list(state, findings),
 				exitCode: 0,
 			};
 		}
@@ -345,7 +271,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: renderList(state, [finding]),
+					: presenters.findings.list(state, [finding]),
 				exitCode: 0,
 			};
 		}
@@ -417,7 +343,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(summary, null, 2)
-					: renderSummary(state, summary),
+					: presenters.findings.summary(state, summary),
 				exitCode: 0,
 			};
 		}
@@ -430,7 +356,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			const state = loadState(config, parsed);
 			const severity = parsed.values["--severity"];
 			const offset = Number(parsed.values["--offset"]);
-			const result = buildFixBatch(state, {
+			const result = fixBatchBuilder.build(state, {
 				severity: severity ? (severity as Severity) : undefined,
 				includeDone: parsed.bools.has("--include-done"),
 				offset: Number.isFinite(offset) ? offset : undefined,
@@ -439,7 +365,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(result, null, 2)
-					: renderBatch(result),
+					: presenters.batch.render(result),
 				exitCode: 0,
 			};
 		}
@@ -479,43 +405,6 @@ function requireIds(parsed: ParsedArgs, sub: string): string[] {
 // verify — as violações foram resolvidas? (sem re-revisar a PR)
 // ---------------------------------------------------------------------------
 
-/** Rótulo curto de cada status de verificação. */
-const VERIFY_LABEL: Record<VerifyStatus, string> = {
-	resolved: "✅ resolvido",
-	persisting: "❌ persiste",
-	uncertain: "⚠️ incerto",
-	"file-missing": "🗑️ arquivo ausente",
-};
-
-/** Render da verificação: contagem por status + uma linha por finding. */
-function renderVerify(
-	state: FindingsStateFile,
-	entries: VerifyEntry[],
-	summary: VerifySummary,
-	meta: { jevChecked: number; jevReason?: string },
-): string {
-	if (entries.length === 0) return "Nenhum finding para verificar.";
-	const lines = [
-		`# Verificação — ${state.branch} (${entries.length})`,
-		"",
-		`Resolvidos: ${summary.resolved} · Persistem: ${summary.persisting} · Incertos: ${summary.uncertain} · Arquivo ausente: ${summary["file-missing"]}`,
-	];
-	if (meta.jevChecked > 0) lines.push(`Confirmados por Jev: ${meta.jevChecked}.`);
-	else if (meta.jevReason) lines.push(`Jev: pulado (${meta.jevReason}).`);
-	lines.push("");
-	for (const entry of entries) {
-		const location = entry.line ? `${entry.file}:${entry.line}` : entry.file;
-		const via =
-			entry.basis === "jev" ? ` · Jev ${(entry.confidence ?? 0).toFixed(2)}` : "";
-		lines.push(
-			`- \`${entry.id}\` ${VERIFY_LABEL[entry.status]} — **${entry.severity}** \`${location}\` — ${entry.rule}${via}`,
-			`  ${entry.message}`,
-		);
-		if (entry.detail) lines.push(`  _${entry.detail}_`);
-	}
-	return lines.join("\n");
-}
-
 /**
  * Subcomando `findings verify` — checa se as violações foram resolvidas, sem
  * re-revisar a PR. Tier local (grátis) + confirmação Jev dos casos ambíguos
@@ -544,28 +433,26 @@ async function executeVerify(
 	const store = FindingsStateStore.at(dir, branch);
 	const state = loadState(config, parsed);
 
-	// Lazy: `../verify` (leve) e `../jev` (axios) só entram no caminho do verify.
-	const [
-		{ selectVerifiable, verifyLocal, summarizeVerify, applyJev, applyResolutions },
-		{ JevCandidatesStore, JevClient, JevVerifier },
-	] = await Promise.all([import("../verify"), import("../jev")]);
+	// Lazy: `../jev` (axios) só entra no caminho do verify.
+	const verifier = new Verifier();
+	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
-	const findings = selectVerifiable(state, filterFrom(parsed));
-	const entries = verifyLocal(findings, fileReader(process.cwd()));
+	const findings = verifier.select(state, filterFrom(parsed));
+	const entries = verifier.verifyLocal(findings, fileReader(process.cwd()));
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
 	let jevReason: string | undefined;
 	const ambiguous = entries.filter((entry) => entry.ambiguous);
 	if (ambiguous.length > 0) {
-		const verifier = new JevVerifier(new JevClient());
+		const jevVerifier = new JevVerifier(new JevClient());
 		if (parsed.bools.has("--no-jev")) {
 			jevReason = "desativado (--no-jev)";
-		} else if (!verifier.isConfigured()) {
+		} else if (!jevVerifier.isConfigured()) {
 			jevReason = "TYPESAFE_API_KEY não configurada";
 		} else {
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
-			const outcome = await verifier.verify(
+			const outcome = await jevVerifier.verify(
 				ambiguous.map((entry) => ({
 					id: entry.id,
 					file: entry.file,
@@ -577,23 +464,23 @@ async function executeVerify(
 					concurrency: resolveJevConcurrency(config),
 				},
 			);
-			applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
+			verifier.applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
 			jevChecked = outcome.checked;
 			jevReason = outcome.reason;
 		}
 	}
 
-	const summary = summarizeVerify(entries);
+	const summary = verifier.summarize(entries);
 	const reportPath = join(runDir(dir, branch), VERIFY_FILE);
 	writeFileSync(
 		reportPath,
-		`${renderVerify(state, entries, summary, { jevChecked, jevReason })}\n`,
+		`${presenters.verify.render(state, entries, summary, { jevChecked, jevReason })}\n`,
 	);
 
 	let applied: string[] = [];
 	if (parsed.bools.has("--apply")) {
 		store.update((current) => {
-			applied = applyResolutions(current, entries);
+			applied = verifier.applyResolutions(current, entries);
 		});
 		pingStatus(config, parsed);
 	}
@@ -605,7 +492,10 @@ async function executeVerify(
 				2,
 			)
 		: [
-				renderVerify(state, entries, summary, { jevChecked, jevReason }),
+				presenters.verify.render(state, entries, summary, {
+					jevChecked,
+					jevReason,
+				}),
 				"",
 				`Relatório: ${relFromRoot(reportPath)}`,
 				parsed.bools.has("--apply")

package/src/core/commands/review.ts

@@ -4,49 +4,32 @@
  * Biblioteca: NÃO usa `process.argv`/`process.exit` (o CLI decide o exit code).
  */
 
+import { ArgParser } from "../arg-parser";
 import { defaultOptions, type ReviewOptions } from "../orchestrator";
 import { ARTIFACT_DIR } from "../paths";
 
-const VALUE_FLAGS = new Set(["--base", "--head", "--branch", "--dir"]);
-const BOOLEAN_FLAGS = new Set([
-	"--finalize",
-	"--report-only",
-	"--fail-on-blocking",
-	"--clean",
-	"--no-jev",
-	"--full",
-]);
-
-function applyValue(opts: ReviewOptions, flag: string, value: string | undefined): void {
-	if (!value) return;
-	if (flag === "--base") opts.base = value;
-	else if (flag === "--head") opts.head = value;
-	else if (flag === "--branch") opts.branch = value;
-	else if (flag === "--dir") opts.dir = value;
-}
-
-function applyBoolean(opts: ReviewOptions, flag: string): void {
-	if (flag === "--finalize" || flag === "--report-only") opts.finalize = true;
-	else if (flag === "--fail-on-blocking") opts.failOnBlocking = true;
-	else if (flag === "--clean") opts.clean = true;
-	else if (flag === "--no-jev") opts.noJev = true;
-	else if (flag === "--full") opts.full = true;
-}
-
 /** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
 export function parseReviewArgs(
 	args: string[],
 	artifactDir: string = ARTIFACT_DIR,
 ): ReviewOptions {
+	const parser = ArgParser.from(args);
 	const opts = defaultOptions(artifactDir);
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (VALUE_FLAGS.has(arg)) {
-			applyValue(opts, arg, args[i + 1]);
-			i++;
-		} else if (BOOLEAN_FLAGS.has(arg)) {
-			applyBoolean(opts, arg);
-		}
-	}
+
+	const base = parser.value("--base");
+	const head = parser.value("--head");
+	const branch = parser.value("--branch");
+	const dir = parser.value("--dir");
+	if (base) opts.base = base;
+	if (head) opts.head = head;
+	if (branch) opts.branch = branch;
+	if (dir) opts.dir = dir;
+
+	if (parser.has("--finalize") || parser.has("--report-only")) opts.finalize = true;
+	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;
+	if (parser.has("--clean")) opts.clean = true;
+	if (parser.has("--no-jev")) opts.noJev = true;
+	if (parser.has("--full")) opts.full = true;
+
 	return opts;
 }

package/src/core/commands/scaffold.ts

@@ -280,83 +280,193 @@ core/
 `;
 
 // ---------------------------------------------------------------------------
-// Escrita
+// Templates (arquivo → conteúdo)
 // ---------------------------------------------------------------------------
 
-/** Escreve um arquivo do usuário somente se ausente (ou se `force`). */
-function writeUserFile(
-	ctx: ScaffoldContext,
-	relativePath: string,
-	content: string,
-): void {
-	const full = join(ctx.cwd, relativePath);
-	if (existsSync(full) && !ctx.force) {
-		ctx.skipped.push(relativePath);
-		return;
+/** Contexto de render de um template. */
+type TemplateContext = { projectName: string };
+
+/** Um arquivo da camada (caminho relativo + conteúdo). */
+interface ScaffoldTemplate {
+	readonly path: string;
+	render(context: TemplateContext): string;
+}
+
+class ConfigTemplate implements ScaffoldTemplate {
+	readonly path = "houndsman.config.ts";
+
+	render(context: TemplateContext): string {
+		return CONFIG_TEMPLATE(context.projectName);
 	}
-	mkdirSync(join(full, ".."), { recursive: true });
-	writeFileSync(full, content);
-	ctx.created.push(relativePath);
 }
 
-/** Escreve/sobrescreve um arquivo auto-gerado. */
-function writeGeneratedFile(
-	ctx: ScaffoldContext,
-	relativePath: string,
-	content: string,
-): void {
-	const full = join(ctx.cwd, relativePath);
-	mkdirSync(join(full, ".."), { recursive: true });
-	writeFileSync(full, content);
-	ctx.generated.push(relativePath);
+class WatchdogExampleTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "example.ts");
+
+	render(): string {
+		return WATCHDOG_EXAMPLE;
+	}
 }
 
-// ---------------------------------------------------------------------------
-// Camadas
-// ---------------------------------------------------------------------------
+class WatchdogsIndexTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "index.ts");
 
-/** Arquivos do usuário: config, watchdogs, exclusões e mapeamentos. */
-export function writeUserLayer(ctx: ScaffoldContext): void {
-	writeUserFile(ctx, "houndsman.config.ts", CONFIG_TEMPLATE(ctx.projectName));
-	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "example.ts"), WATCHDOG_EXAMPLE);
-	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "index.ts"), WATCHDOGS_INDEX);
-	writeUserFile(ctx, join(PROJECT_DIR, "exclusions.ts"), EXCLUSIONS_TEMPLATE);
-	writeUserFile(ctx, join(PROJECT_DIR, "doc-mappings.ts"), DOC_MAPPINGS_TEMPLATE);
+	render(): string {
+		return WATCHDOGS_INDEX;
+	}
 }
 
-/**
- * Arquivos auto-gerados: tipos, docs do skill, `.gitignore` (ignora `core/` e
- * `.runs/`) e o `SKILL.md` de cada harness. Sempre sobrescritos (é o alvo do
- * `update`).
- */
-export function syncGeneratedFiles(ctx: ScaffoldContext): void {
-	writeGeneratedFile(ctx, join(CORE_DIR, "types.ts"), TYPES_TEMPLATE);
-	writeGeneratedFile(ctx, join(PROJECT_DIR, ".gitignore"), PROJECT_GITIGNORE);
-
-	// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry point
-	// dos harnesses (escrito em `writeHarnessPointers`), não um doc da camada.
-	for (const name of readdirSync(SKILL_DIR)) {
-		if (!name.endsWith(".md") || name === SKILL_FILE) continue;
-		const raw = readFileSync(join(SKILL_DIR, name), "utf8");
-		writeGeneratedFile(
-			ctx,
-			join(CORE_SKILL_DIR, name),
-			raw.replaceAll("{{projectName}}", ctx.projectName),
+class ExclusionsTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "exclusions.ts");
+
+	render(): string {
+		return EXCLUSIONS_TEMPLATE;
+	}
+}
+
+class DocMappingsTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "doc-mappings.ts");
+
+	render(): string {
+		return DOC_MAPPINGS_TEMPLATE;
+	}
+}
+
+class TypesTemplate implements ScaffoldTemplate {
+	readonly path = join(CORE_DIR, "types.ts");
+
+	render(): string {
+		return TYPES_TEMPLATE;
+	}
+}
+
+class GitignoreTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, ".gitignore");
+
+	render(): string {
+		return PROJECT_GITIGNORE;
+	}
+}
+
+class SkillDocTemplate implements ScaffoldTemplate {
+	private readonly fileName: string;
+
+	constructor(fileName: string) {
+		this.fileName = fileName;
+	}
+
+	get path(): string {
+		return join(CORE_SKILL_DIR, this.fileName);
+	}
+
+	render(context: TemplateContext): string {
+		return readFileSync(join(SKILL_DIR, this.fileName), "utf8").replaceAll(
+			"{{projectName}}",
+			context.projectName,
 		);
 	}
+}
+
+class HarnessPointerTemplate implements ScaffoldTemplate {
+	private readonly harness: Harness;
 
-	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
+	constructor(harness: Harness) {
+		this.harness = harness;
+	}
+
+	get path(): string {
+		return join(`.${this.harness}`, "skills", "houndsman", SKILL_FILE);
+	}
+
+	render(context: TemplateContext): string {
+		return readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8").replaceAll(
+			"{{projectName}}",
+			context.projectName,
+		);
+	}
 }
 
-/**
- * Escreve o `SKILL.md` do harness a partir do asset base (`src/skill/SKILL.md`),
- * resolvendo `{{projectName}}`. O texto do skill vive no asset — não aqui.
- */
-function writeHarnessPointers(ctx: ScaffoldContext, harness: Harness): void {
-	const raw = readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8");
-	writeGeneratedFile(
-		ctx,
-		join(`.${harness}`, "skills", "houndsman", SKILL_FILE),
-		raw.replaceAll("{{projectName}}", ctx.projectName),
-	);
+// ---------------------------------------------------------------------------
+// Scaffolder
+// ---------------------------------------------------------------------------
+
+/** Escreve as camadas do projeto (`setup`) e sincroniza os auto-gerados (`update`). */
+export class ProjectScaffolder {
+	private readonly ctx: ScaffoldContext;
+
+	constructor(ctx: ScaffoldContext) {
+		this.ctx = ctx;
+	}
+
+	/** Arquivos do usuário: config, watchdogs, exclusões e mapeamentos. */
+	writeUserLayer(): void {
+		const context = this.context();
+		const templates: ScaffoldTemplate[] = [
+			new ConfigTemplate(),
+			new WatchdogExampleTemplate(),
+			new WatchdogsIndexTemplate(),
+			new ExclusionsTemplate(),
+			new DocMappingsTemplate(),
+		];
+		for (const template of templates) this.writeUserFile(template, context);
+	}
+
+	/** Arquivos auto-gerados (sempre sobrescritos). */
+	syncGenerated(): void {
+		const context = this.context();
+		this.writeGeneratedFile(new TypesTemplate(), context);
+		this.writeGeneratedFile(new GitignoreTemplate(), context);
+
+		// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry
+		// point dos harnesses, não um doc da camada.
+		for (const name of readdirSync(SKILL_DIR)) {
+			if (!name.endsWith(".md") || name === SKILL_FILE) continue;
+			this.writeGeneratedFile(new SkillDocTemplate(name), context);
+		}
+
+		for (const harness of this.ctx.harnesses) {
+			this.writeGeneratedFile(new HarnessPointerTemplate(harness), context);
+		}
+	}
+
+	private context(): TemplateContext {
+		return { projectName: this.ctx.projectName };
+	}
+
+	/** Usuário: só escreve se ausente (ou `force`). */
+	private writeUserFile(template: ScaffoldTemplate, context: TemplateContext): void {
+		const full = join(this.ctx.cwd, template.path);
+		if (existsSync(full) && !this.ctx.force) {
+			this.ctx.skipped.push(template.path);
+			return;
+		}
+		mkdirSync(join(full, ".."), { recursive: true });
+		writeFileSync(full, template.render(context));
+		this.ctx.created.push(template.path);
+	}
+
+	/** Auto-gerado: sempre sobrescreve. */
+	private writeGeneratedFile(
+		template: ScaffoldTemplate,
+		context: TemplateContext,
+	): void {
+		const full = join(this.ctx.cwd, template.path);
+		mkdirSync(join(full, ".."), { recursive: true });
+		writeFileSync(full, template.render(context));
+		this.ctx.generated.push(template.path);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Fachada (compatibilidade)
+// ---------------------------------------------------------------------------
+
+/** Arquivos do usuário (setup). */
+export function writeUserLayer(ctx: ScaffoldContext): void {
+	new ProjectScaffolder(ctx).writeUserLayer();
+}
+
+/** Arquivos auto-gerados (setup/update). */
+export function syncGeneratedFiles(ctx: ScaffoldContext): void {
+	new ProjectScaffolder(ctx).syncGenerated();
 }

package/src/core/commands/setup.ts

@@ -49,27 +49,32 @@ function ensurePackageScript(ctx: ScaffoldContext): void {
 	ctx.created.push("package.json#scripts.houndsman");
 }
 
-/** Cria a configuração inicial do projeto. */
-export async function runSetupCommand(options: SetupOptions): Promise<void> {
+/** Cria a configuração inicial do projeto. Devolve as mensagens do CLI. */
+export async function runSetupCommand(options: SetupOptions): Promise<string[]> {
 	const ctx = createScaffoldContext(
 		options.cwd,
 		options.args,
 		options.args.includes("--force"),
 	);
 
-	console.log(`→ Configurando houndsman em ${ctx.cwd} (projeto: ${ctx.projectName})`);
+	const messages = [
+		`→ Configurando houndsman em ${ctx.cwd} (projeto: ${ctx.projectName})`,
+	];
 
 	writeUserLayer(ctx);
 	syncGeneratedFiles(ctx);
 	ensurePackageScript(ctx);
 
-	for (const path of ctx.created) console.log(`  + ${path}`);
-	for (const path of ctx.skipped) console.log(`  = ${path} (mantido)`);
-	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+	for (const path of ctx.created) messages.push(`  + ${path}`);
+	for (const path of ctx.skipped) messages.push(`  = ${path} (mantido)`);
+	for (const path of ctx.generated) messages.push(`  ~ ${path} (auto)`);
 
-	console.log("\nPróximos passos:");
-	console.log("  1. Ajuste `houndsman.config.ts` e `.houndsman/watchdogs/`.");
-	console.log("  2. Valide: bun run houndsman doctor");
-	console.log("  3. Prepare a revisão: bun run houndsman");
-	console.log("  ·  Sincronizar arquivos auto-gerados: bun run houndsman update");
+	messages.push(
+		"\nPróximos passos:",
+		"  1. Ajuste `houndsman.config.ts` e `.houndsman/watchdogs/`.",
+		"  2. Valide: bun run houndsman doctor",
+		"  3. Prepare a revisão: bun run houndsman",
+		"  ·  Sincronizar arquivos auto-gerados: bun run houndsman update",
+	);
+	return messages;
 }