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-claude-plugin/README.md
+++ b/dss-claude-plugin/README.md
@@ -0,0 +1,565 @@
+# DSS Claude Plugin
+
+Design System Swarm (DSS) integration for Claude Code - A comprehensive plugin for analyzing, extracting, and generating design system tokens and components.
+
+## Overview
+
+The DSS Claude Plugin brings the power of DSS directly into Claude Code, enabling:
+
+- **Project Analysis**: Scan codebases for design patterns and tokenization opportunities
+- **Token Extraction**: Extract design tokens from CSS, SCSS, Tailwind, and JSON
+- **Theme Generation**: Generate theme files using style-dictionary
+- **Component Auditing**: Audit components for design system adoption
+- **Storybook Integration**: Set up and configure Storybook
+- **Figma Sync**: Import tokens directly from Figma files
+- **Quick Wins**: Find low-effort, high-impact improvements
+
+## Installation
+
+### Local Development Setup
+
+For local machines with GUI (desktop/laptop):
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/overbits/dss.git
+cd dss
+
+# 2. Run the setup script
+./setup.sh
+
+# 3. Install the plugin in Claude Code
+claude /plugin install ./dss-claude-plugin
+```
+
+Or manually:
+
+```bash
+# 1. Create and activate virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 2. Install dependencies
+pip install -r requirements.txt
+playwright install chromium
+
+# 3. Install the plugin
+claude /plugin install ./dss-claude-plugin
+```
+
+### Remote/Headless Server Setup
+
+For remote servers, VPS, Docker, or CI/CD environments:
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/overbits/dss.git
+cd dss
+
+# 2. Install dependencies (headless mode)
+pip install -r requirements.txt
+playwright install chromium --with-deps  # Installs system dependencies
+
+# 3. Install the plugin in Claude Code
+claude /plugin install ./dss-claude-plugin
+```
+
+**Docker Setup:**
+
+```dockerfile
+FROM python:3.10-slim
+
+# Install system dependencies for Playwright
+RUN apt-get update && apt-get install -y \
+    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
+    libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
+    libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2
+
+WORKDIR /app
+COPY . .
+
+RUN pip install -r requirements.txt
+RUN playwright install chromium
+
+# DSS MCP server runs on stdio
+CMD ["python3", "dss-claude-plugin/servers/dss-mcp-server.py"]
+```
+
+### Claude Code Configuration
+
+After installing the plugin, Claude Code automatically configures the MCP server. The configuration is stored in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dss": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/dss-mcp-server.py"],
+      "env": {
+        "PYTHONPATH": "/path/to/dss/dss-mvp1",
+        "DSS_HOME": "~/.dss"
+      }
+    }
+  }
+}
+```
+
+### Connecting Local Claude Code to Remote Server
+
+You can run Claude Code locally while connecting to a DSS MCP server running on a remote machine.
+
+#### Option 1: SSH Tunnel (Recommended)
+
+Create an SSH tunnel to forward the remote MCP server:
+
+```bash
+# On local machine - tunnel remote MCP server
+ssh -L 9222:localhost:9222 -L 3456:localhost:3456 user@remote-server
+```
+
+This forwards:
+- Port 9222: Chrome DevTools Protocol
+- Port 3456: Your web application
+
+Then use `devtools_connect(port=9222)` as if it were local.
+
+#### Option 2: Remote MCP via SSH
+
+Configure Claude Code to run the MCP server over SSH. Add to your local `~/.claude/settings.json` or project `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dss-remote": {
+      "command": "ssh",
+      "args": [
+        "user@remote-server",
+        "python3",
+        "/home/user/dss/dss-claude-plugin/servers/dss-mcp-server.py"
+      ],
+      "env": {
+        "PYTHONPATH": "/home/user/dss/dss-mvp1"
+      },
+      "description": "Remote DSS MCP server via SSH"
+    }
+  }
+}
+```
+
+#### Option 3: HTTP Proxy (Advanced)
+
+For shared team access, run the MCP server behind an HTTP proxy:
+
+```bash
+# On remote server - start MCP with HTTP transport
+# (Requires mcp-proxy or similar)
+python3 -m mcp.server.http --port 8080 dss-claude-plugin/servers/dss-mcp-server.py
+```
+
+Then configure Claude Code to connect via HTTP:
+
+```json
+{
+  "mcpServers": {
+    "dss-remote": {
+      "url": "http://remote-server:8080",
+      "transport": "http"
+    }
+  }
+}
+```
+
+#### Option 4: VS Code Remote / SSH Workspace
+
+If using Claude Code in VS Code with Remote SSH extension:
+
+1. Connect VS Code to remote server via Remote SSH
+2. Install Claude Code extension in remote context
+3. DSS plugin runs natively on remote - no tunneling needed
+
+### Verify Installation
+
+```bash
+# Check DSS tools are available
+claude --list-tools | grep dss
+
+# Check DevTools are available (requires Playwright)
+claude --list-tools | grep devtools
+
+# Test the MCP server directly
+echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 dss-claude-plugin/servers/dss-mcp-server.py
+```
+
+## Requirements
+
+- Claude Code >= 1.0.0
+- Python 3.10+
+- Node.js 18+ (for style-dictionary)
+- DSS MVP1 installed at `/path/to/dss/dss-mvp1`
+
+### Python Dependencies
+
+```bash
+pip install mcp pydantic pydantic-settings playwright aiohttp
+playwright install chromium
+```
+
+Or run the full setup:
+```bash
+./setup.sh
+```
+
+### Optional: Figma Integration
+
+Set your Figma personal access token:
+```bash
+export FIGMA_TOKEN=your-figma-token
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/dss-analyze [path]` | Analyze project for design system patterns |
+| `/dss-extract [path] [sources]` | Extract design tokens |
+| `/dss-generate <format> [name]` | Generate theme files |
+| `/dss-audit [path]` | Audit components for DS adoption |
+| `/dss-storybook <action> [path]` | Storybook setup and configuration |
+| `/dss-figma <file_key>` | Sync tokens from Figma |
+| `/dss-quick-wins [path]` | Find quick win opportunities |
+
+## Skills
+
+The plugin includes 7 procedural skills:
+
+1. **design-system-analysis** - Comprehensive codebase analysis
+2. **token-extraction** - Multi-source token extraction
+3. **theme-generation** - Style-dictionary theme generation
+4. **component-audit** - React component auditing
+5. **storybook-integration** - Storybook setup and stories
+6. **figma-sync** - Figma API integration
+7. **quick-wins** - Quick win identification
+
+## Agents
+
+Two specialized agents for complex tasks:
+
+### DSS Architect
+Planning and designing design system implementations.
+```
+"Help me plan a design system for our React application"
+```
+
+### DSS Migrator
+Migrating existing codebases to design systems.
+```
+"Help me migrate our button components to use design tokens"
+```
+
+## MCP Tools
+
+The plugin exposes DSS tools and Chrome DevTools tools:
+
+### DSS Tools
+
+| Tool | Description |
+|------|-------------|
+| `dss_analyze_project` | Full project analysis |
+| `dss_extract_tokens` | Extract tokens from sources |
+| `dss_generate_theme` | Generate theme files |
+| `dss_list_themes` | List available themes |
+| `dss_get_status` | Get DSS system status |
+| `dss_audit_components` | Component audit |
+| `dss_setup_storybook` | Storybook configuration |
+| `dss_sync_figma` | Figma token sync |
+| `dss_find_quick_wins` | Quick win analysis |
+| `dss_transform_tokens` | Token format transformation |
+
+### Chrome DevTools Tools
+
+| Tool | Description |
+|------|-------------|
+| `devtools_launch` | Launch headless Chromium (for remote/headless servers) |
+| `devtools_connect` | Connect to running Chrome with CDP (port 9222) |
+| `devtools_disconnect` | Disconnect and clean up resources |
+| `devtools_list_pages` | List all browser tabs/pages |
+| `devtools_select_page` | Select active page for operations |
+| `devtools_goto` | Navigate to a URL |
+| `devtools_console_logs` | Get captured console messages |
+| `devtools_network_requests` | Get captured network activity |
+| `devtools_evaluate` | Execute JavaScript in page context |
+| `devtools_query_dom` | Query DOM elements with CSS selector |
+| `devtools_screenshot` | Capture page/element screenshots (base64 PNG) |
+| `devtools_performance` | Get Core Web Vitals and performance metrics |
+
+## Hooks
+
+The plugin includes hooks for automation:
+
+- **PreToolUse**: Validates Figma token before sync
+- **PostToolUse**: Logs completion of major operations
+
+## Usage Examples
+
+### Analyze a Project
+
+```
+/dss-analyze /path/to/project
+```
+
+Returns comprehensive analysis including:
+- File counts and types
+- Style patterns discovered
+- Component analysis
+- Recommendations
+
+### Extract and Generate Tokens
+
+```
+/dss-extract /path/to/styles css,scss
+/dss-generate css my-theme
+```
+
+### Audit Components
+
+```
+/dss-audit /path/to/components
+```
+
+Identifies:
+- Hardcoded values
+- Consolidation opportunities
+- Refactoring suggestions
+
+### Sync from Figma
+
+```
+/dss-figma abc123xyz456
+```
+
+Extracts:
+- Colors from fill styles
+- Typography from text styles
+- Spacing from auto-layout
+- Effects and shadows
+
+## Chrome DevTools Integration
+
+The plugin includes Chrome DevTools Protocol (CDP) integration for browser debugging, console capture, network monitoring, and performance analysis.
+
+### Remote/Headless Server Setup
+
+For remote or headless servers (no GUI), use the `devtools_launch` tool to spawn a headless Chromium instance:
+
+```python
+# 1. Launch headless browser and navigate to your app
+devtools_launch(url="http://localhost:3456")
+
+# 2. Get console logs
+devtools_console_logs()
+
+# 3. Navigate to another page
+devtools_goto(url="http://localhost:3456/dashboard")
+
+# 4. Capture screenshot
+devtools_screenshot(full_page=True)
+
+# 5. Get performance metrics
+devtools_performance()
+
+# 6. Execute JavaScript
+devtools_evaluate(expression="document.title")
+
+# 7. Query DOM
+devtools_query_dom(selector=".error-message")
+
+# 8. Clean up
+devtools_disconnect()
+```
+
+### Local Desktop Setup
+
+For local development with Chrome GUI, launch Chrome with remote debugging enabled:
+
+```bash
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+Then connect using the `devtools_connect` tool:
+
+```python
+# 1. Connect to running Chrome
+devtools_connect(port=9222)
+
+# 2. List available tabs
+devtools_list_pages()
+
+# 3. Select a tab
+devtools_select_page(page_id="...")
+
+# 4. Capture console logs, network, etc.
+devtools_console_logs()
+devtools_network_requests()
+
+# 5. Disconnect when done
+devtools_disconnect()
+```
+
+### DevTools Configuration
+
+The MCP server includes configurable limits:
+
+```python
+DEVTOOLS_CONSOLE_MAX_ENTRIES = 1000    # Max console messages stored
+DEVTOOLS_NETWORK_MAX_ENTRIES = 500     # Max network requests stored
+DEVTOOLS_CONNECTION_TIMEOUT_MS = 30000 # Connection timeout (30s)
+```
+
+### Common Use Cases
+
+**Debug Console Errors:**
+```python
+devtools_launch(url="http://localhost:3000")
+devtools_console_logs(level="error")
+```
+
+**Monitor Network Requests:**
+```python
+devtools_launch(url="http://localhost:3000")
+devtools_network_requests(filter_url="api/")
+```
+
+**Performance Analysis:**
+```python
+devtools_launch(url="http://localhost:3000")
+devtools_performance()
+# Returns: FCP, LCP, TTFB, DOM metrics
+```
+
+**Visual Regression Testing:**
+```python
+devtools_launch(url="http://localhost:3000")
+devtools_screenshot(full_page=True)
+# Returns: base64 PNG image
+```
+
+## Architecture
+
+```
+dss-claude-plugin/
+├── .claude-plugin/
+│   └── plugin.json           # Plugin metadata
+├── commands/                  # 7 slash commands
+├── skills/                    # 7 procedural skills
+├── agents/                    # 2 specialized agents
+├── hooks/
+│   └── hooks.json            # Event hooks
+├── servers/
+│   └── dss-mcp-server.py     # Python MCP server
+├── .mcp.json                 # MCP configuration
+└── README.md
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FIGMA_TOKEN` | Figma personal access token |
+| `DSS_HOME` | DSS home directory (default: ~/.dss) |
+| `PYTHONPATH` | Path to DSS MVP1 modules |
+
+### Timeouts
+
+The MCP server includes configurable timeouts:
+
+```python
+TIMEOUT_CONFIG = {
+    "analyze": 60,           # Large project scanning
+    "extract": 30,           # Token extraction
+    "generate": 30,          # Theme generation
+    "figma_api": 15,         # Figma API calls
+    "storybook": 60,         # Storybook operations
+    "devtools_connect": 20,  # DevTools CDP connection
+    "devtools_default": 10,  # DevTools operations
+}
+```
+
+## Development
+
+### Running the MCP Server Directly
+
+```bash
+cd /home/overbits/dss/dss-claude-plugin
+python3 servers/dss-mcp-server.py
+```
+
+### Testing
+
+```bash
+# Test MCP server
+echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 servers/dss-mcp-server.py
+```
+
+## Troubleshooting
+
+### DSS Modules Not Found
+
+Ensure PYTHONPATH is set correctly:
+```bash
+export PYTHONPATH=/home/overbits/dss/dss-mvp1
+```
+
+### Figma Sync Fails
+
+1. Check FIGMA_TOKEN is set
+2. Verify file key is correct
+3. Check API rate limits
+
+### Slow Analysis
+
+For large projects, analysis may take longer. The timeout is set to 60 seconds by default.
+
+### DevTools Launch Fails
+
+1. Ensure Playwright is installed: `pip install playwright`
+2. Install Chromium browser: `playwright install chromium`
+3. On Docker/remote: ensure `--no-sandbox` flag is used (handled automatically)
+
+### DevTools Connect Fails
+
+1. Ensure Chrome is running with: `--remote-debugging-port=9222`
+2. Check the port is not blocked by firewall
+3. Verify connection: `curl http://localhost:9222/json`
+
+### DevTools Playwright Not Available
+
+The server gracefully degrades if Playwright isn't installed. DevTools tools will not appear in the tool list. Install with:
+
+```bash
+pip install playwright aiohttp
+playwright install chromium
+```
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Author
+
+overbits - https://overbits.luz.uy
+
+## Links
+
+- [DSS Homepage](https://dss.overbits.luz.uy)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Claude Code](https://claude.ai/code)
+- [Style Dictionary](https://amzn.github.io/style-dictionary)