@zaip-ai/cli 3.2.0 → 3.4.0

package/templates/.agents/dashboard/modules/operations/src/react/export/ExcelExportAction.tsx

@@ -5,6 +5,38 @@ import { formatDeveloperIdentities } from "../developer-identities.js";
 import { ExportProgressToast, ExportSuccessToast } from "./ExportProgressToast.js";
 import { ExportController, type ExportState } from "./export-session.js";
 
+export {
+  AGENT_INVOCATION_EXPORT_COLUMNS,
+  CHANGE_EXPORT_COLUMNS,
+  COMPACT_LIFECYCLE_EXPORT_COLUMNS,
+  CONVERSATION_EXPORT_COLUMNS,
+  COST_AGENT_EXPORT_COLUMNS,
+  COST_GROUP_EXPORT_COLUMNS,
+  DECISION_EXPORT_COLUMNS,
+  DEVELOPER_EXPORT_COLUMNS,
+  EXECUTION_EXPORT_COLUMNS,
+  KANBAN_EXPORT_COLUMNS,
+  MODEL_COST_GROUP_EXPORT_COLUMNS,
+  PERIOD_EXPORT_COLUMNS,
+  WORK_EXPORT_COLUMNS,
+} from "./ExcelExportColumns.js";
+
+import {
+  AGENT_INVOCATION_EXPORT_COLUMNS,
+  CHANGE_EXPORT_COLUMNS,
+  COMPACT_LIFECYCLE_EXPORT_COLUMNS,
+  CONVERSATION_EXPORT_COLUMNS,
+  COST_AGENT_EXPORT_COLUMNS,
+  COST_GROUP_EXPORT_COLUMNS,
+  DECISION_EXPORT_COLUMNS,
+  DEVELOPER_EXPORT_COLUMNS,
+  EXECUTION_EXPORT_COLUMNS,
+  KANBAN_EXPORT_COLUMNS,
+  MODEL_COST_GROUP_EXPORT_COLUMNS,
+  PERIOD_EXPORT_COLUMNS,
+  WORK_EXPORT_COLUMNS,
+} from "./ExcelExportColumns.js";
+
 export type ExcelExportInput = {
   view: string;
   filters: Readonly<Record<string, unknown>>;
@@ -22,193 +54,6 @@ export type PreparedExportPageSource = {
 };
 export const EXPORT_SUCCESS_TOAST_MS = 4_000;
 
-export const PERIOD_EXPORT_COLUMNS = [
-  "key",
-  "prds",
-  "specs",
-  "tasks",
-  "conversations",
-  "runs",
-  "tests",
-  "evidences",
-  "tokens",
-  "cost",
-  "duration_hours",
-] as const;
-
-// Work views contain PRDs, SPECs, and Tasks. Export the common, user-facing
-// fields instead of the union of their internal lifecycle projections. The
-// latter produces columns that are empty for an entire view (or nearly every
-// row), which makes the workbook much harder to use.
-export const WORK_EXPORT_COLUMNS = [
-  "type",
-  "id",
-  "title",
-  "status",
-  "risk",
-  "developers",
-  "occurred_at",
-  "duration_hours",
-  "tokens",
-  "cost_brl",
-] as const;
-
-// Execution rows are entities, not period summaries.  Keep their schema
-// aligned with the Execution table so the workbook never inherits the empty
-// PRD/SPEC/period columns shown by a different tab.
-export const EXECUTION_EXPORT_COLUMNS = [
-  "id",
-  "kind",
-  "status",
-  "origin",
-  "task_id",
-  "conversation_id",
-  "created_at",
-  "finished_at",
-  "duration_hours",
-  "tokens",
-  "cost_brl",
-  "invocations",
-] as const;
-
-export const AGENT_INVOCATION_EXPORT_COLUMNS = [
-  "run_id",
-  "execution_id",
-  "conversation_id",
-  "task_id",
-  "origin",
-  "run_role",
-  "run_purpose",
-  "phase",
-  "status",
-  "agent",
-  "provider",
-  "model",
-  "reasoning_effort",
-  "started_at",
-  "finished_at",
-  "duration_hours",
-  "input_tokens",
-  "cached_input_tokens",
-  "output_tokens",
-  "reasoning_tokens",
-  "total_tokens",
-  "estimated_usd",
-  "estimated_brl",
-] as const;
-
-export const COMPACT_LIFECYCLE_EXPORT_COLUMNS = [
-  "id",
-  "title",
-  "status",
-  "occurred_at",
-  "invocations",
-  "duration_hours",
-  "tokens",
-  "cost_brl",
-] as const;
-
-export const COST_GROUP_EXPORT_COLUMNS = [
-  "key",
-  "label",
-  "invocations",
-  "tasks",
-  "tokens",
-  "cost_usd",
-  "cost_brl",
-  "duration_hours",
-] as const;
-
-/** Agent exports count Task participation, including repeated Tasks across agents. */
-export const COST_AGENT_EXPORT_COLUMNS = [
-  "Persona",
-  "Cargo",
-  "Zaip Agentes",
-  "PRDs",
-  "SPECs",
-  "Tarefas",
-  "Runs",
-  "Testes",
-  "Evidências",
-  "Tempo",
-  "Tokens",
-  "Custos",
-] as const;
-
-/** The model audit mirrors its table: entity links precede financial facts. */
-export const MODEL_COST_GROUP_EXPORT_COLUMNS = [
-  "model",
-  "prds",
-  "specs",
-  "tasks",
-  "conversations",
-  "runs",
-  "tests",
-  "evidences",
-  "duration_hours",
-  "tokens",
-  "costs",
-] as const;
-
-// Cost Monitor developer attribution is a factual aggregate with coverage
-// counters. Keep the workbook schema aligned with that table and retain null
-// facts instead of allowing them to be inferred as zero by a spreadsheet.
-export const DEVELOPER_EXPORT_COLUMNS = [
-  "account_id",
-  "login_snapshot",
-  "prd_count",
-  "spec_count",
-  "task_count",
-  "run_count",
-  "test_count",
-  "evidence_count",
-  "total_duration_hours",
-  "total_tokens",
-  "total_cost_brl",
-  "duration_covered_runs",
-  "token_covered_runs",
-  "brl_covered_runs",
-] as const;
-
-export const CONVERSATION_EXPORT_COLUMNS = [
-  "conversation_id",
-  "status",
-  "risk",
-  "started_at",
-  "finished_at",
-  "model",
-  "reasoning_effort",
-  "invocations",
-  "duration_hours",
-  "tokens",
-  "cost_brl",
-] as const;
-
-export const CHANGE_EXPORT_COLUMNS = [
-  "id",
-  "title",
-  "status",
-  "risk",
-  "source_type",
-  "source_id",
-  "requirement_ids_json",
-  "acceptance_ids_json",
-  "task_ids_json",
-  "occurred_at",
-] as const;
-
-export const DECISION_EXPORT_COLUMNS = [
-  "id",
-  "title",
-  "origin",
-  "scope_type",
-  "scope_id",
-  "occurred_at",
-] as const;
-
-/** @deprecated Use WORK_EXPORT_COLUMNS for Kanban and Work List exports. */
-export const KANBAN_EXPORT_COLUMNS = WORK_EXPORT_COLUMNS;
-
 export async function* exportPageSourceRows(
   pageSource: PreparedExportPageSource,
   mapRows: (
@@ -253,7 +98,7 @@ export function exportWorkRows(
       numberValue(row.duration_ms) ??
       numberValue(telemetry?.duration_ms) ??
       numberValue(row.total_duration) ??
-      numberValue(metricDuration?.known_sum);
+      exportKnownMetric(metricDuration);
     return {
       type: row.kind ?? row.entity_kind,
       id: row.id,
@@ -269,13 +114,13 @@ export function exportWorkRows(
         numberValue(row.total_tokens) ??
         numberValue(telemetry?.tokens) ??
         numberValue(tokenUsage?.total) ??
-        numberValue(metricTokens?.known_sum),
+        exportKnownMetric(metricTokens),
       cost_brl:
         numberValue(row.cost_brl) ??
         numberValue(row.total_cost_brl) ??
         numberValue(telemetry?.cost_brl) ??
         numberValue(costUsage?.brl) ??
-        numberValue(metricCost?.known_sum),
+        exportKnownMetric(metricCost),
     };
   });
 }
@@ -346,6 +191,11 @@ export function exportAgentInvocationRows(
   });
 }
 
+function exportKnownMetric(metric: Record<string, unknown> | null): number | null {
+  if (metric?.complete === false && metric.coverage_ratio === 0) return null;
+  return numberValue(metric?.known_sum);
+}
+
 export function exportCompactLifecycleRows(
   rows: readonly Record<string, unknown>[],
 ): Record<string, unknown>[] {
@@ -354,7 +204,8 @@ export function exportCompactLifecycleRows(
     const duration = asRecord(metrics?.duration);
     const tokens = asRecord(metrics?.total_tokens);
     const cost = asRecord(metrics?.cost);
-    const durationMs = numberValue(duration?.known_sum) ?? numberValue(row.total_duration);
+    const durationMs =
+      duration === null ? numberValue(row.total_duration) : exportKnownMetric(duration);
     return {
       id: row.id ?? null,
       title: row.title ?? null,
@@ -362,8 +213,8 @@ export function exportCompactLifecycleRows(
       occurred_at: row.occurred_at ?? null,
       invocations: numberValue(row.run_count) ?? numberValue(row.invocation_count),
       duration_hours: durationMs === null ? null : durationMs / 3_600_000,
-      tokens: numberValue(tokens?.known_sum) ?? numberValue(row.total_tokens),
-      cost_brl: numberValue(cost?.known_sum) ?? numberValue(row.total_cost_brl),
+      tokens: tokens === null ? numberValue(row.total_tokens) : exportKnownMetric(tokens),
+      cost_brl: cost === null ? numberValue(row.total_cost_brl) : exportKnownMetric(cost),
     };
   });
 }

package/templates/.agents/dashboard/modules/operations/src/react/export/ExcelExportColumns.ts

@@ -0,0 +1,186 @@
+export const PERIOD_EXPORT_COLUMNS = [
+  "key",
+  "prds",
+  "specs",
+  "tasks",
+  "conversations",
+  "runs",
+  "tests",
+  "evidences",
+  "tokens",
+  "cost",
+  "duration_hours",
+] as const;
+
+// Work views contain PRDs, SPECs, and Tasks. Export the common, user-facing
+// fields instead of the union of their internal lifecycle projections. The
+// latter produces columns that are empty for an entire view (or nearly every
+// row), which makes the workbook much harder to use.
+export const WORK_EXPORT_COLUMNS = [
+  "type",
+  "id",
+  "title",
+  "status",
+  "risk",
+  "developers",
+  "occurred_at",
+  "duration_hours",
+  "tokens",
+  "cost_brl",
+] as const;
+
+// Execution rows are entities, not period summaries.  Keep their schema
+// aligned with the Execution table so the workbook never inherits the empty
+// PRD/SPEC/period columns shown by a different tab.
+export const EXECUTION_EXPORT_COLUMNS = [
+  "id",
+  "kind",
+  "status",
+  "origin",
+  "task_id",
+  "conversation_id",
+  "created_at",
+  "finished_at",
+  "duration_hours",
+  "tokens",
+  "cost_brl",
+  "invocations",
+] as const;
+
+export const AGENT_INVOCATION_EXPORT_COLUMNS = [
+  "run_id",
+  "execution_id",
+  "conversation_id",
+  "task_id",
+  "origin",
+  "run_role",
+  "run_purpose",
+  "phase",
+  "status",
+  "agent",
+  "provider",
+  "model",
+  "reasoning_effort",
+  "started_at",
+  "finished_at",
+  "duration_hours",
+  "input_tokens",
+  "cached_input_tokens",
+  "output_tokens",
+  "reasoning_tokens",
+  "total_tokens",
+  "estimated_usd",
+  "estimated_brl",
+] as const;
+
+export const COMPACT_LIFECYCLE_EXPORT_COLUMNS = [
+  "id",
+  "title",
+  "status",
+  "occurred_at",
+  "invocations",
+  "duration_hours",
+  "tokens",
+  "cost_brl",
+] as const;
+
+export const COST_GROUP_EXPORT_COLUMNS = [
+  "key",
+  "label",
+  "invocations",
+  "tasks",
+  "tokens",
+  "cost_usd",
+  "cost_brl",
+  "duration_hours",
+] as const;
+
+/** Agent exports count Task participation, including repeated Tasks across agents. */
+export const COST_AGENT_EXPORT_COLUMNS = [
+  "Persona",
+  "Cargo",
+  "Zaip Agentes",
+  "PRDs",
+  "SPECs",
+  "Tarefas",
+  "Runs",
+  "Testes",
+  "Evidências",
+  "Tempo",
+  "Tokens",
+  "Custos",
+] as const;
+
+/** The model audit mirrors its table: entity links precede financial facts. */
+export const MODEL_COST_GROUP_EXPORT_COLUMNS = [
+  "model",
+  "prds",
+  "specs",
+  "tasks",
+  "conversations",
+  "runs",
+  "tests",
+  "evidences",
+  "duration_hours",
+  "tokens",
+  "costs",
+] as const;
+
+// Cost Monitor developer attribution is a factual aggregate with coverage
+// counters. Keep the workbook schema aligned with that table and retain null
+// facts instead of allowing them to be inferred as zero by a spreadsheet.
+export const DEVELOPER_EXPORT_COLUMNS = [
+  "account_id",
+  "login_snapshot",
+  "prd_count",
+  "spec_count",
+  "task_count",
+  "run_count",
+  "test_count",
+  "evidence_count",
+  "total_duration_hours",
+  "total_tokens",
+  "total_cost_brl",
+  "duration_covered_runs",
+  "token_covered_runs",
+  "brl_covered_runs",
+] as const;
+
+export const CONVERSATION_EXPORT_COLUMNS = [
+  "conversation_id",
+  "status",
+  "risk",
+  "started_at",
+  "finished_at",
+  "model",
+  "reasoning_effort",
+  "invocations",
+  "duration_hours",
+  "tokens",
+  "cost_brl",
+] as const;
+
+export const CHANGE_EXPORT_COLUMNS = [
+  "id",
+  "title",
+  "status",
+  "risk",
+  "source_type",
+  "source_id",
+  "requirement_ids_json",
+  "acceptance_ids_json",
+  "task_ids_json",
+  "occurred_at",
+] as const;
+
+export const DECISION_EXPORT_COLUMNS = [
+  "id",
+  "title",
+  "origin",
+  "scope_type",
+  "scope_id",
+  "occurred_at",
+] as const;
+
+/** @deprecated Use WORK_EXPORT_COLUMNS for Kanban and Work List exports. */
+export const KANBAN_EXPORT_COLUMNS = WORK_EXPORT_COLUMNS;

package/templates/.agents/dashboard/modules/operations/src/react/export/excel-agent-participations.test.ts

@@ -0,0 +1,28 @@
+import { expect, it } from "vitest";
+import { COST_AGENT_EXPORT_COLUMNS, exportCostAgentRows } from "./ExcelExportAction.js";
+
+it("exports Agent tasks as participations and fills every missing numeric cell with zero", () => {
+  expect(COST_AGENT_EXPORT_COLUMNS).toEqual([
+    "Persona",
+    "Cargo",
+    "Zaip Agentes",
+    "PRDs",
+    "SPECs",
+    "Tarefas",
+    "Runs",
+    "Testes",
+    "Evidências",
+    "Tempo",
+    "Tokens",
+    "Custos",
+  ]);
+  const rows = exportCostAgentRows([
+    { key: "dave", task_count: 2 },
+    { key: "leo", task_count: 2 },
+    {},
+  ]);
+  expect(rows[0]?.Tarefas).toBe(2);
+  expect(rows[1]?.Tarefas).toBe(2);
+  for (const key of COST_AGENT_EXPORT_COLUMNS.slice(3)) expect(rows[2]?.[key]).toBe(0);
+  expect(rows[0]).not.toHaveProperty("tasks_created");
+});

package/templates/.agents/dashboard/modules/operations/src/react/export/export-layout.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
+import { WORK_EXPORT_COLUMNS } from "./ExcelExportAction.js";
 
 const operationsPage = readFileSync(new URL("../OperationsPage.tsx", import.meta.url), "utf8");
 const operationsNavigation = readFileSync(
@@ -50,7 +51,7 @@ describe("Excel export layout", () => {
   });
 
   it("exports factual developer identities with the work-list rows", () => {
-    expect(action).toContain('"developers"');
+    expect(WORK_EXPORT_COLUMNS).toContain("developers");
     expect(action).toContain("formatDeveloperIdentities(row.developers)");
   });
 

package/templates/.agents/dashboard/modules/operations/src/react/export/xlsx-runtime-e2e.test.ts

@@ -1,7 +1,5 @@
-import { readdirSync } from "node:fs";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { describe, expect, it } from "vitest";
 // `exceljs` exposes this Node-specific entrypoint without a declaration file.
 // The runtime export test needs the Node loader rather than ExcelJS's browser build.
@@ -176,46 +174,61 @@ const cases: readonly Case[] = [
 ];
 
 describe.skipIf(!enabled)("runtime XLSX exports", () => {
-  it("writes and reopens every eligible XLSX with rows and no wholly empty column", async () => {
-    const root = join(tmpdir(), "zaip-aios");
-    const sessionPaths = await Promise.all(
-      readdirSync(root)
-        .filter((name) => name.startsWith("dashboard-sqlite-"))
-        .map(async (name) => {
-          const path = join(root, name, "dashboard-sqlite-session.json");
-          return { path, modified: (await stat(path).catch(() => null))?.mtimeMs ?? 0 };
-        }),
-    );
-    const sessionPath = sessionPaths.sort((left, right) => right.modified - left.modified)[0]?.path;
-    expect(sessionPath).toBeDefined();
-    const session = JSON.parse(await readFile(sessionPath!, "utf8")) as {
+  it("reopens served exports and preserves headers, every row and unavailable cells", async () => {
+    // An explicit isolated session prevents attaching to a user's unrelated dashboard.
+    const sessionPath = process.env.ZAIP_E2E_XLSX_SESSION;
+    if (!sessionPath) throw new Error("ZAIP_E2E_XLSX_SESSION must name the isolated session");
+    const session = JSON.parse(await readFile(sessionPath, "utf8")) as {
       port: number;
       token: string;
+      proofTaskId: string;
     };
-    const output = join(process.cwd(), "..", "..", "..", "..", ".local", "dashboard-export-e2e");
+    expect(Number.isInteger(session.port) && session.port > 0 && session.port < 65536).toBe(true);
+    expect(session.proofTaskId).toMatch(/^TASK-/);
+    const output = resolve(process.env.ZAIP_E2E_XLSX_OUTPUT ?? ".local/dashboard-export-e2e");
     await mkdir(output, { recursive: true });
-    for (const item of cases) {
+    const report: { name: string; rows: number; pages: number; unavailableCells: number }[] = [];
+    const filtered = {
+      ...cases.find((item) => item.name === "operations-work-list")!,
+      name: "operations-work-list-filtered",
+      query: session.proofTaskId,
+    };
+    for (const item of [...cases, filtered]) {
       const source: Row[] = [];
+      let pages = 0;
+      const filters = "query" in item ? { query: String(item.query) } : {};
       for (let offset = 0; ; ) {
+        const query = new URLSearchParams({
+          view: item.view,
+          offset: String(offset),
+          limit: "1",
+          ...filters,
+        });
         const response = await fetch(
-          `http://127.0.0.1:${session.port}/api/v2/sqlite-views?view=${item.view}&offset=${offset}&limit=100`,
-          { headers: { "x-zaip-session": session.token } },
+          `http://127.0.0.1:${session.port}/api/v2/sqlite-views?${query}`,
+          { headers: { "x-zaip-session": session.token }, signal: AbortSignal.timeout(30_000) },
         );
         expect(response.ok, item.view).toBe(true);
         const page = (await response.json()) as { rows: Row[]; total_count: number };
         source.push(...page.rows);
+        pages += 1;
         offset += page.rows.length;
         if (offset >= page.total_count) break;
         expect(page.rows.length, `${item.view} pagination`).toBeGreaterThan(0);
       }
       const rows = item.map(source);
+      if (item.name === "operations-work-list") {
+        expect(rows.length).toBeGreaterThanOrEqual(2);
+        expect(pages).toBeGreaterThan(1);
+      }
+      if (item.name === filtered.name) expect(rows).toHaveLength(1);
       const chunks: Uint8Array[] = [];
       await exportSnapshotToXlsxParts({
         snapshot: createExportSnapshot({
           id: item.name,
           createdAt: new Date().toISOString(),
           view: item.name,
-          filters: {},
+          filters,
           totalRows: rows.length,
           pages: async function* () {
             yield rows;
@@ -234,15 +247,26 @@ describe.skipIf(!enabled)("runtime XLSX exports", () => {
       await writeFile(path, Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
       const workbook = new ExcelJS.Workbook();
       await workbook.xlsx.load(await readFile(path));
-      expect(workbook.worksheets[0]?.rowCount, item.name).toBe(rows.length + 1);
-      const empty = item.headers.filter(
-        (header) =>
-          rows.length > 0 &&
-          rows.every(
-            (row) => row[header] === null || row[header] === undefined || row[header] === "",
-          ),
-      );
-      expect(empty, `${item.name} columns`).toEqual([]);
+      const sheet = workbook.worksheets[0];
+      expect(sheet?.rowCount, item.name).toBe(rows.length + 1);
+      expect(sheet.getRow(1).values.slice(1), item.name).toEqual(item.headers);
+      let unavailableCells = 0;
+      for (const [index, row] of rows.entries()) {
+        for (const [column, header] of item.headers.entries()) {
+          const value = row[header];
+          if (value === null || value === undefined) unavailableCells += 1;
+          const expected = typeof value === "number" ? value : String(value ?? "");
+          expect(
+            sheet.getCell(index + 2, column + 1).value ?? "",
+            `${item.name}:${index}:${header}`,
+          ).toEqual(expected);
+        }
+      }
+      report.push({ name: item.name, rows: rows.length, pages, unavailableCells });
     }
+    await writeFile(
+      join(output, "report.json"),
+      JSON.stringify({ passed: true, views: report }, null, 2),
+    );
   }, 120_000);
 });

package/templates/.agents/dashboard/modules/operations/src/react/operations-export-duration.ts

@@ -0,0 +1,13 @@
+import { applyFactualPeriodDurations } from "./PeriodSummaryTable.js";
+import type { PeriodGranularity, PeriodSummaryRow } from "./period-summary.js";
+
+/** Applies shared duration facts only to the period exports that own them. */
+export function factualDurationRowsForExport(
+  granularity: PeriodGranularity,
+  rows: readonly PeriodSummaryRow[],
+  factualRows?: readonly { key: string; duration_ms: number | null }[],
+): PeriodSummaryRow[] {
+  return granularity === "month" || granularity === "year"
+    ? applyFactualPeriodDurations(rows, factualRows)
+    : [...rows];
+}

package/templates/.agents/dashboard/modules/operations/src/react/operations-filter-panel.css

@@ -185,3 +185,7 @@
     transform: rotate(360deg);
   }
 }
+.operations-entity-filters {
+  display: grid;
+  gap: 12px;
+}

package/templates/.agents/dashboard/modules/operations/src/react/use-operation-filter-feedback.ts

@@ -0,0 +1,18 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export function useOperationFilterFeedback() {
+  const [filterLoading, setFilterLoading] = useState(false);
+  const filterLoadingTimer = useRef<number | null>(null);
+  const showFilterLoading = useCallback(() => {
+    setFilterLoading(true);
+    if (filterLoadingTimer.current !== null) window.clearTimeout(filterLoadingTimer.current);
+    filterLoadingTimer.current = window.setTimeout(() => setFilterLoading(false), 220);
+  }, []);
+  useEffect(
+    () => () => {
+      if (filterLoadingTimer.current !== null) window.clearTimeout(filterLoadingTimer.current);
+    },
+    [],
+  );
+  return { filterLoading, showFilterLoading };
+}