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/TEST_STRATEGY.md
+++ b/.dss/TEST_STRATEGY.md
@@ -0,0 +1,272 @@
+# Comprehensive Test Strategy: Phases 6-8 & Figma Integration
+
+**Date**: 2025-12-05
+**Purpose**: Test complete flow from Figma → DSS → Storybook with self-referential design system
+**Status**: PLANNING
+
+---
+
+## Architecture Overview: Self-Referential Design System
+
+```
+Figma Design File (Source of Truth)
+    ↓
+DSS Figma Extractor (Phase 7)
+    ↓
+Token/Asset Database
+    ↓
+DSS Component Library (Built using own tokens)
+    ↓
+Storybook (Stories showcase DSS using DSS tokens)
+    ↓
+Output Formats (CSS, JSON, TS, etc.)
+    ↓
+Integration Tests (Verify full loop)
+```
+
+**Key Challenge**: DSS components consume tokens that came from Figma, which were designed to match DSS components. This is intentional (eating your own dogfood).
+
+---
+
+## Test Layers Strategy
+
+### Layer 1: Unit Tests (Individual Modules)
+- Config loader initialization
+- Component registry management
+- Audit logging functionality
+- Workflow persistence snapshots
+- Route guard validation
+- Error recovery mechanisms
+
+### Layer 2: Integration Tests
+- Config → Component Registry flow
+- Figma extraction → Token sync
+- Error handling with recovery points
+- Permission checks with logging
+- State persistence and restoration
+
+### Layer 3: Figma API Tests
+- Real Figma file connection
+- Variable extraction from DSS file
+- Component definition extraction
+- Style and asset extraction
+- Token format conversion
+
+### Layer 4: End-to-End Tests
+- Complete Figma → DSS → Storybook workflow
+- Token sync across all formats
+- Error recovery in full flow
+- Multi-format export validation
+
+### Layer 5: Visual Regression Tests
+- Storybook stories using DSS tokens
+- Component rendering with real tokens
+- Theme switching with token variables
+- Chromatic visual testing
+
+### Layer 6: Snapshot Tests
+- Token export format stability
+- Component rendering consistency
+- Output format preservation
+
+---
+
+## Testing Tools & Setup
+
+### Required Dependencies
+```json
+{
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "jest-environment-jsdom": "^29.0.0",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/jest-dom": "^6.0.0",
+    "pytest": "^7.0.0",
+    "pytest-asyncio": "^0.21.0",
+    "@storybook/test-runner": "^0.13.0",
+    "@chromatic-com/storybook": "^1.0.0"
+  }
+}
+```
+
+### Test File Structure
+```
+project/
+├── admin-ui/js/core/__tests__/
+│   ├── config-loader.test.js
+│   ├── component-config.test.js
+│   ├── workflow-persistence.test.js
+│   ├── audit-logger.test.js
+│   ├── route-guards.test.js
+│   ├── error-recovery.test.js
+│   ├── config-component-integration.test.js
+│   └── phase8-integration.test.js
+│
+├── admin-ui/__tests__/
+│   ├── e2e-full-workflow.test.js
+│   └── __snapshots__/
+│
+├── dss-mvp1/src/__tests__/
+│   ├── component-rendering.test.jsx
+│   └── __snapshots__/
+│
+├── dss-mvp1/.storybook/
+│   └── test-setup.js
+│
+└── tools/api/tests/
+    ├── test_figma_integration.py
+    ├── test_token_formats.py
+    ├── test_token_snapshots.py
+    └── __snapshots__/
+```
+
+---
+
+## Test Execution Matrix
+
+### Environment Variables Required
+```bash
+# Figma Integration
+export FIGMA_API_KEY="figd_xxxxxxxxxxxx"
+export DSS_FIGMA_FILE_KEY="xxxxxxxxxxxx"  # Main DSS design file
+export DSS_TEST_FIGMA_FILE="yyyyyyyyyyyy" # Disposable test file
+
+# DSS Configuration
+export DSS_HOST="dss.overbits.luz.uy"
+export DSS_PORT="3456"
+export STORYBOOK_PORT="6006"
+
+# Test Configuration
+export TEST_ENV="test"
+export VERBOSE_TESTS="true"
+```
+
+### Test Commands
+```bash
+# Run all tests
+npm run test
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests
+npm run test:integration
+
+# Figma real-file tests (requires API key)
+npm run test:figma
+
+# E2E tests (requires running server)
+npm run test:e2e
+
+# Visual regression tests (Storybook)
+npm run test:visual
+
+# With coverage report
+npm run test -- --coverage
+
+# Watch mode for development
+npm run test -- --watch
+
+# Single test file
+npm run test -- config-loader.test.js
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Unit Tests (This Week)
+Create test files for:
+1. config-loader.js
+2. component-config.js
+3. All Phase 8 modules
+
+Target: 80%+ coverage
+
+### Phase 2: Figma Integration (Next Week)
+1. Test real Figma file connection
+2. Test token extraction
+3. Test component extraction
+4. Create token export modules
+
+Target: Full workflow validation
+
+### Phase 3: Storybook Setup (Week After)
+1. Configure Storybook with DSS tokens
+2. Create component stories using tokens
+3. Setup visual regression testing
+4. Chromatic integration
+
+Target: Visual consistency
+
+### Phase 4: CI/CD (Final Week)
+1. GitHub Actions workflow
+2. Automated test runs on push
+3. Coverage reporting
+4. Visual regression tracking
+
+Target: Automated quality gates
+
+---
+
+## Success Criteria
+
+| Layer | Coverage | Pass Rate | Requirement |
+|-------|----------|-----------|-------------|
+| Unit | >80% | 100% | All modules |
+| Integration | >70% | 100% | All interactions |
+| Figma API | N/A | 100% | Real extraction |
+| E2E | >60% | 100% | Full workflow |
+| Visual | >90% | 100% | Component rendering |
+| **Overall** | **>75%** | **100%** | Production ready |
+
+---
+
+## Key Test Scenarios
+
+### Scenario 1: Blank State → Full Import
+- Load app (config not cached)
+- Connect to Figma
+- Extract all tokens, components, styles
+- Import into database
+- Verify all formats work
+
+### Scenario 2: Crash & Recovery
+- Create recovery point
+- Simulate error
+- Verify error logged
+- Restore from recovery point
+- Resume operation
+
+### Scenario 3: Figma Update → DSS Sync
+- Get latest Figma file
+- Extract changed tokens only
+- Sync to DSS
+- Update Storybook
+- Verify visual changes
+
+### Scenario 4: Multi-Format Export
+- Extract from Figma
+- Export as CSS variables
+- Export as JSON
+- Export as TypeScript
+- Verify all formats match
+
+### Scenario 5: Permission Enforcement
+- Attempt unauthorized action
+- Verify guard blocks access
+- Check audit log
+- Verify error recovery
+
+---
+
+## Next Immediate Actions
+
+1. ✅ Create test strategy document (this file)
+2. 🔄 Create unit test files for all modules
+3. 🔄 Setup Figma test environment
+4. 🔄 Create token format exporters
+5. 🔄 Setup Storybook with DSS tokens
+6. 🔄 Create end-to-end tests
+
+All test files will be provided next in this session.