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/docs/CODE_INTEGRATION_GUIDE.md
+++ b/docs/CODE_INTEGRATION_GUIDE.md
@@ -0,0 +1,518 @@
+# 🧬 DSS Organism Framework: Code Integration Guide
+
+**How to integrate organism vocabulary into DSS code, messages, and logging.**
+
+---
+
+## Overview
+
+The organism framework has been **integrated into critical DSS code files**. This guide shows:
+1. ✅ Files already updated
+2. 📋 Files that should be updated next
+3. 🔧 How to apply the framework to code
+4. 📝 Examples and templates
+
+---
+
+## Part 1: Files Already Updated ✅
+
+### **1. JavaScript Error Handler** ✅ COMPLETE
+**File:** `/admin-ui/js/core/error-handler.js`
+
+**What was changed:**
+- Module header updated with organism context
+- All error messages reframed using biological metaphors
+- Error titles now include emoji indicators (🛡️, ❤️, 🧠, ⚡, 🔌, etc.)
+- Error categories mapped to organ systems:
+  - Figma API → Sensory System issues
+  - Network → Heart/Nervous System issues  
+  - Timeout → Metabolism overload
+  - Validation → Immune/Genetic system issues
+
+**Example transformation:**
+
+**Before:**
+```javascript
+figma_403: {
+  title: 'Cannot access Figma file',
+  message: 'Your Figma access token doesn\'t have permission to access this file.',
+  actions: [
+    'Check if your Figma token is valid in Settings',
+    // ...
+  ],
+}
+```
+
+**After:**
+```javascript
+figma_403: {
+  title: '🛡️ IMMUNE ALERT: Sensory Input Blocked',
+  message: 'The DSS sensory organs cannot perceive the Figma file. Your access credentials lack permission.',
+  actions: [
+    'Verify your Figma authentication token in Settings (nervous system communication)',
+    'Confirm you have access to this file in Figma (sensory perception)',
+    // ...
+  ],
+}
+```
+
+**Benefits:**
+✅ Users understand errors as "immune system detecting threats"
+✅ Emojis make error types visually distinct
+✅ Action items include biological context in parentheses
+✅ Creates cohesive communication style
+
+---
+
+### **2. Python Validators** ✅ COMPLETE  
+**File:** `/dss-mvp1/dss/validators/schema.py`
+
+**What was changed:**
+- Module docstring refactored with organism context
+- Validation stages renamed with biological metaphors:
+  - Stage 1: 🛡️ Genetic Structure Check
+  - Stage 2: 🧬 DNA Completeness Check
+  - Stage 3: 🩸 Nutrient Quality Check
+  - Stage 4: 🧬 Tissue Integrity Check
+- Method docstrings explain validation as immune system antibodies
+- Error messages use biological language
+
+**Example transformation:**
+
+**Before:**
+```python
+def _validate_structure(self, data, result):
+    """Stage 2: Validate required fields and structure"""
+    for field in required_fields:
+        if field not in data:
+            result.add_error(
+                ValidationStage.STRUCTURE,
+                f"Missing required field: {field}",
+                field
+            )
+```
+
+**After:**
+```python
+def _validate_structure(self, data, result):
+    """
+    Stage 2: 🧬 DNA COMPLETENESS CHECK
+    
+    The immune system checks if the genetic blueprint has all
+    essential chromosomes. Missing genes prevent organism development.
+    """
+    for field in required_fields:
+        if field not in data:
+            result.add_error(
+                ValidationStage.STRUCTURE,
+                f"🧬 Missing essential gene: {field} (required chromosome incomplete)",
+                field
+            )
+```
+
+**Benefits:**
+✅ Developers understand validation as "immune system protecting health"
+✅ Code comments align with organism framework
+✅ Error messages are more memorable
+✅ Creates teaching opportunity for new developers
+
+---
+
+## Part 2: Files Ready for Next Update 📋
+
+### **HIGH PRIORITY - User-Facing Communication**
+
+#### **File: `/admin-ui/js/core/logger.js`**
+**Status:** Ready for update
+**What to change:** Log level categories and formatting
+**Suggested changes:**
+
+```javascript
+// BEFORE
+const logLevels = {
+  DEBUG: { level: 0, color: '#888', prefix: '[DEBUG]' },
+  INFO: { level: 1, color: '#2196F3', prefix: '[INFO]' },
+  WARN: { level: 2, color: '#FF9800', prefix: '[WARN]' },
+  ERROR: { level: 3, color: '#F44336', prefix: '[ERROR]' },
+};
+
+// AFTER
+const logLevels = {
+  DEBUG: { level: 0, color: '#888', prefix: '🧠 [THOUGHT]' }, // Brain thinking
+  INFO: { level: 1, color: '#2196F3', prefix: '💭 [AWARENESS]' }, // Organism aware
+  WARN: { level: 2, color: '#FF9800', prefix: '⚠️ [SYMPTOM]' }, // Health concern
+  ERROR: { level: 3, color: '#F44336', prefix: '🛡️ [IMMUNE ALERT]' }, // Threat detected
+};
+```
+
+---
+
+#### **File: `/dss-mvp1/dss/settings.py`**
+**Status:** Ready for update
+**What to change:** CLI command messages and output formatting
+**Suggested changes:**
+
+```python
+# BEFORE
+print("Running reset...")
+print("✅ Reset complete")
+
+# AFTER - Frame as organism actions
+print("🧬 Organism undergoing regeneration...")
+print("✅ Regeneration complete - organism reborn")
+
+# Health check output
+print("📊 DSS System Information:")
+print("❤️ Heart rate (DB latency): 145ms")
+print("🧠 Brain status (Validators): All passing")
+print("🩸 Circulation (Token distribution): 84/100 components")
+```
+
+---
+
+#### **File: `/tools/figma/figma_tools.py`**
+**Status:** Ready for update
+**What to change:** Figma integration messages and error handling
+**Suggested messages:**
+
+```python
+# When connecting to Figma
+print("🔌 Nervous system attempting sensory connection to Figma...")
+
+# When extracting tokens
+print("🍽️ Digestive system extracting nutrient particles from design file...")
+
+# When validation passes
+print("🛡️ Immune system approved: Nutrients are safe for circulation")
+
+# Errors
+raise Exception("🔌 NERVOUS SYSTEM ERROR: Cannot establish sensory link to Figma")
+```
+
+---
+
+#### **File: `/dss-mvp1/dss/ingest/base.py`**
+**Status:** Ready for update
+**What to change:** Token ingestion descriptions and progress messages
+**Suggested changes:**
+
+```python
+# BEFORE
+def ingest_tokens(self, tokens):
+    """Ingest and normalize tokens"""
+    
+# AFTER - Use organism metaphors
+def ingest_tokens(self, tokens):
+    """
+    Feed the organism - ingest tokens as nutrients
+    
+    The digestive system breaks down design input and extracts nutrients
+    (design tokens) that the organism can use for circulation.
+    """
+```
+
+---
+
+### **MEDIUM PRIORITY - System Documentation**
+
+#### **File: `/dss-mvp1/dss/tools/style_dictionary.py`**
+**Status:** Ready for update
+**Content type:** Transformation tool documentation
+**Why important:** This is the metabolic system that converts tokens
+
+Suggested framing:
+- Tool description: "The metabolic engine - converts nutrients to usable forms"
+- Process description: "Metabolism of tokens to CSS, JSON, SCSS outputs"
+- Output files: "Byproducts of healthy metabolism"
+
+---
+
+#### **File: `/dss-mvp1/dss/storybook/generator.py`**
+**Status:** Ready for update
+**Content type:** Documentation generation
+**Why important:** Storybook is the "skin" of the organism
+
+Suggested framing:
+- Generator purpose: "Refresh the skin - generate Storybook documentation"
+- Story creation: "Organism educating the external world through documentation"
+- Component showcase: "Display how tissues (components) work together"
+
+---
+
+### **LOW PRIORITY - Core Documentation**
+
+#### **Files that should reference the framework:**
+1. `/dss-mvp1/README.md` - Introduce organism metaphor in MVP1 overview
+2. `/docs/ARCHITECTURE.md` - Map architecture to organism systems  
+3. `/docs/QUICKSTART.md` - Use biological language for getting started
+4. `/ERROR_HANDLING.md` - Frame error handling as immune system
+
+---
+
+## Part 3: How to Apply the Framework
+
+### **Pattern 1: Docstrings & Comments**
+
+When documenting code, use this pattern:
+
+```python
+def some_function(self, data):
+    """
+    [Emoji] ORGANISM CONTEXT - Actual function name
+    
+    Biological explanation of what this does in the context of the DSS
+    organism. Mention which organ system or process is involved.
+    
+    Args:
+        data: Describe what data represents biologically
+        
+    Returns:
+        Describe what is returned in biological terms
+    """
+```
+
+---
+
+### **Pattern 2: Error Messages**
+
+When creating error messages, follow this structure:
+
+```
+[Emoji] SYSTEM ALERT: [Brief biological description]
+
+[Technical problem in biological language]
+
+What to do:
+1. [Action 1 with biological context in parentheses]
+2. [Action 2 with biological context in parentheses]
+```
+
+**Example:**
+
+```python
+raise ValidationError(
+    "🛡️ IMMUNE ALERT: Pathogenic Token Detected\n"
+    "Token value contains invalid characters that could infect the organism.\n"
+    "What to do:\n"
+    "1. Remove invalid characters from the token value (clean the nutrient)\n"
+    "2. Verify the token matches our genetic patterns (naming conventions)\n"
+    "3. Try ingesting the token again (feed the DSS)"
+)
+```
+
+---
+
+### **Pattern 3: Logging & Progress Messages**
+
+For progress tracking and logging, map to organism processes:
+
+```python
+logger.info("🍽️ Digestive system beginning token extraction...")
+logger.debug("🧠 Brain analyzing token patterns...")
+logger.warning("⚠️ Organism experiencing metabolic stress - slow processing")
+logger.error("❌ Critical immune failure - infection detected and isolated")
+```
+
+---
+
+### **Pattern 4: Configuration & Help Text**
+
+For CLI commands and settings descriptions:
+
+```python
+@click.command()
+@click.option('--feed', is_flag=True, help='Feed the DSS with new tokens from Figma')
+@click.option('--health', is_flag=True, help='Check the organism vital signs')
+def dss_cli(feed, health):
+    """DSS Organism Control Panel - Feed, monitor, and maintain the system"""
+    if feed:
+        print("🍽️ Opening intake valve...")
+    if health:
+        print("🏥 Running vital signs diagnostic...")
+```
+
+---
+
+## Part 4: Integration Checklist
+
+### **Phase 2A: Error Messages & Validation** ✅ IN PROGRESS
+- [x] JavaScript error-handler.js - Error messages
+- [x] Python schema.py - Validator docstrings
+- [ ] logger.js - Log level categories
+- [ ] settings.py - CLI messages
+- [ ] All other error sources
+
+### **Phase 2B: Core System Messages** 📋 READY
+- [ ] Figma integration messages
+- [ ] Token ingestion messages
+- [ ] Storybook generation messages
+- [ ] Database operation messages
+- [ ] Analysis & report generation
+
+### **Phase 2C: Documentation** 📋 READY
+- [ ] Code inline comments (docstrings)
+- [ ] README files with organism introduction
+- [ ] Architecture documentation
+- [ ] Setup guides rewritten biologically
+
+### **Phase 3: Team Implementation** 🎯 FUTURE
+- [ ] Train developers on the framework
+- [ ] Establish code review standards for organism language
+- [ ] Create coding guidelines document
+- [ ] Set up templates for new code
+
+---
+
+## Part 5: Code Review Guidelines
+
+When reviewing DSS code, check for organism framework compliance:
+
+### **✅ Good Patterns**
+```python
+# Docstring uses biological metaphor
+"""
+🛡️ IMMUNE SYSTEM - Validate incoming tokens
+Check if tokens are safe for circulation through the organism.
+"""
+
+# Error message includes emoji and biological context
+raise ValidationError("🛡️ Pathogen detected: Invalid token format")
+
+# Comments explain organism role
+# The heart (database) stores this nutrient for circulation
+db.store_token(token)
+```
+
+### **❌ Patterns to Update**
+```python
+# Generic docstring without organism context
+"""Validate tokens"""
+
+# Technical error message
+raise ValidationError("Invalid token: expected string, got dict")
+
+# Comments without biological meaning
+# This stores the token
+db.store_token(token)
+```
+
+---
+
+## Part 6: File Organization
+
+As you update files, organize documentation like this:
+
+```
+dss-mvp1/
+├── README.md
+│   └── Add: "The DSS Organism" section with framework link
+├── dss/
+│   ├── validators/
+│   │   └── schema.py ✅ UPDATED
+│   ├── ingest/
+│   │   └── base.py 📋 READY
+│   ├── tools/
+│   │   └── figma.py 📋 READY
+│   └── storybook/
+│       └── generator.py 📋 READY
+├── docs/
+│   ├── ARCHITECTURE.md 📋 READY
+│   ├── DSS_ORGANISM_GUIDE.md ✅ NEW
+│   └── CODE_INTEGRATION_GUIDE.md ✅ THIS FILE
+└── ...
+```
+
+---
+
+## Part 7: Examples by File Type
+
+### **Python Dataclass/Pydantic Model**
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Token:
+    """🩸 NUTRIENT - A design token flowing through the circulatory system"""
+    name: str  # Genetic identifier
+    value: str  # Nutrient value (color, spacing, etc.)
+    category: str  # Blood type (color, spacing, shadow, etc.)
+```
+
+---
+
+### **JavaScript Promise/Async Function**
+```javascript
+/**
+ * 🧬 ORGANISM PERCEPTION - Check if the sensory organs can connect to Figma
+ * 
+ * @async
+ * @returns {Promise<boolean>} True if sensory connection established
+ */
+async function checkSensoryConnection() {
+  try {
+    const response = await fetch('https://api.figma.com/health');
+    return response.ok; // Sensory organs are alive
+  } catch (error) {
+    console.log('🛡️ IMMUNE ALERT: Sensory disconnection detected');
+    return false;
+  }
+}
+```
+
+---
+
+### **REST API Endpoint**
+```python
+@app.get("/health")
+async def health_check():
+    """
+    ❤️ HEART VITALS - Check if the organism is alive
+    
+    Returns the DSS organism's vital signs.
+    """
+    return {
+        "status": "healthy",
+        "heart_rate": get_db_latency(),  # Database query speed
+        "brain_activity": get_validator_status(),  # Analysis running
+        "circulation": get_token_distribution(),  # Token usage
+    }
+```
+
+---
+
+## Part 8: Common Questions
+
+**Q: Do I HAVE to use organism language?**
+A: Not strictly required, but recommended for user-facing messages (errors, logs, docs). Internal implementation details can stay technical.
+
+**Q: What if the metaphor doesn't fit?**
+A: Use both biological and technical language. The framework is a communication tool, not a cage.
+
+**Q: How do I remember the 11 organs?**
+A: Reference `QUICK_START_ORGANISM.md`. The organ system table shows all 11 with their functions.
+
+**Q: Can I create new biological metaphors?**
+A: Yes! But keep them consistent and document them in the glossary if they're new.
+
+---
+
+## Part 9: Next Steps
+
+1. **Complete Phase 2A** - Finish error/validation updates (in progress)
+2. **Move to Phase 2B** - Update system messages in ingest, Figma, storybook
+3. **Phase 2C** - Update documentation and READMEs
+4. **Train team** - Share the framework, establish guidelines
+5. **Continuous improvement** - Apply to new code as it's written
+
+---
+
+## References
+
+📖 **Full Framework:** See `/docs/DSS_ORGANISM_GUIDE.md`  
+📚 **Glossary:** See `/docs/DSS_BIOLOGY_GLOSSARY.md`  
+⚡ **Quick Start:** See `/docs/QUICK_START_ORGANISM.md`  
+🗂️ **Index:** See `/docs/INDEX_ORGANISM_FRAMEWORK.md`  
+
+---
+
+**Happy integrating! The DSS organism is ready to speak biologically.** 🧬✨