c/snap: add --format json to snap tasks (#17017)

* Revert "o/h/ctlcmd: remove incomplete async snapctl functionality prior to 2.76 (#17076)"

This reverts commit 40008b5.

* o/h/ctlcmd: fix is-ready return codes

* t/main/snapctl-is-ready: remove spread test, test in snapctl async branch covers this feature

* daemon: fix TestStateChange

* daemon: fix TestStateChange unit test

* c/snap: add --format json to snap tasks

* t/main/snap-tasks: create spread test to ensure --format json produces valid JSON

* cmd/snap, t/main/snap-tasks: fix formatting, specify --format options

* fixup! cmd/snap, t/main/snap-tasks: fix formatting, specify --format options

* c/snap, t/m/snap-tasks: fix spread test jq check, make tasks fail with invalid format

* c/snap, t/main/snap-tasks: fix spread test, add formatMixin

* t/main/snap-tasks: fix file name issue for task.yaml

* c/snap, t/m/snap-tasks: fix spread test failure, fix formatting in cmd

Author: Rnfudge02

cmd/snap/cmd_changes.go

@@ -25,7 +25,6 @@ import (
 	"sort"
 
 	"github.com/jessevdk/go-flags"
-
 	"github.com/snapcore/snapd/client"
 	"github.com/snapcore/snapd/i18n"
 )
@@ -51,14 +50,15 @@ type cmdChanges struct {
 type cmdTasks struct {
 	timeMixin
 	changeIDMixin
+	formatMixin
 }
 
 func init() {
 	addCommand("changes", shortChangesHelp, longChangesHelp,
 		func() flags.Commander { return &cmdChanges{} }, timeDescs, nil)
 	addCommand("tasks", shortTasksHelp, longTasksHelp,
 		func() flags.Commander { return &cmdTasks{} },
-		changeIDMixinOptDesc.also(timeDescs),
+		changeIDMixinOptDesc.also(timeDescs).also(formatArgsHelp),
 		changeIDMixinArgDesc).alias = "change"
 }
 
@@ -160,6 +160,11 @@ func (c *cmdTasks) showChange(chid string) error {
 		return err
 	}
 
+	if c.Format != "text" && c.Format != "" {
+		err = c.formatNonText(chg)
+		return err
+	}
+
 	w := tabWriter()
 
 	fmt.Fprint(w, i18n.G("Status\tSpawn\tReady\tSummary\n"))

cmd/snap/cmd_changes_test.go

@@ -20,12 +20,14 @@
 package main_test
 
 import (
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"strings"
 
 	"gopkg.in/check.v1"
 
+	"github.com/snapcore/snapd/client"
 	snap "github.com/snapcore/snapd/cmd/snap"
 )
 
@@ -232,6 +234,36 @@ Doing +2016-04-21T01:02:03Z +2016-04-21T01:02:04Z +some summary \(50.00%\)
 	c.Check(s.Stderr(), check.Equals, "")
 }
 
+func (s *SnapSuite) TestTasksJSON(c *check.C) {
+	s.RedirectClientToTestServer(func(w http.ResponseWriter, r *http.Request) {
+		c.Check(r.Method, check.Equals, "GET")
+		c.Check(r.URL.Path, check.Equals, "/v2/changes/42")
+		fmt.Fprintln(w, mockChangeJSON)
+	})
+
+	rest, err := snap.Parser(snap.Client()).ParseArgs([]string{"tasks", "--format=json", "42"})
+	c.Assert(err, check.IsNil)
+	c.Assert(rest, check.DeepEquals, []string{})
+
+	var chg client.Change
+	c.Assert(json.Unmarshal([]byte(s.Stdout()), &chg), check.IsNil)
+	c.Check(chg.ID, check.Equals, "uno")
+	c.Check(chg.Kind, check.Equals, "foo")
+	c.Check(chg.Summary, check.Equals, "...")
+	c.Check(chg.Status, check.Equals, "Do")
+	c.Check(chg.Ready, check.Equals, false)
+	c.Assert(chg.Tasks, check.HasLen, 1)
+	c.Check(chg.Tasks[0].Kind, check.Equals, "bar")
+	c.Check(chg.Tasks[0].Summary, check.Equals, "some summary")
+	c.Check(chg.Tasks[0].Status, check.Equals, "Do")
+
+	// If format (which has defined values) gets passed an invalid value, the parser wraps it in `'.
+	_, err = snap.Parser(snap.Client()).ParseArgs([]string{"tasks", "--format=", "42"})
+	c.Assert(err, check.ErrorMatches, ".*Invalid value `' for option `--format'. Allowed values are: .* or json")
+	_, err = snap.Parser(snap.Client()).ParseArgs([]string{"tasks", "--format=random", "42"})
+	c.Assert(err, check.ErrorMatches, ".*Invalid value `random' for option `--format'. Allowed values are: .* or json")
+}
+
 func (s *SnapSuite) TestNoChanges(c *check.C) {
 	n := 0
 	s.RedirectClientToTestServer(func(w http.ResponseWriter, r *http.Request) {

cmd/snap/main.go

@@ -20,6 +20,7 @@
 package main
 
 import (
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -215,6 +216,28 @@ func (ch *clientMixin) setClient(cli *client.Client) {
 	ch.client = cli
 }
 
+type formatMixin struct {
+	//lint:ignore SA5008 "choice" tag is intentionally duplicated
+	Format string `long:"format" default:"text" choice:"text" choice:"json"`
+}
+
+var formatArgsHelp = map[string]string{
+	"format": i18n.G("Output format"),
+}
+
+func (mx formatMixin) formatNonText(result any) error {
+	switch mx.Format {
+	case "json":
+		data, err := json.Marshal(result)
+		if err != nil {
+			return err
+		}
+		fmt.Fprintln(Stdout, string(data))
+		return nil
+	}
+	panic(fmt.Sprintf("internal error: invalid format option %q", mx.Format))
+}
+
 func firstNonOptionIsRun() bool {
 	if len(os.Args) < 2 {
 		return false

tests/main/snap-tasks/task.yaml

@@ -0,0 +1,16 @@
+summary: Check that `snap tasks` works as expected.
+
+details: |
+    Verifies that the command 'snap tasks' properly lists the tasks
+    associated with a change. Also check the error scenarios.
+
+execute: |
+    echo "Install snap to trigger a change"
+    "$TESTSTOOLS"/snaps-state install-local test-snapd-sh-core24
+
+    echo "Get the change ID for the install operation"
+    CHANGE_ID=$(snap changes | grep "Install \"test-snapd-sh-core24\" snap" | awk '{print $1}')
+
+    # Check that valid JSON output is produced for the change, and that it contains the expected task with the expected state.
+    echo "Check that 'snap tasks' lists the task for the change (and accepts the --format option)"
+    snap tasks --format json "$CHANGE_ID" | gojq -e '.tasks | all(.status == "Done" or .status == "done")'