@orboto/mcp 0.178.0

package/dist/tools/check-similar.test.js

@@ -0,0 +1,101 @@
+/**
+ * ORB-887 - unit tests for `orboto_check_similar`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeCheckSimilarHandler } from './check-similar.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+describe('orboto_check_similar', () => {
+    it('returns a safe-to-create recommendation when no candidates match', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { candidates: [], mode: 'tsvector' } },
+        ]);
+        const res = await makeCheckSimilarHandler(client)({
+            projectKey: 'ACME', title: 'Brand new scope',
+        });
+        expect(calls[1].url).toContain('/projects/p1/tickets/similar?');
+        expect(calls[1].url).toContain('title=Brand+new+scope');
+        const sc = res.structuredContent;
+        expect(sc.recommendation).toMatch(/safe to create/i);
+        expect(sc.similar).toHaveLength(0);
+    });
+    it('flags a HIGH-SIMILARITY MATCH when the top hit ≥ 0.9', async () => {
+        stub([
+            { json: PROJ },
+            {
+                json: {
+                    mode: 'embedding',
+                    candidates: [
+                        { id: 't42', ticketKey: 'ACME-42', title: 'Existing auth work', statusName: 'In Progress', statusColor: '#fc0', statusCategory: 'in_progress', similarity: 0.94, matchMode: 'embedding' },
+                    ],
+                },
+            },
+        ]);
+        const res = await makeCheckSimilarHandler(client)({
+            projectKey: 'ACME', title: 'Authentication overhaul', description: 'rewrite SSO',
+        });
+        const sc = res.structuredContent;
+        expect(sc.recommendation).toMatch(/HIGH-SIMILARITY MATCH FOUND/);
+        expect(sc.recommendation).toContain('ACME-42');
+    });
+    it('returns the medium recommendation when the top hit is < 0.9', async () => {
+        stub([
+            { json: PROJ },
+            {
+                json: {
+                    mode: 'tsvector',
+                    candidates: [
+                        { id: 't9', ticketKey: 'ACME-9', title: 'Loose match', statusName: 'Done', statusColor: '#7d7', statusCategory: 'done', similarity: 0.55, matchMode: 'tsvector' },
+                    ],
+                },
+            },
+        ]);
+        const res = await makeCheckSimilarHandler(client)({
+            projectKey: 'ACME', title: 'Unrelated effort',
+        });
+        const sc = res.structuredContent;
+        expect(sc.recommendation).toMatch(/Possible related tickets/);
+    });
+    it('passes description through to the query string when provided', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { candidates: [], mode: 'tsvector' } },
+        ]);
+        await makeCheckSimilarHandler(client)({
+            projectKey: 'ACME', title: 'foo', description: 'some long body',
+        });
+        expect(calls[1].url).toContain('description=some+long+body');
+    });
+    it('surfaces a 403 from the API as an OrbotoApiError', async () => {
+        stub([
+            { json: PROJ },
+            { ok: false, status: 403, json: { error: 'Forbidden - missing ticket:create' } },
+        ]);
+        await expect(makeCheckSimilarHandler(client)({ projectKey: 'ACME', title: 'x' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/checklist-writes.js

@@ -0,0 +1,202 @@
+/**
+ * ORB-244 Phase C Group 3 - checklist write tools (ORB-234).
+ *
+ * Four tools:
+ * - orboto_check / orboto_uncheck - toggle a single item's `isCompleted`
+ * - orboto_add_check - append a new item to a list (default: first list
+ *                       on the ticket)
+ * - orboto_new_checklist - create a fresh list with optional triggers-done
+ *
+ * Item identifier: agents prefer 1-based indexes ("check item 3 on
+ * ACME-42") because UUIDs are ergonomic disasters in a chat. The
+ * helper resolves either form by reading the ticket's checklists
+ * once. UUID input is honoured directly so callers that already have
+ * the ID can skip the lookup.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveTicketByKey } from './shared.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Resolve an item identifier (1-based index OR UUID) to its UUID.
+ * Index is global across all checklists on the ticket - same model
+ * the wrapper's `check ORB-X 3` uses, so the agent's mental model
+ * is stable across the two surfaces.
+ */
+async function resolveItemId(client, ticketId, identifier) {
+    const checklists = await client.get(`/tickets/${ticketId}/checklists`);
+    if (typeof identifier === 'string' && UUID_RE.test(identifier)) {
+        return { itemId: identifier, checklists };
+    }
+    const idx = typeof identifier === 'number' ? identifier : parseInt(identifier, 10);
+    if (!Number.isFinite(idx) || idx < 1) {
+        throw new Error(`Invalid item identifier "${identifier}" - must be a 1-based index or a UUID.`);
+    }
+    const flat = checklists.flatMap((cl) => cl.items);
+    const target = flat[idx - 1];
+    if (!target) {
+        throw new Error(`Item index ${idx} is out of range - ticket has ${flat.length} items.`);
+    }
+    return { itemId: target.id, checklists };
+}
+// ---------------------------------------------------------------------------
+// orboto_check / orboto_uncheck
+// ---------------------------------------------------------------------------
+function makeToggleHandler(client, completed) {
+    return async ({ ticketKey, item }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const { itemId, checklists } = await resolveItemId(client, ticket.id, item);
+        const before = checklists.flatMap((c) => c.items).find((i) => i.id === itemId);
+        await client.patch(`/checklist-items/${itemId}`, { isCompleted: completed });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${completed ? 'Checked' : 'Unchecked'} on [${ticket.ticketKey}]: ${before?.content ?? '(item)'}`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                itemId,
+                completed,
+                content: before?.content ?? null,
+            },
+        };
+    };
+}
+const toggleInputSchema = z.object({
+    ticketKey: z.string().min(3),
+    item: z.union([
+        z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+        z.string().describe('Item UUID - for callers that already have it'),
+    ]),
+}).shape;
+export const checkToolConfig = {
+    title: 'Check a checklist item',
+    description: 'Mark a checklist item as completed. `item` is either a 1-based index (count across all checklists on the ticket, top to bottom) or the item\'s UUID. Linked-ticket items are checked automatically when the linked ticket transitions to `done` - checking those manually is ignored.',
+    inputSchema: toggleInputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export const uncheckToolConfig = {
+    title: 'Uncheck a checklist item',
+    description: 'Mark a checklist item as not-completed. Same `item` semantics as orboto_check.',
+    inputSchema: toggleInputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export const makeCheckHandler = (client) => makeToggleHandler(client, true);
+export const makeUncheckHandler = (client) => makeToggleHandler(client, false);
+// ---------------------------------------------------------------------------
+// orboto_remove_check (ORB-1095) - agent parity for DELETE
+// /checklist-items/:id. The surfaces could append but not remove.
+// ---------------------------------------------------------------------------
+export const removeCheckToolConfig = {
+    title: 'Remove a checklist item',
+    description: 'Delete a checklist item from a ticket. `item` is either a 1-based index (global across all checklists on the ticket, top to bottom) or the item\'s UUID - same semantics as orboto_check. Destructive: the item is gone, not just unchecked.',
+    inputSchema: toggleInputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeRemoveCheckHandler(client) {
+    return async ({ ticketKey, item }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const { itemId, checklists } = await resolveItemId(client, ticket.id, item);
+        const before = checklists.flatMap((c) => c.items).find((i) => i.id === itemId);
+        await client.delete(`/checklist-items/${itemId}`);
+        return {
+            content: [{ type: 'text', text: `Removed from [${ticket.ticketKey}]: ${before?.content ?? '(item)'}` }],
+            structuredContent: { ticketKey: ticket.ticketKey, itemId, removed: true, content: before?.content ?? null },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_add_check
+// ---------------------------------------------------------------------------
+export const addCheckToolConfig = {
+    title: 'Add a checklist item',
+    description: 'Append an item to a checklist on a ticket. By default appends to the FIRST checklist on the ticket; pass `listTitle` to target a specific one. Pass `linkedTicketKey` to make the item track another ticket\'s status (the new item\'s `effectiveCompleted` mirrors that ticket\'s done-status from then on).',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        content: z.string().min(1).max(2000),
+        listTitle: z.string().optional().describe('Target checklist title. Default: first checklist on the ticket.'),
+        linkedTicketKey: z.string().optional().describe('Make this item track another ticket\'s done-status (e.g. "ACME-99").'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeAddCheckHandler(client) {
+    return async ({ ticketKey, content, listTitle, linkedTicketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const checklists = await client.get(`/tickets/${ticket.id}/checklists`);
+        if (checklists.length === 0) {
+            throw new Error(`[${ticket.ticketKey}] has no checklists yet. Create one with orboto_new_checklist first.`);
+        }
+        const target = listTitle
+            ? checklists.find((c) => c.title === listTitle)
+            : checklists[0];
+        if (!target) {
+            throw new Error(`Checklist "${listTitle}" not found on [${ticket.ticketKey}]. Lists on this ticket: ${checklists.map((c) => `"${c.title}"`).join(', ')}`);
+        }
+        const body = { content };
+        if (linkedTicketKey) {
+            const linked = await resolveTicketByKey(client, linkedTicketKey);
+            body.linkedTicketId = linked.id;
+        }
+        const item = await client.post(`/tickets/${ticket.id}/checklists/${target.id}/items`, body);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Added to "${target.title}" on [${ticket.ticketKey}]: ${content}${linkedTicketKey ? ` ↪ [${linkedTicketKey}]` : ''}`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                listTitle: target.title,
+                itemId: item.id,
+                content: item.content,
+                linkedTicketKey: linkedTicketKey ?? null,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_new_checklist
+// ---------------------------------------------------------------------------
+export const newChecklistToolConfig = {
+    title: 'Create a new checklist on a ticket',
+    description: 'Create a fresh checklist on a ticket. `triggersDone=true` gates the ticket\'s auto-done transition on this list (the ticket can\'t move to done until every item here is checked). Optional `items` seed the list with content in one call - saves a round-trip per item.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        title: z.string().min(1).max(300),
+        triggersDone: z.boolean().optional().describe('Default: false. Set true to gate the ticket\'s done-transition on this list.'),
+        items: z.array(z.string().min(1).max(2000)).max(100).optional().describe('Seed items in one call.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeNewChecklistHandler(client) {
+    return async ({ ticketKey, title, triggersDone, items }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const body = { title };
+        if (triggersDone)
+            body.triggersDone = true;
+        if (items && items.length > 0)
+            body.items = items.map((content) => ({ content }));
+        let list;
+        try {
+            list = await client.post(`/tickets/${ticket.id}/checklists`, body);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 403) {
+                throw new Error(`Forbidden - you need ticket:edit on [${ticket.ticketKey}]'s project to add checklists.`);
+            }
+            throw err;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Created checklist "${title}" on [${ticket.ticketKey}]${triggersDone ? ' (triggers done)' : ''} with ${list.items.length} item(s).`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                checklistId: list.id,
+                title: list.title,
+                triggersDone: list.triggersDone,
+                itemCount: list.items.length,
+            },
+        };
+    };
+}

package/dist/tools/checklist-writes.test.js

@@ -0,0 +1,184 @@
+/**
+ * ORB-244 Phase C Group 3 - checklist write tool tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeCheckHandler, makeUncheckHandler, makeAddCheckHandler, makeNewChecklistHandler, makeRemoveCheckHandler, } from './checklist-writes.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = url.toString();
+        const m = init?.method ?? 'GET';
+        const b = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: u, method: m, body: b });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${m} ${u}`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const TICKET = { id: 't1', projectId: 'p1', ticketKey: 'ACME-1', title: 'Bug' };
+const SAMPLE_LIST = {
+    id: 'cl1', title: 'Before ship', triggersDone: false,
+    progress: { done: 0, total: 2 },
+    items: [
+        { id: 'i1', content: 'Tests', storedCompleted: false, effectiveCompleted: false, linkedTicketId: null, linkedTicketKey: null, sortOrder: 0 },
+        { id: 'i2', content: 'Docs', storedCompleted: false, effectiveCompleted: false, linkedTicketId: null, linkedTicketKey: null, sortOrder: 1 },
+    ],
+};
+describe('orboto_check / orboto_uncheck', () => {
+    it('check resolves a 1-based index → item UUID, then PATCHes isCompleted=true', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] }, // GET checklists for index lookup
+            { json: { id: 'i2', isCompleted: true } }, // PATCH
+        ]);
+        await makeCheckHandler(client)({ ticketKey: 'ACME-1', item: 2 });
+        expect(calls[3].method).toBe('PATCH');
+        expect(calls[3].url).toContain('/checklist-items/i2');
+        expect(calls[3].body).toEqual({ isCompleted: true });
+    });
+    it('check accepts a UUID directly without re-resolving', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: { id: 'i2', isCompleted: true } },
+        ]);
+        await makeCheckHandler(client)({
+            ticketKey: 'ACME-1',
+            item: '00000000-0000-0000-0000-000000000099',
+        });
+        expect(calls[3].url).toContain('/checklist-items/00000000-0000-0000-0000-000000000099');
+    });
+    it('uncheck PATCHes isCompleted=false', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: { id: 'i1', isCompleted: false } },
+        ]);
+        await makeUncheckHandler(client)({ ticketKey: 'ACME-1', item: 1 });
+        expect(calls[3].body).toEqual({ isCompleted: false });
+    });
+    it('rejects an out-of-range index with a clear count', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] }, // 2 items
+        ]);
+        await expect(makeCheckHandler(client)({ ticketKey: 'ACME-1', item: 99 })).rejects.toThrow(/out of range - ticket has 2 items/);
+    });
+});
+describe('orboto_remove_check (ORB-1095)', () => {
+    it('resolves a 1-based index → item UUID, then DELETEs it', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] }, // GET checklists for index lookup
+            { json: {} }, // DELETE
+        ]);
+        const res = await makeRemoveCheckHandler(client)({ ticketKey: 'ACME-1', item: 2 });
+        expect(calls[3].method).toBe('DELETE');
+        expect(calls[3].url).toContain('/checklist-items/i2');
+        expect(res.structuredContent).toMatchObject({ itemId: 'i2', removed: true, content: 'Docs' });
+    });
+});
+describe('orboto_add_check', () => {
+    it('appends to the FIRST list by default', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: { id: 'i3', content: 'New item' } },
+        ]);
+        await makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'New item' });
+        expect(calls[3].method).toBe('POST');
+        expect(calls[3].url).toContain('/tickets/t1/checklists/cl1/items');
+        expect(calls[3].body).toEqual({ content: 'New item' });
+    });
+    it('targets a named list when listTitle is supplied', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [
+                    SAMPLE_LIST,
+                    { id: 'cl2', title: 'After ship', triggersDone: false, progress: { done: 0, total: 0 }, items: [] },
+                ] },
+            { json: { id: 'i9', content: 'Notify users' } },
+        ]);
+        await makeAddCheckHandler(client)({
+            ticketKey: 'ACME-1', content: 'Notify users', listTitle: 'After ship',
+        });
+        expect(calls[3].url).toContain('/checklists/cl2/items');
+    });
+    it('resolves linkedTicketKey → linkedTicketId for cross-ticket items', async () => {
+        const calls = stub([
+            { json: PROJ }, // resolveTicketByKey: project (parent ACME-1)
+            { json: TICKET }, // resolveTicketByKey: ticket (parent)
+            { json: [SAMPLE_LIST] }, // GET checklists
+            { json: PROJ }, // resolveTicketByKey: project (linked ACME-99)
+            { json: { id: 't99', projectId: 'p1', ticketKey: 'ACME-99', title: 'Race fix' } }, // resolveTicketByKey: ticket (linked)
+            { json: { id: 'i9', content: 'Sub-task', linkedTicketId: 't99' } }, // POST item
+        ]);
+        await makeAddCheckHandler(client)({
+            ticketKey: 'ACME-1', content: 'Sub-task', linkedTicketKey: 'ACME-99',
+        });
+        expect(calls[5].body).toEqual({ content: 'Sub-task', linkedTicketId: 't99' });
+    });
+    it('throws a clear error when the ticket has no checklists yet', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [] },
+        ]);
+        await expect(makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'x' })).rejects.toThrow(/no checklists yet.*orboto_new_checklist/);
+    });
+    it('lists existing list titles when the requested one does not match', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] }, // title is "Before ship"
+        ]);
+        await expect(makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'x', listTitle: 'Wrong' })).rejects.toThrow(/"Before ship"/);
+    });
+});
+describe('orboto_new_checklist', () => {
+    it('POSTs title + optional triggersDone + seeded items', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'cl3', title: 'New', triggersDone: true, progress: { done: 0, total: 2 }, items: [{ id: 'i1' }, { id: 'i2' }] } },
+        ]);
+        await makeNewChecklistHandler(client)({
+            ticketKey: 'ACME-1', title: 'New', triggersDone: true, items: ['a', 'b'],
+        });
+        expect(calls[2].method).toBe('POST');
+        expect(calls[2].url).toContain('/tickets/t1/checklists');
+        expect(calls[2].body).toEqual({
+            title: 'New',
+            triggersDone: true,
+            items: [{ content: 'a' }, { content: 'b' }],
+        });
+    });
+    it('rewrites a 403 from the API into a permission-clarifying error', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { ok: false, status: 403, json: { error: 'Forbidden' } },
+        ]);
+        await expect(makeNewChecklistHandler(client)({ ticketKey: 'ACME-1', title: 'x' })).rejects.toThrow(/ticket:edit/);
+    });
+});