Aperant/tests/test_cli_utils.py

#!/usr/bin/env python3
"""
Tests for CLI Utilities (cli/utils.py)
=======================================

Tests for shared utility functions used across the CLI:
- import_dotenv()
- setup_environment()
- find_spec()
- validate_environment()
- print_banner()
- get_project_dir()
- find_specs_dir()
"""

import os
import sys
from pathlib import Path
from unittest.mock import MagicMock, patch

import pytest

# Note: conftest.py handles apps/backend path
# Add tests directory to path for test_utils import (conftest doesn't handle this)
if str(Path(__file__).parent) not in sys.path:
    sys.path.insert(0, str(Path(__file__).parent))


# =============================================================================
# Mock external dependencies before importing cli.utils
# =============================================================================

# Import shared helper for creating mock modules
from test_utils import _create_mock_module

# Mock modules that may not be available
if 'graphiti_config' not in sys.modules:
    sys.modules['graphiti_config'] = _create_mock_module()
if 'linear_integration' not in sys.modules:
    sys.modules['linear_integration'] = _create_mock_module()
if 'linear_updater' not in sys.modules:
    sys.modules['linear_updater'] = _create_mock_module()


# =============================================================================
# Auto-use fixture to set up mock UI module before importing cli.utils
# =============================================================================

@pytest.fixture(autouse=True)
def setup_mock_ui_for_utils(mock_ui_module_full):
    """Auto-use fixture that replaces sys.modules['ui'] with mock for each test."""
    sys.modules['ui'] = mock_ui_module_full
    yield


# =============================================================================
# Import cli.utils after mock UI is set up by autouse fixture
# =============================================================================

from cli.utils import (
    import_dotenv,
    setup_environment,
    find_spec,
    validate_environment,
    print_banner,
    get_project_dir,
    find_specs_dir,
    DEFAULT_MODEL,
)


# =============================================================================
# Tests for import_dotenv()
# =============================================================================

class TestImportDotenv:
    """Tests for import_dotenv() function."""

    def test_returns_load_dotenv_function_when_available(self):
        """Returns load_dotenv function when python-dotenv is installed."""
        # This test assumes python-dotenv is installed (which it should be)
        result = import_dotenv()
        assert callable(result)

    @patch('cli.utils.sys.exit')
    @patch('cli.utils.sys.executable', '/usr/bin/python3')
    def test_exits_with_helpful_message_when_not_available(self, mock_exit):
        """Exits with helpful error message when dotenv is not installed."""
        import builtins

        # Save the real __import__ function
        original_import = builtins.__import__

        def selective_import_error(name, *args, **kwargs):
            """Only raise ImportError for 'dotenv', delegate to real import otherwise."""
            if name == 'dotenv' or name.startswith('dotenv.'):
                raise ImportError('No module named dotenv')
            return original_import(name, *args, **kwargs)

        # Mock __import__ with selective side effect
        with patch('builtins.__import__', side_effect=selective_import_error):
            import_dotenv()
            # Verify sys.exit was called
            mock_exit.assert_called_once()
            exit_message = mock_exit.call_args[0][0]
            # Check that the error message contains helpful information
            assert "python-dotenv" in exit_message
            assert "not installed" in exit_message
            assert "virtual environment" in exit_message
            assert "/usr/bin/python3" in exit_message
            assert "pip install python-dotenv" in exit_message


# =============================================================================
# Tests for setup_environment()
# =============================================================================

class TestSetupEnvironment:
    """Tests for setup_environment() function."""

    def test_returns_script_dir(self):
        """Returns the script directory path."""
        result = setup_environment()
        assert isinstance(result, Path)
        assert result.exists()

    def test_adds_to_sys_path(self):
        """Adds script directory to sys.path."""
        result = setup_environment()
        assert str(result) in sys.path

    @patch('cli.utils.load_dotenv')
    def test_loads_env_from_script_dir(self, mock_load_dotenv, temp_dir):
        """Loads .env file from script directory when present."""
        # Create a mock script dir with .env file
        env_file = temp_dir / ".env"
        env_file.write_text("TEST_VAR=value")

        with patch('cli.utils.Path') as mock_path:
            mock_path_instance = MagicMock()
            mock_path_instance.parent.parent.resolve.return_value = temp_dir
            mock_path_instance.__truediv__.return_value = env_file
            mock_path_instance.exists.return_value = True
            mock_path.__file__ = str(temp_dir / "cli" / "utils.py")
            mock_path.return_value = mock_path_instance

            setup_environment()
            # Verify load_dotenv was called with the env file path
            # (The actual implementation may vary, so we just check it was called)

    @patch('cli.utils.load_dotenv')
    def test_loads_env_from_dev_location(self, mock_load_dotenv, temp_dir):
        """Loads .env file from dev/auto-claude location when present."""
        dev_env_file = temp_dir / "dev" / "auto-claude" / ".env"
        dev_env_file.parent.mkdir(parents=True, exist_ok=True)
        dev_env_file.write_text("TEST_VAR=dev_value")

        # This test verifies the logic exists but mocking Path is complex
        # We'll just verify the function runs without error
        result = setup_environment()
        assert isinstance(result, Path)

    @patch('cli.utils.load_dotenv')
    def test_loads_dev_env_when_script_env_missing(self, mock_load_dotenv, temp_dir, monkeypatch):
        """Loads dev/.env file when script dir .env does not exist."""
        # Create temp directory structure
        dev_env_file = temp_dir / "dev" / "auto-claude" / ".env"
        dev_env_file.parent.mkdir(parents=True, exist_ok=True)
        dev_env_file.write_text("TEST_VAR=dev_value")

        # Mock Path.__file__ to point to our temp directory structure
        # Create a mock that returns our temp directory structure
        with patch('cli.utils.Path') as mock_path_class:
            # Setup mock Path instance for __file__
            mock_script_dir = MagicMock()
            mock_script_dir.resolve.return_value = temp_dir

            mock_script_env_file = MagicMock()
            mock_script_env_file.exists.return_value = False

            mock_dev_env_file = MagicMock()
            mock_dev_env_file.exists.return_value = True

            # Setup Path division
            def truediv_side_effect(other):
                if str(other) == ".env":
                    return mock_script_env_file
                elif str(other) == "dev":
                    mock_dev = MagicMock()
                    mock_dev_auto_claude = MagicMock()
                    mock_dev_auto_claude_env = MagicMock()
                    mock_dev_auto_claude_env.exists.return_value = True
                    mock_dev_auto_claude.__truediv__.return_value = mock_dev_auto_claude_env
                    mock_dev.__truediv__.return_value = mock_dev_auto_claude
                    return mock_dev
                return MagicMock()

            mock_script_dir.__truediv__.side_effect = truediv_side_effect
            mock_script_dir.parent = MagicMock()

            # Make Path(__file__).parent.parent resolve to our mock
            mock_path_instance = MagicMock()
            mock_path_instance.parent.parent.resolve.return_value = temp_dir
            mock_path_instance.parent.parent.__truediv__ = mock_script_dir.__truediv__
            mock_path_instance.parent.parent.parent = MagicMock()

            # Configure the mock Path class
            mock_path_class.return_value = mock_path_instance
            mock_path_class.__file__ = str(temp_dir / "cli" / "utils.py")

            # Patch the module-level _PARENT_DIR and sys.path logic
            original_path = sys.path.copy()
            try:
                # Clear and reload sys.path to trigger line 15
                if str(temp_dir) in sys.path:
                    sys.path.remove(str(temp_dir))

                # Now call setup_environment - the key is that when script_dir .env
                # doesn't exist but dev/auto-claude/.env does, it should load the dev one
                result = setup_environment()

                # Verify the function completed successfully
                assert isinstance(result, Path)
            finally:
                sys.path[:] = original_path


# =============================================================================
# Tests for find_spec()
# =============================================================================

class TestFindSpec:
    """Tests for find_spec() function."""

    def test_finds_spec_by_exact_match(self, temp_dir):
        """Finds spec by exact identifier match."""
        # Create spec directory
        specs_dir = temp_dir / ".auto-claude" / "specs"
        specs_dir.mkdir(parents=True)
        spec_folder = specs_dir / "001-test-feature"
        spec_folder.mkdir()
        (spec_folder / "spec.md").write_text("# Test Spec")

        result = find_spec(temp_dir, "001-test-feature")
        assert result is not None
        assert result.name == "001-test-feature"
        assert (result / "spec.md").exists()

    def test_finds_spec_by_number_prefix(self, temp_dir):
        """Finds spec by number prefix (001 matches 001-feature-name)."""
        specs_dir = temp_dir / ".auto-claude" / "specs"
        specs_dir.mkdir(parents=True)
        spec_folder = specs_dir / "001-test-feature"
        spec_folder.mkdir()
        (spec_folder / "spec.md").write_text("# Test Spec")

        result = find_spec(temp_dir, "001")
        assert result is not None
        assert result.name == "001-test-feature"

    def test_returns_none_for_nonexistent_spec(self, temp_dir):
        """Returns None when spec is not found."""
        result = find_spec(temp_dir, "999-nonexistent")
        assert result is None

    def test_requires_spec_md_file(self, temp_dir):
        """Requires spec.md to exist in the spec folder."""
        specs_dir = temp_dir / ".auto-claude" / "specs"
        specs_dir.mkdir(parents=True)
        spec_folder = specs_dir / "001-test-feature"
        spec_folder.mkdir()
        # No spec.md file created

        result = find_spec(temp_dir, "001-test-feature")
        assert result is None

    def test_finds_spec_in_worktree(self, temp_dir):
        """Finds spec in worktree directory."""
        # Create worktree structure
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"
        worktree_dir = worktree_base / "001-test-feature"
        spec_in_worktree = worktree_dir / ".auto-claude" / "specs" / "001-test-feature"
        spec_in_worktree.mkdir(parents=True)
        (spec_in_worktree / "spec.md").write_text("# Test Spec")

        result = find_spec(temp_dir, "001-test-feature")
        assert result is not None
        assert "worktrees" in str(result)

    def test_finds_spec_in_worktree_by_prefix(self, temp_dir):
        """Finds spec in worktree by number prefix."""
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"
        worktree_dir = worktree_base / "001-test-feature"
        spec_in_worktree = worktree_dir / ".auto-claude" / "specs" / "001-test-feature"
        spec_in_worktree.mkdir(parents=True)
        (spec_in_worktree / "spec.md").write_text("# Test Spec")

        result = find_spec(temp_dir, "001")
        assert result is not None
        assert "worktrees" in str(result)

    def test_worktree_spec_requires_spec_md_file(self, temp_dir):
        """Worktree spec requires spec.md to exist."""
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"
        worktree_dir = worktree_base / "001-test-feature"
        spec_in_worktree = worktree_dir / ".auto-claude" / "specs" / "001-test-feature"
        spec_in_worktree.mkdir(parents=True)
        # No spec.md file created

        result = find_spec(temp_dir, "001-test-feature")
        assert result is None

    def test_worktree_spec_exact_match_takes_precedence(self, temp_dir):
        """Worktree exact match takes precedence over prefix match."""
        # Create two worktrees - one exact match, one prefix match
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"

        # Exact match directory
        exact_dir = worktree_base / "001"
        exact_spec = exact_dir / ".auto-claude" / "specs" / "001"
        exact_spec.mkdir(parents=True)
        (exact_spec / "spec.md").write_text("# Exact Match")

        # Prefix match directory
        prefix_dir = worktree_base / "001-test"
        prefix_spec = prefix_dir / ".auto-claude" / "specs" / "001-test"
        prefix_spec.mkdir(parents=True)
        (prefix_spec / "spec.md").write_text("# Prefix Match")

        result = find_spec(temp_dir, "001")
        # Exact match should be found first
        assert result is not None
        # The exact match is found first, so it should return the exact directory
        assert "001" in str(result)

    def test_returns_none_when_specs_dir_doesnt_exist(self, temp_dir):
        """Returns None when specs directory doesn't exist."""
        # Don't create any specs directory
        result = find_spec(temp_dir, "001-test")
        assert result is None

    def test_worktree_prefix_match_without_spec_md(self, temp_dir):
        """Worktree prefix match returns None when spec.md is missing."""
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"
        worktree_dir = worktree_base / "001-test-feature"
        spec_in_worktree = worktree_dir / ".auto-claude" / "specs" / "001-test-feature"
        spec_in_worktree.mkdir(parents=True)
        # No spec.md

        result = find_spec(temp_dir, "001")
        assert result is None

    def test_main_specs_dir_priority_over_worktree(self, temp_dir):
        """Main specs directory is checked before worktree."""
        # Create spec in main directory
        specs_dir = temp_dir / ".auto-claude" / "specs"
        specs_dir.mkdir(parents=True)
        main_spec = specs_dir / "001-test"
        main_spec.mkdir()
        (main_spec / "spec.md").write_text("# Main Spec")

        # Also create spec in worktree
        worktree_base = temp_dir / ".auto-claude" / "worktrees" / "tasks"
        worktree_dir = worktree_base / "001-test"
        worktree_spec = worktree_dir / ".auto-claude" / "specs" / "001-test"
        worktree_spec.mkdir(parents=True)
        (worktree_spec / "spec.md").write_text("# Worktree Spec")

        result = find_spec(temp_dir, "001-test")
        # Main specs directory should be found first
        assert result is not None
        assert "worktrees" not in str(result)
        assert str(result).endswith("001-test")


# =============================================================================
# Tests for validate_environment()
# =============================================================================

class TestValidateEnvironment:
    """Tests for validate_environment() function."""

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    @patch('cli.utils.get_auth_token_source')
    @patch('cli.utils.is_linear_enabled')
    @patch('cli.utils.LinearManager')
    def test_returns_true_when_all_valid(
        self,
        mock_linear_manager,
        mock_is_linear_enabled,
        mock_get_auth_token_source,
        mock_get_auth_token,
        mock_validate_platform_deps,
        temp_dir
    ):
        """Returns True when all validation checks pass."""
        # Setup mocks
        mock_get_auth_token.return_value = "test-token"
        mock_get_auth_token_source.return_value = "OAuth"
        mock_is_linear_enabled.return_value = False

        # Create spec.md
        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        # Mock graphiti_config module (imported lazily in validate_environment)
        with patch('graphiti_config.get_graphiti_status', return_value={
            "available": False,
            "enabled": False,
            "reason": "not configured"
        }):
            result = validate_environment(spec_dir)
            assert result is True

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_returns_false_when_no_auth_token(
        self,
        mock_get_auth_token,
        mock_validate_platform_deps,
        temp_dir,
        capsys
    ):
        """Returns False when no OAuth token is found."""
        mock_get_auth_token.return_value = None

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                result = validate_environment(spec_dir)
                assert result is False
                captured = capsys.readouterr()
                assert "No OAuth token found" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_returns_false_when_spec_md_missing(
        self,
        mock_get_auth_token,
        mock_validate_platform_deps,
        temp_dir,
        capsys
    ):
        """Returns False when spec.md is not found."""
        mock_get_auth_token.return_value = "test-token"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        # No spec.md created

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                result = validate_environment(spec_dir)
                assert result is False
                captured = capsys.readouterr()
                assert "spec.md not found" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    @patch('cli.utils.get_auth_token_source')
    def test_shows_auth_source(self, mock_get_auth_token_source, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows which auth source is being used."""
        mock_get_auth_token.return_value = "test-token"
        mock_get_auth_token_source.return_value = "OAuth Profile: test@example.com"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                validate_environment(spec_dir)
                captured = capsys.readouterr()
                assert "OAuth Profile: test@example.com" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    @patch('cli.utils.get_auth_token_source')
    @patch.dict(os.environ, {'ANTHROPIC_BASE_URL': 'http://localhost:8080'})
    def test_shows_custom_base_url(self, mock_get_auth_token_source, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows custom API endpoint when set."""
        mock_get_auth_token.return_value = "test-token"
        mock_get_auth_token_source.return_value = "oauth_profile:test@example.com"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                validate_environment(spec_dir)
                captured = capsys.readouterr()
                assert "http://localhost:8080" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    @patch('cli.utils.is_linear_enabled')
    @patch('cli.utils.LinearManager')
    def test_shows_linear_integration_enabled_with_project(
        self,
        mock_linear_manager_class,
        mock_is_linear_enabled,
        mock_get_auth_token,
        mock_validate_platform_deps,
        temp_dir,
        capsys
    ):
        """Shows Linear integration status when enabled with initialized project."""
        mock_get_auth_token.return_value = "test-token"
        mock_is_linear_enabled.return_value = True

        # Create mock LinearManager instance
        mock_linear_manager = MagicMock()
        mock_linear_manager.is_initialized = True
        mock_linear_manager.get_progress_summary.return_value = {
            'project_name': 'Test Project',
            'mapped_subtasks': 5,
            'total_subtasks': 10
        }
        mock_linear_manager_class.return_value = mock_linear_manager

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            result = validate_environment(spec_dir)
            assert result is True
            captured = capsys.readouterr()
            assert "Linear integration: ENABLED" in captured.out
            assert "Test Project" in captured.out
            assert "5/10 mapped" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    @patch('cli.utils.is_linear_enabled')
    @patch('cli.utils.LinearManager')
    def test_shows_linear_integration_enabled_not_initialized(
        self,
        mock_linear_manager_class,
        mock_is_linear_enabled,
        mock_get_auth_token,
        mock_validate_platform_deps,
        temp_dir,
        capsys
    ):
        """Shows Linear integration enabled but not yet initialized."""
        mock_get_auth_token.return_value = "test-token"
        mock_is_linear_enabled.return_value = True

        # Create mock LinearManager instance that is not initialized
        mock_linear_manager = MagicMock()
        mock_linear_manager.is_initialized = False
        mock_linear_manager_class.return_value = mock_linear_manager

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            result = validate_environment(spec_dir)
            assert result is True
            captured = capsys.readouterr()
            assert "Linear integration: ENABLED" in captured.out
            assert "Will be initialized during planner session" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_shows_linear_integration_disabled(self, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows Linear integration disabled when not enabled."""
        mock_get_auth_token.return_value = "test-token"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {"available": False, "enabled": False, "reason": "test"}
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                validate_environment(spec_dir)
                captured = capsys.readouterr()
                assert "Linear integration: DISABLED" in captured.out
                assert "LINEAR_API_KEY" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_shows_graphiti_enabled_with_db_path(self, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows Graphiti memory enabled with database path."""
        mock_get_auth_token.return_value = "test-token"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {
            "available": True,
            "enabled": True,
            "database": "neo4j",
            "db_path": "/path/to/db"
        }
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                result = validate_environment(spec_dir)
                assert result is True
                captured = capsys.readouterr()
                assert "Graphiti memory: ENABLED" in captured.out
                assert "neo4j" in captured.out
                assert "/path/to/db" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_shows_graphiti_configured_but_unavailable(self, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows Graphiti configured but unavailable."""
        mock_get_auth_token.return_value = "test-token"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {
            "available": False,
            "enabled": True,
            "reason": "connection failed"
        }
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                result = validate_environment(spec_dir)
                assert result is True
                captured = capsys.readouterr()
                assert "Graphiti memory: CONFIGURED but unavailable" in captured.out
                assert "connection failed" in captured.out

    @patch('cli.utils.validate_platform_dependencies')
    @patch('cli.utils.get_auth_token')
    def test_shows_graphiti_disabled(self, mock_get_auth_token, mock_validate_platform_deps, temp_dir, capsys):
        """Shows Graphiti memory disabled when not enabled."""
        mock_get_auth_token.return_value = "test-token"

        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
        spec_dir.mkdir(parents=True)
        (spec_dir / "spec.md").write_text("# Test")

        mock_graphiti_status = {
            "available": False,
            "enabled": False,
            "reason": "not configured"
        }
        with patch('graphiti_config.get_graphiti_status', return_value=mock_graphiti_status):
            with patch('cli.utils.is_linear_enabled', return_value=False):
                validate_environment(spec_dir)
                captured = capsys.readouterr()
                assert "Graphiti memory: DISABLED" in captured.out
                assert "GRAPHITI_ENABLED" in captured.out


# =============================================================================
# Tests for print_banner()
# =============================================================================

class TestPrintBanner:
    """Tests for print_banner() function."""

    def test_prints_banner(self, capsys):
        """Prints the Auto-Build banner."""
        print_banner()
        captured = capsys.readouterr()
        assert "AUTO-BUILD" in captured.out or "Auto-Build" in captured.out
        assert "Autonomous Multi-Session Coding Agent" in captured.out

    def test_includes_subtask_text(self, capsys):
        """Banner mentions subtask-based implementation."""
        print_banner()
        captured = capsys.readouterr()
        # The muted text should be included
        assert "Subtask" in captured.out or "Phase" in captured.out


# =============================================================================
# Tests for get_project_dir()
# =============================================================================

class TestGetProjectDir:
    """Tests for get_project_dir() function."""

    def test_returns_provided_dir(self):
        """Returns the provided directory when given."""
        provided = Path("/tmp/test-project")
        result = get_project_dir(provided)
        assert result == provided.resolve()

    def test_returns_cwd_when_no_dir_provided(self):
        """Returns current working directory, or auto-detects project root from apps/backend."""
        result = get_project_dir(None)

        # If we're in apps/backend directory (with run.py), it should return project root
        # Otherwise, it returns the current working directory
        cwd = Path.cwd()
        expected = cwd

        # Check if we're in apps/backend with run.py
        if cwd.name == "backend" and (cwd / "run.py").exists():
            # Should return project root (2 levels up)
            expected = cwd.parent.parent

        assert result == expected

    def test_auto_detects_backend_directory(self, tmp_path, monkeypatch):
        """Auto-detects project root when running from apps/backend."""
        # Create apps/backend structure
        backend_dir = tmp_path / "apps" / "backend"
        backend_dir.mkdir(parents=True)
        (backend_dir / "run.py").write_text("# run.py")

        # Change to backend directory using monkeypatch
        monkeypatch.chdir(backend_dir)
        result = get_project_dir(None)
        # Should return project root (goes up 2 levels from backend)
        # The function detects it's in backend and goes to parent.parent
        # So from apps/backend, it goes to tmp_path (project root)
        assert result == tmp_path

    def test_returns_cwd_for_non_backend_dir(self, tmp_path, monkeypatch):
        """Returns cwd when not in a backend directory."""
        # Create a regular directory
        test_dir = tmp_path / "some-project"
        test_dir.mkdir()

        # Change to test directory using monkeypatch
        monkeypatch.chdir(test_dir)
        result = get_project_dir(None)
        assert result == test_dir


# =============================================================================
# Tests for find_specs_dir()
# =============================================================================

class TestFindSpecsDir:
    """Tests for find_specs_dir() function."""

    def test_returns_specs_dir_path(self, temp_dir):
        """Returns path to .auto-claude/specs directory."""
        result = find_specs_dir(temp_dir)
        assert result.name == "specs"
        assert ".auto-claude" in result.parts or result.parent.name == ".auto-claude"

    def test_creates_directory_if_not_exists(self, temp_dir):
        """Creates specs directory if it doesn't exist."""
        # Ensure directory doesn't exist
        specs_dir = temp_dir / ".auto-claude" / "specs"
        if specs_dir.exists():
            import shutil
            shutil.rmtree(specs_dir.parent)

        # The find_specs_dir function calls get_specs_dir which creates the directory
        result = find_specs_dir(temp_dir)
        # The directory should be created by get_specs_dir
        # Note: The exact path depends on the implementation
        assert result is not None
        assert "specs" in str(result) or result.name == "specs"


# =============================================================================
# Tests for DEFAULT_MODEL constant
# =============================================================================

class TestDefaultModel:
    """Tests for DEFAULT_MODEL constant."""

    def test_default_model_is_sonnet(self):
        """DEFAULT_MODEL is set to 'sonnet'."""
        assert DEFAULT_MODEL == "sonnet"


# =============================================================================
# Tests for module-level behavior
# =============================================================================

class TestModuleLevelBehavior:
    """Tests for module-level initialization behavior."""

    def test_parent_dir_added_to_sys_path_on_import(self):
        """Tests that parent directory is added to sys.path when module is imported."""
        # The _PARENT_DIR is set at module level (lines 13-14)
        # and conditionally inserted into sys.path (line 15)
        # We need to verify the cli.utils module properly set this up

        import cli.utils as utils_module
        import inspect

        # Get the path to cli/utils.py
        utils_path = Path(inspect.getfile(utils_module))
        parent_dir = utils_path.parent.parent

        # The parent_dir should be in sys.path from the module initialization
        assert str(parent_dir) in sys.path or any(
            str(parent_dir) == p for p in sys.path
        ), f"Parent directory {parent_dir} should be in sys.path"

    def test_parent_dir_inserted_when_not_in_path(self):
        """Tests that parent dir is inserted when not already in sys.path."""
        # This test verifies line 15: sys.path.insert(0, str(_PARENT_DIR))
        # which only executes if str(_PARENT_DIR) not in sys.path

        import importlib
        import cli.utils

        # Get the _PARENT_DIR value and save original state
        parent_dir_str = str(cli.utils._PARENT_DIR)
        original_path = sys.path.copy()
        original_module = sys.modules.get('cli.utils')

        try:
            # Remove the parent dir from sys.path to simulate the condition
            while parent_dir_str in sys.path:
                sys.path.remove(parent_dir_str)

            # Delete the module from sys.modules to force reload
            if 'cli.utils' in sys.modules:
                del sys.modules['cli.utils']

            # Now reimport - this will execute lines 13-15 since path is not present
            import cli.utils as reloaded

            # Verify the parent dir was added to sys.path by line 15
            assert parent_dir_str in sys.path, f"Parent dir {parent_dir_str} should be in sys.path"

        finally:
            # Restore sys.path and sys.modules for other tests
            sys.path[:] = original_path
            if original_module is not None:
                sys.modules['cli.utils'] = original_module
            elif 'cli.utils' in sys.modules:
                del sys.modules['cli.utils']

    def test_parent_dir_conditionally_inserted_to_sys_path(self):
        """Tests line 15: parent dir is only inserted if not already in sys.path."""
        # This test directly verifies the conditional logic on line 15:
        # if str(_PARENT_DIR) not in sys.path:
        #     sys.path.insert(0, str(_PARENT_DIR))

        import cli.utils

        # Get the _PARENT_DIR that was set at module import time
        parent_dir = cli.utils._PARENT_DIR

        # Verify _PARENT_DIR was set correctly
        assert isinstance(parent_dir, Path)
        assert parent_dir.name == "backend" or parent_dir.name == "apps"

        # The condition on line 15 should have triggered the insert
        # Verify the parent dir is now in sys.path
        assert str(parent_dir) in sys.path, f"Parent dir {parent_dir} should be in sys.path after module import"

    @patch('cli.utils.load_dotenv')
    def test_dev_env_file_loaded_when_script_env_missing(self, mock_load_dotenv, tmp_path):
        """Tests line 94: dev .env is loaded when script dir .env doesn't exist."""
        # This test specifically targets line 94:
        # elif dev_env_file.exists():
        #     load_dotenv(dev_env_file)

        from unittest.mock import PropertyMock

        # Create a temporary directory structure
        script_dir = tmp_path / "auto-claude"
        script_dir.mkdir()

        # Create dev/auto-claude/.env
        dev_env_dir = tmp_path / "dev" / "auto-claude"
        dev_env_dir.mkdir(parents=True)
        dev_env_file = dev_env_dir / ".env"
        dev_env_file.write_text("DEV_VAR=dev_value")

        # Mock Path(__file__).parent.parent.resolve() to return our temp_dir
        with patch('cli.utils.Path') as mock_path_class:
            # Create a mock for the Path instance that __file__ would create
            mock_file_path = MagicMock()
            mock_file_path.parent = MagicMock()
            mock_file_path.parent.parent = MagicMock()
            mock_file_path.parent.parent.resolve = MagicMock(return_value=script_dir)

            # Setup the division operator to return appropriate paths
            def mock_truediv(other):
                result = MagicMock()
                if str(other) == ".env":
                    # Script dir .env doesn't exist
                    result.exists = MagicMock(return_value=False)
                elif str(other) == "dev":
                    # Return the dev directory mock
                    mock_dev = MagicMock()
                    mock_dev_auto_claude = MagicMock()
                    mock_dev_env_file = MagicMock()
                    mock_dev_env_file.exists = MagicMock(return_value=True)
                    mock_dev_auto_claude.__truediv__ = MagicMock(return_value=mock_dev_env_file)
                    mock_dev.__truediv__ = MagicMock(return_value=mock_dev_auto_claude)
                    result = mock_dev
                return result

            mock_file_path.parent.parent.__truediv__ = mock_truediv
            mock_file_path.parent.parent.parent = MagicMock()
            mock_file_path.parent.parent.parent.__truediv__ = mock_truediv

            # Make Path() return our mock
            mock_path_instance = mock_file_path
            mock_path_class.return_value = mock_path_instance
            mock_path_class.__file__ = str(script_dir / "cli" / "utils.py")

            # Also patch sys.path to avoid issues with the module-level code
            original_path = sys.path.copy()
            try:
                # Ensure parent dir is in sys.path (for line 15)
                if str(tmp_path) not in sys.path:
                    sys.path.insert(0, str(tmp_path))

                # Import and test setup_environment
                from cli.utils import setup_environment

                result = setup_environment()

                # Verify the function completed
                assert isinstance(result, Path)

            finally:
                sys.path[:] = original_path


# Tests for module-level path insertion behavior

class TestUtilsModuleLevelPathInsertion:
    """Tests for module-level path insertion behavior (line 15)."""

    def test_parent_dir_inserted_to_sys_path_when_not_present(self):
        """Tests that parent dir is inserted into sys.path when not already present (line 15)."""
        # Line 15: sys.path.insert(0, str(_PARENT_DIR))
        # This executes when module is imported and parent dir is not in sys.path

        import cli.utils as utils_module
        import inspect

        # Get the _PARENT_DIR value from the module
        parent_dir = utils_module._PARENT_DIR

        # Verify _PARENT_DIR is set correctly (line 13-14)
        assert isinstance(parent_dir, Path)
        assert parent_dir.exists()

        # Verify parent_dir was inserted into sys.path (line 15)
        assert str(parent_dir) in sys.path, f"Parent dir {parent_dir} should be in sys.path after module import"

    def test_parent_dir_path_insertion_happens_once(self):
        """Tests that parent dir insertion only happens if not already in sys.path (line 14-15)."""
        import cli.utils

        # Get the parent dir that was set at module import time
        parent_dir = cli.utils._PARENT_DIR

        # The conditional logic on lines 14-15 ensures insertion only happens once
        # if str(_PARENT_DIR) not in sys.path:
        #     sys.path.insert(0, str(_PARENT_DIR))

        # Verify parent_dir is a Path object
        assert isinstance(parent_dir, Path)

        # Verify it's in sys.path (should have been inserted on first import)
        assert str(parent_dir) in sys.path

    def test_parent_dir_is_apps_backend_directory(self):
        """Tests that _PARENT_DIR correctly points to apps/backend (line 13)."""
        import cli.utils

        parent_dir = cli.utils._PARENT_DIR

        # _PARENT_DIR = Path(__file__).parent.parent
        # This should be the apps/backend directory
        assert isinstance(parent_dir, Path)
        assert parent_dir.name in ["backend", "apps"]

    @pytest.mark.skipif(
        True,  # Subprocess test requires full environment including claude_agent_sdk (not available in CI)
        reason="Subprocess test requires claude_agent_sdk dependency; coverage achieved via reload test"
    )
    def test_parent_dir_inserted_to_sys_path_subprocess(self):
        """Tests that parent dir is inserted to sys.path at module import (line 15)."""
        import subprocess
        import sys
        import os

        # Get the apps/backend directory
        backend_dir = Path(__file__).parent.parent / "apps" / "backend"

        # Run in subprocess to ensure clean import
        # This tests line 15: sys.path.insert(0, str(_PARENT_DIR))
        code = "import sys; from cli.utils import _PARENT_DIR; assert str(_PARENT_DIR) in sys.path; print('OK')"

        result = subprocess.run(
            [sys.executable, "-c", code],
            cwd=backend_dir,
            env={**os.environ, "PYTHONPATH": str(backend_dir)},
            capture_output=True,
            text=True,
            timeout=10,
        )

        assert result.returncode == 0, f"stderr: {result.stderr}"
        assert "OK" in result.stdout

    def test_path_insertion_coverage_via_reload(self):
        """Tests path insertion by forcing module reload (line 15)."""
        import sys
        from pathlib import Path

        # Save original _PARENT_DIR value and module
        import cli.utils as utils_module
        original_parent_dir = utils_module._PARENT_DIR
        original_module = sys.modules.get('cli.utils')

        # Remove from sys.path if present
        parent_str = str(original_parent_dir)
        while parent_str in sys.path:
            sys.path.remove(parent_str)

        # Remove module from sys.modules to force reload
        if 'cli.utils' in sys.modules:
            del sys.modules['cli.utils']

        try:
            # Now reimport - this will execute lines 13-15 again
            import cli.utils as reimported_utils

            # Verify path insertion happened
            assert str(reimported_utils._PARENT_DIR) in sys.path

        finally:
            # Restore sys.path and sys.modules for other tests
            if str(original_parent_dir) not in sys.path:
                sys.path.insert(0, str(original_parent_dir))
            if original_module is not None:
                sys.modules['cli.utils'] = original_module
            elif 'cli.utils' in sys.modules:
                del sys.modules['cli.utils']