@ryanfw/prompt-orchestration-pipeline 0.10.0 → 0.12.0

package/src/ui/endpoints/job-endpoints.js

@@ -4,6 +4,8 @@
  * Exports:
  *  - handleJobList() -> { ok: true, data: [...] } | error envelope
  *  - handleJobDetail(jobId) -> { ok: true, data: {...} } | error envelope
+ *  - handleJobListRequest(req, res) -> HTTP response wrapper
+ *  - handleJobDetailRequest(req, res, jobId) -> HTTP response wrapper
  *  - getEndpointStats(jobListResponses, jobDetailResponses) -> stats object
  *
  * These functions return structured results (not HTTP responses) so the server
@@ -19,6 +21,7 @@ import {
   transformJobListForAPI,
 } from "../transformers/list-transformer.js";
 import * as configBridge from "../config-bridge.js";
+import { sendJson } from "../utils/http-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getJobPipelinePath } from "../../config/paths.js";
@@ -257,6 +260,65 @@ async function handleJobDetailById(jobId) {
   }
 }
 
+/**
+ * HTTP wrapper function for job list requests.
+ * Calls handleJobList() and sends the response using sendJson().
+ */
+export async function handleJobListRequest(req, res) {
+  console.info("[JobEndpoints] handleJobListRequest called");
+
+  try {
+    const result = await handleJobList();
+
+    if (result.ok) {
+      sendJson(res, 200, result);
+    } else {
+      // Map error codes to appropriate HTTP status codes
+      const statusCode = result.code === "fs_error" ? 500 : 400;
+      sendJson(res, statusCode, result);
+    }
+  } catch (err) {
+    console.error("handleJobListRequest unexpected error:", err);
+    sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}
+
+/**
+ * HTTP wrapper function for job detail requests.
+ * Calls handleJobDetail(jobId) and sends the response using sendJson().
+ */
+export async function handleJobDetailRequest(req, res, jobId) {
+  console.log(`[JobEndpoints] handleJobDetailRequest called for job: ${jobId}`);
+
+  try {
+    const result = await handleJobDetail(jobId);
+
+    if (result.ok) {
+      sendJson(res, 200, result);
+    } else {
+      // Map error codes to appropriate HTTP status codes
+      let statusCode = 400;
+      if (result.code === "job_not_found") {
+        statusCode = 404;
+      } else if (result.code === "fs_error") {
+        statusCode = 500;
+      }
+      sendJson(res, statusCode, result);
+    }
+  } catch (err) {
+    console.error("handleJobDetailRequest unexpected error:", err);
+    sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}
+
 /**
  * Compute endpoint statistics for test assertions.
  * jobListResponses/jobDetailResponses are arrays of response envelopes.

package/src/ui/endpoints/sse-endpoints.js

@@ -0,0 +1,223 @@
+/**
+ * SSE (Server-Sent Events) and state management endpoints
+ */
+
+import { sseRegistry } from "../sse.js";
+import { sendJson } from "../utils/http-utils.js";
+
+/**
+ * Decorate a change object with jobId and lifecycle information
+ */
+function decorateChangeWithJobId(change) {
+  if (!change || typeof change !== "object") return change;
+  const normalizedPath = String(change.path || "").replace(/\\/g, "/");
+  const match = normalizedPath.match(
+    /pipeline-data\/(current|complete|pending|rejected)\/([^/]+)/
+  );
+  if (!match) {
+    return change;
+  }
+  return {
+    ...change,
+    lifecycle: match[1],
+    jobId: match[2],
+  };
+}
+
+/**
+ * Prioritize job status changes from a list of changes
+ */
+function prioritizeJobStatusChange(changes = []) {
+  const normalized = changes.map((change) => decorateChangeWithJobId(change));
+  const statusChange = normalized.find(
+    (change) =>
+      typeof change?.path === "string" &&
+      /tasks-status\.json$/.test(change.path)
+  );
+  return statusChange || normalized[0] || null;
+}
+
+/**
+ * Broadcast state update to all SSE clients
+ *
+ * NOTE: Per plan, SSE should emit compact, incremental events rather than
+ * streaming full application state. Use /api/state for full snapshot
+ * retrieval on client bootstrap. This function will emit only the most
+ * recent change when available (type: "state:change") and fall back to a
+ * lightweight summary event if no recent change is present.
+ */
+function broadcastStateUpdate(currentState) {
+  try {
+    const recentChanges = (currentState && currentState.recentChanges) || [];
+    const latest = prioritizeJobStatusChange(recentChanges);
+    console.debug("[Server] Broadcasting state update:", {
+      latest,
+      currentState,
+    });
+    if (latest) {
+      // Emit only the most recent change as a compact, typed event
+      const eventData = { type: "state:change", data: latest };
+      console.debug("[Server] Broadcasting event:", eventData);
+      sseRegistry.broadcast(eventData);
+    } else {
+      // Fallback: emit a minimal summary so clients can observe a state "tick"
+      const eventData = {
+        type: "state:summary",
+        data: {
+          changeCount:
+            currentState && currentState.changeCount
+              ? currentState.changeCount
+              : 0,
+        },
+      };
+      console.debug("[Server] Broadcasting summary event:", eventData);
+      sseRegistry.broadcast(eventData);
+    }
+  } catch (err) {
+    // Defensive: if something unexpected happens, fall back to a lightweight notification
+    try {
+      console.error("[Server] Error in broadcastStateUpdate:", err);
+      sseRegistry.broadcast({
+        type: "state:summary",
+        data: {
+          changeCount:
+            currentState && currentState.changeCount
+              ? currentState.changeCount
+              : 0,
+        },
+      });
+    } catch (fallbackErr) {
+      // Log error to aid debugging; this should never happen unless sseRegistry.broadcast is broken
+      console.error(
+        "Failed to broadcast fallback state summary in broadcastStateUpdate:",
+        fallbackErr
+      );
+    }
+  }
+}
+
+/**
+ * Handle SSE events endpoint (/api/events)
+ */
+function handleSseEvents(req, res, searchParams) {
+  // Parse jobId from query parameters for filtering
+  const jobId = searchParams.get("jobId");
+
+  // Set SSE headers
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+    "Access-Control-Allow-Origin": "*",
+  });
+
+  // Flush headers immediately
+  res.flushHeaders();
+
+  // Initial full-state is no longer sent over the SSE stream.
+  // Clients should fetch the snapshot from GET /api/state during bootstrap
+  // and then rely on SSE incremental events (state:change/state:summary).
+  // Keep headers flushed; sseRegistry.addClient will optionally send an initial ping.
+  // (Previously sent full state here; removed to reduce SSE payloads.)
+
+  // Add to SSE registry with jobId metadata for filtering
+  sseRegistry.addClient(res, { jobId });
+
+  // Start heartbeat for this connection
+  const heartbeatInterval = setInterval(() => {
+    try {
+      res.write(
+        `event: heartbeat\ndata: ${JSON.stringify({ timestamp: Date.now() })}\n\n`
+      );
+    } catch (err) {
+      // Client disconnected, stop heartbeat
+      clearInterval(heartbeatInterval);
+    }
+  }, 30000);
+
+  // Remove client on disconnect
+  req.on("close", () => {
+    clearInterval(heartbeatInterval);
+    sseRegistry.removeClient(res);
+  });
+}
+
+/**
+ * Handle API state endpoint (/api/state)
+ */
+async function handleApiState(req, res) {
+  if (req.method !== "GET") {
+    sendJson(res, 200, {
+      success: false,
+      error: "Method not allowed",
+      allowed: ["GET"],
+    });
+    return;
+  }
+
+  // Prefer returning in-memory state when available (tests and runtime rely on state.getState()).
+  // If in-memory state is available, return it directly; otherwise fall back to
+  // building a filesystem-backed snapshot for client bootstrap.
+  try {
+    // Dynamically import state to avoid circular dependencies
+    const state = await import("../state.js");
+
+    try {
+      if (state && typeof state.getState === "function") {
+        const inMemory = state.getState();
+        if (inMemory) {
+          sendJson(res, 200, inMemory);
+          return;
+        }
+      }
+    } catch (innerErr) {
+      // If reading in-memory state throws for some reason, fall back to snapshot
+      console.warn("Warning: failed to retrieve in-memory state:", innerErr);
+    }
+
+    // Build a filesystem-backed snapshot for client bootstrap.
+    // Dynamically import the composer and dependencies to avoid circular import issues.
+    const [
+      { buildSnapshotFromFilesystem },
+      jobScannerModule,
+      jobReaderModule,
+      statusTransformerModule,
+      configBridgeModule,
+    ] = await Promise.all([
+      import("../state-snapshot.js"),
+      import("../job-scanner.js").catch(() => null),
+      import("../job-reader.js").catch(() => null),
+      import("../transformers/status-transformer.js").catch(() => null),
+      import("../config-bridge.js").catch(() => null),
+    ]);
+
+    const snapshot = await buildSnapshotFromFilesystem({
+      listAllJobs:
+        jobScannerModule && jobScannerModule.listAllJobs
+          ? jobScannerModule.listAllJobs
+          : undefined,
+      readJob:
+        jobReaderModule && jobReaderModule.readJob
+          ? jobReaderModule.readJob
+          : undefined,
+      transformMultipleJobs:
+        statusTransformerModule && statusTransformerModule.transformMultipleJobs
+          ? statusTransformerModule.transformMultipleJobs
+          : undefined,
+      now: () => new Date(),
+      paths: (configBridgeModule && configBridgeModule.PATHS) || undefined,
+    });
+
+    sendJson(res, 200, snapshot);
+  } catch (err) {
+    console.error("Failed to build /api/state snapshot:", err);
+    sendJson(res, 500, {
+      ok: false,
+      code: "snapshot_error",
+      message: "Failed to build state snapshot",
+      details: err && err.message ? err.message : String(err),
+    });
+  }
+}
+
+export { handleSseEvents, handleApiState, broadcastStateUpdate };

package/src/ui/endpoints/state-endpoint.js

@@ -0,0 +1,85 @@
+/**
+ * Handle GET /api/state endpoint
+ */
+import * as state from "../state.js";
+import { sendJson } from "../utils/http-utils.js";
+
+export async function handleApiState(req, res) {
+  if (req.method !== "GET") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        success: false,
+        error: "Method not allowed",
+        allowed: ["GET"],
+      })
+    );
+    return;
+  }
+
+  // Prefer returning in-memory state when available (tests and runtime rely on state.getState()).
+  // If in-memory state is available, return it directly; otherwise fall back to
+  // building a filesystem-backed snapshot for client bootstrap.
+  try {
+    try {
+      if (state && typeof state.getState === "function") {
+        const inMemory = state.getState();
+        if (inMemory) {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(inMemory));
+          return;
+        }
+      }
+    } catch (innerErr) {
+      // If reading in-memory state throws for some reason, fall back to snapshot
+      console.warn("Warning: failed to retrieve in-memory state:", innerErr);
+    }
+
+    // Build a filesystem-backed snapshot for client bootstrap.
+    // Dynamically import the composer and dependencies to avoid circular import issues.
+    const [
+      { buildSnapshotFromFilesystem },
+      jobScannerModule,
+      jobReaderModule,
+      statusTransformerModule,
+      configBridgeModule,
+    ] = await Promise.all([
+      import("../state-snapshot.js"),
+      import("../job-scanner.js").catch(() => null),
+      import("../job-reader.js").catch(() => null),
+      import("../transformers/status-transformer.js").catch(() => null),
+      import("../config-bridge.js").catch(() => null),
+    ]);
+
+    const snapshot = await buildSnapshotFromFilesystem({
+      listAllJobs:
+        jobScannerModule && jobScannerModule.listAllJobs
+          ? jobScannerModule.listAllJobs
+          : undefined,
+      readJob:
+        jobReaderModule && jobReaderModule.readJob
+          ? jobReaderModule.readJob
+          : undefined,
+      transformMultipleJobs:
+        statusTransformerModule && statusTransformerModule.transformMultipleJobs
+          ? statusTransformerModule.transformMultipleJobs
+          : undefined,
+      now: () => new Date(),
+      paths: (configBridgeModule && configBridgeModule.PATHS) || undefined,
+    });
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(snapshot));
+  } catch (err) {
+    console.error("Failed to build /api/state snapshot:", err);
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        ok: false,
+        code: "snapshot_error",
+        message: "Failed to build state snapshot",
+        details: err && err.message ? err.message : String(err),
+      })
+    );
+  }
+}