8.1 KiB

Raw Blame History

AI Repo Commander - Technical Design Document

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.1 Safety-First Design

// Configuration - MUST be manually enabled for production
const CONFIG = {
    ENABLE_API: false,           // Master kill switch
    DEBUG_MODE: true,           // Development logging
    DEBOUNCE_DELAY: 5000,       // 5-second bot typing protection
    MAX_RETRIES: 2,             // API retry attempts
    VERSION: '1.0.0'
};

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:

class CommandMonitor {
    private trackedMessages: Map<string, CommandState>;
    
    // Message states
    static STATES = {
        DETECTED: 'detected',      // ^%$bridge found
        PARSING: 'parsing',        // YAML parsing in progress
        VALIDATING: 'validating',  // Field validation
        DEBOUNCING: 'debouncing',  // 5-second wait period
        EXECUTING: 'executing',    // API call in progress
        COMPLETE: 'complete',      // Command finished
        ERROR: 'error'            // Command failed
    };
    
    scanMessages(): void           // Find new command messages
    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:

^%$bridge
action: update_file
repo: ai-workflow-test
path: README.md
content: |
  Multi-line content
  with proper formatting  
---

Parsing Logic:

class CommandParser {
    parseYAMLCommand(text): ParsedCommand {
        // 1. Extract command block (^%$bridge to ---)
        // 2. Parse key-value pairs
        // 3. Handle multi-line content with | syntax
        // 4. Set defaults (url, owner if missing)
        // 5. Return structured object
    }
    
    validateStructure(parsed): ValidationResult {
        // Check for required fields based on action type
        // Validate field formats
        // Return { isValid: boolean, errors: string[] }
    }
}

3.3 Validation Engine

Purpose: Ensure command completeness and safety

Required Fields Matrix:

const REQUIRED_FIELDS = {
    'update_file': ['action', 'repo', 'path', 'content'],
    'get_file': ['action', 'repo', 'path'],
    'create_repo': ['action', 'repo'],
    'create_file': ['action', 'repo', 'path', 'content'],
    'delete_file': ['action', 'repo', 'path'],
    'list_files': ['action', 'repo', 'path']
};

const FIELD_VALIDATORS = {
    'repo': (value) => /^[\w\-\.]+$/.test(value),
    '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:

class ExecutionManager {
    async executeCommand(command, sourceElement): Promise<ExecutionResult> {
        // 1. Pre-execution safety checks
        if (!CONFIG.ENABLE_API) {
            return this.mockExecution(command, sourceElement);
        }
        
        // 2. API call with retry logic
        try {
            const response = await this.makeAPICall(command);
            return this.handleSuccess(response, sourceElement);
        } catch (error) {
            return this.handleError(error, sourceElement);
        }
    }
    
    makeAPICall(command): Promise<APIResponse> {
        return new Promise((resolve, reject) => {
            GM_xmlhttpRequest({
                method: 'POST',
                url: command.url || 'https://n8n.brrd.tech/webhook/ai-gitea-bridge',
                headers: {
                    'X-Bridge-Key': 'mango-rocket-82',
                    'Content-Type': 'application/json'
                },
                data: JSON.stringify(command),
                timeout: 30000,
                onload: resolve,
                onerror: reject,
                ontimeout: reject
            });
        });
    }
}

3.5 UI Feedback System

Purpose: Provide clear, consistent user feedback

Status Message Templates:

const STATUS_TEMPLATES = {
    SUCCESS: '[{action}: Success] {details}',
    ERROR: '[{action}: Error] {details}',
    VALIDATION_ERROR: '[{action}: Invalid] {details}',
    EXECUTING: '[{action}: Processing...]',
    MOCK: '[{action}: Mock] {details}'
};

class UIFeedback {
    replaceWithStatus(sourceElement, template, data): void {
        // 1. Create status element matching original style
        // 2. Apply appropriate color coding
        // 3. Replace original message
        // 4. Add copy-friendly formatting
    }
    
    colorCodeStatus(type): string {
        return {
            'success': '#10B981',    // Green
            'error': '#EF4444',      // Red  
            'warning': '#F59E0B',    // Yellow
            'info': '#3B82F6'        // Blue
        }[type];
    }
}

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
4. VALIDATE: Check required fields and formats
5. DEBOUNCE: Wait 5 seconds for bot typing completion
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

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
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

5.2 Emergency Stop Options

// Manual stop mechanisms
const emergencyStop = () => {
    CONFIG.ENABLE_API = false;
    CommandMonitor.stopAllProcessing();
    clearAllIntervals();
};

// Browser console commands
window.AI_REPO_STOP = emergencyStop;

6. Cross-Platform Compatibility

6.1 DOM Selectors by Platform

const PLATFORM_SELECTORS = {
    'chat.openai.com': {
        messages: '[class*="message"]',
        input: '#prompt-textarea'
    },
    'claude.ai': {
        messages: '.chat-message',
        input: '[contenteditable="true"]'
    },
    'gemini.google.com': {
        messages: '.message-content',
        input: 'textarea, [contenteditable="true"]'
    }
};

7. Testing Strategy

7.1 Development Testing Commands

// Test command generator for safe testing
const TEST_COMMANDS = {
    validUpdate: `^%$bridge
action: update_file
repo: test-repo
path: TEST.md
content: |
  Test content
  Multiple lines
---`,

    invalidCommand: `^%$bridge
action: update_file
repo: test-repo
---`,

    getFile: `^%$bridge
action: get_file  
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
Status messages clear and informative
Bot typing protection working
Cross-browser compatibility verified
Memory leaks checked (interval cleanup)
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.

8.1 KiB Raw Blame History