learning_ai_common_plat/AI.dev/PROMPTS/dependency-health-check.md

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

# 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):

pnpm update
pnpm test
pnpm typecheck
git add . && git commit -m "chore(deps): update minor/patch dependencies" && git push

Major updates (higher risk):

# 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:

# 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

## 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