node-power-user 2.2.1 → 2.3.0

package/README.md

@@ -74,23 +74,50 @@ npu global
 ```
 
 ### Install Packages
-Install packages with supply chain protection via [Socket](https://socket.dev/). Every install is wrapped with Socket to detect malicious or compromised packages — including transitive dependencies — before they're added to your project. After install, a full `socket npm audit` runs against your entire dependency tree.
+Install packages with supply chain protection via [Socket Firewall](https://socket.dev/) (`sfw`). Every install is wrapped with sfw, which blocks malicious or compromised packages — including transitive dependencies — before they're downloaded.
 
 ```shell
 npu install
 npu i <package>
-npu i <package> --save-dev
-npu i <package> --save-exact
+npu i <package> --save-dev --legacy-peer-deps
 ```
 
-**If Socket CLI is not installed, `npu install` will refuse to run.** Install it globally to enable protection:
+**Every npm flag passes through verbatim** (`--save-dev`, `--save-exact`, `--legacy-peer-deps`, `--dry-run`, ...) — npu doesn't maintain a whitelist.
+
+**If Socket Firewall is not installed, `npu install` will refuse to run.** Install it globally to enable protection:
+```shell
+npm install -g sfw
+```
+
+Use `--force` (before the command) to bypass Socket protection (not recommended):
+```shell
+npu --force i <package>
+```
+
+### Run Packages (npx)
+Run a package binary with supply chain protection. When the binary would be **downloaded from npm**, the run is wrapped with Socket Firewall. When it's **already installed locally** (`node_modules/.bin/`), it runs directly — nothing is downloaded, so there's nothing to protect and no firewall overhead.
+```shell
+npu npx <command> [args...]
+```
+
+* Output streams **live** in both modes.
+* The child command's exit code is **propagated** (CI-safe).
+* **Everything after the command passes through to the child** — e.g. `npu npx rimraf dist --force` sends `--force` to rimraf.
+* npu's own flags go **before** the `npx` token:
 ```shell
-npm install -g @socketsecurity/cli --save-exact
+npu --force npx <command>   # bypass Socket protection (not recommended)
 ```
 
-Use `--force` to bypass Socket protection (not recommended):
+A run is only reported as **blocked** when Socket Firewall actually blocked a download — an ordinary failure (like a failing test suite) is reported as a plain command failure with its exit code.
+
+Two edge behaviors: `--package`/`-p` runs always stay behind the firewall (they download regardless of local binaries), and bare flag queries (`npx --version`, `npx --help`) pass through silently with no wrapper output at all.
+
+### Wrapped npm (exec / create / init)
+Run any npm command wrapped with Socket Firewall, args untouched. This is what the shell shims use to protect `npm exec|create|init` without rewriting their semantics — `npm create X` maps to package `create-X`, so it must never be turned into `npx X`.
 ```shell
-npu i <package> --force
+npu npm <args...>
+npu npm create vite my-app
+npu --force npm <args...>   # bypass Socket protection (not recommended)
 ```
 
 ### Audit

package/bin/node-power-user

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 const { hideBin } = require('yargs/helpers');
-const argv = require('yargs')(hideBin(process.argv)).parseSync();
+const rawArgs = hideBin(process.argv);
+
+// help(false)/version(false): yargs must not intercept --help/--version —
+// commands like `npu npx <cmd> --help` need those flags to reach the child.
+// boolean('force'): without it, `npu --force npx ...` parses as --force=npx
+// and swallows the command token.
+const argv = require('yargs')(rawArgs).help(false).version(false).boolean('force').parseSync();
+
+// Commands that pass args through to a child (npx) re-parse from raw argv
+argv.raw = rawArgs;
 
 // --cwd / -C: run as if invoked from a different directory
 const targetDir = argv.cwd || argv.C;

package/dist/commands/install.js

@@ -1,32 +1,32 @@
 // Libraries
 const logger = new (require('../lib/logger'))('node-power-user');
 const socket = require('../lib/socket');
+const npxArgs = require('../lib/npx-args');
 const npm = require('../lib/npm');
 
+// Tokens that select the install command (positional + flag aliases)
+const INSTALL_TOKENS = ['install', 'i', '--install', '-i'];
+
 // Module
 module.exports = async function (options) {
-  // Get packages from positional args (everything after "install" / "i")
-  const packages = (options._ || []).slice(1);
-
-  // Build the npm command
-  const flags = [];
-
-  if (options.D || options['save-dev']) {
-    flags.push('--save-dev');
-  }
+  // Parse from RAW argv so every npm flag passes through verbatim
+  // (--save-dev, --legacy-peer-deps, --dry-run, ...). npu's own --force goes
+  // BEFORE the command token: `npu --force i <package>`.
+  const raw = options.raw || [
+    ...(options.force ? ['--force'] : []),
+    'install',
+    ...(options._ || []).slice(1).map(String),
+  ];
+  const { childArgs, force } = npxArgs.parsePassthroughArgs(raw, INSTALL_TOKENS);
 
-  if (options.E || options['save-exact']) {
-    flags.push('--save-exact');
-  }
-
-  if (options.g || options.global) {
-    flags.push('--global');
-  }
+  // Non-flag tokens = the packages being installed (empty = full-tree install)
+  const packages = childArgs.filter((arg) => !arg.startsWith('-'));
+  const isGlobal = childArgs.includes('-g') || childArgs.includes('--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')) {
+  if (packages.length > 0 && !isGlobal) {
     const names = [];
 
     for (const pkg of packages) {
@@ -43,30 +43,30 @@ module.exports = async function (options) {
     npm.removeInstalledCopies(names);
   }
 
-  const command = packages.length > 0
-    ? `npm install ${packages.join(' ')} ${flags.join(' ')}`.trim()
-    : `npm install ${flags.join(' ')}`.trim();
+  const command = `npm install ${childArgs.map(npxArgs.quoteArg).join(' ')}`.trim();
 
   // Check socket status upfront (blocks if not installed unless --force)
-  await socket.check({ force: options.force });
+  await socket.check({ force });
 
   // Log
   logger.log(`Running: ${logger.format.cyan(command)}`);
 
   // Wrap with Socket Firewall
   try {
-    await socket.wrap(command, { force: options.force });
+    await socket.wrap(command, { force });
   } catch (e) {
-    if (e.reason === 'npm-failed') {
+    process.exitCode = e.code || 1;
+
+    if (e.reason === 'sfw-blocked') {
       logger.log('');
-      logger.log('Fix the npm error above (e.g. resolve peer-dep conflicts) and retry.');
+      logger.log('Install blocked. See the output above for details.');
+      logger.log('To retry without firewall protection:');
+      logger.log(logger.format.cyan(`  npu --force i ${childArgs.join(' ')}`.trim()));
       return;
     }
 
     logger.log('');
-    logger.log('Install blocked. See the output above for details.');
-    logger.log('To retry without firewall protection:');
-    logger.log(logger.format.cyan(`  npu i ${packages.join(' ')} ${flags.join(' ')} --force`.trim()));
+    logger.log('Fix the npm error above (e.g. resolve peer-dep conflicts) and retry.');
     return;
   }
 

package/dist/commands/npm.js

@@ -0,0 +1,55 @@
+// Libraries
+const logger = new (require('../lib/logger'))('node-power-user');
+const socket = require('../lib/socket');
+const npxArgs = require('../lib/npx-args');
+
+// Module — `npu npm <args...>`: run ANY npm command wrapped with Socket
+// Firewall, args untouched. Used by the shell shims to protect
+// `npm exec|create|init` without rewriting their semantics (`npm create X`
+// must stay `npm create X` — it maps to package create-X, not X).
+module.exports = async function (options) {
+  // Parse from RAW argv so npm's own flags pass through verbatim; npu's
+  // --force goes BEFORE the npm token: `npu --force npm <args...>`
+  const raw = options.raw || [
+    ...(options.force ? ['--force'] : []),
+    'npm',
+    ...(options._ || []).slice(1).map(String),
+  ];
+  const { childArgs, force } = npxArgs.parsePassthroughArgs(raw, ['npm']);
+
+  if (childArgs.length === 0) {
+    logger.error('Usage: npu [--force] npm <args...>');
+    logger.log(`Example: ${logger.format.cyan('npu npm create vite my-app')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const command = `npm ${childArgs.map(npxArgs.quoteArg).join(' ')}`;
+
+  // Check firewall status upfront (blocks if not installed unless --force)
+  await socket.check({ force });
+
+  // Log
+  logger.log(`Running: ${logger.format.cyan(command)}`);
+
+  // Wrap with Socket Firewall
+  try {
+    await socket.wrap(command, { force });
+  } catch (e) {
+    process.exitCode = e.code || 1;
+    logger.log('');
+
+    if (e.reason === 'sfw-blocked') {
+      logger.log('Command blocked by Socket Firewall. See the output above for details.');
+      logger.log('');
+      logger.log('To retry without firewall protection:');
+      logger.log(logger.format.cyan(`  npu --force ${command}`));
+      return;
+    }
+
+    logger.log(`Command failed (exit ${e.code || 1}). See the error output above.`);
+    return;
+  }
+
+  logger.log(logger.format.green('Done.'));
+};

package/dist/commands/npx.js

@@ -2,6 +2,7 @@
 const logger = new (require('../lib/logger'))('node-power-user');
 const chalk = require('chalk').default;
 const socket = require('../lib/socket');
+const npxArgs = require('../lib/npx-args');
 const jetpack = require('fs-jetpack');
 const path = require('path');
 
@@ -9,58 +10,101 @@ const projectPath = process.cwd();
 
 // Module
 module.exports = async function (options) {
-  // Get everything after "npx" as the command to run
-  const args = (options._ || []).slice(1);
+  // Parse from RAW argv so the child command's flags pass through verbatim
+  // (yargs would otherwise consume them). npu's own flags go BEFORE the npx
+  // token: `npu [--force] npx <command> [args...]` — a trailing --force
+  // belongs to the child (e.g. `npu npx rimraf dist --force`).
+  const raw = options.raw || [
+    ...(options.force ? ['--force'] : []),
+    'npx',
+    ...(options._ || []).slice(1).map(String),
+  ];
+  const { childArgs, force } = npxArgs.parseNpxArgs(raw);
 
-  if (args.length === 0) {
-    logger.error('Usage: npu npx <command> [args...]');
+  if (childArgs.length === 0) {
+    logger.error('Usage: npu [--force] npx <command> [args...]');
     logger.log(`Example: ${logger.format.cyan('npu npx create-react-app my-app')}`);
+    process.exitCode = 1;
     return;
   }
 
-  const command = `npx ${args.join(' ')}`;
-  const binaryName = args[0];
+  const command = npxArgs.buildCommand(childArgs);
+  const binaryName = npxArgs.firstPositional(childArgs);
 
-  // Check firewall status upfront (blocks if not installed unless --force)
-  await socket.check({ force: options.force });
+  // No package named (pure flag queries like `npx --version`) = nothing to
+  // download = nothing to protect — silent plain passthrough, no ceremony.
+  // (--package still downloads even without a positional, so it stays wrapped.)
+  if (!binaryName && !npxArgs.forcesDownload(childArgs)) {
+    try {
+      await socket.wrap(command, { force: true });
+    } catch (e) {
+      process.exitCode = e.code || 1;
+    }
+    return;
+  }
+
+  const localBin = binaryName && path.join(projectPath, 'node_modules', '.bin', binaryName);
+
+  // --package/-p forces npx to download that package even when the named
+  // binary exists locally — those runs must stay behind the firewall
+  const isLocal = !npxArgs.forcesDownload(childArgs)
+    && !!(localBin && jetpack.exists(localBin));
+
+  // Local binaries download nothing, so the firewall has nothing to protect —
+  // run plain (streams live, skips the sfw startup cost)
+  if (isLocal) {
+    logger.log(`'${binaryName}' is installed locally — running it directly (no download to protect).`);
+  } else {
+    // Check firewall status upfront (blocks if not installed unless --force)
+    await socket.check({ force });
+  }
 
   // Log
   logger.log(`Running: ${logger.format.cyan(command)}`);
 
-  // Wrap with Socket Firewall
+  // Wrap with Socket Firewall (plain run for local binaries / --force)
   try {
-    await socket.wrap(command, { force: options.force });
+    await socket.wrap(command, { force: force || isLocal });
   } catch (e) {
-    if (e.reason === 'npm-failed') {
-      logger.log('');
-      logger.log('npx command failed. See the error output above.');
-      return;
-    }
-
+    process.exitCode = e.code || 1;
     logger.log('');
 
-    // Check if the binary exists locally — if not, npx tried to download from npm
-    const localBin = path.join(projectPath, 'node_modules', '.bin', binaryName);
-    if (!jetpack.exists(localBin)) {
+    // A real block — only reachable on the sfw path, i.e. npx tried to
+    // download '<binary>' from npm and Socket Firewall stopped it
+    if (e.reason === 'sfw-blocked') {
       logger.error(`'${binaryName}' was not found in node_modules/.bin/`);
       logger.log(`npx tried to download package '${binaryName}' from npm, which was blocked by Socket Firewall.`);
+      suggestOwnBin(binaryName, childArgs);
 
-      // Check if it's defined in this project's own bin field
-      const pkgJson = jetpack.read(path.join(projectPath, 'package.json'), 'json');
-      if (pkgJson?.bin?.[binaryName]) {
-        logger.log('');
-        logger.log(`'${binaryName}' is defined in this project's ${chalk.cyan('bin')} field but is not installed as a command.`);
-        logger.log(`Run it directly: ${logger.format.cyan(`${pkgJson.bin[binaryName]} ${args.slice(1).join(' ')}`.trim())}`);
-      }
-    } else {
-      logger.log('Command blocked by Socket Firewall. See the output above for details.');
+      logger.log('');
+      logger.log('To retry without firewall protection:');
+      logger.log(logger.format.cyan(`  npu --force ${command}`));
+      return;
+    }
+
+    // The command itself failed — not a firewall matter
+    logger.log(`Command failed (exit ${e.code || 1}). See the error output above.`);
+
+    if (!isLocal) {
+      suggestOwnBin(binaryName, childArgs);
     }
 
-    logger.log('');
-    logger.log('To retry without firewall protection:');
-    logger.log(logger.format.cyan(`  npu npx ${args.join(' ')} --force`));
     return;
   }
 
   logger.log(logger.format.green('Done.'));
 };
+
+// If the binary is defined in this project's own bin field but not installed
+// as a command, point at running it directly
+function suggestOwnBin(binaryName, childArgs) {
+  const pkgJson = jetpack.read(path.join(projectPath, 'package.json'), 'json');
+
+  if (!pkgJson?.bin?.[binaryName]) {
+    return;
+  }
+
+  logger.log('');
+  logger.log(`'${binaryName}' is defined in this project's ${chalk.cyan('bin')} field but is not installed as a command.`);
+  logger.log(`Run it directly: ${logger.format.cyan(`${pkgJson.bin[binaryName]} ${childArgs.slice(1).join(' ')}`.trim())}`);
+}

package/dist/commands/outdated.js

@@ -331,7 +331,7 @@ module.exports = async function (options) {
         jetpack.write(lockfilePath, lockfileBackup);
       }
 
-      if (e.reason === 'npm-failed') {
+      if (e.reason === 'command-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 };
@@ -387,7 +387,7 @@ module.exports = async function (options) {
         jetpack.write(lockfilePath, lockfileBackup);
       }
 
-      if (e.reason === 'npm-failed') {
+      if (e.reason === 'command-failed') {
         logger.log('');
         logger.log('Fix the npm error above and retry.');
         return { allPackages, desynced, synced: false };
@@ -515,7 +515,7 @@ module.exports = async function (options) {
     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.');
 
-    if (e.reason === 'npm-failed') {
+    if (e.reason === 'command-failed') {
       logger.log('');
       logger.log('Fix the npm error above (e.g. resolve peer-dep conflicts) and retry.');
       return { allPackages, desynced, updated: false, target: action };

package/dist/lib/npx-args.js

@@ -0,0 +1,72 @@
+// Pure raw-argv parsing for passthrough commands (`npu npx`, `npu install`,
+// `npu npm`) — the child command's flags must pass through verbatim (yargs
+// would otherwise consume them), so npu's own flags go BEFORE the command
+// token: `npu [--force] npx <command> [args...]`
+
+// Tokens that select the npx command (positional + flag alias)
+const NPX_TOKENS = ['npx', '--npx'];
+
+// Args matching this need no quoting for POSIX sh (commands run with shell: true)
+const SAFE_ARG = /^[A-Za-z0-9_\-./@=:,+]+$/;
+
+// Split raw argv into npu's own flags (before the command token) and the
+// child command's args (everything after, verbatim)
+function parsePassthroughArgs(rawArgs, tokens) {
+  const args = rawArgs || [];
+  const tokenIndex = args.findIndex((arg) => tokens.includes(arg));
+
+  if (tokenIndex === -1) {
+    return { childArgs: [], force: false };
+  }
+
+  return {
+    childArgs: args.slice(tokenIndex + 1),
+    force: args.slice(0, tokenIndex).includes('--force'),
+  };
+}
+
+// npx-flavored parse (the common case)
+function parseNpxArgs(rawArgs) {
+  return parsePassthroughArgs(rawArgs, NPX_TOKENS);
+}
+
+// npx's --package/-p makes it download that package regardless of which
+// binary is named — such runs must never skip the firewall. Scans the whole
+// arg list (a -p meant for the child, e.g. `tsc -p tsconfig.json`, is a
+// false positive — fail-closed: it just runs wrapped instead of fast).
+function forcesDownload(args) {
+  return (args || []).some((arg) => {
+    return arg === '-p'
+      || arg === '--package'
+      || arg.startsWith('--package=');
+  });
+}
+
+// First non-flag token = the binary npx will run (null when only flags)
+function firstPositional(args) {
+  return (args || []).find((arg) => !arg.startsWith('-')) || null;
+}
+
+// Single-quote an arg for the shell when it contains anything unsafe
+function quoteArg(arg) {
+  if (SAFE_ARG.test(arg)) {
+    return arg;
+  }
+
+  return `'${String(arg).replace(/'/g, `'\\''`)}'`;
+}
+
+// Rebuild the npx command string with shell-safe quoting
+function buildCommand(childArgs) {
+  return ['npx', ...childArgs.map(quoteArg)].join(' ');
+}
+
+// Export
+module.exports = {
+  parsePassthroughArgs,
+  parseNpxArgs,
+  forcesDownload,
+  firstPositional,
+  quoteArg,
+  buildCommand,
+};

package/dist/lib/socket.js

@@ -41,42 +41,72 @@ async function check(options) {
   return available;
 }
 
-// Wrap an npm command with sfw if available
+// Markers Socket Firewall prints when it ACTUALLY blocks something (sourced
+// from the sfw-free v1.12.0 report output). sfw passes the wrapped command's
+// exit code through, so a non-zero exit alone does NOT mean a block — a
+// failing test suite exits non-zero too.
+const BLOCK_MARKERS = [
+  /blocked [1-9]\d* packages?:/i,                  // " - blocked 1 package: <purl> - <reason>"
+  /Blocked (?:Packages|Hostnames) \([1-9]\d*\)/i,  // report section headers
+  /SUMMARY: [1-9]\d* item\(s\) blocked/i,          // report summary line
+];
+
+// Check command output for sfw's block report
+function isBlockOutput(output) {
+  return BLOCK_MARKERS.some((marker) => marker.test(output || ''));
+}
+
+// Wrap a command with sfw if available; force (or no sfw) runs it plain.
+// Output always streams live. Throws on non-zero exit with:
+//   err.reason — 'sfw-blocked' (real firewall block) | 'command-failed'
+//   err.code   — the child's exit code
 async function wrap(command, options) {
   options = options || {};
 
-  const available = await isFirewallAvailable();
+  const wrapped = !options.force && await isFirewallAvailable();
+  const finalCommand = wrapped ? `sfw ${command}` : command;
 
-  // If firewall is not installed or --force is used, run plain npm
-  if (!available || options.force) {
-    try {
-      await execute(command, { log: true });
-    } catch (e) {
-      const err = new Error('npm install failed. See the error output above.');
-      err.reason = 'npm-failed';
-      throw err;
-    }
-    return;
-  }
+  let output = '';
+  let exitCode = null;
 
-  // Run with Socket Firewall
-  let output;
-  let exitedWithError = false;
+  const executeOptions = { log: !wrapped, config: {} };
 
-  try {
-    output = await execute(`sfw ${command}`, { log: false });
-  } catch (e) {
-    output = e.message || '';
-    exitedWithError = true;
+  // The wrapped child runs on pipes (not a TTY), which disables color in most
+  // CLIs — restore it, but only when npu itself is printing to a real TTY
+  if (wrapped && process.stdout.isTTY) {
+    executeOptions.config.env = { ...process.env, FORCE_COLOR: '1' };
   }
 
-  if (output) {
-    console.log(output);
-  }
+  try {
+    await execute(finalCommand, executeOptions, (child) => {
+      // Echo piped output through LIVE (and capture it for block detection)
+      // instead of letting it buffer invisibly until the process exits
+      if (child.stdout) {
+        child.stdout.on('data', (chunk) => {
+          output += chunk.toString();
+          process.stdout.write(chunk);
+        });
+      }
+
+      if (child.stderr) {
+        child.stderr.on('data', (chunk) => {
+          output += chunk.toString();
+          process.stderr.write(chunk);
+        });
+      }
+
+      child.on('close', (code) => {
+        exitCode = code;
+      });
+    });
+  } catch (e) {
+    const blocked = wrapped && isBlockOutput(output);
+    const err = blocked
+      ? new Error('Blocked by Socket Firewall — it flagged a risky package.')
+      : new Error(`Command failed with exit code ${exitCode === null ? 1 : exitCode}.`);
 
-  if (exitedWithError) {
-    const err = new Error('Install blocked — Socket Firewall may have flagged a risky package.');
-    err.reason = 'sfw-blocked';
+    err.reason = blocked ? 'sfw-blocked' : 'command-failed';
+    err.code = exitCode === null ? 1 : exitCode;
     throw err;
   }
 }
@@ -90,4 +120,5 @@ module.exports = {
   check,
   wrap,
   audit,
+  isBlockOutput,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-power-user",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Easy tools for every Node.js developer!",
   "main": "dist/index.js",
   "scripts": {