GitMop Assistant
Assists with developing GitMop, a terminal UI application for managing GitHub repositories with bulk operations.
What This Skill Does
Helps you work with the GitMop codebase, a Rust TUI application that enables bulk archiving, deletion, and downloading of GitHub repositories. Provides guidance on architecture, common commands, testing, and best practices specific to this project.
Architecture Overview
GitMop follows a modular Rust architecture:
**`main.rs`**: Entry point - CLI parsing, config loading, auth setup, TUI launch**`lib.rs`**: Library root exposing public modules**`auth/`**: GitHub OAuth device flow with token persistence to `~/.config/gitmop/auth.json`**`github.rs`**: `GitHubClient` wrapper around octocrab for GitHub API**`config.rs`**: User preferences persisted to `~/.config/gitmop/config.json`**`domain.rs`**: Core types (`RepoAction`, `AppState`, `AppMode`, download structs)**`ui/app.rs`**: Main TUI using ratatui, handles input and orchestrates operations**`download.rs`**: Repository download with progress tracking**Key dependencies**: tokio (async), octocrab (GitHub API), ratatui + crossterm (TUI), secrecy (token handling), clap (CLI)
Step-by-Step Instructions
1. Understanding the Request
When the user asks for changes or features:
Determine which module(s) are affected (auth, github, ui, domain, download, config)Check if GitHub API changes are needed (requires octocrab familiarity)Consider impact on TUI flow and user experienceVerify if new config options or domain types are required2. Building and Testing
Run these commands to ensure changes work correctly:
```bash
Check compilation
cargo check
Build release binary
cargo build --release
Run all tests
cargo test
Format and lint
cargo fmt --all && cargo clippy --all-targets -- -D warnings
```
3. Running the Application
```bash
Dry-run mode (default, safe for testing)
cargo run
Execute mode (performs actual GitHub operations)
cargo run -- --execute
```
**Important**: Always test in dry-run mode first. Execute mode performs real archive/delete operations.
4. Working with GitHub Authentication
Requires `GITHUB_CLIENT_ID` environment variable (from GitHub OAuth App)Auth tokens stored in `~/.config/gitmop/auth.json`Uses device flow (user enters code at github.com/login/device)See `auth/` module for implementation details5. Modifying the TUI
TUI logic is in `ui/app.rs`Uses ratatui for rendering, crossterm for terminal controlState management via `AppState` and `AppMode` enums in `domain.rs`User input handled via crossterm eventsConfirmations required for destructive operations (typing "Yes, I am sure")6. Adding New Repository Operations
When adding new bulk operations:
1. Add action variant to `RepoAction` enum in `domain.rs`
2. Implement GitHub API call in `github.rs` via `GitHubClient`
3. Add UI handling in `ui/app.rs` for new action selection and confirmation
4. Update help text and documentation
5. Add tests for new functionality
7. Testing Strategy
Unit tests for domain logic and data transformationsIntegration tests for GitHub API interactions (may require mocking)Manual TUI testing in dry-run modeTest destructive operations carefully in a test GitHub account8. Code Quality Standards
Before committing:
```bash
Format code
cargo fmt --all
Check lints (fail on warnings)
cargo clippy --all-targets -- -D warnings
Ensure tests pass
cargo test
```
Examples
**Example 1: Adding a new repository filter**
```rust
// 1. Add filter to Config in config.rs
pub struct Config {
pub filter_archived: bool,
pub filter_private: bool,
pub new_filter_option: bool, // Add this
}
// 2. Implement filtering in github.rs
impl GitHubClient {
pub async fn list_repos(&self, config: &Config) -> Result<Vec<Repository>> {
let repos = self.octocrab.current().list_repos_for_authenticated_user()
.send()
.await?;
// Apply new filter
let filtered = repos.into_iter()
.filter(|r| !config.new_filter_option || meets_criteria(r))
.collect();
Ok(filtered)
}
}
// 3. Add UI toggle in ui/app.rs
// 4. Test with cargo test and cargo run
```
**Example 2: Running tests for specific module**
```bash
Test only the auth module
cargo test auth::
Test a specific function
cargo test test_repo_action_parse
Run with verbose output
cargo test -- --nocapture
```
Important Notes
**Dry-run mode is default**: Real operations require `--execute` flag**Destructive operations require confirmation**: User must type "Yes, I am sure"**Config and auth stored in `~/.config/gitmop/`**: Cross-platform location**Requires admin permissions**: Only lists repos where user has admin access**Rate limits**: Be mindful of GitHub API rate limits when testing bulk operations**OAuth setup**: Users need to create a GitHub OAuth app and set `GITHUB_CLIENT_ID`Constraints
Must maintain backwards compatibility with existing config filesAll GitHub operations must respect dry-run mode unless `--execute` is explicitly setToken handling must use `secrecy` crate to avoid accidental leakageUI must remain responsive during long-running operations (use async/await properly)Error messages should be user-friendly and actionable