jettypod 4.1.2 → 4.1.4

package/lib/merge-lock.js

@@ -0,0 +1,193 @@
+/**
+ * Merge Lock - Coordination for Concurrent Instances
+ *
+ * This module provides lock acquisition and release for merge operations
+ * to prevent simultaneous access to main branch across multiple Claude Code instances.
+ *
+ * Core principles:
+ * - Database is coordination point (simple, reliable serialization)
+ * - Polling mechanism with exponential backoff
+ * - Automatic cleanup with release() function
+ * - Queue position awareness for UX
+ */
+
+const os = require('os');
+
+/**
+ * Acquire merge lock for a work item
+ *
+ * @param {Object} db - SQLite database connection
+ * @param {number} workItemId - Work item ID attempting merge
+ * @param {string} instanceId - Optional custom instance identifier
+ * @param {Object} options - Optional configuration
+ * @param {number} options.maxWait - Maximum wait time in ms (default: 60000)
+ * @param {number} options.pollInterval - Poll interval in ms (default: 1500)
+ * @returns {Promise<Object>} Lock handle with id, locked_by, work_item_id, release()
+ * @throws {Error} If lock cannot be acquired within maxWait
+ */
+async function acquireMergeLock(db, workItemId, instanceId = null, options = {}) {
+  if (!db) {
+    throw new Error('Database connection required');
+  }
+
+  if (!workItemId || typeof workItemId !== 'number') {
+    throw new Error('Invalid work item ID: must be a number');
+  }
+
+  const maxWait = options.maxWait || 60000; // 1 minute default
+  const pollInterval = options.pollInterval || 1500; // 1.5 seconds
+  const startTime = Date.now();
+
+  // Generate instance identifier
+  const lockedBy = instanceId || `${os.hostname()}-${process.pid}`;
+
+  while (Date.now() - startTime < maxWait) {
+    // Check if lock exists
+    const existingLock = await checkExistingLock(db);
+
+    if (!existingLock) {
+      // Try to acquire lock
+      try {
+        const lockId = await insertLock(db, workItemId, lockedBy);
+
+        // Return lock handle with release function
+        return createLockHandle(db, lockId, lockedBy, workItemId);
+      } catch (err) {
+        // Race condition - someone else got it first
+        // Continue polling
+      }
+    }
+
+    // Wait before retrying
+    await sleep(pollInterval);
+  }
+
+  throw new Error(`Lock acquisition timeout after ${maxWait}ms`);
+}
+
+/**
+ * Check if any merge lock currently exists
+ *
+ * @param {Object} db - SQLite database connection
+ * @returns {Promise<Object|null>} Existing lock or null
+ */
+function checkExistingLock(db) {
+  return new Promise((resolve, reject) => {
+    db.get('SELECT * FROM merge_locks LIMIT 1', (err, row) => {
+      if (err) reject(err);
+      else resolve(row || null);
+    });
+  });
+}
+
+/**
+ * Insert lock record into database
+ *
+ * @param {Object} db - SQLite database connection
+ * @param {number} workItemId - Work item ID
+ * @param {string} lockedBy - Instance identifier
+ * @returns {Promise<number>} Lock ID
+ */
+function insertLock(db, workItemId, lockedBy) {
+  return new Promise((resolve, reject) => {
+    db.run(
+      `INSERT INTO merge_locks (locked_by, work_item_id, operation)
+       VALUES (?, ?, 'merging')`,
+      [lockedBy, workItemId],
+      function(err) {
+        if (err) reject(err);
+        else resolve(this.lastID);
+      }
+    );
+  });
+}
+
+/**
+ * Create lock handle object with release function
+ *
+ * @param {Object} db - SQLite database connection
+ * @param {number} lockId - Lock ID
+ * @param {string} lockedBy - Instance identifier
+ * @param {number} workItemId - Work item ID
+ * @returns {Object} Lock handle
+ */
+function createLockHandle(db, lockId, lockedBy, workItemId) {
+  return {
+    id: lockId,
+    locked_by: lockedBy,
+    work_item_id: workItemId,
+    release: async () => {
+      try {
+        if (!db || typeof db.run !== 'function') {
+          throw new Error('Database connection unavailable during release');
+        }
+
+        await new Promise((resolve, reject) => {
+          db.run('DELETE FROM merge_locks WHERE id = ?', [lockId], (err) => {
+            if (err) {
+              // Enhance error message for common issues
+              if (err.message && err.message.includes('Database is closed')) {
+                reject(new Error('Database connection unavailable during release'));
+              } else {
+                reject(err);
+              }
+            } else {
+              resolve();
+            }
+          });
+        });
+      } catch (err) {
+        // Log error but don't crash - lock may have already been cleaned up
+        // or database may be unavailable. In production, consider:
+        // - Logging to error tracking system
+        // - Alerting on repeated failures
+        // - Background cleanup task to handle orphaned locks
+        console.error(`Failed to release lock ${lockId}:`, err.message);
+        throw err; // Re-throw so caller knows release failed
+      }
+    }
+  };
+}
+
+/**
+ * Clean up stale locks older than threshold
+ *
+ * @param {Object} db - SQLite database connection
+ * @param {Object} options - Optional configuration
+ * @param {number} options.staleThreshold - Age threshold in ms (default: 300000 = 5 minutes)
+ * @returns {Promise<number>} Count of locks removed
+ */
+async function cleanupStaleLocks(db, options = {}) {
+  if (!db) {
+    throw new Error('Database connection required');
+  }
+
+  const staleThreshold = options.staleThreshold || 300000; // 5 minutes default
+  const staleTime = new Date(Date.now() - staleThreshold).toISOString();
+
+  return new Promise((resolve, reject) => {
+    db.run(
+      'DELETE FROM merge_locks WHERE locked_at < ?',
+      [staleTime],
+      function(err) {
+        if (err) reject(err);
+        else resolve(this.changes); // Return count of deleted locks
+      }
+    );
+  });
+}
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  acquireMergeLock,
+  cleanupStaleLocks
+};

package/lib/migrations/012-add-worktree-path.js

@@ -0,0 +1,38 @@
+/**
+ * Migration: Add worktree_path column to work_items table
+ *
+ * Purpose: Track the filesystem path to the git worktree for each work item.
+ * This enables:
+ * - Multiple Claude instances to work on different items in parallel
+ * - Proper worktree cleanup after merge
+ * - Worktree-based conflict detection
+ */
+
+module.exports = {
+  id: '012-add-worktree-path',
+  description: 'Add worktree_path column to work_items table',
+
+  async up(db) {
+    return new Promise((resolve, reject) => {
+      db.run(`
+        ALTER TABLE work_items
+        ADD COLUMN worktree_path TEXT
+      `, (err) => {
+        if (err) {
+          // Column might already exist - ignore error
+          if (err.message.includes('duplicate column')) {
+            return resolve();
+          }
+          return reject(err);
+        }
+        resolve();
+      });
+    });
+  },
+
+  async down(db) {
+    // SQLite doesn't support DROP COLUMN before version 3.35.0
+    // We'll just leave the column - it's harmless if unused
+    return Promise.resolve();
+  }
+};

package/lib/migrations/013-worktrees-table.js

@@ -0,0 +1,86 @@
+/**
+ * Migration: Create worktrees table
+ *
+ * Purpose: Establish database as single source of truth for worktree state.
+ * This table tracks all worktrees with their branch names, paths, and status.
+ *
+ * Why this is critical:
+ * - Never lose track of branch names (even if worktree directory deleted)
+ * - Enable state reconciliation between DB, git, and filesystem
+ * - Track worktree lifecycle with status field
+ * - Support multiple worktrees per work item (for retries/recovery)
+ */
+
+module.exports = {
+  id: '013-worktrees-table',
+  description: 'Create worktrees table for bulletproof worktree state tracking',
+
+  async up(db) {
+    return new Promise((resolve, reject) => {
+      db.run(`
+        CREATE TABLE IF NOT EXISTS worktrees (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          work_item_id INTEGER NOT NULL,
+          branch_name TEXT NOT NULL,
+          worktree_path TEXT NOT NULL,
+          status TEXT NOT NULL CHECK(status IN ('active', 'merging', 'cleanup_pending', 'corrupted')),
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+          FOREIGN KEY (work_item_id) REFERENCES work_items(id)
+        )
+      `, (err) => {
+        if (err) {
+          return reject(err);
+        }
+
+        // Create index on work_item_id for fast lookups
+        db.run(`
+          CREATE INDEX IF NOT EXISTS idx_worktrees_work_item_id
+          ON worktrees(work_item_id)
+        `, (err) => {
+          if (err) {
+            return reject(err);
+          }
+
+          // Create index on status for querying active/corrupted worktrees
+          db.run(`
+            CREATE INDEX IF NOT EXISTS idx_worktrees_status
+            ON worktrees(status)
+          `, (err) => {
+            if (err) {
+              return reject(err);
+            }
+
+            resolve();
+          });
+        });
+      });
+    });
+  },
+
+  async down(db) {
+    return new Promise((resolve, reject) => {
+      // Drop indexes first
+      db.run('DROP INDEX IF EXISTS idx_worktrees_status', (err) => {
+        if (err) {
+          return reject(err);
+        }
+
+        db.run('DROP INDEX IF EXISTS idx_worktrees_work_item_id', (err) => {
+          if (err) {
+            return reject(err);
+          }
+
+          // Drop table
+          db.run('DROP TABLE IF EXISTS worktrees', (err) => {
+            if (err) {
+              return reject(err);
+            }
+
+            resolve();
+          });
+        });
+      });
+    });
+  }
+};

package/lib/migrations/014-migrate-worktree-data.js

@@ -0,0 +1,161 @@
+/**
+ * Migration: Migrate existing worktree_path data to worktrees table
+ *
+ * Purpose: Migrate existing work_items.worktree_path data to the new worktrees table.
+ * This preserves existing worktree state during the transition to the new architecture.
+ *
+ * Strategy:
+ * - For each work item with worktree_path:
+ *   - Check if directory exists
+ *   - Try to discover branch name via git
+ *   - Create worktrees entry with appropriate status (active/corrupted)
+ * - Handle errors gracefully - one corrupted worktree should not fail entire migration
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+module.exports = {
+  id: '014-migrate-worktree-data',
+  description: 'Migrate existing worktree_path data from work_items to worktrees table',
+
+  async up(db) {
+    return new Promise((resolve, reject) => {
+      // Get all work items with worktree_path set
+      db.all('SELECT id, worktree_path FROM work_items WHERE worktree_path IS NOT NULL', async (err, workItems) => {
+        if (err) {
+          return reject(err);
+        }
+
+        if (!workItems || workItems.length === 0) {
+          // No work items with worktrees - nothing to migrate
+          return resolve();
+        }
+
+        console.log(`\nMigrating ${workItems.length} worktree(s) to new worktrees table...`);
+
+        // Process each work item
+        const migrations = [];
+        for (const workItem of workItems) {
+          migrations.push(migrateWorkItemWorktree(db, workItem));
+        }
+
+        try {
+          await Promise.all(migrations);
+          console.log('✓ Worktree data migration complete\n');
+          resolve();
+        } catch (migrateErr) {
+          // Even if some migrations failed, we continue (logged individual errors)
+          console.log('⚠️  Some worktrees could not be migrated (marked as corrupted)\n');
+          resolve();
+        }
+      });
+    });
+  },
+
+  async down(db) {
+    return new Promise((resolve, reject) => {
+      // Get all work items that originally had worktree_path
+      db.all('SELECT id FROM work_items WHERE worktree_path IS NOT NULL', (err, workItems) => {
+        if (err) {
+          return reject(err);
+        }
+
+        if (!workItems || workItems.length === 0) {
+          return resolve();
+        }
+
+        const workItemIds = workItems.map(w => w.id);
+
+        // Delete worktree entries for these work items
+        const placeholders = workItemIds.map(() => '?').join(',');
+        db.run(`DELETE FROM worktrees WHERE work_item_id IN (${placeholders})`, workItemIds, (err) => {
+          if (err) {
+            return reject(err);
+          }
+          resolve();
+        });
+      });
+    });
+  }
+};
+
+/**
+ * Migrate a single work item's worktree to the worktrees table
+ */
+async function migrateWorkItemWorktree(db, workItem) {
+  const { id: workItemId, worktree_path: worktreePath } = workItem;
+
+  return new Promise(async (resolve) => {
+    try {
+      // Check if directory exists
+      const dirExists = fs.existsSync(worktreePath);
+
+      let branchName = 'unknown';
+      let status = 'corrupted';
+
+      if (dirExists) {
+        // Check if this is actually a git repository (has .git file or directory)
+        const gitPath = path.join(worktreePath, '.git');
+        const hasGit = fs.existsSync(gitPath);
+
+        if (!hasGit) {
+          console.log(`  ⚠️  Work item #${workItemId}: Directory exists but no .git found (not a git worktree)`);
+        } else {
+          // Try to discover branch name
+          try {
+            const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+              cwd: worktreePath,
+              encoding: 'utf8',
+              stdio: 'pipe'
+            }).trim();
+
+            if (branch && branch !== 'HEAD') {
+              branchName = branch;
+              status = 'active';
+            } else {
+              console.log(`  ⚠️  Work item #${workItemId}: Could not determine branch (detached HEAD)`);
+            }
+          } catch (gitErr) {
+            // Git command failed - worktree is corrupted
+            console.log(`  ⚠️  Work item #${workItemId}: Git command failed - ${gitErr.message}`);
+          }
+        }
+      } else {
+        console.log(`  ⚠️  Work item #${workItemId}: Worktree directory does not exist: ${worktreePath}`);
+      }
+
+      // Check if entry already exists (idempotency)
+      db.get('SELECT id FROM worktrees WHERE work_item_id = ?', [workItemId], (err, existing) => {
+        if (err) {
+          console.error(`  ❌ Work item #${workItemId}: Database error - ${err.message}`);
+          return resolve(); // Continue with other migrations
+        }
+
+        if (existing) {
+          // Entry already exists - skip
+          return resolve();
+        }
+
+        // Insert into worktrees table
+        db.run(`
+          INSERT INTO worktrees (work_item_id, branch_name, worktree_path, status)
+          VALUES (?, ?, ?, ?)
+        `, [workItemId, branchName, worktreePath, status], (insertErr) => {
+          if (insertErr) {
+            console.error(`  ❌ Work item #${workItemId}: Failed to insert - ${insertErr.message}`);
+          } else if (status === 'active') {
+            console.log(`  ✓ Work item #${workItemId}: Migrated as active (branch: ${branchName})`);
+          } else {
+            console.log(`  ⚠️  Work item #${workItemId}: Migrated as corrupted`);
+          }
+          resolve();
+        });
+      });
+    } catch (err) {
+      console.error(`  ❌ Work item #${workItemId}: Unexpected error - ${err.message}`);
+      resolve(); // Continue with other migrations
+    }
+  });
+}

package/lib/migrations/015-merge-locks-table.js

@@ -0,0 +1,67 @@
+/**
+ * Migration: Create merge_locks table
+ *
+ * Purpose: Enable coordination between multiple Claude Code instances during
+ * merge operations to prevent simultaneous access to main branch.
+ *
+ * Why this is critical:
+ * - Serialize merge operations across concurrent instances
+ * - Prevent git conflicts from simultaneous main branch access
+ * - Track which instance holds the merge lock
+ * - Support queue position awareness for better UX
+ */
+
+module.exports = {
+  id: '015-merge-locks-table',
+  description: 'Create merge_locks table for concurrent instance coordination',
+
+  async up(db) {
+    return new Promise((resolve, reject) => {
+      db.run(`
+        CREATE TABLE IF NOT EXISTS merge_locks (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          locked_by TEXT NOT NULL,
+          locked_at TEXT NOT NULL DEFAULT (datetime('now')),
+          operation TEXT NOT NULL DEFAULT 'merging',
+          work_item_id INTEGER NOT NULL
+        )
+      `, (err) => {
+        if (err) {
+          return reject(err);
+        }
+
+        // Create index on locked_at for queue position queries
+        db.run(`
+          CREATE INDEX IF NOT EXISTS idx_merge_locks_locked_at
+          ON merge_locks(locked_at)
+        `, (err) => {
+          if (err) {
+            return reject(err);
+          }
+
+          resolve();
+        });
+      });
+    });
+  },
+
+  async down(db) {
+    return new Promise((resolve, reject) => {
+      // Drop index first
+      db.run('DROP INDEX IF EXISTS idx_merge_locks_locked_at', (err) => {
+        if (err) {
+          return reject(err);
+        }
+
+        // Drop table
+        db.run('DROP TABLE IF EXISTS merge_locks', (err) => {
+          if (err) {
+            return reject(err);
+          }
+
+          resolve();
+        });
+      });
+    });
+  }
+};

package/lib/pattern-finder.js

@@ -0,0 +1,152 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find similar code patterns in the codebase based on keywords
+ * @param {string|string[]} keywords - Keyword(s) to search for
+ * @param {string} baseDir - Base directory to search (defaults to process.cwd())
+ * @returns {Array<{file: string, description: string}>} Array of pattern matches
+ */
+function findSimilarPatterns(keywords, baseDir = process.cwd()) {
+  const patterns = [];
+
+  // Normalize keywords to array
+  const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
+
+  // Directories to search
+  const searchDirs = ['lib', 'features', 'src'];
+
+  // Search each directory
+  searchDirs.forEach(dir => {
+    const dirPath = path.join(baseDir, dir);
+
+    if (!fs.existsSync(dirPath)) {
+      return;
+    }
+
+    // Search for matching files
+    const matches = searchDirectory(dirPath, keywordArray, baseDir);
+    patterns.push(...matches);
+  });
+
+  return patterns;
+}
+
+/**
+ * Recursively search directory for files matching keywords
+ * @param {string} dirPath - Directory to search
+ * @param {string[]} keywords - Keywords to match
+ * @param {string} baseDir - Base directory for relative paths
+ * @returns {Array<{file: string, description: string}>} Matching files
+ */
+function searchDirectory(dirPath, keywords, baseDir) {
+  const matches = [];
+
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    entries.forEach(entry => {
+      const fullPath = path.join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip node_modules and hidden directories
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+          return;
+        }
+
+        // Recursively search subdirectories
+        const subdirMatches = searchDirectory(fullPath, keywords, baseDir);
+        matches.push(...subdirMatches);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        // Check if filename matches any keyword
+        const fileName = entry.name.toLowerCase();
+        const matchingKeywords = keywords.filter(keyword =>
+          fileName.includes(keyword.toLowerCase())
+        );
+
+        if (matchingKeywords.length > 0) {
+          const relativePath = path.relative(baseDir, fullPath);
+
+          // Try to read file and find relevant functions/classes
+          const description = analyzeFile(fullPath, keywords);
+
+          matches.push({
+            file: relativePath,
+            description: description || `Contains ${matchingKeywords.join(', ')} related code`
+          });
+        }
+      }
+    });
+  } catch (err) {
+    // Skip directories we can't read
+    return matches;
+  }
+
+  return matches;
+}
+
+/**
+ * Analyze a file to find relevant functions or classes
+ * @param {string} filePath - Path to file to analyze
+ * @param {string[]} keywords - Keywords to look for
+ * @returns {string|null} Description of what the file contains
+ */
+function analyzeFile(filePath, keywords) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+
+    const functions = [];
+    const classes = [];
+
+    // Look for function declarations
+    lines.forEach(line => {
+      // Match function declarations: function name() or const name = function()
+      const funcMatch = line.match(/(?:function\s+(\w+)|const\s+(\w+)\s*=\s*(?:function|async|\())/);
+      if (funcMatch) {
+        const funcName = funcMatch[1] || funcMatch[2];
+
+        // Check if function name matches any keyword
+        const matchesKeyword = keywords.some(keyword =>
+          funcName.toLowerCase().includes(keyword.toLowerCase())
+        );
+
+        if (matchesKeyword) {
+          functions.push(funcName);
+        }
+      }
+
+      // Match class declarations: class Name
+      const classMatch = line.match(/class\s+(\w+)/);
+      if (classMatch) {
+        const className = classMatch[1];
+
+        // Check if class name matches any keyword
+        const matchesKeyword = keywords.some(keyword =>
+          className.toLowerCase().includes(keyword.toLowerCase())
+        );
+
+        if (matchesKeyword) {
+          classes.push(className);
+        }
+      }
+    });
+
+    // Build description
+    const parts = [];
+    if (functions.length > 0) {
+      parts.push(`Functions: ${functions.join(', ')}`);
+    }
+    if (classes.length > 0) {
+      parts.push(`Classes: ${classes.join(', ')}`);
+    }
+
+    return parts.length > 0 ? parts.join('; ') : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+module.exports = {
+  findSimilarPatterns
+};