AGENTS.md

1# AGENTS.md
2 
3This is the GitHub CLI (`gh`), a command-line tool for interacting with GitHub. The module path is `github.com/cli/cli/v2`.
4 
5## Security Disclosures
6 
7**Never** post security-related content - vulnerabilities, exploits, proofs of concept, or attack details - in any issue, pull request, comment, commit, or discussion. Stop and file a security advisory per [`.github/SECURITY.md`](.github/SECURITY.md).
8 
9## Build, Test, and Lint
10 
11```bash
12make                                       # Build (Unix) — outputs bin/gh
13go run script/build.go                     # Build (Windows)
14go test ./...                              # All unit tests
15go test ./pkg/cmd/issue/list/... -run TestIssueList_nontty  # Single test
16go test -tags acceptance ./acceptance      # Acceptance tests
17make lint                                  # golangci-lint (same as CI)
18```
19 
20**Before committing, ensure both tests and linter pass:**
21```bash
22go test ./...
23make lint
24```
25 
26## Architecture
27 
28Entry point: `cmd/gh/main.go` → `internal/ghcmd.Main()` → `pkg/cmd/root.NewCmdRoot()`.
29 
30Key packages:
31- `pkg/cmd/<command>/<subcommand>/` — CLI command implementations
32- `pkg/cmdutil/` — Factory, error types, flag helpers (`NilStringFlag`, `NilBoolFlag`, `StringEnumFlag`)
33- `pkg/iostreams/` — I/O abstraction with TTY detection, color, pager
34- `pkg/httpmock/` — HTTP mocking for tests
35- `api/` — GitHub API client (GraphQL + REST)
36- `internal/featuredetection/` — GitHub.com vs GHES capability detection
37- `internal/tableprinter/` — Table output for list commands
38 
39## Command Structure
40 
41A command `gh foo bar` lives in `pkg/cmd/foo/bar/` with `bar.go`, `bar_test.go`, and optionally `http.go`/`http_test.go`.
42 
43### Canonical Examples
44 
45- **Command + tests**: `pkg/cmd/issue/list/list.go` and `list_test.go`
46- **Factory wiring**: `pkg/cmd/factory/default.go`
47- **Unit tests**: `internal/agents/detect_test.go`
48 
49### The Options + Factory Pattern
50 
51Every command follows this structure (see `pkg/cmd/issue/list/list.go`):
52 
531. `Options` struct with `IO`, `HttpClient`, `Config`, `BaseRepo` + flags
542. `NewCmdFoo(f *cmdutil.Factory, runF func(*FooOptions) error)` constructor — `runF` is the test injection point
553. Separate `fooRun(opts)` function with the business logic
56 
57Key rules:
58- Lazy-init `BaseRepo`, `Remotes`, `Branch` inside `RunE`, not the constructor
59- Commands register in `pkg/cmd/root/root.go`; subcommand groups use `cmdutil.AddGroup()`
60 
61### Command Examples and Help Text
62 
63Use `heredoc.Doc` for examples with `#` comment lines and `$ ` command prefixes:
64```go
65Example: heredoc.Doc(`
66    # Do the thing
67    $ gh foo bar --flag value
68`),
69```
70 
71### JSON Output
72 
73Add `--json`, `--jq`, `--template` flags via `cmdutil.AddJSONFlags(cmd, &opts.Exporter, fieldNames)`. In the run function: `if opts.Exporter != nil { return opts.Exporter.Write(opts.IO, data) }`. See `pkg/cmd/pr/list/list.go`.
74 
75## Testing
76 
77Test architecture for commands should generally follow this pattern:
78 
79- One table test for the command constructor (`NewCmdFoo`) to verify flag parsing and `Opts` curation.
80- One table test for the run function (`fooRun`) to verify business logic, output, and mocked HTTP/Git interactions.
81 
82### HTTP Mocking
83 
84Use `httpmock.Registry` with `defer reg.Verify(t)` to ensure all stubs are called:
85 
86```go
87reg := &httpmock.Registry{}
88defer reg.Verify(t)
89 
90reg.Register(
91    httpmock.REST("GET", "repos/OWNER/REPO"),
92    httpmock.JSONResponse(someData),
93)
94reg.Register(
95    httpmock.GraphQL(`query PullRequestList\b`),
96    httpmock.FileResponse("./fixtures/prList.json"),
97)
98client := &http.Client{Transport: reg}
99```
100 
101Common: `REST(method, path)`, `GraphQL(pattern)`, `JSONResponse(body)`, `FileResponse(path)`. See `pkg/httpmock/` for all matchers/responders.
102 
103### IOStreams in Tests
104 
105```go
106ios, stdin, stdout, stderr := iostreams.Test()
107ios.SetStdoutTTY(true)  // simulate terminal
108```
109 
110### Assertions
111 
112Use `testify`. Always use `require` (not `assert`) for error checks so the test halts immediately:
113 
114```go
115require.NoError(t, err)
116require.Error(t, err)
117assert.Equal(t, "expected", actual)
118```
119 
120### Generated Mocks
121 
122Interfaces use `moq`: `//go:generate moq -rm -out prompter_mock.go . Prompter`. Run `go generate ./...` after interface changes.
123 
124### Table-Driven Tests
125 
126Use table-driven tests for functions with multiple input/output scenarios. See `internal/agents/detect_test.go` or `pkg/cmd/issue/list/list_test.go` for examples:
127 
128```go
129tests := []struct {
130    name      string
131    // inputs and expected outputs
132}{
133    {name: "descriptive case name", ...},
134}
135for _, tt := range tests {
136    t.Run(tt.name, func(t *testing.T) {
137        // arrange, act, assert
138    })
139}
140```
141 
142## Code Style
143 
144- Add godoc comments to all exported functions, types, and constants
145- Avoid unnecessary code comments — only comment when the *why* isn't obvious from the code
146- Comments that imbue sanitized and summarized context from your conversation with a human are very valuable. For example, if you found during development that without the code something downstream would break, that's good context to include.
147- Do not comment just to restate what the code does
148- Never use em dashes (—) in code, comments, or documentation; use regular dashes (-) or rewrite the sentence instead
149 
150## Error Handling
151 
152Error types in `pkg/cmdutil/errors.go`:
153- `FlagErrorf(...)` — flag validation (prints usage)
154- `cmdutil.SilentError` — exit 1, no message
155- `cmdutil.CancelError` — user cancelled
156- `cmdutil.PendingError` — outcome pending
157- `cmdutil.NoResultsError` — empty results
158 
159Use `cmdutil.MutuallyExclusive("message", cond1, cond2)` for mutually exclusive flags.
160 
161## Feature Detection
162 
163Commands using feature detection must include a `// TODO <cleanupIdentifier>` comment directly above the if-statement for linter compliance:
164 
165```go
166// TODO someFeatureCleanup
167if features.SomeCapability {
168    // use new API
169} else {
170    // fallback for older GHES
171}
172```
173 
174Use feature detection only when an API is not GA on all supported GHES versions; skip it for long-established APIs.
175 
176## API Patterns
177 
178```go
179client := api.NewClientFromHTTP(httpClient)
180client.GraphQL(hostname, query, variables, &data)
181client.REST(hostname, "GET", "repos/owner/repo", nil, &data)
182```
183 
184For host resolution, use `cfg.Authentication().DefaultHost()`; do not use `ghinstance.Default()` which always returns `github.com`.
185 
186Avoid extra round-trips.
187 
188## Code Review
189 
190Review pull requests with the [`cli-code-reviewer` skill](.github/skills/cli-code-reviewer/SKILL.md).
191