wizz-method 2.0.0 → 2.1.1

package/tools/installer/modules/module-catalog.js

@@ -0,0 +1,565 @@
+/**
+ * Catálogo de módulos (leitura pura) — item 20, etapa 2 (auditoria 2026-09-11).
+ *
+ * Parte do split de official-modules.js: tudo que LÊ módulos (listar,
+ * descrever, localizar fonte, localizar _wizz/, ler config existente) sem
+ * prompt, sem spinner, sem instalar. Métodos que costumavam viver na classe
+ * OfficialModules continuam acessíveis por lá via delegação, para os callers
+ * e testes existentes não mudarem.
+ *
+ * Nada aqui deve importar `prompts` (regra do relatório: o único módulo que
+ * importa prompts é o config-collector).
+ */
+
+const path = require('node:path');
+const fs = require('../fs-native');
+const yaml = require('yaml');
+const { getProjectRoot, getSourcePath, getModulePath } = require('../project-root');
+const { ExternalModuleManager } = require('./external-manager');
+const { loadYamlCached } = require('../core/yaml-cache');
+const { detectWizzDir } = require('../core/wizz-dir');
+
+/**
+ * Parse a config.toml or config.user.toml written by writeCentralConfig.
+ * Only handles the subset of TOML the installer produces: [core],
+ * [modules.<code>], string/bool/number scalar values. [agents.*] and other
+ * sections are ignored. Returns a plain object keyed by section name where
+ * module sections use the bare code (e.g. "bmm"), not the full "modules.bmm".
+ */
+function parseCentralToml(content) {
+  const result = {};
+  let currentSection = null;
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]\s*$/);
+    if (sectionMatch) {
+      const name = sectionMatch[1];
+      if (name === 'core') {
+        currentSection = 'core';
+      } else if (name.startsWith('modules.')) {
+        currentSection = name.slice('modules.'.length);
+      } else {
+        currentSection = null;
+      }
+      if (currentSection && !result[currentSection]) {
+        result[currentSection] = {};
+      }
+      continue;
+    }
+
+    if (!currentSection) continue;
+
+    const kvMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(.+)$/);
+    if (!kvMatch) continue;
+
+    const key = kvMatch[1];
+    const raw = kvMatch[2].trim();
+    let value;
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+      value = raw.slice(1, -1).replaceAll(/\\(["\\nrbt])/g, (_, c) => ({ '"': '"', '\\': '\\', n: '\n', r: '\r', b: '\b', t: '\t' })[c]);
+    } else if (raw === 'true') {
+      value = true;
+    } else if (raw === 'false') {
+      value = false;
+    } else if (raw !== '' && !isNaN(raw)) {
+      value = Number(raw);
+    } else {
+      value = raw;
+    }
+    result[currentSection][key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Localiza o module.yaml de um módulo: caminho padrão (src/modules/<code> ou
+ * core/bmm) primeiro, depois findModuleSource (que cobre externo/custom).
+ * Extrai a resolução copiada 3x em official-modules.js (OM-02, auditoria
+ * 2026-09-11) — scanModuleSchemas, collectModuleConfigQuick e
+ * collectModuleConfig tinham blocos idênticos.
+ *
+ * @param {(moduleCode: string, options?: Object) => Promise<string|null>} findModuleSourceFn
+ *   A função de busca do dono da chamada (normalmente OfficialModules#findModuleSource).
+ * @param {string} moduleName
+ * @param {Object} [options] - Opções repassadas a findModuleSourceFn
+ * @returns {Promise<string|null>} Caminho absoluto para o module.yaml, ou null
+ */
+async function resolveModuleConfigPath(findModuleSourceFn, moduleName, options = {}) {
+  const standardPath = path.join(getModulePath(moduleName), 'module.yaml');
+  if (await fs.pathExists(standardPath)) {
+    return standardPath;
+  }
+  const moduleSourcePath = await findModuleSourceFn(moduleName, { silent: true, ...options });
+  if (moduleSourcePath) {
+    return path.join(moduleSourcePath, 'module.yaml');
+  }
+  return null;
+}
+
+// Campos de metadata de module.yaml que não são perguntas de config.
+// interface_version (auditoria 2026-09-11, item 25 — ver module-interface.js)
+// é um escalar de contrato, não uma pergunta: sem essa entrada ele seria
+// contado como "config real" pelo hasNoConfig do config-collector, do
+// mesmo jeito que default_selected precisou entrar aqui antes dele.
+// description e module_version entraram no review da Fase 4 (2026-09-12)
+// pelo mesmo motivo: metadados escalares, não perguntas.
+const MODULE_METADATA_FIELDS = new Set([
+  'code',
+  'name',
+  'header',
+  'subheader',
+  'description',
+  'module_version',
+  'default_selected',
+  'interface_version',
+]);
+
+/**
+ * True when a config field has no default value at all. An explicit empty
+ * string (`default: ""`) is a real default meaning "defaults to blank" — it
+ * must NOT force a required prompt. Centralized so the express/customize/
+ * skip-prompts paths stay consistent.
+ * @param {*} defaultValue - The field's `default` value from module.yaml.
+ * @returns {boolean} True when the field has no usable default.
+ */
+function isMissingDefault(defaultValue) {
+  return defaultValue === undefined || defaultValue === null;
+}
+
+/**
+ * Camada de leitura pura do OfficialModules: listar, descrever e localizar
+ * módulos. 0 prompts. Os métodos de coleta interativa ficam no restante de
+ * official-modules.js (config-collector), que delega aqui.
+ */
+class ModuleCatalog {
+  /**
+   * @param {Object} [options]
+   * @param {ExternalModuleManager} [options.externalModuleManager]
+   * @param {Object|null} [options.channelOptions]
+   * @param {(moduleCode: string, options?: Object) => Promise<string|null>} [options.findModuleSource]
+   *   Ponto único de resolução de fonte usado INTERNAMENTE pelo catálogo.
+   *   OfficialModules injeta aqui o próprio wrapper, de modo que stubar
+   *   `officialModules.findModuleSource` (padrão dos testes) também
+   *   intercepta listAvailable/getModuleInfo/scanModuleSchemas — antes o
+   *   catálogo chamava só o seu próprio método e o stub não pegava.
+   */
+  constructor(options = {}) {
+    this.externalModuleManager = options.externalModuleManager || new ExternalModuleManager();
+    this.channelOptions = options.channelOptions || null;
+    this.resolveModuleSource = options.findModuleSource || ((code, opts) => this.findModuleSource(code, opts));
+    /**
+     * Erros de leitura acumulados (module.yaml ilegível). O catálogo não
+     * importa `prompts` — quem avisa o usuário é OfficialModules, que drena
+     * esta lista depois de cada chamada (item 20: o split tinha trocado os
+     * `prompts.log.warn` originais por `catch {}` mudos).
+     * @type {Array<{module: string, error: Error}>}
+     */
+    this.loadErrors = [];
+  }
+
+  /**
+   * Drena os erros de leitura acumulados desde a última chamada.
+   * @returns {Array<{module: string, error: Error}>}
+   */
+  takeLoadErrors() {
+    const errors = this.loadErrors;
+    this.loadErrors = [];
+    return errors;
+  }
+
+  /**
+   * List all available built-in modules (core and bmm) plus bundled src/modules.
+   * All other modules come from wizz-modules.yaml
+   * @returns {Object} Object with modules array
+   */
+  async listAvailable() {
+    const modules = [];
+
+    // Add built-in core module (directly under src/core-skills)
+    const corePath = getSourcePath('core-skills');
+    if (await fs.pathExists(corePath)) {
+      const coreInfo = await this.getModuleInfo(corePath, 'core', 'src/core-skills');
+      if (coreInfo) {
+        modules.push(coreInfo);
+      }
+    }
+
+    // Add built-in bmm module (directly under src/bmm-skills)
+    const bmmPath = getSourcePath('bmm-skills');
+    if (await fs.pathExists(bmmPath)) {
+      const bmmInfo = await this.getModuleInfo(bmmPath, 'bmm', 'src/bmm-skills');
+      if (bmmInfo) {
+        modules.push(bmmInfo);
+      }
+    }
+
+    // Add bundled local modules (src/modules/<code>), e.g. wizz. Without this
+    // they never appear in the picker nor in the --yes defaults, even with
+    // default_selected: true — findModuleSource resolves them, but nothing
+    // ever selects them (bug: maestro/agentes de área não instalavam via npx).
+    const bundledDir = getSourcePath('modules');
+    if (await fs.pathExists(bundledDir)) {
+      const entries = await fs.readdir(bundledDir, { withFileTypes: true });
+      const seen = new Set(modules.map((m) => m.id));
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const modulePath = path.join(bundledDir, entry.name);
+        if (!(await fs.pathExists(path.join(modulePath, 'module.yaml')))) continue;
+        const info = await this.getModuleInfo(modulePath, entry.name, `src/modules/${entry.name}`);
+        if (info && !seen.has(info.id)) {
+          modules.push(info);
+          seen.add(info.id);
+        }
+      }
+    }
+
+    return { modules };
+  }
+
+  /**
+   * Get module information from a module path
+   * @param {string} modulePath - Path to the module directory
+   * @param {string} defaultName - Default name for the module
+   * @param {string} sourceDescription - Description of where the module was found
+   * @returns {Object|null} Module info or null if not a valid module
+   */
+  async getModuleInfo(modulePath, defaultName, sourceDescription) {
+    const moduleConfigPath = path.join(modulePath, 'module.yaml');
+
+    if (!(await fs.pathExists(moduleConfigPath))) {
+      // Check resolution cache for strategy 5 modules (no module.yaml on disk)
+      const { CustomModuleManager } = require('./custom-module-manager');
+      const customMgr = new CustomModuleManager();
+      const resolved = customMgr.getResolution(defaultName);
+      if (resolved && resolved.synthesizedModuleYaml) {
+        return {
+          id: resolved.code,
+          path: modulePath,
+          name: resolved.name,
+          description: resolved.description,
+          version: resolved.version || '1.0.0',
+          source: sourceDescription,
+          dependencies: [],
+          defaultSelected: false,
+        };
+      }
+      return null;
+    }
+
+    const moduleInfo = {
+      id: defaultName,
+      path: modulePath,
+      name: defaultName
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' '),
+      description: 'Wizz Method Module',
+      version: '5.0.0',
+      source: sourceDescription,
+    };
+
+    // Read module config for metadata
+    try {
+      const config = await loadYamlCached(moduleConfigPath);
+      if (config) {
+        // Use the code property as the id if available
+        if (config.code) {
+          moduleInfo.id = config.code;
+        }
+
+        moduleInfo.name = config.name || moduleInfo.name;
+        moduleInfo.description = config.description || moduleInfo.description;
+        moduleInfo.version = config.version || moduleInfo.version;
+        moduleInfo.dependencies = config.dependencies || [];
+        moduleInfo.defaultSelected = config.default_selected === undefined ? false : config.default_selected;
+      }
+    } catch (error) {
+      // Sem prompts aqui (regra do split): um module.yaml quebrado degrada
+      // para os defaults acima em vez de falhar a listagem inteira, mas o
+      // erro é registrado para OfficialModules avisar o usuário.
+      this.loadErrors.push({ module: defaultName, error });
+    }
+
+    return moduleInfo;
+  }
+
+  /**
+   * Find the source path for a module by searching all possible locations
+   * @param {string} moduleCode - Code of the module to find (from module.yaml)
+   * @returns {string|null} Path to the module source or null if not found
+   */
+  async findModuleSource(moduleCode, options = {}) {
+    // Inherit channelOptions from the install-scoped instance when the caller
+    // didn't pass one explicitly. Keeps pre-install config collection and the
+    // actual install step looking at the same git ref.
+    if (options.channelOptions === undefined && this.channelOptions) {
+      options = { ...options, channelOptions: this.channelOptions };
+    }
+
+    // Check for core module (directly under src/core-skills)
+    if (moduleCode === 'core') {
+      const corePath = getSourcePath('core-skills');
+      if (await fs.pathExists(corePath)) {
+        return corePath;
+      }
+    }
+
+    // Check for built-in bmm module (directly under src/bmm-skills)
+    if (moduleCode === 'bmm') {
+      const bmmPath = getSourcePath('bmm-skills');
+      if (await fs.pathExists(bmmPath)) {
+        return bmmPath;
+      }
+    }
+
+    // Check bundled local modules (directly under src/modules/<code>), e.g. wizz.
+    // These ship inside this repo and are auto-discovered by list-options.js.
+    const bundledPath = getSourcePath('modules', moduleCode);
+    if (await fs.pathExists(path.join(bundledPath, 'module.yaml'))) {
+      return bundledPath;
+    }
+
+    // Check external official modules (pass channelOptions so channel plan applies)
+    const externalSource = await this.externalModuleManager.findExternalModuleSource(moduleCode, options);
+    if (externalSource) {
+      return externalSource;
+    }
+
+    // Check custom modules (from user-provided URLs, already cloned to cache)
+    const { CustomModuleManager } = require('./custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const customSource = await customMgr.findModuleSourceByCode(moduleCode, options);
+    if (customSource) {
+      return customSource;
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the wizz installation directory in a project
+   * V6+ installations can use ANY folder name but ALWAYS have _config/manifest.yaml
+   * Delegated to core/wizz-dir.js, the single owner of `_wizz` resolution
+   * (item 20, auditoria 2026-09-11) — semântica inalterada.
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<string>} Path to wizz directory
+   */
+  async findWizzDir(projectDir) {
+    return detectWizzDir(projectDir);
+  }
+
+  /**
+   * Load existing config if it exists from module config files.
+   * Populates `this.existingConfig` (plain object module → key → value).
+   * @param {string} projectDir - Target project directory
+   * @returns {Promise<boolean>} True when any prior config was found
+   */
+  async loadExistingConfig(projectDir) {
+    this.existingConfigData = {};
+
+    // Check if project directory exists first
+    if (!(await fs.pathExists(projectDir))) {
+      return false;
+    }
+
+    // Find the actual wizz directory (handles custom folder names)
+    const wizzDir = await this.findWizzDir(projectDir);
+
+    // Check if wizz directory exists
+    if (!(await fs.pathExists(wizzDir))) {
+      return false;
+    }
+
+    // Primary source: installer-written config.toml + config.user.toml (v6+).
+    // Both files together hold all install answers; config.user.toml carries
+    // user-scoped keys like user_name that would otherwise be re-prompted on
+    // every reinstall.
+    let foundAny = false;
+    for (const fileName of ['config.toml', 'config.user.toml']) {
+      const tomlPath = path.join(wizzDir, fileName);
+      if (!(await fs.pathExists(tomlPath))) continue;
+      try {
+        const content = await fs.readFile(tomlPath, 'utf8');
+        const parsed = parseCentralToml(content);
+        for (const [section, values] of Object.entries(parsed)) {
+          if (values && typeof values === 'object' && !Array.isArray(values)) {
+            if (!this.existingConfigData[section]) this.existingConfigData[section] = {};
+            Object.assign(this.existingConfigData[section], values);
+            foundAny = true;
+          }
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    }
+
+    if (foundAny) {
+      return true;
+    }
+
+    // Fallback: legacy per-module config.yaml files (pre-v6 installations).
+    const entries = await fs.readdir(wizzDir, { withFileTypes: true });
+    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom', 'hooks']);
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (nonModuleDirs.has(entry.name)) {
+          continue;
+        }
+
+        const moduleConfigPath = path.join(wizzDir, entry.name, 'config.yaml');
+
+        if (await fs.pathExists(moduleConfigPath)) {
+          try {
+            const content = await fs.readFile(moduleConfigPath, 'utf8');
+            const moduleConfig = yaml.parse(content);
+            // Only keep plain object parses. A corrupt config.yaml that parses
+            // to a scalar or array would crash later code that does `key in cfg`
+            // / `Object.keys(cfg)`; treat it the same as a parse error.
+            if (moduleConfig && typeof moduleConfig === 'object' && !Array.isArray(moduleConfig)) {
+              this.existingConfigData[entry.name] = moduleConfig;
+              foundAny = true;
+            }
+          } catch {
+            // Ignore parse errors for individual modules
+          }
+        }
+      }
+    }
+
+    if (foundAny) {
+      await this._hoistCoreKeysFromLegacyModuleConfigs();
+    }
+
+    return foundAny;
+  }
+
+  /**
+   * Migrate prior answers when a key has moved from a non-core module to core
+   * (e.g. project_name moving from bmm to core in #2279). Without this, the
+   * partition logic in writeCentralConfig drops the value from the bmm bucket
+   * (because it's now a core key) without re-homing it under [core], so the
+   * user's prior answer silently disappears on the next install/quick-update.
+   */
+  async _hoistCoreKeysFromLegacyModuleConfigs() {
+    const coreSchemaPath = path.join(getSourcePath(), 'core-skills', 'module.yaml');
+    if (!(await fs.pathExists(coreSchemaPath))) return;
+
+    let coreSchema;
+    try {
+      coreSchema = await loadYamlCached(coreSchemaPath);
+    } catch {
+      return;
+    }
+    if (!coreSchema || typeof coreSchema !== 'object') return;
+
+    const coreKeys = new Set(
+      Object.entries(coreSchema)
+        .filter(([, v]) => v && typeof v === 'object' && 'prompt' in v)
+        .map(([k]) => k),
+    );
+    if (coreKeys.size === 0) return;
+
+    // Belt-and-suspenders: loadExistingConfig already filters non-object parses,
+    // but anyone calling _hoistCoreKeysFromLegacyModuleConfigs in isolation (or
+    // future code paths populating existingConfigData directly) shouldn't be
+    // able to crash this with a scalar / array.
+    const existingCore = this.existingConfigData.core;
+    this.existingConfigData.core = existingCore && typeof existingCore === 'object' && !Array.isArray(existingCore) ? existingCore : {};
+
+    for (const [moduleName, cfg] of Object.entries(this.existingConfigData)) {
+      if (moduleName === 'core' || !cfg || typeof cfg !== 'object' || Array.isArray(cfg)) continue;
+      for (const key of Object.keys(cfg)) {
+        if (!coreKeys.has(key)) continue;
+        if (!(key in this.existingConfigData.core)) {
+          this.existingConfigData.core[key] = cfg[key];
+        }
+        delete cfg[key];
+      }
+    }
+  }
+
+  /**
+   * Pre-scan module schemas to gather metadata for the configuration gateway prompt.
+   * Returns info about which modules have configurable options.
+   * @param {Array} modules - List of non-core module names
+   * @returns {Promise<Array>} Array of {moduleName, displayName, questionCount, hasFieldsWithoutDefaults}
+   */
+  async scanModuleSchemas(modules) {
+    const results = [];
+
+    for (const moduleName of modules) {
+      const moduleConfigPath = await resolveModuleConfigPath(this.resolveModuleSource, moduleName);
+      if (!moduleConfigPath) {
+        continue;
+      }
+
+      try {
+        const moduleConfig = await loadYamlCached(moduleConfigPath);
+        if (!moduleConfig) continue;
+
+        const displayName = moduleConfig.header || `${moduleName.toUpperCase()} Module`;
+        const configKeys = Object.keys(moduleConfig).filter((key) => key !== 'prompt');
+        const questionKeys = configKeys.filter((key) => {
+          if (MODULE_METADATA_FIELDS.has(key)) return false;
+          const item = moduleConfig[key];
+          return item && typeof item === 'object' && item.prompt;
+        });
+
+        const hasFieldsWithoutDefaults = questionKeys.some((key) => {
+          const item = moduleConfig[key];
+          return isMissingDefault(item.default);
+        });
+
+        results.push({
+          moduleName,
+          displayName,
+          questionCount: questionKeys.length,
+          hasFieldsWithoutDefaults,
+        });
+      } catch (error) {
+        // Sem prompts aqui: uma schema ilegível simplesmente não aparece no
+        // gateway de customização. O erro sobe por loadErrors para
+        // OfficialModules emitir o warn que existia antes do split.
+        this.loadErrors.push({ module: moduleName, error });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Private: Get list of all files in a directory
+   * @param {string} dir - Directory path
+   * @param {string} baseDir - Base directory for relative paths
+   * @returns {Array} List of relative file paths
+   */
+  async getFileList(dir, baseDir = dir) {
+    const files = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const subFiles = await this.getFileList(fullPath, baseDir);
+        files.push(...subFiles);
+      } else {
+        files.push(path.relative(baseDir, fullPath));
+      }
+    }
+
+    return files;
+  }
+}
+
+module.exports = {
+  ModuleCatalog,
+  parseCentralToml,
+  resolveModuleConfigPath,
+  isMissingDefault,
+  MODULE_METADATA_FIELDS,
+};