From 978e925b60b8e3a7881087f437746dbb482c5771 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Sep 2025 22:53:27 +0200 Subject: [PATCH] feat: Enhance tddai configuration with auto-loading .env files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Configuration System Improvements: - Add automatic .env.tddai file loading without external dependencies - Implement load_dotenv_file() helper for lightweight env file parsing - Maintain configuration hierarchy: Environment → .env.tddai → Defaults - Zero breaking changes - existing setup script approach still works Documentation: - Create comprehensive CONFIG.md with configuration management guide - Document hierarchy, options, platform examples, and troubleshooting - Include migration instructions and best practices - Cover both auto-loading and manual configuration methods Benefits: - Users no longer need to manually source setup scripts - Project-agnostic configuration system remains flexible - Improved developer experience with seamless config loading - Complete documentation for configuration management 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONFIG.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++ tddai/config.py | 19 ++++- 2 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 CONFIG.md diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 00000000..4452e113 --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,201 @@ +# TDDAi Configuration Management + +The tddai framework uses a flexible, hierarchical configuration system designed for project-agnostic deployment while supporting per-project customization. + +## Configuration Hierarchy + +Configuration values are loaded in the following priority order (highest to lowest): + +1. **Environment Variables** - Runtime overrides (highest priority) +2. **`.env.tddai` File** - Project-specific configuration (auto-loaded) +3. **Default Values** - Framework defaults (fallback) + +## Quick Start + +### Automatic Configuration (Recommended) +The framework automatically loads `.env.tddai` from the current directory: + +```bash +# Configuration loaded automatically +make tdd-status +make tdd-start NUM=5 +``` + +### Manual Configuration +You can also source the setup script manually: + +```bash +source tddai-setup.sh +make tdd-status +``` + +## Configuration Options + +### Repository Settings (Required) + +| Variable | Description | Example | Required | +|----------|-------------|---------|----------| +| `TDDAI_GITEA_URL` | Git platform URL | `https://github.com` | ✅ | +| `TDDAI_REPO_OWNER` | Repository owner/org | `myusername` | ✅ | +| `TDDAI_REPO_NAME` | Repository name | `myproject` | ✅ | + +### Workspace Settings (Optional) + +| Variable | Description | Default | Example | +|----------|-------------|---------|---------| +| `TDDAI_WORKSPACE_DIR` | TDD workspace directory | `.tddai_workspace` | `.myproject_workspace` | + +### Test Settings (Framework Defaults) + +| Setting | Value | Description | +|---------|-------|-------------| +| `tests_dir` | `tests/` | Main test directory | +| `test_file_pattern` | `test_issue_{issue_num}_{scenario}.py` | Test file naming pattern | +| `current_issue_file` | `current_issue.json` | Active issue metadata file | + +## Configuration Files + +### `.env.tddai` Format +```bash +# TDDAi configuration for YourProject +# Repository settings +TDDAI_GITEA_URL=https://your-git-platform.com +TDDAI_REPO_OWNER=yourusername +TDDAI_REPO_NAME=yourproject + +# Workspace settings (optional) +TDDAI_WORKSPACE_DIR=.yourproject_workspace +``` + +### `tddai-setup.sh` Format +```bash +#!/bin/bash +# TDDAi environment setup script + +export TDDAI_GITEA_URL=https://your-git-platform.com +export TDDAI_REPO_OWNER=yourusername +export TDDAI_REPO_NAME=yourproject +export TDDAI_WORKSPACE_DIR=.yourproject_workspace + +echo "✅ TDDAi configured for YourProject" +``` + +## Platform Examples + +### GitHub Configuration +```bash +TDDAI_GITEA_URL=https://github.com +TDDAI_REPO_OWNER=yourusername +TDDAI_REPO_NAME=yourrepo +``` + +### GitLab Configuration +```bash +TDDAI_GITEA_URL=https://gitlab.com +TDDAI_REPO_OWNER=yourusername +TDDAI_REPO_NAME=yourrepo +``` + +### Self-hosted Gitea +```bash +TDDAI_GITEA_URL=https://git.yourcompany.com +TDDAI_REPO_OWNER=yourorganization +TDDAI_REPO_NAME=yourproject +``` + +## API Integration + +The configuration automatically constructs API URLs: + +```python +# Constructed from configuration +issues_api_url = f"{TDDAI_GITEA_URL}/api/v1/repos/{TDDAI_REPO_OWNER}/{TDDAI_REPO_NAME}/issues" +``` + +## Workspace Structure + +Default workspace layout (configurable via `TDDAI_WORKSPACE_DIR`): + +``` +.tddai_workspace/ +├── current_issue.json # Active issue metadata +└── issue_X/ # Issue-specific workspace + ├── tests/ # Test files for this issue + │ └── test_issue_X_*.py # Generated test files + ├── requirements.md # Issue requirements analysis + └── test_plan.md # Test planning document +``` + +## Environment Variable Overrides + +You can override any configuration at runtime: + +```bash +# Override workspace directory for this session +TDDAI_WORKSPACE_DIR=.custom_workspace make tdd-start NUM=5 + +# Override repository for testing +TDDAI_REPO_NAME=test_repo make tdd-status +``` + +## Validation + +The framework validates configuration on startup: + +- **Required fields** must be non-empty (`gitea_url`, `repo_owner`, `repo_name`) +- **URLs** should include protocol (`http://` or `https://`) +- **Workspace directories** are created automatically if they don't exist + +## Troubleshooting + +### Common Errors + +**`gitea_url cannot be empty`** +- Solution: Create `.env.tddai` with `TDDAI_GITEA_URL=your-url` +- Alternative: Run `source tddai-setup.sh` before tddai commands + +**`repo_owner cannot be empty`** +- Solution: Set `TDDAI_REPO_OWNER` in `.env.tddai` or environment + +**`repo_name cannot be empty`** +- Solution: Set `TDDAI_REPO_NAME` in `.env.tddai` or environment + +### Debug Configuration +```bash +# Check current configuration +python -c "from tddai.config import get_config; c=get_config(); print(f'URL: {c.gitea_url}\\nOwner: {c.repo_owner}\\nRepo: {c.repo_name}\\nWorkspace: {c.workspace_dir}')" +``` + +## Migration from Other Projects + +When adapting tddai for a new project: + +1. **Copy configuration template**: + ```bash + cp .env.tddai.example .env.tddai + ``` + +2. **Update repository settings**: + ```bash + # Edit .env.tddai + TDDAI_GITEA_URL=https://your-platform.com + TDDAI_REPO_OWNER=your-username + TDDAI_REPO_NAME=your-project + ``` + +3. **Test configuration**: + ```bash + make tdd-status + ``` + +## Best Practices + +- **Use `.env.tddai`** for project-specific settings +- **Use environment variables** for temporary overrides +- **Keep configuration in version control** (but exclude sensitive tokens) +- **Document custom workspace naming** in project README +- **Validate configuration** before starting development sessions + +--- + +*This configuration system supports the TDD8 methodology (ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH) across any software development project with issue tracking.* \ No newline at end of file diff --git a/tddai/config.py b/tddai/config.py index 3cda55d5..6c2933f6 100644 --- a/tddai/config.py +++ b/tddai/config.py @@ -26,6 +26,19 @@ from dataclasses import dataclass from .exceptions import ConfigurationError +def load_dotenv_file(env_file: Path) -> None: + """Load environment variables from a .env file.""" + if not env_file.exists(): + return + + with open(env_file, 'r') as f: + for line in f: + line = line.strip() + if line and not line.startswith('#') and '=' in line: + key, value = line.split('=', 1) + os.environ.setdefault(key.strip(), value.strip()) + + @dataclass class TddaiConfig: """Configuration settings for tddai.""" @@ -58,7 +71,11 @@ class TddaiConfig: @classmethod def from_environment(cls) -> "TddaiConfig": - """Create config from environment variables.""" + """Create config from environment variables and .env files.""" + # Auto-load .env.tddai file if it exists + env_file = Path(".env.tddai") + load_dotenv_file(env_file) + config = cls() # Override with environment variables if present