@ryanfw/prompt-orchestration-pipeline 0.12.0 → 0.13.0

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",
+    });
+  }
+}

package/src/ui/endpoints/schema-file-endpoint.js

@@ -0,0 +1,105 @@
+/**
+ * Schema file endpoint
+ *
+ * Exports:
+ *  - handleSchemaFileRequest(req, res) -> HTTP handler function
+ *
+ * Serves schema and sample JSON files for pipeline tasks.
+ */
+
+import { getPipelineConfig } from "../../core/config.js";
+import { sendJson } from "../utils/http-utils.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * HTTP handler for schema file requests.
+ *
+ * @param {http.IncomingMessage} req - HTTP request object
+ * @param {http.ServerResponse} res - HTTP response object
+ */
+export async function handleSchemaFileRequest(req, res) {
+  const { slug, fileName } = req.params;
+  const { type } = req.query;
+
+  // Validate slug parameter
+  if (!slug || typeof slug !== "string" || !/^[A-Za-z0-9_-]+$/.test(slug)) {
+    return sendJson(res, 400, {
+      ok: false,
+      code: "invalid_params",
+      message: "Invalid slug parameter",
+    });
+  }
+
+  // Validate fileName parameter (no path traversal)
+  if (
+    !fileName ||
+    typeof fileName !== "string" ||
+    !/^[A-Za-z0-9_.-]+$/.test(fileName)
+  ) {
+    return sendJson(res, 400, {
+      ok: false,
+      code: "invalid_params",
+      message: "Invalid fileName parameter",
+    });
+  }
+
+  // Validate type parameter
+  if (type !== "schema" && type !== "sample") {
+    return sendJson(res, 400, {
+      ok: false,
+      code: "invalid_params",
+      message: "Invalid type parameter - must be 'schema' or 'sample'",
+    });
+  }
+
+  try {
+    // Get pipeline configuration
+    let pipelineConfig;
+    try {
+      pipelineConfig = getPipelineConfig(slug);
+    } catch (error) {
+      return sendJson(res, 404, {
+        ok: false,
+        code: "not_found",
+        message: `Pipeline '${slug}' not found in registry`,
+      });
+    }
+
+    const pipelineDir = path.dirname(pipelineConfig.pipelineJsonPath);
+    const baseName = path.parse(fileName).name;
+    const schemaFilePath = path.join(
+      pipelineDir,
+      "schemas",
+      `${baseName}.${type}.json`
+    );
+
+    // Read schema file
+    let fileContents;
+    try {
+      fileContents = await fs.readFile(schemaFilePath, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return sendJson(res, 404, {
+          ok: false,
+          code: "not_found",
+          message: "Schema file not found",
+        });
+      }
+      throw error;
+    }
+
+    // Return raw file contents (not parsed)
+    return sendJson(res, 200, {
+      ok: true,
+      data: fileContents,
+    });
+  } catch (error) {
+    console.error("handleSchemaFileRequest unexpected error:", error);
+    return sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}

package/src/ui/endpoints/task-analysis-endpoint.js

@@ -0,0 +1,104 @@
+/**
+ * Task analysis endpoint
+ *
+ * Exports:
+ *  - handleTaskAnalysisRequest(req, res) -> HTTP handler function
+ *
+ * Returns task analysis data if available, or null if no analysis file exists.
+ */
+
+import { getPipelineConfig } from "../../core/config.js";
+import { sendJson } from "../utils/http-utils.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * HTTP handler for task analysis requests.
+ *
+ * @param {http.IncomingMessage} req - HTTP request object
+ * @param {http.ServerResponse} res - HTTP response object
+ */
+export async function handleTaskAnalysisRequest(req, res) {
+  const { slug, taskId } = req.params;
+
+  // Validate slug parameter
+  if (!slug || typeof slug !== "string" || !/^[A-Za-z0-9_-]+$/.test(slug)) {
+    return sendJson(res, 400, {
+      ok: false,
+      code: "invalid_params",
+      message: "Invalid slug parameter",
+    });
+  }
+
+  // Validate taskId parameter
+  if (
+    !taskId ||
+    typeof taskId !== "string" ||
+    !/^[A-Za-z0-9_-]+$/.test(taskId)
+  ) {
+    return sendJson(res, 400, {
+      ok: false,
+      code: "invalid_params",
+      message: "Invalid taskId parameter",
+    });
+  }
+
+  try {
+    // Get pipeline configuration
+    let pipelineConfig;
+    try {
+      pipelineConfig = getPipelineConfig(slug);
+    } catch (error) {
+      return sendJson(res, 404, {
+        ok: false,
+        code: "not_found",
+        message: `Pipeline '${slug}' not found in registry`,
+      });
+    }
+
+    const pipelineDir = path.dirname(pipelineConfig.pipelineJsonPath);
+    const analysisPath = path.join(
+      pipelineDir,
+      "analysis",
+      `${taskId}.analysis.json`
+    );
+
+    // Attempt to read and parse analysis file
+    let analysisData;
+    try {
+      const contents = await fs.readFile(analysisPath, "utf8");
+      analysisData = JSON.parse(contents);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        // Analysis file doesn't exist - this is not an error
+        return sendJson(res, 200, {
+          ok: true,
+          data: null,
+        });
+      }
+
+      if (error instanceof SyntaxError) {
+        return sendJson(res, 500, {
+          ok: false,
+          code: "invalid_json",
+          message: "Invalid JSON in analysis file",
+        });
+      }
+
+      throw error;
+    }
+
+    // Return analysis data
+    return sendJson(res, 200, {
+      ok: true,
+      data: analysisData,
+    });
+  } catch (error) {
+    console.error("handleTaskAnalysisRequest unexpected error:", error);
+    return sendJson(res, 500, {
+      ok: false,
+      code: "internal_error",
+      message: "Internal server error",
+    });
+  }
+}

package/src/ui/endpoints/task-creation-endpoint.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import { streamSSE } from "../lib/sse.js";
+import { createHighLevelLLM } from "../../llm/index.js";
+
+export async function handleTaskPlan(req, res) {
+  console.log("[task-creation-endpoint] Request received");
+
+  const { messages, pipelineSlug } = req.body;
+
+  console.log("[task-creation-endpoint] Request details:", {
+    hasMessages: !!messages,
+    messageCount: Array.isArray(messages) ? messages.length : 0,
+    pipelineSlug,
+    bodyKeys: Object.keys(req.body),
+  });
+
+  // Validate input
+  if (!Array.isArray(messages)) {
+    console.error(
+      "[task-creation-endpoint] Validation failed: messages is not an array"
+    );
+    res.status(400).json({ error: "messages must be an array" });
+    return;
+  }
+
+  console.log(
+    "[task-creation-endpoint] Loading guidelines from docs/pipeline-task-guidelines.md..."
+  );
+
+  // Load guidelines - let it throw if missing
+  const guidelinesPath = "docs/pipeline-task-guidelines.md";
+  const guidelines = fs.readFileSync(guidelinesPath, "utf-8");
+
+  console.log(
+    "[task-creation-endpoint] Guidelines loaded, length:",
+    guidelines.length
+  );
+
+  // Build LLM messages array
+  const systemPrompt = `You are a pipeline task assistant. Help users create task definitions following these guidelines:
+
+${guidelines}
+
+Provide complete, working code. Use markdown code blocks.
+
+When you have completed a task definition that the user wants to create, wrap it in this format:
+[TASK_PROPOSAL]
+FILENAME: <filename.js>
+TASKNAME: <task-name>
+CODE:
+\`\`\`javascript
+<the complete task code here>
+\`\`\`
+[/TASK_PROPOSAL]`;
+
+  const llmMessages = [{ role: "system", content: systemPrompt }, ...messages];
+
+  console.log("[task-creation-endpoint] LLM messages array created:", {
+    totalMessages: llmMessages.length,
+    systemPromptLength: systemPrompt.length,
+  });
+
+  // Create SSE stream
+  console.log("[task-creation-endpoint] Creating SSE stream...");
+  const sse = streamSSE(res);
+
+  try {
+    console.log("[task-creation-endpoint] Creating LLM instance...");
+    // Get LLM instance (uses default provider from config)
+    const llm = createHighLevelLLM();
+
+    console.log("[task-creation-endpoint] Calling LLM chat with streaming...");
+    // Call LLM with streaming enabled
+    const response = await llm.chat({
+      messages: llmMessages,
+      responseFormat: "text",
+      stream: true,
+    });
+
+    console.log("[task-creation-endpoint] LLM response received:", {
+      isStream: typeof response[Symbol.asyncIterator] !== "undefined",
+    });
+
+    // Stream is an async generator
+    let chunkCount = 0;
+    for await (const chunk of response) {
+      if (chunk?.content) {
+        sse.send("chunk", { content: chunk.content });
+        chunkCount++;
+      }
+    }
+
+    console.log("[task-creation-endpoint] Sent", chunkCount, "chunks via SSE");
+
+    // Send done event
+    console.log("[task-creation-endpoint] Sending 'done' event...");
+    sse.send("done", {});
+    console.log("[task-creation-endpoint] Ending SSE stream...");
+    sse.end();
+    console.log("[task-creation-endpoint] Request completed successfully");
+  } catch (error) {
+    console.error("[task-creation-endpoint] Error occurred:", {
+      message: error.message,
+      stack: error.stack,
+      name: error.name,
+    });
+    // Send error event
+    sse.send("error", { message: error.message });
+    console.log(
+      "[task-creation-endpoint] Error sent via SSE, ending stream..."
+    );
+    sse.end();
+  }
+}

package/src/ui/endpoints/task-save-endpoint.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { getConfig } from "../../core/config.js";
+import { sendJson } from "../utils/http-utils.js";
+
+/**
+ * Handle task creation requests
+ *
+ * POST /api/tasks/create
+ * Body: { pipelineSlug, filename, taskName, code }
+ *
+ * Creates a new task file and updates the pipeline's task registry index.js
+ */
+export async function handleTaskSave(req, res) {
+  try {
+    const { pipelineSlug, filename, taskName, code } = req.body;
+
+    if (!pipelineSlug) {
+      return sendJson(res, 400, { error: "pipelineSlug is required" });
+    }
+    // Validate filename ends with .js
+    if (!filename || !filename.endsWith(".js")) {
+      return sendJson(res, 400, { error: "Filename must end with .js" });
+    }
+
+    // Validate taskName is kebab-case
+    const kebabCaseRegex = /^[a-z][a-z0-9-]*$/;
+    if (!taskName || !kebabCaseRegex.test(taskName)) {
+      return sendJson(res, 400, { error: "TaskName must be kebab-case" });
+    }
+
+    // Get configuration and root directory
+    const config = getConfig();
+    const rootDir = config.paths.root;
+
+    // Read registry.json to find pipeline's taskRegistryPath
+    const registryPath = path.join(rootDir, "pipeline-config", "registry.json");
+    const registryData = JSON.parse(await fs.readFile(registryPath, "utf8"));
+
+    // Look up pipeline in registry
+    const pipelineEntry = registryData.pipelines[pipelineSlug];
+    if (!pipelineEntry) {
+      return sendJson(res, 404, { error: "Pipeline not found" });
+    }
+
+    // Get task registry path (relative to root)
+    const taskRegistryPath = path.join(rootDir, pipelineEntry.taskRegistryPath);
+    const tasksDir = path.dirname(taskRegistryPath);
+
+    // Write task file (prevent path traversal by validating resolved path)
+    const taskFilePath = path.resolve(tasksDir, filename);
+    if (!taskFilePath.startsWith(tasksDir)) {
+      return sendJson(res, 400, { error: "Invalid filename" });
+    }
+    await fs.writeFile(taskFilePath, code, "utf8");
+
+    // Update index.js to export new task
+    const indexPath = taskRegistryPath;
+    let indexContent = await fs.readFile(indexPath, "utf8");
+
+    // Check if task name already exists in the index
+    const taskNamePattern = new RegExp(`^\\s*${taskName}\\s*:`, "m");
+    if (taskNamePattern.test(indexContent)) {
+      return sendJson(res, 400, {
+        error: `Task "${taskName}" already exists in the registry`,
+      });
+    }
+
+    // Find the line containing "export default {"
+    const exportLine = "export default {";
+    const exportLineIndex = indexContent.indexOf(exportLine);
+
+    if (exportLineIndex === -1) {
+      return sendJson(res, 500, {
+        error: "Failed to find export default line in index.js",
+      });
+    }
+
+    // Insert new task entry after the export line
+    const insertPosition = indexContent.indexOf("\n", exportLineIndex) + 1;
+    const newEntry = `  ${taskName}: "./${filename}",\n`;
+
+    indexContent =
+      indexContent.slice(0, insertPosition) +
+      newEntry +
+      indexContent.slice(insertPosition);
+
+    // Write updated index.js
+    await fs.writeFile(indexPath, indexContent, "utf8");
+
+    return sendJson(res, 200, {
+      ok: true,
+      path: taskFilePath,
+    });
+  } catch (error) {
+    console.error("Error creating task:", error);
+    return sendJson(res, 500, {
+      error: error.message || "Failed to create task",
+    });
+  }
+}

package/src/ui/express-app.js

@@ -18,6 +18,14 @@ import {
   handleTaskFileListRequest,
   handleTaskFileRequest,
 } from "./endpoints/file-endpoints.js";
+import { handlePipelinesHttpRequest } from "./endpoints/pipelines-endpoint.js";
+import { handleCreatePipeline } from "./endpoints/create-pipeline-endpoint.js";
+import { handlePipelineTypeDetailRequest } from "./endpoints/pipeline-type-detail-endpoint.js";
+import { handlePipelineAnalysis } from "./endpoints/pipeline-analysis-endpoint.js";
+import { handleTaskAnalysisRequest } from "./endpoints/task-analysis-endpoint.js";
+import { handleSchemaFileRequest } from "./endpoints/schema-file-endpoint.js";
+import { handleTaskPlan } from "./endpoints/task-creation-endpoint.js";
+import { handleTaskSave } from "./endpoints/task-save-endpoint.js";
 import { sendJson } from "./utils/http-utils.js";
 import { PROVIDER_FUNCTIONS } from "../config/models.js";
 
@@ -35,6 +43,12 @@ const __dirname = path.dirname(__filename);
 export function buildExpressApp({ dataDir, viteServer }) {
   const app = express();
 
+  // Parse JSON request bodies
+  app.use(express.json());
+
+  // Parse URL-encoded request bodies (for form submissions)
+  app.use(express.urlencoded({ extended: true }));
+
   // API guard middleware mounted on /api
   app.use("/api", (req, res, next) => {
     // Set CORS headers
@@ -103,6 +117,31 @@ export function buildExpressApp({ dataDir, viteServer }) {
     }
   });
 
+  // GET /api/pipelines
+  app.get("/api/pipelines", async (req, res) => {
+    await handlePipelinesHttpRequest(req, res);
+  });
+
+  // POST /api/pipelines
+  app.post("/api/pipelines", handleCreatePipeline);
+
+  // GET /api/pipelines/:slug
+  app.get("/api/pipelines/:slug", async (req, res) => {
+    await handlePipelineTypeDetailRequest(req, res);
+  });
+
+  // POST /api/pipelines/:slug/analyze
+  app.post("/api/pipelines/:slug/analyze", handlePipelineAnalysis);
+
+  // GET /api/pipelines/:slug/tasks/:taskId/analysis
+  app.get(
+    "/api/pipelines/:slug/tasks/:taskId/analysis",
+    handleTaskAnalysisRequest
+  );
+
+  // GET /api/pipelines/:slug/schemas/:fileName
+  app.get("/api/pipelines/:slug/schemas/:fileName", handleSchemaFileRequest);
+
   // GET /api/jobs
   app.get("/api/jobs", async (req, res) => {
     await handleJobListRequest(req, res);
@@ -163,6 +202,12 @@ export function buildExpressApp({ dataDir, viteServer }) {
     });
   });
 
+  // POST /api/ai/task-plan
+  app.post("/api/ai/task-plan", handleTaskPlan);
+
+  // POST /api/tasks/create
+  app.post("/api/tasks/create", handleTaskSave);
+
   // Dev middleware (mount after all API routes)
   if (viteServer && viteServer.middlewares) {
     app.use(viteServer.middlewares);

package/src/ui/lib/analysis-lock.js

@@ -0,0 +1,67 @@
+/**
+ * In-memory lock for pipeline analysis operations.
+ * Ensures only one pipeline can be analyzed at a time.
+ */
+
+let currentLock = null;
+
+/**
+ * Attempt to acquire the analysis lock for a pipeline.
+ * @param {string} pipelineSlug - The pipeline identifier
+ * @returns {{ acquired: true } | { acquired: false, heldBy: string }}
+ */
+export function acquireLock(pipelineSlug) {
+  if (!pipelineSlug || typeof pipelineSlug !== "string") {
+    throw new Error(
+      `Invalid pipelineSlug: expected non-empty string, got ${typeof pipelineSlug}`
+    );
+  }
+
+  if (currentLock === null) {
+    currentLock = {
+      pipelineSlug,
+      startedAt: new Date(),
+    };
+    return { acquired: true };
+  }
+
+  return {
+    acquired: false,
+    heldBy: currentLock.pipelineSlug,
+  };
+}
+
+/**
+ * Release the analysis lock for a pipeline.
+ * @param {string} pipelineSlug - The pipeline identifier that holds the lock
+ * @throws {Error} If the lock is not held by this pipeline
+ */
+export function releaseLock(pipelineSlug) {
+  if (!pipelineSlug || typeof pipelineSlug !== "string") {
+    throw new Error(
+      `Invalid pipelineSlug: expected non-empty string, got ${typeof pipelineSlug}`
+    );
+  }
+
+  if (currentLock === null) {
+    throw new Error(
+      `Cannot release lock for '${pipelineSlug}': no lock is currently held`
+    );
+  }
+
+  if (currentLock.pipelineSlug !== pipelineSlug) {
+    throw new Error(
+      `Cannot release lock for '${pipelineSlug}': lock is held by '${currentLock.pipelineSlug}'`
+    );
+  }
+
+  currentLock = null;
+}
+
+/**
+ * Get the current lock status.
+ * @returns {{ pipelineSlug: string, startedAt: Date } | null}
+ */
+export function getLockStatus() {
+  return currentLock;
+}