Cursor Rules for the git_operations Module

0. Preamble

These rules are specific to the git_operations module and supplement general.cursorrules. Always adhere to general.cursorrules unless explicitly overridden here.

1. Module Purpose & Context

• Core Functionality: Provides a Python API for programmatic Git operations, abstracting direct CLI calls and promoting consistent, secure, and logged version control interactions. Aims to support automation of Git workflows within Codomyrmex.
• Key Technologies/Tools: Python, git CLI via subprocess module.
• Refer to this module's README.md for a comprehensive overview of its intended scope and design.

2. Key Files & Structure

When working within this module, pay close attention to:

• README.md: Comprehensive module overview, quick start guide, and feature list.
• API_SPECIFICATION.md: Defines the public Python API for Git functions (e.g., get_status, commit_changes). This is the primary contract for users of the module.
• COMPLETE_API_DOCUMENTATION.md: Detailed documentation with examples for all functions.
• MCP_TOOL_SPECIFICATION.md: (Currently N/A) Would define any MCP tools for AI-driven Git operations.
• SECURITY.md: Critical security considerations for automating Git operations, especially credential handling and command execution.
• USAGE_EXAMPLES.md and COMPREHENSIVE_USAGE_EXAMPLES.md: Examples of how to use the Python API.
• git_manager.py: Core Python functions wrapping Git commands via subprocess.
• github_api.py: GitHub API integration for repository and PR management.
• repository_manager.py: Repository library management and bulk operations.
• repository_metadata.py: Metadata tracking system for repositories.
• visualization_integration.py: Optional visualization features (requires data_visualization module).
• docs/technical_overview.md: In-depth technical design of the Git interaction logic.
• docs/tutorials/: How-to guides for using the module's API for specific project workflows.

3. Coding Standards & Practices

For Python API (git_manager.py, etc.):

• Follow Python PEP 8 guidelines.
• Subprocess Implementation: The module uses subprocess.run() for all Git operations. This is the current implementation approach.
  • Always pass commands and arguments as a list (e.g., subprocess.run(["git", "status"], ...)).
  • Never use shell=True with user-supplied input.
  • All user-provided strings are passed as list elements, preventing command injection.
  • Use cwd parameter to specify repository path rather than changing directories.
• Comprehensive Error Handling: Catch exceptions from subprocess and return typed results (bool, None, empty dict/list) rather than raising exceptions. Errors are logged via logging_monitoring module.
• Structured Output: Return structured data (dictionaries, lists) rather than raw string output from Git commands where applicable.
• Logging: Integrate with the logging_monitoring module to log all significant Git operations, their parameters (excluding sensitive ones), and their success/failure status.
• Clear Docstrings: All public API functions must have comprehensive docstrings explaining parameters, return values, and behavior, consistent with API_SPECIFICATION.md.
• Idempotency where applicable: Design functions to be idempotent if the underlying Git command supports it and it makes sense for the use case.
• Performance Monitoring: Use @monitor_performance decorator from performance module when available for tracking operation latency.

For Documentation (Markdown):

• Ensure API_SPECIFICATION.md is the source of truth for the Python API.
• Keep tutorials and usage examples aligned with the implemented API.
• Clearly document security implications and prerequisites (like Git authentication setup) for using the API.

4. Testing

• Unit Tests (tests/unit/):
  • Focus on the logic within wrapper functions (argument parsing, subprocess calls, output parsing).
  • Mock subprocess.run() calls to simulate various Git responses (success, errors, different repository states).
  • Test error handling and return value types.
• Integration Tests (tests/integration/):
  • These tests should interact with actual (temporary, locally created) Git repositories.
  • Create a temporary directory, initialize a Git repo (git init).
  • Perform sequences of API calls (e.g., create_branch, commit_changes, get_status) and then assert the state of the local Git repository.
  • Clean up temporary repositories after tests.
  • These tests will be slower and should be marked appropriately if needed.
• Security: Consider tests that try to misuse API functions with unusual inputs to verify subprocess safety.

5. Documentation (Meta-Documentation for this Module)

• Keep this module's README.md and docs/technical_overview.md accurately reflecting the design and implementation of the Git automation tools.

6. Specific Considerations for git_operations

• Cross-Platform Compatibility: Be mindful of how Git behaves on different OS (Windows, Linux, macOS), especially regarding paths, line endings, and credential helpers. The subprocess approach works across platforms.
• Security is Paramount: Given that this module interacts with source code and potentially credentials, all design and implementation choices must prioritize security. Refer to SECURITY.md frequently.
• User Experience for API Consumers: Design the Python API to be intuitive and easy to use correctly.
• Error Handling Philosophy: Functions return False/None/empty collections on error rather than raising exceptions. This allows callers to check results without try/except blocks, but requires careful checking of return values.

7. Final Check (when implementing features)

• Verify that API functions behave as described in API_SPECIFICATION.md.
• Ensure all operations are logged appropriately via logging_monitoring.
• Confirm that error handling is robust and user-friendly.
• Update this module's CHANGELOG.md for any changes to the API or significant functionality.
• Ensure subprocess calls use list arguments and never shell=True.