feat: add wiki CLI commands (#998)

## Summary Add first-class `tea wiki` commands backed by the existing Gitea wiki API and SDK support. ## What this adds - `tea wiki list` - `tea wiki view <page>` - `tea wiki revisions <page>` - `tea wiki create` - `tea wiki edit <page>` - `tea wiki delete <page>` ## Implementation details - registers a new top-level `wiki` entity command - keeps command logic under `cmd/wiki/` - adds wiki-specific renderers in `modules/print/wiki.go` - adds wiki task helpers in `modules/task/wiki.go` - reuses existing repo/login/output/pagination patterns used elsewhere in `tea` - base64-encodes wiki content for create/edit API calls - requires explicit `--confirm` for delete - preserves the current page title during edit when `--title` is omitted ## Test coverage The PR is intentionally split into two commits: 1. `feat: add wiki CLI commands` 2. `test: add wiki integration coverage` Validation performed: - focused command, task, and print tests for the new wiki functionality - integration coverage for the wiki command lifecycle - `make lint` - `make fmt-check` - `make docs-check` - `make build` - upstream PR CI passed: - `check-and-test / Integration Test` - `check-and-test / Lint Build And Unit Coverage` ## Motivation This makes `tea` a better interface for both human and agent-driven workflows by exposing wiki operations as stable first-class CLI commands instead of requiring ad-hoc API calls or custom wrappers. --- Generated by Hermes Agent with GPT-5.4 --------- Co-authored-by: nitro <nitro@nitroui-Macmini.local> Reviewed-on: https://gitea.com/gitea/tea/pulls/998 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: kuil09 <202447+kuil09@noreply.gitea.com> Co-committed-by: kuil09 <202447+kuil09@noreply.gitea.com>
2026-06-05 18:58:43 +02:00 · 2026-05-26 21:14:47 +00:00
parent 28ba9b915b
commit 06e4d16bf3
13 changed files with 1378 additions and 0 deletions
@@ -0,0 +1,209 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package print
+
+import (
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.dev/sdk"
+)
+
+// WikiPageFields are all available fields to print with WikiPagesList().
+var WikiPageFields = []string{
+	"title",
+	"path",
+	"url",
+	"sha",
+	"author",
+	"updated",
+	"message",
+}
+
+// WikiRevisionFields are all available fields to print with WikiRevisionsList().
+var WikiRevisionFields = []string{
+	"sha",
+	"message",
+	"author",
+	"date",
+}
+
+// WikiPagesList prints a listing of wiki pages.
+func WikiPagesList(pages []*gitea.WikiPageMetaData, output string, fields []string) error {
+	if len(pages) == 0 && !isMachineReadable(output) {
+		fmt.Println("No wiki pages found")
+		return nil
+	}
+
+	t := wikiPagesTable(pages, fields, isMachineReadable(output))
+	return t.print(output)
+}
+
+// WikiPageDetails prints a wiki page.
+func WikiPageDetails(page *gitea.WikiPage, output string) error {
+	if output == "" {
+		markdown, err := renderWikiPageMarkdown(page)
+		if err != nil {
+			return err
+		}
+		return outputMarkdown(markdown, getRepoURL(page.HTMLURL))
+	}
+
+	t := wikiPageDetailsTable(page, isMachineReadable(output))
+	return t.print(output)
+}
+
+// WikiRevisionsList prints a listing of wiki page revisions.
+func WikiRevisionsList(revisions []*gitea.WikiCommit, output string, fields []string) error {
+	t := wikiRevisionsTable(revisions, fields, isMachineReadable(output))
+	return t.print(output)
+}
+
+func wikiPagesTable(pages []*gitea.WikiPageMetaData, fields []string, machineReadable bool) table {
+	printables := make([]printable, len(pages))
+	for i, page := range pages {
+		printables[i] = printableWikiPageMetaData{page}
+	}
+	return tableFromItems(fields, printables, machineReadable)
+}
+
+func wikiPageDetailsTable(page *gitea.WikiPage, machineReadable bool) table {
+	content, _ := decodeWikiContent(page.ContentBase64)
+	fields := []string{"title", "content", "commits", "path", "url", "sha", "author", "updated", "message"}
+	return tableFromItems(fields, []printable{printableWikiPage{page: page, content: content}}, machineReadable)
+}
+
+func wikiRevisionsTable(revisions []*gitea.WikiCommit, fields []string, machineReadable bool) table {
+	printables := make([]printable, len(revisions))
+	for i, revision := range revisions {
+		printables[i] = printableWikiRevision{revision}
+	}
+	return tableFromItems(fields, printables, machineReadable)
+}
+
+func renderWikiPageMarkdown(page *gitea.WikiPage) (string, error) {
+	content, err := decodeWikiContent(page.ContentBase64)
+	if err != nil {
+		return "", err
+	}
+	if !strings.HasSuffix(content, "\n") {
+		content += "\n"
+	}
+	return content, nil
+}
+
+func decodeWikiContent(contentBase64 string) (string, error) {
+	decoded, err := base64.StdEncoding.DecodeString(contentBase64)
+	if err != nil {
+		return "", err
+	}
+	return string(decoded), nil
+}
+
+type printableWikiPageMetaData struct{ *gitea.WikiPageMetaData }
+
+type printableWikiPage struct {
+	page    *gitea.WikiPage
+	content string
+}
+
+type printableWikiRevision struct{ *gitea.WikiCommit }
+
+func (x printableWikiPageMetaData) FormatField(field string, machineReadable bool) string {
+	switch field {
+	case "title":
+		return x.Title
+	case "path":
+		return x.SubURL
+	case "url":
+		return x.HTMLURL
+	case "sha":
+		return shortWikiCommitID(x.LastCommit)
+	case "author":
+		return wikiCommitAuthor(x.LastCommit)
+	case "updated":
+		return wikiCommitDate(x.LastCommit, machineReadable)
+	case "message":
+		return wikiCommitMessage(x.LastCommit)
+	}
+	return ""
+}
+
+func (x printableWikiPage) FormatField(field string, machineReadable bool) string {
+	switch field {
+	case "title":
+		return x.page.Title
+	case "content":
+		return x.content
+	case "commits":
+		return fmt.Sprintf("%d", x.page.CommitCount)
+	case "path":
+		return x.page.SubURL
+	case "url":
+		return x.page.HTMLURL
+	case "sha":
+		return shortWikiCommitID(x.page.LastCommit)
+	case "author":
+		return wikiCommitAuthor(x.page.LastCommit)
+	case "updated":
+		return wikiCommitDate(x.page.LastCommit, machineReadable)
+	case "message":
+		return wikiCommitMessage(x.page.LastCommit)
+	}
+	return ""
+}
+
+func (x printableWikiRevision) FormatField(field string, machineReadable bool) string {
+	switch field {
+	case "sha":
+		return shortWikiCommitID(x.WikiCommit)
+	case "message":
+		return x.Message
+	case "author":
+		return wikiCommitAuthor(x.WikiCommit)
+	case "date":
+		return wikiCommitDate(x.WikiCommit, machineReadable)
+	}
+	return ""
+}
+
+func shortWikiCommitID(commit *gitea.WikiCommit) string {
+	if commit == nil {
+		return ""
+	}
+	if len(commit.ID) <= 7 {
+		return commit.ID
+	}
+	return commit.ID[:7]
+}
+
+func wikiCommitAuthor(commit *gitea.WikiCommit) string {
+	if commit == nil || commit.Author == nil {
+		return ""
+	}
+	if commit.Author.Name != "" {
+		return commit.Author.Name
+	}
+	return commit.Author.Email
+}
+
+func wikiCommitDate(commit *gitea.WikiCommit, machineReadable bool) string {
+	if commit == nil || commit.Author == nil || commit.Author.Date == "" {
+		return ""
+	}
+	parsed, err := time.Parse(time.RFC3339, commit.Author.Date)
+	if err != nil {
+		return commit.Author.Date
+	}
+	return FormatTime(parsed, machineReadable)
+}
+
+func wikiCommitMessage(commit *gitea.WikiCommit) string {
+	if commit == nil {
+		return ""
+	}
+	return commit.Message
+}
@@ -0,0 +1,110 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package print
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"os"
+	"testing"
+
+	"gitea.dev/sdk"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWikiPagesTableJSON(t *testing.T) {
+	pages := []*gitea.WikiPageMetaData{{
+		Title:   "Home",
+		HTMLURL: "https://gitea.example.com/octo/tea/wiki/Home",
+		SubURL:  "/octo/tea/wiki/Home",
+		LastCommit: &gitea.WikiCommit{
+			ID:      "abcdef123456",
+			Message: "update home",
+			Author:  &gitea.CommitUser{GitIdentity: gitea.GitIdentity{Name: "alice"}, Date: "2026-05-21T01:02:03Z"},
+		},
+	}}
+
+	tbl := wikiPagesTable(pages, []string{"title", "author", "updated", "sha", "url"}, true)
+	buf := &bytes.Buffer{}
+	require.NoError(t, tbl.fprint(buf, "json"))
+
+	var rows []map[string]string
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &rows))
+	require.Len(t, rows, 1)
+	assert.Equal(t, "Home", rows[0]["title"])
+	assert.Equal(t, "alice", rows[0]["author"])
+	assert.Equal(t, "2026-05-21T01:02:03Z", rows[0]["updated"])
+	assert.Equal(t, "abcdef1", rows[0]["sha"])
+	assert.Equal(t, "https://gitea.example.com/octo/tea/wiki/Home", rows[0]["url"])
+}
+
+func TestWikiRevisionsTableJSON(t *testing.T) {
+	revisions := []*gitea.WikiCommit{{
+		ID:      "1234567890abcdef",
+		Message: "second revision",
+		Author:  &gitea.CommitUser{GitIdentity: gitea.GitIdentity{Name: "bob"}, Date: "2026-05-22T03:04:05Z"},
+	}}
+
+	tbl := wikiRevisionsTable(revisions, []string{"sha", "message", "author", "date"}, true)
+	buf := &bytes.Buffer{}
+	require.NoError(t, tbl.fprint(buf, "json"))
+
+	var rows []map[string]string
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &rows))
+	require.Len(t, rows, 1)
+	assert.Equal(t, "1234567", rows[0]["sha"])
+	assert.Equal(t, "second revision", rows[0]["message"])
+	assert.Equal(t, "bob", rows[0]["author"])
+	assert.Equal(t, "2026-05-22T03:04:05Z", rows[0]["date"])
+}
+
+func TestRenderWikiPageMarkdownReturnsDecodedWikiContent(t *testing.T) {
+	page := &gitea.WikiPage{
+		Title:         "Home",
+		HTMLURL:       "https://gitea.example.com/octo/tea/wiki/Home",
+		ContentBase64: "IyBIZWxsbyB3aWtp",
+		LastCommit: &gitea.WikiCommit{
+			Author: &gitea.CommitUser{GitIdentity: gitea.GitIdentity{Name: "carol"}, Date: "2026-05-23T06:07:08Z"},
+		},
+	}
+
+	out, err := renderWikiPageMarkdown(page)
+	require.NoError(t, err)
+	assert.Equal(t, "# Hello wiki\n", out)
+}
+
+func TestWikiPagesListEmptyHumanOutput(t *testing.T) {
+	out := captureStdout(t, func() {
+		require.NoError(t, WikiPagesList(nil, "", []string{"title"}))
+	})
+
+	assert.Equal(t, "No wiki pages found\n", out)
+}
+
+func captureStdout(t *testing.T, fn func()) string {
+	t.Helper()
+
+	oldStdout := os.Stdout
+	reader, writer, err := os.Pipe()
+	require.NoError(t, err)
+	os.Stdout = writer
+	defer func() {
+		os.Stdout = oldStdout
+	}()
+
+	done := make(chan string, 1)
+	go func() {
+		var outBuf bytes.Buffer
+		_, _ = io.Copy(&outBuf, reader)
+		done <- outBuf.String()
+	}()
+
+	fn()
+	require.NoError(t, writer.Close())
+	output := <-done
+	require.NoError(t, reader.Close())
+	return output
+}
@@ -0,0 +1,61 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	stdctx "context"
+	"fmt"
+
+	"gitea.dev/sdk"
+	teaContext "gitea.dev/tea/modules/context"
+)
+
+// WikiWriteClient defines the wiki write methods required by task helpers.
+type WikiWriteClient interface {
+	CreatePage(ctx stdctx.Context, owner, repo string, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, *gitea.Response, error)
+	EditPage(ctx stdctx.Context, owner, repo, pageName string, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, *gitea.Response, error)
+	DeletePage(ctx stdctx.Context, owner, repo, pageName string) (*gitea.Response, error)
+}
+
+// CreateWikiPage creates a wiki page and returns the created page.
+func CreateWikiPage(ctx *teaContext.TeaContext, client WikiWriteClient, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, error) {
+	if opt.Title == "" {
+		return nil, fmt.Errorf("title is required")
+	}
+	if opt.ContentBase64 == "" {
+		return nil, fmt.Errorf("content is required")
+	}
+	page, _, err := client.CreatePage(stdctx.Background(), ctx.Owner, ctx.Repo, opt)
+	if err != nil {
+		return nil, fmt.Errorf("could not create wiki page: %s", err)
+	}
+	return page, nil
+}
+
+// EditWikiPage edits a wiki page and returns the updated page.
+func EditWikiPage(ctx *teaContext.TeaContext, client WikiWriteClient, pageName string, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, error) {
+	if pageName == "" {
+		return nil, fmt.Errorf("page name is required")
+	}
+	if opt.ContentBase64 == "" {
+		return nil, fmt.Errorf("content is required")
+	}
+	page, _, err := client.EditPage(stdctx.Background(), ctx.Owner, ctx.Repo, pageName, opt)
+	if err != nil {
+		return nil, fmt.Errorf("could not edit wiki page: %s", err)
+	}
+	return page, nil
+}
+
+// DeleteWikiPage deletes a wiki page.
+func DeleteWikiPage(ctx *teaContext.TeaContext, client WikiWriteClient, pageName string) error {
+	if pageName == "" {
+		return fmt.Errorf("page name is required")
+	}
+	_, err := client.DeletePage(stdctx.Background(), ctx.Owner, ctx.Repo, pageName)
+	if err != nil {
+		return fmt.Errorf("could not delete wiki page: %s", err)
+	}
+	return nil
+}
@@ -0,0 +1,83 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	stdctx "context"
+	"testing"
+
+	"gitea.dev/sdk"
+	teaContext "gitea.dev/tea/modules/context"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type fakeWikiWriteClient struct {
+	owner    string
+	repo     string
+	pageName string
+	create   gitea.CreateWikiPageOptions
+	edit     gitea.CreateWikiPageOptions
+	created  *gitea.WikiPage
+	edited   *gitea.WikiPage
+	deleted  bool
+}
+
+func (f *fakeWikiWriteClient) CreatePage(_ stdctx.Context, owner, repo string, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, *gitea.Response, error) {
+	f.owner = owner
+	f.repo = repo
+	f.create = opt
+	return f.created, nil, nil
+}
+
+func (f *fakeWikiWriteClient) EditPage(_ stdctx.Context, owner, repo, pageName string, opt gitea.CreateWikiPageOptions) (*gitea.WikiPage, *gitea.Response, error) {
+	f.owner = owner
+	f.repo = repo
+	f.pageName = pageName
+	f.edit = opt
+	return f.edited, nil, nil
+}
+
+func (f *fakeWikiWriteClient) DeletePage(_ stdctx.Context, owner, repo, pageName string) (*gitea.Response, error) {
+	f.owner = owner
+	f.repo = repo
+	f.pageName = pageName
+	f.deleted = true
+	return nil, nil
+}
+
+func newWikiTaskContext() *teaContext.TeaContext {
+	return &teaContext.TeaContext{Owner: "octo", Repo: "tea"}
+}
+
+func TestCreateWikiPageCallsSDK(t *testing.T) {
+	client := &fakeWikiWriteClient{created: &gitea.WikiPage{Title: "Home"}}
+	page, err := CreateWikiPage(newWikiTaskContext(), client, gitea.CreateWikiPageOptions{Title: "Home", ContentBase64: "IyBIb21l"})
+	require.NoError(t, err)
+	assert.Equal(t, "octo", client.owner)
+	assert.Equal(t, "tea", client.repo)
+	assert.Equal(t, "Home", client.create.Title)
+	assert.Equal(t, "Home", page.Title)
+}
+
+func TestEditWikiPageCallsSDK(t *testing.T) {
+	client := &fakeWikiWriteClient{edited: &gitea.WikiPage{Title: "Home"}}
+	page, err := EditWikiPage(newWikiTaskContext(), client, "Home", gitea.CreateWikiPageOptions{ContentBase64: "IyBVcGRhdGVk"})
+	require.NoError(t, err)
+	assert.Equal(t, "octo", client.owner)
+	assert.Equal(t, "tea", client.repo)
+	assert.Equal(t, "Home", client.pageName)
+	assert.Equal(t, "IyBVcGRhdGVk", client.edit.ContentBase64)
+	assert.Equal(t, "Home", page.Title)
+}
+
+func TestDeleteWikiPageCallsSDK(t *testing.T) {
+	client := &fakeWikiWriteClient{}
+	err := DeleteWikiPage(newWikiTaskContext(), client, "Home")
+	require.NoError(t, err)
+	assert.Equal(t, "octo", client.owner)
+	assert.Equal(t, "tea", client.repo)
+	assert.Equal(t, "Home", client.pageName)
+	assert.True(t, client.deleted)
+}