feat: Enhance tddai configuration with auto-loading .env files
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 <noreply@anthropic.com>
This commit is contained in:
201
CONFIG.md
Normal file
201
CONFIG.md
Normal file
@@ -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.*
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user