Versionbump

versionbump

Choosing the next version number is usually a judgement call made from memory: "this feels like a minor". versionbump makes it a computation instead. You give it the current version, the commits since that version, and the public API surface changes since that version, and it applies the semantic-versioning rules mechanically — then lists the evidence for the level it chose, so anyone can check its work:

• Major — a commit is marked breaking, or an API entry was removed or changed incompatibly. The next version is (X+1).0.0.
• Minor — no breaking signal, but a feat commit landed or an API entry was added. The next version is X.(Y+1).0.
• Patch — no breaking or feature signal, but there are commits. The next version is X.Y.(Z+1).
• None — no commits and no API changes at all. The next version is the current version, unchanged.

The first matching rule wins, but the evidence is complete, not just the winner: reasons lists every breaking commit, every breaking API change, every feature commit, and every added API entry, in that fixed order, each group in input order. A patch bump carries the single reason no breaking or feature signals; commit(s) present, and a none bump carries no commits and no API changes supplied.

Feature detection is exact: a commit is a feature only when its type is precisely feat (case-sensitive); every other commit type is patch-level unless it is marked breaking. The current version must be strict MAJOR.MINOR.PATCH semver — no prerelease or build suffix. Malformed input — a bad version string, a commit without a type, an API change with an unknown kind — is a validation error naming the offending path (for example commits[1].type must be a non-empty string), and no partial recommendation is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/versionbump recommend --input args.json

npx @reneturcios/versionbump --version

args.json contains the full arguments object:

{

"current_version": "1.4.2", "commits": [ { "type": "feat" }, { "type": "fix", "breaking": true } ], "api_changes": [ { "kind": "added", "name": "exportReport" } ] }

breaking defaults to false per commit and api_changes defaults to []. The recommendation is printed as JSON:

{

"current_version": "1.4.2", "next_version": "2.0.0", "bump": "major", "reasons": [ "commit[1] of type \"fix\" is marked breaking", "commit[0] is a feature (\"feat\")", "API entry \"exportReport\" was added" ] }

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/versionbump mcp

MCP client config:

{

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

Tools

• recommend_version_bump — Recommend the next semantic version from commit types and API surface changes, listing the evidence for the bump level chosen.
• current_version (string, required) — strict MAJOR.MINOR.PATCH semver, e.g. "1.4.2"
• commits (array, required, may be empty) — commits as {type, breaking?} objects; type is the conventional-commit type and breaking defaults to false
• api_changes (array, optional, default []) — API changes as {kind, name} objects, where kind is one of "removed", "changed", "added"

Returns {current_version, next_version, bump, reasons}.

Docker

docker run -i ghcr.io/cloudcorprecords/versionbump

docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/versionbump recommend --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