fix(packaging): use direct CLI module entry point (#2665)

## Description

Corrects the packaged `headroom` console-script entry point so it loads
the concrete Click command from `headroom.cli.main:main` instead of
relying on the package-level `headroom.cli:main` re-export.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Updated `[project.scripts] headroom` in `pyproject.toml` from
`headroom.cli:main` to `headroom.cli.main:main`.

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`) - not needed for this
metadata-only packaging target change
- [ ] Type checking passes (`mypy headroom`) - not needed for this
metadata-only packaging target change
- [ ] New tests added for new functionality - not applicable; this
points the existing console script at the existing CLI command
- [x] Manual testing performed

### Test Output

```text
.\.venv\Scripts\python.exe -c "from importlib.metadata import EntryPoint; ep=EntryPoint(name='headroom', value='headroom.cli.main:main', group='console_scripts'); obj=ep.load(); import click; assert isinstance(obj, click.core.Command); print(obj.name)"
main

.\.venv\Scripts\python.exe -m headroom.cli --help
# exited successfully

.\.venv\Scripts\python.exe -m pytest tests/test_cli/test_main_help_version.py -q
5 passed
```

## Real Behavior Proof

- Environment: Windows checkout using the repository `.venv`.
- Exact command / steps: Loaded the proposed console-script entry point
with `importlib.metadata.EntryPoint`, verified it resolves to a Click
command, checked `python -m headroom.cli --help`, and ran the focused
CLI help/version tests.
- Observed result: `headroom.cli.main:main` resolves successfully to the
CLI command, module help still works, and the focused CLI tests pass.
- Not tested: rebuilding and installing a wheel from this branch; GitHub
package checks have not run because only governance checks are currently
present on the PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- not applicable for this one-line entry-point change
- [ ] I have made corresponding changes to the documentation - not
applicable; user-facing CLI behavior is unchanged
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works - existing CLI tests cover the command surface
- [x] New and existing relevant tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Screenshots (if applicable)

N/A - packaging entry-point change only.

## Additional Notes

This PR changes only the console-script target in `pyproject.toml`; it
does not change CLI behavior or command implementation.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2665"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: jd <jd@headroomlabs.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
LIghtJUNction
2026-11-04 08:27:36 -06:00
committed by GitHub
co-authored by JD Davis jd Devin AI
parent 5c8772b721
commit 2892214881
2 changed files with 91 additions and 1 deletions
+1 -1
View File
@@ -404,7 +404,7 @@ sandbox = [
]
[project.scripts]
headroom = "headroom.cli:main"
headroom = "headroom.cli.main:main"
headroom-cache-ttl = "headroom.cache.ttl_estimator:main"
[project.urls]
@@ -0,0 +1,90 @@
"""Regression tests for the packaged ``headroom`` console-script target."""
from __future__ import annotations
import subprocess
import sys
from importlib.metadata import EntryPoint, entry_points
from pathlib import Path
import click
import pytest
try:
import tomllib
except ModuleNotFoundError: # pragma: no cover
import tomli as tomllib # type: ignore[no-redef]
import headroom.cli
from headroom.cli.main import main
ROOT = Path(__file__).resolve().parents[2]
EXPECTED_TARGET = "headroom.cli.main:main"
LEGACY_TARGET = "headroom.cli:main"
def _declared_target() -> str:
pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
return pyproject["project"]["scripts"]["headroom"]
def _entry_point(value: str) -> EntryPoint:
return EntryPoint(name="headroom", value=value, group="console_scripts")
def test_pyproject_targets_defining_module_not_package_reexport() -> None:
ep = _entry_point(_declared_target())
assert ep.value == EXPECTED_TARGET
assert ep.module == main.callback.__module__
assert ep.attr == main.name
def test_declared_target_loads_root_click_command() -> None:
assert _entry_point(_declared_target()).load() is main
def test_declared_target_survives_submodule_shadowing_package_attr(
monkeypatch: pytest.MonkeyPatch,
) -> None:
# Re-importing ``headroom.cli.main`` rebinds the package attribute ``main``
# to the submodule, so the legacy package-level target stops being callable.
monkeypatch.setattr(headroom.cli, "main", sys.modules["headroom.cli.main"])
assert not isinstance(_entry_point(LEGACY_TARGET).load(), click.Command)
assert _entry_point(_declared_target()).load() is main
def test_declared_target_runs_in_fresh_interpreter() -> None:
script = (
"import sys\n"
"from importlib.metadata import EntryPoint\n"
f"ep = EntryPoint(name='headroom', value={_declared_target()!r}, "
"group='console_scripts')\n"
"sys.argv = ['headroom', '--version']\n"
"sys.exit(ep.load()())\n"
)
result = subprocess.run(
[sys.executable, "-c", script],
capture_output=True,
text=True,
timeout=120,
check=False,
)
assert result.returncode == 0, result.stderr
assert "headroom" in result.stdout.lower()
def test_installed_distribution_metadata_matches_pyproject() -> None:
installed = [
ep
for ep in entry_points(group="console_scripts", name="headroom")
if ep.dist is not None and ep.dist.name == "headroom-ai"
]
if not installed:
pytest.skip("headroom-ai distribution metadata is not installed")
assert installed[0].value == _declared_target(), (
"Installed console-script metadata is stale; reinstall headroom-ai"
)