Real-World Scenarios

# Install with audit
npq install lodash

# Output shows:
# - Progress spinner during checks
# - Warnings/errors grouped by category
# - Summary with counts
# - Auto-continue countdown (if warnings only)
# - Installation proceeds after confirmation

# Audit all dependencies without installing
npq install --dry-run

# Reads dependencies and devDependencies from package.json
# Runs all marshalls on each package
# Exits with status code indicating results

# Audit specific dependency
npq install express --dry-run

# Audit with plain output for logging
npq install --dry-run --plain > audit.log

# Add to ~/.bashrc or ~/.zshrc
alias npm='npq-hero'

# Now all npm install commands are automatically audited
npm install express  # Audited by npq first, then installed

# For yarn
alias yarn="NPQ_PKG_MGR=yarn npq-hero"

# For pnpm
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"

# Strict security mode
export NPQ_DISABLE_AUTO_CONTINUE=true
export MARSHALL_DISABLE_AGE=0        # Enable all checks
export SNYK_TOKEN=your_token_here    # Use Snyk for vulnerabilities
export GITHUB_TOKEN=your_token_here  # Higher rate limits

# Run with custom policy
npq install @company/package

# Use --dry-run to audit without installing
npx npq install express --dry-run --plain

# Exit code indicates success/failure
if npx npq install express --dry-run; then
  npm install express
fi

set -e
npx npq install express --dry-run --plain || {
  echo "Security audit failed"
  exit 1
}
npm install express

- name: Security audit
  run: npx npq install --dry-run --plain
- name: Install dependencies
  if: success()
  run: npm install

# Check exit code explicitly
npq install package --dry-run
EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
  echo "Audit passed"
elif [ $EXIT_CODE -eq 1 ]; then
  echo "User aborted"
elif [ $EXIT_CODE -eq -1 ]; then
  echo "Error occurred"
fi

const { execSync } = require('child_process');
try {
  execSync('npq install express --dry-run', { stdio: 'inherit' });
  // Exit code 0 - proceed with installation
  execSync('npm install express', { stdio: 'inherit' });
} catch (error) {
  if (error.status === 1) {
    console.log('User aborted');
  } else if (error.status === -1) {
    console.error('Security audit failed');
    process.exit(1);
  }
}

# Disable auto-continue for strict security review
export NPQ_DISABLE_AUTO_CONTINUE=true

# Audit all project dependencies
npq install  # Reads from package.json

# Audit and install with review
npq install express
# Review all warnings/errors
# Manually confirm or abort

# Use with pnpm
NPQ_PKG_MGR=pnpm npx npq install fastify

# Use with yarn 4.x
NPQ_PKG_MGR=yarn yarn run npq-hero install lodash

# Use with yarn 1.x
NPQ_PKG_MGR=yarn npq install axios

# Disable noisy checks for internal packages
MARSHALL_DISABLE_DOWNLOADS=1 MARSHALL_DISABLE_AGE=1 npq install @mycompany/internal-lib

# Disable checks that require network for offline mode
MARSHALL_DISABLE_REPO=1 MARSHALL_DISABLE_DEPRECATION=1 MARSHALL_DISABLE_SNYK=1 npq install package

// In package.json scripts
{
  "scripts": {
    "preinstall": "node scripts/audit-dependencies.js",
    "install": "npm install"
  }
}

// scripts/audit-dependencies.js
const Marshall = require('npq/lib/marshall');
const fs = require('fs');

async function auditDependencies() {
  const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
  const allDeps = [
    ...Object.keys(packageJson.dependencies || {}),
    ...Object.keys(packageJson.devDependencies || {})
  ];
  
  const packages = allDeps.map(dep => {
    const version = packageJson.dependencies[dep] || packageJson.devDependencies[dep];
    return `${dep}@${version}`;
  });
  
  const marshall = new Marshall({ pkgs: packages });
  const results = await marshall.run();
  
  const hasErrors = results.some(r => r.errors.length > 0);
  if (hasErrors) {
    console.error('Security audit failed');
    process.exit(1);
  }
}

auditDependencies().catch(error => {
  console.error('Audit error:', error);
  process.exit(1);
});