# Lockfile Doctor

> Diagnose package-manager and lockfile drift that causes 'works on my machine' deploy failures. Use whenever an install behaves differently in CI than locally, the user mentions lockfile conflicts, npm/pnpm/yarn confusion, 'npm ci failed', non-reproducible builds, or when auditing any Node project before deploy. Runs fully offline — no API keys, no network, no credentials.

- Skill: `starr-del/lockfile-doctor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add starr-del/lockfile-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starr-del/lockfile-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Starr-del (https://skillmd.com/u/starr-del)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starr-del/lockfile-doctor

---


# lockfile-doctor

Part of **shipsafe** — offline deploy-safety skills. Every script is stdlib-only Python 3.8+; nothing leaves the machine.

```bash
python3 scripts/lockfile_doctor.py <project_root> [--json]
```

Checks: multiple coexisting lockfiles (platform picks one, devs use another), missing lockfile entirely, `packageManager` field disagreeing with the committed lockfile, missing `engines.node`, and fragile dependency specs — git branches, `file:` paths that won't exist on the build machine, and `*`/`latest` wildcards.

The mental model to give the user: **a deploy is reproducible only if the same package manager, same Node version, and same lockfile produce the same node_modules everywhere.** Each finding is one of those three legs broken.

When MULTIPLE_LOCKFILES fires, help the user pick ONE manager (whichever the team actually uses), delete the other lockfiles, and gitignore them so they don't return.

Exit codes: 0 clean, 1 findings.

All paths below are relative to this skill's directory (lockfile-doctor/).