node-power-user 2.1.4 → 2.1.6

package/README.md

@@ -103,12 +103,21 @@ npu audit
 Compare the versions of installed modules to those in your package.json. When you choose to update, the install step and a full post-install audit are both wrapped with Socket for supply chain protection.
 ```shell
 npu outdated
-npu out --force  # bypass Socket protection
+npu out --heal        # skip the menu: reinstall copies that don't match package-lock.json
+npu out --sync        # skip the menu: install packages to match package.json
+npu out -r            # skip the menu: reconcile package.json to installed versions
+npu out -P | -m | -M  # skip the menu: apply patch / minor / major updates
+npu out --force       # bypass Socket protection
 ```
 
-When discrepancies are found between `package.json` and `node_modules`, the menu offers context-aware actions:
+Every run starts with an integrity check: npu compares what `node_modules/.package-lock.json` claims is installed against the packages physically on disk — including transitive deps the table can't show. Desynced copies (stale or partially-extracted installs, typically left behind by an interrupted or Socket-blocked install) make npm silently no-op (`npm install` trusts the lockfile over the disk), so npu warns about them and offers to heal.
+
+When problems are found, the menu offers context-aware actions:
+- **Heal** — when disk copies don't match `package-lock.json`, removes them and reinstalls so reality matches the lockfile again.
 - **Sync** — when `node_modules` is *behind* `package.json`, installs packages to match what `package.json` declares.
-- **Reconcile** — when `node_modules` is *ahead* of `package.json`, updates `package.json` to match installed versions.
+- **Reconcile** — when `node_modules` is *ahead* of `package.json`, updates `package.json` to match installed versions. Strictly ahead-only — it never downgrades `package.json` to match a stale install.
+
+Installs remove the targeted `node_modules` copies first so npm actually re-fetches them (instead of trusting a stale lockfile and reporting "up to date"), then npu verifies the new versions physically landed in `node_modules`. If an install fails or Socket blocks it, both `package.json` and `package-lock.json` are restored — npu never leaves the lockfile advanced past the files on disk.
 
 ### List Packages
 List all packages in your project.

package/bin/node-power-user

@@ -11,5 +11,12 @@ if (targetDir) {
 const cli = new (require('../dist/cli.js'))();
 (async function() {
   'use strict';
-  await cli.process(argv);
+
+  // cli.process logs errors itself — exit non-zero without an unhandled
+  // rejection crash (which dumps noise from libraries with global handlers)
+  try {
+    await cli.process(argv);
+  } catch (e) {
+    process.exitCode = 1;
+  }
 }());

package/dist/commands/install.js

@@ -1,8 +1,7 @@
 // Libraries
 const logger = new (require('../lib/logger'))('node-power-user');
 const socket = require('../lib/socket');
-const jetpack = require('fs-jetpack');
-const path = require('path');
+const npm = require('../lib/npm');
 
 // Module
 module.exports = async function (options) {
@@ -28,6 +27,8 @@ module.exports = async function (options) {
   // remove existing node_modules copies first so npm actually re-fetches them
   // instead of reporting "up to date" with a stale cached version.
   if (packages.length > 0 && !flags.includes('--global')) {
+    const names = [];
+
     for (const pkg of packages) {
       // For scoped packages like @scope/name@version, skip the leading @
       const searchFrom = pkg.startsWith('@') ? 1 : 0;
@@ -36,12 +37,10 @@ module.exports = async function (options) {
         continue;
       }
 
-      const pkgName = pkg.substring(0, versionIdx);
-      const pkgDir = path.join(process.cwd(), 'node_modules', pkgName);
-      if (jetpack.exists(pkgDir)) {
-        jetpack.remove(pkgDir);
-      }
+      names.push(pkg.substring(0, versionIdx));
     }
+
+    npm.removeInstalledCopies(names);
   }
 
   const command = packages.length > 0

package/dist/commands/outdated.js

@@ -8,6 +8,7 @@ const version = require('wonderful-version');
 const inquirer = require('@inquirer/prompts');
 const ncu = require('npm-check-updates');
 const socket = require('../lib/socket');
+const npm = require('../lib/npm');
 const { execute } = require('node-powertools');
 
 // Load package.json
@@ -16,6 +17,7 @@ const projectPath = process.cwd();
 // Module
 module.exports = async function (options) {
   const packageJsonPath = path.join(projectPath, 'package.json');
+  const lockfilePath = path.join(projectPath, 'package-lock.json');
   let projectJson = jetpack.read(packageJsonPath, 'json');
 
   // Check if package.json exists
@@ -34,6 +36,11 @@ module.exports = async function (options) {
   // Log start
   logger.log(`Checking packages for ${logger.format.bold(projectJson.name || 'Unknown Project')}...`);
 
+  // Detect desync between the hidden lockfile and the physical node_modules —
+  // desynced copies make npm silently no-op installs (it trusts the lockfile
+  // over the disk), which is what traps projects in reconcile/update loops
+  const desynced = npm.findDesynced(projectPath);
+
   // Parse --ignore flag (comma-separated list of package names to skip)
   const ignoreList = (options.ignore || '')
     .split(',')
@@ -96,51 +103,64 @@ module.exports = async function (options) {
         latestVersion,
         type: getDependencyType(projectJson, dep),
         hasDiscrepancy,
-        hasMajorUpdate: latestVersion && minorVersion !== latestVersion,
+        hasMajorUpdate: latestVersion && latestVersion.split('.')[0] !== packageVersion.split('.')[0],
       });
     }
   }
 
   // Display unified table
-  if (allPackages.size === 0) {
+  if (allPackages.size === 0 && desynced.length === 0) {
     logger.log(logger.format.green('\nAll packages are up to date!'));
-    return { allPackages };
+    return { allPackages, desynced };
   }
 
-  const dataTable = [['Package', 'package.json', 'Installed', 'Latest', 'Type']];
-
-  for (const pkg of allPackages.values()) {
-    const pkgVersionColor = pkg.hasDiscrepancy ? 'red' : 'green';
-
-    // Format latest version - show major updates in magenta
-    let latestDisplay;
-    if (pkg.latestVersion) {
-      if (pkg.hasMajorUpdate) {
-        latestDisplay = chalk.magenta(pkg.latestVersion + ' ⚠');
-      } else if (pkg.latestVersion !== pkg.installedVersion) {
-        latestDisplay = chalk.cyan(pkg.latestVersion);
+  if (allPackages.size > 0) {
+    const dataTable = [['Package', 'package.json', 'Installed', 'Latest', 'Type']];
+
+    for (const pkg of allPackages.values()) {
+      const pkgVersionColor = pkg.hasDiscrepancy ? 'red' : 'green';
+
+      // Format latest version - show major updates in magenta
+      let latestDisplay;
+      if (pkg.latestVersion) {
+        if (pkg.hasMajorUpdate) {
+          latestDisplay = chalk.magenta(pkg.latestVersion + ' ⚠');
+        } else if (pkg.latestVersion !== pkg.installedVersion) {
+          latestDisplay = chalk.cyan(pkg.latestVersion);
+        } else {
+          latestDisplay = chalk.green(pkg.latestVersion);
+        }
       } else {
-        latestDisplay = chalk.green(pkg.latestVersion);
+        latestDisplay = chalk.dim('-');
       }
-    } else {
-      latestDisplay = chalk.dim('-');
+
+      dataTable.push([
+        pkg.name,
+        chalk[pkgVersionColor](pkg.packageVersion),
+        chalk.green(pkg.installedVersion),
+        latestDisplay,
+        pkg.type,
+      ]);
     }
 
-    dataTable.push([
-      pkg.name,
-      chalk[pkgVersionColor](pkg.packageVersion),
-      chalk.green(pkg.installedVersion),
-      latestDisplay,
-      pkg.type,
-    ]);
-  }
+    console.log(table(dataTable));
 
-  console.log(table(dataTable));
+    // Only show legend if there are major updates
+    const hasMajorUpdates = [...allPackages.values()].some(pkg => pkg.hasMajorUpdate);
+    if (hasMajorUpdates) {
+      logger.log(chalk.dim('Legend: ') + chalk.magenta('⚠ = major version (breaking changes)'));
+    }
+  }
 
-  // Only show legend if there are major updates
-  const hasMajorUpdates = [...allPackages.values()].some(pkg => pkg.hasMajorUpdate);
-  if (hasMajorUpdates) {
-    logger.log(chalk.dim('Legend: ') + chalk.magenta('⚠ = major version (breaking changes)'));
+  // Warn about desynced copies — includes transitive deps the table can't show
+  if (desynced.length > 0) {
+    logger.warn(`${desynced.length} package(s) on disk don't match what package-lock.json claims is installed (stale or partial installs):`);
+    for (const d of desynced.slice(0, 10)) {
+      logger.warn(`  • ${d.loc.replace(/^node_modules\//, '')} — lockfile has ${d.lockfileVersion}, disk has ${d.diskVersion || 'nothing'}`);
+    }
+    if (desynced.length > 10) {
+      logger.warn(`  …and ${desynced.length - 10} more`);
+    }
   }
 
   // Separate discrepancies into two categories:
@@ -166,18 +186,24 @@ module.exports = async function (options) {
   );
 
   // Check if major/latest offers any versions beyond what minor gives
-  const hasMajorBeyondMinor = Object.keys(latestUpgrades).some(dep =>
-    latestUpgrades[dep] !== (minorUpgrades[dep] || allDependencies[dep])
-  );
+  const hasMajorBeyondMinor = Object.keys(latestUpgrades).some(dep => {
+    const latestMajor = version.clean(latestUpgrades[dep]).split('.')[0];
+    const currentMajor = version.clean(allDependencies[dep]).split('.')[0];
+    return latestMajor !== currentMajor;
+  });
 
   // If noPrompt, return data without showing menu (used by tests)
   if (options.noPrompt) {
-    return { allPackages };
+    return { allPackages, desynced };
   }
 
   // Check for shortcut flags (skip menu)
   let action = null;
-  if (options.r || options.reconcile) {
+  if (options.heal) {
+    action = 'heal';
+  } else if (options.sync) {
+    action = 'sync';
+  } else if (options.r || options.reconcile) {
     action = 'reconcile';
   } else if (options.P || options.patch) {
     action = 'patch';
@@ -191,6 +217,14 @@ module.exports = async function (options) {
   if (!action) {
     const choices = [];
 
+    // "Heal" reinstalls copies whose disk state doesn't match the lockfile
+    if (desynced.length > 0) {
+      choices.push({
+        name: `Heal (${desynced.length}) - reinstall copies that don't match package-lock.json`,
+        value: 'heal',
+      });
+    }
+
     // "Sync" installs packages where node_modules is behind package.json
     const syncCount = behindPackages.length + unknownPackages.length;
     if (syncCount > 0) {
@@ -238,24 +272,101 @@ module.exports = async function (options) {
   }
 
   if (action === 'exit') {
-    return { allPackages };
+    return { allPackages, desynced };
+  }
+
+  // Handle heal — reinstall node_modules copies that don't match the hidden
+  // lockfile. Desynced copies make npm silently no-op installs, which traps
+  // projects in reconcile/update loops where nothing ever actually changes.
+  if (action === 'heal') {
+    if (desynced.length === 0) {
+      logger.log(logger.format.green('\nNothing to heal — node_modules matches package-lock.json.'));
+      return { allPackages, desynced, healed: false };
+    }
+
+    const lockfileBackup = jetpack.read(lockfilePath);
+
+    logger.log(logger.format.cyan(`\nRemoving ${desynced.length} desynced copies and reinstalling...`));
+    npm.removeLocations(desynced.map(d => d.loc), projectPath);
+
+    try {
+      await socket.wrap('npm install', { force: options.force });
+    } catch (e) {
+      // Restore the lockfile so the failed run can't advance it further
+      if (lockfileBackup) {
+        jetpack.write(lockfilePath, lockfileBackup);
+      }
+
+      if (e.reason === 'npm-failed') {
+        logger.log('');
+        logger.log('Fix the npm error above and re-run with --heal — the removed copies will reinstall then.');
+        return { allPackages, desynced, healed: false };
+      }
+
+      reportSocketBlock(e, 'npu out --heal --force');
+      return { allPackages, desynced, healed: false };
+    }
+
+    // Confirm disk and lockfile are actually back in sync
+    const remaining = npm.findDesynced(projectPath);
+    if (remaining.length > 0) {
+      logger.error(`\n${remaining.length} package(s) are still desynced after reinstalling:`);
+      remaining.slice(0, 10).forEach(d => logger.error(`  • ${d.loc.replace(/^node_modules\//, '')} — lockfile has ${d.lockfileVersion}, disk has ${d.diskVersion || 'nothing'}`));
+      logger.log(`Try a clean install: ${logger.format.cyan('rm -rf node_modules && npm install')}`);
+      return { allPackages, desynced, healed: false };
+    }
+
+    try {
+      await socket.audit({ force: options.force });
+    } catch (e) {
+      logger.error(`Audit warning: ${e.message}`);
+    }
+
+    logger.log(logger.format.green(`\nHealed ${desynced.length} package(s) — node_modules now matches package-lock.json.`));
+    return { allPackages, desynced, healed: true };
   }
 
   // Handle sync — run npm install for packages where node_modules is behind package.json
   if (action === 'sync') {
     const toSync = [...behindPackages, ...unknownPackages];
+
+    if (toSync.length === 0) {
+      logger.log(logger.format.green('\nNothing to sync — node_modules already matches package.json.'));
+      return { allPackages, desynced, synced: false };
+    }
+
     const installCmd = `npm install ${toSync.map(pkg => `${pkg.name}@${pkg.packageVersion}`).join(' ')}`;
     logger.log(logger.format.cyan(`\nRunning ${installCmd}...`));
 
+    const lockfileBackup = jetpack.read(lockfilePath);
+
+    // Remove stale node_modules copies first so npm actually re-fetches them
+    // instead of trusting the hidden lockfile and reporting "up to date"
+    npm.removeInstalledCopies(toSync.map(pkg => pkg.name), projectPath);
+
     try {
       await socket.wrap(installCmd, { force: options.force });
     } catch (e) {
+      // Restore the lockfile so a blocked/failed install can't leave it
+      // advanced past the physical files (that desync is what mints loops)
+      if (lockfileBackup) {
+        jetpack.write(lockfilePath, lockfileBackup);
+      }
+
       if (e.reason === 'npm-failed') {
         logger.log('');
         logger.log('Fix the npm error above and retry.');
-        return { allPackages, updated: false };
+        return { allPackages, desynced, synced: false };
       }
-      throw e;
+
+      reportSocketBlock(e, 'npu out --sync --force');
+      return { allPackages, desynced, synced: false };
+    }
+
+    // Confirm the installs physically landed in node_modules
+    const expected = Object.fromEntries(toSync.map(pkg => [pkg.name, pkg.packageVersion]));
+    if (reportMismatches(npm.verifyInstalled(expected, projectPath))) {
+      return { allPackages, desynced, synced: false };
     }
 
     try {
@@ -265,15 +376,27 @@ module.exports = async function (options) {
     }
 
     logger.log(logger.format.green(`\nSynced ${toSync.length} package(s) to match package.json.`));
-    return { allPackages, synced: true };
+    return { allPackages, desynced, synced: true };
   }
 
-  // Handle reconcile — update package.json for packages where node_modules is ahead
+  // Handle reconcile — update package.json for packages where node_modules is ahead.
+  // Strictly ahead-only: packages where node_modules is BEHIND are a sync problem,
+  // and downgrading package.json to match them would mask a stale install.
   if (action === 'reconcile') {
+    if (aheadPackages.length === 0) {
+      logger.log('\nNothing to reconcile — no installed packages are ahead of package.json.');
+
+      const syncCount = behindPackages.length + unknownPackages.length;
+      if (syncCount > 0) {
+        logger.log(`${syncCount} package(s) are behind package.json — run ${logger.format.cyan('npu out --sync')} to install them.`);
+      }
+
+      return { allPackages, desynced, reconciled: false };
+    }
+
     projectJson = jetpack.read(packageJsonPath, 'json');
 
-    const toReconcile = aheadPackages.length > 0 ? aheadPackages : discrepancies;
-    for (const pkg of toReconcile) {
+    for (const pkg of aheadPackages) {
       const depType = pkg.type === 'dev' ? 'devDependencies'
         : pkg.type === 'peer' ? 'peerDependencies'
         : 'dependencies';
@@ -282,18 +405,28 @@ module.exports = async function (options) {
     }
 
     jetpack.write(packageJsonPath, projectJson);
-    logger.log(logger.format.green(`\nReconciled ${toReconcile.length} package(s) in package.json.`));
+    logger.log(logger.format.green(`\nReconciled ${aheadPackages.length} package(s) in package.json.`));
 
-    return { allPackages, reconciled: true };
+    return { allPackages, desynced, reconciled: true };
   }
 
   // Handle patch/minor/major updates
   const upgrades = action === 'patch' ? patchUpgrades
     : action === 'minor' ? minorUpgrades
     : latestUpgrades;
+  const packageNames = Object.keys(upgrades);
+
+  if (packageNames.length === 0) {
+    logger.log(logger.format.green(`\nNothing to update — package.json is already at the requested versions.`));
+    return { allPackages, desynced, updated: false, target: action };
+  }
 
-  // Back up package.json before modifying
+  // Back up package.json and package-lock.json before modifying, so a failed
+  // install can restore BOTH — restoring only package.json leaves the lockfile
+  // advanced past the physical files, which is exactly the desync that mints
+  // silent no-op installs
   const packageJsonBackup = jetpack.read(packageJsonPath);
+  const lockfileBackup = jetpack.read(lockfilePath);
 
   await ncu.run({
     packageFile: packageJsonPath,
@@ -301,27 +434,34 @@ module.exports = async function (options) {
     upgrade: true,
   });
 
-  logger.log(logger.format.green(`\nUpdated ${Object.keys(upgrades).length} package(s) in package.json.`));
+  logger.log(logger.format.green(`\nUpdated ${packageNames.length} package(s) in package.json.`));
 
   // Install the specific upgraded packages so npm actually pulls them in
   // (plain `npm install` won't upgrade packages that already satisfy the range)
-  const packageNames = Object.keys(upgrades);
   const installCmd = `npm install ${packageNames.map(name => `${name}@${version.clean(upgrades[name])}`).join(' ')}`;
   logger.log(logger.format.cyan(`\nRunning ${installCmd}...`));
 
+  // Remove stale node_modules copies first so npm actually re-fetches them
+  // instead of trusting the hidden lockfile and reporting "up to date"
+  npm.removeInstalledCopies(packageNames, projectPath);
+
   try {
     await socket.wrap(installCmd, { force: options.force });
   } catch (e) {
-    // Restore package.json since the bulk install failed
+    // Restore both manifests since the bulk install failed
     jetpack.write(packageJsonPath, packageJsonBackup);
-    logger.log('package.json has been restored to its original state.');
+    if (lockfileBackup) {
+      jetpack.write(lockfilePath, lockfileBackup);
+    }
+    logger.log('package.json and package-lock.json have been restored to their original state.');
+    logger.log('The removed package copies will show as missing in the next check until reinstalled.');
 
     // npm itself failed (ERESOLVE, network, peer-dep conflict) — not a Socket block.
     // The npm error was already printed above; just acknowledge and stop.
     if (e.reason === 'npm-failed') {
       logger.log('');
       logger.log('Fix the npm error above (e.g. resolve peer-dep conflicts) and retry.');
-      return { allPackages, updated: false, target: action };
+      return { allPackages, desynced, updated: false, target: action };
     }
 
     const flaggedPackages = e.flaggedPackages || [];
@@ -376,7 +516,13 @@ module.exports = async function (options) {
     logger.log('To bypass Socket for this install only:');
     logger.log(logger.format.cyan(`  SOCKET_CLI_ACCEPT_RISKS=1 npm install ${packageNames.map(name => `${name}@${version.clean(upgrades[name])}`).join(' ')}`));
 
-    return { allPackages, updated: false, target: action };
+    return { allPackages, desynced, updated: false, target: action };
+  }
+
+  // Confirm the installs physically landed in node_modules
+  const expectedUpgrades = Object.fromEntries(packageNames.map(name => [name, version.clean(upgrades[name])]));
+  if (reportMismatches(npm.verifyInstalled(expectedUpgrades, projectPath))) {
+    return { allPackages, desynced, updated: false, target: action };
   }
 
   // Run full audit after install
@@ -386,9 +532,49 @@ module.exports = async function (options) {
     logger.error(`Audit warning: ${e.message}`);
   }
 
-  return { allPackages, updated: true, target: action };
+  return { allPackages, desynced, updated: true, target: action };
 };
 
+// Helper to explain a Socket risk-block after stale copies were already removed.
+// Deliberately does NOT reinstall the removed copies — that would silently
+// bypass the block Socket just raised; removed is safer than stale-and-risky.
+function reportSocketBlock(e, retryCommand) {
+  const flaggedPackages = e.flaggedPackages || [];
+
+  if (flaggedPackages.length > 0) {
+    logger.log('');
+    logger.error('Socket flagged the following dependencies:');
+    flaggedPackages.forEach(pkg => logger.error(`  • ${pkg}`));
+
+    const flaggedNames = flaggedPackages.map(pkg => pkg.replace(/@[^@]+$/, ''));
+    logger.log('');
+    logger.log('If these are fixable CVEs in transitive deps pinned by package-lock.json, re-resolve them with:');
+    logger.log(logger.format.cyan(`  socket npm update ${flaggedNames.join(' ')}`));
+  }
+
+  logger.log('');
+  logger.log('To retry with Socket protection bypassed:');
+  logger.log(logger.format.cyan(`  ${retryCommand}`));
+  logger.log('');
+  logger.log('The risky copies stay removed from node_modules (safer than leaving stale versions) and will show as missing until reinstalled.');
+}
+
+// Helper to report packages that npm claimed to install but didn't physically land.
+// Returns true if there were mismatches (callers should bail).
+function reportMismatches(mismatches) {
+  if (mismatches.length === 0) {
+    return false;
+  }
+
+  logger.error('\nnpm reported success but these packages did not actually update in node_modules:');
+  for (const m of mismatches) {
+    logger.error(`  • ${m.name} — expected ${m.expected}, found ${m.actual}`);
+  }
+  logger.log(`Try a clean install: ${logger.format.cyan('rm -rf node_modules && npm install')}`);
+
+  return true;
+}
+
 // Helper to determine dependency type
 function getDependencyType(packageJson, dep) {
   if (packageJson.devDependencies?.[dep]) {

package/dist/lib/npm.js

@@ -0,0 +1,102 @@
+// Libraries
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const version = require('wonderful-version');
+
+// Remove installed node_modules copies for the given package names so npm
+// actually re-fetches them. npm trusts the hidden lockfile
+// (node_modules/.package-lock.json) over the physical files — if the lockfile
+// already records the requested version, `npm install pkg@version` reports
+// "up to date" without installing anything, even when the physical copy is
+// stale. Deleting the copy forces npm to reify it from the registry/cache.
+function removeInstalledCopies(names, cwd) {
+  const base = cwd || process.cwd();
+
+  for (const name of names) {
+    const pkgDir = path.join(base, 'node_modules', name);
+
+    if (jetpack.exists(pkgDir)) {
+      jetpack.remove(pkgDir);
+    }
+  }
+}
+
+// Remove node_modules entries by their lockfile location (e.g.
+// "node_modules/mocha/node_modules/brace-expansion") — unlike
+// removeInstalledCopies, this handles nested copies.
+function removeLocations(locations, cwd) {
+  const base = cwd || process.cwd();
+
+  for (const location of locations) {
+    jetpack.remove(path.join(base, location));
+  }
+}
+
+// Find packages where the physical node_modules copy doesn't match what the
+// hidden lockfile (node_modules/.package-lock.json) claims is installed.
+// This desync is what makes npm silently no-op installs: npm trusts the hidden
+// lockfile over the physical files, so a stale or partially-extracted copy is
+// never repaired by `npm install`. Created by interrupted or Socket-blocked
+// installs that advance the lockfiles without extracting files.
+// Returns [{ loc, lockfileVersion, diskVersion }] — diskVersion null = missing.
+function findDesynced(cwd) {
+  const base = cwd || process.cwd();
+  const hidden = jetpack.read(path.join(base, 'node_modules', '.package-lock.json'), 'json');
+
+  if (!hidden) {
+    return [];
+  }
+
+  const desynced = [];
+
+  for (const [loc, info] of Object.entries(hidden.packages || {})) {
+    if (!loc.startsWith('node_modules/') || !info.version || info.link) {
+      continue;
+    }
+
+    const pkgJson = jetpack.read(path.join(base, loc, 'package.json'), 'json');
+    const diskVersion = pkgJson?.version || null;
+
+    if (!diskVersion) {
+      // Missing optional packages are normal (platform-specific binaries
+      // like @esbuild/* and fsevents are skipped on non-matching systems)
+      if (info.optional) {
+        continue;
+      }
+
+      desynced.push({ loc, lockfileVersion: info.version, diskVersion: null });
+    } else if (diskVersion !== info.version) {
+      desynced.push({ loc, lockfileVersion: info.version, diskVersion });
+    }
+  }
+
+  return desynced;
+}
+
+// Verify that the physical node_modules copies match the expected versions.
+// expected is a map of { name: version }. Returns an array of mismatches:
+// [{ name, expected, actual }] — empty when everything landed correctly.
+function verifyInstalled(expected, cwd) {
+  const base = cwd || process.cwd();
+  const mismatches = [];
+
+  for (const [name, expectedVersion] of Object.entries(expected)) {
+    const cleanExpected = version.clean(expectedVersion);
+    const pkgJson = jetpack.read(path.join(base, 'node_modules', name, 'package.json'), 'json');
+    const actual = pkgJson?.version ? version.clean(pkgJson.version) : null;
+
+    if (!actual || !version.is(actual, '==', cleanExpected)) {
+      mismatches.push({ name, expected: cleanExpected, actual: actual || 'missing' });
+    }
+  }
+
+  return mismatches;
+}
+
+// Export
+module.exports = {
+  removeInstalledCopies,
+  removeLocations,
+  findDesynced,
+  verifyInstalled,
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "node-power-user",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "description": "Easy tools for every Node.js developer!",
   "main": "dist/index.js",
   "scripts": {
-    "test": "npm run prepare && ./node_modules/mocha/bin/mocha test/ --recursive --timeout=10000",
+    "test": "npm run prepare && mocha test/ --recursive --timeout=10000",
     "start": "npm run prepare && ./bin/node-power-user",
     "help": "echo 'npm start -- -v'",
     "prepare": "node -e \"require('prepare-package')()\"",