Improve error handling for misconfigured hcatPath

- Add directory existence check in ensure_binary() before attempting make
- Provide clear error message when build directory doesn't exist
- Add troubleshooting section to README.md explaining common hcatPath mistakes
- Add tests for invalid hcatPath scenario and installed tool execution
- Helps users distinguish between hashcat path and hate_crack path

Fixes issue where users set hcatPath to hashcat installation directory
instead of hate_crack repository directory, causing confusing errors.

README.md

@@ -149,6 +149,50 @@ You can also use Python directly:
 python hate_crack.py
 ```
 
+-------------------------------------------------------------------
+## Troubleshooting
+
+### Error: Build directory does not exist
+
+If you see an error like:
+```
+Error: Build directory /opt/hashcat/hashcat-utils does not exist.
+Expected to find expander at /opt/hashcat/hashcat-utils/bin/expander.
+```
+
+This means your `hcatPath` in `config.json` is pointing to the wrong directory. The `hcatPath` should point to the **hate_crack repository directory** (which contains `hashcat-utils/` and `princeprocessor/` subdirectories), not the hashcat installation directory.
+
+**Incorrect config.json:**
+```json
+{
+  "hcatPath": "/opt/hashcat",  ❌ Wrong - this is hashcat, not hate_crack
+  ...
+}
+```
+
+**Correct config.json:**
+```json
+{
+  "hcatPath": "/opt/hate_crack",  ✓ Correct - points to hate_crack repo
+  ...
+}
+```
+
+Or use the home directory path:
+```json
+{
+  "hcatPath": "~/hate_crack",  ✓ Also correct
+  ...
+}
+```
+
+The tool will automatically search for assets in:
+1. The `hcatPath` specified in config.json
+2. Environment variables `HATE_CRACK_HOME` or `HATE_CRACK_ASSETS`
+3. Current working directory and parent directory
+4. `~/hate_crack`, `~/hate-crack`, or `~/.hate_crack`
+
+-------------------------------------------------------------------
 ### Makefile helpers
 Install OS dependencies + tool (auto-detects macOS vs Debian/Ubuntu):
 

hate_crack/main.py

@@ -171,6 +171,16 @@ if not logger.handlers:
 def ensure_binary(binary_path, build_dir=None, name=None):
     if not os.path.isfile(binary_path) or not os.access(binary_path, os.X_OK):
         if build_dir:
+            if not os.path.isdir(build_dir):
+                print(f'Error: Build directory {build_dir} does not exist.')
+                print(f'Expected to find {name or "binary"} at {binary_path}.')
+                print('\nThe hcatPath in your config.json may be incorrect.')
+                print('Please ensure hcatPath points to the hate_crack repository directory')
+                print('that contains hashcat-utils/ and princeprocessor/ subdirectories.')
+                print('\nExample config.json:')
+                print('  "hcatPath": "/opt/hate_crack"  (or ~/hate_crack)')
+                quit(1)
+            
             print(f'Attempting to build {name or binary_path} via make in {build_dir}...')
             try:
                 subprocess.run(['make'], cwd=build_dir, check=True)

tests/test_installed_tool_execution.py

@@ -0,0 +1,157 @@
+"""
+Tests for hate_crack execution when installed as a uv tool.
+Verifies that the tool can find assets from any working directory.
+"""
+import subprocess
+import os
+import tempfile
+import shutil
+import pytest
+
+
+@pytest.mark.skipif(
+    not shutil.which("hate_crack"),
+    reason="hate_crack not installed as a tool (run 'make install' first)"
+)
+class TestInstalledToolExecution:
+    """Test suite for execution of installed hate_crack tool."""
+
+    def test_help_from_home_directory(self):
+        """Test that --help works when run from home directory."""
+        home_dir = os.path.expanduser("~")
+        result = subprocess.run(
+            ["hate_crack", "--help"],
+            cwd=home_dir,
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        assert result.returncode == 0
+        assert "usage: hate_crack" in result.stdout
+        assert "Hashcat automation and wordlist management tool" in result.stdout
+
+    def test_help_from_tmp_directory(self):
+        """Test that --help works when run from /tmp directory."""
+        result = subprocess.run(
+            ["hate_crack", "--help"],
+            cwd="/tmp",
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        assert result.returncode == 0
+        assert "usage: hate_crack" in result.stdout
+
+    def test_help_from_temporary_directory(self):
+        """Test that --help works when run from a temporary directory."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = subprocess.run(
+                ["hate_crack", "--help"],
+                cwd=tmpdir,
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            assert result.returncode == 0
+            assert "usage: hate_crack" in result.stdout
+
+    def test_help_from_root_directory(self):
+        """Test that --help works when run from root directory."""
+        result = subprocess.run(
+            ["hate_crack", "--help"],
+            cwd="/",
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        assert result.returncode == 0
+        assert "usage: hate_crack" in result.stdout
+
+    def test_debug_flag_from_home_directory(self):
+        """Test that --debug flag works from home directory."""
+        home_dir = os.path.expanduser("~")
+        result = subprocess.run(
+            ["hate_crack", "--debug", "--help"],
+            cwd=home_dir,
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        assert result.returncode == 0
+        assert "usage: hate_crack" in result.stdout
+
+    def test_no_errors_on_startup_from_home(self):
+        """Test that there are no error messages on startup from home."""
+        home_dir = os.path.expanduser("~")
+        result = subprocess.run(
+            ["hate_crack", "--help"],
+            cwd=home_dir,
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        assert result.returncode == 0
+        # Check that there are no error-related messages
+        assert "Error" not in result.stderr
+        assert "error" not in result.stdout.lower() or "error" in "usage"  # "usage" might contain substring
+        assert "not found" not in result.stderr.lower()
+        assert "No such file" not in result.stderr
+
+    def test_tool_creates_config_on_first_run(self):
+        """Test that tool can run from non-repo directory (config already exists)."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Run from temp directory (not a repo)
+            result = subprocess.run(
+                ["hate_crack", "--help"],
+                cwd=tmpdir,
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            assert result.returncode == 0
+            # Should successfully show help without errors
+            assert "usage: hate_crack" in result.stdout
+
+    def test_consecutive_runs_from_different_directories(self):
+        """Test that tool works when called from multiple different directories."""
+        directories = [
+            os.path.expanduser("~"),
+            "/tmp",
+            "/",
+        ]
+        
+        for directory in directories:
+            result = subprocess.run(
+                ["hate_crack", "--help"],
+                cwd=directory,
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            assert result.returncode == 0, f"Failed when running from {directory}"
+            assert "usage: hate_crack" in result.stdout
+
+    def test_asset_resolution_from_various_locations(self):
+        """Test that assets are correctly resolved from various working directories."""
+        directories = [
+            os.path.expanduser("~"),
+            os.path.expanduser("~/Desktop") if os.path.exists(os.path.expanduser("~/Desktop")) else "/tmp",
+            "/tmp",
+        ]
+        
+        for directory in directories:
+            if not os.path.exists(directory):
+                continue
+                
+            result = subprocess.run(
+                ["hate_crack", "--help"],
+                cwd=directory,
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            # Should succeed from any directory
+            assert result.returncode == 0, (
+                f"Tool failed from {directory}. "
+                f"stdout: {result.stdout}, stderr: {result.stderr}"
+            )

tests/test_invalid_hcatpath.py

@@ -0,0 +1,40 @@
+"""
+Test error handling when hcatPath is misconfigured.
+"""
+import os
+import sys
+import tempfile
+import json
+
+
+def test_ensure_binary_error_message(monkeypatch, capsys):
+    """Test that ensure_binary provides helpful error when build_dir doesn't exist."""
+    # Import the function
+    from hate_crack.main import ensure_binary
+    
+    # Test with non-existent build directory
+    fake_binary = "/nonexistent/path/to/binary"
+    fake_build_dir = "/opt/hashcat/hashcat-utils"  # Simulate user's error
+    
+    # Expect SystemExit when binary and build dir don't exist
+    try:
+        ensure_binary(fake_binary, build_dir=fake_build_dir, name="expander")
+        assert False, "Should have exited with error"
+    except SystemExit as e:
+        assert e.code == 1
+    
+    # Check that the error message mentions the build directory issue
+    captured = capsys.readouterr()
+    assert "Build directory" in captured.out or "does not exist" in captured.out
+    assert "hcatPath" in captured.out  # Should mention config issue
+    assert "hashcat-utils" in captured.out or "princeprocessor" in captured.out
+
+
+def test_ensure_binary_with_existing_binary():
+    """Test that ensure_binary succeeds when binary exists."""
+    from hate_crack.main import ensure_binary
+    
+    # Use a system binary that definitely exists
+    python_path = sys.executable
+    result = ensure_binary(python_path)
+    assert result == python_path