Delete Docs
This commit is contained in:
parent
637e862a9f
commit
fa1a5f215a
283
Docs
283
Docs
|
|
@ -1,283 +0,0 @@
|
||||||
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