125 lines
4.6 KiB
Markdown
125 lines
4.6 KiB
Markdown
# 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`.
|
||
|
||
## 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`
|
||
|
||
## 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.
|
||
|
||
## 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
|
||
```
|
||
|
||
## 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_repo`: action, repo
|
||
- `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
|
||
##### * **owner defaults to config or repository prefix**
|
||
|
||
## 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
|
||
|
||
## 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**.
|
||
|
||
### Examples
|
||
|
||
**Runnable - Not an example - (example: false (or absence) is runnable):**
|
||
```yaml
|
||
@bridge@
|
||
action: list_files
|
||
repo: rob/AI-Repo-Commander
|
||
path: .
|
||
@end@
|
||
```
|
||
**Inert example (skipped silently):**
|
||
|
||
```yaml
|
||
@bridge@
|
||
action: update_file
|
||
repo: rob/AI-Repo-Commander
|
||
path: EXAMPLE.md
|
||
content: |
|
||
This is just an example
|
||
It won't execute
|
||
example: true
|
||
@end@
|
||
```
|
||
## Runtime Helpers
|
||
|
||
- AI_REPO_STOP(): emergency stop
|
||
- AI_REPO.clearHistory: clear dedupe history
|
||
- window.AI_REPO_COMMANDER: monitor, config, tests, history
|
||
|
||
## 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
|
||
|
||
### 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. |