@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/modules/operations/src/react/period-summary.ts

@@ -0,0 +1,237 @@
+import {
+  isAfterLegacyEffortCutoff,
+  LEGACY_EFFORT_DAILY_MS,
+  saoPauloPeriodKey,
+} from "../contracts.js";
+import { analyticalDuration, metricRuns } from "./execution-metrics.js";
+
+export type PeriodGranularity = "day" | "month" | "year";
+
+export interface PeriodSummaryRow {
+  key: string;
+  prds: number;
+  specs: number;
+  /** Legacy alias retained for consumers that mean tasks created. */
+  tasks: number;
+  tasksCreated: number;
+  tasksActive: number | null;
+  /** Sum-safe total for daily rows; a Task active on two days counts twice. */
+  taskDaysActive: number;
+  runs: number;
+  tests: number;
+  evidences: number;
+  durationMs: number | null;
+  tokens: number | null;
+  costBrl: number | null;
+}
+
+interface PeriodSummaryInput {
+  prds: readonly { created_at: string | null }[];
+  specs: readonly { created_at: string | null }[];
+  tasks: readonly {
+    created_at: string;
+    result: { evidence_ids: string[] } | null;
+    test_count?: number;
+  }[];
+  runs: readonly {
+    id: string;
+    task_id?: string | null;
+    phase?: string;
+    parent_run_id?: string | null;
+    started_at: string;
+    finished_at: string | null;
+    duration_ms: number | null;
+    source_duration_ms?: number | null;
+    duration_provenance?:
+      | "observed"
+      | "reconciled"
+      | "legacy_inferred"
+      | "estimated"
+      | "unavailable";
+    usage: { total: { tokens: { total: number | null }; cost: { brl: number | null } } };
+  }[];
+}
+
+export function aggregatePeriodSummary(
+  data: PeriodSummaryInput,
+  granularity: PeriodGranularity,
+  resolveRunCostBrl?: (runId: string) => number | null,
+  includeLegacyEffort = false,
+): PeriodSummaryRow[] {
+  const buckets = new Map<string, PeriodSummaryRow>();
+  const evidenceIds = new Map<string, Set<string>>();
+  const activeTaskIds = new Map<string, Set<string>>();
+  const recordedDurationByPeriod = aggregateObservedDurationByPeriod(
+    data.runs,
+    granularity,
+    includeLegacyEffort,
+  );
+
+  const bucketForKey = (key: string): PeriodSummaryRow => {
+    const existing = buckets.get(key);
+    if (existing !== undefined) return existing;
+    const created: PeriodSummaryRow = {
+      key,
+      prds: 0,
+      specs: 0,
+      tasks: 0,
+      tasksCreated: 0,
+      tasksActive: 0,
+      taskDaysActive: 0,
+      runs: 0,
+      tests: 0,
+      evidences: 0,
+      durationMs: null,
+      tokens: null,
+      costBrl: null,
+    };
+    buckets.set(key, created);
+    evidenceIds.set(key, new Set());
+    activeTaskIds.set(key, new Set());
+    return created;
+  };
+  const bucketFor = (value: string | null): PeriodSummaryRow | null => {
+    const key = periodKey(value, granularity);
+    return key === null ? null : bucketForKey(key);
+  };
+
+  for (const prd of data.prds) {
+    const bucket = bucketFor(prd.created_at);
+    if (bucket !== null) bucket.prds += 1;
+  }
+  for (const spec of data.specs) {
+    const bucket = bucketFor(spec.created_at);
+    if (bucket !== null) bucket.specs += 1;
+  }
+  for (const task of data.tasks) {
+    const bucket = bucketFor(task.created_at);
+    if (bucket === null) continue;
+    bucket.tasks += 1;
+    bucket.tasksCreated += 1;
+    bucket.tests += task.test_count ?? 0;
+    const ids = evidenceIds.get(bucket.key);
+    for (const evidenceId of task.result?.evidence_ids ?? []) ids?.add(evidenceId);
+  }
+  // Period usage follows the global card population: every filtered Run phase.
+  // Observed duration is intentionally populated below from execution Runs only.
+  for (const run of metricRuns(data.runs)) {
+    const bucket = bucketFor(run.started_at);
+    if (bucket === null) continue;
+    bucket.runs += 1;
+    if (run.task_id !== null && run.task_id !== undefined)
+      activeTaskIds.get(bucket.key)?.add(run.task_id);
+    bucket.tokens = addObserved(bucket.tokens, run.usage.total.tokens.total);
+    bucket.costBrl = addObserved(
+      bucket.costBrl,
+      resolveRunCostBrl === undefined ? run.usage.total.cost.brl : resolveRunCostBrl(run.id),
+    );
+  }
+
+  for (const [key, ids] of evidenceIds) {
+    const bucket = buckets.get(key);
+    if (bucket !== undefined) bucket.evidences = ids.size;
+  }
+  for (const [key, ids] of activeTaskIds) {
+    const bucket = buckets.get(key);
+    if (bucket !== undefined) {
+      bucket.tasksActive = ids.size;
+      bucket.taskDaysActive = ids.size;
+    }
+  }
+  for (const [key, durationMs] of recordedDurationByPeriod) {
+    bucketForKey(key).durationMs = durationMs;
+  }
+  return [...buckets.values()].sort((left, right) => right.key.localeCompare(left.key));
+}
+
+function aggregateObservedDurationByPeriod(
+  runs: PeriodSummaryInput["runs"],
+  granularity: PeriodGranularity,
+  includeLegacyEffort: boolean,
+): Map<string, number> {
+  const durations = new Map<string, number>();
+  for (const run of metricRuns(runs)) {
+    if (includeLegacyEffort && !isAfterLegacyEffortCutoff(run.started_at)) continue;
+    const durationMs = analyticalDuration(run);
+    if (durationMs === null) continue;
+    const key = periodKey(run.started_at, granularity);
+    if (key !== null) durations.set(key, (durations.get(key) ?? 0) + durationMs);
+  }
+  if (includeLegacyEffort)
+    for (const [day, durationMs] of Object.entries(LEGACY_EFFORT_DAILY_MS)) {
+      const key = periodKey(`${day}T12:00:00.000Z`, granularity);
+      if (key !== null) durations.set(key, (durations.get(key) ?? 0) + durationMs);
+    }
+  return durations;
+}
+
+export function summarizePeriodRows(
+  rows: readonly PeriodSummaryRow[],
+): Omit<PeriodSummaryRow, "key"> {
+  const total: Omit<PeriodSummaryRow, "key"> = {
+    prds: 0,
+    specs: 0,
+    tasks: 0,
+    tasksCreated: 0,
+    tasksActive: null,
+    taskDaysActive: 0,
+    runs: 0,
+    tests: 0,
+    evidences: 0,
+    durationMs: null,
+    tokens: null,
+    costBrl: null,
+  };
+  for (const row of rows) {
+    total.prds += row.prds;
+    total.specs += row.specs;
+    total.tasks += row.tasks;
+    total.tasksCreated += row.tasksCreated;
+    // A cross-period unique count cannot be derived from already-aggregated
+    // rows; taskDaysActive is the only sum-safe total here.
+    total.taskDaysActive += row.taskDaysActive;
+    total.runs += row.runs;
+    total.tests += row.tests;
+    total.evidences += row.evidences;
+    total.durationMs = addObserved(total.durationMs, row.durationMs);
+    total.tokens = addObserved(total.tokens, row.tokens);
+    total.costBrl = addObserved(total.costBrl, row.costBrl);
+  }
+  return total;
+}
+
+export function averagePeriodSummaryRows(rows: readonly PeriodSummaryRow[]) {
+  const divisor = rows.length;
+  return {
+    tasks: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.tasks, 0) / divisor,
+    specs: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.specs, 0) / divisor,
+    prds: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.prds, 0) / divisor,
+    durationMs: averagePerPeriod(
+      rows.map((row) => row.durationMs),
+      divisor,
+    ),
+    tokens: averageObserved(rows.map((row) => row.tokens)),
+    costBrl: averageObserved(rows.map((row) => row.costBrl)),
+  };
+}
+
+function addObserved(current: number | null, value: number | null): number | null {
+  return value === null ? current : (current ?? 0) + value;
+}
+
+function averageObserved(values: readonly (number | null)[]): number | null {
+  const present = values.filter((value): value is number => value !== null);
+  return present.length === 0
+    ? null
+    : present.reduce((sum, value) => sum + value, 0) / present.length;
+}
+
+function averagePerPeriod(values: readonly (number | null)[], periodCount: number): number | null {
+  if (periodCount === 0) return null;
+  const known = values.filter((value): value is number => value !== null);
+  return known.length === 0 ? null : known.reduce((sum, value) => sum + value, 0) / periodCount;
+}
+
+function periodKey(value: string | null, granularity: PeriodGranularity): string | null {
+  return saoPauloPeriodKey(value, granularity);
+}

package/templates/.agents/dashboard/modules/operations/src/react/popup-localization.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { entityDetailsCopy } from "./EntityDetailsDialog.js";
+import { macroLifecycleStatusLabel } from "./MacroPlanningDialog.js";
+import { taskDetailsCopy } from "./TaskDetailsDialog.js";
+
+describe("operations popup localization", () => {
+  it("provides complete English labels for entity and Run details", () => {
+    expect(entityDetailsCopy("en-US")).toMatchObject({
+      details: "Details for",
+      requirements: "Requirements",
+      acceptanceCriteria: "Acceptance criteria",
+      workStatus: "Work status",
+      tasksInDag: "Tasks in DAG",
+      topologicalOrder: "Topological order",
+      dependencies: "Dependencies",
+      phase: "Phase",
+      entrypoint: "Entrypoint",
+      client: "Client",
+      model: "Model",
+      start: "Start",
+      end: "End",
+      duration: "Duration",
+      file: "File",
+    });
+  });
+
+  it("provides complete English labels for Task details", () => {
+    expect(taskDetailsCopy("en-US")).toEqual({
+      aria: "Task details",
+      close: "Close",
+      status: "Status",
+      risk: "Risk",
+      duration: "Duration",
+      updated: "Updated",
+      acceptanceCriteria: "Acceptance criteria",
+      decisions: "Decisions",
+      noDecisions: "No decisions recorded.",
+      description: "Description",
+      openTraceability: "Open traceability",
+    });
+  });
+
+  it("localizes lifecycle values shown inside PRD and SPEC dialogs", () => {
+    expect(macroLifecycleStatusLabel("active", "en-US")).toBe("Active");
+    expect(macroLifecycleStatusLabel("delivered", "en-US")).toBe("Delivered");
+    expect(macroLifecycleStatusLabel("active", "pt-BR")).toBe("Ativo");
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/react/run-scope.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { scopeRunsToEntities } from "./run-scope.js";
+
+describe("scopeRunsToEntities", () => {
+  const runs = [
+    { task_id: "TASK-A", spec_id: null, prd_id: null },
+    { task_id: null, spec_id: "SPEC-A", prd_id: null },
+    { task_id: null, spec_id: null, prd_id: null },
+  ];
+  const entities = {
+    taskIds: new Set(["TASK-A"]),
+    specIds: new Set<string>(),
+    prdIds: new Set<string>(),
+  };
+
+  it("keeps unlinked project Runs only without an entity filter", () => {
+    expect(scopeRunsToEntities(runs, entities, { entityFilterActive: false })).toHaveLength(3);
+    expect(scopeRunsToEntities(runs, entities, { entityFilterActive: true })).toEqual([runs[0]]);
+  });
+
+  it("keeps a direct Run query match and Runs linked to a matched Task", () => {
+    expect(
+      scopeRunsToEntities(runs, entities, {
+        entityFilterActive: true,
+        directRunMatch: (run) => run.spec_id === "SPEC-A",
+      }),
+    ).toEqual([runs[0], runs[1]]);
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/react/run-scope.ts

@@ -0,0 +1,25 @@
+export interface RelationalRun {
+  task_id: string | null;
+  spec_id: string | null;
+  prd_id: string | null;
+}
+
+/** Entity filters constrain the metric population as well as entity tables. */
+export function scopeRunsToEntities<T extends RelationalRun>(
+  runs: readonly T[],
+  entities: {
+    taskIds: ReadonlySet<string>;
+    specIds: ReadonlySet<string>;
+    prdIds: ReadonlySet<string>;
+  },
+  options: { entityFilterActive: boolean; directRunMatch?: (run: T) => boolean },
+): T[] {
+  if (!options.entityFilterActive) return [...runs];
+  return runs.filter(
+    (run) =>
+      options.directRunMatch?.(run) === true ||
+      (run.task_id !== null && entities.taskIds.has(run.task_id)) ||
+      (run.spec_id !== null && entities.specIds.has(run.spec_id)) ||
+      (run.prd_id !== null && entities.prdIds.has(run.prd_id)),
+  );
+}

package/templates/.agents/dashboard/modules/operations/src/react/sort-by-created-at.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { sortByCreatedAtDescending } from "./sort-by-created-at.js";
+
+describe("sortByCreatedAtDescending", () => {
+  it("places the most recently created rows first without mutating the input", () => {
+    const rows = [
+      { id: "older", created_at: "2026-07-15T12:00:00.000Z" },
+      { id: "newest", created_at: "2026-07-16T14:00:00.000Z" },
+      { id: "middle", created_at: "2026-07-16T10:00:00.000Z" },
+    ] as const;
+
+    expect(sortByCreatedAtDescending(rows).map((row) => row.id)).toEqual([
+      "newest",
+      "middle",
+      "older",
+    ]);
+    expect(rows.map((row) => row.id)).toEqual(["older", "newest", "middle"]);
+  });
+
+  it("keeps missing and invalid creation dates at the end", () => {
+    const sorted = sortByCreatedAtDescending([
+      { id: "missing", created_at: null },
+      { id: "valid", created_at: "2026-07-16T14:00:00.000Z" },
+      { id: "invalid", created_at: "invalid" },
+    ]);
+
+    expect(sorted[0]?.id).toBe("valid");
+    expect(
+      sorted
+        .slice(1)
+        .map((row) => row.id)
+        .sort(),
+    ).toEqual(["invalid", "missing"]);
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/react/sort-by-created-at.ts

@@ -0,0 +1,11 @@
+export function sortByCreatedAtDescending<T extends { created_at: string | null }>(
+  rows: readonly T[],
+): T[] {
+  return [...rows].sort((left, right) => createdAtTimestamp(right) - createdAtTimestamp(left));
+}
+
+function createdAtTimestamp(row: { created_at: string | null }): number {
+  if (row.created_at === null) return Number.NEGATIVE_INFINITY;
+  const timestamp = Date.parse(row.created_at);
+  return Number.isNaN(timestamp) ? Number.NEGATIVE_INFINITY : timestamp;
+}

package/templates/.agents/dashboard/modules/operations/src/react/status-labels.ts

@@ -0,0 +1,36 @@
+import type { TaskStatus } from "../contracts.js";
+
+export type OperationsLocale = "pt-BR" | "en-US";
+
+const labels: Record<OperationsLocale, Record<TaskStatus, string>> = {
+  "en-US": {
+    draft: "Definition (PRD + Requirements)",
+    planned: "Planned (SPEC + Changes)",
+    executing: "Executing (Tasks)",
+    verifying: "Verifying (Tests + Review)",
+    completed: "Completed",
+    blocked: "Blocked",
+    failed: "Failed",
+    cancelled: "Cancelled",
+  },
+  "pt-BR": {
+    draft: "Definição (PRD + Requisitos)",
+    planned: "Planejamento (SPEC + Mudanças)",
+    executing: "Execução (Tarefas)",
+    verifying: "Verificação (Testes + Revisão)",
+    completed: "Concluído",
+    blocked: "Bloqueado",
+    failed: "Falhado",
+    cancelled: "Cancelado",
+  },
+};
+
+export function statusLabel(status: TaskStatus, locale: OperationsLocale): string {
+  return labels[locale][status];
+}
+
+export function riskLabel(risk: string, locale: OperationsLocale): string {
+  if (locale === "en-US")
+    return risk === "lite" ? "Lite" : risk === "standard" ? "Standard" : "Critical";
+  return risk === "lite" ? "Leve" : risk === "standard" ? "Padrão" : "Crítico";
+}

package/templates/.agents/dashboard/modules/operations/src/react/table-order.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { sortByDateDesc } from "./table-order.js";
+
+describe("sortByDateDesc", () => {
+  it("puts the most recent instant first, including timestamps with offsets", () => {
+    const rows = [
+      { id: "older", created_at: "2026-07-13T23:10:00-03:00" },
+      { id: "newer", created_at: "2026-07-14T04:00:00Z" },
+      { id: "middle", created_at: "2026-07-14T00:00:00-03:00" },
+    ];
+
+    expect(sortByDateDesc(rows, (row) => row.created_at).map((row) => row.id)).toEqual([
+      "newer",
+      "middle",
+      "older",
+    ]);
+  });
+
+  it("keeps the original order for equal or invalid dates", () => {
+    const rows = [
+      { id: "first", created_at: "not-a-date" },
+      { id: "second", created_at: "not-a-date" },
+      { id: "same", created_at: "2026-07-14T01:00:00Z" },
+      { id: "same-too", created_at: "2026-07-14T01:00:00Z" },
+    ];
+
+    expect(sortByDateDesc(rows, (row) => row.created_at).map((row) => row.id)).toEqual([
+      "same",
+      "same-too",
+      "first",
+      "second",
+    ]);
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/react/table-order.ts

@@ -0,0 +1,15 @@
+export function sortByDateDesc<Row>(
+  rows: readonly Row[],
+  getDate: (row: Row) => string | null,
+): Row[] {
+  return rows
+    .map((row, index) => ({ row, index, timestamp: Date.parse(getDate(row) ?? "") }))
+    .sort((left, right) => {
+      const leftTime = Number.isFinite(left.timestamp) ? left.timestamp : Number.NEGATIVE_INFINITY;
+      const rightTime = Number.isFinite(right.timestamp)
+        ? right.timestamp
+        : Number.NEGATIVE_INFINITY;
+      return rightTime - leftTime || left.index - right.index;
+    })
+    .map(({ row }) => row);
+}

package/templates/.agents/dashboard/modules/operations/src/react/task-origin-badge.css

@@ -0,0 +1,23 @@
+.operations-task-origin-badge {
+  justify-self: start;
+  border: 1px solid rgba(96, 165, 250, 0.3);
+  border-radius: 999px;
+  padding: 4px 8px;
+  background: rgba(96, 165, 250, 0.12);
+  color: #bfdbfe;
+  font-size: 0.64rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+}
+
+.operations-task-origin-badge.is-spec {
+  border-color: rgba(167, 139, 250, 0.34);
+  background: rgba(124, 58, 237, 0.14);
+  color: #ddd6fe;
+}
+
+.operations-task-origin-badge.is-prd {
+  border-color: rgba(251, 191, 36, 0.34);
+  background: rgba(180, 83, 9, 0.14);
+  color: #fde68a;
+}

package/templates/.agents/dashboard/modules/operations/src/react/task-origin.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import type { ChangeProjection, DashboardTaskProjection } from "../contracts.js";
+import { matchesTaskOrigin, taskOrigin, taskOriginLabel } from "./task-origin.js";
+
+const task = (changeId: string, specId: string | null = null) =>
+  ({ change_id: changeId, spec_id: specId }) as DashboardTaskProjection;
+
+const change = (id: string, type: "task" | "spec" | "prd") =>
+  ({
+    id,
+    source:
+      type === "task"
+        ? { type, task_id: "TASK-1" }
+        : type === "spec"
+          ? { type, spec_id: "SPEC-1" }
+          : { type, prd_id: "PRD-1", spec_id: "SPEC-1" },
+  }) as ChangeProjection;
+
+describe("task origin", () => {
+  const changes = [
+    change("CHG-TASK", "task"),
+    change("CHG-SPEC", "spec"),
+    change("CHG-PRD", "prd"),
+  ];
+
+  it("uses the Change source to distinguish Task-first, SPEC and PRD", () => {
+    expect(taskOrigin(task("CHG-TASK"), changes)).toBe("task");
+    expect(taskOrigin(task("CHG-SPEC", "SPEC-1"), changes)).toBe("spec");
+    expect(taskOrigin(task("CHG-PRD", "SPEC-1"), changes)).toBe("prd");
+  });
+
+  it("keeps a compatible fallback when the Change is absent", () => {
+    expect(taskOrigin(task("CHG-MISSING"), [])).toBe("task");
+    expect(taskOrigin(task("CHG-MISSING", "SPEC-1"), [])).toBe("spec");
+  });
+
+  it("filters by origin and exposes semantic badge labels", () => {
+    const prdTask = task("CHG-PRD", "SPEC-1");
+    expect(matchesTaskOrigin(prdTask, "", changes)).toBe(true);
+    expect(matchesTaskOrigin(prdTask, "prd", changes)).toBe(true);
+    expect(matchesTaskOrigin(prdTask, "spec", changes)).toBe(false);
+    expect(taskOriginLabel("task")).toBe("Task-first");
+    expect(taskOriginLabel("spec")).toBe("SPEC");
+    expect(taskOriginLabel("prd")).toBe("PRD");
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/react/task-origin.ts

@@ -0,0 +1,27 @@
+import type { ChangeProjection, DashboardTaskProjection } from "../contracts.js";
+
+export type TaskOrigin = ChangeProjection["source"]["type"];
+
+export const taskOriginOptions: readonly TaskOrigin[] = ["task", "spec", "prd"];
+
+export function taskOrigin(
+  task: DashboardTaskProjection,
+  changes: readonly ChangeProjection[],
+): TaskOrigin {
+  const sourceType = changes.find((change) => change.id === task.change_id)?.source.type;
+  return sourceType ?? (task.spec_id === null ? "task" : "spec");
+}
+
+export function taskOriginLabel(origin: TaskOrigin): string {
+  if (origin === "task") return "Task-first";
+  if (origin === "spec") return "SPEC";
+  return "PRD";
+}
+
+export function matchesTaskOrigin(
+  task: DashboardTaskProjection,
+  filter: TaskOrigin | "",
+  changes: readonly ChangeProjection[],
+): boolean {
+  return filter === "" || taskOrigin(task, changes) === filter;
+}