@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/dashboard/packages/local-runtime/src/server-dual-reads-manifest-summaries-without-losing.test.ts

@@ -0,0 +1,344 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  createDashboardApp,
+  manifestRun,
+  mergeManifestRuns,
+  openWorkIds,
+  reconciliationResult,
+} from "./server.js";
+import { invocationSummary } from "./server.test-fixtures.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+describe("dashboard backend", () => {
+  it("dual-reads manifest summaries without losing legacy runs, costs, coverage, or hierarchy", () => {
+    const root = invocationSummary({
+      agent_invocation_id: "AINV-ROOT",
+      root_agent_invocation_id: "AINV-ROOT",
+      run_id: "RUN-ROOT",
+      invocation_kind: "orchestrator",
+      delegation_depth: 0,
+    });
+    const child = invocationSummary({
+      agent_invocation_id: "AINV-CHILD",
+      root_agent_invocation_id: "AINV-ROOT",
+      parent_agent_invocation_id: "AINV-ROOT",
+      run_id: "RUN-CHILD",
+      invocation_kind: "delegated",
+      delegation_depth: 1,
+    });
+    const legacyRoot = { ...manifestRun(root, [root, child]), client_thread_id: "legacy-thread" };
+    const legacyOnly = { ...legacyRoot, id: "RUN-LEGACY" };
+    const merged = mergeManifestRuns([legacyRoot, legacyOnly], [root, child]);
+    const mergedRoot = merged.find((run) => run.id === "RUN-ROOT");
+    const mergedChild = merged.find((run) => run.id === "RUN-CHILD");
+    expect(merged).toHaveLength(3);
+    expect(mergedRoot).toMatchObject({
+      client_thread_id: "legacy-thread",
+      run_role: "orchestrator",
+      run_kind: "run",
+      usage: {
+        total: {
+          cost: { usd: 1.25, brl: 7.5 },
+          coverage: { tokens: 1, usd: 1, brl: 1 },
+        },
+      },
+    });
+    expect(mergedChild).toMatchObject({
+      run_role: "subagent",
+      run_kind: "subrun",
+      parent_run_id: "RUN-ROOT",
+    });
+  });
+  it("keeps lifecycle calendar and accounting authoritative while enriching dimensions", () => {
+    const summary = invocationSummary({ run_id: "RUN-CANONICAL" });
+    summary.occurred_at = "2026-08-08T03:10:00.000Z";
+    const projected = manifestRun(summary, [summary]);
+    const legacy = {
+      ...projected,
+      started_at: "2026-08-07T02:57:00.000Z",
+      finished_at: "2026-08-07T03:06:00.000Z",
+      provider: null,
+      usage: {
+        ...projected.usage,
+        total: {
+          ...projected.usage.total,
+          tokens: { ...projected.usage.total.tokens, total: 999 },
+          cost: { usd: 1, brl: 9 },
+        },
+      },
+    };
+    expect(mergeManifestRuns([legacy], [summary])[0]).toMatchObject({
+      started_at: "2026-08-07T02:57:00.000Z",
+      finished_at: "2026-08-07T03:06:00.000Z",
+      provider: "openai",
+      usage: { total: { tokens: { total: 999 }, cost: { brl: 9 } } },
+    });
+  });
+  it("enriches a missing lifecycle token breakdown without replacing known accounting", () => {
+    const summary = invocationSummary({ run_id: "RUN-TOKEN-DETAIL" });
+    const projected = manifestRun(summary, [summary]);
+    const legacy = {
+      ...projected,
+      usage: {
+        ...projected.usage,
+        total: {
+          ...projected.usage.total,
+          tokens: { ...projected.usage.total.tokens, input: null, total: null },
+        },
+      },
+    };
+    const merged = mergeManifestRuns([legacy], [summary])[0]!;
+    expect(merged.usage.total.tokens).toMatchObject({
+      input: projected.usage.total.tokens.input,
+      total: projected.usage.total.tokens.total,
+    });
+  });
+  it("retains bounded lifecycle duration when a manifest summary has no duration", () => {
+    const summary = invocationSummary();
+    summary.time.duration_ms = null;
+    summary.quantitative_coverage.duration_ms = "unavailable";
+    summary.quantitative_metrics.duration_ms = {
+      known_sum: null,
+      unknown_count: 1,
+      total_count: 1,
+      complete: 0,
+      coverage_ratio: 0,
+    };
+    const legacy = {
+      ...manifestRun(summary, [summary]),
+      duration_ms: 12_000,
+      source_duration_ms: 0,
+      source_started_at: "2026-07-26T12:00:00.000Z",
+      source_finished_at: "2026-07-26T12:00:00.000Z",
+      capture_lag_ms: 12_000,
+    };
+    const merged = mergeManifestRuns([legacy], [summary]);
+    expect(merged[0]).toMatchObject({
+      duration_ms: 12_000,
+      source_duration_ms: null,
+      source_started_at: null,
+      source_finished_at: null,
+      capture_lag_ms: null,
+    });
+  });
+  it("does not let an unavailable manifest duration erase recovered source timing", () => {
+    const summary = invocationSummary();
+    summary.time.duration_ms = null;
+    const legacy = {
+      ...manifestRun(summary, [summary]),
+      duration_ms: 12_000,
+      source_duration_ms: 12_000,
+      source_started_at: "2026-07-26T12:00:00.000Z",
+      source_finished_at: "2026-07-26T12:00:12.000Z",
+      capture_lag_ms: 0,
+    };
+    expect(mergeManifestRuns([legacy], [summary])[0]).toMatchObject({
+      duration_ms: 12_000,
+      source_duration_ms: 12_000,
+      source_started_at: "2026-07-26T12:00:00.000Z",
+      source_finished_at: "2026-07-26T12:00:12.000Z",
+    });
+  });
+  it("rejects mutating methods before route dispatch", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const response = await app.request("/api/v2/operations", { method: "POST" });
+    expect(response.status).toBe(405);
+    expect(response.headers.get("allow")).toBe("GET, HEAD");
+  });
+  it("selects only entities represented in open work stages for reconciliation", () => {
+    expect(
+      openWorkIds([
+        { kind: "prd", id: "PRD-DRAFT", status: "draft" },
+        { kind: "spec", id: "SPEC-ACTIVE", status: "active" },
+        { kind: "change", id: "CHG-PLANNED", status: "planned" },
+        { kind: "task", id: "TASK-PLANNED", status: "planned" },
+        { kind: "task", id: "TASK-VERIFYING", status: "verifying" },
+        { kind: "execution", id: "EXEC-RUNNING", status: "running" },
+        { kind: "run", id: "RUN-RUNNING", status: "running" },
+        { kind: "task", id: "TASK-COMPLETED", status: "completed" },
+        { kind: "task", id: "TASK-BLOCKED", status: "blocked" },
+      ]),
+    ).toEqual(["EXEC-RUNNING", "SPEC-ACTIVE", "TASK-PLANNED", "TASK-VERIFYING"]);
+  });
+  it("separates canonical reconciliation outcomes from blocked and unresolved work", () => {
+    expect(
+      reconciliationResult({
+        reconciliations: [
+          {
+            status: "closed",
+            error: null,
+            tasks: [
+              { id: "TASK-COMPLETED", status: "completed" },
+              { id: "TASK-BLOCKED", status: "blocked", status_reason: "Missing finalizer." },
+            ],
+            changes: [{ id: "CHG-COMPLETED", status: "completed" }],
+            executions: [],
+            specs: [],
+            prds: [],
+          },
+          {
+            status: "deferred",
+            error: "Canonical gates are incomplete.",
+            tasks: [{ id: "TASK-DEFERRED", status: "executing" }],
+            changes: [],
+            executions: [],
+            specs: [],
+            prds: [],
+          },
+        ],
+        orphaned_executions: ["EXEC-ORPHANED"],
+        reconciliation_errors: [{ run_id: "RUN-FAILED", error: "Could not read Run." }],
+        unresolved_running_run_ids: ["RUN-ACTIVE"],
+      }),
+    ).toEqual({
+      reconciled_ids: ["CHG-COMPLETED", "TASK-BLOCKED", "TASK-COMPLETED"],
+      blocked: [
+        {
+          id: "EXEC-ORPHANED",
+          reason: "Execution orphaned after the reconciliation grace period.",
+        },
+        { id: "TASK-BLOCKED", reason: "Missing finalizer." },
+      ],
+      not_reconciled: [
+        { id: "RUN-ACTIVE", reason: "Invocation is still running." },
+        { id: "RUN-FAILED", reason: "Could not read Run." },
+        { id: "TASK-DEFERRED", reason: "Canonical gates are incomplete." },
+      ],
+    });
+  });
+  it("requires the local session for projections", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const response = await app.request("/api/v2/operations");
+    expect(response.status).toBe(401);
+  });
+  it("bootstraps a protected browser session from the dashboard document", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const document = await app.request("/", {
+      headers: { "sec-fetch-site": "none" },
+    });
+    const cookie = document.headers.get("set-cookie");
+    expect(cookie).toContain("zaip-dashboard-sqlite-session=test-session");
+    expect(cookie).toContain("HttpOnly");
+    expect(cookie).toContain("SameSite=Strict");
+    expect(cookie).toContain("Path=/");
+    const response = await app.request("/api/v2/operations?scope=quick", {
+      headers: {
+        cookie: cookie?.split(";", 1)[0] ?? "",
+        "x-zaip-session": "",
+      },
+    });
+    expect(response.status, await response.clone().text()).toBe(200);
+  });
+  it("does not bootstrap sessions for cross-site requests", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const response = await app.request("/", {
+      headers: { "sec-fetch-site": "cross-site" },
+    });
+    expect(response.headers.get("set-cookie")).toBeNull();
+  });
+  it("keeps origin checks and accepts a valid cookie alongside a stale header", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const cookie = "zaip-dashboard-sqlite-session=test-session";
+    const rejectedOrigin = await app.request("/api/v2/pricing", {
+      method: "PUT",
+      headers: { cookie, origin: "https://example.com" },
+    });
+    const rejectedHeader = await app.request("/api/v2/pricing", {
+      headers: { "x-zaip-session": "invalid-session" },
+    });
+    const recoveredSession = await app.request("/api/v2/pricing", {
+      headers: { cookie, "x-zaip-session": "stale-session" },
+    });
+    expect(rejectedOrigin.status).toBe(403);
+    expect(rejectedHeader.status).toBe(401);
+    expect(recoveredSession.status, await recoveredSession.clone().text()).toBe(200);
+  });
+  it("does not serve files outside the configured UI root", async () => {
+    const parent = await mkdtemp(join(tmpdir(), "zaip-dashboard-static-boundary-"));
+    const uiRoot = join(parent, "ui");
+    await mkdir(uiRoot);
+    await writeFile(join(uiRoot, "index.html"), "<title>Dashboard</title>", "utf8");
+    await writeFile(join(parent, "secret.txt"), "must-not-be-served", "utf8");
+    try {
+      const app = createDashboardApp(workspaceRoot, "test-session", uiRoot);
+      const response = await app.request("/..%2Fsecret.txt");
+      expect(response.status).not.toBe(200);
+      await expect(response.text()).resolves.not.toContain("must-not-be-served");
+    } finally {
+      await rm(parent, { recursive: true, force: true });
+    }
+  });
+  it("proves canonical projection readiness without exposing authenticated data", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const ready = await app.request("/api/v2/ready");
+    const protectedProjection = await app.request("/api/v2/operations?scope=quick");
+    expect(ready.status, await ready.clone().text()).toBe(200);
+    await expect(ready.json()).resolves.toMatchObject({ status: "ready" });
+    expect(protectedProjection.status).toBe(401);
+  });
+  it("uses the SQLite fact for snapshot readiness without lifecycle daily views", async () => {
+    const source = await import("node:fs/promises").then(({ readFile }) =>
+      readFile(new URL("./server.ts", import.meta.url), "utf8"),
+    );
+    const ready = source.slice(
+      source.indexOf('app.on(["GET", "HEAD"], `${API_PREFIX}/ready`'),
+      source.indexOf('app.on(["GET", "HEAD"], `${API_PREFIX}/operations`'),
+    );
+    expect(ready).toContain("if (isSqliteSnapshot)");
+    expect(ready).not.toContain("firstFoldAllTime()");
+    expect(ready).not.toContain("readAggregate(");
+    expect(ready).not.toContain("dashboard_sqlite_prewarm");
+    expect(ready).not.toContain("firstFoldViewportAllTime()");
+    expect(ready).toContain("day_count: metadata.daily_aggregate_count");
+    expect(ready).toContain("storage_mode: metadata.storage_mode");
+  });
+  it("loads daily periods only for the explicit overview/detail projection", async () => {
+    const source = await import("node:fs/promises").then(({ readFile }) =>
+      readFile(new URL("./server-read-projections.ts", import.meta.url), "utf8"),
+    );
+    const projection = source.slice(
+      source.indexOf("function buildSqliteOperationsProjection"),
+      source.indexOf("function nullableMetric"),
+    );
+    expect(projection).toContain(
+      "options.includePeriods === true ? filesystem.dailyPeriods(filter) : {}",
+    );
+    expect(
+      await import("node:fs/promises").then(({ readFile }) =>
+        readFile(new URL("./server-operations-routes.ts", import.meta.url), "utf8"),
+      ),
+    ).toContain('includePeriods: scope === "detail" || scope === "overview"');
+  });
+  it("rebuilds a fresh aggregate after an in-flight normal read instead of sharing its payload", async () => {
+    const source = await import("node:fs/promises").then(({ readFile }) =>
+      readFile(new URL("./server.ts", import.meta.url), "utf8"),
+    );
+    const aggregate = source.slice(
+      source.indexOf("const readAggregate"),
+      source.indexOf("const snapshotKey"),
+    );
+    expect(aggregate).toContain("if (!fresh) return pending as Promise<T>;");
+    expect(aggregate).toContain("await pending;");
+    expect(aggregate).toContain("return readAggregate(key, build, true);");
+    expect(aggregate).toContain("aggregatePayloads.set(key, { payload, cachedAt: Date.now() });");
+  });
+  it("serves the UI root index for the dashboard root and SPA routes", async () => {
+    const parent = await mkdtemp(join(tmpdir(), "zaip-dashboard-static-root-"));
+    const uiRoot = join(parent, "ui");
+    await mkdir(uiRoot);
+    await writeFile(join(uiRoot, "index.html"), "<title>ZAIP Dashboard</title>", "utf8");
+    try {
+      const app = createDashboardApp(workspaceRoot, "test-session", uiRoot);
+      for (const path of ["/", "/operations/overview"]) {
+        const response = await app.request(path);
+        expect(response.status, path).toBe(200);
+        await expect(response.text()).resolves.toContain("ZAIP Dashboard");
+      }
+    } finally {
+      await rm(parent, { recursive: true, force: true });
+    }
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-hono-security.test.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+
+describe("Dashboard HTTP query security", () => {
+  const app = new Hono().get("/", (context) => context.json(context.req.query()));
+
+  it("does not interpret a question mark inside a URL fragment as a query", async () => {
+    const response = await app.request("http://localhost/#?admin=true");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({});
+  });
+
+  it("preserves real query parameters but excludes fragment parameters", async () => {
+    const response = await app.request("http://localhost/?currency=BRL#?admin=true");
+    expect(await response.json()).toEqual({ currency: "BRL" });
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-http-contracts.ts

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { loadWorkspaceLayout, type WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+export const API_PREFIX = "/api/v2";
+export const WORK_PRIORITY_PATH = ".agents/dashboard/work-priority.json";
+export class V2WorkspaceRequiredError extends Error {
+  override readonly name = "V2WorkspaceRequiredError";
+}
+export async function requireV2Layout(filesystem: WorkspaceFileSystem): Promise<WorkspaceLayout> {
+  const layout = await loadWorkspaceLayout(filesystem);
+  if (layout.version === 1) {
+    throw new V2WorkspaceRequiredError("Dashboard API requires a modern ZAIP-AIOS workspace");
+  }
+  return layout;
+}
+export function headOrJson(
+  context: Context,
+  payload: unknown,
+  status: ContentfulStatusCode = 200,
+  cacheable = false,
+): Response {
+  if (cacheable) {
+    const etag = `"${createHash("sha256").update(JSON.stringify(payload)).digest("base64url")}"`;
+    context.header("ETag", etag);
+    context.header("Cache-Control", "private, no-cache");
+    if (context.req.header("if-none-match") === etag) return context.body(null, 304);
+  }
+  if (context.req.method === "HEAD") return context.body(null, status);
+  return context.json(payload, status);
+}