Merge pull request #280 from dropbox/json-normalize-single-operations

Normalize mkdir and restore to shared JSON operation output

Author: AndreyVMarkelov

README.md

@@ -158,24 +158,35 @@ Structured success output is rolling out command by command. Currently migrated
 
 Command results and JSON errors are written to stdout. Status, progress, human-facing warnings, diagnostics, and verbose logs are written to stderr. JSON errors include a `warnings` array for machine-actionable warnings; it is `[]` when no warnings are present. New operation-style JSON payloads should use the same `warnings` field.
 
-Successful JSON responses are command-specific. Commands that operate on one path usually return an `input` object and a `result` metadata object:
+Successful JSON responses are command-specific. Operation commands return an `input` object, a `results` array, and a `warnings` array. For commands such as `mkdir`, each result reports what happened to the requested path:
 
 ```json
 {
   "input": {
     "path": "/new-folder",
     "parents": false
   },
-  "result": {
-    "type": "folder",
-    "path_display": "/new-folder",
-    "path_lower": "/new-folder",
-    "id": "id:..."
-  }
+  "results": [
+    {
+      "status": "created",
+      "kind": "folder",
+      "input": {
+        "path": "/new-folder",
+        "parents": false
+      },
+      "result": {
+        "type": "folder",
+        "path_display": "/new-folder",
+        "path_lower": "/new-folder",
+        "id": "id:..."
+      }
+    }
+  ],
+  "warnings": []
 }
 ```
 
-Commands that operate on multiple paths return a `results` array. For `cp` and `mv`, each `input` object uses `from_path` and `to_path`:
+For `cp` and `mv`, each result input object uses `from_path` and `to_path`:
 
 ```json
 {

cmd/mkdir.go

@@ -28,7 +28,16 @@ type mkdirInput struct {
 	Parents bool   `json:"parents"`
 }
 
+const (
+	mkdirStatusCreated  = "created"
+	mkdirStatusExisting = "existing"
+
+	mkdirKindFolder = "folder"
+)
+
 type mkdirResult struct {
+	Status string       `json:"status"`
+	Kind   string       `json:"kind"`
 	Input  mkdirInput   `json:"input"`
 	Result jsonMetadata `json:"result"`
 }
@@ -50,6 +59,7 @@ func mkdir(cmd *cobra.Command, args []string) (err error) {
 	dbx := filesNewFunc(config)
 	created, err := dbx.CreateFolderV2(arg)
 	var metadata *files.FolderMetadata
+	status := mkdirStatusCreated
 	if err != nil {
 		if !parents {
 			return err
@@ -65,6 +75,7 @@ func mkdir(cmd *cobra.Command, args []string) (err error) {
 			if err != nil {
 				return err
 			}
+			status = mkdirStatusExisting
 		case ok && (conflictTag == files.WriteConflictErrorFile || conflictTag == files.WriteConflictErrorFileAncestor):
 			return fmt.Errorf("path exists and is not a folder: %s", dst)
 		case ok:
@@ -77,6 +88,7 @@ func mkdir(cmd *cobra.Command, args []string) (err error) {
 			if err != nil {
 				return err
 			}
+			status = mkdirStatusExisting
 		default:
 			return err
 		}
@@ -87,8 +99,8 @@ func mkdir(cmd *cobra.Command, args []string) (err error) {
 		metadata = created.Metadata
 	}
 
-	result := newMkdirResult(dst, parents, metadata)
-	return commandOutput(cmd).Render(nil, result)
+	result := newMkdirResult(status, dst, parents, metadata)
+	return renderJSONOperationOutput(cmd, result.Input, []jsonOperationResult{mkdirOperationResult(result)})
 }
 
 func existingFolderMetadata(dbx files.Client, dst string) (*files.FolderMetadata, error) {
@@ -103,11 +115,13 @@ func existingFolderMetadata(dbx files.Client, dst string) (*files.FolderMetadata
 	return folder, nil
 }
 
-func newMkdirResult(path string, parents bool, metadata *files.FolderMetadata) mkdirResult {
+func newMkdirResult(status, path string, parents bool, metadata *files.FolderMetadata) mkdirResult {
 	result := jsonMetadataFromDropbox(metadata)
 	result.PathDisplay = metadataDisplayPath(path, result.PathDisplay)
 
 	return mkdirResult{
+		Status: status,
+		Kind:   mkdirKindFolder,
 		Input: mkdirInput{
 			Path:    path,
 			Parents: parents,
@@ -116,6 +130,10 @@ func newMkdirResult(path string, parents bool, metadata *files.FolderMetadata) m
 	}
 }
 
+func mkdirOperationResult(result mkdirResult) jsonOperationResult {
+	return newJSONOperationResult(result.Status, result.Kind, result.Input, result.Result)
+}
+
 func createFolderConflictTag(err error) (string, bool) {
 	var apiErrPtr *files.CreateFolderV2APIError
 	if errors.As(err, &apiErrPtr) && apiErrPtr != nil {

cmd/mkdir_test.go

@@ -74,17 +74,24 @@ func TestMkdirJSONOutputsCreatedFolder(t *testing.T) {
 	if got.Input.Path != "/Projects" || got.Input.Parents {
 		t.Fatalf("input = %#v, want path /Projects and parents false", got.Input)
 	}
-	if got.Result.Type != "folder" {
-		t.Fatalf("result type = %q, want folder", got.Result.Type)
+	result := got.Results[0]
+	if result.Status != mkdirStatusCreated || result.Kind != mkdirKindFolder {
+		t.Fatalf("status/kind = %s/%s, want created/folder", result.Status, result.Kind)
 	}
-	if got.Result.PathDisplay != "/Projects" {
-		t.Fatalf("path_display = %q, want /Projects", got.Result.PathDisplay)
+	if result.Input.Path != "/Projects" || result.Input.Parents {
+		t.Fatalf("result input = %#v, want path /Projects and parents false", result.Input)
 	}
-	if got.Result.PathLower != "/projects" {
-		t.Fatalf("path_lower = %q, want /projects", got.Result.PathLower)
+	if result.Result.Type != "folder" {
+		t.Fatalf("result type = %q, want folder", result.Result.Type)
 	}
-	if got.Result.ID != "id:folder" {
-		t.Fatalf("id = %q, want id:folder", got.Result.ID)
+	if result.Result.PathDisplay != "/Projects" {
+		t.Fatalf("path_display = %q, want /Projects", result.Result.PathDisplay)
+	}
+	if result.Result.PathLower != "/projects" {
+		t.Fatalf("path_lower = %q, want /projects", result.Result.PathLower)
+	}
+	if result.Result.ID != "id:folder" {
+		t.Fatalf("id = %q, want id:folder", result.Result.ID)
 	}
 	if strings.Contains(stdout.String(), `"rev"`) || strings.Contains(stdout.String(), `"size"`) {
 		t.Fatalf("folder JSON output = %s, want no file-only fields", stdout.String())
@@ -121,8 +128,12 @@ func TestMkdirJSONParentsReturnsExistingFolderMetadata(t *testing.T) {
 	if got.Input.Path != "/Existing" || !got.Input.Parents {
 		t.Fatalf("input = %#v, want path /Existing and parents true", got.Input)
 	}
-	if got.Result.Type != "folder" || got.Result.PathDisplay != "/Existing" {
-		t.Fatalf("result = %#v, want existing folder metadata", got.Result)
+	result := got.Results[0]
+	if result.Status != mkdirStatusExisting || result.Kind != mkdirKindFolder {
+		t.Fatalf("status/kind = %s/%s, want existing/folder", result.Status, result.Kind)
+	}
+	if result.Result.Type != "folder" || result.Result.PathDisplay != "/Existing" {
+		t.Fatalf("result = %#v, want existing folder metadata", result.Result)
 	}
 }
 
@@ -211,8 +222,8 @@ func TestMkdirJSONUsesInputPathWhenMetadataPathDisplayMissing(t *testing.T) {
 	}
 
 	got := decodeMkdirOutput(t, stdout)
-	if got.Result.PathDisplay != "/Projects" {
-		t.Fatalf("path_display = %q, want fallback input path", got.Result.PathDisplay)
+	if got.Results[0].Result.PathDisplay != "/Projects" {
+		t.Fatalf("path_display = %q, want fallback input path", got.Results[0].Result.PathDisplay)
 	}
 }
 
@@ -294,12 +305,27 @@ func createFolderConflictError(conflictTag string) files.CreateFolderV2APIError
 	}
 }
 
-func decodeMkdirOutput(t *testing.T, stdout *bytes.Buffer) mkdirResult {
+type mkdirOutput struct {
+	Input    mkdirInput    `json:"input"`
+	Results  []mkdirResult `json:"results"`
+	Warnings []jsonWarning `json:"warnings"`
+}
+
+func decodeMkdirOutput(t *testing.T, stdout *bytes.Buffer) mkdirOutput {
 	t.Helper()
 
-	var got mkdirResult
+	var got mkdirOutput
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode JSON output: %v\noutput: %s", err, stdout.String())
 	}
+	if got.Warnings == nil {
+		t.Fatalf("warnings = nil, want empty array")
+	}
+	if len(got.Warnings) != 0 {
+		t.Fatalf("warnings = %+v, want empty", got.Warnings)
+	}
+	if len(got.Results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(got.Results))
+	}
 	return got
 }

cmd/restore.go

@@ -29,7 +29,14 @@ type restoreInput struct {
 	Revision string `json:"revision"`
 }
 
+const (
+	restoreStatusRestored = "restored"
+	restoreKindFile       = "file"
+)
+
 type restoreResult struct {
+	Status string       `json:"status"`
+	Kind   string       `json:"kind"`
 	Input  restoreInput `json:"input"`
 	Result jsonMetadata `json:"result"`
 }
@@ -62,11 +69,13 @@ func restore(cmd *cobra.Command, args []string) (err error) {
 			return nil
 		}
 		return renderRestoreResult(w, result)
-	}, result)
+	}, newJSONOperationOutput(result.Input, []jsonOperationResult{restoreOperationResult(result)}, nil))
 }
 
 func newRestoreResult(path, revision string, metadata *files.FileMetadata) restoreResult {
 	return restoreResult{
+		Status: restoreStatusRestored,
+		Kind:   restoreKindFile,
 		Input: restoreInput{
 			Path:     path,
 			Revision: revision,
@@ -75,6 +84,10 @@ func newRestoreResult(path, revision string, metadata *files.FileMetadata) resto
 	}
 }
 
+func restoreOperationResult(result restoreResult) jsonOperationResult {
+	return newJSONOperationResult(result.Status, result.Kind, result.Input, result.Result)
+}
+
 func restoreMetadataFromDropbox(path string, metadata *files.FileMetadata) jsonMetadata {
 	if metadata == nil {
 		return jsonMetadata{

cmd/restore_test.go

@@ -115,6 +115,9 @@ func TestNewRestoreResultKeepsInputAndMetadata(t *testing.T) {
 	if result.Input.Path != "/Reports/old.pdf" || result.Input.Revision != "target-rev" {
 		t.Fatalf("input = %#v, want path and target revision", result.Input)
 	}
+	if result.Status != restoreStatusRestored || result.Kind != restoreKindFile {
+		t.Fatalf("status/kind = %s/%s, want restored/file", result.Status, result.Kind)
+	}
 	if result.Result.Type != "file" || result.Result.PathDisplay != "/Reports/old.pdf" {
 		t.Fatalf("metadata = %#v, want file path metadata", result.Result)
 	}
@@ -165,20 +168,27 @@ func TestRestoreJSONOutputsInputAndMetadata(t *testing.T) {
 	if got.Input.Path != "/Reports/old.pdf" || got.Input.Revision != "target-rev" {
 		t.Fatalf("input = %#v, want path and target revision", got.Input)
 	}
-	if got.Result.Type != "file" || got.Result.PathDisplay != "/Reports/old.pdf" || got.Result.PathLower != "/reports/old.pdf" {
-		t.Fatalf("metadata = %#v, want file path metadata", got.Result)
+	result := got.Results[0]
+	if result.Status != restoreStatusRestored || result.Kind != restoreKindFile {
+		t.Fatalf("status/kind = %s/%s, want restored/file", result.Status, result.Kind)
+	}
+	if result.Input.Path != "/Reports/old.pdf" || result.Input.Revision != "target-rev" {
+		t.Fatalf("result input = %#v, want path and target revision", result.Input)
 	}
-	if got.Result.ID != "id:abc" || got.Result.Rev != "current-rev" {
-		t.Fatalf("metadata = %#v, want returned id and current revision", got.Result)
+	if result.Result.Type != "file" || result.Result.PathDisplay != "/Reports/old.pdf" || result.Result.PathLower != "/reports/old.pdf" {
+		t.Fatalf("metadata = %#v, want file path metadata", result.Result)
 	}
-	if got.Result.Size == nil || *got.Result.Size != 123 {
-		t.Fatalf("size = %v, want 123", got.Result.Size)
+	if result.Result.ID != "id:abc" || result.Result.Rev != "current-rev" {
+		t.Fatalf("metadata = %#v, want returned id and current revision", result.Result)
 	}
-	if got.Result.ServerModified == nil || *got.Result.ServerModified != "2026-06-17T12:30:00Z" {
-		t.Fatalf("server modified = %v, want 2026-06-17T12:30:00Z", got.Result.ServerModified)
+	if result.Result.Size == nil || *result.Result.Size != 123 {
+		t.Fatalf("size = %v, want 123", result.Result.Size)
+	}
+	if result.Result.ServerModified == nil || *result.Result.ServerModified != "2026-06-17T12:30:00Z" {
+		t.Fatalf("server modified = %v, want 2026-06-17T12:30:00Z", result.Result.ServerModified)
 	}
-	if got.Result.ClientModified == nil || *got.Result.ClientModified != "2026-06-16T10:00:00Z" {
-		t.Fatalf("client modified = %v, want 2026-06-16T10:00:00Z", got.Result.ClientModified)
+	if result.Result.ClientModified == nil || *result.Result.ClientModified != "2026-06-16T10:00:00Z" {
+		t.Fatalf("client modified = %v, want 2026-06-16T10:00:00Z", result.Result.ClientModified)
 	}
 }
 
@@ -197,8 +207,8 @@ func TestRestoreJSONUsesInputPathWhenMetadataPathDisplayMissing(t *testing.T) {
 	}
 
 	got := decodeRestoreOutput(t, stdout)
-	if got.Result.PathDisplay != "/Reports/old.pdf" {
-		t.Fatalf("path_display = %q, want fallback input path", got.Result.PathDisplay)
+	if got.Results[0].Result.PathDisplay != "/Reports/old.pdf" {
+		t.Fatalf("path_display = %q, want fallback input path", got.Results[0].Result.PathDisplay)
 	}
 }
 
@@ -227,8 +237,8 @@ func TestRestoreJSONVerboseDoesNotPrintText(t *testing.T) {
 		t.Fatalf("stdout = %q, want JSON only", stdout.String())
 	}
 	got := decodeRestoreOutput(t, stdout)
-	if got.Result.Rev != "current-rev" {
-		t.Fatalf("rev = %q, want current-rev", got.Result.Rev)
+	if got.Results[0].Result.Rev != "current-rev" {
+		t.Fatalf("rev = %q, want current-rev", got.Results[0].Result.Rev)
 	}
 }
 
@@ -273,12 +283,27 @@ func setRestoreOutputJSON(t *testing.T, cmd *cobra.Command) {
 	}
 }
 
-func decodeRestoreOutput(t *testing.T, stdout *bytes.Buffer) restoreResult {
+type restoreOutput struct {
+	Input    restoreInput    `json:"input"`
+	Results  []restoreResult `json:"results"`
+	Warnings []jsonWarning   `json:"warnings"`
+}
+
+func decodeRestoreOutput(t *testing.T, stdout *bytes.Buffer) restoreOutput {
 	t.Helper()
 
-	var got restoreResult
+	var got restoreOutput
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode JSON output: %v\noutput: %s", err, stdout.String())
 	}
+	if got.Warnings == nil {
+		t.Fatalf("warnings = nil, want empty array")
+	}
+	if len(got.Warnings) != 0 {
+		t.Fatalf("warnings = %+v, want empty", got.Warnings)
+	}
+	if len(got.Results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(got.Results))
+	}
 	return got
 }