Version Synchronization Requirements Across Agent-Reach's pyproject.toml, __init__.py, and Tests

Agent-Reach requires developers to manually synchronize the version string "1.5.0" across pyproject.toml, agent_reach/__init__.py, and tests/test_cli.py, using the test suite as an automated safety net to detect mismatches before release.

In the Panniantong/Agent-Reach repository, version consistency is maintained through a manual three-file update process. The project stores its release identifier in the package metadata, a runtime module constant, and test assertions, requiring careful coordination during each release to ensure all components report the same version number.

Where Version Numbers Are Defined

Agent-Reach maintains its version in three distinct locations, each serving a specific purpose in the build, runtime, and validation lifecycle.

pyproject.toml – The Canonical Source

In pyproject.toml, the version is declared as a literal string that packaging tools consume:

version = "1.5.0"

This value serves as the single source of truth for pip, build, and other PEP 517-compliant tools when installing or distributing the package.

agent_reach/init.py – The Runtime Constant

The __init__.py file exposes the version at runtime through the standard __version__ attribute:

__version__ = "1.5.0"

The CLI and other runtime components import this constant via from agent_reach import __version__ to display version information to users and perform version comparisons.

tests/test_cli.py – The Validation Layer

The test suite contains hardcoded assertions that validate version logic and enforce synchronization:

assert cli._is_newer_version("1.5.0", "1.4.2") is True
assert cli._is_newer_version("1.5.0", "1.5.0") is False

These tests fail immediately if the version literals in the source files diverge from the expected values, preventing inconsistent releases from being merged.

The Synchronization Workflow

Because Agent-Reach does not implement automated version propagation scripts, the synchronization process is human-driven and follows this mandatory sequence:

1. Update pyproject.toml – Bump the version string when preparing a new release.
2. Mirror to __init__.py – Copy the identical literal string into agent_reach/__init__.py as the __version__ constant.
3. Update test assertions – Ensure tests/test_cli.py reflects the new version in its comparison logic.
4. Validate with pytest – Run pytest tests/ -v to confirm the _is_newer_version function and related version tests pass.

This workflow ensures that any mismatch between the packaging metadata and runtime code triggers an immediate test failure, acting as a protective barrier against version drift.

Accessing and Comparing Versions in Your Code

You can retrieve the current version from user code by importing the package constant:

from agent_reach import __version__

print(f"Agent-Reach version: {__version__}")

# Output: Agent-Reach version: 1.5.0

For checking update availability against remote versions, use the CLI's comparison helper:

from agent_reach.cli import _is_newer_version
from agent_reach import __version__

if _is_newer_version(remote="1.5.1", local=__version__):
    print("A newer release is available!")
else:
    print("You are up-to-date.")

Summary

• Three locations require updates: pyproject.toml (packaging), agent_reach/__init__.py (runtime), and tests/test_cli.py (validation).
• Manual synchronization: Developers must copy the version string literally between files; no automated propagation exists.
• Test safety net: The _is_newer_version assertions in tests/test_cli.py catch mismatches during the CI/CD process.
• Current version: As of the latest release, all three files specify version "1.5.0".

Frequently Asked Questions

What happens if I forget to update one of the three version locations?

If the version string in pyproject.toml or agent_reach/__init__.py differs from the hardcoded values in tests/test_cli.py, the test suite will fail when running pytest. Specifically, assertions testing the _is_newer_version function will raise errors, alerting maintainers to the inconsistency before the code is merged.

Why does Agent-Reach use manual version updates instead of dynamic configuration?

The project employs a literal string approach rather than dynamic parsing or automated rewriting scripts. This simplicity ensures that the version is explicitly visible in source control and prevents build-time dependencies from complicating the installation process. The trade-off requires manual vigilance, which is enforced by the test suite.

How does the CLI access the version number for user display?

The CLI module imports the version constant directly from the package root using from agent_reach import __version__. This ensures that the version reported by command-line tools matches the value defined in agent_reach/__init__.py and stays synchronized with the package metadata in pyproject.toml.

Can I check programmatically if a newer version of Agent-Reach is available?

Yes. Import the _is_newer_version function from agent_reach.cli and compare your current __version__ against a remote version string. This helper returns True if the remote version is newer, allowing you to implement custom update notifications in your applications.

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