fix: stage rust binaries in .claude/bin (#3027)

* fix: stage rust binaries in claude bin

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* [skip ci] chore: Auto-bump patch version

---------

Co-authored-by: Ubuntu <azureuser@devy.yb0a3bvkdghunmsjr4s3fnfhra.phxx.internal.cloudapp.net>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 4 people

.claude/bin/.gitkeep

@@ -0,0 +1 @@
+

build_hooks.py

@@ -2,8 +2,8 @@
 
 This module provides custom build hooks that copy directories from the repository
 root into src/amplihack/ before building the wheel. This ensures the framework
-files, plugin manifest, and bundle files are included in the wheel distribution
-for UVX deployment.
+files, plugin manifest, bundle files, and staged Rust binaries are included in
+the wheel distribution for UVX deployment.
 
 Why this is needed:
 - MANIFEST.in only controls sdist, not wheels
@@ -21,7 +21,9 @@
 so missing setuptools import at runtime is expected and not an error.
 """
 
+import os
 import shutil
+import stat
 from pathlib import Path
 
 from setuptools import build_meta as _orig
@@ -53,6 +55,7 @@ def __init__(self):
         self.skills_dest = pkg_root / "skills"
         self.agents_src = self.claude_src / "agents"
         self.agents_dest = pkg_root / "agents"
+        self.rust_binaries = ("amplihack", "amplihack-hooks")
 
     def _get_ignore_patterns(self):
         """Return common ignore patterns for directory copying."""
@@ -113,6 +116,52 @@ def _copy_claude_directory(self):
         """Copy .claude/ from repo root to src/amplihack/ if needed."""
         self._copy_plugin_directory(self.claude_src, self.claude_dest, ".claude/")
 
+    def _find_rust_binary(self, binary_name):
+        """Locate a Rust binary to stage into the wheel, if one is available."""
+        env_dir = os.environ.get("AMPLIHACK_RS_BIN_DIR")
+        candidates = []
+        if env_dir:
+            candidates.append(Path(env_dir) / binary_name)
+
+        sibling_target = self.repo_root.parent / "amplihack-rs" / "target"
+        candidates.extend([
+            sibling_target / "release" / binary_name,
+            sibling_target / "debug" / binary_name,
+            Path.home() / ".cargo" / "bin" / binary_name,
+        ])
+
+        on_path = shutil.which(binary_name)
+        if on_path:
+            candidates.append(Path(on_path))
+
+        for candidate in candidates:
+            expanded = candidate.expanduser()
+            if expanded.is_file() and os.access(expanded, os.X_OK):
+                return expanded
+        return None
+
+    def _copy_rust_binaries(self):
+        """Stage Rust CLI binaries into amplihack/.claude/bin when available."""
+        bin_dest = self.claude_dest / "bin"
+        bin_dest.mkdir(parents=True, exist_ok=True)
+
+        staged = 0
+        for binary_name in self.rust_binaries:
+            source = self._find_rust_binary(binary_name)
+            if source is None:
+                print(f"Info: {binary_name} not found for wheel staging")
+                continue
+
+            target = bin_dest / binary_name
+            print(f"Copying Rust binary {source} -> {target}")
+            shutil.copy2(source, target)
+            current_mode = target.stat().st_mode
+            target.chmod(current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+            staged += 1
+
+        if staged == 0:
+            print("Info: No Rust binaries staged; wheel will use Python-only packaging for binaries")
+
     def _copy_plugin_manifest(self):
         """Copy .claude-plugin/ from repo root to src/amplihack/ for wheel inclusion."""
         self._copy_plugin_directory(self.plugin_src, self.plugin_dest, ".claude-plugin/")
@@ -256,6 +305,7 @@ def build_wheel(self, wheel_directory, config_settings=None, metadata_directory=
         """Build wheel with .claude/, .claude-plugin/, .github/, amplifier-bundle/, AMPLIHACK.md, and CLAUDE.md included."""
         try:
             self._copy_claude_directory()
+            self._copy_rust_binaries()
             self._copy_plugin_manifest()
             self._copy_github_directory()
             self._copy_bundle_directory()

pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "amplihack"
-version = "0.6.20"
+version = "0.6.21"
 description = "Amplifier bundle for agentic coding with comprehensive skills, recipes, and workflows"
 requires-python = ">=3.11"
 dependencies = [

src/amplihack/__init__.py

@@ -65,6 +65,7 @@
 
 # Essential directories that must be copied during installation
 ESSENTIAL_DIRS = [
+    "bin",  # Staged Rust binaries (amplihack, amplihack-hooks)
     "agents/amplihack",  # Specialized agents
     "commands/amplihack",  # Slash commands
     "tools/amplihack",  # Hooks and utilities
@@ -214,4 +215,3 @@ def main():
     # Main
     "main",
 ]
-

src/amplihack/settings.py

@@ -142,26 +142,22 @@ def find_rust_hook_binary():
 
     Search order:
     1. PATH (via shutil.which)
-    2. ~/.amplihack/bin/amplihack-hooks
-    3. ~/.cargo/bin/amplihack-hooks
+    2. ~/.amplihack/.claude/bin/amplihack-hooks
+    3. ~/.amplihack/bin/amplihack-hooks (legacy)
+    4. ~/.cargo/bin/amplihack-hooks
 
     Returns:
         Absolute path to the binary, or None if not found.
     """
-    # 1. Check PATH
-    on_path = shutil.which("amplihack-hooks")
-    if on_path:
-        return os.path.abspath(on_path)
-
-    # 2. Check ~/.amplihack/bin/
-    amplihack_bin = os.path.expanduser("~/.amplihack/bin/amplihack-hooks")
-    if os.path.isfile(amplihack_bin) and os.access(amplihack_bin, os.X_OK):
-        return os.path.abspath(amplihack_bin)
-
-    # 3. Check ~/.cargo/bin/
-    cargo_bin = os.path.expanduser("~/.cargo/bin/amplihack-hooks")
-    if os.path.isfile(cargo_bin) and os.access(cargo_bin, os.X_OK):
-        return os.path.abspath(cargo_bin)
+    candidates = [
+        shutil.which("amplihack-hooks"),
+        os.path.expanduser("~/.amplihack/.claude/bin/amplihack-hooks"),
+        os.path.expanduser("~/.amplihack/bin/amplihack-hooks"),
+        os.path.expanduser("~/.cargo/bin/amplihack-hooks"),
+    ]
+    for candidate in candidates:
+        if candidate and os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return os.path.abspath(candidate)
 
     return None
 

tests/integration/test_cli_unified_staging.py

@@ -466,6 +466,25 @@ def test_copytree_manifest_overwrites_existing_files(self, tmp_path):
         result = (dst_context / "PHILOSOPHY.md").read_text()
         assert result == "# Updated Philosophy", f"File not overwritten. Got: {result}"
 
+    def test_copytree_manifest_copies_bin_directory(self, tmp_path):
+        """Rust binaries under .claude/bin should be staged into ~/.amplihack/.claude/bin."""
+        from src.amplihack.install import copytree_manifest
+
+        src_dir = tmp_path / "src"
+        bin_dir = src_dir / ".claude" / "bin"
+        bin_dir.mkdir(parents=True)
+        binary = bin_dir / "amplihack-hooks"
+        binary.write_text("#!/bin/sh\necho hooks\n")
+        binary.chmod(0o755)
+
+        dst_dir = tmp_path / "dst"
+        copied = copytree_manifest(str(src_dir), str(dst_dir), ".claude")
+
+        staged_binary = dst_dir / "bin" / "amplihack-hooks"
+        assert "bin" in copied
+        assert staged_binary.exists()
+        assert os.access(staged_binary, os.X_OK)
+
 
 class TestStagingE2EBehavior:
     """End-to-end tests for staging behavior with real subprocess calls (optional)."""
@@ -485,4 +504,6 @@ def test_real_staging_from_uvx_creates_files(self):
             assert (staging_dir / "agents").exists(), "agents/ directory missing after staging"
             assert (staging_dir / "skills").exists(), "skills/ directory missing after staging"
             assert (staging_dir / "tools").exists(), "tools/ directory missing after staging"
-            assert (staging_dir / "hooks").exists(), "hooks/ directory missing after staging"
+            assert (staging_dir / "tools" / "amplihack" / "hooks").exists(), (
+                "tools/amplihack/hooks directory missing after staging"
+            )

tests/test_rust_hook_engine.py

@@ -1,7 +1,7 @@
 """Tests for Rust hook engine registration (AMPLIHACK_HOOK_ENGINE=rust).
 
 Covers:
-- find_rust_hook_binary(): PATH lookup, ~/.amplihack/bin, ~/.cargo/bin
+- find_rust_hook_binary(): PATH lookup, ~/.amplihack/.claude/bin, legacy ~/.amplihack/bin, ~/.cargo/bin
 - get_hook_engine(): env var parsing
 - update_hook_paths() with hook_engine="rust": uses Rust binary, errors when missing
 - stage_hooks() with AMPLIHACK_HOOK_ENGINE=rust: generates Rust wrapper scripts
@@ -81,17 +81,31 @@ def test_finds_on_path(self, tmp_path):
             assert result is not None
             assert result.endswith("amplihack-hooks")
 
-    def test_finds_in_amplihack_bin(self, tmp_path):
+    def test_finds_in_staged_claude_bin(self, tmp_path):
+        bin_dir = tmp_path / ".amplihack" / ".claude" / "bin"
+        bin_dir.mkdir(parents=True)
+        binary = bin_dir / "amplihack-hooks"
+        binary.write_text("#!/bin/sh\necho test")
+        binary.chmod(0o755)
+
+        with patch("shutil.which", return_value=None):
+            with patch("os.path.expanduser", side_effect=lambda p: str(tmp_path / p.lstrip("~/"))):
+                result = find_rust_hook_binary()
+                assert result is not None
+                assert ".claude/bin" in result
+
+    def test_finds_in_legacy_amplihack_bin(self, tmp_path):
         bin_dir = tmp_path / ".amplihack" / "bin"
         bin_dir.mkdir(parents=True)
         binary = bin_dir / "amplihack-hooks"
         binary.write_text("#!/bin/sh\necho test")
         binary.chmod(0o755)
 
         with patch("shutil.which", return_value=None):
-            with patch("os.path.expanduser", side_effect=lambda p: str(tmp_path / p.lstrip("~/")))  :
+            with patch("os.path.expanduser", side_effect=lambda p: str(tmp_path / p.lstrip("~/"))):
                 result = find_rust_hook_binary()
                 assert result is not None
+                assert "/.amplihack/bin/" in result
 
     def test_finds_in_cargo_bin(self, tmp_path):
         cargo_dir = tmp_path / ".cargo" / "bin"
@@ -105,13 +119,19 @@ def test_finds_in_cargo_bin(self, tmp_path):
                 result = find_rust_hook_binary()
                 assert result is not None
 
-    def test_amplihack_bin_takes_priority_over_cargo_bin(self, tmp_path):
-        """~/.amplihack/bin should win over ~/.cargo/bin."""
-        amplihack_dir = tmp_path / ".amplihack" / "bin"
-        amplihack_dir.mkdir(parents=True)
-        amplihack_binary = amplihack_dir / "amplihack-hooks"
-        amplihack_binary.write_text("#!/bin/sh\necho amplihack")
-        amplihack_binary.chmod(0o755)
+    def test_staged_bin_takes_priority_over_legacy_and_cargo_bin(self, tmp_path):
+        """~/.amplihack/.claude/bin should win over legacy ~/.amplihack/bin and ~/.cargo/bin."""
+        staged_dir = tmp_path / ".amplihack" / ".claude" / "bin"
+        staged_dir.mkdir(parents=True)
+        staged_binary = staged_dir / "amplihack-hooks"
+        staged_binary.write_text("#!/bin/sh\necho staged")
+        staged_binary.chmod(0o755)
+
+        legacy_dir = tmp_path / ".amplihack" / "bin"
+        legacy_dir.mkdir(parents=True)
+        legacy_binary = legacy_dir / "amplihack-hooks"
+        legacy_binary.write_text("#!/bin/sh\necho legacy")
+        legacy_binary.chmod(0o755)
 
         cargo_dir = tmp_path / ".cargo" / "bin"
         cargo_dir.mkdir(parents=True)
@@ -123,12 +143,12 @@ def test_amplihack_bin_takes_priority_over_cargo_bin(self, tmp_path):
             with patch("os.path.expanduser", side_effect=lambda p: str(tmp_path / p.lstrip("~/"))):
                 result = find_rust_hook_binary()
                 assert result is not None
-                assert ".amplihack" in result
+                assert ".amplihack/.claude/bin" in result
                 assert ".cargo" not in result
 
     def test_non_executable_file_skipped(self, tmp_path):
-        """A non-executable file at ~/.amplihack/bin/amplihack-hooks should be skipped."""
-        bin_dir = tmp_path / ".amplihack" / "bin"
+        """A non-executable file at ~/.amplihack/.claude/bin/amplihack-hooks should be skipped."""
+        bin_dir = tmp_path / ".amplihack" / ".claude" / "bin"
         bin_dir.mkdir(parents=True)
         binary = bin_dir / "amplihack-hooks"
         binary.write_text("#!/bin/sh\necho test")

tests/test_wheel_packaging.py

@@ -5,7 +5,9 @@
 ensuring it's available in UVX deployments.
 """
 
+import os
 import subprocess
+import sys
 import tempfile
 import zipfile
 from pathlib import Path
@@ -18,13 +20,15 @@ def test_wheel_includes_claude_directory():
     # Build wheel in temporary directory
     with tempfile.TemporaryDirectory() as tmpdir:
         wheel_dir = Path(tmpdir)
+        repo_root = Path(__file__).parent.parent
 
         # Build wheel using pyproject-build
         result = subprocess.run(
-            ["python", "-m", "build", "--wheel", "--outdir", str(wheel_dir)],
+            [sys.executable, "-m", "build", "--wheel", "--no-isolation", "--outdir", str(wheel_dir)],
             capture_output=True,
             text=True,
             timeout=120,
+            cwd=repo_root,
         )
 
         # Check build succeeded
@@ -49,6 +53,7 @@ def test_wheel_includes_claude_directory():
             # Verify key files are present
             required_files = [
                 "amplihack/.claude/.version",
+                "amplihack/.claude/bin/.gitkeep",
                 "amplihack/.claude/settings.json",
                 "amplihack/.claude/__init__.py",
             ]
@@ -64,7 +69,7 @@ def test_wheel_includes_claude_directory():
                 "amplihack/.claude/commands/",
                 "amplihack/.claude/context/",
                 "amplihack/.claude/skills/",
-                "amplihack/.claude/workflows/",
+                "amplihack/.claude/workflow/",
             ]
 
             for required_dir in required_dirs:
@@ -80,6 +85,43 @@ def test_wheel_includes_claude_directory():
             )
 
 
+def test_wheel_includes_rust_binaries_when_staged(tmp_path):
+    """Wheel build should include staged Rust binaries when AMPLIHACK_RS_BIN_DIR is set."""
+    rust_bin_dir = tmp_path / "rust-bin"
+    rust_bin_dir.mkdir()
+    for binary_name in ("amplihack", "amplihack-hooks"):
+        binary = rust_bin_dir / binary_name
+        binary.write_text("#!/bin/sh\necho staged\n")
+        binary.chmod(0o755)
+
+    wheel_dir = tmp_path / "wheel"
+    wheel_dir.mkdir()
+    repo_root = Path(__file__).parent.parent
+
+    env = os.environ.copy()
+    env["AMPLIHACK_RS_BIN_DIR"] = str(rust_bin_dir)
+
+    result = subprocess.run(
+        [sys.executable, "-m", "build", "--wheel", "--no-isolation", "--outdir", str(wheel_dir)],
+        capture_output=True,
+        text=True,
+        timeout=120,
+        env=env,
+        cwd=repo_root,
+    )
+
+    if result.returncode != 0:
+        pytest.fail(f"Wheel build failed:\nstdout: {result.stdout}\nstderr: {result.stderr}")
+
+    wheels = list(wheel_dir.glob("*.whl"))
+    assert len(wheels) == 1, f"Expected 1 wheel, found {len(wheels)}"
+
+    with zipfile.ZipFile(wheels[0], "r") as zf:
+        file_list = zf.namelist()
+        assert "amplihack/.claude/bin/amplihack" in file_list
+        assert "amplihack/.claude/bin/amplihack-hooks" in file_list
+
+
 def test_build_hooks_cleanup():
     """Test that build_hooks.py cleans up .claude/ from src/amplihack/ after build."""
     # Path to .claude/ inside package (should not exist after build)
@@ -106,5 +148,12 @@ def test_claude_directory_exists_at_repo_root():
         assert subdir_path.exists(), f"Required subdirectory {subdir} not found"
 
 
+def test_essential_dirs_include_bin():
+    """UVX staging must include .claude/bin for Rust binary deployment."""
+    from amplihack import ESSENTIAL_DIRS
+
+    assert "bin" in ESSENTIAL_DIRS
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])