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

1.1 Diagrams (PlantUML)

Architecture Overview: Docs/diagrams/architecture-overview.puml
Command Execution Sequence: Docs/diagrams/sequence-command-execution.puml
Command Processing State Machine: Docs/diagrams/state-machine.puml

How to view: open the .puml files with any PlantUML viewer (IDE plugin or web renderer) to generate images.

2. Core Architecture

2.1 Safety-First Design

// Configuration (persisted via localStorage)
const DEFAULT_CONFIG = {
  ENABLE_API: true,
  DEBUG_MODE: true,
  DEBUG_LEVEL: 2,
  DEBUG_WATCH_MS: 120000,
  DEBUG_MAX_LINES: 400,
  DEBUG_SHOW_PANEL: true,

  // Timing & API
  DEBOUNCE_DELAY: 6500,            // streaming debounce before settle
  MAX_RETRIES: 2,
  VERSION: '1.6.2',
  API_TIMEOUT_MS: 60000,

  PROCESS_EXISTING: false,         // resume-safe guard
  ASSISTANT_ONLY: true,
  BRIDGE_KEY: '',

  // Persistent dedupe window
  DEDUPE_TTL_MS: 30 * 24 * 60 * 60 * 1000, // 30 days

  COLD_START_MS: 2000,             // avoid immediate re-exec on reload
  SHOW_EXECUTED_MARKER: true,

  // Housekeeping
  CLEANUP_AFTER_MS: 30000,
  CLEANUP_INTERVAL_MS: 60000,

  // Paste + submit behavior
  APPEND_TRAILING_NEWLINE: true,
  AUTO_SUBMIT: true,
  POST_PASTE_DELAY_MS: 250,
  SUBMIT_MODE: 'button_first',

  // Streaming complete hardening
  REQUIRE_TERMINATOR: true,        // requires @end@
  SETTLE_CHECK_MS: 1300,           // stable window after last change
  SETTLE_POLL_MS: 250,             // settle poll frequency

  // Runtime toggles
  RUNTIME: { PAUSED: false },

  // Hardening & perf
  STUCK_AFTER_MS: 10 * 60 * 1000,
  SCAN_DEBOUNCE_MS: 400,
  FAST_WARN_MS: 50,
  SLOW_WARN_MS: 60_000,

  // Queue management
  QUEUE_MIN_DELAY_MS: 800,
  QUEUE_MAX_PER_MINUTE: 15,
  QUEUE_MAX_PER_MESSAGE: 5,
  QUEUE_WAIT_FOR_COMPOSER_MS: 6000,

  RESPONSE_BUFFER_FLUSH_DELAY_MS: 500,
  RESPONSE_BUFFER_SECTION_HEADINGS: true,

  MAX_PASTE_CHARS: 250_000,
  SPLIT_LONG_RESPONSES: true,
};

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

Parsing Logic:

class CommandParser {
    parseYAMLCommand(text): ParsedCommand {
        // 1. Extract command block (@bridge@ ... @end@ terminator required)
        // 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];
    }
}

3.6 Execution Queue

Purpose: Serialize command execution with rate limits and minimal spacing between actions.

Highlights:

Min delay between tasks: CONFIG.QUEUE_MIN_DELAY_MS
Rate cap: CONFIG.QUEUE_MAX_PER_MINUTE
Fire-and-forget push; internal drain loop ensures sequential execution

class ExecutionQueue {
  push(task) { /* queue and begin drain */ }
  async _drain() { /* rate-limit and run */ }
}

3.7 Response Buffer (paste pipeline)

Purpose: Collect response chunks (e.g., get_file content or list_files listing) and paste them into the composer once nearby tasks finish, respecting size limits.

Highlights:

Delayed flush (CONFIG.RESPONSE_BUFFER_FLUSH_DELAY_MS) to batch sibling results
Splitting long responses (CONFIG.SPLIT_LONG_RESPONSES, CONFIG.MAX_PASTE_CHARS)
Uses pasteAndMaybeSubmit(text) which pastes and optionally auto-submits

3.8 Conversation-Aware History (dedupe)

Purpose: Avoid re-executing the same command in the same conversation across reloads.

Highlights:

Fingerprint of message element (plus optional sub-index) stored in localStorage with TTL (CONFIG.DEDUPE_TTL_MS)
Per-message, per-command "Run again" UI allows manual re-exec
SHOW_EXECUTED_MARKER outlines executed messages in green

3.9 Paste + Submit Mechanics

Purpose: Robustly paste text into the site-specific composer and submit.

Paste flow (tries in order):

Dispatch ClipboardEvent('paste', clipboardData)
ProseMirror innerHTML paragraphs with input/change events
Selection/Range insertion for contentEditable; setRangeText for inputs/textareas
Direct value/textContent assignment as a fallback
GM_setClipboard as last resort (manual paste)

Submit flow:

Find send button scoped to nearest form/composer/main first
If no button or enter-only mode, simulate Enter key events on the input

3.10 Notifications

Purpose: Present OS-level notifications via userscript APIs when available.

Implementation: Direct calls to GM_notification for OS-level notifications.
Userscript header includes: @grant GM_notification to enable the API in Tampermonkey/Violentmonkey.
IDE hint: A top-of-file comment /* global GM_notification */ is present to silence unresolved symbol warnings in WebStorm.
Portability note: No wrapper is used. If the script is executed outside a userscript manager, GM_notification will not exist and notifications are skipped; the in-page debug panel/toasts provide fallback visibility.

4. Processing Pipeline

4.1 Step-by-Step Flow

1. MONITOR: Detect @bridge@ command blocks in assistant messages; extract all complete blocks per message.
2. TRACK: Assign readable message ID; mark per-command history to avoid re-exec; show queue badge.
3. PARSE: Extract inner YAML-like key/values from @bridge@ ... @end@; apply defaults; expand owner/repo shorthand.
4. VALIDATE: Check required fields based on action; treat examples specially (skip execution).
5. DEBOUNCE: Wait DEBOUNCE_DELAY, then run SETTLE window to ensure the final, stable command text.
6. EXECUTE (queue): Serialize via ExecutionQueue with rate limits; GM_xmlhttpRequest to bridge with retries.
7. FEEDBACK: Render per-command status lines; paste response bodies via ResponseBuffer into the composer.
8. SUBMIT: Optionally auto-submit after paste using scoped send button or Enter key events.
9. COMPLETE: Update state and timestamps; maintain history TTL; attach per-command "Run again" buttons for manual control.

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 gate and runtime PAUSED toggle
Command Validation: required fields per action, example detection
Streaming Hardened: DEBOUNCE_DELAY + SETTLE_CHECK_MS window ensures complete blocks
Rate Limiting: ExecutionQueue caps per-minute and enforces inter-task delay
Persistent Dedupe: conversation-aware history with TTL to prevent re-exec across reloads
UI Safeguards: per-command "Run again" instead of auto-reexec; executed marker on messages
Network Limits: API_TIMEOUT_MS and bounded retries
Error Isolation: per-command try/catch with inline validation handling (no throw/catch ping-pong)

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: '[data-message-author-role]', input: '#prompt-textarea, textarea, [contenteditable="true"]', content: '.markdown' },
  'chatgpt.com':       { messages: '[data-message-author-role]', input: '#prompt-textarea, textarea, [contenteditable="true"]', content: '.markdown' },
  'claude.ai':         { messages: '.chat-message',              input: '[contenteditable="true"]',                            content: '.content' },
  'gemini.google.com': { messages: '.message-content',           input: 'textarea, [contenteditable="true"]',                  content: '.message-text' }
};

7. Testing Strategy

7.1 Development Testing Commands

// Test command generator for safe testing
const TEST_COMMANDS = {
  validUpdate: '@bridge@\naction: update_file\nrepo: test-repo\npath: TEST.md\ncontent: |\n  Test content\n  Multiple lines\n@end@',
  invalidCommand: '@bridge@\naction: update_file\nrepo: test-repo\n@end@',
  getFile: '@bridge@\naction: get_file\nrepo: test-repo\npath: README.md\n@end@'
};

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.

13 KiB Raw Blame History

AI Repo Commander - Technical Design Document

1. Overview

1.1 Diagrams (PlantUML)

2. Core Architecture

2.1 Safety-First Design

2.2 Module Structure

3. Detailed Component Specifications

3.1 Core Monitor

3.2 Command Parser

3.3 Validation Engine

3.4 Execution Manager

3.5 UI Feedback System

3.6 Execution Queue

3.7 Response Buffer (paste pipeline)

3.8 Conversation-Aware History (dedupe)

3.9 Paste + Submit Mechanics

3.10 Notifications

4. Processing Pipeline

4.1 Step-by-Step Flow

4.2 Error Handling Flow

5. Safety Mechanisms

5.1 Multiple Protection Layers

5.2 Emergency Stop Options

6. Cross-Platform Compatibility

6.1 DOM Selectors by Platform

7. Testing Strategy

7.1 Development Testing Commands

8. Deployment Checklist

8.1 Pre-Launch Verification

8.2 Production Enablement Steps

13 KiB

Raw Blame History