@zaip-ai/cli 1.0.6 → 1.0.7

package/templates/.agents/dashboard/packages/contracts/src/period-counts.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import {
+  aggregateDashboardLifecyclePeriods,
+  dashboardCalendarDateBoundary,
+  dashboardPeriodKey,
+} from "./index.js";
+
+describe("dashboard period contract", () => {
+  it("uses the Sao Paulo calendar consistently at UTC midnight", () => {
+    expect(dashboardPeriodKey("2026-07-31T01:00:00.000Z", "day")).toBe("2026-07-30");
+  });
+
+  it("converts a complete Sao Paulo calendar day into UTC projection boundaries", () => {
+    expect(dashboardCalendarDateBoundary("2026-07-31", "start")).toBe("2026-07-31T03:00:00.000Z");
+    expect(dashboardCalendarDateBoundary("2026-07-31", "end")).toBe("2026-08-01T02:59:59.999Z");
+  });
+
+  it("counts lifecycle entities by creation and deduplicates evidence", () => {
+    const input = {
+      prds: [{ created_at: "2026-07-31T01:00:00.000Z" }],
+      specs: [{ created_at: "2026-07-31T01:00:00.000Z" }],
+      tasks: [
+        {
+          created_at: "2026-07-31T01:00:00.000Z",
+          result: { evidence_ids: ["EVD-1", "EVD-2"] },
+          test_count: 2,
+        },
+        {
+          created_at: "2026-07-30T15:00:00.000Z",
+          result: { evidence_ids: ["EVD-2"] },
+          test_count: 1,
+        },
+      ],
+    };
+
+    expect(aggregateDashboardLifecyclePeriods(input, "day")).toEqual([
+      { key: "2026-07-30", prds: 1, specs: 1, tasks: 2, tests: 3, evidences: 2 },
+    ]);
+    expect(aggregateDashboardLifecyclePeriods(input, "month")[0]).toMatchObject({
+      key: "2026-07",
+      tasks: 2,
+    });
+    expect(aggregateDashboardLifecyclePeriods(input, "year")[0]).toMatchObject({
+      key: "2026",
+      tasks: 2,
+    });
+  });
+});

package/templates/.agents/dashboard/packages/contracts/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/.agents/dashboard/packages/data-export/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@zaip-ai/dashboard-data-export",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zaip-ai/dashboard-contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "exceljs": "^4.4.0"
+  }
+}

package/templates/.agents/dashboard/packages/data-export/src/index.test.ts

@@ -0,0 +1,268 @@
+import ExcelJS from "exceljs";
+import { describe, expect, it } from "vitest";
+import {
+  createExportSnapshot,
+  exportPartCount,
+  exportSnapshotToXlsxParts,
+  pipeRowsWithBackpressure,
+  StoredZipArchive,
+  writeXlsxStream,
+} from "./index.js";
+
+describe("data export core", () => {
+  it("keeps snapshot metadata immutable and uses lazy pages", async () => {
+    let consumed = 0;
+    const snapshot = createExportSnapshot({
+      id: "snapshot-1",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: { q: "a" },
+      totalRows: 2,
+      pages: async function* () {
+        consumed += 1;
+        yield [{ id: 1 }, { id: 2 }];
+      },
+    });
+    expect(snapshot.version).toBe(2);
+    expect(Object.isFrozen(snapshot.filters)).toBe(true);
+    expect(consumed).toBe(0);
+    for await (const page of snapshot.pages()) expect(page).toHaveLength(2);
+    expect(consumed).toBe(1);
+    expect(exportPartCount(0)).toBe(1);
+    expect(exportPartCount(1)).toBe(1);
+    expect(exportPartCount(1_000_000)).toBe(1);
+    expect(exportPartCount(1_000_001)).toBe(2);
+  });
+
+  it("writes a readable XLSX with exactly one formatted worksheet", async () => {
+    const chunks: Uint8Array[] = [];
+    await writeXlsxStream({
+      headers: ["id", "total"],
+      rows: (async function* () {
+        yield { values: [1, 0] };
+        yield { values: [2, 3] };
+      })(),
+      writable: {
+        ready: Promise.resolve(),
+        write: async (chunk) => {
+          chunks.push(chunk);
+        },
+        close: async () => {},
+      },
+    });
+    const workbook = new ExcelJS.Workbook();
+    await workbook.xlsx.load(new Uint8Array(Buffer.concat(chunks.map(Buffer.from))));
+    expect(workbook.worksheets).toHaveLength(1);
+    expect(workbook.worksheets[0]?.rowCount).toBe(3);
+  });
+
+  it("awaits WritableStream backpressure for async row sources", async () => {
+    const received: number[] = [];
+    async function* rows() {
+      yield 1;
+      yield 2;
+    }
+    await pipeRowsWithBackpressure(
+      rows(),
+      new WritableStream({
+        write: async (row) => {
+          received.push(row);
+        },
+      }),
+    );
+    expect(received).toEqual([1, 2]);
+  });
+
+  it("partitions a single-consumption lazy source without buffering rows", async () => {
+    let calls = 0;
+    const snapshot = createExportSnapshot({
+      id: "snapshot-parts",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: {},
+      totalRows: 4,
+      pages: async function* () {
+        if (calls++) throw new Error("consumed twice");
+        yield [{ id: 1 }, { id: 2 }];
+        yield [{ id: 3 }, { id: 4 }];
+      },
+    });
+    const parts: number[] = [];
+    const progress: number[] = [];
+    await exportSnapshotToXlsxParts({
+      snapshot,
+      headers: ["id"],
+      maxRowsPerFile: 3,
+      writable: (part) => ({
+        ready: Promise.resolve(),
+        write: async () => {},
+        close: async () => {
+          parts.push(part);
+        },
+      }),
+      progress: (event) => progress.push(event.percent),
+    });
+    expect(parts).toEqual([1, 2]);
+    expect(progress).toEqual([25, 50, 75, 100]);
+    expect(calls).toBe(1);
+  });
+
+  it("streams reduced-boundary XLSX parts into one ZIP archive", async () => {
+    const snapshot = createExportSnapshot({
+      id: "snapshot-zip",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: {},
+      totalRows: 4,
+      pages: async function* () {
+        yield [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }];
+      },
+    });
+    const chunks: Uint8Array[] = [];
+    const archive = new StoredZipArchive({
+      ready: Promise.resolve(),
+      write: async (chunk) => {
+        chunks.push(chunk);
+      },
+      close: async () => {},
+    });
+    await exportSnapshotToXlsxParts({
+      snapshot,
+      headers: ["id"],
+      maxRowsPerFile: 3,
+      writable: (part) => archive.entry(`costs-part-${part}.xlsx`),
+    });
+    await archive.close();
+
+    const zip = new TextDecoder().decode(Buffer.concat(chunks.map(Buffer.from)));
+    expect(zip).toContain("costs-part-1.xlsx");
+    expect(zip).toContain("costs-part-2.xlsx");
+  });
+
+  it("batches 10,000 lazy rows and throttles progress", async () => {
+    const snapshot = createExportSnapshot({
+      id: "snapshot-batch",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: {},
+      totalRows: 10_000,
+      pages: async function* () {
+        for (let row = 0; row < 10_000; row += 100)
+          yield Array.from({ length: 100 }, (_, index) => ({ id: row + index }));
+      },
+    });
+    let writes = 0;
+    const progress: number[] = [];
+    await exportSnapshotToXlsxParts({
+      snapshot,
+      headers: ["id"],
+      maxRowsPerFile: 10_000,
+      writable: () => ({
+        ready: Promise.resolve(),
+        write: async () => {
+          writes += 1;
+        },
+        close: async () => {},
+      }),
+      progress: (event) => progress.push(event.percent),
+    });
+    expect(writes).toBeLessThan(500);
+    expect(progress.length).toBeLessThanOrEqual(102);
+    expect(progress.at(-1)).toBe(100);
+    expect(
+      progress.every((value, index) => index === 0 || value >= (progress[index - 1] ?? 0)),
+    ).toBe(true);
+  });
+
+  it("benchmarks a representative streaming volume without materializing the production boundary", async () => {
+    const baseline = {
+      maxElapsedMs: 30_000,
+      maxHeapPeakBytes: 128 * 1024 * 1024,
+      maxRssPeakBytes: 256 * 1024 * 1024,
+      minRowsPerSecond: 1_000,
+    };
+    const totalRows = 100_000;
+    const snapshotStarted = performance.now();
+    const snapshot = createExportSnapshot({
+      id: "snapshot-performance-sample",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: {},
+      totalRows,
+      pages: async function* () {
+        const pageSize = 1_024;
+        for (let offset = 0; offset < totalRows; offset += pageSize) {
+          const page = [] as Array<{ id: number }>;
+          for (let index = 0; index < Math.min(pageSize, totalRows - offset); index += 1)
+            page.push({ id: offset + index });
+          yield page;
+        }
+      },
+    });
+    const snapshotMs = performance.now() - snapshotStarted;
+    const before = process.memoryUsage();
+    let heapPeakBytes = 0;
+    let rssPeakBytes = 0;
+    let writes = 0;
+    let totalBytes = 0;
+    const started = performance.now();
+    await exportSnapshotToXlsxParts({
+      snapshot,
+      headers: ["id"],
+      writable: () => ({
+        ready: Promise.resolve(),
+        write: async (chunk) => {
+          totalBytes += chunk.byteLength;
+          writes += 1;
+          const memory = process.memoryUsage();
+          heapPeakBytes = Math.max(heapPeakBytes, memory.heapUsed - before.heapUsed);
+          rssPeakBytes = Math.max(rssPeakBytes, memory.rss - before.rss);
+        },
+        close: async () => {},
+      }),
+    });
+    const elapsedMs = performance.now() - started;
+    const measurement = {
+      totalRows,
+      snapshotMs: Math.round(snapshotMs),
+      rowsPerSecond: Math.round((totalRows / elapsedMs) * 1_000),
+      elapsedMs: Math.round(elapsedMs),
+      heapPeakBytes,
+      rssPeakBytes,
+      totalBytes,
+      writes,
+    };
+    console.info(
+      JSON.stringify({ benchmark: "xlsx-stream-representative", baseline, ...measurement }),
+    );
+
+    expect(totalBytes).toBeGreaterThan(0);
+    expect(measurement.rowsPerSecond).toBeGreaterThanOrEqual(baseline.minRowsPerSecond);
+    expect(measurement.elapsedMs).toBeLessThan(baseline.maxElapsedMs);
+    expect(measurement.heapPeakBytes).toBeLessThan(baseline.maxHeapPeakBytes);
+    expect(measurement.rssPeakBytes).toBeLessThan(baseline.maxRssPeakBytes);
+  }, 60_000);
+
+  it("rejects a test part limit above the production maximum", async () => {
+    const snapshot = createExportSnapshot({
+      id: "snapshot-limit",
+      createdAt: "2026-07-31T12:00:00.000Z",
+      view: "costs",
+      filters: {},
+      totalRows: 0,
+      pages: async function* () {},
+    });
+    await expect(
+      exportSnapshotToXlsxParts({
+        snapshot,
+        headers: ["id"],
+        maxRowsPerFile: 1_000_001,
+        writable: () => ({
+          ready: Promise.resolve(),
+          write: async () => {},
+          close: async () => {},
+        }),
+      }),
+    ).rejects.toThrow("maxRowsPerFile");
+  });
+});

package/templates/.agents/dashboard/packages/data-export/src/index.ts

@@ -0,0 +1,84 @@
+import {
+  createExportSnapshot,
+  type ExportSnapshot,
+  exportPartCount,
+} from "@zaip-ai/dashboard-contracts";
+import { writeXlsxStream, type ZipWritable } from "./ooxml-stream.js";
+
+export {
+  type OoxmlRow,
+  StoredZipArchive,
+  writeXlsxStream,
+  type ZipWritable,
+} from "./ooxml-stream.js";
+export { createExportSnapshot, type ExportSnapshot, exportPartCount };
+
+export async function exportSnapshotToXlsxParts<Row extends Record<string, unknown>>(input: {
+  snapshot: ExportSnapshot<Row>;
+  headers: readonly string[];
+  writable: (part: number, total: number) => ZipWritable;
+  progress?: (value: { processed: number; total: number; percent: number; part: number }) => void;
+  /** @internal Tests only; production files never exceed one million rows. */
+  maxRowsPerFile?: number;
+}): Promise<void> {
+  const limit = input.maxRowsPerFile ?? 1_000_000;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000_000)
+    throw new TypeError("maxRowsPerFile must be from 1 through 1,000,000");
+  const total = Math.max(1, Math.ceil(input.snapshot.totalRows / limit));
+  const source = flattenPages(input.snapshot.pages())[Symbol.asyncIterator]();
+  let part = 1;
+  let processed = 0;
+  let reportedPercent = -1;
+  const nextPart = async () => {
+    const active = part++;
+    let rows = 0;
+    await writeXlsxStream({
+      headers: input.headers,
+      rows: (async function* () {
+        while (rows < limit && processed < input.snapshot.totalRows) {
+          const next = await source.next();
+          if (next.done) throw new RangeError("Snapshot ended before totalRows");
+          rows += 1;
+          processed += 1;
+          yield { values: input.headers.map((key) => next.value[key]) };
+          const percent = Math.floor((processed / input.snapshot.totalRows) * 100);
+          if (
+            percent !== reportedPercent ||
+            processed === input.snapshot.totalRows ||
+            rows === limit
+          ) {
+            reportedPercent = percent;
+            input.progress?.({ processed, total: input.snapshot.totalRows, percent, part: active });
+          }
+        }
+      })(),
+      writable: input.writable(active, total),
+    });
+  };
+  if (input.snapshot.totalRows === 0) {
+    await nextPart();
+    input.progress?.({ processed: 0, total: 0, percent: 100, part: 1 });
+    return;
+  }
+  while (processed < input.snapshot.totalRows) await nextPart();
+  if (!(await source.next()).done) throw new RangeError("Snapshot exceeded totalRows");
+}
+
+async function* flattenPages<Row>(pages: AsyncIterable<readonly Row[]>): AsyncIterable<Row> {
+  for await (const page of pages) for (const row of page) yield row;
+}
+
+export async function pipeRowsWithBackpressure<Row>(
+  rows: AsyncIterable<Row>,
+  writable: WritableStream<Row>,
+): Promise<void> {
+  const writer = writable.getWriter();
+  try {
+    for await (const row of rows) {
+      await writer.ready;
+      await writer.write(row);
+    }
+  } finally {
+    await writer.close();
+  }
+}

package/templates/.agents/dashboard/packages/data-export/src/ooxml-stream.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { worksheetXml } from "./ooxml-stream.js";
+
+describe("OOXML worksheet stream", () => {
+  it("emits lazy escaped rows with one sheet view", async () => {
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of worksheetXml(
+      ["Name"],
+      (async function* () {
+        yield { values: ["A&B"] };
+      })(),
+    ))
+      chunks.push(chunk);
+    const xml = new TextDecoder().decode(Buffer.concat(chunks.map(Buffer.from)));
+    expect(xml).toContain("A&B");
+    expect(xml).toContain('ySplit="1"');
+    expect(xml).toContain('autoFilter ref="A1:A1"');
+  });
+});