[#74416] add work package description support

Add explicit `--description` support to create and update work package
commands.

This extends create and the core update patch path, includes JSON
dry-run coverage for descriptions, documents the new flag, and keeps
validation strict around unsupported flag combinations.

https://community.openproject.org/wp/74416

Author: myabc

README.md

@@ -130,6 +130,7 @@ op update workpackge 42 -
 --action    -a  -- Executes a custom action on a work package
 --assignee      -- Assign a user to the work package
 --attach        -- Attach a file to the work package
+--description   -- Change the raw work package description
 --help      -h  -- help for workpackage
 --subject       -- Change the subject of the work package
 --type      -t  -- Change the work package type
@@ -154,6 +155,11 @@ op create workpackge -p11 'Document new CLI tool' -o
 # Validating the creation of a child work package without persisting it.
 # The parent determines the project automatically.
 op create workpackage --parent 74316 --type Implementation 'Build reusable skill' --dry-run --json
+
+# Creating a child work package with an explicit raw description.
+op create workpackage --parent 74316 --type Implementation \
+  --description 'Use openproject-cli JSON workflows from a reusable agent skill.' \
+  'Build reusable skill'
 ```
 
 #### Listing
@@ -182,6 +188,10 @@ op update workpackage 42 --attach ./Downloads/Report.pdf
 # Resolving and validating field updates as JSON before applying them
 # This first slice supports schema-resolved custom fields via --set.
 op update workpackage 74316 --set 'Votes=3' --dry-run --json
+
+# Updating core fields, including the raw description, in one PATCH request.
+op update workpackage 74416 --subject 'Add explicit description support' \
+  --description 'Allow create and update to write the raw ticket body.'
 ```
 
 #### Inspecting

cmd/create/create.go

@@ -40,6 +40,13 @@ func init() {
 		"Create the work package as a child of an existing work package",
 	)
 
+	createWorkPackageCmd.Flags().StringVar(
+		&descriptionFlag,
+		"description",
+		"",
+		"Set the raw work package description",
+	)
+
 	createWorkPackageCmd.Flags().BoolVar(
 		&printCreatedWorkPackageAsJSON,
 		"json",

cmd/create/work_package.go

@@ -18,6 +18,7 @@ var shouldOpenWorkPackageInBrowser bool
 var printCreatedWorkPackageAsJSON bool
 var dryRunCreateWorkPackage bool
 var typeFlag string
+var descriptionFlag string
 
 var createWorkPackageCmd = &cobra.Command{
 	Use:   "workpackage [subject]",
@@ -103,6 +104,10 @@ func createOptions(subject string) map[work_packages.CreateOption]string {
 		options[work_packages.CreateParent] = fmt.Sprintf("%d", parentWorkPackageID)
 	}
 
+	if len(descriptionFlag) > 0 {
+		options[work_packages.CreateDescription] = descriptionFlag
+	}
+
 	return options
 }
 

cmd/create/work_package_test.go

@@ -60,7 +60,85 @@ func TestCreateWorkPackagePrintsDryRunJSONWithParent(t *testing.T) {
 
 	createWorkPackage(nil, []string{"Build reusable skill"})
 
-	expected := "{\"valid\":true,\"operation\":\"create\",\"project_id\":1482,\"parent_id\":74316,\"work_package\":{\"subject\":\"Build reusable skill\",\"type\":\"\"}}\n"
+	expected := "{\"valid\":true,\"operation\":\"create\",\"project_id\":1482,\"parent_id\":74316,\"work_package\":{\"subject\":\"Build reusable skill\",\"type\":\"\",\"description\":\"\"}}\n"
+	if activePrinter.Result != expected {
+		t.Fatalf("expected %s, got %s", expected, activePrinter.Result)
+	}
+}
+
+func TestCreateWorkPackagePrintsDryRunJSONWithDescription(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v3/work_packages/74316":
+			_, _ = io.WriteString(w, `{
+				"id": 74316,
+				"subject": "Expand op CLI to support scripted work package workflows",
+				"_embedded": {
+					"project": {
+						"id": 1482,
+						"identifier": "cli",
+						"name": "CLI"
+					}
+				},
+				"_links": {
+					"self": {"href": "/api/v3/work_packages/74316"},
+					"project": {"href": "/api/v3/projects/1482", "title": "CLI"},
+					"status": {"href": "/api/v3/statuses/1", "title": "new"},
+					"type": {"href": "/api/v3/types/6", "title": "Feature"},
+					"assignee": {"href": null, "title": ""}
+				}
+			}`)
+		case "/api/v3/projects/1482":
+			_, _ = io.WriteString(w, `{
+				"id": 1482,
+				"identifier": "cli",
+				"name": "CLI",
+				"_links": {
+					"types": {"href": "/api/v3/projects/1482/types/available"}
+				}
+			}`)
+		case "/api/v3/projects/1482/types/available":
+			_, _ = io.WriteString(w, `{
+				"_embedded": {
+					"elements": [
+						{
+							"id": 7,
+							"name": "Implementation",
+							"_links": {
+								"self": {"href": "/api/v3/types/7"}
+							}
+						}
+					]
+				}
+			}`)
+		default:
+			t.Fatalf("unexpected path %s", r.URL.Path)
+		}
+	}))
+	defer server.Close()
+
+	host, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requests.Init(host, "token", false)
+	routes.Init(host)
+
+	activePrinter := &printer.TestingPrinter{}
+	printer.Init(activePrinter)
+
+	projectId = 0
+	parentWorkPackageID = 74316
+	shouldOpenWorkPackageInBrowser = false
+	printCreatedWorkPackageAsJSON = true
+	dryRunCreateWorkPackage = true
+	typeFlag = "Implementation"
+	descriptionFlag = "Body"
+
+	createWorkPackage(nil, []string{"Add explicit work package description support"})
+
+	expected := "{\"valid\":true,\"operation\":\"create\",\"project_id\":1482,\"parent_id\":74316,\"work_package\":{\"subject\":\"Add explicit work package description support\",\"type\":\"Implementation\",\"description\":\"Body\"}}\n"
 	if activePrinter.Result != expected {
 		t.Fatalf("expected %s, got %s", expected, activePrinter.Result)
 	}

cmd/update/update.go

@@ -43,6 +43,12 @@ func addWorkPackageFlags() {
 		"",
 		"Change the subject of the work package",
 	)
+	workPackageCmd.Flags().StringVar(
+		&descriptionFlag,
+		"description",
+		"",
+		"Change the raw work package description",
+	)
 	workPackageCmd.Flags().StringVarP(
 		&typeFlag,
 		"type",

cmd/update/work_package.go

@@ -17,6 +17,7 @@ var (
 	actionFlag                    string
 	assigneeFlag                  uint64
 	attachFlag                    string
+	descriptionFlag               string
 	dryRunUpdateWorkPackage       bool
 	printUpdatedWorkPackageAsJSON bool
 	setFlags                      []string
@@ -100,17 +101,55 @@ func updateWorkPackage(_ *cobra.Command, args []string) {
 		return
 	}
 
-	if printUpdatedWorkPackageAsJSON || dryRunUpdateWorkPackage {
+	options := updateOptions()
+	if len(options) == 0 {
 		printUpdateError("invalid_argument", "--json and --dry-run currently require at least one --set value")
 		return
 	}
 
-	if workPackage, err := work_packages.Update(id, updateOptions()); err == nil {
-		printer.Info("-- ")
-		printer.WorkPackage(workPackage)
-	} else {
+	if dryRunUpdateWorkPackage {
+		plan := work_packages.DryRunUpdate(id, options)
+
+		data, err := presenter.MarshalJSON(plan)
+		if err != nil {
+			printer.Error(err)
+			return
+		}
+
+		printer.Info(string(data))
+		return
+	}
+
+	workPackage, err := work_packages.Update(id, options)
+	if err != nil {
+		if printUpdatedWorkPackageAsJSON {
+			printUpdateError("api_error", err.Error())
+			return
+		}
+
 		printer.Error(err)
+		return
 	}
+
+	if printUpdatedWorkPackageAsJSON {
+		payload, err := work_packages.Inspect(id)
+		if err != nil {
+			printUpdateError("api_error", err.Error())
+			return
+		}
+
+		data, err := presenter.MarshalJSON(payload)
+		if err != nil {
+			printer.Error(err)
+			return
+		}
+
+		printer.Info(string(data))
+		return
+	}
+
+	printer.Info("-- ")
+	printer.WorkPackage(workPackage)
 }
 
 func updateOptions() map[work_packages.UpdateOption]string {
@@ -127,6 +166,9 @@ func updateOptions() map[work_packages.UpdateOption]string {
 	if len(subjectFlag) > 0 {
 		options[work_packages.UpdateSubject] = subjectFlag
 	}
+	if len(descriptionFlag) > 0 {
+		options[work_packages.UpdateDescription] = descriptionFlag
+	}
 	if len(typeFlag) > 0 {
 		options[work_packages.UpdateType] = typeFlag
 	}
@@ -139,6 +181,13 @@ func validateUpdateWorkPackageFlags() error {
 		return fmt.Errorf("cannot use --dry-run without --json")
 	}
 
+	if len(descriptionFlag) > 0 {
+		conflicts := activeDescriptionConflicts()
+		if len(conflicts) > 0 {
+			return fmt.Errorf("cannot combine --description with %s", strings.Join(conflicts, ", "))
+		}
+	}
+
 	if len(setFlags) > 0 && hasLegacyUpdateFlags() {
 		return fmt.Errorf("cannot combine --set with %s", strings.Join(activeLegacyUpdateFlags(), ", "))
 	}
@@ -165,13 +214,29 @@ func activeLegacyUpdateFlags() []string {
 	if len(subjectFlag) > 0 {
 		flags = append(flags, "--subject")
 	}
+	if len(descriptionFlag) > 0 {
+		flags = append(flags, "--description")
+	}
 	if len(typeFlag) > 0 {
 		flags = append(flags, "--type")
 	}
 
 	return flags
 }
 
+func activeDescriptionConflicts() []string {
+	flags := []string{}
+
+	if len(actionFlag) > 0 {
+		flags = append(flags, "--action")
+	}
+	if len(attachFlag) > 0 {
+		flags = append(flags, "--attach")
+	}
+
+	return flags
+}
+
 func printUpdateError(code, message string) {
 	if !printUpdatedWorkPackageAsJSON {
 		printer.ErrorText(message)