Codomyrmex Git Operations Module
Cursor rules for developing the `git_operations` module within Codomyrmex — a Python API for programmatic Git operations that abstracts CLI calls with security, logging, and structured outputs.
Module Overview
The `git_operations` module provides a Python API for automating Git workflows. It wraps Git CLI commands via `subprocess`, ensuring consistent, secure, and logged version control interactions. Designed for AI-driven development automation within the Codomyrmex workspace.
**Core Technologies:** Python, Git CLI, subprocess module, GitHub API integration
Key Files & Structure
When working in this module, reference these files:
`README.md` — Module overview, quick start, feature list`API_SPECIFICATION.md` — Public Python API contract (source of truth)`COMPLETE_API_DOCUMENTATION.md` — Detailed API docs with examples`SECURITY.md` — Critical security considerations for Git automation`USAGE_EXAMPLES.md` / `COMPREHENSIVE_USAGE_EXAMPLES.md` — Usage patterns`git_manager.py` — Core Git command wrappers via subprocess`github_api.py` — GitHub API integration for repos and PRs`repository_manager.py` — Bulk repository operations`repository_metadata.py` — Repository metadata tracking`visualization_integration.py` — Visualization features (requires data_visualization module)`docs/technical_overview.md` — Technical design documentation`docs/tutorials/` — How-to guides for specific workflowsInstructions for AI Agent
1. Follow General Conventions First
These rules supplement `general.cursorrules`. Always adhere to general Codomyrmex conventions unless explicitly overridden here.
2. Python API Implementation Standards
**Subprocess Security (Critical):**
Use `subprocess.run()` for all Git operationsALWAYS pass commands as lists: `subprocess.run(["git", "status"], ...)`NEVER use `shell=True` with user inputAll user-provided strings must be list elements (prevents command injection)Use `cwd` parameter to specify repository path (don't change directories)**Code Quality:**
Follow PEP 8 guidelines strictlyAdd comprehensive docstrings to all public functions (parameters, return values, behavior)Keep `API_SPECIFICATION.md` as the source of truth — ensure implementation matches spec**Error Handling Philosophy:**
Functions return `False`/`None`/empty collections on error (don't raise exceptions)Catch all `subprocess` exceptions and return typed resultsLog all errors via `logging_monitoring` moduleAllows callers to check results without try/except, but requires careful return value checking**Structured Outputs:**
Return structured data (dicts, lists) instead of raw Git output stringsParse Git command output into usable Python structures where applicable**Logging & Monitoring:**
Integrate with `logging_monitoring` module for all significant operationsLog operation parameters (exclude sensitive data like credentials)Log success/failure status for auditingUse `@monitor_performance` decorator (from `performance` module) to track operation latency**Design Principles:**
Design functions to be idempotent where Git commands support itPrioritize intuitive, easy-to-use API for consumersConsider cross-platform compatibility (Windows, Linux, macOS) for paths, line endings, credentials3. Testing Requirements
**Unit Tests (`tests/unit/`):**
Test wrapper function logic: argument parsing, subprocess call construction, output parsingMock `subprocess.run()` to simulate Git responses (success, errors, various repo states)Verify error handling and return value typesTest edge cases and invalid inputs to verify subprocess safety**Integration Tests (`tests/integration/`):**
Create temporary Git repositories (`git init` in temp directory)Execute API call sequences (e.g., `create_branch` → `commit_changes` → `get_status`)Assert repository state after operationsClean up temporary repos after testsMark as slower tests if needed (actual Git operations)**Security Testing:**
Test functions with unusual/malicious inputs to verify subprocess safetyEnsure no command injection vulnerabilities4. Security-First Approach
Refer to `SECURITY.md` frequently. Key considerations:
Never expose credentials in logs or error messagesValidate all user inputs before passing to subprocessBe mindful of Git credential helpers and authentication setupDocument security prerequisites clearlyAssume all user input is potentially malicious5. Documentation Maintenance
Keep `API_SPECIFICATION.md` aligned with implementation (source of truth)Update `COMPLETE_API_DOCUMENTATION.md` with examples for new functionsMaintain `README.md` and `docs/technical_overview.md` accuracyKeep tutorials (`docs/tutorials/`) current with API changesDocument security implications and prerequisites clearlyUpdate `CHANGELOG.md` for API changes or significant functionality updates6. Implementation Workflow
When adding or modifying features:
1. **Review** `API_SPECIFICATION.md` to understand expected behavior
2. **Implement** using subprocess list-based command construction
3. **Handle errors** gracefully with logging (no exceptions)
4. **Add tests** (unit tests with mocks, integration tests with temp repos)
5. **Log operations** via `logging_monitoring` module
6. **Document** in API docs and update examples
7. **Security review** — verify subprocess safety and credential handling
8. **Cross-platform check** — consider Windows/Linux/macOS differences
9. **Update changelog** with changes
7. Final Checklist
Before considering any feature complete:
[ ] Implementation matches `API_SPECIFICATION.md`[ ] All subprocess calls use list arguments (never `shell=True`)[ ] Error handling returns typed results with logging[ ] Unit tests added with subprocess mocks[ ] Integration tests added with temporary repos[ ] Security review passed (no injection risks, no credential exposure)[ ] All operations logged via `logging_monitoring`[ ] API documentation updated[ ] Usage examples added/updated[ ] `CHANGELOG.md` updated[ ] Cross-platform compatibility consideredExample Usage Pattern
```python
from git_operations.git_manager import get_status, commit_changes
Get repository status
status = get_status("/path/to/repo")
if status:
print(f"Branch: {status['branch']}")
Commit changes
success = commit_changes(
repo_path="/path/to/repo",
message="Add new feature",
files=["src/feature.py"]
)
if success:
print("Commit successful")
else:
print("Commit failed — check logs")
```
Critical Reminders
**Security is paramount** — this module handles source code and potentially credentials**Never use `shell=True`** with subprocess**Return typed results** on error (don't raise exceptions)**Log everything** significant via `logging_monitoring`**API_SPECIFICATION.md is the contract** — implementation must match**Cross-platform compatibility** matters for Git operations**Test with real Git repos** in integration tests (use temp directories)