@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/dashboard/apps/frontend/src/snapshot-banner-semantics.test.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { shouldShowSnapshotNotice, snapshotNoticeDelayMs } from "./snapshot-notice.js";
+
+describe("snapshot update banner semantics", () => {
+  it("delays the notice, then hides it on dismiss or completed initial load", () => {
+    expect(snapshotNoticeDelayMs).toBe(1_500);
+    // A fast first-fold load completes before the delay and never flashes.
+    expect(
+      shouldShowSnapshotNotice({
+        snapshotUpdating: true,
+        initialDataPending: true,
+        dismissed: false,
+        delayElapsed: false,
+      }),
+    ).toBe(false);
+    // A genuinely slow initial read receives the helpful stale-snapshot notice.
+    expect(
+      shouldShowSnapshotNotice({
+        snapshotUpdating: true,
+        initialDataPending: true,
+        dismissed: false,
+        delayElapsed: true,
+      }),
+    ).toBe(true);
+    expect(
+      shouldShowSnapshotNotice({
+        snapshotUpdating: true,
+        initialDataPending: true,
+        dismissed: true,
+        delayElapsed: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldShowSnapshotNotice({
+        snapshotUpdating: true,
+        initialDataPending: false,
+        dismissed: false,
+        delayElapsed: true,
+      }),
+    ).toBe(false);
+  });
+
+  it("presents a stale local snapshot as neutral status and reserves alert red for errors", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const boundary = readFileSync(new URL("./AppLoadingBoundary.tsx", import.meta.url), "utf8");
+    const styles = readFileSync(new URL("./styles.css", import.meta.url), "utf8");
+    const snapshot = app.slice(
+      app.indexOf("const initialDataPending"),
+      app.indexOf("const renderedOperations"),
+    );
+    const compactSnapshot = snapshot.replace(/\s+/g, " ");
+    const error = app.slice(app.indexOf("{error ?"), app.indexOf("{/* Cost Monitor boundary"));
+
+    expect(snapshot).toContain('className="app-notice app-snapshot-status" role="status"');
+    expect(snapshot).toContain('aria-live="polite"');
+    expect(snapshot).toContain("shouldShowSnapshotNotice({");
+    expect(snapshot).toContain("delayElapsed: snapshotNoticeDelayElapsed,");
+    expect(compactSnapshot).toMatch(
+      /window\.setTimeout\(\s*\(\) => setSnapshotNoticeDelayElapsed\(true\),\s*snapshotNoticeDelayMs,?\s*\)/,
+    );
+    expect(snapshot).toContain("return () => window.clearTimeout(timeout);");
+    expect(snapshot).toContain("setSnapshotNoticeDismissed(true)");
+    expect(snapshot).toContain('"Fechar aviso de atualização do snapshot"');
+    expect(snapshot).toContain('"Dismiss snapshot update notice"');
+    expect(boundary).toContain("snapshotNotice: ReactNode;");
+    expect(boundary).toContain("{snapshotNotice}");
+    expect(app).not.toContain("{snapshotUpdating ? (");
+    expect(error).toContain('className="app-warning app-error" role="alert"');
+    expect(error).toContain('aria-live="assertive"');
+    expect(error).toContain('"Fechar erro"');
+    expect(error).toContain('"Dismiss error"');
+    expect(styles).toContain(".app-snapshot-status {");
+    expect(styles).toContain("background: rgba(8, 47, 73, 0.96);");
+    expect(styles).toContain(".app-warning.app-error {");
+    expect(styles).toContain("background: rgba(69, 16, 16, 0.96);");
+  });
+});

package/templates/.agents/dashboard/apps/frontend/src/snapshot-coherence.test.ts

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
-import { loadAtomicCostSnapshot, loadCostViewSnapshot } from "./snapshot-coherence.js";
+import { isCurrentDashboardRequest, mergeBoardPages, needsAtomicCostSnapshot } from "./App.js";
+import { loadAtomicCostSnapshot } from "./snapshot-coherence.js";
+import { projectionRefreshDebounceMs, shouldRefreshVisibleProjection } from "./use-app-effects.js";
 
 describe("atomic Cost snapshot loading", () => {
   it("keeps Operations, Cost, and cards on one source generation while the source moves", async () => {
@@ -19,61 +21,254 @@ describe("atomic Cost snapshot loading", () => {
     expect(sourceGeneration).toBe(2);
   });
 
-  it("routes Cost refreshes through the atomic snapshot instead of sequential endpoints", () => {
+  it("keeps Cost out of quick Operations and fetches its narrow summary on entry", () => {
     const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
-    expect(app).toContain("loadAtomicCostSnapshot(() => api.snapshot(currency, period))");
+    expect(app).not.toContain("api.snapshot(currency, period)");
+    expect(app).toContain('api.costMonitor(currency, period, "summary", controller.signal)');
+    expect(app).not.toContain("dailyCostSeed(currency, period)");
+    expect(app).toContain("initialAggregateFreshRef.current");
     expect(app).not.toContain("const nextCosts = await api.costMonitor(currency, period);");
   });
 
-  it("allows only the atomic snapshot to write Cost-view Operations in either completion order", async () => {
-    for (const detailCompletesFirst of [true, false]) {
-      const snapshot = deferred<{ operations: number; costs: number }>();
-      const independentDetails = deferred<number>();
-      const writes: string[] = [];
-      const pending = loadCostViewSnapshot(
-        () => snapshot.promise,
-        (value) => writes.push(`operations:${value.operations}`, `costs:${value.costs}`),
-      );
-
-      if (detailCompletesFirst) independentDetails.resolve(2);
-      await Promise.resolve();
-      expect(writes).toEqual([]);
-
-      snapshot.resolve({ operations: 1, costs: 1 });
-      await pending;
-      if (!detailCompletesFirst) independentDetails.resolve(2);
-      await Promise.resolve();
-
-      expect(writes).toEqual(["operations:1", "costs:1"]);
-    }
+  it("never uses an implicit full snapshot when navigating between areas", () => {
+    expect(needsAtomicCostSnapshot("cost-monitor", false)).toBe(false);
+    expect(needsAtomicCostSnapshot("cost-monitor", true)).toBe(false);
+    expect(needsAtomicCostSnapshot("operations", false)).toBe(false);
+    expect(needsAtomicCostSnapshot("operations", true)).toBe(false);
   });
 
-  it("does not start an independent details load when selecting Cost", () => {
+  it("mounts Cost immediately and lets its Daily page own the only initial request", () => {
     const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
     const costSelection = app.slice(
       app.indexOf('if (nextView === "cost-monitor")'),
       app.indexOf('if (nextView === "traceability")'),
     );
-    expect(costSelection).toContain("void loadCosts();");
+    expect(costSelection).toContain("loadCostSummary()");
+    expect(costSelection).not.toContain("loadCostDetails");
     expect(costSelection).not.toContain("loadOperationsDetails");
   });
 
-  it("shares a silent prefetch with the click and drops it on key change or failure", () => {
+  it("opens the global overlay while the Cost page loads a selected group", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const globalGate = app.slice(
+      app.indexOf("const globalLoadingPending"),
+      app.indexOf("const renderedOperations"),
+    );
+    expect(app).toContain("const [costSurfaceLoading, setCostSurfaceLoading] = useState(false);");
+    expect(globalGate).toContain("costSurfaceLoading");
+    expect(globalGate).toContain('loadingArea !== "costs"');
+  });
+
+  it("does not request Cost Monitor while the initial route is Operations", () => {
     const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
-    expect(app).toContain("const costPrefetch = useRef");
-    expect(app).toContain(
-      "prefetched?.key === costSnapshotKey ? prefetched.promise : api.snapshot(currency, period)",
+    const initialLoad = app.slice(
+      app.indexOf("const refresh = useCallback"),
+      app.indexOf("const loadOperationsDetails"),
     );
-    expect(app).toContain("void promise.catch(() =>");
-    expect(app).toContain("costPrefetch.current = null;");
+
+    expect(initialLoad).toContain('activeDashboardView === "cost-monitor"');
+    expect(initialLoad).toContain("Promise.resolve(null)");
+    expect(initialLoad).not.toContain("api.snapshot(currency, period)");
+  });
+
+  it("retries a failed Cost snapshot through refresh instead of a summary-only Cost request", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const retry = app.slice(app.indexOf("const retryLastLoad"), app.indexOf("const setupRoute"));
+
+    expect(retry).toContain('if (failedArea === "costs") void refresh();');
+    expect(retry).not.toContain("loadCosts");
+  });
+
+  it("does not prefetch or poll a newer Operations snapshot in the background", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const effects = readFileSync(new URL("./use-app-effects.ts", import.meta.url), "utf8");
+    const costLoaders = readFileSync(new URL("./use-app-cost-loaders.ts", import.meta.url), "utf8");
+    expect(app).not.toContain("const costPrefetch = useRef");
+    expect(app).not.toContain("useIdleCostPrefetch");
+    expect(app).not.toContain("window.setInterval");
+    expect(app).toContain("useAppEffects({");
+    expect(effects).toContain("void refresh();");
+    expect(effects).toContain("refresh,");
+    expect(app).toContain("setOperationsPeriod({ preset, range });");
+    expect(app).toContain("setCosts(null);");
+    expect(app).toContain("setDisplayedCosts(null);");
+    expect(app).not.toContain('api.costMonitor(currency, period, "detail")');
+    expect(costLoaders).toContain("api.sqliteViewPage(");
+    expect(costLoaders).not.toContain("api.operationsReadModelPage(");
     expect(app).toContain('setLoadingArea("costs")');
   });
-});
 
-function deferred<Value>() {
-  let resolve!: (value: Value) => void;
-  const promise = new Promise<Value>((nextResolve) => {
-    resolve = nextResolve;
+  it("coalesces focus and visibility events into one non-reconciling projection refresh", () => {
+    expect(
+      shouldRefreshVisibleProjection({
+        visibilityState: "visible",
+        inFlight: false,
+        lastRefreshAt: 0,
+        now: projectionRefreshDebounceMs,
+      }),
+    ).toBe(true);
+    expect(
+      shouldRefreshVisibleProjection({
+        visibilityState: "visible",
+        inFlight: false,
+        lastRefreshAt: projectionRefreshDebounceMs,
+        now: projectionRefreshDebounceMs + 1,
+      }),
+    ).toBe(false);
+    expect(
+      shouldRefreshVisibleProjection({
+        visibilityState: "hidden",
+        inFlight: false,
+        lastRefreshAt: 0,
+        now: projectionRefreshDebounceMs * 2,
+      }),
+    ).toBe(false);
+    const effects = readFileSync(new URL("./use-app-effects.ts", import.meta.url), "utf8");
+    expect(effects).toContain('window.addEventListener("focus", refreshVisibleProjection)');
+    expect(effects).toContain(
+      'document.addEventListener("visibilitychange", refreshVisibleProjection)',
+    );
+    expect(effects).not.toContain("setInterval");
+    expect(effects).toContain("void refresh(false, false, true)");
+  });
+
+  it("removes the global Cost detail request and keeps stale request guards", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const costPage = readFileSync(
+      new URL("../../../modules/cost-monitor/src/react/CostMonitorPage.tsx", import.meta.url),
+      "utf8",
+    );
+    const compactPageHook = readFileSync(
+      new URL("../../../modules/cost-monitor/src/react/use-compact-cost-page.ts", import.meta.url),
+      "utf8",
+    );
+    expect(app).not.toContain("const loadCostDetails");
+    expect(app).not.toContain('api.costMonitor(currency, period, "detail")');
+    expect(compactPageHook).toContain("generation === generationRef.current");
+    expect(compactPageHook).toContain("return () => controller.abort();");
+    expect(costPage).toContain("useCompactCostPage");
+    expect(isCurrentDashboardRequest(7, 8)).toBe(false);
+    expect(isCurrentDashboardRequest(8, 8)).toBe(true);
   });
-  return { promise, resolve };
-}
+
+  it("reproduces a stale active export after a period change and clears it before the atomic replacement", () => {
+    const stalePeriod = {
+      costs: { generation: 1 },
+      activeExport: { generation: 1 },
+    };
+    const afterPeriodChange = {
+      costs: null,
+      activeExport: null,
+    };
+
+    expect(stalePeriod).toEqual({
+      costs: { generation: 1 },
+      activeExport: { generation: 1 },
+    });
+    expect(afterPeriodChange).toEqual({ costs: null, activeExport: null });
+
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const periodChange = app.slice(
+      app.indexOf("onDateChange={(preset, range) => {"),
+      app.indexOf("settings={"),
+    );
+    expect(periodChange.indexOf("setCosts(null);")).toBeGreaterThan(-1);
+    expect(periodChange.indexOf("setDisplayedCosts(null);")).toBeGreaterThan(-1);
+    expect(periodChange.indexOf("setCosts(null);")).toBeLessThan(
+      periodChange.indexOf("setOperationsPeriod({ preset, range });"),
+    );
+    expect(periodChange.indexOf("setDisplayedCosts(null);")).toBeLessThan(
+      periodChange.indexOf("setOperationsPeriod({ preset, range });"),
+    );
+    expect(periodChange).toContain("setOperationsLoading(true);");
+    expect(periodChange).toContain('setLoadingArea("operations");');
+    expect(periodChange).not.toContain("setOperations(null);");
+  });
+
+  it("owns the rendered Operations period in App and routes date changes back to its request state", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const operationsPage = app.slice(app.indexOf("<OperationsPage"), app.indexOf("<AppOverlays"));
+
+    expect(operationsPage).toContain("datePreset={operationsPeriod.preset}");
+    expect(operationsPage).toContain("dateRange={operationsPeriod.range}");
+    expect(operationsPage).toContain("onDateChange={(preset, range) => {");
+    expect(operationsPage).toContain("setOperationsPeriod({ preset, range });");
+  });
+
+  it("keeps detail hydration stable when the quick Operations projection updates", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const detailsLoader = app.slice(
+      app.indexOf("const loadOperationsDetails"),
+      app.indexOf("const loadMoreBoard"),
+    );
+
+    expect(detailsLoader).toContain("if (operationsDetailLoadedRef.current) return null;");
+    expect(detailsLoader).toContain("[api, operationsPeriod],");
+    expect(detailsLoader).not.toContain("}, [api, operations, operationsPeriod]);");
+  });
+
+  it("loads the compact Operations projection before detail data", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const initialLoad = app.slice(
+      app.indexOf("const refresh = useCallback"),
+      app.indexOf("const loadOperationsDetails"),
+    );
+
+    expect(initialLoad).toContain("const [projection, costSummary] = await Promise.all([");
+    expect(initialLoad).toContain("operationsDetailLoadedRef.current = false;");
+    expect(initialLoad).toContain(
+      'api.operations(period, "quick", undefined, initialAggregateFreshRef.current)',
+    );
+    expect(initialLoad).not.toContain(
+      "workBoardStages.map((stage) => api.operationsBoard(period, stage))",
+    );
+  });
+
+  it("defers bounded work-board hydration until after the quick first paint", () => {
+    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const boardHydration = app.slice(
+      app.indexOf('if (dashboardView !== "operations" || operations === null) return;'),
+      app.indexOf("const loadCostDetails"),
+    );
+
+    expect(boardHydration).toContain("for (const stage of initialWorkBoardStages)");
+    expect(boardHydration).toContain("window.requestIdleCallback(hydrateBoard)");
+    expect(boardHydration).toContain("window.setTimeout(hydrateBoard, 0)");
+    expect(boardHydration).toContain("!boardInitialPageRef.current.has(stage)");
+    expect(boardHydration).toContain("boardInitialPageRef.current.add(stage)");
+    expect(boardHydration).toContain("!boardInFlightRef.current.has(stage)");
+    expect(boardHydration).toContain("void loadMoreBoard(stage)");
+  });
+
+  it("merges concurrent board pages without replacing rows from another stage", () => {
+    const projection = {
+      prds: [{ id: "PRD-EXISTING" }],
+      specs: [],
+      tasks: [{ id: "TASK-EXISTING" }],
+      changes: [],
+    } as unknown as Parameters<typeof mergeBoardPages>[0];
+    const first = {
+      prds: [],
+      specs: [{ id: "SPEC-FIRST" }],
+      tasks: [{ id: "TASK-FIRST" }],
+      changes: [],
+    } as unknown as Parameters<typeof mergeBoardPages>[1][number];
+    const second = {
+      prds: [],
+      specs: [],
+      tasks: [{ id: "TASK-SECOND" }, { id: "TASK-FIRST" }],
+      changes: [{ id: "CHANGE-SECOND" }],
+    } as unknown as Parameters<typeof mergeBoardPages>[1][number];
+
+    const merged = mergeBoardPages(mergeBoardPages(projection, [first]), [second]);
+
+    expect(merged.prds.map(({ id }) => id)).toEqual(["PRD-EXISTING"]);
+    expect(merged.specs.map(({ id }) => id)).toEqual(["SPEC-FIRST"]);
+    expect(merged.tasks.map(({ id }) => id)).toEqual([
+      "TASK-EXISTING",
+      "TASK-FIRST",
+      "TASK-SECOND",
+    ]);
+    expect(merged.changes.map(({ id }) => id)).toEqual(["CHANGE-SECOND"]);
+  });
+});

package/templates/.agents/dashboard/apps/frontend/src/snapshot-notice.ts

@@ -0,0 +1,15 @@
+export const snapshotNoticeDelayMs = 1_500;
+
+export function shouldShowSnapshotNotice({
+  snapshotUpdating,
+  initialDataPending,
+  dismissed,
+  delayElapsed,
+}: {
+  snapshotUpdating: boolean;
+  initialDataPending: boolean;
+  dismissed: boolean;
+  delayElapsed: boolean;
+}): boolean {
+  return snapshotUpdating && initialDataPending && !dismissed && delayElapsed;
+}

package/templates/.agents/dashboard/apps/frontend/src/sqlite-cost-adapters.ts

@@ -0,0 +1,26 @@
+export type LegacyKnownMetric = {
+  known_sum: number;
+  unknown: number;
+  complete: boolean;
+  coverage_ratio: number;
+};
+
+export function nullableSqlNumber(value: unknown): number | null {
+  return typeof value === "number" ? value : null;
+}
+
+export function requiredSqlNumber(value: unknown, column: string): number {
+  if (typeof value === "number") return value;
+  throw new Error(`SQLite view is missing required numeric column: ${column}`);
+}
+
+export function legacyKnownMetric(value: unknown): LegacyKnownMetric {
+  return typeof value === "number"
+    ? { known_sum: value, unknown: 0, complete: true, coverage_ratio: 1 }
+    : { known_sum: 0, unknown: 1, complete: false, coverage_ratio: 0 };
+}
+
+export function costGroupDuration(row: Record<string, unknown>): number | null {
+  if (Object.hasOwn(row, "total_duration")) return nullableSqlNumber(row.total_duration);
+  return nullableSqlNumber(row.cost_monitor_total_duration);
+}

package/templates/.agents/dashboard/apps/frontend/src/styles.css

@@ -286,6 +286,7 @@ select:focus-visible {
   }
 }
 
+.app-notice,
 .app-warning {
   position: fixed;
   z-index: 80;
@@ -294,13 +295,24 @@ select:focus-visible {
   display: flex;
   gap: 1rem;
   max-width: min(520px, calc(100% - 2rem));
-  border: 1px solid rgba(248, 113, 113, 0.28);
   border-radius: 16px;
   padding: 0.9rem 1rem;
+  box-shadow: var(--shadow);
+}
+
+.app-snapshot-status {
+  border: 1px solid rgba(56, 189, 248, 0.34);
+  background: rgba(8, 47, 73, 0.96);
+  color: #dbeafe;
+}
+
+.app-warning.app-error {
+  border: 1px solid rgba(248, 113, 113, 0.28);
   background: rgba(69, 16, 16, 0.96);
   color: #fecaca;
-  box-shadow: var(--shadow);
 }
+
+.app-notice button,
 .app-warning button {
   border: 0;
   background: transparent;

package/templates/.agents/dashboard/apps/frontend/src/traceability-workspace.css

@@ -17,14 +17,14 @@
   flex: 1;
   gap: 7px;
 }
-.traceability-workspace > header span {
+.traceability-workspace > header label {
   color: #7dd3fc;
   font-size: 0.65rem;
   font-weight: 700;
   letter-spacing: 0.08em;
   text-transform: uppercase;
 }
-.traceability-workspace select {
+.traceability-workspace input {
   width: 100%;
   min-height: 48px;
   border: 1px solid rgba(96, 165, 250, 0.28);
@@ -34,6 +34,42 @@
   color: #f8fafc;
   font-size: 0.92rem;
 }
+.traceability-task-results {
+  display: grid;
+  max-height: 260px;
+  margin: 0;
+  padding: 6px;
+  overflow-y: auto;
+  border: 1px solid rgba(96, 165, 250, 0.28);
+  border-radius: 13px;
+  background: #0a1220;
+  list-style: none;
+}
+.traceability-task-results button {
+  display: grid;
+  width: 100%;
+  gap: 2px;
+  padding: 10px 12px;
+  border: 0;
+  border-radius: 9px;
+  color: #f8fafc;
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+}
+.traceability-task-results button:hover,
+.traceability-task-results button:focus-visible,
+.traceability-task-results button.is-active {
+  outline: none;
+  background: rgba(56, 189, 248, 0.15);
+}
+.traceability-task-results button small,
+.traceability-task-no-results {
+  color: #a8b6c9;
+}
+.traceability-task-no-results {
+  padding: 12px;
+}
 .traceability-workspace > header small {
   max-width: 360px;
   color: #71829a;