diff --git a/README.md b/README.md index 274ee54..8f495ec 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,183 @@ - AI Repo Commander +๐Ÿง  AI Repo Commander - A safety-first userscript that lets AI assistants securely interact with git repositories using YAML-style commands. It provides strong guardrails, persistent de-duplication, a draggable debug panel with tools and settings, and robust paste/autosubmit for get_file. +A safety-first userscript that lets AI assistants securely interact with your Git repositories using YAML-style commands. +It enforces strict validation, persistent de-duplication, and a command-queue pipeline that prevents overloads while staying streaming-safe and cross-assistant compatible. - Highlights: - - Code-block only execution (only fenced YAML with the bridge header runs) - - Safety-first: STOP switch, strict validation, debounce plus settle - - Persistent de-duplication per conversation (30-day TTL) - - Streaming-safe: waits for final text before executing - - Clear feedback: inline status and desktop notifications - - Cross-platform: ChatGPT, Claude, Gemini - - Tools & Settings panel: bridge key editor, config JSON, clear history - - Robust paste and auto-submit with fallbacks for get_file +๐Ÿš€ Highlights - Quick Start: - 1) Install Tampermonkey or Violentmonkey. - 2) Create a new userscript and paste src/ai-repo-commander.user.js. - 3) Ask the assistant to produce a YAML block beginning with the bridge header and ending with the terminator. - 4) Enter your bridge key when prompted (you can store it in the panel). - 5) Adjust settings in Tools and Settings as needed. +๐Ÿงฉ Code-block-only execution โ€“ only fenced YAML blocks beginning with @bridge@ and ending with @end@ run. - Default Configuration (excerpt): - ENABLE_API: true - DEBUG_MODE: true - ASSISTANT_ONLY: true - PROCESS_EXISTING: false - DEBOUNCE_DELAY: 3000 - REQUIRE_TERMINATOR: true - SETTLE_CHECK_MS: 800 - SETTLE_POLL_MS: 200 - API_TIMEOUT_MS: 60000 - MAX_RETRIES: 2 - DEDUPE_TTL_MS: 2592000000 - COLD_START_MS: 2000 - SHOW_EXECUTED_MARKER: true - CLEANUP_AFTER_MS: 30000 - CLEANUP_INTERVAL_MS: 60000 - APPEND_TRAILING_NEWLINE: true - AUTO_SUBMIT: true - POST_PASTE_DELAY_MS: 250 - SUBMIT_MODE: button_first - STUCK_AFTER_MS: 600000 - SCAN_DEBOUNCE_MS: 250 - FAST_WARN_MS: 50 - SLOW_WARN_MS: 60000 +๐Ÿ›ก๏ธ Safety-first โ€“ master STOP switch, strict schema checks, per-message caps, rate-limited command queue. - Supported Actions (required fields): - get_file: action, repo, path - list_files: action, repo, path - create_file: action, repo, path, content - update_file: action, repo, path, content - delete_file: action, repo, path - create_branch: action, repo, branch (source_branch defaults to main) - create_pr: action, repo, title, head, base - merge_pr: action, repo, pr_number - close_pr: action, repo, pr_number - create_issue: action, repo, title - comment_issue: action, repo, issue_number, body - close_issue: action, repo, issue_number - create_tag: action, repo, tag, target - create_release: action, repo, tag_name, name - rollback: action, repo, commit_sha +๐Ÿ”„ Persistent de-duplication โ€“ remembers executed commands for 30 days and exposes Run Again for manual re-runs. - Operation Summary: - 1) Monitor assistant messages - 2) Detect a complete YAML command: header plus terminator - 3) Debounce and settle, then re-validate - 4) Execute via the bridge with retries and timeouts - 5) Show inline status and store dedupe record - 6) Expose a Run Again button for intentional re-execution +๐Ÿ•’ Streaming-safe โ€“ waits for full assistant output and composer readiness before pasting or submitting. - Runtime Helpers: - - AI_REPO_STOP(): emergency stop - - AI_REPO_CLEAR_HISTORY(): clear dedupe history - - window.AI_REPO_COMMANDER: monitor, config, tests, history +๐Ÿงญ Queue manager โ€“ serializes multiple commands from one response, limits per-minute rate, allows clear/cancel. - Security Model: - - Bridge key stored locally and masked, never logged - - Field validation including path safety and typed values - - Assistant-only and code-block-only execution by default - - STOP immediately halts scanning and API calls +๐Ÿ’ฌ Inline feedback โ€“ status chips, console logs, and desktop notifications for every stage. - Changelog v1.4.1 (summary): - - Tools and Settings panel (bridge key editor, clear history, JSON config) - - Parser hardening for multiline content and body/message fields - - New routes: PRs, Issues, Releases, Tags, Rollback - - Per-conversation dedupe with Run Again UI - - Streaming settle improvements and debounce - - Auto-submit and paste fallback sequence - - Configurable timeouts and retry policy \ No newline at end of file +๐Ÿงฐ Debug Panel โ€“ draggable / collapsible UI with: + +Tools & Settings tab (bridge key editor, config JSON, clear history, queue controls) + +Real-time log viewer with copy buttons + +Pause/Resume toggle and emergency STOP + +๐ŸŒ Cross-platform โ€“ works with ChatGPT, Claude, Gemini, and others. + +โš™๏ธ Quick Start + +Install Tampermonkey or Violentmonkey. + +Create a new userscript and paste src/ai-repo-commander.user.js. + +In chat, have the assistant output YAML like: + +@bridge@ +action: list_files +owner: rob +repo: ai-workflow-test +path: . +@end@ + + +When prompted, enter your bridge key (stored locally, masked). + +Use the debug panel โ†’ Tools & Settings to adjust behavior, clear history, or manage the queue. + +๐Ÿงฉ Default Configuration (excerpt) +ENABLE_API: true +DEBUG_MODE: true +ASSISTANT_ONLY: true +PROCESS_EXISTING: false +DEBOUNCE_DELAY: 3000 +REQUIRE_TERMINATOR: true +SETTLE_CHECK_MS: 800 +SETTLE_POLL_MS: 200 +API_TIMEOUT_MS: 60000 +MAX_RETRIES: 2 +DEDUP_TTL_MS: 2592000000 # 30 days +COLD_START_MS: 2000 +SHOW_EXECUTED_MARKER: true +CLEANUP_AFTER_MS: 30000 +CLEANUP_INTERVAL_MS: 60000 +APPEND_TRAILING_NEWLINE: true +AUTO_SUBMIT: true +POST_PASTE_DELAY_MS: 250 +SUBMIT_MODE: button_first +STUCK_AFTER_MS: 600000 +SCAN_DEBOUNCE_MS: 250 +FAST_WARN_MS: 50 +SLOW_WARN_MS: 60000 +QUEUE_MIN_DELAY_MS: 800 +QUEUE_MAX_PER_MINUTE: 15 +QUEUE_MAX_PER_MESSAGE: 5 +QUEUE_WAIT_FOR_COMPOSER_MS: 6000 + +๐Ÿงฐ Supported Actions (required fields) +Category Action Required fields +Files get_file, list_files, create_file, update_file, delete_file repo, path (+ content for create/update) +Branch & PR create_branch, create_pr, merge_pr, close_pr see branch, head, base, pr_number +Issues create_issue, comment_issue, close_issue issue_number or title, body +Tags & Releases create_tag, create_release tag / tag_name, target, name +Maintenance rollback commit_sha +๐Ÿงฎ Operation Summary + +Monitor assistant messages in real time. + +Detect every complete YAML block (@bridge@ โ†’ @end@). + +Queue all valid commands โ€“ rate-limited and serialized. + +Debounce + Settle, re-validate, and call your bridge API. + +Paste or submit responses back into chat once the composer is ready. + +Show feedback inline + notifications and persist dedupe history. + +Allow re-execution via the Run Again button or queue controls. + +๐Ÿง  Runtime Helpers +Function Purpose +AI_REPO_STOP() Emergency stop โ€“ kills scanning + clears the queue. +AI_REPO_CLEAR_HISTORY() Forget all dedupe records for this conversation. +window.AI_REPO_QUEUE.clear() Manually empty the command queue. +window.AI_REPO_COMMANDER Exposes monitor, config, history, tests, etc. +๐Ÿ” Security Model + +Bridge key stored locally, masked, never logged or transmitted beyond the bridge call. + +Field-level validation for paths, types, and required keys. + +Assistant-only + code-block-only execution by default. + +Hard STOP halts scanning, clears queue, and disables API immediately. + +Optional ASSISTANT_ONLY and PROCESS_EXISTING flags protect against replay. + +๐Ÿงพ Changelog Highlights +v1.6 series + +๐Ÿ” Multi-command execution with rate-limited queue + +๐Ÿ• Per-message and per-minute caps + +๐Ÿ“ฆ Queue UI controls + size indicator + clear button + +โœจ Improved paste pipeline (wait for composer ready, re-enqueue if busy) + +๐Ÿงฉ Index-aware dedupe and retry for multi-block messages + +๐Ÿงฑ Cleaner Debug Panel buttons with click feedback (flash + toast) + +v1.5 series + +๐ŸชŸ Draggable Debug Panel with Tools & Settings tab + +โš™๏ธ Persistent config storage and JSON editor + +๐Ÿงน Clear History button and pause/resume toggle + +๐Ÿ” Enhanced logging and structured debug levels + +v1.4 series + +Parser hardening for multiline content and body/message fields + +New routes: PRs, Issues, Releases, Tags, Rollback + +Per-conversation dedupe with Run Again UI + +Streaming settle improvements and auto-submit fallbacks + +๐Ÿงช Example Usage +@bridge@ +action: update_file +owner: rob +repo: ai-workflow-test +path: roles/mission_control.md +content: | + Updated mission protocol โ€” verified. +@end@ + + +You can also send several commands in one reply: + +@bridge@ +action: update_file +repo: ai-workflow-test +path: tmp/a.md +content: First file +@end@ + +@bridge@ +action: update_file +repo: ai-workflow-test +path: tmp/b.md +content: Second file +@end@ + + +AI Repo Commander will queue both, run them safely in order, and display progress and results.