From 9786846da7001a4b885c12762278cc6a26b3b127 Mon Sep 17 00:00:00 2001
From: ethernet <arilotter@gmail.com>
Date: Mon, 21 Sep 2026 20:19:58 -0400
Subject: [PATCH] feat(version): resolve the version from a generated module

A checkout carries no version of its own. The release stamps
hermes_cli/_version.py into the build tree, and a tree without it reports
0.0.0 rather than a number read out of git.
---
 .gitignore                                  |  2 ++
 hermes_cli/__init__.py                      |  8 ++++-
 tests/hermes_cli/test_version_resolution.py | 35 +++++++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 tests/hermes_cli/test_version_resolution.py

diff --git a/.gitignore b/.gitignore
index 4fcea76f57..ce7e12a4a4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,8 @@
 /_pycache/
 *.pyc*
 __pycache__/
+# Generated by the release into the build tree; a checkout never carries one.
+hermes_cli/_version.py
 act/
 .act-sandbox-agent.*
 .venv/
diff --git a/hermes_cli/__init__.py b/hermes_cli/__init__.py
index 65f253512c..f631af36ff 100644
--- a/hermes_cli/__init__.py
+++ b/hermes_cli/__init__.py
@@ -3,9 +3,15 @@
 import os
 import sys
 
-__version__ = "1.0.0"
 __release_date__ = "2026.9.21"
 
+# A checkout carries no version. The release stamps ``_version.py`` into the build
+# tree; without it the tree reports the placeholder, never a number read from git.
+try:
+    from hermes_cli._version import __version__  # type: ignore[import-not-found]
+except ImportError:
+    __version__ = "0.0.0"
+
 
 def _ensure_utf8():
     """Force UTF-8 stdout/stderr to prevent UnicodeEncodeError crashes.
diff --git a/tests/hermes_cli/test_version_resolution.py b/tests/hermes_cli/test_version_resolution.py
new file mode 100644
index 0000000000..a56558b5a2
--- /dev/null
+++ b/tests/hermes_cli/test_version_resolution.py
@@ -0,0 +1,35 @@
+"""The shipped version comes from a generated module, never from the tree.
+
+A checkout carries no version of its own: the release stamps ``hermes_cli/_version.py``
+into the build tree, and a tree without that file reports the placeholder.
+"""
+import subprocess
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+
+
+def _version_of(tree: Path) -> str:
+    env = {"PYTHONPATH": str(tree)}
+    script = "import hermes_cli; print(hermes_cli.__version__)"
+    out = subprocess.run([sys.executable, "-c", script], cwd=tree, env=env,
+                         capture_output=True, text=True, check=True)
+    return out.stdout.strip()
+
+
+def test_generated_module_wins(tmp_path):
+    cli = tmp_path / "hermes_cli"
+    cli.mkdir()
+    (cli / "__init__.py").write_text((REPO / "hermes_cli" / "__init__.py").read_text())
+    (cli / "_version.py").write_text('__version__ = "0.21.5"\n')
+
+    assert _version_of(tmp_path) == "0.21.5"
+
+
+def test_absent_generated_module_is_the_placeholder(tmp_path):
+    cli = tmp_path / "hermes_cli"
+    cli.mkdir()
+    (cli / "__init__.py").write_text((REPO / "hermes_cli" / "__init__.py").read_text())
+
+    assert _version_of(tmp_path) == "0.0.0"