GitHub - yowainwright/pastoralist: A CLI for automatically shepherding package.json overrides 👩🏽‍🌾 (original) (raw)

Pastoralist is an audit trail for package manager overrides.

Overrides often start as real fixes: a CVE patch, a compatibility pin, a fork, or a temporary transitive dependency workaround. Months later, the override is still in package.json, but the reason is usually somewhere else.

Pastoralist keeps the package-manager instruction where it belongs and adds the missing review record: why the override exists, which packages still need it, which security provider found it, and when it can be removed.

Quick Start

Start with a read-only check:

When you are ready to add it to the project:

npm install pastoralist --save-dev npx pastoralist --init npx pastoralist

Optionally keep the appendix current after installs:

{ "scripts": { "postinstall": "pastoralist" } }

Pastoralist can add that hook for you:

npx pastoralist --setup-hook

Why It Exists

Package managers already know how to force a version:

{ "overrides": { "qs": "6.11.2" } }

That may be exactly the right fix. The missing part is the operational record. Pastoralist adds one without moving the override:

{ "overrides": { "qs": "6.11.2" }, "pastoralist": { "appendix": { "qs@6.11.2": { "dependents": { "express": "qs@6.11.0" }, "ledger": { "addedDate": "2026-05-30T00:00:00.000Z", "reason": "Pin qs while upstream dependencies adopt the patched version.", "source": "manual" } } } } }

The override controls installation. The appendix explains the decision. When security checks run, the same ledger can include CVEs, severity, provider, and patched-version metadata.

What It Does

Tracks npm and Bun overrides, pnpm pnpm.overrides, and Yarn resolutions
Records why an override was added and which packages still depend on it
Connects security metadata such as CVEs, severity, provider, and patched version
Links patch-package files to the override entries they support
Reports stale overrides and removes them only when you pass --remove-unused
Reads workspace manifests and writes one consolidated root appendix
Provides dry-run, summary, quiet, and JSON output for CI

Commands

Command	Purpose
npx pastoralist doctor	Read-only setup and override health check
npx pastoralist	Update the override appendix
npx pastoralist --dry-run	Preview package.json changes
npx pastoralist --remove-unused	Remove overrides no package still needs
npx pastoralist --checkSecurity	Check advisories with the default OSV provider
npx pastoralist --quiet --checkSecurity	Minimal CI output and vulnerability exit code
npx pastoralist --summary	Print package, override, and security metrics

Configuration

Pastoralist can use package.json, .pastoralistrc.json,pastoralist.json, pastoralist.config.cjs, pastoralist.config.js, orpastoralist.config.mjs.

{ "pastoralist": { "depPaths": "workspace", "checkSecurity": true, "security": { "provider": "osv", "severityThreshold": "medium", "hasWorkspaceSecurityChecks": true } } }

See Configuration andWorkspaces for the full setup surface.

GitHub Action

Check override tracking on pull requests:

name: Override Check on: [pull_request]

jobs: pastoralist: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6.0.2 - uses: yowainwright/pastoralist@v1 with: mode: check check-security: false

The action can also run security checks, update files, or open scheduled maintenance PRs. See theGitHub Action docs.

Security and Release Assurance

Pastoralist can write to package.json, so the package should be boring to verify.

Releases are published from GitHub Actions with npm provenance
Published tarballs are packed before release and attached to GitHub Releases with artifact attestations
CI runs CodeQL, OpenSSF Scorecard, unit, integration, e2e, and dependency policy checks

You can verify registry signatures from your project:

Docs

Thanks

Shout out to Bryant Cabrera andMardin for the conversation, insight, and pairing around this topic.

Made by @yowainwright. MIT, 2022.