@ryanfw/prompt-orchestration-pipeline 0.6.0 → 0.7.0

package/src/core/status-writer.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { TaskState } from "../config/statuses.js";
 
 // Lazy import SSE registry to avoid circular dependencies
 let sseRegistry = null;
@@ -57,7 +58,7 @@ const createStatusWriterLogger = (jobId) => {
 function createDefaultStatus(jobId) {
   return {
     id: jobId,
-    state: "pending",
+    state: TaskState.PENDING,
     current: null,
     currentStage: null,
     lastUpdated: new Date().toISOString(),
@@ -131,7 +132,7 @@ function validateStatusSnapshot(snapshot) {
 
   // Ensure required root fields exist
   if (typeof snapshot.state !== "string") {
-    snapshot.state = "pending";
+    snapshot.state = TaskState.PENDING;
   }
   if (snapshot.current !== null && typeof snapshot.current !== "string") {
     snapshot.current = null;
@@ -214,7 +215,13 @@ export async function writeJobStatus(jobDir, updateFn) {
       const validated = validateStatusSnapshot(current);
 
       // Apply user updates
-      const maybeUpdated = updateFn(validated);
+      let maybeUpdated;
+      try {
+        maybeUpdated = updateFn(validated);
+      } catch (error) {
+        console.error(`[${jobId}] Error executing update function:`, error);
+        throw new Error(`Update function failed: ${error.message}`);
+      }
       const snapshot = validateStatusSnapshot(
         maybeUpdated === undefined ? validated : maybeUpdated
       );
@@ -340,3 +347,140 @@ export async function updateTaskStatus(jobDir, taskId, taskUpdateFn) {
     return snapshot;
   });
 }
+
+/**
+ * Reset a job from a specific task onward, preserving prior completed tasks
+ *
+ * @param {string} jobDir - Job directory path containing tasks-status.json
+ * @param {string} fromTask - Task identifier to restart from (inclusive)
+ * @param {Object} options - Reset options
+ * @param {boolean} [options.clearTokenUsage=true] - Whether to clear token usage arrays
+ * @returns {Promise<Object>} The updated status snapshot
+ */
+export async function resetJobFromTask(
+  jobDir,
+  fromTask,
+  { clearTokenUsage = true } = {}
+) {
+  if (!jobDir || typeof jobDir !== "string") {
+    throw new Error("jobDir must be a non-empty string");
+  }
+
+  if (!fromTask || typeof fromTask !== "string") {
+    throw new Error("fromTask must be a non-empty string");
+  }
+
+  return writeJobStatus(jobDir, (snapshot) => {
+    // Reset root-level status
+    snapshot.state = TaskState.PENDING;
+    snapshot.current = null;
+    snapshot.currentStage = null;
+    snapshot.progress = 0;
+    snapshot.lastUpdated = new Date().toISOString();
+
+    // Ensure tasks object exists
+    if (!snapshot.tasks || typeof snapshot.tasks !== "object") {
+      snapshot.tasks = {};
+    }
+
+    // Compute progress based on preserved (done) tasks before fromTask
+    let doneCount = 0;
+    const taskKeys = Object.keys(snapshot.tasks);
+    for (const taskId of taskKeys) {
+      if (snapshot.tasks[taskId]?.state === TaskState.DONE) {
+        doneCount++;
+      }
+    }
+    snapshot.progress =
+      taskKeys.length > 0 ? (doneCount / taskKeys.length) * 100 : 0;
+
+    // Reset tasks from fromTask onward to pending; keep earlier tasks as-is
+    for (const taskId of taskKeys) {
+      const task = snapshot.tasks[taskId];
+      if (!task) continue; // ensure task object exists
+
+      const shouldReset =
+        taskKeys.indexOf(taskId) >= taskKeys.indexOf(fromTask);
+      if (shouldReset) {
+        // Reset task state and metadata
+        task.state = TaskState.PENDING;
+        task.currentStage = null;
+
+        // Remove error-related fields
+        delete task.failedStage;
+        delete task.error;
+
+        // Reset counters
+        task.attempts = 0;
+        task.refinementAttempts = 0;
+
+        // Clear token usage if requested
+        if (clearTokenUsage) {
+          task.tokenUsage = [];
+        }
+      }
+      // If task appears before fromTask and is not done, keep its state untouched
+      // This preserves upstream work if user restarts from a mid-pipeline task
+    }
+
+    // Preserve files.* arrays - do not modify them
+    // This ensures generated files are preserved during restart
+
+    return snapshot;
+  });
+}
+
+/**
+ * Reset a job and all its tasks to clean-slate state atomically
+ *
+ * @param {string} jobDir - Job directory path containing tasks-status.json
+ * @param {Object} options - Reset options
+ * @param {boolean} [options.clearTokenUsage=true] - Whether to clear token usage arrays
+ * @returns {Promise<Object>} The updated status snapshot
+ */
+export async function resetJobToCleanSlate(
+  jobDir,
+  { clearTokenUsage = true } = {}
+) {
+  if (!jobDir || typeof jobDir !== "string") {
+    throw new Error("jobDir must be a non-empty string");
+  }
+
+  return writeJobStatus(jobDir, (snapshot) => {
+    // Reset root-level status
+    snapshot.state = TaskState.PENDING;
+    snapshot.current = null;
+    snapshot.currentStage = null;
+    snapshot.progress = 0;
+    snapshot.lastUpdated = new Date().toISOString();
+
+    // Reset all tasks
+    if (snapshot.tasks && typeof snapshot.tasks === "object") {
+      for (const taskId of Object.keys(snapshot.tasks)) {
+        const task = snapshot.tasks[taskId];
+
+        // Reset task state
+        task.state = TaskState.PENDING;
+        task.currentStage = null;
+
+        // Remove error-related fields
+        delete task.failedStage;
+        delete task.error;
+
+        // Reset counters
+        task.attempts = 0;
+        task.refinementAttempts = 0;
+
+        // Clear token usage if requested
+        if (clearTokenUsage) {
+          task.tokenUsage = [];
+        }
+      }
+    }
+
+    // Preserve files.* arrays - do not modify them
+    // This ensures generated files are preserved during restart
+
+    return snapshot;
+  });
+}

package/src/core/symlink-bridge.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { ensureSymlink } from "./symlink-utils.js";
+
+/**
+ * Creates a taskDir symlink bridge to ensure deterministic module resolution.
+ *
+ * This function creates three symlinks in the task directory:
+ * - taskDir/node_modules -> {poRoot}/node_modules (for bare package specifiers)
+ * - taskDir/project -> {poRoot} (optional convenience for absolute project paths)
+ * - taskDir/_task_root -> dirname(taskModulePath) (for relative imports)
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.taskDir - The task directory where symlinks should be created
+ * @param {string} options.poRoot - The repository root directory
+ * @param {string} options.taskModulePath - Absolute path to the original task module
+ * @returns {string} The relocated entry path for the task module
+ * @throws {Error} If symlink creation fails
+ */
+export async function ensureTaskSymlinkBridge({
+  taskDir,
+  poRoot,
+  taskModulePath,
+}) {
+  // Normalize all paths to absolute paths
+  const normalizedTaskDir = path.resolve(taskDir);
+  const normalizedPoRoot = path.resolve(poRoot);
+  const normalizedTaskModulePath = path.resolve(taskModulePath);
+
+  // Ensure the task directory exists
+  await import("node:fs/promises").then((fs) =>
+    fs.mkdir(normalizedTaskDir, { recursive: true })
+  );
+
+  // Create symlink for node_modules -> {poRoot}/node_modules
+  const nodeModulesLink = path.join(normalizedTaskDir, "node_modules");
+  const nodeModulesTarget = path.join(normalizedPoRoot, "node_modules");
+  await ensureSymlink(nodeModulesLink, nodeModulesTarget, "dir");
+
+  // Create symlink for project -> {poRoot}
+  const projectLink = path.join(normalizedTaskDir, "project");
+  await ensureSymlink(projectLink, normalizedPoRoot, "dir");
+
+  // Create symlink for _task_root -> dirname(taskModulePath)
+  const taskRootLink = path.join(normalizedTaskDir, "_task_root");
+  const taskRootTarget = path.dirname(normalizedTaskModulePath);
+  await ensureSymlink(taskRootLink, taskRootTarget, "dir");
+
+  // Return the relocated entry path
+  const taskModuleBasename = path.basename(normalizedTaskModulePath);
+  const relocatedEntry = path.join(
+    normalizedTaskDir,
+    "_task_root",
+    taskModuleBasename
+  );
+
+  return relocatedEntry;
+}

package/src/core/symlink-utils.js

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Creates an idempotent symlink, safely handling existing files/symlinks.
+ *
+ * @param {string} linkPath - Path where the symlink should be created
+ * @param {string} targetPath - Path that the symlink should point to
+ * @param {'file' | 'dir'} type - Type of symlink to create
+ * @throws {Error} If symlink creation fails on non-POSIX systems
+ */
+export async function ensureSymlink(linkPath, targetPath, type) {
+  try {
+    // Check if linkPath already exists
+    const stats = await fs.lstat(linkPath).catch(() => null);
+
+    if (stats) {
+      if (stats.isSymbolicLink()) {
+        // If it's already a symlink pointing to the correct target, we're done
+        const existingTarget = await fs.readlink(linkPath);
+        if (existingTarget === targetPath) {
+          return;
+        }
+        // If it points to a different target, remove it
+        await fs.unlink(linkPath);
+      } else if (stats.isDirectory()) {
+        // If it's a directory, remove it recursively
+        await fs.rmdir(linkPath, { recursive: true });
+      } else {
+        // If it's a file, remove it
+        await fs.unlink(linkPath);
+      }
+    }
+
+    // Ensure parent directory exists
+    const parentDir = path.dirname(linkPath);
+    await fs.mkdir(parentDir, { recursive: true });
+
+    // Create the symlink
+    await fs.symlink(targetPath, linkPath, type);
+  } catch (error) {
+    // Re-throw with more context
+    throw new Error(
+      `Failed to create symlink from ${linkPath} -> ${targetPath}: ${error.message}`
+    );
+  }
+}
+
+/**
+ * Removes task symlinks from a completed job directory to avoid dangling links.
+ *
+ * @param {string} completedJobDir - Path to the completed job directory (e.g., COMPLETE_DIR/jobId)
+ */
+export async function cleanupTaskSymlinks(completedJobDir) {
+  const tasksDir = path.join(completedJobDir, "tasks");
+
+  try {
+    // Check if tasks directory exists
+    const tasksStats = await fs.lstat(tasksDir).catch(() => null);
+    if (!tasksStats || !tasksStats.isDirectory()) {
+      return; // No tasks directory to clean up
+    }
+
+    // Get all task directories
+    const taskDirs = await fs.readdir(tasksDir, { withFileTypes: true });
+
+    for (const taskDir of taskDirs) {
+      if (!taskDir.isDirectory()) continue;
+
+      const taskPath = path.join(tasksDir, taskDir.name);
+
+      // Remove specific symlinks if they exist and are actually symlinks
+      const symlinksToRemove = ["node_modules", "project", "_task_root"];
+
+      for (const linkName of symlinksToRemove) {
+        const linkPath = path.join(taskPath, linkName);
+
+        try {
+          const stats = await fs.lstat(linkPath);
+          if (stats.isSymbolicLink()) {
+            await fs.unlink(linkPath);
+          }
+        } catch {
+          // Ignore errors (file doesn't exist, permissions, etc.)
+        }
+      }
+    }
+  } catch (error) {
+    // Log but don't fail - cleanup is optional
+    console.warn(
+      `Warning: Failed to cleanup task symlinks in ${completedJobDir}: ${error.message}`
+    );
+  }
+}