@howlil/ez-agents 2.0.0

package/get-shit-done/bin/lib/file-lock.cjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * GSD File Lock — File locking utility for concurrent write protection
+ * 
+ * Uses proper-lockfile to prevent concurrent writes to planning files
+ * Includes deadlock detection (30s timeout) and automatic lock cleanup
+ * 
+ * Fallback: Uses simple lock file mechanism if proper-lockfile is not available
+ * 
+ * Usage:
+ *   const { withLock, isLocked, ifUnlocked } = require('./file-lock.cjs');
+ *   await withLock('.planning/STATE.md', async () => {
+ *     // Safe to write - no other process can modify this file
+ *   });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Try to load proper-lockfile, fallback to simple implementation
+let properLockfile = null;
+try {
+  properLockfile = require('proper-lockfile');
+} catch (err) {
+  logger.warn('proper-lockfile not available, using fallback implementation');
+}
+
+const DEFAULT_OPTIONS = {
+  staleTime: 30000,     // Lock considered stale after 30s
+  update: 10000,        // Update lock every 10s to prevent stale
+  retries: {
+    retries: 10,
+    factor: 1.1,
+    minTimeout: 100,
+    maxTimeout: 1000,
+    randomize: true
+  }
+};
+
+// Simple lock file implementation (fallback)
+const LOCK_SUFFIX = '.lock';
+const lockHolders = new Map(); // Track locks held by this process
+
+/**
+ * Get lock file path
+ * @param {string} filePath - Original file path
+ * @returns {string} - Lock file path
+ */
+function getLockPath(filePath) {
+  return filePath + LOCK_SUFFIX;
+}
+
+/**
+ * Simple lock acquisition (fallback when proper-lockfile unavailable)
+ */
+async function simpleLock(filePath, options = {}) {
+  const lockPath = getLockPath(filePath);
+  const startTime = Date.now();
+  const timeout = options.timeout || 30000;
+  const staleTime = options.staleTime || 30000;
+  
+  while (Date.now() - startTime < timeout) {
+    try {
+      // Check if lock file exists and is not stale
+      if (fs.existsSync(lockPath)) {
+        const stats = fs.statSync(lockPath);
+        const age = Date.now() - stats.mtimeMs;
+        
+        if (age < staleTime) {
+          // Lock is held by another process, wait and retry
+          await new Promise(resolve => setTimeout(resolve, 100));
+          continue;
+        }
+        // Lock is stale, remove it
+        try {
+          fs.unlinkSync(lockPath);
+        } catch (err) {
+          // Ignore - another process might have removed it
+        }
+      }
+      
+      // Try to create lock file
+      fs.writeFileSync(lockPath, JSON.stringify({
+        pid: process.pid,
+        timestamp: Date.now()
+      }), 'utf-8');
+      
+      lockHolders.set(filePath, lockPath);
+      
+      return {
+        release: async () => {
+          try {
+            if (fs.existsSync(lockPath)) {
+              fs.unlinkSync(lockPath);
+            }
+            lockHolders.delete(filePath);
+          } catch (err) {
+            logger.warn(`Failed to release lock: ${lockPath}`, { error: err.message });
+          }
+        }
+      };
+    } catch (err) {
+      // Lock acquisition failed, wait and retry
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+  
+  throw new Error(`Lock acquisition timed out after ${timeout}ms`);
+}
+
+/**
+ * Execute an operation with file lock
+ * @param {string} filePath - Path to file to lock
+ * @param {Function} operation - Async function to execute while locked
+ * @param {Object} options - Lock options
+ * @returns {Promise<any>} - Result of operation
+ */
+async function withLock(filePath, operation, options = {}) {
+  const lockOptions = { ...DEFAULT_OPTIONS, ...options };
+  const absolutePath = path.resolve(filePath);
+  
+  // Ensure file exists
+  if (!fs.existsSync(absolutePath)) {
+    const dir = path.dirname(absolutePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(absolutePath, '', 'utf-8');
+  }
+  
+  let release = null;
+  const startTime = Date.now();
+  
+  try {
+    logger.debug(`Attempting to acquire lock: ${absolutePath}`);
+    
+    if (properLockfile) {
+      // Use proper-lockfile
+      release = await properLockfile.lock(absolutePath, lockOptions);
+    } else {
+      // Use simple fallback
+      const lockResult = await simpleLock(absolutePath, lockOptions);
+      release = lockResult.release;
+    }
+    
+    const acquireTime = Date.now() - startTime;
+    logger.debug(`Lock acquired: ${absolutePath} (${acquireTime}ms)`);
+    
+    const result = await operation();
+    return result;
+  } catch (err) {
+    const waitTime = Date.now() - startTime;
+    if (err.message.includes('timed out') || err.code === 'ELOCKED') {
+      logger.error(`File locked by another process: ${absolutePath}`, { 
+        waited: waitTime,
+        timeout: lockOptions.timeout || 30000
+      });
+      throw new Error(`File locked: ${filePath} (waited ${waitTime}ms)`);
+    }
+    logger.error(`Lock acquisition failed: ${absolutePath}`, { 
+      error: err.message,
+      waited: waitTime 
+    });
+    throw err;
+  } finally {
+    if (release) {
+      try {
+        await release();
+        logger.debug(`Lock released: ${absolutePath}`);
+      } catch (err) {
+        logger.warn(`Failed to release lock: ${absolutePath}`, { 
+          error: err.message 
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Check if a file is currently locked
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} - True if locked
+ */
+async function isLocked(filePath) {
+  const absolutePath = path.resolve(filePath);
+  
+  if (properLockfile) {
+    if (!fs.existsSync(absolutePath)) {
+      return false;
+    }
+    return properLockfile.check(absolutePath);
+  }
+  
+  // Simple fallback
+  const lockPath = getLockPath(filePath);
+  if (!fs.existsSync(lockPath)) {
+    return false;
+  }
+  
+  // Check if lock is stale
+  try {
+    const stats = fs.statSync(lockPath);
+    const age = Date.now() - stats.mtimeMs;
+    const staleTime = 30000;
+    
+    if (age >= staleTime) {
+      // Lock is stale, remove it
+      fs.unlinkSync(lockPath);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Execute operation only if file is not locked
+ * @param {string} filePath - Path to file
+ * @param {Function} operation - Async function to execute
+ * @param {any} fallback - Value to return if file is locked
+ * @returns {Promise<any>} - Result of operation or fallback
+ */
+async function ifUnlocked(filePath, operation, fallback = null) {
+  const locked = await isLocked(filePath);
+  if (locked) {
+    logger.debug(`File locked, using fallback: ${filePath}`);
+    return fallback;
+  }
+  return withLock(filePath, operation);
+}
+
+module.exports = { withLock, isLocked, ifUnlocked };

package/get-shit-done/bin/lib/frontmatter.cjs

@@ -0,0 +1,299 @@
+/**
+ * Frontmatter — YAML frontmatter parsing, serialization, and CRUD commands
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, output, error } = require('./core.cjs');
+
+// ─── Parsing engine ───────────────────────────────────────────────────────────
+
+function extractFrontmatter(content) {
+  const frontmatter = {};
+  const match = content.match(/^---\n([\s\S]+?)\n---/);
+  if (!match) return frontmatter;
+
+  const yaml = match[1];
+  const lines = yaml.split('\n');
+
+  // Stack to track nested objects: [{obj, key, indent}]
+  // obj = object to write to, key = current key collecting array items, indent = indentation level
+  let stack = [{ obj: frontmatter, key: null, indent: -1 }];
+
+  for (const line of lines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+
+    // Calculate indentation (number of leading spaces)
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+
+    // Pop stack back to appropriate level
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1];
+
+    // Check for key: value pattern
+    const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (keyMatch) {
+      const key = keyMatch[2];
+      const value = keyMatch[3].trim();
+
+      if (value === '' || value === '[') {
+        // Key with no value or opening bracket — could be nested object or array
+        // We'll determine based on next lines, for now create placeholder
+        current.obj[key] = value === '[' ? [] : {};
+        current.key = null;
+        // Push new context for potential nested content
+        stack.push({ obj: current.obj[key], key: null, indent });
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        // Inline array: key: [a, b, c]
+        current.obj[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        current.key = null;
+      } else {
+        // Simple key: value
+        current.obj[key] = value.replace(/^["']|["']$/g, '');
+        current.key = null;
+      }
+    } else if (line.trim().startsWith('- ')) {
+      // Array item
+      const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+
+      // If current context is an empty object, convert to array
+      if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
+        // Find the key in parent that points to this object and convert it
+        const parent = stack.length > 1 ? stack[stack.length - 2] : null;
+        if (parent) {
+          for (const k of Object.keys(parent.obj)) {
+            if (parent.obj[k] === current.obj) {
+              parent.obj[k] = [itemValue];
+              current.obj = parent.obj[k];
+              break;
+            }
+          }
+        }
+      } else if (Array.isArray(current.obj)) {
+        current.obj.push(itemValue);
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+function reconstructFrontmatter(obj) {
+  const lines = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else if (value.every(v => typeof v === 'string') && value.length <= 3 && value.join(', ').length < 60) {
+        lines.push(`${key}: [${value.join(', ')}]`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+        }
+      }
+    } else if (typeof value === 'object') {
+      lines.push(`${key}:`);
+      for (const [subkey, subval] of Object.entries(value)) {
+        if (subval === null || subval === undefined) continue;
+        if (Array.isArray(subval)) {
+          if (subval.length === 0) {
+            lines.push(`  ${subkey}: []`);
+          } else if (subval.every(v => typeof v === 'string') && subval.length <= 3 && subval.join(', ').length < 60) {
+            lines.push(`  ${subkey}: [${subval.join(', ')}]`);
+          } else {
+            lines.push(`  ${subkey}:`);
+            for (const item of subval) {
+              lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+            }
+          }
+        } else if (typeof subval === 'object') {
+          lines.push(`  ${subkey}:`);
+          for (const [subsubkey, subsubval] of Object.entries(subval)) {
+            if (subsubval === null || subsubval === undefined) continue;
+            if (Array.isArray(subsubval)) {
+              if (subsubval.length === 0) {
+                lines.push(`    ${subsubkey}: []`);
+              } else {
+                lines.push(`    ${subsubkey}:`);
+                for (const item of subsubval) {
+                  lines.push(`      - ${item}`);
+                }
+              }
+            } else {
+              lines.push(`    ${subsubkey}: ${subsubval}`);
+            }
+          }
+        } else {
+          const sv = String(subval);
+          lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+        }
+      }
+    } else {
+      const sv = String(value);
+      if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
+        lines.push(`${key}: "${sv}"`);
+      } else {
+        lines.push(`${key}: ${sv}`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+function spliceFrontmatter(content, newObj) {
+  const yamlStr = reconstructFrontmatter(newObj);
+  const match = content.match(/^---\n[\s\S]+?\n---/);
+  if (match) {
+    return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+  }
+  return `---\n${yamlStr}\n---\n\n` + content;
+}
+
+function parseMustHavesBlock(content, blockName) {
+  // Extract a specific block from must_haves in raw frontmatter YAML
+  // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}]
+  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  if (!fmMatch) return [];
+
+  const yaml = fmMatch[1];
+  // Find the block (e.g., "truths:", "artifacts:", "key_links:")
+  const blockPattern = new RegExp(`^\\s{4}${blockName}:\\s*$`, 'm');
+  const blockStart = yaml.search(blockPattern);
+  if (blockStart === -1) return [];
+
+  const afterBlock = yaml.slice(blockStart);
+  const blockLines = afterBlock.split('\n').slice(1); // skip the header line
+
+  const items = [];
+  let current = null;
+
+  for (const line of blockLines) {
+    // Stop at same or lower indent level (non-continuation)
+    if (line.trim() === '') continue;
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (indent <= 4 && line.trim() !== '') break; // back to must_haves level or higher
+
+    if (line.match(/^\s{6}-\s+/)) {
+      // New list item at 6-space indent
+      if (current) items.push(current);
+      current = {};
+      // Check if it's a simple string item
+      const simpleMatch = line.match(/^\s{6}-\s+"?([^"]+)"?\s*$/);
+      if (simpleMatch && !line.includes(':')) {
+        current = simpleMatch[1];
+      } else {
+        // Key-value on same line as dash: "- path: value"
+        const kvMatch = line.match(/^\s{6}-\s+(\w+):\s*"?([^"]*)"?\s*$/);
+        if (kvMatch) {
+          current = {};
+          current[kvMatch[1]] = kvMatch[2];
+        }
+      }
+    } else if (current && typeof current === 'object') {
+      // Continuation key-value at 8+ space indent
+      const kvMatch = line.match(/^\s{8,}(\w+):\s*"?([^"]*)"?\s*$/);
+      if (kvMatch) {
+        const val = kvMatch[2];
+        // Try to parse as number
+        current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+      }
+      // Array items under a key
+      const arrMatch = line.match(/^\s{10,}-\s+"?([^"]+)"?\s*$/);
+      if (arrMatch) {
+        // Find the last key added and convert to array
+        const keys = Object.keys(current);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && !Array.isArray(current[lastKey])) {
+          current[lastKey] = current[lastKey] ? [current[lastKey]] : [];
+        }
+        if (lastKey) current[lastKey].push(arrMatch[1]);
+      }
+    }
+  }
+  if (current) items.push(current);
+
+  return items;
+}
+
+// ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+
+const FRONTMATTER_SCHEMAS = {
+  plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
+  verification: { required: ['phase', 'verified', 'status', 'score'] },
+};
+
+function cmdFrontmatterGet(cwd, filePath, field, raw) {
+  if (!filePath) { error('file path required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  if (field) {
+    const value = fm[field];
+    if (value === undefined) { output({ error: 'Field not found', field }, raw); return; }
+    output({ [field]: value }, raw, JSON.stringify(value));
+  } else {
+    output(fm, raw);
+  }
+}
+
+function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
+  if (!filePath || !field || value === undefined) { error('file, field, and value required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let parsedValue;
+  try { parsedValue = JSON.parse(value); } catch { parsedValue = value; }
+  fm[field] = parsedValue;
+  const newContent = spliceFrontmatter(content, fm);
+  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  output({ updated: true, field, value: parsedValue }, raw, 'true');
+}
+
+function cmdFrontmatterMerge(cwd, filePath, data, raw) {
+  if (!filePath || !data) { error('file and data required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let mergeData;
+  try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; }
+  Object.assign(fm, mergeData);
+  const newContent = spliceFrontmatter(content, fm);
+  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true');
+}
+
+function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
+  if (!filePath || !schemaName) { error('file and schema required'); }
+  const schema = FRONTMATTER_SCHEMAS[schemaName];
+  if (!schema) { error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  const missing = schema.required.filter(f => fm[f] === undefined);
+  const present = schema.required.filter(f => fm[f] !== undefined);
+  output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+}
+
+module.exports = {
+  extractFrontmatter,
+  reconstructFrontmatter,
+  spliceFrontmatter,
+  parseMustHavesBlock,
+  FRONTMATTER_SCHEMAS,
+  cmdFrontmatterGet,
+  cmdFrontmatterSet,
+  cmdFrontmatterMerge,
+  cmdFrontmatterValidate,
+};

package/get-shit-done/bin/lib/fs-utils.cjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+/**
+ * GSD FS Utils — Cross-platform file system utilities
+ * 
+ * Replaces Unix commands (find, grep, head, tail) with
+ * cross-platform JavaScript implementations.
+ * 
+ * Usage:
+ *   const { findFiles, grepContent, readLines } = require('./fs-utils.cjs');
+ *   const files = await findFiles('./src', /\.js$/);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Find files matching patterns (cross-platform find replacement)
+ * @param {string} dir - Directory to search
+ * @param {RegExp[]} patterns - File patterns to match
+ * @param {Object} options - Search options
+ * @returns {string[]} - Array of matching file paths
+ */
+function findFiles(dir, patterns, options = {}) {
+  const { maxDepth = 5, exclude = ['node_modules', '.git', '.planning'] } = options;
+  const results = [];
+
+  function recurse(currentDir, depth) {
+    if (depth > maxDepth) return;
+    
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (err) {
+      logger.warn('Cannot read directory', { dir: currentDir, error: err.message });
+      return;
+    }
+
+    for (const entry of entries) {
+      if (exclude.includes(entry.name)) continue;
+      
+      const fullPath = path.join(currentDir, entry.name);
+      
+      if (entry.isDirectory()) {
+        recurse(fullPath, depth + 1);
+      } else if (patterns.some(p => p.test(entry.name))) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  recurse(dir, 0);
+  return results;
+}
+
+/**
+ * Search file content (cross-platform grep replacement)
+ * @param {string} filePath - File to search
+ * @param {RegExp} pattern - Pattern to match
+ * @returns {Object[]} - Array of { line, lineNumber, match }
+ */
+function grepContent(filePath, pattern) {
+  const results = [];
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    
+    lines.forEach((line, index) => {
+      if (pattern.test(line)) {
+        results.push({
+          line: line.trim(),
+          lineNumber: index + 1,
+          match: line.match(pattern)?.[0]
+        });
+      }
+    });
+  } catch (err) {
+    logger.warn('Cannot read file for grep', { filePath, error: err.message });
+  }
+  
+  return results;
+}
+
+/**
+ * Read first N lines (cross-platform head replacement)
+ * @param {string} filePath - File to read
+ * @param {number} count - Number of lines
+ * @returns {string[]} - Array of lines
+ */
+function readFirstLines(filePath, count = 10) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.split('\n').slice(0, count);
+  } catch (err) {
+    logger.warn('Cannot read file', { filePath, error: err.message });
+    return [];
+  }
+}
+
+/**
+ * Read last N lines (cross-platform tail replacement)
+ * @param {string} filePath - File to read
+ * @param {number} count - Number of lines
+ * @returns {string[]} - Array of lines
+ */
+function readLastLines(filePath, count = 10) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    return lines.slice(-count);
+  } catch (err) {
+    logger.warn('Cannot read file', { filePath, error: err.message });
+    return [];
+  }
+}
+
+/**
+ * Count lines in file (cross-platform wc -l replacement)
+ * @param {string} filePath - File to count
+ * @returns {number} - Line count
+ */
+function countLines(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.split('\n').length;
+  } catch (err) {
+    logger.warn('Cannot count lines', { filePath, error: err.message });
+    return 0;
+  }
+}
+
+/**
+ * Ensure directory exists
+ * @param {string} dirPath - Directory path
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+    logger.debug('Directory created', { dir: dirPath });
+  }
+}
+
+module.exports = {
+  findFiles,
+  grepContent,
+  readFirstLines,
+  readLastLines,
+  countLines,
+  ensureDir
+};