conductor(checkpoint): Checkpoint end of Phase 1: Infrastructure & Core Utilities

api_hook_client.py

@@ -1,36 +1,69 @@
 import requests
 import json
+import time
 
 class ApiHookClient:
-    def __init__(self, base_url="http://127.0.0.1:8999"):
+    def __init__(self, base_url="http://127.0.0.1:8999", max_retries=3, retry_delay=1):
         self.base_url = base_url
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+    def wait_for_server(self, timeout=10):
+        """
+        Polls the /status endpoint until the server is ready or timeout is reached.
+        """
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                if self.get_status().get('status') == 'ok':
+                    return True
+            except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+                time.sleep(0.5)
+        return False
 
     def _make_request(self, method, endpoint, data=None):
         url = f"{self.base_url}{endpoint}"
         headers = {'Content-Type': 'application/json'}
         
-        try:
+        last_exception = None
-            if method == 'GET':
+        for attempt in range(self.max_retries + 1):
-                response = requests.get(url, timeout=1)
+            try:
-            elif method == 'POST':
+                if method == 'GET':
-                response = requests.post(url, json=data, headers=headers, timeout=1)
+                    response = requests.get(url, timeout=2)
-            else:
+                elif method == 'POST':
-                raise ValueError(f"Unsupported HTTP method: {method}")
+                    response = requests.post(url, json=data, headers=headers, timeout=2)
-            
+                else:
-            response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
+                    raise ValueError(f"Unsupported HTTP method: {method}")
-            return response.json()
+                
-        except requests.exceptions.Timeout:
+                response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
-            raise requests.exceptions.Timeout(f"Request to {endpoint} timed out.")
+                return response.json()
-        except requests.exceptions.ConnectionError:
+            except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
-            raise requests.exceptions.ConnectionError(f"Could not connect to API hook server at {self.base_url}.")
+                last_exception = e
-        except requests.exceptions.HTTPError as e:
+                if attempt < self.max_retries:
-            raise requests.exceptions.HTTPError(f"HTTP error {e.response.status_code} for {endpoint}: {e.response.text}")
+                    time.sleep(self.retry_delay)
-        except json.JSONDecodeError:
+                    continue
-            raise ValueError(f"Failed to decode JSON from response for {endpoint}: {response.text}")
+                else:
-
+                    if isinstance(e, requests.exceptions.Timeout):
+                        raise requests.exceptions.Timeout(f"Request to {endpoint} timed out after {self.max_retries} retries.") from e
+                    else:
+                        raise requests.exceptions.ConnectionError(f"Could not connect to API hook server at {self.base_url} after {self.max_retries} retries.") from e
+            except requests.exceptions.HTTPError as e:
+                raise requests.exceptions.HTTPError(f"HTTP error {e.response.status_code} for {endpoint}: {e.response.text}") from e
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Failed to decode JSON from response for {endpoint}: {response.text}") from e
+        
+        if last_exception:
+            raise last_exception
 
     def get_status(self):
-        return self._make_request('GET', '/status')
+        """Checks the health of the hook server."""
+        url = f"{self.base_url}/status"
+        try:
+            response = requests.get(url, timeout=1)
+            response.raise_for_status()
+            return response.json()
+        except Exception:
+            raise requests.exceptions.ConnectionError(f"Could not reach /status at {self.base_url}")
 
     def get_project(self):
         return self._make_request('GET', '/api/project')

conductor/workflow.md

@@ -128,11 +128,21 @@ For features involving the GUI or complex internal state, unit tests are often i
     ```powershell
     uv run python gui.py --enable-test-hooks
     ```
-2.  **Verify via REST Commands:** Use PowerShell or `curl` to send commands to the application and verify the response. For example, to check performance metrics:
+    This starts the hook server on port `8999`.
-    ```powershell
+
-    Invoke-RestMethod -Uri "http://localhost:5000/get_ui_performance" -Method Post
+2.  **Use the pytest `live_gui` Fixture:** For automated tests, use the session-scoped `live_gui` fixture defined in `tests/conftest.py`. This fixture handles the lifecycle (startup/shutdown) of the application with hooks enabled.
+    ```python
+    def test_my_feature(live_gui):
+        # The GUI is now running on port 8999
+        ...
+    ```
+
+3.  **Verify via ApiHookClient:** Use the `ApiHookClient` in `api_hook_client.py` to interact with the running application. It includes robust retry logic and health checks.
+
+4.  **Verify via REST Commands:** Use PowerShell or `curl` to send commands to the application and verify the response. For example, to check health:
+    ```powershell
+    Invoke-RestMethod -Uri "http://127.0.0.1:8999/status" -Method Get
     ```
-3.  **Automate in Tasks:** When a task requires "User Manual Verification" or "API Hook Verification", you should script these REST calls to ensure repeatable, objective results.
 
 ### Quality Gates
 

tests/conftest.py

@@ -0,0 +1,73 @@
+import pytest
+import subprocess
+import time
+import requests
+import os
+import signal
+
+def kill_process_tree(pid):
+    """Robustly kills a process and all its children."""
+    if pid is None:
+        return
+    try:
+        print(f"[Fixture] Attempting to kill process tree for PID {pid}...")
+        if os.name == 'nt':
+            # /F is force, /T is tree (includes children)
+            subprocess.run(["taskkill", "/F", "/T", "/PID", str(pid)], 
+                           stdout=subprocess.DEVNULL, 
+                           stderr=subprocess.DEVNULL, 
+                           check=False)
+        else:
+            # On Unix, kill the process group
+            os.killpg(os.getpgid(pid), signal.SIGKILL)
+        print(f"[Fixture] Process tree {pid} killed.")
+    except Exception as e:
+        print(f"[Fixture] Error killing process tree {pid}: {e}")
+
+@pytest.fixture(scope="session")
+def live_gui():
+    """
+    Session-scoped fixture that starts gui.py with --enable-test-hooks.
+    Ensures the GUI is running before tests start and shuts it down after.
+    """
+    print("\n[Fixture] Starting gui.py --enable-test-hooks...")
+    
+    # Start gui.py as a subprocess.
+    process = subprocess.Popen(
+        ["uv", "run", "python", "gui.py", "--enable-test-hooks"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if os.name == 'nt' else 0
+    )
+    
+    # Wait for the hook server to be ready (Port 8999 per api_hooks.py)
+    max_retries = 5
+    ready = False
+    print(f"[Fixture] Waiting up to {max_retries}s for Hook Server on port 8999...")
+    
+    start_time = time.time()
+    while time.time() - start_time < max_retries:
+        try:
+            # Using /status endpoint defined in HookHandler
+            response = requests.get("http://127.0.0.1:8999/status", timeout=0.5)
+            if response.status_code == 200:
+                ready = True
+                print(f"[Fixture] GUI Hook Server is ready after {round(time.time() - start_time, 2)}s.")
+                break
+        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+            if process.poll() is not None:
+                print("[Fixture] Process died unexpectedly during startup.")
+                break
+            time.sleep(0.5)
+            
+    if not ready:
+        print("[Fixture] TIMEOUT/FAILURE: Hook server failed to respond on port 8999 within 5s. Cleaning up...")
+        kill_process_tree(process.pid)
+        pytest.fail("Failed to start gui.py with test hooks within 5 seconds.")
+        
+    try:
+        yield process
+    finally:
+        print("\n[Fixture] Finally block triggered: Shutting down gui.py...")
+        kill_process_tree(process.pid)

tests/test_api_hook_client_enhanced.py

@@ -0,0 +1,28 @@
+import pytest
+import time
+import sys
+import os
+import requests
+
+# Ensure project root is in path
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from api_hook_client import ApiHookClient
+
+def test_client_wait_for_server(live_gui):
+    """Verifies that the client can wait for the server to become ready."""
+    client = ApiHookClient()
+    assert client.wait_for_server(timeout=5) is True
+
+def test_client_get_performance_retry(live_gui):
+    """Verifies that the client can retrieve metrics correctly."""
+    client = ApiHookClient()
+    perf = client.get_performance()
+    assert "performance" in perf
+
+def test_client_connection_error():
+    """Verifies that the client raises a Connection or Timeout error when the server is down."""
+    # Use a port that is unlikely to be in use and not intercepted
+    client = ApiHookClient(base_url="http://127.0.0.1:9998", max_retries=1, retry_delay=0.1)
+    with pytest.raises((requests.exceptions.ConnectionError, requests.exceptions.Timeout)):
+        client.get_project()

tests/test_gui_fixture_green.py

@@ -0,0 +1,21 @@
+import pytest
+import requests
+
+def test_gui_fixture_auto_starts(live_gui):
+    """
+    Verifies that the live_gui fixture correctly starts the GUI 
+    and the hook server is reachable on port 8999.
+    """
+    response = requests.get("http://127.0.0.1:8999/status")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "ok"
+
+def test_get_performance_metrics(live_gui):
+    """
+    Verifies that we can retrieve performance metrics via the hook server.
+    """
+    response = requests.get("http://127.0.0.1:8999/api/performance")
+    assert response.status_code == 200
+    data = response.json()
+    assert "performance" in data

tests/test_gui_fixture_red.py

@@ -0,0 +1,13 @@
+import pytest
+import subprocess
+import time
+import requests
+
+def test_gui_fixture_auto_starts():
+    # This test should fail if the fixture isn't working yet.
+    # It attempts to reach the hook server without starting it manually.
+    try:
+        response = requests.post("http://localhost:5000/get_ui_performance", json={})
+        assert response.status_code == 200
+    except requests.exceptions.ConnectionError:
+        pytest.fail("Hook server is not running. Fixture failed or is missing.")