upkeep

A comprehensive maintenance toolkit for JavaScript and TypeScript repositories, built with Bun.

Features

• Package Manager Agnostic - Auto-detects and works with npm, yarn, pnpm, and bun
• Dependency Analysis - Find outdated packages with update type classification
• Security Auditing - Scan for vulnerabilities across all package managers
• Import Analysis - Track where packages are used with AST-based scanning
• Quality Scoring - Get a health score for your project (A-F grade)
• Risk Assessment - Evaluate upgrade risk before making changes
• Dependabot Integration - Manage Dependabot PRs from the command line

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/llbbl/upkeep/main/scripts/install.sh | bash

This installs:

• The upkeep CLI binary to ~/.local/bin/ (or ~/.upkeep/bin/ if that doesn't exist)
• Claude Code skills to ~/.claude/skills/ for AI-powered workflows

To install a specific version:

UPKEEP_VERSION=v0.1.3 curl -fsSL https://raw.githubusercontent.com/llbbl/upkeep/main/scripts/install.sh | bash

Manual Installation

Download the appropriate binary from releases:

Platform	Binary
Linux x64	upkeep-linux-x64
macOS ARM64 (Apple Silicon)	upkeep-darwin-arm64
macOS x64 (Intel)	upkeep-darwin-x64
Windows x64	upkeep-windows-x64.exe

From Source

git clone https://github.com/llbbl/upkeep.git
cd upkeep
bun install
bun run build

Usage

CLI Commands

# Detect project configuration
upkeep detect

# Analyze outdated dependencies
upkeep deps

# Security vulnerability scan
upkeep audit

# Find where a package is imported
upkeep imports lodash

# Assess upgrade risk
upkeep risk next --from 14.0.0 --to 15.0.0

# Get project quality score
upkeep quality

# List Dependabot PRs (requires gh CLI)
upkeep dependabot

# Enable verbose output
upkeep --verbose detect

# Set specific log level
upkeep --log-level=debug audit

Example Output

upkeep detect

{
  "packageManager": "pnpm",
  "lockfile": "pnpm-lock.yaml",
  "typescript": true,
  "biome": true,
  "prettier": false,
  "testRunner": "vitest",
  "coverage": true,
  "ci": "github-actions"
}

upkeep quality

{
  "score": 85,
  "grade": "B",
  "breakdown": {
    "dependencyFreshness": { "score": 90, "weight": 20, "details": "3 of 45 packages outdated" },
    "security": { "score": 100, "weight": 25, "details": "No vulnerabilities" },
    "testCoverage": { "score": 75, "weight": 20, "details": "75% line coverage" },
    "typescriptStrictness": { "score": 80, "weight": 10, "details": "Missing: exactOptionalPropertyTypes" },
    "linting": { "score": 100, "weight": 10, "details": "Biome configured" },
    "deadCode": { "score": 70, "weight": 15, "details": "noUnusedLocals enabled" }
  },
  "recommendations": [
    { "priority": "medium", "action": "Update 3 outdated packages" }
  ]
}

Claude Code Skills

upkeep includes skills for Claude Code that provide AI-powered maintenance workflows. Each skill has access to the upkeep binary:

/upkeep-deps

Upgrade dependencies with intelligent risk assessment:

• Prioritizes Dependabot PRs and security fixes
• Assesses risk before each upgrade
• Runs tests and rolls back on failure

/upkeep-audit

Security audit with fix recommendations:

• Explains each vulnerability
• Shows dependency paths
• Guides through safe fixes

/upkeep-quality

Improve project health:

• Explains quality metrics
• Provides actionable improvements
• Tracks progress over time

Development

Prerequisites

• Bun >= 1.0
• Node.js >= 20 (for compatibility testing)
• gh CLI (optional, for Dependabot features)

Setup

git clone https://github.com/llbbl/upkeep.git
cd upkeep
bun install

Commands

# Run in development
bun run dev -- detect

# Run tests
bun test

# Type check
bun run typecheck

# Lint
bun run lint

# Build binary
bun run build

# Build for all platforms
bun run build:all

# Version management
make bump-patch   # 0.1.2 → 0.1.3
make bump-minor   # 0.1.2 → 0.2.0
make show-versions

Project Structure

src/
├── cli/
│   ├── index.ts              # CLI entry point
│   └── commands/             # Command implementations
└── lib/
    ├── analyzers/            # Core analysis modules
    ├── scorers/              # Quality and risk scoring
    ├── github/               # GitHub/Dependabot integration
    ├── utils/                # Utilities (exec, semver)
    └── logger.ts             # Pino logging

skills/
├── upkeep-deps/              # Dependency upgrade skill
├── upkeep-audit/             # Security audit skill
└── upkeep-quality/           # Quality improvement skill

tests/
├── cli/                      # CLI integration tests
├── lib/                      # Unit tests
└── fixtures/                 # Test fixtures

Configuration

upkeep works out of the box with no configuration. It automatically detects:

• Package manager from lockfiles
• TypeScript from tsconfig.json
• Linting from biome.json / .eslintrc
• Test runner from config files or package.json scripts
• CI from .github/workflows

License

MIT