@amonstack/gitea-mcp 0.2.2 → 0.3.1

package/README.md

@@ -52,13 +52,77 @@ node dist/cli.js
 
 ## Configuration
 
+All variables are optional — `gitea-mcp` auto-discovers the Gitea instance, repository,
+and token from the project's local git config so a single global install can serve many
+projects. Set them only to override the discovery.
+
 | Variable | Required | Description |
 |----------|:--------:|-------------|
-| `GITEA_BASE_URL` | Yes | Gitea instance URL (e.g. `https://gitea.example.com`) |
-| `GITEA_TOKEN` | Yes | Gitea API access token |
+| `GITEA_BASE_URL` | No | Gitea instance URL (e.g. `https://gitea.example.com`). Auto-detected from the project's git remote when omitted. |
+| `GITEA_TOKEN` | No | Gitea API access token. One of several auth candidates; tried after a `.git/config [gitea]` token and before the git credential store (see [Token discovery](#token-discovery)). |
 | `GITEA_DEFAULT_OWNER` | No | Default repository owner — skip passing `owner` on every call |
 | `GITEA_DEFAULT_REPO` | No | Default repository name — skip passing `repo` on every call |
 
+### How auto-discovery works
+
+On start, `gitea-mcp` reads `<cwd>/.git/config` and derives:
+
+- **Instance URL** — from the selected remote's host. SSH remotes (`git@host:owner/repo`)
+  resolve to `https://host`. Override with `GITEA_BASE_URL`.
+- **owner / repo** — from the selected remote's URL. Override with `GITEA_DEFAULT_OWNER` /
+  `GITEA_DEFAULT_REPO`, or detect ad hoc with the `resolve_repo` tool.
+- **Remote selection** — the `upstream` remote is preferred, falling back to `origin`, then
+  any other remote. Both are reported by `resolve_repo` when they differ.
+
+If the current directory has no git remote and `GITEA_BASE_URL` is not set, the server does
+**not** start — it prints a skip reason and exits 0. Run it from inside a cloned Gitea
+repository, or set `GITEA_BASE_URL` / `GITEA_TOKEN` explicitly.
+
+### Token discovery
+
+`gitea-mcp` collects authentication **candidates** from three sources, in this
+priority order:
+
+1. A `[gitea "<baseUrl>"]` section in `.git/config` (a bare `[gitea]` section is
+   a host-wide fallback):
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   Always sent as `Authorization: token <token>`.
+2. The `GITEA_TOKEN` environment variable — also sent as `Authorization: token`.
+3. The git credential store (`~/.git-credentials`, or
+   `$XDG_CONFIG_HOME/git/credentials`) — every line whose host matches the
+   instance, e.g. `https://alice:s3cret@gitea.example.com`. When several lines
+   match, the one whose path best matches `owner/repo` is tried first.
+
+A credential-store entry's `password` field may hold a real PAT, an account
+password, or an OAuth token — git stores whatever was typed at the prompt, and
+the server cannot tell them apart statically. So each credential-store entry is
+tried under **two authentication schemes**:
+
+- `Authorization: Basic <base64(user:pass)>` — works for account passwords and
+  PATs alike (Gitea checks that the username matches the secret's owner).
+- `Authorization: token <secret>` — works only for real PATs.
+
+The order is chosen by a username heuristic: a convention username
+(`oauth2`, `x-oauth-basic`, or empty) tries `token` first; a real-looking
+username (e.g. `alice`) tries `basic` first.
+
+**Fault tolerance.** On `401`/`403` the server advances to the next
+scheme/candidate and retries the same request; once a combination succeeds it is
+locked for the rest of the session (no re-probing). Non-auth errors (`404`,
+`500`, network) propagate immediately and do **not** trigger a retry.
+
+**Diagnostics.** The `gitea_status` tool (see [Repository Helpers](#repository-helpers))
+returns a redacted view of the current state — which candidate is active, which
+are exhausted, the last status seen — without ever exposing the secret. Use it
+to troubleshoot a `401` instead of guessing.
+
+If no source resolves a credential, the server still starts anonymously. Public
+repositories may be read; private repos and write operations return `401` — use
+the `gitea-configure` skill to guide setup, or set `GITEA_TOKEN`.
+
 When `GITEA_DEFAULT_OWNER` and `GITEA_DEFAULT_REPO` are set, you can omit the
 `owner` and `repo` parameters in tool calls. The `resolve_repo` tool can also
 auto-detect them from a local git repository.
@@ -131,7 +195,14 @@ directory; use `--dir` for an exact location. Then restart your tool. See
 ### Other MCP Clients
 
 Any client that supports stdio-based MCP servers can use `gitea-mcp`. After
-installation, set the required environment variables and run:
+installation, run it from inside a cloned Gitea repository (config is auto-discovered):
+
+```bash
+cd /path/to/your/gitea-repo
+gitea-mcp
+```
+
+Or set the variables explicitly if you prefer:
 
 ```bash
 export GITEA_BASE_URL="https://gitea.example.com"
@@ -189,7 +260,8 @@ gitea-mcp
 | Tool | Description |
 |------|-------------|
 | `list_my_repos` | List repositories accessible to the authenticated user |
-| `resolve_repo` | Auto-detect `owner` and `repo` from a local git remote URL |
+| `resolve_repo` | Detect `baseUrl`, `owner`, and `repo` from the project's git remotes (`upstream` preferred, then `origin`) |
+| `gitea_status` | Inspect credential-handling state — active candidate, exhausted candidates, last error (redacted; secrets never exposed) |
 
 ## AI Guidance & Skills
 
@@ -222,6 +294,7 @@ say, delete instructions while creating). Install them with the
 | `gitea-summarize-issue` | reading and summarizing an issue's discussion |
 | `gitea-plan-milestones` | creating / editing / closing milestones |
 | `gitea-resolve-repo` | resolving owner/repo or listing repositories |
+| `gitea-configure` | fixing the connection — instance URL, token, or 401/403 errors |
 
 Each skill is a short, AI-facing action flow (purpose, when to use, when not to,
 rules, and what to check first). The create, comment, and milestone skills also
@@ -245,6 +318,7 @@ npm ci
 | `make test` | Run unit tests |
 | `make test-watch` | Run tests in watch mode |
 | `make test-integration` | Run integration tests (needs live Gitea instance) |
+| `make scan` | Scan for leaked secrets with gitleaks (part of `make verify`) |
 | `make dev` | Run directly with tsx |
 
 For the full architecture — module layout, dependency graph, core patterns, and

package/README.zh-CN.md

@@ -50,13 +50,67 @@ node dist/cli.js
 
 ## 配置
 
+所有变量都是可选的——`gitea-mcp` 会从项目本地 git 配置自动发现 Gitea 实例、仓库和令牌，
+因此一次全局安装即可服务多个项目。仅在需要覆盖自动发现结果时才设置它们。
+
 | 变量 | 必填 | 说明 |
 |------|:----:|------|
-| `GITEA_BASE_URL` | 是 | Gitea 实例地址（如 `https://gitea.example.com`） |
-| `GITEA_TOKEN` | 是 | Gitea API 访问令牌 |
+| `GITEA_BASE_URL` | 否 | Gitea 实例地址（如 `https://gitea.example.com`）。未设置时从项目 git 远程地址自动推导。 |
+| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。是多个认证候选之一；排在 `.git/config [gitea]` 令牌之后、git 凭据存储之前（见[令牌发现](#令牌发现)）。 |
 | `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者，免去每次传入 `owner` 参数 |
 | `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称，免去每次传入 `repo` 参数 |
 
+### 自动发现的工作方式
+
+启动时，`gitea-mcp` 读取 `<cwd>/.git/config` 并推导：
+
+- **实例地址** —— 取自选中远程地址的 host。SSH 远程（`git@host:owner/repo`）会被推导为
+  `https://host`。可用 `GITEA_BASE_URL` 覆盖。
+- **owner / repo** —— 取自选中远程地址。可用 `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO`
+  覆盖，或随时用 `resolve_repo` 工具检测。
+- **远程选择** —— 优先 `upstream`，回退 `origin`，再回退其它远程。两者不同时 `resolve_repo`
+  会同时返回。
+
+若当前目录没有 git 远程、且未设置 `GITEA_BASE_URL`，服务器**不会启动**——它会打印跳过原因并
+以 exit 0 退出。请在克隆的 Gitea 仓库内运行，或显式设置 `GITEA_BASE_URL` / `GITEA_TOKEN`。
+
+### 令牌发现
+
+`gitea-mcp` 从三个来源收集认证**候选**，按以下优先级排序：
+
+1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段（不带地址的 `[gitea]` 段作为全局兜底）：
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   始终以 `Authorization: token <token>` 发送。
+2. `GITEA_TOKEN` 环境变量 —— 同样以 `Authorization: token` 发送。
+3. git 凭据存储（`~/.git-credentials`，或 `$XDG_CONFIG_HOME/git/credentials`）—— host 匹配实例
+   的每一行，如 `https://alice:s3cret@gitea.example.com`。多行同时匹配时，path 与 `owner/repo`
+   最贴近的那一行优先尝试。
+
+凭据存储条目的 `password` 字段可能是真正的 PAT、账户登录密码，或 OAuth token —— git 存的是
+用户在密码提示里输入的任何内容，服务端无法静态区分。因此每个凭据存储条目会以**两种认证方案**
+依次尝试：
+
+- `Authorization: Basic <base64(user:pass)>` —— 账户密码和 PAT 都能通过（Gitea 会校验用户名与
+  密钥属主一致）。
+- `Authorization: token <secret>` —— 仅对真正的 PAT 有效。
+
+尝试顺序由用户名启发式决定：约定用户名（`oauth2`、`x-oauth-basic`、空）先试 `token`；真实用户名
+（如 `alice`）先试 `basic`。
+
+**容错。** 遇到 `401`/`403`，服务端会切换到下一个方案/候选并重试同一请求；一旦某组凭据成功，
+它会被锁定到本会话结束（不再重复探测）。非认证类错误（`404`、`500`、网络错误）立即向上抛出，
+**不会**触发重试。
+
+**诊断。** `gitea_status` 工具（见[仓库辅助](#仓库辅助-repository-helpers)）返回当前状态的脱敏
+视图 —— 哪个候选处于 active、哪些已耗尽、最近一次的状态码 —— 永不暴露密钥本身。排查 `401` 时
+用它代替盲猜。
+
+若所有来源都未解析到凭据，服务器仍会以匿名方式启动。公开仓库可读；私有仓库和写操作返回
+`401` —— 此时使用 `gitea-configure` 技能引导配置，或设置 `GITEA_TOKEN`。
+
 设置 `GITEA_DEFAULT_OWNER` 和 `GITEA_DEFAULT_REPO` 后，调用工具时可以省略
 `owner` 和 `repo` 参数。也可以使用 `resolve_repo` 工具自动从本地 git 仓库
 检测这两个值。
@@ -126,8 +180,15 @@ gitea-mcp init --dir /exact/path    # 自定义路径
 
 ### 其他 MCP 客户端
 
-任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后设置环境
-变量并启动：
+ 任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后，在克隆的 Gitea 仓库内
+ 吏动即可（配置会自动发现）：
+
+```bash
+cd /path/to/your/gitea-repo
+gitea-mcp
+```
+
+也可显式设置环境变量：
 
 ```bash
 export GITEA_BASE_URL="https://gitea.example.com"
@@ -185,7 +246,8 @@ gitea-mcp
 | 工具 | 说明 |
 |------|------|
 | `list_my_repos` | 列出当前用户可访问的仓库 |
-| `resolve_repo` | 从本地 git 仓库的远程地址自动检测 `owner` 和 `repo` |
+| `resolve_repo` | 从项目 git 远程地址检测 `baseUrl`、`owner`、`repo`（优先 `upstream`，回退 `origin`） |
+| `gitea_status` | 查看认证处理状态 —— active 候选、已耗尽候选、最近一次错误（脱敏；永不暴露密钥） |
 
 ## AI 引导与技能
 
@@ -216,6 +278,7 @@ gitea-mcp
 | `gitea-summarize-issue` | 读取并总结某 issue 的讨论 |
 | `gitea-plan-milestones` | 创建 / 编辑 / 关闭里程碑 |
 | `gitea-resolve-repo` | 解析 owner/repo 或列出仓库 |
+| `gitea-configure` | 修复连接——实例地址、令牌或 401/403 报错 |
 
 每个技能都是面向 AI 的简短动作流程（目的、何时用、何时不用、规则、先检查什么）。
 创建、评论、里程碑三类技能还内嵌**正文模板**（bug / 新功能 / 性能 issue、评论、
@@ -237,6 +300,7 @@ npm ci
 | `make test` | 运行单元测试 |
 | `make test-watch` | 监听模式运行测试 |
 | `make test-integration` | 运行集成测试（需要可用的 Gitea 实例） |
+| `make scan` | 用 gitleaks 扫描泄露的密钥（属于 `make verify`） |
 | `make dev` | 通过 tsx 直接运行 |
 
 完整的架构说明（模块布局、依赖关系、核心模式，以及新增工具的指引）请参阅

package/dist/assets/instructions.md

@@ -4,18 +4,29 @@ You manage Gitea issues, comments, labels, and milestones through this MCP serve
 Every tool returns Gitea's JSON verbatim as text. Follow these rules to use them
 correctly.
 
+## Config is auto-discovered from git (env vars optional)
+
+On start the server reads `<cwd>/.git/config` and derives `baseUrl`, `owner`, `repo`,
+and `token` so one global install can serve many projects. The `GITEA_BASE_URL` /
+`GITEA_TOKEN` / `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars are OPTIONAL
+overrides; when set they take precedence over git discovery. The remote is chosen
+`upstream` first, then `origin`. If the cwd has no git remote and `GITEA_BASE_URL` is
+unset, the server does not start (it prints a skip reason and exits 0). If you hit a
+401/403 or the connection looks unset, use the **gitea-configure** skill.
+
 ## Resolve owner/repo FIRST (most common failure)
 
 Most tools target one repository and need both `owner` and `repo`. They resolve in
 this order:
 
 1. The `owner` / `repo` arguments you pass to the call.
-2. `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars (set at server start).
-3. The `resolve_repo` tool (detects owner/repo from a local git remote).
+2. `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars (or the git-discovered defaults
+   captured at server start).
+3. The `resolve_repo` tool (re-reads `.git/config` and returns `baseUrl`, `owner`, `repo`,
+   the selected `remote`, and every parsed remote under `remotes`).
 
-If neither argument nor env var is set, the call errors. Before a batch of work on a
-repo you have not used this session, call `resolve_repo` (or confirm the env defaults)
-once and reuse the result — do not guess.
+If none resolve, the call errors. Before a batch of work on a repo you have not used this
+session, call `resolve_repo` once and reuse the result — do not guess.
 
 ## Labels: IDs vs names (critical gotcha)
 
@@ -59,5 +70,6 @@ Confirm the target id/index and scope with the user before calling. For labels,
 ## Error format
 
 Failed calls throw `Gitea API error (<status>): <body>`. Read the status: 401/403 →
-token scope/expiry; 404 → wrong owner/repo or no permission; 409 → conflict;
-422 → validation. Do not retry blindly on 4xx.
+token missing, wrong, or lacks scope — run the **gitea-configure** skill to fix the
+connection; 404 → wrong owner/repo or no permission; 409 → conflict; 422 → validation.
+Do not retry blindly on 4xx.

package/dist/assets/skills/gitea-configure/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gitea-configure
+description: Invoke to CONFIGURE / SET UP / FIX the Gitea connection — instance URL, token, or owner/repo discovery. Use when a tool fails with 401/403 (bad or missing token), when the user asks how to wire up gitea-mcp, or when baseUrl/owner/repo could not be auto-detected. Do NOT invoke for normal issue/label/milestone work once the connection works.
+---
+
+# gitea-configure
+
+Diagnose and fix the Gitea connection. The server auto-discovers its config from the
+project's git remotes; this skill is the fallback when that fails or the token is wrong.
+
+## How gitea-mcp discovers config (no env vars required)
+
+On start, the server reads `<cwd>/.git/config` and resolves in this order:
+
+1. **baseUrl** — `GITEA_BASE_URL` env var, else derived from the selected remote's host.
+   SSH remotes (`git@host:owner/repo`) resolve to `https://host`.
+2. **owner / repo** — `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars, else from the
+   selected remote's URL.
+3. **Remote selection** — `upstream` remote first, falling back to `origin`, then any
+   other remote. Both are surfaced in `resolve_repo` output.
+
+If the working directory has NO git remote and `GITEA_BASE_URL` is unset, the server does
+NOT start (it prints a skip reason and exits 0). That is intentional, not a crash.
+
+## Token discovery chain (tried in order)
+
+1. `.git/config` — a `[gitea "<baseUrl>"]` section, e.g.
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   A bare `[gitea]` section with `token = ...` is a host-wide fallback.
+2. The git credential store (`~/.git-credentials`, or `$XDG_CONFIG_HOME/git/credentials`)
+   — a line whose host matches the instance, e.g.
+   `https://oauth2:<token>@gitea.example.com`.
+3. `GITEA_TOKEN` env var.
+4. If none of the above yield a token, the server starts WITHOUT a token (anonymous). Public
+   repos may be read; writes and private repos return 401 — that is the signal to help the
+   user add a token via one of the sources above.
+
+## Fix flow — when a tool returns 401 / 403
+
+1. Confirm the instance: run `resolve_repo` (no args) and read its `baseUrl` and `remote`.
+   If it throws, the cwd has no usable git remote — tell the user to run gitea-mcp from a
+   cloned repo, or set `GITEA_BASE_URL` + `GITEA_TOKEN`.
+2. Ask the user to create a token at `<baseUrl>/user/settings/applications` (Gitea → Settings
+   → Applications → Access Tokens). Capture the scopes they need: `issue`, `comment`,
+   `label`, `milestone` (read+write). NEVER have the user paste a token into chat unless they
+   explicitly choose to — prefer having them run a git command themselves.
+3. Have the user store it so discovery finds it. Recommend, in priority order:
+   - `git config --file=.git/config gitea."<baseUrl>".token "<token>"` (project-scoped), or
+   - add to the credential store, or
+   - export `GITEA_TOKEN` (and `GITEA_BASE_URL`) in their MCP client config.
+   `<baseUrl>` is the EXACT value `resolve_repo` reported (scheme + host, with port if any).
+4. The server must be restarted for new config to take effect — discovery runs once at start.
+
+## Never log the token
+
+Tokens are secret. Do not echo, paste into notes, or include in issue/comment bodies. Pass
+configuration values to the user as commands to run themselves; never print a token back.

package/dist/assets/skills/gitea-resolve-repo/SKILL.md

@@ -1,18 +1,29 @@
 ---
 name: gitea-resolve-repo
-description: Invoke to RESOLVE which owner/repo the other gitea tools should target (auto-detect from a git remote) or to LIST repositories the token can access. Run FIRST when the target repository is unknown. Do NOT invoke for issue/comment/label/milestone work once owner/repo are known.
+description: Invoke to RESOLVE which owner/repo (and baseUrl) the other gitea tools should target (auto-detect from a git remote) or to LIST repositories the token can access. Run FIRST when the target repository is unknown. Do NOT invoke for issue/comment/label/milestone work once owner/repo are known.
 ---
 
 # gitea-resolve-repo
 
-Discover the target repository. Tools: `resolve_repo`, `list_my_repos`.
+Discover the target repository and instance. Tools: `resolve_repo`, `list_my_repos`.
 
 ## resolve_repo
-- Reads the `origin` remote of the git repo at `path` (default: current directory) and parses owner/repo from SSH (`git@gitea.example:owner/repo.git`) or HTTPS (`https://gitea.example/owner/repo.git`) URLs.
-- Throws if there is no `origin` remote or the URL is unparseable. Do NOT guess owner/repo from context — call this, or ask the user.
+- Reads `.git/config` of the git repo at `path` (default: current directory) and parses
+  EVERY remote from SSH (`git@gitea.example:owner/repo.git`) or HTTPS
+  (`https://gitea.example/owner/repo.git`) URLs.
+- Selects the remote to target in this priority: `upstream` → `origin` → any other.
+  SSH remotes resolve to `baseUrl = https://<host>` (the API is assumed HTTPS).
+- Returns `{ baseUrl, owner, repo, remote, remote_url, remotes: { <name>: {baseUrl, owner, repo, url} } }`.
+  Read `baseUrl` to know which instance a token must be valid for; read `remotes` to see
+  upstream vs origin when they differ.
+- Throws `No parseable git remotes found` if the cwd has no git remote or none parse. Do
+  NOT guess owner/repo from context — call this, or ask the user.
 
 ## list_my_repos
-- Lists repositories the token can access. GLOBAL. Returns large objects — paginate (`limit` ≤ 100) and read only the fields you need (name, full_name, owner.login).
+- Lists repositories the token can access. GLOBAL. Returns large objects — paginate (`limit` ≤ 100) and read only the fields you need (name, full_name, owner.login). If this returns
+  401/403 there is no usable token — switch to the **gitea-configure** skill.
 
 ## Resolution order (every repo-scoped tool)
-explicit `owner`/`repo` args → `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` → `resolve_repo`. If none resolve, the tool throws `owner and repo are required`. Wrong values 404 or silently target the wrong repo — never guess.
+explicit `owner`/`repo` args → `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` (or git-discovered
+defaults) → `resolve_repo`. If none resolve, the tool throws `owner and repo are required`.
+Wrong values 404 or silently target the wrong repo — never guess.

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { runServer } from "./server.js";
+import { discoverConfig } from "./git-config.js";
 const argv = process.argv.slice(2);
 if (argv[0] === "init") {
     // `gitea-mcp init [--tool <name>]` installs the bundled skills into a target
     // AI tool's skills directory. It needs no Gitea credentials, so it is
-    // dispatched before the env-var guard below.
+    // dispatched before the config-discovery logic below.
     const { runInitCommand } = await import("./skills.js");
     runInitCommand(argv.slice(1)).catch((err) => {
         console.error("Fatal error:", err);
@@ -12,15 +13,23 @@ if (argv[0] === "init") {
     });
 }
 else {
-    const baseUrl = process.env.GITEA_BASE_URL;
-    const token = process.env.GITEA_TOKEN;
-    const defaultOwner = process.env.GITEA_DEFAULT_OWNER;
-    const defaultRepo = process.env.GITEA_DEFAULT_REPO;
-    if (!baseUrl || !token) {
-        console.error("GITEA_BASE_URL and GITEA_TOKEN environment variables are required");
+    // Resolve baseUrl/owner/repo/credentials from env first, then the local git
+    // context (`.git/config` remotes + credential store). Discovery collects ALL
+    // credential candidates (config token, env token, credential-store entries)
+    // rather than picking one, so the client can fall back across them when one
+    // scheme is rejected (e.g. an account password that is not a PAT). When
+    // neither env nor any git remote provides a baseUrl, the server is
+    // intentionally skipped: a single global install should stay dormant outside
+    // of git projects.
+    const discovered = await discoverConfig().catch((err) => {
+        console.error("Fatal error:", err);
         process.exit(1);
+    });
+    if (!discovered) {
+        console.error(`gitea-mcp: no git remote found in ${process.cwd()} and GITEA_BASE_URL is not set; skipping server start.`);
+        process.exit(0);
     }
-    runServer(baseUrl, token, defaultOwner, defaultRepo).catch((err) => {
+    runServer(discovered.baseUrl, discovered.candidates, discovered.defaultOwner, discovered.defaultRepo).catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
     });

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,sEAAsE;IACtE,6CAA6C;IAC7C,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAEnD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC1E,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,wEAAwE;IACxE,mEAAmE;IACnE,6EAA6E;IAC7E,mBAAmB;IACnB,MAAM,UAAU,GAAG,MAAM,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC/D,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACX,qCAAqC,OAAO,CAAC,GAAG,EAAE,wDAAwD,CAC3G,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CACP,UAAU,CAAC,OAAO,EAClB,UAAU,CAAC,UAAU,EACrB,UAAU,CAAC,YAAY,EACvB,UAAU,CAAC,WAAW,CACvB,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/credentials.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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`.
+ */
+/** Where a candidate came from. Determines scheme ordering and priority. */
+export type CredentialSource = "gitea-config" | "env" | "credential-store";
+/**
+ * HTTP auth scheme. Both are sent via the `Authorization` header.
+ * - `token` → `Authorization: token <PAT>` (Gitea's PAT/OAuth-token scheme)
+ * - `basic` → `Authorization: Basic base64(<username>:<secret>)` (works for
+ *   both account passwords and PATs when the username matches the owner)
+ */
+export type AuthScheme = "token" | "basic";
+/**
+ * A single candidate credential with its runtime state. The state fields
+ * (`status`, `nextSchemeIndex`, `lastTriedScheme`, `lastError`,
+ * `activeScheme`) are mutated by the GiteaClient as requests succeed or fail.
+ */
+export interface CandidateCredential {
+    source: CredentialSource;
+    /** Username from a credential-store URL. Undefined for config/env sources. */
+    username?: string;
+    /** The secret value (PAT, password, or OAuth token). Never logged. */
+    secret: string;
+    /**
+     * Ordered list of auth schemes to try for this candidate. The first scheme
+     * that succeeds is locked in via `activeScheme` and reused for subsequent
+     * requests without re-iterating.
+     */
+    schemes: AuthScheme[];
+    /** Runtime state: pending (untried), active (verified working), exhausted. */
+    status: "pending" | "active" | "exhausted";
+    /** Index into `schemes` for the next untried scheme. */
+    nextSchemeIndex: number;
+    /** The scheme that last produced an HTTP error (for diagnostics). */
+    lastTriedScheme?: AuthScheme;
+    /**
+     * The scheme that succeeded and is in active use. Set when status becomes
+     * "active"; subsequent requests reuse it without re-iterating.
+     */
+    activeScheme?: AuthScheme;
+    /**
+     * Short error reason from the last failed attempt (e.g. "401"). Never
+     * contains the secret or the response body.
+     */
+    lastError?: string;
+}
+/** Result of credential discovery — feeds straight into GiteaClient. */
+export interface CredentialDiscoveryResult {
+    baseUrl: string;
+    defaultOwner?: string;
+    defaultRepo?: string;
+    /** Name of the remote the values were derived from. */
+    remote?: string;
+    /** Candidates in priority order (highest priority first). */
+    candidates: CandidateCredential[];
+}
+/** A picked next attempt — the candidate index plus the scheme to apply. */
+export interface Attempt {
+    candidateIndex: number;
+    scheme: AuthScheme;
+}
+/**
+ * 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 declare function orderSchemesForCredentialStore(username?: string): AuthScheme[];
+/**
+ * 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 declare function buildAuthHeader(candidate: CandidateCredential, scheme: AuthScheme): string;
+/**
+ * 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 declare function pickNextAttempt(candidates: CandidateCredential[]): Attempt | 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 declare function markAttemptFailed(candidates: CandidateCredential[], candidateIndex: number, error: string): void;
+/**
+ * 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 declare function markAttemptSucceeded(candidates: CandidateCredential[], candidateIndex: number, scheme: AuthScheme): void;
+/**
+ * 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 declare function maskUsername(username?: string): string | null;
+/**
+ * Build a redacted summary of all candidates for the `gitea_status` tool.
+ * The `secret` value is never included — only `secretPresent: true`. The
+ * caller passes the active candidate index (or null) so the summary can flag
+ * which candidate is currently in use.
+ */
+export interface CandidateSummary {
+    source: CredentialSource;
+    schemes: AuthScheme[];
+    username: string | null;
+    secretPresent: boolean;
+    status: "pending" | "active" | "exhausted";
+    lastTriedScheme: AuthScheme | null;
+    activeScheme: AuthScheme | null;
+    lastError: string | null;
+}
+export declare function summarizeCandidates(candidates: CandidateCredential[]): CandidateSummary[];
+/** Find the index of the active candidate, or null when none is active. */
+export declare function findActiveCandidateIndex(candidates: CandidateCredential[]): number | null;