@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/beads-client.mjs

@@ -0,0 +1,518 @@
+/**
+ * lib/beads-client.mjs — Wrapper for bd commands with lock‑management and queueing.
+ *
+ * VERSION 2.0: Now uses optimistic locking by default for better concurrency.
+ * All external bd calls should go through `runBd()` to ensure serialized access
+ * to the embedded Dolt database.
+ * 
+ * Changes:
+ * - Reads are now lock-free (concurrent safe)
+ * - Writes use optimistic locking with automatic retry
+ * - Legacy file-based lock is fallback only
+ * - Better error messages and conflict resolution
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  acquireLock,
+  releaseLock,
+  getLockStatus,
+  cleanupStaleLock,
+  enqueueRequest,
+  removeFromQueue,
+  readQueue,
+  cleanupStaleQueue,
+} from './beads-lock.mjs';
+
+import {
+  concurrentRead,
+  optimisticWrite,
+  batchReadBeads,
+  updateBeadOptimistic,
+  claimBeadOptimistic,
+  shouldUseOptimisticLocking,
+  recordOperationStats,
+} from './beads-optimistic.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Configuration and defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_OPTIONS = {
+  actor: 'construct',
+  silent: false,
+  timeoutSeconds: 30,      // Time to wait for lock before giving up
+  commandTimeoutSeconds: 120, // Max runtime for the bd child process
+  queuePollMs: 100,       // How often to check for lock release when queued
+  maxQueueWaitSeconds: 300, // Max total time allowed in queue
+  useOptimisticLocking: true, // NEW: Use optimistic locking by default
+  fallbackToLegacy: true, // NEW: Fall back to legacy locking on failure
+  maxRetries: 5,          // NEW: Max retries for optimistic locking
+};
+
+// Track which operations are reads vs writes
+const READ_OPERATIONS = new Set([
+  'list', 'show', 'ready', 'search', 'merge-slot', 'check',
+  'status', 'log', 'diff', 'note',
+]);
+
+const WRITE_OPERATIONS = new Set([
+  'create', 'update', 'close', 'claim', 'note', 'label',
+  'assign', 'link', 'unlink', 'move', 'archive',
+]);
+
+// ---------------------------------------------------------------------------
+// Operation classification
+// ---------------------------------------------------------------------------
+
+function isReadOperation(args) {
+  if (!args || args.length === 0) return true;
+  const cmd = args[0];
+  return READ_OPERATIONS.has(cmd) || !WRITE_OPERATIONS.has(cmd);
+}
+
+function isWriteOperation(args) {
+  if (!args || args.length === 0) return false;
+  const cmd = args[0];
+  return WRITE_OPERATIONS.has(cmd);
+}
+
+function extractBeadId(args) {
+  // Try to find a bead ID in the arguments (typically the second arg)
+  if (args.length >= 2 && args[1] && !args[1].startsWith('--')) {
+    return args[1];
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Core wrapper with optimistic locking support
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a bd command with appropriate locking strategy.
+ * 
+ * STRATEGY:
+ * 1. Read operations: Lock-free concurrent execution
+ * 2. Write operations: Optimistic locking with retry
+ * 3. Legacy lock: Fallback only when optimistic fails
+ *
+ * @param {string[]} args - Arguments for `bd`
+ * @param {Object} [options]
+ * @param {string} options.actor - Who is running this (for logging)
+ * @param {number} options.timeoutSeconds - Max seconds to wait for lock
+ * @param {number} options.commandTimeoutSeconds - Max seconds to let bd run after lock acquisition
+ * @param {boolean} options.silent - Suppress logging of success/queue status
+ * @param {boolean} options.useOptimisticLocking - Use optimistic locking (default: true)
+ * @param {boolean} options.fallbackToLegacy - Fall back to legacy lock on failure (default: true)
+ * @param {number} options.maxRetries - Max retries for optimistic locking (default: 5)
+ * @param {string} options.cwd - Working directory (default: process.cwd())
+ * @returns {Object} { success: boolean, output: string, error?: string, attempts?: number, method?: string }
+ */
+export async function runBd(args, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const cwd = opts.cwd || process.cwd();
+  const commandDesc = args.join(' ');
+  const isRead = isReadOperation(args);
+  const beadId = extractBeadId(args);
+  
+  if (!opts.silent) {
+    const opType = isRead ? 'read' : 'write';
+    console.error(`[beads] ${opts.actor} ${opType}: bd ${commandDesc}`);
+  }
+  
+  // ==========================================================================
+  // PATH 1: Lock-free reads (fastest, most concurrent)
+  // ==========================================================================
+  if (isRead && opts.useOptimisticLocking) {
+    const startTime = Date.now();
+    
+    const result = spawnSync('bd', args, {
+      cwd,
+      encoding: 'utf8',
+      env: { ...process.env, BEADS_ACTOR: opts.actor },
+      timeout: Math.max(1, Math.round(opts.commandTimeoutSeconds * 1000)),
+    });
+    
+    const execTime = Date.now() - startTime;
+    
+    // Handle timeout error
+    if (result.error?.code === 'ETIMEDOUT') {
+      return {
+        success: false,
+        error: `bd ${commandDesc} timed out after ${opts.commandTimeoutSeconds}s`,
+        exitCode: null,
+        execTimeMs: execTime,
+        method: 'concurrent-read',
+      };
+    }
+    
+    if (!opts.silent) {
+      console.error(`[beads] ✓ Read completed in ${execTime}ms (lock-free)`);
+    }
+    
+    return {
+      success: result.status === 0 && !result.error,
+      output: result.stdout,
+      error: result.stderr || result.error?.message,
+      exitCode: result.status,
+      execTimeMs: execTime,
+      method: 'concurrent-read',
+    };
+  }
+  
+  // ==========================================================================
+  // PATH 2: Optimistic locking for writes (scalable, conflict-resistant)
+  // ==========================================================================
+  if (!isRead && opts.useOptimisticLocking && shouldUseOptimisticLocking()) {
+    const startTime = Date.now();
+    
+    const result = await optimisticWrite({
+      beadId: beadId || 'unknown',
+      cwd,
+      maxRetries: opts.maxRetries,
+      execute: async () => {
+        const execResult = spawnSync('bd', args, {
+          cwd,
+          encoding: 'utf8',
+          env: { ...process.env, BEADS_ACTOR: opts.actor },
+          timeout: Math.max(1, Math.round(opts.commandTimeoutSeconds * 1000)),
+        });
+        
+        if (execResult.status !== 0) {
+          throw new Error(execResult.stderr || 'Command failed');
+        }
+        
+        return execResult.stdout;
+      },
+    });
+    
+    const totalTime = Date.now() - startTime;
+    
+    recordOperationStats(commandDesc, result, cwd);
+    
+    if (result.success) {
+      if (!opts.silent) {
+        console.error(`[beads] ✓ Write completed in ${totalTime}ms (optimistic, ${result.attempts} attempt${result.attempts !== 1 ? 's' : ''})`);
+      }
+      return {
+        success: true,
+        output: result.result,
+        attempts: result.attempts,
+        execTimeMs: totalTime,
+        method: 'optimistic-locking',
+      };
+    }
+    
+    // Optimistic locking failed
+    if (!opts.fallbackToLegacy) {
+      return {
+        success: false,
+        error: result.error,
+        attempts: result.attempts,
+        method: 'optimistic-locking',
+      };
+    }
+    
+    if (!opts.silent) {
+      console.error(`[beads] ⚠ Optimistic locking failed: ${result.error}`);
+      console.error(`[beads] ↘ Falling back to legacy lock...`);
+    }
+  }
+  
+  // ==========================================================================
+  // PATH 3: Legacy file-based locking (fallback, most conservative)
+  // ==========================================================================
+  return runWithLegacyLock(args, opts, cwd, commandDesc);
+}
+
+/**
+ * Legacy locking implementation (original behavior).
+ * Used as fallback when optimistic locking fails.
+ */
+async function runWithLegacyLock(args, opts, cwd, commandDesc) {
+  // Clean up any stale locks before trying
+  cleanupStaleLock({ cwd });
+  cleanupStaleQueue({ cwd });
+
+  // Try to acquire the lock
+  const startWait = Date.now();
+  const lock = await acquireLock({
+    actor: opts.actor,
+    command: commandDesc,
+    timeoutSeconds: opts.timeoutSeconds,
+    cwd,
+  });
+
+  if (!lock) {
+    // Failed to get lock; add to queue if allowed
+    const maxQueueWaitMs = opts.maxQueueWaitSeconds * 1000;
+    if (Date.now() - startWait + maxQueueWaitMs > maxQueueWaitMs) {
+      return {
+        success: false,
+        error: `Timeout waiting for lock after ${opts.timeoutSeconds}s`,
+        queued: false,
+        method: 'legacy-lock',
+      };
+    }
+
+    const queueEntry = enqueueRequest({
+      actor: opts.actor,
+      command: commandDesc,
+      args,
+      cwd,
+    });
+
+    if (!opts.silent) {
+      console.error(`[beads] ↘ Added to queue (position ${readQueue({ cwd }).length})`);
+    }
+
+    // Wait in queue, polling periodically
+    while (Date.now() - startWait < opts.maxQueueWaitSeconds * 1000) {
+      await new Promise((resolve) => setTimeout(resolve, opts.queuePollMs));
+
+      cleanupStaleLock({ cwd });
+      const status = getLockStatus({ cwd });
+      if (!status.locked) {
+        // Lock free, remove from queue and try again
+        removeFromQueue(queueEntry.timestamp || queueEntry.pid, { cwd });
+        return await runBd(args, { ...opts, silent: true });
+      }
+    }
+
+    // Queue timeout
+    removeFromQueue(queueEntry.timestamp || queueEntry.pid, { cwd });
+    return {
+      success: false,
+      error: `Timeout in queue after ${opts.maxQueueWaitSeconds}s`,
+      queued: true,
+      waitTimeMs: Date.now() - startWait,
+      method: 'legacy-lock',
+    };
+  }
+
+  const execStart = Date.now();
+  let result;
+  try {
+    result = spawnSync('bd', args, {
+      cwd,
+      encoding: 'utf8',
+      env: { ...process.env, BEADS_ACTOR: opts.actor },
+      killSignal: 'SIGTERM',
+      timeout: Math.max(1, Math.round(opts.commandTimeoutSeconds * 1000)),
+    });
+  } finally {
+    releaseLock({ cwd });
+  }
+
+  const totalTime = Date.now() - startWait;
+  const execTime = Date.now() - execStart;
+
+  if (!opts.silent) {
+    console.error(`[beads] ✓ Executed in ${execTime}ms (legacy lock, total: ${totalTime}ms)`);
+  }
+
+  return {
+    success: result.status === 0 && !result.error,
+    output: result.stdout,
+    error: result.error?.code === 'ETIMEDOUT'
+      ? `bd ${commandDesc} timed out after ${opts.commandTimeoutSeconds}s`
+      : (result.stderr || result.error?.message),
+    exitCode: result.status,
+    waitTimeMs: execStart - startWait,
+    execTimeMs: execTime,
+    totalTimeMs: totalTime,
+    method: 'legacy-lock',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Higher‑level convenience functions (enhanced with optimistic locking)
+// ---------------------------------------------------------------------------
+
+/**
+ * Quick wrapper that returns parsed JSON output.
+ * Uses concurrent read (no locking) for better performance.
+ */
+export async function runBdJson(args, options = {}) {
+  const result = await runBd([...args, '--json'], { ...options, useOptimisticLocking: true });
+  if (!result.success) {
+    throw new Error(`bd failed: ${result.error}`);
+  }
+  try {
+    return JSON.parse(result.output);
+  } catch (e) {
+    throw new Error(`Failed to parse JSON from bd: ${e.message}\n${result.output}`);
+  }
+}
+
+/**
+ * Get issue list (commonly used).
+ * Uses concurrent reads for better performance.
+ */
+export async function listIssues(options = {}) {
+  return runBdJson(['list'], { useOptimisticLocking: true, ...options });
+}
+
+/**
+ * Show a specific issue.
+ * Uses concurrent read (no locking needed).
+ */
+export async function showIssue(id, options = {}) {
+  return runBdJson(['show', id], { useOptimisticLocking: true, ...options });
+}
+
+/**
+ * Claim an issue with optimistic locking.
+ * Uses optimistic locking for better concurrency.
+ */
+export async function claimIssue(id, options = {}) {
+  // Use the specialized optimistic claim function
+  const result = await claimBeadOptimistic(id, options);
+  
+  if (result.success) {
+    return { success: true, output: JSON.stringify(result.result) };
+  }
+  
+  // Fall back to legacy
+  return runBd(['update', id, '--claim'], { ...options, useOptimisticLocking: false });
+}
+
+/**
+ * Close an issue.
+ */
+export async function closeIssue(id, options = {}) {
+  return runBd(['close', id], options);
+}
+
+/**
+ * Check ready issues.
+ * Uses concurrent read (no locking needed).
+ */
+export async function getReadyIssues(options = {}) {
+  return runBdJson(['ready'], { useOptimisticLocking: true, ...options });
+}
+
+/**
+ * Check merge‑slot availability.
+ * Uses concurrent read.
+ */
+export async function getMergeSlotStatus(options = {}) {
+  return runBd(['merge-slot', 'check'], { silent: true, useOptimisticLocking: true, ...options });
+}
+
+/**
+ * Try to acquire merge‑slot (with fallback if it doesn't exist).
+ * Uses optimistic locking for the acquire operation.
+ */
+export async function acquireMergeSlot(options = {}) {
+  const { success, error } = await runBd(['merge-slot', 'acquire'], { 
+    silent: true, 
+    useOptimisticLocking: true,
+    ...options 
+  });
+  
+  if (!success && error?.includes('merge slot bead')) {
+    // Slot might not exist; create it first
+    await runBd(['merge-slot', 'create'], { silent: true, useOptimisticLocking: true, ...options });
+    return runBd(['merge-slot', 'acquire'], { silent: true, useOptimisticLocking: true, ...options });
+  }
+  
+  return { success, error };
+}
+
+/**
+ * Release merge‑slot.
+ */
+export async function releaseMergeSlot(options = {}) {
+  return runBd(['merge-slot', 'release'], { silent: true, useOptimisticLocking: true, ...options });
+}
+
+/**
+ * Batch read multiple issues efficiently.
+ * NEW: Concurrent batch reading for better performance.
+ */
+export async function batchShowIssues(ids, options = {}) {
+  return batchReadBeads(ids, options.cwd || process.cwd());
+}
+
+// ---------------------------------------------------------------------------
+// Status and utility exports
+// ---------------------------------------------------------------------------
+
+export { getLockStatus, cleanupStaleLock, cleanupStaleQueue, readQueue } from './beads-lock.mjs';
+export { 
+  getContentionStats, 
+  recordOperationStats,
+  shouldUseOptimisticLocking 
+} from './beads-optimistic.mjs';
+
+/**
+ * Shortcut to get current queue length.
+ */
+export function getQueueLength(cwd = process.cwd()) {
+  return readQueue({ cwd }).length;
+}
+
+/**
+ * Get human‑readable status string (lock + queue + contention stats).
+ * ENHANCED: Now includes optimistic locking statistics.
+ */
+export async function getHumanStatus(cwd = process.cwd()) {
+  const status = getLockStatus({ cwd });
+  
+  let out = '';
+  
+  // Optimistic locking status
+  out += 'Locking Strategy:\n';
+  out += `  Mode: ${shouldUseOptimisticLocking() ? 'Optimistic (concurrent reads + versioned writes)' : 'Legacy (exclusive locks)'}\n`;
+  
+  // Try to get stats if available
+  try {
+    const { getContentionStats } = await import('./beads-optimistic.mjs');
+    const stats = await getContentionStats(cwd);
+    if (stats.totalOperations > 0) {
+      out += `  Operations: ${stats.totalOperations}\n`;
+      out += `  Conflicts: ${stats.conflicts} (${((stats.conflicts / stats.totalOperations) * 100).toFixed(1)}%)\n`;
+      out += `  Avg attempts: ${stats.avgAttempts?.toFixed(2) || '1.00'}\n`;
+    }
+  } catch {
+    // Stats not available, skip
+  }
+  
+  out += '\n';
+  
+  // Legacy lock status (for debugging)
+  if (status.lock) {
+    const { lock } = status;
+    out += `Legacy Lock:\n`;
+    out += `  Held by: ${lock.actor} (pid ${lock.pid})\n`;
+    out += `  Command: ${lock.command}\n`;
+    out += `  Started: ${lock.startedAt}${lock.alive ? '' : ' ⚠️ process dead'}\n`;
+  } else if (status.nativeLock) {
+    const { nativeLock } = status;
+    out += `Native Lock:\n`;
+    out += `  Held by: ${nativeLock.command} (pid ${nativeLock.pid})\n`;
+  } else {
+    out += 'No lock held\n';
+  }
+
+  const queue = readQueue({ cwd });
+  if (queue.length) {
+    out += `\nQueue (${queue.length} waiting):\n`;
+    queue.forEach((entry, idx) => {
+      const alive = entry.pid && (() => {
+        try { process.kill(entry.pid, 0); return true; } catch { return false; }
+      })();
+      out += `  ${idx + 1}. ${entry.actor} – ${entry.command || entry.args?.join(' ')}${alive ? '' : ' ⚠️ dead'}\n`;
+    });
+  }
+
+  return out;
+}