fix: report unknown --json fields with the fields a command outputs

tea issue list --json number,titel failed with "accepts 0 arg(s),
received 1": a field list with an unknown name stayed a positional
argument. A field-shaped word after --json now binds to it unless the
command takes the word as an argument, and an unknown field lists the
available fields. --json= is a usage error instead of printing text.

--jq alone now implies --json, except on commands annotated
tea.rawjson that filter raw JSON themselves; -q is short for --jq and
-y for --yes. Fields are listed alphabetically, and terminal.JSONOutput
can indent and color JSON for a terminal.

Signed-off-by: bircni <bircni@icloud.com>

internal/app/app_test.go

@@ -5,6 +5,7 @@ package app
 
 import (
 	"context"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -12,6 +13,7 @@ import (
 	"testing"
 
 	"gitea.dev/tea/internal/clierr"
+	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/require"
 )
 
@@ -60,8 +62,8 @@ func TestCommandLineEdgeCases(t *testing.T) {
 	require.Equal(t, clierr.Usage, clierr.ExitCode(err))
 	require.ErrorContains(t, err, "did you mean issue?")
 	// A help flag supplied as a flag value must not bypass validation.
-	err = Execute(context.Background(), deps, []string{"config", "list", "--jq", ".", "--remote", "-h"})
-	require.ErrorContains(t, err, "--jq requires --json")
+	err = Execute(context.Background(), deps, []string{"config", "list", "--jq", ".[", "--remote", "-h"})
+	require.ErrorContains(t, err, "invalid --jq expression")
 	require.NoError(t, Execute(context.Background(), deps, []string{"--version"}))
 	require.NotContains(t, out.String(), "tea version")
 }
@@ -88,12 +90,17 @@ func TestJoinJSONFields(t *testing.T) {
 		{[]string{"repo", "clone", "--json", "alice/project"}, []string{"repo", "clone", "--json", "alice/project"}},
 		{[]string{"issue", "list", "--json", "--state", "open"}, []string{"issue", "list", "--json", "--state", "open"}},
 		{[]string{"search", "issues", "--", "--json", "id"}, []string{"search", "issues", "--", "--json", "id"}},
-		{[]string{"issue", "list", "--json", "Number"}, []string{"issue", "list", "--json", "Number"}},
 		{[]string{"search", "repo", "--json", "tea"}, []string{"search", "repo", "--json", "tea"}},
 		{[]string{"search", "issue", "--json", "bug"}, []string{"search", "issue", "--json", "bug"}},
 		{[]string{"repo", "clone", "--json", "project"}, []string{"repo", "clone", "--json", "project"}},
 		{[]string{"search", "repo", "--json", "name,url", "tea"}, []string{"search", "repo", "--json=name,url", "tea"}},
 		{[]string{"--json", "number", "my-alias"}, []string{"--json=number", "my-alias"}},
+		// A word that cannot be an argument is a misspelled field, which then lists the available ones.
+		{[]string{"issue", "list", "--json", "Number"}, []string{"issue", "list", "--json=Number"}},
+		{[]string{"issue", "list", "--json", "number,titel"}, []string{"issue", "list", "--json=number,titel"}},
+		{[]string{"run", "list", "--json", "workflow", "--limit", "5"}, []string{"run", "list", "--json=workflow", "--limit", "5"}},
+		{[]string{"issue", "view", "--json", "titel"}, []string{"issue", "view", "--json", "titel"}},
+		{[]string{"issue", "view", "5", "--json", "titel"}, []string{"issue", "view", "5", "--json=titel"}},
 	} {
 		deps, _, _ := testDeps(t)
 		require.Equal(t, tc.want, joinJSONFields(NewRoot(deps), tc.args), tc.args)
@@ -148,3 +155,40 @@ func TestSudoSendsHeaderAfterIdentityCheck(t *testing.T) {
 	requireUsageBeforeRequests(t, "--sudo cannot be used with auth commands", "auth", "status", "--sudo", "bob")
 	requireUsageBeforeRequests(t, "--sudo requires a username", "repo", "view", "--sudo", "")
 }
+
+func TestJSONFieldErrorsListAvailableFields(t *testing.T) {
+	requireUsageBeforeRequests(t, "unknown JSON field \"titel\"\navailable fields: assignees, author, body", "issue", "list", "--json", "number,titel")
+	requireUsageBeforeRequests(t, "unknown JSON field \"workflow\"\navailable fields: actor, attempt, branch", "run", "list", "--json", "workflow")
+	requireUsageBeforeRequests(t, "--json= needs field names; use --json alone for every field", "pr", "list", "--json=")
+	requireUsageBeforeRequests(t, "version prints text; --jq is not supported", "version", "--jq", ".")
+}
+
+func TestJQImpliesJSONAndShorthands(t *testing.T) {
+	server := newAuthenticatedServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[{"id":1,"username":"team","full_name":"Team"}]`))
+	}))
+	defer server.Close()
+	for _, args := range [][]string{{"org", "list", "--jq", ".[].name"}, {"org", "list", "-q", ".[].name"}, {"-q", ".[0].full_name", "org", "list"}} {
+		deps, out, _ := serverDeps(t, server.URL)
+		require.NoError(t, Execute(context.Background(), deps, args), args)
+		require.Contains(t, []string{"team\n", "Team\n"}, out.String(), args)
+	}
+	deps, _, _ := testDeps(t)
+	flags := NewRoot(deps).PersistentFlags()
+	require.Equal(t, "yes", flags.ShorthandLookup("y").Name)
+	require.Equal(t, "jq", flags.ShorthandLookup("q").Name)
+}
+
+func TestRawJSONCommandsKeepJQToThemselves(t *testing.T) {
+	deps, out, _ := testDeps(t)
+	root := NewRoot(deps)
+	root.AddCommand(&cobra.Command{Use: "raw", Annotations: map[string]string{"tea.text": "raw prints text", "tea.rawjson": "true"}, RunE: func(cmd *cobra.Command, _ []string) error {
+		_, err := fmt.Fprintf(cmd.OutOrStdout(), "json=%q", cmd.Flag("json").Value)
+		return err
+	}})
+	root.SetArgs([]string{"raw", "--jq", ".x"})
+	require.NoError(t, root.Execute())
+	require.Equal(t, `json=""`, out.String())
+	root.SetArgs([]string{"raw", "--json"})
+	require.ErrorContains(t, root.Execute(), "raw prints text; --json is not supported")
+}