bmad-fh 6.0.0-alpha.052779ef

package/src/core/lib/scope/scope-validator.js

@@ -0,0 +1,294 @@
+const yaml = require('yaml');
+
+/**
+ * Validates scope configuration and enforces schema rules
+ * @class ScopeValidator
+ */
+class ScopeValidator {
+  constructor() {
+    // Scope ID validation pattern: lowercase alphanumeric + hyphens, 2-50 chars
+
+    // Reserved scope IDs that cannot be used
+    this.reservedIds = ['_shared', '_events', '_config', 'global', 'default'];
+
+    // Valid isolation modes
+    this.validIsolationModes = ['strict', 'warn', 'permissive'];
+
+    // Valid scope statuses
+    this.validStatuses = ['active', 'archived'];
+  }
+
+  /**
+   * Validates a scope ID format
+   * @param {string} scopeId - The scope ID to validate
+   * @returns {{valid: boolean, error: string|null}}
+   */
+  validateScopeId(scopeId) {
+    // Check if provided
+    if (!scopeId || typeof scopeId !== 'string') {
+      return { valid: false, error: 'Scope ID is required and must be a string' };
+    }
+
+    // Check length
+    if (scopeId.length < 2 || scopeId.length > 50) {
+      return { valid: false, error: 'Scope ID must be between 2 and 50 characters' };
+    }
+
+    // Check pattern
+    if (!this.scopeIdPattern.test(scopeId)) {
+      return {
+        valid: false,
+        error:
+          'Scope ID must start with lowercase letter, contain only lowercase letters, numbers, and hyphens, and end with letter or number',
+      };
+    }
+
+    // Check reserved IDs
+    if (this.reservedIds.includes(scopeId)) {
+      return {
+        valid: false,
+        error: `Scope ID '${scopeId}' is reserved and cannot be used`,
+      };
+    }
+
+    return { valid: true, error: null };
+  }
+
+  /**
+   * Validates a complete scope configuration object
+   * @param {object} scope - The scope configuration to validate
+   * @param {object} allScopes - All existing scopes for dependency validation
+   * @returns {{valid: boolean, errors: string[]}}
+   */
+  validateScope(scope, allScopes = {}) {
+    const errors = [];
+
+    // Validate ID
+    const idValidation = this.validateScopeId(scope.id);
+    if (!idValidation.valid) {
+      errors.push(idValidation.error);
+    }
+
+    // Validate name
+    if (!scope.name || typeof scope.name !== 'string' || scope.name.trim().length === 0) {
+      errors.push('Scope name is required and must be a non-empty string');
+    }
+
+    // Validate description (optional but if provided must be string)
+    if (scope.description !== undefined && typeof scope.description !== 'string') {
+      errors.push('Scope description must be a string');
+    }
+
+    // Validate status
+    if (scope.status && !this.validStatuses.includes(scope.status)) {
+      errors.push(`Invalid status '${scope.status}'. Must be one of: ${this.validStatuses.join(', ')}`);
+    }
+
+    // Validate dependencies
+    if (scope.dependencies) {
+      if (Array.isArray(scope.dependencies)) {
+        // Check each dependency exists
+        for (const dep of scope.dependencies) {
+          if (typeof dep !== 'string') {
+            errors.push(`Dependency '${dep}' must be a string`);
+            continue;
+          }
+
+          // Check dependency exists
+          if (!allScopes[dep]) {
+            errors.push(`Dependency '${dep}' does not exist`);
+          }
+
+          // Check for self-dependency
+          if (dep === scope.id) {
+            errors.push(`Scope cannot depend on itself`);
+          }
+        }
+
+        // Check for circular dependencies
+        const circularCheck = this.detectCircularDependencies(scope.id, scope.dependencies, allScopes);
+        if (circularCheck.hasCircular) {
+          errors.push(`Circular dependency detected: ${circularCheck.chain.join(' → ')}`);
+        }
+      } else {
+        errors.push('Scope dependencies must be an array');
+      }
+    }
+
+    // Validate created timestamp (if provided)
+    if (scope.created) {
+      const date = new Date(scope.created);
+      if (isNaN(date.getTime())) {
+        errors.push('Invalid created timestamp format. Use ISO 8601 format.');
+      }
+    }
+
+    // Validate metadata
+    if (scope._meta) {
+      if (typeof scope._meta === 'object') {
+        if (scope._meta.last_activity) {
+          const date = new Date(scope._meta.last_activity);
+          if (isNaN(date.getTime())) {
+            errors.push('Invalid _meta.last_activity timestamp format');
+          }
+        }
+        if (scope._meta.artifact_count !== undefined && (!Number.isInteger(scope._meta.artifact_count) || scope._meta.artifact_count < 0)) {
+          errors.push('_meta.artifact_count must be a non-negative integer');
+        }
+      } else {
+        errors.push('Scope _meta must be an object');
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Detects circular dependencies in scope dependency chain
+   * @param {string} scopeId - The scope ID to check
+   * @param {string[]} dependencies - Direct dependencies of the scope
+   * @param {object} allScopes - All existing scopes
+   * @param {Set} visited - Set of already visited scopes (for recursion)
+   * @param {string[]} chain - Current dependency chain (for error reporting)
+   * @returns {{hasCircular: boolean, chain: string[]}}
+   */
+  detectCircularDependencies(scopeId, dependencies, allScopes, visited = new Set(), chain = []) {
+    // Add current scope to visited set and chain
+    visited.add(scopeId);
+    chain.push(scopeId);
+
+    if (!dependencies || dependencies.length === 0) {
+      return { hasCircular: false, chain: [] };
+    }
+
+    for (const dep of dependencies) {
+      // Check if we've already visited this dependency (circular!)
+      if (visited.has(dep)) {
+        return { hasCircular: true, chain: [...chain, dep] };
+      }
+
+      // Recursively check this dependency's dependencies
+      const depScope = allScopes[dep];
+      if (depScope && depScope.dependencies) {
+        const result = this.detectCircularDependencies(dep, depScope.dependencies, allScopes, new Set(visited), [...chain]);
+        if (result.hasCircular) {
+          return result;
+        }
+      }
+    }
+
+    return { hasCircular: false, chain: [] };
+  }
+
+  /**
+   * Validates complete scopes.yaml configuration
+   * @param {object} config - The complete scopes configuration
+   * @returns {{valid: boolean, errors: string[]}}
+   */
+  validateConfig(config) {
+    const errors = [];
+
+    // Validate version
+    if (!config.version || typeof config.version !== 'number') {
+      errors.push('Configuration version is required and must be a number');
+    }
+
+    // Validate settings
+    if (config.settings) {
+      if (typeof config.settings === 'object') {
+        // Validate isolation_mode
+        if (config.settings.isolation_mode && !this.validIsolationModes.includes(config.settings.isolation_mode)) {
+          errors.push(`Invalid isolation_mode '${config.settings.isolation_mode}'. Must be one of: ${this.validIsolationModes.join(', ')}`);
+        }
+
+        // Validate allow_adhoc_scopes
+        if (config.settings.allow_adhoc_scopes !== undefined && typeof config.settings.allow_adhoc_scopes !== 'boolean') {
+          errors.push('allow_adhoc_scopes must be a boolean');
+        }
+
+        // Validate paths
+        if (config.settings.default_output_base && typeof config.settings.default_output_base !== 'string') {
+          errors.push('default_output_base must be a string');
+        }
+        if (config.settings.default_shared_path && typeof config.settings.default_shared_path !== 'string') {
+          errors.push('default_shared_path must be a string');
+        }
+      } else {
+        errors.push('Settings must be an object');
+      }
+    }
+
+    // Validate scopes object
+    if (config.scopes) {
+      if (typeof config.scopes !== 'object' || Array.isArray(config.scopes)) {
+        errors.push('Scopes must be an object (not an array)');
+      } else {
+        // Validate each scope
+        for (const [scopeId, scopeConfig] of Object.entries(config.scopes)) {
+          // Check ID matches key
+          if (scopeConfig.id !== scopeId) {
+            errors.push(`Scope key '${scopeId}' does not match scope.id '${scopeConfig.id}'`);
+          }
+
+          // Validate the scope
+          const scopeValidation = this.validateScope(scopeConfig, config.scopes);
+          if (!scopeValidation.valid) {
+            errors.push(`Scope '${scopeId}': ${scopeValidation.errors.join(', ')}`);
+          }
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Validates scopes.yaml file content
+   * @param {string} yamlContent - The YAML file content as string
+   * @returns {{valid: boolean, errors: string[], config: object|null}}
+   */
+  validateYamlContent(yamlContent) {
+    try {
+      const config = yaml.parse(yamlContent);
+      const validation = this.validateConfig(config);
+
+      return {
+        valid: validation.valid,
+        errors: validation.errors,
+        config: validation.valid ? config : null,
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [`Failed to parse YAML: ${error.message}`],
+        config: null,
+      };
+    }
+  }
+
+  /**
+   * Creates a default valid scopes.yaml configuration
+   * @returns {object} Default configuration object
+   */
+  createDefaultConfig() {
+    return {
+      version: 1,
+      settings: {
+        allow_adhoc_scopes: true,
+        isolation_mode: 'strict',
+        default_output_base: '_bmad-output',
+        default_shared_path: '_bmad-output/_shared',
+      },
+      scopes: {},
+    };
+  }
+  scopeIdPattern = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+}
+
+module.exports = { ScopeValidator };

package/src/core/lib/scope/state-lock.js

@@ -0,0 +1,336 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+
+/**
+ * File locking utilities for safe concurrent access to state files
+ * Uses file-based locking for cross-process synchronization
+ *
+ * @class StateLock
+ * @requires fs-extra
+ * @requires yaml
+ *
+ * @example
+ * const lock = new StateLock();
+ * const result = await lock.withLock('/path/to/state.yaml', async () => {
+ *   // Safe operations here
+ *   return data;
+ * });
+ */
+class StateLock {
+  constructor(options = {}) {
+    this.staleTimeout = options.staleTimeout || 30_000; // 30 seconds
+    this.retries = options.retries || 10;
+    this.minTimeout = options.minTimeout || 100;
+    this.maxTimeout = options.maxTimeout || 1000;
+    this.lockExtension = options.lockExtension || '.lock';
+  }
+
+  /**
+   * Get lock file path for a given file
+   * @param {string} filePath - The file to lock
+   * @returns {string} Lock file path
+   */
+  getLockPath(filePath) {
+    return `${filePath}${this.lockExtension}`;
+  }
+
+  /**
+   * Check if a lock file is stale
+   * @param {string} lockPath - Path to lock file
+   * @returns {Promise<boolean>} True if lock is stale
+   */
+  async isLockStale(lockPath) {
+    try {
+      const stat = await fs.stat(lockPath);
+      const age = Date.now() - stat.mtimeMs;
+      return age > this.staleTimeout;
+    } catch {
+      return true; // If we can't stat, consider it stale
+    }
+  }
+
+  /**
+   * Acquire a lock on a file
+   * @param {string} filePath - The file to lock
+   * @returns {Promise<{success: boolean, lockPath: string}>}
+   */
+  async acquireLock(filePath) {
+    const lockPath = this.getLockPath(filePath);
+
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        // Check if lock exists
+        const lockExists = await fs.pathExists(lockPath);
+
+        if (lockExists) {
+          // Check if lock is stale
+          const isStale = await this.isLockStale(lockPath);
+
+          if (isStale) {
+            // Remove stale lock
+            await fs.remove(lockPath);
+          } else {
+            // Lock is active, wait and retry
+            const waitTime = Math.min(this.minTimeout * Math.pow(2, attempt), this.maxTimeout);
+            await this.sleep(waitTime);
+            continue;
+          }
+        }
+
+        // Try to create lock file atomically
+        const lockContent = {
+          pid: process.pid,
+          hostname: require('node:os').hostname(),
+          created: new Date().toISOString(),
+        };
+
+        // Use exclusive flag for atomic creation
+        await fs.writeFile(lockPath, JSON.stringify(lockContent), {
+          flag: 'wx', // Exclusive create
+        });
+
+        return { success: true, lockPath };
+      } catch (error) {
+        if (error.code === 'EEXIST') {
+          // Lock was created by another process, retry
+          const waitTime = Math.min(this.minTimeout * Math.pow(2, attempt), this.maxTimeout);
+          await this.sleep(waitTime);
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    return { success: false, lockPath, reason: 'Max retries exceeded' };
+  }
+
+  /**
+   * Release a lock on a file
+   * @param {string} filePath - The file that was locked
+   * @returns {Promise<boolean>} True if lock was released
+   */
+  async releaseLock(filePath) {
+    const lockPath = this.getLockPath(filePath);
+
+    try {
+      await fs.remove(lockPath);
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return true; // Lock already gone
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Execute operation with file lock
+   * @param {string} filePath - File to lock
+   * @param {function} operation - Async operation to perform
+   * @returns {Promise<any>} Result of operation
+   */
+  async withLock(filePath, operation) {
+    const lockResult = await this.acquireLock(filePath);
+
+    if (!lockResult.success) {
+      throw new Error(`Failed to acquire lock on ${filePath}: ${lockResult.reason}`);
+    }
+
+    try {
+      return await operation();
+    } finally {
+      await this.releaseLock(filePath);
+    }
+  }
+
+  /**
+   * Read YAML file with version tracking
+   * @param {string} filePath - Path to YAML file
+   * @returns {Promise<object>} Parsed content with _version
+   */
+  async readYaml(filePath) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      const data = yaml.parse(content);
+
+      // Ensure version field exists
+      if (!data._version) {
+        data._version = 0;
+      }
+
+      return data;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return { _version: 0 };
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Write YAML file with version increment
+   * @param {string} filePath - Path to YAML file
+   * @param {object} data - Data to write
+   * @returns {Promise<object>} Written data with new version
+   */
+  async writeYaml(filePath, data) {
+    // Ensure directory exists
+    await fs.ensureDir(path.dirname(filePath));
+
+    // Update version and timestamp
+    const versionedData = {
+      ...data,
+      _version: (data._version || 0) + 1,
+      _lastModified: new Date().toISOString(),
+    };
+
+    const yamlContent = yaml.stringify(versionedData, { indent: 2 });
+    await fs.writeFile(filePath, yamlContent, 'utf8');
+
+    return versionedData;
+  }
+
+  /**
+   * Update YAML file with automatic version management and locking
+   * @param {string} filePath - Path to YAML file
+   * @param {function} modifier - Function that receives data and returns modified data
+   * @returns {Promise<object>} Updated data
+   */
+  async updateYamlWithVersion(filePath, modifier) {
+    return this.withLock(filePath, async () => {
+      // Read current data
+      const data = await this.readYaml(filePath);
+      const currentVersion = data._version || 0;
+
+      // Apply modifications
+      const modified = await modifier(data);
+
+      // Update version
+      modified._version = currentVersion + 1;
+      modified._lastModified = new Date().toISOString();
+
+      // Write back
+      await this.writeYaml(filePath, modified);
+
+      return modified;
+    });
+  }
+
+  /**
+   * Optimistic update with version check
+   * @param {string} filePath - Path to YAML file
+   * @param {number} expectedVersion - Expected version number
+   * @param {object} newData - New data to write
+   * @returns {Promise<{success: boolean, data: object, conflict: boolean}>}
+   */
+  async optimisticUpdate(filePath, expectedVersion, newData) {
+    return this.withLock(filePath, async () => {
+      const current = await this.readYaml(filePath);
+
+      // Check version
+      if (current._version !== expectedVersion) {
+        return {
+          success: false,
+          data: current,
+          conflict: true,
+          message: `Version conflict: expected ${expectedVersion}, found ${current._version}`,
+        };
+      }
+
+      // Update with new version
+      const updated = {
+        ...newData,
+        _version: expectedVersion + 1,
+        _lastModified: new Date().toISOString(),
+      };
+
+      await this.writeYaml(filePath, updated);
+
+      return {
+        success: true,
+        data: updated,
+        conflict: false,
+      };
+    });
+  }
+
+  /**
+   * Sleep helper
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Check if a file is currently locked
+   * @param {string} filePath - The file to check
+   * @returns {Promise<boolean>} True if locked
+   */
+  async isLocked(filePath) {
+    const lockPath = this.getLockPath(filePath);
+
+    try {
+      const exists = await fs.pathExists(lockPath);
+
+      if (!exists) {
+        return false;
+      }
+
+      // Check if lock is stale
+      const isStale = await this.isLockStale(lockPath);
+      return !isStale;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get lock information
+   * @param {string} filePath - The file to check
+   * @returns {Promise<object|null>} Lock info or null
+   */
+  async getLockInfo(filePath) {
+    const lockPath = this.getLockPath(filePath);
+
+    try {
+      const exists = await fs.pathExists(lockPath);
+
+      if (!exists) {
+        return null;
+      }
+
+      const content = await fs.readFile(lockPath, 'utf8');
+      const info = JSON.parse(content);
+      const stat = await fs.stat(lockPath);
+
+      return {
+        ...info,
+        age: Date.now() - stat.mtimeMs,
+        isStale: Date.now() - stat.mtimeMs > this.staleTimeout,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Force release a lock (use with caution)
+   * @param {string} filePath - The file to unlock
+   * @returns {Promise<boolean>} True if lock was removed
+   */
+  async forceRelease(filePath) {
+    const lockPath = this.getLockPath(filePath);
+
+    try {
+      await fs.remove(lockPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = { StateLock };

package/src/core/module.yaml

@@ -0,0 +1,53 @@
+code: core
+name: "BMad Core Module"
+
+header: "BMad Core Configuration"
+subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all modules and agents."
+
+user_name:
+  prompt: "What should agents call you? (Use your name or a team name)"
+  default: "BMad"
+  result: "{value}"
+
+communication_language:
+  prompt: "What language should agents use when chatting with you?"
+  default: "English"
+  result: "{value}"
+
+document_output_language:
+  prompt: "Preferred document output language?"
+  default: "English"
+  result: "{value}"
+
+output_folder:
+  prompt: "Where should output files be saved?"
+  default: "_bmad-output"
+  result: "{project-root}/{value}"
+
+# Scope System Configuration
+# These settings control the multi-scope parallel artifact system
+scope_settings:
+  header: "Scope System Settings"
+  subheader: "Configure multi-scope artifact isolation"
+
+  allow_adhoc_scopes:
+    prompt: "Allow creating scopes on-demand during workflows?"
+    default: true
+    result: "{value}"
+
+  isolation_mode:
+    prompt: "Scope isolation mode"
+    default: "strict"
+    result: "{value}"
+    single-select:
+      - value: "strict"
+        label: "Strict - Block cross-scope writes, require explicit sync"
+      - value: "warn"
+        label: "Warn - Allow cross-scope writes with warnings"
+      - value: "permissive"
+        label: "Permissive - Allow all operations (not recommended)"
+
+  shared_path:
+    prompt: "Where should shared knowledge artifacts be stored?"
+    default: "{output_folder}/_shared"
+    result: "{project-root}/{value}"