# Hephaestus Development Commands

## Essential Commands

### Development Setup
```bash
# Install dependencies
uv sync

# Verify installation
just --list

# Run initial tests
just test
```

### Running the Server
```bash
# Run MCP server (stdio transport - default)
just run

# Run with HTTP transport for development
just run-http

# Run directly with uv
uv run python -m src.server

# Run with custom arguments
uv run python -m src.server --host localhost --port 8000 --transport http
```

### Code Quality
```bash
# Lint code
just lint

# Format code
just format

# Type check code
just typecheck

# Run all quality checks together
just lint && just format && just typecheck
```

### Testing
```bash
# Run tests
just test

# Run tests with coverage
just test-coverage

# Run specific test file
uv run python -m pytest tests/test_specific.py -v

# Run tests with specific pattern
uv run python -m pytest tests/ -k "test_pattern" -v
```

### Building & Publishing
```bash
# Build package
just build

# Clean build artifacts
just clean

# Version bumping
just bump-patch    # 0.1.0 -> 0.1.1
just bump-minor    # 0.1.0 -> 0.2.0
just bump-major    # 0.1.0 -> 1.0.0

# Publish to TestPyPI
just publish-test

# Publish to PyPI
just publish
```

## System Utilities

### File Operations
```bash
# List directory contents
ls -la

# Find files by pattern
find . -name "*.py" -type f

# Search in files
grep -r "pattern" src/

# Show file contents
cat file.txt

# Edit files (use appropriate editor)
nano file.txt
vim file.txt
```

### Git Operations (GitHub Mirror)
```bash
# Note: Git operations are primarily for GitHub mirror sync
# Main development happens via Radicle

# Check status
git status

# Add files
git add .

# Commit changes
git commit -m "Descriptive commit message"

# Push to GitHub mirror
git push

# Pull from GitHub mirror
git pull

# Check history
git log --oneline -10

# Create branch
git checkout -b feature-name

# Switch branches
git checkout main
```

### Radicle Operations (via MCP)

Hephaestus uses radicle-mcp-server for seamless Radicle operations. Most Radicle tasks are handled through MCP tools rather than direct CLI commands:

#### Project Management
- Issue tracking and management via MCP tools
- Repository inspection and status
- Phase-based development tracking
- Decentralized collaboration features

#### Development Workflow
- Use MCP tools for Radicle operations
- Leverage radicle-mcp-server integration
- Focus on development rather than CLI commands
- Automatic synchronization with GitHub mirror

#### Key Benefits
- Seamless integration with development workflow
- No need to learn Radicle CLI in detail
- MCP-based issue and project management
- Automatic GitHub mirroring

## Development Workflow Commands

### Before Making Changes
```bash
# Ensure clean working directory
git status

# Pull latest changes
git pull

# Run tests to ensure baseline
just test

# Check code quality
just lint && just typecheck
```

### After Making Changes
```bash
# Format code
just format

# Lint code
just lint

# Type check
just typecheck

# Run tests
just test

# If all passes, commit changes
git add .
git commit -m "Descriptive commit message"
```

### Before Submitting Changes
```bash
# Ensure all tests pass
just test

# Check code quality
just lint && just format && just typecheck

# Build package to ensure it works
just build

# Check git status for uncommitted changes
git status

# For Radicle-based development:
# - Changes are tracked via Radicle issues
# - Use MCP tools for project management
# - GitHub mirror updates automatically
```

## MCP Server Specific Commands

### Testing MCP Server
```bash
# Test server startup
timeout 5 uv run python -m src.server || echo "Server started successfully"

# Test with different transports
uv run python -m src.server --transport stdio &
uv run python -m src.server --transport http --host localhost --port 8000 &

# Kill background processes
pkill -f "src.server"
```

### Development Server
```bash
# Run in development mode with auto-reload (if implemented)
uv run python -m src.server --dev

# Run with verbose logging
uv run python -m src.server --verbose

# Run with custom configuration
uv run python -m src.server --config config.yaml
```

## Package Management

### UV Commands
```bash
# Add dependency
uv add package-name

# Add dev dependency
uv add --dev package-name

# Remove dependency
uv remove package-name

# Update dependencies
uv sync

# Check for outdated packages
uv tree

# Run command in environment
uv run command
```

### Python Commands
```bash
# Check Python version
python --version

# Run Python module
python -m module.name

# Install package in development mode
pip install -e .

# Check installed packages
pip list
```

## Troubleshooting Commands

### Common Issues
```bash
# Clear Python cache
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

# Clear uv cache
uv cache clean

# Reinstall dependencies
uv sync --reinstall

# Check environment
uv run python -c "import sys; print(sys.executable)"

# Debug imports
uv run python -c "import fastmcp; print('fastmcp imported successfully')"
```

### Performance Monitoring
```bash
# Check system resources
top
htop

# Check disk usage
df -h

# Check memory usage
free -h

# Monitor file changes
inotifywait -r .  # if inotify-tools is installed
```

## Documentation Commands

### Generating Documentation
```bash
# If using Sphinx (when implemented)
cd docs/
make html

# Serve documentation locally
python -m http.server 8000 --directory docs/_build/html/

# Check documentation links
python -m sphinx.ext.intersphinx docs/_build/html/
```

### Code Documentation
```bash
# Generate API docs (when implemented)
uv run python -m sphinx.ext.autodoc src/

# Check docstring coverage
uv run python -m docstring_coverage src/
```