gitlore/README.md

# 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.

## Features

- **Local-first**: All data stored in SQLite for instant queries
- **Incremental sync**: Cursor-based sync only fetches changes since last sync
- **Multi-project**: Track issues across multiple GitLab projects
- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date
- **Raw payload storage**: Preserves original GitLab API responses for debugging

## Installation

```bash
cargo install --path .
```

Or build from source:

```bash
cargo build --release
./target/release/gi --help
```

## Quick Start

```bash
# Initialize configuration (interactive)
gi init

# Verify authentication
gi auth-test

# Sync issues from GitLab
gi ingest --type issues

# List recent issues
gi list issues --limit 10

# Show issue details
gi show issue 123 --project group/repo
```

## Configuration

Configuration is stored in `~/.config/gi/config.json` (or `$XDG_CONFIG_HOME/gi/config.json`).

### Example Configuration

```json
{
  "gitlab": {
    "baseUrl": "https://gitlab.com",
    "tokenEnvVar": "GITLAB_TOKEN"
  },
  "projects": [
    { "path": "group/project" },
    { "path": "other-group/other-project" }
  ],
  "sync": {
    "backfillDays": 14,
    "staleLockMinutes": 10
  },
  "storage": {
    "compressRawPayloads": true
  }
}
```

### Configuration Options

| Section | Field | Default | Description |
|---------|-------|---------|-------------|
| `gitlab` | `baseUrl` | — | GitLab instance URL (required) |
| `gitlab` | `tokenEnvVar` | `GITLAB_TOKEN` | Environment variable containing API token |
| `projects` | `path` | — | Project path (e.g., `group/project`) |
| `sync` | `backfillDays` | `14` | Days to backfill on initial sync |
| `sync` | `staleLockMinutes` | `10` | Minutes before sync lock considered stale |
| `sync` | `cursorRewindSeconds` | `2` | Seconds to rewind cursor for overlap safety |
| `storage` | `dbPath` | `~/.local/share/gi/gi.db` | Database file path |
| `storage` | `compressRawPayloads` | `true` | Compress stored API responses |

### GitLab Token

Create a personal access token with `read_api` scope:

1. Go to GitLab → Settings → Access Tokens
2. Create token with `read_api` scope
3. Export it: `export GITLAB_TOKEN=glpat-xxxxxxxxxxxx`

## Commands

### `gi init`

Initialize configuration and database interactively.

```bash
gi init                    # Interactive setup
gi init --force            # Overwrite existing config
gi init --non-interactive  # Fail if prompts needed
```

### `gi auth-test`

Verify GitLab authentication is working.

```bash
gi auth-test
# Authenticated as @username (Full Name)
# GitLab: https://gitlab.com
```

### `gi doctor`

Check environment health and configuration.

```bash
gi doctor          # Human-readable output
gi doctor --json   # JSON output for scripting
```

### `gi ingest`

Sync data from GitLab to local database.

```bash
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 list issues`

Query issues from local database.

```bash
gi list issues                              # Recent issues (default 50)
gi list issues --limit 100                  # More results
gi list issues --state opened               # Only open issues
gi list issues --state closed               # Only closed issues
gi list issues --author username            # By author
gi list issues --assignee username          # By assignee
gi list issues --label bug                  # By label (AND logic)
gi list issues --label bug --label urgent   # Multiple labels
gi list issues --milestone "v1.0"           # By milestone title
gi list issues --since 7d                   # Updated in last 7 days
gi list issues --since 2w                   # Updated in last 2 weeks
gi list issues --since 2024-01-01           # Updated since date
gi list issues --due-before 2024-12-31      # Due before date
gi list issues --has-due-date               # Only issues with due dates
gi list issues --project group/repo         # Filter by project
gi list issues --sort created --order asc   # Sort options
gi list issues --open                       # Open first result in browser
gi list issues --json                       # JSON output
```

### `gi show issue`

Display detailed issue information.

```bash
gi show issue 123                      # Show issue #123
gi show issue 123 --project group/repo # Disambiguate if needed
```

### `gi count`

Count entities in local database.

```bash
gi count issues                    # Total issues
gi count discussions               # Total discussions
gi count discussions --type issue  # Issue discussions only
gi count notes                     # Total notes
```

### `gi sync-status`

Show current sync state and watermarks.

```bash
gi sync-status
```

### `gi migrate`

Run pending database migrations.

```bash
gi migrate
```

### `gi version`

Show version information.

```bash
gi version
```

## Database Schema

Data is stored in SQLite with the following main tables:

- **projects**: Tracked GitLab projects
- **issues**: Issue metadata (title, state, author, assignee info, due date, milestone)
- **milestones**: Project milestones with state and due dates
- **issue_assignees**: Many-to-many issue-assignee relationships
- **labels**: Project labels with colors
- **issue_labels**: Many-to-many issue-label relationships
- **discussions**: Issue/MR discussions
- **notes**: Individual notes within discussions
- **raw_payloads**: Compressed original API responses

The database is stored at `~/.local/share/gi/gi.db` by default.

## Global Options

```bash
gi --config /path/to/config.json <command>  # Use alternate config
```

## Development

```bash
# Run tests
cargo test

# Run with debug logging
RUST_LOG=gi=debug gi list issues

# Check formatting
cargo fmt --check

# Lint
cargo clippy
```

## Tech Stack

- **Rust** (2024 edition)
- **SQLite** via rusqlite (bundled)
- **clap** for CLI parsing
- **reqwest** for HTTP
- **tokio** for async runtime
- **serde** for serialization
- **tracing** for logging

## License

MIT