---
name: dependency-health-check
description: 'Audit dependencies across ByteLyst repos for outdated packages, security vulnerabilities, version conflicts, and unused deps.'
argument-hint: 'Scope, e.g. "all repos", "learning_ai_common_plat only", "security audit only"'
agent: agent
---

# Dependency Health Check Prompt

Audit and remediate dependency issues across the ByteLyst ecosystem.

## Context — ByteLyst Dependency Conventions

- **Package manager:** pnpm (workspace) — never npm or yarn
- **Heavy deps:** Use `peerDependencies` in `@bytelyst/*` packages, NOT `dependencies`
- **Workspace refs:** `"@bytelyst/<name>": "workspace:*"` for internal deps
- **Product refs:** `"@bytelyst/<name>": "file:../../learning_ai_common_plat/packages/<name>"` for product repos
- **Node version:** 22 (see `.nvmrc`)
- **Key shared deps:** `@azure/cosmos`, `jose`, `bcryptjs`, `zod`, `fastify`

## Audit Protocol

### Step 1: Scan Dependencies

For each repo:
```bash
# Check for outdated packages
pnpm outdated

# Security audit
pnpm audit

# Check for unused dependencies
npx depcheck

# Check for duplicate packages
pnpm why <package>
```

### Step 2: Classify Issues

| Severity | Type | Action |
|----------|------|--------|
| 🔴 **Critical** | Known security vulnerability (CVE) | Update immediately |
| 🔴 **Critical** | Major version conflict causing runtime errors | Resolve version |
| 🟡 **High** | Outdated major version with breaking changes | Plan upgrade |
| 🟡 **High** | Unused dependency adding bundle bloat | Remove |
| 🔵 **Medium** | Minor/patch updates available | Batch update |
| ⚪ **Low** | Cosmetic (deprecated warning, newer alternative) | Track for later |

### Step 3: Check Cross-Repo Version Alignment

Ensure these critical packages are aligned across all repos:

| Package | Expected Range | Check |
|---------|---------------|-------|
| `typescript` | `^5.7` | All repos |
| `zod` | `^3.23` | All repos using Zod |
| `fastify` | `^5` | All backends |
| `vitest` | `^3` | All repos with tests |
| `jose` | `^5` or `^6` | Auth-related packages |
| `@azure/cosmos` | `^4` | Data layer |
| `react` | `^19` | Web/mobile clients |
| `next` | `^15` or `^16` | Next.js web apps |

### Step 4: Safe Update Process

#### Minor/patch updates (low risk):
```bash
pnpm update
pnpm test
pnpm typecheck
git add . && git commit -m "chore(deps): update minor/patch dependencies" && git push
```

#### Major updates (higher risk):
```bash
# Update one package at a time
pnpm update <package>@latest

# Test immediately
pnpm test
pnpm typecheck
pnpm build

# Commit separately
git add . && git commit -m "chore(deps): upgrade <package> to v<version>" && git push
```

#### Cross-repo updates:
```bash
# 1. Update in common_plat first
cd learning_ai_common_plat
pnpm update <package>@latest
pnpm build && pnpm test
git add . && git commit -m "chore(deps): upgrade <package>" && git push

# 2. Then update in product repos
cd <product>
pnpm install  # Picks up new versions from common_plat
pnpm test
git add . && git commit -m "chore(deps): sync <package> version" && git push
```

### Step 5: Report

```markdown
## Dependency Health Check: <Scope>

### Executive Summary
- Repos audited: N
- Critical issues: N
- Updates available: N
- Unused deps found: N

### Critical Issues
| Repo | Package | Issue | Action |
|------|---------|-------|--------|

### Version Alignment
| Package | Expected | Repos In Sync | Repos Mismatched |
|---------|----------|---------------|------------------|

### Recommended Updates
| Priority | Repo | Package | Current | Target | Risk |
|----------|------|---------|---------|--------|------|

### Unused Dependencies
| Repo | Package | Safe to Remove |
|------|---------|---------------|
```

## Guardrails

- **Never update all dependencies at once** — do it incrementally
- **Always test after each update** — `pnpm test && pnpm typecheck && pnpm build`
- **Update common_plat first** — product repos depend on it
- **Check peerDependencies** — ensure package consumers are compatible
- **Don't force-resolve version conflicts** — understand why they exist first