bmad-stella 1.0.0

package/tools/installer/lib/memory-profiler.js

@@ -0,0 +1,225 @@
+/**
+ * Memory Profiler - Track memory usage during installation
+ * Helps identify memory leaks and optimize resource usage
+ */
+
+const v8 = require('node:v8');
+
+class MemoryProfiler {
+  constructor() {
+    this.checkpoints = [];
+    this.startTime = Date.now();
+    this.peakMemory = 0;
+  }
+
+  /**
+   * Create a memory checkpoint
+   * @param {string} label - Label for this checkpoint
+   */
+  checkpoint(label) {
+    const memUsage = process.memoryUsage();
+    const heapStats = v8.getHeapStatistics();
+
+    const checkpoint = {
+      label,
+      timestamp: Date.now() - this.startTime,
+      memory: {
+        rss: this.formatBytes(memUsage.rss),
+        heapTotal: this.formatBytes(memUsage.heapTotal),
+        heapUsed: this.formatBytes(memUsage.heapUsed),
+        external: this.formatBytes(memUsage.external),
+        arrayBuffers: this.formatBytes(memUsage.arrayBuffers || 0),
+      },
+      heap: {
+        totalHeapSize: this.formatBytes(heapStats.total_heap_size),
+        usedHeapSize: this.formatBytes(heapStats.used_heap_size),
+        heapSizeLimit: this.formatBytes(heapStats.heap_size_limit),
+        mallocedMemory: this.formatBytes(heapStats.malloced_memory),
+        externalMemory: this.formatBytes(heapStats.external_memory),
+      },
+      raw: {
+        heapUsed: memUsage.heapUsed,
+      },
+    };
+
+    // Track peak memory
+    if (memUsage.heapUsed > this.peakMemory) {
+      this.peakMemory = memUsage.heapUsed;
+    }
+
+    this.checkpoints.push(checkpoint);
+    return checkpoint;
+  }
+
+  /**
+   * Force garbage collection (requires --expose-gc flag)
+   */
+  forceGC() {
+    if (globalThis.gc) {
+      globalThis.gc();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get memory usage summary
+   */
+  getSummary() {
+    const currentMemory = process.memoryUsage();
+
+    return {
+      currentUsage: {
+        rss: this.formatBytes(currentMemory.rss),
+        heapTotal: this.formatBytes(currentMemory.heapTotal),
+        heapUsed: this.formatBytes(currentMemory.heapUsed),
+      },
+      peakMemory: this.formatBytes(this.peakMemory),
+      totalCheckpoints: this.checkpoints.length,
+      runTime: `${((Date.now() - this.startTime) / 1000).toFixed(2)}s`,
+    };
+  }
+
+  /**
+   * Get detailed report of memory usage
+   */
+  getDetailedReport() {
+    const summary = this.getSummary();
+    const memoryGrowth = this.calculateMemoryGrowth();
+
+    return {
+      summary,
+      memoryGrowth,
+      checkpoints: this.checkpoints,
+      recommendations: this.getRecommendations(memoryGrowth),
+    };
+  }
+
+  /**
+   * Calculate memory growth between checkpoints
+   */
+  calculateMemoryGrowth() {
+    if (this.checkpoints.length < 2) return [];
+
+    const growth = [];
+    for (let index = 1; index < this.checkpoints.length; index++) {
+      const previous = this.checkpoints[index - 1];
+      const current = this.checkpoints[index];
+
+      const heapDiff = current.raw.heapUsed - previous.raw.heapUsed;
+
+      growth.push({
+        from: previous.label,
+        to: current.label,
+        heapGrowth: this.formatBytes(Math.abs(heapDiff)),
+        isIncrease: heapDiff > 0,
+        timeDiff: `${((current.timestamp - previous.timestamp) / 1000).toFixed(2)}s`,
+      });
+    }
+
+    return growth;
+  }
+
+  /**
+   * Get recommendations based on memory usage
+   */
+  getRecommendations(memoryGrowth) {
+    const recommendations = [];
+
+    // Check for large memory growth
+    const largeGrowths = memoryGrowth.filter((g) => {
+      const bytes = this.parseBytes(g.heapGrowth);
+      return bytes > 50 * 1024 * 1024; // 50MB
+    });
+
+    if (largeGrowths.length > 0) {
+      recommendations.push({
+        type: 'warning',
+        message: `Large memory growth detected in ${largeGrowths.length} operations`,
+        details: largeGrowths.map((g) => `${g.from} → ${g.to}: ${g.heapGrowth}`),
+      });
+    }
+
+    // Check peak memory
+    if (this.peakMemory > 500 * 1024 * 1024) {
+      // 500MB
+      recommendations.push({
+        type: 'warning',
+        message: `High peak memory usage: ${this.formatBytes(this.peakMemory)}`,
+        suggestion: 'Consider processing files in smaller batches',
+      });
+    }
+
+    // Check for potential memory leaks
+    const continuousGrowth = this.checkContinuousGrowth();
+    if (continuousGrowth) {
+      recommendations.push({
+        type: 'error',
+        message: 'Potential memory leak detected',
+        details: 'Memory usage continuously increases without significant decreases',
+      });
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Check for continuous memory growth (potential leak)
+   */
+  checkContinuousGrowth() {
+    if (this.checkpoints.length < 5) return false;
+
+    let increasingCount = 0;
+    for (let index = 1; index < this.checkpoints.length; index++) {
+      if (this.checkpoints[index].raw.heapUsed > this.checkpoints[index - 1].raw.heapUsed) {
+        increasingCount++;
+      }
+    }
+
+    // If memory increases in more than 80% of checkpoints, might be a leak
+    return increasingCount / (this.checkpoints.length - 1) > 0.8;
+  }
+
+  /**
+   * Format bytes to human-readable string
+   */
+  formatBytes(bytes) {
+    if (bytes === 0) return '0 B';
+
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const index = Math.floor(Math.log(bytes) / Math.log(k));
+
+    return Number.parseFloat((bytes / Math.pow(k, index)).toFixed(2)) + ' ' + sizes[index];
+  }
+
+  /**
+   * Parse human-readable bytes back to number
+   */
+  parseBytes(string_) {
+    const match = string_.match(/^([\d.]+)\s*([KMGT]?B?)$/i);
+    if (!match) return 0;
+
+    const value = Number.parseFloat(match[1]);
+    const unit = match[2].toUpperCase();
+
+    const multipliers = {
+      B: 1,
+      KB: 1024,
+      MB: 1024 * 1024,
+      GB: 1024 * 1024 * 1024,
+    };
+
+    return value * (multipliers[unit] || 1);
+  }
+
+  /**
+   * Clear checkpoints to free memory
+   */
+  clear() {
+    this.checkpoints = [];
+  }
+}
+
+// Export singleton instance
+module.exports = new MemoryProfiler();

package/tools/installer/lib/module-manager.js

@@ -0,0 +1,114 @@
+/**
+ * Module Manager - Centralized dynamic import management
+ * Handles loading and caching of ES modules to reduce memory overhead
+ */
+
+class ModuleManager {
+  constructor() {
+    this._cache = new Map();
+    this._loadingPromises = new Map();
+  }
+
+  /**
+   * Initialize all commonly used ES modules at once
+   * @returns {Promise<Object>} Object containing all loaded modules
+   */
+  async initializeCommonModules() {
+    const modules = await Promise.all([
+      this.getModule('chalk'),
+      this.getModule('ora'),
+      this.getModule('inquirer'),
+    ]);
+
+    return {
+      chalk: modules[0],
+      ora: modules[1],
+      inquirer: modules[2],
+    };
+  }
+
+  /**
+   * Get a module by name, with caching
+   * @param {string} moduleName - Name of the module to load
+   * @returns {Promise<any>} The loaded module
+   */
+  async getModule(moduleName) {
+    // Return from cache if available
+    if (this._cache.has(moduleName)) {
+      return this._cache.get(moduleName);
+    }
+
+    // If already loading, return the existing promise
+    if (this._loadingPromises.has(moduleName)) {
+      return this._loadingPromises.get(moduleName);
+    }
+
+    // Start loading the module
+    const loadPromise = this._loadModule(moduleName);
+    this._loadingPromises.set(moduleName, loadPromise);
+
+    try {
+      const module = await loadPromise;
+      this._cache.set(moduleName, module);
+      this._loadingPromises.delete(moduleName);
+      return module;
+    } catch (error) {
+      this._loadingPromises.delete(moduleName);
+      throw error;
+    }
+  }
+
+  /**
+   * Internal method to load a specific module
+   * @private
+   */
+  async _loadModule(moduleName) {
+    switch (moduleName) {
+      case 'chalk': {
+        return (await import('chalk')).default;
+      }
+      case 'ora': {
+        return (await import('ora')).default;
+      }
+      case 'inquirer': {
+        return (await import('inquirer')).default;
+      }
+      case 'glob': {
+        return (await import('glob')).glob;
+      }
+      case 'globSync': {
+        return (await import('glob')).globSync;
+      }
+      default: {
+        throw new Error(`Unknown module: ${moduleName}`);
+      }
+    }
+  }
+
+  /**
+   * Clear the module cache to free memory
+   */
+  clearCache() {
+    this._cache.clear();
+    this._loadingPromises.clear();
+  }
+
+  /**
+   * Get multiple modules at once
+   * @param {string[]} moduleNames - Array of module names
+   * @returns {Promise<Object>} Object with module names as keys
+   */
+  async getModules(moduleNames) {
+    const modules = await Promise.all(moduleNames.map((name) => this.getModule(name)));
+
+    return moduleNames.reduce((accumulator, name, index) => {
+      accumulator[name] = modules[index];
+      return accumulator;
+    }, {});
+  }
+}
+
+// Singleton instance
+const moduleManager = new ModuleManager();
+
+module.exports = moduleManager;

package/tools/installer/lib/resource-locator.js

@@ -0,0 +1,308 @@
+/**
+ * Resource Locator - Centralized file path resolution and caching
+ * Reduces duplicate file system operations and memory usage
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const moduleManager = require('./module-manager');
+
+class ResourceLocator {
+  constructor() {
+    this._pathCache = new Map();
+    this._globCache = new Map();
+    this._bmadCorePath = null;
+    this._expansionPacksPath = null;
+  }
+
+  /**
+   * Get the base path for bmad-core
+   */
+  getBmadCorePath() {
+    if (!this._bmadCorePath) {
+      this._bmadCorePath = path.join(__dirname, '../../../bmad-core');
+    }
+    return this._bmadCorePath;
+  }
+
+  /**
+   * Get the base path for expansion packs
+   */
+  getExpansionPacksPath() {
+    if (!this._expansionPacksPath) {
+      this._expansionPacksPath = path.join(__dirname, '../../../expansion-packs');
+    }
+    return this._expansionPacksPath;
+  }
+
+  /**
+   * Find all files matching a pattern, with caching
+   * @param {string} pattern - Glob pattern
+   * @param {Object} options - Glob options
+   * @returns {Promise<string[]>} Array of matched file paths
+   */
+  async findFiles(pattern, options = {}) {
+    const cacheKey = `${pattern}:${JSON.stringify(options)}`;
+
+    if (this._globCache.has(cacheKey)) {
+      return this._globCache.get(cacheKey);
+    }
+
+    const { glob } = await moduleManager.getModules(['glob']);
+    const files = await glob(pattern, options);
+
+    // Cache for 5 minutes
+    this._globCache.set(cacheKey, files);
+    setTimeout(() => this._globCache.delete(cacheKey), 5 * 60 * 1000);
+
+    return files;
+  }
+
+  /**
+   * Get agent path with caching
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<string|null>} Path to agent file or null if not found
+   */
+  async getAgentPath(agentId) {
+    const cacheKey = `agent:${agentId}`;
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    // Check in bmad-core
+    let agentPath = path.join(this.getBmadCorePath(), 'agents', `${agentId}.md`);
+    if (await fs.pathExists(agentPath)) {
+      this._pathCache.set(cacheKey, agentPath);
+      return agentPath;
+    }
+
+    // Check in expansion packs
+    const expansionPacks = await this.getExpansionPacks();
+    for (const pack of expansionPacks) {
+      agentPath = path.join(pack.path, 'agents', `${agentId}.md`);
+      if (await fs.pathExists(agentPath)) {
+        this._pathCache.set(cacheKey, agentPath);
+        return agentPath;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get available agents with metadata
+   * @returns {Promise<Array>} Array of agent objects
+   */
+  async getAvailableAgents() {
+    const cacheKey = 'all-agents';
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    const agents = [];
+    const yaml = require('js-yaml');
+    const { extractYamlFromAgent } = require('../../lib/yaml-utils');
+
+    // Get agents from bmad-core
+    const coreAgents = await this.findFiles('agents/*.md', {
+      cwd: this.getBmadCorePath(),
+    });
+
+    for (const agentFile of coreAgents) {
+      const content = await fs.readFile(path.join(this.getBmadCorePath(), agentFile), 'utf8');
+      const yamlContent = extractYamlFromAgent(content);
+      if (yamlContent) {
+        try {
+          const metadata = yaml.load(yamlContent);
+          agents.push({
+            id: path.basename(agentFile, '.md'),
+            name: metadata.agent_name || path.basename(agentFile, '.md'),
+            description: metadata.description || 'No description available',
+            source: 'core',
+          });
+        } catch {
+          // Skip invalid agents
+        }
+      }
+    }
+
+    // Cache for 10 minutes
+    this._pathCache.set(cacheKey, agents);
+    setTimeout(() => this._pathCache.delete(cacheKey), 10 * 60 * 1000);
+
+    return agents;
+  }
+
+  /**
+   * Get available expansion packs
+   * @returns {Promise<Array>} Array of expansion pack objects
+   */
+  async getExpansionPacks() {
+    const cacheKey = 'expansion-packs';
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    const packs = [];
+    const expansionPacksPath = this.getExpansionPacksPath();
+
+    if (await fs.pathExists(expansionPacksPath)) {
+      const entries = await fs.readdir(expansionPacksPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const configPath = path.join(expansionPacksPath, entry.name, 'config.yaml');
+          if (await fs.pathExists(configPath)) {
+            try {
+              const yaml = require('js-yaml');
+              const config = yaml.load(await fs.readFile(configPath, 'utf8'));
+              packs.push({
+                id: entry.name,
+                name: config.name || entry.name,
+                version: config.version || '1.0.0',
+                description: config.description || 'No description available',
+                shortTitle:
+                  config['short-title'] || config.description || 'No description available',
+                author: config.author || 'Unknown',
+                path: path.join(expansionPacksPath, entry.name),
+              });
+            } catch {
+              // Skip invalid packs
+            }
+          }
+        }
+      }
+    }
+
+    // Cache for 10 minutes
+    this._pathCache.set(cacheKey, packs);
+    setTimeout(() => this._pathCache.delete(cacheKey), 10 * 60 * 1000);
+
+    return packs;
+  }
+
+  /**
+   * Get team configuration
+   * @param {string} teamId - Team identifier
+   * @returns {Promise<Object|null>} Team configuration or null
+   */
+  async getTeamConfig(teamId) {
+    const cacheKey = `team:${teamId}`;
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    const teamPath = path.join(this.getBmadCorePath(), 'agent-teams', `${teamId}.yaml`);
+
+    if (await fs.pathExists(teamPath)) {
+      try {
+        const yaml = require('js-yaml');
+        const content = await fs.readFile(teamPath, 'utf8');
+        const config = yaml.load(content);
+        this._pathCache.set(cacheKey, config);
+        return config;
+      } catch {
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get resource dependencies for an agent
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<Object>} Dependencies object
+   */
+  async getAgentDependencies(agentId) {
+    const cacheKey = `deps:${agentId}`;
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    const agentPath = await this.getAgentPath(agentId);
+    if (!agentPath) {
+      return { all: [], byType: {} };
+    }
+
+    const content = await fs.readFile(agentPath, 'utf8');
+    const { extractYamlFromAgent } = require('../../lib/yaml-utils');
+    const yamlContent = extractYamlFromAgent(content);
+
+    if (!yamlContent) {
+      return { all: [], byType: {} };
+    }
+
+    try {
+      const yaml = require('js-yaml');
+      const metadata = yaml.load(yamlContent);
+      const dependencies = metadata.dependencies || {};
+
+      // Flatten dependencies
+      const allDeps = [];
+      const byType = {};
+
+      for (const [type, deps] of Object.entries(dependencies)) {
+        if (Array.isArray(deps)) {
+          byType[type] = deps;
+          for (const dep of deps) {
+            allDeps.push(`.bmad-core/${type}/${dep}`);
+          }
+        }
+      }
+
+      const result = { all: allDeps, byType };
+      this._pathCache.set(cacheKey, result);
+      return result;
+    } catch {
+      return { all: [], byType: {} };
+    }
+  }
+
+  /**
+   * Clear all caches to free memory
+   */
+  clearCache() {
+    this._pathCache.clear();
+    this._globCache.clear();
+  }
+
+  /**
+   * Get IDE configuration
+   * @param {string} ideId - IDE identifier
+   * @returns {Promise<Object|null>} IDE configuration or null
+   */
+  async getIdeConfig(ideId) {
+    const cacheKey = `ide:${ideId}`;
+
+    if (this._pathCache.has(cacheKey)) {
+      return this._pathCache.get(cacheKey);
+    }
+
+    const idePath = path.join(this.getBmadCorePath(), 'ide-rules', `${ideId}.yaml`);
+
+    if (await fs.pathExists(idePath)) {
+      try {
+        const yaml = require('js-yaml');
+        const content = await fs.readFile(idePath, 'utf8');
+        const config = yaml.load(content);
+        this._pathCache.set(cacheKey, config);
+        return config;
+      } catch {
+        return null;
+      }
+    }
+
+    return null;
+  }
+}
+
+// Singleton instance
+const resourceLocator = new ResourceLocator();
+
+module.exports = resourceLocator;

package/tools/installer/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "bmad-stella",
+  "version": "1.0.0",
+  "description": "BMad Stella installer - AI-powered Agile development framework",
+  "keywords": [
+    "bmad",
+    "agile",
+    "ai",
+    "development",
+    "framework",
+    "installer",
+    "agents"
+  ],
+  "homepage": "git+https://github.com/Asrarul-BS23/BMad-Stella#readme",
+  "bugs": {
+    "url": "https://github.com/Asrarul-BS23/BMad-Stella/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Asrarul-BS23/BMad-Stella.git"
+  },
+  "license": "MIT",
+  "author": "Stella Team",
+  "contributors": [
+    "BMad Team"
+  ],
+  "main": "lib/installer.js",
+  "bin": {
+    "bmad-stella": "./bin/bmad.js",
+    "stella": "./bin/bmad.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^14.0.0",
+    "fs-extra": "^11.3.0",
+    "inquirer": "^8.2.6",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1",
+    "semver": "^7.6.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}