@jojonax/codex-copilot 1.5.5 → 1.6.0

package/src/utils/checkpoint.js

@@ -1,246 +1,246 @@
-/**
- * Checkpoint state manager - Fine-grained state persistence
- * 
- * Provides atomic save/load for checkpoint state, enabling
- * resume from any sub-step within a task after interruption.
- */
-
-import { readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
-import { resolve } from 'path';
-
-const PHASE_ORDER = ['develop', 'pr', 'review', 'merge'];
-const STEP_ORDERS = {
-  develop: ['branch_created', 'prompt_ready', 'codex_complete'],
-  pr: ['committed', 'pushed', 'pr_created'],
-  review: ['waiting_review', 'feedback_received', 'fix_applied'],
-  merge: ['merged'],
-};
-
-/**
- * Create a checkpoint manager for a project
- * @param {string} projectDir - Project root directory
- */
-export function createCheckpoint(projectDir) {
-  const statePath = resolve(projectDir, '.codex-copilot/state.json');
-  const tempPath = resolve(projectDir, '.codex-copilot/state.json.tmp');
-
-  /**
-   * Load current state from disk
-   */
-  function load() {
-    try {
-      return JSON.parse(readFileSync(statePath, 'utf-8'));
-    } catch {
-      return getDefaultState();
-    }
-  }
-
-  /**
-   * Save state atomically (write to temp file, then rename)
-   * @param {object} update - Partial state to merge
-   */
-  function save(update) {
-    const current = load();
-    const merged = {
-      ...current,
-      ...update,
-      last_updated: new Date().toISOString(),
-    };
-    // Atomic write: temp file + rename prevents corruption on crash
-    writeFileSync(tempPath, JSON.stringify(merged, null, 2));
-    renameSync(tempPath, statePath);
-    return merged;
-  }
-
-  /**
-   * Mark a specific phase & step as reached.
-   * Includes monotonic progress guard — prevents regression from a later
-   * phase back to an earlier one (e.g., 'pr' → 'develop' is blocked).
-   */
-  function saveStep(taskId, phase, phaseStep, extra = {}) {
-    const current = load();
-
-    // Monotonic progress guard: only allow forward movement within the same task
-    if (current.current_task === taskId && current.phase) {
-      const currentPhaseIdx = PHASE_ORDER.indexOf(current.phase);
-      const newPhaseIdx = PHASE_ORDER.indexOf(phase);
-
-      if (newPhaseIdx < currentPhaseIdx) {
-        // Attempting to go backward — ignore silently (likely a stale call)
-        return current;
-      }
-
-      // Same phase: ensure step is not going backward
-      if (newPhaseIdx === currentPhaseIdx) {
-        const steps = STEP_ORDERS[phase] || [];
-        const currentStepIdx = steps.indexOf(current.phase_step);
-        const newStepIdx = steps.indexOf(phaseStep);
-        if (newStepIdx < currentStepIdx) {
-          return current; // Step regression — ignore
-        }
-      }
-    }
-
-    return save({
-      current_task: taskId,
-      phase,
-      phase_step: phaseStep,
-      ...extra,
-    });
-  }
-
-  /**
-   * Mark current task as fully completed, clear phase info
-   */
-  function completeTask(taskId) {
-    return save({
-      current_task: taskId,
-      phase: null,
-      phase_step: null,
-      current_pr: null,
-      review_round: 0,
-      branch: null,
-    });
-  }
-
-  /**
-   * Check if a specific phase+step has been reached for a task
-   * Returns true if the saved state is at or past the given step
-   */
-  function isStepDone(taskId, phase, phaseStep) {
-    const state = load();
-    if (state.current_task !== taskId) return false;
-    if (!state.phase) return false;
-
-    const savedPhaseIdx = PHASE_ORDER.indexOf(state.phase);
-    const targetPhaseIdx = PHASE_ORDER.indexOf(phase);
-
-    // If saved phase is ahead, this step is done
-    if (savedPhaseIdx > targetPhaseIdx) return true;
-    // If saved phase is behind, this step is not done
-    if (savedPhaseIdx < targetPhaseIdx) return false;
-
-    // Same phase: compare steps within phase
-    const steps = STEP_ORDERS[phase] || [];
-    const savedStepIdx = steps.indexOf(state.phase_step);
-    const targetStepIdx = steps.indexOf(phaseStep);
-
-    return savedStepIdx >= targetStepIdx;
-  }
-
-  /**
-   * Full reset to initial state
-   */
-  function reset() {
-    const state = getDefaultState();
-    writeFileSync(statePath, JSON.stringify(state, null, 2));
-    return state;
-  }
-
-  /**
-   * Clear all checkpoint data for a task (for retry)
-   */
-  function clearTask(taskId) {
-    const state = load();
-    if (state.current_task === taskId) {
-      return save({
-        phase: null,
-        phase_step: null,
-        current_pr: null,
-        review_round: 0,
-        branch: null,
-      });
-    }
-    return state;
-  }
-
-  /**
-   * Clear a specific phase step (for partial retry, e.g. merge-only)
-   */
-  function clearStep(taskId, phase, phaseStep) {
-    const state = load();
-    if (state.current_task === taskId && state.phase === phase && state.phase_step === phaseStep) {
-      return save({
-        phase: null,
-        phase_step: null,
-      });
-    }
-    return state;
-  }
-
-  /**
-   * E1/E4: Validate consistency between checkpoint state and tasks status.
-   * Detects and repairs mismatches such as:
-   *  - Task marked 'in_progress' but no checkpoint data for it
-   *  - Checkpoint points to a task that's already completed
-   *  - Multiple tasks marked 'in_progress' simultaneously
-   * @param {object} tasks - The tasks.json data structure
-   * @returns {{ ok: boolean, repairs: string[] }}
-   */
-  function validateConsistency(tasks) {
-    const state = load();
-    const repairs = [];
-
-    if (!tasks?.tasks || !Array.isArray(tasks.tasks)) {
-      return { ok: true, repairs: [] };
-    }
-
-    // Check 1: Multiple in_progress tasks (should only be one at a time)
-    const inProgress = tasks.tasks.filter(t => t.status === 'in_progress');
-    if (inProgress.length > 1) {
-      // Keep the one matching checkpoint, reset others to pending
-      for (const task of inProgress) {
-        if (task.id !== state.current_task) {
-          task.status = 'pending';
-          repairs.push(`Task #${task.id}: was 'in_progress' but not current — reset to 'pending'`);
-        }
-      }
-    }
-
-    // Check 2: Task is in_progress but checkpoint has no data for it
-    if (inProgress.length === 1 && state.current_task !== inProgress[0].id) {
-      if (!state.phase) {
-        // Checkpoint is empty — task was marked in_progress but never started
-        inProgress[0].status = 'pending';
-        repairs.push(`Task #${inProgress[0].id}: marked 'in_progress' but no checkpoint data — reset to 'pending'`);
-      }
-    }
-
-    // Check 3: Checkpoint points to a completed task (stale checkpoint)
-    if (state.current_task > 0 && state.phase) {
-      const checkpointTask = tasks.tasks.find(t => t.id === state.current_task);
-      if (checkpointTask && checkpointTask.status === 'completed') {
-        // Checkpoint is stale — clear it
-        save({ phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
-        repairs.push(`Checkpoint for task #${state.current_task} cleared (task already completed)`);
-      }
-    }
-
-    // Check 4: Checkpoint task ID doesn't exist in tasks list
-    if (state.current_task > 0) {
-      const exists = tasks.tasks.find(t => t.id === state.current_task);
-      if (!exists) {
-        save({ current_task: 0, phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
-        repairs.push(`Checkpoint referenced non-existent task #${state.current_task} — reset`);
-      }
-    }
-
-    return { ok: repairs.length === 0, repairs };
-  }
-
-  return { load, save, saveStep, completeTask, isStepDone, reset, clearTask, clearStep, validateConsistency };
-}
-
-function getDefaultState() {
-  return {
-    current_task: 0,
-    phase: null,
-    phase_step: null,
-    current_pr: null,
-    review_round: 0,
-    branch: null,
-    status: 'initialized',
-    last_updated: new Date().toISOString(),
-  };
-}
-
+/**
+ * Checkpoint state manager - Fine-grained state persistence
+ * 
+ * Provides atomic save/load for checkpoint state, enabling
+ * resume from any sub-step within a task after interruption.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+const PHASE_ORDER = ['develop', 'pr', 'review', 'merge'];
+const STEP_ORDERS = {
+  develop: ['branch_created', 'prompt_ready', 'codex_complete'],
+  pr: ['committed', 'pushed', 'pr_created'],
+  review: ['waiting_review', 'feedback_received', 'fix_applied'],
+  merge: ['merged'],
+};
+
+/**
+ * Create a checkpoint manager for a project
+ * @param {string} projectDir - Project root directory
+ */
+export function createCheckpoint(projectDir) {
+  const statePath = resolve(projectDir, '.codex-copilot/state.json');
+  const tempPath = resolve(projectDir, '.codex-copilot/state.json.tmp');
+
+  /**
+   * Load current state from disk
+   */
+  function load() {
+    try {
+      return JSON.parse(readFileSync(statePath, 'utf-8'));
+    } catch {
+      return getDefaultState();
+    }
+  }
+
+  /**
+   * Save state atomically (write to temp file, then rename)
+   * @param {object} update - Partial state to merge
+   */
+  function save(update) {
+    const current = load();
+    const merged = {
+      ...current,
+      ...update,
+      last_updated: new Date().toISOString(),
+    };
+    // Atomic write: temp file + rename prevents corruption on crash
+    writeFileSync(tempPath, JSON.stringify(merged, null, 2));
+    renameSync(tempPath, statePath);
+    return merged;
+  }
+
+  /**
+   * Mark a specific phase & step as reached.
+   * Includes monotonic progress guard — prevents regression from a later
+   * phase back to an earlier one (e.g., 'pr' → 'develop' is blocked).
+   */
+  function saveStep(taskId, phase, phaseStep, extra = {}) {
+    const current = load();
+
+    // Monotonic progress guard: only allow forward movement within the same task
+    if (current.current_task === taskId && current.phase) {
+      const currentPhaseIdx = PHASE_ORDER.indexOf(current.phase);
+      const newPhaseIdx = PHASE_ORDER.indexOf(phase);
+
+      if (newPhaseIdx < currentPhaseIdx) {
+        // Attempting to go backward — ignore silently (likely a stale call)
+        return current;
+      }
+
+      // Same phase: ensure step is not going backward
+      if (newPhaseIdx === currentPhaseIdx) {
+        const steps = STEP_ORDERS[phase] || [];
+        const currentStepIdx = steps.indexOf(current.phase_step);
+        const newStepIdx = steps.indexOf(phaseStep);
+        if (newStepIdx < currentStepIdx) {
+          return current; // Step regression — ignore
+        }
+      }
+    }
+
+    return save({
+      current_task: taskId,
+      phase,
+      phase_step: phaseStep,
+      ...extra,
+    });
+  }
+
+  /**
+   * Mark current task as fully completed, clear phase info
+   */
+  function completeTask(taskId) {
+    return save({
+      current_task: taskId,
+      phase: null,
+      phase_step: null,
+      current_pr: null,
+      review_round: 0,
+      branch: null,
+    });
+  }
+
+  /**
+   * Check if a specific phase+step has been reached for a task
+   * Returns true if the saved state is at or past the given step
+   */
+  function isStepDone(taskId, phase, phaseStep) {
+    const state = load();
+    if (state.current_task !== taskId) return false;
+    if (!state.phase) return false;
+
+    const savedPhaseIdx = PHASE_ORDER.indexOf(state.phase);
+    const targetPhaseIdx = PHASE_ORDER.indexOf(phase);
+
+    // If saved phase is ahead, this step is done
+    if (savedPhaseIdx > targetPhaseIdx) return true;
+    // If saved phase is behind, this step is not done
+    if (savedPhaseIdx < targetPhaseIdx) return false;
+
+    // Same phase: compare steps within phase
+    const steps = STEP_ORDERS[phase] || [];
+    const savedStepIdx = steps.indexOf(state.phase_step);
+    const targetStepIdx = steps.indexOf(phaseStep);
+
+    return savedStepIdx >= targetStepIdx;
+  }
+
+  /**
+   * Full reset to initial state
+   */
+  function reset() {
+    const state = getDefaultState();
+    writeFileSync(statePath, JSON.stringify(state, null, 2));
+    return state;
+  }
+
+  /**
+   * Clear all checkpoint data for a task (for retry)
+   */
+  function clearTask(taskId) {
+    const state = load();
+    if (state.current_task === taskId) {
+      return save({
+        phase: null,
+        phase_step: null,
+        current_pr: null,
+        review_round: 0,
+        branch: null,
+      });
+    }
+    return state;
+  }
+
+  /**
+   * Clear a specific phase step (for partial retry, e.g. merge-only)
+   */
+  function clearStep(taskId, phase, phaseStep) {
+    const state = load();
+    if (state.current_task === taskId && state.phase === phase && state.phase_step === phaseStep) {
+      return save({
+        phase: null,
+        phase_step: null,
+      });
+    }
+    return state;
+  }
+
+  /**
+   * E1/E4: Validate consistency between checkpoint state and tasks status.
+   * Detects and repairs mismatches such as:
+   *  - Task marked 'in_progress' but no checkpoint data for it
+   *  - Checkpoint points to a task that's already completed
+   *  - Multiple tasks marked 'in_progress' simultaneously
+   * @param {object} tasks - The tasks.json data structure
+   * @returns {{ ok: boolean, repairs: string[] }}
+   */
+  function validateConsistency(tasks) {
+    const state = load();
+    const repairs = [];
+
+    if (!tasks?.tasks || !Array.isArray(tasks.tasks)) {
+      return { ok: true, repairs: [] };
+    }
+
+    // Check 1: Multiple in_progress tasks (should only be one at a time)
+    const inProgress = tasks.tasks.filter(t => t.status === 'in_progress');
+    if (inProgress.length > 1) {
+      // Keep the one matching checkpoint, reset others to pending
+      for (const task of inProgress) {
+        if (task.id !== state.current_task) {
+          task.status = 'pending';
+          repairs.push(`Task #${task.id}: was 'in_progress' but not current — reset to 'pending'`);
+        }
+      }
+    }
+
+    // Check 2: Task is in_progress but checkpoint has no data for it
+    if (inProgress.length === 1 && state.current_task !== inProgress[0].id) {
+      if (!state.phase) {
+        // Checkpoint is empty — task was marked in_progress but never started
+        inProgress[0].status = 'pending';
+        repairs.push(`Task #${inProgress[0].id}: marked 'in_progress' but no checkpoint data — reset to 'pending'`);
+      }
+    }
+
+    // Check 3: Checkpoint points to a completed task (stale checkpoint)
+    if (state.current_task > 0 && state.phase) {
+      const checkpointTask = tasks.tasks.find(t => t.id === state.current_task);
+      if (checkpointTask && checkpointTask.status === 'completed') {
+        // Checkpoint is stale — clear it
+        save({ phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
+        repairs.push(`Checkpoint for task #${state.current_task} cleared (task already completed)`);
+      }
+    }
+
+    // Check 4: Checkpoint task ID doesn't exist in tasks list
+    if (state.current_task > 0) {
+      const exists = tasks.tasks.find(t => t.id === state.current_task);
+      if (!exists) {
+        save({ current_task: 0, phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
+        repairs.push(`Checkpoint referenced non-existent task #${state.current_task} — reset`);
+      }
+    }
+
+    return { ok: repairs.length === 0, repairs };
+  }
+
+  return { load, save, saveStep, completeTask, isStepDone, reset, clearTask, clearStep, validateConsistency };
+}
+
+function getDefaultState() {
+  return {
+    current_task: 0,
+    phase: null,
+    phase_step: null,
+    current_pr: null,
+    review_round: 0,
+    branch: null,
+    status: 'initialized',
+    last_updated: new Date().toISOString(),
+  };
+}
+