Add Key Value output contracts for action commands (#474)

Adds action metadata for commands that need it:
  - `delete`: `{ "data": ..., "meta": { "deleted": true|false, "message": "..." } }`
  - `suspend`: `{ "data": ..., "meta": { "suspended": true|false, "message": "..." } }`

Basically, define and fully control the JSON output for these commands instead of passing along raw API payloads.

---

These commands all operate on a single existing KV, so they can use the same flattened item contract introduced by `kv get`.

`delete` and `suspend` are special because they can run in preview mode. Their JSON needs to represent both the KV and the operation state, so this PR gives them explicit `data` and `meta` envelopes.

`resume` does not need operation metadata; it returns the resumed `KeyValueOut` directly.

GROW-2587: https://linear.app/render-com/issue/GROW-2587/slim-down-kv-json-output-to-resource-only
GitOrigin-RevId: e4b264a2796f1e570f55a5a73a5f40474ee23e9f

Author: davidharting

cmd/kvdelete.go

@@ -59,35 +59,42 @@ Key Value ID instead (which works across workspaces).`,
 		input = kvtypes.NormalizeDeleteInput(input)
 		confirm := command.GetConfirmFromContext(cmd.Context())
 
-		loadData := func() (*keyvalue.DeleteResult, error) {
+		loadData := func() (*keyvalue.DeleteOut, error) {
 			resolved, err := deps.KeyValueService().Resolve(cmd.Context(), keyvalue.ResolveInput{
 				IDOrName:            input.IDOrName,
 				EnvironmentIDOrName: input.EnvironmentIDOrName,
 			})
 			if err != nil {
 				return nil, err
 			}
-			kv := resolved.KeyValue
+			out := keyvalue.DeleteOut{
+				Data: keyvalue.NewKeyValueOut(resolved),
+				Meta: keyvalue.DeleteOutMeta{
+					Deleted: confirm,
+				},
+			}
 			if confirm {
-				if err := deps.KeyValueService().Delete(cmd.Context(), kv.Id); err != nil {
+				if err := deps.KeyValueService().Delete(cmd.Context(), out.Data.ID); err != nil {
 					return nil, err
 				}
+			} else {
+				out.Meta.Message = "re-run with --confirm to delete"
 			}
-			return &keyvalue.DeleteResult{KeyValue: kv, Deleted: confirm}, nil
+			return &out, nil
 		}
 
-		_, err := command.NonInteractive(cmd, loadData, formatTextOutput)
+		_, err := command.NonInteractive(cmd, loadData, formatDeleteTextOutput)
 		return err
 	}
 
 	return cmd
 }
 
-func formatTextOutput(r *keyvalue.DeleteResult) string {
-	if r.Deleted {
-		return "Deleted this Key Value:\n\n" + text.KeyValueAPIDetail(r.KeyValue) + "\n"
+func formatDeleteTextOutput(r *keyvalue.DeleteOut) string {
+	if r.Meta.Deleted {
+		return "Deleted this Key Value:\n\n" + text.KeyValueDetail(&r.Data) + "\n"
 	}
 	return "This command would delete this Key Value:\n\n" +
-		text.KeyValueAPIDetail(r.KeyValue) +
+		text.KeyValueDetail(&r.Data) +
 		"\nRe-run with --confirm to proceed\n"
 }

cmd/kvdelete_test.go

@@ -96,23 +96,51 @@ func TestKVDelete_UnknownName_Errors(t *testing.T) {
 
 func TestKVDelete_JSONOutput_AfterConfirm(t *testing.T) {
 	server := renderapi.NewServer(t)
-	kv := seedKV(server, "json-cache")
+	project := server.CreateProject(
+		renderapi.ProjectAttrs{Name: "My Project", OwnerId: kvTestWorkspaceID},
+		renderapi.EnvAttrs{Name: "production"},
+	)
+	env := project.Env("production")
+	kv := seedKVInEnv(server, "json-cache", env.Id)
 
 	result, err := executeKVDelete(t, server, kv.Id, "--confirm", "--output", "json")
 	require.NoError(t, err)
 	assert.Empty(t, server.KV.Instances)
 
-	var body struct {
-		KeyValue struct {
-			ID   string `json:"id"`
-			Name string `json:"name"`
-		} `json:"keyValue"`
-		Deleted bool `json:"deleted"`
-	}
+	var body map[string]any
+	require.NoError(t, json.Unmarshal([]byte(result.Stdout), &body))
+	require.Len(t, body, 2)
+
+	data := requireSubMap(t, body, "data")
+	meta := requireSubMap(t, body, "meta")
+	assert.Equal(t, kv.Id, data["id"])
+	assert.Equal(t, "json-cache", data["name"])
+	assert.Equal(t, kvTestWorkspaceID, data["ownerId"])
+	assert.Equal(t, project.Project.Id, data["projectId"])
+	assert.Equal(t, env.Id, data["environmentId"])
+	assert.Equal(t, true, meta["deleted"])
+	assert.NotContains(t, meta, "message")
+	assert.NotContains(t, body, "keyValue")
+	assert.NotContains(t, data, "projectName")
+	assert.NotContains(t, data, "environmentName")
+}
+
+func TestKVDelete_JSONOutput_PreviewIncludesConfirmMessage(t *testing.T) {
+	server := renderapi.NewServer(t)
+	kv := seedKV(server, "json-cache")
+
+	result, err := executeKVDelete(t, server, kv.Id, "--output", "json")
+	require.NoError(t, err)
+	assert.Len(t, server.KV.Instances, 1, "preview must not delete")
+
+	var body map[string]any
 	require.NoError(t, json.Unmarshal([]byte(result.Stdout), &body))
-	assert.Equal(t, kv.Id, body.KeyValue.ID)
-	assert.Equal(t, "json-cache", body.KeyValue.Name)
-	assert.True(t, body.Deleted)
+
+	data := requireSubMap(t, body, "data")
+	meta := requireSubMap(t, body, "meta")
+	assert.Equal(t, kv.Id, data["id"])
+	assert.Equal(t, false, meta["deleted"])
+	assert.Equal(t, "re-run with --confirm to delete", meta["message"])
 }
 
 func TestKVDelete_JSONOutput_OnError(t *testing.T) {

cmd/kvresume.go

@@ -3,7 +3,6 @@ package cmd
 import (
 	"github.com/spf13/cobra"
 
-	"github.com/render-oss/cli/pkg/client"
 	"github.com/render-oss/cli/pkg/command"
 	"github.com/render-oss/cli/pkg/dependencies"
 	"github.com/render-oss/cli/pkg/keyvalue"
@@ -51,7 +50,7 @@ Key Value ID instead (which works across workspaces).`,
 		}
 		input = kvtypes.NormalizeResumeInput(input)
 
-		loadData := func() (*client.KeyValueDetail, error) {
+		loadData := func() (*keyvalue.KeyValueOut, error) {
 			kv, err := deps.KeyValueService().Resolve(cmd.Context(), keyvalue.ResolveInput{
 				IDOrName:            input.IDOrName,
 				EnvironmentIDOrName: input.EnvironmentIDOrName,
@@ -68,7 +67,8 @@ Key Value ID instead (which works across workspaces).`,
 			if err != nil {
 				return nil, err
 			}
-			return kv.KeyValue, nil
+			out := keyvalue.NewKeyValueOut(kv)
+			return &out, nil
 		}
 
 		_, err := command.NonInteractive(cmd, loadData, formatResumeTextOutput)
@@ -78,6 +78,6 @@ Key Value ID instead (which works across workspaces).`,
 	return cmd
 }
 
-func formatResumeTextOutput(kv *client.KeyValueDetail) string {
-	return "Resumed this Key Value:\n\n" + text.KeyValueAPIDetail(kv) + "\n"
+func formatResumeTextOutput(kv *keyvalue.KeyValueOut) string {
+	return "Resumed this Key Value:\n\n" + text.KeyValueDetail(kv) + "\n"
 }

cmd/kvresume_test.go

@@ -79,21 +79,29 @@ func TestKVResume_UnknownID_Errors(t *testing.T) {
 
 func TestKVResume_JSONOutput(t *testing.T) {
 	server := renderapi.NewServer(t)
-	kv := seedSuspendedKV(server, "json-cache")
+	project := server.CreateProject(
+		renderapi.ProjectAttrs{Name: "My Project", OwnerId: kvTestWorkspaceID},
+		renderapi.EnvAttrs{Name: "production"},
+	)
+	env := project.Env("production")
+	kv := seedKVInEnv(server, "json-cache", env.Id)
+	kv.Status = client.DatabaseStatusSuspended
 
 	result, err := executeKVResume(t, server, kv.Id, "--output", "json")
 	require.NoError(t, err)
 	assert.Equal(t, client.DatabaseStatusAvailable, server.KV.Instances[0].Status)
 
-	var body struct {
-		ID     string `json:"id"`
-		Name   string `json:"name"`
-		Status string `json:"status"`
-	}
+	var body map[string]any
 	require.NoError(t, json.Unmarshal([]byte(result.Stdout), &body))
-	assert.Equal(t, kv.Id, body.ID)
-	assert.Equal(t, "json-cache", body.Name)
-	assert.Equal(t, string(client.DatabaseStatusAvailable), body.Status)
+	assert.Equal(t, kv.Id, body["id"])
+	assert.Equal(t, "json-cache", body["name"])
+	assert.Equal(t, string(client.DatabaseStatusAvailable), body["status"])
+	assert.Equal(t, kvTestWorkspaceID, body["ownerId"])
+	assert.Equal(t, project.Project.Id, body["projectId"])
+	assert.Equal(t, env.Id, body["environmentId"])
+	assert.NotContains(t, body, "keyValue")
+	assert.NotContains(t, body, "projectName")
+	assert.NotContains(t, body, "environmentName")
 }
 
 func TestKVResume_NameCollision_NarrowedByEnvironment_Resumes(t *testing.T) {

cmd/kvsuspend.go

@@ -57,28 +57,35 @@ Key Value ID instead (which works across workspaces).`,
 		input = kvtypes.NormalizeSuspendInput(input)
 		confirm := command.GetConfirmFromContext(cmd.Context())
 
-		loadData := func() (*keyvalue.SuspendResult, error) {
+		loadData := func() (*keyvalue.SuspendOut, error) {
 			before, err := deps.KeyValueService().Resolve(cmd.Context(), keyvalue.ResolveInput{
 				IDOrName:            input.IDOrName,
 				EnvironmentIDOrName: input.EnvironmentIDOrName,
 			})
 			if err != nil {
 				return nil, err
 			}
-			kv := before.KeyValue
+			out := keyvalue.SuspendOut{
+				Data: keyvalue.NewKeyValueOut(before),
+				Meta: keyvalue.SuspendOutMeta{
+					Suspended: confirm,
+				},
+			}
 			if !confirm {
-				return &keyvalue.SuspendResult{KeyValue: kv, Suspended: false}, nil
+				out.Meta.Message = "re-run with --confirm to suspend"
+				return &out, nil
 			}
-			if err := deps.KeyValueService().Suspend(cmd.Context(), kv.Id); err != nil {
+			if err := deps.KeyValueService().Suspend(cmd.Context(), out.Data.ID); err != nil {
 				return nil, err
 			}
 			after, err := deps.KeyValueService().Resolve(cmd.Context(), keyvalue.ResolveInput{
-				IDOrName: kv.Id,
+				IDOrName: out.Data.ID,
 			})
 			if err != nil {
 				return nil, err
 			}
-			return &keyvalue.SuspendResult{KeyValue: after.KeyValue, Suspended: true}, nil
+			out.Data = keyvalue.NewKeyValueOut(after)
+			return &out, nil
 		}
 
 		_, err := command.NonInteractive(cmd, loadData, formatSuspendTextOutput)
@@ -88,11 +95,11 @@ Key Value ID instead (which works across workspaces).`,
 	return cmd
 }
 
-func formatSuspendTextOutput(r *keyvalue.SuspendResult) string {
-	if r.Suspended {
-		return "Suspended this Key Value:\n\n" + text.KeyValueAPIDetail(r.KeyValue) + "\n"
+func formatSuspendTextOutput(r *keyvalue.SuspendOut) string {
+	if r.Meta.Suspended {
+		return "Suspended this Key Value:\n\n" + text.KeyValueDetail(&r.Data) + "\n"
 	}
 	return "This command would suspend this Key Value:\n\n" +
-		text.KeyValueAPIDetail(r.KeyValue) +
+		text.KeyValueDetail(&r.Data) +
 		"\n\nRe-run with --confirm to proceed\n"
 }

cmd/kvsuspend_test.go

@@ -92,19 +92,38 @@ func TestKVSuspend_JSONOutput_AfterConfirm(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, client.DatabaseStatusSuspended, server.KV.Instances[0].Status)
 
-	var body struct {
-		KeyValue struct {
-			ID     string `json:"id"`
-			Name   string `json:"name"`
-			Status string `json:"status"`
-		} `json:"keyValue"`
-		Suspended bool `json:"suspended"`
-	}
+	var body map[string]any
+	require.NoError(t, json.Unmarshal([]byte(result.Stdout), &body))
+	require.Len(t, body, 2)
+
+	data := requireSubMap(t, body, "data")
+	meta := requireSubMap(t, body, "meta")
+	assert.Equal(t, kv.Id, data["id"])
+	assert.Equal(t, "json-cache", data["name"])
+	assert.Equal(t, string(client.DatabaseStatusSuspended), data["status"])
+	assert.Equal(t, kvTestWorkspaceID, data["ownerId"])
+	assert.Nil(t, data["projectId"])
+	assert.Nil(t, data["environmentId"])
+	assert.Equal(t, true, meta["suspended"])
+	assert.NotContains(t, meta, "message")
+}
+
+func TestKVSuspend_JSONOutput_PreviewIncludesConfirmMessage(t *testing.T) {
+	server := renderapi.NewServer(t)
+	kv := seedKV(server, "json-cache")
+
+	result, err := executeKVSuspend(t, server, kv.Id, "--output", "json")
+	require.NoError(t, err)
+	assert.Len(t, server.KV.Instances, 1, "preview must not suspend")
+
+	var body map[string]any
 	require.NoError(t, json.Unmarshal([]byte(result.Stdout), &body))
-	assert.Equal(t, kv.Id, body.KeyValue.ID)
-	assert.Equal(t, "json-cache", body.KeyValue.Name)
-	assert.Equal(t, string(client.DatabaseStatusSuspended), body.KeyValue.Status)
-	assert.True(t, body.Suspended)
+
+	data := requireSubMap(t, body, "data")
+	meta := requireSubMap(t, body, "meta")
+	assert.Equal(t, kv.Id, data["id"])
+	assert.Equal(t, false, meta["suspended"])
+	assert.Equal(t, "re-run with --confirm to suspend", meta["message"])
 }
 
 func TestKVSuspend_NameCollision_NarrowedByEnvironment_Suspends(t *testing.T) {

cmd/testhelpers_test.go

@@ -21,3 +21,12 @@ func newTestConfigPath(t *testing.T) string {
 	_ = tmpCfg.Close()
 	return tmpCfg.Name()
 }
+
+// requireSubMap returns the nested map stored at key, failing the test if the
+// key is absent or the value is not a map[string]any.
+func requireSubMap(t *testing.T, body map[string]any, key string) map[string]any {
+	t.Helper()
+	require.Contains(t, body, key, "expected %q", key)
+	require.IsType(t, map[string]any{}, body[key], "expected %q to contain a map", key)
+	return body[key].(map[string]any)
+}

pkg/keyvalue/delete.go

@@ -27,6 +27,26 @@ type KeyValueOut struct {
 	MaxmemoryPolicy *string                          `json:"maxmemoryPolicy,omitempty"`
 }
 
+type DeleteOut struct {
+	Data KeyValueOut   `json:"data"`
+	Meta DeleteOutMeta `json:"meta"`
+}
+
+type DeleteOutMeta struct {
+	Deleted bool   `json:"deleted"`
+	Message string `json:"message,omitempty"`
+}
+
+type SuspendOut struct {
+	Data KeyValueOut    `json:"data"`
+	Meta SuspendOutMeta `json:"meta"`
+}
+
+type SuspendOutMeta struct {
+	Suspended bool   `json:"suspended"`
+	Message   string `json:"message,omitempty"`
+}
+
 func NewKeyValueOut(resolved *ResolvedKeyValue) KeyValueOut {
 	if resolved == nil || resolved.KeyValue == nil {
 		return KeyValueOut{}