wizz-method 1.4.0 → 1.5.0

package/tools/installer/core/user-file-preservation.js

@@ -0,0 +1,250 @@
+/**
+ * User file preservation: scan → backup → restore.
+ *
+ * Extracted from `Installer` (installer god-object breakup, A15/A17,
+ * auditoria 2026-07-07, item 3.1). These three functions form one coherent
+ * unit around updates: `detectCustomFiles` scans an existing `_wizz/` for
+ * files the user added or modified since the last install, `backupUserFiles`
+ * copies them out of the way before the update overwrites `_wizz/`, and
+ * `restoreUserFiles` copies them back afterwards. All state that the
+ * original methods read off `this` (the `Manifest` instance for hashing) is
+ * now an explicit parameter — no class, no shared mutable state between
+ * calls.
+ */
+const path = require('node:path');
+const fs = require('../fs-native');
+const prompts = require('../prompts');
+
+/**
+ * Detect custom and modified files.
+ * @param {string} wizzDir - WIZZ installation directory
+ * @param {Array} existingFilesManifest - Previous files from files-manifest.csv
+ * @param {Object} deps - Injected dependencies
+ * @param {Object} deps.manifest - Manifest instance (used for calculateFileHash)
+ * @returns {Object} Object with customFiles and modifiedFiles arrays
+ */
+async function detectCustomFiles(wizzDir, existingFilesManifest, { manifest }) {
+  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 manifest.calculateFileHash(fullPath);
+            if (currentHash && currentHash !== fileInfo.hash) {
+              // Hash changed = file was modified
+              modifiedFiles.push({
+                path: fullPath,
+                relativePath: fileInfo.relativePath,
+              });
+            }
+          }
+        }
+      }
+    } catch (error) {
+      // Best-effort: a permission error mid-scan must not silently decide
+      // what gets preserved on the next update (this scan is what
+      // detects custom/modified files), so warn instead of swallowing it.
+      await prompts.log.warn(`Warning: could not scan ${dir} for custom/modified files: ${error.message}`);
+    }
+  };
+
+  await scanDirectory(wizzDir);
+  return { customFiles, modifiedFiles };
+}
+
+/**
+ * Back up custom and modified files to temp directories before overwriting.
+ * Returns the temp directory paths (or undefined if no files to back up).
+ * @param {Object} paths - InstallPaths instance
+ * @param {string[]} customFiles - Absolute paths of custom (user-added) files
+ * @param {Object[]} modifiedFiles - Array of { path, relativePath } for modified files
+ * @returns {Object} { tempBackupDir, tempModifiedBackupDir } — undefined if no files
+ */
+async function 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 };
+}
+
+/**
+ * Restore custom and modified files that were backed up before the update.
+ * No-op for fresh installs (updateState is null).
+ * @param {Object} paths - InstallPaths instance
+ * @param {Object|null} updateState - From _prepareUpdateState, or null for fresh installs
+ * @returns {Object} { customFiles, modifiedFiles } — lists of restored files
+ */
+async function 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 };
+}
+
+module.exports = { detectCustomFiles, backupUserFiles, restoreUserFiles };

package/tools/installer/modules/channel-resolver.js

@@ -22,6 +22,24 @@ const USER_AGENT = 'wizz-method-installer';
 // Per-process cache: { 'owner/repo' => string[] sorted desc } of pure-semver tags.
 const tagCache = new Map();
 
+// Retry pontual (1 re-tentativa, backoff curto) para chamadas à API do
+// GitHub. Só re-tenta em erro de rede transitório (timeout, ECONNRESET,
+// ENOTFOUND, EAI_AGAIN, 5xx). Erros lógicos (4xx, ex.: 404 de tag inexistente)
+// nunca são re-tentados — propagam direto.
+const FETCH_RETRY_DELAY_MS = 300;
+const TRANSIENT_ERROR_CODES = new Set(['ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT']);
+
+function isTransientError(error) {
+  if (!error) return false;
+  if (typeof error.statusCode === 'number') return error.statusCode >= 500;
+  if (error.code && TRANSIENT_ERROR_CODES.has(error.code)) return true;
+  return /timed out/i.test(error.message || '');
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
  * Parse a GitHub repo URL into { owner, repo }. Returns null if the URL is
  * not a GitHub URL the resolver can handle.
@@ -44,7 +62,7 @@ function parseGitHubRepo(url) {
   return null;
 }
 
-function fetchJson(url, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
+function fetchJsonOnce(url, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
   const headers = {
     'User-Agent': USER_AGENT,
     Accept: 'application/vnd.github+json',
@@ -74,11 +92,25 @@ function fetchJson(url, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
     req.on('error', reject);
     req.on('timeout', () => {
       req.destroy();
-      reject(new Error(`GitHub API request timed out: ${url}`));
+      const err = new Error(`GitHub API request timed out: ${url}`);
+      err.code = 'ETIMEDOUT';
+      reject(err);
     });
   });
 }
 
+// Wrapper com 1 re-tentativa em erro transitório (ver isTransientError acima).
+// Erro não-transitório (404 de tag, JSON malformado etc.) propaga direto.
+async function fetchJson(url, options = {}) {
+  try {
+    return await fetchJsonOnce(url, options);
+  } catch (error) {
+    if (!isTransientError(error)) throw error;
+    await delay(FETCH_RETRY_DELAY_MS);
+    return fetchJsonOnce(url, options);
+  }
+}
+
 /**
  * Strip a leading 'v' and return a valid semver string, or null if the tag
  * is not valid semver or is a prerelease (contains -alpha/-beta/-rc/etc.).

package/tools/installer/modules/cli-config.js

@@ -26,6 +26,7 @@
 
 const { exec } = require('node:child_process');
 const { promisify } = require('node:util');
+const { resolveAreaEntries } = require('./registry-resolve');
 
 const execAsync = promisify(exec);
 
@@ -79,42 +80,33 @@ function matchesPlatform(cli, tag) {
  * `platform:` gate does not match the current OS/arch are dropped too, so a
  * Mac-only tool is never even suggested on Linux/Windows.
  *
+ * Wrapper fino sobre `resolveAreaEntries` (A16): a resolução por área em si
+ * vive em `registry-resolve.js`; aqui só ficam a forma da entrada de CLI e o
+ * filtro de elegibilidade (precisa de `install` + bater o gate de plataforma).
+ *
  * @param {Object} registry - Parsed skills-registry.yaml
  * @param {string[]} [selectedAreas] - Area keys to resolve
  * @param {string} [platformTag] - Current "<platform>-<arch>" (injectable for tests)
- * @returns {Array<{id: string, when: string, check: string, install: string, platform: (string|string[]|undefined), areas: string[]}>}
+ * @returns {Array<{id: string, when: string, check: string, install: string, platform: (string|string[]|undefined), min_version: (string|undefined), verify: (string|undefined), areas: string[]}>}
  */
 function resolveClis(registry, selectedAreas, platformTag = currentPlatformTag()) {
-  const byId = new Map();
-  const areas = (registry && registry.areas) || {};
-  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
-  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
-
-  const add = (cli, areaKey) => {
-    if (!cli || !cli.id || !cli.install) return; // not actionable without an install command
-    if (!matchesPlatform(cli, platformTag)) return; // gated to another OS/arch
-    const existing = byId.get(cli.id);
-    if (existing) {
-      if (areaKey && !existing.areas.includes(areaKey)) existing.areas.push(areaKey);
-      return;
-    }
-    byId.set(cli.id, {
-      id: cli.id,
+  return resolveAreaEntries(registry, selectedAreas, {
+    listKey: 'clis',
+    utilityKey: 'cli_utility',
+    isActionable: (cli) => !!cli.install && matchesPlatform(cli, platformTag),
+    mapEntry: (cli) => ({
       when: cli.when || '',
       check: cli.check || '',
       install: cli.install,
       platform: cli.platform,
-      areas: areaKey ? [areaKey] : [],
-    });
-  };
-
-  for (const area of chosen) {
-    for (const cli of (areas[area] && areas[area].clis) || []) add(cli, area);
-  }
-  // Cross-cutting tools are offered regardless of area selection.
-  for (const cli of (registry && registry.cli_utility) || []) add(cli, null);
-
-  return [...byId.values()];
+      // M27: pin below which `detectClis` reports the entry as needing an
+      // upgrade instead of `installed: true`.
+      min_version: cli.min_version,
+      // M14: post-check/post-install probe for minimal runtime deps (e.g.
+      // clone-and-run tools where `check` only proves the clone exists).
+      verify: cli.verify,
+    }),
+  });
 }
 
 /**
@@ -127,12 +119,58 @@ function renderInstallCommand(cli) {
   return (cli && cli.install) || '';
 }
 
+/**
+ * Extract the first "x.y.z" version number found in a command's output.
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractVersion(text) {
+  const m = String(text || '').match(/\d+\.\d+\.\d+/);
+  return m ? m[0] : null;
+}
+
+/**
+ * Compare two "x.y.z" version strings numerically, segment by segment (no
+ * external semver dependency needed for this simple 3-part comparison).
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative if a<b, 0 if equal, positive if a>b
+ */
+function compareSemver(a, b) {
+  const pa = String(a)
+    .split('.')
+    .map((n) => Number(n) || 0);
+  const pb = String(b)
+    .split('.')
+    .map((n) => Number(n) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
 /**
  * Annotate each CLI with `installed: boolean` by running its `check` command.
  * Immutable: returns new objects, never mutates the input. An entry without a
  * `check` cannot be verified, so it is reported as not installed (we offer it
  * rather than silently assume it is present).
  *
+ * M27 (drift do RTK, 0.30.1 rodando com pin v0.43.0): when the entry declares
+ * `min_version`, a passing `check` is not enough — we also parse the version
+ * out of the check's output and compare it against the pin. Below the pin,
+ * the entry comes back `installed: false` (so the caller's existing "missing
+ * => offer install" path naturally becomes "offer upgrade") plus an
+ * `upgradeMessage` the caller can surface. A version that cannot be parsed
+ * falls back to the old ok-only behavior (nothing to compare against).
+ *
+ * M14 (assimetria MCP vs CLI): when the entry declares `verify` (a check of
+ * minimal runtime deps, e.g. `command -v ffmpeg`, for clone-and-run tools
+ * where `check` only proves "the clone exists"), it also runs AFTER `check`
+ * passes. A failing `verify` means the tool is not genuinely usable, so the
+ * entry is reported `installed: false` with a `verifyWarning` — never an
+ * abort, just a clearer "not really installed yet" signal (CLIs stay opt-in).
+ *
  * @param {Array<Object>} clis - Resolved CLI entries
  * @param {Function} [exec] - Injected runner (command, opts) => {ok,...}
  * @returns {Promise<Array<Object>>} Copies with an added `installed` flag.
@@ -142,7 +180,32 @@ async function detectClis(clis, exec = defaultExec) {
     (clis || []).map(async (cli) => {
       if (!cli.check) return { ...cli, installed: false };
       const res = await exec(cli.check, { timeoutMs: 5000 });
-      return { ...cli, installed: !!res.ok };
+      if (!res.ok) return { ...cli, installed: false };
+
+      if (cli.min_version) {
+        const installedVersion = extractVersion(res.stdout) || extractVersion(res.stderr);
+        if (installedVersion && compareSemver(installedVersion, cli.min_version) < 0) {
+          return {
+            ...cli,
+            installed: false,
+            installedVersion,
+            upgradeMessage: `atualizando ${cli.id} ${installedVersion} → ${cli.min_version}`,
+          };
+        }
+      }
+
+      if (cli.verify) {
+        const verified = await exec(cli.verify, { timeoutMs: 15_000 });
+        if (!verified.ok) {
+          return {
+            ...cli,
+            installed: false,
+            verifyWarning: `${cli.id}: presente, mas a verificação de dependências falhou (${(verified.stderr || 'erro desconhecido').trim()}) — não considerado plenamente instalado`,
+          };
+        }
+      }
+
+      return { ...cli, installed: true };
     }),
   );
 }
@@ -152,24 +215,54 @@ async function detectClis(clis, exec = defaultExec) {
  * a failed install (network, EACCES, missing command) lands in `failed` with
  * its error so the caller can warn and continue the broader install.
  *
+ * M14: when the entry declares `verify`, it runs once the install succeeds
+ * (mirrors mcp-config's post-install VERIFY step). A failing verify does NOT
+ * move the entry to `failed` — the install itself worked (e.g. `git clone`
+ * for a clone-and-run tool) — it only adds a `warnings` entry so the caller
+ * can tell the user their runtime deps (ffmpeg, Ruby, Python...) still need
+ * attention. CLIs are opt-in and fail-open: a warning, never an abort.
+ *
  * @param {Object} args
- * @param {Array<{id: string, install?: string}>} args.clis - Entries to install
+ * @param {Array<{id: string, install?: string, verify?: string}>} args.clis - Entries to install
  * @param {Function} [args.exec] - Injected runner (command, opts) => {ok,...}
- * @returns {Promise<{installed: string[], failed: Array<{id: string, error: string}>}>}
+ * @returns {Promise<{installed: string[], failed: Array<{id: string, error: string}>, warnings: Array<{id: string, warning: string}>}>}
  */
 async function installClis({ clis, exec = defaultExec }) {
   const installed = [];
   const failed = [];
+  const warnings = [];
   for (const cli of clis || []) {
     if (!cli.install) {
       failed.push({ id: cli.id, error: 'sem comando de instalação no registry' });
       continue;
     }
     const res = await exec(cli.install, { timeoutMs: 300_000 });
-    if (res.ok) installed.push(cli.id);
-    else failed.push({ id: cli.id, error: (res.stderr || 'falha desconhecida').trim() });
+    if (!res.ok) {
+      failed.push({ id: cli.id, error: (res.stderr || 'falha desconhecida').trim() });
+      continue;
+    }
+    installed.push(cli.id);
+    if (cli.verify) {
+      const verified = await exec(cli.verify, { timeoutMs: 60_000 });
+      if (!verified.ok) {
+        warnings.push({
+          id: cli.id,
+          warning: `verificação pós-install falhou, dependência mínima pode estar ausente: ${(verified.stderr || 'erro desconhecido').trim()}`,
+        });
+      }
+    }
   }
-  return { installed, failed };
+  return { installed, failed, warnings };
 }
 
-module.exports = { resolveClis, renderInstallCommand, detectClis, installClis, defaultExec, matchesPlatform, currentPlatformTag };
+module.exports = {
+  resolveClis,
+  renderInstallCommand,
+  detectClis,
+  installClis,
+  defaultExec,
+  matchesPlatform,
+  currentPlatformTag,
+  extractVersion,
+  compareSemver,
+};

package/tools/installer/modules/deps-cache.js

@@ -59,7 +59,11 @@ function shapeMcp(mcp) {
  * @param {Object} args
  * @param {string[]} [args.selectedAreas] - Chosen area keys ([] => all areas)
  * @param {{toInstall?: Object[], toRecommend?: Object[], alreadyInstalled?: Object[]}} [args.cliPlan]
- * @param {{toWrite?: Object[], toRecommend?: Object[]}} [args.mcpPlan]
+ * @param {{toWrite?: Object[], toRecommend?: Object[], pinHashes?: Record<string,string>}} [args.mcpPlan]
+ *   `pinHashes` (A13) is `writeMcpConfig`'s `pinHashes` result: id => content
+ *   hash of the server block as it now stands on disk. Persisted here as
+ *   `mcps.pins` so the NEXT install can tell an untouched block (safe to
+ *   auto-update the pin) from a user-customized one (never overwritten).
  * @returns {Object} The manifest to be written.
  */
 function buildDepsCache({ selectedAreas, cliPlan = {}, mcpPlan = {} }) {
@@ -75,6 +79,7 @@ function buildDepsCache({ selectedAreas, cliPlan = {}, mcpPlan = {} }) {
     mcps: {
       written: (mcpPlan.toWrite || []).map(shapeMcp),
       recommended: (mcpPlan.toRecommend || []).map(shapeMcp),
+      pins: mcpPlan.pinHashes && typeof mcpPlan.pinHashes === 'object' ? { ...mcpPlan.pinHashes } : {},
     },
   };
 }
@@ -130,10 +135,32 @@ async function writeDepsCache({ wizzDir, selectedAreas, cliPlan, mcpPlan, trackF
   return { wrote: true, file, counts };
 }
 
+/**
+ * Read the MCP pin hashes recorded by the LAST install (A13), if any. Used
+ * before the next `writeMcpConfig` call so it can tell an untouched block
+ * (safe to auto-update the pin) from a user-customized one. Never throws: a
+ * missing or corrupt cache (or a pre-A13 cache with no `mcps.pins` key) is
+ * simply "no history", which downstream treats the same as "customized" —
+ * the conservative, never-overwrite default.
+ * @param {string} wizzDir - Installed `_wizz` directory
+ * @returns {Promise<Record<string,string>>} Map of mcp id => sha256 hash
+ */
+async function readPreviousMcpPins(wizzDir) {
+  const file = path.join(wizzDir, '_config', CACHE_BASENAME);
+  if (!(await fs.pathExists(file))) return {};
+  try {
+    const cache = JSON.parse(await fs.readFile(file, 'utf8'));
+    return (cache && cache.mcps && cache.mcps.pins && typeof cache.mcps.pins === 'object' && cache.mcps.pins) || {};
+  } catch {
+    return {};
+  }
+}
+
 module.exports = {
   buildDepsCache,
   isEmptyDepsCache,
   writeDepsCache,
+  readPreviousMcpPins,
   shapeCli,
   shapeMcp,
   CACHE_BASENAME,