@llodev/pm-tasks-clickup 0.0.0-pr-130-7078a2a → 0.0.0-stage

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/README.md +2 -195
  2. package/package.json +3 -61
  3. package/LICENSE +0 -21
  4. package/SKILL.md +0 -258
  5. package/anti-patterns/clickup.md +0 -73
  6. package/dist/adapter.d.ts +0 -39
  7. package/dist/adapter.d.ts.map +0 -1
  8. package/dist/adapter.js +0 -83
  9. package/dist/adapter.js.map +0 -1
  10. package/dist/bin/init.d.ts +0 -3
  11. package/dist/bin/init.d.ts.map +0 -1
  12. package/dist/bin/init.js +0 -20
  13. package/dist/bin/init.js.map +0 -1
  14. package/dist/doctor-cli.d.ts +0 -27
  15. package/dist/doctor-cli.d.ts.map +0 -1
  16. package/dist/doctor-cli.js +0 -315
  17. package/dist/doctor-cli.js.map +0 -1
  18. package/dist/env.d.ts +0 -6
  19. package/dist/env.d.ts.map +0 -1
  20. package/dist/env.js +0 -11
  21. package/dist/env.js.map +0 -1
  22. package/dist/envelope.d.ts +0 -44
  23. package/dist/envelope.d.ts.map +0 -1
  24. package/dist/envelope.js +0 -95
  25. package/dist/envelope.js.map +0 -1
  26. package/dist/errors.d.ts +0 -30
  27. package/dist/errors.d.ts.map +0 -1
  28. package/dist/errors.js +0 -60
  29. package/dist/errors.js.map +0 -1
  30. package/dist/estimation.d.ts +0 -20
  31. package/dist/estimation.d.ts.map +0 -1
  32. package/dist/estimation.js +0 -40
  33. package/dist/estimation.js.map +0 -1
  34. package/dist/index.d.ts +0 -5
  35. package/dist/index.d.ts.map +0 -1
  36. package/dist/index.js +0 -3
  37. package/dist/index.js.map +0 -1
  38. package/dist/init-api.d.ts +0 -67
  39. package/dist/init-api.d.ts.map +0 -1
  40. package/dist/init-api.js +0 -271
  41. package/dist/init-api.js.map +0 -1
  42. package/dist/init-flow.d.ts +0 -27
  43. package/dist/init-flow.d.ts.map +0 -1
  44. package/dist/init-flow.js +0 -206
  45. package/dist/init-flow.js.map +0 -1
  46. package/dist/status-map.d.ts +0 -31
  47. package/dist/status-map.d.ts.map +0 -1
  48. package/dist/status-map.js +0 -38
  49. package/dist/status-map.js.map +0 -1
  50. package/dist/status.d.ts +0 -17
  51. package/dist/status.d.ts.map +0 -1
  52. package/dist/status.js +0 -21
  53. package/dist/status.js.map +0 -1
  54. package/dist/transport-clickup.d.ts +0 -99
  55. package/dist/transport-clickup.d.ts.map +0 -1
  56. package/dist/transport-clickup.js +0 -676
  57. package/dist/transport-clickup.js.map +0 -1
  58. package/docs/i18n/README.es-ES.md +0 -196
  59. package/docs/i18n/README.pt-BR.md +0 -196
  60. package/i18n/en-US.json +0 -62
  61. package/i18n/es-ES.json +0 -62
  62. package/i18n/pt-BR.json +0 -62
  63. package/manifest.json +0 -14
  64. package/references/autonomous.md +0 -85
  65. package/references/estimation.md +0 -115
  66. package/references/operations.md +0 -128
  67. package/schemas/config.json +0 -140
@@ -1,676 +0,0 @@
1
- /**
2
- * ClickUp MCP transport: implements the @llodev/pm-tasks-core Transport by
3
- * dispatching each canonical verb to `clickup_*` tools. The MCP dispatcher is
4
- * injected, so this module is testable with a recording stub, has no side
5
- * effects on import, and references no `mcp__*` symbol at build time.
6
- *
7
- * ClickUp specifics:
8
- * - Tool names are passed without the server prefix (`clickup_create_task`).
9
- * - Every call carries `workspace_id: config.workspace.id`.
10
- * - Writes return an envelope, reads a bare task (see envelope.ts); a resolved
11
- * `{error}` is handled like a thrown error.
12
- * - Status names are pinned per list in config and resolved by role (status.ts).
13
- */
14
- import { normalizeEstimate } from "@llodev/pm-tasks-core/estimation";
15
- import { callTool, epochToIso, idString, isObj, taskUrl, unwrapTask, } from "./envelope.js";
16
- import { classifyError, invalidRequest, shapeError } from "./errors.js";
17
- import { DEFAULT_HOURS_PER_DAY, slugify, toMinutes } from "./estimation.js";
18
- import { resolveStatus, statusKey } from "./status.js";
19
- // ---------------------------------------------------------------------------
20
- // Internal helpers
21
- // ---------------------------------------------------------------------------
22
- const PRIORITIES = new Map([
23
- ["urgent", "urgent"],
24
- ["high", "high"],
25
- ["normal", "normal"],
26
- ["medium", "normal"],
27
- ["low", "low"],
28
- ]);
29
- /** Native priority name; undefined (omitted from the call) when unknown. */
30
- function mapPriority(priority) {
31
- return typeof priority === "string" ? PRIORITIES.get(priority.trim().toLowerCase()) : undefined;
32
- }
33
- const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/;
34
- /**
35
- * A string that starts with a real calendar date (`YYYY-MM-DD`). Date rolls
36
- * `2026-02-30` over to March, so the prefix must survive a round trip.
37
- */
38
- function isCalendarDate(value) {
39
- if (typeof value !== "string" || !DATE_PREFIX.test(value))
40
- return false;
41
- const date = value.slice(0, 10);
42
- const parsed = new Date(`${date}T00:00:00Z`);
43
- return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === date;
44
- }
45
- /** Description with the `[ct:<token>]` footer, appended once. */
46
- function withClientToken(description, clientToken) {
47
- const body = description ?? "";
48
- if (!clientToken)
49
- return body;
50
- const marker = `[ct:${clientToken}]`;
51
- if (body.includes(marker))
52
- return body;
53
- return body.trim() === "" ? marker : `${body.trimEnd()}\n\n${marker}`;
54
- }
55
- /** `task.move` role words; a Map so prototype keys such as "constructor" never match. */
56
- const ROLES = new Map([
57
- ["open", "open"],
58
- ["wip", "wip"],
59
- ["done", "done"],
60
- ]);
61
- /** A `task.move` target of six or more digits is a destination list id. */
62
- const LIST_ID = /^\d{6,}$/;
63
- /** `update_task` answer when the status is not in the task's list (renamed or removed). */
64
- const STATUS_REJECTED = /status does not exist/i;
65
- /** Status names compare case-insensitively and trimmed; the pinned name is sent verbatim. */
66
- function sameStatus(current, pinned) {
67
- return statusKey(current) === statusKey(pinned);
68
- }
69
- /**
70
- * INVALID_REQUEST (`id_required`, naming the field) for the first id that is not a
71
- * non-blank string; null when every id is usable. Runs before any MCP call.
72
- */
73
- function missingId(verb, ids) {
74
- for (const [field, value] of Object.entries(ids)) {
75
- if (typeof value !== "string" || value.trim() === "") {
76
- return invalidRequest(verb, "id_required", `${field} must be a non-empty id`, { field });
77
- }
78
- }
79
- return null;
80
- }
81
- /** A thrown or resolved MCP failure, classified. */
82
- function failure(e) {
83
- const { code, details } = classifyError(e);
84
- return { ok: false, code, details };
85
- }
86
- /** The idempotency short-circuit: the requested state already holds, nothing was written. */
87
- function alreadyInState(verb, details) {
88
- return { ok: false, code: "ALREADY_IN_STATE", details: { ...details, verb } };
89
- }
90
- /** A verb ClickUp, or this config, cannot carry out; `reason` is a stable token. */
91
- function notApplicable(verb, reason, message) {
92
- return { ok: false, code: "NOT_APPLICABLE", details: { verb, reason, message } };
93
- }
94
- /**
95
- * A failed `task.estimate.set` write. Before anything was written it is the plain
96
- * classified failure. After a write it is partial: MCP_ERROR with
97
- * `partial`, the steps already applied and the failed one. An auth or rate-limit
98
- * failure keeps its code, so the caller still knows to sign in again or wait.
99
- */
100
- function stepFailure(failed, applied, failedStep) {
101
- if (applied.length === 0)
102
- return failed;
103
- const code = failed.code === "AUTH_ERROR" || failed.code === "RATE_LIMITED" ? failed.code : "MCP_ERROR";
104
- return {
105
- ok: false,
106
- code,
107
- details: {
108
- ...failed.details,
109
- verb: "task.estimate.set",
110
- partial: true,
111
- applied: [...applied],
112
- failedStep,
113
- },
114
- };
115
- }
116
- /**
117
- * Raw `get_task` fields a verb relies on beyond list, status and parent, checked so
118
- * a partial read never passes for a real value. `unwrapTask` reads a missing
119
- * `assignees` array as "nobody" and drops an entry without an id, so the union
120
- * write would unassign people; a missing `due_date` would read as "no due date";
121
- * missing `tags` as "no est: tag" (a second one would be added); a missing
122
- * `subtasks_count` as a leaf (the native estimate would land on a parent); and
123
- * without `space.id` the est: tag cannot be created after the estimate write.
124
- */
125
- const READ_CHECKS = {
126
- assignees: (raw, task) => Array.isArray(raw.assignees) && raw.assignees.length === task.assigneeIds.length,
127
- due_date: (raw, task) => raw.due_date === null || task.dueDate !== null,
128
- tags: (raw, task) => Array.isArray(raw.tags) && raw.tags.length === task.tagNames.length,
129
- subtasks_count: (raw) => typeof raw.subtasks_count === "number",
130
- space: (_raw, task) => task.spaceId !== undefined,
131
- };
132
- /** A ClickUp user id: digits only. Anything else ("me", an email, a name) is resolved. */
133
- const USER_ID = /^\d+$/;
134
- /** `clickup_create_comment.comment_text` maxLength (live schema). */
135
- const COMMENT_MAX_LENGTH = 40000;
136
- /** `utc_offset` of `clickup_get_user` ("-03:00", "+05:30") in minutes; null when unreadable. */
137
- function offsetMinutes(value) {
138
- const m = typeof value === "string" ? /^([+-])(\d{2}):?(\d{2})$/.exec(value) : null;
139
- if (!m)
140
- return null;
141
- const hours = Number(m[2]);
142
- const minutes = Number(m[3]);
143
- if (hours > 14 || minutes > 59)
144
- return null;
145
- return (m[1] === "-" ? -1 : 1) * (hours * 60 + minutes);
146
- }
147
- /** The calendar date (YYYY-MM-DD) of an ISO instant at a fixed UTC offset in minutes. */
148
- function localDate(iso, offset) {
149
- return new Date(Date.parse(iso) + offset * 60_000).toISOString().slice(0, 10);
150
- }
151
- /**
152
- * The comment carrying `marker` on a `clickup_get_task_comments` page, or null.
153
- * ClickUp keeps the marker verbatim and appends a newline to `comment_text`, so
154
- * this is a substring match. An unreadable page, or a match without an id or a
155
- * date, is a shape error: posting anyway could duplicate the comment.
156
- */
157
- function markedComment(resp, marker, verb) {
158
- if (!isObj(resp) || !Array.isArray(resp.comments))
159
- return shapeError(verb);
160
- for (const comment of resp.comments) {
161
- if (!isObj(comment) || typeof comment.comment_text !== "string")
162
- continue;
163
- if (!comment.comment_text.includes(marker))
164
- continue;
165
- const commentId = idString(comment.id);
166
- const postedAt = epochToIso(comment.date);
167
- if (commentId === undefined || postedAt === null)
168
- return shapeError(verb);
169
- return { ok: true, data: { commentId, postedAt } };
170
- }
171
- return { ok: true, data: null };
172
- }
173
- // ---------------------------------------------------------------------------
174
- // Factory
175
- // ---------------------------------------------------------------------------
176
- export function createClickUpTransport(opts) {
177
- const { mcp, config } = opts;
178
- const workspaceId = config.workspace.id;
179
- /** Every ClickUp call carries the configured workspace. */
180
- const call = (tool, args) => callTool(mcp, tool, { ...args, workspace_id: workspaceId });
181
- /**
182
- * One compact `clickup_get_task`: the only trusted source of a task's status,
183
- * home list and parent. A bare task always carries `list.id`, a status name and
184
- * a `parent` key (null for a root task). A write envelope or a partial read
185
- * lacks one of them, and `unwrapTask` would default it (no status, parentId
186
- * null): trusting that skips a write or lets a subtask pass as a root task, so
187
- * it is a shape error instead. `checks` names the further fields the verb
188
- * relies on (READ_CHECKS).
189
- */
190
- async function readTask(taskId, verb, checks = []) {
191
- try {
192
- const raw = await call("clickup_get_task", { task_id: taskId });
193
- const task = unwrapTask(raw);
194
- if (!task || task.listId === undefined || task.status === undefined) {
195
- return shapeError(verb);
196
- }
197
- const fields = raw;
198
- const parent = fields.parent;
199
- if (parent !== null && (typeof parent !== "string" || parent === "")) {
200
- return shapeError(verb);
201
- }
202
- if (!checks.every((field) => READ_CHECKS[field](fields, task)))
203
- return shapeError(verb);
204
- return { ok: true, data: { ...task, listId: task.listId, status: task.status } };
205
- }
206
- catch (e) {
207
- return failure(e);
208
- }
209
- }
210
- /** `clickup_update_task` on one task: null on success, the classified failure otherwise. */
211
- async function updateTask(taskId, fields) {
212
- try {
213
- await call("clickup_update_task", { task_id: taskId, ...fields });
214
- return null;
215
- }
216
- catch (e) {
217
- return failure(e);
218
- }
219
- }
220
- /**
221
- * The account's UTC offset in minutes, from `clickup_get_user`, read once
222
- * per transport; parallel callers share the read in flight. A failure or an
223
- * unreadable offset resolves null and is dropped, so the next call reads again.
224
- */
225
- let offsetRead;
226
- function accountOffset() {
227
- offsetRead ??= call("clickup_get_user", {})
228
- .then((user) => offsetMinutes(isObj(user) ? user.utc_offset : undefined), () => null)
229
- .then((offset) => {
230
- if (offset === null)
231
- offsetRead = undefined;
232
- return offset;
233
- });
234
- return offsetRead;
235
- }
236
- /**
237
- * The numeric user id for `userId`. Digits are used as given; "me", an email or
238
- * a username goes through `clickup_resolve_assignees`, which answers null for a
239
- * name shared by several users. Anything but exactly one numeric id fails closed
240
- * as `assignee_unresolved`, without echoing the input; an auth or rate-limit
241
- * failure keeps its code, since it is not about the user.
242
- */
243
- async function resolveAssignee(userId) {
244
- if (USER_ID.test(userId))
245
- return { ok: true, data: userId };
246
- const unresolved = invalidRequest("task.assignee.add", "assignee_unresolved", "userId did not resolve to exactly one ClickUp user; pass a user id or a unique email");
247
- try {
248
- const resp = await call("clickup_resolve_assignees", { assignees: [userId] });
249
- const ids = isObj(resp) && Array.isArray(resp.userIds) ? resp.userIds : [];
250
- const id = ids.length === 1 ? idString(ids[0]) : undefined;
251
- return id !== undefined && USER_ID.test(id) ? { ok: true, data: id } : unresolved;
252
- }
253
- catch (e) {
254
- const failed = failure(e);
255
- return failed.code === "AUTH_ERROR" || failed.code === "RATE_LIMITED" ? failed : unresolved;
256
- }
257
- }
258
- /** The status pinned for `role` in the task's home list; fails closed when unpinned. */
259
- function pinnedStatus(verb, task, role) {
260
- const resolved = resolveStatus(config, task.listId, role);
261
- if (resolved.ok)
262
- return resolved;
263
- if (resolved.reason === "list_not_configured") {
264
- return invalidRequest(verb, resolved.reason, "The task's list is not in config.lists; register it with init", { listId: task.listId });
265
- }
266
- return invalidRequest(verb, resolved.reason, `No status is pinned for role "${role}" in the task's list; pin it with init`, { listId: task.listId, role });
267
- }
268
- /**
269
- * `clickup_update_task {status}`. A status ClickUp rejects (renamed or removed
270
- * after init) fails closed as `status_rejected`; any other error is classified.
271
- * Returns null on success.
272
- */
273
- async function writeStatus(verb, task, status) {
274
- const failed = await updateTask(task.id, { status });
275
- if (failed === null || !STATUS_REJECTED.test(String(failed.details.message)))
276
- return failed;
277
- return invalidRequest(verb, "status_rejected", "ClickUp rejected the pinned status (renamed or removed after init); run init again", { status, listId: task.listId });
278
- }
279
- /** `task.move` to a list id: `clickup_move_task`, root tasks only. */
280
- async function moveToList(task, listId) {
281
- const verb = "task.move";
282
- if (task.listId === listId)
283
- return alreadyInState(verb, { listId: task.listId });
284
- if (task.parentId !== null) {
285
- return invalidRequest(verb, "subtask_cannot_move", "ClickUp moves root tasks only; move the parent task instead");
286
- }
287
- try {
288
- const resp = await call("clickup_move_task", { task_id: task.id, list_id: listId });
289
- // `{success, task_id, custom_id, new_list_id}`; fall back to the requested id.
290
- const reported = typeof resp === "object" && resp !== null
291
- ? resp.new_list_id
292
- : undefined;
293
- const newListId = typeof reported === "string" && reported !== "" ? reported : listId;
294
- return {
295
- ok: true,
296
- data: { previousListOrSectionId: task.listId, newListOrSectionId: newListId },
297
- };
298
- }
299
- catch (e) {
300
- return failure(e);
301
- }
302
- }
303
- return {
304
- // -------------------------------------------------------------------
305
- // task.create → clickup_create_task
306
- //
307
- // boardOrProjectId = list id; listOrSectionId = initial status name
308
- // (empty → the list's default). `estimate` is not written here: the
309
- // estimate goes through task.estimate.set.
310
- // -------------------------------------------------------------------
311
- async taskCreate(req) {
312
- const verb = "task.create";
313
- if (typeof req.boardOrProjectId !== "string" || req.boardOrProjectId.trim() === "") {
314
- return invalidRequest(verb, "list_required", "boardOrProjectId (the list id) is required");
315
- }
316
- // null is treated like an absent dueDate; "" is still invalid.
317
- if (req.dueDate != null && !isCalendarDate(req.dueDate)) {
318
- return invalidRequest(verb, "invalid_due_date", "dueDate must start with a calendar date (YYYY-MM-DD)");
319
- }
320
- const args = { list_id: req.boardOrProjectId, name: req.name };
321
- const status = typeof req.listOrSectionId === "string" ? req.listOrSectionId.trim() : "";
322
- if (status !== "")
323
- args.status = status;
324
- const description = withClientToken(req.description, req.clientToken);
325
- if (description.trim() !== "")
326
- args.markdown_description = description;
327
- if (req.labels && req.labels.length > 0)
328
- args.tags = req.labels;
329
- const priority = mapPriority(req.priority);
330
- if (priority !== undefined)
331
- args.priority = priority;
332
- if (req.dueDate != null)
333
- args.due_date = req.dueDate.slice(0, 10);
334
- try {
335
- const task = unwrapTask(await call("clickup_create_task", args));
336
- if (!task)
337
- return shapeError(verb);
338
- return { ok: true, data: { id: task.id, url: task.url ?? taskUrl(task.id) } };
339
- }
340
- catch (e) {
341
- return failure(e);
342
- }
343
- },
344
- // -------------------------------------------------------------------
345
- // task.move → clickup_update_task {status} or clickup_move_task
346
- //
347
- // open | wip | done (any case) → the status pinned for that role in the
348
- // task's home list. A digit string of six or more is a destination list
349
- // id → clickup_move_task (root tasks only). The task is read first; no
350
- // write when the requested status or list already holds.
351
- // -------------------------------------------------------------------
352
- async taskMove(req) {
353
- const verb = "task.move";
354
- const noId = missingId(verb, { taskId: req.taskId });
355
- if (noId)
356
- return noId;
357
- const target = typeof req.targetListOrSectionId === "string" ? req.targetListOrSectionId.trim() : "";
358
- const role = ROLES.get(target.toLowerCase());
359
- if (role === undefined && !LIST_ID.test(target)) {
360
- return invalidRequest(verb, "invalid_target", "targetListOrSectionId must be open, wip, done or a numeric list id");
361
- }
362
- const read = await readTask(req.taskId, verb);
363
- if (!read.ok)
364
- return read;
365
- const task = read.data;
366
- if (role === undefined)
367
- return moveToList(task, target);
368
- const pinned = pinnedStatus(verb, task, role);
369
- if (!pinned.ok)
370
- return pinned;
371
- if (sameStatus(task.status, pinned.status)) {
372
- return alreadyInState(verb, { status: pinned.status });
373
- }
374
- const failed = await writeStatus(verb, task, pinned.status);
375
- if (failed)
376
- return failed;
377
- return {
378
- ok: true,
379
- data: { previousListOrSectionId: task.status, newListOrSectionId: pinned.status },
380
- };
381
- },
382
- // -------------------------------------------------------------------
383
- // checklist.check → clickup_update_task {status} on a subtask
384
- //
385
- // Checklist items are subtasks: itemId = the subtask, checklistId = its
386
- // parent. complete → the pinned `done` status, incomplete → `open`. The
387
- // item is complete when its status is the pinned `done` status.
388
- // -------------------------------------------------------------------
389
- async checklistCheck(req) {
390
- const verb = "checklist.check";
391
- const noId = missingId(verb, { itemId: req.itemId, checklistId: req.checklistId });
392
- if (noId)
393
- return noId;
394
- if (req.targetState !== "complete" && req.targetState !== "incomplete") {
395
- return invalidRequest(verb, "invalid_target_state", "targetState must be complete or incomplete");
396
- }
397
- const read = await readTask(req.itemId, verb);
398
- if (!read.ok)
399
- return read;
400
- const item = read.data;
401
- if (item.parentId !== req.checklistId) {
402
- return invalidRequest(verb, "not_a_checklist_item", "itemId must be a subtask whose parent is checklistId");
403
- }
404
- const done = pinnedStatus(verb, item, "done");
405
- if (!done.ok)
406
- return done;
407
- const previousState = sameStatus(item.status, done.status) ? "complete" : "incomplete";
408
- if (previousState === req.targetState) {
409
- return alreadyInState(verb, { state: previousState });
410
- }
411
- const target = req.targetState === "complete" ? done : pinnedStatus(verb, item, "open");
412
- if (!target.ok)
413
- return target;
414
- const failed = await writeStatus(verb, item, target.status);
415
- if (failed)
416
- return failed;
417
- return { ok: true, data: { previousState, newState: req.targetState } };
418
- },
419
- // -------------------------------------------------------------------
420
- // task.close → clickup_update_task {status: pinned done}
421
- //
422
- // Already at the pinned done status, or at the pinned closed status (a
423
- // cancelled task is not turned into done) → {closed: true} with no write.
424
- // closeListOrSectionId is ignored: closing never changes the list.
425
- // -------------------------------------------------------------------
426
- async taskClose(req) {
427
- const verb = "task.close";
428
- const noId = missingId(verb, { taskId: req.taskId });
429
- if (noId)
430
- return noId;
431
- const read = await readTask(req.taskId, verb);
432
- if (!read.ok)
433
- return read;
434
- const task = read.data;
435
- const done = pinnedStatus(verb, task, "done");
436
- if (!done.ok)
437
- return done;
438
- const closed = resolveStatus(config, task.listId, "closed");
439
- const alreadyClosed = sameStatus(task.status, done.status) ||
440
- (closed.ok && sameStatus(task.status, closed.status));
441
- if (!alreadyClosed) {
442
- const failed = await writeStatus(verb, task, done.status);
443
- if (failed)
444
- return failed;
445
- }
446
- return { ok: true, data: { closed: true } };
447
- },
448
- // -------------------------------------------------------------------
449
- // task.due-date.set → clickup_update_task {due_date: YYYY-MM-DD}
450
- //
451
- // ClickUp stores a date-only value at 04:00 local time of the account
452
- // timezone. The write is skipped when the stored instant's LOCAL date
453
- // (account offset from clickup_get_user) is the requested date; without a
454
- // readable offset it writes anyway. A one-hour DST gap cannot move 04:00
455
- // across midnight. previousDueAt is the stored ISO instant; newDueAt is
456
- // the date written (YYYY-MM-DD), since ClickUp keeps no time of day.
457
- // -------------------------------------------------------------------
458
- async taskDueDateSet(req) {
459
- const verb = "task.due-date.set";
460
- const noId = missingId(verb, { taskId: req.taskId });
461
- if (noId)
462
- return noId;
463
- if (!isCalendarDate(req.dueAt)) {
464
- return invalidRequest(verb, "invalid_due_date", "dueAt must start with a calendar date (YYYY-MM-DD)");
465
- }
466
- const date = req.dueAt.slice(0, 10);
467
- const read = await readTask(req.taskId, verb, ["due_date"]);
468
- if (!read.ok)
469
- return read;
470
- const task = read.data;
471
- const data = { previousDueAt: task.dueDate, newDueAt: date };
472
- if (task.dueDate !== null) {
473
- const offset = await accountOffset();
474
- if (offset !== null && localDate(task.dueDate, offset) === date)
475
- return { ok: true, data };
476
- }
477
- const failed = await updateTask(task.id, { due_date: date });
478
- return failed ?? { ok: true, data };
479
- },
480
- // -------------------------------------------------------------------
481
- // task.assignee.add → clickup_update_task {assignees: current ∪ new}
482
- //
483
- // `assignees` replaces the whole set, so the write is the union of
484
- // the assignees just read and the new id; v1 never removes. A non-numeric
485
- // userId ("me", an email) is resolved to an id first. Already assigned →
486
- // {added: false} with no write.
487
- // -------------------------------------------------------------------
488
- async taskAssigneeAdd(req) {
489
- const verb = "task.assignee.add";
490
- const noId = missingId(verb, { taskId: req.taskId, userId: req.userId });
491
- if (noId)
492
- return noId;
493
- const user = await resolveAssignee(req.userId.trim());
494
- if (!user.ok)
495
- return user;
496
- const read = await readTask(req.taskId, verb, ["assignees"]);
497
- if (!read.ok)
498
- return read;
499
- const current = read.data.assigneeIds;
500
- if (current.includes(user.data)) {
501
- return { ok: true, data: { added: false, currentAssigneeIds: current } };
502
- }
503
- const assignees = [...current, user.data];
504
- const failed = await updateTask(read.data.id, { assignees });
505
- return failed ?? { ok: true, data: { added: true, currentAssigneeIds: assignees } };
506
- },
507
- // -------------------------------------------------------------------
508
- // task.comment.add → clickup_create_comment {entity_type: "task"}
509
- //
510
- // With a clientToken the text is posted as `[ct:<token>] <text>`, after a
511
- // scan of the task's first comments page: a comment already carrying the
512
- // marker is returned instead of posting again. The attribution
513
- // prefix, when configured, is already in `text`.
514
- // -------------------------------------------------------------------
515
- async taskCommentAdd(req) {
516
- const verb = "task.comment.add";
517
- const noId = missingId(verb, { taskId: req.taskId });
518
- if (noId)
519
- return noId;
520
- if (typeof req.text !== "string" || req.text.trim() === "") {
521
- return invalidRequest(verb, "text_required", "text must be a non-empty comment");
522
- }
523
- const marker = req.clientToken ? `[ct:${req.clientToken}]` : undefined;
524
- const text = marker === undefined ? req.text : `${marker} ${req.text}`;
525
- if (text.length > COMMENT_MAX_LENGTH) {
526
- return invalidRequest(verb, "text_too_long", `The comment, with its [ct:] marker, exceeds ${COMMENT_MAX_LENGTH} characters`);
527
- }
528
- try {
529
- if (marker !== undefined) {
530
- const page = await call("clickup_get_task_comments", { task_id: req.taskId });
531
- const found = markedComment(page, marker, verb);
532
- if (!found.ok)
533
- return found;
534
- if (found.data !== null)
535
- return { ok: true, data: found.data };
536
- }
537
- const resp = await call("clickup_create_comment", {
538
- entity_type: "task",
539
- entity_id: req.taskId,
540
- comment_text: text,
541
- });
542
- // `{success, comment_id}`: no timestamp, so the comment was posted now.
543
- const commentId = isObj(resp) ? idString(resp.comment_id) : undefined;
544
- if (commentId === undefined)
545
- return shapeError(verb);
546
- return { ok: true, data: { commentId, postedAt: new Date().toISOString() } };
547
- }
548
- catch (e) {
549
- return failure(e);
550
- }
551
- },
552
- // -------------------------------------------------------------------
553
- // task.parent.set → clickup_update_task {parent}
554
- //
555
- // The server also moves the task into the parent's list; the response
556
- // type has no field for it, so it is not reported. The MCP cannot
557
- // clear a parent: a missing parentId is NOT_APPLICABLE. Already under
558
- // that parent → no write. parentId is trimmed once, before every use.
559
- // -------------------------------------------------------------------
560
- async taskParentSet(req) {
561
- const verb = "task.parent.set";
562
- const noId = missingId(verb, { taskId: req.taskId });
563
- if (noId)
564
- return noId;
565
- const requested = req.parentId;
566
- const parentId = typeof requested === "string" ? requested.trim() : "";
567
- if (parentId === "") {
568
- return notApplicable(verb, "detach_unsupported", "ClickUp cannot turn a subtask back into a top-level task through the MCP");
569
- }
570
- if (parentId === req.taskId.trim()) {
571
- return invalidRequest(verb, "self_parent", "A task cannot be its own parent");
572
- }
573
- const read = await readTask(req.taskId, verb);
574
- if (!read.ok)
575
- return read;
576
- const task = read.data;
577
- const data = { previousParentId: task.parentId, newParentId: parentId };
578
- if (task.parentId === parentId)
579
- return { ok: true, data };
580
- const failed = await updateTask(task.id, { parent: parentId });
581
- return failed ?? { ok: true, data };
582
- },
583
- // -------------------------------------------------------------------
584
- // task.estimate.set → clickup_update_task {time_estimate} + est:<slug> tag
585
- //
586
- // On or off: .clickup.json must declare `estimation`, and neither it nor
587
- // the request config may say `enabled: false` (NOT_APPLICABLE). The
588
- // request config then drives strategy, clickupTarget, scale, sizeMap and
589
- // hoursPerDay. The native estimate (whole minutes) is written only when
590
- // clickupTarget is "time", the strategy yields a time, and the task is a
591
- // leaf: ClickUp keeps a parent's own estimate, and roll-up views would add
592
- // its children's to it. The `est:<slug>` tag is always replace-set:
593
- // every other `est:*` tag is removed, the tag is ensured in the space and
594
- // added. What the task already holds is not written again. A failure
595
- // after a write is partial.
596
- // -------------------------------------------------------------------
597
- async taskEstimateSet(req) {
598
- const verb = "task.estimate.set";
599
- const requested = req.config;
600
- if (!isObj(config.estimation) ||
601
- config.estimation.enabled === false ||
602
- (isObj(requested) && requested.enabled === false)) {
603
- return notApplicable(verb, "estimation_disabled", "Estimation is disabled: no estimation block in .clickup.json, or enabled is false");
604
- }
605
- const noId = missingId(verb, { taskId: req.taskId });
606
- if (noId)
607
- return noId;
608
- if (!isObj(requested)) {
609
- return invalidRequest(verb, "estimation_config_required", "config (the estimation block of .clickup.json) is required");
610
- }
611
- const { strategy, clickupTarget, scale, sizeMap } = req.config;
612
- const hoursPerDay = req.config.hoursPerDay ?? DEFAULT_HOURS_PER_DAY;
613
- if (typeof hoursPerDay !== "number" || !(hoursPerDay >= 1 && hoursPerDay <= 24)) {
614
- return invalidRequest(verb, "invalid_hours_per_day", "estimation.hoursPerDay must be a number from 1 to 24");
615
- }
616
- // Core's `jiraTarget` is the adapter-local target: "time" or "none".
617
- const jiraTarget = clickupTarget === "time" ? "time" : "none";
618
- const result = normalizeEstimate(req.input, { strategy, jiraTarget, scale, sizeMap });
619
- if (!result.ok) {
620
- return invalidRequest(verb, "invalid_estimate", "The estimate does not fit the strategy");
621
- }
622
- const normalized = result.value;
623
- const minutes = normalized.timeString === undefined
624
- ? undefined
625
- : toMinutes(normalized.timeString, hoursPerDay);
626
- if (minutes !== undefined && !(Number.isSafeInteger(minutes) && minutes > 0)) {
627
- return invalidRequest(verb, "invalid_estimate", "A time estimate must be a finite duration of at least one minute");
628
- }
629
- const tag = `est:${slugify(normalized.humanReadable)}`;
630
- if (tag === "est:") {
631
- return invalidRequest(verb, "invalid_estimate", "The estimate has no letter or digit for its tag");
632
- }
633
- const read = await readTask(req.taskId, verb, ["tags", "subtasks_count", "space"]);
634
- if (!read.ok)
635
- return read;
636
- const task = read.data;
637
- // The writes, in order: the native estimate first, then the tag.
638
- const steps = [];
639
- const timed = jiraTarget === "time" && minutes !== undefined && task.subtaskCount === 0;
640
- if (timed && task.timeEstimateMs !== minutes * 60_000) {
641
- steps.push([
642
- "time_estimate",
643
- "clickup_update_task",
644
- { task_id: task.id, time_estimate: String(minutes) },
645
- ]);
646
- }
647
- // ClickUp stores tag names lowercased and removes them ignoring case.
648
- const estTags = task.tagNames.filter((name) => name.toLowerCase().startsWith("est:"));
649
- for (const name of estTags) {
650
- if (name.toLowerCase() === tag)
651
- continue;
652
- steps.push([
653
- "tag_remove",
654
- "clickup_remove_tag_from_task",
655
- { task_id: task.id, tag_name: name },
656
- ]);
657
- }
658
- if (!estTags.some((name) => name.toLowerCase() === tag)) {
659
- steps.push(["tag_create", "clickup_create_space_tag", { space_id: task.spaceId, name: tag }], ["tag_add", "clickup_add_tag_to_task", { task_id: task.id, tag_name: tag }]);
660
- }
661
- const applied = [];
662
- for (const [step, tool, args] of steps) {
663
- try {
664
- await call(tool, args);
665
- }
666
- catch (e) {
667
- return stepFailure(failure(e), applied, step);
668
- }
669
- if (!applied.includes(step))
670
- applied.push(step);
671
- }
672
- return { ok: true, data: { normalized, fieldWritten: timed ? "time_estimate" : null } };
673
- },
674
- };
675
- }
676
- //# sourceMappingURL=transport-clickup.js.map