From 52045e47cdde91b297223140e47b67b68bb89213 Mon Sep 17 00:00:00 2001
From: Clay McGinnis <github@clay.sh>
Date: Tue, 8 Sep 2026 10:51:04 -0700
Subject: [PATCH] fix(jobs): explain missing positional arguments (WBC-266)

---
 internal/commands/jobs.go      | 30 ++++++++++++++---------
 internal/commands/jobs_test.go | 45 ++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 12 deletions(-)

diff --git a/internal/commands/jobs.go b/internal/commands/jobs.go
index 158af71..ee9deef 100644
--- a/internal/commands/jobs.go
+++ b/internal/commands/jobs.go
@@ -158,6 +158,21 @@ func findOperation(runtimeSpec *spec.RuntimeSpec, method, path string) *spec.Ope
 	return nil
 }
 
+func requiredJobArgument(name, example string) cobra.PositionalArgs {
+	return func(cmd *cobra.Command, args []string) error {
+		if len(args) == 1 && strings.TrimSpace(args[0]) != "" {
+			return nil
+		}
+
+		message := fmt.Sprintf("missing required argument <%s>", name)
+		if len(args) > 1 {
+			message = fmt.Sprintf("expected one <%s> argument, received %d", name, len(args))
+		}
+		return fmt.Errorf("%s\n\nUsage: %s\nExample: %s %s\nRun '%s --help' for options.",
+			message, cmd.UseLine(), cmd.CommandPath(), example, cmd.CommandPath())
+	}
+}
+
 func (r *jobsRunner) newCreateCommand() *cobra.Command {
 	var (
 		name         string
@@ -178,14 +193,11 @@ func (r *jobsRunner) newCreateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "create <script>",
 		Short:         "Create a job run",
-		Args:          cobra.ExactArgs(1),
+		Args:          requiredJobArgument("script", "s3://my-bucket/job.py"),
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			script := strings.TrimSpace(args[0])
-			if script == "" {
-				return fmt.Errorf("script is required")
-			}
 			if output != outputText && output != outputJSON {
 				return fmt.Errorf("invalid --output %q (expected text|json)", output)
 			}
@@ -689,14 +701,11 @@ func (r *jobsRunner) newLogsCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "logs <run-id>",
 		Short:         "Fetch or stream run logs",
-		Args:          cobra.ExactArgs(1),
+		Args:          requiredJobArgument("run-id", "run-123"),
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			runID := strings.TrimSpace(args[0])
-			if runID == "" {
-				return fmt.Errorf("run-id is required")
-			}
 			if interval <= 0 {
 				return fmt.Errorf("--interval must be greater than 0")
 			}
@@ -872,14 +881,11 @@ func (r *jobsRunner) newMetricsCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "metrics <run-id>",
 		Short:         "Display instant metrics for a job run",
-		Args:          cobra.ExactArgs(1),
+		Args:          requiredJobArgument("run-id", "run-123"),
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			runID := strings.TrimSpace(args[0])
-			if runID == "" {
-				return fmt.Errorf("run-id is required")
-			}
 			if output != outputText && output != outputJSON {
 				return fmt.Errorf("invalid --output %q (expected text|json)", output)
 			}
diff --git a/internal/commands/jobs_test.go b/internal/commands/jobs_test.go
index a786a08..a656e6e 100644
--- a/internal/commands/jobs_test.go
+++ b/internal/commands/jobs_test.go
@@ -1384,3 +1384,48 @@ func TestJobsRunUploadURLStorageSourceErrorWithoutOverrideOmitsGuidance(t *testi
 		t.Fatalf("did not expect override guidance when no --upload-path was given, got:\n%s", got)
 	}
 }
+
+func TestJobsArgumentErrors(t *testing.T) {
+	t.Parallel()
+	for _, command := range []struct {
+		name     string
+		argument string
+		example  string
+	}{
+		{"create", "script", "s3://my-bucket/job.py"},
+		{"logs", "run-id", "run-123"},
+		{"metrics", "run-id", "run-123"},
+	} {
+		for _, input := range []struct {
+			name    string
+			args    []string
+			message string
+		}{
+			{"missing", nil, "missing required argument <" + command.argument + ">"},
+			{"blank", []string{"  "}, "missing required argument <" + command.argument + ">"},
+			{"extra", []string{"first", "second"}, "expected one <" + command.argument + "> argument, received 2"},
+		} {
+			t.Run(command.name+"/"+input.name, func(t *testing.T) {
+				root := buildJobsTestRoot("http://127.0.0.1:1")
+				root.SetOut(io.Discard)
+				root.SetErr(io.Discard)
+				root.SetArgs(append([]string{"job-runs", command.name}, input.args...))
+				err := root.Execute()
+				if err == nil {
+					t.Fatal("expected argument error")
+				}
+				path := "wherobots job-runs " + command.name
+				for _, want := range []string{
+					input.message,
+					"Usage: " + path + " <" + command.argument + "> [flags]",
+					"Example: " + path + " " + command.example,
+					"Run '" + path + " --help' for options.",
+				} {
+					if !strings.Contains(err.Error(), want) {
+						t.Errorf("error = %q, want %q", err, want)
+					}
+				}
+			})
+		}
+	}
+}