refactor(api): split task done/undone into separate operations

Create markTaskDoneOp and markTaskUndoneOp as distinct operations.
CLI task done/undone commands now derive descriptions from their
respective operations. Zero hardcoded descriptions remain outside
parent grouping labels.

Author: Mearman

src/cli/commands/task.ts

@@ -3,7 +3,8 @@ import type { CommandDef } from "../define-command.js";
 import { loadDocument, saveDocument } from "../../io.js";
 import {
 	addPlanTaskOp,
-	updatePlanTaskOp,
+	markTaskDoneOp,
+	markTaskUndoneOp,
 	taskListOp,
 } from "../../operations/index.js";
 
@@ -107,8 +108,8 @@ const doneOpts = z.object({});
 
 const doneSubcommand: CommandDef<typeof doneArgs, typeof doneOpts> = {
 	name: "done",
-	// TODO: derive description from updatePlanTaskOp (conditional on done: true)
-	description: "Mark a task as done",
+	description: markTaskDoneOp.def.description,
+	apiLink: markTaskDoneOp.def.name,
 	args: doneArgs,
 	opts: doneOpts,
 	action(args) {
@@ -121,11 +122,10 @@ const doneSubcommand: CommandDef<typeof doneArgs, typeof doneOpts> = {
 		}
 
 		try {
-			const newDoc = updatePlanTaskOp({
+			const newDoc = markTaskDoneOp({
 				doc,
 				changeId: args.changeId,
 				taskIndex,
-				done: true,
 			});
 			saveDocument(newDoc, format, path);
 			console.log(`Marked task ${String(taskIndex)} done on ${args.changeId}`);
@@ -146,8 +146,8 @@ const undoneOpts = z.object({});
 
 const undoneSubcommand: CommandDef<typeof undoneArgs, typeof undoneOpts> = {
 	name: "undone",
-	// TODO: derive description from updatePlanTaskOp (conditional on done: false)
-	description: "Mark a task as undone",
+	description: markTaskUndoneOp.def.description,
+	apiLink: markTaskUndoneOp.def.name,
 	args: undoneArgs,
 	opts: undoneOpts,
 	action(args) {
@@ -160,11 +160,10 @@ const undoneSubcommand: CommandDef<typeof undoneArgs, typeof undoneOpts> = {
 		}
 
 		try {
-			const newDoc = updatePlanTaskOp({
+			const newDoc = markTaskUndoneOp({
 				doc,
 				changeId: args.changeId,
 				taskIndex,
-				done: false,
 			});
 			saveDocument(newDoc, format, path);
 			console.log(

src/operations/index.ts

@@ -15,6 +15,8 @@ export { nextIdOp } from "./next-id.js";
 export { initDocumentOp } from "./init-document.js";
 export { addPlanTaskOp } from "./add-plan-task.js";
 export { updatePlanTaskOp } from "./update-plan-task.js";
+export { markTaskDoneOp } from "./mark-task-done.js";
+export { markTaskUndoneOp } from "./mark-task-undone.js";
 export { taskListOp } from "./task-list.js";
 export { planInitOp } from "./plan-init.js";
 export { planAddTaskOp } from "./plan-add-task.js";

src/operations/mark-task-done.ts

@@ -0,0 +1,30 @@
+import * as z from "zod";
+import { defineOperation } from "./define-operation.js";
+import { SysProMDocument } from "../schema.js";
+
+export const markTaskDoneOp = defineOperation({
+	name: "markTaskDone",
+	description: "Mark a task as done",
+	input: z.object({
+		doc: SysProMDocument,
+		changeId: z.string().describe("ID of the change node"),
+		taskIndex: z.number().describe("Zero-based index of the task in the plan"),
+	}),
+	output: SysProMDocument,
+	fn: (input) => {
+		const node = input.doc.nodes.find((n) => n.id === input.changeId);
+		if (!node) throw new Error(`Node not found: ${input.changeId}`);
+		const plan = node.plan ?? [];
+		if (input.taskIndex < 0 || input.taskIndex >= plan.length) {
+			throw new Error(
+				`Task index ${String(input.taskIndex)} out of range (plan has ${String(plan.length)} task(s))`,
+			);
+		}
+		const newPlan = [...plan];
+		newPlan[input.taskIndex] = { ...newPlan[input.taskIndex], done: true };
+		const newNodes = input.doc.nodes.map((n) =>
+			n.id === input.changeId ? { ...n, plan: newPlan } : n,
+		);
+		return { ...input.doc, nodes: newNodes };
+	},
+});

src/operations/mark-task-undone.ts

@@ -0,0 +1,30 @@
+import * as z from "zod";
+import { defineOperation } from "./define-operation.js";
+import { SysProMDocument } from "../schema.js";
+
+export const markTaskUndoneOp = defineOperation({
+	name: "markTaskUndone",
+	description: "Mark a task as undone",
+	input: z.object({
+		doc: SysProMDocument,
+		changeId: z.string().describe("ID of the change node"),
+		taskIndex: z.number().describe("Zero-based index of the task in the plan"),
+	}),
+	output: SysProMDocument,
+	fn: (input) => {
+		const node = input.doc.nodes.find((n) => n.id === input.changeId);
+		if (!node) throw new Error(`Node not found: ${input.changeId}`);
+		const plan = node.plan ?? [];
+		if (input.taskIndex < 0 || input.taskIndex >= plan.length) {
+			throw new Error(
+				`Task index ${String(input.taskIndex)} out of range (plan has ${String(plan.length)} task(s))`,
+			);
+		}
+		const newPlan = [...plan];
+		newPlan[input.taskIndex] = { ...newPlan[input.taskIndex], done: false };
+		const newNodes = input.doc.nodes.map((n) =>
+			n.id === input.changeId ? { ...n, plan: newPlan } : n,
+		);
+		return { ...input.doc, nodes: newNodes };
+	},
+});