wogiflow 2.6.3 → 2.7.0

package/lib/workspace-locks.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Workspace — Interface Lock Mechanism
+ *
+ * Prevents concurrent modification of shared interfaces by different repos.
+ * When a worker starts modifying a shared endpoint/type, it acquires a lock.
+ * Other workers get warned if they try to modify the same interface.
+ *
+ * Locks are:
+ *   - File-based (.workspace/state/locks/)
+ *   - Auto-expiring (configurable TTL, default 30 minutes)
+ *   - Best-effort (advisory, not mandatory — warns but doesn't hard-block)
+ *
+ * Lock file format: { interface, owner, taskId, acquiredAt, expiresAt }
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// ============================================================
+// Constants
+// ============================================================
+
+const LOCKS_DIR_NAME = 'locks';
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours cap
+const LOCK_ID_PATTERN = /^lock-[a-f0-9]{8}$/;
+const VALID_NAME_PATTERN = /^[a-zA-Z0-9_\-/.:{} ]{1,256}$/;
+
+// ============================================================
+// Lock Directory
+// ============================================================
+
+/**
+ * Get the locks directory path, ensuring it exists.
+ * @param {string} workspaceRoot
+ * @returns {string} locks directory path
+ */
+function getLocksDir(workspaceRoot) {
+  const dir = path.join(workspaceRoot, '.workspace', 'state', LOCKS_DIR_NAME);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Generate a unique lock ID.
+ * @returns {string} lock-XXXXXXXX
+ */
+function generateLockId() {
+  return 'lock-' + crypto.randomBytes(4).toString('hex');
+}
+
+// ============================================================
+// Lock Operations
+// ============================================================
+
+/**
+ * Acquire a lock on a shared interface.
+ *
+ * @param {string} workspaceRoot
+ * @param {Object} params
+ * @param {string} params.interface — the endpoint/type being locked (e.g., "GET /api/users", "UserDTO")
+ * @param {string} params.owner — the repo name acquiring the lock
+ * @param {string} [params.taskId] — optional task ID for traceability
+ * @param {number} [params.ttlMs] — lock TTL in milliseconds (default: 30 min)
+ * @returns {{ acquired: boolean, lockId: string|null, conflict: Object|null }}
+ */
+function acquireLock(workspaceRoot, params) {
+  const { interface: iface, owner, taskId = '', ttlMs = DEFAULT_TTL_MS } = params;
+
+  if (!iface || !VALID_NAME_PATTERN.test(iface)) {
+    return { acquired: false, lockId: null, conflict: null, error: 'Invalid interface name' };
+  }
+  if (!owner || !VALID_NAME_PATTERN.test(owner)) {
+    return { acquired: false, lockId: null, conflict: null, error: 'Invalid owner name' };
+  }
+
+  const locksDir = getLocksDir(workspaceRoot);
+  const effectiveTtl = Math.min(ttlMs, MAX_TTL_MS);
+
+  // Check for existing lock on this interface
+  const existing = findLockForInterface(workspaceRoot, iface);
+  if (existing) {
+    // Check if expired
+    if (new Date(existing.expiresAt).getTime() < Date.now()) {
+      // Expired — clean up and proceed
+      releaseLock(workspaceRoot, existing.id);
+    } else if (existing.owner === owner) {
+      // Same owner — extend the lock
+      existing.expiresAt = new Date(Date.now() + effectiveTtl).toISOString();
+      if (taskId) existing.taskId = taskId;
+      const lockPath = path.join(locksDir, `${existing.id}.json`);
+      fs.writeFileSync(lockPath, JSON.stringify(existing, null, 2));
+      return { acquired: true, lockId: existing.id, conflict: null };
+    } else {
+      // Conflict — another repo holds the lock
+      return { acquired: false, lockId: null, conflict: existing };
+    }
+  }
+
+  // Create new lock using exclusive create flag to prevent TOCTOU races.
+  // If another process creates the same lock file between our check and write,
+  // the 'wx' flag will throw EEXIST, and we retry with a new ID.
+  const lockId = generateLockId();
+  const lock = {
+    id: lockId,
+    interface: iface,
+    owner,
+    taskId,
+    acquiredAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + effectiveTtl).toISOString()
+  };
+
+  const lockPath = path.join(locksDir, `${lockId}.json`);
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2), { flag: 'wx' });
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      // Extremely unlikely with random IDs, but handle gracefully
+      return { acquired: false, lockId: null, conflict: null, error: 'Lock ID collision — retry' };
+    }
+    return { acquired: false, lockId: null, conflict: null, error: err.message };
+  }
+
+  return { acquired: true, lockId, conflict: null };
+}
+
+/**
+ * Release a lock.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} lockId
+ * @returns {boolean} true if lock was found and removed
+ */
+function releaseLock(workspaceRoot, lockId) {
+  if (!LOCK_ID_PATTERN.test(lockId)) return false;
+
+  const locksDir = getLocksDir(workspaceRoot);
+  const lockPath = path.join(locksDir, `${lockId}.json`);
+
+  try {
+    if (fs.existsSync(lockPath)) {
+      fs.unlinkSync(lockPath);
+      return true;
+    }
+  } catch (_err) {
+    // Best effort
+  }
+
+  return false;
+}
+
+/**
+ * Release all locks held by a specific owner (repo).
+ * Typically called on task completion or session end.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} owner — repo name
+ * @returns {number} number of locks released
+ */
+function releaseAllByOwner(workspaceRoot, owner) {
+  const locks = listLocks(workspaceRoot);
+  let released = 0;
+
+  for (const lock of locks) {
+    if (lock.owner === owner) {
+      if (releaseLock(workspaceRoot, lock.id)) {
+        released++;
+      }
+    }
+  }
+
+  return released;
+}
+
+/**
+ * Release all locks for a specific task.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} taskId
+ * @returns {number} number of locks released
+ */
+function releaseAllByTask(workspaceRoot, taskId) {
+  const locks = listLocks(workspaceRoot);
+  let released = 0;
+
+  for (const lock of locks) {
+    if (lock.taskId === taskId) {
+      if (releaseLock(workspaceRoot, lock.id)) {
+        released++;
+      }
+    }
+  }
+
+  return released;
+}
+
+// ============================================================
+// Lock Queries
+// ============================================================
+
+/**
+ * Find an active (non-expired) lock for a specific interface.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} iface — interface name
+ * @returns {Object|null} lock object or null
+ */
+function findLockForInterface(workspaceRoot, iface) {
+  const locks = listLocks(workspaceRoot);
+  const now = Date.now();
+  const ifaceLower = iface.toLowerCase();
+
+  for (const lock of locks) {
+    if (lock.interface.toLowerCase() === ifaceLower) {
+      if (new Date(lock.expiresAt).getTime() > now) {
+        return lock;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * List all locks (including expired ones).
+ *
+ * @param {string} workspaceRoot
+ * @returns {Array<Object>} lock objects
+ */
+function listLocks(workspaceRoot) {
+  const locksDir = getLocksDir(workspaceRoot);
+  const locks = [];
+
+  try {
+    const files = fs.readdirSync(locksDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const content = JSON.parse(fs.readFileSync(path.join(locksDir, file), 'utf-8'));
+        if (content.id && content.interface && content.owner) {
+          locks.push(content);
+        }
+      } catch (_err) {
+        // Skip malformed lock files
+      }
+    }
+  } catch (_err) {
+    // Locks dir doesn't exist yet
+  }
+
+  return locks;
+}
+
+/**
+ * List only active (non-expired) locks.
+ *
+ * @param {string} workspaceRoot
+ * @returns {Array<Object>} active locks
+ */
+function listActiveLocks(workspaceRoot) {
+  const now = Date.now();
+  return listLocks(workspaceRoot).filter(l => new Date(l.expiresAt).getTime() > now);
+}
+
+/**
+ * Clean up all expired locks.
+ *
+ * @param {string} workspaceRoot
+ * @returns {number} number of expired locks removed
+ */
+function cleanExpiredLocks(workspaceRoot) {
+  const now = Date.now();
+  const locks = listLocks(workspaceRoot);
+  let cleaned = 0;
+
+  for (const lock of locks) {
+    if (new Date(lock.expiresAt).getTime() <= now) {
+      if (releaseLock(workspaceRoot, lock.id)) {
+        cleaned++;
+      }
+    }
+  }
+
+  return cleaned;
+}
+
+/**
+ * Check if modifying a set of interfaces would conflict with any existing locks.
+ *
+ * @param {string} workspaceRoot
+ * @param {string[]} interfaces — interfaces to check
+ * @param {string} requestingRepo — the repo that wants to modify
+ * @returns {{ clear: boolean, conflicts: Array<Object> }}
+ */
+function checkForConflicts(workspaceRoot, interfaces, requestingRepo) {
+  const conflicts = [];
+  const now = Date.now();
+
+  for (const iface of interfaces) {
+    const lock = findLockForInterface(workspaceRoot, iface);
+    if (lock && lock.owner !== requestingRepo && new Date(lock.expiresAt).getTime() > now) {
+      conflicts.push({
+        interface: iface,
+        heldBy: lock.owner,
+        taskId: lock.taskId,
+        acquiredAt: lock.acquiredAt,
+        expiresAt: lock.expiresAt
+      });
+    }
+  }
+
+  return { clear: conflicts.length === 0, conflicts };
+}
+
+/**
+ * Format locks for display.
+ *
+ * @param {Array<Object>} locks
+ * @returns {string} formatted text
+ */
+function formatLocksForDisplay(locks) {
+  if (locks.length === 0) return 'No active locks.';
+
+  const now = Date.now();
+  const lines = [];
+
+  for (const lock of locks) {
+    const remaining = new Date(lock.expiresAt).getTime() - now;
+    const expired = remaining <= 0;
+    const timeStr = expired
+      ? 'EXPIRED'
+      : remaining < 60000
+        ? `${Math.round(remaining / 1000)}s remaining`
+        : `${Math.round(remaining / 60000)}m remaining`;
+
+    const icon = expired ? '🔓' : '🔒';
+    lines.push(`  ${icon} ${lock.interface} — held by ${lock.owner}${lock.taskId ? ` (${lock.taskId})` : ''} [${timeStr}]`);
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================
+// Exports
+// ============================================================
+
+module.exports = {
+  // Lock operations
+  acquireLock,
+  releaseLock,
+  releaseAllByOwner,
+  releaseAllByTask,
+
+  // Lock queries
+  findLockForInterface,
+  listLocks,
+  listActiveLocks,
+  cleanExpiredLocks,
+  checkForConflicts,
+
+  // Display
+  formatLocksForDisplay,
+
+  // Constants
+  DEFAULT_TTL_MS,
+  MAX_TTL_MS
+};

package/lib/workspace-messages.js

@@ -22,7 +22,13 @@ const MESSAGE_TYPES = [
   'bug-report',       // "Your endpoint returns 500 when I send Y"
   'task-complete',    // "I finished my side of feature Z"
   'needs-help',       // "I'm stuck, can you check X on your side?"
-  'heads-up'          // "I'm about to change Y, just FYI"
+  'heads-up',         // "I'm about to change Y, just FYI"
+  'impact-query',     // Pre-dev: "I'm about to change X, will this break you?"
+  'impact-response',  // Pre-dev response: "Yes/No, here's what to watch out for"
+  'verification-request', // Post-change: "Please verify your integrations"
+  'lock-acquired',    // "I'm editing shared interface X"
+  'lock-released',    // "Done editing shared interface X"
+  'decision-broadcast' // "New workspace-wide decision: ..."
 ];
 
 const MESSAGE_STATUSES = ['pending', 'acknowledged', 'task-created', 'resolved'];
@@ -159,7 +165,15 @@ function updateMessageStatus(workspaceRoot, messageId, newStatus, extra = {}) {
     const message = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
     message.status = newStatus;
     message.updatedAt = new Date().toISOString();
-    Object.assign(message, extra);
+    // Safe merge: filter dangerous keys to prevent prototype pollution
+    if (extra && typeof extra === 'object') {
+      const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+      for (const [key, value] of Object.entries(extra)) {
+        if (!DANGEROUS_KEYS.has(key)) {
+          message[key] = value;
+        }
+      }
+    }
     fs.writeFileSync(filePath, JSON.stringify(message, null, 2));
     return message;
   } catch (_err) {
@@ -416,6 +430,182 @@ function readWorkspaceConfig(workspaceRoot) {
   }
 }
 
+// ============================================================
+// Peer Query Protocol (Pre-Dev Impact Queries)
+// ============================================================
+
+/**
+ * Send an impact query to a peer before making changes.
+ * This is a structured pre-dev check: "I'm about to change X, will this break you?"
+ *
+ * @param {string} fromRepo
+ * @param {string} toRepo
+ * @param {Object} params
+ * @param {string} params.taskTitle — what work is planned
+ * @param {string[]} [params.affectedEndpoints] — endpoints that will change
+ * @param {string[]} [params.affectedTypes] — types/schemas that will change
+ * @param {string} [params.changeDescription] — detailed description of planned changes
+ * @returns {Object} impact-query message (unsaved — caller must saveMessage)
+ */
+function sendImpactQuery(fromRepo, toRepo, params) {
+  const { taskTitle, affectedEndpoints = [], affectedTypes = [], changeDescription = '' } = params;
+
+  let body = `## Pre-Dev Impact Query\n\n`;
+  body += `**Planned work**: ${taskTitle}\n\n`;
+  if (affectedEndpoints.length > 0) {
+    body += `**Endpoints that will change**:\n${affectedEndpoints.map(e => `- \`${e}\``).join('\n')}\n\n`;
+  }
+  if (affectedTypes.length > 0) {
+    body += `**Types/schemas that will change**:\n${affectedTypes.map(t => `- \`${t}\``).join('\n')}\n\n`;
+  }
+  if (changeDescription) {
+    body += `**Details**: ${changeDescription}\n\n`;
+  }
+  body += `**Please respond with**:\n`;
+  body += `1. Will this break anything on your side?\n`;
+  body += `2. Are there any endpoints/types I should be aware of?\n`;
+  body += `3. Any coordination needed?\n`;
+
+  return createMessage({
+    from: fromRepo,
+    to: toRepo,
+    type: 'impact-query',
+    subject: `Impact query: ${taskTitle.substring(0, 60)}`,
+    body,
+    priority: 'high',
+    actionRequired: true
+  });
+}
+
+/**
+ * Respond to an impact query from a peer.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} originalMessageId — the impact-query being responded to
+ * @param {string} fromRepo — who is responding
+ * @param {Object} response
+ * @param {boolean} response.willBreak — will the planned changes break this repo?
+ * @param {string[]} [response.concerns] — specific concerns
+ * @param {string} [response.suggestion] — suggested approach
+ * @returns {Object} impact-response message (unsaved)
+ */
+function respondToImpactQuery(workspaceRoot, originalMessageId, fromRepo, response) {
+  if (!MESSAGE_ID_PATTERN.test(originalMessageId)) {
+    throw new Error(`Invalid messageId: ${originalMessageId}. Must match msg-[a-f0-9]{8}`);
+  }
+
+  // Mark original as acknowledged
+  updateMessageStatus(workspaceRoot, originalMessageId, 'acknowledged');
+
+  // Read original to get sender
+  const filePath = path.join(workspaceRoot, '.workspace', 'messages', `${originalMessageId}.json`);
+  let originalFrom = 'unknown';
+  try {
+    const original = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    originalFrom = original.from;
+  } catch (_err) {
+    // Non-critical
+  }
+
+  const { willBreak, concerns = [], suggestion = '' } = response;
+  let body = `## Impact Response\n\n`;
+  body += `**Will break**: ${willBreak ? 'YES' : 'No'}\n\n`;
+  if (concerns.length > 0) {
+    body += `**Concerns**:\n${concerns.map(c => `- ${c}`).join('\n')}\n\n`;
+  }
+  if (suggestion) {
+    body += `**Suggestion**: ${suggestion}\n`;
+  }
+
+  return createMessage({
+    from: fromRepo,
+    to: originalFrom,
+    type: 'impact-response',
+    subject: `Re: ${originalMessageId} — ${willBreak ? 'BREAKING' : 'OK'}`,
+    body,
+    priority: willBreak ? 'critical' : 'medium',
+    actionRequired: willBreak
+  });
+}
+
+// ============================================================
+// Verification Requests (Post-Change)
+// ============================================================
+
+/**
+ * Create a verification request for a consumer repo after provider changes.
+ *
+ * @param {string} fromRepo — the repo that made changes
+ * @param {string} toRepo — the consumer that needs to verify
+ * @param {Object} params
+ * @param {string} params.taskTitle — what was changed
+ * @param {string[]} [params.changedEndpoints] — endpoints that changed
+ * @param {string[]} [params.changedTypes] — types that changed
+ * @param {boolean} [params.contractDriftDetected] — if drift was found
+ * @returns {Object} verification-request message (unsaved)
+ */
+function createVerificationRequest(fromRepo, toRepo, params) {
+  const { taskTitle, changedEndpoints = [], changedTypes = [], contractDriftDetected = false } = params;
+
+  let body = `## Verification Required\n\n`;
+  body += `Repo \`${fromRepo}\` completed: **${taskTitle}**\n\n`;
+  if (changedEndpoints.length > 0) {
+    body += `**Changed endpoints**:\n${changedEndpoints.map(e => `- \`${e}\``).join('\n')}\n\n`;
+  }
+  if (changedTypes.length > 0) {
+    body += `**Changed types**:\n${changedTypes.map(t => `- \`${t}\``).join('\n')}\n\n`;
+  }
+  if (contractDriftDetected) {
+    body += `**WARNING**: Contract drift detected — your integration may be broken.\n\n`;
+  }
+  body += `**Action**: Please verify your API calls and type usage still match.\n`;
+
+  return createMessage({
+    from: fromRepo,
+    to: toRepo,
+    type: 'verification-request',
+    subject: `Verify: ${fromRepo} changed ${taskTitle.substring(0, 50)}`,
+    body,
+    priority: contractDriftDetected ? 'critical' : 'high',
+    actionRequired: true,
+    suggestedTask: {
+      title: `Verify integrations after ${fromRepo} changes — ${taskTitle.substring(0, 40)}`,
+      type: 'fix',
+      priority: contractDriftDetected ? 'P0' : 'P1'
+    }
+  });
+}
+
+// ============================================================
+// Decision Broadcast
+// ============================================================
+
+/**
+ * Broadcast a workspace-wide decision to all members.
+ *
+ * @param {string} fromRepo — the repo that made the decision
+ * @param {string} decisionTitle
+ * @param {string} decisionContent
+ * @param {string[]} targetRepos — list of member repo names
+ * @returns {Array<Object>} messages (unsaved)
+ */
+function broadcastDecision(fromRepo, decisionTitle, decisionContent, targetRepos) {
+  const messages = [];
+  for (const target of targetRepos) {
+    if (target === fromRepo) continue;
+    messages.push(createMessage({
+      from: fromRepo,
+      to: target,
+      type: 'decision-broadcast',
+      subject: `Decision: ${decisionTitle.substring(0, 60)}`,
+      body: `## New Workspace Decision\n\n### ${decisionTitle}\n\n${decisionContent}\n\n*This decision applies workspace-wide. Please follow it in your repo.*`,
+      priority: 'high',
+      actionRequired: false
+    }));
+  }
+  return messages;
+}
+
 // ============================================================
 // Exports
 // ============================================================
@@ -444,5 +634,15 @@ module.exports = {
 
   // Agent questions
   askQuestion,
-  answerQuestion
+  answerQuestion,
+
+  // Peer query protocol (pre-dev)
+  sendImpactQuery,
+  respondToImpactQuery,
+
+  // Verification requests (post-change)
+  createVerificationRequest,
+
+  // Decision broadcast
+  broadcastDecision
 };