dep-guardian 0.2.5

CLI tool to audit & auto-update Node.js dependencies, with AI insights.

DepGuardian 🛡️✨ AI Edition

🚀 Version 0.2.5: DepGuardian is no longer just a CLI tool! Now featuring a Local GUI & Gemini AI-Powered Project Analysis! 🚀
DepGuardian has leveled up! It's your comprehensive Python-powered assistant for monitoring, updating, and deeply analyzing your Node.js (NPM) project dependencies.
It meticulously checks for outdated packages, scans for known vulnerabilities using OSV.dev, and can automate Pull Request creation for straightforward updates. The major leap in this version is the integration of:

• A local web-based GUI 💻 for a more intuitive experience in managing and viewing reports.
• Agentic Project Analysis with the Gemini AI API 🧠, allowing you to upload your entire project for in-depth insights into inter-dependency conflicts and receive AI-generated resolution strategies.

Core Features 🌟

🔎 Outdated Dependency Check:

Scans your package.json and package-lock.json (v1, v2, v3 supported) to find direct dependencies that are out of date compared to the NPM registry's latest tag. Reports the installed version, latest available version, and whether the installed version satisfies the range specified in package.json.

🛡️ Vulnerability Audit:

Queries the Open Source Vulnerabilities (OSV) database (osv.dev) for any known vulnerabilities affecting your project’s installed package versions (from package-lock.json).

🤖 Automated Update PR (Experimental):

Optionally, for the first outdated direct dependency found, DepGuardian can:

1. Create a new git branch (e.g., depguardian/update-express-4.18.2).
2. Run npm install <package>@<latest_version>.
3. Commit the package.json and package-lock.json changes.
4. Push the branch to your origin remote.
5. Open a Pull Request on GitHub targeting your repository's default branch.

Prerequisites for PR creation:

• A clean Git working directory.
• git, node, and npm commands available in your PATH.
• A GitHub Personal Access Token (with repo scope) provided via --github-token or GITHUB_TOKEN.
• The target GitHub repository specified via --github-repo or GITHUB_REPOSITORY (in owner/repo format).

✨ NEW! Agentic Project Analysis with Gemini AI:

• Holistic Project View: Upload your entire Node.js project (as a .zip file) directly through the DepGuardian GUI.
• AI-Powered Insights: Provide your Gemini API Key. DepGuardian will:
  • Perform its standard dependency and vulnerability scan on the uploaded project.
  • Prepare a rich context including your package.json, package-lock.json, the initial scan results, and any npm error output from simulated updates (if applicable in future enhancements).
  • Send this context to the Gemini API.
  • Gemini analyzes for complex inter-dependency issues, potential version conflicts, and suggests actionable resolution strategies.
• Comprehensive Report: Receive a detailed JSON report (viewable in the GUI) combining DepGuardian's core findings with Gemini's expert analysis and recommendations.

🖥️ NEW! Local Web GUI:

• Launch with Ease: Start the local dashboard with a simple CLI command: depg gui start.
• AI Analysis Hub: The primary interface for initiating "Analyze Project with Gemini AI" by uploading your project ZIP and API key.
• Report Viewer: Upload and view standard JSON reports generated by depg check or the more comprehensive reports from the AI agent.

Requirements 📋

• Python 3.11+ (due to google-generativeai library and other modern dependencies)
• Node.js and npm (for interacting with Node.js projects and the semver_checker.js helper)
• Git (for the automated PR creation feature)
• A Gemini API Key (for the AI-powered project analysis feature). You can obtain one from Google AI Studio

Installation 🛠️

From PyPI (Recommended for Users)

pip install dep-guardian==0.2.5

From Source (for Development or Cutting-Edge Features)

git clone https://github.com/AbhayBhandarkar/DepGuardian.git 
cd DepGuardian

# Create and activate a Python virtual environment (highly recommended)
python -m venv .venv
# On macOS/Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
# .\.venv\Scripts\activate
# On Windows (PowerShell):
# .\.venv\Scripts\Activate.ps1

# Install all dependencies
pip install --upgrade pip
pip install -r requirements_dev.txt # Installs dev tools + runtime dependencies
pip install -e .                  # Installs DepGuardian in editable mode

# Install Node.js helper dependency (from DepGuardian's root package.json)
npm install

Usage Guide 📖

1. Using the CLI for Standard Scans (depg check)

Navigate to your Node.js project directory (which should contain package.json and package-lock.json).

Basic Check (Console Output):

depg check

Generate a JSON Report (for GUI upload or other uses):

depg check --path /path/to/your/nodejs_project --json-report my_scan_report.json

Example Console Output from depg check:

Scanning project at: /path/to/your/project
Found 2 direct dependencies in package.json.
Found 158 installed packages in package-lock.json (v3).
--------------------
Checking Direct Dependencies against NPM Registry:
- Checking express (4.16.0)... Installed=4.16.0 | Latest=5.1.0 | satisfies range | Update available: 5.1.0
- Checking jest (^27.0.0)... Installed=27.5.1 | Latest=29.7.0 | satisfies range | Update available: 29.7.0
--------------------
Checking for Known Vulnerabilities (OSV API):
Querying OSV for 158 package versions...
OSV query complete. Found 0 vulnerabilities affecting 0 package versions.
No known vulnerabilities found in installed packages.
--------------------
Summary:
2 direct dependencies are outdated.
No vulnerabilities found.
DepGuardian check complete.

Automated Pull Request Creation (Experimental via depg check)

To attempt to update the first outdated direct dependency found by depg check and create a PR:

• Ensure the target project is a Git repository with a clean working directory.
• Set your GitHub Token: export GITHUB_TOKEN="your_github_pat"

Run:

depg check --path /path/to/project --create-pr --github-repo YourUser/YourRepo --json-report pr_attempt.json

The pr_attempt.json will contain details of the update attempt, including npm error output if it fails (useful for later analysis).

Common depg check Options:

• --path /path/to/project: Specify the project directory.
• --json-report <filepath>: Save detailed results to a JSON file.
• --create-pr: Attempt to create a PR for the first outdated dependency.
• --github-repo <owner/repo>: Target repository for the PR.
• --github-token <token>: GitHub PAT for PR creation.
• --verbose or -v: Show more detailed debug logging.

2. Using the Local Web GUI 🖼️ (depg gui start)

The GUI is your new control center for AI-powered analysis and report viewing.

Start the GUI Server:

depg gui --port number

By default, it runs on http://localhost:5001. Open this address in your web browser.

GUI Features:

Analyze Project with Gemini AI:

1. Navigate to the GUI (http://localhost:5001).
2. Enter your Gemini API Key in the designated field.
3. Upload your Node.js project folder as a single .zip file.
4. Click "Analyze with Gemini AI".

DepGuardian's backend (via the depg agent analyze-project CLI command) will:

• Perform its standard scan on the extracted project.
• Prepare a context including your package.json, package-lock.json, and the scan results.
• Send this context to the Gemini AI model using your provided API key.
• Gemini will analyze for inter-dependency issues, version conflicts, and suggest resolution strategies.
• A comprehensive report combining DepGuardian's findings and Gemini's insights will be generated and displayed in your browser. This process may take several minutes.

View Existing DepGuardian Report:

If you have a JSON report previously generated by depg check --json-report ..., you can upload it directly using the "View Existing DepGuardian Report" section on the GUI's main page.
The report details (outdated dependencies, vulnerabilities, etc.) will be displayed.

3. Using the CLI Agent for Gemini Analysis (depg agent analyze-project)

This is the powerful command that the GUI uses for its AI analysis feature. You can also run it directly from your terminal for scripting or more direct control.

Ensure your project folder is accessible on your filesystem.

Set your Gemini API Key (can also be passed as an option):

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Run the command:

depg agent analyze-project \
    --project-path /path/to/your/nodejs_project_folder \
    --gemini-api-key "$GEMINI_API_KEY" \
    --output-json ai_enhanced_report.json \
    --verbose

This will generate ai_enhanced_report.json containing both the standard DepGuardian scan data and the detailed textual analysis from Gemini.

Exit Codes for depg check and depg agent analyze-project:

• 0: Operation completed successfully, and no issues (outdated/vulnerable) were found by the core scan.
• 1: Operation completed, but issues (outdated/vulnerable) were found by the core scan, OR an error occurred during processing (e.g., API failure, file parsing error, LLM error). Check logs and the JSON report.
• 2: CLI usage error (e.g., invalid command-line arguments).

Development 🧑‍💻

git clone https://github.com/AbhayBhandarkar/DepGuardian.git 
cd DepGuardian

# Create and activate a Python virtual environment (Python 3.9+ recommended)
python -m venv .venv
# On macOS/Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
# .\.venv\Scripts\activate
# On Windows (PowerShell):
# .\.venv\Scripts\Activate.ps1

# Install development dependencies and DepGuardian in editable mode
pip install --upgrade pip
pip install -r requirements_dev.txt
pip install -e .

# Install Node.js helper dependency (for semver_checker.js)
npm install

# Check code formatting
black . --check  # To check formatting
# black .        # To automatically reformat files if needed

# Run tests
pytest

# Run the GUI locally for development (from the DepGuardian-1/dep_guardian/gui/ directory)
python app.py

Roadmap / Future Features 🚀

DepGuardian is on a mission to become an indispensable DevOps companion! Here's what's on the horizon:

• 🤖 Enhanced LLM Interactivity & Actions:
  • Allow follow-up questions to the LLM based on its initial analysis directly within the GUI.
  • Explore LLM-suggested concrete code/configuration changes for package.json (e.g., overrides, specific version pins) that users can review and apply.
  • Enable the LLM to perform targeted web searches for very specific, up-to-the-minute conflict resolutions.
• 🐳 Dockerization: Provide an official Docker image for DepGuardian (including the GUI and potentially a local LLM option like Ollama) for easy, consistent execution.
• 🌐 Expanded Ecosystem Support: Add support for other package managers and programming language ecosystems (e.g., Python's Pip, Java's Maven, RubyGems).
• ⚙️ Advanced Update Strategies: More control over updates (patch/minor only, ignore lists, scheduling).
• 📦 Batch PR Creation / Grouped Updates: Create PRs for multiple outdated dependencies simultaneously or group related updates.