Initial commit: Clean DSS implementation

Migrated from design-system-swarm with fresh git history. Old project history preserved in /home/overbits/apps/design-system-swarm Core components: - MCP Server (Python FastAPI with mcp 1.23.1) - Claude Plugin (agents, commands, skills, strategies, hooks, core) - DSS Backend (dss-mvp1 - token translation, Figma sync) - Admin UI (Node.js/React) - Server (Node.js/Express) - Storybook integration (dss-mvp1/.storybook) Self-contained configuration: - All paths relative or use DSS_BASE_PATH=/home/overbits/dss - PYTHONPATH configured for dss-mvp1 and dss-claude-plugin - .env file with all configuration - Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability Migration completed: $(date) 🤖 Clean migration with full functionality preserved
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
--- a/dss-mvp1/SETTINGS.md
+++ b/dss-mvp1/SETTINGS.md
@@ -0,0 +1,380 @@
+# 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