@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/dashboard/packages/local-runtime/src/server-operations-routes.ts

@@ -0,0 +1,364 @@
+import { buildOperationsProjection } from "@zaip-ai/dashboard-operations/server";
+import { LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
+import type { Hono } from "hono";
+import {
+  type BoardClassification,
+  boardFilters,
+  boardPage,
+  boardStage,
+  classificationPage,
+} from "./server-board.js";
+import { registerDailyReadModelRoute } from "./server-daily-read-models-route.js";
+import {
+  API_PREFIX,
+  headOrJson,
+  requireV2Layout,
+  V2WorkspaceRequiredError,
+  WORK_PRIORITY_PATH,
+} from "./server-http-contracts.js";
+import {
+  changeEntityPageRows,
+  decisionEntityPageRows,
+  filterLifecyclePageRows,
+  operationsPageFilters,
+} from "./server-operations-pages.js";
+import { registerOperationsRunsRoute } from "./server-operations-runs-route.js";
+import { projectionPeriodFilter } from "./server-period.js";
+import {
+  buildCanonicalOperationsProjection,
+  knownWorkIds,
+  normalizeWorkPriority,
+  readWorkPriority,
+} from "./server-projections.js";
+import { buildFirstFoldQuickProjection } from "./server-read-projections.js";
+import type { DashboardRouteContext } from "./server-route-context.js";
+import { SqliteReadModelFileSystem, sqliteViewMetadata } from "./sqlite-read-model.js";
+export function registerOperationsRoutes(app: Hono, dependencies: DashboardRouteContext) {
+  const {
+    filesystem,
+    canonicalFilesystem,
+    isSqliteSnapshot,
+    readLayout,
+    readSnapshot,
+    readAggregate,
+    clearSnapshotCache,
+  } = dependencies;
+  app.on(["GET", "HEAD"], `${API_PREFIX}/operations`, async (context) => {
+    try {
+      const requestStartedAt = performance.now();
+      const scope = context.req.query("scope");
+      if (
+        scope !== "overview" &&
+        scope !== "quick" &&
+        scope !== "detail" &&
+        scope !== "board" &&
+        scope !== "traceability" &&
+        scope !== "classification"
+      )
+        return headOrJson(context, (await readSnapshot(context)).operations);
+      const layout = await readLayout();
+      const layoutMs = performance.now() - requestStartedAt;
+      const { from, to } = projectionPeriodFilter(context);
+      if (scope === "board" || scope === "traceability") {
+        const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
+        const limit = Math.min(
+          50,
+          Math.max(1, Number.parseInt(context.req.query("limit") ?? "10", 10) || 10),
+        );
+        const board = await readAggregate(
+          `operations:board:${from ?? ""}:${to ?? ""}`,
+          async () => {
+            const projection = await buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              { includeBoardTasks: true },
+            );
+            return {
+              projection,
+              priority: await readWorkPriority(canonicalFilesystem, knownWorkIds(projection)),
+            };
+          },
+        );
+        // Traceability is an identity index, not an executable Kanban column.
+        // Drafts remain discoverable without changing their canonical state.
+        if (scope === "traceability") {
+          const tasks = board.projection.tasks.toSorted(
+            (a, b) => b.created_at.localeCompare(a.created_at) || b.id.localeCompare(a.id),
+          );
+          return headOrJson(
+            context,
+            {
+              tasks: tasks.slice(offset, offset + limit),
+              total: tasks.length,
+              offset,
+              limit,
+            },
+            200,
+            true,
+          );
+        }
+        const stage = boardStage(context.req.query("stage"));
+        const filters = boardFilters(context);
+        const pageKey = JSON.stringify({ from, to, stage, offset, limit, ...filters });
+        const page = await readAggregate(`operations:board-page:${pageKey}`, async () =>
+          boardPage(board.projection, stage, offset, limit, board.priority.item_ids, filters),
+        );
+        return headOrJson(context, page, 200, true);
+      }
+      if (scope === "classification") {
+        const kind = context.req.query("kind");
+        const classification = context.req.query("classification");
+        if (kind !== "task" && kind !== "spec" && kind !== "prd")
+          return headOrJson(context, { error: "A valid work kind is required" }, 400);
+        if (
+          !["lite", "standard", "critical", "empty", "structured", "rework"].includes(
+            classification ?? "",
+          )
+        )
+          return headOrJson(context, { error: "A valid classification is required" }, 400);
+        const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
+        const limit = Math.min(
+          50,
+          Math.max(1, Number.parseInt(context.req.query("limit") ?? "50", 10) || 50),
+        );
+        const projection = await readAggregate(
+          `operations:classification:${from ?? ""}:${to ?? ""}`,
+          () =>
+            buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              { includeBoardTasks: true },
+            ),
+        );
+        return headOrJson(
+          context,
+          classificationPage(
+            projection,
+            kind,
+            classification as BoardClassification,
+            offset,
+            limit,
+          ),
+          200,
+          true,
+        );
+      }
+      if (scope === "quick") {
+        const projectionStartedAt = performance.now();
+        const quick = await readAggregate(
+          `operations:quick:${from ?? ""}:${to ?? ""}`,
+          () =>
+            buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              {
+                includeTopTasks: from === null && to === null,
+                includeExtended: from === null && to === null,
+              },
+            ),
+          context.req.query("fresh") === "1",
+        );
+        if (
+          process.env.ZAIP_DASHBOARD_PROFILE_FIRST_FOLD === "1" &&
+          filesystem instanceof SqliteReadModelFileSystem
+        ) {
+          const timings = filesystem.firstFoldViewportProfile();
+          context.header(
+            "Server-Timing",
+            [
+              `layout;dur=${Math.round(layoutMs * 10) / 10}`,
+              `projection;dur=${Math.round((performance.now() - projectionStartedAt) * 10) / 10}`,
+              ...Object.entries(timings).map(([name, duration]) => `${name};dur=${duration}`),
+            ].join(", "),
+          );
+        }
+        return headOrJson(context, quick, 200, true);
+      }
+      const projection =
+        filesystem instanceof SqliteReadModelFileSystem
+          ? await buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              {
+                includeBoardTasks: scope === "detail",
+                includeExtended: scope === "detail" || scope === "overview",
+                includePeriods: scope === "detail" || scope === "overview",
+              },
+            )
+          : await buildCanonicalOperationsProjection(
+              filesystem,
+              layout,
+              { from, to },
+              scope === "overview",
+            );
+      return headOrJson(context, projection, 200, scope === "overview");
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(
+        context,
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      );
+    }
+  });
+  registerOperationsRunsRoute(app, filesystem, readAggregate, headOrJson);
+  // Explicit SQL read-model API for the comparison dashboard. It never falls
+  // back to filesystem pagination, making first-fold/entity query plans
+  // inspectable while preserving the established Operations contracts.
+  app.on(["GET", "HEAD"], `${API_PREFIX}/sqlite-read-models`, async (context) => {
+    if (!(filesystem instanceof SqliteReadModelFileSystem))
+      return headOrJson(context, { error: "SQLite read model is not active" }, 409);
+    const kind = context.req.query("kind");
+    const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
+    const limit = Math.min(
+      200,
+      Math.max(1, Number.parseInt(context.req.query("limit") ?? "20", 10) || 20),
+    );
+    if (kind === "overview") {
+      const period = context.req.query("period");
+      if (period !== "day" && period !== "month" && period !== "year")
+        return headOrJson(context, { error: "Unsupported SQLite overview period" }, 400);
+      return headOrJson(context, filesystem.overviewPage(period, offset, limit), 200, true);
+    }
+    if (kind !== "task" && kind !== "spec" && kind !== "prd")
+      return headOrJson(context, { error: "Unsupported SQLite read model" }, 400);
+    const { from, to } = projectionPeriodFilter(context);
+    const filters = operationsPageFilters(context);
+    return headOrJson(
+      context,
+      filesystem.summaryPage(
+        kind,
+        { from, to, ...filters },
+        offset,
+        limit,
+        context.req.query("cursor") ?? null,
+      ),
+      200,
+      true,
+    );
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/sqlite-views`, async (context) => {
+    if (!(filesystem instanceof SqliteReadModelFileSystem))
+      return headOrJson(context, { error: "SQLite read model is not active" }, 409);
+    const view = context.req.query("view");
+    if (view === undefined || !Object.hasOwn(sqliteViewMetadata, view))
+      return headOrJson(context, { error: "Unsupported SQLite view" }, 400);
+    const parsed = Number.parseInt(context.req.query("limit") ?? "", 10);
+    const defaultLimit = view.includes("agent_invocations")
+      ? 100
+      : view === "first_fold_top_tasks"
+        ? 5
+        : 50;
+    const limit = Math.min(200, Math.max(1, Number.isFinite(parsed) ? parsed : defaultLimit));
+    const { from, to } = projectionPeriodFilter(context);
+    const optional = (name: string) => {
+      const value = context.req.query(name);
+      return value === undefined ? {} : { [name]: value };
+    };
+    const workListKind = context.req.query("kind");
+    if (
+      view === "operations_work_list" &&
+      workListKind !== undefined &&
+      !["all", "task", "standalone-task", "prd", "spec"].includes(workListKind)
+    )
+      return headOrJson(context, { error: "Unsupported Operations work-list kind" }, 400);
+    return headOrJson(
+      context,
+      filesystem.viewPage(view as keyof typeof sqliteViewMetadata, {
+        from,
+        to,
+        ...optional("query"),
+        ...optional("status"),
+        ...optional("risk"),
+        ...optional("provider"),
+        ...optional("model"),
+        ...optional("agent"),
+        ...optional("phase"),
+        ...optional("origin"),
+        ...optional("workType"),
+        ...optional("priority"),
+        ...(workListKind === undefined
+          ? {}
+          : { kind: workListKind as "all" | "task" | "standalone-task" | "prd" | "spec" }),
+        offset: Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0),
+        limit,
+      }),
+      200,
+      true,
+    );
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/work-priority`, async (context) => {
+    const layout = await requireV2Layout(canonicalFilesystem);
+    const operations = await buildOperationsProjection(canonicalFilesystem, layout, {
+      from: null,
+      to: null,
+    });
+    return headOrJson(
+      context,
+      await readWorkPriority(canonicalFilesystem, knownWorkIds(operations)),
+    );
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/operations/entities`, async (context) => {
+    const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
+    const limit = Math.min(
+      500,
+      Math.max(1, Number.parseInt(context.req.query("limit") ?? "100", 10) || 100),
+    );
+    const kind = context.req.query("kind");
+    if (kind !== "changes" && kind !== "decisions")
+      return headOrJson(context, { error: "Unsupported Operations entity page" }, 400);
+    const { from, to } = projectionPeriodFilter(context);
+    const pageFilters = operationsPageFilters(context);
+    const payload = await readAggregate(
+      `operations:entities:${kind}:${from ?? ""}:${to ?? ""}:${offset}:${limit}:${pageFilters.query}:${pageFilters.status}:${pageFilters.risk}`,
+      async () => {
+        const layout = await readLayout();
+        const entities = await new LifecycleManifestStore(filesystem).readEntities(
+          kind === "changes" ? "change" : "decision",
+        );
+        const entityRows =
+          kind === "changes"
+            ? changeEntityPageRows(entities, layout, from, to)
+            : decisionEntityPageRows(entities, layout, from, to);
+        const rows = filterLifecyclePageRows(entityRows, pageFilters);
+        return {
+          data_source: "lifecycle_manifest_shards",
+          kind,
+          offset,
+          limit,
+          total: rows.length,
+          rows: rows.slice(offset, offset + limit),
+        };
+      },
+    );
+    return headOrJson(context, payload, 200, true);
+  });
+  registerDailyReadModelRoute(app, filesystem, readAggregate, headOrJson);
+  app.put(`${API_PREFIX}/work-priority`, async (context) => {
+    const candidate = normalizeWorkPriority(await context.req.json());
+    // Priority is canonical queue configuration, never snapshot content.
+    // Keep every other settings mutation blocked in snapshot-serving mode.
+    await canonicalFilesystem.writeTextAtomic(
+      WORK_PRIORITY_PATH,
+      `${JSON.stringify(candidate, null, 2)}\n`,
+    );
+    clearSnapshotCache();
+    return context.json(candidate);
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/snapshot`, async (context) => {
+    try {
+      return headOrJson(context, await readSnapshot(context));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(
+        context,
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      );
+    }
+  });
+}