diple/AGENTS.md

AGENTS.md

Protected README preamble

The notice at the very top of README.md stating that the entire repository is AI-generated, including the adjacent placeholder for the repository owner's personal comments, is intentional and permanent.

Do not remove, replace, relocate, soften, or rewrite that preamble or its owner-comment placeholder. Only the repository owner may fill in or edit the placeholder. Changes elsewhere in the README must preserve this section verbatim and keep it before the project title.

Repository purpose

diple is a keyboard-first terminal UI for people receiving GitHub pull request reviews. It is a Go 1.24 application built with Bubble Tea and Lip Gloss. It uses GitHub's GraphQL and REST APIs, authenticates through the GitHub CLI or token environment variables, and keeps optional cache, draft, read-state, and local-AI data on disk.

The module path is:

git.pablu.de/Pablu/diple

The application is one package main. There is no internal package hierarchy, so keep new code close to the feature it serves and avoid introducing abstractions without a concrete second use.

Product boundaries

• The primary user is the PR author or assignee responding to a review, not the reviewer submitting one.
• Reading must remain useful when some GitHub subsections fail or cached data is temporarily stale.
• Mutations must be explicit, permission-aware, confirmed where destructive, and protected against stale PR heads where applicable.
• Local AI findings and discussions are local-only. They must never be published to GitHub implicitly.
• AI providers must not receive local checkout contents. Current AI context comes from authenticated GitHub PR data and filtered diffs.
• Never run code, hooks, tools, or repository commands on behalf of an AI provider. Preserve the hardened, tool-free provider boundary.
• The UI is keyboard-first. Similar actions should use the same configurable keybinding groups across screens.
• Narrow terminals, wrapped content, Unicode grapheme clusters, no-color mode, and high-contrast mode are supported behavior, not optional polish.

Important files

• main.go: startup, configuration application, service wiring, persistence, and Bubble Tea program creation.
• cli.go: CLI help and Bash, Zsh, and Fish completion generators.
• config.go: TOML schema, defaults, lookup paths, and validation.
• keybindings.go: configurable key groups, defaults, help labels, and contextual conflict validation.
• github.go: GitHub queries, pagination, mutations, capabilities, rate-limit reporting, and service interfaces.
• cache.go: immediate cached reads, offline fallback, content-aware writes, and bounded pruning.
• tui.go: main application state, updates, screens, rendering, refresh coordination, and contextual help.
• pr_editor.go, text_editor.go, branch_completion.go: PR metadata editor, reusable text editing, Vim-style motions/visual mode, and target-branch completion.
• markdown.go, markdown_editor_highlight.go: GitHub-flavored comment rendering and non-destructive editor highlighting.
• highlight.go, suggestions.go: syntax-highlighted diff hunks and GitHub suggestion previews.
• theme.go: built-in, custom, high-contrast, and no-color palettes.
• health.go: component health, stable status, rate limits, and session event history.
• conflicts.go: read-only conflicting-file discovery in a temporary bare Git repository; it must not depend on or modify the current Git/Jujutsu checkout.
• drafts.go, persistence.go: versioned, atomic local state.
• ai.go, ai_diff.go, ai_codex.go, ai_store.go, ai_tui.go: experimental local-only AI review, filtering, provider isolation, local storage, and UI.
• types.go: shared domain models and capability flags.
• TODO.md: future work; keep completed behavior out of open TODO sections.

Most source files have a corresponding _test.go. Add focused regression tests beside the code being changed.

Build and validation

Use the package, not an individual source file:

go run .
go test ./...
go test -race ./...
go vet ./...
go build ./...

Run gofmt on changed Go files. A normal implementation should at least pass go test ./...; changes involving asynchronous refreshes, provider progress, or shared persistence should also pass the race detector.

Do not use go run main.go: this repository relies on the other files in the same package.

Do not run Git commands or alter repository history unless the user explicitly asks. Preserve unrelated working-tree changes.

Architecture and state flow

App is the Bubble Tea model. GitHub operations return typed messages to Update; rendering belongs in View and feature-specific view helpers. Network calls, subprocesses, and disk reads must not block the update loop. Long operations should expose stable progress and support cancellation where possible.

GitHub access is expressed through narrow service interfaces. Keep compile-time interface assertions in main.go when implementations change. The cached service must preserve the capability behavior of the live service rather than silently bypassing write gates.

Refreshes are intentionally incremental:

• Render cached core data immediately when available.
• Replace it with live core data without blanking the current screen.
• Enrich checks, annotations, and conflict details independently.
• Retain the last complete subsection when one enrichment fails.
• Ignore results from superseded requests.

Do not turn partial failures into an all-or-nothing screen failure.

GitHub correctness and write safety

• Paginate list-like GitHub data or make any remaining bound visible.
• Treat GraphQL partial data and errors deliberately.
• Use the authenticated endpoint consistently, including GitHub Enterprise Server URL derivation.
• Respect rate limits, retry windows, and adaptive polling.
• Check the exposed capability gate before showing or executing a mutation.
• Preserve drafts if a mutation or post-mutation refresh fails.
• Require confirmation for merge, auto-merge, and other consequential actions.
• Use expected head OIDs where GitHub supports them; reject stale prepared actions instead of applying them to a changed PR.
• Sanitize untrusted GitHub and subprocess text before terminal rendering.
• Never interpolate untrusted content into shell commands.

Local persistence

Cache, state, drafts, and local-AI files are user data:

• Keep formats versioned.
• Write atomically.
• Use restrictive permissions for sensitive or user-authored content.
• Avoid rewriting unchanged files.
• Bound cache growth and preserve corrupt-file diagnostics in Health.
• Do not silently delete recoverable drafts or local review state.

Text, Markdown, and terminal behavior

• Terminal width is a runtime constraint. Wrap help, errors, paths, Markdown, editor lines, and modal content without losing structural prefixes.
• Measure display cells, not bytes or rune counts.
• Editing and selections must operate on grapheme boundaries.
• Soft-wrapped editor rows are virtual display rows: navigation may traverse them, but saved GitHub Markdown must reconstruct the original logical lines.
• Syntax and Markdown highlighting must not insert, remove, or replace editable characters.
• Keep the active pane visually distinguishable.
• Compact footers show only the first configured key for each action; the help popup may show all configured alternatives.
• Add new actions to contextual help and keybinding validation.

Themes

Do not hard-code feature colors outside the theme palette. New UI elements must remain legible in built-in dark/light themes, custom themes, high-contrast, and no-color. Syntax and Markdown highlighting should follow the selected theme rather than an independent fixed palette.

Experimental AI rules

The provider abstraction is intentionally broader than the current Codex CLI implementation. Keep provider-specific parsing in its adapter.

• AI remains disabled by default.
• Every inference run requires an explicit user action and scope confirmation.
• The inference-free status check and quota-consuming provider test must remain visibly distinct.
• Filter excluded/sensitive files, redact secret-like values, and enforce byte, file, call, output, and result-count limits.
• Treat paths, code, PR text, and comments as untrusted prompt data.
• Validate findings against changed diff lines and the prepared head.
• Pin one exact model for a run; never silently fall back.
• Reject attempted tool, command, or file-change events.
• Only display provider-exposed reasoning summaries. Never request, infer, log, or display hidden chain-of-thought.
• Store findings locally with deterministic deduplication and mark them outdated when the PR head changes.

Any future provider that sends data to a direct API needs explicit privacy and retention semantics documented before implementation.

Change discipline

Prefer small, idiomatic changes that preserve current behavior. Correctness comes before API consistency, and API consistency comes before refactoring. Do not rewrite working subsystems merely for style.

When behavior changes:

1. Identify the active screen and input context.
2. Update state transitions and cancellation behavior.
3. Update rendering, contextual help, and capability explanations.
4. Add or update regression tests.
5. Update README.md for user-visible configuration or workflow changes.
6. Update TODO.md only when work is genuinely completed or newly deferred.

If a product decision would materially affect persistence compatibility, GitHub writes, AI data exposure, destructive behavior, or default keybindings, ask the repository owner rather than guessing.