bmad-fh 6.0.0-alpha.23

package/src/core/lib/scope/artifact-resolver.js

@@ -0,0 +1,298 @@
+const path = require('node:path');
+
+/**
+ * Resolves and enforces scope-based artifact access
+ * Implements read-any/write-own access model
+ * 
+ * @class ArtifactResolver
+ * 
+ * @example
+ * const resolver = new ArtifactResolver({
+ *   currentScope: 'auth',
+ *   basePath: '/path/to/_bmad-output'
+ * });
+ * 
+ * if (resolver.canWrite('/path/to/_bmad-output/auth/file.md')) {
+ *   // Write operation allowed
+ * }
+ */
+class ArtifactResolver {
+  constructor(options = {}) {
+    this.currentScope = options.currentScope || null;
+    this.basePath = options.basePath || '_bmad-output';
+    this.isolationMode = options.isolationMode || 'strict'; // strict | warn | permissive
+    this.sharedPath = '_shared';
+    this.reservedPaths = ['_shared', '_events', '_config', '_backup'];
+  }
+
+  /**
+   * Set the current scope
+   * @param {string} scopeId - The current scope ID
+   */
+  setCurrentScope(scopeId) {
+    this.currentScope = scopeId;
+  }
+
+  /**
+   * Set isolation mode
+   * @param {string} mode - Isolation mode (strict, warn, permissive)
+   */
+  setIsolationMode(mode) {
+    if (!['strict', 'warn', 'permissive'].includes(mode)) {
+      throw new Error(`Invalid isolation mode: ${mode}`);
+    }
+    this.isolationMode = mode;
+  }
+
+  /**
+   * Extract scope from a file path
+   * @param {string} filePath - The file path to analyze
+   * @returns {string|null} Scope ID or null if not in a scope
+   */
+  extractScopeFromPath(filePath) {
+    // Normalize path
+    const normalizedPath = path.normalize(filePath);
+    
+    // Find the base path in the file path
+    const baseIndex = normalizedPath.indexOf(this.basePath);
+    if (baseIndex === -1) {
+      return null; // Not in output directory
+    }
+
+    // Get the relative path from base
+    const relativePath = normalizedPath.slice(Math.max(0, baseIndex + this.basePath.length + 1));
+    
+    // Split to get the first segment (scope name)
+    const segments = relativePath.split(path.sep).filter(Boolean);
+    
+    if (segments.length === 0) {
+      return null;
+    }
+
+    const firstSegment = segments[0];
+    
+    // Check if it's a reserved path
+    if (this.reservedPaths.includes(firstSegment)) {
+      return firstSegment; // Return the reserved path name
+    }
+
+    return firstSegment;
+  }
+
+  /**
+   * Check if a path is in the shared directory
+   * @param {string} filePath - The file path
+   * @returns {boolean} True if path is in shared
+   */
+  isSharedPath(filePath) {
+    const scope = this.extractScopeFromPath(filePath);
+    return scope === this.sharedPath;
+  }
+
+  /**
+   * Check if a path is in a reserved directory
+   * @param {string} filePath - The file path
+   * @returns {boolean} True if path is reserved
+   */
+  isReservedPath(filePath) {
+    const scope = this.extractScopeFromPath(filePath);
+    return this.reservedPaths.includes(scope);
+  }
+
+  /**
+   * Check if read access is allowed to a path
+   * Read is always allowed in read-any model
+   * @param {string} filePath - The file path to check
+   * @returns {{allowed: boolean, reason: string}}
+   */
+  canRead(filePath) {
+    // Read is always allowed for all paths
+    return {
+      allowed: true,
+      reason: 'Read access is always allowed in read-any model'
+    };
+  }
+
+  /**
+   * Check if write access is allowed to a path
+   * @param {string} filePath - The file path to check
+   * @returns {{allowed: boolean, reason: string, warning: string|null}}
+   */
+  canWrite(filePath) {
+    // No current scope means legacy mode - allow all
+    if (!this.currentScope) {
+      return {
+        allowed: true,
+        reason: 'No scope active, operating in legacy mode',
+        warning: null
+      };
+    }
+
+    const targetScope = this.extractScopeFromPath(filePath);
+
+    // Check for shared path write attempt
+    if (targetScope === this.sharedPath) {
+      return {
+        allowed: false,
+        reason: `Cannot write directly to '${this.sharedPath}'. Use: bmad scope sync-up`,
+        warning: null
+      };
+    }
+
+    // Check for reserved path write attempt
+    if (this.reservedPaths.includes(targetScope) && targetScope !== this.currentScope) {
+      return {
+        allowed: false,
+        reason: `Cannot write to reserved path '${targetScope}'`,
+        warning: null
+      };
+    }
+
+    // Check if writing to current scope
+    if (targetScope === this.currentScope) {
+      return {
+        allowed: true,
+        reason: `Write allowed to current scope '${this.currentScope}'`,
+        warning: null
+      };
+    }
+
+    // Cross-scope write attempt
+    if (targetScope && targetScope !== this.currentScope) {
+      switch (this.isolationMode) {
+        case 'strict': {
+          return {
+            allowed: false,
+            reason: `Cannot write to scope '${targetScope}' while in scope '${this.currentScope}'`,
+            warning: null
+          };
+        }
+        
+        case 'warn': {
+          return {
+            allowed: true,
+            reason: 'Write allowed with warning in warn mode',
+            warning: `Warning: Writing to scope '${targetScope}' from scope '${this.currentScope}'`
+          };
+        }
+        
+        case 'permissive': {
+          return {
+            allowed: true,
+            reason: 'Write allowed in permissive mode',
+            warning: null
+          };
+        }
+        
+        default: {
+          return {
+            allowed: false,
+            reason: 'Unknown isolation mode',
+            warning: null
+          };
+        }
+      }
+    }
+
+    // Path not in any scope - allow (it's outside the scope system)
+    return {
+      allowed: true,
+      reason: 'Path is outside scope system',
+      warning: null
+    };
+  }
+
+  /**
+   * Validate a write operation and throw if not allowed
+   * @param {string} filePath - The file path to write to
+   * @throws {Error} If write is not allowed in strict mode
+   */
+  validateWrite(filePath) {
+    const result = this.canWrite(filePath);
+    
+    if (!result.allowed) {
+      throw new Error(result.reason);
+    }
+    
+    if (result.warning) {
+      console.warn(result.warning);
+    }
+  }
+
+  /**
+   * Resolve a scope-relative path to absolute path
+   * @param {string} relativePath - Relative path within scope
+   * @param {string} scopeId - Scope ID (defaults to current)
+   * @returns {string} Absolute path
+   */
+  resolveScopePath(relativePath, scopeId = null) {
+    const scope = scopeId || this.currentScope;
+    
+    if (!scope) {
+      // No scope - return path relative to base
+      return path.join(this.basePath, relativePath);
+    }
+
+    return path.join(this.basePath, scope, relativePath);
+  }
+
+  /**
+   * Resolve path to shared directory
+   * @param {string} relativePath - Relative path within shared
+   * @returns {string} Absolute path to shared
+   */
+  resolveSharedPath(relativePath) {
+    return path.join(this.basePath, this.sharedPath, relativePath);
+  }
+
+  /**
+   * Get all paths accessible for reading from current scope
+   * @returns {object} Object with path categories
+   */
+  getReadablePaths() {
+    return {
+      currentScope: this.currentScope ? path.join(this.basePath, this.currentScope) : null,
+      shared: path.join(this.basePath, this.sharedPath),
+      allScopes: `${this.basePath}/*`,
+      description: 'Read access is allowed to all scopes and shared directories'
+    };
+  }
+
+  /**
+   * Get paths writable from current scope
+   * @returns {object} Object with writable paths
+   */
+  getWritablePaths() {
+    if (!this.currentScope) {
+      return {
+        all: this.basePath,
+        description: 'No scope active - all paths writable (legacy mode)'
+      };
+    }
+
+    return {
+      currentScope: path.join(this.basePath, this.currentScope),
+      description: `Write access limited to scope '${this.currentScope}'`
+    };
+  }
+
+  /**
+   * Check if current operation context is valid
+   * @returns {boolean} True if context is properly set up
+   */
+  isContextValid() {
+    return this.basePath !== null;
+  }
+
+  /**
+   * Create a scoped path resolver for a specific scope
+   * @param {string} scopeId - The scope ID
+   * @returns {function} Path resolver function
+   */
+  createScopedResolver(scopeId) {
+    const base = this.basePath;
+    return (relativePath) => path.join(base, scopeId, relativePath);
+  }
+}
+
+module.exports = { ArtifactResolver };

package/src/core/lib/scope/event-logger.js

@@ -0,0 +1,411 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const { StateLock } = require('./state-lock');
+
+/**
+ * Logs and tracks events across scopes
+ * Handles event logging and subscription notifications
+ * 
+ * @class EventLogger
+ * @requires fs-extra
+ * @requires yaml
+ * @requires StateLock
+ * 
+ * @example
+ * const logger = new EventLogger({ projectRoot: '/path/to/project' });
+ * await logger.logEvent('artifact_created', 'auth', { artifact: 'prd.md' });
+ */
+class EventLogger {
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.bmadPath = path.join(this.projectRoot, '_bmad');
+    this.eventsPath = path.join(this.bmadPath, '_events');
+    this.eventLogPath = path.join(this.eventsPath, 'event-log.yaml');
+    this.subscriptionsPath = path.join(this.eventsPath, 'subscriptions.yaml');
+    this.stateLock = new StateLock();
+    this.maxEvents = options.maxEvents || 1000; // Rotate after this many events
+  }
+
+  /**
+   * Set the project root directory
+   * @param {string} projectRoot - The project root path
+   */
+  setProjectRoot(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.bmadPath = path.join(projectRoot, '_bmad');
+    this.eventsPath = path.join(this.bmadPath, '_events');
+    this.eventLogPath = path.join(this.eventsPath, 'event-log.yaml');
+    this.subscriptionsPath = path.join(this.eventsPath, 'subscriptions.yaml');
+  }
+
+  /**
+   * Initialize event system
+   * Creates event directories and files if they don't exist
+   */
+  async initialize() {
+    await fs.ensureDir(this.eventsPath);
+
+    // Create event-log.yaml if not exists
+    if (!await fs.pathExists(this.eventLogPath)) {
+      const eventLog = {
+        version: 1,
+        events: []
+      };
+      await fs.writeFile(this.eventLogPath, yaml.stringify(eventLog), 'utf8');
+    }
+
+    // Create subscriptions.yaml if not exists
+    if (!await fs.pathExists(this.subscriptionsPath)) {
+      const subscriptions = {
+        version: 1,
+        subscriptions: {}
+      };
+      await fs.writeFile(this.subscriptionsPath, yaml.stringify(subscriptions), 'utf8');
+    }
+  }
+
+  /**
+   * Generate unique event ID
+   * @returns {string} Event ID
+   */
+  generateEventId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 8);
+    return `evt_${timestamp}_${random}`;
+  }
+
+  /**
+   * Log an event
+   * @param {string} type - Event type
+   * @param {string} scopeId - Source scope ID
+   * @param {object} data - Event data
+   * @returns {Promise<object>} Created event
+   */
+  async logEvent(type, scopeId, data = {}) {
+    const event = {
+      id: this.generateEventId(),
+      type,
+      scope: scopeId,
+      timestamp: new Date().toISOString(),
+      data
+    };
+
+    return this.stateLock.withLock(this.eventLogPath, async () => {
+      const content = await fs.readFile(this.eventLogPath, 'utf8');
+      const log = yaml.parse(content);
+
+      // Add event
+      log.events.push(event);
+
+      // Rotate if needed
+      if (log.events.length > this.maxEvents) {
+        // Keep only recent events
+        log.events = log.events.slice(-this.maxEvents);
+      }
+
+      await fs.writeFile(this.eventLogPath, yaml.stringify(log), 'utf8');
+      return event;
+    });
+  }
+
+  /**
+   * Get events for a scope
+   * @param {string} scopeId - Scope ID
+   * @param {object} options - Filter options
+   * @returns {Promise<object[]>} Array of events
+   */
+  async getEvents(scopeId = null, options = {}) {
+    try {
+      const content = await fs.readFile(this.eventLogPath, 'utf8');
+      const log = yaml.parse(content);
+      let events = log.events || [];
+
+      // Filter by scope
+      if (scopeId) {
+        events = events.filter(e => e.scope === scopeId);
+      }
+
+      // Filter by type
+      if (options.type) {
+        events = events.filter(e => e.type === options.type);
+      }
+
+      // Filter by time range
+      if (options.since) {
+        const sinceDate = new Date(options.since);
+        events = events.filter(e => new Date(e.timestamp) >= sinceDate);
+      }
+
+      if (options.until) {
+        const untilDate = new Date(options.until);
+        events = events.filter(e => new Date(e.timestamp) <= untilDate);
+      }
+
+      // Limit results
+      if (options.limit) {
+        events = events.slice(-options.limit);
+      }
+
+      return events;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Subscribe a scope to events from other scopes
+   * @param {string} subscriberScope - Scope that wants to receive events
+   * @param {string} watchScope - Scope to watch
+   * @param {string[]} patterns - Artifact patterns to watch
+   * @param {object} options - Subscription options
+   */
+  async subscribe(subscriberScope, watchScope, patterns = ['*'], options = {}) {
+    return this.stateLock.withLock(this.subscriptionsPath, async () => {
+      const content = await fs.readFile(this.subscriptionsPath, 'utf8');
+      const subs = yaml.parse(content);
+
+      // Initialize subscriber if not exists
+      if (!subs.subscriptions[subscriberScope]) {
+        subs.subscriptions[subscriberScope] = {
+          watch: [],
+          notify: true
+        };
+      }
+
+      // Add or update watch entry
+      const existingWatch = subs.subscriptions[subscriberScope].watch.find(
+        w => w.scope === watchScope
+      );
+
+      if (existingWatch) {
+        existingWatch.patterns = patterns;
+      } else {
+        subs.subscriptions[subscriberScope].watch.push({
+          scope: watchScope,
+          patterns
+        });
+      }
+
+      if (options.notify !== undefined) {
+        subs.subscriptions[subscriberScope].notify = options.notify;
+      }
+
+      await fs.writeFile(this.subscriptionsPath, yaml.stringify(subs), 'utf8');
+    });
+  }
+
+  /**
+   * Unsubscribe from a scope
+   * @param {string} subscriberScope - Subscriber scope
+   * @param {string} watchScope - Scope to stop watching
+   */
+  async unsubscribe(subscriberScope, watchScope) {
+    return this.stateLock.withLock(this.subscriptionsPath, async () => {
+      const content = await fs.readFile(this.subscriptionsPath, 'utf8');
+      const subs = yaml.parse(content);
+
+      if (subs.subscriptions[subscriberScope]) {
+        subs.subscriptions[subscriberScope].watch = 
+          subs.subscriptions[subscriberScope].watch.filter(w => w.scope !== watchScope);
+      }
+
+      await fs.writeFile(this.subscriptionsPath, yaml.stringify(subs), 'utf8');
+    });
+  }
+
+  /**
+   * Get subscriptions for a scope
+   * @param {string} scopeId - Scope ID
+   * @returns {Promise<object>} Subscription data
+   */
+  async getSubscriptions(scopeId) {
+    try {
+      const content = await fs.readFile(this.subscriptionsPath, 'utf8');
+      const subs = yaml.parse(content);
+      return subs.subscriptions[scopeId] || { watch: [], notify: true };
+    } catch {
+      return { watch: [], notify: true };
+    }
+  }
+
+  /**
+   * Get pending notifications for a scope
+   * Events from watched scopes since last activity
+   * @param {string} scopeId - Scope ID
+   * @param {string} since - ISO timestamp to check from
+   * @returns {Promise<object[]>} Array of relevant events
+   */
+  async getPendingNotifications(scopeId, since = null) {
+    try {
+      const subs = await this.getSubscriptions(scopeId);
+      
+      if (!subs.notify || subs.watch.length === 0) {
+        return [];
+      }
+
+      const notifications = [];
+      
+      for (const watch of subs.watch) {
+        const events = await this.getEvents(watch.scope, {
+          since: since || new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString() // Last 24h default
+        });
+
+        for (const event of events) {
+          // Check if event matches any pattern
+          const matches = watch.patterns.some(pattern => 
+            this.matchesPattern(event.data?.artifact, pattern)
+          );
+
+          if (matches || watch.patterns.includes('*')) {
+            notifications.push({
+              ...event,
+              watchedBy: scopeId,
+              pattern: watch.patterns
+            });
+          }
+        }
+      }
+
+      // Sort by timestamp
+      notifications.sort((a, b) => 
+        new Date(a.timestamp) - new Date(b.timestamp)
+      );
+
+      return notifications;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Check if artifact matches pattern
+   * @param {string} artifact - Artifact path
+   * @param {string} pattern - Pattern to match
+   * @returns {boolean} True if matches
+   */
+  matchesPattern(artifact, pattern) {
+    if (!artifact) return false;
+    if (pattern === '*') return true;
+    
+    const regexPattern = pattern
+      .replaceAll('.', String.raw`\.`)
+      .replaceAll('*', '.*');
+    const regex = new RegExp(regexPattern);
+    return regex.test(artifact);
+  }
+
+  /**
+   * Common event types
+   */
+  static EventTypes = {
+    ARTIFACT_CREATED: 'artifact_created',
+    ARTIFACT_UPDATED: 'artifact_updated',
+    ARTIFACT_DELETED: 'artifact_deleted',
+    ARTIFACT_PROMOTED: 'artifact_promoted',
+    SCOPE_CREATED: 'scope_created',
+    SCOPE_ARCHIVED: 'scope_archived',
+    SCOPE_ACTIVATED: 'scope_activated',
+    SYNC_UP: 'sync_up',
+    SYNC_DOWN: 'sync_down',
+    WORKFLOW_STARTED: 'workflow_started',
+    WORKFLOW_COMPLETED: 'workflow_completed'
+  };
+
+  /**
+   * Log artifact creation event
+   * @param {string} scopeId - Scope ID
+   * @param {string} artifact - Artifact path
+   * @param {object} metadata - Additional metadata
+   */
+  async logArtifactCreated(scopeId, artifact, metadata = {}) {
+    return this.logEvent(EventLogger.EventTypes.ARTIFACT_CREATED, scopeId, {
+      artifact,
+      ...metadata
+    });
+  }
+
+  /**
+   * Log artifact update event
+   * @param {string} scopeId - Scope ID
+   * @param {string} artifact - Artifact path
+   * @param {object} metadata - Additional metadata
+   */
+  async logArtifactUpdated(scopeId, artifact, metadata = {}) {
+    return this.logEvent(EventLogger.EventTypes.ARTIFACT_UPDATED, scopeId, {
+      artifact,
+      ...metadata
+    });
+  }
+
+  /**
+   * Log artifact promotion event
+   * @param {string} scopeId - Scope ID
+   * @param {string} artifact - Artifact path
+   * @param {string} sharedPath - Path in shared layer
+   */
+  async logArtifactPromoted(scopeId, artifact, sharedPath) {
+    return this.logEvent(EventLogger.EventTypes.ARTIFACT_PROMOTED, scopeId, {
+      artifact,
+      shared_path: sharedPath
+    });
+  }
+
+  /**
+   * Log sync operation
+   * @param {string} type - 'up' or 'down'
+   * @param {string} scopeId - Scope ID
+   * @param {object} result - Sync result
+   */
+  async logSync(type, scopeId, result) {
+    const eventType = type === 'up' 
+      ? EventLogger.EventTypes.SYNC_UP 
+      : EventLogger.EventTypes.SYNC_DOWN;
+    
+    return this.logEvent(eventType, scopeId, {
+      files_count: result.promoted?.length || result.pulled?.length || 0,
+      conflicts_count: result.conflicts?.length || 0,
+      errors_count: result.errors?.length || 0
+    });
+  }
+
+  /**
+   * Get event statistics
+   * @param {string} scopeId - Optional scope filter
+   * @returns {Promise<object>} Event statistics
+   */
+  async getStats(scopeId = null) {
+    const events = await this.getEvents(scopeId);
+    
+    const stats = {
+      total: events.length,
+      byType: {},
+      byScope: {},
+      last24h: 0,
+      lastEvent: null
+    };
+
+    const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+
+    for (const event of events) {
+      // Count by type
+      stats.byType[event.type] = (stats.byType[event.type] || 0) + 1;
+      
+      // Count by scope
+      stats.byScope[event.scope] = (stats.byScope[event.scope] || 0) + 1;
+      
+      // Count recent
+      if (new Date(event.timestamp) >= oneDayAgo) {
+        stats.last24h++;
+      }
+    }
+
+    if (events.length > 0) {
+      stats.lastEvent = events.at(-1);
+    }
+
+    return stats;
+  }
+}
+
+module.exports = { EventLogger };