refactor(graph): drop the bespoke codebase-memory-mcp downloader nothing calls

headroom wrap stopped calling ensure_cbm() in dca9853e (#1230), when
tokensave and Serena replaced codebase-memory-mcp. Since then the only
product user of graph/installer.py is the code-graph watcher, which
calls get_cbm_path(). The download path (download_cbm, ensure_cbm and
their platform/asset/zip helpers) duplicated headroom.binaries and was
kept alive only by its tests. Keep get_cbm_path and _installed_name;
remove the rest and the tests that exercised it.

Evidence: grep -rnw for download_cbm, ensure_cbm and the removed helpers
and constants across headroom, crates, plugins, sdk, docs, wiki,
scripts, benchmarks, examples, e2e, .github and the consumer repos finds
only installer.py and tests. The module has no __all__ and is not
re-exported or documented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-09 18:02:48 -07:00
co-authored by Claude Opus 5.5
parent a9815bbb5f
commit 0cbd67d625
6 changed files with 16 additions and 473 deletions
+5 -153
View File
@@ -1,74 +1,20 @@
"""Download and install codebase-memory-mcp binary from GitHub releases."""
"""Locate the codebase-memory-mcp binary used by the code-graph watcher.
The binary is looked up on PATH, then in ``~/.local/bin``.
"""
from __future__ import annotations
import io
import logging
import platform
import shutil
import stat
import tarfile
import zipfile
from pathlib import Path
from urllib.request import urlopen
from headroom.offline import guard_egress
logger = logging.getLogger(__name__)
CBM_VERSION = "v0.8.1"
CBM_REPO = "DeusData/codebase-memory-mcp"
CBM_BIN_DIR = Path.home() / ".local" / "bin"
CBM_BIN_NAME = "codebase-memory-mcp"
GITHUB_RELEASE_URL = f"https://github.com/{CBM_REPO}/releases/download"
def _detect_platform() -> str:
"""Detect platform and return the release asset suffix."""
system = platform.system().lower()
machine = platform.machine().lower()
if system == "darwin":
arch = "arm64" if machine == "arm64" else "amd64"
return f"darwin-{arch}"
elif system == "linux":
arch = "arm64" if machine in ("aarch64", "arm64") else "amd64"
return f"linux-{arch}"
elif system == "windows":
return "windows-amd64"
raise RuntimeError(f"Unsupported platform: {system} {machine}")
def _asset_filename(plat: str) -> str:
"""Return the release asset name for ``plat``, with the extension tools.json pins.
Upstream publishes a .zip for Windows and a .tar.gz for every other platform.
"""
from headroom.binaries import _tool_entry
stem = f"codebase-memory-mcp-{plat}"
for asset in _tool_entry("codebase-memory-mcp").get("assets", {}).values():
name = str(asset.get("url", "")).rsplit("/", 1)[-1]
if name in (f"{stem}.tar.gz", f"{stem}.zip"):
return name
return f"{stem}.tar.gz"
def _extract_from_zip(data: bytes, target_path: Path) -> None:
"""Write the binary member of a .zip release archive to ``target_path``."""
wanted = (CBM_BIN_NAME, f"{CBM_BIN_NAME}.exe")
with zipfile.ZipFile(io.BytesIO(data)) as archive:
for info in archive.infolist():
if not info.is_dir() and info.filename.rsplit("/", 1)[-1] in wanted:
target_path.write_bytes(archive.read(info))
return
raise RuntimeError("codebase-memory-mcp binary not found in archive")
def _installed_name(plat: str) -> str:
"""Return the file name to install the binary under for ``plat``.
"""Return the binary's file name on ``plat``.
On Windows, ``shutil.which`` (and so a PATH lookup) only finds a binary
whose name ends in a PATHEXT extension such as ``.exe``.
@@ -89,97 +35,3 @@ def get_cbm_path() -> Path | None:
return installed
return None
def download_cbm(version: str | None = None) -> Path:
"""Download codebase-memory-mcp binary from GitHub releases.
Returns path to installed binary.
"""
version = version or CBM_VERSION
plat = _detect_platform()
filename = _asset_filename(plat)
url = f"{GITHUB_RELEASE_URL}/{version}/{filename}"
guard_egress("codebase-memory-mcp binary download", url)
CBM_BIN_DIR.mkdir(parents=True, exist_ok=True)
target_path = CBM_BIN_DIR / _installed_name(plat)
logger.info("Downloading codebase-memory-mcp %s for %s ...", version, plat)
try:
if not url.startswith(("http://", "https://")):
raise ValueError(f"Invalid URL: {url}")
with urlopen(url, timeout=60) as response: # noqa: S310
data = response.read()
except Exception as e:
raise RuntimeError(f"Failed to download codebase-memory-mcp from {url}: {e}") from e
from headroom.binaries import verify_download_bytes
verify_download_bytes(data, url=url, name="codebase-memory-mcp")
# Extract binary from the .zip (Windows) or .tar.gz (everything else)
try:
if filename.endswith(".zip"):
_extract_from_zip(data, target_path)
else:
with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
for member in tar.getmembers():
if member.name.endswith(CBM_BIN_NAME) or member.name == CBM_BIN_NAME:
member.name = target_path.name
tar.extract(member, CBM_BIN_DIR, filter="data")
break
else:
raise RuntimeError("codebase-memory-mcp binary not found in archive")
except (tarfile.TarError, zipfile.BadZipFile) as e:
raise RuntimeError(f"Failed to extract archive: {e}") from e
# Make executable
target_path.chmod(target_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
# Verify
try:
from headroom._subprocess import run
result = run(
[str(target_path), "--version"],
capture_output=True,
text=True,
)
if result.returncode == 0:
ver = result.stdout.strip()
logger.info("Installed: %s", ver)
else:
logger.warning("Binary installed but version check failed")
except Exception:
pass
return target_path
def ensure_cbm() -> Path | None:
"""Ensure codebase-memory-mcp is available. Download if needed.
Returns path to binary, or None if download failed.
"""
existing = get_cbm_path()
if existing:
return existing
# Local import to match this module's lazy-import style (see download_cbm).
from headroom.binaries import UnpinnedDownload
try:
return download_cbm()
except RuntimeError as e:
logger.warning("Failed to install codebase-memory-mcp: %s", e)
return None
except UnpinnedDownload as e:
# Documented contract is "path, or None if the download failed", and a
# refusal is a failure to install -- the feature is simply unavailable.
# Deliberately NOT widened to BinaryError: Sha256Mismatch is a tamper
# signal and must keep propagating rather than becoming a quiet None.
logger.warning("Refusing to install codebase-memory-mcp: %s", e)
return None
+1 -1
View File
@@ -8,7 +8,7 @@ deployment exists to carry.
Refused (this is not a sample — it is the rule, and the meta-test enforces it):
the telemetry beacon, the update check, the license/usage reporter, OTLP and
Langfuse export, HuggingFace/Kompress/fastembed model downloads, release-binary
and codebase-memory-mcp downloads, eval dataset downloads and the provider SDK
downloads (codebase-memory-mcp among them), eval dataset downloads and the provider SDK
clients the eval harness drives, GitHub Copilot device-flow auth and token
exchange, the Anthropic / Codex / Copilot subscription pollers, the OpenAI
embedders, both Headroom Cloud compression integrations, and the TLS
@@ -59,39 +59,6 @@ def test_tools_install_keeps_going_and_still_sets_an_exit_code(_refuse) -> None:
assert result.exit_code == 1, result.output
def test_ensure_cbm_honours_its_documented_none_contract(monkeypatch) -> None:
"""`ensure_cbm` promises "path, or None if the download failed"."""
from headroom.graph import installer
monkeypatch.setattr(installer, "get_cbm_path", lambda: None)
def _raise():
raise binaries.UnpinnedDownload("refusing unpinned download codebase-memory-mcp")
monkeypatch.setattr(installer, "download_cbm", _raise)
assert installer.ensure_cbm() is None
def test_a_tamper_signal_still_propagates_from_ensure_cbm(monkeypatch) -> None:
"""The None contract must not swallow a sha256 mismatch.
An unpinned asset is a misconfiguration; a mismatch is evidence of tampering
and has to stay loud rather than becoming a quiet "feature unavailable".
"""
from headroom.graph import installer
monkeypatch.setattr(installer, "get_cbm_path", lambda: None)
def _raise():
raise binaries.Sha256Mismatch("sha256 mismatch for codebase-memory-mcp")
monkeypatch.setattr(installer, "download_cbm", _raise)
with pytest.raises(binaries.Sha256Mismatch):
installer.ensure_cbm()
def test_the_escape_hatch_warning_is_not_printed_twice(monkeypatch, capsys) -> None:
"""With no handlers configured, logging's lastResort already writes stderr.
-154
View File
@@ -1,65 +1,13 @@
from __future__ import annotations
import io
import json
import subprocess
import tarfile
from pathlib import Path
from types import ModuleType, SimpleNamespace
import pytest
from headroom.graph import installer, watcher
def _build_archive(member_name: str = installer.CBM_BIN_NAME) -> bytes:
payload = io.BytesIO()
with tarfile.open(fileobj=payload, mode="w:gz") as tar:
data = b"#!/bin/sh\necho version\n"
info = tarfile.TarInfo(name=member_name)
info.size = len(data)
tar.addfile(info, io.BytesIO(data))
return payload.getvalue()
class FakeResponse:
def __init__(self, data: bytes) -> None:
self._data = data
def __enter__(self):
return self
def __exit__(self, exc_type, exc, tb) -> None:
return None
def read(self) -> bytes:
return self._data
@pytest.mark.parametrize(
("system", "machine", "expected"),
[
("Darwin", "arm64", "darwin-arm64"),
("Darwin", "x86_64", "darwin-amd64"),
("Linux", "aarch64", "linux-arm64"),
("Linux", "arm64", "linux-arm64"),
("Linux", "x86_64", "linux-amd64"),
("Windows", "AMD64", "windows-amd64"),
],
)
def test_detect_platform_variants(monkeypatch, system: str, machine: str, expected: str) -> None:
monkeypatch.setattr(installer.platform, "system", lambda: system)
monkeypatch.setattr(installer.platform, "machine", lambda: machine)
assert installer._detect_platform() == expected
def test_detect_platform_rejects_unknown_system(monkeypatch) -> None:
monkeypatch.setattr(installer.platform, "system", lambda: "Solaris")
monkeypatch.setattr(installer.platform, "machine", lambda: "sparc")
with pytest.raises(RuntimeError, match="Unsupported platform"):
installer._detect_platform()
def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path) -> None:
on_path = tmp_path / "on-path"
installed = tmp_path / installer.CBM_BIN_NAME
@@ -76,108 +24,6 @@ def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path)
assert installer.get_cbm_path() is None
def test_download_cbm_success_and_verification_paths(monkeypatch, tmp_path: Path) -> None:
# v1.2.3 is not in the registry and the mock archive would not match a pin
# anyway; this test is about the install mechanics, not verification.
monkeypatch.setenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", "1")
monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
monkeypatch.setattr(
installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())
)
run_calls: list[list[str]] = []
def fake_run(command, **kwargs):
run_calls.append(command)
return SimpleNamespace(returncode=1, stdout="")
monkeypatch.setattr("subprocess.run", fake_run)
path = installer.download_cbm(version="v1.2.3")
assert path == tmp_path / installer.CBM_BIN_NAME
assert path.exists()
assert run_calls == [[str(path), "--version"]]
monkeypatch.setattr(
"subprocess.run", lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom"))
)
assert installer.download_cbm(version="v1.2.3") == path
monkeypatch.setattr(
"subprocess.run",
lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout="cbm v1.2.3\n"),
)
assert installer.download_cbm(version="v1.2.3") == path
def test_download_cbm_invalid_url_download_failure_and_extract_errors(
monkeypatch, tmp_path: Path
) -> None:
# These failure modes are reached with an overridden (off-registry) release
# host, so verification would refuse them before the code under test runs.
monkeypatch.setenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", "1")
monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "ftp://example.test/releases")
with pytest.raises(RuntimeError, match="Invalid URL"):
installer.download_cbm()
monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "https://example.test/releases")
monkeypatch.setattr(
installer,
"urlopen",
lambda url, timeout=60: (_ for _ in ()).throw(OSError("network down")),
)
with pytest.raises(RuntimeError, match="Failed to download codebase-memory-mcp"):
installer.download_cbm()
monkeypatch.setattr(
installer,
"urlopen",
lambda url, timeout=60: FakeResponse(_build_archive("some/other-binary")),
)
with pytest.raises(RuntimeError, match="binary not found in archive"):
installer.download_cbm()
monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a tar"))
with pytest.raises(RuntimeError, match="Failed to extract archive"):
installer.download_cbm()
def test_download_cbm_refuses_an_off_registry_version(monkeypatch, tmp_path: Path) -> None:
"""A version override points at a URL with no pin — refuse it (A-7).
The default CBM_VERSION is pinned for every platform in tools.json, so only
an override reaches this path.
"""
from headroom import binaries
monkeypatch.delenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", raising=False)
monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
monkeypatch.setattr(
installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())
)
with pytest.raises(binaries.BinaryError) as exc:
installer.download_cbm(version="v9.9.9")
assert type(exc.value) is binaries.UnpinnedDownload
assert not (tmp_path / installer.CBM_BIN_NAME).exists()
def test_ensure_cbm_uses_existing_or_returns_none_on_failure(monkeypatch, tmp_path: Path) -> None:
existing = tmp_path / installer.CBM_BIN_NAME
monkeypatch.setattr(installer, "get_cbm_path", lambda: existing)
assert installer.ensure_cbm() == existing
monkeypatch.setattr(installer, "get_cbm_path", lambda: None)
monkeypatch.setattr(
installer, "download_cbm", lambda: (_ for _ in ()).throw(RuntimeError("nope"))
)
assert installer.ensure_cbm() is None
def test_code_graph_watcher_init_start_stop_and_event_filtering(
monkeypatch, tmp_path: Path
) -> None:
+9 -124
View File
@@ -1,132 +1,33 @@
"""Release asset selection and extraction for the codebase-memory-mcp installer."""
"""Locating the codebase-memory-mcp binary for the code-graph watcher."""
from __future__ import annotations
import io
import platform
import shutil
import tarfile
import zipfile
import stat
from pathlib import Path
from types import SimpleNamespace
import pytest
from headroom import binaries
from headroom.graph import installer
class FakeResponse(io.BytesIO):
def __enter__(self):
return self
def __exit__(self, exc_type, exc, tb) -> None:
return None
def _zip_archive(member_name: str, data: bytes = b"MZ fake binary") -> bytes:
payload = io.BytesIO()
with zipfile.ZipFile(payload, "w") as archive:
archive.writestr(member_name, data)
return payload.getvalue()
@pytest.mark.parametrize(
("plat", "extension"),
[
("darwin-arm64", ".tar.gz"),
("darwin-amd64", ".tar.gz"),
("linux-arm64", ".tar.gz"),
("linux-amd64", ".tar.gz"),
("windows-amd64", ".zip"),
],
)
def test_asset_filename_matches_the_registry_asset(plat: str, extension: str) -> None:
filename = installer._asset_filename(plat)
assert filename == f"codebase-memory-mcp-{plat}{extension}"
pinned_urls = {
asset["url"] for asset in binaries._tool_entry("codebase-memory-mcp")["assets"].values()
}
assert f"{installer.GITHUB_RELEASE_URL}/{installer.CBM_VERSION}/{filename}" in pinned_urls
@pytest.mark.parametrize("member_name", ["codebase-memory-mcp.exe", "codebase-memory-mcp"])
def test_download_cbm_on_windows_fetches_and_extracts_the_zip(
monkeypatch, tmp_path: Path, member_name: str
) -> None:
monkeypatch.setenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", "1")
monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
monkeypatch.setattr(installer, "_detect_platform", lambda: "windows-amd64")
requested: list[str] = []
def fake_urlopen(url: str, timeout: int = 60) -> FakeResponse:
requested.append(url)
return FakeResponse(_zip_archive(member_name))
monkeypatch.setattr(installer, "urlopen", fake_urlopen)
probes: list[list[str]] = []
def fake_run(command: list[str], **kwargs) -> SimpleNamespace:
probes.append(command)
return SimpleNamespace(returncode=1, stdout="")
monkeypatch.setattr("headroom._subprocess.run", fake_run)
path = installer.download_cbm()
assert requested == [
f"{installer.GITHUB_RELEASE_URL}/{installer.CBM_VERSION}/"
"codebase-memory-mcp-windows-amd64.zip"
]
# A PATH lookup on Windows only finds the binary through its .exe extension.
assert path == tmp_path / "codebase-memory-mcp.exe"
assert path.read_bytes() == b"MZ fake binary"
assert probes == [[str(path), "--version"]]
def _host_release_archive(filename: str) -> bytes:
"""Build a release archive in the format ``download_cbm`` requests on this host."""
if filename.endswith(".zip"):
return _zip_archive("codebase-memory-mcp.exe")
payload = io.BytesIO()
with tarfile.open(fileobj=payload, mode="w:gz") as tar:
data = b"#!/bin/sh\necho codebase-memory-mcp test\n"
info = tarfile.TarInfo(name="codebase-memory-mcp")
info.size = len(data)
tar.addfile(info, io.BytesIO(data))
return payload.getvalue()
def test_installed_binary_is_found_by_a_real_path_lookup(monkeypatch, tmp_path: Path) -> None:
"""The installed file must be what ``shutil.which`` resolves on this host.
"""A binary named the way ``get_cbm_path`` expects must be what
``shutil.which`` resolves on this host.
Nothing about the file name is mocked: on Windows this needs the .exe
extension, elsewhere the extensionless name with its executable bit.
"""
bin_dir = tmp_path / "bin"
monkeypatch.setenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", "1")
bin_dir.mkdir()
path = bin_dir / installer._installed_name(platform.system().lower())
path.write_bytes(b"#!/bin/sh\necho codebase-memory-mcp test\n")
path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
monkeypatch.setattr(installer, "CBM_BIN_DIR", bin_dir)
monkeypatch.setattr(
installer,
"urlopen",
lambda url, timeout=60: FakeResponse(_host_release_archive(url.rsplit("/", 1)[-1])),
)
probes: list[list[str]] = []
def fake_run(command: list[str], **kwargs) -> SimpleNamespace:
probes.append(command)
return SimpleNamespace(returncode=1, stdout="")
monkeypatch.setattr("headroom._subprocess.run", fake_run)
path = installer.download_cbm()
assert probes == [[str(path), "--version"]]
monkeypatch.setenv("PATH", str(bin_dir))
found = shutil.which("codebase-memory-mcp")
assert found is not None
assert Path(found).samefile(path)
assert Path(probes[0][0]).samefile(found)
assert installer.get_cbm_path() == Path(found)
@@ -146,19 +47,3 @@ def test_get_cbm_path_finds_the_installed_binary_off_path(monkeypatch, tmp_path:
assert installer.get_cbm_path() is None
(bin_dir / "codebase-memory-mcp").write_bytes(b"#!/bin/sh\n")
assert installer.get_cbm_path() == bin_dir / "codebase-memory-mcp"
def test_download_cbm_zip_errors(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setenv("HEADROOM_BINARIES_ALLOW_UNVERIFIED", "1")
monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
monkeypatch.setattr(installer, "_detect_platform", lambda: "windows-amd64")
monkeypatch.setattr(
installer, "urlopen", lambda url, timeout=60: FakeResponse(_zip_archive("README.md"))
)
with pytest.raises(RuntimeError, match="binary not found in archive"):
installer.download_cbm()
monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a zip"))
with pytest.raises(RuntimeError, match="Failed to extract archive"):
installer.download_cbm()
+1 -8
View File
@@ -1698,7 +1698,7 @@ class TestDoctorNetworkOffline:
class TestInstallDownloadsOffline:
"""`headroom install`'s two release downloads.
"""`headroom install`'s release download.
`binaries.py` already had `HEADROOM_BINARIES_OFFLINE`, which is exactly the
kind of second, differently-named flag an operator should not have to
@@ -1718,13 +1718,6 @@ class TestInstallDownloadsOffline:
)
assert _refused_hostname(excinfo.value) == "github.com"
def test_cbm_download_opens_no_socket(self, offline: None, no_sockets: None) -> None:
from headroom.graph import installer
with pytest.raises(OfflineEgressBlocked) as excinfo:
installer.download_cbm()
assert "HEADROOM_OFFLINE" in str(excinfo.value)
def test_the_binaries_specific_switch_still_wins_first(
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None: