feat: emit X-Wherobots-Client header with command name (WBC-182)

Set an advisory X-Wherobots-Client header on outgoing API requests so
the backend can attribute traffic to the CLI and the specific command
that generated it. The CLI is an ORIGIN client and emits a single hop:

    client=cli;ver=<buildVersion>;cmd=<command>

The command is the operation's CommandPath joined with "." (e.g.
job-runs.list); the ;cmd= field is omitted when CommandPath is empty.
Values are sanitized so commas and semicolons can never break the hop
grammar. The header is advisory only and never affects auth.

The build version reaches the executor package via an exported
executor.Version var (default "dev"), which main.go sets from the
ldflags-injected buildVersion. This avoids an import cycle and keeps
version wiring in one place. A pure buildClientHeader helper renders
the value for testability.

Claude-Session: https://claude.ai/code/session_01QP5saxNQTUTJpMRRxZXhzR

Author: ClayMav

internal/executor/request.go

@@ -15,11 +15,47 @@ import (
 	"wherobots/cli/internal/spec"
 )
 
+// Version identifies the CLI build for the advisory X-Wherobots-Client header.
+// main.go overwrites it with the ldflags-injected build version; the "dev"
+// default keeps local and test builds working without wiring.
+var Version = "dev"
+
 type QueryPair struct {
 	Key   string
 	Value string
 }
 
+// clientHeaderName is the ordered, append-only client-identification header.
+// The CLI is an ORIGIN client, so it emits a single hop and never appends to
+// an existing value. The header is advisory only and never affects auth.
+const clientHeaderName = "X-Wherobots-Client"
+
+// clientHeaderSanitizer strips characters that would break the hop grammar
+// (commas separate hops, semicolons separate fields) so they can never appear
+// inside a value.
+var clientHeaderSanitizer = strings.NewReplacer(",", "_", ";", "_")
+
+// buildClientHeader renders this CLI's single origin hop:
+//
+//	client=cli;ver=<version>;cmd=<command>
+//
+// The cmd field is omitted when command is empty. Values are sanitized so no
+// comma or semicolon leaks into the grammar. An empty version falls back to
+// "dev" to match the package default.
+func buildClientHeader(version, command string) string {
+	if version == "" {
+		version = "dev"
+	}
+	var b strings.Builder
+	b.WriteString("client=cli;ver=")
+	b.WriteString(clientHeaderSanitizer.Replace(version))
+	if command != "" {
+		b.WriteString(";cmd=")
+		b.WriteString(clientHeaderSanitizer.Replace(command))
+	}
+	return b.String()
+}
+
 type HTTPError struct {
 	StatusCode int
 	Body       []byte
@@ -243,6 +279,7 @@ func BuildRequest(
 		req.Header.Set("Content-Type", contentType)
 	}
 	req.Header.Set("x-api-key", cfg.APIKey)
+	req.Header.Set(clientHeaderName, buildClientHeader(Version, strings.Join(op.CommandPath, ".")))
 
 	return req, nil
 }

internal/executor/request_test.go

@@ -184,6 +184,94 @@ func TestBuildRequestInjectsPathQueryBodyAndAuth(t *testing.T) {
 	}
 }
 
+func TestBuildRequestInjectsWherobotsClientHeader(t *testing.T) {
+	// Not parallel: mutates the package-level Version var.
+	prev := Version
+	Version = "1.2.3"
+	t.Cleanup(func() { Version = prev })
+
+	cfg := config.Config{APIKey: "abc123"}
+	runtimeSpec := &spec.RuntimeSpec{BaseURL: "https://api.example.com"}
+	op := &spec.Operation{
+		Method:      "GET",
+		Path:        "/job-runs",
+		CommandPath: []string{"job-runs", "list"},
+	}
+
+	req, err := BuildRequest(context.Background(), cfg, runtimeSpec, op, nil, nil, "")
+	if err != nil {
+		t.Fatalf("BuildRequest() error = %v", err)
+	}
+	if got, want := req.Header.Get("X-Wherobots-Client"), "client=cli;ver=1.2.3;cmd=job-runs.list"; got != want {
+		t.Fatalf("X-Wherobots-Client = %q, want %q", got, want)
+	}
+}
+
+func TestBuildRequestWherobotsClientHeaderOmitsCommandWhenEmpty(t *testing.T) {
+	// Not parallel: mutates the package-level Version var.
+	prev := Version
+	Version = "4.5.6"
+	t.Cleanup(func() { Version = prev })
+
+	cfg := config.Config{APIKey: "abc123"}
+	runtimeSpec := &spec.RuntimeSpec{BaseURL: "https://api.example.com"}
+	op := &spec.Operation{Method: "GET", Path: "/job-runs"}
+
+	req, err := BuildRequest(context.Background(), cfg, runtimeSpec, op, nil, nil, "")
+	if err != nil {
+		t.Fatalf("BuildRequest() error = %v", err)
+	}
+	if got, want := req.Header.Get("X-Wherobots-Client"), "client=cli;ver=4.5.6"; got != want {
+		t.Fatalf("X-Wherobots-Client = %q, want %q", got, want)
+	}
+}
+
+func TestBuildClientHeader(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		version string
+		command string
+		want    string
+	}{
+		{
+			name:    "version and command",
+			version: "1.2.3",
+			command: "job-runs.list",
+			want:    "client=cli;ver=1.2.3;cmd=job-runs.list",
+		},
+		{
+			name:    "empty command omits cmd",
+			version: "1.2.3",
+			command: "",
+			want:    "client=cli;ver=1.2.3",
+		},
+		{
+			name:    "empty version falls back to dev",
+			version: "",
+			command: "job-runs.list",
+			want:    "client=cli;ver=dev;cmd=job-runs.list",
+		},
+		{
+			name:    "sanitizes separators out of values",
+			version: "1,2;3",
+			command: "a;b,c.list",
+			want:    "client=cli;ver=1_2_3;cmd=a_b_c.list",
+		},
+	}
+
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			if got := buildClientHeader(tc.version, tc.command); got != tc.want {
+				t.Fatalf("buildClientHeader(%q, %q) = %q, want %q", tc.version, tc.command, got, tc.want)
+			}
+		})
+	}
+}
+
 func TestBuildRequestMissingRequiredQueryReturnsError(t *testing.T) {
 	t.Parallel()
 

main.go

@@ -8,6 +8,7 @@ import (
 
 	"wherobots/cli/internal/commands"
 	"wherobots/cli/internal/config"
+	"wherobots/cli/internal/executor"
 	"wherobots/cli/internal/spec"
 	"wherobots/cli/internal/version"
 )
@@ -26,6 +27,11 @@ func main() {
 }
 
 func run(ctx context.Context) error {
+	// Surface the build version to the executor so outgoing requests carry the
+	// advisory X-Wherobots-Client header. Set here (not via ldflags directly on
+	// the executor var) to keep version wiring in one place.
+	executor.Version = buildVersion
+
 	// Start a background update check early so it runs in parallel with setup.
 	updateCh := version.CheckInBackground(ctx, buildVersion)