@zaip-ai/cli 1.0.6 → 1.0.7

package/templates/.agents/dashboard/modules/traceability/src/react/TaskTracePanel.tsx

@@ -0,0 +1,681 @@
+import { formatCompactNumber, formatCurrency, formatDurationMs } from "@zaip-ai/dashboard-ui";
+import {
+  ArrowRight,
+  BadgeCheck,
+  Boxes,
+  CalendarDays,
+  Check,
+  CircleGauge,
+  ClipboardList,
+  Clock3,
+  Copy,
+  FileCheck2,
+  FileStack,
+  Gavel,
+  GitBranch,
+  Link2,
+  LoaderCircle,
+  type LucideIcon,
+  Route,
+  Settings,
+  ShieldCheck,
+  Workflow,
+  X,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+import type { TaskTrace, TraceDocument, TraceStage } from "../contracts.js";
+import "./traceability-navigation.css";
+import "./traceability-embedded.css";
+import "./traceability-usage.css";
+import "./traceability.css";
+import "./traceability-stage-detail.css";
+import "./traceability-stage-dialog.css";
+import { TraceDocumentDialog } from "./TraceDocumentDialog.js";
+import { TraceStageDetail } from "./TraceStageDetail.js";
+import { TraceStageDialog } from "./TraceStageDialog.js";
+
+export const traceStages: readonly TraceStage[] = [
+  "definition",
+  "planning",
+  "execution",
+  "decisions",
+  "verification",
+  "evidence",
+];
+const loadingIdentifierKeys = ["task", "change", "spec", "prd"] as const;
+const loadingMetricKeys = ["coverage", "documents", "evidence", "links"] as const;
+const riskLabels = {
+  "pt-BR": { lite: "Leve", standard: "Padrão", critical: "Crítico" },
+  "en-US": { lite: "Lite", standard: "Standard", critical: "Critical" },
+} as const;
+const stageIcons: Record<TraceStage, LucideIcon> = {
+  definition: ClipboardList,
+  planning: GitBranch,
+  execution: Settings,
+  decisions: Gavel,
+  verification: ShieldCheck,
+  evidence: FileCheck2,
+};
+export const traceStageArtifactsPt: Record<TraceStage, string> = {
+  definition: "PRD · Requisitos",
+  planning: "SPEC · Change",
+  execution: "Tarefas · DAG · Runs · arquivos",
+  decisions: "Decisões do planejamento e da execução",
+  verification: "Testes · revisões · evals · checks",
+  evidence: "Evidências · resultados · rastreabilidade",
+};
+export const traceStageArtifactsEn: Record<TraceStage, string> = {
+  definition: "PRD · Requirements",
+  planning: "SPEC · Change",
+  execution: "Tasks · DAG · Runs · files",
+  decisions: "Planning and execution decisions",
+  verification: "Tests · reviews · evals · checks",
+  evidence: "Evidence · results · traceability",
+};
+export const traceStageArtifacts = traceStageArtifactsPt;
+export type TraceLocale = "pt-BR" | "en-US";
+
+export function traceIdentifierLinks(
+  trace: Pick<TaskTrace, "task_id" | "change_id" | "spec_id" | "prd_id">,
+  handlers: {
+    onOpenChange: ((changeId: string) => void) | undefined;
+    onOpenPrd: ((prdId: string) => void) | undefined;
+    onOpenSpec: ((specId: string) => void) | undefined;
+  },
+) {
+  return [
+    { label: "Task", value: trace.task_id, onOpen: undefined },
+    { label: "Change", value: trace.change_id, onOpen: handlers.onOpenChange },
+    { label: "SPEC", value: trace.spec_id, onOpen: handlers.onOpenSpec },
+    { label: "PRD", value: trace.prd_id, onOpen: handlers.onOpenPrd },
+  ] as const;
+}
+
+export const traceStageCopyPt: Record<TraceStage, { label: string; description: string }> = {
+  definition: {
+    label: "Definição (PRD + Requisitos)",
+    description: "Objetivo, contexto e critérios que definem o trabalho.",
+  },
+  planning: {
+    label: "Planejamento (SPEC + Change)",
+    description: "Escopo, solução e mudanças previstas antes da execução.",
+  },
+  execution: {
+    label: "Execução (Tarefas ou DAG)",
+    description: "Tarefas, dependências da DAG, Runs e arquivos produzidos.",
+  },
+  decisions: {
+    label: "Decisões (Plano e Execução)",
+    description: "Decisões humanas e da IA tomadas no planejamento e na execução.",
+  },
+  verification: {
+    label: "Verificação (Testes + Revisões)",
+    description: "Testes, revisões, evals e checks comparam o resultado aos Critérios de Aceite.",
+  },
+  evidence: {
+    label: "Evidências (Resultados + Rastreabilidade)",
+    description: "Provas reproduzíveis vinculadas às Tasks, Changes, Runs e Critérios de Aceite.",
+  },
+};
+export const traceStageCopyEn: Record<TraceStage, { label: string; description: string }> = {
+  definition: {
+    label: "Definition (PRD + Requirements)",
+    description: "Objective, context, and criteria that define the work.",
+  },
+  planning: {
+    label: "Planning (SPEC + Change)",
+    description: "Scope, solution, and changes planned before execution.",
+  },
+  execution: {
+    label: "Execution (Tasks or DAG)",
+    description: "Tasks, DAG dependencies, Runs, and produced files.",
+  },
+  decisions: {
+    label: "Decisions (Plan and Execution)",
+    description: "Human and AI decisions made during planning and execution.",
+  },
+  verification: {
+    label: "Verification (Tests + Reviews)",
+    description: "Tests, reviews, evals, and checks compare results with acceptance criteria.",
+  },
+  evidence: {
+    label: "Evidence (Results + Traceability)",
+    description: "Reproducible proof linked to Tasks, Changes, Runs, and acceptance criteria.",
+  },
+};
+export const traceCopy = {
+  "pt-BR": {
+    aria: "Rastreabilidade da task",
+    coverage: "etapas rastreadas",
+    evidence: "evidências",
+    close: "Fechar",
+    empty: "Nenhum documento relacionado.",
+    closeDocument: "Fechar documento",
+    back: "Voltar às etapas",
+    previous: "Anterior",
+    next: "Próxima",
+    documents: "Documentos",
+    types: "Tipos",
+    evidenceMetric: "Evidências",
+    taskFirst: "Task-first",
+    specDriven: "Spec-driven",
+    copyId: "Copiar ID",
+    copied: "ID copiado",
+    unlinked: "Não vinculado",
+    recorded: "Registrada em",
+    pending: "Pendente",
+    missingTimestamp: "Sem data/hora",
+    tests: "testes registrados",
+    time: "Tempo",
+    tokens: "Tokens",
+    cost: "Custo",
+    measuredRuns: "Runs medidas",
+    items: "itens",
+    navigation: "Navegação entre etapas",
+    of: "de",
+    stageDetails: "Detalhes da etapa",
+    document: "Documento",
+  },
+  "en-US": {
+    aria: "Task traceability",
+    coverage: "tracked stages",
+    evidence: "evidence items",
+    close: "Close",
+    empty: "No related document.",
+    closeDocument: "Close document",
+    back: "Back to stages",
+    previous: "Previous",
+    next: "Next",
+    documents: "Documents",
+    types: "Types",
+    evidenceMetric: "Evidence",
+    taskFirst: "Task-first",
+    specDriven: "Spec-driven",
+    copyId: "Copy ID",
+    copied: "ID copied",
+    unlinked: "Not linked",
+    recorded: "Recorded at",
+    pending: "Pending",
+    missingTimestamp: "Missing date/time",
+    tests: "recorded tests",
+    time: "Time",
+    tokens: "Tokens",
+    cost: "Cost",
+    measuredRuns: "measured Runs",
+    items: "items",
+    navigation: "Stage navigation",
+    of: "of",
+    stageDetails: "Stage details",
+    document: "Document",
+  },
+} as const;
+
+export function TaskTraceLoadingPanel({
+  taskId,
+  locale = "pt-BR",
+}: {
+  taskId: string;
+  locale?: TraceLocale;
+}) {
+  const isPtBr = locale === "pt-BR";
+  return (
+    <div className="trace-backdrop">
+      <section
+        aria-busy="true"
+        aria-label={isPtBr ? "Carregando rastreabilidade" : "Loading traceability"}
+        aria-live="polite"
+        className="trace-panel trace-loading-panel"
+        role="dialog"
+      >
+        <header className="trace-panel-header">
+          <div className="trace-heading">
+            <span className="trace-heading-icon trace-loading-icon" aria-hidden="true">
+              <LoaderCircle size={22} strokeWidth={1.8} />
+            </span>
+            <div className="trace-task-summary-content">
+              <h2>{isPtBr ? "Carregando rastreabilidade" : "Loading traceability"}</h2>
+              <p>{taskId}</p>
+            </div>
+          </div>
+          <span className="trace-loading-status">
+            <LoaderCircle aria-hidden="true" size={15} strokeWidth={2} />
+            {isPtBr ? "Preparando trace" : "Preparing trace"}
+          </span>
+        </header>
+        <div className="trace-loading-identifiers" aria-hidden="true">
+          {loadingIdentifierKeys.map((key) => (
+            <span key={key} />
+          ))}
+        </div>
+        <div className="trace-loading-metrics" aria-hidden="true">
+          {loadingMetricKeys.map((key) => (
+            <span key={key} />
+          ))}
+        </div>
+        <div className="trace-loading-stages" aria-hidden="true">
+          {traceStages.map((stage) => (
+            <span key={stage} />
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+export function TaskTracePanel({
+  trace,
+  locale = "pt-BR",
+  onClose,
+  onOpenChange,
+  onOpenPrd,
+  onOpenSpec,
+  embedded = false,
+}: {
+  trace: TaskTrace;
+  locale?: TraceLocale;
+  onClose: () => void;
+  onOpenChange?: (changeId: string) => void;
+  onOpenPrd?: (prdId: string) => void;
+  onOpenSpec?: (specId: string) => void;
+  embedded?: boolean;
+}) {
+  const [selected, setSelected] = useState<TraceDocument | null>(null);
+  const [activeStage, setActiveStage] = useState<TraceStage | null>(null);
+  const [copiedTaskId, setCopiedTaskId] = useState(false);
+  const copy = traceCopy[locale];
+  const stageCopy = locale === "en-US" ? traceStageCopyEn : traceStageCopyPt;
+  const stageArtifacts = locale === "en-US" ? traceStageArtifactsEn : traceStageArtifactsPt;
+  const grouped = useMemo(
+    () =>
+      new Map(
+        traceStages.map((stage) => [
+          stage,
+          trace.documents.filter((document) => document.stage === stage),
+        ]),
+      ),
+    [trace.documents],
+  );
+  const stageRecords = useMemo(
+    () => new Map(trace.stages.map((record) => [record.stage, record])),
+    [trace.stages],
+  );
+  const coveragePercentage = Math.round(
+    (trace.coverage.stages_with_timestamps / trace.coverage.total_stages) * 100,
+  );
+  const linkedArtifacts = [trace.task_id, trace.change_id, trace.spec_id, trace.prd_id].filter(
+    Boolean,
+  ).length;
+  const identifiers = traceIdentifierLinks(trace, { onOpenChange, onOpenPrd, onOpenSpec });
+  const createdAt = formatTraceCreatedAt(trace.task_created_at, locale);
+  const elapsed = formatTraceElapsed(trace.task_created_at, locale);
+  const copyTaskId = async () => {
+    try {
+      await navigator.clipboard.writeText(trace.task_id);
+      setCopiedTaskId(true);
+      window.setTimeout(() => setCopiedTaskId(false), 2_000);
+    } catch {
+      setCopiedTaskId(false);
+    }
+  };
+
+  return (
+    <div className={embedded ? "trace-embedded" : "trace-backdrop"}>
+      <section
+        aria-label={copy.aria}
+        aria-modal={embedded ? undefined : "true"}
+        className="trace-panel"
+        role="dialog"
+      >
+        <header className="trace-panel-header">
+          <div className="trace-heading">
+            <span className="trace-heading-icon" aria-hidden="true">
+              <Route size={22} strokeWidth={1.8} />
+            </span>
+            <div className="trace-task-summary-content">
+              <div className="trace-heading-title">
+                <h2>
+                  <span className="trace-title-prefix">Trace:</span>{" "}
+                  {trace.task_title || trace.task_id}
+                </h2>
+              </div>
+              <p>
+                {locale === "pt-BR"
+                  ? "Visão completa do ciclo de desenvolvimento"
+                  : "Complete development lifecycle view"}
+              </p>
+            </div>
+          </div>
+          <div className="trace-header-actions">
+            <TraceUsageStrip copy={copy} locale={locale} usage={trace.usage} />
+            {embedded ? null : (
+              <button
+                className="trace-close-button"
+                aria-label={copy.close}
+                onClick={onClose}
+                type="button"
+              >
+                <X aria-hidden="true" size={20} strokeWidth={2} />
+              </button>
+            )}
+          </div>
+        </header>
+        <section
+          className="trace-task-summary"
+          aria-label={locale === "pt-BR" ? "Resumo da tarefa" : "Task summary"}
+        >
+          <article>
+            <CalendarDays aria-hidden="true" size={17} strokeWidth={1.8} />
+            <div className="trace-task-summary-content">
+              <span>{locale === "pt-BR" ? "Criada em" : "Created at"}</span>
+              <strong>{createdAt}</strong>
+            </div>
+          </article>
+          <article>
+            <Clock3 aria-hidden="true" size={17} strokeWidth={1.8} />
+            <div className="trace-task-summary-content">
+              <span>{locale === "pt-BR" ? "Desde a criação" : "Since creation"}</span>
+              <strong>{elapsed}</strong>
+            </div>
+          </article>
+          <article className="trace-task-progress">
+            <CircleGauge aria-hidden="true" size={17} strokeWidth={1.8} />
+            <div className="trace-task-summary-content trace-task-progress-content">
+              <span>{locale === "pt-BR" ? "Progresso" : "Progress"}</span>
+              <strong>{trace.task_progress}%</strong>
+              <progress max={100} value={trace.task_progress} />
+            </div>
+          </article>
+          <article className="trace-task-classification">
+            <BadgeCheck aria-hidden="true" size={17} strokeWidth={1.8} />
+            <div className="trace-task-summary-content">
+              <span>{locale === "pt-BR" ? "Classificação" : "Classification"}</span>
+              <div className="trace-task-badges">
+                <span className="trace-mode-badge">
+                  <Workflow aria-hidden="true" size={12} strokeWidth={2} />
+                  {trace.spec_id === null ? copy.taskFirst : copy.specDriven}
+                </span>
+                {trace.task_risk ? (
+                  <span className="trace-risk-badge" data-risk={trace.task_risk}>
+                    <ShieldCheck aria-hidden="true" size={12} strokeWidth={2} />
+                    {riskLabels[locale][trace.task_risk]}
+                  </span>
+                ) : null}
+              </div>
+            </div>
+          </article>
+        </section>
+        <section
+          className="trace-overview trace-lineage"
+          aria-label={locale === "pt-BR" ? "Identificadores vinculados" : "Linked identifiers"}
+        >
+          {identifiers.map(({ label, value, onOpen }) => {
+            const canNavigate = value !== null && onOpen !== undefined;
+            const isTaskIdentifier = label === "Task" && value !== null;
+            const content = (
+              <>
+                <div className="trace-identifier-content">
+                  <span>
+                    <Link2 aria-hidden="true" size={11} strokeWidth={2} />
+                    {label}
+                  </span>
+                  <strong title={value ?? copy.unlinked}>{value ?? copy.unlinked}</strong>
+                </div>
+                {isTaskIdentifier ? (
+                  <button
+                    aria-label={
+                      copiedTaskId
+                        ? locale === "pt-BR"
+                          ? "ID da tarefa copiado"
+                          : "Task ID copied"
+                        : locale === "pt-BR"
+                          ? "Copiar ID da tarefa"
+                          : "Copy task ID"
+                    }
+                    className="trace-identifier-copy"
+                    onClick={() => void copyTaskId()}
+                    title={copiedTaskId ? (locale === "pt-BR" ? "Copiado" : "Copied") : undefined}
+                    type="button"
+                  >
+                    {copiedTaskId ? (
+                      <Check aria-hidden="true" size={15} />
+                    ) : (
+                      <Copy aria-hidden="true" size={15} />
+                    )}
+                  </button>
+                ) : null}
+                {canNavigate ? <ArrowRight aria-hidden="true" size={15} strokeWidth={1.9} /> : null}
+              </>
+            );
+            return (
+              <article
+                key={label}
+                data-empty={value === null}
+                data-linked={value !== null}
+                data-navigable={canNavigate}
+              >
+                {canNavigate ? (
+                  <button
+                    aria-label={`${locale === "pt-BR" ? "Abrir" : "Open"} ${label}: ${value}`}
+                    className="trace-identifier-navigation"
+                    onClick={() => onOpen(value)}
+                    type="button"
+                  >
+                    {content}
+                  </button>
+                ) : (
+                  <div className="trace-identifier-static">{content}</div>
+                )}
+              </article>
+            );
+          })}
+        </section>
+        <section
+          className="trace-metrics"
+          aria-label={locale === "pt-BR" ? "Resumo da rastreabilidade" : "Traceability summary"}
+        >
+          <article>
+            <span className="trace-metric-icon">
+              <Route aria-hidden="true" size={18} />
+            </span>
+            <div>
+              <strong>{coveragePercentage}%</strong>
+              <span>{copy.coverage}</span>
+            </div>
+            <small>
+              {trace.coverage.stages_with_timestamps} {copy.of} {trace.coverage.total_stages}
+            </small>
+          </article>
+          <article>
+            <span className="trace-metric-icon">
+              <FileStack aria-hidden="true" size={18} />
+            </span>
+            <div>
+              <strong>{trace.documents.length}</strong>
+              <span>{copy.documents}</span>
+            </div>
+            <small>{locale === "pt-BR" ? "no ciclo completo" : "in the full lifecycle"}</small>
+          </article>
+          <article>
+            <span className="trace-metric-icon">
+              <BadgeCheck aria-hidden="true" size={18} />
+            </span>
+            <div>
+              <strong>{trace.coverage.evidence_count}</strong>
+              <span>{copy.evidenceMetric}</span>
+            </div>
+            <small>
+              {trace.coverage.test_count} {copy.tests}
+            </small>
+          </article>
+          <article>
+            <span className="trace-metric-icon">
+              <Link2 aria-hidden="true" size={18} />
+            </span>
+            <div>
+              <strong>{linkedArtifacts}</strong>
+              <span>{locale === "pt-BR" ? "Vínculos" : "Links"}</span>
+            </div>
+            <small>Task · Change · SPEC · PRD</small>
+          </article>
+        </section>
+        <div className="trace-stage-menu">
+          {traceStages.map((stage, index) => {
+            const StageIcon = stageIcons[stage];
+            const itemCount = (grouped.get(stage) ?? []).length;
+            return (
+              <button
+                className="trace-stage-menu-button"
+                data-stage={stage}
+                key={stage}
+                onClick={() => setActiveStage(stage)}
+                type="button"
+              >
+                <span className="trace-stage-number">{String(index + 1).padStart(2, "0")}</span>
+                <StageIcon
+                  className="trace-stage-icon"
+                  aria-hidden="true"
+                  size={22}
+                  strokeWidth={1.8}
+                />
+                <strong>{stageCopy[stage].label}</strong>
+                <em>{stageCopy[stage].description}</em>
+                <span className="trace-stage-action">
+                  <small>
+                    <Boxes aria-hidden="true" size={13} /> {itemCount} {copy.items}
+                  </small>
+                  <span>
+                    {locale === "pt-BR" ? "Ver etapa" : "View stage"}
+                    <ArrowRight aria-hidden="true" size={13} strokeWidth={2} />
+                  </span>
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      </section>
+      {activeStage ? (
+        <TraceStageDialog
+          ariaLabel={copy.stageDetails}
+          closeLabel={locale === "pt-BR" ? "Fechar detalhes da etapa" : "Close stage details"}
+          onClose={() => setActiveStage(null)}
+        >
+          <TraceStageDetail
+            copy={copy}
+            documents={grouped.get(activeStage) ?? []}
+            locale={locale}
+            onBack={() => setActiveStage(null)}
+            onOpenDocument={setSelected}
+            onStageChange={setActiveStage}
+            stage={activeStage}
+            stageArtifacts={stageArtifacts}
+            stageRecord={stageRecords.get(activeStage)}
+            stageCopy={stageCopy}
+          />
+        </TraceStageDialog>
+      ) : null}
+      {selected ? (
+        <TraceDocumentDialog
+          ariaLabel={`${copy.document} ${selected.title}`}
+          closeLabel={copy.closeDocument}
+          document={selected}
+          onClose={() => setSelected(null)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function TraceUsageStrip({
+  usage,
+  locale,
+  copy,
+}: {
+  usage: TaskTrace["usage"];
+  locale: TraceLocale;
+  copy: (typeof traceCopy)[TraceLocale];
+}) {
+  const items = [
+    {
+      label: copy.time,
+      metric: usage.duration_ms,
+      value: formatTraceDuration(usage.duration_ms.value, locale),
+    },
+    {
+      label: copy.tokens,
+      metric: usage.total_tokens,
+      value:
+        usage.total_tokens.value === null
+          ? "—"
+          : formatCompactNumber(usage.total_tokens.value, locale),
+    },
+    {
+      label: copy.cost,
+      metric: usage.cost,
+      value:
+        usage.cost.value === null || usage.cost.currency === null
+          ? "—"
+          : formatCurrency(usage.cost.value, usage.cost.currency, locale),
+    },
+  ];
+  return (
+    <section aria-label={locale === "pt-BR" ? "Uso agregado da Task" : "Aggregated Task usage"}>
+      <dl className="trace-usage-strip">
+        {items.map(({ label, metric, value }) => {
+          const coverage = Math.round(metric.coverage_ratio * 100);
+          const coverageLabel = `${metric.known_runs}/${usage.run_count} ${copy.measuredRuns} · ${coverage}%`;
+          return (
+            <div key={label} title={coverageLabel}>
+              <dt>
+                {label}
+                <span
+                  aria-hidden="true"
+                  className="trace-usage-coverage"
+                  data-complete={metric.unknown_runs === 0}
+                />
+                <span className="trace-usage-sr-only">{coverageLabel}</span>
+              </dt>
+              <dd>{value}</dd>
+            </div>
+          );
+        })}
+      </dl>
+    </section>
+  );
+}
+
+function formatTraceDuration(durationMs: number | null, locale: TraceLocale): string {
+  return durationMs === null ? "—" : formatDurationMs(durationMs, locale);
+}
+
+function formatTraceCreatedAt(value: string | null, locale: TraceLocale): string {
+  if (value === null) return "—";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "—";
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "short",
+    timeStyle: "short",
+  }).format(date);
+}
+
+function formatTraceElapsed(value: string | null, locale: TraceLocale): string {
+  if (value === null) return "—";
+  const createdAt = Date.parse(value);
+  if (!Number.isFinite(createdAt)) return "—";
+  const elapsedMs = Math.max(0, Date.now() - createdAt);
+  const minutes = Math.max(1, Math.round(elapsedMs / 60_000));
+  let unit: string;
+  if (minutes < 60) unit = `${minutes}m`;
+  else {
+    const hours = Math.round(minutes / 60);
+    if (hours < 24) unit = `${hours}h`;
+    else {
+      const days = Math.round(hours / 24);
+      if (days < 7) unit = `${days}d`;
+      else {
+        const weeks = Math.round(days / 7);
+        unit = locale === "pt-BR" ? `${weeks}sem` : `${weeks}w`;
+      }
+    }
+  }
+  return locale === "pt-BR" ? `Há ${unit}` : `${unit} ago`;
+}