Merge pull request #160 from pasha-tw/feat/epics-create-comment

feat: add epics-create-comment tool

Author: andreasmcdermott

src/client/shortcut.ts

@@ -3,8 +3,10 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import type {
 	ShortcutClient as BaseClient,
+	CreateCommentComment,
 	CreateDoc,
 	CreateEpic,
+	CreateEpicComment,
 	CreateIteration,
 	CreateLabelParams,
 	CreateStoryComment,
@@ -26,6 +28,7 @@ import type {
 	StoryLink,
 	StorySlim,
 	Task,
+	ThreadedComment,
 	UpdateDoc,
 	UpdateEpic,
 	UpdateIteration,
@@ -446,6 +449,35 @@ export class ShortcutClientWrapper {
 		await this.client.deleteIteration(iterationPublicId);
 	}
 
+	async createEpicComment(
+		epicPublicId: number,
+		params: CreateEpicComment,
+	): Promise<ThreadedComment> {
+		const response = await this.client.createEpicComment(epicPublicId, params);
+		const epicComment = response?.data ?? null;
+
+		if (!epicComment) throw new Error(`Failed to create the comment: ${response.status}`);
+
+		return epicComment;
+	}
+
+	async createEpicCommentComment(
+		epicPublicId: number,
+		commentPublicId: number,
+		params: CreateCommentComment,
+	): Promise<ThreadedComment> {
+		const response = await this.client.createEpicCommentComment(
+			epicPublicId,
+			commentPublicId,
+			params,
+		);
+		const epicComment = response?.data ?? null;
+
+		if (!epicComment) throw new Error(`Failed to create the comment reply: ${response.status}`);
+
+		return epicComment;
+	}
+
 	async createEpic(params: CreateEpic): Promise<Epic> {
 		const response = await this.client.createEpic(params);
 		const epic = response?.data ?? null;

src/tools/epics.test.ts

@@ -113,10 +113,11 @@ describe("EpicTools", () => {
 			expect(mockToolRead.mock.calls?.[0]?.[0]).toBe("epics-get-by-id");
 			expect(mockToolRead.mock.calls?.[1]?.[0]).toBe("epics-search");
 
-			expect(mockToolWrite).toHaveBeenCalledTimes(3);
+			expect(mockToolWrite).toHaveBeenCalledTimes(4);
 			expect(mockToolWrite.mock.calls?.[0]?.[0]).toBe("epics-create");
 			expect(mockToolWrite.mock.calls?.[1]?.[0]).toBe("epics-update");
-			expect(mockToolWrite.mock.calls?.[2]?.[0]).toBe("epics-delete");
+			expect(mockToolWrite.mock.calls?.[2]?.[0]).toBe("epics-create-comment");
+			expect(mockToolWrite.mock.calls?.[3]?.[0]).toBe("epics-delete");
 		});
 	});
 
@@ -425,6 +426,102 @@ describe("EpicTools", () => {
 		});
 	});
 
+	describe("createEpicComment method", () => {
+		const getEpicMock = mock(async (id: number) => mockEpics.find((epic) => epic.id === id));
+		const createEpicCommentMock = mock(async (_id: number, _params: { text: string }) => ({
+			id: 100,
+			text: "Test comment",
+			app_url: "https://app.shortcut.com/test/epic/1/comments/100",
+		}));
+
+		beforeEach(() => {
+			createEpicCommentMock.mockClear();
+		});
+
+		test("should create a comment on an epic", async () => {
+			const mockClient = createMockClient({
+				getEpic: getEpicMock,
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+			const result = await epicTools.createEpicComment({
+				epicPublicId: 1,
+				text: "Test comment",
+			});
+
+			expect(getTextContent(result)).toBe(
+				"Created comment on epic 1. Comment URL: https://app.shortcut.com/test/epic/1/comments/100.",
+			);
+			expect(createEpicCommentMock).toHaveBeenCalledTimes(1);
+			expect(createEpicCommentMock.mock.calls?.[0]?.[0]).toBe(1);
+			expect(createEpicCommentMock.mock.calls?.[0]?.[1]).toMatchObject({
+				text: "Test comment",
+			});
+		});
+
+		test("should throw error when epic is not found", async () => {
+			const mockClient = createMockClient({
+				getEpic: mock(async () => null),
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+
+			await expect(() =>
+				epicTools.createEpicComment({
+					epicPublicId: 999,
+					text: "Test comment",
+				}),
+			).toThrow("Failed to retrieve Shortcut epic with public ID: 999");
+		});
+
+		test("should throw error when text is empty", async () => {
+			const mockClient = createMockClient({
+				getEpic: getEpicMock,
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+
+			await expect(() =>
+				epicTools.createEpicComment({
+					epicPublicId: 1,
+					text: "",
+				}),
+			).toThrow("Epic comment text is required");
+		});
+
+		test("should create a reply to an existing comment", async () => {
+			const createEpicCommentCommentMock = mock(
+				async (_epicId: number, _commentId: number, _params: { text: string }) => ({
+					id: 200,
+					text: "Reply comment",
+					app_url: "https://app.shortcut.com/test/epic/1/comments/200",
+				}),
+			);
+			const mockClient = createMockClient({
+				getEpic: getEpicMock,
+				createEpicComment: createEpicCommentMock,
+				createEpicCommentComment: createEpicCommentCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+			const result = await epicTools.createEpicComment({
+				epicPublicId: 1,
+				replyToCommentId: 100,
+				text: "Reply comment",
+			});
+
+			expect(getTextContent(result)).toBe(
+				"Created comment on epic 1. Comment URL: https://app.shortcut.com/test/epic/1/comments/200.",
+			);
+			expect(createEpicCommentMock).not.toHaveBeenCalled();
+			expect(createEpicCommentCommentMock).toHaveBeenCalledTimes(1);
+			expect(createEpicCommentCommentMock.mock.calls?.[0]?.[0]).toBe(1);
+			expect(createEpicCommentCommentMock.mock.calls?.[0]?.[1]).toBe(100);
+			expect(createEpicCommentCommentMock.mock.calls?.[0]?.[2]).toMatchObject({
+				text: "Reply comment",
+			});
+		});
+	});
+
 	describe("deleteEpic method", () => {
 		const getEpicMock = mock(async (id: number) => mockEpics.find((epic) => epic.id === id));
 		const deleteEpicMock = mock(async (_id: number) => undefined);

src/tools/epics.ts

@@ -93,6 +93,17 @@ export class EpicTools extends BaseTools {
 			async (params) => await tools.updateEpic(params),
 		);
 
+		server.addToolWithWriteAccess(
+			"epics-create-comment",
+			"Add a comment to an epic.",
+			{
+				epicPublicId: z.number().positive().describe("Epic ID"),
+				replyToCommentId: z.number().positive().optional().describe("Comment ID to reply to"),
+				text: z.string().min(1).describe("Comment text"),
+			},
+			async (params) => await tools.createEpicComment(params),
+		);
+
 		server.addToolWithWriteAccess(
 			"epics-delete",
 			"Delete an epic (cannot be undone).",
@@ -196,6 +207,35 @@ export class EpicTools extends BaseTools {
 		return this.toResult(`Updated epic ${epicPublicId}. Epic URL: ${updatedEpic.app_url}`);
 	}
 
+	async createEpicComment({
+		epicPublicId,
+		replyToCommentId,
+		text,
+	}: {
+		epicPublicId: number;
+		replyToCommentId?: number;
+		text: string;
+	}): Promise<CallToolResult> {
+		if (!epicPublicId) throw new Error("Epic public ID is required");
+		if (!text) throw new Error("Epic comment text is required");
+
+		const epic = await this.client.getEpic(epicPublicId);
+		if (!epic)
+			throw new Error(`Failed to retrieve Shortcut epic with public ID: ${epicPublicId}`);
+
+		const epicComment = replyToCommentId
+			? await this.client.createEpicCommentComment(epicPublicId, replyToCommentId, {
+					text,
+				})
+			: await this.client.createEpicComment(epicPublicId, {
+					text,
+				});
+
+		return this.toResult(
+			`Created comment on epic ${epicPublicId}. Comment URL: ${epicComment.app_url}.`,
+		);
+	}
+
 	async deleteEpic(epicPublicId: number): Promise<CallToolResult> {
 		const epic = await this.client.getEpic(epicPublicId);
 		if (!epic) throw new Error(`Failed to retrieve Shortcut epic with public ID: ${epicPublicId}`);