np-audit 1.3.0 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Kobler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
+![np-audit](docs/title-image.png)
+
+[![npm version](https://img.shields.io/npm/v/np-audit.svg)](https://www.npmjs.com/package/np-audit)
+[![npm downloads](https://img.shields.io/npm/dm/np-audit.svg)](https://www.npmjs.com/package/np-audit)
+[![GitHub license](https://img.shields.io/github/license/KoblerS/np-audit.svg)](https://github.com/KoblerS/np-audit/blob/main/LICENSE)
+[![CI](https://github.com/KoblerS/np-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/KoblerS/np-audit/actions/workflows/ci.yml)
+
 # np-audit — npm package auditor
 
 Statically detect obfuscated code in npm `preinstall`/`postinstall` scripts **before** they run. Drop-in replacement for `npm install` and `npm ci`.
@@ -53,13 +60,16 @@ Real-world examples include:
 
 ## Install
 
+**Global install (recommended):**
+
 ```bash
-# Global install (recommended for daily use)
 npm install -g np-audit
+```
 
-# Or use directly with npx (no install needed)
+**Or use directly with npx:**
+
+```bash
 npx np-audit scan
-npx np-audit install
 ```
 
 After global install, use the `npa` command:
@@ -76,11 +86,16 @@ npa --version
 
 | Command | Alias | Description |
 |---|---|---|
-| `npa install [package]` | `npa i [package]` | Audit then run `npm install` |
+| `npa install [package]` | `npa i` | Audit then run `npm install` |
 | `npa ci` | — | Audit then run `npm ci` |
 | `npa scan` | `npa s` | Scan only, no install |
 | `npa config get` | `npa c get` | Show current configuration |
-| `npa config set <key> <value>` | `npa c set <key> <value>` | Update a config value |
+| `npa config set <key> <value>` | `npa c set` | Update a config value |
+| `npa alias` | — | Print shell hook for auto-scanning |
+| `npa alias --install` | — | Install hook to shell profile |
+| `npa alias --uninstall` | — | Remove hook from shell profile |
+
+Use `npa <command> -h` for detailed help on any command.
 
 ### Flags
 
@@ -159,6 +174,42 @@ npa config set skipScopes '["@types","@babel"]'
 
 Config is stored in `~/.npmauditor.json` (global) and can be overridden per project with `.npmauditor.json` in your project root.
 
+### Shell Hook (npm alias)
+
+Automatically run `npa scan` before every `npm install` or `npm ci`:
+
+```bash
+# Install the hook to your shell profile (~/.zshrc or ~/.bashrc)
+npa alias --install
+
+# Reload your shell
+source ~/.zshrc  # or ~/.bashrc
+```
+
+Now when you run `npm install` or `npm ci`, npa will scan first:
+
+```bash
+$ npm install lodash
+[npa] Scanning dependencies before npm install...
+✔ No packages with install scripts found.
+[npa] Scan passed. Running npm install...
+```
+
+If issues are found, the install is blocked:
+
+```bash
+$ npm install evil-pkg
+[npa] Scanning dependencies before npm install...
+✗ evil-pkg@1.0.0 BLOCK (score: 9)
+[npa] Scan found issues. Run 'npa install --aware' for interactive mode.
+```
+
+To remove the hook:
+
+```bash
+npa alias --uninstall
+```
+
 #### All config keys
 
 | Key | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "np-audit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Static obfuscation detector for npm lifecycle scripts — supply chain attack prevention",
   "bin": {
     "npa": "bin/npa.js",

package/src/cli.js

@@ -1,31 +1,33 @@
 'use strict';
 
-const { scan }      = require('./scanner');
-const { runAware, runNpm } = require('./aware');
-const { loadConfig, setGlobalConfig, getGlobalConfigPath, DEFAULT_CONFIG } = require('./config');
-const output        = require('./output');
+const { loadConfig, DEFAULT_CONFIG } = require('./utils/config');
+const commands = require('./commands');
+const output = require('./utils/output');
 
 const VERSION = require('../package.json').version;
 const NAME    = require('../package.json').name;
 
-const HELP = `
+function buildMainHelp() {
+  const cmdList = commands.list();
+  const lines = cmdList.map(cmd => {
+    const aliases = cmd.aliases.length ? ` (alias: ${cmd.aliases.join(', ')})` : '';
+    return `    npa ${cmd.name.padEnd(20)} ${cmd.description}${aliases}`;
+  });
+
+  return `
   npa — npm package auditor ${VERSION}
   Statically detects obfuscated code in npm install scripts.
 
   Usage:
-    npa install [package]    Audit then run npm install  (alias: i)
-    npa ci                   Audit then run npm ci
-    npa scan                 Scan only, no npm invocation (alias: s)
-    npa config get           Show current configuration   (alias: c)
-    npa config set <k> <v>   Set a config value
+${lines.join('\n')}
 
   Flags:
-    --aware, -a   Interactive mode: choose which scripts to allow
+    --review, -r   Interactive mode: choose which scripts to allow
     --json        Machine-readable JSON output
     --no-dev      Skip devDependencies
     --verbose     Show extra detail
     --version     Print version
-    --help, -h    Print this help
+    --help, -h    Print this help (use <command> -h for command help)
 
   Config keys (stored in ~/.npmauditor.json):
     blockScore       Score threshold for hard block (default: ${DEFAULT_CONFIG.blockScore})
@@ -36,11 +38,12 @@ const HELP = `
     skipScopes       Array of @scopes to skip
     skipPackages     Array of package names to skip
 `;
+}
 
 function parseArgs(argv) {
   const args  = argv.slice(2);
   const flags = {
-    aware:   false,
+    review:  false,
     json:    false,
     noDev:   false,
     verbose: false,
@@ -48,11 +51,12 @@ function parseArgs(argv) {
     help:    false,
   };
   const positionals = [];
+  const rawArgs = [];
 
   for (const arg of args) {
     switch (arg) {
-      case '--aware':
-      case '-a':         flags.aware   = true; break;
+      case '--review':
+      case '-r':         flags.review  = true; break;
       case '--json':     flags.json    = true; break;
       case '--no-dev':   flags.noDev   = true; break;
       case '--verbose':  flags.verbose = true; break;
@@ -67,164 +71,16 @@ function parseArgs(argv) {
 
   const command = positionals[0] || null;
   const cmdArgs = positionals.slice(1);
-  return { command, cmdArgs, flags };
-}
-
-async function runInstall(pkgName, flags, config, cwd) {
-  output.printScanHeader();
-
-  const results = await scan({
-    cwd,
-    config,
-    noDev:         flags.noDev,
-    verbose:       flags.verbose,
-    singlePackage: pkgName || null,
-  });
-
-  if (flags.json) {
-    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
-  } else {
-    printResults(results);
-  }
-
-  const blocked = results.filter(r => r.verdict === 'BLOCK');
-
-  if (blocked.length > 0 && !flags.aware) {
-    output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
-    output.log(output.dim('  Run with --aware to interactively decide which scripts to allow.'));
-    process.exit(1);
-  }
-
-  const npmArgs = pkgName ? [pkgName] : [];
-
-  if (flags.aware) {
-    const packagesWithScripts = results.filter(r => r.verdict !== 'OK' || r.scripts.length > 0);
-    const exit = await runAware({
-      results: packagesWithScripts.length > 0 ? packagesWithScripts : results,
-      command: 'install',
-      npmArgs,
-      cwd,
-    });
-    process.exit(exit);
-  } else {
-    const exit = runNpm('install', npmArgs, cwd);
-    process.exit(exit);
+  const commandIndex = args.indexOf(command);
+  if (commandIndex !== -1) {
+    rawArgs.push(...args.slice(commandIndex + 1));
   }
-}
-
-async function runCi(flags, config, cwd) {
-  output.printScanHeader();
-
-  const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
-
-  if (flags.json) {
-    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
-  } else {
-    printResults(results);
-  }
-
-  const blocked = results.filter(r => r.verdict === 'BLOCK');
-
-  if (blocked.length > 0 && !flags.aware) {
-    output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
-    process.exit(1);
-  }
-
-  if (flags.aware) {
-    const exit = await runAware({ results, command: 'ci', npmArgs: [], cwd });
-    process.exit(exit);
-  } else {
-    const exit = runNpm('ci', [], cwd);
-    process.exit(exit);
-  }
-}
-
-async function runScan(flags, config, cwd) {
-  output.printScanHeader();
-
-  const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
-
-  if (flags.json) {
-    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
-    const hasBlock = results.some(r => r.verdict === 'BLOCK');
-    process.exit(hasBlock ? 1 : 0);
-  }
-
-  printResults(results);
-  output.printSummary(results.map(r => ({ verdict: r.verdict })));
-
-  const hasBlock = results.some(r => r.verdict === 'BLOCK');
-  process.exit(hasBlock ? 1 : 0);
-}
-
-async function runConfig(cmdArgs, config) {
-  const subcommand = cmdArgs[0];
-
-  if (subcommand === 'get') {
-    const globalPath = getGlobalConfigPath();
-    output.log(output.bold('  Current npa configuration'));
-    output.log(output.dim(`  (global: ${globalPath})`));
-    output.log('');
-    for (const [key, val] of Object.entries(config)) {
-      output.log(`  ${output.cyan(key.padEnd(18))} ${JSON.stringify(val)}`);
-    }
-    output.log('');
-    return;
-  }
-
-  if (subcommand === 'set') {
-    const key   = cmdArgs[1];
-    const value = cmdArgs[2];
-    if (!key || value === undefined) {
-      output.error('Usage: npa config set <key> <value>');
-      process.exit(1);
-    }
-    try {
-      const updated = setGlobalConfig(key, value);
-      output.success(`Set ${key} = ${JSON.stringify(updated[key])}`);
-      output.log(output.dim(`  Written to ${getGlobalConfigPath()}`));
-    } catch (err) {
-      output.error(err.message);
-      process.exit(1);
-    }
-    return;
-  }
-
-  output.error(`Unknown config subcommand: "${subcommand}". Use "get" or "set".`);
-  process.exit(1);
-}
-
-function printResults(results) {
-  if (results.length === 0) {
-    output.success('No packages with install scripts found.');
-    return;
-  }
-  for (const r of results) {
-    output.printPackageResult(r.pkg, r);
-  }
-}
-
-function toJsonReport(results) {
-  return {
-    summary: {
-      total:   results.length,
-      blocked: results.filter(r => r.verdict === 'BLOCK').length,
-      warned:  results.filter(r => r.verdict === 'WARN').length,
-      ok:      results.filter(r => r.verdict === 'OK').length,
-    },
-    packages: results.map(r => ({
-      name:     r.pkg.name,
-      version:  r.pkg.version,
-      verdict:  r.verdict,
-      score:    r.score,
-      findings: r.findings,
-      scripts:  r.scripts.map(s => ({ lifecycle: s.lifecycle, file: s.file, score: s.score })),
-    })),
-  };
+  return { command, args: cmdArgs, rawArgs, flags };
 }
 
 async function main() {
-  const { command, cmdArgs, flags } = parseArgs(process.argv);
+  const parsed = parseArgs(process.argv);
+  const { command, args, rawArgs, flags } = parsed;
   const cwd    = process.cwd();
   const config = loadConfig(cwd);
 
@@ -233,23 +89,26 @@ async function main() {
     return;
   }
 
+  if (flags.help && command) {
+    const cmd = commands.get(command);
+    if (cmd) {
+      process.stdout.write(cmd.help() + '\n');
+      return;
+    }
+  }
+
   if (flags.help || !command) {
-    process.stdout.write(HELP + '\n');
+    process.stdout.write(buildMainHelp() + '\n');
     return;
   }
 
-  switch (command) {
-    case 'install':
-    case 'i':        await runInstall(cmdArgs[0] || null, flags, config, cwd); break;
-    case 'ci':       await runCi(flags, config, cwd); break;
-    case 'scan':
-    case 's':        await runScan(flags, config, cwd); break;
-    case 'config':
-    case 'c':        await runConfig(cmdArgs, config); break;
-    default:
-      output.error(`Unknown command: "${command}". Run npa --help for usage.`);
-      process.exit(1);
+  const cmd = commands.get(command);
+  if (!cmd) {
+    output.error(`Unknown command: "${command}". Run npa --help for usage.`);
+    process.exit(1);
   }
+
+  await cmd.run({ args, rawArgs, flags, config, cwd });
 }
 
 main().catch(err => {

package/src/commands/alias.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const output = require('../utils/output');
+
+const BASH_HOOK = `# npa npm hook
+npm() { [[ -n "$NPA_RUNNING" ]] && { command npm "$@"; return; }; case "$1" in scan) npa scan "\${@:2}"; return;; install|i|add) command -v npa >/dev/null && { local pkgs=(); for a in "\${@:2}"; do [[ "$a" != -* ]] && pkgs+=("$a"); done; if [[ \${#pkgs[@]} -gt 0 ]]; then npa scan "\${pkgs[@]}" || { echo "[npa] Blocked. Use 'npa install --review'"; return 1; }; else npa scan || { echo "[npa] Blocked. Use 'npa install --review'"; return 1; }; fi; };; ci) command -v npa >/dev/null && { npa scan || { echo "[npa] Blocked. Use 'npa ci --review'"; return 1; }; };; esac; command npm "$@"; }`;
+
+const POWERSHELL_HOOK = `# npa npm hook
+function npm { if($env:NPA_RUNNING){& npm.cmd @args;return}; if($args[0] -eq 'scan'){& npa scan @($args|Select-Object -Skip 1);return}; if($args[0] -in @('install','i','add')){$pkgs=@($args|Where-Object{$_ -notmatch '^-'}|Select-Object -Skip 1); if($pkgs.Count -gt 0){& npa scan @pkgs; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}else{& npa scan; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}}; if($args[0] -eq 'ci'){& npa scan; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}; & npm.cmd @args }`;
+
+module.exports = {
+  name: 'alias',
+  aliases: [],
+  description: 'Shell hook to auto-scan before npm install/ci',
+
+  help() {
+    return `
+  npa alias — Shell hook to auto-scan before npm install/ci
+
+  Usage:
+    npa alias                Print the shell hook
+    npa alias --install      Add hook to shell profile (~/.zshrc or ~/.bashrc)
+    npa alias --uninstall    Remove hook from shell profile
+
+  The hook intercepts npm install/ci/add commands and runs npa scan first.
+  If issues are found, the install is blocked until resolved.
+
+  Examples:
+    npa alias                     Print hook for manual installation
+    npa alias --install           Auto-install to detected shell
+    eval "$(npa alias)"           Load hook in current session only
+`;
+  },
+
+  run({ rawArgs }) {
+    const install = rawArgs.includes('--install') || rawArgs.includes('-i');
+    const uninstall = rawArgs.includes('--uninstall') || rawArgs.includes('-u');
+
+    const { shell, hook, profilePath } = detectShell();
+
+    if (uninstall) {
+      return doUninstall(profilePath);
+    }
+
+    if (install) {
+      return doInstall(hook, profilePath);
+    }
+
+    // Print hook
+    process.stdout.write(hook + '\n');
+    output.log('');
+    output.log(output.dim(`  Add to your shell profile, or run: npa alias --install`));
+  },
+};
+
+function detectShell() {
+  if (process.platform === 'win32') {
+    return { shell: 'powershell', hook: POWERSHELL_HOOK, profilePath: null };
+  }
+
+  const userShell = process.env.SHELL || '';
+  if (userShell.includes('zsh')) {
+    return { shell: 'zsh', hook: BASH_HOOK, profilePath: path.join(os.homedir(), '.zshrc') };
+  }
+
+  return { shell: 'bash', hook: BASH_HOOK, profilePath: path.join(os.homedir(), '.bashrc') };
+}
+
+function doUninstall(profilePath) {
+  if (!profilePath) {
+    output.error('Auto-uninstall not supported for PowerShell. Remove manually from $PROFILE');
+    return;
+  }
+
+  if (!fs.existsSync(profilePath)) {
+    output.warn('No profile found at ' + profilePath);
+    return;
+  }
+
+  const content = fs.readFileSync(profilePath, 'utf8');
+  if (!content.includes('# npa npm hook')) {
+    output.warn('npa hook not found in ' + profilePath);
+    return;
+  }
+
+  const cleaned = content.replace(/\n*# npa npm hook\nnpm\(\)[^\n]+\n*/g, '\n');
+  fs.writeFileSync(profilePath, cleaned);
+  output.success(`Removed npa hook from ${profilePath}`);
+  output.log(output.dim('  Run: source ' + profilePath + ' (or restart your terminal)'));
+}
+
+function doInstall(hook, profilePath) {
+  if (!profilePath) {
+    output.error('Auto-install not supported for PowerShell. Copy the output manually to $PROFILE');
+    process.stdout.write('\n' + hook + '\n');
+    return;
+  }
+
+  const content = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+  if (content.includes('# npa npm hook')) {
+    output.warn('npa hook already installed in ' + profilePath);
+    return;
+  }
+
+  fs.appendFileSync(profilePath, '\n\n' + hook + '\n');
+  output.success(`Installed npa hook to ${profilePath}`);
+  output.log(output.dim('  Run: source ' + profilePath + ' (or restart your terminal)'));
+}

package/src/commands/ci.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { scan } = require('../core/scanner');
+const { runAware, runNpm } = require('../utils/review');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'ci',
+  aliases: [],
+  description: 'Audit then run npm ci',
+
+  help() {
+    return `
+  npa ci — Audit dependencies then run npm ci
+
+  Usage:
+    npa ci [options]
+
+  Options:
+    --review, -r   Interactive mode: review and allow/deny scripts
+    --json        Output scan results as JSON
+    --no-dev      Skip devDependencies in scan
+    --verbose     Show detailed findings
+    -h, --help    Show this help
+
+  Examples:
+    npa ci            Clean install after audit
+    npa ci --review    Review scripts interactively
+`;
+  },
+
+  async run({ flags, config, cwd }) {
+    const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
+    const hasIssues = results.some(r => r.verdict !== 'OK');
+    const silent = config.silent && !hasIssues;
+
+    output.printScanHeader(silent);
+
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+    } else {
+      printResults(results, silent);
+    }
+
+    const blocked = results.filter(r => r.verdict === 'BLOCK');
+
+    if (blocked.length > 0 && !flags.review) {
+      output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
+      process.exit(1);
+    }
+
+    if (flags.review) {
+      const exit = await runAware({ results, command: 'ci', npmArgs: [], cwd });
+      process.exit(exit);
+    } else {
+      const exit = runNpm('ci', [], cwd);
+      process.exit(exit);
+    }
+  },
+};
+
+function printResults(results, silent = false) {
+  if (silent) return;
+  if (results.length === 0) {
+    output.success('No packages with install scripts found.');
+    return;
+  }
+  for (const r of results) {
+    output.printPackageResult(r.pkg, r);
+  }
+}
+
+function toJsonReport(results) {
+  return {
+    summary: {
+      total:   results.length,
+      blocked: results.filter(r => r.verdict === 'BLOCK').length,
+      warned:  results.filter(r => r.verdict === 'WARN').length,
+      ok:      results.filter(r => r.verdict === 'OK').length,
+    },
+    packages: results.map(r => ({
+      name:     r.pkg.name,
+      version:  r.pkg.version,
+      verdict:  r.verdict,
+      score:    r.score,
+      findings: r.findings,
+      scripts:  r.scripts.map(s => ({ lifecycle: s.lifecycle, file: s.file, score: s.score })),
+    })),
+  };
+}

package/src/commands/config.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { setGlobalConfig, getGlobalConfigPath, DEFAULT_CONFIG } = require('../utils/config');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'config',
+  aliases: ['c'],
+  description: 'View or modify npa configuration',
+
+  help() {
+    return `
+  npa config — View or modify npa configuration
+
+  Usage:
+    npa config get              Show all config values
+    npa config set <key> <val>  Set a config value
+
+  Config keys:
+    blockScore       Score threshold for hard block (default: ${DEFAULT_CONFIG.blockScore})
+    warnScore        Score threshold for warning (default: ${DEFAULT_CONFIG.warnScore})
+    registry         npm registry URL
+    timeout          HTTP timeout in ms (default: ${DEFAULT_CONFIG.timeout})
+    parallelFetches  Concurrent downloads (default: ${DEFAULT_CONFIG.parallelFetches})
+    skipScopes       Array of @scopes to skip (JSON)
+    skipPackages     Array of package names to skip (JSON)
+
+  Examples:
+    npa config get
+    npa config set blockScore 10
+    npa config set skipScopes '["@myorg"]'
+`;
+  },
+
+  async run({ args, config }) {
+    const subcommand = args[0];
+
+    if (subcommand === 'get') {
+      const globalPath = getGlobalConfigPath();
+      output.log(output.bold('  Current npa configuration'));
+      output.log(output.dim(`  (global: ${globalPath})`));
+      output.log('');
+      for (const [key, val] of Object.entries(config)) {
+        output.log(`  ${output.cyan(key.padEnd(18))} ${JSON.stringify(val)}`);
+      }
+      output.log('');
+      return;
+    }
+
+    if (subcommand === 'set') {
+      const key   = args[1];
+      const value = args[2];
+      if (!key || value === undefined) {
+        output.error('Usage: npa config set <key> <value>');
+        process.exit(1);
+      }
+      try {
+        const updated = setGlobalConfig(key, value);
+        output.success(`Set ${key} = ${JSON.stringify(updated[key])}`);
+        output.log(output.dim(`  Written to ${getGlobalConfigPath()}`));
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+      return;
+    }
+
+    output.error(`Unknown config subcommand: "${subcommand}". Use "get" or "set".`);
+    process.exit(1);
+  },
+};

package/src/commands/index.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const commands = new Map();
+
+// Load all command modules from this directory
+const files = fs.readdirSync(__dirname).filter(f => f !== 'index.js' && f.endsWith('.js'));
+
+for (const file of files) {
+  const cmd = require(path.join(__dirname, file));
+  commands.set(cmd.name, cmd);
+  for (const alias of cmd.aliases || []) {
+    commands.set(alias, cmd);
+  }
+}
+
+module.exports = {
+  commands,
+
+  get(name) {
+    return commands.get(name);
+  },
+
+  list() {
+    const seen = new Set();
+    const result = [];
+    for (const cmd of commands.values()) {
+      if (!seen.has(cmd.name)) {
+        seen.add(cmd.name);
+        result.push(cmd);
+      }
+    }
+    return result;
+  },
+};

package/src/commands/install.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { scan } = require('../core/scanner');
+const { runAware, runNpm } = require('../utils/review');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'install',
+  aliases: ['i'],
+  description: 'Audit then run npm install',
+
+  help() {
+    return `
+  npa install — Audit dependencies then run npm install
+
+  Usage:
+    npa install [package] [options]
+
+  Options:
+    --review, -r   Interactive mode: review and allow/deny scripts
+    --json        Output scan results as JSON
+    --no-dev      Skip devDependencies in scan
+    --verbose     Show detailed findings
+    -h, --help    Show this help
+
+  Examples:
+    npa install                Install all deps after audit
+    npa install lodash         Add lodash after auditing it
+    npa install --review        Review scripts interactively
+`;
+  },
+
+  async run({ args, flags, config, cwd }) {
+    const packages = args.filter(a => !a.startsWith('-'));
+
+    const results = await scan({
+      cwd,
+      config,
+      noDev:         flags.noDev,
+      verbose:       flags.verbose,
+      packages:      packages.length > 0 ? packages : null,
+    });
+
+    const hasIssues = results.some(r => r.verdict !== 'OK');
+    const silent = config.silent && !hasIssues;
+
+    output.printScanHeader(silent);
+
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+    } else {
+      printResults(results, silent);
+    }
+
+    const blocked = results.filter(r => r.verdict === 'BLOCK');
+
+    if (blocked.length > 0 && !flags.review) {
+      output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
+      output.log(output.dim('  Run with --review to interactively decide which scripts to allow.'));
+      process.exit(1);
+    }
+
+    const npmArgs = packages.length > 0 ? packages : [];
+
+    if (flags.review) {
+      const packagesWithScripts = results.filter(r => r.verdict !== 'OK' || r.scripts.length > 0);
+      const exit = await runAware({
+        results: packagesWithScripts.length > 0 ? packagesWithScripts : results,
+        command: 'install',
+        npmArgs,
+        cwd,
+      });
+      process.exit(exit);
+    } else {
+      const exit = runNpm('install', npmArgs, cwd);
+      process.exit(exit);
+    }
+  },
+};
+
+function printResults(results, silent = false) {
+  if (silent) return;
+  if (results.length === 0) {
+    output.success('No packages with install scripts found.');
+    return;
+  }
+  for (const r of results) {
+    output.printPackageResult(r.pkg, r);
+  }
+}
+
+function toJsonReport(results) {
+  return {
+    summary: {
+      total:   results.length,
+      blocked: results.filter(r => r.verdict === 'BLOCK').length,
+      warned:  results.filter(r => r.verdict === 'WARN').length,
+      ok:      results.filter(r => r.verdict === 'OK').length,
+    },
+    packages: results.map(r => ({
+      name:     r.pkg.name,
+      version:  r.pkg.version,
+      verdict:  r.verdict,
+      score:    r.score,
+      findings: r.findings,
+      scripts:  r.scripts.map(s => ({ lifecycle: s.lifecycle, file: s.file, score: s.score })),
+    })),
+  };
+}

package/src/commands/scan.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { scan } = require('../core/scanner');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'scan',
+  aliases: ['s'],
+  description: 'Scan only, no npm invocation',
+
+  help() {
+    return `
+  npa scan — Scan dependencies for obfuscated install scripts
+
+  Usage:
+    npa scan [package] [options]
+
+  Options:
+    --json        Output results as JSON
+    --no-dev      Skip devDependencies
+    --verbose     Show detailed findings
+    -h, --help    Show this help
+
+  Examples:
+    npa scan              Scan all dependencies
+    npa scan lodash       Scan a specific package before installing
+    npa scan --no-dev     Scan production dependencies only
+    npa scan --json       Output machine-readable JSON
+`;
+  },
+
+  async run({ args, flags, config, cwd }) {
+    const packages = args.filter(a => !a.startsWith('-'));
+    const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose, packages: packages.length > 0 ? packages : null });
+    const hasIssues = results.some(r => r.verdict !== 'OK');
+    const silent = config.silent && !hasIssues;
+
+    output.printScanHeader(silent);
+
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+      const hasBlock = results.some(r => r.verdict === 'BLOCK');
+      process.exit(hasBlock ? 1 : 0);
+    }
+
+    printResults(results, silent);
+    if (!silent) output.printSummary(results);
+
+    const hasBlock = results.some(r => r.verdict === 'BLOCK');
+    process.exit(hasBlock ? 1 : 0);
+  },
+};
+
+function printResults(results, silent = false) {
+  if (silent) return;
+  if (results.length === 0) {
+    output.success('No packages with install scripts found.');
+    return;
+  }
+  for (const r of results) {
+    output.printPackageResult(r.pkg, r);
+  }
+}
+
+function toJsonReport(results) {
+  return {
+    summary: {
+      total:   results.length,
+      blocked: results.filter(r => r.verdict === 'BLOCK').length,
+      warned:  results.filter(r => r.verdict === 'WARN').length,
+      ok:      results.filter(r => r.verdict === 'OK').length,
+    },
+    packages: results.map(r => ({
+      name:     r.pkg.name,
+      version:  r.pkg.version,
+      verdict:  r.verdict,
+      score:    r.score,
+      findings: r.findings,
+      scripts:  r.scripts.map(s => ({ lifecycle: s.lifecycle, file: s.file, score: s.score })),
+    })),
+  };
+}

package/src/{scanner.js → core/scanner.js}

@@ -2,11 +2,11 @@
 
 const fs      = require('fs');
 const path    = require('path');
-const { parseLockfile }                = require('./lockfile');
-const { fetchTarball, buildTarballUrl, verifyIntegrity } = require('./fetcher');
-const { parseTarGz, extractFile, getPackageJson }        = require('./tarball');
+const { parseLockfile }                = require('../utils/lockfile');
+const { fetchTarball, buildTarballUrl, verifyIntegrity } = require('../utils/fetcher');
+const { parseTarGz, extractFile, getPackageJson }        = require('../utils/tarball');
 const { detectObfuscation }            = require('./detector');
-const output                           = require('./output');
+const output                           = require('../utils/output');
 
 /**
  * Main scan orchestrator.
@@ -15,16 +15,33 @@ const output                           = require('./output');
  * @param {object}  opts.config
  * @param {boolean} opts.noDev
  * @param {boolean} opts.verbose
- * @param {string|null} opts.singlePackage  name for single-package mode
+ * @param {string|null} opts.singlePackage  name for single-package mode (deprecated, use packages)
+ * @param {string[]|null} opts.packages  package names to scan
  * @returns {Promise<ScanResult[]>}
  */
 async function scan(opts) {
-  const { cwd, config, noDev, verbose, singlePackage } = opts;
+  const { cwd, config, noDev, verbose, singlePackage, packages: packageList } = opts;
 
   let packages;
   let lockfileVersion = 1;
-  if (singlePackage) {
-    packages = await resolveSinglePackage(singlePackage, config);
+  let explicitPackageNames = new Set();
+
+  // Support both single package (legacy) and multiple packages
+  const targetPackages = packageList || (singlePackage ? [singlePackage] : null);
+
+  if (targetPackages && targetPackages.length > 0) {
+    // Scan specific packages from registry
+    const allPackages = [];
+    for (const pkg of targetPackages) {
+      const resolved = await resolveSinglePackage(pkg, config);
+      // Mark the first package (the explicitly requested one) as explicit
+      if (resolved.length > 0) {
+        const pkgName = pkg.includes('@') && !pkg.startsWith('@') ? pkg.split('@')[0] : pkg;
+        explicitPackageNames.add(pkgName);
+      }
+      allPackages.push(...resolved);
+    }
+    packages = allPackages;
   } else {
     const lockPath = path.join(cwd, 'package-lock.json');
     if (fs.existsSync(lockPath)) {
@@ -37,6 +54,9 @@ async function scan(opts) {
     }
   }
 
+  // Track packages without install scripts (for skipped count)
+  let skippedCount = 0;
+
   // Apply skip filters
   packages = packages.filter(pkg => {
     if (noDev && pkg.dev) return false;
@@ -47,6 +67,14 @@ async function scan(opts) {
         if (pkg.name.startsWith(scope + '/') || pkg.name === scope) return false;
       }
     }
+    // For explicit packages, always include them but track if they have no scripts
+    if (explicitPackageNames.has(pkg.name)) {
+      if (!pkg.hasInstallScript) {
+        skippedCount++;
+        return false;
+      }
+      return true;
+    }
     // v2/v3 lockfiles reliably report hasInstallScript — skip definitive negatives
     if (lockfileVersion >= 2 && pkg.hasInstallScript === false) return false;
     return true;
@@ -59,7 +87,13 @@ async function scan(opts) {
     return scanPackage(pkg, cwd, config, verbose);
   });
 
-  return results.filter(Boolean);
+  const scanned = results.filter(Boolean);
+  // Add packages that returned null from scanPackage (no scripts found during scan)
+  skippedCount += results.filter(r => r === null).length;
+
+  // Attach metadata to results array
+  scanned.skippedCount = skippedCount;
+  return scanned;
 }
 
 /**
@@ -269,7 +303,8 @@ function extractSemver(range) {
 async function resolveFromPackageJson(cwd, config, noDev) {
   const pkgPath = path.join(cwd, 'package.json');
   if (!fs.existsSync(pkgPath)) {
-    throw new Error(`package.json not found in ${cwd}`);
+    // No package.json — nothing to scan (e.g. empty directory)
+    return [];
   }
 
   let pkgJson;
@@ -285,7 +320,7 @@ async function resolveFromPackageJson(cwd, config, noDev) {
   }
 
   const packages = [];
-  const { fetchJSON } = require('./fetcher');
+  const { fetchJSON } = require('../utils/fetcher');
 
   for (const [name, range] of Object.entries(deps)) {
     const version = extractSemver(range);
@@ -327,7 +362,7 @@ async function resolveSinglePackage(packageSpec, config) {
     ? packageSpec.split('@')
     : [packageSpec, 'latest'];
 
-  const { fetchJSON } = require('./fetcher');
+  const { fetchJSON } = require('../utils/fetcher');
   let meta;
   try {
     meta = await fetchJSON(`${config.registry}/${encodeURIComponent(name)}`, { timeout: config.timeout });

package/src/{config.js → utils/config.js}

@@ -14,6 +14,7 @@ const DEFAULT_CONFIG = Object.freeze({
   parallelFetches: 5,
   skipScopes:      [],
   skipPackages:    [],
+  silent:          false,
 });
 
 const VALID_KEYS = new Set(Object.keys(DEFAULT_CONFIG));
@@ -43,6 +44,8 @@ function coerce(obj) {
     } else if (typeof def === 'number') {
       const n = Number(val);
       if (!isNaN(n)) result[key] = n;
+    } else if (typeof def === 'boolean') {
+      result[key] = val === true || val === 'true' || val === '1';
     } else {
       result[key] = val;
     }

package/src/{output.js → utils/output.js}

@@ -49,16 +49,26 @@ function log(msg) {
 }
 
 function verdictBadge(verdict) {
-  if (NO_COLOR) return `[${verdict}]`;
-  if (verdict === 'BLOCK') return `${BG_RED}${BOLD} BLOCK ${RESET}`;
+  if (NO_COLOR) return verdict === 'BLOCK' ? '[DANGER]' : `[${verdict}]`;
+  if (verdict === 'BLOCK') return `${BG_RED}${WHITE}${BOLD} DANGER ${RESET}`;
   if (verdict === 'WARN')  return `${BG_YELLOW}\x1b[30m WARN  ${RESET}`;
   return `${GREEN} OK    ${RESET}`;
 }
 
-function printScanHeader() {
-  log('');
-  log(bold(cyan('npa') + ' — npm package auditor'));
-  log(dim('Static obfuscation detection for install scripts'));
+const ASCII_LOGO = `
+
+  ███╗   ██╗██████╗  █████╗
+  ████╗  ██║██╔══██╗██╔══██╗
+  ██╔██╗ ██║██████╔╝███████║
+  ██║╚██╗██║██╔═══╝ ██╔══██║
+  ██║ ╚████║██║     ██║  ██║
+  ╚═╝  ╚═══╝╚═╝     ╚═╝  ╚═╝
+`;
+
+function printScanHeader(silent = false) {
+  if (silent) return;
+  log(blue(ASCII_LOGO));
+  log(dim('  npm package auditor — static obfuscation detection'));
   log(dim('─'.repeat(60)));
   log('');
 }
@@ -77,10 +87,15 @@ function printSummary(results) {
   const blocked = results.filter(r => r.verdict === 'BLOCK').length;
   const warned  = results.filter(r => r.verdict === 'WARN').length;
   const ok      = results.filter(r => r.verdict === 'OK').length;
+  const skipped = results.skippedCount || 0;
 
   log('');
   log(dim('─'.repeat(60)));
-  log(`  ${green(String(ok))} clean   ${yellow(String(warned))} warnings   ${red(String(blocked))} blocked`);
+  let summary = `  ${green(String(ok))} clean   ${yellow(String(warned))} warnings   ${red(String(blocked))} blocked`;
+  if (skipped > 0) {
+    summary += `   ${dim(String(skipped) + ' skipped (no install scripts)')}`;
+  }
+  log(summary);
   log('');
 }
 

package/src/{aware.js → utils/review.js}

@@ -40,11 +40,21 @@ async function runAware(opts) {
 
   let cursor = 0;
 
+  // Use alternate screen buffer on supported terminals (not legacy Windows console)
+  const useAltScreen = process.stdout.isTTY && (
+    process.platform !== 'win32' ||
+    process.env.WT_SESSION ||  // Windows Terminal
+    process.env.ConEmuPID      // ConEmu
+  );
+
+  if (useAltScreen) {
+    process.stdout.write('\x1b[?1049h');
+  }
+
   function render() {
-    // Move cursor to top of list — use ANSI escape to clear + redraw
-    process.stdout.write('\x1b[2J\x1b[H'); // clear screen
+    process.stdout.write('\x1b[H\x1b[2J');
     output.log('');
-    output.log(output.bold('  npa --aware mode'));
+    output.log(output.bold('  npa --review mode'));
     output.log(output.dim('  Use ↑/↓ to navigate, SPACE to toggle, ENTER to confirm, q to quit'));
     output.log('');
     output.log(`  Found ${items.length} package(s) with install scripts:\n`);
@@ -115,8 +125,10 @@ async function runAware(opts) {
     process.stdin.on('keypress', onKey);
   });
 
-  // Clear screen after TUI exits
-  process.stdout.write('\x1b[2J\x1b[H');
+  // Exit alternate screen buffer (restores previous screen)
+  if (useAltScreen) {
+    process.stdout.write('\x1b[?1049l');
+  }
 
   const allowedItems = items.filter(i => i.allowed);
   const deniedItems  = items.filter(i => !i.allowed);
@@ -124,30 +136,58 @@ async function runAware(opts) {
   output.log('');
   output.info(`Proceeding with ${allowedItems.length} allowed / ${deniedItems.length} denied`);
 
+  // Get names of denied packages to exclude from install
+  const deniedNames = new Set(deniedItems.map(i => i.result.pkg.name));
+
+  // Filter npmArgs to exclude denied packages
+  let filteredNpmArgs = npmArgs.filter(arg => {
+    // Extract package name (handle @scope/pkg and pkg@version formats)
+    const name = arg.startsWith('@')
+      ? arg.split('/').slice(0, 2).join('/').split('@').slice(0, 2).join('@').replace(/@[^@]*$/, '') || arg.split('@').slice(0, 2).join('@')
+      : arg.split('@')[0];
+    return !deniedNames.has(name);
+  });
+
+  // If all explicitly requested packages are denied, abort
+  if (npmArgs.length > 0 && filteredNpmArgs.length === 0) {
+    output.error('All requested packages were denied. Aborting install.');
+    return 1;
+  }
+
   if (deniedItems.length > 0) {
-    output.warn('Running npm with --ignore-scripts (will run allowed scripts manually after)');
-    const code = runNpm(command, [...npmArgs, '--ignore-scripts'], cwd);
-    if (code !== 0) return code;
-
-    for (const item of allowedItems) {
-      const exitCode = runPackageScripts(item.result, cwd);
-      if (exitCode !== 0) {
-        output.error(`Script for ${item.result.pkg.name} exited with code ${exitCode}`);
+    if (filteredNpmArgs.length > 0 || npmArgs.length === 0) {
+      output.warn('Running npm with --ignore-scripts (will run allowed scripts manually after)');
+      const code = runNpm(command, [...filteredNpmArgs, '--ignore-scripts'], cwd);
+      if (code !== 0) return code;
+
+      for (const item of allowedItems) {
+        const exitCode = runPackageScripts(item.result, cwd);
+        if (exitCode !== 0) {
+          output.error(`Script for ${item.result.pkg.name} exited with code ${exitCode}`);
+        }
       }
+      return 0;
+    } else {
+      output.warn('No packages to install after excluding denied packages.');
+      return 0;
     }
-    return 0;
   } else {
-    return runNpm(command, npmArgs, cwd);
+    return runNpm(command, filteredNpmArgs.length > 0 ? filteredNpmArgs : npmArgs, cwd);
   }
 }
 
 /**
  * Spawn npm install/ci and return the exit code.
+ * Sets NPA_RUNNING=1 to prevent recursive hooks when npm is aliased to npa.
  */
 function runNpm(command, args, cwd) {
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
   const npmArgs = command === 'ci' ? ['ci', ...args] : ['install', ...args];
-  const result = spawnSync(npmCmd, npmArgs, { stdio: 'inherit', cwd });
+  const result = spawnSync(npmCmd, npmArgs, {
+    stdio: 'inherit',
+    cwd,
+    env: { ...process.env, NPA_RUNNING: '1' },
+  });
   return result.status || 0;
 }