@amonstack/gitea-mcp 0.2.2 → 0.3.1

package/dist/credentials.js

@@ -0,0 +1,141 @@
+/**
+ * Credential candidate model and state machine for fault-tolerant Gitea auth.
+ *
+ * A discovered credential is treated as an opaque candidate: the `secret`
+ * field might be a Gitea Personal Access Token, an account login password,
+ * or an OAuth token — the type cannot be determined statically from any
+ * source (`~/.git-credentials` stores whatever the user typed into git's
+ * password prompt, and `[gitea] token` / `GITEA_TOKEN` are by convention but
+ * not guarantee a PAT). The runtime therefore tries each candidate under
+ * one or more HTTP auth schemes, advancing on 401/403 until something works
+ * or every candidate × scheme is exhausted.
+ *
+ * This module is pure (no I/O, no fetch) so the state machine is unit-tested
+ * directly. Mutation is contained to per-candidate state fields; callers
+ * never replace the candidates array.
+ *
+ * SECURITY: `secret` is never logged, never interpolated into error
+ * messages, and never surfaced by `summarizeCandidates`. Diagnostic output
+ * only ever carries `secretPresent: boolean` and a masked `username`.
+ */
+/**
+ * Decide scheme ordering for a credential-store entry based on username
+ * heuristic. Config/env candidates always use `["token"]` (per project
+ * decision to preserve their "simple token" semantics).
+ *
+ * - Username `oauth2`, `x-oauth-basic`, or empty → `["token", "basic"]`:
+ *   these are git OAuth conventions; basic auth with such a username fails
+ *   for real passwords, so try `token` first.
+ * - Any other (real-looking) username → `["basic", "token"]`: basic auth
+ *   with the correct username works for both PATs and passwords, so it has
+ *   the widest coverage and goes first.
+ */
+export function orderSchemesForCredentialStore(username) {
+    if (username === undefined)
+        return ["token", "basic"];
+    const u = username.toLowerCase();
+    if (u === "oauth2" || u === "x-oauth-basic") {
+        return ["token", "basic"];
+    }
+    return ["basic", "token"];
+}
+/**
+ * Build the `Authorization` header value for one attempt. Mutates nothing.
+ *
+ * For `basic`, the username falls back to `oauth2` when absent (a missing
+ * username only happens for malformed credential-store entries; Gitea
+ * rejects basic auth without a username, so the attempt will fail and the
+ * state machine will advance).
+ */
+export function buildAuthHeader(candidate, scheme) {
+    if (scheme === "basic") {
+        const user = candidate.username ?? "oauth2";
+        const encoded = Buffer.from(`${user}:${candidate.secret}`).toString("base64");
+        return `Basic ${encoded}`;
+    }
+    return `token ${candidate.secret}`;
+}
+/**
+ * Pick the next (candidate, scheme) to try. Skips exhausted candidates and
+ * candidates whose scheme list is fully tried. Does NOT mutate state — the
+ * caller records the attempt via `markAttemptFailed` / `markAttemptSucceeded`.
+ *
+ * Returns null when every candidate × scheme has been tried.
+ */
+export function pickNextAttempt(candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        if (c.status === "exhausted")
+            continue;
+        // Active candidates are already locked — the caller short-circuits
+        // before entering this iteration loop (GiteaClient.request checks
+        // findActiveCandidateIndex first). Here we skip them defensively.
+        if (c.status === "active")
+            continue;
+        if (c.nextSchemeIndex >= c.schemes.length)
+            continue;
+        return { candidateIndex: i, scheme: c.schemes[c.nextSchemeIndex] };
+    }
+    return null;
+}
+/**
+ * Record that an attempt failed with `error` (a short reason like "401").
+ * Advances the candidate's scheme index; when no schemes remain, marks the
+ * candidate as exhausted.
+ */
+export function markAttemptFailed(candidates, candidateIndex, error) {
+    const c = candidates[candidateIndex];
+    c.lastError = error;
+    c.lastTriedScheme = c.schemes[c.nextSchemeIndex];
+    c.nextSchemeIndex += 1;
+    if (c.nextSchemeIndex >= c.schemes.length || c.status === "active") {
+        c.status = "exhausted";
+        c.activeScheme = undefined;
+    }
+}
+/**
+ * Record that an attempt succeeded. Marks the candidate as active, locks in
+ * `activeScheme`, and marks all PRIOR candidates as exhausted (they were
+ * tried and failed before this one succeeded).
+ */
+export function markAttemptSucceeded(candidates, candidateIndex, scheme) {
+    for (let i = 0; i < candidateIndex; i++) {
+        if (candidates[i].status !== "active")
+            candidates[i].status = "exhausted";
+    }
+    const c = candidates[candidateIndex];
+    c.status = "active";
+    c.activeScheme = scheme;
+    c.lastError = undefined;
+}
+/**
+ * Mask a username for diagnostic output: first character plus `***`. Returns
+ * null when the candidate has no username (config/env sources, or malformed
+ * credential-store entries).
+ */
+export function maskUsername(username) {
+    if (!username)
+        return null;
+    return `${username.charAt(0)}***`;
+}
+export function summarizeCandidates(candidates) {
+    return candidates.map((c) => ({
+        source: c.source,
+        schemes: c.schemes,
+        username: maskUsername(c.username),
+        secretPresent: c.secret.length > 0,
+        status: c.status,
+        lastTriedScheme: c.lastTriedScheme ?? null,
+        activeScheme: c.activeScheme ?? null,
+        lastError: c.lastError ?? null,
+    }));
+}
+/** Find the index of the active candidate, or null when none is active. */
+export function findActiveCandidateIndex(candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+        if (candidates[i].status === "active")
+            return i;
+    }
+    return null;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/git-config.d.ts

@@ -0,0 +1,97 @@
+import { type CredentialDiscoveryResult } from "./credentials.js";
+/** A single parsed git remote. `remote` is the remote name (`origin`, `upstream`, ...). */
+export interface ParsedRemote {
+    remote: string;
+    url: string;
+    host: string;
+    baseUrl: string;
+    owner: string;
+    repo: string;
+}
+/** A raw `[remote "<name>"]` url entry extracted from a git config file. */
+export interface RawRemote {
+    name: string;
+    url: string;
+}
+export interface DiscoverOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Override credential-store paths (defaults to XDG then `~/.git-credentials`). */
+    credentialsPaths?: string[];
+}
+/**
+ * A parsed `~/.git-credentials` line. Both `username` and `password` are
+ * URL-decoded. Either may be absent:
+ * - `https://user:pass@host` → both present
+ * - `https://:pass@host` → only password
+ * - `https://tok@host` → only username (git stores a token here when the
+ *   host accepts one as the "username"; the caller treats it as the secret)
+ *
+ * `path` is the URL pathname with leading/trailing slashes and any `.git`
+ * suffix stripped, used to narrow multiple host matches toward the target repo.
+ */
+export interface ParsedCredentialEntry {
+    username?: string;
+    password?: string;
+    host: string;
+    path: string;
+}
+/**
+ * Parse a git remote URL into host/baseUrl/owner/repo. Accepts `ssh://`, the
+ * scp-like `user@host:owner/repo` form, and `http(s)://`. SSH URLs derive an
+ * `https://` baseUrl because the Gitea API is served over HTTP(S); a non-standard
+ * web port cannot be inferred from an SSH URL — use an HTTPS remote or GITEA_BASE_URL.
+ */
+export declare function parseGitRemoteUrl(url: string, remote?: string): ParsedRemote | null;
+/** Extract every `[remote "<name>"]` url entry from a git config file's contents. */
+export declare function readGitRemotes(content: string): RawRemote[];
+/** Parse all remotes in a git config file's contents, dropping unparseable urls. */
+export declare function parseRemotes(content: string): ParsedRemote[];
+/** Pick the remote to derive values from: `upstream` first, then `origin`, then the first. */
+export declare function selectRemote(remotes: ParsedRemote[]): ParsedRemote | null;
+/**
+ * Read a Gitea token from a git config. A scoped `[gitea "<baseUrl>"] token = ...`
+ * section wins; a bare `[gitea] token = ...` is the fallback. Returns undefined
+ * when neither matches.
+ */
+export declare function readTokenFromGitConfig(content: string, baseUrl: string): string | undefined;
+/**
+ * Parse every credential-store line whose host matches. Each line is a URL of
+ * the form `protocol://[user[:pass]]@host[:port][/path]`; malformed and
+ * non-matching lines are skipped. Returns entries in file order; callers
+ * narrow and re-sort by repo path specificity.
+ *
+ * The `password` field — when present — holds whatever the user typed into
+ * git's password prompt: a real account password, a Personal Access Token,
+ * or an OAuth token. Git itself does not distinguish, and neither does this
+ * parser; the GiteaClient runtime tries each entry under multiple auth
+ * schemes to discover what works.
+ */
+export declare function parseGitCredentials(content: string, host: string): ParsedCredentialEntry[];
+/** Default credential-store paths: `$XDG_CONFIG_HOME/git/credentials` then `~/.git-credentials`. */
+export declare function defaultCredentialsPaths(): string[];
+/**
+ * Discover the Gitea connection config from env + the local git context.
+ *
+ * baseUrl: `GITEA_BASE_URL` (env) wins; otherwise derived from the selected
+ *   remote (`upstream` → `origin` → first). Returns null only when neither is
+ *   available — callers should treat that as "do not start the server".
+ *
+ * candidates (in priority order):
+ *   1. `[gitea "<baseUrl>"] token` / bare `[gitea] token` from `.git/config`
+ *      (explicit user configuration; `token` scheme only).
+ *   2. `GITEA_TOKEN` env var (explicit env; `token` scheme only — preserves
+ *      the simple-token semantics).
+ *   3. Every host-matching entry in a git credential store, narrowed by repo
+ *      path specificity (most specific first). Each entry may be a PAT,
+ *      password, or OAuth token; the client tries each under `basic` and/or
+ *      `token` schemes per the username heuristic.
+ *
+ * owner/repo: `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` (env) win; otherwise
+ * taken from the selected remote.
+ *
+ * The result may have an empty `candidates` array (anonymous mode); the server
+ * still starts and a Skill guides the user to provide one. Write tools will
+ * fail with 401/403 until a working credential is added.
+ */
+export declare function discoverConfig(options?: DiscoverOptions): Promise<CredentialDiscoveryResult | null>;

package/dist/git-config.js

@@ -0,0 +1,295 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { orderSchemesForCredentialStore, } from "./credentials.js";
+/**
+ * Parse a git remote URL into host/baseUrl/owner/repo. Accepts `ssh://`, the
+ * scp-like `user@host:owner/repo` form, and `http(s)://`. SSH URLs derive an
+ * `https://` baseUrl because the Gitea API is served over HTTP(S); a non-standard
+ * web port cannot be inferred from an SSH URL — use an HTTPS remote or GITEA_BASE_URL.
+ */
+export function parseGitRemoteUrl(url, remote = "origin") {
+    const u = url.trim();
+    let m = u.match(/^ssh:\/\/(?:[^@/\s]+@)?([^:/\s]+)(?::\d+)?\/([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+    if (m) {
+        const [, host, owner, repo] = m;
+        return { remote, url: u, host, baseUrl: `https://${host}`, owner, repo };
+    }
+    m = u.match(/^(https?:)\/\/(?:[^@/\s]+@)?([^:/\s]+)(?::(\d+))?\/([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+    if (m) {
+        const [, scheme, host, port, owner, repo] = m;
+        const baseUrl = port ? `${scheme}//${host}:${port}` : `${scheme}//${host}`;
+        return { remote, url: u, host: port ? `${host}:${port}` : host, baseUrl, owner, repo };
+    }
+    m = u.match(/^(?:[^@/\s]+@)?([^@:/\s]+):([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+    if (m) {
+        const [, host, owner, repo] = m;
+        return { remote, url: u, host, baseUrl: `https://${host}`, owner, repo };
+    }
+    return null;
+}
+/** Extract every `[remote "<name>"]` url entry from a git config file's contents. */
+export function readGitRemotes(content) {
+    const remotes = [];
+    let currentName = null;
+    for (const rawLine of content.split(/\r?\n/)) {
+        const section = rawLine.match(/^\s*\[remote\s+"([^"]+)"\]/);
+        if (section) {
+            currentName = section[1];
+            continue;
+        }
+        if (/^\s*\[[^\]]+\]/.test(rawLine)) {
+            currentName = null;
+            continue;
+        }
+        if (currentName !== null) {
+            const urlMatch = rawLine.match(/^\s*url\s*=\s*(.+?)\s*$/);
+            if (urlMatch) {
+                remotes.push({ name: currentName, url: urlMatch[1] });
+                currentName = null;
+            }
+        }
+    }
+    return remotes;
+}
+/** Parse all remotes in a git config file's contents, dropping unparseable urls. */
+export function parseRemotes(content) {
+    return readGitRemotes(content)
+        .map((r) => parseGitRemoteUrl(r.url, r.name))
+        .filter((r) => r !== null);
+}
+/** Pick the remote to derive values from: `upstream` first, then `origin`, then the first. */
+export function selectRemote(remotes) {
+    if (remotes.length === 0)
+        return null;
+    return (remotes.find((r) => r.remote === "upstream") ??
+        remotes.find((r) => r.remote === "origin") ??
+        remotes[0]);
+}
+/**
+ * Read a Gitea token from a git config. A scoped `[gitea "<baseUrl>"] token = ...`
+ * section wins; a bare `[gitea] token = ...` is the fallback. Returns undefined
+ * when neither matches.
+ */
+export function readTokenFromGitConfig(content, baseUrl) {
+    const escaped = baseUrl.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const scoped = content.match(new RegExp(`\\[gitea\\s+"${escaped}"\\]([\\s\\S]*?)(?=\\n\\s*\\[|$)`));
+    if (scoped) {
+        const t = scoped[1].match(/^\s*token\s*=\s*(.+?)\s*$/m);
+        if (t)
+            return t[1];
+    }
+    const globalSection = content.match(/(?:^|\n)\[gitea\][\t ]*([\s\S]*?)(?=\n\s*\[|$)/);
+    if (globalSection) {
+        const t = globalSection[1].match(/^\s*token\s*=\s*(.+?)\s*$/m);
+        if (t)
+            return t[1];
+    }
+    return undefined;
+}
+/**
+ * Parse every credential-store line whose host matches. Each line is a URL of
+ * the form `protocol://[user[:pass]]@host[:port][/path]`; malformed and
+ * non-matching lines are skipped. Returns entries in file order; callers
+ * narrow and re-sort by repo path specificity.
+ *
+ * The `password` field — when present — holds whatever the user typed into
+ * git's password prompt: a real account password, a Personal Access Token,
+ * or an OAuth token. Git itself does not distinguish, and neither does this
+ * parser; the GiteaClient runtime tries each entry under multiple auth
+ * schemes to discover what works.
+ */
+export function parseGitCredentials(content, host) {
+    const entries = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        try {
+            const credUrl = new URL(line);
+            if (credUrl.host !== host)
+                continue;
+            entries.push({
+                username: credUrl.username ? decodeURIComponent(credUrl.username) : undefined,
+                password: credUrl.password ? decodeURIComponent(credUrl.password) : undefined,
+                host: credUrl.host,
+                path: credUrl.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, ""),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * Score a credential entry's path specificity against the target repo path
+ * (`owner/repo`). Higher = more specific. Used to narrow multiple host
+ * matches toward the most relevant entry first.
+ *
+ * - Path is empty (host-only entry) → 0
+ * - Path is a prefix of the repo path → length of the matching path
+ * - Path does not match → -1 (deprioritized but still tried as a fallback)
+ */
+function scoreEntryPath(entryPath, repoPath) {
+    if (!entryPath)
+        return 0;
+    if (!repoPath)
+        return 0;
+    if (repoPath === entryPath || repoPath.startsWith(`${entryPath}/`)) {
+        return entryPath.length;
+    }
+    return -1;
+}
+/** Default credential-store paths: `$XDG_CONFIG_HOME/git/credentials` then `~/.git-credentials`. */
+export function defaultCredentialsPaths() {
+    const paths = [];
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg)
+        paths.push(join(xdg, "git", "credentials"));
+    paths.push(join(homedir(), ".git-credentials"));
+    return paths;
+}
+async function readOptionalFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return "";
+    }
+}
+/**
+ * Build a `CandidateCredential` from a parsed credential-store entry.
+ *
+ * - `https://:pass@host` or `https://user:pass@host` → secret = pass,
+ *   username preserved (basic auth needs it).
+ * - `https://tok@host` (username but no password) → secret = tok, no
+ *   username: this is git's "store the token as the username" convention.
+ *   Try `token` first (most common), fall back to `basic`.
+ */
+function candidateFromEntry(entry) {
+    if (entry.password) {
+        return {
+            source: "credential-store",
+            username: entry.username,
+            secret: entry.password,
+            schemes: orderSchemesForCredentialStore(entry.username),
+            status: "pending",
+            nextSchemeIndex: 0,
+        };
+    }
+    if (entry.username) {
+        return {
+            source: "credential-store",
+            secret: entry.username,
+            schemes: ["token", "basic"],
+            status: "pending",
+            nextSchemeIndex: 0,
+        };
+    }
+    return null;
+}
+/**
+ * Discover the Gitea connection config from env + the local git context.
+ *
+ * baseUrl: `GITEA_BASE_URL` (env) wins; otherwise derived from the selected
+ *   remote (`upstream` → `origin` → first). Returns null only when neither is
+ *   available — callers should treat that as "do not start the server".
+ *
+ * candidates (in priority order):
+ *   1. `[gitea "<baseUrl>"] token` / bare `[gitea] token` from `.git/config`
+ *      (explicit user configuration; `token` scheme only).
+ *   2. `GITEA_TOKEN` env var (explicit env; `token` scheme only — preserves
+ *      the simple-token semantics).
+ *   3. Every host-matching entry in a git credential store, narrowed by repo
+ *      path specificity (most specific first). Each entry may be a PAT,
+ *      password, or OAuth token; the client tries each under `basic` and/or
+ *      `token` schemes per the username heuristic.
+ *
+ * owner/repo: `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` (env) win; otherwise
+ * taken from the selected remote.
+ *
+ * The result may have an empty `candidates` array (anonymous mode); the server
+ * still starts and a Skill guides the user to provide one. Write tools will
+ * fail with 401/403 until a working credential is added.
+ */
+export async function discoverConfig(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const envBaseUrl = env.GITEA_BASE_URL;
+    const gitConfigContent = await readOptionalFile(join(cwd, ".git", "config"));
+    const parsedRemotes = parseRemotes(gitConfigContent);
+    const selected = selectRemote(parsedRemotes);
+    const baseUrl = envBaseUrl ?? selected?.baseUrl;
+    if (!baseUrl)
+        return null;
+    let host;
+    if (envBaseUrl) {
+        try {
+            host = new URL(envBaseUrl).host;
+        }
+        catch {
+            host = undefined;
+        }
+    }
+    else {
+        host = selected?.host;
+    }
+    const candidates = [];
+    // Source 1: .git/config [gitea "<baseUrl>"] token / bare [gitea] token.
+    if (host) {
+        const configToken = readTokenFromGitConfig(gitConfigContent, baseUrl);
+        if (configToken) {
+            candidates.push({
+                source: "gitea-config",
+                secret: configToken,
+                schemes: ["token"],
+                status: "pending",
+                nextSchemeIndex: 0,
+            });
+        }
+    }
+    // Source 2: GITEA_TOKEN env (simple-token semantics — no scheme probing).
+    const envToken = env.GITEA_TOKEN;
+    if (envToken) {
+        candidates.push({
+            source: "env",
+            secret: envToken,
+            schemes: ["token"],
+            status: "pending",
+            nextSchemeIndex: 0,
+        });
+    }
+    // Source 3..N: credential-store entries, host-matched and path-narrowed.
+    if (host) {
+        const paths = options.credentialsPaths ?? defaultCredentialsPaths();
+        const repoPath = selected ? `${selected.owner}/${selected.repo}` : "";
+        const scored = [];
+        let order = 0;
+        for (const path of paths) {
+            const cred = await readOptionalFile(path);
+            if (!cred)
+                continue;
+            for (const entry of parseGitCredentials(cred, host)) {
+                scored.push({ entry, score: scoreEntryPath(entry.path, repoPath), order: order++ });
+            }
+        }
+        // Sort by score desc; stable within same score (preserve file/discovery order).
+        scored.sort((a, b) => b.score - a.score || a.order - b.order);
+        for (const { entry } of scored) {
+            const candidate = candidateFromEntry(entry);
+            if (candidate)
+                candidates.push(candidate);
+        }
+    }
+    return {
+        baseUrl,
+        defaultOwner: env.GITEA_DEFAULT_OWNER ?? selected?.owner,
+        defaultRepo: env.GITEA_DEFAULT_REPO ?? selected?.repo,
+        remote: selected?.remote,
+        candidates,
+    };
+}
+//# sourceMappingURL=git-config.js.map

package/dist/git-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-config.js","sourceRoot":"","sources":["../src/git-config.ts"],"names":[],"mappings":"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"}

package/dist/gitea-client.d.ts

@@ -1,6 +1,29 @@
+import { type CandidateCredential, type CandidateSummary } from "./credentials.js";
 export interface GiteaConfig {
     baseUrl: string;
-    token: string;
+    /**
+     * Legacy single-token mode. When `candidates` is omitted, this is wrapped
+     * as a one-element candidate list with the `token` scheme (preserving the
+     * pre-multi-credential behavior exactly).
+     */
+    token?: string;
+    /**
+     * Credential candidates in priority order. When provided, enables the
+     * fault-tolerant auth state machine: each candidate × scheme is tried in
+     * order until one succeeds, with 401/403 advancing to the next attempt.
+     */
+    candidates?: CandidateCredential[];
+}
+/**
+ * HTTP error from the Gitea API. Carries `status` as a structured field so
+ * callers (the retry loop, tests) can branch on it without parsing the
+ * message string (AGENTS.md §2.3 forbids substring-based control flow).
+ */
+export declare class GiteaApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
 }
 export interface Issue {
     id: number;
@@ -140,8 +163,38 @@ export interface UpdateMilestoneParams {
 }
 export declare class GiteaClient {
     private baseUrl;
-    private token;
+    private candidates;
     constructor(config: GiteaConfig);
+    /**
+     * Snapshot of the credential state machine — for the `gitea_status` tool.
+     * Secrets are never included; only `secretPresent: boolean` and a masked
+     * `username`. See `summarizeCandidates` in `credentials.ts`.
+     */
+    getCredentialStatus(): {
+        candidates: CandidateSummary[];
+        activeIndex: number | null;
+        totalCandidates: number;
+    };
+    /**
+     * Single HTTP call. Throws `GiteaApiError` on non-2xx so the retry loop can
+     * branch on `status` (never on the message string). The `authHeader` is
+     * pre-built by the caller from the active candidate + scheme.
+     */
+    private doRequest;
+    /**
+     * Auth-aware request entry point. Three modes:
+     *
+     * 1. Active candidate exists (a prior attempt succeeded): reuse its locked
+     *    scheme directly, no iteration.
+     * 2. No candidates at all: anonymous request (no Authorization header).
+     * 3. Otherwise: iterate (candidate, scheme) pairs in priority order, trying
+     *    each until one succeeds. On 401/403 the current attempt is marked
+     *    failed and the next is tried; non-auth errors propagate immediately
+     *    (we do NOT mask 5xx / network errors as auth failures). When every
+     *    candidate × scheme is exhausted, the most recent `GiteaApiError` is
+     *    re-thrown so the caller sees the underlying status/body; the
+     *    `gitea_status` tool surfaces the full attempt history.
+     */
     private request;
     listIssues(params: ListIssuesParams): Promise<Issue[]>;
     getIssue(owner: string, repo: string, index: number): Promise<Issue>;