dss/dss-mvp1/SETTINGS.md

# DSS Settings & Management

Complete guide for DSS configuration, testing, and system management.

## Quick Start

```bash
# Check system information
python3 -m dss.settings info

# Check dependencies
python3 -m dss.settings check-deps

# Run all tests
python3 -m dss.settings test

# Reset DSS to fresh state
python3 -m dss.settings reset
```

## Commands

### System Information

```bash
# Show DSS configuration and paths
python3 -m dss.settings info
```

**Output:**
```
📊 DSS System Information:
   project_root: /path/to/dss-mvp1
   dss_dir: /path/to/dss-mvp1/dss
   tests_dir: /path/to/dss-mvp1/tests
   cache_dir: /home/user/.dss/cache
   database_path: /home/user/.dss/dss.db
   has_anthropic_key: True/False
   has_figma_token: True/False
   use_mock_apis: True
```

### Dependency Check

```bash
# Verify all required dependencies are installed
python3 -m dss.settings check-deps
```

**Checks:**
- ✅ pydantic
- ✅ fastapi
- ✅ pytest
- ✅ requests
- ✅ style-dictionary (Node.js)

### Running Tests

#### All Tests
```bash
python3 -m dss.settings test
```

#### Unit Tests Only
```bash
python3 -m dss.settings test-unit
```

#### Integration Tests Only
```bash
python3 -m dss.settings test-integration
```

#### With Coverage Report
```bash
python3 -m dss.settings test-coverage
```

#### Specific Test File
```bash
python3 -m dss.settings test tests/unit/test_models.py
```

### Reset DSS

Reset DSS to fresh state, deleting all user data but keeping structure.

```bash
python3 -m dss.settings reset
```

**⚠️ WARNING:** This will prompt for confirmation and delete:
- User-created themes (keeps default themes)
- Cache directory
- Figma cache
- Database files
- Test database
- `__pycache__` directories

**Keeps:**
- Directory structure
- Default themes
- Source code
- Configuration files
- Test fixtures

**Confirmation Required:**
```
⚠️  WARNING: This will delete all themes, projects, and cached data.
   The DSS structure will be preserved.
   Type 'RESET' to confirm:
```

Type `RESET` (exactly) to proceed.

## Python API Usage

### Using Settings in Code

```python
from dss.settings import settings, manager

# Access configuration
print(settings.PROJECT_ROOT)
print(settings.ANTHROPIC_API_KEY)

# Run tests programmatically
result = manager.run_tests("tests/unit/")

# Get system info
info = manager.get_system_info()

# Check dependencies
deps = manager.check_dependencies()
```

### DSSSettings

Configuration class using Pydantic Settings.

**Attributes:**
- `PROJECT_ROOT: Path` - Project root directory
- `DSS_DIR: Path` - DSS source directory
- `TESTS_DIR: Path` - Tests directory
- `CACHE_DIR: Path` - Cache directory (~/.dss/cache)
- `ANTHROPIC_API_KEY: Optional[str]` - Claude API key
- `FIGMA_TOKEN: Optional[str]` - Figma API token
- `FIGMA_FILE_KEY: Optional[str]` - Figma file key
- `DATABASE_PATH: Path` - Main database path
- `TEST_DATABASE_PATH: Path` - Test database path
- `USE_MOCK_APIS: bool` - Use mock APIs in tests

**Configuration:**
- Reads from `.env` file
- Case-sensitive environment variables
- Ignores extra fields

### DSSManager

Management utility class.

**Methods:**

#### `run_tests(test_path=None, verbose=True, coverage=False, markers=None)`
Run pytest test suite.

```python
# Run all tests
manager.run_tests()

# Run specific file
manager.run_tests("tests/unit/test_models.py")

# Run with markers
manager.run_tests(markers="unit")

# Run with coverage
manager.run_tests(coverage=True)
```

#### `run_unit_tests()`
Shortcut for running unit tests only.

```python
manager.run_unit_tests()
```

#### `run_integration_tests()`
Shortcut for running integration tests only.

```python
manager.run_integration_tests()
```

#### `run_all_tests_with_coverage()`
Run all tests with coverage report.

```python
manager.run_all_tests_with_coverage()
```

#### `reset_dss(keep_structure=True, confirm=True)`
Reset DSS to fresh state.

```python
# With confirmation prompt
results = manager.reset_dss()

# Without confirmation (dangerous!)
results = manager.reset_dss(confirm=False)
```

**Returns:**
```python
{
    "status": "success",
    "deleted": ["file1.py", "cache/", ...],
    "kept": ["default_themes.py", "models/", ...],
    "errors": []
}
```

#### `get_system_info()`
Get DSS system information.

```python
info = manager.get_system_info()
# {
#     "project_root": "/path/to/project",
#     "dss_dir": "/path/to/dss",
#     ...
# }
```

#### `check_dependencies()`
Check installed dependencies.

```python
deps = manager.check_dependencies()
# {
#     "pydantic": True,
#     "fastapi": True,
#     "pytest": True,
#     "requests": True,
#     "style-dictionary": True
# }
```

## Environment Variables

Create a `.env` file in the project root:

```bash
# API Keys
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
FIGMA_TOKEN=your-figma-token-here
FIGMA_FILE_KEY=your-file-key-here

# Database
DATABASE_PATH=/home/user/.dss/dss.db

# Testing
USE_MOCK_APIS=true
```

See `.env.test` for test environment example.

## Test Fixtures

Mock API keys are available in `tests/fixtures/api_keys.json`:

```python
# In tests
def test_my_feature(mock_anthropic_key, mock_figma_token):
    # Use mock keys automatically
    wrapper = FigmaWrapper(api_token=mock_figma_token, ...)
```

## Troubleshooting

### Missing Dependencies

```bash
# Check what's missing
python3 -m dss.settings check-deps

# Install Python dependencies
pip install -r requirements.txt

# Install Node dependencies
npm install
```

### API Keys Not Loaded

1. Create `.env` file in project root
2. Add your API keys
3. Verify with `python3 -m dss.settings info`

### Tests Failing

```bash
# Run tests with verbose output
python3 -m dss.settings test -v

# Run specific failing test
python3 -m dss.settings test tests/unit/test_models.py::TestTheme::test_specific
```

### Reset Not Working

Ensure you type `RESET` exactly (all caps) when prompted.

Or use Python API without confirmation:

```python
from dss.settings import manager
results = manager.reset_dss(confirm=False)
```

## Examples

### Daily Development Workflow

```bash
# 1. Check system is ready
python3 -m dss.settings check-deps

# 2. Run tests before making changes
python3 -m dss.settings test-unit

# 3. Make your changes...

# 4. Run tests again
python3 -m dss.settings test

# 5. If tests pass, commit!
git add .
git commit -m "Your changes"
```

### Setting Up New Environment

```bash
# 1. Install dependencies
pip install -r requirements.txt
npm install

# 2. Create .env file
cp .env.test .env

# 3. Add your real API keys to .env

# 4. Verify setup
python3 -m dss.settings info
python3 -m dss.settings check-deps

# 5. Run tests to confirm
python3 -m dss.settings test
```

### Starting Fresh

```bash
# Reset everything
python3 -m dss.settings reset

# Verify reset
python3 -m dss.settings info

# Run tests to ensure structure intact
python3 -m dss.settings test
```

## See Also

- [README.md](README.md) - Project overview
- [.env.test](.env.test) - Test environment template
- [requirements.txt](requirements.txt) - Python dependencies
- [package.json](package.json) - Node.js dependencies