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>

Makefile

@@ -24,17 +24,13 @@ endif
 TEA_VERSION_TAG ?= $(shell sed 's/+/_/' <<< $(TEA_VERSION))
 
 TAGS ?=
-SDK ?= $(shell $(GO) list -f '{{.Version}}' -m gitea.dev/sdk)
-LDFLAGS := -X "gitea.dev/tea/modules/version.Version=$(TEA_VERSION)" -X "gitea.dev/tea/modules/version.Tags=$(TAGS)" -X "gitea.dev/tea/modules/version.SDK=$(SDK)" -s -w
+LDFLAGS := -X "gitea.dev/tea/internal/version.Version=$(TEA_VERSION)" -X "gitea.dev/tea/internal/version.Tags=$(TAGS)" -s -w
 
 # override to allow passing additional goflags via make CLI
 override GOFLAGS := $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LDFLAGS)'
 
-PACKAGES ?= $(shell $(GO) list ./... | grep -v '^gitea.dev/tea/tests')
+PACKAGES ?= $(shell $(GO) list ./...)
 UNIT_PACKAGES ?= $(PACKAGES)
-INTEGRATION_PACKAGES ?= $(shell $(GO) list ./tests/... 2>/dev/null)
-INTEGRATION_TEST_TAGS ?= testtools
-INTEGRATION_TEST_GOFLAGS ?= -v
 SOURCES ?= $(shell find . -name "*.go" -type f)
 
 # OS specific vars.
@@ -68,11 +64,11 @@ vet:
 
 .PHONY: lint
 lint:
-	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --build-tags testtools
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) run
 
 .PHONY: lint-fix
 lint-fix:
-	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --build-tags testtools --fix
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --fix
 
 .PHONY: fmt-check
 fmt-check:
@@ -84,18 +80,39 @@ fmt-check:
 		exit 1; \
 	fi;
 
+# Man pages are dated by the last commit unless SOURCE_DATE_EPOCH is already set.
 .PHONY: docs
 docs:
-	$(GO) run docs/docs.go --out docs/CLI.md
+	SOURCE_DATE_EPOCH=$${SOURCE_DATE_EPOCH:-$$(git log -1 --format=%ct 2>/dev/null)} TZ=UTC $(GO) run ./tools/cli-docs --out docs/generated
 
-.PHONY: docs-check
-docs-check:
-	@DIFF=$$($(GO) run docs/docs.go | diff docs/CLI.md -); \
-	if [ -n "$$DIFF" ]; then \
-		echo "Please run 'make docs' and commit the result:"; \
-		echo "$$DIFF"; \
-		exit 1; \
-	fi;
+# Versioned docs archive for release uploads (references, man pages, completions).
+# Keep the artifact outside dist/: goreleaser requires dist/ empty after before hooks.
+# The .tar.xz suffix matches existing release/publisher/checksum ./**.xz globs.
+DOCS_ARCHIVE ?= tea-$(TEA_VERSION_TAG)-docs.tar.xz
+
+.PHONY: docs-archive
+docs-archive: docs
+	@rm -f "$(DOCS_ARCHIVE)" "$(DOCS_ARCHIVE).sha256"
+	tar -C docs/generated -c README.md reference man completion | xz -9 > "$(DOCS_ARCHIVE)"
+	@bash .goreleaser.checksum.sh "$(DOCS_ARCHIVE)"
+
+# Install generated man pages and shell completions for packagers / local installs.
+# Binary install remains `make install` (GOPATH/bin). Override PREFIX/DESTDIR as needed.
+PREFIX ?= /usr/local
+DESTDIR ?=
+
+.PHONY: install-docs
+install-docs: docs
+	install -d "$(DESTDIR)$(PREFIX)/share/man/man1"
+	install -m 644 docs/generated/man/*.1 "$(DESTDIR)$(PREFIX)/share/man/man1/"
+	install -d "$(DESTDIR)$(PREFIX)/share/bash-completion/completions"
+	install -m 644 docs/generated/completion/tea.bash "$(DESTDIR)$(PREFIX)/share/bash-completion/completions/tea"
+	install -d "$(DESTDIR)$(PREFIX)/share/zsh/site-functions"
+	install -m 644 docs/generated/completion/_tea "$(DESTDIR)$(PREFIX)/share/zsh/site-functions/_tea"
+	install -d "$(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d"
+	install -m 644 docs/generated/completion/tea.fish "$(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/tea.fish"
+	install -d "$(DESTDIR)$(PREFIX)/share/powershell/Modules/tea"
+	install -m 644 docs/generated/completion/tea.ps1 "$(DESTDIR)$(PREFIX)/share/powershell/Modules/tea/tea.ps1"
 
 .PHONY: unit-test
 unit-test:
@@ -103,18 +120,17 @@ unit-test:
 
 .PHONY: integration-test
 integration-test:
-	@if [ -n "$(INTEGRATION_PACKAGES)" ]; then \
-		$(GO) test $(INTEGRATION_TEST_GOFLAGS) -tags='$(INTEGRATION_TEST_TAGS)' $(INTEGRATION_PACKAGES); \
-	else \
-		echo "No integration test packages found"; \
-	fi
+	@test -n "$$GITEA_TEA_TEST_URL" || { echo 'Set GITEA_TEA_TEST_URL to a disposable Gitea instance' >&2; exit 1; }
+	@test -r "$$GITEA_TEA_TEST_TOKEN_FILE" || { echo 'Set GITEA_TEA_TEST_TOKEN_FILE to a readable administrator token file' >&2; exit 1; }
+	@test -r "$$GITEA_TEA_TEST_REVIEWER_TOKEN_FILE" || { echo 'Set GITEA_TEA_TEST_REVIEWER_TOKEN_FILE to a readable reviewer token file' >&2; exit 1; }
+	$(GO) test -count=1 -race -run '^TestGitea' $(PACKAGES)
 
 .PHONY: test
-test: unit-test integration-test
+test: unit-test
 
 .PHONY: unit-test-coverage
 unit-test-coverage:
-	$(GO) test -cover -coverprofile coverage.out $(UNIT_PACKAGES) && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+	$(GO) test -race -cover -coverprofile coverage.out $(UNIT_PACKAGES) && echo "\n==>\033[32m Ok\033[m\n" || exit 1
 
 .PHONY: tidy
 tidy: