Update Docs/Technical Design Document
This commit is contained in:
parent
f182751ca7
commit
4fa5949ecf
|
|
@ -1,10 +1,14 @@
|
|||
AI Repo Commander - Technical Design Document
|
||||
1. Overview
|
||||
# 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
|
||||
## 2. Core Architecture
|
||||
|
||||
### 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
|
||||
|
||||
5.2 Emergency Stop Options
|
||||
javascript
|
||||
```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.
|
||||
Loading…
Reference in New Issue