@jojonax/codex-copilot 1.5.5 → 1.6.0

package/src/utils/self-heal.js

@@ -1,330 +1,330 @@
-/**
- * Self-Healing Module — Unified recovery and health check entry point
- *
- * Layer 3-4 of the self-healing architecture:
- *   - preFlightCheck():      Full environment validation before run
- *   - validatePhaseEntry():  Phase-specific guard before each phase starts
- *
- * Uses Layer 2 building blocks from git.js and github.js.
- */
-
-import { existsSync, writeFileSync, readFileSync, unlinkSync, accessSync, constants } from 'fs';
-import { resolve } from 'path';
-import { git } from './git.js';
-import { github } from './github.js';
-import { log } from './logger.js';
-import { readJSON, writeJSON } from './json.js';
-
-/**
- * Layer 4: Pre-flight health check — run before starting the automation loop.
- *
- * Performs comprehensive environment validation and auto-repairs:
- *   1. Concurrent execution lock (PID file)
- *   2. Git lock file cleanup
- *   3. Detached HEAD recovery
- *   4. Orphaned stash detection
- *   5. Git repository integrity
- *   6. GitHub auth verification
- *   7. Temp file cleanup
- *   8. Task/Checkpoint consistency validation
- *
- * @param {string} projectDir - Project root directory
- * @param {string} baseBranch - Base branch name (e.g., 'main')
- * @param {object} [options]
- * @param {object} [options.checkpoint] - Checkpoint manager instance
- * @param {object} [options.tasks] - Tasks data from tasks.json
- * @returns {{ ok: boolean, repairs: string[], warnings: string[], blockers: string[] }}
- */
-export function preFlightCheck(projectDir, baseBranch, options = {}) {
-  const copilotDir = resolve(projectDir, '.codex-copilot');
-  const repairs = [];
-  const warnings = [];
-  const blockers = [];
-
-  log.dim('Running pre-flight health check...');
-
-  // ── 1. Concurrent execution lock (D3) ──
-  const pidPath = resolve(copilotDir, '.pid');
-  if (existsSync(pidPath)) {
-    try {
-      const pidContent = readFileSync(pidPath, 'utf-8').trim();
-      const [pid, startTime] = pidContent.split(':');
-      const pidNum = parseInt(pid, 10);
-
-      // Check if the process is still running
-      let isRunning = false;
-      try {
-        process.kill(pidNum, 0); // Signal 0: check if process exists
-        isRunning = true;
-      } catch {
-        isRunning = false; // Process doesn't exist
-      }
-
-      if (isRunning) {
-        const age = startTime ? Math.round((Date.now() - parseInt(startTime, 10)) / 1000) : 0;
-        blockers.push(`Another codex-copilot instance is running (PID: ${pidNum}, age: ${age}s). Kill it first or wait.`);
-      } else {
-        // Stale PID file — remove it
-        unlinkSync(pidPath);
-        repairs.push('Removed stale PID lock file from crashed process');
-      }
-    } catch {
-      // Can't read PID file — remove it
-      try { unlinkSync(pidPath); } catch {}
-      repairs.push('Removed unreadable PID lock file');
-    }
-  }
-
-  // Write our PID (even if there are other blockers, we need to own the lock)
-  if (blockers.length === 0) {
-    try {
-      writeFileSync(pidPath, `${process.pid}:${Date.now()}`);
-    } catch { /* non-critical */ }
-  }
-
-  // ── 2. Git lock file cleanup (A2) ──
-  try {
-    const removedLocks = git.clearStaleLocks(projectDir);
-    if (removedLocks.length > 0) {
-      repairs.push(`Cleared ${removedLocks.length} stale git lock file(s): ${removedLocks.join(', ')}`);
-    }
-  } catch (err) {
-    warnings.push(`Lock file check failed: ${err.message}`);
-  }
-
-  // ── 3. Detached HEAD recovery (A3) ──
-  try {
-    const recovered = git.recoverDetachedHead(projectDir);
-    if (recovered) {
-      repairs.push(`Recovered from detached HEAD → ${recovered}`);
-    }
-  } catch (err) {
-    warnings.push(`Detached HEAD check failed: ${err.message}`);
-  }
-
-  // ── 4. Orphaned stash detection (A4) ──
-  try {
-    const stashStatus = git.checkOrphanedStash(projectDir);
-    if (stashStatus.found) {
-      warnings.push(`${stashStatus.count} stash entry(s) found — run 'git stash list' to inspect`);
-    }
-  } catch (err) {
-    // Non-critical
-  }
-
-  // ── 5. Git index health (A1) ──
-  try {
-    const gitDir = resolve(projectDir, '.git');
-    const hasRebase = existsSync(resolve(gitDir, 'rebase-merge')) || existsSync(resolve(gitDir, 'rebase-apply'));
-    const hasMerge = existsSync(resolve(gitDir, 'MERGE_HEAD'));
-    const hasCherryPick = existsSync(resolve(gitDir, 'CHERRY_PICK_HEAD'));
-
-    if (hasRebase || hasMerge || hasCherryPick) {
-      git.resolveIndex(projectDir);
-      const operations = [];
-      if (hasRebase) operations.push('rebase');
-      if (hasMerge) operations.push('merge');
-      if (hasCherryPick) operations.push('cherry-pick');
-      repairs.push(`Resolved stuck git operation(s): ${operations.join(', ')}`);
-    }
-  } catch (err) {
-    warnings.push(`Index health check failed: ${err.message}`);
-  }
-
-  // ── 6. GitHub auth verification (C4) ──
-  try {
-    const authStatus = github.ensureAuth(projectDir);
-    if (!authStatus.ok) {
-      blockers.push(`GitHub auth: ${authStatus.error}`);
-    }
-  } catch (err) {
-    warnings.push(`GitHub auth check failed: ${err.message}`);
-  }
-
-  // ── 7. Temp file cleanup (B3) ──
-  try {
-    const tempFiles = [
-      '_current_prompt.md.tmp',
-      'state.json.tmp',
-      'tasks.json.tmp',
-    ];
-    for (const tmpName of tempFiles) {
-      const tmpPath = resolve(copilotDir, tmpName);
-      if (existsSync(tmpPath)) {
-        unlinkSync(tmpPath);
-        repairs.push(`Cleaned up temp file: ${tmpName}`);
-      }
-    }
-  } catch { /* non-critical */ }
-
-  // ── 8. Disk space check (B4) ──
-  try {
-    const probePath = resolve(copilotDir, '.disk_probe');
-    writeFileSync(probePath, 'probe');
-    unlinkSync(probePath);
-  } catch (err) {
-    if (err.code === 'ENOSPC' || err.code === 'EDQUOT') {
-      blockers.push('Disk full — cannot write to project directory. Free up space before running.');
-    } else if (err.code === 'EACCES' || err.code === 'EPERM') {
-      blockers.push(`Permission denied writing to ${copilotDir}. Check directory permissions.`);
-    }
-    // Other errors are non-critical (e.g., copilotDir doesn't exist yet)
-  }
-
-  // ── 9. File permissions check (B5) ──
-  try {
-    const criticalFiles = ['tasks.json', 'state.json', 'config.json'];
-    for (const fileName of criticalFiles) {
-      const filePath = resolve(copilotDir, fileName);
-      if (existsSync(filePath)) {
-        try {
-          // Verify write access
-          accessSync(filePath, constants.R_OK | constants.W_OK);
-        } catch (permErr) {
-          if (permErr.code === 'EACCES' || permErr.code === 'EPERM') {
-            blockers.push(`No read/write permission on ${fileName}. Fix with: chmod 644 ${filePath}`);
-          }
-        }
-      }
-    }
-  } catch { /* non-critical */ }
-
-  // ── 10. Task/Checkpoint consistency (E1, E4) ──
-  if (options.checkpoint && options.tasks) {
-    try {
-      const consistency = options.checkpoint.validateConsistency(options.tasks);
-      if (!consistency.ok) {
-        repairs.push(...consistency.repairs);
-        // Write back repaired tasks
-        const tasksPath = resolve(copilotDir, 'tasks.json');
-        writeJSON(tasksPath, options.tasks);
-      }
-    } catch (err) {
-      warnings.push(`Consistency check failed: ${err.message}`);
-    }
-  }
-
-  // ── Report ──
-  if (repairs.length > 0) {
-    log.info(`🔧 Pre-flight: ${repairs.length} issue(s) auto-repaired`);
-    for (const r of repairs) {
-      log.dim(`   ✅ ${r}`);
-    }
-  }
-
-  if (warnings.length > 0) {
-    for (const w of warnings) {
-      log.warn(`   ⚠ ${w}`);
-    }
-  }
-
-  if (blockers.length > 0) {
-    for (const b of blockers) {
-      log.error(`   🛑 ${b}`);
-    }
-  }
-
-  if (repairs.length === 0 && warnings.length === 0 && blockers.length === 0) {
-    log.dim('Pre-flight: all checks passed ✓');
-  }
-
-  return { ok: blockers.length === 0, repairs, warnings, blockers };
-}
-
-/**
- * Layer 3: Phase entry validation — called before each automation phase.
- *
- * Ensures the environment is in the correct state for the target phase:
- *   - develop: correct branch, clean-enough index
- *   - pr:      has diff to commit, network is reachable
- *   - review:  PR exists and is in 'open' state
- *   - merge:   PR is approved or at least not rejected
- *
- * @param {string} projectDir - Project root
- * @param {object} task - Current task object
- * @param {object} checkpoint - Checkpoint manager
- * @param {string} targetPhase - 'develop' | 'pr' | 'review' | 'merge'
- * @param {object} [extra] - Extra context (e.g., prInfo for review/merge)
- * @returns {{ ok: boolean, error: string|null }}
- */
-export function validatePhaseEntry(projectDir, task, checkpoint, targetPhase, extra = {}) {
-  try {
-    switch (targetPhase) {
-      case 'develop': {
-        // Verify we can identify current branch (not detached)
-        const current = git.currentBranch(projectDir);
-        if (!current) {
-          git.recoverDetachedHead(projectDir);
-          const recovered = git.currentBranch(projectDir);
-          if (!recovered) {
-            return { ok: false, error: 'Cannot determine current branch (detached HEAD, recovery failed)' };
-          }
-        }
-        return { ok: true, error: null };
-      }
-
-      case 'pr': {
-        // Verify we're on the task's feature branch
-        const current = git.currentBranch(projectDir);
-        if (current !== task.branch) {
-          return { ok: false, error: `Expected branch '${task.branch}' but on '${current}'` };
-        }
-        return { ok: true, error: null };
-      }
-
-      case 'review': {
-        // Verify PR exists and is open
-        if (!extra.prNumber) {
-          return { ok: false, error: 'No PR number available for review phase' };
-        }
-        const prState = github.getPRState(projectDir, extra.prNumber);
-        if (prState === 'merged') {
-          return { ok: false, error: `PR #${extra.prNumber} is already merged` };
-        }
-        if (prState === 'closed') {
-          return { ok: false, error: `PR #${extra.prNumber} was closed — needs re-creation` };
-        }
-        return { ok: true, error: null };
-      }
-
-      case 'merge': {
-        // Verify PR is in a mergeable state
-        if (!extra.prNumber) {
-          return { ok: false, error: 'No PR number available for merge phase' };
-        }
-        const prState = github.getPRState(projectDir, extra.prNumber);
-        if (prState === 'merged') {
-          // Already merged — this is fine, skip merge
-          return { ok: true, error: null };
-        }
-        if (prState === 'closed') {
-          return { ok: false, error: `PR #${extra.prNumber} is closed — cannot merge` };
-        }
-        return { ok: true, error: null };
-      }
-
-      default:
-        return { ok: true, error: null };
-    }
-  } catch (err) {
-    return { ok: false, error: `Phase validation error: ${err.message}` };
-  }
-}
-
-/**
- * Remove the PID lock file (called on clean exit).
- */
-export function releaseLock(projectDir) {
-  const pidPath = resolve(projectDir, '.codex-copilot/.pid');
-  try {
-    if (existsSync(pidPath)) {
-      unlinkSync(pidPath);
-    }
-  } catch { /* best effort */ }
-}
-
-export const selfHeal = {
-  preFlightCheck,
-  validatePhaseEntry,
-  releaseLock,
-};
+/**
+ * Self-Healing Module — Unified recovery and health check entry point
+ *
+ * Layer 3-4 of the self-healing architecture:
+ *   - preFlightCheck():      Full environment validation before run
+ *   - validatePhaseEntry():  Phase-specific guard before each phase starts
+ *
+ * Uses Layer 2 building blocks from git.js and github.js.
+ */
+
+import { existsSync, writeFileSync, readFileSync, unlinkSync, accessSync, constants } from 'fs';
+import { resolve } from 'path';
+import { git } from './git.js';
+import { github } from './github.js';
+import { log } from './logger.js';
+import { readJSON, writeJSON } from './json.js';
+
+/**
+ * Layer 4: Pre-flight health check — run before starting the automation loop.
+ *
+ * Performs comprehensive environment validation and auto-repairs:
+ *   1. Concurrent execution lock (PID file)
+ *   2. Git lock file cleanup
+ *   3. Detached HEAD recovery
+ *   4. Orphaned stash detection
+ *   5. Git repository integrity
+ *   6. GitHub auth verification
+ *   7. Temp file cleanup
+ *   8. Task/Checkpoint consistency validation
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {string} baseBranch - Base branch name (e.g., 'main')
+ * @param {object} [options]
+ * @param {object} [options.checkpoint] - Checkpoint manager instance
+ * @param {object} [options.tasks] - Tasks data from tasks.json
+ * @returns {{ ok: boolean, repairs: string[], warnings: string[], blockers: string[] }}
+ */
+export function preFlightCheck(projectDir, baseBranch, options = {}) {
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  const repairs = [];
+  const warnings = [];
+  const blockers = [];
+
+  log.dim('Running pre-flight health check...');
+
+  // ── 1. Concurrent execution lock (D3) ──
+  const pidPath = resolve(copilotDir, '.pid');
+  if (existsSync(pidPath)) {
+    try {
+      const pidContent = readFileSync(pidPath, 'utf-8').trim();
+      const [pid, startTime] = pidContent.split(':');
+      const pidNum = parseInt(pid, 10);
+
+      // Check if the process is still running
+      let isRunning = false;
+      try {
+        process.kill(pidNum, 0); // Signal 0: check if process exists
+        isRunning = true;
+      } catch {
+        isRunning = false; // Process doesn't exist
+      }
+
+      if (isRunning) {
+        const age = startTime ? Math.round((Date.now() - parseInt(startTime, 10)) / 1000) : 0;
+        blockers.push(`Another codex-copilot instance is running (PID: ${pidNum}, age: ${age}s). Kill it first or wait.`);
+      } else {
+        // Stale PID file — remove it
+        unlinkSync(pidPath);
+        repairs.push('Removed stale PID lock file from crashed process');
+      }
+    } catch {
+      // Can't read PID file — remove it
+      try { unlinkSync(pidPath); } catch {}
+      repairs.push('Removed unreadable PID lock file');
+    }
+  }
+
+  // Write our PID (even if there are other blockers, we need to own the lock)
+  if (blockers.length === 0) {
+    try {
+      writeFileSync(pidPath, `${process.pid}:${Date.now()}`);
+    } catch { /* non-critical */ }
+  }
+
+  // ── 2. Git lock file cleanup (A2) ──
+  try {
+    const removedLocks = git.clearStaleLocks(projectDir);
+    if (removedLocks.length > 0) {
+      repairs.push(`Cleared ${removedLocks.length} stale git lock file(s): ${removedLocks.join(', ')}`);
+    }
+  } catch (err) {
+    warnings.push(`Lock file check failed: ${err.message}`);
+  }
+
+  // ── 3. Detached HEAD recovery (A3) ──
+  try {
+    const recovered = git.recoverDetachedHead(projectDir);
+    if (recovered) {
+      repairs.push(`Recovered from detached HEAD → ${recovered}`);
+    }
+  } catch (err) {
+    warnings.push(`Detached HEAD check failed: ${err.message}`);
+  }
+
+  // ── 4. Orphaned stash detection (A4) ──
+  try {
+    const stashStatus = git.checkOrphanedStash(projectDir);
+    if (stashStatus.found) {
+      warnings.push(`${stashStatus.count} stash entry(s) found — run 'git stash list' to inspect`);
+    }
+  } catch (err) {
+    // Non-critical
+  }
+
+  // ── 5. Git index health (A1) ──
+  try {
+    const gitDir = resolve(projectDir, '.git');
+    const hasRebase = existsSync(resolve(gitDir, 'rebase-merge')) || existsSync(resolve(gitDir, 'rebase-apply'));
+    const hasMerge = existsSync(resolve(gitDir, 'MERGE_HEAD'));
+    const hasCherryPick = existsSync(resolve(gitDir, 'CHERRY_PICK_HEAD'));
+
+    if (hasRebase || hasMerge || hasCherryPick) {
+      git.resolveIndex(projectDir);
+      const operations = [];
+      if (hasRebase) operations.push('rebase');
+      if (hasMerge) operations.push('merge');
+      if (hasCherryPick) operations.push('cherry-pick');
+      repairs.push(`Resolved stuck git operation(s): ${operations.join(', ')}`);
+    }
+  } catch (err) {
+    warnings.push(`Index health check failed: ${err.message}`);
+  }
+
+  // ── 6. GitHub auth verification (C4) ──
+  try {
+    const authStatus = github.ensureAuth(projectDir);
+    if (!authStatus.ok) {
+      blockers.push(`GitHub auth: ${authStatus.error}`);
+    }
+  } catch (err) {
+    warnings.push(`GitHub auth check failed: ${err.message}`);
+  }
+
+  // ── 7. Temp file cleanup (B3) ──
+  try {
+    const tempFiles = [
+      '_current_prompt.md.tmp',
+      'state.json.tmp',
+      'tasks.json.tmp',
+    ];
+    for (const tmpName of tempFiles) {
+      const tmpPath = resolve(copilotDir, tmpName);
+      if (existsSync(tmpPath)) {
+        unlinkSync(tmpPath);
+        repairs.push(`Cleaned up temp file: ${tmpName}`);
+      }
+    }
+  } catch { /* non-critical */ }
+
+  // ── 8. Disk space check (B4) ──
+  try {
+    const probePath = resolve(copilotDir, '.disk_probe');
+    writeFileSync(probePath, 'probe');
+    unlinkSync(probePath);
+  } catch (err) {
+    if (err.code === 'ENOSPC' || err.code === 'EDQUOT') {
+      blockers.push('Disk full — cannot write to project directory. Free up space before running.');
+    } else if (err.code === 'EACCES' || err.code === 'EPERM') {
+      blockers.push(`Permission denied writing to ${copilotDir}. Check directory permissions.`);
+    }
+    // Other errors are non-critical (e.g., copilotDir doesn't exist yet)
+  }
+
+  // ── 9. File permissions check (B5) ──
+  try {
+    const criticalFiles = ['tasks.json', 'state.json', 'config.json'];
+    for (const fileName of criticalFiles) {
+      const filePath = resolve(copilotDir, fileName);
+      if (existsSync(filePath)) {
+        try {
+          // Verify write access
+          accessSync(filePath, constants.R_OK | constants.W_OK);
+        } catch (permErr) {
+          if (permErr.code === 'EACCES' || permErr.code === 'EPERM') {
+            blockers.push(`No read/write permission on ${fileName}. Fix with: chmod 644 ${filePath}`);
+          }
+        }
+      }
+    }
+  } catch { /* non-critical */ }
+
+  // ── 10. Task/Checkpoint consistency (E1, E4) ──
+  if (options.checkpoint && options.tasks) {
+    try {
+      const consistency = options.checkpoint.validateConsistency(options.tasks);
+      if (!consistency.ok) {
+        repairs.push(...consistency.repairs);
+        // Write back repaired tasks
+        const tasksPath = resolve(copilotDir, 'tasks.json');
+        writeJSON(tasksPath, options.tasks);
+      }
+    } catch (err) {
+      warnings.push(`Consistency check failed: ${err.message}`);
+    }
+  }
+
+  // ── Report ──
+  if (repairs.length > 0) {
+    log.info(`🔧 Pre-flight: ${repairs.length} issue(s) auto-repaired`);
+    for (const r of repairs) {
+      log.dim(`   ✅ ${r}`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    for (const w of warnings) {
+      log.warn(`   ⚠ ${w}`);
+    }
+  }
+
+  if (blockers.length > 0) {
+    for (const b of blockers) {
+      log.error(`   🛑 ${b}`);
+    }
+  }
+
+  if (repairs.length === 0 && warnings.length === 0 && blockers.length === 0) {
+    log.dim('Pre-flight: all checks passed ✓');
+  }
+
+  return { ok: blockers.length === 0, repairs, warnings, blockers };
+}
+
+/**
+ * Layer 3: Phase entry validation — called before each automation phase.
+ *
+ * Ensures the environment is in the correct state for the target phase:
+ *   - develop: correct branch, clean-enough index
+ *   - pr:      has diff to commit, network is reachable
+ *   - review:  PR exists and is in 'open' state
+ *   - merge:   PR is approved or at least not rejected
+ *
+ * @param {string} projectDir - Project root
+ * @param {object} task - Current task object
+ * @param {object} checkpoint - Checkpoint manager
+ * @param {string} targetPhase - 'develop' | 'pr' | 'review' | 'merge'
+ * @param {object} [extra] - Extra context (e.g., prInfo for review/merge)
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function validatePhaseEntry(projectDir, task, checkpoint, targetPhase, extra = {}) {
+  try {
+    switch (targetPhase) {
+      case 'develop': {
+        // Verify we can identify current branch (not detached)
+        const current = git.currentBranch(projectDir);
+        if (!current) {
+          git.recoverDetachedHead(projectDir);
+          const recovered = git.currentBranch(projectDir);
+          if (!recovered) {
+            return { ok: false, error: 'Cannot determine current branch (detached HEAD, recovery failed)' };
+          }
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'pr': {
+        // Verify we're on the task's feature branch
+        const current = git.currentBranch(projectDir);
+        if (current !== task.branch) {
+          return { ok: false, error: `Expected branch '${task.branch}' but on '${current}'` };
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'review': {
+        // Verify PR exists and is open
+        if (!extra.prNumber) {
+          return { ok: false, error: 'No PR number available for review phase' };
+        }
+        const prState = github.getPRState(projectDir, extra.prNumber);
+        if (prState === 'merged') {
+          return { ok: false, error: `PR #${extra.prNumber} is already merged` };
+        }
+        if (prState === 'closed') {
+          return { ok: false, error: `PR #${extra.prNumber} was closed — needs re-creation` };
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'merge': {
+        // Verify PR is in a mergeable state
+        if (!extra.prNumber) {
+          return { ok: false, error: 'No PR number available for merge phase' };
+        }
+        const prState = github.getPRState(projectDir, extra.prNumber);
+        if (prState === 'merged') {
+          // Already merged — this is fine, skip merge
+          return { ok: true, error: null };
+        }
+        if (prState === 'closed') {
+          return { ok: false, error: `PR #${extra.prNumber} is closed — cannot merge` };
+        }
+        return { ok: true, error: null };
+      }
+
+      default:
+        return { ok: true, error: null };
+    }
+  } catch (err) {
+    return { ok: false, error: `Phase validation error: ${err.message}` };
+  }
+}
+
+/**
+ * Remove the PID lock file (called on clean exit).
+ */
+export function releaseLock(projectDir) {
+  const pidPath = resolve(projectDir, '.codex-copilot/.pid');
+  try {
+    if (existsSync(pidPath)) {
+      unlinkSync(pidPath);
+    }
+  } catch { /* best effort */ }
+}
+
+export const selfHeal = {
+  preFlightCheck,
+  validatePhaseEntry,
+  releaseLock,
+};