create-byan-agent 2.0.1 → 2.1.1

package/src/observability/logger/structured-logger.js

@@ -0,0 +1,254 @@
+/**
+ * Structured Logger for BYAN v2.0
+ * Provides structured logging with JSON format, log levels, and metadata
+ * 
+ * @module observability/logger/structured-logger
+ * @version 2.0.0-HYPER-MVP
+ */
+
+/**
+ * Log levels supported by the logger
+ */
+const LOG_LEVELS = {
+  DEBUG: 'debug',
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+};
+
+/**
+ * Numeric priorities for log levels
+ */
+const LOG_PRIORITIES = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/**
+ * Structured Logger - Provides JSON-formatted logging with metadata
+ * 
+ * @class StructuredLogger
+ * @example
+ * const logger = new StructuredLogger();
+ * logger.info('User logged in', { userId: '123', ip: '192.168.1.1' });
+ */
+class StructuredLogger {
+  constructor(options = {}) {
+    this.level = options.level || LOG_LEVELS.INFO;
+    this.logs = []; // In-memory storage for tests
+    this.enableConsole = options.enableConsole !== false;
+  }
+
+  /**
+   * Set the minimum log level
+   * 
+   * @param {string} level - Log level (debug, info, warn, error)
+   * @returns {void}
+   * 
+   * @example
+   * logger.setLevel('debug'); // Show all logs
+   * logger.setLevel('error'); // Show only errors
+   */
+  setLevel(level) {
+    if (!LOG_PRIORITIES.hasOwnProperty(level)) {
+      throw new Error(
+        `Invalid log level: ${level}. Must be one of: debug, info, warn, error`
+      );
+    }
+    this.level = level;
+  }
+
+  /**
+   * Log debug message
+   * 
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {void}
+   * 
+   * @example
+   * logger.debug('Cache hit', { key: 'user:123', ttl: 3600 });
+   */
+  debug(message, meta = {}) {
+    this._log(LOG_LEVELS.DEBUG, message, meta);
+  }
+
+  /**
+   * Log info message
+   * 
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {void}
+   * 
+   * @example
+   * logger.info('Task started', { taskId: '123', agent: 'dev' });
+   */
+  info(message, meta = {}) {
+    this._log(LOG_LEVELS.INFO, message, meta);
+  }
+
+  /**
+   * Log warning message
+   * 
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {void}
+   * 
+   * @example
+   * logger.warn('Rate limit approaching', { limit: 1000, used: 950 });
+   */
+  warn(message, meta = {}) {
+    this._log(LOG_LEVELS.WARN, message, meta);
+  }
+
+  /**
+   * Log error message
+   * 
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {void}
+   * 
+   * @example
+   * logger.error('Task failed', { taskId: '123', error: 'Timeout' });
+   */
+  error(message, meta = {}) {
+    this._log(LOG_LEVELS.ERROR, message, meta);
+  }
+
+  /**
+   * Internal log method
+   * 
+   * @private
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} meta - Metadata
+   * @returns {void}
+   */
+  _log(level, message, meta) {
+    // Check if this log should be recorded based on level
+    if (LOG_PRIORITIES[level] < LOG_PRIORITIES[this.level]) {
+      return;
+    }
+
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      meta: { ...meta },
+    };
+
+    // Store in memory
+    this.logs.push(logEntry);
+
+    // Output to console if enabled
+    if (this.enableConsole) {
+      this._outputToConsole(logEntry);
+    }
+  }
+
+  /**
+   * Output log entry to console
+   * 
+   * @private
+   * @param {Object} logEntry - Log entry
+   * @returns {void}
+   */
+  _outputToConsole(logEntry) {
+    const output = JSON.stringify(logEntry);
+    
+    switch (logEntry.level) {
+      case LOG_LEVELS.DEBUG:
+        console.debug(output);
+        break;
+      case LOG_LEVELS.INFO:
+        console.info(output);
+        break;
+      case LOG_LEVELS.WARN:
+        console.warn(output);
+        break;
+      case LOG_LEVELS.ERROR:
+        console.error(output);
+        break;
+      default:
+        console.log(output);
+    }
+  }
+
+  /**
+   * Get all logs
+   * 
+   * @returns {Array<Object>} Array of log entries
+   * 
+   * @example
+   * const logs = logger.getLogs();
+   * logs.forEach(log => {
+   *   console.log(`[${log.level}] ${log.message}`);
+   * });
+   */
+  getLogs() {
+    return [...this.logs];
+  }
+
+  /**
+   * Get logs filtered by level
+   * 
+   * @param {string} level - Log level to filter by
+   * @returns {Array<Object>} Filtered log entries
+   * 
+   * @example
+   * const errors = logger.getLogsByLevel('error');
+   */
+  getLogsByLevel(level) {
+    return this.logs.filter((log) => log.level === level);
+  }
+
+  /**
+   * Clear all logs
+   * 
+   * @returns {void}
+   * 
+   * @example
+   * logger.clear(); // Remove all logs from memory
+   */
+  clear() {
+    this.logs = [];
+  }
+
+  /**
+   * Get log count
+   * 
+   * @returns {number} Number of logs
+   */
+  count() {
+    return this.logs.length;
+  }
+
+  /**
+   * Get log count by level
+   * 
+   * @returns {Object} Count of logs per level
+   * 
+   * @example
+   * const stats = logger.getStats();
+   * // { debug: 10, info: 25, warn: 3, error: 1 }
+   */
+  getStats() {
+    const stats = {
+      debug: 0,
+      info: 0,
+      warn: 0,
+      error: 0,
+    };
+
+    this.logs.forEach((log) => {
+      if (stats.hasOwnProperty(log.level)) {
+        stats[log.level]++;
+      }
+    });
+
+    return stats;
+  }
+}
+
+module.exports = { StructuredLogger, LOG_LEVELS };

package/src/observability/metrics/metrics-collector.js

@@ -0,0 +1,325 @@
+/**
+ * Metrics Collector for BYAN v2.0
+ * Collects and manages system metrics (counters, gauges, timings)
+ * 
+ * @module observability/metrics/metrics-collector
+ * @version 2.0.0-HYPER-MVP
+ */
+
+/**
+ * Metrics Collector - Records and tracks system metrics
+ * 
+ * @class MetricsCollector
+ * @example
+ * const metrics = new MetricsCollector();
+ * metrics.increment('api.calls', { endpoint: '/chat' });
+ * metrics.recordDuration('request.duration', 150);
+ */
+class MetricsCollector {
+  constructor() {
+    this.metrics = new Map();
+  }
+
+  /**
+   * Record a metric with a specific value
+   * 
+   * @param {string} name - Metric name
+   * @param {number} value - Metric value
+   * @param {Object} [tags={}] - Optional tags for filtering
+   * @returns {void}
+   * 
+   * @example
+   * metrics.recordMetric('memory.usage', 1024, { unit: 'MB', service: 'api' });
+   */
+  recordMetric(name, value, tags = {}) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof value !== 'number') {
+      throw new Error('Metric value must be a number');
+    }
+
+    if (isNaN(value)) {
+      throw new Error('Metric value cannot be NaN');
+    }
+
+    const key = this._generateKey(name, tags);
+    
+    this.metrics.set(key, {
+      name,
+      value,
+      tags: { ...tags },
+      timestamp: new Date().toISOString(),
+      type: 'gauge',
+    });
+  }
+
+  /**
+   * Increment a counter metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @param {number} [delta=1] - Increment amount
+   * @returns {void}
+   * 
+   * @example
+   * metrics.increment('api.calls', { endpoint: '/chat' });
+   * metrics.increment('cache.hits', {}, 5); // Increment by 5
+   */
+  increment(name, tags = {}, delta = 1) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof delta !== 'number') {
+      throw new Error('Delta must be a number');
+    }
+
+    const key = this._generateKey(name, tags);
+    const existing = this.metrics.get(key);
+
+    if (existing) {
+      this.metrics.set(key, {
+        ...existing,
+        value: existing.value + delta,
+        timestamp: new Date().toISOString(),
+      });
+    } else {
+      this.metrics.set(key, {
+        name,
+        value: delta,
+        tags: { ...tags },
+        timestamp: new Date().toISOString(),
+        type: 'counter',
+      });
+    }
+  }
+
+  /**
+   * Decrement a counter metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @param {number} [delta=1] - Decrement amount
+   * @returns {void}
+   * 
+   * @example
+   * metrics.decrement('active.connections', { server: 'main' });
+   */
+  decrement(name, tags = {}, delta = 1) {
+    this.increment(name, tags, -delta);
+  }
+
+  /**
+   * Record a duration/timing metric
+   * 
+   * @param {string} name - Metric name
+   * @param {number} durationMs - Duration in milliseconds
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {void}
+   * 
+   * @example
+   * metrics.recordDuration('request.duration', 150, { status: '200' });
+   */
+  recordDuration(name, durationMs, tags = {}) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof durationMs !== 'number') {
+      throw new Error('Duration must be a number');
+    }
+
+    if (durationMs < 0) {
+      throw new Error('Duration cannot be negative');
+    }
+
+    const key = this._generateKey(name, tags);
+    
+    this.metrics.set(key, {
+      name,
+      value: durationMs,
+      tags: { ...tags },
+      timestamp: new Date().toISOString(),
+      type: 'timing',
+    });
+  }
+
+  /**
+   * Generate unique key for metric with tags
+   * 
+   * @private
+   * @param {string} name - Metric name
+   * @param {Object} tags - Tags
+   * @returns {string} Unique key
+   */
+  _generateKey(name, tags) {
+    if (Object.keys(tags).length === 0) {
+      return name;
+    }
+
+    const sortedTags = Object.keys(tags)
+      .sort()
+      .map((key) => `${key}:${tags[key]}`)
+      .join(',');
+
+    return `${name}[${sortedTags}]`;
+  }
+
+  /**
+   * Get all metrics
+   * 
+   * @returns {Object} All metrics as key-value pairs
+   * 
+   * @example
+   * const allMetrics = metrics.getMetrics();
+   * Object.entries(allMetrics).forEach(([key, metric]) => {
+   *   console.log(`${key}: ${metric.value}`);
+   * });
+   */
+  getMetrics() {
+    const result = {};
+    
+    for (const [key, value] of this.metrics.entries()) {
+      result[key] = { ...value };
+    }
+
+    return result;
+  }
+
+  /**
+   * Get a specific metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {Object|null} Metric or null if not found
+   * 
+   * @example
+   * const apiCalls = metrics.getMetric('api.calls', { endpoint: '/chat' });
+   * console.log(`API calls: ${apiCalls.value}`);
+   */
+  getMetric(name, tags = {}) {
+    const key = this._generateKey(name, tags);
+    const metric = this.metrics.get(key);
+    
+    return metric ? { ...metric } : null;
+  }
+
+  /**
+   * Get metrics filtered by name prefix
+   * 
+   * @param {string} prefix - Name prefix
+   * @returns {Object} Filtered metrics
+   * 
+   * @example
+   * const apiMetrics = metrics.getMetricsByPrefix('api.');
+   * // Returns all metrics starting with 'api.'
+   */
+  getMetricsByPrefix(prefix) {
+    const result = {};
+
+    for (const [key, value] of this.metrics.entries()) {
+      if (value.name.startsWith(prefix)) {
+        result[key] = { ...value };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get metrics filtered by type
+   * 
+   * @param {string} type - Metric type (gauge, counter, timing)
+   * @returns {Object} Filtered metrics
+   * 
+   * @example
+   * const counters = metrics.getMetricsByType('counter');
+   */
+  getMetricsByType(type) {
+    const result = {};
+
+    for (const [key, value] of this.metrics.entries()) {
+      if (value.type === type) {
+        result[key] = { ...value };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all metrics
+   * 
+   * @returns {void}
+   * 
+   * @example
+   * metrics.clear(); // Remove all metrics
+   */
+  clear() {
+    this.metrics.clear();
+  }
+
+  /**
+   * Get metrics count
+   * 
+   * @returns {number} Number of metrics
+   */
+  count() {
+    return this.metrics.size;
+  }
+
+  /**
+   * Reset a specific metric to zero
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {boolean} True if metric was reset, false if not found
+   * 
+   * @example
+   * metrics.resetMetric('api.calls', { endpoint: '/chat' });
+   */
+  resetMetric(name, tags = {}) {
+    const key = this._generateKey(name, tags);
+    const existing = this.metrics.get(key);
+
+    if (existing) {
+      this.metrics.set(key, {
+        ...existing,
+        value: 0,
+        timestamp: new Date().toISOString(),
+      });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get summary statistics
+   * 
+   * @returns {Object} Summary stats
+   * 
+   * @example
+   * const stats = metrics.getStats();
+   * // { total: 10, byType: { counter: 5, gauge: 3, timing: 2 } }
+   */
+  getStats() {
+    const byType = {};
+    
+    for (const metric of this.metrics.values()) {
+      if (!byType[metric.type]) {
+        byType[metric.type] = 0;
+      }
+      byType[metric.type]++;
+    }
+
+    return {
+      total: this.metrics.size,
+      byType,
+    };
+  }
+}
+
+module.exports = { MetricsCollector };

package/templates/.github/agents/bmad-agent-test-dynamic.md

@@ -1,21 +0,0 @@
----
-name: 'test-dynamic'
-description: 'Test Dynamic Loading - Phase B Validation'
----
-
-<agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from {project-root}/_bmad/core/agents/test-dynamic.md
-2. READ its entire contents
-3. FOLLOW activation steps precisely
-4. WAIT for user input
-</agent-activation>
-
-```xml
-<agent id="test-dynamic" name="TEST-DYNAMIC" title="Dynamic Loading Test" icon="🧪">
-<activation>
-  <step n="1">Load from {project-root}/_bmad/core/agents/test-dynamic.md</step>
-  <step n="2">Test inheritance from base agent</step>
-  <step n="3">Display menu</step>
-</activation>
-</agent>
-```