feat!: rebuild tea on Cobra with explicit noun/verb commands (#1126)

- **switch tea to the Cobra command tree:** `internal/app` wires the packages from parts 1–4 into explicit noun/verb commands with `--repo`, `--json` / `--jq`, `--sudo` and `--debug`; `main.go` points at it. Build, release and docs tooling (`tools/cli-docs`, Makefile, goreleaser, snap, CI) and README / CONTRIBUTING are updated. - **remove the urfave/cli command tree:** deletes `cmd/`, `modules/`, the old integration tests, contrib completion scripts and the generated `docs/CLI.md`, and drops their dependencies. This commit only deletes. ## Breaking changes This is a breaking release. It requires Gitea 28 or newer; configuration moves to separate `config.yml` and `hosts.yml` files and requires fresh authentication, and command names, aliases, flags and output formats change. `docs/migration-1.0.md` maps every old command, flag and environment variable to its replacement. ## Issues fixes #1118 fixes #1116 fixes #1115 fixes #1094 fixes #1091 fixes #1073 fixes #1052 fixes #1032 fixes #1023 fixes #966 fixes #908 fixes #833 fixes #831 fixes #817 fixes #804 fixes #779 fixes #770 fixes #737 fixes #697 fixes #726 fixes #677 fixes #672 fixes #633 fixes #632 fixes #560 fixes #556 fixes #523 fixes #516 fixes #510 fixes #504 fixes #500 fixes #482 fixes #406 fixes #403 fixes #373 fixes #351 fixes #344 fixes #326 fixes #325 fixes #323 fixes #246 fixes #240 fixes #232 fixes #197 fixes #172 fixes #141 fixes #69 fixes #1110 fixes #569 fixes #480 fixes #666 fixes #670 fixes #457 fixes #643 fixes #498 fixes #490 fixes #1069 fixes #834 fixes #602 fixes #328 fixes #417 fixes #571 fixes #1029 fixes #489 fixes #1050 fixes #162 fixes #430 fixes #1087 fixes #683 Reviewed-on: https://gitea.com/gitea/tea/pulls/1126 Reviewed-by: TheFox0x7 <95654+thefox0x7@noreply.gitea.com>
2026-10-26 19:11:25 +01:00 · 2026-10-11 17:23:06 +00:00
1 parent 12e415a7a7
commit f02245449b
@@ -0,0 +1,109 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// cli-docs generates tea's reference, man pages and shell completions.
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.dev/tea/internal/app"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	output := flag.String("out", "docs/generated", "Output directory")
+	flag.Parse()
+	if flag.NArg() != 0 {
+		fmt.Fprintln(os.Stderr, "cli-docs accepts no positional arguments")
+		os.Exit(2)
+	}
+	if err := generate(*output); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func generate(output string) error {
+	// Documentation describes built-ins, independently of personal settings,
+	// credentials, repository discovery, and environment-specific aliases.
+	root := app.NewRoot(app.Dependencies{})
+	var prepare func(*cobra.Command)
+	prepare = func(command *cobra.Command) {
+		command.DisableAutoGenTag = true
+		for _, child := range command.Commands() {
+			prepare(child)
+		}
+	}
+	prepare(root)
+	for _, directory := range []string{"reference", "man", "completion"} {
+		if err := os.MkdirAll(filepath.Join(output, directory), 0o755); err != nil {
+			return err
+		}
+	}
+	if err := doc.GenMarkdownTree(root, filepath.Join(output, "reference")); err != nil {
+		return err
+	}
+	pages, err := filepath.Glob(filepath.Join(output, "reference", "*.md"))
+	if err != nil {
+		return err
+	}
+	for _, page := range pages {
+		content, err := os.ReadFile(page)
+		if err != nil {
+			return err
+		}
+		if err := os.WriteFile(page, []byte(strings.TrimRight(string(content), "\n")+"\n"), 0o644); err != nil {
+			return err
+		}
+	}
+	// Date the pages like tea man; make docs sets SOURCE_DATE_EPOCH to the last commit.
+	date := app.ManualDate(os.Getenv)
+	header := &doc.GenManHeader{Title: "TEA", Section: "1", Date: &date, Source: "Tea", Manual: "Tea Manual"}
+	if err := doc.GenManTree(root, header, filepath.Join(output, "man")); err != nil {
+		return err
+	}
+	completions := []struct {
+		name  string
+		write func(io.Writer) error
+	}{
+		{"tea.bash", func(w io.Writer) error { return root.GenBashCompletionV2(w, true) }},
+		{"_tea", root.GenZshCompletion},
+		{"tea.fish", func(w io.Writer) error { return root.GenFishCompletion(w, true) }},
+		{"tea.ps1", root.GenPowerShellCompletionWithDesc},
+	}
+	for _, completion := range completions {
+		if err := writeFile(filepath.Join(output, "completion", completion.name), completion.write); err != nil {
+			return err
+		}
+	}
+	return os.WriteFile(filepath.Join(output, "README.md"), []byte(strings.TrimSpace(`
+# Tea command reference
+
+Generated from the Cobra command tree with `+"`make docs`"+`.
+These files describe the built-in commands and their supported flags.
+Personal aliases are expanded dynamically by the installed shell completions.
+
+- [Command reference](reference/tea.md)
+- Man pages: `+"`man/tea.1`"+` and one page per command
+- Bash: `+"`completion/tea.bash`"+`
+- Zsh: `+"`completion/_tea`"+`
+- Fish: `+"`completion/tea.fish`"+`
+- PowerShell: `+"`completion/tea.ps1`"+`
+`)+"\n"), 0o644)
+}
+
+func writeFile(path string, write func(io.Writer) error) error {
+	file, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	return errors.Join(write(file), file.Close())
+}
@@ -0,0 +1,68 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package main
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestGeneratedReferenceIsCompleteAndReproducibleWithoutConfiguration(t *testing.T) {
+	// A malformed personal configuration must never enter packaged documentation.
+	config := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(config, "config.yml"), []byte("malformed: ["), 0o600))
+	t.Setenv("TEA_CONFIG_DIR", config)
+	t.Setenv("SOURCE_DATE_EPOCH", "1786795200")
+	first, second := t.TempDir(), t.TempDir()
+	require.NoError(t, generate(first))
+	require.NoError(t, generate(second))
+	links := regexp.MustCompile(`\]\((tea[^)]+\.md)\)`)
+	files := 0
+	require.NoError(t, filepath.WalkDir(first, func(path string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			return nil
+		}
+		relative, err := filepath.Rel(first, path)
+		require.NoError(t, err)
+		original, err := os.ReadFile(path)
+		require.NoError(t, err)
+		regenerated, err := os.ReadFile(filepath.Join(second, relative))
+		require.NoError(t, err)
+		require.Equal(t, string(original), string(regenerated), relative)
+		require.NotContains(t, string(original), "Auto generated")
+		if filepath.Ext(path) == ".md" {
+			for _, link := range links.FindAllStringSubmatch(string(original), -1) {
+				_, err := os.Stat(filepath.Join(filepath.Dir(path), link[1]))
+				require.NoError(t, err, "broken reference link in %s: %s", relative, link[1])
+			}
+		}
+		files++
+		return nil
+	}))
+	require.Greater(t, files, 100)
+	for _, path := range []string{"reference/tea.md", "reference/tea_issue_create.md", "reference/tea_milestone_close.md", "man/tea-auth-login.1", "completion/tea.bash", "completion/_tea", "completion/tea.fish", "completion/tea.ps1"} {
+		content, err := os.ReadFile(filepath.Join(first, filepath.FromSlash(path)))
+		require.NoError(t, err, path)
+		require.NotEmpty(t, strings.TrimSpace(string(content)), path)
+	}
+	root, err := os.ReadFile(filepath.Join(first, "reference", "tea.md"))
+	require.NoError(t, err)
+	require.Contains(t, string(root), "--no-input")
+	require.Contains(t, string(root), "--repo")
+	man, err := os.ReadFile(filepath.Join(first, "man", "tea.1"))
+	require.NoError(t, err)
+	require.Contains(t, string(man), `"Aug 2026"`)
+	milestone, err := os.ReadFile(filepath.Join(first, "reference", "tea_milestone_close.md"))
+	require.NoError(t, err)
+	require.Contains(t, string(milestone), "--by-name")
+}