jettypod 4.1.2 → 4.1.4

package/lib/worktree-facade.js

@@ -0,0 +1,174 @@
+/**
+ * Worktree Facade - Graceful Degradation Layer
+ *
+ * This module provides a high-level API for worktree operations with graceful
+ * fallback when worktree operations fail. It wraps the worktree-manager module
+ * and provides fallback to working in the main repository.
+ *
+ * Key principles:
+ * - Never fail the entire operation if worktree creation fails
+ * - Fall back to main repository when worktrees don't work
+ * - Provide clear feedback about what mode we're in (worktree vs main)
+ * - Preserve all error information for debugging
+ */
+
+const worktreeManager = require('./worktree-manager');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Start work on a work item with graceful degradation
+ *
+ * Attempts to create a worktree. If that fails, falls back to main repository.
+ *
+ * @param {Object} workItem - Work item from database (must have id and title)
+ * @param {Object} options - Optional configuration
+ * @param {string} options.repoPath - Path to git repository (defaults to process.cwd())
+ * @param {Object} options.db - Database connection (defaults to global database)
+ * @returns {Promise<Object>} Result object with mode ('worktree' or 'main'), path, worktree record (if applicable), and any errors
+ */
+async function startWork(workItem, options = {}) {
+  if (!workItem || !workItem.id) {
+    return Promise.reject(new Error('Invalid work item: must have id'));
+  }
+
+  const repoPath = options.repoPath || process.cwd();
+  const result = {
+    mode: null,           // 'worktree' or 'main'
+    path: null,           // Working directory path
+    worktree: null,       // Worktree record (if mode='worktree')
+    error: null,          // Error that caused fallback (if mode='main')
+    warnings: []          // Non-fatal warnings
+  };
+
+  // Attempt to create worktree
+  try {
+    const worktree = await worktreeManager.createWorktree(workItem, options);
+
+    // Verify the worktree path exists and is accessible
+    if (!fs.existsSync(worktree.worktree_path)) {
+      throw new Error(`Worktree directory was not created: ${worktree.worktree_path}`);
+    }
+
+    // Success! Return worktree mode
+    result.mode = 'worktree';
+    result.path = worktree.worktree_path;
+    result.worktree = worktree;
+    return result;
+
+  } catch (err) {
+    // Worktree creation failed - fall back to main repository
+    result.mode = 'main';
+    result.path = repoPath;
+    result.error = {
+      message: err.message,
+      stack: err.stack,
+      reason: 'worktree_creation_failed'
+    };
+    result.warnings.push('Worktree creation failed - using main repository instead');
+
+    return result;
+  }
+}
+
+/**
+ * Stop work on a work item with graceful degradation
+ *
+ * Attempts to cleanup worktree. If that fails, marks as corrupted and continues.
+ *
+ * @param {number} worktreeId - Worktree ID (can be null if working in main)
+ * @param {Object} options - Optional configuration
+ * @param {string} options.repoPath - Path to git repository (defaults to process.cwd())
+ * @param {Object} options.db - Database connection (defaults to global database)
+ * @param {boolean} options.deleteBranch - Whether to delete the branch (defaults to false)
+ * @returns {Promise<Object>} Result object with success status, any errors, and warnings
+ */
+async function stopWork(worktreeId, options = {}) {
+  // If no worktree ID, we were working in main - nothing to cleanup
+  if (!worktreeId) {
+    return {
+      success: true,
+      mode: 'main',
+      message: 'No worktree to cleanup (was working in main repository)'
+    };
+  }
+
+  const result = {
+    success: false,
+    mode: 'worktree',
+    error: null,
+    warnings: []
+  };
+
+  try {
+    await worktreeManager.cleanupWorktree(worktreeId, options);
+    result.success = true;
+    return result;
+
+  } catch (err) {
+    // Cleanup failed - surface the error to the user
+    result.error = {
+      message: err.message,
+      stack: err.stack,
+      reason: 'worktree_cleanup_failed'
+    };
+
+    // Check if it's a "directory in use" error
+    if (err.message.includes('Failed to remove worktree directory')) {
+      result.error.userMessage =
+        'Cannot cleanup worktree - files may still be in use by running tests or processes.\n' +
+        'Please wait for background processes to finish and try again.';
+    }
+
+    result.success = false;
+    return result;
+  }
+}
+
+/**
+ * Get the current working mode for a work item
+ *
+ * Checks if there's an active worktree for the work item.
+ *
+ * @param {number} workItemId - Work item ID
+ * @param {Object} options - Optional configuration
+ * @param {Object} options.db - Database connection (defaults to global database)
+ * @returns {Promise<Object>} Result object with mode, worktree record (if applicable)
+ */
+async function getWorkingMode(workItemId, options = {}) {
+  try {
+    const worktree = await worktreeManager.getWorktreeForWorkItem(workItemId, options);
+
+    if (worktree && worktree.status === 'active') {
+      return {
+        mode: 'worktree',
+        worktree: worktree,
+        path: worktree.worktree_path
+      };
+    }
+
+    return {
+      mode: 'main',
+      worktree: null,
+      path: options.repoPath || process.cwd()
+    };
+
+  } catch (err) {
+    // If we can't determine mode, assume main (safer fallback)
+    return {
+      mode: 'main',
+      worktree: null,
+      path: options.repoPath || process.cwd(),
+      error: {
+        message: err.message,
+        reason: 'mode_detection_failed'
+      }
+    };
+  }
+}
+
+module.exports = {
+  startWork,
+  stopWork,
+  getWorkingMode
+};