@ryanfw/prompt-orchestration-pipeline 0.0.1 → 0.4.0

package/src/ui/client/hooks/useJobListWithUpdates.js

@@ -0,0 +1,335 @@
+import { useState, useEffect, useRef } from "react";
+import { useJobList } from "./useJobList.js";
+import { sortJobs } from "../../transformers/list-transformer.js";
+
+/**
+ * useJobListWithUpdates
+ *
+ * - Uses useJobList to fetch initial data (or a snapshot)
+ * - Hydrates local state from base data, then listens for SSE incremental events
+ * - Applies SSE events idempotently via pure reducer functions
+ * - Maintains connectionStatus derived from EventSource.readyState
+ * - Queues events received before hydration completes and applies them after hydrate
+ *
+ * Note: SSE payloads (job:created, job:updated) match the canonical list item shape
+ * from /api/jobs to ensure consistent updates without page refresh.
+ */
+function applyJobEvent(prev = [], event) {
+  // prev: Array of jobs (treated immutably)
+  // event: { type: string, payload: object }
+  const list = Array.isArray(prev) ? prev.slice() : [];
+
+  if (!event || !event.type) return list;
+
+  const p = event.payload || {};
+  switch (event.type) {
+    case "job:created": {
+      if (!p.jobId) return list;
+      const idx = list.findIndex((j) => j.jobId === p.jobId);
+      if (idx === -1) {
+        // New job: add and sort
+        list.push(p);
+        return sortJobs(list);
+      } else {
+        // Merge with existing; if no effective change, return prev to avoid unnecessary updates
+        const merged = { ...list[idx], ...p };
+        try {
+          if (JSON.stringify(merged) === JSON.stringify(list[idx])) return prev;
+        } catch (e) {
+          // Fall back to returning merged result if JSON stringify fails
+        }
+        list[idx] = merged;
+        return sortJobs(list);
+      }
+    }
+
+    case "job:updated": {
+      if (!p.jobId) return list;
+      const idx = list.findIndex((j) => j.jobId === p.jobId);
+      if (idx === -1) {
+        // If we don't have it yet, add it
+        list.push(p);
+        return sortJobs(list);
+      } else {
+        const merged = { ...list[idx], ...p };
+        try {
+          if (JSON.stringify(merged) === JSON.stringify(list[idx])) return prev;
+        } catch (e) {
+          // ignore stringify errors
+        }
+        list[idx] = merged;
+        return sortJobs(list);
+      }
+    }
+
+    case "job:removed": {
+      if (!p.jobId) return list;
+      const filtered = list.filter((j) => j.jobId !== p.jobId);
+      // If nothing removed, return prev
+      try {
+        if (JSON.stringify(filtered) === JSON.stringify(prev)) return prev;
+      } catch (e) {}
+      return filtered;
+    }
+
+    case "status:changed": {
+      if (!p.jobId) return list;
+      const mapped = list.map((j) =>
+        j.jobId === p.jobId ? { ...j, status: p.status } : j
+      );
+      try {
+        if (JSON.stringify(mapped) === JSON.stringify(prev)) return prev;
+      } catch (e) {}
+      return mapped;
+    }
+
+    default:
+      return list;
+  }
+}
+
+export function useJobListWithUpdates() {
+  const base = useJobList();
+  const { loading, data, error, refetch } = base;
+
+  const [localData, setLocalData] = useState(data || null);
+  const [connectionStatus, setConnectionStatus] = useState("disconnected");
+  const esRef = useRef(null);
+  const reconnectTimer = useRef(null);
+  // Debounce timer for refetch triggered by seed uploads or state-level events
+  const refetchDebounceRef = useRef(null);
+  const REFETCH_DEBOUNCE_MS = 300;
+
+  // Hydration guard and event queue for events that arrive before hydration completes.
+  const hydratedRef = useRef(false);
+  const eventQueue = useRef([]);
+
+  // Keep localData in sync when base data changes (this is the hydration point).
+  useEffect(() => {
+    setLocalData(data || null);
+
+    if (data && Array.isArray(data)) {
+      // Compute hydrated base from incoming data, then apply any queued events deterministically
+      const base = Array.isArray(data) ? data.slice() : [];
+      if (eventQueue.current.length > 0) {
+        try {
+          const applied = eventQueue.current.reduce(
+            (acc, ev) => applyJobEvent(acc, ev),
+            base
+          );
+          // Debug: show applied array content for test troubleshooting
+          setLocalData(applied);
+        } catch (e) {
+          // eslint-disable-next-line no-console
+          console.error(
+            "[useJobListWithUpdates] failed applying queued events",
+            e
+          );
+          // Fallback: set base as localData
+          setLocalData(base);
+        }
+        eventQueue.current = [];
+        hydratedRef.current = true;
+      } else {
+        // No queued events: just hydrate to base
+        setLocalData(base);
+        hydratedRef.current = true;
+      }
+    } else {
+      hydratedRef.current = false;
+    }
+  }, [data]);
+
+  useEffect(() => {
+    // Only create one EventSource per mounted hook instance
+    if (esRef.current) {
+      return undefined;
+    }
+
+    // Helper to attach listeners to a given EventSource instance
+    const attachListeners = (es) => {
+      const onOpen = () => {
+        setConnectionStatus("connected");
+      };
+
+      const onError = () => {
+        // Derive state from readyState when possible
+        try {
+          const rs = esRef.current?.readyState;
+          if (rs === 0) {
+            // connecting
+            setConnectionStatus("disconnected");
+          } else if (rs === 1) {
+            setConnectionStatus("connected");
+          } else if (rs === 2) {
+            setConnectionStatus("disconnected");
+          } else {
+            setConnectionStatus("disconnected");
+          }
+        } catch (err) {
+          setConnectionStatus("disconnected");
+        }
+
+        // Attempt reconnect after 2s if closed
+        if (esRef.current && esRef.current.readyState === 2) {
+          if (reconnectTimer.current) clearTimeout(reconnectTimer.current);
+          reconnectTimer.current = setTimeout(() => {
+            try {
+              // Close existing reference if any
+              try {
+                esRef.current?.close();
+              } catch (e) {
+                // ignore
+              }
+
+              // Create a fresh EventSource and attach the same listeners so reconnect works
+              const newEs = new EventSource("/api/events");
+              newEs.addEventListener("open", onOpen);
+              newEs.addEventListener("job:updated", onJobUpdated);
+              newEs.addEventListener("job:created", onJobCreated);
+              newEs.addEventListener("job:removed", onJobRemoved);
+              newEs.addEventListener("status:changed", onStatusChanged);
+              newEs.addEventListener("error", onError);
+
+              esRef.current = newEs;
+            } catch (err) {
+              // ignore
+            }
+          }, 2000);
+        }
+      };
+
+      const handleIncomingEvent = (type, evt) => {
+        try {
+          const payload = evt && evt.data ? JSON.parse(evt.data) : null;
+          const eventObj = { type, payload };
+
+          if (!hydratedRef.current) {
+            // Queue events functionally (avoid mutating existing array in place)
+            eventQueue.current = (eventQueue.current || []).concat(eventObj);
+            return;
+          }
+
+          // Apply event using pure reducer. If reducer returns an unchanged value,
+          // return prev to avoid unnecessary re-renders.
+          setLocalData((prev) => {
+            const next = applyJobEvent(prev, eventObj);
+            try {
+              if (JSON.stringify(prev) === JSON.stringify(next)) {
+                return prev;
+              }
+            } catch (e) {
+              // If stringify fails, fall back to returning next
+            }
+            return next;
+          });
+        } catch (err) {
+          // Non-fatal: keep queue intact and continue
+          // Logging for visibility in dev; tests should mock console if asserting logs
+          // eslint-disable-next-line no-console
+          if (type === "job:updated") {
+            console.error("Failed to parse job update event:", err);
+          } else {
+            console.error("Failed to handle SSE event:", err);
+          }
+        }
+      };
+
+      const onJobUpdated = (evt) => handleIncomingEvent("job:updated", evt);
+      const onJobCreated = (evt) => handleIncomingEvent("job:created", evt);
+      const onJobRemoved = (evt) => handleIncomingEvent("job:removed", evt);
+      const onStatusChanged = (evt) =>
+        handleIncomingEvent("status:changed", evt);
+
+      const scheduleRefetch = () => {
+        if (refetchDebounceRef.current)
+          clearTimeout(refetchDebounceRef.current);
+        refetchDebounceRef.current = setTimeout(() => {
+          try {
+            if (typeof refetch === "function") {
+              refetch();
+            }
+          } catch (e) {
+            // ignore refetch failures
+          } finally {
+            refetchDebounceRef.current = null;
+          }
+        }, REFETCH_DEBOUNCE_MS);
+      };
+
+      const onSeedUploaded = (evt) => {
+        // Minimal parsing - we don't need payload for refetching
+        try {
+          // eslint-disable-next-line no-unused-vars
+          const payload = evt && evt.data ? JSON.parse(evt.data) : null;
+        } catch (e) {
+          // ignore parse errors
+        }
+        scheduleRefetch();
+      };
+
+      const onStateChange = (evt) => {
+        // Treat state-level changes as a hint to refetch the jobs list (debounced)
+        scheduleRefetch();
+      };
+
+      es.addEventListener("open", onOpen);
+      es.addEventListener("job:updated", onJobUpdated);
+      es.addEventListener("job:created", onJobCreated);
+      es.addEventListener("job:removed", onJobRemoved);
+      es.addEventListener("status:changed", onStatusChanged);
+      es.addEventListener("seed:uploaded", onSeedUploaded);
+      es.addEventListener("state:change", onStateChange);
+      es.addEventListener("state:summary", onStateChange);
+      es.addEventListener("error", onError);
+
+      // Set connection status from readyState when possible
+      if (es.readyState === 1) setConnectionStatus("connected");
+      else if (es.readyState === 0) setConnectionStatus("disconnected");
+
+      return () => {
+        try {
+          es.removeEventListener("open", onOpen);
+          es.removeEventListener("job:updated", onJobUpdated);
+          es.removeEventListener("job:created", onJobCreated);
+          es.removeEventListener("job:removed", onJobRemoved);
+          es.removeEventListener("status:changed", onStatusChanged);
+          es.removeEventListener("seed:uploaded", onSeedUploaded);
+          es.removeEventListener("state:change", onStateChange);
+          es.removeEventListener("state:summary", onStateChange);
+          es.removeEventListener("error", onError);
+          es.close();
+        } catch (err) {
+          // ignore
+        }
+        if (reconnectTimer.current) {
+          clearTimeout(reconnectTimer.current);
+          reconnectTimer.current = null;
+        }
+        esRef.current = null;
+      };
+    };
+
+    // Create EventSource on mount regardless of base snapshot presence
+    try {
+      const es = new EventSource("/api/events");
+      esRef.current = es;
+
+      // attach listeners and return the cleanup function
+      return attachListeners(es);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error("Failed to create SSE connection:", err);
+      setConnectionStatus("error");
+      return undefined;
+    }
+  }, []);
+
+  return {
+    loading,
+    data: localData,
+    error,
+    refetch,
+    connectionStatus,
+  };
+}

package/src/ui/client/hooks/useTicker.js

@@ -0,0 +1,26 @@
+import { useState, useEffect, useRef } from "react";
+
+/**
+ * Reactive ticker hook that provides updating timestamp
+ * @param {number} intervalMs - Update interval in milliseconds (default: 1000)
+ * @returns {number} Current timestamp that updates on interval
+ */
+export function useTicker(intervalMs = 1000) {
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    // Set up interval to update timestamp
+    const intervalId = setInterval(() => {
+      setNow(Date.now());
+    }, intervalMs);
+
+    // Cleanup interval on unmount
+    return () => {
+      clearInterval(intervalId);
+    };
+  }, [intervalMs]);
+
+  return now;
+}
+
+export default useTicker;

package/src/ui/client/index.css

@@ -0,0 +1,31 @@
+/* src/ui/client/index.css */
+@import "@radix-ui/themes/styles.css" layer(radix);
+@import "tailwindcss";
+
+/* Reset and base styles */
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  html {
+    font-family: system-ui, sans-serif;
+  }
+
+  body {
+    margin: 0;
+    line-height: inherit;
+  }
+}
+
+body {
+  font-family: "Inter", sans-serif;
+  line-height: 1.6;
+  min-height: 100vh;
+}
+
+.container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 2rem;
+}

package/src/ui/client/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap"
+      rel="stylesheet"
+    />
+    <title>Prompt Pipeline Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.jsx"></script>
+  </body>
+</html>

package/src/ui/client/main.jsx

@@ -0,0 +1,38 @@
+// import React from "react";
+// import ReactDOM from "react-dom/client";
+// import { Layout } from "../components/Layout.jsx";
+// import "../styles/index.css";
+
+// ReactDOM.createRoot(document.getElementById("root")).render(
+//   <React.StrictMode>
+//     <Layout />
+//   </React.StrictMode>
+// );
+
+import "./index.css"; // Tailwind + tokens + base
+
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import PromptPipelineDashboard from "@/pages/PromptPipelineDashboard.jsx";
+import PipelineDetail from "@/pages/PipelineDetail.jsx";
+import { Theme } from "@radix-ui/themes";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <Theme
+      accentColor="iris"
+      grayColor="gray"
+      panelBackground="solid"
+      scaling="100%"
+      radius="full"
+    >
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<PromptPipelineDashboard />} />
+          <Route path="/pipeline/:jobId" element={<PipelineDetail />} />
+        </Routes>
+      </BrowserRouter>
+    </Theme>
+  </React.StrictMode>
+);

package/src/ui/config-bridge.browser.js

@@ -0,0 +1,149 @@
+/**
+ * Browser-specific configuration bridge for UI helpers.
+ * Contains only browser-safe utilities (no Node APIs).
+ */
+
+/**
+ * Global constants and contracts for project data display system
+ * @namespace Constants
+ */
+export const Constants = {
+  /**
+   * Job ID validation regex
+   * @type {RegExp}
+   */
+  JOB_ID_REGEX: /^[A-Za-z0-9-_]+$/,
+
+  /**
+   * Valid task states
+   * @type {string[]}
+   */
+  TASK_STATES: ["pending", "running", "done", "failed"],
+
+  /**
+   * Valid job locations
+   * @type {string[]}
+   */
+  JOB_LOCATIONS: ["current", "complete"],
+
+  /**
+   * Status sort order (descending priority)
+   * @type {string[]}
+   */
+  STATUS_ORDER: ["running", "failed", "pending", "complete"],
+
+  /**
+   * File size limits for reading
+   * @type {Object}
+   */
+  FILE_LIMITS: {
+    MAX_FILE_SIZE: 5 * 1024 * 1024, // 5MB
+  },
+
+  /**
+   * Retry configuration for atomic reads
+   * @type {Object}
+   */
+  RETRY_CONFIG: {
+    MAX_ATTEMPTS: 3,
+    DELAY_MS: 1000,
+  },
+
+  /**
+   * SSE debounce configuration
+   * @type {Object}
+   */
+  SSE_CONFIG: {
+    DEBOUNCE_MS: 200,
+  },
+
+  /**
+   * Error codes for structured error responses
+   * @type {Object}
+   */
+  ERROR_CODES: {
+    NOT_FOUND: "not_found",
+    INVALID_JSON: "invalid_json",
+    FS_ERROR: "fs_error",
+    JOB_NOT_FOUND: "job_not_found",
+    BAD_REQUEST: "bad_request",
+  },
+};
+
+/**
+ * Validates a job ID against the global contract
+ * @param {string} jobId - Job ID to validate
+ * @returns {boolean} True if valid
+ */
+export function validateJobId(jobId) {
+  return Constants.JOB_ID_REGEX.test(jobId);
+}
+
+/**
+ * Validates a task state against the global contract
+ * @param {string} state - Task state to validate
+ * @returns {boolean} True if valid
+ */
+export function validateTaskState(state) {
+  return Constants.TASK_STATES.includes(state);
+}
+
+/**
+ * Gets the status sort priority for a job status
+ * @param {string} status - Job status
+ * @returns {number} Sort priority (lower number = higher priority)
+ */
+export function getStatusPriority(status) {
+  const index = Constants.STATUS_ORDER.indexOf(status);
+  return index === -1 ? Constants.STATUS_ORDER.length : index;
+}
+
+/**
+ * Determines job status based on task states
+ * @param {Object} tasks - Tasks object from tasks-status.json
+ * @returns {string} Job status
+ */
+export function determineJobStatus(tasks = {}) {
+  const taskEntries = Object.entries(tasks);
+
+  if (taskEntries.length === 0) {
+    return "pending";
+  }
+
+  const taskStates = taskEntries.map(([_, task]) => task.state);
+
+  if (taskStates.includes("failed")) {
+    return "failed";
+  }
+
+  if (taskStates.includes("running")) {
+    return "running";
+  }
+
+  if (taskStates.every((state) => state === "done")) {
+    return "complete";
+  }
+
+  return "pending";
+}
+
+/**
+ * Creates a structured error response
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {string} [path] - Optional file path
+ * @returns {Object} Structured error object
+ */
+export function createErrorResponse(code, message, path = null) {
+  const error = {
+    ok: false,
+    code,
+    message,
+  };
+
+  if (path) {
+    error.path = path;
+  }
+
+  return error;
+}