Renamed and move to docs folder
This commit is contained in:
parent
fa1a5f215a
commit
2f4c6ff326
|
|
@ -0,0 +1,283 @@
|
|||
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
|
||||
javascript
|
||||
// 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
|
||||
text
|
||||
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:
|
||||
|
||||
javascript
|
||||
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:
|
||||
|
||||
yaml
|
||||
^%$bridge
|
||||
action: update_file
|
||||
repo: ai-workflow-test
|
||||
path: README.md
|
||||
content: |
|
||||
Multi-line content
|
||||
with proper formatting
|
||||
---
|
||||
Parsing Logic:
|
||||
|
||||
javascript
|
||||
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:
|
||||
|
||||
javascript
|
||||
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:
|
||||
|
||||
javascript
|
||||
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:
|
||||
|
||||
javascript
|
||||
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
|
||||
text
|
||||
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
|
||||
text
|
||||
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
|
||||
javascript
|
||||
// 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
|
||||
javascript
|
||||
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
|
||||
javascript
|
||||
// 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.
|
||||
Loading…
Reference in New Issue