dss/dss-mvp1/SETTINGS.md

DSS Settings & Management

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

Quick Start

# 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

# 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

# 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

python3 -m dss.settings test

Unit Tests Only

python3 -m dss.settings test-unit

Integration Tests Only

python3 -m dss.settings test-integration

With Coverage Report

python3 -m dss.settings test-coverage

Specific Test File

python3 -m dss.settings test tests/unit/test_models.py

Reset DSS

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

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

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.

# 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.

manager.run_unit_tests()

run_integration_tests()

Shortcut for running integration tests only.

manager.run_integration_tests()

run_all_tests_with_coverage()

Run all tests with coverage report.

manager.run_all_tests_with_coverage()

reset_dss(keep_structure=True, confirm=True)

Reset DSS to fresh state.

# With confirmation prompt
results = manager.reset_dss()

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

Returns:

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

get_system_info()

Get DSS system information.

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

check_dependencies()

Check installed dependencies.

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:

# 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:

# 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

# 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

# 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:

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

Examples

Daily Development Workflow

# 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

# 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

# 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 - Project overview
• .env.test - Test environment template
• requirements.txt - Python dependencies
• package.json - Node.js dependencies