fix(notification): word --all confirmations and flag values clearly

notification mark-read --all asked "Marked as read all … ?"; each command now asks in its own words, such as "Pin all unread notifications in your inbox?". The status and type filters list their values in help, the api parameter flags read like gh's, and tea auth login --help aligns its method list.

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

internal/app/api.go

@@ -277,9 +277,9 @@ func (a *application) apiCommand() *cobra.Command {
 	}}
 	cmd.Flags().StringVarP(&method, "method", "X", "GET", "HTTP `method`")
 	cmd.Flags().StringVar(&input, "input", "", "Read the request body from a `file`, or stdin with -")
-	cmd.Flags().StringArrayVarP(&headerValues, "header", "H", nil, "Add a request header: `\"Name: value\"`")
+	cmd.Flags().StringArrayVarP(&headerValues, "header", "H", nil, "Add an HTTP request header in `name:value` format")
-	cmd.Flags().StringArrayVarP(&raw, "raw-field", "f", nil, "Add a string field: `name=value`")
+	cmd.Flags().StringArrayVarP(&raw, "raw-field", "f", nil, "Add a string parameter in `key=value` format")
-	cmd.Flags().StringArrayVarP(&typed, "field", "F", nil, "Add a typed field: `name=value`; @FILE or @- reads a file or stdin")
+	cmd.Flags().StringArrayVarP(&typed, "field", "F", nil, "Add a typed parameter in `key=value` format; @FILE or @- reads a file or stdin")
 	cmd.Flags().StringVar(&output, "output-file", "", "Write the complete response to a new `file`")
 	cmd.Flags().BoolVarP(&include, "include", "i", false, "Print the response status and headers to stderr")
 	cmd.Flags().BoolVar(&verbose, "verbose", false, "Print the request and the response status and headers to stderr")

internal/app/auth.go

@@ -130,10 +130,11 @@ On a terminal without a method flag, tea asks for the instance, how to log in, w
 keep the token and whether git should use tea for the instance. Otherwise choose one
 method:
 
-  --with-token           read an access token from stdin, or ask for it on a terminal
+  --with-token             read an access token from stdin, or ask for it on a terminal
-  --oauth, --web         authorize tea in a web browser
+  --oauth, --web           authorize tea in a web browser
-  --ssh-key FILE         sign requests with an SSH private key
+  --ssh-key FILE           sign requests with an SSH private key
-  --ssh-agent-key, --ssh-agent-principal   sign requests with a key in ssh-agent
+  --ssh-agent-key FP       sign requests with the key of fingerprint FP in ssh-agent
+  --ssh-agent-principal P  sign requests with the ssh-agent certificate of principal P
 
 Create a token on the instance under Settings > Applications. Logging in to an account
 that tea already has replaces its stored credential after a confirmation (or with --yes).`,

internal/app/notifications.go

@@ -48,12 +48,12 @@ list shows identify notification threads; they are not issue numbers.`}
 	}
 	group.AddCommand(a.notificationListCommand(scope), a.notificationWatchCommand(scope), a.notificationViewCommand(scope))
 	for _, mark := range []struct {
-		verb, status, filter, short, done, example string
+		verb, status, filter, short, ask, done, example string
 	}{
-		{"mark-read", "read", "unread", "Mark notifications as read", "Marked %s as read", "$ tea notification mark-read 28\n# Everything in one repository\n$ tea notification mark-read --all -R alice/project"},
+		{"mark-read", "read", "unread", "Mark notifications as read", "Mark all %s as read?", "Marked %s as read", "$ tea notification mark-read 28\n# Everything in one repository\n$ tea notification mark-read --all -R alice/project"},
-		{"mark-unread", "unread", "read", "Mark notifications as unread", "Marked %s as unread", "$ tea notification mark-unread 28 26"},
+		{"mark-unread", "unread", "read", "Mark notifications as unread", "Mark all %s as unread?", "Marked %s as unread", "$ tea notification mark-unread 28 26"},
-		{"pin", "pinned", "unread", "Pin notifications", "Pinned %s", "$ tea notification pin 28"},
+		{"pin", "pinned", "unread", "Pin notifications", "Pin all %s?", "Pinned %s", "$ tea notification pin 28"},
-		{"unpin", "read", "pinned", "Unpin notifications", "Unpinned %s", "$ tea notification unpin 28\n# Unpin everything\n$ tea notification unpin --all"},
+		{"unpin", "read", "pinned", "Unpin notifications", "Unpin all %s?", "Unpinned %s", "$ tea notification unpin 28\n# Unpin everything\n$ tea notification unpin --all"},
 	} {
 		var all bool
 		var filters []string
@@ -100,7 +100,7 @@ list shows identify notification threads; they are not issue numbers.`}
 				}
 				what := notificationsWith(filters) + " " + s.where
 				if settings, err := a.deps.Settings.Load(); err == nil && a.policy(settings).CanPrompt(a.deps.Streams) {
-					if err := a.confirmAction(cmd, terminal.Confirmation{Prompt: fmt.Sprintf("%s all %s?", strings.Replace(mark.done, " %s", "", 1), what), DefaultYes: true}); err != nil {
+					if err := a.confirmAction(cmd, terminal.Confirmation{Prompt: fmt.Sprintf(mark.ask, what), DefaultYes: true}); err != nil {
 						return err
 					}
 				}
@@ -120,7 +120,7 @@ list shows identify notification threads; they are not issue numbers.`}
 			},
 		}
 		command.Flags().BoolVar(&all, "all", false, "Apply to every notification that matches --status in the scope")
-		command.Flags().StringSliceVar(&filters, "status", nil, "With --all, the statuses to change")
+		command.Flags().StringSliceVar(&filters, "status", nil, "With --all, the statuses to change: unread, read, pinned")
 		enumValues(command, "status", "unread", "read", "pinned")
 		command.Flags().StringVar(&before, "before", "", "With --all, only notifications updated before a date, timestamp, or duration such as 1h")
 		group.AddCommand(command)
@@ -131,9 +131,9 @@ list shows identify notification threads; they are not issue numbers.`}
 // notificationFilters registers the list filters of list and watch.
 func notificationFilters(cmd *cobra.Command, opts *services.NotificationOptions, updated *timeRange) {
 	pageFlags(cmd, &opts.Limit, &opts.Page)
-	cmd.Flags().StringSliceVar(&opts.Statuses, "status", []string{"unread", "pinned"}, "Only notifications with these statuses")
+	cmd.Flags().StringSliceVar(&opts.Statuses, "status", []string{"unread", "pinned"}, "Only notifications with these statuses: unread, read, pinned")
 	enumValues(cmd, "status", "unread", "read", "pinned")
-	cmd.Flags().StringSliceVar(&opts.Types, "type", nil, "Only notifications about these subjects")
+	cmd.Flags().StringSliceVar(&opts.Types, "type", nil, "Only notifications about these subjects: issue, pull, commit, repository")
 	enumValues(cmd, "type", "issue", "pull", "commit", "repository")
 	updated.register(cmd, "since", "Only notifications updated since a date, timestamp, or duration such as 24h", "before", "Only notifications updated before a date, timestamp, or duration such as 1h")
 }

internal/app/notifications_test.go

@@ -132,6 +132,11 @@ func TestNotificationMutationsReportWhatChanged(t *testing.T) {
 		require.Equal(t, tc.want, withoutANSI(diagnostics.String()), tc.args)
 	}
 	require.Equal(t, []string{"pinned", "read", "read", "all read"}, marks)
+	prompt := &scriptedPrompter{accept: true}
+	deps.Prompter, deps.Streams.InTTY, deps.Streams.ErrTTY = prompt, true, true
+	require.NoError(t, Execute(context.Background(), deps, []string{"notification", "pin", "--all"}))
+	require.Equal(t, []string{"Pin all unread notifications in your inbox?"}, prompt.confirmations)
+	deps.Streams.InTTY, deps.Streams.ErrTTY = false, false
 	marks = nil
 	out.Reset()
 	require.NoError(t, Execute(context.Background(), deps, []string{"notification", "view", "12"}))