tuicr: Instructions file for Codex

AGENTS.md - tuicr

This document serves two purposes:

1. Help coding agents understand the tuicr codebase structure
2. Explain how to interpret review feedback generated by tuicr

Project Structure

tuicr is a Rust terminal UI application and library for code reviews. Here's the module structure:

src/
├── lib.rs               # Public crate surface: ReviewStore, session/comment types, core modules
├── main.rs              # Entry point, event loop, action dispatch
├── config/
│   └── mod.rs           # User config loading (XDG on Unix, %APPDATA% on Windows)
├── app.rs               # Application state (App struct, InputMode, etc.)
│   ├── coloring.rs      # Render-time syntax coloring of hunks near the viewport
│   ├── editor_target.rs # Read-only snapshots of a PR revision for `$EDITOR`
│   └── file_filter.rs   # File-tree include/exclude regex filters + `/` path search
├── error.rs             # Error types (TuicrError enum)
├── editor.rs            # External $EDITOR command construction and launch helpers
├── review_store.rs      # Library API for session listing/loading and shared comment insertion
├── review_cli.rs        # Non-interactive `tuicr review` subcommands over ReviewStore
├── update.rs            # Public update facade
├── update/
│   ├── check.rs         # Lightweight crates.io version checks for the TUI badge
│   ├── install.rs       # `tuicr update` orchestration, release verification, and runtime adapter
│   └── install/         # Install detection, archive extraction, replacement, and focused tests
├── tuicrignore.rs       # .tuicrignore loader + diff file filtering (gitignore-style patterns)
├── theme/
│   └── mod.rs           # Theme palette definitions + bundled/local theme resolution
│
├── vcs/                 # VCS abstraction layer
│   ├── mod.rs           # detect_vcs(): auto-detect VCS (jj first, then git, then hg)
│   ├── traits.rs        # VcsBackend trait, VcsInfo, VcsType, CommitInfo
│   ├── diff_parser.rs   # Strict, count-driven hunk parser over structured FilePatch values
│   ├── git/             # Git backend selector (libgit2 by default, CLI for sparse/opt-in)
│   │   ├── mod.rs       # GitBackend wrapper, backend preference, repo mode detection
│   │   ├── cli.rs       # Git CLI backend used for sparse checkouts and backend = "cli"
│   │   ├── raw.rs       # Exact `git diff --raw -z --patch` metadata/patch adapter
│   │   ├── libgit2.rs   # libgit2-backed implementation used for normal Git repos by default
│   │   ├── repository.rs # CommitInfo, get_recent_commits()
│   │   ├── diff.rs      # get_working_tree_diff(), get_commit_range_diff()
│   │   └── context.rs   # fetch_context_lines() for gap expansion
│   ├── hg/              # Mercurial backend (always compiled)
│   │   └── mod.rs       # HgBackend: uses hg CLI, parses with diff_parser::Hg
│   └── jj/              # Jujutsu backend (always compiled)
│       └── mod.rs       # JjBackend: uses jj CLI, parses with diff_parser::GitStyle
│
├── forge/               # Remote forge integration (GitHub PR, GitLab MR, Bitbucket PR,
│                        # Azure DevOps PR, Gerrit change review)
│   ├── mod.rs           # Detect and parse GitHub/GitLab/Bitbucket/Azure/Gerrit remotes
│                        # (parse_any_remote_url: Bitbucket, GitLab, Azure, Gerrit, then GitHub)
│   ├── traits.rs        # ForgeBackend trait, ForgeRepository, PullRequestTarget,
│   │                    # PullRequestDetails, PullRequestInfo, PrSessionKey,
│   │                    # CreateReviewRequest, GhCreateReviewResponse, ForgeFileLinesRequest
│   ├── pr_open.rs       # Async pr-open flow: build session from details + diff
│   ├── selector.rs      # Review target selector state (Local | Pull Requests tabs)
│   ├── context.rs       # Remote context expansion via ForgeBackend::fetch_file_lines
│   ├── local_git.rs     # Shared `git show <sha>:<path>` blob read for all backends
│   ├── remote_comments.rs # RemoteReviewThread shape + visibility filter
│   ├── submit.rs        # Submit pipeline: preflight mapping, resolver actions,
│   │                    # InlineComment payload, build_review_body, SubmitEvent
│   ├── gitea/           # Gitea backend via `tea` CLI
│   │   ├── mod.rs       # GiteaTeaBackend: ForgeBackend impl
│   │   ├── tea.rs       # TeaCommandRunner: spawn `tea api -i`, read HTTP status off stderr
│   │   └── models.rs    # JSON parsing for Gitea REST v1 responses
│   ├── github/          # GitHub backend via `gh` CLI
│   │   ├── mod.rs       # GitHubGhBackend: ForgeBackend impl
│   │   ├── gh.rs        # GhCommandRunner: spawn `gh`, parse output, error mapping
│   │   ├── models.rs    # JSON parsing for `gh` REST + GraphQL responses
│   │   ├── pr_info.rs   # Extended `gh pr view --json` parsing for PR description panel
│   │   ├── review_threads.rs # GraphQL query for existing review threads
│   │   ├── review_metadata.rs # GraphQL review commit metadata for since-last-review scoping
│   │   └── submit.rs    # build_review_payload, create_review wiring
│   ├── gitlab/          # GitLab backend via `glab` CLI
│   │   ├── mod.rs       # GitLabGlabBackend export
│   │   ├── glab.rs      # ForgeBackend impl and glab command runner
│   │   └── models.rs    # GitLab API response models
│   ├── bitbucket/       # Bitbucket Cloud backend via `bkt` CLI (no Data Center)
│   │   ├── mod.rs       # BitbucketBktBackend export
│   │   ├── bkt.rs       # ForgeBackend impl and bkt command runner
│   │   └── models.rs    # Bitbucket Cloud REST 2.0 response models
│   ├── azure/           # Azure DevOps backend via REST (PAT) or `az rest`
│   │   ├── mod.rs       # AzureDevOpsBackend export
│   │   ├── az.rs        # ForgeBackend impl, AzHttp transports, remote/target parsing
│   │   └── models.rs    # Azure DevOps REST 7.1 response models
│   └── gerrit/          # Gerrit backend via the Gerrit REST API (no CLI exists)
│       ├── mod.rs       # GerritBackend export
│       ├── api.rs       # ForgeBackend impl, GerritHttp transport, remote/target parsing
│       └── models.rs    # Gerrit REST response models (ChangeInfo, CommentInfo)
│
├── model/
│   ├── mod.rs
│   ├── comment.rs       # Comment, CommentType (Note/Suggestion/Issue/Praise)
│   ├── diff_types.rs    # DiffFile, DiffHunk, DiffLine, FileStatus, LineOrigin
│   └── review.rs        # ReviewSession, FileReview (the persisted review state)
│
├── input/
│   ├── mod.rs
│   ├── keybindings.rs   # Action enum, map_key_to_action() for each InputMode
│   └── mode.rs          # InputMode enum definition (unused, defined in app.rs)
│
├── persistence/
│   ├── mod.rs
│   └── storage.rs       # save_session, load_session, manifest-backed session lookups
│
├── output/
│   ├── mod.rs
│   └── markdown.rs      # export_to_clipboard(): generate markdown, copy to clipboard
│
└── ui/
    ├── mod.rs
    ├── app_layout.rs    # Main render function, file list, diff view with inline comments
    ├── pr_info_panel.rs # PR description panel (status, reviewers, checks, body)
    ├── comment_navigator.rs # Sidebar comment index for jumping local/remote comments
    ├── status_bar.rs    # Header, status bar, command line rendering
    ├── help_popup.rs    # Help overlay (? key)
    ├── summary_popup.rs # :summary view of pending local-draft comments
    ├── theme_picker.rs  # :theme runtime picker modal (live preview, / filter)
    ├── comment_panel.rs # Comment input dialog, confirm dialog
    └── styles.rs        # Color constants and style helper functions