@ryanfw/prompt-orchestration-pipeline 0.11.0 → 0.13.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/pipeline-analysis-endpoint.js

@@ -0,0 +1,246 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { streamSSE } from "../lib/sse.js";
+import { acquireLock, releaseLock } from "../lib/analysis-lock.js";
+import { getPipelineConfig } from "../../core/config.js";
+import { analyzeTask } from "../../task-analysis/index.js";
+import { writeAnalysisFile } from "../../task-analysis/enrichers/analysis-writer.js";
+import { deduceArtifactSchema } from "../../task-analysis/enrichers/schema-deducer.js";
+import { writeSchemaFiles } from "../../task-analysis/enrichers/schema-writer.js";
+
+/**
+ * Handle pipeline analysis endpoint.
+ * Analyzes all tasks in a pipeline and deduces schemas for artifacts.
+ *
+ * @param {object} req - Express request object
+ * @param {object} res - Express response object
+ */
+export async function handlePipelineAnalysis(req, res) {
+  const slug = req.params.slug;
+  const startTime = Date.now();
+
+  // Validate slug format
+  if (!slug || typeof slug !== "string") {
+    return res.status(400).json({
+      ok: false,
+      code: "invalid_slug",
+      message: "Missing or invalid slug parameter",
+    });
+  }
+
+  if (!/^[A-Za-z0-9_-]+$/.test(slug)) {
+    return res.status(400).json({
+      ok: false,
+      code: "invalid_slug",
+      message:
+        "Invalid slug format: only alphanumeric, hyphens, and underscores allowed",
+    });
+  }
+
+  // Try to acquire lock
+  const lockResult = acquireLock(slug);
+  if (!lockResult.acquired) {
+    return res.status(409).json({
+      ok: false,
+      code: "analysis_locked",
+      heldBy: lockResult.heldBy,
+    });
+  }
+
+  // Create SSE stream
+  const stream = streamSSE(res);
+  let lockReleased = false;
+
+  const releaseLockSafely = () => {
+    if (!lockReleased) {
+      releaseLock(slug);
+      lockReleased = true;
+    }
+  };
+
+  // Handle client disconnect
+  req.on("close", () => {
+    console.log(`[PipelineAnalysis] Client disconnected for ${slug}`);
+    releaseLockSafely();
+  });
+
+  try {
+    // Get pipeline configuration
+    let pipelineConfig;
+    try {
+      pipelineConfig = getPipelineConfig(slug);
+    } catch (error) {
+      stream.send("error", {
+        message: `Pipeline '${slug}' not found in registry`,
+      });
+      stream.end();
+      releaseLockSafely();
+      return;
+    }
+
+    const pipelineDir = path.dirname(pipelineConfig.pipelineJsonPath);
+
+    // Read pipeline.json
+    let pipelineData;
+    try {
+      const contents = await fs.readFile(
+        pipelineConfig.pipelineJsonPath,
+        "utf8"
+      );
+      pipelineData = JSON.parse(contents);
+    } catch (error) {
+      stream.send("error", {
+        message: `Failed to read pipeline.json: ${error.message}`,
+      });
+      stream.end();
+      releaseLockSafely();
+      return;
+    }
+
+    if (!Array.isArray(pipelineData.tasks)) {
+      stream.send("error", {
+        message: "Invalid pipeline.json: tasks array not found",
+      });
+      stream.end();
+      releaseLockSafely();
+      return;
+    }
+
+    const tasks = pipelineData.tasks;
+    const totalTasks = tasks.length;
+
+    // Pre-analyze all tasks to count total artifacts (only JSON files need schema deduction)
+    const taskAnalyses = [];
+    let totalArtifacts = 0;
+
+    for (const taskId of tasks) {
+      const taskFilePath = path.join(pipelineDir, "tasks", `${taskId}.js`);
+      try {
+        const taskCode = await fs.readFile(taskFilePath, "utf8");
+        const analysis = analyzeTask(taskCode, taskFilePath);
+        taskAnalyses.push({ taskId, taskCode, analysis });
+        // Only count JSON artifacts for schema deduction
+        totalArtifacts += analysis.artifacts.writes.filter((a) =>
+          a.fileName.endsWith(".json")
+        ).length;
+      } catch (error) {
+        stream.send("error", {
+          message: `Failed to analyze task '${taskId}': ${error.message}`,
+          taskId,
+        });
+        stream.end();
+        releaseLockSafely();
+        return;
+      }
+    }
+
+    // Send started event
+    stream.send("started", {
+      pipelineSlug: slug,
+      totalTasks,
+      totalArtifacts,
+    });
+
+    let completedTasks = 0;
+    let completedArtifacts = 0;
+
+    // Process each task
+    for (let taskIndex = 0; taskIndex < taskAnalyses.length; taskIndex++) {
+      const { taskId, taskCode, analysis } = taskAnalyses[taskIndex];
+
+      stream.send("task:start", {
+        taskId,
+        taskIndex,
+        totalTasks,
+      });
+
+      // Write analysis file
+      try {
+        await writeAnalysisFile(pipelineDir, taskId, analysis);
+      } catch (error) {
+        stream.send("error", {
+          message: `Failed to write analysis for task '${taskId}': ${error.message}`,
+          taskId,
+        });
+        stream.end();
+        releaseLockSafely();
+        return;
+      }
+
+      // Process each artifact write
+      const artifacts = analysis.artifacts.writes;
+      let jsonArtifactIndex = 0;
+
+      for (
+        let artifactIndex = 0;
+        artifactIndex < artifacts.length;
+        artifactIndex++
+      ) {
+        const artifact = artifacts[artifactIndex];
+
+        // Skip non-JSON artifacts (only JSON files need schema deduction)
+        if (!artifact.fileName.endsWith(".json")) {
+          continue;
+        }
+
+        stream.send("artifact:start", {
+          taskId,
+          artifactName: artifact.fileName,
+          artifactIndex: jsonArtifactIndex,
+          totalArtifacts,
+        });
+
+        try {
+          const deducedSchema = await deduceArtifactSchema(taskCode, artifact);
+          await writeSchemaFiles(pipelineDir, artifact.fileName, deducedSchema);
+        } catch (error) {
+          stream.send("error", {
+            message: `Failed to deduce schema for artifact '${artifact.fileName}': ${error.message}`,
+            taskId,
+            artifactName: artifact.fileName,
+          });
+          stream.end();
+          releaseLockSafely();
+          return;
+        }
+
+        stream.send("artifact:complete", {
+          taskId,
+          artifactName: artifact.fileName,
+          artifactIndex: jsonArtifactIndex,
+          totalArtifacts,
+        });
+
+        completedArtifacts++;
+        jsonArtifactIndex++;
+      }
+
+      stream.send("task:complete", {
+        taskId,
+        taskIndex,
+        totalTasks,
+      });
+
+      completedTasks++;
+    }
+
+    // Send complete event
+    const durationMs = Date.now() - startTime;
+    stream.send("complete", {
+      pipelineSlug: slug,
+      tasksAnalyzed: completedTasks,
+      artifactsProcessed: completedArtifacts,
+      durationMs,
+    });
+
+    stream.end();
+    releaseLockSafely();
+  } catch (error) {
+    console.error(`[PipelineAnalysis] Unexpected error:`, error);
+    stream.send("error", {
+      message: `Unexpected error: ${error.message}`,
+    });
+    stream.end();
+    releaseLockSafely();
+  }
+}

package/src/ui/endpoints/pipeline-type-detail-endpoint.js

@@ -0,0 +1,181 @@
+/**
+ * Pipeline type detail endpoint (logic-only)
+ *
+ * Exports:
+ *  - handlePipelineTypeDetail(slug) -> Core logic function
+ *  - handlePipelineTypeDetailRequest(req, res) -> HTTP response wrapper
+ *
+ * This function returns a read-only pipeline definition with tasks ordered
+ * as specified in pipeline.json for rendering a static DAG visualization.
+ */
+
+import { getPipelineConfig, getConfig } from "../../core/config.js";
+import { sendJson } from "../utils/http-utils.js";
+import * as configBridge from "../config-bridge.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Return pipeline type detail suitable for the API.
+ *
+ * Behavior:
+ *  - Use getPipelineConfig(slug) to resolve pipeline.json path
+ *  - Read and parse pipeline.json from the resolved path
+ *  - Validate that parsed data contains a tasks array
+ *  - Return tasks as { id, title, status: 'definition' } in order
+ *  - Handle all error cases with explicit error responses
+ *
+ * @param {string} slug - Pipeline slug identifier
+ * @returns {Object} Response envelope { ok: true, data } or error envelope
+ */
+export async function handlePipelineTypeDetail(slug) {
+  console.log(`[PipelineTypeDetailEndpoint] GET /api/pipelines/${slug} called`);
+
+  // Validate slug parameter
+  if (!slug || typeof slug !== "string") {
+    return configBridge.createErrorResponse(
+      configBridge.Constants.ERROR_CODES.BAD_REQUEST,
+      "Invalid slug parameter"
+    );
+  }
+
+  // Enforce safe characters in slug to prevent path traversal and similar issues
+  const slugIsValid = /^[A-Za-z0-9_-]+$/.test(slug);
+  if (!slugIsValid) {
+    return configBridge.createErrorResponse(
+      configBridge.Constants.ERROR_CODES.BAD_REQUEST,
+      "Invalid slug parameter: only letters, numbers, hyphens, and underscores are allowed"
+    );
+  }
+  try {
+    // Resolve pipeline configuration using existing config system
+    let pipelineConfig;
+    try {
+      pipelineConfig = getPipelineConfig(slug);
+    } catch (error) {
+      return configBridge.createErrorResponse(
+        configBridge.Constants.ERROR_CODES.NOT_FOUND,
+        `Pipeline '${slug}' not found in registry`
+      );
+    }
+
+    const pipelineJsonPath = pipelineConfig.pipelineJsonPath;
+
+    // Check if pipeline.json exists
+    try {
+      await fs.access(pipelineJsonPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return configBridge.createErrorResponse(
+          configBridge.Constants.ERROR_CODES.NOT_FOUND,
+          `pipeline.json not found for pipeline '${slug}'`,
+          pipelineJsonPath
+        );
+      }
+      throw error;
+    }
+
+    // Read and parse pipeline.json
+    let pipelineData;
+    try {
+      const contents = await fs.readFile(pipelineJsonPath, "utf8");
+      pipelineData = JSON.parse(contents);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return configBridge.createErrorResponse(
+          configBridge.Constants.ERROR_CODES.INVALID_JSON,
+          "Invalid JSON in pipeline.json",
+          pipelineJsonPath
+        );
+      }
+      throw error;
+    }
+
+    // Validate pipeline structure
+    if (
+      !pipelineData ||
+      typeof pipelineData !== "object" ||
+      !Array.isArray(pipelineData.tasks)
+    ) {
+      return configBridge.createErrorResponse(
+        configBridge.Constants.ERROR_CODES.INVALID_JSON,
+        "Invalid pipeline.json format: expected 'tasks' array",
+        pipelineJsonPath
+      );
+    }
+
+    // Transform tasks to API format
+    const tasks = pipelineData.tasks.map((taskId, index) => {
+      if (typeof taskId !== "string" || !taskId.trim()) {
+        throw new Error(`Invalid task ID at index ${index}: ${taskId}`);
+      }
+
+      return {
+        id: taskId,
+        title: taskId.charAt(0).toUpperCase() + taskId.slice(1),
+        status: "definition",
+      };
+    });
+
+    // Get pipeline metadata from config for name/description
+    const config = getConfig();
+    const pipelineMetadata = config.pipelines?.[slug] || {};
+
+    return {
+      ok: true,
+      data: {
+        slug,
+        name: pipelineMetadata.name || slug,
+        description: pipelineMetadata.description || "",
+        tasks,
+      },
+    };
+  } catch (err) {
+    console.error("handlePipelineTypeDetail error:", err);
+    return configBridge.createErrorResponse(
+      configBridge.Constants.ERROR_CODES.FS_ERROR,
+      "Failed to read pipeline configuration"
+    );
+  }
+}
+
+/**
+ * HTTP wrapper function for pipeline type detail requests.
+ * Calls handlePipelineTypeDetail(slug) and sends the response using sendJson().
+ *
+ * @param {http.IncomingMessage} req - HTTP request object
+ * @param {http.ServerResponse} res - HTTP response object
+ */
+export async function handlePipelineTypeDetailRequest(req, res) {
+  console.info(
+    "[PipelineTypeDetailEndpoint] handlePipelineTypeDetailRequest called"
+  );
+
+  try {
+    const slug = req.params.slug;
+    const result = await handlePipelineTypeDetail(slug);
+
+    if (result.ok) {
+      sendJson(res, 200, result);
+    } else {
+      // Map error codes to appropriate HTTP status codes
+      const statusCode =
+        result.code === configBridge.Constants.ERROR_CODES.NOT_FOUND
+          ? 404
+          : result.code === configBridge.Constants.ERROR_CODES.BAD_REQUEST
+            ? 400
+            : result.code === configBridge.Constants.ERROR_CODES.INVALID_JSON ||
+                result.code === configBridge.Constants.ERROR_CODES.FS_ERROR
+              ? 500
+              : 500;
+      sendJson(res, statusCode, result);
+    }
+  } catch (err) {
+    console.error("handlePipelineTypeDetailRequest unexpected error:", err);
+    sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}

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

@@ -0,0 +1,133 @@
+/**
+ * Pipelines endpoint (logic-only)
+ *
+ * Exports:
+ *  - handlePipelinesRequest() -> HTTP response wrapper
+ *
+ * This function returns structured pipeline metadata from the registry
+ * so the frontend can display available pipelines.
+ */
+
+import { getConfig } from "../../core/config.js";
+import { sendJson } from "../utils/http-utils.js";
+import * as configBridge from "../config-bridge.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Return pipeline metadata suitable for the API.
+ *
+ * Behavior:
+ *  - Read pipeline registry from config system
+ *  - Return slug, name, description for each pipeline
+ *  - Handle empty registry (return 200 with empty array)
+ *  - Handle malformed JSON (return 500 with specific error)
+ *  - Handle missing registry file (return 200 with empty array)
+ */
+export async function handlePipelinesRequest() {
+  console.log("[PipelinesEndpoint] GET /api/pipelines called");
+
+  try {
+    const config = getConfig();
+    const rootDir = config.paths?.root;
+
+    if (!rootDir) {
+      return configBridge.createErrorResponse(
+        configBridge.Constants.ERROR_CODES.BAD_REQUEST,
+        "PO_ROOT not configured"
+      );
+    }
+
+    const registryPath = path.join(rootDir, "pipeline-config", "registry.json");
+
+    // Check if registry file exists
+    try {
+      await fs.access(registryPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        // Missing registry file - return empty array as specified
+        return { ok: true, data: { pipelines: [] } };
+      }
+      throw error;
+    }
+
+    // Read and parse registry file
+    let registryData;
+    try {
+      const contents = await fs.readFile(registryPath, "utf8");
+      registryData = JSON.parse(contents);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return configBridge.createErrorResponse(
+          configBridge.Constants.ERROR_CODES.INVALID_JSON,
+          "Invalid JSON in pipeline registry",
+          registryPath
+        );
+      }
+      throw error;
+    }
+
+    // Validate registry structure
+    if (
+      !registryData ||
+      typeof registryData !== "object" ||
+      !registryData.pipelines ||
+      typeof registryData.pipelines !== "object"
+    ) {
+      return configBridge.createErrorResponse(
+        configBridge.Constants.ERROR_CODES.INVALID_JSON,
+        "Invalid pipeline registry format: expected 'pipelines' object",
+        registryPath
+      );
+    }
+
+    // Transform pipeline entries to API format
+    const pipelines = [];
+    for (const [slug, entry] of Object.entries(registryData.pipelines)) {
+      pipelines.push({
+        slug,
+        name: entry?.name || slug,
+        description: entry?.description || "",
+      });
+    }
+
+    return { ok: true, data: { pipelines } };
+  } catch (err) {
+    console.error("handlePipelinesRequest error:", err);
+    return configBridge.createErrorResponse(
+      configBridge.Constants.ERROR_CODES.FS_ERROR,
+      "Failed to read pipeline registry"
+    );
+  }
+}
+
+/**
+ * HTTP wrapper function for pipelines requests.
+ * Calls handlePipelinesRequest() and sends the response using sendJson().
+ */
+export async function handlePipelinesHttpRequest(req, res) {
+  console.info("[PipelinesEndpoint] handlePipelinesHttpRequest called");
+
+  try {
+    const result = await handlePipelinesRequest();
+
+    if (result.ok) {
+      sendJson(res, 200, result);
+    } else {
+      // Map error codes to appropriate HTTP status codes
+      const statusCode =
+        result.code === configBridge.Constants.ERROR_CODES.INVALID_JSON ||
+        result.code === configBridge.Constants.ERROR_CODES.FS_ERROR
+          ? 500
+          : 400;
+      sendJson(res, statusCode, result);
+    }
+  } catch (err) {
+    console.error("handlePipelinesHttpRequest unexpected error:", err);
+    sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}