Agent Reach Version Synchronization Requirements: pyproject.toml, __init__.py, and test_cli.py

Agent Reach requires the version string to be synchronized across three files—pyproject.toml, agent_reach/__init__.py, and tests/test_cli.py—to ensure consistent versioning across packaging, runtime, and CLI outputs.

In the Panniantong/Agent-Reach repository, maintaining identical version identifiers prevents mismatched release information and CI failures. The package relies on a manual triple-point validation system where build metadata, runtime constants, and test assertions must contain the exact same version string.

The Three Critical Files

Agent Reach enforces version consistency through three specific locations. Each serves a distinct purpose in the package lifecycle, and divergence between them causes immediate test failures.

pyproject.toml (Build Metadata)

The pyproject.toml file at the repository root defines the build metadata consumed by Hatchling. At line 3, the version declaration determines what pip and package indexes publish:

[project]
version = "1.5.0"

This static assignment controls the wheel version and PyPI distribution artifacts.

agent_reach/init.py (Runtime Constant)

The agent_reach/__init__.py file exposes the __version__ runtime constant at line 4:

__version__ = "1.5.0"

Downstream code accesses this via agent_reach.__version__, and the CLI imports this constant to generate its --version output.

tests/test_cli.py (Verification Suite)

The test suite validates synchronization through tests/test_cli.py. The TestCLI.test_version method (lines 15–22) executes the CLI and asserts that the output contains the expected version pattern:

def test_version(self, capsys):
    with pytest.raises(SystemExit) as exc_info:
        with patch("sys.argv", ["agent-reach", "version"]):
            main()
    assert exc_info.value.code == 0
    captured = capsys.readouterr()
    assert "Agent Reach v" in captured.out

This test ensures that the runtime version matches the user-facing CLI output, preventing releases where the build and runtime versions diverge.

How Version Propagation Works

The version flows through the codebase in a specific chain that creates testable dependencies:

1. pyproject.toml declares the static version for Hatchling builds
2. agent_reach/__init__.py stores the runtime constant imported by the CLI
3. agent_reach/cli.py (line 58) registers the --version argument using the __version__ constant:

parser.add_argument(
    "--version",
    action="version",
    version=f"Agent Reach v{__version__}"
)

When users execute agent-reach version, the CLI prints Agent Reach v1.5.0 by reading directly from __init__.py. Because the test suite verifies this output against the actual runtime behavior, any discrepancy between the build metadata and runtime code immediately surfaces as a test failure.

Practical Synchronization Examples

When releasing a new version, update all three locations simultaneously:

In pyproject.toml:

[project]
version = "1.6.0"

In agent_reach/__init__.py:

__version__ = "1.6.0"

Verification via CLI:

$ agent-reach version
Agent Reach v1.6.0

The test suite automatically confirms alignment. If the CLI output does not match the expected pattern, pytest will report the assertion failure in test_cli.py, preventing release of inconsistent artifacts.

Summary

• Three files must match: pyproject.toml (build), agent_reach/__init__.py (runtime), and tests/test_cli.py (verification)
• Single source of truth: While pyproject.toml controls packaging, __init__.py controls runtime behavior
• Test enforcement: The test_version test in tests/test_cli.py guarantees that CLI output matches the package version
• Failure mode: Divergent versions cause CI failures and user confusion when pip reports one version but agent-reach --version reports another

Frequently Asked Questions

What happens if pyproject.toml and init.py versions diverge?

The package will build with one version (from pyproject.toml) but report a different version at runtime (from __init__.py). This causes the test_version test in tests/test_cli.py to fail because the CLI output will not match the expected pattern, blocking the release pipeline and preventing inconsistent deployments.

Why does Agent Reach use manual version synchronization instead of dynamic versioning?

The repository uses static version strings in all three locations to maintain explicit, readable version declarations. While tools like hatch-vcs can automate versioning from Git tags, the Panniantong/Agent-Reach codebase prefers explicit synchronization to ensure that the runtime __version__, build metadata, and test assertions remain perfectly aligned without additional build dependencies.

How do I update the version for a new release?

Update the version string in all three locations simultaneously: modify version in pyproject.toml (line 3), __version__ in agent_reach/__init__.py (line 4), and verify that tests/test_cli.py expects the new version in its assertion. Run the test suite to confirm pytest passes the version check before committing the release.

Where does the CLI read its version information?

The CLI implementation in agent_reach/cli.py imports __version__ directly from agent_reach/__init__.py and passes it to the argparse --version action at line 58. This ensures that agent-reach --version always reflects the runtime constant rather than the build metadata, creating a dependency that tests enforce.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}