parent
4dc458451d
commit
17deaac700
224
README.md
224
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.
|
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`.
|
||||||
It enforces strict validation, persistent de-duplication, and a command-queue pipeline that prevents overloads while staying streaming-safe and cross-assistant compatible.
|
|
||||||
|
|
||||||
🚀 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.
|
## Default Configuration (excerpt)
|
||||||
|
|
||||||
🔄 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)
|
|
||||||
ENABLE_API: true
|
ENABLE_API: true
|
||||||
DEBUG_MODE: true
|
DEBUG_MODE: true
|
||||||
ASSISTANT_ONLY: true
|
ASSISTANT_ONLY: true
|
||||||
|
|
@ -58,7 +31,7 @@ SETTLE_CHECK_MS: 800
|
||||||
SETTLE_POLL_MS: 200
|
SETTLE_POLL_MS: 200
|
||||||
API_TIMEOUT_MS: 60000
|
API_TIMEOUT_MS: 60000
|
||||||
MAX_RETRIES: 2
|
MAX_RETRIES: 2
|
||||||
DEDUP_TTL_MS: 2592000000 # 30 days
|
DEDUPE_TTL_MS: 2592000000
|
||||||
COLD_START_MS: 2000
|
COLD_START_MS: 2000
|
||||||
SHOW_EXECUTED_MARKER: true
|
SHOW_EXECUTED_MARKER: true
|
||||||
CLEANUP_AFTER_MS: 30000
|
CLEANUP_AFTER_MS: 30000
|
||||||
|
|
@ -71,113 +44,84 @@ STUCK_AFTER_MS: 600000
|
||||||
SCAN_DEBOUNCE_MS: 250
|
SCAN_DEBOUNCE_MS: 250
|
||||||
FAST_WARN_MS: 50
|
FAST_WARN_MS: 50
|
||||||
SLOW_WARN_MS: 60000
|
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)
|
markdown
|
||||||
Category Action Required fields
|
Copy code
|
||||||
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.
|
## 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.
|
yaml
|
||||||
|
Copy code
|
||||||
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@
|
@bridge@
|
||||||
action: update_file
|
action: update_file
|
||||||
owner: rob
|
repo: rob/AI-Repo-Commander
|
||||||
repo: ai-workflow-test
|
path: EXAMPLE.md
|
||||||
path: roles/mission_control.md
|
|
||||||
content: |
|
content: |
|
||||||
Updated mission protocol — verified.
|
This is just an example
|
||||||
|
It won't execute
|
||||||
|
example: true
|
||||||
@end@
|
@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@
|
Security Model
|
||||||
action: update_file
|
Bridge key stored locally and masked, never logged
|
||||||
repo: ai-workflow-test
|
|
||||||
path: tmp/a.md
|
|
||||||
content: First file
|
|
||||||
@end@
|
|
||||||
|
|
||||||
@bridge@
|
Field validation including path safety and typed values
|
||||||
action: update_file
|
|
||||||
repo: ai-workflow-test
|
|
||||||
path: tmp/b.md
|
|
||||||
content: Second file
|
|
||||||
@end@
|
|
||||||
|
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue