wizz-method 2.0.0 → 2.1.1

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

@@ -0,0 +1,618 @@
+/**
+ * Lado "install" de OfficialModules — item 20, etapa 3 (auditoria 2026-09-11).
+ *
+ * O que copia/instala módulos em disco: atomicModuleSwap (ACH-03/F01),
+ * install/installFromResolution, copyModuleWithFiltering,
+ * createModuleDirectories e remove. Leitura de catálogo mora em
+ * module-catalog.js; coleta interativa de config mora em config-collector.js.
+ *
+ * Os métodos são montados no prototype de OfficialModules (Object.assign em
+ * official-modules.js) em vez de virarem uma classe separada: o estado
+ * (externalModuleManager, catalog, collectedConfig) é compartilhado na
+ * mesma instância, e os testes fazem monkey-patch em métodos de instância
+ * (ex.: `officialModules.findModuleSource = async () => ...`) — uma classe
+ * dona própria quebra esse contrato.
+ */
+
+const path = require('node:path');
+const fs = require('../fs-native');
+const prompts = require('../prompts');
+const { getSourcePath } = require('../project-root');
+const { loadYamlCached } = require('../core/yaml-cache');
+const { assertModuleInterfaceVersion } = require('./module-interface');
+
+const MODULE_SWAP_SUFFIX_RE = /\.(?:tmp|old)-\d+$/;
+
+/**
+ * Remove any `<module>.tmp-<pid>` / `<module>.old-<pid>` leftovers directly
+ * under `wizzDir` — orphans from an `atomicModuleSwap` that was killed
+ * mid-swap in a previous run. Safe to call before every module swap: once
+ * the directory is clean there is nothing left to remove, and the entries
+ * a swap currently in flight creates are never visible here (this only runs
+ * before that swap starts writing anything).
+ * @param {string} wizzDir
+ */
+async function cleanupStaleModuleSwapEntries(wizzDir) {
+  let entries;
+  try {
+    entries = await fs.readdir(wizzDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (MODULE_SWAP_SUFFIX_RE.test(entry.name)) {
+      await fs.remove(path.join(wizzDir, entry.name)).catch(() => {});
+    }
+  }
+}
+
+/**
+ * Atomic per-module install/update swap. Writes the new module content to a
+ * sibling `<targetPath>.tmp-<pid>` (same filesystem as `targetPath`, so every
+ * rename below is atomic — never `os.tmpdir()`), then promotes it: rename the
+ * existing module (if any) to `<targetPath>.old-<pid>`, rename the tmp copy
+ * onto `targetPath`, and only then remove the `.old`. Mirrors the
+ * `_wizz.tmp-<pid>` + rename scaffold used for fresh installs (A14, see
+ * `InstallPaths`/`Installer.install`), scoped to a single module directory
+ * instead of the whole `_wizz/` tree — this is what closes ACH-03/F01
+ * (remove-then-copy update with no rollback) for updates, which never went
+ * through that scaffold.
+ *
+ * Failure modes:
+ * - copy into tmp throws: tmp is removed, `targetPath` (old or absent) is
+ *   never touched.
+ * - promotion rename (tmp → targetPath) throws after the demotion rename
+ *   (targetPath → old) already succeeded: the old content is renamed back
+ *   onto `targetPath`, so the module ends up exactly as it started.
+ * - anything else (process killed between renames): the next call for any
+ *   module in this `wizzDir` sweeps the orphaned `.tmp-`/`.old-` entries via
+ *   `cleanupStaleModuleSwapEntries` before doing its own swap.
+ *
+ * @param {string} wizzDir - Parent `_wizz/` (or tmp install scaffold) directory.
+ * @param {string} targetPath - Final module directory (`wizzDir/<module>`).
+ * @param {(tmpPath: string, track: (filePath: string) => void) => Promise<void>} copyInto -
+ *   Copies the new module content into `tmpPath`. Must report every file it
+ *   writes through `track(filePath)` instead of the caller's own tracking
+ *   callback — those paths still live under the tmp directory and are
+ *   rewritten onto their final `targetPath`-relative location only after a
+ *   successful swap, so a caller's file list never references a path that
+ *   stops existing once the tmp dir is renamed away.
+ * @param {Function|null} fileTrackingCallback - Caller's real tracking callback.
+ */
+async function atomicModuleSwap(wizzDir, targetPath, copyInto, fileTrackingCallback) {
+  await cleanupStaleModuleSwapEntries(wizzDir);
+
+  const pid = process.pid;
+  const tmpPath = `${targetPath}.tmp-${pid}`;
+  const oldPath = `${targetPath}.old-${pid}`;
+
+  // Same pid reusing a leftover from an earlier crash of this exact process
+  // id is astronomically unlikely, but start clean regardless.
+  await fs.remove(tmpPath).catch(() => {});
+  await fs.remove(oldPath).catch(() => {});
+
+  const trackedTmpPaths = [];
+  const track = fileTrackingCallback ? (filePath) => trackedTmpPaths.push(filePath) : () => {};
+
+  try {
+    await copyInto(tmpPath, track);
+  } catch (error) {
+    await fs.remove(tmpPath).catch(() => {});
+    throw error;
+  }
+
+  const hadExisting = await fs.pathExists(targetPath);
+  if (hadExisting) {
+    await fs.rename(targetPath, oldPath);
+  }
+
+  try {
+    await fs.rename(tmpPath, targetPath);
+  } catch (error) {
+    if (hadExisting) {
+      await fs.rename(oldPath, targetPath).catch(() => {});
+    }
+    await fs.remove(tmpPath).catch(() => {});
+    throw error;
+  }
+
+  if (hadExisting) {
+    await fs.remove(oldPath).catch(() => {});
+  }
+
+  if (fileTrackingCallback) {
+    for (const tmpFilePath of trackedTmpPaths) {
+      fileTrackingCallback(targetPath + tmpFilePath.slice(tmpPath.length));
+    }
+  }
+}
+
+const ModuleInstallerMethods = {
+  /**
+   * Copy a file to the target location
+   * @param {string} sourcePath - Source file path
+   * @param {string} targetPath - Target file path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
+   */
+  async copyFile(sourcePath, targetPath, overwrite = true) {
+    await fs.copy(sourcePath, targetPath, { overwrite });
+  },
+  /**
+   * Install a module
+   * @param {string} moduleName - Code of the module to install (from module.yaml)
+   * @param {string} wizzDir - Target wizz directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Additional installation options
+   * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
+   * @param {Object} options.moduleConfig - Module configuration from config collector
+   * @param {Object} options.logger - Logger instance for output
+   */
+  async install(moduleName, wizzDir, fileTrackingCallback = null, options = {}) {
+    // Aliases (ex.: bauto → bmad-loop) chegam crus via --modules e via
+    // moduleIds de instalações antigas; sem normalizar aqui, o cache de
+    // getPluginResolution, o targetPath e o manifest usariam o código legado.
+    moduleName = await this.externalModuleManager.resolveCanonicalCode(moduleName);
+
+    // Check if this module has a plugin resolution (custom marketplace install)
+    const { CustomModuleManager } = require('./custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const resolved = customMgr.getResolution(moduleName);
+    if (resolved) {
+      return this.installFromResolution(resolved, wizzDir, fileTrackingCallback, options);
+    }
+
+    const sourcePath = await this.findModuleSource(moduleName, {
+      silent: options.silent,
+      channelOptions: options.channelOptions,
+    });
+    const targetPath = path.join(wizzDir, moduleName);
+
+    if (!sourcePath) {
+      throw new Error(
+        `Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.`,
+      );
+    }
+
+    // Contract gate (auditoria 2026-09-11, item 25): a module.yaml declaring
+    // an interface_version this installer doesn't support must never reach
+    // _wizz/ — check before anything below writes a single byte. Missing
+    // module.yaml (null) is handled elsewhere (it's not this gate's job to
+    // require one); a module.yaml that exists but fails to parse aborts the
+    // install with a clear error instead of the generic parser error.
+    let moduleYamlForInterfaceCheck;
+    try {
+      moduleYamlForInterfaceCheck = await loadYamlCached(path.join(sourcePath, 'module.yaml'));
+    } catch (error) {
+      throw new Error(`Invalid module.yaml for '${moduleName}': ${error.message}`);
+    }
+    if (moduleYamlForInterfaceCheck) {
+      assertModuleInterfaceVersion(moduleYamlForInterfaceCheck, moduleName);
+    }
+
+    // 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);
+    let pluginResolution = null;
+    if (marketplaceInfo && marketplaceInfo.marketplacePlugin) {
+      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.`,
+        );
+      }
+    }
+
+    // Atomic swap (ACH-03/F01): write the new content beside the target and
+    // only then promote it — an update killed mid-write never leaves the
+    // module directory missing or half-copied. See `atomicModuleSwap` above.
+    await atomicModuleSwap(
+      wizzDir,
+      targetPath,
+      async (tmpPath, track) => {
+        if (pluginResolution) {
+          await this._copyResolvedSkills(pluginResolution, tmpPath, track, options.moduleConfig);
+        } else {
+          await this.copyModuleWithFiltering(sourcePath, tmpPath, track, options.moduleConfig);
+        }
+      },
+      fileTrackingCallback,
+    );
+
+    if (!options.skipModuleInstaller) {
+      await this.createModuleDirectories(moduleName, wizzDir, { ...options, sourcePath });
+    }
+
+    const { Manifest } = require('../core/manifest');
+    const manifestObj = new Manifest();
+    const versionInfo = await manifestObj.getModuleVersionInfo(moduleName, wizzDir, sourcePath);
+
+    // Pick up channel resolution recorded by the external manager (the only
+    // manager that does pre-clone resolution now that community is retired).
+    const resolution = this.externalModuleManager.getResolution(moduleName);
+
+    await manifestObj.addModule(wizzDir, moduleName, {
+      version: resolution?.version || versionInfo.version,
+      source: versionInfo.source,
+      npmPackage: versionInfo.npmPackage,
+      repoUrl: versionInfo.repoUrl,
+      channel: resolution?.channel,
+      sha: resolution?.sha,
+    });
+
+    return { success: true, module: moduleName, path: targetPath, versionInfo };
+  },
+  /**
+   * 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 _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
+    await fs.ensureDir(targetPath);
+
+    // 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, moduleConfig);
+    }
+
+    // Coloca o module-help.csv na raiz do módulo.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
+    if (resolved.moduleHelpCsvPath) {
+      // Estratégias 1-4: copia o arquivo existente.
+      await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
+      if (fileTrackingCallback) fileTrackingCallback(helpTarget);
+    } else if (resolved.synthesizedHelpCsv) {
+      // 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);
+
+    // Contract gate (auditoria 2026-09-11, item 25) — same check as
+    // `install()` above, but a ResolvedModule never loads the full
+    // module.yaml, only the interfaceVersion PluginResolver carried over.
+    assertModuleInterfaceVersion({ interface_version: resolved.interfaceVersion }, resolved.code);
+
+    // Atomic swap (ACH-03/F01) — see `atomicModuleSwap` above.
+    await atomicModuleSwap(
+      wizzDir,
+      targetPath,
+      (tmpPath, track) => this._copyResolvedSkills(resolved, tmpPath, track, options.moduleConfig),
+      fileTrackingCallback,
+    );
+
+    // Create directories declared in module.yaml (strategies 1-4 may have these)
+    if (!options.skipModuleInstaller) {
+      await this.createModuleDirectories(resolved.code, wizzDir, options);
+    }
+
+    // Update manifest. For custom-source installs we derive channel from the
+    // cloneRef (present → pinned, absent → next; local paths have no channel).
+    const { Manifest } = require('../core/manifest');
+    const manifestObj = new Manifest();
+
+    const hasGitClone = !!resolved.repoUrl;
+    const manifestEntry = {
+      version: resolved.cloneRef || (hasGitClone ? 'main' : resolved.version || null),
+      source: 'custom',
+      npmPackage: null,
+      repoUrl: resolved.repoUrl || null,
+    };
+    if (hasGitClone) {
+      manifestEntry.channel = resolved.cloneRef ? 'pinned' : 'next';
+      if (resolved.cloneSha) manifestEntry.sha = resolved.cloneSha;
+      if (resolved.rawInput) manifestEntry.rawSource = resolved.rawInput;
+    }
+    if (resolved.localPath) manifestEntry.localPath = resolved.localPath;
+    await manifestObj.addModule(wizzDir, resolved.code, manifestEntry);
+
+    return {
+      success: true,
+      module: resolved.code,
+      path: targetPath,
+      // Mirror the manifestEntry.version precedence above so downstream summary
+      // lines show the same string we just wrote to disk (custom git-backed
+      // installs show the cloned ref or 'main').
+      versionInfo: {
+        version: resolved.cloneRef || (hasGitClone ? 'main' : resolved.version || ''),
+      },
+    };
+  },
+  /**
+   * Remove a module
+   * @param {string} moduleName - Name of the module to remove
+   * @param {string} wizzDir - Target wizz directory
+   */
+  async remove(moduleName, wizzDir) {
+    const targetPath = path.join(wizzDir, moduleName);
+
+    if (!(await fs.pathExists(targetPath))) {
+      throw new Error(`Module '${moduleName}' is not installed`);
+    }
+
+    await fs.remove(targetPath);
+
+    return {
+      success: true,
+      module: moduleName,
+    };
+  },
+  /**
+   * Copy module with filtering for localskip agents and conditional content
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} moduleConfig - Module configuration with conditional flags
+   */
+  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
+    // Get all files in source
+    const sourceFiles = await this.getFileList(sourcePath);
+
+    for (const file of sourceFiles) {
+      // Skip sub-modules directory - these are IDE-specific and handled separately
+      if (file.startsWith('sub-modules/')) {
+        continue;
+      }
+
+      // Skip sidecar directories - these contain agent-specific assets not needed at install time
+      const isInSidecarDirectory = path
+        .dirname(file)
+        .split('/')
+        .some((dir) => dir.toLowerCase().endsWith('-sidecar'));
+
+      if (isInSidecarDirectory) {
+        continue;
+      }
+
+      // Skip module.yaml at root - it's only needed at install time
+      if (file === 'module.yaml') {
+        continue;
+      }
+
+      // Skip module root config.yaml only - generated by config collector with actual values
+      // Workflow-level config.yaml (e.g. workflows/orchestrate-story/config.yaml) must be copied
+      // for custom modules that use workflow-specific configuration
+      if (file === 'config.yaml') {
+        continue;
+      }
+
+      const sourceFile = path.join(sourcePath, file);
+      const targetFile = path.join(targetPath, file);
+
+      // Check if this is an agent file
+      if (file.startsWith('agents/') && file.endsWith('.md')) {
+        // Read the file to check for localskip
+        const content = await fs.readFile(sourceFile, 'utf8');
+
+        // Check for localskip="true" in the agent tag
+        const agentMatch = content.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
+        if (agentMatch) {
+          await prompts.log.message(`  Skipping web-only agent: ${path.basename(file)}`);
+          continue; // Skip this agent
+        }
+      }
+
+      // Copy the file with placeholder replacement
+      await this.copyFile(sourceFile, targetFile);
+
+      // Track the file if callback provided
+      if (fileTrackingCallback) {
+        fileTrackingCallback(targetFile);
+      }
+    }
+  },
+  /**
+   * Create directories declared in module.yaml's `directories` key
+   * This replaces the security-risky module installer pattern with declarative config
+   * During updates, if a directory path changed, moves the old directory to the new path
+   * @param {string} moduleName - Name of the module
+   * @param {string} wizzDir - Target wizz directory
+   * @param {Object} options - Installation options
+   * @param {Object} options.moduleConfig - Module configuration from config collector
+   * @param {Object} options.existingModuleConfig - Previous module config (for detecting path changes during updates)
+   * @param {Object} options.coreConfig - Core configuration
+   * @returns {Promise<{createdDirs: string[], movedDirs: string[], createdWdsFolders: string[]}>} Created directories info
+   */
+  async createModuleDirectories(moduleName, wizzDir, options = {}) {
+    const moduleConfig = options.moduleConfig || {};
+    const existingModuleConfig = options.existingModuleConfig || {};
+    const projectRoot = path.dirname(wizzDir);
+    const emptyResult = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
+
+    // Special handling for core module - it's in src/core-skills not src/modules.
+    // OM-04 (auditoria 2026-09-11): install() já resolveu a fonte; aceita via
+    // options.sourcePath para não re-varrer caches externos nem quebrar quando
+    // o teste stuba findModuleSource na instância.
+    let sourcePath = options.sourcePath;
+    if (!sourcePath) {
+      if (moduleName === 'core') {
+        sourcePath = getSourcePath('core-skills');
+      } else {
+        sourcePath = await this.findModuleSource(moduleName, { silent: true });
+        if (!sourcePath) {
+          return emptyResult; // No source found, skip
+        }
+      }
+    }
+
+    // Read module.yaml to find the `directories` key
+    const moduleYamlPath = path.join(sourcePath, 'module.yaml');
+    let moduleYaml;
+    try {
+      moduleYaml = await loadYamlCached(moduleYamlPath);
+    } catch (error) {
+      await prompts.log.warn(`Invalid module.yaml for ${moduleName}: ${error.message}`);
+      return emptyResult;
+    }
+    if (!moduleYaml) {
+      return emptyResult; // No module.yaml, skip
+    }
+
+    if (!moduleYaml.directories) {
+      return emptyResult; // No directories declared, skip
+    }
+
+    const directories = moduleYaml.directories;
+    const wdsFolders = moduleYaml.wds_folders || [];
+    const createdDirs = [];
+    const movedDirs = [];
+    const createdWdsFolders = [];
+
+    for (const dirRef of directories) {
+      // Parse variable reference like "{design_artifacts}"
+      const varMatch = dirRef.match(/^\{([^}]+)\}$/);
+      if (!varMatch) {
+        // Not a variable reference, skip
+        continue;
+      }
+
+      const configKey = varMatch[1];
+      const dirValue = moduleConfig[configKey];
+      if (!dirValue || typeof dirValue !== 'string') {
+        continue; // No value or not a string, skip
+      }
+
+      // Strip {project-root}/ prefix if present
+      let dirPath = dirValue.replace(/^\{project-root\}\/?/, '');
+
+      // Handle remaining {project-root} anywhere in the path
+      dirPath = dirPath.replaceAll('{project-root}', '');
+
+      // Resolve to absolute path
+      const fullPath = path.join(projectRoot, dirPath);
+
+      // Validate path is within project root (prevent directory traversal)
+      const normalizedPath = path.normalize(fullPath);
+      const normalizedRoot = path.normalize(projectRoot);
+      if (!normalizedPath.startsWith(normalizedRoot + path.sep) && normalizedPath !== normalizedRoot) {
+        const color = await prompts.getColor();
+        await prompts.log.warn(color.yellow(`${configKey} path escapes project root, skipping: ${dirPath}`));
+        continue;
+      }
+
+      // Check if directory path changed from previous config (update/modify scenario)
+      const oldDirValue = existingModuleConfig[configKey];
+      let oldFullPath = null;
+      let oldDirPath = null;
+      if (oldDirValue && typeof oldDirValue === 'string') {
+        // F3: Normalize both values before comparing to avoid false negatives
+        // from trailing slashes, separator differences, or prefix format variations
+        let normalizedOld = oldDirValue.replace(/^\{project-root\}\/?/, '');
+        normalizedOld = path.normalize(normalizedOld.replaceAll('{project-root}', ''));
+        const normalizedNew = path.normalize(dirPath);
+
+        if (normalizedOld !== normalizedNew) {
+          oldDirPath = normalizedOld;
+          oldFullPath = path.join(projectRoot, oldDirPath);
+          const normalizedOldAbsolute = path.normalize(oldFullPath);
+          if (!normalizedOldAbsolute.startsWith(normalizedRoot + path.sep) && normalizedOldAbsolute !== normalizedRoot) {
+            oldFullPath = null; // Old path escapes project root, ignore it
+          }
+
+          // F13: Prevent parent/child move (e.g. docs/planning → docs/planning/v2)
+          if (oldFullPath) {
+            const normalizedNewAbsolute = path.normalize(fullPath);
+            if (
+              normalizedOldAbsolute.startsWith(normalizedNewAbsolute + path.sep) ||
+              normalizedNewAbsolute.startsWith(normalizedOldAbsolute + path.sep)
+            ) {
+              const color = await prompts.getColor();
+              await prompts.log.warn(
+                color.yellow(
+                  `${configKey}: cannot move between parent/child paths (${oldDirPath} / ${dirPath}), creating new directory instead`,
+                ),
+              );
+              oldFullPath = null;
+            }
+          }
+        }
+      }
+
+      const dirName = configKey.replaceAll('_', ' ');
+
+      if (oldFullPath && (await fs.pathExists(oldFullPath)) && !(await fs.pathExists(fullPath))) {
+        // Path changed and old dir exists → move old to new location
+        // F1: Use fs.move() instead of fs.rename() for cross-device/volume support
+        // F2: Wrap in try/catch — fallback to creating new dir on failure
+        try {
+          await fs.ensureDir(path.dirname(fullPath));
+          await fs.move(oldFullPath, fullPath);
+          movedDirs.push(`${dirName}: ${oldDirPath} → ${dirPath}`);
+        } catch (moveError) {
+          const color = await prompts.getColor();
+          await prompts.log.warn(
+            color.yellow(
+              `Failed to move ${oldDirPath} → ${dirPath}: ${moveError.message}\n  Creating new directory instead. Please move contents from the old directory manually.`,
+            ),
+          );
+          await fs.ensureDir(fullPath);
+          createdDirs.push(`${dirName}: ${dirPath}`);
+        }
+      } else if (oldFullPath && (await fs.pathExists(oldFullPath)) && (await fs.pathExists(fullPath))) {
+        // F5: Both old and new directories exist — warn user about potential orphaned documents
+        const color = await prompts.getColor();
+        await prompts.log.warn(
+          color.yellow(
+            `${dirName}: path changed but both directories exist:\n  Old: ${oldDirPath}\n  New: ${dirPath}\n  Old directory may contain orphaned documents — please review and merge manually.`,
+          ),
+        );
+      } else if (!(await fs.pathExists(fullPath))) {
+        // New directory doesn't exist yet → create it
+        createdDirs.push(`${dirName}: ${dirPath}`);
+        await fs.ensureDir(fullPath);
+      }
+
+      // Create WDS subfolders if this is the design_artifacts directory
+      if (configKey === 'design_artifacts' && wdsFolders.length > 0) {
+        for (const subfolder of wdsFolders) {
+          const subPath = path.join(fullPath, subfolder);
+          if (!(await fs.pathExists(subPath))) {
+            await fs.ensureDir(subPath);
+            createdWdsFolders.push(subfolder);
+          }
+        }
+      }
+    }
+
+    return { createdDirs, movedDirs, createdWdsFolders };
+  },
+};
+
+module.exports = { ModuleInstallerMethods };