feat(cli): add coder task resume command (#22066)

Complements https://github.com/coder/coder/pull/22012 by adding a `coder task resume` command

cli/task.go

@@ -18,6 +18,7 @@ func (r *RootCmd) tasksCommand() *serpent.Command {
 			r.taskList(),
 			r.taskLogs(),
 			r.taskPause(),
+			r.taskResume(),
 			r.taskSend(),
 			r.taskStatus(),
 		},

cli/task_resume.go

@@ -0,0 +1,95 @@
+package cli
+
+import (
+	"fmt"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/pretty"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) taskResume() *serpent.Command {
+	var noWait bool
+
+	cmd := &serpent.Command{
+		Use:   "resume <task>",
+		Short: "Resume a task",
+		Long: FormatExamples(
+			Example{
+				Description: "Resume a task by name",
+				Command:     "coder task resume my-task",
+			},
+			Example{
+				Description: "Resume another user's task",
+				Command:     "coder task resume alice/my-task",
+			},
+			Example{
+				Description: "Resume a task without confirmation",
+				Command:     "coder task resume my-task --yes",
+			},
+		),
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(1),
+		),
+		Options: serpent.OptionSet{
+			{
+				Flag:        "no-wait",
+				Description: "Return immediately after resuming the task.",
+				Value:       serpent.BoolOf(&noWait),
+			},
+			cliui.SkipPromptOption(),
+		},
+		Handler: func(inv *serpent.Invocation) error {
+			ctx := inv.Context()
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
+			task, err := client.TaskByIdentifier(ctx, inv.Args[0])
+			if err != nil {
+				return xerrors.Errorf("resolve task %q: %w", inv.Args[0], err)
+			}
+
+			display := fmt.Sprintf("%s/%s", task.OwnerName, task.Name)
+
+			if task.Status == codersdk.TaskStatusError || task.Status == codersdk.TaskStatusUnknown {
+				return xerrors.Errorf("task %q is in %s state and cannot be resumed; check the workspace build logs and agent status for details", display, task.Status)
+			} else if task.Status != codersdk.TaskStatusPaused {
+				return xerrors.Errorf("task %q cannot be resumed (current status: %s)", display, task.Status)
+			}
+
+			_, err = cliui.Prompt(inv, cliui.PromptOptions{
+				Text:      fmt.Sprintf("Resume task %s?", pretty.Sprint(cliui.DefaultStyles.Code, display)),
+				IsConfirm: true,
+				Default:   cliui.ConfirmNo,
+			})
+			if err != nil {
+				return err
+			}
+
+			resp, err := client.ResumeTask(ctx, task.OwnerName, task.ID)
+			if err != nil {
+				return xerrors.Errorf("resume task %q: %w", display, err)
+			} else if resp.WorkspaceBuild == nil {
+				return xerrors.Errorf("resume task %q: no workspace build returned", display)
+			}
+
+			if noWait {
+				_, _ = fmt.Fprintf(inv.Stdout, "Resuming task %q in the background.\n", cliui.Keyword(display))
+				return nil
+			}
+
+			if err = cliui.WorkspaceBuild(ctx, inv.Stdout, client, resp.WorkspaceBuild.ID); err != nil {
+				return xerrors.Errorf("watch resume build for task %q: %w", display, err)
+			}
+
+			_, _ = fmt.Fprintf(inv.Stdout, "\nThe %s task has been resumed.\n", cliui.Keyword(display))
+			return nil
+		},
+	}
+	return cmd
+}

cli/task_resume_test.go

@@ -0,0 +1,183 @@
+package cli_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestExpTaskResume(t *testing.T) {
+	t.Parallel()
+
+	// pauseTask is a helper that pauses a task and waits for the stop
+	// build to complete.
+	pauseTask := func(ctx context.Context, t *testing.T, client *codersdk.Client, task codersdk.Task) {
+		t.Helper()
+
+		pauseResp, err := client.PauseTask(ctx, task.OwnerName, task.ID)
+		require.NoError(t, err)
+		require.NotNil(t, pauseResp.WorkspaceBuild)
+		coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, pauseResp.WorkspaceBuild.ID)
+	}
+
+	t.Run("WithYesFlag", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A paused task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		_, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+		pauseTask(setupCtx, t, userClient, task)
+
+		// When: We attempt to resume the task
+		inv, root := clitest.New(t, "task", "resume", task.Name, "--yes")
+		output := clitest.Capture(inv)
+		clitest.SetupConfig(t, userClient, root)
+
+		// Then: We expect the task to be resumed
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+		require.Contains(t, output.Stdout(), "has been resumed")
+
+		updated, err := userClient.TaskByIdentifier(ctx, task.Name)
+		require.NoError(t, err)
+		require.Equal(t, codersdk.TaskStatusInitializing, updated.Status)
+	})
+
+	// OtherUserTask verifies that an admin can resume a task owned by
+	// another user using the "owner/name" identifier format.
+	t.Run("OtherUserTask", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A different user's paused task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		adminClient, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+		pauseTask(setupCtx, t, userClient, task)
+
+		// When: We attempt to resume their task
+		identifier := fmt.Sprintf("%s/%s", task.OwnerName, task.Name)
+		inv, root := clitest.New(t, "task", "resume", identifier, "--yes")
+		output := clitest.Capture(inv)
+		clitest.SetupConfig(t, adminClient, root)
+
+		// Then: We expect the task to be resumed
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+		require.Contains(t, output.Stdout(), "has been resumed")
+
+		updated, err := adminClient.TaskByIdentifier(ctx, identifier)
+		require.NoError(t, err)
+		require.Equal(t, codersdk.TaskStatusInitializing, updated.Status)
+	})
+
+	t.Run("NoWait", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A paused task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		_, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+		pauseTask(setupCtx, t, userClient, task)
+
+		// When: We attempt to resume the task (and specify no wait)
+		inv, root := clitest.New(t, "task", "resume", task.Name, "--yes", "--no-wait")
+		output := clitest.Capture(inv)
+		clitest.SetupConfig(t, userClient, root)
+
+		// Then: We expect the task to be resumed in the background
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+		require.Contains(t, output.Stdout(), "in the background")
+
+		// And: The task to eventually be resumed
+		require.True(t, task.WorkspaceID.Valid, "task should have a workspace ID")
+		ws := coderdtest.MustWorkspace(t, userClient, task.WorkspaceID.UUID)
+		coderdtest.AwaitWorkspaceBuildJobCompleted(t, userClient, ws.LatestBuild.ID)
+
+		updated, err := userClient.TaskByIdentifier(ctx, task.Name)
+		require.NoError(t, err)
+		require.Equal(t, codersdk.TaskStatusInitializing, updated.Status)
+	})
+
+	t.Run("PromptConfirm", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A paused task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		_, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+		pauseTask(setupCtx, t, userClient, task)
+
+		// When: We attempt to resume the task
+		inv, root := clitest.New(t, "task", "resume", task.Name)
+		clitest.SetupConfig(t, userClient, root)
+
+		// And: We confirm we want to resume the task
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		inv = inv.WithContext(ctx)
+		pty := ptytest.New(t).Attach(inv)
+		w := clitest.StartWithWaiter(t, inv)
+		pty.ExpectMatchContext(ctx, "Resume task")
+		pty.WriteLine("yes")
+
+		// Then: We expect the task to be resumed
+		pty.ExpectMatchContext(ctx, "has been resumed")
+		require.NoError(t, w.Wait())
+
+		updated, err := userClient.TaskByIdentifier(ctx, task.Name)
+		require.NoError(t, err)
+		require.Equal(t, codersdk.TaskStatusInitializing, updated.Status)
+	})
+
+	t.Run("PromptDecline", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A paused task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		_, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+		pauseTask(setupCtx, t, userClient, task)
+
+		// When: We attempt to resume the task
+		inv, root := clitest.New(t, "task", "resume", task.Name)
+		clitest.SetupConfig(t, userClient, root)
+
+		// But: Say no at the confirmation screen
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		inv = inv.WithContext(ctx)
+		pty := ptytest.New(t).Attach(inv)
+		w := clitest.StartWithWaiter(t, inv)
+		pty.ExpectMatchContext(ctx, "Resume task")
+		pty.WriteLine("no")
+		require.Error(t, w.Wait())
+
+		// Then: We expect the task to still be paused
+		updated, err := userClient.TaskByIdentifier(ctx, task.Name)
+		require.NoError(t, err)
+		require.Equal(t, codersdk.TaskStatusPaused, updated.Status)
+	})
+
+	t.Run("TaskNotPaused", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A running task
+		setupCtx := testutil.Context(t, testutil.WaitLong)
+		_, userClient, task := setupCLITaskTest(setupCtx, t, nil)
+
+		// When: We attempt to resume the task that is not paused
+		inv, root := clitest.New(t, "task", "resume", task.Name, "--yes")
+		clitest.SetupConfig(t, userClient, root)
+
+		// Then: We expect to get an error that the task is not paused
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		err := inv.WithContext(ctx).Run()
+		require.ErrorContains(t, err, "cannot be resumed")
+	})
+}

cli/task_test.go

@@ -137,6 +137,23 @@ func Test_Tasks(t *testing.T) {
 				require.Equal(t, codersdk.TaskStatusPaused, task.Status, "task should be paused")
 			},
 		},
+		{
+			name:    "resume task",
+			cmdArgs: []string{"task", "resume", taskName, "--yes"},
+			assertFn: func(stdout string, userClient *codersdk.Client) {
+				require.Contains(t, stdout, "has been resumed", "resume output should confirm task was resumed")
+			},
+		},
+		{
+			name:    "get task status after resume",
+			cmdArgs: []string{"task", "status", taskName, "--output", "json"},
+			assertFn: func(stdout string, userClient *codersdk.Client) {
+				var task codersdk.Task
+				require.NoError(t, json.NewDecoder(strings.NewReader(stdout)).Decode(&task), "should unmarshal task status")
+				require.Equal(t, taskName, task.Name, "task name should match")
+				require.Equal(t, codersdk.TaskStatusInitializing, task.Status, "task should be initializing after resume")
+			},
+		},
 		{
 			name:    "delete task",
 			cmdArgs: []string{"task", "delete", taskName, "--yes"},

cli/testdata/coder_task_--help.golden

@@ -13,6 +13,7 @@ SUBCOMMANDS:
     list      List tasks
     logs      Show a task's logs
     pause     Pause a task
+    resume    Resume a task
     send      Send input to a task
     status    Show the status of a task.
 

cli/testdata/coder_task_resume_--help.golden

@@ -0,0 +1,28 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder task resume [flags] <task>
+
+  Resume a task
+
+    - Resume a task by name:
+  
+       $ coder task resume my-task
+  
+    - Resume another user's task:
+  
+       $ coder task resume alice/my-task
+  
+    - Resume a task without confirmation:
+  
+       $ coder task resume my-task --yes
+
+OPTIONS:
+      --no-wait bool
+          Return immediately after resuming the task.
+
+  -y, --yes bool
+          Bypass confirmation prompts.
+
+———
+Run `coder --help` for a list of global options.

docs/manifest.json

@@ -2019,6 +2019,11 @@
 							"description": "Pause a task",
 							"path": "reference/cli/task_pause.md"
 						},
+						{
+							"title": "task resume",
+							"description": "Resume a task",
+							"path": "reference/cli/task_resume.md"
+						},
 						{
 							"title": "task send",
 							"description": "Send input to a task",

docs/reference/cli/task.md

@@ -22,5 +22,6 @@ coder task
 | [<code>list</code>](./task_list.md)     | List tasks                 |
 | [<code>logs</code>](./task_logs.md)     | Show a task's logs         |
 | [<code>pause</code>](./task_pause.md)   | Pause a task               |
+| [<code>resume</code>](./task_resume.md) | Resume a task              |
 | [<code>send</code>](./task_send.md)     | Send input to a task       |
 | [<code>status</code>](./task_status.md) | Show the status of a task. |

docs/reference/cli/task_resume.md

@@ -0,0 +1,44 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+# task resume
+
+Resume a task
+
+## Usage
+
+```console
+coder task resume [flags] <task>
+```
+
+## Description
+
+```console
+  - Resume a task by name:
+
+     $ coder task resume my-task
+
+  - Resume another user's task:
+
+     $ coder task resume alice/my-task
+
+  - Resume a task without confirmation:
+
+     $ coder task resume my-task --yes
+```
+
+## Options
+
+### --no-wait
+
+|      |                   |
+|------|-------------------|
+| Type | <code>bool</code> |
+
+Return immediately after resuming the task.
+
+### -y, --yes
+
+|      |                   |
+|------|-------------------|
+| Type | <code>bool</code> |
+
+Bypass confirmation prompts.