@payconductor/houndsman 0.2.0 → 0.4.0

package/src/server/client/constants.ts

@@ -2,7 +2,15 @@
  * Constantes de apresentação do cliente (labels, ordem, emojis).
  */
 
-import type { Decision, ExecState, RunStatus, RunSummary, Severity } from "./types";
+import type {
+	ArtifactKind,
+	ArtifactMeta,
+	Decision,
+	ExecState,
+	RunStatus,
+	RunSummary,
+	Severity,
+} from "./types";
 
 /** Rótulo de exibição de cada severidade (o CSS dá a cor via `sev-<nivel>`). */
 export const SEVERITY_LABELS: Record<Severity, string> = {
@@ -58,34 +66,132 @@ export function describeRunStatus(
 	return { kind: status, label: RUN_STATUS_LABELS[status], timeout: false };
 }
 
-/** Artefatos que podem ser lidos na aba "Artefatos". */
-export const ARTIFACTS = [
-	"manifest.json",
-	"classification.json",
-	"candidates.json",
-	"context-summary.json",
-	"review.md",
-] as const;
-
-export type ArtifactName = (typeof ARTIFACTS)[number];
-
-/** Descrição de cada artefato (mostrada ao selecioná-lo na aba). */
-export const ARTIFACT_INFO: Record<ArtifactName, string> = {
-	"manifest.json":
-		"Resumo da execução: watchdogs ativos, arquivos, orçamento, churn, Jev e contexto da PR.",
-	"classification.json":
-		"Classificação do diff: watchdogs ativados por arquivo, status (A/M/D/R) e churn por arquivo.",
-	"candidates.json":
-		"Indícios da pré-análise Jev (regra + arquivo + confiança) — não são achados.",
-	"context-summary.json":
-		"Resumo da PR (objetivo, motivação e alterações) gerado no Passo 0.",
-	"review.md": "Relatório consolidado da revisão — o entregável.",
+/** Ordem canônica dos tipos de artefato na lista da UI. */
+const KIND_ORDER: ArtifactKind[] = [
+	"review",
+	"domain-review",
+	"verify",
+	"brief",
+	"manifest",
+	"classification",
+	"candidates",
+	"context",
+	"context-brief",
+	"context-summary",
+	"finding-report",
+	"other",
+];
+
+/** Grupo visual de cada tipo (relatórios, briefs, núcleo, contexto…). */
+const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: number }> =
+	{
+		review: { key: "report", label: "Relatórios", order: 0 },
+		"domain-review": { key: "report", label: "Relatórios", order: 0 },
+		verify: { key: "verify", label: "Verificação", order: 1 },
+		brief: { key: "brief", label: "Briefs (auditoria)", order: 2 },
+		manifest: { key: "core", label: "Núcleo da revisão", order: 3 },
+		classification: { key: "core", label: "Núcleo da revisão", order: 3 },
+		candidates: { key: "core", label: "Núcleo da revisão", order: 3 },
+		context: { key: "context", label: "Contexto da PR", order: 4 },
+		"context-brief": { key: "context", label: "Contexto da PR", order: 4 },
+		"context-summary": { key: "context", label: "Contexto da PR", order: 4 },
+		"finding-report": { key: "other", label: "Outros", order: 5 },
+		other: { key: "other", label: "Outros", order: 5 },
+	};
+
+/** Rótulo curto do tipo (badge do item). */
+export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
+	review: "relatório",
+	"domain-review": "domínio",
+	verify: "verify",
+	brief: "brief",
+	manifest: "manifesto",
+	classification: "classificação",
+	candidates: "jev",
+	context: "contexto",
+	"context-brief": "brief ctx",
+	"context-summary": "resumo ctx",
+	"finding-report": "findings",
+	other: "outro",
 };
 
+/** Nome exibido (briefs perdem o prefixo `briefs/`). */
+export function displayArtifactName(meta: ArtifactMeta): string {
+	return meta.name.startsWith("briefs/")
+		? meta.name.slice("briefs/".length)
+		: meta.name;
+}
+
+/** Descrição curta do artefato (cabeçalho do painel). */
+export function describeArtifact(meta: ArtifactMeta): string {
+	switch (meta.kind) {
+		case "review":
+			return "Relatório consolidado da revisão — o entregável.";
+		case "domain-review":
+			return "Relatório isolado do domínio: achados daquele watchdog.";
+		case "verify":
+			return "Resultado do `findings verify` (resolvidos, persistentes e incertos).";
+		case "brief":
+			return "Instruções enviadas ao subagente (auditoria do prompt).";
+		case "manifest":
+			return "Resumo da execução: watchdogs, arquivos, orçamento, churn, Jev e contexto.";
+		case "classification":
+			return "Classificação do diff: watchdogs ativados por arquivo, status (A/M/D/R) e churn.";
+		case "candidates":
+			return "Indícios da pré-análise Jev (regra + arquivo + confiança) — não são achados.";
+		case "context":
+			return "Payload bruto da PR coletado via `gh` (ou marcador de indisponível).";
+		case "context-brief":
+			return "Brief do subagente que resume o contexto da PR.";
+		case "context-summary":
+			return "Resumo da PR (objetivo, motivação e alterações) gerado no Passo 0.";
+		default:
+			return meta.name;
+	}
+}
+
+/** `true` se o conteúdo deve ser renderizado com destaque de JSON. */
+export function isJsonArtifact(meta: ArtifactMeta | undefined): boolean {
+	if (!meta) return false;
+	return meta.contentType.includes("json") || meta.name.toLowerCase().endsWith(".json");
+}
+
+/** Agrupa os artefatos para a navegação lateral (ordem estável). */
+export function groupArtifacts(
+	items: ArtifactMeta[],
+): { key: string; label: string; items: ArtifactMeta[] }[] {
+	const groups = new Map<
+		string,
+		{ key: string; label: string; order: number; items: ArtifactMeta[] }
+	>();
+	for (const item of items) {
+		const meta = GROUP_BY_KIND[item.kind] ?? GROUP_BY_KIND.other;
+		const group = groups.get(meta.key) ?? {
+			key: meta.key,
+			label: meta.label,
+			order: meta.order,
+			items: [],
+		};
+		group.items.push(item);
+		groups.set(meta.key, group);
+	}
+	return [...groups.values()]
+		.sort((a, b) => a.order - b.order)
+		.map((group) => ({
+			key: group.key,
+			label: group.label,
+			items: group.items.sort(
+				(a, b) =>
+					KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) ||
+					a.name.localeCompare(b.name),
+			),
+		}));
+}
+
 /** Legenda única de cada aba (explica o que a aba é; mostrada quando selecionada). */
 export const TAB_CAPTIONS = {
 	findings:
 		"Triagem dos achados da revisão: decida Executar, Ignorar ou deixe Pendente — o comentário orienta o auto-fix. Agente: houndsman findings list --decision pending --json · findings done <id>.",
 	artifacts:
-		"Artefatos brutos da run: manifesto, classificação, candidatos Jev, contexto da PR e o relatório consolidado (review.md).",
+		"Artefatos persistidos da run: relatórios, briefs de auditoria, manifesto, classificação, Jev, contexto da PR e verificação. JSON com destaque de sintaxe.",
 } as const;

package/src/server/client/json-highlight.ts

@@ -0,0 +1,55 @@
+/**
+ * Destaque de sintaxe JSON (cliente) — implementação própria e leve.
+ *
+ * Não puxa lib de highlight: tokeniza o texto já formatado e devolve spans.
+ * Funciona para qualquer JSON gerado pelo houndsman (manifest, classification,
+ * context, candidates, …).
+ */
+
+export type JsonTokenType = "plain" | "key" | "string" | "number" | "literal" | "punct";
+
+export type JsonToken = { text: string; type: JsonTokenType };
+
+const TOKEN =
+	/("(?:\\.|[^"\\])*")(\s*:)?|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|\b(true|false|null)\b|([{}[\],:])/g;
+
+/** Pretty-print best-effort; devolve o original se não for JSON válido. */
+export function formatJson(text: string): string {
+	try {
+		return JSON.stringify(JSON.parse(text), null, 2);
+	} catch {
+		return text;
+	}
+}
+
+/** Tokeniza o JSON preservando o texto original (inclusive espaços/quebras). */
+export function highlightJson(text: string): JsonToken[] {
+	const tokens: JsonToken[] = [];
+	let last = 0;
+	for (const match of text.matchAll(TOKEN)) {
+		const index = match.index ?? 0;
+		if (index > last) {
+			tokens.push({ text: text.slice(last, index), type: "plain" });
+		}
+		if (match[1] !== undefined) {
+			tokens.push({
+				text: match[1],
+				type: match[2] !== undefined ? "key" : "string",
+			});
+			if (match[2] !== undefined) {
+				tokens.push({ text: match[2], type: "punct" });
+			}
+		} else if (match[3] !== undefined) {
+			tokens.push({ text: match[3], type: "number" });
+		} else if (match[4] !== undefined) {
+			tokens.push({ text: match[4], type: "literal" });
+		} else if (match[5] !== undefined) {
+			tokens.push({ text: match[5], type: "punct" });
+		}
+		last = index + match[0].length;
+	}
+	if (last < text.length) {
+		tokens.push({ text: text.slice(last), type: "plain" });
+	}
+	return tokens;
+}

package/src/server/client/markdown.ts

@@ -0,0 +1,153 @@
+/**
+ * Markdown mínimo do campo `action` (cliente).
+ *
+ * Suporta o suficiente para instruções curtas: parágrafos, quebras de linha,
+ * listas, blockquote, blocos de código e formatação inline (`code`, **bold**,
+ * *itálico*, links). Sem lib externa e sem HTML cru.
+ */
+
+export type MarkdownBlock =
+	| { type: "paragraph"; text: string }
+	| { type: "list"; ordered: boolean; items: string[] }
+	| { type: "code"; language: string | null; code: string }
+	| { type: "quote"; text: string };
+
+export type InlineToken =
+	| { type: "text"; text: string }
+	| { type: "code"; text: string }
+	| { type: "strong"; text: string }
+	| { type: "em"; text: string }
+	| { type: "link"; text: string; url: string };
+
+const FENCE = /^\s*```(\S*)\s*$/;
+const BULLET = /^\s*[-*+]\s+(.*)$/;
+const ORDERED = /^\s*\d+\.\s+(.*)$/;
+const QUOTE = /^\s*>\s?(.*)$/;
+
+function isBlockStart(line: string): boolean {
+	return (
+		FENCE.test(line) || BULLET.test(line) || ORDERED.test(line) || QUOTE.test(line)
+	);
+}
+
+/** Divide o texto em blocos simples (sem aninhamento profundo). */
+export function parseMarkdown(text: string): MarkdownBlock[] {
+	const lines = text.replace(/\r\n?/g, "\n").split("\n");
+	const blocks: MarkdownBlock[] = [];
+	let index = 0;
+
+	while (index < lines.length) {
+		const line = lines[index];
+		if (line.trim().length === 0) {
+			index++;
+			continue;
+		}
+
+		const fence = FENCE.exec(line);
+		if (fence) {
+			const language = fence[1] || null;
+			const code: string[] = [];
+			index++;
+			while (index < lines.length && !FENCE.test(lines[index])) {
+				code.push(lines[index]);
+				index++;
+			}
+			if (index < lines.length) index++;
+			blocks.push({ type: "code", language, code: code.join("\n") });
+			continue;
+		}
+
+		if (BULLET.test(line)) {
+			const items: string[] = [];
+			while (index < lines.length) {
+				const item = BULLET.exec(lines[index]);
+				if (!item) break;
+				items.push(item[1]);
+				index++;
+			}
+			blocks.push({ type: "list", ordered: false, items });
+			continue;
+		}
+
+		if (ORDERED.test(line)) {
+			const items: string[] = [];
+			while (index < lines.length) {
+				const item = ORDERED.exec(lines[index]);
+				if (!item) break;
+				items.push(item[1]);
+				index++;
+			}
+			blocks.push({ type: "list", ordered: true, items });
+			continue;
+		}
+
+		if (QUOTE.test(line)) {
+			const quote: string[] = [];
+			while (index < lines.length) {
+				const item = QUOTE.exec(lines[index]);
+				if (!item) break;
+				quote.push(item[1]);
+				index++;
+			}
+			blocks.push({ type: "quote", text: quote.join("\n") });
+			continue;
+		}
+
+		const paragraph: string[] = [line];
+		index++;
+		while (
+			index < lines.length &&
+			lines[index].trim().length > 0 &&
+			!isBlockStart(lines[index])
+		) {
+			paragraph.push(lines[index]);
+			index++;
+		}
+		blocks.push({ type: "paragraph", text: paragraph.join("\n") });
+	}
+
+	return blocks;
+}
+
+/** Tokeniza formatação inline preservando o texto e a ordem dos marcadores. */
+export function parseInline(text: string): InlineToken[] {
+	const tokens: InlineToken[] = [];
+	// Ordem importa: code/bold antes de itálico; `_` exige fronteira de palavra.
+	const pattern =
+		/`[^`\n]+`|\*\*[^*\n]+\*\*|__[^_\n]+__|\*[^*\n]+\*|(?<![\w])_[^_\n]+_(?![\w])|\[[^\]\n]+\]\([^)\s]+\)/g;
+	let last = 0;
+	for (const match of text.matchAll(pattern)) {
+		const start = match.index ?? 0;
+		if (start > last) {
+			tokens.push({ type: "text", text: text.slice(last, start) });
+		}
+		const raw = match[0];
+		if (raw.startsWith("`")) {
+			tokens.push({ type: "code", text: raw.slice(1, -1) });
+		} else if (raw.startsWith("**") || raw.startsWith("__")) {
+			tokens.push({ type: "strong", text: raw.slice(2, -2) });
+		} else if (raw.startsWith("*") || raw.startsWith("_")) {
+			tokens.push({ type: "em", text: raw.slice(1, -1) });
+		} else {
+			const link = /^\[([^\]]+)\]\(([^)\s]+)\)$/.exec(raw);
+			if (link) {
+				tokens.push({ type: "link", text: link[1], url: link[2] });
+			} else {
+				tokens.push({ type: "text", text: raw });
+			}
+		}
+		last = start + raw.length;
+	}
+	if (last < text.length) {
+		tokens.push({ type: "text", text: text.slice(last) });
+	}
+	return tokens;
+}
+
+/** URL segura para links de markdown (evita `javascript:` e afins). */
+export function safeUrl(url: string): string | null {
+	const value = url.trim();
+	if (/^(https?:|mailto:)/i.test(value)) return value;
+	if (value.startsWith("/") && !value.startsWith("//")) return value;
+	return null;
+}

package/src/server/client/types.ts

@@ -50,6 +50,29 @@ export type Summary = {
 	bySeverity: Record<Severity, number>;
 };
 
+/** Espécie de artefato persistido (espelha `core/storage/types.ts`). */
+export type ArtifactKind =
+	| "brief"
+	| "classification"
+	| "manifest"
+	| "candidates"
+	| "context"
+	| "context-brief"
+	| "context-summary"
+	| "finding-report"
+	| "review"
+	| "domain-review"
+	| "verify"
+	| "other";
+
+/** Metadados de artefato retornados pela API (sem conteúdo). */
+export type ArtifactMeta = {
+	name: string;
+	kind: ArtifactKind;
+	contentType: string;
+	updatedAt: string;
+};
+
 export type RunSummary = {
 	slug: string;
 	branch: string;