wizz-method 1.14.0 → 1.16.0

package/tools/installer/modules/external-manager.js

@@ -94,6 +94,13 @@ class ExternalModuleManager {
   // ExternalModuleManager) sees resolutions made during install.
   static _resolutions = new Map();
 
+  // moduleCode → ResolvedModule (do PluginResolver). Preenchido para módulos do
+  // registry marcados com `marketplace-plugin: true`, cujas skills instaláveis
+  // vivem fora de um único diretório de module.yaml e precisam ser resolvidas a
+  // partir de .claude-plugin/marketplace.json. Compartilhado entre instâncias
+  // para o install() aproveitar a resolução feita no findModuleSource.
+  static _pluginResolutions = new Map();
+
   constructor() {}
 
   /**
@@ -105,6 +112,15 @@ class ExternalModuleManager {
     return ExternalModuleManager._resolutions.get(moduleCode) || null;
   }
 
+  /**
+   * Resolução marketplace-plugin em cache para um módulo (se houver).
+   * @param {string} moduleCode
+   * @returns {Object|null} ResolvedModule do PluginResolver, ou null
+   */
+  getPluginResolution(moduleCode) {
+    return ExternalModuleManager._pluginResolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from the bundled YAML file.
    * @returns {Object} Parsed YAML content with modules array
@@ -147,8 +163,16 @@ class ExternalModuleManager {
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
+      deprecated: mod.deprecated === true,
+      deprecationMessage: mod.deprecation_message || mod['deprecation-message'] || mod.deprecationMessage || null,
+      marketplacePlugin: mod.marketplace_plugin === true || mod['marketplace-plugin'] === true || mod.marketplacePlugin === true,
+      postInstallMessage: mod.post_install_message || mod['post-install-message'] || mod.postInstallMessage || null,
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
+      // Códigos anteriores sob os quais este módulo foi registrado (ex.: `bmad-loop`
+      // era `bauto`). Deixa um módulo renomeado continuar resolvendo instalações
+      // existentes em vez de órfã-las — ver getModuleByCode().
+      aliases: Array.isArray(mod.aliases) ? mod.aliases : [],
     };
   }
 
@@ -173,13 +197,27 @@ class ExternalModuleManager {
   }
 
   /**
-   * Get module info by code
+   * Get module info by code. Cai no `aliases` da entrada do registry, de modo
+   * que um módulo renomeado (com `code` alterado) ainda resolve para instalações
+   * gravadas sob o código anterior.
    * @param {string} code - The module code (e.g., 'cis')
    * @returns {Object|null} Module info or null if not found
    */
   async getModuleByCode(code) {
     const modules = await this.listAvailable();
-    return modules.find((m) => m.code === code) || null;
+    return modules.find((m) => m.code === code) || modules.find((m) => m.aliases.includes(code)) || null;
+  }
+
+  /**
+   * Resolve a possibly-legacy module code to its current canonical code.
+   * Returns the input unchanged if it doesn't match any registry entry or
+   * alias (e.g. a custom/unknown module).
+   * @param {string} code
+   * @returns {Promise<string>}
+   */
+  async resolveCanonicalCode(code) {
+    const info = await this.getModuleByCode(code);
+    return info ? info.code : code;
   }
 
   /**
@@ -502,6 +540,24 @@ class ExternalModuleManager {
       return null;
     }
 
+    // Normaliza para o código canônico — um install gravado sob um alias
+    // (ex.: `bauto`) precisa resolver para a entrada atual do registry.
+    moduleCode = moduleInfo.code;
+
+    // Módulos marketplace-plugin (entradas do registry marcadas com
+    // `marketplace-plugin`) trazem um .claude-plugin/marketplace.json e mantêm o
+    // module.yaml dentro do assets/ de uma skill, e não num diretório único ao
+    // lado das skills. Resolve pelo PluginResolver (a mesma máquina que os
+    // installs por URL custom usam) e devolve o diretório que contém o
+    // module.yaml, para os chamadores de config/versão/diretório funcionarem;
+    // o install() copia os diretórios de skill resolvidos.
+    if (moduleInfo.marketplacePlugin) {
+      const pluginMod = await this.resolvePluginModule(moduleCode, options);
+      if (pluginMod && pluginMod.moduleYamlPath) {
+        return path.dirname(pluginMod.moduleYamlPath);
+      }
+    }
+
     // Clone the external module repo
     const cloneDir = await this.cloneExternalModule(moduleCode, options);
 
@@ -555,6 +611,88 @@ class ExternalModuleManager {
         `The repository may have been restructured after this release was tagged.${channelHint}`,
     );
   }
+  /**
+   * Resolve um módulo marketplace-plugin do registry para uma definição de
+   * plugin instalável. Clona o repo (respeitando o plano de canal), lê o
+   * .claude-plugin/marketplace.json e roda o PluginResolver contra o plugin que
+   * corresponde a este módulo. O resultado (skillPaths + module.yaml +
+   * module-help.csv) fica em cache para o install() copiar os diretórios de
+   * skill resolvidos.
+   *
+   * @param {string} moduleCode - Código do módulo externo
+   * @param {Object} options - Opções repassadas a cloneExternalModule
+   * @returns {Promise<Object|null>} ResolvedModule do PluginResolver, ou null
+   *   quando o módulo não é marketplace plugin ou não pode ser resolvido.
+   */
+  async resolvePluginModule(moduleCode, options = {}) {
+    const moduleInfo = await this.getModuleByCode(moduleCode);
+    if (!moduleInfo || moduleInfo.builtIn || !moduleInfo.marketplacePlugin) {
+      return null;
+    }
+
+    // Normaliza para o código canônico — ver cloneExternalModule.
+    moduleCode = moduleInfo.code;
+
+    const cloneDir = await this.cloneExternalModule(moduleCode, options);
+
+    const marketplacePath = path.join(cloneDir, '.claude-plugin', 'marketplace.json');
+    if (!(await fs.pathExists(marketplacePath))) {
+      return null;
+    }
+
+    let marketplace;
+    try {
+      marketplace = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+    } catch {
+      return null;
+    }
+
+    const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+    if (plugins.length === 0) {
+      return null;
+    }
+
+    // Prefere o plugin cujo nome bate com o plugin_name do registry (ou o code),
+    // caindo para qualquer plugin que declare skills.
+    const preferredName = moduleInfo.pluginName || moduleInfo.code;
+    const ordered = [...plugins].sort((a, b) => {
+      const am = a?.name === preferredName ? 0 : 1;
+      const bm = b?.name === preferredName ? 0 : 1;
+      return am - bm;
+    });
+
+    const { PluginResolver } = require('./plugin-resolver');
+    const resolver = new PluginResolver();
+
+    for (const plugin of ordered) {
+      if (!plugin || !Array.isArray(plugin.skills) || plugin.skills.length === 0) {
+        continue;
+      }
+      let resolvedMods;
+      try {
+        resolvedMods = await resolver.resolve(cloneDir, plugin);
+      } catch {
+        continue;
+      }
+      if (!resolvedMods || resolvedMods.length === 0) {
+        continue;
+      }
+      // Casa pelo código do registry, depois pelo nome preferido do plugin,
+      // depois aceita um único módulo resolvido.
+      const match =
+        resolvedMods.find((mod) => mod.code === moduleCode) ||
+        resolvedMods.find((mod) => mod.code === preferredName) ||
+        (resolvedMods.length === 1 ? resolvedMods[0] : null);
+      if (match) {
+        match.repoUrl = moduleInfo.url;
+        ExternalModuleManager._pluginResolutions.set(moduleCode, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
+
   cachedModules = null;
 }
 

package/tools/installer/modules/official-modules.js

@@ -316,7 +316,29 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    // Módulos marketplace-plugin do registry mantêm as skills instaláveis fora do
+    // diretório que contém o module.yaml (sourcePath aponta para o assets/ da
+    // skill -setup), então não dá para instalá-los copiando o sourcePath. Copia
+    // os diretórios de skill resolvidos, do mesmo jeito que um install custom de
+    // marketplace monta um módulo. Todo o resto (manifest, versão) segue pelo
+    // caminho padrão de módulo externo abaixo.
+    const marketplaceInfo = await this.externalModuleManager.getModuleByCode(moduleName);
+    if (marketplaceInfo && marketplaceInfo.marketplacePlugin) {
+      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
+      // Falha alto: copiar o sourcePath aqui instalaria só o assets/ da skill
+      // -setup (module.yaml + module-help.csv) e nenhuma skill — um install
+      // parcial e silenciosamente quebrado. Aborta em vez disso.
+      if (!pluginResolution || !Array.isArray(pluginResolution.skillPaths) || pluginResolution.skillPaths.length === 0) {
+        throw new Error(
+          `Module '${moduleName}' is registered as a marketplace plugin but its skills could not be resolved ` +
+            `from .claude-plugin/marketplace.json (missing or malformed on the selected channel). ` +
+            `Aborting to avoid a partial install with no skills.`,
+        );
+      }
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+    } else {
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    }
 
     if (!options.skipModuleInstaller) {
       await this.createModuleDirectories(moduleName, wizzDir, options);
@@ -343,41 +365,66 @@ class OfficialModules {
   }
 
   /**
-   * Install a module from a PluginResolver resolution result.
-   * Copies specific skill directories and places module-help.csv at the target root.
-   * @param {Object} resolved - ResolvedModule from PluginResolver
-   * @param {string} wizzDir - Target wizz directory
-   * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Installation options
+   * Assenta em disco uma resolução do PluginResolver: copia cada diretório de
+   * skill resolvido (achatado pelo nome da folha) para targetPath e coloca o
+   * module-help.csv na raiz do módulo. Compartilhado pelos installs custom de
+   * marketplace (installFromResolution) e pelos installs oficiais de módulo
+   * marketplace-plugin (install), para os dois caminhos não divergirem.
+   * @param {Object} resolved - ResolvedModule do PluginResolver
+   * @param {string} targetPath - Diretório de destino do módulo (ex.: wizzDir/<code>)
+   * @param {Function} fileTrackingCallback - Callback opcional de rastreio de arquivos
+   * @param {Object} moduleConfig - Configuração do módulo repassada ao filtro de cópia
    */
-  async installFromResolution(resolved, wizzDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(wizzDir, resolved.code);
-
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     await fs.ensureDir(targetPath);
 
-    // Copy each skill directory, flattened by leaf name
+    // Copia cada diretório de skill, achatado pelo nome da folha. Os nomes de
+    // folha precisam ser únicos — duas skills que achatam para o mesmo diretório
+    // se sobrescreveriam em silêncio, então falha alto em vez disso.
+    const seenLeaves = new Map();
     for (const skillPath of resolved.skillPaths) {
       const skillDirName = path.basename(skillPath);
+      if (seenLeaves.has(skillDirName)) {
+        throw new Error(
+          `Cannot install module '${resolved.code}': skill directories '${seenLeaves.get(skillDirName)}' and ` +
+            `'${skillPath}' share the leaf name '${skillDirName}' and would overwrite each other. ` +
+            `Skill directory names must be unique.`,
+        );
+      }
+      seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
     }
 
-    // Place module-help.csv at the module root
+    // Coloca o module-help.csv na raiz do módulo.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
     if (resolved.moduleHelpCsvPath) {
-      // Strategies 1-4: copy the existing file
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Estratégias 1-4: copia o arquivo existente.
       await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     } else if (resolved.synthesizedHelpCsv) {
-      // Strategy 5: write synthesized content
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Estratégia 5: escreve o conteúdo sintetizado.
       await fs.writeFile(helpTarget, resolved.synthesizedHelpCsv, 'utf8');
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     }
+  }
+
+  /**
+   * Install a module from a PluginResolver resolution result.
+   * Copies specific skill directories and places module-help.csv at the target root.
+   * @param {Object} resolved - ResolvedModule from PluginResolver
+   * @param {string} wizzDir - Target wizz directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Installation options
+   */
+  async installFromResolution(resolved, wizzDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(wizzDir, resolved.code);
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {

package/tools/installer/prompts.js

@@ -10,7 +10,6 @@
 let _clack = null;
 let _clackCore = null;
 let _picocolors = null;
-const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
@@ -578,10 +577,6 @@ async function autocomplete(options) {
   return result;
 }
 
-function hasPathSeparator(value) {
-  return value.endsWith('/') || value.endsWith('\\');
-}
-
 function expandHome(input) {
   if (!input) return input;
   if (input === '~') return os.homedir();
@@ -591,91 +586,60 @@ function expandHome(input) {
   return input;
 }
 
-function toDirectoryOption(value, label = value, synthetic = false) {
-  return { value, label, synthetic };
-}
-
-function isExistingDirectory(value) {
-  try {
-    return fs.existsSync(value) && fs.statSync(value).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function listDirectoryOptions(input, options) {
+/**
+ * Resolve o texto do prompt de diretório para um caminho absoluto.
+ * @param {string} input - Texto submetido
+ * @param {Object} [options] - { cwd, default }
+ * @returns {string} Caminho absoluto
+ */
+function resolveDirectoryInput(input, options = {}) {
   const cwd = options.cwd || process.cwd();
-  const rawInput = input.trim();
-  const expandedInput = expandHome(rawInput);
-  const trailingSep = hasPathSeparator(rawInput) || hasPathSeparator(expandedInput);
-  const resolvedInput = expandedInput ? path.resolve(cwd, expandedInput) : cwd;
-  const browseDir = expandedInput && !trailingSep && !isExistingDirectory(resolvedInput) ? path.dirname(resolvedInput) : resolvedInput;
-  const prefix = expandedInput && browseDir !== resolvedInput ? path.basename(resolvedInput).toLowerCase() : '';
-  const results = [];
-
-  if (!trailingSep && isExistingDirectory(resolvedInput)) {
-    results.push(toDirectoryOption(resolvedInput, `. (use this directory)`));
-  }
-
-  if (isExistingDirectory(browseDir)) {
-    try {
-      for (const entry of fs.readdirSync(browseDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        if (prefix && !entry.name.toLowerCase().startsWith(prefix)) continue;
-        const fullPath = path.join(browseDir, entry.name);
-        if (!results.some((option) => option.value === fullPath)) {
-          results.push(toDirectoryOption(fullPath));
-        }
-      }
-    } catch {
-      // Skip unreadable directories; validation still reports path issues.
-    }
-  }
-
-  const validation = options.validate?.(rawInput);
-  const hasMatchingOption = results.some((option) => option.value === resolvedInput);
-  if (expandedInput && !validation && !hasMatchingOption) {
-    results.unshift(toDirectoryOption(resolvedInput, `Create/use: ${resolvedInput}`, true));
-  }
-
-  return results;
+  const rawInput = typeof input === 'string' ? input.trim() : '';
+  // Linha vazia significa "usar o default", resolvido do mesmo jeito que texto
+  // digitado, para um default `~/…` ou relativo ainda devolver caminho absoluto.
+  const effective = rawInput || (options.default || '').trim();
+  if (!effective) return cwd;
+  return path.resolve(cwd, expandHome(effective));
 }
 
 /**
- * Directory prompt with autocomplete candidates and create-directory support.
- * Uses @clack/core directly so typed paths that do not exist yet can still be
- * submitted when validation allows creating them.
+ * Directory prompt.
+ *
+ * Entrada de texto simples: o que está na linha é o que é submetido, resolvido
+ * para caminho absoluto.
+ *
+ * A linha vem pré-preenchida com o default (o diretório atual, de onde os
+ * installs costumam ser rodados) como texto editável de verdade, e não como
+ * placeholder, para poder ser encurtada ou estendida em vez de redigitada.
+ * Limpar a linha e apertar Enter ainda aceita o default.
+ *
+ * Substitui uma AutocompletePrompt cuja lista de candidatos era invisível: o
+ * Enter devolvia a opção em foco, não o texto digitado, então dava para instalar
+ * num caminho que o usuário nunca escreveu. Com TextPrompt o defeito some por
+ * construção — não existe seleção escondida que o Enter possa submeter.
+ *
  * @param {Object} options - Prompt options
  * @param {string} options.message - Prompt message
- * @param {string} [options.default] - Default directory
- * @param {string} [options.placeholder] - Placeholder text
+ * @param {string} [options.default] - Default directory, pré-preenchido na linha
+ * @param {string} [options.placeholder] - Placeholder mostrado só se a linha for limpa
  * @param {Function} [options.validate] - Sync validation function
- * @returns {Promise<string>} Selected or typed directory path
+ * @param {Object} [options.input] - Input stream (default process.stdin; testes injetam)
+ * @param {Object} [options.output] - Output stream (default process.stdout; testes injetam)
+ * @returns {Promise<string>} Caminho absoluto do diretório
  */
 async function directory(options) {
   const core = await getClackCore();
   const color = await getPicocolors();
-  const tabCompletion = {
-    prefix: '',
-    index: -1,
-    options: [],
-    lastValue: '',
-  };
 
-  let prompt;
-  prompt = new core.AutocompletePrompt({
+  const prompt = new core.TextPrompt({
+    ...(options.input ? { input: options.input } : {}),
+    ...(options.output ? { output: options.output } : {}),
     initialValue: options.default,
-    options: () => listDirectoryOptions(prompt?.userInput || '', options),
-    filter: () => true,
-    validate: (value) => options.validate?.(value ?? prompt.userInput),
+    defaultValue: options.default,
+    validate: options.validate,
     render() {
-      const title = `${color.gray('◆')}  ${options.message}`;
       const bar = color.gray('│');
-      const barEnd = color.gray('└');
       const userInput = this.userInput;
-      const placeholder = options.placeholder || options.default;
-      const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
-      const errorLine = this.state === 'error' ? [`${color.yellow('│')}  ${color.yellow(this.error)}`] : [];
 
       switch (this.state) {
         case 'submit': {
@@ -685,42 +649,20 @@ async function directory(options) {
           return `${color.gray('◇')}  ${options.message}\n${bar}  ${color.strikethrough(color.dim(userInput || ''))}`;
         }
         default: {
-          return [title, `${bar}  ${inputDisplay}`, ...errorLine, barEnd].join('\n');
+          const placeholder = options.placeholder || options.default;
+          const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
+          const lines = [`${color.gray('◆')}  ${options.message}`, `${bar}  ${inputDisplay}`];
+          if (this.state === 'error') lines.push(`${color.yellow('│')}  ${color.yellow(this.error)}`);
+          lines.push(color.gray('└'));
+          return lines.join('\n');
         }
       }
     },
   });
 
-  const hasSetUserInput = typeof prompt._setUserInput === 'function';
-  const hasClearUserInput = typeof prompt._clearUserInput === 'function';
-
-  prompt.on('key', (_, key) => {
-    if (key?.name !== 'tab') return;
-    if (!hasSetUserInput) return; // @clack/core API surface changed — skip Tab silently.
-    const currentInput = prompt.userInput;
-    const isContinuingCycle = tabCompletion.lastValue && currentInput === tabCompletion.lastValue;
-    const completionOptions = isContinuingCycle ? tabCompletion.options : prompt.filteredOptions.filter((option) => !option.synthetic);
-    if (completionOptions.length === 0) return;
-
-    if (isContinuingCycle) {
-      tabCompletion.index = (tabCompletion.index + 1) % completionOptions.length;
-    } else {
-      tabCompletion.prefix = currentInput;
-      tabCompletion.options = completionOptions;
-      tabCompletion.index = 0;
-    }
-
-    const focusedOption = completionOptions[tabCompletion.index];
-    if (!focusedOption) return;
-    const completedValue = focusedOption.value;
-    tabCompletion.lastValue = completedValue;
-    if (hasClearUserInput) prompt._clearUserInput();
-    prompt._setUserInput(completedValue, true);
-  });
-
   const result = await prompt.prompt();
   await handleCancel(result);
-  return result;
+  return resolveDirectoryInput(result, options);
 }
 
 /**

package/tools/installer/ui.js

@@ -114,6 +114,45 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
+  /**
+   * Avisa uma vez para cada módulo selecionado que o registry marca como
+   * depreciado.
+   *
+   * Um módulo depreciado nunca é removido da seleção — uma instalação
+   * existente continua funcionando e continua sendo atualizada quando pedido.
+   * O aviso é a única mudança de comportamento, e é ele que informa quem usa
+   * CLI (`--modules`, `--yes`) o que o picker interativo mostra como dica.
+   *
+   * @param {Array<string>} selectedModules - Códigos prestes a ser instalados
+   * @returns {Promise<Array<string>>} Os códigos depreciados que geraram aviso
+   */
+  async _warnDeprecatedModules(selectedModules = []) {
+    const externalManager = new ExternalModuleManager();
+    let registryModules;
+    try {
+      registryModules = await externalManager.listAvailable();
+    } catch {
+      return []; // Registry ilegível — nunca travar uma instalação por causa de um aviso.
+    }
+
+    const deprecatedByCode = new Map();
+    for (const mod of registryModules) {
+      if (!mod.deprecated) continue;
+      deprecatedByCode.set(mod.code, mod);
+      for (const alias of mod.aliases) deprecatedByCode.set(alias, mod);
+    }
+
+    const warned = [];
+    for (const code of selectedModules) {
+      const mod = deprecatedByCode.get(code);
+      if (!mod || warned.includes(mod.code)) continue;
+      warned.push(mod.code);
+      const detail = mod.deprecationMessage || 'It is no longer receiving updates.';
+      await prompts.log.warn(`${mod.name} (${mod.code}) is deprecated. ${detail}`);
+    }
+    return warned;
+  }
+
   async _retainUnavailableInstalledModules(selectedModules, installedModuleIds, wizzDir, options = {}) {
     const { OfficialModules } = require('./modules/official-modules');
     const officialCodes = new Set(['core']);
@@ -274,6 +313,10 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
+        // O Quick Update nunca mostra o picker de módulos, então este é o único
+        // ponto em que uma instalação existente de módulo depreciado ouve o aviso.
+        await this._warnDeprecatedModules(existingInstall.moduleIds || []);
+
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
@@ -338,6 +381,11 @@ class UI {
           );
         }
 
+        // Mostra os avisos de depreciação para o que acabou selecionado. O picker
+        // interativo só dá a dica na lista de opções, e os caminhos --modules /
+        // --yes nunca veem essa lista.
+        await this._warnDeprecatedModules(selectedModules);
+
         // For existing installs, resolve per-module update decisions BEFORE
         // we clone anything. Reads the existing manifest's recorded channel
         // per module and prompts the user on available upgrades (patch/minor
@@ -423,6 +471,8 @@ class UI {
       selectedModules.unshift('core');
     }
 
+    await this._warnDeprecatedModules(selectedModules);
+
     // Interactive channel gate: "Ready to install (all stable)? [Y/n]"
     // Only shown for fresh installs with no channel flags and an external module
     // selected. Skipped for prerelease launches because channelOptions.global
@@ -1236,25 +1286,32 @@ class UI {
       }
     }
 
-    // Add external registry modules (skip built-in duplicates)
-    const externalRegistryModules = registryModules.filter((mod) => !mod.builtIn && !builtInCodes.has(mod.code));
+    // Add external registry modules (skip built-in duplicates and deprecated
+    // modules that are not already installed — um módulo depreciado continua
+    // visível só para quem já o tem instalado poder seguir gerenciando).
+    const externalRegistryModules = registryModules.filter(
+      (mod) => !mod.builtIn && !builtInCodes.has(mod.code) && (!mod.deprecated || installedModuleIds.has(mod.code)),
+    );
     let externalRegistryEntries = [];
     if (externalRegistryModules.length > 0) {
       const spinner = await prompts.spinner();
       spinner.start('Checking latest module versions...');
 
       externalRegistryEntries = await Promise.all(
-        externalRegistryModules.map(async (mod) => ({
-          code: mod.code,
-          entry: await buildModuleEntry(
+        externalRegistryModules.map(async (mod) => {
+          const entry = await buildModuleEntry(
             mod.code,
             mod.name,
             mod.description,
             mod.defaultSelected,
             mod.url || null,
             mod.defaultChannel || null,
-          ),
-        })),
+          );
+          if (mod.deprecated && mod.deprecationMessage) {
+            entry.hint = entry.hint ? `${entry.hint} — ${mod.deprecationMessage}` : mod.deprecationMessage;
+          }
+          return { code: mod.code, entry };
+        }),
       );
 
       spinner.stop('Checked latest module versions.');