@amonstack/gitea-mcp 0.3.0 → 0.3.2

package/README.md

@@ -1,20 +1,50 @@
-# gitea-mcp
+<p align="center">
+  <img alt="gitea-mcp" src="https://raw.githubusercontent.com/amonstack/gitea_mcp/master/docs/assets/gitea-mcp-banner.png" />
+  <h3 align="center">gitea-mcp</h3>
+  <p align="center">MCP server that exposes Gitea issues, labels, milestones, and comments as tools for AI assistants</p>
+</p>
 
-[中文文档](https://github.com/amonstack/gitea_mcp/blob/master/README.zh-CN.md)
+---
 
-> MCP server that lets AI assistants manage Gitea repositories — issues, labels,
-> milestones, comments, and more via the Gitea API.
+[![npm version](https://img.shields.io/npm/v/@amonstack/gitea-mcp?logo=npm)](https://www.npmjs.com/package/@amonstack/gitea-mcp)
+[![codecov](https://codecov.io/gh/amonstack/gitea_mcp/branch/master/graph/badge.svg)](https://codecov.io/gh/amonstack/gitea_mcp)
+[![license](https://img.shields.io/npm/l/@amonstack/gitea-mcp)](https://github.com/amonstack/gitea_mcp/blob/master/LICENSE)
+[![Node](https://img.shields.io/node/v/@amonstack/gitea-mcp?logo=node.js)](https://www.npmjs.com/package/@amonstack/gitea-mcp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![MCP](https://img.shields.io/badge/MCP-server-6f42c1?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
 
-## What is gitea-mcp?
+**English** | [中文文档](https://github.com/amonstack/gitea_mcp/blob/master/README.zh-CN.md)
 
-`gitea-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
-server that exposes Gitea repository operations as tools. Once connected to an
-MCP client (Claude Desktop, opencode, Cursor, etc.), an AI assistant can list,
-create, update, and delete issues, labels, milestones, and comments on your
-Gitea instance — all through natural language.
+`gitea-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes Gitea repository operations as tools. Once connected to an MCP client (Claude Desktop, opencode, Cursor, etc.), an AI assistant can list, create, update, and delete issues, labels, milestones, and comments on your Gitea instance — all through natural language.
 
-The server communicates over stdio and wraps the [Gitea REST API
-(`/api/v1`)](https://docs.gitea.com/api/1.22/).
+The server communicates over stdio and wraps the [Gitea REST API (`/api/v1`)](https://docs.gitea.com/api/1.22/).
+
+## Features
+
+- **Full Gitea project management** — issues, labels, milestones, and comments via natural language
+- **Zero-config auto-discovery** — reads `baseUrl`, `owner`, `repo`, and token from the project's git config; one global install serves many repos
+- **Multi-source auth with failover** — tries `[gitea]` config tokens, `GITEA_TOKEN`, then the git credential store, advancing automatically on `401`/`403`
+- **Action-scoped skills** — ships one skill per workflow (find, create, label, comment, plan milestones, …) for opencode, Claude Code, Cursor, and more
+- **Client-agnostic** — works with any stdio-based MCP client; ships guidance prompts and on-demand reference resources too
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [MCP Client Setup](#mcp-client-setup)
+- [Available Tools](#available-tools)
+- [AI Guidance & Skills](#ai-guidance--skills)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Requirements
+
+- **Node.js ≥ 18** — uses the global `fetch`
+- A **Gitea instance** (self-hosted or Gitea Cloud) reachable over HTTP
+- A **Gitea API token** (or a git credential-store entry) for anything beyond reading public repositories
 
 ## Installation
 
@@ -59,7 +89,7 @@ projects. Set them only to override the discovery.
 | Variable | Required | Description |
 |----------|:--------:|-------------|
 | `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. Resolved from `.git/config`, the git credential store, then this variable (see [Token discovery](#token-discovery)). |
+| `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 |
 
@@ -80,21 +110,48 @@ repository, or set `GITEA_BASE_URL` / `GITEA_TOKEN` explicitly.
 
 ### Token discovery
 
-The token is resolved in this order (first match wins):
+`gitea-mcp` collects authentication **candidates** from three sources, in this
+priority order:
 
-1. A `[gitea "<baseUrl>"]` section in `.git/config`:
+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>
    ```
-   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. The `GITEA_TOKEN` environment variable.
-
-If none resolves, the server still starts without a token (anonymous). Public repositories
-may be read; private repos and write operations return `401` — use the `gitea-configure`
-skill to guide setup, or set `GITEA_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
@@ -234,6 +291,7 @@ gitea-mcp
 |------|-------------|
 | `list_my_repos` | List repositories accessible to the authenticated user |
 | `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
 
@@ -290,11 +348,20 @@ 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
 the guide to adding a new tool — see [`docs/architecture.md`](docs/architecture.md).
 
+## Contributing
+
+Contributions are welcome!
+
+- Found a bug or have a feature idea? Please [open an issue](https://github.com/amonstack/gitea_mcp/issues).
+- Pull requests are gladly accepted. This repo follows [Conventional Commits](https://www.conventionalcommits.org/) and the workflow described in [`AGENTS.md`](AGENTS.md) — please skim it before your first PR.
+- For the module layout, dependency graph, and the guide to adding a new tool, see [`docs/architecture.md`](docs/architecture.md).
+
 ## License
 
-MIT
+[MIT](LICENSE) — Copyright (c) 2026 [amonstack](https://github.com/amonstack).

package/README.zh-CN.md

@@ -1,19 +1,50 @@
-# gitea-mcp
+<p align="center">
+  <img alt="gitea-mcp" src="https://raw.githubusercontent.com/amonstack/gitea_mcp/master/docs/assets/gitea-mcp-banner.png" />
+  <h3 align="center">gitea-mcp</h3>
+  <p align="center">MCP 服务端，将 Gitea 的议题、标签、里程碑与评论封装为工具，供 AI 助手调用</p>
+</p>
 
-[English](https://github.com/amonstack/gitea_mcp/blob/master/README.md)
+---
 
-> 让 AI 助手通过 MCP 协议管理 Gitea 仓库 —— 议题、标签、里程碑、评论等功能，
-> 全部通过 Gitea API 实现。
+[![npm version](https://img.shields.io/npm/v/@amonstack/gitea-mcp?logo=npm)](https://www.npmjs.com/package/@amonstack/gitea-mcp)
+[![codecov](https://codecov.io/gh/amonstack/gitea_mcp/branch/master/graph/badge.svg)](https://codecov.io/gh/amonstack/gitea_mcp)
+[![license](https://img.shields.io/npm/l/@amonstack/gitea-mcp)](https://github.com/amonstack/gitea_mcp/blob/master/LICENSE)
+[![Node](https://img.shields.io/node/v/@amonstack/gitea-mcp?logo=node.js)](https://www.npmjs.com/package/@amonstack/gitea-mcp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![MCP](https://img.shields.io/badge/MCP-server-6f42c1?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
 
-## 这是什么？
+[English](https://github.com/amonstack/gitea_mcp/blob/master/README.md) | **中文文档**
 
-`gitea-mcp` 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
-服务端，将 Gitea 仓库操作暴露为 MCP 工具。连接到 MCP 客户端（Claude Desktop、
-opencode、Cursor 等）后，AI 助手即可通过自然语言在 Gitea 实例上创建、查询、
-更新和删除议题、标签、里程碑和评论。
+`gitea-mcp` 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务端，将 Gitea 仓库操作暴露为 MCP 工具。连接到 MCP 客户端（Claude Desktop、opencode、Cursor 等）后，AI 助手即可通过自然语言在 Gitea 实例上创建、查询、更新和删除议题、标签、里程碑和评论。
 
-服务端通过 stdio 通信，封装了 [Gitea REST API
-(`/api/v1`)](https://docs.gitea.com/api/1.22/)。
+服务端通过 stdio 通信，封装了 [Gitea REST API (`/api/v1`)](https://docs.gitea.com/api/1.22/)。
+
+## 功能特性
+
+- **完整的 Gitea 项目管理** —— 通过自然语言管理议题、标签、里程碑与评论
+- **零配置自动发现** —— 从项目 git 配置读取 `baseUrl`、`owner`、`repo` 与令牌；一次全局安装即可服务多个仓库
+- **多来源认证 + 自动容错** —— 依次尝试 `[gitea]` 配置令牌、`GITEA_TOKEN`、git 凭据存储，遇 `401`/`403` 自动切换
+- **按动作划分的技能** —— 每个工作流一个技能（查找、创建、打标签、评论、规划里程碑……），适配 opencode、Claude Code、Cursor 等
+- **客户端无关** —— 兼容任何基于 stdio 的 MCP 客户端；同时内置引导提示与按需参考资源
+
+## 目录
+
+- [功能特性](#功能特性)
+- [环境要求](#环境要求)
+- [安装](#安装)
+- [配置](#配置)
+- [MCP 客户端配置](#mcp-客户端配置)
+- [可用工具](#可用工具)
+- [AI 引导与技能](#ai-引导与技能)
+- [二次开发](#二次开发)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
+
+## 环境要求
+
+- **Node.js ≥ 18** —— 使用全局 `fetch`
+- 一个可通过 HTTP 访问的 **Gitea 实例**（自托管或 Gitea Cloud）
+- 一个 **Gitea API 令牌**（或 git 凭据存储条目），用于读取公开仓库以外的操作
 
 ## 安装
 
@@ -56,7 +87,7 @@ node dist/cli.js
 | 变量 | 必填 | 说明 |
 |------|:----:|------|
 | `GITEA_BASE_URL` | 否 | Gitea 实例地址（如 `https://gitea.example.com`）。未设置时从项目 git 远程地址自动推导。 |
-| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。依次从 `.git/config`、git 凭据存储、本变量解析（见[令牌发现](#令牌发现)）。 |
+| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。是多个认证候选之一；排在 `.git/config [gitea]` 令牌之后、git 凭据存储之前（见[令牌发现](#令牌发现)）。 |
 | `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者，免去每次传入 `owner` 参数 |
 | `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称，免去每次传入 `repo` 参数 |
 
@@ -76,20 +107,40 @@ node dist/cli.js
 
 ### 令牌发现
 
-令牌按以下顺序解析（先匹配者胜出）：
+`gitea-mcp` 从三个来源收集认证**候选**，按以下优先级排序：
 
-1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段：
+1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段（不带地址的 `[gitea]` 段作为全局兜底）：
    ```ini
    [gitea "https://gitea.example.com"]
        token = <your-token>
    ```
-   不带地址的 `[gitea]` 段中的 `token = ...` 作为全局兜底。
-2. git 凭据存储（`~/.git-credentials`，或 `$XDG_CONFIG_HOME/git/credentials`）——host 匹配实例
-   的那一行，如 `https://oauth2:<token>@gitea.example.com`。
-3. `GITEA_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 存的是
+用户在密码提示里输入的任何内容，服务端无法静态区分。因此每个凭据存储条目会以**两种认证方案**
+依次尝试：
 
-若都未解析到，服务器仍会以匿名方式启动。公开仓库可读；私有仓库和写操作返回 `401`——此时使用
-`gitea-configure` 技能引导配置，或设置 `GITEA_TOKEN`。
+- `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 仓库
@@ -227,6 +278,7 @@ gitea-mcp
 |------|------|
 | `list_my_repos` | 列出当前用户可访问的仓库 |
 | `resolve_repo` | 从项目 git 远程地址检测 `baseUrl`、`owner`、`repo`（优先 `upstream`，回退 `origin`） |
+| `gitea_status` | 查看认证处理状态 —— active 候选、已耗尽候选、最近一次错误（脱敏；永不暴露密钥） |
 
 ## AI 引导与技能
 
@@ -279,11 +331,20 @@ npm ci
 | `make test` | 运行单元测试 |
 | `make test-watch` | 监听模式运行测试 |
 | `make test-integration` | 运行集成测试（需要可用的 Gitea 实例） |
+| `make scan` | 用 gitleaks 扫描泄露的密钥（属于 `make verify`） |
 | `make dev` | 通过 tsx 直接运行 |
 
 完整的架构说明（模块布局、依赖关系、核心模式，以及新增工具的指引）请参阅
 [`docs/architecture.md`](docs/architecture.md)。
 
+## 参与贡献
+
+欢迎贡献！
+
+- 发现 bug 或有功能建议？请[提交一个 issue](https://github.com/amonstack/gitea_mcp/issues)。
+- 欢迎提交 Pull Request。本仓库遵循 [Conventional Commits](https://www.conventionalcommits.org/)，工作流见 [`AGENTS.md`](AGENTS.md) —— 首次 PR 前请先浏览一遍。
+- 模块布局、依赖关系、核心模式以及新增工具的指引，请参阅 [`docs/architecture.md`](docs/architecture.md)。
+
 ## 许可证
 
-MIT
+[MIT](LICENSE) —— 版权所有 (c) 2026 [amonstack](https://github.com/amonstack)。

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+export declare const TOP_LEVEL_USAGE = "Usage: gitea-mcp [command] [options]\n\nGitea MCP server \u2014 exposes Gitea issues, labels, milestones, and comments as\ntools for AI assistants. With no command, it starts the Model Context Protocol\nserver over stdio and auto-discovers baseUrl, owner, repo, and credentials from\nthe environment and the local git remote (.git/config).\n\nCommands:\n  init    Install bundled action skills into an AI tool's skills directory.\n\nOptions:\n  -h, --help        Show this help and exit.\n  -V, --version     Show version and exit.\n\nWith no command, gitea-mcp starts the MCP server. Run `gitea-mcp init --help`\nfor init-specific options.\n";

package/dist/cli.js

@@ -1,8 +1,36 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { runServer } from "./server.js";
 import { discoverConfig } from "./git-config.js";
+const pkgVersion = createRequire(import.meta.url)("../package.json").version;
+export const TOP_LEVEL_USAGE = `Usage: gitea-mcp [command] [options]
+
+Gitea MCP server — exposes Gitea issues, labels, milestones, and comments as
+tools for AI assistants. With no command, it starts the Model Context Protocol
+server over stdio and auto-discovers baseUrl, owner, repo, and credentials from
+the environment and the local git remote (.git/config).
+
+Commands:
+  init    Install bundled action skills into an AI tool's skills directory.
+
+Options:
+  -h, --help        Show this help and exit.
+  -V, --version     Show version and exit.
+
+With no command, gitea-mcp starts the MCP server. Run \`gitea-mcp init --help\`
+for init-specific options.
+`;
 const argv = process.argv.slice(2);
-if (argv[0] === "init") {
+const head = argv[0];
+if (head === "-h" || head === "--help" || head === "help") {
+    process.stdout.write(TOP_LEVEL_USAGE);
+    process.exit(0);
+}
+if (head === "-V" || head === "--version") {
+    process.stdout.write(`gitea-mcp ${pkgVersion}\n`);
+    process.exit(0);
+}
+if (head === "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 config-discovery logic below.
@@ -13,10 +41,14 @@ if (argv[0] === "init") {
     });
 }
 else {
-    // Resolve baseUrl/owner/repo/token from env first, then the local git context
-    // (`.git/config` remotes + credential store). 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.
+    // 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);
@@ -25,7 +57,7 @@ else {
         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(discovered.baseUrl, discovered.token, discovered.defaultOwner, discovered.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;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,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,8DAA8D;IAC9D,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,KAAK,EAChB,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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,UAAU,GAAI,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAyB,CAAC,OAAO,CAAC;AAEtG,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;CAgB9B,CAAC;AAEF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAErB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,UAAU,IAAI,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;IACpB,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;