marketplace/cli/internal/gitea/AGENTS.md

AGENTS.md — internal/gitea (TRANSPORT)

Everything that talks to a tracker, and nothing else. Numbers, logins, HTTP verbs, pagination, JSON.

It does not know what an issue is — no sections, no acceptance criteria, no type taxonomy — and the import graph says so in both directions: this package may not reach into issue, and issue may not reach in here. mapping is not imported either: it sits above this package, not beside it. TestTransportDoesNotImportTheDomain is the check.

file	what is in it
client.go	New, For, the payload-dumping RoundTripper, pagination, APIError and Fail, ListIssues and its budget
issues.go	GetIssue, CreateIssue, EditIssue, SetLabels, comments, milestones, dependencies
labels.go	ListLabels, CreateLabel, EditLabel
remotemap.go	RemoteMap — the number → slug ledger, and why nothing prunes it
client_test.go	pagination, error bodies, the scratchpad, the page budget, the version gate
remotemap_test.go	load, merge, save

What this package is, now that the SDK exists

The one place that holds the credentials, the scratchpad and the repository this project points at, so no command has to. Every method is a thin wrapper, and the wrapping is for the three things the SDK does not do:

• every request body is filed under .kettle/payload/ by a RoundTripper, so a retry or a post-mortem has the bytes that went out;
• every failure comes back as *APIError carrying the status and what the server said, because "500" on its own has never helped anybody. Gitea answers 422 for a label that already exists, for a milestone id belonging to another repository, and for a body missing a field — the three are told apart only by the message, so the body travels with the code, always;
• a listing stops when the caller has what it asked for, which a client that fetches whole pages into a slice cannot do.

The payload shapes are the SDK's, aliased sdk everywhere. The issue keys are still wire's — the SDK addresses an issue as (owner, repo, int64) and never parses owner/repo#42 out of anything.

Fail builds an *APIError out of an SDK (response, error) pair and is exported for cmd/release, the one caller outside this package that builds its own client — so "the tracker said no" has one spelling in the tree.

Building a client dials

New refuses a half-filled configuration before anything else, because building the client dials: the SDK asks the instance for its version before it hands one back. A missing token reported as a connection failure sends the operator to the wrong place. Every field it checks has exactly one command that supplies it.

That handshake is also what pays for the dependency gate below, and it is why every fake tracker in the test suite answers /api/v1/version.

For(repo) returns a copy pointed at another repository — bookkeeping, not a second connection, since the SDK takes the owner and name per call. Credentials, the negotiated version and the scratchpad are shared, which is what makes kettle pull owner/repo#42 cost nothing extra.

The scratchpad

.kettle/payload/ is a sibling of the store, never a child: request bodies are debris of the transport, and a scratchpad inside a store makes ls .kettle/issues lie about what exists. It is written by the RoundTripper, so every request with a body is filed and not only the ones a call site remembered to name — a name only decides what the file is called.

A run that sends nothing, which includes every read-only command, leaves no directory at all: the first write creates it. The dump is the same JSON the wire carried, re-indented and with <, > and & left alone, because the SDK marshals with encoding/json's escaping and a dump nobody can read is a dump nobody reads.

Listings, and the two boundaries

ListIssues makes one request per page, and a payload already carries the issue body — a whole milestone costs one call per page, not one per issue.

IssueFilter.Keep decides whether a payload counts against Limit. What Keep means is the caller's business; this package only counts. Two boundaries hold whatever it decides:

• stop at the limit — the page after the one that completed the budget is never requested;
• stop at the page budget — a filtered read scans at most PageSlack (4) times the pages Limit would need if every payload counted. A predicate that rejects everything must not turn a bounded read into a walk of the whole tracker. Hitting the budget unfilled sets IssueListing.Warning rather than answering short in silence — returned rather than printed, because the transport does not own the operator's terminal.

ResolveMilestone fails loudly, and that is the whole point of resolving before filtering: Gitea silently ignores a milestones= filter it cannot resolve and answers with the entire backlog, so a typo would read as "your milestone has 300 issues in it". It resolves against the whole listing rather than the SDK's GetMilestoneByName, which matches case-insensitively and would fold two different milestones into one. FindMilestone is its quiet counterpart for a push, where a milestone the tracker does not have means "filed without one".

ListMilestones returns both states, always: a milestone is closed the moment its work is done, and a listing that hid those would fail to resolve exactly the filter somebody types when they want to see what was in it. ListLabels is read from the repository and never from a cache — a cache answers "what did we create last time", and the question is "what does this repository have right now".

The ledger

.remote.json, inside the issue store, beside the issues it indexes — it is bookkeeping about issues and belongs where they are, not in the scratchpad.

Its entries outlive the files they name, and that is deliberate. A push deletes an issue's file the moment the tracker confirms the write, and the entry left behind is what makes the next pull of that number land on the same slug — so every depends: that pointed at it still resolves. Nothing prunes them, not push and not eviction, because "no file" no longer means "no such issue". A stale entry costs one line of JSON and is corrected the next time that number is pulled.

It is a cache, not a record. The order of authority:

the tracker      the issue, and the marker naming its slug
.remote.json     a local number -> slug ledger, a cache of that marker
the store        whatever happens to be checked out right now

Which is why LoadRemoteMap never fails — a missing, unreadable or malformed file is an empty ledger, since refusing to run would block the very pull that would rebuild it — and why a rebuild is a merge and never a replacement: the store is a subset of what the ledger knows, so starting from the files alone would throw away every entry it cannot see. Load, add what the files say, save.

Save is the one write here allowed to create the store, and only because of when it happens: the ledger is written the instant the tracker confirms a push and before the local file is deleted, so failing it over a missing directory would lose the slug at exactly the moment the local copy stops being the record.

Issue dependencies — the one endpoint with a story

depends: becomes a native Gitea link, which is what makes the tracker show the blocking panel and refuse to close a blocked issue first.

• Reading goes through the SDK (ListIssueDependencies).
• Writing does not. Gitea's own IssueMeta is {index, owner, repo} and has been since the endpoint existed; the SDK's is {index}, which can only link inside one repository, and a depends: entry is allowed to live somewhere else. So one hand-rolled POST survives, through the same HTTP client as everything else — same payload dump, same *APIError. The URL names the blocked issue and the body the blocker, which is the direction Dependencies reads back.
• The version gates both. The routes are absent from Gitea 1.19 and present in 1.20, checked against the release tags themselves, so an older instance is answered from the version it already gave us rather than from a 404 — which on an old server is also what "no such issue" looks like.
• A tracker that answers with a status still means "no dependencies here", because an instance that has the endpoint can still have them turned off for a repository, and a pull must bring the issue back either way. A dead connection is not that answer — the Python version swallowed both, and "the server said no" and "there was no server" are different answers.

A link that already exists answers 409, so callers pre-filter with DependencyKeys and treat a failure here as a note rather than an abort: one missing cross-link must not undo a push that has already created issues.

Two Gitea quirks worth knowing before touching anything

• EditIssue carries no labels. Gitea's edit endpoint takes none and neither does the SDK's option struct, so an issue whose labels changed needs SetLabels after it — push makes that call and says which names moved.
• A create can silently drop labels handed to it. SetLabels re-applies them rather than trusting the echo.

Keeping this file true

• Scope: every .go file here — the client, the endpoints it wraps, the scratchpad, the ledger, and the quirks that shape them.
• Update it when a method is added or removed, a request stops going through the SDK or starts to, the page budget or the version gate changes, the ledger's format or location changes, or a new Gitea quirk is worked around — a workaround with no written reason is a workaround somebody deletes.
• Do not explain what a field means to an issue. That is mapping's and issue's.