refactor: add settings, transport and alias packages (#1122)

Part 1/5 of the tea 1.0 rewrite.

**Stack** (split from #1121; each PR targets `main` and builds, tests and lints on its own — the shipped CLI only changes in part 5):

1. #1122 Toolchain and foundation packages ← this PR
2. #1123 Credentials and Git
3. #1124 Terminal
4. #1125 Services
5. #1126 CLI wiring, docs, removal of the old tree

## Changes

- **build:** require Go 1.27; bump gofumpt and golangci-lint to releases that can read Go 1.27 export data (own commit).
- `internal/clierr`: typed errors and executable exit codes.
- `internal/version`: build version and tags.
- `internal/filelock`: moved unchanged from `modules/filelock`.
- `internal/aliases`: user-defined command aliases.
- `internal/transport`: the HTTP client the Gitea SDK runs on (part 4): token, Sudo and SSH-signature auth, retries for safe reads, connect/TLS/response-header timeouts, typed API errors that keep Gitea's message, and a redacted request log for `--debug`; plus raw requests for `tea api`, signed downloads that follow object-storage redirects, and log streaming.
- `internal/settings`: split `config.yml` / `hosts.yml` with locked transactions, plus remote URL parsing.

Nothing imports these packages yet.

Note: `flake.nix` now asks for `go_1_27`; the pinned nixpkgs in `flake.lock` predates Go 1.27 and still needs a `nix flake update nixpkgs`.
Reviewed-on: https://gitea.com/gitea/tea/pulls/1122
Reviewed-by: TheFox0x7 <95654+thefox0x7@noreply.gitea.com>

internal/aliases/aliases.go

@@ -0,0 +1,154 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// Package aliases expands built-in command shortcuts without executing a shell.
+package aliases
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/kballard/go-shellquote"
+)
+
+var (
+	placeholder = regexp.MustCompile(`\$([1-9][0-9]*)`)
+	namePattern = regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`)
+)
+
+// maxDepth bounds alias expansion even when configuration is edited by hand.
+const maxDepth = 16
+
+// validate checks names, quoting, and unsupported shell syntax.
+func validate(name, expansion string, builtins map[string]bool) error {
+	if !namePattern.MatchString(name) {
+		return fmt.Errorf("invalid alias name %q", name)
+	}
+	if builtins[name] {
+		return fmt.Errorf("alias %q collides with a built-in command", name)
+	}
+	words, err := shellquote.Split(expansion)
+	if err != nil {
+		return fmt.Errorf("invalid alias expansion: %w", err)
+	}
+	if len(words) == 0 {
+		return fmt.Errorf("alias expansion cannot be empty")
+	}
+	if strings.HasPrefix(words[0], "!") {
+		return fmt.Errorf("shell aliases are not supported")
+	}
+	// Expansion never runs a shell; rejecting common operators only flags misleading shortcuts.
+	for _, word := range words {
+		switch word {
+		case "|", "||", "&", "&&", ";", "<", ">", ">>", "2>":
+			return fmt.Errorf("shell aliases are not supported")
+		}
+	}
+	return nil
+}
+
+// Check validates an alias and every alias it expands through until a built-in.
+func Check(name string, aliases map[string]string, builtins map[string]bool) error {
+	seen := map[string]bool{}
+	for current := name; ; {
+		expansion, ok := aliases[current]
+		// A built-in always wins over an alias, except for the invoked name itself, which
+		// validate reports as a collision.
+		if !ok || (current != name && builtins[current]) {
+			if !builtins[current] {
+				return fmt.Errorf("alias %q targets unknown command %q", name, current)
+			}
+			return nil
+		}
+		if seen[current] {
+			return fmt.Errorf("alias cycle involving %q", current)
+		}
+		if len(seen) >= maxDepth {
+			return fmt.Errorf("alias nesting exceeds %d", maxDepth)
+		}
+		if err := validate(current, expansion, builtins); err != nil {
+			return err
+		}
+		seen[current] = true
+		// validate parsed this expansion without error.
+		words, _ := shellquote.Split(expansion)
+		current = words[0]
+	}
+}
+
+// Expand substitutes arguments without re-parsing or executing user input.
+// Only the invoked alias is checked, so one broken entry cannot block other commands.
+func Expand(args []string, aliases map[string]string, builtins map[string]bool) ([]string, error) {
+	if len(args) == 0 {
+		return args, nil
+	}
+	if _, ok := aliases[args[0]]; ok && !builtins[args[0]] {
+		if err := Check(args[0], aliases, builtins); err != nil {
+			return nil, err
+		}
+	}
+	for {
+		expansion, exists := aliases[args[0]]
+		if !exists || builtins[args[0]] {
+			return args, nil
+		}
+		// Check validated every expansion reachable from the invoked alias.
+		words, _ := shellquote.Split(expansion)
+		supplied := args[1:]
+		consumed := map[int]bool{}
+		for i, word := range words {
+			var substitutionErr error
+			words[i] = placeholder.ReplaceAllStringFunc(word, func(match string) string {
+				n, err := strconv.Atoi(match[1:])
+				if err != nil || n > len(supplied) {
+					substitutionErr = fmt.Errorf("alias requires argument %s", match)
+					return ""
+				}
+				consumed[n-1] = true
+				return supplied[n-1]
+			})
+			if substitutionErr != nil {
+				return nil, substitutionErr
+			}
+		}
+		for i, arg := range supplied {
+			if !consumed[i] {
+				words = append(words, arg)
+			}
+		}
+		args = words
+	}
+}
+
+// ExpandCompletion keeps the in-progress word last, as Cobra's completion protocol requires.
+// Fixed flags after a substituted argument must not become the completion prefix.
+func ExpandCompletion(args []string, definitions map[string]string, builtins map[string]bool) ([]string, error) {
+	if len(args) < 2 {
+		return append([]string{}, args...), nil
+	}
+	const marker = "\x00tea-completion\x00"
+	marked := append([]string{}, args...)
+	current := marked[len(marked)-1]
+	marked[len(marked)-1] = marker
+	expanded, err := Expand(marked, definitions, builtins)
+	if err != nil {
+		return nil, err
+	}
+	position := -1
+	for index, word := range expanded {
+		if strings.Contains(word, marker) {
+			if word != marker || position != -1 {
+				return nil, fmt.Errorf("completion of embedded or repeated placeholders is ambiguous")
+			}
+			position = index
+		}
+	}
+	if position == -1 {
+		return nil, fmt.Errorf("alias completion lost its current argument")
+	}
+	result := append([]string{}, expanded[:position]...)
+	result = append(result, expanded[position+1:]...)
+	return append(result, current), nil
+}

internal/aliases/aliases_test.go

@@ -0,0 +1,65 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package aliases
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestExpand(t *testing.T) {
+	builtins := map[string]bool{"issue": true, "pr": true}
+	for _, tc := range []struct {
+		expansion  string
+		args, want []string
+	}{
+		{"issue list --label 'good first issue'", []string{"bugs", "--limit", "5"}, []string{"issue", "list", "--label", "good first issue", "--limit", "5"}},
+		{"issue view $2", []string{"bugs", "left", "123", "--json"}, []string{"issue", "view", "123", "left", "--json"}},
+		{"issue create --title $1", []string{"bugs", "$(never execute)"}, []string{"issue", "create", "--title", "$(never execute)"}},
+		{"issue list --search '!wip'", []string{"bugs"}, []string{"issue", "list", "--search", "!wip"}},
+		{"issue list", []string{}, []string{}},
+	} {
+		got, err := Expand(tc.args, map[string]string{"bugs": tc.expansion}, builtins)
+		require.NoError(t, err)
+		require.Equal(t, tc.want, got)
+	}
+	got, err := Expand([]string{"a", "42"}, map[string]string{"a": "b", "b": "pr view"}, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"pr", "view", "42"}, got)
+}
+
+func TestRejectInvalidAliases(t *testing.T) {
+	builtins := map[string]bool{"issue": true}
+	for _, aliases := range []map[string]string{{"bad": ""}, {"bad": "issue '"}, {"bad": "a", "a": "bad"}, {"bad": "issue list | cat"}, {"bad": "issue list >> out"}, {"bad": "!echo hi"}, {"bad": "unknown list"}, {"bad": "$1 list"}} {
+		require.Error(t, Check("bad", aliases, builtins))
+		_, err := Expand([]string{"bad"}, aliases, builtins)
+		require.Error(t, err)
+	}
+	require.Error(t, Check("issue", map[string]string{"issue": "issue list"}, builtins))
+	_, err := Expand([]string{"a"}, map[string]string{"a": "issue view $1"}, builtins)
+	require.Error(t, err)
+	// A broken or colliding entry only fails when invoked; built-ins always win.
+	broken := map[string]string{"issue": "pr list", "bad": "unknown", "ok": "issue list"}
+	got, err := Expand([]string{"ok"}, broken, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"issue", "list"}, got)
+	got, err = Expand([]string{"issue", "view"}, broken, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"issue", "view"}, got)
+}
+
+func TestCompletionPreservesCurrentWordAfterFixedFlags(t *testing.T) {
+	definitions := map[string]string{"inspect": "pr view $1 --json number", "nested": "inspect $1"}
+	builtins := map[string]bool{"pr": true}
+	expanded, err := ExpandCompletion([]string{"nested", "7"}, definitions, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"pr", "view", "--json", "number", "7"}, expanded)
+	expanded, err = ExpandCompletion([]string{"inspect"}, definitions, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"inspect"}, expanded)
+	expanded, err = ExpandCompletion([]string{"nested", "7", "--j"}, definitions, builtins)
+	require.NoError(t, err)
+	require.Equal(t, []string{"pr", "view", "7", "--json", "number", "--j"}, expanded)
+}