DepWatcher

An automated dependency monitoring tool that checks for outdated packages in your Node.js project and sends detailed email notifications via Gmail.

Features

• 🔍 Single Project Monitoring: Monitor your current project's dependencies
• 📧 Email Notifications: Send detailed HTML email reports with changelog links and severity information
• ⏰ Automated Scheduling: Run checks daily via cron scheduler (configurable)
• 🎯 Smart Categorization: Categorize updates by severity (major, minor, patch)
• 🔗 Rich Information: Include npm links, changelog URLs, and package descriptions
• 🛡️ Error Handling: Graceful error handling with email notifications
• 🚀 Production Ready: Support for both development and production modes
• 📦 Easy Integration: Simple CLI tool that works with any Node.js project

Installation

Global Installation (Recommended)

npm install -g dep-watcher

Local Installation

npm install --save-dev dep-watcher

Quick Start

Option 1: Interactive Setup (Recommended)

1. Install globally:

   npm install -g dep-watcher

2. Navigate to your project:

   cd /path/to/your/project

3. Run interactive setup:

   dep-watcher setup

   This will guide you through the entire configuration process!

4. Start monitoring:

   dep-watcher start

Option 2: Manual Setup

1. Initialize DepWatcher:

   dep-watcher init

2. Configure Gmail credentials:

   dep-watcher config --gmail [email protected] --recipient [email protected]

3. Set up Gmail app password (see Gmail Setup section below)

4. Set password in .env file:

   # Create .env file with your Gmail app password
   echo "DEPWATCH_GMAIL_PASSWORD=your-app-password" > .env

5. Start monitoring:

   dep-watcher start

Configuration

DepWatcher uses a .env file in your project root for configuration.

1. Initialize Configuration

Run dep-watcher init to create the environment file:

dep-watcher init

This creates a .env file with default settings.

2. Configure Environment Variables

Edit the .env file with your Gmail credentials:

# DepWatcher Configuration
[email protected]
DEPWATCH_GMAIL_PASSWORD=your-gmail-app-password
[email protected]

3. Interactive Setup (Recommended)

For first-time users, use the interactive setup wizard:

dep-watcher setup

This will guide you through the configuration process and create the .env file automatically.

4. Gmail App Password Setup

Since Gmail requires app-specific passwords for SMTP:

1. Go to your Google Account settings
2. Navigate to Security → 2-Step Verification (enable if not already)
3. Go to App passwords
4. Generate a new app password for "Mail"
5. Add it to .env file: DEPWATCH_GMAIL_PASSWORD=your-app-password

5. Schedule Configuration

Set custom schedule in your .env file:

CRON_SCHEDULE=0 9 * * 1-5  # Weekdays at 9 AM

Common cron schedules:

• 0 9 * * * - Daily at 9 AM (default)
• 0 9 * * 1-5 - Weekdays at 9 AM
• 0 9 * * 1 - Weekly on Monday at 9 AM
• 0 */6 * * * - Every 6 hours

Usage

CLI Commands

dep-watcher init                    # Initialize DepWatcher for current project
dep-watcher check                   # Run dependency check
dep-watcher version                 # Show version information
dep-watcher help                    # Show help information

Usage

Initialize DepWatcher

dep-watcher init

This creates a .env file in your project root with default configuration.

Run Dependency Check

dep-watcher check

This will:

1. Check for outdated dependencies
2. Send email notification if updates are found
3. Exit when complete

Production Deployment

Using GitHub Actions

name: Dependency Check
on:
  schedule:
    - cron: '0 9 * * *'  # Daily at 9 AM
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: dep-watcher check
        env:
          GMAIL_USER: ${{ secrets.GMAIL_USER }}
          DEPWATCH_GMAIL_PASSWORD: ${{ secrets.DEPWATCH_GMAIL_PASSWORD }}
          RECIPIENT_EMAIL: ${{ secrets.RECIPIENT_EMAIL }}

Using Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["dep-watcher", "check"]

Using PM2

# Install PM2 globally
npm install -g pm2

# Start DepWatcher
pm2 start "dep-watcher check" --name depwatcher

# Save PM2 configuration
pm2 save
pm2 startup

Manual Testing

Run a dependency check:

dep-watcher check

This will:

1. Check for outdated dependencies in your project
2. Display results in the console
3. Send email notification if updates are found

Cron Schedule Examples

The schedule uses standard cron syntax:

# Daily at 9:00 AM (default)
dep-watcher config --schedule "0 9 * * *"

# Weekly on Monday at midnight
dep-watcher config --schedule "0 0 * * 1"

# Weekdays at 9:00 AM
dep-watcher config --schedule "0 9 * * 1-5"

# Every 6 hours
dep-watcher config --schedule "0 */6 * * *"

# Twice daily (9 AM and 6 PM)
dep-watcher config --schedule "0 9,18 * * *"

Email Report Features

The email reports include:

• Summary Statistics: Total updates, major/minor/patch breakdown
• Project-wise Results: Organized by project with detailed tables
• Package Information: Current vs latest versions, update types, severity
• Direct Links: npm package pages, changelog URLs, homepage links
• Visual Indicators: Color-coded severity badges and update types
• Error Reporting: Clear error messages for failed checks

Project Structure

When you run dep-watcher init, it creates:

your-project/
├── package.json            # Your project's dependencies
├── .depwatch.json         # DepWatcher configuration
└── ...                    # Your other project files

The .depwatch.json file contains:

{
  "email": {
    "gmail": {
      "user": "[email protected]"
    },
    "recipient": "[email protected]"
  },
  "schedule": "0 9 * * *",
  "environment": "development",
  "env": {
    "gmailPassword": "DEPWATCH_GMAIL_PASSWORD"
  }
}

Note: The password field is intentionally omitted for security reasons.

Security

DepWatcher follows security best practices:

Password Storage

• Never stores passwords in config files
• Uses environment variables for sensitive data
• Supports both GMAIL_APP_PASSWORD and DEPWATCH_GMAIL_PASSWORD environment variables

Environment Variables

# Set Gmail app password
export DEPWATCH_GMAIL_PASSWORD="your-app-password"

# Or use the legacy variable name
export GMAIL_APP_PASSWORD="your-app-password"

Config File Security

The .depwatch.json file only contains non-sensitive configuration:

{
  "email": {
    "gmail": {
      "user": "[email protected]"
    },
    "recipient": "[email protected]"
  },
  "schedule": "0 9 * * *",
  "environment": "development"
}

Best Practices

1. Never commit passwords to version control
2. Use environment variables for sensitive data
3. Keep your Gmail app password secure
4. Regularly rotate your app passwords

Error Handling

DepWatcher includes comprehensive error handling:

• Configuration Validation: Validates all required settings before starting
• Email Configuration Testing: Tests Gmail SMTP connection on startup
• Project Validation: Ensures package.json exists in current directory
• Network Error Handling: Graceful handling of npm registry API failures
• Email Error Notifications: Sends error reports via email when checks fail

Production Deployment

Using PM2 (Recommended)

Install PM2 globally:

npm install -g pm2

Start DepWatcher in your project:

cd /path/to/your/project
pm2 start "dep-watcher start" --name "dep-watcher-$(basename $(pwd))"

Save PM2 configuration:

pm2 save
pm2 startup

Using systemd

Create a systemd service file /etc/systemd/system/dep-watcher-yourproject.service:

[Unit]
Description=Dependency Watcher for Your Project
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/your/project
ExecStart=/usr/bin/dep-watcher start
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable dep-watcher-yourproject
sudo systemctl start dep-watcher-yourproject

Troubleshooting

Common Issues

1. Gmail Authentication Failed

   • Ensure 2-Step Verification is enabled
   • Use app-specific password, not your regular password
   • Check that the email address is correct

2. Configuration Not Found

   • Run dep-watcher init to create configuration file
   • Ensure you're in the correct project directory
   • Check that .depwatch.json exists

3. No Email Received

   • Check spam/junk folder
   • Verify recipient email address
   • Test email configuration manually

4. Cron Schedule Not Working

   • Verify cron syntax is correct
   • Check timezone settings
   • Ensure the application is running continuously

Debug Mode

Enable debug logging by setting:

DEBUG=dep-watcher:* dep-watcher start

Examples

Basic Setup

# Install globally
npm install -g dep-watcher

# Navigate to your project
cd /path/to/your/project

# Run interactive setup (recommended)
dep-watcher setup

# Start monitoring
dep-watcher start

Manual Setup

# Install globally
npm install -g dep-watcher

# Navigate to your project
cd /path/to/your/project

# Initialize DepWatcher
dep-watcher init

# Configure Gmail
dep-watcher config --gmail [email protected] --recipient [email protected]

# Start monitoring
dep-watcher start

Advanced Configuration

# Set custom schedule (weekdays at 9 AM)
dep-watcher config --schedule "0 9 * * 1-5"

# Set production environment
dep-watcher config --environment production

# Run manual check
dep-watcher check

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

ISC License - see package.json for details.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the error logs
3. Test your configuration manually
4. Open an issue on GitHub if needed