wizz-method 1.4.1 → 1.5.0

package/tools/installer/core/installer.js

@@ -3,23 +3,26 @@ const fs = require('../fs-native');
 const { Manifest } = require('./manifest');
 const { OfficialModules } = require('../modules/official-modules');
 const { installSkillsLib } = require('../modules/skills-lib');
-const { writeMcpConfig, renderAddCommand, prepareMcps } = require('../modules/mcp-config');
+const { writeMcpConfig, renderAddCommand, prepareMcps, partitionAlreadyConfigured } = require('../modules/mcp-config');
+const { promptMissingEnvVars } = require('../modules/env-vars');
 const { installClis, renderInstallCommand } = require('../modules/cli-config');
-const { writeDepsCache } = require('../modules/deps-cache');
+const { writeDepsCache, readPreviousMcpPins } = require('../modules/deps-cache');
 const { IdeManager } = require('../ide/manager');
 const { FileOps } = require('../file-ops');
 const { Config } = require('./config');
-const { getProjectRoot, getSourcePath } = require('../project-root');
 const { ManifestGenerator } = require('./manifest-generator');
 const prompts = require('../prompts');
 const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
 const { InstallPaths } = require('./install-paths');
 const { ExternalModuleManager } = require('../modules/external-manager');
 const { resolveModuleVersion } = require('../modules/version-resolver');
-const { MODULE_HELP_CSV_HEADER } = require('../modules/module-help-schema');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
+const userFilePreservation = require('./user-file-preservation');
+const moduleConfigWriter = require('./module-config-writer');
+const helpCatalog = require('./help-catalog');
+const quickUpdateModule = require('./quick-update');
 
 class Installer {
   constructor() {
@@ -40,12 +43,33 @@ class Installer {
    */
   async install(originalConfig) {
     let updateState = null;
+    // Fresh installs (A14, atomic install): the writing pipeline runs against
+    // a sibling `_wizz.tmp-<pid>/` scaffold and only gets renamed into
+    // `_wizz/` after `generateManifests` succeeds. Tracked here (outside the
+    // try's local scope) so the outer catch can remove an orphaned tmp dir
+    // without ever touching a real `_wizz/` — cleared the moment the swap
+    // actually happens, so a later best-effort failure (e.g. IDE setup) never
+    // deletes a now-valid install.
+    let freshInstallTmpDir = null;
 
     try {
       const config = Config.build(originalConfig);
-      const paths = await InstallPaths.create(config);
+
+      // Detect BEFORE creating any scaffold — a plain, read-only check
+      // against the path _wizz/ would live at, untouched by InstallPaths.
+      // This decides tmp-vs-real for InstallPaths.create below; detecting
+      // after paths creation (as before A14) meant the real `_wizz/` was
+      // already force-created as a side effect even for a first-time
+      // install, which is exactly the corruption window this task closes.
+      const projectRootCandidate = path.resolve(config.directory);
+      const realWizzDirCandidate = path.join(projectRootCandidate, WIZZ_FOLDER_NAME);
+      const existingInstall = await ExistingInstall.detect(realWizzDirCandidate);
+      const isFreshInstall = !existingInstall.installed;
+
+      let paths = await InstallPaths.create(config, { useTmp: isFreshInstall });
+      if (isFreshInstall) freshInstallTmpDir = paths.wizzDir;
+
       const officialModules = await OfficialModules.build(config, paths);
-      const existingInstall = await ExistingInstall.detect(paths.wizzDir);
 
       try {
         await warnPreNativeSkillsLegacy({
@@ -87,7 +111,7 @@ class Installer {
 
       const allModules = config.modules || [];
 
-      await this._installAndConfigure(
+      const configureResult = await this._installAndConfigure(
         config,
         originalConfig,
         paths,
@@ -97,6 +121,13 @@ class Installer {
         officialModules,
         previousSkillManifestRows,
       );
+      // Fresh installs got promoted from the tmp scaffold to the real
+      // `_wizz/` inside _installAndConfigure (right after generateManifests
+      // succeeded) — pick up the rewritten paths so every step below
+      // (IDE setup, cleanup, summary) reads/writes the real location, and
+      // the outer catch stops treating this as an orphaned tmp dir.
+      paths = configureResult.paths;
+      if (configureResult.swapped) freshInstallTmpDir = null;
 
       await this._setupIdes(config, allModules, paths, addResult, previousSkillIds);
 
@@ -114,14 +145,30 @@ class Installer {
         customFiles: restoreResult.customFiles.length > 0 ? restoreResult.customFiles : undefined,
         modifiedFiles: restoreResult.modifiedFiles.length > 0 ? restoreResult.modifiedFiles : undefined,
         preInstallVersions,
+        traceEnabled: config.traceEnabled,
       });
 
+      // Some steps (IDE setup, global skills/MCP/CLI provisioning) are
+      // best-effort and record their outcome in `results` instead of
+      // throwing, so one broken IDE or MCP never aborts the rest of the
+      // install. That used to mean a real per-step failure was invisible to
+      // the caller: `success` was always true and the CLI always exited 0.
+      // Surface it structurally instead: 'error' rows (hard failures, e.g.
+      // a suspended/broken IDE setup) flip success to false; 'warn' rows
+      // (recoverable, e.g. a single MCP whose setup script failed) keep
+      // success true but are still counted so CI/automation can detect
+      // "succeeded with warnings" without parsing log text (see M24).
+      const errorCount = results.filter((r) => r.status === 'error').length;
+      const warningCount = results.filter((r) => r.status === 'warn').length;
+
       return {
-        success: true,
+        success: errorCount === 0,
         path: paths.wizzDir,
         modules: config.modules,
         ides: config.ides,
         projectDir: paths.projectRoot,
+        errors: errorCount,
+        warnings: warningCount,
       };
     } catch (error) {
       await prompts.log.error('Installation failed');
@@ -134,6 +181,12 @@ class Installer {
         if (updateState?.tempModifiedBackupDir && (await fs.pathExists(updateState.tempModifiedBackupDir))) {
           await fs.remove(updateState.tempModifiedBackupDir);
         }
+        // A14: a fresh install that never reached the tmp→real swap leaves
+        // only the orphaned `_wizz.tmp-<pid>/` scaffold behind — remove just
+        // that, never the real `_wizz/` (which never existed on this path).
+        if (freshInstallTmpDir && (await fs.pathExists(freshInstallTmpDir))) {
+          await fs.remove(freshInstallTmpDir);
+        }
       } catch {
         // Best-effort cleanup — don't mask the original error
       }
@@ -229,6 +282,12 @@ class Installer {
     const moduleConfigs = officialModules.moduleConfigs;
 
     const dirResults = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
+    // Set true inside configTask the moment the A14 tmp→real swap actually
+    // runs, so the return value below tells `install()` precisely when it's
+    // safe to stop treating the tmp scaffold as something to clean up on
+    // failure — never inferred from path shape (updates and fresh-but-
+    // never-swapped both have `paths.isTmp === false` for different reasons).
+    let swapped = false;
 
     const installTasks = [];
 
@@ -294,6 +353,19 @@ class Installer {
     const configTask = {
       title: 'Generating configurations',
       task: async (message) => {
+        // A14 (atomic fresh install): `.mcp.json` lives outside `_wizz/`, at
+        // the project root. For a fresh install it must not be mutated until
+        // AFTER the tmp→real swap below (right after generateManifests
+        // succeeds) — writing it earlier would leave a mutated `.mcp.json`
+        // even when the install as a whole later fails and the tmp scaffold
+        // gets thrown away. `writeMcpConfig` below runs in `dryRun` mode in
+        // that case (same merge computation, no disk write) so the log
+        // lines/results and the `pinHashes` fed to `writeDepsCache` stay
+        // identical to today; the real write happens once, right after the
+        // swap. Updates (paths.isTmp === false) are out of scope for this
+        // task and keep writing inline, as before.
+        let pendingMcpWrite = null;
+
         await this.generateModuleConfigs(paths.wizzDir, moduleConfigs);
         addResult('Configurations', 'ok', 'generated');
 
@@ -322,6 +394,7 @@ class Installer {
             }
           } catch (error) {
             await prompts.log.warn(`Falha ao instalar skills globais: ${error.message}`);
+            addResult('Global skills', 'warn', error.message);
           }
 
           // Configure recommended MCP servers for the chosen areas. The user's
@@ -330,23 +403,62 @@ class Installer {
           // the rest. Additive + placeholder-secret, so it never clobbers config
           // or leaks tokens; a failure warns and never aborts the install.
           const mcpPlan = config.mcpPlan || { toWrite: [], toRecommend: [] };
+          let mcpPinHashes = {};
           try {
             const toWrite = mcpPlan.toWrite || [];
             if (toWrite.length > 0) {
               message('Configuring MCP servers...');
-              // Some servers (e.g. scrapling) shell out to a binary that must be
-              // installed and resolved to an absolute path first — otherwise we
-              // would write a config the client can't launch (ENOENT). prepareMcps
-              // installs + verifies those, patching server.command to the absolute
-              // path; a server whose setup fails is dropped here (never written)
-              // and reported so the user can fix it, instead of leaving a broken
-              // config behind. Servers without a `setup` block pass through as-is.
+              // Every resolved MCP goes through prepareMcps (DETECT→INSTALL→
+              // VERIFY→RESOLVE) — including ids already present in .mcp.json.
+              // A13 needs the RESOLVED server (setup-bearing entries like
+              // scrapling get their command rewritten to an absolute path) to
+              // hash-compare against what's on disk; comparing against the raw
+              // registry command would always "look changed" for those. This
+              // is still cheap for an already-installed binary: prepareMcp is
+              // detect-first, so only a genuinely missing binary pays for the
+              // network-heavy install/post_install steps.
               const { ready: mcpsReady, failed: mcpsFailed } = await prepareMcps({ mcps: toWrite });
               for (const f of mcpsFailed) {
                 await prompts.log.warn(
                   `MCP ${f.id} não pôde ser preparado (${f.error}). Config NÃO escrita para evitar ENOENT — instale manualmente e adicione depois com \`claude mcp add\`.`,
                 );
               }
+              if (mcpsFailed.length > 0) {
+                addResult('MCP servers', 'warn', `falharam: ${mcpsFailed.map((f) => f.id).join(', ')}`);
+              }
+
+              // Env var assistance (3.3, design em _audit parte 3 seção E):
+              // before writing .mcp.json, detect missing `${VAR}`
+              // placeholders in the servers about to be written and — only
+              // when interactive (never --yes/no-TTY, E1/E5) — offer to fill
+              // them, persisting into `.claude/settings.local.json` (the only
+              // place confirmed to reach the MCP subprocess's env; C7). Runs
+              // on `mcpsReady` (never `toRecommend`) and skips any id already
+              // present in `.mcp.json` — its vars are moot, the additive
+              // merge below ignores that server entirely. A dedicated
+              // try/catch so a failure here only warns and never blocks the
+              // `.mcp.json` write that follows (own principle of this
+              // feature: never fail the install over a skipped/failed var).
+              try {
+                const { toPrepare: mcpsForEnvVars } = await partitionAlreadyConfigured({
+                  projectDir: paths.projectRoot,
+                  mcps: mcpsReady,
+                });
+                const envInteractive = !config.skipPrompts && !!process.stdin.isTTY;
+                await promptMissingEnvVars(mcpsForEnvVars, {
+                  projectDir: paths.projectRoot,
+                  interactive: envInteractive,
+                });
+              } catch (error) {
+                await prompts.log.warn(`Falha ao configurar env vars dos MCPs: ${error.message}`);
+                addResult('MCP env vars', 'warn', error.message);
+              }
+
+              // A13 ("merge aditivo congela pins para sempre"): read the pin
+              // hashes the LAST install recorded so writeMcpConfig can tell an
+              // untouched block (safe to auto-update the pin) from a
+              // user-customized one (never overwritten, only warned about).
+              const previousPins = await readPreviousMcpPins(paths.wizzDir);
               // Intentionally NOT tracked in installedFiles: .mcp.json is a
               // shared, user-owned config we merge into (it may hold the user's
               // own servers). Tracking it would expose it to uninstall removal
@@ -354,12 +466,33 @@ class Installer {
               const mcpResult = await writeMcpConfig({
                 projectDir: paths.projectRoot,
                 mcps: mcpsReady,
+                previousPins,
+                dryRun: paths.isTmp,
               });
+              if (paths.isTmp) {
+                // Real write deferred until after the tmp→real swap (see the
+                // comment at the top of this task and step 4/README below).
+                pendingMcpWrite = { mcpsReady, previousPins };
+              }
+              mcpPinHashes = mcpResult.pinHashes || {};
               if (mcpResult.added.length > 0) {
                 addResult('MCP servers', 'ok', `${mcpResult.added.join(', ')} → .mcp.json`);
               }
+              const pinUpdated = mcpResult.pinUpdated || [];
+              if (pinUpdated.length > 0) {
+                await prompts.log.info(
+                  `MCPs com pin atualizado (bloco não havia sido customizado): ${pinUpdated.map((u) => u.id).join(', ')}`,
+                );
+                addResult('MCP servers', 'ok', `pin atualizado: ${pinUpdated.map((u) => u.id).join(', ')}`);
+              }
+              const pinCustomized = mcpResult.pinCustomized || [];
+              if (pinCustomized.length > 0) {
+                await prompts.log.warn(
+                  `Há atualização de pin disponível para ${pinCustomized.map((c) => c.id).join(', ')}, mas o bloco no .mcp.json foi customizado (diferente do que o installer escreveu) — mantido intacto. Atualize manualmente se quiser o pin novo.`,
+                );
+              }
               if (mcpResult.skipped.length > 0) {
-                await prompts.log.info(`MCPs já presentes no .mcp.json (mantidos): ${mcpResult.skipped.join(', ')}`);
+                await prompts.log.info(`MCPs já presentes e atualizados no .mcp.json (mantidos): ${mcpResult.skipped.join(', ')}`);
               }
             }
             const toRecommend = mcpPlan.toRecommend || [];
@@ -375,6 +508,7 @@ class Installer {
             }
           } catch (error) {
             await prompts.log.warn(`Falha ao configurar MCPs: ${error.message}`);
+            addResult('MCP servers', 'warn', error.message);
           }
 
           // Install/recommend the CLIs the agents shell out to (agent-browser,
@@ -401,6 +535,15 @@ class Installer {
                   `Falha ao instalar CLI ${f.id}: ${f.error}. Rode manualmente: ${renderInstallCommand(toInstall.find((c) => c.id === f.id) || {})}`,
                 );
               }
+              if (cliResult.failed.length > 0) {
+                addResult('CLIs', 'warn', `falharam: ${cliResult.failed.map((f) => f.id).join(', ')}`);
+              }
+              // M14: verify failure never aborts (CLIs are opt-in) — just a
+              // clear warning that the tool cloned/installed but a runtime
+              // dependency might still be missing.
+              for (const w of cliResult.warnings || []) {
+                await prompts.log.warn(`CLI ${w.id} instalado, mas ${w.warning}`);
+              }
             }
             const toRecommend = cliPlan.toRecommend || [];
             if (toRecommend.length > 0) {
@@ -409,6 +552,7 @@ class Installer {
             }
           } catch (error) {
             await prompts.log.warn(`Falha ao configurar CLIs: ${error.message}`);
+            addResult('CLIs', 'warn', error.message);
           }
 
           // Persist a project-local cache of the skill dependencies (CLIs +
@@ -422,7 +566,10 @@ class Installer {
               wizzDir: paths.wizzDir,
               selectedAreas: config.selectedAreas || [],
               cliPlan: config.cliPlan || {},
-              mcpPlan: config.mcpPlan || {},
+              // pinHashes (A13) is the writeMcpConfig result computed above,
+              // not part of the config-time plan — merged in here so the
+              // NEXT install's readPreviousMcpPins() can see it.
+              mcpPlan: { ...config.mcpPlan, pinHashes: mcpPinHashes },
               trackFile: (p) => this.installedFiles.add(p),
             });
             if (depsResult.wrote) {
@@ -430,7 +577,16 @@ class Installer {
             }
           } catch (error) {
             await prompts.log.warn(`Falha ao gravar cache de dependências: ${error.message}`);
+            addResult('Skill deps cache', 'warn', error.message);
           }
+        } else if (config.isQuickUpdate() && (config.modules || []).includes('bmm')) {
+          // Gate above only runs for fresh installs / Modify. Quick Update
+          // preserves settings and skips provisioning entirely, so say it
+          // explicitly instead of leaving the user to notice by absence
+          // (see project memory: "atualizei e não veio skill").
+          await prompts.log.info(
+            'Quick Update: skills globais, MCPs e CLIs não foram alterados. Rode install e escolha "Modify Wizz Installation" para instalar itens novos.',
+          );
         }
 
         message('Generating manifests...');
@@ -456,7 +612,44 @@ class Installer {
           ides: config.ides || [],
           preservedModules: modulesForCsvPreserve,
           moduleConfigs,
+          // A14: wizzDir is still the tmp scaffold at this point for a fresh
+          // install (swap happens right below, after this call succeeds) —
+          // skill-manifest.csv must embed the REAL folder name regardless,
+          // or every skill path recorded in it (read later by IDE setup,
+          // post-swap) would point at a `_wizz.tmp-<pid>/` dir that no
+          // longer exists. `paths.realWizzDir` is set by InstallPaths.create
+          // for both tmp and non-tmp installs; guarded here because some
+          // tests hand-roll a minimal `paths` stand-in without it, in which
+          // case falling back to generateManifests' own default (basename of
+          // wizzDir) is exactly the pre-A14 behavior.
+          wizzFolderName: paths.realWizzDir ? path.basename(paths.realWizzDir) : undefined,
         });
+
+        // A14 atomic swap: generateManifests just succeeded, so the tmp
+        // scaffold now has a valid manifest.yaml — promote it to the real
+        // `_wizz/` in one same-filesystem rename. Anything that threw above
+        // this line (module copy, configs, global skills, MCP prepare, CLI
+        // install, deps cache, or generateManifests itself) never reaches
+        // here, so `install()`'s catch finds only the orphaned tmp dir and
+        // the real `_wizz/` never existed. No-op for updates (paths.isTmp
+        // is false; they were never given a tmp scaffold).
+        if (paths.isTmp) {
+          await fs.rename(paths.wizzDir, paths.realWizzDir);
+          paths = paths.toReal();
+          swapped = true;
+        }
+
+        // Perform the .mcp.json write deferred above, now that the swap
+        // succeeded. No-op when nothing was staged (non-wizz install, no
+        // areas selected, or an update that already wrote inline).
+        if (pendingMcpWrite) {
+          await writeMcpConfig({
+            projectDir: paths.projectRoot,
+            mcps: pendingMcpWrite.mcpsReady,
+            previousPins: pendingMcpWrite.previousPins,
+          });
+        }
+
         await this._appendPreservedSkillManifestRows(paths.wizzDir, previousSkillManifestRows, preservedModules);
 
         // Apply post-install --set TOML patches. Runs after writeCentralConfig
@@ -500,6 +693,11 @@ class Installer {
     }
 
     await prompts.tasks([configTask]);
+
+    // `paths` may have been reassigned above (fresh install: tmp → real,
+    // see the A14 swap inside configTask) — return it so `install()` picks
+    // up the real location for every step that runs after this returns.
+    return { paths, swapped };
   }
 
   /**
@@ -577,7 +775,8 @@ class Installer {
         const entries = await fs.readdir(current);
         if (entries.length > 0) break;
         await fs.rmdir(current);
-      } catch {
+      } catch (error) {
+        await prompts.log.warn(`Warning: could not remove empty directory ${current}: ${error.message}`);
         break;
       }
       current = path.dirname(current);
@@ -648,66 +847,7 @@ class Installer {
    * @returns {Object} { customFiles, modifiedFiles } — lists of restored files
    */
   async _restoreUserFiles(paths, updateState) {
-    const noFiles = { customFiles: [], modifiedFiles: [] };
-
-    if (!updateState || (updateState.customFiles.length === 0 && updateState.modifiedFiles.length === 0)) {
-      return noFiles;
-    }
-
-    let restoredCustomFiles = [];
-    let restoredModifiedFiles = [];
-
-    await prompts.tasks([
-      {
-        title: 'Finalizing installation',
-        task: async (message) => {
-          if (updateState.customFiles.length > 0) {
-            message(`Restoring ${updateState.customFiles.length} custom files...`);
-
-            for (const originalPath of updateState.customFiles) {
-              const relativePath = path.relative(paths.wizzDir, originalPath);
-              const backupPath = path.join(updateState.tempBackupDir, relativePath);
-
-              if (await fs.pathExists(backupPath)) {
-                await fs.ensureDir(path.dirname(originalPath));
-                await fs.copy(backupPath, originalPath, { overwrite: true });
-              }
-            }
-
-            if (updateState.tempBackupDir && (await fs.pathExists(updateState.tempBackupDir))) {
-              await fs.remove(updateState.tempBackupDir);
-            }
-
-            restoredCustomFiles = updateState.customFiles;
-          }
-
-          if (updateState.modifiedFiles.length > 0) {
-            restoredModifiedFiles = updateState.modifiedFiles;
-
-            if (updateState.tempModifiedBackupDir && (await fs.pathExists(updateState.tempModifiedBackupDir))) {
-              message(`Restoring ${restoredModifiedFiles.length} modified files as .bak...`);
-
-              for (const modifiedFile of restoredModifiedFiles) {
-                const relativePath = path.relative(paths.wizzDir, modifiedFile.path);
-                const tempBackupPath = path.join(updateState.tempModifiedBackupDir, relativePath);
-                const bakPath = modifiedFile.path + '.bak';
-
-                if (await fs.pathExists(tempBackupPath)) {
-                  await fs.ensureDir(path.dirname(bakPath));
-                  await fs.copy(tempBackupPath, bakPath, { overwrite: true });
-                }
-              }
-
-              await fs.remove(updateState.tempModifiedBackupDir);
-            }
-          }
-
-          return 'Installation finalized';
-        },
-      },
-    ]);
-
-    return { customFiles: restoredCustomFiles, modifiedFiles: restoredModifiedFiles };
+    return userFilePreservation.restoreUserFiles(paths, updateState);
   }
 
   /**
@@ -758,34 +898,7 @@ class Installer {
    * @returns {Object} { tempBackupDir, tempModifiedBackupDir } — undefined if no files
    */
   async _backupUserFiles(paths, customFiles, modifiedFiles) {
-    let tempBackupDir;
-    let tempModifiedBackupDir;
-
-    if (customFiles.length > 0) {
-      tempBackupDir = path.join(paths.projectRoot, '_wizz-custom-backup-temp');
-      await fs.ensureDir(tempBackupDir);
-
-      for (const customFile of customFiles) {
-        const relativePath = path.relative(paths.wizzDir, customFile);
-        const backupPath = path.join(tempBackupDir, relativePath);
-        await fs.ensureDir(path.dirname(backupPath));
-        await fs.copy(customFile, backupPath);
-      }
-    }
-
-    if (modifiedFiles.length > 0) {
-      tempModifiedBackupDir = path.join(paths.projectRoot, '_wizz-modified-backup-temp');
-      await fs.ensureDir(tempModifiedBackupDir);
-
-      for (const modifiedFile of modifiedFiles) {
-        const relativePath = path.relative(paths.wizzDir, modifiedFile.path);
-        const tempBackupPath = path.join(tempModifiedBackupDir, relativePath);
-        await fs.ensureDir(path.dirname(tempBackupPath));
-        await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
-      }
-    }
-
-    return { tempBackupDir, tempModifiedBackupDir };
+    return userFilePreservation.backupUserFiles(paths, customFiles, modifiedFiles);
   }
 
   /**
@@ -966,115 +1079,7 @@ class Installer {
    * @returns {Object} Object with customFiles and modifiedFiles arrays
    */
   async detectCustomFiles(wizzDir, existingFilesManifest) {
-    const customFiles = [];
-    const modifiedFiles = [];
-
-    // Memory subtrees (v6.1: _wizz/_memory, current: _wizz/memory) hold
-    // per-user runtime data generated by agents with sidecars. These files
-    // aren't installer-managed and must never be reported as "custom" or
-    // "modified" — they're user state, not user overrides.
-    const wizzMemoryPaths = ['_memory', 'memory'];
-
-    // Check if the manifest has hashes - if not, we can't detect modifications
-    let manifestHasHashes = false;
-    if (existingFilesManifest && existingFilesManifest.length > 0) {
-      manifestHasHashes = existingFilesManifest.some((f) => f.hash);
-    }
-
-    // Build map of previously installed files from files-manifest.csv with their hashes
-    const installedFilesMap = new Map();
-    for (const fileEntry of existingFilesManifest) {
-      if (fileEntry.path) {
-        const absolutePath = path.join(wizzDir, fileEntry.path);
-        installedFilesMap.set(path.normalize(absolutePath), {
-          hash: fileEntry.hash,
-          relativePath: fileEntry.path,
-        });
-      }
-    }
-
-    // Recursively scan wizzDir for all files
-    const scanDirectory = async (dir) => {
-      try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-
-          if (entry.isDirectory()) {
-            // Skip certain directories
-            if (entry.name === 'node_modules' || entry.name === '.git') {
-              continue;
-            }
-            await scanDirectory(fullPath);
-          } else if (entry.isFile()) {
-            const normalizedPath = path.normalize(fullPath);
-            const fileInfo = installedFilesMap.get(normalizedPath);
-
-            // Skip certain system files that are auto-generated
-            const relativePath = path.relative(wizzDir, fullPath);
-            const fileName = path.basename(fullPath);
-
-            // Skip _config directory EXCEPT for modified agent customizations
-            if (relativePath.startsWith('_config/') || relativePath.startsWith('_config\\')) {
-              // Special handling for .customize.yaml files - only preserve if modified
-              if (relativePath.includes('/agents/') && fileName.endsWith('.customize.yaml')) {
-                // Check if the customization file has been modified from manifest
-                const manifestPath = path.join(wizzDir, '_config', 'manifest.yaml');
-                if (await fs.pathExists(manifestPath)) {
-                  const crypto = require('node:crypto');
-                  const currentContent = await fs.readFile(fullPath, 'utf8');
-                  const currentHash = crypto.createHash('sha256').update(currentContent).digest('hex');
-
-                  const yaml = require('yaml');
-                  const manifestContent = await fs.readFile(manifestPath, 'utf8');
-                  const manifestData = yaml.parse(manifestContent);
-                  const originalHash = manifestData.agentCustomizations?.[relativePath];
-
-                  // Only add to customFiles if hash differs (user modified)
-                  if (originalHash && currentHash !== originalHash) {
-                    customFiles.push(fullPath);
-                  }
-                }
-              }
-              continue;
-            }
-
-            if (wizzMemoryPaths.some((mp) => relativePath === mp || relativePath.startsWith(mp + '/'))) {
-              continue;
-            }
-
-            // Skip config.yaml files - these are regenerated on each install/update
-            if (fileName === 'config.yaml') {
-              continue;
-            }
-
-            if (!fileInfo) {
-              // File not in manifest = custom file
-              // EXCEPT: Agent .md files in module folders are generated files, not custom
-              // Only treat .md files under _config/agents/ as custom
-              if (!(fileName.endsWith('.md') && relativePath.includes('/agents/') && !relativePath.startsWith('_config/'))) {
-                customFiles.push(fullPath);
-              }
-            } else if (manifestHasHashes && fileInfo.hash) {
-              // File in manifest with hash - check if it was modified
-              const currentHash = await this.manifest.calculateFileHash(fullPath);
-              if (currentHash && currentHash !== fileInfo.hash) {
-                // Hash changed = file was modified
-                modifiedFiles.push({
-                  path: fullPath,
-                  relativePath: fileInfo.relativePath,
-                });
-              }
-            }
-          }
-        }
-      } catch {
-        // Ignore errors scanning directories
-      }
-    };
-
-    await scanDirectory(wizzDir);
-    return { customFiles, modifiedFiles };
+    return userFilePreservation.detectCustomFiles(wizzDir, existingFilesManifest, { manifest: this.manifest });
   }
 
   /**
@@ -1083,93 +1088,7 @@ class Installer {
    * @param {Object} moduleConfigs - Collected configuration values
    */
   async generateModuleConfigs(wizzDir, moduleConfigs) {
-    const yaml = require('yaml');
-
-    // Extract core config values to share with other modules
-    const coreConfig = moduleConfigs.core || {};
-
-    // Get all installed module directories
-    const entries = await fs.readdir(wizzDir, { withFileTypes: true });
-    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
-    const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
-
-    // Generate config.yaml for each installed module
-    for (const moduleName of installedModules) {
-      const modulePath = path.join(wizzDir, moduleName);
-
-      // Get module-specific config or use empty object if none
-      const config = moduleConfigs[moduleName] || {};
-
-      if (await fs.pathExists(modulePath)) {
-        const configPath = path.join(modulePath, 'config.yaml');
-
-        // Create header
-        const packageJson = require(path.join(getProjectRoot(), 'package.json'));
-        const header = `# ${moduleName.toUpperCase()} Module Configuration
-# Generated by Wizz Method installer
-# Version: ${packageJson.version}
-# Date: ${new Date().toISOString()}
-
-`;
-
-        // For non-core modules, add core config values directly
-        let finalConfig = { ...config };
-        let coreSection = '';
-
-        if (moduleName !== 'core' && coreConfig && Object.keys(coreConfig).length > 0) {
-          // Add core values directly to the module config
-          // These will be available for reference in the module
-          finalConfig = {
-            ...config,
-            ...coreConfig, // Spread core config values directly into the module config
-          };
-
-          // Create a comment section to identify core values
-          coreSection = '\n# Core Configuration Values\n';
-        }
-
-        // Clean the config to remove any non-serializable values (like functions)
-        const cleanConfig = structuredClone(finalConfig);
-
-        // Convert config to YAML
-        let yamlContent = yaml.stringify(cleanConfig, {
-          indent: 2,
-          lineWidth: 0,
-          minContentWidth: 0,
-        });
-
-        // If we have core values, reorganize the YAML to group them with their comment
-        if (coreSection && moduleName !== 'core') {
-          // Split the YAML into lines
-          const lines = yamlContent.split('\n');
-          const moduleConfigLines = [];
-          const coreConfigLines = [];
-
-          // Separate module-specific and core config lines
-          for (const line of lines) {
-            const key = line.split(':')[0].trim();
-            if (Object.prototype.hasOwnProperty.call(coreConfig, key)) {
-              coreConfigLines.push(line);
-            } else {
-              moduleConfigLines.push(line);
-            }
-          }
-
-          // Rebuild YAML with module config first, then core config with comment
-          yamlContent = moduleConfigLines.join('\n');
-          if (coreConfigLines.length > 0) {
-            yamlContent += coreSection + coreConfigLines.join('\n');
-          }
-        }
-
-        // Write the clean config file with POSIX-compliant final newline
-        const content = header + yamlContent;
-        await fs.writeFile(configPath, content.endsWith('\n') ? content : content + '\n', 'utf8');
-
-        // Track the config file in installedFiles
-        this.installedFiles.add(configPath);
-      }
-    }
+    return moduleConfigWriter.generateModuleConfigs(wizzDir, moduleConfigs, { trackFile: (p) => this.installedFiles.add(p) });
   }
 
   /**
@@ -1179,118 +1098,14 @@ class Installer {
    * @param {string} wizzDir - WIZZ installation directory
    * @param {Array<Object>} _agentEntries - Unused; retained for call-site compatibility
    */
-  async mergeModuleHelpCatalogs(wizzDir, _agentEntries = []) {
-    const allRows = [];
-    const headerRow = MODULE_HELP_CSV_HEADER;
-    const COLUMN_COUNT = 13;
-    const PHASE_INDEX = 7;
-
-    // Get all installed module directories
-    const entries = await fs.readdir(wizzDir, { withFileTypes: true });
-    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
-    const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
-
-    // Add core module to scan (it's installed at root level as _config, but we check src/core-skills)
-    const coreModulePath = getSourcePath('core-skills');
-    const modulePaths = new Map();
-
-    // Map all module source paths
-    if (await fs.pathExists(coreModulePath)) {
-      modulePaths.set('core', coreModulePath);
-    }
-
-    // Map installed module paths
-    for (const moduleName of installedModules) {
-      const modulePath = path.join(wizzDir, moduleName);
-      modulePaths.set(moduleName, modulePath);
-    }
-
-    // Scan each module for module-help.csv
-    for (const [moduleName, modulePath] of modulePaths) {
-      const helpFilePath = path.join(modulePath, 'module-help.csv');
-
-      if (await fs.pathExists(helpFilePath)) {
-        try {
-          const content = await fs.readFile(helpFilePath, 'utf8');
-          const lines = content.split('\n').filter((line) => line.trim() && !line.startsWith('#'));
-
-          let headerWarned = false;
-          for (const line of lines) {
-            // Header row: warn on drift from canonical schema, then skip.
-            // Data rows are loaded positionally regardless, so the warning
-            // is advisory — the maintainer should rename their columns.
-            if (line.startsWith('module,')) {
-              if (!headerWarned && line.trim() !== headerRow) {
-                await prompts.log.warn(
-                  `  ${moduleName}/module-help.csv header does not match canonical schema. ` +
-                    `Expected: ${headerRow} | Found: ${line.trim()} | Data loaded positionally.`,
-                );
-                headerWarned = true;
-              }
-              continue;
-            }
-
-            // Parse the line - handle quoted fields with commas
-            const columns = this.parseCSVLine(line);
-            if (columns.length < COLUMN_COUNT - 1) continue;
-
-            // Pad short rows; truncate over-long rows
-            const padded = columns.slice(0, COLUMN_COUNT);
-            while (padded.length < COLUMN_COUNT) padded.push('');
-
-            // If module column is empty, fill with this module's name
-            // (core stays empty so its rows render as universal tools)
-            if ((!padded[0] || padded[0].trim() === '') && moduleName !== 'core') {
-              padded[0] = moduleName;
-            }
-
-            allRows.push(padded.map((c) => this.escapeCSVField(c)).join(','));
-          }
-
-          if (process.env.WIZZ_VERBOSE_INSTALL === 'true') {
-            await prompts.log.message(`  Merged module-help from: ${moduleName}`);
-          }
-        } catch (error) {
-          await prompts.log.warn(`  Warning: Failed to read module-help.csv from ${moduleName}: ${error.message}`);
-        }
-      }
-    }
-
-    // Sort by module, then phase. Stable sort preserves authored order within a phase.
-    const decorated = allRows.map((row, index) => ({ row, index, cols: this.parseCSVLine(row) }));
-    decorated.sort((a, b) => {
-      const moduleA = (a.cols[0] || '').toLowerCase();
-      const moduleB = (b.cols[0] || '').toLowerCase();
-      if (moduleA !== moduleB) return moduleA.localeCompare(moduleB);
-
-      const phaseA = a.cols[PHASE_INDEX] || '';
-      const phaseB = b.cols[PHASE_INDEX] || '';
-      if (phaseA !== phaseB) return phaseA.localeCompare(phaseB);
-
-      return a.index - b.index;
-    });
-    const sortedRows = decorated.map((d) => d.row);
-
-    // Write merged catalog
-    const outputDir = path.join(wizzDir, '_config');
-    await fs.ensureDir(outputDir);
-    const outputPath = path.join(outputDir, 'wizz-help.csv');
-
-    const mergedContent = [headerRow, ...sortedRows].join('\n');
-    await fs.writeFile(outputPath, mergedContent, 'utf8');
-
-    // Track the installed file
-    this.installedFiles.add(outputPath);
-
-    if (process.env.WIZZ_VERBOSE_INSTALL === 'true') {
-      await prompts.log.message(`  Generated wizz-help.csv: ${sortedRows.length} workflows`);
-    }
+  async mergeModuleHelpCatalogs(wizzDir, agentEntries = []) {
+    return helpCatalog.mergeModuleHelpCatalogs(wizzDir, agentEntries, { trackFile: (p) => this.installedFiles.add(p) });
   }
 
   /**
    * Render a consolidated install summary using prompts.note()
    * @param {Array} results - Array of {step, status: 'ok'|'error'|'warn', detail}
-   * @param {Object} context - {wizzDir, modules, ides, customFiles, modifiedFiles}
+   * @param {Object} context - {wizzDir, modules, ides, customFiles, modifiedFiles, traceEnabled}
    */
   async renderInstallSummary(results, context = {}) {
     const color = await prompts.getColor();
@@ -1362,6 +1177,19 @@ class Installer {
       lines.push(`  ${color.yellow(`Modified files backed up (.bak): ${context.modifiedFiles.length}`)}`);
     }
 
+    // 3.8-E1: mention the routing-trace opt-in choice. `traceEnabled` is
+    // `null` when the question was never asked (quick-update/update, or a
+    // module set without bmm) — that case is intentionally silent instead of
+    // misreporting an unasked question as "desligado".
+    if (context.traceEnabled === true) {
+      lines.push(
+        `  ${color.cyan('Medidor de roteamento: ligado')} (WIZZ_TRACE=1 em .claude/settings.local.json)`,
+        `    Para desligar: remova "WIZZ_TRACE" de .claude/settings.local.json (ou defina "0")`,
+      );
+    } else if (context.traceEnabled === false) {
+      lines.push(`  Medidor de roteamento: desligado (rode o install de novo para ligar)`);
+    }
+
     // Next steps
     lines.push(
       '',
@@ -1385,172 +1213,7 @@ class Installer {
    * @returns {Object} Update result
    */
   async quickUpdate(config) {
-    const projectDir = path.resolve(config.directory);
-    const { wizzDir } = await this.findWizzDir(projectDir);
-
-    // Check if wizz directory exists
-    if (!(await fs.pathExists(wizzDir))) {
-      throw new Error(`Wizz not installed at ${wizzDir}. Use regular install for first-time setup.`);
-    }
-
-    // Detect existing installation
-    const existingInstall = await ExistingInstall.detect(wizzDir);
-    const installedModules = existingInstall.moduleIds;
-    const configuredIdes = existingInstall.ides;
-    const projectRoot = path.dirname(wizzDir);
-
-    // Get available modules (what we have source for)
-    const availableModulesData = await new OfficialModules().listAvailable();
-    const availableModules = [...availableModulesData.modules];
-
-    // Add external official modules to available modules
-    const externalModules = await this.externalModuleManager.listAvailable();
-    for (const externalModule of externalModules) {
-      if (installedModules.includes(externalModule.code) && !availableModules.some((m) => m.id === externalModule.code)) {
-        availableModules.push({
-          id: externalModule.code,
-          name: externalModule.name,
-          isExternal: true,
-          fromExternal: true,
-        });
-      }
-    }
-
-    // Add installed custom modules to available modules
-    const { CustomModuleManager } = require('../modules/custom-module-manager');
-    const customMgr = new CustomModuleManager();
-    for (const moduleId of installedModules) {
-      if (!availableModules.some((m) => m.id === moduleId)) {
-        const customSource = await customMgr.findModuleSourceByCode(moduleId, { wizzDir });
-        if (customSource) {
-          availableModules.push({
-            id: moduleId,
-            name: moduleId,
-            isExternal: true,
-            fromCustom: true,
-          });
-        }
-      }
-    }
-
-    const availableModuleIds = new Set(availableModules.map((m) => m.id));
-
-    // Only update modules that are BOTH installed AND available (we have source for)
-    const modulesToUpdate = installedModules.filter((id) => availableModuleIds.has(id));
-    const skippedModules = installedModules.filter((id) => !availableModuleIds.has(id));
-
-    if (skippedModules.length > 0) {
-      await prompts.log.warn(`Skipping ${skippedModules.length} module(s) - no source available: ${skippedModules.join(', ')}`);
-    }
-
-    // Build channel options from the existing manifest FIRST so the config
-    // collector below (which triggers external-module clones via
-    // findModuleSource) knows each module's recorded channel and doesn't
-    // silently redecide it. Without this, modules previously on 'next' or
-    // 'pinned' would trigger a stable-channel tag lookup at config-collection
-    // time, burning GitHub API quota and potentially failing.
-    const manifestData = await this.manifest.read(wizzDir);
-    const channelOptions = { global: null, nextSet: new Set(), pins: new Map(), warnings: [] };
-    if (manifestData?.modulesDetailed) {
-      const { fetchStableTags, classifyUpgrade, parseGitHubRepo } = require('../modules/channel-resolver');
-      for (const entry of manifestData.modulesDetailed) {
-        if (!entry?.name || !entry?.channel) continue;
-        if (entry.channel === 'pinned' && entry.version) {
-          channelOptions.pins.set(entry.name, entry.version);
-          continue;
-        }
-        if (entry.channel === 'next') {
-          channelOptions.nextSet.add(entry.name);
-          continue;
-        }
-        // Stable: classify the available upgrade. Patches and minors fall
-        // through (stable default picks up the top tag). A major upgrade
-        // requires opt-in, so under quick-update's non-interactive semantics
-        // we pin to the current version to prevent a silent breaking jump.
-        if (entry.channel === 'stable' && entry.version && entry.repoUrl) {
-          const parsed = parseGitHubRepo(entry.repoUrl);
-          if (!parsed) continue;
-          try {
-            const tags = await fetchStableTags(parsed.owner, parsed.repo);
-            if (tags.length === 0) continue;
-            const topTag = tags[0].tag;
-            const cls = classifyUpgrade(entry.version, topTag);
-            if (cls === 'major') {
-              channelOptions.pins.set(entry.name, entry.version);
-              await prompts.log.warn(
-                `${entry.name} ${entry.version} → ${topTag} is a new major release; staying on ${entry.version}. ` +
-                  `Run \`wizz install\` (Modify) with \`--pin ${entry.name}=${topTag}\` to accept.`,
-              );
-            }
-          } catch (error) {
-            // Tag lookup failed (offline, rate-limited). Stay on the current
-            // version rather than guessing — the existing cache is already
-            // at that ref, so re-using it keeps the install stable.
-            channelOptions.pins.set(entry.name, entry.version);
-            await prompts.log.warn(`Could not check ${entry.name} for updates (${error.message}); staying on ${entry.version}.`);
-          }
-        }
-      }
-    }
-
-    // Load existing configs and collect new fields (if any)
-    await prompts.log.info('Checking for new configuration options...');
-    const quickModules = new OfficialModules({ channelOptions });
-    await quickModules.loadExistingConfig(projectDir);
-
-    let promptedForNewFields = false;
-
-    const corePrompted = await quickModules.collectModuleConfigQuick('core', projectDir, true);
-    if (corePrompted) {
-      promptedForNewFields = true;
-    }
-
-    for (const moduleName of modulesToUpdate) {
-      if (moduleName === 'core') continue; // Already collected above
-      const modulePrompted = await quickModules.collectModuleConfigQuick(moduleName, projectDir, true);
-      if (modulePrompted) {
-        promptedForNewFields = true;
-      }
-    }
-
-    if (!promptedForNewFields) {
-      await prompts.log.success('All configuration is up to date, no new options to configure');
-    }
-
-    quickModules.collectedConfig._meta = {
-      version: require(path.join(getProjectRoot(), 'package.json')).version,
-      installDate: new Date().toISOString(),
-      lastModified: new Date().toISOString(),
-    };
-
-    // Build config and delegate to install()
-    const installConfig = {
-      directory: projectDir,
-      modules: modulesToUpdate,
-      ides: configuredIdes,
-      coreConfig: quickModules.collectedConfig.core,
-      moduleConfigs: quickModules.collectedConfig,
-      // Forward `--set` overrides so the post-install patch step
-      // (`applySetOverrides`) runs at the end of quick-update too. The
-      // installer.install path applies them after writeCentralConfig.
-      setOverrides: config.setOverrides || {},
-      actionType: 'install',
-      _quickUpdate: true,
-      _preserveModules: skippedModules,
-      _existingModules: installedModules,
-      channelOptions,
-    };
-
-    await this.install(installConfig);
-
-    return {
-      success: true,
-      moduleCount: modulesToUpdate.length,
-      hadNewFields: promptedForNewFields,
-      modules: modulesToUpdate,
-      skippedModules: skippedModules,
-      ides: configuredIdes,
-    };
+    return quickUpdateModule.quickUpdate(this, config);
   }
 
   /**
@@ -1703,8 +1366,8 @@ class Installer {
           // Strip {project-root}/ prefix if present
           return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
         }
-      } catch {
-        // Fall through to other modules
+      } catch (error) {
+        await prompts.log.warn(`Warning: could not read ${bmmConfigPath}: ${error.message}`);
       }
     }
 
@@ -1721,13 +1384,13 @@ class Installer {
             if (config && config.output_folder) {
               return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
             }
-          } catch {
-            // Continue scanning
+          } catch (error) {
+            await prompts.log.warn(`Warning: could not read ${configPath}: ${error.message}`);
           }
         }
       }
-    } catch {
-      // Directory scan failed
+    } catch (error) {
+      await prompts.log.warn(`Warning: could not scan ${wizzDir} for module configs: ${error.message}`);
     }
 
     // Default fallback
@@ -1735,54 +1398,26 @@ class Installer {
   }
 
   /**
-   * Parse a CSV line, handling quoted fields
+   * Parse a CSV line, handling quoted fields.
+   * Thin wrapper — see `core/help-catalog.js` for the implementation and the
+   * M15 rationale (auditoria 2026-07-07) on why this delegates to
+   * `csv-parse/sync`.
    * @param {string} line - CSV line to parse
    * @returns {Array} Array of field values
    */
   parseCSVLine(line) {
-    const result = [];
-    let current = '';
-    let inQuotes = false;
-
-    for (let i = 0; i < line.length; i++) {
-      const char = line[i];
-      const nextChar = line[i + 1];
-
-      if (char === '"') {
-        if (inQuotes && nextChar === '"') {
-          // Escaped quote
-          current += '"';
-          i++; // Skip next quote
-        } else {
-          // Toggle quote mode
-          inQuotes = !inQuotes;
-        }
-      } else if (char === ',' && !inQuotes) {
-        result.push(current);
-        current = '';
-      } else {
-        current += char;
-      }
-    }
-    result.push(current);
-    return result;
+    return helpCatalog.parseCSVLine(line);
   }
 
   /**
-   * Escape a CSV field if it contains special characters
+   * Escape a CSV field if it contains special characters.
+   * Thin wrapper — see `core/help-catalog.js` for the implementation and the
+   * M15 rationale (auditoria 2026-07-07) on why this stays manual.
    * @param {string} field - Field value to escape
    * @returns {string} Escaped field
    */
   escapeCSVField(field) {
-    if (field === null || field === undefined) {
-      return '';
-    }
-    const str = String(field);
-    // If field contains comma, quote, or newline, wrap in quotes and escape inner quotes
-    if (str.includes(',') || str.includes('"') || str.includes('\n')) {
-      return `"${str.replaceAll('"', '""')}"`;
-    }
-    return str;
+    return helpCatalog.escapeCSVField(field);
   }
 }