Allow mutations in the api command (#419)

Author: alexjurkiewicz

internal/cmd/api/README.md

@@ -1,16 +1,16 @@
 # `spacectl api`
 
-`spacectl api` lets you run ad-hoc read-only GraphQL queries against the Spacelift API using your existing authentication.
+`spacectl api` lets you run ad-hoc GraphQL operations against the Spacelift API using your existing authentication.
 
-Mutations are not supported. For write operations, use the dedicated `spacectl` subcommands or the [Spacelift Terraform Provider](https://github.com/spacelift-io/terraform-provider-spacelift).
+The provided document is sent unchanged to the API, so queries and mutations are both supported.
 
 ## Usage
 
-Basic queries (bare field selections are wrapped in `query { ... }` automatically):
+Basic queries:
 
 ```bash
-spacectl api 'stacks { id name state }'
-spacectl api 'workerPools { id name workers { id } }'
+spacectl api '{ stacks { id name state } }'
+spacectl api '{ workerPools { id name workers { id } } }'
 ```
 
 Full query syntax:
@@ -25,12 +25,20 @@ With variables:
 spacectl api --variables '{"id":"my-stack"}' 'query($id: ID!) { stack(id: $id) { id name } }'
 ```
 
+Mutations:
+
+```bash
+spacectl api 'mutation { stackDelete(id: "my-stack") { id } }'
+spacectl api 'mutation DeleteStack($id: ID!) { stackDelete(id: $id) { id } }' --variables '{"id":"my-stack"}'
+```
+
 From a file or stdin:
 
 ```bash
 spacectl api < query.graphql
 spacectl api --variables '{"id":"my-stack"}' < query.graphql
 cat query.graphql | spacectl api
+spacectl api < mutation.graphql
 ```
 
 ## Output

internal/cmd/api/api.go

@@ -44,8 +44,8 @@ func Command() cmd.Command {
 				Command: &cli.Command{
 					Before:      authenticated.Ensure,
 					Flags:       []cli.Flag{flagVariables, flagRaw, flagSchema},
-					Description: "Pass a read-only GraphQL query as a positional argument, or pipe via stdin.\nBare field selections are wrapped as query { ... } automatically.\nMutations and subscriptions are not supported. Read more: https://github.com/spacelift-io/spacectl/tree/main/internal/cmd/api/README.md",
-					ArgsUsage:   "[query]",
+					Description: "Pass a GraphQL document as a positional argument, or pipe via stdin.\nThe provided document is sent unchanged to the Spacelift GraphQL API. Read more: https://github.com/spacelift-io/spacectl/tree/main/internal/cmd/api/README.md",
+					ArgsUsage:   "[document]",
 					Action:      run,
 				},
 			},
@@ -58,25 +58,16 @@ type apiRequest struct {
 	Variables map[string]any `json:"variables,omitempty"`
 }
 
-var errMutationsNotAllowed = errors.New("mutations are not supported by spacectl api")
-
 func run(ctx context.Context, cliCmd *cli.Command) error {
 	var query string
 	if cliCmd.Bool(flagSchema.Name) {
 		query = introspectionQuery
 	} else {
 		var err error
-		query, err = resolveQuery(cliCmd)
+		query, err = resolveDocument(cliCmd)
 		if err != nil {
 			return err
 		}
-
-		// This is a hopefull check but it's enough for most cases.
-		// We could in theory allow mutations, but spacectl is not a great tool for
-		// that so we do not.
-		if isMutation(query) {
-			return errMutationsNotAllowed
-		}
 	}
 
 	variables, err := parseVariables(cliCmd.String(flagVariables.Name))
@@ -124,9 +115,9 @@ func run(ctx context.Context, cliCmd *cli.Command) error {
 	return nil
 }
 
-func resolveQuery(cliCmd *cli.Command) (string, error) {
+func resolveDocument(cliCmd *cli.Command) (string, error) {
 	if args := strings.TrimSpace(strings.Join(cliCmd.Args().Slice(), " ")); args != "" {
-		return normalizeQuery(args), nil
+		return args, nil
 	}
 
 	if !isatty.IsTerminal(os.Stdin.Fd()) {
@@ -139,7 +130,7 @@ func resolveQuery(cliCmd *cli.Command) (string, error) {
 		}
 	}
 
-	return "", errors.New("query required: pass as argument or pipe via stdin")
+	return "", errors.New("document required: pass as argument or pipe via stdin")
 }
 
 func parseVariables(raw string) (map[string]any, error) {
@@ -153,19 +144,6 @@ func parseVariables(raw string) (map[string]any, error) {
 	return obj, nil
 }
 
-func normalizeQuery(query string) string {
-	lower := strings.ToLower(query)
-	if strings.HasPrefix(lower, "query") || strings.HasPrefix(lower, "mutation") || strings.HasPrefix(lower, "subscription") || strings.HasPrefix(query, "{") {
-		return query
-	}
-	return "query { " + query + " }"
-}
-
-func isMutation(query string) bool {
-	lower := strings.ToLower(strings.TrimSpace(query))
-	return strings.HasPrefix(lower, "mutation")
-}
-
 func graphqlErrors(body []byte) string {
 	var resp struct {
 		Errors []struct {

internal/cmd/api/api_test.go

@@ -1,25 +1,6 @@
 package api
 
-import (
-	"testing"
-)
-
-func TestNormalizeQuery(t *testing.T) {
-	tests := []struct {
-		in, want string
-	}{
-		{"{ viewer { id } }", "{ viewer { id } }"},
-		{"query { viewer { id } }", "query { viewer { id } }"},
-		{"mutation { deleteStack(id: \"x\") { id } }", "mutation { deleteStack(id: \"x\") { id } }"},
-		{"subscription { runs { id } }", "subscription { runs { id } }"},
-		{"stacks { id name }", "query { stacks { id name } }"},
-	}
-	for _, tc := range tests {
-		if got := normalizeQuery(tc.in); got != tc.want {
-			t.Errorf("normalizeQuery(%q) = %q, want %q", tc.in, got, tc.want)
-		}
-	}
-}
+import "testing"
 
 func TestParseVariables(t *testing.T) {
 	if v, err := parseVariables(""); v != nil || err != nil {
@@ -52,24 +33,6 @@ func TestGraphqlErrors(t *testing.T) {
 	}
 }
 
-func TestIsMutation(t *testing.T) {
-	tests := []struct {
-		in   string
-		want bool
-	}{
-		{"mutation { deleteStack(id: \"x\") { id } }", true},
-		{"  Mutation { foo }", true},
-		{"query { stacks { id } }", false},
-		{"{ viewer { id } }", false},
-		{"stacks { id }", false},
-	}
-	for _, tc := range tests {
-		if got := isMutation(tc.in); got != tc.want {
-			t.Errorf("isMutation(%q) = %v, want %v", tc.in, got, tc.want)
-		}
-	}
-}
-
 func TestTruncate(t *testing.T) {
 	if s := truncate([]byte("short"), 100); s != "short" {
 		t.Errorf("got %q", s)