node-power-user 2.1.3 → 2.1.5

package/README.md

@@ -103,9 +103,22 @@ 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
 ```
 
+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. 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.
 ```shell
@@ -137,6 +150,7 @@ npu wait <ms>
 ```
 
 ### Global flags
+  * `-C <dir>`, `--cwd <dir>`: Run as if invoked from `<dir>` (e.g. `npu -C /path/to/project out`)
   * `--debug`: Log the commands and flags before they are executed
 
 ## 🛠️ Development

package/bin/node-power-user

@@ -1,8 +1,22 @@
 #!/usr/bin/env node
 const { hideBin } = require('yargs/helpers');
 const argv = require('yargs')(hideBin(process.argv)).parseSync();
+
+// --cwd / -C: run as if invoked from a different directory
+const targetDir = argv.cwd || argv.C;
+if (targetDir) {
+  process.chdir(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,6 +1,7 @@
 // Libraries
 const logger = new (require('../lib/logger'))('node-power-user');
 const socket = require('../lib/socket');
+const npm = require('../lib/npm');
 
 // Module
 module.exports = async function (options) {
@@ -22,6 +23,26 @@ module.exports = async function (options) {
     flags.push('--global');
   }
 
+  // When installing specific packages with a version/tag (e.g. @latest, @^2.0.0),
+  // 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;
+      const versionIdx = pkg.indexOf('@', searchFrom);
+      if (versionIdx <= 0) {
+        continue;
+      }
+
+      names.push(pkg.substring(0, versionIdx));
+    }
+
+    npm.removeInstalledCopies(names);
+  }
+
   const command = packages.length > 0
     ? `npm install ${packages.join(' ')} ${flags.join(' ')}`.trim()
     : `npm install ${flags.join(' ')}`.trim();

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(',')
@@ -102,49 +109,73 @@ module.exports = async function (options) {
   }
 
   // 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`);
+    }
   }
 
-  // Get counts for menu (only show a tier if it offers upgrades beyond the tier below)
+  // Separate discrepancies into two categories:
+  // - "behind": node_modules has an OLDER version than package.json wants (needs npm install)
+  // - "ahead": node_modules has a NEWER version than package.json specifies (reconcile package.json)
   const discrepancies = [...allPackages.values()].filter(pkg => pkg.hasDiscrepancy);
+  const behindPackages = discrepancies.filter(pkg =>
+    pkg.installedVersion !== '?' && version.is(pkg.installedVersion, '<', pkg.packageVersion)
+  );
+  const aheadPackages = discrepancies.filter(pkg =>
+    pkg.installedVersion !== '?' && version.is(pkg.installedVersion, '>', pkg.packageVersion)
+  );
+  const unknownPackages = discrepancies.filter(pkg => pkg.installedVersion === '?');
+
+  // Get counts for menu (only show a tier if it offers upgrades beyond the tier below)
   const patchCount = Object.keys(patchUpgrades).length;
   const minorCount = Object.keys(minorUpgrades).length;
   const majorCount = Object.keys(latestUpgrades).length;
@@ -161,12 +192,16 @@ module.exports = async function (options) {
 
   // 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';
@@ -180,9 +215,27 @@ module.exports = async function (options) {
   if (!action) {
     const choices = [];
 
-    if (discrepancies.length > 0) {
+    // "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) {
+      choices.push({
+        name: `Sync (${syncCount}) - install packages to match package.json`,
+        value: 'sync',
+      });
+    }
+
+    // "Reconcile" updates package.json where node_modules is ahead
+    if (aheadPackages.length > 0) {
       choices.push({
-        name: `Reconcile (${discrepancies.length}) - sync package.json to installed versions`,
+        name: `Reconcile (${aheadPackages.length}) - sync package.json to installed versions`,
         value: 'reconcile',
       });
     }
@@ -217,15 +270,131 @@ 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, desynced, synced: false };
+      }
+
+      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 {
+      await socket.audit({ force: options.force });
+    } catch (e) {
+      logger.error(`Audit warning: ${e.message}`);
+    }
+
+    logger.log(logger.format.green(`\nSynced ${toSync.length} package(s) to match package.json.`));
+    return { allPackages, desynced, synced: true };
   }
 
-  // Handle reconcile
+  // 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') {
-    // Re-read in case it changed
+    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');
 
-    for (const pkg of discrepancies) {
+    for (const pkg of aheadPackages) {
       const depType = pkg.type === 'dev' ? 'devDependencies'
         : pkg.type === 'peer' ? 'peerDependencies'
         : 'dependencies';
@@ -234,18 +403,28 @@ module.exports = async function (options) {
     }
 
     jetpack.write(packageJsonPath, projectJson);
-    logger.log(logger.format.green(`\nReconciled ${discrepancies.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);
 
-  // Back up package.json before modifying
+  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 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,
@@ -253,27 +432,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 || [];
@@ -328,7 +514,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
@@ -338,9 +530,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.3",
+  "version": "2.1.5",
   "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')()\"",