io.github.CloudCorpRecords/peerconflict

peerconflict

An install just failed with a peer-dependency error and the output is a wall of nested requirements. peerconflict takes the resolved tree — every installed package's name and version, plus the peer requirements each package declares — and lays the problem out as a graph you can read:

• Edges — one entry per peer requirement, each marked satisfied or not. An edge is satisfied only when the peer is actually installed and its installed version falls inside the required range.
• Conflicts — the unsatisfied edges, each typed missing when the peer is not installed at all and version when it is installed but out of range, with a one-line detail such as app requires peer react (^18.0.0) but 17.0.2 is installed.
• Resolutions — one entry per conflicted peer: the requirements behind the conflict, the lowest version that satisfies each range, and the least-change suggestion — install the peer when it is absent, or change its version when it is present — always phrased against every listed range, so the fix addresses all of the peer's requirers at once.

Versions are MAJOR.MINOR.PATCH and nothing else. Ranges follow the grammar the tool defines: * accepts anything, an exact version accepts only itself, ^x.y.z accepts the base version up to (but not including) the next breaking bound — with the usual 0.x tightening, so ^0.2.3 stops before 0.3.0 and ^0.0.3 accepts 0.0.3 alone — ~x.y.z accepts patch-level changes within the same minor, and >=x.y.z accepts the base version and anything above it. Anything outside that grammar is a validation error, as are a missing or duplicate package name, a malformed version, a package listing the same peer twice, and a package declaring a peer on itself. Errors name the offending path (for example packages[0].peers[1].range is not a supported range: "=>1.0.0") and no partial explanation is produced. A peer that is simply absent from the tree is not an error — it is a missing conflict. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/peerconflict explain --input args.json
npx @reneturcios/peerconflict --version

args.json contains the full arguments object:

{
  "packages": [
    { "name": "react", "version": "17.0.2" },
    {
      "name": "app",
      "version": "1.0.0",
      "peers": [{ "name": "react", "range": "^18.0.0" }]
    }
  ]
}

peers defaults to [] per package. The explanation is printed as JSON:

{
  "ok": false,
  "conflicts": [
    {
      "from": "app",
      "peer": "react",
      "range": "^18.0.0",
      "installed": "17.0.2",
      "type": "version",
      "detail": "app requires peer react (^18.0.0) but 17.0.2 is installed"
    }
  ],
  "edges": [
    { "from": "app", "to": "react", "range": "^18.0.0", "satisfied": false }
  ],
  "resolutions": [
    {
      "peer": "react",
      "installed": "17.0.2",
      "required_by": [{ "from": "app", "range": "^18.0.0", "lowest": "18.0.0" }],
      "suggestion": "change react from 17.0.2 to a version satisfying every listed range"
    }
  ]
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/peerconflict mcp

MCP client config:

{
  "mcpServers": {
    "peerconflict": {
      "command": "npx",
      "args": ["-y", "@reneturcios/peerconflict", "mcp"]
    }
  }
}

Tools

• explain_peer_conflict — Explain peer-dependency conflicts in the installed tree.

  • packages (array, required, at least one) — packages as {name, version, peers?} objects; name is unique across the set, version is the installed MAJOR.MINOR.PATCH version, and each peers entry is a {name, range} requirement

  Returns {ok, conflicts, edges, resolutions}.

Docker

docker run -i ghcr.io/cloudcorprecords/peerconflict
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/peerconflict explain --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios