feat(data): add data argument to payload-based methods

To help simplify the modification and mutation of complex data structures,
add a `--@data` flag which can consume a file directly.

resolves #21.

Author: toumorokoshi

docs/userguide.md

@@ -178,6 +178,55 @@ lists are specified as a comma-separated list:
 aepcli bookstore book-edition create --book "peter-pan" --publisher "consistent-house" --tags "fantasy,childrens"
 ```
 
+### JSON File Input with --@data Flag
+
+For complex resource data or when working with arrays of objects, you can use the `--@data` flag to read resource data from JSON files.
+
+#### Basic Usage
+
+Create a JSON file containing the resource data:
+
+```json
+{
+  "title": "The Lord of the Rings",
+  "author": "J.R.R. Tolkien",
+  "published": 1954,
+  "metadata": {
+    "isbn": "978-0-618-00222-1",
+    "pages": 1178,
+    "publisher": {
+      "name": "Houghton Mifflin",
+      "location": "Boston"
+    }
+  },
+  "genres": ["fantasy", "adventure", "epic"],
+  "available": true
+}
+```
+
+Then use the flag to reference the file:
+
+```bash
+aepcli bookstore book create lotr --@data book.json
+```
+
+#### File Reference Syntax
+
+- Relative paths are resolved from the current working directory
+- Absolute paths are also supported
+
+```bash
+# Using relative path
+aepcli bookstore book create --@data ./data/book.json
+
+# Using absolute path
+aepcli bookstore book create --@data /home/user/books/fantasy.json
+```
+
+#### Mutually Exclusive with Field Flags
+
+The `--@data` flag cannot be used together with individual field flags. This prevents confusion about which values should be used.
+
 ### Logging HTTP requests and Dry Runs
 
 aepcli supports logging http requests and dry runs. To log http requests, use the

example_openapis/book-create.json

@@ -0,0 +1,19 @@
+{
+    "title": "The Lord of the Rings",
+    "author": "J.R.R. Tolkien",
+    "published": 1954,
+    "metadata": {
+        "isbn": "978-0-618-00222-1",
+        "pages": 1178,
+        "publisher": {
+            "name": "Houghton Mifflin",
+            "location": "Boston"
+        }
+    },
+    "genres": [
+        "fantasy",
+        "adventure",
+        "epic"
+    ],
+    "available": true
+}

example_openapis/book-update.json

@@ -0,0 +1,13 @@
+{
+    "title": "The Lord of the Rings: Updated Edition",
+    "metadata": {
+        "isbn": "978-0-618-00222-1",
+        "pages": 1200,
+        "edition": 2,
+        "publisher": {
+            "name": "New Publisher Inc.",
+            "location": "New York"
+        }
+    },
+    "available": false
+}

example_openapis/complex-book.json

@@ -0,0 +1,61 @@
+{
+    "title": "Complex Book Example",
+    "author": "Multi Author",
+    "authors": [
+        {
+            "name": "Author One",
+            "role": "writer",
+            "bio": "Primary author of the work"
+        },
+        {
+            "name": "Author Two",
+            "role": "editor",
+            "bio": "Editorial contributions"
+        }
+    ],
+    "categories": [
+        {
+            "name": "Science Fiction",
+            "subcategories": [
+                "Space Opera",
+                "Hard SF"
+            ]
+        },
+        {
+            "name": "Adventure",
+            "subcategories": [
+                "Quest",
+                "Journey"
+            ]
+        }
+    ],
+    "metadata": {
+        "format": "hardback",
+        "isbn": "978-1-234-56789-0",
+        "publisher": {
+            "name": "Example Publisher",
+            "address": {
+                "street": "123 Publishing Ave",
+                "city": "Book City",
+                "state": "NY",
+                "zip": "12345"
+            },
+            "contact": {
+                "email": "contact@example-publisher.com",
+                "phone": "+1-555-123-4567"
+            }
+        }
+    },
+    "reviews": [
+        {
+            "reviewer": "Book Critic",
+            "rating": 5,
+            "comment": "Excellent work!"
+        },
+        {
+            "reviewer": "Another Reader",
+            "rating": 4,
+            "comment": "Really enjoyed it."
+        }
+    ]
+}

example_openapis/invalid.json

@@ -0,0 +1,3 @@
+{
+    "invalid": "json",
+    "missing": "closing brace"

example_openapis/review-request.json

@@ -0,0 +1,11 @@
+{
+    "reason": "Quality assurance review",
+    "reviewer": {
+        "name": "Jane Doe",
+        "department": "Editorial",
+        "email": "jane.doe@publisher.com"
+    },
+    "priority": "high",
+    "notes": "Please review the technical accuracy of chapters 5-8",
+    "deadline": "2024-12-01T00:00:00Z"
+}

internal/service/flagtypes.go

@@ -3,6 +3,8 @@ package service
 import (
 	"encoding/csv"
 	"encoding/json"
+	"fmt"
+	"os"
 	"strings"
 )
 
@@ -56,3 +58,64 @@ func (f *ArrayFlag) Set(v string) error {
 func (f *ArrayFlag) Type() string {
 	return "array"
 }
+
+// DataFlag handles file references with @file syntax
+type DataFlag struct {
+	Target *map[string]interface{}
+}
+
+func (f *DataFlag) String() string {
+	if f.Target == nil || *f.Target == nil {
+		return ""
+	}
+	b, err := json.Marshal(*f.Target)
+	if err != nil {
+		return "failed to marshal object"
+	}
+	return string(b)
+}
+
+func (f *DataFlag) Set(v string) error {
+	// The filename is provided directly (no @ prefix needed)
+	filename := v
+	if filename == "" {
+		return fmt.Errorf("filename cannot be empty")
+	}
+
+	// Read the file
+	data, err := os.ReadFile(filename)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("unable to read file '%s': no such file or directory", filename)
+		}
+		return fmt.Errorf("unable to read file '%s': %v", filename, err)
+	}
+
+	// Parse JSON
+	var jsonData map[string]interface{}
+	if err := json.Unmarshal(data, &jsonData); err != nil {
+		// Try to provide line/column information if possible
+		if syntaxErr, ok := err.(*json.SyntaxError); ok {
+			// Calculate line and column from offset
+			line := 1
+			col := 1
+			for i := int64(0); i < syntaxErr.Offset; i++ {
+				if i < int64(len(data)) && data[i] == '\n' {
+					line++
+					col = 1
+				} else {
+					col++
+				}
+			}
+			return fmt.Errorf("invalid JSON in '%s': %s at line %d, column %d", filename, syntaxErr.Error(), line, col)
+		}
+		return fmt.Errorf("invalid JSON in '%s': %v", filename, err)
+	}
+
+	*f.Target = jsonData
+	return nil
+}
+
+func (f *DataFlag) Type() string {
+	return "data"
+}

internal/service/flagtypes_test.go

@@ -0,0 +1,139 @@
+package service
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDataFlag(t *testing.T) {
+	// Create a temporary directory for test files
+	tempDir := t.TempDir()
+
+	// Test data
+	validJSON := map[string]interface{}{
+		"title":  "Test Book",
+		"author": "Test Author",
+		"metadata": map[string]interface{}{
+			"isbn":  "123-456-789",
+			"pages": float64(300), // JSON numbers are float64
+		},
+	}
+
+	t.Run("valid JSON file", func(t *testing.T) {
+		// Create a temporary JSON file
+		jsonData, _ := json.Marshal(validJSON)
+		testFile := filepath.Join(tempDir, "valid.json")
+		err := os.WriteFile(testFile, jsonData, 0644)
+		if err != nil {
+			t.Fatalf("Failed to create test file: %v", err)
+		}
+
+		// Test the flag
+		var target map[string]interface{}
+		flag := &DataFlag{Target: &target}
+
+		err = flag.Set(testFile)
+		if err != nil {
+			t.Fatalf("Expected no error, got: %v", err)
+		}
+
+		// Check that the data was parsed correctly
+		if target["title"] != "Test Book" {
+			t.Errorf("Expected title 'Test Book', got: %v", target["title"])
+		}
+		if target["author"] != "Test Author" {
+			t.Errorf("Expected author 'Test Author', got: %v", target["author"])
+		}
+	})
+
+	t.Run("empty filename", func(t *testing.T) {
+		var target map[string]interface{}
+		flag := &DataFlag{Target: &target}
+
+		err := flag.Set("")
+		if err == nil {
+			t.Fatal("Expected error for empty filename")
+		}
+
+		expectedError := "filename cannot be empty"
+		if err.Error() != expectedError {
+			t.Errorf("Expected error: %s, got: %s", expectedError, err.Error())
+		}
+	})
+
+	t.Run("file not found", func(t *testing.T) {
+		var target map[string]interface{}
+		flag := &DataFlag{Target: &target}
+
+		err := flag.Set("nonexistent.json")
+		if err == nil {
+			t.Fatal("Expected error for nonexistent file")
+		}
+
+		if !contains(err.Error(), "unable to read file 'nonexistent.json': no such file or directory") {
+			t.Errorf("Expected file not found error, got: %s", err.Error())
+		}
+	})
+
+	t.Run("invalid JSON", func(t *testing.T) {
+		// Create a file with invalid JSON
+		invalidJSON := `{"title": "Test", "missing": "closing brace"`
+		testFile := filepath.Join(tempDir, "invalid.json")
+		err := os.WriteFile(testFile, []byte(invalidJSON), 0644)
+		if err != nil {
+			t.Fatalf("Failed to create test file: %v", err)
+		}
+
+		var target map[string]interface{}
+		flag := &DataFlag{Target: &target}
+
+		err = flag.Set(testFile)
+		if err == nil {
+			t.Fatal("Expected error for invalid JSON")
+		}
+
+		if !contains(err.Error(), "invalid JSON in") {
+			t.Errorf("Expected invalid JSON error, got: %s", err.Error())
+		}
+	})
+
+	t.Run("string representation", func(t *testing.T) {
+		target := map[string]interface{}{
+			"title": "Test Book",
+		}
+		flag := &DataFlag{Target: &target}
+
+		str := flag.String()
+		expected := `{"title":"Test Book"}`
+		if str != expected {
+			t.Errorf("Expected string: %s, got: %s", expected, str)
+		}
+	})
+
+	t.Run("type", func(t *testing.T) {
+		flag := &DataFlag{}
+		if flag.Type() != "data" {
+			t.Errorf("Expected type 'data', got: %s", flag.Type())
+		}
+	})
+}
+
+// Helper function to check if a string contains a substring
+func contains(str, substr string) bool {
+	return len(str) >= len(substr) && (str == substr ||
+		(len(str) > len(substr) &&
+			(str[:len(substr)] == substr ||
+				str[len(str)-len(substr):] == substr ||
+				containsInMiddle(str, substr))))
+}
+
+func containsInMiddle(str, substr string) bool {
+	for i := 0; i <= len(str)-len(substr); i++ {
+		if str[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}