From 17deaac7008501fc0b5a38882f58fc58efe965a1 Mon Sep 17 00:00:00 2001 From: rob Date: Fri, 10 Oct 2025 04:01:42 +0000 Subject: [PATCH] Update README.md Updated to match current operation. --- README.md | 224 ++++++++++++++++++++---------------------------------- 1 file changed, 84 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 8f495ec..7d4302e 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,26 @@ -๐Ÿง  AI Repo Commander + # AI Repo Commander -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. + 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`. -๐Ÿš€ Highlights + ## Highlights + - **Code-block only execution** (only fenced YAML with the bridge header runs) + - **Safety-first:** STOP switch, strict validation, debounce + settle + - **Resume-safe scanning:** resuming marks on-screen commands as processed and shows **Run again** instead of auto-executing + - **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 & auto-submit** with fallbacks for `get_file` -๐Ÿงฉ Code-block-only execution โ€“ only fenced YAML blocks beginning with @bridge@ and ending with @end@ run. + ## 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 `@bridge@` and ending with `@end@`. + 4) Enter your bridge key when prompted (you can store it in the panel). + 5) Adjust settings in Tools & Settings as needed. -๐Ÿ›ก๏ธ Safety-first โ€“ master STOP switch, strict schema checks, per-message caps, rate-limited command queue. - -๐Ÿ”„ Persistent de-duplication โ€“ remembers executed commands for 30 days and exposes Run Again for manual re-runs. - -๐Ÿ•’ Streaming-safe โ€“ waits for full assistant output and composer readiness before pasting or submitting. - -๐Ÿงญ Queue manager โ€“ serializes multiple commands from one response, limits per-minute rate, allows clear/cancel. - -๐Ÿ’ฌ Inline feedback โ€“ status chips, console logs, and desktop notifications for every stage. - -๐Ÿงฐ 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) + ## Default Configuration (excerpt) ENABLE_API: true DEBUG_MODE: true ASSISTANT_ONLY: true @@ -58,7 +31,7 @@ SETTLE_CHECK_MS: 800 SETTLE_POLL_MS: 200 API_TIMEOUT_MS: 60000 MAX_RETRIES: 2 -DEDUP_TTL_MS: 2592000000 # 30 days +DEDUPE_TTL_MS: 2592000000 COLD_START_MS: 2000 SHOW_EXECUTED_MARKER: true CLEANUP_AFTER_MS: 30000 @@ -71,113 +44,84 @@ 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 +markdown +Copy code -Monitor assistant messages in real time. +## 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 -Detect every complete YAML block (@bridge@ โ†’ @end@). +## 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 -Queue all valid commands โ€“ rate-limited and serialized. +## New in v1.6.2 +- **Resume-Safe Guard:** On resume, treat like a cold start and mark visible commands as processed, preventing accidental re-execution. +- **Example Field Support:** Add `example: true` to any command block to make it inert. Itโ€™s silently skipped (no error UI). +- **Paste Quality:** Added padding around pasted content to preserve triple-backtick fences in ProseMirror fields. +- **Debounce Timing Notes:** If you see โ€œdebouncing โ†’ error,โ€ try `DEBOUNCE_DELAY: 5000โ€“7000` and `SETTLE_CHECK_MS: 1200โ€“1500`. +- **Version:** Bumped to **1.6.2**. -Debounce + Settle, re-validate, and call your bridge API. +### Examples -Paste or submit responses back into chat once the composer is ready. +**Runnable (explicitly not an example):** +```yaml +@bridge@ +action: list_files +repo: rob/AI-Repo-Commander +path: . +example: false +@end@ +Inert example (skipped silently): -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 +yaml +Copy code @bridge@ action: update_file -owner: rob -repo: ai-workflow-test -path: roles/mission_control.md +repo: rob/AI-Repo-Commander +path: EXAMPLE.md content: | - Updated mission protocol โ€” verified. + This is just an example + It won't execute +example: true @end@ +Runtime Helpers +AI_REPO_STOP(): emergency stop +AI_REPO_CLEAR_HISTORY(): clear dedupe history -You can also send several commands in one reply: +window.AI_REPO_COMMANDER: monitor, config, tests, history -@bridge@ -action: update_file -repo: ai-workflow-test -path: tmp/a.md -content: First file -@end@ +Security Model +Bridge key stored locally and masked, never logged -@bridge@ -action: update_file -repo: ai-workflow-test -path: tmp/b.md -content: Second file -@end@ +Field validation including path safety and typed values +Assistant-only and code-block-only execution by default -AI Repo Commander will queue both, run them safely in order, and display progress and results. +STOP immediately halts scanning and API calls + +Changelog +v1.6.2 +Resume-safe guard; example: true support; ProseMirror paste padding; timing docs; version bump. + +v1.4.1 (previous) +Tools/Settings panel, parser hardening, new routes (PRs, Issues, Releases, Tags, Rollback), per-convo dedupe + Run Again UI, streaming settle improvements, auto-submit/paste fallback, configurable timeouts/retries. \ No newline at end of file