tagguard

tagguard

You are about to tag a release. Do the three things that have to agree — the git tag, the package version, and the changelog entry — actually agree? tagguard is a pre-release gate that answers that question with five explicit checks and blocks the release when any of them fails:

1. SEMVER_VALID — the package version matches the semver grammar (leading zeroes in numeric components are rejected; prerelease and build-metadata suffixes follow semver rules)
2. TAG_MATCHES_VERSION — the tag, normalised by stripping one leading v or V when it is followed by a digit, equals the package version exactly
3. PRERELEASE_ALLOWED — a version with a prerelease component (a - before any +) fails unless prereleases are allowed
4. CHANGELOG_ENTRY — the changelog has a ## heading for this version: ## 0.2.0, ## [0.2.0], ## v0.2.0 (2026-01-01), and ## [0.2.0] - 2026-01-01 all count
5. CHANGELOG_ENTRY_NONEMPTY — the section under that heading says something: at least one non-blank line that is not itself a heading, before the next ## heading

Every check is reported, pass or fail, in that order — the gate never short-circuits, so a blocked release shows all of its problems at once. Pure local computation: no git commands, no network, no configuration.

CLI

npx @reneturcios/tagguard check --tag v0.2.0 --version 0.2.0 --changelog CHANGELOG.md
npx @reneturcios/tagguard --version

Add --allow-prerelease to permit a prerelease version such as 1.0.0-beta.1.

The command prints the gate report as JSON:

{
  "ok": true,
  "normalized_tag": "0.2.0",
  "checks": [
    { "code": "SEMVER_VALID", "ok": true, "message": "..." }
  ]
}

Exit codes: 0 when the gate passes, 1 when the gate blocks (the JSON report is still printed) or a runtime error occurs (an unreadable changelog file prints an error line and no JSON), 2 on a usage error.

MCP server

npx -y @reneturcios/tagguard mcp

MCP client config:

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

Tools

• check_release_tag — Run the pre-release gate over one proposed release and report all five checks.
  • tag (string, required) — the proposed git tag, e.g. "v0.2.0"
  • package_version (string, required) — the version in package.json
  • changelog (string, required) — the CHANGELOG.md text
  • allow_prerelease (boolean, optional, default false) — allow a prerelease version component

A missing or empty tag, package_version, or changelog is an error naming the argument. A non-semver package_version is not an error — it is check 1 failing, which is the gate doing its job.

Docker

docker run -i ghcr.io/cloudcorprecords/tagguard
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/tagguard check --tag v0.2.0 --version 0.2.0 --changelog /w/CHANGELOG.md

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