@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/modules/operations/src/server/usage.ts

@@ -0,0 +1,139 @@
+import { aggregateRunV2Usage, type UsageBucketV2 } from "@zaip-ai/costs";
+import type { ExecutionV2 } from "@zaip-ai/specs";
+import type { TaskV2 } from "@zaip-ai/tasks";
+import type {
+  OperationsProjection,
+  QualityProjection,
+  UsageMetricProjection,
+  UsageProjection,
+} from "../contracts.js";
+import type { ScopedRun } from "./internal.js";
+
+export function usageProjection(runs: readonly ScopedRun[]): UsageProjection {
+  const aggregate = aggregateRunV2Usage(runs.map((run) => run.cost));
+  return {
+    conversation: metric(aggregate.conversation),
+    planning: metric(aggregate.planning),
+    execution: metric(aggregate.execution),
+    total: metric(aggregate.total),
+    new_work: metric(aggregate.work_types.new),
+    rework: metric(aggregate.work_types.rework),
+  };
+}
+
+function metric(bucket: UsageBucketV2): UsageMetricProjection {
+  return {
+    events: bucket.usage_event_count,
+    tokens: bucket.tokens,
+    cost: bucket.cost,
+    coverage: bucket.coverage,
+  };
+}
+
+export function decisionCounts(decisions: readonly { origin: "human" | "agent" }[]) {
+  return {
+    human: decisions.filter((decision) => decision.origin === "human").length,
+    agent: decisions.filter((decision) => decision.origin === "agent").length,
+  };
+}
+
+export function qualityProjection(
+  tasks: readonly TaskV2[],
+  runs: readonly ScopedRun[],
+): QualityProjection {
+  const completedTasks = tasks.filter((task) => task.status === "completed").length;
+  const terminalRuns = runs.filter((run) => run.fold.status !== "running");
+  const successfulRuns = terminalRuns.filter((run) => run.fold.status === "completed").length;
+  const reworkRuns = runs.filter((run) => run.fold.run.work_type === "rework").length;
+  return {
+    completed_tasks: completedTasks,
+    task_completion_rate: tasks.length === 0 ? 0 : completedTasks / tasks.length,
+    terminal_runs: terminalRuns.length,
+    successful_runs: successfulRuns,
+    terminal_success_rate: terminalRuns.length === 0 ? 0 : successfulRuns / terminalRuns.length,
+    rework_rate: runs.length === 0 ? 0 : reworkRuns / runs.length,
+  };
+}
+
+export function reconciliation(
+  total: UsageProjection,
+  origins: OperationsProjection["origins"],
+): OperationsProjection["summary"]["reconciliation"] {
+  const phases = [total.conversation, total.planning, total.execution];
+  const originTotals = Object.values(origins).map((origin) => origin.total);
+  return {
+    phase_tokens_match_total: reconcileValues(
+      phases.map((phase) => phase.tokens.total),
+      total.total.tokens.total,
+    ),
+    phase_usd_match_total: reconcileValues(
+      phases.map((phase) => phase.cost.usd),
+      total.total.cost.usd,
+    ),
+    phase_brl_match_total: reconcileValues(
+      phases.map((phase) => phase.cost.brl),
+      total.total.cost.brl,
+    ),
+    origin_tokens_match_total: reconcileValues(
+      originTotals.map((origin) => origin.tokens.total),
+      total.total.tokens.total,
+    ),
+  };
+}
+
+function reconcileValues(values: readonly (number | null)[], expected: number | null): boolean {
+  const populated = values.filter((value): value is number => value !== null);
+  if (expected === null) return populated.length === 0;
+  return Math.abs(populated.reduce((sum, value) => sum + value, 0) - expected) < 1e-9;
+}
+
+export function taskProgress(status: TaskV2["status"]): number {
+  if (status === "completed") return 100;
+  if (status === "verifying") return 80;
+  if (status === "executing") return 50;
+  if (["blocked", "failed", "cancelled"].includes(status)) return 0;
+  return 10;
+}
+
+export function executionWorkStatus(status: ExecutionV2["status"]): string {
+  if (status === "planned") return "planning";
+  if (["running", "paused", "verifying"].includes(status)) return "executing";
+  return status;
+}
+
+export function macroWorkStatus(
+  lifecycleStatus: string,
+  executions: readonly ({ status: string } | undefined)[],
+): "planning" | "executing" | "verifying" | "completed" | "blocked" | "failed" | "cancelled" {
+  if (lifecycleStatus === "delivered") return "completed";
+  if (lifecycleStatus === "blocked") return "blocked";
+  if (lifecycleStatus === "failed") return "failed";
+  if (lifecycleStatus === "cancelled") return "cancelled";
+  const statuses = executions.flatMap((execution) =>
+    execution === undefined ? [] : [execution.status],
+  );
+  if (statuses.some((status) => ["running", "paused"].includes(status))) {
+    return "executing";
+  }
+  if (statuses.includes("verifying")) return "verifying";
+  if (statuses.length > 0 && statuses.every((status) => status === "completed")) {
+    return lifecycleStatus === "active" ? "verifying" : "completed";
+  }
+  if (lifecycleStatus === "active") return "executing";
+  if (statuses.includes("blocked")) return "blocked";
+  if (statuses.includes("failed")) return "failed";
+  if (statuses.includes("planned") || ["draft", "ready"].includes(lifecycleStatus)) {
+    return "planning";
+  }
+  return "planning";
+}
+
+export function latestTimestamp(values: readonly (string | null)[]): string | null {
+  return (
+    values
+      .filter((value): value is string => value !== null)
+      .map((value) => new Date(value).toISOString())
+      .sort()
+      .at(-1) ?? null
+  );
+}

package/templates/.agents/dashboard/modules/operations/src/work-readiness.ts

@@ -0,0 +1,26 @@
+import type { DashboardTaskProjection, OperationsProjection } from "./contracts.js";
+
+export function isStandaloneTaskReady(
+  task: Pick<
+    DashboardTaskProjection,
+    "status" | "spec_id" | "attempt_count" | "started_at" | "execution_started"
+  >,
+): boolean {
+  return (
+    task.status === "planned" &&
+    task.spec_id === null &&
+    task.attempt_count === 0 &&
+    task.started_at === null &&
+    task.execution_started === false
+  );
+}
+
+export function taskIdsWithStartedExecution(
+  executions: readonly Pick<OperationsProjection["executions"][number], "status" | "dag">[],
+): ReadonlySet<string> {
+  return new Set(
+    executions
+      .filter((execution) => execution.status !== "planned")
+      .flatMap((execution) => execution.dag.nodes.map((node) => node.task_id)),
+  );
+}

package/templates/.agents/dashboard/modules/operations/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM"],
+    "noEmit": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["composition-root.ts", "src/**/*.ts", "src/**/*.tsx"]
+}

package/templates/.agents/dashboard/modules/traceability/composition-root.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceFileSystem, WorkspaceLayout } from "@zaip-ai/core";
+import { buildTaskTrace } from "./src/server/index.js";
+
+export function createTraceabilityModule(filesystem: WorkspaceFileSystem, layout: WorkspaceLayout) {
+  if (layout.version !== 2) throw new Error("Traceability module requires WorkspaceLayout V2");
+  return { taskTrace: (taskId: string) => buildTaskTrace(filesystem, layout, taskId) };
+}

package/templates/.agents/dashboard/modules/traceability/golden/golden-view.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import {
+  goldenObservabilityFixture,
+  projectGoldenObservability,
+} from "../../../../../packages/lifecycle-manifests/src/golden/index.js";
+import { buildGoldenDashboardView } from "./golden-view.js";
+
+describe("golden dashboard read-only view", () => {
+  it("uses the canonical projection and preserves unknown coverage", () => {
+    const projection = projectGoldenObservability(goldenObservabilityFixture());
+    const view = buildGoldenDashboardView(projection);
+    expect(view).toMatchObject({
+      readonly: true,
+      status: "healthy",
+      source: ".agents/records",
+    });
+    expect(view.cards.find((card) => card.id === "cost")).toEqual({
+      id: "cost",
+      label: "Custo USD",
+      value: "US$ 0.6000",
+      coverage: "75%",
+    });
+    expect(view.correlations).toHaveLength(4);
+    expect(Object.isFrozen(view)).toBe(true);
+    expect(Object.isFrozen(view.cards)).toBe(true);
+  });
+});

package/templates/.agents/dashboard/modules/traceability/golden/golden-view.ts

@@ -0,0 +1,57 @@
+import type { GoldenObservabilityProjection } from "../../../../../packages/lifecycle-manifests/src/golden/index.js";
+
+export interface GoldenDashboardView {
+  readonly: true;
+  status: "healthy" | "degraded";
+  source: ".agents/records";
+  cards: readonly { id: string; label: string; value: string; coverage: string | null }[];
+  slos: readonly { id: string; passed: boolean; label: string }[];
+  correlations: GoldenObservabilityProjection["correlations"];
+}
+
+export function buildGoldenDashboardView(
+  projection: GoldenObservabilityProjection,
+): GoldenDashboardView {
+  const percentage = (ratio: number) => `${Math.round(ratio * 100)}%`;
+  const tokens = projection.total.total_tokens;
+  const cost = projection.total.cost_usd;
+  return Object.freeze({
+    readonly: true as const,
+    status: projection.healthy ? ("healthy" as const) : ("degraded" as const),
+    source: ".agents/records" as const,
+    cards: Object.freeze([
+      {
+        id: "runs",
+        label: "Runs",
+        value: String(projection.run_ids.length),
+        coverage: null,
+      },
+      {
+        id: "tokens",
+        label: "Tokens",
+        value: tokens.known_sum === null ? "Indisponível" : String(tokens.known_sum),
+        coverage: percentage(tokens.coverage_ratio),
+      },
+      {
+        id: "cost",
+        label: "Custo USD",
+        value: cost.known_sum === null ? "Indisponível" : `US$ ${cost.known_sum.toFixed(4)}`,
+        coverage: percentage(cost.coverage_ratio),
+      },
+      {
+        id: "rework",
+        label: "Retries / repairs",
+        value: `${projection.reliability.retries} / ${projection.reliability.repairs}`,
+        coverage: null,
+      },
+    ]),
+    slos: Object.freeze(
+      projection.slos.map((slo) => ({
+        id: slo.id,
+        passed: slo.passed,
+        label: `${slo.observed} ${slo.operator} ${slo.target}`,
+      })),
+    ),
+    correlations: Object.freeze([...projection.correlations]),
+  });
+}

package/templates/.agents/dashboard/modules/traceability/golden/index.ts

@@ -0,0 +1 @@
+export * from "./golden-view.js";

package/templates/.agents/dashboard/modules/traceability/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zaip-ai/dashboard-traceability",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./contracts": "./src/contracts.ts",
+    "./server": "./src/server/index.ts",
+    "./react": "./src/react/index.ts",
+    "./composition-root": "./composition-root.ts"
+  },
+  "scripts": {
+    "clean": "node ../../../../scripts/clean.mjs",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zaip-ai/core": "workspace:*",
+    "@zaip-ai/dashboard-ui": "workspace:*",
+    "@zaip-ai/lifecycle-manifests": "workspace:*",
+    "@zaip-ai/specs": "workspace:*",
+    "@zaip-ai/tasks": "workspace:*",
+    "lucide-react": "^0.468.0",
+    "react": "19.2.7"
+  }
+}

package/templates/.agents/dashboard/modules/traceability/src/contracts.ts

@@ -0,0 +1,76 @@
+export type TraceStage =
+  | "definition"
+  | "planning"
+  | "execution"
+  | "decisions"
+  | "verification"
+  | "evidence";
+
+export interface TraceDocument {
+  id: string;
+  path: string;
+  title: string;
+  stage: TraceStage;
+  kind:
+    | "prd"
+    | "spec"
+    | "requirement"
+    | "change"
+    | "task"
+    | "execution"
+    | "run"
+    | "decision"
+    | "evidence"
+    | "test"
+    | "eval"
+    | "check";
+  content: string;
+  recorded_at: string | null;
+  updated_at: string | null;
+}
+
+export interface TraceStageRecord {
+  stage: TraceStage;
+  status: "recorded" | "missing_timestamp" | "pending";
+  first_recorded_at: string | null;
+  last_recorded_at: string | null;
+  document_count: number;
+  test_count: number;
+}
+
+export interface TraceObservedMetric {
+  value: number | null;
+  known_runs: number;
+  unknown_runs: number;
+  coverage_ratio: number;
+}
+
+export interface TaskTrace {
+  schema_version: 2;
+  layout_version: 2 | 3;
+  readonly: true;
+  source: ".agents/records";
+  task_id: string;
+  task_title: string;
+  task_risk: "lite" | "standard" | "critical" | null;
+  task_created_at: string | null;
+  task_progress: number;
+  spec_id: string | null;
+  prd_id: string | null;
+  change_id: string;
+  usage: {
+    run_count: number;
+    duration_ms: TraceObservedMetric;
+    total_tokens: TraceObservedMetric;
+    cost: TraceObservedMetric & { currency: "BRL" | "USD" | null };
+  };
+  documents: TraceDocument[];
+  stages: TraceStageRecord[];
+  coverage: {
+    stages_with_documents: number;
+    stages_with_timestamps: number;
+    total_stages: 6;
+    evidence_count: number;
+    test_count: number;
+  };
+}

package/templates/.agents/dashboard/modules/traceability/src/react/TaskTracePanel.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  traceIdentifierLinks,
+  traceStageArtifacts,
+  traceStageArtifactsEn,
+  traceStageCopyEn,
+  traceStageCopyPt,
+} from "./TaskTracePanel.js";
+
+describe("logical trace copy", () => {
+  it("uses the six lifecycle names and descriptions", () => {
+    expect(traceStageCopyPt).toEqual({
+      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.",
+      },
+    });
+  });
+
+  it("summarizes decisions from planning and execution together", () => {
+    expect(traceStageArtifacts.decisions).toBe("Decisões do planejamento e da execução");
+  });
+
+  it("translates every stage summary inside the English popup", () => {
+    expect(traceStageArtifactsEn).toEqual({
+      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",
+    });
+    expect(traceStageCopyEn.definition.label).toBe("Definition (PRD + Requirements)");
+    expect(traceStageCopyEn.evidence.description).toContain("acceptance criteria");
+  });
+
+  it("keeps Task static and makes Change, SPEC and PRD navigable", () => {
+    const openChange = () => undefined;
+    const openSpec = () => undefined;
+    const openPrd = () => undefined;
+    const links = traceIdentifierLinks(
+      {
+        task_id: "TASK-1",
+        change_id: "CHG-1",
+        spec_id: "SPEC-1",
+        prd_id: "PRD-1",
+      },
+      { onOpenChange: openChange, onOpenPrd: openPrd, onOpenSpec: openSpec },
+    );
+
+    expect(links.map(({ label, value, onOpen }) => [label, value, onOpen])).toEqual([
+      ["Task", "TASK-1", undefined],
+      ["Change", "CHG-1", openChange],
+      ["SPEC", "SPEC-1", openSpec],
+      ["PRD", "PRD-1", openPrd],
+    ]);
+  });
+});