pastoralist

Pastoralist

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:

npx pastoralist doctor

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, or pastoralist.config.mjs.

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

See Configuration and Workspaces 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 the GitHub 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:

npm audit signatures

Docs

• Why Pastoralist
• Setup
• Configuration
• Security
• Workspaces
• GitHub Action
• API Reference
• Architecture

Thanks

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

Made by @yowainwright. MIT, 2022.