feat(tools): file_write_branch

Add BranchExists/CreateBranch/UpsertFile gitea client methods and the
file_write_branch MCP tool. Branch is auto-created from base (or repo
default_branch) when it doesn't exist; file is upserted via PUT contents.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

internal/gitea/files.go

@@ -32,3 +32,82 @@ func (c *Client) GetFileContents(ctx context.Context, owner, repo, path, ref str
 	}
 	return &fc, nil
 }
+
+type Branch struct {
+	Name   string `json:"name"`
+	Commit struct {
+		ID  string `json:"id"`
+		URL string `json:"url"`
+	} `json:"commit"`
+}
+
+// BranchExists returns (true, nil) if the branch exists, (false, nil) on 404, (false, err) otherwise.
+func (c *Client) BranchExists(ctx context.Context, owner, repo, branch string) (bool, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/branches/%s", owner, repo, branch)
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return false, err
+	}
+	if status == 404 {
+		return false, nil
+	}
+	if err := MapStatus(status, body); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+func (c *Client) CreateBranch(ctx context.Context, owner, repo, newBranch, oldBranch string) error {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/branches", owner, repo)
+	payload, err := json.Marshal(map[string]string{
+		"new_branch_name": newBranch,
+		"old_branch_name": oldBranch,
+	})
+	if err != nil {
+		return err
+	}
+	body, status, err := c.PostJSON(ctx, p, payload)
+	if err != nil {
+		return err
+	}
+	return MapStatus(status, body)
+}
+
+type UpsertFileArgs struct {
+	Branch  string `json:"branch"`
+	Content string `json:"content"` // already base64-encoded
+	Message string `json:"message"`
+	Sha     string `json:"sha,omitempty"`
+}
+
+type FileWriteResult struct {
+	Content struct {
+		Path    string `json:"path"`
+		Sha     string `json:"sha"`
+		HTMLURL string `json:"html_url"`
+	} `json:"content"`
+	Commit struct {
+		Sha     string `json:"sha"`
+		HTMLURL string `json:"html_url"`
+	} `json:"commit"`
+}
+
+func (c *Client) UpsertFile(ctx context.Context, owner, repo, path string, args UpsertFileArgs) (*FileWriteResult, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
+	payload, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	body, status, err := c.PutJSON(ctx, p, payload)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var out FileWriteResult
+	if err := json.Unmarshal(body, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}

internal/gitea/files_test.go

@@ -2,6 +2,8 @@ package gitea_test
 
 import (
 	"context"
+	"encoding/json"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -28,3 +30,89 @@ func TestGetFileContents(t *testing.T) {
 	assert.Equal(t, int64(13), fc.Size)
 	assert.Equal(t, "SGVsbG8sIHdvcmxkIQ==", fc.Content)
 }
+
+func TestBranchExistsTrue(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branches/main", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"main","commit":{"id":"abc123","url":"http://example.com"}}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	exists, err := c.BranchExists(context.Background(), "o", "r", "main")
+	require.NoError(t, err)
+	assert.True(t, exists)
+}
+
+func TestBranchExistsFalseOn404(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branches/nonexistent", r.URL.Path)
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte(`{"message":"branch not found"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	exists, err := c.BranchExists(context.Background(), "o", "r", "nonexistent")
+	require.NoError(t, err)
+	assert.False(t, exists)
+}
+
+func TestCreateBranchSendsPayload(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branches", r.URL.Path)
+		assert.Equal(t, http.MethodPost, r.Method)
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"name":"feat/x","commit":{"id":"abc","url":"http://example.com"}}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.CreateBranch(context.Background(), "o", "r", "feat/x", "main")
+	require.NoError(t, err)
+
+	var payload map[string]string
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "feat/x", payload["new_branch_name"])
+	assert.Equal(t, "main", payload["old_branch_name"])
+}
+
+func TestUpsertFileSendsPayloadAndDecodesResult(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/contents/p.md", r.URL.Path)
+		assert.Equal(t, http.MethodPut, r.Method)
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"content":{"path":"p.md","sha":"newsha","html_url":"http://example.com/p.md"},"commit":{"sha":"abc","html_url":"http://example.com/commit/abc"}}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	result, err := c.UpsertFile(context.Background(), "o", "r", "p.md", gitea.UpsertFileArgs{
+		Branch:  "feat/x",
+		Content: "aGVsbG8=",
+		Message: "add p.md",
+		Sha:     "oldsha",
+	})
+	require.NoError(t, err)
+
+	var payload map[string]string
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "feat/x", payload["branch"])
+	assert.Equal(t, "aGVsbG8=", payload["content"])
+	assert.Equal(t, "add p.md", payload["message"])
+	assert.Equal(t, "oldsha", payload["sha"])
+
+	assert.Equal(t, "p.md", result.Content.Path)
+	assert.Equal(t, "newsha", result.Content.Sha)
+	assert.Equal(t, "http://example.com/p.md", result.Content.HTMLURL)
+	assert.Equal(t, "abc", result.Commit.Sha)
+}