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>

CONTRIBUTING.md

@@ -56,9 +56,27 @@ high-level discussions.
 
 ## Testing redux
 
-Before sending code out for review, run all the test by executing: `make test`
+Before sending code out for review, run the unit tests with `make test`.
 Since TEA is an cli tool it should be obvious to test your feature locally first.
 
+Tests live beside the packages they exercise. `make integration-test` runs the
+`TestGitea*` tests against a disposable Gitea instance with an administrator
+account named `integration` and a reviewer named `tea-reviewer`. Never point
+these tests at a production instance: they create and delete resources.
+
+```sh
+GITEA_TEA_TEST_URL=http://127.0.0.1:3000 \
+GITEA_TEA_TEST_TOKEN_FILE=/private/path/admin-token \
+GITEA_TEA_TEST_REVIEWER_TOKEN_FILE=/private/path/reviewer-token \
+  make integration-test
+```
+
+Token files contain scoped PATs for their accounts and should be `0600`;
+`scripts/integration-tokens.py` creates them for the CI accounts. Optional
+coverage is enabled by `GITEA_TEA_TEST_REPOSITORY_ROOT` (the server's repository
+root, with `[repository] IMPORT_LOCAL_PATHS = true`, for migration) and
+`GITEA_TEA_TEST_SSH_ENDPOINT` (an SSH clone endpoint).
+
 ## Code review
 
 Changes to TEA must be reviewed before they are accepted—no matter who
@@ -81,52 +99,49 @@ Some of the key points:
 ## Styleguide
 
 ### Commands
-- Subcommands should follow the following structure:
-    ```
-    tea <noun> <verb> [<noun>] [<flags>]
-    ```
 
-    for example:
+Use explicit singular noun/verb commands, such as `tea issue list` and
+`tea pr create`. Bare command groups show help. Commands validate input, collect
+missing fields when the shared prompting policy permits it, invoke services, and
+render results through injected streams. Destructive commands require confirmation
+or `--yes`; `--no-input` disables implicit interaction. JSON results go to stdout;
+diagnostics and prompts go to stderr. Lists register `--limit`/`--page` with
+`pageFlags` and print through `writeList`, which renders one `terminal.Table`
+(ID or number first, then title or name, then state) through the pager.
 
-    ```
-    tea issues list
-    tea pulls create
-    tea teams add user --team x --user y
-    ```
-- Commands should accept nouns as singular & plural by making use of the `Aliases` field.
-- The default action without a verb is `list`.
-- There is a standard set of verbs: `list/ls`, `create`, `edit`, `delete`
-  - `ls` lists objects with filter options, and applies pagination where available.
-  - `delete` should show info what is deleted and ask user again, if force flag`-y` is not set
-  - Verbs that accept large numbers of flags provide an interactive mode when called without any arguments or flags.
-- Try to reuse as many flag definitions as possible, see `cmd/flags/flags.go`.
-- Always make sure that the help texts are properly set, and as concise as possible.
+### Internal Package Structure
 
-### Internal Module Structure
-- `cmd`: only contains command/flag options for `urfave/cli`
-  - subcommands are in a subpackage named after its parent command
-- `modules/task`: contain func for doing something with gitea
-  (e.g. create token by user/passwd)
-- `modules/print`: contain all functions that print to stdout
-- `modules/config`: config tea & login things
-- `modules/interact`: contain functions to interact with user by prompts
-- `modules/git`: do git related stuff (get info/push/pull/checkout/...)
-- `modules/utils`: helper functions used by other functions
+- `internal/app`: Cobra commands and application dependency construction.
+- `internal/services`: typed workflows over `gitea.dev/sdk`, independent of CLI flags
+  and terminal I/O, including pagination policy. Services map SDK types to tea's
+  output types; requests the SDK cannot make yet go through the raw helpers in
+  `raw.go`, each marked `TODO(sdk)` with the missing SDK piece.
+- `internal/settings`: split configuration, validation, persistence, target resolution,
+  and remote URL parsing.
+- `internal/auth`: secure credentials and OAuth lifecycle.
+- `internal/transport`: the tea HTTP client shared by the SDK and raw requests: TLS,
+  timeouts, User-Agent, `--debug`, retries, token, Sudo and SSH-signature
+  authentication, and sanitised API errors. Its raw requests serve `tea api`, signed
+  downloads and log streaming.
+- `internal/git`: repository discovery and cancellable Git subprocesses.
+- `internal/terminal`: streams, input, editor, browser, and rendering.
+- `internal/clierr`: typed errors and executable exit codes.
+- `internal/aliases`: user command alias expansion.
+- `internal/filelock`: cross-process locks for configuration writes.
+- `internal/version`: build version metadata.
+
+Unit and integration tests live beside their packages; see [Testing redux](#testing-redux).
 
 ### Code Style
 Use `make fmt`, check with `make lint`.
-For imports you should use the following format (_without_ the comments)
+Group imports into the standard library, then all other packages (local and
+external) in one sorted block, as gofumpt keeps them:
 ```go
 import (
-  // stdlib
   "encoding/json"
   "fmt"
 
-  // local packages
-  "code.gitea.io/gitea/models"
-  "gitea.dev/sdk"
-
-  // external packages
+  "gitea.dev/tea/internal/services"
   "github.com/foo/bar"
   "gopkg.io/baz.v1"
 )