fix(api): distinct error code for templated-dispatch refusal (#196) (#238)

DispatchAction's templated-params gate previously returned the generic
ErrValidationFailed code. The web client maps errors by structured
ErrorDetail.code (not message text) to localized UI strings, so the
shared 'validation_failed' code couldn't be distinguished from a
hundred other validation paths.

Adds ErrTemplatedDispatchRefused = "templated_dispatch_refused" and
swaps it into the gate. The CodeFailedPrecondition + human message
stay the same; only the structured code changes.

Test extended to assert the structured code via connect.Error.Details
\xe2\x80\x94 a future refactor that drops the structured detail will break the
test instead of silently breaking the web error mapping.

Refs #196 (web error mapping prep).

Author: PaulDotterer

internal/api/action_dispatch.go

@@ -170,7 +170,7 @@ func (h *ActionHandler) DispatchAction(ctx context.Context, req *connect.Request
 			fmt.Sprintf("failed to marshal action params for template scan: %v", err))
 	}
 	if template.HasReference(string(paramsJSONForScan)) {
-		return nil, apiErrorCtx(ctx, ErrValidationFailed, connect.CodeFailedPrecondition,
+		return nil, apiErrorCtx(ctx, ErrTemplatedDispatchRefused, connect.CodeFailedPrecondition,
 			"this action contains templated parameters ({{ var.NAME }}) and cannot be dispatched ad-hoc to a single device. "+
 				"Variables are resolved from device-group / user-group memberships at agent sync time. "+
 				"Assign the action to a device-group or user-group instead of running it directly.")

internal/api/dispatch_validation_test.go

@@ -1,6 +1,7 @@
 package api_test
 
 import (
+	"errors"
 	"log/slog"
 	"testing"
 
@@ -213,6 +214,22 @@ func TestDispatchAction_TemplatedParamsRefused(t *testing.T) {
 		"templated params on ad-hoc dispatch MUST surface FailedPrecondition — anything else lets literal {{ var.X }} reach the agent verbatim")
 	assert.Contains(t, err.Error(), "templated parameters",
 		"error message must explain that variables are group-only and the action should be assigned to a group instead")
+
+	// The web client reads the structured ErrorDetail code (not the
+	// human-readable message) to map the failure to a localized
+	// "assign to a group instead" UI message. Pin the code here so a
+	// future refactor that drops the structured detail breaks the test
+	// instead of silently breaking the web error mapping.
+	var connectErr *connect.Error
+	require.True(t, errors.As(err, &connectErr))
+	details := connectErr.Details()
+	require.NotEmpty(t, details, "templated-dispatch refusal MUST carry the structured ErrorDetail — the web client maps by code, not by message")
+	val, vErr := details[0].Value()
+	require.NoError(t, vErr)
+	detail, ok := val.(*pm.ErrorDetail)
+	require.True(t, ok, "first detail must be ErrorDetail; got %T", val)
+	assert.Equal(t, api.ErrTemplatedDispatchRefused, detail.Code,
+		"error code MUST be templated_dispatch_refused — the web client switches on this exact string")
 }
 
 // TestDispatchInstantAction_PreconditionNoTaskQueue pins the

internal/api/errors.go

@@ -109,6 +109,15 @@ const (
 	ErrValidationFailed = "validation_failed"
 	ErrInvalidPageToken = "invalid_page_token"
 	ErrInvalidQuery     = "invalid_query"
+
+	// ErrTemplatedDispatchRefused is returned when an operator tries to
+	// dispatch an action whose params contain `{{ var.NAME }}` references
+	// directly to a single device (DispatchAction / DispatchToMultiple /
+	// DispatchActionSet / etc.). Variables resolve only via device-group
+	// or user-group memberships at agent SyncActions time; the ad-hoc
+	// dispatch path has no group context. Web maps this code to a
+	// "assign to a group instead" UI message. See #196.
+	ErrTemplatedDispatchRefused = "templated_dispatch_refused"
 )
 
 // Internal error code (generic).