chore(docs-tests): merge comprehensive documentation and test improvements

Fayeblade1488 · web-flow · commit 2014918b6a1d · 2025-10-02T20:55:09.000-07:00
Merging PR #6 with: - Added WARP.md for warp.dev development guidance - Fixed import merge conflicts in qwen_cli_integrator.py - Fixed critical test bugs in test_coverage_improvement.py - All tests passing, approved by Gemini Code Assist Includes commits: - dc78083: Fix import merge conflicts and test syntax errors - d138eb1: Add WARP.md documentation - aa565b5: Fix test_main_help and test_main_invalid_subcommand
diff --git a/WARP.md b/WARP.md
@@ -0,0 +1,197 @@
+# WARP.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Essential Development Commands
+
+### Installation & Setup
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Set up for Gemini environment (copies scripts to ~/.gemini)
+make setup-gemini
+
+# Set up for Qwen environment (copies scripts to ~/.qwen)
+make setup-qwen
+
+# Install development tools
+pip install pytest pytest-cov pytest-mock flake8 black isort pylint
+```
+
+### Environment Configuration
+```bash
+# Required: Set Venice AI API key
+export VENICE_API_KEY="your_api_key_here"
+
+# Verify Venice API configuration
+python auto_config.py --verify
+
+# Check API key is set
+echo $VENICE_API_KEY
+```
+
+### Running Tests
+```bash
+# Run all tests
+pytest tests/
+
+# Run tests quietly
+pytest -q tests/
+
+# Run with fail-fast and last-failed optimization
+pytest -x --ff tests/
+
+# Run with coverage report
+pytest --cov=. --cov-report=term-missing tests/
+
+# Run specific test file
+pytest tests/test_integration.py -v
+```
+
+### Code Quality & Linting
+```bash
+# Run flake8 linter
+flake8 . --max-line-length=120
+
+# Format code with Black (120 char line length)
+black . --line-length 120
+
+# Sort imports with isort
+isort . --profile black
+
+# Check formatting without changes
+black --check . --line-length 120
+isort --check-only . --profile black
+```
+
+### CLI Usage
+```bash
+# Get help
+python qwen_cli_integrator.py --help
+
+# Generate image with Venice AI
+python qwen_cli_integrator.py venice generate --prompt "description" --model lustify-sdxl
+
+# GitKraken operations
+python qwen_cli_integrator.py gitkraken ai_commit
+python qwen_cli_integrator.py gitkraken workspace_list
+```
+
+## High-Level Architecture
+
+### Unified CLI Integration
+This is a **unified CLI tool** that bridges three distinct integrations:
+- **Venice AI**: Uncensored image generation and upscaling
+- **GitKraken CLI**: AI-powered Git workflow operations  
+- **External API Providers**: Generic provider abstraction layer
+
+### Core Entry Point
+- **`qwen_cli_integrator.py`**: Main orchestrator providing the `QwenCLIIntegrator` class
+  - Dispatches commands to appropriate integration modules
+  - Handles cross-tool workflows
+  - Provides unified CLI interface via argparse
+
+### Integration Modules (Flat Structure)
+All modules are in the repository root (no nested packages):
+
+- **`venice_integration.py`**: Venice AI image generation
+  - Default model: `lustify-sdxl` with 50 steps
+  - Supports image generation, upscaling (4x), and model listing
+  - Authentication: `VENICE_API_KEY` environment variable
+  - Key classes: `VeniceAIImageGenerator`, `VeniceAIVerifier`, `VeniceAIConfigUpdater`
+
+- **`gitkraken_integration.py`**: GitKraken CLI wrapper
+  - Wraps `gk` command-line tool for Git operations
+  - AI-powered features: commit generation, conflict resolution, PR creation
+  - Standard operations: branch management, workspace operations, status queries
+  - Key class: `GitKrakenCLI`
+
+- **`external_api_integrator.py`**: External API provider support
+  - Provider-agnostic abstraction layer
+  - Loads configurations from Raycast YAML format (optional)
+  - Centralizes authentication and configuration
+  - Config path: `~/.config/raycast/ai/providers.yaml`
+  - Key class: `ExternalAPIIntegrator`
+
+- **`auto_config.py`**: Configuration verification utility
+  - Standalone tool for API key verification
+  - Can automatically update Raycast configurations
+  - Usage: `python auto_config.py --verify` or `python auto_config.py --auto`
+
+### Configuration Philosophy
+- **No secrets in repository**: All API keys loaded from environment variables
+- **Environment-based setup**: Uses `.gemini` or `.qwen` home directory structure
+- **Settings file**: `setting_to_apply.json` copied during setup but contains no secrets
+
+### Scripts Directory Structure
+```
+scripts/
+├── gemini/     # Full set of modules for Gemini environment
+└── qwen/       # Full set of modules for Qwen environment
+```
+Setup targets copy these to `~/.gemini/` or `~/.qwen/` respectively.
+
+## Ongoing Improvement Work
+
+### Current Development Context
+- **Branch**: `chore/docs-tests-bugfix-qwen-cli`
+- **Recent commit**: `dc78083` (fixed merge conflicts and test syntax errors)
+- **Test baseline**: 60 tests passing, 5 tests failing (pre-existing issues, not regressions)
+- **Repository state**: Clean working state on feature branch, ready for enhancement
+
+### In-Progress Tasks
+1. **Comprehensive Docstrings**: Adding complete docstrings across 5 core modules
+2. **Test Coverage Expansion**: Creating new test files to cover high-risk code paths
+3. **Security Hardening**: `yaml.safe_load()` already implemented (was security issue)
+4. **Documentation Overhaul**: README enhancement, architecture guides, this WARP.md
+
+### Priority Items (from previous session)
+- **Critical bug fix**: Security issue with yaml loading (✓ already fixed)
+- **Core module documentation**: Focus on `qwen_cli_integrator`, `venice_integration`, `external_api_integrator`
+- **Essential test coverage**: New test files targeting highest-risk paths
+- **Architecture documentation**: This WARP.md and README updates
+
+## Important Development Notes
+
+### Requirements
+- **Python**: 3.7+ required
+- **Optional**: GitKraken CLI (`gk` command) for Git operations
+- **Required for image gen**: Venice AI API key
+
+### Code Style & Standards
+- **Commit format**: Conventional commits enforced (`feat:`, `fix:`, `docs:`, `chore:`, etc.)
+- **Formatting**: Black with 120 character line length
+- **Import sorting**: isort with black profile
+- **Linting**: flake8 with max-complexity=10
+
+### Security Best Practices
+- Never commit API keys or secrets
+- Always use environment variables for configuration
+- API keys are automatically redacted in logs
+- Client-side CSAM guard implemented (content filtering)
+
+### Testing Stack
+- **pytest**: Test framework
+- **pytest-cov**: Coverage reporting
+- **pytest-mock**: Mocking support
+- Test files located in `tests/` directory
+
+### GitHub Workflows
+- **tests.yml**: Runs pytest on push/PR to main
+- **linting.yml**: Runs flake8, black, isort checks
+- **security.yml**: Security scanning
+
+### Notable Defaults
+- **Venice model**: `lustify-sdxl` (uncensored)
+- **Generation steps**: 50 (optimal for lustify-sdxl)
+- **Safe mode**: Disabled by default
+- **CFG scale**: 5.0
+
+### Module Dependencies
+```
+qwen_cli_integrator.py
+├── gitkraken_integration.py (no external deps)
+├── venice_integration.py (requires: requests, urllib3)
+└── external_api_integrator.py (requires: requests, pyyaml [optional])
+```
diff --git a/qwen_cli_integrator.py b/qwen_cli_integrator.py
@@ -14,12 +14,8 @@
 
 # Import our integration modules
 from gitkraken_integration import GitKrakenCLI
-<<<<<<< Updated upstream
 from venice_integration import VeniceAIImageGenerator, VeniceAIVerifier, VeniceAIConfigUpdater
 from external_api_integrator import ExternalAPIIntegrator
-=======
-from venice_integration import VeniceAIImageGenerator
->>>>>>> Stashed changes
 
 
 class QwenCLIIntegrator:
@@ -245,7 +241,6 @@ def list_available_models(self) -> Dict[str, Any]:
                 'success': False,
                 'error': str(e)
             }
-<<<<<<< Updated upstream
     
     def external_chat_completion(self, provider_id: str, model_id: str, messages: list, **kwargs) -> Dict[str, Any]:
         """Performs a chat completion using an external API provider.
diff --git a/tests/test_coverage_improvement.py b/tests/test_coverage_improvement.py
@@ -522,33 +522,44 @@ def test_list_external_providers(self, mock_ext_class):
         self.assertTrue(result['success'])
         self.assertIn('providers', result)
     
-+    @patch('qwen_cli_integrator.sys.argv', ['qwen_cli_integrator.py', '--help'])
-+    @patch('qwen_cli_integrator.argparse.ArgumentParser')
-+    def test_main_help(self, mock_parser_class):
-+        """Test main function with --help."""
-+        from qwen_cli_integrator import main
-+        
-+        mock_parser = MagicMock()
-+        mock_parser_class.return_value = mock_parser
-+        
-+        result = main()
-+        mock_parser.print_help.assert_called()
-+
-+    @patch('qwen_cli_integrator.sys.argv', ['qwen_cli_integrator.py', 'invalid_subcommand'])
-+    @patch('qwen_cli_integrator.argparse.ArgumentParser')
-+    def test_main_invalid_subcommand(self, mock_parser_class):
-+        """Test main function with invalid subcommand."""
-+        from qwen_cli_integrator import main
-+
-+        mock_parser = MagicMock()
-+        # Simulate parse_args returning a Namespace with an invalid subcommand
-+        mock_parser.parse_args.return_value = argparse.Namespace(command='invalid_subcommand')
-+        mock_parser_class.return_value = mock_parser
-+
-+        # Simulate error handling: ArgumentParser.error should be called
-+        mock_parser.error = MagicMock()
-+
-+        main()
-+        mock_parser.error.assert_called()
+    @patch('qwen_cli_integrator.sys.argv', ['qwen_cli_integrator.py', '--help'])
+    @patch('qwen_cli_integrator.sys.exit')  # Mock sys.exit as argparse exits on --help
+    @patch('qwen_cli_integrator.argparse.ArgumentParser')
+    def test_main_help(self, mock_parser_class, mock_sys_exit):
+        """Test main function with --help (argparse exits with code 0)."""
+        from qwen_cli_integrator import main
+        
+        mock_parser = MagicMock()
+        # When --help is provided, argparse's parse_args raises SystemExit(0)
+        mock_parser.parse_args.side_effect = SystemExit(0)
+        mock_parser_class.return_value = mock_parser
+        
+        # Call main and expect SystemExit to be caught
+        try:
+            main()
+        except SystemExit:
+            pass  # Expected behavior
+        
+        # Verify parse_args was called (which triggers help output)
+        mock_parser.parse_args.assert_called_once()
+
+    @patch('qwen_cli_integrator.sys.argv', ['qwen_cli_integrator.py', 'invalid_subcommand'])
+    @patch('qwen_cli_integrator.argparse.ArgumentParser')
+    def test_main_invalid_subcommand(self, mock_parser_class):
+        """Test main function with invalid subcommand (prints help and returns 1)."""
+        from qwen_cli_integrator import main
+
+        mock_parser = MagicMock()
+        # Simulate parse_args returning a Namespace with an invalid subcommand
+        # Corrected: 'dest' for subparsers is 'tool', not 'command'
+        mock_parser.parse_args.return_value = argparse.Namespace(tool='invalid_subcommand')
+        mock_parser_class.return_value = mock_parser
+
+        # For invalid tool, main() calls parser.print_help() and returns 1
+        result = main()
+        
+        mock_parser.print_help.assert_called_once()  # Assert parser.print_help is called
+        self.assertEqual(result, 1)  # Assert return code is 1
+
 if __name__ == '__main__':
     unittest.main()
