diff --git a/AGENTS.md b/AGENTS.md index e88c80f..2b5b266 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,3 +164,88 @@ git push # Push to remote - Always `bd sync` before ending session + +--- + +## GitLab Inbox Robot Mode + +The `gi` CLI has a robot mode optimized for AI agent consumption with structured JSON output, meaningful exit codes, and TTY auto-detection. + +### Activation + +```bash +# Explicit flag +gi --robot list issues + +# Auto-detection (when stdout is not a TTY) +gi list issues | jq . + +# Environment variable +GI_ROBOT=1 gi list issues +``` + +### Robot Mode Commands + +```bash +# List issues/MRs with JSON output +gi --robot list issues --limit=10 +gi --robot list mrs --state=opened + +# Count entities +gi --robot count issues +gi --robot count discussions --type=mr + +# Show detailed entity info +gi --robot show issue 123 +gi --robot show mr 456 --project=group/repo + +# Check sync status +gi --robot sync-status + +# Run ingestion (quiet, JSON summary) +gi --robot ingest --type=issues + +# Check environment health +gi --robot doctor +``` + +### Response Format + +All commands return consistent JSON: + +```json +{"ok":true,"data":{...},"meta":{...}} +``` + +Errors return structured JSON to stderr: + +```json +{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'gi init'"}} +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | Internal error | +| 2 | Config not found | +| 3 | Config invalid | +| 4 | Token not set | +| 5 | GitLab auth failed | +| 6 | Resource not found | +| 7 | Rate limited | +| 8 | Network error | +| 9 | Database locked | +| 10 | Database error | +| 11 | Migration failed | +| 12 | I/O error | +| 13 | Transform error | + +### Best Practices + +- Use `gi --robot` for all agent interactions +- Check exit codes for error handling +- Parse JSON errors from stderr +- Use `--limit` to control response size +- TTY detection handles piped commands automatically diff --git a/Cargo.toml b/Cargo.toml index edb1b7f..90df70b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,7 +20,7 @@ serde = { version = "1", features = ["derive"] } serde_json = "1" # CLI -clap = { version = "4", features = ["derive"] } +clap = { version = "4", features = ["derive", "env"] } dialoguer = "0.12" console = "0.16" indicatif = "0.18" diff --git a/README.md b/README.md index 243e7cd..2e67c69 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ # gi - GitLab Inbox -A command-line tool for managing GitLab issues locally. Syncs issues, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying and filtering. +A command-line tool for managing GitLab issues and merge requests locally. Syncs issues, MRs, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying and filtering. ## Features - **Local-first**: All data stored in SQLite for instant queries - **Incremental sync**: Cursor-based sync only fetches changes since last sync - **Full re-sync**: Reset cursors and fetch all data from scratch when needed -- **Multi-project**: Track issues across multiple GitLab projects -- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date +- **Multi-project**: Track issues and MRs across multiple GitLab projects +- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches - **Raw payload storage**: Preserves original GitLab API responses for debugging +- **Discussion threading**: Full support for issue and MR discussions including inline code review comments ## Installation @@ -36,11 +37,20 @@ gi auth-test # Sync issues from GitLab gi ingest --type issues +# Sync merge requests from GitLab +gi ingest --type mrs + # List recent issues gi list issues --limit 10 +# List open merge requests +gi list mrs --state opened + # Show issue details gi show issue 123 --project group/repo + +# Show MR details with discussions +gi show mr 456 --project group/repo ``` ## Configuration @@ -163,13 +173,19 @@ Checks performed: Sync data from GitLab to local database. ```bash +# Issues gi ingest --type issues # Sync all projects gi ingest --type issues --project group/repo # Single project gi ingest --type issues --force # Override stale lock gi ingest --type issues --full # Full re-sync (reset cursors) + +# Merge Requests +gi ingest --type mrs # Sync all projects +gi ingest --type mrs --project group/repo # Single project +gi ingest --type mrs --full # Full re-sync (reset cursors) ``` -The `--full` flag resets sync cursors and fetches all data from scratch, useful when: +The `--full` flag resets sync cursors and discussion watermarks, then fetches all data from scratch. Useful when: - Assignee data or other fields were missing from earlier syncs - You want to ensure complete data after schema changes - Troubleshooting sync issues @@ -201,6 +217,35 @@ gi list issues --json # JSON output Output includes: IID, title, state, author, assignee, labels, and update time. +### `gi list mrs` + +Query merge requests from local database. + +```bash +gi list mrs # Recent MRs (default 50) +gi list mrs --limit 100 # More results +gi list mrs --state opened # Only open MRs +gi list mrs --state merged # Only merged MRs +gi list mrs --state closed # Only closed MRs +gi list mrs --state locked # Only locked MRs +gi list mrs --state all # All states +gi list mrs --author username # By author (@ prefix optional) +gi list mrs --assignee username # By assignee (@ prefix optional) +gi list mrs --reviewer username # By reviewer (@ prefix optional) +gi list mrs --draft # Only draft/WIP MRs +gi list mrs --no-draft # Exclude draft MRs +gi list mrs --target-branch main # By target branch +gi list mrs --source-branch feature/foo # By source branch +gi list mrs --label needs-review # By label (AND logic) +gi list mrs --since 7d # Updated in last 7 days +gi list mrs --project group/repo # Filter by project +gi list mrs --sort created --order asc # Sort options +gi list mrs --open # Open first result in browser +gi list mrs --json # JSON output +``` + +Output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time. + ### `gi show issue` Display detailed issue information. @@ -212,14 +257,27 @@ gi show issue 123 --project group/repo # Disambiguate if needed Shows: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions. +### `gi show mr` + +Display detailed merge request information. + +```bash +gi show mr 456 # Show MR !456 +gi show mr 456 --project group/repo # Disambiguate if needed +``` + +Shows: title, description, state, draft status, author, assignees, reviewers, labels, source/target branches, merge status, web URL, and threaded discussions. Inline code review comments (DiffNotes) display file context in the format `[src/file.ts:45]`. + ### `gi count` Count entities in local database. ```bash gi count issues # Total issues +gi count mrs # Total MRs (with state breakdown) gi count discussions # Total discussions gi count discussions --type issue # Issue discussions only +gi count discussions --type mr # MR discussions only gi count notes # Total notes (shows system vs user breakdown) ``` @@ -233,7 +291,7 @@ gi sync-status Displays: - Last sync run details (status, timing) -- Cursor positions per project and resource type +- Cursor positions per project and resource type (issues and MRs) - Data summary counts ### `gi migrate` @@ -282,12 +340,16 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables: |-------|---------| | `projects` | Tracked GitLab projects with metadata | | `issues` | Issue metadata (title, state, author, due date, milestone) | +| `merge_requests` | MR metadata (title, state, draft, branches, merge status) | | `milestones` | Project milestones with state and due dates | | `labels` | Project labels with colors | | `issue_labels` | Many-to-many issue-label relationships | | `issue_assignees` | Many-to-many issue-assignee relationships | +| `mr_labels` | Many-to-many MR-label relationships | +| `mr_assignees` | Many-to-many MR-assignee relationships | +| `mr_reviewers` | Many-to-many MR-reviewer relationships | | `discussions` | Issue/MR discussion threads | -| `notes` | Individual notes within discussions (with system note flag) | +| `notes` | Individual notes within discussions (with system note flag and DiffNote position data) | | `sync_runs` | Audit trail of sync operations | | `sync_cursors` | Cursor positions for incremental sync | | `app_locks` | Crash-safe single-flight lock | @@ -334,15 +396,16 @@ cargo clippy ## Current Status -This is Checkpoint 1 (CP1) of the GitLab Knowledge Engine project. Currently implemented: +This is Checkpoint 2 (CP2) of the GitLab Knowledge Engine project. Currently implemented: - Issue ingestion with cursor-based incremental sync -- Discussion and note syncing for issues -- Rich filtering and querying -- Full re-sync capability +- Merge request ingestion with cursor-based incremental sync +- Discussion and note syncing for issues and MRs +- DiffNote support for inline code review comments +- Rich filtering and querying for both issues and MRs +- Full re-sync capability with watermark reset Not yet implemented: -- Merge request support (CP2) - Semantic search with embeddings (CP3+) - Backup and reset commands