Implement notification subcommands (#389)

- [x] enhance notification listing
  - add `--states` and `--type` filters
  - toggle per-user or per-repo listing via `--mine` flag
  - print more fields
- [x] add subcommands to mark notifications as read, unread, pinned, unpinned. operates on
  - all notifications matching the `--state` and `--mine` filter flags, or
  - a notification specified by ID.
- [ ] ~~add a `--fields` flag for notifications listing.~~ *not in this PR*
- [ ] ~~interactive mode~~ *not in this PR*. this would go well together with #324

fixes #243, fixes #155

based on initial work in #283 and #386, but opening a new PR for @6543 to review as I changed quite a lot

---

### ⚠️ breaking ⚠️
- `tea notifications --all` has moved to `tea notifications --mine`
- `tea notifications` now only works with the context of a remote repo.
  To run this outside of a local git dir, run either `tea n --mine` or `tea n --repo <my/repo>`

---

Co-authored-by: Karl Heinz Marbaise <kama@soebes.de>
Co-authored-by: 6543 <6543@obermui.de>
Co-authored-by: Norwin Roosen <git@nroo.de>
Reviewed-on: https://gitea.com/gitea/tea/pulls/389
Reviewed-by: 6543 <6543@obermui.de>
Reviewed-by: Alexey 〒erentyev <axifive@noreply.gitea.io>
Co-authored-by: Norwin <noerw@noreply.gitea.io>
Co-committed-by: Norwin <noerw@noreply.gitea.io>

cmd/flags/csvflag.go

@@ -0,0 +1,49 @@
+// Copyright 2021 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package flags
+
+import (
+	"fmt"
+	"strings"
+
+	"code.gitea.io/tea/modules/utils"
+	"github.com/urfave/cli/v2"
+)
+
+// CsvFlag is a wrapper around cli.StringFlag, with an added GetValues() method
+// to retrieve comma separated string values as a slice.
+type CsvFlag struct {
+	cli.StringFlag
+	AvailableFields []string
+}
+
+// NewCsvFlag creates a CsvFlag, while setting its usage string and default values
+func NewCsvFlag(name, usage string, aliases, availableValues, defaults []string) *CsvFlag {
+	return &CsvFlag{
+		AvailableFields: availableValues,
+		StringFlag: cli.StringFlag{
+			Name:    name,
+			Aliases: aliases,
+			Value:   strings.Join(defaults, ","),
+			Usage: fmt.Sprintf(`Comma-separated list of %s. Available values:
+			%s
+		`, usage, strings.Join(availableValues, ",")),
+		},
+	}
+}
+
+// GetValues returns the value of the flag, parsed as a commaseparated list
+func (f CsvFlag) GetValues(ctx *cli.Context) ([]string, error) {
+	val := ctx.String(f.Name)
+	selection := strings.Split(val, ",")
+	if f.AvailableFields != nil && val != "" {
+		for _, field := range selection {
+			if !utils.Contains(f.AvailableFields, field) {
+				return nil, fmt.Errorf("Invalid field '%s'", field)
+			}
+		}
+	}
+	return selection, nil
+}

cmd/flags/flags.go

@@ -11,7 +11,6 @@ import (
 	"code.gitea.io/sdk/gitea"
 	"code.gitea.io/tea/modules/context"
 	"code.gitea.io/tea/modules/task"
-	"code.gitea.io/tea/modules/utils"
 
 	"github.com/araddon/dateparse"
 	"github.com/urfave/cli/v2"
@@ -101,6 +100,27 @@ var IssuePRFlags = append([]cli.Flag{
 	&PaginationLimitFlag,
 }, AllDefaultFlags...)
 
+// NotificationFlags defines flags that should be available on notifications.
+var NotificationFlags = append([]cli.Flag{
+	NotificationStateFlag,
+	&cli.BoolFlag{
+		Name:    "mine",
+		Aliases: []string{"m"},
+		Usage:   "Show notifications across all your repositories instead of the current repository only",
+	},
+	&PaginationPageFlag,
+	&PaginationLimitFlag,
+}, AllDefaultFlags...)
+
+// NotificationStateFlag is a csv flag applied to all notification subcommands as filter
+var NotificationStateFlag = NewCsvFlag(
+	"states",
+	"notification states to filter by",
+	[]string{"s"},
+	[]string{"pinned", "unread", "read"},
+	[]string{"unread", "pinned"},
+)
+
 // IssuePREditFlags defines flags for properties of issues and PRs
 var IssuePREditFlags = append([]cli.Flag{
 	&cli.StringFlag{
@@ -178,28 +198,7 @@ func GetIssuePREditFlags(ctx *context.TeaContext) (*gitea.CreateIssueOption, err
 }
 
 // FieldsFlag generates a flag selecting printable fields.
-// To retrieve the value, use GetFields()
+// To retrieve the value, use f.GetValues()
-func FieldsFlag(availableFields, defaultFields []string) *cli.StringFlag {
+func FieldsFlag(availableFields, defaultFields []string) *CsvFlag {
-	return &cli.StringFlag{
+	return NewCsvFlag("fields", "fields to print", []string{"f"}, availableFields, defaultFields)
-		Name:    "fields",
-		Aliases: []string{"f"},
-		Usage: fmt.Sprintf(`Comma-separated list of fields to print. Available values:
-			%s
-		`, strings.Join(availableFields, ",")),
-		Value: strings.Join(defaultFields, ","),
-	}
-}
-
-// GetFields parses the values provided in a fields flag, and
-// optionally validates against valid values.
-func GetFields(ctx *cli.Context, validFields []string) ([]string, error) {
-	selection := strings.Split(ctx.String("fields"), ",")
-	if validFields != nil {
-		for _, field := range selection {
-			if !utils.Contains(validFields, field) {
-				return nil, fmt.Errorf("Invalid field '%s'", field)
-			}
-		}
-	}
-	return selection, nil
 }

cmd/issues/list.go

@@ -13,6 +13,10 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+var issueFieldsFlag = flags.FieldsFlag(print.IssueFields, []string{
+	"index", "title", "state", "author", "milestone", "labels",
+})
+
 // CmdIssuesList represents a sub command of issues to list issues
 var CmdIssuesList = cli.Command{
 	Name:        "list",
@@ -20,11 +24,7 @@ var CmdIssuesList = cli.Command{
 	Usage:       "List issues of the repository",
 	Description: `List issues of the repository`,
 	Action:      RunIssuesList,
-	Flags: append([]cli.Flag{
+	Flags:       append([]cli.Flag{issueFieldsFlag}, flags.IssuePRFlags...),
-		flags.FieldsFlag(print.IssueFields, []string{
-			"index", "title", "state", "author", "milestone", "labels",
-		}),
-	}, flags.IssuePRFlags...),
 }
 
 // RunIssuesList list issues
@@ -52,7 +52,7 @@ func RunIssuesList(cmd *cli.Context) error {
 		return err
 	}
 
-	fields, err := flags.GetFields(cmd, print.IssueFields)
+	fields, err := issueFieldsFlag.GetValues(cmd)
 	if err != nil {
 		return err
 	}

cmd/milestones/issues.go

@@ -16,6 +16,10 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+var msIssuesFieldsFlag = flags.FieldsFlag(print.IssueFields, []string{
+	"index", "kind", "title", "state", "updated", "labels",
+})
+
 // CmdMilestonesIssues represents a sub command of milestones to manage issue/pull of an milestone
 var CmdMilestonesIssues = cli.Command{
 	Name:        "issues",
@@ -40,9 +44,7 @@ var CmdMilestonesIssues = cli.Command{
 		},
 		&flags.PaginationPageFlag,
 		&flags.PaginationLimitFlag,
-		flags.FieldsFlag(print.IssueFields, []string{
+		msIssuesFieldsFlag,
-			"index", "kind", "title", "state", "updated", "labels",
-		}),
 	}, flags.AllDefaultFlags...),
 }
 
@@ -110,7 +112,7 @@ func runMilestoneIssueList(cmd *cli.Context) error {
 		return err
 	}
 
-	fields, err := flags.GetFields(cmd, print.IssueFields)
+	fields, err := msIssuesFieldsFlag.GetValues(cmd)
 	if err != nil {
 		return err
 	}

cmd/notifications.go

@@ -5,11 +5,8 @@
 package cmd
 
 import (
-	"code.gitea.io/tea/cmd/flags"
+	"code.gitea.io/tea/cmd/notifications"
-	"code.gitea.io/tea/modules/context"
-	"code.gitea.io/tea/modules/print"
 
-	"code.gitea.io/sdk/gitea"
 	"github.com/urfave/cli/v2"
 )
 
@@ -19,65 +16,14 @@ var CmdNotifications = cli.Command{
 	Aliases:     []string{"notification", "n"},
 	Category:    catHelpers,
 	Usage:       "Show notifications",
-	Description: "Show notifications, by default based of the current repo and unread one",
+	Description: "Show notifications, by default based on the current repo if available",
-	Action:      runNotifications,
+	Action:      notifications.RunNotificationsList,
-	Flags: append([]cli.Flag{
+	Subcommands: []*cli.Command{
-		&cli.BoolFlag{
+		&notifications.CmdNotificationsList,
-			Name:    "all",
+		&notifications.CmdNotificationsMarkRead,
-			Aliases: []string{"a"},
+		&notifications.CmdNotificationsMarkUnread,
-			Usage:   "show all notifications of related gitea instance",
+		&notifications.CmdNotificationsMarkPinned,
-		},
+		&notifications.CmdNotificationsUnpin,
-		&cli.BoolFlag{
+	},
-			Name:    "read",
+	Flags: notifications.CmdNotificationsList.Flags,
-			Aliases: []string{"rd"},
-			Usage:   "show read notifications instead unread",
-		},
-		&cli.BoolFlag{
-			Name:    "pinned",
-			Aliases: []string{"pd"},
-			Usage:   "show pinned notifications instead unread",
-		},
-		&flags.PaginationPageFlag,
-		&flags.PaginationLimitFlag,
-	}, flags.AllDefaultFlags...),
-}
-
-func runNotifications(cmd *cli.Context) error {
-	var news []*gitea.NotificationThread
-	var err error
-
-	ctx := context.InitCommand(cmd)
-	client := ctx.Login.Client()
-
-	listOpts := ctx.GetListOptions()
-	if listOpts.Page == 0 {
-		listOpts.Page = 1
-	}
-
-	var status []gitea.NotifyStatus
-	if ctx.Bool("read") {
-		status = []gitea.NotifyStatus{gitea.NotifyStatusRead}
-	}
-	if ctx.Bool("pinned") {
-		status = append(status, gitea.NotifyStatusPinned)
-	}
-
-	if ctx.Bool("all") {
-		news, _, err = client.ListNotifications(gitea.ListNotificationOptions{
-			ListOptions: listOpts,
-			Status:      status,
-		})
-	} else {
-		ctx.Ensure(context.CtxRequirement{RemoteRepo: true})
-		news, _, err = client.ListRepoNotifications(ctx.Owner, ctx.Repo, gitea.ListNotificationOptions{
-			ListOptions: listOpts,
-			Status:      status,
-		})
-	}
-	if err != nil {
-		return err
-	}
-
-	print.NotificationsList(news, ctx.Output, ctx.Bool("all"))
-	return nil
 }

cmd/notifications/list.go

@@ -0,0 +1,89 @@
+// Copyright 2021 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package notifications
+
+import (
+	"log"
+
+	"code.gitea.io/tea/cmd/flags"
+	"code.gitea.io/tea/modules/context"
+	"code.gitea.io/tea/modules/print"
+
+	"code.gitea.io/sdk/gitea"
+	"github.com/urfave/cli/v2"
+)
+
+var notifTypeFlag = flags.NewCsvFlag("types", "subject types to filter by", []string{"t"},
+	[]string{"issue", "pull", "repository", "commit"}, nil)
+
+// CmdNotificationsList represents a sub command of notifications to list notifications
+var CmdNotificationsList = cli.Command{
+	Name:        "ls",
+	Aliases:     []string{"list"},
+	Usage:       "List notifications",
+	Description: `List notifications`,
+	Action:      RunNotificationsList,
+	Flags:       append([]cli.Flag{notifTypeFlag}, flags.NotificationFlags...),
+}
+
+// RunNotificationsList list notifications
+func RunNotificationsList(ctx *cli.Context) error {
+	var states []gitea.NotifyStatus
+	statesStr, err := flags.NotificationStateFlag.GetValues(ctx)
+	if err != nil {
+		return err
+	}
+	for _, s := range statesStr {
+		states = append(states, gitea.NotifyStatus(s))
+	}
+
+	var types []gitea.NotifySubjectType
+	typesStr, err := notifTypeFlag.GetValues(ctx)
+	if err != nil {
+		return err
+	}
+	for _, t := range typesStr {
+		types = append(types, gitea.NotifySubjectType(t))
+	}
+
+	return listNotifications(ctx, states, types)
+}
+
+// listNotifications will get the notifications based on status and subject type
+func listNotifications(cmd *cli.Context, status []gitea.NotifyStatus, subjects []gitea.NotifySubjectType) error {
+	var news []*gitea.NotificationThread
+	var err error
+
+	ctx := context.InitCommand(cmd)
+	client := ctx.Login.Client()
+	all := ctx.Bool("mine")
+
+	// This enforces pagination (see https://github.com/go-gitea/gitea/issues/16733)
+	listOpts := ctx.GetListOptions()
+	if listOpts.Page == 0 {
+		listOpts.Page = 1
+	}
+
+	if all {
+		news, _, err = client.ListNotifications(gitea.ListNotificationOptions{
+			ListOptions:  listOpts,
+			Status:       status,
+			SubjectTypes: subjects,
+		})
+	} else {
+		ctx.Ensure(context.CtxRequirement{RemoteRepo: true})
+		news, _, err = client.ListRepoNotifications(ctx.Owner, ctx.Repo, gitea.ListNotificationOptions{
+			ListOptions:  listOpts,
+			Status:       status,
+			SubjectTypes: subjects,
+		})
+	}
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	print.NotificationsList(news, ctx.Output, all)
+	return nil
+}

cmd/notifications/mark_as.go

@@ -0,0 +1,139 @@
+// Copyright 2021 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package notifications
+
+import (
+	"fmt"
+
+	"code.gitea.io/sdk/gitea"
+	"code.gitea.io/tea/cmd/flags"
+	"code.gitea.io/tea/modules/context"
+	"code.gitea.io/tea/modules/utils"
+	"github.com/urfave/cli/v2"
+)
+
+// CmdNotificationsMarkRead represents a sub command of notifications to list read notifications
+var CmdNotificationsMarkRead = cli.Command{
+	Name:        "read",
+	Aliases:     []string{"r"},
+	Usage:       "Mark all filtered or a specific notification as read",
+	Description: "Mark all filtered or a specific notification as read",
+	ArgsUsage:   "[all | <notification id>]",
+	Flags:       flags.NotificationFlags,
+	Action: func(ctx *cli.Context) error {
+		cmd := context.InitCommand(ctx)
+		filter, err := flags.NotificationStateFlag.GetValues(ctx)
+		if err != nil {
+			return err
+		}
+		if !flags.NotificationStateFlag.IsSet() {
+			filter = []string{string(gitea.NotifyStatusUnread)}
+		}
+		return markNotificationAs(cmd, filter, gitea.NotifyStatusRead)
+	},
+}
+
+// CmdNotificationsMarkUnread will mark notifications as unread.
+var CmdNotificationsMarkUnread = cli.Command{
+	Name:        "unread",
+	Aliases:     []string{"u"},
+	Usage:       "Mark all filtered or a specific notification as unread",
+	Description: "Mark all filtered or a specific notification as unread",
+	ArgsUsage:   "[all | <notification id>]",
+	Flags:       flags.NotificationFlags,
+	Action: func(ctx *cli.Context) error {
+		cmd := context.InitCommand(ctx)
+		filter, err := flags.NotificationStateFlag.GetValues(ctx)
+		if err != nil {
+			return err
+		}
+		if !flags.NotificationStateFlag.IsSet() {
+			filter = []string{string(gitea.NotifyStatusRead)}
+		}
+		return markNotificationAs(cmd, filter, gitea.NotifyStatusUnread)
+	},
+}
+
+// CmdNotificationsMarkPinned will mark notifications as unread.
+var CmdNotificationsMarkPinned = cli.Command{
+	Name:        "pin",
+	Aliases:     []string{"p"},
+	Usage:       "Mark all filtered or a specific notification as pinned",
+	Description: "Mark all filtered or a specific notification as pinned",
+	ArgsUsage:   "[all | <notification id>]",
+	Flags:       flags.NotificationFlags,
+	Action: func(ctx *cli.Context) error {
+		cmd := context.InitCommand(ctx)
+		filter, err := flags.NotificationStateFlag.GetValues(ctx)
+		if err != nil {
+			return err
+		}
+		if !flags.NotificationStateFlag.IsSet() {
+			filter = []string{string(gitea.NotifyStatusUnread)}
+		}
+		return markNotificationAs(cmd, filter, gitea.NotifyStatusPinned)
+	},
+}
+
+// CmdNotificationsUnpin will mark pinned notifications as unread.
+var CmdNotificationsUnpin = cli.Command{
+	Name:        "unpin",
+	Usage:       "Unpin all pinned or a specific notification",
+	Description: "Marks all pinned or a specific notification as read",
+	ArgsUsage:   "[all | <notification id>]",
+	Flags:       flags.NotificationFlags,
+	Action: func(ctx *cli.Context) error {
+		cmd := context.InitCommand(ctx)
+		filter := []string{string(gitea.NotifyStatusPinned)}
+		// NOTE: we implicitly mark it as read, to match web UI semantics. marking as unread might be more useful?
+		return markNotificationAs(cmd, filter, gitea.NotifyStatusRead)
+	},
+}
+
+func markNotificationAs(cmd *context.TeaContext, filterStates []string, targetState gitea.NotifyStatus) (err error) {
+	client := cmd.Login.Client()
+	subject := cmd.Args().First()
+	allRepos := cmd.Bool("mine")
+
+	states := []gitea.NotifyStatus{}
+	for _, s := range filterStates {
+		states = append(states, gitea.NotifyStatus(s))
+	}
+
+	switch subject {
+	case "", "all":
+		opts := gitea.MarkNotificationOptions{Status: states, ToStatus: targetState}
+
+		if allRepos {
+			_, err = client.ReadNotifications(opts)
+		} else {
+			cmd.Ensure(context.CtxRequirement{RemoteRepo: true})
+			_, err = client.ReadRepoNotifications(cmd.Owner, cmd.Repo, opts)
+		}
+
+		// TODO: print all affected notification subject URLs
+		// (not supported by API currently, https://github.com/go-gitea/gitea/issues/16797)
+
+	default:
+		id, err := utils.ArgToIndex(subject)
+		if err != nil {
+			return err
+		}
+		_, err = client.ReadNotification(id, targetState)
+		if err != nil {
+			return err
+		}
+
+		n, _, err := client.GetNotification(id)
+		if err != nil {
+			return err
+		}
+		// FIXME: this is an API URL, we want to display a web ui link..
+		fmt.Println(n.Subject.URL)
+		return nil
+	}
+
+	return err
+}

cmd/repos/list.go

@@ -13,6 +13,10 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+var repoFieldsFlag = flags.FieldsFlag(print.RepoFields, []string{
+	"owner", "name", "type", "ssh",
+})
+
 // CmdReposListFlags contains all flags needed for repo listing
 var CmdReposListFlags = append([]cli.Flag{
 	&cli.BoolFlag{
@@ -27,9 +31,7 @@ var CmdReposListFlags = append([]cli.Flag{
 		Required: false,
 		Usage:    "List your starred repos instead",
 	},
-	flags.FieldsFlag(print.RepoFields, []string{
+	repoFieldsFlag,
-		"owner", "name", "type", "ssh",
-	}),
 	&typeFilterFlag,
 	&flags.PaginationPageFlag,
 	&flags.PaginationLimitFlag,
@@ -82,7 +84,7 @@ func RunReposList(cmd *cli.Context) error {
 		reposFiltered = filterReposByType(rps, typeFilter)
 	}
 
-	fields, err := flags.GetFields(cmd, print.RepoFields)
+	fields, err := repoFieldsFlag.GetValues(cmd)
 	if err != nil {
 		return err
 	}

cmd/repos/search.go

@@ -50,9 +50,7 @@ var CmdReposSearch = cli.Command{
 			Required: false,
 			Usage:    "Filter archived repos (true|false)",
 		},
-		flags.FieldsFlag(print.RepoFields, []string{
+		repoFieldsFlag,
-			"owner", "name", "type", "ssh",
-		}),
 		&flags.PaginationPageFlag,
 		&flags.PaginationLimitFlag,
 	}, flags.LoginOutputFlags...),
@@ -125,7 +123,7 @@ func runReposSearch(cmd *cli.Context) error {
 		return err
 	}
 
-	fields, err := flags.GetFields(cmd, nil)
+	fields, err := repoFieldsFlag.GetValues(cmd)
 	if err != nil {
 		return err
 	}

cmd/times/list.go

@@ -19,6 +19,17 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+// NOTE: not using NewCsvFlag, as we don't want an alias & default value.
+var timeFieldsFlag = &flags.CsvFlag{
+	AvailableFields: print.TrackedTimeFields,
+	StringFlag: cli.StringFlag{
+		Name: "fields",
+		Usage: fmt.Sprintf(`Comma-separated list of fields to print. Available values:
+	%s
+`, strings.Join(print.TrackedTimeFields, ",")),
+	},
+}
+
 // CmdTrackedTimesList represents a sub command of times to list them
 var CmdTrackedTimesList = cli.Command{
 	Name:    "list",
@@ -53,12 +64,7 @@ Depending on your permissions on the repository, only your own tracked times mig
 			Aliases: []string{"m"},
 			Usage:   "Show all times tracked by you across all repositories (overrides command arguments)",
 		},
-		&cli.StringFlag{
+		timeFieldsFlag,
-			Name: "fields",
-			Usage: fmt.Sprintf(`Comma-separated list of fields to print. Available values:
-			%s
-		`, strings.Join(print.TrackedTimeFields, ",")),
-		},
 	}, flags.AllDefaultFlags...),
 }
 
@@ -116,7 +122,7 @@ func RunTimesList(cmd *cli.Context) error {
 	}
 
 	if ctx.IsSet("fields") {
-		if fields, err = flags.GetFields(cmd, print.TrackedTimeFields); err != nil {
+		if fields, err = timeFieldsFlag.GetValues(cmd); err != nil {
 			return err
 		}
 	}

modules/print/notification.go

@@ -5,6 +5,7 @@
 package print
 
 import (
+	"fmt"
 	"strings"
 
 	"code.gitea.io/sdk/gitea"
@@ -13,6 +14,8 @@ import (
 // NotificationsList prints a listing of notification threads
 func NotificationsList(news []*gitea.NotificationThread, output string, showRepository bool) {
 	headers := []string{
+		"ID",
+		"Status",
 		"Type",
 		"State",
 		"Index",
@@ -39,7 +42,21 @@ func NotificationsList(news []*gitea.NotificationThread, output string, showRepo
 			index = "#" + index
 		}
 
-		item := []string{string(n.Subject.Type), string(n.Subject.State), index, n.Subject.Title}
+		status := "read"
+		if n.Pinned {
+			status = "pinned"
+		} else if n.Unread {
+			status = "unread"
+		}
+
+		item := []string{
+			fmt.Sprint(n.ID),
+			status,
+			string(n.Subject.Type),
+			string(n.Subject.State),
+			index,
+			n.Subject.Title,
+		}
 		if showRepository {
 			item = append(item, n.Repository.FullName)
 		}