bmad-method 6.2.3-next.9 → 6.3.0

package/tools/installer/ui.js

@@ -2,22 +2,50 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('fs-extra');
 const { CLIUtils } = require('./cli-utils');
-const { CustomHandler } = require('./custom-handler');
 const { ExternalModuleManager } = require('./modules/external-manager');
+const { getProjectRoot } = require('./project-root');
 const prompts = require('./prompts');
 
-// Separator class for visual grouping in select/multiselect prompts
-// Note: @clack/prompts doesn't support separators natively, they are filtered out
-class Separator {
-  constructor(text = '────────') {
-    this.line = text;
-    this.name = text;
+/**
+ * Read module version from .claude-plugin/marketplace.json
+ * @param {string} moduleCode - Module code (e.g., 'core', 'bmm', 'cis')
+ * @returns {string} Version string or empty string
+ */
+async function getMarketplaceVersion(moduleCode) {
+  let marketplacePath;
+  if (moduleCode === 'core' || moduleCode === 'bmm') {
+    marketplacePath = path.join(getProjectRoot(), '.claude-plugin', 'marketplace.json');
+  } else {
+    const cacheDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules', moduleCode);
+    marketplacePath = path.join(cacheDir, '.claude-plugin', 'marketplace.json');
+  }
+  try {
+    if (await fs.pathExists(marketplacePath)) {
+      const data = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+      return _extractMarketplaceVersion(data);
+    }
+  } catch {
+    // ignore
   }
-  type = 'separator';
+  return '';
 }
 
-// Separator for choice lists (compatible interface)
-const choiceUtils = { Separator };
+/**
+ * Extract the highest version from marketplace.json plugins array.
+ * Handles multiple plugins per file safely.
+ * @param {Object} data - Parsed marketplace.json
+ * @returns {string} Version string or empty string
+ */
+function _extractMarketplaceVersion(data) {
+  const plugins = data?.plugins;
+  if (!Array.isArray(plugins) || plugins.length === 0) return '';
+  // Use the highest version across all plugins in the file
+  let best = '';
+  for (const p of plugins) {
+    if (p.version && (!best || p.version > best)) best = p.version;
+  }
+  return best;
+}
 
 /**
  * UI utilities for the installer
@@ -58,11 +86,6 @@ class UI {
     // Check if there's an existing BMAD installation
     const hasExistingInstall = await fs.pathExists(bmadDir);
 
-    let customContentConfig = { hasCustomContent: false };
-    if (!hasExistingInstall) {
-      customContentConfig._shouldAsk = true;
-    }
-
     // Track action type (only set if there's an existing installation)
     let actionType;
 
@@ -70,17 +93,14 @@ class UI {
     if (hasExistingInstall) {
       // Get version information
       const { existingInstall, bmadDir } = await this.getExistingInstallation(confirmedDirectory);
-      const packageJsonPath = path.join(__dirname, '../../package.json');
-      const currentVersion = require(packageJsonPath).version;
-      const installedVersion = existingInstall.installed ? existingInstall.version || 'unknown' : 'unknown';
 
       // Build menu choices dynamically
       const choices = [];
 
       // Always show Quick Update first (allows refreshing installation even on same version)
-      if (installedVersion !== 'unknown') {
+      if (existingInstall.installed) {
         choices.push({
-          name: `Quick Update (v${installedVersion} → v${currentVersion})`,
+          name: 'Quick Update',
           value: 'quick-update',
         });
       }
@@ -114,48 +134,9 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
-        // Pass --custom-content through so installer can re-cache if cache is missing
-        let customContentForQuickUpdate = { hasCustomContent: false };
-        if (options.customContent) {
-          const paths = options.customContent
-            .split(',')
-            .map((p) => p.trim())
-            .filter(Boolean);
-          if (paths.length > 0) {
-            const customPaths = [];
-            const selectedModuleIds = [];
-            const sources = [];
-            for (const customPath of paths) {
-              const expandedPath = this.expandUserPath(customPath);
-              const validation = this.validateCustomContentPathSync(expandedPath);
-              if (validation) continue;
-              let moduleMeta;
-              try {
-                const moduleYamlPath = path.join(expandedPath, 'module.yaml');
-                moduleMeta = require('yaml').parse(await fs.readFile(moduleYamlPath, 'utf-8'));
-              } catch {
-                continue;
-              }
-              if (!moduleMeta?.code) continue;
-              customPaths.push(expandedPath);
-              selectedModuleIds.push(moduleMeta.code);
-              sources.push({ path: expandedPath, id: moduleMeta.code, name: moduleMeta.name || moduleMeta.code });
-            }
-            if (customPaths.length > 0) {
-              customContentForQuickUpdate = {
-                hasCustomContent: true,
-                selected: true,
-                sources,
-                selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
-                selectedModuleIds,
-              };
-            }
-          }
-        }
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
-          customContent: customContentForQuickUpdate,
           skipPrompts: options.yes || false,
         };
       }
@@ -177,6 +158,9 @@ class UI {
             .map((m) => m.trim())
             .filter(Boolean);
           await prompts.log.info(`Using modules from command-line: ${selectedModules.join(', ')}`);
+        } else if (options.customSource) {
+          // Custom source without --modules: start with empty list (core added below)
+          selectedModules = [];
         } else if (options.yes) {
           selectedModules = await this.getDefaultModules(installedModuleIds);
           await prompts.log.info(
@@ -186,120 +170,14 @@ class UI {
           selectedModules = await this.selectAllModules(installedModuleIds);
         }
 
-        // After module selection, ask about custom modules
-        let customModuleResult = { selectedCustomModules: [], customContentConfig: { hasCustomContent: false } };
-
-        if (options.customContent) {
-          // Use custom content from command-line
-          const paths = options.customContent
-            .split(',')
-            .map((p) => p.trim())
-            .filter(Boolean);
-          await prompts.log.info(`Using custom content from command-line: ${paths.join(', ')}`);
-
-          // Build custom content config similar to promptCustomContentSource
-          const customPaths = [];
-          const selectedModuleIds = [];
-          const sources = [];
-
-          for (const customPath of paths) {
-            const expandedPath = this.expandUserPath(customPath);
-            const validation = this.validateCustomContentPathSync(expandedPath);
-            if (validation) {
-              await prompts.log.warn(`Skipping invalid custom content path: ${customPath} - ${validation}`);
-              continue;
-            }
-
-            // Read module metadata
-            let moduleMeta;
-            try {
-              const moduleYamlPath = path.join(expandedPath, 'module.yaml');
-              const moduleYaml = await fs.readFile(moduleYamlPath, 'utf-8');
-              const yaml = require('yaml');
-              moduleMeta = yaml.parse(moduleYaml);
-            } catch (error) {
-              await prompts.log.warn(`Skipping custom content path: ${customPath} - failed to read module.yaml: ${error.message}`);
-              continue;
-            }
-
-            if (!moduleMeta) {
-              await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml is empty`);
-              continue;
-            }
-
-            if (!moduleMeta.code) {
-              await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml missing 'code' field`);
-              continue;
-            }
-
-            customPaths.push(expandedPath);
-            selectedModuleIds.push(moduleMeta.code);
-            sources.push({
-              path: expandedPath,
-              id: moduleMeta.code,
-              name: moduleMeta.name || moduleMeta.code,
-            });
-          }
-
-          if (customPaths.length > 0) {
-            customModuleResult = {
-              selectedCustomModules: selectedModuleIds,
-              customContentConfig: {
-                hasCustomContent: true,
-                selected: true,
-                sources,
-                selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
-                selectedModuleIds: selectedModuleIds,
-              },
-            };
-          }
-        } else if (options.yes) {
-          // Non-interactive mode: preserve existing custom modules (matches default: false)
-          const cacheDir = path.join(bmadDir, '_config', 'custom');
-          if (await fs.pathExists(cacheDir)) {
-            const entries = await fs.readdir(cacheDir, { withFileTypes: true });
-            for (const entry of entries) {
-              if (entry.isDirectory()) {
-                customModuleResult.selectedCustomModules.push(entry.name);
-              }
-            }
-            await prompts.log.info(
-              `Non-interactive mode (--yes): preserving ${customModuleResult.selectedCustomModules.length} existing custom module(s)`,
-            );
-          } else {
-            await prompts.log.info('Non-interactive mode (--yes): no existing custom modules found');
-          }
-        } else {
-          const changeCustomModules = await prompts.confirm({
-            message: 'Modify custom modules, agents, or workflows?',
-            default: false,
-          });
-
-          if (changeCustomModules) {
-            customModuleResult = await this.handleCustomModulesInModifyFlow(confirmedDirectory, selectedModules);
-          } else {
-            // Preserve existing custom modules if user doesn't want to modify them
-            const { Installer } = require('./core/installer');
-            const installer = new Installer();
-            const { bmadDir } = await installer.findBmadDir(confirmedDirectory);
-
-            const cacheDir = path.join(bmadDir, '_config', 'custom');
-            if (await fs.pathExists(cacheDir)) {
-              const entries = await fs.readdir(cacheDir, { withFileTypes: true });
-              for (const entry of entries) {
-                if (entry.isDirectory()) {
-                  customModuleResult.selectedCustomModules.push(entry.name);
-                }
-              }
-            }
+        // Resolve custom sources from --custom-source flag
+        if (options.customSource) {
+          const customCodes = await this._resolveCustomSourcesCli(options.customSource);
+          for (const code of customCodes) {
+            if (!selectedModules.includes(code)) selectedModules.push(code);
           }
         }
 
-        // Merge any selected custom modules
-        if (customModuleResult.selectedCustomModules.length > 0) {
-          selectedModules.push(...customModuleResult.selectedCustomModules);
-        }
-
         // Ensure core is in the modules list
         if (!selectedModules.includes('core')) {
           selectedModules.unshift('core');
@@ -318,7 +196,6 @@ class UI {
           skipIde: toolSelection.skipIde,
           coreConfig: moduleConfigs.core || {},
           moduleConfigs: moduleConfigs,
-          customContent: customModuleResult.customContentConfig,
           skipPrompts: options.yes || false,
         };
       }
@@ -336,6 +213,9 @@ class UI {
         .map((m) => m.trim())
         .filter(Boolean);
       await prompts.log.info(`Using modules from command-line: ${selectedModules.join(', ')}`);
+    } else if (options.customSource) {
+      // Custom source without --modules: start with empty list (core added below)
+      selectedModules = [];
     } else if (options.yes) {
       // Use default modules when --yes flag is set
       selectedModules = await this.getDefaultModules(installedModuleIds);
@@ -344,84 +224,14 @@ class UI {
       selectedModules = await this.selectAllModules(installedModuleIds);
     }
 
-    // Ask about custom content (local modules/agents/workflows)
-    if (options.customContent) {
-      // Use custom content from command-line
-      const paths = options.customContent
-        .split(',')
-        .map((p) => p.trim())
-        .filter(Boolean);
-      await prompts.log.info(`Using custom content from command-line: ${paths.join(', ')}`);
-
-      // Build custom content config similar to promptCustomContentSource
-      const customPaths = [];
-      const selectedModuleIds = [];
-      const sources = [];
-
-      for (const customPath of paths) {
-        const expandedPath = this.expandUserPath(customPath);
-        const validation = this.validateCustomContentPathSync(expandedPath);
-        if (validation) {
-          await prompts.log.warn(`Skipping invalid custom content path: ${customPath} - ${validation}`);
-          continue;
-        }
-
-        // Read module metadata
-        let moduleMeta;
-        try {
-          const moduleYamlPath = path.join(expandedPath, 'module.yaml');
-          const moduleYaml = await fs.readFile(moduleYamlPath, 'utf-8');
-          const yaml = require('yaml');
-          moduleMeta = yaml.parse(moduleYaml);
-        } catch (error) {
-          await prompts.log.warn(`Skipping custom content path: ${customPath} - failed to read module.yaml: ${error.message}`);
-          continue;
-        }
-
-        if (!moduleMeta) {
-          await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml is empty`);
-          continue;
-        }
-
-        if (!moduleMeta.code) {
-          await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml missing 'code' field`);
-          continue;
-        }
-
-        customPaths.push(expandedPath);
-        selectedModuleIds.push(moduleMeta.code);
-        sources.push({
-          path: expandedPath,
-          id: moduleMeta.code,
-          name: moduleMeta.name || moduleMeta.code,
-        });
-      }
-
-      if (customPaths.length > 0) {
-        customContentConfig = {
-          hasCustomContent: true,
-          selected: true,
-          sources,
-          selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
-          selectedModuleIds: selectedModuleIds,
-        };
-      }
-    } else if (!options.yes) {
-      const wantsCustomContent = await prompts.confirm({
-        message: 'Add custom modules, agents, or workflows from your computer?',
-        default: false,
-      });
-
-      if (wantsCustomContent) {
-        customContentConfig = await this.promptCustomContentSource();
+    // Resolve custom sources from --custom-source flag
+    if (options.customSource) {
+      const customCodes = await this._resolveCustomSourcesCli(options.customSource);
+      for (const code of customCodes) {
+        if (!selectedModules.includes(code)) selectedModules.push(code);
       }
     }
 
-    // Add custom content modules if any were selected
-    if (customContentConfig && customContentConfig.selectedModuleIds) {
-      selectedModules.push(...customContentConfig.selectedModuleIds);
-    }
-
     // Ensure core is in the modules list
     if (!selectedModules.includes('core')) {
       selectedModules.unshift('core');
@@ -437,7 +247,6 @@ class UI {
       skipIde: toolSelection.skipIde,
       coreConfig: moduleConfigs.core || {},
       moduleConfigs: moduleConfigs,
-      customContent: customContentConfig,
       skipPrompts: options.yes || false,
     };
   }
@@ -776,166 +585,80 @@ class UI {
   }
 
   /**
-   * Get module choices for selection
+   * Select all modules across three tiers: official, community, and custom URL.
    * @param {Set} installedModuleIds - Currently installed module IDs
-   * @param {Object} customContentConfig - Custom content configuration
-   * @returns {Array} Module choices for prompt
+   * @returns {Array} Selected module codes (excluding core)
    */
-  async getModuleChoices(installedModuleIds, customContentConfig = null) {
-    const color = await prompts.getColor();
-    const moduleChoices = [];
-    const isNewInstallation = installedModuleIds.size === 0;
-
-    const customContentItems = [];
-
-    // Add custom content items
-    if (customContentConfig && customContentConfig.hasCustomContent && customContentConfig.customPath) {
-      // Existing installation - show from directory
-      const customHandler = new CustomHandler();
-      const customFiles = await customHandler.findCustomContent(customContentConfig.customPath);
-
-      for (const customFile of customFiles) {
-        const customInfo = await customHandler.getCustomInfo(customFile);
-        if (customInfo) {
-          customContentItems.push({
-            name: `${color.cyan('\u2713')} ${customInfo.name} ${color.dim(`(${customInfo.relativePath})`)}`,
-            value: `__CUSTOM_CONTENT__${customFile}`, // Unique value for each custom content
-            checked: true, // Default to selected since user chose to provide custom content
-            path: customInfo.path, // Track path to avoid duplicates
-            hint: customInfo.description || undefined,
-          });
-        }
-      }
-    }
-
-    // Add official modules
-    const { OfficialModules } = require('./modules/official-modules');
-    const officialModules = new OfficialModules();
-    const { modules: availableModules, customModules: customModulesFromCache } = await officialModules.listAvailable();
-
-    // First, add all items to appropriate sections
-    const allCustomModules = [];
-
-    // Add custom content items from directory
-    allCustomModules.push(...customContentItems);
-
-    // Add custom modules from cache
-    for (const mod of customModulesFromCache) {
-      // Skip if this module is already in customContentItems (by path)
-      const isDuplicate = allCustomModules.some((item) => item.path && mod.path && path.resolve(item.path) === path.resolve(mod.path));
-
-      if (!isDuplicate) {
-        allCustomModules.push({
-          name: `${color.cyan('\u2713')} ${mod.name} ${color.dim('(cached)')}`,
-          value: mod.id,
-          checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
-          hint: mod.description || undefined,
-        });
-      }
-    }
-
-    // Add separators and modules in correct order
-    if (allCustomModules.length > 0) {
-      // Add separator for custom content, all custom modules, and official content separator
-      moduleChoices.push(
-        new choiceUtils.Separator('── Custom Content ──'),
-        ...allCustomModules,
-        new choiceUtils.Separator('── Official Content ──'),
-      );
-    }
+  async selectAllModules(installedModuleIds = new Set()) {
+    // Phase 1: Official modules
+    const officialSelected = await this._selectOfficialModules(installedModuleIds);
 
-    // Add official modules (only non-custom ones)
-    for (const mod of availableModules) {
-      if (!mod.isCustom) {
-        moduleChoices.push({
-          name: mod.name,
-          value: mod.id,
-          checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
-          hint: mod.description || undefined,
-        });
+    // Determine which installed modules are NOT official (community or custom).
+    // These must be preserved even if the user declines to browse community/custom.
+    const officialCodes = new Set(officialSelected);
+    const externalManager = new ExternalModuleManager();
+    const registryModules = await externalManager.listAvailable();
+    const officialRegistryCodes = new Set(registryModules.map((m) => m.code));
+    const installedNonOfficial = [...installedModuleIds].filter((id) => !officialRegistryCodes.has(id));
+
+    // Phase 2: Community modules (category drill-down)
+    // Returns { codes, didBrowse } so we know if the user entered the flow
+    const communityResult = await this._browseCommunityModules(installedModuleIds);
+
+    // Phase 3: Custom URL modules
+    const customSelected = await this._addCustomUrlModules(installedModuleIds);
+
+    // Merge all selections
+    const allSelected = new Set([...officialSelected, ...communityResult.codes, ...customSelected]);
+
+    // Auto-include installed non-official modules that the user didn't get
+    // a chance to manage (they declined to browse). If they did browse,
+    // trust their selections - they could have deselected intentionally.
+    if (!communityResult.didBrowse) {
+      for (const code of installedNonOfficial) {
+        allSelected.add(code);
       }
     }
 
-    return moduleChoices;
+    return [...allSelected];
   }
 
   /**
-   * Select all modules (official + community) using grouped multiselect.
-   * Core is shown as locked but filtered from the result since it's always installed separately.
+   * Select official modules using autocompleteMultiselect.
+   * Extracted from the original selectAllModules - unchanged behavior.
    * @param {Set} installedModuleIds - Currently installed module IDs
-   * @returns {Array} Selected module codes (excluding core)
+   * @returns {Array} Selected official module codes
    */
-  async selectAllModules(installedModuleIds = new Set()) {
-    const { OfficialModules } = require('./modules/official-modules');
-    const officialModulesSource = new OfficialModules();
-    const { modules: localModules } = await officialModulesSource.listAvailable();
-
-    // Get external modules
+  async _selectOfficialModules(installedModuleIds = new Set()) {
     const externalManager = new ExternalModuleManager();
-    const externalModules = await externalManager.listAvailable();
+    const registryModules = await externalManager.listAvailable();
 
-    // Build flat options list with group hints for autocompleteMultiselect
     const allOptions = [];
     const initialValues = [];
     const lockedValues = ['core'];
 
-    // Core module is always installed — show it locked at the top
-    allOptions.push({ label: 'BMad Core Module', value: 'core', hint: 'Core configuration and shared resources' });
-    initialValues.push('core');
-
-    // Helper to build module entry with proper sorting and selection
-    const buildModuleEntry = (mod, value, group) => {
-      const isInstalled = installedModuleIds.has(value);
+    const buildModuleEntry = async (mod) => {
+      const isInstalled = installedModuleIds.has(mod.code);
+      const version = await getMarketplaceVersion(mod.code);
+      const label = version ? `${mod.name} (v${version})` : mod.name;
       return {
-        label: mod.name,
-        value,
-        hint: mod.description || group,
-        // Pre-select only if already installed (not on fresh install)
+        label,
+        value: mod.code,
+        hint: mod.description,
         selected: isInstalled,
       };
     };
 
-    // Local modules (BMM, BMB, etc.)
-    const localEntries = [];
-    for (const mod of localModules) {
-      if (!mod.isCustom && mod.id !== 'core') {
-        const entry = buildModuleEntry(mod, mod.id, 'Local');
-        localEntries.push(entry);
-        if (entry.selected) {
-          initialValues.push(mod.id);
-        }
-      }
-    }
-    allOptions.push(...localEntries.map(({ label, value, hint }) => ({ label, value, hint })));
-
-    // Group 2: BMad Official Modules (type: bmad-org)
-    const officialModules = [];
-    for (const mod of externalModules) {
-      if (mod.type === 'bmad-org') {
-        const entry = buildModuleEntry(mod, mod.code, 'Official');
-        officialModules.push(entry);
-        if (entry.selected) {
-          initialValues.push(mod.code);
-        }
+    for (const mod of registryModules) {
+      const entry = await buildModuleEntry(mod);
+      allOptions.push({ label: entry.label, value: entry.value, hint: entry.hint });
+      if (entry.selected) {
+        initialValues.push(mod.code);
       }
     }
-    allOptions.push(...officialModules.map(({ label, value, hint }) => ({ label, value, hint })));
-
-    // Group 3: Community Modules (type: community)
-    const communityModules = [];
-    for (const mod of externalModules) {
-      if (mod.type === 'community') {
-        const entry = buildModuleEntry(mod, mod.code, 'Community');
-        communityModules.push(entry);
-        if (entry.selected) {
-          initialValues.push(mod.code);
-        }
-      }
-    }
-    allOptions.push(...communityModules.map(({ label, value, hint }) => ({ label, value, hint })));
 
     const selected = await prompts.autocompleteMultiselect({
-      message: 'Select modules to install:',
+      message: 'Select official modules to install:',
       options: allOptions,
       initialValues: initialValues.length > 0 ? initialValues : undefined,
       lockedValues,
@@ -945,34 +668,468 @@ class UI {
 
     const result = selected ? [...selected] : [];
 
-    // Display selected modules as bulleted list
     if (result.length > 0) {
       const moduleLines = result.map((moduleId) => {
         const opt = allOptions.find((o) => o.value === moduleId);
         return `  \u2022 ${opt?.label || moduleId}`;
       });
-      await prompts.log.message('Selected modules:\n' + moduleLines.join('\n'));
+      await prompts.log.message('Selected official modules:\n' + moduleLines.join('\n'));
     }
 
     return result;
   }
 
+  /**
+   * Browse and select community modules using category drill-down.
+   * Featured/promoted modules appear at the top.
+   * @param {Set} installedModuleIds - Currently installed module IDs
+   * @returns {Object} { codes: string[], didBrowse: boolean }
+   */
+  async _browseCommunityModules(installedModuleIds = new Set()) {
+    const browseCommunity = await prompts.confirm({
+      message: 'Would you like to browse community modules?',
+      default: false,
+    });
+    if (!browseCommunity) return { codes: [], didBrowse: false };
+
+    const { CommunityModuleManager } = require('./modules/community-manager');
+    const communityMgr = new CommunityModuleManager();
+
+    const s = await prompts.spinner();
+    s.start('Loading community module catalog...');
+
+    let categories, featured, allCommunity;
+    try {
+      [categories, featured, allCommunity] = await Promise.all([
+        communityMgr.getCategoryList(),
+        communityMgr.listFeatured(),
+        communityMgr.listAll(),
+      ]);
+      s.stop(`Community catalog loaded (${allCommunity.length} modules)`);
+    } catch (error) {
+      s.error('Failed to load community catalog');
+      await prompts.log.warn(`  ${error.message}`);
+      return { codes: [], didBrowse: false };
+    }
+
+    if (allCommunity.length === 0) {
+      await prompts.log.info('No community modules are currently available.');
+      return { codes: [], didBrowse: false };
+    }
+
+    const selectedCodes = new Set();
+    let browsing = true;
+
+    while (browsing) {
+      const categoryChoices = [];
+
+      // Featured section at top
+      if (featured.length > 0) {
+        categoryChoices.push({
+          value: '__featured__',
+          label: `\u2605 Featured (${featured.length} module${featured.length === 1 ? '' : 's'})`,
+        });
+      }
+
+      // Categories with module counts
+      for (const cat of categories) {
+        categoryChoices.push({
+          value: cat.slug,
+          label: `${cat.name} (${cat.moduleCount} module${cat.moduleCount === 1 ? '' : 's'})`,
+        });
+      }
+
+      // Special actions at bottom
+      categoryChoices.push(
+        { value: '__all__', label: '\u25CE View all community modules' },
+        { value: '__search__', label: '\u25CE Search by keyword' },
+        { value: '__done__', label: '\u2713 Done browsing' },
+      );
+
+      const selectedCount = selectedCodes.size;
+      const categoryChoice = await prompts.select({
+        message: `Browse community modules${selectedCount > 0 ? ` (${selectedCount} selected)` : ''}:`,
+        choices: categoryChoices,
+      });
+
+      if (categoryChoice === '__done__') {
+        browsing = false;
+        continue;
+      }
+
+      let modulesToShow;
+      switch (categoryChoice) {
+        case '__featured__': {
+          modulesToShow = featured;
+
+          break;
+        }
+        case '__all__': {
+          modulesToShow = allCommunity;
+
+          break;
+        }
+        case '__search__': {
+          const query = await prompts.text({
+            message: 'Search community modules:',
+            placeholder: 'e.g., design, testing, game',
+          });
+          if (!query || query.trim() === '') continue;
+          modulesToShow = await communityMgr.searchByKeyword(query.trim());
+          if (modulesToShow.length === 0) {
+            await prompts.log.warn('No matching modules found.');
+            continue;
+          }
+
+          break;
+        }
+        default: {
+          modulesToShow = await communityMgr.listByCategory(categoryChoice);
+        }
+      }
+
+      // Build options for autocompleteMultiselect
+      const trustBadge = (tier) => {
+        if (tier === 'bmad-certified') return '\u2713';
+        if (tier === 'community-reviewed') return '\u25CB';
+        return '\u26A0';
+      };
+
+      const options = modulesToShow.map((mod) => {
+        const versionStr = mod.version ? ` (v${mod.version})` : '';
+        const badge = trustBadge(mod.trustTier);
+        return {
+          label: `${mod.displayName}${versionStr} [${badge}]`,
+          value: mod.code,
+          hint: mod.description,
+        };
+      });
+
+      // Pre-check modules that are already selected or installed
+      const initialValues = modulesToShow.filter((m) => selectedCodes.has(m.code) || installedModuleIds.has(m.code)).map((m) => m.code);
+
+      const selected = await prompts.autocompleteMultiselect({
+        message: 'Select community modules:',
+        options,
+        initialValues: initialValues.length > 0 ? initialValues : undefined,
+        required: false,
+        maxItems: Math.min(options.length, 10),
+      });
+
+      // Update accumulated selections: sync with what user selected in this view
+      const shownCodes = new Set(modulesToShow.map((m) => m.code));
+      for (const code of shownCodes) {
+        if (selected && selected.includes(code)) {
+          selectedCodes.add(code);
+        } else {
+          selectedCodes.delete(code);
+        }
+      }
+    }
+
+    if (selectedCodes.size > 0) {
+      const moduleLines = [];
+      for (const code of selectedCodes) {
+        const mod = await communityMgr.getModuleByCode(code);
+        moduleLines.push(`  \u2022 ${mod?.displayName || code}`);
+      }
+      await prompts.log.message('Selected community modules:\n' + moduleLines.join('\n'));
+    }
+
+    return { codes: [...selectedCodes], didBrowse: true };
+  }
+
+  /**
+   * Prompt user to install modules from custom sources (Git URLs or local paths).
+   * @param {Set} installedModuleIds - Currently installed module IDs
+   * @returns {Array} Selected custom module code strings
+   */
+  async _addCustomUrlModules(installedModuleIds = new Set()) {
+    const addCustom = await prompts.confirm({
+      message: 'Would you like to install from a custom source (Git URL or local path)?',
+      default: false,
+    });
+    if (!addCustom) return [];
+
+    const { CustomModuleManager } = require('./modules/custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const selectedModules = [];
+
+    let addMore = true;
+    while (addMore) {
+      const sourceInput = await prompts.text({
+        message: 'Git URL or local path:',
+        placeholder: 'https://github.com/owner/repo or /path/to/module',
+        validate: (input) => {
+          if (!input || input.trim() === '') return 'Source is required';
+          const result = customMgr.parseSource(input.trim());
+          return result.isValid ? undefined : result.error;
+        },
+      });
+
+      const s = await prompts.spinner();
+      s.start('Resolving source...');
+
+      let sourceResult;
+      try {
+        sourceResult = await customMgr.resolveSource(sourceInput.trim(), { skipInstall: true, silent: true });
+        s.stop(sourceResult.parsed.type === 'local' ? 'Local source resolved' : 'Repository cloned');
+      } catch (error) {
+        s.error('Failed to resolve source');
+        await prompts.log.error(`  ${error.message}`);
+        addMore = await prompts.confirm({ message: 'Try another source?', default: false });
+        continue;
+      }
+
+      if (sourceResult.parsed.type === 'local') {
+        await prompts.log.info('LOCAL MODULE: Pointing directly at local source (changes take effect on reinstall).');
+      } else {
+        await prompts.log.warn(
+          'UNVERIFIED MODULE: This module has not been reviewed by the BMad team.\n' + '  Only install modules from sources you trust.',
+        );
+      }
+
+      // Resolve plugins based on discovery mode vs direct mode
+      s.start('Analyzing plugin structure...');
+      const allResolved = [];
+      const localPath = sourceResult.parsed.type === 'local' ? sourceResult.rootDir : null;
+
+      if (sourceResult.mode === 'discovery') {
+        // Discovery mode: marketplace.json found, list available plugins
+        let plugins;
+        try {
+          plugins = await customMgr.discoverModules(sourceResult.marketplace, sourceResult.sourceUrl);
+        } catch (discoverError) {
+          s.error('Failed to discover modules');
+          await prompts.log.error(`  ${discoverError.message}`);
+          addMore = await prompts.confirm({ message: 'Try another source?', default: false });
+          continue;
+        }
+
+        const effectiveRepoPath = sourceResult.repoPath || sourceResult.rootDir;
+        for (const plugin of plugins) {
+          try {
+            const resolved = await customMgr.resolvePlugin(effectiveRepoPath, plugin.rawPlugin, sourceResult.sourceUrl, localPath);
+            if (resolved.length > 0) {
+              allResolved.push(...resolved);
+            } else {
+              // No skills array or empty - use plugin metadata as-is (legacy)
+              allResolved.push({
+                code: plugin.code,
+                name: plugin.displayName || plugin.name,
+                version: plugin.version,
+                description: plugin.description,
+                strategy: 0,
+                pluginName: plugin.name,
+                skillPaths: [],
+              });
+            }
+          } catch (resolveError) {
+            await prompts.log.warn(`  Could not resolve ${plugin.name}: ${resolveError.message}`);
+          }
+        }
+      } else {
+        // Direct mode: no marketplace.json, scan directory for skills and resolve
+        const directPlugin = {
+          name: sourceResult.parsed.displayName || path.basename(sourceResult.rootDir),
+          source: '.',
+          skills: [],
+        };
+
+        // Scan for SKILL.md directories to populate skills array
+        try {
+          const entries = await fs.readdir(sourceResult.rootDir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.isDirectory()) {
+              const skillMd = path.join(sourceResult.rootDir, entry.name, 'SKILL.md');
+              if (await fs.pathExists(skillMd)) {
+                directPlugin.skills.push(entry.name);
+              }
+            }
+          }
+        } catch (scanError) {
+          s.error('Failed to scan directory');
+          await prompts.log.error(`  ${scanError.message}`);
+          addMore = await prompts.confirm({ message: 'Try another source?', default: false });
+          continue;
+        }
+
+        if (directPlugin.skills.length > 0) {
+          try {
+            const resolved = await customMgr.resolvePlugin(sourceResult.rootDir, directPlugin, sourceResult.sourceUrl, localPath);
+            allResolved.push(...resolved);
+          } catch (resolveError) {
+            await prompts.log.warn(`  Could not resolve: ${resolveError.message}`);
+          }
+        }
+      }
+      s.stop(`Found ${allResolved.length} installable module${allResolved.length === 1 ? '' : 's'}`);
+
+      if (allResolved.length === 0) {
+        await prompts.log.warn('No installable modules found in this source.');
+        addMore = await prompts.confirm({ message: 'Try another source?', default: false });
+        continue;
+      }
+
+      // Build multiselect choices
+      // Already-installed modules are pre-checked (update). New modules are unchecked (opt-in).
+      // Unchecking an installed module means "skip update" - removal is handled elsewhere.
+      const choices = allResolved.map((mod) => {
+        const versionStr = mod.version ? ` v${mod.version}` : '';
+        const skillCount = mod.skillPaths ? mod.skillPaths.length : 0;
+        const skillStr = skillCount > 0 ? ` (${skillCount} skill${skillCount === 1 ? '' : 's'})` : '';
+        const alreadyInstalled = installedModuleIds.has(mod.code);
+        const hint = alreadyInstalled ? 'update' : undefined;
+
+        return {
+          name: `${mod.name}${versionStr}${skillStr}`,
+          value: mod.code,
+          hint,
+          checked: alreadyInstalled,
+        };
+      });
+
+      // Show descriptions before the multiselect
+      for (const mod of allResolved) {
+        const versionStr = mod.version ? ` v${mod.version}` : '';
+        await prompts.log.info(`  ${mod.name}${versionStr}\n  ${mod.description}`);
+      }
+
+      const selected = await prompts.multiselect({
+        message: 'Select modules to install:',
+        choices,
+        required: false,
+      });
+
+      if (selected && selected.length > 0) {
+        for (const code of selected) {
+          selectedModules.push(code);
+        }
+      }
+
+      addMore = await prompts.confirm({
+        message: 'Add another custom source?',
+        default: false,
+      });
+    }
+
+    if (selectedModules.length > 0) {
+      await prompts.log.message('Selected custom modules:\n' + selectedModules.map((c) => `  \u2022 ${c}`).join('\n'));
+    }
+
+    return selectedModules;
+  }
+
+  /**
+   * Resolve custom sources from --custom-source CLI flag (non-interactive).
+   * Auto-selects all discovered modules from each source.
+   * @param {string} sourcesArg - Comma-separated Git URLs or local paths
+   * @returns {Array} Module codes from all resolved sources
+   */
+  async _resolveCustomSourcesCli(sourcesArg) {
+    const { CustomModuleManager } = require('./modules/custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const allCodes = [];
+
+    const sources = sourcesArg
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    for (const source of sources) {
+      const s = await prompts.spinner();
+      s.start(`Resolving ${source}...`);
+
+      let sourceResult;
+      try {
+        sourceResult = await customMgr.resolveSource(source, { skipInstall: true, silent: true });
+        s.stop(sourceResult.parsed.type === 'local' ? 'Local source resolved' : 'Repository cloned');
+      } catch (error) {
+        s.error(`Failed to resolve ${source}`);
+        await prompts.log.error(`  ${error.message}`);
+        continue;
+      }
+
+      const s2 = await prompts.spinner();
+      s2.start('Analyzing plugin structure...');
+      const allResolved = [];
+      const localPath = sourceResult.parsed.type === 'local' ? sourceResult.rootDir : null;
+
+      if (sourceResult.mode === 'discovery') {
+        try {
+          const plugins = await customMgr.discoverModules(sourceResult.marketplace, sourceResult.sourceUrl);
+          const effectiveRepoPath = sourceResult.repoPath || sourceResult.rootDir;
+          for (const plugin of plugins) {
+            try {
+              const resolved = await customMgr.resolvePlugin(effectiveRepoPath, plugin.rawPlugin, sourceResult.sourceUrl, localPath);
+              if (resolved.length > 0) {
+                allResolved.push(...resolved);
+              }
+            } catch {
+              // Skip unresolvable plugins
+            }
+          }
+        } catch (discoverError) {
+          s2.error('Failed to discover modules');
+          await prompts.log.error(`  ${discoverError.message}`);
+          continue;
+        }
+      } else {
+        // Direct mode: scan for SKILL.md directories
+        const directPlugin = {
+          name: sourceResult.parsed.displayName || path.basename(sourceResult.rootDir),
+          source: '.',
+          skills: [],
+        };
+        try {
+          const entries = await fs.readdir(sourceResult.rootDir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.isDirectory()) {
+              const skillMd = path.join(sourceResult.rootDir, entry.name, 'SKILL.md');
+              if (await fs.pathExists(skillMd)) {
+                directPlugin.skills.push(entry.name);
+              }
+            }
+          }
+        } catch {
+          // Skip unreadable directories
+        }
+
+        if (directPlugin.skills.length > 0) {
+          try {
+            const resolved = await customMgr.resolvePlugin(sourceResult.rootDir, directPlugin, sourceResult.sourceUrl, localPath);
+            allResolved.push(...resolved);
+          } catch {
+            // Skip unresolvable
+          }
+        }
+      }
+      s2.stop(`Found ${allResolved.length} module${allResolved.length === 1 ? '' : 's'}`);
+
+      for (const mod of allResolved) {
+        allCodes.push(mod.code);
+        const versionStr = mod.version ? ` v${mod.version}` : '';
+        await prompts.log.info(`  Custom module: ${mod.name}${versionStr}`);
+      }
+    }
+
+    return allCodes;
+  }
+
   /**
    * Get default modules for non-interactive mode
    * @param {Set} installedModuleIds - Already installed module IDs
    * @returns {Array} Default module codes
    */
   async getDefaultModules(installedModuleIds = new Set()) {
-    const { OfficialModules } = require('./modules/official-modules');
-    const officialModules = new OfficialModules();
-    const { modules: localModules } = await officialModules.listAvailable();
+    const externalManager = new ExternalModuleManager();
+    const registryModules = await externalManager.listAvailable();
 
     const defaultModules = [];
 
-    // Add default-selected local modules (typically BMM)
-    for (const mod of localModules) {
-      if (mod.defaultSelected === true || installedModuleIds.has(mod.id)) {
-        defaultModules.push(mod.id);
+    for (const mod of registryModules) {
+      if (mod.defaultSelected || installedModuleIds.has(mod.code)) {
+        defaultModules.push(mod.code);
       }
     }
 
@@ -1273,282 +1430,6 @@ class UI {
     return existingInstall.ides;
   }
 
-  /**
-   * Validate custom content path synchronously
-   * @param {string} input - User input path
-   * @returns {string|undefined} Error message or undefined if valid
-   */
-  validateCustomContentPathSync(input) {
-    // Allow empty input to cancel
-    if (!input || input.trim() === '') {
-      return; // Allow empty to exit
-    }
-
-    try {
-      // Expand the path
-      const expandedPath = this.expandUserPath(input.trim());
-
-      // Check if path exists
-      if (!fs.pathExistsSync(expandedPath)) {
-        return 'Path does not exist';
-      }
-
-      // Check if it's a directory
-      const stat = fs.statSync(expandedPath);
-      if (!stat.isDirectory()) {
-        return 'Path must be a directory';
-      }
-
-      // Check for module.yaml in the root
-      const moduleYamlPath = path.join(expandedPath, 'module.yaml');
-      if (!fs.pathExistsSync(moduleYamlPath)) {
-        return 'Directory must contain a module.yaml file in the root';
-      }
-
-      // Try to parse the module.yaml to get the module ID
-      try {
-        const yaml = require('yaml');
-        const content = fs.readFileSync(moduleYamlPath, 'utf8');
-        const moduleData = yaml.parse(content);
-        if (!moduleData.code) {
-          return 'module.yaml must contain a "code" field for the module ID';
-        }
-      } catch (error) {
-        return 'Invalid module.yaml file: ' + error.message;
-      }
-
-      return; // Valid
-    } catch (error) {
-      return 'Error validating path: ' + error.message;
-    }
-  }
-
-  /**
-   * Prompt user for custom content source location
-   * @returns {Object} Custom content configuration
-   */
-  async promptCustomContentSource() {
-    const customContentConfig = { hasCustomContent: true, sources: [] };
-
-    // Keep asking for more sources until user is done
-    while (true) {
-      // First ask if user wants to add another module or continue
-      if (customContentConfig.sources.length > 0) {
-        const action = await prompts.select({
-          message: 'Would you like to:',
-          choices: [
-            { name: 'Add another custom module', value: 'add' },
-            { name: 'Continue with installation', value: 'continue' },
-          ],
-          default: 'continue',
-        });
-
-        if (action === 'continue') {
-          break;
-        }
-      }
-
-      let sourcePath;
-      let isValid = false;
-
-      while (!isValid) {
-        // Use sync validation because @clack/prompts doesn't support async validate
-        const inputPath = await prompts.text({
-          message: 'Path to custom module folder (press Enter to skip):',
-          validate: (input) => this.validateCustomContentPathSync(input),
-        });
-
-        // If user pressed Enter without typing anything, exit the loop
-        if (!inputPath || inputPath.trim() === '') {
-          // If we have no modules yet, return false for no custom content
-          if (customContentConfig.sources.length === 0) {
-            return { hasCustomContent: false };
-          }
-          return customContentConfig;
-        }
-
-        sourcePath = this.expandUserPath(inputPath);
-        isValid = true;
-      }
-
-      // Read module.yaml to get module info
-      const yaml = require('yaml');
-      const moduleYamlPath = path.join(sourcePath, 'module.yaml');
-      const moduleContent = await fs.readFile(moduleYamlPath, 'utf8');
-      const moduleData = yaml.parse(moduleContent);
-
-      // Add to sources
-      customContentConfig.sources.push({
-        path: sourcePath,
-        id: moduleData.code,
-        name: moduleData.name || moduleData.code,
-      });
-
-      await prompts.log.success(`Confirmed local custom module: ${moduleData.name || moduleData.code}`);
-    }
-
-    // Ask if user wants to add these to the installation
-    const shouldInstall = await prompts.confirm({
-      message: `Install these ${customContentConfig.sources.length} custom modules?`,
-      default: true,
-    });
-
-    if (shouldInstall) {
-      customContentConfig.selected = true;
-      // Store paths to module.yaml files, not directories
-      customContentConfig.selectedFiles = customContentConfig.sources.map((s) => path.join(s.path, 'module.yaml'));
-      // Also include module IDs for installation
-      customContentConfig.selectedModuleIds = customContentConfig.sources.map((s) => s.id);
-    }
-
-    return customContentConfig;
-  }
-
-  /**
-   * Handle custom modules in the modify flow
-   * @param {string} directory - Installation directory
-   * @param {Array} selectedModules - Currently selected modules
-   * @returns {Object} Result with selected custom modules and custom content config
-   */
-  async handleCustomModulesInModifyFlow(directory, selectedModules) {
-    // Get existing installation to find custom modules
-    const { existingInstall } = await this.getExistingInstallation(directory);
-
-    // Check if there are any custom modules in cache
-    const { Installer } = require('./core/installer');
-    const installer = new Installer();
-    const { bmadDir } = await installer.findBmadDir(directory);
-
-    const cacheDir = path.join(bmadDir, '_config', 'custom');
-    const cachedCustomModules = [];
-
-    if (await fs.pathExists(cacheDir)) {
-      const entries = await fs.readdir(cacheDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          const moduleYamlPath = path.join(cacheDir, entry.name, 'module.yaml');
-          if (await fs.pathExists(moduleYamlPath)) {
-            const yaml = require('yaml');
-            const content = await fs.readFile(moduleYamlPath, 'utf8');
-            const moduleData = yaml.parse(content);
-
-            cachedCustomModules.push({
-              id: entry.name,
-              name: moduleData.name || entry.name,
-              description: moduleData.description || 'Custom module from cache',
-              checked: selectedModules.includes(entry.name),
-              fromCache: true,
-            });
-          }
-        }
-      }
-    }
-
-    const result = {
-      selectedCustomModules: [],
-      customContentConfig: { hasCustomContent: false },
-    };
-
-    // Ask user about custom modules
-    await prompts.log.info('Custom Modules');
-    if (cachedCustomModules.length > 0) {
-      await prompts.log.message('Found custom modules in your installation:');
-    } else {
-      await prompts.log.message('No custom modules currently installed.');
-    }
-
-    // Build choices dynamically based on whether we have existing modules
-    const choices = [];
-    if (cachedCustomModules.length > 0) {
-      choices.push(
-        { name: 'Keep all existing custom modules', value: 'keep' },
-        { name: 'Select which custom modules to keep', value: 'select' },
-        { name: 'Add new custom modules', value: 'add' },
-        { name: 'Remove all custom modules', value: 'remove' },
-      );
-    } else {
-      choices.push({ name: 'Add new custom modules', value: 'add' }, { name: 'Cancel (no custom modules)', value: 'cancel' });
-    }
-
-    const customAction = await prompts.select({
-      message: cachedCustomModules.length > 0 ? 'Manage custom modules?' : 'Add custom modules?',
-      choices: choices,
-      default: cachedCustomModules.length > 0 ? 'keep' : 'add',
-    });
-
-    switch (customAction) {
-      case 'keep': {
-        // Keep all existing custom modules
-        result.selectedCustomModules = cachedCustomModules.map((m) => m.id);
-        await prompts.log.message(`Keeping ${result.selectedCustomModules.length} custom module(s)`);
-        break;
-      }
-
-      case 'select': {
-        // Let user choose which to keep
-        const selectChoices = cachedCustomModules.map((m) => ({
-          name: `${m.name} (${m.id})`,
-          value: m.id,
-          checked: m.checked,
-        }));
-
-        // Add "None / I changed my mind" option at the end
-        const choicesWithSkip = [
-          ...selectChoices,
-          {
-            name: '⚠ None / I changed my mind - keep no custom modules',
-            value: '__NONE__',
-            checked: false,
-          },
-        ];
-
-        const keepModules = await prompts.multiselect({
-          message: 'Select custom modules to keep (use arrow keys, space to toggle):',
-          choices: choicesWithSkip,
-          required: true,
-        });
-
-        // If user selected both "__NONE__" and other modules, honor the "None" choice
-        if (keepModules && keepModules.includes('__NONE__') && keepModules.length > 1) {
-          await prompts.log.warn('"None / I changed my mind" was selected, so no custom modules will be kept.');
-          result.selectedCustomModules = [];
-        } else {
-          // Filter out the special '__NONE__' value
-          result.selectedCustomModules = keepModules ? keepModules.filter((m) => m !== '__NONE__') : [];
-        }
-        break;
-      }
-
-      case 'add': {
-        // By default, keep existing modules when adding new ones
-        // User chose "Add new" not "Replace", so we assume they want to keep existing
-        result.selectedCustomModules = cachedCustomModules.map((m) => m.id);
-
-        // Then prompt for new ones (reuse existing method)
-        const newCustomContent = await this.promptCustomContentSource();
-        if (newCustomContent.hasCustomContent && newCustomContent.selected) {
-          result.selectedCustomModules.push(...newCustomContent.selectedModuleIds);
-          result.customContentConfig = newCustomContent;
-        }
-        break;
-      }
-
-      case 'remove': {
-        // Remove all custom modules
-        await prompts.log.warn('All custom modules will be removed from the installation');
-        break;
-      }
-
-      case 'cancel': {
-        // User cancelled - no custom modules
-        await prompts.log.message('No custom modules will be added');
-        break;
-      }
-    }
-
-    return result;
-  }
-
   /**
    * Display module versions with update availability
    * @param {Array} modules - Array of module info objects with version info
@@ -1558,6 +1439,7 @@ class UI {
     // Group modules by source
     const builtIn = modules.filter((m) => m.source === 'built-in');
     const external = modules.filter((m) => m.source === 'external');
+    const community = modules.filter((m) => m.source === 'community');
     const custom = modules.filter((m) => m.source === 'custom');
     const unknown = modules.filter((m) => m.source === 'unknown');
 
@@ -1578,6 +1460,7 @@ class UI {
 
     formatGroup(builtIn, 'Built-in Modules');
     formatGroup(external, 'External Modules (Official)');
+    formatGroup(community, 'Community Modules');
     formatGroup(custom, 'Custom Modules');
     formatGroup(unknown, 'Other Modules');