@zaip-ai/cli 1.0.6 → 1.0.7

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

@@ -0,0 +1,68 @@
+import type { ExecutionV2 } from "@zaip-ai/specs";
+import type { TaskV2 } from "@zaip-ai/tasks";
+import type { MacroProjection } from "../contracts.js";
+import type { ScopedRun } from "./internal.js";
+import { decisionCounts, macroWorkStatus, qualityProjection, usageProjection } from "./usage.js";
+
+export function macroProjection(input: {
+  id: string;
+  title: string;
+  createdAt: string;
+  kind: "prd" | "spec";
+  parentId: string | null;
+  artifactPath: string;
+  lifecycleStatus: string;
+  changeIds: ReadonlySet<string>;
+  executionIds: ReadonlySet<string>;
+  taskIds: ReadonlySet<string>;
+  runs: readonly ScopedRun[];
+  decisions: readonly { origin: "human" | "agent"; scope_type: string; scope_id: string }[];
+  executions: ReadonlyMap<string, ExecutionV2>;
+  tasks: ReadonlyMap<string, TaskV2>;
+}): MacroProjection {
+  const relevantDecisions = input.decisions.filter(
+    (decision) =>
+      (decision.scope_type === "change" && input.changeIds.has(decision.scope_id)) ||
+      (decision.scope_type === "execution" && input.executionIds.has(decision.scope_id)),
+  );
+  const scopedTasks = [...input.taskIds].flatMap((taskId) => {
+    const task = input.tasks.get(taskId);
+    return task === undefined ? [] : [task];
+  });
+  return {
+    id: input.id,
+    title: input.title,
+    created_at: input.createdAt,
+    kind: input.kind,
+    parent_id: input.parentId,
+    artifact_path: input.artifactPath,
+    lifecycle_status: input.lifecycleStatus,
+    work_status: macroWorkStatus(
+      input.lifecycleStatus,
+      [...input.executionIds].map((value) => input.executions.get(value)),
+    ),
+    execution_ids: [...input.executionIds].sort(),
+    task_ids: [...input.taskIds].sort(),
+    planned_tasks: [],
+    run_ids: input.runs.map((run) => run.fold.run.run_id).sort(),
+    execution_count: input.executionIds.size,
+    task_count: input.taskIds.size,
+    run_count: input.runs.length,
+    duration_ms: sumRunDurations(input.runs),
+    decisions: decisionCounts(relevantDecisions),
+    rework_run_count: input.runs.filter((run) => run.fold.run.work_type === "rework").length,
+    quality: qualityProjection(scopedTasks, input.runs),
+    usage: usageProjection(input.runs),
+  };
+}
+
+function sumRunDurations(runs: readonly ScopedRun[]): number | null {
+  const durations = runs
+    .filter((run) => run.fold.run.parent_run_id === null)
+    .flatMap((run) => {
+      const finishedAt = run.fold.finished?.occurred_at;
+      if (finishedAt === undefined) return [];
+      return [Math.max(0, Date.parse(finishedAt) - Date.parse(run.fold.run.occurred_at))];
+    });
+  return durations.length === 0 ? null : durations.reduce((total, duration) => total + duration, 0);
+}

package/templates/.agents/dashboard/modules/operations/src/server/metric-coverage.ts

@@ -0,0 +1,60 @@
+import type {
+  MacroMetricCoverage,
+  MetricCoverageProjection,
+  MetricProvenance,
+  UsageMetricProjection,
+} from "../contracts.js";
+
+const provenance = (): Record<MetricProvenance, number> => ({
+  observed: 0,
+  reconciled: 0,
+  legacy_inferred: 0,
+  estimated: 0,
+});
+
+export function metricCoverage(
+  values: readonly { value: number | null; provenance?: MetricProvenance | undefined }[],
+): MetricCoverageProjection {
+  const known = values.filter(
+    (value): value is { value: number; provenance?: MetricProvenance } => value.value !== null,
+  );
+  const byProvenance = provenance();
+  for (const value of known) {
+    const key = value.provenance ?? "observed";
+    byProvenance[key] = (byProvenance[key] ?? 0) + 1;
+  }
+  return {
+    population: values.length,
+    known: known.length,
+    unknown: values.length - known.length,
+    known_sum: known.reduce((sum, value) => sum + value.value, 0),
+    coverage_ratio: values.length === 0 ? 0 : known.length / values.length,
+    complete: values.length > 0 && known.length === values.length,
+    provenance: byProvenance,
+  };
+}
+
+export function usageMetricCoverage(
+  usage: UsageMetricProjection,
+): Pick<MacroMetricCoverage, "tokens" | "estimated_usd" | "estimated_brl"> {
+  // Coverage counts come from the canonical usage collector; they describe
+  // the same event population as its aggregate sums.
+  const coverage = (known: number, value: number | null) => {
+    const population = usage.events;
+    const observed = Math.min(Math.max(known, 0), population);
+    return {
+      population,
+      known: observed,
+      unknown: population - observed,
+      known_sum: value ?? 0,
+      coverage_ratio: population === 0 ? 0 : observed / population,
+      complete: population > 0 && observed === population,
+      provenance: { ...provenance(), observed },
+    };
+  };
+  return {
+    tokens: coverage(usage.coverage.tokens, usage.tokens.total),
+    estimated_usd: coverage(usage.coverage.usd, usage.cost.usd),
+    estimated_brl: coverage(usage.coverage.brl, usage.cost.brl),
+  };
+}

package/templates/.agents/dashboard/modules/operations/src/server/planned-task-previews.test.ts

@@ -0,0 +1,22 @@
+import type { DeliverySpecV2, PrdV2 } from "@zaip-ai/specs";
+import { describe, expect, it } from "vitest";
+import { plannedTaskPreviews } from "./planned-task-previews.js";
+
+describe("planned Task previews", () => {
+  it("keeps historical macros without PreparedPlan blueprints readable", () => {
+    const prd = {
+      id: "PRD-HISTORICAL",
+      prepared_plan: undefined,
+    } as unknown as PrdV2;
+    const spec = {
+      id: "SPEC-HISTORICAL",
+      prd_id: prd.id,
+      prepared_plan: {},
+    } as unknown as DeliverySpecV2;
+
+    const previews = plannedTaskPreviews([prd], [spec]);
+
+    expect(previews.byPrd.get(prd.id)).toEqual([]);
+    expect(previews.bySpec.get(spec.id)).toEqual([]);
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/server/planned-task-previews.ts

@@ -0,0 +1,55 @@
+import type { DeliverySpecV2, ExecutionV2, PrdV2 } from "@zaip-ai/specs";
+import type { PlannedTaskPreview } from "../contracts.js";
+
+export function plannedTaskPreviews(prds: readonly PrdV2[], specs: readonly DeliverySpecV2[]) {
+  const byPrd = new Map(prds.map((prd) => [prd.id, previews(prd.prepared_plan)] as const));
+  const bySpec = new Map(
+    specs.map((spec) => {
+      const own = previews(spec.prepared_plan);
+      if (own.length > 0 || spec.prd_id === null) return [spec.id, own] as const;
+      const parent = prds.find((prd) => prd.id === spec.prd_id);
+      return [
+        spec.id,
+        parent === undefined ? [] : previews(parent.prepared_plan, spec.id),
+      ] as const;
+    }),
+  );
+  return { byPrd, bySpec };
+}
+
+export function taskExecutionIds(executions: readonly ExecutionV2[]): Map<string, string[]> {
+  const ids = new Map<string, Set<string>>();
+  for (const execution of executions) {
+    if (execution.kind === "interaction") continue;
+    const taskIds = new Set(execution.dag.nodes.map((node) => node.task_id));
+    if (execution.origin.type === "task") taskIds.add(execution.origin.task_id);
+    for (const taskId of taskIds) {
+      ids.set(taskId, new Set([...(ids.get(taskId) ?? []), execution.id]));
+    }
+  }
+  return new Map([...ids].map(([taskId, values]) => [taskId, [...values].sort()]));
+}
+
+function previews(
+  plan: PrdV2["prepared_plan"] | DeliverySpecV2["prepared_plan"],
+  specId?: string,
+): PlannedTaskPreview[] {
+  if (plan === null || plan === undefined || plan.blueprints === undefined) return [];
+  const changeSpecIds = new Map(
+    plan.blueprints.changes.map((change) => [
+      change.id,
+      change.source.type === "spec" || change.source.type === "prd"
+        ? (change.source.spec_id ?? null)
+        : null,
+    ]),
+  );
+  const dependencies = new Map(plan.dag.nodes.map((node) => [node.task_id, node.depends_on]));
+  return plan.blueprints.tasks
+    .filter((task) => specId === undefined || changeSpecIds.get(task.change_id) === specId)
+    .map((task) => ({
+      id: task.id,
+      title: task.title,
+      objective: task.objective,
+      depends_on: dependencies.get(task.id) ?? [],
+    }));
+}

package/templates/.agents/dashboard/modules/operations/src/server/read-task-detail.ts

@@ -0,0 +1,86 @@
+import type { WorkspaceFileSystem, WorkspaceLayout } from "@zaip-ai/core";
+import {
+  ChangeV2Repository,
+  DeliverySpecV2Repository,
+  ExecutionV2Repository,
+  PrdV2Repository,
+} from "@zaip-ai/specs";
+import { TaskV2Repository } from "@zaip-ai/tasks";
+import type {
+  PrdDetailProjection,
+  SpecDetailProjection,
+  TaskDetailProjection,
+} from "../contracts.js";
+import { taskIdsWithStartedExecution } from "../work-readiness.js";
+import { countTaskTestArtifacts } from "./task-test-counts.js";
+import { taskProgress } from "./usage.js";
+
+export async function readTaskDetail(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  taskId: string,
+): Promise<TaskDetailProjection> {
+  if (layout.version === 1) throw new Error("Task detail requires a modern WorkspaceLayout");
+  const tasks = new TaskV2Repository(filesystem, layout);
+  const changes = new ChangeV2Repository(filesystem, layout);
+  const executions = new ExecutionV2Repository(filesystem, layout);
+  const { task, body } = await tasks.read(taskId);
+  const { change } = await changes.read(task.change_id);
+  const specId =
+    change.source.type === "spec"
+      ? change.source.spec_id
+      : change.source.type === "prd"
+        ? change.source.spec_id
+        : null;
+  const testCounts = await countTaskTestArtifacts(filesystem, [task], (changeId) =>
+    changes.path(changeId),
+  );
+  const allExecutions = await executions.list();
+  const startedExecutionTaskIds = taskIdsWithStartedExecution(allExecutions);
+  const execution_ids = allExecutions
+    .filter(
+      (execution) =>
+        execution.kind !== "interaction" &&
+        ((execution.origin.type === "task" && execution.origin.task_id === task.id) ||
+          execution.dag.nodes.some((node) => node.task_id === task.id)),
+    )
+    .map((execution) => execution.id)
+    .sort();
+  return {
+    task: {
+      ...task,
+      attempt_count: task.attempt_count ?? null,
+      artifact_path: tasks.path(task.id),
+      progress: taskProgress(task.status),
+      spec_id: specId,
+      execution_started: startedExecutionTaskIds.has(task.id),
+      execution_ids,
+      execution_count: execution_ids.length,
+      test_count: testCounts.get(task.id) ?? 0,
+    },
+    body,
+    artifact_path: tasks.path(task.id),
+  };
+}
+
+export async function readPrdDetail(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  prdId: string,
+): Promise<PrdDetailProjection> {
+  if (layout.version === 1) throw new Error("PRD detail requires a modern WorkspaceLayout");
+  const prds = new PrdV2Repository(filesystem, layout);
+  const { prd, body } = await prds.read(prdId);
+  return { id: prd.id, title: prd.title, body, artifact_path: prds.path(prd.id) };
+}
+
+export async function readSpecDetail(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  specId: string,
+): Promise<SpecDetailProjection> {
+  if (layout.version === 1) throw new Error("SPEC detail requires a modern WorkspaceLayout");
+  const specs = new DeliverySpecV2Repository(filesystem, layout);
+  const { spec, body } = await specs.read(specId);
+  return { id: spec.id, title: spec.title, body, artifact_path: specs.path(spec.id) };
+}

package/templates/.agents/dashboard/modules/operations/src/server/run-order.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { recentRunsFirst } from "./run-order.js";
+
+describe("Agent Run ordering", () => {
+  it("orders Runs by start time instead of projection shard order", () => {
+    const shardOrder = [
+      { id: "RUN-SHARD-00", started_at: "2026-07-18T22:00:46.248Z" },
+      { id: "RUN-SHARD-06", started_at: "2026-07-20T19:44:11.230Z" },
+      { id: "RUN-SHARD-03", started_at: "2026-07-19T10:00:00.000Z" },
+    ];
+
+    expect(recentRunsFirst(shardOrder).map((run) => run.id)).toEqual([
+      "RUN-SHARD-06",
+      "RUN-SHARD-03",
+      "RUN-SHARD-00",
+    ]);
+    expect(shardOrder.map((run) => run.id)).toEqual([
+      "RUN-SHARD-00",
+      "RUN-SHARD-06",
+      "RUN-SHARD-03",
+    ]);
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/server/run-order.ts

@@ -0,0 +1,11 @@
+export interface StartedRun {
+  id: string;
+  started_at: string;
+}
+
+export function recentRunsFirst<Run extends StartedRun>(runs: readonly Run[]): Run[] {
+  return [...runs].sort(
+    (left, right) =>
+      right.started_at.localeCompare(left.started_at) || right.id.localeCompare(left.id),
+  );
+}

package/templates/.agents/dashboard/modules/operations/src/server/runs.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { mapLimited } from "./runs.js";
+
+describe("mapLimited", () => {
+  it("preserves result order while limiting concurrent work", async () => {
+    let active = 0;
+    let peak = 0;
+    const result = await mapLimited([3, 2, 1, 0], 2, async (value) => {
+      active += 1;
+      peak = Math.max(peak, active);
+      await Promise.resolve();
+      active -= 1;
+      return value;
+    });
+    expect(result).toEqual([3, 2, 1, 0]);
+    expect(peak).toBeLessThanOrEqual(2);
+  });
+
+  it("propagates a batch read failure", async () => {
+    await expect(
+      mapLimited([1, 2], 2, async (value) => {
+        if (value === 2) throw new Error("read failed");
+        return value;
+      }),
+    ).rejects.toThrow("read failed");
+  });
+});

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

@@ -0,0 +1,77 @@
+import type { WorkspaceFileSystem, WorkspaceLayout } from "@zaip-ai/core";
+import { foldRunV2Records, parseRunV2JsonLines } from "@zaip-ai/decisions";
+import type { ProjectionTimeFilter } from "../contracts.js";
+import type { ScopedRun } from "./internal.js";
+
+export async function readScopedRuns(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  filter: ProjectionTimeFilter,
+): Promise<ScopedRun[]> {
+  if (layout.version === 1) throw new TypeError("Operations projection requires a modern layout");
+  const paths = (
+    await Promise.all(
+      runSearchRoots(layout.entityRoot("run"), filter).map((root) =>
+        filesystem.listFiles(root, ".jsonl"),
+      ),
+    )
+  ).flat();
+  const runs = (
+    await mapLimited<string, ScopedRun | null>(paths, 32, async (path) => {
+      const fold = foldRunV2Records(parseRunV2JsonLines(await filesystem.readText(path)));
+      const records = fold.records.filter((record) => inWindow(record.occurred_at, filter));
+      if ((filter.from !== null || filter.to !== null) && records.length === 0) return null;
+      const scoped: ScopedRun = {
+        fold,
+        artifactPath: path,
+        cost: {
+          run: fold.run,
+          records,
+          effective_usage_records: fold.effective_usage_records.filter((record) =>
+            inWindow(record.occurred_at, filter),
+          ),
+        },
+      };
+      return scoped;
+    })
+  ).filter((run): run is ScopedRun => run !== null);
+  return runs.sort((left, right) => left.fold.run.run_id.localeCompare(right.fold.run.run_id));
+}
+
+/** Bounded parallel IO that preserves input result order and propagates failures. */
+export async function mapLimited<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  map: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  for (let start = 0; start < items.length; start += concurrency) {
+    const batch = items.slice(start, start + concurrency);
+    results.push(...(await Promise.all(batch.map(map))));
+  }
+  return results;
+}
+
+/** Avoid opening every historical Run file for a bounded dashboard period. */
+export function runSearchRoots(root: string, filter: ProjectionTimeFilter): string[] {
+  if (filter.from === null || filter.to === null) return [root];
+  const months = new Set<string>();
+  const cursor = new Date(filter.from);
+  const end = new Date(filter.to);
+  cursor.setUTCDate(1);
+  while (cursor <= end) {
+    months.add(
+      `${root}/${cursor.getUTCFullYear()}/${String(cursor.getUTCMonth() + 1).padStart(2, "0")}`,
+    );
+    cursor.setUTCMonth(cursor.getUTCMonth() + 1);
+  }
+  return [...months];
+}
+
+function inWindow(timestamp: string, filter: ProjectionTimeFilter): boolean {
+  const normalized = new Date(timestamp).toISOString();
+  return (
+    (filter.from === null || normalized >= filter.from) &&
+    (filter.to === null || normalized <= filter.to)
+  );
+}

package/templates/.agents/dashboard/modules/operations/src/server/task-test-counts.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { countTaskTestArtifacts } from "./task-test-counts.js";
+
+describe("countTaskTestArtifacts", () => {
+  it("counts only test artifacts that reference each task", async () => {
+    const contents = new Map([
+      ["records/changes/CHG-1/artifacts/tests/TEST-A.log", "TASK-A passed"],
+      ["records/changes/CHG-1/artifacts/tests/TEST-B.md", "TASK-A and TASK-B passed"],
+      ["records/changes/CHG-1/artifacts/evidence/EVD.md", "TASK-A"],
+    ]);
+    const filesystem = {
+      listFiles: async () => [...contents.keys()],
+      readText: async (path: string) => contents.get(path) ?? "",
+    };
+
+    const counts = await countTaskTestArtifacts(
+      filesystem,
+      [
+        { id: "TASK-A", change_id: "CHG-1" },
+        { id: "TASK-B", change_id: "CHG-1" },
+      ],
+      () => "records/changes/CHG-1/change.md",
+    );
+
+    expect(counts).toEqual(
+      new Map([
+        ["TASK-A", 2],
+        ["TASK-B", 1],
+      ]),
+    );
+  });
+});

package/templates/.agents/dashboard/modules/operations/src/server/task-test-counts.ts

@@ -0,0 +1,49 @@
+interface ArtifactFileSystem {
+  listFiles(path: string): Promise<readonly string[]>;
+  readText(path: string): Promise<string>;
+}
+
+interface TaskArtifactOwner {
+  id: string;
+  change_id: string;
+}
+
+export async function countTaskTestArtifacts(
+  filesystem: ArtifactFileSystem,
+  tasks: readonly TaskArtifactOwner[],
+  changePath: (changeId: string) => string,
+): Promise<Map<string, number>> {
+  const counts = new Map(tasks.map((task) => [task.id, 0]));
+  const tasksByChange = new Map<string, TaskArtifactOwner[]>();
+  for (const task of tasks) {
+    tasksByChange.set(task.change_id, [...(tasksByChange.get(task.change_id) ?? []), task]);
+  }
+
+  for (const [changeId, relatedTasks] of tasksByChange) {
+    const artifactPath = changePath(changeId).replace(/\\/g, "/");
+    const changeDirectory = artifactPath.slice(0, artifactPath.lastIndexOf("/"));
+    let paths: readonly string[];
+    try {
+      paths = await filesystem.listFiles(changeDirectory);
+    } catch {
+      continue;
+    }
+    const testPaths = paths.filter(
+      (path) =>
+        path.replace(/\\/g, "/").includes("/artifacts/tests/") &&
+        /\.(?:md|json|jsonl|txt|log)$/i.test(path),
+    );
+    for (const path of testPaths) {
+      let content: string;
+      try {
+        content = await filesystem.readText(path);
+      } catch {
+        continue;
+      }
+      for (const task of relatedTasks) {
+        if (content.includes(task.id)) counts.set(task.id, (counts.get(task.id) ?? 0) + 1);
+      }
+    }
+  }
+  return counts;
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { macroWorkStatus } from "./usage.js";
+
+describe("macroWorkStatus", () => {
+  it("shows execution while a descendant execution is running", () => {
+    expect(macroWorkStatus("active", [{ status: "running" }] as never)).toBe("executing");
+  });
+
+  it("moves an active parent to verification after every execution completes", () => {
+    expect(macroWorkStatus("active", [{ status: "completed" }] as never)).toBe("verifying");
+  });
+
+  it("keeps an active parent executing when a child is blocked", () => {
+    expect(macroWorkStatus("active", [{ status: "blocked" }] as never)).toBe("executing");
+  });
+
+  it("keeps a delivered lifecycle completed even without a projected execution", () => {
+    expect(macroWorkStatus("delivered", [])).toBe("completed");
+  });
+
+  it("preserves explicit blocked and failed macro outcomes", () => {
+    expect(macroWorkStatus("blocked", [])).toBe("blocked");
+    expect(macroWorkStatus("failed", [])).toBe("failed");
+  });
+});