Update Docs/Technical Design Document

Docs/Technical Design Document

@@ -1,10 +1,14 @@
-AI Repo Commander - Technical Design Document
+# AI Repo Commander - Technical Design Document
-1. Overview
+
+## 1. Overview
+
 A browser userscript that enables AI assistants to securely interact with git repositories via YAML-style commands, with comprehensive safety measures and real-time feedback.
 
-2. Core Architecture
+## 2. Core Architecture
-2.1 Safety-First Design
+
-javascript
+### 2.1 Safety-First Design
+
+```javascript
 // Configuration - MUST be manually enabled for production
 const CONFIG = {
     ENABLE_API: false,           // Master kill switch
@@ -13,21 +17,28 @@ const CONFIG = {
     MAX_RETRIES: 2,             // API retry attempts
     VERSION: '1.0.0'
 };
-2.2 Module Structure
+```
-text
+
+### 2.2 Module Structure
+
+```
 AI Repo Commander
 ├── Core Monitor
 ├── Command Parser
 ├── Validation Engine
 ├── Execution Manager
 └── UI Feedback System
-3. Detailed Component Specifications
+```
-3.1 Core Monitor
-Purpose: Detect and track command messages safely
 
-Implementation:
+## 3. Detailed Component Specifications
 
-javascript
+### 3.1 Core Monitor
+
+**Purpose:** Detect and track command messages safely
+
+**Implementation:**
+
+```javascript
 class CommandMonitor {
     private trackedMessages: Map<string, CommandState>;
     
@@ -46,12 +57,15 @@ class CommandMonitor {
     trackMessage(element, text): void // Begin processing pipeline
     updateState(messageId, state): void // State machine transitions
 }
-3.2 Command Parser
+```
-Purpose: Extract structured data from YAML commands
 
-Input Format:
+### 3.2 Command Parser
 
-yaml
+**Purpose:** Extract structured data from YAML commands
+
+**Input Format:**
+
+```yaml
 ^%$bridge
 action: update_file
 repo: ai-workflow-test
@@ -60,9 +74,11 @@ content: |
   Multi-line content
   with proper formatting
 ---
-Parsing Logic:
+```
 
-javascript
+**Parsing Logic:**
+
+```javascript
 class CommandParser {
     parseYAMLCommand(text): ParsedCommand {
         // 1. Extract command block (^%$bridge to ---)
@@ -78,12 +94,15 @@ class CommandParser {
         // Return { isValid: boolean, errors: string[] }
     }
 }
-3.3 Validation Engine
+```
-Purpose: Ensure command completeness and safety
 
-Required Fields Matrix:
+### 3.3 Validation Engine
 
-javascript
+**Purpose:** Ensure command completeness and safety
+
+**Required Fields Matrix:**
+
+```javascript
 const REQUIRED_FIELDS = {
     'update_file': ['action', 'repo', 'path', 'content'],
     'get_file': ['action', 'repo', 'path'],
@@ -98,12 +117,15 @@ const FIELD_VALIDATORS = {
     'path': (value) => !value.includes('..') && !value.startsWith('/'),
     'action': (value) => Object.keys(REQUIRED_FIELDS).includes(value)
 };
-3.4 Execution Manager
+```
-Purpose: Handle API calls with comprehensive safety
 
-Execution Flow:
+### 3.4 Execution Manager
 
-javascript
+**Purpose:** Handle API calls with comprehensive safety
+
+**Execution Flow:**
+
+```javascript
 class ExecutionManager {
     async executeCommand(command, sourceElement): Promise<ExecutionResult> {
         // 1. Pre-execution safety checks
@@ -138,12 +160,15 @@ class ExecutionManager {
         });
     }
 }
-3.5 UI Feedback System
+```
-Purpose: Provide clear, consistent user feedback
 
-Status Message Templates:
+### 3.5 UI Feedback System
 
-javascript
+**Purpose:** Provide clear, consistent user feedback
+
+**Status Message Templates:**
+
+```javascript
 const STATUS_TEMPLATES = {
     SUCCESS: '[{action}: Success] {details}',
     ERROR: '[{action}: Error] {details}',
@@ -169,9 +194,13 @@ class UIFeedback {
         }[type];
     }
 }
-4. Processing Pipeline
+```
-4.1 Step-by-Step Flow
+
-text
+## 4. Processing Pipeline
+
+### 4.1 Step-by-Step Flow
+
+```
 1. MONITOR: Detect ^%$bridge in new messages
 2. TRACK: Assign unique ID and initial state
 3. PARSE: Extract YAML into structured command
@@ -180,28 +209,31 @@ text
 6. EXECUTE: Make API call (or mock if disabled)
 7. FEEDBACK: Replace with status message
 8. CLEANUP: Update state to complete
-4.2 Error Handling Flow
+```
-text
+
+### 4.2 Error Handling Flow
+
+```
 Parse Error → [Action: Invalid] Invalid YAML format
 Validation Error → [Action: Invalid] Missing field: content
 API Error → [Action: Error] Network timeout
 Network Error → [Action: Error] Cannot reach bridge
-5. Safety Mechanisms
+```
-5.1 Multiple Protection Layers
-API Master Switch: ENABLE_API must be explicitly true
 
-Command Validation: Required fields and format checking
+## 5. Safety Mechanisms
 
-Bot Debouncing: 5-second wait prevents partial command execution
+### 5.1 Multiple Protection Layers
 
-Network Timeouts: 30-second API call limits
+- **API Master Switch:** ENABLE_API must be explicitly true
+- **Command Validation:** Required fields and format checking
+- **Bot Debouncing:** 5-second wait prevents partial command execution
+- **Network Timeouts:** 30-second API call limits
+- **Error Boundaries:** Isolated error handling per command
+- **State Tracking:** Prevents duplicate processing
 
-Error Boundaries: Isolated error handling per command
+### 5.2 Emergency Stop Options
 
-State Tracking: Prevents duplicate processing
+```javascript
-
-5.2 Emergency Stop Options
-javascript
 // Manual stop mechanisms
 const emergencyStop = () => {
     CONFIG.ENABLE_API = false;
@@ -211,9 +243,13 @@ const emergencyStop = () => {
 
 // Browser console commands
 window.AI_REPO_STOP = emergencyStop;
-6. Cross-Platform Compatibility
+```
-6.1 DOM Selectors by Platform
+
-javascript
+## 6. Cross-Platform Compatibility
+
+### 6.1 DOM Selectors by Platform
+
+```javascript
 const PLATFORM_SELECTORS = {
     'chat.openai.com': {
         messages: '[class*="message"]',
@@ -228,9 +264,13 @@ const PLATFORM_SELECTORS = {
         input: 'textarea, [contenteditable="true"]'
     }
 };
-7. Testing Strategy
+```
-7.1 Development Testing Commands
+
-javascript
+## 7. Testing Strategy
+
+### 7.1 Development Testing Commands
+
+```javascript
 // Test command generator for safe testing
 const TEST_COMMANDS = {
     validUpdate: `^%$bridge
@@ -253,31 +293,28 @@ repo: test-repo
 path: README.md
 ---`
 };
-8. Deployment Checklist
+```
-8.1 Pre-Launch Verification
-ENABLE_API = false in production code
 
-All error cases handled gracefully
+## 8. Deployment Checklist
 
-Status messages clear and informative
+### 8.1 Pre-Launch Verification
 
-Bot typing protection working
+- ENABLE_API = false in production code
+- All error cases handled gracefully
+- Status messages clear and informative
+- Bot typing protection working
+- Cross-browser compatibility verified
+- Memory leaks checked (interval cleanup)
+- Performance impact acceptable
 
-Cross-browser compatibility verified
+### 8.2 Production Enablement Steps
 
-Memory leaks checked (interval cleanup)
+1. Test thoroughly with ENABLE_API = false
+2. Verify mock executions work correctly
+3. Enable API for single test command
+4. Monitor real API interactions
+5. Enable for full usage
 
-Performance impact acceptable
+---
-
-8.2 Production Enablement Steps
-Test thoroughly with ENABLE_API = false
-
-Verify mock executions work correctly
-
-Enable API for single test command
-
-Monitor real API interactions
-
-Enable for full usage
 
 This design provides a comprehensive, safe, and extensible foundation for your AI Repo Commander.