From b446771480d6da97e738e318670962f876c29b4f Mon Sep 17 00:00:00 2001 From: rob Date: Tue, 14 Oct 2025 15:14:28 -0300 Subject: [PATCH] fixed all warnings and the docs --- Docs/Technical_Design_Document.md | 208 +++++++++++++----- Docs/diagrams/architecture-overview.puml | 45 ++++ Docs/diagrams/sequence-command-execution.puml | 37 ++++ Docs/diagrams/state-machine.puml | 42 ++++ 4 files changed, 273 insertions(+), 59 deletions(-) create mode 100644 Docs/diagrams/architecture-overview.puml create mode 100644 Docs/diagrams/sequence-command-execution.puml create mode 100644 Docs/diagrams/state-machine.puml diff --git a/Docs/Technical_Design_Document.md b/Docs/Technical_Design_Document.md index a41fcf9..8916188 100644 --- a/Docs/Technical_Design_Document.md +++ b/Docs/Technical_Design_Document.md @@ -17,13 +17,66 @@ How to view: open the .puml files with any PlantUML viewer (IDE plugin or web re ### 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' +// 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, }; ``` @@ -52,7 +105,7 @@ class CommandMonitor { // Message states static STATES = { - DETECTED: 'detected', // ^%$bridge found + DETECTED: 'detected', // @bridge@ found PARSING: 'parsing', // YAML parsing in progress VALIDATING: 'validating', // Field validation DEBOUNCING: 'debouncing', // 5-second wait period @@ -61,9 +114,9 @@ class CommandMonitor { ERROR: 'error' // Command failed }; - scanMessages(): void // Find new command messages - trackMessage(element, text): void // Begin processing pipeline - updateState(messageId, state): void // State machine transitions + scanMessages(): void; // Find new command messages + trackMessage(element, text): void; // Begin processing pipeline + updateState(messageId, state): void; // State machine transitions } ``` @@ -74,14 +127,14 @@ class CommandMonitor { **Input Format:** ```yaml -^%$bridge +@bridge@ action: update_file repo: ai-workflow-test path: README.md content: | Multi-line content with proper formatting ---- +@end@ ``` **Parsing Logic:** @@ -89,7 +142,7 @@ content: | ```javascript class CommandParser { parseYAMLCommand(text): ParsedCommand { - // 1. Extract command block (^%$bridge to ---) + // 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) @@ -204,19 +257,78 @@ class UIFeedback { } ``` +### 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 + +```javascript +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 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 +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 @@ -232,12 +344,14 @@ Network Error → [Action: Error] Cannot reach bridge ### 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 +- 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 @@ -259,18 +373,10 @@ window.AI_REPO_STOP = emergencyStop; ```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"]' - } + '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' } }; ``` @@ -281,25 +387,9 @@ const PLATFORM_SELECTORS = { ```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 ----` + 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@' }; ``` diff --git a/Docs/diagrams/architecture-overview.puml b/Docs/diagrams/architecture-overview.puml new file mode 100644 index 0000000..c37888f --- /dev/null +++ b/Docs/diagrams/architecture-overview.puml @@ -0,0 +1,45 @@ +@startuml Architecture Overview +skinparam componentStyle rectangle +skinparam shadowing false +skinparam ArrowColor #555 +skinparam component { + BackgroundColor<> #E8F5E9 + BackgroundColor<> #E3F2FD + BackgroundColor<> #FFF3E0 +} + +package "Browser (Chat Sites)" <> { + [ChatGPT DOM] + [Claude DOM] + [Gemini DOM] +} + +node "Userscript: AI Repo Commander" as Userscript { + component "Core Monitor" <> as Monitor + component "Command Parser" <> as Parser + component "Validation Engine" <> as Validator + component "Execution Manager" <> as Executor + component "Dedupe Store" <> as Dedupe + component "Config Manager" <> as Config + component "UI Panel (Tools/Settings)" <> as Panel + component "Inline Status UI" <> as InlineUI +} + +cloud "Bridge API" <> as Bridge + +' Relationships +[ChatGPT DOM] -down-> Monitor : observe assistant messages +[Claude DOM] -down-> Monitor +[Gemini DOM] -down-> Monitor + +Monitor -> Parser : extract YAML blocks +Parser -> Validator : validate fields/actions +Validator -> Executor : approved commands +Executor -> Bridge : HTTP requests (key, action) +Executor --> InlineUI : progress + results +Monitor --> InlineUI : markers (processed, run again) +Panel <--> Config : view/edit config +Executor <--> Config : timeouts, retries +Monitor <--> Dedupe : per-convo records + +@enduml \ No newline at end of file diff --git a/Docs/diagrams/sequence-command-execution.puml b/Docs/diagrams/sequence-command-execution.puml new file mode 100644 index 0000000..91eab18 --- /dev/null +++ b/Docs/diagrams/sequence-command-execution.puml @@ -0,0 +1,37 @@ +@startuml Command Execution Sequence +skinparam shadowing false +skinparam ArrowColor #555 + +actor User as U +participant "Assistant Message\n(DOM)" as DOM +participant "Core Monitor" as Monitor +participant "Command Parser" as Parser +participant "Validation Engine" as Validator +participant "Dedupe Store" as Dedupe +participant "Execution Manager" as Executor +participant "Inline Status UI" as UI +participant "Bridge API" as Bridge + +U -> DOM : Produces message with YAML block +DOM -> Monitor : observe new/updated message +Monitor -> Monitor : debounce + streaming settle +Monitor -> Parser : extract YAML block +Parser --> Monitor : ParsedCommand +Monitor -> Validator : validate fields and action +Validator --> Monitor : ValidationResult +Monitor -> Dedupe : check de-duplication +Dedupe --> Monitor : isNew? +alt example: true or duplicate + Monitor -> UI : mark as processed (skipped) + return +else valid and new + Monitor -> UI : show "Ready" (runnable) + Monitor -> Executor : enqueue/execute command + Executor -> UI : state = executing + Executor -> Bridge : POST action with bridge key + Bridge --> Executor : response (success/failure) + Executor -> UI : show result + Run Again button + Executor -> Dedupe : record execution (ttl 30d) +end + +@enduml \ No newline at end of file diff --git a/Docs/diagrams/state-machine.puml b/Docs/diagrams/state-machine.puml new file mode 100644 index 0000000..37d633a --- /dev/null +++ b/Docs/diagrams/state-machine.puml @@ -0,0 +1,42 @@ + +@startuml Command Processing State Machine +skinparam shadowing false +skinparam ArrowColor #555 +skinparam state { + StartColor #A5D6A7 + BackgroundColor #FAFAFA +} + +[*] --> DETECTED : YAML block found + +state DETECTED { +} +DETECTED --> PARSING : debounce/settle passed +PARSING --> VALIDATING : YAML parsed +PARSING --> ERROR : parse failure + +VALIDATING --> DEDUPE_CHECK : required fields ok +VALIDATING --> ERROR : validation failed + +state DEDUPE_CHECK +DEDUPE_CHECK --> SKIPPED : duplicate or example:true +DEDUPE_CHECK --> READY : new and runnable + +state READY +READY --> EXECUTING : user intent or auto-exec policy +READY --> [*] : STOP triggered + +state EXECUTING +EXECUTING --> COMPLETE : success +EXECUTING --> ERROR : API/network failure + +state SKIPPED +SKIPPED --> [*] + +state COMPLETE +COMPLETE --> [*] + +state ERROR +ERROR --> [*] + +@enduml \ No newline at end of file